@spintax/core 0.1.5 → 0.2.0

package/CHANGELOG.md

@@ -3,6 +3,123 @@
 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.
+
+### Fixed
+
+- **A run of sentence punctuation is no longer split from the inside.** This is not a Spanish issue
+  and it predates the 0.1.5 work: the "space after `.!?`" rule looked exactly one character ahead
+  and never at the rest of the run, so it fired *between* the marks.
+
+  ```
+  wait... what?   →  Wait. . . What?      (0.1.5 and earlier)
+  wow!!!          →  Wow! ! !
+  really?!        →  Really? !
+  ```
+
+  The ASCII ellipsis is the common casualty — and the Unicode `…` is *not* in the `[.!?]` class,
+  which is exactly why the corpus's existing ellipsis fixture never caught it. A run is now matched
+  whole and required to be complete: `([.!?]+)(?![.!?])`. The guard is load-bearing — a greedy `+`
+  alone gives ground back *into* the run to satisfy the lookaheads and yields `Wow!! !`.
+
+- **`¡¿Qué haces?!` keeps its capital.** The 0.1.5 opener rule allowed exactly *one* opener, so the
+  RAE form for a sentence that is both a question and an exclamation — the most Spanish sentence
+  there is — still lost its capital. An opener followed by markup (`¿<strong>cómo</strong> estás?`,
+  `<p>¿<a href="/ayuda">necesitas ayuda</a>?</p>`) failed for the same reason: the old lead only
+  allowed `tags → opener → letter`, never `opener → tags → letter`.
+
+  The lead is now any run of tags, sentence openers and whitespace, in any order. The opener set
+  stays deliberately **narrow** — quotes and brackets are still not openers, and the fixtures added
+  in 0.1.5 keep guarding that.
+
+### Notes
+
+- Mirrored into the PHP plugin engine (released there as 2.3.3). Verified against the shared golden
+  corpus in both engines: TS 243 tests; the conformance runner against the real plugin engine 107
+  tests / 120 assertions. No performance regression — the pathological-input cost is unchanged from
+  0.1.5 and comes from the URL/domain shields, not from these rules.
+
 ## 0.1.5 — 2026-07-13
 
 Spanish post-process fix. 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 "";
@@ -914,18 +956,18 @@ var MULTI_ABBR_RE = new RegExp(`\\b(?:\\p{L}{1,2}\\.${S}*){2,}`, "gu");
 var SINGLE_ABBR_RE = new RegExp(`(?<![\\p{L}\\p{N}])(?:${SINGLE_ABBREVS.join("|")})\\.(?=${S}|$|<)`, "giu");
 var TRAILING_PUNCT_RE = /([.,;:!]+)$/u;
 var SENTENCE_OPENERS = "\xBF\xA1";
-var OPEN = `[${SENTENCE_OPENERS}]?${S}*`;
+var LEAD = `(?:<[^>]+>|[${SENTENCE_OPENERS}]|${S})*`;
 var SPACE_BEFORE_PUNCT_RE = new RegExp(`${S}+([,;:!?.])`, "gu");
 var SPACE_AFTER_COMMA_RE = new RegExp(`([,;:])(?!\\d)(?!${S}|$|<)`, "gu");
-var SPACE_AFTER_SENTENCE_RE = new RegExp(`([.!?])(?!\\d)(?!${S}|$|<)`, "gu");
+var SPACE_AFTER_SENTENCE_RE = new RegExp(`([.!?]+)(?![.!?])(?!\\d)(?!${S}|$|<)`, "gu");
 var SPACE_AFTER_OPENER_RE = new RegExp(`([${SENTENCE_OPENERS}])${S}+`, "gu");
-var CAP_FIRST_RE = new RegExp(`^(${S}*(?:<[^>]+>${S}*)*${OPEN})(\\p{Ll})`, "u");
-var CAP_AFTER_SENTENCE_RE = new RegExp(`([.!?\u2026])(${S}*(?:<\\/?[^>]+>${S}*)*${OPEN})(\\p{Ll})`, "gu");
+var CAP_FIRST_RE = new RegExp(`^(${LEAD})(\\p{Ll})`, "u");
+var CAP_AFTER_SENTENCE_RE = new RegExp(`([.!?\u2026])(${LEAD})(\\p{Ll})`, "gu");
 var CAP_AFTER_BLOCK_RE = new RegExp(
-  `(<\\/?(?:p|h[1-6]|li|blockquote|div|td|th)[^>]*>${S}*${OPEN})(\\p{Ll})`,
+  `(<\\/?(?:p|h[1-6]|li|blockquote|div|td|th)[^>]*>${LEAD})(\\p{Ll})`,
   "giu"
 );
-var CAP_AFTER_BREAK_RE = new RegExp(`(\\n${S}*${OPEN})(\\p{Ll})`, "gu");
+var CAP_AFTER_BREAK_RE = new RegExp(`(\\n${LEAD})(\\p{Ll})`, "gu");
 var up = (ch) => ch.toUpperCase();
 function postProcess(input) {
   const placeholders = /* @__PURE__ */ new Map();
@@ -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