A tool for reporting code complexity metrics in JavaScript projects. Currently the tool reports on:

• lines of code;
• cyclomatic complexity;
• Halstead metrics;
• maintainability index.

Here is an example report.

The tool can be configured to fail when complexity metrics pass a specified threshold, to aid its usefulness in automated environments / CI. There are also options for controlling how metrics are calculated and the format of the report output.

The metrics are calculated by walking syntax trees generated by the Esprima parser.

For people who are only interested in analysing small amounts of code and don't want to download the tool, there is also a web front-end available:

• JSComplexity.org

npm install complexity-report

sudo npm install -g complexity-report

cr [options] <file...>

The tool will recursively read files from any directories that it encounters automatically.

• -o <file>: Specify an output file for the report, defaults to stdout.
• -f <format>: Specify an output format for the report, defaults to plain.
• -a: Include hidden files in the report.
• -m <maintainability>: Specify the per-module maintainability index threshold (beyond which, the process will fail when exiting).
• -c <complexity>: Specify the per-function cyclomatic complexity threshold (beyond which, the process will fail when exiting).
• -d <difficulty>: Specify the per-function Halstead difficulty threshold (beyond which, the process will fail when exiting).
• -v <volume>: Specify the per-function Halstead volume threshold (beyond which, the process will fail when exiting).
• -e <effort>: Specify the per-function Halstead effort threshold (beyond which, the process will fail when exiting).
• -s: Silences the console output.
• -l: Disregards operator || as a source of cyclomatic complexity.
• -w: Disregards switch statements as a source of cyclomatic complexity.
• -i: Treats for...in loops as a source of cyclomatic complexity.
• -t: Treats catch clauses as a source of cyclomatic complexity.
• -n: Uses the Microsoft-variant maintainability index.

Currently there are five output formats supported: plain, markdown, minimal, json and xml. These are loaded with require from the src/formats subdirectory and adding new formats is really easy. Each format module must export a function format, which takes a report object as its only argument and returns its string representation of the report. See src/formats/plain.js for an example format.

var cr = require('complexity-report');

var report = cr.run(source, options);

The argument source must be a string containing the source code that is to be analysed. The argument options is an optional object which may contain properties that modify cyclomatic complexity calculation. The following options are available:

• logicalor: Boolean indicating whether operator || should be considered a source of cyclomatic complexity, defaults to true.
• switchcase: Boolean indicating whether switch statements should be considered a source of cyclomatic complexity, defaults to true.
• forin: Boolean indicating whether for...in loops should be considered a source of cyclomatic complexity, defaults to false.
• trycatch: Boolean indicating whether catch clauses should be considered a source of cyclomatic complexity, defaults to false.
• newmi: Boolean indicating whether the maintainability index should be rebased on a scale from 0 to 100.

The returned report is an object that contains properties detailing the complexity of each function from the source code. There is also a maintainability index as well as aggregate complexity metrics for the source in its entirety.

Visualizations:

• Gleb Bahmutov's js-complexity-viz;
• Jarrod Overson's Plato.

Build tools:

• Viget Labs' grunt-complexity;
• Cliffano Subagio's Bob;
• Cardio.

The short-term plan is to write more output formats and open up lots more options for external configuration of the analysis.

I also need to spend some time throwing more complex test cases at it, to flush out all of the edge cases that I'm probably not yet handling. To this end, it would be great to hear from people that have run the tool against their own codebases. The bigger and uglier, the better! If you spot any issues, please raise them in the tracker.

In the longer term, I have some vague ideas concerning how to track trends in a codebase over time. Visualisations is another area that could be pretty sweet to look into.

If you think there's anything else I should look at, please raise an issue or, even better, feel free to implement it and submit a pull request! :)

The build environment relies on Node.js, NPM, Jake, JSHint, Mocha and Chai. Assuming that you already have Node.js and NPM set up, you just need to run npm install to install all of the dependencies as listed in package.json.

The tests are in test/complexityReport.js. You can run them with the command npm test or jake test.