@nwire/studio 0.12.0 → 0.13.0

package/src/lib/__tests__/bc-graph.test.ts

@@ -0,0 +1,218 @@
+import { describe, it, expect } from "vitest";
+import { buildBcGraph, nodeDetail, toInvariants, layoutBcGraph, type BcGraph } from "../bc-graph";
+import type { Manifest } from "../manifest";
+
+/** A flat (older) manifest — per-kind arrays + `graph.events`, no `model`. */
+const flat = {
+  apps: [{ name: "orders" }, { name: "billing" }],
+  actions: [
+    { name: "orders.place", app: "orders", public: true },
+    { name: "billing.charge", app: "billing" },
+  ],
+  events: [
+    { name: "orders.placed", app: "orders", public: true },
+    { name: "billing.charged", app: "billing" },
+  ],
+  queries: [{ name: "orders.list", app: "orders" }],
+  actors: [],
+  workflows: [{ name: "orders.fulfil", app: "orders" }],
+  projections: [{ name: "orders.dashboard", app: "orders" }],
+  graph: {
+    events: [
+      // orders.placed (orders) → billing.charge (billing): cross-BC.
+      { from: "orders.placed", to: "billing.charge", via: "delivers" },
+      // intra-BC — must not produce an edge.
+      { from: "orders.place", to: "orders.placed", via: "emits" },
+    ],
+  },
+} as unknown as Manifest;
+
+/** A deep manifest — carries `model.edges` over `${kind}:${name}` ids. */
+const deep = {
+  apps: [{ name: "orders" }, { name: "billing" }],
+  actions: [
+    { name: "orders.place", app: "orders" },
+    { name: "billing.charge", app: "billing" },
+  ],
+  events: [{ name: "orders.placed", app: "orders" }],
+  queries: [],
+  actors: [],
+  workflows: [],
+  projections: [],
+  model: {
+    nodes: [],
+    edges: [{ from: "event:orders.placed", to: "action:billing.charge", type: "delivers" }],
+  },
+  // a flat graph that DISAGREES — proves `model.edges` wins when present.
+  graph: { events: [{ from: "orders.placed", to: "orders.place", via: "emits" }] },
+} as unknown as Manifest;
+
+describe("buildBcGraph", () => {
+  it("returns empty graph for null/undefined", () => {
+    expect(buildBcGraph(null)).toEqual({ bcs: [], edges: [] });
+    expect(buildBcGraph(undefined)).toEqual({ bcs: [], edges: [] });
+  });
+
+  it("groups members into BC cards by app, sorted", () => {
+    const g = buildBcGraph(flat);
+    expect(g.bcs.map((b) => b.name)).toEqual(["billing", "orders"]);
+    const orders = g.bcs.find((b) => b.name === "orders")!;
+    // 1 action + 1 event + 1 query + 1 workflow + 1 projection
+    expect(orders.rows).toHaveLength(5);
+    expect(orders.rows.map((r) => r.kind).sort()).toEqual([
+      "action",
+      "event",
+      "projection",
+      "query",
+      "workflow",
+    ]);
+  });
+
+  it("carries public flag and stable ids onto rows", () => {
+    const g = buildBcGraph(flat);
+    const place = g.bcs.flatMap((b) => b.rows).find((r) => r.name === "orders.place")!;
+    expect(place.id).toBe("action:orders.place");
+    expect(place.public).toBe(true);
+  });
+
+  it("derives cross-BC edges from graph.events (flat path), skipping intra-BC", () => {
+    const g = buildBcGraph(flat);
+    expect(g.edges).toEqual([{ from: "orders", to: "billing", label: "delivers" }]);
+  });
+
+  it("prefers model.edges over graph.events when a deep model is present", () => {
+    const g = buildBcGraph(deep);
+    expect(g.edges).toEqual([{ from: "orders", to: "billing", label: "delivers" }]);
+  });
+
+  it("buckets members with no app into (unscoped)", () => {
+    const g = buildBcGraph({
+      apps: [],
+      actions: [{ name: "loose.thing" }],
+    } as unknown as Manifest);
+    expect(g.bcs.map((b) => b.name)).toContain("(unscoped)");
+  });
+});
+
+describe("nodeDetail", () => {
+  const m = {
+    actions: [
+      {
+        name: "orders.place",
+        app: "orders",
+        description: "Place an order.",
+        public: true,
+        inputSchema: { type: "object" },
+        emits: ["orders.placed"],
+        retry: 3,
+        source: { file: "/app/actions.ts", line: 10, column: 2 },
+      },
+    ],
+  } as unknown as Manifest;
+
+  it("resolves a row id to full detail", () => {
+    const d = nodeDetail(m, "action:orders.place")!;
+    expect(d.name).toBe("orders.place");
+    expect(d.app).toBe("orders");
+    expect(d.description).toBe("Place an order.");
+    expect(d.public).toBe(true);
+    expect(d.schema).toEqual({ type: "object" });
+    expect(d.emits).toEqual(["orders.placed"]);
+    expect(d.source).toEqual({ file: "/app/actions.ts", line: 10, column: 2 });
+  });
+
+  it("puts unknown fields into extra, not the typed surface", () => {
+    const d = nodeDetail(m, "action:orders.place")!;
+    expect(d.extra.retry).toBe(3);
+    expect(d.extra.name).toBeUndefined();
+    expect(d.extra.inputSchema).toBeUndefined();
+  });
+
+  it("returns null for unknown kind, missing entry, bad id, or no manifest", () => {
+    expect(nodeDetail(m, "nope:orders.place")).toBeNull();
+    expect(nodeDetail(m, "action:does.not.exist")).toBeNull();
+    expect(nodeDetail(m, "noseparator")).toBeNull();
+    expect(nodeDetail(null, "action:orders.place")).toBeNull();
+    expect(nodeDetail(m, null)).toBeNull();
+  });
+
+  it("surfaces invariants as a typed field, not in extra", () => {
+    const withRules = {
+      actions: [
+        {
+          name: "mod.approve",
+          app: "mod",
+          invariants: [
+            { rule: '(i) => i.by.length > 0 || "Needs a moderator"', message: "Needs a moderator" },
+            { rule: "(i) => i.ok" },
+          ],
+        },
+      ],
+    } as unknown as Manifest;
+    const d = nodeDetail(withRules, "action:mod.approve")!;
+    expect(d.invariants).toEqual([
+      { rule: '(i) => i.by.length > 0 || "Needs a moderator"', message: "Needs a moderator" },
+      { rule: "(i) => i.ok" },
+    ]);
+    expect(d.extra.invariants).toBeUndefined();
+  });
+});
+
+describe("toInvariants", () => {
+  it("normalizes well-formed entries and drops junk", () => {
+    expect(
+      toInvariants([{ rule: "a", message: "A" }, { rule: "b" }, { rule: 123 }, "nope", null]),
+    ).toEqual([{ rule: "a", message: "A" }, { rule: "b" }]);
+  });
+
+  it("returns undefined for non-arrays and empty results", () => {
+    expect(toInvariants(undefined)).toBeUndefined();
+    expect(toInvariants("x")).toBeUndefined();
+    expect(toInvariants([])).toBeUndefined();
+    expect(toInvariants([{ message: "no rule" }])).toBeUndefined();
+  });
+});
+
+describe("layoutBcGraph", () => {
+  const graph: BcGraph = {
+    bcs: [
+      {
+        name: "a",
+        rows: [
+          { id: "action:a1", kind: "action", name: "a1" },
+          { id: "action:a2", kind: "action", name: "a2" },
+          { id: "action:a3", kind: "action", name: "a3" },
+        ],
+      },
+      { name: "b", rows: [] },
+      { name: "c", rows: [] },
+      { name: "d", rows: [] },
+    ],
+    edges: [],
+  };
+
+  it("positions cards in a grid by column count", () => {
+    const nodes = layoutBcGraph(graph, { columns: 2, width: 100, gapX: 20 });
+    expect(nodes).toHaveLength(4);
+    // row 0
+    expect(nodes[0]!.x).toBe(0);
+    expect(nodes[1]!.x).toBe(120);
+    expect(nodes[0]!.y).toBe(nodes[1]!.y);
+    // row 1 wraps below row 0
+    expect(nodes[2]!.x).toBe(0);
+    expect(nodes[2]!.y).toBeGreaterThan(nodes[0]!.y);
+  });
+
+  it("scales card height with member count", () => {
+    const nodes = layoutBcGraph(graph, { columns: 4 });
+    const tall = nodes.find((n) => n.name === "a")!;
+    const short = nodes.find((n) => n.name === "b")!;
+    expect(tall.height).toBeGreaterThan(short.height);
+  });
+
+  it("never overlaps rows — next row clears the tallest card above", () => {
+    const nodes = layoutBcGraph(graph, { columns: 2 });
+    const rowZeroBottom = Math.max(nodes[0]!.y + nodes[0]!.height, nodes[1]!.y + nodes[1]!.height);
+    expect(nodes[2]!.y).toBeGreaterThanOrEqual(rowZeroBottom);
+  });
+});

