@limaformat/lima 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -12,6 +12,97 @@ are both frozen regardless of what this file shows.
 
 ## [Unreleased]
 
+## [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
+consolidated result. Nine rounds of Core 1.0 errata (`1.0.1`–`1.0.9`) and
+a cross-implementation rework of References 2.0 error positions, all
+fixing behaviour the specifications already required. The npm package
+version advances to `0.4.0` to align with the Rust crate and Go module.
+The Lima Core 1.0 and References 2.0 specification texts gain only
+non-normative clarifications (§5, §5.2, §6.1.3, error-api); no rule
+changed.
+
+The shared conformance corpus grows to 211 Core and 136 References 2.0
+cases (from 149 / 119). The frozen 1.0.0 baseline of 149 Core cases is
+byte-identical; every added case carries a `since` revision marker.
+
+### Changed
+
+- An unquoted key must now match the Core §5.1 grammar
+  (`[A-Za-z0-9_][A-Za-z0-9_:-]*`) in **every** mapping context — top level,
+  nested, and flow. Keys such as `a.b`, `($x)`, `${x}`, or a key with a
+  leading non-ASCII space are no longer recognised; the line or item is
+  skipped in both strict and non-strict mode. Previously some of these
+  were accepted as literal keys in nested or flow mappings. (errata 1.0.5)
+- `parseCore` no longer builds reference-position metadata — that work is
+  now confined to the `parse` / positioned path — restoring the Core hot
+  path to its pre-errata baseline.
+
+### Fixed
+
+- `|` literal block scalars: recognised under a nested key, not only at the
+  top level; the scalar now ends at the first line indented to the key's
+  column or less, so a dedented comment or freetext is no longer absorbed;
+  indentation trimming removes exactly the smallest common indent (no
+  `key.length + 2` cap, a one-space indent is handled). (errata 1.0.1)
+- Quoted-string lexing is escape-aware in every value position: `"a\""` and
+  `'a\''` are unterminated in flow and block contexts too; `"a: b": v` and
+  `"say \"hi\"": v` parse as a single key; an unquoted key with interior
+  whitespace makes its line or item unrecognised in nested and flow
+  mappings, matching the top level. (errata 1.0.2)
+- A comment line between a bare key and its nested block no longer drops
+  the block. (errata 1.0.3)
+- A block-sequence item's first bare key now aligns following sibling keys
+  at the key's own column, not the dash column. (errata 1.0.6)
+- A raw U+000A inside a quoted key is rejected (Core §15.6), the `\n`
+  escape is unaffected, and — corrected in 1.0.9 — U+2028 / U+2029 are
+  ordinary quoted-key characters (§15.6 excludes only U+000A), matching
+  the Rust and Go implementations. (errata 1.0.8 / 1.0.9)
+- A block-scalar line whose only content is a non-ASCII space (U+00A0,
+  U+2028, …) is no longer treated as blank in the Go implementation; it
+  ends the scalar, matching TypeScript and Rust. (errata 1.0.9)
+- `\#` is collapsed to `#` only in unquoted values (Core §6.1.4). Inside
+  `"..."` it is now an unknown escape — non-strict keeps the backslash,
+  strict throws `INVALID_ESCAPE` — and inside `'...'` a literal backslash.
+  (errata 1.0.9)
+- The whitespace between a value and a trailing `#` comment is stripped
+  with the full project whitespace set in all three implementations, so a
+  U+00A0 or U+FEFF before a comment no longer stays attached to the value
+  (Go and Rust previously used narrower sets). U+0085 is not in the set
+  and remains literal content. (errata 1.0.9)
+- References 2.0 error positions: `line` and `column` are the physical
+  position in the original source text, counted in Unicode code points and
+  identical across the TypeScript, Rust, and Go implementations.
+  Leading-tab expansion and `\#` escapes no longer shift a later token's
+  reported column — including inside a flow `[...]` / `{...}`.
+  `LimaError.column` is now populated on reference errors.
+- References 2.0 diagnostic ordering: an unresolved-reference or structural
+  error is attributed to the earliest participating source token,
+  including across flow-collection elements on one line and across a second
+  pure-reference copy.
+
 ## [0.3.1] — 2026-08-12
 
 ### Fixed

