@shortlink-org/portolan 0.1.0

package/src/flow/outline.test.ts

@@ -0,0 +1,212 @@
+import { describe, expect, it } from "vitest";
+import { rawCatalog as raw } from "../test-catalog";
+import type { Catalog, Flow } from "../catalog";
+import { stepFrames, walkSteps } from "../catalog";
+import { hiddenStepIds } from "./cross-context";
+import { flowPaths } from "./paths";
+import { buildOutline, outlineSteps } from "./outline";
+import type { OutlineFrame } from "./outline";
+
+const catalog = raw as unknown as Catalog;
+const checkout = catalog.flows.find((f) => f.slug === "checkout") as Flow;
+
+const NO_FILTER = { hidden: new Set<string>(), crossOnly: false };
+
+function frames(rows: ReturnType<typeof buildOutline>): OutlineFrame[] {
+  return rows.filter((r): r is OutlineFrame => r.type === "frame");
+}
+
+describe("buildOutline with a status filter", () => {
+  it("marks the steps of other statuses off, and keeps them", () => {
+    const rows = buildOutline(checkout, { ...NO_FILTER, statuses: new Set(["verified"]) });
+    const steps = outlineSteps(rows);
+    expect(steps.length).toBe(walkSteps(checkout.steps).length);
+    const off = steps.filter((r) => r.offStatus).map((r) => r.step.status);
+    expect(off.length).toBeGreaterThan(0);
+    expect(off.every((s) => s !== "verified")).toBe(true);
+    expect(steps.filter((r) => !r.offStatus).every((r) => r.step.status === "verified")).toBe(true);
+  });
+
+  it("marks nothing off when no status is chosen", () => {
+    const steps = outlineSteps(buildOutline(checkout, { ...NO_FILTER, statuses: null }));
+    expect(steps.some((r) => r.offStatus)).toBe(false);
+  });
+});
+
+describe("buildOutline", () => {
+  it("heads every frame with the keyword its shape calls for", () => {
+    const keywords = frames(buildOutline(checkout, NO_FILTER)).map(
+      (f) => f.keyword,
+    );
+    expect(keywords.length).toBeGreaterThan(0);
+    // A choice always opens with `alt` and continues with `else`; a parallel
+    // opens with `par` and continues with `and`. Neither continuation can
+    // appear before its opening, or the rail would show a branch of nothing.
+    const seenAlt = keywords.indexOf("alt");
+    const seenPar = keywords.indexOf("par");
+    expect(keywords.indexOf("else") === -1 || seenAlt !== -1).toBe(true);
+    expect(keywords.indexOf("and") === -1 || seenPar !== -1).toBe(true);
+    if (keywords.includes("else")) {
+      expect(seenAlt).toBeLessThan(keywords.indexOf("else"));
+    }
+    if (keywords.includes("and")) {
+      expect(seenPar).toBeLessThan(keywords.indexOf("and"));
+    }
+    for (const f of frames(buildOutline(checkout, NO_FILTER))) {
+      // Only `and` is nameless: it continues a parallel that is already named.
+      if (f.keyword !== "and") expect(f.title, f.keyword).toBeTruthy();
+    }
+  });
+
+  it("marks exactly the branches the catalog calls terminal", () => {
+    for (const flow of catalog.flows) {
+      const rows = buildOutline(flow, NO_FILTER);
+      const marked = frames(rows)
+        .filter((f) => f.terminal)
+        .map((f) => f.title);
+      const declared = [...stepFrames(flow.steps).values()]
+        .flat()
+        .filter((f) => f.terminal)
+        .map((f) => f.branch);
+      expect([...new Set(marked)].sort(), flow.slug).toEqual(
+        [...new Set(declared)].sort(),
+      );
+    }
+  });
+
+  it("indents every step by how many frames enclose it", () => {
+    for (const flow of catalog.flows) {
+      const enclosing = stepFrames(flow.steps);
+      for (const row of outlineSteps(buildOutline(flow, NO_FILTER))) {
+        expect(row.depth, `${flow.slug} ${row.step.id}`).toBe(
+          (enclosing.get(row.step.id) ?? []).length,
+        );
+      }
+    }
+  });
+
+  it("numbers over every step, filtered or not", () => {
+    const all = outlineSteps(buildOutline(checkout, NO_FILTER));
+    expect(all.map((r) => r.number)).toEqual(all.map((_, i) => i + 1));
+
+    const hidden = hiddenStepIds(checkout);
+    const filtered = outlineSteps(
+      buildOutline(checkout, { hidden, crossOnly: true }),
+    );
+    // The numbers survive the filter, so "step 7" means the same thing in both.
+    for (const row of filtered) {
+      expect(row.number).toBe(
+        all.find((r) => r.step.id === row.step.id)?.number,
+      );
+    }
+    expect(filtered.length).toBeLessThan(all.length);
+  });
+
+  it("drops a frame whose every step the filter removed", () => {
+    const first = walkSteps(checkout.steps)[0];
+    if (!first) throw new Error("fixture has no steps");
+    const hidden = new Set(
+      walkSteps(checkout.steps)
+        .map((s) => s.id)
+        .filter((id) => id !== first.id),
+    );
+    const rows = buildOutline(checkout, { hidden, crossOnly: true });
+    expect(frames(rows)).toEqual([]);
+    expect(outlineSteps(rows).map((r) => r.step.id)).toEqual([first.id]);
+  });
+
+  it("opens the frame at the first branch that survives the filter", () => {
+    // Hide every step of the first alt branch: the next surviving branch must
+    // read `alt`, not `else`, or the rail shows a choice with no opening arm.
+    const enclosing = stepFrames(checkout.steps);
+    const firstAlt = [...enclosing.values()]
+      .flat()
+      .find((f) => f.kind === "alt");
+    if (!firstAlt) throw new Error("fixture has no alt");
+    const firstBranch = firstAlt.branch;
+    const hidden = new Set(
+      walkSteps(checkout.steps)
+        .map((s) => s.id)
+        .filter((id) =>
+          (enclosing.get(id) ?? []).some(
+            (f) => f.id === firstAlt.id && f.branch === firstBranch,
+          ),
+        ),
+    );
+    const rows = buildOutline(checkout, { hidden, crossOnly: true });
+    const opening = frames(rows).find(
+      (f) => f.keyword === "alt" || f.keyword === "else",
+    );
+    expect(opening?.keyword).toBe("alt");
+    expect(opening?.title).not.toBe(firstBranch);
+  });
+
+  it("keeps only the steps of a chosen path", () => {
+    const path = flowPaths(checkout).paths.find((p) => p.terminal);
+    if (!path) throw new Error("fixture has no terminal path");
+    const all = walkSteps(checkout.steps).map((s) => s.id);
+    const rows = buildOutline(checkout, { ...NO_FILTER, path: path.stepIds });
+
+    expect(outlineSteps(rows).map((r) => r.step.id)).toEqual(
+      all.filter((id) => path.stepIds.has(id)),
+    );
+    expect(outlineSteps(rows).every((r) => !r.offPath)).toBe(true);
+  });
+
+  it("keeps only the branch frames selected by the path", () => {
+    const path = flowPaths(checkout).paths.find((p) => p.terminal);
+    if (!path) throw new Error("fixture has no terminal path");
+    const rows = buildOutline(checkout, { ...NO_FILTER, path: path.stepIds });
+    const choices = frames(rows).filter(
+      (f) => f.keyword === "alt" || f.keyword === "else",
+    );
+
+    expect(choices.map((f) => f.title)).toEqual(
+      path.choices.map((c) => c.title),
+    );
+    expect(choices.every((f) => !f.offPath)).toBe(true);
+  });
+
+  it("numbers every step by its place in the whole flow, path or not", () => {
+    const order = walkSteps(checkout.steps).map((s) => s.id);
+    const path = flowPaths(checkout).paths.find((p) => p.terminal);
+    if (!path) throw new Error("fixture has no terminal path");
+    const rows = buildOutline(checkout, { ...NO_FILTER, path: path.stepIds });
+    expect(outlineSteps(rows).map((r) => r.number)).toEqual(
+      order
+        .map((id, i) => ({ id, number: i + 1 }))
+        .filter(({ id }) => path.stepIds.has(id))
+        .map(({ number }) => number),
+    );
+  });
+
+  it("composes the path marking with the cross-context filter", () => {
+    const hidden = hiddenStepIds(checkout);
+    const path = flowPaths(checkout).paths.find((p) => p.terminal);
+    if (!path) throw new Error("fixture has no terminal path");
+    const rows = buildOutline(checkout, {
+      hidden,
+      crossOnly: true,
+      path: path.stepIds,
+    });
+    // Both filters remove their own set; the intersection is what remains.
+    expect(outlineSteps(rows).map((r) => r.step.id)).toEqual(
+      walkSteps(checkout.steps)
+        .map((s) => s.id)
+        .filter((id) => !hidden.has(id) && path.stepIds.has(id)),
+    );
+    expect(outlineSteps(rows).every((r) => !r.offPath)).toBe(true);
+  });
+
+  it("emits nothing but steps for a flow with no frames", () => {
+    const flat = catalog.flows.find(
+      (f) =>
+        stepFrames(f.steps).size > 0 &&
+        [...stepFrames(f.steps).values()].every((s) => s.length === 0),
+    );
+    if (!flat) throw new Error("fixture has no flat flow");
+    const rows = buildOutline(flat, NO_FILTER);
+    expect(frames(rows)).toEqual([]);
+    expect(rows).toHaveLength(outlineSteps(rows).length);
+  });
+});

