@limaformat/lima 0.7.1 → 0.8.1

package/dist/builder.d.ts

@@ -25,7 +25,25 @@
  * therefore performance — is identical either way, verified by benchmark.
  */
 import type { ReferenceSource } from './reference-tokens2.js';
+/**
+ * Reader events for structural editor output. All positions are UTF-16 offsets
+ * in the normalized source; ends are exclusive, separator is the colon and
+ * line is one-based. A zero-width key denotes a tolerant entry without a
+ * physical separator; its value's events are still balanced but not emitted.
+ * Readers select reporting functions once on entry. Native/References builders
+ * never set this hook, so their key loops do no optional-sink checks.
+ */
+export interface SourcePositions {
+    key(key: string, start: number, end: number, separator: number, line: number): void;
+    comment(start: number, end: number): void;
+    /**
+     * On failure, discard key events left unfinished by `read`. Return `fallback`
+     * for non-resource LimaErrors; rethrow resource-limit and non-Lima errors.
+     */
+    recover<T>(read: () => T, fallback: T): T;
+}
 export interface ValueBuilder<V, M = Map<string, V>> {
+    readonly sourcePositions?: SourcePositions;
     /** Whether scalar builders need physical source anchors for editor positions. */
     readonly positions?: boolean;
     null(line: number): V;

package/dist/flow.d.ts

@@ -1,8 +1,28 @@
 /** Core §15.8 flow collections: `[...]` sequences and `{...}` mappings. */
 import { type ParseContext } from './normalize.js';
-import type { ValueBuilder } from './builder.js';
+import type { SourcePositions, ValueBuilder } from './builder.js';
 import type { ReferenceSource } from './reference-tokens2.js';
-export declare const parseFlowSequence: <V, M>(val: string, ctx: ParseContext, line: number, builder: ValueBuilder<V, M>, source?: ReferenceSource) => V[] | null;
-export declare const parseFlowMapping: <V, M>(val: string, ctx: ParseContext, line: number, builder: ValueBuilder<V, M>, source?: ReferenceSource) => V | null;
+/** Stateful comma-item cursor over a flow container's original string. */
+export declare class FlowCursor {
+    private readonly source;
+    private readonly end;
+    itemStart: number;
+    itemEnd: number;
+    private nextStart;
+    private done;
+    constructor(source: string, start: number, end: number);
+    next(): boolean;
+    get isLast(): boolean;
+}
+export declare const parseFlowSequence: <V, M>(val: string, ctx: ParseContext, line: number, builder: ValueBuilder<V, M>, source?: ReferenceSource, offset?: number) => V[] | null;
+/**
+ * Index of the key/value `: ` separator within a flow-mapping item — the
+ * first `: ` that is not inside a quoted key (§5.1). Returns -1 when the
+ * item has no separator.
+ */
+export declare const flowItemSeparator: (val: string, start: number, end: number) => number;
+export declare const parseFlowMapping: <V, M>(val: string, ctx: ParseContext, line: number, builder: ValueBuilder<V, M>, source?: ReferenceSource, offset?: number) => V | null;
 /** Parses a value that may be a flow collection, without probing both flow parsers for ordinary scalars. */
-export declare const parseFlowOrScalarValue: <V, M>(raw: string, ctx: ParseContext, line: number, builder: ValueBuilder<V, M>, source?: ReferenceSource) => V;
+export declare const parseFlowOrScalarValue: <V, M>(raw: string, ctx: ParseContext, line: number, builder: ValueBuilder<V, M>, source?: ReferenceSource, offset?: number) => V;
+/** Select recovery once, outside the block reader's key loop. */
+export declare const flowValueReader: (positions?: SourcePositions) => typeof parseFlowOrScalarValue;

package/dist/flow.js

@@ -71,7 +71,7 @@ const trimEnd = (source, start, end) => {
     return end;
 };
 /** Stateful comma-item cursor over a flow container's original string. */
-class FlowCursor {
+export class FlowCursor {
     source;
     end;
     itemStart = 0;
@@ -118,7 +118,7 @@ class FlowCursor {
 }
 const isNestedFlowConstruct = (item) => (item.charCodeAt(0) === 91 && item.charCodeAt(item.length - 1) === 93) ||
     (item.charCodeAt(0) === 123 && item.charCodeAt(item.length - 1) === 125);
-export const parseFlowSequence = (val, ctx, line, builder, source) => {
+export const parseFlowSequence = (val, ctx, line, builder, source, offset = 0) => {
     if (val.charCodeAt(0) !== 91 || val.charCodeAt(val.length - 1) !== 93)
         return null;
     const innerStart = trimStart(val, 1, val.length - 1);
@@ -147,7 +147,7 @@ export const parseFlowSequence = (val, ctx, line, builder, source) => {
             });
         }
         if (item.charCodeAt(0) === 123 && item.charCodeAt(item.length - 1) === 125) {
-            const nested = parseFlowMapping(item, ctx, line, builder, elementSource(source, val, start, end));
+            const nested = parseFlowMapping(item, ctx, line, builder, elementSource(source, val, start, end), offset + start);
             if (nested !== null) {
                 items.push(nested);
                 continue;
@@ -162,7 +162,7 @@ export const parseFlowSequence = (val, ctx, line, builder, source) => {
  * first `: ` that is not inside a quoted key (§5.1). Returns -1 when the
  * item has no separator.
  */
-const flowItemSeparator = (val, start, end) => {
+export const flowItemSeparator = (val, start, end) => {
     let scan = start;
     if (val.charCodeAt(start) === 34 || val.charCodeAt(start) === 39) {
         // §5.2: a single-quoted key is literal, so its first `'` closes.
@@ -174,11 +174,18 @@ const flowItemSeparator = (val, start, end) => {
     const sep = val.indexOf(': ', scan);
     return sep === -1 || sep >= end ? -1 : sep;
 };
-export const parseFlowMapping = (val, ctx, line, builder, source) => {
+const sourceKeyReader = (positions, offset) => (raw, strict, line, start, colon) => {
+    const key = stripKeyQuotes(raw, strict, line);
+    positions.key(key, offset + start, offset + start + raw.length, offset + colon, line);
+    return key;
+};
+export const parseFlowMapping = (val, ctx, line, builder, source, offset = 0) => {
     if (val.charCodeAt(0) !== 123 || val.charCodeAt(val.length - 1) !== 125)
         return null;
     const innerStart = trimStart(val, 1, val.length - 1);
     const innerEnd = trimEnd(val, innerStart, val.length - 1);
+    const positions = builder.sourcePositions;
+    const readKey = positions ? sourceKeyReader(positions, offset) : stripKeyQuotes;
     const entries = builder.createMapping();
     if (innerStart === innerEnd)
         return builder.mapping(entries, line);
@@ -209,7 +216,7 @@ export const parseFlowMapping = (val, ctx, line, builder, source) => {
             // list is closed and does not cover this — same as the top level).
             continue;
         }
-        const key = stripKeyQuotes(keyRaw, ctx.strict, line);
+        const key = readKey(keyRaw, ctx.strict, line, keyStart, colonPos);
         checkKeyLength(key, line);
         if (ctx.strict || ctx.onWarning !== undefined) {
             checkDuplicateKey(builder.hasMappingKey(entries, key), key, line, ctx);
@@ -225,19 +232,24 @@ export const parseFlowMapping = (val, ctx, line, builder, source) => {
     return builder.mapping(entries, line);
 };
 /** Parses a value that may be a flow collection, without probing both flow parsers for ordinary scalars. */
-export const parseFlowOrScalarValue = (raw, ctx, line, builder, source) => {
+export const parseFlowOrScalarValue = (raw, ctx, line, builder, source, offset = 0) => {
     const first = raw.charCodeAt(0);
     if (first === 91) {
-        const sequence = parseFlowSequence(raw, ctx, line, builder, source);
+        const sequence = parseFlowSequence(raw, ctx, line, builder, source, offset);
         if (sequence !== null)
             return builder.array(sequence, line);
         return parseScalarValue(raw, ctx, line, builder, source);
     }
     else if (first === 123) {
-        const mapping = parseFlowMapping(raw, ctx, line, builder, source);
+        const mapping = parseFlowMapping(raw, ctx, line, builder, source, offset);
         if (mapping !== null)
             return mapping;
         return parseScalarValue(raw, ctx, line, builder, source);
     }
     return parseQuotedOrTyped(raw, ctx, line, builder, source);
 };
+/** Select recovery once, outside the block reader's key loop. */
+export const flowValueReader = (positions) => positions ? sourceValueReader(positions) : parseFlowOrScalarValue;
+// Structural values are still physical text; reference anchors would rescan
+// every flow prefix for codepoint columns that the outline never uses.
+const sourceValueReader = (positions) => (raw, ctx, line, builder, _source, offset) => positions.recover(() => parseFlowOrScalarValue(raw, ctx, line, builder, undefined, offset), builder.null(line));

package/dist/index.d.ts

@@ -15,3 +15,4 @@ export { parseCore, type CoreOptions, type Diagnostic } from './core.js';
 export { LimaError, type LimaDiagnostic, type LimaDiagnosticCode } from './errors.js';
 export { parseReferences, parse, type ParseMode, type ParseOptions } from './references2.js';
 export type ReferencesOptions = import('./references2.js').ParseOptions;
+export { outline, type LimaPoint, type LimaSpan, type LimaOutlineKey, type LimaOutline } from './outline.js';

package/dist/index.js

@@ -14,3 +14,4 @@
 export { parseCore } from './core.js';
 export { LimaError } from './errors.js';
 export { parseReferences, parse } from './references2.js';
+export { outline } from './outline.js';

package/dist/outline.d.ts

@@ -0,0 +1,28 @@
+import { type LimaDiagnostic } from './errors.js';
+export interface LimaPoint {
+    /** One-based source line. */
+    readonly line: number;
+    /** One-based column in UTF-16 code units. */
+    readonly column: number;
+    /** UTF-16 code units from the start of the BOM-free input. */
+    readonly offset: number;
+}
+export interface LimaSpan {
+    readonly start: LimaPoint;
+    /** Exclusive end. */
+    readonly end: LimaPoint;
+}
+export interface LimaOutlineKey {
+    readonly key: string;
+    readonly path: readonly string[];
+    readonly span: LimaSpan;
+    readonly separator: LimaSpan;
+}
+export interface LimaOutline {
+    readonly offsetUnit: 'utf16-code-unit';
+    readonly keys: readonly LimaOutlineKey[];
+    readonly comments: readonly LimaSpan[];
+    readonly diagnostics: readonly LimaDiagnostic[];
+}
+/** Source structure for editors; references are only evaluated by the diagnostic oracle. */
+export declare function outline(frontMatter: string): LimaOutline;

package/dist/outline.js

@@ -0,0 +1,248 @@
+import { SourceBlockCursor } from './block-cursor.js';
+import { parseBlockRange, parseInlineValue } from './block.js';
+import { parseCore } from './core.js';
+import { LimaError } from './errors.js';
+import { flowValueReader } from './flow.js';
+import { NESTING_DEPTH_LIMIT, checkKeyLength, checkDuplicateKey, } from './normalize.js';
+import { parse } from './references2.js';
+import { scanKeys } from './scanner.js';
+import { stripCommentKeepEscapes, stripKeyQuotes } from './scalars.js';
+import { isBlockScalarMarker } from './structure.js';
+/** Core §3 normalization, with a boundary map back to the BOM-free physical input. */
+function normalize(input) {
+    const units = [];
+    const offsets = [];
+    let leading = true;
+    for (let i = 0; i < input.length; i++) {
+        const c = input[i];
+        if (c === '\r' || c === '\n') {
+            while (units.at(-1) === ' ') {
+                units.pop();
+                offsets.pop();
+            }
+            offsets.push(i);
+            units.push('\n');
+            if (c === '\r' && input[i + 1] === '\n')
+                i++;
+            leading = true;
+        }
+        else if (leading && c === '\t') {
+            units.push(' ', ' ');
+            offsets.push(i, i);
+        }
+        else {
+            units.push(c);
+            offsets.push(i);
+            if (c !== ' ')
+                leading = false;
+        }
+    }
+    while (units.at(-1) === ' ') {
+        units.pop();
+        offsets.pop();
+    }
+    offsets.push(input.length);
+    return { source: units.join(''), offsets };
+}
+/** Editor positions count UTF-16 units, including CRLF's two units. */
+function spanReader(input, offsets) {
+    const lines = [0];
+    const lineNumbers = new Uint32Array(input.length + 1);
+    let line = 0;
+    for (let i = 0; i < input.length; i++) {
+        lineNumbers[i] = line;
+        if (input[i] === '\r') {
+            if (input[i + 1] === '\n')
+                lineNumbers[++i] = line;
+            lines.push(i + 1);
+            line++;
+        }
+        else if (input[i] === '\n') {
+            lines.push(i + 1);
+            line++;
+        }
+    }
+    lineNumbers[input.length] = line;
+    const point = (offset) => {
+        const line = lineNumbers[offset];
+        return { line: line + 1, column: offset - lines[line] + 1, offset };
+    };
+    return (start, end) => ({ start: point(offsets[start]),
+        end: point(end > start ? offsets[end - 1] + 1 : offsets[end]) });
+}
+/** Pair each reader event with the value built immediately after it. */
+function outlineBuilder(comment) {
+    const pending = [];
+    const failed = new WeakSet();
+    const leaf = () => ({});
+    const entry = (value) => {
+        const position = pending.pop();
+        if (!position)
+            throw new Error('Lima: missing outline key position');
+        return { position, value };
+    };
+    return {
+        positions: true,
+        sourcePositions: {
+            key: (key, start, end, separator, line) => pending.push({ key, start, end, separator, line, duplicates: false }),
+            comment,
+            recover: (read, fallback) => {
+                const depth = pending.length;
+                try {
+                    const value = read();
+                    if (pending.length !== depth)
+                        throw new Error('Lima: unbalanced outline key positions');
+                    return value;
+                }
+                catch (error) {
+                    pending.length = depth;
+                    if (!(error instanceof LimaError) || error.code === 'RESOURCE_LIMIT')
+                        throw error;
+                    if (fallback !== null && typeof fallback === 'object')
+                        failed.add(fallback);
+                    return fallback;
+                }
+            },
+        },
+        null: leaf, bool: leaf, int: leaf, float: leaf, string: leaf, instant: leaf,
+        // A failed mapping value keeps its key; an unreadable whole item is skipped.
+        array: (items) => ({ items: items.filter((item) => !failed.has(item)) }), createMapping: () => [],
+        createMappingWith: (_, value) => [entry(value)],
+        hasMappingKey: () => {
+            const position = pending.at(-1);
+            if (!position)
+                throw new Error('Lima: missing outline duplicate position');
+            position.duplicates = true;
+            return false; // diagnostics are collected in source order below
+        },
+        setMapping: (entries, _, value) => { entries.push(entry(value)); },
+        mappingMaxDepth: () => 0, mapping: (entries) => ({ entries }),
+    };
+}
+/** Consume scanner ranges once; nested grammar stays in the block and flow readers. */
+function readOutline(source, builder, ctx, emit, walk) {
+    const positions = builder.sourcePositions;
+    if (!positions)
+        throw new Error('Lima: missing outline source positions');
+    const readValue = flowValueReader(positions);
+    const matches = scanKeys(source);
+    const preamble = new SourceBlockCursor(source, 0, matches[0]?.matchStart ?? source.length, positions);
+    while (preamble.next()) { }
+    const topKeys = new Set();
+    for (let i = 0; i < matches.length; i++) {
+        const match = matches[i];
+        const end = matches[i + 1]?.matchStart ?? source.length;
+        const key = match.unquoted ?? match.singleQuoted ?? stripKeyQuotes(source.slice(match.matchStart, match.sepStart - 1));
+        checkDuplicateKey(topKeys.has(key), key, match.line, ctx);
+        topKeys.add(key);
+        emit({ key, start: match.matchStart, end: match.sepStart - 1,
+            separator: match.sepStart - 1, line: match.line, duplicates: true }, []);
+        const cursor = new SourceBlockCursor(source, match.isBlock ? match.rawStart : match.matchStart, end, positions);
+        if (match.isBlock) {
+            const value = parseBlockRange(source, match.rawStart, end, ctx, match.line + 1, builder, { mayExceed: false }, cursor);
+            if (value)
+                walk(value, [key]);
+        }
+        else {
+            cursor.next();
+            cursor.excludeCommentsBefore(match.rawStart);
+            const raw = source.slice(match.rawStart, cursor.lineEnd);
+            const value = stripCommentKeepEscapes(raw).trim();
+            const column = match.rawStart - match.matchStart + raw.length - raw.trimStart().length;
+            walk(parseInlineValue(value, isBlockScalarMarker(source, match.rawStart, cursor.lineEnd), 0, match.line, column, raw, cursor, ctx, builder, readValue), [key]);
+        }
+        while (cursor.valid)
+            cursor.next();
+    }
+}
+/** Source structure for editors; references are only evaluated by the diagnostic oracle. */
+export function outline(frontMatter) {
+    const diagnostics = [];
+    const keys = [];
+    const comments = [];
+    const result = { offsetUnit: 'utf16-code-unit', keys, comments, diagnostics };
+    const diagnosticKeys = new Set();
+    const addWarning = (warning) => {
+        const identity = JSON.stringify([warning.code, warning.line, warning.key]);
+        if (diagnosticKeys.has(identity))
+            return;
+        diagnosticKeys.add(identity);
+        diagnostics.push(warning);
+    };
+    let limited = false;
+    try {
+        parse(frontMatter, { strict: true });
+    }
+    catch (error) {
+        if (!(error instanceof LimaError))
+            throw error;
+        addWarning({ ...error, message: error.message });
+        limited = error.code === 'RESOURCE_LIMIT';
+    }
+    // Also check limits beyond strict mode's first error, and collect duplicate
+    // warnings without resolving references in the tolerant structural pass.
+    try {
+        parseCore(frontMatter, { onWarning: (warning) => addWarning(warning) });
+    }
+    catch (error) {
+        if (!(error instanceof LimaError))
+            throw error;
+        if (error.code === 'RESOURCE_LIMIT') {
+            limited = true;
+            if (!diagnostics.some((d) => d.code === error.code && d.line === error.line))
+                addWarning({ ...error, message: error.message });
+        }
+    }
+    if (limited)
+        return result;
+    try {
+        const input = frontMatter.startsWith('\uFEFF') ? frontMatter.slice(1) : frontMatter;
+        const { source, offsets } = normalize(input);
+        const span = spanReader(input, offsets);
+        const ctx = { strict: false, onWarning: (warning) => addWarning(warning) };
+        const builder = outlineBuilder((start, end) => {
+            const comment = span(start, end);
+            let physicalEnd = comment.end.offset;
+            while (physicalEnd < input.length && input[physicalEnd] !== '\r' && input[physicalEnd] !== '\n')
+                physicalEnd++;
+            comments.push({ start: comment.start, end: { ...comment.end,
+                    column: comment.end.column + physicalEnd - comment.end.offset, offset: physicalEnd } });
+        });
+        const emit = (position, path) => {
+            checkKeyLength(position.key, position.line);
+            const colon = span(position.separator, position.separator + 1);
+            const separator = input[colon.end.offset] === ' '
+                ? { start: colon.start, end: { ...colon.end, column: colon.end.column + 1, offset: colon.end.offset + 1 } }
+                : colon;
+            keys.push({ key: position.key, path: [...path, position.key], span: span(position.start, position.end), separator });
+        };
+        const walk = (value, path, depth = 0) => {
+            if (value.entries || value.items)
+                depth++;
+            if (depth > NESTING_DEPTH_LIMIT)
+                throw new LimaError({ code: 'RESOURCE_LIMIT', line: 1,
+                    message: `Lima: nesting depth exceeds maximum of ${NESTING_DEPTH_LIMIT} at line 1` });
+            const seen = new Set();
+            for (const { position, value: child } of value.entries ?? []) {
+                if (position.start === position.end)
+                    continue;
+                if (position.duplicates)
+                    checkDuplicateKey(seen.has(position.key), position.key, position.line, ctx);
+                seen.add(position.key);
+                emit(position, path);
+                walk(child, [...path, position.key], depth);
+            }
+            value.items?.forEach((item, index) => walk(item, [...path, String(index)], depth));
+        };
+        readOutline(source, builder, ctx, emit, walk);
+    }
+    catch (error) {
+        if (!(error instanceof LimaError))
+            throw error;
+        keys.length = 0;
+        comments.length = 0;
+        if (!diagnostics.some((d) => d.code === error.code && d.line === error.line))
+            addWarning({ ...error, message: error.message });
+    }
+    return result;
+}

package/dist/scalars.d.ts

@@ -120,6 +120,8 @@ export declare const closingQuoteIndex: (s: string, singleQuoteEscape?: boolean)
  */
 export declare const isValidKey: (raw: string) => boolean;
 export declare const unescapeDQ: (s: string, strict?: boolean, line?: number) => string;
+/** UTF-16 offset of the first unescaped, unquoted hash, or -1. */
+export declare const commentStart: (val: string) => number;
 /**
  * The value text with a trailing `#` comment removed, but with `\#`
  * escapes left as written. This is the *physical* form a References 2.0

package/dist/scalars.js

@@ -436,19 +436,8 @@ export const unescapeDQ = (s, strict = false, line = 0) => {
         }
     });
 };
-/**
- * The value text with a trailing `#` comment removed, but with `\#`
- * escapes left as written. This is the *physical* form a References 2.0
- * token's column is measured against (§2.4): the comment is not part of
- * the value (so its `${…}`-shaped text must not be scanned as a token),
- * but a `\#` before a token still occupies its two source columns.
- *
- * `trimEnd()` is exactly the project whitespace set (ECMAScript WhiteSpace
- * + LineTerminator = `isTrimWhitespace`) — a U+00A0 / FEFF between the
- * value and the `#` is not part of the value. The Rust and Go ports must
- * use `is_trim_whitespace` here, not a host `trim_end` or `" \t"`.
- */
-export const stripCommentKeepEscapes = (val) => {
+/** UTF-16 offset of the first unescaped, unquoted hash, or -1. */
+export const commentStart = (val) => {
     let quote = 0;
     for (let i = 0; i < val.length; i++) {
         const cc = val.charCodeAt(i);
@@ -465,10 +454,26 @@ export const stripCommentKeepEscapes = (val) => {
             i++;
         }
         else if (cc === 35) {
-            return val.slice(0, i).trimEnd();
+            return i;
         }
     }
-    return val;
+    return -1;
+};
+/**
+ * The value text with a trailing `#` comment removed, but with `\#`
+ * escapes left as written. This is the *physical* form a References 2.0
+ * token's column is measured against (§2.4): the comment is not part of
+ * the value (so its `${…}`-shaped text must not be scanned as a token),
+ * but a `\#` before a token still occupies its two source columns.
+ *
+ * `trimEnd()` is exactly the project whitespace set (ECMAScript WhiteSpace
+ * + LineTerminator = `isTrimWhitespace`) — a U+00A0 / FEFF between the
+ * value and the `#` is not part of the value. The Rust and Go ports must
+ * use `is_trim_whitespace` here, not a host `trim_end` or `" \t"`.
+ */
+export const stripCommentKeepEscapes = (val) => {
+    const start = commentStart(val);
+    return start === -1 ? val : val.slice(0, start).trimEnd();
 };
 /**
  * The value text with a trailing `#` comment removed and each `\#` *outside*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@limaformat/lima",
-  "version": "0.7.1",
+  "version": "0.8.1",
   "description": "Lima frontmatter parser — LIMA Is Metadata Annotation",
   "keywords": ["frontmatter", "parser", "yaml", "markdown", "metadata"],
   "homepage": "https://limaformat.dev",