@spintax/core 0.1.6 → 0.3.0

package/dist/index.d.cts

@@ -15,13 +15,76 @@
  *     the AST here.
  * Permutation's `<config>` + per-element separators are fully parsed (PR-11b).
  */
-/** Bumped only on a breaking change to the node shape (independent of syntax v1). */
-declare const AST_VERSION = 1;
+/**
+ * Bumped only on a breaking change to the node shape (independent of syntax v1).
+ *
+ * 2 — `ParsedAst` gained `defDefs`. An `Ast` cached by an older version carries no `#def` map, so
+ * rendering it would silently drop every definition; the version guard turns that into an
+ * `AstVersionError` instead.
+ */
+declare const AST_VERSION = 2;
 /** Opaque public handle (re-exported as `Ast` from the package index). */
 interface Ast {
     readonly astVersion: typeof AST_VERSION;
 }
 
+/**
+ * Tree-walk renderer with the plugin's staged semantics layered on (parity with
+ * Renderer::process_template). Not a naive walk — the deterministic stages are
+ * reproduced in order:
+ *   - #set is a global pre-pass (parser) → setDefs; those enum values are
+ *     COLLAPSED ONCE here (buildVars), skipping values with `{?`/`{plural ` (they
+ *     reference vars and defer to the body) — plugin Stage 4b.
+ *   - variables resolve against the merged map (runtime context > #set); a value
+ *     that itself contains constructs is re-parsed and rendered (recursive, depth
+ *     capped) — this covers conditionals/plurals introduced by a variable value
+ *     (Stages 6b–6c), so a separate pre/post conditional pass isn't needed.
+ *   - conditionals test truthiness against the raw var map; plurals resolve the
+ *     count (vars already expanded) then pick the bucket, lenient fullwidth
+ *     fallback (Stage 6d, after vars).
+ *   - #include (post-tree string pass) and post-process are later PRs.
+ *
+ * RNG note: cross-engine RNG-sequence parity is a non-goal (§3.2). Enumerations
+ * render outer-first and LAZILY (only the picked branch's nested RNG is used) vs
+ * the plugin's eager innermost-out; corpus-safe because deterministic nested-enum
+ * cases use order-independent sequences. Permutation matches the plugin's exact
+ * pick→Fisher-Yates, so its rng-strategy cases are exact.
+ */
+
+/** Document-level render context (threads through nested #include resolution). */
+/**
+ * A `{plural …}` block the renderer could not resolve, reported through
+ * {@link RenderCtx.onPluralError}. Observation only — the render still degrades
+ * exactly as it always has (§0.1 lenient contract); the host decides whether a
+ * report is fatal. Mirrors the plugin's `on_error` callable.
+ */
+interface PluralIssue {
+    /**
+     * `plural.nested-brackets` and `plural.arity` are the same codes `validate()`
+     * emits. `plural.count` has no validate counterpart on purpose — an unresolved
+     * count is a runtime-value fact, invisible to static analysis.
+     */
+    readonly code: 'plural.nested-brackets' | 'plural.arity' | 'plural.count';
+    readonly message: string;
+    /** The construct as the renderer saw it, AFTER variable expansion. */
+    readonly construct: string;
+    /** Normalized base language the arity was judged against. */
+    readonly locale: string;
+    /** Arity verdicts only. */
+    readonly expected?: number;
+    readonly got?: number;
+}
+
+/**
+ * The full render pipeline with an INJECTED rng — the seam shared by the public
+ * render() (which seeds the rng from RenderOptions.seed) and the corpus harness
+ * (which injects a fixture's `rng` strategy). Keeping the rng a parameter is what
+ * lets the deterministic parity fixtures assert exact output.
+ *
+ * Order: strip stray sentinels → collapse-once #set + tree-walk (+ #include) →
+ * cosmetic post-process (if on) → mandatory neutralize safety-restore (always).
+ */
+
 /** Default for {@link PipelineOptions.maxDepth} (#include + parse-nesting guard). */
 declare const DEFAULT_MAX_DEPTH = 20;
 
