@shiyuphan/follow-me 0.3.0 → 0.4.1

package/dist/src/cli.js

@@ -5,13 +5,13 @@ import { dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 import { DiffParseError, formatUnitRef, isUnitId } from "./diff.js";
 import { BranchRefusedError, branchHead, GitError, isOwnWork, signing, treeOf, writeBranch, } from "./git.js";
-import { fetchReport, findServer, followEvents, idleMs, listSessions, openBrowser, pollEvents, portFallbackMessage, postComment, postReply, probeHealth, registerWith, sessionUrl, spawnDetached, startOrAttach, stateDir, stillHosted, stopServer, swapVersion, } from "./host.js";
+import { fetchCarried, fetchReport, findServer, followEvents, idleMs, listSessions, openBrowser, pollEvents, portFallbackMessage, postComment, postReply, probeHealth, readServerRecord, registerWith, sessionUrl, spawnDetached, startOrAttach, stateDir, stillHosted, stopServer, swapVersion, } from "./host.js";
 import { runInstall, runUninstall, syncSkills } from "./install.js";
 import { naiveDraft } from "./naive.js";
-import { serializePlanFile, validatePlan } from "./plan.js";
+import { isFields, serializePlanFile, validatePlan } from "./plan.js";
 import { renderEvents, renderPrompt, renderReport, reportItems, } from "./prompt.js";
 import { RegistrationError, sessionIdOf } from "./server.js";
-import { BranchMovedError, cleanSessions, extractSession, MissingDraftError, NotARepositoryError, openSession, SessionFileError, SessionLockedError, } from "./session.js";
+import { BranchMovedError, cleanSessions, extractSession, MissingDraftError, NotARepositoryError, openSession, SessionFileError, SessionLockedError, sinceLastPlan, } from "./session.js";
 import { checkSyntax } from "./syntax.js";
 class UsageError extends Error {
     name = "UsageError";
@@ -20,8 +20,9 @@ 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
 writes the prompt for you to answer, reports what is wrong with your draft, opens the review for
-the user, then listens to them for up to --wait seconds (default 60, 0 for none) and prints what
-they flagged or asked. Do what its "next:" line says. Run it again to keep listening.
+the user, then listens to them for up to --wait seconds (default 90, at most 300, 0 for none) and
+prints what they flagged or asked. It is interactive: do what its "next:" line says and run it
+again until it prints the report.
 
 Other commands:
   reply <commentId> --body <text> [--diagram <file>]
@@ -411,6 +412,7 @@ async function apply(cwd, args) {
  * write runs under it, and the page is then swapped to the new plan version in place.
  */
 async function applyHosted(session, args, open) {
+    rememberPort(session, open.port);
     const code = await applyLocked(session, args);
     const latest = session.plans().at(-1);
     if (code !== 0 || latest === undefined)
@@ -482,11 +484,12 @@ async function applyLocked(session, args) {
     say(`proof: ${result.branch}^{tree} ${tree} ${same ? "equals" : "DIFFERS FROM"} ${session.anchor.branch}^{tree} ${session.anchor.tipTree}`);
     return same ? 0 : 1;
 }
-function promptInput(session, mode, args) {
+function promptInput(session, mode, args, changes) {
     const common = {
         diff: session.diff,
         draftPath: session.draftPath,
         checkCommand: `follow-me check${branchFlag(args)}`,
+        ...(changes === undefined ? {} : { changes }),
     };
     if (mode === "walk")
         return { ...common, mode };
@@ -564,6 +567,7 @@ async function hostReview(session, mode, args, prepare, report) {
     const home = stateDir();
     const open = await openOnServer(session, mode);
     if (open !== null) {
+        rememberPort(session, open.port);
         announce(sessionUrl(open.port, open.summary), args);
         return { kind: "elsewhere", ...open };
     }
@@ -578,7 +582,7 @@ async function hostReview(session, mode, args, prepare, report) {
             hash: prepared.plan.hash,
             lockToken: held.token,
         };
-        const port = portOf(args);
+        const port = portOf(args) ?? rememberedPort(session);
         let started;
         const running = await runningServer(home, port);
         if (running !== null)
@@ -591,6 +595,7 @@ async function hostReview(session, mode, args, prepare, report) {
         }
         else
             started = await startOrAttach(home, port, say);
+        rememberPort(session, started.kind === "attached" ? started.port : started.host.port);
         if (started.kind === "attached") {
             const summary = await registerWith(started.port, registration);
             announce(sessionUrl(started.port, summary), args);
@@ -631,7 +636,52 @@ async function openOnServer(session, mode) {
         return null;
     const id = sessionIdOf(session.dir);
     const summary = (await listSessions(live.port)).find((s) => s.id === id && (mode === null || s.mode === mode));
-    return summary === undefined ? null : { port: live.port, summary };
+    if (summary === undefined)
+        return null;
+    rememberPort(session, live.port);
+    return { port: live.port, summary };
+}
+/**
+ * The session's review after its server died: the lock still names the dead server. A fresh
+ * server takes the port the old one had, so the open page's origin stays valid and it reconnects;
+ * the session registers again from disk, where the page autosaved everything. Null when the
+ * session was not hosted by a dead server or its review already ended.
+ */
+async function revive(session) {
+    const home = stateDir();
+    const record = readServerRecord(home);
+    const lock = session.lockState();
+    if (record === null || lock.kind !== "stale" || lock.pid !== record.pid)
+        return null;
+    const latest = session.plans().at(-1);
+    if (latest === undefined || reviewsOf(session).some((r) => r.version === latest.version)) {
+        return null;
+    }
+    const server = (await findServer(home)) ?? (await spawnDetached(home, record.port));
+    const registration = {
+        dir: session.dir,
+        mode: reviewMode(session),
+        version: latest.version,
+        hash: latest.hash,
+        lockToken: null,
+    };
+    let summary;
+    try {
+        summary = await registerWith(server.port, registration);
+    }
+    catch (error) {
+        if (error instanceof RegistrationError)
+            return null;
+        throw error;
+    }
+    rememberPort(session, server.port);
+    say("review server restarted, nothing lost");
+    if (server.port !== record.port) {
+        say(portFallbackMessage(record.port, server.port));
+        say(`follow-me review: ${sessionUrl(server.port, summary)}`);
+        say("the open page cannot follow it to the new port; reopen it at that URL");
+    }
+    return { port: server.port, summary };
 }
 function timeoutOf(args) {
     const raw = args.values.get("timeout");
@@ -767,6 +817,7 @@ async function split(cwd, args) {
     say(headline(session));
     const open = await openOnServer(session, "split");
     if (open !== null) {
+        rememberPort(session, open.port);
         announce(sessionUrl(open.port, open.summary), args);
         next("end the review on the page, then follow-me report");
         return 0;
@@ -844,6 +895,76 @@ function finished(session, stored) {
     next("done; the user can port it with follow-me report --json");
     return 0;
 }
+/** Whether draft.json was written for the branch's current tip; a missing draft was not. */
+function draftForTip(session) {
+    try {
+        const raw = session.readDraft();
+        return (typeof raw === "object" && raw !== null && "tip" in raw && raw.tip === session.anchor.tip);
+    }
+    catch (error) {
+        if (error instanceof MissingDraftError)
+            return false;
+        throw error;
+    }
+}
+/**
+ * The branch moved after the latest plan. The first call writes that plan carried over to the new
+ * tip as draft.json; while the draft does not validate, each call writes the prompt with what
+ * changed and hands off. Null when the draft is ready, so the entry applies it as usual.
+ */
+function evolveHandoff(session, cwd, mode, args, moved, hosted) {
+    if (!draftForTip(session))
+        session.writeDraft(serializePlanFile(moved.draft));
+    if (draftState(session).kind === "valid")
+        return null;
+    const { since, vanished, added } = moved;
+    session.writePrompt(renderPrompt(promptInput(session, mode, args, { since, vanished, added })));
+    say(`wrote ${relative(cwd, session.promptPath)}`);
+    const step = `assign the new units in ${relative(cwd, session.draftPath)}, then run follow-me again`;
+    next(hosted ? `${step}; ${STILL_WORKING}` : step);
+    return 0;
+}
+const STILL_WORKING = "the reviewer is still working";
+/**
+ * Applies the draft carried over to the moved tip under the server's lock (only freezes it for a
+ * reviewer's walk) and moves the open page onto it, threads and all.
+ */
+async function swapOpenPage(session, open, args) {
+    const state = draftState(session);
+    if (state.kind !== "valid")
+        return 1;
+    const syntax = await checkSyntax(state.prepared, syntaxOverride(args));
+    if (syntax.issues.length > 0) {
+        for (const line of formatSyntax(syntax))
+            say(line);
+        next(`fix the draft, then run follow-me again; ${STILL_WORKING}`);
+        return 1;
+    }
+    if (open.summary.mode === "split") {
+        const code = await applyLocked(session, args);
+        if (code !== 0) {
+            next(`fix the draft, then run follow-me again; ${STILL_WORKING}`);
+            return code;
+        }
+    }
+    else
+        session.freeze(state.prepared);
+    const latest = session.plans().at(-1);
+    if (latest === undefined)
+        return 1;
+    const swapped = latest.version === open.summary.version
+        ? open.summary
+        : await swapVersion(open.port, open.summary, latest.version, latest.hash);
+    const carried = await fetchCarried(open.port, swapped);
+    const changed = carried.filter((c) => c.changed);
+    say(`swapped the open page to plan v${latest.version}; carried ${plural(carried.length, "comment")}, ${changed.length} changed`);
+    for (const { comment, path, newLine } of changed) {
+        const where = path === null ? "no file" : newLine === null ? path : `${path}:${newLine}`;
+        say(`  ${comment.id} now on ${where}`);
+    }
+    next(`${STILL_WORKING}; reply on each changed thread with follow-me reply <id> --body "<what changed and where>", then run follow-me again`);
+    return 0;
+}
 /** Writes the prompt for the agent and says where; used whenever there is no plan to review. */
 function promptHandoff(session, cwd, mode, args) {
     session.writePrompt(renderPrompt(promptInput(session, mode, args)));
@@ -856,25 +977,31 @@ function promptHandoff(session, cwd, mode, args) {
 function cursorPath(session) {
     return join(session.dir, "cursor.json");
 }
-/** Where the last `follow-me` stopped reading this hosted session's events; 0 for a new one. */
+function logOf(summary) {
+    return `${summary.id}@${summary.openedAt}`;
+}
 function readCursor(session, summary) {
     let raw;
     try {
         raw = JSON.parse(readFileSync(cursorPath(session), "utf8"));
     }
     catch {
-        return 0;
+        raw = null;
     }
-    if (typeof raw !== "object" || raw === null)
-        return 0;
-    const seen = "session" in raw ? raw.session : undefined;
-    const seq = "seq" in raw ? raw.seq : undefined;
-    const same = seen === `${summary.id}@${summary.openedAt}`;
-    return same && typeof seq === "number" && Number.isInteger(seq) && seq >= 0 ? seq : 0;
+    const { session: log, seq, seen: ids } = isFields(raw) ? raw : {};
+    const seen = new Set(Array.isArray(ids) ? ids.filter((id) => typeof id === "string") : []);
+    const counts = log === logOf(summary) && typeof seq === "number" && Number.isInteger(seq) && seq >= 0;
+    return { session: logOf(summary), seq: counts ? seq : 0, seen };
 }
-function writeCursor(session, summary, seq) {
-    const cursor = { session: `${summary.id}@${summary.openedAt}`, seq };
-    writeFileSync(cursorPath(session), `${JSON.stringify(cursor)}\n`);
+function writeCursor(session, cursor) {
+    const { session: log, seq, seen } = cursor;
+    writeFileSync(cursorPath(session), `${JSON.stringify({ session: log, seq, seen: [...seen] })}\n`);
+}
+/** The comment or reply id an event first carries, or null for events without one. */
+function saidId(event) {
+    if (event.type === "comment")
+        return event.comment.id;
+    return event.type === "reply" ? event.reply.id : null;
 }
 function waitOf(args) {
     const raw = args.values.get("wait");
@@ -884,9 +1011,11 @@ function waitOf(args) {
     if (!Number.isFinite(seconds) || seconds < 0) {
         throw new UsageError(`--wait ${raw} is not a number of seconds`);
     }
-    return seconds;
+    return Math.min(seconds, MAX_ENTRY_WAIT_SECONDS);
 }
-const ENTRY_WAIT_SECONDS = 60;
+/** One call fits inside a harness's tool timeout, so the agent's loop is one command per turn. */
+const ENTRY_WAIT_SECONDS = 90;
+const MAX_ENTRY_WAIT_SECONDS = 300;
 /**
  * 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.
@@ -895,28 +1024,38 @@ async function listen(session, open, args) {
     const { port, summary } = open;
     const waitMs = waitOf(args) * 1000;
     const deadline = Date.now() + waitMs;
-    let since = readCursor(session, summary);
+    let cursor = readCursor(session, summary);
     let version = summary.version;
     for (;;) {
         const left = Math.max(0, deadline - Date.now());
         let batch;
         try {
-            batch = await pollEvents(port, summary, since, Math.min(left, POLL_MS));
+            batch = await pollEvents(port, summary, cursor.seq, Math.min(left, POLL_MS));
         }
         catch (error) {
             if (!(error instanceof RegistrationError))
                 throw error;
             // The log restarted under us (a new server); read it from the start.
-            since = 0;
-            writeCursor(session, summary, 0);
+            cursor = { ...cursor, seq: 0 };
+            writeCursor(session, cursor);
             continue;
         }
-        since = batch.seq;
-        writeCursor(session, summary, since);
+        const fresh = batch.events.filter((e) => {
+            const id = saidId(e);
+            return id === null || !cursor.seen.has(id);
+        });
+        const seen = new Set(cursor.seen);
+        for (const event of batch.events) {
+            const id = saidId(event);
+            if (id !== null)
+                seen.add(id);
+        }
+        cursor = { ...cursor, seq: batch.seq, seen };
+        writeCursor(session, cursor);
         for (const event of batch.events)
             if (event.type === "version")
                 version = event.version;
-        const news = batch.events.filter(isNews);
+        const news = fresh.filter(isNews);
         if (news.length > 0) {
             const ctx = { commits: projectedCommits(session, version), units: session.diff.units };
             process.stdout.write(renderEvents(news, ctx));
@@ -933,12 +1072,11 @@ async function listen(session, open, args) {
                 next("done; the user can port it with follow-me report --json");
                 return 0;
             }
-            next('answer with follow-me reply <id> --body "<markdown>" [--diagram file], or run follow-me again to keep listening');
+            next(`${STILL_WORKING}; answer with follow-me reply <id> --body "<markdown>" [--diagram file], then run follow-me again`);
             return 0;
         }
         if (left <= 0) {
-            say(`nothing new on the review page in ${Math.round(waitMs / 1000)}s`);
-            next("run follow-me again to keep listening");
+            next(`${STILL_WORKING}; run follow-me again to keep listening`);
             return 0;
         }
     }
@@ -951,10 +1089,18 @@ async function listen(session, open, args) {
 async function entry(cwd, args) {
     syncSkills(homedir(), say);
     const session = await openFresh(cwd, args);
-    const hosted = await openOnServer(session, null);
+    const hosted = (await openOnServer(session, null)) ?? (await revive(session));
+    const mode = hosted?.summary.mode ?? (await entryMode(session, args));
+    const moved = await sinceLastPlan(session);
+    if (moved !== null) {
+        const handed = evolveHandoff(session, cwd, mode, args, moved, hosted !== null);
+        if (handed !== null)
+            return handed;
+        if (hosted !== null)
+            return swapOpenPage(session, hosted, args);
+    }
     if (hosted !== null)
         return listen(session, hosted, args);
-    const mode = await entryMode(session, args);
     const state = draftState(session);
     if (state.kind === "invalid") {
         next("fix the draft, then run follow-me again");
@@ -999,6 +1145,7 @@ async function entry(cwd, args) {
     const result = await hostReview(session, mode, detached, async () => prep, reportSaved);
     if (result.kind !== "elsewhere")
         return exitCode(result);
+    say("follow-me is interactive: keep running it until it prints the report");
     return listen(session, result, args);
 }
 /** Opens the session, re-extracting instead of failing when the branch moved or --base changed. */
@@ -1133,7 +1280,7 @@ function notOpen(session) {
  */
 async function watch(cwd, args) {
     const session = await openSession(cwd, sessionOpts(args));
-    const open = await openOnServer(session, null);
+    const open = (await openOnServer(session, null)) ?? (await revive(session));
     if (open === null)
         return notOpen(session);
     const sinceRaw = args.values.get("since");
@@ -1475,6 +1622,27 @@ function upgrade(targets, cwd) {
     return code;
 }
 const HELP_OR_VERSION = new Set(["--help", "--version"]);
+/**
+ * The port the page was last served on for this session. A server that died or exited idle
+ * takes its record with it; reusing the port keeps an open page on a live origin.
+ */
+function rememberedPort(session) {
+    try {
+        const raw = JSON.parse(readFileSync(join(session.dir, "page.json"), "utf8"));
+        if (typeof raw === "object" && raw !== null && "port" in raw) {
+            const port = raw.port;
+            if (typeof port === "number" && Number.isInteger(port) && port > 0)
+                return port;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+function rememberPort(session, port) {
+    writeFileSync(join(session.dir, "page.json"), `${JSON.stringify({ port })}\n`);
+}
 export async function main(argv, cwd) {
     const [command, ...rest] = argv;
     try {

package/dist/src/comments.js

@@ -133,11 +133,6 @@ export function parseComment(v) {
     const severity = v.severity;
     if (severity !== undefined && !isSeverity(severity))
         return "severity is unknown";
-    if (v.pending !== undefined && v.pending !== true)
-        return "pending is not true";
-    if (v.pending === true && (v.kind === "question" || v.author === "agent")) {
-        return "only a reviewer's flag can be pending";
-    }
     const replies = parseList(v.replies, parseReply, "replies");
     if (typeof replies === "string")
         return replies;
@@ -154,7 +149,6 @@ export function parseComment(v) {
         ...(v.kind === "question" ? { kind: "question" } : {}),
         ...(follows === undefined ? {} : { follows }),
         ...(severity === undefined ? {} : { severity }),
-        ...(v.pending === true ? { pending: true } : {}),
         ...(replies.length === 0 ? {} : { replies }),
         ...(v.author === "agent" ? { author: "agent" } : {}),
         ...(v.diagram === undefined ? {} : { diagram: v.diagram }),
@@ -193,7 +187,10 @@ export function parseNewDecision(concern, v) {
         return "the decision is not an object";
     return withDecision(concern, { ...v, decidedAt: undefined });
 }
-/** Absent reads as none. The first item that does not parse names its index and reason. */
+/**
+ * Absent reads as none. The first item that does not parse names its index and reason. Items
+ * are objects so a string result can only mean a failure; string values go through parseIds.
+ */
 function parseList(raw, parse, what) {
     if (raw === undefined)
         return [];
@@ -208,8 +205,26 @@ function parseList(raw, parse, what) {
     }
     return out;
 }
-function parseConcernId(item) {
-    return isConcernId(item) ? item : "not a concern id";
+/** Absent reads as none. The first item that is not an id of the kind names its index. */
+function parseIds(raw, is, what, kind) {
+    if (raw === undefined)
+        return [];
+    if (!isArray(raw))
+        return `${what} is not an array`;
+    const out = [];
+    for (const [i, item] of raw.entries()) {
+        if (!is(item))
+            return `${what}[${i}]: not a ${kind} id`;
+        out.push(item);
+    }
+    return out;
+}
+/** Keeps only the items that are ids of the kind. */
+function lenientIds(raw, is) {
+    return isArray(raw) ? raw.filter(is) : [];
+}
+function isCommentIdValue(item) {
+    return typeof item === "string" && isCommentId(item);
 }
 /** Absent reads as nothing excluded. */
 export function parseExcluded(v) {
@@ -217,17 +232,54 @@ export function parseExcluded(v) {
         return { comments: [], concerns: [] };
     if (!isFields(v))
         return "excluded is not an object";
-    const comments = parseList(v.comments, parseCommentId, "excluded.comments");
+    const comments = parseIds(v.comments, isCommentIdValue, "excluded.comments", "comment");
     if (typeof comments === "string")
         return comments;
-    const concerns = parseList(v.concerns, parseConcernId, "excluded.concerns");
+    const concerns = parseIds(v.concerns, isConcernId, "excluded.concerns", "concern");
     return typeof concerns === "string" ? concerns : { comments, concerns };
 }
 function asCommentId(item) {
-    return typeof item === "string" && isCommentId(item) ? item : null;
+    return isCommentIdValue(item) ? item : null;
+}
+function parseEarlierReplies(v) {
+    if (!isFields(v))
+        return "not an object";
+    const comment = asCommentId(v.comment);
+    if (comment === null)
+        return "comment is not a comment id";
+    const replies = parseList(v.replies, parseReply, "replies");
+    return typeof replies === "string" ? replies : { comment, replies };
+}
+function isLine(v) {
+    return typeof v === "number" && Number.isInteger(v) && v >= 1;
 }
-function parseCommentId(item) {
-    return asCommentId(item) ?? "not a comment id";
+export function parseCarried(v) {
+    if (!isFields(v)) {
+        return "not an object";
+    }
+    const comment = parseComment(v.comment);
+    if (typeof comment === "string")
+        return comment;
+    const { unit, offsets, changed, path, newLine } = v;
+    if (unit !== null && !(typeof unit === "string" && isUnitId(unit)))
+        return "unit is not a unit id";
+    if (offsets !== null && !(isArray(offsets) && offsets.every(isIndex))) {
+        return "offsets is not null or a list of rows";
+    }
+    if (typeof changed !== "boolean")
+        return "changed is not a boolean";
+    if (path !== null && !(typeof path === "string" && isRepoPath(path)))
+        return "path is not a path";
+    if (newLine !== null && !isLine(newLine))
+        return "newLine is not null or a line";
+    return {
+        comment,
+        unit,
+        offsets: offsets === null ? null : offsets.filter(isIndex),
+        changed,
+        path,
+        newLine,
+    };
 }
 /** Boundary parse of reviews/vN.json. Files written before walk mode existed have no mode. */
 export function parseReview(v) {
@@ -252,13 +304,16 @@ export function parseReview(v) {
     const concerns = parseList(v.concerns, parseDecision, "concerns");
     if (typeof concerns === "string")
         return concerns;
-    const resolved = parseList(v.resolved, parseCommentId, "resolved");
+    const resolved = parseIds(v.resolved, isCommentIdValue, "resolved", "comment");
     if (typeof resolved === "string")
         return resolved;
     const excluded = parseExcluded(v.excluded);
     if (typeof excluded === "string")
         return excluded;
     const anyExcluded = excluded.comments.length + excluded.concerns.length > 0;
+    const earlier = parseList(v.earlierReplies, parseEarlierReplies, "earlierReplies");
+    if (typeof earlier === "string")
+        return earlier;
     return {
         schema: v.schema,
         mode,
@@ -269,6 +324,7 @@ export function parseReview(v) {
         ...(concerns.length === 0 ? {} : { concerns }),
         ...(resolved.length === 0 ? {} : { resolved }),
         ...(anyExcluded ? { excluded } : {}),
+        ...(earlier.length === 0 ? {} : { earlierReplies: earlier }),
     };
 }
 function lenient(items, parse) {
@@ -291,8 +347,9 @@ export function parseDraft(v) {
     return {
         comments: lenient(v.comments, parseComment),
         concerns: lenient(v.concerns, parseDecision),
-        resolved: lenient(v.resolved, parseCommentId),
+        resolved: lenientIds(v.resolved, isCommentIdValue),
         excluded: typeof excluded === "string" ? { comments: [], concerns: [] } : excluded,
+        earlierReplies: lenient(v.earlierReplies, parseEarlierReplies),
     };
 }
 export function parseEvent(v) {
@@ -337,7 +394,10 @@ export function parseEvent(v) {
         case "version": {
             if (!isPlanVersion(v.version) || typeof v.hash !== "string")
                 return "malformed version event";
-            return { seq, type: v.type, version: v.version, hash: v.hash };
+            const carried = parseList(v.carried, parseCarried, "carried");
+            if (typeof carried === "string")
+                return carried;
+            return { seq, type: v.type, version: v.version, hash: v.hash, carried };
         }
         case "submitted":
             return { seq, type: v.type };

package/dist/src/diff.js

@@ -357,3 +357,14 @@ export function parseUnitRef(s) {
     }
     return { unit, select: { kind: "lines", changes } };
 }
+/** Where the hunk starts in the tip: its base position shifted by earlier hunks of the file. */
+export function tipStartOf(hunk, units) {
+    let shift = 0;
+    for (const u of units.values()) {
+        if (u.kind !== "hunk" || u.path !== hunk.path || u.oldStart >= hunk.oldStart)
+            continue;
+        for (const line of u.body)
+            shift += line.op === "+" ? 1 : line.op === "-" ? -1 : 0;
+    }
+    return hunk.oldStart + shift + 1;
+}