@thoughtflow/codebase 0.2.0

package/src/tools/codebase/codebase-analyze.tool.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import { ToolBase, ToolContext, ToolExecutionResult } from "@thoughtflow/core";
+
+export class CodebaseAnalyzeTool extends ToolBase {
+  readonly name = "codebaseAnalyze";
+  readonly description = "Run the full deep analysis pipeline — analyze the entire repository from scratch";
+
+  constructor() {
+    super(z.object({
+      projectPath: z.string().optional(),
+      phases: z.array(z.enum(["discover", "index", "graph", "extract-knowledge", "cross-reference"])).optional(),
+    }));
+  }
+
+  async run(_input: Record<string, unknown>, _ctx: ToolContext): Promise<ToolExecutionResult> {
+    return { success: true, output: JSON.stringify({ report: {}, status: "not implemented" }) };
+  }
+}

package/src/tools/codebase/codebase-crossref.tool.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import { ToolBase, ToolContext, ToolExecutionResult } from "@thoughtflow/core";
+
+export class CodebaseCrossrefTool extends ToolBase {
+  readonly name = "codebaseCrossref";
+  readonly description = "Trace cross-references: which code implements which feature, which doc describes which module?";
+
+  constructor() {
+    super(z.object({
+      query: z.string(),
+      traceType: z.enum(["feature-to-code", "code-to-doc", "doc-to-code", "all"]).optional(),
+    }));
+  }
+
+  async run(_input: Record<string, unknown>, _ctx: ToolContext): Promise<ToolExecutionResult> {
+    return { success: true, output: JSON.stringify({ references: [], chains: [] }) };
+  }
+}

package/src/tools/codebase/codebase-flow.tool.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import { ToolBase, ToolContext, ToolExecutionResult } from "@thoughtflow/core";
+
+export class CodebaseFlowTool extends ToolBase {
+  readonly name = "codebaseFlow";
+  readonly description = "Trace call flow forward from an entry point through the dependency graph";
+
+  constructor() {
+    super(z.object({
+      entrypoint: z.string().optional(),
+      maxDepth: z.number().optional(),
+    }));
+  }
+
+  async run(_input: Record<string, unknown>, _ctx: ToolContext): Promise<ToolExecutionResult> {
+    return { success: true, output: JSON.stringify({ entrypoints: [], flow: [] }) };
+  }
+}

package/src/tools/codebase/codebase-graph-circular.tool.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import { ToolBase, ToolContext, ToolExecutionResult } from "@thoughtflow/core";
+
+export class CodebaseGraphCircularTool extends ToolBase {
+  readonly name = "codebaseGraphCircular";
+  readonly description = "Detect circular dependencies in the codebase";
+
+  constructor() {
+    super(z.object({}));
+  }
+
+  async run(_input: Record<string, unknown>, _ctx: ToolContext): Promise<ToolExecutionResult> {
+    return { success: true, output: JSON.stringify({ cycles: [] }) };
+  }
+}

package/src/tools/codebase/codebase-graph-query.tool.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+import { ToolBase, ToolContext, ToolExecutionResult } from "@thoughtflow/core";
+
+export class CodebaseGraphQueryTool extends ToolBase {
+  readonly name = "codebaseGraphQuery";
+  readonly description = "Query the dependency graph: what does a file import, and what depends on it?";
+
+  constructor() {
+    super(z.object({
+      filePath: z.string(),
+      direction: z.enum(["imports", "dependents", "both"]).optional(),
+    }));
+  }
+
+  async run(input: Record<string, unknown>, _ctx: ToolContext): Promise<ToolExecutionResult> {
+    const { filePath } = input as { filePath: string };
+    return { success: true, output: JSON.stringify({ filePath, imports: [], dependents: [] }) };
+  }
+}

