crap4ts

CRAP (Change Risk Anti-Pattern) metric for TypeScript projects.

Combines cyclomatic complexity with test coverage to identify functions that are both complex and under-tested — the riskiest code to change.

Quick Start

Install from npm:

npm install -g @sebassdc/crap4ts

Or from source:

git clone https://github.com/sebassdc/crap4ts.git
cd crap4ts
npm install
npm run build
npm install -g .

Configure your test runner to emit Istanbul JSON coverage:

Vitest (vitest.config.ts):

export default defineConfig({
  test: {
    coverage: {
      provider: 'v8',          // or 'istanbul'
      reporter: ['text', 'json'],
    },
  },
});

Jest (jest.config.ts):

export default {
  coverageReporters: ['text', 'json'],
};

Run from your project root (where src/ lives):

crap4ts

crap4ts automatically deletes stale coverage data, runs your test suite with coverage, and prints the report.

Output

CRAP Report
===========
Function                       Module                              CC   Cov%     CRAP
-------------------------------------------------------------------------------------
complexFn                      my.module                          12  45.0%    130.2
simpleFn                       my.module                           1 100.0%      1.0

CLI Options

crap4ts --help              # show usage and available options
crap4ts --version           # print version number
crap4ts --src lib           # analyze from lib/ instead of src/
crap4ts --exclude dist      # exclude paths containing "dist"
crap4ts --timeout 120       # set analysis timeout to 120 seconds

Configuration File

Instead of passing flags every time, create a crap4ts.config.json (or .crap4tsrc.json) in your project root:

{
  "src": "lib",
  "exclude": ["dist", "fixtures"],
  "output": "json",
  "failOnCrap": 30,
  "timeout": 120
}

File Discovery

crap4ts looks for config files in the current working directory in this order:

1. crap4ts.config.json (preferred)
2. .crap4tsrc.json (fallback)

The first file found is used. If neither exists, all options use their defaults.

To load a config file from a custom path, use the --config flag:

crap4ts --config configs/crap4ts.json

CLI Override Precedence

CLI flags always take precedence over config file values. For example, if your config file sets "src": "lib" but you run crap4ts --src app, the app directory is used.

Supported Keys

Key	Type	Description	Default
src	string	Source directory to analyze	"src"
exclude	string[]	Exclude paths containing these patterns	[]
output	string	Output format: "text", "json", "markdown", or "csv"	"text"
runner	string	Test runner: "vitest" or "jest"	auto
coverageCommand	string	Custom shell command to generate coverage	none
failOnCrap	number	Fail if any CRAP score >= this value	none
failOnComplexity	number	Fail if any cyclomatic complexity >= this value	none
failOnCoverageBelow	number	Fail if any function coverage < this % (0-100)	none
top	number	Show only the top N entries	all
timeout	number	Analysis timeout in seconds	600

Unknown keys are silently ignored, so config files are forward-compatible with future versions.

Programmatic API

crap4ts can be used as a library in your own tools and scripts. The API assumes coverage data already exists (run your test suite with coverage first).

import { generateReport, crapScore, extractFunctions } from '@sebassdc/crap4ts';

// High-level: analyze an entire source tree against existing coverage
const { entries } = generateReport({
  srcDir: 'src',
  coverageDir: 'coverage',
});

entries.forEach(e => console.log(`${e.name}: CRAP ${e.crap}`));

generateReport(options)

Finds source files, parses coverage, analyzes each file, and returns entries sorted by CRAP score. This does not run your test suite -- it reads from an existing coverage-final.json.

Option	Type	Description	Default
srcDir	string	Source directory to scan for .ts files	--
coverageDir	string	Directory containing coverage-final.json	--
filters	string[]	Only include files matching these substrings	[]
excludes	string[]	Exclude files whose path contains these substrings	[]

Low-level exports

For fine-grained control, individual functions are also exported:

