karajan-code 2.8.0 → 2.10.0

package/src/roles/audit-role.js

@@ -1,6 +1,11 @@
 import { AgentRole } from "./agent-role.js";
 import { buildAuditPrompt, parseAuditOutput, AUDIT_DIMENSIONS } from "../prompts/audit.js";
 import { measureBasalCost, loadPreviousAudit, saveAuditSnapshot, computeGrowthDelta } from "../audit/basal-cost.js";
+import { detectProjectStack } from "../utils/stack-detect.js";
+import { collectSonarFindings } from "../audit/sonar-findings.js";
+import { collectWebPerfInput } from "../audit/webperf-input.js";
+import { collectOsvFindings } from "../audit/osv-findings.js";
+import { collectSemgrepFindings } from "../audit/semgrep-findings.js";
 
 function parseDimensions(dimensionsStr) {
   if (!dimensionsStr || dimensionsStr === "all") return null;
@@ -26,37 +31,98 @@ export class AuditRole extends AgentRole {
     super({ ...opts, name: "audit" });
   }
 
-  async execute(input) {
-    const task = typeof input === "string" ? input : input?.task || this.context?.task || "";
-    const onOutput = typeof input === "string" ? null : input?.onOutput || null;
-    const rawDimensions = typeof input === "object" ? input?.dimensions || null : null;
-    const context = typeof input === "object" ? input?.context || null : null;
-    const dimensions = typeof rawDimensions === "string" ? parseDimensions(rawDimensions) : rawDimensions;
-
+  /**
+   * Run the deterministic side of an audit — basalCost, stack detection,
+   * Sonar issues, WebPerf input — without invoking the LLM. Cheap (no
+   * tokens, no API call). KJC-TSK-0364 splits the original execute() into
+   * this collector + executeWithDeterministic() so the CLI can show
+   * deterministic findings first and ask the user before paying for the
+   * LLM phase.
+   *
+   * @param {object|string} input - same shape execute() accepts
+   * @returns {Promise<object>} deterministic context (the same data
+   *   execute() would gather internally)
+   */
+  async collectDeterministic(input) {
+    const noSonar = typeof input === "object" ? Boolean(input?.noSonar) : false;
+    const noOsv = typeof input === "object" ? Boolean(input?.noOsv) : false;
+    const noSemgrep = typeof input === "object" ? Boolean(input?.noSemgrep) : false;
     const projectDir = this.config?.projectDir || process.cwd();
     let basalCost = null;
     let growthDelta = null;
+    let stack = null;
+    let sonarFindings = null;
+    let webperf = null;
+    let osvFindings = null;
+    let semgrepFindings = null;
     try {
       basalCost = await measureBasalCost(projectDir);
       const previous = await loadPreviousAudit(projectDir);
       growthDelta = computeGrowthDelta(basalCost, previous);
     } catch { /* basal cost is best-effort */ }
+    try {
+      stack = await detectProjectStack(projectDir);
+    } catch { /* stack detect is best-effort */ }
+    if (!noSonar) {
+      try {
+        sonarFindings = await collectSonarFindings(this.config, this.logger);
+      } catch { /* sonar fetch is best-effort */ }
+    }
+    try {
+      webperf = collectWebPerfInput(stack, this.config);
+    } catch { /* webperf input is best-effort */ }
+    // OSV vulnerabilities — KJC-TSK-0365. Best-effort: missing
+    // osv-scanner binary returns available:false and the audit
+    // continues without the section.
+    if (!noOsv) {
+      try {
+        osvFindings = await collectOsvFindings(projectDir, this.logger);
+      } catch { /* osv-scanner is best-effort */ }
+    }
+    // Semgrep SAST — KJC-TSK-0366. Best-effort: missing semgrep binary
+    // returns available:false and the audit continues without the section.
+    if (!noSemgrep) {
+      try {
+        semgrepFindings = await collectSemgrepFindings(projectDir, this.logger);
+      } catch { /* semgrep is best-effort */ }
+    }
+    return { projectDir, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings };
+  }
+
+  /**
+   * Run the LLM phase of an audit using a pre-collected deterministic
+   * context. KJC-TSK-0364: separated from execute() so the CLI can run
+   * collectDeterministic() first, show findings, prompt, and only then
+   * call this if the user wants to spend tokens.
+   */
+  async executeWithDeterministic(input, deterministicCtx) {
+    const task = typeof input === "string" ? input : input?.task || this.context?.task || "";
+    const onOutput = typeof input === "string" ? null : input?.onOutput || null;
+    const rawDimensions = typeof input === "object" ? input?.dimensions || null : null;
+    const context = typeof input === "object" ? input?.context || null : null;
+    const dimensions = typeof rawDimensions === "string" ? parseDimensions(rawDimensions) : rawDimensions;
+
+    const { projectDir, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings } = deterministicCtx;
 
     const provider = this.resolveProvider();
     const agent = this.createAgentInstance(provider);
-    const prompt = buildAuditPrompt({ task, instructions: this.instructions, dimensions, context, basalCost, growthDelta });
+    const prompt = buildAuditPrompt({ task, instructions: this.instructions, dimensions, context, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings });
     const runArgs = { prompt, role: "audit" };
     if (onOutput) runArgs.onOutput = onOutput;
+    const startedAt = Date.now();
     const result = await agent.runTask(runArgs);
+    const durationMs = Date.now() - startedAt;
+
+    const usage = extractUsage(result, { provider, durationMs });
 
     if (!result.ok) {
-      return { ok: false, result: { error: result.error || result.output || "Audit failed", provider }, summary: `Audit failed: ${result.error || "unknown error"}`, usage: result.usage };
+      return { ok: false, result: { error: result.error || result.output || "Audit failed", provider }, summary: `Audit failed: ${result.error || "unknown error"}`, usage };
     }
 
     try {
       const parsed = parseAuditOutput(result.output);
       if (!parsed) {
-        return { ok: true, result: { raw: result.output, provider }, summary: "Audit complete (unstructured output)", usage: result.usage };
+        return { ok: true, result: { raw: result.output, provider }, summary: "Audit complete (unstructured output)", usage };
       }
       if (basalCost) { try { await saveAuditSnapshot(projectDir, basalCost); } catch { /* best-effort */ } }
 
@@ -65,13 +131,59 @@ export class AuditRole extends AgentRole {
         result: {
           summary: parsed.summary, dimensions: parsed.dimensions,
           topRecommendations: parsed.topRecommendations,
-          basalCost: basalCost || undefined, growthDelta: growthDelta || undefined, provider
+          textSummary: parsed.textSummary || undefined,
+          basalCost: basalCost || undefined, growthDelta: growthDelta || undefined,
+          stack: stack || undefined,
+          sonarFindings: sonarFindings?.available ? sonarFindings : undefined,
+          webperf: webperf?.available ? webperf : undefined,
+          osvFindings: osvFindings?.available ? osvFindings : undefined,
+          semgrepFindings: semgrepFindings?.available ? semgrepFindings : undefined,
+          provider
         },
         summary: buildSummary(parsed),
-        usage: result.usage
+        usage
       };
     } catch {
-      return { ok: true, result: { raw: result.output, provider }, summary: "Audit complete (unstructured output)", usage: result.usage };
+      return { ok: true, result: { raw: result.output, provider }, summary: "Audit complete (unstructured output)", usage };
     }
   }
+
+  /**
+   * Convenience: run both phases in one call. Identical to the previous
+   * (single-phase) execute() so MCP and pipeline callers don't change.
+   */
+  async execute(input) {
+    const deterministicCtx = await this.collectDeterministic(input);
+    return this.executeWithDeterministic(input, deterministicCtx);
+  }
+}
+
+/**
+ * Consolidate the usage telemetry the agent spreads across its top-level
+ * result fields. Returns a single object so consumers (CLI formatter,
+ * report-file writer, MCP) don't need to know about the spread shape.
+ *
+ * @param {object} result - raw agent.runTask() return
+ * @param {{provider: string, durationMs: number}} ctx
+ * @returns {{available: boolean, provider: string, model?: string, tokens_in?: number, tokens_out?: number, total_tokens?: number, cost_usd?: number, durationMs: number, reason?: string}}
+ */
+function extractUsage(result, { provider, durationMs }) {
+  if (!result || typeof result !== "object") {
+    return { available: false, provider, durationMs, reason: "no agent result" };
+  }
+  const tokens_in = Number.isFinite(result.tokens_in) ? result.tokens_in : null;
+  const tokens_out = Number.isFinite(result.tokens_out) ? result.tokens_out : null;
+  if (tokens_in === null && tokens_out === null) {
+    return { available: false, provider, model: result.model, durationMs, reason: `provider "${provider}" did not report token usage` };
+  }
+  return {
+    available: true,
+    provider,
+    model: result.model,
+    tokens_in: tokens_in ?? 0,
+    tokens_out: tokens_out ?? 0,
+    total_tokens: (tokens_in ?? 0) + (tokens_out ?? 0),
+    cost_usd: typeof result.cost_usd === "number" ? result.cost_usd : null,
+    durationMs,
+  };
 }

package/src/roles/perf-role.js

@@ -0,0 +1,122 @@
+/**
+ * PerfRole — webperf quality gate (KJC-TSK-0150).
+ *
+ * Same shape as SonarRole / AuditRole: extends BaseRole, exposes an
+ * `execute()` that returns `{ok, result, summary}`. Internally drives
+ * `runWebperfScan` from src/webperf/scanner.js (the Lighthouse wrapper
+ * added in KJC-TSK-0149) and persists the result so subsequent
+ * `kj audit` runs surface it via `cwv-result` mode (KJC-TSK-0360).
+ *
+ * Configuration (kj.config.yml):
+ *   webperf:
+ *     url: http://localhost:3000   # required for the role to run
+ *     preset: desktop              # or "mobile"
+ *     thresholds: { lcp: { good: 2500, poor: 4000 }, ... }
+ *     persist: true                # writes to ~/.karajan/webperf/<slug>/last.json
+ *
+ * Pipeline activation (KJC-TSK-0151) wires this role behind a triage-
+ * driven flag so it only runs for frontend / fullstack tasks.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { BaseRole } from "./base-role.js";
+import { runWebperfScan } from "../webperf/scanner.js";
+
+function projectSlug(projectDir) {
+  return path.basename(projectDir || process.cwd()).replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+
+function defaultPersistDir() {
+  return path.join(os.homedir(), ".karajan", "webperf");
+}
+
+async function persistResult(result, projectDir) {
+  if (!result?.ok) return null;
+  const dir = path.join(defaultPersistDir(), projectSlug(projectDir));
+  await fs.mkdir(dir, { recursive: true });
+  const filePath = path.join(dir, "last.json");
+  await fs.writeFile(filePath, JSON.stringify(result, null, 2), "utf8");
+  return filePath;
+}
+
+export class PerfRole extends BaseRole {
+  constructor({ config, logger, emitter = null, scanFn = null }) {
+    super({ name: "perf", config, logger, emitter });
+    // scanFn is injectable for tests so we don't need to mock execFile here.
+    this._scan = scanFn || runWebperfScan;
+  }
+
+  /**
+   * Run a webperf scan against the configured URL.
+   *
+   * @param {object} [_input] - unused; PerfRole reads its target from config
+   * @returns {Promise<{ok: boolean, result: object, summary: string}>}
+   */
+  async execute(_input) {
+    const webperfConfig = this.config?.webperf || {};
+    const url = webperfConfig.url;
+    const preset = webperfConfig.preset === "mobile" ? "mobile" : "desktop";
+    const thresholds = webperfConfig.thresholds || null;
+    const persist = webperfConfig.persist !== false;
+
+    if (!url) {
+      return {
+        ok: false,
+        result: { error: "config.webperf.url is required for PerfRole" },
+        summary: "PerfRole skipped: no config.webperf.url configured",
+      };
+    }
+
+    const scan = await this._scan(url, { preset, thresholds, logger: this.logger });
+
+    if (!scan.ok) {
+      return {
+        ok: false,
+        result: {
+          url,
+          error: scan.reason || "webperf scan failed",
+        },
+        summary: `Webperf scan failed: ${scan.reason || "unknown"}`,
+      };
+    }
+
+    let savedPath = null;
+    if (persist) {
+      try {
+        savedPath = await persistResult(scan, this.config?.projectDir);
+      } catch (err) {
+        if (this.logger?.warn) {
+          this.logger.warn(`PerfRole: failed to persist result (non-blocking): ${err.message}`);
+        }
+      }
+    }
+
+    const verdict = scan.cwv?.pass ? "PASS" : "FAIL";
+    const score = typeof scan.performanceScore === "number" ? scan.performanceScore : null;
+    const blockingMetrics = (scan.cwv?.blocking || []).map(b => `${b.metric.toUpperCase()}=${Math.round(b.value)}`).join(", ");
+    const summaryParts = [
+      `Webperf ${verdict}`,
+      score !== null ? `score ${score}/100` : null,
+      blockingMetrics ? `blocking: ${blockingMetrics}` : null,
+      `top opportunities: ${scan.issues?.length ?? 0}`,
+    ].filter(Boolean);
+
+    return {
+      ok: scan.cwv?.pass === true,
+      result: {
+        url: scan.url,
+        preset: scan.preset,
+        capturedAt: scan.capturedAt,
+        performanceScore: scan.performanceScore,
+        metrics: scan.metrics,
+        cwv: scan.cwv,
+        issues: scan.issues,
+        thresholds: scan.thresholds,
+        savedPath,
+      },
+      summary: summaryParts.join(" — "),
+    };
+  }
+}

