deadwood-scan 0.2.0 → 0.4.0

package/dist/index.js

@@ -2,13 +2,13 @@
 
 // src/index.ts
 import { createRequire } from "module";
-import process from "process";
+import process2 from "process";
 import { Command, Option } from "commander";
 import ora from "ora";
-import pc2 from "picocolors";
+import pc3 from "picocolors";
 
 // ../core/src/index.ts
-import fs8 from "fs";
+import fs9 from "fs";
 import path11 from "path";
 import { glob as glob2 } from "tinyglobby";
 
@@ -981,6 +981,11 @@ var SIGNAL_LIST = [
   spare("static:string-dispatch", 20, "Symbol appears in a string-keyed dispatch table"),
   spare("static:script-reference", 60, "Referenced by a package.json script"),
   spare("static:config-reference", 60, "Referenced by a build/deploy config"),
+  spare(
+    "static:dev-config-reference",
+    60,
+    "Referenced by a tooling config file (eslint/babel/CI/\u2026) rather than an import"
+  ),
   spare("static:manifest-reference", 60, "Referenced by a caller manifest (cron/CI/k8s)"),
   spare("static:job-registration", 50, "File registers scheduled jobs or queue workers"),
   spare(
@@ -1005,6 +1010,28 @@ 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"),
+  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"
+  },
   // Reserved for the paid evidence layer — registered now so the scorer and
   // JSON contract already understand them.
   {
@@ -1036,6 +1063,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) {
@@ -1784,9 +1813,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)) {
@@ -1794,7 +1820,59 @@ function addOnce(finding, evidence) {
   }
 }
 
