argusqa-os 9.7.5 → 9.8.0

package/src/utils/import-graph.js

@@ -0,0 +1,290 @@
+/**
+ * Argus — static ES/CJS import graph for framework-aware PR route mapping (PR_VALIDATOR C1).
+ *
+ * Builds a forward + reverse import adjacency over a source tree by statically parsing
+ * import / export-from / require / dynamic-import specifiers (regex — no AST, no execution)
+ * and resolving relative + tsconfig-alias specifiers to on-disk files. The PR Validator's
+ * framework-aware mapping uses the REVERSE graph to find which route entry files
+ * (transitively) import a changed component, so a PR touching `components/Foo.tsx` audits
+ * only the routes that render it instead of every route.
+ *
+ * Deliberately conservative + bounded:
+ *   - bare package specifiers (react, lodash, next/link) are ignored — they resolve to
+ *     node_modules, never an app route;
+ *   - unresolvable specifiers (computed requires, aliases we can't read) are dropped;
+ *   - stylesheet imports (`import './x.module.css'`) are tracked as LEAF nodes so a changed
+ *     stylesheet attributes to its importing routes (PR_VALIDATOR C3); they are never parsed;
+ *   - the walk skips node_modules/.git/build dirs and caps file count + size.
+ * The CALLER treats an INCOMPLETE resolution as "ambiguous → audit all routes", so any gap
+ * in this graph costs precision, never a missed regression.
+ *
+ * Pure filesystem + string parsing. No Chrome, no MCP, no network. This module is reachable
+ * from the MCP server (via pr-diff-analyzer), so it writes NOTHING to stdout — diagnostics
+ * go to stderr through childLogger.
+ */
+
+import fs   from 'fs';
+import path from 'path';
+import { childLogger } from './logger.js';
+
+const logger = childLogger('import-graph');
+
+// Source extensions we parse + resolve, in resolution-preference order.
+export const SOURCE_EXTS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'];
+const SOURCE_EXT_SET     = new Set(SOURCE_EXTS);
+const INDEX_BASENAMES    = SOURCE_EXTS.map(e => `index${e}`);
+
+// Stylesheet (asset) extensions tracked as LEAF nodes in the graph (PR_VALIDATOR C3): a changed
+// stylesheet must resolve to its importing routes, but a stylesheet imports nothing the route
+// graph cares about, so asset files are never parsed for specifiers. They participate in
+// resolution ONLY with an explicit extension (you write `import './x.module.css'`), never via
+// the extensionless inference used for source modules.
+export const ASSET_EXTS = ['.css', '.scss', '.sass', '.less'];
+const ASSET_EXT_SET     = new Set(ASSET_EXTS);
+const GRAPH_EXT_SET      = new Set([...SOURCE_EXTS, ...ASSET_EXTS]);
+
+// Directories never worth walking for app source.
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', '.next', '.nuxt', '.svelte-kit',
+  'dist', 'build', 'out', 'coverage', '.turbo', '.cache', '.vercel',
+]);
+
+const MAX_FILES      = 5000;          // bound the walk on a mega-repo
+const MAX_FILE_BYTES = 512 * 1024;    // skip giant generated/bundled files
+
+// Static specifier extractors. Targeted (not one mega-regex) to limit false matches.
+const SPECIFIER_RES = [
+  /\bimport\s+(?:[\w*${},\s]+\s+from\s+)?['"]([^'"]+)['"]/g, // import x from 'y' | import 'y'
+  /\bexport\s+(?:[\w*${},\s]+\s+)?from\s+['"]([^'"]+)['"]/g, // export … from 'y'
+  /\brequire\(\s*['"]([^'"]+)['"]\s*\)/g,                     // require('y')
+  /\bimport\(\s*['"]([^'"]+)['"]\s*\)/g,                      // dynamic import('y')
+];
+
+/**
+ * Extract the raw module specifiers referenced by a source file's text.
+ * Static parse only — template-string / computed specifiers are not detected (and are
+ * inherently unresolvable, so they fall into the caller's conservative bucket).
+ *
+ * @param {string} src
+ * @returns {string[]} de-duplicated specifier strings
+ */
+export function parseImports(src) {
+  if (typeof src !== 'string' || src.length === 0) return [];
+  const found = new Set();
+  for (const re of SPECIFIER_RES) {
+    re.lastIndex = 0;
+    for (const m of src.matchAll(re)) {
+      if (m[1]) found.add(m[1]);
+    }
+  }
+  return [...found];
+}
+
+/**
+ * Resolve a candidate path (without/with extension, or a directory) to a concrete source
+ * file on disk, applying extension inference and index-file resolution. Returns null when
+ * nothing matches.
+ */
+function resolveFileCandidate(candidate) {
+  try {
+    // Exact path with a known source OR asset extension (asset = a C3 stylesheet leaf, e.g.
+    // an explicit `import './x.module.css'`).
+    if (GRAPH_EXT_SET.has(path.extname(candidate)) && isFile(candidate)) return candidate;
+    // Extensionless import → try each source extension. (Stylesheets are always imported with
+    // their extension, so they never participate in this inference.)
+    for (const ext of SOURCE_EXTS) {
+      const withExt = candidate + ext;
+      if (isFile(withExt)) return withExt;
+    }
+    // Directory import → index.<ext>.
+    for (const idx of INDEX_BASENAMES) {
+      const indexed = path.join(candidate, idx);
+      if (isFile(indexed)) return indexed;
+    }
+  } catch { /* fall through to null */ }
+  return null;
+}
+
+function isFile(p) {
+  try { return fs.statSync(p).isFile(); } catch { return false; }
+}
+
+/**
+ * Read tsconfig.json / jsconfig.json `compilerOptions.paths` aliases (the common `@/*`
+ * style). Lenient: strips // and /* *​/ comments + trailing commas before parsing, and
+ * returns [] on any read/parse error so a missing or exotic config never throws.
+ *
+ * @param {string} rootDir
+ * @returns {Array<{ prefix: string, targets: string[] }>} prefix→absolute-dir aliases
+ */
+export function loadAliases(rootDir) {
+  for (const name of ['tsconfig.json', 'jsconfig.json']) {
+    const file = path.join(rootDir, name);
+    if (!isFile(file)) continue;
+    try {
+      const raw = fs.readFileSync(file, 'utf8');
+      const cleaned = raw
+        .replace(/\/\*[\s\S]*?\*\//g, '')      // block comments
+        .replace(/(^|[^:])\/\/.*$/gm, '$1')    // line comments (not URLs after ':')
+        .replace(/,(\s*[}\]])/g, '$1');        // trailing commas
+      const cfg     = JSON.parse(cleaned);
+      const co      = cfg.compilerOptions ?? {};
+      const baseUrl = path.resolve(rootDir, co.baseUrl ?? '.');
+      const paths   = co.paths ?? {};
+      const aliases = [];
+      for (const [key, targets] of Object.entries(paths)) {
+        if (!Array.isArray(targets) || targets.length === 0) continue;
+        const prefix = key.replace(/\*$/, '');               // "@/*" → "@/"
+        const absTargets = targets.map(t =>
+          path.resolve(baseUrl, String(t).replace(/\*$/, '')), // "src/*" → "<base>/src/"
+        );
+        aliases.push({ prefix, targets: absTargets });
+      }
+      // Longer prefixes first so "@/components/" wins over "@/".
+      aliases.sort((a, b) => b.prefix.length - a.prefix.length);
+      return aliases;
+    } catch (err) {
+      logger.debug(`[ARGUS] C1: could not parse ${name} for path aliases — ${err.message}`);
+      return [];
+    }
+  }
+  return [];
+}
+
+/**
+ * Resolve a single import specifier from a source file to an absolute on-disk source file,
+ * or null when it is a bare package import / unresolvable.
+ *
+ * @param {string} spec        the import specifier (e.g. "../components/Foo", "@/lib/api")
+ * @param {string} fromFileAbs absolute path of the importing file
+ * @param {Array<{prefix:string,targets:string[]}>} aliases  from loadAliases()
+ * @returns {string|null}
+ */
+export function resolveSpecifier(spec, fromFileAbs, aliases = []) {
+  if (typeof spec !== 'string' || spec.length === 0) return null;
+
+  // Relative import.
+  if (spec.startsWith('./') || spec.startsWith('../') || spec === '.' || spec === '..') {
+    return resolveFileCandidate(path.resolve(path.dirname(fromFileAbs), spec));
+  }
+
+  // tsconfig path alias.
+  for (const { prefix, targets } of aliases) {
+    if (prefix && spec.startsWith(prefix)) {
+      const rest = spec.slice(prefix.length);
+      for (const target of targets) {
+        const hit = resolveFileCandidate(path.join(target, rest));
+        if (hit) return hit;
+      }
+    }
+  }
+
+  // Bare package specifier (react, next/link, lodash/get, …) → not an app file.
+  return null;
+}
+
+/**
+ * Recursively collect graph files under dir — source modules plus C3 stylesheet leaves
+ * (bounded; skips SKIP_DIRS + symlinks).
+ */
+function collectSourceFiles(dir) {
+  const out = [];
+  const stack = [dir];
+  while (stack.length > 0 && out.length < MAX_FILES) {
+    const cur = stack.pop();
+    let entries;
+    try { entries = fs.readdirSync(cur, { withFileTypes: true }); } catch { continue; }
+    for (const entry of entries) {
+      if (entry.isSymbolicLink()) continue;             // avoid symlink cycles
+      const full = path.join(cur, entry.name);
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRS.has(entry.name)) stack.push(full);
+      } else if (GRAPH_EXT_SET.has(path.extname(entry.name))) {
+        out.push(full);
+        if (out.length >= MAX_FILES) break;
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Build the import graph for a source tree.
+ *
+ * @param {string} rootDir
+ * @returns {{ files: Set<string>,
+ *            forward: Map<string, Set<string>>,
+ *            reverse: Map<string, Set<string>>,
+ *            truncated: boolean }}
+ *   `forward[a]` = files a imports; `reverse[b]` = files that import b. Both keyed by
+ *   absolute path. `truncated` is true when the MAX_FILES cap was hit (the graph may be
+ *   incomplete → the caller must fall back conservatively).
+ */
+export function buildImportGraph(rootDir) {
+  const files     = new Set();
+  const forward   = new Map();
+  const reverse   = new Map();
+  const empty     = { files, forward, reverse, truncated: false };
+
+  if (typeof rootDir !== 'string' || !isDir(rootDir)) return empty;
+
+  const sourceFiles = collectSourceFiles(rootDir);
+  const truncated   = sourceFiles.length >= MAX_FILES;
+  const fileSet     = new Set(sourceFiles);
+  const aliases     = loadAliases(rootDir);
+
+  for (const file of sourceFiles) {
+    files.add(file);
+    if (!forward.has(file)) forward.set(file, new Set());
+
+    // C3: stylesheet leaves are graph NODES (so a changed stylesheet resolves + carries reverse
+    // edges from its importers) but import nothing the route graph tracks — never parse them.
+    if (ASSET_EXT_SET.has(path.extname(file))) continue;
+
+    let src;
+    try {
+      if (fs.statSync(file).size > MAX_FILE_BYTES) continue; // skip giant files
+      src = fs.readFileSync(file, 'utf8');
+    } catch { continue; }
+
+    for (const spec of parseImports(src)) {
+      const target = resolveSpecifier(spec, file, aliases);
+      if (!target || !fileSet.has(target)) continue;        // bare pkg or outside the tree
+      forward.get(file).add(target);
+      if (!reverse.has(target)) reverse.set(target, new Set());
+      reverse.get(target).add(file);
+    }
+  }
+
+  return { files, forward, reverse, truncated };
+}
+
+function isDir(p) {
+  try { return fs.statSync(p).isDirectory(); } catch { return false; }
+}
+
+/**
+ * Transitive reverse closure: every file that (directly or indirectly) imports any seed.
+ * Seeds themselves are NOT included unless they are reached via another importer.
+ *
+ * @param {Map<string, Set<string>>} reverse  reverse adjacency from buildImportGraph
+ * @param {Iterable<string>} seeds            absolute paths of changed files
+ * @returns {Set<string>} absolute paths of importing files
+ */
+export function findDependents(reverse, seeds) {
+  const dependents = new Set();
+  const stack = [...seeds];
+  const visited = new Set(stack);
+  while (stack.length > 0) {
+    const cur = stack.pop();
+    const importers = reverse.get(cur);
+    if (!importers) continue;
+    for (const imp of importers) {
+      if (!dependents.has(imp)) {
+        dependents.add(imp);
+        if (!visited.has(imp)) { visited.add(imp); stack.push(imp); }
+      }
+    }
+  }
+  return dependents;
+}

package/src/utils/issues-analyzer.js

@@ -31,7 +31,10 @@ const CLASSIFIERS = [
   {
     type:             'cors_violation',
     issueTypePattern: /cors/i,
-    textPattern:      /cors policy|cross.origin.*blocked|access.control.allow.origin/i,
+    // Live Chrome 149 surfaces CorsIssue in the panel as e.g.
+    // "Ensure CORS response header values are valid" — the older phrase-specific
+    // patterns missed it, so the \bcors\b word-match anchors any CORS issue title.
+    textPattern:      /cors policy|cross.origin.*blocked|access.control.allow.origin|\bcors\b/i,
     severity:         (isCritical) => isCritical ? 'critical' : 'warning',
   },
   {
@@ -49,7 +52,10 @@ const CLASSIFIERS = [
   {
     type:             'cookie_attribute_missing',
     issueTypePattern: /cookie/i,
-    textPattern:      /samesite|secure attribute|partitioned|cookie.*rejected|set-cookie.*blocked/i,
+    // Live Chrome 149 surfaces the SameSite=None-without-Secure cookie Issue as
+    // "Mark cross-site cookies as Secure to allow setting them in cross-site contexts"
+    // — neither "samesite" nor "secure attribute" appear, so match those phrasings too.
+    textPattern:      /samesite|secure attribute|partitioned|cookie.*rejected|set-cookie.*blocked|cross-site cookies?|cookies? as secure/i,
     severity:         () => 'warning',
   },
   {

package/src/utils/lighthouse-checker.js

@@ -5,12 +5,49 @@
  * checkLighthouse directly without pulling in the Slack-initialised orchestrator.
  */
 
+import fs from 'node:fs';
 import { registerExpensive } from '../registry.js';
 import { thresholds }        from '../config/targets.js';
 import { childLogger }       from './logger.js';
 
 const logger = childLogger('lighthouse-checker');
 
+/**
+ * Parse a chrome-devtools-mcp `lighthouse_audit` response into the Lighthouse
+ * result shape this module consumes: `{ categories, audits }` (category scores 0–1,
+ * `audits` keyed by id). The tool returns markdown with a "### Reports" section that
+ * points at a full `report.json`; we read that for complete category scores +
+ * per-audit detail (`auditRefs`, `title`, `description`). If the file is unavailable
+ * we fall back to the markdown "### Category Scores" block (scores only, no audits).
+ * Returns `{ categories: {}, audits: {} }` when nothing parses — never throws.
+ *
+ * @param {string} responseText - raw lighthouse_audit response (markdown text)
+ * @returns {{ categories: object, audits: object }}
+ */
+export function parseLighthouseReport(responseText) {
+  const text = String(responseText ?? '');
+  // Prefer the authoritative report.json (categories + auditRefs + per-audit detail).
+  const pathMatch = text.match(/([A-Za-z]:\\[^\r\n]*?report\.json|\/[^\r\n]*?report\.json)/);
+  if (pathMatch) {
+    try {
+      const json = JSON.parse(fs.readFileSync(pathMatch[1].trim(), 'utf8'));
+      if (json && typeof json === 'object' && json.categories) {
+        return { categories: json.categories, audits: json.audits ?? {} };
+      }
+    } catch { /* fall through to the markdown scores */ }
+  }
+  // Fallback: synthesize categories from the "### Category Scores" markdown block,
+  // e.g. "- Accessibility: 96 (accessibility)". Scores normalised to 0–1 to match report.json.
+  const categories = {};
+  const block = text.match(/### Category Scores\s*\n([\s\S]*?)(?:\n###|\s*$)/);
+  if (block) {
+    for (const m of block[1].matchAll(/^\s*-\s+.+?:\s*([\d.]+)\s*\(([\w-]+)\)\s*$/gm)) {
+      categories[m[2]] = { id: m[2], score: Number(m[1]) / 100 };
+    }
+  }
+  return { categories, audits: {} };
+}
+
 const LIGHTHOUSE_LABELS = {
   accessibility:    'Accessibility',
   performance:      'Performance',
@@ -39,13 +76,16 @@ export async function checkLighthouse(browser, url) {
   const LIGHTHOUSE_TIMEOUT_MS = parseInt(process.env.ARGUS_LIGHTHOUSE_TIMEOUT ?? '120000', 10);
 
   try {
-    const auditPromise = browser.lighthouse(url, {
-      categories: ['accessibility', 'performance', 'seo', 'best-practices'],
-    });
+    // browser.lighthouse navigates to url + audits the current page. lighthouse_audit
+    // returns markdown referencing a full report.json — parseLighthouseReport reads that
+    // back into the { categories, audits } shape this function consumes. Performance is
+    // excluded by the tool (covered by web-vitals); thresholds.lighthouse.performance is
+    // simply skipped below when its category is absent.
+    const auditPromise = browser.lighthouse(url);
     const timeoutPromise = new Promise((_, reject) =>
       setTimeout(() => reject(new Error(`Lighthouse timed out after ${LIGHTHOUSE_TIMEOUT_MS / 1000}s`)), LIGHTHOUSE_TIMEOUT_MS)
     );
-    const result = await Promise.race([auditPromise, timeoutPromise]);
+    const result = parseLighthouseReport(await Promise.race([auditPromise, timeoutPromise]));
 
     const categories = result?.categories ?? {};
     const audits     = result?.audits     ?? {};

package/src/utils/parallel-crawler.js

@@ -26,3 +26,205 @@ export function chunkArray(arr, n) {
   for (let i = 0; i < arr.length; i += size) chunks.push(arr.slice(i, i + size));
   return chunks;
 }
+
+// NOTE: this module is imported by mcp-server.js (via the PR-validate path) and by the
+// orchestrator. It MUST stay stdout-clean (no console.log) — stdout is reserved for JSON-RPC.
+
+/**
+ * Map `worker` over `items` with bounded concurrency, returning results in INPUT order
+ * (results[i] ⟷ items[i]) regardless of completion order — so the output is identical to a
+ * sequential `for…of` map. This is the safety property the PR Validator relies on: the
+ * aggregate findings and the merge-block decision must not depend on how routes interleave.
+ *
+ * Spawns exactly `min(concurrency, items.length)` persistent lanes; each lane repeatedly pulls
+ * the next item from a shared cursor (the read-then-increment `cursor++` is atomic on the
+ * single-threaded event loop — there is no await between the read and the bump, so two lanes can
+ * never claim the same index). The lane index (0…lanes-1) is passed to `worker` so a caller can
+ * pin a per-lane resource — e.g. one Chrome client per lane — and be sure it is never used by two
+ * items at once.
+ *
+ * Errors: if a `worker` call rejects, its result slot is left `undefined`, the OTHER in-flight
+ * items still drain to completion, and the FIRST rejection is re-thrown after every lane finishes
+ * (fail-loud — a parallel error is never silently dropped). Callers that need per-item error
+ * handling (e.g. recording a per-route audit failure) should catch inside `worker` and return an
+ * error marker instead of throwing.
+ *
+ * @template T, R
+ * @param {T[]} items
+ * @param {number} concurrency  max parallel workers; effective lanes = min(concurrency, items.length)
+ * @param {(item: T, index: number, lane: number) => Promise<R>} worker
+ * @returns {Promise<R[]>} results in input order
+ */
+export async function mapWithConcurrency(items, concurrency, worker) {
+  if (!Array.isArray(items)) throw new TypeError('mapWithConcurrency: items must be an array');
+  if (typeof worker !== 'function') throw new TypeError('mapWithConcurrency: worker must be a function');
+  if (!Number.isInteger(concurrency) || concurrency <= 0) {
+    throw new RangeError('mapWithConcurrency: concurrency must be a positive integer');
+  }
+
+  const results = new Array(items.length);
+  if (items.length === 0) return results;
+
+  const lanes = Math.min(concurrency, items.length);
+  let cursor = 0;
+  let firstError = null;
+
+  async function runLane(lane) {
+    for (let index = cursor++; index < items.length; index = cursor++) {
+      try {
+        results[index] = await worker(items[index], index, lane);
+      } catch (err) {
+        if (firstError === null) firstError = err;
+        // keep draining the remaining items so siblings finish; this slot stays undefined
+      }
+    }
+  }
+
+  await Promise.all(Array.from({ length: lanes }, (_unused, lane) => runLane(lane)));
+  if (firstError !== null) throw firstError;
+  return results;
+}
+
+/**
+ * Audit `routes` with bounded concurrency, giving each lane its OWN client, and return the
+ * per-route results in INPUT (route) order — identical to a sequential crawl.
+ *
+ * `crawlRouteCheap` mutates page-navigation state, so two concurrent crawls must never share a
+ * Chrome connection. This wrapper allocates one client per lane: lane 0 reuses `primaryClient`
+ * (the already-open connection); lanes 1…n-1 each get a fresh client from `createClient()`.
+ * Because a lane processes one route at a time, a given client is never used by two routes at
+ * once. The extra clients are always closed in a `finally` (via `closeClient`, default
+ * `client.close()`); `primaryClient` is owned by the caller and is NOT closed here.
+ *
+ * `crawlRoute` should handle its own per-route errors (catch + return a marker) so one route's
+ * failure does not abort its siblings and the all-routes-failed guard still sees every route.
+ *
+ * @param {Array} routes  [] returns [] with no clients created
+ * @param {object} opts
+ * @param {number}   opts.concurrency    desired max parallel clients; lanes = min(concurrency, routes.length)
+ * @param {*}        opts.primaryClient  the already-open client used by lane 0
+ * @param {() => Promise<*>} opts.createClient  factory for lanes 1…n-1 (only called when lanes > 1)
+ * @param {(route: any, client: any, meta: { index: number, lane: number }) => Promise<any>} opts.crawlRoute
+ * @param {(client: any) => any} [opts.closeClient]  teardown for the extra clients (default: client.close())
+ * @returns {Promise<Array>} results in route order
+ */
+export async function auditRoutesConcurrently(routes, { concurrency, primaryClient, createClient, crawlRoute, closeClient } = {}) {
+  if (!Array.isArray(routes)) throw new TypeError('auditRoutesConcurrently: routes must be an array');
+  if (typeof crawlRoute !== 'function') throw new TypeError('auditRoutesConcurrently: crawlRoute must be a function');
+  if (routes.length === 0) return [];
+
+  const want  = Number.isInteger(concurrency) && concurrency > 0 ? concurrency : 1;
+  const lanes = Math.min(want, routes.length);
+  const extraClients = [];
+  const close = typeof closeClient === 'function' ? closeClient : (c) => c?.close?.();
+
+  try {
+    for (let i = 1; i < lanes; i++) {
+      if (typeof createClient !== 'function') {
+        throw new TypeError('auditRoutesConcurrently: createClient is required when concurrency > 1');
+      }
+      extraClients.push(await createClient());
+    }
+    const clients = [primaryClient, ...extraClients];
+    return await mapWithConcurrency(
+      routes, lanes,
+      (route, index, lane) => crawlRoute(route, clients[lane], { index, lane }),
+    );
+  } finally {
+    for (const client of extraClients) {
+      try { await close(client); } catch { /* ignore teardown errors */ }
+    }
+  }
+}
+
+// ── D4 — per-route timeout / retry ────────────────────────────────────────────
+// A hung or flaky route audit must surface as a REJECTION, never a silent zero-findings
+// resolution — the caller records the rejection as a route ERROR, which feeds the
+// all-routes-failed guard (src/cli/pr-validate.js allRoutesFailed). These helpers therefore
+// never resolve on timeout; a timed-out audit can never become a false PASS.
+
+/**
+ * Race `work` against a timeout. If `ms` elapses before the work settles, the returned promise
+ * REJECTS with a timeout Error — it NEVER resolves on timeout. This is the load-bearing safety
+ * property of the PR Validator's per-route audit: a hung audit must surface as a rejection
+ * (→ recorded as a route ERROR → fed to the all-routes-failed guard), never as a silently
+ * passing zero-findings route (a false PASS).
+ *
+ * A non-finite or non-positive `ms` disables the bound (the work is awaited as-is). The timer is
+ * cleared once the work settles so it never keeps the event loop alive; the underlying work is
+ * NOT cancelled (there is no abort channel through CDP) — the timer only stops US from waiting.
+ *
+ * @template R
+ * @param {Promise<R> | (() => Promise<R>)} work  a promise, or a thunk returning one (a thunk's
+ *   synchronous throw is converted to a rejection)
+ * @param {number} ms        timeout in milliseconds (<=0 / non-finite → unbounded)
+ * @param {string} [label]   human-readable label used in the timeout message
+ * @returns {Promise<R>}
+ */
+export function withTimeout(work, ms, label = 'operation') {
+  // Wrapping a thunk in an async IIFE turns a synchronous throw into a rejection.
+  const promise = typeof work === 'function' ? (async () => work())() : Promise.resolve(work);
+  if (!Number.isFinite(ms) || ms <= 0) return promise;
+  let timer;
+  const timeout = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
+  });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+
+/**
+ * Run a single route audit with a per-attempt timeout and bounded retries. Returns the audit
+ * result on the first success; THROWS (fail-loud) if every attempt times out or errors, so the
+ * caller's per-route catch records a route ERROR (never a false PASS). With the defaults
+ * (1 attempt, unbounded) this is byte-identical to calling `auditFn()` directly.
+ *
+ * Retries are immediate (no backoff): a route audit re-navigates from a clean state, so a fixed
+ * inter-attempt delay would only add wall-clock without changing a deterministic failure. This is
+ * deliberately distinct from withRetry() (retry.js), which back-off-retries idempotent CDP ops;
+ * a route audit needs a per-ATTEMPT timeout plus a route-scoped retry count.
+ *
+ * @template R
+ * @param {() => Promise<R>} auditFn   the per-route audit, e.g. () => crawlRouteWithDepth(route, …)
+ * @param {object} opts
+ * @param {number} [opts.timeoutMs=0]  per-attempt timeout (<=0 / non-finite → unbounded)
+ * @param {number} [opts.retries=0]    additional attempts after the first (total = retries + 1)
+ * @param {string} [opts.label]        label used in the timeout message
+ * @param {(attempt: number, err: Error) => void} [opts.onRetry]  invoked before each retry
+ * @returns {Promise<R>}
+ */
+export async function auditRouteWithRetry(auditFn, { timeoutMs = 0, retries = 0, label = 'route audit', onRetry } = {}) {
+  if (typeof auditFn !== 'function') throw new TypeError('auditRouteWithRetry: auditFn must be a function');
+  const attempts = Math.max(1, Math.floor(Number.isFinite(retries) ? retries : 0) + 1);
+  let lastErr;
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    try {
+      return await withTimeout(auditFn, timeoutMs, label);
+    } catch (err) {
+      lastErr = err;
+      if (attempt < attempts && typeof onRetry === 'function') {
+        try { onRetry(attempt, err); } catch { /* a logging callback must never break the retry loop */ }
+      }
+    }
+  }
+  throw lastErr;
+}
+
+/**
+ * Resolve the per-route audit timeout + retry policy from the environment. Shared by BOTH
+ * PR-validate paths (CLI + the MCP tool) so they cannot diverge on the bound.
+ *   ARGUS_ROUTE_TIMEOUT_MS — per-route audit timeout (default 120000 ms; explicit 0 / negative →
+ *     unbounded; unset or non-numeric → the 120000 default, the safe bounded direction).
+ *   ARGUS_ROUTE_RETRIES    — extra attempts on a failed/timed-out audit (default 0; clamped 0–5).
+ * A timed-out audit is recorded as a route ERROR and feeds the all-routes-failed guard — bounding
+ * a route can only BLOCK (the conservative direction), never produce a false PASS.
+ *
+ * @param {Record<string, string|undefined>} [env=process.env]
+ * @returns {{ timeoutMs: number, retries: number }}
+ */
+export function routeResilienceFromEnv(env = process.env) {
+  const rawTimeout = parseInt(env.ARGUS_ROUTE_TIMEOUT_MS, 10);
+  const timeoutMs  = Number.isNaN(rawTimeout) ? 120000 : (rawTimeout > 0 ? rawTimeout : 0);
+  const rawRetries = parseInt(env.ARGUS_ROUTE_RETRIES, 10);
+  const retries    = Number.isNaN(rawRetries) ? 0 : Math.min(5, Math.max(0, rawRetries));
+  return { timeoutMs, retries };
+}