import {
  extractFunctions,    // parse a TS source string into FunctionInfo[]
  parseCoverage,       // read coverage-final.json from a directory
  coverageForRange,    // get coverage % for a line range
  sourceToModule,      // convert file path to dotted module name
  crapScore,           // compute CRAP score from complexity and coverage
  sortByCrap,          // sort CrapEntry[] by CRAP descending
  formatReport,        // render text table from CrapEntry[]
  formatJsonReport,    // render JSON string from CrapEntry[]
  formatMarkdownReport, // render markdown table from CrapEntry[]
  formatCsvReport,     // render CSV string from CrapEntry[]
  findSourceFiles,     // find all .ts files in a directory
  filterSources,       // filter file list by substring patterns
  analyzeFile,         // analyze a single file against coverage data
} from '@sebassdc/crap4ts';

TypeScript types CrapEntry, FunctionInfo, CoverageData, and FileCoverageData are also exported.

CI Integration

Use threshold flags to fail CI when code quality drops below acceptable levels:

# Fail if any function has CRAP >= 30 or coverage below 70%
crap4ts --fail-on-crap 30 --fail-on-coverage-below 70

# Fail if any function has complexity >= 15, show only top 10
crap4ts --fail-on-complexity 15 --top 10

Multiple thresholds can be combined. The report is always printed before any failure.

The --top flag limits displayed entries but all entries are evaluated against thresholds.

Exit Codes

Code	Meaning
0	Pass -- no threshold violations
1	Threshold violated or runtime error
2	Usage error (invalid flags or arguments)

Output Formats

crap4ts supports four output formats:

crap4ts                      # default text table
crap4ts --json               # JSON (shorthand for --output json)
crap4ts --output markdown    # Markdown table
crap4ts --output csv         # CSV

Text (default)

CRAP Report
===========
Function                       Module                              CC   Cov%     CRAP
-------------------------------------------------------------------------------------
complexFn                      my.module                          12  45.0%    130.2
simpleFn                       my.module                           1 100.0%      1.0

JSON

{
  "tool": "crap4ts",
  "entries": [
    {
      "name": "complexFn",
      "module": "my.module",
      "complexity": 12,
      "coverage": 45,
      "crap": 130.2
    }
  ]
}

Markdown

# CRAP Report

| Function | Module | CC | Cov% | CRAP |
|---|---|---:|---:|---:|
| complexFn | my.module | 12 | 45.0% | 130.2 |
| simpleFn | my.module | 1 | 100.0% | 1.0 |

CSV

Function,Module,CC,Coverage,CRAP
complexFn,my.module,12,45.0,130.2
simpleFn,my.module,1,100.0,1.0

Text output is the default. Use --json as a shorthand or --output <format> for any format.

Excluding Paths

Use --exclude to filter out files whose path contains a given substring. The flag is repeatable:

# Skip dist and fixtures directories
crap4ts --exclude dist --exclude fixtures

# Analyze lib/ but skip generated code
crap4ts --src lib --exclude __generated__

# Combine with other options
crap4ts --src packages/core/src --exclude __mocks__ --exclude .stories --json

Filtering

Pass module path fragments as arguments to filter:

crap4ts parser validator   # only files matching those strings

CRAP Formula

CRAP(fn) = CC² × (1 - coverage)³ + CC

• CC = cyclomatic complexity (decision points + 1)
• coverage = fraction of statements covered by tests

Score	Risk
1–5	Low — clean code
5–30	Moderate — refactor or add tests
30+	High — complex and under-tested

What It Counts

Decision points that increase cyclomatic complexity:

• if / ternary (c ? a : b)
• else if (each adds 1)
• for / for...of / for...in
• while / do...while
• catch clauses (each adds 1)
• case clauses in switch (each case adds 1; default does not)
• && / || / ?? operators (each operator adds 1)

Nested functions and class bodies are skipped — only the enclosing function's body is analyzed.

Compatibility

Layout	Status	Notes
Standard (src/)	Supported	Default, no config needed
Custom source dir	Supported	Use --src <dir>
Monorepo workspace	Supported	Point --src to package source
Multiple src dirs	Supported	Use --exclude to filter
Windows paths	Supported	Normalized internally
Istanbul JSON coverage	Required	Other formats not supported
Branch coverage	Not used	Statement coverage only

Limitations

