@spintax/core 0.5.3 → 0.6.0

package/CHANGELOG.md

@@ -3,6 +3,48 @@
 All notable changes to `@spintax/core` are documented here. This project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.6.0 — 2026-08-18
+
+**`validate()` now emits ONE `variable.circular-reference` per NAME that takes part in, or leads
+to, a cycle** — it used to emit one per PATH (issue #59). Minor rather than patch: diagnostic
+output visibly changes, though no verdict moves and no API does.
+
+### Fixed
+
+Per-path emission is exponential on a converging diamond, because the number of routes into a
+cycle is exponential in the diamond's depth:
+
+| shape | template | before | after |
+|---|---|---|---|
+| 20 definitions, each referencing the previous one twice, feeding a 2-cycle | **507 B** | **2 097 152 diagnostics, 5.9 s** | **22 diagnostics, 6 ms** |
+| the same at depth 200 | 5 KB | (never finished) | 202 diagnostics, ms |
+| live `POST /validate-template` | **547 B** | **HTTP 503** | 200, with a verdict |
+
+The second half of the same issue: one cycle of N names printed an N-name route in each of N
+messages. A 43 KB template of one giant cycle carried **29 MB of message text**; the route is now
+capped at 8 names and becomes a count — `n0 → n1 → … → n7 → … (1992 more)` — which brings that to
+200 KB. A real cycle is two to five names and reads exactly as it did.
+
+**Messages are unchanged for every shape a human writes.** The colour walk that already existed as
+a prune now also records one witness edge per name, and following those edges reproduces the route
+the per-path walk used to print: `a → b → a`, `d0 → c1 → c2 → c1`. Only the duplicates are gone.
+`Diagnostic.data` carries `{ name }` so a consumer can group without parsing the message.
+
+### Notes
+
+This reverses a deliberate decision, which is why it is recorded rather than quietly shipped. The
+per-path shape was pinned on purpose in three engines' own suites — "an implementation that
+deduplicates repeated edges, memoizes per root, or reorders roots goes red here, not silently
+green" — and `spintax-win` aligned to it on 2026-08-07. It could not be kept and bounded: re-walking
+every route *is* the emission. `spintax-core` (Python) already emitted per name and was the one
+engine immune; the rest followed it, and its counts are now the reference — verified by diffing 400
+generated definition graphs against it, and against `spintax/core`, with zero mismatches.
+
+Mirrored into `spintax/core` 0.8.0 and the WordPress plugin. The corpus gains a fixture for the
+diamond whose real assertion is that the engine *answers*; it cannot gate the count, because
+diagnostics are asserted as a subset — and `packages/conformance/README.md` now says that
+multiplicity is deliberately not part of the contract.
+
 ## 0.5.3 — 2026-08-18
 
 The expansion budget added in 0.5.2 was created per rendered AST, and an `#include` renders one

package/dist/index.cjs

@@ -750,9 +750,14 @@ function checkVariableReferences(text, idx, known, out) {
     for (const m of value.matchAll(/%(\w+)%/gu)) refs.push((m[1] ?? "").toLowerCase());
     refsOf.set(name, refs);
   }
-  const reachesCycle = namesThatReachACycle(defs, refsOf);
+  const { reaches: reachesCycle, via } = namesThatReachACycle(defs, refsOf);
   for (const name of defs.keys()) {
-    detectCycle(name, defs, refsOf, reachesCycle, defPos.get(name) ?? somewhere, out);
+    if (!reachesCycle.has(name)) continue;
+    out.push(err(
+      "variable.circular-reference",
+      `Circular variable reference: ${cyclePath(name, via)}.`,
+      { ...defPos.get(name) ?? somewhere, data: { name } }
+    ));
   }
   const body = text.replace(/^[ \t]*#(?:set|def)[ \t]+%\w+%[ \t]*=[ \t]*.*?$/gmu, (m) => m.replace(/[^\n]/g, " "));
   const seen = /* @__PURE__ */ new Set();
@@ -776,6 +781,12 @@ function namesThatReachACycle(defs, refsOf) {
   const BLACK = 2;
   const color = /* @__PURE__ */ new Map();
   const reaches = /* @__PURE__ */ new Set();
+  const via = /* @__PURE__ */ new Map();
+  const mark = (name, witness) => {
+    if (reaches.has(name)) return;
+    reaches.add(name);
+    via.set(name, witness);
+  };
   for (const root of defs.keys()) {
     if (color.has(root)) continue;
     const stack = [{ name: root, refs: refsOf.get(root) ?? [], i: 0 }];
@@ -787,9 +798,9 @@ function namesThatReachACycle(defs, refsOf) {
         top.i += 1;
         if (ref === top.name || !defs.has(ref)) continue;
         const c = color.get(ref);
-        if (c === GREY) reaches.add(top.name);
+        if (c === GREY) mark(top.name, ref);
         else if (c === BLACK) {
-          if (reaches.has(ref)) reaches.add(top.name);
+          if (reaches.has(ref)) mark(top.name, ref);
         } else {
           stack.push({ name: ref, refs: refsOf.get(ref) ?? [], i: 0 });
           color.set(ref, GREY);
@@ -797,42 +808,41 @@ function namesThatReachACycle(defs, refsOf) {
       } else {
         stack.pop();
         color.set(top.name, BLACK);
-        if (stack.length > 0 && reaches.has(top.name)) reaches.add(stack[stack.length - 1].name);
+        if (stack.length > 0 && reaches.has(top.name)) mark(stack[stack.length - 1].name, top.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;
+  return { reaches, via };
+}
+var CYCLE_PATH_LIMIT = 8;
+function cyclePath(name, via) {
+  const seen = /* @__PURE__ */ new Set([name]);
+  const shown = [name];
+  let current = name;
+  for (; ; ) {
+    const next = via.get(current);
+    if (next === void 0) break;
+    if (seen.has(next)) {
+      shown.push(next);
+      return shown.join(" \u2192 ");
     }
-    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 (shown.length >= CYCLE_PATH_LIMIT) {
+      let more = 0;
+      let walk2 = next;
+      while (!seen.has(walk2)) {
+        seen.add(walk2);
+        more += 1;
+        const step = via.get(walk2);
+        if (step === void 0) break;
+        walk2 = step;
+      }
+      return `${shown.join(" \u2192 ")} \u2192 \u2026 (${more} more)`;
     }
+    seen.add(next);
+    shown.push(next);
+    current = next;
   }
+  return shown.join(" \u2192 ");
 }
 function checkIncludeTargets(text, idx, known, out) {
   const set = new Set(known);