@erdemtuna/doc-review 0.9.0 → 0.10.0

package/lib/icons.js

@@ -0,0 +1,249 @@
+// 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 → lib}/markdown.js

@@ -1,8 +1,6 @@
 import path from "node:path";
 import { marked, Renderer } from "marked";
-
 export const isMarkdown = (file) => /\.(md|markdown)$/i.test(file);
-
 /**
  * Readable defaults for rendered Markdown. This HTML is a viewing surface
  * only — it is never written back to disk, so the styling can be opinionated.
@@ -35,45 +33,46 @@ const STYLE = `
   img { max-width: 100%; height: auto; }
   hr { border: none; border-top: 1px solid #eceae3; margin: 2.2em 0; }
 `;
-
-const escapeHtml = (value) =>
-  String(value)
+const escapeHtml = (value) => String(value)
     .replace(/&/g, "&")
     .replace(/</g, "&lt;")
     .replace(/>/g, "&gt;");
-
 function safeUrl(value, { image = false } = {}) {
-  const url = String(value || "").trim();
-  const probe = url.replace(/[\u0000-\u0020\u007f]+/g, "");
-  const match = /^([a-z][a-z0-9+.-]*):/i.exec(probe);
-  if (!match) return url;
-  const scheme = match[1].toLowerCase();
-  if (scheme === "http" || scheme === "https") return url;
-  if (!image && scheme === "mailto") return url;
-  if (image && /^data:image\/(?:avif|gif|jpe?g|png|webp);base64,/i.test(probe)) return url;
-  return null;
+    const url = String(value || "").trim();
+    const probe = url.replace(/[\u0000-\u0020\u007f]+/g, "");
+    const match = /^([a-z][a-z0-9+.-]*):/i.exec(probe);
+    if (!match)
+        return url;
+    const scheme = match[1].toLowerCase();
+    if (scheme === "http" || scheme === "https")
+        return url;
+    if (!image && scheme === "mailto")
+        return url;
+    if (image && /^data:image\/(?:avif|gif|jpe?g|png|webp);base64,/i.test(probe))
+        return url;
+    return null;
 }
-
 // Markdown can contain arbitrary HTML. Show that source as text so event
 // handlers, embeds, SVG, and future browser features can never become active.
 const INERT_RENDERER = new Renderer();
 INERT_RENDERER.html = ({ text }) => escapeHtml(text);
 INERT_RENDERER.link = function (token) {
-  const href = safeUrl(token.href);
-  if (!href) return this.parser.parseInline(token.tokens);
-  return Renderer.prototype.link.call(this, { ...token, href });
+    const href = safeUrl(token.href);
+    if (!href)
+        return this.parser.parseInline(token.tokens);
+    return Renderer.prototype.link.call(this, { ...token, href });
 };
 INERT_RENDERER.image = function (token) {
-  const href = safeUrl(token.href, { image: true });
-  if (!href) return escapeHtml(token.text || "");
-  return Renderer.prototype.image.call(this, { ...token, href });
+    const href = safeUrl(token.href, { image: true });
+    if (!href)
+        return escapeHtml(token.text || "");
+    return Renderer.prototype.image.call(this, { ...token, href });
 };
-
 /** Render a Markdown file into a standalone review page. */
 export function renderMarkdownPage(mdText, file) {
-  const body = marked.parse(mdText, { gfm: true, async: false, renderer: INERT_RENDERER });
-  const title = path.basename(file);
-  return `<!DOCTYPE html>
+    const body = marked.parse(mdText, { gfm: true, async: false, renderer: INERT_RENDERER });
+    const title = path.basename(file);
+    return `<!DOCTYPE html>
 <html lang="en">
 <head>
 <meta charset="utf-8">

package/lib/paths.js

@@ -0,0 +1,83 @@
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import path from "node:path";
+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 = 17;
+export function serverProtocolMatches(protocol) {
+    return Number(protocol) === SERVER_PROTOCOL;
+}
+export function stateDir() {
+    const override = process.env.DOC_REVIEW_STATE_DIR;
+    return override ? path.resolve(override) : path.join(homedir(), ".doc-review");
+}
+export function statePath() {
+    return path.join(stateDir(), "state.json");
+}
+export function serverPath() {
+    return path.join(stateDir(), "server.json");
+}
+export function serverLockPath() {
+    return path.join(stateDir(), "server.lock");
+}
+export function ensureStateDir() {
+    // Comments and the server token live here; keep it private to the user.
+    fs.mkdirSync(stateDir(), { recursive: true, mode: 0o700 });
+}
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+/**
+ * Return a canonical loopback URL, or null when the input is a filesystem path.
+ * HTTP-looking non-loopback targets fail loudly instead of becoming odd paths.
+ */
+export function localUrl(target) {
+    const value = String(target || "");
+    if (!/^https?:\/\//i.test(value))
+        return null;
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        throw new Error(`Invalid localhost URL: ${value}`);
+    }
+    if (!LOOPBACK_HOSTS.has(parsed.hostname)) {
+        throw new Error("doc-review URL support is limited to localhost, 127.0.0.1, and [::1].");
+    }
+    if (parsed.username || parsed.password) {
+        throw new Error("Localhost review URLs cannot contain credentials.");
+    }
+    parsed.hash = "";
+    return parsed.href;
+}
+/** Canonical identity for a page: the real path of the file on disk. */
+export function pageKey(file) {
+    let real = path.resolve(file);
+    try {
+        real = fs.realpathSync(real);
+    }
+    catch {
+        // File may not exist yet; the resolved path is still a stable identity.
+    }
+    return createHash("sha256").update(real).digest("hex").slice(0, 16);
+}
+/** Stable identity for either an existing file target or a localhost URL. */
+export function targetKey(target) {
+    const url = localUrl(target);
+    if (!url)
+        return pageKey(target);
+    return createHash("sha256").update(`url:${url}`).digest("hex").slice(0, 16);
+}
+export function canonicalTarget(target) {
+    const url = localUrl(target);
+    return url ? { kind: "url", value: url } : { kind: "file", value: realFile(target) };
+}
+export function realFile(file) {
+    const resolved = path.resolve(file);
+    try {
+        return fs.realpathSync(resolved);
+    }
+    catch {
+        return resolved;
+    }
+}

package/lib/poll-transport.js

@@ -0,0 +1,220 @@
+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;
+            }
+        }
+    }
+}