@coldtea/pr-lens-cli 0.1.0

package/src/git.ts

@@ -0,0 +1,151 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { PrLensCliError } from "./errors.js";
+
+const run = promisify(execFile);
+
+/** Large enough for any diff worth sending to a model; a bigger one is truncated anyway. */
+const MAX_GIT_OUTPUT_BYTES = 64 * 1024 * 1024;
+
+export const git = async (repo: string, args: readonly string[]): Promise<string> => {
+  try {
+    const { stdout } = await run("git", [...args], {
+      cwd: repo,
+      maxBuffer: MAX_GIT_OUTPUT_BYTES,
+      encoding: "utf8",
+    });
+    return stdout;
+  } catch (error) {
+    const stderr =
+      typeof error === "object" && error !== null && "stderr" in error ? String(error.stderr) : "";
+    throw new PrLensCliError(
+      "GIT_FAILED",
+      `git ${args.join(" ")} failed in ${repo}`,
+      stderr.trim() || (error instanceof Error ? error.message : String(error)),
+    );
+  }
+};
+
+export type Commit = { sha: string; ref: string | undefined };
+
+/**
+ * A ref becomes the commit it named at the moment of the run, and a branch
+ * keeps its name for the permalinks. `HEAD` is resolved to a branch name when
+ * it is on one, since "HEAD" tells a reader of the comment nothing.
+ */
+export const resolveCommit = async (repo: string, ref: string): Promise<Commit> => {
+  const sha = (await git(repo, ["rev-parse", "--verify", `${ref}^{commit}`])).trim();
+  if (ref !== "HEAD") return { sha, ref };
+
+  const branch = (await git(repo, ["rev-parse", "--abbrev-ref", "HEAD"])).trim();
+  return { sha, ref: branch === "HEAD" ? undefined : branch };
+};
+
+/**
+ * The commit the pull request would be compared against, not the tip of the
+ * base branch: a diff against the tip would attribute every change made on
+ * the base branch since the fork point to this pull request.
+ */
+export const mergeBase = async (repo: string, base: string, head: string): Promise<string> => {
+  const merged = await git(repo, ["merge-base", base, head]).catch(() => undefined);
+  if (merged === undefined)
+    throw new PrLensCliError(
+      "GIT_FAILED",
+      `${base} and ${head} have no common ancestor`,
+      "fetch the base branch, or pass --base with a ref that shares history with the head",
+    );
+  return merged.trim();
+};
+
+export type ChangedFile = {
+  path: string;
+  additions: number | undefined;
+  deletions: number | undefined;
+};
+
+export type Diff = {
+  files: ChangedFile[];
+  additions: number;
+  deletions: number;
+  patch: string;
+  truncatedAt: number | undefined;
+};
+
+/** `--numstat` reports a binary file's line counts as `-`, which is not zero. */
+const parseNumstat = (stdout: string): ChangedFile[] =>
+  stdout
+    .split("\n")
+    .filter((line) => line.trim() !== "")
+    .flatMap((line) => {
+      const [additions, deletions, ...rest] = line.split("\t");
+      const path = rest.join("\t");
+      if (additions === undefined || deletions === undefined || path === "") return [];
+      const count = (value: string): number | undefined =>
+        value === "-" ? undefined : Number(value);
+      return [{ path, additions: count(additions), deletions: count(deletions) }];
+    });
+
+const sum = (values: readonly (number | undefined)[]): number =>
+  values.reduce<number>((total, value) => total + (value ?? 0), 0);
+
+export const collectDiff = async (
+  repo: string,
+  base: string,
+  head: string,
+  maxPatchBytes: number,
+): Promise<Diff> => {
+  const files = parseNumstat(await git(repo, ["diff", "--numstat", "--find-renames", base, head]));
+  const patch = await git(repo, [
+    "diff",
+    "--no-color",
+    "--find-renames",
+    "--unified=3",
+    base,
+    head,
+  ]);
+
+  const withinBudget = Buffer.byteLength(patch, "utf8") <= maxPatchBytes;
+
+  return {
+    files,
+    additions: sum(files.map((file) => file.additions)),
+    deletions: sum(files.map((file) => file.deletions)),
+    patch: withinBudget ? patch : Buffer.from(patch, "utf8").subarray(0, maxPatchBytes).toString("utf8"),
+    truncatedAt: withinBudget ? undefined : maxPatchBytes,
+  };
+};
+
+export type RepoSlug = { owner: string; name: string; host: string };
+
+const REMOTE_URL = /^(?:(?:ssh|git|https?):\/\/)?(?:[^@/]+@)?([^/:]+)[:/](.+?)(?:\.git)?\/?$/;
+
+export const parseRemoteUrl = (url: string): RepoSlug | undefined => {
+  const match = REMOTE_URL.exec(url.trim());
+  if (!match) return undefined;
+
+  const [, host, path] = match;
+  if (host === undefined || path === undefined) return undefined;
+
+  const segments = path.split("/").filter((segment) => segment !== "");
+  const name = segments.at(-1);
+  const owner = segments.slice(0, -1).join("/");
+  if (name === undefined || owner === "") return undefined;
+
+  return { owner, name, host };
+};
+
+export const parseRepoSlug = (slug: string): RepoSlug | undefined => {
+  const segments = slug.split("/").filter((segment) => segment !== "");
+  const name = segments.at(-1);
+  const owner = segments.slice(0, -1).join("/");
+  if (name === undefined || owner === "" || segments.length !== 2) return undefined;
+  return { owner, name, host: "github.com" };
+};
+
+export const remoteSlug = async (repo: string, remote: string): Promise<RepoSlug | undefined> => {
+  const url = await git(repo, ["remote", "get-url", remote]).catch(() => undefined);
+  return url === undefined ? undefined : parseRemoteUrl(url);
+};
+
+export const repositoryRoot = async (repo: string): Promise<string> =>
+  (await git(repo, ["rev-parse", "--show-toplevel"])).trim();

