@runbooks/graph 0.1.0

package/dist/layout.test.js

@@ -0,0 +1,181 @@
+import { describe, it, expect } from "vitest";
+import { readdirSync, readFileSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { toGraph } from "./model.js";
+import { layout, happyPath, topologicalOrder } from "./layout.js";
+const CORPUS = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "schema", "fixtures", "p1-valid");
+const corpus = readdirSync(CORPUS).map((name) => ({
+    name,
+    graph: toGraph(JSON.parse(readFileSync(join(CORPUS, name), "utf8"))),
+}));
+/**
+ * P-08's constraints are hard, not preferences. A generic layered algorithm optimizes
+ * edge crossings and would happily place a rollback on the right; the point of the rule
+ * is that a reader locates the bad path in two seconds, and that only works if direction
+ * means the same thing on every graph in the catalog.
+ */
+describe("the happy path is a strictly vertical centre axis", () => {
+    it.each(corpus)("$name keeps every happy-path node at x = 0", ({ graph }) => {
+        const { positions, happyPath: path } = layout(graph);
+        expect(path.length).toBeGreaterThan(1);
+        for (const id of path)
+            expect(positions[id].x).toBe(0);
+    });
+    it.each(corpus)("$name descends without revisiting a layer", ({ graph }) => {
+        const { positions, happyPath: path } = layout(graph);
+        const ys = path.map((id) => positions[id].y);
+        for (let i = 1; i < ys.length; i++)
+            expect(ys[i]).toBeGreaterThan(ys[i - 1]);
+    });
+});
+describe("direction is consistent across every graph", () => {
+    it.each(corpus)("$name puts no rollback target right of the axis", ({ graph }) => {
+        const { positions } = layout(graph);
+        for (const e of graph.edges.filter((x) => x.kind === "rollback")) {
+            expect(positions[e.to].x, `${e.to} is a rollback target`).toBeLessThanOrEqual(0);
+        }
+    });
+    // A node can be both a rollback and a failure route — a check that fails routes to the
+    // step that undoes the previous action. Rollback wins, because that is what the node
+    // *is*; the on_fail edge merely reaches it.
+    it.each(corpus)("$name puts a purely on_fail target right of the axis", ({ graph }) => {
+        const { positions, happyPath: path } = layout(graph);
+        const onAxis = new Set(path);
+        const rollbackTargets = new Set(graph.edges.filter((x) => x.kind === "rollback").map((x) => x.to));
+        for (const e of graph.edges.filter((x) => x.kind === "on_fail")) {
+            if (onAxis.has(e.to) || rollbackTargets.has(e.to))
+                continue;
+            expect(positions[e.to].x, `${e.to} is an on_fail target`).toBeGreaterThan(0);
+        }
+    });
+    it("keeps a node that is both a rollback and a failure route on the rollback side", () => {
+        const graph = toGraph({
+            runbook: {
+                steps: [
+                    { id: "s1", kind: "action", title: "Drop it", risk: "destructive", rollback_ref: "s3", next: "s2" },
+                    { id: "s2", kind: "check", title: "Confirm", expect: "gone", on_fail: "s3", next: "end:success" },
+                    { id: "s3", kind: "action", title: "Put it back", risk: "reversible-write", next: "end:aborted" },
+                ],
+            },
+        });
+        expect(layout(graph).positions.s3.x).toBeLessThan(0);
+    });
+    it.each(corpus)("$name puts every escalation right of the axis", ({ graph }) => {
+        const { positions, happyPath: path } = layout(graph);
+        for (const n of graph.nodes.filter((x) => x.kind === "escalate")) {
+            if (path.includes(n.id))
+                continue;
+            expect(positions[n.id].x).toBeGreaterThan(0);
+        }
+    });
+});
+describe("layout is pure and deterministic", () => {
+    // What makes a rendered SVG diffable and a card's mini-graph silhouette stable across
+    // builds. Without it, a silhouette is not a silhouette.
+    it.each(corpus)("$name produces byte-identical coordinates twice", ({ graph }) => {
+        expect(JSON.stringify(layout(graph))).toBe(JSON.stringify(layout(graph)));
+    });
+    it.each(corpus)("$name places every node exactly once", ({ graph }) => {
+        const { positions } = layout(graph);
+        expect(Object.keys(positions).sort()).toEqual(graph.nodes.map((n) => n.id).sort());
+    });
+    it.each(corpus)("$name never stacks two nodes on one point", ({ graph }) => {
+        const seen = new Set(Object.values(layout(graph).positions).map((p) => `${p.x},${p.y}`));
+        expect(seen.size).toBe(graph.nodes.length);
+    });
+    // A malformed graph must not hang an editor that lays out on every keystroke.
+    it("settles on a 12-node graph well inside an interactive budget", () => {
+        const steps = Array.from({ length: 12 }, (_, i) => ({
+            id: `s${i}`, kind: "action", title: `Step ${i}`, risk: "read-only",
+        }));
+        const graph = toGraph({ runbook: { steps } });
+        const started = performance.now();
+        for (let i = 0; i < 100; i++)
+            layout(graph);
+        expect((performance.now() - started) / 100).toBeLessThan(5);
+    });
+});
+describe("happy path selection", () => {
+    it("does not follow a branch straight into an escalation", () => {
+        const graph = toGraph({
+            runbook: {
+                steps: [
+                    { id: "s1", kind: "decision", title: "Decide", question: "q?", branches: { bad: "s9", good: "s2", default: "s9" } },
+                    { id: "s2", kind: "action", title: "Act", risk: "read-only", next: "end:success" },
+                    { id: "s9", kind: "escalate", title: "Escalate", to: "team:x" },
+                ],
+            },
+        });
+        expect(happyPath(graph)).toContain("s2");
+        expect(happyPath(graph)).not.toContain("s9");
+    });
+});
+/**
+ * The order a person is handed, not just an order (§18.2, W-02).
+ *
+ * The graph is also a structured list, and the list is what a screen reader and a no-CSS
+ * reader get. A rollback edge is deliberately not a flow edge — including it would make a
+ * cycle of every paired destructive step — which left the step it points at with no
+ * incoming flow and put it wherever the node list happened to fall. On
+ * `k8s-node-not-ready-drain` that read "start, Uncordon the node, Confirm the node is
+ * NotReady": the undo before the action, which is the procedure told backwards.
+ */
+describe("the linear order reads as the procedure", () => {
+    const undoPairs = (graph) => graph.edges.filter((e) => e.kind === "rollback");
+    it("has fixtures with a rollback in them", () => {
+        // Otherwise the sweep below would pass over a corpus that never exercises the rule.
+        expect(corpus.some(({ graph }) => undoPairs(graph).length > 0)).toBe(true);
+    });
+    it.each(corpus)("$name reads an undo after the step it undoes", ({ graph }) => {
+        const order = topologicalOrder(graph);
+        for (const edge of undoPairs(graph)) {
+            expect(order.indexOf(edge.to), `${edge.to} undoes ${edge.from} and is read before it`).toBeGreaterThan(order.indexOf(edge.from));
+        }
+    });
+    /** The guarantee that must survive: it is still a topological order over the flow. */
+    it.each(corpus)("$name still orders every flow edge from before to", ({ graph }) => {
+        const order = topologicalOrder(graph);
+        for (const edge of graph.edges) {
+            if (!["next", "branch", "on_fail"].includes(edge.kind))
+                continue;
+            expect(order.indexOf(edge.from), `${edge.from} -> ${edge.to}`).toBeLessThan(order.indexOf(edge.to));
+        }
+    });
+    /*
+     * The shape the corpus does not have.
+     *
+     * Every fixture happens to write its undo after the step it undoes, so document order
+     * hides the defect and a sweep over them cannot fail. `std/k8s-node-not-ready-drain`
+     * writes it second, which is how the list came to open with "Uncordon the node". This
+     * is that record's shape, small enough to read.
+     */
+    it("reads an undo written before its action after it anyway", () => {
+        const graph = toGraph({
+            runbook: {
+                steps: [
+                    { id: "s1", kind: "check", title: "Confirm", expect: "ok", on_fail: "s9", next: "s2" },
+                    { id: "s5", kind: "action", title: "Undo it", risk: "reversible-write", next: "end:aborted" },
+                    { id: "s2", kind: "action", title: "Do it", risk: "destructive", rollback_ref: "s5", next: "end:success" },
+                    { id: "s9", kind: "escalate", title: "Escalate", to: "team:x" },
+                ],
+            },
+        });
+        const order = topologicalOrder(graph);
+        expect(order.indexOf("s5"), "the undo is read before the step it undoes").toBeGreaterThan(order.indexOf("s2"));
+    });
+    it("traverses every node of a graph whose steps roll each other back", () => {
+        // A malformed pair must not deadlock the traversal: keyboard navigation that skips a
+        // node is worse than an order that has to make an arbitrary choice.
+        const mutual = toGraph({
+            runbook: {
+                steps: [
+                    { id: "s1", kind: "action", title: "One", risk: "destructive", rollback_ref: "s2", next: "end:success" },
+                    { id: "s2", kind: "action", title: "Two", risk: "destructive", rollback_ref: "s1", next: "end:success" },
+                ],
+            },
+        });
+        const order = topologicalOrder(mutual);
+        expect(new Set(order).size).toBe(mutual.nodes.length);
+    });
+});

