review-workspace 1.5.0 → 1.6.0

package/dist/bundle/carry-forward.js

@@ -0,0 +1,135 @@
+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 { incrementalTouchedPaths } from "./incremental-patch.js";
+export function createCaches() {
+    return { chain: new Map(), patch: new Map(), reviewDocument: new Map() };
+}
+export function readChain(bundlePath, caches = createCaches()) {
+    if (!caches.chain.has(bundlePath)) {
+        const path = join(bundlePath, 'chain.json');
+        caches.chain.set(bundlePath, existsSync(path) ? JSON.parse(readFileSync(path, 'utf-8')) : undefined);
+    }
+    return caches.chain.get(bundlePath);
+}
+export function resolvePreviousBundlePath(bundlePath, chain) {
+    return resolve(bundlePath, chain.previousBundle);
+}
+function readPatch(bundlePath, caches) {
+    if (!caches.patch.has(bundlePath)) {
+        caches.patch.set(bundlePath, parsePatch(readFileSync(join(bundlePath, 'changes.diff'), 'utf-8')));
+    }
+    return caches.patch.get(bundlePath);
+}
+function readReviewDocument(bundlePath, caches) {
+    if (!caches.reviewDocument.has(bundlePath)) {
+        caches.reviewDocument.set(bundlePath, JSON.parse(readFileSync(join(bundlePath, 'review.json'), 'utf-8')));
+    }
+    return caches.reviewDocument.get(bundlePath);
+}
+function openChangeRequests(bundlePath) {
+    return readQuestions(bundlePath).filter((c) => c.kind === 'change-request' && c.status === 'open' && !c.resolved);
+}
+/**
+ * Shared shape behind every chain-walking function below: a round-1 bundle (no
+ * `chain.json`) is the base case, otherwise resolve the previous round's bundle path
+ * and hand it (plus the chain itself, for its `round` number) to `step`.
+ */
+function walkChain(bundlePath, caches, base, step) {
+    const chain = readChain(bundlePath, caches);
+    return chain ? step(resolvePreviousBundlePath(bundlePath, chain), chain) : base();
+}
+/**
+ * Copies every still-open change-request Comment from the previous round in the chain
+ * into this round's own comment log, so it's visible and actionable here too. Idempotent
+ * — safe to call every time a round-N bundle is opened, validated, or rendered.
+ * No-ops for a round-1 bundle (no `chain.json`).
+ */
+export function carryForwardChain(bundlePath, caches = createCaches()) {
+    walkChain(bundlePath, caches, () => undefined, (previousBundlePath) => {
+        for (const comment of openChangeRequests(previousBundlePath)) {
+            carryForwardComment(bundlePath, comment);
+        }
+    });
+}
+/**
+ * Evaluates every comment carried forward from the previous round against this round's
+ * incremental patch. Assumes `carryForwardChain` has already copied them into this
+ * round's own log — this only reads, never writes.
+ */
+export function computeCarriedResolutions(bundlePath, caches = createCaches()) {
+    return walkChain(bundlePath, caches, () => [], (previousBundlePath) => {
+        const carriedIds = new Set(openChangeRequests(previousBundlePath).map((c) => c.id));
+        if (carriedIds.size === 0)
+            return [];
+        const previousPatch = readPatch(previousBundlePath, caches);
+        const currentPatch = readPatch(bundlePath, caches);
+        return readQuestions(bundlePath)
+            .filter((c) => carriedIds.has(c.id))
+            .map((comment) => ({ comment, resolution: evaluateResolution(comment, previousPatch, currentPatch) }));
+    });
+}
+function findOriginRound(bundlePath, commentId, caches) {
+    return walkChain(bundlePath, caches, () => 1, (previousBundlePath, chain) => {
+        const inPreviousRound = readQuestions(previousBundlePath).some((c) => c.id === commentId);
+        return inPreviousRound ? findOriginRound(previousBundlePath, commentId, caches) : chain.round;
+    });
+}
+/**
+ * The full comment history for this bundle: its own log, plus every ancestor round's
+ * comments not already present here (own log id, e.g. a resolved-in-round-1 change
+ * request never carried forward as open). Resolved comments are never dropped — they
+ * simply keep showing from whichever round's log actually holds them (framework.md's
+ * "never silently discard evidence").
+ */
+export function collectCommentHistory(bundlePath, caches = createCaches()) {
+    const own = readQuestions(bundlePath).map((c) => ({ ...c, originRound: findOriginRound(bundlePath, c.id, caches) }));
+    return walkChain(bundlePath, caches, () => own, (previousBundlePath) => {
+        const ownIds = new Set(own.map((c) => c.id));
+        const ancestorHistory = collectCommentHistory(previousBundlePath, caches).filter((c) => !ownIds.has(c.id));
+        return [...own, ...ancestorHistory].sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+    });
+}
+/** Every Comment relevant to this bundle, with its claimed Resolution attached where one applies. */
+export function listComments(bundlePath, caches = createCaches()) {
+    const resolutions = new Map(computeCarriedResolutions(bundlePath, caches).map((c) => [c.comment.id, c.resolution]));
+    return collectCommentHistory(bundlePath, caches).map((comment) => ({ ...comment, resolution: resolutions.get(comment.id) }));
+}
+function targetKey(target) {
+    switch (target.type) {
+        case 'file':
+            return `file:${target.path}`;
+        case 'binary':
+            return `binary:${target.path}`;
+        case 'hunk':
+            return `hunk:${target.path}:${target.hunkIndex}`;
+        case 'line':
+            return `line:${target.path}:${target.side}:${target.line}`;
+    }
+}
+/**
+ * Behavioral Groups/Annotations carried forward from earlier rounds for material the
+ * incremental patch doesn't touch — the round-N Generator is only expected to write
+ * fresh ones for genuinely new material (framework.md's "slim rounds"). Recurses the
+ * whole chain so a group/annotation keeps surfacing across every later round until a
+ * round's incremental patch actually touches its file, or a later round redeclares it.
+ */
+export function collectCarriedReviewContent(bundlePath, ownDocument, caches = createCaches()) {
+    return walkChain(bundlePath, caches, () => ({ behavioralGroups: [], annotations: [] }), (previousBundlePath) => {
+        const previousDocument = readReviewDocument(previousBundlePath, caches);
+        const previousCarried = collectCarriedReviewContent(previousBundlePath, previousDocument, caches);
+        const previousAll = {
+            behavioralGroups: [...(previousDocument.behavioralGroups ?? []), ...previousCarried.behavioralGroups],
+            annotations: [...(previousDocument.annotations ?? []), ...previousCarried.annotations],
+        };
+        const touchedPaths = incrementalTouchedPaths(readPatch(previousBundlePath, caches), readPatch(bundlePath, caches));
+        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))),
+            behavioralGroups: previousAll.behavioralGroups.filter((g) => !ownGroupIds.has(g.id) && !(g.targets ?? []).some((t) => touchedPaths.has(t.path))),
+        };
+    });
+}

