@geml/geml 1.4.2 → 1.4.3

package/codemap/verify.mjs

@@ -1,148 +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"]);
-// 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);
+#!/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/chart.d.ts

@@ -1,3 +1,4 @@
+import { type DiagnosticCode } from "./diagnostics.js";
 import { type Value } from "./attrs.js";
 import { type TableModel } from "./table.js";
 export type ChartType = "bar" | "line" | "area" | "pie" | "scatter";
@@ -19,6 +20,7 @@ export interface ChartModel {
 }
 export interface ChartDiag {
     severity: "error" | "warning";
+    code: DiagnosticCode;
     message: string;
 }
 export interface ChartResult {

package/dist/chart.js

@@ -20,16 +20,16 @@ function str(v) {
 }
 export function buildChart(attrs, table) {
     const diagnostics = [];
-    const err = (m) => diagnostics.push({ severity: "error", message: m });
-    const warn = (m) => diagnostics.push({ severity: "warning", message: m });
+    const err = (code, m) => diagnostics.push({ severity: "error", code, message: m });
+    const warn = (code, m) => diagnostics.push({ severity: "warning", code, message: m });
     const fail = () => ({ model: null, diagnostics });
     const typeRaw = str(attrs["type"]);
     if (!typeRaw) {
-        err("chart: missing `type`");
+        err("chart-missing-type", "chart: missing `type`");
         return fail();
     }
     if (!TYPES.has(typeRaw)) {
-        err(`chart: unknown type \`${typeRaw}\` (supported: bar, line, area, pie, scatter; use format=vega-lite for others)`);
+        err("chart-unknown-type", `chart: unknown type \`${typeRaw}\` (supported: bar, line, area, pie, scatter; use format=vega-lite for others)`);
         return fail();
     }
     const type = typeRaw;
@@ -37,29 +37,29 @@ export function buildChart(attrs, table) {
     // name is also wrong.
     const rowsAttr = (str(attrs["rows"]) ?? "data");
     if (!["data", "all", "summary"].includes(rowsAttr)) {
-        err(`chart: unknown rows scope \`${rowsAttr}\` (data|all|summary)`);
+        err("chart-unknown-rows-scope", `chart: unknown rows scope \`${rowsAttr}\` (data|all|summary)`);
         return fail();
     }
     const x = str(attrs["x"]);
     const yRaw = str(attrs["y"]);
     if (!x)
-        err("chart: missing required channel `x`");
+        err("chart-missing-channel", "chart: missing required channel `x`");
     if (!yRaw)
-        err("chart: missing required channel `y`");
+        err("chart-missing-channel", "chart: missing required channel `y`");
     if (!x || !yRaw)
         return fail();
     let y = yRaw.split(",").map((s) => s.trim()).filter((s) => s !== "");
     if (y.length === 0) {
-        err("chart: `y` lists no columns");
+        err("chart-empty-channel", "chart: `y` lists no columns");
         return fail();
     }
     // Wrong-channel warnings (channel present but unused by this type).
     if (attrs["size"] !== undefined && !USES[type].has("size"))
-        warn(`chart: \`size\` is ignored for type \`${type}\``);
+        warn("chart-unused-channel", `chart: \`size\` is ignored for type \`${type}\``);
     if (attrs["series"] !== undefined && !USES[type].has("series"))
-        warn(`chart: \`series\` is ignored for type \`${type}\``);
+        warn("chart-unused-channel", `chart: \`series\` is ignored for type \`${type}\``);
     if (type === "pie" && y.length > 1) {
-        warn("chart: pie uses a single `y`; extra columns ignored");
+        warn("chart-unused-channel", "chart: pie uses a single `y`; extra columns ignored");
         y = [y[0]];
     }
     // Optional channels, only when used by this type.
@@ -69,7 +69,7 @@ export function buildChart(attrs, table) {
     const idx = (name) => table.columns.indexOf(name);
     for (const name of [x, ...y, ...(series ? [series] : []), ...(size ? [size] : [])]) {
         if (idx(name) < 0)
-            err(`chart: column \`${name}\` not found in table`);
+            err("chart-unknown-column", `chart: column \`${name}\` not found in table`);
     }
     if (diagnostics.some((d) => d.severity === "error"))
         return fail();
@@ -77,14 +77,14 @@ export function buildChart(attrs, table) {
     let picked;
     if (rowsAttr === "summary") {
         if (!table.summary) {
-            err("chart: rows=summary but the table has no summary row");
+            err("chart-missing-summary-row", "chart: rows=summary but the table has no summary row");
             return fail();
         }
         picked = [table.summary];
     }
     else if (rowsAttr === "all") {
         if (!table.summary)
-            warn("chart: rows=all but the table has no summary row; using data rows");
+            warn("chart-summary-row-unavailable", "chart: rows=all but the table has no summary row; using data rows");
         picked = table.summary ? [...table.rows, table.summary] : table.rows;
     }
     else {
@@ -105,7 +105,7 @@ export function buildChart(attrs, table) {
     for (const row of picked) {
         const cells = numIs.map((i) => row[i]);
         if (cells.some((cell) => (cell?.text ?? "") !== "" && typeof cell?.value !== "number")) {
-            err("chart: non-numeric value in a y column");
+            err("chart-non-numeric-value", "chart: non-numeric value in a y column");
             return fail();
         }
         if (cells.some((cell) => (cell?.text ?? "") === ""))

package/dist/diagnostics.d.ts

@@ -0,0 +1,9 @@
+export type DiagnosticCode = "unterminated-block" | "unknown-block-type" | "block-nesting-too-deep" | "list-nesting-too-deep" | "inline-nesting-too-deep" | "duplicate-id" | "unresolved-reference" | "unresolved-footnote" | "unresolved-cross-document-reference" | "unresolvable-document" | "unchecked-cross-document-reference" | "unknown-metadata-reference" | "table-src-and-body" | "unknown-table-format" | "bad-compute-formula" | "unlexable-compute-formula" | "compute-error" | "bad-summary-entry" | "summary-unknown-column" | "unlexable-summary-expression" | "summary-error" | "bad-span" | "span-outside-table" | "unknown-diagram-format" | "ignored-diagram-body" | "code-graph-missing-src" | "code-graph-unresolvable-document" | "chart-missing-data" | "chart-data-not-a-table" | "chart-missing-type" | "chart-unknown-type" | "chart-unknown-rows-scope" | "chart-missing-channel" | "chart-empty-channel" | "chart-unknown-column" | "chart-unused-channel" | "chart-missing-summary-row" | "chart-summary-row-unavailable" | "chart-non-numeric-value";
+export interface Diagnostic {
+    severity: "error" | "warning";
+    code: DiagnosticCode;
+    message: string;
+    line: number;
+}
+export declare const SEVERITY: Record<DiagnosticCode, "error" | "warning">;
+export declare function normalizeSource(source: string): string;

package/dist/diagnostics.js

@@ -0,0 +1,73 @@
+// GEML reference parser — the diagnostic catalogue (spec Appendix A).
+//
+// Every diagnostic a conforming parser emits carries a STABLE `code` in
+// addition to its human-readable `message`. The message is prose: it may be
+// reworded, translated, or given more context between releases. The code is
+// the contract — it is what a conformance test, an editor integration, or a CI
+// gate matches on, and it is what the specification's Appendix A enumerates.
+//
+// `DiagnosticCode` below is the single source of truth: it is a closed union,
+// so a misspelled or unregistered code is a compile error, and the spec's
+// catalogue can be checked against this list mechanically.
+// The severity each code is emitted with. The specification fixes severity per
+// code (Appendix A), so this table is normative, not advisory: a second
+// implementation reporting `unknown-block-type` as an error does not conform.
+export const SEVERITY = {
+    "unterminated-block": "error",
+    "unknown-block-type": "warning",
+    "block-nesting-too-deep": "error",
+    "list-nesting-too-deep": "error",
+    "inline-nesting-too-deep": "error",
+    "duplicate-id": "error",
+    "unresolved-reference": "error",
+    "unresolved-footnote": "error",
+    "unresolved-cross-document-reference": "error",
+    "unresolvable-document": "error",
+    "unchecked-cross-document-reference": "warning",
+    "unknown-metadata-reference": "error",
+    "table-src-and-body": "error",
+    "unknown-table-format": "warning",
+    "bad-compute-formula": "error",
+    "unlexable-compute-formula": "error",
+    "compute-error": "error",
+    "bad-summary-entry": "error",
+    "summary-unknown-column": "error",
+    "unlexable-summary-expression": "error",
+    "summary-error": "error",
+    "bad-span": "error",
+    "span-outside-table": "warning",
+    "unknown-diagram-format": "warning",
+    "ignored-diagram-body": "warning",
+    "code-graph-missing-src": "warning",
+    "code-graph-unresolvable-document": "warning",
+    "chart-missing-data": "error",
+    "chart-data-not-a-table": "error",
+    "chart-missing-type": "error",
+    "chart-unknown-type": "error",
+    "chart-unknown-rows-scope": "error",
+    "chart-missing-channel": "error",
+    "chart-empty-channel": "error",
+    "chart-unknown-column": "error",
+    "chart-unused-channel": "warning",
+    "chart-missing-summary-row": "error",
+    "chart-summary-row-unavailable": "warning",
+    "chart-non-numeric-value": "error",
+};
+// ---------------------------------------------------------------------------
+// Source normalization (spec §0)
+// ---------------------------------------------------------------------------
+// A conforming parser normalizes its input before scanning:
+//
+//   1. a single leading BOM (U+FEFF) is removed;
+//   2. every line ending (CRLF, or a lone CR) becomes LF;
+//   3. U+0000 becomes U+FFFD.
+//
+// All three preserve the LINE COUNT, which is what lets `blockSpans` index the
+// original bytes by line: normalization only ever rewrites bytes *within* a
+// line, never splits or joins one. (1) only touches the first line's leading
+// bytes; (3) is a same-line substitution; (2) is per-line trailing bytes, and
+// splitting on the normalized LF yields exactly the lines the original had.
+export function normalizeSource(source) {
+    const noBom = source.charCodeAt(0) === 0xfeff ? source.slice(1) : source;
+    return noBom.replace(/\r\n?/g, "\n").replace(/\0/g, "�");
+}

package/dist/geml.d.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { type Diagnostic } from "./diagnostics.js";
 import { type Value } from "./attrs.js";
 import { type Inline } from "./inline.js";
 import { type TableModel } from "./table.js";
@@ -54,11 +55,7 @@ export type Block = {
     chart?: ChartModel;
     hidden?: boolean;
 };
-export interface Diagnostic {
-    severity: "error" | "warning";
-    message: string;
-    line: number;
-}
+export { type Diagnostic, type DiagnosticCode, SEVERITY } from "./diagnostics.js";
 export interface Document {
     kind: "document";
     children: Block[];