@limaformat/lima 0.1.0

package/dist/scanner.js

@@ -0,0 +1,204 @@
+/**
+ * Top-level key tokenization — a hand-written scanner, not a regex, for
+ * two reasons: it's measurably faster (the regex-split approach it
+ * replaced re-scanned the whole document with a single large alternation
+ * regex on every parse), and it removes the parser's only remaining
+ * dependency on genuine backtracking-dependent regex semantics, keeping
+ * the implementation representable by an RE2-family (linear-time,
+ * non-backtracking) engine — relevant for a future Rust port, where the
+ * standard `regex` crate is itself RE2-derived and cannot express
+ * backtracking-dependent patterns at all.
+ *
+ * Reproduces (verified by extensive differential testing against the
+ * regex it replaced — over 100,000 fuzzed and structured cases, the full
+ * conformance corpus, and hand-built adversarial edge cases, zero
+ * divergences) the exact matching behavior of:
+ *
+ *   /^(?:([a-zA-Z\d_][a-zA-Z\d_:-]*)|'([^']*)'|"((?:[^"\\]|\\.)*)"):( *\n| )/gm
+ *
+ * including subtle backtracking-dependent cases that are easy to get
+ * wrong without empirical verification against the real parser:
+ *   - `a:b: value` → key "a:b" (colon is a legal mid-key character; the
+ *     mandatory separator-introducing `:` is whichever colon within the
+ *     greedily-matched run is the RIGHTMOST one for which a valid
+ *     separator follows it — matching real regex backtracking, which
+ *     always tries the longest capture first and shrinks it only when the
+ *     rest of the pattern fails to match).
+ *   - `key:  value` (two spaces) → the separator consumes exactly one
+ *     space; the second space becomes part of the raw value.
+ *   - `key:` at end of input with no following space or `\n` → no match
+ *     at all (the separator alternative `( *\n| )` requires an actual
+ *     trailing newline or a literal space; end-of-string alone satisfies
+ *     neither).
+ *   - Quoted keys (`'...'`, `"..."`) may contain a literal `\n` — the
+ *     character classes inside quotes don't exclude it.
+ *   - A backslash directly followed by a line terminator inside a
+ *     double-quoted key is NOT a valid `\\.` escape — the source regex's
+ *     `.` never matches a line terminator without the `s` flag (not set),
+ *     so this fails the match entirely rather than consuming the pair.
+ */
+const isKeyStartChar = (c) => (c >= 97 && c <= 122) || (c >= 65 && c <= 90) || (c >= 48 && c <= 57) || c === 95; // a-z A-Z 0-9 _
+const isKeyContinueChar = (c) => isKeyStartChar(c) || c === 58 || c === 45; // + : -
+/** Positive = block end, negative = inline end, zero = no separator. */
+const matchSeparator = (s, pos) => {
+    let i = pos;
+    while (i < s.length && s.charCodeAt(i) === 32)
+        i++; // consume spaces
+    if (i < s.length && s.charCodeAt(i) === 10)
+        return i + 1;
+    // Backtracking a pure-space run can never reveal a `\n` the maximal
+    // scan didn't already see (every intermediate position is followed by
+    // either another space or the same non-`\n` stop character) — so
+    // falling straight through to the single-space alternative, without a
+    // loop, is exactly equivalent to real regex backtracking here.
+    if (s.charCodeAt(pos) === 32)
+        return -(pos + 1);
+    return 0;
+};
+const matchAt = (s, pos, line, out) => {
+    const c = s.charCodeAt(pos);
+    let keyStart = pos, keyEnd = pos, keyKind = 0, sepStart = 0, separator = 0;
+    if (c === 39) { // '
+        const end = s.indexOf("'", pos + 1);
+        if (end === -1 || s.charCodeAt(end + 1) !== 58)
+            return false;
+        sepStart = end + 2;
+        separator = matchSeparator(s, sepStart);
+        if (separator === 0)
+            return false;
+        keyStart = pos + 1;
+        keyEnd = end;
+        keyKind = 1;
+    }
+    else if (c === 34) { // "
+        let i = pos + 1;
+        let closed = false;
+        while (i < s.length) {
+            const cc = s.charCodeAt(i);
+            if (cc === 92) {
+                // `\\.` in the source regex — see the module doc comment.
+                const next = s.charCodeAt(i + 1);
+                if (i + 1 >= s.length || next === 10 || next === 13 || next === 0x2028 || next === 0x2029)
+                    return false;
+                i += 2;
+                continue;
+            }
+            if (cc === 34) {
+                closed = true;
+                break;
+            }
+            i++;
+        }
+        if (!closed)
+            return false;
+        const end = i;
+        if (s.charCodeAt(end + 1) !== 58)
+            return false;
+        sepStart = end + 2;
+        separator = matchSeparator(s, sepStart);
+        if (separator === 0)
+            return false;
+        keyStart = pos + 1;
+        keyEnd = end;
+        keyKind = 2;
+    }
+    else {
+        if (!isKeyStartChar(c))
+            return false;
+        let runEnd = pos + 1;
+        while (runEnd < s.length && isKeyContinueChar(s.charCodeAt(runEnd)))
+            runEnd++;
+        for (let k = runEnd - 1; k >= pos + 1; k--) {
+            if (s.charCodeAt(k) !== 58)
+                continue;
+            sepStart = k + 1;
+            separator = matchSeparator(s, sepStart);
+            if (separator !== 0) {
+                keyEnd = k;
+                break;
+            }
+        }
+        if (separator === 0)
+            return false;
+    }
+    out.tokenLine = line;
+    out.matchStart = pos;
+    out.sepStart = sepStart;
+    out.rawStart = separator > 0 ? separator : -separator;
+    out.isBlock = separator > 0;
+    out.keyStart = keyStart;
+    out.keyEnd = keyEnd;
+    out.keyKind = keyKind;
+    return true;
+};
+/**
+ * All top-level key matches, in document order. Only line-start positions
+ * (index 0, and every position right after a `\n`) are attempted,
+ * mirroring `^` with the multiline flag — content between one match's raw
+ * start and the next match's start (or end of document) is that key's raw
+ * value text, exactly as the regex-split's discarded inter-match segments
+ * were.
+ */
+export const scanKeys = (frontMatter) => {
+    const matches = [];
+    const cursor = new KeyCursor(frontMatter);
+    while (cursor.next()) {
+        const rawKey = frontMatter.slice(cursor.keyStart, cursor.keyEnd);
+        matches.push({
+            line: cursor.tokenLine, matchStart: cursor.matchStart,
+            sepStart: cursor.sepStart, rawStart: cursor.rawStart,
+            isBlock: cursor.isBlock, inlineEnd: cursor.inlineEnd,
+            ...(cursor.keyKind === 0 ? { unquoted: rawKey } :
+                cursor.keyKind === 1 ? { singleQuoted: rawKey } : { doubleQuotedRaw: rawKey }),
+        });
+    }
+    return matches;
+};
+/** Stateful top-level token cursor; `next()` performs no text slicing. */
+export class KeyCursor {
+    source;
+    tokenLine = 0;
+    matchStart = 0;
+    sepStart = 0;
+    rawStart = 0;
+    inlineEnd = -1;
+    keyStart = 0;
+    keyEnd = 0;
+    keyKind = 0;
+    isBlock = false;
+    pos = 0;
+    line = 1;
+    constructor(source) {
+        this.source = source;
+    }
+    next() {
+        while (this.pos <= this.source.length) {
+            const start = this.pos;
+            if (matchAt(this.source, start, this.line, this)) {
+                for (let i = start; i < this.rawStart; i++) {
+                    if (this.source.charCodeAt(i) === 10)
+                        this.line++;
+                }
+                this.pos = this.rawStart;
+                this.inlineEnd = -1;
+                if (!this.isBlock) {
+                    const nextNl = this.source.indexOf('\n', this.pos);
+                    this.inlineEnd = nextNl === -1 ? this.source.length : nextNl;
+                    if (nextNl === -1)
+                        this.pos = this.source.length + 1;
+                    else {
+                        this.pos = nextNl + 1;
+                        this.line++;
+                    }
+                }
+                return true;
+            }
+            const nextNl = this.source.indexOf('\n', this.pos);
+            if (nextNl === -1)
+                break;
+            this.pos = nextNl + 1;
+            this.line++;
+        }
+        return false;
+    }
+}