package/dist/bundle/incremental-patch.js

@@ -0,0 +1,35 @@
+/**
+ * Both a round's own `changes.diff` and its predecessor's are full base..head patches
+ * (ADR 0002 — every bundle is a real Comparison), so there is no git access to compute
+ * `previousHead..head` directly (see framework.md's product boundary). Instead, a hunk
+ * that appears verbatim in both is treated as unchanged since the previous round; one
+ * that doesn't is incremental. This slightly over-reports "touched" when unrelated
+ * earlier edits shift a hunk's line numbers without changing its content, which is the
+ * conservative direction (never silently treats real change as untouched).
+ */
+function hunkFingerprint(path, hunkIndex, hunk) {
+    return JSON.stringify([path, hunkIndex, hunk]);
+}
+/** Hunks in `currentPatch`'s file at `path` that weren't present, verbatim and at the same
+ * index, in `previousPatch`. A file absent from `previousPatch` counts as entirely incremental.
+ * The index is part of the fingerprint so two textually-identical hunks at different
+ * locations (e.g. near-duplicate boilerplate) can never be mistaken for each other. */
+export function incrementalHunks(previousPatch, currentPatch, path) {
+    const currentFile = currentPatch.files.find((f) => f.path === path);
+    if (!currentFile)
+        return [];
+    const previousFile = previousPatch.files.find((f) => f.path === path);
+    if (!previousFile)
+        return currentFile.hunks;
+    const previousHunkKeys = new Set(previousFile.hunks.map((hunk, index) => hunkFingerprint(path, index, hunk)));
+    return currentFile.hunks.filter((hunk, index) => !previousHunkKeys.has(hunkFingerprint(path, index, hunk)));
+}
+/** File paths in `currentPatch` with at least one hunk incremental since `previousPatch`. */
+export function incrementalTouchedPaths(previousPatch, currentPatch) {
+    const touched = new Set();
+    for (const file of currentPatch.files) {
+        if (incrementalHunks(previousPatch, currentPatch, file.path).length > 0)
+            touched.add(file.path);
+    }
+    return touched;
+}

