@geml/geml 1.1.1 → 1.3.2

package/dist/geml.js

@@ -8,21 +8,21 @@
 // M2: inline parsing of flow blocks (§5 — emphasis/strong/strike, code, math,
 // 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, join, resolve as resolvePath } from "node:path";
+import { readFileSync, writeFileSync, realpathSync, statSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve as resolvePath, sep } 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 { renderHtml } from "./render-html.js";
 import { coerce, parseAttrs } from "./attrs.js";
-import { parseInline } from "./inline.js";
+import { META_REF_SRC, parseInline } from "./inline.js";
 import { parseTable } from "./table.js";
 import { buildChart } from "./chart.js";
 import { mdToGeml } from "./from-md.js";
 import { serialize } from "./serialize.js";
 import { gemlToMd } from "./to-md.js";
 export { mdToGeml } from "./from-md.js";
-export { renderHtml } from "./render.js";
+export { renderHtml } from "./render-html.js";
 export { serialize } from "./serialize.js";
 export { gemlToMd } from "./to-md.js";
 // Type registry: which body mode each typed block uses. Unknown types are a
@@ -34,6 +34,7 @@ const REGISTRY = {
     table: "raw", // structured table parsing lands in M3
     output: "raw", // captured result of a code block (stored, never executed)
     note: "flow",
+    text: "flow", // addressable prose container: an id/attrs for a run of flow, no callout chrome
     meta: "data",
 };
 // §7: built-in diagram renderer registry. Unknown formats are a warning (the