package/src/flow/outline.ts

@@ -0,0 +1,170 @@
+// The rail's shape. A flow is a tree of frames, but a rail is a list, and the
+// flattening is where the meaning usually goes missing: indentation alone
+// cannot tell an alternative apart from a step that merely runs later.
+//
+// So the frames are flattened INTO the list rather than out of it. Every alt,
+// parallel and loop keeps a header row carrying its keyword and its condition,
+// in the sequence-diagram convention — alt / else, par / and, loop — and the
+// steps inside it are indented under that row.
+
+import type { Flow, FlowNode, Status, Step } from "../catalog";
+
+export type FrameKeyword = "alt" | "else" | "par" | "and" | "loop";
+
+export interface OutlineFrame {
+  type: "frame";
+  key: string;
+  depth: number;
+  keyword: FrameKeyword;
+  /** The loop's title, the parallel's title, or the alt branch's condition. */
+  title?: string;
+  /** Alt branch that ends the flow instead of rejoining it. */
+  terminal?: boolean;
+  /** No step under this frame runs on the chosen path. */
+  offPath?: boolean;
+}
+
+export interface OutlineStep {
+  type: "step";
+  key: string;
+  depth: number;
+  step: Step;
+  /** Position in the flow's overall step order, 1-based, frames included. */
+  number: number;
+  /** True when the cross-context view would leave this step out. */
+  hidden: boolean;
+  /** Reserved for consumers that render an unfocused path as context. */
+  offPath: boolean;
+  /** True when the status filter is on and this step is not the status asked for. */
+  offStatus: boolean;
+}
+
+export type OutlineRow = OutlineFrame | OutlineStep;
+
+export interface OutlineOptions {
+  /** Steps the cross-context view drops. */
+  hidden: ReadonlySet<string>;
+  /** When true, those steps are left out and empty frames go with them. */
+  crossOnly: boolean;
+  /**
+   * When set, only steps on this executable path remain. The unfiltered state
+   * already shows the whole decision tree; choosing a path is an explicit
+   * request to focus on one run through it, not merely recolour the tree.
+   */
+  path?: ReadonlySet<string> | null;
+  /**
+   * When set, steps of other statuses are marked `offStatus`. Like `path`,
+   * the step stays and recedes: the filter answers "which hops have been seen
+   * running", and the answer only means something against the ones that have
+   * not.
+   */
+  statuses?: ReadonlySet<Status> | null;
+}
+
+/**
+ * Rows for one flow, in walk order. Numbering runs over every step whether it
+ * is shown or not, so a filtered rail still says step 7 is the seventh step.
+ */
+export function buildOutline(
+  flow: Flow,
+  options: OutlineOptions,
+): OutlineRow[] {
+  let counter = 0;
+
+  const emit = (nodes: FlowNode[], depth: number): OutlineRow[] => {
+    const rows: OutlineRow[] = [];
+
+    for (const node of nodes) {
+      switch (node.type) {
+        case "step": {
+          counter += 1;
+          const hidden = options.hidden.has(node.id);
+          if (options.crossOnly && hidden) break;
+          if (options.path && !options.path.has(node.id)) break;
+          rows.push({
+            type: "step",
+            key: node.id,
+            depth,
+            step: node,
+            number: counter,
+            hidden,
+            offPath: false,
+            offStatus: options.statuses
+              ? !options.statuses.has(node.status)
+              : false,
+          });
+          break;
+        }
+
+        case "parallel": {
+          // Branch bodies are built first: a frame whose every branch was
+          // filtered away has nothing left to head, and heading nothing reads
+          // as a frame that exists but is empty.
+          const bodies = node.branches.map((branch) => emit(branch, depth + 1));
+          let opened = false;
+          bodies.forEach((body, i) => {
+            if (body.length === 0) return;
+            rows.push({
+              type: "frame",
+              key: `${node.id}:${i}`,
+              depth,
+              keyword: opened ? "and" : "par",
+              title: opened ? undefined : node.title,
+              offPath: false,
+            });
+            opened = true;
+            rows.push(...body);
+          });
+          break;
+        }
+
+        case "alt": {
+          const bodies = node.branches.map((branch) =>
+            emit(branch.steps, depth + 1),
+          );
+          let opened = false;
+          bodies.forEach((body, i) => {
+            const branch = node.branches[i];
+            if (body.length === 0 || !branch) return;
+            rows.push({
+              type: "frame",
+              key: `${node.id}:${i}`,
+              depth,
+              keyword: opened ? "else" : "alt",
+              title: branch.title,
+              terminal: branch.terminal,
+              offPath: false,
+            });
+            opened = true;
+            rows.push(...body);
+          });
+          break;
+        }
+
+        case "loop": {
+          const body = emit(node.steps, depth + 1);
+          if (body.length === 0) break;
+          rows.push({
+            type: "frame",
+            key: node.id,
+            depth,
+            keyword: "loop",
+            title: node.title,
+            offPath: false,
+          });
+          rows.push(...body);
+          break;
+        }
+      }
+    }
+
+    return rows;
+  };
+
+  return emit(flow.steps, 0);
+}
+
+/** Just the step rows, for anything that walks the rail rather than draws it. */
+export function outlineSteps(rows: readonly OutlineRow[]): OutlineStep[] {
+  return rows.filter((row): row is OutlineStep => row.type === "step");
+}

