review-workspace 1.0.0

package/dist/renderer/render.js

@@ -0,0 +1,170 @@
+import { resolve } from 'node:path';
+import { ALLOWED_ASSET_EXTENSIONS } from "../security/asset-path.js";
+/**
+ * The app never launches a Generator itself (per framework.md) — this only
+ * builds text for the Reviewer to copy and run themselves.
+ */
+export function buildGeneratorPrompt(bundlePath) {
+    return `Invoke the /review-workspace skill on this bundle: ${resolve(bundlePath)}`;
+}
+/** Both layouts derive from the same RenderedLine[] — by construction they can never diverge in content. */
+export function toInlineRows(lines) {
+    return lines;
+}
+export function toSideBySideRows(lines) {
+    const rows = [];
+    let i = 0;
+    while (i < lines.length) {
+        if (lines[i].kind === 'context') {
+            rows.push({ left: lines[i], right: lines[i] });
+            i++;
+            continue;
+        }
+        const removes = [];
+        while (i < lines.length && lines[i].kind === 'remove') {
+            removes.push(lines[i]);
+            i++;
+        }
+        const adds = [];
+        while (i < lines.length && lines[i].kind === 'add') {
+            adds.push(lines[i]);
+            i++;
+        }
+        const max = Math.max(removes.length, adds.length);
+        for (let j = 0; j < max; j++) {
+            rows.push({ left: removes[j] ?? null, right: adds[j] ?? null });
+        }
+    }
+    return rows;
+}
+const OVERFLOW_THRESHOLD = 120;
+function targetPath(target) {
+    return target.path;
+}
+function diagnosticPath(diagnostic) {
+    return 'path' in diagnostic ? diagnostic.path : undefined;
+}
+function diagnosticLine(diagnostic) {
+    return diagnostic.kind === 'stale-line-target' ? diagnostic.line : undefined;
+}
+function renderFile(patchFile, document, fileDiagnostics) {
+    const fileAnnotations = (document.annotations ?? []).filter((a) => targetPath(a.target) === patchFile.path);
+    const hunks = patchFile.hunks.map((hunk, hunkIndex) => ({
+        oldStart: hunk.oldStart,
+        oldLines: hunk.oldLines,
+        newStart: hunk.newStart,
+        newLines: hunk.newLines,
+        lines: hunk.lines.map((line, lineIndex) => {
+            const lineAnnotations = fileAnnotations.filter((a) => a.target.type === 'line' &&
+                ((a.target.side === 'base' && a.target.line === line.oldLine) ||
+                    (a.target.side === 'head' && a.target.line === line.newLine)));
+            const lineDiagnostics = fileDiagnostics.filter((d) => diagnosticLine(d) !== undefined && (diagnosticLine(d) === line.oldLine || diagnosticLine(d) === line.newLine));
+            return {
+                id: `${patchFile.path}#${hunkIndex}#${lineIndex}`,
+                kind: line.kind,
+                text: line.text,
+                oldLine: line.oldLine,
+                newLine: line.newLine,
+                overflowsInline: line.text.length > OVERFLOW_THRESHOLD,
+                annotations: lineAnnotations,
+                diagnostics: lineDiagnostics,
+            };
+        }),
+    }));
+    const attachedLineDiagnosticKeys = new Set(hunks.flatMap((h) => h.lines.flatMap((l) => l.diagnostics)));
+    const fileLevelDiagnostics = fileDiagnostics.filter((d) => !attachedLineDiagnosticKeys.has(d));
+    const imageEvidence = (document.evidence ?? [])
+        .filter((e) => e.assetPath && ALLOWED_ASSET_EXTENSIONS.some((ext) => e.assetPath.toLowerCase().endsWith(ext)))
+        .filter((e) => (e.targetIds ?? []).includes(patchFile.path) || fileAnnotations.some((a) => (e.targetIds ?? []).includes(a.id)))
+        .map((e) => ({
+        id: e.id,
+        assetPath: e.assetPath,
+        baseAssetPath: e.baseAssetPath,
+        description: e.description,
+        comparisonModes: e.baseAssetPath ? ['side-by-side', 'swipe', 'onion-skin', 'changed-pixel'] : [],
+    }));
+    const pipelineEvidence = (document.evidence ?? [])
+        .filter((e) => e.pipeline)
+        .filter((e) => (e.targetIds ?? []).includes(patchFile.path) || fileAnnotations.some((a) => (e.targetIds ?? []).includes(a.id)))
+        .map((e) => ({
+        id: e.id,
+        jobName: e.pipeline.jobName,
+        status: e.pipeline.status,
+        url: e.pipeline.url,
+        logExcerpt: e.pipeline.logExcerpt,
+        description: e.description,
+    }));
+    return {
+        path: patchFile.path,
+        oldPath: patchFile.oldPath,
+        binary: patchFile.binary,
+        hunks,
+        annotations: fileAnnotations,
+        imageEvidence,
+        pipelineEvidence,
+        diagnostics: fileLevelDiagnostics,
+    };
+}
+/**
+ * Builds a deterministic, framework-agnostic view model from a validated bundle.
+ * Ordering: files belonging to a Behavioral Group are ordered by that group's
+ * declared `order`, then by the group's own target order; files not covered by
+ * any group fall back to patch order, per framework.md's "missing optional
+ * interpretation falls back to the complete patch in patch order" rule.
+ * Dependency/risk ordering is deferred — the schema has no such fields yet to sort by.
+ */
+export function render(document, patch, diagnostics, bundlePath) {
+    const diagnosticsByPath = new Map();
+    for (const d of diagnostics) {
+        const path = diagnosticPath(d);
+        if (!path)
+            continue;
+        const list = diagnosticsByPath.get(path) ?? [];
+        list.push(d);
+        diagnosticsByPath.set(path, list);
+    }
+    const groups = [...(document.behavioralGroups ?? [])]
+        .sort((a, b) => a.order - b.order)
+        .map((g) => ({
+        id: g.id,
+        title: g.title,
+        description: g.description,
+        order: g.order,
+        risk: g.risk,
+        filePaths: [...new Set((g.targets ?? []).map(targetPath))],
+    }));
+    const orderedPaths = [];
+    const seen = new Set();
+    for (const group of groups) {
+        for (const path of group.filePaths) {
+            if (!seen.has(path)) {
+                seen.add(path);
+                orderedPaths.push(path);
+            }
+        }
+    }
+    for (const patchFile of patch.files) {
+        if (!seen.has(patchFile.path)) {
+            seen.add(patchFile.path);
+            orderedPaths.push(patchFile.path);
+        }
+    }
+    const patchFileByPath = new Map(patch.files.map((f) => [f.path, f]));
+    const files = orderedPaths
+        .map((path) => patchFileByPath.get(path))
+        .filter((f) => f !== undefined)
+        .map((f) => renderFile(f, document, diagnosticsByPath.get(f.path) ?? []));
+    const attachedPaths = new Set(patch.files.map((f) => f.path));
+    const bundleLevelDiagnostics = diagnostics.filter((d) => {
+        const path = diagnosticPath(d);
+        return !path || !attachedPaths.has(path);
+    });
+    return {
+        comparison: document.comparison,
+        groups,
+        files,
+        diagnostics: bundleLevelDiagnostics,
+        generatorPrompt: buildGeneratorPrompt(bundlePath),
+        answers: document.answers ?? [],
+    };
+}