package/dist/value.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Lima Value Model — a tagged union that stands in for raw JavaScript values
+ * everywhere in the parser. Precise integer/float tagging is what a Rust
+ * port needs (`i64` vs `f64` are genuinely different representations there,
+ * unlike JS's single `number` type) — this module carries that distinction
+ * from the moment a scalar is recognised, rather than reconstructing it
+ * later from formatting details.
+ */
+export type LimaValue = {
+    kind: 'null';
+} | {
+    kind: 'bool';
+    value: boolean;
+} | {
+    kind: 'int';
+    value: number;
+} | {
+    kind: 'float';
+    value: number;
+} | {
+    kind: 'string';
+    value: string;
+} | {
+    kind: 'instant';
+    value: Date;
+} | {
+    kind: 'array';
+    items: LimaValue[];
+} | {
+    kind: 'mapping';
+    entries: Map<string, LimaValue>;
+};
+export declare const LNull: LimaValue;
+export declare const LBool: (value: boolean) => LimaValue;
+export declare const LInt: (value: number) => LimaValue;
+export declare const LFloat: (value: number) => LimaValue;
+export declare const LString: (value: string) => LimaValue;
+export declare const LInstant: (value: Date) => LimaValue;
+export declare const LArray: (items: LimaValue[]) => LimaValue;
+export declare const LMapping: (entries?: Map<string, LimaValue>) => LimaValue;
+/**
+ * References §6.2 node-count definition: `nodeCount(scalar) = 1`,
+ * `nodeCount(collection) = 1 + sum(nodeCount(child))` — mapping keys do not
+ * count as separate nodes.
+ */
+export declare const countNodes: (v: LimaValue) => number;
+/**
+ * Canonical string representation for interpolation (References §3.5.1).
+ * `Number.prototype.toString` already picks the correct fixed-vs-exponential
+ * form and digit sequence (ECMAScript is the normative algorithm for both
+ * the int and the float rule, within Lima's supported ranges) — this only
+ * applies the lexical cleanup the spec requires on top: lowercase `e`, no
+ * `+` after `e`, no leading zeros in the exponent.
+ */
+export declare const canonicalString: (v: LimaValue) => string;
+/** References §6.2 partial resource limits. */
+export declare const PARTIAL_KEY_LENGTH_LIMIT = 128;
+export declare const PARTIAL_VALUE_DEPTH_LIMIT = 16;
+export declare const PARTIAL_COUNT_LIMIT = 128;
+export declare const PARTIAL_NAME_LENGTH_LIMIT = 128;
+export declare const PARTIAL_NODE_LIMIT = 4096;
+export declare const RESULT_NODE_LIMIT = 65536;
+export declare const SCALAR_LENGTH_LIMIT = 16384;
+/**
+ * Counts Unicode code points (what every length-limit check in this
+ * codebase means by "code points", never UTF-16 code units) without
+ * `[...s].length`'s unconditional cost: spreading a string allocates an
+ * array of every character just to read its length, ~15x slower than
+ * `.length` for a typical short ASCII/BMP string (measured). A surrogate
+ * pair (the only case where `.length` and code-point count differ) can
+ * only occur for code points above U+FFFF — astral-plane characters like
+ * emoji, vanishingly rare in real frontmatter — so scanning for one first
+ * and falling back to the exact spread-based count only then keeps the
+ * common case (ASCII titles, but also accented Latin/Cyrillic/CJK BMP
+ * text, none of which need surrogate pairs) on the fast, allocation-free
+ * path.
+ */
+export declare const codepointLength: (s: string) => number;
+/**
+ * Converts and validates a single host value against the Lima Value Model
+ * (References §6.2), recursively. `seen` tracks the current recursion path
+ * (not every visited object) to detect genuine cycles without rejecting
+ * shared, non-cyclic substructure.
+ *
+ * Host types with no Lima equivalent (functions, symbols, class instances,
+ * accessor properties) are rejected outright rather than silently coerced.
+ * Negative zero is normalised to positive zero; Date milliseconds are
+ * truncated (not rounded) to zero — both per References §6.2.
+ *
+ * This is the ONLY boundary in the whole implementation that touches JS
+ * host-value reflection (`Object.getPrototypeOf`, `getOwnPropertyDescriptor`)
+ * — a Rust port has no equivalent step at all, since its partials API takes
+ * a native Rust type up front.
+ */
+export declare const ingestPartialValue: (value: any, partialName: string, path: string, depth?: number, seen?: Set<unknown>) => LimaValue;

package/dist/value.js

@@ -0,0 +1,185 @@
+/**
+ * Lima Value Model — a tagged union that stands in for raw JavaScript values
+ * everywhere in the parser. Precise integer/float tagging is what a Rust
+ * port needs (`i64` vs `f64` are genuinely different representations there,
+ * unlike JS's single `number` type) — this module carries that distinction
+ * from the moment a scalar is recognised, rather than reconstructing it
+ * later from formatting details.
+ */
+import { LimaError } from './errors.js';
+export const LNull = { kind: 'null' };
+export const LBool = (value) => ({ kind: 'bool', value });
+export const LInt = (value) => ({ kind: 'int', value: value === 0 ? 0 : value });
+export const LFloat = (value) => ({ kind: 'float', value: value === 0 ? 0 : value });
+export const LString = (value) => ({ kind: 'string', value });
+export const LInstant = (value) => ({ kind: 'instant', value });
+export const LArray = (items) => ({ kind: 'array', items });
+export const LMapping = (entries = new Map()) => ({ kind: 'mapping', entries });
+/**
+ * References §6.2 node-count definition: `nodeCount(scalar) = 1`,
+ * `nodeCount(collection) = 1 + sum(nodeCount(child))` — mapping keys do not
+ * count as separate nodes.
+ */
+export const countNodes = (v) => {
+    if (v.kind === 'array')
+        return 1 + v.items.reduce((sum, item) => sum + countNodes(item), 0);
+    if (v.kind === 'mapping') {
+        let sum = 1;
+        for (const child of v.entries.values())
+            sum += countNodes(child);
+        return sum;
+    }
+    return 1;
+};
+/**
+ * Canonical string representation for interpolation (References §3.5.1).
+ * `Number.prototype.toString` already picks the correct fixed-vs-exponential
+ * form and digit sequence (ECMAScript is the normative algorithm for both
+ * the int and the float rule, within Lima's supported ranges) — this only
+ * applies the lexical cleanup the spec requires on top: lowercase `e`, no
+ * `+` after `e`, no leading zeros in the exponent.
+ */
+export const canonicalString = (v) => {
+    switch (v.kind) {
+        case 'null': return '';
+        case 'bool': return v.value ? 'true' : 'false';
+        case 'instant': return v.value.toISOString().replace(/\.\d{3}Z$/, 'Z');
+        case 'string': return v.value;
+        case 'int':
+        case 'float': {
+            const s = String(v.value);
+            return s.includes('e') || s.includes('E')
+                ? s.replace(/[eE]\+?(-?)0*(\d+)/, 'e$1$2')
+                : s;
+        }
+        default: return '';
+    }
+};
+// ─── Partial ingestion: host JS values → LimaValue ────────────────────────
+/** References §6.2 partial resource limits. */
+export const PARTIAL_KEY_LENGTH_LIMIT = 128;
+export const PARTIAL_VALUE_DEPTH_LIMIT = 16;
+export const PARTIAL_COUNT_LIMIT = 128;
+export const PARTIAL_NAME_LENGTH_LIMIT = 128;
+export const PARTIAL_NODE_LIMIT = 4096;
+export const RESULT_NODE_LIMIT = 65536;
+export const SCALAR_LENGTH_LIMIT = 16384;
+/**
+ * Counts Unicode code points (what every length-limit check in this
+ * codebase means by "code points", never UTF-16 code units) without
+ * `[...s].length`'s unconditional cost: spreading a string allocates an
+ * array of every character just to read its length, ~15x slower than
+ * `.length` for a typical short ASCII/BMP string (measured). A surrogate
+ * pair (the only case where `.length` and code-point count differ) can
+ * only occur for code points above U+FFFF — astral-plane characters like
+ * emoji, vanishingly rare in real frontmatter — so scanning for one first
+ * and falling back to the exact spread-based count only then keeps the
+ * common case (ASCII titles, but also accented Latin/Cyrillic/CJK BMP
+ * text, none of which need surrogate pairs) on the fast, allocation-free
+ * path.
+ */
+export const codepointLength = (s) => {
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        if (c >= 0xd800 && c <= 0xdfff)
+            return [...s].length;
+    }
+    return s.length;
+};
+/**
+ * Converts and validates a single host value against the Lima Value Model
+ * (References §6.2), recursively. `seen` tracks the current recursion path
+ * (not every visited object) to detect genuine cycles without rejecting
+ * shared, non-cyclic substructure.
+ *
+ * Host types with no Lima equivalent (functions, symbols, class instances,
+ * accessor properties) are rejected outright rather than silently coerced.
+ * Negative zero is normalised to positive zero; Date milliseconds are
+ * truncated (not rounded) to zero — both per References §6.2.
+ *
+ * This is the ONLY boundary in the whole implementation that touches JS
+ * host-value reflection (`Object.getPrototypeOf`, `getOwnPropertyDescriptor`)
+ * — a Rust port has no equivalent step at all, since its partials API takes
+ * a native Rust type up front.
+ */
+export const ingestPartialValue = (value, partialName, path, depth = 0, seen = new Set()) => {
+    const invalid = (reason) => {
+        throw new LimaError({
+            code: 'INVALID_PARTIAL', partial: partialName, path,
+            message: `LIMA: invalid partial "${partialName}" at path "${path}": ${reason}`,
+        });
+    };
+    if (value === null)
+        return LNull;
+    if (typeof value === 'boolean')
+        return LBool(value);
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            invalid('non-finite number');
+        return LFloat(value);
+    }
+    if (typeof value === 'string') {
+        if (codepointLength(value) > SCALAR_LENGTH_LIMIT) {
+            invalid(`string exceeds maximum length of ${SCALAR_LENGTH_LIMIT} code points`);
+        }
+        return LString(value);
+    }
+    if (value instanceof Date) {
+        if (isNaN(value.getTime()))
+            invalid('invalid date');
+        const year = value.getUTCFullYear();
+        if (year < 1 || year > 9999)
+            invalid(`date year ${year} outside the range 0001-9999`);
+        return LInstant(new Date(Math.floor(value.getTime() / 1000) * 1000));
+    }
+    if (value === undefined || typeof value !== 'object') {
+        invalid('unsupported value type'); // undefined, function, symbol, bigint, ...
+    }
+    if (seen.has(value))
+        invalid('cyclic reference');
+    if (depth >= PARTIAL_VALUE_DEPTH_LIMIT) {
+        invalid(`nesting depth exceeds maximum of ${PARTIAL_VALUE_DEPTH_LIMIT}`);
+    }
+    seen.add(value);
+    let result;
+    if (Array.isArray(value)) {
+        result = LArray(value.map((item, i) => {
+            if (Array.isArray(item)) {
+                throw new LimaError({
+                    code: 'INVALID_PARTIAL', partial: partialName, path: `${path}[${i}]`,
+                    message: `LIMA: invalid partial "${partialName}" at path "${path}[${i}]": nested arrays are not supported`,
+                });
+            }
+            return ingestPartialValue(item, partialName, `${path}[${i}]`, depth + 1, seen);
+        }));
+    }
+    else {
+        // Plain-object check: `Object.keys()` alone can't distinguish a class
+        // instance's own data properties from a genuine plain mapping — a
+        // prototype check can. `Object.create(null)` (proto === null) is also
+        // accepted.
+        const proto = Object.getPrototypeOf(value);
+        if (proto !== null && proto !== Object.prototype)
+            invalid('unsupported value type');
+        const entries = new Map();
+        for (const key of Object.keys(value)) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (!descriptor || !('value' in descriptor)) {
+                throw new LimaError({
+                    code: 'INVALID_PARTIAL', partial: partialName, path: `${path}.${key}`,
+                    message: `LIMA: invalid partial "${partialName}" at path "${path}.${key}": accessor properties are not supported`,
+                });
+            }
+            if (codepointLength(key) > PARTIAL_KEY_LENGTH_LIMIT) {
+                throw new LimaError({
+                    code: 'INVALID_PARTIAL', partial: partialName, path: `${path}.${key}`,
+                    message: `LIMA: invalid partial "${partialName}" at path "${path}.${key}": key exceeds maximum length of ${PARTIAL_KEY_LENGTH_LIMIT} code points`,
+                });
+            }
+            entries.set(key, ingestPartialValue(value[key], partialName, `${path}.${key}`, depth + 1, seen));
+        }
+        result = LMapping(entries);
+    }
+    seen.delete(value);
+    return result;
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@limaformat/lima",
+  "version": "0.1.0",
+  "description": "Lima frontmatter parser — LIMA Is Metadata Annotation",
+  "keywords": ["frontmatter", "parser", "yaml", "markdown", "metadata"],
+  "homepage": "https://limaformat.dev",
+  "author": "Michael Kortstiege",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/limaformat/lima",
+    "directory": "js"
+  },
+  "bugs": "https://github.com/limaformat/lima/issues",
+  "license": "ISC",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE", "CHANGELOG.md"],
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "pretest": "bun run build",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run typecheck && bun test",
+    "bench": "bun run bench/index.ts",
+    "bench:vs-yaml": "bun run bench/vs-yaml.ts",
+    "bench:vs-yaml:node": "node bench/vs-yaml-node.mjs",
+    "bench:differential": "bun run bench/differential.ts"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "@types/js-yaml": "^4.0.9",
+    "js-yaml": "^5.2.3",
+    "typescript": "^7.0.2"
+  }
+}