@spintax/core 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -3,6 +3,75 @@
 All notable changes to `@spintax/core` are documented here. This project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.3.0 — 2026-07-19
+
+`#set` goes back to being a macro and a new `#def` carries roll-once. Breaking: it changes what
+existing templates mean. Ships in lockstep with the WordPress plugin 3.0.0, `spintax/core` and the
+OpenCart port; the corpus landed last, after both PHP engines.
+
+### Changed
+
+- **`#set` is a macro.** The value is substituted at every `%var%` reference and whatever brackets
+  it holds resolve independently each time. Until now an enumeration-valued `#set` collapsed once at
+  set-time; that behaviour moved to `#def`.
+
+  Worth recording *why* the revert, because the reasoning is not recoverable from the diff:
+  collapse-once was the newcomer. It shipped in the plugin on 2026-07-04, was announced in one
+  changelog line, and contradicted the project's published documentation from the day it landed.
+  Macro expansion is what the engine did before that and what consumers written against those docs
+  assume.
+
+- **`AST_VERSION` 1 → 2.** `ParsedAst` gained `defDefs`. An `Ast` cached by an older version carries
+  no definition map, so rendering it would silently drop every `#def`; the version guard turns that
+  into an `AstVersionError` instead.
+
+- **`extract()` reports `defs`** alongside `sets`. Additive for readers, but a consumer building a
+  variable list from `sets` alone will now miss `#def` names.
+
+- **`plural.nested-brackets` advice.** "Extract via `#set` first" was correct under collapse-once and
+  is wrong under a macro — the value is substituted verbatim and puts the brackets straight back into
+  the form slot, raising the very error it was meant to avoid. It now says `#def`.
+
+### Added
+
+- **`#def %var% = value` — roll-once.** The value is rendered once per render, as if it were a
+  miniature body, and the result is held for every reference. It covers enumerations *and*
+  permutations, resolves **after** the merged context exists (so it can read globals and runtime
+  variables; a runtime variable of the same name outranks it), and resolves in dependency order —
+  an order that follows aliases **through** macro values, since a `#def` can reach another `#def` by
+  way of a `#set` expanded only at reference time.
+
+  This is where a plural counter now lives: `#def %n% = {1|4|9}` then `{plural %n%: …}` prints and
+  agrees the same number. Under `#set` the two disagree and the block is dropped.
+
+- **Four diagnostics**: `def.malformed`, `definition.duplicate-name` (a name belongs to one
+  directive, once — this also closes silently-last-wins duplicate `#set`s), `def.include-in-value`
+  (includes resolve after a value is frozen; legal inside a `#set`), and `plural.count-macro`.
+
+  `plural.count-macro` is decided by **stage order, not bracket type**: conditionals resolve before
+  plurals and are exempt, enumerations and permutations resolve after and are not, and a nested
+  `{plural …}` resolves in the *same* pass so it is not exempt either. Taint propagates through
+  `#set` → `#set` references to a fixpoint.
+
+### Corpus
+
+The difference between the directives is a difference in how many RNG draws a render consumes, so
+seeded-sequence fixtures pin it exactly and cross-engine — `set/macro-re-rolls-at-every-reference`
+and `def/rolled-once-and-held` share a template and a sequence and differ only in whether the second
+draw is reached. The corpus grew 138 → 160 cases, green against this engine, the WordPress plugin
+and `spintax/core`.
+
+The previous rule here said collapse could only be pinned with RNG-free values, and the consequence
+was that **nothing pinned it at all**: the semantics flipped in the plugin without a single fixture
+noticing. All-identical alternatives are not sufficient either — they render the same under both
+semantics and would pass against an engine implementing `#def` as an alias of `#set`.
+
+### Migration
+
+A `#set` whose value is an enumeration or permutation *and* which is referenced more than once for
+consistency — a plural counter, a brand name that must not vary mid-sentence — becomes `#def`. One
+line per definition; references are untouched.
+
 ## 0.2.0 — 2026-07-18
 
 Serbian, Croatian and Bosnian join the 3-form plural family; the plural error model and the

package/README.md

@@ -17,8 +17,8 @@ parse, render, validate, extract, analyze, and neutralize spintax templates.
 - **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.
