@shortlink-org/portolan 0.1.0

package/src/flow/chapters.ts

@@ -0,0 +1,225 @@
+// Chapters: the rail's second level, above steps and below the flow.
+//
+// A forty-five step rail is a wall. What breaks it up is already in the data —
+// every alt, parallel and loop is a self-contained episode with a name of its
+// own, and the plain steps between two of them are the connective tissue that
+// gets the sequence from one to the next. So a chapter is exactly one of those
+// two things:
+//
+//   * a top-level frame — the alt, the par, the loop, named by its own title;
+//   * a run of top-level plain steps, named by the first and last of them.
+//
+// Only TOP-LEVEL nodes make chapters. A frame nested inside another frame is
+// part of its parent's episode, not an episode of its own, and promoting it
+// would put the same steps in two chapters at once.
+//
+// Chapters are derived from the FLOW, never from the filtered rail: switching
+// the cross-context filter must not renumber or rename them. What the filter
+// changes is which chapters have any rows left to show, and that is decided
+// where the rows are grouped rather than here.
+
+import type { Flow, FlowNode, Status, Step } from "../catalog";
+import { walkSteps } from "../catalog";
+import { contextResolver } from "./cross-context";
+import type { OutlineRow } from "./outline";
+
+export type ChapterKind = "alt" | "par" | "loop" | "steps";
+
+export interface Chapter {
+  /** Stable across renders and filters: the frame's id, or the first step's. */
+  id: string;
+  kind: ChapterKind;
+  /**
+   * What this episode is called. The frame's own title for a frame — an alt
+   * takes its first branch's condition, which is the question being asked —
+   * and "first → last" for a run of plain steps.
+   */
+  title: string;
+  /** Step numbers this chapter spans, 1-based over the whole flow. */
+  from: number;
+  to: number;
+  stepIds: string[];
+  /** How many steps of each status. The header's summary dots. */
+  status: Record<Status, number>;
+  /** Contexts these steps touch, in the order they are first touched. */
+  contexts: string[];
+  /** An alt whose opening branch ends the flow rather than rejoining it. */
+  terminal?: boolean;
+}
+
+/** A chapter and the rail rows that fall under it, in rail order. */
+export interface ChapterGroup {
+  chapter: Chapter;
+  rows: OutlineRow[];
+}
+
+/** What a step is called when it has to name something. */
+export function stepTitle(step: Step): string {
+  return step.label ?? step.ref ?? step.kind;
+}
+
+const NO_STATUS: Record<Status, number> = {
+  verified: 0,
+  declared: 0,
+  unresolved: 0,
+};
+
+/**
+ * The chapters of one flow, in walk order. A flow with no frames yields
+ * exactly one chapter, so callers never need a special case for the flat
+ * shape — the rail draws one header and every step under it.
+ */
+export function buildChapters(flow: Flow): Chapter[] {
+  const contextOf = contextResolver(flow);
+
+  // Numbering runs over every step of the flow, frames included, and matches
+  // the rail's own counter because both walk the tree the same way.
+  const numberOf = new Map<string, number>();
+  walkSteps(flow.steps).forEach((step, i) => numberOf.set(step.id, i + 1));
+
+  const chapters: Chapter[] = [];
+
+  const describe = (
+    id: string,
+    kind: ChapterKind,
+    title: string,
+    steps: Step[],
+    terminal?: boolean,
+  ): void => {
+    if (steps.length === 0) return;
+    const status = { ...NO_STATUS };
+    const contexts: string[] = [];
+    for (const step of steps) {
+      status[step.status] += 1;
+      for (const participant of [step.from, step.to]) {
+        const context = contextOf(participant);
+        if (context && !contexts.includes(context)) contexts.push(context);
+      }
+    }
+    const first = steps[0];
+    const last = steps[steps.length - 1];
+    chapters.push({
+      id,
+      kind,
+      title,
+      from: (first && numberOf.get(first.id)) ?? 0,
+      to: (last && numberOf.get(last.id)) ?? 0,
+      stepIds: steps.map((s) => s.id),
+      status,
+      contexts,
+      ...(terminal ? { terminal: true } : {}),
+    });
+  };
+
+  /** The plain steps seen since the last frame, waiting for a name. */
+  let run: Step[] = [];
+  const flushRun = (): void => {
+    if (run.length === 0) return;
+    const first = run[0];
+    const last = run[run.length - 1];
+    if (!first || !last) {
+      run = [];
+      return;
+    }
+    const title =
+      run.length === 1
+        ? stepTitle(first)
+        : `${stepTitle(first)} → ${stepTitle(last)}`;
+    describe(`steps:${first.id}`, "steps", title, run);
+    run = [];
+  };
+
+  for (const node of flow.steps as FlowNode[]) {
+    if (node.type === "step") {
+      run.push(node);
+      continue;
+    }
+
+    flushRun();
+
+    if (node.type === "alt") {
+      // The alt's name is the question it asks, and the first branch is where
+      // that question is written down. The other conditions are one row below
+      // as `else` frames, so repeating them in the header buys nothing.
+      const opening = node.branches[0];
+      describe(
+        node.id,
+        "alt",
+        opening?.title ?? "alt",
+        walkSteps([node]),
+        opening?.terminal,
+      );
+      continue;
+    }
+
+    if (node.type === "parallel") {
+      describe(node.id, "par", node.title ?? "in parallel", walkSteps([node]));
+      continue;
+    }
+
+    describe(node.id, "loop", node.title, walkSteps([node]));
+  }
+
+  flushRun();
+  return chapters;
+}
+
+/**
+ * The rail's rows, cut into their chapters.
+ *
+ * A frame row belongs to the chapter of the first step underneath it: a frame
+ * header with no steps left after filtering is not a chapter of its own, it is
+ * a header for nothing, and it goes wherever its body went. Chapters whose
+ * every step was filtered away are dropped entirely rather than drawn empty.
+ */
+export function groupRows(
+  rows: readonly OutlineRow[],
+  chapters: readonly Chapter[],
+): ChapterGroup[] {
+  const chapterOf = new Map<string, Chapter>();
+  for (const chapter of chapters) {
+    for (const stepId of chapter.stepIds) chapterOf.set(stepId, chapter);
+  }
+
+  // Resolved back to front: a frame's chapter is the chapter of the next step
+  // row, and reading backwards is what makes "next" available without a scan.
+  const owner: (Chapter | undefined)[] = new Array(rows.length);
+  let ahead: Chapter | undefined;
+  for (let i = rows.length - 1; i >= 0; i -= 1) {
+    const row = rows[i];
+    if (row?.type === "step") ahead = chapterOf.get(row.step.id);
+    owner[i] = ahead;
+  }
+
+  const groups: ChapterGroup[] = [];
+  rows.forEach((row, i) => {
+    const chapter = owner[i];
+    if (!chapter) return;
+    const last = groups[groups.length - 1];
+    if (last && last.chapter.id === chapter.id) last.rows.push(row);
+    else groups.push({ chapter, rows: [row] });
+  });
+
+  return groups;
+}
+
+/**
+ * The rows a chapter actually draws.
+ *
+ * A frame chapter's header already says the keyword and the condition, so the
+ * frame row that opens it would say them twice in a row. It is dropped — but
+ * only when it really is the same row: under the cross-context filter the
+ * opening branch can vanish and the NEXT one is promoted to head the frame, and
+ * then the row carries a condition the header does not have and has to stay.
+ */
+export function railRows(group: ChapterGroup): OutlineRow[] {
+  const [first, ...rest] = group.rows;
+  if (
+    group.chapter.kind !== "steps" &&
+    first?.type === "frame" &&
+    first.title === group.chapter.title
+  ) {
+    return rest;
+  }
+  return group.rows;
+}

