@shiyuphan/follow-me 0.9.0 → 0.9.1

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";
@@ -20,6 +20,10 @@ 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";
@@ -47,7 +51,8 @@ Other commands:
                                             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]
@@ -117,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.
 
@@ -157,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;
@@ -176,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`);
 }
@@ -265,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}`;
@@ -316,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`;
@@ -403,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)`);
     }
@@ -559,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. */
@@ -930,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;
         }
     }
@@ -1076,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;
@@ -1136,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;
         }
@@ -1165,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");
@@ -1210,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) {
@@ -1237,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 };
     }
@@ -1276,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;
@@ -1340,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.
@@ -1404,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;
 }
 /**
@@ -1540,7 +1644,11 @@ async function reply(cwd, args) {
         ...(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>]]
@@ -1824,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)) {
@@ -1915,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");
     }
@@ -2136,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,

package/dist/src/comments.js

@@ -1,6 +1,7 @@
 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";
+import { parseRefText } from "./refs.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
@@ -49,26 +50,42 @@ function parseAnchor(v) {
     }
     return { kind: "hunk", unit: v.unit, commit, changes, offsets };
 }
+/** A place written as a ref string (`path:a-b`, tip lines) or as { path, start, end }. */
+function parsePlace(raw) {
+    if (typeof raw !== "string")
+        return parseLoc(raw);
+    const spec = parseRefText(raw);
+    if (spec === null)
+        return null;
+    if (spec.at !== null)
+        return `${JSON.stringify(raw)}: a map is in tip lines; drop the @`;
+    return parseLoc({ path: spec.path, start: spec.start, end: spec.end });
+}
 function parseLocs(v, at, needed) {
-    const what = `${at}: expected a list of { path, start, end }${needed ? " with at least one place" : ""}`;
+    const what = `${at}: expected a list of "path:a-b" or { 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);
+        const loc = parsePlace(raw);
         if (loc === null)
-            return `${at}[${i}]: expected { path, start, end } with 1 <= start <= end`;
+            return `${at}[${i}]: expected "path:a-b" or { path, start, end } with 1 <= start <= end`;
+        if (typeof loc === "string")
+            return `${at}[${i}]: ${loc}`;
         out.push(loc);
     }
     return out;
 }
 const TRANSITION_ENDS = ["from", "to"];
+/** A stateDiagram's start and end marker. */
+const START_END = "[*]";
 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 states of the map, and with a stateDiagram every state name appears in it. A transition
+ * to or from `[*]` is dropped: the diagram marks the start and end. The reason
  * names the bad entry, as map.states.<name>[i] or map.transitions[i].<field>.
  */
 export function parseStateMap(v, diagram) {
@@ -95,6 +112,10 @@ export function parseStateMap(v, diagram) {
         const at = `map.transitions[${i}]`;
         if (!isFields(raw))
             return `${at}: expected { from, to, event, at }`;
+        // The diagram's [*] already marks where the machine starts and ends; a move to or from it
+        // has no code of its own, so it is dropped rather than refused.
+        if (raw.from === START_END || raw.to === START_END)
+            continue;
         for (const end of TRANSITION_ENDS) {
             const state = raw[end];
             if (typeof state !== "string" || !named.has(state)) {

package/dist/src/coverage.js

@@ -272,12 +272,8 @@ export function recordRun(prior, run, at) {
 function testEntry(ran) {
     return { lines: ran.lines, ...(ran.branches.size === 0 ? {} : { branches: ran.branches }) };
 }
-/**
- * Per file, the branch's added rows that lcov calls executable, and how many ran. Every added
- * row is a tip line, which is where the run was taken. Files without such rows are left out.
- */
-export function changedLines(units, files) {
-    const out = new Map();
+/** Calls visit with each added row's tip line, per hunk, for files the run covers. */
+function eachAddedLine(units, files, visit) {
     for (const unit of units.values()) {
         if (unit.kind !== "hunk")
             continue;
@@ -285,22 +281,37 @@ export function changedLines(units, files) {
         if (file === undefined)
             continue;
         let line = tipStartOf(unit, units);
-        let { covered, executable } = out.get(unit.path) ?? { covered: 0, executable: 0 };
         for (const row of unit.body) {
-            const hits = row.op === "+" ? file.lines.get(line) : undefined;
-            if (hits !== undefined) {
-                executable += 1;
-                if (hits > 0)
-                    covered += 1;
-            }
+            if (row.op === "+")
+                visit(unit.path, file, line);
             if (row.op !== "-")
                 line += 1;
         }
-        if (executable > 0)
-            out.set(unit.path, { covered, executable });
     }
+}
+/**
+ * Per file, the branch's added rows that lcov calls executable, and how many ran. Every added
+ * row is a tip line, which is where the run was taken. Files without such rows are left out.
+ */
+export function changedLines(units, files) {
+    const out = new Map();
+    eachAddedLine(units, files, (path, file, line) => {
+        const hits = file.lines.get(line);
+        if (hits === undefined)
+            return;
+        const { covered, executable } = out.get(path) ?? { covered: 0, executable: 0 };
+        out.set(path, { covered: covered + (hits > 0 ? 1 : 0), executable: executable + 1 });
+    });
     return out;
 }
+/** How many branches the run took on the branch's added rows, summed over every decision. */
+export function changedBranchesTaken(units, files) {
+    let taken = 0;
+    eachAddedLine(units, files, (_, file, line) => {
+        taken += file.branches.get(line)?.[0] ?? 0;
+    });
+    return taken;
+}
 export function totalOf(tallies) {
     let covered = 0;
     let executable = 0;

package/dist/src/host.js

@@ -122,6 +122,7 @@ async function loadHosted(registration, held) {
         }
         const verdict = validatePlan(session.diff, serializePlanFile(stored.file), {
             lastReview: session.lastReview(),
+            frozen: true,
         });
         if (!verdict.ok) {
             throw new RegistrationError(`plan v${version} no longer fits ${branch}; check it again`);

package/dist/src/plan.js

@@ -556,12 +556,13 @@ function deriveConcernId(unit, c) {
 }
 /**
  * Gives every concern its id and checks where it sits: lines must be change lines the commit
- * takes, and a unit carries at most one concern across the whole plan.
+ * takes, and a unit carries at most one concern in each commit, so each slice of a hunk split
+ * across commits may carry its own.
  */
 function placeConcerns(diff, file, claims, issues) {
     const ids = new Set();
-    const holders = new Map();
     const placedPerCommit = file.commits.map((commit, k) => {
+        const held = new Map();
         const placed = [];
         const add = (c, unit) => {
             const id = deriveConcernId(unit, c);
@@ -578,7 +579,7 @@ function placeConcerns(diff, file, claims, issues) {
             const concerns = ref.concerns ?? [];
             if (concerns.length === 0)
                 return;
-            holders.set(ref.unit, [...(holders.get(ref.unit) ?? []), ...concerns.map(() => k)]);
+            held.set(ref.unit, (held.get(ref.unit) ?? 0) + concerns.length);
             const taken = claims.resolved[k]?.[j]?.select;
             const unit = diff.units.get(ref.unit);
             for (const c of concerns) {
@@ -591,25 +592,25 @@ function placeConcerns(diff, file, claims, issues) {
                     });
                     continue;
                 }
-                const outside = taken?.kind === "lines" ? lines.filter((n) => !taken.changes.includes(n)) : [];
-                if (outside.length > 0) {
+                const takes = taken?.kind === "lines" ? taken : null;
+                const outside = takes === null ? [] : lines.filter((n) => !takes.changes.includes(n));
+                if (takes !== null && outside.length > 0) {
                     issues.push({
                         kind: "bad-concern",
                         commit: k,
-                        reason: `${ref.unit}: concern lines ${outside.join(", ")} are not change lines this commit takes`,
+                        reason: `${ref.unit}: concern lines ${outside.join(", ")} are not change lines this commit takes; \`lines\` are the hunk's [n] as prompt.md shows them, on a slice too, and this commit takes ${formatUnitRef({ unit: ref.unit, select: takes })}`,
                     });
                 }
                 else
                     add(c, ref.unit);
             }
         });
