@spintax/core 0.6.0 → 0.7.0

package/dist/index.d.cts

@@ -21,8 +21,12 @@
  * 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.
+ *
+ * 3 — `EnumerationNode` and `PermutationNode` gained `raw`, the body a direct `%var%` reference
+ * is spliced into at render time. An `Ast` cached by version 2 carries no `raw`, so rendering it
+ * would silently keep a pipe-joined value as ONE option — the defect 0.7.0 fixed.
  */
-declare const AST_VERSION = 2;
+declare const AST_VERSION = 3;
 /** Opaque public handle (re-exported as `Ast` from the package index). */
 interface Ast {
     readonly astVersion: typeof AST_VERSION;
@@ -42,6 +46,10 @@ interface Ast {
  *   - conditionals test truthiness against the raw var map; plurals resolve the
  *     count (vars already expanded) then pick the bucket, lenient fullwidth
  *     fallback (Stage 6d, after vars).
+ *   - a `%var%` that sits DIRECTLY in an enumeration/permutation body is spliced as
+ *     TEXT and the construct re-read (spliceConstruct, 0.7.0): a `|` inside such a
+ *     value separates options, exactly as in the plugin, whose expansion runs before
+ *     any bracket is read. Every other construct keeps the tree it was parsed into.
  *   - #include (post-tree string pass) and post-process are later PRs.
  *
  * RNG note: cross-engine RNG-sequence parity is a non-goal (§3.2). Enumerations

package/dist/index.d.ts

@@ -21,8 +21,12 @@
  * 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.
+ *
+ * 3 — `EnumerationNode` and `PermutationNode` gained `raw`, the body a direct `%var%` reference
+ * is spliced into at render time. An `Ast` cached by version 2 carries no `raw`, so rendering it
+ * would silently keep a pipe-joined value as ONE option — the defect 0.7.0 fixed.
  */
-declare const AST_VERSION = 2;
+declare const AST_VERSION = 3;
 /** Opaque public handle (re-exported as `Ast` from the package index). */
 interface Ast {
     readonly astVersion: typeof AST_VERSION;
@@ -42,6 +46,10 @@ interface Ast {
  *   - conditionals test truthiness against the raw var map; plurals resolve the
  *     count (vars already expanded) then pick the bucket, lenient fullwidth
  *     fallback (Stage 6d, after vars).
+ *   - a `%var%` that sits DIRECTLY in an enumeration/permutation body is spliced as
+ *     TEXT and the construct re-read (spliceConstruct, 0.7.0): a `|` inside such a
+ *     value separates options, exactly as in the plugin, whose expansion runs before
+ *     any bracket is read. Every other construct keeps the tree it was parsed into.
  *   - #include (post-tree string pass) and post-process are later PRs.
  *
  * RNG note: cross-engine RNG-sequence parity is a non-goal (§3.2). Enumerations

package/dist/index.js

@@ -1,19 +1,32 @@
 // src/internal/ast.ts
-var AST_VERSION = 2;
+var AST_VERSION = 3;
 function walk(nodes, visit) {
-  for (const n of nodes) {
+  const stack = [{ list: nodes, i: 0 }];
+  while (stack.length > 0) {
+    const top = stack[stack.length - 1];
+    if (top.i >= top.list.length) {
+      stack.pop();
+      continue;
+    }
+    const n = top.list[top.i];
+    top.i += 1;
     visit(n);
+    let children;
     switch (n.type) {
       case "enumeration":
-        for (const opt of n.options) walk(opt, visit);
+        children = n.options;
         break;
       case "conditional":
-        walk(n.then, visit);
-        walk(n.else, visit);
+        children = [n.then, n.else];
         break;
       case "permutation":
-        for (const opt of n.options) walk(opt.nodes, visit);
+        children = n.options.map((opt) => opt.nodes);
         break;
+      default:
+        continue;
+    }
+    for (let k = children.length - 1; k >= 0; k -= 1) {
+      stack.push({ list: children[k], i: 0 });
     }
   }
 }
@@ -90,65 +103,114 @@ function stripComments(text) {
   return text.replace(/\/#[\s\S]*?#\//g, "");
 }
 function parseSequence(text) {
-  const nodes = [];
-  let literal = "";
-  let i = 0;
-  const flushLiteral = () => {
-    if (literal !== "") {
-      nodes.push({ type: "literal", value: literal });
-      literal = "";
-    }
-  };
-  while (i < text.length) {
-    const ch = text.charAt(i);
-    if (ch === "{") {
-      const end = findMatchingClose(text, i, "{", "}");
-      if (end === -1) {
-        literal += ch;
-        i += 1;
+  const frame = (t) => ({ text: t, i: 0, literal: "", nodes: [], plan: null, parts: [] });
+  const stack = [frame(text)];
+  while (stack.length > 0) {
+    const f = stack[stack.length - 1];
+    if (f.plan !== null) {
+      if (f.parts.length < f.plan.texts.length) {
+        stack.push(frame(f.plan.texts[f.parts.length]));
         continue;
       }
-      const content = text.slice(i + 1, end);
-      flushLiteral();
-      nodes.push(parseBraceConstruct(content));
-      i = end + 1;
+      f.nodes.push(f.plan.build(f.parts));
+      f.plan = null;
+      f.parts = [];
       continue;
     }
-    if (ch === "[") {
-      const end = findMatchingClose(text, i, "[", "]");
-      if (end === -1) {
-        literal += ch;
-        i += 1;
-        continue;
+    const flushLiteral = () => {
+      if (f.literal !== "") {
+        f.nodes.push({ type: "literal", value: f.literal });
+        f.literal = "";
       }
-      flushLiteral();
-      nodes.push(parsePermutation(text.slice(i + 1, end)));
-      i = end + 1;
-      continue;
-    }
-    if (ch === "%") {
-      const name = VARIABLE_RE.exec(text.slice(i))?.[1];
-      if (name !== void 0) {
+    };
+    let planned = null;
+    while (f.i < f.text.length && planned === null) {
+      const ch = f.text.charAt(f.i);
+      if (ch === "{" || ch === "[") {
+        const close = ch === "{" ? "}" : "]";
+        const end = findMatchingClose(f.text, f.i, ch, close);
+        if (end === -1) {
+          f.literal += ch;
+          f.i += 1;
+          continue;
+        }
+        const inner = f.text.slice(f.i + 1, end);
         flushLiteral();
-        nodes.push({ type: "variable", name });
-        i += name.length + 2;
+        planned = ch === "{" ? planBraceConstruct(inner) : planPermutation(inner);
+        f.i = end + 1;
         continue;
       }
+      if (ch === "%") {
+        const name = VARIABLE_RE.exec(f.text.slice(f.i))?.[1];
+        if (name !== void 0) {
+          flushLiteral();
+          f.nodes.push({ type: "variable", name });
+          f.i += name.length + 2;
+          continue;
+        }
+      }
+      f.literal += ch;
+      f.i += 1;
     }
-    literal += ch;
-    i += 1;
+    if (planned !== null) {
+      if ("node" in planned) f.nodes.push(planned.node);
+      else f.plan = planned;
+      continue;
+    }
+    flushLiteral();
+    stack.pop();
+    const parent = stack[stack.length - 1];
+    if (parent !== void 0) parent.parts.push(f.nodes);
+    else return f.nodes;
   }
-  flushLiteral();
-  return nodes;
+  return [];
 }
-function parseBraceConstruct(content) {
+function planBraceConstruct(content) {
   if (content.charAt(0) === "?") {
-    const cond = tryParseConditional(content);
-    if (cond) return cond;
+    const parts = splitConditional(content);
+    if (parts !== null) {
+      return {
+        texts: [parts.thenRaw, parts.elseRaw],
+        build: (children) => ({
+          type: "conditional",
+          name: parts.name,
+          inverted: parts.inverted,
+          then: children[0] ?? [],
+          else: children[1] ?? []
+        })
+      };
+    }
   } else if (content.startsWith(PLURAL_PREFIX) && content.slice(PLURAL_PREFIX.length).includes(":")) {
-    return parsePlural(content.slice(PLURAL_PREFIX.length));
+    return { node: parsePlural(content.slice(PLURAL_PREFIX.length)) };
   }
-  return { type: "enumeration", options: splitTopLevel(content).map((o) => parseSequence(o)) };
+  return {
+    texts: splitTopLevel(content),
+    build: (children) => hasDirectReference(children) ? { type: "enumeration", options: children, raw: content } : { type: "enumeration", options: children }
+  };
+}
+function hasDirectReference(lists) {
+  const stack = [...lists];
+  while (stack.length > 0) {
+    const list = stack.pop();
+    for (const node of list) {
+      if (node.type === "variable") return true;
+      if (node.type === "conditional") stack.push(node.then, node.else);
+    }
+  }
+  return false;
+}
+var REFERENCE_RE = /%\w+%/u;
+function planPermutation(rawInner) {
+  const { config, content } = extractPermutationConfig(rawInner);
+  const { texts, separators } = permutationElements(splitTopLevel(content));
+  const separatorHasRef = REFERENCE_RE.test(config.sep) || config.lastsep !== null && REFERENCE_RE.test(config.lastsep) || separators.some((sep) => sep !== null && REFERENCE_RE.test(sep));
+  return {
+    texts,
+    build: (children) => {
+      const options = children.map((nodes, i) => ({ nodes, separator: separators[i] ?? null }));
+      return separatorHasRef || hasDirectReference(children) ? { type: "permutation", config, options, raw: rawInner } : { type: "permutation", config, options };
+    }
+  };
 }
 function recognizeConditional(text, contentStart, contentEnd) {
   let p = contentStart + 1;
@@ -177,17 +239,6 @@ function splitConditional(content) {
     elseRaw: sep < 0 ? "" : body.slice(sep + 1)
   };
 }
-function tryParseConditional(content) {
-  const parts = splitConditional(content);
-  if (parts === null) return null;
-  return {
-    type: "conditional",
-    name: parts.name,
-    inverted: parts.inverted,
-    then: parseSequence(parts.thenRaw),
-    else: parseSequence(parts.elseRaw)
-  };
-}
 function parsePlural(afterPrefix) {
   const colon = afterPrefix.indexOf(":");
   return { type: "plural", countRaw: afterPrefix.slice(0, colon), formsRaw: afterPrefix.slice(colon + 1) };
@@ -202,11 +253,6 @@ var PER_ELEM_HTML_RE = /^[a-zA-Z][a-zA-Z0-9]*\s/;
 function defaultPermConfig() {
   return { minsize: null, maxsize: null, sep: " ", lastsep: null };
 }
-function parsePermutation(rawInner) {
-  const { config, content } = extractPermutationConfig(rawInner);
-  const options = extractPerElementSeparators(splitTopLevel(content));
-  return { type: "permutation", config, options };
-}
 function extractPermutationConfig(content) {
   const trimmed = phpLtrim(content);
   if (trimmed === "" || trimmed.charAt(0) !== "<") {
@@ -250,8 +296,9 @@ function looksLikeHtmlStartTag(tagText, remaining) {
   const tagName = (m[1] ?? "").toLowerCase();
   return new RegExp(`</${escapeRegExp(tagName)}\\s*>`, "iu").test(remaining);
 }
-function extractPerElementSeparators(rawParts) {
-  const options = [];
+function permutationElements(rawParts) {
+  const texts = [];
+  const separators = [];
   let pendingSep = null;
   rawParts.forEach((part, i) => {
     let text = part;
@@ -265,11 +312,12 @@ function extractPerElementSeparators(rawParts) {
     }
     const trimmed = phpTrim(text);
     if (trimmed !== "") {
-      options.push({ nodes: parseSequence(trimmed), separator: pendingSep });
+      texts.push(trimmed);
+      separators.push(pendingSep);
     }
     pendingSep = trailingSep;
   });
-  return options;
+  return { texts, separators };
 }
 function extractTrailingSep(part) {
   const trimmed = phpRtrim(part);
@@ -1014,9 +1062,34 @@ function directReferences(text) {
   return [...text.matchAll(/%(\w+)%/gu)].map((match) => (match[1] ?? "").toLowerCase());
 }
 function renderNodes(nodes, opts) {
-  let out = "";
-  for (const node of nodes) out += renderNode(node, opts);
-  return out;
+  const frame = (list) => ({ nodes: list, i: 0, out: [], pending: null });
+  const stack = [frame(nodes)];
+  while (stack.length > 0) {
+    const f = stack[stack.length - 1];
+    if (f.pending !== null) {
+      if (f.pending.done.length < f.pending.lists.length) {
+        stack.push(frame(f.pending.lists[f.pending.done.length]));
+        continue;
+      }
+      f.out.push(f.pending.assemble(f.pending.done));
+      f.pending = null;
+      continue;
+    }
+    if (f.i >= f.nodes.length) {
+      const text = f.out.join("");
+      stack.pop();
+      const parent = stack[stack.length - 1];
+      if (parent === void 0) return text;
+      parent.pending.done.push(text);
+      continue;
+    }
+    const node = f.nodes[f.i];
+    f.i += 1;
+    const step = renderNode(node, opts);
+    if (typeof step === "string") f.out.push(step);
+    else f.pending = step;
+  }
+  return "";
 }
 function renderNode(node, opts) {
   switch (node.type) {
@@ -1025,7 +1098,7 @@ function renderNode(node, opts) {
     case "variable":
       return resolveVariable(node.name, opts);
     case "enumeration":
-      return renderEnumeration(node.options, opts);
+      return renderEnumeration(node, opts);
     case "permutation":
       return renderPermutation(node, opts);
     case "conditional":
@@ -1039,15 +1112,20 @@ function randomInt(rng, min, max) {
 }
 function resolveVariable(name, opts) {
   const value = opts.vars[name.toLowerCase()];
-  if (value === void 0) return `%${name}%`;
-  if (opts.depth >= MAX_VARIABLE_DEPTH || !/[{[%]/u.test(value)) return value;
+  if (value === void 0 || opts.frozen === true) return `%${name}%`;
   if (opts.budget.left <= 0) return `%${name}%`;
   opts.budget.left -= value.length;
+  if (opts.depth >= MAX_VARIABLE_DEPTH || !/[{[%]/u.test(value)) return value;
   return renderNodes(parseSequence(value), { ...opts, depth: opts.depth + 1 });
 }
-function expandVarsOnly(text, opts) {
+function passesLeft(opts) {
+  return Math.max(1, MAX_VARIABLE_DEPTH - opts.depth + 1);
+}
+function expandVarsFixpoint(text, opts, passes) {
+  if (opts.frozen === true) return { text, changed: false, converged: true };
   let out = text;
-  for (let i = 0; i < MAX_VARIABLE_DEPTH; i += 1) {
+  let changedAny = false;
+  for (let i = 0; i < passes; i += 1) {
     let changed = false;
     out = out.replace(/%(\w+)%/gu, (m, name) => {
       const value = opts.vars[name.toLowerCase()];
@@ -1057,9 +1135,10 @@ function expandVarsOnly(text, opts) {
       changed = true;
       return value;
     });
-    if (!changed) break;
+    if (!changed) return { text: out, changed: changedAny, converged: true };
+    changedAny = true;
   }
-  return out;
+  return { text: out, changed: changedAny, converged: false };
 }
 function conditionalTakesThen(name, inverted, opts) {
   const value = opts.vars[name.toLowerCase()];
@@ -1068,9 +1147,9 @@ function conditionalTakesThen(name, inverted, opts) {
 }
 function renderConditional(node, opts) {
   const truthy = conditionalTakesThen(node.name, node.inverted, opts);
-  return renderNodes(truthy ? node.then : node.else, opts);
+  return { lists: [truthy ? node.then : node.else], done: [], assemble: (parts) => parts[0] ?? "" };
 }
-function resolveCountConditionals(text, opts) {
+function resolveConditionalsInText(text, opts) {
   if (!text.includes("{?")) return text;
   const close = matchBraces(text);
   const out = [];
@@ -1117,8 +1196,11 @@ function matchBraces(text) {
   return close;
 }
 function renderPlural(node, opts) {
-  const countRaw = resolveCountConditionals(expandVarsOnly(node.countRaw, opts), opts);
-  const formsRaw = expandVarsOnly(node.formsRaw, opts);
+  const passes = passesLeft(opts);
+  const countPass = expandVarsFixpoint(node.countRaw, opts, passes);
+  const formsPass = expandVarsFixpoint(node.formsRaw, opts, passes);
+  const countRaw = resolveConditionalsInText(countPass.text, opts);
+  const formsRaw = formsPass.text;
   const base = normalizeBaseLang(opts.locale);
   const report = (issue) => opts.onPluralError?.(issue);
   if (/[{}[\]]/u.test(formsRaw)) {
@@ -1153,7 +1235,8 @@ function renderPlural(node, opts) {
     return fullwidthVerbatim(countRaw, formsRaw);
   }
   const picked = pluralFor(base, Number.parseInt(count, 10), forms);
-  return renderNodes(parseSequence(picked), opts);
+  if (!formsPass.converged) return renderNodes(parseSequence(picked), { ...opts, frozen: true });
+  return { lists: [parseSequence(picked)], done: [], assemble: (parts) => parts[0] ?? "" };
 }
 function rawConstruct(countRaw, formsRaw) {
   return `{plural ${countRaw}:${formsRaw}}`;
@@ -1161,16 +1244,36 @@ function rawConstruct(countRaw, formsRaw) {
 function fullwidthVerbatim(countRaw, formsRaw) {
   return rawConstruct(countRaw, formsRaw).replace(/\{/gu, "\uFF5B").replace(/\}/gu, "\uFF5D");
 }
-function renderEnumeration(options, opts) {
+function renderEnumeration(node, opts) {
+  const spliced = node.raw === void 0 ? null : spliceConstruct(node.raw, "{", "}", opts);
+  if (spliced !== null) return spliced;
+  const { options } = node;
   if (options.length === 0) return "";
   const picked = options[randomInt(opts.rng, 0, options.length - 1)];
-  return picked ? renderNodes(picked, opts) : "";
+  if (!picked) return "";
+  return { lists: [picked], done: [], assemble: (parts) => parts[0] ?? "" };
+}
+function spliceConstruct(raw, open, close, opts) {
+  if (opts.frozen === true) return null;
+  const expanded = expandVarsFixpoint(resolveConditionalsInText(raw, opts), opts, passesLeft(opts));
+  const body = resolveConditionalsInText(expanded.text, opts);
+  if (body === raw) return null;
+  const nodes = parseSequence(open + body + close);
+  if (!expanded.converged) return renderNodes(nodes, { ...opts, frozen: true });
+  return { lists: [nodes], done: [], assemble: (parts) => parts[0] ?? "" };
 }
 function renderPermutation(node, opts) {
-  const elements = node.options.map((o) => ({
-    text: renderNodes(o.nodes, opts),
-    sep: o.separator
-  }));
+  const spliced = node.raw === void 0 ? null : spliceConstruct(node.raw, "[", "]", opts);
+  if (spliced !== null) return spliced;
+  if (node.options.length === 0) return "";
+  return {
+    lists: node.options.map((o) => o.nodes),
+    done: [],
+    assemble: (parts) => assemblePermutation(node, parts, opts)
+  };
+}
+function assemblePermutation(node, rendered, opts) {
+  const elements = node.options.map((o, i) => ({ text: rendered[i] ?? "", sep: o.separator }));
   const total = elements.length;
   if (total === 0) return "";
   const { config } = node;