• Only TypeScript (.ts) files are analyzed — .tsx, .js, and .jsx files are ignored.
• Only functions found within the configured source directory (default: src/) are scanned.
• Coverage data must be in Istanbul JSON format (coverage-final.json). Other coverage formats are not supported.
• Runner detection is heuristic: crap4ts checks for Vitest config files first, then Jest config files, then falls back to the scripts field in package.json. Use --runner vitest|jest to override.
• Nested functions are attributed to their enclosing function rather than being extracted as separate symbols.
• Dynamic or computed method names (e.g., [Symbol.iterator]() or ["methodName"]()) are not extracted.
• Only statement coverage is used when computing the coverage fraction — branch and function coverage are ignored.
• Coverage is calculated using statement-to-function overlap: a statement is attributed to a function if its line range overlaps the function's line range. This is an approximation; a multi-line statement that spans a function boundary may be counted for both the enclosing and the adjacent function.

For advanced usage patterns, see docs/advanced-usage.md.

Extracted Symbols

• Top-level function declarations
• Top-level const f = () => {} and const f = function() {}
• Class constructor, methods, getters, and setters (named as ClassName.methodName)
• Object literal methods, getters, and setters in top-level variable declarations (named as varName.methodName or varName['string-key'])

Nested functions (functions defined inside other functions, methods, or arrows) are intentionally excluded. They are not extracted as separate symbols; their complexity is attributed to the enclosing function.

Cross-Agent Skill

crap4ts ships a bundled SKILL.md that you can install into the cross-agent skill directory consumed by Claude Code, Codex, Pi, and any harness that reads .agents/skills/.

# Global install for the current user (~/.agents/skills/crap4ts/SKILL.md)
crap4ts skill install

# Project-local install (./.agents/skills/crap4ts/SKILL.md)
crap4ts skill install --project

# Print the bundled skill
crap4ts skill show

# Print where the skill is (or would be) installed
crap4ts skill path
crap4ts skill path --project

# Remove
crap4ts skill uninstall
crap4ts skill uninstall --project

The bundled skill lives inside the published package at src/skill/SKILL.md and is shipped via the files field in package.json.

Claude Code

Claude Code reads skills from ~/.claude/skills/, not ~/.agents/skills/. After installing, symlink the skill so both directories stay in sync:

crap4ts skill install
ln -s ~/.agents/skills/crap4ts ~/.claude/skills/crap4ts

For project-local installs, symlink into .claude/skills/ at the repo root:

crap4ts skill install --project
ln -s .agents/skills/crap4ts .claude/skills/crap4ts

Runner Configuration

crap4ts supports three ways to run your test suite for coverage, applied in this order of precedence:

1. --coverage-command (highest priority)

Run an arbitrary shell command instead of the built-in runner logic. The command is executed with shell: true, so pipes, environment variables, and shell syntax all work.

# Monorepo: run tests only for a specific package
crap4ts --coverage-command "npm run test:api -- --coverage"

# Custom script with environment variables
crap4ts --coverage-command "CI=1 yarn test --coverage --coverageReporters=json"

# Turborepo / Nx workspace
crap4ts --coverage-command "npx turbo run test -- --coverage"

The command must produce a coverage/coverage-final.json file in Istanbul JSON format.

2. --runner vitest|jest (skip auto-detection)

Use the built-in runner invocation for Vitest or Jest, but skip the config-file heuristic:

# Force Jest even if a vitest.config.ts exists
crap4ts --runner jest

# Force Vitest in a project without a vitest.config file
crap4ts --runner vitest

3. Auto-detection (default)

When neither flag is provided, crap4ts detects the runner automatically:

1. If any vitest.config.* file exists, use Vitest.
2. If any jest.config.* file exists, use Jest.
3. If package.json lists jest as a dependency, use Jest.
4. Otherwise, default to Vitest.

Troubleshooting

Error	Fix
Source directory 'src' not found	Use --src <dir> to point to your source directory
No TypeScript files found	Verify your source directory contains .ts files
No files match the filters	Check your filter arguments match actual file paths
Unable to parse package.json	Fix your package.json or use --runner vitest|jest
Coverage run failed	Ensure your test suite passes independently before running crap4ts
No coverage-final.json found	Configure your test runner to output Istanbul JSON coverage (see Quick Start)
Coverage run timed out	Increase timeout with --timeout <seconds>

Development

npm install
npm test          # run tests
npm run build     # compile to dist/
npm run coverage  # run tests with coverage

Inspiration

This project was inspired by crap4clj by Uncle Bob.

License

MIT