Home

Awesome

escomplex

Build status

:exclamation: :anguished: :exclamation: :anguished: :exclamation: :anguished: :exclamation: :anguished: :exclamation: :anguished: :exclamation: :anguished: :exclamation: :anguished: :exclamation: :anguished: :exclamation: :anguished: :exclamation: :anguished: :exclamation:

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

:exclamation: :anguished: :exclamation: :anguished: :exclamation: :anguished: :exclamation: :anguished: :exclamation: :anguished: :exclamation: :anguished: :exclamation: :anguished: :exclamation: :anguished: :exclamation: :anguished: :exclamation: :anguished: :exclamation:

Software complexity analysis of JavaScript-family abstract syntax trees. The back-end for complexity-report.

Abstract syntax trees

This library deliberately excludes logic for parsing source code and for navigating parse trees. Both the syntax tree and a matching syntax tree walker are inputs to escomplex, meaning it is not tied to any particular language, parser or data format.

Syntax tree walkers

Metrics

Currently the library reports on:

It is important to note that none of these metrics can compete with the insight of a competent developer. At best, they are an automatable warning system, which can help to identify areas of code that warrant closer inspection by a human being.

Links to research

Installation

The library is published on npm under the name escomplex. To install, you can add it to the dependencies in your package.json file or simply run:

npm install escomplex

Usage

You can load escomplex in your own code by calling require:

var escomplex = require('escomplex');

escomplex exports two primary functions, analyze and processResults

analyze

var result = escomplex.analyse(ast, walker, options);

Arguments

ast

The first argument, ast, must be either an abstract syntax tree or an array of syntax trees. If it is an array, each tree should include an extra property, path, that is either a relative or full path to the equivalent module on disk. As well as identifying each of the result objects, that path is also used during dependency analysis.

walker

The second argument, walker, must be a syntax tree walker.

options

The third argument, options, is an optional object containing properties that modify some of the complexity calculations:

processResults

escomplex.processResults(result, false);

This function takes a report object and computes aggregate scores for all individual files and also adjacency and visibility matrices. This is useful for combining together multiple report objects (say from different languages) and recomputing aggregate scores.

Arguments

Result

A result object of the form:

var result = {
  reports: [
    {
      // same format as module return
    }
  ]
}

noCoreSize

a boolean indicating not to calculate the visibilityMatrix or core size

Result Format

Both analyze and processResults return a report of the following format, with some variation depending on the given options.

For a single module

If a single abstract syntax tree object is passed in the ast argument, the result will be a report object that looks like the following:

{
    maintainability: 171,
    dependencies: [],
    aggregate: {
        sloc: {
            logical: 0,
            physical: 0
        },
        params: 0,
        cyclomatic: 1,
        cyclomaticDensity: 1,
        halstead: {
            vocabulary: 0,
            difficulty: 0,
            volume: 0,
            effort: 0,
            bugs: 0,
            time: 0
        }
    },
    functions: [
        {
            name: '',
            line: 0,
            sloc: {
                logical: 0,
                physical: 0
            },
            params: 0,
            cyclomatic: 1,
            cyclomaticDensity: 1,
            halstead: {
                vocabulary: 0,
                difficulty: 0,
                volume: 0,
                effort: 0,
                bugs: 0,
                time: 0
            }
        },
        ...
    ]
}

The meaning of those values, briefly, is as follows (see metrics for more information on each one):

For multiple modules

If an array of syntax trees is passed in the ast argument, the result will be an object that looks like the following:

{
    reports: [
        ...
    ],
    adjacencyMatrix: [
        [ 0 ]
    ],
    firstOrderDensity: 0,
    visibilityMatrix: [
        [ 0 ]
    ],
    changeCost: 100,
    coreSize: 100,
    loc: 0,
    cyclomatic: 1,
    effort: 0,
    params: 0,
    maintainability: 171
}

Those properties are defined as follows:

Related projects

Development

Refer to the contrubution guidelines before submitting a pull request.

Source code is in /src. Unit tests are in /test. You can run the tests with npm test. You can run the linter with npm run lint. Make sure you've installed all the dependencies with npm install first.

License

MIT