package/dist/renderer/types.js

@@ -0,0 +1 @@
+export {};

package/dist/review-state/review-state.js

@@ -0,0 +1,15 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { EMPTY_REVIEW_STATE } from "./types.js";
+function statePath(bundlePath) {
+    return join(bundlePath, 'state.json');
+}
+export function readReviewState(bundlePath) {
+    const path = statePath(bundlePath);
+    if (!existsSync(path))
+        return structuredClone(EMPTY_REVIEW_STATE);
+    return JSON.parse(readFileSync(path, 'utf-8'));
+}
+export function writeReviewState(bundlePath, state) {
+    writeFileSync(statePath(bundlePath), JSON.stringify(state, null, 2));
+}

package/dist/review-state/types.js

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

package/dist/schema/types.js

@@ -0,0 +1 @@
+export {};

package/dist/schema/validate.js

@@ -0,0 +1,14 @@
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import schema from '../../schemas/review-document.schema.json' with { type: 'json' };
+const ajv = new Ajv2020({ allErrors: true });
+addFormats(ajv);
+const validateFn = ajv.compile(schema);
+export function validateReviewDocumentSchema(input) {
+    const valid = validateFn(input);
+    if (!valid) {
+        return { valid: false, errors: validateFn.errors ?? [] };
+    }
+    return { valid: true, document: input };
+}
+export const CURRENT_SCHEMA_VERSION = 1;

