@geml/geml 1.0.0 → 1.1.1

package/codemap/verify.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+// geml-code-graph verify — the codemap's correctness oracle, two passes:
+//
+//   1. `geml check` over every .geml (document structure, id uniqueness,
+//      native references).
+//   2. The codemap-profile pass (docs/codemap-profile.md): CSV cells and meta
+//      values are opaque to the GEML standard BY DESIGN (the standard stays
+//      untouched), so edge integrity is checked here — the from/to columns of
+//      #calls / #called-by / #ref-by tables and every meta `entry` value must
+//      resolve (`#id` in the same document, `doc.geml#id` in a sibling).
+//      A renamed or deleted method therefore fails the build, not the reader.
+//
+//   geml codemap verify [dir] [--geml <path-to-geml.js|geml>]
+import { readdirSync, existsSync, readFileSync } from "node:fs";
+import { join, resolve, dirname, relative } from "node:path";
+import { posix } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const args = process.argv.slice(2);
+const flagI = args.indexOf("--geml");
+if (args.includes("--help") || args.includes("-h")) {
+  console.error("usage: geml codemap verify [dir] [--geml <path>]   (dir defaults to ./.geml-code-graph)");
+  process.exit(2);
+}
+const dir = args.find((a, i) => !a.startsWith("-") && (flagI < 0 || i !== flagI + 1)) || ".geml-code-graph";
+const rootDir = resolve(dir);
+
+// Resolve the geml CLI (pass 1) and the parser API (pass 2).
+const localParser = resolve(dirname(fileURLToPath(import.meta.url)), "../dist/geml.js");
+let cli = flagI >= 0 ? args[flagI + 1] : undefined;
+if (!cli) cli = existsSync(localParser) ? localParser : "geml";
+const runCheck = (file) => cli.endsWith(".js")
+  ? spawnSync(process.execPath, [cli, "check", file], { encoding: "utf8" })
+  : spawnSync(cli, ["check", file], { encoding: "utf8", shell: process.platform === "win32" });
+if (!existsSync(localParser)) {
+  console.error("verify: the profile pass needs the built parser (cd geml-parser && npm install && npm run build)");
+  process.exit(1);
+}
+const { parse } = await import(`file://${localParser.replace(/\\/g, "/")}`);
+
+const files = [];
+const walk = (d) => {
+  for (const e of readdirSync(d, { withFileTypes: true })) {
+    const p = join(d, e.name);
+    if (e.isDirectory()) walk(p);
+    else if (e.name.endsWith(".geml")) files.push(p);
+  }
+};
+walk(rootDir);
+files.sort();
+
+// ---- pass 1: geml check ----
+let failed = 0;
+for (const f of files) {
+  const r = runCheck(f);
+  if (r.status !== 0) {
+    failed++;
+    console.error(`FAIL ${f}`);
+    console.error((r.stderr || r.stdout || "").split("\n").slice(0, 4).map((l) => `  ${l}`).join("\n"));
+  }
+}
+
+// ---- pass 2: codemap profile references ----
+const REF_TABLES = new Set(["calls", "called-by", "ref-by"]);
+const relDoc = (f) => relative(rootDir, f).replace(/\\/g, "/");
+const docs = new Map(); // relPath -> { ids:Set, blocks }
+const collectIds = (blocks, ids) => {
+  for (const b of blocks) {
+    if (b.id) ids.add(b.id);
+    if (b.children) collectIds(b.children, ids);
+    if (b.items) for (const it of b.items) if (it.children) collectIds(it.children, ids);
+  }
+};
+for (const f of files) {
+  const doc = parse(readFileSync(f, "utf8"));
+  const ids = new Set();
+  collectIds(doc.children, ids);
+  docs.set(relDoc(f), { ids, blocks: doc.children });
+}
+
+let refErrors = 0;
+const err = (doc, where, msg) => {
+  refErrors++;
+  console.error(`REF  ${doc} ${where}: ${msg}`);
+};
+const checkRef = (fromDoc, where, ref) => {
+  ref = String(ref).trim();
+  if (!ref) return err(fromDoc, where, "empty reference cell");
+  const h = ref.indexOf("#");
+  if (h < 0) return err(fromDoc, where, `not a reference: \`${ref}\``);
+  let targetDoc = fromDoc;
+  if (h > 0) targetDoc = posix.normalize(posix.join(posix.dirname(fromDoc), ref.slice(0, h)));
+  const id = ref.slice(h + 1);
+  const target = docs.get(targetDoc);
+  if (!target) return err(fromDoc, where, `cannot resolve document \`${ref.slice(0, h)}\``);
+  // reads/writes values may carry a plain-text `.member` suffix (ids never contain '.')
+  const bare = id.split(".")[0];
+  if (!target.ids.has(bare)) return err(fromDoc, where, `unresolved reference \`${ref}\``);
+};
+
+for (const [docPath, { blocks }] of docs) {
+  for (const b of blocks) {
+    if (b.kind !== "block") continue;
+    if (b.type === "table" && REF_TABLES.has(b.id) && b.table) {
+      const fromCol = b.table.columns.indexOf("from");
+      const toCol = b.table.columns.indexOf("to");
+      if (fromCol < 0 || toCol < 0) { err(docPath, `#${b.id}`, "missing from/to columns"); continue; }
+      b.table.rows.forEach((row, i) => {
+        checkRef(docPath, `#${b.id} row ${i + 1} from`, row[fromCol]?.text ?? "");
+        checkRef(docPath, `#${b.id} row ${i + 1} to`, row[toCol]?.text ?? "");
+      });
+    }
+    if (b.type === "meta" && b.data?.entry) {
+      for (const ref of String(b.data.entry).split(/\s+/).filter(Boolean)) {
+        checkRef(docPath, "meta entry", ref);
+      }
+    }
+  }
+}
+
+console.error(
+  `verify: ${files.length - failed}/${files.length} documents pass geml check; `
+  + `profile references: ${refErrors === 0 ? "all resolve" : `${refErrors} dangling`}`,
+);
+process.exit(failed || refErrors ? 1 : 0);

