eslint-plugin-stylelint-2 1.0.9

package/docs/rules/require-stylelint-config-file-naming-convention.md

@@ -0,0 +1,61 @@
+# require-stylelint-config-file-naming-convention
+
+Require canonical `stylelint.config.*` naming for shared 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
+
+Reports Stylelint config files that are valid config targets but do not follow canonical `stylelint.config.*` naming.
+
+## Why this rule exists
+
+Canonical filenames improve discoverability in editors, scripts, and monorepos. Mixed `.stylelintrc*` and `stylelint.config.*` naming increases operational drift.
+
+## ❌ Incorrect
+
+```js
+// .stylelintrc.js
+export default {
+    rules: {},
+};
+```
+
+## ✅ Correct
+
+```ts
+// stylelint.config.ts
+export default {
+    rules: {},
+};
+```
+
+## Behavior and migration notes
+
+This rule reports non-canonical filenames and does not auto-fix because file renaming is outside safe text-fixer scope.
+
+## 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 standardizes on `.stylelintrc*` filenames.
+
+## Package documentation
+
+Stylelint package documentation:
+
+> **Rule catalog ID:** R035
+
+## Further reading
+
+- [Stylelint config formats](https://stylelint.io/user-guide/configure/)

package/docs/rules/require-stylelint-custom-syntax-in-overrides.md

@@ -0,0 +1,77 @@
+# require-stylelint-custom-syntax-in-overrides
+
+Require top-level `customSyntax` usage to be moved into scoped `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 top-level `customSyntax` declarations that are not mirrored by at least one override entry with a concrete `customSyntax` value.
+
+## Why this rule exists
+
+Global syntax declarations can accidentally affect unrelated file types. Declaring syntax inside overrides keeps parser behavior explicit and file-scoped.
+
+## ❌ Incorrect
+
+```ts
+export default {
+    customSyntax: "postcss-scss",
+    rules: {
+        "color-no-invalid-hex": true,
+    },
+};
+```
+
+## ✅ Correct
+
+```ts
+export default {
+    customSyntax: "postcss-scss",
+    overrides: [
+        {
+            customSyntax: "postcss-scss",
+            files: ["**/*.scss"],
+            rules: {
+                "at-rule-no-unknown": null,
+            },
+        },
+    ],
+    rules: {
+        "color-no-invalid-hex": true,
+    },
+};
+```
+
+## Behavior and migration notes
+
+- This rule reports unscoped top-level `customSyntax` usage.
+- It does not auto-fix because correct override file patterns are repository-specific.
+- Pair this with `disallow-stylelint-custom-syntax` for stricter top-level policy.
+
+## 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 applies one global syntax for all linted files.
+
+## Package documentation
+
+Stylelint package documentation:
+
+> **Rule catalog ID:** R020
+
+## Further reading
+
+- [Stylelint customSyntax](https://stylelint.io/user-guide/configure/#customsyntax)
+- [Stylelint overrides](https://stylelint.io/user-guide/configure/#overrides)

package/docs/rules/require-stylelint-extends-packages-installed.md

@@ -0,0 +1,61 @@
+# require-stylelint-extends-packages-installed
+
+Require top-level Stylelint `extends` package specifiers to be listed in workspace dependencies.
+
+## 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 package-backed `extends` entries that do not resolve to a declared dependency in the nearest workspace package.json.
+
+## Why this rule exists
+
+Shared Stylelint configs should reference installed packages explicitly. Missing dependency declarations create non-reproducible lint behavior across machines and CI jobs.
+
+## ❌ Incorrect
+
+```ts
+export default {
+    extends: ["stylelint-config-does-not-exist"],
+    rules: {},
+};
+```
+
+## ✅ Correct
+
+```ts
+export default {
+    extends: ["stylelint-config-standard"],
+    rules: {},
+};
+```
+
+## Behavior and migration notes
+
+This rule reports unresolved package references and does not auto-fix because dependency installation strategy is 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 repository intentionally resolves `extends` packages through non-package-manager mechanisms.
+
+## Package documentation
+
+Stylelint package documentation:
+
+> **Rule catalog ID:** R033
+
+## Further reading
+
+- [Stylelint extends](https://stylelint.io/user-guide/configure/#extends)

package/docs/rules/require-stylelint-overrides-configuration.md

@@ -0,0 +1,80 @@
+# require-stylelint-overrides-configuration
+
+Require each Stylelint `overrides` entry to include effective configuration content beyond `files` and optional `name`.
+
+## 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 only contain structural fields (`files` and optional `name`) and no effective config payload (for example `rules`, `customSyntax`, `extends`, `plugins`).
+
+## Why this rule exists
+
+Stylelint override entries are intended to apply specific configuration changes to a file subset. Entries without effective config content are misleading and increase maintenance noise.
+
+## ❌ Incorrect
+
+```ts
+export default {
+    overrides: [
+        {
+            files: ["**/*.scss"],
+            name: "SCSS files",
+        },
+    ],
+    rules: {
+        "color-no-invalid-hex": true,
+    },
+};
+```
+
+## ✅ Correct
+
+```ts
+export default {
+    overrides: [
+        {
+            files: ["**/*.scss"],
+            customSyntax: "postcss-scss",
+            rules: {
+                "at-rule-no-unknown": null,
+            },
+        },
+    ],
+    rules: {
+        "color-no-invalid-hex": true,
+    },
+};
+```
+
+## Behavior and migration notes
+
+- This rule reports override entries that contain no effective config payload.
+- It intentionally skips entries with spread elements (`...foo`) because static analysis cannot safely prove whether effective config content is present.
+- It does not auto-fix because the correct override payload is 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 repository intentionally keeps placeholder override entries as an intermediate migration step.
+
+## Package documentation
+
+Stylelint package documentation:
+
+> **Rule catalog ID:** R037
+
+## Further reading
+
+- [Stylelint `overrides`](https://stylelint.io/user-guide/configure/#overrides)

package/docs/rules/require-stylelint-overrides-files-array.md

@@ -0,0 +1,78 @@
+# require-stylelint-overrides-files-array
+
+Require each Stylelint `overrides` entry `files` value to be an explicit non-empty array of glob strings.
+
+## 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 `files` values that are not explicit non-empty string arrays, including:
+
+- scalar strings (`files: "**/*.scss"`)
+- empty arrays (`files: []`)
+- arrays containing non-string or empty elements
+
+## Why this rule exists
+
+Stylelint documents `overrides.files` as an array of glob patterns. Enforcing explicit arrays makes override scope predictable and easier to review at scale.
+
+## ❌ Incorrect
+
+```ts
+export default {
+    overrides: [
+        {
+            files: "**/*.scss",
+            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 reports invalid `overrides.files` array shape.
+- It does not auto-fix because converting dynamic patterns to explicit globs requires repository-specific intent.
+
+## 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 allows dynamic glob expressions for override matching.
+
+## Package documentation
+
+Stylelint package documentation:
+
+> **Rule catalog ID:** R038
+
+## Further reading
+
+- [Stylelint `overrides`](https://stylelint.io/user-guide/configure/#overrides)

package/docs/rules/require-stylelint-overrides-files.md

@@ -0,0 +1,83 @@
+# require-stylelint-overrides-files
+
+Require every Stylelint `overrides` entry to define a non-empty `files` matcher.
+
+## 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:
+
+- omit `files`, or
+- set `files` to an empty string, or
+- set `files` to an empty array.
+
+## Why this rule exists
+
+Overrides without explicit file scope are brittle and easy to misread. A non-empty `files` matcher makes override intent explicit and auditable.
+
+## ❌ Incorrect
+
+```ts
+export default {
+    overrides: [
+        {
+            rules: {
+                "at-rule-no-unknown": null,
+            },
+        },
+    ],
+    rules: {
+        "color-no-invalid-hex": true,
+    },
+};
+```
+
+## ✅ Correct
+
+```ts
+export default {
+    overrides: [
+        {
+            files: ["**/*.scss"],
+            rules: {
+                "at-rule-no-unknown": null,
+            },
+        },
+    ],
+    rules: {
+        "color-no-invalid-hex": true,
+    },
+};
+```
+
+## Behavior and migration notes
+
+- This rule reports invalid or missing `files` in override entries.
+- It does not auto-fix because correct glob scopes 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 repository intentionally permits non-standard override objects without explicit file globs.
+
+## Package documentation
+
+Stylelint package documentation:
+
+> **Rule catalog ID:** R019
+
+## Further reading
+
+- [Stylelint overrides](https://stylelint.io/user-guide/configure/#overrides)

package/docs/rules/require-stylelint-plugins-packages-installed.md

@@ -0,0 +1,61 @@
+# require-stylelint-plugins-packages-installed
+
+Require top-level Stylelint `plugins` package specifiers to be listed in workspace dependencies.
+
+## 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 package-backed `plugins` entries that do not resolve to a declared dependency in the nearest workspace package.json.
+
+## Why this rule exists
+
+Plugin references in shared config should be reproducible across contributors and CI. Missing plugin dependency declarations are a common source of broken lint runs.
+
+## ❌ Incorrect
+
+```ts
+export default {
+    plugins: ["stylelint-plugin-does-not-exist"],
+    rules: {},
+};
+```
+
+## ✅ Correct
+
+```ts
+export default {
+    plugins: ["stylelint-order"],
+    rules: {},
+};
+```
+
+## Behavior and migration notes
+
+This rule reports unresolved package references and does not auto-fix because dependency installation strategy is 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 repository intentionally loads plugins from non-standard dependency resolution paths.
+
+## Package documentation
+
+Stylelint package documentation:
+
+> **Rule catalog ID:** R034
+
+## Further reading
+
+- [Stylelint plugins](https://stylelint.io/user-guide/configure/#plugins)

package/docs/rules/require-stylelint-report-disables.md

@@ -0,0 +1,67 @@
+# require-stylelint-report-disables
+
+Require `reportDisables: true` 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
+
+Reports configs where `reportDisables` is missing or explicitly set to `false`.
+
+## Why this rule exists
+
+Disable-comment usage should stay visible during lint runs. Enabling `reportDisables` improves governance and reviewability in shared lint policy.
+
+## ❌ Incorrect
+
+```ts
+export default {
+    rules: {},
+};
+```
+
+```ts
+export default {
+    reportDisables: false,
+    rules: {},
+};
+```
+
+## ✅ Correct
+
+```ts
+export default {
+    reportDisables: true,
+    rules: {},
+};
+```
+
+## Behavior and migration notes
+
+This rule auto-fixes by inserting or setting `reportDisables: 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 suppresses disable-comment reporting.
+
+## Package documentation
+
+Stylelint package documentation:
+
+> **Rule catalog ID:** R029
+
+## Further reading
+
+- [Stylelint reportDisables](https://stylelint.io/user-guide/configure/#reportdisables)

package/docs/rules/require-stylelint-rules-object.md

@@ -0,0 +1,61 @@
+# require-stylelint-rules-object
+
+Require a 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 Stylelint config objects that do not define a top-level `rules` property.
+
+## Why this rule exists
+
+A missing `rules` object often indicates partial or placeholder config exports that are hard to review and reason about. Requiring an explicit `rules` object keeps lint intent visible.
+
+## ❌ Incorrect
+
+```ts
+export default {
+    reportDescriptionlessDisables: true,
+};
+```
+
+## ✅ Correct
+
+```ts
+export default {
+    reportDescriptionlessDisables: true,
+    rules: {},
+};
+```
+
+## Behavior and migration notes
+
+- This rule inserts `rules: {},` when missing.
+- The fixer preserves surrounding object structure and formatting style.
+
+## 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 treats Stylelint config files as non-rule-only wrappers and does not want to enforce explicit `rules` declarations.
+
+## Package documentation
+
+Stylelint package documentation:
+
+> **Rule catalog ID:** R017
+
+## Further reading
+
+- [Stylelint configuring guide](https://stylelint.io/user-guide/configure/)

package/docs/rules/sort-stylelint-extends.md

@@ -0,0 +1,61 @@
+# sort-stylelint-extends
+
+Enforce sorted 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` arrays whose string entries are not in ascending lexical order.
+
+## Why this rule exists
+
+Stable sorted arrays reduce diff noise and keep shared config layering predictable.
+
+## ❌ Incorrect
+
+```ts
+export default {
+    extends: ["stylelint-config-standard", "stylelint-config-recommended"],
+    rules: {},
+};
+```
+
+## ✅ Correct
+
+```ts
+export default {
+    extends: ["stylelint-config-recommended", "stylelint-config-standard"],
+    rules: {},
+};
+```
+
+## Behavior and migration notes
+
+This rule auto-fixes by sorting `extends` entries lexically.
+
+## 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 relies on non-lexical manual ordering for readability conventions.
+
+## Package documentation
+
+Stylelint package documentation:
+
+> **Rule catalog ID:** R025
+
+## Further reading
+
+- [Stylelint extends](https://stylelint.io/user-guide/configure/#extends)