package/dist/security/asset-path.js

@@ -0,0 +1,15 @@
+import { resolve, sep } from 'node:path';
+export const ALLOWED_ASSET_EXTENSIONS = ['.png', '.jpg', '.jpeg', '.gif', '.webp'];
+/** Resolves an evidence-declared relative path against the bundle's assets/ directory, refusing to leave it. */
+export function resolveAssetPath(bundlePath, assetPath) {
+    const assetsDir = resolve(bundlePath, 'assets');
+    const resolved = resolve(assetsDir, assetPath);
+    if (resolved !== assetsDir && !resolved.startsWith(assetsDir + sep)) {
+        return { ok: false, reason: 'unsafe-path' };
+    }
+    const lowerPath = resolved.toLowerCase();
+    if (!ALLOWED_ASSET_EXTENSIONS.some((ext) => lowerPath.endsWith(ext))) {
+        return { ok: false, reason: 'disallowed-type' };
+    }
+    return { ok: true, absolutePath: resolved };
+}

package/dist/security/limits.js

@@ -0,0 +1,6 @@
+export const DEFAULT_LIMITS = {
+    maxDocumentBytes: 5 * 1024 * 1024,
+    maxPatchBytes: 20 * 1024 * 1024,
+    maxPatchLines: 20_000,
+    maxAssetBytes: 10 * 1024 * 1024,
+};

package/dist/security/sanitize.js

