@vaudience/aigentflow-flow-validator 0.23.0 → 0.24.0

package/PARITY.md

@@ -6,6 +6,22 @@ discipline for keeping the two in sync.
 
 **Tracks AIgentFlow flow schema: `v2.831.0`** (`SPEC_VERSION` in [`src/spec/aigentflow-spec.json`](./src/spec/aigentflow-spec.json)), which adds the rule `unknown_function_operation` and a clearer `unknown_executor_scheme` message (package 0.23.0, below). Earlier: the rule `flow_data_key_reserved` (package 0.22.0). Earlier: the `here` executor scheme, the `strict_templates` flow key and the rule `template_default_piped` (package 0.21.0). Earlier: the warning `compliance_residency_unenforced` (package 0.20.0). `orchestrator.region` / `orchestrator.enforce_region` (package 0.19.0). Earlier: the AigentChat executor was removed (package 0.18.0). Earlier additions: the `examples:` block (package 0.17.0), `server_owned_query_key` (package 0.15.1) from the AIgentFlow release after v2.790.0, `credential_endpoint_unpaired` (package 0.15.2) from AIgentFlow v2.793.0 and the release after it, and `display_name_too_long` (package 0.15.3) from AIgentFlow v2.802.0.
 
+> package 0.24.0 — **`potential_infinite_loop` fires only on a cycle with no way out**, in step
+> with the reference. It used to fire on every cycle reachable from the start step, so a deliberate
+> ask-again loop (a step that routes back until a condition sends it onward) carried a warning that
+> told the author nothing. The reference now computes the strongly connected sets (Tarjan) over
+> `next.default` and `next.conditions[].goto` edges reachable from start (markers `null` /
+> `orchestrator` and unknown steps are not followed; `end` is an ordinary step) and warns once when
+> a cyclic set (more than one step, or a self-loop) has no exit. A member leaves the set when it has
+> no `next`, its `next` has `parallel` (a fan-out is treated as an exit, not guessed at), its
+> `next.default` is empty (when no condition matches the flow ends), or any default or condition
+> target is `null`, `orchestrator` or a step outside the set. Code and severity are unchanged; the
+> message now ends "a cycle of steps has no way out" and the suggestion asks for a `next.conditions`
+> branch that leaves the cycle. It cannot prove an exit ever fires; that is undecidable from the
+> YAML. Module: `validators/connectivity.ts`. Gates: ten `valid-cycle-*` / `warn-cycle-*` fixtures
+> (the valid ones use `forbidWarningCodes`, the only way to assert a false-positive risk), shared
+> byte for byte with the Go port. On the 227 bundled example flows both ports report 0 findings.
+
 > package 0.23.0 — **`unknown_function_operation`**, in step with the reference (AIgentFlow
 > v2.831.0; `specVersion` 2.831.0). One new **error**: a step or loop sub-step whose executor
 > is `function://<a>/<b>` where `<a>/<b>` is not one of the 32 registered built-ins. Before

package/dist/cli.js

@@ -2732,31 +2732,81 @@ function validateConnectivity(flow, issues) {
       });
     }
   }
-  const visited = /* @__PURE__ */ new Set();
-  const recStack = /* @__PURE__ */ new Set();
-  const hasCycle = (stepID) => {
-    if (recStack.has(stepID)) return true;
-    if (visited.has(stepID)) return false;
-    visited.add(stepID);
-    recStack.add(stepID);
-    const step = steps[stepID];
-    if (isRecord(step) && isRecord(step.next)) {
-      const next = step.next;
-      for (const target of cycleTargets(next, `steps.${stepID}.next`, issues)) {
-        if (hasCycle(target)) return true;
-      }
-    }
-    recStack.delete(stepID);
-    return false;
-  };
-  if (hasCycle(start)) {
+  if (cycleWithoutExit(steps, start, issues)) {
     issues.warn({
       field: "steps",
-      message: "Potential infinite loop detected in step flow",
+      message: "Potential infinite loop detected in step flow: a cycle of steps has no way out",
       code: "potential_infinite_loop",
-      suggestion: "Review your step transitions to ensure they eventually terminate"
+      suggestion: "Give one step in the cycle a `next.conditions` branch that leaves it (or end the flow there)"
+    });
+  }
+}
+function cycleEdges(step, stepID, issues) {
+  if (!isRecord(step) || !isRecord(step.next)) return [];
+  const next = step.next;
+  const nextPath = `steps.${stepID}.next`;
+  const out = [];
+  const def = issues.stringOf(next, "default", nextPath);
+  if (def !== null && def !== "") out.push(def);
+  if (Array.isArray(next.conditions)) {
+    next.conditions.forEach((cond, i) => {
+      if (!isRecord(cond)) return;
+      const goto = issues.stringOf(cond, "goto", `${nextPath}.conditions[${i}]`);
+      if (goto !== null && goto !== "") out.push(goto);
     });
   }
+  return out;
+}
+function stepLeavesCycle(steps, stepID, inCycle, issues) {
+  const step = steps[stepID];
+  if (!isRecord(step) || !isRecord(step.next)) return true;
+  const next = step.next;
+  if (next.parallel !== void 0 && next.parallel !== null) return true;
+  const def = issues.stringOf(next, "default", `steps.${stepID}.next`);
+  if (def === null || def === "") return true;
+  for (const target of cycleEdges(step, stepID, issues)) {
+    if (isMarker(target) || !inCycle.has(target)) return true;
+  }
+  return false;
+}
+function cycleWithoutExit(steps, start, issues) {
+  let index = 0;
+  const indices = /* @__PURE__ */ new Map();
+  const low = /* @__PURE__ */ new Map();
+  const onStack = /* @__PURE__ */ new Set();
+  const stack = [];
+  let found = false;
+  const strong = (id) => {
+    indices.set(id, index);
+    low.set(id, index);
+    index++;
+    stack.push(id);
+    onStack.add(id);
+    for (const target of cycleEdges(steps[id], id, issues)) {
+      if (isMarker(target) || !Object.prototype.hasOwnProperty.call(steps, target)) continue;
+      if (!indices.has(target)) {
+        strong(target);
+        low.set(id, Math.min(low.get(id), low.get(target)));
+      } else if (onStack.has(target)) {
+        low.set(id, Math.min(low.get(id), indices.get(target)));
+      }
+    }
+    if (low.get(id) !== indices.get(id)) return;
+    const component = [];
+    for (; ; ) {
+      const top = stack.pop();
+      onStack.delete(top);
+      component.push(top);
+      if (top === id) break;
+    }
+    const inCycle = new Set(component);
+    const cyclic = component.length > 1 || cycleEdges(steps[id], id, issues).includes(id);
+    if (!cyclic) return;
+    if (component.some((member) => stepLeavesCycle(steps, member, inCycle, issues))) return;
+    found = true;
+  };
+  if (Object.prototype.hasOwnProperty.call(steps, start)) strong(start);
+  return found;
 }
 
 // src/validators/nextLogic.ts

