code-notes v.1.0.3

Fixed an issue that caused text that contains any of the catch words to be parsed.

Make sure we have always a colon after the catch words

code-notes v1.0.2

In this quick patch i have addressed the following issues:

• Being able to include only certain patterns with the -i flag
• Improve filtering by excluding directory patterns first then file patterns
• Improve default exclusion lists with more file extensions and directories

code-notes v1.0.0

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:

• Flexibility in defining the source scanning directory
• The ability to pass exclude patterns that are compatible with multimatch
• The ability to read exclusion list from a .gitignore file

It ends up giving you an output like this:

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)
    -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)

• source: The path to scan through for notes, defaults to process.cwd()
• patterns: Glob patterns for files directories to ignore. Passes these straight to multimatch so check there for more information on proper syntax.
• ignoreHidden: Define if you want to ignore hidden files and directories. Defaults to true as all paths will be scanned.
• encoding: The encoding the files scanned will be opened as.
• lineLength: 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!
• gitIgnore: Path to your .gitignore file. The exclusion patterns will be automatically read from there and merged with your defined patterns if found.

Deep dive into patterns

Globbing patterns

• * matches any number of characters, but not /
• ? matches a single character, but not /
• ** matches any number of characters, including /, as long as it's the only thing in a path part
• {} allows for a comma-separated list of "or" expressions

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 (John Postlethwait): 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 (John Postlethwait): 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 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".

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

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 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"];

The object should contain the following fields:

• regex: this is used to extract the line containing the annotation
• label: this defines what will be printed in the console
• colorer: this controls the visual display of the message and can be customised with any valid chalk option

Writing Comments for Use With Fixme

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

• Can be preceeded by 0 to n number of characters, this includes the comment characters // and /*
• Must have one of the words: NOTE, OPTIMIZE, TODO, HACK, XXX, FIXME, or BUG
• Can have 0 to n space characters
• Can have an author in parenthesis after the above word, and before a colon (:)
• Can have 0 to n space characters
• Must be followed by a colon (:)
• Can have 0 to n space characters
• Should have a message of 0 to n characters for the note

Displaying Authors

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!