@spintax/core 0.2.0 → 0.3.1

package/dist/index.d.cts

@@ -15,8 +15,14 @@
  *     the AST here.
  * Permutation's `<config>` + per-element separators are fully parsed (PR-11b).
  */
-/** Bumped only on a breaking change to the node shape (independent of syntax v1). */
-declare const AST_VERSION = 1;
+/**
+ * Bumped only on a breaking change to the node shape (independent of syntax v1).
+ *
+ * 2 — `ParsedAst` gained `defDefs`. An `Ast` cached by an older version carries no `#def` map, so
+ * rendering it would silently drop every definition; the version guard turns that into an
+ * `AstVersionError` instead.
+ */
+declare const AST_VERSION = 2;
 /** Opaque public handle (re-exported as `Ast` from the package index). */
 interface Ast {
     readonly astVersion: typeof AST_VERSION;
@@ -75,7 +81,7 @@ interface PluralIssue {
  * (which injects a fixture's `rng` strategy). Keeping the rng a parameter is what
  * lets the deterministic parity fixtures assert exact output.
  *
- * Order: strip stray sentinels → collapse-once #set + tree-walk (+ #include) →
+ * Order: strip stray sentinels → build vars, roll #def, tree-walk (+ #include) →
  * cosmetic post-process (if on) → mandatory neutralize safety-restore (always).
  */
 
@@ -166,7 +172,10 @@ interface Diagnostic {
 }
 interface ExtractResult {
     refs: string[];
+    /** Names defined by `#set` — macros, re-picked at every reference. */
     sets: string[];
+    /** Names defined by `#def` — rolled once per render and held. */
+    defs: string[];
     includes: string[];
 }
 interface Analysis extends ExtractResult {

package/dist/index.d.ts

@@ -15,8 +15,14 @@
  *     the AST here.
  * Permutation's `<config>` + per-element separators are fully parsed (PR-11b).
  */
-/** Bumped only on a breaking change to the node shape (independent of syntax v1). */
-declare const AST_VERSION = 1;
+/**
+ * Bumped only on a breaking change to the node shape (independent of syntax v1).
+ *
+ * 2 — `ParsedAst` gained `defDefs`. An `Ast` cached by an older version carries no `#def` map, so
+ * rendering it would silently drop every definition; the version guard turns that into an
+ * `AstVersionError` instead.
+ */
+declare const AST_VERSION = 2;
 /** Opaque public handle (re-exported as `Ast` from the package index). */
 interface Ast {
     readonly astVersion: typeof AST_VERSION;
@@ -75,7 +81,7 @@ interface PluralIssue {
  * (which injects a fixture's `rng` strategy). Keeping the rng a parameter is what
  * lets the deterministic parity fixtures assert exact output.
  *
- * Order: strip stray sentinels → collapse-once #set + tree-walk (+ #include) →
+ * Order: strip stray sentinels → build vars, roll #def, tree-walk (+ #include) →
  * cosmetic post-process (if on) → mandatory neutralize safety-restore (always).
  */
 
@@ -166,7 +172,10 @@ interface Diagnostic {
 }
 interface ExtractResult {
     refs: string[];
+    /** Names defined by `#set` — macros, re-picked at every reference. */
     sets: string[];
+    /** Names defined by `#def` — rolled once per render and held. */
+    defs: string[];
     includes: string[];
 }
 interface Analysis extends ExtractResult {

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/internal/ast.ts
-var AST_VERSION = 1;
+var AST_VERSION = 2;
 function walk(nodes, visit) {
   for (const n of nodes) {
     visit(n);
@@ -21,23 +21,66 @@ function isParsedAst(value) {
   return typeof value === "object" && value !== null && value.astVersion === AST_VERSION && typeof value.source === "string" && Array.isArray(value.nodes);
 }
 
+// src/internal/neutralize.ts
+var STRUCTURAL = ["{", "}", "[", "]", "%", "#"];
+var SENTINEL_BASE = 57344;
+var SHIELD = /* @__PURE__ */ new Map();
+var RESTORE = /* @__PURE__ */ new Map();
+STRUCTURAL.forEach((ch, i) => {
+  const sentinel = String.fromCharCode(SENTINEL_BASE + i);
+  SHIELD.set(ch, sentinel);
+  RESTORE.set(sentinel, ch);
+});
+var SHIELD_RE = /[{}[\]%#]/gu;
+var RESTORE_RE = new RegExp(
+  `[${String.fromCharCode(SENTINEL_BASE)}-${String.fromCharCode(SENTINEL_BASE + STRUCTURAL.length - 1)}]`,
+  "gu"
+);
+function neutralize(value) {
+  return value.replace(SHIELD_RE, (ch) => SHIELD.get(ch) ?? ch);
+}
+function safetyRestore(text) {
+  return text.replace(RESTORE_RE, (ch) => RESTORE.get(ch) ?? ch);
+}
+function stripSentinels(text) {
+  return text.replace(RESTORE_RE, "");
+}
+
 // 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(stripSentinels(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, "");
@@ -376,7 +419,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);
@@ -435,17 +478,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)) {
@@ -483,10 +552,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) {
@@ -501,11 +580,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("%");
@@ -520,7 +621,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();
@@ -567,19 +668,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();
@@ -622,43 +725,19 @@ var NotImplementedError = class extends SpintaxError {
   }
 };
 
-// src/internal/neutralize.ts
-var STRUCTURAL = ["{", "}", "[", "]", "%", "#"];
-var SENTINEL_BASE = 57344;
-var SHIELD = /* @__PURE__ */ new Map();
-var RESTORE = /* @__PURE__ */ new Map();
-STRUCTURAL.forEach((ch, i) => {
-  const sentinel = String.fromCharCode(SENTINEL_BASE + i);
-  SHIELD.set(ch, sentinel);
-  RESTORE.set(sentinel, ch);
-});
-var SHIELD_RE = /[{}[\]%#]/gu;
-var RESTORE_RE = new RegExp(
-  `[${String.fromCharCode(SENTINEL_BASE)}-${String.fromCharCode(SENTINEL_BASE + STRUCTURAL.length - 1)}]`,
-  "gu"
-);
-function neutralize(value) {
-  return value.replace(SHIELD_RE, (ch) => SHIELD.get(ch) ?? ch);
-}
-function safetyRestore(text) {
-  return text.replace(RESTORE_RE, (ch) => RESTORE.get(ch) ?? ch);
-}
-function stripSentinels(text) {
-  return text.replace(RESTORE_RE, "");
-}
-
 // src/internal/render.ts
 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) {
@@ -672,7 +751,7 @@ function resolveIncludes(text, ctx) {
       throw new IncludeResolverError(`includeResolver threw for "${ref}"`, { cause });
     }
     if (included === null) return "";
-    return renderAst(parseTemplate(stripSentinels(included)), {
+    return renderAst(parseTemplate(included), {
       ...ctx,
       runtimeContext: ctx.runtimeContext,
       // child inherits runtime, not parent #set
@@ -680,33 +759,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 = "";
@@ -766,7 +877,7 @@ function renderPlural(node, opts) {
   if (/[{}[\]]/u.test(formsRaw)) {
     report({
       code: "plural.nested-brackets",
-      message: "Plural form slot contains nested spintax brackets; extract via #set first.",
+      message: "Plural form slot contains nested spintax brackets; extract via #def first \u2014 a #set is substituted verbatim and would put the brackets straight back.",
       construct: rawConstruct(countRaw, formsRaw),
       locale: base
     });
@@ -865,26 +976,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) {
@@ -1020,7 +1111,7 @@ function renderWith(input, rng, opts = {}) {
     includeStack: [],
     onPluralError: opts.onPluralError
   };
-  const ast = resolveAst(typeof input === "string" ? stripSentinels(input) : input);
+  const ast = resolveAst(input);
   let out = renderAst(ast, ctx);
   if (opts.postProcess !== false) out = postProcess(out);
   return safetyRestore(out);