knip-guard/README.md

Baseline / no-new-issues guard for Knip

# knip-guard

Guard your codebase from **new dead code issues** detected by [Knip](https://github.com/webpro/knip).

`knip-guard` adds a minimal **baseline/snapshot** mechanism so large or legacy repositories can adopt Knip **without blocking progress or hiding existing issues from reports, but rather as a mechanism to accept and progressively improve and accept new issues if needed, promoting ownership and visibility**.
You keep all existing issues for now — but **no new issues can be introduced**.


---

## 🚀 Why knip-guard?

Knip is excellent at discovering:

- unused files
- unused exports
- unused dependencies
- unresolved imports
- dead enum/class members
- and more…

But if you already have **hundreds of issues**, enabling Knip in CI immediately will break every PR.

`knip-guard` solves this by:

- creating a **baseline** (snapshot of current issues)
- allowing those issues to exist temporarily
- **failing CI only when new issues appear**
- letting teams clean old issues gradually and safely

This is the same model used by tools like SonarQube, ESLint’s `--init` baseline mode, and static analyzers.

---

## ❗ How is this different from Knip’s `ignore` functionality?

Knip provides an `ignore` config, but it is **not the same thing**.

### `ignore` is static
You manually list files/paths/symbols to ignore forever.

Problems:
- It does **not** distinguish between old accepted issues and new regressions.
- It grows stale as code changes.
- It must be manually curated.
- If you ignore everything, you lose all value from Knip.

### `knip-guard` is dynamic
It maintains a snapshot of all current issues and blocks **only newly introduced** ones.

Advantages:
- Zero manual maintenance.
- Old issues tolerated; new ones blocked.
- Ideal for large monorepos full of legacy dead code.
- Baseline updates are intentional and simple (`knip-guard accept`).

**In short:**
`ignore` hides issues.
`knip-guard` prevents regressions.

---

## 📦 Installation

```bash
npm install --save-dev knip-guard
```

## Usage

Install as a dev dependency:

```bash
npm install --save-dev knip-guard
```

Initialize a baseline (run this once in a clean state):

```bash
npx knip-guard init --command "npm run knip"
```

Check in CI (exit code 1 when new issues are introduced):

```bash
npx knip-guard check --command "npm run knip"
```

Accept new issues (after review) and update baseline:

```bash
npx knip-guard accept --command "npm run knip"
```

CLI options:
- -b, --baseline <path>  Path to baseline file (default: .knip-baseline.json)
- -r, --report <path>    Path to existing Knip JSON report (otherwise run knip)
- -c, --command <cmd>    Command to run knip (default: "npx knip")
- -h, --help             Show help

## Build, test & publish

Build (generate JS + types in dist/):

```bash
npm run build
```

Run tests:

```bash
npm test
```

Prepare/publish:
- The package has a `prepare` and `prepublishOnly` script that runs the build.
- Before publishing, ensure `dist/` contains the compiled files and the CLI (`dist/cli.js`) includes the shebang line.