@erdemtuna/doc-review 0.7.0 → 0.8.1

package/src/icons.js

@@ -0,0 +1,251 @@
+// Generated by scripts/generate-icons.js from lucide-static. Do not edit.
+export const ICON_NODES = Object.freeze({
+  "eye": [
+    [
+      "path",
+      {
+        "d": "M2.062 12.348a1 1 0 0 1 0-.696 10.75 10.75 0 0 1 19.876 0 1 1 0 0 1 0 .696 10.75 10.75 0 0 1-19.876 0"
+      }
+    ],
+    [
+      "circle",
+      {
+        "cx": "12",
+        "cy": "12",
+        "r": "3"
+      }
+    ]
+  ],
+  "pencil": [
+    [
+      "path",
+      {
+        "d": "M21.174 6.812a1 1 0 0 0-3.986-3.987L3.842 16.174a2 2 0 0 0-.5.83l-1.321 4.352a.5.5 0 0 0 .623.622l4.353-1.32a2 2 0 0 0 .83-.497z"
+      }
+    ],
+    [
+      "path",
+      {
+        "d": "m15 5 4 4"
+      }
+    ]
+  ],
+  "chevronDown": [
+    [
+      "path",
+      {
+        "d": "m6 9 6 6 6-6"
+      }
+    ]
+  ],
+  "messageSquarePlus": [
+    [
+      "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": "M12 8v6"
+      }
+    ],
+    [
+      "path",
+      {
+        "d": "M9 11h6"
+      }
+    ]
+  ],
+  "messages": [
+    [
+      "path",
+      {
+        "d": "M16 10a2 2 0 0 1-2 2H6.828a2 2 0 0 0-1.414.586l-2.202 2.202A.71.71 0 0 1 2 14.286V4a2 2 0 0 1 2-2h10a2 2 0 0 1 2 2z"
+      }
+    ],
+    [
+      "path",
+      {
+        "d": "M20 9a2 2 0 0 1 2 2v10.286a.71.71 0 0 1-1.212.502l-2.202-2.202A2 2 0 0 0 17.172 19H10a2 2 0 0 1-2-2v-1"
+      }
+    ]
+  ],
+  "send": [
+    [
+      "path",
+      {
+        "d": "M14.536 21.686a.5.5 0 0 0 .937-.024l6.5-19a.496.496 0 0 0-.635-.635l-19 6.5a.5.5 0 0 0-.024.937l7.93 3.18a2 2 0 0 1 1.112 1.11z"
+      }
+    ],
+    [
+      "path",
+      {
+        "d": "m21.854 2.147-10.94 10.939"
+      }
+    ]
+  ],
+  "trash": [
+    [
+      "path",
+      {
+        "d": "M10 11v6"
+      }
+    ],
+    [
+      "path",
+      {
+        "d": "M14 11v6"
+      }
+    ],
+    [
+      "path",
+      {
+        "d": "M19 6v14a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V6"
+      }
+    ],
+    [
+      "path",
+      {
+        "d": "M3 6h18"
+      }
+    ],
+    [
+      "path",
+      {
+        "d": "M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2"
+      }
+    ]
+  ],
+  "moreHorizontal": [
+    [
+      "circle",
+      {
+        "cx": "12",
+        "cy": "12",
+        "r": "1"
+      }
+    ],
+    [
+      "circle",
+      {
+        "cx": "19",
+        "cy": "12",
+        "r": "1"
+      }
+    ],
+    [
+      "circle",
+      {
+        "cx": "5",
+        "cy": "12",
+        "r": "1"
+      }
+    ]
+  ],
+  "x": [
+    [
+      "path",
+      {
+        "d": "M18 6 6 18"
+      }
+    ],
+    [
+      "path",
+      {
+        "d": "m6 6 12 12"
+      }
+    ]
+  ],
+  "check": [
+    [
+      "path",
+      {
+        "d": "M20 6 9 17l-5-5"
+      }
+    ]
+  ],
+  "sun": [
+    [
+      "circle",
+      {
+        "cx": "12",
+        "cy": "12",
+        "r": "4"
+      }
+    ],
+    [
+      "path",
+      {
+        "d": "M12 2v2"
+      }
+    ],
+    [
+      "path",
+      {
+        "d": "M12 20v2"
+      }
+    ],
+    [
+      "path",
+      {
+        "d": "m4.93 4.93 1.41 1.41"
+      }
+    ],
+    [
+      "path",
+      {
+        "d": "m17.66 17.66 1.41 1.41"
+      }
+    ],
+    [
+      "path",
+      {
+        "d": "M2 12h2"
+      }
+    ],
+    [
+      "path",
+      {
+        "d": "M20 12h2"
+      }
+    ],
+    [
+      "path",
+      {
+        "d": "m6.34 17.66-1.41 1.41"
+      }
+    ],
+    [
+      "path",
+      {
+        "d": "m19.07 4.93-1.41 1.41"
+      }
+    ]
+  ],
+  "moon": [
+    [
+      "path",
+      {
+        "d": "M20.985 12.486a9 9 0 1 1-9.473-9.472c.405-.022.617.46.402.803a6 6 0 0 0 8.268 8.268c.344-.215.825-.004.803.401"
+      }
+    ]
+  ]
+});
+
+const escape = (value) => String(value).replace(/[&<>"]/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[char]);
+
+export function iconMarkup(name, { title = "", className = "icon", size = 16 } = {}) {
+  const nodes = ICON_NODES[name];
+  if (!nodes) throw new Error(`Unknown icon: ${name}`);
+  const body = nodes.map(([tag, attrs]) => `<${tag} ${Object.entries(attrs).map(([key, value]) => `${key}="${escape(value)}"`).join(" ")}></${tag}>`).join("");
+  const label = title ? ` role="img" aria-label="${escape(title)}"` : ' aria-hidden="true"';
+  return `<svg class="${escape(className)}" width="${size}" height="${size}" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"${label}>${body}</svg>`;
+}
+
+export function createIcon(name, options = {}) {
+  const template = document.createElement("template");
+  template.innerHTML = iconMarkup(name, options);
+  return template.content.firstElementChild;
+}

package/src/paths.js

@@ -5,7 +5,11 @@ import fs from "node:fs";
 
 // Bump this when the CLI and detached server no longer share the same request
 // contract. A new CLI must not silently reuse an older background server.
-export const SERVER_PROTOCOL = 11;
+export const SERVER_PROTOCOL = 13;
+
+export function serverProtocolMatches(protocol) {
+  return Number(protocol) === SERVER_PROTOCOL;
+}
 
 export function stateDir() {
   const override = process.env.DOC_REVIEW_STATE_DIR;

package/src/poll-transport.js

@@ -0,0 +1,222 @@
+import http from "node:http";
+import { performance } from "node:perf_hooks";
+
+export const DEFAULT_POLL_SECONDS = 12 * 60 * 60;
+const MAX_TIMER_MS = 2 ** 31 - 1;
+const clock = {
+  now: () => performance.now(),
+  setTimeout: (fn, ms) => setTimeout(fn, ms),
+  clearTimeout: (timer) => clearTimeout(timer),
+};
+
+function codedError(message, code) {
+  return Object.assign(new Error(message), { code });
+}
+
+export function createDeadline(seconds = DEFAULT_POLL_SECONDS, time = clock) {
+  const end = time.now() + seconds * 1000;
+  const remaining = () => Math.max(0, end - time.now());
+  const check = () => {
+    if (remaining() <= 0) throw codedError("Polling deadline reached.", "POLL_DEADLINE");
+  };
+  return {
+    seconds,
+    time,
+    remaining,
+    check,
+    async sleep(ms) {
+      check();
+      await new Promise((resolve) => time.setTimeout(resolve, Math.min(ms, remaining(), MAX_TIMER_MS)));
+      check();
+    },
+  };
+}
+
+export function isRecoverableTransportError(err) {
+  return new Set([
+    "ECONNRESET", "ECONNREFUSED", "EPIPE", "ETIMEDOUT", "EHOSTUNREACH",
+    "ENETUNREACH", "ENETDOWN", "ECONNABORTED", "ERR_STREAM_PREMATURE_CLOSE",
+    "SERVER_START_PENDING",
+  ]).has(err?.code);
+}
+
+/**
+ * An absolute response deadline, not a socket-idle timeout: heartbeats and
+ * partially received JSON must not extend the caller's waiting budget.
+ */
+export function requestRaw(server, options, body, {
+  timeoutMs = options.timeout,
+  time = clock,
+  signal,
+  timeoutCode = "ETIMEDOUT",
+  makeRequest = http.request,
+} = {}) {
+  return new Promise((resolve, reject) => {
+    let req;
+    let res;
+    let timer;
+    let done = false;
+    let ended = false;
+    let raw = "";
+    const expires = timeoutMs == null ? null : time.now() + timeoutMs;
+    const premature = () => codedError("The server closed an incomplete response.", "ERR_STREAM_PREMATURE_CLOSE");
+    const cleanupResponse = () => {
+      res?.removeListener("data", onData);
+      res?.removeListener("end", onEnd);
+      res?.removeListener("aborted", onAborted);
+    };
+    const settle = (err, value) => {
+      if (done) return;
+      done = true;
+      time.clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      cleanupResponse();
+      // Keep error handlers until close: destroying a socket may emit one last
+      // error asynchronously. Close removes the remaining owned listeners.
+      res?.destroy();
+      req?.destroy();
+      if (err) reject(err);
+      else resolve(value);
+    };
+    const onError = (err) => settle(err);
+    const onData = (chunk) => { raw += chunk; };
+    const onEnd = () => {
+      ended = true;
+      if (!res.complete) return settle(premature());
+      settle(null, { status: res.statusCode, raw });
+    };
+    const onAborted = () => settle(premature());
+    const onResponseClose = () => {
+      if (!ended) settle(premature());
+      cleanupResponse();
+      res.removeListener("error", onError);
+      res.removeListener("close", onResponseClose);
+    };
+    const onRequestClose = () => {
+      if (!done) settle(premature());
+      req.removeListener("error", onError);
+      req.removeListener("close", onRequestClose);
+      req.removeListener("response", onResponse);
+    };
+    const onAbort = () => settle(codedError("Polling cancelled.", "ABORT_ERR"));
+    const armTimer = () => {
+      const left = expires - time.now();
+      if (left <= 0) return settle(codedError("Polling request timed out.", timeoutCode));
+      timer = time.setTimeout(armTimer, Math.min(left, MAX_TIMER_MS));
+    };
+    const onResponse = (response) => {
+      res = response;
+      if (done) {
+        res.destroy();
+        return;
+      }
+      res.setEncoding("utf8");
+      res.on("data", onData);
+      res.on("end", onEnd);
+      res.on("error", onError);
+      res.on("aborted", onAborted);
+      res.on("close", onResponseClose);
+    };
+    try {
+      if (signal?.aborted) return onAbort();
+      const port = typeof server === "number" ? server : server.port;
+      const token = typeof server === "number" ? "" : server.token || "";
+      const { timeout: _timeout, ...requestOptions } = options;
+      req = makeRequest({
+        host: "127.0.0.1",
+        port,
+        ...requestOptions,
+        headers: { ...(token ? { "x-doc-review-token": token } : {}), ...(options.headers || {}) },
+      });
+      req.on("response", onResponse);
+      req.on("error", onError);
+      req.on("close", onRequestClose);
+      signal?.addEventListener("abort", onAbort, { once: true });
+      if (expires !== null) armTimer();
+      if (done) return;
+      if (body) req.write(JSON.stringify(body));
+      req.end();
+    } catch (err) {
+      settle(err);
+    }
+  });
+}
+
+export function parseServerResponse(response) {
+  if (response.status !== 200) {
+    let detail = "";
+    try { detail = JSON.parse(response.raw).error || ""; } catch { /* HTTP status is sufficient. */ }
+    throw codedError(
+      `Doc-review server returned HTTP ${response.status}${detail ? `: ${detail}` : "."}`,
+      "SERVER_RESPONSE_ERROR",
+    );
+  }
+  try {
+    const parsed = JSON.parse(response.raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error();
+    return parsed;
+  } catch {
+    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) {
+  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(),
+    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");
+  }
+  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");
+  }
+  return batch;
+}
+
+export async function pollUntilDeadline({
+  target,
+  ackId = "",
+  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;
+    } 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.",
+        };
+      }
+      if (!isRecoverableTransportError(err)) throw err;
+      diagnostic(`Lost the connection (${err.message}); retrying.\n`);
+      try {
+        await deadline.sleep(Math.min(250 * 2 ** Math.min(failures++, 5), 5000));
+      } catch (sleepError) {
+        if (sleepError.code !== "POLL_DEADLINE") throw sleepError;
+      }
+    }
+  }
+}

