@coldtea/pr-lens-schema 0.1.3 → 0.2.1

package/src/examples/postmark-refactor.ts

@@ -8,7 +8,8 @@ import { SCHEMA_VERSION } from "../version.js";
  * refactor: broadcast sending moved from one Postmark request per recipient
  * to batched requests of 500, behind a shared library. Every downstream
  * renderer golden is measured against this document, so it exercises all
- * four delta states, a hero edge, and a full data-flow sequence.
+ * four delta states, a hero edge, a full data-flow sequence, and a
+ * walkthrough that stages both a drill-down view and a flow.
  */
 export const postmarkRefactorGraphInput: GraphDocInput = {
   schemaVersion: SCHEMA_VERSION,
@@ -393,6 +394,55 @@ export const postmarkRefactorGraphInput: GraphDocInput = {
       scope: { kind: "selection", flows: ["send-pipeline"] },
     },
   ],
+  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",
+          nodes: ["send-broadcast-bulk", "build-bulk-payload", "postmark"],
+        },
+      },
+      {
+        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", nodes: ["get-suppressed-emails", "postmark"] },
+      },
+      {
+        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", nodes: ["process-broadcast", "send-single-email"] },
+      },
+      {
+        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", 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: ["web", "functions", "external"],

package/src/graph.ts

@@ -1,5 +1,16 @@
 import { z } from "zod";
-import { Delta, FileRef, Id, Label, Lens, SchemaVersionField, Sha, Summary } from "./primitives.js";
+import {
+  Beat,
+  Delta,
+  FileRef,
+  Id,
+  Label,
+  Lens,
+  Line,
+  SchemaVersionField,
+  Sha,
+  Summary,
+} from "./primitives.js";
 
 /**
  * Coarse on purpose: this drives the card icon and shape, never analysis.
@@ -255,6 +266,92 @@ export const View: z.ZodType<View, ViewInput> = z.lazy(() =>
     .describe("A drill-down section; children nest as further <details> blocks."),
 );
 
+/**
+ * The picture a step plays over: one of the document's drill-down views, or
+ * one of its flows drawn on its own.
+ *
+ * Leaving it out means the picture the reader is already looking at. Which
+ * one that is belongs to the surface showing the document, not to the
+ * contract, so the contract says nothing about it.
+ */
+export const StepStage = z
+  .discriminatedUnion("kind", [
+    z.strictObject({
+      kind: z.literal("view"),
+      view: Id.describe("Id of the drill-down view to draw."),
+    }),
+    z.strictObject({
+      kind: z.literal("flow"),
+      flow: Id.describe("Id of the flow to draw."),
+    }),
+  ])
+  .describe("Which diagram a walkthrough step plays over.");
+export type StepStage = z.infer<typeof StepStage>;
+
+/**
+ * What a step points at inside its stage. The same two states a view scope
+ * has, and for the same reason: a step that loses the last element it named
+ * must never quietly become a step about everything.
+ *
+ * `messages` names steps of a flow, so it only means anything when the stage
+ * draws that flow. That pairing is the parser's to check.
+ */
+export const StepFocus = z
+  .discriminatedUnion("kind", [
+    z.strictObject({ kind: z.literal("all") }),
+    z
+      .strictObject({
+        kind: z.literal("selection"),
+        lanes: z.array(Id).max(64).default([]),
+        nodes: z.array(Id).max(256).default([]),
+        edges: z.array(Id).max(512).default([]),
+        messages: z.array(Id).max(64).default([]).describe("Steps of the flow on the stage."),
+      })
+      .meta({
+        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"] },
+        ],
+      })
+      .refine(
+        (focus) =>
+          focus.lanes.length + focus.nodes.length + focus.edges.length + focus.messages.length > 0,
+        { message: "a selection must name at least one element" },
+      ),
+  ])
+  .describe("What stays lit while a walkthrough step plays.");
+export type StepFocus = z.infer<typeof StepFocus>;
+
+export const WalkthroughStep = z
+  .strictObject({
+    id: Id,
+    heading: Beat,
+    body: Line,
+    stage: StepStage.optional(),
+    focus: StepFocus.default({ kind: "all" }),
+  })
+  .describe(
+    "One stop on the walkthrough: a heading, a line under it, and the part of one diagram it is about.",
+  );
+export type WalkthroughStep = z.infer<typeof WalkthroughStep>;
+
+/**
+ * An ordered tour of the document's diagrams, authored alongside them.
+ *
+ * Two steps is the floor because one step is a caption, and twelve is the
+ * ceiling because a reader scrolling a rail loses the thread long before
+ * that. A document that carries one has already decided what a reader should
+ * see first; a surface playing it only reads.
+ */
+export const Walkthrough = z
+  .strictObject({
+    steps: z.array(WalkthroughStep).min(2).max(12).describe("Ordered by array position."),
+  })
+  .describe("An ordered tour of this document's diagrams.");
+export type Walkthrough = z.infer<typeof Walkthrough>;
+
 /**
  * Hints, not instructions: the renderer owns final placement so that layout
  * stays deterministic for a given document. A hint is a floor rather than an
@@ -324,6 +421,7 @@ export const GraphDoc = z
     flows: z.array(Flow).max(16).default([]),
     stats: Stats.optional(),
     views: z.array(View).max(32).default([]),
+    walkthrough: Walkthrough.optional(),
     layout: LayoutHints.optional(),
   })
   .describe("A PR Lens graph document.");

package/src/index.ts

@@ -1,6 +1,7 @@
 export { SCHEMA_VERSION, type SchemaVersion } from "./version.js";
 
 export {
+  Beat,
   Delta,
   DELTAS,
   FileRef,
@@ -9,6 +10,7 @@ export {
   Label,
   Lens,
   LENSES,
+  Line,
   MAX_RENDER_ASSETS,
   MAX_VIEWS,
   Theme,
@@ -34,8 +36,12 @@ export {
   Provenance,
   StatChip,
   Stats,
+  StepFocus,
+  StepStage,
   View,
   ViewScope,
+  Walkthrough,
+  WalkthroughStep,
   type GraphDocInput,
   type ViewInput,
 } from "./graph.js";
@@ -79,4 +85,6 @@ export {
 
 export { applyPatch, applyPatchDoc } from "./apply.js";
 
+export { pruneWalkthrough, type WalkthroughSubject } from "./walkthrough.js";
+
 export { assertNever } from "./utils.js";

package/src/integrity.ts

@@ -2,6 +2,7 @@ import type { SchemaIssue } from "./errors.js";
 import type { GraphDoc, View } from "./graph.js";
 import { FullSha, MAX_VIEWS, THEMES, type Delta } from "./primitives.js";
 import { assertNever } from "./utils.js";
+import { indexViews, stagedMessages } from "./walkthrough.js";
 
 const duplicates = (ids: readonly string[]): string[] => {
   const seen = new Set<string>();
@@ -135,6 +136,82 @@ export const graphIntegrityIssues = (doc: GraphDoc): SchemaIssue[] => {
     }
   }
 
+  if (doc.walkthrough) {
+    const viewsById = indexViews(doc.views);
+
+    for (const id of duplicates(doc.walkthrough.steps.map((step) => step.id)))
+      duplicate("walkthrough.steps", `duplicate step id '${id}'`);
+
+    doc.walkthrough.steps.forEach((step, index) => {
+      const at = `walkthrough.steps[${index}]`;
+
+      if (step.stage !== undefined) {
+        switch (step.stage.kind) {
+          case "view":
+            if (!viewsById.has(step.stage.view))
+              broken(`${at}.stage.view`, `step '${step.id}' stages unknown view '${step.stage.view}'`);
+            break;
+          case "flow":
+            if (!flowIds.has(step.stage.flow))
+              broken(`${at}.stage.flow`, `step '${step.id}' stages unknown flow '${step.stage.flow}'`);
+            break;
+          default:
+            assertNever(step.stage, "Unhandled step stage");
+        }
+      }
+
+      switch (step.focus.kind) {
+        case "all":
+          break;
+        case "selection": {
+          const focus = step.focus;
+          const focused: [keyof Omit<typeof focus, "kind" | "messages">, string, ReadonlySet<string>][] = [
+            ["lanes", "lane", laneIds],
+            ["nodes", "node", nodeIds],
+            ["edges", "edge", edgeIds],
+          ];
+          for (const [collection, singular, known] of focused) {
+            focus[collection].forEach((id, memberIndex) => {
+              if (!known.has(id))
+                broken(
+                  `${at}.focus.${collection}[${memberIndex}]`,
+                  `step '${step.id}' focuses unknown ${singular} '${id}'`,
+                );
+            });
+          }
+
+          const onStage = stagedMessages(step.stage, doc.flows, viewsById);
+          switch (onStage.kind) {
+            case "messages":
+              focus.messages.forEach((id, memberIndex) => {
+                if (!onStage.ids.has(id))
+                  broken(
+                    `${at}.focus.messages[${memberIndex}]`,
+                    `step '${step.id}' focuses '${id}', which no flow on its stage carries`,
+                  );
+              });
+              break;
+            case "no-stage":
+              if (focus.messages.length > 0)
+                issues.push({
+                  code: "INVALID_DOCUMENT",
+                  path: `${at}.focus.messages`,
+                  message: `step '${step.id}' focuses flow steps but names no stage to draw them on`,
+                });
+              break;
+            case "unknown-stage":
+              break;
+            default:
+              assertNever(onStage, "Unhandled staged messages");
+          }
+          break;
+        }
+        default:
+          assertNever(step.focus, "Unhandled step focus");
+      }
+    });
+  }
+
   if (doc.layout) {
     doc.layout.laneOrder.forEach((id, index) => {
       if (!laneIds.has(id)) broken(`layout.laneOrder[${index}]`, `unknown lane '${id}'`);
@@ -167,6 +244,14 @@ export const graphSnapshotIssues = (doc: GraphDoc): SchemaIssue[] => {
       message: "a stored map needs an id, so a patch can say which map it targets",
     });
 
+  if (doc.walkthrough !== undefined)
+    issues.push({
+      code: "NOT_A_SNAPSHOT",
+      path: "walkthrough",
+      message:
+        "a stored map carries a walkthrough, but a walkthrough narrates a change and a map describes a system",
+    });
+
   for (const side of ["base", "head"] as const) {
     if (!FullSha.safeParse(doc.provenance[side].sha).success)
       issues.push({

package/src/primitives.ts

@@ -38,6 +38,27 @@ export const Summary = z
   .max(2000)
   .describe("One or two sentences of plain prose. No markdown headings.");
 
+/**
+ * A walkthrough step's heading. The cap is part of the contract rather than
+ * advice: the rail shows one line per step, so a heading long enough to wrap
+ * turns the tour into a wall of text, and no producer can pad its way past it.
+ */
+export const Beat = z
+  .string()
+  .min(1)
+  .max(48)
+  .describe("A step heading. Short enough to read at a glance.");
+
+/**
+ * The one line of body under a step's heading. Required: a heading with
+ * nothing under it reads as a step someone started and never finished.
+ */
+export const Line = z
+  .string()
+  .min(1)
+  .max(140)
+  .describe("A single line under a step heading.");
+
 export const Sha = z
   .string()
   .regex(/^[0-9a-f]{7,40}$/, "must be a lowercase hex git object name")