package/src/flow/continues.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, it } from "vitest";
+import { catalog } from "../data";
+import { walkSteps } from "../catalog";
+import type { Flow, Step } from "../catalog";
+import { continuationIndex, continuationsOf, openingRef } from "./continues";
+
+/** A step carrying `ref`; the participants are not what any of this is about. */
+function step(id: string, ref?: string): Step {
+  return {
+    type: "step",
+    id,
+    from: "a",
+    to: "b",
+    kind: ref ? "event" : "call",
+    ...(ref ? { ref } : {}),
+    status: "declared",
+  };
+}
+
+function makeFlow(slug: string, steps: Step[]): Flow {
+  return {
+    id: `test.${slug}`,
+    slug,
+    name: slug.replace(/-/g, " "),
+    summary: "",
+    owner: "shop",
+    participants: [],
+    steps,
+  };
+}
+
+// The fixture estate has no flow that opens on an event — every one of them
+// starts with an inbound call — so the seam this module is about is built by
+// hand here. That is the honest way round: the rule is what is under test, and
+// a catalog that happens not to exercise it must not silently skip it.
+const emits = makeFlow("emits", [step("s1"), step("s2", "shop.oms.Order.Placed")]);
+const opens = makeFlow("opens", [
+  step("t1", "shop.oms.Order.Placed"),
+  step("t2", "shop.oms.Order.Priced"),
+]);
+const mentions = makeFlow("mentions", [
+  step("u1"),
+  step("u2", "shop.oms.Order.Placed"),
+]);
+const flows = [emits, opens, mentions];
+
+describe("openingRef", () => {
+  it("is the ref of the flow's first step, in walk order", () => {
+    expect(openingRef(opens)).toBe("shop.oms.Order.Placed");
+    expect(openingRef(emits)).toBeUndefined();
+    for (const f of catalog.flows) {
+      expect(openingRef(f)).toBe(walkSteps(f.steps)[0]?.ref);
+    }
+  });
+});
+
+describe("continuationsOf", () => {
+  it("finds the flow a step's event opens", () => {
+    const hits = continuationsOf(step("s2", "shop.oms.Order.Placed"), emits, flows);
+    expect(hits.map((h) => h.slug)).toEqual(["opens"]);
+  });
+
+  it("ignores an event another flow merely mentions in its middle", () => {
+    // `mentions` carries the same ref, but not first, so it is another reader
+    // of the event rather than the continuation of this one.
+    const hits = continuationsOf(step("s2", "shop.oms.Order.Placed"), emits, flows);
+    expect(hits.map((h) => h.slug)).not.toContain("mentions");
+  });
+
+  it("never points a flow at itself", () => {
+    const hits = continuationsOf(step("t1", "shop.oms.Order.Placed"), opens, flows);
+    expect(hits).toEqual([]);
+  });
+
+  it("says nothing for a step that carries no ref", () => {
+    expect(continuationsOf(step("s1"), emits, flows)).toEqual([]);
+  });
+});
+
+describe("continuationIndex", () => {
+  it("agrees with the per-step answer", () => {
+    const index = continuationIndex(emits, flows);
+    for (const s of walkSteps(emits.steps)) {
+      expect(index.get(s.id) ?? []).toEqual(continuationsOf(s, emits, flows));
+    }
+  });
+
+  it("holds an entry only for steps that actually continue somewhere", () => {
+    const index = continuationIndex(emits, flows);
+    expect([...index.keys()]).toEqual(["s2"]);
+    for (const [, hits] of index) expect(hits.length).toBeGreaterThan(0);
+  });
+
+  it("agrees with the per-step answer across the real catalog too", () => {
+    for (const f of catalog.flows) {
+      const index = continuationIndex(f, catalog.flows);
+      for (const s of walkSteps(f.steps)) {
+        expect(index.get(s.id) ?? []).toEqual(continuationsOf(s, f, catalog.flows));
+      }
+    }
+  });
+});