@@ -0,0 +1,11 @@
+const ESCAPES = {
+    '&': '&',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#39;',
+};
+/** Disables raw HTML in Markdown-bearing text by escaping it to literal characters. */
+export function escapeRawHtml(text) {
+    return text.replace(/[&<>"']/g, (char) => ESCAPES[char]);
+}

package/dist/server/create-server.js

@@ -0,0 +1,204 @@
+import { createServer } from 'node:http';
+import { randomBytes } from 'node:crypto';
+import { createReadStream, existsSync, statSync } from 'node:fs';
+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 { readReviewState, writeReviewState } from "../review-state/review-state.js";
+import { render } from "../renderer/render.js";
+import { buildConcernComments, buildReport } from "../export/report.js";
+import { resolveAssetPath } from "../security/asset-path.js";
+export function generateWriteToken() {
+    return randomBytes(24).toString('hex');
+}
+const WRITE_TOKEN_HEADER = 'x-write-token';
+const WITHDRAW_PATH = /^\/questions\/([^/]+)\/withdraw$/;
+const ASSET_CONTENT_TYPES = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+};
+// `pnpm build:ui` copies the built Vite app here (sibling of src/) so a published
+// package can serve the UI itself — `npx review-workspace serve` with no separate
+// `cd ui && pnpm dev` step. Absent when running from source (dev uses Vite's own
+// dev server + proxy instead), so every lookup below treats a missing dir as "not built".
+const UI_DIST_DIR = join(import.meta.dirname, '..', '..', 'ui-dist');
+const UI_CONTENT_TYPES = {
+    '.html': 'text/html',
+    '.js': 'text/javascript',
+    '.css': 'text/css',
+    '.svg': 'image/svg+xml',
+    '.json': 'application/json',
+    ...ASSET_CONTENT_TYPES,
+};
+function serveUiStatic(pathname, res) {
+    if (!existsSync(UI_DIST_DIR))
+        return false;
+    // SPA fallback: any path without a recognized static-file extension is a client-side
+    // route (e.g. a deep link) — serve index.html and let the app's own router take over.
+    const hasExtension = /\.[a-zA-Z0-9]+$/.test(pathname);
+    const candidate = join(UI_DIST_DIR, hasExtension ? pathname : 'index.html');
+    const resolved = hasExtension && existsSync(candidate) && statSync(candidate).isFile() ? candidate : join(UI_DIST_DIR, 'index.html');
+    if (!existsSync(resolved))
+        return false;
+    const ext = resolved.slice(resolved.lastIndexOf('.')).toLowerCase();
+    res.writeHead(200, { 'content-type': UI_CONTENT_TYPES[ext] ?? 'application/octet-stream' });
+    createReadStream(resolved).pipe(res);
+    return true;
+}
+function readJsonBody(req) {
+    return new Promise((resolve, reject) => {
+        let raw = '';
+        req.on('data', (chunk) => {
+            raw += chunk;
+        });
+        req.on('end', () => {
+            try {
+                resolve(raw.trim() === '' ? {} : JSON.parse(raw));
+            }
+            catch (err) {
+                reject(err);
+            }
+        });
+        req.on('error', reject);
+    });
+}
+export function startReviewServer(bundlePath, opts = {}) {
+    const writeToken = opts.writeToken ?? generateWriteToken();
+    // 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
+    // around a stateless re-read-per-request design.
+    let latest = validateBundle(bundlePath);
+    const watcher = watchBundle(bundlePath);
+    watcher.emitter.on('change', () => {
+        latest = validateBundle(bundlePath);
+    });
+    const server = createServer((req, res) => {
+        const url = new URL(req.url ?? '/', 'http://localhost');
+        // The dev-mode Vite proxy strips this same prefix before forwarding here; a bundled
+        // production build talks to this one server directly, so both shapes must resolve
+        // to the same routes below.
+        if (url.pathname.startsWith('/api/'))
+            url.pathname = url.pathname.slice('/api'.length);
+        const respond = (status, body) => {
+            res.writeHead(status, { 'content-type': 'application/json' });
+            res.end(JSON.stringify(body));
+        };
+        if (req.method === 'GET' && url.pathname === '/document') {
+            respond(200, latest);
+            return;
+        }
+        if (req.method === 'GET' && url.pathname === '/view') {
+            if (!latest.valid) {
+                respond(422, { error: 'bundle is not valid', blockingReason: latest.blockingReason });
+                return;
+            }
+            respond(200, render(latest.document, latest.patch, latest.diagnostics ?? [], bundlePath));
+            return;
+        }
+        if (req.method === 'GET' && url.pathname === '/questions') {
+            respond(200, readQuestions(bundlePath));
+            return;
+        }
+        if (req.method === 'GET' && url.pathname === '/state') {
+            respond(200, readReviewState(bundlePath));
+            return;
+        }
+        if (req.method === 'GET' && url.pathname === '/report') {
+            if (!latest.valid) {
+                respond(422, { error: 'bundle is not valid', blockingReason: latest.blockingReason });
+                return;
+            }
+            res.writeHead(200, { 'content-type': 'text/markdown' });
+            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);
+            if (!resolution.ok || !existsSync(resolution.absolutePath) || !statSync(resolution.absolutePath).isFile()) {
+                respond(404, { error: 'asset not found' });
+                return;
+            }
+            const ext = assetPath.slice(assetPath.lastIndexOf('.')).toLowerCase();
+            res.writeHead(200, { 'content-type': ASSET_CONTENT_TYPES[ext] ?? 'application/octet-stream' });
+            createReadStream(resolution.absolutePath).pipe(res);
+            return;
+        }
+        if (req.method !== 'GET') {
+            if (req.headers[WRITE_TOKEN_HEADER] !== writeToken) {
+                respond(401, { error: 'invalid write token' });
+                return;
+            }
+        }
+        if (req.method === 'POST' && url.pathname === '/publish') {
+            const result = publishBundle(bundlePath);
+            respond(result.ok ? 200 : 422, result);
+            return;
+        }
+        if (req.method === 'POST' && url.pathname === '/questions') {
+            readJsonBody(req)
+                .then((body) => {
+                const { body: text, target } = body;
+                if (typeof text !== 'string' || text.trim() === '') {
+                    respond(400, { error: 'body is required' });
+                    return;
+                }
+                respond(201, raiseQuestion(bundlePath, text, target));
+            })
+                .catch(() => respond(400, { error: 'invalid JSON body' }));
+            return;
+        }
+        const withdrawMatch = WITHDRAW_PATH.exec(url.pathname);
+        if (req.method === 'POST' && withdrawMatch) {
+            readJsonBody(req)
+                .then((body) => {
+                const { body: text, target } = body;
+                if (typeof text !== 'string' || text.trim() === '') {
+                    respond(400, { error: 'body is required for the replacement Question' });
+                    return;
+                }
+                respond(201, withdrawAndReplaceQuestion(bundlePath, withdrawMatch[1], text, target));
+            })
+                .catch(() => respond(400, { error: 'invalid JSON body' }));
+            return;
+        }
+        if (req.method === 'PUT' && url.pathname === '/state') {
+            readJsonBody(req)
+                .then((body) => {
+                writeReviewState(bundlePath, body);
+                respond(200, body);
+            })
+                .catch(() => respond(400, { error: 'invalid JSON body' }));
+            return;
+        }
+        if (req.method === 'GET' && serveUiStatic(url.pathname, res))
+            return;
+        respond(404, { error: 'not found' });
+    });
+    return new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(opts.port ?? 0, '127.0.0.1', () => {
+            const address = server.address();
+            const port = typeof address === 'object' && address !== null ? address.port : 0;
+            resolve({
+                server,
+                writeToken,
+                port,
+                close: () => new Promise((res) => {
+                    watcher.stop();
+                    server.close(() => res());
+                }),
+            });
+        });
+    });
+}

