local-review 0.0.1 → 0.2.0

package/dist/server/projects.js

@@ -0,0 +1,319 @@
+// Projects: projects/<slug>/project.yaml lists repos (each a commit range), and splits each repo's commits
+// into consecutive, colour-coded PR stacks. Everything here is re-read on every request, so edits (by the reviewer or
+// an agent) show up without a restart.
+import fs from 'node:fs';
+import path from 'node:path';
+import YAML from 'yaml';
+import { PROJECTS_DIR, SAFE_NAME, expandHome, safeName } from './config.js';
+import { loadRepo, rangeEnd } from './commits.js';
+import { normalizeSubject } from './reviews.js';
+import { loadLanded } from './landed.js';
+import { loadPrs } from './prs.js';
+import { inspectOrphan, liveCommits } from './context.js';
+// the colours a regular stack can have (auto-assigned in this order, cycling). Yellow isn't one of them: it's
+// reserved for follow-on stacks, which are always yellow whatever their `color:` says.
+export const PALETTE = ['blue', 'green', 'purple', 'orange', 'pink', 'teal', 'red'];
+export const FOLLOW_ON_COLOR = 'yellow';
+export const UNSTACKED_COLOR = 'gray';
+const isHexColor = (s) => /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i.test(s);
+/** A project slug from the URL or the file system: must be a plain directory name. */
+export function projectDir(slug) {
+    if (!SAFE_NAME.test(slug))
+        throw new Error(`bad project name: ${slug}`);
+    return path.join(PROJECTS_DIR, slug);
+}
+export function listProjectSlugs() {
+    let entries;
+    try {
+        entries = fs.readdirSync(PROJECTS_DIR, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((e) => e.isDirectory() && SAFE_NAME.test(e.name) && fs.existsSync(path.join(PROJECTS_DIR, e.name, 'project.yaml')))
+        .map((e) => e.name)
+        .sort();
+}
+/** A YAML flag: true/false, or "yes"/"no" (and "true"/"false") as strings, any case. Anything else: undefined. */
+export function flag(v) {
+    if (typeof v === 'boolean')
+        return v;
+    if (typeof v !== 'string')
+        return undefined;
+    const t = v.trim().toLowerCase();
+    return t === 'yes' || t === 'true' ? true : t === 'no' || t === 'false' ? false : undefined;
+}
+const text = (v) => (v === null || v === undefined ? undefined : typeof v === 'object' ? undefined : String(v));
+/** Parse a project.yaml. Never throws: problems are reported as `error` (whole file) or repo `warnings`. */
+export function parseProject(slug, dir, raw) {
+    const file = path.join(dir, 'project.yaml');
+    const out = { slug, dir, file, title: slug, description: null, repos: [] };
+    let doc;
+    try {
+        doc = YAML.parse(raw) ?? {};
+    }
+    catch (e) {
+        out.error = `invalid YAML in ${file}: ${e.message}`;
+        return out;
+    }
+    if (typeof doc !== 'object' || Array.isArray(doc)) {
+        out.error = `${file}: the top level must be a mapping (title:, repos: …)`;
+        return out;
+    }
+    out.title = text(doc.title)?.trim() || slug;
+    out.description = text(doc.description) ?? null;
+    const list = Array.isArray(doc.repos) ? doc.repos : [];
+    if (doc.repos != null && !Array.isArray(doc.repos))
+        out.error = `${file}: \`repos\` must be a list`;
+    const used = new Set();
+    for (const [index, r] of list.entries()) {
+        if (!r || typeof r !== 'object' || typeof r.path !== 'string')
+            continue;
+        const repoPath = path.resolve(expandHome(r.path));
+        const wanted = safeName(text(r.name) ?? path.basename(repoPath), 'repo');
+        let name = wanted;
+        for (let n = 2; used.has(name); n++)
+            name = `${wanted}-${n}`;
+        used.add(name);
+        const warnings = [];
+        // the suffix depends on the order of `repos`, and the name is the reviews/ and prs/ directory: reordering
+        // or removing a repo would silently switch which comments a repo shows
+        if (name !== wanted)
+            warnings.push(`another repo is already named "${wanted}", so this one is "${name}" (its reviews/ and prs/ directories use that name; reordering the repos would change it). Give it a unique \`name\`.`);
+        const stacks = [];
+        if (r.stacks != null && !Array.isArray(r.stacks))
+            warnings.push('`stacks` must be a list; ignored');
+        for (const [i, s] of (Array.isArray(r.stacks) ? r.stacks : []).entries()) {
+            const spec = s && typeof s === 'object' ? s : { title: text(s) };
+            const title = text(spec.title)?.trim() || `Stack ${i + 1}`;
+            let followOn = false;
+            if (spec.follow_on != null) {
+                const f = flag(spec.follow_on);
+                if (f === undefined)
+                    warnings.push(`stack "${title}": follow_on must be true or false (or yes / no), not ${JSON.stringify(spec.follow_on)}; ignored`);
+                else
+                    followOn = f;
+            }
+            // a follow-on stack is always yellow (its `color:` is ignored); a regular one never is
+            let color = followOn ? FOLLOW_ON_COLOR : PALETTE[i % PALETTE.length];
+            const c = text(spec.color)?.trim();
+            if (c && !followOn) {
+                if (PALETTE.includes(c.toLowerCase()))
+                    color = c.toLowerCase();
+                else if (c.toLowerCase() === FOLLOW_ON_COLOR)
+                    warnings.push(`stack "${title}": yellow is reserved for follow-on stacks; using ${color} (pick another colour, or mark it follow_on: true)`);
+                else if (isHexColor(c))
+                    color = c;
+                else
+                    warnings.push(`stack "${title}": unknown colour '${c}' (use ${PALETTE.join(', ')} or #hex)`);
+            }
+            const startsAt = text(spec.starts_at)?.trim();
+            const description = text(spec.description)?.replace(/\r\n/g, '\n').trim();
+            stacks.push({ title, color, ...(startsAt ? { starts_at: startsAt } : {}), ...(description ? { description } : {}), ...(followOn ? { follow_on: true } : {}) });
+        }
+        let landed = [];
+        if (Array.isArray(r.landed))
+            landed = r.landed;
+        else if (r.landed != null)
+            warnings.push('`landed` must be a list of prs file keys (sha prefixes); ignored');
+        const ghStack = Number(text(r.github_stack)?.replace(/^#/, ''));
+        out.repos.push({
+            index,
+            name,
+            path: repoPath,
+            branch: text(r.branch),
+            to: text(r.to),
+            base: text(r.base),
+            from: text(r.from),
+            stacks,
+            warnings,
+            landed,
+            ...(Number.isSafeInteger(ghStack) && ghStack > 0 ? { github_stack: ghStack } : {}),
+        });
+    }
+    return out;
+}
+export function loadProjectConfig(slug) {
+    const dir = projectDir(slug);
+    let raw;
+    try {
+        raw = fs.readFileSync(path.join(dir, 'project.yaml'), 'utf8');
+    }
+    catch {
+        return null;
+    }
+    return parseProject(slug, dir, raw);
+}
+/**
+ * Split a repo's commits (oldest first) into consecutive stacks. Each declared stack starts at the commit its
+ * `starts_at` selects and runs up to the next stack's start. Commits before the first start form an implicit
+ * "Unstacked" group. A selector that matches nothing, or only commits at or before the previous stack's start
+ * (out of order), gives a warning and an empty stack; it never throws.
+ */
+export function partitionStacks(commits, specs, defaultTitle = 'Stack') {
+    const warnings = [];
+    let unmatched = false;
+    if (!specs.length) {
+        return { stacks: [{ index: 0, number: null, title: defaultTitle, color: PALETTE[0], implicit: 'branch', shas: commits.map((c) => c.sha) }], warnings };
+    }
+    // nothing to place (e.g. the branch has no commits yet): empty stacks, no warnings
+    const declared = (s, i, index, shas) => ({ index, number: i + 1, title: s.title, color: s.follow_on ? FOLLOW_ON_COLOR : s.color, shas, ...(s.description ? { description: s.description } : {}), ...(s.follow_on ? { follow_on: true } : {}) });
+    if (!commits.length)
+        return { stacks: specs.map((s, i) => declared(s, i, i, [])), warnings };
+    const subjects = commits.map((c) => normalizeSubject(c.subject));
+    // a PR's title (override) is tried after the subjects: a landed multi-commit PR has no meaningful single subject
+    const titles = commits.map((c) => (c.title ? normalizeSubject(c.title) : ''));
+    const starts = [];
+    const specWarnings = [];
+    let last = -1;
+    for (const [i, spec] of specs.entries()) {
+        const label = `stack ${i + 1} "${spec.title}"`;
+        let cands;
+        const sel = spec.starts_at;
+        if (sel === undefined) {
+            if (i === 0)
+                cands = [0];
+            else {
+                specWarnings.push(`${label} has no starts_at, so it is empty`);
+                starts.push(null);
+                continue;
+            }
+        }
+        else {
+            cands = [];
+            if (/^[0-9a-f]{7,40}$/i.test(sel))
+                cands = commits.flatMap((c, j) => (c.sha.startsWith(sel.toLowerCase()) ? [j] : []));
+            if (!cands.length) {
+                const n = normalizeSubject(sel);
+                cands = subjects.flatMap((s, j) => (s === n ? [j] : []));
+                if (!cands.length)
+                    cands = titles.flatMap((t, j) => (t && t === n ? [j] : []));
+            }
+        }
+        if (!cands.length) {
+            unmatched = true;
+            specWarnings.push(`${label}: starts_at "${sel}" doesn't match any commit (sha prefix, subject or PR title), so it is empty`);
+            starts.push(null);
+            continue;
+        }
+        const pick = cands.find((j) => j > last);
+        if (pick === undefined) {
+            specWarnings.push(`${label}: starts_at "${sel}" is at or before the previous stack's start (out of order), so it is empty`);
+            starts.push(null);
+            continue;
+        }
+        starts.push(pick);
+        specWarnings.push(undefined);
+        last = pick;
+    }
+    // follow-on stacks are parked at the end: a regular stack after one would be stacked on held-back work
+    const firstFollowOn = specs.findIndex((s) => s.follow_on);
+    if (firstFollowOn >= 0)
+        for (const [i, spec] of specs.entries()) {
+            if (i <= firstFollowOn || spec.follow_on)
+                continue;
+            const w = `stack ${i + 1} "${spec.title}" comes after follow-on stack ${firstFollowOn + 1} "${specs[firstFollowOn].title}" but isn't a follow-on itself: its PRs would be stacked on held-back work (move follow-on stacks to the end, or mark this one follow_on: true)`;
+            specWarnings[i] = specWarnings[i] ? `${specWarnings[i]}\n${w}` : w;
+        }
+    const valid = starts.map((s, i) => ({ s, i })).filter((x) => x.s !== null);
+    const groups = [];
+    const firstStart = valid.length ? valid[0].s : commits.length;
+    if (firstStart > 0) {
+        groups.push({ index: 0, number: null, title: 'Unstacked', color: UNSTACKED_COLOR, implicit: 'unstacked', shas: commits.slice(0, firstStart).map((c) => c.sha) });
+    }
+    for (const [i, spec] of specs.entries()) {
+        const s = starts[i];
+        let shas = [];
+        if (s !== null) {
+            const k = valid.findIndex((v) => v.i === i);
+            const end = valid[k + 1]?.s ?? commits.length;
+            shas = commits.slice(s, end).map((c) => c.sha);
+        }
+        const g = declared(spec, i, groups.length, shas);
+        if (specWarnings[i]) {
+            g.warning = specWarnings[i];
+            warnings.push(...specWarnings[i].split('\n'));
+        }
+        groups.push(g);
+    }
+    return { stacks: groups, warnings, ...(unmatched ? { unmatched } : {}) };
+}
+export function repoDirs(project, repo) {
+    if (!SAFE_NAME.test(repo))
+        throw new Error(`bad repo name: ${repo}`);
+    return { reviewsDir: path.join(project.dir, 'reviews', repo), prsDir: path.join(project.dir, 'prs', repo) };
+}
+export async function loadProject(slug) {
+    const cfg = loadProjectConfig(slug);
+    if (!cfg)
+        return null;
+    const repos = await Promise.all(cfg.repos.map(async (rc) => {
+        const dirs = repoDirs(cfg, rc.name);
+        // with landed PRs, a missing / deleted branch or an empty live range is fine: they still show
+        const info = await loadRepo(rc, { optional: rc.landed.length > 0 });
+        const extra = info.warning ? [info.warning] : [];
+        let titles = new Map();
+        if (rc.landed.length && !info.error) {
+            const landed = await loadLanded(rc.path, dirs.prsDir, rc.landed);
+            extra.push(...landed.warnings);
+            titles = landed.titles;
+            // a frozen PR whose commit is still in the live range (frozen before the rebase) is shown once, as landed
+            const keys = new Set(landed.commits.map((c) => c.sha));
+            info.commits = [...landed.commits, ...info.commits.filter((c) => !keys.has(c.sha))];
+        }
+        const defaultTitle = rc.branch || rangeEnd(rc) || rc.name;
+        let part = partitionStacks(info.commits.map((c) => ({ sha: c.sha, subject: c.subject, title: titles.get(c.sha) })), rc.stacks, defaultTitle);
+        // a selector that's no sha or subject may be a live PR's title: only then read the prs files for titles
+        if (part.unmatched && info.commits.some((c) => !c.landed)) {
+            const prs = await loadPrs(dirs.prsDir, liveCommits(rc, info), inspectOrphan(rc, info)).catch(() => new Map());
+            part = partitionStacks(info.commits.map((c) => ({ sha: c.sha, subject: c.subject, title: titles.get(c.sha) ?? prs.get(c.sha)?.override.title })), rc.stacks, defaultTitle);
+        }
+        const { stacks, warnings } = part;
+        const stackOf = new Map();
+        for (const g of stacks)
+            for (const sha of g.shas)
+                stackOf.set(sha, g.index);
+        return { cfg: rc, info, stacks, warnings: [...rc.warnings, ...extra, ...warnings], stackOf, ...dirs };
+    }));
+    return { cfg, repos };
+}
+/**
+ * Archived: everything in the project has landed. Some repo has landed PRs, and no repo has a live (unmerged) commit
+ * or an error. The project switcher lists these in a separate, collapsed section.
+ */
+export function isArchived(p) {
+    if (p.cfg.error || !p.repos.length)
+        return false;
+    return p.repos.some((r) => r.info.commits.some((c) => c.landed)) && p.repos.every((r) => !r.info.error && r.info.commits.every((c) => c.landed));
+}
+/** Newest mtime of anything in the project directory (project.yaml, prs/, reviews/), for "most recent". */
+export function projectModified(dir) {
+    let max = 0;
+    const walk = (d, depth) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(d, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const p = path.join(d, e.name);
+            if (e.isDirectory()) {
+                if (depth < 3)
+                    walk(p, depth + 1);
+            }
+            else {
+                try {
+                    max = Math.max(max, fs.statSync(p).mtimeMs);
+                }
+                catch {
+                    /* gone */
+                }
+            }
+        }
+    };
+    walk(dir, 0);
+    return max;
+}

package/dist/server/prs.js

@@ -0,0 +1,314 @@
+// PR title/description overrides: projects/<project>/prs/<repo>/<full-sha>.yaml
+// A commit's PR title and description default to its subject and body. Changing them must never touch the
+// reviewed repo, so overrides live here. Like review files they follow rebases (patch-id, Change-Id, subject;
+// only from files whose commit has left the range), tolerate hand edits, and are written atomically.
+import fs from 'node:fs';
+import YAML from 'yaml';
+import { atomicWrite, renameToBak } from './safefs.js';
+import { normBody, normTitle } from '../shared/prText.js';
+import { storedStatus } from '../shared/readiness.js';
+import { ReviewConflictError, matchOrphans, readRaw, reviewPath, str, withLock } from './reviews.js';
+export const prPath = reviewPath; // same `<dir>/<40-hex>.yaml` rule
+function parse(raw) {
+    let doc;
+    try {
+        doc = YAML.parse(raw);
+    }
+    catch (e) {
+        return { doc: null, error: e.message };
+    }
+    if (doc === null || doc === undefined)
+        return { doc: {} };
+    if (typeof doc !== 'object' || Array.isArray(doc))
+        return { doc: null, error: 'the top level must be a mapping (title:, body: …)' };
+    return { doc };
+}
+/** What the file overrides. A blank title doesn't count; `description:` is accepted as an alias of `body:`. */
+export function overrideOf(doc) {
+    if (!doc)
+        return {};
+    const o = {};
+    const title = normTitle(str(doc.title) ?? '');
+    if (title)
+        o.title = title;
+    const body = str(doc.body) ?? str(doc.description);
+    if (body !== undefined)
+        o.body = normBody(body);
+    const branch = branchName(doc.branch);
+    if (branch)
+        o.branch = branch;
+    const gh = githubOf(doc.github);
+    if (gh)
+        o.github = gh;
+    const status = storedStatus(doc.status);
+    if (status)
+        o.status = status;
+    const landed = landedOf(doc.landed);
+    if (landed)
+        o.landed = landed;
+    return o;
+}
+const SHA = /^[0-9a-f]{40}$/;
+const METHODS = ['merge', 'squash', 'rebase'];
+/**
+ * The `landed:` block, tolerantly: `{head, base, commit, method, at}`, shas as full 40-hex (any case; anything else is
+ * ignored), `method` merge / squash / rebase (any case). Usable once it has a `head` or a `commit`; otherwise null.
+ */
+export function landedOf(v) {
+    if (!v || typeof v !== 'object' || Array.isArray(v))
+        return null;
+    const o = v;
+    const sha = (x) => {
+        const s = str(x)?.trim().toLowerCase();
+        return s && SHA.test(s) ? s : undefined;
+    };
+    const l = {};
+    const head = sha(o.head);
+    if (head)
+        l.head = head;
+    const base = sha(o.base);
+    if (base)
+        l.base = base;
+    const commit = sha(o.commit) ?? sha(o.merge_commit);
+    if (commit)
+        l.commit = commit;
+    const m = str(o.method)?.trim().toLowerCase();
+    if (m && METHODS.includes(m))
+        l.method = m;
+    const at = str(o.at)?.trim();
+    if (at)
+        l.at = at;
+    return l.head || l.commit ? l : null;
+}
+/** A hand-written branch name: trimmed, `refs/heads/` dropped. Blank or not a string: none. */
+export function branchName(v) {
+    const s = typeof v === 'string' ? v.trim().replace(/^refs\/heads\//, '') : undefined;
+    return s || undefined;
+}
+const PR_URL = /^https?:\/\/\S+\/pull\/(\d+)\/?(?:[#?]\S*)?$/;
+function prNumber(v) {
+    const s = str(v)?.trim().replace(/^#/, '');
+    if (!s || !/^\d{1,9}$/.test(s))
+        return undefined;
+    const n = Number(s);
+    return n > 0 ? n : undefined;
+}
+/**
+ * The `github:` field, tolerantly: `{number, url, branch?, base?, created?}` with the number as a number or a
+ * string (`"123"`, `"#123"`), or derived from a `.../pull/123` url; or just a number or a PR url on its own.
+ * Anything without a usable PR number is ignored (null).
+ */
+export function githubOf(v) {
+    if (v === null || v === undefined)
+        return null;
+    if (typeof v !== 'object' || Array.isArray(v)) {
+        const s = str(v)?.trim() ?? '';
+        const m = PR_URL.exec(s);
+        if (m)
+            return { number: Number(m[1]), url: s };
+        const n = prNumber(s);
+        return n ? { number: n, url: '' } : null;
+    }
+    const o = v;
+    const url = str(o.url)?.trim() ?? '';
+    const number = prNumber(o.number) ?? (PR_URL.exec(url) ? Number(PR_URL.exec(url)[1]) : undefined);
+    if (!number)
+        return null;
+    const gh = { number, url };
+    const branch = branchName(o.branch);
+    if (branch)
+        gh.branch = branch;
+    const base = branchName(o.base);
+    if (base)
+        gh.base = base;
+    const created = str(o.created)?.trim();
+    if (created)
+        gh.created = created;
+    const stack = prNumber(o.stack);
+    if (stack)
+        gh.stack = stack;
+    const stackedOn = branchName(o.stacked_on);
+    if (stackedOn)
+        gh.stacked_on = stackedOn;
+    return gh;
+}
+export function readPrFile(file) {
+    const raw = fs.readFileSync(file, 'utf8');
+    const { doc, error } = parse(raw);
+    return { override: overrideOf(doc), doc, file, raw, ...(error ? { parseError: error } : {}) };
+}
+const none = () => ({ override: {}, doc: null, file: null, raw: null });
+export async function loadPr(ctx) {
+    const file = prPath(ctx.dir, ctx.sha);
+    if (fs.existsSync(file))
+        return readPrFile(file);
+    const live = ctx.liveCommits ?? [{ sha: ctx.sha, subject: ctx.subject, changeId: ctx.changeId, getPatchId: ctx.getPatchId }];
+    const m = (await matchOrphans(ctx.dir, live, { inspect: ctx.inspectOrphan })).get(ctx.sha);
+    if (m) {
+        const l = readPrFile(m.orphan.file);
+        if (!l.parseError)
+            return { ...l, matchedFrom: m.orphan.sha, matchedBy: m.by };
+    }
+    return none();
+}
+/** Overrides for every commit of a repo at once (one directory scan), for the sidebar. */
+export async function loadPrs(dir, live, inspect) {
+    const out = new Map();
+    if (!fs.existsSync(dir))
+        return out;
+    const matched = await matchOrphans(dir, live, { inspect });
+    for (const c of live) {
+        const file = prPath(dir, c.sha);
+        try {
+            if (fs.existsSync(file))
+                out.set(c.sha, readPrFile(file));
+            else {
+                const m = matched.get(c.sha);
+                if (m) {
+                    const l = readPrFile(m.orphan.file);
+                    if (!l.parseError)
+                        out.set(c.sha, { ...l, matchedFrom: m.orphan.sha, matchedBy: m.by });
+                }
+            }
+        }
+        catch {
+            /* unreadable: no override */
+        }
+    }
+    return out;
+}
+function toYaml(doc) {
+    const { commit, patch_id, change_id, subject, previous_commits, matched_by, title, body, status, branch, github, landed, updated, ...rest } = doc;
+    const o = { commit, patch_id: patch_id ?? null };
+    if (change_id)
+        o.change_id = change_id;
+    o.subject = subject;
+    if (Array.isArray(previous_commits) && previous_commits.length)
+        o.previous_commits = previous_commits;
+    if (matched_by)
+        o.matched_by = matched_by;
+    if (title !== undefined)
+        o.title = title;
+    if (body !== undefined)
+        o.body = body;
+    if (status !== undefined)
+        o.status = status;
+    if (branch !== undefined)
+        o.branch = branch;
+    if (github !== undefined)
+        o.github = github;
+    if (landed !== undefined)
+        o.landed = landed;
+    if (updated !== undefined)
+        o.updated = updated;
+    Object.assign(o, rest);
+    const d = new YAML.Document(o);
+    YAML.visit(d, {
+        Pair(_, pair) {
+            if (YAML.isScalar(pair.key) && pair.key.value === 'body' && YAML.isScalar(pair.value) && typeof pair.value.value === 'string')
+                pair.value.type = 'BLOCK_LITERAL';
+        },
+    });
+    return d.toString({ lineWidth: 0, blockQuote: 'literal' });
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const MAX_ATTEMPTS = 6;
+export function writePr(ctx, change, now = new Date()) {
+    const target = prPath(ctx.dir, ctx.sha);
+    return withLock(target, async () => {
+        for (let attempt = 1;; attempt++) {
+            const loaded = await loadPr(ctx);
+            if (loaded.parseError) {
+                if (attempt < MAX_ATTEMPTS) {
+                    await sleep(40 * attempt);
+                    continue;
+                }
+                throw new ReviewConflictError(`refusing to overwrite ${loaded.file}: it is not valid YAML (${loaded.parseError}). Fix the file by hand.`);
+            }
+            const doc = { ...(loaded.doc ?? {}) };
+            if (change.title !== undefined) {
+                if (change.title === null || !change.title.trim())
+                    delete doc.title;
+                else
+                    doc.title = change.title.replace(/\s+/g, ' ').trim();
+            }
+            if (change.body !== undefined) {
+                delete doc.description; // the alias, if an agent used it
+                if (change.body === null)
+                    delete doc.body;
+                else
+                    doc.body = change.body.replace(/\r\n/g, '\n').trimEnd() + '\n';
+            }
+            if (change.branch !== undefined) {
+                const b = change.branch === null ? undefined : branchName(change.branch);
+                if (b)
+                    doc.branch = b;
+                else
+                    delete doc.branch;
+            }
+            if (change.github !== undefined) {
+                if (change.github === null)
+                    delete doc.github;
+                else {
+                    const { number, url, branch, base, created, stack, stacked_on } = change.github;
+                    doc.github = { number, url, ...(branch ? { branch } : {}), ...(base ? { base } : {}), ...(created ? { created } : {}), ...(stack ? { stack } : {}), ...(stacked_on ? { stacked_on } : {}) };
+                }
+            }
+            if (change.status !== undefined) {
+                if (change.status === 'ready')
+                    doc.status = 'ready';
+                else
+                    delete doc.status;
+            }
+            doc.commit = ctx.sha;
+            doc.patch_id = (!loaded.matchedFrom && str(doc.patch_id)) || (await ctx.getPatchId());
+            if (ctx.changeId)
+                doc.change_id = ctx.changeId;
+            doc.subject = ctx.subject;
+            if (loaded.matchedFrom) {
+                const prev = Array.isArray(doc.previous_commits) ? doc.previous_commits.map(str).filter(Boolean) : [];
+                doc.previous_commits = [...new Set([...prev, loaded.matchedFrom])];
+                doc.matched_by = loaded.matchedBy;
+            }
+            doc.updated = now.toISOString().replace(/\.\d{3}Z$/, 'Z');
+            const text = toYaml(doc);
+            const changed = readRaw(loaded.file) !== loaded.raw || (loaded.file !== target && fs.existsSync(target));
+            if (changed) {
+                if (attempt < MAX_ATTEMPTS)
+                    continue;
+                throw new ReviewConflictError(`${loaded.file ?? target} keeps changing on disk; not saving over it. Try again.`);
+            }
+            atomicWrite(target, text);
+            if (loaded.matchedFrom && loaded.file && loaded.file !== target) {
+                try {
+                    renameToBak(loaded.file, `superseded-by-${ctx.sha.slice(0, 8)}`); // never over an existing file
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            return readPrFile(target);
+        }
+    });
+}
+/**
+ * Whether the override's title / body actually changes the commit's. One that says the same as the commit (after the
+ * normalising every stored title / body gets) isn't an edit: the UI's own save drops it, and a hand-written copy of
+ * the commit message reads as unedited too. The file is left alone.
+ */
+export const titleEdited = (o, subject) => o?.title !== undefined && o.title !== normTitle(subject);
+export const bodyEdited = (o, body) => o?.body !== undefined && o.body !== normBody(body ?? '');
+/** The PR as shown: the override where it changes something, else the commit message. */
+export function prView(l, commit) {
+    const o = l?.override;
+    const t = titleEdited(o, commit.subject);
+    const b = bodyEdited(o, commit.body);
+    return {
+        title: t ? o.title : commit.subject,
+        body: b ? o.body : (commit.body ?? ''),
+        title_source: (t ? 'override' : 'commit'),
+        body_source: (b ? 'override' : 'commit'),
+        commit_subject: commit.subject,
+        commit_body: commit.body ?? '',
+    };
+}

package/dist/server/reviewer.js

@@ -0,0 +1,33 @@
+import { execFileSync } from 'node:child_process';
+import os from 'node:os';
+export function reviewerId(name) {
+    const first = name.trim().split(/\s+/)[0] ?? '';
+    const id = first.toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 32);
+    // `claude` is the agent's id: a reviewer can't take it
+    return id && id !== 'claude' ? id : 'reviewer';
+}
+export function resolveReviewer(sources) {
+    const name = [sources.env, sources.gitName, sources.user].map((s) => s?.trim()).find((s) => s) || 'reviewer';
+    return { id: reviewerId(name), name };
+}
+function gitUserName() {
+    try {
+        return execFileSync('git', ['config', '--get', 'user.name'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000 });
+    }
+    catch {
+        return undefined;
+    }
+}
+function osUser() {
+    try {
+        return process.env.USER || os.userInfo().username;
+    }
+    catch {
+        return undefined;
+    }
+}
+export const REVIEWER = resolveReviewer({
+    env: process.env.LOCAL_REVIEW_USER,
+    gitName: process.env.LOCAL_REVIEW_USER ? undefined : gitUserName(),
+    user: osUser(),
+});