package/dist/geml.d.ts

@@ -68,3 +68,8 @@ export interface ParseOptions {
     resolveDoc?: (doc: string) => string | null;
 }
 export declare function parse(source: string, opts?: ParseOptions): Document;
+export interface Span {
+    start: number;
+    end: number;
+}
+export declare function blockSpans(source: string): Map<string, Span>;

package/dist/geml.js

@@ -9,8 +9,10 @@
 // media embeds, links, auto-references, footnotes) and build-time reference
 // validation (§8 — unique ids, resolvable internal/cross-document references).
 import { readFileSync, writeFileSync } from "node:fs";
-import { basename, dirname, resolve as resolvePath } from "node:path";
-import { commit, restore, verify } from "./history.js";
+import { basename, dirname, join, resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import { commit, restore, verify, listRevisions, resolveContent, firstChangedContent } from "./history.js";
 import { renderHtml } from "./render.js";
 import { coerce, parseAttrs } from "./attrs.js";
 import { parseInline } from "./inline.js";
@@ -32,12 +34,11 @@ const REGISTRY = {
     table: "raw", // structured table parsing lands in M3
     output: "raw", // captured result of a code block (stored, never executed)
     note: "flow",
-    aside: "flow",
     meta: "data",
 };
 // §7: built-in diagram renderer registry. Unknown formats are a warning (the
 // processor keeps the body raw rather than interpreting it).
-const DIAGRAM_RENDERERS = new Set(["mermaid", "graphviz", "dot", "d2", "plantuml", "geml-chart"]);
+const DIAGRAM_RENDERERS = new Set(["mermaid", "graphviz", "dot", "d2", "plantuml", "geml-chart", "geml-code-graph"]);
 // ---------------------------------------------------------------------------
 // Lexical helpers
 // ---------------------------------------------------------------------------
@@ -143,6 +144,11 @@ function parseList(lines, i, base, ctx) {
             stack.push({ list: cur, indent: mk.indent });
         }
         else {
+            // §5: a change of marker type (bullet ↔ ordered) at the same level ends
+            // this list; scanBlocks then opens a fresh one at this marker. Without it,
+            // `- a` then `1. b` would merge into one mis-typed list (CommonMark §5.3).
+            if (mk.ordered !== top.list.ordered)
+                break;
             cur = top.list;
         }
         if (prevBlank && cur.items.length > 0)
@@ -265,6 +271,21 @@ function scanBlocks(lines, base, ctx) {
                         }
                         (ctx.charts ??= []).push({ block, line: openLineNo });
                     }
