@spintax/core 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -1,35 +1,58 @@
-# Changelog
-
-All notable changes to `@spintax/core` are documented here. This project adheres to
-[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## 0.1.0 — 2026-07-07
-
-First public release. Feature-complete engine; the TS suite passes the full **deterministic**
-golden corpus that encodes the Spintax WordPress plugin's behavior contract (validation verdicts,
-plural buckets, conditional truthiness, `#set` collapse, post-process output, enum/perm selection).
-Cross-engine execution of that corpus by the PHP plugin is the remaining verification gate (see Notes).
-
-### Added
-
-- `parse(input)` — opaque, versioned AST for reuse.
-- `render(input, opts)` — seeded, lenient rendering: enumerations, permutations (config +
-  per-element separators), variables (recursive), `#set` (collapse-once), conditionals, plurals
-  (locale buckets), `#include` (host-injected resolver, scope isolation, circular guard), and the
-  12-step cosmetic post-process (URL/email/domain/abbreviation shielding, spacing, capitalization).
-  Post-process defaults on; `postProcess: false` yields the raw pick.
-- `validate(input, opts)` — diagnostics with a parity-gated verdict (valid ⇔ no `error`);
-  `knownIncludes` / `knownVariables` options.
-- `extract(input)` — `{ refs, sets, includes }`.
-- `analyze(input, opts)` — extract + validate + a best-effort construct census.
-- `neutralize(value)` — text-safe shielding of data-derived input, with a mandatory safety-restore.
-
-### Notes
-
-- `render()` is lenient on depth: a circular / too-deep `#include` resolves to `''` (there is
-  **no** `MaxDepthExceededError`), matching the plugin. It throws only on a resolver that itself
-  throws (`IncludeResolverError`) or a foreign `Ast` (`AstVersionError`) — revised after the
-  reference-Worker dogfood surfaced the phantom error export.
-- Zero runtime dependencies; ESM-first with dual CJS. Node 18+, Cloudflare Workers, browser.
-- Cross-engine RNG-sequence parity with the PHP plugin is a non-goal; only deterministic behavior
-  is parity-gated. The PHP-side corpus runner is the remaining cross-engine verification gate.
+# Changelog
+
+All notable changes to `@spintax/core` are documented here. This project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 0.1.2 — 2026-07-08
+
+Docs. No engine or API changes.
+
+### Changed
+
+- **Cross-engine parity is now machine-verified.** The shared golden corpus was executed against
+  the actual PHP Spintax plugin engine (via the new `packages/conformance/php` runner) — 88 cases,
+  no divergence. Upgraded the README claim from "TS side; PHP execution pending" to parity-verified
+  against both engines.
+
+## 0.1.1 — 2026-07-08
+
+Docs + metadata. First release published from CI with **provenance** (npm Trusted Publishing).
+No engine or API changes.
+
+### Changed
+
+- npm `keywords` + `description` reworked for discoverability — spintax / text-spinning /
+  LLM-authoring workflow; dropped the obscure `gtw` tag.
+- README: badges, npm + [301.st](https://301.st) links, and LLM-pairing positioning (draft a
+  template with a model once, generate unlimited deterministic variations on-device).
+
+## 0.1.0 — 2026-07-07
+
+First public release. Feature-complete engine; the TS suite passes the full **deterministic**
+golden corpus that encodes the Spintax WordPress plugin's behavior contract (validation verdicts,
+plural buckets, conditional truthiness, `#set` collapse, post-process output, enum/perm selection).
+Cross-engine execution of that corpus by the PHP plugin is the remaining verification gate (see Notes).
+
+### Added
+
+- `parse(input)` — opaque, versioned AST for reuse.
+- `render(input, opts)` — seeded, lenient rendering: enumerations, permutations (config +
+  per-element separators), variables (recursive), `#set` (collapse-once), conditionals, plurals
+  (locale buckets), `#include` (host-injected resolver, scope isolation, circular guard), and the
+  12-step cosmetic post-process (URL/email/domain/abbreviation shielding, spacing, capitalization).
+  Post-process defaults on; `postProcess: false` yields the raw pick.
+- `validate(input, opts)` — diagnostics with a parity-gated verdict (valid ⇔ no `error`);
+  `knownIncludes` / `knownVariables` options.
+- `extract(input)` — `{ refs, sets, includes }`.
+- `analyze(input, opts)` — extract + validate + a best-effort construct census.
+- `neutralize(value)` — text-safe shielding of data-derived input, with a mandatory safety-restore.
+
+### Notes
+
+- `render()` is lenient on depth: a circular / too-deep `#include` resolves to `''` (there is
+  **no** `MaxDepthExceededError`), matching the plugin. It throws only on a resolver that itself
+  throws (`IncludeResolverError`) or a foreign `Ast` (`AstVersionError`) — revised after the
+  reference-Worker dogfood surfaced the phantom error export.
+- Zero runtime dependencies; ESM-first with dual CJS. Node 18+, Cloudflare Workers, browser.
+- Cross-engine RNG-sequence parity with the PHP plugin is a non-goal; only deterministic behavior
+  is parity-gated. The PHP-side corpus runner is the remaining cross-engine verification gate.

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 301st (https://301.st)
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 301st (https://301.st)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,122 +1,145 @@
-# @spintax/core
-
-Framework-agnostic **[spintax](https://spintax.net) engine** for JavaScript / TypeScript —
-parse, render, validate, extract, analyze, and neutralize GTW-compatible 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.
-- **Built to the [Spintax WordPress plugin](https://wordpress.org/plugins/spintax/)'s behavior
-  contract** via a shared golden corpus — an *independent* TypeScript implementation, not a
-  line-by-line port. The TS suite passes the full deterministic corpus; cross-engine execution
-  of that corpus by the PHP plugin is pending.
-- **MIT** licensed.
-
-> **Status: `0.1.0`** — first public release. Feature-complete; passes the full deterministic
-> golden corpus (encoding the plugin's contract, TS side); the §9.2 API is proven by a reference
-> Cloudflare Worker (`examples/worker`).
-
-## Install
-
-```sh
-npm install @spintax/core
-```
-
-## Quick start
-
-```ts
-import { render, validate, extract } from '@spintax/core';
-
-render('{Hello|Hi|Hey} %name%!', { context: { name: 'Ada' }, seed: 42 });
-// → "Hi Ada!"  (deterministic for a given seed; post-processed by default)
-
-validate('{a|b');          // → [{ severity: 'error', code: 'bracket.unclosed', … }]
-extract('%title% {?promo?Sale}'); // → { refs: ['title', 'promo'], sets: [], includes: [] }
-```
-
-## Spintax syntax
-
-| Construct | Example | Meaning |
-| --- | --- | --- |
-| Enumeration | `{a\|b\|c}` | pick one (nestable: `{a\|{b\|c}}`) |
-| Permutation | `[a\|b\|c]` | pick N, shuffle, join — `[<minsize=1;maxsize=2;sep=", ">a\|b\|c]` |
-| Variable | `%var%` | substitute a context value |
-| Local set | `#set %v% = value` | define a variable (one line) |
-| Conditional | `{?VAR?then\|else}` | `then` if `VAR` is truthy, else `else` |
-| Plural | `{plural %n%: one\|few\|many}` | grammatical agreement by locale |
-| Include | `#include "slug-or-id"` | embed another template (host-resolved) |
-| Comment | `/# … #/` | stripped before rendering |
-
-## API
-
-All functions accept a `string` **or** a parsed `Ast` (from `parse`) as their first argument.
-
-### `render(input, options?): string`
-
-Renders a template to a single string. **Lenient** — never throws on malformed markup (a bad
-block is emitted verbatim with fullwidth braces `｛…｝`). Cosmetic post-processing (spacing,
-capitalization, URL/email shielding) is **on by default**.
-
-```ts
-render(input, {
-  context?:         Record<string, string>,   // variable map
-  seed?:            number | string,           // deterministic RNG; omit ⇒ random
-  locale?:          string,                     // plural buckets, e.g. 'ru' (3-form)
-  includeResolver?: (ref: string) => string | null,  // host-injected, synchronous
-  postProcess?:     boolean,                    // default true; false ⇒ raw pick
-  maxDepth?:        number,                      // #include / nesting guard (default 20)
-});
-```
-
-`#include` is resolved only when you pass an `includeResolver`; child templates inherit the
-runtime context but **not** the parent's `#set` locals. Circular / too-deep includes resolve to
-`''` (lenient).
-
-### `validate(input, options?): Diagnostic[]`
-
-Returns diagnostics. A template is **valid** ⇔ no diagnostic has `severity: 'error'`. An
-unresolved `%var%` is a `warning`, not an error.
-
-```ts
-validate(input, {
-  locale?:         string,             // locale-aware plural-arity verdicts
-  knownIncludes?:  readonly string[],  // enables "unknown #include target" errors
-  knownVariables?: readonly string[],  // suppresses undefined-variable warnings
-});
-// Diagnostic: { severity, code, message, line, column, endLine?, endColumn?, data? }
-```
-
-### `extract(input): { refs, sets, includes }`
-
-Variable references (`%var%`, `{?…}`, plural counts), `#set` names, and `#include` targets.
-
-### `analyze(input, options?): Analysis`
-
-`extract` + `validate` + a best-effort `constructs` census (`{ enumeration, permutation,
-variable, conditional, plural, set, include }`). The census counts author-visible constructs;
-it is **not** a variant-cardinality promise.
-
-### `parse(input): Ast`
-
-Parses once for reuse. `Ast` is **opaque and versioned** — pass it back to the other functions,
-do not introspect or persist it across engine versions.
-
-### `neutralize(value): string`
-
-Shields data-derived (untrusted) text so it can't be re-interpreted as spintax markup — use it
-on any value you inject via `context` that isn't author-controlled. It is **text-safe**
-(round-trips to literal glyphs in any sink), not HTML/XSS escaping.
-
-```ts
-render('%bio%', { context: { bio: neutralize('Save {50|60}% today') }, postProcess: false });
-// → "Save {50|60}% today"   (the braces stay literal, not a random pick)
-```
-
-## Determinism & RNG
-
-With a `seed`, `render` is reproducible within this engine. Cross-engine RNG-sequence parity
-with the PHP plugin is a **non-goal** — only the *deterministic* behavior (validation verdicts,
-plural buckets, conditional truthiness, `#set` collapse, post-process output) is parity-gated.
-
-## License
-
-[MIT](../../LICENSE). The Spintax WordPress plugin remains GPL; MIT/Expat is GPL-compatible.
+# @spintax/core
+
+[![npm](https://img.shields.io/npm/v/@spintax/core.svg)](https://www.npmjs.com/package/@spintax/core)
+[![npm downloads](https://img.shields.io/npm/dm/@spintax/core.svg)](https://www.npmjs.com/package/@spintax/core)
+[![CI](https://github.com/investblog/spintax-js/actions/workflows/ci.yml/badge.svg)](https://github.com/investblog/spintax-js/actions/workflows/ci.yml)
+[![types](https://img.shields.io/npm/types/@spintax/core.svg)](https://www.npmjs.com/package/@spintax/core)
+[![license](https://img.shields.io/npm/l/@spintax/core.svg)](https://github.com/investblog/spintax-js/blob/main/LICENSE)
+
+Framework-agnostic **[spintax](https://spintax.net) engine** for JavaScript / TypeScript —
+parse, render, validate, extract, analyze, and neutralize spintax templates.
+
+> **Pairs naturally with LLMs.** Have a model draft a spintax template once, then generate
+> unlimited variations on-device — deterministic, free, and offline, with no per-generation
+> API calls. The LLM handles creativity; the engine handles scale.
+
+- **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` collapse, post-process),
+  with no divergence.
+- **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`).
+
+## Install
+
+```sh
+npm install @spintax/core
+```
+
+## Quick start
+
+```ts
+import { render, validate, extract } from '@spintax/core';
+
+render('{Hello|Hi|Hey} %name%!', { context: { name: 'Ada' }, seed: 42 });
+// → "Hi Ada!"  (deterministic for a given seed; post-processed by default)
+
+validate('{a|b');          // → [{ severity: 'error', code: 'bracket.unclosed', … }]
+extract('%title% {?promo?Sale}'); // → { refs: ['title', 'promo'], sets: [], includes: [] }
+```
+
+## Spintax syntax
+
+| Construct | Example | Meaning |
+| --- | --- | --- |
+| Enumeration | `{a\|b\|c}` | pick one (nestable: `{a\|{b\|c}}`) |
+| Permutation | `[a\|b\|c]` | pick N, shuffle, join — `[<minsize=1;maxsize=2;sep=", ">a\|b\|c]` |
+| Variable | `%var%` | substitute a context value |
+| Local set | `#set %v% = value` | define a variable (one line) |
+| Conditional | `{?VAR?then\|else}` | `then` if `VAR` is truthy, else `else` |
+| Plural | `{plural %n%: one\|few\|many}` | grammatical agreement by locale |
+| Include | `#include "slug-or-id"` | embed another template (host-resolved) |
+| Comment | `/# … #/` | stripped before rendering |
+
+## API
+
+All functions accept a `string` **or** a parsed `Ast` (from `parse`) as their first argument.
+
+### `render(input, options?): string`
+
+Renders a template to a single string. **Lenient** — never throws on malformed markup (a bad
+block is emitted verbatim with fullwidth braces `｛…｝`). Cosmetic post-processing (spacing,
+capitalization, URL/email shielding) is **on by default**.
+
+```ts
+render(input, {
+  context?:         Record<string, string>,   // variable map
+  seed?:            number | string,           // deterministic RNG; omit ⇒ random
+  locale?:          string,                     // plural buckets, e.g. 'ru' (3-form)
+  includeResolver?: (ref: string) => string | null,  // host-injected, synchronous
+  postProcess?:     boolean,                    // default true; false ⇒ raw pick
+  maxDepth?:        number,                      // #include / nesting guard (default 20)
+});
+```
+
+`#include` is resolved only when you pass an `includeResolver`; child templates inherit the
+runtime context but **not** the parent's `#set` locals. Circular / too-deep includes resolve to
+`''` (lenient).
+
+### `validate(input, options?): Diagnostic[]`
+
+Returns diagnostics. A template is **valid** ⇔ no diagnostic has `severity: 'error'`. An
+unresolved `%var%` is a `warning`, not an error.
+
+```ts
+validate(input, {
+  locale?:         string,             // locale-aware plural-arity verdicts
+  knownIncludes?:  readonly string[],  // enables "unknown #include target" errors
+  knownVariables?: readonly string[],  // suppresses undefined-variable warnings
+});
+// Diagnostic: { severity, code, message, line, column, endLine?, endColumn?, data? }
+```
+
+### `extract(input): { refs, sets, includes }`
+
+Variable references (`%var%`, `{?…}`, plural counts), `#set` names, and `#include` targets.
+
+### `analyze(input, options?): Analysis`
+
+`extract` + `validate` + a best-effort `constructs` census (`{ enumeration, permutation,
+variable, conditional, plural, set, include }`). The census counts author-visible constructs;
+it is **not** a variant-cardinality promise.
+
+### `parse(input): Ast`
+
+Parses once for reuse. `Ast` is **opaque and versioned** — pass it back to the other functions,
+do not introspect or persist it across engine versions.
+
+### `neutralize(value): string`
+
+Shields data-derived (untrusted) text so it can't be re-interpreted as spintax markup — use it
+on any value you inject via `context` that isn't author-controlled. It is **text-safe**
+(round-trips to literal glyphs in any sink), not HTML/XSS escaping.
+
+```ts
+render('%bio%', { context: { bio: neutralize('Save {50|60}% today') }, postProcess: false });
+// → "Save {50|60}% today"   (the braces stay literal, not a random pick)
+```
+
+## Determinism & RNG
+
+With a `seed`, `render` is reproducible within this engine. Cross-engine RNG-sequence parity
+with the PHP plugin is a **non-goal** — only the *deterministic* behavior (validation verdicts,
+plural buckets, conditional truthiness, `#set` collapse, post-process output) is parity-gated.
+
+## Links
+
+- 📦 npm — [`@spintax/core`](https://www.npmjs.com/package/@spintax/core)
+- 🧩 Source — [investblog/spintax-js](https://github.com/investblog/spintax-js)
+- 🌐 Product — [spintax.net](https://spintax.net)
+- 🏠 Maintainer — [301.st](https://301.st)
+
+## License
+
+[MIT](https://github.com/investblog/spintax-js/blob/main/LICENSE). The Spintax WordPress plugin
+remains GPL; MIT/Expat is GPL-compatible.
+
+---
+
+Part of the [301.st](https://301.st) toolset. Product home: [spintax.net](https://spintax.net).