@coldtea/pr-lens-schema 0.1.3 → 0.2.1

package/dist/walkthrough.js

@@ -0,0 +1,95 @@
+import { assertNever } from "./utils.js";
+const NOTHING = new Set();
+export const indexViews = (views) => new Map(views.flatMap((view) => [[view.id, view], ...indexViews(view.children)]));
+const messageIdsOf = (flows) => new Set(flows.flatMap((flow) => flow.messages.map((message) => message.id)));
+export const stagedMessages = (stage, flows, views) => {
+    if (stage === undefined)
+        return { kind: "no-stage" };
+    switch (stage.kind) {
+        case "flow": {
+            const flow = flows.find(({ id }) => id === stage.flow);
+            return flow === undefined
+                ? { kind: "unknown-stage" }
+                : { kind: "messages", ids: messageIdsOf([flow]) };
+        }
+        case "view": {
+            const view = views.get(stage.view);
+            if (view === undefined)
+                return { kind: "unknown-stage" };
+            switch (view.scope.kind) {
+                case "all":
+                    return { kind: "messages", ids: messageIdsOf(flows) };
+                case "selection": {
+                    const scoped = view.scope.flows;
+                    return {
+                        kind: "messages",
+                        ids: messageIdsOf(flows.filter((flow) => scoped.includes(flow.id))),
+                    };
+                }
+                default:
+                    return assertNever(view.scope, "Unhandled view scope");
+            }
+        }
+        default:
+            return assertNever(stage, "Unhandled step stage");
+    }
+};
+const stageSurvives = (stage, flows, views) => {
+    switch (stage.kind) {
+        case "view":
+            return views.has(stage.view);
+        case "flow":
+            return flows.has(stage.flow);
+        default:
+            return assertNever(stage, "Unhandled step stage");
+    }
+};
+const focusable = (staged) => {
+    switch (staged.kind) {
+        case "messages":
+            return staged.ids;
+        case "no-stage":
+        case "unknown-stage":
+            return NOTHING;
+        default:
+            return assertNever(staged, "Unhandled staged messages");
+    }
+};
+/**
+ * A step that loses the last element it focused is dropped rather than left
+ * to widen into a step about everything. A tour of one step is a caption, so
+ * a walkthrough cut below two steps goes whole.
+ */
+export const pruneWalkthrough = (walkthrough, subject) => {
+    if (walkthrough === undefined)
+        return undefined;
+    const lanes = new Set(subject.lanes.map((lane) => lane.id));
+    const nodes = new Set(subject.nodes.map((node) => node.id));
+    const edges = new Set(subject.edges.map((edge) => edge.id));
+    const flows = new Set(subject.flows.map((flow) => flow.id));
+    const views = indexViews(subject.views);
+    const steps = walkthrough.steps.flatMap((step) => {
+        if (step.stage !== undefined && !stageSurvives(step.stage, flows, views))
+            return [];
+        switch (step.focus.kind) {
+            case "all":
+                return [step];
+            case "selection": {
+                const onStage = focusable(stagedMessages(step.stage, subject.flows, views));
+                const focus = {
+                    kind: "selection",
+                    lanes: step.focus.lanes.filter((id) => lanes.has(id)),
+                    nodes: step.focus.nodes.filter((id) => nodes.has(id)),
+                    edges: step.focus.edges.filter((id) => edges.has(id)),
+                    messages: step.focus.messages.filter((id) => onStage.has(id)),
+                };
+                const focused = focus.lanes.length + focus.nodes.length + focus.edges.length + focus.messages.length;
+                return focused === 0 ? [] : [{ ...step, focus }];
+            }
+            default:
+                return assertNever(step.focus, "Unhandled step focus");
+        }
+    });
+    return steps.length < 2 ? undefined : { ...walkthrough, steps };
+};
+//# sourceMappingURL=walkthrough.js.map

package/dist/walkthrough.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"walkthrough.js","sourceRoot":"","sources":["../src/walkthrough.ts"],"names":[],"mappings":"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"}

package/examples/broadcast-baseline.graph.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "0.1.0",
+  "schemaVersion": "0.1.1",
   "kind": "graph",
   "id": "bestregards-broadcast-baseline",
   "generatedAt": "2026-08-12T09:02:00.000Z",

