depwire-cli 0.2.6 → 0.3.1

package/dist/{chunk-V3SB37U3.js → chunk-LOX5NEND.js}

@@ -2044,6 +2044,43 @@ function buildGraph(parsedFiles) {
 }
 
 // src/graph/queries.ts
+function findSymbols(graph, query) {
+  if (query.includes("::")) {
+    if (graph.hasNode(query)) {
+      const attrs = graph.getNodeAttributes(query);
+      return [{
+        id: query,
+        name: attrs.name,
+        kind: attrs.kind,
+        filePath: attrs.filePath,
+        startLine: attrs.startLine,
+        endLine: attrs.endLine,
+        exported: attrs.exported,
+        scope: attrs.scope,
+        dependentCount: graph.inDegree(query)
+      }];
+    }
+  }
+  const queryLower = query.toLowerCase();
+  const results = [];
+  graph.forEachNode((nodeId, attrs) => {
+    if (attrs.name.toLowerCase() === queryLower) {
+      results.push({
+        id: nodeId,
+        name: attrs.name,
+        kind: attrs.kind,
+        filePath: attrs.filePath,
+        startLine: attrs.startLine,
+        endLine: attrs.endLine,
+        exported: attrs.exported,
+        scope: attrs.scope,
+        dependentCount: graph.inDegree(nodeId)
+      });
+    }
+  });
+  results.sort((a, b) => b.dependentCount - a.dependentCount);
+  return results;
+}
 function getDependencies(graph, symbolId) {
   if (!graph.hasNode(symbolId)) return [];
   const dependencies = [];
@@ -2364,7 +2401,7 @@ import { fileURLToPath } from "url";
 import { dirname as dirname5, join as join7 } from "path";
 import { WebSocketServer } from "ws";
 var __filename = fileURLToPath(import.meta.url);
-var __dirname = dirname5(__filename);
+var __dirname2 = dirname5(__filename);
 var activeServer = null;
 async function findAvailablePort(startPort, maxAttempts = 10) {
   const net = await import("net");
@@ -2402,7 +2439,7 @@ async function startVizServer(initialVizData, graph, projectRoot, port = 3333, s
   const availablePort = await findAvailablePort(port);
   const app = express();
   let vizData = initialVizData;
-  const publicDir = join7(__dirname, "viz", "public");
+  const publicDir = join7(__dirname2, "viz", "public");
   app.use(express.static(publicDir));
   app.get("/api/graph", (req, res) => {
     res.json(vizData);
@@ -2491,97 +2528,1824 @@ Depwire visualization running at ${url2}`);
       }
     }
   });
-  process.on("SIGINT", () => {
-    console.error("\nShutting down visualization server...");
-    activeServer = null;
-    watcher.close();
-    wss.close();
-    server.close(() => {
-      process.exit(0);
+  process.on("SIGINT", () => {
+    console.error("\nShutting down visualization server...");
+    activeServer = null;
+    watcher.close();
+    wss.close();
+    server.close(() => {
+      process.exit(0);
+    });
+  });
+  const url = `http://127.0.0.1:${availablePort}`;
+  return { server, url, alreadyRunning: false };
+}
+
+// src/mcp/state.ts
+function createEmptyState() {
+  return {
+    graph: null,
+    projectRoot: null,
+    projectName: null,
+    watcher: null
+  };
+}
+function isProjectLoaded(state) {
+  return state.graph !== null && state.projectRoot !== null;
+}
+
+// src/graph/updater.ts
+import { join as join8 } from "path";
+function removeFileFromGraph(graph, filePath) {
+  const nodesToRemove = [];
+  graph.forEachNode((node, attrs) => {
+    if (attrs.filePath === filePath) {
+      nodesToRemove.push(node);
+    }
+  });
+  nodesToRemove.forEach((node) => {
+    try {
+      graph.dropNode(node);
+    } catch (error) {
+    }
+  });
+}
+function addFileToGraph(graph, parsedFile) {
+  for (const symbol of parsedFile.symbols) {
+    const nodeId = `${parsedFile.filePath}::${symbol.name}`;
+    try {
+      graph.addNode(nodeId, {
+        name: symbol.name,
+        kind: symbol.kind,
+        filePath: parsedFile.filePath,
+        startLine: symbol.location.startLine,
+        endLine: symbol.location.endLine,
+        exported: symbol.exported,
+        scope: symbol.scope
+      });
+    } catch (error) {
+    }
+  }
+  for (const edge of parsedFile.edges) {
+    try {
+      graph.mergeEdge(edge.source, edge.target, {
+        kind: edge.kind,
+        sourceFile: edge.sourceFile,
+        targetFile: edge.targetFile
+      });
+    } catch (error) {
+    }
+  }
+}
+async function updateFileInGraph(graph, projectRoot, relativeFilePath) {
+  removeFileFromGraph(graph, relativeFilePath);
+  const absolutePath = join8(projectRoot, relativeFilePath);
+  try {
+    const parsedFile = parseTypeScriptFile(absolutePath, relativeFilePath);
+    addFileToGraph(graph, parsedFile);
+  } catch (error) {
+    console.error(`Failed to parse file ${relativeFilePath}:`, error);
+  }
+}
+
+// src/docs/generator.ts
+import { writeFileSync as writeFileSync2, mkdirSync, existsSync as existsSync6 } from "fs";
+import { join as join10 } from "path";
+
+// src/docs/architecture.ts
+import { dirname as dirname6 } from "path";
+
+// src/docs/templates.ts
+function header(text, level = 1) {
+  return `${"#".repeat(level)} ${text}
+
+`;
+}
+function code(text) {
+  return `\`${text}\``;
+}
+function codeBlock(code2, lang = "") {
+  return `\`\`\`${lang}
+${code2}
+\`\`\`
+
+`;
+}
+function unorderedList(items) {
+  return items.map((item) => `- ${item}`).join("\n") + "\n\n";
+}
+function orderedList(items) {
+  return items.map((item, i) => `${i + 1}. ${item}`).join("\n") + "\n\n";
+}
+function table(headers, rows) {
+  const headerRow = `| ${headers.join(" | ")} |`;
+  const separator = `| ${headers.map(() => "---").join(" | ")} |`;
+  const dataRows = rows.map((row) => `| ${row.join(" | ")} |`).join("\n");
+  return `${headerRow}
+${separator}
+${dataRows}
+
+`;
+}
+function blockquote(text) {
+  return `> ${text}
+
+`;
+}
+function timestamp(version, date, fileCount, symbolCount) {
+  return blockquote(`Auto-generated by Depwire ${version} on ${date} | ${fileCount.toLocaleString()} files, ${symbolCount.toLocaleString()} symbols`);
+}
+function formatNumber(n) {
+  return n.toLocaleString();
+}
+function formatPercent(value, total) {
+  if (total === 0) return "0.0%";
+  return `${(value / total * 100).toFixed(1)}%`;
+}
+function impactEmoji(count) {
+  if (count >= 20) return "\u{1F534}";
+  if (count >= 10) return "\u{1F7E1}";
+  if (count >= 5) return "\u{1F7E2}";
+  return "\u26AA";
+}
+
+// src/docs/architecture.ts
+function generateArchitecture(graph, projectRoot, version, parseTime) {
+  const startTime = Date.now();
+  let output = "";
+  const now = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  output += timestamp(version, now, getFileCount(graph), graph.order);
+  output += header("Architecture Overview");
+  output += header("Project Summary", 2);
+  output += generateProjectSummary(graph, parseTime);
+  output += header("Module Structure", 2);
+  output += generateModuleStructure(graph);
+  output += header("Entry Points", 2);
+  output += generateEntryPoints(graph);
+  output += header("Hub Files", 2);
+  output += generateHubFiles(graph);
+  output += header("Layer Analysis", 2);
+  output += generateLayerAnalysis(graph);
+  output += header("Circular Dependencies", 2);
+  output += generateCircularDependencies(graph);
+  return output;
+}
+function getFileCount(graph) {
+  const files = /* @__PURE__ */ new Set();
+  graph.forEachNode((node, attrs) => {
+    files.add(attrs.filePath);
+  });
+  return files.size;
+}
+function getLanguageStats(graph) {
+  const stats = {};
+  const files = /* @__PURE__ */ new Set();
+  graph.forEachNode((node, attrs) => {
+    if (!files.has(attrs.filePath)) {
+      files.add(attrs.filePath);
+      const ext = attrs.filePath.toLowerCase();
+      let lang;
+      if (ext.endsWith(".ts") || ext.endsWith(".tsx")) {
+        lang = "TypeScript";
+      } else if (ext.endsWith(".py")) {
+        lang = "Python";
+      } else if (ext.endsWith(".js") || ext.endsWith(".jsx") || ext.endsWith(".mjs") || ext.endsWith(".cjs")) {
+        lang = "JavaScript";
+      } else if (ext.endsWith(".go")) {
+        lang = "Go";
+      } else {
+        lang = "Other";
+      }
+      stats[lang] = (stats[lang] || 0) + 1;
+    }
+  });
+  return stats;
+}
+function generateProjectSummary(graph, parseTime) {
+  const fileCount = getFileCount(graph);
+  const symbolCount = graph.order;
+  const edgeCount = graph.size;
+  const languages = getLanguageStats(graph);
+  let output = "";
+  output += `- **Total Files:** ${formatNumber(fileCount)}
+`;
+  output += `- **Total Symbols:** ${formatNumber(symbolCount)}
+`;
+  output += `- **Total Edges:** ${formatNumber(edgeCount)}
+`;
+  output += `- **Parse Time:** ${parseTime.toFixed(1)}s
+`;
+  if (Object.keys(languages).length > 1) {
+    output += "\n**Languages:**\n\n";
+    const totalFiles = fileCount;
+    for (const [lang, count] of Object.entries(languages).sort((a, b) => b[1] - a[1])) {
+      output += `- ${lang}: ${count} files (${formatPercent(count, totalFiles)})
+`;
+    }
+  }
+  output += "\n";
+  return output;
+}
+function generateModuleStructure(graph) {
+  const dirStats = getDirectoryStats(graph);
+  if (dirStats.length === 0) {
+    return "No module structure detected (single file or flat structure).\n\n";
+  }
+  const headers = ["Directory", "Files", "Symbols", "Connections", "Role"];
+  const rows = dirStats.slice(0, 15).map((dir) => [
+    `\`${dir.name}\``,
+    formatNumber(dir.fileCount),
+    formatNumber(dir.symbolCount),
+    formatNumber(dir.connectionCount),
+    dir.role
+  ]);
+  return table(headers, rows);
+}
+function getDirectoryStats(graph) {
+  const dirMap = /* @__PURE__ */ new Map();
+  graph.forEachNode((node, attrs) => {
+    const dir = dirname6(attrs.filePath);
+    if (dir === ".") return;
+    if (!dirMap.has(dir)) {
+      dirMap.set(dir, {
+        name: dir,
+        fileCount: 0,
+        symbolCount: 0,
+        connectionCount: 0,
+        role: "",
+        typeCount: 0,
+        functionCount: 0,
+        outboundEdges: 0,
+        inboundEdges: 0
+      });
+    }
+    const dirStat = dirMap.get(dir);
+    dirStat.symbolCount++;
+    if (attrs.kind === "interface" || attrs.kind === "type_alias") {
+      dirStat.typeCount++;
+    } else if (attrs.kind === "function" || attrs.kind === "method") {
+      dirStat.functionCount++;
+    }
+  });
+  const filesPerDir = /* @__PURE__ */ new Map();
+  graph.forEachNode((node, attrs) => {
+    const dir = dirname6(attrs.filePath);
+    if (!filesPerDir.has(dir)) {
+      filesPerDir.set(dir, /* @__PURE__ */ new Set());
+    }
+    filesPerDir.get(dir).add(attrs.filePath);
+  });
+  filesPerDir.forEach((files, dir) => {
+    if (dirMap.has(dir)) {
+      dirMap.get(dir).fileCount = files.size;
+    }
+  });
+  const dirEdges = /* @__PURE__ */ new Map();
+  graph.forEachEdge((edge, attrs, source, target) => {
+    const sourceAttrs = graph.getNodeAttributes(source);
+    const targetAttrs = graph.getNodeAttributes(target);
+    const sourceDir = dirname6(sourceAttrs.filePath);
+    const targetDir = dirname6(targetAttrs.filePath);
+    if (sourceDir !== targetDir) {
+      if (!dirEdges.has(sourceDir)) {
+        dirEdges.set(sourceDir, { in: 0, out: 0 });
+      }
+      if (!dirEdges.has(targetDir)) {
+        dirEdges.set(targetDir, { in: 0, out: 0 });
+      }
+      dirEdges.get(sourceDir).out++;
+      dirEdges.get(targetDir).in++;
+    }
+  });
+  dirEdges.forEach((edges, dir) => {
+    if (dirMap.has(dir)) {
+      const stat = dirMap.get(dir);
+      stat.inboundEdges = edges.in;
+      stat.outboundEdges = edges.out;
+      stat.connectionCount = edges.in + edges.out;
+    }
+  });
+  dirMap.forEach((dir) => {
+    const typeRatio = dir.symbolCount > 0 ? dir.typeCount / dir.symbolCount : 0;
+    const outboundRatio = dir.connectionCount > 0 ? dir.outboundEdges / dir.connectionCount : 0;
+    const inboundRatio = dir.connectionCount > 0 ? dir.inboundEdges / dir.connectionCount : 0;
+    if (typeRatio > 0.7) {
+      dir.role = "Type definitions";
+    } else if (outboundRatio > 0.7) {
+      dir.role = "Orchestration / Entry points";
+    } else if (inboundRatio > 0.7) {
+      dir.role = "Shared utilities / Foundation";
+    } else {
+      dir.role = "Core logic";
+    }
+  });
+  return Array.from(dirMap.values()).sort((a, b) => b.symbolCount - a.symbolCount);
+}
+function generateEntryPoints(graph) {
+  const fileStats = getFileStats(graph);
+  const entryPoints = fileStats.filter((f) => f.outgoingRefs > 0).map((f) => ({
+    ...f,
+    ratio: f.incomingRefs === 0 ? Infinity : f.outgoingRefs / (f.incomingRefs + 1)
+  })).sort((a, b) => b.ratio - a.ratio).slice(0, 5);
+  if (entryPoints.length === 0) {
+    return "No clear entry points detected.\n\n";
+  }
+  const headers = ["File", "Outgoing", "Incoming", "Ratio"];
+  const rows = entryPoints.map((f) => [
+    `\`${f.filePath}\``,
+    formatNumber(f.outgoingRefs),
+    formatNumber(f.incomingRefs),
+    f.ratio === Infinity ? "\u221E" : f.ratio.toFixed(1)
+  ]);
+  return table(headers, rows);
+}
+function generateHubFiles(graph) {
+  const fileStats = getFileStats(graph);
+  const hubFiles = fileStats.sort((a, b) => b.incomingRefs - a.incomingRefs).slice(0, 10);
+  if (hubFiles.length === 0 || hubFiles[0].incomingRefs === 0) {
+    return "No hub files detected.\n\n";
+  }
+  const headers = ["File", "Dependents", "Symbols"];
+  const rows = hubFiles.map((f) => [
+    `\`${f.filePath}\``,
+    formatNumber(f.incomingRefs),
+    formatNumber(f.symbolCount)
+  ]);
+  return table(headers, rows);
+}
+function getFileStats(graph) {
+  const fileMap = /* @__PURE__ */ new Map();
+  graph.forEachNode((node, attrs) => {
+    if (!fileMap.has(attrs.filePath)) {
+      fileMap.set(attrs.filePath, {
+        symbolCount: 0,
+        incomingRefs: /* @__PURE__ */ new Set(),
+        outgoingRefs: /* @__PURE__ */ new Set()
+      });
+    }
+    fileMap.get(attrs.filePath).symbolCount++;
+  });
+  graph.forEachEdge((edge, attrs, source, target) => {
+    const sourceAttrs = graph.getNodeAttributes(source);
+    const targetAttrs = graph.getNodeAttributes(target);
+    if (sourceAttrs.filePath !== targetAttrs.filePath) {
+      const sourceFile = fileMap.get(sourceAttrs.filePath);
+      const targetFile = fileMap.get(targetAttrs.filePath);
+      if (sourceFile) {
+        sourceFile.outgoingRefs.add(targetAttrs.filePath);
+      }
+      if (targetFile) {
+        targetFile.incomingRefs.add(sourceAttrs.filePath);
+      }
+    }
+  });
+  const result = [];
+  for (const [filePath, data] of fileMap.entries()) {
+    result.push({
+      filePath,
+      symbolCount: data.symbolCount,
+      incomingRefs: data.incomingRefs.size,
+      outgoingRefs: data.outgoingRefs.size
+    });
+  }
+  return result;
+}
+function generateLayerAnalysis(graph) {
+  const dirStats = getDirectoryStats(graph);
+  if (dirStats.length === 0) {
+    return "No layered architecture detected (flat or single-file project).\n\n";
+  }
+  const foundation = dirStats.filter((d) => d.inboundEdges > d.outboundEdges * 2);
+  const orchestration = dirStats.filter((d) => d.outboundEdges > d.inboundEdges * 2);
+  const core = dirStats.filter((d) => !foundation.includes(d) && !orchestration.includes(d));
+  let output = "";
+  if (foundation.length > 0) {
+    output += "**Foundation Layer** (mostly imported by others):\n\n";
+    output += unorderedList(foundation.map((d) => `\`${d.name}\` \u2014 ${d.role}`));
+  }
+  if (core.length > 0) {
+    output += "**Core Layer** (balanced dependencies):\n\n";
+    output += unorderedList(core.map((d) => `\`${d.name}\` \u2014 ${d.role}`));
+  }
+  if (orchestration.length > 0) {
+    output += "**Orchestration Layer** (mostly imports from others):\n\n";
+    output += unorderedList(orchestration.map((d) => `\`${d.name}\` \u2014 ${d.role}`));
+  }
+  return output;
+}
+function generateCircularDependencies(graph) {
+  const cycles = detectCycles(graph);
+  if (cycles.length === 0) {
+    return "\u2705 No circular dependencies detected.\n\n";
+  }
+  let output = `\u26A0\uFE0F Found ${cycles.length} circular ${cycles.length === 1 ? "dependency" : "dependencies"}:
+
+`;
+  for (let i = 0; i < Math.min(cycles.length, 10); i++) {
+    const cycle = cycles[i];
+    output += `**Cycle ${i + 1}:**
+
+`;
+    output += codeBlock(cycle.path.join(" \u2192\n"), "");
+    output += `**Suggested fix:** ${cycle.suggestion}
+
+`;
+  }
+  if (cycles.length > 10) {
+    output += `... and ${cycles.length - 10} more cycles.
+
+`;
+  }
+  return output;
+}
+function detectCycles(graph) {
+  const cycles = [];
+  const visited = /* @__PURE__ */ new Set();
+  const recStack = /* @__PURE__ */ new Set();
+  const pathStack = [];
+  const fileGraph = /* @__PURE__ */ new Map();
+  graph.forEachEdge((edge, attrs, source, target) => {
+    const sourceFile = graph.getNodeAttributes(source).filePath;
+    const targetFile = graph.getNodeAttributes(target).filePath;
+    if (sourceFile !== targetFile) {
+      if (!fileGraph.has(sourceFile)) {
+        fileGraph.set(sourceFile, /* @__PURE__ */ new Set());
+      }
+      fileGraph.get(sourceFile).add(targetFile);
+    }
+  });
+  function dfs(file) {
+    visited.add(file);
+    recStack.add(file);
+    pathStack.push(file);
+    const neighbors = fileGraph.get(file);
+    if (neighbors) {
+      for (const neighbor of neighbors) {
+        if (!visited.has(neighbor)) {
+          if (dfs(neighbor)) {
+            return true;
+          }
+        } else if (recStack.has(neighbor)) {
+          const cycleStart = pathStack.indexOf(neighbor);
+          const cyclePath = pathStack.slice(cycleStart);
+          cyclePath.push(neighbor);
+          cycles.push({
+            path: cyclePath,
+            suggestion: "Extract shared types/interfaces to a common file"
+          });
+          return true;
+        }
+      }
+    }
+    recStack.delete(file);
+    pathStack.pop();
+    return false;
+  }
+  for (const file of fileGraph.keys()) {
+    if (!visited.has(file)) {
+      dfs(file);
+      recStack.clear();
+      pathStack.length = 0;
+    }
+  }
+  return cycles;
+}
+
+// src/docs/conventions.ts
+import { basename as basename2, extname as extname4 } from "path";
+function generateConventions(graph, projectRoot, version) {
+  let output = "";
+  const now = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  const fileCount = getFileCount2(graph);
+  output += timestamp(version, now, fileCount, graph.order);
+  output += header("Code Conventions");
+  output += "Auto-detected coding patterns and conventions in this codebase.\n\n";
+  output += header("File Organization", 2);
+  output += generateFileOrganization(graph);
+  output += header("Naming Patterns", 2);
+  output += generateNamingPatterns(graph);
+  output += header("Import Style", 2);
+  output += generateImportStyle(graph);
+  output += header("Export Patterns", 2);
+  output += generateExportPatterns(graph);
+  output += header("Symbol Distribution", 2);
+  output += generateSymbolDistribution(graph);
+  output += header("Detected Design Patterns", 2);
+  output += generateDesignPatterns(graph);
+  return output;
+}
+function getFileCount2(graph) {
+  const files = /* @__PURE__ */ new Set();
+  graph.forEachNode((node, attrs) => {
+    files.add(attrs.filePath);
+  });
+  return files.size;
+}
+function generateFileOrganization(graph) {
+  const files = /* @__PURE__ */ new Set();
+  let barrelFileCount = 0;
+  let testFileCount = 0;
+  let totalLines = 0;
+  const fileSizes = [];
+  graph.forEachNode((node, attrs) => {
+    if (!files.has(attrs.filePath)) {
+      files.add(attrs.filePath);
+      const fileName = basename2(attrs.filePath);
+      if (fileName === "index.ts" || fileName === "index.js" || fileName === "index.tsx" || fileName === "index.jsx") {
+        barrelFileCount++;
+      }
+      if (fileName.includes(".test.") || fileName.includes(".spec.") || attrs.filePath.includes("__tests__")) {
+        testFileCount++;
+      }
+      const maxLine = getMaxLineNumber(graph, attrs.filePath);
+      if (maxLine > 0) {
+        fileSizes.push(maxLine);
+        totalLines += maxLine;
+      }
+    }
+  });
+  const avgFileSize = fileSizes.length > 0 ? Math.round(totalLines / fileSizes.length) : 0;
+  const medianFileSize = fileSizes.length > 0 ? getMedian(fileSizes) : 0;
+  let output = "";
+  output += `- **Total Files:** ${formatNumber(files.size)}
+`;
+  output += `- **Barrel Files (index.*):** ${formatNumber(barrelFileCount)} (${formatPercent(barrelFileCount, files.size)})
+`;
+  output += `- **Test Files:** ${formatNumber(testFileCount)} (${formatPercent(testFileCount, files.size)})
+`;
+  if (avgFileSize > 0) {
+    output += `- **Average File Size:** ${formatNumber(avgFileSize)} lines
+`;
+    output += `- **Median File Size:** ${formatNumber(medianFileSize)} lines
+`;
+  }
+  output += "\n";
+  return output;
+}
+function getMaxLineNumber(graph, filePath) {
+  let maxLine = 0;
+  graph.forEachNode((node, attrs) => {
+    if (attrs.filePath === filePath) {
+      maxLine = Math.max(maxLine, attrs.endLine);
+    }
+  });
+  return maxLine;
+}
+function getMedian(numbers) {
+  const sorted = [...numbers].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 0 ? Math.round((sorted[mid - 1] + sorted[mid]) / 2) : sorted[mid];
+}
+function generateNamingPatterns(graph) {
+  const patterns = {
+    files: { camelCase: 0, PascalCase: 0, kebabCase: 0, snakeCase: 0, total: 0 },
+    functions: { camelCase: 0, PascalCase: 0, snakeCase: 0, total: 0 },
+    classes: { PascalCase: 0, other: 0, total: 0 },
+    interfaces: { IPrefixed: 0, PascalCase: 0, other: 0, total: 0 },
+    constants: { UPPER_SNAKE: 0, other: 0, total: 0 },
+    types: { PascalCase: 0, camelCase: 0, other: 0, total: 0 }
+  };
+  const files = /* @__PURE__ */ new Set();
+  graph.forEachNode((node, attrs) => {
+    if (!files.has(attrs.filePath)) {
+      files.add(attrs.filePath);
+      const fileName = basename2(attrs.filePath, extname4(attrs.filePath));
+      if (isCamelCase(fileName)) patterns.files.camelCase++;
+      else if (isPascalCase(fileName)) patterns.files.PascalCase++;
+      else if (isKebabCase(fileName)) patterns.files.kebabCase++;
+      else if (isSnakeCase(fileName)) patterns.files.snakeCase++;
+      patterns.files.total++;
+    }
+    const name = attrs.name;
+    const kind = attrs.kind;
+    if (kind === "function" || kind === "method") {
+      if (isCamelCase(name)) patterns.functions.camelCase++;
+      else if (isPascalCase(name)) patterns.functions.PascalCase++;
+      else if (isSnakeCase(name)) patterns.functions.snakeCase++;
+      patterns.functions.total++;
+    } else if (kind === "class") {
+      if (isPascalCase(name)) patterns.classes.PascalCase++;
+      else patterns.classes.other++;
+      patterns.classes.total++;
+    } else if (kind === "interface") {
+      if (name.startsWith("I") && isPascalCase(name.slice(1))) patterns.interfaces.IPrefixed++;
+      else if (isPascalCase(name)) patterns.interfaces.PascalCase++;
+      else patterns.interfaces.other++;
+      patterns.interfaces.total++;
+    } else if (kind === "constant") {
+      if (isUpperSnakeCase(name)) patterns.constants.UPPER_SNAKE++;
+      else patterns.constants.other++;
+      patterns.constants.total++;
+    } else if (kind === "type_alias") {
+      if (isPascalCase(name)) patterns.types.PascalCase++;
+      else if (isCamelCase(name)) patterns.types.camelCase++;
+      else patterns.types.other++;
+      patterns.types.total++;
+    }
+  });
+  let output = "";
+  if (patterns.files.total > 0) {
+    output += "**File Naming:**\n\n";
+    if (patterns.files.kebabCase > 0) {
+      output += `- kebab-case: ${formatPercent(patterns.files.kebabCase, patterns.files.total)}
+`;
+    }
+    if (patterns.files.camelCase > 0) {
+      output += `- camelCase: ${formatPercent(patterns.files.camelCase, patterns.files.total)}
+`;
+    }
+    if (patterns.files.PascalCase > 0) {
+      output += `- PascalCase: ${formatPercent(patterns.files.PascalCase, patterns.files.total)}
+`;
+    }
+    if (patterns.files.snakeCase > 0) {
+      output += `- snake_case: ${formatPercent(patterns.files.snakeCase, patterns.files.total)}
+`;
+    }
+    output += "\n";
+  }
+  if (patterns.functions.total > 0) {
+    output += "**Function Naming:**\n\n";
+    if (patterns.functions.camelCase > 0) {
+      output += `- camelCase: ${formatPercent(patterns.functions.camelCase, patterns.functions.total)}
+`;
+    }
+    if (patterns.functions.snakeCase > 0) {
+      output += `- snake_case: ${formatPercent(patterns.functions.snakeCase, patterns.functions.total)}
+`;
+    }
+    if (patterns.functions.PascalCase > 0) {
+      output += `- PascalCase: ${formatPercent(patterns.functions.PascalCase, patterns.functions.total)}
+`;
+    }
+    output += "\n";
+  }
+  if (patterns.classes.total > 0) {
+    output += "**Class Naming:**\n\n";
+    output += `- PascalCase: ${formatPercent(patterns.classes.PascalCase, patterns.classes.total)}
+`;
+    if (patterns.classes.other > 0) {
+      output += `- Other: ${formatPercent(patterns.classes.other, patterns.classes.total)}
+`;
+    }
+    output += "\n";
+  }
+  if (patterns.interfaces.total > 0) {
+    output += "**Interface Naming:**\n\n";
+    if (patterns.interfaces.IPrefixed > 0) {
+      output += `- I-prefix (IPerson): ${formatPercent(patterns.interfaces.IPrefixed, patterns.interfaces.total)}
+`;
+    }
+    if (patterns.interfaces.PascalCase > 0) {
+      output += `- PascalCase (Person): ${formatPercent(patterns.interfaces.PascalCase, patterns.interfaces.total)}
+`;
+    }
+    if (patterns.interfaces.other > 0) {
+      output += `- Other: ${formatPercent(patterns.interfaces.other, patterns.interfaces.total)}
+`;
+    }
+    output += "\n";
+  }
+  if (patterns.types.total > 0) {
+    output += "**Type Naming:**\n\n";
+    if (patterns.types.PascalCase > 0) {
+      output += `- PascalCase: ${formatPercent(patterns.types.PascalCase, patterns.types.total)}
+`;
+    }
+    if (patterns.types.camelCase > 0) {
+      output += `- camelCase: ${formatPercent(patterns.types.camelCase, patterns.types.total)}
+`;
+    }
+    if (patterns.types.other > 0) {
+      output += `- Other: ${formatPercent(patterns.types.other, patterns.types.total)}
+`;
+    }
+    output += "\n";
+  }
+  if (patterns.constants.total > 0) {
+    output += "**Constant Naming:**\n\n";
+    output += `- UPPER_SNAKE_CASE: ${formatPercent(patterns.constants.UPPER_SNAKE, patterns.constants.total)}
+`;
+    if (patterns.constants.other > 0) {
+      output += `- Other: ${formatPercent(patterns.constants.other, patterns.constants.total)}
+`;
+    }
+    output += "\n";
+  }
+  return output;
+}
+function generateImportStyle(graph) {
+  let barrelImportCount = 0;
+  let pathAliasCount = 0;
+  let totalImports = 0;
+  let namedExportCount = 0;
+  let defaultExportCount = 0;
+  graph.forEachEdge((edge, attrs, source, target) => {
+    const sourceAttrs = graph.getNodeAttributes(source);
+    const targetAttrs = graph.getNodeAttributes(target);
+    if (sourceAttrs.filePath !== targetAttrs.filePath && attrs.kind === "imports") {
+      totalImports++;
+      if (targetAttrs.filePath.endsWith("/index.ts") || targetAttrs.filePath.endsWith("/index.js")) {
+        barrelImportCount++;
+      }
+      if (targetAttrs.filePath.startsWith("@/") || targetAttrs.filePath.startsWith("~/") || targetAttrs.filePath.startsWith("src/")) {
+        pathAliasCount++;
+      }
+    }
+  });
+  graph.forEachNode((node, attrs) => {
+    if (attrs.exported) {
+      if (attrs.name === "default") {
+        defaultExportCount++;
+      } else {
+        namedExportCount++;
+      }
+    }
+  });
+  let output = "";
+  if (totalImports > 0) {
+    output += `- **Total Cross-File Imports:** ${formatNumber(totalImports)}
+`;
+    if (barrelImportCount > 0) {
+      output += `- **Barrel Imports (from index files):** ${formatPercent(barrelImportCount, totalImports)}
+`;
+    }
+    if (pathAliasCount > 0) {
+      output += `- **Path Alias Usage (@/ or ~/):** ${formatPercent(pathAliasCount, totalImports)}
+`;
+    }
+  }
+  output += "\n";
+  return output;
+}
+function generateExportPatterns(graph) {
+  let namedExportCount = 0;
+  let defaultExportCount = 0;
+  let reExportCount = 0;
+  graph.forEachNode((node, attrs) => {
+    if (attrs.exported) {
+      if (attrs.name === "default") {
+        defaultExportCount++;
+      } else {
+        namedExportCount++;
+      }
+    }
+    if (attrs.kind === "export") {
+      reExportCount++;
+    }
+  });
+  const totalExports = namedExportCount + defaultExportCount;
+  let output = "";
+  if (totalExports > 0) {
+    output += `- **Named Exports:** ${formatNumber(namedExportCount)} (${formatPercent(namedExportCount, totalExports)})
+`;
+    output += `- **Default Exports:** ${formatNumber(defaultExportCount)} (${formatPercent(defaultExportCount, totalExports)})
+`;
+    if (reExportCount > 0) {
+      output += `- **Re-exports:** ${formatNumber(reExportCount)}
+`;
+    }
+  }
+  output += "\n";
+  return output;
+}
+function generateSymbolDistribution(graph) {
+  const symbolCounts = {
+    function: 0,
+    class: 0,
+    variable: 0,
+    constant: 0,
+    type_alias: 0,
+    interface: 0,
+    enum: 0,
+    import: 0,
+    export: 0,
+    method: 0,
+    property: 0,
+    decorator: 0,
+    module: 0
+  };
+  graph.forEachNode((node, attrs) => {
+    symbolCounts[attrs.kind]++;
+  });
+  const total = graph.order;
+  const rows = [];
+  for (const [kind, count] of Object.entries(symbolCounts)) {
+    if (count > 0) {
+      rows.push([kind, formatNumber(count), formatPercent(count, total)]);
+    }
+  }
+  rows.sort((a, b) => parseInt(b[1].replace(/,/g, "")) - parseInt(a[1].replace(/,/g, "")));
+  return table(["Symbol Kind", "Count", "Percentage"], rows);
+}
+function generateDesignPatterns(graph) {
+  const patterns = {
+    service: 0,
+    factory: 0,
+    hook: 0,
+    middleware: 0,
+    controller: 0,
+    repository: 0,
+    handler: 0
+  };
+  graph.forEachNode((node, attrs) => {
+    const name = attrs.name;
+    const file = attrs.filePath.toLowerCase();
+    if (attrs.kind === "class" && name.endsWith("Service")) {
+      patterns.service++;
+    }
+    if (attrs.kind === "function" && name.startsWith("create")) {
+      patterns.factory++;
+    }
+    if (attrs.kind === "function" && name.startsWith("use") && name.length > 3) {
+      patterns.hook++;
+    }
+    if (file.includes("middleware")) {
+      patterns.middleware++;
+    }
+    if ((attrs.kind === "class" || attrs.kind === "function") && name.endsWith("Controller")) {
+      patterns.controller++;
+    }
+    if ((attrs.kind === "class" || attrs.kind === "function") && name.endsWith("Repository")) {
+      patterns.repository++;
+    }
+    if ((attrs.kind === "class" || attrs.kind === "function") && name.endsWith("Handler")) {
+      patterns.handler++;
+    }
+  });
+  const detected = Object.entries(patterns).filter(([, count]) => count > 0);
+  if (detected.length === 0) {
+    return "No common design patterns detected.\n\n";
+  }
+  let output = "";
+  for (const [pattern, count] of detected) {
+    const description = getPatternDescription(pattern);
+    output += `- **${capitalizeFirst(pattern)} Pattern:** ${count} occurrences \u2014 ${description}
+`;
+  }
+  output += "\n";
+  return output;
+}
+function getPatternDescription(pattern) {
+  switch (pattern) {
+    case "service":
+      return 'Classes ending in "Service"';
+    case "factory":
+      return 'Functions starting with "create"';
+    case "hook":
+      return 'Functions starting with "use" (React hooks)';
+    case "middleware":
+      return "Files in middleware directories";
+    case "controller":
+      return "Controllers for handling requests";
+    case "repository":
+      return "Data access layer pattern";
+    case "handler":
+      return "Event/request handlers";
+    default:
+      return "";
+  }
+}
+function capitalizeFirst(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+function isCamelCase(name) {
+  return /^[a-z][a-zA-Z0-9]*$/.test(name) && /[A-Z]/.test(name);
+}
+function isPascalCase(name) {
+  return /^[A-Z][a-zA-Z0-9]*$/.test(name);
+}
+function isKebabCase(name) {
+  return /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/.test(name);
+}
+function isSnakeCase(name) {
+  return /^[a-z][a-z0-9]*(_[a-z0-9]+)*$/.test(name);
+}
+function isUpperSnakeCase(name) {
+  return /^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$/.test(name);
+}
+
+// src/docs/dependencies.ts
+function generateDependencies(graph, projectRoot, version) {
+  let output = "";
+  const now = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  const fileCount = getFileCount3(graph);
+  output += timestamp(version, now, fileCount, graph.order);
+  output += header("Dependency Map");
+  output += "Complete dependency mapping showing what connects to what.\n\n";
+  output += header("Module Dependency Matrix", 2);
+  output += generateModuleDependencyMatrix(graph);
+  output += header("High-Impact Symbols", 2);
+  output += generateHighImpactSymbols(graph);
+  output += header("Isolated Files", 2);
+  output += generateIsolatedFiles(graph);
+  output += header("Most Connected File Pairs", 2);
+  output += generateConnectedFilePairs(graph);
+  output += header("Longest Dependency Chains", 2);
+  output += generateDependencyChains(graph);
+  output += header("Circular Dependencies (Detailed)", 2);
+  output += generateCircularDependenciesDetailed(graph);
+  return output;
+}
+function getFileCount3(graph) {
+  const files = /* @__PURE__ */ new Set();
+  graph.forEachNode((node, attrs) => {
+    files.add(attrs.filePath);
+  });
+  return files.size;
+}
+function generateModuleDependencyMatrix(graph) {
+  const dirEdges = /* @__PURE__ */ new Map();
+  const allDirs = /* @__PURE__ */ new Set();
+  graph.forEachEdge((edge, attrs, source, target) => {
+    const sourceAttrs = graph.getNodeAttributes(source);
+    const targetAttrs = graph.getNodeAttributes(target);
+    if (sourceAttrs.filePath !== targetAttrs.filePath) {
+      const sourceDir = getTopLevelDir(sourceAttrs.filePath);
+      const targetDir = getTopLevelDir(targetAttrs.filePath);
+      if (sourceDir && targetDir && sourceDir !== targetDir) {
+        allDirs.add(sourceDir);
+        allDirs.add(targetDir);
+        if (!dirEdges.has(sourceDir)) {
+          dirEdges.set(sourceDir, /* @__PURE__ */ new Map());
+        }
+        const targetMap = dirEdges.get(sourceDir);
+        targetMap.set(targetDir, (targetMap.get(targetDir) || 0) + 1);
+      }
+    }
+  });
+  if (allDirs.size === 0) {
+    return "No module structure detected (flat or single-directory project).\n\n";
+  }
+  const dirTotalEdges = /* @__PURE__ */ new Map();
+  for (const [sourceDir, targets] of dirEdges.entries()) {
+    let total = 0;
+    for (const count of targets.values()) {
+      total += count;
+    }
+    dirTotalEdges.set(sourceDir, total);
+  }
+  const sortedDirs = Array.from(allDirs).sort((a, b) => (dirTotalEdges.get(b) || 0) - (dirTotalEdges.get(a) || 0)).slice(0, 15);
+  if (sortedDirs.length === 0) {
+    return "No cross-module dependencies detected.\n\n";
+  }
+  const headers = ["From / To", ...sortedDirs];
+  const rows = [];
+  for (const sourceDir of sortedDirs) {
+    const row = [sourceDir];
+    for (const targetDir of sortedDirs) {
+      if (sourceDir === targetDir) {
+        row.push("-");
+      } else {
+        const count = dirEdges.get(sourceDir)?.get(targetDir) || 0;
+        row.push(count > 0 ? count.toString() : "\u2717");
+      }
+    }
+    rows.push(row);
+  }
+  return table(headers, rows);
+}
+function getTopLevelDir(filePath) {
+  const parts = filePath.split("/");
+  if (parts.length < 2) {
+    return null;
+  }
+  if (parts[0] === "src" && parts.length >= 3) {
+    return `${parts[0]}/${parts[1]}`;
+  }
+  if (parts[0] === "src" && parts.length === 2) {
+    return null;
+  }
+  const firstDir = parts[0];
+  if (firstDir.includes("test") || firstDir.includes("fixture") || firstDir.includes("example") || firstDir.includes("__tests__") || firstDir === "node_modules" || firstDir === "dist" || firstDir === "build") {
+    return null;
+  }
+  if (parts.length >= 2) {
+    return `${parts[0]}/${parts[1]}`;
+  }
+  return parts[0];
+}
+function generateHighImpactSymbols(graph) {
+  const symbolImpact = [];
+  graph.forEachNode((node, attrs) => {
+    const inDegree = graph.inDegree(node);
+    if (inDegree > 0 && attrs.name !== "__file__") {
+      symbolImpact.push({
+        name: attrs.name,
+        filePath: attrs.filePath,
+        kind: attrs.kind,
+        dependentCount: inDegree
+      });
+    }
+  });
+  symbolImpact.sort((a, b) => b.dependentCount - a.dependentCount);
+  const top = symbolImpact.slice(0, 15);
+  if (top.length === 0) {
+    return "No high-impact symbols detected.\n\n";
+  }
+  const headers = ["Symbol", "File", "Kind", "Dependents", "Impact"];
+  const rows = top.map((s) => {
+    const impact = s.dependentCount >= 20 ? `${impactEmoji(s.dependentCount)} Critical` : s.dependentCount >= 10 ? `${impactEmoji(s.dependentCount)} High` : s.dependentCount >= 5 ? `${impactEmoji(s.dependentCount)} Medium` : `${impactEmoji(s.dependentCount)} Low`;
+    return [
+      `\`${s.name}\``,
+      `\`${s.filePath}\``,
+      s.kind,
+      formatNumber(s.dependentCount),
+      impact
+    ];
+  });
+  return table(headers, rows);
+}
+function generateIsolatedFiles(graph) {
+  const fileConnections = /* @__PURE__ */ new Map();
+  graph.forEachNode((node, attrs) => {
+    if (!fileConnections.has(attrs.filePath)) {
+      fileConnections.set(attrs.filePath, { incoming: 0, outgoing: 0 });
+    }
+  });
+  graph.forEachEdge((edge, attrs, source, target) => {
+    const sourceAttrs = graph.getNodeAttributes(source);
+    const targetAttrs = graph.getNodeAttributes(target);
+    if (sourceAttrs.filePath !== targetAttrs.filePath) {
+      const sourceConn = fileConnections.get(sourceAttrs.filePath);
+      const targetConn = fileConnections.get(targetAttrs.filePath);
+      if (sourceConn) sourceConn.outgoing++;
+      if (targetConn) targetConn.incoming++;
+    }
+  });
+  const isolated = [];
+  for (const [file, conn] of fileConnections.entries()) {
+    if (conn.incoming === 0) {
+      isolated.push(file);
+    }
+  }
+  if (isolated.length === 0) {
+    return "No isolated files detected. All files are connected.\n\n";
+  }
+  let output = `Found ${isolated.length} file${isolated.length === 1 ? "" : "s"} with no incoming dependencies:
+
+`;
+  if (isolated.length <= 20) {
+    output += unorderedList(isolated.map((f) => `\`${f}\``));
+  } else {
+    output += unorderedList(isolated.slice(0, 20).map((f) => `\`${f}\``));
+    output += `... and ${isolated.length - 20} more.
+
+`;
+  }
+  output += "These files could be entry points, standalone scripts, or dead code.\n\n";
+  return output;
+}
+function generateConnectedFilePairs(graph) {
+  const filePairEdges = /* @__PURE__ */ new Map();
+  graph.forEachEdge((edge, attrs, source, target) => {
+    const sourceAttrs = graph.getNodeAttributes(source);
+    const targetAttrs = graph.getNodeAttributes(target);
+    if (sourceAttrs.filePath !== targetAttrs.filePath) {
+      const pair = [sourceAttrs.filePath, targetAttrs.filePath].sort().join(" <-> ");
+      filePairEdges.set(pair, (filePairEdges.get(pair) || 0) + 1);
+    }
+  });
+  const pairs = Array.from(filePairEdges.entries()).sort((a, b) => b[1] - a[1]).slice(0, 10);
+  if (pairs.length === 0) {
+    return "No cross-file dependencies detected.\n\n";
+  }
+  const headers = ["File 1", "File 2", "Edges"];
+  const rows = pairs.map(([pair, count]) => {
+    const [file1, file2] = pair.split(" <-> ");
+    return [`\`${file1}\``, `\`${file2}\``, formatNumber(count)];
+  });
+  return table(headers, rows);
+}
+function generateDependencyChains(graph) {
+  const chains = findLongestPaths(graph, 5);
+  if (chains.length === 0) {
+    return "No significant dependency chains detected.\n\n";
+  }
+  let output = "";
+  for (let i = 0; i < chains.length; i++) {
+    const chain = chains[i];
+    output += `**Chain ${i + 1}** (${chain.length} files):
+
+`;
+    output += codeBlock(chain.join(" \u2192\n"), "");
+  }
+  return output;
+}
+function findLongestPaths(graph, limit) {
+  const fileGraph = /* @__PURE__ */ new Map();
+  const fileInDegree = /* @__PURE__ */ new Map();
+  graph.forEachEdge((edge, attrs, source, target) => {
+    const sourceFile = graph.getNodeAttributes(source).filePath;
+    const targetFile = graph.getNodeAttributes(target).filePath;
+    if (sourceFile !== targetFile) {
+      if (!fileGraph.has(sourceFile)) {
+        fileGraph.set(sourceFile, /* @__PURE__ */ new Set());
+      }
+      fileGraph.get(sourceFile).add(targetFile);
+      fileInDegree.set(targetFile, (fileInDegree.get(targetFile) || 0) + 1);
+      if (!fileInDegree.has(sourceFile)) {
+        fileInDegree.set(sourceFile, 0);
+      }
+    }
+  });
+  const roots = [];
+  for (const [file, inDegree] of fileInDegree.entries()) {
+    if (inDegree === 0) {
+      roots.push(file);
+    }
+  }
+  const allPaths = [];
+  const visited = /* @__PURE__ */ new Set();
+  function dfs(file, path) {
+    visited.add(file);
+    path.push(file);
+    const neighbors = fileGraph.get(file);
+    if (!neighbors || neighbors.size === 0) {
+      allPaths.push([...path]);
+    } else {
+      for (const neighbor of neighbors) {
+        if (!visited.has(neighbor)) {
+          dfs(neighbor, path);
+        }
+      }
+    }
+    path.pop();
+    visited.delete(file);
+  }
+  for (const root of roots.slice(0, 10)) {
+    dfs(root, []);
+  }
+  allPaths.sort((a, b) => b.length - a.length);
+  return allPaths.slice(0, limit);
+}
+function generateCircularDependenciesDetailed(graph) {
+  const cycles = detectCyclesDetailed(graph);
+  if (cycles.length === 0) {
+    return "\u2705 No circular dependencies detected.\n\n";
+  }
+  let output = `\u26A0\uFE0F Found ${cycles.length} circular ${cycles.length === 1 ? "dependency" : "dependencies"}:
+
+`;
+  for (let i = 0; i < Math.min(cycles.length, 5); i++) {
+    const cycle = cycles[i];
+    output += `**Cycle ${i + 1}:**
+
+`;
+    output += codeBlock(cycle.files.join(" \u2192\n") + " \u2192 " + cycle.files[0], "");
+    if (cycle.symbols.length > 0) {
+      output += "**Symbols involved:**\n\n";
+      output += unorderedList(cycle.symbols.map((s) => `\`${s.name}\` (${s.kind}) at \`${s.filePath}:${s.line}\``));
+    }
+    output += `**Suggested fix:** ${cycle.suggestion}
+
+`;
+  }
+  if (cycles.length > 5) {
+    output += `... and ${cycles.length - 5} more cycles.
+
+`;
+  }
+  return output;
+}
+function detectCyclesDetailed(graph) {
+  const cycles = [];
+  const visited = /* @__PURE__ */ new Set();
+  const recStack = /* @__PURE__ */ new Set();
+  const pathStack = [];
+  const fileGraph = /* @__PURE__ */ new Map();
+  graph.forEachEdge((edge, attrs, source, target) => {
+    const sourceAttrs = graph.getNodeAttributes(source);
+    const targetAttrs = graph.getNodeAttributes(target);
+    const sourceFile = sourceAttrs.filePath;
+    const targetFile = targetAttrs.filePath;
+    if (sourceFile !== targetFile) {
+      if (!fileGraph.has(sourceFile)) {
+        fileGraph.set(sourceFile, /* @__PURE__ */ new Map());
+      }
+      const targetMap = fileGraph.get(sourceFile);
+      if (!targetMap.has(targetFile)) {
+        targetMap.set(targetFile, []);
+      }
+      targetMap.get(targetFile).push({
+        symbolName: targetAttrs.name,
+        symbolKind: targetAttrs.kind,
+        line: attrs.line || sourceAttrs.startLine
+      });
+    }
+  });
+  function dfs(file) {
+    visited.add(file);
+    recStack.add(file);
+    pathStack.push(file);
+    const neighbors = fileGraph.get(file);
+    if (neighbors) {
+      for (const [neighbor, symbols] of neighbors.entries()) {
+        if (!visited.has(neighbor)) {
+          if (dfs(neighbor)) {
+            return true;
+          }
+        } else if (recStack.has(neighbor)) {
+          const cycleStart = pathStack.indexOf(neighbor);
+          const cyclePath = pathStack.slice(cycleStart);
+          const cycleSymbols = [];
+          for (let i = 0; i < cyclePath.length; i++) {
+            const currentFile = cyclePath[i];
+            const nextFile = cyclePath[(i + 1) % cyclePath.length];
+            const edgeSymbols = fileGraph.get(currentFile)?.get(nextFile) || [];
+            for (const sym of edgeSymbols.slice(0, 3)) {
+              cycleSymbols.push({
+                name: sym.symbolName,
+                kind: sym.symbolKind,
+                filePath: currentFile,
+                line: sym.line
+              });
+            }
+          }
+          cycles.push({
+            files: cyclePath,
+            symbols: cycleSymbols,
+            suggestion: "Extract shared types/interfaces to a common file"
+          });
+          return true;
+        }
+      }
+    }
+    recStack.delete(file);
+    pathStack.pop();
+    return false;
+  }
+  for (const file of fileGraph.keys()) {
+    if (!visited.has(file)) {
+      dfs(file);
+      recStack.clear();
+      pathStack.length = 0;
+    }
+  }
+  return cycles;
+}
+
+// src/docs/onboarding.ts
+import { dirname as dirname7 } from "path";
+function generateOnboarding(graph, projectRoot, version) {
+  let output = "";
+  const now = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  const fileCount = getFileCount4(graph);
+  output += timestamp(version, now, fileCount, graph.order);
+  output += header("Onboarding Guide");
+  output += "A guide for developers new to this codebase.\n\n";
+  output += header("Quick Orientation", 2);
+  output += generateQuickOrientation(graph);
+  output += header("Where to Start Reading", 2);
+  output += generateReadingOrder(graph);
+  output += header("Module Map", 2);
+  output += generateModuleMap(graph);
+  output += header("Key Concepts", 2);
+  output += generateKeyConcepts(graph);
+  output += header("High-Impact Files", 2);
+  output += generateHighImpactWarning(graph);
+  output += header("Using Depwire with This Project", 2);
+  output += generateDepwireUsage(projectRoot);
+  return output;
+}
+function getFileCount4(graph) {
+  const files = /* @__PURE__ */ new Set();
+  graph.forEachNode((node, attrs) => {
+    files.add(attrs.filePath);
+  });
+  return files.size;
+}
+function getLanguageStats2(graph) {
+  const stats = {};
+  const files = /* @__PURE__ */ new Set();
+  graph.forEachNode((node, attrs) => {
+    if (!files.has(attrs.filePath)) {
+      files.add(attrs.filePath);
+      const ext = attrs.filePath.toLowerCase();
+      let lang;
+      if (ext.endsWith(".ts") || ext.endsWith(".tsx")) {
+        lang = "TypeScript";
+      } else if (ext.endsWith(".py")) {
+        lang = "Python";
+      } else if (ext.endsWith(".js") || ext.endsWith(".jsx") || ext.endsWith(".mjs") || ext.endsWith(".cjs")) {
+        lang = "JavaScript";
+      } else if (ext.endsWith(".go")) {
+        lang = "Go";
+      } else {
+        lang = "Other";
+      }
+      stats[lang] = (stats[lang] || 0) + 1;
+    }
+  });
+  return stats;
+}
+function generateQuickOrientation(graph) {
+  const fileCount = getFileCount4(graph);
+  const languages = getLanguageStats2(graph);
+  const primaryLang = Object.entries(languages).sort((a, b) => b[1] - a[1])[0];
+  const dirs = /* @__PURE__ */ new Set();
+  graph.forEachNode((node, attrs) => {
+    const dir = dirname7(attrs.filePath);
+    if (dir !== ".") {
+      const topLevel = dir.split("/")[0];
+      dirs.add(topLevel);
+    }
+  });
+  const mainAreas = Array.from(dirs).sort().join(", ");
+  let output = "";
+  if (primaryLang) {
+    output += `This is a **${primaryLang[0]}** project with **${fileCount} files** and **${graph.order} symbols**. `;
+  } else {
+    output += `This project has **${fileCount} files** and **${graph.order} symbols**. `;
+  }
+  if (dirs.size > 0) {
+    output += `The main areas are: ${mainAreas}.`;
+  } else {
+    output += "The project has a flat file structure.";
+  }
+  output += "\n\n";
+  return output;
+}
+function generateReadingOrder(graph) {
+  const fileStats = getFileStatsWithDeps(graph);
+  if (fileStats.length === 0) {
+    return "No files to analyze.\n\n";
+  }
+  const foundation = fileStats.filter((f) => f.incomingRefs > 0 && f.incomingRefs >= f.outgoingRefs * 2).sort((a, b) => b.incomingRefs - a.incomingRefs).slice(0, 3);
+  const core = fileStats.filter((f) => !foundation.includes(f)).filter((f) => f.incomingRefs > 0 && f.outgoingRefs > 0).filter((f) => {
+    const ratio = f.incomingRefs / (f.outgoingRefs + 0.1);
+    return ratio > 0.3 && ratio < 3;
+  }).sort((a, b) => b.incomingRefs + b.outgoingRefs - (a.incomingRefs + a.outgoingRefs)).slice(0, 5);
+  const orchestration = fileStats.filter((f) => !foundation.includes(f) && !core.includes(f)).filter((f) => f.outgoingRefs > 0 && f.outgoingRefs >= f.incomingRefs * 2).sort((a, b) => b.outgoingRefs - a.outgoingRefs).slice(0, 3);
+  if (foundation.length === 0 && core.length === 0 && orchestration.length === 0) {
+    return "No clear reading order detected. Start with any file.\n\n";
+  }
+  let output = "Recommended reading order for understanding the codebase:\n\n";
+  if (foundation.length > 0) {
+    output += "**Foundation** (start here \u2014 these are building blocks):\n\n";
+    output += orderedList(foundation.map((f) => `${code(f.filePath)} \u2014 Shared foundation (${f.incomingRefs} dependents)`));
+  }
+  if (core.length > 0) {
+    output += "**Core Logic** (read these next):\n\n";
+    output += orderedList(core.map((f) => `${code(f.filePath)} \u2014 Core logic (${f.symbolCount} symbols)`));
+  }
+  if (orchestration.length > 0) {
+    output += "**Entry Points** (read these last to see how it all fits together):\n\n";
+    output += orderedList(orchestration.map((f) => `${code(f.filePath)} \u2014 Entry point (imports from ${f.outgoingRefs} files)`));
+  }
+  return output;
+}
+function getFileStatsWithDeps(graph) {
+  const fileMap = /* @__PURE__ */ new Map();
+  graph.forEachNode((node, attrs) => {
+    if (!fileMap.has(attrs.filePath)) {
+      fileMap.set(attrs.filePath, {
+        symbolCount: 0,
+        incomingRefs: /* @__PURE__ */ new Set(),
+        outgoingRefs: /* @__PURE__ */ new Set()
+      });
+    }
+    fileMap.get(attrs.filePath).symbolCount++;
+  });
+  graph.forEachEdge((edge, attrs, source, target) => {
+    const sourceAttrs = graph.getNodeAttributes(source);
+    const targetAttrs = graph.getNodeAttributes(target);
+    if (sourceAttrs.filePath !== targetAttrs.filePath) {
+      const sourceFile = fileMap.get(sourceAttrs.filePath);
+      const targetFile = fileMap.get(targetAttrs.filePath);
+      if (sourceFile) {
+        sourceFile.outgoingRefs.add(targetAttrs.filePath);
+      }
+      if (targetFile) {
+        targetFile.incomingRefs.add(sourceAttrs.filePath);
+      }
+    }
+  });
+  const result = [];
+  for (const [filePath, data] of fileMap.entries()) {
+    result.push({
+      filePath,
+      symbolCount: data.symbolCount,
+      incomingRefs: data.incomingRefs.size,
+      outgoingRefs: data.outgoingRefs.size
     });
+  }
+  return result;
+}
+function generateModuleMap(graph) {
+  const dirStats = getDirectoryStats2(graph);
+  if (dirStats.length === 0) {
+    return "Flat file structure (no subdirectories).\n\n";
+  }
+  let output = "";
+  for (const dir of dirStats) {
+    const description = inferDirectoryDescription(dir, graph);
+    output += `- ${code(dir.name)} \u2014 ${description}
+`;
+  }
+  output += "\n";
+  return output;
+}
+function getDirectoryStats2(graph) {
+  const dirMap = /* @__PURE__ */ new Map();
+  graph.forEachNode((node, attrs) => {
+    const dir = dirname7(attrs.filePath);
+    if (dir === ".") return;
+    if (!dirMap.has(dir)) {
+      dirMap.set(dir, {
+        name: dir,
+        fileCount: 0,
+        symbolCount: 0,
+        inboundEdges: 0,
+        outboundEdges: 0
+      });
+    }
+    dirMap.get(dir).symbolCount++;
   });
-  const url = `http://127.0.0.1:${availablePort}`;
-  return { server, url, alreadyRunning: false };
+  const filesPerDir = /* @__PURE__ */ new Map();
+  graph.forEachNode((node, attrs) => {
+    const dir = dirname7(attrs.filePath);
+    if (!filesPerDir.has(dir)) {
+      filesPerDir.set(dir, /* @__PURE__ */ new Set());
+    }
+    filesPerDir.get(dir).add(attrs.filePath);
+  });
+  filesPerDir.forEach((files, dir) => {
+    if (dirMap.has(dir)) {
+      dirMap.get(dir).fileCount = files.size;
+    }
+  });
+  const dirEdges = /* @__PURE__ */ new Map();
+  graph.forEachEdge((edge, attrs, source, target) => {
+    const sourceAttrs = graph.getNodeAttributes(source);
+    const targetAttrs = graph.getNodeAttributes(target);
+    const sourceDir = dirname7(sourceAttrs.filePath);
+    const targetDir = dirname7(targetAttrs.filePath);
+    if (sourceDir !== targetDir) {
+      if (!dirEdges.has(sourceDir)) {
+        dirEdges.set(sourceDir, { in: 0, out: 0 });
+      }
+      if (!dirEdges.has(targetDir)) {
+        dirEdges.set(targetDir, { in: 0, out: 0 });
+      }
+      dirEdges.get(sourceDir).out++;
+      dirEdges.get(targetDir).in++;
+    }
+  });
+  dirEdges.forEach((edges, dir) => {
+    if (dirMap.has(dir)) {
+      const stat = dirMap.get(dir);
+      stat.inboundEdges = edges.in;
+      stat.outboundEdges = edges.out;
+    }
+  });
+  return Array.from(dirMap.values()).sort((a, b) => a.name.localeCompare(b.name));
 }
-
-// src/mcp/state.ts
-function createEmptyState() {
-  return {
-    graph: null,
-    projectRoot: null,
-    projectName: null,
-    watcher: null
-  };
+function inferDirectoryDescription(dir, graph) {
+  const name = dir.name.toLowerCase();
+  if (name.includes("types") || name.includes("interfaces")) {
+    return "Type definitions and interfaces";
+  }
+  if (name.includes("utils") || name.includes("helpers")) {
+    return "Utility functions and helpers";
+  }
+  if (name.includes("services")) {
+    return "Business logic and services";
+  }
+  if (name.includes("components")) {
+    return "UI components";
+  }
+  if (name.includes("api") || name.includes("routes")) {
+    return "API routes and endpoints";
+  }
+  if (name.includes("models") || name.includes("entities")) {
+    return "Data models and entities";
+  }
+  if (name.includes("config")) {
+    return "Configuration files";
+  }
+  if (name.includes("test")) {
+    return "Test files";
+  }
+  const totalEdges = dir.inboundEdges + dir.outboundEdges;
+  if (totalEdges === 0) {
+    return "Isolated module";
+  }
+  const inboundRatio = dir.inboundEdges / totalEdges;
+  if (inboundRatio > 0.7) {
+    return "Shared foundation \u2014 heavily imported by other modules";
+  } else if (inboundRatio < 0.3) {
+    return "Orchestration \u2014 imports from many other modules";
+  } else {
+    return `Core logic \u2014 ${dir.fileCount} files, ${dir.symbolCount} symbols`;
+  }
 }
-function isProjectLoaded(state) {
-  return state.graph !== null && state.projectRoot !== null;
+function generateKeyConcepts(graph) {
+  const clusters = detectClusters(graph);
+  if (clusters.length === 0) {
+    return "No distinct concept clusters detected.\n\n";
+  }
+  let output = "The codebase is organized around these key concepts:\n\n";
+  for (const cluster of clusters.slice(0, 5)) {
+    output += `- **${cluster.name}** \u2014 ${cluster.files.length} tightly-connected files: `;
+    output += cluster.files.slice(0, 3).map((f) => code(f)).join(", ");
+    if (cluster.files.length > 3) {
+      output += `, and ${cluster.files.length - 3} more`;
+    }
+    output += "\n";
+  }
+  output += "\n";
+  return output;
 }
-
-// src/graph/updater.ts
-import { join as join8 } from "path";
-function removeFileFromGraph(graph, filePath) {
-  const nodesToRemove = [];
+function detectClusters(graph) {
+  const dirFiles = /* @__PURE__ */ new Map();
+  const fileEdges = /* @__PURE__ */ new Map();
   graph.forEachNode((node, attrs) => {
-    if (attrs.filePath === filePath) {
-      nodesToRemove.push(node);
+    const dir = dirname7(attrs.filePath);
+    if (!dirFiles.has(dir)) {
+      dirFiles.set(dir, /* @__PURE__ */ new Set());
     }
+    dirFiles.get(dir).add(attrs.filePath);
   });
-  nodesToRemove.forEach((node) => {
-    try {
-      graph.dropNode(node);
-    } catch (error) {
+  graph.forEachEdge((edge, attrs, source, target) => {
+    const sourceFile = graph.getNodeAttributes(source).filePath;
+    const targetFile = graph.getNodeAttributes(target).filePath;
+    if (sourceFile !== targetFile) {
+      if (!fileEdges.has(sourceFile)) {
+        fileEdges.set(sourceFile, /* @__PURE__ */ new Set());
+      }
+      fileEdges.get(sourceFile).add(targetFile);
     }
   });
-}
-function addFileToGraph(graph, parsedFile) {
-  for (const symbol of parsedFile.symbols) {
-    const nodeId = `${parsedFile.filePath}::${symbol.name}`;
-    try {
-      graph.addNode(nodeId, {
-        name: symbol.name,
-        kind: symbol.kind,
-        filePath: parsedFile.filePath,
-        startLine: symbol.location.startLine,
-        endLine: symbol.location.endLine,
-        exported: symbol.exported,
-        scope: symbol.scope
+  const clusters = [];
+  for (const [dir, files] of dirFiles.entries()) {
+    if (dir === "." || files.size < 2) continue;
+    const fileArray = Array.from(files);
+    let internalEdgeCount = 0;
+    for (const file of fileArray) {
+      const targets = fileEdges.get(file);
+      if (targets) {
+        for (const target of targets) {
+          if (files.has(target)) {
+            internalEdgeCount++;
+          }
+        }
+      }
+    }
+    if (internalEdgeCount >= 2) {
+      const clusterName = inferClusterName(fileArray);
+      clusters.push({
+        name: clusterName,
+        files: fileArray
       });
-    } catch (error) {
     }
   }
-  for (const edge of parsedFile.edges) {
-    try {
-      graph.mergeEdge(edge.source, edge.target, {
-        kind: edge.kind,
-        sourceFile: edge.sourceFile,
-        targetFile: edge.targetFile
-      });
-    } catch (error) {
+  return clusters.sort((a, b) => b.files.length - a.files.length);
+}
+function inferClusterName(files) {
+  const words = /* @__PURE__ */ new Map();
+  for (const file of files) {
+    const fileName = file.toLowerCase();
+    const parts = fileName.split(/[\/\-\_\.]/).filter((p) => p.length > 3);
+    for (const part of parts) {
+      words.set(part, (words.get(part) || 0) + 1);
+    }
+  }
+  const sortedWords = Array.from(words.entries()).sort((a, b) => b[1] - a[1]);
+  if (sortedWords.length > 0 && sortedWords[0][1] > 1) {
+    return capitalizeFirst2(sortedWords[0][0]);
+  }
+  const commonDir = dirname7(files[0]);
+  if (files.every((f) => dirname7(f) === commonDir)) {
+    return capitalizeFirst2(commonDir.split("/").pop() || "Core");
+  }
+  return "Core";
+}
+function capitalizeFirst2(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+function generateHighImpactWarning(graph) {
+  const highImpactFiles = [];
+  const fileInDegree = /* @__PURE__ */ new Map();
+  graph.forEachEdge((edge, attrs, source, target) => {
+    const sourceFile = graph.getNodeAttributes(source).filePath;
+    const targetFile = graph.getNodeAttributes(target).filePath;
+    if (sourceFile !== targetFile) {
+      fileInDegree.set(targetFile, (fileInDegree.get(targetFile) || 0) + 1);
+    }
+  });
+  for (const [file, count] of fileInDegree.entries()) {
+    if (count >= 5) {
+      highImpactFiles.push({ file, dependents: count });
     }
   }
+  highImpactFiles.sort((a, b) => b.dependents - a.dependents);
+  if (highImpactFiles.length === 0) {
+    return "No high-impact files detected. Changes should be relatively isolated.\n\n";
+  }
+  let output = "\u26A0\uFE0F **Before modifying these files, check the blast radius:**\n\n";
+  const topFiles = highImpactFiles.slice(0, 5);
+  for (const { file, dependents } of topFiles) {
+    output += `- ${code(file)} \u2014 ${dependents} dependent files (run \`depwire impact_analysis ${file}\`)
+`;
+  }
+  output += "\n";
+  return output;
 }
-async function updateFileInGraph(graph, projectRoot, relativeFilePath) {
-  removeFileFromGraph(graph, relativeFilePath);
-  const absolutePath = join8(projectRoot, relativeFilePath);
+function generateDepwireUsage(projectRoot) {
+  let output = "Use Depwire to explore this codebase:\n\n";
+  output += "**Visualize the dependency graph:**\n\n";
+  output += "```bash\n";
+  output += "depwire viz .\n";
+  output += "```\n\n";
+  output += "**Connect to AI coding tools (MCP):**\n\n";
+  output += "```bash\n";
+  output += "depwire mcp .\n";
+  output += "```\n\n";
+  output += "**Analyze impact of changes:**\n\n";
+  output += "```bash\n";
+  output += "depwire query . <symbol-name>\n";
+  output += "```\n\n";
+  output += "**Update documentation:**\n\n";
+  output += "```bash\n";
+  output += "depwire docs . --update\n";
+  output += "```\n\n";
+  return output;
+}
+
+// src/docs/metadata.ts
+import { existsSync as existsSync5, readFileSync as readFileSync4, writeFileSync } from "fs";
+import { join as join9 } from "path";
+function loadMetadata(outputDir) {
+  const metadataPath = join9(outputDir, "metadata.json");
+  if (!existsSync5(metadataPath)) {
+    return null;
+  }
   try {
-    const parsedFile = parseTypeScriptFile(absolutePath, relativeFilePath);
-    addFileToGraph(graph, parsedFile);
-  } catch (error) {
-    console.error(`Failed to parse file ${relativeFilePath}:`, error);
+    const content = readFileSync4(metadataPath, "utf-8");
+    return JSON.parse(content);
+  } catch (err) {
+    console.error("Failed to load metadata:", err);
+    return null;
+  }
+}
+function saveMetadata(outputDir, metadata) {
+  const metadataPath = join9(outputDir, "metadata.json");
+  writeFileSync(metadataPath, JSON.stringify(metadata, null, 2), "utf-8");
+}
+function createMetadata(version, projectPath, fileCount, symbolCount, edgeCount, docTypes) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const documents = {};
+  for (const docType of docTypes) {
+    const fileName = docType === "architecture" ? "ARCHITECTURE.md" : docType === "conventions" ? "CONVENTIONS.md" : docType === "dependencies" ? "DEPENDENCIES.md" : docType === "onboarding" ? "ONBOARDING.md" : `${docType.toUpperCase()}.md`;
+    documents[docType] = {
+      generated_at: now,
+      file: fileName
+    };
+  }
+  return {
+    version,
+    generated_at: now,
+    project_path: projectPath,
+    file_count: fileCount,
+    symbol_count: symbolCount,
+    edge_count: edgeCount,
+    documents
+  };
+}
+function updateMetadata(existing, docTypes, fileCount, symbolCount, edgeCount) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  for (const docType of docTypes) {
+    if (existing.documents[docType]) {
+      existing.documents[docType].generated_at = now;
+    }
+  }
+  existing.file_count = fileCount;
+  existing.symbol_count = symbolCount;
+  existing.edge_count = edgeCount;
+  existing.generated_at = now;
+  return existing;
+}
+
+// src/docs/generator.ts
+async function generateDocs(graph, projectRoot, version, parseTime, options) {
+  const startTime = Date.now();
+  const generated = [];
+  const errors = [];
+  try {
+    if (!existsSync6(options.outputDir)) {
+      mkdirSync(options.outputDir, { recursive: true });
+      if (options.verbose) {
+        console.log(`Created output directory: ${options.outputDir}`);
+      }
+    }
+    let docsToGenerate = options.include;
+    if (options.update && options.only) {
+      docsToGenerate = options.only;
+    }
+    if (docsToGenerate.includes("all")) {
+      docsToGenerate = ["architecture", "conventions", "dependencies", "onboarding"];
+    }
+    let metadata = null;
+    if (options.update) {
+      metadata = loadMetadata(options.outputDir);
+    }
+    const fileCount = getFileCount5(graph);
+    const symbolCount = graph.order;
+    const edgeCount = graph.size;
+    if (options.format === "markdown") {
+      if (docsToGenerate.includes("architecture")) {
+        try {
+          if (options.verbose) console.log("Generating ARCHITECTURE.md...");
+          const content = generateArchitecture(graph, projectRoot, version, parseTime);
+          const filePath = join10(options.outputDir, "ARCHITECTURE.md");
+          writeFileSync2(filePath, content, "utf-8");
+          generated.push("ARCHITECTURE.md");
+        } catch (err) {
+          errors.push(`Failed to generate ARCHITECTURE.md: ${err}`);
+        }
+      }
+      if (docsToGenerate.includes("conventions")) {
+        try {
+          if (options.verbose) console.log("Generating CONVENTIONS.md...");
+          const content = generateConventions(graph, projectRoot, version);
+          const filePath = join10(options.outputDir, "CONVENTIONS.md");
+          writeFileSync2(filePath, content, "utf-8");
+          generated.push("CONVENTIONS.md");
+        } catch (err) {
+          errors.push(`Failed to generate CONVENTIONS.md: ${err}`);
+        }
+      }
+      if (docsToGenerate.includes("dependencies")) {
+        try {
+          if (options.verbose) console.log("Generating DEPENDENCIES.md...");
+          const content = generateDependencies(graph, projectRoot, version);
+          const filePath = join10(options.outputDir, "DEPENDENCIES.md");
+          writeFileSync2(filePath, content, "utf-8");
+          generated.push("DEPENDENCIES.md");
+        } catch (err) {
+          errors.push(`Failed to generate DEPENDENCIES.md: ${err}`);
+        }
+      }
+      if (docsToGenerate.includes("onboarding")) {
+        try {
+          if (options.verbose) console.log("Generating ONBOARDING.md...");
+          const content = generateOnboarding(graph, projectRoot, version);
+          const filePath = join10(options.outputDir, "ONBOARDING.md");
+          writeFileSync2(filePath, content, "utf-8");
+          generated.push("ONBOARDING.md");
+        } catch (err) {
+          errors.push(`Failed to generate ONBOARDING.md: ${err}`);
+        }
+      }
+    } else if (options.format === "json") {
+      errors.push("JSON format not yet supported");
+    }
+    if (metadata && options.update) {
+      metadata = updateMetadata(metadata, docsToGenerate, fileCount, symbolCount, edgeCount);
+    } else {
+      metadata = createMetadata(version, projectRoot, fileCount, symbolCount, edgeCount, docsToGenerate);
+    }
+    saveMetadata(options.outputDir, metadata);
+    if (options.verbose) console.log("Saved metadata.json");
+    const totalTime = Date.now() - startTime;
+    return {
+      success: errors.length === 0,
+      generated,
+      errors,
+      stats: options.stats ? {
+        totalTime,
+        filesGenerated: generated.length
+      } : void 0
+    };
+  } catch (err) {
+    return {
+      success: false,
+      generated,
+      errors: [`Fatal error: ${err}`]
+    };
   }
 }
+function getFileCount5(graph) {
+  const files = /* @__PURE__ */ new Set();
+  graph.forEachNode((node, attrs) => {
+    files.add(attrs.filePath);
+  });
+  return files.size;
+}
 
 // src/mcp/server.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/mcp/tools.ts
-import { dirname as dirname6 } from "path";
+import { dirname as dirname8, join as join12 } from "path";
+import { existsSync as existsSync8, readFileSync as readFileSync5 } from "fs";
 
 // src/mcp/connect.ts
 import simpleGit from "simple-git";
-import { existsSync as existsSync5 } from "fs";
-import { join as join9, basename as basename2, resolve as resolve2 } from "path";
+import { existsSync as existsSync7 } from "fs";
+import { join as join11, basename as basename3, resolve as resolve2 } from "path";
 import { tmpdir, homedir } from "os";
 function validateProjectPath(source) {
   const resolved = resolve2(source);
@@ -2594,11 +4358,11 @@ function validateProjectPath(source) {
     "/boot",
     "/proc",
     "/sys",
-    join9(homedir(), ".ssh"),
-    join9(homedir(), ".gnupg"),
-    join9(homedir(), ".aws"),
-    join9(homedir(), ".config"),
-    join9(homedir(), ".env")
+    join11(homedir(), ".ssh"),
+    join11(homedir(), ".gnupg"),
+    join11(homedir(), ".aws"),
+    join11(homedir(), ".config"),
+    join11(homedir(), ".env")
   ];
   for (const blocked of blockedPaths) {
     if (resolved.startsWith(blocked)) {
@@ -2621,11 +4385,11 @@ async function connectToRepo(source, subdirectory, state) {
         };
       }
       projectName = match[1];
-      const reposDir = join9(tmpdir(), "depwire-repos");
-      const cloneDir = join9(reposDir, projectName);
+      const reposDir = join11(tmpdir(), "depwire-repos");
+      const cloneDir = join11(reposDir, projectName);
       console.error(`Connecting to GitHub repo: ${source}`);
       const git = simpleGit();
-      if (existsSync5(cloneDir)) {
+      if (existsSync7(cloneDir)) {
         console.error(`Repo already cloned at ${cloneDir}, pulling latest changes...`);
         try {
           await git.cwd(cloneDir).pull();
@@ -2643,7 +4407,7 @@ async function connectToRepo(source, subdirectory, state) {
           };
         }
       }
-      projectRoot = subdirectory ? join9(cloneDir, subdirectory) : cloneDir;
+      projectRoot = subdirectory ? join11(cloneDir, subdirectory) : cloneDir;
     } else {
       const validation2 = validateProjectPath(source);
       if (!validation2.valid) {
@@ -2652,14 +4416,14 @@ async function connectToRepo(source, subdirectory, state) {
           message: validation2.error
         };
       }
-      if (!existsSync5(source)) {
+      if (!existsSync7(source)) {
         return {
           error: "Directory not found",
           message: `Directory does not exist: ${source}`
         };
       }
-      projectRoot = subdirectory ? join9(source, subdirectory) : source;
-      projectName = basename2(projectRoot);
+      projectRoot = subdirectory ? join11(source, subdirectory) : source;
+      projectName = basename3(projectRoot);
     }
     const validation = validateProjectPath(projectRoot);
     if (!validation.valid) {
@@ -2668,7 +4432,7 @@ async function connectToRepo(source, subdirectory, state) {
         message: validation.error
       };
     }
-    if (!existsSync5(projectRoot)) {
+    if (!existsSync7(projectRoot)) {
       return {
         error: "Project root not found",
         message: `Directory does not exist: ${projectRoot}`
@@ -2793,13 +4557,13 @@ function getToolsList() {
     },
     {
       name: "get_symbol_info",
-      description: "Look up detailed information about a symbol (function, class, variable, type, etc.) by name. Returns file location, type, line numbers, and export status.",
+      description: "Look up detailed information about a symbol (function, class, variable, type, etc.) by name. Pass a symbol name (e.g., 'Router') or a fully qualified ID (e.g., 'src/router.ts::Router') for exact matching. If multiple symbols share the same name, returns all matches for disambiguation.",
       inputSchema: {
         type: "object",
         properties: {
           name: {
             type: "string",
-            description: "The symbol name to look up (e.g., 'UserService', 'handleAuth')"
+            description: "The symbol name to look up (e.g., 'UserService') or full ID (e.g., 'src/services/UserService.ts::UserService')"
           }
         },
         required: ["name"]
@@ -2807,13 +4571,13 @@ function getToolsList() {
     },
     {
       name: "get_dependencies",
-      description: "Get all symbols that a given symbol depends on (what does this symbol use/import/call?).",
+      description: "Get all symbols that a given symbol depends on (what does this symbol use/import/call?). Pass a symbol name (e.g., 'Router') or a fully qualified ID (e.g., 'src/router.ts::Router') for exact matching. If multiple symbols share the same name, returns all matches for disambiguation.",
       inputSchema: {
         type: "object",
         properties: {
           symbol: {
             type: "string",
-            description: "Symbol name or ID to analyze"
+            description: "Symbol name (e.g., 'Router') or full ID (e.g., 'src/router.ts::Router')"
           }
         },
         required: ["symbol"]
@@ -2821,13 +4585,13 @@ function getToolsList() {
     },
     {
       name: "get_dependents",
-      description: "Get all symbols that depend on a given symbol (what uses this symbol?).",
+      description: "Get all symbols that depend on a given symbol (what uses this symbol?). Pass a symbol name (e.g., 'Router') or a fully qualified ID (e.g., 'src/router.ts::Router') for exact matching. If multiple symbols share the same name, returns all matches for disambiguation.",
       inputSchema: {
         type: "object",
         properties: {
           symbol: {
             type: "string",
-            description: "Symbol name or ID to analyze"
+            description: "Symbol name (e.g., 'Router') or full ID (e.g., 'src/router.ts::Router')"
           }
         },
         required: ["symbol"]
@@ -2835,13 +4599,13 @@ function getToolsList() {
     },
     {
       name: "impact_analysis",
-      description: "Analyze what would break if a symbol is changed, renamed, or removed. Shows direct dependents, transitive dependents (chain reaction), and all affected files. Use this before making changes to understand the blast radius.",
+      description: "Analyze what would break if a symbol is changed, renamed, or removed. Shows direct dependents, transitive dependents (chain reaction), and all affected files. Pass a symbol name (e.g., 'Router') or a fully qualified ID (e.g., 'src/router.ts::Router') for exact matching. If multiple symbols share the same name, returns all matches for disambiguation. Use this before making changes to understand the blast radius.",
       inputSchema: {
         type: "object",
         properties: {
           symbol: {
             type: "string",
-            description: "The symbol name or ID to analyze"
+            description: "Symbol name (e.g., 'Router') or full ID (e.g., 'src/router.ts::Router')"
           }
         },
         required: ["symbol"]
@@ -2916,6 +4680,32 @@ function getToolsList() {
           }
         }
       }
+    },
+    {
+      name: "get_project_docs",
+      description: "Retrieve auto-generated codebase documentation. Returns architecture overview, code conventions, dependency maps, and onboarding guides. Documentation must be generated first with `depwire docs` command.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          doc_type: {
+            type: "string",
+            description: "Document type to retrieve: 'architecture', 'conventions', 'dependencies', 'onboarding', or 'all' (default: 'all')"
+          }
+        }
+      }
+    },
+    {
+      name: "update_project_docs",
+      description: "Regenerate codebase documentation with the latest changes. If docs don't exist, generates them for the first time. Use this after significant code changes to keep documentation up-to-date.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          doc_type: {
+            type: "string",
+            description: "Document type to update: 'architecture', 'conventions', 'dependencies', 'onboarding', or 'all' (default: 'all')"
+          }
+        }
+      }
     }
   ];
 }
@@ -2942,6 +4732,24 @@ async function handleToolCall(name, args, state) {
       } else {
         result = await handleVisualizeGraph(args.highlight, args.maxFiles, state);
       }
+    } else if (name === "get_project_docs") {
+      if (!isProjectLoaded(state)) {
+        result = {
+          error: "No project loaded",
+          message: "Use connect_repo to connect to a codebase first"
+        };
+      } else {
+        result = await handleGetProjectDocs(args.doc_type || "all", state);
+      }
+    } else if (name === "update_project_docs") {
+      if (!isProjectLoaded(state)) {
+        result = {
+          error: "No project loaded",
+          message: "Use connect_repo to connect to a codebase first"
+        };
+      } else {
+        result = await handleUpdateProjectDocs(args.doc_type || "all", state);
+      }
     } else {
       if (!isProjectLoaded(state)) {
         result = {
@@ -3019,12 +4827,39 @@ async function handleToolCall(name, args, state) {
     };
   }
 }
+function createDisambiguationResponse(matches, queryName) {
+  const suggestion = matches.length > 0 ? matches[0].id : "";
+  return {
+    ambiguous: true,
+    message: `Found ${matches.length} symbols named '${queryName}'. Please specify which one by using the full ID (e.g., '${suggestion}').`,
+    matches: matches.map((m, index) => ({
+      id: m.id,
+      kind: m.kind,
+      filePath: m.filePath,
+      line: m.startLine,
+      dependents: m.dependentCount,
+      hint: index === 0 && m.dependentCount > 0 ? "Most dependents \u2014 likely the one you want" : ""
+    })),
+    suggestion
+  };
+}
 function handleGetSymbolInfo(name, graph) {
-  const matches = searchSymbols(graph, name);
-  const exactMatches = matches.filter((m) => m.name.toLowerCase() === name.toLowerCase());
-  const results = exactMatches.length > 0 ? exactMatches : matches.slice(0, 10);
+  const matches = findSymbols(graph, name);
+  if (matches.length === 0) {
+    const fuzzyMatches = searchSymbols(graph, name).slice(0, 10);
+    return {
+      error: `Symbol '${name}' not found`,
+      suggestion: fuzzyMatches.length > 0 ? `Did you mean: ${fuzzyMatches.map((m) => m.name).join(", ")}?` : "Try using search_symbols to find available symbols",
+      fuzzyMatches: fuzzyMatches.map((m) => ({
+        id: m.id,
+        name: m.name,
+        kind: m.kind,
+        filePath: m.filePath
+      }))
+    };
+  }
   return {
-    matches: results.map((m) => ({
+    matches: matches.map((m) => ({
       id: m.id,
       name: m.name,
       kind: m.kind,
@@ -3032,19 +4867,24 @@ function handleGetSymbolInfo(name, graph) {
       startLine: m.startLine,
       endLine: m.endLine,
       exported: m.exported,
-      scope: m.scope
+      scope: m.scope,
+      dependents: m.dependentCount
     })),
-    count: results.length
+    count: matches.length
   };
 }
 function handleGetDependencies(symbol, graph) {
-  const matches = searchSymbols(graph, symbol);
+  const matches = findSymbols(graph, symbol);
   if (matches.length === 0) {
+    const fuzzyMatches = searchSymbols(graph, symbol).slice(0, 10);
     return {
       error: `Symbol '${symbol}' not found`,
-      suggestion: "Try using search_symbols to find available symbols"
+      suggestion: fuzzyMatches.length > 0 ? `Did you mean: ${fuzzyMatches.map((m) => m.name).join(", ")}?` : "Try using search_symbols to find available symbols"
     };
   }
+  if (matches.length > 1) {
+    return createDisambiguationResponse(matches, symbol);
+  }
   const target = matches[0];
   const deps = getDependencies(graph, target.id);
   const grouped = {};
@@ -3062,19 +4902,23 @@ function handleGetDependencies(symbol, graph) {
   });
   const totalCount = Object.values(grouped).reduce((sum, arr) => sum + arr.length, 0);
   return {
-    symbol: `${target.filePath}::${target.name}`,
+    symbol: target.id,
     dependencies: grouped,
     totalCount
   };
 }
 function handleGetDependents(symbol, graph) {
-  const matches = searchSymbols(graph, symbol);
+  const matches = findSymbols(graph, symbol);
   if (matches.length === 0) {
+    const fuzzyMatches = searchSymbols(graph, symbol).slice(0, 10);
     return {
       error: `Symbol '${symbol}' not found`,
-      suggestion: "Try using search_symbols to find available symbols"
+      suggestion: fuzzyMatches.length > 0 ? `Did you mean: ${fuzzyMatches.map((m) => m.name).join(", ")}?` : "Try using search_symbols to find available symbols"
     };
   }
+  if (matches.length > 1) {
+    return createDisambiguationResponse(matches, symbol);
+  }
   const target = matches[0];
   const deps = getDependents(graph, target.id);
   const grouped = {};
@@ -3092,19 +4936,23 @@ function handleGetDependents(symbol, graph) {
   });
   const totalCount = Object.values(grouped).reduce((sum, arr) => sum + arr.length, 0);
   return {
-    symbol: `${target.filePath}::${target.name}`,
+    symbol: target.id,
     dependents: grouped,
     totalCount
   };
 }
 function handleImpactAnalysis(symbol, graph) {
-  const matches = searchSymbols(graph, symbol);
+  const matches = findSymbols(graph, symbol);
   if (matches.length === 0) {
+    const fuzzyMatches = searchSymbols(graph, symbol).slice(0, 10);
     return {
       error: `Symbol '${symbol}' not found`,
-      suggestion: "Try using search_symbols to find available symbols"
+      suggestion: fuzzyMatches.length > 0 ? `Did you mean: ${fuzzyMatches.map((m) => m.name).join(", ")}?` : "Try using search_symbols to find available symbols"
     };
   }
+  if (matches.length > 1) {
+    return createDisambiguationResponse(matches, symbol);
+  }
   const target = matches[0];
   const impact = getImpact(graph, target.id);
   const directWithKinds = impact.directDependents.map((dep) => {
@@ -3127,6 +4975,7 @@ function handleImpactAnalysis(symbol, graph) {
   const summary = `Changing ${target.name} would directly affect ${impact.directDependents.length} symbol(s) and transitively affect ${transitiveFormatted.length} more, across ${impact.affectedFiles.length} file(s).`;
   return {
     symbol: {
+      id: target.id,
       name: target.name,
       filePath: target.filePath,
       kind: target.kind
@@ -3238,7 +5087,7 @@ function handleGetArchitectureSummary(graph) {
   const dirMap = /* @__PURE__ */ new Map();
   const languageBreakdown = {};
   fileSummary.forEach((f) => {
-    const dir = f.filePath.includes("/") ? dirname6(f.filePath) : ".";
+    const dir = f.filePath.includes("/") ? dirname8(f.filePath) : ".";
     if (!dirMap.has(dir)) {
       dirMap.set(dir, { fileCount: 0, symbolCount: 0 });
     }
@@ -3324,6 +5173,112 @@ The server will keep running until you end the MCP session or press Ctrl+C.`;
     content: [{ type: "text", text: message }]
   };
 }
+async function handleGetProjectDocs(docType, state) {
+  const docsDir = join12(state.projectRoot, ".depwire");
+  if (!existsSync8(docsDir)) {
+    const errorMessage = `Project documentation has not been generated yet.
+
+Run \`depwire docs ${state.projectRoot}\` to generate codebase documentation.
+
+Once generated, this tool will return the requested documentation.
+
+Available document types:
+- architecture: High-level structural overview
+- conventions: Auto-detected coding patterns
+- dependencies: Complete dependency mapping
+- onboarding: Guide for new developers`;
+    return {
+      content: [{ type: "text", text: errorMessage }]
+    };
+  }
+  const metadata = loadMetadata(docsDir);
+  if (!metadata) {
+    return {
+      content: [{ type: "text", text: "Documentation directory exists but metadata is missing. Please regenerate with `depwire docs`." }]
+    };
+  }
+  const docsToReturn = docType === "all" ? ["architecture", "conventions", "dependencies", "onboarding"] : [docType];
+  let output = "";
+  const missing = [];
+  for (const doc of docsToReturn) {
+    if (!metadata.documents[doc]) {
+      missing.push(doc);
+      continue;
+    }
+    const filePath = join12(docsDir, metadata.documents[doc].file);
+    if (!existsSync8(filePath)) {
+      missing.push(doc);
+      continue;
+    }
+    const content = readFileSync5(filePath, "utf-8");
+    if (docsToReturn.length > 1) {
+      output += `
+
+---
+
+# ${doc.toUpperCase()}
+
+`;
+    }
+    output += content;
+  }
+  if (missing.length > 0) {
+    output += `
+
+---
+
+**Note:** The following documents are missing: ${missing.join(", ")}. Run \`depwire docs ${state.projectRoot} --update\` to generate them.`;
+  }
+  return {
+    content: [{ type: "text", text: output }]
+  };
+}
+async function handleUpdateProjectDocs(docType, state) {
+  const startTime = Date.now();
+  const docsDir = join12(state.projectRoot, ".depwire");
+  console.error("Regenerating project documentation...");
+  const parsedFiles = parseProject(state.projectRoot);
+  const graph = buildGraph(parsedFiles);
+  const parseTime = (Date.now() - startTime) / 1e3;
+  state.graph = graph;
+  const packageJsonPath = join12(__dirname, "../../package.json");
+  const packageJson = JSON.parse(readFileSync5(packageJsonPath, "utf-8"));
+  const docsToGenerate = docType === "all" ? ["architecture", "conventions", "dependencies", "onboarding"] : [docType];
+  const docsExist = existsSync8(docsDir);
+  const result = await generateDocs(graph, state.projectRoot, packageJson.version, parseTime, {
+    outputDir: docsDir,
+    format: "markdown",
+    include: docsToGenerate,
+    update: docsExist,
+    only: docsExist ? docsToGenerate : void 0,
+    verbose: false,
+    stats: false
+  });
+  const elapsed = (Date.now() - startTime) / 1e3;
+  if (result.success) {
+    const fileCount = /* @__PURE__ */ new Set();
+    graph.forEachNode((node, attrs) => {
+      fileCount.add(attrs.filePath);
+    });
+    return {
+      status: "success",
+      message: `Updated ${result.generated.join(", ")} (${fileCount.size} files, ${graph.order} symbols, ${elapsed.toFixed(1)}s)`,
+      generated: result.generated,
+      stats: {
+        files: fileCount.size,
+        symbols: graph.order,
+        edges: graph.size,
+        time: elapsed
+      }
+    };
+  } else {
+    return {
+      status: "error",
+      message: `Failed to update documentation: ${result.errors.join(", ")}`,
+      errors: result.errors
+    };
+  }
+}
 
 // src/mcp/server.ts
 async function startMcpServer(state) {
@@ -3369,5 +5324,6 @@ export {
   startVizServer,
   createEmptyState,
   updateFileInGraph,
+  generateDocs,
   startMcpServer
 };