@erdemtuna/doc-review 0.9.0 → 0.11.0

package/lib/view-identity.js

@@ -0,0 +1,112 @@
+const MAX_TABS = 32;
+const MAX_ID = 256;
+const unknown = (reason) => ({ version: 1, status: "unverified", tabs: [], reason });
+export function normalizeView(value) {
+    if (value === undefined || value === null)
+        return unknown("View identity was not recorded.");
+    const invalid = () => { throw Object.assign(new Error("Invalid captured view identity."), { code: "INVALID_REVISION", status: 400 }); };
+    if (value.version !== 1 || !["identified", "unverified"].includes(value.status) ||
+        !Array.isArray(value.tabs) || value.tabs.length > MAX_TABS)
+        invalid();
+    if (value.status === "unverified") {
+        if (value.tabs.length || (value.reason !== undefined && (typeof value.reason !== "string" || value.reason.length > 500)))
+            invalid();
+        return unknown(value.reason || "View identity could not be verified.");
+    }
+    if (!value.tabs.length)
+        invalid();
+    const groups = new Set();
+    const tabs = value.tabs.map((tab) => {
+        if (!tab || typeof tab !== "object")
+            invalid();
+        for (const key of ["groupId", "tabId", "panelId", "label"]) {
+            if (typeof tab[key] !== "string" || !tab[key] || tab[key].length > MAX_ID)
+                invalid();
+        }
+        if (groups.has(tab.groupId))
+            invalid();
+        groups.add(tab.groupId);
+        return { groupId: tab.groupId, tabId: tab.tabId, panelId: tab.panelId, label: tab.label };
+    }).sort((a, b) => a.groupId.localeCompare(b.groupId));
+    return { version: 1, status: "identified", tabs };
+}
+function viewKey(view) {
+    const normalized = normalizeView(view);
+    return JSON.stringify([normalized.status, normalized.tabs.map(({ groupId, tabId, panelId }) => [groupId, tabId, panelId])]);
+}
+export function sameObservedView(before, after) {
+    return viewKey(before) === viewKey(after);
+}
+export function compareCapturedViews(before, after) {
+    const left = normalizeView(before);
+    const right = normalizeView(after);
+    if (left.status === "identified") {
+        if (right.status === "identified" && sameObservedView(left, right)) {
+            return { status: "matched", message: `Matching visible view: ${left.tabs.map((tab) => tab.label).join(" / ")}.` };
+        }
+        return {
+            status: "mismatch",
+            message: `Return to ${left.tabs.map((tab) => tab.label).join(" / ")} to capture the result.${right.status === "unverified" ? " The current tab identity could not be verified." : ""}`,
+        };
+    }
+    return { status: "unverified", message: "Visible content only; matching view not verified." };
+}
+export function observeView(document) {
+    const started = Date.now();
+    let visited = 0;
+    let limited = false;
+    const visible = (element) => {
+        for (let node = element; node; node = node.parentElement) {
+            if (++visited > 5000 || Date.now() - started > 500) {
+                limited = true;
+                return false;
+            }
+            if (node.hidden || node.getAttribute("aria-hidden") === "true" || node.hasAttribute("data-eh-ui"))
+                return false;
+            const style = document.defaultView.getComputedStyle(node);
+            if (style.display === "none" || style.visibility === "hidden")
+                return false;
+        }
+        return true;
+    };
+    const uniqueId = (element) => {
+        if (!element?.id || element.id.length > MAX_ID)
+            return false;
+        const escaped = element.id.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/[\n\r\f]/g, "");
+        return document.querySelectorAll(`[id="${escaped}"]`).length === 1;
+    };
+    const candidates = document.querySelectorAll('[role="tablist"]');
+    if (candidates.length > MAX_TABS)
+        return unknown("Too many tab groups to identify reliably.");
+    const groups = [...candidates].filter(visible);
+    if (limited)
+        return unknown("View identity observation exceeded its limits.");
+    if (!groups.length)
+        return unknown("No reliably identifiable tab groups were found.");
+    if (groups.length > MAX_TABS)
+        return unknown("Too many tab groups to identify reliably.");
+    const tabs = [];
+    for (const group of groups) {
+        const members = [...group.querySelectorAll('[role="tab"]')].filter((tab) => tab.closest('[role="tablist"]') === group);
+        if (members.length > 128 || Date.now() - started > 500)
+            return unknown("View identity observation exceeded its limits.");
+        const selected = members.filter((tab) => tab.getAttribute("aria-selected") === "true");
+        if (selected.length !== 1)
+            return unknown("A tab group does not have exactly one selected tab.");
+        const tab = selected[0];
+        const panelId = tab.getAttribute("aria-controls");
+        const panel = panelId && document.getElementById(panelId);
+        if (!visible(tab) || !uniqueId(tab) || !uniqueId(panel) || panel.getAttribute("role") !== "tabpanel" || !visible(panel)) {
+            return unknown("Selected tabs and visible panels do not have unique stable identifiers.");
+        }
+        // A complete set of authored tab IDs identifies an otherwise unnamed tablist.
+        if (!members.length || members.some((member) => !uniqueId(member)))
+            return unknown("Tab identifiers are incomplete.");
+        const groupId = uniqueId(group) ? `id:${group.id}` : `tabs:${JSON.stringify(members.map((member) => member.id).sort())}`;
+        if (groupId.length > MAX_ID)
+            return unknown("Tab group identity exceeds the capture limit.");
+        const label = (tab.getAttribute("aria-label") || tab.textContent || tab.id).replace(/\s+/g, " ").trim().slice(0, MAX_ID);
+        tabs.push({ groupId, tabId: tab.id, panelId, label: label || tab.id });
+    }
+    return normalizeView({ version: 1, status: "identified", tabs });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@erdemtuna/doc-review",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Review and edit agent-generated files and localhost pages in the browser, then send the whole batch back to your agent.",
   "author": "Peter Yang",
   "homepage": "https://github.com/erdemtuna/doc-review#readme",