package/examples/broadcast-baseline.patch.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "0.1.0",
+  "schemaVersion": "0.1.1",
   "kind": "patch",
   "generatedAt": "2026-08-19T18:31:00.000Z",
   "summary": "Fold the batch send path into the baseline map and retire the single-send path.",

package/examples/minimal.graph.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "0.1.0",
+  "schemaVersion": "0.1.1",
   "kind": "graph",
   "title": "Touch the health check",
   "lenses": [

package/examples/postmark-refactor.graph.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "0.1.0",
+  "schemaVersion": "0.1.1",
   "kind": "graph",
   "generatedAt": "2026-08-19T18:24:00.000Z",
   "title": "Batch broadcast sending through Postmark",
@@ -564,6 +564,111 @@
       "children": []
     }
   ],
+  "walkthrough": {
+    "steps": [
+      {
+        "id": "batches-of-500",
+        "heading": "sendBroadcastBulk and buildBulkPayload added",
+        "body": "Nothing loops over recipients any more. The sender works on a whole batch at a time.",
+        "stage": {
+          "kind": "view",
+          "view": "overview"
+        },
+        "focus": {
+          "kind": "selection",
+          "lanes": [],
+          "nodes": [
+            "send-broadcast-bulk",
+            "build-bulk-payload",
+            "postmark"
+          ],
+          "edges": [],
+          "messages": []
+        }
+      },
+      {
+        "id": "suppression-first",
+        "heading": "getSuppressedEmails added before the send",
+        "body": "It pulls the blocked addresses once, before any batch is built.",
+        "stage": {
+          "kind": "view",
+          "view": "new-batch-path"
+        },
+        "focus": {
+          "kind": "selection",
+          "lanes": [],
+          "nodes": [
+            "get-suppressed-emails",
+            "postmark"
+          ],
+          "edges": [],
+          "messages": []
+        }
+      },
+      {
+        "id": "old-path-goes-dark",
+        "heading": "processBroadcast and sendSingleEmail removed",
+        "body": "sendBroadcastBulk does their job for whole batches.",
+        "stage": {
+          "kind": "view",
+          "view": "overview"
+        },
+        "focus": {
+          "kind": "selection",
+          "lanes": [],
+          "nodes": [
+            "process-broadcast",
+            "send-single-email"
+          ],
+          "edges": [],
+          "messages": []
+        }
+      },
+      {
+        "id": "sequence-start-to-finish",
+        "heading": "The send sequence gained 6 new steps",
+        "body": "The queue write is the only step that was there before, and it now stamps the batch size.",
+        "stage": {
+          "kind": "flow",
+          "flow": "send-pipeline"
+        },
+        "focus": {
+          "kind": "all"
+        }
+      },
+      {
+        "id": "four-batch-calls",
+        "heading": "Postmark now gets 500 emails per call",
+        "body": "One call per batch, and Postmark answers with a result for each message.",
+        "stage": {
+          "kind": "flow",
+          "flow": "send-pipeline"
+        },
+        "focus": {
+          "kind": "selection",
+          "lanes": [],
+          "nodes": [],
+          "edges": [],
+          "messages": [
+            "batch-post",
+            "batch-results"
+          ]
+        }
+      },
+      {
+        "id": "blast-radius",
+        "heading": "4 parts added, 2 removed, across 3 lanes",
+        "body": "A 2,000-person broadcast used to make 2,000 calls to Postmark. It now makes 4.",
+        "stage": {
+          "kind": "view",
+          "view": "overview"
+        },
+        "focus": {
+          "kind": "all"
+        }
+      }
+    ]
+  },
   "layout": {
     "direction": "right",
     "laneOrder": [

package/examples/postmark-refactor.render-manifest.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "0.1.0",
+  "schemaVersion": "0.1.1",
   "kind": "render-manifest",
   "generatedAt": "2026-08-19T18:32:10.000Z",
   "graph": {

package/examples/pr-lens.config.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "0.1.0",
+  "schemaVersion": "0.1.1",
   "lenses": [
     "architecture",
     "data-flow"

package/json-schema/config.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://raw.githubusercontent.com/coldteadotai/pr-lens/main/packages/schema/json-schema/config.schema.json",
   "title": "PR Lens repository config",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "object",
   "properties": {
     "schemaVersion": {

package/json-schema/graph-doc.schema.json

@@ -2,13 +2,13 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://raw.githubusercontent.com/coldteadotai/pr-lens/main/packages/schema/json-schema/graph-doc.schema.json",
   "title": "PR Lens graph document",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "object",
   "properties": {
     "schemaVersion": {
       "type": "string",
       "pattern": "^0\\.1\\.\\d+$",
-      "description": "Contract version the document targets. Current: 0.1.0."
+      "description": "Contract version the document targets. Current: 0.1.1."
     },
     "kind": {
       "type": "string",
@@ -795,6 +795,225 @@
         "$ref": "#/$defs/View"
       }
     },
+    "walkthrough": {
+      "type": "object",
+      "properties": {
+        "steps": {
+          "minItems": 2,
+          "maxItems": 12,
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 128,
+                "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]*$",
+                "description": "Stable identifier, unique within its collection in a document."
+              },
+              "heading": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 48,
+                "description": "A step heading. Short enough to read at a glance."
+              },
+              "body": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 140,
+                "description": "A single line under a step heading."
+              },
+              "stage": {
+                "oneOf": [
+                  {
+                    "type": "object",
+                    "properties": {
+                      "kind": {
+                        "type": "string",
+                        "const": "view"
+                      },
+                      "view": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 128,
+                        "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]*$",
+                        "description": "Id of the drill-down view to draw."
+                      }
+                    },
+                    "required": [
+                      "kind",
+                      "view"
+                    ],
+                    "additionalProperties": false
+                  },
+                  {
+                    "type": "object",
+                    "properties": {
+                      "kind": {
+                        "type": "string",
+                        "const": "flow"
+                      },
+                      "flow": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 128,
+                        "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]*$",
+                        "description": "Id of the flow to draw."
+                      }
+                    },
+                    "required": [
+                      "kind",
+                      "flow"
+                    ],
+                    "additionalProperties": false
+                  }
+                ],
+                "description": "Which diagram a walkthrough step plays over."
+              },
+              "focus": {
+                "default": {
+                  "kind": "all"
+                },
+                "oneOf": [
+                  {
+                    "type": "object",
+                    "properties": {
+                      "kind": {
+                        "type": "string",
+                        "const": "all"
+                      }
+                    },
+                    "required": [
+                      "kind"
+                    ],
+                    "additionalProperties": false
+                  },
+                  {
+                    "type": "object",
+                    "properties": {
+                      "kind": {
+                        "type": "string",
+                        "const": "selection"
+                      },
+                      "lanes": {
+                        "default": [],
+                        "maxItems": 64,
+                        "type": "array",
+                        "items": {
+                          "type": "string",
+                          "minLength": 1,
+                          "maxLength": 128,
+                          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]*$",
+                          "description": "Stable identifier, unique within its collection in a document."
+                        }
+                      },
+                      "nodes": {
+                        "default": [],
+                        "maxItems": 256,
+                        "type": "array",
+                        "items": {
+                          "type": "string",
+                          "minLength": 1,
+                          "maxLength": 128,
+                          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]*$",
+                          "description": "Stable identifier, unique within its collection in a document."
+                        }
+                      },
+                      "edges": {
+                        "default": [],
+                        "maxItems": 512,
+                        "type": "array",
+                        "items": {
+                          "type": "string",
+                          "minLength": 1,
+                          "maxLength": 128,
+                          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]*$",
+                          "description": "Stable identifier, unique within its collection in a document."
+                        }
+                      },
+                      "messages": {
+                        "default": [],
+                        "description": "Steps of the flow on the stage.",
+                        "maxItems": 64,
+                        "type": "array",
+                        "items": {
+                          "type": "string",
+                          "minLength": 1,
+                          "maxLength": 128,
+                          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]*$",
+                          "description": "Stable identifier, unique within its collection in a document."
+                        }
+                      }
+                    },
+                    "required": [
+                      "kind"
+                    ],
+                    "additionalProperties": false,
+                    "anyOf": [
+                      {
+                        "properties": {
+                          "lanes": {
+                            "minItems": 1
+                          }
+                        },
+                        "required": [
+                          "lanes"
+                        ]
+                      },
+                      {
+                        "properties": {
+                          "nodes": {
+                            "minItems": 1
+                          }
+                        },
+                        "required": [
+                          "nodes"
+                        ]
+                      },
+                      {
+                        "properties": {
+                          "edges": {
+                            "minItems": 1
+                          }
+                        },
+                        "required": [
+                          "edges"
+                        ]
+                      },
+                      {
+                        "properties": {
+                          "messages": {
+                            "minItems": 1
+                          }
+                        },
+                        "required": [
+                          "messages"
+                        ]
+                      }
+                    ]
+                  }
+                ],
+                "description": "What stays lit while a walkthrough step plays."
+              }
+            },
+            "required": [
+              "id",
+              "heading",
+              "body"
+            ],
+            "additionalProperties": false,
+            "description": "One stop on the walkthrough: a heading, a line under it, and the part of one diagram it is about."
+          },
+          "description": "Ordered by array position."
+        }
+      },
+      "required": [
+        "steps"
+      ],
+      "additionalProperties": false,
+      "description": "An ordered tour of this document's diagrams."
+    },
     "layout": {
       "type": "object",
       "properties": {

package/json-schema/patch-doc.schema.json

@@ -2,13 +2,13 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://raw.githubusercontent.com/coldteadotai/pr-lens/main/packages/schema/json-schema/patch-doc.schema.json",
   "title": "PR Lens patch document",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "object",
   "properties": {
     "schemaVersion": {
       "type": "string",
       "pattern": "^0\\.1\\.\\d+$",
-      "description": "Contract version the document targets. Current: 0.1.0."
+      "description": "Contract version the document targets. Current: 0.1.1."
     },
     "kind": {
       "type": "string",

package/json-schema/render-manifest.schema.json

@@ -2,13 +2,13 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://raw.githubusercontent.com/coldteadotai/pr-lens/main/packages/schema/json-schema/render-manifest.schema.json",
   "title": "PR Lens render manifest",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "object",
   "properties": {
     "schemaVersion": {
       "type": "string",
       "pattern": "^0\\.1\\.\\d+$",
-      "description": "Contract version the document targets. Current: 0.1.0."
+      "description": "Contract version the document targets. Current: 0.1.1."
     },
     "kind": {
       "type": "string",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coldtea/pr-lens-schema",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "The PR Lens contract: versioned schemas for architecture / data-flow graph documents, baseline patches, config and render manifests.",
   "license": "MIT",
   "author": "Coldtea AI",
@@ -46,13 +46,6 @@
   "engines": {
     "node": ">=20.11"
   },
-  "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json && pnpm run schema:emit",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "schema:emit": "tsx scripts/emit-artifacts.ts",
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
   "dependencies": {
     "zod": "^4.4.3"
   },
@@ -62,5 +55,12 @@
     "tsx": "4.23.12",
     "typescript": "7.0.2",
     "vitest": "4.1.11"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && pnpm run schema:emit",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "schema:emit": "tsx scripts/emit-artifacts.ts",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
-}
+}

package/src/apply.ts

@@ -4,6 +4,7 @@ import type { Flow, GraphDoc, GraphEdge, Lane, View } from "./graph.js";
 import { graphSnapshotIssues } from "./integrity.js";
 import { targetDescribesATransition, type PatchDoc, type PatchOp } from "./patch.js";
 import { assertNever } from "./utils.js";
+import { pruneWalkthrough } from "./walkthrough.js";
 
 type Collections = {
   lanes: Lane[];
@@ -298,6 +299,20 @@ export const applyPatch = (graph: GraphDoc, ops: readonly PatchOp[]): Parsed<Gra
     }
   }
 
+  /**
+   * The tour is pruned once, against the document the operations produced,
+   * rather than alongside each removal. A step names a diagram as well as
+   * elements, and an operation that rewrites a flow's steps takes members
+   * away without removing anything the other prunes would notice.
+   */
+  const walkthrough = pruneWalkthrough(graph.walkthrough, {
+    lanes: working.lanes,
+    nodes: working.nodes,
+    edges: working.edges,
+    flows: working.flows,
+    views,
+  });
+
   return safeParseGraphDoc({
     ...graph,
     lanes: working.lanes,
@@ -306,6 +321,7 @@ export const applyPatch = (graph: GraphDoc, ops: readonly PatchOp[]): Parsed<Gra
     flows: working.flows,
     stats: working.stats,
     views,
+    walkthrough,
     layout,
   });
 };