@nwire/studio 0.12.0 → 0.13.0

package/src/lib/__tests__/topology-view.test.ts

@@ -0,0 +1,154 @@
+import { describe, it, expect } from "vitest";
+import { manifestView, type Manifest } from "../manifest";
+import type { TelemetryRecord } from "../telemetry";
+import {
+  hookRegistry,
+  registeringPlugin,
+  pluginRegistry,
+  pluginInternals,
+  liveFireTally,
+} from "../topology-view";
+
+/** Build a tolerant view over a minimal manifest with a given topology + model. */
+function viewOf(topology?: object, model?: object) {
+  const manifest = {
+    version: 3,
+    actions: [],
+    events: [],
+    model: model ?? { nodes: [{ id: "_seed", kind: "_seed", name: "_seed" }], edges: [] },
+    ...(topology ? { topology } : {}),
+  } as unknown as Manifest;
+  return manifestView(manifest);
+}
+
+describe("topology-view: hookRegistry", () => {
+  it("shapes topology.hooks into name-sorted rows with defaulted counts", () => {
+    const view = viewOf({
+      hooks: [
+        { name: "zeta", chain: 3, listeners: 2 },
+        { name: "alpha" }, // missing counts default to 0
+      ],
+      plugins: [],
+    });
+    const rows = hookRegistry(view);
+    expect(rows.map((r) => r.name)).toEqual(["alpha", "zeta"]);
+    expect(rows[0]).toMatchObject({ id: "hook:alpha", chain: 0, listeners: 0 });
+    expect(rows[1]).toMatchObject({ chain: 3, listeners: 2 });
+  });
+
+  it("uses the topology hook id when present", () => {
+    const view = viewOf({ hooks: [{ name: "h", id: "custom-id" }], plugins: [] });
+    expect(hookRegistry(view)[0]!.id).toBe("custom-id");
+  });
+
+  it("carries the hook's source location through to the row (the SourcePill)", () => {
+    const source = { file: "/app/orders.ts", line: 12, column: 4 };
+    const view = viewOf({ hooks: [{ name: "h", source }], plugins: [] });
+    expect(hookRegistry(view)[0]!.source).toEqual(source);
+  });
+
+  it("returns [] for a null view or a topology-less manifest", () => {
+    expect(hookRegistry(null)).toEqual([]);
+    expect(hookRegistry(viewOf(undefined))).toEqual([]);
+  });
+});
+
+describe("topology-view: registeringPlugin", () => {
+  it("extracts the plugin name from boot/shutdown lifecycle hooks", () => {
+    expect(registeringPlugin("plugin.boot:auth")).toBe("auth");
+    expect(registeringPlugin("plugin.shutdown:storage")).toBe("storage");
+  });
+  it("returns null for non-lifecycle hooks and empty input", () => {
+    expect(registeringPlugin("action.before:x")).toBeNull();
+    expect(registeringPlugin("")).toBeNull();
+    expect(registeringPlugin(undefined)).toBeNull();
+  });
+});
+
+describe("topology-view: pluginRegistry", () => {
+  it("shapes topology.plugins into name-sorted rows", () => {
+    const view = viewOf({ hooks: [], plugins: [{ name: "storage" }, { name: "auth" }] });
+    const rows = pluginRegistry(view);
+    expect(rows.map((r) => r.name)).toEqual(["auth", "storage"]);
+    expect(rows[0]!.id).toBe("plugin:auth");
+  });
+  it("returns [] without a topology", () => {
+    expect(pluginRegistry(viewOf(undefined))).toEqual([]);
+  });
+});
+
+describe("topology-view: pluginInternals", () => {
+  it("collects boot/shutdown lifecycle hooks (boot first)", () => {
+    const view = viewOf({
+      plugins: [{ name: "auth" }],
+      hooks: [
+        { name: "plugin.shutdown:auth", chain: 1, listeners: 0 },
+        { name: "plugin.boot:auth", chain: 2, listeners: 1 },
+        { name: "plugin.boot:other" }, // a different plugin — excluded
+      ],
+    });
+    const internals = pluginInternals(view, "auth")!;
+    expect(internals.lifecycleHooks.map((h) => h.phase)).toEqual(["boot", "shutdown"]);
+    expect(internals.lifecycleHooks[0]).toMatchObject({
+      name: "plugin.boot:auth",
+      chain: 2,
+      listeners: 1,
+    });
+  });
+
+  it("reads contributes/mounts edges and a same-named capability's ctx-by-kind", () => {
+    const model = {
+      nodes: [
+        { id: "plugin:auth", kind: "plugin", name: "auth" },
+        { id: "binding:tokenStore", kind: "binding", name: "tokenStore" },
+        { id: "route:GET /me", kind: "route", name: "GET /me" },
+        {
+          id: "capability:auth",
+          kind: "capability",
+          name: "auth",
+          data: { kinds: ["action"], ctxKeys: ["currentUser", "can"] },
+        },
+      ],
+      edges: [
+        { from: "plugin:auth", to: "binding:tokenStore", type: "contributes" },
+        { from: "plugin:auth", to: "route:GET /me", type: "mounts" },
+      ],
+    };
+    const view = viewOf({ plugins: [{ name: "auth" }], hooks: [] }, model);
+    const internals = pluginInternals(view, "auth")!;
+    expect(internals.contributes).toEqual(["GET /me", "tokenStore"]);
+    expect(internals.ctxByKind).toEqual({ action: ["currentUser", "can"] });
+  });
+
+  it("returns null for a null view or no name", () => {
+    expect(pluginInternals(null, "auth")).toBeNull();
+    expect(pluginInternals(viewOf({ plugins: [], hooks: [] }), null)).toBeNull();
+  });
+});
+
+describe("topology-view: liveFireTally", () => {
+  const step = (hookName: string, phase: string, ts: string): TelemetryRecord =>
+    ({ kind: "hook.step", hookName, phase, ts }) as unknown as TelemetryRecord;
+
+  it("counts one fire per start phase and tracks the last timestamp", () => {
+    const recs = [
+      step("h", "start", "2026-01-01T00:00:00Z"),
+      step("h", "end", "2026-01-01T00:00:01Z"),
+      step("h", "start", "2026-01-01T00:00:02Z"),
+    ];
+    const tally = liveFireTally(recs);
+    expect(tally.get("h")).toEqual({ fires: 2, lastTs: "2026-01-01T00:00:02Z" });
+  });
+
+  it("ignores non-hook.step records and records without a hook name", () => {
+    const recs = [
+      { kind: "action.completed", ts: "t" } as unknown as TelemetryRecord,
+      { kind: "hook.step", phase: "start", ts: "t" } as unknown as TelemetryRecord,
+    ];
+    expect(liveFireTally(recs).size).toBe(0);
+  });
+
+  it("returns an empty map for no records (graceful idle)", () => {
+    expect(liveFireTally([]).size).toBe(0);
+  });
+});

