enigma-cli 1.59.1 → 1.60.0

package/dist/codegraph-hook.js

@@ -304,6 +304,8 @@ var init_config = __esm({
       gateTrivialLines: 20,
       subagentLimit: 4,
       compactWindow: 4e5,
+      relay: true,
+      relayAt: 3e5,
       planSessionLimit: 0,
       planWeeklyLimit: 0,
       planWeeklySonnetLimit: 0,
@@ -545,10 +547,222 @@ var init_codegraph_rank = __esm({
   }
 });
 
+// src/codegraph-extract-docs.ts
+function cap(text) {
+  const t = text.trim();
+  return t.length > MAX_SIGNATURE ? `${t.slice(0, MAX_SIGNATURE)}...` : t;
+}
+function indentOf(line) {
+  let n = 0;
+  while (n < line.length && (line[n] === " " || line[n] === "	")) n++;
+  return n;
+}
+function fencedLines(lines) {
+  const inside = new Uint8Array(lines.length);
+  let fence = null;
+  for (let i = 0; i < lines.length; i++) {
+    const m = /^\s*(`{3,}|~{3,})/.exec(lines[i]);
+    if (fence) {
+      inside[i] = 1;
+      if (m && m[1][0] === fence[0] && m[1].length >= fence.length) fence = null;
+      continue;
+    }
+    if (m) {
+      fence = m[1];
+      inside[i] = 1;
+    }
+  }
+  return inside;
+}
+function markdownSymbols(lines) {
+  const fenced = fencedLines(lines);
+  const heads = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (fenced[i]) continue;
+    const m = /^(#{1,6})\s+(.+?)\s*#*\s*$/.exec(lines[i]);
+    if (m && m[1].length <= MAX_HEADING_LEVEL) heads.push({ level: m[1].length, name: m[2].replace(/[`*_]/g, "").trim(), line: i + 1 });
+  }
+  return heads.filter((h) => h.name).map((h, idx) => {
+    const next = heads.slice(idx + 1).find((o) => o.level <= h.level);
+    return { name: h.name, kind: "section", line: h.line, endLine: next ? next.line - 1 : lines.length, signature: cap(lines[h.line - 1]) };
+  });
+}
+function sqlEnd(lines, start) {
+  let dollar = false;
+  for (let i = start; i < lines.length; i++) {
+    const parts = lines[i].replace(/--.*$/, "").split("$$");
+    for (let p = 0; p < parts.length; p++) {
+      if (p > 0) dollar = !dollar;
+      if (!dollar && parts[p].includes(";")) return i + 1;
+    }
+  }
+  return lines.length;
+}
+function sqlSymbols(lines) {
+  const rules = [
+    ["table", new RegExp(String.raw`^\s*create\s+(?:or\s+replace\s+)?(?:(?:global|local)\s+)?(?:temp(?:orary)?\s+|unlogged\s+)?(?:materialized\s+)?(?:table|view)\s+(?:if\s+not\s+exists\s+)?${SQL_NAME}`, "i")],
+    ["function", new RegExp(String.raw`^\s*create\s+(?:or\s+replace\s+)?(?:function|procedure)\s+${SQL_NAME}`, "i")],
+    ["type", new RegExp(String.raw`^\s*create\s+type\s+${SQL_NAME}`, "i")]
+  ];
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    for (const [kind, re] of rules) {
+      const m = re.exec(lines[i]);
+      if (!m) continue;
+      out.push({ name: m[1], kind, line: i + 1, endLine: sqlEnd(lines, i), signature: cap(lines[i].replace(/\(.*$/, "")) });
+      break;
+    }
+  }
+  return out;
+}
+function prismaSymbols(lines) {
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = /^\s*(model|view|enum|type)\s+([A-Za-z_]\w*)\s*\{/.exec(lines[i]);
+    if (!m) continue;
+    let end = i;
+    while (end < lines.length - 1 && !/^\s*\}/.test(lines[end])) end++;
+    const kind = m[1] === "enum" ? "enum" : m[1] === "type" ? "type" : "table";
+    out.push({ name: m[2], kind, line: i + 1, endLine: end + 1, signature: cap(`${m[1]} ${m[2]}`) });
+  }
+  return out;
+}
+function yamlEnd(lines, start) {
+  const base = indentOf(lines[start]);
+  let end = start + 1;
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.trim() || line.trimStart().startsWith("#")) continue;
+    if (indentOf(line) <= base && !line.trimStart().startsWith("- ")) break;
+    end = i + 1;
+  }
+  return end;
+}
+function yamlSymbols(lines) {
+  const out = [];
+  const KEY = /^(\s*)([A-Za-z0-9_][\w.-]*)\s*:(?:\s|$)/;
+  for (let i = 0; i < lines.length; i++) {
+    const m = KEY.exec(lines[i]);
+    if (!m || m[1].length) continue;
+    const end = yamlEnd(lines, i);
+    out.push({ name: m[2], kind: "key", line: i + 1, endLine: end, signature: cap(lines[i]) });
+    if (!YAML_CONTAINERS.has(m[2])) continue;
+    let childIndent = -1;
+    for (let j = i + 1; j < end; j++) {
+      const c = KEY.exec(lines[j]);
+      if (!c || !c[1].length) continue;
+      if (childIndent === -1) childIndent = c[1].length;
+      if (c[1].length !== childIndent) continue;
+      out.push({ name: c[2], kind: "key", line: j + 1, endLine: yamlEnd(lines, j), signature: cap(`${m[2]}.${c[2]}`) });
+    }
+  }
+  return out;
+}
+function tomlSymbols(lines) {
+  const heads = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = /^\s*\[\[?\s*([^\]]+?)\s*\]\]?\s*(?:#.*)?$/.exec(lines[i]);
+    if (m) heads.push({ name: m[1], line: i + 1 });
+  }
+  return heads.map((h, idx) => ({
+    name: h.name,
+    kind: "key",
+    line: h.line,
+    endLine: idx + 1 < heads.length ? heads[idx + 1].line - 1 : lines.length,
+    signature: cap(lines[h.line - 1])
+  }));
+}
+function markdownLinks(lines) {
+  const fenced = fencedLines(lines);
+  const out = /* @__PURE__ */ new Set();
+  for (let i = 0; i < lines.length; i++) {
+    if (fenced[i]) continue;
+    const re = /\]\(\s*<?([^)\s>]+)>?(?:\s+"[^"]*")?\s*\)/g;
+    let m;
+    while (m = re.exec(lines[i])) {
+      const target = m[1].replace(/[#?].*$/, "");
+      if (!target || /^[a-z][a-z0-9+.-]*:/i.test(target) || target.startsWith("//")) continue;
+      try {
+        out.add(decodeURI(target));
+      } catch {
+        out.add(target);
+      }
+    }
+  }
+  return [...out];
+}
+function markdownCodeMentions(content) {
+  const lines = content.split("\n");
+  const fenced = fencedLines(lines);
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (fenced[i]) continue;
+    const re = /`([A-Za-z_$][\w$]*)(?:\(\))?`/g;
+    let m;
+    while (m = re.exec(lines[i])) out.push({ name: m[1], line: i + 1 });
+  }
+  return out;
+}
+function extractDocFile(lang, content) {
+  const lines = content.split("\n");
+  const out = (() => {
+    switch (lang) {
+      case "markdown":
+        return { symbols: markdownSymbols(lines), imports: markdownLinks(lines) };
+      case "sql":
+        return { symbols: sqlSymbols(lines), imports: [] };
+      case "prisma":
+        return { symbols: prismaSymbols(lines), imports: [] };
+      case "yaml":
+        return { symbols: yamlSymbols(lines), imports: [] };
+      case "toml":
+        return { symbols: tomlSymbols(lines), imports: [] };
+      default:
+        return { symbols: [], imports: [] };
+    }
+  })();
+  for (const s of out.symbols) while (s.endLine > s.line && !(lines[s.endLine - 1] ?? "").trim()) s.endLine--;
+  return out;
+}
+var DOC_LANG_BY_EXT, DOC_LANGS, DOC_REFERENCE_LANGS, YAML_CONTAINERS, MAX_SIGNATURE, MAX_HEADING_LEVEL, SQL_NAME;
+var init_codegraph_extract_docs = __esm({
+  "src/codegraph-extract-docs.ts"() {
+    "use strict";
+    DOC_LANG_BY_EXT = {
+      ".md": "markdown",
+      ".mdx": "markdown",
+      ".sql": "sql",
+      ".prisma": "prisma",
+      ".yaml": "yaml",
+      ".yml": "yaml",
+      ".toml": "toml"
+    };
+    DOC_LANGS = new Set(Object.values(DOC_LANG_BY_EXT));
+    DOC_REFERENCE_LANGS = /* @__PURE__ */ new Set(["sql", "prisma"]);
+    YAML_CONTAINERS = /* @__PURE__ */ new Set(["services", "jobs", "workflows", "volumes", "networks"]);
+    MAX_SIGNATURE = 200;
+    MAX_HEADING_LEVEL = 3;
+    SQL_NAME = String.raw`(?:[\w"\x60\[\]]+\.)?["\x60\[]?([A-Za-z_][\w$]*)["\x60\]]?`;
+  }
+});
+
 // src/codegraph-extract.ts
 import { execFileSync as execFileSync2 } from "child_process";
 import { extname, join as join4, relative as relative2, resolve as resolve2 } from "path";
 import { existsSync as existsSync4, readdirSync as readdirSync2, readFileSync as readFileSync4, statSync as statSync2 } from "fs";
