@limaformat/lima 0.7.1 → 0.8.1

package/CHANGELOG.md

@@ -12,6 +12,23 @@ carry their own.
 
 ## [Unreleased]
 
+## [0.8.1] — 2026-11-06
+
+### Changed
+
+- `outline()` takes the positions of keys and comments from the parser's own readers as they read, instead of
+  matching the parsed tree to the lines afterwards. It grows linearly with its input (2,048 malformed lines in 15 ms
+  instead of 527); `parse` and `parseCore` keep their speed. For a few malformed inputs the result is now right where
+  the old matching took a key from another line.
+
+## [0.8.0] — 2026-11-05
+
+### Added
+
+- `outline(input)` returns decoded key paths, key and separator spans, comments,
+  and parser diagnostics for editors. Positions use UTF-16 code units in the
+  BOM-free physical input, with tolerant recovery for unfinished documents.
+
 ## [0.7.1] — 2026-10-31
 
 ### Security

package/README.md

@@ -35,8 +35,9 @@ tags:
 `parse` accepts the raw content **between** the frontmatter delimiters
 (`---`) — stripping them is the caller's job.
 
-Three functions are exported:
+Four functions are exported:
 
+- `outline(input)` — source positions for editor keys, comments and diagnostics.
 - `parseCore(input, options?)` — the base format only.
 - `parse(input, options?)` — the primary References <!-- facts:language.references_version -->2.1<!-- /facts --> parser; adds
   `${key}` document references and `$(key)` external partials.
@@ -49,6 +50,29 @@ parse(frontmatter, { partials: { author: 'Alice' } })
 parse(frontmatter, { mode: 'core' }) // same reference-unaware path as parseCore
 ```
 
+## Editor outlines
+
+```ts
+import { outline } from '@limaformat/lima'
+
+const { keys, comments, diagnostics } = outline('author: {name: Ada} # byline')
+// keys: paths ['author'] and ['author', 'name'], with key and separator spans
+```
+
+`outline` tolerates unfinished content and returns keys in source order, including
+all duplicate occurrences. Sequence paths include string indices, such as
+`['authors', '0', 'name']`. Quoted keys are decoded; their spans include the quotes.
+Comments run from `#` through the physical line's end, excluding its terminator.
+Block scalar content contributes no keys or comments.
+
+Spans are half-open. Lines and columns start at 1; columns and offsets count
+UTF-16 code units (`offsetUnit: 'utf16-code-unit'`). Positions refer to the raw
+input with a leading BOM removed; CRLF and tabs keep their original widths.
+Diagnostics contain strict `parse`'s first error, followed by non-strict duplicate
+warnings. A resource limit produces diagnostics and no spans. Structure remains
+reference-inert: keys copied by reference substitution have no source occurrence
+and are omitted; only the diagnostic pass evaluates references, without partials.
+
 The **[guide](https://github.com/limaformat/lima/blob/main/docs/guide.md)**
 covers Core <!-- facts:language.core_version -->1.2<!-- /facts --> and References <!-- facts:language.references_version -->2.1<!-- /facts --> syntax, resource limits, strict mode, and the
 public API. The normative rules are defined in the

package/dist/block-cursor.d.ts

@@ -1,3 +1,4 @@
+import type { SourcePositions } from './builder.js';
 /**
  * Allocation-free physical-line cursor over one top-level block extent.
  * Positions are UTF-16 code-unit offsets. Indentation is the run of spaces
@@ -20,6 +21,20 @@ export declare class BlockCursor {
     private nextStart;
     constructor(source: string, rangeStart: number, rangeEnd: number);
     next(): boolean;
+    /** Consume the physical body of a block scalar, leaving the first dedented line. */
+    scalarLines(keyIndent: number): string[];
+    protected scalarBody(keyIndent: number): string[];
     get empty(): boolean;
     get firstCode(): number;
 }
+/** Reports comments only as lines are consumed, never inside a scalar body. */
+export declare class SourceBlockCursor extends BlockCursor {
+    private readonly positions;
+    private commentFrom;
+    private scalar;
+    constructor(source: string, start: number, end: number, positions: SourcePositions);
+    /** Exclude comment markers before this normalized UTF-16 offset on the current line. */
+    excludeCommentsBefore(offset: number): void;
+    next(): boolean;
+    protected scalarBody(keyIndent: number): string[];
+}

