feat(lint): allow for custom commit parser function (#4829)

* feat(test): addes a test confirming functionality doesn't exist

This adds tests to confirm that functionality for #4816
doesn't exist and doesn't work

* 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,85 @@ test("passes for async rule", async () => {
 
 	expect(report.valid).toBe(true);
 });
+
+test("custom parser output is used by rules", async () => {
+	// The default parser extracts no type from this message; the custom parser supplies one,
+	// so type-empty (never) only passes because the custom parser ran.
+	const customParser: Parser = (message) => ({
+		type: "feat",
+		scope: null,
+		subject: "my-feature",
+		body: null,
+		footer: null,
+		header: message,
+	});
+
+	const report = await lint(
+		"a message with no conventional type",
+		{
+			"type-empty": [RuleConfigSeverity.Error, "never"],
+		},
+		{ parser: customParser },
+	);
+
+	expect(report.valid).toBe(true);
+	expect(report.errors.length).toBe(0);
+});
+
+test("custom parser overrides the default parse result", async () => {
+	// "feat: add thing" is a valid feat to the default parser; the custom parser rewrites the
+	// type to "wip", so the commit only fails type-enum because the custom parser ran.
+	const customParser: Parser = (message) => ({
+		type: "wip",
+		scope: null,
+		subject: "add thing",
+		body: null,
+		footer: null,
+		header: message,
+	});
+
+	const report = await lint(
+		"feat: add thing",
+		{
+			"type-enum": [RuleConfigSeverity.Error, "always", ["feat"]],
+		},
+		{ parser: customParser },
+	);
+
+	expect(report.valid).toBe(false);
+	expect(report.errors.length).toBe(1);
+});
+
+test("custom parser receives parser options as second argument", async () => {
+	let receivedOpts: Record<string, unknown> | undefined;
+
+	const customParser: Parser = (_message, opts) => {
+		receivedOpts =
+			typeof opts === "object" && opts !== null ? (opts as Record<string, unknown>) : {};
+		return {
+			header: "custom-parsed-header",
+			type: "chore",
+			subject: null,
+			body: null,
+			footer: null,
+			merge: null,
+			revert: null,
+			notes: [],
+			mentions: [],
+			references: [],
+		} as unknown as ReturnType<Parser>;
+	};
+
+	const customOpts = { headerPattern: /^custom-parsed-header/ };
+
+	await lint(
+		"any message",
+		{
+			"type-enum": [RuleConfigSeverity.Error, "always", ["chore"]],
+		},
+		{ parser: customParser, parserOpts: customOpts },
+	);
+
+	expect(receivedOpts).toBeDefined();
+	expect((receivedOpts as Record<string, unknown>).headerPattern).toBeDefined();
+});

@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 type { 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;
+	/** A custom parser function, used instead of the default conventional-commits-parser */
+	parser?: Parser;
 
 	plugins?: PluginRecords;
 	helpUrl?: string;