@erdemtuna/doc-review 0.8.0 → 0.9.0

package/src/history-client.js

@@ -0,0 +1,104 @@
+/** A capture is valid only for the exact frame that answered the request. */
+export function sameRender(a, b) {
+  return !!a && !!b && a.key === b.key && a.renderId === b.renderId &&
+    a.generation === b.generation && !!a.renderId;
+}
+
+export function createCaptureRequests({ send, current, timeout = 6000 }) {
+  const pending = new Map();
+  let sequence = 0;
+  return {
+    request({ timeout: requestTimeout = timeout, signal } = {}) {
+      const identity = { ...current() };
+      if (signal?.aborted) return Promise.reject(captureError("CAPTURE_CANCELLED", "Capture cancelled"));
+      if (!identity.renderId || identity.loading) return Promise.reject(captureError("CAPTURE_NOT_READY", "The page is not ready to capture"));
+      const requestId = `capture-${++sequence}`;
+      return new Promise((resolve, reject) => {
+        const finish = (error, value) => {
+          if (!pending.has(requestId)) return;
+          pending.delete(requestId);
+          clearTimeout(timer);
+          signal?.removeEventListener("abort", abort);
+          if (error) reject(error);
+          else resolve(value);
+        };
+        const abort = () => finish(captureError("CAPTURE_CANCELLED", "Capture cancelled"));
+        const timer = setTimeout(() => finish(captureError("CAPTURE_TIMEOUT",
+          "The page did not confirm a stable capture. Recapture when it is ready.")), requestTimeout);
+        pending.set(requestId, { identity, finish });
+        signal?.addEventListener("abort", abort, { once: true });
+        try { send({ type: "eh:captureSnapshot", requestId, requireStable: true }); }
+        catch (error) { finish(error); }
+      });
+    },
+    receive(message) {
+      const request = pending.get(message.requestId);
+      if (!request) return false;
+      if (!sameRender(request.identity, current())) request.finish(captureError("CAPTURE_CHANGED", "The page changed during capture. Recapture the latest version."));
+      else if (message.error || !message.snapshot) request.finish(captureError(message.error?.code || "CAPTURE_UNAVAILABLE",
+        message.error?.message || message.error || "Semantic capture is unavailable"));
+      else request.finish(null, {
+        ...request.identity, semantic: message.snapshot, sourceHash: message.sourceHash,
+        semanticCapturedAt: Number.isFinite(message.capturedAt) ? message.capturedAt : undefined,
+        view: message.view,
+      });
+      return true;
+    },
+    cancel(reason = "The page changed during capture") {
+      for (const request of pending.values()) {
+        request.finish(captureError("CAPTURE_CANCELLED", reason));
+      }
+      pending.clear();
+    },
+    get size() { return pending.size; },
+  };
+}
+
+export function captureError(code, message) {
+  return Object.assign(new Error(message), { code });
+}
+
+export function draftCount({ compose, commentUi }, note = "") {
+  return Number(!!compose) + Number(!!commentUi?.edit) + Number(!!note.trim());
+}
+
+export function excerpt(value) {
+  if (typeof value === "string") return value;
+  if (!value) return "";
+  return String(value.text ?? value.excerpt ?? value.content ?? value.label ?? "");
+}
+
+export function changeKind(item) {
+  const kind = String(item.kind || item.type || "").toLowerCase();
+  return kind === "added" || kind === "removed" ? kind : "modified";
+}
+
+export function pendingCaptureTarget(round, key, readyAt) {
+  if (round?.feedbackStatus !== "acknowledged" || !(readyAt > 0)) return null;
+  return round.targets?.find((target) => target.key === key && !target.resultRevisionId &&
+    ["pending", "failed"].includes(target.capture?.status || target.captureStatus || "pending")) || null;
+}
+
+export function defaultHistoryRound(rounds) {
+  return rounds.find((round) => round.completedAt || round.captureStatus === "ready" ||
+    ["complete", "completed"].includes(round.status)) || rounds[0] || null;
+}
+
+export function comparisonFreshness(comparison, targetKey, current) {
+  if (targetKey !== current.key) return "Different page: this saved comparison does not describe the page open in Latest version.";
+  if (!current.ready || current.pendingReload || current.dirty) return "Latest version is unverified: reload or finish saving before comparing it with this captured result.";
+  if (current.kind === "url") {
+    return comparison.capturedSessionId === current.sessionId && comparison.capturedGeneration === current.generation
+      ? "Same live render generation; the current DOM is not verified against the captured result. Live content may have changed."
+      : "Latest live render is different or unverified. This historical comparison cannot identify exact targets on the live page.";
+  }
+  if (!comparison.sourceHash || !current.sourceHash) return "Latest source is unverified against this captured result.";
+  return comparison.sourceHash === current.sourceHash
+    ? "Latest file source matches the captured result. Runtime DOM changes are not verified by a source match."
+    : "Latest source is newer or different from the captured result. You are viewing a historical comparison.";
+}
+
+export function canJumpToCurrent(item, result, current) {
+  return item.confidence === "exact" && !!item.navigation?.selector && !item.unresolved && changeKind(item) !== "removed" &&
+    !!result?.renderId && sameRender(result, current);
+}

