@limaformat/lima 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -12,6 +12,48 @@ are both frozen regardless of what this file shows.
 
 ## [Unreleased]
 
+## [0.5.1] — 2026-10-28
+
+Core errata `1.0.10`: aligned top-level values are trimmed, as Core 1.0
+always required.
+
+### Fixed
+
+- A top-level inline value kept every space after `: ` but the first:
+  `title:   Hello` read `'  Hello'`, and `n:    42` the string `'   42'`
+  instead of the integer 42 — against §4 step 3 and the §4 and §5.1
+  examples. Nested keys were not affected. The top-level entry now skips the
+  whitespace after the separator before reading the value, as the block
+  mapping does; the References 2.0 columns it reports were already physical
+  and are unchanged.
+
+The shared conformance corpus grows to 218 Core cases (7 new, `since:
+"1.0.10"`); TypeScript, Rust, and Go pass all of them.
+
+A unit test in `src/block.test.ts` had asserted the defect (`key:  value`
+→ `' value'`); it now asserts the specified `'value'`.
+
+## [0.5.0] — 2026-09-09
+
+Scope cleanup. The frozen **References 1.0** resolver is no longer bundled in
+the published package — it was never a public entry point (`parseReferences`
+and `parse` are References 2.0) and only existed to run the frozen 1.0
+conformance corpus, which now does so against the repository source. The
+1.0 specification and its 101-case corpus stay in the repository as a
+frozen regression target.
+
+No changes to Core 1.0 or References 2.0 syntax, semantics, or public API.
+The version advances to `0.5.0` in step with the Rust crate and Go module.
+
+### Changed
+
+- The published tarball drops from ~59.3 KB to ~53.4 KB — the internal
+  References 1.0 resolver (`references.ts`) is excluded from the build.
+- Documentation de-emphasises References 1.0 throughout: it is presented as
+  a briefly-published, immediately-superseded early version, not a current
+  target. The "Migrating References 1.0 to 2.0" guide is removed (see git
+  history if you need it).
+
 ## [0.4.0] — 2026-09-08
 
 First independent whole-repo review of Lima, then a second review of the

package/dist/block.js

@@ -9,7 +9,7 @@
  * never resolves a reference in the first place).
  */
 import { checkKeyLength, checkDuplicateKey, NESTING_DEPTH_LIMIT } from './normalize.js';
-import { stripKeyQuotes, stripComment, stripCommentKeepEscapes, parseQuotedOrTyped, closingQuoteIndex, isValidKey, positionedBuilder, } from './scalars.js';
+import { stripKeyQuotes, stripComment, stripCommentKeepEscapes, parseQuotedOrTyped, closingQuoteIndex, isValidKey, } from './scalars.js';
 import { parseFlowMapping, parseFlowOrScalarValue } from './flow.js';
 import { buildBlockScalar } from './block-scalar.js';
 import { LimaError } from './errors.js';