package/src/lib/__tests__/waterfall.test.ts

@@ -0,0 +1,165 @@
+import { describe, it, expect } from "vitest";
+import { buildWaterfall, criticalPath, recordLabel } from "../waterfall";
+import type { TelemetryRecord, TraceNode } from "../telemetry";
+
+function rec(over: Partial<TelemetryRecord> & { kind: string }): TelemetryRecord {
+  return over;
+}
+function node(record: TelemetryRecord, children: TraceNode[] = []): TraceNode {
+  return { record, children };
+}
+
+const t = (ms: number) => new Date(Date.UTC(2026, 0, 1, 0, 0, 0, ms)).toISOString();
+
+describe("recordLabel", () => {
+  it("prefers a name/handler field over the kind", () => {
+    expect(recordLabel(rec({ kind: "action.completed", name: "orders.place" }))).toBe(
+      "orders.place",
+    );
+    expect(recordLabel(rec({ kind: "event.published", event: "orders.placed" }))).toBe(
+      "orders.placed",
+    );
+  });
+  it("falls back to the kind when no name is carried", () => {
+    expect(recordLabel(rec({ kind: "timer.fired" }))).toBe("timer.fired");
+  });
+});
+
+describe("buildWaterfall", () => {
+  it("flattens the forest in pre-order with depth", () => {
+    const forest = [
+      node(
+        rec({
+          kind: "action.dispatched",
+          name: "a",
+          envelope: { messageId: "m1", causationId: "m1", correlationId: "c" },
+        }),
+        [
+          node(
+            rec({
+              kind: "event.published",
+              name: "b",
+              envelope: { messageId: "m2", causationId: "m1", correlationId: "c" },
+            }),
+            [
+              node(
+                rec({
+                  kind: "listener.fired",
+                  name: "c",
+                  envelope: { messageId: "m3", causationId: "m2", correlationId: "c" },
+                }),
+              ),
+            ],
+          ),
+        ],
+      ),
+    ];
+    const { rows } = buildWaterfall(forest);
+    expect(rows.map((r) => r.label)).toEqual(["a", "b", "c"]);
+    expect(rows.map((r) => r.depth)).toEqual([0, 1, 2]);
+  });
+
+  it("positions bars against the trace span when records carry ts", () => {
+    const forest = [
+      node(
+        rec({
+          kind: "action.dispatched",
+          ts: t(0),
+          durationMs: 100,
+          envelope: { messageId: "m1", causationId: "m1", correlationId: "c" },
+        }),
+        [
+          node(
+            rec({
+              kind: "query.executed",
+              ts: t(50),
+              durationMs: 50,
+              envelope: { messageId: "m2", causationId: "m1", correlationId: "c" },
+            }),
+          ),
+        ],
+      ),
+    ];
+    const { rows, spanMs } = buildWaterfall(forest);
+    expect(spanMs).toBe(100);
+    expect(rows[0]!.offsetPct).toBe(0);
+    expect(rows[0]!.widthPct).toBe(100);
+    expect(rows[1]!.offsetPct).toBe(50);
+    expect(rows[1]!.widthPct).toBe(50);
+  });
+
+  it("clamps a zero-duration span to a visible minimum width", () => {
+    const forest = [
+      node(
+        rec({
+          kind: "event.emitted",
+          ts: t(0),
+          durationMs: 0,
+          envelope: { messageId: "m1", causationId: "m1", correlationId: "c" },
+        }),
+      ),
+    ];
+    const { rows } = buildWaterfall(forest);
+    expect(rows[0]!.widthPct).toBeGreaterThan(0);
+  });
+
+  it("falls back to full-width bars when no record carries a ts", () => {
+    const forest = [
+      node(
+        rec({
+          kind: "action.completed",
+          envelope: { messageId: "m1", causationId: "m1", correlationId: "c" },
+        }),
+      ),
+    ];
+    const { rows } = buildWaterfall(forest);
+    expect(rows[0]!.offsetPct).toBe(0);
+    expect(rows[0]!.widthPct).toBe(100);
+  });
+
+  it("marks failures", () => {
+    const forest = [
+      node(
+        rec({
+          kind: "action.failed",
+          error: { name: "E", message: "boom" },
+          envelope: { messageId: "m1", causationId: "m1", correlationId: "c" },
+        }),
+      ),
+    ];
+    const { rows } = buildWaterfall(forest);
+    expect(rows[0]!.failed).toBe(true);
+  });
+});
+
+describe("criticalPath", () => {
+  it("selects the longest-duration root→leaf chain", () => {
+    const slow = rec({
+      kind: "query.executed",
+      name: "slow",
+      durationMs: 90,
+      envelope: { messageId: "m2", causationId: "m1", correlationId: "c" },
+    });
+    const fast = rec({
+      kind: "query.executed",
+      name: "fast",
+      durationMs: 5,
+      envelope: { messageId: "m3", causationId: "m1", correlationId: "c" },
+    });
+    const root = rec({
+      kind: "action.dispatched",
+      name: "root",
+      durationMs: 10,
+      envelope: { messageId: "m1", causationId: "m1", correlationId: "c" },
+    });
+    const forest = [node(root, [node(fast), node(slow)])];
+
+    const crit = criticalPath(forest);
+    const { rows } = buildWaterfall(forest);
+    const byLabel = Object.fromEntries(rows.map((r) => [r.label, r.critical]));
+    expect(byLabel.root).toBe(true);
+    expect(byLabel.slow).toBe(true);
+    expect(byLabel.fast).toBe(false);
+    expect(crit.size).toBe(2);
+  });
+});

