prefer-stylelint-report-needless-disables

Require enabling Stylelint's reportNeedlessDisables config 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 when reportNeedlessDisables is:

missing
explicitly false
configured as an array whose primary option is not true

Why this rule exists

Stylelint can report disable comments that do not suppress any active finding. That helps teams remove stale disable comments instead of letting them accumulate as dead configuration noise.

❌ Incorrect

export default {
    rules: {
        "color-no-invalid-hex": true,
    },
};

✅ Correct

export default {
    reportNeedlessDisables: true,
    rules: {
        "color-no-invalid-hex": true,
    },
};

Behavior and migration notes

Missing properties are autofixed by inserting reportNeedlessDisables: true.
false values are autofixed to true.
Array-form values preserve secondary options while rewriting the primary option to true.

Additional examples

✅ Correct — keep secondary options

export default {
    reportNeedlessDisables: [true, { severity: "warning" }],
};

ESLint flat config example

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 allows needless disable comments to remain in place without reporting.

Package documentation

Stylelint package documentation:

Rule catalog ID: R005

Targeted pattern scope​

What this rule reports​

Why this rule exists​

❌ Incorrect​

✅ Correct​

Behavior and migration notes​

Additional examples​

✅ Correct — keep secondary options​

ESLint flat config example​

When not to use it​

Package documentation​

Further reading​