@shiyuphan/follow-me 0.5.0 → 0.6.0

package/README.md

@@ -69,8 +69,11 @@ 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.*
 
 ![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 +81,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, `?` 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

@@ -3,15 +3,16 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
+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 { 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, sinceLastPlan, } from "./session.js";
+import { BranchMovedError, cleanSessions, extractSession, MissingDraftError, NotARepositoryError, openSession, SessionFileError, SessionLockedError, sessionComments, sinceLastPlan, } from "./session.js";
 import { checkSyntax } from "./syntax.js";
 class UsageError extends Error {
     name = "UsageError";
@@ -30,9 +31,10 @@ 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
 
@@ -85,11 +87,13 @@ 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
@@ -909,7 +913,9 @@ function finished(session, stored) {
     const text = renderStored(session, stored);
     if (text === null)
         return 1;
-    say(`review v${stored.version} ended with ${plural(stored.review.comments.length, "comment")}`);
+    // A review that swapped versions holds what its earlier versions said too.
+    const said = stored.review.comments.length + (stored.review.carried?.length ?? 0);
+    say(`review v${stored.version} ended with ${plural(said, "comment")}`);
     process.stdout.write(text);
     say();
     next("done; the user can port it with follow-me report --json");
@@ -1240,7 +1246,19 @@ function renderStored(session, stored, format = "markdown") {
         .plans()
         .filter((p) => p.version > stored.version)
         .flatMap((p) => p.file.responses);
-    const opts = { branch: session.anchor.branch, responses };
+    const { carried } = stored.review;
+    const said = reviewsOf(session)
+        .filter((r) => r.version <= stored.version)
+        .map((r) => r.review);
+    const earlier = carried === undefined
+        ? {}
+        : {
+            earlier: {
+                comments: sessionComments(carried, said),
+                concerns: stored.review.carriedConcerns ?? [],
+            },
+        };
+    const opts = { branch: session.anchor.branch, responses, ...earlier };
     if (format === "json") {
         const items = reportItems(stored.review, verdict.plan.commits, session.diff.units, opts);
         return `${JSON.stringify(items, null, 2)}\n`;
@@ -1502,7 +1520,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);
@@ -1615,6 +1633,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;
 }

package/dist/src/comments.js

@@ -1,5 +1,5 @@
 import { isRepoPath, isUnitId } from "./diff.js";
-import { diagramProblem, isArray, isCommentId, isConcernId, isFields, isPlanVersion, isSeverity, } from "./plan.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
  * decisions, the review file, its autosaved draft and the events a hosted session logs. Every
@@ -253,13 +253,7 @@ function parseEarlierReplies(v) {
 function isLine(v) {
     return typeof v === "number" && Number.isInteger(v) && v >= 1;
 }
-export function parseCarried(v) {
-    if (!isFields(v)) {
-        return "not an object";
-    }
-    const comment = parseComment(v.comment);
-    if (typeof comment === "string")
-        return comment;
+function parsePlacement(v) {
     const { unit, offsets, changed, path, newLine } = v;
     if (unit !== null && !(typeof unit === "string" && isUnitId(unit)))
         return "unit is not a unit id";
@@ -273,7 +267,6 @@ export function parseCarried(v) {
     if (newLine !== null && !isLine(newLine))
         return "newLine is not null or a line";
     return {
-        comment,
         unit,
         offsets: offsets === null ? null : offsets.filter(isIndex),
         changed,
@@ -281,6 +274,56 @@ export function parseCarried(v) {
         newLine,
     };
 }
+export function parseCarried(v) {
+    if (!isFields(v))
+        return "not an object";
+    const comment = parseComment(v.comment);
+    if (typeof comment === "string")
+        return comment;
+    const placement = parsePlacement(v);
+    return typeof placement === "string" ? placement : { comment, ...placement };
+}
+function parseSince(v) {
+    if (v === null)
+        return null;
+    return isPlanVersion(v) ? v : "since is not null or a plan version";
+}
+function parseCarriedRef(v) {
+    if (!isFields(v))
+        return "not an object";
+    const comment = asCommentId(v.comment);
+    if (comment === null)
+        return "comment is not a comment id";
+    if (!isPlanVersion(v.version))
+        return "version is not a plan version";
+    const since = parseSince(v.since);
+    if (typeof since === "string")
+        return since;
+    const placement = parsePlacement(v);
+    if (typeof placement === "string")
+        return placement;
+    return { ...placement, comment, version: v.version, since };
+}
+function parseCarriedConcern(v) {
+    if (!isFields(v)) {
+        return "not an object";
+    }
+    const concern = parsePlacedConcern(v.concern);
+    if (typeof concern === "string")
+        return `concern: ${concern}`;
+    if (!isIndex(v.commit))
+        return "commit is not a commit index";
+    const decision = parseDecision(v.decision);
+    if (typeof decision === "string")
+        return `decision: ${decision}`;
+    const since = parseSince(v.since);
+    if (typeof since === "string")
+        return since;
+    const placement = parsePlacement(v);
+    if (typeof placement === "string")
+        return placement;
+    return { ...placement, concern, commit: v.commit, decision, since };
+}
 /** Boundary parse of reviews/vN.json. Files written before walk mode existed have no mode. */
 export function parseReview(v) {
     if (!isFields(v)) {
@@ -314,6 +357,12 @@ export function parseReview(v) {
     const earlier = parseList(v.earlierReplies, parseEarlierReplies, "earlierReplies");
     if (typeof earlier === "string")
         return earlier;
+    const carried = v.carried === undefined ? null : parseList(v.carried, parseCarriedRef, "carried");
+    if (typeof carried === "string")
+        return carried;
+    const concernsCarried = parseList(v.carriedConcerns, parseCarriedConcern, "carriedConcerns");
+    if (typeof concernsCarried === "string")
+        return concernsCarried;
     return {
         schema: v.schema,
         mode,
@@ -325,6 +374,8 @@ export function parseReview(v) {
         ...(resolved.length === 0 ? {} : { resolved }),
         ...(anyExcluded ? { excluded } : {}),
         ...(earlier.length === 0 ? {} : { earlierReplies: earlier }),
+        ...(carried === null ? {} : { carried }),
+        ...(concernsCarried.length === 0 ? {} : { carriedConcerns: concernsCarried }),
     };
 }
 function lenient(items, parse) {
@@ -350,6 +401,8 @@ export function parseDraft(v) {
         resolved: lenientIds(v.resolved, isCommentIdValue),
         excluded: typeof excluded === "string" ? { comments: [], concerns: [] } : excluded,
         earlierReplies: lenient(v.earlierReplies, parseEarlierReplies),
+        carried: v.carried === undefined ? null : lenient(v.carried, parseCarriedRef),
+        carriedConcerns: lenient(v.carriedConcerns, parseCarriedConcern),
     };
 }
 export function parseEvent(v) {

package/dist/src/definition.js

@@ -0,0 +1,226 @@
+import { posix } from "node:path";
+import { splitLines, tipStartOf } from "./diff.js";
+import { blobsAt, grepTip } from "./git.js";
+export const MAX_CANDIDATES = 10;
+const PREVIEW_LINES = 8;
+/** An ASCII identifier as JS, Python, Go, Rust, JVM languages, Ruby and C spell one. */
+export function isIdentifier(s) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]{0,127}$/.test(s);
+}
+const JS_MODS = "((static|async|public|private|protected|readonly|override|get|set)\\s+)*";
+const RUST_VIS = "(pub([(][^)]*[)])?\\s+)?";
+const JAVA_MODS = "((public|private|protected|static|final|abstract|synchronized|native|default|strictfp)\\s+)*";
+const JVM_CLASS_MODS = "((public|private|protected|static|final|abstract|sealed|data|open|internal|inner|enum|annotation)\\s+)*";
+const KOTLIN_MODS = "((public|private|protected|internal|override|open|abstract|suspend|inline|operator|infix|tailrec|external|actual|expect)\\s+)*";
+const STATEMENT = /^\s*(return|new|throw|else|case|yield|await|typedef|delete|goto)\b/;
+const LANGUAGES = [
+    {
+        extensions: [".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx", ".mts", ".cts"],
+        patterns: [
+            {
+                kind: "function",
+                source: "^\\s*(export\\s+)?(default\\s+)?(async\\s+)?function\\s*[*]?\\s*NAME\\s*[(<]",
+            },
+            {
+                kind: "const",
+                source: "^\\s*(export\\s+)?(declare\\s+)?(const|let|var)\\s+NAME\\s*(:[^=]*)?=",
+            },
+            {
+                kind: "class",
+                source: "^\\s*(export\\s+)?(default\\s+)?(declare\\s+)?(abstract\\s+)?class\\s+NAMEEND",
+            },
+            {
+                kind: "type",
+                source: "^\\s*(export\\s+)?(declare\\s+)?(interface|type|(const\\s+)?enum)\\s+NAMEEND",
+            },
+            {
+                kind: "method",
+                source: `^\\s+${JS_MODS}[*]?NAME\\s*(<[^>]*>)?[(].*[)]\\s*(:[^={;]+)?[{]\\s*$`,
+                reject: /^\s*(if|for|while|switch|catch|return)\b/,
+            },
+        ],
+    },
+    {
+        extensions: [".py", ".pyi"],
+        patterns: [
+            { kind: "function", source: "^(async\\s+)?def\\s+NAME\\s*[(]" },
+            { kind: "method", source: "^\\s+(async\\s+)?def\\s+NAME\\s*[(]" },
+            { kind: "class", source: "^\\s*class\\s+NAME\\s*[(:]" },
+        ],
+    },
+    {
+        extensions: [".go"],
+        patterns: [
+            { kind: "function", source: "^func\\s+NAME\\s*[[(]" },
+            { kind: "method", source: "^func\\s*[(][^)]*[)]\\s*NAME\\s*[[(]" },
+            { kind: "type", source: "^\\s*type\\s+NAMEEND" },
+        ],
+    },
+    {
+        extensions: [".rs"],
+        patterns: [
+            {
+                kind: "function",
+                source: `^${RUST_VIS}((const|async|unsafe|extern)\\s+("[^"]*"\\s+)?)*fn\\s+NAME\\s*[<(]`,
+            },
+            {
+                kind: "method",
+                source: `^\\s+${RUST_VIS}((const|async|unsafe|extern)\\s+("[^"]*"\\s+)?)*fn\\s+NAME\\s*[<(]`,
+            },
+            { kind: "class", source: `^\\s*${RUST_VIS}struct\\s+NAMEEND` },
+            { kind: "type", source: `^\\s*${RUST_VIS}(enum|trait|type)\\s+NAMEEND` },
+            { kind: "other", source: "^\\s*impl(<[^>]*>)?\\s+([A-Za-z0-9_:<>, ]+\\s+for\\s+)?NAMEEND" },
+        ],
+    },
+    {
+        extensions: [".java", ".kt", ".kts"],
+        patterns: [
+            { kind: "class", source: `^\\s*${JVM_CLASS_MODS}(class|object|record)\\s+NAMEEND` },
+            { kind: "type", source: `^\\s*${JVM_CLASS_MODS}(interface|enum|@interface)\\s+NAMEEND` },
+            {
+                kind: "function",
+                source: `^\\s*${KOTLIN_MODS}fun\\s+(<[^>]*>\\s*)?([A-Za-z0-9_.<>]+[.])?NAME\\s*[(]`,
+            },
+            {
+                kind: "method",
+                source: `^\\s*${JAVA_MODS}(<[^>]*>\\s+)?[A-Za-z_][A-Za-z0-9_<>,.?]*(\\[\\])*\\s+NAME\\s*[(][^;]*$`,
+                reject: STATEMENT,
+            },
+        ],
+    },
+    {
+        extensions: [".rb"],
+        patterns: [
+            { kind: "method", source: "^\\s*def\\s+(self[.])?NAMEEND" },
+            { kind: "class", source: "^\\s*class\\s+NAMEEND" },
+            { kind: "other", source: "^\\s*module\\s+NAMEEND" },
+        ],
+    },
+    {
+        extensions: [".c", ".h", ".cc", ".cpp", ".cxx", ".hh", ".hpp", ".hxx"],
+        patterns: [
+            {
+                kind: "function",
+                source: "^[A-Za-z_][A-Za-z0-9_ *&<>,:~]*[ *&]([A-Za-z_][A-Za-z0-9_]*::)*NAME\\s*[(][^;]*$",
+                reject: STATEMENT,
+            },
+            { kind: "function", source: "^NAME\\s*[(][^;]*$" },
+            { kind: "class", source: "^\\s*(typedef\\s+)?(struct|class|union)\\s+NAME\\s*([{:]|$)" },
+            { kind: "type", source: "^\\s*(typedef\\s+)?enum\\s+(class\\s+)?NAME\\s*([{:]|$)" },
+        ],
+    },
+];
+const END = "([^A-Za-z0-9_$]|$)";
+function spell(source, name) {
+    return source
+        .replaceAll("NAMEEND", `${name.replaceAll("$", "[$]")}${END}`)
+        .replaceAll("NAME", name.replaceAll("$", "[$]"));
+}
+function toEre(source) {
+    return source.replaceAll("\\s", "[[:space:]]");
+}
+function languageOf(path) {
+    const ext = posix.extname(path).toLowerCase();
+    return LANGUAGES.find((l) => l.extensions.includes(ext)) ?? null;
+}
+/** What the match defines by the patterns of its file's language, or null when it is no definition. */
+function kindOf(match, name) {
+    const language = languageOf(match.path);
+    if (language === null)
+        return null;
+    const hit = language.patterns.find((p) => new RegExp(spell(p.source, name)).test(match.text) && !p.reject?.test(match.text));
+    return hit?.kind ?? null;
+}
+/** Same file as `from` first, then the same directory, then the rest, each in path and line order. */
+export function rank(found, from) {
+    const tier = (path) => {
+        if (from === null)
+            return 2;
+        if (path === from)
+            return 0;
+        return posix.dirname(path) === posix.dirname(from) ? 1 : 2;
+    };
+    return found
+        .map((f, i) => ({ f, i, t: tier(f.path) }))
+        .sort((a, b) => a.t - b.t || a.i - b.i)
+        .map(({ f }) => f);
+}
+const NOWHERE = { unit: null, row: null, commit: null };
+/**
+ * The hunk row that holds tip line `line` of `path`, and the commit that writes it: the owner of a
+ * change row, or the first commit taking the unit for a context row.
+ */
+export function place(units, commits, path, line) {
+    for (const unit of units.values()) {
+        if (unit.kind !== "hunk" || unit.path !== path)
+            continue;
+        const row = rowAt(unit, tipStartOf(unit, units), line);
+        if (row === null)
+            continue;
+        const body = unit.body[row];
+        const change = body !== undefined && body.op !== " " ? body.change : null;
+        const takes = (c) => c.refs.some((r) => r.unit === unit.id &&
+            (change === null || r.select.kind === "rest" || r.select.changes.includes(change)));
+        const k = commits.findIndex(takes);
+        return { unit: unit.id, row, commit: k === -1 ? null : k };
+    }
+    return NOWHERE;
+}
+function rowAt(hunk, tipStart, line) {
+    let tipLine = tipStart;
+    for (const [row, body] of hunk.body.entries()) {
+        if (body.op === "-")
+            continue;
+        if (tipLine === line)
+            return row;
+        tipLine += 1;
+    }
+    return null;
+}
+function stripEol(line) {
+    return line.replace(/\r?\n$/, "");
+}
+/**
+ * Where names are defined at one branch tip and where each lands in the plan. Built per hosted
+ * version, so a swap starts a fresh one; matches are cached per name and file lines per path.
+ */
+export function definitionIndex(repo, tip, units, commits) {
+    const foundByName = new Map();
+    const linesByPath = new Map();
+    const find = (name) => {
+        const cached = foundByName.get(name);
+        if (cached !== undefined)
+            return cached;
+        const patterns = [
+            ...new Set(LANGUAGES.flatMap((l) => l.patterns.map((p) => toEre(spell(p.source, name))))),
+        ];
+        const pathspecs = LANGUAGES.flatMap((l) => l.extensions.map((e) => `*${e}`));
+        const found = grepTip(repo, tip, patterns, pathspecs).then((matches) => matches.flatMap((m) => {
+            const kind = kindOf(m, name);
+            return kind === null ? [] : [{ path: m.path, newLine: m.line, kind }];
+        }));
+        foundByName.set(name, found);
+        // A failed grep is not an answer; the next request tries again.
+        found.catch(() => foundByName.delete(name));
+        return found;
+    };
+    const load = async (paths) => {
+        const missing = [...new Set(paths)].filter((p) => !linesByPath.has(p));
+        if (missing.length === 0)
+            return;
+        for (const [path, bytes] of await blobsAt(repo, tip, missing)) {
+            linesByPath.set(path, splitLines(bytes).map(stripEol));
+        }
+    };
+    return {
+        lookup: async (name, from) => {
+            const ranked = rank(await find(name), from).slice(0, MAX_CANDIDATES);
+            await load(ranked.map((f) => f.path));
+            return ranked.map((f) => ({
+                ...f,
+                ...place(units, commits, f.path, f.newLine),
+                preview: (linesByPath.get(f.path) ?? []).slice(f.newLine - 1, f.newLine - 1 + PREVIEW_LINES),
+            }));
+        },
+    };
+}

package/dist/src/evolve.js

@@ -78,50 +78,166 @@ function distance(hunk, units, line) {
     const [from, to] = span(hunk, units);
     return line < from ? from - line : line > to ? line - to : 0;
 }
-/**
- * Pure. Places each comment of the previous version on the new diff: on its own unit when that
- * hunk is unchanged, else on the hunk of the same path nearest its old tip line.
- */
-export function carryComments(comments, oldUnits, newUnits) {
-    return comments.map((comment) => carry(comment, oldUnits, newUnits));
+/** The body row whose tip line is `line`; a kept row before a removal at the same line. */
+function rowAt(hunk, units, line) {
+    if (line === null)
+        return 0;
+    const lines = tipLines(hunk, units);
+    const row = hunk.body.findIndex((r, i) => r.op !== "-" && lines[i] === line);
+    return row === -1 ? 0 : row;
 }
-function carry(comment, oldUnits, newUnits) {
+function pinnedComment(comment) {
     const { anchor } = comment;
-    const nowhere = { comment, unit: null, offsets: null, newLine: null };
-    if (anchor.kind !== "hunk")
-        return { ...nowhere, changed: false, path: comment.context.path };
     // A comment on a whole hunk has no line; inventing one moves its card off the hunk's end.
-    const whole = anchor.changes === null && anchor.offsets === undefined;
-    const kept = newUnits.get(anchor.unit);
+    const whole = anchor.kind === "hunk" && anchor.changes === null && anchor.offsets === undefined;
+    return { whole, row: (hunk) => firstRow(comment, hunk) };
+}
+function pinnedConcern(concern) {
+    const { lines } = concern;
+    if (lines === undefined)
+        return { whole: true, row: () => 0 };
+    return {
+        whole: false,
+        row: (hunk) => {
+            const row = hunk.body.findIndex((r) => r.op !== " " && lines.includes(r.change));
+            return row === -1 ? 0 : row;
+        },
+    };
+}
+/** Where a comment points on the version it was made on. */
+function placedOwn(comment) {
+    const { anchor } = comment;
+    return {
+        unit: anchor.kind === "hunk" ? anchor.unit : null,
+        offsets: anchor.kind === "hunk" ? (anchor.offsets ?? null) : null,
+        changed: false,
+        path: comment.context.path,
+        newLine: null,
+    };
+}
+/**
+ * Pure. Moves a placement on the old diff to the new one: a unit the new diff still has keeps its
+ * place, else the hunk of the same path nearest its old tip line takes it, marked changed. A
+ * placement on no unit stays as it is.
+ */
+function move(at, pinned, oldUnits, newUnits) {
+    if (at.unit === null)
+        return at;
+    const kept = newUnits.get(at.unit);
+    const old = oldUnits.get(at.unit);
     if (kept !== undefined) {
-        const newLine = kept.kind === "hunk" && !whole
-            ? (tipLines(kept, newUnits)[firstRow(comment, kept)] ?? null)
-            : null;
-        return {
-            comment,
-            unit: kept.id,
-            offsets: anchor.offsets ?? null,
-            changed: false,
-            path: kept.path,
-            newLine,
-        };
+        let newLine = null;
+        if (kept.kind === "hunk" && !pinned.whole) {
+            if (!at.changed)
+                newLine = tipLines(kept, newUnits)[pinned.row(kept)] ?? null;
+            else if (at.newLine !== null && old?.kind === "hunk") {
+                newLine = at.newLine - tipStartOf(old, oldUnits) + tipStartOf(kept, newUnits);
+            }
+            else
+                newLine = at.newLine;
+        }
+        return { ...at, path: kept.path, newLine };
     }
-    const old = oldUnits.get(anchor.unit);
-    const path = old?.path ?? comment.context.path;
+    const path = old?.path ?? at.path;
     const onPath = [...newUnits.values()].filter((u) => u.path === path);
     const first = onPath[0];
+    const moved = { offsets: null, changed: true, path };
     if (first === undefined)
-        return { ...nowhere, changed: true, path };
-    const moved = { comment, offsets: null, changed: true, path };
+        return { ...moved, unit: null, newLine: null };
     const hunks = onPath.filter((u) => u.kind === "hunk");
     if (old?.kind !== "hunk" || hunks.length === 0)
         return { ...moved, unit: first.id, newLine: null };
-    const row = firstRow(comment, old);
+    const row = at.changed ? rowAt(old, oldUnits, at.newLine) : pinned.row(old);
     const oldLine = tipLines(old, oldUnits)[row] ?? tipStartOf(old, oldUnits);
     const nearest = hunks.reduce((a, b) => distance(b, newUnits, oldLine) < distance(a, newUnits, oldLine) ? b : a);
     return {
         ...moved,
         unit: nearest.id,
-        newLine: whole ? null : landing(nearest, newUnits, oldLine, old.body[row]?.text),
+        newLine: pinned.whole ? null : landing(nearest, newUnits, oldLine, old.body[row]?.text),
     };
 }
+/**
+ * Pure. Places each comment of the previous version on the new diff: on its own unit when that
+ * hunk is unchanged, else on the hunk of the same path nearest its old tip line.
+ */
+export function carryComments(comments, oldUnits, newUnits) {
+    return comments.map((comment) => ({
+        comment,
+        ...move(placedOwn(comment), pinnedComment(comment), oldUnits, newUnits),
+    }));
+}
+/** since stays once set; a first change records the version the code still matched. */
+function sinceOf(before, after, since, at) {
+    return since ?? (after.changed && !before.changed ? at : null);
+}
+/**
+ * Pure. What an open review carries from version `at` into the next: what it carried already,
+ * moved again, then the comments said on `at`. Nothing is dropped, so a comment of v1 is still
+ * there after the second swap.
+ */
+export function carrySession(carried, said, at, oldUnits, newUnits) {
+    const again = carried.map((c) => {
+        const moved = move(c, pinnedComment(c.comment), oldUnits, newUnits);
+        return { ...c, ...moved, since: sinceOf(c, moved, c.since, at) };
+    });
+    const fresh = said.map((comment) => {
+        const own = placedOwn(comment);
+        const moved = move(own, pinnedComment(comment), oldUnits, newUnits);
+        return { comment, version: at, ...moved, since: sinceOf(own, moved, null, at) };
+    });
+    return [...again, ...fresh];
+}
+/**
+ * Pure. Kept concerns of version `at` that the next plan no longer has, plus those carried before,
+ * placed on the new diff. A concern the next plan has again keeps its decision there instead, so
+ * it is left out here.
+ */
+export function carryConcerns(carried, kept, inNext, at, oldUnits, newUnits) {
+    const fresh = kept.map((k) => {
+        const unit = k.concern.unit ?? null;
+        const path = unit === null ? null : (oldUnits.get(unit)?.path ?? null);
+        return { ...k, unit, offsets: null, changed: false, path, newLine: null, since: null };
+    });
+    return [...carried, ...fresh]
+        .filter((c) => !inNext.has(c.concern.id))
+        .map((c) => {
+        const moved = move(c, pinnedConcern(c.concern), oldUnits, newUnits);
+        return { ...c, ...moved, since: sinceOf(c, moved, c.since, at) };
+    });
+}
+/**
+ * Pure. Where a carried hunk comment points on the diff it was carried to, as an anchor of that
+ * diff: its own rows when the hunk is unchanged, the row at its new line when it changed, the
+ * whole hunk when it has no line. Null when the code is gone or the comment is not on a hunk.
+ */
+export function anchorOn(carried, units, commit) {
+    const { anchor } = carried.comment;
+    if (anchor.kind !== "hunk" || carried.unit === null)
+        return null;
+    if (!carried.changed)
+        return { ...anchor, commit };
+    const hunk = units.get(carried.unit);
+    if (hunk?.kind !== "hunk" || carried.newLine === null) {
+        return { kind: "hunk", unit: carried.unit, commit, changes: null };
+    }
+    const row = rowAt(hunk, units, carried.newLine);
+    const at = hunk.body[row];
+    const changes = at === undefined || at.op === " " ? [] : [at.change];
+    return { kind: "hunk", unit: carried.unit, commit, changes, offsets: [row] };
+}
+/** Pure. A carried concern as a concern of the diff it was carried to; see anchorOn. */
+export function concernOn(carried, units) {
+    const { concern } = carried;
+    if (carried.unit === null)
+        return concern;
+    if (!carried.changed)
+        return { ...concern, unit: carried.unit };
+    const { lines: _old, ...rest } = concern;
+    const hunk = units.get(carried.unit);
+    if (hunk?.kind !== "hunk" || carried.newLine === null)
+        return { ...rest, unit: carried.unit };
+    const at = hunk.body[rowAt(hunk, units, carried.newLine)];
+    return at === undefined || at.op === " "
+        ? { ...rest, unit: carried.unit }
+        : { ...rest, unit: carried.unit, lines: [at.change] };
+}