Add rule name to custom messages

jhae-de · jhae-de · commit f9fde25ca462 · 2025-09-28T23:51:07.000+02:00
Ensures that when a custom message is specified in a Stylelint configuration, the rule name is automatically appended in parentheses at the end of the message if not already present, improving traceability of reported problems.
diff --git a/.changeset/violet-beds-care.md b/.changeset/violet-beds-care.md
@@ -0,0 +1,5 @@
+---
+"stylelint": minor
+---
+
+Added: rule name to custom messages
diff --git a/lib/__tests__/integration.test.mjs b/lib/__tests__/integration.test.mjs
@@ -94,7 +94,7 @@ describe('integration test expecting warnings', () => {
 		expect(errors).toHaveLength(2);
 
 		for (const error of errors) {
-			expect(error.text).toBe('You made a mistake');
+			expect(error.text).toBe('You made a mistake (color-no-invalid-hex)');
 			expect(error.severity).toBe('warning');
 		}
 	});
diff --git a/lib/__tests__/message.test.mjs b/lib/__tests__/message.test.mjs
@@ -12,5 +12,5 @@ it('standalone loading YAML with custom message', async () => {
 	});
 
 	expect(results[0].warnings).toHaveLength(1);
-	expect(results[0].warnings[0].text).toBe('Unacceptable');
+	expect(results[0].warnings[0].text).toBe('Unacceptable (color-named)');
 });
