@shiyuphan/follow-me 0.5.1 → 0.7.1

package/README.md

@@ -69,8 +69,14 @@ If the hashes differ, `apply` exits with code 1. The commits are signed when you
 
 The red blob in the party hat is your branch tip. Nothing follow-me does moves it.
 
-![The review page: one scrolling document of commits with the stack dropdown in the sticky header, a picked line with its Ask box, and an inline thread where the agent answers in Markdown with a diagram](assets/screenshots/review.png)
-*The review page. Pick any line, changed or not, or a range; Ask or Flag opens right under it. The agent answers inline in Markdown.*
+![The review page: the index on the left groups commits by section in top-down order, and commit 2 shows a question on a line with the agent's answer inline](assets/screenshots/review.png)
+*The review page. The index groups the commits the way they read: the story first, then the steps it calls, then the details. Pick any line, changed or not, and Ask or Flag right under it; the agent answers inline.*
+
+![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.*
@@ -78,7 +84,7 @@ The red blob in the party hat is your branch tip. Nothing follow-me does moves i
 ![The hand-off page: every kept item with its original-branch path and line, an include checkbox, and copy buttons](assets/screenshots/handoff.png)
 *Submit review. Each item carries the original branch's path and line, so your agent can post it to the merge request as is.*
 
-Keys: `j` and `k` move between commits, 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,21 +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, renderShownUnit, reportItems, } from "./prompt.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
@@ -30,11 +36,14 @@ Other commands:
                                             Mermaid source
   explain [--commit <n>] [--unit <id>] [--lines <a-b>] --body <text> [--diagram <file>]
                                             start a thread on the page without being asked
-  show <h_…|c_…|k_…|path:line[@n|@base]>   print a unit, a comment's thread, a concern, or the
-                                            lines around path:line in commit n, instead of
-                                            reading files
+  show <h_…|c_…|k_…|path:line[@n|@base]|name>
+                                            print a unit, a comment's thread, a concern, the
+                                            lines around path:line in commit n, or where a name
+                                            is defined, instead of reading files
   report [--json] [--markdown]              print the report of the latest review; --json lists
                                             the items to post to a merge request
+  coverage <lcov> [--test <id> [--at <path:line>]]
+                                            record a test run taken at the tip for the page
 
 help --all lists every command.`;
 const USAGE = `usage: follow-me <command> [options]
@@ -85,17 +94,24 @@ Interactive loop (while the review page is open):
                                             --lines are change lines of the unit, commits count
                                             from 1; with no target it is about the whole plan.
                                             watch leaves these out like your replies
-  show <h_…|c_…|k_…|path:line[@n|@base]> [--branch <name>]
+  show <h_…|c_…|k_…|path:line[@n|@base]|name> [--branch <name>]
                                             print a unit with the commits that take it, a
                                             comment with its rows and thread, a concern with its
-                                            lines, or the lines around path:line at the tip, in
-                                            commit n of the plan, or in the base
+                                            lines, the lines around path:line at the tip, in
+                                            commit n of the plan, or in the base, or each place
+                                            a name is defined at the tip with the commit it
+                                            lands in
   report [--json] [--markdown] [--branch <name>]
                                             print the report of the open review, or of the last
                                             one that ended. Markdown lists issues by file and
                                             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:
@@ -905,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.
@@ -1169,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);
 }
@@ -1226,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`);
@@ -1254,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`;
@@ -1284,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");
@@ -1298,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";
@@ -1516,7 +1599,7 @@ async function explain(cwd, args) {
     next(`run follow-me again; ${STILL_WORKING}`);
     return 0;
 }
-const SHOW_USAGE = "usage: follow-me show <h_…|c_…|k_…|path:line[@<commit>|@base]>";
+const SHOW_USAGE = "usage: follow-me show <h_…|c_…|k_…|path:line[@<commit>|@base]|name>";
 /** Every comment the session has, with the plan version it was made on: live ones first. */
 async function knownComments(session) {
     const open = await openOnServer(session, null);
@@ -1629,6 +1712,12 @@ async function showRef(cwd, args) {
         }
         throw new UsageError(`no concern ${ref} in a plan that fits the branch`);
     }
+    if (isIdentifier(ref)) {
+        const commits = latest === undefined ? [] : projectedCommits(session, latest.version);
+        const index = definitionIndex(session.root, session.diff.tip, units, commits);
+        process.stdout.write(renderShownDefinitions(ref, await index.lookup(ref, null)));
+        return 0;
+    }
     process.stdout.write(showLines(session, ref));
     return 0;
 }
@@ -1868,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": {
@@ -1908,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":