eslint-plugin-stylelint-2 1.0.9

package/docs/rules/getting-started.md

@@ -0,0 +1,130 @@
+---
+title: Getting Started
+description: Enable eslint-plugin-stylelint-2 quickly in Flat Config.
+---
+
+# Getting Started
+
+Install the plugin and Stylelint:
+
+```bash
+npm install --save-dev eslint-plugin-stylelint-2 eslint stylelint
+```
+
+Then enable the recommended preset:
+
+```ts
+import stylelint2 from "eslint-plugin-stylelint-2";
+
+export default [
+    ...stylelint2.configs.recommended,
+];
+```
+
+## What `recommended` includes
+
+`recommended` returns an array of flat config entries, not a single object.
+
+It currently adds:
+
+1. a CSS-targeted config that enables `stylelint-2/stylelint`
+2. a config-file-targeted config that enables the Stylelint config authoring rules
+
+## Stylelint bridge only
+
+If you only want the Stylelint bridge for stylesheet files:
+
+```ts
+import stylelint2 from "eslint-plugin-stylelint-2";
+
+export default [
+    stylelint2.configs.stylelintOnly,
+];
+```
+
+## Stylelint config files only
+
+If you only want the config-authoring rules and no stylesheet bridge:
+
+```ts
+import stylelint2 from "eslint-plugin-stylelint-2";
+
+export default [
+    stylelint2.configs.configuration,
+];
+```
+
+Legacy aliases remain supported:
+
+- `stylelint2.configs.stylesheets` → `stylelint2.configs.stylelintOnly`
+- `stylelint2.configs.configs` → `stylelint2.configs.configuration`
+
+That preset currently enables:
+
+- `stylelint-2/disallow-stylelint-allow-empty-input`
+- `stylelint-2/disallow-stylelint-configuration-comment`
+- `stylelint-2/disallow-stylelint-custom-syntax`
+- `stylelint-2/disallow-stylelint-default-severity`
+- `stylelint-2/disallow-stylelint-duplicate-extends`
+- `stylelint-2/disallow-stylelint-duplicate-plugins`
+- `stylelint-2/disallow-stylelint-duplicate-rule-option-values`
+- `stylelint-2/disallow-stylelint-empty-rules-object`
+- `stylelint-2/disallow-stylelint-ignore-disables`
+- `stylelint-2/disallow-stylelint-ignore-files`
+- `stylelint-2/disallow-stylelint-null-rule-config`
+- `stylelint-2/disallow-stylelint-overrides-runtime-options`
+- `stylelint-2/disallow-stylelint-processors`
+- `stylelint-2/disallow-stylelint-relative-extends-paths`
+- `stylelint-2/disallow-stylelint-relative-plugin-paths`
+- `stylelint-2/prefer-stylelint-cache`
+- `stylelint-2/prefer-stylelint-define-config`
+- `stylelint-2/prefer-stylelint-extends-array`
+- `stylelint-2/prefer-stylelint-fix`
+- `stylelint-2/prefer-stylelint-formatter`
+- `stylelint-2/prefer-stylelint-plugins-array`
+- `stylelint-2/prefer-stylelint-report-descriptionless-disables`
+- `stylelint-2/prefer-stylelint-report-invalid-scope-disables`
+- `stylelint-2/prefer-stylelint-report-needless-disables`
+- `stylelint-2/prefer-stylelint-report-unscoped-disables`
+- `stylelint-2/require-stylelint-custom-syntax-in-overrides`
+- `stylelint-2/require-stylelint-config-file-naming-convention`
+- `stylelint-2/require-stylelint-extends-packages-installed`
+- `stylelint-2/require-stylelint-overrides-configuration`
+- `stylelint-2/require-stylelint-overrides-files-array`
+- `stylelint-2/require-stylelint-overrides-files`
+- `stylelint-2/require-stylelint-plugins-packages-installed`
+- `stylelint-2/require-stylelint-report-disables`
+- `stylelint-2/require-stylelint-rules-object`
+- `stylelint-2/sort-stylelint-extends`
+- `stylelint-2/sort-stylelint-plugins`
+- `stylelint-2/sort-stylelint-rule-keys`
+
+## Adding Stylelint options
+
+Pass rule options when you need a custom syntax or an explicit config file:
+
+```ts
+import stylelint2 from "eslint-plugin-stylelint-2";
+
+export default [
+    {
+        ...stylelint2.configs.stylelintOnly,
+        rules: {
+            "stylelint-2/stylelint": [
+                "error",
+                {
+                    configFile: "./stylelint.config.mjs",
+                    customSyntax: "postcss-scss",
+                    ignoreDisables: true,
+                },
+            ],
+        },
+    },
+];
+```
+
+## When to use ESLint + Stylelint together
+
+Use this plugin when you want ESLint to be the single command that reports and fixes both JavaScript/TypeScript issues and stylesheet issues.
+
+If your team already runs Stylelint separately and is happy with that split, this plugin may be unnecessary overhead.

