@barney-media/crap-typescript
CLI for CRAP (Change Risk Anti-Pattern) metric analysis in TypeScript projects.
Install
npm install --save-dev @barney-media/crap-typescript
Usage
npx crap-typescript
npx crap-typescript --changed
npx crap-typescript --format json --output reports/crap.json
npx crap-typescript --agent --junit-report reports/crap-junit.xml
npx crap-typescript --threshold 6
npx crap-typescript --exclude 'packages/api/generated/**'
npx crap-typescript --exclude-path-regex '^src/proto/'
npx crap-typescript --exclude-generated-marker '@custom-generated'
npx crap-typescript src/sample.ts
npx crap-typescript packages/api packages/web
Options
--help Print usage to stdout
(no args) Analyze all TypeScript files under any nested src/ tree
--changed Analyze changed TypeScript files under src/
--exclude <glob> Exclude source paths by normalized relative glob; repeatable
--exclude-path-regex <regex> Exclude source paths by normalized relative regex; repeatable
--exclude-generated-marker <marker> Exclude leading generated-header markers; repeatable
--use-default-exclusions[=true|false] Enable generated-code defaults (`true` by default)
--package-manager <tool> Force auto, npm, pnpm, yarn, or bun
--test-runner <runner> Force auto, vitest, or jest
--format <format> Emit toon, json, text, junit, or none (default: toon)
--agent Default primary output to toon, failures-only, omit-redundancy
--failures-only[=true|false] Emit failed methods 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 <number> Override the CRAP threshold (`6.0` by default)
<file ...> Analyze explicit TypeScript files
<directory ...> Analyze TypeScript files under each directory's nested src/ tree
The default toon format is compact and agent-readable. Primary reports include run-level status and threshold; method rows use status, crap, cc, cov, covKind, method, src, lineStart, and lineEnd, with src set to the project-relative source file path. --format none suppresses primary stdout output; when used with --output, it creates an empty primary report file. --failures-only, --failures-only=true, and --failures-only=false control whether the primary report includes only failed method entries. --omit-redundancy, --omit-redundancy=true, and --omit-redundancy=false control whether primary report method rows omit status; with --format junit, they omit the custom testcase status property while preserving JUnit failure and skipped elements. JUnit sidecar reports always include the full method set and method status, regardless of --agent, --failures-only, or --omit-redundancy. JUnit XML is shaped for GitLab's Tests tab with a <testsuites> wrapper, testcase classname/file source paths, metric-bearing testcase names, time="0", and testcase-level system-out plus failure/skipped text containing CRAP score, threshold, coverage kind, source path, and line range. --agent is a composite shortcut, not a format: it defaults primary output to --format toon, --failures-only=true, and --omit-redundancy=true. Explicit --format, --failures-only=false, or --omit-redundancy=false options override those defaults.
Baseline analyzability exclusions always skip declarations, test/spec files, __tests__/, dist/, coverage/, and node_modules/. Generated-code defaults then exclude generated directory segments, exact gen directory segments, common generated filename suffixes, protobuf outputs, Angular generated artifacts, and leading generated-header markers before the first non-comment token. User exclusions compose with those defaults unless --use-default-exclusions=false; disabling defaults does not disable the baseline analyzability filter.
Full primary reports and JUnit sidecars include source-exclusion audit counts when files were excluded. Default agent primary output omits those details.
Commands run by the built-in executor, including coverage commands and --changed discovery, time out after 300 seconds by default. Set CRAP_TYPESCRIPT_COMMAND_TIMEOUT_MS to a non-negative millisecond value to override this default; 0 disables the timeout. Captured stdout and stderr are capped at 10 MiB per stream. User-facing command failures may include truncated output, while internal commands that require complete output, such as git status --porcelain -z, fail if the cap is exceeded.
The default threshold is 6.0. Values below 4.0 print a warning because they are likely too noisy; values above 8.0 print a warning because they are too lenient even for hard gates.
Exit Codes
0success, threshold respected1invalid CLI usage or execution failure2CRAP threshold exceeded (> configured threshold)
See the main documentation for full details.