depwire-cli 0.7.1 → 0.8.0

package/LICENSE

@@ -1,3 +1,5 @@
+SPDX-License-Identifier: BUSL-1.1
+
 Business Source License 1.1
 
 Parameters

package/README.md

@@ -1,5 +1,29 @@
 # Depwire
 
+<p align="center">
+  <a href="https://glama.ai/mcp/servers/depwire/depwire">
+    <img width="380" height="200" src="https://glama.ai/mcp/servers/depwire/depwire/badge" alt="Depwire MCP server" />
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/depwire-cli">
+    <img src="https://img.shields.io/npm/v/depwire-cli.svg?style=flat-square" alt="npm version" />
+  </a>
+  <a href="https://www.npmjs.com/package/depwire-cli">
+    <img src="https://img.shields.io/npm/dm/depwire-cli.svg?style=flat-square" alt="npm downloads" />
+  </a>
+  <a href="LICENSE">
+    <img src="https://img.shields.io/badge/license-BUSL--1.1-blue.svg?style=flat-square" alt="License" />
+  </a>
+  <a href="https://github.com/depwire/depwire/stargazers">
+    <img src="https://img.shields.io/github/stars/depwire/depwire.svg?style=flat-square" alt="GitHub stars" />
+  </a>
+  <a href="https://github.com/depwire/depwire/network/members">
+    <img src="https://img.shields.io/github/forks/depwire/depwire.svg?style=flat-square" alt="GitHub forks" />
+  </a>
+</p>
+
 ![Depwire - Arc diagram visualization of the Hono framework](./assets/depwire-hero.png)
 
 **See how your code connects. Give AI tools full codebase context.**
@@ -10,9 +34,10 @@ Depwire analyzes codebases to build a cross-reference graph showing how every fi
 
 - 🎨 **Beautiful arc diagram visualization** — Interactive Harrison Bible-style graphic
 - 🤖 **MCP server for AI tools** — Cursor, Claude Desktop get full dependency context
-- 📊 **Dependency health score** — 0-100 score across 6 dimensions (coupling, cohesion, circular deps, god files, orphans, depth)
-- 📄 **Auto-generated documentation** — 12 comprehensive documents: architecture, conventions, dependencies, onboarding, file catalog, API surface, error patterns, test coverage, git history, full snapshot, TODO/FIXME inventory, and health report
+- 📊 **Dependency health score** — 0-100 score across 6 dimensions (coupling, cohesion, circular deps, god files, orphans & dead code, depth)
+- 📄 **Auto-generated documentation** — 13 comprehensive documents: architecture, conventions, dependencies, onboarding, file catalog, API surface, error patterns, test coverage, git history, full snapshot, TODO/FIXME inventory, health report, and dead code analysis
 - 🔍 **Impact analysis** — "What breaks if I rename this function?" answered precisely
+- 🧹 **Dead code detection** — Find symbols that are defined but never referenced, categorized by confidence level
 - 👀 **Live updates** — Graph stays current as you edit code
 - 🌍 **Multi-language** — TypeScript, JavaScript, Python, and Go
 
@@ -34,14 +59,14 @@ Depwire fixes this by giving AI tools a complete dependency graph of your codeba
 ### Ship Better Code
 - **Impact analysis for any change** — renaming a function, moving a file, upgrading a dependency, deleting a module — know the full blast radius before you touch anything
 - **Refactor with confidence** — see every downstream consumer, every transitive dependency, 2-3 levels deep
-- **Catch dead code** — find symbols nobody references anymore
+- **Catch dead code** — find symbols nobody references anymore with confidence-based classification (high/medium/low)
 
 ### Stay in Flow
 - **Live graph, always current** — edit a file and the dependency map updates in real-time. No re-indexing, no waiting.
 - **Works locally, stays private** — zero cloud accounts, zero data leaving your machine. Just `npm install` and go.
 
-### 14 MCP Tools, Not Just Visualization
-Depwire isn't just a pretty graph. It's a full context engine with 14 tools that AI assistants call autonomously — architecture summaries, dependency tracing, symbol search, file context, health scores, temporal evolution, and more. The AI decides which tool to use based on your question.
+### 15 MCP Tools, Not Just Visualization
+Depwire isn't just a pretty graph. It's a full context engine with 15 tools that AI assistants call autonomously — architecture summaries, dependency tracing, symbol search, file context, health scores, dead code detection, temporal evolution, and more. The AI decides which tool to use based on your question.
 
 ## Installation
 
@@ -66,11 +91,13 @@ depwire viz
 depwire parse
 depwire docs
 depwire health
+depwire dead-code
 depwire temporal
 
 # Or specify a directory explicitly
 npx depwire-cli viz ./my-project
 npx depwire-cli parse ./my-project
+npx depwire-cli dead-code ./my-project
 npx depwire-cli temporal ./my-project
 
 # Temporal visualization options
@@ -139,6 +166,7 @@ Settings → Features → Experimental → Enable MCP → Add Server:
 | `get_project_docs` | Retrieve auto-generated codebase documentation |
 | `update_project_docs` | Regenerate documentation on demand |
 | `get_health_score` | Get 0-100 dependency health score with recommendations |
