Fixme

NOTE: I no longer actively maintain this package. I'd love to get PRs to keep it going though!

Scan for NOTE, OPTIMIZE, TODO, HACK, XXX, FIXME, and BUG comments within your source, and print them to stdout so you can deal with them. This is similar to the rake notes task from Rails.

It ends up giving you an output like this:

Output is colored when printing to a terminal. Set NO_COLOR=1 to turn color off, or FORCE_COLOR=1 to keep it when piping.

Fixme currently scans your matching files line-by-line looking for annotations in the code. As such; multi-line annotation capturing is currently not supported. All annotations must be on the same line.

Fixme supports scanning for annotations in a variety of file types. The default file patterns it looks for are:

• JavaScript: **/*.js
• Makefile: Makefile
• Shell scripts: **/*.sh
• HTML: **/*.html
• CSS: **/*.css
• JSON: **/*.json
• Markdown: **/*.md
• Text files: **/*.txt
• YAML: **/*.yaml, **/*.yml
• SASS: **/*.scss
• LESS: **/*.less
• PHP: **/*.php
• Java: **/*.java
• Python: **/*.py
• Ruby: **/*.rb
• C++: **/*.cpp
• C#: **/*.cs
• Swift: **/*.swift
• Rust: **/*.rs
• Go: **/*.go
• Header files: **/*.h, **/*.hpp
• TypeScript: **/*.ts
• JSX: **/*.jsx
• TSX: **/*.tsx
• Vue.js: **/*.vue
• Perl: **/*.pl
• Lua: **/*.lua
• Groovy: **/*.groovy
• Scala: **/*.scala
• Kotlin: **/*.kt
• Dart: **/*.dart

Fixme requires Node.js 20.12 or newer. In order to use Fixme all you need to do is install it:

npm install -g fixme

Note: There really shouldn't be much reason to globally install it...

Require it:

var fixme = require("fixme");

And finally; configure it when you call it:

// All values below are Fixme default values unless otherwise overridden here.
fixme({
  path: process.cwd(),
  ignored_directories: ["node_modules/**", ".git/**", ".hg/**"],
  file_patterns: ["**/*.js", "Makefile", "**/*.sh"],
  file_encoding: "utf8",
  line_length_limit: 1000,
  skip: [],
});

You should then see some nice output when this is run:

• path/to/your/directory/file.js [4 messages]:
  [Line   1]  ✐ NOTE: This is here because sometimes an intermittent issue appears.
  [Line   7]  ↻ OPTIMIZE: This could be reworked to not do a O(N2) lookup.
  [Line   9]  ✓ TODO from John: Add a check here to ensure these are always strings.
  [Line  24]  ✄ HACK: I am doing something here that is horrible, but it works for now...
  [Line  89]  ✗ XXX: Let's do this better next time? It's bad.
  [Line 136]  ☠ FIXME: We sometimes get an undefined index in this array.
  [Line 211]  ☢ BUG: If the user inputs "Easter" we always output "Egg", even if they wanted a "Bunny".

fixme() returns a promise that resolves with the results once they are printed. To get the results without printing anything, use fixme.scan():

const results = await fixme.scan({ path: "src" });
// [{ path: "a.js", total_lines: 12, messages: [{ type: "todo", label: " ✓ TODO", line_number: 3, author: null, message: "..." }] }]

• path: The path to scan through for notes, defaults to process.cwd()
• ignored_directories: Glob patterns for directories to ignore. Passes these straight to minimatch so check there for more information on proper syntax.
• file_patterns: Glob patterns for files to scan. Also uses minimatch.
• file_encoding: The encoding the files scanned will be opened as.
• line_length_limit: The number of max characters a line can be before Fixme gives up and doen not scan it for matches. If a line is too long, the regular expression will take an extremely long time to finish. You have been warned!
• skip: List of check names to skip. Valid options: note, optimize, todo, hack, xxx, fixme, bug, line. line will disable the line length warning.

fixme --help

Using this as a GulpJS task is pretty simple, here is a very straight-forward "notes" task:

gulp.task("notes", fixme);

That, of course, assumes all of the defaults in Fixme are ok with you. If not, this is still pretty simple to configure and run as a Gulp task:

gulp.task("notes", function () {
  fixme({
    path: process.cwd(),
    ignored_directories: ["node_modules/**", ".git/**", ".hg/**"],
    file_patterns: ["**/*.js", "Makefile", "**/*.sh"],
    file_encoding: "utf8",
    line_length_limit: 1000,
  });
});

A code annotation needs to follow these rules to be picked up by Fixme:

• Must come right after a comment marker: //, /*, #, --, <!--, {{!, {{!--, {#, or * inside a block comment. Code can come before the comment.
• #, -- and * only count at the start of a line or after whitespace. // doesn't count after a colon, so URLs are not matched.
• Must have one of the words: NOTE, OPTIMIZE, TODO, HACK, XXX, FIXME, or BUG
• Can have an @ character before the word
• Can have an author in parentheses after the word
• The word must be upper case, or be followed by a colon. // todo: x and // TODO x are annotations, // todo list is not.
• Can have a message after the word. It ends at the comment closer, if there is one on the line.

You can have an author of a comment displayed via Fixme:

// NOTE(John Postlethwait): This comment will be shown as a note, and have an author!

  [Line 1]  ✐ NOTE from John Postlethwait: This comment will be shown as a note, and have an author!

Take a look at the test/fixtures/annotations.txt file, all of those comments in there are supported and expected to parse with Fixme.