@limaformat/lima 0.1.0

package/dist/index.js

@@ -0,0 +1,15 @@
+/**
+ * LIMA Parser — LIMA Is Metadata Annotation
+ *
+ * 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.
+ *   - `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.
+ */
+export { parseCore } from './core.js';
+export { parseReferences, parse } from './references.js';

package/dist/normalize.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Shared, domain-agnostic parsing primitives: the parse context threaded
+ * through every module, Core §9's resource limits, and the length/duplicate
+ * checks built on them. Every other Core module (`scalars.ts`, `flow.ts`,
+ * `block.ts`, `core.ts`) sits above this one.
+ */
+import { type LimaValue, SCALAR_LENGTH_LIMIT } from './value.js';
+export { SCALAR_LENGTH_LIMIT };
+/** Core §11.2: the minimal `onWarning` diagnostic shape — message and line only. */
+export type Diagnostic = {
+    message: string;
+    line: number;
+};
+/**
+ * Threaded through the whole recursive descent instead of a bare `strict`
+ * boolean, so `onWarning` reaches every call site that can emit a warning
+ * (currently just duplicate-key detection) without growing every
+ * function's parameter list further as new warning types are added.
+ */
+export type ParseContext = {
+    strict: boolean;
+    onWarning?: (diagnostic: Diagnostic) => void;
+};
+export declare const DOCUMENT_SIZE_LIMIT = 65536;
+export declare const KEY_LENGTH_LIMIT = 128;
+export declare const TOP_LEVEL_KEY_LIMIT = 128;
+export declare const NESTING_DEPTH_LIMIT = 16;
+export declare const byteLength: (s: string) => number;
+export declare const checkStringLimit: (value: string, line: number) => void;
+export declare const checkScalarLimit: (v: LimaValue, line: number) => void;
+/**
+ * `line` is a thunk, not a plain number: computing a top-level key's line
+ * can trigger an O(document length) scan (see `keyLine` in core.ts) the very
+ * first time it's called, and this check runs for every key in the
+ * document. Evaluating it eagerly would pay that cost on every parse, even
+ * though the overwhelming majority of keys never violate the limit — the
+ * thunk defers it to the one branch that actually needs a line number.
+ */
+export declare const checkKeyLength: (key: string, line: () => number) => void;
+export declare const checkDuplicateKey: (exists: boolean, key: string, line: number, ctx: ParseContext) => void;
+export declare const checkDuplicateKeyMap: (entries: Map<string, unknown>, key: string, line: number, ctx: ParseContext) => void;

package/dist/normalize.js

