@notrealstudio/nr-md 0.1.0

package/dist/typed-header.js

@@ -0,0 +1,229 @@
+// Typed tbl header (serialize-spec §2.3 / format-spec §5.4).
+//
+// A tbl header cell may carry an optional type annotation: `name[:type][!]`.
+// Without an annotation the column keeps the legacy per-cell coercion (§3).
+// A typed column is homogeneous: every cell coerces to the declared type and an
+// impossible coercion is a LOUD error (TableParseError), never a silent string.
+//
+// Portable: string primitives only, no regex.
+import { coerce, unescapeQuoted } from './coerce.js';
+/** Loud, non-silent table-parse error (serialize-spec §6). */
+export class TableParseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TableParseError';
+    }
+}
+// ---------- Small helpers (no regex) ----------
+function trimWs(s) {
+    let a = 0;
+    let b = s.length;
+    while (a < b && (s[a] === ' ' || s[a] === '\t'))
+        a++;
+    while (b > a && (s[b - 1] === ' ' || s[b - 1] === '\t'))
+        b--;
+    return s.slice(a, b);
+}
+function isQuoted(s) {
+    return s.length >= 2 && s[0] === '"' && s[s.length - 1] === '"';
+}
+// ---------- Header cell parsing (§2.3) ----------
+/**
+ * Split a header cell into its name (with `\:` / `\\` resolved) and the raw
+ * type-spec after the first UNescaped `:` (or null when there is no annotation).
+ */
+function splitNameAndType(t) {
+    let name = '';
+    let i = 0;
+    while (i < t.length) {
+        const c = t[i];
+        if (c === '\\' && i + 1 < t.length) {
+            const n = t[i + 1];
+            if (n === ':') {
+                name += ':';
+                i += 2;
+                continue;
+            }
+            if (n === '\\') {
+                name += '\\';
+                i += 2;
+                continue;
+            }
+            // Unknown escape — preserve the backslash verbatim.
+            name += c;
+            i++;
+            continue;
+        }
+        if (c === ':')
+            return { name, typeSpec: t.slice(i + 1) };
+        name += c;
+        i++;
+    }
+    return { name, typeSpec: null };
+}
+function parseTypeSpec(s) {
+    if (s === 'string')
+        return { kind: 'string' };
+    if (s === 'number')
+        return { kind: 'number' };
+    if (s === 'boolean')
+        return { kind: 'boolean' };
+    if (s.length >= 6 && s.slice(0, 5) === 'list(' && s[s.length - 1] === ')') {
+        const sep = s.slice(5, -1);
+        if (sep.length !== 1) {
+            throw new TableParseError(`list separator must be one character, got "${sep}"`);
+        }
+        return { kind: 'list', sep };
+    }
+    throw new TableParseError(`unknown column type: "${s}"`);
+}
+/**
+ * Parse a single header cell (`name[:type][!]`, §2.3).
+ *
+ * - A fully double-quoted cell is a literal name — no annotation.
+ * - `\:` escapes a literal colon in the name; `\\` a literal backslash.
+ * - `!` (after the optional type) marks the column required.
+ * - Un-annotated cells keep legacy behaviour (per-cell coercion §3).
+ */
+export function parseHeaderCell(cell) {
+    const t = trimWs(cell);
+    if (isQuoted(t)) {
+        return { name: unescapeQuoted(t.slice(1, -1)), required: false };
+    }
+    const { name, typeSpec } = splitNameAndType(t);
+    if (typeSpec !== null) {
+        let spec = trimWs(typeSpec);
+        let required = false;
+        if (spec.length > 0 && spec[spec.length - 1] === '!') {
+            required = true;
+            spec = trimWs(spec.slice(0, -1));
+        }
+        return { name: trimWs(name), type: parseTypeSpec(spec), required };
+    }
+    // No type annotation — still allow a trailing `!` for a required legacy column.
+    let bare = name;
+    let required = false;
+    if (bare.length > 0 && bare[bare.length - 1] === '!') {
+        required = true;
+        bare = bare.slice(0, -1);
+    }
+    return { name: trimWs(bare), required };
+}
+/** Parse a full header line into typed columns (used by {@link tableSchema}). */
+export function parseHeaderLine(line, splitCells) {
+    return splitCells(line).map(parseHeaderCell);
+}
+// ---------- Header cell emit (§2.3 serialize) ----------
+function typeSpecText(type) {
+    switch (type.kind) {
+        case 'string': return 'string';
+        case 'number': return 'number';
+        case 'boolean': return 'boolean';
+        case 'list': return `list(${type.sep})`;
+    }
+}
+/** Escape `\` and `:` in a typed column name for header emission. */
+function escapeName(name) {
+    let out = '';
+    for (let i = 0; i < name.length; i++) {
+        const c = name[i];
+        if (c === '\\')
+            out += '\\\\';
+        else if (c === ':')
+            out += '\\:';
+        else
+            out += c;
+    }
+    return out;
+}
+/**
+ * Emit a header cell. Typed columns emit `name[:type][!]` with `\:` escaping;
+ * un-annotated columns fall back to the caller's plain cell serializer.
+ */
+export function emitHeaderCell(col, plainCell) {
+    if (!col.type && !col.required)
+        return plainCell(col.name);
+    let out = escapeName(col.name);
+    if (col.type)
+        out += ':' + typeSpecText(col.type);
+    if (col.required)
+        out += '!';
+    return out;
+}
+// ---------- Homogeneous cell coercion (§2.3) ----------
+function stripQuotesForList(raw) {
+    return isQuoted(raw) ? unescapeQuoted(raw.slice(1, -1)) : raw;
+}
+/**
+ * Coerce a raw cell to the column's declared type (§2.3). Un-annotated columns
+ * fall back to §3 coercion. Impossible coercions and empty required cells throw
+ * {@link TableParseError} — never a silent string.
+ */
+export function coerceTyped(raw, col) {
+    const isEmpty = raw === '';
+    if (isEmpty && col.required) {
+        throw new TableParseError(`column "${col.name}": required cell is empty`);
+    }
+    const type = col.type;
+    if (!type)
+        return coerce(raw);
+    switch (type.kind) {
+        case 'string': {
+            if (isEmpty)
+                return '';
+            return isQuoted(raw) ? unescapeQuoted(raw.slice(1, -1)) : raw;
+        }
+        case 'number': {
+            if (isEmpty)
+                return null;
+            const c = coerce(raw);
+            if (typeof c === 'number')
+                return c;
+            throw new TableParseError(`column "${col.name}": "${raw}" is not a number`);
+        }
+        case 'boolean': {
+            if (isEmpty)
+                return null;
+            const c = coerce(raw);
+            if (typeof c === 'boolean')
+                return c;
+            throw new TableParseError(`column "${col.name}": "${raw}" is not a boolean`);
+        }
+        case 'list': {
+            if (isEmpty)
+                return [];
+            const body = stripQuotesForList(raw);
+            return body.split(type.sep).map((e) => coerce(trimWs(e)));
+        }
+    }
+}
+// ---------- Derived JSON Schema (§2.3, tableSchema) ----------
+function typeToSchema(type) {
+    if (!type)
+        return {};
+    switch (type.kind) {
+        case 'string': return { type: 'string' };
+        case 'number': return { type: 'number' };
+        case 'boolean': return { type: 'boolean' };
+        case 'list': return { type: 'array', 'x-mdd': { separator: type.sep } };
+    }
+}
+/**
+ * Derive a JSON Schema fragment from a typed header (serialize-spec §2.3).
+ *
+ * `weight:number` → `{type:'number'}`, `!` → required, `list(;)` →
+ * `{type:'array', 'x-mdd':{separator:';'}}`. The result is derived, never stored.
+ */
+export function tableSchema(columns) {
+    const properties = {};
+    const required = [];
+    for (const col of columns) {
+        properties[col.name] = typeToSchema(col.type);
+        if (col.required)
+            required.push(col.name);
+    }
+    const schema = { type: 'object', properties };
+    if (required.length > 0)
+        schema.required = required;
+    return schema;
+}

