automategraph 1.5.1 → 1.5.3

package/tests/lint.test.ts

@@ -0,0 +1,381 @@
+/* ============================================================
+ * LINT PACK — success dead-end rule (v1.2)
+ * ------------------------------------------------------------
+ * Closes the gap found while explaining the C-19 resilience
+ * fixture: a non-terminal node whose success path has nowhere to
+ * go (no `next`) used to pass linting as long as it declared an
+ * error transition.
+ *
+ * New code:
+ *   SUCCESS_DEAD_END (error tier) — the node can only "continue"
+ *   when it fails; a successful output is silently unreachable.
+ *   DEAD_END_NODE stays for the total case (no transitions at all).
+ * The two are mutually exclusive: every node with no `next` gets
+ * exactly one of them.
+ * ============================================================ */
+
+import { GraphExecutionEngine, lintGraph } from "../src/automategraph";
+import { capture, constNode, g, logCollector, node, sleep } from "./helpers";
+import { suite } from "./harness";
+
+const lint = suite("lint", "Success dead-end rule");
+
+const BIG = { timeoutMs: 20_000 };
+
+/**
+ * The exact C-19 resilience fixture (with its test gate), rebuilt per
+ * call so each test gets a fresh gate promise.
+ */
+function resilienceFixture(options: { slowNext?: string[] } = {}) {
+  let releaseFast: () => void = () => {};
+  const fallbackDone = new Promise<void>(resolve => { releaseFast = resolve; });
+
+  const definition = g({
+    nodes: [
+      node("start", () => 1, { next: ["slow-vendor", "fast-vendor"] }),
+      node("slow-vendor", async () => { await sleep(80); return "vendor-result"; }, {
+        timeoutMs: 25,
+        onThrow: "vendor-fallback",
+        ...(options.slowNext ? { next: options.slowNext } : {})
+      }),
+      node("vendor-fallback", () => { releaseFast(); return "cached-price"; }, { next: ["decide"] }),
+      node("fast-vendor", async () => {
+        await Promise.race([fallbackDone, sleep(2000)]);
+        return "fresh-price";
+      }, { next: ["decide"] }),
+      node("decide", async context => {
+        await context.emit("pricing.decided", { fallback: context.outputs["vendor-fallback"] });
+        return "decided";
+      }, { next: ["finish"] }),
+      constNode("finish", "DONE")
+    ],
+    entryNodes: ["start"],
+    terminalNodes: ["finish"]
+  });
+
+  return definition;
+}
+
+const codesFor = (definition: Parameters<typeof lintGraph>[0], nodeId: string): string[] =>
+  lintGraph(definition)
+    .filter(issue => issue.nodeId === nodeId)
+    .map(issue => issue.code);
+
+/* ------------------------------ the rule ------------------------------ */
+
+lint.t(
+  "the exact C-19 fixture is flagged: slow-vendor succeeds into a void",
+  async t => {
+    const issues = lintGraph(resilienceFixture());
+    const slowIssues = issues.filter(issue => issue.nodeId === "slow-vendor");
+
+    if (slowIssues.length !== 1) {
+      throw new Error(`slow-vendor issues=${slowIssues.map(i => i.code).join(",") || "none"}`);
+    }
+
+    const issue = slowIssues[0];
+    if (issue.code !== "SUCCESS_DEAD_END") throw new Error(issue.code);
+    if (issue.level !== "error") throw new Error(issue.level);
+    if (!issue.message.includes('"slow-vendor"')) throw new Error(issue.message);
+    if (!issue.message.includes("no next target")) throw new Error(issue.message);
+
+    // mutual exclusivity: the old code must not also fire here
+    if (codesFor(resilienceFixture(), "slow-vendor").includes("DEAD_END_NODE")) {
+      throw new Error("both rules fired for the same node");
+    }
+
+    t.log("issue", `${issue.level}/${issue.code} @ ${issue.nodeId}`);
+    t.log(
+      "finding: a node can declare onThrow and still be unreachable on its success path — " +
+      "the previous DEAD_END_NODE rule only asked whether *any* transition existed"
+    );
+  },
+  BIG
+);
+
+lint.t(
+  "the fix suggested by the message clears the issue (next declared)",
+  async t => {
+    const fixed = resilienceFixture({ slowNext: ["decide"] });
+    const slowIssues = codesFor(fixed, "slow-vendor");
+
+    if (slowIssues.includes("SUCCESS_DEAD_END")) throw new Error("issue survived the fix");
+    if (slowIssues.length !== 0) throw new Error(slowIssues.join(","));
+
+    t.log("slow-vendor issues after adding next", slowIssues.length);
+  },
+  BIG
+);
+
+lint.t(
+  "declared terminal nodes are never flagged, even without next",
+  () => {
+    const definition = g({
+      nodes: [constNode("start", "S", { next: ["end"] }), constNode("end", "E")],
+      entryNodes: ["start"],
+      terminalNodes: ["end"]
+    });
+
+    const issues = lintGraph(definition);
+    if (issues.some(issue => issue.nodeId === "end")) {
+      throw new Error(`terminal flagged: ${issues.map(i => i.code).join(",")}`);
+    }
+    if (issues.length !== 0) throw new Error(issues.map(i => i.code).join(","));
+  }
+);
+
+lint.t(
+  "a node with no transitions at all is DEAD_END_NODE, not SUCCESS_DEAD_END",
+  () => {
+    const definition = g({
+      nodes: [
+        constNode("start", "S", { next: ["dead", "end"] }),
+        constNode("dead", "D"),
+        constNode("end", "E")
+      ],
+      entryNodes: ["start"],
+      terminalNodes: ["end"]
+    });
+
+    const codes = codesFor(definition, "dead");
+    if (!codes.includes("DEAD_END_NODE")) throw new Error(`codes=${codes.join(",")}`);
+    if (codes.includes("SUCCESS_DEAD_END")) throw new Error("wrong rule fired");
+  }
+);
+
+lint.t(
+  "an ignored fallback does not count as a live error transition",
+  () => {
+    const definition = g({
+      nodes: [
+        constNode("start", "S", { next: ["orphanish", "end"] }),
+        // fallback declared, but the effective policy is CONTINUE ⇒ inert
+        node("orphanish", () => "O", { fallback: "end" }),
+        constNode("end", "E")
+      ],
+      entryNodes: ["start"],
+      terminalNodes: ["end"]
+    });
+
+    const codes = codesFor(definition, "orphanish");
+    if (!codes.includes("DEAD_END_NODE")) throw new Error(`codes=${codes.join(",")}`);
+    if (!codes.includes("FALLBACK_TARGET_IGNORED")) throw new Error(`codes=${codes.join(",")}`);
+    if (codes.includes("SUCCESS_DEAD_END")) throw new Error("inert fallback treated as live");
+  }
+);
+
+lint.t(
+  "a live fallback (policy FALLBACK) makes it SUCCESS_DEAD_END, not a total dead end",
+  () => {
+    const definition = g({
+      nodes: [
+        constNode("start", "S", { next: ["primary", "end"] }),
+        node("primary", () => "P", { errorPolicy: "FALLBACK", fallback: "end" }),
+        constNode("end", "E")
+      ],
+      entryNodes: ["start"],
+      terminalNodes: ["end"]
+    });
+
+    const codes = codesFor(definition, "primary");
+    if (!codes.includes("SUCCESS_DEAD_END")) throw new Error(`codes=${codes.join(",")}`);
+    if (codes.includes("DEAD_END_NODE")) throw new Error("total dead end wrongly reported");
+    if (codes.includes("FALLBACK_TARGET_IGNORED")) throw new Error("fallback should be live");
+  }
+);
+
+lint.t(
+  "onThrow alone is treated as a live error transition",
+  () => {
+    const definition = g({
+      nodes: [
+        constNode("start", "S", { next: ["risky", "end"] }),
+        node("risky", () => "R", { onThrow: "end" }),
+        constNode("end", "E")
+      ],
+      entryNodes: ["start"],
+      terminalNodes: ["end"]
+    });
+
+    const codes = codesFor(definition, "risky");
+    if (codes.length !== 1 || codes[0] !== "SUCCESS_DEAD_END") {
+      throw new Error(`codes=${codes.join(",")}`);
+    }
+  }
+);
+
+lint.t(
+  "unreachable nodes with a success path stay unreachable-only (no noise)",
+  () => {
+    const definition = g({
+      nodes: [
+        constNode("start", "S", { next: ["end"] }),
+        constNode("end", "E"),
+        constNode("floating", "F", { next: ["end"] })
+      ],
+      entryNodes: ["start"],
+      terminalNodes: ["end"]
+    });
+
+    const codes = codesFor(definition, "floating");
+    if (!codes.includes("UNREACHABLE_NODE")) throw new Error(`codes=${codes.join(",")}`);
+    if (codes.includes("SUCCESS_DEAD_END")) throw new Error("unexpected success dead-end");
+  }
+);
+
+lint.t(
+  "every issue has a stable shape and a known code",
+  t => {
+    const known = new Set([
+      "DUPLICATE_ENTRY",
+      "DUPLICATE_TERMINAL",
+      "UNREACHABLE_NODE",
+      "UNREACHABLE_TERMINAL",
+      "DEAD_END_NODE",
+      "SUCCESS_DEAD_END",
+      "FALLBACK_TARGET_IGNORED"
+    ]);
+
+    const messy = g({
+      nodes: [
+        constNode("start", "S", { next: ["risky", "orphan"] }),
+        node("risky", () => "R", { onThrow: "end" }),
+        constNode("orphan", "O"),
+        constNode("end", "E")
+      ],
+      entryNodes: ["start", "start"],
+      terminalNodes: ["end"]
+    });
+
+    const issues = lintGraph(messy);
+    if (issues.length === 0) throw new Error("expected issues");
+
+    for (const issue of issues) {
+      if (issue.level !== "error" && issue.level !== "warn") throw new Error(issue.level);
+      if (!known.has(issue.code)) throw new Error(`unknown code ${issue.code}`);
+      if (typeof issue.message !== "string" || issue.message.length === 0) throw new Error("empty");
+      if (typeof issue.nodeId !== "string" || issue.nodeId.length === 0) throw new Error("missing nodeId");
+    }
+
+    const codes = new Set(issues.map(issue => issue.code));
+    for (const expected of ["DUPLICATE_ENTRY", "SUCCESS_DEAD_END", "DEAD_END_NODE"]) {
+      if (!codes.has(expected as never)) throw new Error(`missing ${expected}`);
+    }
+
+    t.log("codes observed", [...codes].join(", "));
+  }
+);
+
+/* --------------------------- engine integration --------------------------- */
+
+lint.t(
+  "lint: \"warn\" logs SUCCESS_DEAD_END and still completes the C-19 run",
+  async t => {
+    const { lines, onLog } = logCollector();
+    const engine = new GraphExecutionEngine(resilienceFixture(), { lint: "warn", onLog });
+
+    const report = await engine.run();
+
+    if (report.status !== "COMPLETED") throw new Error(report.status);
+    if (!report.results.some(result => result.nodeId === "finish")) throw new Error("finish never ran");
+
+    const logged = lines.filter(line => line.message.includes("Graph lint [SUCCESS_DEAD_END]"));
+    if (logged.length !== 1) throw new Error(`lint log lines=${logged.length}`);
+    // the line carries the ISSUE severity ("error"); the mode only decides
+    // whether error-tier issues are enforced or merely reported
+    if (logged[0].level !== "error") throw new Error(logged[0].level);
+
+    const issues = report.lintIssues.filter(issue => issue.code === "SUCCESS_DEAD_END");
+    if (issues.length !== 1 || issues[0].nodeId !== "slow-vendor") {
+      throw new Error("lintIssues missing from the report");
+    }
+
+    t.log("run status", report.status, "| issue logged at severity 'error' but not enforced in warn mode");
+  },
+  BIG
+);
+
+lint.t(
+  "lint: \"error\" rejects the C-19 graph before any node runs",
+  async t => {
+    const engine = new GraphExecutionEngine(resilienceFixture(), { lint: "error" });
+    const started = await engine.run();
+
+    if (started.status !== "REJECTED") throw new Error(started.status);
+    if (started.results.length !== 0) throw new Error(`ran ${started.results.length} nodes`);
+    if (Object.keys(started.outputs).length !== 0) throw new Error("outputs recorded");
+    if (!started.errors[0].message.includes("Graph lint reported")) {
+      throw new Error(started.errors[0].message);
+    }
+    if (!started.lintIssues.some(issue => issue.code === "SUCCESS_DEAD_END")) {
+      throw new Error("lintIssues missing");
+    }
+
+    t.log("finding: lint enforcement is a pre-flight gate — the graph is rejected before " +
+      "initialization finishes, so no side effects from node callbacks can occur");
+  },
+  BIG
+);
+
+/* ------------------------------ regression ------------------------------ */
+
+lint.t(
+  "the C-01 order-pipeline fixture flags audit as DEAD_END_NODE (documented gotcha)",
+  async t => {
+    const definition = g({
+      id: "order-pipeline",
+      version: "2.1.0",
+      nodes: [
+        node("validate", () => ({ orderId: 7, amount: 120 }), { next: ["fraud", "audit"] }),
+        node("fraud", () => "clean", { next: ["charge"] }),
+        node("charge", () => ({ charged: 120 }), { next: ["ship"] }),
+        node("ship", () => "SHIPPED", { next: ["notify"] }),
+        constNode("notify", "EMAIL_SENT"),
+        constNode("audit", "AUDITED")
+      ],
+      entryNodes: ["validate"],
+      terminalNodes: ["notify"]
+    });
+
+    const issues = lintGraph(definition);
+
+    const audit = issues.filter(issue => issue.nodeId === "audit");
+    if (audit.length !== 1 || audit[0].code !== "DEAD_END_NODE") {
+      throw new Error(`audit issues=${audit.map(i => i.code).join(",") || "none"}`);
+    }
+    if (issues.some(issue => issue.nodeId === "notify")) throw new Error("terminal flagged");
+
+    // the fixture still runs fine — linting is off by default
+    const report = await new GraphExecutionEngine(definition).run();
+    if (report.status !== "COMPLETED") throw new Error(report.status);
+
+    t.log("audit", `${audit[0].level}/${audit[0].code}`, "| run", report.status);
+  },
+  BIG
+);
+
+lint.t(
+  "a graph with no transition problems lints clean and runs",
+  async t => {
+    const definition = g({
+      nodes: [
+        node("a", () => "A", { next: ["b"] }),
+        node("b", () => "B", { next: ["c"] }),
+        constNode("c", "C")
+      ],
+      entryNodes: ["a"],
+      terminalNodes: ["c"]
+    });
+
+    const issues = lintGraph(definition);
+    if (issues.length !== 0) throw new Error(issues.map(issue => issue.code).join(","));
+
+    const engine = new GraphExecutionEngine(definition, { lint: "error" });
+    const captured = capture(engine, ["graph.finished"]);
+    const report = await engine.run();
+
+    if (report.status !== "COMPLETED") throw new Error(report.status);
+    if (captured.length !== 1) throw new Error("graph.finished missing");
+  },
+  BIG
+);