package/src/flow/continues.ts

@@ -0,0 +1,65 @@
+// Where a flow hands off to another one.
+//
+// A step that publishes an event is often the last thing one flow says and the
+// first thing another one hears. Nothing in the catalog states that seam — it
+// is not a field, it is a coincidence of two refs — but it is the single most
+// useful link a rail can carry, because it is the answer to "and then what?"
+// that the flow itself cannot give.
+//
+// The rule is deliberately strict: only the FIRST step of the other flow
+// counts. A flow that merely mentions the same event somewhere in its middle
+// is not continuing this one, it is another reader of the same event, and the
+// event page already says so.
+
+import type { Flow, Step } from "../catalog";
+import { walkSteps } from "../catalog";
+
+export interface Continuation {
+  slug: string;
+  name: string;
+}
+
+/** The ref the flow opens with, or undefined for a flow that opens with none. */
+export function openingRef(flow: Flow): string | undefined {
+  return walkSteps(flow.steps)[0]?.ref;
+}
+
+/**
+ * Flows that begin where this step ends. `from` is the flow the step belongs
+ * to and is never returned: a flow does not continue in itself.
+ */
+export function continuationsOf(
+  step: Step,
+  from: Flow,
+  flows: readonly Flow[],
+): Continuation[] {
+  if (!step.ref) return [];
+  return flows
+    .filter((flow) => flow.slug !== from.slug && openingRef(flow) === step.ref)
+    .map((flow) => ({ slug: flow.slug, name: flow.name }));
+}
+
+/** Continuations for every step of a flow at once, keyed by step id. */
+export function continuationIndex(
+  flow: Flow,
+  flows: readonly Flow[],
+): Map<string, Continuation[]> {
+  // One pass over the other flows rather than one per step: a flow with forty
+  // steps would otherwise walk the whole catalog forty times.
+  const byRef = new Map<string, Continuation[]>();
+  for (const other of flows) {
+    if (other.slug === flow.slug) continue;
+    const ref = openingRef(other);
+    if (!ref) continue;
+    const list = byRef.get(ref) ?? [];
+    list.push({ slug: other.slug, name: other.name });
+    byRef.set(ref, list);
+  }
+
+  const out = new Map<string, Continuation[]>();
+  for (const step of walkSteps(flow.steps)) {
+    const hits = step.ref ? byRef.get(step.ref) : undefined;
+    if (hits && hits.length > 0) out.set(step.id, hits);
+  }
+  return out;
+}

