Add ignoreAtRules: [] to no-invalid-position-declaration (#8781)

jrmlt · jeddy3 · ybiquitous · web-flow · commit b478202a2f06 · 2025-09-25T09:49:09.000+01:00
Co-authored-by: Richard Hallows &lt;jeddy3@users.noreply.github.com&gt;
Co-authored-by: Masafumi Koba &lt;473530+ybiquitous@users.noreply.github.com&gt;
diff --git a/lib/rules/no-invalid-position-declaration/README.md b/lib/rules/no-invalid-position-declaration/README.md
@@ -60,3 +60,53 @@ a { --foo: red; }
   }
 }
 ```
+
+<!-- prettier-ignore -->
+```css
+a {
+  @media all {
+    color: red;
+  }
+}
+```
+
+## Optional secondary options
+
+### `ignoreAtRules`
+
+```json
+{ "ignoreAtRules": ["array", "of", "at-rules", "/regex/"] }
+```
+
+Ignore nesting at-rules within specified at-rules.
+
+Given:
+
+```json
+{
+  "no-invalid-position-declaration": [
+    true,
+    { "ignoreAtRules": ["--foo", "/^--bar-/"] }
+  ]
+}
+```
+
+The following patterns are _not_ considered problems:
+
+<!-- prettier-ignore -->
+```css
+@--foo {
+  @media all {
+    color: red;
+  }
+}
+```
+
+<!-- prettier-ignore -->
+```css
+@--bar-baz qux {
+  @layer foo {
+    color: red;
+  }
+}
+```
diff --git a/lib/rules/no-invalid-position-declaration/__tests__/index.mjs b/lib/rules/no-invalid-position-declaration/__tests__/index.mjs
@@ -352,3 +352,36 @@ testRule({
 		},
 	],
 });
+
+testRule({
+	ruleName,
+	config: [true, { ignoreAtRules: ['--foo', '/^--bar-/'] }],
+
+	accept: [
+		{
+			code: '@--foo { @media all { color: red; } }',
+		},
+		{
+			code: '@--bar-baz qux { @media all { color: red; } }',
+		},
+	],
+
+	reject: [
+		{
+			code: '@foo { @media all { color: red; } }',
+			message: messages.rejected,
+			line: 1,
+			column: 21,
+			endLine: 1,
+			endColumn: 32,
+		},
+		{
+			code: '@--bar { @media all { color: red; } }',
+			message: messages.rejected,
+			line: 1,
+			column: 23,
+			endLine: 1,
+			endColumn: 34,
+		},
+	],
+});
diff --git a/lib/rules/no-invalid-position-declaration/index.cjs b/lib/rules/no-invalid-position-declaration/index.cjs
diff --git a/lib/rules/no-invalid-position-declaration/index.mjs b/lib/rules/no-invalid-position-declaration/index.mjs
@@ -1,8 +1,10 @@
 import { isAtRule, isRule } from '../../utils/typeGuards.mjs';
+import { isRegExp, isString } from '../../utils/validateTypes.mjs';
 import findNodeUpToRoot from '../../utils/findNodeUpToRoot.mjs';
 import isInDocument from '../../utils/isInDocument.mjs';
 import isStandardSyntaxDeclaration from '../../utils/isStandardSyntaxDeclaration.mjs';
 import { nestingSupportedAtKeywords } from '../../reference/atKeywords.mjs';
+import optionsMatches from '../../utils/optionsMatches.mjs';
 import report from '../../utils/report.mjs';
 import ruleMessages from '../../utils/ruleMessages.mjs';
 import validateOptions from '../../utils/validateOptions.mjs';
@@ -18,12 +20,27 @@ const meta = {
 };
 
 /** @type {import('stylelint').CoreRules[ruleName]} */
-const rule = (primary) => {
+const rule = (primary, secondaryOptions) => {
 	return (root, result) => {
-		const validOptions = validateOptions(result, ruleName, { actual: primary });
+		const validOptions = validateOptions(
+			result,
+			ruleName,
+			{ actual: primary, possible: [true] },
+			{
+				actual: secondaryOptions,
+				possible: {
+					ignoreAtRules: [isString, isRegExp],
+				},
+				optional: true,
+			},
+		);
 
 		if (!validOptions) return;
 
+		/** @type {(node: import('postcss').Node) => boolean} */
+		const isIgnoredAtRule = (node) =>
+			isAtRule(node) && optionsMatches(secondaryOptions, 'ignoreAtRules', node.name);
+
 		root.walkDecls((decl) => {
 			// Skip checking declarations in embedded styles
 			if (isInDocument(decl)) return;
@@ -42,7 +59,10 @@ const rule = (primary) => {
 
 				// Nesting-supported at-rules only allow declarations when nested inside a rule
 				if (nestingSupportedAtKeywords.has(atRuleName)) {
-					const parentRule = findNodeUpToRoot(decl, ({ type }) => type === 'rule');
+					const parentRule = findNodeUpToRoot(
+						decl,
+						(node) => isRule(node) || isIgnoredAtRule(node),
+					);
 
 					if (parentRule) return;
 				} else {
diff --git a/types/stylelint/index.d.ts b/types/stylelint/index.d.ts
@@ -804,7 +804,7 @@ declare namespace stylelint {
 			true,
 			{ ignoreAtRules: OneOrMany<StringOrRegex> }
 		>;
-		'no-invalid-position-declaration': CoreRule<true>;
+		'no-invalid-position-declaration': CoreRule<true, { ignoreAtRules: OneOrMany<StringOrRegex> }>;
 		'no-irregular-whitespace': CoreRule<true>;
 		'no-unknown-animations': CoreRule<true, {}, RejectedMessage<[name: string]>>;
 		'no-unknown-custom-media': CoreRule<true, {}, RejectedMessage<[name: string]>>;
