Awesome Open Source
Awesome Open Source
Sponsorship

complexity-report

โ—๏ธ ๐Ÿ˜ง โ—๏ธ ๐Ÿ˜ง โ—๏ธ ๐Ÿ˜ง โ—๏ธ ๐Ÿ˜ง โ—๏ธ ๐Ÿ˜ง โ—๏ธ ๐Ÿ˜ง โ—๏ธ ๐Ÿ˜ง โ—๏ธ ๐Ÿ˜ง โ—๏ธ ๐Ÿ˜ง โ—๏ธ ๐Ÿ˜ง โ—๏ธ

NOTE: This fork is no longer maintained. Use Jared's fork instead.

โ—๏ธ ๐Ÿ˜ง โ—๏ธ ๐Ÿ˜ง โ—๏ธ ๐Ÿ˜ง โ—๏ธ ๐Ÿ˜ง โ—๏ธ ๐Ÿ˜ง โ—๏ธ ๐Ÿ˜ง โ—๏ธ ๐Ÿ˜ง โ—๏ธ ๐Ÿ˜ง โ—๏ธ ๐Ÿ˜ง โ—๏ธ ๐Ÿ˜ง โ—๏ธ

Software complexity analysis for JavaScript projects. Command-line front-end for escomplex. Less attractive elder brother of JSComplexity.org.

Software complexity analysis

Complexity is the quality of consisting of many interrelated parts. When software consists of many interrelated parts, it becomes more difficult to reason about. Software that is difficult to reason about is a more fertile breeding ground for bugs than software that is simple.

Every problem space contains some level of inherent complexity, which is shared by all possible solutions. However, as programmers, we can reduce the complexity of our chosen solutions by limiting the interrelatedness of their constituent components. This is commonly referred to as favouring cohesion over coupling, and forms the bedrock on which axioms such as the single responsibility principle are built.

In codebases that are large and/or unfamiliar, it can be difficult to know whether regions of complexity exist and where they might be. By defining metrics of complexity, the search for offending components can be automated and brought into the existing build process alongside other forms of static analysis and unit tests.

How it works

complexity-report is just a node.js-based command-line wrapper around escomplex, which is the library that performs the actual analysis work. Code is passed to escomplex in the form of syntax trees that have been generated with esprima, the popular JavaScript parser.

Here is an example report.

Complexity metrics

The readme for escomplex contains a brief overview of the metrics it produces.

What not to do with the results

The numbers returned by this tool should not be interpreted as definitive indicators of whether a piece of software is "too complex", whatever that might mean.

Software development is a varied field and every project is subject to a unique set of environmental factors. Attempts to set generic hard limits for these complexity metrics must essentially be arbitrary and fail to consider the specific requirements of a given project. Further, complexity itself is such an amorphous, multi-dimensional continuum, that attempting to pigeon-hole chunks of code at discrete points along a single axis is an intrinsically crude approach.

What to do with the results

It is better to use this tool as a fuzzy, high-level mechanism, which can identify regions of interest or concern and from which your own programming- and domain-expertise can take over for a more comprehensive analysis.

Although the metrics themselves are not perfect, they can help to identify areas of code that warrant closer inspection. They can also be tracked over time, as an indicator of the direction that overall code quality may be moving in.

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.

Installation

You must have node.js installed.

Then, for a project-based install:

npm install complexity-report

Or globally for all projects:

sudo npm install -g complexity-report

Usage

cr [options] <path>

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

Command-line options

-h, --help                            output usage information
-c, --config <path>                   specify a configuration JSON file
-o, --output <path>                   specify an output file for the report
-f, --format <format>                 specify the output format of the report
-e, --ignoreerrors                    ignore parser errors
-a, --allfiles                        include hidden files in the report
-p, --filepattern <pattern>           specify the files to process using a regular expression to match against file names
-P, --dirpattern <pattern>            specify the directories to process using a regular expression to match against directory names
-x, --excludepattern <pattern>        specify the the directories to exclude using a regular expression to match against directory names
-m, --maxfiles <number>               specify the maximum number of files to have open at any point
-F, --maxfod <first-order density>    specify the per-project first-order density threshold
-O, --maxcost <change cost>           specify the per-project change cost threshold
-S, --maxsize <core size>             specify the per-project core size threshold
-M, --minmi <maintainability index>   specify the per-module maintainability index threshold
-C, --maxcyc <cyclomatic complexity>  specify the per-function cyclomatic complexity threshold
-Y, --maxcycden <cyclomatic density>  specify the per-function cyclomatic complexity density threshold
-D, --maxhd <halstead difficulty>     specify the per-function Halstead difficulty threshold
-V, --maxhv <halstead volume>         specify the per-function Halstead volume threshold
-E, --maxhe <halstead effort>         specify the per-function Halstead effort threshold
-s, --silent                          don't write any output to the console
-l, --logicalor                       disregard operator || as source of cyclomatic complexity
-w, --switchcase                      disregard switch statements as source of cyclomatic complexity
-i, --forin                           treat for...in statements as source of cyclomatic complexity
-t, --trycatch                        treat catch clauses as source of cyclomatic complexity
-n, --newmi                           use the Microsoft-variant maintainability index (scale of 0 to 100)
-T, --coffeescript                    include coffee-script files