package/dist/block-scalar.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Core §6.1.5 literal block scalars (`|`). Shared by the top-level key path
+ * (`core.ts`) and the nested block path (`block.ts`): §6.1.5 defines block
+ * scalar extent generically ("indentation strictly greater than the
+ * indentation of the key that introduced the scalar"), with no top-level
+ * restriction, so both call sites must agree byte for byte.
+ *
+ * Generic over the output representation via `ValueBuilder` (see
+ * `builder.ts`), like the rest of the Core grammar.
+ */
+import { type ParseContext } from './normalize.js';
+import type { ValueBuilder } from './builder.js';
+/** Leading U+0020 count. "Indentation" in §6.1.5 is spaces, measured from column 0. */
+export declare const leadingSpaces: (line: string) => number;
+/** Index right after the last non-space character — the `trimEnd()` boundary, without allocating. */
+export declare const trailingSpaceEnd: (line: string) => number;
+/**
+ * Builds a `|` block scalar value.
+ *
+ * `bodyLines` are the physical source lines *after* the `|` line, each in
+ * its original column-0 form (trailing whitespace is stripped here).
+ * `keyIndent` is the indentation of the key that introduced the scalar
+ * (0 at the top level). `pipeLine` is the 1-based line number of the `|`
+ * line, so `bodyLines[i]` is at `pipeLine + 1 + i`.
+ *
+ * Returns the joined value plus how many of `bodyLines` the scalar
+ * consumed — a caller iterating physical lines resumes past that; a caller
+ * that already sliced the range to the scalar can ignore it.
+ */
+export declare const buildBlockScalar: <V, M>(bodyLines: string[], keyIndent: number, pipeLine: number, ctx: ParseContext, builder: ValueBuilder<V, M>) => {
+    value: V;
+    consumed: number;
+};

package/dist/block-scalar.js

@@ -0,0 +1,109 @@
+/**
+ * Core §6.1.5 literal block scalars (`|`). Shared by the top-level key path
+ * (`core.ts`) and the nested block path (`block.ts`): §6.1.5 defines block
+ * scalar extent generically ("indentation strictly greater than the
+ * indentation of the key that introduced the scalar"), with no top-level
+ * restriction, so both call sites must agree byte for byte.
+ *
+ * Generic over the output representation via `ValueBuilder` (see
+ * `builder.ts`), like the rest of the Core grammar.
+ */
+import { LString } from './value.js';
+import { checkScalarLimit } from './normalize.js';
+/** Leading U+0020 count. "Indentation" in §6.1.5 is spaces, measured from column 0. */
+export const leadingSpaces = (line) => {
+    let i = 0;
+    while (i < line.length && line.charCodeAt(i) === 32)
+        i++;
+    return i;
+};
+/** Index right after the last non-space character — the `trimEnd()` boundary, without allocating. */
+export const trailingSpaceEnd = (line) => {
+    let i = line.length;
+    while (i > 0 && line.charCodeAt(i - 1) === 32)
+        i--;
+    return i;
+};
+/**
+ * Builds a `|` block scalar value.
+ *
+ * `bodyLines` are the physical source lines *after* the `|` line, each in
+ * its original column-0 form (trailing whitespace is stripped here).
+ * `keyIndent` is the indentation of the key that introduced the scalar
+ * (0 at the top level). `pipeLine` is the 1-based line number of the `|`
+ * line, so `bodyLines[i]` is at `pipeLine + 1 + i`.
+ *
+ * Returns the joined value plus how many of `bodyLines` the scalar
+ * consumed — a caller iterating physical lines resumes past that; a caller
+ * that already sliced the range to the scalar can ignore it.
+ */
+export const buildBlockScalar = (bodyLines, keyIndent, pipeLine, ctx, builder) => {
+    // Extent (§6.1.5): a line belongs to the scalar iff its indentation is
+    // strictly greater than the introducing key's. Empty lines between
+    // content lines belong regardless of indentation; the first non-empty
+    // line dedented to the key's column or less ends the scalar, `#` lines
+    // included.
+    let consumed = bodyLines.length;
+    for (let i = 0; i < bodyLines.length; i++) {
+        const bl = bodyLines[i];
+        const ind = leadingSpaces(bl);
+        if (ind === bl.length)
+            continue; // empty (blank or whitespace-only)
+        if (ind <= keyIndent) {
+            consumed = i;
+            break;
+        }
+    }
+    const lines = consumed === bodyLines.length ? bodyLines : bodyLines.slice(0, consumed);
+    // Content indentation (§6.1.5): the smallest number of leading spaces
+    // among all non-empty content lines, measured from column 0, removed
+    // uniformly from every line.
+    let minIndent = Infinity;
+    for (const l of lines) {
+        const ind = leadingSpaces(l);
+        if (ind === l.length)
+            continue; // empty lines do not participate
+        if (ind < minIndent)
+            minIndent = ind;
+    }
+    const trimAmt = isFinite(minIndent) ? minIndent : 0;
+    // dedent + `^^` continuation strip + trailing-space trim collapse into a
+    // single slice() per line. leadingSpaces/trailingSpaceEnd avoid the
+    // temporary strings trim()/trimStart()/trimEnd() would allocate.
+    const merged = [];
+    for (let i = 0; i < lines.length; i++) {
+        const l = lines[i];
+        const lineLen = l.length;
+        let start = trimAmt < lineLen ? trimAmt : lineLen;
+        const isContinuation = l.charCodeAt(start) === 94 && l.charCodeAt(start + 1) === 94; // ^^
+        if (isContinuation)
+            start += 2;
+        let end = trailingSpaceEnd(l);
+        if (end < start)
+            end = start;
+        const content = l.slice(start, end);
+        if (isContinuation && merged.length > 0) {
+            if (content)
+                merged[merged.length - 1] += ' ' + content;
+        }
+        else {
+            merged.push(content);
+        }
+    }
+    // Trailing content (§6.1.5): all trailing empty lines are stripped.
+    while (merged.length > 0 && merged[merged.length - 1] === '')
+        merged.pop();
+    const joined = merged.join('\n');
+    checkScalarLimit(LString(joined), pipeLine);
+    // A token's physical `(line, offset)` is read from the original body
+    // lines (column-0 form), not reconstructed from the dedented/`^^`-merged
+    // `joined` string — References 2.0 §2.4. `lines` are at physical lines
+    // `pipeLine + 1 .. pipeLine + consumed` (0-based indices `pipeLine ..`).
+    return {
+        value: builder.string(joined, pipeLine + 1, false, {
+            raw: lines.join('\n'), line: pipeLine + 1, col: 0,
+            tabAdjust: ctx.tabAdjust?.slice(pipeLine, pipeLine + consumed),
+        }),
+        consumed,
+    };
+};

package/dist/block.js

@@ -8,22 +8,72 @@
  * reference-shape check — that error class cannot occur here since Core
  * never resolves a reference in the first place).
  */
