@codyswann/lisa 4.60.3 → 4.60.5

package/{scripts/check-workflow-load-failures.ts → all/copy-overwrite/scripts/check-workflow-load-failures.mjs}

@@ -1,55 +1,20 @@
-/**
- * Scan this repository's recent run history for reusable workflows that failed
- * to LOAD (CodySwannGT/lisa#3581).
- *
- * ## Why this runs on a schedule and not at a gate
- *
- * The failure is invisible at the moments a gate covers. On a pull request it
- * is already caught — `check-skipped-required-checks --pr=<n>` raises
- * `absent_required_check`, and a ruleset-required context that never reports
- * blocks the merge anyway. The incident this closes happened somewhere no gate
- * looks: a `push` handler failed five times in a row, ~40 minutes after an
- * upstream commit landed, with nothing changed on the consumer side and no red
- * job to open. A control that only runs where the failure cannot happen is not
- * a control, so the moment is the design decision here, not the mechanism.
- *
- * The sibling precedent is `lifecycle-drift-sweep.yml`, which exists because a
- * report nobody scheduled and nobody read is indistinguishable from no report.
- * This follows it: scheduled, and failing the job on drift so the finding lands
- * in the existing failure-to-issue path rather than a job summary nobody opens.
- *
- * ## Two ways to exit non-zero, and they mean different things
- *
- * Findings are one. **A window this scan could not cover is the other**, and it
- * is the more important of the two: the implementation this replaces read one
- * page, filtered by timestamp, and reported that a hundred runs were inspected
- * across a window that contained four known load failures. "Found nothing" and
- * "could not look" must never render as the same green.
- * @module scripts/check-workflow-load-failures
- */
+#!/usr/bin/env node
+// This file is managed by Lisa and IS replaced on each `lisa` run.
+// Do not edit directly — durable changes belong upstream in Lisa.
+
 import { execFile } from "node:child_process";
 import { readdir, readFile } from "node:fs/promises";
 import path from "node:path";
+import { pathToFileURL } from "node:url";
 import { promisify } from "node:util";
-
-import { callerDeclaresReusableWorkflow } from "../src/core/reusable-workflow-load-failure.js";
-import {
-  createRunPageFetcher,
-  type GithubRequest,
-} from "../src/core/reusable-workflow-load-adapter.js";
-import {
-  scanForLoadFailures,
-  type ScanResult,
-} from "../src/core/reusable-workflow-load-scan.js";
-
+import { callerDeclaresReusableWorkflow } from "./lib/reusable-workflow-load-failure.mjs";
+import { createRunPageFetcher } from "./lib/reusable-workflow-load-adapter.mjs";
+import { scanForLoadFailures } from "./lib/reusable-workflow-load-scan.mjs";
 const run = promisify(execFile);
-
 /** Where caller workflows live, relative to the repository root. */
 const WORKFLOW_DIR = ".github/workflows";
-
 /** How far back to scan, in hours. */
 const WINDOW_HOURS = 26;
-
 /**
  * Page cap.
  *
@@ -58,7 +23,6 @@ const WINDOW_HOURS = 26;
  * evidence about the runs beyond it.
  */
 const MAX_PAGES = 20;
-
 /**
  * Build the population test by reading the callers' own source.
  *
@@ -68,37 +32,32 @@ const MAX_PAGES = 20;
  * @param root - Repository root
  * @returns A predicate over a run's caller `path`
  */
