@notrealstudio/nr-md 0.1.0

package/dist/interpolation.d.ts

@@ -0,0 +1,41 @@
+import type { InterpolationSpan } from './types.js';
+/**
+ * Given that `${` opens just before `fromAfterOpen`, return the offset of the
+ * matching `}` in `s`, or -1 if it is unbalanced.
+ *
+ * Brace-balanced and aware of:
+ * - escape sequences `\X` (consume both characters)
+ * - nested `${...}` (increment depth; a bare `{` is NOT counted — §7.1 has no
+ *   bare braces outside string literals)
+ * - double-quoted strings (skip the content; honour `\"`)
+ */
+export declare function findMatchingBrace(s: string, fromAfterOpen: number): number;
+/**
+ * Scan a value or body string for `${...}` and return their spans, in source
+ * order.
+ *
+ * - `\${` is a literal `${` and is NOT an interpolation.
+ * - An unbalanced `${` is silently treated as literal text.
+ *
+ * NB: quotes are NOT skipped here. `${}` inside `"..."` in arbitrary text (JSON,
+ * prose) is a live interpolation; quotes are grammar only in a whole-value
+ * scalar literal (coerce.ts), not in this scan.
+ */
+export declare function scanInterpolations(s: string): InterpolationSpan[];
+/**
+ * Detect a backslash-escaped interpolation opener — the opt-out marker (§2.5).
+ *
+ * An escaped opener means "do NOT resolve this". The marker MUST survive parsing
+ * intact: unescaping it eagerly into a bare `${` would turn the value into an
+ * ordinary interpolation, and a resolver would substitute it the moment the
+ * value flowed through recursion — silently breaking opt-out (format-spec
+ * open #1: in values and results, not only in source text).
+ *
+ * So any value carrying the marker is stored as an InterpolatedValue with `raw`
+ * preserved, escapes NOT unfolded.
+ *
+ * Char codes (no string literals) keep this robust across edit transports. The
+ * walk mirrors scanInterpolations' escape handling, so an escaped backslash
+ * followed by a LIVE interpolation is not a false positive.
+ */
+export declare function hasOptOutEscape(s: string): boolean;

package/dist/interpolation.js

