npm - @spintax/core - Versions diffs - 0.1.0 → 0.1.1 - Mend

@spintax/core 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -1,35 +1,47 @@
-# 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.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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -1,122 +1,144 @@
-# @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.
+- **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.
+## 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).