package/src/lib/bc-graph.ts

@@ -0,0 +1,298 @@
+/**
+ * Build the BC (bounded-context) graph the Map renders — one card per app with
+ * its member primitives, plus the inter-BC flow edges.
+ *
+ * Resilient by design: membership comes from the manifest's per-kind arrays
+ * (always present); edges come from the deep `model.edges` when available, else
+ * from the flat `graph.events`. So the Map works against both a full deep
+ * manifest and an older/partial one — never throws on missing fields.
+ */
+import type { Manifest } from "./manifest";
+
+export interface BcRow {
+  /** Graph node id (`${kind}:${name}`). */
+  readonly id: string;
+  readonly kind: string;
+  readonly name: string;
+  readonly public?: boolean;
+}
+export interface BcNode {
+  readonly name: string;
+  readonly rows: BcRow[];
+}
+export interface BcEdge {
+  readonly from: string;
+  readonly to: string;
+  readonly label?: string;
+}
+export interface BcGraph {
+  readonly bcs: BcNode[];
+  readonly edges: BcEdge[];
+}
+
+/** A positioned BC node — what the canvas lays out. */
+export interface BcLayoutNode extends BcNode {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+/** A business-rule invariant surfaced from a `validate()` predicate. */
+export interface NodeInvariant {
+  readonly rule: string;
+  readonly message?: string;
+}
+
+/** A config module surfaced on an app: its file path and top-level field names. */
+export interface NodeConfigModule {
+  readonly file: string;
+  readonly keys: readonly string[];
+}
+
+/** The full detail for one selected primitive — what NodeCard renders. */
+export interface BcNodeDetail {
+  readonly id: string;
+  readonly kind: string;
+  readonly name: string;
+  readonly app?: string;
+  readonly description?: string;
+  readonly public?: boolean;
+  readonly source?: { file: string; line?: number; column?: number };
+  /** Input/payload schema when the kind carries one (actions, queries…). */
+  readonly schema?: unknown;
+  readonly emits?: string[];
+  /** Business rules surfaced from `validate()` predicates (actions, actors). */
+  readonly invariants?: NodeInvariant[];
+  /** Environment variable names this app reads (app nodes only). */
+  readonly env?: readonly string[];
+  /** Config modules this app exposes (app nodes only). */
+  readonly config?: readonly NodeConfigModule[];
+  /** Remaining kind-specific fields (states, schedule, subscribesTo, …). */
+  readonly extra: Record<string, unknown>;
+}
+
+/** Normalize a raw `config` value to `NodeConfigModule[]` (or undefined). */
+export function toConfigModules(raw: unknown): NodeConfigModule[] | undefined {
+  if (!Array.isArray(raw)) return undefined;
+  const out: NodeConfigModule[] = [];
+  for (const r of raw) {
+    if (r && typeof r === "object" && typeof (r as { file?: unknown }).file === "string") {
+      const { file, keys } = r as { file: string; keys?: unknown };
+      out.push({ file, keys: Array.isArray(keys) ? (keys as string[]) : [] });
+    }
+  }
+  return out.length ? out : undefined;
+}
+
+/** Normalize a raw `env` value to a string array (or undefined). */
+export function toEnvVars(raw: unknown): string[] | undefined {
+  if (!Array.isArray(raw)) return undefined;
+  const out = raw.filter((x): x is string => typeof x === "string");
+  return out.length ? out : undefined;
+}
+
+/** Normalize a raw `invariants` value to `NodeInvariant[]` (or undefined). */
+export function toInvariants(raw: unknown): NodeInvariant[] | undefined {
+  if (!Array.isArray(raw)) return undefined;
+  const out: NodeInvariant[] = [];
+  for (const r of raw) {
+    if (r && typeof r === "object" && typeof (r as { rule?: unknown }).rule === "string") {
+      const { rule, message } = r as { rule: string; message?: unknown };
+      out.push(typeof message === "string" ? { rule, message } : { rule });
+    }
+  }
+  return out.length ? out : undefined;
+}
+
+/** Per-kind arrays on the manifest → the node kind they map to. */
+const MEMBER_KINDS: ReadonlyArray<readonly [string, string]> = [
+  ["actions", "action"],
+  ["queries", "query"],
+  ["events", "event"],
+  ["actors", "actor"],
+  ["workflows", "workflow"],
+  ["projections", "projection"],
+];
+
+type Entry = { name?: unknown; app?: unknown; public?: unknown };
+type RawGraphEdge = { from?: unknown; to?: unknown; via?: unknown; type?: unknown };
+
+function arr(m: Record<string, unknown>, key: string): Entry[] {
+  const v = m[key];
+  return Array.isArray(v) ? (v as Entry[]) : [];
+}
+
+/** `"action:orders.place"` → `"orders.place"`. */
+function nameOfId(id: string): string {
+  const i = id.indexOf(":");
+  return i === -1 ? id : id.slice(i + 1);
+}
+
+export function buildBcGraph(manifest: Manifest | null | undefined): BcGraph {
+  if (!manifest) return { bcs: [], edges: [] };
+  const m = manifest as unknown as Record<string, unknown>;
+
+  const appNames = new Set<string>();
+  for (const a of arr(m, "apps")) if (typeof a.name === "string") appNames.add(a.name);
+
+  const nameToApp = new Map<string, string>();
+  const rowsByApp = new Map<string, BcRow[]>();
+  for (const [key, kind] of MEMBER_KINDS) {
+    for (const e of arr(m, key)) {
+      if (typeof e.name !== "string") continue;
+      const app = typeof e.app === "string" && e.app ? e.app : "(unscoped)";
+      appNames.add(app);
+      nameToApp.set(e.name, app);
+      const rows = rowsByApp.get(app) ?? [];
+      rows.push({ id: `${kind}:${e.name}`, kind, name: e.name, public: e.public === true });
+      rowsByApp.set(app, rows);
+    }
+  }
+
+  const bcs: BcNode[] = [...appNames]
+    .sort()
+    .map((name) => ({ name, rows: rowsByApp.get(name) ?? [] }));
+
+  const edges = new Map<string, BcEdge>();
+  const add = (fromApp?: string, toApp?: string, label?: string) => {
+    if (fromApp && toApp && fromApp !== toApp)
+      edges.set(`${fromApp}->${toApp}`, { from: fromApp, to: toApp, label });
+  };
+
+  // Prefer the deep model edges; fall back to the flat event graph.
+  const model = m.model as { edges?: RawGraphEdge[] } | undefined;
+  if (model && Array.isArray(model.edges) && model.edges.length) {
+    for (const e of model.edges) {
+      if (typeof e.from !== "string" || typeof e.to !== "string") continue;
+      add(
+        nameToApp.get(nameOfId(e.from)),
+        nameToApp.get(nameOfId(e.to)),
+        typeof e.type === "string" ? e.type : undefined,
+      );
+    }
+  } else {
+    const graph = m.graph as { events?: RawGraphEdge[] } | undefined;
+    for (const e of graph?.events ?? []) {
+      if (typeof e.from !== "string" || typeof e.to !== "string") continue;
+      add(
+        nameToApp.get(e.from),
+        nameToApp.get(e.to),
+        typeof e.via === "string" ? e.via : undefined,
+      );
+    }
+  }
+
+  return { bcs, edges: [...edges.values()] };
+}
+
+const KIND_TO_KEY: Record<string, string> = Object.fromEntries(
+  MEMBER_KINDS.map(([key, kind]) => [kind, key]),
+);
+
+/** Fields we surface on their own; everything else lands in `extra`. */
+const KNOWN_FIELDS = new Set([
+  "name",
+  "app",
+  "kind",
+  "description",
+  "public",
+  "source",
+  "inputSchema",
+  "schema",
+  "payloadSchema",
+  "emits",
+  "invariants",
+]);
+
+/**
+ * Resolve a graph-node id (`"action:orders.place"`) to its full detail by
+ * looking the entry up in the manifest's flat per-kind array. Returns null
+ * when the kind/name isn't found — callers render an empty detail panel.
+ */
+export function nodeDetail(
+  manifest: Manifest | null | undefined,
+  id: string | null | undefined,
+): BcNodeDetail | null {
+  if (!manifest || !id) return null;
+  const sep = id.indexOf(":");
+  if (sep === -1) return null;
+  const kind = id.slice(0, sep);
+  const name = id.slice(sep + 1);
+  const key = KIND_TO_KEY[kind];
+  if (!key) return null;
+
+  const m = manifest as unknown as Record<string, unknown>;
+  const entry = arr(m, key).find((e) => e.name === name) as Record<string, unknown> | undefined;
+  if (!entry) return null;
+
+  const extra: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(entry)) {
+    if (!KNOWN_FIELDS.has(k) && v !== undefined) extra[k] = v;
+  }
+
+  const emits = Array.isArray(entry.emits) ? (entry.emits as string[]) : undefined;
+  const schema = entry.inputSchema ?? entry.schema ?? entry.payloadSchema;
+
+  return {
+    id,
+    kind,
+    name,
+    app: typeof entry.app === "string" ? entry.app : undefined,
+    description: typeof entry.description === "string" ? entry.description : undefined,
+    public: entry.public === true,
+    source: entry.source as BcNodeDetail["source"],
+    schema,
+    emits,
+    invariants: toInvariants(entry.invariants),
+    extra,
+  };
+}
+
+export interface LayoutOptions {
+  readonly columns?: number;
+  readonly width?: number;
+  readonly gapX?: number;
+  readonly gapY?: number;
+  readonly rowHeight?: number;
+  readonly originX?: number;
+  readonly originY?: number;
+}
+
+/**
+ * Pure grid layout for BC cards — deterministic positions so the canvas is
+ * stable across renders and the layout is unit-testable without a DOM. Card
+ * height scales with member count so tall BCs don't overlap their neighbours.
+ */
+export function layoutBcGraph(graph: BcGraph, opts: LayoutOptions = {}): BcLayoutNode[] {
+  const columns = Math.max(1, opts.columns ?? 3);
+  const width = opts.width ?? 260;
+  const gapX = opts.gapX ?? 48;
+  const gapY = opts.gapY ?? 48;
+  const rowHeight = opts.rowHeight ?? 20;
+  const originX = opts.originX ?? 0;
+  const originY = opts.originY ?? 0;
+  const headerH = 64;
+
+  // Row height is driven by the tallest card in each grid row so cards in a
+  // row share a baseline and the next row clears the tallest one.
+  const heightOf = (n: BcNode) => headerH + Math.max(1, n.rows.length) * rowHeight + 16;
+
+  const out: BcLayoutNode[] = [];
+  let rowTop = originY;
+  for (let i = 0; i < graph.bcs.length; i += columns) {
+    const rowNodes = graph.bcs.slice(i, i + columns);
+    const rowMax = Math.max(...rowNodes.map(heightOf));
+    rowNodes.forEach((n, col) => {
+      out.push({
+        ...n,
+        x: originX + col * (width + gapX),
+        y: rowTop,
+        width,
+        height: heightOf(n),
+      });
+    });
+    rowTop += rowMax + gapY;
+  }
+  return out;
+}