+        for (const [unit, count] of held) {
+            if (count > 1)
+                issues.push({ kind: "too-many-concerns", unit, commit: k, count });
+        }
         return placed;
     });
-    for (const [unit, commits] of holders) {
-        if (commits.length > 1) {
-            issues.push({ kind: "too-many-concerns", unit, commits: [...new Set(commits)] });
-        }
-    }
     return placedPerCommit;
 }
 /** "o_" + 8 hex over the unit and the label: stable while the offer stays at its place. */
@@ -744,6 +745,36 @@ function answerProblem(file, r, isQuestion) {
  * Parses and checks a draft against the diff: every change line used exactly once, every
  * commit's tree valid, and the last commit equal to the tip. Collects all issues at once.
  */
+/**
+ * Sections read top-down: story, steps, details, wiring. A later section never comes back, so a
+ * commit whose section ranks below an earlier commit's must move ahead of the first such commit.
+ */
+function sectionOrder(file) {
+    const issues = [];
+    const placed = [];
+    file.commits.forEach((c, commit) => {
+        if (c.section === undefined)
+            return;
+        const rank = SECTIONS.indexOf(c.section);
+        const first = placed.find((p) => p.rank > rank);
+        if (first !== undefined) {
+            issues.push({
+                kind: "section-order",
+                commit,
+                section: c.section,
+                before: first.commit,
+                beforeSection: first.section,
+            });
+        }
+        else
+            placed.push({ commit, rank, section: c.section });
+    });
+    return issues;
+}
+/**
+ * Judges a draft against the diff. `frozen` re-checks a plan that already passed when it was
+ * frozen: section order is a rule for drafts, so a plan frozen before it was one still fits.
+ */
 export function validatePlan(diff, draft, opts = {}) {
     const parsed = parsePlanFile(draft);
     if (Array.isArray(parsed))
@@ -766,6 +797,8 @@ export function validatePlan(diff, draft, opts = {}) {
             issues.push({ kind: "empty-commit", commit: k });
     });
     issues.push(...offerLimits(file));
+    if (opts.frozen !== true)
+        issues.push(...sectionOrder(file));
     const assignment = [];
     const claims = claim(diff, file, assignment);
     issues.push(...assignment);
@@ -788,17 +821,6 @@ export function validatePlan(diff, draft, opts = {}) {
         if (length > LONG_TITLE)
             warnings.push({ kind: "long-title", commit, length });
     });
-    // Sections read top-down: story, steps, details, wiring. A later section never comes back.
-    let reached = null;
-    file.commits.forEach((c, commit) => {
-        if (c.section === undefined)
-            return;
-        if (reached !== null && SECTIONS.indexOf(c.section) < SECTIONS.indexOf(reached)) {
-            warnings.push({ kind: "section-order", commit, section: c.section, after: reached });
-        }
-        else
-            reached = c.section;
-    });
     const asked = new Map(review?.comments.map((c) => [c.id, c.kind === "question"]));
     for (const r of file.responses) {
         const isQuestion = asked.get(r.comment);