@@ -13,22 +13,37 @@
   },
   "type": "module",
   "bin": {
-    "doc-review": "src/cli.js"
+    "doc-review": "lib/cli.js"
   },
   "files": [
-    "src",
+    "lib",
     "README.md",
     "LICENSE"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=24.21.0"
   },
+  "packageManager": "npm@12.0.2",
   "scripts": {
+    "build": "node scripts/build.js",
+    "typecheck": "tsc -p tsconfig.shared.json && tsc -p tsconfig.browser.json && tsc -p tsconfig.node.json && tsc -p tsconfig.ui.json && tsc -p tsconfig.ui-test.json && tsc -p tsconfig.tooling.json",
+    "prepack": "node scripts/build.js",
     "test": "npm run test:unit",
-    "test:unit": "node --test",
-    "test:browser": "playwright test",
-    "test:all": "npm run test:unit && npm run test:browser",
-    "start": "node src/cli.js"
+    "test:unit": "npm run build && node --test test/*.test.js && npm run test:ui",
+    "test:ui": "vitest run",
+    "preview:ui": "node scripts/ui-preview.js",
+    "preview:recovery": "node scripts/ui-preview.js --recovery",
+    "preview:shell": "npm run build && node scripts/shell-preview.js",
+    "preview:review": "npm run build && node scripts/migration-review.js",
+    "media:readme": "npm run build && node scripts/capture-readme.js",
+    "media:preview": "node scripts/preview-readme.js",
+    "test:browser": "npm run build && playwright test",
+    "test:package": "node scripts/package-smoke.js",
+    "test:package:browser": "node scripts/package-smoke.js --browser",
+    "test:all": "npm run build && node --test test/*.test.js && npm run test:ui && playwright test && npm run test:package",
+    "browser:install": "playwright install chromium",
+    "browser:install:ci": "playwright install --with-deps chromium",
+    "start": "npm run build && node lib/cli.js"
   },
   "keywords": [
     "html",
@@ -48,13 +63,34 @@
     "registry": "https://registry.npmjs.org"
   },
   "devDependencies": {
-    "@playwright/test": "^1.62.1",
-    "jsdom": "^29.1.1",
-    "lucide-static": "^1.34.0"
+    "@playwright/test": "1.63.0",
+    "@tailwindcss/vite": "4.3.3",
+    "@testing-library/dom": "10.4.1",
+    "@testing-library/jest-dom": "7.0.1",
+    "@testing-library/react": "16.3.3",
+    "@testing-library/user-event": "14.6.7",
+    "@types/node": "24.10.4",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "@vitejs/plugin-react": "6.1.1",
+    "class-variance-authority": "0.7.1",
+    "clsx": "2.1.1",
+    "jsdom": "30.0.1",
+    "lucide-static": "1.44.0",
+    "radix-ui": "1.6.7",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "shadcn": "4.21.0",
+    "tailwind-merge": "3.6.0",
+    "tailwindcss": "4.3.3",
+    "tw-animate-css": "1.4.0",
+    "typescript": "6.0.3",
+    "vite": "8.3.0",
+    "vitest": "5.0.0"
   },
   "dependencies": {
-    "diff": "^9.0.0",
-    "marked": "^18.0.7",
-    "parse5": "^8.0.1"
+    "diff": "9.0.0",
+    "marked": "18.0.12",
+    "parse5": "8.0.1"
   }
 }