package/src/tools/codebase/codebase-graph-stats.tool.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import { ToolBase, ToolContext, ToolExecutionResult } from "@thoughtflow/core";
+
+export class CodebaseGraphStatsTool extends ToolBase {
+  readonly name = "codebaseGraphStats";
+  readonly description = "Get statistics about the dependency graph (nodes, edges, density, top modules)";
+
+  constructor() {
+    super(z.object({}));
+  }
+
+  async run(_input: Record<string, unknown>, _ctx: ToolContext): Promise<ToolExecutionResult> {
+    return { success: true, output: JSON.stringify({ nodes: 0, edges: 0, density: 0, topModules: [] }) };
+  }
+}

package/src/tools/codebase/codebase-graph-visualize.tool.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+import { ToolBase, ToolContext, ToolExecutionResult } from "@thoughtflow/core";
+
+export class CodebaseGraphVisualizeTool extends ToolBase {
+  readonly name = "codebaseGraphVisualize";
+  readonly description = "Generate a Mermaid diagram or interactive HTML visualization of the dependency graph";
+
+  constructor() {
+    super(z.object({
+      format: z.enum(["mermaid", "html"]).optional(),
+      maxNodes: z.number().optional(),
+    }));
+  }
+
+  async run(input: Record<string, unknown>, _ctx: ToolContext): Promise<ToolExecutionResult> {
+    const format = (input as { format?: string }).format ?? "mermaid";
+    return { success: true, output: JSON.stringify({ diagram: "", format }) };
+  }
+}

package/src/tools/codebase/codebase-impact.tool.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+import { ToolBase, ToolContext, ToolExecutionResult } from "@thoughtflow/core";
+
+export class CodebaseImpactTool extends ToolBase {
+  readonly name = "codebaseImpact";
+  readonly description = "Analyze blast radius: what files would be affected by changing a given file?";
+
+  constructor() {
+    super(z.object({
+      targetFile: z.string(),
+      maxHops: z.number().optional(),
+    }));
+  }
+
+  async run(input: Record<string, unknown>, _ctx: ToolContext): Promise<ToolExecutionResult> {
+    const { targetFile } = input as { targetFile: string };
+    return { success: true, output: JSON.stringify({ target: targetFile, affectedFiles: [], hops: [] }) };
+  }
+}

package/src/tools/codebase/codebase-index.tool.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+import { ToolBase, ToolContext, ToolExecutionResult } from "@thoughtflow/core";
+
+export class CodebaseIndexTool extends ToolBase {
+  readonly name = "codebaseIndex";
+  readonly description = "Index the current codebase — discovers files, chunks code, generates embeddings, stores to vector DB";
+
+  constructor() {
+    super(z.object({
+      projectPath: z.string().optional(),
+      mode: z.enum(["full", "incremental"]).optional(),
+      includeDocs: z.boolean().optional(),
+    }));
+  }
+
+  async run(_input: Record<string, unknown>, _ctx: ToolContext): Promise<ToolExecutionResult> {
+    return { success: true, output: JSON.stringify({ message: "Indexing started — use codebase_status to check progress" }) };
+  }
+}

package/src/tools/codebase/codebase-knowledge.tool.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import { ToolBase, ToolContext, ToolExecutionResult } from "@thoughtflow/core";
+
+export class CodebaseKnowledgeTool extends ToolBase {
+  readonly name = "codebaseKnowledge";
+  readonly description = "Search across extracted documentation, business plans, guidelines, and architectural decisions";
+
+  constructor() {
+    super(z.object({
+      query: z.string(),
+      docType: z.string().optional(),
+      limit: z.number().optional(),
+    }));
+  }
+
+  async run(input: Record<string, unknown>, _ctx: ToolContext): Promise<ToolExecutionResult> {
+    const { query } = input as { query: string };
+    return { success: true, output: JSON.stringify({ results: [], query }) };
+  }
+}

