@erdemtuna/doc-review 0.12.0 → 0.14.0

package/lib/conversation-save.js

@@ -0,0 +1,175 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { parse, parseFragment, serialize, serializeOuter } from "parse5";
+import { documentExecutionPolicy } from "./document-execution.js";
+import { isMarkdown } from "./markdown.js";
+import { stripSdk } from "./html-transform.js";
+import { stateDir } from "./paths.js";
+import { reject, rejectSave } from "./contracts/validation.js";
+import { REVISION_LIMITS } from "./revision-schema.js";
+export const sourceHash = (text) => crypto.createHash("sha1").update(text).digest("hex");
+export const stagedRoot = (key) => path.join(stateDir(), "conversation-pasted", key);
+export function readSource(page) {
+    if (page.kind === "url")
+        return { text: null, hash: null, writable: false };
+    try {
+        if (fs.statSync(page.file).size > REVISION_LIMITS.sourceBytes)
+            reject("SNAPSHOT_TOO_LARGE", "Source exceeds snapshot safety bound.");
+        const text = fs.readFileSync(page.file, "utf8");
+        if (Buffer.byteLength(text) > REVISION_LIMITS.sourceBytes)
+            reject("SNAPSHOT_TOO_LARGE", "Source exceeds snapshot safety bound.");
+        const policy = documentExecutionPolicy({ ...page, markdown: isMarkdown(page.file) }, text);
+        return { text, hash: sourceHash(text), writable: policy.savePolicy === "writable" };
+    }
+    catch (error) {
+        if (["ENOENT", "EACCES", "EPERM"].includes(error.code)) {
+            return { text: null, hash: null, writable: false };
+        }
+        throw error;
+    }
+}
+const textOf = (node) => node.nodeName === "#text" ? node.value : (node.childNodes || []).map(textOf).join("");
+function elements(root) {
+    const out = [];
+    const visit = (node) => {
+        if (node.tagName && !["html", "head", "body"].includes(node.tagName))
+            out.push(node);
+        for (const child of node.childNodes || [])
+            visit(child);
+    };
+    visit(root);
+    return out;
+}
+function matches(root, html, text) {
+    if (html !== undefined) {
+        const expected = serialize(parseFragment(html));
+        return elements(root).filter((node) => serializeOuter(node) === expected);
+    }
+    // Prefer the innermost exact block; ambiguity is rejected rather than guessed.
+    const candidates = elements(root).filter((node) => textOf(node) === text);
+    return candidates.filter((node) => !candidates.some((other) => other.parentNode === node));
+}
+function one(root, html, text) {
+    const found = matches(root, html, text);
+    if (found.length !== 1)
+        rejectSave("evidence-mismatch", "Edit source is absent or ambiguous; preserve it as source-pending.");
+    return found[0];
+}
+const conflict = (message) => rejectSave("evidence-mismatch", message);
+function neighborMatches(node, label) {
+    const text = textOf(node || {});
+    const flat = text.replace(/\s+/g, " ").trim();
+    const summary = flat.length > 90 ? `${flat.slice(0, 89).trimEnd()}\u2026` : flat;
+    return text === label || summary === label;
+}
+function neighbor(parent, label) {
+    if (!label)
+        return null;
+    const found = parent.childNodes.filter((node) => node.tagName && neighborMatches(node, label));
+    if (found.length !== 1)
+        conflict("Move boundary is absent or ambiguous.");
+    return found[0];
+}
+/** Prove a single recorded transition, not a client assertion that HTML was saved. */
+function applyEdit(document, edit, priorContent) {
+    if (edit.truncated)
+        conflict("Truncated edits cannot be saved as complete source.");
+    for (const content of [edit, ...(priorContent ? [priorContent] : [])]) {
+        for (const field of ["before", "after"]) {
+            if (content[field] !== undefined && content[`${field}_html`] !== undefined &&
+                textOf(parseFragment(content[`${field}_html`])) !== content[field]) {
+                conflict("HTML and text must describe the same exact edit.");
+            }
+        }
+    }
+    const before = priorContent || edit;
+    const node = one(document, priorContent ? before.after_html : before.before_html, priorContent ? before.after : before.before);
+    const parent = node.parentNode;
+    const index = parent.childNodes.indexOf(node);
+    if (edit.kind === "deleted")
+        parent.childNodes.splice(index, 1);
+    else if (edit.kind === "moved") {
+        parent.childNodes.splice(index, 1);
+        const after = neighbor(parent, edit.moved_after);
+        const next = neighbor(parent, edit.moved_before);
+        if ((!after && !next) || (after && after.parentNode !== parent) || (next && next.parentNode !== parent)) {
+            conflict("Move requires exact sibling boundaries.");
+        }
+        const position = after ? parent.childNodes.indexOf(after) + 1 : parent.childNodes.indexOf(next);
+        if (next && parent.childNodes.slice(position, parent.childNodes.indexOf(next)).some((item) => item.tagName)) {
+            conflict("Move boundaries disagree.");
+        }
+        parent.childNodes.splice(position, 0, node);
+    }
+    else if (edit.after_html !== undefined) {
+        const replacements = parseFragment(parent, edit.after_html).childNodes;
+        for (const replacement of replacements)
+            replacement.parentNode = parent;
+        parent.childNodes.splice(index, 1, ...replacements);
+    }
+    else {
+        node.childNodes = [{ nodeName: "#text", value: edit.after, parentNode: node }];
+    }
+}
+/** Every saved delta must be explained by exact, recorded transitions. */
+export function proveSave(current, candidate, transitions) {
+    if (Buffer.byteLength(candidate) > REVISION_LIMITS.sourceBytes)
+        reject("SNAPSHOT_TOO_LARGE", "Saved source exceeds snapshot safety bound.");
+    if (candidate !== stripSdk(candidate))
+        rejectSave("unsafe-content", "Injected review markup cannot be saved as source.");
+    if (documentExecutionPolicy({ kind: "file", markdown: false }, candidate).savePolicy !== "writable") {
+        rejectSave("unsafe-content", "This change introduces executable content; retain it as source-pending for source-directed handling.");
+    }
+    const document = parse(current);
+    for (const { content, priorContent } of transitions)
+        applyEdit(document, content, priorContent);
+    if (serialize(document) !== serialize(parse(candidate))) {
+        conflict("Saved HTML must contain exactly the recorded transitions; record other edits separately.");
+    }
+}
+export function sourceEditContent(edit) {
+    const content = { ...edit.content };
+    for (const field of ["before_html", "after_html"]) {
+        if (content[field] === undefined)
+            continue;
+        for (const asset of edit.assets)
+            content[field] = content[field].replaceAll(asset.preview_src, `assets/${asset.id}`);
+    }
+    return content;
+}
+export function editIncluded(text, content) {
+    const document = parse(text);
+    if (content.kind === "deleted")
+        return matches(document, content.before_html, content.before).length === 0;
+    const found = matches(document, content.after_html ?? content.before_html, content.after ?? content.before);
+    if (found.length !== 1)
+        return false;
+    if (content.kind !== "moved")
+        return true;
+    const siblings = found[0].parentNode.childNodes.filter((node) => node.tagName);
+    const index = siblings.indexOf(found[0]);
+    return (!content.moved_after || neighborMatches(siblings[index - 1], content.moved_after)) &&
+        (!content.moved_before || neighborMatches(siblings[index + 1], content.moved_before));
+}
+export function resolveEditAssets(key, content) {
+    return content.staged_assets.map(({ id, preview_src }) => {
+        if (path.basename(id) !== id || /[\\/:]/.test(id) || id === "." || id === "..")
+            reject("INVALID_INPUT", "Invalid staged asset identity.");
+        const root = stagedRoot(key);
+        const file = path.join(root, id);
+        let real;
+        try {
+            real = fs.realpathSync(file);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            reject("NOT_FOUND", "Staged asset is missing.");
+        }
+        if (path.dirname(real) !== fs.realpathSync(root) || !fs.statSync(real).isFile() ||
+            preview_src !== `__doc_review_paste__/${id}`)
+            reject("SCOPE_MISMATCH", "Asset is outside this page.");
+        return { id, path: real, preview_src };
+    });
+}