package/dist/block-cursor.js

@@ -1,4 +1,5 @@
 import { isTrimWhitespace } from './chars.js';
+import { commentStart } from './scalars.js';
 /**
  * Allocation-free physical-line cursor over one top-level block extent.
  * Positions are UTF-16 code-unit offsets. Indentation is the run of spaces
@@ -66,6 +67,21 @@ export class BlockCursor {
         this.nextStart = newline === -1 || newline >= this.rangeEnd ? this.rangeEnd : newline + 1;
         return true;
     }
+    /** Consume the physical body of a block scalar, leaving the first dedented line. */
+    scalarLines(keyIndent) {
+        this.next();
+        return this.scalarBody(keyIndent);
+    }
+    scalarBody(keyIndent) {
+        const lines = [];
+        while (this.valid) {
+            if (this.lineEnd - this.lineStart > this.asciiIndent && this.asciiIndent <= keyIndent)
+                break;
+            lines.push(this.source.slice(this.lineStart, this.lineEnd));
+            this.next();
+        }
+        return lines;
+    }
     get empty() {
         return this.contentStart === this.lineEnd;
     }
@@ -73,3 +89,33 @@ export class BlockCursor {
         return this.source.charCodeAt(this.contentStart);
     }
 }
+/** Reports comments only as lines are consumed, never inside a scalar body. */
+export class SourceBlockCursor extends BlockCursor {
+    positions;
+    commentFrom = 0;
+    scalar = false;
+    constructor(source, start, end, positions) {
+        super(source, start, end);
+        this.positions = positions;
+    }
+    /** Exclude comment markers before this normalized UTF-16 offset on the current line. */
+    excludeCommentsBefore(offset) {
+        this.commentFrom = offset;
+    }
+    next() {
+        if (this.valid && !this.scalar) {
+            const hash = commentStart(this.source.slice(this.commentFrom, this.lineEnd));
+            if (hash !== -1)
+                this.positions.comment(this.commentFrom + hash, this.lineEnd);
+        }
+        const valid = super.next();
+        this.commentFrom = this.contentStart;
+        return valid;
+    }
+    scalarBody(keyIndent) {
+        this.scalar = true;
+        const lines = super.scalarBody(keyIndent);
+        this.scalar = false;
+        return lines;
+    }
+}

package/dist/block.d.ts

@@ -9,10 +9,21 @@
  * never resolves a reference in the first place).
  */
 import { type ParseContext } from './normalize.js';
+import { parseFlowOrScalarValue } from './flow.js';
 import type { ValueBuilder } from './builder.js';
+import { BlockCursor } from './block-cursor.js';
+/**
+ * An inline value, or a block scalar when `marker`: `|` alone (§6.1.5;
+ * `| # c` is the string `|`). Both leave the cursor on the next unread line.
+ */
+export declare const parseInlineValue: <V, M>(raw: string, marker: boolean, keyIndent: number, keyLine: number, valueCol: number, rawUndecoded: string, cursor: BlockCursor, ctx: ParseContext, builder: ValueBuilder<V, M>, readValue: typeof parseFlowOrScalarValue<V, M>) => V;
 export declare const findKeySep: (s: string) => number;
+declare const nativeBlockParser: <V, M>(cursor: BlockCursor, baseIndent: number, ctx: ParseContext, baseLine: number, builder: ValueBuilder<V, M>, compact?: boolean) => V | null;
+/** Shared block grammar consuming one mutable physical-line cursor. */
+export declare const parseCursorBlock: typeof nativeBlockParser;
 /** Complete block grammar over one UTF-16 source range. */
 export type BlockDepthRisk = {
     mayExceed: boolean;
 };
-export declare const parseBlockRange: <V, M>(source: string, start: number, end: number, ctx: ParseContext, baseLine: number, builder: ValueBuilder<V, M>, depthRisk: BlockDepthRisk) => V | null;
+export declare const parseBlockRange: <V, M>(source: string, start: number, end: number, ctx: ParseContext, baseLine: number, builder: ValueBuilder<V, M>, depthRisk: BlockDepthRisk, cursor?: BlockCursor) => V | null;
+export {};