package/src/lib/__tests__/dispatch-form.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect } from "vitest";
+import type { Manifest } from "../manifest";
+import {
+  dispatchTargets,
+  filterTargets,
+  schemaFields,
+  scaffoldInput,
+  isInlineRenderable,
+  allInlineRenderable,
+} from "../dispatch-form";
+
+const objectSchema = {
+  type: "object",
+  properties: {
+    authorId: { type: "string" },
+    body: { type: "string" },
+    flagged: { type: "boolean", default: false },
+    severity: { type: "string", enum: ["low", "high"] },
+  },
+  required: ["authorId", "body"],
+};
+
+const manifest = {
+  actions: [
+    {
+      name: "moderation.submit-post",
+      app: "moderation",
+      description: "post",
+      inputSchema: objectSchema,
+    },
+    { name: "moderation.flag", app: "moderation" },
+  ],
+  queries: [{ name: "moderation.queue", app: "moderation", projection: "queue" }],
+} as unknown as Manifest;
+
+describe("dispatchTargets", () => {
+  it("reads actions then queries from the flat manifest arrays", () => {
+    const t = dispatchTargets(manifest);
+    expect(t.map((x) => x.name)).toEqual([
+      "moderation.submit-post",
+      "moderation.flag",
+      "moderation.queue",
+    ]);
+    expect(t[0].kind).toBe("action");
+    expect(t[2].kind).toBe("query");
+    expect(t[0].inputSchema).toBe(objectSchema);
+  });
+
+  it("is tolerant of a null / partial manifest", () => {
+    expect(dispatchTargets(null)).toEqual([]);
+    expect(dispatchTargets({} as Manifest)).toEqual([]);
+    expect(dispatchTargets({ actions: "nope" } as unknown as Manifest)).toEqual([]);
+  });
+
+  it("skips entries without a name", () => {
+    const m = {
+      actions: [{ app: "x" }, { name: "ok", app: "x" }],
+    } as unknown as Manifest;
+    expect(dispatchTargets(m).map((t) => t.name)).toEqual(["ok"]);
+  });
+});
+
+describe("filterTargets", () => {
+  const targets = dispatchTargets(manifest);
+  it("returns all on an empty query", () => {
+    expect(filterTargets(targets, "  ")).toHaveLength(3);
+  });
+  it("matches name, app, and description case-insensitively", () => {
+    expect(filterTargets(targets, "FLAG").map((t) => t.name)).toEqual(["moderation.flag"]);
+    expect(filterTargets(targets, "post").map((t) => t.name)).toEqual(["moderation.submit-post"]);
+    expect(filterTargets(targets, "queue").map((t) => t.name)).toEqual(["moderation.queue"]);
+  });
+});
+
+describe("schemaFields", () => {
+  it("flattens top-level properties with required/default/enum", () => {
+    const f = schemaFields(objectSchema);
+    expect(f.map((x) => x.name)).toEqual(["authorId", "body", "flagged", "severity"]);
+    expect(f.find((x) => x.name === "authorId")?.required).toBe(true);
+    expect(f.find((x) => x.name === "flagged")?.default).toBe(false);
+    expect(f.find((x) => x.name === "severity")?.enum).toEqual(["low", "high"]);
+  });
+  it("returns [] for a non-object / schemaless input", () => {
+    expect(schemaFields(undefined)).toEqual([]);
+    expect(schemaFields({ type: "string" })).toEqual([]);
+  });
+});
+
+describe("scaffoldInput", () => {
+  it("seeds type-appropriate values and honors defaults", () => {
+    expect(scaffoldInput(objectSchema)).toEqual({
+      authorId: "",
+      body: "",
+      flagged: false,
+      severity: "",
+    });
+  });
+  it("returns {} for a schemaless input", () => {
+    expect(scaffoldInput(null)).toEqual({});
+  });
+});
+
+describe("inline renderability", () => {
+  it("treats primitives as inline-renderable", () => {
+    expect(isInlineRenderable({ name: "a", type: "string", required: true })).toBe(true);
+    expect(isInlineRenderable({ name: "a", type: "object", required: false })).toBe(false);
+  });
+  it("allInlineRenderable is true only when all fields are primitive", () => {
+    expect(allInlineRenderable(schemaFields(objectSchema))).toBe(true);
+    expect(allInlineRenderable([{ name: "x", type: "object", required: false }])).toBe(false);
+    expect(allInlineRenderable([])).toBe(false);
+  });
+});

