Guide · 20

TODO scanner

Counts TODO, FIXME, HACK, XXX and BUG markers inside comments, by type and by file, with a ceiling for CI.

In one line

node scripts/20-todo-scan.mjs ./src --max 50

What it's for

TODOs and FIXMEs pile up and fade from the team's memory. This script counts them, by type and by file, so you can decide which to handle before a release. It only counts markers located inside a comment: a string that contains "TODO" is not counted.

Before you start

  • A code folder. node_modules, .git, build folders and binary files are skipped.

Step by step

  1. Take inventory:
    node scripts/20-todo-scan.mjs ./src
    
  2. Look at the busiest files (shown at the end of the report): they are often where technical debt lives.
  3. For a dashboard or a script, use --json.

Reading the output

The markers: TODO (to do), FIXME (broken or wrong), HACK (workaround), XXX (careful), BUG (known defect). Each line gives file:line and the text.

Automating it

Set a ceiling: --max 50 fails CI if the total goes above it, so debt cannot grow without someone deciding it should.

Pitfalls

  • A ceiling set too low on day one will be worked around: start from the current total and bring it down.
  • A TODO with no description helps nobody: write what needs doing and why.

This guide goes with a free script (MIT license). Try it on a copy of your data first.