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.

Lines of code:
Both physical (the number of lines in a module or function)
and logical (a count of the imperative statements).
A crude measure.

Number of parameters:
Analysed statically
from the function signature,
so no accounting is made
for functions that rely on the arguments object.
Lower is better.

Cyclomatic complexity:
Defined by Thomas J. McCabe in 1976,
this is a count of the number of cycles
in the program flow control graph.
Effectively the number of distinct paths
through a block of code.
Lower is better.

Cyclomatic complexity density:
Proposed as a modification
to cyclomatic complexity
by Geoffrey K. Gill and Chris F. Kemerer in 1991,
this metric simply re-expresses it
as a percentage of the logical lines of code.
Lower is better.

Halstead metrics:
Defined by Maurice Halstead in 1977,
these metrics are calculated
from the numbers of operators
and operands in each function.
Lower is better.

Maintainability index:
Defined by Paul Oman & Jack Hagemeister in 1991,
this is a logarithmic scale
from negative infinity to 171,
calculated from
the logical lines of code,
the cyclomatix complexity
and the Halstead effort.
Higher is better.

Dependencies:
A count of the calls
to CommonJS and AMD require.
Analysed statically
from the function signature,
so no accounting is made
for dynamic calls
where a variable or function is
obscuring the nature of the dependency.
Lower is better.

First-order density:
The percentage of all possible internal dependencies
that are actually realised in the project.
Lower is better.

Change cost:
The percentage of modules affected,
on average,
when one module in the project
is changed.
Lower is better.

Core size:
The percentage of modules
that are both widely depended on
and themselves depend on other modules.
Lower is better.

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.

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.

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

options.logicalor:
Boolean indicating whether operator ||
should be considered a source of cyclomatic complexity,
defaults to true.

options.switchcase:
Boolean indicating whether switch statements
should be considered a source of cyclomatic complexity,
defaults to true.

options.forin:
Boolean indicating whether for...in loops
should be considered a source of cyclomatic complexity,
defaults to false.

options.trycatch:
Boolean indicating whether catch clauses
should be considered a source of cyclomatic complexity,
defaults to false.

options.newmi:
Boolean indicating whether the maintainability
index should be rebased on a scale from 0 to 100,
defaults to false.

options.skipCalculation:
only valid for when ast is an array of files
Boolean indicating if we should skip processing of certain values,
such as the adjacency and visibility matrixes,
core sizes, and average values loc, etc.

options.noCoreSize:
Skips creating the visibility matrix and calculating the coreSize,
which can be very expensive for large projects

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.

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:

result.reports:
An array of report objects,
each one in the same format
described above
but with an extra property path
that matches the path property
from its corresponding syntax tree.
This path property is required
because the reports array gets sorted
during dependency analysis.

result.adjacencyMatrix:
The adjacency
design structure matrix (DSM)
for the project.
This is a two-dimensional array,
each dimension with the same order and length
as the reports array.
Each row and column
represents its equivalent
indexed module
from the reports array,
with values along the horizontal
being 1
when that module
directly depends on another
and values along the vertical
being 1
when that module
is directly depended on by another.
All other values are 0.

result.firstOrderDensity:
The first-order density for the project.

result.visibilityMatrix:
The visibility DSM for the project.
Like the adjacency matrix,
but expanded to incorporate
indirect dependencies.
Will be missing if noCoreSize is passed
as an option.

result.changeCost:
The change cost for the project.
Will be missing if noCoreSize is passed
as an option.