package/src/tools/codebase/codebase-search.tool.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import { ToolBase, ToolContext, ToolExecutionResult } from "@thoughtflow/core";
+
+export class CodebaseSearchTool extends ToolBase {
+  readonly name = "codebaseSearch";
+  readonly description = "Hybrid semantic + keyword search across the indexed codebase";
+
+  constructor() {
+    super(z.object({
+      query: z.string(),
+      limit: z.number().optional(),
+      mode: z.enum(["hybrid", "semantic", "keyword"]).optional(),
+      filterPath: z.string().optional(),
+      filterLanguage: z.string().optional(),
+    }));
+  }
+
+  async run(input: Record<string, unknown>, _ctx: ToolContext): Promise<ToolExecutionResult> {
+    const { query } = input as { query: string };
+    return { success: true, output: JSON.stringify({ results: [], query }) };
+  }
+}

package/src/tools/codebase/codebase-status.tool.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import { ToolBase, ToolContext, ToolExecutionResult } from "@thoughtflow/core";
+
+export class CodebaseStatusTool extends ToolBase {
+  readonly name = "codebaseStatus";
+  readonly description = "Check indexing status and statistics for the codebase";
+
+  constructor() {
+    super(z.object({
+      projectPath: z.string().optional(),
+    }));
+  }
+
+  async run(_input: Record<string, unknown>, _ctx: ToolContext): Promise<ToolExecutionResult> {
+    return { success: true, output: JSON.stringify({ indexed: false, stats: {} }) };
+  }
+}

package/src/tools/neural/comparative-analysis.tool.ts

