@dev-loops/core 0.8.0 → 0.9.0

package/src/loop/ui-review-diagnose.mjs

@@ -0,0 +1,291 @@
+/**
+ * Diagnose + anchor for the ui_review route (Stage 3).
+ *
+ * Consumes the structured captured-failures feed from the drive stage and maps
+ * each failure — exception + JS stack or server-log traceback context — to a
+ * source location (the top in-repo stack frame), then to a diff line on the PR
+ * head so the poster stage can anchor an inline comment on a real changed line.
+ *
+ * This module is PURE: the diff text and the drive result are inputs. The thin
+ * CLI wires the real IO (loop info for PR state + the PR diff fetch).
+ *
+ * Contract: a failure is NEVER silently dropped. One that has no source
+ * location, whose file is not in the diff, whose line is not on a changed diff
+ * line, or whose file maps ambiguously to more than one changed file, is
+ * RETAINED as a finding flagged non-anchorable (with a stated reason) so the
+ * poster body-attaches it instead of inlining.
+ *
+ * Out of scope (later stages): review posting, artifact publishing, auto-fixing.
+ */
+
+const RIGHT = "RIGHT";
+
+/** Severity ordering for the ranked findings list. Unknown severities sort last
+ * but before nothing — a finding is never dropped for an unrecognized severity. */
+const SEVERITY_RANK = Object.freeze({ "must-fix": 0, note: 1 });
+const severityRank = (s) => (s in SEVERITY_RANK ? SEVERITY_RANK[s] : 2);
+
+/** Frames whose file matches a vendor/framework/runtime marker are NOT in-repo:
+ * the diagnosis anchors the change's own code, not a dependency's internals. The
+ * default is deliberately conservative — a project with an unusual layout injects
+ * its own predicate rather than loosening this shared default. */
+const VENDOR_FRAME = /node_modules|[/\\]gems[/\\]|[/\\]vendor[/\\]|\bwebpack:\/\/|^node:|[/\\]ruby[/\\]|[/\\]dist-packages[/\\]/u;
+
+/** Default in-repo predicate: a non-empty file path that is not a vendor frame. */
+export function isInRepoFrame(file) {
+  return typeof file === "string" && file.length > 0 && !VENDOR_FRAME.test(file);
+}
+
+/** Extract the exception type + message from stack/traceback text. Matches the
+ * first exception token and the text that follows it: a `SomethingError`/
+ * `SomethingException`-suffixed name (JS `TypeError: msg`, Ruby `NoMethodError
+ * (msg)`, Python/dotted `django.core.exceptions.ValidationError: msg`) OR a Ruby
+ * `::`-namespaced constant like `ActiveRecord::RecordNotFound` /
+ * `Mongoid::Errors::DocumentNotFound`, captured whole. The `::` alternative
+ * requires at least one namespace segment so it signals a class, not an
+ * arbitrary identifier. Returns nulls when no recognizable exception name is
+ * present. */
+export function parseException(text = "") {
+  const m = String(text).match(/([A-Z]\w*(?:::[A-Z]\w*)+|[A-Za-z_][\w.]*(?:Error|Exception))\b[:\s(]*([^\n)]*)/u);
+  if (!m) return { type: null, message: null };
+  const message = m[2].trim();
+  return { type: m[1], message: message.length > 0 ? message : null };
+}
+
+/** Parse a single stack/traceback line into `{file, line}` or null. Tries the
+ * three shapes the drive feed can carry: Python `File "path", line N`, JS
+ * `at ... (file:line:col)`, then a generic `path.ext:line` (Ruby, and JS frames
+ * without an `at` prefix). */
+function extractFrameFromLine(line) {
+  let m = line.match(/File "([^"]+)", line (\d+)/u);
+  if (m) return { file: m[1], line: Number(m[2]) };
+  // The file capture excludes only whitespace/parens (not `:`) and is lazy, so a
+  // served URL (`http://host:3000/assets/x.js`) is captured whole up to the
+  // trailing `:line:col` — normalizeFrameFile then strips the scheme/authority.
+  m = line.match(/\bat\s+(?:.*\()?([^\s()]+?):(\d+)(?::\d+)?\)?\s*$/u);
+  if (m) return { file: m[1], line: Number(m[2]) };
+  m = line.match(/([^\s():]+\.[A-Za-z0-9_]+):(\d+)\b/u);
+  if (m) return { file: m[1], line: Number(m[2]) };
+  return null;
+}
+
+/** Extract all frames from multi-line stack/traceback text, preserving order. */
+export function extractFrames(text = "") {
+  const frames = [];
+  for (const line of String(text).split("\n")) {
+    const frame = extractFrameFromLine(line);
+    if (frame) frames.push(frame);
+  }
+  return frames;
+}
+
+/** The top in-repo frame drives the anchor: the first frame (topmost, closest to
+ * the throw) whose file passes the in-repo predicate. We do NOT search deeper for
+ * a frame that happens to be in the diff — anchoring a lower frame would point at
+ * a caller, not the failing line. A deeper frame that is in-repo but not in the
+ * diff is handled downstream as non-anchorable, never by guessing past the top. */
+export function topInRepoFrame(frames) {
+  return frames.find((f) => isInRepoFrame(f.file)) ?? null;
+}
+
+/**
+ * Parse a unified diff into a map of changed file -> set of ADDED head line
+ * numbers (the RIGHT side). EVERY changed file is a key (registered from its
+ * `diff --git`/`+++ ` header) so a file that is changed but adds no anchorable
+ * line (deletion-only, binary, or mode-only) still reports as changed with an
+ * empty set — distinct from a file the PR never touched. Only added (`+`) lines
+ * are anchor targets: an inline comment on an added line points at code the PR
+ * introduced. Unchanged context lines advance the head counter but are not
+ * anchor targets — a defect on an unchanged line is body-attached, not falsely
+ * pinned to "changed" code.
+ *
+ * @param {string} diffOutput - raw `gh pr diff` / `git diff` unified output.
+ * @returns {Map<string, Set<number>>}
+ */
+export function parseDiffAnchors(diffOutput = "") {
+  const map = new Map();
+  const register = (p) => {
+    if (p !== null && !map.has(p)) map.set(p, new Set());
+  };
+  let currentPath = null;
+  let newLine = 0;
+  let inHunk = false;
+  for (const line of String(diffOutput).split("\n")) {
+    if (line.startsWith("diff --git")) {
+      // The only hunk terminator: a bare `diff --git` can never be hunk content
+      // (content lines always carry a `+`/`-`/space prefix), so it always resets.
+      currentPath = null;
+      inHunk = false;
+      // Register the RIGHT-side path so binary/mode-only changes (which carry no
+      // `+++ ` header) still count as changed files.
+      const m = line.match(/^diff --git a\/.+ b\/(.+)$/u);
+      if (m) register(m[1]);
+      continue;
+    }
+    // File headers appear only before the first hunk. Inside a hunk a line
+    // beginning `+++ `/`--- ` is content (an added `++ x` / a deleted `-- x`),
+    // so it must fall through to the `+`/`-` content handling below, not be
+    // misread as a header that rebinds the path or drops the rest of the hunk.
+    if (!inHunk && line.startsWith("+++ ")) {
+      const p = line.slice(4).trim();
+      currentPath = p === "/dev/null" ? null : p.replace(/^b\//u, "");
+      // Register even deletion-only files (they keep a `+++ b/path` header but
+      // add no line) so they report as changed rather than not-among-changed.
+      register(currentPath);
+      continue;
+    }
+    if (!inHunk && line.startsWith("--- ")) {
+      continue;
+    }
+    if (line.startsWith("@@")) {
+      const m = line.match(/@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/u);
+      newLine = m ? Number(m[1]) : 0;
+      inHunk = Boolean(m);
+      continue;
+    }
+    if (!inHunk || currentPath === null) continue;
+    if (line.startsWith("+")) {
+      if (!map.has(currentPath)) map.set(currentPath, new Set());
+      map.get(currentPath).add(newLine);
+      newLine += 1;
+    } else if (line.startsWith("-")) {
+      // Deleted line: present only on the old side, so it does not advance the head counter.
+    } else if (line.startsWith("\\")) {
+      // "": a marker, not a content line.
+    } else {
+      // Context line: on both sides, so it advances the head counter but is not an anchor target.
+      newLine += 1;
+    }
+  }
+  return map;
+}
+
+/** Normalize a stack-frame file to a repo-relative-comparable form: strip a URL
+ * scheme+authority (`http://host/assets/x.js` -> `/assets/x.js`) and any
+ * query/hash, then fold Windows `\` separators to `/`, so an absolute, served,
+ * or Windows-style path can be suffix-matched to a (forward-slash) diff path. */
+function normalizeFrameFile(file) {
+  let s = String(file);
+  const scheme = s.match(/^[a-z][a-z0-9+.\-]*:\/\/[^/]*(\/.*)$/iu);
+  if (scheme) s = scheme[1];
+  return s.split(/[?#]/u)[0].replace(/\\/gu, "/");
+}
+
+/** The source-file -> changed-file mapping is the fragile axis (bundlers, moved
+ * code, served paths). Match a frame file to a diff path by exact match or path
+ * suffix. Return every match so an ambiguous mapping (more than one changed file
+ * is a suffix of the frame path) is flagged rather than guessed. */
+function matchDiffPaths(frameFile, anchorPaths) {
+  const nf = normalizeFrameFile(frameFile);
+  return anchorPaths.filter((p) => nf === p || nf.endsWith(`/${p}`));
+}
+
+/**
+ * Map one Stage-2 failure to a finding: parse its exception + source location,
+ * resolve an anchor on the diff, or retain it flagged non-anchorable.
+ *
+ * @param {object} failure - a `classifyFailures` entry `{kind, severity, message, ...}`.
+ * @param {Map<string,Set<number>>} anchorsByPath
+ * @param {object|null} evidence - the reproduced-evidence reference to attach.
+ */
+function diagnoseOne(failure, anchorsByPath, evidence) {
+  // page-error carries `stack`; server-log-exception carries `context`; the
+  // wire-level failures (error/request) carry neither -> no source location.
+  const sourceText =
+    failure.kind === "page-error" ? failure.stack :
+    failure.kind === "server-log-exception" ? failure.context :
+    "";
+  const exception = parseException(sourceText || failure.message || "");
+  const finding = {
+    severity: failure.severity ?? null,
+    kind: failure.kind,
+    message: failure.message ?? null,
+    exception,
+    source: null,
+    anchor: null,
+    anchorable: false,
+    nonAnchorableReason: null,
+    evidence,
+  };
+
+  const frame = topInRepoFrame(extractFrames(sourceText || ""));
+  if (!frame) {
+    finding.nonAnchorableReason = "no source location (no in-repo stack frame in the captured failure)";
+    return finding;
+  }
+  finding.source = frame;
+
+  const matches = matchDiffPaths(frame.file, [...anchorsByPath.keys()]);
+  if (matches.length === 0) {
+    finding.nonAnchorableReason = "source file is not among the PR's changed files";
+    return finding;
+  }
+  if (matches.length > 1) {
+    finding.nonAnchorableReason = `ambiguous: source file maps to more than one changed file (${matches.join(", ")})`;
+    return finding;
+  }
+  const path = matches[0];
+  if (!anchorsByPath.get(path).has(frame.line)) {
+    finding.nonAnchorableReason = "source line is not on an added diff line";
+    return finding;
+  }
+  finding.anchor = { path, line: frame.line, side: RIGHT };
+  finding.anchorable = true;
+  return finding;
+}
+
+/**
+ * Rank findings deterministically — no wall-clock, no input-order dependence.
+ * Order: severity (must-fix first), then anchorable-first (the poster can inline
+ * these), then kind, then source file, then source line. Every key is a total
+ * order over the data so the result is stable for a given input set.
+ */
+export function rankFindings(findings) {
+  const key = (f) => [
+    severityRank(f.severity),
+    f.anchorable ? 0 : 1,
+    f.kind ?? "",
+    f.source?.file ?? "",
+    f.source?.line ?? 0,
+  ];
+  return [...findings].sort((a, b) => {
+    const ka = key(a);
+    const kb = key(b);
+    for (let i = 0; i < ka.length; i += 1) {
+      if (ka[i] < kb[i]) return -1;
+      if (ka[i] > kb[i]) return 1;
+    }
+    return 0;
+  });
+}
+
+/**
+ * Diagnose the drive stage's captured failures into a ranked findings list with
+ * diff-line anchors or explicit non-anchorable flags plus reproduced-evidence
+ * references. Pure.
+ *
+ * @param {object} input
+ * @param {object[]} [input.failures] - the drive stage's `failures`.
+ * @param {object[]} [input.captures] - the drive stage's `captures` (evidence).
+ * @param {string} [input.diffOutput] - the PR's unified diff.
+ * @returns {{ok:boolean, findings:object[], counts:{total:number,anchorable:number,nonAnchorable:number}}}
+ */
+export function diagnoseFailures({ failures = [], captures = [], diffOutput = "" } = {}) {
+  const anchorsByPath = parseDiffAnchors(diffOutput);
+  // ponytail: one reproduced-evidence reference per finding — the drive's final
+  // captured state (the last screenshot/state pair). Per-step attribution would
+  // need brittle parsing of the step-failure message; wire flow/step through the
+  // drive feed first if a stage needs frame-accurate evidence.
+  const last = captures.length > 0 ? captures[captures.length - 1] : null;
+  const evidence = last
+    ? { flow: last.flow ?? null, step: last.step ?? null, screenshotPath: last.screenshotPath ?? null, statePath: last.statePath ?? null }
+    : null;
+
+  const findings = rankFindings(failures.map((f) => diagnoseOne(f, anchorsByPath, evidence)));
+  const anchorable = findings.filter((f) => f.anchorable).length;
+  return {
+    ok: findings.length === 0,
+    findings,
+    counts: { total: findings.length, anchorable, nonAnchorable: findings.length - anchorable },
+  };
+}

package/src/loop/ui-review-drive.mjs

@@ -0,0 +1,348 @@
+/**
+ * Drive orchestrator for the ui_review route (Stage 2).
+ *
+ * Authenticates as the change's target role via a project-provided dev-login
+ * recipe, then walks the changed UI flows against the arbitrary running-app URL
+ * handed off by Stage 1 — rendering each page, exercising its declared
+ * interactions, and capturing an ordered set of step screenshots. While it
+ * drives, response/requestfailed/pageerror listeners and a server-log tail run
+ * so a swallowed error response (a 500 the UI hides) is still recorded.
+ *
+ * This module is PURE orchestration: all browser/page IO, the auth recipe, the
+ * interstitial dismissal, the per-step capture, the event collection, and the
+ * server-log tail are injected seams. The thin CLI/harness wires real Playwright
+ * (WebKit). The decision logic that lives here is: which flows to drive
+ * (a bounded changed-flow heuristic over an explicit allowlist), cap
+ * enforcement (max screenshots, screens skipped, no-retry) with explicit logs,
+ * and failure classification (collating error responses, request failures,
+ * page errors, and server-log exceptions into one structured list).
+ *
+ * Fail closed: a can't-authenticate condition STOPS with a stated reason and
+ * drives nothing. The structured captured-failures list feeds the next stage.
+ *
+ * Out of scope (later stages): exception -> source-line mapping, review
+ * posting, visual-regression/pixel-diffing, cross-browser matrix.
+ */
+
+const MUST_FIX = "must-fix";
+
+/** The one owner of the error-response threshold: an error response is anything
+ * outside 2xx/3xx. 3xx redirects are normal navigation (login/canonical), not
+ * errors, so they are not flagged. Shared by the CLI listener's pre-filter (for
+ * buffer bounding) and the classifier, so the policy has a single source. */
+export function isErrorResponseStatus(status) {
+  return typeof status === "number" && (status < 200 || status >= 400);
+}
+
+/** Bound the stack text carried onto a page-error failure so a runaway stack
+ * (or a synthetic error with a huge stack) can't bloat the feed envelope. Keeps
+ * the head — the top frames, where the throwing file:line sits. */
+const PAGE_ERROR_STACK_MAX_CHARS = 4000;
+
+/** Lines of context to preserve on each side of a matching server-log line, so
+ * the traceback frames that carry file:line (often on adjacent, non-matching
+ * lines) survive into the Stage 3 feed. */
+const SERVER_LOG_CONTEXT_LINES = 4;
+/** Char cap on the preserved server-log context window per failure entry. */
+const SERVER_LOG_CONTEXT_MAX_CHARS = 2000;
+
+/** Bounded caps. A project cannot raise these past the ceilings — the walker is
+ * a diagnostic pass over the changed flows, never an unbounded crawl. */
+export const DEFAULT_DRIVE_CAPS = Object.freeze({
+  maxScreenshots: 40,
+  maxFlows: 12,
+  maxStepsPerFlow: 20,
+  // No-retry is a fixed policy, not a tunable: a flaky step is a finding, not
+  // something to paper over by re-running. Logged explicitly on every run.
+  retries: 0,
+});
+
+/** Merge project caps onto the defaults, clamping each to its ceiling so a
+ * recipe can only tighten a cap, never loosen it past the diagnostic budget. */
+export function resolveCaps(caps = {}) {
+  const clamp = (v, ceiling) =>
+    Number.isInteger(v) && v >= 0 ? Math.min(v, ceiling) : ceiling;
+  return {
+    maxScreenshots: clamp(caps.maxScreenshots, DEFAULT_DRIVE_CAPS.maxScreenshots),
+    maxFlows: clamp(caps.maxFlows, DEFAULT_DRIVE_CAPS.maxFlows),
+    maxStepsPerFlow: clamp(caps.maxStepsPerFlow, DEFAULT_DRIVE_CAPS.maxStepsPerFlow),
+    retries: 0,
+  };
+}
+
+/**
+ * Changed-flow discovery: pick which allowlisted flows to drive.
+ *
+ * This is a DOCUMENTED HEURISTIC over an EXPLICIT allowlist, never an unbounded
+ * crawl. Each flow declares `pathPatterns` (plain substrings matched against the
+ * PR's changed file paths). A flow is in scope when any changed path contains
+ * any of its patterns. A flow with no `pathPatterns` is always in scope (the
+ * project opted it into every run). When `changedPaths` is empty/absent the diff
+ * is unknown, so every allowlisted flow is driven — the safe over-approximation.
+ * The selection is then capped at `caps.maxFlows`; the overflow is skipped and
+ * logged, never silently dropped.
+ *
+ * @returns {{ selected: object[], skipped: {name:string, reason:string}[] }}
+ */
+export function selectFlows({ flows = [], changedPaths = [], caps = DEFAULT_DRIVE_CAPS } = {}) {
+  const paths = Array.isArray(changedPaths) ? changedPaths : [];
+  const haveDiff = paths.length > 0;
+  const matched = [];
+  const skipped = [];
+  for (const flow of flows) {
+    const patterns = Array.isArray(flow.pathPatterns) ? flow.pathPatterns : [];
+    let inScope;
+    if (!haveDiff || patterns.length === 0) {
+      inScope = true; // unknown diff, or an always-on flow
+    } else {
+      inScope = patterns.some((p) => paths.some((cp) => cp.includes(p)));
+    }
+    if (inScope) matched.push(flow);
+    else skipped.push({ name: flow.name, reason: "no changed path matched its pathPatterns" });
+  }
+  const selected = matched.slice(0, caps.maxFlows);
+  for (const flow of matched.slice(caps.maxFlows)) {
+    skipped.push({ name: flow.name, reason: `maxFlows cap (${caps.maxFlows}) reached` });
+  }
+  return { selected, skipped };
+}
+
+/**
+ * Classify raw captured events + the server-log tail into one structured failure
+ * list. Pure. This is where a swallowed error response surfaces twice — once
+ * from the response listener and once from the server-log tail — so a 500 the UI
+ * hid is still recorded.
+ *
+ * @param {object} input
+ * @param {{url?:string,status:number}[]} [input.responses] - from page.on('response')
+ * @param {{url?:string,failure?:string}[]} [input.requestFailures] - from page.on('requestfailed')
+ * @param {{message?:string,stack?:string|null}[]} [input.pageErrors] - from page.on('pageerror'); `stack` (file:line) feeds Stage 3
+ * @param {string} [input.serverLogTail] - tail text of the project server log
+ * @param {string} [input.serverLogExceptionPattern] - regex (source) flagging a log exception line
+ * @returns {{kind:string, severity:string, message:string, [k:string]:unknown}[]}
+ */
+export function classifyFailures({
+  responses = [],
+  requestFailures = [],
+  pageErrors = [],
+  serverLogTail = "",
+  serverLogExceptionPattern,
+} = {}) {
+  const failures = [];
+
+  for (const r of responses) {
+    // A swallowed 500 lands here even when the page rendered a success state,
+    // because the listener sees the wire. The error-response threshold has one
+    // owner: isErrorResponseStatus.
+    if (isErrorResponseStatus(r.status)) {
+      failures.push({
+        kind: "error-response",
+        severity: MUST_FIX,
+        status: r.status,
+        url: r.url ?? null,
+        message: `error response ${r.status}${r.url ? ` at ${r.url}` : ""}`,
+      });
+    }
+  }
+
+  for (const f of requestFailures) {
+    failures.push({
+      kind: "request-failed",
+      severity: MUST_FIX,
+      url: f.url ?? null,
+      message: `request failed${f.url ? ` at ${f.url}` : ""}${f.failure ? `: ${f.failure}` : ""}`,
+    });
+  }
+
+  for (const e of pageErrors) {
+    // Carry the bounded stack so Stage 3's exception -> source-line mapping has
+    // the file:line signal; null when the listener captured no stack.
+    const stack = typeof e.stack === "string" && e.stack.length > 0 ? e.stack.slice(0, PAGE_ERROR_STACK_MAX_CHARS) : null;
+    failures.push({
+      kind: "page-error",
+      severity: MUST_FIX,
+      message: `uncaught page error: ${e.message ?? "(no message)"}`,
+      stack,
+    });
+  }
+
+  if (serverLogTail && serverLogExceptionPattern) {
+    // Config validates the pattern only on the CLI path; a direct caller can
+    // pass an invalid regex. Guard the compile so a bad pattern degrades to a
+    // surfaced note instead of throwing and breaking the whole drive envelope.
+    let re;
+    try {
+      re = new RegExp(serverLogExceptionPattern, "iu");
+    } catch (err) {
+      failures.push({
+        kind: "server-log-pattern-invalid",
+        severity: "note",
+        message: `server-log exception pattern is not a valid regex; skipped server-log classification: ${err?.message ?? String(err)}`,
+      });
+    }
+    if (re) {
+      const lines = serverLogTail.split("\n");
+      for (let i = 0; i < lines.length; i += 1) {
+        const trimmed = lines[i].trim();
+        if (trimmed.length > 0 && re.test(trimmed)) {
+          // Preserve the contiguous frames around the match: the file:line the
+          // traceback carries usually sits on adjacent, non-matching lines that
+          // the per-line match alone would drop. Bounded on both axes.
+          const from = Math.max(0, i - SERVER_LOG_CONTEXT_LINES);
+          const to = Math.min(lines.length, i + SERVER_LOG_CONTEXT_LINES + 1);
+          const context = lines.slice(from, to).join("\n").slice(0, SERVER_LOG_CONTEXT_MAX_CHARS);
+          failures.push({
+            kind: "server-log-exception",
+            severity: MUST_FIX,
+            message: `server log exception: ${trimmed.slice(0, 500)}`,
+            context,
+          });
+        }
+      }
+    }
+  }
+
+  return failures;
+}
+
+/**
+ * Run the auth + drive sequence over the changed flows.
+ *
+ * @param {object} input
+ * @param {string} input.appUrl - The arbitrary running-app URL from Stage 1.
+ * @param {object} input.login - Resolved dev-login recipe (loginUrl + selectors).
+ * @param {object[]} [input.flows] - Allowlisted changed-flow definitions.
+ * @param {object[]} [input.interstitials] - Config-declared dismiss selectors.
+ * @param {string[]} [input.changedPaths] - Changed file paths (drives selection).
+ * @param {string} [input.serverLogExceptionPattern] - regex source for log-tail classification.
+ * @param {object} [input.caps] - Project cap overrides (clamped to the ceilings).
+ * @param {object} seams - Injected IO.
+ * @param {(a:{appUrl:string,login:object})=>Promise<{ok:boolean,detail:string}>} seams.authenticate
+ * @param {(a:{interstitials:object[]})=>Promise<{dismissed:string[]}>} [seams.dismissInterstitials]
+ * @param {(a:{appUrl:string,flow:object,step:object,index:number})=>Promise<{screenshotPath?:string,statePath?:string,ok?:boolean,detail?:string}>} seams.runStep
+ * @param {()=>{responses?:object[],requestFailures?:object[],pageErrors?:object[]}} seams.getCapturedEvents
+ * @param {()=>Promise<string>} [seams.readServerLogTail]
+ * @param {(msg:string)=>void} [seams.log]
+ * @returns {Promise<object>} Result envelope (steps, captures, failures, caps, logs).
+ */
+export async function driveUiReview(
+  { appUrl, login, flows = [], interstitials = [], changedPaths = [], serverLogExceptionPattern, caps = {} },
+  {
+    authenticate,
+    dismissInterstitials = async () => ({ dismissed: [] }),
+    runStep,
+    getCapturedEvents,
+    readServerLogTail = async () => "",
+    log = () => {},
+  } = {},
+) {
+  const logs = [];
+  const record = (msg) => {
+    logs.push(msg);
+    log(msg);
+  };
+  const resolvedCaps = resolveCaps(caps);
+  // No-retry is a fixed policy — log it every run so the bound is never implicit.
+  record(`caps: maxScreenshots=${resolvedCaps.maxScreenshots}, maxFlows=${resolvedCaps.maxFlows}, maxStepsPerFlow=${resolvedCaps.maxStepsPerFlow}, retries=${resolvedCaps.retries} (no-retry)`);
+
+  const base = () => ({ appUrl: appUrl ?? null, logs });
+
+  // 1. Authenticate as the target role. Fail closed: no session -> STOP, drive
+  //    nothing (a review that never reached the app is worthless, not empty).
+  const auth = await authenticate({ appUrl, login });
+  if (!auth.ok) {
+    const stopReason = `cannot authenticate: ${auth.detail ?? "dev-login recipe did not yield a session"}`;
+    record(`STOP: ${stopReason}`);
+    return {
+      ok: false,
+      stopped: true,
+      stopReason,
+      steps: [],
+      captures: [],
+      failures: [{ kind: "auth-failed", severity: MUST_FIX, message: stopReason }],
+      caps: resolvedCaps,
+      ...base(),
+    };
+  }
+  record(`authenticated: ${auth.detail ?? "session established"}`);
+
+  // 2. Dismiss known interstitials ONCE per browser context (config-declared).
+  const dismiss = await dismissInterstitials({ interstitials });
+  if (dismiss.dismissed?.length) record(`interstitials dismissed: ${dismiss.dismissed.join(", ")}`);
+
+  // 3. Select the changed flows (bounded heuristic over the explicit allowlist).
+  const { selected, skipped } = selectFlows({ flows, changedPaths, caps: resolvedCaps });
+  for (const s of skipped) record(`flow skipped: ${s.name} (${s.reason})`);
+  record(`driving ${selected.length} flow(s)`);
+
+  // 4. Walk each flow's steps, capturing every step, until the screenshot cap.
+  //    No retry: a step that throws is recorded as a step failure and the walk
+  //    moves on — deterministic, bounded, never re-run.
+  const steps = [];
+  const captures = [];
+  let screenshots = 0;
+  let screensSkipped = 0;
+  for (const flow of selected) {
+    const declaredSteps = Array.isArray(flow.steps) ? flow.steps : [];
+    const flowSteps = declaredSteps.slice(0, resolvedCaps.maxStepsPerFlow);
+    if (declaredSteps.length > flowSteps.length) {
+      record(`steps skipped: ${flow.name} truncated to ${flowSteps.length} step(s) at the maxStepsPerFlow cap (${resolvedCaps.maxStepsPerFlow})`);
+    }
+    for (let i = 0; i < flowSteps.length; i += 1) {
+      const step = flowSteps[i];
+      if (screenshots >= resolvedCaps.maxScreenshots) {
+        screensSkipped += 1;
+        continue;
+      }
+      let outcome;
+      try {
+        outcome = await runStep({ appUrl, flow, step, index: screenshots });
+      } catch (err) {
+        outcome = { ok: false, detail: (err?.message ?? String(err)).slice(0, 500) };
+      }
+      const ok = outcome?.ok !== false;
+      screenshots += 1;
+      const entry = {
+        flow: flow.name,
+        step: step.name ?? step.action ?? `step-${i}`,
+        order: screenshots,
+        ok,
+        screenshotPath: outcome?.screenshotPath ?? null,
+        statePath: outcome?.statePath ?? null,
+        detail: outcome?.detail ?? null,
+      };
+      steps.push(entry);
+      if (entry.screenshotPath) captures.push({ flow: flow.name, step: entry.step, screenshotPath: entry.screenshotPath, statePath: entry.statePath });
+      if (!ok) record(`step failed (no retry): ${flow.name} / ${entry.step}: ${entry.detail ?? "unknown"}`);
+    }
+  }
+  if (screensSkipped > 0) record(`screens skipped: ${screensSkipped} step(s) past the maxScreenshots cap (${resolvedCaps.maxScreenshots})`);
+
+  // 5. Collate the out-of-band captures: listener events + the server-log tail.
+  const events = getCapturedEvents() ?? {};
+  const serverLogTail = await readServerLogTail();
+  const failures = classifyFailures({
+    responses: events.responses ?? [],
+    requestFailures: events.requestFailures ?? [],
+    pageErrors: events.pageErrors ?? [],
+    serverLogTail,
+    serverLogExceptionPattern,
+  });
+  // A step that threw is a drive failure too — surface it in the structured list.
+  for (const s of steps) {
+    if (!s.ok) failures.push({ kind: "step-failure", severity: MUST_FIX, message: `step failed: ${s.flow} / ${s.step}${s.detail ? `: ${s.detail}` : ""}` });
+  }
+  record(`captured ${failures.length} failure(s) across ${steps.length} step(s)`);
+
+  return {
+    ok: failures.length === 0,
+    stopped: false,
+    stopReason: null,
+    steps,
+    captures,
+    failures,
+    caps: resolvedCaps,
+    screensSkipped,
+    ...base(),
+  };
+}