complete re-write of the main fork

Author: ahmadassaf

.gitignore

@@ -1 +1,44 @@
-node_modules
+# Logs
+logs
+*.log
+
+npm-debug.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (http://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directory
+node_modules/
+
+# Users Environment Variables
+.lock-wscript
+
+cache
+
+# Optional npm cache directory
+.npm
+
+# Optional REPL history
+.node_repl_history
+
+# sonar relevant files
+.sonar
+
+coverage/

.notesrc

@@ -1,34 +1,163 @@
-node-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. Uses local ``.gitignore`` to ignore files or default ignore list.
+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](https://github.com/JohnPostlethwait/fixme) but also inspired by [node-notes](https://github.com/stephenb/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](https://github.com/sindresorhus/multimatch)
+ - The ability to read exclusion list from a `.gitignore` file
+
+It ends up giving you an output like this:
+
+![](http://i.imgur.com/OXsTtCZ.png)
 
 ### Installation:
 
-    npm install notes -g
+    npm install code-notes -g
+
+### CLI Usage ###
+
+```sh
+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](https://github.com/sindresorhus/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:
+
+```bash
+# Exclude node_modules
+notes -x node_modules/
 
-### Usage:
+# Exclude folder `src/lib`
+notes -x src/lib/
+```
 
-    $ notes              # will search for notes in cwd
-    $ notes .            # will search for notes in cwd considers .gitignore to ignore files
-    $ notes lib/ test/   # will search only in lib and test
+> 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:
 
-    code...
-    # NOTE: This line should get annoated by Notes.
-    # OPTIMIZE Make things faster!
+```
+// 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?!
+```
 
-    more code...
-    # TODO: Annotate your tasks.
+Those comments would be annotated as:
 
-    yet more code...
-    # FIXME: Keep up with things to fix.
+```
+• 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".
+```
 
-Those comments would be annotated as:
+### Example Usage
+
+```bash
+
+# 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:
+
+```javascript
+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`
+
+```javascript
+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](https://www.npmjs.com/package/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:
+
+```javascript
+// NOTE(John Postlethwait): This comment will be shown as a note, and have an author!
+```
 
-    * /path/to/my/file
-    Line 8:    ✐ NOTE This line should get annoated by Notes.
-    Line 9:   ↘ OPTIMIZE Make things faster!
-    Line 10:   ✓ TODO Annotate your tasks.
-    Line 11:   ☂ FIXME Keep up with things to fix.
+```shell
+  [Line 1]  ✐ NOTE from John Postlethwait: This comment will be shown as a note, and have an author!
+```

Cakefile

@@ -1,49 +1,22 @@
 #!/usr/bin/env node
 
-/**
- * Core dependencies.
- */
-var fs = require('fs');
-var path = require('path');
+"use strict";
 
-/**
- * Notes.
- *
- * @type {Function}
- */
-var Notes = require('../lib/notes');
+const program = require('commander');
 
-/**
- * Argv.
- *
- * @type {Array}
- */
-var argv = process.argv.slice(2, process.argv.length);
+const Notes   = require('../lib/notes');
 
-/**
- * Current working directory.
- *
- * @type {String}
- */
-var cwd = process.cwd();
+program
+	.version('1.0.0')
+	.description('Tool to summarise all code annotation like TODO or FIXME')
+	.option('-s, --source [dir]', 'root directory to be included only for checks (default: current working directory)')
+	.option('-x, --patterns [dir]', 'Path patterns to exclude (default: include all files and directories)',
+		function collect(val, collector) { collector.push("" + val); return collector; }, [])
+	.option('-e, --encoding [type]', 'file encoding to be scanned (default: utf8)')
+	.option('-l, --line-length <n>', 'number of max characters a line (default: 1000)', parseInt)
+	.option('-h, --ignore-hidden <n>', 'ignore hidden files (default: false)')
+	.option('-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')
 
-/**
- * Runtime configurations path.
- *
- * @type {String}
- */
-var rc = path.join(cwd, '.notesrc');
+	.parse(process.argv);
 
-if (0 !== argv.length) {
-  return argv.forEach(function(arg) {
-    new Notes(arg).annotate();
-  });
-}
-
-if (!fs.existsSync(rc)) {
-  return new Notes(cwd).annotate();
-}
-
-fs.readFileSync(rc, 'utf8').trim().split(/\s+/).forEach(function(directory) {
-  new Notes(directory).annotate();
-});
+Notes(program);

README.md

@@ -0,0 +1,34 @@
+'use strict';
+
+const multimatch  = require('multimatch');
+
+
+let ignoreHidden, patterns;
+
+class Filter {
+
+	constructor(_ignoreHidden, _patterns) {
+		ignoreHidden = _ignoreHidden;
+		patterns     = _patterns;
+	}
+
+	/**
+	 * Determines whether or not to let the file through. by ensuring that the
+	 * file name does not match one of the excluded directories, and ensuring it
+	 * matches one of the file filters.
+	 *
+	 * It will also ensure that even if a binary file matches the filter patterns,
+	 * it will not let it through as searching binary file contents for string
+	 * matches will never make sense.
+	 *
+	 * @param   {String} fileInformation
+	 *
+	 * @return  {Boolean}
+	 */
+	fileFilterer(fileInformation) {
+		let matchOptions = {};
+		if (!ignoreHidden) matchOptions["dot"] = true;
+		return multimatch(fileInformation.path, patterns, matchOptions).length;
+	}
+}
+module.exports = Filter;