@spintax/core 0.1.6 → 0.2.0

package/dist/index.d.cts

@@ -22,6 +22,63 @@ 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 +126,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. */
@@ -107,6 +175,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 +207,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

@@ -22,6 +22,63 @@ 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 +126,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. */
@@ -107,6 +175,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 +207,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.js

@@ -342,6 +342,9 @@ function pluralArity(baseLang) {
     case "ru":
     case "uk":
     case "be":
+    case "sr":
+    case "hr":
+    case "bs":
       return 3;
     default:
       return 2;
@@ -355,6 +358,9 @@ function pluralFor(baseLang, n, forms) {
     case "ru":
     case "uk":
     case "be":
+    case "sr":
+    case "hr":
+    case "bs":
       if (mod10 === 1 && mod100 !== 11) return forms[0] ?? "";
       if (mod10 >= 2 && mod10 <= 4 && (mod100 < 12 || mod100 > 14)) return forms[1] ?? "";
       return forms[2] ?? "";
@@ -646,7 +652,13 @@ var MAX_VARIABLE_DEPTH = 50;
 var INCLUDE_LINE_RE = /^[ \t]*#include[ \t\n\r\f\x0B]+"([^"]+)"[ \t\n\r\f\x0B]*$/gmu;
 function renderAst(ast, ctx) {
   const vars = buildVars(ast.setDefs, ctx.runtimeContext, ctx.rng);
-  const text = renderNodes(ast.nodes, { vars, rng: ctx.rng, locale: ctx.locale, depth: 0 });
+  const text = renderNodes(ast.nodes, {
+    vars,
+    rng: ctx.rng,
+    locale: ctx.locale,
+    depth: 0,
+    onPluralError: ctx.onPluralError
+  });
   return ctx.resolver ? resolveIncludes(text, ctx) : text;
 }
 function resolveIncludes(text, ctx) {
@@ -749,17 +761,47 @@ function renderConditional(node, opts) {
 function renderPlural(node, opts) {
   const countRaw = expandVarsOnly(node.countRaw, opts);
   const formsRaw = expandVarsOnly(node.formsRaw, opts);
-  if (/[{}[\]]/u.test(formsRaw)) return fullwidthVerbatim(countRaw, formsRaw);
-  const count = phpTrim2(countRaw);
-  if (!/^-?\d+$/u.test(count)) return "";
   const base = normalizeBaseLang(opts.locale);
+  const report = (issue) => opts.onPluralError?.(issue);
+  if (/[{}[\]]/u.test(formsRaw)) {
+    report({
+      code: "plural.nested-brackets",
+      message: "Plural form slot contains nested spintax brackets; extract via #set first.",
+      construct: rawConstruct(countRaw, formsRaw),
+      locale: base
+    });
+    return fullwidthVerbatim(countRaw, formsRaw);
+  }
+  const count = phpTrim2(countRaw);
+  if (!/^-?\d+$/u.test(count)) {
+    report({
+      code: "plural.count",
+      message: `Plural count slot is empty or non-numeric (${JSON.stringify(count)}); block erased.`,
+      construct: rawConstruct(countRaw, formsRaw),
+      locale: base
+    });
+    return "";
+  }
   const forms = formsRaw.split("|").map((f) => phpTrim2(f));
-  if (forms.length !== pluralArity(base)) return fullwidthVerbatim(countRaw, formsRaw);
+  if (forms.length !== pluralArity(base)) {
+    report({
+      code: "plural.arity",
+      message: `Plural has ${forms.length} form(s); locale "${base}" takes ${pluralArity(base)}.`,
+      construct: rawConstruct(countRaw, formsRaw),
+      locale: base,
+      expected: pluralArity(base),
+      got: forms.length
+    });
+    return fullwidthVerbatim(countRaw, formsRaw);
+  }
   const picked = pluralFor(base, Number.parseInt(count, 10), forms);
   return renderNodes(parseSequence(picked), opts);
 }
+function rawConstruct(countRaw, formsRaw) {
+  return `{plural ${countRaw}:${formsRaw}}`;
+}
 function fullwidthVerbatim(countRaw, formsRaw) {
-  return `{plural ${countRaw}:${formsRaw}}`.replace(/\{/gu, "\uFF5B").replace(/\}/gu, "\uFF5D");
+  return rawConstruct(countRaw, formsRaw).replace(/\{/gu, "\uFF5B").replace(/\}/gu, "\uFF5D");
 }
 function renderEnumeration(options, opts) {
   if (options.length === 0) return "";
@@ -975,7 +1017,8 @@ function renderWith(input, rng, opts = {}) {
     locale: opts.locale ?? "",
     resolver: opts.includeResolver,
     maxDepth: opts.maxDepth ?? DEFAULT_MAX_DEPTH,
-    includeStack: []
+    includeStack: [],
+    onPluralError: opts.onPluralError
   };
   const ast = resolveAst(typeof input === "string" ? stripSentinels(input) : input);
   let out = renderAst(ast, ctx);
@@ -1012,6 +1055,12 @@ function hashString(s) {
 }
 
 // src/index.ts
+function normalizeBaseLang2(locale) {
+  return normalizeBaseLang(locale ?? "");
+}
+function pluralArity2(locale) {
+  return pluralArity(normalizeBaseLang2(locale));
+}
 function parse(src) {
   return parseTemplate(src);
 }
@@ -1062,6 +1111,6 @@ function neutralize2(value) {
   return neutralize(value);
 }
 
-export { AstVersionError, DEFAULT_MAX_DEPTH, IncludeResolverError, NotImplementedError, SpintaxError, analyze, extract, neutralize2 as neutralize, parse, render, validate };
+export { AstVersionError, DEFAULT_MAX_DEPTH, IncludeResolverError, NotImplementedError, SpintaxError, analyze, extract, neutralize2 as neutralize, normalizeBaseLang2 as normalizeBaseLang, parse, pluralArity2 as pluralArity, render, validate };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map