# crap-score

> Use CRAP to estimate and visualize the change risk of your JS/TS project.

Latest version **1.2.1** (published 2026-04-24) · MIT license · 0 weekly downloads

## Install

```sh
npm install crap-score
pnpm add crap-score
yarn add crap-score
bun add crap-score
```

Provides the command `crap`.

## Health

**Score 65/100 (B)** — status: stable.

Positive: has types; esm support; no vulnerabilities; has provenance; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.2.1 |
| Published | 2026-04-24 |
| First published | 2023-03-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18.17.1 |
| Dependencies | 12 |
| Unpacked size | 102.2 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 18 |
| Author | Arno Hilke |
| Maintainers | ahilke |
| Keywords | CRAP Score, Cyclomatic Complexity, Code Quality, Test Coverage |

## Links

- npm: https://www.npmjs.com/package/crap-score
- Repository: https://github.com/ahilke/js-crap-score
- Homepage: https://github.com/ahilke/js-crap-score#readme
- Issues: https://github.com/ahilke/js-crap-score/issues
- npm.io page: https://npm.io/package/crap-score

## Dependencies (12)

- [rxjs](https://npm.io/package/rxjs.md) ^7.8.1
- [eslint](https://npm.io/package/eslint.md) ^8.53.0
- [lodash-es](https://npm.io/package/lodash-es.md) ^4.17.21
- [handlebars](https://npm.io/package/handlebars.md) ^4.7.8
- [@nestjs/cli](https://npm.io/package/@nestjs/cli.md) ^10.3.2
- [@nestjs/core](https://npm.io/package/@nestjs/core.md) ^10.3.9
- [@nestjs/common](https://npm.io/package/@nestjs/common.md) ^10.3.9
- [nest-commander](https://npm.io/package/nest-commander.md) ^3.13.0
- [@types/inquirer](https://npm.io/package/@types/inquirer.md) ^8.2.10
- [reflect-metadata](https://npm.io/package/reflect-metadata.md) ^0.2.2
- [@typescript-eslint/utils](https://npm.io/package/@typescript-eslint/utils.md) ^7.13.1
- [@typescript-eslint/parser](https://npm.io/package/@typescript-eslint/parser.md) ^7.13.1

## Recent versions

- 1.2.1 (latest) — 2026-04-24
- 1.2.0 — 2023-05-20
- 1.1.0 — 2023-04-08
- 1.0.1 — 2023-03-27
- 1.0.0 — 2023-03-23

## README

# CRAP Score

[![npm version](https://badge.fury.io/js/crap-score.svg)](https://badge.fury.io/js/crap-score)

Use CRAP to estimate and visualize the change risk of your JS/TS project.

-   [Example](#example)
-   [What is CRAP?](#what-is-crap)
-   [How to Use](#how-to-use)
    -   [Jest Reporter](#jest-reporter)
    -   [CLI](#cli)
    -   [API](#api)
    -   [istanbul JSON Coverage Report](#istanbul-json-coverage-report)
-   [Contributing](#contributing)

## Example

The HTML CRAP report of the project itself can be found under <https://ahilke.github.io/js-crap-score/>.

## What is CRAP?

The CRAP score is a measure of the risk of a function ranging from 1 (best) to infinity (worst). It uses complexity and coverage information to give an estimate how likely it is that a function contains bugs or breaks with future changes.

CRAP is an acronym for Change Risk Anti-Patterns and is computed as follows: $comp^2 \cdot (1 - cov)^3 + comp$, where `comp` is the cyclomatic complexity of the function and `cov` is the statement coverage as number between 0 (no coverage) and 1 (fully covered).

A common guideline is to address functions with a CRAP score above 30 by either adding additional tests or refactoring the function to reduce complexity. This translates to simple functions with complexity 5 or lower not requiring any test coverage, while a function with complexity over 30 always requires refactoring.

## How to Use

This package provides multiple ways to generate and collect information about coverage, complexity and CRAP for each function within your project. It generates both a human-readable HTML report and a JSON report for further processing.

Usage Options:

-   run it together with your tests by adding it to your [jest configuration](#jest-reporter)
-   run it from the [command line](#cli)
-   integrate it into your [own program](#api)

### Jest Reporter

Add `crap-score` as [test reporter](https://jestjs.io/docs/configuration#reporters-arraymodulename--modulename-options) to jest.
When `jest` is run with coverage enabled, this will also generate a CRAP report. Example for `jest.config.json`:

```json
"reporters": ["default", "crap-score"]
```

The reporter also accepts options, for example:

```json
"reporters": [
    "default",
    [
        "crap-score",
        {
            "jsonReportFile": "crap.json",
        }
    ]
]
```

A typed interface for the reporter options is available via `import type { ReporterOptions } from "crap-score";`.

Available options:

| Option         | Description                                                                                                                               |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| jsonReportFile | Specifies path where the JSON report will be written to. Defaults to `crap-report/crap-report.json`. Pass `false` to disable JSON report. |
| htmlReportDir  | Specifies path where the HTML report will be written to. Defaults to `crap-report/html/`. Pass `false` to disable HTML report.            |
| log            | Changes log behaviour. `"silent"` suppresses all logs. `"debug"` prints additional logs.                                                  |

### CLI

Install the package (or use it directly via npx), then just run `npx crap <path-to-coverage>`.
The command expects an istanbul JSON coverage report as input (see [JSON Coverage Report](#istanbul-json-coverage-report)) and generates both an HTML and a JSON report in the `crap-report` folder, containing the CRAP score of each function in the original istanbul report.

```sh
crap --help
```

### API

#### ESM

```ts
import { getCrapReport, CrapReport } from "crap-score";

const report: CrapReport = await getCrapReport({
    testCoverage: "./coverage/coverage-final.json",
});
```

#### CommonJS

To use the library API in a CommonJS project, you will need to use dynamic `import` statements as this is a ESM library:

```ts
async function main() {
    const { getCrapReport } = await import("crap-score");
    const report = await getCrapReport({
        testCoverage: "./coverage/coverage-final.json",
    });
}
```

If you are using TypeScript, make sure to have `"moduleResolution": "node16"` to avoid `import` being transformed into `require`. If that is not an option, you can work around it via `eval`:

```ts
async function main() {
    const { getCrapReport } = await eval("import('crap-score')");
    const report = await getCrapReport({
        testCoverage: "./coverage/coverage-final.json",
    });
}
```

### istanbul JSON Coverage Report

If you are using `jest`, you can generate an istanbul JSON coverage report by adding `collectCoverage: true` and `coverageReporters: ["json"]` to your configuration. This will generate a JSON report under `coverage-final.json`.

Make sure to also review other configuration related to coverage, especially `collectCoverageFrom`. This allows you to include files in your report even if they are not covered. This is important, since any uncovered function in your project may have a very high CRAP score.

## Contributing

Got any feedback? I'm eager to hear it! Please open an issue or send me an email.

If you want to contribute code, please read [CONTRIBUTING.md](./CONTRIBUTING.md) first.

---
_Source: https://npm.io/package/crap-score · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._