@@ -0,0 +1,309 @@
+import { z } from "zod";
+import { ToolBase, ToolContext, ToolExecutionResult } from "@thoughtflow/core";
+import type { DesignComplianceResult, DesignDiscrepancy, Warning, CriticalIssue } from "@thoughtflow/core";
+
+export interface ComparativeAnalysisConfig {
+  /** Custom persona prompt for LLM-powered comparison */
+  personaPrompt?: string;
+  /** Scoring weights for compliance calculation */
+  scoringWeights?: {
+    penaltyPerDiscrepancy?: number;
+    criticalMultiplier?: number;
+  };
+  /** Char limits for state/content truncation */
+  truncation?: {
+    actualMaxChars?: number;
+    expectedMaxChars?: number;
+    contextMaxChars?: number;
+  };
+  /** Custom cross-cutting checks to run after comparison */
+  crossCuttingChecks?: Array<{
+    keyword: string;
+    severity: "low" | "medium" | "high";
+    title: string;
+    suggestion: string;
+  }>;
+}
+
+const ComparativeResultSchema = z.object({
+  overallCompliance: z.number().min(0).max(1),
+  sections: z.array(z.object({
+    section: z.string(),
+    status: z.enum(["compliant", "partial", "non_compliant", "not_applicable"]),
+    details: z.string(),
+    evidenceRefs: z.array(z.string()).optional(),
+  })),
+  discrepancies: z.array(z.object({
+    section: z.string(),
+    expected: z.string(),
+    actual: z.string(),
+    severity: z.enum(["low", "medium", "high", "critical"]),
+    fix: z.string(),
+  })),
+  additionalWarnings: z.array(z.object({
+    title: z.string(),
+    description: z.string(),
+    severity: z.enum(["low", "medium", "high"]),
+    relatedRule: z.string().optional(),
+    suggestion: z.string(),
+  })),
+  additionalCritical: z.array(z.object({
+    title: z.string(),
+    description: z.string(),
+    impact: z.string(),
+    blocking: z.boolean(),
+    relatedRule: z.string().optional(),
+    suggestedFix: z.string(),
+  })),
+  summary: z.string(),
+});
+
+export class ComparativeAnalysisTool extends ToolBase {
+  readonly name = "comparativeAnalysis";
+  readonly description =
+    "Compare actual state (code, files, screenshots) against expected state (design specs, rules, guidelines). " +
+    "Detects discrepancies, compliance issues, and suggests fixes. " +
+    "Returns structured output with: target (what was checked), additionalWarnings (non-critical issues), " +
+    "additionalCritical (blocking issues), designCompliance (per-section status), diffDesign (expected vs actual). " +
+    "Use this when you need to verify implementation against design specifications or coding rules.";
+  override readonly readonly = true;
+  readonly namespace = "neural";
+  readonly tags = ["analysis", "compare", "verify"];
+
+  constructor(private readonly config: ComparativeAnalysisConfig = {}) {
+    super(
+      z.object({
+        actualState: z.string().describe(
+          "What currently exists — file content, code snippet, or description of current state",
+        ),
+        expectedState: z.string().describe(
+          "What should exist — design spec, rules, acceptance criteria, or expected behavior",
+        ),
+        context: z.array(z.string()).optional().describe(
+          "Additional context documents (architecture docs, related files, etc.)",
+        ),
+        checkSections: z.array(z.string()).optional().describe(
+          "Specific sections/aspects to compare (e.g. ['colors', 'spacing', 'routing', 'auth'])",
+        ),
+        strictMode: z.boolean().optional().default(false).describe(
+          "If true, flags even minor deviations as warnings",
+        ),
+      })
+    );
+  }
+
+  async run(input: Record<string, unknown>, ctx: ToolContext): Promise<ToolExecutionResult> {
+    const actualState = input["actualState"] as string;
+    const expectedState = input["expectedState"] as string;
+    const context = input["context"] as string[] | undefined;
+    const checkSections = input["checkSections"] as string[] | undefined;
+    const strictMode = (input["strictMode"] as boolean) ?? false;
+
+    ctx.emitProgress?.("Starting comparative analysis...");
+
+    const callStructured = ctx.conversation?.callStructured;
+    if (callStructured) {
+      try {
+        ctx.emitProgress?.("Running LLM-powered comparison...");
+        const result = await callStructured(this.buildLLMPrompt(
+          actualState, expectedState, context, checkSections, strictMode,
+        ), ComparativeResultSchema);
+
+        ctx.emitProgress?.("Comparison complete", {
+          compliance: result.overallCompliance,
+          discrepancies: result.discrepancies.length,
+          warnings: result.additionalWarnings.length,
+          criticals: result.additionalCritical.length,
+        });
+
+        return {
+          success: true,
+          output: JSON.stringify(this.formatOutput(result), null, 2),
+          data: { result },
+        };
+      } catch (err) {
+        ctx.emitProgress?.(`LLM comparison failed: ${String(err)}`);
+      }
+    }
+
+    // Fallback: keyword-based comparison
+    ctx.emitProgress?.("Running heuristic comparison...");
+    const heuristic = this.heuristicCompare(actualState, expectedState, checkSections, strictMode);
+    return {
+      success: true,
+      output: JSON.stringify(heuristic, null, 2),
+      data: { result: heuristic },
+    };
+  }
+
+  private buildLLMPrompt(
+    actual: string,
+    expected: string,
+    context: string[] | undefined,
+    sections: string[] | undefined,
+    strictMode: boolean,
+  ): string {
+    const t = this.config.truncation ?? {};
+    const actualChars = t.actualMaxChars ?? 3000;
+    const expectedChars = t.expectedMaxChars ?? 3000;
+    const ctxChars = t.contextMaxChars ?? 2000;
+
+    const parts: string[] = [];
+    parts.push(this.config.personaPrompt ??
+      "You are a design compliance auditor. Compare the ACTUAL implementation against the EXPECTED specification.");
+    parts.push(`\n## ACTUAL State (what currently exists)\n${actual.slice(0, actualChars)}`);
+    parts.push(`\n## EXPECTED State (what should exist)\n${expected.slice(0, expectedChars)}`);
+
+    if (context && context.length > 0) {
+      parts.push(`\n## Additional Context\n${context.join("\n\n").slice(0, ctxChars)}`);
+    }
+
+    parts.push("\n## Instructions");
+
+    if (sections && sections.length > 0) {
+      parts.push(`Check these specific sections: ${sections.join(", ")}`);
+    }
+
+    parts.push(strictMode
+      ? "STRICT MODE: Flag every deviation, even minor spacing/color differences."
+      : "Balanced mode: Focus on functional and design-breaking issues. Minor style deviations are warnings."
+    );
+    parts.push(``);
+    parts.push("Return structured JSON with:");
+    parts.push("- overallCompliance (0-1, where 1 = perfect match)");
+    parts.push("- sections: per-section compliance status");
+    parts.push("- discrepancies: expected vs actual with severity and suggested fix");
+    parts.push("- additionalWarnings: non-critical issues found beyond the immediate scope");
+    parts.push("- additionalCritical: blocking or severe issues");
+    parts.push("- summary: concise human-readable verdict");
+
+    return parts.join("\n");
+  }
+
+  private heuristicCompare(
+    actual: string,
+    expected: string,
+    sections: string[] | undefined,
+    strictMode: boolean,
+  ): object {
+    const discrepancies: DesignDiscrepancy[] = [];
+    const warnings: Warning[] = [];
+    const criticals: CriticalIssue[] = [];
+    const sectionResults: DesignComplianceResult["sections"] = [];
+
+    const checkList = sections ?? ["overall"];
+    const actualLower = actual.toLowerCase();
+    const expectedLower = expected.toLowerCase();
+
+    // Check for common issues
+    for (const section of checkList) {
+      const sectionLower = section.toLowerCase();
+
+      // Color-related checks
+      if (sectionLower.includes("color") || sectionLower.includes("style") || sectionLower.includes("css")) {
+        const expectedColors = expectedLower.match(/#[0-9a-f]{3,6}|rgb\([^)]+\)|red|blue|green|white|black/g);
+        const actualColors = actualLower.match(/#[0-9a-f]{3,6}|rgb\([^)]+\)|red|blue|green|white|black/g);
+        if (expectedColors && actualColors) {
+          for (const ec of expectedColors) {
+            if (!actualColors.includes(ec)) {
+              discrepancies.push({
+                section,
+                expected: `Color should include ${ec}`,
+                actual: `Color ${ec} not found in implementation`,
+                severity: strictMode ? "medium" : "low",
+                fix: `Add color ${ec} as specified`,
+              });
+            }
+          }
+        }
+        sectionResults.push({ section, status: discrepancies.length === 0 ? "compliant" : "partial", details: `${discrepancies.length} color mismatches`, evidenceRefs: [] });
+      }
+
+      // Navigation/routing checks
+      if (sectionLower.includes("nav") || sectionLower.includes("rout") || sectionLower.includes("link")) {
+        const hasNavActual = /<nav|navigation|navigate|route|link/i.test(actual);
+        if (!hasNavActual) {
+          discrepancies.push({
+            section,
+            expected: `Navigation structure should be present`,
+            actual: "No navigation pattern detected",
+            severity: "high",
+            fix: "Implement navigation as specified",
+          });
+        }
+        sectionResults.push({ section, status: hasNavActual ? "compliant" : "non_compliant", details: "Navigation check", evidenceRefs: [] });
+      }
+
+      // Default section
+      // Always run default comparison for sections that aren't specifically handled
+      {
+        // Basic content comparison
+        const expectedKeywords = expectedLower.split(/\s+/).filter((w) => w.length > 3).slice(0, 10);
+        const missingKeywords = expectedKeywords.filter((kw) => !actualLower.includes(kw));
+        if (missingKeywords.length > 3) {
+          discrepancies.push({
+            section,
+            expected: `Should contain: ${missingKeywords.join(", ")}`,
+            actual: "Keywords not found in implementation",
+            severity: "medium",
+            fix: "Ensure implementation includes expected content",
+          });
+        }
+        sectionResults.push({
+          section,
+          status: missingKeywords.length === 0 ? "compliant" : missingKeywords.length <= 3 ? "partial" : "non_compliant",
+          details: `${missingKeywords.length}/${expectedKeywords.length} keywords missing`,
+          evidenceRefs: [],
+        });
+      }
+    }
+
+    // Always check for common cross-cutting concerns
+    const crossChecks = this.config.crossCuttingChecks ?? [
+      { keyword: "test", severity: "medium" as const, title: "Testing not detected in implementation", suggestion: "Add unit and integration tests" },
+      { keyword: "error", severity: "medium" as const, title: "Error handling may be missing", suggestion: "Add error handling and user feedback" },
+    ];
+    for (const check of crossChecks) {
+      if (!actualLower.includes(check.keyword) && expectedLower.includes(check.keyword)) {
+        warnings.push({
+          sourceNodeId: "",
+          title: check.title,
+          description: `Expected specification mentions ${check.keyword}, not detected in implementation`,
+          severity: check.severity,
+          suggestion: check.suggestion,
+        });
+      }
+    }
+
+    const penalty = this.config.scoringWeights?.penaltyPerDiscrepancy ?? 0.15;
+    return {
+      overallCompliance: discrepancies.length === 0 ? 1 : Math.max(0, 1 - discrepancies.length * penalty),
+      sections: sectionResults,
+      discrepancies,
+      additionalWarnings: warnings,
+      additionalCritical: criticals,
+      summary: discrepancies.length === 0
+        ? "Implementation appears compliant with specification"
+        : `${discrepancies.length} discrepancy(s) found, ${warnings.length} warning(s)`,
+    };
+  }
+
+  private formatOutput(result: z.infer<typeof ComparativeResultSchema>): object {
+    return {
+      target: "Comparative analysis between expected and actual state",
+      designCompliance: {
+        overallScore: result.overallCompliance,
+        sections: result.sections,
+        discrepancies: result.discrepancies,
+      },
+      additionalWarnings: result.additionalWarnings,
+      additionalCritical: result.additionalCritical,
+      diffDesign: result.discrepancies.map((d) => ({
+        section: d.section,
+        diff: `Expected: ${d.expected}\nActual: ${d.actual}\nFix: ${d.fix}`,
+        severity: d.severity,
+      })),
+      summary: result.summary,
+    };
+  }
+}

package/src/tools/neural/index.ts

@@ -0,0 +1,11 @@
+export * from "./neural-explain.tool";
+export * from "./neural-suggest.tool";
+export * from "./neural-review.tool";
+export * from "./neural-debug.tool";
+export * from "./neural-security.tool";
+export * from "./neural-smells.tool";
+export * from "./neural-deadcode.tool";
+export * from "./neural-similar.tool";
+export * from "./neural-pattern.tool";
+export * from "./neural-optimize.tool";
+export * from "./comparative-analysis.tool";

package/src/tools/neural/neural-deadcode.tool.ts

@@ -0,0 +1,105 @@
+import { z } from "zod";
+import { ToolBase, ToolContext, ToolExecutionResult } from "@thoughtflow/core";
+import { DependencyExtractor } from "../../libs/codebase/graph/dependency-extractor";
+import { CodebaseExplorer } from "../../libs/codebase/indexer/explorer";
+import * as fs from "node:fs";
+
+export class NeuralDeadcodeTool extends ToolBase {
+  readonly name = "neuralDeadcode";
+  readonly description = "Detect dead code: unused exports, unreachable functions, unused variables, and orphaned files using dependency graph analysis with LLM-guided false-positive filtering for uncertain cases.";
+  override readonly readonly = true;
+
+  constructor() {
+    super(z.object({
+      projectPath: z.string().optional(),
+      threshold: z.number().optional().describe("Min lines of dead code to report a file"),
+      llmVerify: z.boolean().optional().describe("Use LLM to verify uncertain cases"),
+    }));
+  }
+
+  async run(input: Record<string, unknown>, ctx: ToolContext): Promise<ToolExecutionResult> {
+    const rootPath = (input.projectPath as string) ?? process.cwd();
+    const threshold = (input.threshold as number) ?? 3;
+    const llmVerify = (input.llmVerify as boolean) ?? false;
+
+    const explorer = new CodebaseExplorer();
+    const files = explorer.explore({ rootPath });
+    const codeFiles = files.filter((f) => f.classification === "source-code")
+      .map((f) => ({ relativePath: f.relativePath, absolutePath: f.absolutePath }));
+
+    const depExtractor = new DependencyExtractor();
+    const graph = await depExtractor.buildGraph(codeFiles, rootPath);
+
+    const usedFiles = new Set<string>();
+    for (const edge of graph.edges) {
+      usedFiles.add(edge.to);
+    }
+
+    const deadExports: Array<{ file: string; symbol: string; type: string; line: number; confidence: string }> = [];
+    const unreachableFiles: string[] = [];
+
+    for (const file of codeFiles) {
+      const content = fs.readFileSync(file.absolutePath, "utf8");
+      const exports = this.extractExports(content, file.relativePath);
+
+      const hasIncoming = graph.edges.some((e) => e.to === file.relativePath);
+      const isEntry = file.relativePath.match(/(index|main|app|server|cli)\.ts$/);
+      if (!hasIncoming && !isEntry && file.relativePath.includes("/")) {
+        unreachableFiles.push(file.relativePath);
+      }
+
+      for (const exp of exports) {
+        let used = false;
+        for (const edge of graph.edges) {
+          if (edge.symbols?.includes(exp.symbol)) { used = true; break; }
+        }
+        if (!used && !exp.symbol.startsWith("_") && !exp.symbol.startsWith("I")) {
+          deadExports.push({ ...exp, confidence: "high" });
+        }
+      }
+    }
+
+    if (llmVerify && unreachableFiles.length > 0 && ctx.conversation) {
+      const prompt = `These files appear to have no imports from other project files. Are any of them entry points, referenced dynamically (e.g., loaded by string path, used in config files, routing tables, or build scripts), or otherwise used indirectly?\n\n${unreachableFiles.slice(0, 10).join("\n")}\n\nReturn: { falsePositives: string[] } listing only files that are genuinely in use.`;
+
+      try {
+        const result = await ctx.conversation.callStructured(prompt, z.object({ falsePositives: z.array(z.string()) }));
+        const fps = new Set(result.falsePositives ?? []);
+        const filtered = unreachableFiles.filter((f) => !fps.has(f));
+        return {
+          success: true,
+          output: JSON.stringify({
+            summary: { totalFiles: codeFiles.length, deadExports: deadExports.length, unreachableFiles: filtered.length, falsePositivesRemoved: fps.size },
+            deadExports: deadExports.slice(0, 50),
+            unreachableFiles: filtered,
+          }),
+        };
+      } catch {
+      }
+    }
+
+    return {
+      success: true,
+      output: JSON.stringify({
+        summary: { totalFiles: codeFiles.length, deadExports: deadExports.length, unreachableFiles: unreachableFiles.length },
+        deadExports: deadExports.slice(0, 50),
+        unreachableFiles: unreachableFiles.slice(0, 20),
+      }),
+    };
+  }
+
+  private extractExports(content: string, filePath: string): Array<{ file: string; symbol: string; type: string; line: number }> {
+    const exports: Array<{ file: string; symbol: string; type: string; line: number }> = [];
+    const lines = content.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      const match = lines[i].match(/(?:export\s+(?:async\s+)?(?:function|class|const|let|var|interface|type|enum)\s+(\w+))|(?:export\s*\{\s*([^}]+)\s*\})/);
+      if (match) {
+        const name = match[1] || match[2];
+        if (name) {
+          exports.push({ file: filePath, symbol: name, type: "export", line: i + 1 });
+        }
+      }
+    }
+    return exports;
+  }
+}