@spintax/core 0.3.2 → 0.3.4

package/CHANGELOG.md

@@ -3,7 +3,68 @@
 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.2 — 2026-07-23
+## 0.3.4 — 2026-08-08
+
+Docs-only release — no engine changes; every byte of `dist/` behavior is 0.3.3's.
+
+### Changed
+
+- **README catches up with the ecosystem.** The parity paragraph now states the real contract —
+  one syntax surface across five independent engines (npm / Packagist / PyPI / Object Pascal /
+  the WordPress plugin) held by the shared 234-fixture corpus — instead of the original
+  two-engine wording. New "Using it without writing code" section and refreshed links:
+  the [`n8n-nodes-spintax`](https://www.npmjs.com/package/n8n-nodes-spintax) community node
+  (released 2026-08-07), the spintax.net playground, the Telegram bot, and Spintax Studio.
+  Internal spec-section references dropped from public copy.
+- **`package.json`**: description mentions the n8n node; `n8n` added to keywords.
+
+## 0.3.3 — 2026-08-07
+
+`validate()` scales. No output changes anywhere: a 464-document differential over every
+definition-graph, diagnostic-position and fuzz shape is byte-identical before and after, and
+three deliberate mutations (drop the prune, shift a column, freeze the line counter) each
+turn it red — the harness can see what it guards.
+
+### Fixed
+
+- **`validate()` is no longer super-linear on definition graphs — and no longer hangs.** Four
+  independent costs, each measured before and after (Node 22, same machine):
+
+  | shape | 0.3.2 | 0.3.3 |
+  |---|---|---|
+  | chain of 1600 `#set`s | 13.1 s | 18 ms |
+  | converging diamond, 20 levels (~1 KB) | 4.8 s | <1 ms |
+  | converging diamond, 26+ levels | **never returns** | <1 ms (2000 levels: 22 ms) |
+  | one cycle of 1600 | 55.6 s | 0.8 s |
+  | 6400 duplicate definitions | 9.3 s | 29 ms |
+  | 6400 undefined references | 2.9 s | 11 ms |
+
+  The circular-reference walk re-parsed every value's references at every visit, tested the
+  path with an array `includes`, copied the path at every step, and restarted from every
+  definition with no memory of silent subtrees — on a converging diamond that re-explored
+  shared subgraphs exponentially, so a one-kilobyte template could pin a CPU forever (the
+  validator is exposed by hosts; that is a denial-of-service shape, not just a slow one).
+  References are now parsed once, the path is a Set plus a shared push/pop array, the walk is
+  iterative (a chain as deep as the document cannot overflow the call stack), and one colour
+  walk computes up front which names can reach a cycle — a subtree that cannot reach one
+  cannot report, so skipping it is output-neutral by construction. Emission order, count and
+  messages are exactly the old walk's, duplicated edges and all.
+
+  The taint sweep behind `plural.count-macro` was a fixpoint that re-read every macro once per
+  newly tainted name; it is now a reverse-edge worklist computing the same closure. Diagnostic
+  positions were each computed by scanning from offset 0; a line-start index built once per
+  call now answers them by binary search. And `extractDirectives` counted the line of each
+  occurrence from the start of the text — quadratic on directive-heavy documents, and on the
+  **render** path too, since the renderer extracts directives the same way; a resuming counter
+  fixes both surfaces.
+
+  Two boundaries stay as they are, deliberately. A giant single cycle still costs seconds at
+  6400 definitions because the output itself is quadratic — every diagnostic's message carries
+  the full cycle path, so ~300 MB of message text is the answer, not the overhead. And a
+  converging diamond that FEEDS a cycle still emits one diagnostic per path — exponentially
+  many — because that is the reference emission the corpus family just aligned on
+  (spintax-win, 2026-08-07); whether that emission should be bounded is a family question, not
+  a patch.
 
 Post-process robustness and scaling: `postProcess()` no longer emits its own U+0000 sentinel, and
 the placeholder restore is linear instead of quadratic. Output is unchanged on ordinary text; the

package/README.md

@@ -14,16 +14,20 @@ parse, render, validate, extract, analyze, and neutralize 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.
-- **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`/`#def` semantics,
-  post-process), with no divergence.
+- **One syntax contract, [five independent engines](https://spintax.net/spintax-engines/).**
+  This package, [`spintax/core`](https://packagist.org/packages/spintax/core) (PHP),
+  [`spintax-core`](https://pypi.org/project/spintax-core/) (Python), an Object Pascal engine, and
+  the [Spintax WordPress plugin](https://wordpress.org/plugins/spintax/) are all held to the same
+  behavior contract by a **shared golden corpus of 234 fixtures** — deterministic verdicts, plural
+  buckets, conditionals, `#set`/`#def` semantics and post-processing agree everywhere, so a
+  template is an asset you can move between runtimes, not a lock-in.
 - **MIT** licensed.
 
 > **Status: released & stable.** Feature-complete — parse / render / validate / extract / analyze /
-> neutralize. The deterministic golden corpus passes against **both** this engine and the PHP
-> plugin, and the §9.2 API is proven by a reference Cloudflare Worker (`examples/worker`).
+> neutralize — with the public API proven by real consumers: a reference Cloudflare Worker, the
+> [@spintaxnetbot](https://t.me/spintaxnetbot) Telegram bot, the
+> [spintax.net playground](https://spintax.net/play/), and the
+> [n8n community node](https://www.npmjs.com/package/n8n-nodes-spintax).
 
 ## Install
 
@@ -149,6 +153,19 @@ render('%bio%', { context: { bio: neutralize('Save {50|60}% today') }, postProce
 // → "Save {50|60}% today"   (the braces stay literal, not a random pick)
 ```
 
+## Using it without writing code
+
+- **n8n** — install [`n8n-nodes-spintax`](https://www.npmjs.com/package/n8n-nodes-spintax)
+  (Settings → Community Nodes). One node, five operations: Render, Render Many, a two-output
+  Validate, and the LLM authoring/repair prompt builders — a Sheets-to-outbox personalization
+  flow or a full AI authoring loop with no code and no credentials on the node's side.
+- **Telegram** — [@spintaxnetbot](https://t.me/spintaxnetbot): validate, preview, and AI-draft
+  templates in chat.
+- **Browser** — the [spintax.net playground](https://spintax.net/play/): live validation and
+  N-variant rendering, entirely client-side (it runs this very package).
+- **Windows** — [Spintax Studio](https://apps.microsoft.com/detail/9mw3ch7b530p), a native
+  editor in the Microsoft Store (renders via the family's Object Pascal engine; same corpus).
+
 ## Determinism & RNG
 
 With a `seed`, `render` is reproducible within this engine. Cross-engine RNG-sequence parity
@@ -157,10 +174,15 @@ plural buckets, conditional truthiness, `#set`/`#def` semantics, post-process ou
 
 ## Links
 
-- 📦 npm — [`@spintax/core`](https://www.npmjs.com/package/@spintax/core)
-- 🤖 Try it — [@spintaxnetbot](https://t.me/spintaxnetbot) (Telegram: validate + preview + AI `/draft`)
+- 📦 npm — [`@spintax/core`](https://www.npmjs.com/package/@spintax/core) ·
+  [`n8n-nodes-spintax`](https://www.npmjs.com/package/n8n-nodes-spintax) (the n8n node)
+- 🧪 Try it — [playground](https://spintax.net/play/) ·
+  [@spintaxnetbot](https://t.me/spintaxnetbot) (Telegram: validate + preview + AI `/draft`)
+- 🖥️ Desktop — [Spintax Studio](https://apps.microsoft.com/detail/9mw3ch7b530p) (Microsoft Store)
+- 🧬 The family — [all five engines, one corpus](https://spintax.net/spintax-engines/)
+  (PHP · Python · Pascal · WordPress)
 - 🧩 Source — [investblog/spintax-js](https://github.com/investblog/spintax-js)
-- 🌐 Product — [spintax.net](https://spintax.net)
+- 🌐 Docs & guides — [spintax.net](https://spintax.net)
 - 🏠 Maintainer — [301.st](https://301.st)
 
 ## License

package/dist/index.cjs

@@ -61,6 +61,15 @@ function extractDirectives(text) {
   const setDefs = {};
   const defDefs = {};
   const occurrences = [];
+  let cursorOffset = 0;
+  let cursorLine = 1;
+  const lineAt = (offset) => {
+    for (let i = cursorOffset; i < offset; i += 1) {
+      if (text.charCodeAt(i) === 10) cursorLine += 1;
+    }
+    cursorOffset = offset;
+    return cursorLine;
+  };
   DIRECTIVE_RE.lastIndex = 0;
   const stripped = text.replace(
     DIRECTIVE_RE,
@@ -70,7 +79,7 @@ function extractDirectives(text) {
         kind,
         name,
         value,
-        line: countLines(text, offset)
+        line: lineAt(offset)
       });
       if (kind === "def") defDefs[name] = value;
       else setDefs[name] = value;
@@ -79,11 +88,6 @@ function extractDirectives(text) {
   );
   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, "");
 }
@@ -420,13 +424,14 @@ var INCLUDE_RE = /^[ \t]*#include[ \t\n\r\f\x0B]+"([^"]+)"[ \t\n\r\f\x0B]*$/gmu;
 function validateTemplate(src, opts = {}) {
   const diagnostics = [];
   const text = stripComments(src);
+  const idx = buildLineIndex(text);
   checkBrackets(text, diagnostics);
   checkDirectives(text, diagnostics);
-  checkPermutationConfigs(text, diagnostics);
-  checkPlurals(text, opts.locale, diagnostics);
-  checkVariableReferences(text, opts.knownVariables, diagnostics);
+  checkPermutationConfigs(text, idx, diagnostics);
+  checkPlurals(text, idx, opts.locale, diagnostics);
+  checkVariableReferences(text, idx, opts.knownVariables, diagnostics);
   if (opts.knownIncludes && opts.knownIncludes.length > 0) {
-    checkIncludeTargets(text, opts.knownIncludes, diagnostics);
+    checkIncludeTargets(text, idx, opts.knownIncludes, diagnostics);
   }
   return diagnostics;
 }
@@ -436,21 +441,27 @@ function err(code, message, pos) {
 function warn(code, message, pos) {
   return { severity: "warning", code, message, ...pos };
 }
-function offsetToLineCol(text, offset) {
-  let line = 1;
-  let lineStart = 0;
-  const end = Math.min(Math.max(offset, 0), text.length);
-  for (let i = 0; i < end; i += 1) {
-    if (text.charAt(i) === "\n") {
-      line += 1;
-      lineStart = i + 1;
-    }
+function buildLineIndex(text) {
+  const starts = [0];
+  for (let i = 0; i < text.length; i += 1) {
+    if (text.charCodeAt(i) === 10) starts.push(i + 1);
+  }
+  return { starts, length: text.length };
+}
+function offsetToLineCol(idx, offset) {
+  const end = Math.min(Math.max(offset, 0), idx.length);
+  let lo = 0;
+  let hi = idx.starts.length - 1;
+  while (lo < hi) {
+    const mid = lo + hi + 1 >> 1;
+    if ((idx.starts[mid] ?? 0) <= end) lo = mid;
+    else hi = mid - 1;
   }
-  return { line, column: end - lineStart + 1 };
+  return { line: lo + 1, column: end - (idx.starts[lo] ?? 0) + 1 };
 }
-function span(text, offset, length) {
-  const s = offsetToLineCol(text, offset);
-  const e = offsetToLineCol(text, offset + length);
+function span(idx, offset, length) {
+  const s = offsetToLineCol(idx, offset);
+  const e = offsetToLineCol(idx, offset + length);
   return { line: s.line, column: s.column, endLine: e.line, endColumn: e.column };
 }
 function checkBrackets(text, out) {
@@ -518,7 +529,7 @@ function checkDirectives(text, out) {
     }
   }
 }
-function checkPermutationConfigs(text, out) {
+function checkPermutationConfigs(text, idx, out) {
   for (const m of text.matchAll(/\[<([^>]*?)>/gu)) {
     const configStr = m[1] ?? "";
     if (!/\w+\s*=/.test(configStr)) continue;
@@ -529,7 +540,7 @@ function checkPermutationConfigs(text, out) {
         out.push(err(
           "permutation.unknown-key",
           `Unknown permutation config key: '${km[1]}'.`,
-          { ...span(text, configBase + (km.index ?? 0), (km[1] ?? "").length), data: { key: km[1] } }
+          { ...span(idx, configBase + (km.index ?? 0), (km[1] ?? "").length), data: { key: km[1] } }
         ));
       }
     }
@@ -538,7 +549,7 @@ function checkPermutationConfigs(text, out) {
       out.push(err(
         "permutation.minsize-not-integer",
         `minsize must be a positive integer, got '${min[1]}'.`,
-        { ...span(text, configBase + min.index, min[0].length), data: { value: min[1] } }
+        { ...span(idx, configBase + min.index, min[0].length), data: { value: min[1] } }
       ));
     }
     const max = /maxsize\s*=\s*([^;>\s]+)/i.exec(configStr);
@@ -546,17 +557,17 @@ function checkPermutationConfigs(text, out) {
       out.push(err(
         "permutation.maxsize-not-integer",
         `maxsize must be a positive integer, got '${max[1]}'.`,
-        { ...span(text, configBase + max.index, max[0].length), data: { value: max[1] } }
+        { ...span(idx, configBase + max.index, max[0].length), data: { value: max[1] } }
       ));
     }
   }
 }
-function checkPlurals(text, locale, out) {
+function checkPlurals(text, idx, 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);
+    const at = span(idx, 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;
@@ -586,25 +597,34 @@ var UNRESOLVED_AT_PLURAL_TIME = /\[|\{(?!\?)/u;
 function macroTaintedNames(text) {
   const macros = extractDirectives(text).setDefs;
   const tainted = /* @__PURE__ */ new Set();
+  const queue = [];
+  for (const [name, value] of Object.entries(macros)) {
+    if (UNRESOLVED_AT_PLURAL_TIME.test(value)) {
+      tainted.add(name);
+      queue.push(name);
+    }
+  }
+  const dependents = /* @__PURE__ */ new Map();
   for (const [name, value] of Object.entries(macros)) {
-    if (UNRESOLVED_AT_PLURAL_TIME.test(value)) tainted.add(name);
+    for (const m of value.matchAll(/%(\w+)%/gu)) {
+      const ref = (m[1] ?? "").toLowerCase();
+      const list = dependents.get(ref);
+      if (list === void 0) dependents.set(ref, [name]);
+      else list.push(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;
+  while (queue.length > 0) {
+    const source = queue.pop();
+    for (const name of dependents.get(source) ?? []) {
+      if (!tainted.has(name)) {
         tainted.add(name);
-        grew = true;
-        break;
+        queue.push(name);
       }
     }
   }
   return tainted;
 }
-function checkVariableReferences(text, known, out) {
+function checkVariableReferences(text, idx, known, out) {
   const knownSet = new Set((known ?? []).map((n) => n.toLowerCase()));
   const defs = /* @__PURE__ */ new Map();
   const defPos = /* @__PURE__ */ new Map();
@@ -612,7 +632,7 @@ function checkVariableReferences(text, known, out) {
     const name = (m[1] ?? "").toLowerCase();
     defs.set(name, m[2] ?? "");
     const nameOffset = (m.index ?? 0) + m[0].indexOf("%");
-    defPos.set(name, span(text, nameOffset, name.length + 2));
+    defPos.set(name, span(idx, nameOffset, name.length + 2));
   }
   const somewhere = { line: 1, column: 1 };
   for (const [name, value] of defs) {
@@ -620,8 +640,15 @@ function checkVariableReferences(text, known, out) {
       out.push(err("variable.self-reference", `Variable '${name}' references itself.`, defPos.get(name) ?? somewhere));
     }
   }
+  const refsOf = /* @__PURE__ */ new Map();
+  for (const [name, value] of defs) {
+    const refs = [];
+    for (const m of value.matchAll(/%(\w+)%/gu)) refs.push((m[1] ?? "").toLowerCase());
+    refsOf.set(name, refs);
+  }
+  const reachesCycle = namesThatReachACycle(defs, refsOf);
   for (const name of defs.keys()) {
-    detectCycle(name, defs, [name], defPos.get(name) ?? somewhere, out);
+    detectCycle(name, defs, refsOf, reachesCycle, defPos.get(name) ?? somewhere, out);
   }
   const body = text.replace(/^[ \t]*#(?:set|def)[ \t]+%\w+%[ \t]*=[ \t]*.*?$/gmu, (m) => m.replace(/[^\n]/g, " "));
   const seen = /* @__PURE__ */ new Set();
@@ -632,7 +659,7 @@ function checkVariableReferences(text, known, out) {
     out.push(warn(
       "variable.undefined",
       `Variable '${name}' is not defined \u2014 may be a runtime variable.`,
-      { ...span(text, offset, length), data: { name } }
+      { ...span(idx, offset, length), data: { name } }
     ));
   };
   for (const m of body.matchAll(/%(\w+)%/gu)) undefinedAt(m[1] ?? "", m.index ?? 0, m[0].length);
@@ -640,19 +667,70 @@ function checkVariableReferences(text, known, out) {
     undefinedAt(m[1] ?? "", (m.index ?? 0) + m[0].indexOf(m[1] ?? ""), (m[1] ?? "").length);
   }
 }
-function detectCycle(current, defs, visited, rootPos, out) {
-  const value = defs.get(current) ?? "";
-  for (const m of value.matchAll(/%(\w+)%/gu)) {
-    const ref = (m[1] ?? "").toLowerCase();
-    if (ref === current) continue;
-    if (visited.includes(ref)) {
-      out.push(err("variable.circular-reference", `Circular variable reference: ${[...visited, ref].join(" \u2192 ")}.`, rootPos));
-      return;
+function namesThatReachACycle(defs, refsOf) {
+  const GREY = 1;
+  const BLACK = 2;
+  const color = /* @__PURE__ */ new Map();
+  const reaches = /* @__PURE__ */ new Set();
+  for (const root of defs.keys()) {
+    if (color.has(root)) continue;
+    const stack = [{ name: root, refs: refsOf.get(root) ?? [], i: 0 }];
+    color.set(root, GREY);
+    while (stack.length > 0) {
+      const top = stack[stack.length - 1];
+      if (top.i < top.refs.length) {
+        const ref = top.refs[top.i];
+        top.i += 1;
+        if (ref === top.name || !defs.has(ref)) continue;
+        const c = color.get(ref);
+        if (c === GREY) reaches.add(top.name);
+        else if (c === BLACK) {
+          if (reaches.has(ref)) reaches.add(top.name);
+        } else {
+          stack.push({ name: ref, refs: refsOf.get(ref) ?? [], i: 0 });
+          color.set(ref, GREY);
+        }
+      } else {
+        stack.pop();
+        color.set(top.name, BLACK);
+        if (stack.length > 0 && reaches.has(top.name)) reaches.add(stack[stack.length - 1].name);
+      }
+    }
+  }
+  return reaches;
+}
+function detectCycle(root, defs, refsOf, reachesCycle, rootPos, out) {
+  if (!reachesCycle.has(root)) return;
+  const path = [root];
+  const onPath = /* @__PURE__ */ new Set([root]);
+  const stack = [{ name: root, refs: refsOf.get(root) ?? [], i: 0 }];
+  const leave = (frame) => {
+    stack.pop();
+    onPath.delete(frame.name);
+    path.pop();
+  };
+  while (stack.length > 0) {
+    const top = stack[stack.length - 1];
+    if (top.i >= top.refs.length) {
+      leave(top);
+      continue;
+    }
+    const ref = top.refs[top.i];
+    top.i += 1;
+    if (ref === top.name) continue;
+    if (onPath.has(ref)) {
+      out.push(err("variable.circular-reference", `Circular variable reference: ${[...path, ref].join(" \u2192 ")}.`, rootPos));
+      leave(top);
+      continue;
+    }
+    if (defs.has(ref) && reachesCycle.has(ref)) {
+      stack.push({ name: ref, refs: refsOf.get(ref) ?? [], i: 0 });
+      onPath.add(ref);
+      path.push(ref);
     }
-    if (defs.has(ref)) detectCycle(ref, defs, [...visited, ref], rootPos, out);
   }
 }
-function checkIncludeTargets(text, known, out) {
+function checkIncludeTargets(text, idx, known, out) {
   const set = new Set(known);
   INCLUDE_RE.lastIndex = 0;
   for (const m of text.matchAll(INCLUDE_RE)) {
@@ -662,7 +740,7 @@ function checkIncludeTargets(text, known, out) {
       out.push(err(
         "include.unknown-target",
         `#include target '${ref}' does not match any known template.`,
-        { ...span(text, refOffset, ref.length), data: { target: ref } }
+        { ...span(idx, refOffset, ref.length), data: { target: ref } }
       ));
     }
   }