This program analyses TypeScript and JavaScript code according to the Cognitive Complexity metric. It produces a JSON summary and a GUI for exploring the complexity of your codebase.

Disclaimer

I and this project are completely unaffiliated with Sonar Source.

Install

npm install cognitive-complexity-ts

Run

# UI output (any of the following)
npx ccts [file path]
npx cognitive-complexity-ts [file path]
npx cognitive-complexity-ts-ui [file path]
npx ccts-ui [file path]

# JSON output (any of the following)
npx cognitive-complexity-ts-json [file path]
npx ccts-json [file path]

API

See src/api.ts or build/src/api.d.ts.

Functions available when this package is imported:

function getFileOrFolderOutput(entryPath: string): Promise<FileOutput | FolderOutput>;
function getFileOutput(filePath: string): Promise<FileOutput>;
function getFolderOutput(folderPath: string): Promise<FolderOutput>;
function programOutput(entryPath: string): Promise<string>;

Simple Overview of the Cognitive Complexity Metric

Each function, class, namespace, type, and file has a complexity score based on the total complexity of all code written inside. The complexity score is not increased by code that is referenced.

Inherent Cost

The following structures increase the complexity score by 1.

if, else, else if, ? : for types and data
switch
for, while, do while
catch
break label, continue label
a sequence of the same operator &&, ||, ??, intersection &, union |
a recursive reference to a function, class, or type
mapped type { [K in T]: ... }

Nesting Increments

The following structures increase the complexity score by a number equal to the depth the code is at. The depth of code is defined in the next section.

if, ? : for types and data
switch
for, while, do while
catch
mapped type { [K in T]: ... }

The following structures increment the depth by 1.

code called when the condition is met in if and else if
else
conditionally executed code in a conditional expression ? ... : ...
switch
looped code in for, while, do while
catch
nested function body, nested class body

Differences

I have taken some liberties with the guidelines set out by Sonar Source in the Cognitive Complexity whitepaper in order to account for TypeScript's features and to improve the user output.

Changes:

Classes have a score
Files have a score
Namespaces have a score
Types have a score
- Union and intersection have an inherent increment
- Mapped types have an inherent and nesting increments
- Recursive types have an inherent increment
Recursive references have an increment, not just recursive calls
& and | are not supported by TypeScript as eager boolean operators, so they do not carry an inherent increment.

Output

Some anonymous classes and functions will appear with names because they are assigned to a variable/const.

Development

Install

git clone https://github.com/Deskbot/Cognitive-Complexity-TS
npm i

Build

# All builds are incremental.
# These scripts also build dependencies incrementally.
npm run build       # The main complexity analysis program and UI back-end server.
npm run build-tools
npm run build-ui    # The in-browser UI code only.

Run

# These also build dependencies.
# The binaries exposed by package.json do not.
npm run json
npm run ui

Test

npm run test [test name]

The test name can be any substring of a path to a test file. Or the test name can be left blank to run all tests.

See TypeScript Parser Output

Microsoft doesn't appear to have documentation for what all of the AST nodes are, so I created a tool to output the AST for the code.

npm run what [file path]

License

Deskbot/Cognitive-Complexity-TS

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 6

Uh oh!

Languages

Packages