@shiyuphan/follow-me 0.8.0 → 0.9.1

package/README.md

@@ -75,11 +75,16 @@ 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.*
 
+When your agent's answer names code, like `src/lib.js:4-5`, each place becomes a numbered chip. Hover the answer to tint those lines, click a chip to jump there and Alt+Left to come back. An answer that names several places is a walkthrough: press Enter on it, then `.` and `,` to step.
+
+![An agent reply naming three places as numbered chips, one in a later commit, with those lines tinted and numbered in the code and the walkthrough bar at step 1 of 3](assets/screenshots/refs.png)
+*A walkthrough. Each place the agent names is tinted and numbered on the code, the current step strongest, and the bar at the bottom says where you are.*
+
 ![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 checkout state machine reply: each state marked by whether a test reached it, tested transitions green with a count of their tests, one untested transition red and dashed, the sequences no one test drives, and a table naming the tests of each state and move](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. A transition is green with the number of tests that take it, or red and dashed when none does. When the tests run one at a time, the table names them, and a list names the sequences each step of which has a test but no one test drives. Click a state or a transition 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.*
@@ -87,7 +92,7 @@ The red blob in the party hat is your branch tip. Nothing follow-me does moves i
 ![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, `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.
+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, `.` and `,` step through the agent's walkthrough, `?` 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,10 +1,10 @@
 import { execFileSync } from "node:child_process";
-import { readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 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 { changedBranchesTaken, changedLines, LcovError, PREVIEW_LINES, parseLcov, parseLocArg, recordRun, runOf, tipPlacer, totalOf, } from "./coverage.js";
 import { definitionIndex, isIdentifier } from "./definition.js";
 import { DiffParseError, formatUnitRef, isRepoPath, isUnitId, splitLines } from "./diff.js";
 import { BranchRefusedError, blobsAt, branchHead, GitError, isOwnWork, pathsAt, pathsChanged, signing, treeOf, writeBranch, } from "./git.js";
@@ -13,12 +13,17 @@ import { findSkillDir, InstallError, runInstall, runUninstall, syncSkills, } fro
 import { naiveDraft } from "./naive.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 { parseRefText, refsIn, repoPathOfTyped, resolveRefs } from "./refs.js";
 import { RegistrationError, sessionIdOf } from "./server.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";
 }
+/** `--help` or `-h` anywhere a command reads its options; main prints that command's usage. */
+class HelpRequested extends Error {
+    name = "HelpRequested";
+}
 /** A test run follow-me will not record, with the reason the agent can act on. */
 class CoverageError extends Error {
     name = "CoverageError";
@@ -38,15 +43,16 @@ Other commands:
                                             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>
+  show <h_…|c_…|k_…|path:a[-b][@n|@base]|name>
                                             print a unit, a comment's thread, a concern, the
-                                            lines around path:line in commit n, or where a name
+                                            lines around path:a-b in commit n, or where a name
                                             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
+                                            --at is where the test is declared; --reset alone
+                                            clears it before per-test runs
 
 help --all lists every command.`;
 const USAGE = `usage: follow-me <command> [options]
@@ -92,16 +98,17 @@ Interactive loop (while the review page is open):
   reply <commentId> --body <text> [--diagram <file> [--map <file>]]
                                             answer under a comment on the page; the diagram is
                                             Mermaid source, the map JSON tying its states to
-                                            tip lines
+                                            tip lines. \`path:a-b[@n]\` in backticks in the body
+                                            points at code, and is refused if it does not exist
   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
                                             from 1; with no target it is about the whole plan.
                                             watch leaves these out like your replies
-  show <h_…|c_…|k_…|path:line[@n|@base]|name> [--branch <name>]
+  show <h_…|c_…|k_…|path:a[-b][@n|@base]|name> [--branch <name>]
                                             print a unit with the commits that take it, a
                                             comment with its rows and thread, a concern with its
-                                            lines, the lines around path:line at the tip, in
+                                            lines, the lines around path:a-b at the tip, in
                                             commit n of the plan, or in the base, or each place
                                             a name is defined at the tip with the commit it
                                             lands in
@@ -115,7 +122,8 @@ Interactive loop (while the review page is open):
                                             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.
+                                            --test runs add one test each, --at is the line
+                                            where that test is declared.
                                             --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.
 
@@ -155,6 +163,8 @@ function parseArgs(argv, spec) {
     const flags = new Set();
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i] ?? "";
+        if (arg === "--help" || arg === "-h")
+            throw new HelpRequested();
         if (!arg.startsWith("--")) {
             positionals.push(arg);
             continue;
@@ -174,6 +184,43 @@ function parseArgs(argv, spec) {
     }
     return { positionals, values, flags };
 }
+/**
+ * The usage of one command, read from its entries in USAGE: the synopsis, then what it does.
+ * Null for a command USAGE does not list.
+ */
+function usageOf(command) {
+    const blocks = [];
+    let block = null;
+    for (const line of USAGE.split("\n")) {
+        if (line.startsWith(`  ${command} `) || line === `  ${command}`) {
+            block = [line];
+            blocks.push(block);
+        }
+        else if (block !== null && line.startsWith("    "))
+            block.push(line);
+        else
+            block = null;
+    }
+    if (blocks.length === 0)
+        return null;
+    return blocks
+        .map((lines) => {
+        const synopsis = [];
+        const what = [];
+        for (const line of lines) {
+            const [left = "", right = ""] = line.trim().split(/\s{3,}/, 2);
+            if (/^\s{20,}/.test(line))
+                what.push(left);
+            else {
+                synopsis.push(left);
+                if (right !== "")
+                    what.push(right);
+            }
+        }
+        return [`usage: follow-me ${synopsis.join(" ")}`, ...what.map((w) => `  ${w}`)].join("\n");
+    })
+        .join("\n");
+}
 function say(line = "") {
     process.stdout.write(`${line}\n`);
 }
@@ -263,45 +310,59 @@ function summarize(session, cwd) {
     }
     say(`session ${relative(cwd, session.dir) || "."}`);
 }
+/** Commits are numbered from 1 in everything the agent reads; issues carry 0-based indices. */
+function commitName(k) {
+    return `commit ${k + 1}`;
+}
+/** A JSON path into the draft with its commit named from 1: `$.commits[2].units[0]` reads `commit 3, units[0]`. */
+function jsonPlace(at) {
+    const m = /^\$\.commits\[(\d+)\]\.?(.*)$/.exec(at);
+    if (m === null)
+        return at;
+    const [, k = "0", rest = ""] = m;
+    return rest === "" ? commitName(Number(k)) : `${commitName(Number(k))}, ${rest}`;
+}
 function formatIssue(issue) {
     switch (issue.kind) {
         case "malformed":
-            return `malformed ${issue.at}: ${issue.reason}`;
+            return `malformed ${jsonPlace(issue.at)}: ${issue.reason}`;
         case "stale":
             return `stale: the plan is for tip ${short(issue.planTip)} but the session tip is ${short(issue.sessionTip)}`;
         case "empty-message":
-            return `$.commits[${issue.commit}]: empty message`;
+            return `${commitName(issue.commit)}: empty message`;
         case "empty-commit":
-            return `$.commits[${issue.commit}]: no units`;
+            return `${commitName(issue.commit)}: no units`;
         case "unknown-unit":
-            return `$.commits[${issue.commit}]: unknown unit ${issue.ref}`;
+            return `${commitName(issue.commit)}: unknown unit ${issue.ref}`;
         case "bad-selection":
-            return `$.commits[${issue.commit}]: ${issue.unit}: ${issue.reason}`;
+            return `${commitName(issue.commit)}: ${issue.unit}: ${issue.reason}`;
         case "duplicate": {
             const [a, b] = issue.commits;
             const what = issue.changes.length > 0 ? lines(issue.unit, issue.changes) : issue.unit;
-            return `${what} is claimed by commits ${a} and ${b}`;
+            return `${what} is claimed by commits ${a + 1} and ${b + 1}`;
         }
         case "unassigned": {
             const what = issue.changes.length > 0 ? lines(issue.unit, issue.changes) : issue.unit;
             return `${what} (${show(issue.path)}) is in no commit`;
         }
         case "path-conflict":
-            return `$.commits[${issue.commit}]: ${show(issue.file)} is a file while ${show(issue.under)} exists`;
+            return `${commitName(issue.commit)}: ${show(issue.file)} is a file while ${show(issue.under)} exists`;
         case "unknown-response":
             return `response to unknown comment ${issue.comment}`;
         case "bad-answer":
             return `response to ${issue.comment}: ${issue.reason}`;
+        case "section-order":
+            return `${commitName(issue.commit)}: section ${issue.section} comes after ${commitName(issue.before)} in ${issue.beforeSection}; sections read story, steps, details, wiring, so move ${commitName(issue.commit)} before ${commitName(issue.before)}, or change its section`;
         case "bad-concern":
-            return `$.commits[${issue.commit}]: concern: ${issue.reason}`;
+            return `${commitName(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`;
+            return `${commitName(issue.commit)}: ${issue.unit} has ${issue.count} concerns; a unit takes one per commit (each slice of a split hunk may carry its own), so keep the one that matters`;
         case "bad-offer":
-            return `$.commits[${issue.commit}]: offer: ${issue.reason}`;
+            return `${commitName(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`;
+                : `${commitName(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}`;
@@ -314,10 +375,7 @@ function formatIssue(issue) {
 }
 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`;
+        return `warning: ${commitName(w.commit)}: title is ${w.length} characters; keep it to 50`;
     }
     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`;
@@ -401,7 +459,7 @@ function syntaxOverride(args) {
     return { override };
 }
 function formatSyntax(report, mark = "") {
-    const out = report.issues.map((i) => `${mark}$.commits[${i.commit}]: ${show(i.path)}: ${i.message}`);
+    const out = report.issues.map((i) => `${mark}${commitName(i.commit)}: ${show(i.path)}: ${i.message}`);
     for (const i of report.tip) {
         out.push(`${mark}${show(i.path)}: ${i.message} (the tip itself does not parse here, so earlier commits are not checked for it)`);
     }
@@ -557,7 +615,7 @@ function projectedCommits(session, version) {
     const plan = session.plans().find((p) => p.version === version);
     if (plan === undefined)
         return [];
-    const verdict = validatePlan(session.diff, serializePlanFile(plan.file));
+    const verdict = validatePlan(session.diff, serializePlanFile(plan.file), { frozen: true });
     return verdict.ok ? verdict.plan.commits : [];
 }
 /** Writes the one-commit-per-file draft with no agent. */
@@ -928,7 +986,8 @@ function reviewedPlan(session) {
     const reviews = reviewsOf(session);
     for (const stored of reviews.toReversed()) {
         const plan = session.plans().find((p) => p.version === stored.version);
-        if (plan !== undefined && validatePlan(session.diff, serializePlanFile(plan.file)).ok) {
+        if (plan !== undefined &&
+            validatePlan(session.diff, serializePlanFile(plan.file), { frozen: true }).ok) {
             return stored;
         }
     }
@@ -1074,11 +1133,42 @@ async function offerStep(port, summary) {
         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`;
 }
+/** The per-test step while a state map waits for it, said as a `next:` of the listening loop. */
+async function testsStep(session, open, cwd) {
+    if (!(await mapWantsTests(session, open)))
+        return null;
+    return `${STILL_WORKING}; ${perTestStep(session, cwd)}; then run follow-me again`;
+}
+/**
+ * Where the agent writes lcov files, relative to cwd: inside the session, which `.follow-me/`'s
+ * own .gitignore hides and which goes when the session goes, so no run leaves a file in the repo.
+ */
+function lcovDir(session, cwd) {
+    const dir = join(session.dir, "lcov");
+    mkdirSync(dir, { recursive: true });
+    return relative(cwd, dir);
+}
+/** The aggregate run to take when a review opens. */
+function coverageStep(session, cwd) {
+    return `if the project has tests, run them with coverage at the tip, lcov to ${lcovDir(session, cwd)}/all.info, and pass it to follow-me coverage`;
+}
+/** The per-test runs a state map needs for its badges and its "Not driven" list. */
+function perTestStep(session, cwd) {
+    const dir = lcovDir(session, cwd);
+    return `the state machine needs one coverage run per test: follow-me coverage --reset, then for each test run it alone with lcov to ${dir}/<n>.info and follow-me coverage ${dir}/<n>.info --test "<test name>" --at <path:line where it is declared>`;
+}
+/** Whether a reply of the hosted review carries a state map while no run has per-test detail. */
+async function mapWantsTests(session, open) {
+    if ((session.coverage()?.tests.size ?? 0) > 0)
+        return false;
+    const said = await fetchComments(open.port, open.summary);
+    return said.some(({ comments }) => comments.some((c) => (c.replies ?? []).some((r) => r.map !== undefined)));
+}
 /**
  * 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.
  */
-async function listen(session, open, args) {
+async function listen(session, open, args, cwd) {
     const { port, summary } = open;
     const waitMs = waitOf(args) * 1000;
     const deadline = Date.now() + waitMs;
@@ -1134,11 +1224,13 @@ async function listen(session, open, args) {
                 return 0;
             }
             next((await offerStep(port, summary)) ??
+                (await testsStep(session, open, cwd)) ??
                 `${STILL_WORKING}; answer with follow-me reply <id> --body "<markdown>" [--diagram file], then run follow-me again`);
             return 0;
         }
         if (left <= 0) {
             next((await offerStep(port, summary)) ??
+                (await testsStep(session, open, cwd)) ??
                 `${STILL_WORKING}; run follow-me again to keep listening`);
             return 0;
         }
@@ -1163,7 +1255,7 @@ async function entry(cwd, args) {
             return swapOpenPage(session, hosted, args);
     }
     if (hosted !== null)
-        return listen(session, hosted, args);
+        return listen(session, hosted, args, cwd);
     const state = draftState(session);
     if (state.kind === "invalid") {
         next("fix the draft, then run follow-me again");
@@ -1208,11 +1300,10 @@ 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");
-    }
+    if (session.coverage() === null)
+        next(coverageStep(session, cwd));
     say("follow-me is interactive: keep running it until it prints the report");
-    return listen(session, result, args);
+    return listen(session, result, args, cwd);
 }
 /** Opens the session, re-extracting instead of failing when the branch moved or --base changed. */
 async function openFresh(cwd, args) {
@@ -1235,7 +1326,10 @@ function walkablePlan(session) {
     const lastReview = session.lastReview();
     const stored = session.plans().at(-1);
     if (stored !== undefined) {
-        const verdict = validatePlan(session.diff, serializePlanFile(stored.file), { lastReview });
+        const verdict = validatePlan(session.diff, serializePlanFile(stored.file), {
+            lastReview,
+            frozen: true,
+        });
         if (verdict.ok)
             return { version: stored.version, plan: verdict.plan };
     }
@@ -1274,7 +1368,7 @@ async function renderStored(session, stored, format = "markdown") {
         console.error(`follow-me: review v${stored.version} refers to a plan that is missing`);
         return null;
     }
-    const verdict = validatePlan(session.diff, serializePlanFile(plan.file));
+    const verdict = validatePlan(session.diff, serializePlanFile(plan.file), { frozen: true });
     if (!verdict.ok) {
         console.error(`follow-me: plan v${plan.version} no longer fits ${session.anchor.branch}`);
         return null;
@@ -1338,7 +1432,7 @@ async function report(cwd, args, walkOnly = false) {
     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";
+const COVERAGE_USAGE = "usage: follow-me coverage <lcov> [--test <id> [--at <path:line>]] [--reset]\n       follow-me coverage --reset\n--at is the path:line where the test is declared";
 /**
  * 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.
@@ -1402,7 +1496,19 @@ async function coverage(cwd, args) {
     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`);
+    const total = `coverage for ${plural(recorded.files.size, "file")} at ${short(tip)}; ${covered} of ${executable} changed lines covered`;
+    if (test === undefined)
+        say(total);
+    else {
+        // A per-test run adds to what is on record, so its own share is said apart from the total.
+        const own = totalOf(changedLines(session.diff.units, run.files).values()).covered;
+        const branches = changedBranchesTaken(session.diff.units, run.files);
+        say(`recorded test ${JSON.stringify(test.id)}: ${plural(own, "changed line")}, ${branches === 1 ? "1 branch" : `${branches} branches`}`);
+        say(`running total of ${plural(recorded.tests.size, "test")}: ${total}`);
+    }
+    if (test === undefined && open !== null && (await mapWantsTests(session, open))) {
+        next(`${perTestStep(session, cwd)}; then run follow-me again`);
+    }
     return 0;
 }
 /**
@@ -1529,14 +1635,20 @@ async function reply(cwd, args) {
     const open = await openOnServer(session, null);
     if (open === null)
         return notOpen(session);
+    const refs = await bodyRefs(session, open.summary.version, body);
     const id = await postReply(open.port, open.summary, commentId, {
         author: "agent",
         body,
         ...(diagram === undefined ? {} : { diagram }),
         ...(map === undefined ? {} : { map }),
+        ...(refs.length === 0 ? {} : { refs }),
     });
     say(`replied ${id} to ${commentId}`);
-    next(`run follow-me again; ${STILL_WORKING}`);
+    if (map !== undefined && (session.coverage()?.tests.size ?? 0) === 0) {
+        next(`${perTestStep(session, cwd)}; then run follow-me again; ${STILL_WORKING}`);
+    }
+    else
+        next(`run follow-me again; ${STILL_WORKING}`);
     return 0;
 }
 const REPLY_USAGE = `usage: follow-me reply <commentId> --body <text> [--diagram <file> [--map <file>]]
@@ -1586,6 +1698,33 @@ async function readMap(session, file, diagram) {
         throw new UsageError(`${file}:\n  ${problems.join("\n  ")}`);
     return map;
 }
+/**
+ * The refs --body writes, resolved against plan `version` and the tip. Every one that does not
+ * resolve is named at once, as --map's are.
+ */
+async function bodyRefs(session, version, body) {
+    const specs = refsIn(body);
+    if (specs.length === 0)
+        return [];
+    const { root, diff } = session;
+    const otherChanged = new Set([...diff.units.values()].flatMap((u) => (diff.textFiles.has(u.path) ? [] : [u.path])));
+    const asked = [...new Set(specs.map((s) => repoPathOfTyped(s.path)))].filter((p) => isRepoPath(p) && !diff.textFiles.has(p) && !otherChanged.has(p));
+    const tip = asked.length === 0 ? new Set() : await pathsAt(root, diff.tip);
+    const present = asked.filter((p) => tip.has(p));
+    const unchanged = new Map([...(await blobsAt(root, diff.tip, present))].map(([p, bytes]) => [p, splitLines(bytes)]));
+    const { refs, problems } = resolveRefs(specs, {
+        tip: diff.tip,
+        textFiles: diff.textFiles,
+        otherChanged,
+        unchanged,
+        commits: projectedCommits(session, version),
+        version,
+    });
+    if (problems.length > 0) {
+        throw new UsageError(`--body points at code that does not resolve:\n  ${problems.join("\n  ")}`);
+    }
+    return refs;
+}
 /** The Mermaid source in --diagram's file, or undefined without the flag. */
 function diagramOf(args) {
     const file = args.values.get("diagram");
@@ -1693,17 +1832,19 @@ async function explain(cwd, args) {
     if (open === null)
         return notOpen(session);
     const target = explainTarget(session, open.summary.version, args);
+    const refs = await bodyRefs(session, open.summary.version, body);
     const id = await postComment(open.port, open.summary, {
         ...target,
         body,
         author: "agent",
         ...(diagram === undefined ? {} : { diagram }),
+        ...(refs.length === 0 ? {} : { refs }),
     });
     say(`explained ${id}`);
     next(`run follow-me again; ${STILL_WORKING}`);
     return 0;
 }
-const SHOW_USAGE = "usage: follow-me show <h_…|c_…|k_…|path:line[@<commit>|@base]|name>";
+const SHOW_USAGE = "usage: follow-me show <h_…|c_…|k_…|path:a[-b][@<commit>|@base]|name>";
 /** Every comment the session has, with the plan version it was made on: live ones first. */
 async function knownComments(session) {
     const open = await openOnServer(session, null);
@@ -1717,14 +1858,16 @@ async function knownComments(session) {
 }
 const SHOW_MARGIN = 3;
 /**
- * The lines around path:line as commit `at` of the latest plan writes the file (1-based), the
- * base, or the tip when `at` is undefined. Read from the plan, so it works before any apply.
+ * The lines around path:a-b as commit `at` of the latest plan writes the file (1-based), the
+ * base, or the tip when `at` is null. Read from the plan, so it works before any apply.
  */
 function showLines(session, raw) {
-    const m = /^(.+):(\d+)(?:@(\d+|base))?$/.exec(raw);
-    const [, typed, lineRaw, at] = m ?? [];
-    if (typed === undefined || lineRaw === undefined)
+    const spec = parseRefText(raw);
+    if (spec === null)
         throw new UsageError(SHOW_USAGE);
+    const { path: typed, start, end, at } = spec;
+    if (end < start)
+        throw new UsageError(`${raw} ends before it starts`);
     const path = Buffer.from(typed, "utf8").toString("latin1");
     const file = [...session.diff.textFiles.values()].find((f) => f.path === path);
     if (file === undefined) {
@@ -1732,7 +1875,7 @@ function showLines(session, raw) {
     }
     let text;
     let label;
-    if (at === undefined) {
+    if (at === null) {
         text = file.tip?.bytes ?? null;
         label = "the tip";
     }
@@ -1743,7 +1886,7 @@ function showLines(session, raw) {
     else {
         const latest = session.plans().at(-1);
         const commits = latest === undefined ? [] : projectedCommits(session, latest.version);
-        const n = Number(at);
+        const n = at;
         if (n < 1 || n > commits.length) {
             throw new UsageError(`@${at} is not one of the ${commits.length} commits of the plan`);
         }
@@ -1762,18 +1905,18 @@ function showLines(session, raw) {
     const lines = Buffer.from(text, "latin1").toString("utf8").split("\n");
     if (lines.at(-1) === "")
         lines.pop();
-    const line = Number(lineRaw);
-    if (line < 1 || line > lines.length) {
+    if (start < 1 || end > lines.length) {
         return `${typed} has ${plural(lines.length, "line")} in ${label}\n`;
     }
-    const from = Math.max(1, line - SHOW_MARGIN);
-    const to = Math.min(lines.length, line + SHOW_MARGIN);
+    const from = Math.max(1, start - SHOW_MARGIN);
+    const to = Math.min(lines.length, end + SHOW_MARGIN);
     const width = String(to).length;
     const rows = lines.slice(from - 1, to).map((l, i) => {
         const n = from + i;
-        return `${n === line ? ">" : " "} ${String(n).padStart(width)}  ${l}`;
+        return `${n >= start && n <= end ? ">" : " "} ${String(n).padStart(width)}  ${l}`;
     });
-    return `${typed}:${line} in ${label}\n${rows.join("\n")}\n`;
+    const span = end > start ? `${start}-${end}` : `${start}`;
+    return `${typed}:${span} in ${label}\n${rows.join("\n")}\n`;
 }
 /** Expands a ref the agent was given to the lines and thread it names, so no file read is needed. */
 async function showRef(cwd, args) {
@@ -1789,7 +1932,7 @@ async function showRef(cwd, args) {
             throw new UsageError(`${ref} is not a unit of the branch now; its hunk changed`);
         }
         const commits = latest === undefined ? [] : projectedCommits(session, latest.version);
-        process.stdout.write(renderShownUnit(unit, commits));
+        process.stdout.write(renderShownUnit(unit, units, commits));
         return 0;
     }
     if (/^c_[a-z2-7]{6}$/.test(ref) && isCommentId(ref)) {
@@ -1880,6 +2023,9 @@ async function serverCommand(argv) {
             await started.host.closed;
             return 0;
         }
+        case "--help":
+        case "-h":
+            throw new HelpRequested();
         default:
             throw new UsageError("usage: follow-me server status|stop");
     }
@@ -2101,6 +2247,11 @@ export async function main(argv, cwd) {
         }
     }
     catch (error) {
+        if (error instanceof HelpRequested) {
+            const asked = command === undefined || command === "help" ? null : usageOf(command);
+            say(asked ?? SHORT_USAGE);
+            return 0;
+        }
         const known = [
             UsageError,
             CoverageError,