argusqa-os 9.7.6 → 9.8.0

package/src/utils/github-api.js

@@ -0,0 +1,242 @@
+/**
+ * Shared resilient GitHub REST client for the PR Validator (Phase E2).
+ *
+ * One place that BOTH GitHub throw-path callers route through — fetchPrFiles
+ * (pr-diff-analyzer.js, the PR diff) and ghFetch (github-reporter.js, the PR
+ * comment / Check Run) — so the two paths can never diverge on resilience.
+ * Mirrors the "one shared decision" discipline of decidePrBlock (B1) /
+ * selectAnalyzers (D2) / resolveTargetUrl (D3) / routeResilienceFromEnv (D4).
+ *
+ * What it does:
+ *   - retries a 403 PRIMARY rate-limit (X-RateLimit-Remaining: 0), a 403/429
+ *     SECONDARY rate-limit (Retry-After), a transient 5xx, and a network error,
+ *     with backoff that honours Retry-After / X-RateLimit-Reset when present;
+ *   - NEVER retries a 401 / 404 / 422 / plain-403 (permissions) — those are
+ *     terminal and throw a structured, cause-carrying error immediately;
+ *   - keeps every thrown message SECRET-FREE: the token rides only in request
+ *     headers (never the response body), and scrubSecrets() defensively redacts
+ *     any Bearer / ghp_ / github_pat_ token that somehow appears in a body.
+ *
+ * deploy-preview.js's Deployments probe is deliberately NOT routed through here:
+ * it is fail-safe-to-null + opt-in (D3) and must degrade fast, not retry.
+ *
+ * Pure helpers + one fetch wrapper. No Chrome, no MCP, no AI verdict. Imported
+ * (transitively) by the MCP server → nothing here writes to stdout.
+ */
+
+/** Default per-request timeout (ms) — matches the prior ghFetch behaviour. */
+const DEFAULT_TIMEOUT_MS = 15000;
+/** Default backoff base (ms) for the exponential fallback. */
+const DEFAULT_BASE_MS = 1000;
+/**
+ * Cap on any single backoff wait (ms). A far-future X-RateLimit-Reset (the GitHub
+ * primary-limit window can be up to an hour) must NOT hang CI for the whole window —
+ * we cap, retry sooner, and fail loud if still limited. A capped retry that throws a
+ * clear "rate limit exceeded — retries exhausted" beats a multi-minute silent stall.
+ */
+const DEFAULT_MAX_MS = 8000;
+/** Default total attempts (1 initial + 2 retries). */
+const DEFAULT_MAX_ATTEMPTS = 3;
+
+/**
+ * Read a header case-insensitively from a Headers object (fetch Response.headers,
+ * which exposes .get()) OR a plain object (used by test stubs). Returns the string
+ * value or undefined — never throws on a missing/odd headers bag.
+ *
+ * @param {Headers|Record<string,string>|undefined} headers
+ * @param {string} name
+ * @returns {string|undefined}
+ */
+export function headerValue(headers, name) {
+  if (!headers) return undefined;
+  const key = String(name).toLowerCase();
+  if (typeof headers.get === 'function') {
+    return headers.get(name) ?? headers.get(key) ?? undefined;
+  }
+  for (const k of Object.keys(headers)) {
+    if (k.toLowerCase() === key) return headers[k];
+  }
+  return undefined;
+}
+
+/**
+ * Redact any GitHub token shape from a string. The token is sent only in request
+ * headers, so a response body never contains it — this is belt-and-suspenders so a
+ * thrown error message can NEVER leak a credential even if a body echoes one.
+ *
+ * @param {*} text
+ * @returns {string}
+ */
+export function scrubSecrets(text) {
+  return String(text ?? '')
+    .replace(/Bearer\s+[A-Za-z0-9._~+/=-]+/gi, 'Bearer ***')
+    .replace(/\bgithub_pat_[A-Za-z0-9_]{20,}/g, '***')   // fine-grained PAT (has underscores)
+    .replace(/\bgh[posru]_[A-Za-z0-9_]{10,}/g, '***');   // ghp_ gho_ ghs_ ghr_ ghu_
+}
+
+/**
+ * Classify a response as a GitHub rate-limit (so it should be retried with backoff).
+ *   - 429                                   → always a rate-limit (secondary).
+ *   - 403 with X-RateLimit-Remaining === 0  → primary rate-limit exhausted.
+ *   - 403 with a Retry-After header          → secondary rate-limit.
+ * A plain 403 with no rate-limit signal is a PERMISSIONS error — not retried.
+ *
+ * @param {number} status
+ * @param {Headers|Record<string,string>|undefined} headers
+ * @returns {boolean}
+ */
+export function isRateLimitResponse(status, headers) {
+  if (status === 429) return true;
+  if (status === 403) {
+    const remaining = headerValue(headers, 'x-ratelimit-remaining');
+    if (remaining !== undefined && remaining !== null && Number(remaining) === 0) return true;
+    if (headerValue(headers, 'retry-after') !== undefined) return true;
+  }
+  return false;
+}
+
+/**
+ * Compute the backoff (ms) before the next attempt. Honours GitHub's explicit
+ * signals first (Retry-After seconds, then X-RateLimit-Reset epoch seconds),
+ * falling back to exponential backoff. Every result is capped at maxMs.
+ *
+ * @param {number} status   HTTP status (0 for a network error)
+ * @param {Headers|Record<string,string>|undefined} headers
+ * @param {number} attempt  1-based attempt number that just failed
+ * @param {{ baseMs?: number, maxMs?: number, now?: () => number }} [opts]
+ * @returns {number}
+ */
+export function retryDelayMs(status, headers, attempt, opts = {}) {
+  const { baseMs = DEFAULT_BASE_MS, maxMs = DEFAULT_MAX_MS, now = Date.now } = opts;
+
+  const retryAfter = headerValue(headers, 'retry-after');
+  if (retryAfter !== undefined && retryAfter !== null && String(retryAfter).trim() !== '') {
+    const secs = Number(retryAfter);
+    if (Number.isFinite(secs) && secs >= 0) return Math.min(secs * 1000, maxMs);
+  }
+
+  if (isRateLimitResponse(status, headers)) {
+    const reset = headerValue(headers, 'x-ratelimit-reset');
+    if (reset !== undefined) {
+      const resetMs = Number(reset) * 1000 - now();
+      if (Number.isFinite(resetMs) && resetMs > 0) return Math.min(resetMs, maxMs);
+    }
+  }
+
+  const exp = baseMs * Math.pow(2, Math.max(0, attempt - 1));
+  return Math.min(exp, maxMs);
+}
+
+/**
+ * Build a structured, secret-free error message for a TERMINAL (non-retried)
+ * GitHub response. Carries the cause (status + a short, scrubbed body) and a
+ * human hint for the common cases — never the token, never "is not defined".
+ *
+ * @param {number} status
+ * @param {string} [statusText]
+ * @param {string} [bodyText]
+ * @param {string} [context]  e.g. "GET /repos/o/r/pulls/7/files"
+ * @returns {string}
+ */
+export function classifyGitHubError(status, statusText, bodyText, context) {
+  const ctx  = context ? ` (${context})` : '';
+  const body = scrubSecrets(String(bodyText ?? '').replace(/\s+/g, ' ').trim()).slice(0, 300);
+  const tail = body ? `: ${body}` : (statusText ? `: ${statusText}` : '');
+  switch (status) {
+    case 401:
+      return `GitHub API 401 (bad credentials)${ctx} — the token is missing, invalid, or expired${tail}`;
+    case 403:
+      return `GitHub API 403 (forbidden)${ctx} — the token lacks the required scope or resource access${tail}`;
+    case 404:
+      return `GitHub API 404 (not found)${ctx} — check the repository and PR exist and the token can access them${tail}`;
+    case 422:
+      return `GitHub API 422 (unprocessable)${ctx} — GitHub rejected the request${tail}`;
+    default:
+      return `GitHub API ${status}${ctx}${tail}`;
+  }
+}
+
+async function safeText(res) {
+  try {
+    return res && typeof res.text === 'function' ? await res.text() : '';
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Resilient GitHub REST request. Resolves to the OK Response (caller reads
+ * .json() / paginates) or THROWS a structured, secret-free Error. See the module
+ * header for the retry vs throw policy.
+ *
+ * @param {string} url
+ * @param {object} [opts]
+ * @param {string} [opts.method='GET']
+ * @param {Record<string,string>} [opts.headers]
+ * @param {string} [opts.body]              already-serialised body (or undefined)
+ * @param {number} [opts.maxAttempts=3]
+ * @param {number} [opts.baseMs=1000]
+ * @param {number} [opts.maxMs=8000]
+ * @param {number} [opts.timeoutMs=15000]   per-attempt timeout; <=0 disables
+ * @param {(ms:number)=>Promise<void>} [opts.sleep]  injectable for tests
+ * @param {()=>number} [opts.now]           injectable clock for backoff math
+ * @param {(url:string,init:object)=>Promise<Response>} [opts.fetchImpl]
+ * @param {string} [opts.context]           label woven into error messages
+ * @returns {Promise<Response>}
+ */
+export async function githubFetch(url, opts = {}) {
+  const {
+    method = 'GET', headers, body,
+    maxAttempts = DEFAULT_MAX_ATTEMPTS,
+    baseMs = DEFAULT_BASE_MS, maxMs = DEFAULT_MAX_MS, timeoutMs = DEFAULT_TIMEOUT_MS,
+    sleep = (ms) => new Promise(r => setTimeout(r, ms)),
+    now = Date.now,
+    fetchImpl,
+    context,
+  } = opts;
+
+  const doFetch = fetchImpl ?? ((u, init) => fetch(u, init));
+  const ctx = context ? ` (${context})` : '';
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    let res;
+    try {
+      res = await doFetch(url, {
+        method, headers, body,
+        signal: timeoutMs > 0 ? AbortSignal.timeout(timeoutMs) : undefined,
+      });
+    } catch (err) {
+      // Network error / timeout — retry with backoff, else fail loud (secret-free).
+      if (attempt < maxAttempts) {
+        await sleep(retryDelayMs(0, null, attempt, { baseMs, maxMs, now }));
+        continue;
+      }
+      throw new Error(scrubSecrets(`GitHub API request failed${ctx}: ${err.message}`));
+    }
+
+    if (res.ok) return res;
+
+    const status = res.status;
+    const rateLimited = isRateLimitResponse(status, res.headers);
+    const transient = rateLimited || status >= 500;
+
+    if (transient && attempt < maxAttempts) {
+      await sleep(retryDelayMs(status, res.headers, attempt, { baseMs, maxMs, now }));
+      continue;
+    }
+
+    // Terminal: read the body once and throw a structured, secret-free error.
+    const bodyText = await safeText(res);
+    if (rateLimited) {
+      const body = scrubSecrets(String(bodyText ?? '').replace(/\s+/g, ' ').trim()).slice(0, 300);
+      throw new Error(
+        `GitHub API ${status} (rate limit exceeded)${ctx} — retries exhausted after ${attempt} attempt(s)` +
+        (body ? `: ${body}` : ''),
+      );
+    }
+    throw new Error(classifyGitHubError(status, res.statusText, bodyText, context));
+  }
+
+  // Defensive — the loop above always returns or throws.
+  throw new Error(`GitHub API request failed${ctx} — retries exhausted`);
+}

package/src/utils/github-reporter.js

@@ -27,6 +27,8 @@
  */
 
 import { childLogger } from './logger.js';
+import { parsePrUrl } from './pr-diff-analyzer.js';
+import { githubFetch } from './github-api.js';
 
 const logger = childLogger('github-reporter');
 
@@ -44,6 +46,45 @@ function mdCell(text, maxLen = 100) {
   return String(text ?? '').slice(0, maxLen).replace(/\|/g, '\\|').replace(/\n/g, ' '); // lgtm[js/incomplete-string-escaping] — escaping pipe and newline is correct and sufficient for GitHub Markdown table cells
 }
 
+/**
+ * Build the PR-Validator banner lines (block verdict + reason + affected routes).
+ * Rendered at the top of the comment only when report.prValidation is present, so
+ * existing runCrawl()-sourced reports are unaffected.
+ */
+function prValidationBanner(pv) {
+  const bl = pv.baseline;
+  const baselineAware = !!(bl && bl.available);
+  const lines = [
+    pv.blocked
+      ? `> 🔴 **Merge blocked** — ${pv.reason} (block-on: \`${pv.blockOn}\`)`
+      : baselineAware
+        ? `> ✅ **Merge allowed** — this PR introduces no findings at or above the \`${pv.blockOn}\` threshold`
+        : `> ✅ **Merge allowed** — no findings at or above the \`${pv.blockOn}\` threshold`,
+  ];
+  // Baseline-aware surfacing (Phase B2): what this PR INTRODUCES vs what already existed on the
+  // affected routes, so a reviewer sees why the merge was (or wasn't) blocked. When no per-branch
+  // baseline was available the decision fell back to absolute counts — say so, never silently.
+  if (baselineAware) {
+    lines.push(
+      '',
+      'Blocking on findings this PR **introduces** (vs the base-branch baseline):  ',
+      `🔴 ${bl.newCritical} new critical · 🟡 ${bl.newWarning} new warning · 🔵 ${bl.newInfo} new info · ${bl.persisting} persisting · ${bl.resolved} resolved  `,
+    );
+  } else if (bl && bl.available === false) {
+    lines.push('', `> ⚠️ ${bl.note ?? 'Baseline unavailable — blocking on absolute finding counts.'}  `);
+  }
+  if (Array.isArray(pv.affectedRoutes) && pv.affectedRoutes.length > 0) {
+    const shown = pv.affectedRoutes.slice(0, 20).map(r => `\`${r}\``).join(', ');
+    const extra = pv.affectedRoutes.length > 20 ? ` _(+${pv.affectedRoutes.length - 20} more)_` : '';
+    lines.push('', `**Affected routes** (${pv.affectedRoutes.length}): ${shown}${extra}  `);
+  }
+  if (typeof pv.changedFileCount === 'number') {
+    lines.push(`**Files changed**: ${pv.changedFileCount}  `);
+  }
+  lines.push('');
+  return lines;
+}
+
 // ── C2.1: PR comment formatter (pure — no I/O) ───────────────────────────────
 
 /**
@@ -89,6 +130,7 @@ export function formatPrComment(report, diff) {
     `**Base URL**: ${baseUrl}  `,
     `**Run time**: ${runDate}  `,
     '',
+    ...(report.prValidation ? prValidationBanner(report.prValidation) : []),
     '| | 🔴 Critical | 🟡 Warning | 🔵 Info | Total |',
     '|---|---|---|---|---|',
     `| **Total** | ${summary.critical} | ${summary.warning} | ${summary.info} | ${summary.total} |`,
@@ -217,7 +259,7 @@ export function buildStatusPayload(report, diff) {
 
 // ── GitHub API helper ─────────────────────────────────────────────────────────
 
-async function ghFetch(urlPath, method, body, attempt = 1) {
+async function ghFetch(urlPath, method, body) {
   if (!process.env.GITHUB_TOKEN) {
     throw new Error('GITHUB_TOKEN environment variable is not set — GitHub reporting is disabled');
   }
@@ -228,33 +270,16 @@ async function ghFetch(urlPath, method, body, attempt = 1) {
   };
   if (body) headers['Content-Type'] = 'application/json';
 
-  let res;
-  try {
-    res = await fetch(`${GITHUB_API}${urlPath}`, {
-      method,
-      headers,
-      body: body ? JSON.stringify(body) : undefined,
-      signal: AbortSignal.timeout(15000),
-    });
-  } catch (err) {
-    // Network error or timeout — retry up to 3 times with exponential backoff
-    if (attempt < 3) {
-      await new Promise(r => setTimeout(r, attempt * 1000));
-      return ghFetch(urlPath, method, body, attempt + 1);
-    }
-    throw err;
-  }
-
-  // Retry on transient server errors (5xx) and rate-limit (429) with exponential backoff
-  if ((res.status >= 500 || res.status === 429) && attempt < 3) {
-    await new Promise(r => setTimeout(r, attempt * 1000));
-    return ghFetch(urlPath, method, body, attempt + 1);
-  }
-
-  if (!res.ok) {
-    const text = await res.text().catch(() => '');
-    throw new Error(`GitHub API ${method} ${urlPath} → ${res.status}: ${text.slice(0, 200)}`);
-  }
+  // E2: shared resilient client — retries a rate-limit (403 primary / 429 secondary)
+  // + transient 5xx + network error with backoff (Retry-After / X-RateLimit-Reset
+  // aware), throws a structured, secret-free error on 401/404/422/plain-403. The token
+  // rides only in the request headers above, never in any thrown message.
+  const res = await githubFetch(`${GITHUB_API}${urlPath}`, {
+    method,
+    headers,
+    body: body ? JSON.stringify(body) : undefined,
+    context: `${method} ${urlPath}`,
+  });
   return res.json();
 }
 
@@ -264,9 +289,9 @@ async function ghFetch(urlPath, method, body, attempt = 1) {
  * Create a PR comment, or update the existing Argus comment if one is already present.
  * Idempotent: re-running on the same PR updates in-place rather than spamming new comments.
  */
-export async function postPrComment(report, diff) {
-  const repo  = process.env.GITHUB_REPOSITORY;
-  const prNum = process.env.GITHUB_PR_NUMBER;
+export async function postPrComment(report, diff, opts = {}) {
+  const repo  = opts.repo     ?? process.env.GITHUB_REPOSITORY;
+  const prNum = opts.prNumber ?? process.env.GITHUB_PR_NUMBER;
   if (!repo || !prNum) throw new Error('[ARGUS] C2: GITHUB_REPOSITORY or GITHUB_PR_NUMBER not set');
 
   let body = formatPrComment(report, diff);
@@ -322,10 +347,14 @@ export async function setCommitStatus(report, diff) {
  *
  * @param {string} [name]   - Check run name (default: GITHUB_CHECK_NAME ?? 'argus-qa')
  * @param {string} [sha]    - Commit SHA (default: GITHUB_SHA env var)
+ * @param {object} [opts]
+ * @param {string} [opts.repo] - "owner/repo" override (default: GITHUB_REPOSITORY env var).
+ *                               Lets callers that resolved the repo from a PR URL (the PR
+ *                               Validator) drive the Check Run without relying on env.
  * @returns {Promise<number>} check run id
  */
-export async function createCheckRun(name, sha) {
-  const repo    = process.env.GITHUB_REPOSITORY;
+export async function createCheckRun(name, sha, opts = {}) {
+  const repo    = opts.repo ?? process.env.GITHUB_REPOSITORY;
   const headSha = sha ?? process.env.GITHUB_SHA;
   if (!repo || !headSha) throw new Error('[ARGUS] C2: GITHUB_REPOSITORY or GITHUB_SHA not set');
 
@@ -352,13 +381,30 @@ export async function createCheckRun(name, sha) {
  * @param {number} checkRunId - id from createCheckRun()
  * @param {object} report     - runCrawl() report
  * @param {object|null} diff  - baseline diff (null = first run)
+ * @param {object} [opts]
+ * @param {string} [opts.repo] - "owner/repo" override (default: GITHUB_REPOSITORY env var)
  */
-export async function completeCheckRun(checkRunId, report, diff) {
-  const repo = process.env.GITHUB_REPOSITORY;
+export async function completeCheckRun(checkRunId, report, diff, opts = {}) {
+  const repo = opts.repo ?? process.env.GITHUB_REPOSITORY;
   if (!repo) throw new Error('[ARGUS] C2: GITHUB_REPOSITORY not set');
 
-  const status = buildStatusPayload(report, diff);
-  const conclusion = status.state === 'success' ? 'success' : 'failure';
+  // The conclusion must reflect the merge gate. For a PR-Validator report the authoritative
+  // gate is the block-on decision (report.prValidation.blocked), NOT buildStatusPayload's
+  // new-criticals-vs-ARGUS_CRITICAL_THRESHOLD rule — the two diverge (e.g. block-on=warning
+  // with 0 criticals blocks the merge but has 0 new criticals). runCrawl reports carry no
+  // prValidation field, so they keep the existing threshold-based conclusion.
+  let conclusion, title;
+  const pv = report.prValidation;
+  if (pv) {
+    conclusion = pv.blocked ? 'failure' : 'success';
+    title      = pv.blocked
+      ? `Argus: merge blocked — ${pv.reason}`
+      : `Argus: merge allowed — no findings at or above block-on=${pv.blockOn}`;
+  } else {
+    const status = buildStatusPayload(report, diff);
+    conclusion   = status.state === 'success' ? 'success' : 'failure';
+    title        = status.description;
+  }
 
   // Build rich text output (full findings table, without the COMMENT_MARKER sentinel)
   const fullBody = formatPrComment(report, diff);
@@ -371,8 +417,8 @@ export async function completeCheckRun(checkRunId, report, diff) {
     conclusion,
     completed_at: new Date().toISOString(),
     output: {
-      title:   status.description,
-      summary: status.description,
+      title:   title.slice(0, 255),       // GitHub Check output.title limit
+      summary: title,
       text:    richText,
     },
   });
@@ -511,3 +557,169 @@ export async function reportToGitHub(report, diff) {
 
   await Promise.all(tasks);
 }
+
+// ── PR Validator reporting (Phase A) ──────────────────────────────────────────
+
+/**
+ * Adapt a PR-Validator result (the src/cli/pr-validate.js + argus_pr_validate response
+ * shape) into the `report` object that formatPrComment / buildStatusPayload consume.
+ * Pure — no I/O.
+ *
+ * The PR Validator has no per-run baseline yet (Phase B introduces head-vs-base
+ * diffing), so every finding on an affected route is surfaced as-is; callers pair this
+ * with a NON-first `diff` (see reportPrValidation) so formatPrComment renders the
+ * findings table rather than treating the run as a baseline-establishing first run.
+ *
+ * @param {object} result
+ * @param {string} [result.targetUrl]
+ * @param {{ critical: number, warning: number, info: number }} [result.summary]
+ * @param {Array<{ severity: string, type: string, message: string, url: string }>} [result.findings]
+ * @param {string[]} [result.affectedRoutes]
+ * @param {string[]} [result.changedFiles]
+ * @param {boolean} [result.blocked]
+ * @param {string}  [result.blockOn]
+ * @returns {object} report consumable by formatPrComment
+ */
+export function prResultToReport(result = {}) {
+  const {
+    targetUrl,
+    summary = { critical: 0, warning: 0, info: 0 },
+    findings = [],
+    affectedRoutes = [],
+    changedFiles = [],
+    blocked = false,
+    blockOn = 'critical',
+    baseline,   // B2: { available, newCritical, newWarning, newInfo, persisting, resolved } | { available:false, note }
+  } = result;
+
+  const base = String(targetUrl ?? '').replace(/\/$/, '');
+
+  // Group findings by their route path (derived from each finding's url), so the
+  // comment's findings table is sourced per-route — formatPrComment uses
+  // report.routes[].route as the display source label for each finding.
+  const byRoute = new Map();
+  for (const f of findings) {
+    const url = String(f.url ?? '');
+    let label = url || '(unknown route)';
+    if (base && url.startsWith(base)) label = url.slice(base.length) || '/';
+    if (!byRoute.has(label)) byRoute.set(label, []);
+    byRoute.get(label).push(f);
+  }
+  const routes = [...byRoute.entries()].map(([route, errors]) => ({
+    route, errors, screenshot: null,
+  }));
+
+  const crit  = summary.critical ?? 0;
+  const warn  = summary.warning  ?? 0;
+  const info  = summary.info     ?? 0;
+
+  // The block reason must reflect what the decision actually counted, so the banner reconciles
+  // with `blocked` (Phase B2): the NEW (PR-introduced) counts when a baseline was available, the
+  // absolute counts otherwise. The scope word ("new"/"total") matches decidePrBlock's phrasing;
+  // it is omitted entirely for legacy callers that pass no baseline field (back-compat).
+  const blPresent = !!(baseline && typeof baseline === 'object');
+  const blAvail   = !!(blPresent && baseline.available);
+  const rCrit = blAvail ? (baseline.newCritical ?? 0) : crit;
+  const rWarn = blAvail ? (baseline.newWarning  ?? 0) : warn;
+  const scope = !blPresent ? '' : blAvail ? 'new ' : 'total ';
+  const reason = !blocked ? null
+    : blockOn === 'warning'
+      ? `${rCrit} critical + ${rWarn} warning ${scope}finding(s) at or above the block threshold`
+      : `${rCrit} critical ${scope}finding(s) found`;
+
+  return {
+    baseUrl: base || String(targetUrl ?? ''),
+    generatedAt: new Date().toISOString(),
+    summary: { critical: crit, warning: warn, info, total: crit + warn + info },
+    routes,
+    codebase: [],
+    flows: [],
+    prValidation: {
+      blocked,
+      blockOn,
+      reason,
+      affectedRoutes: affectedRoutes
+        .map(r => (typeof r === 'string' ? r : r?.path))
+        .filter(Boolean),
+      changedFileCount: Array.isArray(changedFiles) ? changedFiles.length : 0,
+      baseline: baseline ?? null,
+    },
+  };
+}
+
+/**
+ * Post (or idempotently update) the single Argus PR comment for a PR-Validator run.
+ *
+ * Gated on GITHUB_TOKEN plus a resolvable owner/repo + PR number — taken from the
+ * GITHUB_REPOSITORY / GITHUB_PR_NUMBER env vars (set by the GitHub runner) or, failing
+ * that, parsed from the PR URL. A missing token or unresolvable PR context SKIPS
+ * reporting (returns a status) rather than throwing: a reporting misconfiguration must
+ * never crash or block the validation step. The GitHub token is never echoed into the
+ * return value, logs, or thrown errors (it rides only in the Authorization header).
+ *
+ * Idempotent: postPrComment finds the existing Argus comment by its HTML marker and
+ * PATCHes it in place, so re-running on the same PR updates rather than duplicates.
+ *
+ * In addition to the comment (A1), a GitHub Check Run is created + completed (A2) when a
+ * PR head SHA is resolvable (ARGUS_PR_HEAD_SHA — set by action.yml to
+ * github.event.pull_request.head.sha — or GITHUB_SHA). Its conclusion maps to the block
+ * decision (failure iff blocked). The Check Run is best-effort and isolated: a failure
+ * there never discards an already-posted comment and never changes the merge decision.
+ *
+ * @param {object} result        - PR-validate result (see prResultToReport)
+ * @param {object} [opts]
+ * @param {string} [opts.prUrl]  - PR URL used to derive owner/repo/prNumber when env vars are absent
+ * @returns {Promise<{ posted: boolean, checked: boolean, skipped: boolean, reason?: string }>}
+ */
+export async function reportPrValidation(result, { prUrl } = {}) {
+  if (!process.env.GITHUB_TOKEN) {
+    return { posted: false, checked: false, skipped: true, reason: 'GITHUB_TOKEN not set — PR reporting skipped' };
+  }
+
+  let repo     = process.env.GITHUB_REPOSITORY;
+  let prNumber = process.env.GITHUB_PR_NUMBER;
+  const url    = prUrl ?? result?.prUrl;
+  if ((!repo || !prNumber) && url) {
+    try {
+      const { owner, repo: r, prNumber: n } = parsePrUrl(url);
+      repo     = repo     || `${owner}/${r}`;
+      prNumber = prNumber || n;
+    } catch { /* unparseable URL — fall through to the skip below */ }
+  }
+  if (!repo || !prNumber) {
+    return { posted: false, checked: false, skipped: true, reason: 'no resolvable repo / PR number — PR reporting skipped' };
+  }
+
+  const report = prResultToReport(result);
+  // Non-first diff so findings render (not treated as a baseline-establishing first run). The
+  // new/persisting split rides on each finding's `isNew` tag (set in the PR-validate paths via
+  // tagFindingNovelty); `resolvedCount` comes from the head-vs-base diff (Phase B2) so the
+  // comment's Resolved row reconciles with the block decision. 0 when no baseline was available.
+  const diff = {
+    isFirstRun: false,
+    resolvedCount: (result && result.baseline && result.baseline.available) ? (result.baseline.resolved ?? 0) : 0,
+    flowResolvedCount: 0,
+  };
+
+  // A1 — idempotent PR comment (the primary visible surface). A failure here propagates to
+  // the caller, which logs a ::warning:: and leaves the already-computed merge decision intact.
+  await postPrComment(report, diff, { repo, prNumber });
+
+  // A2 — Check Run whose conclusion maps to the block decision. Gated on a resolvable PR
+  // head SHA; isolated so a Check Run failure can't discard the posted comment.
+  let checked = false;
+  let checkError;
+  const headSha = process.env.ARGUS_PR_HEAD_SHA || process.env.GITHUB_SHA;
+  if (headSha) {
+    try {
+      const checkId = await createCheckRun(undefined, headSha, { repo });
+      await completeCheckRun(checkId, report, diff, { repo });
+      checked = true;
+    } catch (err) {
+      checkError = err.message;
+      logger.warn(`[ARGUS] C2: PR Check Run failed — ${err.message}`);
+    }
+  }
+
+  return { posted: true, checked, skipped: false, ...(checkError ? { reason: `check run failed: ${checkError}` } : {}) };
+}