@limaformat/lima 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -12,8 +12,22 @@ are both frozen regardless of what this file shows.
 
 ## [Unreleased]
 
+## [0.2.0] — 2026-08-11
+
 ### Changed
 
+- **Breaking:** `parse(input, options?)` now implements Lima References 2.0.
+  Document references use `$(key)` instead of `($key)`, and partial
+  references use `$(:key)` instead of `(%key)`. References 1.0 tokens are
+  literal text through the public 2.0 API.
+- `parseReferences(input, options?)` is now a deprecated compatibility alias
+  for `parse` with identical References 2.0 results and diagnostics. It is not
+  a References 1.0 mode.
+- `ParseOptions.mode` selects `"references"` (the default) or `"core"`.
+  Core mode uses the same reference-unaware path as `parseCore`; supplying
+  `partials` in Core mode is invalid. `parseCore` itself is unchanged.
+- References 2.0 adds bounded transitive resolution (at most three reference
+  edges), partial mapping traversal, and `$(:namespace/name.path)` partials.
 - Error message prefix `LIMA:` → `Lima:` throughout (e.g. `LIMA: duplicate
   key "a" at line 3` → `Lima: duplicate key "a" at line 3`), plus internal
   code comments — naming-consistency fix, no functional change. `.code`

package/README.md

@@ -35,30 +35,33 @@ tags:
 `parse` accepts the raw content **between** the frontmatter delimiters
 (`---`) — stripping them is the caller's job.
 
-Two functions are exported:
+Three functions are exported:
 
 - `parseCore(input, options?)` — the base format only.
-- `parse(input, options?)` (alias for `parseReferences`) — adds
-  `($key)` document references and `(%key)` external partials.
+- `parse(input, options?)` — the primary References 2.0 parser; adds
+  `$(key)` document references and `$(:key)` external partials.
+- `parseReferences(input, options?)` — deprecated compatibility alias for
+  `parse` with the same References 2.0 semantics.
 
 ```ts
 parse(frontmatter, { strict: true })
 parse(frontmatter, { partials: { author: 'Alice' } })
+parse(frontmatter, { mode: 'core' }) // same reference-unaware path as parseCore
 ```
 