+function isCodeLang(lang) {
+  return !DOC_LANGS.has(lang);
+}
+function isDocPath(path) {
+  return !!DOC_LANG_BY_EXT[extname(path).toLowerCase()];
+}
+function isForeignPath(rel) {
+  return FOREIGN_DOC_DIRS.test(rel);
+}
+function pickDocs(root, docs, room) {
+  const depth = (p) => relPath(root, p).split("/").length;
+  return docs.filter((p) => !FOREIGN_DOC_DIRS.test(relPath(root, p))).sort((a, b) => depth(a) - depth(b) || a.localeCompare(b)).slice(0, Math.max(0, Math.min(MAX_DOC_FILES, room)));
+}
 function symRules(lang) {
   switch (lang) {
     case "ts":
@@ -713,7 +927,7 @@ function lineResolver(content) {
     return lo + 1;
   };
 }
-function indentOf(line) {
+function indentOf2(line) {
   let n = 0;
   while (n < line.length && (line[n] === " " || line[n] === "	")) n++;
   return n;
@@ -779,18 +993,18 @@ function braceEnd(lines, startIdx, lang) {
   return lines.length;
 }
 function indentEnd(lines, startIdx) {
-  const base = indentOf(lines[startIdx]);
+  const base = indentOf2(lines[startIdx]);
   let end = startIdx + 1;
   for (let i = startIdx + 1; i < lines.length; i++) {
     const line = lines[i];
     if (!line.trim()) continue;
-    if (indentOf(line) <= base) break;
+    if (indentOf2(line) <= base) break;
     end = i + 1;
   }
   return end;
 }
 function clampToSiblings(symbols, lines) {
-  const indentAt = (line) => indentOf(lines[line - 1] ?? "");
+  const indentAt = (line) => indentOf2(lines[line - 1] ?? "");
   for (let i = 0; i < symbols.length; i++) {
     const s = symbols[i];
     for (let j = i + 1; j < symbols.length; j++) {
@@ -803,14 +1017,15 @@ function clampToSiblings(symbols, lines) {
   }
 }
 function signatureOf(line) {
-  const MAX_SIGNATURE = 200;
+  const MAX_SIGNATURE2 = 200;
   let sig = line.trim();
   const brace = sig.indexOf("{");
   if (brace > 0) sig = sig.slice(0, brace).trim();
   if (sig.endsWith(":")) sig = sig.slice(0, -1).trim();
-  return sig.length > MAX_SIGNATURE ? `${sig.slice(0, MAX_SIGNATURE)}...` : sig;
+  return sig.length > MAX_SIGNATURE2 ? `${sig.slice(0, MAX_SIGNATURE2)}...` : sig;
 }
 function extractFile(lang, content) {
+  if (DOC_LANGS.has(lang)) return extractDocFile(lang, content);
   const lineAt = lineResolver(content);
   const lines = content.split("\n");
   const braced = BRACE_LANGS.has(lang);
@@ -852,25 +1067,27 @@ function gitSourceFiles(root) {
   const out = gitList(root, ["--cached", "--others", "--exclude-standard"]);
   if (out === null) return null;
   const nested = existsSync4(join4(root, ".gitmodules")) ? gitList(root, ["--recurse-submodules"]) : null;
-  const files = [];
+  const code = [];
+  const docs = [];
   const seen = /* @__PURE__ */ new Set();
   for (const rel of [...out.split("\0"), ...(nested ?? "").split("\0")]) {
-    if (files.length >= MAX_FILES) break;
+    if (code.length >= MAX_FILES) break;
     if (!rel || seen.has(rel)) continue;
     seen.add(rel);
     if (!LANG_BY_EXT[extname(rel).toLowerCase()]) continue;
     if (rel.split("/").some((seg) => seg.startsWith(".") || IGNORE_DIRS.has(seg))) continue;
-    files.push(join4(root, rel));
+    (isDocPath(rel) ? docs : code).push(join4(root, rel));
   }
-  return files;
+  return [...code, ...pickDocs(root, docs, MAX_FILES - code.length)];
 }
 function walk(root) {
   const tracked = gitSourceFiles(root);
   if (tracked && tracked.length) return { files: tracked, truncated: tracked.length >= MAX_FILES };
-  const files = [];
+  const code = [];
+  const docs = [];
   const queue = [root];
   let visited = 0;
-  for (let head = 0; head < queue.length && files.length < MAX_FILES && visited < MAX_ENTRIES; head++) {
+  for (let head = 0; head < queue.length && code.length < MAX_FILES && visited < MAX_ENTRIES; head++) {
     let entries;
     try {
       entries = readdirSync2(queue[head], { withFileTypes: true });
@@ -878,16 +1095,17 @@ function walk(root) {
       continue;
     }
     for (const e of entries) {
-      if (files.length >= MAX_FILES || ++visited >= MAX_ENTRIES) break;
+      if (code.length >= MAX_FILES || ++visited >= MAX_ENTRIES) break;
       if (e.isDirectory()) {
         if (!e.name.startsWith(".") && !IGNORE_DIRS.has(e.name)) queue.push(join4(queue[head], e.name));
         continue;
       }
-      if (!e.isFile()) continue;
-      if (LANG_BY_EXT[extname(e.name).toLowerCase()]) files.push(join4(queue[head], e.name));
+      if (!e.isFile() || !LANG_BY_EXT[extname(e.name).toLowerCase()]) continue;
+      (isDocPath(e.name) ? docs : code).push(join4(queue[head], e.name));
     }
   }
-  return { files, truncated: files.length >= MAX_FILES || visited >= MAX_ENTRIES };
+  const ordered = [...code, ...pickDocs(root, docs, MAX_FILES - code.length)];
+  return { files: ordered, truncated: code.length >= MAX_FILES || visited >= MAX_ENTRIES };
 }
 function relPath(root, abs) {
   return relative2(root, abs).split("\\").join("/");
@@ -945,10 +1163,11 @@ function statSourceFiles(root) {
   }
   return out;
 }
-var IGNORE_DIRS, LANG_BY_EXT, MAX_FILES, MAX_FILE_BYTES, BRACE_LANGS, HASH_COMMENT_LANGS, PREPROCESSOR_LANGS, MAX_ENTRIES;
+var IGNORE_DIRS, CODE_LANG_BY_EXT, LANG_BY_EXT, FOREIGN_DOC_DIRS, MAX_DOC_FILES, MAX_FILES, MAX_FILE_BYTES, BRACE_LANGS, HASH_COMMENT_LANGS, PREPROCESSOR_LANGS, MAX_ENTRIES;
 var init_codegraph_extract = __esm({
   "src/codegraph-extract.ts"() {
     "use strict";
+    init_codegraph_extract_docs();
     IGNORE_DIRS = /* @__PURE__ */ new Set([
       "node_modules",
       ".git",
@@ -973,7 +1192,7 @@ var init_codegraph_extract = __esm({
       ".gradle",
       ".dart_tool"
     ]);
-    LANG_BY_EXT = {
+    CODE_LANG_BY_EXT = {
       ".ts": "ts",
       ".tsx": "ts",
       ".mts": "ts",
@@ -999,6 +1218,9 @@ var init_codegraph_extract = __esm({
       ".hpp": "cpp",
       ".hh": "cpp"
     };
+    LANG_BY_EXT = { ...CODE_LANG_BY_EXT, ...DOC_LANG_BY_EXT };
+    FOREIGN_DOC_DIRS = /(?:^|\/)(?:references?|examples?|samples?|fixtures?|third[_-]party|vendor(?:ed)?)\//i;
+    MAX_DOC_FILES = 1500;
     MAX_FILES = 8e3;
     MAX_FILE_BYTES = 512 * 1024;
     BRACE_LANGS = /* @__PURE__ */ new Set(["ts", "js", "go", "rust", "java", "csharp", "kotlin", "php", "c", "cpp"]);
@@ -1214,12 +1436,12 @@ function buildEdges(root, files, importEdges, resolveImport) {
   }
   const edges = [];
   const seen = /* @__PURE__ */ new Set();
-  const push = (from, to, rel) => {
+  const push = (from, to, rel, inferred = false) => {
     if (edges.length >= MAX_EDGES || from === to) return;
     const key = `${from}|${to}|${rel}`;
     if (seen.has(key)) return;
     seen.add(key);
-    edges.push([from, to, rel]);
+    edges.push(inferred ? [from, to, rel, 1] : [from, to, rel]);
   };
   for (const f of files) {
     for (const span of spansByFile.get(f.path) ?? []) push(f.path, span.id, "contains");
@@ -1248,12 +1470,14 @@ function buildEdges(root, files, importEdges, resolveImport) {
       const candidates = defsByName.get(name)?.filter((c) => imported?.has(c.path) && reachable(c.path));
       return candidates?.length === 1 ? candidates[0].id : null;
     };
+    const extracted = (id) => id ? { id, inferred: false } : null;
+    const inferred = (id) => id ? { id, inferred: true } : null;
     if (!f.bindings) {
       return (name) => {
-        if (local.has(name)) return local.get(name) ?? null;
-        if (imported?.size) return unique(name);
+        if (local.has(name)) return extracted(local.get(name));
+        if (imported?.size) return inferred(unique(name));
         const all = defsByName.get(name)?.filter((c) => reachable(c.path));
-        return all?.length === 1 ? all[0].id : null;
+        return all?.length === 1 ? inferred(all[0].id) : null;
       };
     }
     const bound = new Set(f.bindings.names);
@@ -1265,10 +1489,10 @@ function buildEdges(root, files, importEdges, resolveImport) {
     return (name, memberOf) => {
       if (memberOf !== void 0) {
         const path = namespaces.get(memberOf);
-        return path ? idByPathName.get(`${path}#${name}`) ?? null : null;
+        return path ? extracted(idByPathName.get(`${path}#${name}`)) : null;
       }
-      if (local.has(name)) return local.get(name) ?? null;
-      return bound.has(name) ? unique(name) : null;
+      if (local.has(name)) return extracted(local.get(name));
+      return bound.has(name) ? extracted(unique(name)) : null;
     };
   }
   const bodies = [];
@@ -1282,7 +1506,7 @@ function buildEdges(root, files, importEdges, resolveImport) {
     const spans = spansByFile.get(f.path) ?? [];
     const declLines = new Set(f.symbols.map((s) => s.line));
     const lines = content.split("\n");
-    indexBodies(bodies, f.path, spans, lines);
+    indexBodies(bodies, f.path, spans, lines, DOC_LANGS.has(f.lang) ? MAX_DOC_BODY_TOKENS : MAX_BODY_TOKENS);
     const bind = binderFor(f);
     const strict = !!f.bindings;
     for (const s of f.symbols) {
@@ -1291,9 +1515,17 @@ function buildEdges(root, files, importEdges, resolveImport) {
       if (!self) continue;
       for (const [rel, name] of inheritanceTargets(s.signature)) {
         const target = bind(name);
-        if (target) push(self.id, target, rel);
+        if (target) push(self.id, target.id, rel, target.inferred);
       }
     }
+    if (f.lang === "markdown") {
+      for (const { name, line } of markdownCodeMentions(content)) {
+        if (name.length < MIN_DOC_MENTION) continue;
+        const code = defsByName.get(name)?.filter((c) => !DOC_LANGS.has(langByPath.get(c.path) ?? ""));
+        if (code?.length === 1) push(enclosingSymbol(spans, line) ?? f.path, code[0].id, "references", true);
+      }
+    }
+    if (DOC_LANGS.has(f.lang) && !DOC_REFERENCE_LANGS.has(f.lang)) continue;
     for (let i = 0; i < lines.length; i++) {
       const lineNo = i + 1;
       if (declLines.has(lineNo)) continue;
@@ -1306,31 +1538,32 @@ function buildEdges(root, files, importEdges, resolveImport) {
         if (name.length < MIN_REF_NAME || !defsByName.has(name)) continue;
         const memberOf = strict ? /([A-Za-z_$][\w$]*)\s*\.\s*$/.exec(line.slice(0, m.index))?.[1] : void 0;
         const target = bind(name, memberOf);
-        if (!target || target === from) continue;
+        if (!target || target.id === from) continue;
         const after = line.slice(m.index + name.length);
-        push(from, target, /^\s*\(/.test(after) ? "calls" : "references");
+        const calls = !DOC_LANGS.has(f.lang) && /^\s*\(/.test(after);
+        push(from, target.id, calls ? "calls" : "references", target.inferred);
       }
     }
   }
   return { edges, bodies };
 }
-function indexBodies(out, path, spans, lines) {
+function indexBodies(out, path, spans, lines, limit) {
   const covered = new Uint8Array(lines.length + 1);
   for (const s of spans) {
     const text = lines.slice(s.line - 1, s.endLine).join("\n");
     for (let l = s.line; l <= Math.min(s.endLine, lines.length); l++) covered[l] = 1;
-    const bag = topTokens(text);
+    const bag = topTokens(text, limit);
     if (bag.length) out.push([s.id, bag]);
   }
   const residual = [];
   for (let l = 1; l <= lines.length; l++) if (!covered[l]) residual.push(lines[l - 1]);
-  const fileBag = topTokens(residual.join("\n"));
+  const fileBag = topTokens(residual.join("\n"), limit);
   if (fileBag.length) out.push([path, fileBag]);
 }
-function topTokens(text) {
+function topTokens(text, limit) {
   const m = /* @__PURE__ */ new Map();
   for (const t of tokenize(text)) m.set(t, (m.get(t) ?? 0) + 1);
-  return [...m.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, MAX_BODY_TOKENS);
+  return [...m.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, limit);
 }
 function isManagedPath(dir) {
   const managed = resolve3(join5(enigmaHome(), ".enigma"));
@@ -1548,17 +1781,18 @@ function codeGraphAvailable() {
 function codeGraphStatus() {
   return { enabled: readConfig().config.codeGraph, available: true, projects: listProjects().length };
 }
-var GRAPH_VERSION, RESOLVE_EXTS, LANG_EXTS, LANG_INDEX, MIN_REF_NAME, MAX_EDGES, LANG_FAMILY, INDEX_NAMES, MODULE_ROOTS, MODULE_SEPARATOR, BARE_IS_PACKAGE, EXT_ORDER, INDEX_ORDER, MAX_BODY_TOKENS, ROOT_MARKERS, MAX_ROOT_WALK;
+var GRAPH_VERSION, RESOLVE_EXTS, LANG_EXTS, LANG_INDEX, MIN_REF_NAME, MIN_DOC_MENTION, MAX_EDGES, LANG_FAMILY, INDEX_NAMES, MODULE_ROOTS, MODULE_SEPARATOR, BARE_IS_PACKAGE, EXT_ORDER, INDEX_ORDER, MAX_BODY_TOKENS, MAX_DOC_BODY_TOKENS, ROOT_MARKERS, MAX_ROOT_WALK;
 var init_codegraph = __esm({
   "src/codegraph.ts"() {
     "use strict";
     init_util();
     init_config();
     init_codegraph_rank();
+    init_codegraph_extract_docs();
     init_codegraph_extract();
     init_codegraph_extract();
     init_codegraph_types();
-    GRAPH_VERSION = 4;
+    GRAPH_VERSION = 5;
     RESOLVE_EXTS = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs", ".py", ".go", ".rs", ".java", ".rb", ".php", ".cs", ".kt"];
     LANG_EXTS = {
       ts: [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"],
@@ -1574,6 +1808,7 @@ var init_codegraph = __esm({
     };
     LANG_INDEX = { python: ["__init__"], go: ["mod"], rust: ["mod"] };
     MIN_REF_NAME = 3;
+    MIN_DOC_MENTION = 4;
     MAX_EDGES = 4e5;
     LANG_FAMILY = {
       ts: "js",
@@ -1590,6 +1825,7 @@ var init_codegraph = __esm({
     EXT_ORDER = orders(RESOLVE_EXTS, LANG_EXTS);
     INDEX_ORDER = orders(INDEX_NAMES, LANG_INDEX);
     MAX_BODY_TOKENS = 80;
+    MAX_DOC_BODY_TOKENS = 24;
     ROOT_MARKERS = [".git", "package.json", "go.mod", "pyproject.toml", "Cargo.toml", "pom.xml", "composer.json"];
     MAX_ROOT_WALK = 6;
   }
@@ -1822,11 +2058,11 @@ ${result.note}` : structural.fallthrough;
 }
 function adjacency(edges, direction) {
   const adj = /* @__PURE__ */ new Map();
-  for (const [source, target, rel] of edges) {
+  for (const [source, target, rel, guess] of edges) {
     if (!WALK_RELATIONS.has(rel)) continue;
     const key = direction === "in" ? target : source;
     const other = direction === "in" ? source : target;
-    const entry = { other, relation: rel };
+    const entry = { other, relation: rel, inferred: guess === 1 };
     const arr = adj.get(key);
     if (arr) arr.push(entry);
     else adj.set(key, [entry]);
@@ -1855,13 +2091,13 @@ function codeGraphTrace(symbol, opts = {}) {
   for (let d = 1; d <= depth && frontier.length; d++) {
     const next = [];
     for (const current of frontier) {
-      for (const { other, relation } of adj.get(current) ?? []) {
+      for (const { other, relation, inferred } of adj.get(current) ?? []) {
         if (visited.has(other)) continue;
         visited.add(other);
         const node = loaded.byId.get(other);
         if (!node) continue;
         if (inPrefix !== void 0 && !underPrefix(node.path, inPrefix)) continue;
-        hits.push({ id: other, name: node.name, kind: node.kind, path: node.path, line: node.line, relation, depth: d });
+        hits.push({ id: other, name: node.name, kind: node.kind, path: node.path, line: node.line, relation, depth: d, ...inferred ? { inferred } : {} });
         next.push(other);
       }
     }
@@ -1900,8 +2136,8 @@ function dirKey(path, depth) {
   const segments = path.split("/");
   return segments.slice(0, Math.min(depth, segments.length)).join("/");
 }
-function topHubs(nodes, deg, cap) {
-  return nodes.map((n) => ({ name: n.name, kind: n.kind, path: n.path, line: n.line, inDegree: deg.get(n.id) ?? 0 })).filter((h) => h.inDegree > 0).sort((a, b) => b.inDegree - a.inDegree || a.name.localeCompare(b.name) || a.path.localeCompare(b.path)).slice(0, cap);
+function topHubs(nodes, deg, cap2) {
+  return nodes.map((n) => ({ name: n.name, kind: n.kind, path: n.path, line: n.line, inDegree: deg.get(n.id) ?? 0 })).filter((h) => h.inDegree > 0).sort((a, b) => b.inDegree - a.inDegree || a.name.localeCompare(b.name) || a.path.localeCompare(b.path)).slice(0, cap2);
 }
 function codeGraphMap(opts = {}) {
   const loaded = load(opts);
@@ -2129,7 +2365,7 @@ ${r.note ?? empty}
   const lines = [head, ""];
   lines.push(`defined at: ${r.matched.map((m) => `${m.path}:${m.line}`).join(", ")}`, "");
   for (const h of r.hits) {
-    lines.push(`- ${h.name} - ${h.kind} - ${h.path}:${h.line} - ${h.relation}${r.depth > 1 ? ` - depth ${h.depth}` : ""}`);
+    lines.push(`- ${h.name} - ${h.kind} - ${h.path}:${h.line} - ${h.relation}${h.inferred ? " (inferred)" : ""}${r.depth > 1 ? ` - depth ${h.depth}` : ""}`);
   }
   lines.push("", `${r.hits.length} node${r.hits.length === 1 ? "" : "s"}.`);
   return `${lines.join("\n")}
@@ -2252,6 +2488,295 @@ var init_codegraph_format = __esm({
   }
 });
 
+// src/codegraph-cluster.ts
+function localMoves(level, totalWeight) {
+  const { nodes, adj, selfLoops } = level;
+  const degree = new Array(nodes).fill(0);
+  for (let i = 0; i < nodes; i++) {
+    let d = selfLoops[i] * 2;
+    for (const w of adj[i].values()) d += w;
+    degree[i] = d;
+  }
+  const comm = Array.from({ length: nodes }, (_, i) => i);
+  const commDegree = degree.slice();
+  const m2 = totalWeight * 2;
+  for (let sweep = 0; sweep < MAX_SWEEPS; sweep++) {
+    let moved = false;
+    for (let i = 0; i < nodes; i++) {
+      const current = comm[i];
+      const toComm = /* @__PURE__ */ new Map();
+      for (const [j, w] of adj[i]) toComm.set(comm[j], (toComm.get(comm[j]) ?? 0) + w);
+      commDegree[current] -= degree[i];
+      let best = current;
+      let bestGain = (toComm.get(current) ?? 0) - commDegree[current] * degree[i] / m2;
+      for (const [c, w] of [...toComm.entries()].sort((a, b) => a[0] - b[0])) {
+        const gain = w - commDegree[c] * degree[i] / m2;
+        if (gain > bestGain + 1e-12) {
+          best = c;
+          bestGain = gain;
+        }
+      }
+      commDegree[best] += degree[i];
+      if (best !== current) {
+        comm[i] = best;
+        moved = true;
+      }
+    }
+    if (!moved) break;
+  }
+  return comm;
+}
+function clusterFiles(files, links) {
+  const sorted = [...new Set(files)].sort();
+  const index = new Map(sorted.map((f, i) => [f, i]));
+  let level = { nodes: sorted.length, adj: sorted.map(() => /* @__PURE__ */ new Map()), selfLoops: new Array(sorted.length).fill(0) };
+  let totalWeight = 0;
+  for (const [a, b, w] of links) {
+    const i = index.get(a);
+    const j = index.get(b);
+    if (i === void 0 || j === void 0 || w <= 0) continue;
+    totalWeight += w;
+    if (i === j) {
+      level.selfLoops[i] += w;
+      continue;
+    }
+    level.adj[i].set(j, (level.adj[i].get(j) ?? 0) + w);
+    level.adj[j].set(i, (level.adj[j].get(i) ?? 0) + w);
+  }
+  let membership = sorted.map((_, i) => i);
+  if (totalWeight === 0) return new Map(sorted.map((f, i) => [f, i]));
+  for (let l = 0; l < MAX_LEVELS; l++) {
+    const comm = localMoves(level, totalWeight);
+    const ids = /* @__PURE__ */ new Map();
+    for (const c of comm) if (!ids.has(c)) ids.set(c, ids.size);
+    if (ids.size === level.nodes) break;
+    membership = membership.map((c) => ids.get(comm[c]));
+    const next = { nodes: ids.size, adj: Array.from({ length: ids.size }, () => /* @__PURE__ */ new Map()), selfLoops: new Array(ids.size).fill(0) };
+    for (let i = 0; i < level.nodes; i++) {
+      const ci = ids.get(comm[i]);
+      next.selfLoops[ci] += level.selfLoops[i];
+      for (const [j, w] of level.adj[i]) {
+        const cj = ids.get(comm[j]);
+        if (ci === cj) {
+          if (i < j) next.selfLoops[ci] += w;
+        } else next.adj[ci].set(cj, (next.adj[ci].get(cj) ?? 0) + w);
+      }
+    }
+    level = next;
+  }
+  const members = /* @__PURE__ */ new Map();
+  sorted.forEach((f, i) => {
+    const c = membership[i];
+    const list = members.get(c);
+    if (list) list.push(f);
+    else members.set(c, [f]);
+  });
+  const order = [...members.entries()].sort((a, b) => b[1].length - a[1].length || a[1][0].localeCompare(b[1][0]));
+  const out = /* @__PURE__ */ new Map();
+  order.forEach(([, list], rank) => {
+    for (const f of list) out.set(f, rank);
+  });
+  return out;
+}
+var MAX_SWEEPS, MAX_LEVELS;
+var init_codegraph_cluster = __esm({
+  "src/codegraph-cluster.ts"() {
+    "use strict";
+    MAX_SWEEPS = 20;
+    MAX_LEVELS = 6;
+  }
+});
+
+// src/codegraph-report.ts
+var codegraph_report_exports = {};
+__export(codegraph_report_exports, {
+  codeGraphReport: () => codeGraphReport,
+  formatReport: () => formatReport
+});
+function areaLabel(paths) {
+  const dirs = paths.map((p) => p.split("/").slice(0, -1));
+  let label = [];
+  for (let depth = 1; ; depth++) {
+    const counts2 = /* @__PURE__ */ new Map();
+    for (const d of dirs) if (d.length >= depth) {
+      const k = d.slice(0, depth).join("/");
+      counts2.set(k, (counts2.get(k) ?? 0) + 1);
+    }
+    const top2 = [...counts2.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))[0];
+    if (!top2 || top2[1] / paths.length < LABEL_SHARE) break;
+    label = top2[0].split("/");
+  }
+  if (label.length) return `${label.join("/")}/`;
+  if (paths.length === 1) return paths[0];
+  const first = /* @__PURE__ */ new Map();
+  for (const d of dirs) {
+    const k = d[0] ?? "(root)";
+    first.set(k, (first.get(k) ?? 0) + 1);
+  }
+  const [top] = [...first.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))[0];
+  return `${top}/ (mixed)`;
+}
+function codeGraphReport(opts = {}) {
+  const graph = loadFreshGraph(opts.project, opts.refresh ?? true);
+  if (!graph) return null;
+  const nodes = graphNodes(graph);
+  const byId = new Map(nodes.map((n) => [n.id, n]));
+  const langByPath = new Map(graph.files.map((f) => [f.path, f.lang]));
+  const own = graph.files.filter((f) => !isForeignPath(f.path));
+  const codePaths = new Set(own.filter((f) => isCodeLang(f.lang)).map((f) => f.path));
+  const docPaths = new Set(own.filter((f) => f.lang === "markdown").map((f) => f.path));
+  const weights = /* @__PURE__ */ new Map();
+  const directed = /* @__PURE__ */ new Map();
+  const docRefs = /* @__PURE__ */ new Map();
+  for (const e of graph.edges) {
+    if (e[2] === "contains") continue;
+    const a = byId.get(e[0])?.path;
+    const b = byId.get(e[1])?.path;
+    if (!a || !b || a === b) continue;
+    if (docPaths.has(a) && codePaths.has(b)) {
+      const refs = docRefs.get(a) ?? /* @__PURE__ */ new Map();
+      refs.set(b, (refs.get(b) ?? 0) + 1);
+      docRefs.set(a, refs);
+      continue;
+    }
+    if (!codePaths.has(a) || !codePaths.has(b)) continue;
+    const key = a < b ? `${a}
+${b}` : `${b}
+${a}`;
+    weights.set(key, (weights.get(key) ?? 0) + 1);
+    directed.set(`${a}
+${b}`, (directed.get(`${a}
+${b}`) ?? 0) + 1);
+  }
+  const links = [...weights.entries()].map(([k, w]) => {
+    const [a, b] = k.split("\n");
+    return [a, b, w];
+  });
+  const areaOf = clusterFiles([...codePaths], links);
+  const members = /* @__PURE__ */ new Map();
+  for (const [path, area] of areaOf) {
+    const list = members.get(area);
+    if (list) list.push(path);
+    else members.set(area, [path]);
+  }
+  const deg = inDegree(graph.edges, true);
+  const maxAreas = opts.maxAreas ?? DEFAULT_MAX_AREAS;
+  const ranked = [...members.entries()].filter(([, paths]) => paths.length >= 2).sort((a, b) => b[1].length - a[1].length || a[0] - b[0]);
+  const symbolsOf = /* @__PURE__ */ new Map();
+  for (const n of nodes) {
+    if (n.kind === "file" || isTestPath(n.path)) continue;
+    const area = areaOf.get(n.path);
+    if (area === void 0) continue;
+    const list = symbolsOf.get(area);
+    if (list) list.push(n);
+    else symbolsOf.set(area, [n]);
+  }
+  const keys = /* @__PURE__ */ new Map();
+  const keyOf = (area) => {
+    let key = keys.get(area);
+    if (key) return key;
+    key = (symbolsOf.get(area) ?? []).map((n) => ({ name: n.name, kind: n.kind, path: n.path, line: n.line, inDegree: deg.get(n.id) ?? 0 })).filter((sym) => sym.inDegree > 0).sort((a, b) => b.inDegree - a.inDegree || a.name.localeCompare(b.name)).slice(0, KEY_SYMBOLS);
+    keys.set(area, key);
+    return key;
+  };
+  const base = new Map(ranked.map(([area, paths]) => [area, areaLabel(paths)]));
+  const seenLabel = /* @__PURE__ */ new Map();
+  for (const label of base.values()) seenLabel.set(label, (seenLabel.get(label) ?? 0) + 1);
+  const labels = new Map([...base.entries()].map(([area, label]) => {
+    if ((seenLabel.get(label) ?? 0) < 2) return [area, label];
+    const around = keyOf(area)[0]?.name;
+    return [area, around ? `${label} ~ ${around}` : label];
+  }));
+  const docsOf = /* @__PURE__ */ new Map();
+  for (const [doc, refs] of docRefs) {
+    const byArea = /* @__PURE__ */ new Map();
+    for (const [code, w] of refs) {
+      const area = areaOf.get(code);
+      if (area !== void 0) byArea.set(area, (byArea.get(area) ?? 0) + w);
+    }
+    const best = [...byArea.entries()].sort((a, b) => b[1] - a[1] || a[0] - b[0])[0];
+    if (!best) continue;
+    const list = docsOf.get(best[0]) ?? [];
+    list.push(doc);
+    docsOf.set(best[0], list);
+  }
+  const areas = ranked.slice(0, maxAreas).map(([area, paths]) => {
+    const inArea = new Set(paths);
+    const out = /* @__PURE__ */ new Map();
+    for (const [key, w] of directed) {
+      const [a, b] = key.split("\n");
+      if (!inArea.has(a) || inArea.has(b)) continue;
+      const target = areaOf.get(b);
+      if (target !== void 0 && target !== area && labels.has(target)) out.set(target, (out.get(target) ?? 0) + w);
+    }
+    return {
+      label: labels.get(area),
+      files: paths.length,
+      languages: [...new Set(paths.map((p) => langByPath.get(p)).filter((l) => !!l))].sort(),
+      keySymbols: keyOf(area),
+      docs: (docsOf.get(area) ?? []).sort((a, b) => a.split("/").length - b.split("/").length || a.localeCompare(b)).slice(0, AREA_DOCS),
+      dependsOn: [...out.entries()].sort((a, b) => b[1] - a[1] || a[0] - b[0]).slice(0, DEPENDS_ON).map(([t]) => labels.get(t))
+    };
+  });
+  const titleOf = /* @__PURE__ */ new Map();
+  for (const n of nodes) if (n.kind === "section" && !titleOf.has(n.path)) titleOf.set(n.path, n.name);
+  const docFiles = own.filter((f) => f.lang === "markdown").sort((a, b) => a.path.split("/").length - b.path.split("/").length || a.path.localeCompare(b.path));
+  const maxDocs = opts.maxDocs ?? DEFAULT_MAX_DOCS;
+  return {
+    name: graph.name,
+    totals: {
+      files: graph.files.length,
+      symbols: nodes.length - graph.files.length,
+      edges: graph.edges.length,
+      inferred: graph.edges.filter((e) => e[3] === 1).length,
+      docs: docFiles.length
+    },
+    areas,
+    moreAreas: Math.max(0, ranked.length - areas.length),
+    docs: docFiles.slice(0, maxDocs).map((f) => ({ path: f.path, title: titleOf.get(f.path) ?? "" })),
+    moreDocs: Math.max(0, docFiles.length - maxDocs),
+    foreign: graph.files.length - own.length,
+    truncated: graph.truncated
+  };
+}
+function formatReport(r) {
+  const t = r.totals;
+  const lines = [`repo report - ${r.name} - ${t.files} files (${t.docs} docs) - ${t.symbols} symbols - ${t.edges} edges (${t.inferred} inferred by name)`];
+  if (r.foreign) lines.push(`${r.foreign} file(s) of vendored, reference or example material are left out of the areas below.`);
+  lines.push("", "areas (files that depend on each other, largest first):");
+  for (const a of r.areas) {
+    lines.push(`- ${a.label} - ${a.files} files${a.languages.length ? ` - ${a.languages.join(", ")}` : ""}`);
+    if (a.keySymbols.length) lines.push(`    key: ${a.keySymbols.map((s) => `${s.name} (${s.path}:${s.line}, ${s.inDegree} in)`).join(", ")}`);
+    if (a.dependsOn.length) lines.push(`    uses: ${a.dependsOn.join(", ")}`);
+    if (a.docs.length) lines.push(`    docs: ${a.docs.join(", ")}`);
+  }
+  if (r.moreAreas) lines.push(`  +${r.moreAreas} smaller area(s)`);
+  if (r.docs.length) {
+    lines.push("", "docs:");
+    for (const d of r.docs) lines.push(`- ${d.path}${d.title ? ` - ${d.title}` : ""}`);
+    if (r.moreDocs) lines.push(`  +${r.moreDocs} more (enigma_codegraph_ask finds them by topic)`);
+  }
+  if (r.truncated) lines.push("", "The index hit its size cap; some files are not covered.");
+  return `${lines.join("\n")}
+`;
+}
+var DEFAULT_MAX_AREAS, DEFAULT_MAX_DOCS, KEY_SYMBOLS, AREA_DOCS, DEPENDS_ON, LABEL_SHARE;
+var init_codegraph_report = __esm({
+  "src/codegraph-report.ts"() {
+    "use strict";
+    init_codegraph();
+    init_codegraph_rank();
+    init_codegraph_extract();
+    init_codegraph_cluster();
+    DEFAULT_MAX_AREAS = 8;
+    DEFAULT_MAX_DOCS = 12;
+    KEY_SYMBOLS = 3;
+    AREA_DOCS = 2;
+    DEPENDS_ON = 2;
+    LABEL_SHARE = 0.6;
+  }
+});
+
 // src/codegraph-hook.ts
 import { homedir as homedir3 } from "os";
 
@@ -2388,14 +2913,17 @@ async function sessionStart(dir) {
     "  - enigma_codegraph_skeleton: a file's whole API surface, no bodies.",
     "  - enigma_codegraph_grep: every occurrence, grouped by enclosing symbol - when you need them ALL, not the top matches."
   ].join("\n");
-  const map = q.codeGraphMap({ project, refresh: false, maxDirs: 8 });
+  const rep = await Promise.resolve().then(() => (init_codegraph_report(), codegraph_report_exports));
+  const report = rep.codeGraphReport({ project, refresh: false });
+  const map = report ? null : q.codeGraphMap({ project, refresh: false, maxDirs: 8 });
+  const body = report ? rep.formatReport(report) : map ? fmt.formatMap(map) : "";
   const fresh = q.codeGraphCheck(project);
   const stale = fresh && fresh.stale > 0 ? `
 ${fresh.stale} file(s) changed since the last index; the next query refreshes them.` : "";
-  writeStatuslineSnapshot(projectRoot(cg, project, dir), map?.totals.symbols ?? 0, fresh?.stale ?? 0);
-  emit("SessionStart", map ? `${directive}
+  writeStatuslineSnapshot(projectRoot(cg, project, dir), report?.totals.symbols ?? map?.totals.symbols ?? 0, fresh?.stale ?? 0);
+  emit("SessionStart", body ? `${directive}
 
-${fmt.formatMap(map).trimEnd()}${stale}` : directive);
+${body.trimEnd()}${stale}` : directive);
 }
 function coveringProject(cg, dir) {
   const project = cg.findProjectForCwd(dir);