@runbooks/graph 0.1.0

package/dist/subgraph.test.js

@@ -0,0 +1,127 @@
+import { describe, it, expect } from "vitest";
+import { isDangerous, RISK_ORDER } from "@runbooks/schema";
+import { aggregate, decomposition, childrenOf, overCap, NODE_CAP, MAX_ROLLUP_DEPTH, } from "./subgraph.js";
+const record = (ref, steps, relations = [], capabilities = []) => ({
+    ref,
+    document: { runbook: { steps, relations, capabilities } },
+});
+const parent = record("std/drain", [
+    { id: "s1", kind: "check", title: "Look", risk: "read-only", next: "s2" },
+    { id: "s2", kind: "action", title: "Prepare", risk: "reversible-write", next: "s3" },
+    { id: "s3", kind: "action", title: "Finish", risk: "read-only", next: "end:success" },
+], [], ["cli:kubectl"]);
+const child = record("std/prepare", [
+    { id: "c1", kind: "check", title: "Check", risk: "read-only", next: "c2" },
+    { id: "c2", kind: "action", title: "Cordon", risk: "reversible-write", next: "end:success" },
+], [{ kind: "part_of", ref: "std/drain", step: "s2" }], ["cli:kubectl"]);
+const dangerousGrandchild = record("std/wipe", [{ id: "g1", kind: "action", title: "Wipe", risk: "irreversible", next: "end:success" }], [{ kind: "part_of", ref: "std/prepare", step: "c2" }], ["cli:rm"]);
+const world = [parent, child, dangerousGrandchild];
+/** "A collapsed subgraph containing a destructive step is visibly marked as containing one." */
+describe("nothing dangerous is hidden by collapsing", () => {
+    it("rolls the worst risk up from a grandchild", () => {
+        const summary = aggregate(child, "std/drain", world);
+        expect(summary.highestRisk).toBe("irreversible");
+        expect(summary.containsDangerous).toBe(true);
+    });
+    it("says so on the collapsed node, not on the page you would have to open", () => {
+        const [line] = decomposition(parent, world);
+        expect(line.containsDangerous).toBe(true);
+        expect(line.highestRisk).toBe("irreversible");
+    });
+    it("is not dangerous when nothing inside is", () => {
+        const summary = aggregate(child, "std/drain", [parent, child]);
+        expect(summary.highestRisk).toBe("reversible-write");
+        expect(summary.containsDangerous).toBe(false);
+    });
+    /**
+     * Two of the four risks are exercised above. The mark comes from `isDangerous`, and a
+     * collapsed subgraph is the one place a reader cannot look inside — so ask it about
+     * each risk there is, not about the two this world happens to contain.
+     */
+    it.each(RISK_ORDER)("marks a hidden %s step if and only if the spec calls it dangerous", (risk) => {
+        const hidden = record("std/hidden", [{ id: "h1", kind: "action", title: "Do it", risk, next: "end:success" }], [{ kind: "part_of", ref: "std/prepare", step: "c2" }]);
+        const summary = aggregate(child, "std/drain", [parent, child, hidden]);
+        expect(summary.containsDangerous).toBe(isDangerous(risk));
+    });
+    it("counts every node inside, including the ones two levels down", () => {
+        expect(aggregate(child, "std/drain", world).nodes).toBe(3);
+    });
+    it("unions the capabilities, because granting the parent grants all of them", () => {
+        expect(aggregate(child, "std/drain", world).capabilities).toEqual(["cli:kubectl", "cli:rm"]);
+    });
+});
+/** Displayed depth is one; aggregation depth is not. */
+describe("what is shown stays small and what is summarised stays complete", () => {
+    it("lists direct children only", () => {
+        expect(decomposition(parent, world).map((line) => line.ref)).toEqual(["std/prepare"]);
+    });
+    it("reports how deep the summary actually went", () => {
+        expect(decomposition(parent, world)[0].depth).toBe(2);
+    });
+    it("orders children by the parent's own steps, so a keyboard walks the procedure", () => {
+        const second = record("std/finish-detail", [{ id: "f1", kind: "check", title: "Check", risk: "read-only", next: "end:success" }], [{ kind: "part_of", ref: "std/drain", step: "s3" }]);
+        const first = record("std/look-detail", [{ id: "l1", kind: "check", title: "Check", risk: "read-only", next: "end:success" }], [{ kind: "part_of", ref: "std/drain", step: "s1" }]);
+        const order = decomposition(parent, [parent, second, first, child]).map((line) => line.step);
+        expect(order).toEqual(["s1", "s2", "s3"]);
+    });
+    it("names which step each child expands", () => {
+        expect(decomposition(parent, world)[0].step).toBe("s2");
+    });
+    it("finds the children that declare themselves part of a record", () => {
+        expect(childrenOf("std/drain", world).map((r) => r.ref)).toEqual(["std/prepare"]);
+        expect(childrenOf("std/prepare", world).map((r) => r.ref)).toEqual(["std/wipe"]);
+    });
+});
+/** A cycle here means the catalog moved underneath us; hanging would be the worse answer. */
+describe("a malformed decomposition terminates and says so", () => {
+    it("stops on a part_of cycle rather than recursing", () => {
+        const a = record("std/a", [{ id: "a1", kind: "check", title: "A", next: "end:success" }], [
+            { kind: "part_of", ref: "std/b", step: "b1" },
+        ]);
+        const b = record("std/b", [{ id: "b1", kind: "check", title: "B", next: "end:success" }], [
+            { kind: "part_of", ref: "std/a", step: "a1" },
+        ]);
+        const summary = aggregate(a, "std/b", [a, b]);
+        expect(summary.truncated).toMatch(/already on this path/);
+    });
+    it("has a stated depth limit rather than an implicit one", () => {
+        expect(MAX_ROLLUP_DEPTH).toBeGreaterThan(4);
+    });
+});
+/** §18.6 rule 2, as a question about one record. */
+describe("the twelve-node cap", () => {
+    const big = record("std/long", Array.from({ length: NODE_CAP + 2 }, (_, i) => ({
+        id: `s${i}`,
+        kind: "check",
+        title: `Step ${i}`,
+        risk: "read-only",
+        next: i === NODE_CAP + 1 ? "end:success" : `s${i + 1}`,
+    })));
+    it("notices a graph over the cap with nothing decomposed out of it", () => {
+        expect(overCap(big, [big])).toBe(true);
+    });
+    it("is satisfied by a decomposition rather than by shortening the procedure", () => {
+        const part = record("std/long-part", [{ id: "p1", kind: "check", title: "Part", next: "end:success" }], [{ kind: "part_of", ref: "std/long", step: "s0" }]);
+        expect(overCap(big, [big, part])).toBe(false);
+    });
+    it("leaves a small graph alone", () => {
+        expect(overCap(parent, world)).toBe(false);
+    });
+});
+/**
+ * Q7's answer, as a property of the code: there is no expansion. What the parent has is a
+ * summary and a link, and both are computed rather than typed by an author.
+ */
+describe("nothing expands in place", () => {
+    it("summarises rather than returning the child's graph", () => {
+        const summary = aggregate(child, "std/drain", world);
+        expect(Object.keys(summary).sort()).toEqual([
+            "capabilities", "containsDangerous", "depth", "highestRisk", "nodes", "ref", "step",
+        ]);
+        expect(summary).not.toHaveProperty("graph");
+        expect(summary).not.toHaveProperty("nodesList");
+    });
+    it("gives a reader the child's own address, since it is a record", () => {
+        expect(decomposition(parent, world)[0].ref).toBe("std/prepare");
+    });
+});

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@runbooks/graph",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "Graph model, the seven blocking invariants, and layered layout.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@runbooks/schema": "^0.1.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/runbooks-directory/runbooks.directory"
+  },
+  "engines": {
+    "node": ">=20.11"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "test": "vitest run --passWithNoTests",
+    "lint": "eslint src"
+  }
+}