@geml/geml 1.1.1 → 1.4.2

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,79 +1,155 @@
-<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.
+<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
+
+The reference parser, validator, renderer, and CLI for **GEML** (General
+Expressive Markup Language) — **one format, two readers.** People and AI agents
+co-write the same document: plain text that stays legible for people, and
+**addressable, verifiable, and versioned** for machines.
+
+Every kind of structured content — code, tables, diagrams, math, callouts,
+metadata — rides on **one** primitive, the typed block:
+
+```
+=== code {#hello lang=python}
+print("hi")
+===
+```
+
+- **Addressable** — every block has an `#id`; `geml get` / `geml set '#id'`
+  read or patch one section without re-emitting the whole file (on this repo's
+  own spec, ~**31× less context** than shipping the whole document).
+- **Verifiable** — 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 a `diagnostics` array, so agents and CI get a structured pass/fail signal.
+- **Versioned** — `geml history` and `geml revert` snapshot and rewind
+  revisions over a plain-text `.gemlhistory` sidecar.
+
+Try the format in the [playground](https://geml-spec.github.io/geml/playground/)
+— no install. Full pitch, spec, and format comparison live in the
+[repository](https://github.com/geml-spec/geml).
+
+## 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 ≥ 22.
+
+## CLI
+
+The CLI is built around one question: can a single agent author and maintain an
+entire `.geml` file from the command line — create, add, edit, delete, and copy
+blocks in from other files? Three tests keep the command set honest:
+
+- **Complete** — every step of a document's life has a verb, so an agent never
+  rewrites the whole file to change one block.
+- **Ergonomic** — few flags, sensible defaults, and pipeline-friendly I/O, so
+  multi-step edits chain without ceremony.
+- **Consistent** — behavior is uniform and predictable: name a target `#id` and
+  the content adopts it, every write is guarded, a file is edited in place while
+  `-` streams to stdout.
+
+Every command reads a file path, or `-` for stdin. Exit codes: `0` ok ·
+`1` document/operation error · `2` usage error.
+
+```sh
+geml doc.geml                       # document-model JSON (default --to json)
+geml doc.geml --to md|html|geml     # convert; geml notes.md -> GEML
+geml get    doc.geml ['#id']        # list addressable ids, or print one block (heading id = its section)
+geml set    doc.geml '#id' [--head|--body] [--in F[#src]]   # replace a block's content (id kept)
+geml add    doc.geml (--append|--before #id|--after #id) [--in F[#src]]   # insert a fragment
+geml delete doc.geml '#id' ['#id2' …]     # remove one or more blocks
+geml rename doc.geml '#old' '#new'        # rename an id + every reference to it
+geml revert doc.geml '#id' [--rev -1]     # undo a block: splice / resurrect / remove
+geml check  doc.geml [--root <dir>]       # validate only: diagnostics + exit code (--json for the array)
+geml history <commit|verify|show|restore|log> doc.geml [...]   # .gemlhistory version sidecar
+geml codemap <build|verify|render|serve|refresh|find|mcp>      # your codebase's call graph as GEML docs
+geml --help | --version             # --version --json prints {"parser","spec"}
+```
+
+The agent loop: `geml get` a block → `set`/`add`/`delete`/`rename` it →
+`geml check` → `geml history commit` — small, precise, verifiable edits.
+
+Conversion is one entry — `geml <file> [--to json|html|md|geml]`; the input
+format is inferred (`--from` overrides > extension > GEML), the target is `--to`
+(default: GEML → JSON, Markdown → GEML), and `-o` names the output path.
+
+`set` and `add` take their content from `--in F` (F's block whose id equals the
+target), `--in F#src` (F's block `#src`), or stdin (raw bytes). `set` **replaces
+a whole block** and normalizes the content's id to the target — so you can fork
+any block into this slot without hand-editing its id (`--head` swaps just the
+head line, `--body` just the body). `add` **inserts a fragment** (one or more
+blocks, or bare prose) at `--append` / `--before #id` / `--after #id`, keeping
+the content's own ids (a collision is refused). `delete` removes one or more
+ids; `rename` rewrites an id's declaration and every reference to it.
+
+Mutations (`set`/`add`/`delete`/`rename`) write the **whole updated document**:
+in place when the input is a file, or to **stdout** when the input is `-`; `-o`
+redirects the write (`-o -` forces stdout), so edits pipe cleanly. Every write
+is guarded — re-parsed and refused if it would break the document or drop an id
+(a reference left dangling by `delete` is a warning, not a refusal; `geml check`
+flags it later).
+
+Undo is `revert`, which reconciles one block to a past revision (`--rev`, default
+`-1`): it **splices** back changed content, **resurrects** a deleted block (placed
+by its old neighbours, or `--append`/`--before`/`--after`), or **removes** a block
+that did not exist then. So each forward edit has an inverse:
+
+| forward edit | undo |
+|---|---|
+| `set #id` | `revert #id` (splice) |
+| `delete #id` | `revert #id` (resurrect) |
+| `add #id` | `revert #id` (remove) — or `delete #id` |
+| `rename #old #new` | `rename #new #old` (self-inverse) |
+
+`revert` reads the `.gemlhistory` sidecar, so `set`/`delete`/`add` undo needs a
+prior `geml history commit`; `rename` is its own inverse and needs no history.
+
+A **heading's** `#id` addresses its whole **section** — the heading line through
+the line before the next heading of the same-or-higher level — so the prose
+under a heading is block-editable with no extra syntax.
+Spans overlap: blocks nested in the section keep their own ids, and a `set` on
+the section that drops one of them is refused by the guard. `get --json` on a
+heading covers the same content as the raw span: a section envelope
+`{kind:"section", id, level, blocks:[heading, …its section's blocks]}` (a
+block/footnote id still prints its single model node). `--head` narrows
+`get`/`set`/`revert` to ANY id's head line — a heading's line, or a typed
+block's opening fence line, so an agent renames a heading or edits a block's
+attributes (caption, compute, …) without touching the body. Convention: keep
+the document title in `=== meta` (`title = "…"`), not an H1 — a lone top-level
+`#` section is the whole document, the telltale that it is really a title.
+
+## 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

@@ -1,109 +1,120 @@
-// 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 };
-}
+// 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);
+  try {
+    return extractFrom(db, root);
+  } finally {
+    // Always release the handle: an open DatabaseSync keeps graph.db locked for
+    // the process lifetime, so on Windows the caller cannot delete or replace
+    // it (EPERM). try/finally closes it even if extraction throws.
+    db.close();
+  }
+}
+
+function extractFrom(db, root) {
+  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 };
+}