package/dist/bundle/resolution.js

@@ -0,0 +1,68 @@
+import { resolveTarget } from "./resolve-diagnostics.js";
+import { incrementalHunks } from "./incremental-patch.js";
+function targetHunkIndex(target, patch) {
+    const file = patch.files.find((f) => f.path === target.path);
+    if (!file)
+        return undefined;
+    if (target.type === 'hunk')
+        return target.hunkIndex;
+    if (target.type !== 'line')
+        return undefined;
+    return file.hunks.findIndex((h) => h.lines.some((l) => (target.side === 'base' ? l.oldLine === target.line : l.newLine === target.line)));
+}
+/**
+ * Evaluates one carried-forward change-request Comment against the round's incremental
+ * patch. `target-gone` reuses the same Target-resolution logic the engine already uses
+ * to flag stale Targets in `resolve-diagnostics.ts`, rather than reinventing it.
+ */
+export function evaluateResolution(comment, previousPatch, currentPatch) {
+    const target = comment.target;
+    if (!target) {
+        const anyIncrementalChange = currentPatch.files.some((f) => incrementalHunks(previousPatch, currentPatch, f.path).length > 0);
+        return anyIncrementalChange
+            ? {
+                commentId: comment.id,
+                status: 'target-partially-touched',
+                evidence: 'The incremental patch changed other content, but this comment has no Target to correlate against.',
+            }
+            : { commentId: comment.id, status: 'target-untouched', evidence: 'No incremental changes were made in this round.' };
+    }
+    const staleDiagnostic = resolveTarget(target, currentPatch);
+    if (staleDiagnostic) {
+        const detail = 'detail' in staleDiagnostic ? staleDiagnostic.detail : 'the Target no longer resolves';
+        return {
+            commentId: comment.id,
+            status: 'target-gone',
+            evidence: `The comment's original Target no longer resolves against this round's patch: ${detail}`,
+        };
+    }
+    const touchedHunks = incrementalHunks(previousPatch, currentPatch, target.path);
+    if (touchedHunks.length === 0) {
+        return {
+            commentId: comment.id,
+            status: 'target-untouched',
+            evidence: `${target.path} has no incremental changes since the previous round.`,
+        };
+    }
+    if (target.type === 'file' || target.type === 'binary') {
+        return {
+            commentId: comment.id,
+            status: 'target-partially-touched',
+            evidence: `${touchedHunks.length} hunk(s) changed in ${target.path} since the previous round.`,
+        };
+    }
+    const currentFile = currentPatch.files.find((f) => f.path === target.path);
+    const hunkIndex = targetHunkIndex(target, currentPatch);
+    const targetedHunkChanged = hunkIndex !== undefined && hunkIndex >= 0 && touchedHunks.includes(currentFile.hunks[hunkIndex]);
+    return targetedHunkChanged
+        ? {
+            commentId: comment.id,
+            status: 'target-touched',
+            evidence: `The hunk containing this comment's Target changed in the incremental patch — this is a mechanical signal only, not a judgment that the underlying concern was actually addressed.`,
+        }
+        : {
+            commentId: comment.id,
+            status: 'target-partially-touched',
+            evidence: `${target.path} changed elsewhere in the incremental patch, but not at this comment's exact Target.`,
+        };
+}

