@erdemtuna/doc-review 0.12.0 → 0.13.0

package/lib/icons.js

@@ -30,6 +30,203 @@ export const ICON_NODES = Object.freeze({
             }
         ]
     ],
+    "filePenLine": [
+        [
+            "path",
+            {
+                "d": "M14.364 13.634a2 2 0 0 0-.506.854l-.837 2.87a.5.5 0 0 0 .62.62l2.87-.837a2 2 0 0 0 .854-.506l4.013-4.009a1 1 0 0 0-3.004-3.004z"
+            }
+        ],
+        [
+            "path",
+            {
+                "d": "M14.487 7.858A1 1 0 0 1 14 7V2"
+            }
+        ],
+        [
+            "path",
+            {
+                "d": "M20 19.645V20a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h8a2.4 2.4 0 0 1 1.704.706l2.516 2.516"
+            }
+        ],
+        [
+            "path",
+            {
+                "d": "M8 18h1"
+            }
+        ]
+    ],
+    "arrowRight": [
+        [
+            "path",
+            {
+                "d": "M5 12h14"
+            }
+        ],
+        [
+            "path",
+            {
+                "d": "m12 5 7 7-7 7"
+            }
+        ]
+    ],
+    "messageSquareDiff": [
+        [
+            "path",
+            {
+                "d": "M22 17a2 2 0 0 1-2 2H6.828a2 2 0 0 0-1.414.586l-2.202 2.202A.71.71 0 0 1 2 21.286V5a2 2 0 0 1 2-2h16a2 2 0 0 1 2 2z"
+            }
+        ],
+        [
+            "path",
+            {
+                "d": "M10 15h4"
+            }
+        ],
+        [
+            "path",
+            {
+                "d": "M10 9h4"
+            }
+        ],
+        [
+            "path",
+            {
+                "d": "M12 7v4"
+            }
+        ]
+    ],
+    "messageSquareCheck": [
+        [
+            "path",
+            {
+                "d": "M22 17a2 2 0 0 1-2 2H6.828a2 2 0 0 0-1.414.586l-2.202 2.202A.7.7 0 0 1 2 21.286V5a2 2 0 0 1 2-2h16a2 2 0 0 1 2 2z"
+            }
+        ],
+        [
+            "path",
+            {
+                "d": "m9 11 2 2 4-4"
+            }
+        ]
+    ],
+    "messageCircleQuestion": [
+        [
+            "path",
+            {
+                "d": "M2.992 16.342a2 2 0 0 1 .094 1.167l-1.065 3.29a1 1 0 0 0 1.236 1.168l3.413-.998a2 2 0 0 1 1.099.092 10 10 0 1 0-4.777-4.719"
+            }
+        ],
+        [
+            "path",
+            {
+                "d": "M9.09 9a3 3 0 0 1 5.83 1c0 2-3 3-3 3"
+            }
+        ],
+        [
+            "path",
+            {
+                "d": "M12 17h.01"
+            }
+        ]
+    ],
+    "circleDashed": [
+        [
+            "path",
+            {
+                "d": "M10.1 2.182a10 10 0 0 1 3.8 0"
+            }
+        ],
+        [
+            "path",
+            {
+                "d": "M13.9 21.818a10 10 0 0 1-3.8 0"
+            }
+        ],
+        [
+            "path",
+            {
+                "d": "M17.609 3.721a10 10 0 0 1 2.69 2.7"
+            }
+        ],
+        [
+            "path",
+            {
+                "d": "M2.182 13.9a10 10 0 0 1 0-3.8"
+            }
+        ],
+        [
+            "path",
+            {
+                "d": "M20.279 17.609a10 10 0 0 1-2.7 2.69"
+            }
+        ],
+        [
+            "path",
+            {
+                "d": "M21.818 10.1a10 10 0 0 1 0 3.8"
+            }
+        ],
+        [
+            "path",
+            {
+                "d": "M3.721 6.391a10 10 0 0 1 2.7-2.69"
+            }
+        ],
+        [
+            "path",
+            {
+                "d": "M6.391 20.279a10 10 0 0 1-2.69-2.7"
+            }
+        ]
+    ],
+    "circlePause": [
+        [
+            "circle",
+            {
+                "cx": "12",
+                "cy": "12",
+                "r": "10"
+            }
+        ],
+        [
+            "line",
+            {
+                "x1": "10",
+                "x2": "10",
+                "y1": "15",
+                "y2": "9"
+            }
+        ],
+        [
+            "line",
+            {
+                "x1": "14",
+                "x2": "14",
+                "y1": "15",
+                "y2": "9"
+            }
+        ]
+    ],
+    "copy": [
+        [
+            "rect",
+            {
+                "width": "14",
+                "height": "14",
+                "x": "8",
+                "y": "8",
+                "rx": "2",
+                "ry": "2"
+            }
+        ],
+        [
+            "path",
+            {
+                "d": "M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"
+            }
+        ]
+    ],
     "plus": [
         [
             "path",
@@ -106,6 +303,14 @@ export const ICON_NODES = Object.freeze({
             }
         ]
     ],
+    "chevronLeft": [
+        [
+            "path",
+            {
+                "d": "m15 18-6-6 6-6"
+            }
+        ]
+    ],
     "chevronRight": [
         [
             "path",
@@ -242,6 +447,124 @@ export const ICON_NODES = Object.freeze({
             }
         ]
     ],
+    "checkCheck": [
+        [
+            "path",
+            {
+                "d": "M18 6 7 17l-5-5"
+            }
+        ],
+        [
+            "path",
+            {
+                "d": "m22 10-7.5 7.5L13 16"
+            }
+        ]
+    ],
+    "circleCheck": [
+        [
+            "circle",
+            {
+                "cx": "12",
+                "cy": "12",
+                "r": "10"
+            }
+        ],
+        [
+            "path",
+            {
+                "d": "m16 9-5.5 5.5L8 12"
+            }
+        ]
+    ],
+    "rotateCcw": [
+        [
+            "path",
+            {
+                "d": "M3 12a9 9 0 1 0 9-9 9.75 9.75 0 0 0-6.74 2.74L3 8"
+            }
+        ],
+        [
+            "path",
+            {
+                "d": "M3 3v5h5"
+            }
+        ]
+    ],
+    "clock": [
+        [
+            "circle",
+            {
+                "cx": "12",
+                "cy": "12",
+                "r": "10"
+            }
+        ],
+        [
+            "path",
+            {
+                "d": "M12 6v6l4 2"
+            }
+        ]
+    ],
+    "inbox": [
+        [
+            "polyline",
+            {
+                "points": "22 12 16 12 14 15 10 15 8 12 2 12"
+            }
+        ],
+        [
+            "path",
+            {
+                "d": "M5.45 5.11 2 12v6a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-6l-3.45-6.89A2 2 0 0 0 16.76 4H7.24a2 2 0 0 0-1.79 1.11z"
+            }
+        ]
+    ],
+    "circleX": [
+        [
+            "circle",
+            {
+                "cx": "12",
+                "cy": "12",
+                "r": "10"
+            }
+        ],
+        [
+            "path",
+            {
+                "d": "m15 9-6 6"
+            }
+        ],
+        [
+            "path",
+            {
+                "d": "m9 9 6 6"
+            }
+        ]
+    ],
+    "circleHelp": [
+        [
+            "circle",
+            {
+                "cx": "12",
+                "cy": "12",
+                "r": "10"
+            }
+        ],
+        [
+            "path",
+            {
+                "d": "M9.09 9a3 3 0 0 1 5.83 1c0 2-3 3-3 3"
+            }
+        ],
+        [
+            "path",
+            {
+                "d": "M12 17h.01"
+            }
+        ]
+    ],
     "sun": [
         [
             "circle",

package/lib/new-message-target.js

@@ -0,0 +1,27 @@
+import { conversationTargetSchema } from "./contracts/feedback.js";
+import { reject } from "./contracts/validation.js";
+import { sanitizeClientRects, sanitizeClipRect } from "./comment-target.js";
+/** Existing SDK payload: anchors are required to save; geometry is optional presentation. */
+export function readNewMessageTarget(input) {
+    const target = conversationTargetSchema.parse({ kind: input.kind, anchor: input.anchor });
+    if (!Number.isSafeInteger(input.targetGeneration) || Number(input.targetGeneration) < 1) {
+        reject("INVALID_INPUT", "Invalid new-comment target generation.");
+    }
+    const viewport = input.viewport;
+    const relation = input.relation;
+    const clip = viewport && Number.isFinite(viewport.width) && viewport.width > 0 &&
+        Number.isFinite(viewport.height) && viewport.height > 0 ? sanitizeClipRect(input.clip, viewport) : null;
+    const rects = clip ? sanitizeClientRects(input.rects, viewport).flatMap((rect) => {
+        if (!rect)
+            return [];
+        const left = Math.max(rect.left, clip.left), top = Math.max(rect.top, clip.top);
+        const right = Math.min(rect.right, clip.right), bottom = Math.min(rect.bottom, clip.bottom);
+        return right > left && bottom > top ? [{ left, top, right, bottom, width: right - left, height: bottom - top }] : [];
+    }) : [];
+    const geometry = clip && ["visible", "above", "below", "unavailable"].includes(String(relation)) &&
+        (relation !== "visible" || rects.length) ? {
+        rects, clip, viewport: viewport, relation: relation,
+        horizontal: typeof input.horizontal === "number" && Number.isFinite(input.horizontal) ? input.horizontal : null,
+    } : null;
+    return { target, generation: Number(input.targetGeneration), geometry };
+}

package/lib/paths.js

@@ -4,7 +4,7 @@ import path from "node:path";
 import fs from "node:fs";
 // Bump for incompatible CLI/server or shell/SDK contracts, including readiness.
 // A new CLI must not silently reuse an older background server.
-export const SERVER_PROTOCOL = 18;
+export const SERVER_PROTOCOL = 25;
 export function serverProtocolMatches(protocol) {
     return Number(protocol) === SERVER_PROTOCOL;
 }
@@ -13,7 +13,7 @@ export function stateDir() {
     return override ? path.resolve(override) : path.join(homedir(), ".doc-review");
 }
 export function statePath() {
-    return path.join(stateDir(), "state.json");
+    return path.join(stateDir(), "conversation-state.json");
 }
 export function serverPath() {
     return path.join(stateDir(), "server.json");

package/lib/poll-transport.js

@@ -1,5 +1,8 @@
 import http from "node:http";
 import { performance } from "node:perf_hooks";
+import { acceptedMutationSchema } from "./contracts/feedback.js";
+import { pollResponseSchema } from "./contracts/page-boundary.js";
+import { ContractError, failureSchema } from "./contracts/validation.js";
 export const DEFAULT_POLL_SECONDS = 12 * 60 * 60;
 const MAX_TIMER_MS = 2 ** 31 - 1;
 const clock = {
@@ -162,48 +165,62 @@ export function parseServerResponse(response) {
         throw codedError("Malformed response from the doc-review server. End the review and restart the server.", "SERVER_RESPONSE_INVALID");
     }
 }
-export async function pollOnce(server, target, ackId, deadline) {
+export async function conversationOnce(server, body, decoder, deadline, route = "/api/conversation") {
     deadline.check();
-    const query = `target=${encodeURIComponent(target)}${ackId ? `&ack=${encodeURIComponent(ackId)}` : ""}`;
     const response = await requestRaw(server, {
-        method: "GET",
-        path: `/api/poll?${query}`,
-    }, undefined, {
-        timeoutMs: deadline.remaining(),
+        method: "POST", path: route, headers: { "content-type": "application/json" },
+    }, body, {
+        timeoutMs: Math.min(15000, deadline.remaining()),
         time: deadline.time,
-        timeoutCode: "POLL_DEADLINE",
     });
-    // Graceful server disposal ends the space heartbeats without a JSON payload.
-    // HTTP is complete, but this poll was interrupted just like a dropped socket.
-    if (response.status === 200 && /^ +$/.test(response.raw)) {
-        throw codedError("The server ended the poll before sending feedback.", "ERR_STREAM_PREMATURE_CLOSE");
+    let parsed;
+    try {
+        parsed = JSON.parse(response.raw);
+    }
+    catch (error) {
+        if (!(error instanceof SyntaxError))
+            throw error;
+        throw codedError("Malformed conversation response.", "SERVER_RESPONSE_INVALID");
+    }
+    if (response.status !== 200) {
+        let failure;
+        try {
+            failure = failureSchema.parse(parsed);
+        }
+        catch {
+            throw codedError(`Invalid error response (HTTP ${response.status}).`, "SERVER_RESPONSE_INVALID");
+        }
+        if (failure.error.status !== response.status)
+            throw codedError("HTTP and error status disagree.", "SERVER_RESPONSE_INVALID");
+        throw new ContractError(failure.error.code, failure.error.message);
     }
-    const batch = parseServerResponse(response);
-    if (!["feedback", "closed", "timeout"].includes(batch.status) ||
-        (batch.status === "feedback" && (typeof batch.batch_id !== "string" || !batch.batch_id || !Array.isArray(batch.pages)))) {
-        throw codedError("Malformed polling response from the doc-review server.", "SERVER_RESPONSE_INVALID");
+    try {
+        return decoder.parse(parsed);
+    }
+    catch {
+        throw codedError("Conversation response does not match its schema.", "SERVER_RESPONSE_INVALID");
     }
-    return batch;
 }
-export async function pollUntilDeadline({ target, ackId = "", deadline = createDeadline(), discover, poll = pollOnce, diagnostic = () => { }, }) {
+export const pollOnce = (server, reference, deadline) => conversationOnce(server, { operation: "poll", ...reference }, pollResponseSchema, deadline);
+export async function pollUntilDeadline({ reference, deadline = createDeadline(), discover, poll = pollOnce, diagnostic = () => { }, }) {
     let failures = 0;
     for (;;) {
         try {
             deadline.check();
             const server = await discover(deadline);
             deadline.check();
-            // An uncertain send must repeat the supplied receipt, never a newer ID.
-            const batch = await poll(server, target, ackId, deadline);
-            deadline.check();
-            return batch;
+            const result = await poll(server, reference, deadline);
+            if (result.review.reviewId !== reference.reviewId || result.review.entryKey !== reference.entryKey) {
+                throw codedError("Polling response belongs to another review.", "SERVER_RESPONSE_INVALID");
+            }
+            if (result.state !== "waiting")
+                return result;
+            failures = 0;
+            await deadline.sleep(500);
         }
         catch (err) {
             if (err.code === "POLL_DEADLINE" || deadline.remaining() <= 0) {
-                return {
-                    status: "timeout",
-                    waited_seconds: deadline.seconds,
-                    next_step: "No feedback yet. Run the same poll command again to keep waiting, or `doc-review status <target>` to check without blocking.",
-                };
+                return { state: "timeout", ...reference };
             }
             if (!isRecoverableTransportError(err))
                 throw err;
@@ -218,3 +235,69 @@ export async function pollUntilDeadline({ target, ackId = "", deadline = createD
         }
     }
 }
+/** Retry transport only. This function never opens or edits a reviewed source. */
+export async function mutationUntilDeadline({ body, deadline = createDeadline(60), discover, send = conversationOnce, diagnostic = () => { }, }) {
+    const request = structuredClone(body);
+    let failures = 0;
+    let reason = "unavailable";
+    let attempted = false;
+    const unknown = (detail = "") => Object.assign(new Error(`Acceptance is unknown. Reuse the identical request; do not repeat source edits.${detail ? ` ${detail}` : ""}`), { code: "TRANSPORT_UNKNOWN", outcome: { state: "unknown", requestId: request.requestId, reason } });
+    for (;;) {
+        try {
+            deadline.check();
+            const server = await discover(deadline);
+            deadline.check();
+            attempted = true;
+            const accepted = await send(server, request, acceptedMutationSchema, deadline);
+            const receipt = acceptedMutationSchema.parse(accepted).receipt;
+            if (receipt.requestId !== request.requestId || receipt.operation !== request.operation ||
+                (request.reviewId !== undefined && receipt.reviewId !== request.reviewId) ||
+                (request.entryKey !== undefined && receipt.entryKey !== request.entryKey) ||
+                (request.submissionId !== undefined && receipt.value.submissionId !== request.submissionId)) {
+                throw codedError("Receipt does not match the submitted request.", "SERVER_RESPONSE_INVALID");
+            }
+            return accepted;
+        }
+        catch (error) {
+            if (error instanceof ContractError && !["STATE_PERSIST_FAILED", "INTERNAL_ERROR"].includes(error.code))
+                throw error;
+            const recoverable = isRecoverableTransportError(error) || ["SERVER_RESPONSE_INVALID", "STATE_PERSIST_FAILED"].includes(error.code);
+            if (!recoverable && error.code !== "POLL_DEADLINE") {
+                if (attempted)
+                    throw unknown(error.message);
+                throw error;
+            }
+            if (error.code !== "POLL_DEADLINE")
+                reason = error.code === "SERVER_RESPONSE_INVALID" ? "invalid-response" :
+                    error.code === "ETIMEDOUT" ? "timeout" : error.code === "STATE_PERSIST_FAILED" ? "unavailable" : "disconnected";
+            if (error.code === "POLL_DEADLINE" || deadline.remaining() <= 0) {
+                throw unknown();
+            }
+            diagnostic(`Response uncertain (${error.message}); retrying the identical request.\n`);
+            try {
+                await deadline.sleep(Math.min(250 * 2 ** Math.min(failures++, 5), 5000));
+            }
+            catch (sleepError) {
+                if (sleepError.code !== "POLL_DEADLINE")
+                    throw sleepError;
+            }
+        }
+    }
+}
+export async function readUntilDeadline({ body, decoder, deadline = createDeadline(60), discover, diagnostic = () => { }, route }) {
+    let failures = 0;
+    for (;;) {
+        try {
+            deadline.check();
+            return await conversationOnce(await discover(deadline), body, decoder, deadline, route);
+        }
+        catch (error) {
+            if (error.code === "POLL_DEADLINE" || deadline.remaining() <= 0)
+                throw error;
+            if (!isRecoverableTransportError(error))
+                throw error;
+            diagnostic(`Read interrupted (${error.message}); retrying.\n`);
+            await deadline.sleep(Math.min(250 * 2 ** Math.min(failures++, 5), 5000));
+        }
+    }
+}

package/lib/positioning.js

@@ -95,3 +95,54 @@ export function alignedCardPosition(rects, { frameRect, viewport, width = 300, h
         top: Math.max(viewport.top + 12, Math.min(viewport.top + viewport.height - height - 12, top)),
     };
 }
+/** Popovers may cover unselected prose, never any visible part of their target. */
+function placeLocalSurface(geometry, { frameRect, viewport, surfaceWidth, surfaceHeight, minHeight = surfaceHeight, toolbarHeight = 48 }) {
+    if (!geometry || geometry.relation === "unavailable")
+        return null;
+    const bounds = { left: viewport.left + GAP, right: viewport.left + viewport.width - GAP,
+        top: viewport.top + toolbarHeight + GAP, bottom: viewport.top + viewport.height - GAP };
+    const width = Math.min(surfaceWidth, bounds.right - bounds.left);
+    if (width < 240 || bounds.bottom - bounds.top < minHeight)
+        return null;
+    const height = Math.min(surfaceHeight, bounds.bottom - bounds.top);
+    const clip = geometry.clip ? frameRectToChrome(geometry.clip, frameRect) : bounds;
+    const rects = geometry.rects.map(rect => frameRectToChrome(rect, frameRect)).map(rect => ({
+        left: Math.max(rect.left, clip.left, bounds.left - GAP), right: Math.min(rect.right, clip.right, bounds.right + GAP),
+        top: Math.max(rect.top, clip.top, bounds.top - GAP), bottom: Math.min(rect.bottom, clip.bottom, bounds.bottom + GAP),
+    })).filter(rect => rect.right > rect.left && rect.bottom > rect.top);
+    if (!rects.length) {
+        if (!["above", "below"].includes(geometry.relation))
+            return null;
+        const horizontal = Number.isFinite(geometry.horizontal) ? frameRect.left + geometry.horizontal : clip.left;
+        return { kind: geometry.relation === "above" ? "edge-top" : "edge-bottom",
+            left: clamp(horizontal, bounds.left, bounds.right - width),
+            top: clamp(geometry.relation === "above" ? clip.top + GAP : clip.bottom - height - GAP, bounds.top, bounds.bottom - height),
+            width, height };
+    }
+    const target = { left: Math.min(...rects.map(rect => rect.left)), right: Math.max(...rects.map(rect => rect.right)),
+        top: Math.min(...rects.map(rect => rect.top)), bottom: Math.max(...rects.map(rect => rect.bottom)) };
+    const x = clamp(target.left, bounds.left, bounds.right - width);
+    const y = clamp(target.top, bounds.top, bounds.bottom - height);
+    const below = Math.min(height, bounds.bottom - target.bottom - GAP);
+    const above = Math.min(height, target.top - GAP - bounds.top);
+    const candidates = [
+        { left: target.right + GAP, top: y, height },
+        { left: target.left - width - GAP, top: y, height },
+        { left: x, top: target.bottom + GAP, height: below },
+        { left: x, top: target.top - GAP - above, height: above },
+    ];
+    const fit = candidates.find(candidate => candidate.height >= minHeight &&
+        candidate.left >= bounds.left && candidate.left + width <= bounds.right &&
+        candidate.top >= bounds.top && candidate.top + candidate.height <= bounds.bottom &&
+        rects.every(rect => candidate.left >= rect.right + GAP || candidate.left + width <= rect.left - GAP ||
+            candidate.top >= rect.bottom + GAP || candidate.top + candidate.height <= rect.top - GAP));
+    return fit ? { kind: "attached", ...fit, width } : null;
+}
+export function placeNewMessageSurface(geometry, options) {
+    return placeLocalSurface(geometry, options);
+}
+export function placeConversationSurface(state, { frameRect, viewport, toolbarHeight = 48, width = 360, height = 260, minHeight = 160 }) {
+    if (state?.state !== "found")
+        return null;
+    return placeLocalSurface(state, { frameRect, viewport, toolbarHeight, surfaceWidth: width, surfaceHeight: height, minHeight });
+}