@@ -45,6 +46,11 @@ const DIAGRAM_RENDERERS = new Set(["mermaid", "graphviz", "dot", "d2", "plantuml
 const FENCE_OPEN = /^(={3,})[ \t]+([A-Za-z][A-Za-z0-9_-]*)[ \t]*(\{.*\})?[ \t]*$/;
 const HEADING = /^(#{1,6})[ \t]+(.*?)[ \t]*(\{[^}]*\})?[ \t]*$/;
 const LIST_ITEM = /^[ \t]*(?:[-*]|\d+\.)[ \t]+(.*)$/;
+// Maximum block/list nesting depth the recursive-descent scanner will build
+// before emitting a diagnostic instead of recursing further. Guards parse()
+// (scanBlocks / parseList) and, in step, the renderer against a deeply nested
+// document overflowing the call stack (DoS). 256 is far past any real document.
+const MAX_NESTING = 256;
 function isCloseFence(line, openLen) {
     const t = line.replace(/\s+$/, "");
     return /^=+$/.test(t) && t.length === openLen;
@@ -62,15 +68,67 @@ function slug(text) {
 // ---------------------------------------------------------------------------
 // §4: substitute `{{key}}` in flow text with the matching `=== meta` value.
 // An unknown key is a build error (single-source-of-truth, fail loudly).
+// The scan mirrors the §5.3(1) verbatim atoms: a `{{key}}` inside a code span
+// or inline math is left untouched (so GEML prose can document this very
+// syntax), and a backslash-escaped character can neither open a span nor a
+// `{{…}}` reference — `\{{key}}` renders as the literal text `{{key}}`.
+const META_REF = new RegExp(META_REF_SRC, "y");
 function interpolate(text, line, ctx) {
     if (!text.includes("{{"))
         return text;
-    return text.replace(/\{\{\s*([A-Za-z_][A-Za-z0-9_-]*)\s*\}\}/g, (full, key) => {
-        if (ctx.meta.has(key))
-            return ctx.meta.get(key);
-        ctx.diags.push({ severity: "error", message: `unknown metadata reference \`{{${key}}}\``, line });
-        return full;
-    });
+    let out = "";
+    let i = 0;
+    while (i < text.length) {
+        const c = text[i];
+        if (c === "\\" && i + 1 < text.length) {
+            out += c + text[i + 1];
+            i += 2;
+            continue;
+        }
+        if (c === "`") {
+            let n = 0;
+            while (text[i + n] === "`")
+                n++;
+            const close = text.indexOf("`".repeat(n), i + n);
+            if (close >= 0) {
+                out += text.slice(i, close + n);
+                i = close + n;
+                continue;
+            }
+            out += text.slice(i, i + n); // unclosed run: literal, keep scanning
+            i += n;
+            continue;
+        }
+        if (c === "$") {
+            const close = text.indexOf("$", i + 1);
+            if (close > i + 1) {
+                out += text.slice(i, close + 1);
+                i = close + 1;
+                continue;
+            }
+            out += c;
+            i++;
+            continue;
+        }
+        if (c === "{" && text[i + 1] === "{") {
+            META_REF.lastIndex = i;
+            const m = META_REF.exec(text);
+            if (m) {
+                const key = m[1];
+                if (ctx.meta.has(key))
+                    out += ctx.meta.get(key);
+                else {
+                    ctx.diags.push({ severity: "error", message: `unknown metadata reference \`{{${key}}}\``, line });
+                    out += m[0];
+                }
+                i = META_REF.lastIndex;
+                continue;
+            }
+        }
+        out += c;
+        i++;
+    }
+    return out;
 }
 // Register a block id, flagging duplicates as errors (§4: ids unique per doc).
 function registerId(ctx, id, line) {
@@ -122,6 +180,7 @@ function parseList(lines, i, base, ctx) {
     const root = mkList(matchMarker(lines[i]));
     const stack = [{ list: root, indent: matchMarker(lines[i]).indent }];
     let prevBlank = false;
+    let tooDeep = false;
     while (i < lines.length) {
         if (lines[i].trim() === "") {
             prevBlank = true;
@@ -139,9 +198,21 @@ function parseList(lines, i, base, ctx) {
             const parent = top.list.items[top.list.items.length - 1];
             if (!parent)
                 break; // deeper indent with no parent item: defensive stop
-            cur = mkList(mk);
-            (parent.children ??= []).push(cur);
-            stack.push({ list: cur, indent: mk.indent });
+            if (stack.length >= MAX_NESTING) {
+                // Refuse to nest deeper than the cap: keep the item at the current level
+                // rather than building a model that overflows the renderer (DoS). One
+                // diagnostic per over-deep list; content is preserved, just flattened.
+                if (!tooDeep) {
+                    ctx.diags.push({ severity: "error", message: `list nesting too deep (max ${MAX_NESTING})`, line: base + i + 1 });
+                    tooDeep = true;
+                }
+                cur = top.list;
+            }
+            else {
+                cur = mkList(mk);
+                (parent.children ??= []).push(cur);
+                stack.push({ list: cur, indent: mk.indent });
+            }
         }
         else {
             // §5: a change of marker type (bullet ↔ ordered) at the same level ends
@@ -159,7 +230,7 @@ function parseList(lines, i, base, ctx) {
     }
     return { block: root, next: i };
 }
-function scanBlocks(lines, base, ctx) {
+function scanBlocks(lines, base, ctx, depth = 0) {
     const blocks = [];
     const diags = ctx.diags;
     let i = 0;
@@ -242,7 +313,16 @@ function scanBlocks(lines, base, ctx) {
                     ctx.refs.push({ kind: "internal", anchor: of.slice(1), line: openLineNo });
             }
             if (mode === "flow") {
-                block.children = scanBlocks(body, base + i + 1, ctx);
+                if (depth >= MAX_NESTING) {
+                    // Refuse to recurse past the cap: emit a diagnostic and keep the body
+                    // as raw so the parser returns cleanly instead of overflowing the
+                    // call stack on a pathologically nested document (DoS).
+                    diags.push({ severity: "error", message: `block nesting too deep (max ${MAX_NESTING}); body kept as raw`, line: openLineNo });
+                    block.raw = body;
+                }
+                else {
+                    block.children = scanBlocks(body, base + i + 1, ctx, depth + 1);
+                }
             }
             else if (mode === "data") {
                 block.data = parseData(body);
@@ -453,8 +533,46 @@ export function parse(source, opts = {}) {
 }
 // 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);
+// The slug MUST come from the INTERPOLATED text — scanBlocks slugs after
+// interpolate(), so `# {{title}} Setup` registers the substituted slug; slugging
+// the raw text here would create a phantom id the parser never registered and
+// make the real one unaddressable. `ctx` is an inert context carrying the
+// document's meta (diagnostics are discarded — spans never report).
+function idOfHeading(braces, text, line, ctx) {
+    return (braces ? parseAttrs(braces).id : undefined) ?? slug(interpolate(text, line, ctx));
+}
+// The matching close of the fence opened at lines[i] (equal-length run, or the
+// labeled `=== #id` close when the block carries an id): the index just past
+// the close line, and whether one was found — an unterminated block runs to
+// the end of the scope.
+function fenceClose(lines, i, open) {
+    const openLen = open[1].length;
+    const id = open[3] ? parseAttrs(open[3]).id : undefined;
+    const labeled = id !== undefined ? new RegExp(`^={3,}[ \\t]+#${id}[ \\t]*$`) : null;
+    for (let j = i + 1; j < lines.length; j++) {
+        if (isCloseFence(lines[j], openLen) || (labeled && labeled.test(lines[j])))
+            return { end: j + 1, closed: true };
+    }
+    return { end: lines.length, closed: false };
+}
+// A heading's span covers its whole SECTION: the heading line through the line
+// just before the next heading of same-or-higher level (fewer-or-equal `#`) in
+// the current scope, or end-of-scope. Fenced blocks are skipped whole — a `#`
+// line inside a `=== code` body is content, never a boundary.
+function sectionEnd(lines, i, level) {
+    let j = i + 1;
+    while (j < lines.length) {
+        const open = FENCE_OPEN.exec(lines[j]);
+        if (open) {
+            j = fenceClose(lines, j, open).end;
+            continue;
+        }
+        const h = HEADING.exec(lines[j]);
+        if (h && h[1].length <= level)
+            return j;
+        j++;
+    }
+    return lines.length;
 }
 // Walk `lines` exactly as scanBlocks does — same fence close rules (equal-length
 // or labeled `=== #id`), same flow-only recursion via REGISTRY — recording the
@@ -462,7 +580,7 @@ function idOfHeading(braces, text) {
 // 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) {
+function collectSpans(lines, base, out, ctx, depth = 0) {
     const add = (id, start, end) => {
         if (!out.has(id))
             out.set(id, { start, end });
@@ -486,33 +604,27 @@ function collectSpans(lines, base, out) {
         } // 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;
+            const { end, closed } = fenceClose(lines, i, open);
             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);
+            if ((REGISTRY[type] ?? "raw") === "flow" && depth < MAX_NESTING) {
+                collectSpans(lines.slice(i + 1, closed ? end - 1 : end), base + i + 1, out, ctx, depth + 1);
             }
             i = end;
             continue;
         }
         const h = HEADING.exec(line);
         if (h) {
-            add(idOfHeading(h[3], h[2]), base + i, base + i + 1);
+            // Section span (heading through its prose and nested blocks). The walk
+            // still advances one line at a time so every nested id inside the
+            // section registers its own span — spans intentionally OVERLAP: #sec
+            // contains #code, and each remains addressable on its own.
+            add(idOfHeading(h[3], h[2], base + i + 1, ctx), base + i, base + sectionEnd(lines, i, h[1].length));
             i++;
             continue;
         }
@@ -523,29 +635,49 @@ function collectSpans(lines, base, out) {
 // 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);
+    const lines = source.replace(/\r\n?/g, "\n").split("\n");
+    // Inert context: heading auto-ids slug the interpolated text (parser parity);
+    // its diagnostics are discarded — the span scan never reports.
+    const ctx = { diags: [], ids: new Map(), refs: [], meta: collectMeta(lines) };
+    collectSpans(lines, 0, out, ctx);
     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.
+// A line ends at `\n` or at a LONE `\r` (old-Mac style) — the same boundaries
+// the span scan's `\r\n?` -> `\n` normalization sees, so span indices always
+// address the same lines the parser counted.
 function splitLines(source) {
-    return source.split(/(?<=\n)/);
+    return source.split(/(?<=\n|\r(?!\n))/);
+}
+// `--head`: narrow any id's span to its HEAD line — the single declaring line
+// (a heading's `# … {#id}` line, a typed block's opening fence, a footnote's
+// `[^id]:` line). The head is by construction the FIRST line of the span, so
+// the narrowing is parse-free and needs no type check. Main use: `set --head`
+// edits a block's attributes (caption/compute/lang/…) without re-sending its
+// body, or renames a heading without rewriting its section.
+function narrowToHead(span) {
+    return { start: span.start, end: span.start + 1 };
 }
 // 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) {
+// Returns the containing sibling array and index, not just the node: the model
+// is FLAT — a heading does not own its section; the section's prose and blocks
+// are its FOLLOWING SIBLINGS — so a section consumer needs the array.
+function findBlockSite(blocks, id) {
+    for (let i = 0; i < blocks.length; i++) {
+        const b = blocks[i];
         if ((b.kind === "heading" || b.kind === "block") && b.id === id)
-            return b;
+            return { siblings: blocks, index: i };
         if (b.kind === "block" && b.children) {
-            const hit = findBlockById(b.children, id);
+            const hit = findBlockSite(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);
+                    const hit = findBlockSite(it.children, id);
                     if (hit)
                         return hit;
                 }
@@ -554,6 +686,21 @@ function findBlockById(blocks, id) {
     }
     return undefined;
 }
+// Model-side section boundary: within one sibling array, the section opened by
+// the heading at index k runs to the next sibling heading of same-or-higher
+// level, or the array end. This is the SAME rule sectionEnd() applies to raw
+// source lines (where skipping fenced bodies makes "next heading" well-defined)
+// — the two sides must stay in lockstep; the get-set suite pins their parity
+// (ids covered by the raw slice == ids covered by the --json envelope).
+function sectionEndIndex(siblings, k) {
+    const level = siblings[k].level;
+    for (let m = k + 1; m < siblings.length; m++) {
+        const b = siblings[m];
+        if (b.kind === "heading" && b.level <= level)
+            return m;
+    }
+    return siblings.length;
+}
 // ---------------------------------------------------------------------------
 // CLI
 // ---------------------------------------------------------------------------
@@ -572,45 +719,52 @@ function parseStamp(s) {
     return new Date(Date.UTC(+y, +mo - 1, +d, +h, +mi, +se));
 }
 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|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.
-Exit codes: 0 ok · 1 document/operation error · 2 usage error.`;
+const PARSER_VERSION = "1.3.2"; // 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][--head]  print ONE block by id (a heading id = its section;
+                                             --head narrows any id to its head line; --json = model node)
+  geml set <file.geml|-> #id [--from f][-o f][--head] replace ONE block by id (new content: --from/stdin)
+  geml revert <file.geml> #id [--to <sel>][--head] restore ONE block to a past revision (sel: -N|latest|id)
+  geml check <file.geml|-> [--root d][--json] validate only: diagnostics + exit code
+                                             (--root widens cross-doc refs to dir d, e.g. the repo root)
+  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|log> <file.geml> [...]
+  geml codemap <build|verify|render|serve|refresh|find|mcp> [...]   code-graph toolkit (alias: codegraph)
+  geml --help | --version [--json]
+
+Use '-' as the file to read from stdin.
+Exit codes: 
+  0 ok
+  1 document/operation error
+  2 command 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]",
+    get: "usage: geml get <file.geml|-> #id [--json] [--head]  (a heading id = its whole section; --head narrows any id to its head line)",
+    set: "usage: geml set <file.geml|-> #id [--from FILE] [-o out.geml] [--head]",
+    check: "usage: geml check <file.geml|-> [--root <dir>] [--json]  (--root: resolve cross-doc refs within <dir> instead of the file's own directory)",
     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]",
-    revert: "usage: geml revert <file.geml> #id [--to <sel>] [--changed] [--dry-run] [-o out]  (sel: -N | latest | id-prefix; default -1)",
+    revert: "usage: geml revert <file.geml> #id [--to <sel>] [--changed] [--dry-run] [-o out] [--head]  (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)`,
+    codemap: `usage: geml codemap build  [--root <repo>]   # auto-detect languages, run the indexer(s), and merge into one codemap (--root defaults to the current directory)
+       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 find <name> [dir]            locate a symbol by substring name -> doc#id + src (stdout, no browser)
+       geml codemap mcp                          stdio MCP server (GEML_GRAPH_DIR or graph_dir arg)
+       (<dir> for verify/render/serve/refresh/find defaults to ./.geml-code-graph; codegraph and code-graph are accepted as aliases of codemap)`,
 };
 // 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.
@@ -634,12 +788,66 @@ function readInput(file) {
         fail(file === "-" ? "cannot read stdin" : `cannot read ${file}`);
     }
 }
-// A cross-document resolver rooted at the input's directory (cwd for stdin).
-function resolverFor(file) {
-    const baseDir = file === "-" ? "." : dirname(file);
+// A cross-document resolver rooted at the input's directory (cwd for stdin),
+// CONFINED to that directory's subtree. A reference that resolves outside the
+// base — via a `..` escape, an absolute path, or (on Windows) a different drive
+// — is refused (returns null, i.e. an unresolvable ref) so a crafted document
+// cannot turn `geml check`/parse into an arbitrary local-file read oracle. §8.
+//
+// A purely LEXICAL check is not enough: a symlink that sits lexically inside the
+// subtree but points to `../../outside.geml` passes `path.relative` yet reads an
+// external target. So after the cheap lexical gate we resolve BOTH the base and
+// the target through `realpathSync` (following every symlink component) and
+// re-check that the REAL target still lies within the REAL base subtree before
+// reading. A target that does not exist makes `realpathSync` throw — handled as
+// an ordinary unresolvable ref (null), never a crash.
+//
+// `root` (CLI `--root`, an explicit per-invocation user grant — never
+// document-controlled) widens the confinement base from the input's own
+// directory to an ancestor the user names, so repo-relative `../` references
+// between sibling directories can be checked. It moves WHERE the boundary
+// stands, never whether it is enforced: both gates below run against the
+// widened base, so escapes past the root are refused exactly as above. The
+// viewer/web surfaces never pass a root — their boundary is unchanged.
+function resolverFor(file, root) {
+    const dirAbs = resolvePath(file === "-" ? "." : dirname(file));
+    const baseAbs = root === undefined ? dirAbs : resolvePath(root);
+    // Canonicalise the base once. If the base itself cannot be realpath'd, no
+    // cross-doc ref can be safely confined — resolve nothing.
+    let realBase = null;
+    try {
+        realBase = realpathSync(baseAbs);
+    }
+    catch {
+        realBase = null;
+    }
+    const outside = (from, to) => {
+        const rel = relative(from, to);
+        return rel === ".." || rel.startsWith(".." + sep) || isAbsolute(rel);
+    };
     return (d) => {
+        if (realBase === null)
+            return null;
+        // References resolve FROM the document's own directory; the gates below
+        // confine them to the (possibly widened) base.
+        const targetAbs = resolvePath(dirAbs, d);
+        // Cheap lexical gate: reject an obvious `..`/absolute/other-drive escape
+        // before touching the filesystem.
+        if (outside(baseAbs, targetAbs))
+            return null;
+        // Real (symlink-resolved) gate: a symlink pointing out of the subtree
+        // resolves to a real path outside `realBase` and is refused here.
+        let realTarget;
         try {
-            return readFileSync(resolvePath(baseDir, d), "utf8");
+            realTarget = realpathSync(targetAbs);
+        }
+        catch {
+            return null;
+        }
+        if (outside(realBase, realTarget))
+            return null;
+        try {
+            return readFileSync(realTarget, "utf8");
         }
         catch {
             return null;
@@ -650,10 +858,22 @@ function resolverFor(file) {
 // dump (cheap for agents). `--json` prints the diagnostics array for machines.
 function runCheck(args) {
     const json = args.includes("--json");
-    const file = args.find((a) => a === "-" || !a.startsWith("-"));
+    const root = flag(args, "--root");
+    const file = args.find((a) => a === "-" || (!a.startsWith("-") && a !== root));
     if (!file)
         fail(SUBHELP.check);
-    const doc = parse(readInput(file), { resolveDoc: resolverFor(file) });
+    // A mistyped --root must be a usage error (exit 2), not a wall of misleading
+    // "cannot resolve document" errors from a resolver confined to nothing.
+    if (root !== undefined) {
+        let isDir = false;
+        try {
+            isDir = statSync(root).isDirectory();
+        }
+        catch { /* missing -> not a dir */ }
+        if (!isDir)
+            fail(`--root ${root} is not a directory`);
+    }
+    const doc = parse(readInput(file), { resolveDoc: resolverFor(file, root) });
     if (json) {
         console.log(JSON.stringify(doc.diagnostics, null, 2));
     }
@@ -851,30 +1071,51 @@ function positionals(args, valued) {
 }
 // `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.
+// block's exact source bytes: a typed block's full `=== … ===` span, a
+// footnote's line, or — for a heading — its whole SECTION (heading line through
+// the line before the next same-or-higher heading). `--json` covers the same
+// content: a block/footnote id prints its document-model node; a heading id
+// prints a section envelope `{kind:"section", id, level, blocks:[heading,
+// …siblings up to the boundary]}`.
 function runGet(args) {
     const json = args.includes("--json");
+    const headOnly = args.includes("--head");
     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.
+        // The model node(s) — same shapes `geml <file>` emits. Parsing is needed
+        // to resolve the tree (and nested-block ids), but only the target prints.
         const doc = parse(source, { resolveDoc: resolverFor(file) });
-        const block = findBlockById(doc.children, id);
-        if (!block)
+        const site = findBlockSite(doc.children, id);
+        if (!site)
             fail(`no block with id \`${id}\``, 1);
+        const block = site.siblings[site.index];
+        // `--head` on a heading suppresses the section envelope (the lone heading
+        // node IS the head). On a block/footnote id there is nothing finer than
+        // the single node — the model has no sub-node for "just the fence line" —
+        // so --head refines only the RAW output there.
+        if (block.kind === "heading" && !headOnly) {
+            // A heading id addresses its SECTION, so `--json` covers the same
+            // content as the raw span: a self-describing envelope whose blocks[0]
+            // is the heading node followed by its siblings up to the boundary.
+            // `kind: "section"` lets a consumer branch — a block/footnote id still
+            // yields the single model node (the model itself stays flat).
+            const end = sectionEndIndex(site.siblings, site.index);
+            console.log(JSON.stringify({ kind: "section", id: block.id, level: block.level, blocks: site.siblings.slice(site.index, end) }, null, 2));
+            return;
+        }
         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)
+    const found = blockSpans(source).get(id);
+    if (!found)
         fail(`no block with id \`${id}\``, 1);
+    const span = headOnly ? narrowToHead(found) : found;
     process.stdout.write(splitLines(source).slice(span.start, span.end).join(""));
 }
 // `geml set <file.geml|-> #id [--from FILE] [-o out]` — replace ONLY that
@@ -885,6 +1126,7 @@ function runGet(args) {
 function runSet(args) {
     const out = flag(args, "-o") ?? flag(args, "--out");
     const from = flag(args, "--from");
+    const headOnly = args.includes("--head");
     const [file, rawId] = positionals(args, ["-o", "--out", "--from"]);
     if (!file || !rawId)
         fail(SUBHELP.set);
@@ -905,7 +1147,7 @@ function runSet(args) {
         if (replacement === "")
             fail("no replacement content (use --from FILE or pipe it on stdin)", 1);
     }
-    const updated = spliceBlock(source, id, replacement, file);
+    const updated = spliceBlock(source, id, replacement, file, headOnly);
     if (out) {
         writeFileSync(out, updated);
         console.error(`wrote ${out}`);
@@ -919,15 +1161,21 @@ function runSet(args) {
 // 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)
+function spliceBlock(source, id, replacement, file, headOnly = false) {
+    const found = blockSpans(source).get(id);
+    if (!found)
         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);
+    // `--head`: splice only the id's head line; everything below stays
+    // byte-identical. The guard below still applies — the replacement must
+    // re-declare `{#id}` and, for a typed block, keep the fence pairing intact
+    // (an opening line that no longer matches the untouched close fence breaks
+    // the re-parse), or the splice is refused.
+    const span = headOnly ? narrowToHead(found) : found;
     const before = orig.slice(0, span.start);
     const after = orig.slice(span.end);
     let inject = replacement.replace(/\r\n?/g, "\n");
@@ -964,6 +1212,7 @@ function spliceBlock(source, id, replacement, file) {
 function runRevert(args) {
     const changed = args.includes("--changed");
     const dryRun = args.includes("--dry-run");
+    const headOnly = args.includes("--head");
     const out = flag(args, "-o") ?? flag(args, "--out");
     const to = flag(args, "--to") ?? "-1";
     const [file, rawId] = positionals(args, ["--to", "--history", "-o", "--out"]);
@@ -974,15 +1223,19 @@ function runRevert(args) {
     const id = rawId.replace(/^#/, "");
     const historyPath = flag(args, "--history") ?? historyPathFor(file);
     const source = readInput(file);
-    const curSpan = blockSpans(source).get(id);
-    if (!curSpan)
+    const found = blockSpans(source).get(id);
+    if (!found)
         fail(`no block with id \`${id}\` in ${file}`, 1);
+    const curSpan = headOnly ? narrowToHead(found) : found;
     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).
+    // block did not exist there). Under `--head`, extract only the head line.
     const pick = (text) => {
         const s = blockSpans(text).get(id);
-        return s ? splitLines(text).slice(s.start, s.end).join("") : undefined;
+        if (!s)
+            return undefined;
+        const span = headOnly ? narrowToHead(s) : s;
+        return splitLines(text).slice(span.start, span.end).join("");
     };
     // Resolve the source revision, formatting any history-layer error cleanly.
     const target = (() => {
@@ -1011,7 +1264,7 @@ function runRevert(args) {
         process.stdout.write(oldBlock.endsWith("\n") ? oldBlock : oldBlock + "\n");
         return;
     }
-    const updated = spliceBlock(source, id, oldBlock, file);
+    const updated = spliceBlock(source, id, oldBlock, file, headOnly);
     const dest = out ?? file;
     writeFileSync(dest, updated);
     console.error(`reverted #${id} to ${target.id}${dest === file ? "" : ` -> ${dest}`}`);
@@ -1027,6 +1280,7 @@ function runCodemap(args) {
         render: "render-all.mjs",
         serve: "serve.mjs",
         refresh: "refresh.mjs",
+        find: "find.mjs",
         mcp: "mcp-server.mjs",
     };
     const sub = args[0] ?? "";
@@ -1037,10 +1291,28 @@ function runCodemap(args) {
     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")) {
+// npm's unix bin shim is a symlink named plain `geml`, so detect "run as a
+// CLI" by resolving argv[1] to its real path, not by its spelling.
+const entry = (() => {
+    const argv1 = process.argv[1];
+    if (!argv1)
+        return "";
+    try {
+        return realpathSync(argv1);
+    }
+    catch {
+        return argv1;
+    }
+})();
+// `entry` must be non-empty: in a browser bundle both sides degenerate to ""
+// (esbuild defines process.argv=[] and import.meta.url="", and the node-stub's
+// fileURLToPath is String()), which would run the CLI at import time and crash
+// the page. A real CLI invocation always has argv[1].
+if (entry && (entry === fileURLToPath(import.meta.url) || entry.endsWith("geml.ts"))) {
     const argv = process.argv.slice(2);
-    const cmd = argv[0];
+    // The on-disk artifact is `.geml-code-graph/`, so people reconstruct the
+    // command from the directory name — accept those spellings as `codemap`.
+    const cmd = argv[0] === "codegraph" || argv[0] === "code-graph" ? "codemap" : argv[0];
     jsonMode = argv.includes("--json");
     const rest = argv.slice(1);
     if (cmd === "--help" || cmd === "-h") {