diff --git a/lib/rules/rule-selector-property-disallowed-list/__tests__/index.mjs b/lib/rules/rule-selector-property-disallowed-list/__tests__/index.mjs
@@ -130,7 +130,7 @@ testRule({
 	reject: [
 		{
 			code: 'a { color: red; }',
-			message: 'foo',
+			message: `foo (${ruleName})`,
 			description: 'custom message',
 		},
 	],
diff --git a/lib/utils/__tests__/appendRuleName.test.mjs b/lib/utils/__tests__/appendRuleName.test.mjs
@@ -0,0 +1,15 @@
+import appendRuleName from '../appendRuleName.mjs';
+
+describe('appendRuleName', () => {
+	const expectedString = 'Unexpected empty block (block-no-empty)';
+
+	it('should append rule name in parentheses if not present', () => {
+		expect(appendRuleName('Unexpected empty block', 'block-no-empty')).toBe(expectedString);
+	});
+
+	it('should not append rule name if already present', () => {
+		expect(appendRuleName('Unexpected empty block (block-no-empty)', 'block-no-empty')).toBe(
+			expectedString,
+		);
+	});
+});
diff --git a/lib/utils/__tests__/report.test.mjs b/lib/utils/__tests__/report.test.mjs
@@ -44,7 +44,7 @@ test('without disabledRanges', () => {
 	report(v);
 	const spyArgs = v.result.warn.mock.calls[0];
 
-	expect(spyArgs[0]).toBe('bar');
+	expect(spyArgs[0]).toBe('bar (foo)');
 	expect(spyArgs[1].node).toBe(v.node);
 });
 
@@ -68,7 +68,7 @@ test('with irrelevant general disabledRange', () => {
 	report(v);
 	const spyArgs = v.result.warn.mock.calls[0];
 
-	expect(spyArgs[0]).toBe('bar');
+	expect(spyArgs[0]).toBe('bar (foo)');
 	expect(spyArgs[1].node).toBe(v.node);
 });
 
@@ -114,7 +114,7 @@ test('with irrelevant rule-specific disabledRange', () => {
 	report(v);
 	const spyArgs = v.result.warn.mock.calls[0];
 
-	expect(spyArgs[0]).toBe('bar');
+	expect(spyArgs[0]).toBe('bar (foo)');
 	expect(spyArgs[1].node).toBe(v.node);
 });
 
@@ -276,7 +276,7 @@ test('with custom rule severity', () => {
 	report(v);
 	const spyArgs = v.result.warn.mock.calls[0];
 
-	expect(spyArgs[0]).toBe('bar');
+	expect(spyArgs[0]).toBe('bar (foo)');
 	expect(spyArgs[1].severity).toBe('warning');
 	expect(spyArgs[1].node).toBe(v.node);
 });
@@ -396,7 +396,7 @@ test('with message function', () => {
 	report(v);
 	const spyArgs = v.result.warn.mock.calls[0];
 
-	expect(spyArgs[0]).toBe('a=str, b=true, c=10, d=/regex/');
+	expect(spyArgs[0]).toBe('a=str, b=true, c=10, d=/regex/ (foo)');
 	expect(spyArgs[1].node).toBe(v.node);
 });
 
@@ -529,7 +529,7 @@ describe('with fix object', () => {
 
 		const spyArgs1 = v.result.warn.mock.calls[0];
 
-		expect(spyArgs1[0]).toBe('bar');
+		expect(spyArgs1[0]).toBe('bar (foo)');
 		expect(spyArgs1[1].fix.range).toMatchObject([0, 3]);
 		expect(spyArgs1[1].fix.text).toBe('bar');
 
@@ -543,7 +543,7 @@ describe('with fix object', () => {
 
 		const spyArgs2 = v.result.warn.mock.calls[1];
 
-		expect(spyArgs2[0]).toBe('qux');
+		expect(spyArgs2[0]).toBe('qux (foo)');
 		expect(spyArgs2[1].fix).toBeUndefined();
 	});
 
@@ -579,7 +579,7 @@ describe('with fix object', () => {
 
 		const spyArgs = v.result.warn.mock.calls[0];
 
-		expect(spyArgs[0]).toBe('bar');
+		expect(spyArgs[0]).toBe('bar (foo)');
 		expect(spyArgs[1].fix).toBeUndefined();
 	});
 
@@ -618,7 +618,7 @@ describe('with fix object', () => {
 
 		const spyArgs = v.result.warn.mock.calls[0];
 
-		expect(spyArgs[0]).toBe('bar');
+		expect(spyArgs[0]).toBe('bar (foo)');
 		expect(spyArgs[1].fix).toBeUndefined();
 	});
 
@@ -652,7 +652,7 @@ describe('with fix object', () => {
 
 		const spyArgs = v.result.warn.mock.calls[0];
 
-		expect(spyArgs[0]).toBe('bar');
+		expect(spyArgs[0]).toBe('bar (foo)');
 		expect(spyArgs[1].fix).toBeUndefined();
 	});
 
@@ -686,7 +686,7 @@ describe('with fix object', () => {
 
 		const spyArgs = v.result.warn.mock.calls[0];
 
-		expect(spyArgs[0]).toBe('bar');
+		expect(spyArgs[0]).toBe('bar (foo)');
 		expect(spyArgs[1].fix).toBeUndefined();
 	});
 });
@@ -710,7 +710,51 @@ test('with custom message', () => {
 	report(v);
 	const spyArgs = v.result.warn.mock.calls[0];
 
-	expect(spyArgs[0]).toBe('A custom message: str, true, 10, /regex/');
+	expect(spyArgs[0]).toBe('A custom message: str, true, 10, /regex/ (foo)');
+	expect(spyArgs[1].node).toBe(v.node);
+});
+
+test('with custom message (missing rule name)', () => {
+	const v = {
+		ruleName: 'foo',
+		result: {
+			warn: jest.fn(),
+			stylelint: resultStylelint({
+				customMessages: { foo: 'A custom message with appended rule name' },
+			}),
+		},
+		message: 'bar',
+		node: {
+			rangeBy: defaultRangeBy,
+		},
+	};
+
+	report(v);
+	const spyArgs = v.result.warn.mock.calls[0];
+
+	expect(spyArgs[0]).toBe('A custom message with appended rule name (foo)');
+	expect(spyArgs[1].node).toBe(v.node);
+});
+
+test('with custom message (appended rule name)', () => {
+	const v = {
+		ruleName: 'foo',
+		result: {
+			warn: jest.fn(),
+			stylelint: resultStylelint({
+				customMessages: { foo: 'A custom message with appended rule name (foo)' },
+			}),
+		},
+		message: 'bar',
+		node: {
+			rangeBy: defaultRangeBy,
+		},
+	};
+
+	report(v);
+	const spyArgs = v.result.warn.mock.calls[0];
+
+	expect(spyArgs[0]).toBe('A custom message with appended rule name (foo)');
 	expect(spyArgs[1].node).toBe(v.node);
 });
 
@@ -733,7 +777,7 @@ test('with custom message function', () => {
 	report(v);
 	const spyArgs = v.result.warn.mock.calls[0];
 
-	expect(spyArgs[0]).toBe('a=str, b=123');
+	expect(spyArgs[0]).toBe('a=str, b=123 (foo)');
 	expect(spyArgs[1].node).toBe(v.node);
 });
 
diff --git a/lib/utils/appendRuleName.mjs b/lib/utils/appendRuleName.mjs
@@ -0,0 +1,13 @@
+/**
+ * Ensures the given rule name is appended to the provided string.
+ *
+ * If the string does not already end with the rule name in parentheses, the rule name is appended in parentheses.
+ *
+ * @param {string} string - The message to which the rule name may be appended
+ * @param {string} ruleName - The rule name to append
+ *
+ * @returns {string} The provided string with the given rule name appended
+ */
+export default function appendRuleName(string, ruleName) {
+	return !string.endsWith(`(${ruleName})`) ? `${string} (${ruleName})` : string;
+}
diff --git a/lib/utils/report.cjs b/lib/utils/report.cjs
diff --git a/lib/utils/report.mjs b/lib/utils/report.mjs
@@ -13,6 +13,7 @@ import {
 	SEVERITY_WARNING,
 } from '../constants.mjs';
 import addSemicolonForEditInfo from './addSemicolonForEditInfo.mjs';
+import appendRuleName from './appendRuleName.mjs';
 import { emitDeprecationWarning } from './emitWarning.mjs';
 import narrowFixRange from './narrowFixRange.mjs';
 import rangesOverlap from './rangesOverlap.mjs';
@@ -126,7 +127,7 @@ export default function report(problem) {
 
 	warningProperties.fix = computeEditInfo({ ...problem, line: startLine });
 
-	const warningMessage = buildWarningMessage(message, messageArgs);
+	const warningMessage = buildWarningMessage(message, messageArgs, ruleName);
 
 	result.warn(warningMessage, warningProperties);
 }
@@ -173,14 +174,14 @@ function checkProblemRangeDeprecations(problem) {
 /**
  * @param {RuleMessage} message
  * @param {NonNullable<Problem['messageArgs']>} messageArgs
+ * @param {string} ruleName
  * @returns {string}
  */
-function buildWarningMessage(message, messageArgs) {
-	if (isString(message)) {
-		return printfLike(message, ...messageArgs);
-	}
-
-	return message(...messageArgs);
+function buildWarningMessage(message, messageArgs, ruleName) {
+	return appendRuleName(
+		isString(message) ? printfLike(message, ...messageArgs) : message(...messageArgs),
+		ruleName,
+	);
 }
 
 /**

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"stylelint": minor
 +---
++
 +Added: rule name to custom messages
Original file line number	Diff line number	Diff line change
`@@ -94,7 +94,7 @@ describe('integration test expecting warnings', () => {`
`94`	`94`	`expect(errors).toHaveLength(2);`
`95`	`95`
`96`	`96`	`for (const error of errors) {`
`97`		`- expect(error.text).toBe('You made a mistake');`
	`97`	`+ expect(error.text).toBe('You made a mistake (color-no-invalid-hex)');`
`98`	`98`	`expect(error.severity).toBe('warning');`
`99`	`99`	`}`
`100`	`100`	`});`
Original file line number	Diff line number	Diff line change
`@@ -130,7 +130,7 @@ testRule({`
`130`	`130`	`reject: [`
`131`	`131`	`{`
`132`	`132`	`code: 'a { color: red; }',`
`133`		`- message: 'foo',`
	`133`	+ message: `foo (${ruleName})`,
`134`	`134`	`description: 'custom message',`
`135`	`135`	`},`
`136`	`136`	`],`