@shiyuphan/follow-me 0.2.0 → 0.4.0

package/dist/src/comments.js

@@ -14,8 +14,9 @@ function isIndex(v) {
     return typeof v === "number" && Number.isInteger(v) && v >= 0;
 }
 function parseAnchor(v) {
-    if (!isFields(v))
+    if (!isFields(v)) {
         return "anchor is not an object";
+    }
     if (v.kind === "plan")
         return { kind: "plan" };
     if (!isIndex(v.commit))
@@ -27,12 +28,25 @@ function parseAnchor(v) {
         return "anchor.kind is unknown";
     if (typeof v.unit !== "string" || !isUnitId(v.unit))
         return "anchor.unit is not a unit id";
-    if (v.changes === null)
+    if (v.changes === null) {
+        if (v.offsets !== undefined)
+            return "anchor.offsets needs anchor.changes to be a list";
         return { kind: "hunk", unit: v.unit, commit, changes: null };
+    }
     if (!isArray(v.changes) || !v.changes.every(isIndex)) {
         return "anchor.changes is not null or a list of change indices";
     }
-    return { kind: "hunk", unit: v.unit, commit, changes: v.changes.filter(isIndex) };
+    const changes = v.changes.filter(isIndex);
+    if (v.offsets === undefined)
+        return { kind: "hunk", unit: v.unit, commit, changes };
+    if (!isArray(v.offsets) || v.offsets.length === 0 || !v.offsets.every(isIndex)) {
+        return "anchor.offsets is not a non-empty list of row indices";
+    }
+    const offsets = v.offsets.filter(isIndex);
+    if (!offsets.every((o, i) => i === 0 || o > (offsets[i - 1] ?? 0))) {
+        return "anchor.offsets is not strictly ascending";
+    }
+    return { kind: "hunk", unit: v.unit, commit, changes, offsets };
 }
 /** A stored reply. Replies a client posts go through parseNewReply, which mints id and time. */
 export function parseReply(v) {
@@ -101,6 +115,17 @@ export function parseComment(v) {
     }
     if (v.kind !== undefined && v.kind !== "question")
         return 'kind is not "question"';
+    if (v.author !== undefined && v.author !== "agent")
+        return 'author is not "agent"';
+    if (v.diagram !== undefined) {
+        if (typeof v.diagram !== "string")
+            return "diagram is not a string";
+        if (v.author !== "agent")
+            return "diagram is only for an agent's comment";
+        const problem = diagramProblem(v.diagram);
+        if (problem !== null)
+            return `diagram: ${problem}`;
+    }
     const follows = v.follows;
     if (follows !== undefined && !(typeof follows === "string" && isCommentId(follows))) {
         return "follows is not a comment id";
@@ -125,6 +150,8 @@ export function parseComment(v) {
         ...(follows === undefined ? {} : { follows }),
         ...(severity === undefined ? {} : { severity }),
         ...(replies.length === 0 ? {} : { replies }),
+        ...(v.author === "agent" ? { author: "agent" } : {}),
+        ...(v.diagram === undefined ? {} : { diagram: v.diagram }),
     };
 }
 function withDecision(concern, v) {
@@ -135,11 +162,15 @@ function withDecision(concern, v) {
         return "severity is unknown";
     if (v.note !== undefined && typeof v.note !== "string")
         return "note is not a string";
+    if (v.decidedAt !== undefined && typeof v.decidedAt !== "string") {
+        return "decidedAt is not a string";
+    }
     return {
         concern,
         decision: v.decision,
         ...(v.severity === undefined ? {} : { severity: v.severity }),
         ...(v.note === undefined || v.note.trim() === "" ? {} : { note: v.note }),
+        ...(v.decidedAt === undefined ? {} : { decidedAt: v.decidedAt }),
     };
 }
 /** A stored decision. */
@@ -150,11 +181,11 @@ export function parseDecision(v) {
         return "concern is not a concern id";
     return withDecision(v.concern, v);
 }
-/** The body of POST .../concerns/<id>; the id comes from the URL. */
+/** The body of POST .../concerns/<id>; the id comes from the URL and the time is the server's. */
 export function parseNewDecision(concern, v) {
     if (!isFields(v))
         return "the decision is not an object";
-    return withDecision(concern, v);
+    return withDecision(concern, { ...v, decidedAt: undefined });
 }
 /** Absent reads as none. The first item that does not parse names its index and reason. */
 function parseList(raw, parse, what) {
@@ -171,12 +202,67 @@ function parseList(raw, parse, what) {
     }
     return out;
 }
+function parseConcernId(item) {
+    return isConcernId(item) ? item : "not a concern id";
+}
+/** Absent reads as nothing excluded. */
+export function parseExcluded(v) {
+    if (v === undefined)
+        return { comments: [], concerns: [] };
+    if (!isFields(v))
+        return "excluded is not an object";
+    const comments = parseList(v.comments, parseCommentId, "excluded.comments");
+    if (typeof comments === "string")
+        return comments;
+    const concerns = parseList(v.concerns, parseConcernId, "excluded.concerns");
+    return typeof concerns === "string" ? concerns : { comments, concerns };
+}
 function asCommentId(item) {
     return typeof item === "string" && isCommentId(item) ? item : null;
 }
 function parseCommentId(item) {
     return asCommentId(item) ?? "not a comment id";
 }
+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;
+}
+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) {
     if (!isFields(v)) {
@@ -203,6 +289,13 @@ export function parseReview(v) {
     const resolved = parseList(v.resolved, parseCommentId, "resolved");
     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,
@@ -212,6 +305,8 @@ export function parseReview(v) {
         comments,
         ...(concerns.length === 0 ? {} : { concerns }),
         ...(resolved.length === 0 ? {} : { resolved }),
+        ...(anyExcluded ? { excluded } : {}),
+        ...(earlier.length === 0 ? {} : { earlierReplies: earlier }),
     };
 }
 function lenient(items, parse) {
@@ -230,10 +325,13 @@ export function parseDraft(v) {
     if (!isFields(v) || !isArray(v.comments)) {
         return "not a review draft";
     }
+    const excluded = parseExcluded(v.excluded);
     return {
         comments: lenient(v.comments, parseComment),
         concerns: lenient(v.concerns, parseDecision),
         resolved: lenient(v.resolved, parseCommentId),
+        excluded: typeof excluded === "string" ? { comments: [], concerns: [] } : excluded,
+        earlierReplies: lenient(v.earlierReplies, parseEarlierReplies),
     };
 }
 export function parseEvent(v) {
@@ -278,8 +376,13 @@ 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 };
         case "ended":
             return typeof v.review === "string"
                 ? { seq, type: v.type, review: v.review }

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;
+}

package/dist/src/evolve.js

@@ -0,0 +1,123 @@
+/**
+ * How a plan follows its branch when the tip moves. A unit id hashes its path and hunk body, so
+ * an id that survives names the same change and keeps its place in the plan; everything else is
+ * either gone or new, and the agent decides where the new units go.
+ */
+import { tipStartOf } from "./diff.js";
+/** Pure. Responses start empty: they answer the review of the old version, not this one. */
+export function evolvePlan(oldPlan, oldDiff, newDiff) {
+    const gone = new Map();
+    const commits = [];
+    oldPlan.commits.forEach((commit, index) => {
+        const units = commit.units.filter((ref) => newDiff.units.has(ref.unit));
+        for (const ref of commit.units) {
+            const unit = oldDiff.units.get(ref.unit);
+            if (newDiff.units.has(ref.unit) || unit === undefined)
+                continue;
+            const seen = gone.get(ref.unit)?.commits ?? [];
+            gone.set(ref.unit, { unit, commits: [...seen, { index, message: commit.message }] });
+        }
+        if (units.length > 0)
+            commits.push({ ...commit, units });
+    });
+    const taken = new Set(oldPlan.commits.flatMap((c) => c.units.map((ref) => ref.unit)));
+    return {
+        draft: {
+            schema: oldPlan.schema,
+            base: newDiff.base,
+            tip: newDiff.tip,
+            commits,
+            responses: [],
+        },
+        vanished: [...gone.values()],
+        added: [...newDiff.units.values()].filter((unit) => !taken.has(unit.id)),
+    };
+}
+/** The tip line of each body row; a removed row gets the line that follows it. */
+function tipLines(hunk, units) {
+    let line = tipStartOf(hunk, units);
+    return hunk.body.map((row) => {
+        const at = line;
+        if (row.op !== "-")
+            line += 1;
+        return at;
+    });
+}
+/** The body row a hunk comment points at first: its first picked row, else its first change. */
+function firstRow(comment, hunk) {
+    const { anchor } = comment;
+    if (anchor.kind !== "hunk")
+        return 0;
+    const picked = anchor.offsets?.[0];
+    if (picked !== undefined)
+        return picked;
+    const change = anchor.changes?.[0];
+    const row = hunk.body.findIndex((r) => r.op !== " " && r.change === change);
+    return change === undefined || row === -1 ? 0 : row;
+}
+/**
+ * Where an old line lands in a replacement hunk: the nearest row with the same text the tip
+ * keeps, else the old line clamped into the hunk's tip lines.
+ */
+function landing(hunk, units, oldLine, text) {
+    const lines = tipLines(hunk, units);
+    const same = hunk.body.flatMap((row, i) => row.op !== "-" && row.text === text ? [lines[i] ?? oldLine] : []);
+    if (same.length > 0) {
+        return same.reduce((a, b) => (Math.abs(b - oldLine) < Math.abs(a - oldLine) ? b : a));
+    }
+    const [from, to] = span(hunk, units);
+    return Math.min(Math.max(oldLine, from), to);
+}
+/** First and last tip line of a hunk; a pure removal spans the one line after it. */
+function span(hunk, units) {
+    const from = tipStartOf(hunk, units);
+    const kept = hunk.body.filter((row) => row.op !== "-").length;
+    return [from, from + Math.max(kept, 1) - 1];
+}
+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));
+}
+function carry(comment, oldUnits, newUnits) {
+    const { anchor } = comment;
+    const nowhere = { comment, unit: null, offsets: null, newLine: null };
+    if (anchor.kind !== "hunk")
+        return { ...nowhere, changed: false, path: comment.context.path };
+    const kept = newUnits.get(anchor.unit);
+    if (kept !== undefined) {
+        const newLine = kept.kind === "hunk" ? (tipLines(kept, newUnits)[firstRow(comment, kept)] ?? null) : null;
+        return {
+            comment,
+            unit: kept.id,
+            offsets: anchor.offsets ?? null,
+            changed: false,
+            path: kept.path,
+            newLine,
+        };
+    }
+    const old = oldUnits.get(anchor.unit);
+    const path = old?.path ?? comment.context.path;
+    const onPath = [...newUnits.values()].filter((u) => u.path === path);
+    const first = onPath[0];
+    if (first === undefined)
+        return { ...nowhere, changed: true, path };
+    const moved = { comment, offsets: null, changed: true, path };
+    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 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: landing(nearest, newUnits, oldLine, old.body[row]?.text),
+    };
+}