package/src/flow/cross-context.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { catalog } from "../testing/estate";
+// Same split as src/likec4/ids.test.ts: the predicate is checked against the
+// frozen fixture, and the generated views against the estate they were
+// generated from.
+import { catalog as shipped } from "../data";
+import { walkSteps } from "../catalog";
+import {
+  contextResolver,
+  hiddenStepIds,
+  isCrossContext,
+} from "./cross-context";
+import { flowCrossViewId, flowViewId } from "../likec4/ids";
+
+const checkout = catalog.flows.find((f) => f.slug === "checkout");
+if (!checkout) throw new Error("fixture missing checkout flow");
+
+describe("isCrossContext", () => {
+  it("drops internal calls, self messages and same-context hops", () => {
+    expect([...hiddenStepIds(checkout)].sort()).toEqual([
+      "s10",
+      "s11",
+      "s13",
+      "s17",
+      "s18",
+      "s2",
+      "s23",
+      "s3",
+      "s33",
+      "s4",
+      "s41",
+      "s6",
+      "s8",
+    ]);
+  });
+
+  it("keeps hops touching a null-context lane", () => {
+    const contextOf = contextResolver(checkout);
+    const s12 = walkSteps(checkout.steps).find((s) => s.id === "s12");
+    if (!s12) throw new Error("no s12");
+    // shop.oms (shop) -> bus (null)
+    expect(isCrossContext(s12, contextOf)).toBe(true);
+  });
+});
+
+describe("generated LikeC4 views agree with the predicate", () => {
+  const views = readFileSync("likec4/views.c4", "utf8");
+
+  it("declares both a full and a cross view for every flow", () => {
+    for (const flow of shipped.flows) {
+      expect(views, flow.slug).toContain(`dynamic view ${flowViewId(flow)} {`);
+      expect(views, flow.slug).toContain(
+        `dynamic view ${flowCrossViewId(flow)} {`,
+      );
+    }
+  });
+
+  it("omits exactly the hidden steps from a cross view", () => {
+    // Whichever shipped flow hides the most: the point is the predicate, and
+    // pinning one flow by name is how this test broke when that flow left.
+    const flow = [...shipped.flows].sort(
+      (a, b) => hiddenStepIds(b).size - hiddenStepIds(a).size,
+    )[0];
+    if (!flow) throw new Error("no flows");
+    const hidden = hiddenStepIds(flow);
+    expect(hidden.size).toBeGreaterThan(0);
+
+    const start = views.indexOf(`dynamic view ${flowCrossViewId(flow)} {`);
+    expect(start, flow.slug).toBeGreaterThan(-1);
+    const section = views.slice(
+      start,
+      views.indexOf("dynamic view", start + 10),
+    );
+
+    const labelOf = (id: string): string => {
+      const step = walkSteps(flow.steps).find((s) => s.id === id);
+      if (!step) throw new Error(`no step ${id}`);
+      return step.label ?? step.ref ?? step.kind;
+    };
+    const shown = new Set(
+      walkSteps(flow.steps)
+        .filter((s) => !hidden.has(s.id))
+        .map((s) => labelOf(s.id)),
+    );
+    for (const label of shown) {
+      expect(section, `${flow.slug}: ${label}`).toContain(label);
+    }
+    // A hop the predicate hides is in no cross view - unless a hop that stays
+    // happens to carry the same label, which is not this rule's business.
+    for (const id of hidden) {
+      const label = labelOf(id);
+      if (shown.has(label)) continue;
+      expect(section, `${flow.slug}: ${label}`).not.toContain(label);
+    }
+  });
+});