+| `find_dead_code` | Find dead code — symbols defined but never referenced |
 | `get_temporal_graph` | Show how the graph evolved over git history |
 
 ## Supported Languages
@@ -189,6 +217,8 @@ Opens an interactive arc diagram in your browser:
 
 Visualize how your codebase architecture evolved over git history. Scrub through time with an interactive timeline slider.
 
+![Depwire Temporal Graph](assets/depwire-temporal-hono.gif)
+
 ```bash
 # Auto-detects project root
 depwire temporal
@@ -220,6 +250,37 @@ Opens an interactive temporal visualization in your browser:
 - Auto-zoom to fit all arcs on snapshot change
 - Search to highlight specific files across time
 
+## 🪦 Dead Code Detection
+
+Find unused symbols across your codebase before they become technical debt.
+
+- Detects symbols with zero incoming references (never called, never imported)
+- Confidence scoring: **high** (definitely dead), **medium** (probably dead), **low** (might be dead)
+- Smart exclusion rules — ignores entry points, test files, barrel files, and config files to reduce false positives
+- Filter by confidence level, export as JSON for CI pipelines
+- Integrated into the health score (orphans dimension)
+- New MCP tool: `find_dead_code` — AI assistants can query dead code directly
+- New document generator: `DEAD_CODE.md` — auto-generated dead code report
+
+```bash
+depwire dead-code
+depwire dead-code --confidence high
+depwire dead-code --stats
+depwire dead-code --json
+```
+
+**Confidence Levels:**
+- 🔴 **High confidence (definitely dead)**: Not exported with zero references, or exported but never used
+- 🟡 **Medium confidence (probably dead)**: Exported from barrel files with zero dependents, or only used in test files
+- ⚪ **Low confidence (might be dead)**: Exported from package entry points, types with zero dependents, or in dynamic-use directories (routes, middleware, etc.)
+
+The dead code detector automatically excludes:
+- Entry point files (index.ts, main.ts, server.ts, etc.)
+- Test files (*.test.*, *.spec.*, __tests__/)
+- Config files (*.config.*)
+- Type declarations (*.d.ts)
+- Framework auto-loaded directories (pages/, routes/, middleware/, commands/)
+
 ## How It Works
 
 1. **Parser** — tree-sitter extracts every symbol and reference
@@ -357,6 +418,7 @@ depwire docs --update --only conventions
 | `CURRENT.md` | Complete codebase snapshot (every file, symbol, connection) |
 | `STATUS.md` | TODO/FIXME/HACK inventory with priority matrix |
 | `HEALTH.md` | Dependency health score (0-100) across 6 dimensions with recommendations |
+| `DEAD_CODE.md` | Dead code analysis — unused symbols by confidence level (high/medium/low) |
 
 Documents are stored in `.depwire/` with `metadata.json` tracking generation timestamps for staleness detection.
 
@@ -401,6 +463,56 @@ depwire health --json
 
 Health history is stored in `.depwire/health-history.json` (last 50 checks).
 
+### `depwire dead-code [directory]`
+
+Detect unused symbols across your codebase with confidence-based classification.
+
+**Directory argument is optional** — Auto-detects project root.
+
+**Options:**
+- `--confidence <level>` — Minimum confidence level to show: `high`, `medium`, `low` (default: `medium`)
+- `--include-low` — Shortcut for `--confidence low`
+- `--verbose` — Show detailed info for each dead symbol (file, line, kind, reason)
+- `--stats` — Show summary statistics
+- `--include-tests` — Include test files in analysis (excluded by default)
+- `--json` — Output as JSON for CI/automation
+
+**Confidence Levels:**
+- 🔴 **High confidence (definitely dead)**: Not exported with zero references, or exported but never used
+- 🟡 **Medium confidence (probably dead)**: Exported from barrel files with zero dependents, or only used in test files
+- ⚪ **Low confidence (might be dead)**: Exported from package entry points, types with zero dependents, or in dynamic-use directories (routes, middleware, etc.)
+
+**Examples:**
+```bash
+# Analyze dead code (default: medium confidence and above)
+depwire dead-code
+
+# Show only high-confidence dead code
+depwire dead-code --confidence high
+
+# Show all potential dead code (including low confidence)
+depwire dead-code --confidence low
+# Or use shortcut
+depwire dead-code --include-low
+
+# Detailed analysis with reasons and statistics
+depwire dead-code --verbose --stats
+
+# Include test files in analysis (excluded by default)
+depwire dead-code --include-tests
+
+# JSON output for CI/automation
+depwire dead-code --json
+```
+
+**Automatic Exclusions:**
+The dead code detector automatically excludes:
+- Entry point files (index.ts, main.ts, server.ts, etc.)
+- Test files (*.test.*, *.spec.*, __tests__/)
+- Config files (*.config.*)
+- Type declarations (*.d.ts)
+- Framework auto-loaded directories (pages/, routes/, middleware/, commands/)
+
 ### `depwire temporal [directory]`
 
 Visualize how the dependency graph evolved over git history.

package/dist/{chunk-65H7HCM4.js → chunk-IGRFC3MQ.js}

@@ -2009,10 +2009,10 @@ async function parseProject(projectRoot, options) {
     try {
       const fullPath = join6(projectRoot, file);
       if (options?.exclude) {
-        const shouldExclude = options.exclude.some(
+        const shouldExclude2 = options.exclude.some(
           (pattern) => minimatch(file, pattern, { matchBase: true })
         );
-        if (shouldExclude) {
+        if (shouldExclude2) {
           if (options.verbose) {
             console.error(`[Parser] Excluded: ${file}`);
           }
@@ -2820,11 +2820,11 @@ function calculateCircularDepsScore(graph) {
   const visited = /* @__PURE__ */ new Set();
   const recStack = /* @__PURE__ */ new Set();
   const cycles = [];
-  function dfs(node, path2) {
+  function dfs(node, path6) {
     if (recStack.has(node)) {
-      const cycleStart = path2.indexOf(node);
+      const cycleStart = path6.indexOf(node);
       if (cycleStart >= 0) {
-        cycles.push(path2.slice(cycleStart));
+        cycles.push(path6.slice(cycleStart));
       }
       return;
     }
@@ -2833,11 +2833,11 @@ function calculateCircularDepsScore(graph) {
     }
     visited.add(node);
     recStack.add(node);
-    path2.push(node);
+    path6.push(node);
     const neighbors = fileGraph.get(node);
     if (neighbors) {
       for (const neighbor of neighbors) {
-        dfs(neighbor, [...path2]);
+        dfs(neighbor, [...path6]);
       }
     }
     recStack.delete(node);
@@ -2939,25 +2939,40 @@ function calculateOrphansScore(graph) {
   });
   const orphanCount = files.size - connectedFiles.size;
   const orphanPercent = files.size > 0 ? orphanCount / files.size * 100 : 0;
+  const totalSymbols = graph.order;
+  let deadSymbolCount = 0;
+  graph.forEachNode((node) => {
+    const inDegree = graph.inDegree(node);
+    if (inDegree === 0) {
+      deadSymbolCount++;
+    }
+  });
+  const deadCodePercent = totalSymbols > 0 ? deadSymbolCount / totalSymbols * 100 : 0;
+  const combinedScore = (orphanPercent + deadCodePercent) / 2;
   let score = 100;
-  if (orphanPercent === 0) {
+  if (combinedScore === 0) {
     score = 100;
-  } else if (orphanPercent <= 5) {
+  } else if (combinedScore <= 5) {
     score = 80;
-  } else if (orphanPercent <= 10) {
+  } else if (combinedScore <= 10) {
     score = 60;
-  } else if (orphanPercent <= 20) {
+  } else if (combinedScore <= 20) {
     score = 40;
   } else {
     score = 20;
   }
   return {
-    name: "Orphan Files",
+    name: "Orphans & Dead Code",
     score,
     weight: 0.1,
     grade: scoreToGrade(score),
-    details: orphanCount === 0 ? "No orphan files" : `${orphanCount} orphan file${orphanCount === 1 ? "" : "s"} (${orphanPercent.toFixed(0)}%)`,
-    metrics: { orphans: orphanCount, percentage: parseFloat(orphanPercent.toFixed(1)) }
+    details: `${orphanCount} orphan file${orphanCount === 1 ? "" : "s"} (${orphanPercent.toFixed(0)}%), ${deadSymbolCount} dead symbols (${deadCodePercent.toFixed(1)}%)`,
+    metrics: {
+      orphans: orphanCount,
+      orphanPercentage: parseFloat(orphanPercent.toFixed(1)),
+      deadSymbols: deadSymbolCount,
+      deadCodePercentage: parseFloat(deadCodePercent.toFixed(1))
+    }
   };
 }
 function calculateDepthScore(graph) {
@@ -3159,6 +3174,304 @@ function loadHealthHistory(projectRoot) {
   }
 }
 
+// src/dead-code/detector.ts
+import path2 from "path";
+function findDeadSymbols(graph, projectRoot, includeTests = false) {
+  const deadSymbols = [];
+  const context = { graph, projectRoot };
+  for (const node of graph.nodes()) {
+    const attrs = graph.getNodeAttributes(node);
+    if (!attrs.file || !attrs.name) continue;
+    const inDegree = graph.inDegree(node);
+    if (inDegree === 0) {
+      if (shouldExclude(attrs, context, includeTests)) {
+        continue;
+      }
+      deadSymbols.push({
+        name: attrs.name,
+        kind: attrs.kind || "unknown",
+        file: attrs.file,
+        line: attrs.startLine || 0,
+        exported: attrs.exported || false,
+        dependents: 0,
+        confidence: "high",
+        reason: "Zero dependents"
+      });
+    }
+  }
+  return deadSymbols;
+}
+function shouldExclude(attrs, context, includeTests) {
+  const filePath = attrs.file;
+  const relativePath = path2.relative(context.projectRoot, filePath);
+  if (!includeTests && isTestFile(relativePath)) {
+    return true;
+  }
+  if (isEntryPoint(relativePath)) {
+    return true;
+  }
+  if (isConfigFile(relativePath)) {
+    return true;
+  }
+  if (isTypeDeclarationFile(relativePath)) {
+    return true;
+  }
+  if (attrs.kind === "default") {
+    return true;
+  }
+  if (isFrameworkAutoLoadedFile(relativePath)) {
+    return true;
+  }
+  return false;
+}
+function isTestFile(filePath) {
+  return filePath.includes("__tests__/") || filePath.includes(".test.") || filePath.includes(".spec.") || filePath.includes("/test/") || filePath.includes("/tests/");
+}
+function isEntryPoint(filePath) {
+  const basename6 = path2.basename(filePath);
+  return basename6 === "index.ts" || basename6 === "index.js" || basename6 === "main.ts" || basename6 === "main.js" || basename6 === "app.ts" || basename6 === "app.js" || basename6 === "server.ts" || basename6 === "server.js";
+}
+function isConfigFile(filePath) {
+  return filePath.includes(".config.") || filePath.includes("config/") || filePath.includes("vite.config") || filePath.includes("rollup.config") || filePath.includes("webpack.config");
+}
+function isTypeDeclarationFile(filePath) {
+  return filePath.endsWith(".d.ts");
+}
+function isFrameworkAutoLoadedFile(filePath) {
+  return filePath.includes("/pages/") || filePath.includes("/routes/") || filePath.includes("/middleware/") || filePath.includes("/commands/") || filePath.includes("/api/") || filePath.includes("/app/");
+}
+
+// src/dead-code/classifier.ts
+import path3 from "path";
+function classifyDeadSymbols(symbols, graph) {
+  return symbols.map((symbol) => {
+    const confidence = calculateConfidence(symbol, graph);
+    const reason = generateReason(symbol, confidence);
+    return {
+      ...symbol,
+      confidence,
+      reason
+    };
+  });
+}
+function calculateConfidence(symbol, graph) {
+  if (!symbol.exported && symbol.dependents === 0) {
+    return "high";
+  }
+  if (symbol.exported && symbol.dependents === 0 && !isBarrelFile(symbol.file)) {
+    return "high";
+  }
+  if (symbol.exported && symbol.dependents === 0 && isBarrelFile(symbol.file)) {
+    return "medium";
+  }
+  const dependents = getSymbolDependents(symbol, graph);
+  if (dependents.length === 1 && isTestFile2(dependents[0])) {
+    return "medium";
+  }
+  if (symbol.exported && isPackageEntryPoint(symbol.file)) {
+    return "low";
+  }
+  if ((symbol.kind === "interface" || symbol.kind === "type") && symbol.dependents === 0) {
+    return "low";
+  }
+  if (isLikelyDynamicUsage(symbol)) {
+    return "low";
+  }
+  return "medium";
+}
+function generateReason(symbol, confidence) {
+  if (!symbol.exported && symbol.dependents === 0) {
+    return "Not exported, zero references";
+  }
+  if (symbol.exported && symbol.dependents === 0 && !isBarrelFile(symbol.file)) {
+    return "Exported, zero dependents";
+  }
+  if (symbol.exported && symbol.dependents === 0 && isBarrelFile(symbol.file)) {
+    return "Exported from barrel file, zero dependents (might be used externally)";
+  }
+  if (confidence === "medium") {
+    return "Low usage, might be dead";
+  }
+  if (confidence === "low") {
+    if (symbol.kind === "interface" || symbol.kind === "type") {
+      return "Type with zero dependents (might be used via import type)";
+    }
+    if (isPackageEntryPoint(symbol.file)) {
+      return "Exported from package entry point (might be public API)";
+    }
+    if (isLikelyDynamicUsage(symbol)) {
+      return "In dynamic-use pattern directory (might be auto-loaded)";
+    }
+  }
+  return "Potentially unused";
+}
+function isBarrelFile(filePath) {
+  const basename6 = path3.basename(filePath);
+  return basename6 === "index.ts" || basename6 === "index.js";
+}
+function isTestFile2(filePath) {
+  return filePath.includes("__tests__/") || filePath.includes(".test.") || filePath.includes(".spec.") || filePath.includes("/test/") || filePath.includes("/tests/");
+}
+function isPackageEntryPoint(filePath) {
+  return filePath.includes("/src/index.") || filePath.includes("/lib/index.") || filePath.endsWith("/index.ts") || filePath.endsWith("/index.js");
+}
+function isLikelyDynamicUsage(symbol) {
+  const filePath = symbol.file;
+  return filePath.includes("/routes/") || filePath.includes("/pages/") || filePath.includes("/middleware/") || filePath.includes("/commands/") || filePath.includes("/handlers/") || filePath.includes("/api/");
+}
+function getSymbolDependents(symbol, graph) {
+  const dependents = [];
+  for (const node of graph.nodes()) {
+    const attrs = graph.getNodeAttributes(node);
+    if (attrs.file === symbol.file && attrs.name === symbol.name) {
+      const inNeighbors = graph.inNeighbors(node);
+      for (const neighbor of inNeighbors) {
+        const neighborAttrs = graph.getNodeAttributes(neighbor);
+        if (neighborAttrs.file) {
+          dependents.push(neighborAttrs.file);
+        }
+      }
+      break;
+    }
+  }
+  return dependents;
+}
+
+// src/dead-code/display.ts
+import chalk from "chalk";
+import path4 from "path";
+function displayDeadCodeReport(report, options, projectRoot) {
+  if (options.json) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+  console.log(chalk.cyan.bold("\n\u{1F50D} Dead Code Analysis\n"));
+  const { high, medium, low } = report.byConfidence;
+  console.log(
+    `Found ${chalk.yellow.bold(report.deadSymbols)} potentially dead symbols (${chalk.red(high)} high, ${chalk.yellow(medium)} medium, ${chalk.gray(low)} low confidence)
+`
+  );
+  const symbolsByConfidence = groupByConfidence(report.symbols);
+  if (symbolsByConfidence.high.length > 0) {
+    displayConfidenceGroup("HIGH", symbolsByConfidence.high, options.verbose, projectRoot);
+  }
+  if (symbolsByConfidence.medium.length > 0) {
+    displayConfidenceGroup("MEDIUM", symbolsByConfidence.medium, options.verbose, projectRoot);
+  }
+  if (symbolsByConfidence.low.length > 0) {
+    displayConfidenceGroup("LOW", symbolsByConfidence.low, options.verbose, projectRoot);
+  }
+  if (options.stats) {
+    displayStats(report);
+  }
+}
+function groupByConfidence(symbols) {
+  return symbols.reduce(
+    (acc, symbol) => {
+      acc[symbol.confidence].push(symbol);
+      return acc;
+    },
+    { high: [], medium: [], low: [] }
+  );
+}
+function displayConfidenceGroup(level, symbols, verbose, projectRoot) {
+  const emoji = level === "HIGH" ? "\u{1F534}" : level === "MEDIUM" ? "\u{1F7E1}" : "\u26AA";
+  const color = level === "HIGH" ? chalk.red : level === "MEDIUM" ? chalk.yellow : chalk.gray;
+  console.log(
+    color.bold(`
+${emoji} ${level} CONFIDENCE `) + chalk.gray(`(${level === "HIGH" ? "definitely" : level === "MEDIUM" ? "probably" : "might be"} dead)`)
+  );
+  const headers = ["Symbol", "Kind", "File", verbose ? "Reason" : ""];
+  const rows = symbols.map((symbol) => {
+    const relativePath = path4.relative(projectRoot, symbol.file);
+    return [
+      chalk.bold(symbol.name),
+      symbol.kind,
+      `${relativePath}:${symbol.line}`,
+      verbose ? symbol.reason : ""
+    ];
+  });
+  displayTable(headers, rows.filter((row) => row[3] !== ""));
+}
+function displayTable(headers, rows) {
+  if (rows.length === 0) return;
+  const columnWidths = headers.map((header2, i) => {
+    const maxRowWidth = Math.max(...rows.map((row) => stripAnsi(row[i]).length));
+    return Math.max(header2.length, maxRowWidth);
+  });
+  const separator = "\u250C" + columnWidths.map((w) => "\u2500".repeat(w + 2)).join("\u252C") + "\u2510";
+  const headerRow = "\u2502 " + headers.map((h, i) => h.padEnd(columnWidths[i])).join(" \u2502 ") + " \u2502";
+  const divider = "\u251C" + columnWidths.map((w) => "\u2500".repeat(w + 2)).join("\u253C") + "\u2524";
+  const footer = "\u2514" + columnWidths.map((w) => "\u2500".repeat(w + 2)).join("\u2534") + "\u2518";
+  console.log(separator);
+  console.log(headerRow);
+  console.log(divider);
+  for (const row of rows) {
+    const formattedRow = "\u2502 " + row.map((cell, i) => {
+      const stripped = stripAnsi(cell);
+      const padding = columnWidths[i] - stripped.length;
+      return cell + " ".repeat(padding);
+    }).join(" \u2502 ") + " \u2502";
+    console.log(formattedRow);
+  }
+  console.log(footer);
+}
+function displayStats(report) {
+  console.log(chalk.cyan.bold("\n\u{1F4CA} Summary\n"));
+  console.log(`  Total symbols analyzed: ${chalk.bold(report.totalSymbols.toLocaleString())}`);
+  console.log(`  Potentially dead: ${chalk.yellow.bold(report.deadSymbols)} (${report.deadPercentage.toFixed(1)}%)`);
+  console.log(
+    `  By confidence: ${chalk.red(report.byConfidence.high)} high, ${chalk.yellow(report.byConfidence.medium)} medium, ${chalk.gray(report.byConfidence.low)} low`
+  );
+  const estimatedLines = report.deadSymbols * 18;
+  console.log(`  Estimated dead code: ${chalk.gray(`~${estimatedLines.toLocaleString()} lines`)}
+`);
+}
+function stripAnsi(str) {
+  return str.replace(
+    /[\u001b\u009b][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g,
+    ""
+  );
+}
+
+// src/dead-code/index.ts
+function analyzeDeadCode(graph, projectRoot, options = {}) {
+  const opts = {
+    confidence: options.confidence || "medium",
+    includeTests: options.includeTests || false,
+    verbose: options.verbose || false,
+    stats: options.stats || false,
+    json: options.json || false
+  };
+  const rawDeadSymbols = findDeadSymbols(graph, projectRoot, opts.includeTests);
+  const classifiedSymbols = classifyDeadSymbols(rawDeadSymbols, graph);
+  const filteredSymbols = filterByConfidence(classifiedSymbols, opts.confidence);
+  const totalSymbols = graph.order;
+  const byConfidence = {
+    high: classifiedSymbols.filter((s) => s.confidence === "high").length,
+    medium: classifiedSymbols.filter((s) => s.confidence === "medium").length,
+    low: classifiedSymbols.filter((s) => s.confidence === "low").length
+  };
+  const report = {
+    totalSymbols,
+    deadSymbols: filteredSymbols.length,
+    deadPercentage: filteredSymbols.length / totalSymbols * 100,
+    byConfidence,
+    symbols: filteredSymbols
+  };
+  if (!opts.json) {
+    displayDeadCodeReport(report, opts, projectRoot);
+  }
+  return report;
+}
+function filterByConfidence(symbols, minConfidence) {
+  const confidenceLevels = { high: 3, medium: 2, low: 1 };
+  const minLevel = confidenceLevels[minConfidence];
+  return symbols.filter(
+    (s) => confidenceLevels[s.confidence] >= minLevel
+  );
+}
+
 // src/docs/generator.ts
 import { writeFileSync as writeFileSync3, mkdirSync as mkdirSync2, existsSync as existsSync9 } from "fs";
 import { join as join12 } from "path";
@@ -4208,20 +4521,20 @@ function findLongestPaths(graph, limit) {
   }
   const allPaths = [];
   const visited = /* @__PURE__ */ new Set();
-  function dfs(file, path2) {
+  function dfs(file, path6) {
     visited.add(file);
-    path2.push(file);
+    path6.push(file);
     const neighbors = fileGraph.get(file);
     if (!neighbors || neighbors.size === 0) {
-      allPaths.push([...path2]);
+      allPaths.push([...path6]);
     } else {
       for (const neighbor of neighbors) {
         if (!visited.has(neighbor)) {
-          dfs(neighbor, path2);
+          dfs(neighbor, path6);
         }
       }
     }
-    path2.pop();
+    path6.pop();
     visited.delete(file);
   }
   for (const root of roots.slice(0, 10)) {
@@ -5499,7 +5812,7 @@ function getFileCount8(graph) {
   });
   return files.size;
 }
-function isTestFile(filePath) {
+function isTestFile3(filePath) {
   const fileName = basename4(filePath).toLowerCase();
   const dirPath = dirname11(filePath).toLowerCase();
   if (dirPath.includes("test") || dirPath.includes("spec") || dirPath.includes("__tests__")) {
@@ -5513,7 +5826,7 @@ function isTestFile(filePath) {
 function getTestFiles(graph) {
   const testFiles = /* @__PURE__ */ new Map();
   graph.forEachNode((node, attrs) => {
-    if (isTestFile(attrs.filePath)) {
+    if (isTestFile3(attrs.filePath)) {
       if (!testFiles.has(attrs.filePath)) {
         testFiles.set(attrs.filePath, {
           filePath: attrs.filePath,
@@ -5572,9 +5885,9 @@ function matchTestToSource(testFile) {
     const srcDir = testDir.replace(/test[s]?/g, "src");
     possiblePaths.push(srcDir + "/" + sourceFileName);
   }
-  for (const path2 of possiblePaths) {
-    if (!isTestFile(path2)) {
-      return path2;
+  for (const path6 of possiblePaths) {
+    if (!isTestFile3(path6)) {
+      return path6;
     }
   }
   return null;
@@ -5629,7 +5942,7 @@ function generateUntestedFiles(graph) {
     allFiles.add(attrs.filePath);
   });
   for (const file of allFiles) {
-    if (!isTestFile(file)) {
+    if (!isTestFile3(file)) {
       sourceFiles.push(file);
     }
   }
@@ -5688,7 +6001,7 @@ function generateTestCoverageMap(graph) {
     allFiles.add(attrs.filePath);
   });
   for (const file of allFiles) {
-    if (!isTestFile(file)) {
+    if (!isTestFile3(file)) {
       sourceFiles.push(file);
     }
   }
@@ -5740,7 +6053,7 @@ function generateTestStatistics(graph) {
     allFiles.add(attrs.filePath);
   });
   for (const file of allFiles) {
-    if (!isTestFile(file)) {
+    if (!isTestFile3(file)) {
       sourceFiles.push(file);
     }
   }
@@ -7005,6 +7318,98 @@ function generateDetailedMetrics(dimensions) {
   return output;
 }
 
+// src/docs/dead-code.ts
+import path5 from "path";
+function generateDeadCode(graph, projectRoot, projectName) {
+  const report = analyzeDeadCode(graph, projectRoot, {
+    confidence: "low",
+    includeTests: false,
+    verbose: true,
+    stats: true,
+    json: true
+  });
+  let output = "";
+  output += header(`${projectName} - Dead Code Analysis`, 1);
+  output += timestamp();
+  output += "\n";
+  output += header("Summary", 2);
+  output += `Total symbols analyzed: **${formatNumber(report.totalSymbols)}**
+
+`;
+  output += `Potentially dead symbols: **${formatNumber(report.deadSymbols)}** (${report.deadPercentage.toFixed(1)}%)
+
+`;
+  output += `- \u{1F534} High confidence (definitely dead): **${report.byConfidence.high}**
+`;
+  output += `- \u{1F7E1} Medium confidence (probably dead): **${report.byConfidence.medium}**
+`;
+  output += `- \u26AA Low confidence (might be dead): **${report.byConfidence.low}**
+
+`;
+  const estimatedLines = report.deadSymbols * 18;
+  output += `Estimated dead code: **~${formatNumber(estimatedLines)} lines**
+
+`;
+  const symbolsByConfidence = groupByConfidence2(report.symbols);
+  if (symbolsByConfidence.high.length > 0) {
+    output += generateConfidenceSection(
+      "High Confidence",
+      "definitely dead",
+      symbolsByConfidence.high,
+      projectRoot
+    );
+  }
+  if (symbolsByConfidence.medium.length > 0) {
+    output += generateConfidenceSection(
+      "Medium Confidence",
+      "probably dead",
+      symbolsByConfidence.medium,
+      projectRoot
+    );
+  }
+  if (symbolsByConfidence.low.length > 0) {
+    output += generateConfidenceSection(
+      "Low Confidence",
+      "might be dead",
+      symbolsByConfidence.low,
+      projectRoot
+    );
+  }
+  output += "\n---\n\n";
+  output += "_This document was auto-generated by Depwire. It reflects the current state of the codebase and should be reviewed before taking action._\n";
+  return output;
+}
+function groupByConfidence2(symbols) {
+  return symbols.reduce(
+    (acc, symbol) => {
+      acc[symbol.confidence].push(symbol);
+      return acc;
+    },
+    { high: [], medium: [], low: [] }
+  );
+}
+function generateConfidenceSection(title, description, symbols, projectRoot) {
+  let output = "";
+  output += header(`${title} (${description})`, 2);
+  output += `Found **${symbols.length}** symbol${symbols.length === 1 ? "" : "s"}.
+
+`;
+  const headers = ["Symbol", "Kind", "File", "Exported", "Reason"];
+  const rows = symbols.map((s) => {
+    const relativePath = path5.relative(projectRoot, s.file);
+    return [
+      code(s.name),
+      s.kind,
+      `${relativePath}:${s.line}`,
+      s.exported ? "Yes" : "No",
+      s.reason
+    ];
+  });
+  output += table(headers, rows);
+  output += "\n";
+  return output;
+}
+
 // src/docs/metadata.ts
 import { existsSync as existsSync8, readFileSync as readFileSync6, writeFileSync as writeFileSync2 } from "fs";
 import { join as join11 } from "path";
@@ -7088,7 +7493,8 @@ async function generateDocs(graph, projectRoot, version, parseTime, options) {
         "history",
         "current",
         "status",
-        "health"
+        "health",
+        "dead_code"
       ];
     }
     let metadata = null;
@@ -7231,6 +7637,17 @@ async function generateDocs(graph, projectRoot, version, parseTime, options) {
           errors.push(`Failed to generate HEALTH.md: ${err}`);
         }
       }
+      if (docsToGenerate.includes("dead_code")) {
+        try {
+          if (options.verbose) console.log("Generating DEAD_CODE.md...");
+          const content = generateDeadCode(graph, projectRoot, version);
+          const filePath = join12(options.outputDir, "DEAD_CODE.md");
+          writeFileSync3(filePath, content, "utf-8");
+          generated.push("DEAD_CODE.md");
+        } catch (err) {
+          errors.push(`Failed to generate DEAD_CODE.md: ${err}`);
+        }
+      }
     } else if (options.format === "json") {
       errors.push("JSON format not yet supported");
     }
@@ -7689,8 +8106,8 @@ function createSnapshot(graph, commitHash, commitDate, commitMessage, commitAuth
       }
     }
   }
-  const files = Array.from(fileMap.entries()).map(([path2, data]) => ({
-    path: path2,
+  const files = Array.from(fileMap.entries()).map(([path6, data]) => ({
+    path: path6,
     symbols: data.symbols,
     connections: data.inbound + data.outbound
   }));
@@ -7927,6 +8344,21 @@ function getToolsList() {
           }
         }
       }
+    },
+    {
+      name: "find_dead_code",
+      description: "Find potentially dead code \u2014 symbols that are defined but never referenced anywhere in the codebase. Returns symbols categorized by confidence level (high, medium, low). High confidence means definitely unused. Use this to identify cleanup opportunities.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          confidence: {
+            type: "string",
+            enum: ["high", "medium", "low"],
+            description: "Minimum confidence level to return (default: medium)",
+            default: "medium"
+          }
+        }
+      }
     }
   ];
 }
@@ -7989,6 +8421,15 @@ async function handleToolCall(name, args, state) {
       } else {
         result = await handleGetTemporalGraph(state, args.commits || 10, args.strategy || "even");
       }
+    } else if (name === "find_dead_code") {
+      if (!isProjectLoaded(state)) {
+        result = {
+          error: "No project loaded",
+          message: "Use connect_repo to connect to a codebase first"
+        };
+      } else {
+        result = handleFindDeadCode(state, args.confidence || "medium");
+      }
     } else {
       if (!isProjectLoaded(state)) {
         result = {
@@ -8604,6 +9045,46 @@ async function handleGetTemporalGraph(state, commits, strategy) {
     };
   }
 }
+function handleFindDeadCode(state, confidence) {
+  if (!state.graph || !state.projectRoot) {
+    return {
+      error: "No project loaded",
+      message: "Use connect_repo to connect to a codebase first"
+    };
+  }
+  try {
+    const report = analyzeDeadCode(state.graph, state.projectRoot, {
+      confidence,
+      includeTests: false,
+      verbose: false,
+      stats: false,
+      json: true
+    });
+    return {
+      status: "success",
+      totalSymbols: report.totalSymbols,
+      deadSymbols: report.deadSymbols,
+      deadPercentage: report.deadPercentage,
+      byConfidence: report.byConfidence,
+      symbols: report.symbols.map((s) => ({
+        name: s.name,
+        kind: s.kind,
+        file: s.file,
+        line: s.line,
+        exported: s.exported,
+        dependents: s.dependents,
+        confidence: s.confidence,
+        reason: s.reason
+      })),
+      summary: `Found ${report.deadSymbols} potentially dead symbols (${report.byConfidence.high} high, ${report.byConfidence.medium} medium, ${report.byConfidence.low} low confidence) out of ${report.totalSymbols} total symbols (${report.deadPercentage.toFixed(1)}% dead code).`
+    };
+  } catch (error) {
+    return {
+      error: "Failed to analyze dead code",
+      message: String(error)
+    };
+  }
+}
 
 // src/mcp/server.ts
 async function startMcpServer(state) {
@@ -8652,6 +9133,7 @@ export {
   updateFileInGraph,
   calculateHealthScore,
   getHealthTrend,
+  analyzeDeadCode,
   generateDocs,
   getCommitLog,
   getCurrentBranch,

package/dist/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import {
+  analyzeDeadCode,
   buildGraph,
   calculateHealthScore,
   checkoutCommit,
@@ -26,7 +27,7 @@ import {
   stashChanges,
   updateFileInGraph,
   watchProject
-} from "./chunk-65H7HCM4.js";
+} from "./chunk-IGRFC3MQ.js";
 
 // src/index.ts
 import { Command } from "commander";
@@ -787,4 +788,32 @@ program.command("health").description("Analyze dependency architecture health (0
     process.exit(1);
   }
 });
+program.command("dead-code").description("Identify dead code - symbols defined but never referenced").argument("[directory]", "Project directory to analyze (defaults to current directory or auto-detected project root)").option("--confidence <level>", "Minimum confidence level to show: high, medium, low (default: medium)", "medium").option("--json", "Output as JSON (for CI/automation)").option("--verbose", "Show detailed info for each dead symbol").option("--stats", "Show summary statistics").option("--include-tests", "Include test files in analysis").option("--include-low", "Shortcut for --confidence low").action(async (directory, options) => {
+  try {
+    const projectRoot = directory ? resolve(directory) : findProjectRoot();
+    const startTime = Date.now();
+    const parsedFiles = await parseProject(projectRoot);
+    const graph = buildGraph(parsedFiles);
+    const confidence = options.includeLow ? "low" : options.confidence || "medium";
+    const report = analyzeDeadCode(graph, projectRoot, {
+      confidence,
+      includeTests: options.includeTests || false,
+      verbose: options.verbose || false,
+      stats: options.stats || false,
+      json: options.json || false
+    });
+    if (options.json) {
+      console.log(JSON.stringify(report, null, 2));
+    }
+    const totalTime = Date.now() - startTime;
+    if (!options.json) {
+      console.log(`
+Analysis completed in ${(totalTime / 1e3).toFixed(2)}s
+`);
+    }
+  } catch (err) {
+    console.error("Error analyzing dead code:", err);
+    process.exit(1);
+  }
+});
 program.parse();

package/dist/mcpb-entry.js

@@ -6,7 +6,7 @@ import {
   startMcpServer,
   updateFileInGraph,
   watchProject
-} from "./chunk-65H7HCM4.js";
+} from "./chunk-IGRFC3MQ.js";
 
 // src/mcpb-entry.ts
 import { resolve } from "path";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "depwire-cli",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Code cross-reference visualization and AI context engine for TypeScript, JavaScript, Python, and Go. Zero native dependencies — works on Windows, macOS, and Linux.",
   "type": "module",
   "bin": {
@@ -31,7 +31,7 @@
     "cross-reference"
   ],
   "author": "Atef Ataya (https://www.youtube.com/@atefataya)",
-  "license": "BSL-1.1",
+  "license": "BUSL-1.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/depwire/depwire.git"
@@ -51,6 +51,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.26.0",
+    "chalk": "^5.6.2",
     "chokidar": "5.0.0",
     "commander": "14.0.3",
     "express": "5.2.1",