feat(rules): add breaking-change-exclamation-mark

Implements and closes #4547.

Author: adamchristiansen

@commitlint/rules/src/breaking-change-exclamation-mark.test.ts

@@ -0,0 +1,85 @@
+import { test, expect } from "vitest";
+import parse from "@commitlint/parse";
+import { breakingChangeExclamationMark } from "./breaking-change-exclamation-mark.js";
+
+const noHeader = "commit message";
+const plainHeader = "type: subject";
+const breakingHeader = "type!: subject";
+const noFooter = "";
+const plainFooter = "Some-Other-Trailer: content";
+const breakingFooter = "BREAKING CHANGE: reason";
+
+// These are equivalence partitions.
+const messages = {
+	noHeaderNoFooter: `${noHeader}\n\n${noFooter}`,
+	noHeaderPlainFooter: `${noHeader}\n\n${plainFooter}`,
+	noHeaderBreakingFooter: `${noHeader}\n\n${breakingFooter}`,
+	plainHeaderPlainFooter: `${plainHeader}\n\n${plainFooter}`,
+	plainHeaderBreakingFooter: `${plainHeader}\n\n${breakingFooter}`,
+	breakingHeaderPlainFooter: `${breakingHeader}\n\n${plainFooter}`,
+	breakingHeaderBreakingFooter: `${breakingHeader}\n\n${breakingFooter}`,
+};
+
+const parsed = {
+	noHeaderNoFooter: parse(messages.noHeaderNoFooter),
+	noHeaderPlainFooter: parse(messages.noHeaderPlainFooter),
+	noHeaderBreakingFooter: parse(messages.noHeaderBreakingFooter),
+	plainHeaderPlainFooter: parse(messages.plainHeaderPlainFooter),
+	plainHeaderBreakingFooter: parse(messages.plainHeaderBreakingFooter),
+	breakingHeaderPlainFooter: parse(messages.breakingHeaderPlainFooter),
+	breakingHeaderBreakingFooter: parse(messages.breakingHeaderBreakingFooter),
+};
+
+test("with noHeaderNoFooter should succeed", async () => {
+	const [actual] = breakingChangeExclamationMark(await parsed.noHeaderNoFooter);
+	const expected = true;
+	expect(actual).toEqual(expected);
+});
+
+test("with noHeaderPlainFooter should succeed", async () => {
+	const [actual] = breakingChangeExclamationMark(
+		await parsed.noHeaderPlainFooter,
+	);
+	const expected = true;
+	expect(actual).toEqual(expected);
+});
+
+test("with noHeaderBreakingFooter should fail", async () => {
+	const [actual] = breakingChangeExclamationMark(
+		await parsed.noHeaderBreakingFooter,
+	);
+	const expected = false;
+	expect(actual).toEqual(expected);
+});
+
+test("with plainHeaderPlainFooter should succeed", async () => {
+	const [actual] = breakingChangeExclamationMark(
+		await parsed.plainHeaderPlainFooter,
+	);
+	const expected = true;
+	expect(actual).toEqual(expected);
+});
+
+test("with plainHeaderBreakingFooter should fail", async () => {
+	const [actual] = breakingChangeExclamationMark(
+		await parsed.plainHeaderBreakingFooter,
+	);
+	const expected = false;
+	expect(actual).toEqual(expected);
+});
+
+test("with breakingHeaderPlainFooter should fail", async () => {
+	const [actual] = breakingChangeExclamationMark(
+		await parsed.breakingHeaderPlainFooter,
+	);
+	const expected = false;
+	expect(actual).toEqual(expected);
+});
+
+test("with breakingHeaderBreakingFooter should succeed", async () => {
+	const [actual] = breakingChangeExclamationMark(
+		await parsed.breakingHeaderBreakingFooter,
+	);
+	const expected = true;
+	expect(actual).toEqual(expected);
+});

@commitlint/rules/src/breaking-change-exclamation-mark.ts

@@ -0,0 +1,35 @@
+import message from "@commitlint/message";
+import { SyncRule } from "@commitlint/types";
+
+export const breakingChangeExclamationMark: SyncRule = (
+	parsed,
+	when = "always",
+) => {
+	const header = parsed.header;
+	const footer = parsed.footer;
+
+	// It is the correct behavior to return true only when both the header and footer are empty,
+	// but still run the usual checks if one or neither are empty.
+	// The reasoning is that if one is empty and the other contains a breaking change marker,
+	// then the check fails as it is not possible for the empty one to indicate a breaking change.
+	if (!header && !footer) {
+		return [true];
+	}
+
+	const hasExclamationMark = !!header && /!:/.test(header);
+	const hasBreakingChange = !!footer && /BREAKING[ -]CHANGE:/.test(footer);
+
+	const negated = when === "never";
+	const check = hasExclamationMark === hasBreakingChange;
+
+	return [
+		negated ? !check : check,
+		message([
+			"breaking changes",
+			negated ? "must not" : "must",
+			"have both an exclamation mark in the header",
+			"and BREAKING CHANGE in the footer",
+			"to identify a breaking change",
+		]),
+	];
+};

@commitlint/rules/src/index.ts

@@ -1,3 +1,4 @@
+import { breakingChangeExclamationMark } from "./breaking-change-exclamation-mark.js";
 import { bodyCase } from "./body-case.js";
 import { bodyEmpty } from "./body-empty.js";
 import { bodyFullStop } from "./body-full-stop.js";
@@ -36,6 +37,7 @@ import { typeMaxLength } from "./type-max-length.js";
 import { typeMinLength } from "./type-min-length.js";
 
 export default {
+	"breaking-change-exclamation-mark": breakingChangeExclamationMark,
 	"body-case": bodyCase,
 	"body-empty": bodyEmpty,
 	"body-full-stop": bodyFullStop,

docs/reference/rules.md

@@ -1,5 +1,19 @@
 # Rules
 
+## breaking-change-exclamation-mark
+
+- **condition**: Either both or neither `header` has an exclamation mark before the `:` marker
+  and `footer` matches the regular expression `BREAKING[ -]CHANGE:`
+- **rule**: `always`
+
+> [!NOTE]
+>
+> This rule enforces that breaking changes are marked by both a `!` in the header
+> and `BREAKING CHANGE` in the footer. The behavior is that of an XNOR operation:
+>
+> - It passes when either both are present or both are not.
+> - It fails when one is present and the other is not.
+
 ## body-full-stop
 
 - **condition**: `body` ends with `value`