package/src/io.ts

@@ -0,0 +1,38 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { PrLensCliError } from "./errors.js";
+
+const describe = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error);
+
+export const readTextFile = async (path: string): Promise<string> => {
+  try {
+    return await readFile(resolve(path), "utf8");
+  } catch (error) {
+    throw new PrLensCliError("UNREADABLE_FILE", `cannot read ${path}`, describe(error));
+  }
+};
+
+export const readJsonFile = async (path: string): Promise<unknown> => {
+  const text = await readTextFile(path);
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    throw new PrLensCliError("UNREADABLE_FILE", `${path} is not valid JSON`, describe(error));
+  }
+};
+
+export const writeTextFile = async (path: string, contents: string): Promise<string> => {
+  const absolute = resolve(path);
+  try {
+    await mkdir(dirname(absolute), { recursive: true });
+    await writeFile(absolute, contents, "utf8");
+  } catch (error) {
+    throw new PrLensCliError("UNREADABLE_FILE", `cannot write ${path}`, describe(error));
+  }
+  return absolute;
+};
+
+/** One trailing newline, so written documents behave in a diff and in a shell. */
+export const writeJsonFile = (path: string, value: unknown): Promise<string> =>
+  writeTextFile(path, `${JSON.stringify(value, null, 2)}\n`);

package/src/prompt.ts

@@ -0,0 +1,87 @@
+import type { Lens, PrLensSchemaError } from "@coldtea/pr-lens-schema";
+import type { Diff } from "./git.js";
+
+export type PromptContext = {
+  repo: { owner: string; name: string };
+  base: { sha: string; ref: string | undefined };
+  head: { sha: string; ref: string | undefined };
+  diff: Diff;
+  lenses: readonly Lens[];
+};
+
+export const SYSTEM_PROMPT = [
+  "You read a pull request diff and produce one PR Lens graph document: the map a reviewer wishes they had before reading the code.",
+  "",
+  "You are not a review bot. You never report bugs, risks, style or security findings — there is no field for them and a document that carries them is rejected. Your only job is to describe what the system looks like and how data moves through it, and to mark what this change did to it.",
+  "",
+  "Rules the validator enforces, in the order they are usually broken:",
+  "- Unknown fields are rejected outright. Emit only what the schema names.",
+  "- Every edge endpoint and every flow participant must be a node id you declared, and every node must sit in a lane id you declared. An edge to an undeclared node is the single most common failure.",
+  "- Ids match ^[A-Za-z0-9][A-Za-z0-9._:/-]*$ and are unique within their collection. Prefer readable kebab-case, e.g. 'broadcast-sender'.",
+  "- File paths are repository-relative and POSIX: no leading slash, no drive letter, no backslash, no '..' segment.",
+  "- A flow's step order is the order of the messages array. There is no step number field.",
+  "- A message with kind 'self' has from equal to to, and no other kind may.",
+  "- A document that carries flows must declare the 'data-flow' lens.",
+  "",
+  "What makes the document worth reading:",
+  "- Include the unchanged neighbours the changed code touches, marked delta 'unchanged'. They are the context that makes blast radius legible; a diagram of only changed nodes says nothing about impact.",
+  "- Lanes are the reader's mental model of the system — a runtime, a tier, a boundary they already hold in their head — not the folder tree.",
+  "- Use as few lanes as carry that meaning: three or four. Every lane makes the diagram wider, and a diagram wider than a pull request comment is shown scaled down — past about four lanes the labels on the cards stop being readable without opening the image. If you reach six, two of them are usually the same boundary at different granularity: merge them, and express the finer split as a `group` on the nodes instead, which costs no width.",
+  "- Mark at most one or two edges 'hero': the connection the change is really about.",
+  "- Give the document a title a reviewer would recognise, and a summary that answers 'what does this change do?' in a short paragraph.",
+  "- Attach file refs to nodes, edges and steps wherever the diff shows where they live: they become the permalinks a reader clicks.",
+  "- Add a data flow only when the change actually has an ordered sequence worth animating. One good flow beats three thin ones.",
+  "- Build the drill-down tree: a view over the whole document, and a focused view for each part of the change that deserves its own section. Views are what a reader expands in the comment, so a document without them renders as one picture and nothing else.",
+  "- Stat chips carry the numbers that make the change legible, e.g. label 'Postmark calls' value '500x fewer'. Leave out files changed and line counts — those are filled in for you.",
+  "",
+  "Answer with the JSON document alone. No prose, no markdown fence.",
+].join("\n");
+
+const fileList = (diff: Diff): string =>
+  diff.files
+    .map((file) => {
+      const added = file.additions === undefined ? "bin" : `+${file.additions}`;
+      const removed = file.deletions === undefined ? "" : ` -${file.deletions}`;
+      return `  ${file.path} (${added}${removed})`;
+    })
+    .join("\n");
+
+export const buildExtractionPrompt = (context: PromptContext, jsonSchema: string): string =>
+  [
+    `Repository: ${context.repo.owner}/${context.repo.name}`,
+    `Base commit: ${context.base.sha}${context.base.ref ? ` (${context.base.ref})` : ""}`,
+    `Head commit: ${context.head.sha}${context.head.ref ? ` (${context.head.ref})` : ""}`,
+    `Lenses to fill: ${context.lenses.join(", ")} — exactly these, and no others. Anything needing a lens that is not listed is out of scope for this document.`,
+    "",
+    `Changed files (${context.diff.files.length}, +${context.diff.additions} -${context.diff.deletions}):`,
+    fileList(context.diff),
+    "",
+    "Leave out schemaVersion, kind, generatedAt, provenance, and the numeric fields of stats. Those are filled in from the repository itself, and anything you write there is discarded.",
+    "",
+    "JSON Schema of the document (draft 2020-12). A field with a default may be omitted:",
+    "",
+    jsonSchema,
+    "",
+    "The diff follows.",
+    context.diff.truncatedAt === undefined
+      ? ""
+      : `It was truncated at ${context.diff.truncatedAt} bytes, so the tail of the change is missing; describe what you can see and do not invent the rest.`,
+    "",
+    context.diff.patch,
+  ].join("\n");
+
+export const buildJsonRepairPrompt = (reason: string): string =>
+  [
+    `That answer could not be read as JSON: ${reason}`,
+    "",
+    "Return the whole document again as a single JSON object and nothing else — no prose around it, no markdown fence, and nothing after the closing brace. If the previous answer was cut off, shorten the document so it fits: fewer nodes and one flow beat a document that never ends.",
+  ].join("\n");
+
+export const buildRepairPrompt = (error: PrLensSchemaError): string =>
+  [
+    "That document was rejected. Each line is one problem, as a path into the document, a reason, and the machine code:",
+    "",
+    error.message,
+    "",
+    "Return the whole corrected document again, as JSON alone. Fix only what was named — do not restructure the parts that validated, and do not add fields the schema does not name.",
+  ].join("\n");

package/src/providers/gemini.ts

@@ -0,0 +1,61 @@
+import { z } from "zod";
+import { cutOff, postJson, unreadableResponse } from "./http.js";
+import type { JsonCompletion, Provider } from "./index.js";
+
+/**
+ * Reasoning parts come back in the same array as the answer and must not be
+ * concatenated into it.
+ */
+const Response = z.object({
+  candidates: z
+    .array(
+      z.object({
+        content: z
+          .object({ parts: z.array(z.object({ text: z.string().optional(), thought: z.boolean().optional() })).optional() })
+          .optional(),
+        finishReason: z.string().optional(),
+      }),
+    )
+    .optional(),
+});
+
+export const geminiCompleteJson = async (
+  provider: Provider,
+  request: JsonCompletion,
+): Promise<string> => {
+  const body = await postJson(
+    `${provider.baseUrl}/models/${provider.model}:generateContent`,
+    { "x-goog-api-key": provider.apiKey },
+    {
+      systemInstruction: { parts: [{ text: request.system }] },
+      contents: request.turns.map((turn) => ({ role: turn.role, parts: [{ text: turn.text }] })),
+      generationConfig: {
+        responseMimeType: "application/json",
+        temperature: 0,
+        maxOutputTokens: request.maxOutputTokens,
+      },
+    },
+  );
+
+  const parsed = Response.safeParse(body);
+  if (!parsed.success)
+    throw unreadableResponse("Gemini", "the response did not have the shape the API documents");
+
+  const candidate = parsed.data.candidates?.[0];
+  if (candidate === undefined)
+    throw unreadableResponse("Gemini", "the response carried no candidate — the prompt may have been blocked");
+
+  const text = (candidate.content?.parts ?? [])
+    .filter((part) => part.thought !== true)
+    .map((part) => part.text ?? "")
+    .join("");
+
+  if (text.trim() === "") {
+    if (candidate.finishReason === "MAX_TOKENS") throw cutOff("Gemini");
+    throw unreadableResponse("Gemini", `finish reason: ${candidate.finishReason ?? "unknown"}`);
+  }
+
+  if (candidate.finishReason === "MAX_TOKENS") throw cutOff("Gemini");
+
+  return text;
+};

package/src/providers/http.ts

@@ -0,0 +1,54 @@
+import { PrLensCliError } from "../errors.js";
+
+/** Long enough for a reasoning model on a large diff, short enough to fail a stuck CI job. */
+const REQUEST_TIMEOUT_MS = 300_000;
+
+const MAX_ERROR_BODY_CHARS = 600;
+
+export const postJson = async (
+  url: string,
+  headers: Record<string, string>,
+  body: unknown,
+): Promise<unknown> => {
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "content-type": "application/json", ...headers },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+  }).catch((error: unknown) => {
+    throw new PrLensCliError(
+      "PROVIDER_FAILED",
+      `the request to ${url} did not complete`,
+      error instanceof Error ? error.message : String(error),
+    );
+  });
+
+  const text = await response.text();
+
+  if (!response.ok)
+    throw new PrLensCliError(
+      "PROVIDER_FAILED",
+      `${url} answered ${response.status} ${response.statusText}`,
+      text.slice(0, MAX_ERROR_BODY_CHARS),
+    );
+
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new PrLensCliError(
+      "PROVIDER_FAILED",
+      `${url} answered with something that is not JSON`,
+      text.slice(0, MAX_ERROR_BODY_CHARS),
+    );
+  }
+};
+
+export const cutOff = (provider: string): PrLensCliError =>
+  new PrLensCliError(
+    "PROVIDER_FAILED",
+    `${provider} stopped before finishing the document`,
+    "the answer hit the output token limit — raise --max-output-tokens, or narrow the diff with --base",
+  );
+
+export const unreadableResponse = (provider: string, detail: string): PrLensCliError =>
+  new PrLensCliError("PROVIDER_FAILED", `${provider} returned no usable text`, detail);

package/src/providers/index.ts

@@ -0,0 +1,124 @@
+import { assertNever } from "@coldtea/pr-lens-schema";
+import { PrLensCliError } from "../errors.js";
+import { geminiCompleteJson } from "./gemini.js";
+import { openAiCompleteJson } from "./openai.js";
+
+/**
+ * Three shapes rather than a list of vendors: Gemini's own API, OpenAI's own
+ * API, and the `/chat/completions` shape everyone else copied from it.
+ *
+ * OpenAI is separate from the servers that copied it because the two have
+ * drifted: it renamed the output limit to `max_completion_tokens` and its
+ * newer models reject `max_tokens`, which is the only spelling DeepSeek,
+ * Ollama and llama.cpp know. Everything else about the request is shared, and
+ * a new vendor still needs no code here — only a `--base-url`.
+ */
+export const PROVIDER_IDS = ["gemini", "openai", "openai-compatible"] as const;
+export type ProviderId = (typeof PROVIDER_IDS)[number];
+
+export const isProviderId = (value: string): value is ProviderId =>
+  PROVIDER_IDS.some((id) => id === value);
+
+export type Provider = {
+  id: ProviderId;
+  model: string;
+  apiKey: string;
+  baseUrl: string;
+};
+
+export type Turn = { role: "user" | "model"; text: string };
+
+export type JsonCompletion = {
+  system: string;
+  turns: readonly Turn[];
+  maxOutputTokens: number;
+};
+
+type ProviderDefaults = {
+  apiKeyEnv: string;
+  baseUrl: string | undefined;
+  model: string | undefined;
+};
+
+export const providerDefaults = (id: ProviderId): ProviderDefaults => {
+  switch (id) {
+    case "gemini":
+      return {
+        apiKeyEnv: "GEMINI_API_KEY",
+        baseUrl: "https://generativelanguage.googleapis.com/v1beta",
+        model: "gemini-3.7-flash",
+      };
+    case "openai":
+      return {
+        apiKeyEnv: "OPENAI_API_KEY",
+        baseUrl: "https://api.openai.com/v1",
+        model: undefined,
+      };
+    case "openai-compatible":
+      return {
+        apiKeyEnv: "OPENAI_API_KEY",
+        baseUrl: undefined,
+        model: undefined,
+      };
+    default:
+      return assertNever(id, "Unhandled provider");
+  }
+};
+
+export type ProviderOptions = {
+  id: ProviderId;
+  model: string | undefined;
+  baseUrl: string | undefined;
+  apiKeyEnv: string | undefined;
+};
+
+/**
+ * The key is read from the environment and never accepted as an argument: a
+ * flag would land in shell history and in a CI log line.
+ */
+export const resolveProvider = (
+  options: ProviderOptions,
+  env: Record<string, string | undefined>,
+): Provider => {
+  const defaults = providerDefaults(options.id);
+  const apiKeyEnv = options.apiKeyEnv ?? defaults.apiKeyEnv;
+  const apiKey = env[apiKeyEnv];
+
+  if (apiKey === undefined || apiKey === "")
+    throw new PrLensCliError(
+      "MISSING_API_KEY",
+      `${apiKeyEnv} is not set`,
+      `export ${apiKeyEnv} with your own key, or point --api-key-env at the variable that holds it`,
+    );
+
+  const model = options.model ?? defaults.model;
+  if (model === undefined)
+    throw new PrLensCliError(
+      "USAGE",
+      `--model is required for the ${options.id} provider`,
+      "the endpoint decides which model names exist, so there is no default worth guessing",
+    );
+
+  const baseUrl = options.baseUrl ?? defaults.baseUrl;
+  if (baseUrl === undefined)
+    throw new PrLensCliError(
+      "USAGE",
+      "--base-url is required for an openai-compatible provider",
+      "it is the endpoint that is compatible: point it at DeepSeek, OpenRouter, Ollama or your own server. For OpenAI itself, use --provider openai",
+    );
+
+  return { id: options.id, model, apiKey, baseUrl: baseUrl.replace(/\/+$/, "") };
+};
+
+export const completeJson = (provider: Provider, request: JsonCompletion): Promise<string> => {
+  switch (provider.id) {
+    case "gemini":
+      return geminiCompleteJson(provider, request);
+    case "openai":
+      return openAiCompleteJson(provider, request, "max_completion_tokens");
+    case "openai-compatible":
+      return openAiCompleteJson(provider, request, "max_tokens");
+    default:
+      return assertNever(provider.id, "Unhandled provider");
+  }
+};

package/src/providers/openai.ts

@@ -0,0 +1,68 @@
+import { z } from "zod";
+import { cutOff, postJson, unreadableResponse } from "./http.js";
+import type { JsonCompletion, Provider } from "./index.js";
+
+const Response = z.object({
+  choices: z
+    .array(
+      z.object({
+        message: z.object({ content: z.string().nullable().optional() }).optional(),
+        finish_reason: z.string().nullable().optional(),
+      }),
+    )
+    .optional(),
+});
+
+/**
+ * What an output limit is called on this endpoint.
+ *
+ * OpenAI renamed the field to `max_completion_tokens` and its newer models
+ * reject the old one; the servers that copied the API before that rename —
+ * DeepSeek, Ollama, llama.cpp and the rest — only know `max_tokens`. There is
+ * no spelling both accept, so the caller says which endpoint it is talking to
+ * rather than the request guessing from a hostname.
+ */
+export type TokenLimitField = "max_tokens" | "max_completion_tokens";
+
+/**
+ * The `/chat/completions` shape. The system prompt is the first message rather
+ * than a separate field.
+ */
+export const openAiCompleteJson = async (
+  provider: Provider,
+  request: JsonCompletion,
+  tokenLimitField: TokenLimitField,
+): Promise<string> => {
+  const body = await postJson(
+    `${provider.baseUrl}/chat/completions`,
+    { authorization: `Bearer ${provider.apiKey}` },
+    {
+      model: provider.model,
+      temperature: 0,
+      [tokenLimitField]: request.maxOutputTokens,
+      response_format: { type: "json_object" },
+      messages: [
+        { role: "system", content: request.system },
+        ...request.turns.map((turn) => ({
+          role: turn.role === "model" ? "assistant" : "user",
+          content: turn.text,
+        })),
+      ],
+    },
+  );
+
+  const parsed = Response.safeParse(body);
+  if (!parsed.success)
+    throw unreadableResponse("the provider", "the response did not have the shape /chat/completions documents");
+
+  const choice = parsed.data.choices?.[0];
+  if (choice === undefined) throw unreadableResponse("the provider", "the response carried no choice");
+
+  if (choice.finish_reason === "length") throw cutOff("the provider");
+
+  const text = choice.message?.content ?? "";
+  if (text.trim() === "")
+    throw unreadableResponse("the provider", `finish reason: ${choice.finish_reason ?? "unknown"}`);
+
+  return text;
+};

package/src/snapshot.ts

@@ -0,0 +1,102 @@
+import {
+  applyPatch,
+  formatIssues,
+  graphSnapshotIssues,
+  PrLensSchemaError,
+  safeParseGraphDoc,
+  type Flow,
+  type GraphDoc,
+  type Parsed,
+  type PatchOp,
+} from "@coldtea/pr-lens-schema";
+
+export type StoredMapOptions = {
+  id: string;
+  sha: string;
+  generatedAt: string;
+};
+
+const withoutRemovedMessages = (flow: Flow): Flow["messages"] =>
+  flow.messages.filter((message) => message.delta !== "removed");
+
+/**
+ * A pull-request document says what a change did; a stored map says what the
+ * system is once it has been done. So elements the change deletes go, and the
+ * rest stops being annotated.
+ *
+ * The deletions run through `applyPatch` rather than a filter, because
+ * removing a node also strands its edges, its flow steps, the drill-down views
+ * that pointed at it and the layout hints that named it — the contract already
+ * owns that cascade and there is no second version of it here.
+ */
+const deletionOps = (graph: GraphDoc): PatchOp[] => {
+  const flowOps = graph.flows.flatMap<PatchOp>((flow) => {
+    const messages = withoutRemovedMessages(flow);
+    if (flow.delta === "removed" || messages.length === 0) return [{ op: "remove_flow", id: flow.id }];
+    if (messages.length === flow.messages.length) return [];
+    return [{ op: "update_flow", id: flow.id, patch: { messages } }];
+  });
+
+  return [
+    ...flowOps,
+    ...graph.edges
+      .filter((edge) => edge.delta === "removed")
+      .map<PatchOp>((edge) => ({ op: "remove_edge", id: edge.id })),
+    ...graph.nodes
+      .filter((node) => node.delta === "removed")
+      .map<PatchOp>((node) => ({ op: "remove_node", id: node.id })),
+    ...graph.lanes
+      .filter((lane) => lane.delta === "removed")
+      .map<PatchOp>((lane) => ({ op: "remove_lane", id: lane.id })),
+  ];
+};
+
+/**
+ * The map a repository commits: the merged state of the system, identified,
+ * stamped with the one commit it reflects, and carrying no annotations.
+ *
+ * Change statistics are dropped rather than carried over. A line count
+ * describes a diff, and this document no longer describes one.
+ */
+export const toStoredMap = (graph: GraphDoc, options: StoredMapOptions): Parsed<GraphDoc> => {
+  const applied = applyPatch(graph, deletionOps(graph));
+  if (!applied.ok) return applied;
+
+  const merged = applied.value;
+  const head = { ...merged.provenance.head, sha: options.sha };
+
+  const candidate = {
+    ...merged,
+    id: options.id,
+    generatedAt: options.generatedAt,
+    provenance: { ...merged.provenance, base: head, head },
+    stats: undefined,
+    lanes: merged.lanes.map(({ delta: _delta, ...lane }) => lane),
+    nodes: merged.nodes.map((node) => ({ ...node, delta: "unchanged" as const })),
+    edges: merged.edges.map((edge) => ({ ...edge, delta: "unchanged" as const })),
+    flows: merged.flows.map((flow) => ({
+      ...flow,
+      delta: "unchanged" as const,
+      messages: withoutRemovedMessages(flow).map((message) => ({
+        ...message,
+        delta: "unchanged" as const,
+      })),
+    })),
+  };
+
+  const parsed = safeParseGraphDoc(candidate);
+  if (!parsed.ok) return parsed;
+
+  const issues = graphSnapshotIssues(parsed.value);
+  if (issues.length > 0)
+    return {
+      ok: false,
+      error: new PrLensSchemaError(
+        "NOT_A_SNAPSHOT",
+        `the exported document is not a stored map:\n${formatIssues(issues)}`,
+        issues,
+      ),
+    };
+
+  return parsed;
+};