package/dist/model.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The graph model and its deterministic derivation from `steps[]`.
+ *
+ * One model, three consumers: the linter, the renderer, the editor (RUNBOOK.md 6). If
+ * the editor grows its own representation the two drift, and the constructor starts
+ * producing documents the linter rejects for reasons the editor cannot explain.
+ *
+ * No dependency on React, the DOM, or Node — this runs in a browser for the live editor
+ * and in the gate runner for linting.
+ */
+import type { Risk } from "@runbooks/schema";
+export type NodeKind = "start" | "check" | "action" | "decision" | "wait" | "escalate" | "end";
+export type EdgeKind = "next" | "branch" | "on_fail" | "rollback" | "approval" | "retry";
+export type EndOutcome = "success" | "failed" | "aborted";
+export interface GraphNode {
+    readonly id: string;
+    readonly kind: NodeKind;
+    readonly title: string;
+    readonly risk?: Risk;
+    readonly requiresApproval?: boolean;
+    /** `end` only. */
+    readonly outcome?: EndOutcome;
+    /** Nodes the derivation created rather than the author writing them. */
+    readonly synthetic?: boolean;
+    /**
+     * The step this node was derived from, carried verbatim.
+     *
+     * The graph is a view over the document, not a replacement for it: the source of
+     * truth is the parsed tree, not the picture (RUNBOOK.md 18.3). Carrying the step
+     * makes `graph -> steps[]` lossless by construction rather than by a field list
+     * somebody has to keep in sync — which is what the constructor's YAML/Graph toggle
+     * needs to be trustworthy, and an engineer is right not to trust an editor that
+     * loses what it did not think to model.
+     */
+    readonly step?: RawStep;
+}
+export interface GraphEdge {
+    readonly from: string;
+    readonly to: string;
+    readonly kind: EdgeKind;
+    /** Required on `branch` (the value from `branches`) and on `retry` (the limit). */
+    readonly label?: string;
+    /** `retry` only: the finite limit that makes the cycle legal (invariant 6). */
+    readonly max?: number;
+}
+export interface Graph {
+    readonly nodes: readonly GraphNode[];
+    readonly edges: readonly GraphEdge[];
+}
+export declare const START = "__start";
+export declare const end: (outcome: EndOutcome) => string;
+/** Nodes a graph cannot continue past (RUNBOOK.md 6). */
+export declare function isTerminal(kind: NodeKind): boolean;
+export interface RawStep {
+    id: string;
+    kind: Exclude<NodeKind, "start" | "end">;
+    title: string;
+    risk?: Risk;
+    /** The capability this step alone invokes. Scope is per step, never the union. */
+    tool?: string;
+    command?: string;
+    /** Machine-checkable postcondition. `expect` is prose for the reader; this is what an
+     *  R2 supervisor evaluates (docs/decisions/Q12-expect-evaluability.md). */
+    assert?: Record<string, unknown>;
+    requires_approval?: boolean;
+    rollback_ref?: string;
+    expect?: string;
+    on_fail?: string;
+    question?: string;
+    branches?: Record<string, string>;
+    /** `wait` only, and one of these forms is required: a bound is not optional, because
+     *  an unbounded wait is a hang with better manners. */
+    duration?: string;
+    until?: string;
+    timeout?: string;
+    retry?: {
+        max?: number;
+        target?: string;
+    };
+    next?: string;
+    to?: string;
+}
+export interface RunbookDocument {
+    runbook?: {
+        steps?: RawStep[];
+    };
+}
+/**
+ * `steps[] → graph`, deterministic: two implementations must produce the same graph
+ * from the same document, or the linter and the renderer disagree about what they are
+ * looking at.
+ *
+ * Ordering rule: nodes follow document order with the synthetic `start` first and
+ * synthetic `end` nodes last; edges follow the order they are derived per step. Nothing
+ * here sorts by id or by anything else — determinism comes from the document, so a
+ * reordering of `steps[]` is a real change and shows up as one.
+ */
+export declare function toGraph(doc: RunbookDocument): Graph;
+/**
+ * `graph -> steps[]`. Lossless because each node carries its source step; the graph
+ * adds a reading of the document, it does not replace it.
+ *
+ * Synthetic nodes (`start`, `end`) are dropped: they exist so that invariant 7 can be
+ * checked without a hole in the graph, and they have no representation in `steps[]`.
+ */
+export declare function fromGraph(g: Graph): RawStep[];

