automategraph 1.5.1 → 1.5.3

package/tests/graphjson.test.ts

@@ -0,0 +1,737 @@
+/* ============================================================
+ * GRAPH JSON LOADER PACK (v1.4)
+ * ------------------------------------------------------------
+ * src/graph-json.ts turns a data document into a GraphDefinition:
+ *
+ *   { "id", "version", "entryNodes", "terminalNodes",
+ *     "nodes": { "a": { "run": "fnName",
+ *                       "next": [ { "test": "predName", "nextNode": "b" },
+ *                                 { "nextNode": "c" } ] } } }
+ *
+ * Under test:
+ *   • parsing needs NO registry (names resolve lazily in the engine)
+ *   • validation is total — every problem is collected with its JSON
+ *     path and thrown as one GraphJSONError carrying `issues`
+ *   • createEngineFromJSON(document, { functions }) is the whole
+ *     pipeline: data file → running engine → report with fingerprint
+ * ============================================================ */
+
+import { GraphExecutionEngine, GraphValidationError } from "../src/automategraph";
+import {
+  GraphJSONError,
+  createEngineFromJSON,
+  isGraphJSON,
+  parseGraphJSON
+} from "../src/graph-json";
+
+import { BIG, capture } from "./helpers";
+import { suite } from "./harness";
+
+const json = suite("graphjson", "Graph JSON loader");
+
+/* ------------------------------ helpers ------------------------------ */
+
+const DOCUMENT = {
+  id: "order-flow",
+  version: "1.0.0",
+  entryNodes: ["classify"],
+  terminalNodes: ["ship", "manual", "reject"],
+  completionPolicy: "FIRST_TERMINAL",
+  nodes: {
+    classify: {
+      run: "classifyOrder",
+      next: [
+        { test: "isPriority", nextNode: "charge" },
+        { result: "manual", nextNode: "manual" },
+        { nextNode: "reject" }
+      ]
+    },
+    charge: {
+      run: "chargeCard",
+      next: ["ship"],
+      onThrow: "manual",
+      errorPolicy: "RETRY",
+      retry: { maxAttempts: 2, delayMs: 1 }
+    },
+    ship: { run: "shipOrder" },
+    manual: { run: "manualReview" },
+    reject: { run: "rejectOrder" }
+  }
+};
+
+const FUNCTIONS = {
+  classifyOrder: () => "priority",
+  isPriority: (value: unknown) => value === "priority",
+  chargeCard: () => "charged",
+  shipOrder: () => "shipped",
+  manualReview: () => "queued",
+  rejectOrder: () => "rejected"
+};
+
+function issuesOf(input: unknown): Array<{ path: string; message: string }> {
+  try {
+    parseGraphJSON(input);
+  } catch (error) {
+    if (error instanceof GraphJSONError) return [...error.issues];
+    throw error;
+  }
+
+  throw new Error("expected a GraphJSONError");
+}
+
+function issuePaths(input: unknown): string[] {
+  return issuesOf(input).map(issue => issue.path);
+}
+
+function catchJSONError(input: unknown): GraphJSONError {
+  try {
+    parseGraphJSON(input);
+  } catch (error) {
+    if (error instanceof GraphJSONError) return error;
+    throw error;
+  }
+
+  throw new Error("expected a GraphJSONError");
+}
+
+function ok(condition: unknown, label: string): void {
+  if (!condition) throw new Error(label);
+}
+
+function eq(actual: unknown, expected: unknown, label: string): void {
+  if (actual !== expected) {
+    throw new Error(
+      `${label}: expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`
+    );
+  }
+}
+
+function stable(value: unknown): string {
+  return JSON.stringify(sortKeys(value)) ?? "undefined";
+}
+
+function sortKeys(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortKeys);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.keys(value as Record<string, unknown>)
+        .sort()
+        .map(key => [key, sortKeys((value as Record<string, unknown>)[key])])
+    );
+  }
+  return value;
+}
+
+function deepEq(actual: unknown, expected: unknown, label: string): void {
+  const a = stable(actual);
+  const b = stable(expected);
+
+  if (a !== b) throw new Error(`${label}: expected ${b}, got ${a}`);
+}
+
+/* ------------------------------ 1. parsing ------------------------------ */
+
+json.t(
+  "a valid document parses into a GraphDefinition (string and object input agree)",
+  async t => {
+    const fromObject = parseGraphJSON(DOCUMENT);
+    const fromText = parseGraphJSON(JSON.stringify(DOCUMENT));
+
+    deepEq(fromText, fromObject, "text and object input agree");
+
+    eq(fromObject.id, "order-flow", "id");
+    eq(fromObject.version, "1.0.0", "version");
+    deepEq(fromObject.entryNodes, ["classify"], "entryNodes");
+    deepEq(
+      fromObject.terminalNodes,
+      ["ship", "manual", "reject"],
+      "terminalNodes"
+    );
+    eq(fromObject.completionPolicy, "FIRST_TERMINAL", "completionPolicy");
+    deepEq(Object.keys(fromObject.nodes), ["classify", "charge", "ship", "manual", "reject"], "nodes");
+
+    eq(fromObject.nodes.classify.run, "classifyOrder", "run stays a name");
+    eq(
+      typeof fromObject.nodes.classify.next?.[0],
+      "object",
+      "edge objects survive parsing"
+    );
+    deepEq(
+      fromObject.nodes.charge.next,
+      ["ship"],
+      "string edges stay strings"
+    );
+    eq(fromObject.nodes.charge.onThrow, "manual", "onThrow");
+    eq(fromObject.nodes.charge.errorPolicy, "RETRY", "errorPolicy");
+    deepEq(
+      fromObject.nodes.charge.retry,
+      { maxAttempts: 2, delayMs: 1 },
+      "retry"
+    );
+
+    t.log("finding: parsing never needs the registry — a data file is valid even when a function name is unknown; the engine decides that at run time");
+  },
+  BIG
+);
+
+json.t(
+  "node ids default to their keys, and a mismatching explicit id is an issue",
+  async t => {
+    const parsed = parseGraphJSON({
+      id: "g",
+      version: "1",
+      entryNodes: ["a"],
+      terminalNodes: ["a"],
+      nodes: { a: { run: "fn" } }
+    });
+
+    eq(parsed.nodes.a.id, "a", "id defaults to the key");
+
+    const paths = issuePaths({
+      id: "g",
+      version: "1",
+      entryNodes: ["a"],
+      terminalNodes: ["a"],
+      nodes: { a: { id: "elsewhere", run: "fn" } }
+    });
+
+    ok(paths.includes("nodes.a.id"), paths.join(","));
+  },
+  BIG
+);
+
+json.t(
+  "deep-equality results, named tests and parallel flags survive the round trip",
+  async t => {
+    const parsed = parseGraphJSON({
+      id: "g",
+      version: "1",
+      entryNodes: ["a"],
+      terminalNodes: ["b", "c", "d"],
+      nodes: {
+        a: {
+          run: "fn",
+          next: [
+            { test: "isBig", nextNode: "b" },
+            { result: { nested: [1, { two: "2" }], nil: null }, nextNode: "c" },
+            "d"
+          ]
+        },
+        b: { run: "fn" },
+        c: { run: "fn" },
+        d: { run: "fn" }
+      }
+    });
+
+    const edges = parsed.nodes.a.next ?? [];
+
+    deepEq(edges[0], { test: "isBig", nextNode: "b" }, "named test edge");
+    deepEq(
+      edges[1],
+      { result: { nested: [1, { two: "2" }], nil: null }, nextNode: "c" },
+      "structured result matcher"
+    );
+    eq(edges[2], "d", "string edge");
+  },
+  BIG
+);
+
+/* ------------------------------ 2. end-to-end ------------------------------ */
+
+json.t(
+  "createEngineFromJSON runs the data file and reports the registry fingerprint",
+  async t => {
+    const engine = createEngineFromJSON(JSON.stringify(DOCUMENT), {
+      functions: FUNCTIONS,
+      lint: "error"
+    });
+
+    const captured = capture(engine, ["node.succeeded"]);
+    const report = await engine.run();
+
+    eq(report.status, "COMPLETED", "status");
+    deepEq(
+      report.results.map(result => result.nodeId),
+      ["classify", "charge", "ship"],
+      "path"
+    );
+    deepEq(
+      report.results.map(result => result.fn),
+      ["classifyOrder", "chargeCard", "shipOrder"],
+      "fn per activation"
+    );
+    deepEq(report.lintIssues, [], "the data file is lint-clean");
+    deepEq(
+      report.registry?.names,
+      [
+        "chargeCard",
+        "classifyOrder",
+        "isPriority",
+        "manualReview",
+        "rejectOrder",
+        "shipOrder"
+      ],
+      "registry names are sorted"
+    );
+    ok(
+      (report.registry?.fingerprint ?? "").startsWith("fnr1:6:"),
+      `fingerprint: ${report.registry?.fingerprint}`
+    );
+    eq(
+      (captured.at(-1)?.payload as { fn?: string }).fn,
+      "shipOrder",
+      "events carry the function name"
+    );
+  },
+  BIG
+);
+
+json.t(
+  "a named test in the document routes via the supplied registry",
+  async t => {
+    const engine = createEngineFromJSON(DOCUMENT, {
+      functions: { ...FUNCTIONS, classifyOrder: () => "standard" }
+    });
+
+    const report = await engine.run();
+
+    eq(report.status, "COMPLETED", "status");
+    deepEq(
+      report.results.map(result => result.nodeId),
+      ["classify", "reject"],
+      "the else edge caught the unmatched value"
+    );
+    eq(report.outputs.reject, "rejected", "output");
+  },
+  BIG
+);
+
+json.t(
+  "a data file with an unknown name runs and fails with UNKNOWN_FUNCTION",
+  async t => {
+    const engine = createEngineFromJSON(DOCUMENT, {
+      functions: { ...FUNCTIONS, shipOrder: undefined }
+    });
+
+    const report = await engine.run();
+
+    eq(report.status, "FAILED", "status");
+    eq(report.errors[0].code, "UNKNOWN_FUNCTION", "code");
+    eq(report.errors[0].nodeId, "ship", "nodeId");
+    eq(report.errors[0].handled, false, "handled");
+    eq(
+      (report.errors[0].details as { name: string }).name,
+      "shipOrder",
+      "the missing name is named"
+    );
+    deepEq(
+      report.results.map(result => result.status),
+      ["SUCCEEDED", "SUCCEEDED", "FAILED"],
+      "everything before the missing node ran"
+    );
+  },
+  BIG
+);
+
+json.t(
+  "the parsed definition is accepted by the engine unchanged",
+  async t => {
+    const definition = parseGraphJSON(DOCUMENT);
+    const engine = new GraphExecutionEngine(definition, {
+      functions: FUNCTIONS
+    });
+
+    const report = await engine.run();
+
+    eq(report.status, "COMPLETED", "the loader output needs no fixing up");
+    eq(engine.registry.names.length, 6, "registry intact");
+
+    /* the engine's own validation would have thrown on a malformed graph */
+    ok(definition.nodes.classify.run === "classifyOrder", "run name preserved");
+  },
+  BIG
+);
+
+/* ------------------------------ 3. validation: structure ------------------------------ */
+
+json.t(
+  "invalid JSON text is a single, clear GraphJSONError",
+  async t => {
+    let caught: unknown;
+
+    try {
+      parseGraphJSON("{ not json ");
+    } catch (error) {
+      caught = error;
+    }
+
+    ok(caught instanceof GraphJSONError, "GraphJSONError expected");
+    eq((caught as GraphJSONError).code, "GRAPH_JSON_ERROR", "code");
+    deepEq(
+      (caught as GraphJSONError).issues.map(issue => issue.path),
+      ["$"],
+      "path is the document root"
+    );
+    ok(
+      (caught as GraphJSONError).message.includes("not parseable JSON"),
+      (caught as GraphJSONError).message
+    );
+  },
+  BIG
+);
+
+json.t(
+  "a non-object document is rejected with one issue",
+  async t => {
+    const paths = issuePaths([1, 2, 3]);
+
+    deepEq(paths, ["$"], "one issue at the root");
+    ok(
+      issuesOf([1, 2, 3])[0].message.includes("array"),
+      "the message names what arrived"
+    );
+
+    deepEq(issuePaths(null), ["$"], "null");
+    deepEq(issuePaths(42), ["$"], "a number");
+  },
+  BIG
+);
+
+json.t(
+  "unknown properties are rejected at every level",
+  async t => {
+    const paths = issuePaths({
+      id: "g",
+      version: "1",
+      entryNodes: ["a"],
+      terminalNodes: ["a"],
+      extra: true,
+      nodes: {
+        a: { run: "fn", wat: 1, next: [{ nextNode: "a", nope: 2 }] }
+      }
+    });
+
+    ok(paths.includes("extra"), paths.join(","));
+    ok(paths.includes("nodes.a.wat"), paths.join(","));
+    ok(paths.includes("nodes.a.next[0].nope"), paths.join(","));
+  },
+  BIG
+);
+
+json.t(
+  "functions cannot live in the document — the issue points at the engine options",
+  async t => {
+    const issues = issuesOf({ ...DOCUMENT, functions: { a: 1 } });
+
+    eq(issues.length, 1, "one issue");
+    eq(issues[0].path, "functions", "path");
+    ok(
+      issues[0].message.includes("createEngineFromJSON(json, { functions })"),
+      issues[0].message
+    );
+  },
+  BIG
+);
+
+/* ------------------------------ 4. validation: semantics ------------------------------ */
+
+json.t(
+  "dangling references are reported with their paths",
+  async t => {
+    const paths = issuePaths({
+      id: "g",
+      version: "1",
+      entryNodes: ["ghost"],
+      terminalNodes: ["a"],
+      nodes: {
+        a: {
+          run: "fn",
+          next: ["nowhere", { nextNode: "void" }],
+          onThrow: "nobody",
+          fallback: "nobody"
+        }
+      }
+    });
+
+    ok(paths.includes("entryNodes[0]"), paths.join(","));
+    ok(paths.includes("nodes.a.next[0]"), paths.join(","));
+    ok(paths.includes("nodes.a.next[1]"), paths.join(","));
+    ok(paths.includes("nodes.a.onThrow"), paths.join(","));
+    ok(paths.includes("nodes.a.fallback"), paths.join(","));
+  },
+  BIG
+);
+
+json.t(
+  "malformed edges are rejected entry by entry",
+  async t => {
+    const paths = issuePaths({
+      id: "g",
+      version: "1",
+      entryNodes: ["a"],
+      terminalNodes: ["a"],
+      nodes: {
+        a: {
+          run: "fn",
+          next: [
+            42,
+            {},
+            { nextNode: "" },
+            { nextNode: "a", parallel: "yes" },
+            { nextNode: "a", test: 7 },
+            { nextNode: "a", test: "not a name!" }
+          ]
+        }
+      }
+    });
+
+    for (const expected of [
+      "nodes.a.next[0]",
+      "nodes.a.next[1].nextNode",
+      "nodes.a.next[2].nextNode",
+      "nodes.a.next[3].parallel",
+      "nodes.a.next[4].test",
+      "nodes.a.next[5].test"
+    ]) {
+      ok(paths.includes(expected), `${expected} missing from ${paths.join(",")}`);
+    }
+
+    /* `next: {}` is not an array either */
+    const scalarPaths = issuePaths({
+      id: "g",
+      version: "1",
+      entryNodes: ["a"],
+      terminalNodes: ["a"],
+      nodes: { a: { run: "fn", next: {} } }
+    });
+
+    ok(scalarPaths.includes("nodes.a.next"), scalarPaths.join(","));
+  },
+  BIG
+);
+
+json.t(
+  "invalid scalars, policies and retry blocks are rejected",
+  async t => {
+    const paths = issuePaths({
+      id: "",
+      version: "",
+      defaultNodeTimeoutMs: 0,
+      errorPolicy: "NOPE",
+      checkpointEveryNode: "yes",
+      completionPolicy: "SOMETIMES",
+      entryNodes: "a",
+      terminalNodes: ["a"],
+      nodes: {
+        a: {
+          run: 42,
+          timeoutMs: -5,
+          errorPolicy: "MAYBE",
+          retry: { maxAttempts: 0, delayMs: -1, extra: true }
+        }
+      }
+    });
+
+    for (const expected of [
+      "id",
+      "version",
+      "defaultNodeTimeoutMs",
+      "errorPolicy",
+      "checkpointEveryNode",
+      "completionPolicy",
+      "entryNodes",
+      "nodes.a.run",
+      "nodes.a.timeoutMs",
+      "nodes.a.errorPolicy",
+      "nodes.a.retry.maxAttempts",
+      "nodes.a.retry.delayMs",
+      "nodes.a.retry.extra"
+    ]) {
+      ok(paths.includes(expected), `${expected} missing from ${paths.join(",")}`);
+    }
+
+    /* a run name with illegal characters is a shape error too */
+    const namePaths = issuePaths({
+      id: "g",
+      version: "1",
+      entryNodes: ["a"],
+      terminalNodes: ["a"],
+      nodes: { a: { run: "has space" } }
+    });
+
+    ok(namePaths.includes("nodes.a.run"), namePaths.join(","));
+  },
+  BIG
+);
+
+json.t(
+  "EVERY issue is collected — one throw carries them all",
+  async t => {
+    const issues = issuesOf({
+      id: "",
+      version: "1",
+      entryNodes: ["ghost"],
+      terminalNodes: ["a"],
+      extra: 1,
+      nodes: {
+        a: { run: "fn", next: [{ nextNode: "nowhere" }, 7] },
+        b: { run: 12 }
+      }
+    });
+
+    ok(issues.length >= 6, `expected several issues, got ${issues.length}`);
+    eq(
+      new Set(issues.map(issue => issue.path)).size,
+      issues.length,
+      "paths are distinct"
+    );
+    ok(
+      issues.every(issue => issue.message.length > 0),
+      "every issue has a message"
+    );
+
+    const caught = catchJSONError({
+      id: "",
+      version: "",
+      entryNodes: [],
+      terminalNodes: [],
+      nodes: {}
+    });
+
+    ok(/problem\(s\)/.test(caught.message), caught.message);
+    ok(caught.issues.length >= 5, `issues=${caught.issues.length}`);
+
+    t.log(`finding: one document reported ${caught.issues.length} problems in a single throw — no fix-one-rerun loop`);
+  },
+  BIG
+);
+
+/* ------------------------------ 5. surface ------------------------------ */
+
+json.t(
+  "isGraphJSON() is a cheap shape probe, not a validator",
+  async t => {
+    eq(isGraphJSON(JSON.stringify(DOCUMENT)), true, "text");
+    eq(isGraphJSON(DOCUMENT), true, "object");
+    eq(isGraphJSON({ id: "g" }), false, "no nodes");
+    eq(isGraphJSON("{ not json"), false, "broken text");
+    eq(isGraphJSON(null), false, "null");
+    eq(isGraphJSON([1]), false, "array");
+    eq(isGraphJSON(parseGraphJSON(DOCUMENT)), true, "parser output");
+  },
+  BIG
+);
+
+json.t(
+  "an in-memory object may pass real functions through (escape hatch)",
+  async t => {
+    const parsed = parseGraphJSON({
+      id: "in-memory",
+      version: "1.0.0",
+      entryNodes: ["a"],
+      terminalNodes: ["b"],
+      nodes: {
+        a: { run: () => "inline through the loader", next: ["b"] },
+        b: { run: () => "B" }
+      }
+    });
+
+    const engine = new GraphExecutionEngine(parsed);
+
+    const report = await engine.run();
+
+    eq(report.status, "COMPLETED", "status");
+    eq(report.outputs.a, "inline through the loader", "output");
+    eq(report.registry, undefined, "no names, no registry");
+    eq(report.results[0].fn, undefined, "inline activation has no fn");
+  },
+  BIG
+);
+
+json.t(
+  "a parsed document with dangling ids is still caught by the engine if it is hand-edited",
+  async t => {
+    const definition = parseGraphJSON(DOCUMENT);
+    const tampered = {
+      ...definition,
+      nodes: {
+        ...definition.nodes,
+        classify: { ...definition.nodes.classify, next: ["ghost"] }
+      }
+    };
+
+    try {
+      new GraphExecutionEngine(tampered as typeof definition, {
+        functions: FUNCTIONS
+      });
+      throw new Error("expected the engine to reject the tampered graph");
+    } catch (error) {
+      if (!(error instanceof GraphValidationError)) throw error;
+      ok(
+        error.message.includes('unknown next Node "ghost"'),
+        error.message
+      );
+    }
+
+    t.log("finding: the loader and the engine validate different layers (paths vs. final shape) — both stay in force");
+  },
+  BIG
+);
+
+json.t(
+  "the loader example document is valid (regression: the shipped .json file)",
+  async t => {
+    /* mirrors examples/order-flow.graph.json */
+    const shipped = {
+      id: "order-flow",
+      version: "1.0.0",
+      entryNodes: ["classify"],
+      terminalNodes: ["ship", "manual", "reject"],
+      completionPolicy: "FIRST_TERMINAL",
+      nodes: {
+        classify: {
+          run: "classifyOrder",
+          next: [
+            { test: "isPriority", nextNode: "charge" },
+            { result: "manual", nextNode: "manual" },
+            { nextNode: "reject" }
+          ]
+        },
+        charge: {
+          run: "chargeCard",
+          next: ["ship"],
+          onThrow: "manual",
+          errorPolicy: "RETRY",
+          retry: { maxAttempts: 2, delayMs: 5 }
+        },
+        ship: { run: "shipOrder" },
+        manual: { run: "manualReview" },
+        reject: { run: "rejectOrder" }
+      }
+    };
+
+    const engine = createEngineFromJSON(shipped, {
+      functions: FUNCTIONS,
+      lint: "error"
+    });
+
+    const report = await engine.run();
+
+    eq(report.status, "COMPLETED", "status");
+    deepEq(report.lintIssues, [], "lint-clean");
+
+    /* and the same document, missing one name, is still lint-clean but fails
+     * exactly once at the missing node */
+    const partial = createEngineFromJSON(shipped, {
+      functions: { ...FUNCTIONS, chargeCard: undefined },
+      lint: "error"
+    });
+
+    const partialReport = await partial.run();
+
+    eq(partialReport.errors.length, 1, "one defect");
+    eq(partialReport.errors[0].code, "UNKNOWN_FUNCTION", "code");
+    eq(partialReport.status, "FAILED", "status");
+  },
+  BIG
+);