package/src/history-coordinator.js

@@ -0,0 +1,186 @@
+import { defaultHistoryRound } from "./history-client.js";
+
+const idOf = (round) => round?.roundId || round?.id;
+const retryDelays = [1000, 2000, 4000];
+
+export function transientCaptureError(error) {
+  return ["CAPTURE_TIMEOUT", "CAPTURE_NOT_READY", "CAPTURE_UNSTABLE", "CAPTURE_BUSY", "VIEW_CHANGED"].includes(error?.code) ||
+    [408, 429, 502, 503, 504].includes(error?.status) ||
+    (error instanceof TypeError && /fetch|network|load failed/i.test(error.message));
+}
+
+export function requireCaptureSuccess(result, key) {
+  if (result?.ok === true) return result;
+  throw Object.assign(new Error(result?.round?.targets?.find((target) => target.key === key)?.capture?.error ||
+    "Content capture is unavailable"), { code: "CAPTURE_UNAVAILABLE" });
+}
+
+/** One capture at a time; delayed/finished attempts never block other rounds. */
+export function createCaptureCoordinator({ candidates, ready, capture, now = Date.now,
+  setTimer = setTimeout, clearTimer = clearTimeout }) {
+  const attempts = new Map();
+  let timer = null;
+  let active = null;
+  let epoch = 0;
+  let stopped = false;
+  function tick() {
+    clearTimer(timer);
+    timer = null;
+    if (stopped || active || !ready()) return;
+    const jobs = candidates();
+    const job = jobs.find(({ id }) => {
+      const attempt = attempts.get(id);
+      return !attempt || (!attempt.done && attempt.due <= now());
+    });
+    if (!job) {
+      const due = jobs.map(({ id }) => attempts.get(id)).filter((entry) => entry && !entry.done)
+        .reduce((next, entry) => Math.min(next, entry.due), Infinity);
+      if (Number.isFinite(due)) timer = setTimer(tick, Math.max(0, due - now()));
+      return;
+    }
+    const attempt = attempts.get(job.id) || { count: 0, due: 0, done: false };
+    attempts.set(job.id, attempt);
+    attempt.count++;
+    const controller = new AbortController();
+    const started = epoch;
+    active = controller;
+    Promise.resolve().then(() => {
+      if (controller.signal.aborted) return;
+      return capture(job, controller.signal);
+    }).then(() => { attempt.done = true; }, (error) => {
+      if (transientCaptureError(error) && attempt.count <= retryDelays.length) {
+        attempt.due = now() + retryDelays[attempt.count - 1];
+      } else attempt.done = true;
+    }).finally(() => {
+      if (started !== epoch) return;
+      active = null;
+      tick();
+    });
+  }
+  return {
+    tick,
+    reset() {
+      epoch++;
+      active?.abort();
+      active = null;
+      clearTimer(timer);
+      timer = null;
+      attempts.clear();
+    },
+    stop() {
+      this.reset();
+      stopped = true;
+    },
+    get busy() { return !!active; },
+  };
+}
+
+export function historyPresentation({ loading, error, round, target, comparison = {}, failure }) {
+  const modes = ["content", "source"].filter((mode) => comparison[mode]?.available === true);
+  if (loading && !round) return { state: "loading", message: "Loading comparison…", modes };
+  if (error && !round) return { state: "failed", message: "History could not be loaded. Try again.", modes };
+  if (!round) return { state: "empty", message: "No review rounds yet. Send feedback to start.", modes };
+  if (modes.length) {
+    const partial = modes.length < 2 || !!target?.baselineUnavailable || !!target?.resultUnavailable;
+    return { state: partial ? "partial" : "available", modes,
+      message: modes.includes("content")
+        ? partial ? "Content available; some comparison coverage is missing." : "Comparison ready."
+        : "Source available. Content is pending or unavailable." };
+  }
+  if (failure || error || target?.capture?.status === "failed") {
+    return { state: "failed", message: "Content capture failed. Feedback is safe; retry when ready.", modes };
+  }
+  if (target?.capture?.status === "unavailable" || target?.resultRevisionId) {
+    return { state: "partial", message: "Comparison unavailable for these snapshots. Feedback is safe.", modes };
+  }
+  return { state: "waiting", message: round.feedbackStatus === "acknowledged"
+    ? "Waiting for a stable result snapshot. You can keep reviewing."
+    : "Waiting for the agent's result.", modes };
+}
+
+/** Fetch into local values, then publish atomically so selectors never relabel stale content. */
+export function createHistoryController({ request, changed = () => {}, refreshed = () => {} }) {
+  const state = {
+    rounds: [], selectedId: null, round: null, targetKey: null, mode: "content", preferredMode: null,
+    index: 0, loading: false, error: null, captureBusy: false, finalizing: false, failures: new Map(),
+  };
+  let revision = 0;
+  const targets = new Map();
+  async function refresh() {
+    const current = ++revision;
+    state.loading = true;
+    state.error = null;
+    if (state.round && (idOf(state.round) !== state.selectedId ||
+      !state.round.targets?.some((target) => target.key === state.targetKey && target.comparison))) state.round = null;
+    changed();
+    try {
+      const collection = await request("");
+      if (current !== revision) return false;
+      state.rounds = collection.rounds || [];
+      if (!state.rounds.some((round) => idOf(round) === state.selectedId)) {
+        state.selectedId = idOf(defaultHistoryRound(state.rounds)) || null;
+      }
+      const selectedId = state.selectedId;
+      let round = null;
+      let targetKey = state.targetKey || targets.get(selectedId);
+      if (selectedId) {
+        const detail = await request(`/${selectedId}`);
+        if (current !== revision) return false;
+        round = detail.round || detail;
+        const summary = state.rounds.find((item) => idOf(item) === selectedId);
+        for (const target of round.targets || []) {
+          target.filename ||= summary?.targets?.find((item) => item.key === target.key)?.filename;
+        }
+        const target = round.targets?.find((item) => item.key === targetKey) || round.targets?.[0];
+        targetKey = target?.key || null;
+        if (target) {
+          const results = await Promise.allSettled(["content", "source"].map((mode) =>
+            request(`/${selectedId}/compare?key=${encodeURIComponent(target.key)}&mode=${mode}`)));
+          if (current !== revision) return false;
+          target.comparison = Object.fromEntries(["content", "source"].map((mode, index) =>
+            [mode, results[index].status === "fulfilled" ? results[index].value
+              : { available: false, counts: null, reason: results[index].reason.message }]));
+          if (results.every((result) => result.status === "rejected")) state.error = results[0].reason;
+        }
+      }
+      state.round = round;
+      state.targetKey = targetKey;
+      if (selectedId) targets.set(selectedId, targetKey);
+      state.loading = false;
+      changed();
+      refreshed();
+      return true;
+    } catch (error) {
+      if (current !== revision) return false;
+      state.error = error;
+      state.loading = false;
+      changed();
+      return false;
+    }
+  }
+  return {
+    state, refresh,
+    selectRound(id) {
+      state.selectedId = id;
+      state.targetKey = targets.get(id) || null;
+      state.index = 0;
+      return refresh();
+    },
+    selectTarget(key) { state.targetKey = key; state.index = 0; return refresh(); },
+    cancel() { revision++; state.loading = false; },
+  };
+}
+
+/** Optional capture cannot veto delivery; a failed refresh cannot masquerade as failed Send. */
+export async function deliverFeedback({ save, capture, deliver, committed, refresh }) {
+  await save();
+  let snapshot = null;
+  let captureFailure = null;
+  try { snapshot = await capture(); } catch (error) { captureFailure = error; }
+  await deliver(snapshot);
+  committed();
+  let refreshFailure = null;
+  try { if (await refresh() === false) refreshFailure = new Error("History could not be refreshed"); }
+  catch (error) { refreshFailure = error; }
+  return { captureFailure, refreshFailure };
+}

