@shiyuphan/follow-me 0.6.0 → 0.7.1

package/README.md

@@ -75,13 +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.*
 
+![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 diagram opened in the lightbox at full size](assets/screenshots/diagram.png)
 *Diagrams sit full width under the commit or reply they explain, and open full size on click.*
 
 ![The hand-off page: every kept item with its original-branch path and line, an include checkbox, and copy buttons](assets/screenshots/handoff.png)
 *Submit review. Each item carries the original branch's path and line, so your agent can post it to the merge request as is.*
 
-Keys: `[` shows or hides the index, `j` and `k` move between commits, Cmd-click (Ctrl-click) goes to a definition and Alt+Left comes back, arrows and Shift+arrows pick rows inside a hunk, `c` comments on the pick, `v` marks a commit viewed, `?` lists the rest. An unfinished review autosaves and comes back when the page is opened again.
+Keys: `[` shows or hides the index, `j` and `k` move between commits, Cmd-click (Ctrl-click) goes to a definition and Alt+Left comes back, arrows and Shift+arrows pick rows inside a hunk, `c` comments on the pick, `v` marks a commit viewed, `g` shows or hides coverage and `x` jumps to the next uncovered line, `?` lists the rest. An unfinished review autosaves and comes back when the page is opened again.
 
 ### Reviewing someone else's branch
 

package/dist/src/cli.js

@@ -1,22 +1,27 @@
 import { execFileSync } from "node:child_process";
 import { readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join, relative } from "node:path";
+import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { changedLines, LcovError, parseLcov, parseLocArg, recordRun, runOf, tipPlacer, totalOf, } from "./coverage.js";
 import { definitionIndex, isIdentifier } from "./definition.js";
 import { DiffParseError, formatUnitRef, isUnitId } from "./diff.js";
-import { BranchRefusedError, branchHead, GitError, isOwnWork, signing, treeOf, writeBranch, } from "./git.js";
-import { fetchCarried, fetchComments, fetchReport, findServer, followEvents, idleMs, listSessions, openBrowser, pollEvents, portFallbackMessage, postComment, postReply, probeHealth, readServerRecord, registerWith, sessionUrl, spawnDetached, startOrAttach, stateDir, stillHosted, stopServer, swapVersion, } from "./host.js";
+import { BranchRefusedError, branchHead, GitError, isOwnWork, pathsAt, pathsChanged, signing, treeOf, writeBranch, } from "./git.js";
+import { fetchCarried, fetchComments, fetchReport, findServer, followEvents, idleMs, listSessions, openBrowser, pollEvents, portFallbackMessage, postComment, postCoverage, postReply, probeHealth, readServerRecord, registerWith, sessionUrl, spawnDetached, startOrAttach, stateDir, stillHosted, stopServer, swapVersion, } from "./host.js";
 import { findSkillDir, InstallError, runInstall, runUninstall, syncSkills, } from "./install.js";
 import { naiveDraft } from "./naive.js";
 import { isCommentId, isConcernId, isFields, serializePlanFile, validatePlan, } from "./plan.js";
 import { renderEvents, renderPrompt, renderReport, renderShownComment, renderShownConcern, renderShownDefinitions, renderShownUnit, reportItems, } from "./prompt.js";
 import { RegistrationError, sessionIdOf } from "./server.js";
-import { BranchMovedError, cleanSessions, extractSession, MissingDraftError, NotARepositoryError, openSession, SessionFileError, SessionLockedError, sessionComments, sinceLastPlan, } from "./session.js";
+import { BranchMovedError, cleanSessions, coverageAt, extractSession, MissingDraftError, NotARepositoryError, openSession, SessionFileError, SessionLockedError, sessionComments, sinceLastPlan, } from "./session.js";
 import { checkSyntax } from "./syntax.js";
 class UsageError extends Error {
     name = "UsageError";
 }