package/dist/model.js

@@ -0,0 +1,118 @@
+export const START = "__start";
+export const end = (outcome) => `__end_${outcome}`;
+/** Nodes a graph cannot continue past (RUNBOOK.md 6). */
+export function isTerminal(kind) {
+    return kind === "escalate" || kind === "end";
+}
+/**
+ * `steps[] → graph`, deterministic: two implementations must produce the same graph
+ * from the same document, or the linter and the renderer disagree about what they are
+ * looking at.
+ *
+ * Ordering rule: nodes follow document order with the synthetic `start` first and
+ * synthetic `end` nodes last; edges follow the order they are derived per step. Nothing
+ * here sorts by id or by anything else — determinism comes from the document, so a
+ * reordering of `steps[]` is a real change and shows up as one.
+ */
+export function toGraph(doc) {
+    const steps = doc.runbook?.steps ?? [];
+    const nodes = [
+        { id: START, kind: "start", title: "start", synthetic: true },
+    ];
+    const edges = [];
+    const known = new Set(steps.map((s) => s.id));
+    const endsUsed = new Set();
+    /** Steps whose every incoming transition passes an approval gate. Modelled on the
+     *  edges rather than as a self-loop on the node: a gate is a property of arriving at
+     *  a step, and a self-loop would be a cycle, which invariant 6 would then reject. */
+    const gated = new Set(steps.filter((s) => s.requires_approval === true).map((s) => s.id));
+    const target = (ref) => {
+        // `end:<outcome>` names an explicit terminal, `escalate:sN` and a bare id name a
+        // step. Anything else is dangling, and invariant 2 reports it against the id as
+        // written rather than silently dropping it.
+        if (ref.startsWith("end:")) {
+            const outcome = ref.slice("end:".length);
+            endsUsed.add(outcome);
+            return end(outcome);
+        }
+        return ref.startsWith("escalate:") ? ref.slice("escalate:".length) : ref;
+    };
+    /** Every arrival at a gated step carries the gate. */
+    const link = (from, to, kind, extra = {}) => {
+        edges.push({ from, to, kind, ...extra });
+        if (gated.has(to) && kind !== "approval" && kind !== "rollback") {
+            edges.push({ from, to, kind: "approval", label: "approval" });
+        }
+    };
+    if (steps.length > 0)
+        link(START, steps[0].id, "next");
+    for (const [i, step] of steps.entries()) {
+        nodes.push({
+            id: step.id,
+            kind: step.kind,
+            title: step.title,
+            ...(step.risk ? { risk: step.risk } : {}),
+            ...(step.requires_approval !== undefined
+                ? { requiresApproval: step.requires_approval }
+                : {}),
+            step,
+        });
+        if (step.rollback_ref && known.has(step.rollback_ref)) {
+            edges.push({ from: step.id, to: step.rollback_ref, kind: "rollback" });
+        }
+        if (step.on_fail) {
+            link(step.id, target(step.on_fail), "on_fail");
+        }
+        if (step.branches) {
+            for (const [label, to] of Object.entries(step.branches)) {
+                link(step.id, target(to), "branch", { label });
+            }
+        }
+        if (step.retry) {
+            edges.push({
+                from: step.id,
+                to: step.retry.target ?? step.id,
+                kind: "retry",
+                label: String(step.retry.max ?? ""),
+                ...(step.retry.max !== undefined ? { max: step.retry.max } : {}),
+            });
+        }
+        if (step.kind === "escalate")
+            continue;
+        // A step whose branches are its routes gets no fall-through. Reading the next step
+        // in file order as an edge would put a route in the graph that the author never
+        // wrote, and a supervisor may only take routes the document declares.
+        const next = step.next ? target(step.next) : step.branches ? undefined : steps[i + 1]?.id;
+        if (next) {
+            link(step.id, next, "next");
+        }
+        else if (!step.branches) {
+            // A step that runs off the end of the list terminates. Invariant 7 wants that
+            // explicit, so the derivation makes it explicit rather than leaving a hole.
+            endsUsed.add("success");
+            link(step.id, end("success"), "next");
+        }
+    }
+    for (const outcome of ["success", "failed", "aborted"]) {
+        if (endsUsed.has(outcome)) {
+            nodes.push({
+                id: end(outcome),
+                kind: "end",
+                title: outcome,
+                outcome,
+                synthetic: true,
+            });
+        }
+    }
+    return { nodes, edges };
+}
+/**
+ * `graph -> steps[]`. Lossless because each node carries its source step; the graph
+ * adds a reading of the document, it does not replace it.
+ *
+ * Synthetic nodes (`start`, `end`) are dropped: they exist so that invariant 7 can be
+ * checked without a hole in the graph, and they have no representation in `steps[]`.
+ */
+export function fromGraph(g) {
+    return g.nodes.filter((n) => !n.synthetic && n.step).map((n) => n.step);
+}

