AG-29460 Add no-invalid-cosmetic-separator rule

Author: jellizaveta

CHANGELOG.md

@@ -7,6 +7,12 @@ The format is based on [Keep a Changelog], and this project adheres to [Semantic
 [Keep a Changelog]: https://keepachangelog.com/en/1.0.0/
 [Semantic Versioning]: https://semver.org/spec/v2.0.0.html
 
+## [Unreleazed]
+
+### Added
+
+- `no-invalid-cosmetic-separator` linter rule.
+
 ## [4.0.0-beta.5] - 2025-12-22
 
 ### Added

config-presets/all.json

@@ -20,6 +20,7 @@
       }
     ],
     "no-inconsistent-hint-platforms": "error",
+    "no-invalid-cosmetic-separator": "error",
     "no-invalid-css-declaration": "error",
     "no-invalid-domains": "error",
     "no-invalid-hint-params": "error",

config-presets/recommended.json

@@ -7,6 +7,7 @@
     "no-duplicated-hints": "error",
     "no-duplicated-modifiers": "error",
     "no-inconsistent-hint-platforms": "error",
+    "no-invalid-cosmetic-separator": "error",
     "no-invalid-css-declaration": "error",
     "no-invalid-domains": "error",
     "no-invalid-hint-params": "error",

docs/rules/README.md

@@ -12,6 +12,7 @@
 | [no-duplicated-modifiers](./no-duplicated-modifiers.md) | Checks if a network rule contains multiple same modifiers | ✅ |  |  |
 | [no-excluded-rules](./no-excluded-rules.md) | Checks if any rule matches an excluded pattern |  | 🔧 |  |
 | [no-inconsistent-hint-platforms](./no-inconsistent-hint-platforms.md) | Checks if a platform targeted by a PLATFORM() hint is also excluded by a NOT_PLATFORM() hint at the same time | ✅ |  |  |
+| [no-invalid-cosmetic-separator](./no-invalid-cosmetic-separator.md) | Validates that rule separator matches selector/declaration capabilities | ✅ | 🔧 | 💡 |
 | [no-invalid-css-declaration](./no-invalid-css-declaration.md) | Checks if CSS declarations are valid | ✅ |  |  |
 | [no-invalid-domains](./no-invalid-domains.md) | Disallows invalid domains | ✅ |  | 💡 |
 | [no-invalid-hint-params](./no-invalid-hint-params.md) | Checks if hints are parameterized correctly | ✅ |  |  |

docs/rules/no-invalid-cosmetic-separator.md

@@ -0,0 +1,128 @@
+<!-- markdownlint-disable -->
+# `no-invalid-cosmetic-separator`
+
+> ✅ Using `aglint:recommended` preset will enable this rule
+
+## Description
+
+Validates that rule separator matches selector/declaration capabilities
+
+## Type
+
+Problem. Identifies parts that causes errors or confusing behavior. High priority fix.
+
+## Automatic issue fixing
+
+- Some reported problems can be fixed automatically 🔧
+- Some reported problems can be fixed via suggestions 💡
+
+## Correct examples
+
+Examples of correct code:
+
+### Element hiding with extended selector
+
+The following code
+
+```adblock
+#?#div:contains(a)
+```
+
+should not be reported
+
+## Incorrect examples
+
+Examples of incorrect code:
+
+### Extended selector with native separator
+
+The following code
+
+```adblock
+##div:contains(a)
+```
+
+should be reported as:
+
+```shell
+1:2 Extended CSS is used in selector, replace "##" with "#?#"
+```
+
+and the following suggestions should be offered:
+
+- Change separator to "#?#"
+
+  ```diff
+  ===================================================================
+  --- original
+  +++ fixed
+  @@ -1,1 +1,1 @@
+  -##div:contains(a)
+  +#?#div:contains(a)
+  ```
+
+### Extended selector nested in :has() with native separator
+
+The following code
+
+```adblock
+##div:has(> table:contains(a))
+```
+
+should be reported as:
+
+```shell
+1:2 Extended CSS is used in selector, replace "##" with "#?#"
+```
+
+and the following suggestions should be offered:
+
+- Change separator to "#?#"
+
+  ```diff
+  ===================================================================
+  --- original
+  +++ fixed
+  @@ -1,1 +1,1 @@
+  -##div:has(> table:contains(a))
+  +#?#div:has(> table:contains(a))
+  ```
+
+### remove:true with native CSS injection separator
+
+The following code
+
+```adblock
+#$#a[href^="/bnlink/?bnid="] { remove: true; }
+```
+
+should be reported as:
+
+```shell
+1:3 Declaration { remove: true; } is allowed only with "#$?#" separator
+```
+
+and the following suggestions should be offered:
+
+- Change separator to "#$?#"
+
+  ```diff
+  ===================================================================
+  --- original
+  +++ fixed
+  @@ -1,1 +1,1 @@
+  -#$#a[href^="/bnlink/?bnid="] { remove: true; }
+  +#$?#a[href^="/bnlink/?bnid="] { remove: true; }
+  ```
+
+## Version
+
+This rule was added in AGLint version 4.0.0
+
+## Rule source
+
+https://github.com/AdguardTeam/AGLint/blob/master/src/rules/no-invalid-cosmetic-separator.ts
+
+## Test cases
+
+https://github.com/AdguardTeam/AGLint/blob/master/test/rules/no-invalid-cosmetic-separator.test.ts

package.json

@@ -88,6 +88,11 @@
             "import": "./dist/rules/no-inconsistent-hint-platforms.js",
             "default": "./dist/rules/no-inconsistent-hint-platforms.js"
         },
+        "./rules/no-invalid-cosmetic-separator": {
+            "types": "./dist/rules/no-invalid-cosmetic-separator.d.ts",
+            "import": "./dist/rules/no-invalid-cosmetic-separator.js",
+            "default": "./dist/rules/no-invalid-cosmetic-separator.js"
+        },
         "./rules/no-invalid-css-declaration": {
             "types": "./dist/rules/no-invalid-css-declaration.d.ts",
             "import": "./dist/rules/no-invalid-css-declaration.js",