argusqa-os 9.7.6 → 9.8.1

package/src/mcp-server.js

@@ -29,14 +29,22 @@ import { createRequire } from 'module';
 import { createMcpClient }                    from './utils/mcp-client.js';
 import { childLogger }                        from './utils/logger.js';
 import { parseListPagesResponse }             from './utils/mcp-parsers.js';
-import { crawlRouteCheap, runCrawl }          from './orchestration/crawl-and-report.js';
+import { crawlRouteWithDepth, runCrawl }      from './orchestration/crawl-and-report.js';
+import { resolveAuditDepth, selectAnalyzers } from './utils/audit-depth.js';
 import { runComparison }                      from './orchestration/env-comparison.js';
 import { WatchSession }                       from './orchestration/watch-mode.js';
 import { CdpBrowserAdapter }                  from './adapters/browser.js';
 import { getFigmaFrame }                      from './adapters/figma.js';
 import { analyzeDesignFidelity }             from './utils/design-fidelity-analyzer.js';
 import { analyzeVisualRegression }           from './utils/visual-diff-analyzer.js';
-import { fetchPrFiles, mapFilesToRoutes } from './utils/pr-diff-analyzer.js';
+import { fetchPrFiles, mapFilesToRoutesDeep } from './utils/pr-diff-analyzer.js';
+import { resolveTargetUrl }                    from './utils/deploy-preview.js';
+import { mapWithConcurrency, auditRouteWithRetry, routeResilienceFromEnv } from './utils/parallel-crawler.js';
+import { reportPrValidation }                 from './utils/github-reporter.js';
+import { getCurrentBranch }                    from './utils/baseline-manager.js';
+import {
+  decidePrBlock, resolvePrBaselineFile, loadPrBaseline, savePrBaseline, tagFindingNovelty, severityTally,
+} from './utils/pr-baseline.js';
 
 const logger = childLogger('mcp-server');
 
