deadwood-scan 0.3.0 → 0.5.0

package/dist/index.js

@@ -2,10 +2,12 @@
 
 // src/index.ts
 import { createRequire } from "module";
-import process from "process";
+import nodePath from "path";
+import fs13 from "fs";
+import process4 from "process";
 import { Command, Option } from "commander";
 import ora from "ora";
-import pc2 from "picocolors";
+import pc6 from "picocolors";
 
 // ../core/src/index.ts
 import fs9 from "fs";
@@ -719,8 +721,8 @@ function discoverEntryPoints(unit, scannedFiles, warnings) {
 function resolveEntryRef(unitDir, ref, scannedFiles) {
   const accept = (p) => {
     if (!p) return void 0;
-    const posix = toPosix(p);
-    return !scannedFiles || scannedFiles.has(posix) ? posix : void 0;
+    const posix2 = toPosix(p);
+    return !scannedFiles || scannedFiles.has(posix2) ? posix2 : void 0;
   };
   const clean = ref.replace(/^\.\//, "");
   const direct = accept(tryFile(path4.join(unitDir, clean)));
@@ -1010,6 +1012,49 @@ var SIGNAL_LIST = [
     30,
     "Re-exported by a package entry point; external consumers are invisible to static analysis"
   ),
+  // Git-history signals (git:*) — computed from the repo's own history, which
+  // the CLI collects and injects via scan options (core never spawns git; see
+  // evidence/gitHistory.ts). Deliberately `source: 'static'` so the static cap
+  // still applies: history sharpens confidence, only PRODUCTION lifts the cap.
+  kill("git:untouched-1y", 10, "No commit has touched this file in over a year"),
+  kill(
+    "git:author-departed",
+    10,
+    "The last author of this file has had no repo activity for 6+ months"
+  ),
+  kill(
+    "git:never-modified-since-introduction",
+    5,
+    "Introduced in a single commit 6+ months ago and never touched again"
+  ),
+  spare(
+    "git:recently-modified",
+    15,
+    "This file was modified in the last 30 days \u2014 likely active work"
+  ),
+  // Dev/staging/test-traffic evidence (dev:*) — runtime evidence from
+  // NON-production collectors (a probe pointed at a dev server or running
+  // during an e2e suite). Only the spare direction ships for now: traffic
+  // seen anywhere proves the route is wired (revival errs safe); a dev
+  // zero-requests kill would need its own coverage-guarantee story.
+  {
+    id: "dev:request-seen",
+    source: "development",
+    direction: "spare",
+    weight: -60,
+    description: "Traffic observed in a development/staging/test environment"
+  },
+  {
+    // A small nudge with its own coverage guarantee: emitted only when an
+    // ACTIVE non-production collector (fresh AND it reported real traffic in
+    // the window — the suite provably ran) watched the route and never hit
+    // it. Silence from an idle collector proves nothing and earns nothing.
+    id: "dev:zero-requests-in-tests",
+    source: "development",
+    direction: "kill",
+    weight: 10,
+    description: "Watched by an active non-production collector that reported traffic, yet this route was never hit"
+  },
   // Reserved for the paid evidence layer — registered now so the scorer and
   // JSON contract already understand them.
   {
@@ -1041,6 +1086,8 @@ var STATIC_CAPS = {
   "unreachable-file": 85
 };
 var STATIC_CAP_REASON = "no runtime evidence \u2014 connect telemetry to confirm";
+var DEV_CAP = 90;
+var DEV_CAP_REASON = "dev traffic cannot confirm \u2014 production evidence completes it";
 function evidenceFor(signalId, detail, location) {
   const spec = SIGNALS.get(signalId);
   if (!spec) {
@@ -1789,9 +1836,6 @@ function findPathMatch2(routePath, literals) {
   );
 }
 
-// ../core/src/evidence/dynamicImports.ts
-import path10 from "path";
-
 // ../core/src/evidence/types.ts
 function addOnce(finding, evidence) {
   if (!finding.evidence.some((e) => e.signal === evidence.signal)) {
@@ -1799,7 +1843,104 @@ function addOnce(finding, evidence) {
   }
 }
 
+// ../core/src/evidence/gitHistory.ts
+var DAY = 24 * 60 * 60;
+var STALE_SECONDS = 365 * DAY;
+var FRESH_SECONDS = 30 * DAY;
+var DEPARTED_SECONDS = 180 * DAY;
+function ageInWords(seconds) {
+  const days = Math.floor(seconds / DAY);
+  if (days < 1) return "today";
+  if (days === 1) return "yesterday";
+  if (days < 60) return `${days} days ago`;
+  return `${Math.floor(days / 30)} months ago`;
+}
+function gitHistory(facts) {
+  return {
+    name: "git-history",
+    provide(_ctx, findings) {
+      if (!facts) return;
+      for (const finding of findings) {
+        if (finding.category === "unused-dependency") continue;
+        const last = facts.lastModified[finding.location.file];
+        if (last === void 0) {
+          if (!facts.truncated) {
+            addOnce(
+              finding,
+              evidenceFor("git:recently-modified", "not committed yet \u2014 likely work in progress")
+            );
+          }
+          continue;
+        }
+        const age = facts.now - last;
+        if (age <= FRESH_SECONDS) {
+          addOnce(
+            finding,
+            evidenceFor(
+              "git:recently-modified",
+              `last commit touching this file was ${ageInWords(age)}`
+            )
+          );
+          continue;
+        }
+        if (age >= STALE_SECONDS) {
+          addOnce(
+            finding,
+            evidenceFor(
+              "git:untouched-1y",
+              `last commit touching this file was ${ageInWords(age)}`
+            )
+          );
+        }
+        const author = facts.lastAuthor?.[finding.location.file];
+        const active = author !== void 0 ? facts.authorLastActive?.[author] : void 0;
+        if (active !== void 0 && facts.now - active >= DEPARTED_SECONDS) {
+          addOnce(
+            finding,
+            evidenceFor(
+              "git:author-departed",
+              `last edited by an author with no repo activity for ${ageInWords(facts.now - active)}`
+            )
+          );
+        }
+        if (!facts.truncated && facts.singleCommit?.[finding.location.file] && age >= DEPARTED_SECONDS) {
+          addOnce(
+            finding,
+            evidenceFor(
+              "git:never-modified-since-introduction",
+              `introduced ${ageInWords(age)} and never touched again`
+            )
+          );
+        }
+      }
+    }
+  };
+}
+
+// ../core/src/evidence/publicApi.ts
+function publicApi(files) {
+  const declared = new Set(files ?? []);
+  return {
+    name: "public-api",
+    provide(_ctx, findings) {
+      if (declared.size === 0) return;
+      for (const finding of findings) {
+        if (finding.category !== "unused-export") continue;
+        if (!declared.has(finding.location.file)) continue;
+        addOnce(
+          finding,
+          evidenceFor(
+            "static:public-api-reexport",
+            "declared public API in deadwood.config.json \u2014 external consumers are invisible to static analysis"
+          )
+        );
+      }
+    }
+  };
+}
+
 // ../core/src/evidence/dynamicImports.ts
+import path10 from "path";
 var dynamicImports = {
   name: "dynamic-imports",
   provide(ctx, findings) {
@@ -2166,12 +2307,13 @@ function levelFor(score) {
 }
 function scoreFinding(category, evidence) {
   const raw = evidence.reduce((sum, e) => sum + e.weight, 0);
-  const allStatic = evidence.every((e) => e.source === "static");
-  const cap = allStatic ? STATIC_CAPS[category] : 100;
+  const hasProduction = evidence.some((e) => e.source === "production" || e.source === "tombstone");
+  const hasDev = evidence.some((e) => e.source === "development");
+  const [cap, reason] = hasProduction ? [100, ""] : hasDev ? [DEV_CAP, DEV_CAP_REASON] : [STATIC_CAPS[category], STATIC_CAP_REASON];
   const score = Math.max(0, Math.min(cap, Math.round(raw)));
   const result = { score, level: levelFor(score) };
-  if (allStatic && raw > cap) {
-    result.capped = { at: cap, reason: STATIC_CAP_REASON };
+  if (!hasProduction && raw > cap) {
+    result.capped = { at: cap, reason };
   }
   return result;
 }
@@ -2356,7 +2498,11 @@ async function scan(options) {
     rel: (file) => relPosix(root, file),
     abs: (relPath) => `${root}/${relPath}`
   };
-  for (const provider of PROVIDERS) {
+  for (const provider of [
+    ...PROVIDERS,
+    gitHistory(options.gitFacts),
+    publicApi(options.publicApi)
+  ]) {
     provider.provide(providerCtx, findings);
   }
   for (const finding of findings) {
@@ -2495,6 +2641,763 @@ function evaluateFailOn(findings, spec) {
   return { count, tripped: count >= spec.min };
 }
 
+// src/git.ts
+import { spawnSync } from "child_process";
+var MAX_COMMITS = 5e4;
+var MAX_BUFFER = 128 * 1024 * 1024;
+var MARK = "
";
+var SEP = "";
+function collectGitFacts(dir, now = /* @__PURE__ */ new Date()) {
+  const out = runGit(dir, [
+    "log",
+    `--max-count=${MAX_COMMITS}`,
+    "--format=%x01%ct%x02%ae",
+    "--name-only",
+    "--no-renames",
+    "--relative",
+    "--",
+    "."
+  ]);
+  if (out === void 0) return void 0;
+  const lastModified = {};
+  const lastAuthor = {};
+  const authorLastActive = {};
+  const commitCount = {};
+  let commits = 0;
+  let current = 0;
+  let currentAuthor = "";
+  for (const rawLine of out.split("\n")) {
+    const line = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine;
+    if (line.length === 0) continue;
+    if (line.startsWith(MARK)) {
+      const [tsRaw, author = ""] = line.slice(1).split(SEP);
+      const ts7 = Number(tsRaw);
+      if (!Number.isFinite(ts7)) continue;
+      current = ts7;
+      currentAuthor = author;
+      commits++;
+      if (author && authorLastActive[author] === void 0) authorLastActive[author] = ts7;
+      continue;
+    }
+    if (current === 0) continue;
+    const path15 = normalizeGitPath(line);
+    if (lastModified[path15] === void 0) {
+      lastModified[path15] = current;
+      if (currentAuthor) lastAuthor[path15] = currentAuthor;
+    }
+    commitCount[path15] = (commitCount[path15] ?? 0) + 1;
+  }
+  if (commits === 0) return void 0;
+  const singleCommit = {};
+  for (const [path15, count] of Object.entries(commitCount)) {
+    if (count === 1) singleCommit[path15] = true;
+  }
+  return {
+    lastModified,
+    truncated: commits >= MAX_COMMITS,
+    now: Math.floor(now.getTime() / 1e3),
+    lastAuthor,
+    authorLastActive,
+    singleCommit
+  };
+}
+function normalizeGitPath(line) {
+  if (line.startsWith('"') && line.endsWith('"') && line.length >= 2) {
+    try {
+      return JSON.parse(line);
+    } catch {
+      return line;
+    }
+  }
+  return line;
+}
+function runGit(dir, args) {
+  try {
+    const res = spawnSync("git", ["-C", dir, ...args], {
+      encoding: "utf8",
+      maxBuffer: MAX_BUFFER,
+      windowsHide: true
+    });
+    if (res.error || res.status !== 0 || typeof res.stdout !== "string") return void 0;
+    return res.stdout;
+  } catch {
+    return void 0;
+  }
+}
+
+// src/clean.ts
+import fs10 from "fs";
+import path12 from "path";
+import readline from "readline/promises";
+import { spawnSync as spawnSync2 } from "child_process";
+import process from "process";
+import pc from "picocolors";
+var LEVEL_RANK2 = { low: 0, medium: 1, high: 2 };
+async function runClean(dir, opts) {
+  const root = path12.resolve(dir);
+  const useColor = opts.color && process.stdout.isTTY === true;
+  const paint = {
+    dead: (s) => useColor ? pc.red(s) : s,
+    ok: (s) => useColor ? pc.green(s) : s,
+    dim: (s) => useColor ? pc.dim(s) : s,
+    bold: (s) => useColor ? pc.bold(s) : s
+  };
+  if (!opts.dryRun && !opts.yes && process.stdin.isTTY !== true) {
+    process.stderr.write("error: interactive clean needs a TTY \u2014 use --yes or --dry-run\n");
+    process.exitCode = 2;
+    return;
+  }
+  if (opts.commit && !opts.dryRun) {
+    if (!isGitRepo(root)) {
+      process.stderr.write(
+        "error: not a git repository \u2014 deadwood clean commits each removal so it is revertable.\n       Use --no-commit to delete without commits (you own the undo story then).\n"
+      );
+      process.exitCode = 2;
+      return;
+    }
+    if (!workingTreeClean(root)) {
+      process.stderr.write(
+        "error: working tree is not clean \u2014 commit or stash first, so each removal is its own revertable commit.\n"
+      );
+      process.exitCode = 2;
+      return;
+    }
+  }
+  process.stderr.write("scanning\u2026\n");
+  const gitFacts = opts.git ? collectGitFacts(root) : void 0;
+  const result = await scan({ path: root, gitFacts });
+  const min = LEVEL_RANK2[opts.minConfidence];
+  const eligible = result.findings.filter((f) => LEVEL_RANK2[f.confidence.level] >= min);
+  const removals = [];
+  let unsupported = 0;
+  for (const f of eligible) {
+    const removal = planRemoval(root, f, result);
+    if (removal) removals.push(removal);
+    else if (f.category === "dead-route" || f.category === "unused-export") unsupported++;
+  }
+  if (removals.length === 0) {
+    process.stdout.write(
+      `Nothing removable at ${opts.minConfidence}+ confidence.` + (unsupported > 0 ? ` (${unsupported} route/export finding${unsupported === 1 ? "" : "s"} need manual review \u2014 automated line surgery isn't provable yet.)` : "") + "\n"
+    );
+    return;
+  }
+  process.stdout.write(
+    `${paint.bold(String(removals.length))} removable finding${removals.length === 1 ? "" : "s"} at ${opts.minConfidence}+ confidence` + (unsupported > 0 ? paint.dim(` (+${unsupported} route/export need manual review)`) : "") + "\n\n"
+  );
+  const rl = !opts.dryRun && !opts.yes ? readline.createInterface({ input: process.stdin, output: process.stderr }) : void 0;
+  let acceptAll = Boolean(opts.yes);
+  let removed = 0;
+  let skipped = 0;
+  let failed = 0;
+  try {
+    for (const removal of removals) {
+      const f = removal.finding;
+      process.stdout.write(
+        `${paint.dead(describeTarget(f.target))}  ${paint.dim(`${f.location.file}:${f.location.line}`)}  ${f.confidence.score}% ${f.confidence.level}
+`
+      );
+      for (const e of f.evidence.slice(0, 3)) {
+        process.stdout.write(paint.dim(`  ${e.direction === "spare" ? "~" : "-"} ${e.detail}
+`));
+      }
+      process.stdout.write(`  \u2192 ${removal.describe}
+`);
+      if (opts.dryRun) {
+        process.stdout.write(paint.dim("  dry-run: not applied\n\n"));
+        continue;
+      }
+      let accepted = acceptAll;
+      if (!accepted && rl) {
+        const answer = (await rl.question("  [d]elete / [s]kip / [a]ll remaining / [q]uit > ")).trim().toLowerCase();
+        if (answer === "q") break;
+        if (answer === "a") {
+          acceptAll = true;
+          accepted = true;
+        } else {
+          accepted = answer === "d" || answer === "y";
+        }
+      }
+      if (!accepted) {
+        skipped++;
+        process.stdout.write(paint.dim("  skipped\n\n"));
+        continue;
+      }
+      try {
+        const staged = removal.apply();
+        if (opts.commit) {
+          commitRemoval(root, staged, `chore(deadwood): remove ${describeTarget(f.target)}`);
+        }
+        removed++;
+        process.stdout.write(paint.ok(`  removed${opts.commit ? " + committed" : ""}
+
+`));
+      } catch (err) {
+        failed++;
+        process.stderr.write(
+          `  error: ${err instanceof Error ? err.message : String(err)} \u2014 leaving it in place
+
+`
+        );
+      }
+    }
+  } finally {
+    rl?.close();
+  }
+  if (opts.dryRun) {
+    process.stdout.write(
+      `dry run: ${removals.length} removal${removals.length === 1 ? "" : "s"} planned, nothing touched.
+`
+    );
+    return;
+  }
+  process.stdout.write(
+    `${paint.ok(String(removed))} removed, ${skipped} skipped${failed > 0 ? `, ${paint.dead(String(failed))} failed` : ""}.` + (removed > 0 && opts.commit ? " Each removal is its own commit \u2014 `git revert <sha>` undoes any of them." : "") + "\n"
+  );
+  if (failed > 0) process.exitCode = 2;
+}
+function planRemoval(root, f, result) {
+  if (f.category === "unreachable-file" && f.target.kind === "file") {
+    const abs = containedPath(root, f.target.file);
+    if (!abs || !fs10.existsSync(abs)) return null;
+    const file = f.target.file;
+    return {
+      finding: f,
+      describe: `delete file ${file}`,
+      apply: () => {
+        fs10.rmSync(abs);
+        return [file];
+      }
+    };
+  }
+  if (f.category === "unused-dependency" && f.target.kind === "dependency") {
+    const pkgRel = f.location.file;
+    const abs = containedPath(root, pkgRel);
+    if (!abs || !fs10.existsSync(abs) || !pkgRel.endsWith("package.json")) return null;
+    const { name, depType } = f.target;
+    return {
+      finding: f,
+      describe: `remove ${name} from ${depType} in ${pkgRel}`,
+      apply: () => {
+        removeDependency(abs, name, depType);
+        return [pkgRel];
+      }
+    };
+  }
+  void result;
+  return null;
+}
+function containedPath(root, rel) {
+  const abs = path12.resolve(root, rel);
+  const normRoot = path12.resolve(root) + path12.sep;
+  return abs.startsWith(normRoot) ? abs : void 0;
+}
+function removeDependency(pkgPath, name, depType) {
+  const raw = fs10.readFileSync(pkgPath, "utf8");
+  const pkg2 = JSON.parse(raw);
+  const deps = pkg2[depType];
+  if (typeof deps !== "object" || deps === null || !(name in deps)) {
+    throw new Error(`${name} not found in ${depType}`);
+  }
+  delete deps[name];
+  const indent = /^([ \t]+)"/m.exec(raw)?.[1] ?? "  ";
+  const trailingNewline = raw.endsWith("\n") ? "\n" : "";
+  fs10.writeFileSync(pkgPath, JSON.stringify(pkg2, null, indent) + trailingNewline);
+}
+function isGitRepo(dir) {
+  return runGit2(dir, ["rev-parse", "--is-inside-work-tree"])?.trim() === "true";
+}
+function workingTreeClean(dir) {
+  const out = runGit2(dir, ["status", "--porcelain"]);
+  return out !== void 0 && out.trim().length === 0;
+}
+function commitRemoval(root, relPaths, message) {
+  const add = spawnSync2("git", ["-C", root, "add", "--", ...relPaths], {
+    windowsHide: true,
+    encoding: "utf8"
+  });
+  if (add.status !== 0) throw new Error(`git add failed: ${firstLine(add.stderr)}`);
+  const commit = spawnSync2("git", ["-C", root, "commit", "-q", "-m", message, "--", ...relPaths], {
+    windowsHide: true,
+    encoding: "utf8"
+  });
+  if (commit.status !== 0) throw new Error(`git commit failed: ${firstLine(commit.stderr)}`);
+}
+function firstLine(s) {
+  const line = (s ?? "").split("\n").find((l) => l.trim().length > 0);
+  return line?.trim() ?? "unknown git error";
+}
+function runGit2(dir, args) {
+  try {
+    const res = spawnSync2("git", ["-C", dir, ...args], { encoding: "utf8", windowsHide: true });
+    if (res.error || res.status !== 0) return void 0;
+    return res.stdout;
+  } catch {
+    return void 0;
+  }
+}
+
+// src/repoConfig.ts
+import fs11 from "fs";
+import path13 from "path";
+var EMPTY = { entries: [], exclude: [], publicApi: [], warnings: [] };
+function loadRepoConfig(root) {
+  const out = { ...EMPTY, entries: [], exclude: [], publicApi: [], warnings: [] };
+  const cfgPath = path13.join(root, "deadwood.config.json");
+  if (fs11.existsSync(cfgPath)) {
+    try {
+      const raw = JSON.parse(fs11.readFileSync(cfgPath, "utf8"));
+      out.entries = stringArray(raw.entries, "entries", out.warnings);
+      out.exclude = stringArray(raw.exclude, "exclude", out.warnings);
+      out.publicApi = stringArray(raw.publicApi, "publicApi", out.warnings).map(posix);
+    } catch (err) {
+      out.warnings.push(
+        `deadwood.config.json could not be parsed (${err instanceof Error ? err.message : "bad JSON"}); ignoring it.`
+      );
+    }
+  }
+  const ignorePath = path13.join(root, ".deadwoodignore");
+  if (fs11.existsSync(ignorePath)) {
+    try {
+      for (const line of fs11.readFileSync(ignorePath, "utf8").split("\n")) {
+        const glob3 = line.trim();
+        if (glob3.length === 0 || glob3.startsWith("#")) continue;
+        if (glob3.startsWith("!")) {
+          out.warnings.push(
+            `.deadwoodignore: negations ('!') are not supported \u2014 '${glob3}' skipped.`
+          );
+          continue;
+        }
+        out.exclude.push(glob3);
+      }
+    } catch {
+      out.warnings.push(".deadwoodignore could not be read; ignoring it.");
+    }
+  }
+  return out;
+}
+function stringArray(value, field, warnings) {
+  if (value === void 0) return [];
+  if (Array.isArray(value) && value.every((v) => typeof v === "string")) return value;
+  warnings.push(`deadwood.config.json: '${field}' must be an array of strings; ignoring it.`);
+  return [];
+}
+function posix(p) {
+  return p.replace(/\\/g, "/");
+}
+
+// src/delta.ts
+import { mkdtempSync, rmSync } from "fs";
+import os from "os";
+import path14 from "path";
+import { spawnSync as spawnSync3 } from "child_process";
+import pc2 from "picocolors";
+function diffFindings(base, head, baseRef) {
+  const baseIds = new Set(base.findings.map((f) => f.id));
+  const headIds = new Set(head.findings.map((f) => f.id));
+  return {
+    baseRef,
+    added: head.findings.filter((f) => !baseIds.has(f.id)),
+    resolved: base.findings.filter((f) => !headIds.has(f.id))
+  };
+}
+async function scanBaseRef(root, ref, options) {
+  const verify = spawnSync3(
+    "git",
+    ["-C", root, "rev-parse", "--verify", "--quiet", `${ref}^{commit}`],
+    {
+      encoding: "utf8",
+      windowsHide: true
+    }
+  );
+  if (verify.error) throw new Error("git is not available \u2014 --diff-base needs git");
+  if (verify.status !== 0) {
+    throw new Error(`--diff-base '${ref}' is not a commit in this repository`);
+  }
+  const tmp = mkdtempSync(path14.join(os.tmpdir(), "deadwood-base-"));
+  const add = spawnSync3("git", ["-C", root, "worktree", "add", "--detach", "--force", tmp, ref], {
+    encoding: "utf8",
+    windowsHide: true
+  });
+  if (add.status !== 0) {
+    rmSync(tmp, { recursive: true, force: true });
+    throw new Error(`could not materialize '${ref}': ${(add.stderr ?? "").trim().split("\n")[0]}`);
+  }
+  try {
+    return await scan({ ...options, path: tmp });
+  } finally {
+    spawnSync3("git", ["-C", root, "worktree", "remove", "--force", tmp], { windowsHide: true });
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}
+function renderDeltaPretty(delta, useColor) {
+  const c = pc2.createColors(useColor);
+  const lines = [""];
+  lines.push(`  ${c.bold("\u2620 deadwood delta")} ${c.dim(`vs ${delta.baseRef}`)}`);
+  lines.push(`  ${c.dim("\u2500".repeat(72))}`);
+  const added = delta.added.length;
+  const resolved = delta.resolved.length;
+  lines.push(
+    `  ${added > 0 ? c.red(`+${added} introduced`) : c.green("+0 introduced")}  \xB7  ${resolved > 0 ? c.green(`\u2212${resolved} resolved`) : c.dim("\u22120 resolved")}`
+  );
+  lines.push("");
+  for (const f of delta.added) {
+    lines.push(
+      `  ${c.red("+")} ${c.bold(describeTarget(f.target))}  ${c.dim(`${f.location.file}:${f.location.line}`)}  ${f.confidence.score}% ${f.confidence.level}`
+    );
+    const top = [...f.evidence].sort((a, b) => Math.abs(b.weight) - Math.abs(a.weight)).slice(0, 2);
+    for (const e of top) lines.push(`      ${c.dim(e.detail)}`);
+  }
+  if (added > 0) lines.push("");
+  for (const f of delta.resolved) {
+    lines.push(`  ${c.green("\u2713")} ${c.dim(`resolved: ${describeTarget(f.target)}`)}`);
+  }
+  if (added === 0 && resolved === 0) {
+    lines.push(`  ${c.green("\u2713")} This change introduces no new dead code.`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+// src/watch.ts
+import fs12 from "fs";
+import process2 from "process";
+import pc3 from "picocolors";
+var IGNORE2 = /(^|[\\/])(node_modules|\.git|dist|build|out|coverage|\.next)([\\/]|$)/;
+var DEBOUNCE_MS = 400;
+async function runWatch(dir, buildOptions, useColor) {
+  const c = pc3.createColors(useColor);
+  const stamp = () => (/* @__PURE__ */ new Date()).toTimeString().slice(0, 8);
+  let prev = await scan(buildOptions());
+  process2.stdout.write(
+    `${c.dim(`[${stamp()}]`)} watching ${dir} \u2014 ${headline(prev)} ${c.dim("(ctrl-c to stop)")}
+`
+  );
+  let timer;
+  let scanning = false;
+  let dirty = false;
+  const tick = async () => {
+    if (scanning) {
+      dirty = true;
+      return;
+    }
+    scanning = true;
+    try {
+      const next = await scan(buildOptions());
+      const delta = diffFindings(prev, next, "previous scan");
+      if (delta.added.length === 0 && delta.resolved.length === 0) {
+        process2.stdout.write(
+          `${c.dim(`[${stamp()}]`)} ${c.dim("no change \u2014")} ${headline(next)}
+`
+        );
+      } else {
+        const parts = [
+          delta.added.length > 0 ? c.red(`+${delta.added.length}`) : void 0,
+          delta.resolved.length > 0 ? c.green(`\u2212${delta.resolved.length}`) : void 0
+        ].filter(Boolean);
+        process2.stdout.write(`${c.dim(`[${stamp()}]`)} ${parts.join(" ")} \u2014 ${headline(next)}
+`);
+        for (const f of delta.added) {
+          process2.stdout.write(
+            `  ${c.red("+")} ${describeTarget(f.target)} ${c.dim(`${f.location.file}:${f.location.line} \xB7 ${f.confidence.score}%`)}
+`
+          );
+        }
+        for (const f of delta.resolved) {
+          process2.stdout.write(
+            `  ${c.green("\u2713")} ${c.dim(`resolved: ${describeTarget(f.target)}`)}
+`
+          );
+        }
+      }
+      prev = next;
+    } catch (err) {
+      process2.stderr.write(
+        `watch: scan failed: ${err instanceof Error ? err.message : String(err)}
+`
+      );
+    } finally {
+      scanning = false;
+      if (dirty) {
+        dirty = false;
+        void tick();
+      }
+    }
+  };
+  try {
+    fs12.watch(dir, { recursive: true }, (_event, filename) => {
+      if (filename && IGNORE2.test(String(filename))) return;
+      clearTimeout(timer);
+      timer = setTimeout(() => void tick(), DEBOUNCE_MS);
+    });
+  } catch (err) {
+    process2.stderr.write(
+      `error: --watch needs recursive fs.watch (${err instanceof Error ? err.message : String(err)})
+`
+    );
+    process2.exitCode = 2;
+    return;
+  }
+  await new Promise(() => void 0);
+}
+function headline(r) {
+  const flagged = r.findings.filter((f) => f.confidence.score >= 50).length;
+  return `${flagged} flagged finding${flagged === 1 ? "" : "s"}`;
+}
+
+// src/explain.ts
+import pc4 from "picocolors";
+var CAPS = {
+  "dead-route": 70,
+  "unused-export": 85,
+  "unused-dependency": 85,
+  "unreachable-file": 85
+};
+var MAKE_IT_LIVE = {
+  "dead-route": "a string literal in the repo matching its path, a caller manifest (cron/CI/k8s), or observed traffic (dev retires it; production confirms either way)",
+  "unused-export": "any import of the symbol from a reachable file",
+  "unused-dependency": "any import of the package (or a config/script reference we can see)",
+  "unreachable-file": "an import chain from any entry point, or listing it via --entry / deadwood.config.json"
+};
+function findMatches(result, query) {
+  const q = query.toLowerCase();
+  return result.findings.filter(
+    (f) => f.id.startsWith(query) || describeTarget(f.target).toLowerCase().includes(q) || f.location.file.toLowerCase().includes(q)
+  );
+}
+function renderExplanation(f, useColor) {
+  const c = pc4.createColors(useColor);
+  const lines = [""];
+  lines.push(`  ${c.bold(describeTarget(f.target))}`);
+  lines.push(
+    `  ${c.dim(`${f.category} \xB7 ${f.location.file}:${f.location.line} \xB7 workspace ${f.workspace} \xB7 id ${f.id.slice(0, 12)}\u2026`)}`
+  );
+  lines.push("");
+  lines.push(`  ${c.dim("evidence (kill raises confidence, spare lowers it):")}`);
+  let raw = 0;
+  for (const e of f.evidence) {
+    raw += e.weight;
+    const sign = e.weight >= 0 ? `+${e.weight}` : `${e.weight}`;
+    const mark = e.direction === "kill" ? c.red(sign.padStart(4)) : c.green(sign.padStart(4));
+    lines.push(`  ${mark}  ${c.dim(`[${e.source}]`)} ${e.detail}`);
+  }
+  lines.push("");
+  const cap = capFor(f);
+  const capped = raw > cap;
+  lines.push(
+    `  ${c.dim("score:")} \u03A3 weights = ${raw}${capped ? ` \u2192 capped at ${cap}` : ""} \u21D2 ${c.bold(
+      `${f.confidence.score}% ${f.confidence.level}`
+    )}`
+  );
+  if (f.confidence.capped) {
+    lines.push(`  ${c.dim(`cap reason: ${f.confidence.capped.reason}`)}`);
+  }
+  lines.push("");
+  lines.push(`  ${c.dim("what would make it live:")} ${MAKE_IT_LIVE[f.category]}`);
+  lines.push("");
+  return lines.join("\n");
+}
+function capFor(f) {
+  if (f.evidence.some((e) => e.source === "production" || e.source === "tombstone")) return 100;
+  if (f.evidence.some((e) => e.source === "development")) return 90;
+  return CAPS[f.category];
+}
+function renderCandidates(matches, useColor) {
+  const c = pc4.createColors(useColor);
+  const lines = [`  ${matches.length} findings match \u2014 narrow the query:`, ""];
+  for (const f of matches.slice(0, 10)) {
+    lines.push(
+      `  ${c.dim(f.id.slice(0, 8))}  ${describeTarget(f.target)}  ${c.dim(f.location.file)}`
+    );
+  }
+  if (matches.length > 10) lines.push(c.dim(`  \u2026 and ${matches.length - 10} more`));
+  lines.push("");
+  return lines.join("\n");
+}
+
+// src/badge.ts
+function buildBadge(result, svgPath = "./deadwood-badge.svg") {
+  const high = result.findings.filter((f) => f.confidence.level === "high").length;
+  const flagged = result.findings.filter((f) => f.confidence.score >= 50).length;
+  const [value, color] = high > 0 ? [`${high} high-confidence`, "#e5543f"] : flagged > 0 ? [`${flagged} flagged`, "#d0a215"] : ["clean", "#58b368"];
+  const label = "deadwood";
+  const svg = renderSvg(label, value, color);
+  return {
+    label,
+    value,
+    color,
+    svg,
+    markdown: `![deadwood](${svgPath})`
+  };
+}
+function renderSvg(label, value, color) {
+  const lw = Math.round(label.length * 6.5) + 14;
+  const vw = Math.round(value.length * 6.5) + 14;
+  const w = lw + vw;
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="20" role="img" aria-label="${label}: ${value}">
+  <rect width="${lw}" height="20" fill="#2c2f36"/>
+  <rect x="${lw}" width="${vw}" height="20" fill="${color}"/>
+  <g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="11">
+    <text x="${lw / 2}" y="14">${label}</text>
+    <text x="${lw + vw / 2}" y="14">${value}</text>
+  </g>
+</svg>
+`;
+}
+
+// src/mcp.ts
+import readline2 from "readline";
+import process3 from "process";
+var PROTOCOL_VERSION = "2024-11-05";
+var CACHE_TTL_MS = 3e4;
+var LEVEL_RANK3 = { low: 0, medium: 1, high: 2 };
+async function runMcp(buildOptions, version, io = {}) {
+  const input = io.input ?? process3.stdin;
+  const output = io.output ?? process3.stdout;
+  const send = (msg) => void output.write(JSON.stringify(msg) + "\n");
+  let cached;
+  const getResult = async () => {
+    if (cached && Date.now() - cached.at < CACHE_TTL_MS) return cached.result;
+    const result = await scan(buildOptions());
+    cached = { at: Date.now(), result };
+    return result;
+  };
+  const rl = readline2.createInterface({ input });
+  for await (const line of rl) {
+    if (line.trim().length === 0) continue;
+    let req;
+    try {
+      req = JSON.parse(line);
+    } catch {
+      send({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "parse error" } });
+      continue;
+    }
+    const id = req.id;
+    try {
+      if (req.method === "initialize") {
+        send({
+          jsonrpc: "2.0",
+          id,
+          result: {
+            protocolVersion: typeof req.params?.protocolVersion === "string" ? req.params.protocolVersion : PROTOCOL_VERSION,
+            capabilities: { tools: {} },
+            serverInfo: { name: "deadwood", version }
+          }
+        });
+      } else if (req.method?.startsWith("notifications/")) {
+      } else if (req.method === "ping") {
+        send({ jsonrpc: "2.0", id, result: {} });
+      } else if (req.method === "tools/list") {
+        send({ jsonrpc: "2.0", id, result: { tools: TOOLS } });
+      } else if (req.method === "tools/call") {
+        const name = req.params?.name;
+        const args = req.params?.arguments ?? {};
+        const result = await getResult();
+        if (name === "deadwood_scan") {
+          send(toolResult(id, summarize(result)));
+        } else if (name === "deadwood_findings") {
+          send(toolResult(id, filterFindings(result, args)));
+        } else {
+          send({
+            jsonrpc: "2.0",
+            id,
+            error: { code: -32602, message: `unknown tool: ${String(name)}` }
+          });
+        }
+      } else if (id !== void 0) {
+        send({
+          jsonrpc: "2.0",
+          id,
+          error: { code: -32601, message: `unknown method: ${req.method}` }
+        });
+      }
+    } catch (err) {
+      if (id !== void 0) {
+        send({
+          jsonrpc: "2.0",
+          id,
+          error: { code: -32e3, message: err instanceof Error ? err.message : String(err) }
+        });
+      }
+    }
+  }
+}
+var TOOLS = [
+  {
+    name: "deadwood_scan",
+    description: 'Scan the repo for dead code. Returns headline stats (routes/exports/dependencies/files: total vs flagged) and finding counts by confidence. Wording is "appears dead" \u2014 static confidence is capped by design.',
+    inputSchema: { type: "object", properties: {}, additionalProperties: false }
+  },
+  {
+    name: "deadwood_findings",
+    description: "List dead-code findings with their evidence chains. Filter by category, minimum confidence, file substring, or free-text query. Use before deleting code or to check whether a symbol/route/file is used anywhere.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        category: {
+          type: "string",
+          enum: ["dead-route", "unused-export", "unused-dependency", "unreachable-file"]
+        },
+        minConfidence: { type: "string", enum: ["low", "medium", "high"] },
+        file: { type: "string", description: "substring of the finding file path" },
+        query: { type: "string", description: "substring of the finding target" },
+        limit: { type: "number" }
+      },
+      additionalProperties: false
+    }
+  }
+];
+function toolResult(id, payload) {
+  return {
+    jsonrpc: "2.0",
+    id,
+    result: { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] }
+  };
+}
+function summarize(r) {
+  const by = (lv) => r.findings.filter((f) => f.confidence.level === lv).length;
+  return {
+    tool: r.tool,
+    filesScanned: r.stats.filesScanned,
+    stats: r.stats,
+    findings: { total: r.findings.length, high: by("high"), medium: by("medium"), low: by("low") },
+    note: 'Static confidence is capped (routes 70, others 85) \u2014 findings "appear" dead; only runtime evidence confirms.'
+  };
+}
+function filterFindings(r, args) {
+  let findings = r.findings;
+  if (typeof args.category === "string")
+    findings = findings.filter((f) => f.category === args.category);
+  if (typeof args.minConfidence === "string" && args.minConfidence in LEVEL_RANK3) {
+    const min = LEVEL_RANK3[args.minConfidence];
+    findings = findings.filter((f) => LEVEL_RANK3[f.confidence.level] >= min);
+  }
+  if (typeof args.file === "string") {
+    const q = args.file.toLowerCase();
+    findings = findings.filter((f) => f.location.file.toLowerCase().includes(q));
+  }
+  if (typeof args.query === "string") {
+    const q = args.query.toLowerCase();
+    findings = findings.filter((f) => describeTarget(f.target).toLowerCase().includes(q));
+  }
+  const limit = typeof args.limit === "number" && args.limit > 0 ? Math.floor(args.limit) : 50;
+  return {
+    total: findings.length,
+    findings: findings.slice(0, limit).map((f) => ({
+      id: f.id,
+      category: f.category,
+      target: describeTarget(f.target),
+      location: `${f.location.file}:${f.location.line}`,
+      confidence: f.confidence,
+      evidence: f.evidence.map((e) => ({
+        signal: e.signal,
+        direction: e.direction,
+        weight: e.weight,
+        detail: e.detail
+      }))
+    }))
+  };
+}
+
 // src/reporters/json.ts
 function renderJson(result) {
   return JSON.stringify(result, null, 2) + "\n";
@@ -2557,7 +3460,7 @@ function escapeMd(s) {
 }
 
 // src/reporters/pretty.ts
-import pc from "picocolors";
+import pc5 from "picocolors";
 var CATEGORY_TITLES2 = {
   "dead-route": "ROUTES THAT APPEAR DEAD",
   "unused-export": "EXPORTS THAT APPEAR UNUSED",
@@ -2566,7 +3469,7 @@ var CATEGORY_TITLES2 = {
 };
 var RULE_WIDTH = 72;
 function renderPretty(result, useColor) {
-  const c = pc.createColors(useColor);
+  const c = pc5.createColors(useColor);
   const lines = [];
   const { stats } = result;
   lines.push("");
@@ -2637,8 +3540,16 @@ function renderPretty(result, useColor) {
     lines.push(`  ${c.yellow("\u26A0")} ${c.dim(warning)}`);
   }
   lines.push("");
+  const removable = result.findings.some(
+    (f) => (f.category === "unreachable-file" || f.category === "unused-dependency") && f.confidence.score >= 50
+  );
+  if (removable) {
+    lines.push(
+      `  ${c.green("\u2192")} ${c.bold("deadwood clean")} \u2014 review & remove these interactively ${c.dim("(one revertable commit each)")}`
+    );
+  }
   lines.push(
-    `  ${c.dim("\u2192 --min-confidence medium  \xB7  --json for machines  \xB7  --fail-on high for CI")}`
+    `  ${c.dim("\u2192 --diff-base main for PR deltas  \xB7  --json for machines  \xB7  --fail-on high for CI")}`
   );
   lines.push("");
   return lines.join("\n");
@@ -2685,7 +3596,7 @@ var CATEGORIES = [
   "unused-dependency",
   "unreachable-file"
 ];
-var LEVEL_RANK2 = { low: 0, medium: 1, high: 2 };
+var LEVEL_RANK4 = { low: 0, medium: 1, high: 2 };
 var program = new Command();
 program.name("deadwood").description("Find dead code and prove it \u2014 scans a JS/TS repo and prints a shock report").version(pkg.version).argument("[path]", "directory to scan", ".").option("--json", "machine-readable ScanResult on stdout").option("--md", "markdown report (PR comments / Slack)").option("--fail-on <spec>", "CI gate: 'high', 'medium', or 'high:5' (exit 1 when tripped)").option("--include <glob...>", "extra include globs").option("--exclude <glob...>", "extra exclude globs").option(
   "--no-default-excludes",
@@ -2697,83 +3608,231 @@ program.name("deadwood").description("Find dead code and prove it \u2014 scans a
     "nest",
     "next"
   ])
-).option("--entry <file...>", "extra entry points (false-positive escape hatch)").addOption(
+).option("--entry <file...>", "extra entry points (false-positive escape hatch)").option(
+  "--diff-base <ref>",
+  "PR delta mode: report only findings INTRODUCED since this git ref; --fail-on gates the delta"
+).option("--watch", "re-scan on file changes and report the delta per save").option("--no-git", "skip git-history evidence (untouched-for-a-year / recently-modified nudges)").addOption(
   new Option("--min-confidence <level>", "hide findings below this level").choices(["low", "medium", "high"]).default("low")
-).option("--no-color", "disable colors").action(async (path12, opts) => {
-  await run(path12, opts);
+).option("--no-color", "disable colors").action(async (path15, opts) => {
+  await run(path15, opts);
 });
-async function run(path12, opts) {
+program.command("clean").description("guided deletion: review findings and remove them, one revertable commit each").argument("[path]", "directory to clean", ".").option("--dry-run", "print the removal plan without touching anything").option("--yes", "accept every removal at/above the confidence floor (non-interactive)").addOption(
+  new Option("--min-confidence <level>", "only offer removals at/above this level").choices(["medium", "high"]).default("medium")
+).option("--no-commit", "delete without committing (also lifts the clean-tree requirement)").option("--no-git", "skip git-history evidence in the underlying scan").option("--no-color", "disable colors").action(async (path15, opts) => {
+  try {
+    await runClean(path15, opts);
+  } catch (err) {
+    if (err instanceof ScanError) {
+      process4.stderr.write(`error (${err.code}): ${err.message}
+`);
+    } else {
+      process4.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}
+`);
+    }
+    process4.exitCode = 2;
+  }
+});
+program.command("explain").description(
+  "unpack one finding: every evidence line, the confidence math, and what would make it live"
+).argument("<query>", "finding id prefix, target text, or file path substring").argument("[path]", "directory to scan", ".").option("--no-git", "skip git-history evidence").option("--no-color", "disable colors").action(async (query, path15, opts) => {
+  try {
+    const { options } = buildScanOptions(path15, { ...defaultCliOptions(), git: opts.git });
+    const result = await scan(options);
+    const matches = findMatches(result, query);
+    const useColor = opts.color && pc6.isColorSupported && process4.stdout.isTTY === true;
+    if (matches.length === 0) {
+      process4.stderr.write(
+        `no finding matches '${query}' \u2014 try a file path or run a scan first
+`
+      );
+      process4.exitCode = 2;
+    } else if (matches.length > 1) {
+      process4.stdout.write(renderCandidates(matches, useColor));
+      process4.exitCode = 2;
+    } else {
+      process4.stdout.write(renderExplanation(matches[0], useColor));
+    }
+  } catch (err) {
+    reportError(err);
+  }
+});
+program.command("badge").description(
+  "generate a self-hosted status badge SVG (no external service, nothing leaves the machine)"
+).argument("[path]", "directory to scan", ".").option("--output <file>", "write the SVG here instead of stdout").option("--no-git", "skip git-history evidence").action(async (path15, opts) => {
+  try {
+    const { options } = buildScanOptions(path15, { ...defaultCliOptions(), git: opts.git });
+    const result = await scan(options);
+    const badge = buildBadge(result, opts.output ?? "./deadwood-badge.svg");
+    if (opts.output) {
+      fs13.writeFileSync(opts.output, badge.svg);
+      process4.stderr.write(
+        `wrote ${opts.output} (${badge.value}) \u2014 reference it: ${badge.markdown}
+`
+      );
+    } else {
+      process4.stdout.write(badge.svg);
+      process4.stderr.write(
+        `badge: ${badge.value} \u2014 save it and reference it: ${badge.markdown}
+`
+      );
+    }
+  } catch (err) {
+    reportError(err);
+  }
+});
+program.command("mcp").description("serve the dead-code map to coding agents (Model Context Protocol over stdio)").argument("[path]", "directory to serve", ".").option("--no-git", "skip git-history evidence").action(async (path15, opts) => {
+  try {
+    await runMcp(
+      () => buildScanOptions(path15, { ...defaultCliOptions(), git: opts.git }).options,
+      pkg.version
+    );
+  } catch (err) {
+    reportError(err);
+  }
+});
+function defaultCliOptions() {
+  return { defaultExcludes: true, git: true, minConfidence: "low", color: true };
+}
+function reportError(err) {
+  if (err instanceof ScanError) {
+    process4.stderr.write(`error (${err.code}): ${err.message}
+`);
+  } else {
+    process4.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}
+`);
+  }
+  process4.exitCode = 2;
+}
+function buildScanOptions(dir, opts, { git = opts.git } = {}) {
+  const cfg = loadRepoConfig(nodePath.resolve(dir));
+  return {
+    options: {
+      path: dir,
+      include: opts.include,
+      exclude: [...opts.exclude ?? [], ...cfg.exclude],
+      defaultExcludes: opts.defaultExcludes,
+      categories: opts.category,
+      frameworks: opts.framework,
+      entries: [...opts.entry ?? [], ...cfg.entries],
+      workspaces: opts.workspace,
+      toolVersion: pkg.version,
+      gitFacts: git ? collectGitFacts(dir) : void 0,
+      publicApi: cfg.publicApi
+    },
+    configWarnings: cfg.warnings
+  };
+}
+async function run(path15, opts) {
   if (opts.json && opts.md) {
-    process.stderr.write("error: --json and --md are mutually exclusive\n");
-    process.exitCode = 2;
+    process4.stderr.write("error: --json and --md are mutually exclusive\n");
+    process4.exitCode = 2;
+    return;
+  }
+  if (opts.watch && (opts.json || opts.md || opts.diffBase)) {
+    process4.stderr.write(
+      "error: --watch is interactive \u2014 it cannot combine with --json/--md/--diff-base\n"
+    );
+    process4.exitCode = 2;
     return;
   }
   const failOnSpec = (() => {
     try {
       return opts.failOn ? parseFailOn(opts.failOn) : void 0;
     } catch (err) {
-      process.stderr.write(`error: ${err.message}
+      process4.stderr.write(`error: ${err.message}
 `);
-      process.exitCode = 2;
+      process4.exitCode = 2;
       return null;
     }
   })();
   if (failOnSpec === null) return;
+  const useColor = opts.color && pc6.isColorSupported && process4.stdout.isTTY === true;
+  if (opts.watch) {
+    await runWatch(path15, () => buildScanOptions(path15, opts).options, useColor);
+    return;
+  }
   const machineOutput = Boolean(opts.json || opts.md);
   const spinner = ora({
     text: "scanning\u2026",
-    stream: process.stderr,
-    isEnabled: !machineOutput && process.stderr.isTTY === true
+    stream: process4.stderr,
+    isEnabled: !machineOutput && process4.stderr.isTTY === true
   });
   try {
     spinner.start();
-    const result = await scan({
-      path: path12,
-      include: opts.include,
-      exclude: opts.exclude,
-      defaultExcludes: opts.defaultExcludes,
-      categories: opts.category,
-      frameworks: opts.framework,
-      entries: opts.entry,
-      workspaces: opts.workspace,
-      toolVersion: pkg.version
-    });
+    const { options, configWarnings } = buildScanOptions(path15, opts);
+    const result = await scan(options);
+    result.warnings.push(...configWarnings);
+    let delta;
+    if (opts.diffBase) {
+      spinner.text = `scanning base ${opts.diffBase}\u2026`;
+      const { options: baseOptions } = buildScanOptions(path15, opts, { git: false });
+      const { path: _p, ...rest } = baseOptions;
+      const base = await scanBaseRef(nodePath.resolve(path15), opts.diffBase, rest);
+      delta = diffFindings(base, result, opts.diffBase);
+    }
     spinner.stop();
-    const gate = failOnSpec ? evaluateFailOn(result.findings, failOnSpec) : void 0;
+    const gate = failOnSpec ? evaluateFailOn(delta ? delta.added : result.findings, failOnSpec) : void 0;
     const displayed = filterForDisplay(result, opts.minConfidence);
-    const useColor = opts.color && pc2.isColorSupported && process.stdout.isTTY === true;
-    const output = opts.json ? renderJson(displayed) : opts.md ? renderMd(displayed) : renderPretty(displayed, useColor);
-    process.stdout.write(output);
+    let output;
+    if (delta) {
+      const displayedDelta = {
+        ...delta,
+        added: filterForDisplay({ ...result, findings: delta.added }, opts.minConfidence).findings
+      };
+      output = opts.json ? JSON.stringify(
+        {
+          ...displayed,
+          delta: {
+            baseRef: delta.baseRef,
+            added: delta.added.map((f) => f.id),
+            resolved: delta.resolved.map((f) => ({
+              id: f.id,
+              category: f.category,
+              target: f.target
+            }))
+          }
+        },
+        null,
+        2
+      ) + "\n" : opts.md ? `### \u2620 deadwood delta vs \`${delta.baseRef}\`
+
++${delta.added.length} introduced \xB7 \u2212${delta.resolved.length} resolved
+
+` + renderMd({ ...displayed, findings: displayedDelta.added }) : renderDeltaPretty(displayedDelta, useColor);
+    } else {
+      output = opts.json ? renderJson(displayed) : opts.md ? renderMd(displayed) : renderPretty(displayed, useColor);
+    }
+    process4.stdout.write(output);
     if (opts.json) {
-      for (const warning of result.warnings) process.stderr.write(`warning: ${warning}
+      for (const warning of result.warnings) process4.stderr.write(`warning: ${warning}
 `);
     }
     if (gate?.tripped) {
-      process.stderr.write(
-        `deadwood: --fail-on ${opts.failOn} tripped (${gate.count} finding${gate.count === 1 ? "" : "s"} at/above '${failOnSpec.level}')
+      process4.stderr.write(
+        `deadwood: --fail-on ${opts.failOn} tripped (${gate.count} ${delta ? "INTRODUCED " : ""}finding${gate.count === 1 ? "" : "s"} at/above '${failOnSpec.level}')
 `
       );
-      process.exitCode = 1;
+      process4.exitCode = 1;
     }
   } catch (err) {
     spinner.stop();
     if (err instanceof ScanError) {
-      process.stderr.write(`error (${err.code}): ${err.message}
+      process4.stderr.write(`error (${err.code}): ${err.message}
 `);
     } else {
-      process.stderr.write(
+      process4.stderr.write(
         `error: ${err instanceof Error ? err.stack ?? err.message : String(err)}
 `
       );
     }
-    process.exitCode = 2;
+    process4.exitCode = 2;
   }
 }
 function filterForDisplay(result, minConfidence) {
   if (minConfidence === "low") return result;
-  const min = LEVEL_RANK2[minConfidence];
-  const findings = result.findings.filter((f) => LEVEL_RANK2[f.confidence.level] >= min);
+  const min = LEVEL_RANK4[minConfidence];
+  const findings = result.findings.filter((f) => LEVEL_RANK4[f.confidence.level] >= min);
   return { ...result, findings };
 }
-await program.parseAsync(process.argv);
+await program.parseAsync(process4.argv);
 //# sourceMappingURL=index.js.map