@@ -0,0 +1,135 @@
+// Interpolation lexing (§7) — brace-balanced, no regex, internal to nr-md.
+//
+// The split this file draws: nr-md answers "does this value interpolate, and
+// where", never "what does the expression mean". Recognising `${...}` is
+// lexical — you need it to tokenise attribute values at all, since a comma or a
+// closing bracket inside `${}` is not a delimiter. Reading the expression is a
+// different language on top, and it belongs to whoever evaluates it.
+//
+// So: spans out, no expression tree, no evaluation vocabulary in the AST.
+/**
+ * Given that `${` opens just before `fromAfterOpen`, return the offset of the
+ * matching `}` in `s`, or -1 if it is unbalanced.
+ *
+ * Brace-balanced and aware of:
+ * - escape sequences `\X` (consume both characters)
+ * - nested `${...}` (increment depth; a bare `{` is NOT counted — §7.1 has no
+ *   bare braces outside string literals)
+ * - double-quoted strings (skip the content; honour `\"`)
+ */
+export function findMatchingBrace(s, fromAfterOpen) {
+    let depth = 1;
+    let i = fromAfterOpen;
+    while (i < s.length) {
+        const c = s[i];
+        if (c === '\\' && i + 1 < s.length) {
+            i += 2;
+            continue;
+        }
+        if (c === '"') {
+            i++;
+            while (i < s.length) {
+                if (s[i] === '\\' && i + 1 < s.length) {
+                    i += 2;
+                    continue;
+                }
+                if (s[i] === '"') {
+                    i++;
+                    break;
+                }
+                i++;
+            }
+            continue;
+        }
+        if (c === '$' && i + 1 < s.length && s[i + 1] === '{') {
+            depth++;
+            i += 2;
+            continue;
+        }
+        if (c === '}') {
+            depth--;
+            if (depth === 0)
+                return i;
+            i++;
+            continue;
+        }
+        i++;
+    }
+    return -1;
+}
+/**
+ * Scan a value or body string for `${...}` and return their spans, in source
+ * order.
+ *
+ * - `\${` is a literal `${` and is NOT an interpolation.
+ * - An unbalanced `${` is silently treated as literal text.
+ *
+ * NB: quotes are NOT skipped here. `${}` inside `"..."` in arbitrary text (JSON,
+ * prose) is a live interpolation; quotes are grammar only in a whole-value
+ * scalar literal (coerce.ts), not in this scan.
+ */
+export function scanInterpolations(s) {
+    const out = [];
+    let i = 0;
+    while (i < s.length) {
+        const c = s[i];
+        if (c === '\\' && s[i + 1] === '$' && s[i + 2] === '{') {
+            // literal ${
+            i += 3;
+            continue;
+        }
+        if (c === '\\' && i + 1 < s.length) {
+            i += 2;
+            continue;
+        }
+        if (c === '$' && s[i + 1] === '{') {
+            const start = i;
+            const end = findMatchingBrace(s, i + 2);
+            if (end === -1) {
+                // Unbalanced — literal text; step past the `$`.
+                i++;
+                continue;
+            }
+            out.push({ raw: s.slice(i + 2, end), start, end: end + 1 });
+            i = end + 1;
+            continue;
+        }
+        i++;
+    }
+    return out;
+}
+/**
+ * Detect a backslash-escaped interpolation opener — the opt-out marker (§2.5).
+ *
+ * An escaped opener means "do NOT resolve this". The marker MUST survive parsing
+ * intact: unescaping it eagerly into a bare `${` would turn the value into an
+ * ordinary interpolation, and a resolver would substitute it the moment the
+ * value flowed through recursion — silently breaking opt-out (format-spec
+ * open #1: in values and results, not only in source text).
+ *
+ * So any value carrying the marker is stored as an InterpolatedValue with `raw`
+ * preserved, escapes NOT unfolded.
+ *
+ * Char codes (no string literals) keep this robust across edit transports. The
+ * walk mirrors scanInterpolations' escape handling, so an escaped backslash
+ * followed by a LIVE interpolation is not a false positive.
+ */
+export function hasOptOutEscape(s) {
+    const BACKSLASH = 92;
+    const DOLLAR = 36;
+    const BRACE = 123;
+    let i = 0;
+    while (i < s.length) {
+        if (s.charCodeAt(i) === BACKSLASH &&
+            s.charCodeAt(i + 1) === DOLLAR &&
+            s.charCodeAt(i + 2) === BRACE) {
+            return true;
+        }
+        if (s.charCodeAt(i) === BACKSLASH && i + 1 < s.length) {
+            i += 2;
+            continue;
+        }
+        i++;
+    }
+    return false;
+}

package/dist/json5-value.d.ts

@@ -0,0 +1,30 @@
+import type { Json5Object } from './types.js';
+/** A malformed JSON5 attribute value (same convention as TableParseError, §5). */
+export declare class Json5ParseError extends Error {
+    /** 1-based line in the source document, when known. */
+    readonly line?: number;
+    /** Attribute key the value belongs to, when known. */
+    readonly key?: string;
+    constructor(message: string, line?: number, key?: string);
+}
+/**
+ * The shape of a JSON5 object (§3): the value opens with `{` and closes with `}`.
+ *
+ * Test the RAW value, before unescape. Otherwise `\{literal}` would unfold to
+ * `{literal}` first, get caught by the detection, and the escape (§2.5) would
+ * stop working.
+ *
+ * `{name} says hi` opens with `{` but does not close with `}`, so it is not the
+ * shape — just prose. Prose and this detection do not collide.
+ */
+export declare function isJson5Shaped(raw: string): boolean;
+/** Flat guard telling a JSON5 object from an InterpolatedValue (`{raw, placeholders}`). */
+export declare function isJson5Object(v: unknown): v is Json5Object;
+/**
+ * Strict parse of a value that passed {@link isJson5Shaped} (§3).
+ *
+ * Single-line is a consequence of position, not a rule: an attribute value does
+ * not wrap. A multi-line result substituted into a JSON5 string is invalid and
+ * throws, deliberately — multi-line structure is what blocks are for.
+ */
+export declare function parseJson5Object(raw: string, line?: number, key?: string): Json5Object;

