review-workspace 1.3.0 → 1.4.0

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.3.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",