+// ../core/src/evidence/gitHistory.ts
+var DAY = 24 * 60 * 60;
+var STALE_SECONDS = 365 * DAY;
+var FRESH_SECONDS = 30 * 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)}`
+            )
+          );
+        } else if (age >= STALE_SECONDS) {
+          addOnce(
+            finding,
+            evidenceFor(
+              "git:untouched-1y",
+              `last commit touching this file was ${ageInWords(age)}`
+            )
+          );
+        }
+      }
+    }
+  };
+}
+
 // ../core/src/evidence/dynamicImports.ts
+import path10 from "path";
 var dynamicImports = {
   name: "dynamic-imports",
   provide(ctx, findings) {
@@ -1926,6 +2004,126 @@ function truncate(s) {
   return s.length > 60 ? s.slice(0, 57) + "\u2026" : s;
 }
 
+// ../core/src/evidence/depConfigRefs.ts
+import fs8 from "fs";
+import { globSync } from "tinyglobby";
+var CONFIG_GLOBS = [
+  "**/.eslintrc",
+  "**/.eslintrc.{json,yml,yaml,js,cjs}",
+  "**/eslint.config.{js,cjs,mjs,ts}",
+  "**/.babelrc",
+  "**/.babelrc.{json,js,cjs}",
+  "**/babel.config.{json,js,cjs,mjs}",
+  "**/.prettierrc",
+  "**/.prettierrc.{json,yml,yaml,js,cjs}",
+  "**/prettier.config.{js,cjs,mjs}",
+  "**/.mocharc.{json,yml,yaml,js,cjs}",
+  "**/jest.config.{js,cjs,mjs,ts,json}",
+  "**/jest.setup.{js,cjs,mjs,ts}",
+  "**/vitest.config.{js,cjs,mjs,ts}",
+  "**/webpack.config.{js,cjs,mjs,ts}",
+  "**/rollup.config.{js,cjs,mjs,ts}",
+  "**/tsup.config.{js,cjs,mjs,ts}",
+  "**/playwright.config.{js,cjs,mjs,ts}",
+  "**/cypress.config.{js,cjs,mjs,ts}",
+  "**/karma.conf.{js,cjs}",
+  "**/tsconfig*.json",
+  "**/.lintstagedrc",
+  "**/.lintstagedrc.{json,yml,yaml}",
+  "**/nyc.config.js",
+  "**/.nycrc",
+  "**/.nycrc.{json,yml,yaml}",
+  "**/commitlint.config.{js,cjs,mjs}",
+  "**/.github/workflows/*.{yml,yaml}",
+  "**/.travis.yml",
+  "**/appveyor.yml",
+  "**/azure-pipelines.yml",
+  "**/.gitlab-ci.yml"
+];
+var CONFIG_PRESENCE = [
+  { dep: "typescript", file: /^tsconfig[^/]*\.json$/ },
+  { dep: "prettier", file: /^\.prettierrc|^prettier\.config\./ },
+  { dep: "eslint", file: /^\.eslintrc|^eslint\.config\./ },
+  { dep: "jest", file: /^jest\.(config|setup)\./ },
+  { dep: "vitest", file: /^vitest\.config\./ },
+  { dep: "mocha", file: /^\.mocharc/ },
+  { dep: "nyc", file: /^\.nycrc|^nyc\.config\./ },
+  { dep: "karma", file: /^karma\.conf\./ }
+];
+var IGNORE = ["**/node_modules/**", "**/dist/**", "**/.git/**"];
+var MAX_FILES = 100;
+var MAX_FILE_BYTES = 256 * 1024;
+var depConfigRefs = {
+  name: "dep-config-references",
+  provide(ctx, findings) {
+    const deps = findings.filter(
+      (f) => f.category === "unused-dependency" && f.target.kind === "dependency"
+    );
+    if (deps.length === 0) return;
+    const configs = readConfigFiles(ctx);
+    if (configs.length === 0) return;
+    for (const finding of deps) {
+      if (finding.target.kind !== "dependency") continue;
+      const name = finding.target.name;
+      const hit = configs.find((c) => referencesDep(c, name));
+      if (hit) {
+        addOnce(finding, evidenceFor("static:dev-config-reference", `Referenced in ${hit.rel}`));
+        continue;
+      }
+      const presence = CONFIG_PRESENCE.find((p) => p.dep === name);
+      const owner = presence && configs.find((c) => presence.file.test(c.base));
+      if (owner) {
+        addOnce(
+          finding,
+          evidenceFor("static:dev-config-reference", `Its config file exists: ${owner.rel}`)
+        );
+      }
+    }
+  }
+};
+function readConfigFiles(ctx) {
+  let paths;
+  try {
+    paths = globSync(CONFIG_GLOBS, { cwd: ctx.root, ignore: IGNORE, absolute: true, dot: true });
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const p of paths.map(toPosix).sort().slice(0, MAX_FILES)) {
+    try {
+      if (fs8.statSync(p).size > MAX_FILE_BYTES) continue;
+      out.push({
+        rel: ctx.rel(p),
+        base: p.slice(p.lastIndexOf("/") + 1).toLowerCase(),
+        text: fs8.readFileSync(p, "utf8")
+      });
+    } catch {
+    }
+  }
+  return out;
+}
+function referencesDep(config, depName) {
+  if (wordMatch(config.text, depName)) return true;
+  if (config.base.includes("eslint")) {
+    const m = /^eslint-(?:plugin|config)-(.+)$/.exec(depName);
+    if (m && wordMatch(config.text, m[1])) return true;
+    const scoped = /^(@[^/]+)\/eslint-config$/.exec(depName);
+    if (scoped && wordMatch(config.text, scoped[1])) return true;
+  }
+  if (config.base.includes("babel")) {
+    const m = /^babel-(?:plugin|preset)-(.+)$/.exec(depName);
+    if (m && wordMatch(config.text, m[1])) return true;
+  }
+  return false;
+}
+function wordMatch(text, name) {
+  const re = new RegExp(`(^|[^\\w@/-])${escapeRe2(name)}($|[^\\w-])`, "m");
+  return re.test(text);
+}
+function escapeRe2(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
 // ../core/src/evidence/jobRegistration.ts
 import ts6 from "typescript";
 var JOB_PACKAGES = /* @__PURE__ */ new Set([
@@ -2041,12 +2239,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;
 }
@@ -2065,6 +2264,26 @@ var DEFAULT_EXCLUDE = [
   "**/*.d.ts",
   "**/*.min.js"
 ];
+var NOISE_EXCLUDE = [
+  // Generated code — owned by a generator, not deletable by hand.
+  "**/generated/**",
+  "**/__generated__/**",
+  "**/*.generated.*",
+  "**/.prisma/**",
+  // Example/demo code — each file is its own intentional entry point.
+  "**/examples/**",
+  "**/example/**",
+  "**/samples/**",
+  "**/sample/**",
+  // Test scaffolding — referenced by test runners in ways imports don't show
+  // (jest loads __mocks__/ and setup files by convention/config string).
+  "**/fixtures/**",
+  "**/__fixtures__/**",
+  "**/__mocks__/**",
+  "**/testdata/**",
+  "**/jest.setup.*",
+  "**/vitest.setup.*"
+];
 var ALL_CATEGORIES = [
   "dead-route",
   "unused-export",
@@ -2089,6 +2308,7 @@ var PROVIDERS = [
   dynamicImports,
   stringDispatch,
   packageScripts,
+  depConfigRefs,
   jobRegistration,
   manifestReference,
   comments
@@ -2096,37 +2316,43 @@ var PROVIDERS = [
 async function scan(options) {
   const startedAt = Date.now();
   const root = absPosix(options.path);
-  if (!fs8.existsSync(root) || !fs8.statSync(root).isDirectory()) {
+  if (!fs9.existsSync(root) || !fs9.statSync(root).isDirectory()) {
     throw new ScanError("INVALID_PATH", `Not a directory: ${options.path}`);
   }
   const warnings = [];
   const { units: allUnits, warnings: wsWarnings } = await discoverWorkspaces(root);
   warnings.push(...wsWarnings);
   const units = options.workspaces && options.workspaces.length > 0 ? allUnits.filter((u, i) => i === 0 || options.workspaces.includes(u.name)) : allUnits;
-  const files = await glob2([...DEFAULT_INCLUDE, ...options.include ?? []], {
-    cwd: root,
-    ignore: [...DEFAULT_EXCLUDE, ...options.exclude ?? []],
-    absolute: true,
-    dot: true
-  });
+  const include = [...DEFAULT_INCLUDE, ...options.include ?? []];
+  const baseIgnore = [...DEFAULT_EXCLUDE, ...options.exclude ?? []];
+  const globOpts = { cwd: root, absolute: true, dot: true, followSymbolicLinks: false };
+  const files = await glob2(include, { ...globOpts, ignore: baseIgnore });
   if (files.length === 0) {
     throw new ScanError("NO_SOURCE_FILES", `No JS/TS source files found under ${options.path}`);
   }
+  const reportableFiles = options.defaultExcludes === false ? void 0 : new Set(
+    (await glob2(include, { ...globOpts, ignore: [...baseIgnore, ...NOISE_EXCLUDE] })).map(
+      toPosix
+    )
+  );
   const graph = new ModuleGraph();
   for (const file of files.map(toPosix).sort()) {
+    const source = readSourceSafe(file, warnings, (f) => relPosix(root, f));
+    if (source === void 0) continue;
     try {
-      graph.addFile(parseFile(file, fs8.readFileSync(file, "utf8")));
+      graph.addFile(parseFile(file, source));
     } catch {
       warnings.push(`Could not parse ${relPosix(root, file)}; it is excluded from analysis.`);
     }
   }
-  const scannedFiles = new Set(graph.files.keys());
-  const wsEntries = units.filter((u) => u.name !== ".").map((u) => ({ name: u.name, dir: u.dir, entryFile: guessUnitEntry(u, scannedFiles) }));
-  graph.link(new Resolver(root, wsEntries, scannedFiles, warnings));
-  const manifestCallers = await collectManifestCallers(root, scannedFiles, warnings);
+  const parsedFiles = new Set(graph.files.keys());
+  const scannedFiles = reportableFiles ? new Set([...parsedFiles].filter((f) => reportableFiles.has(f))) : parsedFiles;
+  const wsEntries = units.filter((u) => u.name !== ".").map((u) => ({ name: u.name, dir: u.dir, entryFile: guessUnitEntry(u, parsedFiles) }));
+  graph.link(new Resolver(root, wsEntries, parsedFiles, warnings));
+  const manifestCallers = await collectManifestCallers(root, parsedFiles, warnings);
   const entriesByUnit = /* @__PURE__ */ new Map();
   for (const unit of units) {
-    entriesByUnit.set(unit, discoverEntryPoints(unit, scannedFiles, warnings));
+    entriesByUnit.set(unit, discoverEntryPoints(unit, parsedFiles, warnings));
   }
   const rootUnit = units[0];
   for (const caller of manifestCallers) {
@@ -2137,7 +2363,7 @@ async function scan(options) {
     });
   }
   for (const ref of options.entries ?? []) {
-    const resolved = resolveEntryRef(root, ref, scannedFiles) ?? tryFile(path11.resolve(root, ref));
+    const resolved = resolveEntryRef(root, ref, parsedFiles) ?? tryFile(path11.resolve(root, ref));
     if (resolved) {
       pushEntry(entriesByUnit, unitForFile(units, toPosix(resolved)), {
         file: toPosix(resolved),
@@ -2151,7 +2377,7 @@ async function scan(options) {
   for (const unit of units) {
     const eps = entriesByUnit.get(unit);
     if (!eps.some((e) => e.tag !== "test" && e.reason !== "config")) {
-      const guess = guessUnitEntry(unit, scannedFiles);
+      const guess = guessUnitEntry(unit, parsedFiles);
       if (guess)
         pushEntry(entriesByUnit, unit, { file: guess, reason: "main", detail: "convention" });
     }
@@ -2204,7 +2430,7 @@ 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)]) {
     provider.provide(providerCtx, findings);
   }
   for (const finding of findings) {
@@ -2223,10 +2449,28 @@ async function scan(options) {
     root,
     workspaces: units.map((u) => u.name),
     findings,
-    stats: computeStats(graph, units, findings, routesTotal, Date.now() - startedAt),
+    stats: computeStats(graph, scannedFiles, units, findings, routesTotal, Date.now() - startedAt),
     warnings: [...new Set(warnings)]
   };
 }
+var MAX_SOURCE_BYTES = 8 * 1024 * 1024;
+function readSourceSafe(file, warnings, rel) {
+  try {
+    const st = fs9.lstatSync(file);
+    if (!st.isFile()) {
+      warnings.push(`Skipped ${rel(file)}: not a regular file (symlink or special file).`);
+      return void 0;
+    }
+    if (st.size > MAX_SOURCE_BYTES) {
+      warnings.push(`Skipped ${rel(file)}: exceeds ${MAX_SOURCE_BYTES} bytes.`);
+      return void 0;
+    }
+    return fs9.readFileSync(file, "utf8");
+  } catch {
+    warnings.push(`Could not read ${rel(file)}; it is excluded from analysis.`);
+    return void 0;
+  }
+}
 function pushEntry(map, unit, entry) {
   const list = map.get(unit);
   if (!list) {
@@ -2258,7 +2502,14 @@ async function collectManifestCallers(root, scannedFiles, warnings) {
       "**/cron.d/**",
       "webpack.config.{js,cjs,mjs,ts}"
     ],
-    { cwd: root, ignore: ["**/node_modules/**", "**/dist/**", "**/.git/**"], dot: true }
+    // followSymbolicLinks:false — same untrusted-content rule as the source
+    // globs (a symlinked serverless.yml → host file must not be read).
+    {
+      cwd: root,
+      ignore: ["**/node_modules/**", "**/dist/**", "**/.git/**"],
+      dot: true,
+      followSymbolicLinks: false
+    }
   );
   for (const rel of manifestFiles.map(toPosix).sort()) {
     try {
@@ -2281,23 +2532,24 @@ async function collectManifestCallers(root, scannedFiles, warnings) {
   }
   return callers.filter((c) => scannedFiles.has(c.file));
 }
-function computeStats(graph, units, findings, routesTotal, durationMs) {
+function computeStats(graph, scannedFiles, units, findings, routesTotal, durationMs) {
   const flagged = (category) => findings.filter((f) => f.category === category && f.confidence.score >= 50).length;
   let exportsTotal = 0;
-  for (const pf of graph.files.values()) {
-    exportsTotal += new Set(pf.exports.map((e) => e.name)).size;
+  for (const file of scannedFiles) {
+    const pf = graph.files.get(file);
+    if (pf) exportsTotal += new Set(pf.exports.map((e) => e.name)).size;
   }
   let depsTotal = 0;
   for (const u of units) {
     depsTotal += Object.keys(u.packageJson.dependencies ?? {}).length + Object.keys(u.packageJson.devDependencies ?? {}).length;
   }
   return {
-    filesScanned: graph.files.size,
+    filesScanned: scannedFiles.size,
     durationMs,
     routes: { total: routesTotal, flagged: flagged("dead-route") },
     exports: { total: exportsTotal, flagged: flagged("unused-export") },
     dependencies: { total: depsTotal, flagged: flagged("unused-dependency") },
-    files: { total: graph.files.size, flagged: flagged("unreachable-file") }
+    files: { total: scannedFiles.size, flagged: flagged("unreachable-file") }
   };
 }
 
@@ -2317,6 +2569,282 @@ 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 = "
";
+function collectGitFacts(dir, now = /* @__PURE__ */ new Date()) {
+  const out = runGit(dir, [
+    "log",
+    `--max-count=${MAX_COMMITS}`,
+    "--format=%x01%ct",
+    "--name-only",
+    "--no-renames",
+    "--relative",
+    "--",
+    "."
+  ]);
+  if (out === void 0) return void 0;
+  const lastModified = {};
+  let commits = 0;
+  let current = 0;
+  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 ts7 = Number(line.slice(1));
+      if (!Number.isFinite(ts7)) continue;
+      current = ts7;
+      commits++;
+      continue;
+    }
+    if (current === 0) continue;
+    const path13 = normalizeGitPath(line);
+    if (lastModified[path13] === void 0) lastModified[path13] = current;
+  }
+  if (commits === 0) return void 0;
+  return {
+    lastModified,
+    truncated: commits >= MAX_COMMITS,
+    now: Math.floor(now.getTime() / 1e3)
+  };
+}
+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/reporters/json.ts
 function renderJson(result) {
   return JSON.stringify(result, null, 2) + "\n";
@@ -2379,7 +2907,7 @@ function escapeMd(s) {
 }
 
 // src/reporters/pretty.ts
-import pc from "picocolors";
+import pc2 from "picocolors";
 var CATEGORY_TITLES2 = {
   "dead-route": "ROUTES THAT APPEAR DEAD",
   "unused-export": "EXPORTS THAT APPEAR UNUSED",
@@ -2388,7 +2916,7 @@ var CATEGORY_TITLES2 = {
 };
 var RULE_WIDTH = 72;
 function renderPretty(result, useColor) {
-  const c = pc.createColors(useColor);
+  const c = pc2.createColors(useColor);
   const lines = [];
   const { stats } = result;
   lines.push("");
@@ -2507,33 +3035,52 @@ var CATEGORIES = [
   "unused-dependency",
   "unreachable-file"
 ];
-var LEVEL_RANK2 = { low: 0, medium: 1, high: 2 };
+var LEVEL_RANK3 = { 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").addOption(new Option("--category <category...>", "limit findings").choices(CATEGORIES)).option("--workspace <name...>", "limit monorepo scan to these packages").addOption(
+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",
+  "also scan generated/, examples/, fixtures/, __mocks__/ (excluded by default as noise)"
+).addOption(new Option("--category <category...>", "limit findings").choices(CATEGORIES)).option("--workspace <name...>", "limit monorepo scan to these packages").addOption(
   new Option("--framework <framework...>", "force route framework detection").choices([
     "express",
     "fastify",
     "nest",
     "next"
   ])
-).option("--entry <file...>", "extra entry points (false-positive escape hatch)").addOption(
+).option("--entry <file...>", "extra entry points (false-positive escape hatch)").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 (path13, opts) => {
+  await run(path13, 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 (path13, opts) => {
+  try {
+    await runClean(path13, opts);
+  } catch (err) {
+    if (err instanceof ScanError) {
+      process2.stderr.write(`error (${err.code}): ${err.message}
+`);
+    } else {
+      process2.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}
+`);
+    }
+    process2.exitCode = 2;
+  }
 });
