@geml/geml 1.0.0 → 1.3.2

package/codemap/find.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// geml codemap find <name> [codemap-dir]
+//
+// Locate a function/class by (substring, case-insensitive) name in a built
+// codemap. Prints each candidate as  <name> \t <doc>#<id> \t <src>  — the
+// document + block id to open, and the true source location. NO browser: pure
+// stdout, so it pipes/greps. `dir` defaults to ./.geml-code-graph.
+//
+// Same index the MCP `resolve_name` tool and the viewer search box use
+// (_index/name-lookup.json); a name with several rows is real ambiguity
+// (overloads / same short name across classes) — every candidate is printed.
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+// `find x | head` closes stdout after a few lines — that is normal pipe
+// usage, not an error (POSIX would kill us silently with SIGPIPE; Windows
+// node surfaces it as an EPIPE error event): exit quietly instead of
+// crashing with an unhandled-error stack trace.
+process.stdout.on("error", (e) => { if (e.code === "EPIPE") process.exit(0); throw e; });
+
+const args = process.argv.slice(2);
+if (!args.length || args[0] === "--help" || args[0] === "-h") {
+  console.error("usage: geml codemap find <name> [codemap-dir]   # locate a symbol by substring name (dir defaults to ./.geml-code-graph)");
+  process.exit(args.length ? 0 : 2);
+}
+const query = args[0];
+const dir = args[1] || ".geml-code-graph";
+const lookupPath = join(dir, "_index", "name-lookup.json");
+if (!existsSync(lookupPath)) {
+  console.error(`no name-lookup at ${lookupPath} — build the codemap first (geml codemap build)`);
+  process.exit(1);
+}
+const lookup = JSON.parse(readFileSync(lookupPath, "utf8"));
+const q = query.toLowerCase();
+const names = Object.keys(lookup).filter((n) => n.toLowerCase().includes(q)).sort();
+if (!names.length) { console.error(`no symbol matching "${query}"`); process.exit(1); }
+
+// src= lives on the block header line in the doc; read each doc once, index by id.
+const docCache = new Map(); // doc -> Map(id -> src)
+const srcOf = (doc, id) => {
+  if (!docCache.has(doc)) {
+    const map = new Map();
+    try {
+      const text = readFileSync(join(dir, doc), "utf8");
+      // src= may be quoted or a bare token (path#Lx-y, no spaces).
+      const re = /\{#([A-Za-z0-9._-]+)\b[^}]*?\bsrc=(?:"([^"]+)"|([^\s}]+))/g;
+      let m;
+      while ((m = re.exec(text))) map.set(m[1], m[2] || m[3]);
+    } catch { /* doc unreadable — skip src */ }
+    docCache.set(doc, map);
+  }
+  return docCache.get(doc).get(id) || "";
+};
+
+let n = 0;
+for (const name of names) {
+  for (const c of lookup[name]) {
+    const src = srcOf(c.doc, c.id);
+    process.stdout.write(`${name}\t${c.doc}#${c.id}${src ? `\t${src}` : ""}\n`);
+    n++;
+  }
+}
+console.error(`\n${n} match(es) for "${query}" across ${names.length} name(s).`);

package/codemap/foldings.mjs

@@ -0,0 +1,110 @@
+// foldings.geml — the visible, human-owned config for codemap ceremony folding.
+// GEML (dogfooded; the viewer renders it): a meta header, three bullet-list
+// sections (fold-prefixes / source-roots / test-roots) and an options section.
+// Read via the bundled parser; group-id shared-prefix stripping stays
+// algorithmic (only its on/off toggle lives here).
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "../dist/geml.js";
+import { deriveFoldLayers, DEFAULT_SOURCE_ROOTS, DEFAULT_TEST_ROOTS, LANG_FOLD_PREFIXES } from "./normalize.mjs";
+
+const SECTIONS = { "fold-prefixes": "foldPrefixes", "source-roots": "sourceRoots", "test-roots": "testRoots", "module-roots": "moduleRoots" };
+// Plain text of a bullet-list item. GEML list items carry `.text`; fall back to
+// joining inline `.value`s if a build ever changes that shape.
+const itemText = (it) => (typeof it.text === "string" ? it.text : (it.inlines ?? []).map((n) => n.value ?? "").join("")).trim();
+
+export function parseFoldings(text) {
+  const doc = parse(text);
+  // A malformed hand-edit must fail LOUDLY, not silently drop every rule: the
+  // caller (loadOrSeedFoldings) catches this and falls back to the defaults.
+  // An intentionally empty file carries NO error diagnostics and yields empty
+  // sections — the "fold nothing" off-switch, a deliberately different outcome.
+  const errs = doc.diagnostics.filter((d) => d.severity === "error");
+  if (errs.length) throw new Error(`invalid GEML in foldings config: ${errs[0].message} (line ${errs[0].line})`);
+  const cfg = { foldPrefixes: [], sourceRoots: [], testRoots: [], moduleRoots: [], stripSharedPrefix: true };
+  let section = null;
+  for (const b of doc.children) {
+    if (b.kind === "heading") { section = b.text.trim().toLowerCase(); continue; }
+    if (b.kind !== "list") continue;
+    const items = b.items.map(itemText).filter(Boolean);
+    if (Object.hasOwn(SECTIONS, section)) cfg[SECTIONS[section]] = items;
+    else if (section === "options") {
+      for (const it of items) {
+        const m = it.match(/^strip-shared-prefix\s*:\s*(on|off|true|false)$/i);
+        if (m) cfg.stripSharedPrefix = /^(on|true)$/i.test(m[1]);
+      }
+    }
+  }
+  return cfg;
+}
+
+export function serializeFoldings(cfg) {
+  const list = (xs) => xs.map((x) => `- ${x}`).join("\n");
+  return [
+    "=== meta",
+    'title = "codemap foldings"',
+    "===",
+    "",
+    "Ceremony folded out of module display names. Seeded on first build; edit",
+    "freely — build never rewrites this. The shared package prefix (group-ids",
+    "like com/acme/app) is stripped automatically and needs no entry here; set",
+    "strip-shared-prefix to off under Options to disable it.",
+    "",
+    "Add a directory under module-roots to force it to display as its own",
+    "module — for a submodule a build tool declares centrally but whose folder",
+    "carries no manifest, or any layout the detector cannot see.",
+    "",
+    "## fold-prefixes",
+    "",
+    list(cfg.foldPrefixes),
+    "",
+    "## source-roots",
+    "",
+    list(cfg.sourceRoots),
+    "",
+    "## test-roots",
+    "",
+    list(cfg.testRoots),
+    "",
+    "## module-roots",
+    "",
+    list(cfg.moduleRoots ?? []),
+    "",
+    "## options",
+    "",
+    `- strip-shared-prefix: ${cfg.stripSharedPrefix ? "on" : "off"}`,
+    "",
+  ].join("\n");
+}
+
+// Seeded config for a first build: structural fold-layers (above-root
+// ceremony dirs, derived from the discovered module roots) unioned with
+// known per-language ceremony (Cargo's `crates/`). Source/test roots always
+// start from the same global defaults — the human edits foldings.geml from
+// there; the build never rewrites it once it exists.
+export function defaultFoldings({ moduleRoots, languages }) {
+  const langPrefixes = (languages ?? []).flatMap((l) => LANG_FOLD_PREFIXES[l] ?? []);
+  const foldPrefixes = [...new Set([...deriveFoldLayers(moduleRoots ?? []), ...langPrefixes])].sort();
+  return { foldPrefixes, sourceRoots: [...DEFAULT_SOURCE_ROOTS], testRoots: [...DEFAULT_TEST_ROOTS], moduleRoots: [], stripSharedPrefix: true };
+}
+
+// Read <outDir>/_index/foldings.geml, or seed it on first build. Write-once:
+// an existing file is the human's — we read it and never rewrite it (the
+// refresh.json contract). A missing or unreadable file never crashes the
+// build: seed/fall back to defaults and say so. Returns { config, seeded }.
+export function loadOrSeedFoldings({ outDir, moduleRoots, languages }) {
+  const path = join(outDir, "_index", "foldings.geml");
+  if (existsSync(path)) {
+    try { return { config: parseFoldings(readFileSync(path, "utf8")), seeded: false }; }
+    catch (e) {
+      console.error(`warning: ignoring ${path} (${e.message}) — using default foldings; fix the file to re-enable your edits.`);
+      return { config: defaultFoldings({ moduleRoots, languages }), seeded: false };
+    }
+  }
+  const config = defaultFoldings({ moduleRoots, languages });
+  try {
+    mkdirSync(join(outDir, "_index"), { recursive: true });
+    writeFileSync(path, serializeFoldings(config));
+  } catch (e) { console.error(`warning: could not seed ${path} (${e.message}).`); }
+  return { config, seeded: true };
+}

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,172 @@
+#!/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.
+//
+// The dispatch is exported (and the stdio wiring below is main-module guarded)
+// so the test suite can drive it in-process; the CLI dispatcher always runs
+// this file as a child's MAIN module, where nothing changes.
+import { readFileSync, existsSync, realpathSync } from "node:fs";
+import { join, resolve, dirname, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } 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)/);
+
+export const graphDirOf = (args) => resolve(args?.graph_dir ?? process.env.GEML_GRAPH_DIR ?? ".geml-code-graph");
+
+export const readBlock = (graphDir, doc, id) => {
+  const p = join(graphDir, doc);
+  // Confine `doc` to the graph dir. `doc` is client-supplied, so a value like
+  // ../../../etc/hosts joins OUT of the dir; realpathSync canonicalizes both
+  // sides (also defeating symlink escapes and normalizing Windows casing) and
+  // we verify the real doc path stays within the real graph dir. A missing
+  // file makes realpathSync throw — that is the normal "no such document"
+  // miss. (graph_dir itself is intentionally client-chosen — the server is
+  // pointed at a graph — so only the doc path is confined, to that dir.)
+  let realDir;
+  try { realDir = realpathSync(graphDir); } catch { realDir = resolve(graphDir); }
+  let realP;
+  try { realP = realpathSync(p); } catch { throw new Error(`no such document: ${doc} (graph dir: ${graphDir})`); }
+  if (realP !== realDir && !realP.startsWith(realDir + sep)) {
+    throw new Error(`document escapes the graph dir: ${doc} (graph dir: ${graphDir})`);
+  }
+  const source = readFileSync(realP, "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("");
+};
+
+export 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(/^#/, "");
+      // `id` is client-supplied and goes straight into a RegExp: escape every
+      // regex metacharacter so it matches LITERALLY (an id like `.*` or a
+      // catastrophic-backtracking pattern can neither widen the match nor cause
+      // ReDoS — the pattern is a fixed string wrapped in `,\s*#…\s*,`).
+      const escId = id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      const re = new RegExp(`,\\s*#${escId}\\s*,`);
+      const lines = table.split("\n");
+      const hits = lines.filter((l, i) => i < 2 || re.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 ----
+// One frame in, zero or one frame out via `write` (stdout in production).
+export function handleLine(line, write = (s) => process.stdout.write(s)) {
+  const reply = (id, result) => write(JSON.stringify({ jsonrpc: "2.0", id, result }) + "\n");
+  const replyError = (id, code, message) =>
+    write(JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } }) + "\n");
+  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));
+  }
+}
+
+// Auto-run only as a MAIN module (the CLI dispatcher spawns this file as a
+// child's entry script) — an in-process `import` stays inert.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  createInterface({ input: process.stdin }).on("line", (line) => handleLine(line));
+}