@maffelu/eslint-plugin-no-todo-advanced

Find // TODO/FIXME comments and only allow those that match an approved pattern (regex). By default, allows TODO: or FIXME: that include an issue number like #123456, but any pattern that can be expressed with regexp works.

Example (default behavior):

// ❌ Disallowed (no issue number)
// TODO: refactor this

// ✅ Allowed (has an issue number)
// TODO: #123456 refactor this

// ❌ Disallowed (FIXME without an issue number)
/* FIXME: investigate performance */

// ✅ Allowed (FIXME with an issue number)
/* FIXME: #987654 investigate performance */

Install

npm i -D @maffelu/eslint-plugin-no-todo-advanced

Usage (Flat Config)

You can register the plugin using either the scoped key ("@maffelu") or any custom alias you prefer (e.g. "plugin-todo-advanced").

ESM (eslint.config.js / .mjs)

// eslint.config.js (ESLint v9 flat config)
import * as pluginTodoAdvanced from "@maffelu/eslint-plugin-no-todo-advanced";

// Option A: Scoped key
export default [
  {
    plugins: { "@maffelu": pluginTodoAdvanced },
    rules: {
      "@maffelu/no-todo-advanced": "warn",
    },
  },
];

// Option B: Custom key/alias
// export default [
//   {
//     plugins: { "plugin-todo-advanced": pluginTodoAdvanced },
//     rules: {
//       "plugin-todo-advanced/no-todo-advanced": "warn",
//     },
//   },
// ];

CJS (eslint.config.cjs)

// eslint.config.cjs (ESLint v9 flat config)
const pluginTodoAdvanced = require("@maffelu/eslint-plugin-no-todo-advanced");

// Option A: Scoped key
module.exports = [
  {
    plugins: { "@maffelu": pluginTodoAdvanced },
    rules: {
      "@maffelu/no-todo-advanced": "warn",
    },
  },
];

// Option B: Custom key/alias
// module.exports = [
//   {
//     plugins: { "plugin-todo-advanced": pluginTodoAdvanced },
//     rules: {
//       "plugin-todo-advanced/no-todo-advanced": "warn",
//     },
//   },
// ];

Rule: @maffelu/no-todo-advanced

Disallows TODO/FIXME comments unless they match an approved regex.

• Default approved regex: ^\s*(?:TODO|FIXME)\s*:\s*#\d{3,}\b (e.g. // TODO: #123456 ...).
• Also supports an allow-list of substrings.

Options

[
  "warn",
  {
    "approvedRegex": "^\\s*(?:TODO|FIXME)\\s*:\\s*#\\d{3,}\\b",
    "allow": [],
    "caseSensitive": false
  }
]

• approvedRegex: string regex. You can pass either a plain pattern (e.g. "TODO: #\d+") or a slash-delimited one with flags (e.g. "/TODO\s*:\s*ALLOW\b/i").
• allow: array of substrings that, if present in the comment, will be accepted.
• caseSensitive: whether to treat matching as case-sensitive for the allow list and TODO/FIXME detection.

Examples

// ❌ Disallowed (no issue number)
// TODO: refactor this

// ✅ Allowed (has an issue number)
// TODO: #123456 refactor this

// ❌ Disallowed (FIXME without an issue number)
/* FIXME: investigate performance */

// ✅ Allowed (FIXME with an issue number)
/* FIXME: #987654 investigate performance */

With custom approvedRegex (e.g. /TODO\s*:\s*ALLOW\b/i):

// ✅ Allowed (matches custom pattern)
// TODO: ALLOW remove deprecated code

// ❌ Disallowed (does not match custom pattern)
// TODO: #123456 remove deprecated code

// ❌ Disallowed (does not match custom pattern)
/* TODO: remove this deprecated code */

• Custom approved regex config:

{
  plugins: { "@maffelu": pluginTodoAdvanced },
  rules: {
    "@maffelu/no-todo-advanced": [
      "warn",
      { "approvedRegex": "/TODO\\s*:\\s*ALLOW\\b/i" }
    ],
  },
}

// Using a custom key/alias
// {
//   plugins: { "plugin-todo-advanced": pluginTodoAdvanced },
//   rules: {
//     "plugin-todo-advanced/no-todo-advanced": [
//       "warn",
//       { "approvedRegex": "/TODO\\s*:\\s*ALLOW\\b/i" }
//     ],
//   },
// }

Troubleshooting

• If using a flat config and ESM, prefer a namespace import: import * as pluginTodoAdvanced from "@maffelu/eslint-plugin-no-todo-advanced".
• Ensure your Node version meets the engine requirement (>= 18.18.0).
• If you see a module resolution error about exports, make sure you are importing the package root (no deep imports) and that your package manager installed the latest version.

Development

• Build: npm run build
• Test: npm test

Publishing

First bump the module version

npm version patch   # 1.0.0 → 1.0.1
npm version minor   # 1.0.0 → 1.1.0
npm version major   # 1.0.0 → 2.0.0

Then tag it with the new version

git tag v1.0.1
git push --tags

Now publish it

npm publish