@shortlink-org/portolan 0.1.0

package/src/flow/chain.ts

@@ -0,0 +1,353 @@
+// What happens after an event, as far as the flows can say.
+//
+// The event page lists who consumes an event. This module answers the next
+// question - and then what? - by following each consumer into the flow where
+// it is shown hearing the event, reading off what it publishes after that,
+// and asking the same question of those events. Nothing here is a new fact:
+// every hop is a consumer entry or a flow step the catalog already has, and
+// each node links to the step it was read from.
+//
+// The chain hangs off the RECEIVING step, wherever it sits in a flow. The
+// rail's "continues in" link only follows a flow that OPENS with the event,
+// which is right for a handoff between two flows and wrong for this: in the
+// hand-written estate no flow opens with an event, and OrderPlaced is heard at
+// step 3 of one flow and step 14 of another.
+//
+// What a consumer publishes "after" hearing an event is read in walk order
+// within the same flow, minus the branches the receiving step is not on: a
+// publish inside another arm of an alt that encloses the receipt did not
+// follow from it. A publish inside an alt the receipt is outside of is kept -
+// it is conditional, but it is one of the things that can happen next.
+//
+// An event is expanded once in the whole tree. The estate's flows fan out and
+// fold back - a cancellation is reachable from three different declines - and
+// drawing the same subtree under each arrival would make the page a wall
+// without adding a fact. The second arrival says the event is shown above.
+
+import type {
+  Catalog,
+  EdgeVia,
+  Flow,
+  FlowNode,
+  Participant,
+  Status,
+  Step,
+} from "../catalog";
+import { worstStatus } from "../lib/event-graph";
+
+/** Why a branch stops short, and how much is not shown. */
+export interface ChainCut {
+  /**
+   * `cycle`: the event is already on the path above this node.
+   * `seen`: the event is expanded elsewhere in the tree, earlier.
+   * `depth`: past the number of hops the page follows.
+   * `budget`: the tree hit its size limit.
+   */
+  reason: "depth" | "cycle" | "seen" | "budget";
+  hidden: number;
+}
+
+interface ChainBase {
+  /** Indentation level; the root event's consumers sit at 0. */
+  depth: number;
+  /** This node's own status: the consumer's, or the step's. */
+  status: Status;
+  /** Worst of this node and everything under it. */
+  worst: Status;
+  children: ChainNode[];
+  cut?: ChainCut;
+}
+
+export type ChainNode = ChainBase &
+  (
+    | {
+        kind: "consumer";
+        service: string;
+        context: string | null;
+        /** False for a consumer no service in the catalog answers to. */
+        known: boolean;
+        via?: EdgeVia;
+      }
+    | {
+        /** The step where the consumer is shown hearing the event. */
+        kind: "receipt";
+        flow: string;
+        name: string;
+        stepId: string;
+        number: number;
+      }
+    | {
+        /** An event the consumer publishes after hearing the one above. */
+        kind: "event";
+        id: string;
+        name: string;
+        publisher: string;
+        context: string | null;
+        flow: string;
+        stepId: string;
+        number: number;
+      }
+  );
+
+export interface EventChain {
+  root: string;
+  nodes: ChainNode[];
+  /** Nodes in the whole tree. */
+  count: number;
+  /** True when the node budget stopped the walk somewhere. */
+  truncated: boolean;
+}
+
+export interface ChainOptions {
+  /** Event hops below the root; a consumer, its receipt and what it publishes are one hop. */
+  maxDepth?: number;
+  maxNodes?: number;
+}
+
+const CHAIN_DEPTH = 4;
+export const CHAIN_BUDGET = 200;
+
+/** Which arm of which alt a step sits in, innermost last. */
+type Arms = readonly { alt: string; arm: number }[];
+
+interface Walked {
+  steps: Step[];
+  arms: Arms[];
+}
+
+/**
+ * The steps of a flow in walk order - the order `walkSteps` uses, so step
+ * numbers agree with the rail - each with the alt arms enclosing it.
+ */
+function walk(nodes: FlowNode[]): Walked {
+  const steps: Step[] = [];
+  const arms: Arms[] = [];
+  const visit = (list: FlowNode[], enclosing: Arms): void => {
+    for (const node of list) {
+      switch (node.type) {
+        case "step":
+          steps.push(node);
+          arms.push(enclosing);
+          break;
+        case "parallel":
+          for (const branch of node.branches) visit(branch, enclosing);
+          break;
+        case "alt":
+          node.branches.forEach((branch, arm) =>
+            visit(branch.steps, [...enclosing, { alt: node.id, arm }]),
+          );
+          break;
+        case "loop":
+          visit(node.steps, enclosing);
+          break;
+      }
+    }
+  };
+  visit(nodes, []);
+  return { steps, arms };
+}
+
+/** True unless `later` sits in another arm of an alt that encloses `earlier`. */
+function sameSide(earlier: Arms, later: Arms): boolean {
+  return earlier.every((frame) => {
+    const other = later.find((f) => f.alt === frame.alt);
+    return other === undefined || other.arm === frame.arm;
+  });
+}
+
+interface Receipt {
+  flow: Flow;
+  walked: Walked;
+  lanes: Map<string, Participant>;
+  index: number;
+}
+
+export function eventChain(
+  catalog: Catalog,
+  eventId: string,
+  opts: ChainOptions = {},
+): EventChain {
+  const maxDepth = opts.maxDepth ?? CHAIN_DEPTH;
+  const maxNodes = opts.maxNodes ?? CHAIN_BUDGET;
+
+  const serviceContext = new Map<string, string>();
+  const events = new Map<
+    string,
+    { name: string; publisher: string; consumers: ChainConsumer[] }
+  >();
+  for (const context of catalog.contexts) {
+    for (const service of context.services) {
+      serviceContext.set(service.id, context.id);
+      for (const aggregate of service.aggregates) {
+        for (const event of aggregate.events) {
+          events.set(event.id, {
+            name: event.name,
+            publisher: service.id,
+            consumers: event.consumers,
+          });
+        }
+      }
+    }
+  }
+
+  // Every step where a service is shown hearing an event, by event.
+  const receipts = new Map<string, Receipt[]>();
+  for (const flow of catalog.flows) {
+    const walked = walk(flow.steps);
+    const lanes = new Map(flow.participants.map((p) => [p.id, p]));
+    walked.steps.forEach((step, index) => {
+      if (step.kind !== "event" || !step.ref || !events.has(step.ref)) return;
+      if (step.from === step.to) return;
+      if (lanes.get(step.to)?.kind !== "service") return;
+      const list = receipts.get(step.ref) ?? [];
+      list.push({ flow, walked, lanes, index });
+      receipts.set(step.ref, list);
+    });
+  }
+
+  let count = 0;
+  let truncated = false;
+  const expanded = new Set<string>([eventId]);
+
+  /** True when there is room for one more node; marks the cut otherwise. */
+  const room = (parent: ChainBase | null, remaining: number): boolean => {
+    if (count < maxNodes) {
+      count += 1;
+      return true;
+    }
+    truncated = true;
+    if (parent && !parent.cut) parent.cut = { reason: "budget", hidden: remaining };
+    return false;
+  };
+
+  const settle = (node: ChainBase): void => {
+    node.worst = worstStatus([node.status, ...node.children.map((c) => c.worst)]);
+  };
+
+  const visit = (
+    id: string,
+    ancestors: Set<string>,
+    hop: number,
+    depth: number,
+    parent: ChainBase | null,
+  ): ChainNode[] => {
+    const event = events.get(id);
+    if (!event) return [];
+    const out: ChainNode[] = [];
+
+    event.consumers.forEach((consumer, i) => {
+      if (!room(parent, event.consumers.length - i)) return;
+      const node: ChainNode = {
+        kind: "consumer",
+        service: consumer.service,
+        context: serviceContext.get(consumer.service) ?? null,
+        known: serviceContext.has(consumer.service),
+        ...(consumer.via ? { via: consumer.via } : {}),
+        depth,
+        status: consumer.status,
+        worst: consumer.status,
+        children: [],
+      };
+      out.push(node);
+
+      const heard = (receipts.get(id) ?? []).filter(
+        (r) => r.walked.steps[r.index]?.to === consumer.service,
+      );
+      heard.forEach((receipt, j) => {
+        if (!room(node, heard.length - j)) return;
+        const step = receipt.walked.steps[receipt.index]!;
+        const rnode: ChainNode = {
+          kind: "receipt",
+          flow: receipt.flow.slug,
+          name: receipt.flow.name,
+          stepId: step.id,
+          number: receipt.index + 1,
+          depth: depth + 1,
+          status: step.status,
+          worst: step.status,
+          children: [],
+        };
+        node.children.push(rnode);
+
+        const published = publishedAfter(receipt, consumer.service, events);
+        published.forEach(({ step: pub, index }, k) => {
+          if (!room(rnode, published.length - k)) return;
+          const ref = pub.ref!;
+          const next = events.get(ref)!;
+          const enode: ChainNode = {
+            kind: "event",
+            id: ref,
+            name: next.name,
+            publisher: next.publisher,
+            context: serviceContext.get(next.publisher) ?? null,
+            flow: receipt.flow.slug,
+            stepId: pub.id,
+            number: index + 1,
+            depth: depth + 2,
+            status: pub.status,
+            worst: pub.status,
+            children: [],
+          };
+          rnode.children.push(enode);
+
+          if (ancestors.has(ref)) {
+            enode.cut = { reason: "cycle", hidden: next.consumers.length };
+          } else if (expanded.has(ref)) {
+            if (next.consumers.length > 0)
+              enode.cut = { reason: "seen", hidden: next.consumers.length };
+          } else if (hop + 1 >= maxDepth) {
+            if (next.consumers.length > 0)
+              enode.cut = { reason: "depth", hidden: next.consumers.length };
+          } else {
+            expanded.add(ref);
+            enode.children = visit(
+              ref,
+              new Set([...ancestors, ref]),
+              hop + 1,
+              depth + 3,
+              enode,
+            );
+          }
+          settle(enode);
+        });
+        settle(rnode);
+      });
+      settle(node);
+    });
+
+    return out;
+  };
+
+  const nodes = visit(eventId, new Set([eventId]), 0, 0, null);
+  return { root: eventId, nodes, count, truncated };
+}
+
+type ChainConsumer = { service: string; status: Status; via?: EdgeVia };
+
+/**
+ * The events a service publishes after a given step of a flow, in walk order,
+ * first occurrence of each, leaving out the arms of an alt the step is not
+ * on. Only the publisher's own events count: a service relaying somebody
+ * else's event is a broker, and a broker is not a "then".
+ */
+function publishedAfter(
+  receipt: Receipt,
+  service: string,
+  events: Map<string, { publisher: string }>,
+): { step: Step; index: number }[] {
+  const out: { step: Step; index: number }[] = [];
+  const seen = new Set<string>();
+  const { steps, arms } = receipt.walked;
+  const here = arms[receipt.index]!;
+  for (let i = receipt.index + 1; i < steps.length; i += 1) {
+    const step = steps[i]!;
+    if (step.kind !== "event" || !step.ref || step.from !== service) continue;
+    if (step.to === step.from) continue;
+    if (events.get(step.ref)?.publisher !== service) continue;
+    if (!sameSide(here, arms[i]!)) continue;
+    if (seen.has(step.ref)) continue;
+    seen.add(step.ref);
+    out.push({ step, index: i });
+  }
+  return out;
+}

