@spintax/core 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# 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.

package/LICENSE

@@ -0,0 +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.

package/README.md

@@ -0,0 +1,122 @@
+# @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.