review-workspace 1.10.2 → 1.12.0

package/README.md

@@ -30,7 +30,7 @@ To view an already-scaffolded bundle:
 npx review-workspace serve .bundles/<name> --port 4317
 ```
 
-Opens the UI at `http://127.0.0.1:4317` (prints a write token too — needed only to raise/answer Questions, not to view). One process, no separate dev server.
+Opens the UI at `http://127.0.0.1:4317` (prints a write token too — needed only to raise/answer Questions, not to view). The token is saved in the bundle as `.write-token` and stays the same after a restart. Use `serve --rotate-token` to make a new one. One process, no separate dev server.
 
 ## Addressing review feedback in the target repo
 

package/dist/bundle/annotation-fields.js

@@ -0,0 +1,18 @@
+const FIRST_VERSION_REQUIRING_NOTE_FIELDS = 2;
+const VERDICTS_NEEDING_SUGGESTION = ['wrong', 'missing'];
+export function checkAnnotationFields(document) {
+    if (document.schemaVersion < FIRST_VERSION_REQUIRING_NOTE_FIELDS)
+        return [];
+    const diagnostics = [];
+    for (const annotation of document.annotations ?? []) {
+        if (!annotation.verdict) {
+            diagnostics.push({ kind: 'missing-verdict', annotationId: annotation.id });
+            continue;
+        }
+        const needsSuggestion = VERDICTS_NEEDING_SUGGESTION.includes(annotation.verdict);
+        if (needsSuggestion && !annotation.suggestion?.trim()) {
+            diagnostics.push({ kind: 'missing-suggestion', annotationId: annotation.id, verdict: annotation.verdict });
+        }
+    }
+    return diagnostics;
+}

package/dist/bundle/carry-forward.js

