@spintax/core 0.3.3 → 0.4.0

package/CHANGELOG.md

@@ -3,6 +3,48 @@
 All notable changes to `@spintax/core` are documented here. This project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.4.0 — 2026-08-17
+
+### Added
+
+- **`plural.locale-missing` — a warning where `validate` used to be silent** (issue #65, reported
+  from a pipeline rendering ~1000 articles per campaign).
+
+  `validate` files no arity *verdict* without a locale, and that stays: the template may well be
+  correct for the locale the host will render with, so failing it here would fail a good template
+  for a fact the caller never claimed. But `render` has no such luxury — it resolves against the
+  2-form default — so a `{plural …}` block with any other form count reached finished text as the
+  fullwidth-brace fallback `｛plural …｝`, with nothing said upfront. Downstream checks that scan
+  for `{`/`}` do not see those braces.
+
+  The warning fires only where the risk is: **no locale normalized, and the form count is not the
+  render default**. A 2-form block stays silent, because the default resolves it. `valid` is
+  unchanged in every case (`valid ⇔ no error-severity diagnostic`), and supplying any locale
+  replaces the warning with the real verdict — nothing for `ru`, `plural.arity` for `en`.
+
+  Carries `data: { got, defaultArity }`. The default arity is derived from the same table `render`
+  uses rather than written as a literal, so the two cannot come to disagree.
+
+  Mirrored into `spintax/core`, the WordPress plugin and `spintax-core` (Python) in the same
+  change, and pinned by a corpus fixture. Note the gate's shape: the shared corpus asserts
+  diagnostics as a SUBSET, so it can pin that the warning IS emitted but not that it is absent on
+  a 2-form block — that negative control lives in each engine's own suite.
+
+## 0.3.4 — 2026-08-08
+
+Docs-only release — no engine changes; every byte of `dist/` behavior is 0.3.3's.
+
+### Changed
+
+- **README catches up with the ecosystem.** The parity paragraph now states the real contract —
+  one syntax surface across five independent engines (npm / Packagist / PyPI / Object Pascal /
+  the WordPress plugin) held by the shared 234-fixture corpus — instead of the original
+  two-engine wording. New "Using it without writing code" section and refreshed links:
+  the [`n8n-nodes-spintax`](https://www.npmjs.com/package/n8n-nodes-spintax) community node
+  (released 2026-08-07), the spintax.net playground, the Telegram bot, and Spintax Studio.
+  Internal spec-section references dropped from public copy.
+- **`package.json`**: description mentions the n8n node; `n8n` added to keywords.
+
 ## 0.3.3 — 2026-08-07
 
 `validate()` scales. No output changes anywhere: a 464-document differential over every

package/README.md

@@ -14,16 +14,20 @@ parse, render, validate, extract, analyze, and neutralize spintax templates.
 
 - **Zero runtime dependencies.** Runs unchanged on Cloudflare Workers, Node 18+, and in the browser.
 - **ESM-first, dual CJS.** Ships `.d.ts` types for both.
-- **Parity-verified against the [Spintax WordPress plugin](https://wordpress.org/plugins/spintax/).**
-  An *independent* TypeScript implementation (not a line-by-line port) held to the plugin's behavior
-  contract by a shared golden corpus — the **same** fixtures pass against both this engine and the
-  PHP plugin (deterministic verdicts, plural buckets, conditionals, `#set`/`#def` semantics,
-  post-process), with no divergence.
+- **One syntax contract, [five independent engines](https://spintax.net/spintax-engines/).**
+  This package, [`spintax/core`](https://packagist.org/packages/spintax/core) (PHP),
+  [`spintax-core`](https://pypi.org/project/spintax-core/) (Python), an Object Pascal engine, and
+  the [Spintax WordPress plugin](https://wordpress.org/plugins/spintax/) are all held to the same
+  behavior contract by a **shared golden corpus of 234 fixtures** — deterministic verdicts, plural
+  buckets, conditionals, `#set`/`#def` semantics and post-processing agree everywhere, so a
+  template is an asset you can move between runtimes, not a lock-in.
 - **MIT** licensed.
 
 > **Status: released & stable.** Feature-complete — parse / render / validate / extract / analyze /
-> neutralize. The deterministic golden corpus passes against **both** this engine and the PHP
-> plugin, and the §9.2 API is proven by a reference Cloudflare Worker (`examples/worker`).
+> neutralize — with the public API proven by real consumers: a reference Cloudflare Worker, the
+> [@spintaxnetbot](https://t.me/spintaxnetbot) Telegram bot, the
+> [spintax.net playground](https://spintax.net/play/), and the
+> [n8n community node](https://www.npmjs.com/package/n8n-nodes-spintax).
 
 ## Install
 
@@ -149,6 +153,19 @@ render('%bio%', { context: { bio: neutralize('Save {50|60}% today') }, postProce
 // → "Save {50|60}% today"   (the braces stay literal, not a random pick)
 ```
 
+## Using it without writing code
+
+- **n8n** — install [`n8n-nodes-spintax`](https://www.npmjs.com/package/n8n-nodes-spintax)
+  (Settings → Community Nodes). One node, five operations: Render, Render Many, a two-output
+  Validate, and the LLM authoring/repair prompt builders — a Sheets-to-outbox personalization
+  flow or a full AI authoring loop with no code and no credentials on the node's side.
+- **Telegram** — [@spintaxnetbot](https://t.me/spintaxnetbot): validate, preview, and AI-draft
+  templates in chat.
+- **Browser** — the [spintax.net playground](https://spintax.net/play/): live validation and
+  N-variant rendering, entirely client-side (it runs this very package).
+- **Windows** — [Spintax Studio](https://apps.microsoft.com/detail/9mw3ch7b530p), a native
+  editor in the Microsoft Store (renders via the family's Object Pascal engine; same corpus).
+
 ## Determinism & RNG
 
 With a `seed`, `render` is reproducible within this engine. Cross-engine RNG-sequence parity
@@ -157,10 +174,15 @@ plural buckets, conditional truthiness, `#set`/`#def` semantics, post-process ou
 
 ## Links
 
-- 📦 npm — [`@spintax/core`](https://www.npmjs.com/package/@spintax/core)
-- 🤖 Try it — [@spintaxnetbot](https://t.me/spintaxnetbot) (Telegram: validate + preview + AI `/draft`)
+- 📦 npm — [`@spintax/core`](https://www.npmjs.com/package/@spintax/core) ·
+  [`n8n-nodes-spintax`](https://www.npmjs.com/package/n8n-nodes-spintax) (the n8n node)
+- 🧪 Try it — [playground](https://spintax.net/play/) ·
+  [@spintaxnetbot](https://t.me/spintaxnetbot) (Telegram: validate + preview + AI `/draft`)
+- 🖥️ Desktop — [Spintax Studio](https://apps.microsoft.com/detail/9mw3ch7b530p) (Microsoft Store)
+- 🧬 The family — [all five engines, one corpus](https://spintax.net/spintax-engines/)
+  (PHP · Python · Pascal · WordPress)
 - 🧩 Source — [investblog/spintax-js](https://github.com/investblog/spintax-js)
-- 🌐 Product — [spintax.net](https://spintax.net)
+- 🌐 Docs & guides — [spintax.net](https://spintax.net)
 - 🏠 Maintainer — [301.st](https://301.st)
 
 ## License

package/dist/index.cjs

@@ -399,6 +399,7 @@ function pluralArity(baseLang) {
       return 2;
   }
 }
+var DEFAULT_PLURAL_ARITY = pluralArity("");
 function pluralFor(baseLang, n, forms) {
   const abs = Math.abs(n);
   const mod10 = abs % 10;
@@ -581,8 +582,8 @@ function checkPlurals(text, idx, locale, out) {
       out.push(err("plural.nested-brackets", "{plural ...}: forms must not contain nested spintax brackets. Extract via #def first \u2014 a #set is substituted verbatim and would put the brackets straight back.", at));
       continue;
     }
+    const count = block.formsRaw.split("|").length;
     if (arity > 0) {
-      const count = block.formsRaw.split("|").length;
       if (count !== arity) {
         out.push(err(
           "plural.arity",
@@ -590,6 +591,12 @@ function checkPlurals(text, idx, locale, out) {
           { ...at, data: { expected: arity, got: count } }
         ));
       }
+    } else if (count !== DEFAULT_PLURAL_ARITY) {
+      out.push(warn(
+        "plural.locale-missing",
+        `{plural ...}: ${count} forms, but no locale was supplied. render defaults to ${DEFAULT_PLURAL_ARITY} forms and leaves this block unresolved \u2014 pass the locale you will render with.`,
+        { ...at, data: { got: count, defaultArity: DEFAULT_PLURAL_ARITY } }
+      ));
     }
   }
 }