package/docs/rules/overview.md

@@ -0,0 +1,99 @@
+---
+title: Overview
+description: Overview of eslint-plugin-stylelint-2 and its Stylelint-to-ESLint workflow.
+---
+
+# eslint-plugin-stylelint-2
+
+`eslint-plugin-stylelint-2` lets you run Stylelint inside ESLint for CSS files and author Stylelint config files with a more predictable typed setup.
+
+The current rule set focuses on three high-value workflows:
+
+- surface Stylelint diagnostics through ESLint with autofix support
+- disallow execution-only Stylelint config options that belong in the runner, not the shared config object
+- disallow shared-config severity and file-ignore options that hide lint-policy changes globally
+- standardize modern `stylelint-define-config` usage in Stylelint config modules
+- require Stylelint config files to report disable comments that lack a reason
+- require the full family of Stylelint disable-comment reporting safeguards in config files
+
+## Installation
+
+```bash
+npm install --save-dev eslint-plugin-stylelint-2 eslint stylelint
+```
+
+## Quick start
+
+```ts
+import stylelint2 from "eslint-plugin-stylelint-2";
+
+export default [
+    ...stylelint2.configs.recommended,
+];
+```
+
+`recommended` expands to two file-scoped flat config entries:
+
+- one for CSS files using ESLint's `css/css` language
+- one for Stylelint config files such as `stylelint.config.ts`
+
+## Included presets
+
+| Preset                                                            | Purpose                                                       |
+| ----------------------------------------------------------------- | ------------------------------------------------------------- |
+| [`stylelint2.configs.recommended`](./presets/recommended.md)      | Stylesheet linting plus Stylelint config authoring guidance   |
+| [`stylelint2.configs.stylelintOnly`](./presets/stylelint-only.md) | Only run the Stylelint bridge workflow for stylesheet files   |
+| [`stylelint2.configs.configuration`](./presets/configuration.md)  | Only lint Stylelint config modules, with no stylesheet bridge |
+| [`stylelint2.configs.all`](./presets/all.md)                      | Enable every preset entry currently shipped by this plugin    |
+
+Legacy aliases remain supported:
+
+- `stylelint2.configs.stylesheets` → `stylelint2.configs.stylelintOnly`
+- `stylelint2.configs.configs` → `stylelint2.configs.configuration`
+
+## Included rules
+
+- [`stylelint`](./stylelint.md)
+- [`disallow-stylelint-allow-empty-input`](./disallow-stylelint-allow-empty-input.md)
+- [`disallow-stylelint-configuration-comment`](./disallow-stylelint-configuration-comment.md)
+- [`disallow-stylelint-custom-syntax`](./disallow-stylelint-custom-syntax.md)
+- [`disallow-stylelint-default-severity`](./disallow-stylelint-default-severity.md)
+- [`disallow-stylelint-duplicate-extends`](./disallow-stylelint-duplicate-extends.md)
+- [`disallow-stylelint-duplicate-plugins`](./disallow-stylelint-duplicate-plugins.md)
+- [`disallow-stylelint-duplicate-rule-option-values`](./disallow-stylelint-duplicate-rule-option-values.md)
+- [`disallow-stylelint-empty-rules-object`](./disallow-stylelint-empty-rules-object.md)
+- [`disallow-stylelint-ignore-disables`](./disallow-stylelint-ignore-disables.md)
+- [`disallow-stylelint-ignore-files`](./disallow-stylelint-ignore-files.md)
+- [`disallow-stylelint-null-rule-config`](./disallow-stylelint-null-rule-config.md)
+- [`disallow-stylelint-overrides-runtime-options`](./disallow-stylelint-overrides-runtime-options.md)
+- [`disallow-stylelint-processors`](./disallow-stylelint-processors.md)
+- [`disallow-stylelint-relative-extends-paths`](./disallow-stylelint-relative-extends-paths.md)
+- [`disallow-stylelint-relative-plugin-paths`](./disallow-stylelint-relative-plugin-paths.md)
+- [`prefer-stylelint-cache`](./prefer-stylelint-cache.md)
+- [`prefer-stylelint-define-config`](./prefer-stylelint-define-config.md)
+- [`prefer-stylelint-extends-array`](./prefer-stylelint-extends-array.md)
+- [`prefer-stylelint-fix`](./prefer-stylelint-fix.md)
+- [`prefer-stylelint-formatter`](./prefer-stylelint-formatter.md)
+- [`prefer-stylelint-plugins-array`](./prefer-stylelint-plugins-array.md)
+- [`prefer-stylelint-report-descriptionless-disables`](./prefer-stylelint-report-descriptionless-disables.md)
+- [`prefer-stylelint-report-invalid-scope-disables`](./prefer-stylelint-report-invalid-scope-disables.md)
+- [`prefer-stylelint-report-needless-disables`](./prefer-stylelint-report-needless-disables.md)
+- [`prefer-stylelint-report-unscoped-disables`](./prefer-stylelint-report-unscoped-disables.md)
+- [`require-stylelint-custom-syntax-in-overrides`](./require-stylelint-custom-syntax-in-overrides.md)
+- [`require-stylelint-config-file-naming-convention`](./require-stylelint-config-file-naming-convention.md)
+- [`require-stylelint-extends-packages-installed`](./require-stylelint-extends-packages-installed.md)
+- [`require-stylelint-overrides-configuration`](./require-stylelint-overrides-configuration.md)
+- [`require-stylelint-overrides-files-array`](./require-stylelint-overrides-files-array.md)
+- [`require-stylelint-overrides-files`](./require-stylelint-overrides-files.md)
+- [`require-stylelint-plugins-packages-installed`](./require-stylelint-plugins-packages-installed.md)
+- [`require-stylelint-report-disables`](./require-stylelint-report-disables.md)
+- [`require-stylelint-rules-object`](./require-stylelint-rules-object.md)
+- [`sort-stylelint-extends`](./sort-stylelint-extends.md)
+- [`sort-stylelint-plugins`](./sort-stylelint-plugins.md)
+- [`sort-stylelint-rule-keys`](./sort-stylelint-rule-keys.md)
+
+## Next steps
+
+- Read [Getting Started](./getting-started.md) for copy-paste setup examples.
+- Review [Presets](./presets/index.md) to pick the right rollout path.
+- Open each rule page before enabling stricter adoption in a larger codebase.