+/** A test run follow-me will not record, with the reason the agent can act on. */
+class CoverageError extends Error {
+    name = "CoverageError";
+}
 const SHORT_USAGE = `usage: follow-me [--wait <seconds>] [--branch <name>]
 
 Run follow-me with no command. Each call does the next thing that is missing and returns: it
@@ -37,6 +42,8 @@ Other commands:
                                             is defined, instead of reading files
   report [--json] [--markdown]              print the report of the latest review; --json lists
                                             the items to post to a merge request
+  coverage <lcov> [--test <id> [--at <path:line>]]
+                                            record a test run taken at the tip for the page
 
 help --all lists every command.`;
 const USAGE = `usage: follow-me <command> [options]
@@ -100,6 +107,11 @@ Interactive loop (while the review page is open):
                                             line in both voices, then questions with answers;
                                             --json lists the items to post to a merge request
                                             (path, lines, severity, body, thread, excluded)
+  coverage <lcov> [--test <id> [--at <path:line>]] [--branch <name>]
+                                            record the lcov of a test run at the branch tip;
+                                            refuses when a covered file in the working tree
+                                            differs from the tip. A plain run replaces the last;
+                                            --test runs add one test each, --at is where it is
   apply, while the page is open, swaps it to the new plan version in place, same URL.
 
 Old names, still working:
@@ -909,8 +921,8 @@ function reviewedPlan(session) {
     return null;
 }
 /** Prints the finished review's report, which is what the agent works from from here on. */
-function finished(session, stored) {
-    const text = renderStored(session, stored);
+async function finished(session, stored) {
+    const text = await renderStored(session, stored);
     if (text === null)
         return 1;
     // A review that swapped versions holds what its earlier versions said too.
@@ -1173,6 +1185,9 @@ async function entry(cwd, args) {
     const result = await hostReview(session, mode, detached, async () => prep, reportSaved);
     if (result.kind !== "elsewhere")
         return exitCode(result);
+    if (session.coverage() === null) {
+        next("if the project has tests, run them with coverage at the tip and pass the lcov to follow-me coverage");
+    }
     say("follow-me is interactive: keep running it until it prints the report");
     return listen(session, result, args);
 }
@@ -1230,7 +1245,7 @@ async function walkPlan(session, args) {
     return alreadyReviewed(session, latest.version, args) ? null : latest;
 }
 /** The consolidated report of a saved review, or null after saying why it cannot be rendered. */
-function renderStored(session, stored, format = "markdown") {
+async function renderStored(session, stored, format = "markdown") {
     const plan = session.plans().find((p) => p.version === stored.version);
     if (plan === undefined) {
         console.error(`follow-me: review v${stored.version} refers to a plan that is missing`);
@@ -1258,7 +1273,13 @@ function renderStored(session, stored, format = "markdown") {
                 concerns: stored.review.carriedConcerns ?? [],
             },
         };
-    const opts = { branch: session.anchor.branch, responses, ...earlier };
+    const coverage = await coverageAt(session.root, session.dir, session.anchor.tip);
+    const opts = {
+        branch: session.anchor.branch,
+        responses,
+        ...earlier,
+        ...(coverage === null ? {} : { coverage }),
+    };
     if (format === "json") {
         const items = reportItems(stored.review, verdict.plan.commits, session.diff.units, opts);
         return `${JSON.stringify(items, null, 2)}\n`;
@@ -1288,12 +1309,67 @@ async function report(cwd, args, walkOnly = false) {
         console.error("follow-me: no review is open and none has ended; run `follow-me review` first");
         return 1;
     }
-    const text = renderStored(session, stored, format);
+    const text = await renderStored(session, stored, format);
     if (text === null)
         return 1;
     process.stdout.write(text);
     return 0;
 }
+const COVERAGE_USAGE = "usage: follow-me coverage <lcov> [--test <id> [--at <path:line>]]";
+/**
+ * Records the lcov of a test run the agent made at the tip in the session's coverage.json and
+ * prints how much of the branch's changed code it ran. follow-me never runs the tests itself.
+ */
+async function coverage(cwd, args) {
+    const [file, extra] = args.positionals;
+    const id = args.values.get("test");
+    const atArg = args.values.get("at");
+    if (file === undefined || extra !== undefined)
+        throw new UsageError(COVERAGE_USAGE);
+    if (atArg !== undefined && id === undefined) {
+        throw new UsageError(`--at needs --test\n${COVERAGE_USAGE}`);
+    }
+    let text;
+    try {
+        text = readFileSync(resolve(cwd, file), "utf8");
+    }
+    catch {
+        throw new UsageError(`cannot read ${file}`);
+    }
+    const records = parseLcov(text);
+    const session = await openFresh(cwd, args);
+    const { tip } = session.anchor;
+    const place = tipPlacer(session.root, cwd, await pathsAt(session.root, tip));
+    const run = runOf(records, place);
+    if (run.files.size === 0) {
+        throw new CoverageError(`none of the ${plural(new Set(records.map((r) => r.path)).size, "file")} in ${file} is in ${session.anchor.branch} at the tip; run follow-me coverage from the directory the tests ran in`);
+    }
+    const changed = await pathsChanged(session.root, tip, null);
+    const differ = [...run.files.keys()].filter((p) => changed.has(p));
+    if (differ.length > 0) {
+        throw new CoverageError(`coverage must be taken on the tip; these files differ: ${differ.map(show).join(", ")}`);
+    }
+    let test;
+    if (id !== undefined) {
+        const at = atArg === undefined ? undefined : parseLocArg(atArg, place);
+        if (typeof at === "string")
+            throw new UsageError(at);
+        test = { id, ...(at === undefined ? {} : { at }) };
+    }
+    const takenAt = new Date().toISOString();
+    const recorded = recordRun(session.coverage(), run, {
+        tip,
+        takenAt,
+        ...(test === undefined ? {} : { test }),
+    });
+    session.writeCoverage(recorded);
+    const open = await openOnServer(session, null);
+    if (open !== null)
+        await postCoverage(open.port, open.summary);
+    const { covered, executable } = totalOf(changedLines(session.diff.units, recorded.files).values());
+    say(`coverage for ${plural(recorded.files.size, "file")} at ${short(tip)}; ${covered} of ${executable} changed lines covered`);
+    return 0;
+}
 /** The old name of report. */
 async function feedback(cwd, args) {
     console.error("follow-me: feedback is now report; printing the same");
@@ -1302,9 +1378,12 @@ async function feedback(cwd, args) {
 function isCommentEvent(event) {
     return event.type === "comment" || event.type === "comment-updated";
 }
-/** Events the reviewer caused; the agent's own replies, explanations and version swaps are not news. */
+/**
+ * Events the reviewer caused; the agent's own replies, explanations, version swaps and coverage
+ * are not news.
+ */
 function isNews(event) {
-    if (event.type === "version")
+    if (event.type === "version" || event.type === "coverage")
         return false;
     if (event.type === "comment" || event.type === "comment-updated") {
         return event.comment.author !== "agent";
@@ -1878,6 +1957,8 @@ export async function main(argv, cwd) {
             }
             case "show":
                 return await showRef(cwd, parseArgs(rest, { values: ["branch"] }));
+            case "coverage":
+                return await coverage(cwd, parseArgs(rest, { values: ["test", "at", "branch"] }));
             case "report":
                 return await report(cwd, parseArgs(rest, { values: ["branch"], flags: ["json", "markdown"] }));
             case "clean": {
@@ -1918,6 +1999,8 @@ export async function main(argv, cwd) {
     catch (error) {
         const known = [
             UsageError,
+            CoverageError,
+            LcovError,
             BranchMovedError,
             BranchRefusedError,
             SessionFileError,

package/dist/src/comments.js

@@ -1,4 +1,4 @@
-import { isRepoPath, isUnitId } from "./diff.js";
+import { isRepoPath, isSha, isUnitId } from "./diff.js";
 import { diagramProblem, isArray, isCommentId, isConcernId, isFields, isPlanVersion, isSeverity, parsePlacedConcern, } from "./plan.js";
 /**
  * The wire formats of review state, parsed once at the boundary: comments, replies, concern
@@ -452,6 +452,11 @@ export function parseEvent(v) {
                 return carried;
             return { seq, type: v.type, version: v.version, hash: v.hash, carried };
         }
+        case "coverage":
+            if (typeof v.tip !== "string" || !isSha(v.tip) || typeof v.takenAt !== "string") {
+                return "malformed coverage event";
+            }
+            return { seq, type: v.type, tip: v.tip, takenAt: v.takenAt };
         case "submitted":
             return { seq, type: v.type };
         case "ended":

package/dist/src/coverage.js

@@ -0,0 +1,397 @@
+import { realpathSync } from "node:fs";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { isRepoPath, isSha, tipStartOf } from "./diff.js";
+import { GitError, pathsChanged } from "./git.js";
+import { isFields } from "./plan.js";
+/** lcov input that cannot be read, with the 1-based line it fails on. */
+export class LcovError extends Error {
+    name = "LcovError";
+    line;
+    constructor(line, reason) {
+        super(`lcov line ${line}: ${reason}`);
+        this.line = line;
+    }
+}
+const RECORD = /^([A-Z][A-Z0-9_]*):(.*)$/;
+const DA = /^([1-9][0-9]*),([0-9]+)(?:,.*)?$/;
+const BRDA = /^([1-9][0-9]*),([^,]+),(.+),(-|[0-9]+)$/;
+/**
+ * Reads lcov's tracefile format: TN names the test of the records after it, SF opens a file, DA
+ * and BRDA give line and branch hits, end_of_record closes it. Other records are skipped.
+ */
+export function parseLcov(text) {
+    const records = [];
+    let test = null;
+    let open = null;
+    const close = () => {
+        if (open !== null)
+            records.push(open);
+        open = null;
+    };
+    const rows = text.split("\n");
+    for (const [i, raw] of rows.entries()) {
+        const n = i + 1;
+        const row = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+        if (row.trim() === "")
+            continue;
+        if (row === "end_of_record") {
+            close();
+            continue;
+        }
+        const m = RECORD.exec(row);
+        if (m === null)
+            throw new LcovError(n, `"${row.slice(0, 60)}" is not an lcov record`);
+        const [, key = "", value = ""] = m;
+        if (key === "TN") {
+            test = value.trim() === "" ? null : value.trim();
+            continue;
+        }
+        if (key === "SF") {
+            close();
+            if (value === "")
+                throw new LcovError(n, "SF needs a path");
+            open = { path: value, test, lines: new Map(), branches: new Map() };
+            continue;
+        }
+        if (key !== "DA" && key !== "BRDA")
+            continue;
+        if (open === null)
+            throw new LcovError(n, `${key} comes before any SF`);
+        if (key === "DA") {
+            const da = DA.exec(value);
+            if (da === null)
+                throw new LcovError(n, `DA needs <line>,<hits>, got "${value}"`);
+            const line = Number(da[1]);
+            open.lines.set(line, (open.lines.get(line) ?? 0) + Number(da[2]));
+            continue;
+        }
+        const br = BRDA.exec(value);
+        if (br === null) {
+            throw new LcovError(n, `BRDA needs <line>,<block>,<branch>,<taken>, got "${value}"`);
+        }
+        const line = Number(br[1]);
+        const id = `${br[2]},${br[3]}`;
+        const taken = br[4] !== "-" && Number(br[4]) > 0;
+        const branches = open.branches.get(line) ?? new Map();
+        branches.set(id, (branches.get(id) ?? false) || taken);
+        open.branches.set(line, branches);
+    }
+    close();
+    if (records.length === 0)
+        throw new LcovError(rows.length, "no SF record; is this lcov?");
+    return records;
+}
+/**
+ * Where an lcov path is at the tip: absolute, or relative to cwd and failing that to the root,
+ * symlinks resolved, then relative to the root. Null outside the repo or for a file the tip lacks.
+ */
+export function tipPlacer(root, cwd, atTip) {
+    const real = (p) => {
+        try {
+            return realpathSync(p);
+        }
+        catch {
+            return p;
+        }
+    };
+    const tops = [root, real(root)];
+    return (raw) => {
+        const tried = isAbsolute(raw) ? [raw] : [resolve(cwd, raw), resolve(root, raw)];
+        for (const abs of tried.flatMap((p) => [p, real(p)])) {
+            for (const top of tops) {
+                const rel = relative(top, abs);
+                if (rel === "" || rel.startsWith("..") || isAbsolute(rel))
+                    continue;
+                const path = Buffer.from(rel.split(sep).join("/"), "utf8").toString("latin1");
+                if (isRepoPath(path) && atTip.has(path))
+                    return path;
+            }
+        }
+        return null;
+    };
+}
+/** Sums hits and joins branches over records of the same file; drops what `place` rejects. */
+export function runOf(records, place) {
+    const lines = new Map();
+    const branches = new Map();
+    const tests = new Map();
+    for (const record of records) {
+        const path = place(record.path);
+        if (path === null)
+            continue;
+        const hits = lines.get(path) ?? new Map();
+        for (const [line, n] of record.lines)
+            hits.set(line, (hits.get(line) ?? 0) + n);
+        lines.set(path, hits);
+        const joined = branches.get(path) ?? new Map();
+        for (const [line, ids] of record.branches) {
+            const on = joined.get(line) ?? new Map();
+            for (const [id, taken] of ids)
+                on.set(id, (on.get(id) ?? false) || taken);
+            joined.set(line, on);
+        }
+        branches.set(path, joined);
+        if (record.test === null)
+            continue;
+        const ran = tests.get(record.test) ?? new Map();
+        const set = ran.get(path) ?? new Set();
+        for (const [line, n] of record.lines)
+            if (n > 0)
+                set.add(line);
+        ran.set(path, set);
+        tests.set(record.test, ran);
+    }
+    const files = new Map();
+    for (const [path, hits] of lines) {
+        const counted = new Map();
+        for (const [line, ids] of branches.get(path) ?? []) {
+            counted.set(line, [[...ids.values()].filter(Boolean).length, ids.size]);
+        }
+        files.set(path, { lines: sorted(hits), branches: sorted(counted) });
+    }
+    return {
+        files,
+        tests: new Map([...tests].map(([id, ran]) => [
+            id,
+            new Map([...ran].map(([path, set]) => [path, [...set].sort((a, b) => a - b)])),
+        ])),
+    };
+}
+function sorted(map) {
+    return new Map([...map].sort(([a], [b]) => a - b));
+}
+/** The lines of each file with at least one hit. */
+function hitLines(files) {
+    return new Map([...files].map(([path, f]) => [path, [...f.lines].flatMap(([l, n]) => (n > 0 ? [l] : []))]));
+}
+/**
+ * Per-test runs only add: a line keeps the larger count, so they never inflate an aggregate run
+ * of the same suite, and running the same test twice changes nothing.
+ */
+function mergeMax(a, b) {
+    const out = new Map(a);
+    for (const [path, f] of b) {
+        const had = out.get(path);
+        if (had === undefined) {
+            out.set(path, f);
+            continue;
+        }
+        const lines = new Map(had.lines);
+        for (const [l, n] of f.lines)
+            lines.set(l, Math.max(n, lines.get(l) ?? 0));
+        const branches = new Map(had.branches);
+        for (const [l, [taken, total]] of f.branches) {
+            const [t, n] = branches.get(l) ?? [0, 0];
+            branches.set(l, [Math.max(taken, t), Math.max(total, n)]);
+        }
+        out.set(path, { lines: sorted(lines), branches: sorted(branches) });
+    }
+    return out;
+}
+/**
+ * The coverage after this run. A plain run replaces everything, its TN blocks becoming its tests.
+ * A named test's run adds to what is already there for the same tip, and starts over otherwise.
+ */
+export function recordRun(prior, run, at) {
+    const { tip, takenAt, test } = at;
+    if (test === undefined) {
+        const tests = new Map([...run.tests].map(([id, lines]) => [id, { lines }]));
+        return { tip, takenAt, files: run.files, tests };
+    }
+    const base = prior !== null && prior.tip === tip ? prior : null;
+    const tests = new Map(base?.tests ?? []);
+    const entry = {
+        ...(test.at === undefined ? {} : { at: test.at }),
+        lines: hitLines(run.files),
+    };
+    tests.set(test.id, entry);
+    const files = base === null ? run.files : mergeMax(base.files, run.files);
+    return { tip, takenAt, files, tests };
+}
+/**
+ * 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();
+    for (const unit of units.values()) {
+        if (unit.kind !== "hunk")
+            continue;
+        const file = files.get(unit.path);
+        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 !== "-")
+                line += 1;
+        }
+        if (executable > 0)
+            out.set(unit.path, { covered, executable });
+    }
+    return out;
+}
+export function totalOf(tallies) {
+    let covered = 0;
+    let executable = 0;
+    for (const t of tallies) {
+        covered += t.covered;
+        executable += t.executable;
+    }
+    return { covered, executable };
+}
+/**
+ * Covered files whose content at `tip` differs from where the run was taken, in file order.
+ * When the run's commit is gone from the repo, every file is stale.
+ */
+export async function staleFiles(repo, coverage, tip) {
+    if (coverage.tip === tip)
+        return [];
+    let changed;
+    try {
+        changed = await pathsChanged(repo, coverage.tip, tip);
+    }
+    catch (error) {
+        if (!(error instanceof GitError))
+            throw error;
+        changed = new Set(coverage.files.keys());
+    }
+    return [...coverage.files.keys()].filter((p) => changed.has(p));
+}
+/** The files whose coverage still describes the tip. */
+export function freshFiles(coverage, stale) {
+    const gone = new Set(stale);
+    return new Map([...coverage.files].filter(([path]) => !gone.has(path)));
+}
+export function serializeCoverage(c) {
+    const files = Object.fromEntries([...c.files].map(([path, f]) => [
+        path,
+        {
+            lines: Object.fromEntries(f.lines),
+            ...(f.branches.size === 0 ? {} : { branches: Object.fromEntries(f.branches) }),
+        },
+    ]));
+    const tests = Object.fromEntries([...c.tests].map(([id, t]) => [
+        id,
+        {
+            ...(t.at === undefined ? {} : { at: t.at }),
+            lines: Object.fromEntries([...t.lines].map(([p, ls]) => [p, [...ls]])),
+        },
+    ]));
+    return { tip: c.tip, takenAt: c.takenAt, files, ...(c.tests.size === 0 ? {} : { tests }) };
+}
+const LINE_KEY = /^[1-9][0-9]*$/;
+function isCount(v) {
+    return typeof v === "number" && Number.isInteger(v) && v >= 0;
+}
+function isLine(v) {
+    return typeof v === "number" && Number.isInteger(v) && v >= 1;
+}
+function entries(v) {
+    return isFields(v) ? Object.entries(v) : null;
+}
+function parseLoc(v) {
+    if (!isFields(v))
+        return null;
+    const { path, start, end } = v;
+    if (typeof path !== "string" || !isRepoPath(path) || !isLine(start) || !isLine(end))
+        return null;
+    return end < start ? null : { path, start, end };
+}
+/** Like parseLoc, for argv: "path:line" or "path:start-end", the path placed like lcov's. */
+export function parseLocArg(raw, place) {
+    const m = /^(.+):([1-9][0-9]*)(?:-([1-9][0-9]*))?$/.exec(raw);
+    if (m === null)
+        return `--at ${raw} is not <path>:<line> or <path>:<start>-<end>`;
+    const path = place(m[1] ?? "");
+    if (path === null)
+        return `--at ${raw} names no file of the branch tip`;
+    const start = Number(m[2]);
+    const end = m[3] === undefined ? start : Number(m[3]);
+    return end < start ? `--at ${raw} runs backwards` : { path, start, end };
+}
+function parseFile(v) {
+    if (!isFields(v))
+        return "a file is not an object";
+    const lines = entries(v.lines);
+    if (lines === null)
+        return "lines is not an object";
+    const hits = new Map();
+    for (const [key, n] of lines) {
+        if (!LINE_KEY.test(key) || !isCount(n))
+            return `line ${key} has no hit count`;
+        hits.set(Number(key), n);
+    }
+    const branchEntries = entries(v.branches ?? {});
+    if (branchEntries === null)
+        return "branches is not an object";
+    const branches = new Map();
+    for (const [key, pair] of branchEntries) {
+        if (!LINE_KEY.test(key) || !Array.isArray(pair) || pair.length !== 2) {
+            return `branches of line ${key} are not [taken, total]`;
+        }
+        const [taken, total] = pair;
+        if (!isCount(taken) || !isCount(total) || taken > total) {
+            return `branches of line ${key} are not [taken, total]`;
+        }
+        branches.set(Number(key), [taken, total]);
+    }
+    return { lines: sorted(hits), branches: sorted(branches) };
+}
+function parseTest(v) {
+    if (!isFields(v))
+        return "a test is not an object";
+    const at = v.at === undefined ? undefined : parseLoc(v.at);
+    if (at === null)
+        return "at is not a { path, start, end }";
+    const lineEntries = entries(v.lines);
+    if (lineEntries === null)
+        return "lines is not an object";
+    const lines = new Map();
+    for (const [path, list] of lineEntries) {
+        if (!isRepoPath(path) || !Array.isArray(list) || !list.every(isLine)) {
+            return `lines of ${path} are not line numbers`;
+        }
+        lines.set(path, list);
+    }
+    return { ...(at === undefined ? {} : { at }), lines };
+}
+/** The one place coverage.json becomes a Coverage. */
+export function parseCoverage(v) {
+    if (!isFields(v))
+        return "not an object";
+    const { tip, takenAt } = v;
+    if (typeof tip !== "string" || !isSha(tip))
+        return "tip is not an object id";
+    if (typeof takenAt !== "string")
+        return "takenAt is not a time";
+    const fileEntries = entries(v.files);
+    if (fileEntries === null)
+        return "files is not an object";
+    const files = new Map();
+    for (const [path, raw] of fileEntries) {
+        if (!isRepoPath(path))
+            return "a file has no path";
+        const file = parseFile(raw);
+        if (typeof file === "string")
+            return `${path}: ${file}`;
+        files.set(path, file);
+    }
+    const testEntries = entries(v.tests ?? {});
+    if (testEntries === null)
+        return "tests is not an object";
+    const tests = new Map();
+    for (const [id, raw] of testEntries) {
+        const test = parseTest(raw);
+        if (typeof test === "string")
+            return `test ${id}: ${test}`;
+        tests.set(id, test);
+    }
+    return { tip, takenAt, files, tests };
+}

package/dist/src/git.js

@@ -132,6 +132,24 @@ export async function blobsAt(repo, commit, paths) {
     const blobs = await catBatch(repo, paths.map((p) => `${commit}:${p}`));
     return new Map(paths.map((p, i) => [p, blobs[i] ?? ""]));
 }
+function pathList(out) {
+    return new Set(out
+        .toString("latin1")
+        .split("\0")
+        .filter((p) => isRepoPath(p)));
+}
+/** Every file path in the commit's tree. */
+export async function pathsAt(repo, commit) {
+    return pathList(await git(repo, ["ls-tree", "-r", "-z", "--name-only", commit]));
+}
+/**
+ * Paths whose content differs between the commit and `to`: another commit, or with null the
+ * working tree and index. Untracked files are not listed.
+ */
+export async function pathsChanged(repo, from, to) {
+    const target = to === null ? [] : [to];
+    return pathList(await git(repo, ["diff", "--name-only", "-z", ...DIFF_FLAGS, from, ...target, "--"]));
+}
 /**
  * Lines of the commit's tree, not the working tree, that match any of the POSIX extended
  * patterns, in files matching the pathspecs. Binary files are skipped.

package/dist/src/host.js

@@ -373,6 +373,10 @@ export async function postComment(port, summary, comment) {
     }
     return id;
 }
+/** Tells the hosted page that coverage.json changed, so it reloads its marks. */
+export async function postCoverage(port, summary) {
+    await call(port, "POST", `${summary.url}api/coverage`);
+}
 /** 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}`);