@spintax/core 0.1.6 → 0.2.0

package/CHANGELOG.md

@@ -3,6 +3,85 @@
 All notable changes to `@spintax/core` are documented here. This project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.2.0 — 2026-07-18
+
+Serbian, Croatian and Bosnian join the 3-form plural family; the plural error model and the
+locale helpers that go with it land in the same release. Minor, not patch: the BCS change
+below alters a **validation verdict**, which §0.1 classes as breaking.
+
+Nothing here shipped separately — 0.2.0 was never published, so these additions fold into it
+rather than minting a version between them. That matters for `@spintax/authoring-prompt`,
+whose peer range `>=0.2.0` would otherwise be satisfiable by a 0.2.0 without the exports it
+now imports at runtime.
+
+### Added
+
+- **`pluralArity(locale?)` and `normalizeBaseLang(locale?)` are public.** Exported so a
+  consumer that must AGREE with the engine about plurals can ask it instead of keeping a copy
+  of the table. The copy is not hypothetical: this repo's own authoring prompt kept one and it
+  drifted twice — once in content (a locale added here and not there) and once in shape
+  (`locale.slice(0, 2)`, which disagrees with this normalization on any 3-letter tag).
+
+  `pluralArity` takes a RAW locale and normalizes internally, unlike the internal helper of the
+  same name — a public function answering 2 for `sr-Latn` would be a trap. Both accept an absent
+  locale, matching `RenderOptions.locale?` / `ValidateOptions.locale?`, so the same optional
+  value can be threaded straight through.
+
+  Note one asymmetry: an absent locale makes `validate()` skip the arity check entirely, while
+  `pluralArity` answers the 2-form default `render()` would apply. It tells you what render will
+  do, not what validate will enforce.
+
+  `findPluralBlocks` is deliberately NOT exported alongside them — it returns byte offsets into
+  the source, and publishing it would freeze a parser internal and invite consumers onto the
+  parse layer, the same reason `Ast` is opaque.
+
+- **`RenderOptions.onPluralError` — an observer for unresolvable `{plural …}` blocks.**
+  The port of the plugin's `on_error` callable, and the missing half of its error model:
+  this engine already behaved exactly like the plugin's *lenient* mode (arity mismatch and
+  nested-bracket errors degrade to fullwidth-brace verbatim, an unresolved count erases the
+  block), but there was no way to learn that it had happened.
+
+  Observation only. Output is byte-identical with and without the callback, and `render()`
+  still never throws on template content (§9.3) — the host decides whether a report is
+  fatal. A report carries the diagnostic `code`, the construct **as the renderer saw it**
+  (after variable expansion), the normalized `locale`, and `expected`/`got` for arity.
+
+  The `plural.count` code has no `validate()` counterpart on purpose: an unresolved count is
+  a runtime-value fact that static analysis cannot see. It is also the case that most needs
+  the seam — erasing leaves no trace, so a host persisting a render otherwise cannot tell an
+  unsubstituted `%Var%` from copy that was meant to be empty.
+
+- **BCS plural buckets — `sr`, `hr`, `bs`.** On integers, BCS shares the East-Slavic rule
+  character for character (`mod10===1 && mod100!==11` → one; `mod10∈[2,4] && mod100∉[12,14]`
+  → few; else → many), so it reuses that branch rather than getting its own. CLDR names the
+  third bucket `other` rather than `many` — positionally the same slot. The genuine
+  BCS/East-Slavic divergence is fractional-only and unreachable here, since a non-numeric
+  count slot is erased to `''` before the bucket math (§3.1).
+
+  **Script and region subtags carry no plural grammar.** `sr-Latn`, `sr-Cyrl` and `sr_RS` all
+  normalise to `sr` and pick identical buckets; the script lives only in the author's form text.
+  Corpus fixtures pin each form, and the arity fixtures pin that a script subtag does not rescue
+  a 2-form template. The ladder runs past two digits, where `mod100` has to beat `mod10`: 101 is
+  `one`, 111 is not.
+
+  Render fixtures probe with `sat` (1 sat / 2 sata / 5 sati) because all three buckets differ
+  there. The tempting `bonus|bonusa|bonusa` collapses few and other, so it would pass against a
+  broken rule.
+
+  Landed in all three engines at once — `@spintax/core`, the WordPress plugin 2.5.0, and
+  `spintax/core` 0.2.0 — because plural buckets are a parity-required item and the golden
+  corpus gates every engine.
+
+### Changed
+
+- **BREAKING (verdict): `{plural 2: one|many}` under `sr`/`hr`/`bs` is now `plural.arity`.**
+  Previously these locales fell through to the EN-style 2-form default, so a 2-form BCS
+  template validated clean and rendered from the wrong bucket set. Any existing BCS template
+  must grow a third form. No other locale changes behaviour.
+- The LLM authoring prompt (`@spintax/authoring-prompt`) now emits a BCS grammar block —
+  agreement rules, the 3-bucket warning, and a "do not mix Latin and Cyrillic inside one
+  template" rule. Without it a model writes 2-form BCS that the validator then rejects.
+
 ## 0.1.6 — 2026-07-13
 
 Two post-process fixes. **Supersedes 0.1.5** — upgrade straight past it. No API change.

package/dist/index.cjs

@@ -344,6 +344,9 @@ function pluralArity(baseLang) {
     case "ru":
     case "uk":
     case "be":
+    case "sr":
+    case "hr":
+    case "bs":
       return 3;
     default:
       return 2;
@@ -357,6 +360,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] ?? "";
@@ -648,7 +654,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) {
@@ -751,17 +763,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 "";
@@ -977,7 +1019,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);
@@ -1014,6 +1057,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);
 }
@@ -1072,7 +1121,9 @@ exports.SpintaxError = SpintaxError;
 exports.analyze = analyze;
 exports.extract = extract;
 exports.neutralize = neutralize2;
+exports.normalizeBaseLang = normalizeBaseLang2;
 exports.parse = parse;
+exports.pluralArity = pluralArity2;
 exports.render = render;
 exports.validate = validate;
 //# sourceMappingURL=index.cjs.map