argusqa-os 9.7.5 → 9.8.0

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 } 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';
@@ -370,6 +371,33 @@ function analyzeNetworkPerformance(perfEntries, pageUrl) {
   return bugs;
 }
 
+/**
+ * HTTPS-enforcement rule (single source of truth, exported so it can be verified
+ * directly — the harness can only crawl localhost, which is excluded, so the
+ * positive-trigger path has no live fixture).
+ *
+ * Returns a `security_no_https` finding for an http:// page on a non-loopback host,
+ * or null otherwise (https, or any localhost/127.x/::1 address).
+ *
+ * @param {string} url
+ * @returns {{type:string,message:string,severity:string,url:string}|null}
+ */
+export function checkHttpsRequired(url) {
+  try {
+    const parsed = new URL(url);
+    const isLocalhost = /^(localhost|127\.|::1)/.test(parsed.hostname);
+    if (parsed.protocol === 'http:' && !isLocalhost) {
+      return {
+        type:     'security_no_https',
+        message:  `Page served over HTTP — enforce HTTPS via server redirect or HSTS`,
+        severity: 'warning',
+        url,
+      };
+    }
+  } catch { /* URL parse failure */ }
+  return null;
+}
+
 // ── Cheap Crawl (called ×2 for flakiness detection) ───────────────────────────
 
 /**
@@ -680,19 +708,9 @@ export async function crawlRouteCheap(route, baseUrl, mcp) {
     logger.warn(`[ARGUS] Issues analysis skipped for ${url}: ${err.message}`);
   }
 
-  // 9f. HTTPS enforcement check
-  try {
-    const parsed = new URL(url);
-    const isLocalhost = /^(localhost|127\.|::1)/.test(parsed.hostname);
-    if (parsed.protocol === 'http:' && !isLocalhost) {
-      result.errors.push({
-        type:     'security_no_https',
-        message:  `Page served over HTTP — enforce HTTPS via server redirect or HSTS`,
-        severity: 'warning',
-        url,
-      });
-    }
-  } catch { /* URL parse failure */ }
+  // 9f. HTTPS enforcement check (shared rule — see checkHttpsRequired above)
+  const httpsFinding = checkHttpsRequired(url);
+  if (httpsFinding) result.errors.push(httpsFinding);
 
   // 10. Deduplicate within this cheap run
   result.errors = deduplicateErrors(result.errors);
@@ -836,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;
+}