-async function run(path12, opts) {
+async function run(path13, opts) {
   if (opts.json && opts.md) {
-    process.stderr.write("error: --json and --md are mutually exclusive\n");
-    process.exitCode = 2;
+    process2.stderr.write("error: --json and --md are mutually exclusive\n");
+    process2.exitCode = 2;
     return;
   }
   const failOnSpec = (() => {
     try {
       return opts.failOn ? parseFailOn(opts.failOn) : void 0;
     } catch (err) {
-      process.stderr.write(`error: ${err.message}
+      process2.stderr.write(`error: ${err.message}
 `);
-      process.exitCode = 2;
+      process2.exitCode = 2;
       return null;
     }
   })();
@@ -2541,57 +3088,60 @@ async function run(path12, opts) {
   const machineOutput = Boolean(opts.json || opts.md);
   const spinner = ora({
     text: "scanning\u2026",
-    stream: process.stderr,
-    isEnabled: !machineOutput && process.stderr.isTTY === true
+    stream: process2.stderr,
+    isEnabled: !machineOutput && process2.stderr.isTTY === true
   });
   try {
     spinner.start();
+    const gitFacts = opts.git ? collectGitFacts(path13) : void 0;
     const result = await scan({
-      path: path12,
+      path: path13,
       include: opts.include,
       exclude: opts.exclude,
+      defaultExcludes: opts.defaultExcludes,
       categories: opts.category,
       frameworks: opts.framework,
       entries: opts.entry,
       workspaces: opts.workspace,
-      toolVersion: pkg.version
+      toolVersion: pkg.version,
+      gitFacts
     });
     spinner.stop();
     const gate = failOnSpec ? evaluateFailOn(result.findings, failOnSpec) : void 0;
     const displayed = filterForDisplay(result, opts.minConfidence);
-    const useColor = opts.color && pc2.isColorSupported && process.stdout.isTTY === true;
+    const useColor = opts.color && pc3.isColorSupported && process2.stdout.isTTY === true;
     const output = opts.json ? renderJson(displayed) : opts.md ? renderMd(displayed) : renderPretty(displayed, useColor);
-    process.stdout.write(output);
+    process2.stdout.write(output);
     if (opts.json) {
-      for (const warning of result.warnings) process.stderr.write(`warning: ${warning}
+      for (const warning of result.warnings) process2.stderr.write(`warning: ${warning}
 `);
     }
     if (gate?.tripped) {
-      process.stderr.write(
+      process2.stderr.write(
         `deadwood: --fail-on ${opts.failOn} tripped (${gate.count} finding${gate.count === 1 ? "" : "s"} at/above '${failOnSpec.level}')
 `
       );
-      process.exitCode = 1;
+      process2.exitCode = 1;
     }
   } catch (err) {
     spinner.stop();
     if (err instanceof ScanError) {
-      process.stderr.write(`error (${err.code}): ${err.message}
+      process2.stderr.write(`error (${err.code}): ${err.message}
 `);
     } else {
-      process.stderr.write(
+      process2.stderr.write(
         `error: ${err instanceof Error ? err.stack ?? err.message : String(err)}
 `
       );
     }
-    process.exitCode = 2;
+    process2.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_RANK3[minConfidence];
+  const findings = result.findings.filter((f) => LEVEL_RANK3[f.confidence.level] >= min);
   return { ...result, findings };
 }
-await program.parseAsync(process.argv);
+await program.parseAsync(process2.argv);
 //# sourceMappingURL=index.js.map