@barney-media/crap-typescript-core

Core analysis engine for computing CRAP (Change Risk Anti-Pattern) scores on TypeScript projects. Combines cyclomatic complexity with function-level Istanbul coverage data.

Install

npm install @barney-media/crap-typescript-core

API

import { analyzeProject, formatAnalysisReport } from "@barney-media/crap-typescript-core";

const result = await analyzeProject({ projectRoot: "." });
const report = formatAnalysisReport(result.metrics, { format: "toon" });
console.log(report);

Key exports: analyzeProject, calculateCrapScore, formatAnalysisReport, formatReport, parseCoverageReport, parseFileMethods.

analyzeProject accepts threshold to override the default CRAP threshold of 8.0. Values below 4.0 emit a warning because they are likely too noisy; values above 8.0 emit a warning because they are too lenient even for hard gates.

Commands run by the default command executor, including coverage commands and changed-file discovery, time out after 300 seconds. 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.

analyzeProject also accepts excludes, excludePathRegexes, excludeGeneratedMarkers, and useDefaultExclusions. These filters run after explicitPaths or changedOnly select candidate files and before parsing, coverage attribution, reporting, and threshold evaluation. Baseline analyzability exclusions always remain active for declarations, test/spec files, __tests__/, dist/, coverage/, and node_modules/; useDefaultExclusions: false only disables generated-code defaults.

Generated-code defaults exclude directory segments containing generated, directory segments exactly named gen, common generated filename suffixes such as *.generated.ts, *.gen.ts, *Generated.ts, protobuf outputs, and Angular generated artifacts. Leading generated-header markers are matched only in comments before the first non-comment token.

formatAnalysisReport supports toon, json, text, junit, and none. Primary reports expose run-level status and threshold; method-level entries use status, crap, cc, cov, covKind, method, src, lineStart, and lineEnd, with src set to the project-relative source file path. format: "none" returns empty primary content. Pass failuresOnly: true to include failed method entries only. Pass omitRedundancy: true to omit method-level status while keeping run-level metadata; with format: "junit", this omits the custom testcase status property while preserving JUnit failure and skipped elements. JUnit output is GitLab-oriented: it uses a <testsuites> wrapper, classname/file source-path testcase attributes, method:lineStart testcase names, time="0", and failure/skipped body text with CRAP score, threshold, coverage kind, source path, and line range. JUnit still writes custom properties for compatibility. Sidecar JUnit reports should be generated by formatting the full metrics set separately with format: "junit" and without failuresOnly, omitRedundancy, or agent.

Pass sourceExclusionAudit: result.sourceExclusionAudit to formatAnalysisReport when reports should expose excluded-source counts. Full reports and JUnit sidecars include the audit when files were excluded. Optimized primary reports from default agent mode omit it by default.

agent: true is a composite shortcut for primary reports. It defaults format to toon in the CLI and adapters, and defaults failuresOnly and omitRedundancy to true in core formatting. Explicit format, failuresOnly: false, or omitRedundancy: false options override those defaults at the call site.

Formula

CRAP = CC^2 * (1 - coverage)^3 + CC

See the main documentation for full details.

License

Apache-2.0