@geml/geml 1.8.2 → 1.8.3

package/codemap/entries.mjs

@@ -1,129 +1,129 @@
-// geml-code-graph app-entry detection — WHERE does this repo start running?
-//
-// Emits entry HINTS ({ file, via, name? }) from three signal tiers, each
-// carrying an honest `via` label (the codemap never claims an entry without
-// saying what convention identified it):
-//   L2 manifest/layout   Cargo [[bin]] & src/main.rs & src/bin/*, package.json
-//                        bin, wrangler.toml main, Nuxt app.vue, Next root
-//                        page, SvelteKit root route, Django manage.py,
-//                        python __main__.py
-//   L3 source markers    workers-rs #[event(...)], createApp().mount() /
-//                        createRoot() / svelte mount (SPA bootstraps),
-//                        .listen() (node servers), export default { fetch }
-//                        (JS workers), Flask()/FastAPI() apps,
-//                        @SpringBootApplication
-// (L1 — a function literally named `main` — is already flagged by the scip
-// and joern adapters at extraction time; hints here ADD to it.)
-//
-// Pure by design: given precomputed { files, manifests, pkgs } lists it walks
-// nothing; `readText`/`readJson` are injectable, and every source peek is
-// bounded to a handful of conventional entry files per project — never a
-// repo-wide grep. A hint is only emitted for files the build actually indexes
-// (present in `files`), so a pkg-bin pointing at dist/ never leaks in.
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
-
-const dirOf = (p) => (p.includes("/") ? p.slice(0, p.lastIndexOf("/")) : "");
-
-export function detectEntries(root, { files = [], manifests = [], pkgs = [], readText, readJson } = {}) {
-  readText ??= (p) => readFileSync(p, "utf8");
-  readJson ??= (p) => JSON.parse(readText(p));
-  const fileSet = new Set(files);
-  const hints = [];
-  const seen = new Set();
-  const add = (file, via, name) => {
-    if (!file || !fileSet.has(file)) return;
-    const k = `${file}
${via}
${name ?? ""}`;
-    if (seen.has(k)) return;
-    seen.add(k);
-    hints.push(name ? { file, via, name } : { file, via });
-  };
-  const tryText = (rel) => {
-    try { return readText(join(root, ...rel.split("/"))); } catch { return null; }
-  };
-
-  // ---- Rust: cargo bin targets + workers-rs event handlers ----
-  for (const m of manifests.filter((x) => x.endsWith("Cargo.toml"))) {
-    const dir = dirOf(m);
-    const at = (rel) => (dir ? `${dir}/${rel}` : rel);
-    add(at("src/main.rs"), "cargo-bin", "main");
-    for (const f of files) if (f.startsWith(at("src/bin/")) && f.endsWith(".rs")) add(f, "cargo-bin", "main");
-    const toml = tryText(m);
-    if (toml) {
-      for (const b of toml.matchAll(/^\[\[bin\]\][^[]*/gm)) {
-        const p = /path\s*=\s*"([^"]+)"/.exec(b[0]);
-        if (p) add(at(p[1].replace(/\\/g, "/")), "cargo-bin", "main");
-      }
-    }
-    for (const rel of ["src/main.rs", "src/lib.rs"]) {
-      const t = fileSet.has(at(rel)) ? tryText(at(rel)) : null;
-      if (!t) continue;
-      for (const ev of t.matchAll(/#\[event\((\w+)[^)]*\)\]\s*(?:pub\s+)?(?:async\s+)?fn\s+([A-Za-z_][A-Za-z0-9_]*)/g)) {
-        add(at(rel), `worker-${ev[1]}`, ev[2]);
-      }
-    }
-  }
-
-  // ---- Node/TS/frontends: one look per package ----
-  for (const p of pkgs) {
-    const dir = dirOf(p);
-    const at = (rel) => (dir ? `${dir}/${rel}` : rel);
-    let pkg = {};
-    try { pkg = readJson(join(root, ...p.split("/"))) ?? {}; } catch { /* unreadable manifest */ }
-    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
-    const norm = (v) => (typeof v === "string" ? v.replace(/^\.\//, "").replace(/\\/g, "/") : null);
-    const bins = typeof pkg.bin === "string" ? [pkg.bin] : Object.values(pkg.bin ?? {});
-    for (const b of bins) { const f = norm(b); if (f) add(at(f), "pkg-bin"); }
-    const wrangler = tryText(at("wrangler.toml"));
-    if (wrangler) {
-      const mm = /^\s*main\s*=\s*"([^"]+)"/m.exec(wrangler);
-      if (mm) add(at(norm(mm[1])), "worker-fetch");
-    }
-    // Nuxt: the app shell is the entry; individual pages are routes, not
-    // program starts — deliberately NOT flooded into app-entries.
-    if (deps.nuxt || fileSet.has(at("nuxt.config.ts")) || fileSet.has(at("nuxt.config.js"))) {
-      if (fileSet.has(at("app.vue"))) add(at("app.vue"), "nuxt-app");
-      else add(at("pages/index.vue"), "nuxt-page");
-    }
-    if (deps.next) {
-      for (const rel of ["app/page.tsx", "app/page.jsx", "src/app/page.tsx", "pages/index.tsx", "pages/index.jsx", "src/pages/index.tsx"]) {
-        if (fileSet.has(at(rel))) { add(at(rel), "next-page"); break; }
-      }
-    }
-    if (deps["@sveltejs/kit"]) add(at("src/routes/+page.svelte"), "kit-route");
-    // SPA bootstrap / server start markers — conventional entry files only.
-    for (const rel of ["src/main.ts", "src/main.tsx", "src/main.js", "src/main.jsx",
-      "src/index.ts", "src/index.tsx", "src/index.js", "index.ts", "index.js",
-      "src/server.ts", "src/server.js", "server.js", "src/app.ts", "app.js"]) {
-      const f = at(rel);
-      if (!fileSet.has(f)) continue;
-      const t = tryText(f);
-      if (!t) continue;
-      if (/createApp\s*\(/.test(t) && /\.mount\s*\(/.test(t)) add(f, "vue-mount");
-      else if (/createRoot\s*\(|ReactDOM\.render\s*\(/.test(t)) add(f, "react-mount");
-      else if (deps.svelte && /\bnew\s+\w+\s*\(\s*\{[^}]*target|\bmount\s*\(/.test(t)) add(f, "svelte-mount");
-      if (/\.listen\s*\(/.test(t)) add(f, "server-listen");
-      if (/export\s+default\s*\{[^}]*\bfetch\b/s.test(t)) add(f, "worker-fetch");
-    }
-  }
-
-  // ---- Python ----
-  for (const f of files) {
-    if (/(^|\/)manage\.py$/.test(f)) add(f, "django-manage");
-    else if (/(^|\/)__main__\.py$/.test(f)) add(f, "py-main");
-    else if (/(^|\/)(app|main|wsgi|asgi)\.py$/.test(f)) {
-      const t = tryText(f);
-      if (t && /\bFlask\s*\(|\bFastAPI\s*\(/.test(t)) add(f, "wsgi-app");
-    }
-  }
-
-  // ---- Java: Spring Boot (convention-named files only, never a repo grep) ----
-  for (const f of files) {
-    if (/Application\.java$/.test(f)) {
-      const t = tryText(f);
-      if (t && /@SpringBootApplication/.test(t)) add(f, "spring-boot", "main");
-    }
-  }
-
-  return hints;
-}
+// geml-code-graph app-entry detection — WHERE does this repo start running?
+//
+// Emits entry HINTS ({ file, via, name? }) from three signal tiers, each
+// carrying an honest `via` label (the codemap never claims an entry without
+// saying what convention identified it):
+//   L2 manifest/layout   Cargo [[bin]] & src/main.rs & src/bin/*, package.json
+//                        bin, wrangler.toml main, Nuxt app.vue, Next root
+//                        page, SvelteKit root route, Django manage.py,
+//                        python __main__.py
+//   L3 source markers    workers-rs #[event(...)], createApp().mount() /
+//                        createRoot() / svelte mount (SPA bootstraps),
+//                        .listen() (node servers), export default { fetch }
+//                        (JS workers), Flask()/FastAPI() apps,
+//                        @SpringBootApplication
+// (L1 — a function literally named `main` — is already flagged by the scip
+// and joern adapters at extraction time; hints here ADD to it.)
+//
+// Pure by design: given precomputed { files, manifests, pkgs } lists it walks
+// nothing; `readText`/`readJson` are injectable, and every source peek is
+// bounded to a handful of conventional entry files per project — never a
+// repo-wide grep. A hint is only emitted for files the build actually indexes
+// (present in `files`), so a pkg-bin pointing at dist/ never leaks in.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const dirOf = (p) => (p.includes("/") ? p.slice(0, p.lastIndexOf("/")) : "");
+
+export function detectEntries(root, { files = [], manifests = [], pkgs = [], readText, readJson } = {}) {
+  readText ??= (p) => readFileSync(p, "utf8");
+  readJson ??= (p) => JSON.parse(readText(p));
+  const fileSet = new Set(files);
+  const hints = [];
+  const seen = new Set();
+  const add = (file, via, name) => {
+    if (!file || !fileSet.has(file)) return;
+    const k = `${file}
${via}
${name ?? ""}`;
+    if (seen.has(k)) return;
+    seen.add(k);
+    hints.push(name ? { file, via, name } : { file, via });
+  };
+  const tryText = (rel) => {
+    try { return readText(join(root, ...rel.split("/"))); } catch { return null; }
+  };
+
+  // ---- Rust: cargo bin targets + workers-rs event handlers ----
+  for (const m of manifests.filter((x) => x.endsWith("Cargo.toml"))) {
+    const dir = dirOf(m);
+    const at = (rel) => (dir ? `${dir}/${rel}` : rel);
+    add(at("src/main.rs"), "cargo-bin", "main");
+    for (const f of files) if (f.startsWith(at("src/bin/")) && f.endsWith(".rs")) add(f, "cargo-bin", "main");
+    const toml = tryText(m);
+    if (toml) {
+      for (const b of toml.matchAll(/^\[\[bin\]\][^[]*/gm)) {
+        const p = /path\s*=\s*"([^"]+)"/.exec(b[0]);
+        if (p) add(at(p[1].replace(/\\/g, "/")), "cargo-bin", "main");
+      }
+    }
+    for (const rel of ["src/main.rs", "src/lib.rs"]) {
+      const t = fileSet.has(at(rel)) ? tryText(at(rel)) : null;
+      if (!t) continue;
+      for (const ev of t.matchAll(/#\[event\((\w+)[^)]*\)\]\s*(?:pub\s+)?(?:async\s+)?fn\s+([A-Za-z_][A-Za-z0-9_]*)/g)) {
+        add(at(rel), `worker-${ev[1]}`, ev[2]);
+      }
+    }
+  }
+
+  // ---- Node/TS/frontends: one look per package ----
+  for (const p of pkgs) {
+    const dir = dirOf(p);
+    const at = (rel) => (dir ? `${dir}/${rel}` : rel);
+    let pkg = {};
+    try { pkg = readJson(join(root, ...p.split("/"))) ?? {}; } catch { /* unreadable manifest */ }
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    const norm = (v) => (typeof v === "string" ? v.replace(/^\.\//, "").replace(/\\/g, "/") : null);
+    const bins = typeof pkg.bin === "string" ? [pkg.bin] : Object.values(pkg.bin ?? {});
+    for (const b of bins) { const f = norm(b); if (f) add(at(f), "pkg-bin"); }
+    const wrangler = tryText(at("wrangler.toml"));
+    if (wrangler) {
+      const mm = /^\s*main\s*=\s*"([^"]+)"/m.exec(wrangler);
+      if (mm) add(at(norm(mm[1])), "worker-fetch");
+    }
+    // Nuxt: the app shell is the entry; individual pages are routes, not
+    // program starts — deliberately NOT flooded into app-entries.
+    if (deps.nuxt || fileSet.has(at("nuxt.config.ts")) || fileSet.has(at("nuxt.config.js"))) {
+      if (fileSet.has(at("app.vue"))) add(at("app.vue"), "nuxt-app");
+      else add(at("pages/index.vue"), "nuxt-page");
+    }
+    if (deps.next) {
+      for (const rel of ["app/page.tsx", "app/page.jsx", "src/app/page.tsx", "pages/index.tsx", "pages/index.jsx", "src/pages/index.tsx"]) {
+        if (fileSet.has(at(rel))) { add(at(rel), "next-page"); break; }
+      }
+    }
+    if (deps["@sveltejs/kit"]) add(at("src/routes/+page.svelte"), "kit-route");
+    // SPA bootstrap / server start markers — conventional entry files only.
+    for (const rel of ["src/main.ts", "src/main.tsx", "src/main.js", "src/main.jsx",
+      "src/index.ts", "src/index.tsx", "src/index.js", "index.ts", "index.js",
+      "src/server.ts", "src/server.js", "server.js", "src/app.ts", "app.js"]) {
+      const f = at(rel);
+      if (!fileSet.has(f)) continue;
+      const t = tryText(f);
+      if (!t) continue;
+      if (/createApp\s*\(/.test(t) && /\.mount\s*\(/.test(t)) add(f, "vue-mount");
+      else if (/createRoot\s*\(|ReactDOM\.render\s*\(/.test(t)) add(f, "react-mount");
+      else if (deps.svelte && /\bnew\s+\w+\s*\(\s*\{[^}]*target|\bmount\s*\(/.test(t)) add(f, "svelte-mount");
+      if (/\.listen\s*\(/.test(t)) add(f, "server-listen");
+      if (/export\s+default\s*\{[^}]*\bfetch\b/s.test(t)) add(f, "worker-fetch");
+    }
+  }
+
+  // ---- Python ----
+  for (const f of files) {
+    if (/(^|\/)manage\.py$/.test(f)) add(f, "django-manage");
+    else if (/(^|\/)__main__\.py$/.test(f)) add(f, "py-main");
+    else if (/(^|\/)(app|main|wsgi|asgi)\.py$/.test(f)) {
+      const t = tryText(f);
+      if (t && /\bFlask\s*\(|\bFastAPI\s*\(/.test(t)) add(f, "wsgi-app");
+    }
+  }
+
+  // ---- Java: Spring Boot (convention-named files only, never a repo grep) ----
+  for (const f of files) {
+    if (/Application\.java$/.test(f)) {
+      const t = tryText(f);
+      if (t && /@SpringBootApplication/.test(t)) add(f, "spring-boot", "main");
+    }
+  }
+
+  return hints;
+}

package/codemap/exclude.mjs

@@ -1,56 +1,56 @@
-// 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) {
-  // The glob comes from a `--exclude` argument, so nothing in it may reach the
-  // compiled pattern as *syntax*. Split on the wildcards, keeping them (the
-  // capture group), which leaves the array strictly alternating: even indices
-  // are literal text, odd indices are `*`, `**` or `**/`. Literals go through a
-  // total regex-metacharacter escape; wildcards map to fixed patterns. Neither
-  // path can carry an unescaped metacharacter through.
-  const parts = String(glob).split(/(\*\*\/?|\*)/);
-  let re = "";
-  for (let i = 0; i < parts.length; i++) {
-    if (i % 2 === 0) re += parts[i].replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    else re += parts[i] === "*" ? "[^/]*" : ".*"; // `**` and `**/` span separators
-  }
-  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.
-// The injected runner is named `run`, not `exec`: it is always an execFile-shaped
-// (program, args[]) call that spawns NO shell, whereas a callback named `exec`
-// reads — to a human skimming, and to a static analyser — as the shell-string
-// child_process API. The name should not imply the dangerous one.
-export function gitIgnored(root, files, run = _execFileSync) {
-  if (!files.length) return new Set();
-  try {
-    const out = run("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 = [], run } = {}) {
-  const res = globs.map(globToRegExp);
-  const ignored = gitignore ? gitIgnored(root, files, run) : new Set();
-  return (file) => ignored.has(file) || res.some((r) => r.test(file));
-}
+// 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) {
+  // The glob comes from a `--exclude` argument, so nothing in it may reach the
+  // compiled pattern as *syntax*. Split on the wildcards, keeping them (the
+  // capture group), which leaves the array strictly alternating: even indices
+  // are literal text, odd indices are `*`, `**` or `**/`. Literals go through a
+  // total regex-metacharacter escape; wildcards map to fixed patterns. Neither
+  // path can carry an unescaped metacharacter through.
+  const parts = String(glob).split(/(\*\*\/?|\*)/);
+  let re = "";
+  for (let i = 0; i < parts.length; i++) {
+    if (i % 2 === 0) re += parts[i].replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    else re += parts[i] === "*" ? "[^/]*" : ".*"; // `**` and `**/` span separators
+  }
+  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.
+// The injected runner is named `run`, not `exec`: it is always an execFile-shaped
+// (program, args[]) call that spawns NO shell, whereas a callback named `exec`
+// reads — to a human skimming, and to a static analyser — as the shell-string
+// child_process API. The name should not imply the dangerous one.
+export function gitIgnored(root, files, run = _execFileSync) {
+  if (!files.length) return new Set();
+  try {
+    const out = run("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 = [], run } = {}) {
+  const res = globs.map(globToRegExp);
+  const ignored = gitignore ? gitIgnored(root, files, run) : new Set();
+  return (file) => ignored.has(file) || res.some((r) => r.test(file));
+}

package/codemap/find.mjs

@@ -1,49 +1,49 @@
-#!/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 `geml_codemap_search` 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.
-//
-// The matching rule and the src lookup are IMPORTED, not repeated here: this
-// command and `geml_codemap_search` answer the same question, and two copies of
-// "what counts as a match" would drift the moment one of them is tuned.
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-import { searchNames, srcOf } from "./mcp-server.mjs";
-
-// `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 { names, lookup } = searchNames(dir, query);
-if (!names.length) { console.error(`no symbol matching "${query}"`); process.exit(1); }
-
-let n = 0;
-for (const name of names) {
-  for (const c of lookup[name]) {
-    const src = srcOf(dir, 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).`);
+#!/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 `geml_codemap_search` 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.
+//
+// The matching rule and the src lookup are IMPORTED, not repeated here: this
+// command and `geml_codemap_search` answer the same question, and two copies of
+// "what counts as a match" would drift the moment one of them is tuned.
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { searchNames, srcOf } from "./mcp-server.mjs";
+
+// `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 { names, lookup } = searchNames(dir, query);
+if (!names.length) { console.error(`no symbol matching "${query}"`); process.exit(1); }
+
+let n = 0;
+for (const name of names) {
+  for (const c of lookup[name]) {
+    const src = srcOf(dir, 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).`);