package/src/flow/paths.test.ts

@@ -0,0 +1,129 @@
+import { describe, expect, it } from "vitest";
+import { rawCatalog as raw } from "../test-catalog";
+import type { Alt, Catalog, Flow, FlowNode } from "../catalog";
+import { stepFrames, walkSteps } from "../catalog";
+import { flowPaths } from "./paths";
+
+const catalog = raw as unknown as Catalog;
+const checkout = catalog.flows.find((f) => f.slug === "checkout") as Flow;
+
+const ids = (flow: Flow): string[] => walkSteps(flow.steps).map((s) => s.id);
+
+/** Every Alt in a flow, at any depth. */
+function alts(nodes: FlowNode[], out: Alt[] = []): Alt[] {
+  for (const node of nodes) {
+    switch (node.type) {
+      case "step":
+        break;
+      case "alt":
+        out.push(node);
+        for (const b of node.branches) alts(b.steps, out);
+        break;
+      case "parallel":
+        for (const b of node.branches) alts(b, out);
+        break;
+      case "loop":
+        alts(node.steps, out);
+        break;
+    }
+  }
+  return out;
+}
+
+describe("flowPaths", () => {
+  it("gives a flow with no alt exactly one path, with no choices", () => {
+    const flat = catalog.flows.filter((f) => alts(f.steps).length === 0);
+    expect(flat.length).toBeGreaterThan(0);
+    for (const flow of flat) {
+      const { paths, truncated } = flowPaths(flow);
+      expect(truncated, flow.slug).toBe(false);
+      expect(paths, flow.slug).toHaveLength(1);
+      expect(paths[0]?.choices, flow.slug).toEqual([]);
+      expect(paths[0]?.terminal, flow.slug).toBe(false);
+      expect([...(paths[0]?.stepIds ?? [])], flow.slug).toEqual(ids(flow));
+    }
+  });
+
+  it("forks checkout once per branch of every alt it reaches", () => {
+    const { paths, truncated } = flowPaths(checkout);
+    expect(truncated).toBe(false);
+    // Five alts down the sequence — quote, risk, currency, authorization,
+    // capture — three of which carry a branch that ends the flow. A terminal
+    // branch takes no further choices, which is what keeps this from being 72.
+    expect(alts(checkout.steps).map((a) => a.branches.length)).toEqual([
+      2, 3, 3, 2, 2,
+    ]);
+    expect(paths).toHaveLength(30);
+    expect(new Set(paths.map((p) => p.id)).size).toBe(paths.length);
+  });
+
+  it("never puts two branches of the same alt on one path", () => {
+    for (const flow of catalog.flows) {
+      const frames = stepFrames(flow.steps);
+      for (const path of flowPaths(flow).paths) {
+        const chosen = new Map<string, string>();
+        for (const id of path.stepIds) {
+          for (const frame of frames.get(id) ?? []) {
+            if (frame.kind !== "alt") continue;
+            const seen = chosen.get(frame.id);
+            if (seen === undefined) chosen.set(frame.id, frame.branch ?? "");
+            else expect(seen, `${flow.slug} ${path.id}`).toBe(frame.branch);
+          }
+        }
+      }
+    }
+  });
+
+  it("stops a terminal path at the branch that ends it", () => {
+    for (const flow of catalog.flows) {
+      const order = ids(flow);
+      const frames = stepFrames(flow.steps);
+      for (const path of flowPaths(flow).paths) {
+        const ending = path.choices.find((c) => c.terminal);
+        expect(path.terminal, `${flow.slug} ${path.id}`).toBe(
+          ending !== undefined,
+        );
+        if (!ending) continue;
+        // Nothing outside the branch that ended it may survive past it.
+        const last = order.filter((id) => path.stepIds.has(id)).at(-1);
+        expect(
+          (frames.get(last ?? "") ?? []).some(
+            (f) => f.kind === "alt" && f.id === ending.altId,
+          ),
+          `${flow.slug} ${path.id}`,
+        ).toBe(true);
+      }
+    }
+  });
+
+  it("covers every step of the flow across all of its paths", () => {
+    for (const flow of catalog.flows) {
+      const union = new Set<string>();
+      for (const path of flowPaths(flow).paths) {
+        for (const id of path.stepIds) union.add(id);
+      }
+      expect([...union].sort(), flow.slug).toEqual([...ids(flow)].sort());
+    }
+  });
+
+  it("keeps every path a subsequence of the flow's own step order", () => {
+    for (const flow of catalog.flows) {
+      const order = ids(flow);
+      for (const path of flowPaths(flow).paths) {
+        const onPath = order.filter((id) => path.stepIds.has(id));
+        expect([...path.stepIds], `${flow.slug} ${path.id}`).toEqual(onPath);
+      }
+    }
+  });
+
+  it("names a path by the conditions it took, in order", () => {
+    for (const path of flowPaths(checkout).paths) {
+      expect(path.label).toBe(path.choices.map((c) => c.title).join(" · "));
+      expect(path.choices.map((c) => c.altId)).toEqual(
+        alts(checkout.steps)
+          .map((a) => a.id)
+          .filter((id) => path.choices.some((c) => c.altId === id)),
+      );
+    }
+  });
+});

