complexityReport.js

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

• lines of code;
• number of parameters;
• 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

License

MIT

Installation

Local to the current project

npm install complexity-report

Globally for all projects

sudo npm install -g complexity-report

Usage

From the command line

cr [options] <file...>

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

Options

• -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.
• -p <regex>: Specify the files to be processed using a regular expression to match against file names, defaults to \.js$.
• -r <regex>: Specify the directories to be processed using a regular expression to match against directory names, defaults to all directories. Usefull if you want to exclude specific directories such as 'node_modules': -r '^((?!node_modules).)*$'
• -x <number>: Specify the maximum number of files to open concurrently, defaults to 1024.
• -m <maintainability>: Specify the per-module maintainability index threshold (below 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.

Output formats

Currently there are five output formats supported: plain, markdown, minimal, json and xml. These are loaded with require from the src/formats subdirectory. If the format file is not found in that directory, a second attempt will be made to load the module without the subdirectory prefix, more easily enabling the use of custom formats if they are required. 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.

From code

Loading the library

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

Calling the library

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.

Related projects

Visualizations:

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

Build tools:

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

Editor integration:

• Brackets-crjs.

Development

Dependencies

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.

Linting

There is a config file for JSHint in config/jshint.json. You can run JSHint with the command jake lint.

Tests

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

Complexity :)

Of course, you can also run complexityReport against itself! From the command line, run ./src/cli.js src. Or you can see a recent report here.