review-workspace 1.1.0 → 1.3.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/export/report.js

@@ -1,23 +1,3 @@
-function formatTarget(target) {
-    switch (target.type) {
-        case 'file':
-            return target.path;
-        case 'hunk':
-            return `${target.path}#hunk${target.hunkIndex}`;
-        case 'binary':
-            return `${target.path} (binary)`;
-        case 'line':
-            return `${target.path}:${target.line} (${target.side})`;
-    }
-}
-export function buildConcernComment(concern) {
-    const prefix = concern.target ? `[${formatTarget(concern.target)}] ` : '';
-    return `${prefix}${concern.note}`;
-}
-/** One comment per Concern, plain text — pasteable individually into an external tool. */
-export function buildConcernComments(state) {
-    return state.concerns.map(buildConcernComment);
-}
 /**
  * A self-contained Markdown report — no server needed to view it afterward.
  * Read-only with respect to the bundle: never mutates state.json or questions.jsonl.
@@ -41,16 +21,6 @@ export function buildReport(document, state) {
         }
     }
     lines.push('');
-    lines.push('## Concerns');
-    if (state.concerns.length === 0) {
-        lines.push('_None raised._');
-    }
-    else {
-        for (const comment of buildConcernComments(state)) {
-            lines.push(`- ${comment}`);
-        }
-    }
-    lines.push('');
     lines.push('## Notes');
     if (state.notes.length === 0) {
         lines.push('_None._');

package/dist/questions/questions-log.js

@@ -1,6 +1,9 @@
 import { appendFileSync, existsSync, readFileSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { join } from 'node:path';
+// File name predates the Comment/kind split (it only ever held Questions) — kept
+// as-is so bundles created before this change keep reading correctly; only the
+// in-memory shape gained `kind`, not the on-disk path.
 function logPath(bundlePath) {
     return join(bundlePath, 'questions.jsonl');
 }
@@ -17,15 +20,22 @@ function readLog(bundlePath) {
 function appendEntry(bundlePath, entry) {
     appendFileSync(logPath(bundlePath), JSON.stringify(entry) + '\n');
 }
-/** Raises a new, immutable Question. Never mutates or removes any existing log entry. */
+/** Raises a new, immutable question Comment. Never mutates or removes any existing log entry. */
 export function raiseQuestion(bundlePath, body, target) {
-    const entry = { type: 'raised', id: randomUUID(), createdAt: new Date().toISOString(), body, target };
+    const entry = {
+        type: 'raised',
+        id: randomUUID(),
+        createdAt: new Date().toISOString(),
+        body,
+        target,
+        kind: 'question',
+    };
     appendEntry(bundlePath, entry);
-    return { id: entry.id, createdAt: entry.createdAt, body: entry.body, target: entry.target, status: 'open' };
+    return { id: entry.id, createdAt: entry.createdAt, body: entry.body, target: entry.target, kind: 'question', status: 'open' };
 }
 /**
- * Withdraws an existing Question and raises its replacement in one call — a
- * correction is recorded as new log entries, never as an edit to the original.
+ * Withdraws an existing question Comment and raises its replacement in one call —
+ * a correction is recorded as new log entries, never as an edit to the original.
  */
 export function withdrawAndReplaceQuestion(bundlePath, questionId, replacementBody, replacementTarget) {
     const replacement = {
@@ -34,6 +44,7 @@ export function withdrawAndReplaceQuestion(bundlePath, questionId, replacementBo
         createdAt: new Date().toISOString(),
         body: replacementBody,
         target: replacementTarget,
+        kind: 'question',
     };
     const withdrawal = {
         type: 'withdrawn',
@@ -51,30 +62,32 @@ export function withdrawAndReplaceQuestion(bundlePath, questionId, replacementBo
             createdAt: replacement.createdAt,
             body: replacement.body,
             target: replacement.target,
+            kind: 'question',
             status: 'open',
         },
     };
 }
-/** Reduces the append-only log into the current set of Questions. */
+/** Reduces the append-only log into the current set of Comments. */
 export function readQuestions(bundlePath) {
-    const questions = new Map();
+    const comments = new Map();
     for (const entry of readLog(bundlePath)) {
         if (entry.type === 'raised') {
-            questions.set(entry.id, {
+            comments.set(entry.id, {
                 id: entry.id,
                 createdAt: entry.createdAt,
                 body: entry.body,
                 target: entry.target,
+                kind: entry.kind ?? 'question',
                 status: 'open',
             });
         }
         else {
-            const question = questions.get(entry.questionId);
-            if (question) {
-                question.status = 'withdrawn';
-                question.supersededBy = entry.replacementId;
+            const comment = comments.get(entry.questionId);
+            if (comment) {
+                comment.status = 'withdrawn';
+                comment.supersededBy = entry.replacementId;
             }
         }
     }
-    return [...questions.values()].sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+    return [...comments.values()].sort((a, b) => a.createdAt.localeCompare(b.createdAt));
 }

package/dist/review-state/types.js

@@ -1,6 +1,5 @@
 export const EMPTY_REVIEW_STATE = {
     groups: {},
-    concerns: [],
     notes: [],
     decision: 'unset',
 };

package/dist/server/create-server.js

@@ -8,7 +8,7 @@ import { watchBundle } from "./watch-bundle.js";
 import { raiseQuestion, readQuestions, withdrawAndReplaceQuestion } from "../questions/questions-log.js";
 import { readReviewState, writeReviewState } from "../review-state/review-state.js";
 import { render } from "../renderer/render.js";
-import { buildConcernComments, buildReport } from "../export/report.js";
+import { buildReport } from "../export/report.js";
 import { resolveAssetPath } from "../security/asset-path.js";
 export function generateWriteToken() {
     return randomBytes(24).toString('hex');
@@ -118,10 +118,6 @@ export function startReviewServer(bundlePath, opts = {}) {
             res.end(buildReport(latest.document, readReviewState(bundlePath)));
             return;
         }
-        if (req.method === 'GET' && url.pathname === '/concerns') {
-            respond(200, buildConcernComments(readReviewState(bundlePath)));
-            return;
-        }
         if (req.method === 'GET' && url.pathname.startsWith('/assets/')) {
             const assetPath = decodeURIComponent(url.pathname.slice('/assets/'.length));
             const resolution = resolveAssetPath(bundlePath, assetPath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "review-workspace",
-  "version": "1.1.0",
+  "version": "1.3.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",