@geml/geml 1.0.0 → 1.3.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,72 +1,109 @@
-# @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
+
+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
+
+Every command reads a file path, or `-` for stdin. Exit codes: `0` ok ·
+`1` document/operation error · `2` usage error.
+
+```sh
+geml get    file.geml '#id'      # print ONE block by id — a heading id yields its whole section
+geml set    file.geml '#id' --from new.geml  # replace just that block; re-parsed, refused if it breaks the doc
+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 history <commit|verify|show|restore|log> file.geml [...]   # .gemlhistory version sidecar
+geml revert file.geml '#id' [--to -1]  # roll ONE block back to an earlier revision (-N | latest | id)
+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 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 → edit it → `geml set` (guarded splice) →
+`geml check` → `geml history commit` — small, precise, verifiable edits.
+
+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

@@ -0,0 +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);
+  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 };
+}

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 };
+}