package/src/positioning.js

@@ -0,0 +1,107 @@
+const GAP = 12;
+
+export function visibleViewport(win = window) {
+  const viewport = win.visualViewport;
+  return viewport
+    ? { left: viewport.offsetLeft, top: viewport.offsetTop, width: viewport.width, height: viewport.height }
+    : { left: 0, top: 0, width: win.innerWidth, height: win.innerHeight };
+}
+
+export function lastVisibleRect(rects) {
+  if (!Array.isArray(rects)) return null;
+  for (let index = rects.length - 1; index >= 0; index -= 1) {
+    const rect = rects[index];
+    if (rect && rect.width >= 0 && rect.height >= 0) return rect;
+  }
+  return null;
+}
+
+const clamp = (value, min, max) => Math.max(min, Math.min(max, value));
+
+function frameRectToChrome(rect, frameRect) {
+  return {
+    left: frameRect.left + rect.left,
+    right: frameRect.left + rect.right,
+    top: frameRect.top + rect.top,
+    bottom: frameRect.top + rect.bottom,
+  };
+}
+
+export function placeContextualSurface(geometry, options) {
+  const {
+    frameRect,
+    viewport,
+    surfaceWidth = 340,
+    surfaceHeight = 220,
+    narrow = false,
+    toolbarHeight = 48,
+  } = options;
+  const bottomSheet = () => ({
+    kind: "sheet",
+    left: viewport.left,
+    top: viewport.top + viewport.height - Math.min(surfaceHeight, viewport.height),
+    width: viewport.width,
+  });
+  if (!geometry || geometry.relation === "unavailable" || !geometry.clip) return { kind: "hidden" };
+  if (narrow) return bottomSheet();
+  const clip = frameRectToChrome(geometry.clip, frameRect);
+  const minLeft = viewport.left + GAP;
+  const maxLeft = viewport.left + viewport.width - surfaceWidth - GAP;
+  const viewportMinTop = viewport.top + toolbarHeight + GAP;
+  const minTop = Math.max(viewportMinTop, clip.top + GAP);
+  const maxTop = viewport.top + viewport.height - surfaceHeight - GAP;
+  const clipBottomTop = clip.bottom - surfaceHeight - GAP;
+  const horizontal = Number.isFinite(geometry.horizontal)
+    ? frameRect.left + geometry.horizontal
+    : clip.left;
+  const edgeLeft = clamp(horizontal + GAP, minLeft, maxLeft);
+
+  if (geometry.relation === "above") {
+    return { kind: "edge-top", left: edgeLeft, top: minTop, width: surfaceWidth };
+  }
+  if (geometry.relation === "below") {
+    return {
+      kind: "edge-bottom",
+      left: edgeLeft,
+      top: Math.max(viewportMinTop, Math.min(maxTop, clipBottomTop)),
+      width: surfaceWidth,
+    };
+  }
+
+  const target = lastVisibleRect(geometry.rects);
+  if (!target) return { kind: "hidden" };
+  const rect = frameRectToChrome(target, frameRect);
+  const attachedMaxTop = Math.min(maxTop, clipBottomTop);
+  const clampTop = (top) => clamp(top, minTop, Math.max(minTop, attachedMaxTop));
+  const candidates = [
+    { left: rect.right + GAP, top: clampTop(rect.bottom - surfaceHeight) },
+    { left: rect.left - surfaceWidth - GAP, top: clampTop(rect.bottom - surfaceHeight) },
+    { left: clamp(rect.left, minLeft, maxLeft), top: rect.bottom + GAP },
+    { left: clamp(rect.left, minLeft, maxLeft), top: rect.top - surfaceHeight - GAP },
+  ];
+  const fit = candidates.find((candidate) =>
+    candidate.left >= minLeft &&
+    candidate.left <= maxLeft &&
+    candidate.top >= minTop &&
+    candidate.top <= attachedMaxTop &&
+    candidate.left + surfaceWidth <= Math.min(viewport.left + viewport.width - GAP, clip.right) &&
+    candidate.top + surfaceHeight <= clip.bottom
+  );
+  const fallback = fit || {
+    left: clamp(rect.right + GAP, minLeft, maxLeft),
+    top: clampTop(rect.top),
+  };
+  return { kind: "attached", ...fallback, width: surfaceWidth };
+}
+
+export function alignedCardPosition(rects, { frameRect, viewport, width = 300, height = 180 }) {
+  const target = lastVisibleRect(rects);
+  if (!target) return null;
+  const top = frameRect.top + target.top;
+  const right = frameRect.left + target.right;
+  if (top < frameRect.top || top > frameRect.bottom || right < frameRect.left || right > frameRect.right) return null;
+  return {
+    left: Math.max(viewport.left + 12, Math.min(viewport.left + viewport.width - width - 12, right + 12)),
+    top: Math.max(viewport.top + 12, Math.min(viewport.top + viewport.height - height - 12, top)),
+  };
+}