package/dist/bundle/resolve-diagnostics.js

@@ -22,7 +22,8 @@ function checkAssetPath(bundlePath, assetPath, limits) {
     }
     return undefined;
 }
-function resolveTarget(target, patch) {
+/** 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) {
     const file = findFile(patch, target.path);
     if (target.type === 'file') {
         if (!file)

package/dist/cli.js

@@ -4,6 +4,7 @@ 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;
 function fail(message) {
@@ -18,6 +19,7 @@ if (!command || !bundlePath) {
     fail('Usage: review-workspace <open|publish|serve|round> <bundlePath> [--port N] [--live-head SHA --patch FILE]');
 }
 if (command === 'open') {
+    carryForwardChain(bundlePath);
     const result = validateBundle(bundlePath);
     if (!result.valid) {
         fail(`Cannot open bundle: ${result.blockingReason} — ${result.message}`);

package/dist/questions/questions-log.js

@@ -105,6 +105,25 @@ export function resolveComment(bundlePath, commentId) {
         comment: { ...comment, resolved: true, resolvedAt: entry.createdAt },
     };
 }
+/**
+ * Copies a still-open change-request Comment from an earlier round's log into this
+ * round's own log, preserving its id and original createdAt so a Reviewer can act on it
+ * (resolve it) directly from this round. No-ops if this round's log already has a
+ * `raised` entry for that id — safe to call on every bundle open/validate/render.
+ */
+export function carryForwardComment(bundlePath, comment) {
+    const alreadyCarried = readLog(bundlePath).some((entry) => entry.type === 'raised' && entry.id === comment.id);
+    if (alreadyCarried)
+        return;
+    appendEntry(bundlePath, {
+        type: 'raised',
+        id: comment.id,
+        createdAt: comment.createdAt,
+        body: comment.body,
+        target: comment.target,
+        kind: comment.kind,
+    });
+}
 /** Reduces the append-only log into the current set of Comments. */
 export function readQuestions(bundlePath) {
     const comments = new Map();

package/dist/renderer/render.js

@@ -1,4 +1,5 @@
 import { resolve } from 'node:path';
+import { collectCarriedReviewContent, createCaches, readChain } from "../bundle/carry-forward.js";
 import { ALLOWED_ASSET_EXTENSIONS } from "../security/asset-path.js";
 /**
  * The app never launches a Generator itself (per framework.md) — this only
@@ -123,7 +124,22 @@ export function render(document, patch, diagnostics, bundlePath) {
         list.push(d);
         diagnosticsByPath.set(path, list);
     }
-    const groups = [...(document.behavioralGroups ?? [])]
+    // Both `chain` below and `collectCarriedReviewContent` read the same chain.json —
+    // sharing one `Caches` instance across both calls (scoped to this single `render()`
+    // call, then discarded) makes that one disk read either way, without ever letting the
+    // read survive past this call to go stale on a later one.
+    const caches = createCaches();
+    const chain = readChain(bundlePath, caches);
+    // Behavioral Groups/Annotations from earlier rounds the incremental patch doesn't
+    // touch surface here unchanged (framework.md's "slim rounds") — round N's own
+    // document only needs fresh ones for genuinely new material.
+    const carried = collectCarriedReviewContent(bundlePath, document, caches);
+    const effectiveDocument = {
+        ...document,
+        behavioralGroups: [...(document.behavioralGroups ?? []), ...carried.behavioralGroups],
+        annotations: [...(document.annotations ?? []), ...carried.annotations],
+    };
+    const groups = [...(effectiveDocument.behavioralGroups ?? [])]
         .sort((a, b) => a.order - b.order)
         .map((g) => ({
         id: g.id,
@@ -153,7 +169,7 @@ export function render(document, patch, diagnostics, bundlePath) {
     const files = orderedPaths
         .map((path) => patchFileByPath.get(path))
         .filter((f) => f !== undefined)
-        .map((f) => renderFile(f, document, diagnosticsByPath.get(f.path) ?? []));
+        .map((f) => renderFile(f, effectiveDocument, diagnosticsByPath.get(f.path) ?? []));
     const attachedPaths = new Set(patch.files.map((f) => f.path));
     const bundleLevelDiagnostics = diagnostics.filter((d) => {
         const path = diagnosticPath(d);
@@ -161,12 +177,13 @@ export function render(document, patch, diagnostics, bundlePath) {
     });
     return {
         comparison: document.comparison,
+        round: chain?.round ?? 1,
         groups,
         files,
         diagnostics: bundleLevelDiagnostics,
         generatorPrompt: buildGeneratorPrompt(bundlePath),
         answers: document.answers ?? [],
-        summary: renderSummary(document, attachedPaths),
+        summary: renderSummary(effectiveDocument, attachedPaths),
     };
 }
 /** Dangling ids/paths are dropped rather than diagnosed — same treatment as evidence/verification targetIds. */

package/dist/server/create-server.js

@@ -5,8 +5,9 @@ import { join } from 'node:path';
 import { validateBundle } from "../bundle/validate-bundle.js";
 import { publishBundleAndExportHandoff } from "../bundle/publish-with-handoff.js";
 import { watchBundle } from "./watch-bundle.js";
-import { raiseQuestion, readQuestions, resolveComment, withdrawAndReplaceQuestion } from "../questions/questions-log.js";
+import { raiseQuestion, resolveComment, withdrawAndReplaceQuestion } from "../questions/questions-log.js";
 import { askForRepoPathOnStdin } from "../handoff/ask-repo-path.js";
+import { carryForwardChain, listComments } from "../bundle/carry-forward.js";
 import { readReviewState, writeReviewState } from "../review-state/review-state.js";
 import { render } from "../renderer/render.js";
 import { buildReport } from "../export/report.js";
@@ -73,6 +74,10 @@ function readJsonBody(req) {
 export function startReviewServer(bundlePath, opts = {}) {
     const writeToken = opts.writeToken ?? generateWriteToken();
     const askForRepoPath = opts.askForRepoPath ?? askForRepoPathOnStdin;
+    // A round-N bundle (has chain.json) carries forward every still-open change-request
+    // from the previous round into its own log the moment it's opened — idempotent, so
+    // safe to repeat on every subsequent change below too.
+    carryForwardChain(bundlePath);
     // The served document is cached and only refreshed by the watcher below, so a
     // publish must actually trigger re-validation for /document to ever change —
     // this is what makes file watching load-bearing rather than a no-op wrapper
@@ -80,6 +85,7 @@ export function startReviewServer(bundlePath, opts = {}) {
     let latest = validateBundle(bundlePath);
     const watcher = watchBundle(bundlePath);
     watcher.emitter.on('change', () => {
+        carryForwardChain(bundlePath);
         latest = validateBundle(bundlePath);
     });
     const server = createServer((req, res) => {
@@ -106,7 +112,7 @@ export function startReviewServer(bundlePath, opts = {}) {
             return;
         }
         if (req.method === 'GET' && url.pathname === '/questions') {
-            respond(200, readQuestions(bundlePath));
+            respond(200, listComments(bundlePath));
             return;
         }
         if (req.method === 'GET' && url.pathname === '/state') {

package/package.json

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