-Full syntax reference, the References extension, resource limits, strict
-mode, and the complete API:
-**[docs/guide.md](https://github.com/limaformat/lima/blob/main/docs/guide.md)**.
+The **[guide](https://github.com/limaformat/lima/blob/main/docs/guide.md)**
+covers Core and References 2.0 syntax, resource limits, strict mode, and the
+public API. The normative rules are defined in the
+**[References 2.0 specification](https://github.com/limaformat/lima/blob/main/docs/lima-references-2.0-spec.md)**.
 
 Why Lima exists, the case against YAML, and security rationale:
 **[repository README](https://github.com/limaformat/lima#readme)**.
 
 The [Lima Core 1.0](https://github.com/limaformat/lima/blob/main/docs/lima-core-1.0-spec.md)
-and [Lima References 1.0](https://github.com/limaformat/lima/blob/main/docs/lima-references-1.0-spec.md)
-specifications are the normative source of truth — this package implements
-them exactly, verified against a
-[250-case conformance corpus](https://github.com/limaformat/lima/tree/main/corpus)
-(count pinned by a test) shared with any other Lima implementation.
+and [Lima References 2.0](https://github.com/limaformat/lima/blob/main/docs/lima-references-2.0-spec.md)
+specifications are the source of truth for these public entry points. The
+frozen References 1.0 implementation remains available internally to run its
+independent conformance suite.
 
 Migrating existing YAML frontmatter:
 [docs/migrating-from-yaml.md](https://github.com/limaformat/lima/blob/main/docs/migrating-from-yaml.md).

package/dist/builder.d.ts

@@ -25,11 +25,13 @@
  * therefore performance — is identical either way, verified by benchmark.
  */
 export interface ValueBuilder<V, M = Map<string, V>> {
+    /** Opt-in for References' annotated builder; native Core avoids source-map work. */
+    readonly tracksStringSourcePositions?: boolean;
     null(line: number): V;
     bool(value: boolean, line: number): V;
     int(value: number, line: number): V;
     float(value: number, line: number): V;
-    string(value: string, line: number, quoted: boolean): V;
+    string(value: string, line: number, quoted: boolean, sourceSpans?: StringSourceSpan[]): V;
     instant(value: Date, line: number): V;
     array(items: V[], line: number): V;
     createMapping(): M;
@@ -39,3 +41,9 @@ export interface ValueBuilder<V, M = Map<string, V>> {
     mappingMaxDepth(entries: M, depthOf: (value: V) => number): number;
     mapping(entries: M, line: number): V;
 }
+/** Maps a span in a decoded scalar back to its physical source line/column. */
+export type StringSourceSpan = {
+    start: number;
+    line: number;
+    sourceOffset: number;
+};

package/dist/core.js

@@ -239,7 +239,9 @@ const parseCoreGeneric = (frontMatter, ctx, builder, computeDepth) => {
             minIndent = Math.min(minIndent, key.length + 2);
             const trimAmt = minIndent > 1 && isFinite(minIndent) ? minIndent : 0;
             const mergedLines = [];
-            for (const bodyLine of bodyLines) {
+            const mergedLineSpans = builder.tracksStringSourcePositions ? [] : undefined;
+            for (let bodyIndex = 0; bodyIndex < bodyLines.length; bodyIndex++) {
+                const bodyLine = bodyLines[bodyIndex];
                 const lineLen = bodyLine.length;
                 let start = trimAmt < lineLen ? trimAmt : lineLen;
                 const isContinuation = bodyLine.charCodeAt(start) === 94 && bodyLine.charCodeAt(start + 1) === 94; // ^^
@@ -251,22 +253,41 @@ const parseCoreGeneric = (frontMatter, ctx, builder, computeDepth) => {
                 const content = bodyLine.slice(start, end);
                 if (isContinuation) {
                     if (mergedLines.length > 0) {
-                        if (content)
+                        if (content) {
+                            const outputStart = mergedLines[mergedLines.length - 1].length + 1;
                             mergedLines[mergedLines.length - 1] += ' ' + content;
+                            mergedLineSpans?.[mergedLineSpans.length - 1].push({
+                                start: outputStart, line: line + 1 + bodyIndex, sourceOffset: start,
+                            });
+                        }
                     }
                     else {
                         mergedLines.push(content);
+                        mergedLineSpans?.push(content ? [{ start: 0, line: line + 1 + bodyIndex, sourceOffset: start }] : []);
                     }
                 }
                 else {
                     mergedLines.push(content);
+                    mergedLineSpans?.push(content ? [{ start: 0, line: line + 1 + bodyIndex, sourceOffset: start }] : []);
                 }
             }
-            while (mergedLines.length > 0 && mergedLines[mergedLines.length - 1] === '')
+            while (mergedLines.length > 0 && mergedLines[mergedLines.length - 1] === '') {
                 mergedLines.pop();
+                mergedLineSpans?.pop();
+            }
             const joined = mergedLines.join('\n');
+            let sourceSpans;
+            if (mergedLineSpans) {
+                sourceSpans = [];
+                let outputStart = 0;
+                for (let i = 0; i < mergedLines.length; i++) {
+                    for (const span of mergedLineSpans[i])
+                        sourceSpans.push({ ...span, start: outputStart + span.start });
+                    outputStart += mergedLines[i].length + 1;
+                }
+            }
             checkScalarLimit(LString(joined), line);
-            builder.setMapping(root, key, builder.string(joined, line, false));
+            builder.setMapping(root, key, builder.string(joined, line + 1, false, sourceSpans));
         }
     };
     // A recognised top-level entry needs at least one UTF-16 unit of key text,

package/dist/index.d.ts

@@ -4,12 +4,13 @@
  * Public entry point. The implementation is split per Appendix B's own
  * layering:
  *   - `core.ts`       — Lima Core 1.0, reference-unaware by construction.
- *   - `references.ts` — the optional References 1.0 extension, layered on
- *                        top of Core's internal annotated value tree.
+ *   - `references2.ts` — the References 2.0 extension layered on Core.
+ *   - `references.ts`  — the frozen internal References 1.0 implementation.
  *   - `value.ts`       — the shared Lima Value Model both build on.
  *
- * `parse` (the historical default export) resolves references — it is
- * `parseReferences` under a name kept for backward compatibility.
+ * `parse` is the primary References 2.0 entry point. `parseReferences` is
+ * retained as its deprecated compatibility alias.
  */
 export { parseCore, type CoreOptions, type Diagnostic } from './core.js';
-export { parseReferences, parse, type ReferencesOptions, type ParseOptions } from './references.js';
+export { parseReferences, parse, type ParseMode, type ParseOptions } from './references2.js';
+export type ReferencesOptions = import('./references2.js').ParseOptions;

package/dist/index.js

@@ -4,12 +4,12 @@
  * Public entry point. The implementation is split per Appendix B's own
  * layering:
  *   - `core.ts`       — Lima Core 1.0, reference-unaware by construction.
- *   - `references.ts` — the optional References 1.0 extension, layered on
- *                        top of Core's internal annotated value tree.
+ *   - `references2.ts` — the References 2.0 extension layered on Core.
+ *   - `references.ts`  — the frozen internal References 1.0 implementation.
  *   - `value.ts`       — the shared Lima Value Model both build on.
  *
- * `parse` (the historical default export) resolves references — it is
- * `parseReferences` under a name kept for backward compatibility.
+ * `parse` is the primary References 2.0 entry point. `parseReferences` is
+ * retained as its deprecated compatibility alias.
  */
 export { parseCore } from './core.js';
-export { parseReferences, parse } from './references.js';
+export { parseReferences, parse } from './references2.js';

package/dist/reference-tokens2.d.ts

@@ -0,0 +1,12 @@
+/** Reference tokens recorded while the annotated Core tree is being built. */
+import type { StringSourceSpan } from './builder.js';
+export type ReferenceToken2 = {
+    token: string;
+    index: number;
+    offset: number;
+    line: number;
+    documentPath?: string;
+    partialPath?: string;
+};
+export declare const PURE_REFERENCE_2: RegExp;
+export declare const scanReferenceTokens2: (value: string, firstLine: number, sourceSpans?: StringSourceSpan[]) => ReferenceToken2[];

package/dist/reference-tokens2.js

@@ -0,0 +1,37 @@
+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 PURE_REFERENCE_2 = new RegExp(`^\\$\\((?:(${DOC_PATH})|:(${PARTIAL_PATH}))\\)$`);
+const REFERENCE_2 = new RegExp(`\\$\\((?:(${DOC_PATH})|:(${PARTIAL_PATH}))\\)`, 'g');
+const NO_TOKENS = [];
+export const scanReferenceTokens2 = (value, firstLine, sourceSpans) => {
+    if (!value.includes('$('))
+        return NO_TOKENS;
+    REFERENCE_2.lastIndex = 0;
+    const result = [];
+    let line = firstLine;
+    let lineStart = 0;
+    let scanned = 0;
+    let spanIndex = 0;
+    for (const match of value.matchAll(REFERENCE_2)) {
+        const index = match.index ?? 0;
+        while (scanned < index) {
+            if (value.charCodeAt(scanned) === 10) {
+                line++;
+                lineStart = scanned + 1;
+            }
+            scanned++;
+        }
+        while (sourceSpans && spanIndex + 1 < sourceSpans.length && sourceSpans[spanIndex + 1].start <= index)
+            spanIndex++;
+        const source = sourceSpans?.[spanIndex];
+        result.push({
+            token: match[0], index,
+            line: source?.line ?? line,
+            offset: source ? source.sourceOffset + index - source.start : index - lineStart,
+            ...(match[1] !== undefined ? { documentPath: match[1] } : { partialPath: match[2] }),
+        });
+    }
+    return result;
+};

package/dist/references.d.ts

@@ -20,8 +20,71 @@
  * 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';
+import { type LimaValue } from './value.js';
+import { type PositionedValue, type Diagnostic, type InsertedAt, type NativeValue } from './core.js';
 type Meta = Record<string, unknown>;
+/**
+ * Structural deep copy for document-derived targets — preserves each leaf's
+ * own line/quoted (§4.2/R-104: still eligible for further resolution) and
+ * any existing `insertedAt` provenance from an earlier, nested resolution
+ * (R-112: a reference copied wholesale into a new position can itself
+ * already contain the result of an inner reference that resolved first —
+ * both insertion sites remain identifiable participants after the copy).
+ */
+export declare const deepCopyPositioned: (v: PositionedValue) => PositionedValue;
+/**
+ * Wraps a partial's ingested value into the annotated representation, with
+ * every string leaf marked permanently inert (§3.8: "no traversal into
+ * partial values" — the resolution phases must never rediscover a
+ * reference-like substring inside partial content). Called once per partial
+ * name at ingestion (see the call site), producing the one canonical tree
+ * every pure reference to that partial retrieves — deep-copying it on every
+ * such reference (§3.1) is the resolveTree call site's job, not this one.
+ */
+export declare const partialToPositioned: (v: LimaValue, line: number) => PositionedValue;
+/**
+ * References §5/R-112 (nesting depth), §6.2 (node count), and the public
+ * result shape (native conversion) computed together in one recursive pass
+ * over the final, post-substitution tree — instead of three independent
+ * full-tree walks (a depth-only pass, a count-only pass, then
+ * `toNativeFromPositioned`), each of which would otherwise revisit every
+ * node of what can be a large, reference-expanded result. Depth attribution
+ * needs more than a depth number: it needs to know which reference
+ * insertions lie on the actual deepest path, so the earliest of those (by
+ * line) can be blamed if the limit is exceeded — ties for "deepest child"
+ * all count, since a violation can be reached via more than one
+ * maximal-depth branch. `native` is still built unconditionally even
+ * though a depth/node-count violation elsewhere in the document means it
+ * will be discarded and never returned — cheaper than adding a second
+ * conditional branch to every call site, and the discarded case is the
+ * rare (error) path, not the one this pass exists to speed up.
+ *
+ * Each array/mapping branch tracks a running max depth and its participant
+ * list in a single loop over its children, instead of first materializing a
+ * full array of child results and then doing separate `.map()`/`Math.max`/
+ * `.filter().flatMap()` passes over it — for a wide sibling group (many
+ * children at the same depth, the common shape for flat documents with many
+ * top-level references) that would mean an extra full pass per level on top
+ * of the traversal itself. A running accumulator only ever copies-on-write:
+ * `.slice()` when a strictly greater depth replaces the running set, plain
+ * `.push()` onto that fresh copy for a tie at the current max — never a
+ * mutation of a child's own returned array. Reusing a child's array in
+ * place would currently be safe (each node is visited exactly once, no
+ * aliasing left after the pure-reference deep-copy fix), but relying on
+ * that invariant here has no upside worth the risk in a file that has
+ * already had one real aliasing bug.
+ */
+export type FinalizedValue = {
+    native: NativeValue;
+    nodeCount: number;
+    depth: number;
+    deepestParticipants: InsertedAt[];
+};
+export declare const finalizePositioned: (v: PositionedValue) => FinalizedValue;
+/** Earliest (lowest-line) participant, or null when none exist — R-113's "line 1" fallback applies then. */
+export declare const earliestParticipant: (participants: InsertedAt[]) => InsertedAt | null;
+/** Node-count attribution for the RESOURCE_LIMIT error path: every reference insertion anywhere in the tree contributes to the total. */
+export declare const collectAllParticipants: (v: PositionedValue, acc: InsertedAt[]) => void;
 export type ReferencesOptions = {
     /** Named values available via `(%key)` references. */
     partials?: Meta;
@@ -33,4 +96,6 @@ export declare const parseReferences: <T extends Record<string, unknown> = Meta>
 /** 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

@@ -110,14 +110,14 @@ const isReferenceFreeP = (v) => {
  * already contain the result of an inner reference that resolved first —
  * both insertion sites remain identifiable participants after the copy).
  */
-const deepCopyPositioned = (v) => {
+export const deepCopyPositioned = (v) => {
     switch (v.kind) {
-        case 'array': return { kind: 'array', items: v.items.map(deepCopyPositioned), line: v.line, insertedAt: v.insertedAt };
+        case 'array': return { kind: 'array', items: v.items.map(deepCopyPositioned), line: v.line, references2Active: v.references2Active, insertedAt: v.insertedAt };
         case 'mapping': {
             const entries = new Map();
             for (const [k, c] of v.entries)
                 entries.set(k, deepCopyPositioned(c));
-            return { kind: 'mapping', entries, line: v.line, insertedAt: v.insertedAt };
+            return { kind: 'mapping', entries, line: v.line, references2Active: v.references2Active, insertedAt: v.insertedAt };
         }
         case 'instant': return { kind: 'instant', value: new Date(v.value.getTime()), line: v.line, insertedAt: v.insertedAt };
         default: return v;
@@ -132,7 +132,7 @@ const deepCopyPositioned = (v) => {
  * every pure reference to that partial retrieves — deep-copying it on every
  * such reference (§3.1) is the resolveTree call site's job, not this one.
  */
-const partialToPositioned = (v, line) => {
+export const partialToPositioned = (v, line) => {
     switch (v.kind) {
         case 'null': return { kind: 'null', line };
         case 'bool': return { kind: 'bool', value: v.value, line };
@@ -282,7 +282,7 @@ const resolveTree = (node, lookup, partials, ctx) => {
     }
     return node; // null/bool/int/float/instant — nothing to resolve
 };
-const finalizePositioned = (v) => {
+export const finalizePositioned = (v) => {
     const own = v.insertedAt ? [v.insertedAt] : [];
     if (v.kind === 'array') {
         if (v.items.length === 0)
@@ -334,9 +334,9 @@ const finalizePositioned = (v) => {
     return { native: toNativeFromPositioned(v), nodeCount: 1, depth: 0, deepestParticipants: own };
 };
 /** Earliest (lowest-line) participant, or null when none exist — R-113's "line 1" fallback applies then. */
-const earliestParticipant = (participants) => participants.length === 0 ? null : participants.reduce((a, b) => (b.line < a.line ? b : a));
+export const earliestParticipant = (participants) => participants.length === 0 ? null : participants.reduce((a, b) => (b.line < a.line ? b : a));
 /** Node-count attribution for the RESOURCE_LIMIT error path: every reference insertion anywhere in the tree contributes to the total. */
-const collectAllParticipants = (v, acc) => {
+export const collectAllParticipants = (v, acc) => {
     if (v.insertedAt)
         acc.push(v.insertedAt);
     if (v.kind === 'array')
@@ -520,3 +520,5 @@ export const parseReferences = (frontMatter, options) => {
 };
 /** 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;

package/dist/references2.d.ts

@@ -0,0 +1,13 @@
+import { type Diagnostic } from './core.js';
+type Meta = Record<string, unknown>;
+export type ParseMode = 'references' | 'core';
+export type ParseOptions = {
+    mode?: ParseMode;
+    partials?: Meta;
+    strict?: boolean;
+    onWarning?: (diagnostic: Diagnostic) => void;
+};
+export declare const parse: <T extends Record<string, unknown> = Meta>(frontMatter: string, options?: ParseOptions) => T;
+/** @deprecated Use parse(). */
+export declare const parseReferences: typeof parse;
+export {};

package/dist/references2.js

@@ -0,0 +1,295 @@
+/** Lima References 2.0 resolver. References 1.0 remains isolated in references.ts. */
+import { canonicalString, codepointLength, countNodes, ingestPartialValue, PARTIAL_COUNT_LIMIT, PARTIAL_NAME_LENGTH_LIMIT, PARTIAL_NODE_LIMIT, RESULT_NODE_LIMIT, SCALAR_LENGTH_LIMIT, } from './value.js';
+import { NESTING_DEPTH_LIMIT, parseCore, parseCoreWithPositions, toPlainValue, } from './core.js';
+import { hasActiveReferences2 } from './scalars.js';
+import { LimaError } from './errors.js';
+import { collectAllParticipants, deepCopyPositioned, earliestParticipant, finalizePositioned, partialToPositioned, } from './references.js';
+const emptyMapping = () => Object.create(null);
+const PARTIAL_NAME = '[a-zA-Z0-9_][a-zA-Z0-9_:/-]*';
+const PARTIAL_NAME_RE = new RegExp(`^${PARTIAL_NAME}$`);
+const MAX_EDGES = 3;
+const addDiagnostic = (ctx, diagnostic, offset = 0) => {
+    ctx.diagnostics.push({ ...diagnostic, offset });
+};
+const tokenMatches = (node) => node.references2 ?? [];
+const lookupPath = (root, segments) => {
+    let current = root;
+    for (const segment of segments) {
+        if (current?.kind !== 'mapping')
+            return undefined;
+        current = current.entries.get(segment);
+    }
+    return current;
+};
+const documentTarget = (root, path) => {
+    const segments = path.split('.');
+    const value = root.get(segments[0]);
+    return value === undefined ? undefined : { root: value, tail: segments.slice(1) };
+};
+const lookupPartial = (partials, path) => {
+    const dot = path.indexOf('.');
+    if (dot < 0)
+        return partials.get(path);
+    return lookupPath(partials.get(path.slice(0, dot)), path.slice(dot + 1).split('.'));
+};
+const isActiveString = (node) => node.kind === 'string' && !node.quoted;
+const scalarText = (value, token, line, offset, ctx) => {
+    if (value.kind === 'mapping') {
+        addDiagnostic(ctx, {
+            code: 'INVALID_INTERPOLATION', line, token,
+            message: `Lima: invalid interpolation of "${token}" at line ${line}: mapping cannot be interpolated into a string`,
+        }, offset);
+        return null;
+    }
+    if (value.kind === 'array') {
+        if (value.items.some((item) => item.kind === 'array' || item.kind === 'mapping')) {
+            addDiagnostic(ctx, {
+                code: 'INVALID_INTERPOLATION', line, token,
+                message: `Lima: invalid interpolation of "${token}" at line ${line}: array contains a nested array or mapping`,
+            }, offset);
+            return null;
+        }
+        return value.items.map((item) => canonicalString(toPlainValue(item))).join(', ');
+    }
+    return canonicalString(toPlainValue(value));
+};
+const resolveNodeUncached = (node, document, partials, ctx, remainingEdges, stack) => {
+    if (node.kind === 'array') {
+        if (!hasActiveReferences2(node))
+            return { value: node, complete: true };
+        let complete = true;
+        const items = node.items.map((item) => {
+            const result = resolveNode(item, document, partials, ctx, remainingEdges, stack);
+            complete &&= result.complete;
+            if (isActiveString(item) && result.value.kind === 'array') {
+                const match = tokenMatches(item)[0];
+                const token = match?.token ?? item.value;
+                addDiagnostic(ctx, {
+                    code: 'INVALID_REFERENCE_SHAPE', line: item.line, token,
+                    message: `Lima: reference "${token}" resolves to an array, which cannot be inserted as a sequence item at line ${item.line}`,
+                });
+                return item;
+            }
+            return result.value;
+        });
+        return {
+            value: { ...node, items, references2Active: items.some(hasActiveReferences2) || undefined },
+            complete,
+        };
+    }
+    if (node.kind === 'mapping') {
+        if (!hasActiveReferences2(node))
+            return { value: node, complete: true };
+        let complete = true;
+        const entries = new Map();
+        for (const [key, child] of node.entries) {
+            const result = resolveNode(child, document, partials, ctx, remainingEdges, stack);
+            complete &&= result.complete;
+            entries.set(key, result.value);
+        }
+        let references2Active = false;
+        for (const value of entries.values()) {
+            if (hasActiveReferences2(value)) {
+                references2Active = true;
+                break;
+            }
+        }
+        return { value: { ...node, entries, references2Active: references2Active || undefined }, complete };
+    }
+    if (!isActiveString(node))
+        return { value: node, complete: true };
+    const recorded = tokenMatches(node);
+    const pure = recorded.length === 1 && recorded[0].index === 0 && recorded[0].token.length === node.value.length
+        ? recorded[0]
+        : undefined;
+    if (pure) {
+        if (remainingEdges === 0)
+            return { value: node, complete: false };
+        const documentLookup = pure.documentPath !== undefined ? documentTarget(document, pure.documentPath) : undefined;
+        const target = pure.documentPath !== undefined ? documentLookup?.root : lookupPartial(partials, pure.partialPath);
+        if (target === undefined || stack.has(target))
+            return { value: node, complete: false };
+        if (pure.partialPath !== undefined) {
+            return {
+                value: { ...deepCopyPositioned(target), insertedAt: { line: pure.line, token: pure.token } },
+                complete: true,
+            };
+        }
+        stack.add(target);
+        const result = resolveNode(target, document, partials, ctx, remainingEdges - 1, stack);
+        stack.delete(target);
+        if (!result.complete)
+            return { value: node, complete: false };
+        const selected = lookupPath(result.value, documentLookup?.tail ?? []);
+        if (selected === undefined)
+            return { value: node, complete: false };
+        return {
+            value: { ...deepCopyPositioned(selected), insertedAt: { line: pure.line, token: pure.token } },
+            complete: true,
+        };
+    }
+    const matches = recorded;
+    if (matches.length === 0)
+        return { value: node, complete: true };
+    let complete = true;
+    let cursor = 0;
+    let output = '';
+    const unresolvedTokens = [];
+    for (const match of matches) {
+        const offset = match.index;
+        output += node.value.slice(cursor, offset);
+        const documentLookup = match.documentPath !== undefined ? documentTarget(document, match.documentPath) : undefined;
+        const target = match.documentPath !== undefined ? documentLookup?.root : lookupPartial(partials, match.partialPath);
+        let replacement = null;
+        if (remainingEdges > 0 && target !== undefined && !stack.has(target)) {
+            if (match.partialPath !== undefined)
+                replacement = scalarText(target, match.token, match.line, match.offset, ctx);
+            else {
+                stack.add(target);
+                const result = resolveNode(target, document, partials, ctx, remainingEdges - 1, stack);
+                stack.delete(target);
+                const selected = result.complete ? lookupPath(result.value, documentLookup?.tail ?? []) : undefined;
+                if (selected !== undefined)
+                    replacement = scalarText(selected, match.token, match.line, match.offset, ctx);
+            }
+        }
+        if (replacement === null) {
+            complete = false;
+            unresolvedTokens.push({ ...match, index: output.length });
+            output += match.token;
+        }
+        else
+            output += replacement;
+        cursor = offset + match.token.length;
+    }
+    output += node.value.slice(cursor);
+    if (codepointLength(output) > SCALAR_LENGTH_LIMIT) {
+        const first = matches[0];
+        addDiagnostic(ctx, {
+            code: 'RESOURCE_LIMIT', line: first.line, token: first.token,
+            message: `Lima: scalar exceeds maximum length of ${SCALAR_LENGTH_LIMIT} code points at line ${first.line}`,
+        }, first.offset);
+    }
+    return { value: { ...node, value: output, references2: unresolvedTokens }, complete };
+};
+/** Successful and failed dependency results are immutable and budget-specific. */
+const resolveNode = (node, document, partials, ctx, remainingEdges, stack) => {
+    const cacheable = stack.size > 1 && (node.kind === 'array' || node.kind === 'mapping' ||
+        (isActiveString(node) && tokenMatches(node).length > 0));
+    if (!cacheable)
+        return resolveNodeUncached(node, document, partials, ctx, remainingEdges, stack);
+    const byBudget = ctx.cache.get(node);
+    const cached = byBudget?.get(remainingEdges);
+    if (cached !== undefined)
+        return cached;
+    const result = resolveNodeUncached(node, document, partials, ctx, remainingEdges, stack);
+    if (byBudget !== undefined)
+        byBudget.set(remainingEdges, result);
+    else
+        ctx.cache.set(node, new Map([[remainingEdges, result]]));
+    return result;
+};
+const validatePartials = (raw) => {
+    const names = Object.keys(raw);
+    if (names.length > PARTIAL_COUNT_LIMIT) {
+        throw new LimaError({ code: 'INVALID_PARTIAL', message: `Lima: too many partials (max ${PARTIAL_COUNT_LIMIT})` });
+    }
+    for (const name of names) {
+        if (!PARTIAL_NAME_RE.test(name)) {
+            throw new LimaError({ code: 'INVALID_PARTIAL', partial: name, message: `Lima: invalid partial name "${name}"` });
+        }
+        if (codepointLength(name) > PARTIAL_NAME_LENGTH_LIMIT) {
+            throw new LimaError({ code: 'INVALID_PARTIAL', partial: name, message: `Lima: invalid partial name "${name}": exceeds maximum length of ${PARTIAL_NAME_LENGTH_LIMIT} code points` });
+        }
+    }
+    const ingested = new Map();
+    for (const name of names)
+        ingested.set(name, ingestPartialValue(raw[name], name, name));
+    let nodes = 0;
+    for (const value of ingested.values())
+        nodes += countNodes(value);
+    if (nodes > PARTIAL_NODE_LIMIT) {
+        throw new LimaError({ code: 'INVALID_PARTIAL', message: `Lima: partials exceed the combined maximum of ${PARTIAL_NODE_LIMIT} value nodes` });
+    }
+    const result = new Map();
+    for (const [name, value] of ingested)
+        result.set(name, partialToPositioned(value, 0));
+    return result;
+};
+const scanUnresolved = (node, ctx) => {
+    if (isActiveString(node)) {
+        for (const match of tokenMatches(node)) {
+            addDiagnostic(ctx, {
+                code: 'UNRESOLVED_REFERENCE', line: match.line, token: match.token,
+                message: `Lima: unresolved reference "${match.token}" at line ${match.line}`,
+            }, match.offset);
+        }
+        return;
+    }
+    if (node.kind === 'array')
+        for (const item of node.items)
+            scanUnresolved(item, ctx);
+    if (node.kind === 'mapping')
+        for (const child of node.entries.values())
+            scanUnresolved(child, ctx);
+};
+export const parse = (frontMatter, options) => {
+    if (options?.mode !== undefined && options.mode !== 'core' && options.mode !== 'references') {
+        throw new TypeError(`Lima: invalid parse mode "${String(options.mode)}"`);
+    }
+    if (options?.mode === 'core') {
+        if (Object.prototype.hasOwnProperty.call(options, 'partials')) {
+            throw new TypeError('Lima: partials cannot be supplied in core mode');
+        }
+        // Core ignores the additional `mode` property. Passing the same object
+        // avoids allocating a projected options object on this hot dispatch path.
+        return parseCore(frontMatter, options);
+    }
+    const partials = validatePartials(options?.partials ?? {});
+    if (!frontMatter.includes('$(')) {
+        return parseCore(frontMatter, options);
+    }
+    const document = parseCoreWithPositions(frontMatter, { strict: options?.strict ?? false, onWarning: options?.onWarning });
+    const ctx = { diagnostics: [], 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);
+    }
+    if (options?.strict)
+        for (const value of resolved.values())
+            scanUnresolved(value, ctx);
+    if (ctx.diagnostics.length > 0) {
+        ctx.diagnostics.sort((a, b) => a.line - b.line || a.offset - b.offset);
+        throw new LimaError(ctx.diagnostics[0]);
+    }
+    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,
+            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,
+            message: `Lima: result exceeds maximum size of ${RESULT_NODE_LIMIT} total nodes at line ${winner?.line ?? 1}`,
+        });
+    }
+    const out = emptyMapping();
+    for (const [key, value] of finalized)
+        out[key] = value.native;
+    return out;
+};
+/** @deprecated Use parse(). */
+export const parseReferences = parse;

package/dist/scalars.d.ts

@@ -7,6 +7,7 @@
 import { type LimaValue } from './value.js';
 import { type ParseContext } from './normalize.js';
 import type { ValueBuilder } from './builder.js';
+import { type ReferenceToken2 } from './reference-tokens2.js';
 /**
  * `insertedAt` is never set by Core — it's a References-only annotation
  * (see references.ts's `resolveTree`), stamped on the root of a value
@@ -45,6 +46,7 @@ export type PositionedValue = {
     value: string;
     line: number;
     quoted: boolean;
+    references2?: ReferenceToken2[];
     insertedAt?: InsertedAt;
 } | {
     kind: 'instant';
@@ -55,13 +57,16 @@ export type PositionedValue = {
     kind: 'array';
     items: PositionedValue[];
     line: number;
+    references2Active?: boolean;
     insertedAt?: InsertedAt;
 } | {
     kind: 'mapping';
     entries: Map<string, PositionedValue>;
     line: number;
+    references2Active?: boolean;
     insertedAt?: InsertedAt;
 };
+export declare const hasActiveReferences2: (value: PositionedValue) => boolean;
 /** The `ValueBuilder<PositionedValue>` — reconstructs today's annotated tree exactly, for References. */
 export declare const positionedBuilder: ValueBuilder<PositionedValue>;
 /** Strips position/quoted-origin annotations, recursively — the public parseCore() projection. */

package/dist/scalars.js

@@ -7,15 +7,29 @@
 import { LNull, LBool, LFloat, LInt, LString, LInstant } from './value.js';
 import { checkStringLimit } from './normalize.js';
 import { LimaError } from './errors.js';
+import { scanReferenceTokens2 } from './reference-tokens2.js';
+export const hasActiveReferences2 = (value) => value.kind === 'string' ? (value.references2?.length ?? 0) > 0
+    : value.kind === 'array' || value.kind === 'mapping' ? value.references2Active === true
+        : false;
 /** The `ValueBuilder<PositionedValue>` — reconstructs today's annotated tree exactly, for References. */
 export const positionedBuilder = {
+    tracksStringSourcePositions: true,
     null: (line) => ({ kind: 'null', line }),
     bool: (value, line) => ({ kind: 'bool', value, line }),
     int: (value, line) => ({ kind: 'int', value, line }),
     float: (value, line) => ({ kind: 'float', value, line }),
-    string: (value, line, quoted) => ({ kind: 'string', value, line, quoted }),
+    string: (value, line, quoted, sourceSpans) => {
+        const references2 = quoted ? undefined : scanReferenceTokens2(value, line, sourceSpans);
+        return {
+            kind: 'string', value, line, quoted,
+            ...(references2 && references2.length > 0 ? { references2 } : {}),
+        };
+    },
     instant: (value, line) => ({ kind: 'instant', value, line }),
-    array: (items, line) => ({ kind: 'array', items, line }),
+    array: (items, line) => ({
+        kind: 'array', items, line,
+        ...(items.some(hasActiveReferences2) ? { references2Active: true } : {}),
+    }),
     createMapping: () => new Map(),
     createMappingWith: (key, value) => new Map([[key, value]]),
     hasMappingKey: (entries, key) => entries.has(key),
@@ -28,7 +42,16 @@ export const positionedBuilder = {
         }
         return max;
     },
-    mapping: (entries, line) => ({ kind: 'mapping', entries, line }),
+    mapping: (entries, line) => {
+        let references2Active = false;
+        for (const value of entries.values()) {
+            if (hasActiveReferences2(value)) {
+                references2Active = true;
+                break;
+            }
+        }
+        return { kind: 'mapping', entries, line, ...(references2Active ? { references2Active: true } : {}) };
+    },
 };
 /** Strips position/quoted-origin annotations, recursively — the public parseCore() projection. */
 export const toPlainValue = (v) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@limaformat/lima",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Lima frontmatter parser — LIMA Is Metadata Annotation",
   "keywords": ["frontmatter", "parser", "yaml", "markdown", "metadata"],
   "homepage": "https://limaformat.dev",
@@ -20,24 +20,25 @@
     }
   },
   "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"
-}
+  "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:cross-language": "bun run bench/cross-language.ts",
+    "bench:differential": "bun run bench/differential.ts",
+    "wordcount": "bun run scripts/wordcount.ts"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "@types/js-yaml": "^4.0.9",
+    "js-yaml": "^5.2.3",
+    "typescript": "^7.0.2",
+    "typescript-classic": "npm:typescript@^5.9.3"
+  }
 }