@barney-media/cognitive-typescript

CLI for Cognitive Complexity analysis in TypeScript projects.

Install

npm install --save-dev @barney-media/cognitive-typescript

Usage

npx cognitive-typescript
npx cognitive-typescript --changed
npx cognitive-typescript src/sample.ts
npx cognitive-typescript packages/api packages/web
npx cognitive-typescript --agent
npx cognitive-typescript --format json --output reports/cognitive.json --junit-report reports/cognitive-junit.xml

Options

--help                       Print usage to stdout
(no args)                    Analyze all TypeScript files under any nested src/ tree
--changed                    Analyze changed TypeScript files under src/
<file ...>                   Analyze explicit TypeScript files
<directory ...>              Analyze TypeScript files under each directory's nested src/ tree
--format <format>            Emit toon, json, text, junit, or none (default: toon)
--exclude <glob>             Exclude normalized project-relative paths from analysis (repeatable)
--exclude-name <regex>       Exclude matching function or method names from analysis (repeatable)
--exclude-decorator <name>   Exclude matching decorators by simple or dotted source name (repeatable)
--exclude-comment <marker>   Exclude generated code with leading file/function comment markers (repeatable)
--use-default-exclusions     Enable conservative generated-code exclusions (default: true)
--failures-only[=true|false] Emit failed functions only in the primary report
--omit-redundancy[=true|false]
                             Omit redundant per-method status in the primary report
--output <path>              Write the primary report to a file instead of stdout
--junit-report <path>        Also write a full JUnit XML report for CI test-report UIs
--threshold <integer>        Override the Cognitive Complexity threshold (default: 15)
--agent                      Compact the primary report to actionable failures by default

Default exclusions cover declaration files, generated/build directories, generated file-name suffixes, existing test-file defaults, and the leading generated-code markers @generated and <auto-generated.

Primary formats:

• toon default CLI format
• json
• text
• junit
• none

--agent defaults the primary report to toon and turns on --failures-only plus --omit-redundancy.

The CLI is pure static analysis. It does not execute tests, collect coverage, or compute CRAP scores.

--junit-report is opt-in on the CLI. Both --output and --junit-report must stay inside the project root and must target files rather than the project root, filesystem roots, or existing directories.

Exit Codes

• 0 success, threshold respected
• 1 invalid CLI usage or execution failure
• 2 Cognitive Complexity threshold exceeded (> threshold)
• 3 unexpected internal error

See the main repository for full details.

License

Apache-2.0