@shiyuphan/follow-me 0.1.1 → 0.2.0

package/dist/src/session.js

@@ -1,9 +1,10 @@
 import { randomUUID } from "node:crypto";
-import { existsSync, linkSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { existsSync, linkSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { basename, dirname, join } from "node:path";
-import { isRepoPath, isSha, isUnitId } from "./diff.js";
-import { branchExists, currentBranch, defaultBaseRef, loadDiff, objectsDir, QUARANTINE_PREFIX, repoRoot, resolveCommit, } from "./git.js";
-import { isArray, isCommentId, isFields, isPlanVersion, parsePlanFile, planHash, serializePlanFile, } from "./plan.js";
+import { parseDraft, parseReview } from "./comments.js";
+import { isSha } from "./diff.js";
+import { branchExists, currentBranch, defaultBaseRef, GitError, loadDiff, objectsDir, QUARANTINE_PREFIX, repoRoot, resolveCommit, } from "./git.js";
+import { isFields, isPlanVersion, parsePlanFile, planHash, serializePlanFile, } from "./plan.js";
 export class BranchMovedError extends Error {
     name = "BranchMovedError";
 }
@@ -11,6 +12,21 @@ export class BranchMovedError extends Error {
 export class SessionFileError extends Error {
     name = "SessionFileError";
 }
+/** draft.json has not been written yet. */
+export class MissingDraftError extends SessionFileError {
+    path;
+    constructor(path) {
+        super(`${path} does not exist yet`);
+        this.path = path;
+    }
+}
+/** The command ran outside any git work tree. */
+export class NotARepositoryError extends Error {
+    name = "NotARepositoryError";
+    constructor() {
+        super("not a git repository (run it inside the repo you want to split)");
+    }
+}
 /** Another live follow-me process holds the session's lock. */
 export class SessionLockedError extends Error {
     name = "SessionLockedError";
@@ -118,12 +134,15 @@ function adoptLock(dir, from, command) {
 export function slugOf(branch) {
     return branch.replaceAll("/", "-");
 }
-function writeJson(path, value) {
+function writeText(path, text) {
     mkdirSync(dirname(path), { recursive: true });
     const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
-    writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`);
+    writeFileSync(temp, text);
     renameSync(temp, path);
 }
+function writeJson(path, value) {
+    writeText(path, `${JSON.stringify(value, null, 2)}\n`);
+}
 function readJson(path) {
     let text;
     try {
@@ -169,101 +188,24 @@ function parseAnchor(v) {
 function parseApplied(v) {
     if (!isFields(v))
         return null;
-    const { schema, version, branch, head } = v;
+    const { schema, version, branch, head, hash = null, signed = null } = v;
     if (schema !== "follow-me/applied@1" || !isPlanVersion(version))
         return null;
     if (typeof branch !== "string" || typeof head !== "string" || !isSha(head))
         return null;
-    return { schema, version, branch, head };
-}
-function isCommitIndex(v) {
-    return typeof v === "number" && Number.isInteger(v) && v >= 0;
-}
-function parseCommentAnchor(v) {
-    if (!isFields(v))
-        return "anchor is not an object";
-    if (v.kind === "plan")
-        return { kind: "plan" };
-    if (!isCommitIndex(v.commit))
-        return "anchor.commit is not a commit index";
-    const commit = v.commit;
-    if (v.kind === "message" || v.kind === "position")
-        return { kind: v.kind, commit };
-    if (v.kind !== "hunk")
-        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)
-        return { kind: "hunk", unit: v.unit, commit, changes: null };
-    if (!isArray(v.changes) || !v.changes.every(isCommitIndex)) {
-        return "anchor.changes is not null or a list of change indices";
-    }
-    return { kind: "hunk", unit: v.unit, commit, changes: v.changes.filter(isCommitIndex) };
-}
-function parseComment(v) {
-    if (!isFields(v))
-        return "not an object";
-    if (typeof v.id !== "string" || !isCommentId(v.id))
-        return "id is not a comment id";
-    const anchor = parseCommentAnchor(v.anchor);
-    if (typeof anchor === "string")
-        return anchor;
-    const ctx = v.context;
-    if (!isFields(ctx) || typeof ctx.commitMessage !== "string") {
-        return "context.commitMessage is not a string";
-    }
-    const path = ctx.path;
-    if (path !== null && (typeof path !== "string" || !isRepoPath(path))) {
-        return "context.path is not null or a path";
-    }
-    if (typeof v.body !== "string" || typeof v.createdAt !== "string") {
-        return "body and createdAt must be strings";
-    }
-    return {
-        id: v.id,
-        anchor,
-        context: { commitMessage: ctx.commitMessage, path },
-        body: v.body,
-        createdAt: v.createdAt,
-    };
-}
-/** Boundary parse of reviews/vN.json. Files written before walk mode existed have no mode. */
-export function parseReview(v) {
-    if (!isFields(v)) {
-        return "not an object";
-    }
-    if (v.schema !== "follow-me/review@1")
-        return 'schema is not "follow-me/review@1"';
-    const mode = v.mode ?? "split";
-    if (mode !== "split" && mode !== "walk")
-        return 'mode is not "split" or "walk"';
-    if (!isPlanVersion(v.planVersion))
-        return "planVersion is not a positive integer";
-    if (typeof v.planHash !== "string" || typeof v.endedAt !== "string") {
-        return "planHash and endedAt must be strings";
-    }
-    if (!isArray(v.comments))
-        return "comments is not an array";
-    const comments = [];
-    for (const [i, raw] of v.comments.entries()) {
-        const c = parseComment(raw);
-        if (typeof c === "string")
-            return `comments[${i}]: ${c}`;
-        comments.push(c);
-    }
-    return {
-        schema: v.schema,
-        mode,
-        planVersion: v.planVersion,
-        planHash: v.planHash,
-        endedAt: v.endedAt,
-        comments,
-    };
+    if (hash !== null && typeof hash !== "string")
+        return null;
+    if (signed !== null && typeof signed !== "boolean")
+        return null;
+    return { schema, version, branch, head, hash, signed };
 }
 function makeSession(root, dir, anchor, diff) {
     const plansDir = join(dir, "plans");
-    const reviewsDir = join(dir, "reviews");
+    const splitReviews = join(dir, "reviews");
+    const walkReviewsDir = join(splitReviews, "walk");
+    const reviewsDir = (mode) => mode === "walk" ? walkReviewsDir : splitReviews;
     const draftPath = join(dir, "draft.json");
+    const promptPath = join(dir, "prompt.md");
     const appliedPath = join(dir, "applied.json");
     const plans = () => versions(plansDir).map(({ version, path }) => {
         const file = parsePlanFile(readJson(path));
@@ -274,30 +216,74 @@ function makeSession(root, dir, anchor, diff) {
         }
         return { version, file, hash: planHash(file) };
     });
-    const reviews = () => versions(reviewsDir).map(({ version, path }) => {
+    const reviewsIn = (mode) => versions(reviewsDir(mode)).map(({ version, path }) => {
         const review = parseReview(readJson(path));
         if (typeof review === "string")
             throw new SessionFileError(`${path}: ${review}`);
         return { version, review };
     });
+    const reviews = () => reviewsIn("split");
+    const walkReviews = () => [...reviews().filter((r) => r.review.mode === "walk"), ...reviewsIn("walk")].sort((a, b) => a.version - b.version);
+    const draftVersions = (mode) => {
+        const dir = reviewsDir(mode);
+        if (!existsSync(dir))
+            return [];
+        return readdirSync(dir).flatMap((name) => {
+            const n = Number(/^v([1-9][0-9]*)\.draft\.json$/.exec(name)?.[1]);
+            return isPlanVersion(n) ? [n] : [];
+        });
+    };
+    const draftReview = (mode, version) => {
+        const path = join(reviewsDir(mode), `v${version}.draft.json`);
+        const draft = parseDraft(readJson(path));
+        if (typeof draft === "string")
+            throw new SessionFileError(`${path}: ${draft}`);
+        const { comments, concerns, resolved } = draft;
+        return {
+            schema: "follow-me/review@1",
+            mode,
+            planVersion: version,
+            planHash: plans().find((p) => p.version === version)?.hash ?? "",
+            endedAt: statSync(path).mtime.toISOString(),
+            comments,
+            ...(concerns.length === 0 ? {} : { concerns }),
+            ...(resolved.length === 0 ? {} : { resolved }),
+        };
+    };
+    const priorReview = (mode, before) => {
+        const below = (v) => before === null || v < before;
+        const done = (mode === "walk" ? walkReviews() : reviews().filter((r) => r.review.mode === mode))
+            .filter((r) => below(r.version))
+            .at(-1);
+        const unfinished = draftVersions(mode)
+            .filter((v) => below(v) && v > (done?.version ?? 0))
+            .sort((a, b) => a - b)
+            .at(-1);
+        return unfinished === undefined ? (done?.review ?? null) : draftReview(mode, unfinished);
+    };
     return {
         root,
         dir,
         anchor,
         diff,
         draftPath,
+        promptPath,
         plans,
+        reviewsDir,
         reviews,
-        lastReview: () => reviews().findLast((r) => r.review.mode === "split")?.review ?? null,
+        walkReviews,
+        lastReview: () => priorReview("split", null),
+        priorReview,
         readDraft: () => {
             const draft = readJson(draftPath);
             if (draft === undefined)
-                throw new SessionFileError(`${draftPath} does not exist yet`);
+                throw new MissingDraftError(draftPath);
             return draft;
         },
         writeDraft: (draft) => writeJson(draftPath, draft),
+        writePrompt: (text) => writeText(promptPath, text),
         writeReview: (review) => {
-            const path = join(reviewsDir, `v${review.planVersion}.json`);
+            const path = join(reviewsDir(review.mode), `v${review.planVersion}.json`);
             if (existsSync(path))
                 throw new SessionFileError(`${path} is already written`);
             writeJson(path, review);
@@ -324,16 +310,30 @@ function makeSession(root, dir, anchor, diff) {
                 throw new SessionFileError(`${appliedPath} is not an applied record`);
             return applied;
         },
-        recordApplied: (version, result) => writeJson(appliedPath, {
+        recordApplied: (plan, result) => writeJson(appliedPath, {
             schema: "follow-me/applied@1",
-            version,
+            version: plan.version,
             branch: result.branch,
             head: result.head,
+            hash: plan.hash,
+            signed: result.signed,
         }),
     };
 }
+/** The top level of the work tree holding cwd. */
+async function rootOf(cwd) {
+    try {
+        return await repoRoot(cwd);
+    }
+    catch (error) {
+        if (error instanceof GitError && error.message.includes("not a git repository")) {
+            throw new NotARepositoryError();
+        }
+        throw error;
+    }
+}
 async function locate(repo, branch) {
-    const root = await repoRoot(repo);
+    const root = await rootOf(repo);
     const name = branch ?? (await currentBranch(root));
     if (name === null)
         throw new Error("HEAD is detached; pass --branch <name>");
@@ -421,8 +421,7 @@ function abandonedTemps(dir) {
         .map((name) => join(dir, name));
 }
 /** Review drafts for a version at or below the latest finished review; none can be resumed. */
-function deadReviewDrafts(dir) {
-    const reviewsDir = join(dir, "reviews");
+function deadReviewDrafts(reviewsDir) {
     const latest = versions(reviewsDir).at(-1)?.version ?? 0;
     if (!existsSync(reviewsDir))
         return [];
@@ -441,7 +440,7 @@ function deadReviewDrafts(dir) {
  * a live process are left alone, and all refuses while one exists.
  */
 export async function cleanSessions(repo, opts) {
-    const root = await repoRoot(repo);
+    const root = await rootOf(repo);
     const top = join(root, ".follow-me");
     const sessions = existsSync(top)
         ? readdirSync(top, { withFileTypes: true })
@@ -466,7 +465,8 @@ export async function cleanSessions(repo, opts) {
         }
         if (lock.kind === "stale")
             found.push(join(dir, "lock"));
-        found.push(...abandonedTemps(dir), ...deadReviewDrafts(dir));
+        const reviews = join(dir, "reviews");
+        found.push(...abandonedTemps(dir), ...deadReviewDrafts(reviews), ...deadReviewDrafts(join(reviews, "walk")));
     }
     if (opts.all && existsSync(top))
         found.push(top);

package/dist/src/syntax.js

@@ -0,0 +1,199 @@
+import { execFile } from "node:child_process";
+import { mkdtemp, realpath, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { extname, join } from "node:path";
+const LIMIT = 4;
+const TIMEOUT_MS = 30_000;
+/**
+ * node --check does not strip types, so .ts goes through module.stripTypeScriptTypes, which
+ * parses the whole file and throws on a syntax error. An enum or namespace parses but cannot be
+ * stripped, which is node's limit and not the file's, so that counts as parsing.
+ */
+const STRIP_TYPES = `
+const { stripTypeScriptTypes } = require("node:module");
+const { readFileSync } = require("node:fs");
+try {
+  stripTypeScriptTypes(readFileSync(process.argv[1], "utf8"), { mode: "strip" });
+} catch (error) {
+  if (error.code === "ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX") process.exit(0);
+  console.error(error.message);
+  process.exit(1);
+}`;
+/** Runs argv with {file} replaced; a program that is not installed skips the file. */
+function command(argv) {
+    return (file) => run(argv.map((a) => (a === "{file}" ? file : a)), file, argv[0] ?? "");
+}
+function run(argv, file, what) {
+    const [program, ...rest] = argv;
+    if (program === undefined)
+        return Promise.resolve({ kind: "parses" });
+    return new Promise((resolve) => {
+        execFile(program, rest, { timeout: TIMEOUT_MS, encoding: "utf8" }, (error, stdout, stderr) => {
+            if (error === null)
+                return resolve({ kind: "parses" });
+            if (error.code === "ENOENT") {
+                return resolve({ kind: "skipped", reason: `${what} is not installed` });
+            }
+            const output = stderr.trim() === "" ? stdout : stderr;
+            const message = error.killed === true
+                ? `checker timed out after ${TIMEOUT_MS / 1000}s`
+                : output.trim() === ""
+                    ? `checker exited ${error.code}`
+                    : complaint(output, file);
+            resolve({ kind: "fails", message });
+        });
+    });
+}
+/**
+ * The line of a parser's output that names the problem. node prints `file:LINE`, the source line,
+ * a caret and then `SyntaxError: ...`; python prints a traceback ending in `SyntaxError: ...`;
+ * sh and bash print one line. The temp path never leaks into the message.
+ */
+export function complaint(output, file) {
+    const lines = output
+        .replaceAll(file, "file")
+        .split("\n")
+        .map((l) => l.trimEnd())
+        .filter((l) => l !== "");
+    const named = lines.find((l) => /^[A-Za-z]*Error\b/.test(l));
+    if (named === undefined)
+        return lines[0] ?? "does not parse";
+    const where = /^file:(\d+)$/.exec(lines[0] ?? "")?.[1];
+    return where === undefined ? named : `line ${where}: ${named}`;
+}
+const json = async (_file, text) => {
+    try {
+        JSON.parse(text);
+        return { kind: "parses" };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { kind: "fails", message: message.split("\n")[0] ?? message };
+    }
+};
+/** Bash scripts need bash -n; a plain .sh is held to POSIX unless its shebang names bash. */
+const sh = command(["sh", "-n", "{file}"]);
+const bash = command(["bash", "-n", "{file}"]);
+const shell = (file, text) => /^#!.*\bbash\b/.test(text) || file.endsWith(".bash") ? bash(file, text) : sh(file, text);
+const node = command(["node", "--check", "{file}"]);
+const types = command([
+    "node",
+    "--disable-warning=ExperimentalWarning",
+    "-e",
+    STRIP_TYPES,
+    "{file}",
+]);
+const python = command(["python3", "-m", "py_compile", "{file}"]);
+/**
+ * Extension to checker. A missing extension is skipped, not guessed: .jsx and .tsx need a JSX
+ * parser node does not have, and yaml has none installed.
+ */
+const CHECKERS = new Map([
+    [".js", node],
+    [".mjs", node],
+    [".cjs", node],
+    [".ts", types],
+    [".mts", types],
+    [".cts", types],
+    [".json", json],
+    [".sh", shell],
+    [".bash", shell],
+    [".py", python],
+]);
+function quote(s) {
+    return `'${s.replaceAll("'", `'\\''`)}'`;
+}
+/** The --syntax override: one shell command for every text file, {file} replaced by its path. */
+function overrideChecker(template) {
+    return (file) => run(["sh", "-c", template.replaceAll("{file}", quote(file))], file, "the --syntax command");
+}
+async function mapLimit(items, limit, fn) {
+    const out = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        for (let i = next++; i < items.length; i = next++) {
+            const item = items[i];
+            if (item !== undefined)
+                out[i] = await fn(item);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    return out;
+}
+function byPath(a, b) {
+    return a.path < b.path ? -1 : a.path > b.path ? 1 : 0;
+}
+/**
+ * Checks every file each commit writes. The last commit equals the tip by construction, so a
+ * file that fails there is reported as the tip's own state and is not checked in earlier commits,
+ * where the same failure would be blamed on the split.
+ */
+export async function checkSyntax(plan, opts) {
+    const last = plan.commits.length - 1;
+    const jobs = plan.commits.flatMap((c) => c.changes.flatMap((ch) => ch.op === "write" ? [{ commit: c.index, path: ch.path, bytes: ch.bytes }] : []));
+    // node prints the resolved path, so the dir is resolved too for the message to find it.
+    const dir = await realpath(await mkdtemp(join(tmpdir(), "follow-me-syntax-")));
+    try {
+        const cache = new Map();
+        let serial = 0;
+        const outcomeOf = (job) => {
+            const ext = extname(job.path).toLowerCase();
+            const checker = opts.override === undefined ? CHECKERS.get(ext) : overrideChecker(opts.override);
+            if (checker === undefined) {
+                return Promise.resolve({
+                    kind: "skipped",
+                    reason: `no checker for ${ext === "" ? "files without an extension" : ext}`,
+                });
+            }
+            const key = `${ext}\0${job.bytes}`;
+            const known = cache.get(key);
+            if (known !== undefined)
+                return known;
+            const file = join(dir, `f${serial++}${ext}`);
+            const fresh = writeFile(file, Buffer.from(job.bytes, "latin1")).then(() => checker(file, job.bytes));
+            cache.set(key, fresh);
+            return fresh;
+        };
+        const tipJobs = jobs.filter((j) => j.commit === last);
+        const tipOutcomes = await mapLimit(tipJobs, LIMIT, outcomeOf);
+        const tip = [];
+        const broken = new Set();
+        tipJobs.forEach((job, i) => {
+            const outcome = tipOutcomes[i];
+            if (outcome?.kind !== "fails")
+                return;
+            tip.push({ commit: job.commit, path: job.path, message: outcome.message });
+            broken.add(job.path);
+        });
+        const rest = jobs.filter((j) => j.commit !== last && !broken.has(j.path));
+        const outcomes = await mapLimit(rest, LIMIT, outcomeOf);
+        const issues = [];
+        const skipped = new Map();
+        let checked = 0;
+        const all = [
+            ...tipJobs.map((j, i) => [j, tipOutcomes[i]]),
+            ...rest.map((j, i) => [j, outcomes[i]]),
+        ];
+        for (const [job, outcome] of all) {
+            if (outcome === undefined)
+                continue;
+            if (outcome.kind === "skipped")
+                skipped.set(job.path, outcome.reason);
+            else
+                checked++;
+            if (outcome.kind === "fails" && job.commit !== last) {
+                issues.push({ commit: job.commit, path: job.path, message: outcome.message });
+            }
+        }
+        issues.sort((a, b) => a.commit - b.commit || byPath(a, b));
+        return {
+            issues,
+            tip,
+            skipped: [...skipped].map(([path, reason]) => ({ path, reason })).sort(byPath),
+            checked,
+        };
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+}

package/dist/src/types.js

@@ -8,7 +8,9 @@
  *               project every commit, prove the last one equals the tip. Pure.
  *   git.ts      the only module that spawns git: load a Diff, write a branch from a ValidPlan.
  *   session.ts  the .follow-me/<slug>/ layout: session anchor, plans, reviews, draft.
- *   prompt.ts   the planner prompt for an agent, and the Anthropic API planner.
+ *   comments.ts the wire formats of review state: comments, replies, concern decisions, the
+ *               review file, the autosaved draft and the server's events. Pure parsers.
+ *   prompt.ts   the planner prompt for an agent, the feedback and the consolidated report.
  *   server.ts   the review server: a registry of hosted sessions, their JSON API, and ui/.
  *   host.ts     the one server per user: its record in the state dir, attach, start, stop.
  *   cli.ts      argv -> one call into the modules above.