Configuration files

By default, complexity-report will attempt to read configuration options from a JSON file called .complexrc in the current working directory. This file should contain a JSON object with property names matching the long-form option names from the command line (the ones that follow --). Options set in this file will be over-ridden by options specified on the command line.

See an example configuration file.

You can also specify an alternative path to this file using the -c command-line option.

Output formats

Currently there are five output formats supported: plain, markdown, minimal, json, and xml. These are loaded 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 so desired.

Adding new formats is simple; each one must be a CommonJS module, which exports a function named format. The format function should take a report object, as defined by escomplex, and return its string representation of the report.

See the plain formatter for an example.

Development

See the contribution guidelines.

License

MIT


Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
javascript (66,042)ย 
unmaintained (55)ย 

Find Open Source By Browsing 7,000 Topics Across 59 Categories

Advertising ๐Ÿ“ฆ10
All Projects
Application Programming Interfaces ๐Ÿ“ฆ124
Applications ๐Ÿ“ฆ192
Artificial Intelligence ๐Ÿ“ฆ78
Blockchain ๐Ÿ“ฆ73
Build Tools ๐Ÿ“ฆ113
Cloud Computing ๐Ÿ“ฆ80
Code Quality ๐Ÿ“ฆ28
Collaboration ๐Ÿ“ฆ32
Command Line Interface ๐Ÿ“ฆ49
Community ๐Ÿ“ฆ83
Companies ๐Ÿ“ฆ60
Compilers ๐Ÿ“ฆ63
Computer Science ๐Ÿ“ฆ80
Configuration Management ๐Ÿ“ฆ42
Content Management ๐Ÿ“ฆ175
Control Flow ๐Ÿ“ฆ213
Data Formats ๐Ÿ“ฆ78
Data Processing ๐Ÿ“ฆ276
Data Storage ๐Ÿ“ฆ135
Economics ๐Ÿ“ฆ64
Frameworks ๐Ÿ“ฆ215
Games ๐Ÿ“ฆ129
Graphics ๐Ÿ“ฆ110
Hardware ๐Ÿ“ฆ152
Integrated Development Environments ๐Ÿ“ฆ49
Learning Resources ๐Ÿ“ฆ166
Legal ๐Ÿ“ฆ29
Libraries ๐Ÿ“ฆ129
Lists Of Projects ๐Ÿ“ฆ22
Machine Learning ๐Ÿ“ฆ347
Mapping ๐Ÿ“ฆ64
Marketing ๐Ÿ“ฆ15
Mathematics ๐Ÿ“ฆ55
Media ๐Ÿ“ฆ239
Messaging ๐Ÿ“ฆ98
Networking ๐Ÿ“ฆ315
Operating Systems ๐Ÿ“ฆ89
Operations ๐Ÿ“ฆ121
Package Managers ๐Ÿ“ฆ55
Programming Languages ๐Ÿ“ฆ245
Runtime Environments ๐Ÿ“ฆ100
Science ๐Ÿ“ฆ42
Security ๐Ÿ“ฆ396
Social Media ๐Ÿ“ฆ27
Software Architecture ๐Ÿ“ฆ72
Software Development ๐Ÿ“ฆ72
Software Performance ๐Ÿ“ฆ58
Software Quality ๐Ÿ“ฆ133
Text Editors ๐Ÿ“ฆ49
Text Processing ๐Ÿ“ฆ136
User Interface ๐Ÿ“ฆ330
User Interface Components ๐Ÿ“ฆ514
Version Control ๐Ÿ“ฆ30
Virtualization ๐Ÿ“ฆ71
Web Browsers ๐Ÿ“ฆ42
Web Servers ๐Ÿ“ฆ26
Web User Interface ๐Ÿ“ฆ210