@geml/geml 1.3.2 → 1.4.2

package/codemap/verify.mjs

@@ -1,143 +1,148 @@
-#!/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";
-// win32 cmd.exe quoting (same rationale as build.mjs). q: space-aware quote for
-// the PROGRAM token — a bare launcher name (geml resolved via PATH) whose
-// .cmd/.bat shim uses %~dp0 breaks if the name is blanket-quoted. shq: ALWAYS
-// double-quote ARGUMENTS — Node does not escape args under shell:true, so a
-// `.geml` filename containing & | ( ) would otherwise break out and inject.
-// cmd.exe treats those metacharacters and whitespace as literal inside quotes;
-// CRT rules for embedded " / trailing \.
-const q = (s) => (/[\s"]/.test(String(s)) ? `"${String(s).replace(/"/g, '\\"')}"` : String(s));
-const shq = (s) => `"${String(s).replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/, '$1$1')}"`;
-const runCheck = (file) => {
-  // The built-parser path: run node on geml.js directly (array args, no shell).
-  if (cli.endsWith(".js")) return spawnSync(process.execPath, [cli, "check", file], { encoding: "utf8" });
-  // A non-.js cli may be a .cmd/.bat launcher (e.g. geml.cmd on PATH), which
-  // Node can only spawn through the shell. Hand cmd.exe ONE pre-escaped command
-  // string (never an args array — that is the unescaped, injection-prone path).
-  if (process.platform === "win32") {
-    return spawnSync([q(cli), ...["check", file].map(shq)].join(" "), { encoding: "utf8", shell: true });
-  }
-  return spawnSync(cli, ["check", file], { encoding: "utf8" });
-};
-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);
+#!/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";
+// win32 cmd.exe quoting (same rationale as build.mjs). q: space-aware quote for
+// the PROGRAM token — a bare launcher name (geml resolved via PATH) whose
+// .cmd/.bat shim uses %~dp0 breaks if the name is blanket-quoted. shq: ALWAYS
+// double-quote ARGUMENTS — Node does not escape args under shell:true, so a
+// `.geml` filename containing & | ( ) would otherwise break out and inject.
+// cmd.exe treats those metacharacters and whitespace as literal inside quotes;
+// CRT rules for embedded " / trailing \.
+const q = (s) => (/[\s"]/.test(String(s)) ? `"${String(s).replace(/"/g, '\\"')}"` : String(s));
+const shq = (s) => `"${String(s).replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/, '$1$1')}"`;
+const runCheck = (file) => {
+  // The built-parser path: run node on geml.js directly (array args, no shell).
+  if (cli.endsWith(".js")) return spawnSync(process.execPath, [cli, "check", file], { encoding: "utf8" });
+  // A non-.js cli may be a .cmd/.bat launcher (e.g. geml.cmd on PATH), which
+  // Node can only spawn through the shell. Hand cmd.exe ONE pre-escaped command
+  // string (never an args array — that is the unescaped, injection-prone path).
+  if (process.platform === "win32") {
+    return spawnSync([q(cli), ...["check", file].map(shq)].join(" "), { encoding: "utf8", shell: true });
+  }
+  return spawnSync(cli, ["check", file], { encoding: "utf8" });
+};
+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"]);
+// Cross-stack link tables: `from`/`to` may be a #ref (resolved cross-tree
+// link — checked) OR plain `file:line` text (a call/route outside any indexed
+// function — tolerated, nothing to resolve).
+const LINK_TABLES = new Set(["api-calls", "api-served-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, lenient = false) => {
+  ref = String(ref).trim();
+  if (!ref) return lenient ? undefined : err(fromDoc, where, "empty reference cell");
+  const h = ref.indexOf("#");
+  if (h < 0) return lenient ? undefined : 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) || LINK_TABLES.has(b.id)) && b.table) {
+      const lenient = LINK_TABLES.has(b.id);
+      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 ?? "", lenient);
+        checkRef(docPath, `#${b.id} row ${i + 1} to`, row[toCol]?.text ?? "", lenient);
+      });
+    }
+    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/block-edit.d.ts

@@ -0,0 +1 @@
+export declare function normalizeBlockId(blockSrc: string, newId: string): string;

package/dist/block-edit.js

@@ -0,0 +1,112 @@
+// Structural id-rewriting for `geml set`. `set #id` names the block to edit,
+// so the content spliced in must ADOPT that id — whatever id it declared (or
+// none). This module performs that rewrite parse-aware (per head form) rather
+// than by blind byte replacement, touching ONLY the id: type, classes,
+// attributes, body and the fence pairing all ride along unchanged.
+//
+// Deliberately self-contained — it imports only the shared attribute parser,
+// never geml.ts: geml.ts's module body runs the CLI on import, so a back-import
+// would fire the whole command line just by loading this helper.
+import { parseAttrs } from "./attrs.js";
+// The two head forms, spelled to MIRROR geml.ts's FENCE_OPEN / HEADING (same
+// language) but with the id-bearing brace tail split out so the id can be
+// rewritten while every other byte is copied verbatim:
+//   FENCE_HEAD  g1 = `=== type`   g2 = ws   g3 = `{…}`?   g4 = trailing ws
+//   HEAD_HEAD   g1 = `## text`    g2 = ws   g3 = `{…}`?   g4 = trailing ws
+const FENCE_HEAD = /^(={3,}[ \t]+[A-Za-z][A-Za-z0-9_-]*)([ \t]*)(\{.*\})?([ \t]*)$/;
+const HEAD_HEAD = /^(#{1,6}[ \t]+.*?)([ \t]*)(\{[^}]*\})?([ \t]*)$/;
+// Split into physical lines while keeping each line's terminator, so join("")
+// is byte-exact — the same boundaries geml.ts's splitLines() uses. A line ends
+// at `\n`, `\r\n`, or a lone `\r`.
+function splitLines(source) {
+    return source.split(/(?<=\n|\r(?!\n))/);
+}
+// Strip a single trailing terminator from one physical line.
+function stripEnding(line) {
+    return line.replace(/(\r\n|\r|\n)$/, "");
+}
+// Rewrite the id inside a `{…}` attribute block to `#newId`, keeping the braces
+// and every other class/attr byte. If no id is present, insert `#newId` as the
+// first token. The id token sits at a token boundary (`{` or whitespace) and
+// never inside a quoted value, so the anchored match can't disturb a value like
+// `caption="#x"`.
+function rewriteBraces(braces, newId) {
+    if (parseAttrs(braces).id !== undefined) {
+        return braces.replace(/([{\s])#[^\s}]+/, `$1#${newId}`);
+    }
+    const inner = braces.slice(1, -1).replace(/^[ \t]*/, "");
+    return `{#${newId}${inner.length ? " " + inner : ""}}`;
+}
+// Rewrite a HEAD line's id declaration to `#newId`. Handles both head forms and
+// all id states: existing brace id, brace attrs without an id, and no braces at
+// all (append `{#newId}`). A line that is neither form is returned unchanged.
+function rewriteHead(head, newId) {
+    const rebuild = (m) => {
+        const lead = m[1], ws = m[2] ?? "", braces = m[3], trail = m[4] ?? "";
+        if (braces)
+            return lead + ws + rewriteBraces(braces, newId) + trail;
+        return `${lead} {#${newId}}${ws}${trail}`;
+    };
+    const f = FENCE_HEAD.exec(head);
+    if (f)
+        return rebuild(f);
+    const h = HEAD_HEAD.exec(head);
+    if (h)
+        return rebuild(h);
+    return head;
+}
+// Locate the block's HEAD: the first non-blank, non-`%%` line that opens a fence
+// or a heading. Returns its line index, or -1 when the content has no head
+// (pure prose, or a structural line that is not a head) — the caller decides
+// what that means.
+function findHead(lines) {
+    for (let i = 0; i < lines.length; i++) {
+        const t = stripEnding(lines[i]);
+        if (t.trim() === "" || /^[ \t]*%%/.test(t))
+            continue;
+        if (FENCE_HEAD.test(t) || HEAD_HEAD.test(t))
+            return i;
+        return -1; // the first structural line isn't a head: no addressable block
+    }
+    return -1;
+}
+// Rewrite the HEAD id of the first block in `blockSrc` to `newId`, across every
+// head form:
+//   • fence attrs `{#x …}`  -> `{#newId …}` (other classes/attrs kept)
+//   • fence with attrs but no id, or no braces -> gains `{#newId}`
+//   • labeled close `=== #x` -> `=== #newId` (renamed to match the open)
+//   • heading `## T {#x}`    -> `## T {#newId}`
+//   • heading auto-slug (no braces) -> `## T {#newId}` appended
+// Only the id changes; type / classes / attrs / body / fence length are byte-
+// preserved, as are line terminators. Content with no head is returned as-is.
+export function normalizeBlockId(blockSrc, newId) {
+    const lines = splitLines(blockSrc);
+    const hi = findHead(lines);
+    if (hi < 0)
+        return blockSrc;
+    const headText = stripEnding(lines[hi]);
+    const headTerm = lines[hi].slice(headText.length);
+    lines[hi] = rewriteHead(headText, newId) + headTerm;
+    // For a fence carrying an id, a labeled close `=== #oldId` names that id and
+    // must be renamed too — otherwise the open declares #newId while the close
+    // still labels #oldId and the block no longer parses. The FIRST close wins
+    // (plain equal-length OR labeled), matching geml.ts's fenceClose scan; a
+    // plain close needs no rewrite.
+    const f = FENCE_HEAD.exec(headText);
+    const oldId = f && f[3] ? parseAttrs(f[3]).id : undefined;
+    if (f && oldId !== undefined) {
+        const openLen = /^=+/.exec(f[1])[0].length;
+        for (let j = hi + 1; j < lines.length; j++) {
+            const ct = stripEnding(lines[j]);
+            const trimmed = ct.replace(/[ \t]+$/, "");
+            if (/^=+$/.test(trimmed) && trimmed.length === openLen)
+                break; // plain close: done
+            const cm = /^(={3,}[ \t]+#)([^\s}]+)([ \t]*)$/.exec(ct);
+            if (cm && cm[2] === oldId) {
+                lines[j] = cm[1] + newId + cm[3] + lines[j].slice(ct.length);
+                break;
+            }
+        }
+    }
+    return lines.join("");
+}