All notable changes to @limaformat/lima are documented in this file.
The format follows Keep a Changelog. This package's version number tracks its own release history and is independent of the Lima specification versions — Lima Core 1.3 and Lima References 2.1 carry their own.
Lima Core 1.3: Lima reads five forms as YAML front matter writes them, and strict mode names what to write for the YAML forms it does not read (Core §10.2, Appendix E).
- The diagnostic code
UNSUPPORTED_YAML.
- A
#begins a comment only at the start of a value or after whitespace (Core §4), in flow sequences and flow mappings too, decided once over the whole value:https://example.org/x#topandC#keep their#, and[a,#x]is["a", "#x"].\#still yields#. A References token after such a#is active, and${a}#xis an interpolation. - An entry whose value is only a comment,
key: # note, is a bare key: the deeper lines after it are its block, at every level.- # notestays anullitem, andkey: nullandkey: ''have an inline value. - A tab after the colon separates key and value as a space does, at the top level, in blocks, in sequence items and in flow mappings.
- A flow mapping finds its separator before the item is trimmed:
{k: }is{k: null};{k:}has no separator. - Strict mode throws
UNSUPPORTED_YAMLfor an unquoted value that starts with&,*or!, and for a YAML block scalar header other than|(>,|-,>2, …) at the header's own line, lines after it or not. Non-strict mode reads both as strings, as before. - Error messages for YAML forms name the Lima form: quote the value,
|and^^,'It\'s', no merge keys or directives, a quoted key with spaces, nesting forseo.title,|for a value of several lines, a block sequence for a flow sequence that does not close.
- A tab after U+2028 or U+2029 was expanded as leading indentation, and the References columns of every later line moved (Core §3 erratum).
- A flow value with a
#after text and a References token,[a#b,${x}], threw an internal error: the position map took every#for\#. outline()follows the new comment boundary, bare keys after a comment, and a tab separator.- A value is trimmed after comment removal also when no comment is removed
(Core §4):
x\#yor'#x'followed by a tab, and a value followed by U+00A0 before a comment line, kept that whitespace, and'#x'followed by a tab was no quoted value. - In a sequence item, a single-quoted key that ends in
\kept the comment of its value:- 'a\': x # creadx # c, and- 'a\': # cwas no bare key. The key is read by the key rules first, which know no escape in single quotes (Core §5.2).
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);parseandparseCorekeep their speed. For a few malformed inputs the result is now right where the old matching took a key from another line.
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.
- A few KB of references could copy millions of nodes before the limit on the result stopped them, and interpolation kept growing a value past its limit. Resolution now counts what it copies and stops (References §4.1), with the error of an oversized result.
- A value or sequence item followed by whitespace other than spaces kept it at the top level:
draft: falsewith a no-break space after it is now the boolean, as in a block (Core §4). .0and-.0are zero, not an underflow.- A line with an empty key in a block is an unrecognised line.
- Spaces before a flow value in a sequence item threw an error without a Lima code.
- Messages no longer quote control or direction characters of the source, and shorten a long line.
LimaErroris exported.
Lima Core 1.2 and References 2.1: an unquoted key may be written in any
script. It starts with a letter or number of Unicode 18.0 or _, and after
its first character also holds marks, * and ·, so keys can be written
in any language and gendered (größe, 題名, autor*in, autor·in);
references reach every such key. Core 1.2 also states in one table what
each kind of line does where it stands (§7.1), without changing an outcome.
- Unquoted keys and reference names take Unicode letters, marks and numbers
(Unicode 18.0, fixed by the specification) and
*and·after their first character. The categories come from a generated table, not the host's Unicode support, and no dependency; ASCII keys are read as fast as before. - Hints: whitespace other than spaces before a key, a FULLWIDTH COLON
(U+FF1A) in place of
:, and the key-grammar hint for a key such asx y: 2at every level.
- A line whose key Core 1.1 rejected for its characters, and Core 1.2 admits, is an entry now; non-strict mode skipped it, strict mode threw.
- A document with a lone surrogate is rejected with
INVALID_DOCUMENTand the line it is on (Core §1), in both modes. - Node.js 22 or later (
String.prototype.isWellFormed).
Lima Core 1.1: strict mode rejects a content line that belongs to no structure, which Core 1.0 skipped in both modes. Core 1.1 also settles cases Core 1.0 left open, where the three implementations differed; some non-strict results change with them (below).
- Strict mode throws
INVALID_INDENTATIONfor a line indented after a top-level key with an inline value — the lines after a YAML>,|-or|+, a key indented by a tab, freetext after a value — as it already did one level down; the message names the YAML marker and what Lima writes instead. - Strict mode throws the new
UNRECOGNIZED_LINEfor an unindented line that matches no key pattern: a key without its:, a dotted or otherwise invalid key, a YAML---/...marker, a quoted key broken by a newline. - A line of a block mapping whose key the key grammar rejects (
a.b: value,bad key: value), skipped in strict mode until now, throwsUNRECOGNIZED_LINEtoo; an indented line below a block mapping's base indentation, or after a|scalar a column-0 comment ended, throwsINVALID_INDENTATION. LimaDiagnosticCodegains'UNRECOGNIZED_LINE'.- A bare key's sequence may start at the key's own column, as YAML writes
it (
tags:/- a/- b), at any level (Core 1.1 §7.2). At the top level this was read so by accident; one level down the sequence and the keys after it were lost. - An item whose value is a flow sequence (
- [a, b],- []) is a nested sequence (Core 1.1 §7.2):nullin non-strict mode,INVALID_FLOW_SYNTAXin strict mode. - Indentation is spaces only (Core 1.1 §7.1): a line whose spaces are followed by other whitespace, such as U+00A0, before its content is unrecognised — skipped in non-strict mode, an error in strict mode. Whitespace is defined once (§1), as the set every check already used. TypeScript counted such whitespace as indentation.
- An object item's later keys stand at its first key's column (§7.2): a line
of the item deeper than that is skipped in non-strict mode, and one less
indented ends the item; strict mode throws
INVALID_INDENTATIONfor either. Any deeper line was taken as a key of the item.
- A
|scalar as an object item's first key measured its body from the dash plus two columns, so after wider whitespace (- a: |) it took the item's next key as text; it measures from the key's column (§6.1.5, §7.2). - In strict mode, a line deeper than a nested
|scalar's key, after a line of other whitespace that ended the scalar, was dropped without an error; it throwsINVALID_INDENTATION. - A top-level
key:at the very end of the input, without a line terminator, was no key at all and vanished; it isnull, as at any nested level and in the Rust and Go implementations, and as Core 1.1 §4 now says. This changes a non-strict result too. - A
|with no content lines (a: |at the end of a block, or of the input) was the string"|"; it is""(Core 1.1 §6.1.5). - A block of mapping entries with a sequence item in it, or the reverse, was an empty sequence in non-strict mode, all its entries lost; the first kind wins and a line of the other kind is skipped (Core 1.1 §7.1).
- An item value that begins with
[but is no flow sequence (- [x] done), or with{and does not close (- {a: 1), throwsINVALID_FLOW_SYNTAXin strict mode, as an inline value does. key: | # cbelow the top level, in a block mapping or an object item, was a block scalar; it is the string"|", as at the top level — the marker stands alone (§6.1.5).
The shared conformance corpus is at 336 Core cases: the 218 Core 1.0 cases
without the 8 that Core 1.1 supersedes, plus 126 Core 1.1 cases
(corpus/core-1.1/).
Core errata 1.0.10: aligned top-level values are trimmed, as Core 1.0
always required.
- A top-level inline value kept every space after
:but the first:title: Helloread' Hello', andn: 42the string' 42'instead of the integer 42 — against §4 step 3 and the §4 and §5.1 examples. Nested keys were not affected. The top-level entry now skips the whitespace after the separator before reading the value, as the block mapping does; the References 2.0 columns it reports were already physical and are unchanged.
The shared conformance corpus grows to 218 Core cases (7 new, since: "1.0.10"); TypeScript, Rust, and Go pass all of them.
A unit test in src/block.test.ts had asserted the defect (key: value
→ ' value'); it now asserts the specified 'value'.
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.
- 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).
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.
- 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 asa.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) parseCoreno longer builds reference-position metadata — that work is now confined to theparse/ positioned path — restoring the Core hot path to its pre-errata baseline.
|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 (nokey.length + 2cap, 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": vand"say \"hi\"": vparse 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
\nescape 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 throwsINVALID_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:
lineandcolumnare 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.columnis 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.
- References 2.0 document references now resolve correctly when the source and target share a top-level mapping, including sibling fields and separate nested branches. Genuine self-references and dependency cycles remain unresolved.
- Breaking: References 2.0 document references now use
${key}, while partial references use$(key). The briefly published$(key)document syntax is therefore reinterpreted as a partial reference;$(:key)is literal text.
- 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 forparsewith identical References 2.0 results and diagnostics. It is not a References 1.0 mode.ParseOptions.modeselects"references"(the default) or"core". Core mode uses the same reference-unaware path asparseCore; supplyingpartialsin Core mode is invalid.parseCoreitself 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(the stable, documented field for programmatic error handling) is unaffected; message text was never a documented stable API surface.
Initial release.
parseCore(input, options?)— Lima Core 1.0 only, no reference resolution.parse(input, options?)/parseReferences(input, options?)— Core plus the References 1.0 extension (($key)document references,(%key)external partials).- Zero runtime dependencies.
- Verified against the shared, implementation-independent conformance
corpus (250 cases as of this release; count pinned by a test — see
docs/guide.mdanddocs/corpus-design/).