Add media-query-no-invalid specific problem messages

.changeset/healthy-donkeys-appear.md

@@ -0,0 +1,5 @@
+---
+"stylelint": patch
+---
+
+Added: `media-query-no-invalid` specific problem messages

lib/rules/media-query-no-invalid/__tests__/index.mjs

@@ -159,31 +159,43 @@ testRule({
 		},
 		{
 			code: '@media (--foo: 2) {}',
-			message: messages.rejected('(--foo: 2)'),
+			message: messages.rejected(
+				'(--foo: 2)',
+				'custom media queries can only be used in boolean queries',
+			),
 			line: 1,
 			column: 8,
 			endLine: 1,
 			endColumn: 18,
 		},
 		{
 			code: '@media (min-width < 500px) {}',
-			message: messages.rejected('(min-width < 500px)'),
+			message: messages.rejected(
+				'(min-width < 500px)',
+				'"min-" and "max-" prefixes are not needed when using range queries',
+			),
 			line: 1,
 			column: 8,
 			endLine: 1,
 			endColumn: 27,
 		},
 		{
 			code: '@media (min-width) {}',
-			message: messages.rejected('(min-width)'),
+			message: messages.rejected(
+				'(min-width)',
+				'"min-" and "max-" prefixes are not needed in boolean queries',
+			),
 			line: 1,
 			column: 8,
 			endLine: 1,
 			endColumn: 19,
 		},
 		{
 			code: '@media (grid < 0) {}',
-			message: messages.rejected('(grid < 0)'),
+			message: messages.rejected(
+				'(grid < 0)',
+				'discrete features can only be used in plain and boolean queries',
+			),
 			line: 1,
 			column: 8,
 			endLine: 1,
@@ -248,15 +260,21 @@ testRule({
 		},
 		{
 			code: '@media (--foo: 300px) {}',
-			message: messages.rejected('(--foo: 300px)'),
+			message: messages.rejected(
+				'(--foo: 300px)',
+				'custom media queries can only be used in boolean queries',
+			),
 			line: 1,
 			column: 8,
 			endLine: 1,
 			endColumn: 22,
 		},
 		{
 			code: '@media (--foo < 300px) {}',
-			message: messages.rejected('(--foo < 300px)'),
+			message: messages.rejected(
+				'(--foo < 300px)',
+				'custom media queries can only be used in boolean queries',
+			),
 			line: 1,
 			column: 8,
 			endLine: 1,

lib/rules/media-query-no-invalid/index.cjs

@@ -15,7 +15,11 @@ const validateOptions = require('../../utils/validateOptions.cjs');
 const ruleName = 'media-query-no-invalid';
 
 const messages = ruleMessages(ruleName, {
-	rejected: (query) => `Unexpected invalid media query "${query}"`,
+	rejected: (query, hint) => {
+		if (!hint) return `Unexpected invalid media query "${query}"`;
+
+		return `Unexpected invalid media query "${query}", ${hint}`;
+	},
 });
 
 const HAS_MIN_MAX_PREFIX = /^(?:min|max)-/i;
@@ -34,21 +38,20 @@ const rule = (primary) => {
 		}
 
 		root.walkAtRules(/^media$/i, (atRule) => {
-			/** @type {Array<{tokens(): Array<import('@csstools/css-tokenizer').CSSToken>}>} */
-			let invalidNodes = [];
+			const atRuleParamIndexValue = atRuleParamIndex(atRule);
 
 			parseMediaQuery(atRule).forEach((mediaQuery) => {
 				if (mediaQueryListParser.isMediaQueryInvalid(mediaQuery)) {
 					// Queries that fail to parse are invalid.
-					invalidNodes.push(mediaQuery);
+					complain(atRule, atRuleParamIndexValue, mediaQuery);
 
 					return;
 				}
 
 				mediaQuery.walk(({ node, parent }) => {
 					// All general enclosed nodes are invalid.
 					if (mediaQueryListParser.isGeneralEnclosed(node)) {
-						invalidNodes.push(node);
+						complain(atRule, atRuleParamIndexValue, node);
 
 						return;
 					}
@@ -59,7 +62,12 @@ const rule = (primary) => {
 
 						if (isCustomMediaQuery(name)) {
 							// In a plain context, custom media queries are invalid.
-							invalidNodes.push(parent);
+							complain(
+								atRule,
+								atRuleParamIndexValue,
+								parent,
+								'custom media queries can only be used in boolean queries',
+							);
 
 							return;
 						}
@@ -73,21 +81,36 @@ const rule = (primary) => {
 
 						if (isCustomMediaQuery(name)) {
 							// In a range context, custom media queries are invalid.
-							invalidNodes.push(parent);
+							complain(
+								atRule,
+								atRuleParamIndexValue,
+								parent,
+								'custom media queries can only be used in boolean queries',
+							);
 
 							return;
 						}
 
 						if (HAS_MIN_MAX_PREFIX.test(name)) {
 							// In a range context, min- and max- prefixed feature names are invalid.
-							invalidNodes.push(parent);
+							complain(
+								atRule,
+								atRuleParamIndexValue,
+								parent,
+								'"min-" and "max-" prefixes are not needed when using range queries',
+							);
 
 							return;
 						}
 
 						if (!mediaFeatures.rangeTypeMediaFeatureNames.has(name)) {
 							// In a range context, non-range typed features are invalid.
-							invalidNodes.push(parent);
+							complain(
+								atRule,
+								atRuleParamIndexValue,
+								parent,
+								'discrete features can only be used in plain and boolean queries',
+							);
 
 							return;
 						}
@@ -101,30 +124,37 @@ const rule = (primary) => {
 
 						if (HAS_MIN_MAX_PREFIX.test(name)) {
 							// In a range context, min- and max- prefixed feature names are invalid
-							invalidNodes.push(parent);
+							complain(
+								atRule,
+								atRuleParamIndexValue,
+								parent,
+								'"min-" and "max-" prefixes are not needed in boolean queries',
+							);
 						}
 					}
 				});
 			});
+		});
 
-			if (invalidNodes.length === 0) return;
-
-			const atRuleParamIndexValue = atRuleParamIndex(atRule);
-
-			invalidNodes.forEach((invalidNode) => {
-				const [start, end] = cssParserAlgorithms.sourceIndices(invalidNode);
-
-				report({
-					message: messages.rejected,
-					messageArgs: [invalidNode.toString()],
-					index: atRuleParamIndexValue + start,
-					endIndex: atRuleParamIndexValue + end + 1,
-					node: atRule,
-					ruleName,
-					result,
-				});
+		/**
+		 * @param {import('postcss').AtRule} atRule
+		 * @param {number} index
+		 * @param {{tokens(): Array<import('@csstools/css-tokenizer').CSSToken>}} node
+		 * @param {string} messageHint
+		 */
+		function complain(atRule, index, node, messageHint = '') {
+			const [start, end] = cssParserAlgorithms.sourceIndices(node);
+
+			report({
+				message: messages.rejected,
+				messageArgs: [node.toString(), messageHint],
+				index: index + start,
+				endIndex: index + end + 1,
+				node: atRule,
+				ruleName,
+				result,
 			});
-		});
+		}
 	};
 };
 

lib/rules/media-query-no-invalid/index.mjs

@@ -18,7 +18,11 @@ import validateOptions from '../../utils/validateOptions.mjs';
 const ruleName = 'media-query-no-invalid';
 
 const messages = ruleMessages(ruleName, {
-	rejected: (query) => `Unexpected invalid media query "${query}"`,
+	rejected: (query, hint) => {
+		if (!hint) return `Unexpected invalid media query "${query}"`;
+
+		return `Unexpected invalid media query "${query}", ${hint}`;
+	},
 });
 
 const HAS_MIN_MAX_PREFIX = /^(?:min|max)-/i;
@@ -37,21 +41,20 @@ const rule = (primary) => {
 		}
 
 		root.walkAtRules(/^media$/i, (atRule) => {
-			/** @type {Array<{tokens(): Array<import('@csstools/css-tokenizer').CSSToken>}>} */
-			let invalidNodes = [];
+			const atRuleParamIndexValue = atRuleParamIndex(atRule);
 
 			parseMediaQuery(atRule).forEach((mediaQuery) => {
 				if (isMediaQueryInvalid(mediaQuery)) {
 					// Queries that fail to parse are invalid.
-					invalidNodes.push(mediaQuery);
+					complain(atRule, atRuleParamIndexValue, mediaQuery);
 
 					return;
 				}
 
 				mediaQuery.walk(({ node, parent }) => {
 					// All general enclosed nodes are invalid.
 					if (isGeneralEnclosed(node)) {
-						invalidNodes.push(node);
+						complain(atRule, atRuleParamIndexValue, node);
 
 						return;
 					}
@@ -62,7 +65,12 @@ const rule = (primary) => {
 
 						if (isCustomMediaQuery(name)) {
 							// In a plain context, custom media queries are invalid.
-							invalidNodes.push(parent);
+							complain(
+								atRule,
+								atRuleParamIndexValue,
+								parent,
+								'custom media queries can only be used in boolean queries',
+							);
 
 							return;
 						}
@@ -76,21 +84,36 @@ const rule = (primary) => {
 
 						if (isCustomMediaQuery(name)) {
 							// In a range context, custom media queries are invalid.
-							invalidNodes.push(parent);
+							complain(
+								atRule,
+								atRuleParamIndexValue,
+								parent,
+								'custom media queries can only be used in boolean queries',
+							);
 
 							return;
 						}
 
 						if (HAS_MIN_MAX_PREFIX.test(name)) {
 							// In a range context, min- and max- prefixed feature names are invalid.
-							invalidNodes.push(parent);
+							complain(
+								atRule,
+								atRuleParamIndexValue,
+								parent,
+								'"min-" and "max-" prefixes are not needed when using range queries',
+							);
 
 							return;
 						}
 
 						if (!rangeTypeMediaFeatureNames.has(name)) {
 							// In a range context, non-range typed features are invalid.
-							invalidNodes.push(parent);
+							complain(
+								atRule,
+								atRuleParamIndexValue,
+								parent,
+								'discrete features can only be used in plain and boolean queries',
+							);
 
 							return;
 						}
@@ -104,30 +127,37 @@ const rule = (primary) => {
 
 						if (HAS_MIN_MAX_PREFIX.test(name)) {
 							// In a range context, min- and max- prefixed feature names are invalid
-							invalidNodes.push(parent);
+							complain(
+								atRule,
+								atRuleParamIndexValue,
+								parent,
+								'"min-" and "max-" prefixes are not needed in boolean queries',
+							);
 						}
 					}
 				});
 			});
+		});
 
-			if (invalidNodes.length === 0) return;
-
-			const atRuleParamIndexValue = atRuleParamIndex(atRule);
-
-			invalidNodes.forEach((invalidNode) => {
-				const [start, end] = sourceIndices(invalidNode);
-
-				report({
-					message: messages.rejected,
-					messageArgs: [invalidNode.toString()],
-					index: atRuleParamIndexValue + start,
-					endIndex: atRuleParamIndexValue + end + 1,
-					node: atRule,
-					ruleName,
-					result,
-				});
+		/**
+		 * @param {import('postcss').AtRule} atRule
+		 * @param {number} index
+		 * @param {{tokens(): Array<import('@csstools/css-tokenizer').CSSToken>}} node
+		 * @param {string} messageHint
+		 */
+		function complain(atRule, index, node, messageHint = '') {
+			const [start, end] = sourceIndices(node);
+
+			report({
+				message: messages.rejected,
+				messageArgs: [node.toString(), messageHint],
+				index: index + start,
+				endIndex: index + end + 1,
+				node: atRule,
+				ruleName,
+				result,
 			});
-		});
+		}
 	};
 };