package/dist/json5-value.js

@@ -0,0 +1,79 @@
+// JSON5 object as an attribute value (format-spec §3; json5-scalar-spec).
+// Detection is by shape and it is strict: `{...}` MUST be a valid JSON5 object.
+// Malformed input throws with a line number — no silent fallback to a string.
+import { parseJson5 } from '@notrealstudio/nr-json5';
+const LBRACE = 123; // {
+const RBRACE = 125; // }
+/** A malformed JSON5 attribute value (same convention as TableParseError, §5). */
+export class Json5ParseError extends Error {
+    /** 1-based line in the source document, when known. */
+    line;
+    /** Attribute key the value belongs to, when known. */
+    key;
+    constructor(message, line, key) {
+        super(message);
+        this.name = 'Json5ParseError';
+        this.line = line;
+        this.key = key;
+    }
+}
+/** Trim spaces/tabs at both ends (string primitives, no regex). */
+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);
+}
+/**
+ * The shape of a JSON5 object (§3): the value opens with `{` and closes with `}`.
+ *
+ * Test the RAW value, before unescape. Otherwise `\{literal}` would unfold to
+ * `{literal}` first, get caught by the detection, and the escape (§2.5) would
+ * stop working.
+ *
+ * `{name} says hi` opens with `{` but does not close with `}`, so it is not the
+ * shape — just prose. Prose and this detection do not collide.
+ */
+export function isJson5Shaped(raw) {
+    const s = trim(raw);
+    return s.length >= 2 && s.charCodeAt(0) === LBRACE && s.charCodeAt(s.length - 1) === RBRACE;
+}
+/** Flat guard telling a JSON5 object from an InterpolatedValue (`{raw, placeholders}`). */
+export function isJson5Object(v) {
+    return (typeof v === 'object' &&
+        v !== null &&
+        !Array.isArray(v) &&
+        !('raw' in v && 'placeholders' in v) &&
+        typeof v.cast !== 'function');
+}
+function where(line, key) {
+    const k = key === undefined ? 'attribute value' : `$${key}`;
+    const l = line === undefined ? '' : ` (line ${line})`;
+    return `${k}${l}`;
+}
+/**
+ * Strict parse of a value that passed {@link isJson5Shaped} (§3).
+ *
+ * Single-line is a consequence of position, not a rule: an attribute value does
+ * not wrap. A multi-line result substituted into a JSON5 string is invalid and
+ * throws, deliberately — multi-line structure is what blocks are for.
+ */
+export function parseJson5Object(raw, line, key) {
+    const text = trim(raw);
+    let parsed;
+    try {
+        parsed = parseJson5(text);
+    }
+    catch (e) {
+        const detail = e instanceof Error ? e.message : String(e);
+        throw new Json5ParseError(`${where(line, key)}: ${detail}`, line, key);
+    }
+    // The shape guarantees an object, but parseJson5 returns unknown — narrow honestly.
+    if (!isJson5Object(parsed)) {
+        throw new Json5ParseError(`${where(line, key)}: JSON5 value is not an object`, line, key);
+    }
+    return parsed;
+}

package/dist/parser.d.ts

@@ -0,0 +1,3 @@
+import type { Document, ParseOptions } from './types.js';
+/** A line that does not match any structured form contributes to body. */
+export declare function parse(text: string, options?: ParseOptions): Document;

package/dist/parser.js

