@shiyuphan/follow-me 0.9.0 → 0.9.2

package/dist/src/cli.js

@@ -1,16 +1,17 @@
 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";
 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 { plainNumber, plainText } from "./plain.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";
@@ -20,6 +21,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 +52,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 +123,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 +164,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 +185,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 +311,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 +376,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 +460,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 +616,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 +987,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;
         }
     }
@@ -1046,9 +1104,18 @@ function readCursor(session, summary) {
     const counts = log === logOf(summary) && typeof seq === "number" && Number.isInteger(seq) && seq >= 0;
     return { session: logOf(summary), seq: counts ? seq : 0, seen };
 }
+const ID_CHARS = "abcdefghijklmnopqrstuvwxyz0123456789_";
+const LOG_CHARS = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-@.:+";
+const CURSOR_ID = /^[a-z]_[a-z0-9]+$/;
+const CURSOR_LOG = /^[\w-]+@[\w.:+-]+$/;
+/** The cursor holds data the server sent, so only ids and a log name of the expected shape are written. */
 function writeCursor(session, cursor) {
     const { session: log, seq, seen } = cursor;
-    writeFileSync(cursorPath(session), `${JSON.stringify({ session: log, seq, seen: [...seen] })}\n`);
+    if (!CURSOR_LOG.test(log) || !Number.isInteger(seq))
+        throw new Error(`refusing to save the cursor for ${log}`);
+    const ids = [...seen].filter((id) => CURSOR_ID.test(id)).map((id) => plainText(id, ID_CHARS));
+    const saved = { session: plainText(log, LOG_CHARS), seq: plainNumber(seq), seen: ids };
+    writeFileSync(cursorPath(session), `${JSON.stringify(saved)}\n`);
 }
 /** The comment or reply id an event first carries, or null for events without one. */
 function saidId(event) {
@@ -1076,11 +1143,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 +1234,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 +1265,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 +1310,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 +1336,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 +1378,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 +1442,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 +1506,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 +1654,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 +1942,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 +2033,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 +2257,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

@@ -5,10 +5,12 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { parseCarried, parseComment, parseEvent, parseEventBatch, } from "./comments.js";
 import { carryComments } from "./evolve.js";
+import { plainNumber, plainText } from "./plain.js";
 import { isPlanVersion, serializePlanFile, validatePlan } from "./plan.js";
 import { HEALTH_APP, isSessionId, loadDraft, PortInUseError, RegistrationError, startServer, } from "./server.js";
 import { BranchMovedError, diffOfPlan, isAlive, openSessionAt, SessionFileError, SessionLockedError, sessionComments, } from "./session.js";
 const RECORD = "server.json";
+const PATH_CHARS = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789/._~-?=&";
 const DEFAULT_IDLE_MS = 30_000;
 const START_TIMEOUT_MS = 10_000;
 const STOP_TIMEOUT_MS = 5_000;
@@ -28,6 +30,13 @@ export function idleMs(env = process.env) {
 function isPort(value) {
     return typeof value === "number" && Number.isInteger(value) && value > 0 && value <= 65535;
 }
+/** Every request this client makes goes to the loopback server, on a port and a path that are plain. */
+function loopbackUrl(port, path) {
+    if (!isPort(port) || !/^\/[\w./~-]*(\?[\w=&.-]*)?$/.test(path)) {
+        throw new RegistrationError("refusing a request to an unexpected address");
+    }
+    return `http://127.0.0.1:${plainNumber(port)}${plainText(path, PATH_CHARS)}`;
+}
 function isFields(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -52,7 +61,7 @@ export function readServerRecord(dir) {
 /** The pid of the follow-me server answering on this port, or null for anything else. */
 export async function probeHealth(port) {
     try {
-        const res = await fetch(`http://127.0.0.1:${port}/api/health`, {
+        const res = await fetch(loopbackUrl(port, "/api/health"), {
             signal: AbortSignal.timeout(1_000),
         });
         const body = await res.json();
@@ -122,6 +131,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`);
@@ -251,7 +261,7 @@ export async function spawnDetached(dir, port) {
     throw new Error(`the review server did not start; see ${logPath}`);
 }
 async function call(port, method, path, body) {
-    const res = await fetch(`http://127.0.0.1:${port}${path}`, {
+    const res = await fetch(loopbackUrl(port, path), {
         method,
         headers: { "content-type": "application/json" },
         ...(body === undefined ? {} : { body: JSON.stringify(body) }),
@@ -356,7 +366,7 @@ export async function pollEvents(port, summary, since, timeoutMs) {
  * the server closes the stream, which it does after the `ended` event.
  */
 export async function followEvents(port, summary, since, onEvent) {
-    const res = await fetch(`${sessionUrl(port, summary)}api/events/stream?since=${since}`);
+    const res = await fetch(loopbackUrl(port, `${summary.url}api/events/stream?since=${Number(since)}`));
     if (!res.ok || res.body === null) {
         throw new RegistrationError(`GET api/events/stream failed with ${res.status}`);
     }
@@ -402,7 +412,7 @@ export async function postCoverage(port, summary) {
 }
 /** The consolidated report of the hosted session as it stands. */
 export async function fetchReport(port, summary, format = "markdown") {
-    const res = await fetch(`${sessionUrl(port, summary)}api/report?format=${format}`);
+    const res = await fetch(loopbackUrl(port, `${summary.url}api/report?format=${format}`));
     if (!res.ok)
         throw new RegistrationError(`GET api/report failed with ${res.status}`);
     return res.text();
@@ -422,7 +432,7 @@ export function sessionUrl(port, summary) {
 /** Whether the server on this port still serves the session's state; a gone server serves none. */
 export async function stillHosted(port, summary) {
     try {
-        const res = await fetch(`${sessionUrl(port, summary)}api/state`, {
+        const res = await fetch(loopbackUrl(port, `${summary.url}api/state`), {
             signal: AbortSignal.timeout(2_000),
         });
         await res.body?.cancel();

package/dist/src/install.js

@@ -60,9 +60,19 @@ export function planSkillFiles(options, home, repoRoot) {
     }
     return [...byPath.values()];
 }
+function readIfPresent(path) {
+    try {
+        return readFileSync(path);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
 function writeSkill(skillDir, file, dryRun) {
     const content = readFileSync(join(skillDir, file.source));
-    const current = existsSync(file.path) ? readFileSync(file.path) : null;
+    const current = readIfPresent(file.path);
     if (current?.equals(content))
         return `unchanged ${file.path}`;
     if (dryRun)

package/dist/src/plain.js

@@ -0,0 +1,20 @@
+const DIGITS = "0123456789";
+/**
+ * Rebuilds `text` one character at a time from `alphabet`, and throws on a character outside it. What comes
+ * back is made only of characters that were checked, so a port read from a file or an id sent by the server
+ * cannot carry anything else into a request address or a file.
+ */
+export function plainText(text, alphabet) {
+    let out = "";
+    for (const char of text) {
+        const at = alphabet.indexOf(char);
+        if (at < 0)
+            throw new Error(`unexpected character ${JSON.stringify(char)}`);
+        out += alphabet.charAt(at);
+    }
+    return out;
+}
+/** A whole number, rebuilt from its digits; throws on anything else. */
+export function plainNumber(value) {
+    return Number(plainText(String(value), DIGITS));
+}