@@ -158,7 +166,7 @@ const TOOLS = [
   },
   {
     name: 'argus_pr_validate',
-    description: 'Runs a targeted Argus audit on the routes affected by a GitHub pull request. Fetches the PR diff, maps changed files to routes in your target config using path-slug heuristics (infrastructure changes trigger a full audit; targeted otherwise), and audits only those routes — faster than a full scan and focused on what the PR actually touched. Returns { findings, affectedRoutes, changedFiles, perRoute, summary, blocked, blockOn }. Use in CI to gate merges: check blocked:true or pipe findings to an AI verdict step. Requires Chrome on --remote-debugging-port=9222. GITHUB_TOKEN env var recommended for private repos.',
+    description: 'Runs a targeted Argus audit on the routes affected by a GitHub pull request. Fetches the PR diff, maps changed files to routes in your target config using path-slug heuristics (infrastructure changes trigger a full audit; targeted otherwise) — or, when ARGUS_SOURCE_DIR points at the checked-out app source, framework-aware import-graph mapping that narrows a changed component or stylesheet to only the routes whose pages import it (Next.js + monorepo-aware, conservative-fallback on any ambiguity) — and audits only those routes — faster than a full scan and focused on what the PR actually touched. The audit target is resolved per-PR: an explicit targetUrl, else the PR\'s deploy-preview URL (ARGUS_PREVIEW_URL or opt-in GitHub-Deployments auto-detection), else TARGET_DEV_URL. Routes are audited with bounded concurrency (ARGUS_CONCURRENCY) and each route audit is timeout-bounded (ARGUS_ROUTE_TIMEOUT_MS) so a hung audit blocks rather than silently passing. Returns { findings, affectedRoutes, changedFiles, perRoute, summary, blocked, blockOn, baseline, reporting }. Blocking is baseline-aware: it gates on the findings the PR introduces vs a stored per-branch baseline (reports/baselines/<base-branch>.json, restored via actions/cache), failing safe to absolute counts when no baseline is available. When GITHUB_TOKEN and a resolvable PR are present it also posts/updates an Argus PR comment (surfacing new/persisting/resolved counts) and a GitHub Check Run (the same reporting the CI Action produces) — best-effort, never alters the block decision. Use in CI to gate merges: check blocked:true or pipe findings to an AI verdict step. Requires Chrome on --remote-debugging-port=9222. GITHUB_TOKEN env var recommended for private repos.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -188,7 +196,11 @@ async function withMcp(fn) {
 
 // ── Tool handlers ─────────────────────────────────────────────────────────────
 
-async function handleAudit({ url, critical = false, cache = false }) {
+// `analyzers` is an INTERNAL-only argument (not in the public argus_audit schema): the
+// PR-validate path (handlePrValidate) passes the depth-policy-selected expensive analyzer
+// names (D2) so the same handler runs them on the affected route. The public tool is always
+// called with no `analyzers` → [] → crawlRouteWithDepth returns the cheap pass unchanged.
+async function handleAudit({ url, critical = false, cache = false, analyzers = [] }) {
   if (cache && auditCache.has(url)) {
     const { result, ts } = auditCache.get(url);
     // Refresh recency on read so eviction is true LRU, not insertion-order FIFO.
@@ -199,7 +211,7 @@ async function handleAudit({ url, critical = false, cache = false }) {
   return withMcp(async (mcp) => {
     const parsed = new URL(url);
     const route  = { path: parsed.pathname + parsed.search + parsed.hash, name: 'audit', critical };
-    const raw    = await crawlRouteCheap(route, parsed.origin, mcp);
+    const raw    = await crawlRouteWithDepth(route, parsed.origin, mcp, analyzers);
     const findings = Array.isArray(raw.errors) ? raw.errors : [];
     const result = {
       findings,
@@ -397,44 +409,132 @@ async function handleDesignAudit({ url, figmaFrameUrl }) {
   });
 }
 
+/**
+ * argus_pr_validate — the MCP-tool PR-validate path.
+ *
+ * INTENTIONAL DIVERGENCE from the CLI (src/cli/pr-validate.js): this path audits the dev's
+ * own config/targets.js routes (dev convenience), whereas the CLI audits a routes-file (CI
+ * safety + speed). That ROUTE-SOURCE divergence is by design (PR_VALIDATOR plan A4/E4).
+ * Everything downstream of the route list is SHARED so the two paths agree (E4 — CLI↔MCP parity):
+ *   - AUDIT DEPTH does NOT diverge: both paths run the same crawlRouteCheap pass by default and
+ *     share ONE opt-in depth policy (ARGUS_PR_AUDIT_DEPTH → selectAnalyzers, D2). (Earlier comments
+ *     here claimed this path ran the "full" audit; it has always called handleAudit = argus_audit =
+ *     the cheap pass, never handleAuditFull — corrected in D2.)
+ *   - The BLOCK DECISION is the shared decidePrBlock, fed a summary built by the shared severityTally,
+ *     so for the same findings + baseline + blockOn the two paths reach the IDENTICAL blocked/reason.
+ *     decidePrBlock owns the none|warning|critical matrix AND normalizes blockOn casing internally, so
+ *     this path may pass the raw `blockOn` arg without re-normalizing and still agree with the CLI.
+ *   - Both paths report through the SAME shared helper — reportPrValidation — so a reviewer sees an
+ *     identical PR comment + Check Run.
+ */
 async function handlePrValidate({ prUrl, targetUrl, githubToken, blockOn } = {}) {
   if (!prUrl) throw new Error('argus_pr_validate: prUrl is required');
 
   const { routes } = await import('./config/targets.js');
   const token  = githubToken ?? process.env.GITHUB_TOKEN;
-  const base   = targetUrl  ?? process.env.TARGET_DEV_URL ?? 'http://localhost:3000';
+  // D3 — resolve the audit target: an explicit `targetUrl` arg wins (raw); else a per-PR
+  // deploy preview (ARGUS_PREVIEW_URL / opt-in GitHub-Deployments auto-detection); else
+  // TARGET_DEV_URL. Mirrors the CLI; default (no arg, no preview env) → byte-identical.
+  const headSha = process.env.ARGUS_PR_HEAD_SHA || process.env.GITHUB_SHA;
+  const { url: base } = await resolveTargetUrl({ env: process.env, explicitTarget: targetUrl, prUrl, headSha, token });
   const policy = blockOn    ?? process.env.ARGUS_BLOCK_ON ?? 'critical';
 
-  const changedFiles   = await fetchPrFiles(prUrl, token);
-  const affectedRoutes = mapFilesToRoutes(changedFiles, routes ?? []);
+  // prFiles carries { filename, status, patch } per file; changedFiles is the filename-only
+  // view kept as a string[] in the tool response. mapFilesToRoutesDeep accepts either shape.
+  // ARGUS_SOURCE_DIR (opt-in) enables C1 framework-aware mapping (changed component → only the
+  // routes whose pages import it); unset → conservative slug heuristic. Mirrors the CLI path.
+  const prFiles        = await fetchPrFiles(prUrl, token);
+  const changedFiles   = prFiles.map(f => f.filename);
+  const affectedRoutes = mapFilesToRoutesDeep(prFiles, routes ?? [], { sourceDir: process.env.ARGUS_SOURCE_DIR });
 
-  const allFindings = [];
-  const perRoute    = [];
+  const allFindings   = [];
+  const perRoute      = [];
+  const routeFindings = [];   // [{ path, findings }] — feeds the baseline-aware diff (B1)
 
   // Preserve any path prefix in the target URL (e.g. http://host/app) — new URL()
   // with a leading-slash path would drop it. Mirrors src/cli/pr-validate.js.
   const baseUrl = String(base).replace(/\/$/, '');
-  for (const route of affectedRoutes) {
+
+  // Selective analyzer depth (D2) — the SAME shared policy the CLI uses (audit-depth.js), so
+  // the two paths run identical depth. Default 'cheap' → no expensive analyzers (byte-identical
+  // to the prior loop). Computed once per PR off ARGUS_PR_AUDIT_DEPTH + the changed file types.
+  const auditDepth     = resolveAuditDepth(process.env.ARGUS_PR_AUDIT_DEPTH);
+  const depthAnalyzers = selectAnalyzers({ depth: auditDepth, changedFiles });
+  if (depthAnalyzers.length > 0) {
+    logger.info(`[ARGUS] D2: audit depth ${auditDepth} → expensive analyzers: ${depthAnalyzers.join(', ')}`);
+  }
+
+  // Audit affected routes with bounded concurrency (ARGUS_CONCURRENCY; default 1 = sequential,
+  // byte-identical to the prior loop). handleAudit opens its OWN MCP client per call (withMcp), so
+  // routes are already connection-isolated — concurrency just caps how many run at once.
+  // mapWithConcurrency returns results in route order, so the baseline diff + block decision are
+  // identical to a sequential run. Mirrors the CLI path + the orchestrator's parallel crawling.
+  const rawConcurrency = parseInt(process.env.ARGUS_CONCURRENCY ?? '1', 10);
+  const concurrency    = Math.min(10, Math.max(1, Number.isNaN(rawConcurrency) ? 1 : rawConcurrency));
+  // Per-route timeout + retry (D4) — the SAME shared policy the CLI uses (routeResilienceFromEnv),
+  // so the two paths cannot diverge on the bound. A timed-out audit throws; mapWithConcurrency
+  // re-throws the first error, so handlePrValidate fails loud (a structured tool error) rather than
+  // returning a false-PASS result — the MCP path has no all-routes-failed guard, so fail-loud IS the
+  // safe behaviour here. Default ARGUS_ROUTE_TIMEOUT_MS=120000 / ARGUS_ROUTE_RETRIES=0.
+  const { timeoutMs: routeTimeoutMs, retries: routeRetries } = routeResilienceFromEnv();
+  const auditResults   = await mapWithConcurrency(affectedRoutes, concurrency, async (route) => {
     const routePath = String(route.path ?? '/').startsWith('/') ? route.path : `/${route.path}`;
-    const url = `${baseUrl}${routePath}`;
-    const res = await handleAudit({ url, critical: route.critical ?? false });
+    const url  = `${baseUrl}${routePath}`;
+    const res  = await auditRouteWithRetry(
+      () => handleAudit({ url, critical: route.critical ?? false, analyzers: depthAnalyzers }),
+      { timeoutMs: routeTimeoutMs, retries: routeRetries, label: `Route audit ${routePath}` },
+    );
     const data = JSON.parse(res.content[0].text);
-    allFindings.push(...(data.findings ?? []));
-    perRoute.push({ route: route.path, ...data.summary });
+    return { route, findings: data.findings ?? [], summary: data.summary };
+  });
+  for (const { route, findings, summary } of auditResults) {
+    allFindings.push(...findings);
+    perRoute.push({ route: route.path, ...summary });
+    routeFindings.push({ path: route.path, findings });
   }
 
-  const summary = {
-    critical: allFindings.filter(f => f.severity === 'critical').length,
-    warning:  allFindings.filter(f => f.severity === 'warning').length,
-    info:     allFindings.filter(f => f.severity === 'info').length,
-  };
+  // Aggregate (absolute) severity summary that feeds the block decision — built via the shared
+  // severityTally so this path and the CLI (src/cli/pr-validate.js) construct the decidePrBlock
+  // `summary` input IDENTICALLY (PR_VALIDATOR plan E4 — CLI↔MCP parity).
+  const summary = severityTally(allFindings);
+
+  // B1 — baseline-aware merge-block decision via the SAME shared helper the CLI uses
+  // (decidePrBlock), so the two PR-validate paths cannot diverge on the block semantics.
+  // Diff the head findings against the stored base-branch baseline (GITHUB_BASE_REF, restored
+  // via actions/cache) and gate on the findings this PR introduces; fail safe to absolute
+  // blocking when no baseline is resolvable.
+  const outputDir    = process.env.REPORT_OUTPUT_DIR || './reports';
+  const baselineFile = resolvePrBaselineFile({ outputDir });
+  const baseline     = baselineFile ? loadPrBaseline(baselineFile) : null;
+  const decision     = decidePrBlock({ routeFindings, summary, blockOn: policy, baseline });
+  const blocked      = decision.blocked;
+
+  // B2: tag each finding new-vs-persisting off the same baseline (shared objects in allFindings),
+  // so the PR comment surfaces only the findings this PR introduced — parity with the CLI path.
+  tagFindingNovelty(routeFindings, baseline);
+
+  const baselineInfo = decision.baselineAvailable
+    ? {
+        available:   true,
+        newCritical: decision.newSummary.critical,
+        newWarning:  decision.newSummary.warning,
+        newInfo:     decision.newSummary.info,
+        persisting:  decision.persistingCount,
+        resolved:    decision.resolvedCount,
+      }
+    : { available: false, note: decision.note };
 
-  const blocked =
-    policy === 'critical' ? summary.critical > 0 :
-    policy === 'warning'  ? summary.critical + summary.warning > 0 :
-    false;
+  // Optionally update this branch's baseline (ARGUS_UPDATE_BASELINE) — default off → no write.
+  if (/^(1|true|yes|on)$/i.test(process.env.ARGUS_UPDATE_BASELINE || '')) {
+    try {
+      const writeFile = resolvePrBaselineFile({ outputDir, baseRef: getCurrentBranch() });
+      if (writeFile) savePrBaseline(writeFile, routeFindings);
+    } catch (baseErr) {
+      logger.warn(`[ARGUS] B1: argus_pr_validate baseline write failed — ${baseErr.message}`);
+    }
+  }
 
-  return { content: [{ type: 'text', text: JSON.stringify({
+  const result = {
     prUrl,
     targetUrl: base,
     affectedRoutes: affectedRoutes.map(r => r.path),
@@ -444,7 +544,23 @@ async function handlePrValidate({ prUrl, targetUrl, githubToken, blockOn } = {})
     summary,
     blocked,
     blockOn: policy,
-  }, null, 2) }] };
+    baseline: baselineInfo,
+  };
+
+  // A4 — report through the SAME shared helper the CLI uses. Best-effort + fully isolated:
+  // reporting runs AFTER the block decision and is appended to the response, so a missing
+  // GITHUB_TOKEN, an unresolvable PR, or a GitHub API error can never change `blocked` or
+  // throw out of the tool. Env-gated on GITHUB_TOKEN exactly like the CLI (reporting uses the
+  // env token, not the per-call githubToken arg). The token never rides into the result.
+  let reporting;
+  try {
+    reporting = await reportPrValidation(result, { prUrl });
+  } catch (err) {
+    logger.warn(`[ARGUS] A4: argus_pr_validate PR reporting failed — ${err.message}`);
+    reporting = { posted: false, checked: false, skipped: true, reason: `reporting failed: ${err.message}` };
+  }
+
+  return { content: [{ type: 'text', text: JSON.stringify({ ...result, reporting }, null, 2) }] };
 }
 
 async function handleLastReport() {

package/src/orchestration/crawl-and-report.js

@@ -11,6 +11,6 @@
  * continue to import from this file unchanged.
  */
 
-export { runCrawl, crawlRouteCheap, crawlRouteExpensive, checkHttpsRequired } from './orchestrator.js';
+export { runCrawl, crawlRouteCheap, crawlRouteExpensive, crawlRouteWithDepth, checkHttpsRequired } from './orchestrator.js';
 export { processReport, deduplicateFindings, rebuildSummary } from './report-processor.js';
 export { dispatchAll } from './dispatcher.js';

package/src/orchestration/orchestrator.js

@@ -28,6 +28,7 @@ import { parseConsoleMsgResponse }                                       from '.
 import { CdpBrowserAdapter }                                             from '../adapters/browser.js';
 import { getFigmaFrame }                                                 from '../adapters/figma.js';
 import { chunkArray }                                                    from '../utils/parallel-crawler.js';
+import { runDepthAnalyzers }                                             from '../utils/audit-depth.js';
 import { validateApiContracts }                                          from '../utils/contract-validator.js';
 import { checkLighthouse }                                               from '../utils/lighthouse-checker.js';
 import { parseIssues }                                                   from '../utils/issues-analyzer.js';
@@ -853,6 +854,39 @@ export async function crawlRouteExpensive(route, baseUrl, mcp) {
   return errors;
 }
 
+// ── Selective-Depth Crawl (D2 — PR Validator) ──────────────────────────────────
+
+/**
+ * Crawl one route at a SELECTABLE depth for the PR Validator (D2).
+ *
+ * Runs the cheap pass (crawlRouteCheap) and then a SELECTED SUBSET of the registered
+ * expensive analyzers — the names chosen by the shared depth policy (audit-depth.js
+ * selectAnalyzers, off ARGUS_PR_AUDIT_DEPTH + the PR's changed file types). With an empty
+ * selection it returns the crawlRouteCheap result UNCHANGED, so the default ('cheap') tier
+ * is byte-identical to the prior PR-validate behaviour. Each expensive analyzer is isolated
+ * (runDepthAnalyzers try/catch), so deepening only ever ADDS findings — it can never turn a
+ * real failure into a PASS. Same shape as crawlRouteCheap ({ ...result, errors }).
+ *
+ * @param {object} route
+ * @param {string} baseUrl
+ * @param {object} mcp
+ * @param {string[]} [analyzerNames]  registry expensive-analyzer names to also run
+ */
+export async function crawlRouteWithDepth(route, baseUrl, mcp, analyzerNames = []) {
+  const result = await crawlRouteCheap(route, baseUrl, mcp);
+  const wanted = Array.isArray(analyzerNames) ? analyzerNames : [];
+  if (wanted.length === 0) return result;
+
+  const browser = new CdpBrowserAdapter(mcp);
+  const url     = `${baseUrl}${route.path}`;
+  const extra   = await runDepthAnalyzers(getExpensive(), browser, url, route, wanted);
+  if (extra.length > 0) {
+    result.errors.push(...extra);
+    result.errors = deduplicateErrors(result.errors);
+  }
+  return result;
+}
+
 // ── Per-Route Crawl Coordinator ────────────────────────────────────────────────
 
 async function crawlAndAnalyzeRoute(route, targetBaseUrl, mcp, sessionFile) {

package/src/utils/audit-depth.js

@@ -0,0 +1,148 @@
+/**
+ * Argus PR-Validator — selective analyzer depth policy (D2).
+ *
+ * Both PR-validate paths (the CLI `src/cli/pr-validate.js` and the MCP tool
+ * `handlePrValidate` in `src/mcp-server.js`) run `crawlRouteCheap` on each affected route
+ * by default. This module is the SINGLE, documented, deterministic policy that decides
+ * which — if any — registered EXPENSIVE analyzers also run on those routes, based on an
+ * opt-in depth tier and the PR's changed file types. Shared by both paths so they can
+ * never diverge on depth.
+ *
+ * Tiers (ARGUS_PR_AUDIT_DEPTH):
+ *   cheap    (default) → no expensive analyzers → byte-identical to the prior behaviour.
+ *   standard           → a file-type-selected subset of expensive analyzers (this module's
+ *                        STANDARD_POLICY) — the "selective" tier; a PR that only touches
+ *                        non-UI files (docs/config) degrades to cheap.
+ *   deep               → every registered expensive analyzer (ALL_EXPENSIVE_ANALYZERS),
+ *                        including Lighthouse + memory.
+ *
+ * Safety: depth can only ADD findings on a route, never drop one — a failing analyzer is
+ * isolated (try/catch) and skipped — so a deeper audit can never turn a real failure into a
+ * PASS. The merge-block decision (decidePrBlock) is untouched by this module.
+ *
+ * Purity: `resolveAuditDepth` / `selectAnalyzers` are pure (no I/O, no Chrome).
+ * `runDepthAnalyzers` is dependency-injected (the analyzer list + a browser are passed in),
+ * so the whole module is Chrome-free testable and stdout-clean (logs to stderr via Pino) —
+ * safe to import from the JSON-RPC MCP server.
+ */
+
+import { childLogger } from './logger.js';
+
+const logger = childLogger('audit-depth');
+
+/** Valid depth tiers, cheapest → deepest. The unset/invalid fallback is the cheapest. */
+export const AUDIT_DEPTHS = ['cheap', 'standard', 'deep'];
+
+/**
+ * The full catalog of registry expensive-analyzer `name`s D2 can run, in registration
+ * order (lighthouse self-registers first via its named import in orchestrator.js, then the
+ * side-effect imports). A drift-guard test asserts this set equals the live registry
+ * (`getExpensive()`), so a renamed/added/removed analyzer fails LOUDLY here instead of
+ * silently never running (the recurring "Argus mis-reads its own state" bug class).
+ */
+export const ALL_EXPENSIVE_ANALYZERS = [
+  'lighthouse', 'css', 'responsive', 'memory', 'hover', 'snapshot', 'keyboard',
+  'theme', 'design-fidelity', 'web-vitals', 'visual', 'a11y-deep', 'har-recorder',
+  'motion', 'font', 'form',
+];
+
+/**
+ * The documented file-type → analyzer policy for the `standard` tier. Each changed file
+ * contributes the analyzers of EVERY rule whose `test` matches its name; the route set runs
+ * the UNION (deduped, in registry order). A file matching no rule contributes nothing.
+ *
+ * Deliberately EXCLUDED from `standard` (reserved for `deep`): `lighthouse` (slow, up to the
+ * Lighthouse timeout), `memory` (GC-dependent / flaky), `design-fidelity` (inert without a
+ * route `figmaFrameUrl`), `har-recorder` (needs a committed HAR baseline). These add little
+ * PR signal per file type and would slow the per-PR gate.
+ */
+export const STANDARD_POLICY = [
+  // Stylesheets → layout/overflow, theming, motion, visual + contrast (a11y) regressions.
+  { label: 'stylesheet', test: /\.(css|scss|sass|less|styl)$/i,
+    analyzers: ['css', 'responsive', 'theme', 'motion', 'visual', 'a11y-deep'] },
+  // Component / markup source → a11y tree, focus order, hover state, vitals, forms.
+  { label: 'component', test: /\.(jsx?|tsx?|mjs|cjs|vue|svelte|astro|mdx|html?)$/i,
+    analyzers: ['a11y-deep', 'snapshot', 'keyboard', 'hover', 'web-vitals', 'form'] },
+  // Raster/vector images → visual regression.
+  { label: 'image', test: /\.(png|jpe?g|gif|webp|avif|svg|ico)$/i,
+    analyzers: ['visual'] },
+  // Web fonts → font-loading (FOIT/FOUT/fallback) regression.
+  { label: 'font', test: /\.(woff2?|ttf|otf|eot)$/i,
+    analyzers: ['font'] },
+];
+
+/**
+ * Normalize a raw depth value (env string) to a valid tier. Anything unrecognized →
+ * 'cheap' (fail-safe to the cheapest, byte-identical tier — a misconfigured value must
+ * never silently deepen or, worse, skip the audit).
+ *
+ * @param {string|undefined|null} raw
+ * @returns {'cheap'|'standard'|'deep'}
+ */
+export function resolveAuditDepth(raw) {
+  const v = String(raw ?? '').toLowerCase().trim();
+  return AUDIT_DEPTHS.includes(v) ? v : 'cheap';
+}
+
+/**
+ * The depth policy: which registered expensive-analyzer names to run on each affected
+ * route, given the resolved tier + the PR's changed files. Returns a deduped list in
+ * registry (ALL_EXPENSIVE_ANALYZERS) order. `cheap` → []; `deep` → all; `standard` → the
+ * union of STANDARD_POLICY rules over the changed files.
+ *
+ * @param {{depth?: string, changedFiles?: string[]}} [opts]
+ * @returns {string[]}
+ */
+export function selectAnalyzers({ depth = 'cheap', changedFiles = [] } = {}) {
+  const tier = resolveAuditDepth(depth);
+  if (tier === 'cheap') return [];
+  if (tier === 'deep')  return [...ALL_EXPENSIVE_ANALYZERS];
+
+  // standard — union of the file-type rules over the changed files.
+  const selected = new Set();
+  for (const file of Array.isArray(changedFiles) ? changedFiles : []) {
+    const name = String(file ?? '');
+    for (const rule of STANDARD_POLICY) {
+      if (rule.test.test(name)) {
+        for (const a of rule.analyzers) selected.add(a);
+      }
+    }
+  }
+  // Emit in registry order for determinism (and so dedup is stable).
+  return ALL_EXPENSIVE_ANALYZERS.filter(a => selected.has(a));
+}
+
+/**
+ * Run a SELECTED SUBSET of expensive analyzers against an already-navigated page.
+ * Dependency-injected: `expensiveAnalyzers` is the registry list (`getExpensive()`) and
+ * `browser` is the live adapter — both passed in, so this is Chrome-free testable. Only
+ * analyzers whose `name` is in `wantedNames` run; each runs in its own try/catch so one
+ * failing analyzer never aborts the route (and never drops a finding — depth is additive
+ * only, which is why it can never turn a real failure into a PASS).
+ *
+ * @param {Array<{name: string, analyze: Function}>} expensiveAnalyzers
+ * @param {object} browser   CdpBrowserAdapter (or a stub in tests)
+ * @param {string} url
+ * @param {object} route
+ * @param {string[]} [wantedNames]
+ * @returns {Promise<Array<object>>} collected findings
+ */
+export async function runDepthAnalyzers(expensiveAnalyzers, browser, url, route, wantedNames = []) {
+  const wanted = new Set(Array.isArray(wantedNames) ? wantedNames : []);
+  const findings = [];
+  if (wanted.size === 0) return findings;
+
+  for (const entry of Array.isArray(expensiveAnalyzers) ? expensiveAnalyzers : []) {
+    if (!entry || !wanted.has(entry.name) || typeof entry.analyze !== 'function') continue;
+    try {
+      const raw = await entry.analyze(browser, url, route);
+      // Analyzers return either findings[] or { findings, screenshots } (responsive).
+      const out = Array.isArray(raw) ? raw
+        : (raw && Array.isArray(raw.findings) ? raw.findings : []);
+      findings.push(...out);
+    } catch (err) {
+      logger.warn(`[ARGUS] D2: expensive analyzer "${entry.name}" skipped for ${url}: ${err.message}`);
+    }
+  }
+  return findings;
+}

package/src/utils/deploy-preview.js

@@ -0,0 +1,210 @@
+/**
+ * Deploy-preview URL auto-detection (PR Validator D3).
+ *
+ * Resolves the audit TARGET URL for a PR run, preferring a per-PR deploy preview
+ * (Vercel / Netlify / any GitHub Deployment) over the static TARGET_DEV_URL, and ALWAYS
+ * degrading gracefully to TARGET_DEV_URL when no preview is found or any detection step
+ * fails. Detection never throws and never blocks the run — a wrong/failed/missing preview
+ * must never silently audit the wrong app, so only a SUCCESS deploy-status URL for the PR's
+ * head SHA is ever adopted; everything else falls back.
+ *
+ * Resolution precedence (resolveTargetUrl):
+ *   1. explicitTarget    — an explicit per-call target (MCP tool `targetUrl` arg). Highest;
+ *                          passed through raw (explicit caller intent, like TARGET_DEV_URL).
+ *   2. ARGUS_PREVIEW_URL  — explicit env override (opt-in by being set). Provider env vars
+ *                          DEPLOY_PRIME_URL (Netlify) + VERCEL_URL (Vercel, bare host) are
+ *                          also recognized for convenience.
+ *   3. auto-detected preview from the PR head SHA's GitHub Deployments — OPT-IN:
+ *      ARGUS_PREVIEW_DETECT truthy + a token + a head SHA + a parseable PR URL. One+one
+ *      GitHub API call, fully fail-safe (any error → no preview → fallback).
+ *   4. TARGET_DEV_URL (or http://localhost:3000) — the conservative fallback, byte-identical
+ *      to the pre-D3 behaviour when nothing above matches.
+ *
+ * Pure helpers (Chrome-free, network-free) + one fail-safe async fetch. Imported (transitively)
+ * by the MCP server → nothing here writes to stdout (logs go to the injected/childLogger).
+ * No AI verdict — pure static/heuristic resolution (OSS side of the argus-pro boundary).
+ */
+
+import { parsePrUrl } from './pr-diff-analyzer.js';
+import { childLogger } from './logger.js';
+
+const logger = childLogger('deploy-preview');
+
+const GITHUB_API   = 'https://api.github.com';
+const FETCH_TIMEOUT = 10000;
+
+// Env vars (priority order) that may carry an explicit preview URL. ARGUS_PREVIEW_URL is the
+// portable, Argus-namespaced canonical; the rest are provider conventions surfaced for users
+// who forward them into the runner. VERCEL_URL is a bare host (no scheme) — normalized below.
+const ENV_PREVIEW_VARS = ['ARGUS_PREVIEW_URL', 'DEPLOY_PRIME_URL', 'VERCEL_URL'];
+
+/**
+ * Trim a candidate URL and accept it only if it carries an http(s) scheme.
+ * Returns the trimmed URL or null (never throws). Untrusted/auto-detected URLs flow through
+ * this; explicit caller targets (the MCP arg, TARGET_DEV_URL) are passed through raw.
+ * @param {*} raw
+ * @returns {string|null}
+ */
+export function normalizeUrl(raw) {
+  if (raw == null) return null;
+  const s = String(raw).trim();
+  if (!s) return null;
+  return /^https?:\/\//i.test(s) ? s : null;
+}
+
+/**
+ * Pick an explicit preview URL from the environment, honouring ENV_PREVIEW_VARS priority.
+ * VERCEL_URL is a bare host → prefixed with https:// before validation.
+ * @param {Record<string,string|undefined>} env
+ * @returns {{ url: string, source: string }|null}
+ */
+export function pickPreviewFromEnv(env = {}) {
+  for (const name of ENV_PREVIEW_VARS) {
+    let raw = env[name];
+    if (raw == null || String(raw).trim() === '') continue;
+    // VERCEL_URL is conventionally a bare host (e.g. my-app-git-pr.vercel.app).
+    if (name === 'VERCEL_URL' && !/^https?:\/\//i.test(String(raw).trim())) {
+      raw = `https://${String(raw).trim()}`;
+    }
+    const url = normalizeUrl(raw);
+    if (url) return { url, source: `env:${name}` };
+    logger.warn(`[ARGUS] D3: ${name} is set but not a valid http(s) URL — ignoring`);
+  }
+  return null;
+}
+
+/**
+ * Heuristic: is a GitHub Deployment object a PR/preview deployment (not production)?
+ * Recognizes Vercel ("Preview – <project>"), Netlify ("deploy-preview"), and any explicitly
+ * non-production / transient environment. Production deployments are excluded.
+ * @param {object} deployment
+ * @returns {boolean}
+ */
+export function isPreviewDeployment(deployment) {
+  if (!deployment || typeof deployment !== 'object') return false;
+  const env = String(deployment.environment ?? '');
+  // Explicit production → never a preview target.
+  if (deployment.production_environment === true || /production/i.test(env)) return false;
+  return (
+    /preview|deploy[\s-]?preview|staging/i.test(env) ||
+    deployment.transient_environment === true ||
+    deployment.production_environment === false
+  );
+}
+
+/**
+ * From a list of GitHub Deployments (newest-first, as the API returns them), pick the most
+ * recent preview deployment, or null when none qualify.
+ * @param {Array<object>} deployments
+ * @returns {object|null}
+ */
+export function pickPreviewDeployment(deployments) {
+  if (!Array.isArray(deployments)) return null;
+  return deployments.find(isPreviewDeployment) ?? null;
+}
+
+/**
+ * From a deployment's statuses (newest-first), return the live preview URL — the
+ * environment_url (preferred) or target_url of the most recent SUCCESS status — or null.
+ * Only a `success` status is adopted: a failed / error / pending / inactive deploy must
+ * never become the audit target (auditing a broken or stale preview would be a false result).
+ * @param {Array<object>} statuses
+ * @returns {string|null}
+ */
+export function previewUrlFromStatuses(statuses) {
+  if (!Array.isArray(statuses)) return null;
+  for (const s of statuses) {
+    if (!s || s.state !== 'success') continue;
+    const url = normalizeUrl(s.environment_url) ?? normalizeUrl(s.target_url);
+    if (url) return url;
+  }
+  return null;
+}
+
+async function ghGet(url, headers) {
+  const res = await fetch(url, { headers, signal: AbortSignal.timeout(FETCH_TIMEOUT) });
+  if (!res.ok) return null;
+  return res.json();
+}
+
+/**
+ * Fetch the live preview URL for a PR head SHA via the GitHub Deployments API. Fully
+ * fail-safe: ANY failure (no SHA, non-2xx, network error, no preview deployment, no success
+ * status) resolves to null so the caller degrades to TARGET_DEV_URL. Never throws.
+ *
+ * @param {object} opts
+ * @param {string} opts.owner
+ * @param {string} opts.repo
+ * @param {string} opts.sha    PR head SHA (NOT the merge commit)
+ * @param {string} [opts.token] GitHub token
+ * @returns {Promise<string|null>}
+ */
+export async function fetchPreviewUrlFromDeployments({ owner, repo, sha, token } = {}) {
+  try {
+    if (!owner || !repo || !sha) return null;
+    const headers = {
+      Accept: 'application/vnd.github+json',
+      'X-GitHub-Api-Version': '2022-11-28',
+      'User-Agent': 'argusqa-os',
+      ...(token ? { Authorization: `Bearer ${token}` } : {}),
+    };
+    const deployments = await ghGet(
+      `${GITHUB_API}/repos/${owner}/${repo}/deployments?sha=${encodeURIComponent(sha)}&per_page=30`,
+      headers,
+    );
+    const dep = pickPreviewDeployment(deployments);
+    if (!dep) return null;
+    const statuses = await ghGet(
+      `${GITHUB_API}/repos/${owner}/${repo}/deployments/${dep.id}/statuses?per_page=30`,
+      headers,
+    );
+    return previewUrlFromStatuses(statuses);
+  } catch (err) {
+    // Detection is best-effort — a probe failure must degrade to TARGET_DEV_URL, never break
+    // the run. The token never rides into the message (err.message is GitHub's text only).
+    logger.warn(`[ARGUS] D3: deploy-preview detection failed — ${err.message}`);
+    return null;
+  }
+}
+
+/**
+ * Resolve the audit target URL for a PR run (D3). See the module header for precedence.
+ * Always resolves (never throws); `source` records which rung won, for logging/visibility.
+ *
+ * @param {object} opts
+ * @param {Record<string,string|undefined>} opts.env  the process env (or a test object)
+ * @param {string} [opts.explicitTarget] an explicit per-call target (MCP `targetUrl` arg)
+ * @param {string} [opts.prUrl]
+ * @param {string} [opts.headSha]
+ * @param {string} [opts.token]
+ * @returns {Promise<{ url: string, source: string }>}
+ */
+export async function resolveTargetUrl({ env = {}, explicitTarget, prUrl, headSha, token } = {}) {
+  // The conservative fallback — passed through RAW (explicit operator intent), so the default
+  // path is byte-identical to the pre-D3 `TARGET_DEV_URL ?? 'http://localhost:3000'`.
+  const fallback = env.TARGET_DEV_URL ?? 'http://localhost:3000';
+
+  // 1. Explicit per-call target (MCP arg) — raw, highest precedence.
+  if (explicitTarget != null && String(explicitTarget).trim() !== '') {
+    return { url: explicitTarget, source: 'explicit' };
+  }
+
+  // 2. Explicit env override (ARGUS_PREVIEW_URL / provider env vars).
+  const envPick = pickPreviewFromEnv(env);
+  if (envPick) return envPick;
+
+  // 3. Auto-detect from GitHub Deployments — opt-in + fully fail-safe.
+  const detectOn = /^(1|true|yes|on)$/i.test(env.ARGUS_PREVIEW_DETECT || '');
+  if (detectOn && token && headSha && prUrl) {
+    try {
+      const { owner, repo } = parsePrUrl(prUrl);
+      const url = await fetchPreviewUrlFromDeployments({ owner, repo, sha: headSha, token });
+      if (url) return { url, source: 'deployment' };
+    } catch {
+      // parsePrUrl or detection threw — degrade silently to the fallback below.
+    }
+  }
+
+  // 4. Conservative fallback.
+  return { url: fallback, source: 'target-dev-url' };
+}