@forkpoint/agent-lighthouse-core 0.3.0 → 0.4.0

package/dist/index.mjs

@@ -17396,17 +17396,17 @@ function stubCheck(meta, tag, explanation) {
     tags: [tag]
   };
 }
-async function runAudits(ctx, config, onProgress) {
+function planAudits(ctx, config) {
   const scannedPageTypes = new Set(ctx.pages.map((p) => p.pageType));
-  const all = [];
-  const allChecks = [];
+  const runnable = [];
+  const skipped = [];
   for (const cat of config.categories) {
     const regs = config.audits[cat.id] ?? [];
     for (const reg2 of regs) {
       const applicable = reg2.meta.applicablePageTypes;
       if (applicable && applicable.length > 0) {
         if (!applicable.some((pt) => scannedPageTypes.has(pt))) {
-          allChecks.push(
+          skipped.push(
             stubCheck(
               reg2.meta,
               TAG_SKIPPED_PAGE_TYPE,
@@ -17416,30 +17416,35 @@ async function runAudits(ctx, config, onProgress) {
           continue;
         }
       }
-      all.push({ reg: reg2, categoryId: cat.id });
+      runnable.push({ reg: reg2, categoryId: cat.id });
     }
   }
-  const totalAudits = all.length;
-  let completed = 0;
+  return { runnable, skipped };
+}
+async function runAudits(ctx, config, onEvent, plan) {
+  const { runnable, skipped } = plan ?? planAudits(ctx, config);
+  const allChecks = [...skipped];
   const batchSize = 20;
-  for (let i = 0; i < totalAudits; i += batchSize) {
-    const batch = all.slice(i, i + batchSize);
+  for (let i = 0; i < runnable.length; i += batchSize) {
+    const batch = runnable.slice(i, i + batchSize);
     const batchResults = await Promise.all(
       batch.map(async ({ reg: reg2 }) => {
+        const label2 = `${reg2.meta.id} ${reg2.meta.title}`;
         try {
           const instance = reg2.create();
           const result = await instance.audit(ctx);
-          return instance.toCheckResult(result);
+          const check = instance.toCheckResult(result);
+          onEvent?.({ type: "unit:done", label: label2 });
+          return check;
         } catch (err) {
           logger.error({ err, auditId: reg2.meta.id }, "[scanner] Audit error");
           const message = err instanceof Error ? err.message : String(err);
+          onEvent?.({ type: "unit:fail", label: label2, error: message });
           return stubCheck(reg2.meta, TAG_SCAN_ERROR, `Audit failed to run: ${message}`);
         }
       })
     );
     allChecks.push(...batchResults);
-    completed += batchResults.length;
-    onProgress?.(completed, totalAudits);
   }
   const categories = config.categories.map((cat) => {
     const catChecks = allChecks.filter((c) => c.category === cat.id);
@@ -17487,6 +17492,110 @@ function buildWeightedCategoryResult(cat, checks2, registrations) {
   };
 }
 
+// src/progress.ts
+var PHASE_WEIGHTS = {
+  "fetch-root": 0.35,
+  "fetch-pages": 0.2,
+  analyze: 0.1,
+  audits: 0.3,
+  report: 0.05
+};
+var ProgressTracker = class {
+  onEvent;
+  startMs;
+  doneWeight = 0;
+  phase = null;
+  phaseStartMs = 0;
+  totalUnits = 0;
+  completedUnits = 0;
+  lastFraction = 0;
+  constructor(onEvent) {
+    this.onEvent = onEvent;
+    this.startMs = performance.now();
+  }
+  /** Fraction of the whole scan that is complete, in [0, 1]. Never decreases. */
+  get fraction() {
+    let f = this.doneWeight;
+    if (this.phase !== null) {
+      const ratio = this.totalUnits > 0 ? Math.min(1, this.completedUnits / this.totalUnits) : 0;
+      f += PHASE_WEIGHTS[this.phase] * ratio;
+    }
+    return Math.min(1, Math.max(f, this.lastFraction));
+  }
+  /** Stamp an event with the current fraction/elapsed and advance the floor. */
+  stamp() {
+    const fraction = this.fraction;
+    this.lastFraction = Math.max(this.lastFraction, fraction);
+    return { fraction, elapsedMs: this.elapsedMs() };
+  }
+  elapsedMs() {
+    return Math.max(0, Math.round(performance.now() - this.startMs));
+  }
+  scanStart(url) {
+    this.onEvent({ type: "scan:start", url, ...this.stamp() });
+  }
+  phaseStart(phase, totalUnits) {
+    this.phase = phase;
+    this.phaseStartMs = performance.now();
+    this.totalUnits = Math.max(0, totalUnits);
+    this.completedUnits = 0;
+    this.onEvent({
+      type: "phase:start",
+      phase,
+      totalUnits: this.totalUnits,
+      ...this.stamp()
+    });
+  }
+  /** Correct the current phase's unit total (e.g. discovery finds pages mid-phase). */
+  setPhaseTotal(totalUnits) {
+    this.totalUnits = Math.max(this.completedUnits, totalUnits);
+  }
+  unitDone(label2) {
+    const phase = this.phase;
+    if (phase === null) return;
+    this.completedUnits += 1;
+    this.onEvent({
+      type: "unit:done",
+      phase,
+      completed: this.completedUnits,
+      total: this.totalUnits,
+      label: label2,
+      ...this.stamp()
+    });
+  }
+  /** A failed unit still counts as settled work so the phase can complete. */
+  unitFail(label2, error) {
+    const phase = this.phase;
+    if (phase === null) return;
+    this.completedUnits += 1;
+    this.onEvent({
+      type: "unit:fail",
+      phase,
+      label: label2,
+      error,
+      ...this.stamp()
+    });
+  }
+  phaseDone() {
+    const phase = this.phase;
+    if (phase === null) return;
+    this.phase = null;
+    this.doneWeight += PHASE_WEIGHTS[phase];
+    const durationMs = Math.max(0, Math.round(performance.now() - this.phaseStartMs));
+    this.totalUnits = 0;
+    this.completedUnits = 0;
+    this.onEvent({
+      type: "phase:done",
+      phase,
+      durationMs,
+      ...this.stamp()
+    });
+  }
+  scanDone(score) {
+    this.onEvent({ type: "scan:done", durationMs: this.elapsedMs(), score, ...this.stamp() });
+  }
+};
+
 // src/audits/accessibility/runner.ts
 import { JSDOM } from "jsdom";
 
@@ -22998,9 +23107,11 @@ function discoverPages(homepageUrl, domain, rootFiles, homepage$, exclude, maxAd
   }
   return selected;
 }
-async function runScan(url, onProgress, pageOverrides, signal) {
-  const progress = onProgress ?? (() => {
-  });
+async function runScan(url, options) {
+  const onEvent = options?.onEvent;
+  const pageOverrides = options?.pages;
+  const signal = options?.signal;
+  const tracker = new ProgressTracker((event) => onEvent?.(event));
   const start = performance.now();
   const fetcher = createFetcher();
   const baseUrl = new URL(url).origin;
@@ -23023,7 +23134,7 @@ async function runScan(url, onProgress, pageOverrides, signal) {
   }
   logger.debug({ url, domain }, "[orchestrator] Starting runScan");
   signal?.throwIfAborted();
-  await progress(5, "Fetching root files");
+  tracker.scanStart(displayUrl);
   const rootFilePaths = [
     "/robots.txt",
     "/llms.txt",
@@ -23061,19 +23172,26 @@ async function runScan(url, onProgress, pageOverrides, signal) {
     "/our-story"
   ];
   logger.debug({ count: rootFilePaths.length }, "[orchestrator] Phase 1: Fetching root files");
+  tracker.phaseStart("fetch-root", rootFilePaths.length);
   const rootResults = await Promise.all(
-    rootFilePaths.map((path) => fetcher.fetch({ url: `${baseUrl}${path}`, signal }))
+    rootFilePaths.map(
+      (path) => fetcher.fetch({ url: `${baseUrl}${path}`, signal }).then((result) => {
+        tracker.unitDone(path);
+        return result;
+      })
+    )
   );
   const rootFiles = {};
   rootFilePaths.forEach((path, i) => {
     rootFiles[path] = rootResults[i];
   });
-  await progress(25, "Root files fetched");
+  tracker.phaseDone();
   logger.debug("[orchestrator] Phase 1 complete: Root files fetched");
   signal?.throwIfAborted();
-  await progress(30, "Fetching pages");
   logger.debug("[orchestrator] Phase 2: Fetching pages");
+  tracker.phaseStart("fetch-pages", 1);
   const homepageResult = await fetcher.fetch({ url, signal });
+  tracker.unitDone(displayUrl);
   const homepage$ = homepageResult.status === 200 && homepageResult.body ? parseHtml(homepageResult.body) : null;
   const discoverLimit = Math.max(0, MAX_PAGES_PER_SCAN - 1 - overrideUrls.length);
   const discoveredUrls = homepage$ ? discoverPages(url, domain, rootFiles, homepage$, new Set(overrideTypeByKey.keys()), discoverLimit) : [];
@@ -23082,12 +23200,22 @@ async function runScan(url, onProgress, pageOverrides, signal) {
     "[orchestrator] Page set: overrides + discovered URLs"
   );
   const extraUrls = [...overrideUrls, ...discoveredUrls];
-  await progress(40, `Analyzing ${1 + extraUrls.length} pages`);
+  tracker.setPhaseTotal(1 + extraUrls.length);
   const extraResults = await Promise.all(
-    extraUrls.map((pageUrl) => fetcher.fetch({ url: pageUrl, signal }))
+    extraUrls.map(
+      (pageUrl) => fetcher.fetch({ url: pageUrl, signal }).then((result) => {
+        tracker.unitDone(pageUrl);
+        return result;
+      })
+    )
   );
+  tracker.phaseDone();
   const allPageResults = [homepageResult, ...extraResults];
   const allPageUrls = [displayUrl, ...extraUrls];
+  tracker.phaseStart(
+    "analyze",
+    allPageResults.filter((r) => r.status === 200 && r.body).length
+  );
   const pages = allPageResults.map((r, i) => ({ result: r, url: allPageUrls[i], index: i })).filter((p) => p.result.status === 200 && p.result.body).map((p) => {
     const $ = parseHtml(p.result.body);
     const jsonLd = extractJsonLd($);
@@ -23095,6 +23223,7 @@ async function runScan(url, onProgress, pageOverrides, signal) {
     const meta = extractMetaTags($);
     const isFirstPage = p.index === 0;
     const forcedType = overrideTypeByKey.get(p.url.replace(/\/$/, ""));
+    tracker.unitDone(p.url);
     return {
       url: p.url,
       pageType: forcedType ?? detectPageType(p.url, $, structuredData, meta, isFirstPage),
@@ -23112,13 +23241,12 @@ async function runScan(url, onProgress, pageOverrides, signal) {
       p.a11yResults = await runA11yForHtml(p.fetchResult.body, p.url, A11Y_RULES);
     })
   );
-  await progress(55, "Page analysis complete");
+  tracker.phaseDone();
   logger.debug(
     { pagesAnalyzed: pages.length },
     "[orchestrator] Phase 2 complete: Page analysis complete"
   );
   signal?.throwIfAborted();
-  await progress(60, "Running audits");
   logger.debug("[orchestrator] Phase 3: Running audits");
   const wafProtection = detectWafProtection(url, homepageResult, rootFiles, pages.length);
   const ctx = {
@@ -23126,19 +23254,27 @@ async function runScan(url, onProgress, pageOverrides, signal) {
     pages,
     domain,
     baseUrl,
-    fetch: (options) => fetcher.fetch({ ...options, signal }),
+    fetch: (options2) => fetcher.fetch({ ...options2, signal }),
     wafProtection: wafProtection ?? void 0
   };
+  const auditPlan = planAudits(ctx, defaultConfig);
+  tracker.phaseStart("audits", auditPlan.runnable.length);
   const {
     checks: allChecks,
     categories,
     overallScore
-  } = await runAudits(ctx, defaultConfig, (completed, total) => {
-    const checkProgress = 60 + Math.round(completed / total * 30);
-    void progress(checkProgress, `Running audits (${completed}/${total})`);
-  });
+  } = await runAudits(
+    ctx,
+    defaultConfig,
+    (event) => {
+      if (event.type === "unit:done") tracker.unitDone(event.label);
+      else tracker.unitFail(event.label, event.error);
+    },
+    auditPlan
+  );
+  tracker.phaseDone();
   logger.debug("[orchestrator] Phase 3 complete: Audits finished");
-  await progress(97, "Building report");
+  tracker.phaseStart("report", 1);
   logger.debug("[orchestrator] Phase 4: Building final report");
   const durationMs = Math.round(performance.now() - start);
   const recommendations = allChecks.filter((c) => c.status !== "pass").slice().sort((a, b) => {
@@ -23155,7 +23291,6 @@ async function runScan(url, onProgress, pageOverrides, signal) {
   const topPasses = allChecks.filter((c) => c.status === "pass").slice().sort(
     (a, b) => (weightMap.get(b.id) ?? 1) - (weightMap.get(a.id) ?? 1)
   ).slice(0, 10);
-  await progress(100, "Complete");
   const readinessVitals = calculateReadinessVitals(allChecks);
   const readinessScore = Math.round(
     readinessVitals.commerce * READINESS_WEIGHTS.commerce + readinessVitals.content * READINESS_WEIGHTS.content + readinessVitals.botAccessibility * READINESS_WEIGHTS.botAccessibility + readinessVitals.technical * READINESS_WEIGHTS.technical
@@ -23185,6 +23320,9 @@ async function runScan(url, onProgress, pageOverrides, signal) {
     productFields: [...overrideTypeByKey.values()].includes("product") ? extractProductFieldVerification(pages) : void 0
   };
   report.summary = generateScanSummary(report);
+  tracker.unitDone();
+  tracker.phaseDone();
+  tracker.scanDone(overallScore);
   logger.debug({ durationMs, score: overallScore }, "[orchestrator] runScan complete");
   return report;
 }
@@ -23369,7 +23507,9 @@ export {
   MAX_PAGES_PER_SCAN,
   MAX_RESPONSE_BODY_BYTES,
   PAGE_TYPE_LABELS,
+  PHASE_WEIGHTS,
   PRESETS,
+  ProgressTracker,
   READINESS_WEIGHTS,
   REQUEST_TIMEOUT_MS,
   SCANNER_USER_AGENT,
@@ -23413,6 +23553,7 @@ export {
   logger,
   normalizeUrl,
   parseHtml,
+  planAudits,
   runAudits,
   runScan
 };