@geml/geml 1.0.0 → 1.1.1

package/codemap/emit.mjs

@@ -0,0 +1,361 @@
+// geml-code-graph emit — exchange-format symbols/edges → the codemap document
+// tree of docs/DESIGN-codemap-delta.md (§4–6) / docs/codemap-profile.md:
+//   one .geml per container (module|dir|file), each with EXACTLY ONE meta
+//   (module/src/entry/resolution-default), empty-body `code` blocks per method
+//   (src=path#Lx-y, anchor=; symbol-level classes .leaf/.test), and up to three
+//   CSV edge tables: #calls (out), #called-by (in, aggregated), #unresolved
+//   (blind spots, hidden). Plus index.geml (aggregates) and name-lookup.json.
+//
+// Generated documents are PURE DATA: no diagram blocks (a codemap-aware
+// renderer offers the layered-flow view; embedding elsewhere uses
+// `=== diagram {format=geml-code-graph src=…}`).
+//
+// Emission is deterministic: stable sort orders everywhere; a file is only
+// written when its bytes changed (mtime = "what a change touched").
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { dirname, join, posix } from "node:path";
+import { buildNormalizer } from "./normalize.mjs";
+
+const esc = (s) => String(s).replace(/`/g, "'");
+const attrVal = (s) => String(s).replace(/"/g, "'");
+// Plain-text cells: no commas/newlines (CSV), and no square brackets — table
+// cells are inline-parsed, so `f[i](&x)` would otherwise read as a LINK with an
+// unresolvable target. Brackets become parens: still readable, never markup.
+const csvCell = (s) => String(s).replace(/[,\r\n]/g, " ").replace(/\[/g, "(").replace(/\]/g, ")").trim();
+const sha6 = (s, len = 6) => createHash("sha256").update(s, "utf8").digest("hex").slice(0, len);
+
+// Test territory (path conventions; the avowed heuristic of GEP-0002).
+const TEST_DIR = /(^|\/)(test|tests|testing|__tests__|spec|specs)(\/|$)/i;
+const TEST_FILE = /(^test_|^tests?\.|[._-]tests?\.|\.test\.|\.spec\.)/i;
+const isTestPath = (p) => {
+  p = String(p).replace(/\\/g, "/");
+  return TEST_DIR.test(p) || TEST_FILE.test(p.slice(p.lastIndexOf("/") + 1));
+};
+
+const slugName = (name) => {
+  let s = String(name).replace(/[^A-Za-z0-9_-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "").slice(0, 32);
+  if (!/^[A-Za-z]/.test(s)) s = "s" + s;
+  return s;
+};
+const slugPath = (p) => (p === "" || p === "(root)" ? "root" : p.replace(/\//g, "--").replace(/[^A-Za-z0-9_.-]/g, "-"));
+const dirOf = (rel) => { const i = rel.lastIndexOf("/"); return i < 0 ? "(root)" : rel.slice(0, i); };
+const topOf = (rel) => { const i = rel.indexOf("/"); return i < 0 ? "(root)" : rel.slice(0, i); };
+
+export function emit({ symbols, edges, outDir, buildDir, repoName, container = "dir", commit, root }) {
+  const byAnchor = new Map(symbols.map((s) => [s.anchor, s]));
+  const methods = symbols.filter((s) => s.kind === "Function" || s.kind === "Test");
+  const files = symbols.filter((s) => s.kind === "File");
+
+  // ---- containers ----
+  const containerOf = (s) =>
+    container === "file" ? s.file : container === "module" ? topOf(s.file) : dirOf(s.file);
+  // Display-path normalisation: strip each module's shared ceremony prefix so
+  // `module=`/doc names read as the real structure. Applies in every container
+  // mode (dir and file) — a file-mode container path carries the same source
+  // roots (geml-parser/src/render.ts -> geml-parser/render.ts). Grouping still
+  // keys on the TRUE path (containerOf) and `src=` stays the true path — only
+  // the displayed module path shortens. root may be absent (older callers / crg
+  // tier): then displayOf is the identity.
+  const normMap = root ? buildNormalizer(root, methods.map(containerOf), { repoName, fileMode: container === "file" }) : new Map();
+  const displayOf = (name) => normMap.get(name) ?? name;
+  const containers = new Map(); // name -> { docName, methods[], files[] }
+  const taken = new Set(["index.geml"]);
+  const containerFor = (name) => {
+    if (!containers.has(name)) {
+      let doc = `${slugPath(displayOf(name))}.geml`;
+      for (let i = 2; taken.has(doc); i++) doc = `${slugPath(displayOf(name))}-${i}.geml`;
+      taken.add(doc);
+      containers.set(name, { docName: doc, methods: [], files: [] });
+    }
+    return containers.get(name);
+  };
+  for (const s of methods) containerFor(containerOf(s)).methods.push(s);
+  for (const s of files) {
+    const c = containers.get(containerOf(s));
+    if (c) c.files.push(s); // only files that actually host methods
+  }
+  const docOfAnchor = new Map();
+  for (const [name, c] of containers) {
+    for (const s of [...c.methods, ...c.files]) docOfAnchor.set(s.anchor, c.docName);
+  }
+
+  // ---- block ids: short name when unique in its doc, else name-<sha6(anchor)> ----
+  const idOf = new Map(); // anchor -> id
+  for (const [, c] of containers) {
+    const byName = new Map();
+    for (const s of [...c.methods, ...c.files]) {
+      const base = slugName(s.name);
+      if (!byName.has(base)) byName.set(base, []);
+      byName.get(base).push(s);
+    }
+    for (const [base, list] of byName) {
+      if (list.length === 1) { idOf.set(list[0].anchor, base); continue; }
+      // Escalate hash length only when the default 6 hex chars actually collide
+      // within this name group — keeps ids short in the common case.
+      let len = 6;
+      let ids;
+      for (;;) {
+        ids = list.map((s) => `${base}-${sha6(s.anchor, len)}`);
+        if (new Set(ids).size === ids.length) break;
+        // sha256 hex is 64 chars — beyond that only IDENTICAL anchors can
+        // still collide, which is a caller bug (build.mjs dedupes anchors):
+        // fail loudly instead of escalating forever.
+        if (len >= 64) throw new Error(`emit: duplicate anchors in name group "${base}" — anchors must be unique`);
+        len += 2;
+      }
+      list.forEach((s, i) => idOf.set(s.anchor, ids[i]));
+    }
+  }
+
+  // ---- edges (stage A: the `calls` relation only) ----
+  const calls = edges.filter((e) => e.kind === "calls");
+  const outCalls = new Map();   // anchor -> total outgoing (incl. unresolved) — leaf rule
+  const inBySym = new Map();    // target anchor -> [{fromAnchor, kind, site, confidence}]
+  const outBySym = new Map();   // source anchor -> [{toAnchor, kind, confidence}] resolved
+  const unresBySym = new Map(); // source anchor -> Set(to_text)
+  const addIn = (target, rec) => {
+    if (!byAnchor.has(target)) return;
+    if (!inBySym.has(target)) inBySym.set(target, []);
+    inBySym.get(target).push(rec);
+  };
+  for (const e of calls) {
+    if (!docOfAnchor.has(e.from)) continue;
+    outCalls.set(e.from, (outCalls.get(e.from) ?? 0) + 1);
+    if (e.to !== undefined && docOfAnchor.has(e.to)) {
+      if (!outBySym.has(e.from)) outBySym.set(e.from, []);
+      const conf = e.confidence === "high" || !e.confidence ? "" : e.confidence;
+      outBySym.get(e.from).push({ to: e.to, kind: "call", confidence: conf });
+      addIn(e.to, { from: e.from, kind: "call", site: e.site, confidence: conf });
+      for (const c of e.candidates ?? []) {
+        if (!docOfAnchor.has(c)) continue;
+        outBySym.get(e.from).push({ to: c, kind: "candidate", confidence: "" });
+        addIn(c, { from: e.from, kind: "candidate", site: e.site, confidence: "" });
+      }
+    } else if (e.to_text) {
+      if (!unresBySym.has(e.from)) unresBySym.set(e.from, new Set());
+      unresBySym.get(e.from).add(e.to_text);
+    }
+  }
+  const isLeaf = (s) =>
+    (s.kind === "Function" || s.kind === "Test") &&
+    !(outCalls.get(s.anchor) > 0) && (inBySym.get(s.anchor)?.length ?? 0) >= 1;
+  // Bean-style accessors that also call nothing: pure noise in a flow view.
+  // Marked so renderers can hide them by default; the edge tables keep them.
+  const isAccessor = (s) => isLeaf(s) && /^(get|set|is)(?![a-z])/.test(s.name);
+
+  // ---- entry: called from outside its container, or an app entry (main) ----
+  const isEntry = (s) => {
+    if (s.entry) return true;
+    const doc = docOfAnchor.get(s.anchor);
+    return (inBySym.get(s.anchor) ?? []).some((r) => docOfAnchor.get(r.from) !== doc);
+  };
+
+  // A reference to `anchor` as seen from `fromDoc`.
+  const refTo = (anchor, fromDoc) => {
+    const doc = docOfAnchor.get(anchor);
+    const id = idOf.get(anchor);
+    return doc === fromDoc ? `#${id}` : `${posix.relative(posix.dirname(fromDoc), doc)}#${id}`;
+  };
+
+  // ---- write helper: deterministic, only-on-change ----
+  const stats = { docs: 0, written: 0, bytes: 0 };
+  const allDocs = [];
+  const writtenDocs = [];
+  const writeIfChanged = (relPath, content) => {
+    const p = join(outDir, relPath);
+    mkdirSync(dirname(p), { recursive: true });
+    stats.docs++;
+    stats.bytes += content.length;
+    if (relPath.endsWith(".geml")) allDocs.push(relPath);
+    if (existsSync(p) && readFileSync(p, "utf8") === content) return false;
+    writeFileSync(p, content);
+    stats.written++;
+    if (relPath.endsWith(".geml")) writtenDocs.push(relPath);
+    return true;
+  };
+
+  const RESOLUTION_DEFAULT = symbols.some((s) => s.resolution === "cpg") ? "cpg" : "heuristic";
+  const csv = (id, columns, rows, extraAttrs = "") => {
+    if (!rows.length) return null; // empty tables are not generated
+    // Column width by loop, not Math.max(...spread) — a spread call over a
+    // repo-scale table's rows blows the argument limit (same failure class
+    // as the build.mjs merge).
+    const widths = columns.map((c, i) => {
+      let w = c.length;
+      for (const r of rows) { const l = String(r[i] ?? "").length; if (l > w) w = l; }
+      return w;
+    });
+    const line = (cells) => cells.map((v, i) =>
+      i === cells.length - 1 ? String(v ?? "") : (String(v ?? "") + ",").padEnd(widths[i] + 2)).join("").replace(/\s+$/, "");
+    return `=== table {#${id} format=csv${extraAttrs}}\n${line(columns)}\n${rows.map(line).join("\n")}\n===\n`;
+  };
+
+  // ---- container documents ----
+  const indexRows = [];
+  const appEntries = [];
+  for (const [name, c] of [...containers.entries()].sort((a, b) => a[1].docName.localeCompare(b[1].docName))) {
+    const doc = c.docName;
+    c.methods.sort((a, b) => a.file.localeCompare(b.file) || (a.line_start ?? 0) - (b.line_start ?? 0) || a.anchor.localeCompare(b.anchor));
+
+    const entries = c.methods.filter(isEntry);
+    for (const s of c.methods) if (s.entry) appEntries.push(s.anchor);
+    const testCount = c.methods.filter((s) => isTestPath(s.file)).length;
+    // src= = the TRUE source directory (real path, for locating code); module=
+    // and the heading = the normalised DISPLAY path (ceremony stripped).
+    const srcDir = container === "file" ? name : name === "(root)" ? "" : `${name}/`;
+    const disp = displayOf(name);
+    const dispLabel = disp === "(root)" ? "root" : disp;
+
+    const chunks = [
+      "=== meta\n"
+      + `module = ${csvCell(dispLabel)}\n`
+      + (srcDir ? `src = ${csvCell(srcDir)}\n` : "")
+      + (entries.length ? `entry = ${entries.map((s) => `#${idOf.get(s.anchor)}`).join(" ")}\n` : "")
+      + `resolution-default = ${RESOLUTION_DEFAULT}\n===\n`,
+      `# ${esc(dispLabel)}\n`,
+    ];
+
+    // method blocks, grouped under a `##` file heading when the container spans
+    // several files (containment = document structure)
+    const byFile = new Map();
+    for (const s of c.methods) {
+      if (!byFile.has(s.file)) byFile.set(s.file, []);
+      byFile.get(s.file).push(s);
+    }
+    const multiFile = byFile.size > 1;
+    const fileSymByPath = new Map(c.files.map((f) => [f.file, f]));
+    for (const [file, list] of [...byFile.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+      if (multiFile) {
+        const fileSym = fileSymByPath.get(file);
+        const base = file.split("/").pop();
+        chunks.push(fileSym ? `## ${esc(base)} {#${idOf.get(fileSym.anchor)}}\n` : `## ${esc(base)}\n`);
+      }
+      for (const s of list) {
+        const cls = `${isTestPath(s.file) ? " .test" : ""}${isLeaf(s) ? " .leaf" : ""}${isAccessor(s) ? " .accessor" : ""}${s.flow_crit ? " .flow-entry" : ""}`;
+        const src = `${s.file}${s.line_start !== undefined ? `#L${s.line_start}-${s.line_end ?? s.line_start}` : ""}`;
+        // The display name rides along whenever id sanitisation changed it
+        // ("RenderCtx.block" -> id RenderCtx-block): renderers label nodes
+        // with the real name, ids stay reference-grammar clean.
+        const id = idOf.get(s.anchor);
+        const nameAttr = s.name !== id ? ` name="${attrVal(s.name)}"` : "";
+        chunks.push(`=== code {#${id}${cls}${nameAttr} src=${attrVal(src)} anchor="${attrVal(s.anchor)}"}\n===\n`);
+      }
+    }
+
+    // #calls
+    const callRows = [];
+    for (const s of c.methods) {
+      for (const r of (outBySym.get(s.anchor) ?? [])
+        .sort((x, y) => (x.kind === y.kind ? refTo(x.to, doc).localeCompare(refTo(y.to, doc)) : 0))) {
+        callRows.push([`#${idOf.get(s.anchor)}`, refTo(r.to, doc), r.kind, r.confidence]);
+      }
+    }
+    const callsTable = csv("calls", ["from", "to", "kind", "confidence"], callRows);
+    if (callsTable) chunks.push(callsTable);
+
+    // #called-by (aggregated in-edges)
+    const inRows = [];
+    for (const s of c.methods) {
+      const recs = (inBySym.get(s.anchor) ?? [])
+        .sort((x, y) => (x.site?.file ?? "").localeCompare(y.site?.file ?? "") || (x.site?.line ?? 0) - (y.site?.line ?? 0) || x.from.localeCompare(y.from));
+      for (const r of recs) {
+        const site = r.site ? `${r.site.file}:${r.site.line}` : "";
+        inRows.push([refTo(r.from, doc), `#${idOf.get(s.anchor)}`, r.kind, csvCell(site)]);
+      }
+    }
+    const inTable = csv("called-by", ["from", "to", "kind", "site"], inRows);
+    if (inTable) chunks.push(inTable);
+
+    // #unresolved (hidden)
+    const unRows = [];
+    for (const s of c.methods) {
+      for (const t of [...(unresBySym.get(s.anchor) ?? [])].sort()) {
+        unRows.push([`#${idOf.get(s.anchor)}`, csvCell(t)]);
+      }
+    }
+    const unTable = csv("unresolved", ["from", "to"], unRows, " hidden");
+    if (unTable) chunks.push(unTable);
+
+    writeIfChanged(doc, chunks.join("\n"));
+    indexRows.push({ module: dispLabel, doc, methods: c.methods.length, entries: entries.length, tests: testCount });
+  }
+
+  // ---- index.geml ----
+  appEntries.sort((a, b) => docOfAnchor.get(a).localeCompare(docOfAnchor.get(b)) || a.localeCompare(b));
+  const moduleEdges = new Map(); // "fromDoc toDoc" -> count (cross-container resolved calls)
+  for (const [from, recs] of outBySym) {
+    const fd = docOfAnchor.get(from);
+    for (const r of recs) {
+      if (r.kind !== "call") continue;
+      const td = docOfAnchor.get(r.to);
+      if (fd === td) continue;
+      const key = `${fd} ${td}`;
+      moduleEdges.set(key, (moduleEdges.get(key) ?? 0) + 1);
+    }
+  }
+  const modName = (doc) => indexRows.find((r) => r.doc === doc)?.module ?? doc;
+  const index = [
+    "=== meta\n"
+    + `repo = ${csvCell(repoName)}\n`
+    + (commit ? `commit = ${csvCell(commit)}\n` : "")
+    + `container = ${container}\n`
+    + (appEntries.length ? `entry = ${appEntries.map((a) => `${docOfAnchor.get(a)}#${idOf.get(a)}`).join(" ")}\n` : "")
+    + `resolution-default = ${RESOLUTION_DEFAULT}\n===\n`,
+    `# Code map — ${esc(repoName)}\n`,
+    csv("modules", ["module", "doc", "methods", "entries", "tests"],
+      indexRows.sort((a, b) => b.methods - a.methods)
+        .map((r) => [csvCell(r.module), r.doc, r.methods, r.entries, r.tests])) ?? "",
+    csv("module-edges", ["from", "to", "calls"],
+      [...moduleEdges.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .map(([k, n]) => { const [fd, td] = k.split(" "); return [csvCell(modName(fd)), csvCell(modName(td)), n]; })) ?? "",
+  ].filter(Boolean).join("\n");
+  writeIfChanged("index.geml", index);
+
+  // ---- name-lookup ----
+  // Class-qualified names ("Cls.method") are ALSO findable by the bare member
+  // name — an agent asking "who is handleLogin" should not need to know the
+  // class first; ambiguity across classes is intrinsic and the lookup already
+  // answers with every candidate.
+  const lookup = new Map();
+  const addLookup = (name, s) => {
+    if (!lookup.has(name)) lookup.set(name, []);
+    lookup.get(name).push({ anchor: s.anchor, doc: docOfAnchor.get(s.anchor), id: idOf.get(s.anchor) });
+  };
+  for (const s of methods) {
+    addLookup(s.name, s);
+    const dot = s.name.indexOf(".");
+    if (dot > 0 && dot < s.name.length - 1) addLookup(s.name.slice(dot + 1), s);
+  }
+  const sortedLookup = {};
+  for (const name of [...lookup.keys()].sort()) {
+    sortedLookup[name] = lookup.get(name).sort((a, b) => a.anchor.localeCompare(b.anchor));
+  }
+  writeIfChanged("_index/name-lookup.json", JSON.stringify(sortedLookup, null, 2) + "\n");
+
+  // ---- edges-manifest (internal) ----
+  if (buildDir) {
+    const manifest = {};
+    for (const a of [...outBySym.keys()].sort()) {
+      manifest[a] = outBySym.get(a).map((r) => ({ kind: r.kind, to: r.to }))
+        .sort((x, y) => (x.kind + x.to).localeCompare(y.kind + y.to));
+    }
+    mkdirSync(buildDir, { recursive: true });
+    const p = join(buildDir, "edges-manifest.json");
+    const content = JSON.stringify(manifest, null, 1) + "\n";
+    if (!existsSync(p) || readFileSync(p, "utf8") !== content) writeFileSync(p, content);
+  }
+
+  return {
+    ...stats,
+    allDocs,
+    writtenDocs,
+    containers: containers.size,
+    symbols: symbols.length,
+    methods: methods.length,
+    edges: edges.length,
+    resolved: calls.filter((e) => e.to !== undefined && docOfAnchor.has(e.to)).length,
+    leaves: methods.filter((s) => isLeaf(s)).length,
+    entries: appEntries.length,
+  };
+}

package/codemap/exclude.mjs

@@ -0,0 +1,52 @@
+// Source exclusion for the codemap build.
+//
+// Two mechanisms, both matching on a symbol's repo-relative POSIX file path:
+//   1. .gitignore — the default. Whatever git ignores (vendored copies, build
+//      output, dependency dumps) never enters the graph. Uses `git check-ignore`
+//      so the semantics are exactly git's, including un-committed .gitignore
+//      edits (check-ignore reads the working tree).
+//   2. --exclude <glob> — explicit, repeatable, for paths git still tracks that
+//      you nonetheless don't want in the graph.
+// Neither touches the raw indexer output; excluded symbols are dropped before
+// emit, and the edge tables (which key on surviving anchors) follow.
+
+import { execFileSync as _execFileSync } from "node:child_process";
+
+// Minimal gitignore-flavoured glob: `**` spans path separators, `*` stays
+// within a segment, everything else is literal. Anchored to the whole path.
+export function globToRegExp(glob) {
+  let re = "";
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === "*") {
+      if (glob[i + 1] === "*") { re += ".*"; i++; if (glob[i + 1] === "/") i++; }
+      else re += "[^/]*";
+    } else if ("\\^$+?.()|{}[]".includes(c)) {
+      re += "\\" + c;
+    } else {
+      re += c;
+    }
+  }
+  return new RegExp("^" + re + "$");
+}
+
+// Ask git which of `files` it ignores. Returns a Set of the ignored paths.
+// check-ignore exits 1 when nothing matches and 128 when git is unavailable /
+// the dir is not a repo — both mean "ignore nothing", not a build failure.
+export function gitIgnored(root, files, exec = _execFileSync) {
+  if (!files.length) return new Set();
+  try {
+    const out = exec("git", ["-C", root, "check-ignore", "--stdin"], { input: files.join("\n"), encoding: "utf8" });
+    return new Set(out.split(/\r?\n/).filter(Boolean));
+  } catch (e) {
+    const out = e && e.stdout ? String(e.stdout) : "";
+    return new Set(out.split(/\r?\n/).filter(Boolean));
+  }
+}
+
+// Build a predicate (file) => shouldExclude.
+export function makeExcluder({ root, globs = [], gitignore = true, files = [], exec } = {}) {
+  const res = globs.map(globToRegExp);
+  const ignored = gitignore ? gitIgnored(root, files, exec) : new Set();
+  return (file) => ignored.has(file) || res.some((r) => r.test(file));
+}

package/codemap/joern-export.sc

@@ -0,0 +1,83 @@
+// geml-code-graph Joern export (P1, DESIGN §3.4).
+// Runs INSIDE joern; emits raw method/call records as JSONL for adapters/joern.mjs.
+//
+// Parameters come from ENVIRONMENT VARIABLES, not --param: on Windows the
+// joern.bat -> repl-bridge.bat hop re-tokenizes %* and cmd.exe treats `=` as a
+// delimiter, so `--param k=v` never survives intact. Env vars pass through
+// every layer on every OS:
+//
+//   GEML_SRC=/abs/path/to/src GEML_OUT=/abs/path/to/build/raw \
+//     joern --script geml-parser/codemap/joern-export.sc
+//
+// Output:
+//   <GEML_OUT>/methods.jsonl   one record per internal method
+//   <GEML_OUT>/calls.jsonl     one record per call site, callees resolved by Joern
+//
+// Identity: methods are keyed by fullName|signature|filename — the adapter
+// mints anchors and stable ids from these; this script stays dumb on purpose.
+import java.io.{File, PrintWriter}
+
+@main def exec(): Unit = {
+  val codeDir = sys.env.getOrElse("GEML_SRC", { System.err.println("GEML_SRC not set"); sys.exit(2) })
+  val outDir = sys.env.getOrElse("GEML_OUT", { System.err.println("GEML_OUT not set"); sys.exit(2) })
+  // GEML_LANG (optional): force a frontend in mixed-language repos, where
+  // auto-detection may pick the majority language instead of the intended one.
+  // Values are Joern's --language names: JAVASRC, NEWC, PYTHONSRC, JSSRC, …
+  sys.env.get("GEML_LANG") match {
+    case Some(lang) => importCode(inputPath = codeDir, projectName = "geml-code-graph", language = lang)
+    case None       => importCode(inputPath = codeDir, projectName = "geml-code-graph")
+  }
+
+  def esc(s: String): String =
+    s.replace("\\", "\\\\").replace("\"", "\\\"")
+     .replace("\n", "\\n").replace("\r", "\\r").replace("\t", "\\t")
+  def jstr(s: String): String = "\"" + esc(s) + "\""
+
+  new File(outDir).mkdirs()
+
+  val skipName = (n: String) => n == "<global>" || n.startsWith("<operator>") || n.startsWith("<clinit>")
+
+  // ---- methods ----
+  val mOut = new PrintWriter(new File(outDir, "methods.jsonl"), "UTF-8")
+  cpg.method.filter(m => !m.isExternal && !skipName(m.name)).foreach { m =>
+    mOut.println(
+      s"""{"name":${jstr(m.name)},"fullName":${jstr(m.fullName)},"signature":${jstr(m.signature)},""" +
+      s""""file":${jstr(m.filename)},"lineStart":${m.lineNumber.map(_.toString).getOrElse("null")},""" +
+      s""""lineEnd":${m.lineNumberEnd.map(_.toString).getOrElse("null")}}"""
+    )
+  }
+  mOut.close()
+
+  // ---- calls ----
+  // For each call site inside an internal method: Joern-resolved callees.
+  // Several internal callees = dispatch candidates (the adapter keeps them ALL,
+  // per the "never force a single candidate" red line). No internal callee =
+  // unresolved from the graph's point of view (external / pointer call).
+  // Operator calls are noise (arithmetic, casts, field access) EXCEPT
+  // <operator>.pointerCall — a function-pointer invocation is a real dispatch
+  // site the graph cannot resolve statically, so it must surface as an
+  // unresolved call (blind spots are shown, not hidden). Its readable label is
+  // the source expression itself.
+  val cOut = new PrintWriter(new File(outDir, "calls.jsonl"), "UTF-8")
+  cpg.call.filterNot(c => c.name.startsWith("<operator>") && c.name != "<operator>.pointerCall").foreach { c =>
+    val caller = c.method
+    if (!caller.isExternal && !skipName(caller.name)) {
+      val callees = c.callee.l
+      val internal = callees.filter(m => !m.isExternal && !skipName(m.name))
+      val tos = internal.map(m =>
+        s"""{"fullName":${jstr(m.fullName)},"signature":${jstr(m.signature)},"file":${jstr(m.filename)}}"""
+      ).mkString("[", ",", "]")
+      val label =
+        if (c.name == "<operator>.pointerCall") c.code.takeWhile(_ != '\n').take(48)
+        else c.name
+      cOut.println(
+        s"""{"callerFullName":${jstr(caller.fullName)},"callerSignature":${jstr(caller.signature)},""" +
+        s""""callerFile":${jstr(caller.filename)},"name":${jstr(label)},""" +
+        s""""line":${c.lineNumber.map(_.toString).getOrElse("null")},"callees":$tos}"""
+      )
+    }
+  }
+  cOut.close()
+
+  println(s"geml-code-graph joern-export: done -> $outDir")
+}

package/codemap/mcp-server.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+// geml-code-graph MCP server — the thin consumption wrapper of DESIGN §8 (P2).
+// Three navigation tools over a built graph/ directory, each "give an
+// identifier, get readable text back" (the original proposal's 2.6):
+//   resolve_name   name -> candidate anchors (doc + block id)
+//   open_symbol    doc + id -> that symbol's block, verbatim
+//   get_backlinks  doc + id -> the symbol's backlink block (who calls it)
+//
+// Zero dependencies: newline-delimited JSON-RPC 2.0 over stdio (the MCP stdio
+// transport). Register e.g.:
+//   claude mcp add geml-code-graph -e GEML_GRAPH_DIR=/abs/path/to/graph \
+//     -- geml codemap mcp
+// The graph dir comes from GEML_GRAPH_DIR or a per-call `graph_dir` argument.
+import { readFileSync, existsSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createInterface } from "node:readline";
+
+// blockSpans from the reference parser (its CLI entry is guarded, so importing
+// is side-effect free). Falls back with a clear error if the parser isn't built.
+const parserPath = resolve(dirname(fileURLToPath(import.meta.url)), "../dist/geml.js");
+if (!existsSync(parserPath)) {
+  console.error("geml-code-graph mcp: build the parser first (cd geml-parser && npm install && npm run build)");
+  process.exit(1);
+}
+const { blockSpans } = await import(`file://${parserPath.replace(/\\/g, "/")}`);
+const splitLines = (s) => s.split(/(?<=\n)/);
+
+const graphDirOf = (args) => resolve(args?.graph_dir ?? process.env.GEML_GRAPH_DIR ?? ".geml-code-graph");
+
+const readBlock = (graphDir, doc, id) => {
+  const p = join(graphDir, doc);
+  if (!existsSync(p)) throw new Error(`no such document: ${doc} (graph dir: ${graphDir})`);
+  const source = readFileSync(p, "utf8");
+  const span = blockSpans(source).get(id.replace(/^#/, ""));
+  if (!span) throw new Error(`no block with id \`${id}\` in ${doc}`);
+  return splitLines(source).slice(span.start, span.end).join("");
+};
+
+const TOOLS = [
+  {
+    name: "resolve_name",
+    description: "Find a function/class by name in the code graph. Returns candidate anchors with the document and block id to open. Multiple candidates = real ambiguity (overloads/same name) — inspect each, never assume.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Exact symbol name (function/class short name)" },
+        graph_dir: { type: "string", description: "Graph directory (default: $GEML_GRAPH_DIR or ./.geml-code-graph)" },
+      },
+      required: ["name"],
+    },
+    run: (args) => {
+      const lookupPath = join(graphDirOf(args), "_index/name-lookup.json");
+      if (!existsSync(lookupPath)) throw new Error(`no name-lookup at ${lookupPath} — build the graph first`);
+      const lookup = JSON.parse(readFileSync(lookupPath, "utf8"));
+      const hits = lookup[args.name];
+      if (!hits?.length) return `no symbol named \`${args.name}\` in the graph`;
+      return JSON.stringify(hits, null, 1);
+    },
+  },
+  {
+    name: "open_symbol",
+    description: "Open ONE symbol's block from the code graph (its callees as checked references, confidence annotations, called-by pointer). Equivalent to following a link. Get doc+id from resolve_name.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        doc: { type: "string", description: "Document path relative to the codemap dir, e.g. hashtable.c.geml" },
+        id: { type: "string", description: "Block id, e.g. hashtableFind (or #calls / #called-by for the edge tables)" },
+        graph_dir: { type: "string", description: "Graph directory (default: $GEML_GRAPH_DIR or ./.geml-code-graph)" },
+      },
+      required: ["doc", "id"],
+    },
+    run: (args) => readBlock(graphDirOf(args), args.doc, args.id),
+  },
+  {
+    name: "get_backlinks",
+    description: "Who calls this symbol: opens its backlink block (callers with file:line sites, each a followable reference). Absence means no RESOLVED callers — never proof of none.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        doc: { type: "string", description: "The symbol's document path, e.g. hashtable.c.geml" },
+        id: { type: "string", description: "The symbol's block id (e.g. hashtableFind); omit to get the whole #called-by table" },
+        graph_dir: { type: "string", description: "Codemap directory (default: $GEML_GRAPH_DIR or ./.geml-code-graph)" },
+      },
+      required: ["doc"],
+    },
+    run: (args) => {
+      // codemap profile: in-edges live in the SAME document's #called-by table.
+      let table;
+      try {
+        table = readBlock(graphDirOf(args), args.doc, "called-by");
+      } catch {
+        return `no #called-by table in ${args.doc} — no resolved callers recorded (under heuristic extraction this is a blind spot, not proof of none)`;
+      }
+      if (!args.id) return table;
+      const id = args.id.replace(/^#/, "");
+      const lines = table.split("\n");
+      const hits = lines.filter((l, i) => i < 2 || new RegExp(`,\\s*#${id}\\s*,`).test(l));
+      return hits.length > 2 ? hits.join("\n")
+        : `no resolved callers of #${id} in ${args.doc} (blind spots live in the #unresolved table)`;
+    },
+  },
+];
+
+// ---- newline-delimited JSON-RPC 2.0 over stdio ----
+const reply = (id, result) => process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id, result }) + "\n");
+const replyError = (id, code, message) =>
+  process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } }) + "\n");
+
+createInterface({ input: process.stdin }).on("line", (line) => {
+  line = line.trim();
+  if (!line) return;
+  let msg;
+  try { msg = JSON.parse(line); } catch { return; }
+  const { id, method, params } = msg;
+  try {
+    if (method === "initialize") {
+      reply(id, {
+        protocolVersion: params?.protocolVersion ?? "2024-11-05",
+        capabilities: { tools: {} },
+        serverInfo: { name: "geml-code-graph", version: "0.2.0" },
+      });
+    } else if (method === "notifications/initialized" || method?.startsWith("notifications/")) {
+      // notifications get no response
+    } else if (method === "ping") {
+      reply(id, {});
+    } else if (method === "tools/list") {
+      reply(id, { tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })) });
+    } else if (method === "tools/call") {
+      const tool = TOOLS.find((t) => t.name === params?.name);
+      if (!tool) { replyError(id, -32602, `unknown tool: ${params?.name}`); return; }
+      try {
+        reply(id, { content: [{ type: "text", text: tool.run(params?.arguments ?? {}) }] });
+      } catch (e) {
+        reply(id, { content: [{ type: "text", text: `error: ${e.message}` }], isError: true });
+      }
+    } else if (id !== undefined) {
+      replyError(id, -32601, `method not found: ${method}`);
+    }
+  } catch (e) {
+    if (id !== undefined) replyError(id, -32603, String(e?.message ?? e));
+  }
+});