@@ -0,0 +1,227 @@
+// Top-level parser for mdd/mdz documents (§2, §6).
+import { parseAttributeValue, parseBodyValue } from './value.js';
+import { isFullyQuoted, unescapeQuoted } from './coerce.js';
+const CC_A_UP = 65;
+const CC_Z_UP = 90;
+const CC_A_LO = 97;
+const CC_Z_LO = 122;
+const CC_0 = 48;
+const CC_9 = 57;
+const CC_UNDER = 95;
+const CC_DASH = 45;
+const CC_DOT = 46;
+function isNameStart(c) {
+    return (c >= CC_A_UP && c <= CC_Z_UP) || (c >= CC_A_LO && c <= CC_Z_LO) || c === CC_UNDER;
+}
+function isNameCont(c) {
+    return (isNameStart(c) ||
+        (c >= CC_0 && c <= CC_9) ||
+        c === CC_DASH);
+}
+function isBlockNameCont(c) {
+    return isNameCont(c) || c === CC_DOT;
+}
+/** Read `#`-prefix and return raw hash count, or null. */
+function readHashes(line) {
+    let n = 0;
+    while (n < line.length && line[n] === '#')
+        n++;
+    if (n === 0)
+        return null;
+    return { count: n, next: n };
+}
+/**
+ * Try to parse a markdown heading as a structured block header.
+ *
+ * Returns null when the line isn't a structured header (regular markdown
+ * heading, or just non-header text).
+ */
+function parseHeader(line, sigil) {
+    const hash = readHashes(line);
+    if (!hash)
+        return null;
+    if (hash.count < 1 || hash.count > 6)
+        return null;
+    if (line[hash.next] !== ' ')
+        return null;
+    let i = hash.next + 1;
+    if (line[i] !== sigil)
+        return null;
+    const rest = line.slice(i);
+    // Closing forms.
+    if (rest === sigil) {
+        return { level: hash.count, closing: true, name: '' };
+    }
+    if (sigil === '$' && rest === '$@') {
+        return { level: hash.count, closing: true, name: '' };
+    }
+    if (sigil === '@' && rest === '@@') {
+        return { level: hash.count, closing: true, name: '' };
+    }
+    if (sigil === '$' && rest === '$$') {
+        // `## $$` reserved (Obsidian math conflict, §2.1) — not a header.
+        return null;
+    }
+    i++; // consume sigil
+    // Block name (allows dot).
+    if (i >= line.length)
+        return null;
+    if (!isNameStart(line.charCodeAt(i)))
+        return null;
+    const nameStart = i;
+    i++;
+    while (i < line.length && isBlockNameCont(line.charCodeAt(i)))
+        i++;
+    const name = line.slice(nameStart, i);
+    let id;
+    if (i < line.length) {
+        if (line[i] !== ' ')
+            return null;
+        const tail = line.slice(i + 1).trim();
+        // Bare id — rest of the line as-is. Quotes are for an id that bare form
+        // would lose: edge whitespace, or an empty string (§2.1).
+        if (tail.length > 0)
+            id = isFullyQuoted(tail) ? unescapeQuoted(tail.slice(1, -1)) : tail;
+    }
+    return { level: hash.count, closing: false, name, id };
+}
+/**
+ * Parse a line as `$key: value` / `$a.b: value`. Returns null if the line
+ * is not a valid attribute.
+ */
+function parseAttribute(line, sigil) {
+    if (line.length === 0)
+        return null;
+    if (line[0] !== sigil)
+        return null;
+    let i = 1;
+    if (i >= line.length)
+        return null;
+    if (!isNameStart(line.charCodeAt(i)))
+        return null;
+    // Key is a single literal name; a dot is part of the name (§2.2), exactly like
+    // block names (§2.1). NO path-splitting, NO escape on the key side — addressing
+    // a dotted key from a placeholder uses the escape there (§7.1), not here.
+    const keyStart = i;
+    i++;
+    while (i < line.length && isBlockNameCont(line.charCodeAt(i)))
+        i++;
+    const segs = [line.slice(keyStart, i)];
+    if (line[i] !== ':')
+        return null;
+    i++;
+    if (line[i] === ' ')
+        i++;
+    return { key: segs, rawValue: line.slice(i) };
+}
+// ---------- Body line ----------
+/** A line that does not match any structured form contributes to body. */
+// ---------- Driver ----------
+export function parse(text, options = {}) {
+    const sigil = options.sigil ?? '$';
+    const baseLevel = options.baseLevel ?? 1;
+    if (baseLevel < 1 || baseLevel > 6) {
+        throw new Error(`baseLevel must be in 1..6, got ${baseLevel}`);
+    }
+    // Normalise line endings (§2: parser normalises \r\n → \n).
+    const normalised = normaliseNewlines(text);
+    const lines = normalised.split('\n');
+    const root = { name: '', level: 0, attrs: [], children: [] };
+    const stack = [root];
+    let bodyLines = [];
+    // Raw (un-unescaped) body per block — the source of truth when stanzas are
+    // joined. The body stays raw until the final assembly, and unescape runs
+    // exactly once, in parseBodyValue, over the COMPLETE raw text (§2.5).
+    // Unescaping per fragment would double-unescape a resumed body (\\$ → \$ → $).
+    const bodyRaw = new Map();
+    const flushBody = (target) => {
+        // Drop trailing/leading blank-only lines — they are "separators" (§2.3).
+        let start = 0;
+        let end = bodyLines.length;
+        while (start < end && bodyLines[start].length === 0)
+            start++;
+        while (end > start && bodyLines[end - 1].length === 0)
+            end--;
+        if (start < end) {
+            const frag = bodyLines.slice(start, end).join('\n');
+            // Body resumed after a nested block closed → append raw as strophes.
+            const prev = bodyRaw.get(target);
+            const full = prev === undefined ? frag : prev + '\n\n' + frag;
+            bodyRaw.set(target, full);
+            target.body = parseBodyValue(full); // one unescape, over the whole raw
+        }
+        bodyLines = [];
+    };
+    const top = () => stack[stack.length - 1];
+    for (let li = 0; li < lines.length; li++) {
+        const line = lines[li];
+        const header = parseHeader(line, sigil);
+        if (header) {
+            // Effective level — header.level minus (baseLevel - 1).
+            const effLevel = header.level - (baseLevel - 1);
+            if (header.closing) {
+                flushBody(top());
+                // Pop everything back to root (global zone).
+                while (stack.length > 1)
+                    stack.pop();
+                continue;
+            }
+            if (effLevel < 1) {
+                // Heading below baseLevel — treat as body content (regular markdown).
+                bodyLines.push(line);
+                continue;
+            }
+            flushBody(top());
+            // Pop until parent's level < new block's level.
+            while (stack.length > 1 && top().level >= effLevel) {
+                stack.pop();
+            }
+            const block = {
+                name: header.name,
+                level: effLevel,
+                attrs: [],
+                children: [],
+            };
+            if (header.id !== undefined)
+                block.id = header.id;
+            top().children.push(block);
+            stack.push(block);
+            continue;
+        }
+        const attr = parseAttribute(line, sigil);
+        if (attr) {
+            // li is a 0-based index into the lines; errors (Json5ParseError) are 1-based.
+            const value = parseAttributeValue(attr.rawValue, sigil, li + 1, attr.key.join('.'));
+            const a = { key: attr.key, value };
+            top().attrs.push(a);
+            continue;
+        }
+        // Anything else is a body line. Empty lines are kept for now; they may
+        // get trimmed by flushBody if they sit at the edges.
+        bodyLines.push(line);
+    }
+    // Flush trailing body of every open block.
+    while (stack.length > 0) {
+        flushBody(top());
+        stack.pop();
+    }
+    return { sigil, root };
+}
+function normaliseNewlines(s) {
+    let out = '';
+    let i = 0;
+    while (i < s.length) {
+        const c = s[i];
+        if (c === '\r') {
+            out += '\n';
+            if (s[i + 1] === '\n')
+                i += 2;
+            else
+                i++;
+            continue;
+        }
+        out += c;
+        i++;
+    }
+    return out;
+}