package/dist/src/git.js

@@ -134,6 +134,18 @@ export async function loadDiff(repo, baseRef, tipRef) {
     const blobs = await catBlobs(repo, neededBlobs(rawZ, patchText));
     return parseDiff({ base, tip, baseTree, tipTree, rawZ, patch: patchText, blobs });
 }
+/**
+ * Whether the configured user wrote every commit of base..tip, which is how follow-me tells its
+ * author's own branch from one it is asked to review. False when no user.email is set.
+ */
+export async function isOwnWork(repo, base, tip) {
+    const me = await gitText(repo, ["config", "--default=", "user.email"]);
+    if (me === "")
+        return false;
+    const authors = await gitText(repo, ["log", "--format=%ae", `${base}..${tip}`]);
+    const emails = authors.split("\n").filter((line) => line !== "");
+    return emails.length > 0 && emails.every((email) => email === me);
+}
 export async function signing(repo, mode) {
     const configured = await gitText(repo, [
         "config",

package/dist/src/host.js

@@ -3,10 +3,11 @@ import { randomUUID } from "node:crypto";
 import { closeSync, linkSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { parseEvent, parseEventBatch } from "./comments.js";
+import { parseCarried, parseEvent, parseEventBatch } from "./comments.js";
+import { carryComments } from "./evolve.js";
 import { isPlanVersion, serializePlanFile, validatePlan } from "./plan.js";
 import { HEALTH_APP, isSessionId, loadDraftComments, PortInUseError, RegistrationError, startServer, } from "./server.js";
-import { BranchMovedError, isAlive, openSessionAt, SessionFileError, SessionLockedError, } from "./session.js";
+import { BranchMovedError, diffOfPlan, isAlive, openSessionAt, SessionFileError, SessionLockedError, } from "./session.js";
 const RECORD = "server.json";
 const DEFAULT_IDLE_MS = 30_000;
 const START_TIMEOUT_MS = 10_000;
@@ -125,7 +126,7 @@ async function loadHosted(registration, held) {
         if (!verdict.ok) {
             throw new RegistrationError(`plan v${version} no longer fits ${branch}; check it again`);
         }
-        const reviewsDir = session.reviewsDir(mode);
+        const reviewsDir = session.reviewsDir();
         const comments = await loadDraftComments(reviewsDir, version);
         const prior = session.priorReview(mode, version);
         const previous = prior === null || prior.comments.length === 0
@@ -135,7 +136,12 @@ async function loadHosted(registration, held) {
                 comments: prior.comments,
                 responses: stored.file.responses,
             };
-        const command = mode === "walk" ? "walk" : "review";
+        const priorPlan = session.plans().find((p) => p.version === previous?.version);
+        const before = priorPlan === undefined ? null : await diffOfPlan(session, priorPlan);
+        const carried = previous === null
+            ? []
+            : carryComments(previous.comments, before?.units ?? new Map(), session.diff.units);
+        const command = "review";
         // A version swap runs inside the server that already owns this session's lock.
         const release = held ??
             (lockToken === null ? session.lock(command) : session.adoptLock(lockToken, command)).release;
@@ -144,6 +150,7 @@ async function loadHosted(registration, held) {
             reviewsDir,
             release,
             previous,
+            carried,
             state: {
                 mode,
                 anchor: session.anchor,
@@ -250,14 +257,16 @@ async function call(port, method, path, body) {
 function parseSummary(raw) {
     if (!isFields(raw))
         return null;
-    const { id, url, repo, branch, mode, version, comments } = raw;
+    const { id, url, repo, branch, mode, version, comments, openedAt } = raw;
     if (typeof url !== "string" || typeof repo !== "string")
         return null;
     if (typeof branch !== "string" || (mode !== "split" && mode !== "walk"))
         return null;
     if (!isSessionId(id) || !isPlanVersion(version) || typeof comments !== "number")
         return null;
-    return { id, url, repo, branch, mode, version, comments };
+    if (typeof openedAt !== "string")
+        return null;
+    return { id, url, repo, branch, mode, version, comments, openedAt };
 }
 /** Registers a session with the server on this port; the same session yields the same URL. */
 export async function registerWith(port, registration) {
@@ -273,6 +282,19 @@ export async function swapVersion(port, summary, version, hash) {
         throw new RegistrationError("the server answered with a malformed session");
     return swapped;
 }
+/** The previous version's comments as the open page places them on its plan. */
+export async function fetchCarried(port, summary) {
+    const state = await call(port, "GET", `${summary.url}api/state`);
+    const raw = isFields(state) ? state["carried"] : undefined;
+    if (!Array.isArray(raw))
+        throw new RegistrationError("the server sent no carried comments");
+    return raw.flatMap((item) => {
+        const carried = parseCarried(item);
+        if (typeof carried === "string")
+            throw new RegistrationError(`carried: ${carried}`);
+        return [carried];
+    });
+}
 /** One long poll of the session's event log: what happened after `since`, or nothing at timeout. */
 export async function pollEvents(port, summary, since, timeoutMs) {
     const path = `${summary.url}api/events?since=${since}&timeout=${timeoutMs}`;
@@ -317,9 +339,18 @@ export async function postReply(port, summary, commentId, reply) {
         throw new RegistrationError("the server answered without a reply id");
     return id;
 }
+/** Posts a comment the agent starts and returns its id; the server mints id and time. */
+export async function postComment(port, summary, comment) {
+    const body = await call(port, "POST", `${summary.url}api/comments`, comment);
+    const id = isFields(body) ? body["id"] : undefined;
+    if (typeof id !== "string") {
+        throw new RegistrationError("the server answered without a comment id");
+    }
+    return id;
+}
 /** The consolidated report of the hosted session as it stands. */
-export async function fetchReport(port, summary) {
-    const res = await fetch(`${sessionUrl(port, summary)}api/report`);
+export async function fetchReport(port, summary, format = "markdown") {
+    const res = await fetch(`${sessionUrl(port, summary)}api/report?format=${format}`);
     if (!res.ok)
         throw new RegistrationError(`GET api/report failed with ${res.status}`);
     return res.text();

package/dist/src/install.js

@@ -122,6 +122,27 @@ export function runInstall(options, home, repoRoot, say, skillDir = findSkillDir
         }
     });
 }
+/**
+ * Keeps the skill current in every harness found at user scope: writes what is missing or differs
+ * from the shipped copy and says so, one line per file; says nothing when all is current. A host
+ * with no harness, or a package without its skill folder, is not an error here.
+ */
+export function syncSkills(home, say, skillDir) {
+    try {
+        const dir = skillDir ?? findSkillDir();
+        const targets = { harness: undefined, all: false, project: false, dryRun: false };
+        for (const file of planSkillFiles(targets, home, home)) {
+            const line = writeSkill(dir, file, false);
+            if (line.startsWith("wrote "))
+                say(line);
+        }
+    }
+    catch (error) {
+        if (error instanceof InstallError)
+            return;
+        process.stderr.write(`follow-me: could not update the skill: ${error instanceof Error ? error.message : error}\n`);
+    }
+}
 export function runUninstall(options, home, repoRoot, say) {
     return reportingErrors(() => {
         for (const file of planSkillFiles(options, home, repoRoot)) {

package/dist/src/plan.js

@@ -645,7 +645,7 @@ export function validatePlan(diff, draft, opts = {}) {
     const warnings = review === null
         ? []
         : review.comments
-            .filter((c) => !answered.has(c.id))
+            .filter((c) => c.author !== "agent" && !answered.has(c.id))
             .map((c) => ({ kind: "unanswered", comment: c.id, review: review.planVersion }));
     file.commits.forEach((c, commit) => {
         const length = (c.message.split("\n")[0] ?? "").length;