package/src/review-mode.js

@@ -0,0 +1,59 @@
+export const REVIEW_MODES = Object.freeze(["view", "edit"]);
+
+export function normalizeReviewMode(mode) {
+  return mode === "edit" ? "edit" : "view";
+}
+
+export function savePolicyForPage(page) {
+  return page && (page.kind === "url" || page.markdown || page.feedbackOnly)
+    ? "feedback-only"
+    : "writable";
+}
+
+export function reviewConfiguration(page, mode) {
+  return {
+    mode: normalizeReviewMode(mode),
+    savePolicy: savePolicyForPage(page),
+  };
+}
+
+export function applyBodyReviewMode(body, mode) {
+  const normalized = normalizeReviewMode(mode);
+  if (normalized === "edit") {
+    if (body.getAttribute("contenteditable") !== "true") body.setAttribute("contenteditable", "true");
+    if (body.getAttribute("spellcheck") !== "false") body.setAttribute("spellcheck", "false");
+  } else {
+    if (body.hasAttribute("contenteditable")) body.removeAttribute("contenteditable");
+    if (body.hasAttribute("spellcheck")) body.removeAttribute("spellcheck");
+  }
+  return normalized;
+}
+
+/** Keep the active mode intact when an application hydrates and rewrites body attributes. */
+export function keepBodyInReviewMode(body, initialMode = "view") {
+  let mode = normalizeReviewMode(initialMode);
+  let applying = false;
+  const enforce = () => {
+    if (applying) return;
+    applying = true;
+    applyBodyReviewMode(body, mode);
+    applying = false;
+  };
+  const Observer = body.ownerDocument.defaultView.MutationObserver;
+  const observer = new Observer(enforce);
+  observer.observe(body, { attributes: true, attributeFilter: ["contenteditable", "spellcheck"] });
+  enforce();
+  return {
+    get mode() {
+      return mode;
+    },
+    setMode(nextMode) {
+      mode = normalizeReviewMode(nextMode);
+      enforce();
+      return mode;
+    },
+    disconnect() {
+      observer.disconnect();
+    },
+  };
+}