package/dist/types.d.ts

@@ -0,0 +1,101 @@
+/** Format sigil — `$` for mdz, `@` for mdd. */
+export type Sigil = '@' | '$';
+export type Scalar = string | number | boolean | null;
+/**
+ * A recognised `${...}` interpolation, as a span in the containing raw text.
+ *
+ * nr-md lexes interpolations, it does not parse them: the span says WHERE the
+ * expression is, never what it means. The expression grammar belongs to whoever
+ * evaluates it — a different layer, possibly a different language.
+ */
+export interface InterpolationSpan {
+    /** Text between `${` and the matching `}`, verbatim. */
+    raw: string;
+    /** Offset of the `$` in the containing raw value. */
+    start: number;
+    /** Offset just past the closing `}` (exclusive). */
+    end: number;
+}
+/**
+ * A value that carries at least one `${...}` (or the `\${` opt-out marker).
+ *
+ * `raw` is the fact: original text, escapes NOT unfolded, interpolations left
+ * in place. Consumers that resolve interpolations read `raw`; `placeholders`
+ * is the lexer's index into it.
+ */
+export interface InterpolatedValue {
+    raw: string;
+    placeholders: InterpolationSpan[];
+}
+export type ListItem = Scalar | InterpolatedValue;
+/** A value inside a JSON5 object: scalars, arrays, nested objects. */
+export type Json5Value = Scalar | Json5Value[] | Json5Object;
+/**
+ * A JSON5 object used as an attribute value (§3; json5-scalar-spec).
+ *
+ * A plain object — no behaviour attached. A path into it (`${attr.path}`) is
+ * the evaluator's business, not the parser's.
+ */
+export interface Json5Object {
+    [key: string]: Json5Value;
+}
+export type AttributeValue = Scalar | ListItem[] | InterpolatedValue | Json5Object;
+export type BodyValue = string | InterpolatedValue;
+/**
+ * Source position of a tree node.
+ *
+ * Reserved slot: nothing populates it yet. It exists so that adding position
+ * tracking later cannot break an exhaustive walk written against this AST.
+ */
+export interface Pos {
+    /** 1-based line in the source text. */
+    line: number;
+    /** 1-based column. */
+    col: number;
+    /** 0-based character offset. */
+    offset: number;
+}
+export interface Attribute {
+    /** Dotted key as segments (§2.2). Single-segment keys → array of length 1. */
+    key: string[];
+    value: AttributeValue;
+    /** Reserved — see {@link Pos}. Not populated. */
+    pos?: Pos;
+}
+export interface Block {
+    /** Block name (after the sigil in the header). The root pseudo-block has an empty name. */
+    name: string;
+    /** Optional id from the header (§2.1). */
+    id?: string;
+    /** Effective level (1..6) after the baseLevel shift. Root is 0. */
+    level: number;
+    /** Attributes in order of appearance (relevant for §2.4 last-wins). */
+    attrs: Attribute[];
+    /** Block body, or undefined if empty. */
+    body?: BodyValue;
+    /** Child blocks in order of appearance. */
+    children: Block[];
+    /** Reserved — see {@link Pos}. Not populated. */
+    pos?: Pos;
+}
+export interface Document {
+    sigil: Sigil;
+    root: Block;
+}
+export interface ParseOptions {
+    /** Format sigil — `$` for mdz (default), `@` for mdd. */
+    sigil?: Sigil;
+    /** Offset added to the header `#` count; default 1 (h1 root). */
+    baseLevel?: number;
+}
+export interface SerializeOptions {
+    /**
+     * Format sigil to emit — `$` (mdz) | `@` (mdd).
+     * Defaults to the document's own sigil (`doc.sigil`).
+     */
+    sigil?: Sigil;
+    /** Level of root blocks; mirrors ParseOptions.baseLevel. Default 1. */
+    baseLevel?: number;
+    /** Line ending. Default `\n`. */
+    eol?: '\n' | '\r\n';
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+// Parse-tree types: what `parse` produces and `serialize` consumes.
+// Section numbers throughout this package refer to format-spec / serialize-spec,
+// the normative grammar reference (see README).
+export {};

package/dist/value.d.ts

@@ -0,0 +1,33 @@
+import type { AttributeValue, BodyValue, Sigil } from './types.js';
+interface EscapeMode {
+    /** Inside a flow-literal `[...]` element — `\,` is meaningful (§2.5). */
+    flow: boolean;
+}
+/**
+ * Unfold escape sequences in a value (§2.5).
+ *
+ * Always recognised: `\$`, `\@`, `\[`, `\{`, `\\`, `\n`, `\t`, `\${`.
+ * Context-dependent: `\,` (flow only); `\.` only inside `${}` paths and so
+ * is meaningful only inside `${}`, where this module does not reach.
+ *
+ * Note on `\${`: this branch is the RESOLVER's final-pass behaviour (run once,
+ * after all recursion settles). The parser must NOT feed `\${`-bearing values
+ * here — see hasOptOutEscape — or opt-out is lost when the value flows through
+ * recursion.
+ *
+ * Any other `\X` is preserved verbatim (backslash + char).
+ */
+export declare function unescape(s: string, mode: EscapeMode): string;
+/**
+ * Parse the raw text after an attribute's `:` (with surrounding ws stripped
+ * by the caller — single optional space after `:` already consumed; trailing
+ * trimmed). Returns a coerced scalar, a list (flow-literal), or an
+ * InterpolatedValue when `${}` is present.
+ */
+export declare function parseAttributeValue(raw: string, sigil: Sigil, line?: number, key?: string): AttributeValue;
+/**
+ * Parse a body string. Body is raw text; we only recognise `${}` and unfold
+ * escapes (§2.5 says escapes act in body too).
+ */
+export declare function parseBodyValue(raw: string): BodyValue;
+export {};

package/dist/value.js

@@ -0,0 +1,193 @@
+// Value parsing — escapes (§2.5), flow literals (§4), interpolation lexing (§7).
+import { coerce, isFullyQuoted } from './coerce.js';
+import { isJson5Shaped, parseJson5Object } from './json5-value.js';
+import { findMatchingBrace, hasOptOutEscape, scanInterpolations } from './interpolation.js';
+/**
+ * Unfold escape sequences in a value (§2.5).
+ *
+ * Always recognised: `\$`, `\@`, `\[`, `\{`, `\\`, `\n`, `\t`, `\${`.
+ * Context-dependent: `\,` (flow only); `\.` only inside `${}` paths and so
+ * is meaningful only inside `${}`, where this module does not reach.
+ *
+ * Note on `\${`: this branch is the RESOLVER's final-pass behaviour (run once,
+ * after all recursion settles). The parser must NOT feed `\${`-bearing values
+ * here — see hasOptOutEscape — or opt-out is lost when the value flows through
+ * recursion.
+ *
+ * Any other `\X` is preserved verbatim (backslash + char).
+ */
+export function unescape(s, mode) {
+    let out = '';
+    let i = 0;
+    while (i < s.length) {
+        if (s[i] === '\\' && i + 1 < s.length) {
+            // `\${` — a literal `${` (interpolation opt-out).
+            if (s[i + 1] === '$' && s[i + 2] === '{') {
+                out += '${';
+                i += 3;
+                continue;
+            }
+            const n = s[i + 1];
+            // `\{` — a literal `{` (§2.5): a value wrapped in braces stays a string
+            // instead of becoming a JSON5 object. Checked after `\${` above, so the
+            // interpolation opt-out is untouched.
+            if (n === '$' || n === '@' || n === '[' || n === '{' || n === '\\') {
+                out += n;
+                i += 2;
+                continue;
+            }
+            if (mode.flow && n === ',') {
+                out += ',';
+                i += 2;
+                continue;
+            }
+            // Unknown — preserve verbatim.
+            out += '\\' + n;
+            i += 2;
+            continue;
+        }
+        out += s[i];
+        i++;
+    }
+    return out;
+}
+// ---------- Flow-literal splitting (§4) ----------
+/**
+ * Split flow-literal body into elements by top-level commas, respecting
+ * string literals, escape sequences and nested `${...}`.
+ */
+function splitFlowElements(s) {
+    const out = [];
+    let buf = '';
+    let i = 0;
+    let inStr = false;
+    while (i < s.length) {
+        const c = s[i];
+        if (inStr) {
+            buf += c;
+            if (c === '\\' && i + 1 < s.length) {
+                buf += s[i + 1];
+                i += 2;
+                continue;
+            }
+            if (c === '"')
+                inStr = false;
+            i++;
+            continue;
+        }
+        if (c === '\\' && i + 1 < s.length) {
+            buf += c + s[i + 1];
+            i += 2;
+            continue;
+        }
+        if (c === '"') {
+            inStr = true;
+            buf += c;
+            i++;
+            continue;
+        }
+        if (c === '$' && s[i + 1] === '{') {
+            const close = findMatchingBrace(s, i + 2);
+            if (close === -1) {
+                buf += c;
+                i++;
+                continue;
+            }
+            buf += s.slice(i, close + 1);
+            i = close + 1;
+            continue;
+        }
+        if (c === ',') {
+            out.push(buf);
+            buf = '';
+            i++;
+            continue;
+        }
+        buf += c;
+        i++;
+    }
+    out.push(buf);
+    return out;
+}
+function trim(s) {
+    let a = 0;
+    let b = s.length;
+    while (a < b && (s[a] === ' ' || s[a] === '\t'))
+        a++;
+    while (b > a && (s[b - 1] === ' ' || s[b - 1] === '\t'))
+        b--;
+    return s.slice(a, b);
+}
+function parseFlowElement(raw) {
+    const t = trim(raw);
+    // A whole-element scalar literal `"..."` → coerce (quotes come off, `${}`
+    // inside stays literal). Otherwise the lexer sees everything.
+    if (isFullyQuoted(t))
+        return coerce(t);
+    const ph = scanInterpolations(t);
+    if (ph.length > 0 || hasOptOutEscape(t)) {
+        return { raw: t, placeholders: ph };
+    }
+    return coerce(unescape(t, { flow: true }));
+}
+// ---------- Public value parsers ----------
+/**
+ * Parse the raw text after an attribute's `:` (with surrounding ws stripped
+ * by the caller — single optional space after `:` already consumed; trailing
+ * trimmed). Returns a coerced scalar, a list (flow-literal), or an
+ * InterpolatedValue when `${}` is present.
+ */
+export function parseAttributeValue(raw, sigil, line, key) {
+    // Trim trailing whitespace (incl. \r left after split).
+    const value = trimTrailingWs(raw);
+    // Flow-literal trigger: sigil + `[` at the very start.
+    if (value.length >= 2 && value[0] === sigil && value[1] === '[') {
+        if (value[value.length - 1] !== ']') {
+            // Malformed — fall through to regular parsing.
+        }
+        else {
+            const inner = value.slice(2, value.length - 1);
+            if (trim(inner).length === 0)
+                return [];
+            return splitFlowElements(inner).map(parseFlowElement);
+        }
+    }
+    // A fully quoted value is a scalar literal: coerce strips the quotes and the
+    // `${}` inside stays literal. Partial quoting (JSON `{"m":"${x}"}`) is ordinary
+    // text — the lexer sees the `${}` and the value becomes an InterpolatedValue.
+    if (isFullyQuoted(value))
+        return coerce(value);
+    const ph = scanInterpolations(value);
+    if (ph.length > 0 || hasOptOutEscape(value)) {
+        // JSON5 detection waits until after resolution (§7.2): `{model: '${m}'}`
+        // becomes an object once the substitution has happened, not here.
+        return { raw: value, placeholders: ph };
+    }
+    // JSON5 object (§3) — tested on the RAW value, before unescape: otherwise
+    // `\{literal}` would unfold to `{literal}` and be caught by the detection.
+    if (isJson5Shaped(value))
+        return parseJson5Object(value, line, key);
+    return coerce(unescape(value, { flow: false }));
+}
+/**
+ * Parse a body string. Body is raw text; we only recognise `${}` and unfold
+ * escapes (§2.5 says escapes act in body too).
+ */
+export function parseBodyValue(raw) {
+    const ph = scanInterpolations(raw);
+    if (ph.length > 0 || hasOptOutEscape(raw)) {
+        return { raw, placeholders: ph };
+    }
+    return unescape(raw, { flow: false });
+}
+function trimTrailingWs(s) {
+    let end = s.length;
+    while (end > 0) {
+        const c = s[end - 1];
+        if (c === ' ' || c === '\t' || c === '\r')
+            end--;
+        else
+            break;
+    }
+    return s.slice(0, end);
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@notrealstudio/nr-md",
+  "version": "0.1.0",
+  "description": "Markdown as structured data: headings become blocks, $key: value lines become attributes. Parser and serializer for the mdd/mdz block grammar.",
+  "keywords": [
+    "markdown",
+    "parser",
+    "serializer",
+    "structured-data",
+    "ast",
+    "config",
+    "frontmatter",
+    "mdd",
+    "mdz",
+    "json5"
+  ],
+  "license": "MIT",
+  "author": "Julian Garrett",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./schema": {
+      "types": "./dist/schema.d.ts",
+      "import": "./dist/schema.js",
+      "default": "./dist/schema.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@notrealstudio/nr-json5": "file:../nr-json5"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^2.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Not-Real-Studio/nr-md.git"
+  },
+  "homepage": "https://github.com/Not-Real-Studio/nr-md#readme",
+  "bugs": {
+    "url": "https://github.com/Not-Real-Studio/nr-md/issues"
+  },
+  "peerDependencies": {
+    "ajv": "^8.12.0"
+  },
+  "peerDependenciesMeta": {
+    "ajv": {
+      "optional": true
+    }
+  }
+}