@vaudience/aigentflow-flow-validator 0.22.0 → 0.24.0

package/dist/index.js

@@ -433,7 +433,7 @@ function validateBasicStructure(flow, issues) {
           message: "Executor is required for each step",
           code: "missing_required_field",
           stepId: stepID,
-          suggestion: "Specify an executor URL (e.g., 'function://demo/processor')"
+          suggestion: "Specify an executor URL (e.g., 'function://utils/log')"
         });
       } else if (executorText === null) {
         issues.error({
@@ -449,7 +449,7 @@ function validateBasicStructure(flow, issues) {
 
 // src/spec/aigentflow-spec.json
 var aigentflow_spec_default = {
-  specVersion: "2.828.0",
+  specVersion: "2.831.0",
   inputSchemaVersion: 1,
   executorSchemes: [
     "a2a",
@@ -946,6 +946,46 @@ var aigentflow_spec_default = {
     stepFieldFormat: "steps.%s.query.%s",
     loopStepFieldFormat: "steps.%s.loop.steps.%s.query.%s"
   },
+  functionOperations: {
+    code: "unknown_function_operation",
+    scheme: "function",
+    messageFormat: "step %s uses function://%s, which is not a built-in function. Available: %s",
+    suggestionFormat: "Use one of the built-in function operations: %s. For custom logic use a script://, http:// or ai:// executor instead.",
+    operations: [
+      "binary-processor/validate-and-store",
+      "data/create",
+      "data/from-json",
+      "data/to-json",
+      "data/validate",
+      "demo/adult-processor",
+      "demo/calculator",
+      "demo/data-processor",
+      "demo/finalizer",
+      "demo/senior-processor",
+      "demo/youth-processor",
+      "document/finalize",
+      "document/prepare",
+      "json/validate",
+      "math/basic",
+      "math/calculate",
+      "math/sum",
+      "results-compiler/aggregate",
+      "system/info",
+      "text/analysis",
+      "text/count-characters",
+      "text/count-lines",
+      "text/count-occurrences",
+      "text/count-words",
+      "text/find-pattern",
+      "text/generate",
+      "text/replace-text",
+      "text/search",
+      "utils/datetime",
+      "utils/format-date",
+      "utils/log",
+      "utils/parse-date"
+    ]
+  },
   flowDataReservedKeys: {
     code: "flow_data_key_reserved",
     fieldFormat: "data.%s",
@@ -1980,9 +2020,51 @@ var TEMPLATE_DEFAULT_PIPED = {
   messageFormat: aigentflow_spec_default.templateDefaultPiped.messageFormat,
   suggestion: aigentflow_spec_default.templateDefaultPiped.suggestion
 };
+var FUNCTION_OPERATIONS = {
+  code: aigentflow_spec_default.functionOperations.code,
+  scheme: aigentflow_spec_default.functionOperations.scheme,
+  messageFormat: aigentflow_spec_default.functionOperations.messageFormat,
+  suggestionFormat: aigentflow_spec_default.functionOperations.suggestionFormat,
+  operations: new Set(aigentflow_spec_default.functionOperations.operations),
+  sorted: aigentflow_spec_default.functionOperations.operations
+};
 
 // src/validators/executors.ts
 var SCHEME_SEPARATOR = "://";
+var UNKNOWN_SCHEME_BASE = (scheme) => `Unknown executor scheme '${scheme}'. It may be valid in a newer AIgentFlow release, or it could be a typo.`;
+var DECIDE_SCHEME = "decide";
+var DECIDE_HINT = "Decision models run through ai://{provider}/decide (for example ai://openai/decide), not through a scheme of their own.";
+var MAX_SCHEME_EDIT_DISTANCE = 2;
+function editDistance(a, b) {
+  let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
+  for (let i = 1; i <= a.length; i++) {
+    const cur = [i];
+    for (let j = 1; j <= b.length; j++) {
+      cur[j] = Math.min(
+        prev[j] + 1,
+        cur[j - 1] + 1,
+        prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1)
+      );
+    }
+    prev = cur;
+  }
+  return prev[b.length];
+}
+function unknownSchemeMessage(scheme) {
+  const lower = scheme.toLowerCase();
+  const base = UNKNOWN_SCHEME_BASE(scheme);
+  if (lower === DECIDE_SCHEME) return `${base} ${DECIDE_HINT}`;
+  let best;
+  let bestDist = MAX_SCHEME_EDIT_DISTANCE + 1;
+  for (const known of [...EXECUTOR_SCHEMES].sort()) {
+    const d = editDistance(lower, known);
+    if (d < bestDist) {
+      best = known;
+      bestDist = d;
+    }
+  }
+  return best === void 0 ? base : `${base} Did you mean '${best}'?`;
+}
 function checkExecutor(executor, field, stepID, issues) {
   const sepIdx = executor.indexOf(SCHEME_SEPARATOR);
   const scheme = sepIdx > 0 ? executor.slice(0, sepIdx) : "";
@@ -2001,11 +2083,28 @@ function checkExecutor(executor, field, stepID, issues) {
   if (!EXECUTOR_SCHEMES.has(scheme.toLowerCase())) {
     issues.warn({
       field,
-      message: `Unknown executor scheme '${scheme}'. It may be valid in a newer AIgentFlow release, or it could be a typo.`,
+      message: unknownSchemeMessage(scheme),
       code: "unknown_executor_scheme",
       stepId: stepID
     });
+    return;
   }
+  checkFunctionOperation(executor, field, stepID, templated, issues);
+}
+function checkFunctionOperation(executor, field, stepID, templated, issues) {
+  if (templated) return;
+  const m = EXECUTOR_URL_PATTERN.exec(executor);
+  if (m === null || m[1] !== FUNCTION_OPERATIONS.scheme) return;
+  const op = `${m[2]}/${m[3]}`;
+  if (FUNCTION_OPERATIONS.operations.has(op)) return;
+  const list = FUNCTION_OPERATIONS.sorted.join(", ");
+  issues.error({
+    field,
+    message: FUNCTION_OPERATIONS.messageFormat.replace("%s", () => JSON.stringify(stepID)).replace("%s", () => op).replace("%s", () => list),
+    code: FUNCTION_OPERATIONS.code,
+    stepId: stepID,
+    suggestion: FUNCTION_OPERATIONS.suggestionFormat.replace("%s", () => list)
+  });
 }
 function validateExecutors(flow, issues) {
   const steps = flow.steps;
@@ -2532,32 +2631,82 @@ 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
 var NEXT_NULL = "null";