depgraph-core 1.8.0 → 1.9.1

package/depgraph-mcp.js

@@ -3263,8 +3263,8 @@ var require_utils = __commonJS({
       }
       return ind;
     }
-    function removeDotSegments(path7) {
-      let input = path7;
+    function removeDotSegments(path8) {
+      let input = path8;
       const output = [];
       let nextSlash = -1;
       let len = 0;
@@ -3673,8 +3673,8 @@ var require_schemes = __commonJS({
       }
       if (wsComponent.resourceName) {
         const queryIndex = wsComponent.resourceName.indexOf("?");
-        const path7 = queryIndex === -1 ? wsComponent.resourceName : wsComponent.resourceName.slice(0, queryIndex);
-        wsComponent.path = path7 && path7 !== "/" ? path7 : void 0;
+        const path8 = queryIndex === -1 ? wsComponent.resourceName : wsComponent.resourceName.slice(0, queryIndex);
+        wsComponent.path = path8 && path8 !== "/" ? path8 : void 0;
         wsComponent.query = queryIndex === -1 ? void 0 : wsComponent.resourceName.slice(queryIndex + 1);
         wsComponent.resourceName = void 0;
       }
@@ -7677,8 +7677,8 @@ function getErrorMap() {
 
 // node_modules/zod/v3/helpers/parseUtil.js
 var makeIssue = (params) => {
-  const { data, path: path7, errorMaps, issueData } = params;
-  const fullPath = [...path7, ...issueData.path || []];
+  const { data, path: path8, errorMaps, issueData } = params;
+  const fullPath = [...path8, ...issueData.path || []];
   const fullIssue = {
     ...issueData,
     path: fullPath
@@ -7794,11 +7794,11 @@ var errorUtil;
 
 // node_modules/zod/v3/types.js
 var ParseInputLazyPath = class {
-  constructor(parent, value, path7, key) {
+  constructor(parent, value, path8, key) {
     this._cachedPath = [];
     this.parent = parent;
     this.data = value;
-    this._path = path7;
+    this._path = path8;
     this._key = key;
   }
   get path() {
@@ -11435,10 +11435,10 @@ function assignProp(target, prop, value) {
     configurable: true
   });
 }
-function getElementAtPath(obj, path7) {
-  if (!path7)
+function getElementAtPath(obj, path8) {
+  if (!path8)
     return obj;
-  return path7.reduce((acc, key) => acc?.[key], obj);
+  return path8.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject(promisesObj) {
   const keys = Object.keys(promisesObj);
@@ -11758,11 +11758,11 @@ function aborted(x, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues(path7, issues) {
+function prefixIssues(path8, issues) {
   return issues.map((iss) => {
     var _a;
     (_a = iss).path ?? (_a.path = []);
-    iss.path.unshift(path7);
+    iss.path.unshift(path8);
     return iss;
   });
 }
@@ -15173,11 +15173,11 @@ function normalizeObjectSchema(schema) {
   }
   return void 0;
 }
-function getDotPath(path7) {
-  if (path7.length === 0) {
+function getDotPath(path8) {
+  if (path8.length === 0) {
     return "object root";
   }
-  return path7.reduce((acc, seg, index) => {
+  return path8.reduce((acc, seg, index) => {
     if (index === 0) {
       return String(seg);
     }
@@ -21545,7 +21545,8 @@ var SUPPORTED_EXTS = /* @__PURE__ */ new Set([
   ".vue",
   ".svelte",
   ".dart",
-  ".rs"
+  ".rs",
+  ".sql"
 ]);
 var MAX_FILE_SIZE = 3e5;
 var MAX_BFS_DEPTH = 10;
@@ -23592,9 +23593,274 @@ var RustParser = {
 };
 registerParser(RustParser);
 
+// src/languages/sql/helpers.ts
+var NAME_PART = '(?:"(?:[^"\\n]|"")*"|`(?:[^`\\n]|``)*`|\\[(?:[^\\]\\n]|\\]\\])*\\]|[\\w$]+)';
+var QUAL_NAME = `${NAME_PART}(?:\\s*\\.\\s*${NAME_PART})*`;
+var ROUTINE_RECOVERY_RX = new RegExp(
+  `\\bCREATE\\s+(?:OR\\s+(?:REPLACE|ALTER)\\s+)?(?:FUNCTION|PROC(?:EDURE)?)\\s+(?:IF\\s+NOT\\s+EXISTS\\s+)?(${QUAL_NAME})`,
+  "gi"
+);
+function lineOf(text, offset) {
+  return text.slice(0, offset).split("\n").length;
+}
+function normIdent(name) {
+  return name.split(".").map((p) => {
+    const s = p.trim();
+    if (s.length >= 2 && (s[0] === s[s.length - 1] && (s[0] === '"' || s[0] === "`") || s[0] === "[" && s[s.length - 1] === "]")) {
+      return s.slice(1, -1).toLowerCase();
+    }
+    return s.toLowerCase();
+  }).join(".");
+}
+function maskSqlComments(text) {
+  const out = [];
+  let i = 0;
+  const n = text.length;
+  function blank(upto) {
+    for (const ch of text.slice(i, upto)) out.push(ch === "\n" ? "\n" : " ");
+    return upto;
+  }
+  while (i < n) {
+    const c = text[i];
+    if (c === "'") {
+      let j = i + 1;
+      while (j < n && text[j] !== "\n") {
+        if (text[j] === "'") {
+          if (j + 1 < n && text[j + 1] === "'") {
+            j += 2;
+            continue;
+          }
+          j++;
+          break;
+        }
+        j++;
+      }
+      i = blank(j);
+    } else if (c === '"' || c === "`" || c === "[") {
+      const closer = c === "[" ? "]" : c;
+      let j = i + 1;
+      let closed = false;
+      while (j < n && text[j] !== "\n") {
+        if (text[j] === closer) {
+          if (j + 1 < n && text[j + 1] === closer) {
+            j += 2;
+            continue;
+          }
+          j++;
+          closed = true;
+          break;
+        }
+        j++;
+      }
+      const span = text.slice(i, j);
+      if (closed && !span.includes("--") && !span.includes("/*")) {
+        out.push(span);
+        i = j;
+      } else {
+        let eol = text.indexOf("\n", i);
+        if (eol === -1) eol = n;
+        i = blank(eol);
+      }
+    } else if (c === "-" && i + 1 < n && text[i + 1] === "-") {
+      let j = i;
+      while (j < n && text[j] !== "\n") j++;
+      i = blank(j);
+    } else if (c === "/" && i + 1 < n && text[i + 1] === "*") {
+      let depth = 1;
+      let j = i + 2;
+      while (j < n && depth > 0) {
+        if (text[j] === "/" && j + 1 < n && text[j + 1] === "*") {
+          depth++;
+          j += 2;
+        } else if (text[j] === "*" && j + 1 < n && text[j + 1] === "/") {
+          depth--;
+          j += 2;
+        } else j++;
+      }
+      i = blank(j);
+    } else {
+      out.push(c);
+      i++;
+    }
+  }
+  return out.join("");
+}
+var NON_TABLES = /* @__PURE__ */ new Set([
+  "select",
+  "where",
+  "set",
+  "dual",
+  "null",
+  "true",
+  "false",
+  "first",
+  "skip",
+  "rows",
+  "next",
+  "only",
+  "lateral",
+  "values",
+  "inserted",
+  "deleted",
+  "new",
+  "old"
+]);
+function collectCteNames(text) {
+  const ctes = /* @__PURE__ */ new Set();
+  const rx = /\bWITH\s+(?:RECURSIVE\s+)?([\w$]+)\s*(?:\([^()]*\))?\s+AS\s*\(/gi;
+  for (const m of text.matchAll(rx)) ctes.add(normIdent(m[1]));
+  return ctes;
+}
+function collectTableRefs(masked, extraNonTables = /* @__PURE__ */ new Set()) {
+  const skip = /* @__PURE__ */ new Set([...NON_TABLES, ...extraNonTables]);
+  const refs = [];
+  const seen = /* @__PURE__ */ new Set();
+  const rx = new RegExp(
+    `\\b(?:FROM|JOIN|INTO|UPDATE)\\s+(${QUAL_NAME})`,
+    "gi"
+  );
+  for (const m of masked.matchAll(rx)) {
+    const raw = m[1];
+    const key = normIdent(raw);
+    if (skip.has(key) || seen.has(key)) continue;
+    seen.add(key);
+    refs.push({ name: raw, line: lineOf(masked, m.index ?? 0) });
+  }
+  return refs;
+}
+function collectFkRefs(masked) {
+  const refs = [];
+  const seen = /* @__PURE__ */ new Set();
+  const rx = new RegExp(`\\bREFERENCES\\s+(${QUAL_NAME})`, "gi");
+  for (const m of masked.matchAll(rx)) {
+    const raw = m[1];
+    const key = normIdent(raw);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    refs.push({ name: raw, line: lineOf(masked, m.index ?? 0) });
+  }
+  return refs;
+}
+
+// src/languages/sql/patterns.ts
+var sqlEntityPatterns = [
+  {
+    regex: new RegExp(
+      `\\bCREATE\\s+(?:TEMP(?:ORARY)?\\s+)?TABLE\\s+(?:IF\\s+NOT\\s+EXISTS\\s+)?(${QUAL_NAME})`,
+      "gi"
+    ),
+    type: "table"
+  },
+  {
+    regex: new RegExp(
+      `\\bCREATE\\s+(?:OR\\s+(?:REPLACE|ALTER)\\s+)?(?:MATERIALIZED\\s+)?VIEW\\s+(?:IF\\s+NOT\\s+EXISTS\\s+)?(${QUAL_NAME})`,
+      "gi"
+    ),
+    type: "view"
+  },
+  {
+    regex: new RegExp(
+      `\\bCREATE\\s+(?:OR\\s+(?:REPLACE|ALTER)\\s+)?FUNCTION\\s+(?:IF\\s+NOT\\s+EXISTS\\s+)?(${QUAL_NAME})`,
+      "gi"
+    ),
+    type: "function"
+  },
+  {
+    regex: new RegExp(
+      `\\bCREATE\\s+(?:OR\\s+(?:REPLACE|ALTER)\\s+)?PROC(?:EDURE)?\\s+(?:IF\\s+NOT\\s+EXISTS\\s+)?(${QUAL_NAME})`,
+      "gi"
+    ),
+    type: "procedure"
+  },
+  {
+    regex: new RegExp(
+      `\\bCREATE\\s+(?:OR\\s+(?:REPLACE|ALTER)\\s+)?TRIGGER\\s+(?:IF\\s+NOT\\s+EXISTS\\s+)?(${QUAL_NAME})`,
+      "gi"
+    ),
+    type: "trigger"
+  },
+  {
+    regex: new RegExp(
+      `\\bCREATE\\s+(?:UNIQUE\\s+)?INDEX\\s+(?:CONCURRENTLY\\s+)?(?:IF\\s+NOT\\s+EXISTS\\s+)?(${QUAL_NAME})\\s+ON\\b`,
+      "gi"
+    ),
+    type: "index"
+  }
+];
+
+// src/languages/sql/extractor.ts
+var import_path3 = __toESM(require("path"));
+var _currentFile = "";
+function extractEntities12(code, filePath) {
+  _currentFile = filePath;
+  const masked = maskSqlComments(code);
+  const entities = [];
+  const seenNames = /* @__PURE__ */ new Set();
+  for (const { regex, type } of sqlEntityPatterns) {
+    regex.lastIndex = 0;
+    for (const m of masked.matchAll(regex)) {
+      const raw = m[1].trim();
+      const key = normIdent(raw);
+      if (seenNames.has(key)) continue;
+      seenNames.add(key);
+      entities.push({ name: raw, type, line: lineOf(code, m.index ?? 0), complexity: "low" });
+    }
+  }
+  ROUTINE_RECOVERY_RX.lastIndex = 0;
+  for (const m of masked.matchAll(ROUTINE_RECOVERY_RX)) {
+    const raw = m[1].trim();
+    const key = normIdent(raw);
+    if (seenNames.has(key)) continue;
+    seenNames.add(key);
+    entities.push({ name: `${raw}()`, type: "procedure", line: lineOf(code, m.index ?? 0), complexity: "low" });
+  }
+  return entities;
+}
+function extractImports12(code) {
+  const masked = maskSqlComments(code);
+  const imports = [];
+  const fileBase = import_path3.default.basename(_currentFile, import_path3.default.extname(_currentFile));
+  if (!fileBase) return imports;
+  const ctes = collectCteNames(masked);
+  for (const ref of collectFkRefs(masked)) {
+    imports.push({ source: fileBase, names: [ref.name], isLocal: true });
+  }
+  for (const ref of collectTableRefs(masked, ctes)) {
+    imports.push({ source: fileBase, names: [ref.name], isLocal: true });
+  }
+  return imports;
+}
+function extractExports12(code) {
+  const masked = maskSqlComments(code);
+  const names = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const { regex } of sqlEntityPatterns) {
+    regex.lastIndex = 0;
+    for (const m of masked.matchAll(regex)) {
+      const key = normIdent(m[1].trim());
+      if (!seen.has(key)) {
+        seen.add(key);
+        names.push(m[1].trim());
+      }
+    }
+  }
+  return names;
+}
+
+// src/languages/sql/index.ts
+var SqlParser = {
+  lang: "sql",
+  extensions: [".sql"],
+  extractEntities: extractEntities12,
+  extractImports: extractImports12,
+  extractExports: extractExports12,
+  entityPatterns: sqlEntityPatterns
+};
+registerParser(SqlParser);
+
 // src/stages/collector.ts
 var import_fs = __toESM(require("fs"));
-var import_path3 = __toESM(require("path"));
+var import_path4 = __toESM(require("path"));
 function collectFiles(dir) {
   const results = [];
   function walk(currentDir) {
@@ -23606,7 +23872,7 @@ function collectFiles(dir) {
       return;
     }
     for (const entry of entries) {
-      const fullPath = import_path3.default.join(currentDir, entry);
+      const fullPath = import_path4.default.join(currentDir, entry);
       let stat;
       try {
         stat = import_fs.default.statSync(fullPath);
@@ -23620,7 +23886,7 @@ function collectFiles(dir) {
         }
         continue;
       }
-      const ext = import_path3.default.extname(entry);
+      const ext = import_path4.default.extname(entry);
       if (SUPPORTED_EXTS.has(ext) && stat.size < MAX_FILE_SIZE) {
         results.push(fullPath);
       }
@@ -23632,7 +23898,7 @@ function collectFiles(dir) {
 
 // src/stages/parser.ts
 var import_fs2 = __toESM(require("fs"));
-var import_path4 = __toESM(require("path"));
+var import_path5 = __toESM(require("path"));
 function parseFile(filePath) {
   let code;
   try {
@@ -23641,7 +23907,7 @@ function parseFile(filePath) {
     console.warn(`\u26A0 Cannot read file: ${filePath}`);
     return null;
   }
-  const ext = import_path4.default.extname(filePath).toLowerCase();
+  const ext = import_path5.default.extname(filePath).toLowerCase();
   const parser = getLanguageParser(ext);
   if (!parser) return null;
   const isHashCommentLang = [".py", ".rb", ".sh", ".bash", ".ps1"].includes(ext);
@@ -23673,12 +23939,12 @@ function parseFiles(filePaths) {
 }
 
 // src/stages/graph.ts
-var import_path5 = __toESM(require("path"));
+var import_path6 = __toESM(require("path"));
 function buildGraph(parsedFiles) {
   const nodes = /* @__PURE__ */ new Map();
   const edges = [];
   for (const file of parsedFiles) {
-    const fileBase = import_path5.default.basename(file.filePath, import_path5.default.extname(file.filePath));
+    const fileBase = import_path6.default.basename(file.filePath, import_path6.default.extname(file.filePath));
     for (const entity of file.entities) {
       const id = makeId(entity.name, fileBase);
       if (nodes.has(id)) continue;
@@ -23702,7 +23968,7 @@ function buildGraph(parsedFiles) {
     fileMap.set(file.filePath, file);
   }
   for (const file of parsedFiles) {
-    const fileBase = import_path5.default.basename(file.filePath, import_path5.default.extname(file.filePath));
+    const fileBase = import_path6.default.basename(file.filePath, import_path6.default.extname(file.filePath));
     for (const imp of file.imports) {
       if (!imp.isLocal) continue;
       const resolvedPath = resolvePath(file.filePath, imp.source, parsedFiles);
@@ -23712,7 +23978,7 @@ function buildGraph(parsedFiles) {
       for (const importedName of imp.names) {
         const targetEntity = targetFile.entities.find((e) => e.name === importedName);
         if (!targetEntity) continue;
-        const targetBase = import_path5.default.basename(resolvedPath, import_path5.default.extname(resolvedPath));
+        const targetBase = import_path6.default.basename(resolvedPath, import_path6.default.extname(resolvedPath));
         const toId = makeId(importedName, targetBase);
         if (!nodes.has(toId)) continue;
         const fromEntities = file.entities.length > 0 ? file.entities : [{ name: fileBase, type: "file", line: 0, complexity: "low" }];
@@ -23728,7 +23994,7 @@ function buildGraph(parsedFiles) {
             from: fromId,
             to: toId,
             type: "imports",
-            description: `${fromEntity.name} imports ${importedName} from ${import_path5.default.basename(resolvedPath)}`
+            description: `${fromEntity.name} imports ${importedName} from ${import_path6.default.basename(resolvedPath)}`
           });
           const fromNode = nodes.get(fromId);
           const toNode = nodes.get(toId);
@@ -23750,7 +24016,7 @@ function makeId(name, fileBase) {
   return `${cleanName}__${cleanBase}`;
 }
 function resolvePath(fromFile, importSource, allFiles) {
-  const fromDir = import_path5.default.dirname(fromFile);
+  const fromDir = import_path6.default.dirname(fromFile);
   let normalizedSource = importSource;
   if (normalizedSource.startsWith("crate::")) {
     normalizedSource = normalizedSource.slice(7).replace(/::/g, "/");
@@ -23759,7 +24025,7 @@ function resolvePath(fromFile, importSource, allFiles) {
   } else if (normalizedSource.startsWith("self::")) {
     normalizedSource = "./" + normalizedSource.slice(6).replace(/::/g, "/");
   }
-  const base = import_path5.default.join(fromDir, normalizedSource);
+  const base = import_path6.default.join(fromDir, normalizedSource);
   const candidates = [
     base,
     `${base}.ts`,
@@ -23769,14 +24035,15 @@ function resolvePath(fromFile, importSource, allFiles) {
     `${base}/index.ts`,
     `${base}/index.js`,
     `${base}.dart`,
-    `${base}.rs`
+    `${base}.rs`,
+    `${base}.sql`
   ];
   for (const candidate of candidates) {
     const normalized = candidate.replace(/\\/g, "/");
     const found = allFiles.find((f) => f.filePath.replace(/\\/g, "/") === normalized);
     if (found) return found.filePath;
   }
-  const parentBase = import_path5.default.dirname(base);
+  const parentBase = import_path6.default.dirname(base);
   if (parentBase && parentBase !== base) {
     const parentCandidates = [
       `${parentBase}.rs`,
@@ -23966,7 +24233,7 @@ function emptyReport(targetName, changeDescription, reason) {
 
 // src/stages/gitdiff.ts
 var import_child_process = require("child_process");
-var import_path6 = __toESM(require("path"));
+var import_path7 = __toESM(require("path"));
 function getChangedEntities(options) {
   const diff = runGitDiff(options);
   if (!diff) return [];
@@ -24058,7 +24325,7 @@ function parseDiff(diff, projectDir) {
   return entities;
 }
 function extractEntityFromContext(context, file) {
-  const ext = import_path6.default.extname(file).toLowerCase();
+  const ext = import_path7.default.extname(file).toLowerCase();
   const parser = getLanguageParser(ext);
   if (parser?.entityPatterns) {
     for (const { regex, type } of parser.entityPatterns) {
@@ -24110,28 +24377,79 @@ function buildPipeline(projectDir) {
   const metrics = computeMetrics(graph);
   return { files, parsed, graph, metrics };
 }
-function analyzeProject(projectDir) {
+function buildSubgraph(graph, focusName, maxDepth) {
+  const focusNode = [...graph.nodes.values()].find((n) => n.name === focusName);
+  if (!focusNode) return { nodes: /* @__PURE__ */ new Map(), edges: [] };
+  const included = /* @__PURE__ */ new Set();
+  const queue = [{ id: focusNode.id, depth: 0 }];
+  while (queue.length > 0) {
+    const { id, depth } = queue.shift();
+    if (included.has(id)) continue;
+    included.add(id);
+    if (depth >= maxDepth) continue;
+    for (const edge of graph.edges) {
+      if (edge.from === id && !included.has(edge.to)) queue.push({ id: edge.to, depth: depth + 1 });
+      if (edge.to === id && !included.has(edge.from)) queue.push({ id: edge.from, depth: depth + 1 });
+    }
+  }
+  const nodes = /* @__PURE__ */ new Map();
+  for (const id of included) {
+    const node = graph.nodes.get(id);
+    if (node) nodes.set(id, node);
+  }
+  return {
+    nodes,
+    edges: graph.edges.filter((e) => included.has(e.from) && included.has(e.to))
+  };
+}
+function buildProseSummary(summary) {
+  const s = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+  const shortIds = (ids) => ids.slice(0, 3).map((id) => id.split("__")[0]).join(", ") + (ids.length > 3 ? ` (+${ids.length - 3} more)` : "");
+  const parts = [
+    `${s(summary.totalFiles, "file")}, ${s(summary.totalNodes, "node")}, ${s(summary.totalEdges, "edge")}.`
+  ];
+  if (summary.criticalNodes.length > 0) {
+    parts.push(
+      `${s(summary.criticalNodes.length, "critical node")} \u2014 change carefully: ${shortIds(summary.criticalNodes)}.`
+    );
+  }
+  if (summary.entryPoints.length > 0) {
+    parts.push(`${s(summary.entryPoints.length, "entry point")}: ${shortIds(summary.entryPoints)}.`);
+  }
+  if (summary.leafNodes.length > 0) {
+    parts.push(`${s(summary.leafNodes.length, "leaf node")} (pure utilities with no outgoing deps).`);
+  }
+  if (summary.isolatedNodes.length > 0) {
+    parts.push(`${s(summary.isolatedNodes.length, "isolated node")} \u2014 potential dead code: ${shortIds(summary.isolatedNodes)}.`);
+  }
+  return parts.join(" ");
+}
+function analyzeProject(projectDir, opts = {}) {
+  const { verbosity = "full", focus, depth = 3 } = opts;
   const { files, parsed, metrics } = buildPipeline(projectDir);
   const totalLines = parsed.reduce((sum, f) => sum + f.lines, 0);
-  return {
-    meta: {
-      version: VERSION,
-      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-      totalFiles: parsed.length,
-      totalLines
-    },
-    summary: {
-      totalNodes: metrics.nodes.size,
-      totalEdges: metrics.edges.length,
-      entryPoints: getEntryPoints(metrics),
-      leafNodes: getLeafNodes(metrics),
-      isolatedNodes: getIsolatedNodes(metrics),
-      criticalNodes: getCriticalNodes(metrics)
-    },
-    nodes: [...metrics.nodes.values()],
-    edges: metrics.edges,
-    files: parsed
+  const graph = focus ? buildSubgraph(metrics, focus, depth) : metrics;
+  const meta = {
+    version: VERSION,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    totalFiles: parsed.length,
+    totalLines
+  };
+  const summary = {
+    totalNodes: graph.nodes.size,
+    totalEdges: graph.edges.length,
+    entryPoints: getEntryPoints(graph),
+    leafNodes: getLeafNodes(graph),
+    isolatedNodes: getIsolatedNodes(graph),
+    criticalNodes: getCriticalNodes(graph)
   };
+  if (verbosity === "sketch") {
+    return { meta, summary, nodes: [], edges: [], files: [] };
+  }
+  if (verbosity === "overview") {
+    return { meta, summary, nodes: [...graph.nodes.values()], edges: [], files: [] };
+  }
+  return { meta, summary, nodes: [...graph.nodes.values()], edges: graph.edges, files: parsed };
 }
 function analyzeImpact(projectDir, targetNode, changeDescription) {
   const { metrics } = buildPipeline(projectDir);
@@ -24149,16 +24467,68 @@ function analyzeGitImpact(options) {
   }));
   return { changedEntities, impacts };
 }
-function getGraphSummary(projectDir) {
+function getGraphSummary(projectDir, verbosity = "overview") {
   const { files, parsed, metrics } = buildPipeline(projectDir);
-  return {
+  const base = {
     totalFiles: files.length,
     totalNodes: metrics.nodes.size,
     totalEdges: metrics.edges.length,
+    criticalNodes: getCriticalNodes(metrics)
+  };
+  if (verbosity === "sketch") {
+    return { ...base, entryPoints: [], leafNodes: [], isolatedNodes: [] };
+  }
+  return {
+    ...base,
     entryPoints: getEntryPoints(metrics),
     leafNodes: getLeafNodes(metrics),
-    isolatedNodes: getIsolatedNodes(metrics),
-    criticalNodes: getCriticalNodes(metrics)
+    isolatedNodes: getIsolatedNodes(metrics)
+  };
+}
+function describeNode(projectDir, nodeName) {
+  const { metrics } = buildPipeline(projectDir);
+  const node = [...metrics.nodes.values()].find((n) => n.name === nodeName);
+  if (!node) {
+    return {
+      found: false,
+      name: nodeName,
+      file: "",
+      line: 0,
+      type: "",
+      lang: "",
+      centralityScore: 0,
+      inDegree: 0,
+      outDegree: 0,
+      importedBy: [],
+      imports: [],
+      role: "not found"
+    };
+  }
+  const importedBy = [...new Set(
+    metrics.edges.filter((e) => e.to === node.id).map((e) => metrics.nodes.get(e.from)?.name).filter((n) => Boolean(n))
+  )];
+  const imports = [...new Set(
+    metrics.edges.filter((e) => e.from === node.id).map((e) => metrics.nodes.get(e.to)?.name).filter((n) => Boolean(n))
+  )];
+  let role;
+  if (node.centralityScore > 20) role = "critical shared dependency";
+  else if (node.inDegree === 0 && node.outDegree > 0) role = "entry point";
+  else if (node.outDegree === 0 && node.inDegree > 0) role = "leaf";
+  else if (node.inDegree === 0 && node.outDegree === 0) role = "isolated \u2014 potential dead code";
+  else role = "connector";
+  return {
+    found: true,
+    name: node.name,
+    file: node.file,
+    line: node.line,
+    type: node.type,
+    lang: node.lang,
+    centralityScore: node.centralityScore,
+    inDegree: node.inDegree,
+    outDegree: node.outDegree,
+    importedBy,
+    imports,
+    role
   };
 }
 
@@ -24168,16 +24538,17 @@ var server = new McpServer({
   version: VERSION
 });
 server.tool(
-  "analyze_project",
-  "Scan a project directory and return its full dependency graph \u2014 nodes, edges, entry points, leaf nodes, isolated nodes, critical nodes, and per-file metadata. Use this to understand the full structure of a codebase before making changes.",
+  "describe_node",
+  'PREFERRED first tool for questions about a specific function, class, or entity. Returns what depends on it, what it depends on, its file/line, type, and role \u2014 all in ~50 tokens. Use this INSTEAD of analyze_project when the question is "tell me about X" or "what uses X" or "what does X import". Much cheaper than loading the full graph.',
   {
-    projectDir: external_exports.string().describe(
-      "Absolute path to the project directory to analyze (e.g. /Users/me/my-app)"
+    projectDir: external_exports.string().describe("Absolute path to the project directory"),
+    nodeName: external_exports.string().describe(
+      'Exact name of the entity to look up (e.g. "getUserById", "UserService", "AuthMiddleware")'
     )
   },
-  async ({ projectDir }) => {
+  async ({ projectDir, nodeName }) => {
     try {
-      const result = analyzeProject(projectDir);
+      const result = describeNode(projectDir, nodeName);
       return {
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
       };
@@ -24191,15 +24562,22 @@ server.tool(
 );
 server.tool(
   "get_graph_summary",
-  "Get a lightweight summary of the dependency graph \u2014 file/node/edge counts, entry points, leaf nodes, isolated nodes, and critical nodes \u2014 without returning the full graph data. Faster than analyze_project when you only need the overview.",
+  'Get a project-wide overview \u2014 file/node/edge counts, critical nodes, entry points, leaf nodes, and isolated nodes. Use verbosity "sketch" (~50 tokens) for a quick orientation, "overview" for the full summary. Use format "prose" to get a single readable sentence (~100 tokens) instead of JSON. Call this before analyze_project or when you only need counts and structure, not full node data.',
   {
-    projectDir: external_exports.string().describe("Absolute path to the project directory")
+    projectDir: external_exports.string().describe("Absolute path to the project directory"),
+    verbosity: external_exports.enum(["sketch", "overview", "full"]).optional().describe(
+      '"sketch" = counts + critical nodes only (~50 tokens). "overview" = full summary with entry/leaf/isolated lists (default). "full" = same as overview.'
+    ),
+    format: external_exports.enum(["json", "prose"]).optional().describe(
+      '"json" = structured JSON object (default). "prose" = single readable paragraph (~100 tokens) \u2014 use when you want compact context without JSON overhead.'
+    )
   },
-  async ({ projectDir }) => {
+  async ({ projectDir, verbosity, format }) => {
     try {
-      const result = getGraphSummary(projectDir);
+      const result = getGraphSummary(projectDir, verbosity ?? "overview");
+      const text = format === "prose" ? buildProseSummary(result) : JSON.stringify(result, null, 2);
       return {
-        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        content: [{ type: "text", text }]
       };
     } catch (err) {
       return {
@@ -24211,16 +24589,14 @@ server.tool(
 );
 server.tool(
   "simulate_impact",
-  "Simulate the cascading downstream impact of changing a specific function, class, or entity. Returns a risk score (0-100), risk level (LOW/MEDIUM/HIGH/CRITICAL), a list of all affected nodes with their change requirements, a testing plan, and actionable recommendations.",
+  'PREFERRED tool when the question is impact-oriented: "what breaks if I change X?". Use this INSTEAD of analyze_project \u2014 it requires no graph preload and costs ~200 tokens vs ~80k for the full graph. Returns risk score (0-100), risk level (LOW/MEDIUM/HIGH/CRITICAL), all affected nodes, a testing plan, and recommendations.',
   {
-    projectDir: external_exports.string().describe(
-      "Absolute path to the project directory"
-    ),
+    projectDir: external_exports.string().describe("Absolute path to the project directory"),
     targetNode: external_exports.string().describe(
       'Name of the function, class, or entity to simulate changing (e.g. "getUserById")'
     ),
     changeDescription: external_exports.string().describe(
-      'Human-readable description of the proposed change (e.g. "removing the userId parameter")'
+      'Description of the proposed change (e.g. "removing the userId parameter")'
     )
   },
   async ({ projectDir, targetNode, changeDescription }) => {
@@ -24237,9 +24613,40 @@ server.tool(
     }
   }
 );
+server.tool(
+  "analyze_project",
+  'Return the dependency graph. EXPENSIVE at full verbosity \u2014 use verbosity "sketch" or "overview", or narrow scope with "focus" + "depth" to avoid token overload. Prefer describe_node for single-entity questions, simulate_impact for risk questions, and get_graph_summary for project-wide orientation.',
+  {
+    projectDir: external_exports.string().describe(
+      "Absolute path to the project directory to analyze (e.g. /Users/me/my-app)"
+    ),
+    verbosity: external_exports.enum(["sketch", "overview", "full"]).optional().describe(
+      '"sketch" = meta + summary only, no nodes/edges (~100 tokens). "overview" = meta + summary + nodes, no edges. "full" = complete graph incl. edges and file detail (default, can be very large).'
+    ),
+    focus: external_exports.string().optional().describe(
+      "Entity name to centre the graph on \u2014 returns only the subgraph within `depth` hops of this node (bidirectional). Use to scope the result to one module instead of the whole project."
+    ),
+    depth: external_exports.number().optional().describe(
+      "Max BFS hops from the focus node (default 3). Only used when focus is set."
+    )
+  },
+  async ({ projectDir, verbosity, focus, depth }) => {
+    try {
+      const result = analyzeProject(projectDir, { verbosity, focus, depth });
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+      };
+    } catch (err) {
+      return {
+        content: [{ type: "text", text: `Error: ${err.message}` }],
+        isError: true
+      };
+    }
+  }
+);
 server.tool(
   "git_impact",
-  "Detect which functions/classes changed in a git diff and simulate their downstream impact on the whole project. Supports three modes: uncommitted changes, a specific commit, or a branch comparison.",
+  'PREFERRED tool for "what did this commit/branch change and what does it break?". Detects changed functions/classes from a git diff and simulates their downstream impact \u2014 no manual entity name needed. Supports uncommitted changes, a specific commit SHA, or a branch comparison.',
   {
     projectDir: external_exports.string().describe(
       "Absolute path to the project directory (must be a git repository)"