feat(lint): allow for custom commit parser function

This change makes it possible to pass a custom function to the top level
lint function, which is passed through to the parse function and
consequently passed through to the parser exposed by
convential-commits-parser. In linting it is important to parse content
to be linted with a high level of fidelity so linting can be applied
accurately. The default parser the is used, conventional-commits-parser
makes many assumptions about the format of the commit to perform its
parsing which leads to parsing errors and inaccuracies which in turn
lead to many false positives in linting, and incorrect or invalid errors
in additional confusing error messages.

This change will allow end users utilize a more accurate parser for
their linting purposes in the short term while issues with the default
parser are reconciled

Resolves: #4816

Author: esatterwhite

@commitlint/lint/src/lint.test.ts

@@ -1,4 +1,5 @@
 import { test, expect } from "vitest";
+import type { Parser } from "@commitlint/types";
 import { RuleConfigSeverity } from "@commitlint/types";
 
 import lint from "./lint.js";
@@ -308,3 +309,79 @@ test("passes for async rule", async () => {
 
 	expect(report.valid).toBe(true);
 });
+
+test("uses custom parser when provided", async () => {
+	const customParser: Parser = (message) => ({
+		type: "feat",
+		scope: null,
+		subject: "my-feature",
+		body: null,
+		footer: null,
+		header: message.trim(),
+	});
+
+	const report = await lint(
+		"any message",
+		{
+			"type-enum": [RuleConfigSeverity.Error, "always", ["feat"]],
+		},
+		{ parser: customParser },
+	);
+
+	expect(report.valid).toBe(true);
+	expect(report.errors.length).toBe(0);
+});
+
+test("custom parser output is used by rules", async () => {
+	const customParser: Parser = (_message) => ({
+		type: null,
+		scope: "auth",
+		subject: "fix login",
+		body: null,
+		footer: null,
+		header: "scope(subject): description",
+	});
+
+	const report = await lint(
+		"any message",
+		{
+			"type-empty": [RuleConfigSeverity.Error, "never"],
+		},
+		{ parser: customParser },
+	);
+
+	expect(report.valid).toBe(false);
+	expect(report.errors.length).toBe(1);
+});
+
+test("custom parser works alongside parserOpts", async () => {
+	const customParser: Parser = (_message) =>
+		({
+			type: "chore",
+			subject: "dep bump",
+			body: null,
+			footer: "Refs #42",
+			header: "chore: dep bump",
+			references: [
+				{
+					raw: "Refs #42",
+					action: "Refs",
+					owner: null,
+					repository: null,
+					issue: "42",
+					prefix: "#",
+				},
+			],
+		}) as unknown as ReturnType<Parser>;
+
+	const report = await lint(
+		"any message",
+		{
+			"type-enum": [RuleConfigSeverity.Error, "always", ["chore"]],
+			"references-empty": [RuleConfigSeverity.Error, "never"],
+		},
+		{ parser: customParser },
+	);
+
+	expect(report.valid).toBe(true);
+});

@commitlint/lint/src/lint.ts

@@ -37,7 +37,7 @@ export default async function lint(
 	const parsed =
 		message === ""
 			? { header: null, body: null, footer: null }
-			: await parse(message, undefined, opts.parserOpts);
+			: await parse(message, opts.parser, opts.parserOpts);
 
 	if (parsed.header === null && parsed.body === null && parsed.footer === null) {
 		// Commit is empty, skip

@commitlint/types/src/lint.ts

@@ -1,6 +1,7 @@
 import type { ParserOptions as Options } from "conventional-commits-parser";
 import { IsIgnoredOptions } from "./is-ignored.js";
 import { PluginRecords } from "./load.js";
+import { Parser } from "./parse.js";
 import { RuleConfigSeverity, RuleConfigTuple } from "./rules.js";
 
 export type LintRuleConfig = Record<
@@ -15,6 +16,8 @@ export interface LintOptions {
 	ignores?: IsIgnoredOptions["ignores"];
 	/** The parser configuration to use when linting the commit */
 	parserOpts?: Options;
+	/** An optional custom parser function for parsing commit messages */
+	parser?: Parser;
 
 	plugins?: PluginRecords;
 	helpUrl?: string;

docs/reference/configuration.md

@@ -253,6 +253,77 @@ export default {
 
 :::
 
+### Custom parser function
+
+You can provide a custom commit parsing implementation by supplying a `parser` function in your configuration. This is useful if you have specific parsing requirements that cannot be met by existing presets or options.
+
+The custom function must return an object matching the [`Commit` type from `conventional-commits-parser`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-commits-parser#commit), which includes all fields from `CommitBase`: `header`, `type`, `scope`, `subject`, `body`, `footer`, `merge`, `revert`, `notes`, `mentions`, and `references`. The `raw` property must be omitted (it is set by commitlint internally).
+
+Omitting any of the array fields (`notes`, `mentions`, `references`) will cause lint rules like `references-empty` to crash, since they expect arrays rather than `undefined`:
+
+::: code-group
+
+```js [commitlint.config.js]
+export default {
+  parserPreset: {
+    parser: (message, options) => {
+      // Instantiate your custom parsing implementation
+      const parser = new MyParser(options);
+      const parsed = parser.parse(message);
+
+      // Return all required CommitBase fields from the parsed result
+      return {
+        header: parsed.header ?? message.trim(),
+        type: parsed.type ?? null,
+        scope: parsed.scope ?? null,
+        subject: parsed.subject ?? null,
+        body: parsed.body ?? null,
+        footer: parsed.footer ?? null,
+        merge: null,
+        revert: null,
+        notes: parsed.notes ?? [],
+        mentions: parsed.mentions ?? [],
+        references: parsed.references ?? [],
+      };
+    },
+  },
+};
+```
+
+```ts [commitlint.config.ts]
+import type { Parser as CommitParser } from "@commitlint/types";
+
+const myParser: CommitParser = (message, options) => {
+  // Instantiate your custom parsing implementation
+  const parser = new MyParser(options);
+  const parsed = parser.parse(message);
+
+  return {
+    header: parsed.header ?? message.trim(),
+    type: parsed.type ?? null,
+    scope: parsed.scope ?? null,
+    subject: parsed.subject ?? null,
+    body: parsed.body ?? null,
+    footer: parsed.footer ?? null,
+    merge: null,
+    revert: null,
+    notes: parsed.notes ?? [],
+    mentions: parsed.mentions ?? [],
+    references: parsed.references ?? [],
+  };
+};
+
+export default {
+  parserPreset: {
+    parser: myParser,
+  },
+};
+```
+
+:::
+
+### Common `parserOpts`
+
 ### Common `parserOpts`
 
 The parser is powered by [`conventional-commits-parser`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-commits-parser). Common options include: