@shiyuphan/follow-me 0.6.0 → 0.8.0

package/README.md

@@ -75,13 +75,19 @@ The red blob in the party hat is your branch tip. Nothing follow-me does moves i
 ![Cmd-clicking format in pow opens a peek of its definition, which lives outside this branch](assets/screenshots/definition.png)
 *Cmd-click a name to jump to where it is defined, even in a later commit, and Alt+Left to come back. A definition the branch does not change opens as a peek.*
 
+![Coverage while reading: gutter bars mark covered, partly covered and uncovered lines, with counts per commit, per file and for the branch, and a popover listing the test that ran a line](assets/screenshots/coverage.png)
+*Coverage while reading. Your agent runs the tests with coverage and passes the lcov to `follow-me coverage`; follow-me never runs anything. Bars show covered, partly covered and uncovered lines, `x` jumps to the next uncovered line, and clicking a bar lists the tests that ran it.*
+
+![A state machine reply: each state is marked by whether a test reached it, and clicking a state jumps to its code](assets/screenshots/state-machine.png)
+*Your agent offers what it can draw, like "a state machine for this guard", as chips under the commit. Tap one and it answers with the diagram, each state marked by whether a test reached it. Click a state to jump to its code.*
+
 ![A diagram opened in the lightbox at full size](assets/screenshots/diagram.png)
 *Diagrams sit full width under the commit or reply they explain, and open full size on click.*
 
 ![The hand-off page: every kept item with its original-branch path and line, an include checkbox, and copy buttons](assets/screenshots/handoff.png)
 *Submit review. Each item carries the original branch's path and line, so your agent can post it to the merge request as is.*
 
-Keys: `[` shows or hides the index, `j` and `k` move between commits, Cmd-click (Ctrl-click) goes to a definition and Alt+Left comes back, arrows and Shift+arrows pick rows inside a hunk, `c` comments on the pick, `v` marks a commit viewed, `?` lists the rest. An unfinished review autosaves and comes back when the page is opened again.
+Keys: `[` shows or hides the index, `j` and `k` move between commits, Cmd-click (Ctrl-click) goes to a definition and Alt+Left comes back, arrows and Shift+arrows pick rows inside a hunk, `c` comments on the pick, `v` marks a commit viewed, `g` shows or hides coverage and `x` jumps to the next uncovered line, `?` lists the rest. An unfinished review autosaves and comes back when the page is opened again.
 
 ### Reviewing someone else's branch
 

package/dist/src/cli.js

@@ -1,22 +1,28 @@
 import { execFileSync } from "node:child_process";
 import { readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join, relative } from "node:path";
+import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { mapOffTip, parseStateMap } from "./comments.js";
+import { changedLines, LcovError, PREVIEW_LINES, parseLcov, parseLocArg, recordRun, runOf, tipPlacer, totalOf, } from "./coverage.js";
 import { definitionIndex, isIdentifier } from "./definition.js";
-import { DiffParseError, formatUnitRef, isUnitId } from "./diff.js";
-import { BranchRefusedError, branchHead, GitError, isOwnWork, signing, treeOf, writeBranch, } from "./git.js";
-import { fetchCarried, fetchComments, fetchReport, findServer, followEvents, idleMs, listSessions, openBrowser, pollEvents, portFallbackMessage, postComment, postReply, probeHealth, readServerRecord, registerWith, sessionUrl, spawnDetached, startOrAttach, stateDir, stillHosted, stopServer, swapVersion, } from "./host.js";
+import { DiffParseError, formatUnitRef, isRepoPath, isUnitId, splitLines } from "./diff.js";
+import { BranchRefusedError, blobsAt, branchHead, GitError, isOwnWork, pathsAt, pathsChanged, signing, treeOf, writeBranch, } from "./git.js";
+import { fetchCarried, fetchComments, fetchReport, fetchWaitingOffers, findServer, followEvents, idleMs, listSessions, openBrowser, pollEvents, portFallbackMessage, postComment, postCoverage, postReply, probeHealth, readServerRecord, registerWith, sessionUrl, spawnDetached, startOrAttach, stateDir, stillHosted, stopServer, swapVersion, } from "./host.js";
 import { findSkillDir, InstallError, runInstall, runUninstall, syncSkills, } from "./install.js";
 import { naiveDraft } from "./naive.js";
-import { isCommentId, isConcernId, isFields, serializePlanFile, validatePlan, } from "./plan.js";
+import { isCommentId, isConcernId, isFields, OFFERS_PER_COMMIT, OFFERS_PER_PLAN, serializePlanFile, validatePlan, } from "./plan.js";
 import { renderEvents, renderPrompt, renderReport, renderShownComment, renderShownConcern, renderShownDefinitions, renderShownUnit, reportItems, } from "./prompt.js";
 import { RegistrationError, sessionIdOf } from "./server.js";
-import { BranchMovedError, cleanSessions, extractSession, MissingDraftError, NotARepositoryError, openSession, SessionFileError, SessionLockedError, sessionComments, sinceLastPlan, } from "./session.js";
+import { BranchMovedError, cleanSessions, coverageAt, extractSession, MissingDraftError, NotARepositoryError, openSession, SessionFileError, SessionLockedError, sessionComments, sinceLastPlan, } from "./session.js";
 import { checkSyntax } from "./syntax.js";
 class UsageError extends Error {
     name = "UsageError";
 }
+/** A test run follow-me will not record, with the reason the agent can act on. */
+class CoverageError extends Error {
+    name = "CoverageError";
+}
 const SHORT_USAGE = `usage: follow-me [--wait <seconds>] [--branch <name>]
 
 Run follow-me with no command. Each call does the next thing that is missing and returns: it
@@ -26,9 +32,10 @@ prints what they flagged or asked. It is interactive: do what its "next:" line s
 again until it prints the report.
 
 Other commands:
-  reply <commentId> --body <text> [--diagram <file>]
+  reply <commentId> --body <text> [--diagram <file> [--map <file>]]
                                             answer under a comment on the page; the diagram is
-                                            Mermaid source
+                                            Mermaid source, the map JSON tying its states to
+                                            tip lines
   explain [--commit <n>] [--unit <id>] [--lines <a-b>] --body <text> [--diagram <file>]
                                             start a thread on the page without being asked
   show <h_…|c_…|k_…|path:line[@n|@base]|name>
@@ -37,6 +44,9 @@ Other commands:
                                             is defined, instead of reading files
   report [--json] [--markdown]              print the report of the latest review; --json lists
                                             the items to post to a merge request
+  coverage <lcov> [--test <id> [--at <path:line>]] [--reset]
+                                            record a test run taken at the tip for the page;
+                                            --reset alone clears it before per-test runs
 
 help --all lists every command.`;
 const USAGE = `usage: follow-me <command> [options]
@@ -79,9 +89,10 @@ Interactive loop (while the review page is open):
                                             reports the end of the review. Your own replies are
                                             left out. --follow streams every event until the
                                             review ends instead of stopping at the first
-  reply <commentId> --body <text> [--diagram <file>]
+  reply <commentId> --body <text> [--diagram <file> [--map <file>]]
                                             answer under a comment on the page; the diagram is
-                                            Mermaid source
+                                            Mermaid source, the map JSON tying its states to
+                                            tip lines
   explain [--commit <n>] [--unit <id>] [--lines <a-b>] --body <text> [--diagram <file>]
                                             start a thread on the page without being asked;
                                             --lines are change lines of the unit, commits count
@@ -100,6 +111,12 @@ Interactive loop (while the review page is open):
                                             line in both voices, then questions with answers;
                                             --json lists the items to post to a merge request
                                             (path, lines, severity, body, thread, excluded)
+  coverage <lcov> [--test <id> [--at <path:line>]] [--reset] [--branch <name>]
+                                            record the lcov of a test run at the branch tip;
+                                            refuses when a covered file in the working tree
+                                            differs from the tip. A plain run replaces the last;
+                                            --test runs add one test each, --at is where it is.
+                                            --reset starts fresh; alone it clears the last run
   apply, while the page is open, swaps it to the new plan version in place, same URL.
 
 Old names, still working:
@@ -279,6 +296,12 @@ function formatIssue(issue) {
             return `$.commits[${issue.commit}]: concern: ${issue.reason}`;
         case "too-many-concerns":
             return `${issue.unit} has more than one concern, in commits ${issue.commits.join(" and ")}; keep the one that matters`;
+        case "bad-offer":
+            return `$.commits[${issue.commit}]: offer: ${issue.reason}`;
+        case "too-many-offers":
+            return issue.commit === null
+                ? `the plan has ${issue.count} offers; at most ${OFFERS_PER_PLAN}, and most plans need none`
+                : `$.commits[${issue.commit}] has ${issue.count} offers; at most ${OFFERS_PER_COMMIT} per commit`;
         case "final-mismatch": {
             const tip = issue.expected ? `${issue.expected.mode} ${issue.expected.blob}` : "absent";
             return `${show(issue.path)}: the last commit has ${issue.got}, the tip has ${tip}`;
@@ -293,6 +316,9 @@ function formatWarning(w) {
     if (w.kind === "long-title") {
         return `warning: $.commits[${w.commit}]: title is ${w.length} characters; keep it to 50`;
     }
+    if (w.kind === "section-order") {
+        return `warning: $.commits[${w.commit}]: section ${w.section} comes after ${w.after}; sections read story, steps, details, wiring`;
+    }
     if (w.kind === "question-addressed") {
         return `warning: question ${w.comment} is marked addressed; explain it with "answered" and "at" unless answering it changed the plan`;
     }
@@ -909,8 +935,8 @@ function reviewedPlan(session) {
     return null;
 }
 /** Prints the finished review's report, which is what the agent works from from here on. */
-function finished(session, stored) {
-    const text = renderStored(session, stored);
+async function finished(session, stored) {
+    const text = await renderStored(session, stored);
     if (text === null)
         return 1;
     // A review that swapped versions holds what its earlier versions said too.
@@ -1041,6 +1067,13 @@ function waitOf(args) {
 /** One call fits inside a harness's tool timeout, so the agent's loop is one command per turn. */
 const ENTRY_WAIT_SECONDS = 90;
 const MAX_ENTRY_WAIT_SECONDS = 300;
+/** The step that names the oldest accepted offer the agent has not answered, or null. */
+async function offerStep(port, summary) {
+    const [first] = await fetchWaitingOffers(port, summary);
+    if (first === undefined)
+        return null;
+    return `${STILL_WORKING}; offer ${first.offer} waits for your diagram: follow-me reply ${first.comment} --diagram <file> [--map <file>], then run follow-me again`;
+}
 /**
  * Listens to the hosted review for up to --wait seconds and prints what the reviewer did. It
  * returns at once with news, and with the report when the reviewer submitted or ended the review.
@@ -1100,11 +1133,13 @@ async function listen(session, open, args) {
                 next("done; the user can port it with follow-me report --json");
                 return 0;
             }
-            next(`${STILL_WORKING}; answer with follow-me reply <id> --body "<markdown>" [--diagram file], then run follow-me again`);
+            next((await offerStep(port, summary)) ??
+                `${STILL_WORKING}; answer with follow-me reply <id> --body "<markdown>" [--diagram file], then run follow-me again`);
             return 0;
         }
         if (left <= 0) {
-            next(`${STILL_WORKING}; run follow-me again to keep listening`);
+            next((await offerStep(port, summary)) ??
+                `${STILL_WORKING}; run follow-me again to keep listening`);
             return 0;
         }
     }
@@ -1173,6 +1208,9 @@ async function entry(cwd, args) {
     const result = await hostReview(session, mode, detached, async () => prep, reportSaved);
     if (result.kind !== "elsewhere")
         return exitCode(result);
+    if (session.coverage() === null) {
+        next("if the project has tests, run them with coverage at the tip and pass the lcov to follow-me coverage");
+    }
     say("follow-me is interactive: keep running it until it prints the report");
     return listen(session, result, args);
 }
@@ -1230,7 +1268,7 @@ async function walkPlan(session, args) {
     return alreadyReviewed(session, latest.version, args) ? null : latest;
 }
 /** The consolidated report of a saved review, or null after saying why it cannot be rendered. */
-function renderStored(session, stored, format = "markdown") {
+async function renderStored(session, stored, format = "markdown") {
     const plan = session.plans().find((p) => p.version === stored.version);
     if (plan === undefined) {
         console.error(`follow-me: review v${stored.version} refers to a plan that is missing`);
@@ -1258,7 +1296,13 @@ function renderStored(session, stored, format = "markdown") {
                 concerns: stored.review.carriedConcerns ?? [],
             },
         };
-    const opts = { branch: session.anchor.branch, responses, ...earlier };
+    const coverage = await coverageAt(session.root, session.dir, session.anchor.tip);
+    const opts = {
+        branch: session.anchor.branch,
+        responses,
+        ...earlier,
+        ...(coverage === null ? {} : { coverage }),
+    };
     if (format === "json") {
         const items = reportItems(stored.review, verdict.plan.commits, session.diff.units, opts);
         return `${JSON.stringify(items, null, 2)}\n`;
@@ -1288,12 +1332,92 @@ async function report(cwd, args, walkOnly = false) {
         console.error("follow-me: no review is open and none has ended; run `follow-me review` first");
         return 1;
     }
-    const text = renderStored(session, stored, format);
+    const text = await renderStored(session, stored, format);
     if (text === null)
         return 1;
     process.stdout.write(text);
     return 0;
 }
+const COVERAGE_USAGE = "usage: follow-me coverage <lcov> [--test <id> [--at <path:line>]] [--reset]\n       follow-me coverage --reset";
+/**
+ * Records the lcov of a test run the agent made at the tip in the session's coverage.json and
+ * prints how much of the branch's changed code it ran. follow-me never runs the tests itself.
+ */
+async function coverage(cwd, args) {
+    const [file, extra] = args.positionals;
+    const id = args.values.get("test");
+    const atArg = args.values.get("at");
+    const reset = args.flags.has("reset");
+    if (file === undefined && reset && id === undefined && atArg === undefined) {
+        const session = await openFresh(cwd, args);
+        session.clearCoverage();
+        say("coverage cleared; the next run starts fresh");
+        return 0;
+    }
+    if (file === undefined || extra !== undefined)
+        throw new UsageError(COVERAGE_USAGE);
+    if (atArg !== undefined && id === undefined) {
+        throw new UsageError(`--at needs --test\n${COVERAGE_USAGE}`);
+    }
+    let text;
+    try {
+        text = readFileSync(resolve(cwd, file), "utf8");
+    }
+    catch {
+        throw new UsageError(`cannot read ${file}`);
+    }
+    const records = parseLcov(text);
+    const session = await openFresh(cwd, args);
+    const { tip } = session.anchor;
+    const place = tipPlacer(session.root, cwd, await pathsAt(session.root, tip));
+    const run = runOf(records, place);
+    if (run.files.size === 0) {
+        throw new CoverageError(`none of the ${plural(new Set(records.map((r) => r.path)).size, "file")} in ${file} is in ${session.anchor.branch} at the tip; run follow-me coverage from the directory the tests ran in`);
+    }
+    const changed = await pathsChanged(session.root, tip, null);
+    const differ = [...run.files.keys()].filter((p) => changed.has(p));
+    if (differ.length > 0) {
+        throw new CoverageError(`coverage must be taken on the tip; these files differ: ${differ.map(show).join(", ")}`);
+    }
+    let test;
+    if (id !== undefined) {
+        const at = atArg === undefined ? undefined : parseLocArg(atArg, place);
+        if (typeof at === "string")
+            throw new UsageError(at);
+        const preview = at === undefined ? undefined : await testPreview(session, at);
+        test = {
+            id,
+            ...(at === undefined ? {} : { at }),
+            ...(preview === undefined ? {} : { preview }),
+        };
+    }
+    const takenAt = new Date().toISOString();
+    const recorded = recordRun(reset ? null : session.coverage(), run, {
+        tip,
+        takenAt,
+        ...(test === undefined ? {} : { test }),
+    });
+    session.writeCoverage(recorded);
+    const open = await openOnServer(session, null);
+    if (open !== null)
+        await postCoverage(open.port, open.summary);
+    const { covered, executable } = totalOf(changedLines(session.diff.units, recorded.files).values());
+    say(`coverage for ${plural(recorded.files.size, "file")} at ${short(tip)}; ${covered} of ${executable} changed lines covered`);
+    return 0;
+}
+/**
+ * Up to PREVIEW_LINES tip lines from where a test starts, when the branch leaves its file alone:
+ * the page shows the branch's own files from the plan, and the others need this to peek.
+ */
+async function testPreview(session, at) {
+    const changed = new Set([...session.diff.units.values()].map((u) => u.path));
+    if (changed.has(at.path))
+        return undefined;
+    const bytes = (await blobsAt(session.root, session.anchor.tip, [at.path])).get(at.path) ?? "";
+    return splitLines(bytes)
+        .slice(at.start - 1, at.start - 1 + PREVIEW_LINES)
+        .map((line) => Buffer.from(line.replace(/\r?\n$/, ""), "latin1").toString("utf8"));
+}
 /** The old name of report. */
 async function feedback(cwd, args) {
     console.error("follow-me: feedback is now report; printing the same");
@@ -1302,9 +1426,14 @@ async function feedback(cwd, args) {
 function isCommentEvent(event) {
     return event.type === "comment" || event.type === "comment-updated";
 }
-/** Events the reviewer caused; the agent's own replies, explanations and version swaps are not news. */
+/**
+ * Events the reviewer caused; the agent's own replies, explanations, version swaps and coverage
+ * are not news, and neither is a dismissed offer, which asks nothing of the agent.
+ */
 function isNews(event) {
-    if (event.type === "version")
+    if (event.type === "version" || event.type === "coverage")
+        return false;
+    if (event.type === "offer-dismissed")
         return false;
     if (event.type === "comment" || event.type === "comment-updated") {
         return event.comment.author !== "agent";
@@ -1385,12 +1514,18 @@ async function watch(cwd, args) {
 /** Posts the agent's answer under a comment on the hosted page. */
 async function reply(cwd, args) {
     const [commentId, extra] = args.positionals;
-    const body = args.values.get("body");
+    const diagram = diagramOf(args);
+    // A diagram can be the whole answer, as when it answers an accepted offer.
+    const body = args.values.get("body") ?? (diagram === undefined ? undefined : "");
     if (commentId === undefined || extra !== undefined || body === undefined) {
-        throw new UsageError("usage: follow-me reply <commentId> --body <text> [--diagram <file>]");
+        throw new UsageError(REPLY_USAGE);
+    }
+    const mapFile = args.values.get("map");
+    if (mapFile !== undefined && diagram === undefined) {
+        throw new UsageError(`--map needs --diagram, the state diagram it ties to code\n${REPLY_USAGE}`);
     }
-    const diagram = diagramOf(args);
     const session = await openSession(cwd, sessionOpts(args));
+    const map = mapFile === undefined ? undefined : await readMap(session, mapFile, diagram);
     const open = await openOnServer(session, null);
     if (open === null)
         return notOpen(session);
@@ -1398,11 +1533,59 @@ async function reply(cwd, args) {
         author: "agent",
         body,
         ...(diagram === undefined ? {} : { diagram }),
+        ...(map === undefined ? {} : { map }),
     });
     say(`replied ${id} to ${commentId}`);
     next(`run follow-me again; ${STILL_WORKING}`);
     return 0;
 }
+const REPLY_USAGE = `usage: follow-me reply <commentId> --body <text> [--diagram <file> [--map <file>]]
+       follow-me reply <commentId> --diagram <file> [--map <file>] [--body <text>]`;
+/** A map path as git names it: the JSON's UTF-8 text as the bytes git prints, read as latin1. */
+function repoPathOf(typed) {
+    const path = Buffer.from(typed, "utf8").toString("latin1");
+    if (!isRepoPath(path))
+        throw new UsageError(`${typed} is not a repo path`);
+    return path;
+}
+/**
+ * --map's JSON, checked against the tip: every place is a file there and within its lines. Every
+ * bad entry is named at once, so one fix round is enough.
+ */
+async function readMap(session, file, diagram) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        throw new UsageError(`cannot read ${file} as JSON: ${error instanceof Error ? error.message : error}`);
+    }
+    const typed = parseStateMap(raw, diagram);
+    if (typeof typed === "string")
+        throw new UsageError(`${file}: ${typed}`);
+    const at = (loc) => ({ ...loc, path: repoPathOf(loc.path) });
+    const map = {
+        states: Object.fromEntries(Object.entries(typed.states).map(([name, locs]) => [name, locs.map(at)])),
+        ...(typed.transitions === undefined
+            ? {}
+            : { transitions: typed.transitions.map((t) => ({ ...t, at: t.at.map(at) })) }),
+    };
+    const { root, anchor } = session;
+    const named = [
+        ...Object.values(map.states).flat(),
+        ...(map.transitions ?? []).flatMap((t) => t.at),
+    ].map((loc) => loc.path);
+    const tip = await pathsAt(root, anchor.tip);
+    const present = [...new Set(named)].filter((p) => tip.has(p));
+    const lines = new Map([...(await blobsAt(root, anchor.tip, present))].map(([p, bytes]) => [
+        p,
+        splitLines(bytes).length,
+    ]));
+    const problems = mapOffTip(map, lines, (p) => Buffer.from(p, "latin1").toString("utf8"));
+    if (problems.length > 0)
+        throw new UsageError(`${file}:\n  ${problems.join("\n  ")}`);
+    return map;
+}
 /** The Mermaid source in --diagram's file, or undefined without the flag. */
 function diagramOf(args) {
     const file = args.values.get("diagram");
@@ -1871,13 +2054,15 @@ export async function main(argv, cwd) {
                 return await watch(cwd, parseArgs(rest, spec));
             }
             case "reply":
-                return await reply(cwd, parseArgs(rest, { values: ["body", "diagram", "branch"] }));
+                return await reply(cwd, parseArgs(rest, { values: ["body", "diagram", "map", "branch"] }));
             case "explain": {
                 const spec = { values: ["commit", "unit", "lines", "body", "diagram", "branch"] };
                 return await explain(cwd, parseArgs(rest, spec));
             }
             case "show":
                 return await showRef(cwd, parseArgs(rest, { values: ["branch"] }));
+            case "coverage":
+                return await coverage(cwd, parseArgs(rest, { values: ["test", "at", "branch"], flags: ["reset"] }));
             case "report":
                 return await report(cwd, parseArgs(rest, { values: ["branch"], flags: ["json", "markdown"] }));
             case "clean": {
@@ -1918,6 +2103,8 @@ export async function main(argv, cwd) {
     catch (error) {
         const known = [
             UsageError,
+            CoverageError,
+            LcovError,
             BranchMovedError,
             BranchRefusedError,
             SessionFileError,

package/dist/src/comments.js

@@ -1,5 +1,6 @@
-import { isRepoPath, isUnitId } from "./diff.js";
-import { diagramProblem, isArray, isCommentId, isConcernId, isFields, isPlanVersion, isSeverity, parsePlacedConcern, } from "./plan.js";
+import { parseLoc } from "./coverage.js";
+import { isRepoPath, isSha, isUnitId } from "./diff.js";
+import { diagramProblem, isArray, isCommentId, isConcernId, isFields, isOfferId, isPlanVersion, isSeverity, parsePlacedConcern, } from "./plan.js";
 /**
  * The wire formats of review state, parsed once at the boundary: comments, replies, concern
  * decisions, the review file, its autosaved draft and the events a hosted session logs. Every
@@ -48,10 +49,110 @@ function parseAnchor(v) {
     }
     return { kind: "hunk", unit: v.unit, commit, changes, offsets };
 }
+function parseLocs(v, at, needed) {
+    const what = `${at}: expected a list of { path, start, end }${needed ? " with at least one place" : ""}`;
+    if (!isArray(v) || (needed && v.length === 0))
+        return what;
+    const out = [];
+    for (const [i, raw] of v.entries()) {
+        const loc = parseLoc(raw);
+        if (loc === null)
+            return `${at}[${i}]: expected { path, start, end } with 1 <= start <= end`;
+        out.push(loc);
+    }
+    return out;
+}
+const TRANSITION_ENDS = ["from", "to"];
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Boundary parse of a reply's state map. Every state has at least one place, every transition
+ * names states of the map, and with a stateDiagram every state name appears in it. The reason
+ * names the bad entry, as map.states.<name>[i] or map.transitions[i].<field>.
+ */
+export function parseStateMap(v, diagram) {
+    if (!isFields(v))
+        return "map: expected { states, transitions }";
+    if (!isFields(v.states) || Object.keys(v.states).length === 0) {
+        return "map.states: expected an object of state name to places";
+    }
+    const states = [];
+    for (const [name, raw] of Object.entries(v.states)) {
+        if (name.trim() === "")
+            return "map.states: a state has an empty name";
+        const locs = parseLocs(raw, `map.states.${name}`, true);
+        if (typeof locs === "string")
+            return locs;
+        states.push([name, locs]);
+    }
+    const named = new Set(states.map(([name]) => name));
+    const transitions = [];
+    const rawTransitions = v.transitions ?? [];
+    if (!isArray(rawTransitions))
+        return "map.transitions: expected a list";
+    for (const [i, raw] of rawTransitions.entries()) {
+        const at = `map.transitions[${i}]`;
+        if (!isFields(raw))
+            return `${at}: expected { from, to, event, at }`;
+        for (const end of TRANSITION_ENDS) {
+            const state = raw[end];
+            if (typeof state !== "string" || !named.has(state)) {
+                return `${at}.${end}: ${JSON.stringify(state)} is not a state in map.states`;
+            }
+        }
+        const { from, to, event } = raw;
+        if (typeof from !== "string" || typeof to !== "string")
+            return `${at}: expected from and to`;
+        if (event !== undefined && typeof event !== "string")
+            return `${at}.event: expected a string`;
+        const locs = parseLocs(raw.at, `${at}.at`, false);
+        if (typeof locs === "string")
+            return locs;
+        transitions.push({ from, to, ...(event === undefined ? {} : { event }), at: locs });
+    }
+    const first = (diagram ?? "")
+        .split("\n")
+        .find((line) => line.trim() !== "")
+        ?.trim() ?? "";
+    if (first.startsWith("stateDiagram")) {
+        for (const name of named) {
+            if (!new RegExp(`(^|[^\\w])${escapeRegExp(name)}([^\\w]|$)`, "m").test(diagram ?? "")) {
+                return `map.states.${name}: not a state of the stateDiagram`;
+            }
+        }
+    }
+    return {
+        states: Object.fromEntries(states),
+        ...(transitions.length === 0 ? {} : { transitions }),
+    };
+}
+/**
+ * Where a map points past the tip: a path the tip has no file at, or lines beyond its end. lines
+ * holds the line count of every tip file the map names that exists; show prints a path.
+ */
+export function mapOffTip(map, lines, show = (path) => path) {
+    const check = (loc, at) => {
+        const count = lines.get(loc.path);
+        if (count === undefined)
+            return [`${at}: ${show(loc.path)} is not a file at the tip`];
+        if (loc.end > count) {
+            return [
+                `${at}: lines ${loc.start}-${loc.end} are past the end of ${show(loc.path)}, which has ${count} lines at the tip`,
+            ];
+        }
+        return [];
+    };
+    return [
+        ...Object.entries(map.states).flatMap(([name, locs]) => locs.flatMap((loc, i) => check(loc, `map.states.${name}[${i}]`))),
+        ...(map.transitions ?? []).flatMap((t, i) => t.at.flatMap((loc, j) => check(loc, `map.transitions[${i}].at[${j}]`))),
+    ];
+}
 /** A stored reply. Replies a client posts go through parseNewReply, which mints id and time. */
 export function parseReply(v) {
-    if (!isFields(v))
+    if (!isFields(v)) {
         return "not an object";
+    }
     if (!isReplyId(v.id))
         return "id is not a reply id";
     if (v.author !== "agent" && v.author !== "reviewer")
@@ -61,30 +162,50 @@ export function parseReply(v) {
     }
     if (v.diagram !== undefined && typeof v.diagram !== "string")
         return "diagram is not a string";
+    const map = v.map === undefined ? undefined : parseStateMap(v.map, v.diagram);
+    if (typeof map === "string")
+        return map;
     return {
         id: v.id,
         author: v.author,
         body: v.body,
         ...(v.diagram === undefined ? {} : { diagram: v.diagram }),
+        ...(map === undefined ? {} : { map }),
         createdAt: v.createdAt,
     };
 }
-/** The body of POST .../replies: who speaks, what, and an optional Mermaid diagram. */
+/**
+ * The body of POST .../replies: who speaks, what, and an optional Mermaid diagram. The body may be
+ * empty only when the diagram is the answer.
+ */
 export function parseNewReply(v) {
     if (!isFields(v))
         return "the reply is not an object";
     if (v.author !== "agent" && v.author !== "reviewer")
         return 'author is not "agent" or "reviewer"';
-    if (typeof v.body !== "string" || v.body.trim() === "")
-        return "body is not a non-empty string";
-    if (v.diagram === undefined)
+    if (typeof v.body !== "string")
+        return "body is not a string";
+    if (v.diagram === undefined) {
+        if (v.map !== undefined)
+            return "map needs the diagram it ties to code";
+        if (v.body.trim() === "")
+            return "body is empty; a reply needs words or a diagram";
         return { author: v.author, body: v.body };
+    }
     if (typeof v.diagram !== "string")
         return "diagram is not a string";
     const problem = diagramProblem(v.diagram);
     if (problem !== null)
         return `diagram: ${problem}`;
-    return { author: v.author, body: v.body, diagram: v.diagram };
+    const map = v.map === undefined ? undefined : parseStateMap(v.map, v.diagram);
+    if (typeof map === "string")
+        return map;
+    return {
+        author: v.author,
+        body: v.body,
+        diagram: v.diagram,
+        ...(map === undefined ? {} : { map }),
+    };
 }
 function isString(v) {
     return typeof v === "string";
@@ -133,6 +254,14 @@ export function parseComment(v) {
     const severity = v.severity;
     if (severity !== undefined && !isSeverity(severity))
         return "severity is unknown";
+    const offer = v.offer;
+    if (offer !== undefined) {
+        if (!isOfferId(offer))
+            return "offer is not an offer id";
+        if (v.kind !== "question" || v.author !== undefined) {
+            return "offer is only for a reviewer's question";
+        }
+    }
     const replies = parseList(v.replies, parseReply, "replies");
     if (typeof replies === "string")
         return replies;
@@ -152,6 +281,7 @@ export function parseComment(v) {
         ...(replies.length === 0 ? {} : { replies }),
         ...(v.author === "agent" ? { author: "agent" } : {}),
         ...(v.diagram === undefined ? {} : { diagram: v.diagram }),
+        ...(offer === undefined ? {} : { offer }),
     };
 }
 function withDecision(concern, v) {
@@ -363,6 +493,9 @@ export function parseReview(v) {
     const concernsCarried = parseList(v.carriedConcerns, parseCarriedConcern, "carriedConcerns");
     if (typeof concernsCarried === "string")
         return concernsCarried;
+    const dismissed = parseIds(v.dismissedOffers, isOfferId, "dismissedOffers", "offer");
+    if (typeof dismissed === "string")
+        return dismissed;
     return {
         schema: v.schema,
         mode,
@@ -376,6 +509,7 @@ export function parseReview(v) {
         ...(earlier.length === 0 ? {} : { earlierReplies: earlier }),
         ...(carried === null ? {} : { carried }),
         ...(concernsCarried.length === 0 ? {} : { carriedConcerns: concernsCarried }),
+        ...(dismissed.length === 0 ? {} : { dismissedOffers: dismissed }),
     };
 }
 function lenient(items, parse) {
@@ -403,6 +537,7 @@ export function parseDraft(v) {
         earlierReplies: lenient(v.earlierReplies, parseEarlierReplies),
         carried: v.carried === undefined ? null : lenient(v.carried, parseCarriedRef),
         carriedConcerns: lenient(v.carriedConcerns, parseCarriedConcern),
+        dismissedOffers: lenientIds(v.dismissedOffers, isOfferId),
     };
 }
 export function parseEvent(v) {
@@ -444,6 +579,10 @@ export function parseEvent(v) {
             }
             return { seq, type: v.type, commentId: id, resolved: v.resolved };
         }
+        case "offer-dismissed":
+            return isOfferId(v.offer)
+                ? { seq, type: v.type, offer: v.offer }
+                : "offer is not an offer id";
         case "version": {
             if (!isPlanVersion(v.version) || typeof v.hash !== "string")
                 return "malformed version event";
@@ -452,6 +591,11 @@ export function parseEvent(v) {
                 return carried;
             return { seq, type: v.type, version: v.version, hash: v.hash, carried };
         }
+        case "coverage":
+            if (typeof v.tip !== "string" || !isSha(v.tip) || typeof v.takenAt !== "string") {
+                return "malformed coverage event";
+            }
+            return { seq, type: v.type, tip: v.tip, takenAt: v.takenAt };
         case "submitted":
             return { seq, type: v.type };
         case "ended":