package/src/history-policy.js

@@ -0,0 +1,43 @@
+import { COMPLETED_ROUNDS_TO_KEEP, isRevisionId } from "./revision-schema.js";
+
+function references(value, out = new Set()) {
+  if (isRevisionId(value)) out.add(value);
+  else if (Array.isArray(value)) for (const item of value) references(item, out);
+  else if (value && typeof value === "object") for (const item of Object.values(value)) references(item, out);
+  return out;
+}
+
+export function unsentRevisionReferences(data) {
+  const out = new Set();
+  for (const page of Object.values(data.pages || {})) {
+    references(page.comments, out);
+    references(page.edits, out);
+    references(page.revisionRefs, out);
+  }
+  return out;
+}
+
+export function historyRevisionReferences(data) {
+  const out = unsentRevisionReferences(data);
+  references(data.histories, out);
+  references(data.batches, out);
+  return out;
+}
+
+export function retainHistory(data) {
+  const pinned = unsentRevisionReferences(data);
+  let changed = false;
+  for (const history of Object.values(data.histories || {})) {
+    const completed = history.rounds
+      .filter((round) => round.completedAt)
+      .sort((a, b) => b.completedAt - a.completedAt || b.ordinal - a.ordinal);
+    const keep = new Set(completed.slice(0, COMPLETED_ROUNDS_TO_KEEP).map((round) => round.roundId));
+    const rounds = history.rounds.filter((round) =>
+      !round.completedAt || keep.has(round.roundId) || [...references(round.targets)].some((id) => pinned.has(id)));
+    if (rounds.length !== history.rounds.length) {
+      history.rounds = rounds;
+      changed = true;
+    }
+  }
+  return changed;
+}