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

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

@@ -495,7 +495,9 @@ 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);
+	for (const line of input.split("\n").filter((l) => l.length > 0)) {
+		expect(output.stdout).toContain(line);
+	}
 	expect(result.exitCode).toBe(ExitCode.CommitlintErrorDefault);
 });
 
@@ -644,6 +646,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,21 @@ test("type-enum", async () => {
 	const result = await commitLint(messages.invalidTypeEnum);
 
 	expect(result.valid).toBe(false);
-	expect(result.errors).toEqual([errors.typeEnum]);
+	expect(result.errors).toMatchObject([errors.typeEnum]);
 });
 
 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).toMatchObject([errors.typeCase, errors.typeEnum]);
 });
 
 test("type-empty", async () => {
 	const result = await commitLint(messages.invalidTypeEmpty);
 
 	expect(result.valid).toBe(false);
-	expect(result.errors).toEqual([errors.typeEmpty]);
+	expect(result.errors).toMatchObject([errors.typeEmpty]);
 });
 
 test("subject-case", async () => {
@@ -158,57 +158,57 @@ test("subject-case", async () => {
 
 	invalidInputs.forEach((result) => {
 		expect(result.valid).toBe(false);
-		expect(result.errors).toEqual([errors.subjectCase]);
+		expect(result.errors).toMatchObject([errors.subjectCase]);
 	});
 });
 
 test("subject-empty", async () => {
 	const result = await commitLint(messages.invalidSubjectEmpty);
 
 	expect(result.valid).toBe(false);
-	expect(result.errors).toEqual([errors.subjectEmpty, errors.typeEmpty]);
+	expect(result.errors).toMatchObject([errors.subjectEmpty, errors.typeEmpty]);
 });
 
 test("subject-full-stop", async () => {
 	const result = await commitLint(messages.invalidSubjectFullStop);
 
 	expect(result.valid).toBe(false);
-	expect(result.errors).toEqual([errors.subjectFullStop]);
+	expect(result.errors).toMatchObject([errors.subjectFullStop]);
 });
 
 test("header-max-length", async () => {
 	const result = await commitLint(messages.invalidHeaderMaxLength);
 
 	expect(result.valid).toBe(false);
-	expect(result.errors).toEqual([errors.headerMaxLength]);
+	expect(result.errors).toMatchObject([errors.headerMaxLength]);
 });
 
 test("footer-leading-blank", async () => {
 	const result = await commitLint(messages.warningFooterLeadingBlank);
 
 	expect(result.valid).toBe(true);
-	expect(result.warnings).toEqual([warnings.footerLeadingBlank]);
+	expect(result.warnings).toMatchObject([warnings.footerLeadingBlank]);
 });
 
 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).toMatchObject([errors.footerMaxLineLength]);
 });
 
 test("body-leading-blank", async () => {
 	const result = await commitLint(messages.warningBodyLeadingBlank);
 
 	expect(result.valid).toBe(true);
-	expect(result.warnings).toEqual([warnings.bodyLeadingBlank]);
+	expect(result.warnings).toMatchObject([warnings.bodyLeadingBlank]);
 });
 
 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).toMatchObject([errors.bodyMaxLineLength]);
 });
 
 test("valid messages", async () => {

@commitlint/format/src/format.test.ts

@@ -54,7 +54,7 @@ test("returns empty summary with full commit message if verbose", () => {
 	);
 
 	expect(actual).toStrictEqual(
-		"⧗   input: feat(cli): this is a valid header\n\nThis is a valid body\n\nSigned-off-by: tester\n✔   found 0 problems, 0 warnings",
+		"⧗   input: feat(cli): this is a valid header\n           \n           This is a valid body\n           \n           Signed-off-by: tester\n✔   found 0 problems, 0 warnings",
 	);
 });
 
@@ -303,3 +303,222 @@ test("format result should not contain `Get help` prefix if helpUrl is not provi
 		expect.arrayContaining([expect.stringContaining("Get help:")]),
 	);
 });