package/dist/server/watch-bundle.js

@@ -0,0 +1,31 @@
+import { EventEmitter } from 'node:events';
+import { statSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Polls review.json's mtime rather than using fs.watch — fs.watch's rename/change
+ * semantics are notoriously inconsistent across platforms for atomic-rename-based
+ * writes, and a bundle is a local, low-frequency-write directory where a short poll
+ * interval is indistinguishable from a native watch in practice.
+ */
+export function watchBundle(bundlePath, intervalMs = 100) {
+    const emitter = new EventEmitter();
+    const reviewPath = join(bundlePath, 'review.json');
+    let lastMtime = statOrNull(reviewPath);
+    const timer = setInterval(() => {
+        const mtime = statOrNull(reviewPath);
+        if (mtime !== lastMtime) {
+            lastMtime = mtime;
+            emitter.emit('change');
+        }
+    }, intervalMs);
+    timer.unref();
+    return { emitter, stop: () => clearInterval(timer) };
+}
+function statOrNull(path) {
+    try {
+        return statSync(path).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "review-workspace",
+  "version": "1.0.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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sabasayer/review-workspace.git"
+  },
+  "homepage": "https://github.com/sabasayer/review-workspace#readme",
+  "bugs": {
+    "url": "https://github.com/sabasayer/review-workspace/issues"
+  },
+  "keywords": [
+    "code-review",
+    "cli",
+    "pull-request",
+    "merge-request",
+    "diff"
+  ],
+  "type": "module",
+  "bin": {
+    "review-workspace": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "schemas",
+    "ui-dist"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "packageManager": "pnpm@10.33.2",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "build:ui": "cd ui && pnpm install && pnpm build && rm -rf ../ui-dist && mv dist ../ui-dist",
+    "prepublishOnly": "pnpm test && pnpm typecheck && pnpm build && pnpm build:ui"
+  },
+  "devDependencies": {
+    "@semantic-release/changelog": "^7.0.0",
+    "@semantic-release/git": "^11.0.1",
+    "@semantic-release/github": "^12.0.9",
+    "@semantic-release/npm": "^13.1.5",
+    "@types/node": "^26.1.2",
+    "semantic-release": "^25.0.8",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "dependencies": {
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1"
+  }
+}