package/docs/rules/prefer-stylelint-cache.md

@@ -0,0 +1,79 @@
+# prefer-stylelint-cache
+
+Prefer enabling Stylelint's top-level `cache` option in authored Stylelint config files.
+
+This rule is intentionally excluded from `stylelint2.configs.recommended` because it encodes an opinionated operational default rather than a broadly applicable config-hygiene rule.
+
+## 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 omit `cache`, or configure it as a disabled value.
+
+## Why this rule exists
+
+If your team consistently runs Stylelint with caching enabled, an explicit top-level `cache` setting makes that default visible in the shared config instead of leaving it implicit in scattered scripts.
+
+This rule is opinionated. It is useful when you want config files to advertise that fast repeated lint runs are part of the default workflow.
+
+## ❌ Incorrect
+
+```ts
+export default {
+    rules: {},
+};
+```
+
+## ✅ Correct
+
+```ts
+export default {
+    cache: true,
+    rules: {},
+};
+```
+
+## Behavior and migration notes
+
+- This rule auto-fixes missing or disabled top-level `cache` configuration to `cache: true`.
+- It preserves the rest of the config object.
+- Use this rule only when cache-on-by-default is a deliberate repository policy.
+
+## Additional examples
+
+### ✅ Correct — cache policy at invocation level
+
+```json
+{
+    "scripts": {
+        "lint:stylelint": "stylelint --cache \"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 prefers cache behavior to stay entirely at invocation scope or wants different runners to choose different cache strategies.
+
+## Package documentation
+
+Stylelint package documentation:
+
+> **Rule catalog ID:** R012
+
+## Further reading
+
+- [Stylelint configuring guide](https://stylelint.io/user-guide/configure/#cache)
+- [Stylelint cache option](https://stylelint.io/user-guide/options/#cache)

package/docs/rules/prefer-stylelint-define-config.md

@@ -0,0 +1,90 @@
+# prefer-stylelint-define-config
+
+Prefer wrapping exported Stylelint config objects in `defineConfig()` from `stylelint-define-config`.
+
+## Targeted pattern scope
+
+This rule targets direct default object exports in Stylelint config files such as `stylelint.config.ts` and `.stylelintrc.js`.
+
+It intentionally focuses on the narrow case that can be autofixed safely.
+
+## What this rule reports
+
+This rule reports `export default { ... }` object exports in Stylelint config files when the object is not wrapped in `defineConfig(...)`.
+
+## Why this rule exists
+
+`defineConfig()` makes the intent of a Stylelint config module explicit and improves tooling support for config authoring.
+
+The helper also gives teams a single recognizable pattern for authored config modules instead of a mix of raw objects and helper-wrapped objects.
+
+## ❌ Incorrect
+
+```ts
+export default {
+    rules: {
+        "color-no-invalid-hex": true,
+    },
+};
+```
+
+## ✅ Correct
+
+```ts
+import { defineConfig } from "stylelint-define-config";
+
+export default defineConfig({
+    rules: {
+        "color-no-invalid-hex": true,
+    },
+});
+```
+
+## Behavior and migration notes
+
+- The current autofix rewrites direct object exports only.
+- The rule does not try to rewrite CommonJS config modules.
+- The rule does not try to rewrite `export default config` when `config` is declared elsewhere.
+
+That restraint is deliberate. Broad config rewrites are easier to get wrong than direct object-export fixes.
+
+## Additional examples
+
+### ✅ Correct — already wrapped export
+
+```ts
+import { defineConfig } from "stylelint-define-config";
+
+const config = defineConfig({
+    rules: {
+        "color-no-invalid-hex": true,
+    },
+});
+
+export default config;
+```
+
+## 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 project intentionally keeps Stylelint configs in CommonJS or uses a custom config factory that should stay unchanged.
+
+## Package documentation
+
+Stylelint package documentation:
+
+> **Rule catalog ID:** R002
+
+## Further reading
+
+- [stylelint-define-config](https://www.npmjs.com/package/stylelint-define-config)
+- [Stylelint configuration guide](https://stylelint.io/user-guide/configure)

package/docs/rules/prefer-stylelint-extends-array.md

@@ -0,0 +1,61 @@
+# prefer-stylelint-extends-array
+
+Prefer array form for 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` when it is defined as a single string instead of an array.
+
+## Why this rule exists
+
+Array form is easier to append, reorder, and review safely in shared config files.
+
+## ❌ Incorrect
+
+```ts
+export default {
+    extends: "stylelint-config-standard",
+    rules: {},
+};
+```
+
+## ✅ Correct
+
+```ts
+export default {
+    extends: ["stylelint-config-standard"],
+    rules: {},
+};
+```
+
+## Behavior and migration notes
+
+This rule auto-fixes scalar string form to a single-entry array.
+
+## 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 enforces scalar `extends` syntax in every Stylelint config file.
+
+## Package documentation
+
+Stylelint package documentation:
+
+> **Rule catalog ID:** R021
+
+## Further reading
+
+- [Stylelint extends](https://stylelint.io/user-guide/configure/#extends)

package/docs/rules/prefer-stylelint-fix.md

@@ -0,0 +1,79 @@
+# prefer-stylelint-fix
+
+Prefer enabling Stylelint's top-level `fix` option 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 omit `fix`, or configure it with a disabled value.
+
+## Why this rule exists
+
+If your repository expects Stylelint autofix to be on by default, an explicit top-level `fix` setting makes that operational choice visible and consistent.
+
+This rule is intentionally opinionated and best suited for repositories that want shared Stylelint config files to declare autofix-on behavior directly.
+
+This rule is intentionally excluded from `stylelint2.configs.recommended` because it encodes an opinionated operational default rather than a broadly applicable config-hygiene rule.
+
+## ❌ Incorrect
+
+```ts
+export default {
+    rules: {},
+};
+```
+
+## ✅ Correct
+
+```ts
+export default {
+    fix: true,
+    rules: {},
+};
+```
+
+## Behavior and migration notes
+
+- This rule auto-fixes missing or disabled top-level `fix` configuration to `fix: true`.
+- Existing enabled values such as `"strict"` and `"lax"` are accepted.
+- Use this rule only when enabling autofix in shared config is an intentional repository policy.
+
+## Additional examples
+
+### ✅ Correct — execution controls autofix
+
+```json
+{
+    "scripts": {
+        "lint:styles": "eslint \"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 wants autofix to stay an invocation-only decision or needs different fix modes across environments.
+
+## Package documentation
+
+Stylelint package documentation:
+
+> **Rule catalog ID:** R011
+
+## Further reading
+
+- [Stylelint configuring guide](https://stylelint.io/user-guide/configure/#fix)
+- [Stylelint autofix documentation](https://stylelint.io/user-guide/options/#fix)

package/docs/rules/prefer-stylelint-formatter.md

@@ -0,0 +1,80 @@
+# prefer-stylelint-formatter
+
+Prefer explicit top-level Stylelint `formatter` configuration 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 omit `formatter`, or configure it with an unusable empty string.
+
+## Why this rule exists
+
+If your team wants Stylelint output shape to be explicit across runners, an explicit shared `formatter` setting keeps that policy visible in the config instead of burying it in task wiring.
+
+This is an opinionated rule. It is useful only when consistent formatter selection is part of your repository policy.
+
+This rule is intentionally excluded from `stylelint2.configs.recommended` because it encodes an opinionated operational default rather than a broadly applicable config-hygiene rule.
+
+## ❌ Incorrect
+
+```ts
+export default {
+    rules: {},
+};
+```
+
+## ✅ Correct
+
+```ts
+export default {
+    formatter: "json",
+    rules: {},
+};
+```
+
+## Behavior and migration notes
+
+- This rule reports missing or unusable top-level `formatter` configuration.
+- It does not auto-fix because the correct formatter choice is repository-specific.
+- Non-literal formatter expressions are accepted to avoid false positives in JavaScript-based config modules.
+
+## Additional examples
+
+### ✅ Correct — formatter belongs in the runner
+
+```ts
+await stylelint.lint({
+    code,
+    formatter: "string",
+});
+```
+
+## 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 prefers formatter choice to remain purely at invocation scope.
+
+## Package documentation
+
+Stylelint package documentation:
+
+> **Rule catalog ID:** R007
+
+## Further reading
+
+- [Stylelint configuring guide](https://stylelint.io/user-guide/configure/#formatter)
+- [Stylelint Node API](https://stylelint.io/user-guide/node-api/)

package/docs/rules/prefer-stylelint-plugins-array.md

@@ -0,0 +1,61 @@
+# prefer-stylelint-plugins-array
+
+Prefer array form for 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` when it is defined as a single string instead of an array.
+
+## Why this rule exists
+
+Array form makes plugin composition deterministic and easier to maintain in shared configuration.
+
+## ❌ Incorrect
+
+```ts
+export default {
+    plugins: "stylelint-order",
+    rules: {},
+};
+```
+
+## ✅ Correct
+
+```ts
+export default {
+    plugins: ["stylelint-order"],
+    rules: {},
+};
+```
+
+## Behavior and migration notes
+
+This rule auto-fixes scalar string form to a single-entry array.
+
+## 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 enforces scalar `plugins` syntax.
+
+## Package documentation
+
+Stylelint package documentation:
+
+> **Rule catalog ID:** R022
+
+## Further reading
+
+- [Stylelint plugins](https://stylelint.io/user-guide/configure/#plugins)