package/src/flow/cross-context.ts

@@ -0,0 +1,35 @@
+// The cross-context predicate. Data logic, not rendering: the LikeC4 generator
+// applies it when emitting the *_cross views, and the step rail applies it to
+// stay in step with whichever view is on screen.
+
+import type { Flow, Step } from "../catalog";
+import { walkSteps } from "../catalog";
+
+export function isCrossContext(
+  step: Step,
+  contextOf: (participantId: string) => string | null,
+): boolean {
+  if (step.kind === "call") return false;
+  if (step.from === step.to) return false;
+  const a = contextOf(step.from);
+  const b = contextOf(step.to);
+  if (a !== null && a === b) return false;
+  return true;
+}
+
+export function contextResolver(
+  flow: Flow,
+): (participantId: string) => string | null {
+  const contexts = new Map(flow.participants.map((p) => [p.id, p.context]));
+  return (id) => contexts.get(id) ?? null;
+}
+
+/** Ids of the steps a cross-context view leaves out. */
+export function hiddenStepIds(flow: Flow): Set<string> {
+  const contextOf = contextResolver(flow);
+  return new Set(
+    walkSteps(flow.steps)
+      .filter((step) => !isCrossContext(step, contextOf))
+      .map((step) => step.id),
+  );
+}

package/src/flow/mermaid.test.ts

@@ -0,0 +1,22 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+import { catalog, index } from "../data";
+import { flowAnswers } from "./answers";
+import { flowMermaid } from "./mermaid";
+
+/** The fenced mermaid block of a generated flow page. */
+function generated(slug: string): string {
+  const page = readFileSync(`docs/flows/${slug}.md`, "utf8");
+  const match = /```mermaid\n([\s\S]*?)```/.exec(page);
+  if (!match) throw new Error(`no mermaid block in docs/flows/${slug}.md`);
+  return match[1]!;
+}
+
+describe("flowMermaid", () => {
+  // The Go generator and this port draw the same diagram, or one of them is
+  // wrong; the generated pages are the record of what the Go one drew.
+  it.each(catalog.flows.map((f) => f.slug))("draws %s as gen-markdown does", (slug) => {
+    const flow = catalog.flows.find((f) => f.slug === slug)!;
+    expect(flowMermaid(flow, flowAnswers(index, flow))).toBe(generated(slug));
+  });
+});

package/src/flow/mermaid.ts

