Home

Awesome

code-notes

code-notes is a node.js version of Rails' "rake notes" functionality. It allows you to put comments in your code and then have them annotated across your whole project.

code-notes is based on two npm modules, mainly forked from fixme but also inspired by node-notes. The main differences in this module is:

It ends up giving you an output like this:

code-notes also exits with proper error codes in case you want to use that in an integration workflow. It will terminate with an error code if any annotations are found.

Installation:

npm install code-notes -g

CLI Usage

notes --help

Options:

 Usage: notes [options]

  Tool to summarise all code annotation like TODO or FIXME

  Options:

    -h, --help               output usage information
    -V, --version            output the version number
    -s, --source [dir]       root directory to be included only for checks (default: current working directory)
    -x, --patterns [dir]     Path patterns to exclude (default: include all files and directories)
    -e, --encoding [type]    file encoding to be scanned (default: utf8)
    -i, --include [dir]      Path patterns to include only (default: include all files and directories). Note that include patterns will overwrite any exclude patterns
    -l, --line-length <n>    number of max characters a line (default: 1000)
    -h, --ignore-hidden <n>  ignore hidden files (default: false)
    -g, --git-ignore <n>     ignore patterns from your .gitignore file. This paramter accepts the path for the .gitIgnore file (default: false | no .gitignore is read

Configure Options (In More Detail)

Deep dive into patterns

Globbing patterns

Note that you are defining exclusion patterns, no need to add the negation operator ! in front of each pattern as it will be added automatically.

Directories exclusion

An important thing to take into consideration when defining exclusion patterns for directories is that you need to make sure to append a trailing backslash / to the directory path. For example:

# Exclude node_modules
notes -x node_modules/

# Exclude folder `src/lib`
notes -x src/lib/

This pattern should also be followed inside of your .gitignore file, so make sure you edit that accordingly

What It Does:

For example, if a file contained these lines somewhere in it:

// NOTE: This is the sample output for a note!
// OPTIMIZE (Mr Author): This is the sample output for an optimize with an author!
// TODO: This is the sample output for a todo!
// HACK: This is the sample output for a hack! Don't commit hacks!
// XXX: This is the sample output for a XXX! XXX's need attention too!
// FIXME (Mr Author): This is the sample output for a fixme! Seriously fix this...
// BUG: This is the sample output for a bug! Who checked in a bug?!

Those comments would be annotated as:

• path/to/your/directory/file.js [7 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 Mr Author: 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".

Example Usage


# Exclude any pattern inside of .gitignore file in the same path as the script is run and ignore any hidden files and folders
notes -g .gitignore -h true
# Exclude any file under the src directory and node_modules and any file with .md extension
notes -x src/ -x -x node_modules/ -x *.md
# Only scan .md files
notes -i "*.md"

Important: For some reason that i still cant figure out, some extensions like .md .html have to be wrapped with ". So if your pattern does not seem to work at first, try to wrap it with quotes

Extending code-notes

code-notes 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. However, if you wish to define more annotations to be extracted, this can be easily done by extending the definitions in lib/messageChecks.js. An example for an annotation:

todo: {
	regex: /[\/\/][\/\*]\s*TODO\s*(?:\(([^:]*)\))*\s*:?\s*(.*)/i,
	label: ' ✓ TODO',
	colorer: chalk.magenta
}

Ignoring files

Certain file extensions and directories are skipped from being scanned. They are defined in lib/notes.js

const BAD_EXTENSIONS = ["!*.jpg", "!*.jpeg", "!*.mov", "!*.mp3", "!*.gif", "!*.png", "!*.log", "!*.bin", "!*.psd", "!*.swf", "!*.fla", "!*.ico", "!*.jar", "!*.war", "!*.ear", "!*.zip", "!*.tar.gz", "!*.rar"];
const BAD_DIRECTORIES= ["!.git/**", "!.sass-cache/**", "!coverage/**"]

The object should contain the following fields:

Writing Comments for Use With Fixme

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

Displaying Authors

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

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

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