@@ -49,7 +49,7 @@ const inlineSource = (wantSource, ctx, keyLine, valueCol, rawUndecoded) => wantS
     tabAdjust: ctx.tabAdjust ? [ctx.tabAdjust[keyLine - 1] ?? 0] : undefined,
 }) : undefined;
 const inlineOrBlockScalar = (raw, keyIndent, keyLine, valueCol, rawUndecoded, cursor, ctx, builder) => {
-    const wantSource = builder === positionedBuilder;
+    const wantSource = builder.positions === true;
     if (raw !== '|') {
         const value = parseFlowOrScalarValue(raw, ctx, keyLine, builder, inlineSource(wantSource, ctx, keyLine, valueCol, rawUndecoded));
         cursor.next();
@@ -129,7 +129,7 @@ const cursorAfterDash = (cursor) => {
 };
 /** Shared block grammar consuming one mutable physical-line cursor. */
 const parseCursorBlock = (cursor, baseIndent, ctx, baseLine, builder) => {
-    const wantSource = builder === positionedBuilder;
+    const wantSource = builder.positions === true;
     let items = null;
     let entries = null;
     let pendingItem = null;

package/dist/builder.d.ts

@@ -26,6 +26,8 @@
  */
 import type { ReferenceSource } from './reference-tokens2.js';
 export interface ValueBuilder<V, M = Map<string, V>> {
+    /** Whether scalar builders need physical source anchors for editor positions. */
+    readonly positions?: boolean;
     null(line: number): V;
     bool(value: boolean, line: number): V;
     int(value: number, line: number): V;

package/dist/core.d.ts

@@ -22,6 +22,7 @@ import { type LimaValue } from './value.js';
 import { type ParseContext, type Diagnostic } from './normalize.js';
 import { type PositionedValue } from './scalars.js';
 import type { ValueBuilder } from './builder.js';
+import type { ReferenceToken2 } from './reference-tokens2.js';
 export type { Diagnostic, ParseContext } from './normalize.js';
 export { NESTING_DEPTH_LIMIT, SCALAR_LENGTH_LIMIT } from './normalize.js';
 export type { PositionedValue, InsertedAt } from './scalars.js';
@@ -40,6 +41,16 @@ export type CoreOptions = {
  * primitive the References layer (`references.ts`) builds on.
  */
 export declare const parseCoreWithPositions: (frontMatter: string, ctx: ParseContext) => Map<string, PositionedValue>;
+export type PositionedReferenceParse = {
+    document: Map<string, PositionedValue>;
+    references: ReferenceToken2[];
+};
+/**
+ * Position-aware Core parse plus every active References 2.0 token seen while
+ * values are built. Recording at construction time preserves tokens from
+ * earlier duplicate-key values even though the result map is last-value-wins.
+ */
+export declare const parseCoreWithPositionedReferences: (frontMatter: string, ctx: ParseContext) => PositionedReferenceParse;
 /** The public result shape (Core §11.1): every value `toNative*` can produce. */
 export type NativeValue = null | boolean | number | string | Date | NativeValue[] | {
     [key: string]: NativeValue;

package/dist/core.js

@@ -20,6 +20,7 @@
  */
 import { checkKeyLength, byteLength, DOCUMENT_SIZE_LIMIT, TOP_LEVEL_KEY_LIMIT, NESTING_DEPTH_LIMIT, } from './normalize.js';
 import { unescapeDQ, stripComment, stripCommentKeepEscapes, positionedBuilder, NO_SPAN_VALUE, parseSimpleScalarSpan, } from './scalars.js';
+import { isTrimWhitespace } from './chars.js';
 import { parseFlowOrScalarValue } from './flow.js';
 import { parseBlockRange } from './block.js';
 import { buildBlockScalar } from './block-scalar.js';
@@ -156,8 +157,21 @@ const parseCoreGeneric = (frontMatter, ctx, builder, computeDepth) => {
             searchFrom = lineEnd + 1;
         }
     }
-    const parseEntry = (key, line, rawStart, isBlock, inlineEnd, nextStart) => {
+    const parseEntry = (key, line, separatorEnd, isBlock, inlineEnd, nextStart) => {
         checkKeyLength(key, line);
+        // §4 step 3: an inline value begins after the spaces that follow `: `, however many there are — as in a
+        // block mapping (block.ts trimSlice), so that the scalar paths below and the source column see the value
+        // itself. The newline that ends the line is not skipped.
+        let rawStart = separatorEnd;
+        if (!isBlock) {
+            while (rawStart < nextStart) {
+                const c = frontMatter.charCodeAt(rawStart);
+                // printable ASCII other than SPACE is never whitespace: the common case ends here at once
+                if ((c > 0x20 && c < 0x7f) || c === 10 || !isTrimWhitespace(c))
+                    break;
+                rawStart++;
+            }
+        }
         if ((strict || ctx.onWarning !== undefined) && builder.hasMappingKey(root, key)) {
             const diagnostic = {
                 code: 'DUPLICATE_KEY', line, key,
@@ -176,7 +190,7 @@ const parseCoreGeneric = (frontMatter, ctx, builder, computeDepth) => {
         // source line — the anchor for References 2.0 token positions (§2.4).
         // References 2.0 token positions (§2.4): only build the source anchor
         // for the annotated builder; `parseCore` (native) discards it.
-        const wantSource = builder === positionedBuilder;
+        const wantSource = builder.positions === true;
         const valueLineStart = wantSource ? frontMatter.lastIndexOf('\n', rawStart - 1) + 1 : 0;
         const valueCol = wantSource ? [...frontMatter.slice(valueLineStart, rawStart)].length : 0;
         const lineTabAdjust = wantSource && ctx.tabAdjust ? [ctx.tabAdjust[line - 1] ?? 0] : undefined;
@@ -315,6 +329,28 @@ const parseCoreGeneric = (frontMatter, ctx, builder, computeDepth) => {
  * primitive the References layer (`references.ts`) builds on.
  */
 export const parseCoreWithPositions = (frontMatter, ctx) => parseCoreGeneric(frontMatter, ctx, positionedBuilder, depthOfPositioned);
+/**
+ * Position-aware Core parse plus every active References 2.0 token seen while
+ * values are built. Recording at construction time preserves tokens from
+ * earlier duplicate-key values even though the result map is last-value-wins.
+ */
+export const parseCoreWithPositionedReferences = (frontMatter, ctx) => {
+    const references = [];
+    const recordingBuilder = {
+        ...positionedBuilder,
+        string: (value, line, quoted, source) => {
+            const positioned = positionedBuilder.string(value, line, quoted, source);
+            if (positioned.kind === 'string' && positioned.references2) {
+                references.push(...positioned.references2);
+            }
+            return positioned;
+        },
+    };
+    return {
+        document: parseCoreGeneric(frontMatter, ctx, recordingBuilder, depthOfPositioned),
+        references,
+    };
+};
 /**
  * The `ValueBuilder<NativeValue>` — `parseCore`'s fast path. Every scalar
  * builder is the identity function: unlike `positionedBuilder`, there is no

package/dist/reference-tokens2.d.ts

@@ -39,5 +39,13 @@ export type ReferenceSource = {
     col: number;
     tabAdjust?: number[];
 };
+export declare const SEGMENT = "[a-zA-Z0-9_][a-zA-Z0-9_:-]*";
+export declare const DOC_PATH = "[a-zA-Z0-9_][a-zA-Z0-9_:-]*(?:\\.[a-zA-Z0-9_][a-zA-Z0-9_:-]*)*";
+export declare const PARTIAL_NAME = "[a-zA-Z0-9_][a-zA-Z0-9_:/-]*";
+export declare const PARTIAL_PATH = "[a-zA-Z0-9_][a-zA-Z0-9_:/-]*(?:\\.[a-zA-Z0-9_][a-zA-Z0-9_:-]*)*";
 export declare const PURE_REFERENCE_2: RegExp;
+/** Converts a 0-based codepoint offset to JavaScript/LSP UTF-16 units. */
+export declare const codepointOffsetToUtf16: (text: string, codepointOffset: number) => number;
+/** Converts a 0-based JavaScript/LSP UTF-16 offset to a codepoint offset. */
+export declare const utf16OffsetToCodepoint: (text: string, utf16Offset: number) => number;
 export declare const scanReferenceTokens2: (value: string, source: ReferenceSource | undefined) => ReferenceToken2[];

package/dist/reference-tokens2.js

@@ -1,20 +1,42 @@
 /** Reference tokens recorded while the annotated Core tree is being built. */
-const SEGMENT = '[a-zA-Z0-9_][a-zA-Z0-9_:-]*';
-const DOC_PATH = `${SEGMENT}(?:\\.${SEGMENT})*`;
-const PARTIAL_NAME = '[a-zA-Z0-9_][a-zA-Z0-9_:/-]*';
-const PARTIAL_PATH = `${PARTIAL_NAME}(?:\\.${SEGMENT})*`;
+export const SEGMENT = '[a-zA-Z0-9_][a-zA-Z0-9_:-]*';
+export const DOC_PATH = `${SEGMENT}(?:\\.${SEGMENT})*`;
+export const PARTIAL_NAME = '[a-zA-Z0-9_][a-zA-Z0-9_:/-]*';
+export const PARTIAL_PATH = `${PARTIAL_NAME}(?:\\.${SEGMENT})*`;
 export const PURE_REFERENCE_2 = new RegExp(`^(?:\\$\\{(${DOC_PATH})\\}|\\$\\((${PARTIAL_PATH})\\))$`);
 const REFERENCE_2 = new RegExp(`\\$\\{(${DOC_PATH})\\}|\\$\\((${PARTIAL_PATH})\\)`, 'g');
 const NO_TOKENS = [];
+const utf16WidthAt = (text, offset) => text.codePointAt(offset) > 0xffff ? 2 : 1;
 /** Codepoint length of the UTF-16 slice `[a, b)` of `s`. */
 const codepointLen = (s, a, b) => {
     let n = 0;
     for (let i = a; i < b;) {
-        i += s.codePointAt(i) > 0xffff ? 2 : 1;
+        i += utf16WidthAt(s, i);
         n++;
     }
     return n;
 };
+/** Converts a 0-based codepoint offset to JavaScript/LSP UTF-16 units. */
+export const codepointOffsetToUtf16 = (text, codepointOffset) => {
+    let utf16Offset = 0;
+    let codepoints = 0;
+    while (utf16Offset < text.length && codepoints < codepointOffset) {
+        utf16Offset += utf16WidthAt(text, utf16Offset);
+        codepoints++;
+    }
+    return utf16Offset;
+};
+/** Converts a 0-based JavaScript/LSP UTF-16 offset to a codepoint offset. */
+export const utf16OffsetToCodepoint = (text, utf16Offset) => {
+    let currentUtf16 = 0;
+    let codepoints = 0;
+    const limit = Math.min(Math.max(utf16Offset, 0), text.length);
+    while (currentUtf16 < limit) {
+        currentUtf16 += utf16WidthAt(text, currentUtf16);
+        codepoints++;
+    }
+    return codepoints;
+};
 /** Splice points (decoded value order): token text, UTF-16 index, path. */
 const scanDecoded = (value) => {
     REFERENCE_2.lastIndex = 0;

package/dist/references2.d.ts

@@ -1,5 +1,19 @@
-import { type Diagnostic } from './core.js';
+import { type Diagnostic, type PositionedReferenceParse, type PositionedValue } from './core.js';
 type Meta = Record<string, unknown>;
+/**
+ * Resolve one document-reference path with the same traversal, cycle checks,
+ * and edge budget used by the public References 2.0 parser. The returned
+ * positioned value retains the definition site's source line.
+ */
+export type DocumentReferenceTargetResolution = {
+    status: 'resolved';
+    target: PositionedValue;
+} | {
+    status: 'unverifiable-partials';
+} | {
+    status: 'unresolved';
+};
+export declare const resolveDocumentReferenceTarget: (parsed: PositionedReferenceParse, path: string) => DocumentReferenceTargetResolution;
 export type ParseMode = 'references' | 'core';
 export type ParseOptions = {
     mode?: ParseMode;

package/dist/references2.js

@@ -7,6 +7,10 @@ import { collectAllParticipants, deepCopyPositioned, earliestParticipant, emptyM
 const PARTIAL_NAME = '[a-zA-Z0-9_][a-zA-Z0-9_:/-]*';
 const PARTIAL_NAME_RE = new RegExp(`^${PARTIAL_NAME}$`);
 const MAX_EDGES = 3;
+// Looking up the root path is itself the first reference edge; recursion into
+// that root therefore gets the public resolver's remaining two-edge budget.
+const TARGET_EDGE_BUDGET = MAX_EDGES - 1;
+const referenceResourceStatuses = new WeakMap();
 /** Copies a pure-reference target and stamps the new insertion without
  * discarding provenance already attached to the copied root (R-112). */
 const copyWithInsertion = (target, insertedAt) => {
@@ -44,6 +48,91 @@ const documentTarget = (root, path) => {
     }
     return { root: value, tail: segments.slice(index) };
 };
+export const resolveDocumentReferenceTarget = (parsed, path) => {
+    const { document } = parsed;
+    const target = documentTarget(document, path);
+    if (target === undefined)
+        return { status: 'unresolved' };
+    const resourceStatus = documentReferenceResourceStatus(parsed);
+    if (resourceStatus === 'unverifiable-partials')
+        return { status: resourceStatus };
+    if (resourceStatus === 'invalid')
+        return { status: 'unresolved' };
+    const ctx = { diagnostics: [], cache: new WeakMap() };
+    const stack = new Set([target.root]);
+    const resolved = resolveNode(target.root, document, new Map(), ctx, TARGET_EDGE_BUDGET, stack);
+    if (!resolved.complete || ctx.diagnostics.length > 0)
+        return { status: 'unresolved' };
+    const selected = lookupPath(resolved.value, target.tail);
+    return selected === undefined
+        ? { status: 'unresolved' }
+        : { status: 'resolved', target: selected };
+};
+const resolveDocument = (document, partials, ctx) => {
+    const resolved = new Map();
+    for (const [key, value] of document) {
+        const stack = new Set([value]);
+        resolved.set(key, resolveNode(value, document, partials, ctx, MAX_EDGES, stack).value);
+    }
+    return resolved;
+};
+const assertResolvedDocumentResourceLimits = (resolved) => {
+    const finalized = [...resolved].map(([key, value]) => [key, finalizePositioned(value)]);
+    const depth = finalized.length === 0 ? 0 : Math.max(...finalized.map(([, value]) => value.depth));
+    if (depth > NESTING_DEPTH_LIMIT) {
+        const participants = finalized
+            .filter(([, value]) => value.depth === depth)
+            .flatMap(([, value]) => value.deepestParticipants);
+        const winner = earliestParticipant(participants);
+        throw new LimaError({
+            code: 'RESOURCE_LIMIT', line: winner?.line ?? 1, token: winner?.token,
+            ...(winner?.offset !== undefined ? { column: winner.offset + 1 } : {}),
+            message: `Lima: nesting depth exceeds maximum of ${NESTING_DEPTH_LIMIT} at line ${winner?.line ?? 1}`,
+        });
+    }
+    let nodeCount = 1;
+    for (const [, value] of finalized)
+        nodeCount += value.nodeCount;
+    if (nodeCount > RESULT_NODE_LIMIT) {
+        const participants = [];
+        for (const value of resolved.values())
+            collectAllParticipants(value, participants);
+        const winner = earliestParticipant(participants);
+        throw new LimaError({
+            code: 'RESOURCE_LIMIT', line: winner?.line ?? 1, token: winner?.token,
+            ...(winner?.offset !== undefined ? { column: winner.offset + 1 } : {}),
+            message: `Lima: result exceeds maximum size of ${RESULT_NODE_LIMIT} total nodes at line ${winner?.line ?? 1}`,
+        });
+    }
+    return finalized;
+};
+const documentReferenceResourceStatus = (parsed) => {
+    // Partial values are supplied by caller code and can change whole-document
+    // depth/node limits. With no file convention for them, editor tooling cannot
+    // prove that even an unrelated document reference is safe to resolve.
+    if (parsed.references.some((reference) => reference.partialPath !== undefined))
+        return 'unverifiable-partials';
+    const { document } = parsed;
+    const cached = referenceResourceStatuses.get(document);
+    if (cached !== undefined)
+        return cached;
+    const ctx = { diagnostics: [], cache: new WeakMap() };
+    const resolved = resolveDocument(document, new Map(), ctx);
+    let valid = !ctx.diagnostics.some((diagnostic) => diagnostic.code === 'RESOURCE_LIMIT');
+    if (valid) {
+        try {
+            assertResolvedDocumentResourceLimits(resolved);
+        }
+        catch (error) {
+            if (!(error instanceof LimaError) || error.code !== 'RESOURCE_LIMIT')
+                throw error;
+            valid = false;
+        }
+    }
+    const status = valid ? 'valid' : 'invalid';
+    referenceResourceStatuses.set(document, status);
+    return status;
+};
 const lookupPartial = (partials, path) => {
     const dot = path.indexOf('.');
     if (dot < 0)
@@ -284,11 +373,7 @@ const parseInternal = (frontMatter, options, useResolveCache) => {
     }
     const document = parseCoreWithPositions(frontMatter, { strict: options?.strict ?? false, onWarning: options?.onWarning });
     const ctx = { diagnostics: [], ...(useResolveCache ? { cache: new WeakMap() } : {}) };
-    const resolved = new Map();
-    for (const [key, value] of document) {
-        const stack = new Set([value]);
-        resolved.set(key, resolveNode(value, document, partials, ctx, MAX_EDGES, stack).value);
-    }
+    const resolved = resolveDocument(document, partials, ctx);
     if (options?.strict)
         for (const value of resolved.values())
             scanUnresolved(value, ctx);
@@ -299,31 +384,7 @@ const parseInternal = (frontMatter, options, useResolveCache) => {
         // already do; `offset` was internal-only here.
         throw new LimaError({ ...winner, column: winner.offset + 1 });
     }
-    const finalized = [...resolved].map(([key, value]) => [key, finalizePositioned(value)]);
-    const depth = finalized.length === 0 ? 0 : Math.max(...finalized.map(([, value]) => value.depth));
-    if (depth > NESTING_DEPTH_LIMIT) {
-        const participants = finalized.filter(([, value]) => value.depth === depth).flatMap(([, value]) => value.deepestParticipants);
-        const winner = earliestParticipant(participants);
-        throw new LimaError({
-            code: 'RESOURCE_LIMIT', line: winner?.line ?? 1, token: winner?.token,
-            ...(winner?.offset !== undefined ? { column: winner.offset + 1 } : {}),
-            message: `Lima: nesting depth exceeds maximum of ${NESTING_DEPTH_LIMIT} at line ${winner?.line ?? 1}`,
-        });
-    }
-    let nodeCount = 1;
-    for (const [, value] of finalized)
-        nodeCount += value.nodeCount;
-    if (nodeCount > RESULT_NODE_LIMIT) {
-        const participants = [];
-        for (const value of resolved.values())
-            collectAllParticipants(value, participants);
-        const winner = earliestParticipant(participants);
-        throw new LimaError({
-            code: 'RESOURCE_LIMIT', line: winner?.line ?? 1, token: winner?.token,
-            ...(winner?.offset !== undefined ? { column: winner.offset + 1 } : {}),
-            message: `Lima: result exceeds maximum size of ${RESULT_NODE_LIMIT} total nodes at line ${winner?.line ?? 1}`,
-        });
-    }
+    const finalized = assertResolvedDocumentResourceLimits(resolved);
     const out = emptyMapping();
     for (const [key, value] of finalized)
         out[key] = value.native;

package/dist/scalars.js

@@ -13,6 +13,7 @@ export const hasActiveReferences2 = (value) => value.kind === 'string' ? (value.
         : false;
 /** The `ValueBuilder<PositionedValue>` — reconstructs today's annotated tree exactly, for References. */
 export const positionedBuilder = {
+    positions: true,
     null: (line) => ({ kind: 'null', line }),
     bool: (value, line) => ({ kind: 'bool', value, line }),
     int: (value, line) => ({ kind: 'int', value, line }),

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@limaformat/lima",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "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",
+    "url": "git+https://github.com/limaformat/lima.git",
     "directory": "js"
   },
   "bugs": "https://github.com/limaformat/lima/issues",
@@ -23,8 +23,10 @@
   "engines": { "node": ">=18" },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
+    "prepack": "bun run build",
     "pretest": "bun run build",
     "test": "bun test",
+    "pretypecheck": "bun run build",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "bun run typecheck && bun test",
     "bench": "bun run bench/index.ts",

package/dist/references.d.ts

@@ -1,38 +0,0 @@
-/**
- * Lima References 1.0 — layered strictly on top of `core.ts` (Appendix B:
- * reference resolution is exclusively this extension's concern; Core never
- * sees it). Reads the annotated `PositionedValue` tree Core produces and
- * performs the two-phase resolution the spec describes (§4), keeping every
- * intermediate result in the SAME annotated representation instead of a
- * separate raw-value tree with a bolted-on marker for "inert":
- *
- *   - A string's `quoted` flag (set once, by Core, from actual quote syntax)
- *     is the single source of truth for "never treat this as a reference
- *     site" — §2.3 (quoted tokens) and §3.8 (partial content) are the same
- *     rule applied to two different origins, so partial values are wrapped
- *     into this same representation with every string leaf pre-marked
- *     `quoted: true` before insertion (`partialToPositioned`), rather than
- *     needing a second, unrelated mechanism.
- *   - Every node keeps the source `line` it was parsed with, even after
- *     being deep-copied into a new position — diagnostics read it directly
- *     off the node instead of falling back to a coarser key-level lookup.
- *
- * There is no module-level mutable state: diagnostics are collected in a
- * `ResolutionContext` created fresh per call and threaded explicitly.
- */
-import { type Diagnostic } from './core.js';
-type Meta = Record<string, unknown>;
-export type ReferencesOptions = {
-    /** Named values available via `(%key)` references. */
-    partials?: Meta;
-    strict?: boolean;
-    /** Core §11.2 (inherited): callback for non-strict warnings (e.g. duplicate keys). Discarded if omitted. */
-    onWarning?: (diagnostic: Diagnostic) => void;
-};
-export declare const parseReferences: <T extends Record<string, unknown> = Meta>(frontMatter: string, options?: ReferencesOptions) => T;
-/** Backward-compatible primary entry point — References layered on Core. */
-export declare const parse: typeof parseReferences;
-export type ParseOptions = ReferencesOptions;
-/** Internal conformance entry point for the frozen References 1.0 suite. */
-export declare const parseReferencesV1: typeof parseReferences;
-export {};

package/dist/references.js

@@ -1,413 +0,0 @@
-/**
- * Lima References 1.0 — layered strictly on top of `core.ts` (Appendix B:
- * reference resolution is exclusively this extension's concern; Core never
- * sees it). Reads the annotated `PositionedValue` tree Core produces and
- * performs the two-phase resolution the spec describes (§4), keeping every
- * intermediate result in the SAME annotated representation instead of a
- * separate raw-value tree with a bolted-on marker for "inert":
- *
- *   - A string's `quoted` flag (set once, by Core, from actual quote syntax)
- *     is the single source of truth for "never treat this as a reference
- *     site" — §2.3 (quoted tokens) and §3.8 (partial content) are the same
- *     rule applied to two different origins, so partial values are wrapped
- *     into this same representation with every string leaf pre-marked
- *     `quoted: true` before insertion (`partialToPositioned`), rather than
- *     needing a second, unrelated mechanism.
- *   - Every node keeps the source `line` it was parsed with, even after
- *     being deep-copied into a new position — diagnostics read it directly
- *     off the node instead of falling back to a coarser key-level lookup.
- *
- * There is no module-level mutable state: diagnostics are collected in a
- * `ResolutionContext` created fresh per call and threaded explicitly.
- */
-import { countNodes, canonicalString, codepointLength, ingestPartialValue, PARTIAL_COUNT_LIMIT, PARTIAL_NAME_LENGTH_LIMIT, PARTIAL_NODE_LIMIT, RESULT_NODE_LIMIT, SCALAR_LENGTH_LIMIT, } from './value.js';
-import { parseCoreWithPositions, toPlainValue, NESTING_DEPTH_LIMIT, } from './core.js';
-import { LimaError } from './errors.js';
-import { collectAllParticipants, deepCopyPositioned, earliestParticipant, emptyMapping, finalizePositioned, partialToPositioned, } from './positioned-tree.js';
-// References §2.1/§2.2/Appendix B grammar, per sigil.
-const DOC_SEGMENT = '[a-zA-Z0-9_][a-zA-Z0-9_:-]*';
-const DOC_PATH = `${DOC_SEGMENT}(?:\\.${DOC_SEGMENT})*`;
-const PARTIAL_KEY = '[a-zA-Z0-9_][a-zA-Z0-9_:/-]*';
-const PURE_REF_RE = new RegExp(`^\\((?:\\$(${DOC_PATH})|%(${PARTIAL_KEY}))\\)$`);
-const INTERP_RE = new RegExp(`\\((?:\\$(${DOC_PATH})|%(${PARTIAL_KEY}))\\)`, 'g');
-/**
- * §5: of every reference-resolution error encountered during a single
- * resolveTree pass, only the one at the lowest source line is ultimately
- * thrown. Tracking a running minimum instead of collecting every diagnostic
- * into an array and sorting it at the end avoids an O(e log e) sort (and
- * its allocations) for documents with many reference errors — `<` (not
- * `<=`) preserves the original stable-sort-then-take-first tie-break: the
- * first diagnostic reported at any given minimum line keeps winning over a
- * later one at the same line, exactly as it did when every one of them was
- * pushed into an array and stably sorted by line.
- */
-const reportDiagnostic = (ctx, d) => {
-    if (ctx.best === null || d.line < ctx.best.line)
-        ctx.best = d;
-};
-// ─── PositionedValue-level helpers ─────────────────────────────────────────
-const getNestedValueP = (root, path) => {
-    if (!path.includes('.'))
-        return root.get(path);
-    const parts = path.split('.');
-    let cur = root.get(parts[0]);
-    for (let i = 1; i < parts.length; i++) {
-        if (cur === undefined || cur.kind !== 'mapping')
-            return undefined;
-        cur = cur.entries.get(parts[i]);
-    }
-    return cur;
-};
-/**
- * `resolveTree` re-checks reference-freedom repeatedly on the SAME target
- * subtree — once per reference pointing at it (the fast-path guard at the
- * top of `resolveTree`, once more before copying a pure-reference target,
- * once more per interpolation match) — so a document with many references
- * into one large shared mapping would otherwise re-traverse that whole
- * subtree for every single reference. `PositionedValue` nodes are only ever
- * produced fresh (by Core, or by `deepCopyPositioned` below) and never
- * mutated in place, so object identity is a stable cache key for the
- * lifetime of a single `parseReferences` call — a module-level `WeakMap`
- * is safe (and self-cleaning: entries vanish once a parse's tree is
- * garbage-collected) rather than needing a per-call cache threaded through
- * every function.
- */
-const referenceFreeCache = new WeakMap();
-/**
- * A reference is only resolved from a target that is itself reference-free
- * (§4). Quoted strings are always free (§2.3); partial-derived values are
- * always free too, but never reach this function — see `partialToPositioned`.
- */
-const isReferenceFreeP = (v) => {
-    if (v.kind !== 'string' && v.kind !== 'array' && v.kind !== 'mapping')
-        return true;
-    const cached = referenceFreeCache.get(v);
-    if (cached !== undefined)
-        return cached;
-    let result;
-    if (v.kind === 'string') {
-        result = v.quoted || (!v.value.includes('($') && !v.value.includes('(%'));
-    }
-    else if (v.kind === 'array') {
-        result = v.items.every(isReferenceFreeP);
-    }
-    else {
-        result = true;
-        for (const c of v.entries.values())
-            if (!isReferenceFreeP(c)) {
-                result = false;
-                break;
-            }
-    }
-    referenceFreeCache.set(v, result);
-    return result;
-};
-/**
- * Recursively resolves reference-shaped string leaves in `node` against
- * `lookup` — the single function both resolution phases share (§4.1's live
- * backward-reference pass and §4.2's snapshot-based forward pass differ
- * only in which `lookup` map and which source tree they're applied to, not
- * in the resolution logic itself). Errors are collected into `ctx`, never
- * thrown directly — see the module doc comment on error ordering.
- */
-const resolveTree = (node, lookup, partials, ctx) => {
-    // Fast path: a subtree with no active reference-shaped string anywhere
-    // inside it has nothing this function could change — skip rebuilding
-    // it. Matters most for phase 2's redundant re-walk (see the module doc
-    // comment) of a large already-resolved value, e.g. a big partial copied
-    // in by several separate references: without this, every element gets
-    // a fresh resolveTree call and every array/mapping level gets
-    // reconstructed via .map()/a new Map on a pass that can only ever
-    // return its input unchanged.
-    if (node.kind !== 'string' && isReferenceFreeP(node))
-        return node;
-    if (node.kind === 'string') {
-        if (node.quoted)
-            return node;
-        const val = node.value;
-        // Pure reference: entire value is exactly one ($path) or (%key).
-        if (val.charCodeAt(0) === 40 && val.charCodeAt(val.length - 1) === 41) {
-            const m = val.match(PURE_REF_RE);
-            if (m) {
-                const isPartial = m[2] !== undefined;
-                const key = (isPartial ? m[2] : m[1]);
-                // R-112: stamped on the copy's root only — descendants keep
-                // whatever insertedAt they already carried from an earlier,
-                // more deeply nested resolution (see deepCopyPositioned).
-                const insertedAt = { line: node.line, token: val };
-                if (isPartial) {
-                    const target = partials.get(key);
-                    // §3.1 deep-copy requirement: `target` is the SAME cached tree
-                    // built once per partial name at ingestion (see
-                    // `partialToPositioned`'s call site) — every pure reference to
-                    // this partial anywhere in the document retrieves that one
-                    // tree. A shallow spread of its root would leave descendants
-                    // (including a mutable `Date` in an `instant` node) aliased
-                    // across every such reference; deep-copying here, exactly like
-                    // the document-reference branch below, is what actually
-                    // satisfies the guarantee.
-                    if (target !== undefined)
-                        return { ...deepCopyPositioned(target), insertedAt };
-                }
-                else {
-                    const target = getNestedValueP(lookup, key);
-                    if (target !== undefined && isReferenceFreeP(target)) {
-                        return { ...deepCopyPositioned(target), insertedAt };
-                    }
-                }
-                // Unresolved (or target not yet reference-free) — leave unchanged.
-            }
-        }
-        // String interpolation: replace all ($path) / (%key) occurrences.
-        if (val.includes('($') || val.includes('(%')) {
-            const replaced = val.replace(INTERP_RE, (match, docPath, partialKey) => {
-                const isPartial = partialKey !== undefined;
-                const key = isPartial ? partialKey : docPath;
-                const target = isPartial ? partials.get(key) : getNestedValueP(lookup, key);
-                if (target === undefined || (!isPartial && !isReferenceFreeP(target)))
-                    return match;
-                if (target.kind === 'mapping') {
-                    reportDiagnostic(ctx, {
-                        code: 'INVALID_INTERPOLATION', line: node.line, token: match,
-                        message: `Lima: invalid interpolation of "${match}" at line ${node.line}: mapping cannot be interpolated into a string`,
-                    });
-                    return match;
-                }
-                if (target.kind === 'array') {
-                    if (target.items.some((item) => item.kind === 'array' || item.kind === 'mapping')) {
-                        reportDiagnostic(ctx, {
-                            code: 'INVALID_INTERPOLATION', line: node.line, token: match,
-                            message: `Lima: invalid interpolation of "${match}" at line ${node.line}: array contains a nested array or mapping`,
-                        });
-                        return match;
-                    }
-                    return target.items.map((item) => canonicalString(toPlainValue(item))).join(', ');
-                }
-                return canonicalString(toPlainValue(target));
-            });
-            // §6.2 final scalar-length limit: interpolation can grow a string
-            // past the limit even when neither the raw document text nor the
-            // interpolated target individually violated it — a hard error in
-            // both modes, thrown immediately like the other resource limits
-            // (never part of the ordered diagnostics set below).
-            if (codepointLength(replaced) > SCALAR_LENGTH_LIMIT) {
-                throw new LimaError({
-                    code: 'RESOURCE_LIMIT', line: node.line,
-                    message: `Lima: scalar exceeds maximum length of ${SCALAR_LENGTH_LIMIT} code points at line ${node.line}`,
-                });
-            }
-            return { kind: 'string', value: replaced, line: node.line, quoted: false };
-        }
-        return node;
-    }
-    if (node.kind === 'array') {
-        return {
-            kind: 'array',
-            line: node.line,
-            // Phase 2 redundantly re-walks values phase 1 already resolved
-            // (harmless — see the module doc comment) — including, sometimes,
-            // a node that phase 1 already stamped with insertedAt. Must be
-            // carried over here, not just at the point of insertion, or a
-            // reference's provenance silently disappears on the second pass.
-            insertedAt: node.insertedAt,
-            items: node.items.map((item) => {
-                const resolved = resolveTree(item, lookup, partials, ctx);
-                if (item.kind === 'string' && resolved.kind === 'array') {
-                    // References Appendix: array spreading was removed, and a
-                    // nested array produced by reference insertion violates
-                    // Core §7.2 (sequences contain scalars or mappings only) —
-                    // throws in BOTH modes (R-036/R-143).
-                    reportDiagnostic(ctx, {
-                        code: 'INVALID_REFERENCE_SHAPE', line: item.line, token: item.value,
-                        message: `Lima: reference "${item.value}" resolves to an array, which cannot be inserted as a sequence item at line ${item.line}`,
-                    });
-                    return item;
-                }
-                return resolved;
-            }),
-        };
-    }
-    if (node.kind === 'mapping') {
-        const entries = new Map();
-        for (const [k, c] of node.entries)
-            entries.set(k, resolveTree(c, lookup, partials, ctx));
-        return { kind: 'mapping', entries, line: node.line, insertedAt: node.insertedAt };
-    }
-    return node; // null/bool/int/float/instant — nothing to resolve
-};
-export const parseReferences = (frontMatter, options) => {
-    const strict = options?.strict ?? false;
-    const rawPartials = options?.partials ?? {};
-    // §6.2 / R-114: partials are validated and deep-copied before document
-    // parsing begins — this must run even for an empty document. Partial
-    // errors carry a value path, never a document line (parsing hasn't
-    // started), so they throw directly rather than joining the ordered
-    // diagnostics collected below.
-    const partialNames = Object.keys(rawPartials);
-    if (partialNames.length > PARTIAL_COUNT_LIMIT) {
-        throw new LimaError({ code: 'INVALID_PARTIAL', message: `Lima: too many partials (max ${PARTIAL_COUNT_LIMIT})` });
-    }
-    for (const name of partialNames) {
-        if (codepointLength(name) > PARTIAL_NAME_LENGTH_LIMIT) {
-            throw new LimaError({
-                code: 'INVALID_PARTIAL', partial: name, path: name,
-                message: `Lima: invalid partial "${name}" at path "${name}": name exceeds maximum length of ${PARTIAL_NAME_LENGTH_LIMIT} code points`,
-            });
-        }
-    }
-    const partials = new Map();
-    for (const [name, value] of Object.entries(rawPartials)) {
-        partials.set(name, ingestPartialValue(value, name, name));
-    }
-    let totalPartialNodes = 0;
-    for (const v of partials.values())
-        totalPartialNodes += countNodes(v);
-    if (totalPartialNodes > PARTIAL_NODE_LIMIT) {
-        throw new LimaError({
-            code: 'INVALID_PARTIAL',
-            message: `Lima: partials exceed the combined maximum of ${PARTIAL_NODE_LIMIT} value nodes`,
-        });
-    }
-    // Converted to the annotated representation once per partial, not once
-    // per reference: nothing downstream ever mutates a PositionedValue tree
-    // in place (resolveTree's fast path returns inert subtrees unchanged;
-    // toNativeFromPositioned always allocates fresh native containers for
-    // the public result), so every reference to the same partial can safely
-    // reuse the same body and only needs its own `insertedAt` stamped onto
-    // a shallow copy of the root — no per-reference deep copy required. The
-    // internal `line` on partial-derived nodes is never read downstream
-    // (every diagnostic that could involve one uses the referencing site's
-    // own line instead), so the placeholder `0` here is fine.
-    const partialsPositioned = new Map();
-    for (const [name, value] of partials)
-        partialsPositioned.set(name, partialToPositioned(value, 0));
-    const root = parseCoreWithPositions(frontMatter, { strict, onWarning: options?.onWarning });
-    const ctx = { best: null };
-    const hasRefs = frontMatter.includes('($') || frontMatter.includes('(%');
-    let finalMap;
-    if (!hasRefs) {
-        finalMap = root;
-    }
-    else {
-        // Phase 1 (§4.1): resolve each top-level key's value in document
-        // order against a live, growing snapshot of already-processed keys
-        // — reproduces backward-reference resolution without needing a
-        // second pass for the common case.
-        const phase1Live = new Map();
-        // §3.7/§4 one-hop limit: a top-level key whose OWN inline value was
-        // itself a pure reference token must never be usable as another
-        // key's hop target via its (possibly already-resolved) live value —
-        // only its original token text is a valid phase-2 lookup target, so
-        // a chain a→b→c can never fully resolve regardless of where c
-        // happens to be written relative to b (§4: independent of mapping
-        // enumeration order).
-        const originalPureRefText = new Map();
-        for (const [key, node] of root) {
-            if (node.kind === 'string' && !node.quoted && PURE_REF_RE.test(node.value)) {
-                originalPureRefText.set(key, node.value);
-            }
-            phase1Live.set(key, resolveTree(node, phase1Live, partialsPositioned, ctx));
-        }
-        // Phase 2 (§4.2): re-resolve every key's phase-1 value — this is
-        // what catches forward references — against a snapshot that is
-        // immutable for the whole phase (a plain reference to a Map built
-        // once above, no cloning needed: nothing here mutates it).
-        const phase1Snapshot = new Map();
-        for (const [key, value] of phase1Live) {
-            phase1Snapshot.set(key, originalPureRefText.has(key)
-                ? { kind: 'string', value: originalPureRefText.get(key), line: root.get(key).line, quoted: false }
-                : value);
-        }
-        finalMap = new Map();
-        for (const [key] of root) {
-            finalMap.set(key, resolveTree(phase1Live.get(key), phase1Snapshot, partialsPositioned, ctx));
-        }
-    }
-    // Strict mode: collect every reference still unresolved after both
-    // phases. Each leaf reports its OWN line — every node in this tree
-    // carries one from the moment Core parsed it, so no separate
-    // provenance-tracking pass is needed to attribute this precisely.
-    if (strict) {
-        const scanUnresolved = (v) => {
-            if (v.kind === 'string') {
-                if (!v.quoted && (v.value.includes('($') || v.value.includes('(%'))) {
-                    const m = v.value.match(/\(([%$])([^)]+)\)/);
-                    if (m) {
-                        reportDiagnostic(ctx, {
-                            code: 'UNRESOLVED_REFERENCE', line: v.line, token: `(${m[1]}${m[2]})`,
-                            message: `Lima: unresolved reference "(${m[1]}${m[2]})" at line ${v.line}`,
-                        });
-                    }
-                }
-                return;
-            }
-            if (v.kind === 'array') {
-                for (const item of v.items)
-                    scanUnresolved(item);
-                return;
-            }
-            if (v.kind === 'mapping') {
-                for (const c of v.entries.values())
-                    scanUnresolved(c);
-                return;
-            }
-        };
-        for (const v of finalMap.values())
-            scanUnresolved(v);
-    }
-    // §5: of every reference-resolution error collected above, the one at
-    // the lowest source line is thrown; the rest are discarded.
-    if (ctx.best !== null) {
-        throw new LimaError(ctx.best);
-    }
-    // Depth (Core §9, re-checked on the final POST-substitution tree —
-    // inserted values can add depth Core's own pre-resolution check inside
-    // parseCoreWithPositions could not see yet), node count (§6.2), and the
-    // native result itself all come out of one pass over `finalMap` — see
-    // finalizePositioned's doc comment for why this replaces three
-    // independent full-tree walks.
-    const finalResults = [];
-    for (const [k, v] of finalMap)
-        finalResults.push([k, finalizePositioned(v)]);
-    // References §5/R-112: attributed to the lowest-line reference token
-    // among the insertions on the actual deepest path, or line 1 (R-113)
-    // when the excess depth came entirely from literal, non-reference
-    // content.
-    const depth = finalResults.length === 0 ? 0 : Math.max(...finalResults.map(([, r]) => r.depth));
-    if (depth > NESTING_DEPTH_LIMIT) {
-        const participants = finalResults.filter(([, r]) => r.depth === depth).flatMap(([, r]) => r.deepestParticipants);
-        const winner = earliestParticipant(participants);
-        throw new LimaError({
-            code: 'RESOURCE_LIMIT', line: winner?.line ?? 1, token: winner?.token,
-            message: winner
-                ? `Lima: nesting depth exceeds maximum of ${NESTING_DEPTH_LIMIT} at line ${winner.line}: "${winner.token}"`
-                : `Lima: nesting depth exceeds maximum of ${NESTING_DEPTH_LIMIT} at line 1`,
-        });
-    }
-    // §6.2: total node count of the final result tree, both modes. Same
-    // R-112 attribution — every reference insertion anywhere in the tree
-    // contributes to the total, so the lowest-line one is reported.
-    let totalResultNodes = 1; // the root mapping itself counts as one node
-    for (const [, r] of finalResults)
-        totalResultNodes += r.nodeCount;
-    if (totalResultNodes > RESULT_NODE_LIMIT) {
-        const participants = [];
-        for (const v of finalMap.values())
-            collectAllParticipants(v, participants);
-        const winner = earliestParticipant(participants);
-        throw new LimaError({
-            code: 'RESOURCE_LIMIT', line: winner?.line ?? 1, token: winner?.token,
-            message: winner
-                ? `Lima: result exceeds maximum size of ${RESULT_NODE_LIMIT} total nodes at line ${winner.line}: "${winner.token}"`
-                : `Lima: result exceeds maximum size of ${RESULT_NODE_LIMIT} total nodes at line 1`,
-        });
-    }
-    const out = emptyMapping();
-    for (const [k, r] of finalResults)
-        out[k] = r.native;
-    return out;
-};
-/** Backward-compatible primary entry point — References layered on Core. */
-export const parse = parseReferences;
-/** Internal conformance entry point for the frozen References 1.0 suite. */
-export const parseReferencesV1 = parseReferences;