package/src/skills/addyosmani-role-map.js

@@ -89,6 +89,12 @@ export const TASK_PATTERN_TO_SLUG = [
   { pattern: /\bsecurity\b|\bhardening\b|\bauth(entication|orization)?\b|\bxss\b|\bcsrf\b|\binjection\b/i, slug: "security-and-hardening" },
   { pattern: /\btdd\b|\btest[- ]driven\b/i, slug: "test-driven-development" },
   { pattern: /\bfrontend\b|\bui\b|\bux\b|\bcss\b|\bresponsive\b/i, slug: "frontend-ui-engineering" },
+  // Accessibility (a11y / WCAG / ARIA / screen reader / keyboard nav).
+  // No dedicated addyosmani skill exists yet for a11y; until one ships,
+  // route to frontend-ui-engineering — the closest authoritative source
+  // for WCAG-aware UI work. When upstream ships an a11y skill, change
+  // only the `slug` field here.
+  { pattern: /\baccessibility\b|\ba11y\b|\bwcag\b|\baria\b|\bscreen[\s-]?reader\b|\bkeyboard[\s-]?nav(igation)?\b/i, slug: "frontend-ui-engineering" },
   { pattern: /\bapi\b|\bendpoint\b|\binterface\s+design\b|\bopenapi\b|\brest\b|\bgraphql\b/i, slug: "api-and-interface-design" },
   { pattern: /\bci\b|\bcd\b|\bci\/cd\b|\bpipeline\b|\bgithub\s+actions\b|\bworkflow\b/i, slug: "ci-cd-and-automation" },
   { pattern: /\bgit\b|\bcommit\b|\bbranch\b|\bmerge\b|\bversioning\b|\bsemver\b/i, slug: "git-workflow-and-versioning" },

package/src/sonar/api.js

@@ -3,7 +3,7 @@ import { withRetry } from "../utils/retry.js";
 import { resolveSonarProjectKey } from "./project-key.js";
 import { resolveSonarToken } from "./config-resolver.js";
 
-export class SonarApiError extends Error {
+class SonarApiError extends Error {
   constructor(message, { url, httpStatus, hint } = {}) {
     super(message);
     this.name = "SonarApiError";

package/src/utils/display/event-handlers.js

@@ -342,7 +342,7 @@ export const EVENT_HANDLERS = {
 };
 
 /** Event types suppressed in quiet mode (internal/noise events). */
-export const QUIET_SUPPRESSED = new Set([
+const QUIET_SUPPRESSED = new Set([
   "agent:output",
   "agent:stall",
   "pipeline:simplify",

package/src/utils/display/header.js

@@ -8,7 +8,7 @@ import { ANSI } from "./formatters.js";
 const DISPLAY_PKG_PATH = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../package.json");
 const DISPLAY_VERSION = JSON.parse(readFileSync(DISPLAY_PKG_PATH, "utf8")).version;
 
-export const BAR = `${ANSI.dim}\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500${ANSI.reset}`;
+const BAR = `${ANSI.dim}\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500${ANSI.reset}`;
 
 /**
  * Print task, configuration and pipeline header

package/src/utils/display/session-summary.js

@@ -15,7 +15,7 @@ export function printSessionStages(stages) {
   printSessionSonar(stages.sonar);
 }
 
-export function printSessionPlanner(planner) {
+function printSessionPlanner(planner) {
   if (!planner?.title && !planner?.approach && !planner?.completedSteps?.length) return;
   const planParts = [];
   if (planner.title) planParts.push(planner.title);
@@ -26,7 +26,7 @@ export function printSessionPlanner(planner) {
   }
 }
 
-export function printSessionSonar(sonar) {
+function printSessionSonar(sonar) {
   if (!sonar) return;
   const gateLabel = sonar.gateStatus === "OK" ? ANSI.green : ANSI.red;
   console.log(`  ${ANSI.dim}\ud83d\udd0d Sonar: ${gateLabel}${sonar.gateStatus}${ANSI.reset}${ANSI.dim} (${sonar.openIssues ?? 0} issues)${ANSI.reset}`);
@@ -55,7 +55,7 @@ export function printSessionGit(git) {
   }
 }
 
-export function isBudgetUnavailable(budget) {
+function isBudgetUnavailable(budget) {
   return budget.usage_available === false ||
     (budget.total_tokens === 0 && budget.total_cost_usd === 0 && Object.keys(budget.breakdown_by_role || {}).length > 0);
 }

package/src/utils/display/solomon.js

@@ -1,6 +1,6 @@
 import { ANSI } from "./formatters.js";
 
-export const SOLOMON_RULING_HANDLERS = {
+const SOLOMON_RULING_HANDLERS = {
   approve(detail, elapsed) {
     const dismissedCount = detail?.dismissed?.length || 0;
     const dismissedSuffix = dismissedCount > 0 ? ` (${dismissedCount} dismissed)` : "";

package/src/utils/role-assigner.js

@@ -128,4 +128,4 @@ export function applyRoleAssignments(config, assignments) {
   return config;
 }
 
-export { CAPABILITY_TIERS, ROLE_PREFERENCES };
+export { CAPABILITY_TIERS };

package/src/webperf/scanner.js

@@ -0,0 +1,209 @@
+/**
+ * Web performance scanner — KJC-TSK-0149.
+ *
+ * Wraps Google's Lighthouse CLI (`lighthouse`) to produce a structured
+ * Core Web Vitals + opportunity report against a local URL. Same
+ * pattern as sonar-findings.js, osv-findings.js, semgrep-findings.js:
+ * best-effort, missing binary returns {ok:false, reason}, all heavy
+ * lifting happens in an external tool the user installs themselves.
+ *
+ * Output shape is designed to feed two downstream consumers:
+ *   1. The CLI `kj webperf <url>` (KJC-TSK-0149) — print JSON or human
+ *      report, optionally persist to config.webperf.lastResult.
+ *   2. `kj audit` WebPerf section (KJC-TSK-0360) — the `cwv-result` mode
+ *      reads exactly this shape from `config.webperf.lastResult`.
+ *
+ * Lighthouse JSON schema reference:
+ *   https://github.com/GoogleChrome/lighthouse/blob/main/types/lhr/lhr.d.ts
+ */
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { evaluateCwv, CWV_THRESHOLDS } from "./cwv-gate.js";
+
+const execFileAsync = promisify(execFile);
+
+const SCAN_TIMEOUT_MS = 120_000;
+const MAX_OPPORTUNITIES = 20;
+
+/**
+ * Opportunity audits we extract from Lighthouse output. Each maps to a
+ * known render-perf issue with actionable fixes; we keep the list short
+ * to bound the payload size and keep the LLM prompt tight when this
+ * result feeds `kj audit`.
+ */
+const OPPORTUNITY_AUDITS = [
+  "render-blocking-resources",
+  "unused-css-rules",
+  "unused-javascript",
+  "unminified-css",
+  "unminified-javascript",
+  "modern-image-formats",
+  "uses-optimized-images",
+  "uses-text-compression",
+  "uses-responsive-images",
+  "uses-rel-preconnect",
+  "uses-rel-preload",
+  "font-display",
+  "preload-lcp-image",
+  "lcp-lazy-loaded",
+  "non-composited-animations",
+  "third-party-summary",
+  "bootup-time",
+  "mainthread-work-breakdown",
+];
+
+/**
+ * Run Lighthouse against a URL and return a structured result.
+ *
+ * @param {string} url - target URL (must be reachable from the runner)
+ * @param {object} [opts]
+ * @param {object} [opts.thresholds] - CWV thresholds override (passed to evaluateCwv)
+ * @param {object} [opts.logger]
+ * @param {string} [opts.preset] - "desktop" or "mobile" (default: desktop)
+ * @param {number} [opts.timeoutMs] - override the 120s default
+ * @returns {Promise<object>} scanner result (see module JSDoc)
+ */
+export async function runWebperfScan(url, opts = {}) {
+  if (!url || typeof url !== "string") {
+    return { ok: false, reason: "no URL provided" };
+  }
+
+  const logger = opts.logger || null;
+  const preset = opts.preset === "mobile" ? "mobile" : "desktop";
+  const timeoutMs = opts.timeoutMs || SCAN_TIMEOUT_MS;
+
+  const lighthouseArgs = [
+    url,
+    "--output=json",
+    "--quiet",
+    "--chrome-flags=--headless --no-sandbox --disable-gpu",
+    `--preset=${preset}`,
+    "--only-categories=performance",
+  ];
+
+  let stdout;
+  try {
+    const result = await execFileAsync("lighthouse", lighthouseArgs, {
+      timeout: timeoutMs,
+      maxBuffer: 64 * 1024 * 1024,
+    });
+    stdout = result.stdout;
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      if (logger?.warn) logger.warn("lighthouse not found in PATH — install via 'npm install -g lighthouse'");
+      return { ok: false, reason: "lighthouse not installed", url };
+    }
+    if (err.killed) {
+      return { ok: false, reason: `lighthouse timed out after ${timeoutMs}ms`, url };
+    }
+    if (typeof err.stdout === "string" && err.stdout.trim().startsWith("{")) {
+      stdout = err.stdout;
+    } else {
+      const stderr = (err.stderr || "").trim().split("\n").pop() || err.message;
+      // Lighthouse prints clear NO_DCHECK / NO_NAVSTART errors when the URL
+      // is unreachable. Surface that verbatim.
+      const reason = /failed to fetch|connection refused|net::|navigation_start_time/i.test(stderr)
+        ? `URL ${url} not reachable: ${stderr}`
+        : `lighthouse failed: ${stderr}`;
+      if (logger?.warn) logger.warn(reason);
+      return { ok: false, reason, url };
+    }
+  }
+
+  let report;
+  try {
+    report = JSON.parse(stdout);
+  } catch (err) {
+    return { ok: false, reason: `lighthouse output not parseable: ${err.message}`, url };
+  }
+
+  return parseLighthouseReport(report, { url, preset, thresholds: opts.thresholds });
+}
+
+/**
+ * Convert a raw Lighthouse JSON report into the scanner's flat output.
+ * Public so tests can drive parsing without spawning lighthouse.
+ *
+ * @param {object} report - parsed Lighthouse output (lhr)
+ * @param {{url: string, preset?: string, thresholds?: object}} ctx
+ */
+export function parseLighthouseReport(report, ctx = {}) {
+  const audits = report?.audits || {};
+  const metrics = extractMetrics(audits);
+  const issues = extractIssues(audits);
+  const cwv = evaluateCwv(metrics, ctx.thresholds || CWV_THRESHOLDS);
+
+  return {
+    ok: true,
+    url: ctx.url || report?.finalDisplayedUrl || report?.requestedUrl || null,
+    preset: ctx.preset || "desktop",
+    capturedAt: report?.fetchTime || new Date().toISOString(),
+    lighthouseVersion: report?.lighthouseVersion || null,
+    performanceScore: typeof report?.categories?.performance?.score === "number"
+      ? Math.round(report.categories.performance.score * 100)
+      : null,
+    metrics,
+    cwv,
+    issues,
+    thresholds: ctx.thresholds || CWV_THRESHOLDS,
+  };
+}
+
+/**
+ * Pull Core Web Vitals + supporting metrics out of the Lighthouse audit
+ * collection. `numericValue` is the raw measurement Google reports (ms
+ * for time-based metrics, score 0-1 for CLS).
+ */
+function extractMetrics(audits) {
+  const get = (id) => {
+    const v = audits[id]?.numericValue;
+    return typeof v === "number" ? v : null;
+  };
+  return {
+    // CWV — these three drive the cwv-gate verdict
+    lcp: get("largest-contentful-paint"),
+    cls: get("cumulative-layout-shift"),
+    inp: get("interaction-to-next-paint") ?? get("max-potential-fid"),
+    // Supporting (informational)
+    fcp: get("first-contentful-paint"),
+    tbt: get("total-blocking-time"),
+    si: get("speed-index"),
+    tti: get("interactive"),
+  };
+}
+
+/**
+ * Distil the Lighthouse opportunity audits into a flat `issues` array.
+ * Each issue carries the audit id, score, savings (when applicable) and
+ * a one-line description so consumers can prioritise without parsing
+ * the full lhr.
+ */
+function extractIssues(audits) {
+  const issues = [];
+  for (const id of OPPORTUNITY_AUDITS) {
+    const audit = audits[id];
+    if (!audit) continue;
+    // score === 1 means "passed" — skip clean audits
+    if (typeof audit.score === "number" && audit.score >= 1) continue;
+    if (audit.scoreDisplayMode === "notApplicable") continue;
+    issues.push({
+      id,
+      title: audit.title || id,
+      score: typeof audit.score === "number" ? audit.score : null,
+      savingsMs: audit.details?.overallSavingsMs ?? null,
+      savingsBytes: audit.details?.overallSavingsBytes ?? null,
+      severity: scoreToSeverity(audit.score),
+    });
+  }
+  return issues
+    .sort((a, b) => (b.savingsMs || 0) - (a.savingsMs || 0))
+    .slice(0, MAX_OPPORTUNITIES);
+}
+
+function scoreToSeverity(score) {
+  if (typeof score !== "number") return "info";
+  if (score < 0.5) return "high";
+  if (score < 0.9) return "medium";
+  return "low";
+}