@@ -69,6 +132,17 @@ interface RenderOptions {
     postProcess?: boolean;
     /** #include + parse-nesting guard; defaults to {@link DEFAULT_MAX_DEPTH}. */
     maxDepth?: number;
+    /**
+     * Observer for `{plural …}` blocks the renderer could not resolve — the port of
+     * the plugin's `on_error` callable. Observation ONLY: output degrades exactly as
+     * it does without it (§0.1 lenient contract — `render()` never throws on template
+     * content), and the host decides whether a report is fatal.
+     *
+     * Worth wiring when a render is PERSISTED rather than shown: an unresolved count
+     * erases its block, which is indistinguishable in the output from copy that was
+     * meant to be empty.
+     */
+    onPluralError?: (issue: PluralIssue) => void;
 }
 interface ValidateOptions {
     /** Plural-bucket locale for arity verdicts (§3.1); omit ⇒ default 2-form. */
@@ -98,7 +172,10 @@ interface Diagnostic {
 }
 interface ExtractResult {
     refs: string[];
+    /** Names defined by `#set` — macros, re-picked at every reference. */
     sets: string[];
+    /** Names defined by `#def` — rolled once per render and held. */
+    defs: string[];
     includes: string[];
 }
 interface Analysis extends ExtractResult {
@@ -107,6 +184,31 @@ interface Analysis extends ExtractResult {
     constructs: Record<string, number>;
 }
 
+/**
+ * A locale's base language tag: `pt-BR`→`pt`, `uk_UA`→`uk`, `RU`→`ru`. Absent or
+ * empty gives `''`.
+ *
+ * Knows nothing of ISO-639-3, so a 3-letter tag is returned whole (`srp`→`srp`)
+ * and is NOT recognized as its 2-letter language.
+ */
+declare function normalizeBaseLang(locale?: string | null): string;
+/**
+ * How many `{plural …}` forms this locale takes — 3 for the Slavic one/few/other
+ * family (ru/uk/be + sr/hr/bs), 2 for everything else.
+ *
+ * Takes a RAW locale and normalizes internally, unlike the internal helper of the
+ * same name: a public function that silently answered 2 for `sr-Latn` would be a
+ * trap. Accepts an absent locale, and unknown tags fall back to 2 rather than
+ * throwing (§3.1), so the same optional value `RenderOptions.locale` carries can be
+ * passed straight through.
+ *
+ * NOTE the asymmetry with {@link validate}: an absent or empty locale makes the
+ * validator skip the arity check ENTIRELY (structural verdicts only), whereas this
+ * answers the 2-form default that {@link render} would then apply. Ask this what
+ * render will do; do not read it as "what validate will enforce".
+ */
+declare function pluralArity(locale?: string | null): number;
+
 declare function parse(src: string): Ast;
 declare function render(input: string | Ast, opts?: RenderOptions): string;
 declare function validate(input: string | Ast, opts?: ValidateOptions): Diagnostic[];
@@ -114,4 +216,4 @@ declare function extract(input: string | Ast): ExtractResult;
 declare function analyze(input: string | Ast, opts?: ValidateOptions): Analysis;
 declare function neutralize(value: string): string;
 
-export { type Analysis, type Ast, AstVersionError, DEFAULT_MAX_DEPTH, type Diagnostic, type ExtractResult, IncludeResolverError, NotImplementedError, type RenderOptions, SpintaxError, type ValidateOptions, analyze, extract, neutralize, parse, render, validate };
+export { type Analysis, type Ast, AstVersionError, DEFAULT_MAX_DEPTH, type Diagnostic, type ExtractResult, IncludeResolverError, NotImplementedError, type PluralIssue, type RenderOptions, SpintaxError, type ValidateOptions, analyze, extract, neutralize, normalizeBaseLang, parse, pluralArity, render, validate };

package/dist/index.d.ts

@@ -15,13 +15,76 @@
  *     the AST here.
  * Permutation's `<config>` + per-element separators are fully parsed (PR-11b).
  */
-/** Bumped only on a breaking change to the node shape (independent of syntax v1). */
-declare const AST_VERSION = 1;
+/**
+ * Bumped only on a breaking change to the node shape (independent of syntax v1).
+ *
+ * 2 — `ParsedAst` gained `defDefs`. An `Ast` cached by an older version carries no `#def` map, so
+ * rendering it would silently drop every definition; the version guard turns that into an
+ * `AstVersionError` instead.
+ */
+declare const AST_VERSION = 2;
 /** Opaque public handle (re-exported as `Ast` from the package index). */
 interface Ast {
     readonly astVersion: typeof AST_VERSION;
 }
 
+/**
+ * Tree-walk renderer with the plugin's staged semantics layered on (parity with
+ * Renderer::process_template). Not a naive walk — the deterministic stages are
+ * reproduced in order:
+ *   - #set is a global pre-pass (parser) → setDefs; those enum values are
+ *     COLLAPSED ONCE here (buildVars), skipping values with `{?`/`{plural ` (they
+ *     reference vars and defer to the body) — plugin Stage 4b.
+ *   - variables resolve against the merged map (runtime context > #set); a value
+ *     that itself contains constructs is re-parsed and rendered (recursive, depth
+ *     capped) — this covers conditionals/plurals introduced by a variable value
+ *     (Stages 6b–6c), so a separate pre/post conditional pass isn't needed.
+ *   - conditionals test truthiness against the raw var map; plurals resolve the
+ *     count (vars already expanded) then pick the bucket, lenient fullwidth
+ *     fallback (Stage 6d, after vars).
+ *   - #include (post-tree string pass) and post-process are later PRs.
+ *
+ * RNG note: cross-engine RNG-sequence parity is a non-goal (§3.2). Enumerations
+ * render outer-first and LAZILY (only the picked branch's nested RNG is used) vs
+ * the plugin's eager innermost-out; corpus-safe because deterministic nested-enum
+ * cases use order-independent sequences. Permutation matches the plugin's exact
+ * pick→Fisher-Yates, so its rng-strategy cases are exact.
+ */
+
+/** Document-level render context (threads through nested #include resolution). */
+/**
+ * A `{plural …}` block the renderer could not resolve, reported through
+ * {@link RenderCtx.onPluralError}. Observation only — the render still degrades
+ * exactly as it always has (§0.1 lenient contract); the host decides whether a
+ * report is fatal. Mirrors the plugin's `on_error` callable.
+ */
+interface PluralIssue {
+    /**
+     * `plural.nested-brackets` and `plural.arity` are the same codes `validate()`
+     * emits. `plural.count` has no validate counterpart on purpose — an unresolved
+     * count is a runtime-value fact, invisible to static analysis.
+     */
+    readonly code: 'plural.nested-brackets' | 'plural.arity' | 'plural.count';
+    readonly message: string;
+    /** The construct as the renderer saw it, AFTER variable expansion. */
+    readonly construct: string;
+    /** Normalized base language the arity was judged against. */
+    readonly locale: string;
+    /** Arity verdicts only. */
+    readonly expected?: number;
+    readonly got?: number;
+}
+
+/**
+ * The full render pipeline with an INJECTED rng — the seam shared by the public
+ * render() (which seeds the rng from RenderOptions.seed) and the corpus harness
+ * (which injects a fixture's `rng` strategy). Keeping the rng a parameter is what
+ * lets the deterministic parity fixtures assert exact output.
+ *
+ * Order: strip stray sentinels → collapse-once #set + tree-walk (+ #include) →
+ * cosmetic post-process (if on) → mandatory neutralize safety-restore (always).
+ */
+
 /** Default for {@link PipelineOptions.maxDepth} (#include + parse-nesting guard). */
 declare const DEFAULT_MAX_DEPTH = 20;
 
@@ -69,6 +132,17 @@ interface RenderOptions {
     postProcess?: boolean;
     /** #include + parse-nesting guard; defaults to {@link DEFAULT_MAX_DEPTH}. */
     maxDepth?: number;
+    /**
+     * Observer for `{plural …}` blocks the renderer could not resolve — the port of
+     * the plugin's `on_error` callable. Observation ONLY: output degrades exactly as
+     * it does without it (§0.1 lenient contract — `render()` never throws on template
+     * content), and the host decides whether a report is fatal.
+     *
+     * Worth wiring when a render is PERSISTED rather than shown: an unresolved count
+     * erases its block, which is indistinguishable in the output from copy that was
+     * meant to be empty.
+     */
+    onPluralError?: (issue: PluralIssue) => void;
 }
 interface ValidateOptions {
     /** Plural-bucket locale for arity verdicts (§3.1); omit ⇒ default 2-form. */
@@ -98,7 +172,10 @@ interface Diagnostic {
 }
 interface ExtractResult {
     refs: string[];
+    /** Names defined by `#set` — macros, re-picked at every reference. */
     sets: string[];
+    /** Names defined by `#def` — rolled once per render and held. */
+    defs: string[];
     includes: string[];
 }
 interface Analysis extends ExtractResult {
@@ -107,6 +184,31 @@ interface Analysis extends ExtractResult {
     constructs: Record<string, number>;
 }
 
+/**
+ * A locale's base language tag: `pt-BR`→`pt`, `uk_UA`→`uk`, `RU`→`ru`. Absent or
+ * empty gives `''`.
+ *
+ * Knows nothing of ISO-639-3, so a 3-letter tag is returned whole (`srp`→`srp`)
+ * and is NOT recognized as its 2-letter language.
+ */
+declare function normalizeBaseLang(locale?: string | null): string;
+/**
+ * How many `{plural …}` forms this locale takes — 3 for the Slavic one/few/other
+ * family (ru/uk/be + sr/hr/bs), 2 for everything else.
+ *
+ * Takes a RAW locale and normalizes internally, unlike the internal helper of the
+ * same name: a public function that silently answered 2 for `sr-Latn` would be a
+ * trap. Accepts an absent locale, and unknown tags fall back to 2 rather than
+ * throwing (§3.1), so the same optional value `RenderOptions.locale` carries can be
+ * passed straight through.
+ *
+ * NOTE the asymmetry with {@link validate}: an absent or empty locale makes the
+ * validator skip the arity check ENTIRELY (structural verdicts only), whereas this
+ * answers the 2-form default that {@link render} would then apply. Ask this what
+ * render will do; do not read it as "what validate will enforce".
+ */
+declare function pluralArity(locale?: string | null): number;
+
 declare function parse(src: string): Ast;
 declare function render(input: string | Ast, opts?: RenderOptions): string;
 declare function validate(input: string | Ast, opts?: ValidateOptions): Diagnostic[];
@@ -114,4 +216,4 @@ declare function extract(input: string | Ast): ExtractResult;
 declare function analyze(input: string | Ast, opts?: ValidateOptions): Analysis;
 declare function neutralize(value: string): string;
 
-export { type Analysis, type Ast, AstVersionError, DEFAULT_MAX_DEPTH, type Diagnostic, type ExtractResult, IncludeResolverError, NotImplementedError, type RenderOptions, SpintaxError, type ValidateOptions, analyze, extract, neutralize, parse, render, validate };
+export { type Analysis, type Ast, AstVersionError, DEFAULT_MAX_DEPTH, type Diagnostic, type ExtractResult, IncludeResolverError, NotImplementedError, type PluralIssue, type RenderOptions, SpintaxError, type ValidateOptions, analyze, extract, neutralize, normalizeBaseLang, parse, pluralArity, render, validate };