+
+test("shows position indicator when showPosition is true and error has position", () => {
+	const actual = format(
+		{
+			results: [
+				{
+					errors: [
+						{
+							level: 2,
+							name: "type-enum",
+							message: "type must be one of [feat, fix]",
+							start: { line: 1, column: 1, offset: 0 },
+							end: { line: 1, column: 4, offset: 3 },
+						},
+					],
+					input: "foo: some message",
+				},
+			],
+		},
+		{
+			showPosition: true,
+			color: false,
+		},
+	);
+
+	expect(actual).toContain("^");
+});
+
+test("does not show position indicator when showPosition is false", () => {
+	const actual = format(
+		{
+			results: [
+				{
+					errors: [
+						{
+							level: 2,
+							name: "type-enum",
+							message: "type must be one of [feat, fix]",
+							start: { line: 1, column: 1, offset: 0 },
+							end: { line: 1, column: 4, offset: 3 },
+						},
+					],
+					input: "foo: some message",
+				},
+			],
+		},
+		{
+			showPosition: false,
+			color: false,
+		},
+	);
+
+	expect(actual).not.toContain("^");
+});
+
+test("shows position indicator when showPosition is not provided (default)", () => {
+	const actual = format(
+		{
+			results: [
+				{
+					errors: [
+						{
+							level: 2,
+							name: "type-enum",
+							message: "type must be one of [feat, fix]",
+							start: { line: 1, column: 1, offset: 0 },
+							end: { line: 1, column: 4, offset: 3 },
+						},
+					],
+					input: "foo: some message",
+				},
+			],
+		},
+		{
+			color: false,
+		},
+	);
+
+	expect(actual).toContain("^");
+});
+
+test("does not show position indicator when error has no position", () => {
+	const actual = format(
+		{
+			results: [
+				{
+					errors: [
+						{
+							level: 2,
+							name: "type-enum",
+							message: "type must be one of [feat, fix]",
+						},
+					],
+					input: "foo: some message",
+				},
+			],
+		},
+		{
+			showPosition: true,
+			color: false,
+		},
+	);
+
+	expect(actual).not.toContain("^");
+});
+
+test("shows correct position for subject error", () => {
+	const actual = format(
+		{
+			results: [
+				{
+					errors: [
+						{
+							level: 2,
+							name: "subject-max-length",
+							message: "subject must not be longer than 72 characters",
+							start: { line: 1, column: 10, offset: 9 },
+							end: { line: 1, column: 50, offset: 49 },
+						},
+					],
+					input:
+						"feat: this is a subject that is way too long for the commit message format",
+				},
+			],
+		},
+		{
+			showPosition: true,
+			color: false,
+		},
+	);
+
+	expect(actual).toContain("^");
+});
+
+test("position indicator alignment is identical with or without color", () => {
+	const result = {
+		errors: [
+			{
+				level: 2 as const,
+				name: "subject-max-length",
+				message: "subject must not be longer than 72 characters",
+				start: { line: 1, column: 10, offset: 9 },
+				end: { line: 1, column: 50, offset: 49 },
+			},
+		],
+		input: "feat: this subject is going to be a bit too long",
+	};
+
+	const colored = format({ results: [result] }, { showPosition: true });
+	const plain = format(
+		{ results: [result] },
+		{ showPosition: true, color: false },
+	);
+
+	const indicatorOf = (output: string) =>
+		output.split("\n").find((line) => line.trimStart().startsWith("^"));
+
+	expect(indicatorOf(colored)).toBe(indicatorOf(plain));
+});
+
+test("renders position indicator under the failing line for multi-line input", () => {
+	const actual = format(
+		{
+			results: [
+				{
+					errors: [
+						{
+							level: 2,
+							name: "body-max-line-length",
+							message: "body must not have lines longer than 80 characters",
+							start: { line: 3, column: 1, offset: 14 },
+							end: { line: 3, column: 100, offset: 113 },
+						},
+					],
+					input: "feat: header\n\nthis body line is far too long to fit",
+				},
+			],
+		},
+		{
+			showPosition: true,
+			color: false,
+		},
+	);
+
+	const lines = actual.split("\n");
+	const bodyLineIndex = lines.findIndex((l) =>
+		l.includes("this body line is far too long"),
+	);
+	expect(bodyLineIndex).toBeGreaterThan(-1);
+	expect(lines[bodyLineIndex + 1]).toContain("^");
+});
+
+test("shows position indicator with single caret for longer errors", () => {
+	const actual = format(
+		{
+			results: [
+				{
+					errors: [
+						{
+							level: 2,
+							name: "header-max-length",
+							message: "header must not be longer than 100 characters",
+							start: { line: 1, column: 1, offset: 0 },
+							end: { line: 1, column: 80, offset: 79 },
+						},
+					],
+					input:
+						"feat: this is a very long header that exceeds the maximum allowed character limit for the commit message",
+				},
+			],
+		},
+		{
+			showPosition: true,
+			color: false,
+		},
+	);
+
+	expect(actual).toContain("^");
+});