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;