@@ -1,8 +1,8 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { parsePatch } from "../patch/parse.js";
-import { carryForwardComment, readQuestions } from "../questions/questions-log.js";
-import { evaluateResolution } from "./resolution.js";
+import { carryForwardComment, isOpenChangeRequest, readQuestions } from "../questions/questions-log.js";
+import { evaluateResolution, isCodeComment } from "./resolution.js";
 import { incrementalTouchedPaths } from "./incremental-patch.js";
 export function createCaches() {
     return { chain: new Map(), patch: new Map(), reviewDocument: new Map() };
@@ -30,7 +30,7 @@ function readReviewDocument(bundlePath, caches) {
     return caches.reviewDocument.get(bundlePath);
 }
 function openChangeRequests(bundlePath) {
-    return readQuestions(bundlePath).filter((c) => c.kind === 'change-request' && c.status === 'open' && !c.resolved);
+    return readQuestions(bundlePath).filter(isOpenChangeRequest);
 }
 /**
  * Shared shape behind every chain-walking function below: a round-1 bundle (no
@@ -68,6 +68,7 @@ export function computeCarriedResolutions(bundlePath, caches = createCaches()) {
         const currentPatch = readPatch(bundlePath, caches);
         return readQuestions(bundlePath)
             .filter((c) => carriedIds.has(c.id))
+            .filter(isCodeComment)
             .map((comment) => ({ comment, resolution: evaluateResolution(comment, previousPatch, currentPatch) }));
     });
 }
@@ -99,6 +100,8 @@ export function listComments(bundlePath, caches = createCaches()) {
 }
 function targetKey(target) {
     switch (target.type) {
+        case 'general':
+            return 'general';
         case 'file':
             return `file:${target.path}`;
         case 'binary':
@@ -128,7 +131,7 @@ export function collectCarriedReviewContent(bundlePath, ownDocument, caches = cr
         const ownTargetKeys = new Set((ownDocument.annotations ?? []).map((a) => targetKey(a.target)));
         const ownGroupIds = new Set((ownDocument.behavioralGroups ?? []).map((g) => g.id));
         return {
-            annotations: previousAll.annotations.filter((a) => !touchedPaths.has(a.target.path) && !ownTargetKeys.has(targetKey(a.target))),
+            annotations: previousAll.annotations.filter((a) => a.target.type !== 'general' && !touchedPaths.has(a.target.path) && !ownTargetKeys.has(targetKey(a.target))),
             behavioralGroups: previousAll.behavioralGroups.filter((g) => !ownGroupIds.has(g.id) && !(g.targets ?? []).some((t) => touchedPaths.has(t.path))),
         };
     });

package/dist/bundle/format-diagnostic.js

@@ -0,0 +1,33 @@
+function describeDiagnostic(d) {
+    switch (d.kind) {
+        case 'stale-line-target':
+            return `Stale annotation: ${d.detail}`;
+        case 'invalid-field':
+            return `Invalid field (${d.instancePath}): ${d.message}`;
+        case 'unresolved-target':
+            return `Unresolved ${d.targetType} target: ${d.detail}`;
+        case 'missing-asset':
+            return `Missing asset: ${d.assetPath}`;
+        case 'unsafe-asset-path':
+            return `Unsafe asset path: ${d.assetPath}`;
+        case 'disallowed-asset-type':
+            return `Disallowed asset type: ${d.assetPath}`;
+        case 'asset-too-large':
+            return `Asset too large (${d.bytes} bytes): ${d.assetPath}`;
+        case 'image-without-comparison':
+            return `Changed image has no base and head asset: ${d.path}`;
+        case 'dangling-answer':
+            return `Answer ${d.answerId} references unknown Question ${d.questionId}`;
+        case 'unanchored-verification-gap':
+            return `Verification gap ${d.verificationId} has no concrete anchor: ${d.detail}`;
+        case 'missing-verdict':
+            return `Note ${d.annotationId} has no verdict. Set it to intended, missing, wrong, extra or unclear.`;
+        case 'missing-suggestion':
+            return `Note ${d.annotationId} has the verdict ${d.verdict} but no suggestion. Say what to change.`;
+        case 'invalid-proof-link':
+            return `Proof link in evidence ${d.evidenceId} is broken: ${d.detail}`;
+    }
+}
+export function formatDiagnostic(d) {
+    return `${d.kind}: ${describeDiagnostic(d)}`;
+}

package/dist/bundle/live-head.js

@@ -0,0 +1,34 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const LIVE_HEAD_FILE = 'live-head.json';
+function parseLiveHead(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return `${LIVE_HEAD_FILE} must be a JSON object`;
+    const { head, checkedAt } = value;
+    if (typeof head !== 'string' || head === '')
+        return 'head must be a non-empty string';
+    if (typeof checkedAt !== 'string' || Number.isNaN(Date.parse(checkedAt)))
+        return 'checkedAt must be an ISO date string';
+    return { head, checkedAt };
+}
+export function readLiveHead(bundlePath) {
+    const path = join(bundlePath, LIVE_HEAD_FILE);
+    if (!existsSync(path))
+        return { status: 'absent' };
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch (err) {
+        return { status: 'invalid', message: `${LIVE_HEAD_FILE} is not valid JSON: ${err.message}` };
+    }
+    const parsed = parseLiveHead(raw);
+    return typeof parsed === 'string' ? { status: 'invalid', message: parsed } : { status: 'ok', liveHead: parsed };
+}
+export function bundleStaleness(comparisonHead, liveHead, round) {
+    return { stale: liveHead !== undefined && liveHead.head !== comparisonHead, round };
+}
+export function buildLiveHeadStatus(read, comparisonHead, round) {
+    const liveHead = read.status === 'ok' ? read.liveHead : undefined;
+    return { ...read, recordedHead: comparisonHead, ...bundleStaleness(comparisonHead, liveHead, round) };
+}

package/dist/bundle/proof-links.js

@@ -0,0 +1,71 @@
+import { ALLOWED_ASSET_EXTENSIONS } from "../security/asset-path.js";
+function isImagePath(id) {
+    const lowerId = id.toLowerCase();
+    return ALLOWED_ASSET_EXTENSIONS.some((ext) => lowerId.endsWith(ext));
+}
+function hunkIndexOf(target, patch) {
+    if (target.type === 'hunk')
+        return target.hunkIndex;
+    if (target.type !== 'line')
+        return undefined;
+    const file = patch.files.find((f) => f.path === target.path);
+    const index = file?.hunks.findIndex((h) => h.lines.some((l) => (target.side === 'base' ? l.oldLine === target.line : l.newLine === target.line)));
+    return index === undefined || index < 0 ? undefined : index;
+}
+function codeRefFromAnnotation(annotation, patch) {
+    const { target } = annotation;
+    if (target.type === 'general' || target.type === 'binary')
+        return undefined;
+    const hunkIndex = hunkIndexOf(target, patch);
+    return { path: target.path, ...(hunkIndex === undefined ? {} : { hunkIndex }), annotationId: annotation.id };
+}
+function codeRefFromId(id, annotationsById, patch) {
+    const annotation = annotationsById.get(id);
+    if (annotation)
+        return codeRefFromAnnotation(annotation, patch);
+    const file = patch.files.find((f) => f.path === id);
+    return file && !file.binary ? { path: id } : undefined;
+}
+function isIdOfImageSide(id, annotationsById) {
+    const annotation = annotationsById.get(id);
+    return annotation?.target.type === 'binary';
+}
+function findLinksForEvidence(evidence, annotationsById, patch) {
+    const ids = evidence.targetIds ?? [];
+    const imageIds = ids.filter(isImagePath);
+    const otherIds = ids.filter((id) => !isImagePath(id) && !isIdOfImageSide(id, annotationsById));
+    if (imageIds.length === 0 || otherIds.length === 0)
+        return { links: [], diagnostics: [] };
+    if (!evidence.assetPath) {
+        const detail = 'the evidence has no assetPath, so there is no image to show';
+        return { links: [], diagnostics: [{ kind: 'invalid-proof-link', evidenceId: evidence.id, detail }] };
+    }
+    const diagnostics = [];
+    const changedImagePaths = new Set(patch.files.filter((f) => f.binary).map((f) => f.path));
+    const images = imageIds.filter((imagePath) => {
+        const exists = changedImagePaths.has(imagePath);
+        if (!exists) {
+            diagnostics.push({ kind: 'invalid-proof-link', evidenceId: evidence.id, detail: `image ${imagePath} is not a changed image in the patch` });
+        }
+        return exists;
+    });
+    const codeRefs = otherIds.flatMap((id) => codeRefFromId(id, annotationsById, patch) ?? []);
+    if (codeRefs.length === 0) {
+        const named = otherIds.join(', ');
+        diagnostics.push({
+            kind: 'invalid-proof-link',
+            evidenceId: evidence.id,
+            detail: `no code Target found for ${named} (use an Annotation id or a changed file path)`,
+        });
+    }
+    const links = images.flatMap((imagePath) => codeRefs.map((code) => ({ evidenceId: evidence.id, imagePath, code })));
+    return { links, diagnostics };
+}
+export function findProofLinks(document, patch) {
+    const annotationsById = new Map((document.annotations ?? []).map((a) => [a.id, a]));
+    const results = (document.evidence ?? []).map((e) => findLinksForEvidence(e, annotationsById, patch));
+    return {
+        links: results.flatMap((r) => r.links),
+        diagnostics: results.flatMap((r) => r.diagnostics),
+    };
+}

package/dist/bundle/publish-with-handoff.js

@@ -24,8 +24,7 @@ export async function publishBundleAndExportHandoff(bundlePath, options) {
         round,
         comments: readQuestions(bundlePath),
         annotations: document.annotations ?? [],
-        ask: options.ask,
-        repoPathCachePath: options.repoPathCachePath,
+        repoPath: options.repoPath,
     });
     return { ...result, handoff };
 }

package/dist/bundle/publish.js

@@ -20,5 +20,5 @@ export function publishBundle(bundlePath, limits = DEFAULT_LIMITS) {
     const tmpPath = join(bundlePath, `.review.json.tmp-${process.pid}-${Date.now()}`);
     writeFileSync(tmpPath, readFileSync(nextPath, 'utf-8'));
     renameSync(tmpPath, reviewPath);
-    return { ok: true };
+    return { ok: true, diagnostics: result.diagnostics };
 }

package/dist/bundle/resolution.js

@@ -1,5 +1,9 @@
 import { resolveTarget } from "./resolve-diagnostics.js";
 import { incrementalHunks } from "./incremental-patch.js";
+/** A general Comment has no place in the patch, so it has no Resolution. */
+export function isCodeComment(comment) {
+    return comment.target?.type !== 'general';
+}
 function targetHunkIndex(target, patch) {
     const file = patch.files.find((f) => f.path === target.path);
     if (!file)

package/dist/bundle/resolve-diagnostics.js

@@ -1,8 +1,10 @@
 import { existsSync, statSync } from 'node:fs';
 import { validateReviewDocumentSchema } from "../schema/validate.js";
-import { resolveAssetPath } from "../security/asset-path.js";
+import { ALLOWED_ASSET_EXTENSIONS, resolveAssetPath } from "../security/asset-path.js";
 import { DEFAULT_LIMITS } from "../security/limits.js";
 import { readQuestions } from "../questions/questions-log.js";
+import { checkAnnotationFields } from "./annotation-fields.js";
+import { findProofLinks } from "./proof-links.js";
 function findFile(patch, path) {
     return patch.files.find((f) => f.path === path);
 }
@@ -24,6 +26,8 @@ function checkAssetPath(bundlePath, assetPath, limits) {
 }
 /** Resolves a Target against a patch, returning the Diagnostic that explains why it's unresolved/stale, or undefined when it resolves cleanly. */
 export function resolveTarget(target, patch) {
+    if (target.type === 'general')
+        return undefined;
     const file = findFile(patch, target.path);
     if (target.type === 'file') {
         if (!file)
@@ -81,6 +85,34 @@ function isConcreteAnchor(id, annotationIds, evidenceById, filePaths) {
         return false;
     return (evidence.targetIds ?? []).some((innerId) => annotationIds.has(innerId) || filePaths.has(innerId));
 }
+function intentVisualAssetPaths(document) {
+    return (document.intent?.visuals ?? []).flatMap((v) => (v.baseAssetPath ? [v.assetPath, v.baseAssetPath] : [v.assetPath]));
+}
+function isImagePath(path) {
+    const lowerPath = path.toLowerCase();
+    return ALLOWED_ASSET_EXTENSIONS.some((ext) => lowerPath.endsWith(ext));
+}
+function changedImagePaths(document, patch) {
+    const targets = [
+        ...(document.behavioralGroups ?? []).flatMap((g) => g.targets ?? []),
+        ...(document.annotations ?? []).map((a) => a.target),
+    ];
+    const paths = [
+        ...patch.files.filter((f) => f.binary).map((f) => f.path),
+        ...targets.flatMap((t) => (t.type === 'binary' ? [t.path] : [])),
+    ];
+    const addedPaths = new Set(patch.files.filter((f) => f.added).map((f) => f.path));
+    return [...new Set(paths.filter(isImagePath))].filter((path) => !addedPaths.has(path));
+}
+function findImagesWithoutComparison(document, patch) {
+    const pairedEvidence = (document.evidence ?? []).filter((e) => e.assetPath && e.baseAssetPath);
+    return changedImagePaths(document, patch)
+        .filter((path) => {
+        const annotationIds = (document.annotations ?? []).filter((a) => a.target.type !== 'general' && a.target.path === path).map((a) => a.id);
+        return !pairedEvidence.some((e) => (e.targetIds ?? []).some((id) => id === path || annotationIds.includes(id)));
+    })
+        .map((path) => ({ kind: 'image-without-comparison', path }));
+}
 export function collectDiagnostics(document, patch, bundlePath, limits = DEFAULT_LIMITS) {
     const diagnostics = [];
     const schemaResult = validateReviewDocumentSchema(document);
@@ -115,6 +147,14 @@ export function collectDiagnostics(document, patch, bundlePath, limits = DEFAULT
                 diagnostics.push(diagnostic);
         }
     }
+    for (const assetPath of intentVisualAssetPaths(document)) {
+        const diagnostic = checkAssetPath(bundlePath, assetPath, limits);
+        if (diagnostic)
+            diagnostics.push(diagnostic);
+    }
+    diagnostics.push(...checkAnnotationFields(document));
+    diagnostics.push(...findProofLinks(document, patch).diagnostics);
+    diagnostics.push(...findImagesWithoutComparison(document, patch));
     if (document.answers?.length) {
         const questionIds = new Set(readQuestions(bundlePath).map((q) => q.id));
         for (const answer of document.answers) {

package/dist/bundle/round.js

@@ -1,8 +1,9 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, relative, resolve } from 'node:path';
+import { carryForwardChain } from "./carry-forward.js";
 /**
  * A stable cross-round identity for one MR: repo slug + number, e.g.
- * "founda/application/xds-viewer-ui!367".
+ * "group/project!367".
  */
 export function mrKeyFor(comparison) {
     if (!comparison.repository || !comparison.number) {
@@ -47,7 +48,8 @@ export function checkRound(bundlePath, liveHead) {
  * Scaffolds a new sibling round bundle for an MR whose live head has moved
  * past what `bundlePath` recorded. Never mutates `bundlePath` (ADR 0002) —
  * only creates the new `<name>-r{N}` directory alongside it, with its own
- * Comparison, Unified Patch, and a `chain.json` linking it back.
+ * Comparison, Unified Patch, a `chain.json` linking it back, and a
+ * `questions.jsonl` holding the previous round's open change-requests.
  */
 export function scaffoldNextRound(bundlePath, liveHead, options) {
     const document = readReviewDocument(bundlePath);
@@ -73,5 +75,6 @@ export function scaffoldNextRound(bundlePath, liveHead, options) {
         comparison: { ...document.comparison, head: liveHead },
     }, null, 2));
     writeFileSync(join(newBundlePath, 'chain.json'), JSON.stringify(chain, null, 2));
+    carryForwardChain(newBundlePath);
     return { bundlePath: newBundlePath, chain };
 }

package/dist/bundle/validate-bundle.js

@@ -4,7 +4,7 @@ import { parsePatch } from "../patch/parse.js";
 import { PatchParseError } from "../patch/types.js";
 import { collectDiagnostics } from "./resolve-diagnostics.js";
 import { DEFAULT_LIMITS } from "../security/limits.js";
-export const SUPPORTED_SCHEMA_VERSIONS = [1];
+export const SUPPORTED_SCHEMA_VERSIONS = [1, 2];
 function hasComparisonIdentity(document) {
     if (typeof document !== 'object' || document === null)
         return false;

package/dist/bundle/watcher.js

@@ -0,0 +1,38 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const WATCHER_FILE = 'watcher.json';
+function isCount(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 0;
+}
+function parseWatcher(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return `${WATCHER_FILE} must be a JSON object`;
+    const { enabled, cap, used, current = null, updatedAt } = value;
+    if (typeof enabled !== 'boolean')
+        return 'enabled must be true or false';
+    if (!isCount(cap))
+        return 'cap must be a whole number of 0 or more';
+    if (!isCount(used))
+        return 'used must be a whole number of 0 or more';
+    if (current !== null && typeof current !== 'string')
+        return 'current must be a Question id or null';
+    if (updatedAt === undefined)
+        return { enabled, cap, used, current };
+    if (typeof updatedAt !== 'string' || Number.isNaN(Date.parse(updatedAt)))
+        return 'updatedAt must be an ISO date-time string';
+    return { enabled, cap, used, current, updatedAt };
+}
+export function readWatcher(bundlePath) {
+    const path = join(bundlePath, WATCHER_FILE);
+    if (!existsSync(path))
+        return { status: 'absent' };
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch (err) {
+        return { status: 'invalid', message: `${WATCHER_FILE} is not valid JSON: ${err.message}` };
+    }
+    const parsed = parseWatcher(raw);
+    return typeof parsed === 'string' ? { status: 'invalid', message: parsed } : { status: 'ok', watcher: parsed };
+}

package/dist/cli.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import { readFileSync } from 'node:fs';
+import { formatDiagnostic } from "./bundle/format-diagnostic.js";
 import { validateBundle } from "./bundle/validate-bundle.js";
 import { publishBundleAndExportHandoff } from "./bundle/publish-with-handoff.js";
 import { checkRound, scaffoldNextRound } from "./bundle/round.js";
-import { askForRepoPathOnStdin } from "./handoff/ask-repo-path.js";
 import { carryForwardChain } from "./bundle/carry-forward.js";
 import { startReviewServer } from "./server/create-server.js";
 const [, , command, bundlePath, ...rest] = process.argv;
@@ -16,7 +16,7 @@ function flagValue(name) {
     return index === -1 ? undefined : rest[index + 1];
 }
 if (!command || !bundlePath) {
-    fail('Usage: review-workspace <open|publish|serve|round> <bundlePath> [--port N] [--live-head SHA --patch FILE]');
+    fail('Usage: review-workspace <open|publish|serve|round> <bundlePath> [--port N] [--rotate-token] [--repo PATH] [--live-head SHA --patch FILE]');
 }
 if (command === 'open') {
     carryForwardChain(bundlePath);
@@ -27,17 +27,29 @@ if (command === 'open') {
     console.log('Bundle is valid.');
     if (result.diagnostics?.length) {
         console.log(`${result.diagnostics.length} diagnostic(s) found.`);
+        for (const diagnostic of result.diagnostics) {
+            console.log(`  ${formatDiagnostic(diagnostic)}`);
+        }
     }
 }
 else if (command === 'publish') {
-    const result = await publishBundleAndExportHandoff(bundlePath, { ask: askForRepoPathOnStdin });
+    const result = await publishBundleAndExportHandoff(bundlePath, { repoPath: flagValue('--repo') });
     if (!result.ok) {
         fail(`Publish rejected: ${result.blockingReason} — ${result.message}`);
     }
     console.log('Published.');
+    for (const diagnostic of result.diagnostics ?? []) {
+        console.log(`  ${formatDiagnostic(diagnostic)}`);
+    }
     if (result.handoff?.written) {
         console.log(`Hand-off file written: ${result.handoff.filePath}`);
     }
+    else if (result.handoff?.skipped === 'no-repo-path') {
+        console.log('Hand-off skipped: pass --repo <path> to export the open change-requests.');
+    }
+    else if (result.handoff?.skipped === 'not-a-git-repo') {
+        console.log('Hand-off skipped: the --repo path is not a git repository.');
+    }
 }
 else if (command === 'round') {
     const liveHead = flagValue('--live-head');
@@ -57,7 +69,7 @@ else if (command === 'round') {
 }
 else if (command === 'serve') {
     const port = Number(flagValue('--port') ?? 4317);
-    const handle = await startReviewServer(bundlePath, { port });
+    const handle = await startReviewServer(bundlePath, { port, rotateToken: rest.includes('--rotate-token'), repoPath: flagValue('--repo') });
     console.log(JSON.stringify({ port: handle.port, writeToken: handle.writeToken, url: `http://127.0.0.1:${handle.port}` }));
 }
 else {

package/dist/handoff/build-handoff-markdown.js

@@ -1,10 +1,16 @@
 import { resolve } from 'node:path';
-const GENERAL_GROUP = '(general — no Target)';
-function targetPath(target) {
-    return target.path;
+import { isOpenChangeRequest } from "../questions/questions-log.js";
+const NO_TARGET_GROUP = '(general — no Target)';
+const GENERAL_TARGET_GROUP = 'General';
+function groupKey(target) {
+    if (!target)
+        return NO_TARGET_GROUP;
+    return target.type === 'general' ? GENERAL_TARGET_GROUP : target.path;
 }
 function targetKey(target) {
     switch (target.type) {
+        case 'general':
+            return 'general';
         case 'file':
             return `file:${target.path}`;
         case 'binary':
@@ -25,6 +31,8 @@ function targetsEqual(a, b) {
 }
 function describeTarget(target) {
     switch (target.type) {
+        case 'general':
+            return 'General';
         case 'file':
             return `File: ${target.path}`;
         case 'hunk':
@@ -36,25 +44,26 @@ function describeTarget(target) {
     }
 }
 function openChangeRequests(comments) {
-    return comments.filter((c) => c.kind === 'change-request' && c.status === 'open' && !c.resolved);
+    return comments.filter(isOpenChangeRequest);
 }
 function groupByFile(comments) {
     const byFile = new Map();
     for (const comment of comments) {
-        const key = comment.target ? targetPath(comment.target) : GENERAL_GROUP;
+        const key = groupKey(comment.target);
         const group = byFile.get(key) ?? [];
         group.push(comment);
         byFile.set(key, group);
     }
     return byFile;
 }
+function groupRank(key) {
+    if (key === NO_TARGET_GROUP)
+        return 2;
+    return key === GENERAL_TARGET_GROUP ? 1 : 0;
+}
 function orderedFileKeys(byFile) {
     return [...byFile.keys()].sort((a, b) => {
-        if (a === GENERAL_GROUP)
-            return 1;
-        if (b === GENERAL_GROUP)
-            return -1;
-        return a.localeCompare(b);
+        return groupRank(a) - groupRank(b) || a.localeCompare(b);
     });
 }
 function metadataBlock(input) {
@@ -95,7 +104,7 @@ export function buildHandoffMarkdown(input) {
             lines.push('');
             lines.push(comment.body);
             lines.push('');
-            const relatedAnnotations = comment.target
+            const relatedAnnotations = comment.target && comment.target.type !== 'general'
                 ? input.annotations.filter((a) => targetsEqual(a.target, comment.target))
                 : [];
             for (const annotation of relatedAnnotations) {

package/dist/handoff/ensure-git-exclude.js

@@ -0,0 +1,34 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+const ENTRY = '.review-feedback/';
+function resolveExcludePath(repoPath) {
+    try {
+        const output = execFileSync('git', ['rev-parse', '--git-path', 'info/exclude'], {
+            cwd: repoPath,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        return resolve(repoPath, output.trim());
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Lists `.review-feedback/` in the repo's local `.git/info/exclude`, so the
+ * hand-off file never shows up as a change and the tracked `.gitignore` is
+ * never edited. Returns false when `repoPath` is not a git repo.
+ */
+export function ensureGitExcludesHandoff(repoPath) {
+    const excludePath = resolveExcludePath(repoPath);
+    if (!excludePath)
+        return false;
+    const content = existsSync(excludePath) ? readFileSync(excludePath, 'utf-8') : '';
+    if (content.split('\n').some((line) => line.trim() === ENTRY))
+        return true;
+    const withTrailingNewline = content === '' || content.endsWith('\n') ? content : `${content}\n`;
+    mkdirSync(dirname(excludePath), { recursive: true });
+    writeFileSync(excludePath, `${withTrailingNewline}${ENTRY}\n`);
+    return true;
+}

package/dist/handoff/export-handoff.js

@@ -1,28 +1,28 @@
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { isOpenChangeRequest } from "../questions/questions-log.js";
 import { buildHandoffMarkdown } from "./build-handoff-markdown.js";
-import { ensureGitignoreExcludesHandoff } from "./ensure-gitignore.js";
-import { DEFAULT_REPO_PATH_CACHE_PATH, resolveRepoPath } from "./repo-path-cache.js";
+import { ensureGitExcludesHandoff } from "./ensure-git-exclude.js";
 /**
  * Exports open change-request Comments as a self-describing hand-off
- * Markdown file into the target repo's local working tree, and ensures
- * `.review-feedback/` is gitignored there. A no-op when there are no open
- * change-requests — this is what makes it safe to call after every publish.
+ * Markdown file into the target repo's local working tree, and lists
+ * `.review-feedback/` in that repo's `.git/info/exclude`. A no-op when there
+ * are no open change-requests — this is what makes it safe to call after
+ * every publish. Never prompts: without a usable repo path it skips.
  */
 export async function exportHandoff(options) {
-    const { bundlePath, comparison, round, comments, annotations, ask, repoPathCachePath } = options;
-    const hasOpenChangeRequest = comments.some((c) => c.kind === 'change-request' && c.status === 'open' && !c.resolved);
+    const { bundlePath, comparison, round, comments, annotations, repoPath } = options;
+    const hasOpenChangeRequest = comments.some(isOpenChangeRequest);
     if (!hasOpenChangeRequest)
         return { written: false };
-    if (!comparison.repository) {
-        throw new Error('comparison.repository is required to export a hand-off file');
-    }
-    const repoPath = await resolveRepoPath(comparison.repository, ask, repoPathCachePath ?? DEFAULT_REPO_PATH_CACHE_PATH);
+    if (!repoPath)
+        return { written: false, skipped: 'no-repo-path' };
+    if (!ensureGitExcludesHandoff(repoPath))
+        return { written: false, skipped: 'not-a-git-repo' };
     const markdown = buildHandoffMarkdown({ bundlePath, comparison, round, comments, annotations });
     const feedbackDir = join(repoPath, '.review-feedback');
     mkdirSync(feedbackDir, { recursive: true });
     const filePath = join(feedbackDir, `${comparison.number}-round${round}.md`);
     writeFileSync(filePath, markdown);
-    ensureGitignoreExcludesHandoff(repoPath);
     return { written: true, filePath, repoPath };
 }

package/dist/patch/parse.js

@@ -2,7 +2,9 @@ import { PatchParseError } from "./types.js";
 const GIT_FILE_HEADER = /^diff --git a\/(.+) b\/(.+)$/;
 const OLD_FILE_MARKER = /^--- (.+)$/;
 const NEW_FILE_MARKER = /^\+\+\+ (.+)$/;
+const NO_BASE_PATH = '/dev/null';
 const BINARY_MARKER = /^Binary files (?:a\/)?(.+) and (?:b\/)?(.+) differ$/;
+const EXTENDED_HEADER = /^(?:index |new file mode |deleted file mode |old mode |new mode |similarity index |rename from |rename to )/;
 const HUNK_HEADER = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/;
 function stripPrefix(path) {
     if (path === '/dev/null')
@@ -55,8 +57,11 @@ export function parsePatch(text) {
             // Binary marker's own paths: for a bare-format deletion the marker line reads
             // "Binary files a/X and /dev/null differ", so deriving identity from its second
             // capture group would wrongly produce "/dev/null" instead of the real path X.
+            const added = binaryMatch[1] === NO_BASE_PATH;
             if (!pendingGitPaths && currentFile !== null && currentFile.hunks.length === 0 && !currentFile.binary) {
                 currentFile.binary = true;
+                if (added)
+                    currentFile.added = true;
             }
             else {
                 const path = pendingGitPaths?.new ?? stripPrefix(binaryMatch[2]);
@@ -65,13 +70,14 @@ export function parsePatch(text) {
                     oldPath: pendingGitPaths?.old ?? stripPrefix(binaryMatch[1]),
                     binary: true,
                     hunks: [],
+                    ...(added && { added }),
                 };
                 files.push(currentFile);
             }
             pendingGitPaths = null;
             continue;
         }
-        if (line.startsWith('index '))
+        if (EXTENDED_HEADER.test(line))
             continue;
         // A real file header only ever appears between hunks, never inside one — so once a
         // hunk is open and still expects more lines, a "--- "/"+++ "-prefixed line is content