@@ -0,0 +1,141 @@
+// The flow as a Mermaid sequence diagram, for copying out.
+//
+// This is the same picture plugins/gen-markdown/flow.go draws into docs/, line
+// for line, and mermaid.test.ts holds the two to each other: a reader who
+// pastes this into a wiki and a reader of the generated page see one diagram.
+// Participants are aliased p0, p1, … because Mermaid wants an identifier where
+// the catalog has a dotted service id.
+
+import type { Flow, FlowNode, Step } from "../catalog";
+
+/**
+ * `answers` is what each step's callee hands back, by step id - see
+ * `answers.ts`. It is passed in rather than looked up here so that this stays
+ * a function of the flow, and so the Go generator, which has the catalog and
+ * not the index, can hand over the same map.
+ */
+export function flowMermaid(
+  flow: Flow,
+  answers: ReadonlyMap<string, string> = new Map(),
+): string {
+  const alias = new Map<string, string>();
+  flow.participants.forEach((p, i) => alias.set(p.id, `p${i}`));
+  const of = (id: string) => alias.get(id) ?? id;
+
+  const lines: string[] = ["sequenceDiagram", "    autonumber"];
+  for (const p of flow.participants) {
+    const keyword = p.kind === "actor" ? "actor" : "participant";
+    lines.push(`    ${keyword} ${of(p.id)} as ${text(p.label || p.id)}`);
+  }
+  emit(flow.steps, of, 1, lines, answers);
+  return `${lines.join("\n")}\n`;
+}
+
+function emit(
+  nodes: FlowNode[],
+  of: (id: string) => string,
+  depth: number,
+  out: string[],
+  answers: ReadonlyMap<string, string>,
+): void {
+  const indent = "    ".repeat(depth);
+  for (const node of nodes) {
+    switch (node.type) {
+      case "step": {
+        // An event is drawn with the async arrow. A reader who cannot tell a
+        // call from a publication is reading a different flow.
+        const arrow = node.kind === "event" ? "-)" : "->>";
+        // The reply rides on the hop's own label rather than coming back as a
+        // second message: `autonumber` counts messages, and the numbers here
+        // are the numbers of the step list beside the diagram.
+        out.push(`${indent}${of(node.from)}${arrow}${of(node.to)}: ${text(labelWithAnswer(node, answers))}`);
+        break;
+      }
+      case "parallel": {
+        out.push(`${indent}par ${text(node.title?.trim() ? node.title : "in parallel")}`);
+        node.branches.forEach((branch, i) => {
+          if (i > 0) out.push(`${indent}and`);
+          emit(branch, of, depth + 1, out, answers);
+        });
+        out.push(`${indent}end`);
+        break;
+      }
+      case "alt": {
+        node.branches.forEach((branch, i) => {
+          out.push(`${indent}${i === 0 ? "alt " : "else "}${text(branch.title)}`);
+          emit(branch.steps, of, depth + 1, out, answers);
+          // A branch that ends the flow has to say so inside the diagram, or
+          // the steps drawn after the alt read as if they follow it too.
+          if (branch.terminal) {
+            const last = lastParticipant(branch.steps);
+            if (last)
+              out.push(`${"    ".repeat(depth + 1)}Note over ${of(last)}: flow ends here`);
+          }
+        });
+        out.push(`${indent}end`);
+        break;
+      }
+      case "loop": {
+        out.push(`${indent}loop ${text(node.title)}`);
+        emit(node.steps, of, depth + 1, out, answers);
+        out.push(`${indent}end`);
+        break;
+      }
+    }
+  }
+}
+
+function stepLabel(step: Step): string {
+  return step.label || step.ref || step.kind;
+}
+
+function lastParticipant(nodes: FlowNode[]): string {
+  for (let i = nodes.length - 1; i >= 0; i--) {
+    const node = nodes[i]!;
+    switch (node.type) {
+      case "step":
+        return node.to;
+      case "parallel":
+        for (let j = node.branches.length - 1; j >= 0; j--) {
+          const p = lastParticipant(node.branches[j]!);
+          if (p) return p;
+        }
+        break;
+      case "alt":
+        for (let j = node.branches.length - 1; j >= 0; j--) {
+          const p = lastParticipant(node.branches[j]!.steps);
+          if (p) return p;
+        }
+        break;
+      case "loop": {
+        const p = lastParticipant(node.steps);
+        if (p) return p;
+        break;
+      }
+    }
+  }
+  return "";
+}
+
+/** The step's label, and what comes back when a contract says so. */
+export function labelWithAnswer(
+  step: Step,
+  answers: ReadonlyMap<string, string>,
+): string {
+  const answer = answers.get(step.id);
+  return answer ? `${stepLabel(step)} → ${answer}` : stepLabel(step);
+}
+
+/**
+ * A label made safe on a Mermaid line: a newline ends the statement, so does
+ * a semicolon, and a bare # opens an entity code. Semicolons go first, or the
+ * escape for # is mangled into text.
+ */
+function text(s: string): string {
+  return s
+    .replace(/\r\n/g, "\n")
+    .replace(/\n/g, " ")
+    .replace(/;/g, ",")
+    .replace(/#/g, "#35;")
+    .trim();
+}