@geml/geml 1.3.2 → 1.4.3

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("");
+}

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[];