package/src/flow/chapters.test.ts

@@ -0,0 +1,185 @@
+import { describe, expect, it } from "vitest";
+import { catalog } from "../testing/estate";
+import { walkSteps } from "../catalog";
+import type { Flow } from "../catalog";
+import { buildChapters, groupRows, railRows } from "./chapters";
+import { buildOutline, outlineSteps } from "./outline";
+import { hiddenStepIds } from "./cross-context";
+
+const NO_FILTER = { hidden: new Set<string>(), crossOnly: false };
+
+function flow(slug: string): Flow {
+  const found = catalog.flows.find((f) => f.slug === slug);
+  if (!found) throw new Error(`fixture has no flow ${slug}`);
+  return found;
+}
+
+const checkout = flow("checkout");
+
+describe("buildChapters", () => {
+  it("covers every step of the flow exactly once", () => {
+    for (const f of catalog.flows) {
+      const covered = buildChapters(f).flatMap((c) => c.stepIds);
+      expect(covered).toEqual(walkSteps(f.steps).map((s) => s.id));
+    }
+  });
+
+  it("makes one chapter per top-level frame, and one per run between them", () => {
+    const chapters = buildChapters(checkout);
+    const topLevelFrames = checkout.steps.filter((n) => n.type !== "step");
+    expect(chapters.filter((c) => c.kind !== "steps").map((c) => c.id)).toEqual(
+      topLevelFrames.map((n) => n.id),
+    );
+    // Frames and runs alternate by construction, so no two runs can be
+    // adjacent — a run that could continue is the same run.
+    const kinds = chapters.map((c) => c.kind === "steps");
+    expect(kinds.some((isRun, i) => isRun && kinds[i - 1] === true)).toBe(false);
+  });
+
+  it("does not promote a nested frame to a chapter of its own", () => {
+    // par-captured sits inside alt-capture; it must belong to that chapter
+    // rather than splitting it in two.
+    const chapters = buildChapters(checkout);
+    expect(chapters.map((c) => c.id)).not.toContain("par-captured");
+    const owner = chapters.find((c) => c.stepIds.includes("s35"));
+    expect(owner?.id).toBe("alt-capture");
+  });
+
+  it("numbers a chapter by the whole flow, frames included", () => {
+    const chapters = buildChapters(checkout);
+    const first = chapters[0];
+    const last = chapters[chapters.length - 1];
+    expect(first?.from).toBe(1);
+    expect(last?.to).toBe(walkSteps(checkout.steps).length);
+    // Ranges tile the flow: each chapter starts where the last one stopped.
+    chapters.forEach((chapter, i) => {
+      const previous = chapters[i - 1];
+      if (previous) expect(chapter.from).toBe(previous.to + 1);
+    });
+  });
+
+  it("names an alt by the question it asks and a run by its ends", () => {
+    const chapters = buildChapters(checkout);
+    const alt = chapters.find((c) => c.id === "alt-risk");
+    expect(alt?.kind).toBe("alt");
+    expect(alt?.title).toBe("score below 40");
+
+    const opening = chapters[0];
+    expect(opening?.kind).toBe("steps");
+    expect(opening?.title).toBe("PlaceOrder → GetQuote");
+  });
+
+  it("counts status per chapter and lists the contexts it touches", () => {
+    const chapter = buildChapters(checkout).find((c) => c.id === "alt-risk");
+    if (!chapter) throw new Error("fixture has no alt-risk");
+    const total =
+      chapter.status.verified +
+      chapter.status.declared +
+      chapter.status.unresolved;
+    expect(total).toBe(chapter.stepIds.length);
+    expect(chapter.contexts).toEqual(["shop"]);
+  });
+
+  it("gives a flow with no frames exactly one chapter", () => {
+    const flat = catalog.flows.find((f) =>
+      f.steps.every((n) => n.type === "step"),
+    );
+    if (!flat) throw new Error("fixture has no flat flow");
+    const chapters = buildChapters(flat);
+    expect(chapters).toHaveLength(1);
+    expect(chapters[0]?.kind).toBe("steps");
+  });
+});
+
+describe("groupRows", () => {
+  const chapters = buildChapters(checkout);
+
+  it("keeps the rail's order and loses none of its rows", () => {
+    const rows = buildOutline(checkout, NO_FILTER);
+    const groups = groupRows(rows, chapters);
+    expect(groups.flatMap((g) => g.rows)).toEqual(rows);
+  });
+
+  it("gives a frame header to the chapter its body belongs to", () => {
+    const rows = buildOutline(checkout, NO_FILTER);
+    const groups = groupRows(rows, chapters);
+    for (const { chapter, rows: owned } of groups) {
+      for (const row of owned) {
+        if (row.type === "step") expect(chapter.stepIds).toContain(row.step.id);
+      }
+    }
+    // The alt's own header sits inside the alt's chapter, not the run before it.
+    const risk = groups.find((g) => g.chapter.id === "alt-risk");
+    expect(risk?.rows[0]?.type).toBe("frame");
+  });
+
+  it("drops a chapter the filter emptied rather than drawing it blank", () => {
+    const hidden = hiddenStepIds(checkout);
+    const rows = buildOutline(checkout, { hidden, crossOnly: true });
+    const groups = groupRows(rows, chapters);
+    const shown = new Set(groups.map((g) => g.chapter.id));
+    const visible = new Set(outlineSteps(rows).map((r) => r.step.id));
+    for (const chapter of chapters) {
+      const survives = chapter.stepIds.some((id) => visible.has(id));
+      expect(shown.has(chapter.id)).toBe(survives);
+    }
+    expect(groups.every((g) => g.rows.length > 0)).toBe(true);
+  });
+
+  it("marks an alt chapter terminal when its opening branch ends the flow", () => {
+    // alt-risk's arms are: score below 40, score at or above 40 (terminal),
+    // scorer timed out. The opening arm is not the terminal one, so the header
+    // must not claim the chapter ends the flow.
+    const risk = chapters.find((c) => c.id === "alt-risk");
+    expect(risk?.terminal).toBeUndefined();
+  });
+
+  it("drops the frame row the chapter header already is", () => {
+    const rows = buildOutline(checkout, NO_FILTER);
+    const risk = groupRows(rows, chapters).find(
+      (g) => g.chapter.id === "alt-risk",
+    );
+    if (!risk) throw new Error("fixture has no alt-risk group");
+    expect(risk.rows[0]?.type).toBe("frame");
+    // The opening `alt` row said exactly what the header says; the `else` rows
+    // under it did not, and they stay.
+    const shown = railRows(risk);
+    expect(shown).toEqual(risk.rows.slice(1));
+    expect(
+      shown.filter((r) => r.type === "frame").map((r) => r.keyword),
+    ).toEqual(["else", "else"]);
+  });
+
+  it("keeps the opening frame row when the filter promoted a different branch", () => {
+    const hidden = hiddenStepIds(checkout);
+    const rows = buildOutline(checkout, { hidden, crossOnly: true });
+    for (const group of groupRows(rows, chapters)) {
+      const first = group.rows[0];
+      if (group.chapter.kind === "steps" || first?.type !== "frame") continue;
+      // Whatever survives, the condition heading the frame is on screen: either
+      // the header says it, or the row does.
+      const shown = railRows(group);
+      const headed =
+        first.title === group.chapter.title
+          ? group.chapter.title
+          : shown[0]?.type === "frame"
+            ? shown[0].title
+            : undefined;
+      expect(headed).toBe(first.title ?? group.chapter.title);
+    }
+  });
+
+  it("does not rename or renumber chapters when the filter changes", () => {
+    const hidden = hiddenStepIds(checkout);
+    const filtered = groupRows(
+      buildOutline(checkout, { hidden, crossOnly: true }),
+      chapters,
+    );
+    for (const { chapter } of filtered) {
+      const original = chapters.find((c) => c.id === chapter.id);
+      expect(chapter.title).toBe(original?.title);
+      expect(chapter.from).toBe(original?.from);
+      expect(chapter.to).toBe(original?.to);
+    }
+  });
+});