review-workspace 1.2.0 → 1.4.0

package/dist/bundle/round.js

@@ -0,0 +1,71 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, relative } from 'node:path';
+/**
+ * A stable cross-round identity for one MR: repo slug + number, e.g.
+ * "founda/application/xds-viewer-ui!367".
+ */
+export function mrKeyFor(comparison) {
+    if (!comparison.repository || !comparison.number) {
+        throw new Error('comparison.repository and comparison.number are required to compute an mrKey');
+    }
+    return `${comparison.repository}!${comparison.number}`;
+}
+function readReviewDocument(bundlePath) {
+    return JSON.parse(readFileSync(join(bundlePath, 'review.json'), 'utf-8'));
+}
+/**
+ * Reads a bundle directory name shaped like `<name>-r{N}` and splits it into
+ * the chain's base name and that bundle's round number. A name with no
+ * `-r{N}` suffix is round 1.
+ */
+function parseBundleDirName(dirName) {
+    const match = dirName.match(/^(.+)-r(\d+)$/);
+    if (!match)
+        return { baseName: dirName, round: 1 };
+    return { baseName: match[1], round: Number(match[2]) };
+}
+/** The sibling bundle path a new round for `bundlePath` would scaffold into. */
+export function nextRoundBundlePath(bundlePath) {
+    const { baseName, round } = parseBundleDirName(basename(bundlePath));
+    return join(dirname(bundlePath), `${baseName}-r${round + 1}`);
+}
+/**
+ * Detects, purely from what's on disk plus a supplied live head, whether a
+ * bundle's recorded Comparison has fallen behind its MR — the "new round"
+ * case alongside New/Existing/Improve bundle determination.
+ */
+export function checkRound(bundlePath, liveHead) {
+    const { comparison } = readReviewDocument(bundlePath);
+    return { needsNewRound: comparison.head !== liveHead, recordedHead: comparison.head, 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.
+ */
+export function scaffoldNextRound(bundlePath, liveHead, options) {
+    const document = readReviewDocument(bundlePath);
+    if (document.comparison.head === liveHead) {
+        throw new Error(`Live head ${liveHead} matches the bundle's recorded head; no new round is needed`);
+    }
+    const { round: currentRound } = parseBundleDirName(basename(bundlePath));
+    const newBundlePath = nextRoundBundlePath(bundlePath);
+    if (existsSync(newBundlePath)) {
+        throw new Error(`Round bundle already exists at ${newBundlePath}`);
+    }
+    const chain = {
+        mrKey: mrKeyFor(document.comparison),
+        round: currentRound + 1,
+        previousBundle: relative(newBundlePath, bundlePath),
+        previousHead: document.comparison.head,
+    };
+    mkdirSync(newBundlePath, { recursive: true });
+    writeFileSync(join(newBundlePath, 'changes.diff'), options.patch);
+    writeFileSync(join(newBundlePath, 'review.json'), JSON.stringify({
+        schemaVersion: document.schemaVersion,
+        comparison: { ...document.comparison, head: liveHead },
+    }, null, 2));
+    writeFileSync(join(newBundlePath, 'chain.json'), JSON.stringify(chain, null, 2));
+    return { bundlePath: newBundlePath, chain };
+}

package/dist/cli.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
+import { readFileSync } from 'node:fs';
 import { validateBundle } from "./bundle/validate-bundle.js";
 import { publishBundle } from "./bundle/publish.js";
+import { checkRound, scaffoldNextRound } from "./bundle/round.js";
 import { startReviewServer } from "./server/create-server.js";
 const [, , command, bundlePath, ...rest] = process.argv;
 function fail(message) {
@@ -12,7 +14,7 @@ function flagValue(name) {
     return index === -1 ? undefined : rest[index + 1];
 }
 if (!command || !bundlePath) {
-    fail('Usage: review-workspace <open|publish|serve> <bundlePath> [--port N]');
+    fail('Usage: review-workspace <open|publish|serve|round> <bundlePath> [--port N] [--live-head SHA --patch FILE]');
 }
 if (command === 'open') {
     const result = validateBundle(bundlePath);
@@ -31,6 +33,22 @@ else if (command === 'publish') {
     }
     console.log('Published.');
 }
+else if (command === 'round') {
+    const liveHead = flagValue('--live-head');
+    const patchPath = flagValue('--patch');
+    if (!liveHead || !patchPath) {
+        fail('Usage: review-workspace round <bundlePath> --live-head <sha> --patch <patchFile>');
+    }
+    const { needsNewRound } = checkRound(bundlePath, liveHead);
+    if (!needsNewRound) {
+        console.log(JSON.stringify({ needsNewRound: false }));
+    }
+    else {
+        const patch = readFileSync(patchPath, 'utf-8');
+        const result = scaffoldNextRound(bundlePath, liveHead, { patch });
+        console.log(JSON.stringify({ needsNewRound: true, ...result }));
+    }
+}
 else if (command === 'serve') {
     const port = Number(flagValue('--port') ?? 4317);
     const handle = await startReviewServer(bundlePath, { port });

package/dist/questions/questions-log.js

@@ -20,18 +20,26 @@ function readLog(bundlePath) {
 function appendEntry(bundlePath, entry) {
     appendFileSync(logPath(bundlePath), JSON.stringify(entry) + '\n');
 }
-/** Raises a new, immutable question Comment. Never mutates or removes any existing log entry. */
-export function raiseQuestion(bundlePath, body, target) {
+/** Raises a new, immutable Comment. Never mutates or removes any existing log entry. */
+export function raiseQuestion(bundlePath, body, target, kind = 'question') {
     const entry = {
         type: 'raised',
         id: randomUUID(),
         createdAt: new Date().toISOString(),
         body,
         target,
-        kind: 'question',
+        kind,
     };
     appendEntry(bundlePath, entry);
-    return { id: entry.id, createdAt: entry.createdAt, body: entry.body, target: entry.target, kind: 'question', status: 'open' };
+    return {
+        id: entry.id,
+        createdAt: entry.createdAt,
+        body: entry.body,
+        target: entry.target,
+        kind,
+        status: 'open',
+        resolved: false,
+    };
 }
 /**
  * Withdraws an existing question Comment and raises its replacement in one call —
@@ -64,9 +72,39 @@ export function withdrawAndReplaceQuestion(bundlePath, questionId, replacementBo
             target: replacement.target,
             kind: 'question',
             status: 'open',
+            resolved: false,
         },
     };
 }
+function isOpenChangeRequest(comment) {
+    return comment.kind === 'change-request' && comment.status === 'open' && !comment.resolved;
+}
+/**
+ * Marks an open change-request Comment resolved. This is a human-only, reviewer-triggered
+ * action recorded in the same append-only log — nothing a Generator writes (the
+ * Review Document, `review.next.json`) can ever produce this entry.
+ *
+ * Validates before writing: a Comment that doesn't exist, or isn't currently an open
+ * change-request, is rejected without appending anything to the log.
+ */
+export function resolveComment(bundlePath, commentId) {
+    const comment = readQuestions(bundlePath).find((c) => c.id === commentId);
+    if (!comment)
+        return { outcome: 'not-found' };
+    if (!isOpenChangeRequest(comment))
+        return { outcome: 'not-resolvable', comment };
+    const entry = {
+        type: 'resolved',
+        id: randomUUID(),
+        createdAt: new Date().toISOString(),
+        commentId,
+    };
+    appendEntry(bundlePath, entry);
+    return {
+        outcome: 'resolved',
+        comment: { ...comment, resolved: true, resolvedAt: entry.createdAt },
+    };
+}
 /** Reduces the append-only log into the current set of Comments. */
 export function readQuestions(bundlePath) {
     const comments = new Map();
@@ -79,15 +117,23 @@ export function readQuestions(bundlePath) {
                 target: entry.target,
                 kind: entry.kind ?? 'question',
                 status: 'open',
+                resolved: false,
             });
         }
-        else {
+        else if (entry.type === 'withdrawn') {
             const comment = comments.get(entry.questionId);
             if (comment) {
                 comment.status = 'withdrawn';
                 comment.supersededBy = entry.replacementId;
             }
         }
+        else {
+            const comment = comments.get(entry.commentId);
+            if (comment && comment.kind === 'change-request') {
+                comment.resolved = true;
+                comment.resolvedAt = entry.createdAt;
+            }
+        }
     }
     return [...comments.values()].sort((a, b) => a.createdAt.localeCompare(b.createdAt));
 }

package/dist/server/create-server.js

@@ -5,7 +5,7 @@ import { join } from 'node:path';
 import { validateBundle } from "../bundle/validate-bundle.js";
 import { publishBundle } from "../bundle/publish.js";
 import { watchBundle } from "./watch-bundle.js";
-import { raiseQuestion, readQuestions, withdrawAndReplaceQuestion } from "../questions/questions-log.js";
+import { raiseQuestion, readQuestions, resolveComment, withdrawAndReplaceQuestion } from "../questions/questions-log.js";
 import { readReviewState, writeReviewState } from "../review-state/review-state.js";
 import { render } from "../renderer/render.js";
 import { buildReport } from "../export/report.js";
@@ -15,6 +15,8 @@ export function generateWriteToken() {
 }
 const WRITE_TOKEN_HEADER = 'x-write-token';
 const WITHDRAW_PATH = /^\/questions\/([^/]+)\/withdraw$/;
+const RESOLVE_PATH = /^\/questions\/([^/]+)\/resolve$/;
+const COMMENT_KINDS = ['question', 'change-request'];
 const ASSET_CONTENT_TYPES = {
     '.png': 'image/png',
     '.jpg': 'image/jpeg',
@@ -144,12 +146,16 @@ export function startReviewServer(bundlePath, opts = {}) {
         if (req.method === 'POST' && url.pathname === '/questions') {
             readJsonBody(req)
                 .then((body) => {
-                const { body: text, target } = body;
+                const { body: text, target, kind } = body;
                 if (typeof text !== 'string' || text.trim() === '') {
                     respond(400, { error: 'body is required' });
                     return;
                 }
-                respond(201, raiseQuestion(bundlePath, text, target));
+                if (kind !== undefined && !COMMENT_KINDS.includes(kind)) {
+                    respond(400, { error: `kind must be one of ${COMMENT_KINDS.join(', ')}` });
+                    return;
+                }
+                respond(201, raiseQuestion(bundlePath, text, target, kind ?? 'question'));
             })
                 .catch(() => respond(400, { error: 'invalid JSON body' }));
             return;
@@ -168,6 +174,23 @@ export function startReviewServer(bundlePath, opts = {}) {
                 .catch(() => respond(400, { error: 'invalid JSON body' }));
             return;
         }
+        // Human-only action: a Reviewer marking a change-request Comment resolved. This
+        // never reads from or writes to `review.next.json`/the Generator-owned Review
+        // Document — the Generator has no path to setting `resolved` (see ADR 0002).
+        const resolveMatch = RESOLVE_PATH.exec(url.pathname);
+        if (req.method === 'POST' && resolveMatch) {
+            const result = resolveComment(bundlePath, resolveMatch[1]);
+            if (result.outcome === 'not-found') {
+                respond(404, { error: 'no such Comment' });
+                return;
+            }
+            if (result.outcome === 'not-resolvable') {
+                respond(400, { error: 'Comment is not an open change-request' });
+                return;
+            }
+            respond(200, result.comment);
+            return;
+        }
         if (req.method === 'PUT' && url.pathname === '/state') {
             readJsonBody(req)
                 .then((body) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "review-workspace",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "A local, offline decision surface for reviewing a code Comparison — evidence-linked map of intent, behavior, risk, and observable effects.",
   "license": "MIT",
   "author": "Salih Sayer",