+                    else if (fmt === "geml-code-graph") {
+                        // Code-graph embed (GEP-0003): the ONLY attribute is src=, pointing
+                        // at a codemap document; roots/depth come from that document's meta
+                        // ("view config travels with the data"). Body is empty.
+                        const src = attrs.attrs["src"];
+                        if (typeof src !== "string" || src === "") {
+                            diags.push({ severity: "warning", message: "geml-code-graph: missing `src=` (nothing to render)", line: openLineNo });
+                        }
+                        else if (ctx.resolveDoc && ctx.resolveDoc(src) === null) {
+                            diags.push({ severity: "warning", message: `geml-code-graph: cannot resolve document \`${src}\``, line: openLineNo });
+                        }
+                        if (body.length > 0 && body.some((l) => l.trim() !== "")) {
+                            diags.push({ severity: "warning", message: "geml-code-graph body is ignored; the embed is configured by `src=` alone", line: openLineNo });
+                        }
+                    }
                     else if (typeof fmt === "string" && !DIAGRAM_RENDERERS.has(fmt)) {
                         // §7: warn on a diagram format with no registered renderer.
                         diags.push({ severity: "warning", message: `no registered renderer for diagram format \`${fmt}\`; body kept raw`, line: openLineNo });
@@ -424,12 +445,115 @@ function resolveCharts(ctx) {
 }
 export function parse(source, opts = {}) {
     const lines = source.replace(/\r\n?/g, "\n").split("\n");
-    const ctx = { diags: [], ids: new Map(), refs: [], meta: collectMeta(lines) };
+    const ctx = { diags: [], ids: new Map(), refs: [], meta: collectMeta(lines), resolveDoc: opts.resolveDoc };
     const children = scanBlocks(lines, 0, ctx);
     resolveCharts(ctx);
     validateRefs(ctx, opts);
     return { kind: "document", children, ids: [...ctx.ids.keys()], diagnostics: ctx.diags };
 }
+// The id that a fence/heading line defines, matching how scanBlocks derives it
+// (parseAttrs for the attribute object; heading text slug when no explicit id).
+function idOfHeading(braces, text) {
+    return (braces ? parseAttrs(braces).id : undefined) ?? slug(text);
+}
+// Walk `lines` exactly as scanBlocks does — same fence close rules (equal-length
+// or labeled `=== #id`), same flow-only recursion via REGISTRY — recording the
+// source span of every addressable id (typed block, heading, footnote def).
+// First definition wins, mirroring ctx.ids (a duplicate id is a build error, so
+// `get`/`set` operate on the one the parser actually registered). `base` is the
+// absolute line offset of this slice within the whole document.
+function collectSpans(lines, base, out) {
+    const add = (id, start, end) => {
+        if (!out.has(id))
+            out.set(id, { start, end });
+    };
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (line.trim() === "") {
+            i++;
+            continue;
+        }
+        const fndef = /^\[\^([^\]]+)\]:[ \t]?(.*)$/.exec(line);
+        if (fndef) {
+            add(fndef[1].trim(), base + i, base + i + 1);
+            i++;
+            continue;
+        }
+        if (/^[ \t]*%%/.test(line)) {
+            i++;
+            continue;
+        } // hidden line: no id
+        const open = FENCE_OPEN.exec(line);
+        if (open) {
+            const openLen = open[1].length;
+            const type = open[2];
+            const id = open[3] ? parseAttrs(open[3]).id : undefined;
+            const labeled = id !== undefined ? new RegExp(`^={3,}[ \\t]+#${id}[ \\t]*$`) : null;
+            let j = i + 1;
+            let closed = false;
+            for (; j < lines.length; j++) {
+                if (isCloseFence(lines[j], openLen) || (labeled && labeled.test(lines[j]))) {
+                    closed = true;
+                    break;
+                }
+            }
+            const end = closed ? j + 1 : j;
+            if (id !== undefined)
+                add(id, base + i, base + end);
+            // Only a flow body is scanned for nested blocks (raw/data bodies are
+            // opaque), so an id inside a `code` body is *not* addressable — exactly
+            // the parser's contract.
+            if ((REGISTRY[type] ?? "raw") === "flow") {
+                collectSpans(lines.slice(i + 1, closed ? j : end), base + i + 1, out);
+            }
+            i = end;
+            continue;
+        }
+        const h = HEADING.exec(line);
+        if (h) {
+            add(idOfHeading(h[3], h[2]), base + i, base + i + 1);
+            i++;
+            continue;
+        }
+        i++;
+    }
+}
+// Map every addressable id in `source` to its source span. Line indices align
+// with the physical lines produced by splitLines(source).
+export function blockSpans(source) {
+    const out = new Map();
+    collectSpans(source.replace(/\r\n?/g, "\n").split("\n"), 0, out);
+    return out;
+}
+// Split into physical lines while *keeping* each line's terminator, so
+// join("") is byte-exact and slicing by span never rewrites line endings.
+function splitLines(source) {
+    return source.split(/(?<=\n)/);
+}
+// Depth-first search for the document-model node carrying `id`, descending into
+// flow-block children (and list-item children) so a nested id is found too.
+function findBlockById(blocks, id) {
+    for (const b of blocks) {
+        if ((b.kind === "heading" || b.kind === "block") && b.id === id)
+            return b;
+        if (b.kind === "block" && b.children) {
+            const hit = findBlockById(b.children, id);
+            if (hit)
+                return hit;
+        }
+        if (b.kind === "list") {
+            for (const it of b.items) {
+                if (it.children) {
+                    const hit = findBlockById(it.children, id);
+                    if (hit)
+                        return hit;
+                }
+            }
+        }
+    }
+    return undefined;
+}
 // ---------------------------------------------------------------------------
 // CLI
 // ---------------------------------------------------------------------------