package/dist/schema.d.ts

@@ -0,0 +1,80 @@
+import type { Sigil } from './types.js';
+import { type JSONSchema } from './typed-header.js';
+export type { JSONSchema } from './typed-header.js';
+/**
+ * Where a field is stored in mdd/mdz (serialize-spec §3.2).
+ *
+ * `block` — the field travels as its OWN child block, the value in that block's
+ * body. Unlike `body` (the parent block's body, so at most one such field), an
+ * object may have any number of these: the prose fields (description, scenario…).
+ */
+export type XStorage = 'attr' | 'body' | 'name' | 'id' | 'block';
+/** How an array is laid out (`x-mdd.list`, §3.2). */
+export type XListMode = 'flow' | 'tbl' | 'lines' | 'blocks';
+/** Representation refinement (`x-mdd.as`, §3.9) — `json`: a fenced JSON block (opaque). */
+export type XAs = 'json';
+/**
+ * Key of the catch-all bag holding fields NOT described by the schema.
+ *
+ * Enabled per object schema with `x-mdd: { unknown: 'block' }`; `parseWithSchema`
+ * collects every unclaimed attribute/block here and `serializeWithSchema` emits
+ * the bag back — round-trip of foreign extensions is lossless.
+ */
+export declare const UNKNOWN_KEY = "$unknown";
+/**
+ * Block name of the overflow bag: unknown keys that are NOT valid mdd names
+ * (spaces, leading digits…) cannot be an attribute or a block header, so they
+ * travel together in one fenced-JSON block instead of being dropped.
+ */
+export declare const UNKNOWN_OVERFLOW_BLOCK = "_unknown";
+export interface SchemaSerializeOptions {
+    sigil?: Sigil;
+    baseLevel?: number;
+    eol?: '\n' | '\r\n';
+    /** Diagnostics sink (lossy fallbacks, type conflicts). Default: `console.warn`. */
+    warn?: (msg: string) => void;
+}
+export interface ParseWithSchemaOptions {
+    sigil?: Sigil;
+    baseLevel?: number;
+    /** Diagnostics sink (type conflicts between inline tbl header and schema). Default: `console.warn`. */
+    warn?: (msg: string) => void;
+}
+export interface ValidationError {
+    /** JSON-pointer-ish path to the offending value (`` for root). */
+    path: string;
+    message: string;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+}
+export interface ValidateOptions {
+    /** Inject a validator (e.g. a native one) instead of the Ajv delegate. */
+    validator?: (obj: unknown, schema: JSONSchema) => ValidationResult;
+}
+/**
+ * Serialize an object to mdd/mdz text through a JSON Schema (serialize-spec §3.3).
+ *
+ * Layout by `x-storage` (attr | body | name | id) and `x-mdd` (list: flow | tbl |
+ * lines | blocks, unknown: block). Field order = order of schema `properties` —
+ * deterministic, so the same object always serializes byte-for-byte identically.
+ */
+export declare function serializeWithSchema(obj: unknown, schema: JSONSchema, opts?: SchemaSerializeOptions): string;
+/**
+ * Parse mdd/mdz text back into an object through a JSON Schema (serialize-spec §3.3).
+ *
+ * Inverse of {@link serializeWithSchema}: reassembles the object from x-storage
+ * placement and coerces each field by its schema type (schema type wins over
+ * YAML coercion). Generic `<T>` is a TS-only convenience — no runtime effect.
+ */
+export declare function parseWithSchema<T = unknown>(text: string, schema: JSONSchema, opts?: ParseWithSchemaOptions): T;
+/**
+ * Validate an object against a schema (serialize-spec §3.4).
+ *
+ * Delegates to Ajv2020 with `addVocabulary(['x-storage','x-mdd','x-ui'])` so the
+ * strict mode does not choke on our x-extensions (nr-schema §5). Ajv is an
+ * OPTIONAL peer — when it is not installed and no `opts.validator` is provided,
+ * a clear error is thrown ("install ajv or provide a validator").
+ */
+export declare function validate(obj: unknown, schema: JSONSchema, opts?: ValidateOptions): ValidationResult;