package/src/flow/paths.ts

@@ -0,0 +1,147 @@
+// A path through a flow: one way the sequence can actually run.
+//
+// The step tree unions every alt branch, which is right for asking "what does
+// this flow touch" and wrong for asking "what happens". Those are different
+// questions and this module answers the second one.
+//
+// Only `alt` forks. A `parallel` runs all of its branches and a `loop` runs its
+// body, so neither multiplies the count; and a `terminal` alt branch ENDS the
+// path, so nothing written after that alt — at any enclosing level — belongs to
+// it. That last rule is the whole reason `AltBranch.terminal` exists.
+
+import type { Alt, Flow, FlowNode } from "../catalog";
+
+export interface PathChoice {
+  /** Id of the Alt this choice was made at. */
+  altId: string;
+  branchIndex: number;
+  /** The branch condition, verbatim. */
+  title: string;
+  /** This branch ends the flow rather than rejoining it. */
+  terminal?: boolean;
+}
+
+export interface FlowPath {
+  /** Stable across renders: the choices, in order, as "<altId>:<index>". */
+  id: string;
+  /** The conditions along the way, for a menu or a heading. */
+  label: string;
+  choices: PathChoice[];
+  /** Steps on this path, in walk order. */
+  stepIds: Set<string>;
+  /** The path stops at a terminal branch instead of running to the end. */
+  terminal: boolean;
+}
+
+export interface FlowPaths {
+  paths: FlowPath[];
+  /**
+   * Set when enumeration hit the ceiling. The paths listed are still real; there
+   * are simply more of them. Said out loud rather than truncated in silence,
+   * which would read as "these are all of them".
+   */
+  truncated: boolean;
+}
+
+/** Enough for any flow a person is going to read; a guard, not a design limit. */
+const MAX_PATHS = 64;
+
+/**
+ * Every way this flow can run. A flow with no alt yields exactly one path with
+ * no choices, so callers never need a special case for the flat shape.
+ */
+export function flowPaths(flow: Flow): FlowPaths {
+  const out: FlowPath[] = [];
+  let truncated = false;
+
+  /**
+   * Walks `nodes`, carrying the choices and steps gathered so far, and calls
+   * `emit` once for every way the walk can finish. Whatever follows a frame is
+   * spliced onto the front of the recursion rather than visited afterwards, so
+   * a terminal branch simply never receives its siblings.
+   */
+  const walk = (
+    nodes: FlowNode[],
+    choices: PathChoice[],
+    steps: string[],
+    emit: (choices: PathChoice[], steps: string[], terminal: boolean) => void,
+  ): void => {
+    for (let i = 0; i < nodes.length; i += 1) {
+      const node = nodes[i];
+      if (!node) continue;
+
+      if (node.type === "step") {
+        steps.push(node.id);
+        continue;
+      }
+
+      if (node.type === "loop") {
+        // The body always runs, so it neither forks nor is optional here.
+        const rest = nodes.slice(i + 1);
+        walk([...node.steps, ...rest], choices, steps, emit);
+        return;
+      }
+
+      if (node.type === "parallel") {
+        const rest = nodes.slice(i + 1);
+        walk([...node.branches.flat(), ...rest], choices, steps, emit);
+        return;
+      }
+
+      // An alt is the only fork. Each branch continues into whatever follows
+      // the alt — unless it is terminal, in which case nothing follows it.
+      const alt: Alt = node;
+      const rest = nodes.slice(i + 1);
+      alt.branches.forEach((branch, branchIndex) => {
+        const choice: PathChoice = {
+          altId: alt.id,
+          branchIndex,
+          title: branch.title,
+          ...(branch.terminal ? { terminal: true } : {}),
+        };
+        const nextChoices = [...choices, choice];
+        const nextSteps = [...steps];
+        if (branch.terminal) {
+          walk(branch.steps, nextChoices, nextSteps, (c, s) =>
+            emit(c, s, true),
+          );
+        } else {
+          walk([...branch.steps, ...rest], nextChoices, nextSteps, emit);
+        }
+      });
+      return;
+    }
+
+    emit(choices, steps, false);
+  };
+
+  walk(flow.steps, [], [], (choices, steps, terminal) => {
+    if (out.length >= MAX_PATHS) {
+      truncated = true;
+      return;
+    }
+    out.push({
+      id: choices.map((c) => `${c.altId}:${c.branchIndex}`).join("|"),
+      label: pathLabel(choices),
+      choices,
+      stepIds: new Set(steps),
+      terminal,
+    });
+  });
+
+  return { paths: out, truncated };
+}
+
+/** The conditions along a path, or a name for the one path a flat flow has. */
+function pathLabel(choices: readonly PathChoice[]): string {
+  if (choices.length === 0) return "the only path";
+  return choices.map((c) => c.title).join(" · ");
+}
+
+/** The path with this id, if the flow still has one. */
+export function findPath(
+  paths: readonly FlowPath[],
+  id: string,
+): FlowPath | null {
+  return paths.find((p) => p.id === id) ?? null;
+}