package/src/anchor-text.js

@@ -1,160 +0,0 @@
-/**
- * Quote-with-context anchoring, in the spirit of the W3C TextQuoteSelector.
- *
- * These functions are pure string maths so they can be unit-tested in Node and
- * shipped verbatim to the browser, where the DOM half of anchoring lives.
- */
-
-export const CONTEXT_PAD = 32;
-
-/** Capture `quote` plus surrounding context so it can be re-found after edits. */
-export function buildContext(text, start, end, pad = CONTEXT_PAD) {
-  return {
-    prefix: text.slice(Math.max(0, start - pad), start),
-    quote: text.slice(start, end),
-    suffix: text.slice(end, Math.min(text.length, end + pad)),
-  };
-}
-
-function commonSuffixLength(a, b) {
-  let n = 0;
-  while (n < a.length && n < b.length && a[a.length - 1 - n] === b[b.length - 1 - n]) n += 1;
-  return n;
-}
-
-function commonPrefixLength(a, b) {
-  let n = 0;
-  while (n < a.length && n < b.length && a[n] === b[n]) n += 1;
-  return n;
-}
-
-function occurrences(text, quote) {
-  const found = [];
-  let at = text.indexOf(quote);
-  while (at !== -1) {
-    found.push(at);
-    at = text.indexOf(quote, at + 1);
-  }
-  return found;
-}
-
-function bestHit(text, hits, quote, prefix, suffix) {
-  let best = hits[0];
-  let bestScore = -1;
-  for (const at of hits) {
-    const before = text.slice(Math.max(0, at - prefix.length), at);
-    const after = text.slice(at + quote.length, at + quote.length + suffix.length);
-    const score = commonSuffixLength(prefix, before) + commonPrefixLength(suffix, after);
-    if (score > bestScore) {
-      bestScore = score;
-      best = at;
-    }
-  }
-  return { at: best, score: bestScore };
-}
-
-const collapse = (s) => String(s || "").replace(/\s+/g, " ");
-
-/** Collapse whitespace runs, keeping a map from each kept char to its original index. */
-function collapseWithMap(text) {
-  let flat = "";
-  const map = [];
-  let pendingWs = -1;
-  for (let i = 0; i < text.length; i += 1) {
-    if (/\s/.test(text[i])) {
-      if (pendingWs === -1) pendingWs = i;
-      continue;
-    }
-    if (pendingWs !== -1 && flat) {
-      flat += " ";
-      map.push(pendingWs);
-    }
-    pendingWs = -1;
-    flat += text[i];
-    map.push(i);
-  }
-  return { flat, map };
-}
-
-/**
- * Locate `ctx.quote` in `text`, using prefix/suffix to disambiguate repeats.
- * Returns `{ start, end, exact }` or null when the quote is gone entirely.
- */
-export function findQuote(text, ctx) {
-  const quote = ctx && ctx.quote;
-  if (!quote) return null;
-
-  const hits = occurrences(text, quote);
-  if (hits.length === 1) {
-    return { start: hits[0], end: hits[0] + quote.length, exact: true };
-  }
-  if (hits.length > 1) {
-    const { at, score } = bestHit(text, hits, quote, ctx.prefix || "", ctx.suffix || "");
-    return { start: at, end: at + quote.length, exact: score > 0 };
-  }
-
-  // Reformatting (a prettier run, an agent rewrite) reflows whitespace without
-  // changing any words. Match again on whitespace-collapsed text and map the
-  // hit back to real offsets, so those comments survive instead of orphaning.
-  const { flat, map } = collapseWithMap(text);
-  const flatQuote = collapse(quote).trim();
-  if (!flatQuote || !map.length) return null;
-  const flatHits = occurrences(flat, flatQuote);
-  if (!flatHits.length) return null;
-  const { at } = bestHit(flat, flatHits, flatQuote, collapse(ctx.prefix || ""), collapse(ctx.suffix || ""));
-  return { start: map[at], end: map[at + flatQuote.length - 1] + 1, exact: false };
-}
-
-/** Collapse runs of whitespace for display in a comment card. */
-export function tidy(text, limit = 0) {
-  const flat = String(text == null ? "" : text)
-    .replace(/\s+/g, " ")
-    .trim();
-  if (!limit || flat.length <= limit) return flat;
-  return `${flat.slice(0, limit - 1).trimEnd()}…`;
-}
-
-function graphemes(text) {
-  if (typeof Intl?.Segmenter === "function") {
-    const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
-    return [...segmenter.segment(text)].map(({ segment }) => segment);
-  }
-  // Array.from is deterministic and, unlike string slicing, never splits a
-  // surrogate pair. Older engines may split a multi-code-point grapheme.
-  return Array.from(text);
-}
-
-function nearbyHeadBoundary(parts, ideal) {
-  for (let index = ideal; index >= Math.max(1, ideal - 8); index -= 1) {
-    if (/^\s$/u.test(parts[index - 1])) return index - 1;
-  }
-  return ideal;
-}
-
-function nearbyTailBoundary(parts, ideal) {
-  for (let index = ideal; index < Math.min(parts.length - 1, ideal + 8); index += 1) {
-    if (/^\s$/u.test(parts[index])) return index + 1;
-  }
-  return ideal;
-}
-
-/**
- * Collapse whitespace and preserve both ends of a long quote. `limit` counts
- * grapheme clusters, including the ellipsis.
- */
-export function tidyMiddle(text, limit = 0) {
-  const flat = String(text == null ? "" : text)
-    .replace(/\s+/g, " ")
-    .trim();
-  if (!limit) return flat;
-  const parts = graphemes(flat);
-  if (parts.length <= limit) return flat;
-  if (limit <= 1) return "…";
-
-  const available = limit - 1;
-  const idealHead = Math.ceil(available * 0.6);
-  const idealTailStart = parts.length - (available - idealHead);
-  const headEnd = nearbyHeadBoundary(parts, idealHead);
-  const tailStart = nearbyTailBoundary(parts, idealTailStart);
-  return `${parts.slice(0, headEnd).join("").trimEnd()}…${parts.slice(tailStart).join("").trimStart()}`;
-}

