oxlint-plugin-directive-comments

Lint your oxlint-disable and eslint-disable comments.

Oxlint reads both spellings, so this plugin does too. Seven rules are ports of eslint-plugin-eslint-comments with the same names and options. Two are new and only make sense for Oxlint.

It catches things like:

/* oxlint-disable no-undef */                  ← disable-enable-pair: never turned back on
const x = y; // eslint-disable-line            ← no-unlimited-disable: which rule?
// oxlint-disable-next-line no-console         ← require-description: why?
/* global $ */                                 ← no-unsupported-directive: Oxlint ignores this
// eslint-disable-next-line no-debugger        ← prefer-oxlint-directive: fixable to oxlint-

Install

npm i -D oxlint oxlint-plugin-directive-comments
pnpm add -D oxlint oxlint-plugin-directive-comments
yarn add -D oxlint oxlint-plugin-directive-comments
bun add -d oxlint oxlint-plugin-directive-comments

Use

oxlint.config.ts:

import { defineConfig } from "oxlint";
import directiveComments from "oxlint-plugin-directive-comments";

export default defineConfig({
  extends: [directiveComments.configs.recommended],
});

Or .oxlintrc.json. A string extends does not carry jsPlugins across (oxc#17320), so list the rules yourself:

{
  "jsPlugins": ["oxlint-plugin-directive-comments"],
  "rules": {
    "directive-comments/disable-enable-pair": "error",
    "directive-comments/no-aggregating-enable": "error",
    "directive-comments/no-duplicate-disable": "error",
    "directive-comments/no-unlimited-disable": "error",
    "directive-comments/no-unsupported-directive": "warn"
  }
}

That is what recommended enables. require-description is the rule people ask for by name, and it is one more line: "directive-comments/require-description": "error".

The same package loads in ESLint 9: plugins: { "directive-comments": directiveComments }, then enable rules under that prefix.

Rules

🔧 has an autofix. ✅ is in recommended.

| Rule | What it flags | 🔧 | ✅ | | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | --- | --- | | disable-enable-pair | A disable comment with no matching enable. | | ✅ | | no-aggregating-enable | One enable comment that closes several disable comments. | | ✅ | | no-duplicate-disable | Disabling a rule that an earlier comment already disabled. | | ✅ | | no-restricted-disable | disable comments for rules you list, with gitignore-style patterns. | | | | no-unlimited-disable | disable comments that do not name a rule. | | ✅ | | no-unsupported-directive | eslint, eslint-env, global, globals, and exported comments. Oxlint ignores them. | | ✅ | | no-use | Any directive comment, or any not in allow. | | | | prefer-oxlint-directive | eslint-disable and friends. Rewrites the prefix to oxlint-. | 🔧 | | | require-description | Directive comments without a -- reason. | | |

no-unsupported-directive is a warning in recommended because a project that still runs ESLint on the same files may need those comments. prefer-oxlint-directive stays off for the same reason: ESLint ignores oxlint- comments, so the fix would switch them off there.

Things worth knowing

• There is no no-inline-config rule. no-use with { "allow": [] } (the default) bans every directive comment, which is what oxc#15173 asks for.
• Oxlint honours // eslint-disable and // eslint-enable written as line comments. ESLint does not. This plugin treats them as directives everywhere, because Oxlint does.
• Oxlint reads -- reason and - reason as a description. ESLint only reads --. require-description accepts both; write -- if both linters run.
• Option lists such as ignore and allow match the directive exactly as written. To cover both spellings, list both: ["eslint-disable", "oxlint-disable"].
• Oxlint's own --report-unused-disable-directives can report the same comment disable-enable-pair does. That is two true statements about one comment, not a conflict.
• In Oxlint, reports land on the text between the comment delimiters, which is the one span the comment's own disable never covers. A /* oxlint-disable */ at the top of a file cannot hide the report about itself. Under ESLint the plugin reports at column -1, as the upstream plugin does.
• A directive can still hide reports about a different directive. In Oxlint, // oxlint-disable-next-line silences everything this plugin would say about a directive on the next line, and a /* oxlint-disable */ block silences reports about every comment below it, in both linters. Those are the directives doing their job.
• Oxlint also honours a /* oxlint-disable-line */ block comment that spans lines. ESLint ignores it. This plugin counts it.

Contributing

Read CONTRIBUTING.md. The short version: pnpm new-rule <name> scaffolds a rule with its test and doc page, PR titles are conventional commits like feat(require-description): add ignore option, and issues labelled good first issue are a fine place to start.

License

MIT