-export async function buildPopulationTest(
-  root: string
-): Promise<(runPath: string) => boolean> {
+export async function buildPopulationTest(root) {
   const dir = path.join(root, WORKFLOW_DIR);
-  const names = await readdir(dir).catch(() => [] as string[]);
+  const names = await readdir(dir);
   const declaring = await Promise.all(
     names
       .filter(name => name.endsWith(".yml") || name.endsWith(".yaml"))
       .map(async name => {
-        const source = await readFile(path.join(dir, name), "utf8").catch(
-          () => ""
-        );
+        const source = await readFile(path.join(dir, name), "utf8");
         return callerDeclaresReusableWorkflow(source) ? name : "";
       })
   );
   const declared = new Set(declaring.filter(name => name !== ""));
-  return (runPath: string): boolean => declared.has(path.basename(runPath));
+  return runPath => declared.has(path.basename(runPath));
 }
-
 /**
  * A request function backed by the `gh` CLI.
  * @param repo - Repository in `owner/name` form, used only for error text
  * @returns A request function returning decoded JSON
  */
-export function ghRequest(repo: string): GithubRequest {
-  return async (apiPath: string): Promise<unknown> => {
+export function ghRequest(repo) {
+  return async apiPath => {
     const { stdout } = await run("gh", ["api", apiPath], {
       maxBuffer: 32 * 1024 * 1024,
     });
     try {
-      return JSON.parse(stdout) as unknown;
+      return JSON.parse(stdout);
     } catch {
       throw new Error(
         `check-workflow-load-failures: \`gh api ${apiPath}\` on ${repo} returned a body that is not JSON. Treating that as "nothing found" would be a pass produced by a broken read, so this is an error.`
@@ -106,18 +65,17 @@ export function ghRequest(repo: string): GithubRequest {
     }
   };
 }
-
 /**
  * Render the scan's answer for an operator.
  * @param result - What the scan found, and whether it could see
  * @returns Operator-readable lines
  */
-export function describe(result: ScanResult): string {
+export function describe(result) {
   if (!result.covered) {
     return `check-workflow-load-failures: INCOMPLETE. The scan ${result.reason} It inspected ${result.inspected} run(s), but that is not the same as having covered the window, so this is an error rather than a pass.`;
   }
   if (result.loadFailures.length === 0) {
-    return `check-workflow-load-failures: OK. ${result.inspected} run(s) inspected across the last ${WINDOW_HOURS}h; every caller that declared a reusable workflow resolved one.`;
+    return `check-workflow-load-failures: OK. ${result.inspected} run(s) inspected across the last ${WINDOW_HOURS}h; no reusable workflow load failures found.`;
   }
   const lines = result.loadFailures.map(
     finding =>
@@ -130,42 +88,44 @@ export function describe(result: ScanResult): string {
     "A load failure creates NO jobs, so there is no red job to open and no annotation naming the line. Check the upstream workflow's most recent commit for a syntax or schema error.",
   ].join("\n");
 }
-
 /**
  * Scan, report, and choose an exit code.
  * @param repo - Repository in `owner/name` form
  * @param root - Repository root
  * @returns 0 when the window was covered and clean, 1 otherwise
  */
-export async function main(repo: string, root: string): Promise<number> {
+export async function main(repo, root) {
   const windowStart = new Date(
     Date.now() - WINDOW_HOURS * 60 * 60 * 1000
   ).toISOString();
-
   const result = await scanForLoadFailures({
     fetchPage: createRunPageFetcher({ repo, request: ghRequest(repo) }),
     windowStart,
     inPopulation: await buildPopulationTest(root),
     maxPages: MAX_PAGES,
   });
-
   console.log(describe(result));
   return result.covered && result.loadFailures.length === 0 ? 0 : 1;
 }
+/** Run against the repository explicitly supplied by the workflow. */
+export async function runCli() {
+  const repo = process.env.GITHUB_REPOSITORY;
+  if (!repo || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo)) {
+    console.error("Set GITHUB_REPOSITORY to the owner/repository to scan.");
+    process.exitCode = 1;
+    return;
+  }
+  try {
+    process.exitCode = await main(repo, process.cwd());
+  } catch (error) {
+    console.error(String(error));
+    process.exitCode = 1;
+  }
+}
 
-/* c8 ignore start -- entry point, exercised by the workflow rather than a test */
 if (
-  process.argv[1] !== undefined &&
-  import.meta.url.endsWith(path.basename(process.argv[1]))
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href
 ) {
-  const repo = process.env["GITHUB_REPOSITORY"] ?? "CodySwannGT/lisa";
-  main(repo, process.cwd())
-    .then(code => {
-      process.exitCode = code;
-    })
-    .catch((error: unknown) => {
-      console.error(String(error));
-      process.exitCode = 1;
-    });
+  runCli();
 }
-/* c8 ignore stop */

package/all/copy-overwrite/scripts/lib/reusable-workflow-load-adapter.d.mts

@@ -0,0 +1,21 @@
+// This file is managed by Lisa and IS replaced on each `lisa` run.
+// Do not edit directly — durable changes belong upstream in Lisa.
+
+import type { RunPage } from "./reusable-workflow-load-scan.mjs";
+export declare const RUNS_PER_PAGE = 100;
+export type GithubRequest = (path: string) => Promise<unknown>;
+export interface AdapterOptions {
+  readonly repo: string;
+  readonly request: GithubRequest;
+  readonly perPage?: number;
+}
+export declare function runsPath(
+  repo: string,
+  page: number,
+  perPage: number
+): string;
+export declare function runPath(repo: string, id: number): string;
+export declare function jobsPath(repo: string, id: number): string;
+export declare function createRunPageFetcher(
+  options: AdapterOptions
+): (page: number) => Promise<RunPage>;

package/{dist/core/reusable-workflow-load-adapter.js → all/copy-overwrite/scripts/lib/reusable-workflow-load-adapter.mjs}

@@ -1,3 +1,6 @@
+// This file is managed by Lisa and IS replaced on each `lisa` run.
+// Do not edit directly — durable changes belong upstream in Lisa.
+
 /**
  * Conclusions worth spending two extra requests on.
  *
@@ -17,7 +20,7 @@ export const RUNS_PER_PAGE = 100;
  * @returns The API path to request
  */
 export function runsPath(repo, page, perPage) {
-    return `repos/${repo}/actions/runs?per_page=${perPage}&page=${page}`;
+  return `repos/${repo}/actions/runs?per_page=${perPage}&page=${page}`;
 }
 /**
  * Path for one run's detail, which is where `referenced_workflows` lives.
@@ -26,7 +29,7 @@ export function runsPath(repo, page, perPage) {
  * @returns The API path to request
  */
 export function runPath(repo, id) {
-    return `repos/${repo}/actions/runs/${id}`;
+  return `repos/${repo}/actions/runs/${id}`;
 }
 /**
  * Path for one run's jobs, read only for its `total_count`.
@@ -35,7 +38,7 @@ export function runPath(repo, id) {
  * @returns The API path to request
  */
 export function jobsPath(repo, id) {
-    return `repos/${repo}/actions/runs/${id}/jobs?per_page=1`;
+  return `repos/${repo}/actions/runs/${id}/jobs?per_page=1`;
 }
 /**
  * Read a property off an unknown decoded body without asserting a shape.
@@ -44,9 +47,8 @@ export function jobsPath(repo, id) {
  * @returns The value, or undefined when the body is not an object
  */
 function field(body, key) {
-    if (typeof body !== "object" || body === null)
-        return undefined;
-    return body[key];
+  if (typeof body !== "object" || body === null) return undefined;
+  return body[key];
 }
 /**
  * Coerce an unknown to a number, defaulting rather than throwing.
@@ -54,7 +56,7 @@ function field(body, key) {
  * @returns The number, or 0 when it is not a finite one
  */
 function count(value) {
-    return typeof value === "number" && Number.isFinite(value) ? value : 0;
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
 }
 /**
  * Coerce an unknown to a string, or empty.
@@ -62,7 +64,7 @@ function count(value) {
  * @returns The string, or empty when it is not one
  */
 function text(value) {
-    return typeof value === "string" ? value : "";
+  return typeof value === "string" ? value : "";
 }
 /**
  * Read the list endpoint's runs array into the fields the scan needs.
@@ -70,17 +72,21 @@ function text(value) {
  * @returns One entry per run, in the order GitHub returned them
  */
 function listedRuns(body) {
-    const runs = field(body, "workflow_runs");
-    if (!Array.isArray(runs))
-        return [];
-    return runs.map((run) => ({
-        id: count(field(run, "id")),
-        path: text(field(run, "path")),
-        createdAt: text(field(run, "created_at")),
-        conclusion: typeof field(run, "conclusion") === "string"
-            ? text(field(run, "conclusion"))
-            : null,
-    }));
+  const runs = field(body, "workflow_runs");
+  if (!Array.isArray(runs)) {
+    throw new Error(
+      "Workflow run list is unreadable: expected workflow_runs array."
+    );
+  }
+  return runs.map(run => ({
+    id: count(field(run, "id")),
+    path: text(field(run, "path")),
+    createdAt: text(field(run, "created_at")),
+    conclusion:
+      typeof field(run, "conclusion") === "string"
+        ? text(field(run, "conclusion"))
+        : null,
+  }));
 }
 /**
  * Gather the two extra facts a candidate run's verdict turns on.
@@ -89,14 +95,14 @@ function listedRuns(body) {
  * @returns The run with its referenced-workflow and job counts filled in
  */
 async function withDetail(listed, options) {
-    const detail = await options.request(runPath(options.repo, listed.id));
-    const jobs = await options.request(jobsPath(options.repo, listed.id));
-    const referenced = field(detail, "referenced_workflows");
-    return {
-        ...listed,
-        referencedCount: Array.isArray(referenced) ? referenced.length : 0,
-        jobCount: count(field(jobs, "total_count")),
-    };
+  const detail = await options.request(runPath(options.repo, listed.id));
+  const jobs = await options.request(jobsPath(options.repo, listed.id));
+  const referenced = field(detail, "referenced_workflows");
+  return {
+    ...listed,
+    referencedCount: Array.isArray(referenced) ? referenced.length : 0,
+    jobCount: count(field(jobs, "total_count")),
+  };
 }
 /**
  * Build the page fetcher `scanForLoadFailures` consumes.
@@ -108,18 +114,21 @@ async function withDetail(listed, options) {
  * @returns A fetcher for one 1-based page of run history
  */
 export function createRunPageFetcher(options) {
-    const perPage = options.perPage ?? RUNS_PER_PAGE;
-    return async (page) => {
-        const body = await options.request(runsPath(options.repo, page, perPage));
-        const listed = listedRuns(body);
-        const runs = await Promise.all(listed.map(async (run) => {
-            if (run.conclusion === null ||
-                !DETAIL_WORTH_FETCHING.includes(run.conclusion)) {
-                return { ...run, referencedCount: 0, jobCount: 0 };
-            }
-            return withDetail(run, options);
-        }));
-        return { runs, hasMore: listed.length === perPage };
-    };
+  const perPage = options.perPage ?? RUNS_PER_PAGE;
+  return async page => {
+    const body = await options.request(runsPath(options.repo, page, perPage));
+    const listed = listedRuns(body);
+    const runs = await Promise.all(
+      listed.map(async run => {
+        if (
+          run.conclusion === null ||
+          !DETAIL_WORTH_FETCHING.includes(run.conclusion)
+        ) {
+          return { ...run, referencedCount: 0, jobCount: 0 };
+        }
+        return withDetail(run, options);
+      })
+    );
+    return { runs, hasMore: listed.length === perPage };
+  };
 }
-//# sourceMappingURL=reusable-workflow-load-adapter.js.map

package/all/copy-overwrite/scripts/lib/reusable-workflow-load-failure.d.mts

@@ -0,0 +1,29 @@
+// This file is managed by Lisa and IS replaced on each `lisa` run.
+// Do not edit directly — durable changes belong upstream in Lisa.
+
+export type RunLoadClass =
+  | "load-failure"
+  | "dead-runner"
+  | "resolved"
+  | "out-of-population"
+  | "skipped"
+  | "inconclusive"
+  | "in-flight";
+export interface RunLoadFacts {
+  readonly inPopulation: boolean;
+  readonly referencedCount: number;
+  readonly jobCount: number;
+  readonly conclusion: string | null;
+}
+export declare function callerDeclaresReusableWorkflow(source: string): boolean;
+export declare function classifyRunLoad(facts: RunLoadFacts): RunLoadClass;
+export interface WindowScan {
+  readonly oldestSeen: string | null;
+  readonly windowStart: string;
+  readonly exhausted: boolean;
+}
+export interface WindowVerdict {
+  readonly covered: boolean;
+  readonly reason: string;
+}
+export declare function windowCoverage(scan: WindowScan): WindowVerdict;

package/all/copy-overwrite/scripts/lib/reusable-workflow-load-failure.mjs

@@ -0,0 +1,124 @@
+// This file is managed by Lisa and IS replaced on each `lisa` run.
+// Do not edit directly — durable changes belong upstream in Lisa.
+
+/**
+ * A job-level `uses:` naming a reusable workflow in another repository.
+ *
+ * The path shape is what discriminates, not a roster of known callers: a
+ * reusable workflow is always `<owner>/<repo>/.github/workflows/<file>@<ref>`.
+ * A step action is `<owner>/<repo>@<ref>` with no path, so `actions/checkout@v6`
+ * cannot match — which matters, because reading step actions as declarations
+ * is exactly what produced 14 false positives out of 19.
+ */
+const CROSS_REPO_USES =
+  /^[ \t]*uses:[ \t]*["']?[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+\/\.github\/workflows\/[A-Za-z0-9._-]+\.ya?ml@[^\s"'#]+/u;
+/**
+ * A job-level `uses:` naming a reusable workflow in the caller's own
+ * repository.
+ *
+ * Unlike the cross-repo arm this one is NOT backed by a measured run — the
+ * ticket's evidence is all cross-repo. It is included because the path shape
+ * is unambiguous and excluding it would leave local reusable workflows
+ * undetectable, but if this detector ever reports a false positive, this is
+ * the first line to suspect.
+ */
+const LOCAL_USES =
+  /^[ \t]*uses:[ \t]*["']?\.\/\.github\/workflows\/[A-Za-z0-9._-]+\.ya?ml/u;
+/** Whether a line is entirely a YAML comment. */
+const COMMENT_LINE = /^\s*#/u;
+/**
+ * Conclusions that can be reached before a single job is created.
+ *
+ * `startup_failure` is GitHub's own name for this class and is the conclusion
+ * a load failure most often carries; `failure` is what the runs measured for
+ * this ticket carried. Anything else — `success`, `cancelled`, `neutral` — is
+ * never a load failure, and treating it as one is how a detector starts
+ * inventing reds.
+ */
+const PRE_JOB_FAILURES = ["failure", "startup_failure"];
+/**
+ * Whether a caller workflow declares any reusable workflow.
+ *
+ * This is the population gate, and it is DERIVED from the caller's own source
+ * rather than read from a roster. There is deliberately no list of known
+ * callers or known upstream repositories anywhere in this module: a roster
+ * would silently exclude every caller nobody remembered to add, which is the
+ * failure mode this codebase already has a ticket for one level up.
+ * @param source - Full text of a caller's workflow file
+ * @returns True when at least one non-comment line calls a reusable workflow
+ */
+export function callerDeclaresReusableWorkflow(source) {
+  return source
+    .split("\n")
+    .some(
+      line =>
+        !COMMENT_LINE.test(line) &&
+        (CROSS_REPO_USES.test(line) || LOCAL_USES.test(line))
+    );
+}
+/**
+ * Classify what a finished run says about reusable-workflow loading.
+ *
+ * The order of these tests is the whole design, so it is worth stating: a run
+ * that RESOLVED something is settled before the population gate is consulted,
+ * because resolution is direct evidence that loading worked and the gate is
+ * only a heuristic about whether the field can speak. That way an
+ * under-detecting population gate can never manufacture a load-failure
+ * verdict — it can only cause one to be missed, which is the direction a
+ * detector should fail in.
+ * @param facts - The four run facts
+ * @returns The single class this run belongs to
+ */
+export function classifyRunLoad(facts) {
+  const { inPopulation, referencedCount, jobCount, conclusion } = facts;
+  if (conclusion === null) return "in-flight";
+  if (conclusion === "skipped") return "skipped";
+  // Resolution outranks the population gate: see the note above.
+  if (referencedCount > 0) return "resolved";
+  if (!inPopulation) return "out-of-population";
+  // Jobs that exist and are empty are a dead runner, not a parse failure.
+  if (jobCount > 0) return "dead-runner";
+  if (!PRE_JOB_FAILURES.includes(conclusion)) return "inconclusive";
+  return "load-failure";
+}
+/**
+ * Whether a page set actually covered the window it claims to report on.
+ *
+ * A first implementation of this detector read one page of runs and filtered
+ * by timestamp. On a busy repository the window's start fell off page one, so
+ * it reported "OK, 100 runs inspected" across a period that contained four
+ * known load failures. It was clean because it could not see. A scan that
+ * cannot cover its window must report an ERROR, never a pass — a detector
+ * that reports success for the range it failed to read is worse than no
+ * detector, because it also retires the suspicion.
+ * @param scan - How far back the page set reached
+ * @returns Covered, or not covered with the reason
+ */
+export function windowCoverage(scan) {
+  const { oldestSeen, windowStart, exhausted } = scan;
+  // An exhausted history is covered even when it stops short: a repository
+  // younger than the window has no earlier runs to read, and refusing it
+  // would be a red nobody can ever clear.
+  if (exhausted) return { covered: true, reason: "" };
+  if (oldestSeen === null) {
+    return {
+      covered: false,
+      reason: `read no runs at all, so it did not reach ${windowStart}. An empty read is not an empty window.`,
+    };
+  }
+  const oldest = Date.parse(oldestSeen);
+  const start = Date.parse(windowStart);
+  if (Number.isNaN(oldest) || Number.isNaN(start)) {
+    return {
+      covered: false,
+      reason: `could not read \`${oldestSeen}\` or \`${windowStart}\` as a timestamp, so it did not reach the start of the window. An unreadable bound is not a satisfied one.`,
+    };
+  }
+  if (oldest > start) {
+    return {
+      covered: false,
+      reason: `paging stopped at ${oldestSeen} and did not reach ${windowStart}, so any load failure older than that was never read. Page further, or narrow the window.`,
+    };
+  }
+  return { covered: true, reason: "" };
+}

package/all/copy-overwrite/scripts/lib/reusable-workflow-load-scan.d.mts

@@ -0,0 +1,36 @@
+// This file is managed by Lisa and IS replaced on each `lisa` run.
+// Do not edit directly — durable changes belong upstream in Lisa.
+
+import { type RunLoadClass } from "./reusable-workflow-load-failure.mjs";
+export interface ScannedRun {
+  readonly id: number;
+  readonly path: string;
+  readonly createdAt: string;
+  readonly referencedCount: number;
+  readonly jobCount: number;
+  readonly conclusion: string | null;
+}
+export interface RunPage {
+  readonly runs: readonly ScannedRun[];
+  readonly hasMore: boolean;
+}
+export interface ScanRequest {
+  readonly fetchPage: (page: number) => Promise<RunPage>;
+  readonly windowStart: string;
+  readonly inPopulation: (path: string) => boolean;
+  readonly maxPages: number;
+}
+export interface ScanFinding {
+  readonly id: number;
+  readonly path: string;
+  readonly verdict: RunLoadClass;
+}
+export interface ScanResult {
+  readonly loadFailures: readonly ScanFinding[];
+  readonly inspected: number;
+  readonly covered: boolean;
+  readonly reason: string;
+}
+export declare function scanForLoadFailures(
+  request: ScanRequest
+): Promise<ScanResult>;

package/all/copy-overwrite/scripts/lib/reusable-workflow-load-scan.mjs

@@ -0,0 +1,102 @@
+// This file is managed by Lisa and IS replaced on each `lisa` run.
+// Do not edit directly — durable changes belong upstream in Lisa.
+
+import {
+  classifyRunLoad,
+  windowCoverage,
+} from "./reusable-workflow-load-failure.mjs";
+/**
+ * Whether a run predates the window, so everything after it can be ignored.
+ * @param run - The run being considered
+ * @param windowStart - ISO timestamp the scan intends to cover back to
+ * @returns True only when this run is at or before the start of the window
+ */
+function reachedWindow(run, windowStart) {
+  const created = Date.parse(run.createdAt);
+  const start = Date.parse(windowStart);
+  // An unparseable timestamp must not read as "we are past the window" —
+  // that would end the scan early and call the short read complete.
+  if (Number.isNaN(created) || Number.isNaN(start)) return false;
+  return created <= start;
+}
+/**
+ * Classify one run through the shared decision.
+ * @param run - The run being classified
+ * @param inPopulation - Whether this run's caller declares a reusable workflow
+ * @returns The run's id, caller path, and verdict
+ */
+function findingFor(run, inPopulation) {
+  return {
+    id: run.id,
+    path: run.path,
+    verdict: classifyRunLoad({
+      inPopulation,
+      referencedCount: run.referencedCount,
+      jobCount: run.jobCount,
+      conclusion: run.conclusion,
+    }),
+  };
+}
+/**
+ * Fold one page into the running scan state.
+ * @param state - Everything the scan has accumulated so far
+ * @param page - The page just fetched
+ * @param request - The scan request, for its window and population test
+ * @returns The scan state after absorbing this page
+ */
+function absorb(state, page, request) {
+  const findings = page.runs
+    .filter(run => !reachedWindow(run, request.windowStart))
+    .map(run => findingFor(run, request.inPopulation(run.path)));
+  const oldest = page.runs.at(-1)?.createdAt ?? state.oldestSeen;
+  const reached = page.runs.some(run =>
+    reachedWindow(run, request.windowStart)
+  );
+  return {
+    findings: [...state.findings, ...findings],
+    inspected: state.inspected + page.runs.length,
+    oldestSeen: oldest,
+    exhausted: !page.hasMore,
+    done: reached || !page.hasMore,
+  };
+}
+/**
+ * Read run history until the window is covered, then report load failures.
+ *
+ * Paging stops on the first of three conditions: a run older than the window
+ * was seen, the history ran out, or `maxPages` was reached. Only the first
+ * two are coverage; hitting the cap leaves `covered` false, because a cap is
+ * a budget the operator set and not evidence about the runs beyond it.
+ * @param request - Fetcher, window, population test, and page cap
+ * @returns Findings plus whether the window was actually covered
+ */
+export async function scanForLoadFailures(request) {
+  const initial = {
+    findings: [],
+    inspected: 0,
+    oldestSeen: null,
+    exhausted: false,
+    done: false,
+  };
+  const final = await Array.from(
+    { length: request.maxPages },
+    (_unused, index) => index + 1
+  ).reduce(async (carried, pageNumber) => {
+    const state = await carried;
+    if (state.done) return state;
+    return absorb(state, await request.fetchPage(pageNumber), request);
+  }, Promise.resolve(initial));
+  const coverage = windowCoverage({
+    oldestSeen: final.oldestSeen,
+    windowStart: request.windowStart,
+    exhausted: final.exhausted,
+  });
+  return {
+    loadFailures: final.findings.filter(
+      finding => finding.verdict === "load-failure"
+    ),
+    inspected: final.inspected,
+    covered: coverage.covered,
+    reason: coverage.reason,
+  };
+}