npm package: @maffelu/eslint-plugin-no-todo-advanced
Description: ESLint plugin that warns on TODO/FIXME comments with advanced options
Latest version: 1.0.3

# @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):

```ts
// ❌ 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

```bash
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)

```js
// 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)

```js
// 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

```json
[
  "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

```ts
// ❌ 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`):

```ts
// ✅ 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:

```js
{
  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
```