package/dist/index.cjs

@@ -2633,31 +2633,81 @@ function validateConnectivity(flow, issues) {
       });
     }
   }
-  const visited = /* @__PURE__ */ new Set();
-  const recStack = /* @__PURE__ */ new Set();
-  const hasCycle = (stepID) => {
-    if (recStack.has(stepID)) return true;
-    if (visited.has(stepID)) return false;
-    visited.add(stepID);
-    recStack.add(stepID);
-    const step = steps[stepID];
-    if (isRecord(step) && isRecord(step.next)) {
-      const next = step.next;
-      for (const target of cycleTargets(next, `steps.${stepID}.next`, issues)) {
-        if (hasCycle(target)) return true;
-      }
-    }
-    recStack.delete(stepID);
-    return false;
-  };
-  if (hasCycle(start)) {
+  if (cycleWithoutExit(steps, start, issues)) {
     issues.warn({
       field: "steps",
-      message: "Potential infinite loop detected in step flow",
+      message: "Potential infinite loop detected in step flow: a cycle of steps has no way out",
       code: "potential_infinite_loop",
-      suggestion: "Review your step transitions to ensure they eventually terminate"
+      suggestion: "Give one step in the cycle a `next.conditions` branch that leaves it (or end the flow there)"
+    });
+  }
+}
+function cycleEdges(step, stepID, issues) {
+  if (!isRecord(step) || !isRecord(step.next)) return [];
+  const next = step.next;
+  const nextPath = `steps.${stepID}.next`;
+  const out = [];
+  const def = issues.stringOf(next, "default", nextPath);
+  if (def !== null && def !== "") out.push(def);
+  if (Array.isArray(next.conditions)) {
+    next.conditions.forEach((cond, i) => {
+      if (!isRecord(cond)) return;
+      const goto = issues.stringOf(cond, "goto", `${nextPath}.conditions[${i}]`);
+      if (goto !== null && goto !== "") out.push(goto);
     });
   }
+  return out;
+}
+function stepLeavesCycle(steps, stepID, inCycle, issues) {
+  const step = steps[stepID];
+  if (!isRecord(step) || !isRecord(step.next)) return true;
+  const next = step.next;
+  if (next.parallel !== void 0 && next.parallel !== null) return true;
+  const def = issues.stringOf(next, "default", `steps.${stepID}.next`);
+  if (def === null || def === "") return true;
+  for (const target of cycleEdges(step, stepID, issues)) {
+    if (isMarker(target) || !inCycle.has(target)) return true;
+  }
+  return false;
+}
+function cycleWithoutExit(steps, start, issues) {
+  let index = 0;
+  const indices = /* @__PURE__ */ new Map();
+  const low = /* @__PURE__ */ new Map();
+  const onStack = /* @__PURE__ */ new Set();
+  const stack = [];
+  let found = false;
+  const strong = (id) => {
+    indices.set(id, index);
+    low.set(id, index);
+    index++;
+    stack.push(id);
+    onStack.add(id);
+    for (const target of cycleEdges(steps[id], id, issues)) {
+      if (isMarker(target) || !Object.prototype.hasOwnProperty.call(steps, target)) continue;
+      if (!indices.has(target)) {
+        strong(target);
+        low.set(id, Math.min(low.get(id), low.get(target)));
+      } else if (onStack.has(target)) {
+        low.set(id, Math.min(low.get(id), indices.get(target)));
+      }
+    }
+    if (low.get(id) !== indices.get(id)) return;
+    const component = [];
+    for (; ; ) {
+      const top = stack.pop();
+      onStack.delete(top);
+      component.push(top);
+      if (top === id) break;
+    }
+    const inCycle = new Set(component);
+    const cyclic = component.length > 1 || cycleEdges(steps[id], id, issues).includes(id);
+    if (!cyclic) return;
+    if (component.some((member) => stepLeavesCycle(steps, member, inCycle, issues))) return;
+    found = true;
+  };
+  if (Object.prototype.hasOwnProperty.call(steps, start)) strong(start);
+  return found;
 }
 
 // src/validators/nextLogic.ts