@@ -447,18 +571,22 @@ function parseStamp(s) {
     const [, y, mo, d, h, mi, se] = m;
     return new Date(Date.UTC(+y, +mo - 1, +d, +h, +mi, +se));
 }
-const VERSION = "1.0-draft"; // GEML spec version this CLI targets
-const PARSER_VERSION = "1.0.0"; // reference implementation; keep in sync with package.json
+const VERSION = "1.0"; // GEML spec version this CLI targets
+const PARSER_VERSION = "1.1.1"; // reference implementation; keep in sync with package.json
 const USAGE = `geml — GEML reference CLI
 
 Usage:
   geml <file.geml|->                         parse -> document-model JSON (stdout)
+  geml get <file.geml|-> #id [--json]        print ONE block by id (raw span, or --json node)
+  geml set <file.geml|-> #id [--from f][-o f] replace ONE block by id (new content: --from/stdin)
+  geml revert <file.geml> #id [--to <sel>]   restore ONE block to a past revision (sel: -N|latest|id)
   geml check <file.geml|-> [--json]          validate only: diagnostics + exit code
   geml render <file.geml|-> [-o out.html]    render to one self-contained HTML file
   geml fmt <file.geml|-> [-o out.geml]       re-serialize to canonical GEML
   geml convert <file.md|-> [-o out.geml]     Markdown -> GEML
   geml export <file.geml|-> [-o out.md]      GEML -> Markdown (lossy)
-  geml history <commit|verify|show|restore> <file.geml> [...]
+  geml history <commit|verify|show|restore|log> <file.geml> [...]
+  geml codemap <build|verify|render|serve|refresh|mcp> [...]   code-graph toolkit (geml codemap --help)
   geml --help | --version [--json]
 
 Use '-' as the file to read from stdin.
@@ -466,23 +594,36 @@ Exit codes: 0 ok · 1 document/operation error · 2 usage error.`;
 // One-line usage for each subcommand — the single source for both the error
 // shown on misuse and the `<cmd> --help` text.
 const SUBHELP = {
+    get: "usage: geml get <file.geml|-> #id [--json]",
+    set: "usage: geml set <file.geml|-> #id [--from FILE] [-o out.geml]",
     check: "usage: geml check <file.geml|-> [--json]",
     render: "usage: geml render <file.geml|-> [-o out.html]",
     convert: "usage: geml convert <file.md|-> [-o out.geml]",
     export: "usage: geml export <file.geml|-> [-o out.md]",
     fmt: "usage: geml fmt <file.geml|-> [-o out.geml]",
-    history: "usage: geml history <commit|verify|show|restore> <file.geml> [...]",
+    revert: "usage: geml revert <file.geml> #id [--to <sel>] [--changed] [--dry-run] [-o out]  (sel: -N | latest | id-prefix; default -1)",
+    history: "usage: geml history <commit|verify|show|restore|log> <file.geml> [...]",
+    codemap: `usage: geml codemap build  --root <repo>   # auto-detect languages, run the indexer(s), and merge into one codemap
+       geml codemap build  (--db <graph.db> | --adapter joern|scip --raw <in>)+ --root <repo> [--out .geml-code-graph] [--container module|dir|file] [--lang <JAVASRC|NEWC|…>] [--joern <path>] [--history [-m msg]]
+       geml codemap verify [dir]                 geml check + profile reference checks
+       geml codemap render [dir]                 every doc -> sibling .html (open index.html from disk)
+       geml codemap serve  [dir] [--port 8140] [--watch] [--background|--stop]   live viewer: pages render from .geml on request; --watch re-runs the recipe when sources change
+       geml codemap refresh [dir] [--force] [--commit] [--background|--hook]   re-run the recorded build recipe (_index/refresh.json); --commit lands it as its own commit
+       geml codemap mcp                          stdio MCP server (GEML_GRAPH_DIR or graph_dir arg)
+       (<dir> for verify/render/serve/refresh defaults to ./.geml-code-graph)`,
 };
 // Set from argv at dispatch time; when true, errors are emitted as a JSON
 // envelope so an agent that standardizes on --json never has to parse text.
 let jsonMode = false;
