feat(cli)!: show position of error in commit input #633

@commitlint/cli/src/cli.test.ts

@@ -193,6 +193,24 @@ test("should fail for input from stdin with rule from rc", async () => {
 	expect(result.exitCode).toBe(ExitCode.CommitlintErrorDefault);
 });
 
+test("should print position indicator caret by default on failure", async () => {
+	const cwd = await gitBootstrap("fixtures/simple");
+	const result = cli(["--color=false"], { cwd })("foo: bar");
+	const output = await result;
+	expect(output.stdout).toContain("^");
+	expect(result.exitCode).toBe(ExitCode.CommitlintErrorDefault);
+});
+
+test("should suppress position indicator when --no-show-position is set", async () => {
+	const cwd = await gitBootstrap("fixtures/simple");
+	const result = cli(["--color=false", "--no-show-position"], { cwd })(
+		"foo: bar",
+	);
+	const output = await result;
+	expect(output.stdout).not.toContain("^");
+	expect(result.exitCode).toBe(ExitCode.CommitlintErrorDefault);
+});
+
 test("should work with --config option", async () => {
 	const file = "config/commitlint.config.js";
 	const cwd = await gitBootstrap("fixtures/specify-config-file");
@@ -495,7 +513,14 @@ test("should print full commit message when input from stdin fails", async () =>
 	// output text in plain text so we can compare it
 	const result = cli(["--color=false"], { cwd })(input);
 	const output = await result;
-	expect(output.stdout.trim()).toContain(input);
+	// Each input line must appear in stdout *in the original order* —
+	// independent toContain checks would let scrambled output pass.
+	let cursor = 0;
+	for (const line of input.split("\n").filter((l) => l.length > 0)) {
+		const found = output.stdout.indexOf(line, cursor);
+		expect(found).toBeGreaterThanOrEqual(cursor);
+		cursor = found + line.length;
+	}
 	expect(result.exitCode).toBe(ExitCode.CommitlintErrorDefault);
 });
 
@@ -644,6 +669,7 @@ test("should print help", async () => {
 		  -q, --quiet          toggle console output  [boolean] [default: false]
 		  -t, --to             upper end of the commit range to lint; applies if edit=false  [string]
 		  -V, --verbose        enable verbose output for reports without problems  [boolean]
+		      --show-position  show position of error in output  [boolean] [default: true]
 		  -s, --strict         enable strict mode; result code 2 for warnings, 3 for errors  [boolean]
 		      --options        path to a JSON file or Common.js module containing CLI options
 		  -v, --version        display version information  [boolean]

@commitlint/cli/src/cli.ts

@@ -135,6 +135,11 @@ const cli = yargs(process.argv.slice(2))
 			type: "boolean",
 			description: "enable verbose output for reports without problems",
 		},
+		"show-position": {
+			type: "boolean",
+			default: true,
+			description: "show position of error in output",
+		},
 		strict: {
 			alias: "s",
 			type: "boolean",
@@ -398,6 +403,7 @@ async function main(args: MainArgs): Promise<void> {
 		color: flags.color,
 		verbose: flags.verbose,
 		helpUrl,
+		showPosition: flags["show-position"],
 	});
 
 	if (!flags.quiet && output !== "") {

@commitlint/cli/src/types.ts

@@ -17,6 +17,7 @@ export interface CliFlags {
 	to?: string;
 	version?: boolean;
 	verbose?: boolean;
+	"show-position"?: boolean;
 	/** @type {'' | 'text' | 'json'} */
 	"print-config"?: string;
 	strict?: boolean;

@commitlint/config-conventional/src/index.test.ts

@@ -132,21 +132,44 @@ test("type-enum", async () => {
 	const result = await commitLint(messages.invalidTypeEnum);
 
 	expect(result.valid).toBe(false);
-	expect(result.errors).toEqual([errors.typeEnum]);
+	expect(result.errors).toEqual([
+		{
+			...errors.typeEnum,
+			start: { line: 1, column: 1, offset: 0 },
+			end: { line: 1, column: 4, offset: 3 },
+		},
+	]);
 });
 
 test("type-case", async () => {
 	const result = await commitLint(messages.invalidTypeCase);
 
 	expect(result.valid).toBe(false);
-	expect(result.errors).toEqual([errors.typeCase, errors.typeEnum]);
+	expect(result.errors).toEqual([
+		{
+			...errors.typeCase,
+			start: { line: 1, column: 1, offset: 0 },
+			end: { line: 1, column: 4, offset: 3 },
+		},
+		{
+			...errors.typeEnum,
+			start: { line: 1, column: 1, offset: 0 },
+			end: { line: 1, column: 4, offset: 3 },
+		},
+	]);
 });
 
 test("type-empty", async () => {
 	const result = await commitLint(messages.invalidTypeEmpty);
 
 	expect(result.valid).toBe(false);
-	expect(result.errors).toEqual([errors.typeEmpty]);
+	expect(result.errors).toEqual([
+		{
+			...errors.typeEmpty,
+			start: { line: 1, column: 1, offset: 0 },
+			end: { line: 1, column: 1, offset: 0 },
+		},
+	]);
 });
 
 test("subject-case", async () => {
@@ -156,59 +179,138 @@ test("subject-case", async () => {
 		),
 	);
 
-	invalidInputs.forEach((result) => {
+	const headerPrefix = "fix(scope): ";
+	invalidInputs.forEach((result, i) => {
+		const input = messages.invalidSubjectCases[i];
+		const subject = input.slice(headerPrefix.length);
+		const offset = headerPrefix.length;
 		expect(result.valid).toBe(false);
-		expect(result.errors).toEqual([errors.subjectCase]);
+		expect(result.errors).toEqual([
+			{
+				...errors.subjectCase,
+				start: { line: 1, column: offset + 1, offset },
+				end: {
+					line: 1,
+					column: offset + subject.length + 1,
+					offset: offset + subject.length,
+				},
+			},
+		]);
 	});
 });
 
 test("subject-empty", async () => {
 	const result = await commitLint(messages.invalidSubjectEmpty);
 
 	expect(result.valid).toBe(false);
-	expect(result.errors).toEqual([errors.subjectEmpty, errors.typeEmpty]);
+	// "fix:" — header length 4; type "fix" at offset 0 length 3.
+	expect(result.errors).toEqual([
+		{
+			...errors.subjectEmpty,
+			start: { line: 1, column: 5, offset: 4 },
+			end: { line: 1, column: 5, offset: 4 },
+		},
+		{
+			...errors.typeEmpty,
+			start: { line: 1, column: 1, offset: 0 },
+			end: { line: 1, column: 1, offset: 0 },
+		},
+	]);
 });
 
 test("subject-full-stop", async () => {
 	const result = await commitLint(messages.invalidSubjectFullStop);
 
 	expect(result.valid).toBe(false);
-	expect(result.errors).toEqual([errors.subjectFullStop]);
+	// "fix: some message." — subject "some message." at offset 5, length 13
+	// (parser keeps the trailing period in parsed.subject).
+	expect(result.errors).toEqual([
+		{
+			...errors.subjectFullStop,
+			start: { line: 1, column: 6, offset: 5 },
+			end: { line: 1, column: 19, offset: 18 },
+		},
+	]);
 });
 
 test("header-max-length", async () => {
 	const result = await commitLint(messages.invalidHeaderMaxLength);
+	const header = messages.invalidHeaderMaxLength;
 
 	expect(result.valid).toBe(false);
-	expect(result.errors).toEqual([errors.headerMaxLength]);
+	expect(result.errors).toEqual([
+		{
+			...errors.headerMaxLength,
+			start: { line: 1, column: 1, offset: 0 },
+			end: { line: 1, column: header.length + 1, offset: header.length },
+		},
+	]);
 });
 
 test("footer-leading-blank", async () => {
 	const result = await commitLint(messages.warningFooterLeadingBlank);
+	const message = messages.warningFooterLeadingBlank;
+	const footerOffset = message.indexOf("BREAKING CHANGE") - 1;
 
 	expect(result.valid).toBe(true);
-	expect(result.warnings).toEqual([warnings.footerLeadingBlank]);
+	expect(result.warnings).toEqual([
+		{
+			...warnings.footerLeadingBlank,
+			start: {
+				line: 3,
+				column: message.split("\n")[2].length + 1,
+				offset: footerOffset,
+			},
+			end: {
+				line: 3,
+				column: message.split("\n")[2].length + 1,
+				offset: footerOffset,
+			},
+		},
+	]);
 });
 
 test("footer-max-line-length", async () => {
 	const result = await commitLint(messages.invalidFooterMaxLineLength);
 
 	expect(result.valid).toBe(false);
-	expect(result.errors).toEqual([errors.footerMaxLineLength]);
+	expect(result.errors).toHaveLength(1);
+	expect(result.errors[0]).toMatchObject(errors.footerMaxLineLength);
+	expect(result.errors[0].start).toBeDefined();
+	expect(result.errors[0].end).toBeDefined();
 });
 
 test("body-leading-blank", async () => {
 	const result = await commitLint(messages.warningBodyLeadingBlank);
+	const message = messages.warningBodyLeadingBlank;
+	const headerLength = message.split("\n")[0].length;
 
 	expect(result.valid).toBe(true);
-	expect(result.warnings).toEqual([warnings.bodyLeadingBlank]);
+	expect(result.warnings).toEqual([
+		{
+			...warnings.bodyLeadingBlank,
+			start: {
+				line: 1,
+				column: headerLength + 1,
+				offset: headerLength,
+			},
+			end: {
+				line: 1,
+				column: headerLength + 1,
+				offset: headerLength,
+			},
+		},
+	]);
 });
 
 test("body-max-line-length", async () => {
 	const result = await commitLint(messages.invalidBodyMaxLineLength);
 
 	expect(result.valid).toBe(false);
-	expect(result.errors).toEqual([errors.bodyMaxLineLength]);
+	expect(result.errors).toHaveLength(1);
+	expect(result.errors[0]).toMatchObject(errors.bodyMaxLineLength);
+	expect(result.errors[0].start).toBeDefined();
+	expect(result.errors[0].end).toBeDefined();
 });
 
 test("valid messages", async () => {