package/src/atomic-write.js

@@ -1,53 +0,0 @@
-import crypto from "node:crypto";
-import fs from "node:fs";
-
-const RETRY_DELAYS_MS = [10, 20, 40, 80, 160];
-const TRANSIENT_RENAME_ERRORS = new Set(["EPERM", "EACCES", "EBUSY"]);
-const waitState = new Int32Array(new SharedArrayBuffer(4));
-
-// Keep Store transactions synchronous; rename backoff blocks for at most 310ms.
-const sleepSync = (ms) => Atomics.wait(waitState, 0, 0, ms);
-
-export function createAtomicWriter({ fileSystem = fs, sleep = sleepSync, report = console.error } = {}) {
-  return function atomicWrite(file, data) {
-    const tmp = `${file}.${process.pid}.${crypto.randomBytes(6).toString("hex")}.doc-review.tmp`;
-    let fd;
-    let created = false;
-    try {
-      fd = fileSystem.openSync(tmp, "wx");
-      created = true;
-      fileSystem.writeFileSync(fd, data);
-      fileSystem.closeSync(fd);
-      fd = undefined;
-      for (let attempt = 0; ; attempt += 1) {
-        try {
-          fileSystem.renameSync(tmp, file);
-          return;
-        } catch (err) {
-          if (!TRANSIENT_RENAME_ERRORS.has(err.code) || attempt === RETRY_DELAYS_MS.length) throw err;
-          sleep(RETRY_DELAYS_MS[attempt]);
-        }
-      }
-    } catch (err) {
-      if (fd !== undefined) {
-        try {
-          fileSystem.closeSync(fd);
-        } catch (cleanupError) {
-          report(`Could not close atomic-write temporary file ${tmp}: ${cleanupError.message}`);
-        }
-      }
-      if (created) {
-        try {
-          fileSystem.unlinkSync(tmp);
-        } catch (cleanupError) {
-          if (cleanupError.code !== "ENOENT") {
-            report(`Could not remove atomic-write temporary file ${tmp}: ${cleanupError.message}`);
-          }
-        }
-      }
-      throw err;
-    }
-  };
-}
-
-export const atomicWrite = createAtomicWriter();