package/dist/paths.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Path enumeration (P-07, §6).
+ *
+ * What simulation (W-15), the mini-graph silhouette (§18.5) and keyboard navigation
+ * (§18.2) will be built from, and what invariant 1 is built on today: reachability had
+ * two implementations — the same sweep written twice, agreeing until the next person
+ * changed what counts as an edge in one of them.
+ *
+ * The other consumers do not exist yet. `layout.ts` keeps its own `happyPath`, which is a
+ * different question — the single vertical axis a layout is arranged around, not the set
+ * of routes a run can take — and `topologicalOrder` stays there for the same reason. When
+ * W-15 arrives it uses these rather than walking again; until then this file has exactly
+ * one caller and says so.
+ */
+import { type Graph } from "./model.js";
+/** Every node reachable from a starting point, in the order first reached. */
+export declare function reachableFrom(graph: Graph, from?: string): string[];
+/** Nodes no path from the start can arrive at. Invariant 1 blocks on these; §18 highlights them. */
+export declare function unreachable(graph: Graph): string[];
+export interface PathOptions {
+    /** Edge kinds to follow. Omitted means all of them. */
+    readonly kinds?: readonly string[];
+    /**
+     * How many times one node may appear on a path. Two, by default: a bounded retry is a
+     * legal cycle (invariant 6), and a path that may not revisit anything cannot express
+     * one — while a path that may revisit freely never terminates.
+     */
+    readonly maxVisits?: number;
+    /** A ceiling on how many paths are returned, so a wide graph cannot hang a caller. */
+    readonly limit?: number;
+}
+/**
+ * Every path from a node to a terminal.
+ *
+ * Depth-first with a visit budget rather than a visited set, because a legal retry means
+ * a node genuinely appears twice on a real run and a simulation that could not express
+ * that would be simulating a different procedure.
+ */
+export declare function allPathsTo(graph: Graph, from?: string, options?: PathOptions): string[][];
+/**
+ * The paths a run can take without anything going wrong: forward edges only.
+ *
+ * `happyPath` gives the single vertical axis a layout is built around; this gives every
+ * branch of it, which is what a reader comparing variants and a simulation stepping
+ * through choices both need.
+ */
+export declare function successPaths(graph: Graph): string[][];