package/src/version.ts

@@ -6,7 +6,7 @@
  * with semver semantics: patch/minor releases only ever add optional fields
  * or widen an enum, a major release may remove or retype a field.
  */
-export const SCHEMA_VERSION = "0.1.0" as const;
+export const SCHEMA_VERSION = "0.1.1" as const;
 
 export type SchemaVersion = typeof SCHEMA_VERSION;
 

package/src/walkthrough.ts

@@ -0,0 +1,146 @@
+import type { Flow, GraphEdge, GraphNode, Lane, StepStage, View, Walkthrough } from "./graph.js";
+import { assertNever } from "./utils.js";
+
+const NOTHING: ReadonlySet<string> = new Set();
+
+export const indexViews = (views: readonly View[]): Map<string, View> =>
+  new Map(views.flatMap((view) => [[view.id, view] as const, ...indexViews(view.children)]));
+
+/**
+ * A flow step is only ever identified within its own flow, so the stage rather
+ * than the document decides which one a focus meant. Two flows may each carry
+ * a step called `retry`, and neither document is wrong for it.
+ *
+ * `unknown-stage` is its own answer rather than an empty set, so a stage that
+ * names a view or flow the document lacks is reported once, as the broken
+ * reference it is, instead of again for every step underneath it.
+ */
+export type StagedMessages =
+  | { kind: "messages"; ids: ReadonlySet<string> }
+  | { kind: "no-stage" }
+  | { kind: "unknown-stage" };
+
+const messageIdsOf = (flows: readonly Flow[]): Set<string> =>
+  new Set(flows.flatMap((flow) => flow.messages.map((message) => message.id)));
+
+export const stagedMessages = (
+  stage: StepStage | undefined,
+  flows: readonly Flow[],
+  views: ReadonlyMap<string, View>,
+): StagedMessages => {
+  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");
+  }
+};
+
+/**
+ * The document that survived, rather than the ids that went: a step names a
+ * diagram as well as elements, and a flow step means nothing outside the flow
+ * that carries it.
+ */
+export type WalkthroughSubject = {
+  lanes: readonly Lane[];
+  nodes: readonly GraphNode[];
+  edges: readonly GraphEdge[];
+  flows: readonly Flow[];
+  views: readonly View[];
+};
+
+const stageSurvives = (
+  stage: StepStage,
+  flows: ReadonlySet<string>,
+  views: ReadonlyMap<string, View>,
+): boolean => {
+  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: StagedMessages): ReadonlySet<string> => {
+  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: Walkthrough | undefined,
+  subject: WalkthroughSubject,
+): Walkthrough | undefined => {
+  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)),
+        } as const;
+
+        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 };
+};