package/src/lib/__tests__/error-friendly.test.ts

@@ -0,0 +1,198 @@
+import { describe, it, expect } from "vitest";
+import {
+  explainError,
+  categorize,
+  severityOf,
+  subjectOf,
+  attemptOf,
+  retryNarrative,
+  maxSeverity,
+} from "../error-friendly";
+import type { TelemetryRecord } from "../telemetry";
+
+const rec = (over: Partial<TelemetryRecord> & { kind: string }): TelemetryRecord => over;
+
+describe("subjectOf", () => {
+  it("reads the failing unit off whichever id field is present", () => {
+    expect(subjectOf(rec({ kind: "action.failed", action: "orders.charge" }))).toEqual({
+      kind: "action",
+      name: "orders.charge",
+    });
+    expect(subjectOf(rec({ kind: "projection.failed", projection: "balances" }))).toEqual({
+      kind: "projection",
+      name: "balances",
+    });
+    expect(subjectOf(rec({ kind: "external.call.failed", call: "stripe.charge" }))).toEqual({
+      kind: "external call",
+      name: "stripe.charge",
+    });
+  });
+  it("falls back to the source event, then a generic label", () => {
+    expect(subjectOf(rec({ kind: "reaction.failed", sourceEvent: "OrderPlaced" }))).toEqual({
+      kind: "operation",
+      name: "OrderPlaced",
+    });
+    expect(subjectOf(rec({ kind: "x" })).name).toBe("an operation");
+  });
+});
+
+describe("categorize", () => {
+  it("classifies by error name / message / code first", () => {
+    expect(
+      categorize(rec({ kind: "action.failed", error: { name: "ZodError", message: "x" } })),
+    ).toBe("validation");
+    expect(
+      categorize(
+        rec({ kind: "action.failed", error: { name: "E", message: "field is required" } }),
+      ),
+    ).toBe("validation");
+    expect(
+      categorize(
+        rec({ kind: "action.failed", error: { name: "E", message: "card declined", code: 402 } }),
+      ),
+    ).toBe("declined");
+    expect(
+      categorize(
+        rec({ kind: "action.failed", error: { name: "Forbidden", message: "x", code: 403 } }),
+      ),
+    ).toBe("unauthorized");
+    expect(
+      categorize(
+        rec({ kind: "action.failed", error: { name: "E", message: "user not found", code: 404 } }),
+      ),
+    ).toBe("not-found");
+    expect(
+      categorize(
+        rec({ kind: "action.failed", error: { name: "E", message: "already exists", code: 409 } }),
+      ),
+    ).toBe("conflict");
+    expect(
+      categorize(
+        rec({ kind: "action.failed", error: { name: "TimeoutError", message: "timed out" } }),
+      ),
+    ).toBe("timeout");
+  });
+  it("falls back to the record kind for the forge terminal shapes", () => {
+    expect(categorize(rec({ kind: "dlq.recorded", error: { name: "E", message: "boom" } }))).toBe(
+      "dead-letter",
+    );
+    expect(
+      categorize(rec({ kind: "reaction.exhausted", error: { name: "E", message: "boom" } })),
+    ).toBe("exhausted");
+    expect(
+      categorize(rec({ kind: "external.call.failed", error: { name: "E", message: "boom" } })),
+    ).toBe("external");
+    expect(
+      categorize(rec({ kind: "projection.failed", error: { name: "E", message: "boom" } })),
+    ).toBe("downstream");
+  });
+  it("is 'unknown' when nothing matches", () => {
+    expect(
+      categorize(rec({ kind: "action.failed", error: { name: "WeirdError", message: "?" } })),
+    ).toBe("unknown");
+  });
+});
+
+describe("attemptOf / retryNarrative", () => {
+  it("normalises the retrying shape", () => {
+    const r = rec({
+      kind: "action.failed",
+      attempt: 2,
+      maxAttempts: 3,
+      willRetry: true,
+      error: { name: "E", message: "x" },
+    });
+    expect(attemptOf(r)).toMatchObject({
+      attempt: 2,
+      maxAttempts: 3,
+      willRetry: true,
+      terminal: false,
+    });
+    expect(retryNarrative(r)).toBe("attempt 2 of 3, retrying");
+  });
+  it("marks terminal shapes and reports total attempts", () => {
+    const r = rec({ kind: "dlq.recorded", attempts: 3, error: { name: "E", message: "x" } });
+    expect(attemptOf(r)).toMatchObject({ attempts: 3, willRetry: false, terminal: true });
+    expect(retryNarrative(r)).toBe("3 attempts — gave up");
+  });
+  it("returns null when there's nothing to say", () => {
+    expect(retryNarrative(rec({ kind: "action.failed", attempt: 1, maxAttempts: 1 }))).toBe(
+      "attempt 1 of 1",
+    );
+    expect(retryNarrative(rec({ kind: "projection.failed" }))).toBeNull();
+  });
+});
+
+describe("severityOf", () => {
+  it("terminal shapes are critical", () => {
+    expect(severityOf(rec({ kind: "dlq.recorded" }))).toBe("critical");
+    expect(severityOf(rec({ kind: "reaction.exhausted" }))).toBe("critical");
+  });
+  it("a failure that will retry is only a warning", () => {
+    expect(
+      severityOf(
+        rec({ kind: "action.failed", willRetry: true, error: { name: "E", message: "x" } }),
+      ),
+    ).toBe("warning");
+  });
+  it("validation / declined are warnings (expected control-flow)", () => {
+    expect(
+      severityOf(rec({ kind: "action.failed", error: { name: "ZodError", message: "x" } })),
+    ).toBe("warning");
+    expect(
+      severityOf(rec({ kind: "action.failed", error: { name: "E", message: "declined" } })),
+    ).toBe("warning");
+  });
+  it("an unrecoverable runtime failure is high", () => {
+    expect(
+      severityOf(
+        rec({
+          kind: "action.failed",
+          willRetry: false,
+          error: { name: "TypeError", message: "boom" },
+        }),
+      ),
+    ).toBe("high");
+  });
+});
+
+describe("maxSeverity", () => {
+  it("picks the louder", () => {
+    expect(maxSeverity("warning", "critical")).toBe("critical");
+    expect(maxSeverity("high", "warning")).toBe("high");
+    expect(maxSeverity("info", "info")).toBe("info");
+  });
+});
+
+describe("explainError", () => {
+  it("produces a friendly title/summary/suggestion naming the subject", () => {
+    const f = explainError(
+      rec({
+        kind: "action.failed",
+        action: "orders.charge",
+        willRetry: false,
+        error: { name: "PaymentDeclined", message: "card declined", code: 402 },
+      }),
+    );
+    expect(f.category).toBe("declined");
+    expect(f.title).toBe("Declined");
+    expect(f.summary).toContain("orders.charge");
+    expect(f.suggestion.length).toBeGreaterThan(0);
+    expect(f.severity).toBe("warning");
+    expect(f.rawMessage).toBe("card declined");
+  });
+  it("explains a dead-lettered action loudly", () => {
+    const f = explainError(
+      rec({
+        kind: "dlq.recorded",
+        action: "orders.ship",
+        attempts: 5,
+        error: { name: "TypeError", message: "boom" },
+      }),
+    );
+    expect(f.severity).toBe("critical");
+    expect(f.title).toBe("Dead-lettered");
+    expect(f.summary).toContain("orders.ship");
+    expect(f.attempt.terminal).toBe(true);
+  });
+});