-// Clean one-line error + non-zero exit — never a raw Node stack trace.
-function fail(msg) {
+// Clean one-line error + non-zero exit — never a raw Node stack trace. `code`
+// is the process exit status: 2 for a usage error (the default), 1 for a
+// document/operation error. `--json` wraps it in the same {error, code} envelope.
+function fail(msg, code = 2) {
     if (jsonMode)
-        console.error(JSON.stringify({ error: msg, code: 2 }));
+        console.error(JSON.stringify({ error: msg, code }));
     else
         console.error(`error: ${msg}`);
-    process.exit(2);
+    process.exit(code);
 }
 // Read a file, or stdin when the path is "-". On failure emit a clean error.
 function readInput(file) {
@@ -580,6 +721,14 @@ function runHistory(args) {
             restore({ historyPath, gemlPath: file, revision: rev, write: true, force: args.includes("--force") });
             console.log(`restored ${file} to ${rev}`);
         }
+        else if (sub === "log") {
+            // Newest-first, with the `--to` selector for each row in the first column
+            // (`latest` for the tip, then `-1`, `-2`, …) so the output is copy-paste.
+            for (const r of listRevisions(historyPath)) {
+                const sel = r.current ? "latest" : `-${r.offset}`;
+                console.log(`${sel.padEnd(7)} ${r.id}  ${r.author ?? "-"}  ${r.summary ?? ""}`.replace(/\s+$/, ""));
+            }
+        }
         else {
             fail(`unknown history subcommand: ${sub}. Run 'geml --help'.`);
         }
@@ -638,7 +787,12 @@ function runRender(args) {
     if (!file)
         fail(SUBHELP.render);
     const doc = parse(readInput(file), { resolveDoc: resolverFor(file) });
-    const html = renderHtml(doc, { source: file === "-" ? "stdin" : basename(file) });
+    const html = renderHtml(doc, {
+        source: file === "-" ? "stdin" : basename(file),
+        // geml-code-graph embeds load + parse sibling codemap documents on demand.
+        loadDoc: resolverFor(file),
+        parseDoc: (s) => parse(s),
+    });
     if (out) {
         writeFileSync(out, html);
         console.error(`wrote ${out}`);
@@ -673,6 +827,216 @@ function runFmt(args) {
     if (doc.diagnostics.some((d) => d.severity === "error"))
         process.exit(1);
 }
+// Positional args (a file, an id) are the non-flag tokens that aren't the value
+// of a value-taking flag. `-` (stdin) is a positional, not a flag. An id may be
+// written `#id` or `id`; a leading `-` never begins an id, so this stays
+// unambiguous. `valued` lists the flags that consume the following token.
+function positionals(args, valued) {
+    const out = [];
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (valued.includes(a)) {
+            i++;
+            continue;
+        } // skip the flag *and* its value
+        if (a === "-") {
+            out.push(a);
+            continue;
+        }
+        if (a.startsWith("-"))
+            continue; // a bare flag (e.g. --json)
+        out.push(a);
+    }
+    return out;
+}
+// `geml get <file.geml|-> #id [--json]` — print ONE block, addressed by id,
+// without loading the rest of the document into context. Default output is the
+// block's exact source bytes (its full `=== … ===` span, or the source line for
+// a heading/footnote); `--json` prints that block's document-model node.
+function runGet(args) {
+    const json = args.includes("--json");
+    const [file, rawId] = positionals(args, []);
+    if (!file || !rawId)
+        fail(SUBHELP.get);
+    const id = rawId.replace(/^#/, "");
+    const source = readInput(file);
+    if (json) {
+        // The model node — same shape `geml <file>` emits for it. Parsing is needed
+        // to resolve the tree (and nested-block ids), but only the one node prints.
+        const doc = parse(source, { resolveDoc: resolverFor(file) });
+        const block = findBlockById(doc.children, id);
+        if (!block)
+            fail(`no block with id \`${id}\``, 1);
+        console.log(JSON.stringify(block, null, 2));
+        return;
+    }
+    // Raw: slice the source span byte-for-byte. No parse required, so `get` still
+    // returns the exact bytes even if the document has diagnostics elsewhere.
+    const span = blockSpans(source).get(id);
+    if (!span)
+        fail(`no block with id \`${id}\``, 1);
+    process.stdout.write(splitLines(source).slice(span.start, span.end).join(""));
+}
+// `geml set <file.geml|-> #id [--from FILE] [-o out]` — replace ONLY that
+// block's source span with new content (from --from or stdin), preserving every
+// other byte. Prints the full updated document, or writes in place with -o. The
+// splice is re-parsed and rejected if it broke the doc: `set` never writes a
+// corrupt file.
+function runSet(args) {
+    const out = flag(args, "-o") ?? flag(args, "--out");
+    const from = flag(args, "--from");
+    const [file, rawId] = positionals(args, ["-o", "--out", "--from"]);
+    if (!file || !rawId)
+        fail(SUBHELP.set);
+    const id = rawId.replace(/^#/, "");
+    // Both the document and the replacement can't come from stdin. Reject that up
+    // front — before consuming stdin — so the document read below is unambiguous.
+    if (file === "-" && from === undefined) {
+        fail("reading the document from stdin needs --from for the new content", 2);
+    }
+    const source = readInput(file);
+    // New content: an explicit --from file, else stdin.
+    let replacement;
+    if (from !== undefined) {
+        replacement = readInput(from);
+    }
+    else {
+        replacement = readInput("-");
+        if (replacement === "")
+            fail("no replacement content (use --from FILE or pipe it on stdin)", 1);
+    }
+    const updated = spliceBlock(source, id, replacement, file);
+    if (out) {
+        writeFileSync(out, updated);
+        console.error(`wrote ${out}`);
+    }
+    else
+        process.stdout.write(updated);
+}
+// Replace block #id's source span in `source` with `replacement`, preserving
+// every other byte, and GUARD the result: the re-parse must be error-free, #id
+// must survive, and no other pre-existing id may vanish (a malformed replacement
+// can silently swallow a neighbour). Returns the updated document text; on any
+// violation it calls fail() and never returns a corrupt document. Shared by
+// `set` and `revert`.
+function spliceBlock(source, id, replacement, file) {
+    const span = blockSpans(source).get(id);
+    if (!span)
+        fail(`no block with id \`${id}\``, 1);
+    const beforeIds = parse(source, { resolveDoc: resolverFor(file) }).ids;
+    // Keep the bytes before and after the target span exactly; give the new block
+    // a single trailing newline so the following block still starts on its own
+    // line (unless it is the file's last line, which may legitimately lack one).
+    const orig = splitLines(source);
+    const before = orig.slice(0, span.start);
+    const after = orig.slice(span.end);
+    let inject = replacement.replace(/\r\n?/g, "\n");
+    const lastLine = span.end >= orig.length;
+    if (!inject.endsWith("\n") && !lastLine)
+        inject += "\n";
+    const updated = before.join("") + inject + after.join("");
+    // Re-parse and refuse a broken result. A parse error or a duplicate id both
+    // surface as error diagnostics (registerId flags dups); one check covers both.
+    // Then require the target id to survive, and — because a malformed replacement
+    // can swallow a neighbour — that every other pre-existing id survives too.
+    const reparsed = parse(updated, { resolveDoc: resolverFor(file) });
+    const errs = reparsed.diagnostics.filter((d) => d.severity === "error");
+    if (errs.length) {
+        const first = errs[0];
+        fail(`replacement would break the document: ${first.message} (line ${first.line}); not written`, 1);
+    }
+    const now = new Set(reparsed.ids);
+    if (!now.has(id))
+        fail(`replacement removes id \`${id}\`; not written`, 1);
+    const dropped = beforeIds.find((x) => x !== id && !now.has(x));
+    if (dropped !== undefined) {
+        fail(`replacement would drop block \`#${dropped}\` (malformed content?); not written`, 1);
+    }
+    return updated;
+}
+// `geml revert <file.geml> #id [--to <sel>] [--changed] [--dry-run] [-o out] [--history PATH]`
+// Restore ONE block to a past revision's version — a targeted, guarded splice
+// that leaves the rest of the document untouched. <sel> (default `-1`): `-N` (N
+// revisions back from current), `latest`, or an id prefix/suffix. `--changed`
+// skips revisions that never touched the block, landing on its previous
+// *distinct* version. `--dry-run` prints what would be spliced in, writing
+// nothing. Writes in place by default (revert is a mutation); `-o` redirects.
+function runRevert(args) {
+    const changed = args.includes("--changed");
+    const dryRun = args.includes("--dry-run");
+    const out = flag(args, "-o") ?? flag(args, "--out");
+    const to = flag(args, "--to") ?? "-1";
+    const [file, rawId] = positionals(args, ["--to", "--history", "-o", "--out"]);
+    if (!file || !rawId)
+        fail(SUBHELP.revert);
+    if (file === "-")
+        fail("revert needs a real file (it reads that file's .gemlhistory)", 2);
+    const id = rawId.replace(/^#/, "");
+    const historyPath = flag(args, "--history") ?? historyPathFor(file);
+    const source = readInput(file);
+    const curSpan = blockSpans(source).get(id);
+    if (!curSpan)
+        fail(`no block with id \`${id}\` in ${file}`, 1);
+    const curBlock = splitLines(source).slice(curSpan.start, curSpan.end).join("");
+    // Extract block #id's source from a reconstructed revision (undefined if the
+    // block did not exist there).
+    const pick = (text) => {
+        const s = blockSpans(text).get(id);
+        return s ? splitLines(text).slice(s.start, s.end).join("") : undefined;
+    };
+    // Resolve the source revision, formatting any history-layer error cleanly.
+    const target = (() => {
+        try {
+            if (changed) {
+                const found = firstChangedContent(historyPath, curBlock, pick);
+                if (!found)
+                    fail(`no earlier revision changes \`${id}\``, 1);
+                return found;
+            }
+            return resolveContent(historyPath, to);
+        }
+        catch (e) {
+            fail(historyError(e, file, historyPath), 1);
+        }
+    })();
+    const oldBlock = pick(target.text);
+    if (oldBlock === undefined)
+        fail(`block \`${id}\` does not exist at revision ${target.id}`, 1);
+    if (oldBlock === curBlock) {
+        console.error(`#${id} is unchanged at ${target.id}; nothing to revert${changed ? "" : " (try --to -2, or --changed)"}`);
+        return;
+    }
+    if (dryRun) {
+        console.error(`would revert #${id} to ${target.id}:`);
+        process.stdout.write(oldBlock.endsWith("\n") ? oldBlock : oldBlock + "\n");
+        return;
+    }
+    const updated = spliceBlock(source, id, oldBlock, file);
+    const dest = out ?? file;
+    writeFileSync(dest, updated);
+    console.error(`reverted #${id} to ${target.id}${dest === file ? "" : ` -> ${dest}`}`);
+}
+// geml codemap <sub>: the code-graph toolkit ships as plain scripts in the
+// package's codemap/ directory (they are argv-driven programs, some
+// long-running like `serve`) — dispatch = run the script in a child node
+// with the remaining arguments, propagating the exit code.
+function runCodemap(args) {
+    const scripts = {
+        build: "build.mjs",
+        verify: "verify.mjs",
+        render: "render-all.mjs",
+        serve: "serve.mjs",
+        refresh: "refresh.mjs",
+        mcp: "mcp-server.mjs",
+    };
+    const sub = args[0] ?? "";
+    const script = scripts[sub];
+    if (!script)
+        fail(`unknown codemap subcommand '${sub}'.\n${SUBHELP.codemap}`);
+    const mod = join(dirname(fileURLToPath(import.meta.url)), "..", "codemap", script);
+    const r = spawnSync(process.execPath, [mod, ...args.slice(1)], { stdio: "inherit" });
+    process.exit(r.status ?? 1);
+}
 const entry = process.argv[1] ?? "";
 if (entry.endsWith("geml.js") || entry.endsWith("geml.ts")) {
     const argv = process.argv.slice(2);
@@ -697,6 +1061,15 @@ if (entry.endsWith("geml.js") || entry.endsWith("geml.ts")) {
         // stdout, exit 0 — never the `error:`-prefixed exit-2 path.
         console.log(SUBHELP[cmd]);
     }
+    else if (cmd === "get") {
+        runGet(argv.slice(1));
+    }
+    else if (cmd === "set") {
+        runSet(argv.slice(1));
+    }
+    else if (cmd === "revert") {
+        runRevert(argv.slice(1));
+    }
     else if (cmd === "history") {
         runHistory(argv.slice(1));
     }
@@ -715,6 +1088,9 @@ if (entry.endsWith("geml.js") || entry.endsWith("geml.ts")) {
     else if (cmd === "check") {
         runCheck(argv.slice(1));
     }
+    else if (cmd === "codemap") {
+        runCodemap(argv.slice(1));
+    }
     else if (cmd !== "-" && !/[.\/\\]/.test(cmd)) {
         // A bare word that is neither a known command nor a path is almost always
         // a mistyped command — say so, don't try to read it as a file.