@geml/geml 1.0.0 → 1.1.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 GEML contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 GEML contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,72 +1,79 @@
-# @geml/geml
-
-Reference parser, validator, renderer, and CLI for **GEML** — the General
-Expressive Markup Language: a plain-text document format that stays legible to
-people and reliable for machines. Every kind of structured content — code,
-tables, diagrams, math, callouts, metadata — is carried on **one** primitive,
-the typed block:
-
-```
-=== code {#hello lang=python}
-print("hi")
-===
-```
-
-References are checked at build time (a dangling `#id` is an error, not a silent
-dead link), and the parser emits a document-model JSON with `diagnostics`, so
-agents and CI get a structured pass/fail signal.
-
-## Install
-
-```sh
-npm install -g @geml/geml   # global CLI — installs the `geml` command
-# or, per project:
-npm install @geml/geml      # library + local bin
-```
-
-Requires Node ≥ 18.
-
-## CLI
-
-Every command reads a file path, or `-` for stdin. Exit codes: `0` ok ·
-`1` document/operation error · `2` usage error.
-
-```sh
-geml check  file.geml            # validate only: diagnostics + exit code
-geml check --json file.geml      # machine-readable: diagnostics array (or {"error":…} on IO failure)
-geml        file.geml            # full document-model JSON
-geml render file.geml -o out.html  # one self-contained, interactive HTML file
-geml export file.geml -o out.md    # project to GitHub-Flavored Markdown (lossy; notes on stderr)
-geml convert in.md     -o out.geml # Markdown -> GEML
-geml fmt    file.geml            # canonical re-format (idempotent)
-geml history <commit|verify|show|restore> file.geml [...]   # .gemlhistory sidecar
-geml --help | --version          # --version --json prints {"parser","spec"}
-```
-
-The agent loop: write `.geml` → `geml check` → fix on non-zero → done.
-
-## Library
-
-```js
-import { parse, serialize, renderHtml, gemlToMd, mdToGeml } from "@geml/geml";
-
-const doc = parse(src);                 // { kind:"document", children, ids, diagnostics }
-const ok  = !doc.diagnostics.some(d => d.severity === "error");
-const html = renderHtml(doc);           // one self-contained HTML string
-const md   = gemlToMd(doc).md;          // GitHub-Flavored Markdown (lossy)
-const geml = mdToGeml(markdown).geml;   // the inverse
-const canonical = serialize(doc);       // GEML text; parse(serialize(parse(x))) is stable
-```
-
-`parse(src, { resolveDoc })` enables cross-document reference checking — pass a
-function that returns another file's source by path (or `null`).
-
-## Documentation
-
-Full normative spec, history-sidecar spec, and format comparison live in the
-[repository](https://github.com/xiongjy2104/geml-spec). The spec is itself
-written in GEML (`GEML-spec.geml`) and parsed clean on every test run.
-
-## License
-
-MIT.
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/geml-spec/geml/main/docs/assets/logo/geml-logo-dark.svg">
+    <img src="https://raw.githubusercontent.com/geml-spec/geml/main/docs/assets/logo/geml-logo-light.svg" alt="GEML" width="300">
+  </picture>
+</p>
+
+# @geml/geml
+
+Reference parser, validator, renderer, and CLI for **GEML** — the General
+Expressive Markup Language: a plain-text document format that stays legible to
+people and reliable for machines. Every kind of structured content — code,
+tables, diagrams, math, callouts, metadata — is carried on **one** primitive,
+the typed block:
+
+```
+=== code {#hello lang=python}
+print("hi")
+===
+```
+
+References are checked at build time (a dangling `#id` is an error, not a silent
+dead link), and the parser emits a document-model JSON with `diagnostics`, so
+agents and CI get a structured pass/fail signal.
+
+## Install
+
+```sh
+npm install -g @geml/geml   # global CLI — installs the `geml` command
+# or, per project:
+npm install @geml/geml      # library + local bin
+```
+
+Requires Node ≥ 18.
+
+## CLI
+
+Every command reads a file path, or `-` for stdin. Exit codes: `0` ok ·
+`1` document/operation error · `2` usage error.
+
+```sh
+geml check  file.geml            # validate only: diagnostics + exit code
+geml check --json file.geml      # machine-readable: diagnostics array (or {"error":…} on IO failure)
+geml        file.geml            # full document-model JSON
+geml render file.geml -o out.html  # one self-contained, interactive HTML file
+geml export file.geml -o out.md    # project to GitHub-Flavored Markdown (lossy; notes on stderr)
+geml convert in.md     -o out.geml # Markdown -> GEML
+geml fmt    file.geml            # canonical re-format (idempotent)
+geml history <commit|verify|show|restore> file.geml [...]   # .gemlhistory sidecar
+geml --help | --version          # --version --json prints {"parser","spec"}
+```
+
+The agent loop: write `.geml` → `geml check` → fix on non-zero → done.
+
+## Library
+
+```js
+import { parse, serialize, renderHtml, gemlToMd, mdToGeml } from "@geml/geml";
+
+const doc = parse(src);                 // { kind:"document", children, ids, diagnostics }
+const ok  = !doc.diagnostics.some(d => d.severity === "error");
+const html = renderHtml(doc);           // one self-contained HTML string
+const md   = gemlToMd(doc).md;          // GitHub-Flavored Markdown (lossy)
+const geml = mdToGeml(markdown).geml;   // the inverse
+const canonical = serialize(doc);       // GEML text; parse(serialize(parse(x))) is stable
+```
+
+`parse(src, { resolveDoc })` enables cross-document reference checking — pass a
+function that returns another file's source by path (or `null`).
+
+## Documentation
+
+Full normative spec, history-sidecar spec, and format comparison live in the
+[repository](https://github.com/geml-spec/geml). The spec is itself
+written in GEML (`GEML-spec.geml`) and parsed clean on every test run.
+
+## License
+
+MIT.

package/codemap/adapters/crg.mjs

@@ -0,0 +1,109 @@
+// geml-code-graph adapter: code-review-graph SQLite (`graph.db`, tree-sitter based) →
+// the exchange format of docs/DESIGN-geml-code-graph.md §3 (symbols + edges).
+//
+// Everything this adapter emits is syntax-level extraction, so per §3.3 every
+// symbol and edge carries resolution:"heuristic"; resolved targets get
+// confidence:"medium", unresolved ones become `to_text` rows (confidence:"low").
+// CONTAINS is not an edge — containment is document structure (GEP-0002).
+//
+// Beyond the core schema, symbols may carry optional navigation flags the
+// engine knows about: `entry` (a `main` function) and `flow_crit` (max
+// criticality of execution flows entered at this symbol, when >= 0.6).
+import { DatabaseSync } from "node:sqlite";
+
+const EDGE_KIND = {
+  CALLS: "calls",
+  IMPORTS_FROM: "imports",
+  INHERITS: "inherits",
+  TESTED_BY: "tested-by",
+  REFERENCES: "references",
+};
+
+export function extract({ db: dbPath, root }) {
+  const db = new DatabaseSync(dbPath);
+  const rootFs = root.replace(/\\/g, "/").replace(/\/?$/, "/");
+  const rel = (p) => {
+    p = String(p).replace(/\\/g, "/");
+    return p.startsWith(rootFs) ? p.slice(rootFs.length) : p;
+  };
+
+  const rows = db.prepare(
+    "SELECT id, kind, name, qualified_name, file_path, line_start, line_end, language, is_test FROM nodes",
+  ).all();
+
+  // anchor = "<lang>:<relfile>#<name>", File symbols just "<lang>:<relfile>".
+  // Same-file same-name collisions get ~2, ~3 … ordered by line_start so the
+  // numbering is stable across rebuilds (§4.2 / risk 3).
+  const byKey = new Map();
+  for (const r of rows) {
+    const key = `${r.language ?? "unknown"}:${rel(r.file_path)}#${r.name}`;
+    if (!byKey.has(key)) byKey.set(key, []);
+    byKey.get(key).push(r);
+  }
+  const anchorOf = new Map(); // node rowid -> anchor
+  for (const [key, list] of byKey) {
+    list.sort((a, b) => (a.line_start ?? 0) - (b.line_start ?? 0) || a.id - b.id);
+    list.forEach((r, i) => {
+      const base = r.kind === "File" ? key.slice(0, key.lastIndexOf("#")) : key;
+      anchorOf.set(r.id, i === 0 ? base : `${base}~${i + 1}`);
+    });
+  }
+
+  // Navigation flags from engine-specific tables.
+  const mains = new Set(
+    db.prepare("SELECT id FROM nodes WHERE kind='Function' AND name='main'").all().map((r) => r.id),
+  );
+  const flowCrit = new Map();
+  try {
+    for (const r of db.prepare(
+      "SELECT entry_point_id id, max(criticality) c FROM flows GROUP BY 1 HAVING c >= 0.6",
+    ).all()) flowCrit.set(r.id, r.c);
+  } catch { /* no flows table */ }
+
+  const symbols = rows.map((r) => {
+    const s = {
+      anchor: anchorOf.get(r.id),
+      lang: r.language ?? "unknown",
+      kind: r.kind,
+      name: r.name,
+      file: rel(r.file_path),
+      line_start: r.line_start ?? undefined,
+      line_end: r.line_end ?? undefined,
+      is_test: r.is_test ? true : undefined,
+      entry: mains.has(r.id) ? true : undefined,
+      flow_crit: flowCrit.get(r.id),
+      resolution: "heuristic",
+    };
+    return s;
+  });
+
+  const idByQual = new Map(rows.map((r) => [r.qualified_name, r.id]));
+  const edges = [];
+  for (const e of db.prepare(
+    "SELECT kind, source_qualified, target_qualified, file_path, line FROM edges",
+  ).all()) {
+    const kind = EDGE_KIND[e.kind];
+    if (!kind) continue; // CONTAINS and anything unknown
+    const fromId = idByQual.get(e.source_qualified);
+    if (fromId === undefined) continue; // dangling source: nothing to attach to
+    const toId = idByQual.get(e.target_qualified);
+    const edge = {
+      kind,
+      from: anchorOf.get(fromId),
+      resolution: "heuristic",
+      site: { file: rel(e.file_path), line: e.line ?? 0 },
+    };
+    if (toId !== undefined) {
+      edge.to = anchorOf.get(toId);
+      edge.confidence = "medium";
+    } else {
+      // Keep only a readable short name for the unresolved target (§5.2's
+      // calls-unresolved line) — qualified names here are often paths.
+      edge.to_text = String(e.target_qualified).replace(/\\/g, "/").split("/").pop();
+      edge.confidence = "low";
+    }
+    edges.push(edge);
+  }
+
+  return { symbols, edges };
+}

package/codemap/adapters/joern.mjs

@@ -0,0 +1,131 @@
+// geml-code-graph adapter: Joern CPG export → exchange format (DESIGN §3.2/3.4).
+//
+// Consumes the raw JSONL written by joern-export.sc (methods.jsonl +
+// calls.jsonl) — so the node side never touches the JVM. Everything here is
+// resolution:"cpg". Confidence mapping (§3.4):
+//   exactly one internal callee            → high
+//   several internal callees (dispatch)    → first as `to` + the rest as
+//                                            `candidates`, medium
+//   no internal callee (external/pointer)  → to_text, low (unresolved)
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const LANG_BY_EXT = {
+  c: "c", h: "c", cc: "cpp", cpp: "cpp", cxx: "cpp", hpp: "cpp", hh: "cpp",
+  java: "java", js: "javascript", mjs: "javascript", ts: "typescript",
+  py: "python", kt: "kotlin", go: "go", rb: "ruby", swift: "swift",
+  cs: "csharp", php: "php",
+};
+const langOf = (file) => LANG_BY_EXT[file.split(".").pop()?.toLowerCase()] ?? "unknown";
+
+const readJsonl = (p) => readFileSync(p, "utf8").split("\n").filter(Boolean).map((l) => JSON.parse(l));
+
+export function extract({ raw, root }) {
+  const rootFs = root ? root.replace(/\\/g, "/").replace(/\/?$/, "/") : "";
+  const rel = (p) => {
+    p = String(p).replace(/\\/g, "/");
+    return rootFs && p.startsWith(rootFs) ? p.slice(rootFs.length) : p.replace(/^\//, "");
+  };
+
+  const methods = readJsonl(join(raw, "methods.jsonl"));
+  const calls = readJsonl(join(raw, "calls.jsonl"));
+
+  // Identity: fullName|signature|file — the same tuple joern-export.sc keys on.
+  const keyOf = (m) => `${m.fullName}|${m.signature}|${rel(m.file)}`;
+
+  // Some frontends (javasrc2cpg: constructors, overload/bridge pairs) emit
+  // several method records with an IDENTICAL fullName|signature|file — one
+  // logical method must become one symbol, so dedupe by key first, keeping the
+  // record with the widest line span (the real body over a synthetic stub).
+  const byKey = new Map();
+  for (const m of methods) {
+    const k = keyOf(m);
+    const prev = byKey.get(k);
+    if (!prev || (m.lineEnd ?? 0) - (m.lineStart ?? 0) > (prev.lineEnd ?? 0) - (prev.lineStart ?? 0)) {
+      byKey.set(k, m);
+    }
+  }
+  const uniqueMethods = [...byKey.values()];
+
+  // Anchors: "<lang>:<relfile>#<name>(<sig>)"; same-file same-name-and-sig
+  // duplicates that remain distinct (different fullName) get ~2, ~3 by line order.
+  const byAnchorBase = new Map();
+  for (const m of uniqueMethods) {
+    const base = `${langOf(m.file)}:${rel(m.file)}#${m.name}(${m.signature})`;
+    if (!byAnchorBase.has(base)) byAnchorBase.set(base, []);
+    byAnchorBase.get(base).push(m);
+  }
+  const anchorByKey = new Map();
+  for (const [base, list] of byAnchorBase) {
+    list.sort((a, b) => (a.lineStart ?? 0) - (b.lineStart ?? 0));
+    list.forEach((m, i) => anchorByKey.set(keyOf(m), i === 0 ? base : `${base}~${i + 1}`));
+  }
+
+  // Class-qualified display names: in a class language a method's natural
+  // short name is `Cls.method` — bare names ("invoke", "execute") repeat in
+  // every other class and read as noise. Constructors are `Cls.new`, static
+  // initialisers `Cls.static{}`. C (no classes: fullName has no dot) keeps
+  // plain names. The anchor keeps the raw identity — presentation only.
+  const displayName = (m) => {
+    const head = String(m.fullName ?? "").split(":")[0]; // pkg.Outer$Inner.method
+    const di = head.lastIndexOf(".");
+    const owner = di > 0 ? head.slice(0, di) : "";
+    const simple = (owner.split(".").pop() || "").split("$").pop() || "";
+    if (m.name === "<init>") return simple ? `${simple}.new` : "new";
+    if (m.name === "<clinit>") return simple ? `${simple}.static{}` : "static{}";
+    return simple ? `${simple}.${m.name}` : m.name;
+  };
+
+  const symbols = [];
+  const seenFiles = new Set();
+  for (const m of uniqueMethods) {
+    const file = rel(m.file);
+    symbols.push({
+      anchor: anchorByKey.get(keyOf(m)),
+      lang: langOf(file),
+      kind: "Function",
+      name: displayName(m),
+      file,
+      line_start: m.lineStart ?? undefined,
+      line_end: m.lineEnd ?? undefined,
+      signature: m.signature || undefined,
+      entry: m.name === "main" ? true : undefined,
+      resolution: "cpg",
+    });
+    // Derive one File symbol per source file so emit gets stable heading ids.
+    if (!seenFiles.has(file)) {
+      seenFiles.add(file);
+      symbols.push({
+        anchor: `${langOf(file)}:${file}`,
+        lang: langOf(file),
+        kind: "File",
+        name: file.split("/").pop(),
+        file,
+        resolution: "cpg",
+      });
+    }
+  }
+
+  const edges = [];
+  for (const c of calls) {
+    const from = anchorByKey.get(`${c.callerFullName}|${c.callerSignature}|${rel(c.callerFile)}`);
+    if (!from) continue;
+    const site = { file: rel(c.callerFile), line: c.line ?? 0 };
+    const targets = (c.callees ?? [])
+      .map((t) => anchorByKey.get(`${t.fullName}|${t.signature}|${rel(t.file)}`))
+      .filter(Boolean);
+    if (targets.length === 0) {
+      edges.push({ kind: "calls", from, to_text: c.name, resolution: "cpg", confidence: "low", site });
+    } else if (targets.length === 1) {
+      edges.push({ kind: "calls", from, to: targets[0], resolution: "cpg", confidence: "high", site });
+    } else {
+      const [first, ...rest] = [...new Set(targets)].sort();
+      edges.push({
+        kind: "calls", from, to: first, resolution: "cpg", confidence: "medium",
+        note: `dispatch, ${targets.length} candidates`, candidates: rest, site,
+      });
+    }
+  }
+
+  return { symbols, edges };
+}

package/codemap/adapters/scip.mjs

@@ -0,0 +1,229 @@
+// geml-code-graph adapter: SCIP index (index.scip, protobuf) → exchange format.
+//
+// Reads the protobuf DIRECTLY with a minimal embedded wire-format reader — the
+// scip CLI ships no Windows binary, and the fields we need are few. Everything
+// here is compiler-grade resolution, so edges are resolution:"cpg"; a direct
+// hit is confidence:"high"; a call to an interface/abstract member with known
+// implementations becomes medium + candidates; references to symbols not
+// defined in the project become to_text (unresolved, low).
+//
+// Produce the index with scip-typescript (TS/JS):
+//   npx --yes @sourcegraph/scip-typescript index --output index.scip
+//
+// Caller attribution: a reference occurrence belongs to the innermost function
+// DEFINITION whose enclosing_range contains it. scip-typescript emits
+// enclosing_range on definition occurrences; if absent we fall back to "the
+// nearest preceding definition in the file" and mark the adapter degraded.
+import { readFileSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
+
+// ---- minimal protobuf wire reader ------------------------------------------
+function varint(buf, p) {
+  let x = 0n, s = 0n, b;
+  do { b = buf[p.i++]; x |= BigInt(b & 0x7f) << s; s += 7n; } while (b & 0x80);
+  return x;
+}
+// Iterate fields of one message region [start, end): yields {no, wt, val|sub}.
+function* fields(buf, start, end) {
+  const p = { i: start };
+  while (p.i < end) {
+    const key = Number(varint(buf, p));
+    const no = key >> 3, wt = key & 7;
+    if (wt === 0) yield { no, wt, val: varint(buf, p) };
+    else if (wt === 1) { yield { no, wt, val: buf.readBigUInt64LE(p.i) }; p.i += 8; }
+    else if (wt === 2) { const len = Number(varint(buf, p)); yield { no, wt, a: p.i, b: p.i + len }; p.i += len; }
+    else if (wt === 5) { yield { no, wt, val: BigInt(buf.readUInt32LE(p.i)) }; p.i += 4; }
+    else throw new Error(`scip: unsupported wire type ${wt}`);
+  }
+}
+const str = (buf, f) => buf.toString("utf8", f.a, f.b);
+// repeated int32, packed (len-delimited varints) or single varint value
+function packedInts(buf, f, out) {
+  if (f.wt === 0) { out.push(Number(f.val)); return; }
+  const p = { i: f.a };
+  while (p.i < f.b) out.push(Number(varint(buf, p)));
+}
+
+// ---- SCIP field numbers (scip.proto) ---------------------------------------
+// Index: metadata=1, documents=2, external_symbols=3
+// Document: relative_path=1, occurrences=2, symbols=3, language=4
+// Occurrence: range=1, symbol=2, symbol_roles=3, enclosing_range=7
+// SymbolInformation: symbol=1, relationships=4, display_name=6
+// Relationship: symbol=1, is_implementation=3
+const ROLE_DEFINITION = 0x1;
+
+function parseScip(path) {
+  const buf = readFileSync(path);
+  const docs = [];
+  let projectRoot = "";
+  for (const f of fields(buf, 0, buf.length)) {
+    if (f.no === 1 && f.wt === 2) {
+      // Metadata → project_root (field 3): the directory the indexer ran in.
+      // Needed to re-anchor document paths when a SUBPROJECT of the repo was
+      // indexed (scip paths are relative to the indexed project, not the repo).
+      for (const m of fields(buf, f.a, f.b)) {
+        if (m.no === 3 && m.wt === 2) projectRoot = str(buf, m);
+      }
+      continue;
+    }
+    if (f.no !== 2 || f.wt !== 2) continue;
+    const doc = { path: "", occ: [], rel: [] };
+    for (const d of fields(buf, f.a, f.b)) {
+      if (d.no === 1 && d.wt === 2) doc.path = str(buf, d);
+      else if (d.no === 2 && d.wt === 2) {
+        const o = { range: [], symbol: "", roles: 0, enclosing: [] };
+        for (const x of fields(buf, d.a, d.b)) {
+          if (x.no === 1) packedInts(buf, x, o.range);
+          else if (x.no === 2 && x.wt === 2) o.symbol = str(buf, x);
+          else if (x.no === 3 && x.wt === 0) o.roles = Number(x.val);
+          else if (x.no === 7) packedInts(buf, x, o.enclosing);
+        }
+        doc.occ.push(o);
+      } else if (d.no === 3 && d.wt === 2) {
+        // SymbolInformation → implementation relationships only
+        let sym = "";
+        const impl = [];
+        for (const x of fields(buf, d.a, d.b)) {
+          if (x.no === 1 && x.wt === 2) sym = str(buf, x);
+          else if (x.no === 4 && x.wt === 2) {
+            let rsym = "", isImpl = false;
+            for (const r of fields(buf, x.a, x.b)) {
+              if (r.no === 1 && r.wt === 2) rsym = str(buf, r);
+              else if (r.no === 3 && r.wt === 0) isImpl = r.val !== 0n;
+            }
+            if (isImpl && rsym) impl.push(rsym);
+          }
+        }
+        if (impl.length) doc.rel.push({ sym, impl });
+      }
+    }
+    docs.push(doc);
+  }
+  return { docs, projectRoot };
+}
+
+// ---- SCIP symbol grammar helpers -------------------------------------------
+// e.g. "scip-typescript npm @geml/geml 1.0.0 src/`geml.ts`/parse()."
+const isFuncSym = (s) => s.endsWith("().");
+const nameOf = (s) => {
+  // Class members read class-qualified (`RenderCtx.block`), constructors as
+  // `Cls.new` — free functions (no `Owner#` scope) keep their plain name.
+  if (/`?<constructor>`?\(\)\.$/.test(s)) {
+    const cm = /([A-Za-z0-9_$]+)#`?<constructor>`?\(\)\.$/.exec(s);
+    return cm ? `${cm[1]}.new` : "new";
+  }
+  const m = /(?:([A-Za-z0-9_$]+)#)?([^\/#.`]+)\(\)\.$/.exec(s);
+  if (m) return m[1] ? `${m[1]}.${m[2]}` : m[2];
+  return s.split("/").pop() ?? s;
+};
+
+export function extract({ raw: scipPath, root }) {
+  const { docs, projectRoot } = parseScip(scipPath);
+  // scip-typescript emits OS-native separators in relative_path on Windows;
+  // the codemap profile is posix throughout.
+  for (const d of docs) d.path = d.path.replace(/\\/g, "/");
+  // Document paths are relative to the INDEXED project (metadata.project_root),
+  // which may be a subdirectory of the codemap's --root. Re-anchor them so a
+  // multi-language merge keeps one coherent repo-relative path space.
+  if (projectRoot && root) {
+    const norm = (p) => p.replace(/^file:\/\/\/?/, "").replace(/\\/g, "/").replace(/\/+$/, "").toLowerCase();
+    const rootN = norm(resolvePath(root));
+    const projN = norm(decodeURIComponent(projectRoot));
+    if (projN !== rootN && projN.startsWith(rootN + "/")) {
+      const prefix = decodeURIComponent(projectRoot).replace(/^file:\/\/\/?/, "").replace(/\\/g, "/").replace(/\/+$/, "").slice(rootN.length + 1);
+      for (const d of docs) d.path = `${prefix}/${d.path}`;
+    }
+  }
+
+  // range = [startLine, startChar, endLine(, endChar)] (0-based); normalize.
+  const spanOf = (r) => (r.length === 3 ? [r[0], r[0]] : [r[0], r[2]]);
+
+  // 1. definitions of function symbols
+  const defs = new Map(); // symbol -> {file, name, line_start, line_end, encl:[sl,el]}
+  for (const d of docs) {
+    for (const o of d.occ) {
+      if (!(o.roles & ROLE_DEFINITION) || !isFuncSym(o.symbol)) continue;
+      const [nl] = spanOf(o.range);
+      const encl = o.enclosing.length ? spanOf(o.enclosing) : [nl, nl];
+      const prev = defs.get(o.symbol);
+      // keep the widest definition (impl over overload signatures)
+      if (!prev || encl[1] - encl[0] > prev.encl[1] - prev.encl[0]) {
+        defs.set(o.symbol, { file: d.path, name: nameOf(o.symbol), line_start: encl[0] + 1, line_end: encl[1] + 1, encl });
+      }
+    }
+  }
+  const enclosingDegraded = [...defs.values()].every((v) => v.encl[0] === v.encl[1]);
+
+  // implementations map: interface/abstract member symbol -> implementing symbols
+  const implOf = new Map();
+  for (const d of docs) {
+    for (const { sym, impl } of d.rel) {
+      for (const target of impl) {
+        if (!implOf.has(target)) implOf.set(target, []);
+        implOf.get(target).push(sym);
+      }
+    }
+  }
+
+  const symbols = [];
+  const seenFiles = new Set();
+  for (const [sym, v] of defs) {
+    symbols.push({
+      anchor: sym, lang: "typescript", kind: "Function", name: v.name,
+      file: v.file, line_start: v.line_start, line_end: v.line_end,
+      entry: v.name === "main" ? true : undefined,
+      resolution: "cpg",
+    });
+    if (!seenFiles.has(v.file)) {
+      seenFiles.add(v.file);
+      symbols.push({ anchor: `file:${v.file}`, lang: "typescript", kind: "File", name: v.file.split("/").pop(), file: v.file, resolution: "cpg" });
+    }
+  }
+
+  // 2. calls: reference occurrences of function symbols, attributed to the
+  //    innermost containing definition of the same file.
+  const perFileDefs = new Map(); // file -> defs sorted by span size asc
+  for (const [sym, v] of defs) {
+    if (!perFileDefs.has(v.file)) perFileDefs.set(v.file, []);
+    perFileDefs.get(v.file).push({ sym, ...v });
+  }
+  for (const list of perFileDefs.values()) list.sort((a, b) => (a.encl[1] - a.encl[0]) - (b.encl[1] - b.encl[0]));
+  const callerAt = (file, line) => {
+    const list = perFileDefs.get(file);
+    if (!list) return undefined;
+    if (!enclosingDegraded) {
+      for (const d of list) if (line >= d.encl[0] && line <= d.encl[1]) return d.sym; // innermost first (sorted asc)
+      return undefined;
+    }
+    // degraded: nearest preceding definition start
+    let best;
+    for (const d of list) if (d.encl[0] <= line && (!best || d.encl[0] > best.encl[0])) best = d;
+    return best?.sym;
+  };
+
+  const edges = [];
+  for (const d of docs) {
+    for (const o of d.occ) {
+      if ((o.roles & ROLE_DEFINITION) || !isFuncSym(o.symbol)) continue;
+      const [line] = spanOf(o.range);
+      const from = callerAt(d.path, line);
+      if (!from || from === o.symbol) continue;
+      const site = { file: d.path, line: line + 1 };
+      if (defs.has(o.symbol)) {
+        const impls = (implOf.get(o.symbol) ?? []).filter((s) => defs.has(s));
+        if (impls.length) {
+          edges.push({ kind: "calls", from, to: o.symbol, resolution: "cpg", confidence: "medium", note: `dispatch, ${impls.length + 1} candidates`, candidates: [...new Set(impls)].sort(), site });
+        } else {
+          edges.push({ kind: "calls", from, to: o.symbol, resolution: "cpg", confidence: "high", site });
+        }
+      } else {
+        edges.push({ kind: "calls", from, to_text: nameOf(o.symbol), resolution: "cpg", confidence: "low", site });
+      }
+    }
+  }
+
+  if (enclosingDegraded) {
+    console.error("scip adapter: no enclosing_range in this index — caller attribution degraded to nearest-preceding definition");
+  }
+  return { symbols, edges };
+}