package/lib/conversation-server.js

@@ -0,0 +1,184 @@
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { contractFailure, ContractError, CONTRACT_LIMITS, reject, object, id, enumeration, integer, nullable, optional, timestamp, schema, } from "./contracts/validation.js";
+import { reviewReadRequestSchema } from "./contracts/page-boundary.js";
+import { readAgent } from "./agent-output.js";
+import { stagedRoot } from "./conversation-save.js";
+import { compareRevisions } from "./history-server.js";
+import { normalizeSemanticSnapshot } from "./revision-schema.js";
+import { normalizeView } from "./view-identity.js";
+export async function readConversationBody(req) {
+    let size = 0;
+    const chunks = [];
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size <= CONTRACT_LIMITS.requestBytes)
+            chunks.push(chunk);
+    }
+    if (size > CONTRACT_LIMITS.requestBytes)
+        reject("INPUT_TOO_LARGE", "Request exceeds 24 MiB UTF-8.");
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    }
+    catch (error) {
+        if (!(error instanceof SyntaxError))
+            throw error;
+        reject("MALFORMED_JSON", "Expected a JSON document.");
+    }
+}
+export function conversationFailure(error) {
+    if (error instanceof ContractError)
+        return contractFailure(error);
+    const known = {
+        SNAPSHOT_TOO_LARGE: "SNAPSHOT_TOO_LARGE", INVALID_REVISION: "INVALID_INPUT",
+        history_invalid_request: "INVALID_INPUT", history_frame_changed: "VERSION_CONFLICT",
+        history_source_changed: "SAVE_EVIDENCE_CONFLICT", history_source_unavailable: "SAVE_EVIDENCE_CONFLICT",
+        history_source_too_large: "SNAPSHOT_TOO_LARGE",
+    }[error.code];
+    if (known)
+        return contractFailure(new ContractError(known, error.message));
+    console.error("[doc-review] conversation request failed:", error);
+    return contractFailure(new ContractError("INTERNAL_ERROR", error.message));
+}
+export function createConversationController({ store, sessions, watchPage, json, emit, sourceWritten, currentRender, captureObservation, cliInvocation }) {
+    store.conversations.observationIsCurrent = (review, key, observation) => {
+        const session = sessions.get(observation.sessionId);
+        const render = currentRender(observation.renderId);
+        return session?.reviewId === review.reviewId && render?.sessionId === session.id && render.pageKey === key &&
+            render.generation === observation.generation && render.documentState === "served";
+    };
+    const attach = (reference) => {
+        const review = store.conversations.read({ operation: "read-review", ...reference });
+        const record = store.data.conversations.reviews[review.reviewId];
+        const sessionId = `s_${crypto.randomBytes(16).toString("hex")}`;
+        const session = {
+            id: sessionId, reviewId: review.reviewId, entryKey: review.entryKey, activeKey: review.entryKey,
+            generation: 0, renderId: null, executionPreferences: new Map(),
+            visited: new Set(Object.keys(record.pages)), clients: new Set(), lastSeen: Date.now(),
+        };
+        sessions.set(sessionId, session);
+        for (const key of session.visited)
+            watchPage(key);
+        return { sessionId, review, path: `/r/${review.reviewId}` };
+    };
+    const changed = () => {
+        // An overlapping review's permissions may have changed too. Always refetch.
+        for (const session of sessions.values())
+            if (session.reviewId) {
+                emit(session, "invalidate", { reviewId: session.reviewId });
+            }
+    };
+    const capture = (reference) => {
+        try {
+            store.conversations.captureResults(reference);
+        }
+        catch (error) {
+            console.error("[doc-review] result capture state not persisted; restart retries:", error.message);
+        }
+    };
+    for (const record of Object.values(store.data.conversations.reviews))
+        capture(record.review);
+    async function handle(req, res, url) {
+        if (!url.pathname.startsWith("/api/conversation"))
+            return false;
+        try {
+            if (req.method !== "POST")
+                reject("INVALID_INPUT", "Conversation endpoints require POST.");
+            const input = await readConversationBody(req);
+            let result;
+            if (url.pathname === "/api/conversation") {
+                const before = store.data;
+                result = store.conversations.execute(input);
+                if (before !== store.data && (input.operation === "save-edit" || input.operation === "revert"))
+                    sourceWritten(input.pageKey);
+                if (input.operation === "respond")
+                    capture(input);
+                if (input.operation === "respond" && before !== store.data) {
+                    const submission = store.data.conversations.reviews[input.reviewId].submissions[input.submissionId];
+                    const result = store.data.conversations.reviews[input.reviewId].results[submission.resultId];
+                    if (result.effect === "changes-reported")
+                        for (const session of sessions.values()) {
+                            if (session.reviewId === input.reviewId && submission.pageKeys.includes(session.activeKey)) {
+                                emit(session, "reload", { key: session.activeKey, reason: "submission-result" });
+                            }
+                        }
+                }
+                if (before !== store.data)
+                    changed();
+            }
+            else if (url.pathname === "/api/conversation/agent") {
+                result = readAgent(store.conversations, input, cliInvocation);
+            }
+            else if (url.pathname === "/api/conversation/session") {
+                const request = reviewReadRequestSchema.parse(input);
+                if (request.operation !== "read-review")
+                    reject("INVALID_INPUT", "Attach requires a read-review reference.");
+                result = attach({ reviewId: request.reviewId, entryKey: request.entryKey });
+            }
+            else if (url.pathname === "/api/conversation/capture") {
+                const request = object({
+                    reviewId: id, entryKey: id, pageKey: id, submissionId: nullable(id),
+                    sessionId: id, renderId: id, generation: integer(1), expectedSourceHash: nullable(id),
+                    semantic: schema((value) => normalizeSemanticSnapshot(value)),
+                    semanticCapturedAt: optional(timestamp), view: optional(schema((value) => normalizeView(value))),
+                }).parse(input);
+                store.conversations.read({ operation: "read-page", reviewId: request.reviewId, entryKey: request.entryKey, pageKey: request.pageKey });
+                if (request.submissionId === null && store.conversations.read({
+                    operation: "read-review", reviewId: request.reviewId, entryKey: request.entryKey,
+                }).state !== "open")
+                    reject("REVIEW_ENDED", "Ended review cannot replace a Send baseline.");
+                const session = sessions.get(request.sessionId);
+                if (session?.reviewId !== request.reviewId || session.entryKey !== request.entryKey)
+                    reject("SCOPE_MISMATCH", "Capture frame belongs to another review.");
+                const saved = captureObservation(session, request.pageKey, request, request.submissionId === null ? "submission-baseline" : "submission-result");
+                result = store.conversations.observe(request, {
+                    revisionId: saved.revisionId, sessionId: session.id, renderId: request.renderId, generation: request.generation,
+                });
+                changed();
+            }
+            else if (url.pathname === "/api/conversation/asset") {
+                const request = object({ reviewId: id, entryKey: id, pageKey: id,
+                    type: enumeration(["image/png", "image/jpeg", "image/gif", "image/webp"]), base64: id }).parse(input);
+                const page = store.conversations.read({
+                    operation: "read-page", reviewId: request.reviewId, entryKey: request.entryKey, pageKey: request.pageKey,
+                });
+                const review = store.conversations.read({ operation: "read-review", reviewId: request.reviewId, entryKey: request.entryKey });
+                if (review.state !== "open")
+                    reject("REVIEW_ENDED", "Ended review assets are read-only.");
+                if (page.writeBlockedBy.length)
+                    reject("WORK_OUTSTANDING", "Target has outstanding work.");
+                if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(request.base64))
+                    reject("INVALID_INPUT", "Invalid base64 image.");
+                const bytes = Buffer.from(request.base64, "base64");
+                if (!bytes.length)
+                    reject("INVALID_INPUT", "Empty image.");
+                const extension = { "image/png": "png", "image/jpeg": "jpg", "image/gif": "gif", "image/webp": "webp" }[request.type];
+                const assetId = `paste_${crypto.randomBytes(16).toString("hex")}.${extension}`;
+                fs.mkdirSync(stagedRoot(request.pageKey), { recursive: true, mode: 0o700 });
+                fs.writeFileSync(path.join(stagedRoot(request.pageKey), assetId), bytes, { flag: "wx", mode: 0o600 });
+                result = { id: assetId, preview_src: `__doc_review_paste__/${assetId}` };
+            }
+            else if (url.pathname === "/api/conversation/comparison") {
+                const request = object({ reviewId: id, entryKey: id, submissionId: id, pageKey: id, mode: enumeration(["source", "content"]) }).parse(input);
+                store.conversations.read({ operation: "submission", reviewId: request.reviewId, entryKey: request.entryKey, submissionId: request.submissionId });
+                const record = store.data.conversations.reviews[request.reviewId];
+                const comparison = Object.values(record.comparisons).find((item) => item.submissionId === request.submissionId && item.pageKey === request.pageKey);
+                if (!comparison)
+                    reject("SCOPE_MISMATCH", "Page has no comparison in this submission.");
+                result = compareRevisions(store.revisions, comparison.baselineRevisionId, comparison.resultRevisionId, request.mode, {
+                    resultUnavailable: comparison.reason,
+                });
+            }
+            else
+                reject("NOT_FOUND", "Unknown conversation endpoint.");
+            json(res, 200, result);
+        }
+        catch (error) {
+            const failure = conversationFailure(error);
+            json(res, failure.error.status, failure);
+        }
+        return true;
+    }
+    return { attach, changed, handle };
+}