eslint-plugin-stylelint-2 1.0.9

package/docs/rules/disallow-stylelint-duplicate-plugins.md

@@ -0,0 +1,61 @@
+# disallow-stylelint-duplicate-plugins
+
+Disallow duplicate entries in top-level Stylelint `plugins` declarations.
+
+## Targeted pattern scope
+
+This rule targets Stylelint config modules such as `stylelint.config.ts`, `stylelint.config.mjs`, and `.stylelintrc.js`.
+
+It focuses on top-level exported config objects, including configs wrapped in `defineConfig(...)`.
+
+## What this rule reports
+
+Reports duplicate string entries in top-level `plugins` arrays.
+
+## Why this rule exists
+
+Duplicate plugin references make config harder to reason about and create unnecessary churn in shared lint setup.
+
+## ❌ Incorrect
+
+```ts
+export default {
+    plugins: ["stylelint-order", "stylelint-order"],
+    rules: {},
+};
+```
+
+## ✅ Correct
+
+```ts
+export default {
+    plugins: ["stylelint-order"],
+    rules: {},
+};
+```
+
+## Behavior and migration notes
+
+This rule auto-fixes by keeping the first occurrence of each plugin entry.
+
+## ESLint flat config example
+
+```ts
+import stylelint2 from "eslint-plugin-stylelint-2";
+
+export default [stylelint2.configs.configuration];
+```
+
+## When not to use it
+
+Do not use this rule if duplicate plugin entries are intentionally required by external code-generation workflows.
+
+## Package documentation
+
+Stylelint package documentation:
+
+> **Rule catalog ID:** R024
+
+## Further reading
+
+- [Stylelint plugins](https://stylelint.io/user-guide/configure/#plugins)

package/docs/rules/disallow-stylelint-duplicate-rule-option-values.md

@@ -0,0 +1,73 @@
+# disallow-stylelint-duplicate-rule-option-values
+
+Disallow duplicate scalar literals in array-valued Stylelint secondary rule options.
+
+## Targeted pattern scope
+
+This rule targets Stylelint config modules such as `stylelint.config.ts`, `stylelint.config.mjs`, and `.stylelintrc.js`.
+
+It focuses on top-level exported config objects, including configs wrapped in `defineConfig(...)`.
+
+## What this rule reports
+
+Reports duplicate scalar literals in array-valued properties inside secondary option objects.
+
+## Why this rule exists
+
+Duplicate option values add noise and can obscure actual rule intent during config review.
+
+## ❌ Incorrect
+
+```ts
+export default {
+    rules: {
+        "selector-class-pattern": [
+            "^[a-z]+$",
+            {
+                resolveNestedSelectors: [":global", ":global", ":host"],
+            },
+        ],
+    },
+};
+```
+
+## ✅ Correct
+
+```ts
+export default {
+    rules: {
+        "selector-class-pattern": [
+            "^[a-z]+$",
+            {
+                resolveNestedSelectors: [":global", ":host"],
+            },
+        ],
+    },
+};
+```
+
+## Behavior and migration notes
+
+This rule auto-fixes by keeping the first occurrence of each duplicate scalar literal value.
+
+## ESLint flat config example
+
+```ts
+import stylelint2 from "eslint-plugin-stylelint-2";
+
+export default [stylelint2.configs.configuration];
+```
+
+## When not to use it
+
+Do not use this rule if your stylelint secondary option arrays intentionally include duplicate scalar values for generated-tool compatibility.
+
+## Package documentation
+
+Stylelint package documentation:
+
+> **Rule catalog ID:** R032
+
+## Further reading
+
+- [Stylelint secondary options](https://stylelint.io/user-guide/configure/)

package/docs/rules/disallow-stylelint-empty-rules-object.md

@@ -0,0 +1,62 @@
+# disallow-stylelint-empty-rules-object
+
+Disallow an empty top-level `rules` object in authored Stylelint config files.
+
+## Targeted pattern scope
+
+This rule targets Stylelint config modules such as `stylelint.config.ts`, `stylelint.config.mjs`, and `.stylelintrc.js`.
+
+It focuses on top-level exported config objects, including configs wrapped in `defineConfig(...)`.
+
+## What this rule reports
+
+This rule reports config objects that include `rules: {}` with no configured rules.
+
+## Why this rule exists
+
+An empty `rules` object in committed shared config is usually accidental drift. It communicates that rule policy exists while actually enabling nothing.
+
+## ❌ Incorrect
+
+```ts
+export default {
+    rules: {},
+};
+```
+
+## ✅ Correct
+
+```ts
+export default {
+    rules: {
+        "color-no-invalid-hex": true,
+    },
+};
+```
+
+## Behavior and migration notes
+
+- This rule reports empty rules objects.
+- It does not auto-fix because the desired replacement depends on your policy (add real rules or remove the object).
+
+## ESLint flat config example
+
+```ts
+import stylelint2 from "eslint-plugin-stylelint-2";
+
+export default [stylelint2.configs.configuration];
+```
+
+## When not to use it
+
+Do not use this rule if your team intentionally keeps empty `rules` objects as scaffolding placeholders.
+
+## Package documentation
+
+Stylelint package documentation:
+
+> **Rule catalog ID:** R018
+
+## Further reading
+
+- [Stylelint rules reference](https://stylelint.io/user-guide/rules/list)

package/docs/rules/disallow-stylelint-ignore-disables.md

@@ -0,0 +1,78 @@
+# disallow-stylelint-ignore-disables
+
+Disallow configuring Stylelint's top-level `ignoreDisables` option inside authored Stylelint config files.
+
+## Targeted pattern scope
+
+This rule targets Stylelint config modules such as `stylelint.config.ts`, `stylelint.config.mjs`, and `.stylelintrc.js`.
+
+It focuses on top-level exported config objects, including configs wrapped in `defineConfig(...)`.
+
+## What this rule reports
+
+This rule reports Stylelint config objects that include a top-level `ignoreDisables` property.
+
+## Why this rule exists
+
+This plugin now provides a family of rules that reinforce Stylelint disable-comment reporting. `ignoreDisables: true` undermines that governance by making Stylelint disregard disable comments entirely.
+
+That setting is an execution policy decision and is usually a poor fit for a shared committed config object.
+
+## ❌ Incorrect
+
+```ts
+export default {
+    ignoreDisables: true,
+    rules: {},
+};
+```
+
+## ✅ Correct
+
+```ts
+export default {
+    rules: {},
+};
+```
+
+## Behavior and migration notes
+
+- This rule removes the top-level `ignoreDisables` property.
+- It preserves the rest of the config object.
+- If you truly need to ignore disable comments, set that at the Stylelint invocation layer instead of the shared config file.
+
+## Additional examples
+
+### ✅ Correct — leave invocation-only behavior to the runner
+
+```ts
+await stylelint.lint({
+    code,
+    ignoreDisables: true,
+});
+```
+
+## ESLint flat config example
+
+```ts
+import stylelint2 from "eslint-plugin-stylelint-2";
+
+export default [
+    stylelint2.configs.configuration,
+];
+```
+
+## When not to use it
+
+Do not use this rule if your team intentionally wants a committed shared Stylelint config to ignore disable comments across every environment.
+
+## Package documentation
+
+Stylelint package documentation:
+
+> **Rule catalog ID:** R008
+
+## Further reading
+
+- [Stylelint configuring guide](https://stylelint.io/user-guide/configure/#ignoredisables)
+- [Stylelint ignore-code guide](https://stylelint.io/user-guide/ignore-code/)

package/docs/rules/disallow-stylelint-ignore-files.md

@@ -0,0 +1,78 @@
+# disallow-stylelint-ignore-files
+
+Disallow configuring Stylelint's top-level `ignoreFiles` option inside authored Stylelint config files.
+
+## Targeted pattern scope
+
+This rule targets Stylelint config modules such as `stylelint.config.ts`, `stylelint.config.mjs`, and `.stylelintrc.js`.
+
+It focuses on top-level exported config objects, including configs wrapped in `defineConfig(...)`.
+
+## What this rule reports
+
+This rule reports Stylelint config objects that include a top-level `ignoreFiles` property.
+
+## Why this rule exists
+
+`ignoreFiles` changes lint coverage at the config level and can accidentally hide files from linting across editor, CI, and local workflows.
+
+Stylelint also documents that `ignoreFiles` is not efficient for broad ignore coverage and can override default `node_modules` ignore behavior. In shared configs, ignore scope is usually clearer in `.stylelintignore` or invocation-level file globs.
+
+## ❌ Incorrect
+
+```ts
+export default {
+    ignoreFiles: ["**/vendor/**/*.css"],
+    rules: {},
+};
+```
+
+## ✅ Correct
+
+```ts
+export default {
+    rules: {},
+};
+```
+
+## Behavior and migration notes
+
+- This rule removes the top-level `ignoreFiles` property.
+- It preserves the rest of the config object.
+- Move ignore patterns to `.stylelintignore` (preferred for file-scope ignores) or to explicit invocation globs in scripts.
+
+## Additional examples
+
+### ✅ Correct — ignore scope moved out of shared config
+
+```ts
+// package.json
+{
+    "scripts": {
+        "lint:css": "stylelint \"src/**/*.{css,scss}\""
+    }
+}
+```
+
+## ESLint flat config example
+
+```ts
+import stylelint2 from "eslint-plugin-stylelint-2";
+
+export default [stylelint2.configs.configuration];
+```
+
+## When not to use it
+
+Do not use this rule if your team intentionally controls all Stylelint ignore patterns directly in the committed config object and accepts that coupling.
+
+## Package documentation
+
+Stylelint package documentation:
+
+> **Rule catalog ID:** R010
+
+## Further reading
+
+- [Stylelint configuring guide](https://stylelint.io/user-guide/configure/#ignorefiles)
+- [Stylelint ignoring code](https://stylelint.io/user-guide/ignore-code/)

package/docs/rules/disallow-stylelint-null-rule-config.md

@@ -0,0 +1,63 @@
+# disallow-stylelint-null-rule-config
+
+Disallow `null` values in top-level Stylelint `rules` entries.
+
+## Targeted pattern scope
+
+This rule targets Stylelint config modules such as `stylelint.config.ts`, `stylelint.config.mjs`, and `.stylelintrc.js`.
+
+It focuses on top-level exported config objects, including configs wrapped in `defineConfig(...)`.
+
+## What this rule reports
+
+Reports top-level rule entries configured as `null`, for example `"at-rule-no-unknown": null`.
+
+## Why this rule exists
+
+`null` entries hide rule intent in shared configs and can mask policy drift. Explicit rule values are easier to audit and maintain.
+
+## ❌ Incorrect
+
+```ts
+export default {
+    rules: {
+        "at-rule-no-unknown": null,
+    },
+};
+```
+
+## ✅ Correct
+
+```ts
+export default {
+    rules: {
+        "at-rule-no-unknown": true,
+    },
+};
+```
+
+## Behavior and migration notes
+
+This rule reports null rule entries and does not auto-fix because desired replacement values are policy-specific.
+
+## ESLint flat config example
+
+```ts
+import stylelint2 from "eslint-plugin-stylelint-2";
+
+export default [stylelint2.configs.configuration];
+```
+
+## When not to use it
+
+Do not use this rule if your team intentionally uses `null` to disable inherited rules in shared config files.
+
+## Package documentation
+
+Stylelint package documentation:
+
+> **Rule catalog ID:** R030
+
+## Further reading
+
+- [Stylelint rules](https://stylelint.io/user-guide/rules/list)

package/docs/rules/disallow-stylelint-overrides-runtime-options.md

@@ -0,0 +1,82 @@
+# disallow-stylelint-overrides-runtime-options
+
+Disallow runtime-only Stylelint options (`allowEmptyInput`, `cache`, `fix`) inside `overrides` entries.
+
+## Targeted pattern scope
+
+This rule targets Stylelint config modules such as `stylelint.config.ts`, `stylelint.config.mjs`, and `.stylelintrc.js`.
+
+It focuses on top-level exported config objects, including configs wrapped in `defineConfig(...)`.
+
+## What this rule reports
+
+This rule reports override entries that configure:
+
+- `allowEmptyInput`
+- `cache`
+- `fix`
+
+## Why this rule exists
+
+Stylelint documents these as runtime options that should not be overridden per-file. Keeping them inside override blocks creates confusing behavior and weakens execution-level policy.
+
+## ❌ Incorrect
+
+```ts
+export default {
+    overrides: [
+        {
+            files: ["**/*.scss"],
+            fix: true,
+            rules: {
+                "at-rule-no-unknown": null,
+            },
+        },
+    ],
+};
+```
+
+## ✅ Correct
+
+```ts
+export default {
+    overrides: [
+        {
+            files: ["**/*.scss"],
+            rules: {
+                "at-rule-no-unknown": null,
+            },
+        },
+    ],
+};
+```
+
+## Behavior and migration notes
+
+- This rule auto-fixes by removing the runtime-only option from each invalid override entry.
+- Use execution-time controls (`eslint --fix`, Stylelint CLI options, task-runner settings) for runtime behavior.
+
+## ESLint flat config example
+
+```ts
+import stylelint2 from "eslint-plugin-stylelint-2";
+
+export default [stylelint2.configs.configuration];
+```
+
+## When not to use it
+
+Do not use this rule if your team intentionally accepts override-local runtime behavior and understands the resulting execution coupling.
+
+## Package documentation
+
+Stylelint package documentation:
+
+> **Rule catalog ID:** R036
+
+## Further reading
+
+- [Stylelint `allowEmptyInput`](https://stylelint.io/user-guide/configure/#allowemptyinput)
+- [Stylelint `cache`](https://stylelint.io/user-guide/configure/#cache)
+- [Stylelint `fix`](https://stylelint.io/user-guide/configure/#fix)
+- [Stylelint `overrides`](https://stylelint.io/user-guide/configure/#overrides)

package/docs/rules/disallow-stylelint-processors.md

@@ -0,0 +1,62 @@
+# disallow-stylelint-processors
+
+Disallow configuring Stylelint's top-level `processors` option inside authored Stylelint config files.
+
+## Targeted pattern scope
+
+This rule targets Stylelint config modules such as `stylelint.config.ts`, `stylelint.config.mjs`, and `.stylelintrc.js`.
+
+It focuses on top-level exported config objects, including configs wrapped in `defineConfig(...)`.
+
+## What this rule reports
+
+This rule reports Stylelint config objects that include a top-level `processors` property.
+
+## Why this rule exists
+
+Processor pipelines are often legacy integration paths that hide parsing behavior and introduce brittle lint flows. Modern Stylelint usage favors explicit syntax selection and rule config composition.
+
+## ❌ Incorrect
+
+```ts
+export default {
+    processors: ["stylelint-processor-styled-components"],
+    rules: {},
+};
+```
+
+## ✅ Correct
+
+```ts
+export default {
+    rules: {},
+};
+```
+
+## Behavior and migration notes
+
+- This rule removes top-level `processors`.
+- It preserves the rest of the config object.
+- Prefer modern syntax-aware configuration and explicit file scoping.
+
+## ESLint flat config example
+
+```ts
+import stylelint2 from "eslint-plugin-stylelint-2";
+
+export default [stylelint2.configs.configuration];
+```
+
+## When not to use it
+
+Do not use this rule if your repository still relies on processor-based Stylelint integration and cannot migrate yet.
+
+## Package documentation
+
+Stylelint package documentation:
+
+> **Rule catalog ID:** R015
+
+## Further reading
+
+- [Stylelint configuring guide](https://stylelint.io/user-guide/configure/)

package/docs/rules/disallow-stylelint-relative-extends-paths.md

@@ -0,0 +1,61 @@
+# disallow-stylelint-relative-extends-paths
+
+Disallow relative-path entries in top-level Stylelint `extends` declarations.
+
+## Targeted pattern scope
+
+This rule targets Stylelint config modules such as `stylelint.config.ts`, `stylelint.config.mjs`, and `.stylelintrc.js`.
+
+It focuses on top-level exported config objects, including configs wrapped in `defineConfig(...)`.
+
+## What this rule reports
+
+Reports `extends` entries that start with `./`, `../`, `.\\`, or `..\\`.
+
+## Why this rule exists
+
+Relative path references in shared configs are fragile across package boundaries and monorepos. Package-based identifiers are more portable and predictable.
+
+## ❌ Incorrect
+
+```ts
+export default {
+    extends: ["../shared/stylelint.cjs"],
+    rules: {},
+};
+```
+
+## ✅ Correct
+
+```ts
+export default {
+    extends: ["stylelint-config-standard"],
+    rules: {},
+};
+```
+
+## Behavior and migration notes
+
+This rule reports relative-path entries and does not auto-fix because replacement identifiers are repository-specific.
+
+## ESLint flat config example
+
+```ts
+import stylelint2 from "eslint-plugin-stylelint-2";
+
+export default [stylelint2.configs.configuration];
+```
+
+## When not to use it
+
+Do not use this rule if your config architecture intentionally relies on relative extends references.
+
+## Package documentation
+
+Stylelint package documentation:
+
+> **Rule catalog ID:** R027
+
+## Further reading
+
+- [Stylelint extends](https://stylelint.io/user-guide/configure/#extends)

package/docs/rules/disallow-stylelint-relative-plugin-paths.md

@@ -0,0 +1,61 @@
+# disallow-stylelint-relative-plugin-paths
+
+Disallow relative-path entries in top-level Stylelint `plugins` declarations.
+
+## Targeted pattern scope
+
+This rule targets Stylelint config modules such as `stylelint.config.ts`, `stylelint.config.mjs`, and `.stylelintrc.js`.
+
+It focuses on top-level exported config objects, including configs wrapped in `defineConfig(...)`.
+
+## What this rule reports
+
+Reports `plugins` entries that start with `./`, `../`, `.\\`, or `..\\`.
+
+## Why this rule exists
+
+Relative plugin paths are brittle in shared configs and can break when package roots or workspace layouts change.
+
+## ❌ Incorrect
+
+```ts
+export default {
+    plugins: ["./plugins/local-stylelint-plugin.cjs"],
+    rules: {},
+};
+```
+
+## ✅ Correct
+
+```ts
+export default {
+    plugins: ["stylelint-order"],
+    rules: {},
+};
+```
+
+## Behavior and migration notes
+
+This rule reports relative-path entries and does not auto-fix because package replacement names are project-specific.
+
+## ESLint flat config example
+
+```ts
+import stylelint2 from "eslint-plugin-stylelint-2";
+
+export default [stylelint2.configs.configuration];
+```
+
+## When not to use it
+
+Do not use this rule if your repository intentionally loads local relative plugin modules.
+
+## Package documentation
+
+Stylelint package documentation:
+
+> **Rule catalog ID:** R028
+
+## Further reading
+
+- [Stylelint plugins](https://stylelint.io/user-guide/configure/#plugins)