@@ -0,0 +1,67 @@
+/**
+ * Shared, domain-agnostic parsing primitives: the parse context threaded
+ * through every module, Core §9's resource limits, and the length/duplicate
+ * checks built on them. Every other Core module (`scalars.ts`, `flow.ts`,
+ * `block.ts`, `core.ts`) sits above this one.
+ */
+import { SCALAR_LENGTH_LIMIT, codepointLength } from './value.js';
+import { LimaError } from './errors.js';
+export { SCALAR_LENGTH_LIMIT };
+// Core §9 resource limits. All are hard errors in both modes.
+export const DOCUMENT_SIZE_LIMIT = 65536;
+export const KEY_LENGTH_LIMIT = 128;
+export const TOP_LEVEL_KEY_LIMIT = 128;
+export const NESTING_DEPTH_LIMIT = 16;
+const utf8Encoder = new TextEncoder();
+export const byteLength = (s) => utf8Encoder.encode(s).length;
+export const checkStringLimit = (value, line) => {
+    // UTF-16 code-unit length is always >= Unicode code-point length. Short
+    // values therefore cannot violate the limit and need no surrogate scan.
+    if (value.length > SCALAR_LENGTH_LIMIT && codepointLength(value) > SCALAR_LENGTH_LIMIT) {
+        throw new LimaError({
+            code: 'RESOURCE_LIMIT', line,
+            message: `LIMA: scalar exceeds maximum length of ${SCALAR_LENGTH_LIMIT} code points at line ${line}`,
+        });
+    }
+};
+export const checkScalarLimit = (v, line) => {
+    if (v.kind === 'string')
+        checkStringLimit(v.value, line);
+};
+/**
+ * `line` is a thunk, not a plain number: computing a top-level key's line
+ * can trigger an O(document length) scan (see `keyLine` in core.ts) the very
+ * first time it's called, and this check runs for every key in the
+ * document. Evaluating it eagerly would pay that cost on every parse, even
+ * though the overwhelming majority of keys never violate the limit — the
+ * thunk defers it to the one branch that actually needs a line number.
+ */
+export const checkKeyLength = (key, line) => {
+    if (key.length > KEY_LENGTH_LIMIT && codepointLength(key) > KEY_LENGTH_LIMIT) {
+        const l = line();
+        throw new LimaError({
+            code: 'RESOURCE_LIMIT', line: l,
+            message: `LIMA: key "${key}" exceeds maximum length of ${KEY_LENGTH_LIMIT} code points at line ${l}`,
+        });
+    }
+};
+export const checkDuplicateKey = (exists, key, line, ctx) => {
+    if (!exists)
+        return;
+    const diagnostic = {
+        code: 'DUPLICATE_KEY', line, key,
+        message: `LIMA: duplicate key "${key}" at line ${line} — last value wins`,
+    };
+    if (ctx.strict)
+        throw new LimaError(diagnostic);
+    // Core §11.2: "Implementations MUST NOT emit warnings to any implicit
+    // output channel (e.g. console.warn)." Silently discarded when no
+    // onWarning callback is provided — never a fallback to console.warn.
+    // The public `Diagnostic` type is the spec-frozen {message, line} shape
+    // (§11.2); the object actually delivered is the richer `LimaDiagnostic`
+    // (a structural superset), letting an internal caller — such as the
+    // conformance runner, which imports these modules directly — read
+    // `.code` without parsing the message.
+    ctx.onWarning?.(diagnostic);
+};
+export const checkDuplicateKeyMap = (entries, key, line, ctx) => checkDuplicateKey(entries.has(key), key, line, ctx);

package/dist/references.d.ts

@@ -0,0 +1,36 @@
+/**
+ * LIMA References 1.0 — layered strictly on top of `core.ts` (Appendix B:
+ * reference resolution is exclusively this extension's concern; Core never
+ * sees it). Reads the annotated `PositionedValue` tree Core produces and
+ * performs the two-phase resolution the spec describes (§4), keeping every
+ * intermediate result in the SAME annotated representation instead of a
+ * separate raw-value tree with a bolted-on marker for "inert":
+ *
+ *   - A string's `quoted` flag (set once, by Core, from actual quote syntax)
+ *     is the single source of truth for "never treat this as a reference
+ *     site" — §2.3 (quoted tokens) and §3.8 (partial content) are the same
+ *     rule applied to two different origins, so partial values are wrapped
+ *     into this same representation with every string leaf pre-marked
+ *     `quoted: true` before insertion (`partialToPositioned`), rather than
+ *     needing a second, unrelated mechanism.
+ *   - Every node keeps the source `line` it was parsed with, even after
+ *     being deep-copied into a new position — diagnostics read it directly
+ *     off the node instead of falling back to a coarser key-level lookup.
+ *
+ * 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';
+type Meta = Record<string, unknown>;
+export type ReferencesOptions = {
+    /** Named values available via `(%key)` references. */
+    partials?: Meta;
+    strict?: boolean;
+    /** Core §11.2 (inherited): callback for non-strict warnings (e.g. duplicate keys). Discarded if omitted. */
+    onWarning?: (diagnostic: Diagnostic) => void;
+};
+export declare const parseReferences: <T extends Record<string, unknown> = Meta>(frontMatter: string, options?: ReferencesOptions) => T;
+/** Backward-compatible primary entry point — References layered on Core. */
+export declare const parse: typeof parseReferences;
+export type ParseOptions = ReferencesOptions;
+export {};