-import { LString } from './value.js';
-import { checkKeyLength, checkDuplicateKey, checkScalarLimit, NESTING_DEPTH_LIMIT } from './normalize.js';
-import { stripKeyQuotes, unescapeDQ, stripComment, parseQuotedOrTyped, } from './scalars.js';
+import { checkKeyLength, checkDuplicateKey, NESTING_DEPTH_LIMIT } from './normalize.js';
+import { stripKeyQuotes, stripComment, stripCommentKeepEscapes, parseQuotedOrTyped, closingQuoteIndex, isValidKey, positionedBuilder, } from './scalars.js';
 import { parseFlowMapping, parseFlowOrScalarValue } from './flow.js';
+import { buildBlockScalar } from './block-scalar.js';
 import { LimaError } from './errors.js';
 import { isTrimWhitespace } from './chars.js';
 import { BlockCursor } from './block-cursor.js';
 const DASH_PREFIX_RE = /^-\s+/;
+/**
+ * A key's inline value text. If it is exactly `|`, consume the following
+ * physical lines belonging to the Core §6.1.5 block scalar introduced by a
+ * key at `keyIndent` and return the scalar; the cursor is left on the first
+ * line past the scalar. Otherwise parse `raw` as an ordinary inline value
+ * and advance one line. §6.1.5 places no top-level restriction on block
+ * scalars, so this is the same primitive `core.ts` uses at the top level.
+ */
+/** Length of the `- ` (dash + whitespace) prefix on the cursor's current line. */
+const dashPrefixLen = (cursor) => {
+    const start = cursor.contentStart, end = cursor.lineEnd;
+    if (start + 1 === end)
+        return 1;
+    let content = start + 1;
+    while (content < end && isTrimWhitespace(cursor.source.charCodeAt(content)))
+        content++;
+    return content - start;
+};
+/** Codepoints of leading whitespace on `s` — for a value's column within its line. */
+const leadingWsLen = (s) => s.length - s.trimStart().length;
+/** A value's physical `raw` for References 2.0 token positions: a trailing
+ * `#` comment removed (its `${…}`-shaped text is not part of the value, so
+ * must not be scanned), but `\#` kept as written (§2.4 — a `\#` before a
+ * token still occupies two source columns). */
+const physicalRaw = (s) => (s.includes('#') ? stripCommentKeepEscapes(s) : s);
+/** The `ReferenceSource` for an inline value on line `keyLine` at column
+ * `valueCol`; `rawUndecoded` is the value text before comment stripping /
+ * `\#` collapse (so a `\#` before a token doesn't shift its column). */
+const inlineSource = (wantSource, ctx, keyLine, valueCol, rawUndecoded) => wantSource ? ({
+    raw: physicalRaw(rawUndecoded), line: keyLine, col: valueCol,
+    tabAdjust: ctx.tabAdjust ? [ctx.tabAdjust[keyLine - 1] ?? 0] : undefined,
+}) : undefined;
+const inlineOrBlockScalar = (raw, keyIndent, keyLine, valueCol, rawUndecoded, cursor, ctx, builder) => {
+    const wantSource = builder === positionedBuilder;
+    if (raw !== '|') {
+        const value = parseFlowOrScalarValue(raw, ctx, keyLine, builder, inlineSource(wantSource, ctx, keyLine, valueCol, rawUndecoded));
+        cursor.next();
+        return value;
+    }
+    cursor.next(); // past the `key: |` line
+    const bodyLines = [];
+    while (cursor.valid) {
+        if (!cursor.empty && cursor.asciiIndent <= keyIndent)
+            break;
+        bodyLines.push(cursor.source.slice(cursor.lineStart, cursor.lineEnd));
+        cursor.next();
+    }
+    return buildBlockScalar(bodyLines, keyIndent, keyLine, ctx, builder).value;
+};
 export const findKeySep = (s) => {
     const first = s.charCodeAt(0);
     if (first === 39 || first === 34) {
-        let i = 1;
-        while (i < s.length && s.charCodeAt(i) !== first)
-            i++;
-        if (s.charCodeAt(i + 1) === 58 && s.charCodeAt(i + 2) === 32)
-            return i + 1;
+        // §5.1: the `: ` separator must sit outside the quoted key, so scan
+        // past its closing quote first. Double-quoted keys honour `\"`; a
+        // single-quoted key is literal (§5.2), so its first `'` closes.
+        const close = closingQuoteIndex(s, false);
+        if (close !== -1 && s.charCodeAt(close + 1) === 58 && s.charCodeAt(close + 2) === 32)
+            return close + 1;
         return -1;
     }
     return s.indexOf(': ');
@@ -52,6 +102,19 @@ const trimSlice = (source, start, end) => {
     return source.slice(start, end);
 };
 const cursorContent = (cursor) => cursor.source.slice(cursor.contentStart, cursor.lineEnd);
+/**
+ * Core §4 rule 7 / §6.1.3: comment lines (first non-whitespace character
+ * `#`) do not affect base indentation and are skipped — including in the
+ * lookahead that decides whether a bare key (`key:` with no inline value)
+ * has any nested block at all. Advancing past a comment here, not only a
+ * blank line, keeps that pre-check consistent with the same skip already
+ * applied once inside an established block (`parseCursorBlock`'s own
+ * `cursor.empty || cursor.firstCode === 35` check at the top of its loop).
+ */
+const skipEmptyAndCommentLines = (cursor) => {
+    while (cursor.valid && (cursor.empty || cursor.firstCode === 35))
+        cursor.next();
+};
 const cursorAfterDash = (cursor) => {
     const start = cursor.contentStart;
     const end = cursor.lineEnd;
@@ -66,6 +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;
     let items = null;
     let entries = null;
     let pendingItem = null;
@@ -82,22 +146,30 @@ const parseCursorBlock = (cursor, baseIndent, ctx, baseLine, builder) => {
         if (indent > baseIndent) {
             const trimmed = cursorContent(cursor);
             if (items !== null && pendingItem !== null) {
-                const colonPos = findKeySep(trimmed);
-                if (colonPos !== -1) {
-                    const key = stripKeyQuotes(trimSlice(trimmed, 0, colonPos));
-                    checkKeyLength(key, () => line);
-                    let raw = trimSlice(trimmed, colonPos + 2, trimmed.length);
-                    if (raw.includes('#'))
-                        raw = stripComment(raw);
-                    builder.setMapping(pendingItem, key, parseFlowOrScalarValue(raw, ctx, line, builder));
+                const bareKey = trimmed.charCodeAt(trimmed.length - 1) === 58;
+                const colonPos = bareKey && trimmed.indexOf(' ') === -1 ? -1 : findKeySep(trimmed);
+                const keyRaw = colonPos !== -1
+                    ? trimSlice(trimmed, 0, colonPos)
+                    : bareKey ? trimSlice(trimmed, 0, trimmed.length - 1) : '';
+                if (keyRaw !== '' && !isValidKey(keyRaw)) {
+                    // §5.1: not a usable key — skipped in both modes, as at the top level.
                     cursor.next();
                 }
-                else if (trimmed.endsWith(':')) {
-                    const key = stripKeyQuotes(trimSlice(trimmed, 0, trimmed.length - 1));
-                    checkKeyLength(key, () => line);
+                else if (colonPos !== -1) {
+                    const key = stripKeyQuotes(keyRaw, ctx.strict, line);
+                    checkKeyLength(key, line);
+                    const rawUndecoded = trimSlice(trimmed, colonPos + 2, trimmed.length);
+                    let raw = rawUndecoded;
+                    if (raw !== '|' && raw.includes('#'))
+                        raw = stripComment(raw);
+                    const valueCol = wantSource ? cursor.indent + colonPos + 2 + leadingWsLen(trimmed.slice(colonPos + 2)) : 0;
+                    builder.setMapping(pendingItem, key, inlineOrBlockScalar(raw, indent, line, valueCol, rawUndecoded, cursor, ctx, builder));
+                }
+                else if (bareKey) {
+                    const key = stripKeyQuotes(keyRaw, ctx.strict, line);
+                    checkKeyLength(key, line);
                     cursor.next();
-                    while (cursor.valid && cursor.empty)
-                        cursor.next();
+                    skipEmptyAndCommentLines(cursor);
                     if (cursor.valid && cursor.indent > indent) {
                         const nested = parseCursorBlock(cursor, cursor.indent, ctx, baseLine, builder);
                         builder.setMapping(pendingItem, key, nested ?? builder.null(line));
@@ -134,17 +206,23 @@ const parseCursorBlock = (cursor, baseIndent, ctx, baseLine, builder) => {
                 cursor.next();
                 continue;
             }
-            let afterDash = cursorAfterDash(cursor);
+            const afterDashRaw = cursorAfterDash(cursor);
+            let afterDash = afterDashRaw;
             if (afterDash.includes('#'))
                 afterDash = stripComment(afterDash);
+            const afterDashCol = wantSource ? cursor.indent + dashPrefixLen(cursor) : 0;
+            const afterDashTab = wantSource && ctx.tabAdjust ? [ctx.tabAdjust[line - 1] ?? 0] : undefined;
+            const dashSource = wantSource ? ({
+                raw: physicalRaw(afterDashRaw), line, col: afterDashCol, tabAdjust: afterDashTab,
+            }) : undefined;
             const first = afterDash.charCodeAt(0);
             if (first !== 34 && first !== 39 && first !== 45 && first !== 123 &&
                 afterDash.indexOf(': ') === -1 && !afterDash.endsWith(':')) {
-                items.push(parseQuotedOrTyped(afterDash, ctx, line, false, builder));
+                items.push(parseQuotedOrTyped(afterDash, ctx, line, builder, dashSource));
                 cursor.next();
                 continue;
             }
-            const flowMap = parseFlowMapping(afterDash, ctx, line, builder);
+            const flowMap = parseFlowMapping(afterDash, ctx, line, builder, dashSource);
             const colonPos = findKeySep(afterDash);
             if (flowMap !== null) {
                 items.push(flowMap);
@@ -166,53 +244,60 @@ const parseCursorBlock = (cursor, baseIndent, ctx, baseLine, builder) => {
                     cursor.next();
                 }
             }
-            else if (colonPos !== -1) {
-                const keyFirst = afterDash.charCodeAt(0);
-                const keyLast = afterDash.charCodeAt(colonPos - 1);
-                const keyRaw = keyFirst > 0x20 && keyFirst < 0x7f && keyLast > 0x20 && keyLast < 0x7f
-                    ? afterDash.slice(0, colonPos) : trimSlice(afterDash, 0, colonPos);
-                const key = keyFirst === 34 || keyFirst === 39 ? stripKeyQuotes(keyRaw) : keyRaw;
-                checkKeyLength(key, () => line);
+            else if (colonPos !== -1 && isValidKey(trimSlice(afterDash, 0, colonPos))) {
+                const keyRaw = trimSlice(afterDash, 0, colonPos);
+                const key = stripKeyQuotes(keyRaw, ctx.strict, line);
+                checkKeyLength(key, line);
                 const valueStart = colonPos + 2;
                 const valueFirst = afterDash.charCodeAt(valueStart);
                 const valueLast = afterDash.charCodeAt(afterDash.length - 1);
                 const raw = valueFirst > 0x20 && valueFirst < 0x7f && valueLast > 0x20 && valueLast < 0x7f
                     ? afterDash.slice(valueStart) : trimSlice(afterDash, valueStart, afterDash.length);
-                pendingItem = builder.createMappingWith(key, parseFlowOrScalarValue(raw, ctx, line, builder));
-                cursor.next();
+                // The key sits after `- `, two columns past the dash.
+                const valueCol = wantSource ? afterDashCol + valueStart + leadingWsLen(afterDash.slice(valueStart)) : 0;
+                pendingItem = builder.createMappingWith(key, inlineOrBlockScalar(raw, baseIndent + 2, line, valueCol, wantSource ? afterDashRaw.slice(valueStart) : raw, cursor, ctx, builder));
                 while (cursor.valid && cursor.indent > baseIndent) {
                     const continuationLine = baseLine + cursor.lineIndex;
-                    const start = cursor.contentStart, end = cursor.lineEnd;
-                    const cfirst = cursor.source.charCodeAt(start);
-                    if (cfirst === 34 || cfirst === 39 || cfirst === 35)
+                    const ckeyIndent = cursor.asciiIndent;
+                    const cfirst = cursor.source.charCodeAt(cursor.contentStart);
+                    if (cfirst === 35)
+                        break;
+                    const contLine = trimSlice(cursor.source, cursor.contentStart, cursor.lineEnd);
+                    const csep = findKeySep(contLine);
+                    if (csep === -1)
                         break;
-                    const sep = cursor.source.indexOf(': ', start);
-                    if (sep === -1 || sep >= end)
+                    const ckeyRaw = trimSlice(contLine, 0, csep);
+                    if (!isValidKey(ckeyRaw))
                         break;
-                    const keyLast = cursor.source.charCodeAt(sep - 1);
-                    const ckey = cfirst > 0x20 && cfirst < 0x7f && keyLast > 0x20 && keyLast < 0x7f
-                        ? cursor.source.slice(start, sep) : trimSlice(cursor.source, start, sep);
+                    const ckey = stripKeyQuotes(ckeyRaw, ctx.strict, continuationLine);
                     if (!ckey)
                         break;
-                    checkKeyLength(ckey, () => continuationLine);
-                    const valueStart = sep + 2;
-                    const valueFirst = cursor.source.charCodeAt(valueStart);
-                    const valueLast = cursor.source.charCodeAt(end - 1);
-                    let value = valueFirst > 0x20 && valueFirst < 0x7f && valueLast > 0x20 && valueLast < 0x7f
-                        ? cursor.source.slice(valueStart, end) : trimSlice(cursor.source, valueStart, end);
-                    if (value.includes('#'))
+                    checkKeyLength(ckey, continuationLine);
+                    const valueUndecoded = trimSlice(contLine, csep + 2, contLine.length);
+                    let value = valueUndecoded;
+                    if (value !== '|' && value.includes('#'))
                         value = stripComment(value);
-                    builder.setMapping(pendingItem, ckey, parseFlowOrScalarValue(value, ctx, continuationLine, builder));
-                    cursor.next();
+                    // contLine starts exactly at contentStart (no leading trim), so
+                    // the value's column is the indent plus its offset in contLine.
+                    const cValueCol = wantSource ? cursor.indent + csep + 2 + leadingWsLen(contLine.slice(csep + 2)) : 0;
+                    builder.setMapping(pendingItem, ckey, inlineOrBlockScalar(value, ckeyIndent, continuationLine, cValueCol, valueUndecoded, cursor, ctx, builder));
                 }
             }
-            else if (afterDash.endsWith(':')) {
-                const key = stripKeyQuotes(trimSlice(afterDash, 0, afterDash.length - 1));
-                checkKeyLength(key, () => line);
+            else if (afterDash.endsWith(':') && isValidKey(trimSlice(afterDash, 0, afterDash.length - 1))) {
+                const key = stripKeyQuotes(trimSlice(afterDash, 0, afterDash.length - 1), ctx.strict, line);
+                checkKeyLength(key, line);
+                // §7.1 rule 3 / §7.2: sibling keys of an object item align at
+                // the column of the first key *after* `- `; a nested block
+                // must be indented deeper than that column, not merely deeper
+                // than the item's dash. A line at the key's own column is the
+                // next sibling key, so the bare key is `null`.
+                let keyColumn = cursor.contentStart + 1;
+                while (keyColumn < cursor.lineEnd && isTrimWhitespace(cursor.source.charCodeAt(keyColumn)))
+                    keyColumn++;
+                keyColumn -= cursor.lineStart;
                 cursor.next();
-                while (cursor.valid && cursor.empty)
-                    cursor.next();
-                if (cursor.valid && cursor.indent > baseIndent) {
+                skipEmptyAndCommentLines(cursor);
+                if (cursor.valid && cursor.indent > keyColumn) {
                     const nested = parseCursorBlock(cursor, cursor.indent, ctx, baseLine, builder);
                     pendingItem = builder.createMappingWith(key, nested ?? builder.null(line));
                 }
@@ -220,15 +305,9 @@ const parseCursorBlock = (cursor, baseIndent, ctx, baseLine, builder) => {
                     pendingItem = builder.createMappingWith(key, builder.null(line));
             }
             else {
-                const q = afterDash.charCodeAt(0);
-                if ((q === 34 || q === 39) && afterDash.charCodeAt(afterDash.length - 1) === q) {
-                    const inner = afterDash.slice(1, -1);
-                    const value = q === 34 ? unescapeDQ(inner, ctx.strict, line) : inner.replace(/\\'/g, "'");
-                    checkScalarLimit(LString(value), line);
-                    items.push(builder.string(value, line, true));
-                }
-                else
-                    items.push(parseQuotedOrTyped(afterDash, ctx, line, false, builder));
+                // A quoted-or-typed scalar item — parseQuotedOrTyped enforces
+                // §10.1's unterminated / trailing-content strict checks.
+                items.push(parseQuotedOrTyped(afterDash, ctx, line, builder, dashSource));
                 cursor.next();
             }
         }
@@ -241,30 +320,39 @@ const parseCursorBlock = (cursor, baseIndent, ctx, baseLine, builder) => {
                 cursor.next();
                 continue;
             }
-            const colonPos = findKeySep(trimmed);
-            if (colonPos !== -1) {
+            const bareKey = trimmed.charCodeAt(trimmed.length - 1) === 58;
+            const colonPos = bareKey && trimmed.indexOf(' ') === -1 ? -1 : findKeySep(trimmed);
+            const keyRaw = colonPos !== -1
+                ? trimSlice(trimmed, 0, colonPos)
+                : bareKey ? trimSlice(trimmed, 0, trimmed.length - 1) : '';
+            if (keyRaw !== '' && !isValidKey(keyRaw)) {
+                // §5.1: not a usable key — unrecognised line, skipped in both
+                // modes (§10's strict list is closed and does not cover this).
+                cursor.next();
+            }
+            else if (colonPos !== -1) {
                 if (entries === null)
                     entries = builder.createMapping();
-                const key = stripKeyQuotes(trimSlice(trimmed, 0, colonPos));
-                checkKeyLength(key, () => line);
+                const key = stripKeyQuotes(keyRaw, ctx.strict, line);
+                checkKeyLength(key, line);
                 if (ctx.strict || ctx.onWarning !== undefined)
                     checkDuplicateKey(builder.hasMappingKey(entries, key), key, line, ctx);
-                let raw = trimSlice(trimmed, colonPos + 2, trimmed.length);
-                if (raw.includes('#'))
+                const rawUndecoded = trimSlice(trimmed, colonPos + 2, trimmed.length);
+                let raw = rawUndecoded;
+                if (raw !== '|' && raw.includes('#'))
                     raw = stripComment(raw);
-                builder.setMapping(entries, key, parseFlowOrScalarValue(raw, ctx, line, builder));
-                cursor.next();
+                const valueCol = wantSource ? cursor.indent + colonPos + 2 + leadingWsLen(trimmed.slice(colonPos + 2)) : 0;
+                builder.setMapping(entries, key, inlineOrBlockScalar(raw, baseIndent, line, valueCol, rawUndecoded, cursor, ctx, builder));
             }
-            else if (trimmed.endsWith(':')) {
+            else if (bareKey) {
                 if (entries === null)
                     entries = builder.createMapping();
-                const key = stripKeyQuotes(trimSlice(trimmed, 0, trimmed.length - 1));
-                checkKeyLength(key, () => line);
+                const key = stripKeyQuotes(keyRaw, ctx.strict, line);
+                checkKeyLength(key, line);
                 if (ctx.strict || ctx.onWarning !== undefined)
                     checkDuplicateKey(builder.hasMappingKey(entries, key), key, line, ctx);
                 cursor.next();
-                while (cursor.valid && cursor.empty)
-                    cursor.next();
+                skipEmptyAndCommentLines(cursor);
                 if (cursor.valid && cursor.indent > baseIndent) {
                     const nested = parseCursorBlock(cursor, cursor.indent, ctx, baseLine, builder);
                     builder.setMapping(entries, key, nested ?? builder.null(line));
@@ -289,8 +377,7 @@ export const parseBlockRange = (source, start, end, ctx, baseLine, builder, dept
     const cursor = new BlockCursor(source, start, end);
     if (!cursor.next())
         return null;
-    while (cursor.valid && cursor.empty)
-        cursor.next();
+    skipEmptyAndCommentLines(cursor);
     if (!cursor.valid)
         return null;
     const baseIndent = cursor.asciiIndent;

package/dist/builder.d.ts

@@ -24,14 +24,19 @@
  * is compile-time-only: generics are erased, so the emitted JS — and
  * therefore performance — is identical either way, verified by benchmark.
  */
+import type { ReferenceSource } from './reference-tokens2.js';
 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, sourceSpans?: StringSourceSpan[]): V;
+    /**
+     * `source` (when given, for unquoted strings that may hold References 2.0
+     * tokens) carries the physical position needed to attribute those tokens
+     * to a real `(line, offset)` in the source text (§2.4). `nativeBuilder`
+     * ignores it.
+     */
+    string(value: string, line: number, quoted: boolean, source?: ReferenceSource): V;
     instant(value: Date, line: number): V;
     array(items: V[], line: number): V;
     createMapping(): M;
@@ -41,9 +46,3 @@ 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;
-};