+  PHP plugin (deterministic verdicts, plural buckets, conditionals, `#set`/`#def` semantics,
+  post-process), with no divergence.
 - **MIT** licensed.
 
 > **Status: released & stable.** Feature-complete — parse / render / validate / extract / analyze /
@@ -77,7 +77,8 @@ dedupe in the host and cap the retries: a template may simply not have N combina
 | 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) |
+| Local set | `#set %v% = value` | define a macro — re-picked at every use |
+| Local def | `#def %v% = value` | define a value — picked once per render, held at every use |
 | 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) |

package/dist/index.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
 // src/internal/ast.ts
-var AST_VERSION = 1;
+var AST_VERSION = 2;
 function walk(nodes, visit) {
   for (const n of nodes) {
     visit(n);
@@ -25,21 +25,39 @@ function isParsedAst(value) {
 
 // src/internal/parser.ts
 var VARIABLE_RE = /^%(\w+)%/;
-var SET_DIRECTIVE_RE = /^[ \t]*#set[ \t]+%(\w+)%[ \t]*=[ \t]*(.*?)[ \t]*\r?$/gmu;
+var DIRECTIVE_RE = /^[ \t]*#(set|def)[ \t]+%(\w+)%[ \t]*=[ \t]*(.*?)[ \t]*\r?$/gmu;
 var CONDITIONAL_NAME_RE = /^[A-Za-z_]\w*/;
 var PLURAL_PREFIX = "plural ";
 function parseTemplate(src) {
-  const { body, setDefs } = extractSetDirectives(stripComments(src));
-  return { astVersion: AST_VERSION, source: src, setDefs, nodes: parseSequence(body) };
+  const { body, setDefs, defDefs } = extractDirectives(stripComments(src));
+  return { astVersion: AST_VERSION, source: src, setDefs, defDefs, nodes: parseSequence(body) };
 }
-function extractSetDirectives(text) {
+function extractDirectives(text) {
   const setDefs = {};
-  SET_DIRECTIVE_RE.lastIndex = 0;
-  const stripped = text.replace(SET_DIRECTIVE_RE, (_full, name, value) => {
-    setDefs[name.toLowerCase()] = value;
-    return "";
-  });
-  return { body: stripped.replace(/\n{3,}/gu, "\n\n"), setDefs };
+  const defDefs = {};
+  const occurrences = [];
+  DIRECTIVE_RE.lastIndex = 0;
+  const stripped = text.replace(
+    DIRECTIVE_RE,
+    (full, kind, rawName, value, offset) => {
+      const name = rawName.toLowerCase();
+      occurrences.push({
+        kind,
+        name,
+        value,
+        line: countLines(text, offset)
+      });
+      if (kind === "def") defDefs[name] = value;
+      else setDefs[name] = value;
+      return "";
+    }
+  );
+  return { body: stripped.replace(/\n{3,}/gu, "\n\n"), setDefs, defDefs, occurrences };
+}
+function countLines(text, offset) {
+  let line = 1;
+  for (let i = 0; i < offset; i += 1) if (text[i] === "\n") line += 1;
+  return line;
 }
 function stripComments(text) {
   return text.replace(/\/#[\s\S]*?#\//g, "");
@@ -378,7 +396,7 @@ function validateTemplate(src, opts = {}) {
   const diagnostics = [];
   const text = stripComments(src);
   checkBrackets(text, diagnostics);
-  checkSetDirectives(text, diagnostics);
+  checkDirectives(text, diagnostics);
   checkPermutationConfigs(text, diagnostics);
   checkPlurals(text, opts.locale, diagnostics);
   checkVariableReferences(text, opts.knownVariables, diagnostics);
@@ -437,17 +455,43 @@ function checkBrackets(text, out) {
     out.push(err("bracket.unclosed", `Unclosed '${unclosed.char}'.`, { line: unclosed.line, column: unclosed.column, endLine: unclosed.line, endColumn: unclosed.column + 1, data: { bracket: unclosed.char } }));
   }
 }
-function checkSetDirectives(text, out) {
+function checkDirectives(text, out) {
   const lines = text.split("\n");
   lines.forEach((lineText, idx) => {
     const trimmed = lineText.replace(/^[ \t]+/, "");
-    if (!trimmed.startsWith("#set ") && !trimmed.startsWith("#set	")) return;
-    if (!/^#set\s+%(\w+)%\s*=\s*(.+)$/u.test(trimmed)) {
+    const kind = ["#set", "#def"].find(
+      (candidate) => trimmed.startsWith(`${candidate} `) || trimmed.startsWith(`${candidate}	`)
+    );
+    if (!kind) return;
+    DIRECTIVE_RE.lastIndex = 0;
+    if (!DIRECTIVE_RE.test(trimmed)) {
       const column = lineText.length - trimmed.length + 1;
       const line = idx + 1;
-      out.push(err("set.malformed", "Malformed #set. Expected: #set %name% = value", { line, column, endLine: line, endColumn: lineText.length + 1 }));
+      const code = kind === "#def" ? "def.malformed" : "set.malformed";
+      out.push(err(code, `Malformed ${kind}. Expected: ${kind} %name% = value`, { line, column, endLine: line, endColumn: lineText.length + 1 }));
     }
   });
+  const { occurrences } = extractDirectives(text);
+  const seen = /* @__PURE__ */ new Map();
+  for (const occurrence of occurrences) {
+    const first = seen.get(occurrence.name);
+    if (first !== void 0) {
+      out.push(err(
+        "definition.duplicate-name",
+        `Variable '${occurrence.name}' is defined more than once (first on line ${first}). A name belongs to one directive, once.`,
+        { line: occurrence.line, column: 1 }
+      ));
+    } else {
+      seen.set(occurrence.name, occurrence.line);
+    }
+    if (occurrence.kind === "def" && /#include\b/u.test(occurrence.value)) {
+      out.push(err(
+        "def.include-in-value",
+        `#include cannot appear in a #def value ('${occurrence.name}'): includes resolve after the value is frozen. Use #set, or put the #include in the body.`,
+        { line: occurrence.line, column: 1 }
+      ));
+    }
+  }
 }
 function checkPermutationConfigs(text, out) {
   for (const m of text.matchAll(/\[<([^>]*?)>/gu)) {
@@ -485,10 +529,20 @@ function checkPermutationConfigs(text, out) {
 function checkPlurals(text, locale, out) {
   const base = locale && locale !== "" ? normalizeBaseLang(locale) : "";
   const arity = base !== "" ? pluralArity(base) : 0;
+  const tainted = macroTaintedNames(text);
   for (const block of findPluralBlocks(text)) {
     const at = span(text, block.start, block.end - block.start);
+    for (const m of block.countSlot.matchAll(/%(\w+)%/gu)) {
+      const name = (m[1] ?? "").toLowerCase();
+      if (!tainted.has(name)) continue;
+      out.push(err(
+        "plural.count-macro",
+        `{plural ...}: the count '${m[1]}' is a #set macro, so it is still unresolved spintax when the plural is decided and the block renders empty. Define it with #def instead.`,
+        at
+      ));
+    }
     if (/[{}[\]]/.test(block.formsRaw)) {
-      out.push(err("plural.nested-brackets", "{plural ...}: forms must not contain nested spintax brackets.", at));
+      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;
     }
     if (arity > 0) {
@@ -503,11 +557,33 @@ function checkPlurals(text, locale, out) {
     }
   }
 }
+var UNRESOLVED_AT_PLURAL_TIME = /\[|\{(?!\?)/u;
+function macroTaintedNames(text) {
+  const macros = extractDirectives(text).setDefs;
+  const tainted = /* @__PURE__ */ new Set();
+  for (const [name, value] of Object.entries(macros)) {
+    if (UNRESOLVED_AT_PLURAL_TIME.test(value)) tainted.add(name);
+  }
+  let grew = true;
+  while (grew) {
+    grew = false;
+    for (const [name, value] of Object.entries(macros)) {
+      if (tainted.has(name)) continue;
+      for (const m of value.matchAll(/%(\w+)%/gu)) {
+        if (!tainted.has((m[1] ?? "").toLowerCase())) continue;
+        tainted.add(name);
+        grew = true;
+        break;
+      }
+    }
+  }
+  return tainted;
+}
 function checkVariableReferences(text, known, out) {
   const knownSet = new Set((known ?? []).map((n) => n.toLowerCase()));
   const defs = /* @__PURE__ */ new Map();
   const defPos = /* @__PURE__ */ new Map();
-  for (const m of text.matchAll(/^[ \t]*#set[ \t]+%(\w+)%[ \t]*=[ \t]*(.*?)$/gmu)) {
+  for (const m of text.matchAll(/^[ \t]*#(?:set|def)[ \t]+%(\w+)%[ \t]*=[ \t]*(.*?)$/gmu)) {
     const name = (m[1] ?? "").toLowerCase();
     defs.set(name, m[2] ?? "");
     const nameOffset = (m.index ?? 0) + m[0].indexOf("%");
@@ -522,7 +598,7 @@ function checkVariableReferences(text, known, out) {
   for (const name of defs.keys()) {
     detectCycle(name, defs, [name], defPos.get(name) ?? somewhere, out);
   }
-  const body = text.replace(/^[ \t]*#set[ \t]+%\w+%[ \t]*=[ \t]*.*?$/gmu, (m) => m.replace(/[^\n]/g, " "));
+  const body = text.replace(/^[ \t]*#(?:set|def)[ \t]+%\w+%[ \t]*=[ \t]*.*?$/gmu, (m) => m.replace(/[^\n]/g, " "));
   const seen = /* @__PURE__ */ new Set();
   const undefinedAt = (name, offset, length) => {
     const key = name.toLowerCase();
@@ -569,19 +645,21 @@ function checkIncludeTargets(text, known, out) {
 
 // src/internal/extract.ts
 var SET_DEF_RE = /^[ \t]*#set[ \t]+%(\w+)%[ \t]*=/gmu;
-var SET_LHS_RE = /^[ \t]*#set[ \t]+%\w+%[ \t]*=/gmu;
+var DEF_DEF_RE = /^[ \t]*#def[ \t]+%(\w+)%[ \t]*=/gmu;
+var DEFINITION_LHS_RE = /^[ \t]*#(?:set|def)[ \t]+%\w+%[ \t]*=/gmu;
 var INCLUDE_RE2 = /^[ \t]*#include[ \t\n\r\f\x0B]+"([^"]+)"[ \t\n\r\f\x0B]*$/gmu;
 var VARIABLE_RE2 = /%(\w+)%/gu;
 var CONDITIONAL_REF_RE = /\{\?!?([A-Za-z_]\w*)\?/gu;
 function extractFromSource(src) {
   const text = stripComments(src);
   const sets = collect(text, SET_DEF_RE, true);
+  const defs = collect(text, DEF_DEF_RE, true);
   const includes = collect(text, INCLUDE_RE2, false);
-  const body = text.replace(SET_LHS_RE, "");
+  const body = text.replace(DEFINITION_LHS_RE, "");
   const refs = /* @__PURE__ */ new Set();
   addAll(refs, body, VARIABLE_RE2, true);
   addAll(refs, body, CONDITIONAL_REF_RE, true);
-  return { refs: [...refs], sets, includes };
+  return { refs: [...refs], sets, defs, includes };
 }
 function collect(text, re, fold) {
   const seen = /* @__PURE__ */ new Set();
@@ -653,14 +731,15 @@ function stripSentinels(text) {
 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,
+  const base = buildVars(ast.setDefs, ctx.runtimeContext);
+  const walkOpts = {
     rng: ctx.rng,
     locale: ctx.locale,
     depth: 0,
     onPluralError: ctx.onPluralError
-  });
+  };
+  const vars = Object.keys(ast.defDefs).length > 0 ? { ...base, ...rollDefinitions(ast.defDefs, base, ctx.runtimeContext, walkOpts) } : base;
+  const text = renderNodes(ast.nodes, { ...walkOpts, vars });
   return ctx.resolver ? resolveIncludes(text, ctx) : text;
 }
 function resolveIncludes(text, ctx) {
@@ -682,33 +761,65 @@ function resolveIncludes(text, ctx) {
     });
   });
 }
-function buildVars(setDefs, context, rng) {
+function buildVars(setDefs, context) {
   const vars = {};
   for (const [name, value] of Object.entries(setDefs)) {
-    vars[name] = collapseSetValue(value, rng);
+    vars[name] = value;
   }
   for (const [name, value] of Object.entries(context)) {
     vars[name.toLowerCase()] = value;
   }
   return vars;
 }
-function collapseSetValue(value, rng) {
-  if (!value.includes("{")) return value;
-  if (value.includes("{?") || value.includes("{plural ")) return value;
-  return resolveEnumerationsString(value, rng);
-}
-function resolveEnumerationsString(text, rng) {
-  let out = text;
-  for (let guard = 0; guard < 1e3; guard += 1) {
-    let changed = false;
-    out = out.replace(/\{([^{}]*)\}/gu, (_m, inner) => {
-      changed = true;
-      const options = splitTopLevelPipes(inner);
-      return options.length === 0 ? "" : options[randomInt(rng, 0, options.length - 1)] ?? "";
+function rollDefinitions(defDefs, vars, context, opts) {
+  const outranked = new Set(Object.keys(context).map((key) => key.toLowerCase()));
+  const rolled = {};
+  const aliases = {};
+  for (const [name, value] of Object.entries(vars)) {
+    if (name in defDefs && !outranked.has(name)) continue;
+    aliases[name] = value;
+  }
+  for (const name of orderDefinitions(defDefs, aliases)) {
+    if (outranked.has(name)) continue;
+    const value = defDefs[name] ?? "";
+    rolled[name] = renderNodes(parseSequence(value), { ...opts, vars: { ...vars, ...rolled } });
+  }
+  return rolled;
+}
+function orderDefinitions(defDefs, aliases) {
+  const names = Object.keys(defDefs);
+  const blocked = /* @__PURE__ */ new Map();
+  for (const name of names) {
+    const reached = referencedNames(defDefs[name] ?? "", aliases);
+    blocked.set(name, new Set(names.filter((candidate) => reached.has(candidate))));
+  }
+  const ordered = [];
+  let pending = names;
+  while (pending.length > 0) {
+    const ready = pending.filter((name) => {
+      const deps = blocked.get(name);
+      return !deps || ![...deps].some((dep) => dep !== name && pending.includes(dep));
     });
-    if (!changed) break;
+    if (ready.length === 0) return [...ordered, ...pending];
+    ordered.push(...ready);
+    pending = pending.filter((name) => !ready.includes(name));
   }
-  return out;
+  return ordered;
+}
+function referencedNames(value, aliases) {
+  const seen = /* @__PURE__ */ new Set();
+  const queue = directReferences(value);
+  while (queue.length > 0) {
+    const name = queue.shift();
+    if (seen.has(name)) continue;
+    seen.add(name);
+    const alias = aliases[name];
+    if (alias !== void 0) queue.push(...directReferences(alias));
+  }
+  return seen;
+}
+function directReferences(text) {
+  return [...text.matchAll(/%(\w+)%/gu)].map((match) => (match[1] ?? "").toLowerCase());
 }
 function renderNodes(nodes, opts) {
   let out = "";
@@ -867,26 +978,6 @@ function padSeparator(sep) {
   if (/^\p{L}+$/u.test(trimmed)) return ` ${trimmed} `;
   return sep;
 }
-function splitTopLevelPipes(inner) {
-  const parts = [];
-  let brace = 0;
-  let bracket = 0;
-  let cur = "";
-  for (const ch of inner) {
-    if (ch === "{") brace += 1;
-    else if (ch === "}") brace -= 1;
-    else if (ch === "[") bracket += 1;
-    else if (ch === "]") bracket -= 1;
-    if (ch === "|" && brace === 0 && bracket === 0) {
-      parts.push(cur);
-      cur = "";
-    } else {
-      cur += ch;
-    }
-  }
-  parts.push(cur);
-  return parts;
-}
 var PHP_LTRIM_RE2 = /^[ \t\n\r\0\x0B]+/u;
 var PHP_RTRIM_RE2 = /[ \t\n\r\0\x0B]+$/u;
 function phpTrim2(s) {