package/dist/paths.js

@@ -0,0 +1,84 @@
+/**
+ * Path enumeration (P-07, §6).
+ *
+ * What simulation (W-15), the mini-graph silhouette (§18.5) and keyboard navigation
+ * (§18.2) will be built from, and what invariant 1 is built on today: reachability had
+ * two implementations — the same sweep written twice, agreeing until the next person
+ * changed what counts as an edge in one of them.
+ *
+ * The other consumers do not exist yet. `layout.ts` keeps its own `happyPath`, which is a
+ * different question — the single vertical axis a layout is arranged around, not the set
+ * of routes a run can take — and `topologicalOrder` stays there for the same reason. When
+ * W-15 arrives it uses these rather than walking again; until then this file has exactly
+ * one caller and says so.
+ */
+import { isTerminal, START } from "./model.js";
+/** Every node reachable from a starting point, in the order first reached. */
+export function reachableFrom(graph, from = START) {
+    const seen = new Set();
+    const order = [];
+    const queue = [from];
+    while (queue.length > 0) {
+        const id = queue.shift();
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        order.push(id);
+        for (const edge of graph.edges.filter((e) => e.from === id))
+            queue.push(edge.to);
+    }
+    return order;
+}
+/** Nodes no path from the start can arrive at. Invariant 1 blocks on these; §18 highlights them. */
+export function unreachable(graph) {
+    const reached = new Set(reachableFrom(graph));
+    return graph.nodes.filter((node) => !reached.has(node.id)).map((node) => node.id);
+}
+/**
+ * Every path from a node to a terminal.
+ *
+ * Depth-first with a visit budget rather than a visited set, because a legal retry means
+ * a node genuinely appears twice on a real run and a simulation that could not express
+ * that would be simulating a different procedure.
+ */
+export function allPathsTo(graph, from = START, options = {}) {
+    const maxVisits = options.maxVisits ?? 2;
+    const limit = options.limit ?? 256;
+    const kinds = options.kinds;
+    const paths = [];
+    const walk = (id, path, visits) => {
+        if (paths.length >= limit)
+            return;
+        const next = [...path, id];
+        const node = graph.nodes.find((n) => n.id === id);
+        if (node && isTerminal(node.kind)) {
+            paths.push(next);
+            return;
+        }
+        const outgoing = graph.edges.filter((edge) => edge.from === id && (!kinds || kinds.includes(edge.kind)));
+        if (outgoing.length === 0) {
+            // Running out of edges is not reaching a terminal. Invariant 7 blocks on it; a
+            // caller enumerating paths should see where it happened rather than nothing.
+            paths.push(next);
+            return;
+        }
+        for (const edge of outgoing) {
+            const used = visits.get(edge.to) ?? 0;
+            if (used >= maxVisits)
+                continue;
+            walk(edge.to, next, new Map(visits).set(edge.to, used + 1));
+        }
+    };
+    walk(from, [], new Map([[from, 1]]));
+    return paths;
+}
+/**
+ * The paths a run can take without anything going wrong: forward edges only.
+ *
+ * `happyPath` gives the single vertical axis a layout is built around; this gives every
+ * branch of it, which is what a reader comparing variants and a simulation stepping
+ * through choices both need.
+ */
+export function successPaths(graph) {
+    return allPathsTo(graph, START, { kinds: ["next", "branch", "approval"] });
+}

package/dist/paths.test.d.ts

@@ -0,0 +1 @@
+export {};