deadwood-scan 0.3.0 → 0.5.0

package/README.md

@@ -0,0 +1,158 @@
+# deadwood-scan
+
+[![npm version](https://img.shields.io/npm/v/deadwood-scan)](https://www.npmjs.com/package/deadwood-scan)
+
+**Find the code your repo no longer calls — and prove it.** deadwood statically scans a
+JS/TS repo for dead routes, unused exports, unused dependencies and unreachable files,
+attaches **evidence** to every finding, and gives you a safe way to delete it.
+
+```bash
+npx deadwood-scan .
+```
+
+```
+☠ 31% of your routes appear dead (9 of 29)
+  7 unused exports · 2 unused dependencies
+
+  DELETE /api/legacy/export   legacy.ts:87    70% │ capped
+    ├─ no client path matches this route
+    ├─ marked @deprecated
+    ├─ last commit touching this file: 14 months ago
+    └─ no runtime evidence — connect telemetry
+
+  export draftCheckout        pay.ts:12       50% │ demoted
+    └─ modified 3 days ago — likely work in progress
+
+  → deadwood clean — review & remove these interactively (one revertable commit each)
+```
+
+Zero network calls. Zero telemetry. Nothing leaves your machine.
+
+## Why it's different
+
+- **Evidence, not verdicts.** Every finding carries the signals that produced it, with
+  signed weights. Anything the analyzer can't resolve _lowers_ confidence instead of
+  being ignored — so hidden callers (dynamic imports, string dispatch, cron manifests)
+  demote a finding rather than causing a false positive.
+- **It says "appears dead", never "is dead".** Static confidence is hard-capped (70 for
+  routes, 85 for the rest). Only runtime evidence lifts the cap.
+- **Your git history is evidence.** Code untouched for a year ranks up; code you touched
+  this week is demoted as work-in-progress. Works from your first commit, offline.
+
+## Commands
+
+### Scan
+
+```bash
+deadwood [path]                      # the shock report
+deadwood --json                      # machine-readable ScanResult (schemaVersion 1)
+deadwood --md                        # markdown, for PR comments / Slack
+deadwood --fail-on high              # CI gate: exit 1 when tripped
+```
+
+### `--diff-base <ref>` — the PR delta gate
+
+Report only what a change **introduces**, not the whole inventory. This is the loop that
+stops AI-generated orphan code at the door:
+
+```bash
+deadwood --diff-base main                     # "+2 introduced · −1 resolved"
+deadwood --diff-base origin/main --fail-on medium   # CI: you may not ADD dead code
+```
+
+The base ref is scanned in a temporary git worktree; the diff is exact (finding ids are
+stable across scans by design). `--fail-on` then gates the _delta_, not the backlog — so
+a legacy repo can adopt the gate on day one without fixing everything first.
+
+### `deadwood clean` — guided deletion
+
+```bash
+deadwood clean --dry-run     # print the plan, touch nothing
+deadwood clean               # interactive: [d]elete / [s]kip / [a]ll / [q]uit
+deadwood clean --yes         # non-interactive, medium+ confidence
+```
+
+Each accepted removal is applied **and committed on its own**, so `git revert <sha>` is
+always the undo. It only offers removals it can _prove_ (whole unreachable files, unused
+dependencies); routes and exports are listed for manual review, never auto-edited. It
+refuses to run on a dirty working tree.
+
+### `deadwood explain <query>`
+
+One finding, fully unpacked — every evidence line with its signed weight and source, the
+confidence arithmetic including the active cap, and what would make the code live.
+
+### `deadwood mcp`
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server over stdio, so your
+coding agents (Cursor, Claude Code, Copilot) can consult the dead-code map _before_
+writing or deleting. Tools: `deadwood_scan`, `deadwood_findings`.
+
+```jsonc
+// .cursor/mcp.json or claude_desktop_config.json
+{ "mcpServers": { "deadwood": { "command": "npx", "args": ["deadwood-scan", "mcp", "."] } } }
+```
+
+### `deadwood badge` · `--watch`
+
+```bash
+deadwood badge --output deadwood-badge.svg   # self-hosted status SVG (no external service)
+deadwood --watch                              # re-scan on save: +introduced / −resolved
+```
+
+## Flags
+
+| flag                                                     |                                                           |
+| -------------------------------------------------------- | --------------------------------------------------------- |
+| `--json` / `--md`                                        | machine-readable / markdown output                        |
+| `--fail-on <high\|medium\|high:N>`                       | CI gate (exit 1); with `--diff-base`, gates the delta     |
+| `--diff-base <ref>`                                      | report only findings introduced since this git ref        |
+| `--watch`                                                | re-scan on save, report the delta per change              |
+| `--min-confidence <low\|medium\|high>`                   | hide findings below this level (never affects the gate)   |
+| `--entry <file...>`                                      | extra entry points — the false-positive escape hatch      |
+| `--category <…>` · `--workspace <…>` · `--framework <…>` | narrow the scan                                           |
+| `--include` / `--exclude <glob...>`                      | extra globs                                               |
+| `--no-default-excludes`                                  | also report on `generated/`, `examples/`, fixtures, mocks |
+| `--no-git`                                               | skip git-history evidence                                 |
+| `--no-color`                                             | plain output                                              |
+
+**Exit codes:** `0` clean · `1` `--fail-on` gate tripped · `2` scan error.
+
+## Configuration (in-repo, versioned with your code)
+
+`deadwood.config.json`:
+
+```json
+{
+  "entries": ["scripts/cron-job.ts"],
+  "exclude": ["legacy/**"],
+  "publicApi": ["src/index.ts"]
+}
+```
+
+`entries` = extra entry points. `exclude` = extra globs. **`publicApi`** = files whose
+exports are your published API surface: external consumers are invisible to static
+analysis, so their unused-export findings are demoted with spare evidence — kept visible,
+never shouted.
+
+```
+# .deadwoodignore  (one glob per line, '#' comments)
+vendor/**
+```
+
+## Evidence signals
+
+Findings score as `clamp(0, cap, Σ evidence weights)`:
+
+|                                                          |                                                                                                                                                                                                                           |
+| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **kill** (raise confidence)                              | route registered but nothing references its path · marked `@deprecated` · reachable only from tests · file untouched for a year · last author gone 6+ months · introduced once, never revisited                           |
+| **spare** (lower confidence — a hidden caller may exist) | dynamic import may load this directory · symbol in a string-dispatch table · referenced by a package script, build config or CI/cron manifest · declared public API · **modified in the last 30 days (work in progress)** |
+| **runtime** (lifts the cap — the paid tiers)             | dev/staging/e2e traffic seen (→ 90) · production traffic seen, or coverage-guaranteed zero requests in 90 days (→ 100, _confirmed dead_)                                                                                  |
+
+## Beyond the CLI
+
+- **GitHub App** — a shock report on every PR, findings that upgrade in place as evidence arrives.
+- **[deadwood-express-probe](https://www.npmjs.com/package/deadwood-express-probe)** — report aggregate route usage (templates, counts, windows — never a concrete URL) from a dev server, e2e suite, or production. That's what turns "appears dead" into _confirmed dead_.
+
+See [deadwood.dev](https://github.com/BilalBaheer/deadwood-Cli) · MIT.