monkeypatchlist 0.0.0-stage → 0.1.0

package/dist/packages/source-store/lib/integrity.js

@@ -0,0 +1,86 @@
+// Subresource Integrity (§17 Integrity): fetched bytes are checked against the integrity metadata their reference
+// carries, as the SRI spec does it, and bytes that don't match are withheld.
+import { createHash } from 'node:crypto';
+/** The hash algorithms SRI supports (SRI § Cryptographic hash functions), from the weakest to the strongest. */
+const algorithms = ['sha256', 'sha384', 'sha512'];
+/**
+ * The result of fetching `bytes` with the integrity metadata `integrity` (the empty string for none): `ok` with the
+ * check, or `sri-mismatch` with it, and without the bytes, which are never analyzed (§17 Integrity).
+ */
+export function verified(bytes, response, integrity) {
+    const sri = checkIntegrity(integrity, bytes);
+    if (sri === 'none' || sri.result === 'match')
+        return { status: 'ok', response, bytes, sri };
+    const expected = sri.expected.join(' or ');
+    const detail = `the fetched bytes' digest is ${sri.actual}, and the integrity value expects ${expected}`;
+    return { status: 'sri-mismatch', detail, response, sri };
+}
+/** Separates the alternatives of an integrity value (`alternativeIntegrity`): not ASCII whitespace, which separates tokens. */
+const separator = '\u001f';
+/**
+ * One integrity value that stands for several (§17 Integrity): code sets an element's `integrity` to one of
+ * several constants, and the bytes pass when they match any. A single value is returned as it is.
+ */
+export function alternativeIntegrity(values) {
+    return values.join(separator);
+}
+/**
+ * Checks `bytes` against an integrity value, which is integrity metadata or alternatives of it
+ * (`alternativeIntegrity`). The bytes match when they match any alternative, and the check is that alternative's. When
+ * none does, the check expects every alternative's digests, and `actual` is the bytes' digest in the strongest
+ * algorithm any of them names. An alternative that checks nothing makes the value check nothing (`none`), as in a
+ * browser.
+ */
+export function checkIntegrity(integrity, bytes) {
+    const checks = [];
+    for (const alternative of integrity.split(separator)) {
+        const check = checkMetadata(alternative, bytes);
+        if (check === 'none')
+            return 'none';
+        if (check.result === 'match')
+            return check;
+        checks.push(check);
+    }
+    if (checks.length === 1)
+        return checks[0];
+    const algorithm = algorithms.findLast((candidate) => checks.some(({ actual }) => actual.startsWith(`${candidate}-`)));
+    const actual = checks.find((check) => check.actual.startsWith(`${algorithm}-`)).actual;
+    return { result: 'mismatch', expected: checks.flatMap(({ expected }) => expected), actual };
+}
+/**
+ * Checks `bytes` against integrity metadata (SRI § Does response match metadataList?). Only the digests in the
+ * strongest algorithm the metadata names are compared, and the bytes match when any of them is their digest in that
+ * algorithm, base64-encoded. Metadata that names no supported algorithm, the empty string included, checks nothing
+ * (`none`), as in a browser.
+ */
+function checkMetadata(integrity, bytes) {
+    const metadata = parseMetadata(integrity);
+    if (metadata.length === 0)
+        return 'none';
+    // The strongest algorithm named (SRI § Get the strongest metadata). Spreading the metadata into `Math.max` would
+    // overflow the stack on a long enough integrity value, which a page supplies.
+    const named = new Set(metadata.map((item) => item.algorithm));
+    const algorithm = algorithms.findLast((candidate) => named.has(candidate));
+    const strongest = metadata.filter((item) => item.algorithm === algorithm);
+    const digest = createHash(algorithm).update(bytes).digest('base64');
+    return {
+        result: strongest.some(({ value }) => value === digest) ? 'match' : 'mismatch',
+        expected: strongest.map(({ value }) => `${algorithm}-${value}`),
+        actual: `${algorithm}-${digest}`,
+    };
+}
+/**
+ * Parses integrity metadata (SRI § Parse metadata): each token separated by ASCII whitespace is an algorithm and a
+ * base64 value, joined by `-`, optionally followed by `?` and options, which are ignored. A token whose algorithm is
+ * not a supported one, ignoring ASCII case, is skipped.
+ */
+function parseMetadata(integrity) {
+    const metadata = [];
+    for (const token of integrity.split(/[\t\n\f\r ]+/)) {
+        const [name = '', value = ''] = token.split('?')[0].split('-');
+        const algorithm = algorithms.find((supported) => supported === name.replace(/[A-Z]/g, (c) => c.toLowerCase()));
+        if (algorithm !== undefined)
+            metadata.push({ algorithm, value });
+    }
+    return metadata;
+}

package/dist/packages/source-store/lib/outcomes.d.ts

@@ -0,0 +1,12 @@
+import type { FetchedResponse } from '../index.ts';
+/** The safety floor refuses the fetch: a scheme, address, size, count, redirect or content-type refusal. */
+export declare class Refusal extends Error {
+    /** The response the refusal was made on, if there was one. */
+    readonly response: FetchedResponse | null;
+    constructor(detail: string, response?: FetchedResponse | null);
+}
+/** The fetch failed: a timeout, a DNS, connection or TLS error, or a response that can't be read. */
+export declare class Failure extends Error {
+}
+/** An error's code, or its message. */
+export declare function reason(error: unknown): string;

package/dist/packages/source-store/lib/outcomes.js

@@ -0,0 +1,22 @@
+// How the resolve fetcher's steps report the two ways a fetch can end without bytes (§17 Outcomes). They are thrown
+// inside the fetcher and returned from it as data.
+/** The safety floor refuses the fetch: a scheme, address, size, count, redirect or content-type refusal. */
+export class Refusal extends Error {
+    /** The response the refusal was made on, if there was one. */
+    response;
+    constructor(detail, response = null) {
+        super(detail);
+        this.response = response;
+    }
+}
+/** The fetch failed: a timeout, a DNS, connection or TLS error, or a response that can't be read. */
+export class Failure extends Error {
+}
+/** An error's code, or its message. */
+export function reason(error) {
+    if (error instanceof Error) {
+        const code = error.code;
+        return code === undefined || error.message.includes(code) ? error.message : `${code}: ${error.message}`;
+    }
+    return String(error);
+}

package/dist/packages/source-store/lib/proxy.d.ts

@@ -0,0 +1,11 @@
+/** A proxy to tunnel a request through: its URL, and the `Proxy-Authorization` its credentials give. */
+export interface Proxy {
+    url: URL;
+    authorization: string | null;
+}
+/**
+ * The proxy for `url`, from the environment, or null to connect directly. Only `https:` is proxied, through
+ * `HTTPS_PROXY` (or `https_proxy`), and not to a host `NO_PROXY` (or `no_proxy`) names. The credentials sent to it are
+ * the ones in its URL, and no others.
+ */
+export declare function proxyFor(url: URL, env: Readonly<Record<string, string | undefined>>): Proxy | null;

package/dist/packages/source-store/lib/proxy.js

@@ -0,0 +1,53 @@
+// The proxy the floor honours (§17 Safety floor: Proxies): `HTTPS_PROXY`, except for the hosts `NO_PROXY` names.
+import { Failure } from "./outcomes.js";
+import { hostOf, portOf } from "./urls.js";
+/**
+ * The proxy for `url`, from the environment, or null to connect directly. Only `https:` is proxied, through
+ * `HTTPS_PROXY` (or `https_proxy`), and not to a host `NO_PROXY` (or `no_proxy`) names. The credentials sent to it are
+ * the ones in its URL, and no others.
+ */
+export function proxyFor(url, env) {
+    if (url.protocol !== 'https:')
+        return null;
+    const setting = (env.HTTPS_PROXY ?? env.https_proxy ?? '').trim();
+    if (setting === '' || bypasses(url, env.NO_PROXY ?? env.no_proxy ?? ''))
+        return null;
+    const proxy = URL.parse(/^[a-z][a-z\d+.-]*:\/\//i.test(setting) ? setting : `http://${setting}`);
+    if (proxy === null || (proxy.protocol !== 'http:' && proxy.protocol !== 'https:')) {
+        throw new Failure(`HTTPS_PROXY is not an http: or https: proxy URL: ${setting}`);
+    }
+    if (proxy.username === '')
+        return { url: proxy, authorization: null };
+    let credentials;
+    try {
+        credentials = `${decodeURIComponent(proxy.username)}:${decodeURIComponent(proxy.password)}`;
+    }
+    catch {
+        throw new Failure("HTTPS_PROXY's credentials are not well-formed percent-encoding");
+    }
+    return { url: proxy, authorization: `Basic ${Buffer.from(credentials).toString('base64')}` };
+}
+/**
+ * Whether `NO_PROXY` names the URL's host: `*`, the host itself, or a domain it is in (`example.com` or `.example.com`
+ * for `cdn.example.com`), with or without a port, ignoring case.
+ */
+function bypasses(url, noProxy) {
+    const host = hostOf(url).toLowerCase();
+    const port = portOf(url);
+    return noProxy
+        .split(/[\s,]+/)
+        .filter((entry) => entry !== '')
+        .some((entry) => {
+        if (entry === '*')
+            return true;
+        const lower = entry.toLowerCase();
+        // A host, `[IPv6]` or an IPv6 address, then an optional port.
+        const bracketed = /^\[(.*)\](?::(\d+))?$/.exec(lower);
+        const parts = lower.split(':');
+        const [named = '', entryPort] = bracketed !== null ? bracketed.slice(1) : parts.length === 2 ? parts : [lower];
+        if (entryPort !== undefined && Number(entryPort) !== port)
+            return false;
+        const name = named.replace(/^\*?\./, '');
+        return name !== '' && (host === name || host.endsWith(`.${name}`));
+    });
+}

package/dist/packages/source-store/lib/session.d.ts

@@ -0,0 +1,12 @@
+import type { Fetcher } from '../index.ts';
+import type { Connect, Limits, Lookup } from '../resolve.ts';
+export interface SessionOptions {
+    version: string;
+    env: Readonly<Record<string, string | undefined>>;
+    lookup: Lookup;
+    connect: Connect;
+    ca: string | string[] | null;
+    limits: Limits;
+    clock: () => number;
+}
+export declare function createSession(options: SessionOptions): Fetcher;

package/dist/packages/source-store/lib/session.js

@@ -0,0 +1,139 @@
+// One scan's resolve fetcher: the floor's per-fetch rules, and the state its scan-wide limits and its cache keep.
+import { open } from "./connection.js";
+import { blockedTypeRefusal, javascriptTypeRefusal } from "./content-types.js";
+import { Sockets, within } from "./deadline.js";
+import { exchange } from "./exchange.js";
+import { verified } from "./integrity.js";
+import { Failure, Refusal } from "./outcomes.js";
+import { hostOf, withoutFragment } from "./urls.js";
+export function createSession(options) {
+    /** What requesting each URL gave, by URL without its fragment: each URL is requested once per scan (§17 Caching). */
+    const hops = new Map();
+    /** The bytes of every response body read so far, decompressed (§17 Size). */
+    let scanned = 0;
+    /** How long the scan's requests have taken so far, in all (§17 Time). */
+    let spent = 0;
+    /** The remote URLs the scan has fetched, without their fragments (§17 Count). A redirect's target isn't one. */
+    const fetched = new Set();
+    function hop(url) {
+        let found = hops.get(url.href);
+        if (found === undefined)
+            hops.set(url.href, (found = request(url)));
+        return found;
+    }
+    /**
+     * Requests `url` once: its connection may take the connect limit, and the whole request the request limit, or what
+     * is left of the scan's (§17 Time). Once the scan's is spent, nothing more is requested.
+     */
+    async function request(url) {
+        const { connectMs, requestMs, scanMs, responseBytes, scanBytes } = options.limits;
+        const left = scanMs - spent;
+        const outOfTime = () => new Failure(`the scan's fetches took longer than the safety floor's ${scanMs} ms in all`);
+        if (left <= 0)
+            return failed(outOfTime());
+        const sockets = new Sockets();
+        const start = options.clock();
+        try {
+            const connecting = open(url, options, sockets);
+            const connection = await within(connecting, Math.min(connectMs, left), () => connectMs <= left
+                ? new Failure(`connecting to ${hostOf(url)} took longer than the safety floor's ${connectMs} ms`)
+                : outOfTime());
+            const exchanging = exchange(url, connection, options, { responseBytes, scanBytes, scanned });
+            const answer = await within(exchanging, Math.min(requestMs, left) - (options.clock() - start), () => requestMs <= left
+                ? new Failure(`the request for ${url.href} took longer than the safety floor's ${requestMs} ms`)
+                : outOfTime());
+            scanned += answer.bytes?.length ?? 0;
+            return { kind: 'response', ...answer };
+        }
+        catch (error) {
+            if (error instanceof Refusal)
+                return { kind: 'refused', detail: error.message, response: error.response };
+            if (error instanceof Failure)
+                return failed(error);
+            throw error;
+        }
+        finally {
+            sockets.close();
+            spent += options.clock() - start;
+        }
+    }
+    return {
+        /**
+         * Fetches `requested` as `request` asks for it, following redirects. Every hop is checked against the whole floor
+         * (§17 Redirects): its scheme here, its address when it is connected to. A fragment is never requested. The bytes
+         * are checked against the request's integrity value, if any (§17 Integrity).
+         */
+        async fetch(requested, { destination, document, integrity = '' }) {
+            let url = withoutFragment(new URL(requested));
+            const scheme = schemeRefusal(url, document);
+            if (scheme !== null)
+                return refused(scheme);
+            const { artifacts } = options.limits;
+            if (!fetched.has(url.href)) {
+                if (fetched.size >= artifacts)
+                    return refused(`the safety floor fetches at most ${artifacts} remote artifacts`);
+                fetched.add(url.href);
+            }
+            // There is no separate loop check: a loop is refused when it reaches the sixth redirect, as any chain is. Each
+            // URL in it is still requested once, since a hop's outcome is cached.
+            for (let redirects = 0;; redirects++) {
+                const outcome = await hop(url);
+                if (outcome.kind === 'failed')
+                    return failure(outcome.detail);
+                if (outcome.kind === 'refused')
+                    return refused(outcome.detail, outcome.response);
+                const { response, status, location, nosniff, bytes } = outcome;
+                if (redirectStatuses.has(status) && location !== null) {
+                    const next = URL.parse(location, url.href);
+                    if (next === null)
+                        return failure(`a redirect to ${location}, which isn't a URL`, response);
+                    url = withoutFragment(next);
+                    if (redirects === options.limits.redirects) {
+                        return refused(`the safety floor follows at most ${options.limits.redirects} redirects`);
+                    }
+                    const hopScheme = schemeRefusal(url, document);
+                    if (hopScheme !== null)
+                        return refused(`${hopScheme}, in a redirect to ${url.href}`);
+                    continue;
+                }
+                if (status < 200 || status > 299 || bytes === null)
+                    return failure(`HTTP ${status}`, response);
+                // The body was read whatever the destination, so a URL fetched as another is still requested once. The checks
+                // run in the browser's order (§17 Content types): blocked types and `nosniff`, integrity, then the JavaScript
+                // MIME type that modules and workers need.
+                const blocked = blockedTypeRefusal(destination, response.contentType, nosniff);
+                if (blocked !== null)
+                    return refused(blocked, response);
+                const checked = verified(bytes, response, integrity);
+                if (checked.status !== 'ok')
+                    return checked;
+                const type = javascriptTypeRefusal(destination, response.contentType);
+                return type === null ? checked : refused(type, response, checked.sri);
+            }
+        },
+    };
+}
+function failed(error) {
+    return { kind: 'failed', detail: error.message };
+}
+/** The statuses a browser follows a `Location` for (Fetch § HTTP-redirect fetch). */
+const redirectStatuses = new Set([301, 302, 303, 307, 308]);
+function refused(detail, response = null, sri = 'none') {
+    return { status: 'remote-refused', detail, response, sri };
+}
+function failure(detail, response = null) {
+    return { status: 'fetch-failed', detail, response };
+}
+/**
+ * Why the floor refuses to fetch `url` for the entry document `document`, or null when it doesn't (§17 Schemes):
+ * `https:` is fetched for any document, and `http:` only for an `http:` one.
+ */
+function schemeRefusal(url, document) {
+    if (url.protocol === 'https:')
+        return null;
+    const from = new URL(document).protocol;
+    if (url.protocol === 'http:' && from === 'http:')
+        return null;
+    const allowed = from === 'http:' ? '`https:` and `http:`' : '`https:`';
+    return `the safety floor fetches only ${allowed} for an \`${from}\` document, not \`${url.protocol}\``;
+}

package/dist/packages/source-store/lib/urls.d.ts

@@ -0,0 +1,6 @@
+/** The URL's host, without the brackets of an IPv6 literal. */
+export declare function hostOf(url: URL): string;
+/** The URL's port, or its scheme's default. */
+export declare function portOf(url: URL): number;
+/** The URL without its fragment, which is never part of a request. */
+export declare function withoutFragment(url: URL): URL;

package/dist/packages/source-store/lib/urls.js

@@ -0,0 +1,15 @@
+// The parts of a URL a request is made from.
+/** The URL's host, without the brackets of an IPv6 literal. */
+export function hostOf(url) {
+    return url.hostname.replace(/^\[(.*)\]$/, '$1');
+}
+/** The URL's port, or its scheme's default. */
+export function portOf(url) {
+    return url.port === '' ? (url.protocol === 'https:' ? 443 : 80) : Number(url.port);
+}
+/** The URL without its fragment, which is never part of a request. */
+export function withoutFragment(url) {
+    const copy = new URL(url);
+    copy.hash = '';
+    return copy;
+}

package/dist/packages/source-store/resolve.d.ts

@@ -0,0 +1,59 @@
+import type { Duplex } from 'node:stream';
+import type { Fetcher } from './index.ts';
+/** The floor's limits (§17 Safety floor). The defaults are §17's; Release 2 makes them configurable (§22). */
+export interface Limits {
+    /** The most redirects one fetch follows. */
+    redirects: number;
+    /** The most bytes one response may have, decompressed. */
+    responseBytes: number;
+    /** The most bytes all the responses of a scan may have, decompressed. */
+    scanBytes: number;
+    /** How long a connection may take to open: the lookup, the connect, and any proxy tunnel and TLS handshake. */
+    connectMs: number;
+    /** How long one request may take, from opening its connection to the end of its body. */
+    requestMs: number;
+    /** How long all the fetches of a scan may take together. */
+    scanMs: number;
+    /** The most remote artifacts a scan fetches. */
+    artifacts: number;
+}
+export declare const defaultLimits: Readonly<Limits>;
+/** An address a host name resolves to. */
+export interface ResolvedAddress {
+    address: string;
+    family: 4 | 6;
+}
+/** The DNS hook: every address a host name resolves to. */
+export type Lookup = (hostname: string) => Promise<ResolvedAddress[]>;
+/**
+ * The connect hook: opens a TCP connection to an address the floor has checked, resolving once it is connected. When
+ * `signal` aborts first, because a time limit ran out, it stops connecting and rejects.
+ */
+export type Connect = (target: ResolvedAddress & {
+    port: number;
+    signal: AbortSignal;
+}) => Promise<Duplex>;
+export interface ResolveFetcherOptions {
+    /** monkeypatchlist's version, which the `User-Agent` names. */
+    version: string;
+    /** The environment, which `HTTPS_PROXY` and `NO_PROXY` are read from. */
+    env: Readonly<Record<string, string | undefined>>;
+    /** The DNS hook. The system resolver by default. */
+    lookup?: Lookup;
+    /** The connect hook. A `net` socket by default. */
+    connect?: Connect;
+    /**
+     * Certificate authorities to trust instead of Node's, for tests. TLS is verified whatever this is: nothing turns
+     * verification off.
+     */
+    ca?: string | string[];
+    /** The floor's limits; §17's by default. */
+    limits?: Partial<Limits>;
+    /** A monotonic clock in milliseconds, for the scan-wide time limit. */
+    clock?: () => number;
+}
+/**
+ * A resolve fetcher for one scan. Each URL is requested at most once however often it is asked for, and the scan-wide
+ * limits (bytes, time and artifacts) count everything it fetches. Nothing it holds outlives it.
+ */
+export declare function resolveFetcher(options: ResolveFetcherOptions): Fetcher;

package/dist/packages/source-store/resolve.js

@@ -0,0 +1,45 @@
+// The resolve fetcher (§17, §19 Source store and retrieval): fetches remote URLs under §17's fixed safety floor, which
+// it enforces entirely inside itself, and checks their bytes against the integrity value each request carries (§17
+// Integrity). It is made for one scan, and caches nothing beyond it.
+import { lookup as systemLookup } from 'node:dns/promises';
+import { connect as netConnect } from 'node:net';
+import { createSession } from "./lib/session.js";
+export const defaultLimits = {
+    redirects: 5,
+    responseBytes: 20 * 1024 * 1024,
+    scanBytes: 100 * 1024 * 1024,
+    connectMs: 10_000,
+    requestMs: 30_000,
+    scanMs: 5 * 60_000,
+    artifacts: 500,
+};
+/**
+ * A resolve fetcher for one scan. Each URL is requested at most once however often it is asked for, and the scan-wide
+ * limits (bytes, time and artifacts) count everything it fetches. Nothing it holds outlives it.
+ */
+export function resolveFetcher(options) {
+    return createSession({
+        version: options.version,
+        env: options.env,
+        lookup: options.lookup ?? systemLookupAll,
+        connect: options.connect ?? tcpConnect,
+        ca: options.ca ?? null,
+        limits: { ...defaultLimits, ...options.limits },
+        clock: options.clock ?? (() => performance.now()),
+    });
+}
+async function systemLookupAll(hostname) {
+    const addresses = await systemLookup(hostname, { all: true, order: 'verbatim' });
+    return addresses.map(({ address, family }) => ({ address, family: family === 6 ? 6 : 4 }));
+}
+function tcpConnect({ address, port, signal }) {
+    return new Promise((resolve, reject) => {
+        // An abort destroys the socket, which then rejects, however far it has got.
+        const socket = netConnect({ host: address, port, signal });
+        socket.once('connect', () => {
+            socket.off('error', reject);
+            resolve(socket);
+        });
+        socket.once('error', reject);
+    });
+}

package/dist/scan.d.ts

@@ -0,0 +1,65 @@
+import { type CatalogChangelog, type SerializedCatalog } from './catalog.ts';
+import { type Budget, type Resolver } from './packages/analysis/index.ts';
+import { type LockfileInput } from './packages/attribution/index.ts';
+import type { Baseline, BaselineNote, PreviousValues } from './packages/baseline/index.ts';
+import type { ScanConfig } from './packages/config/index.ts';
+import { type ResolvedReference } from './packages/discovery/index.ts';
+import { type GroupRunner } from './packages/parallel/index.ts';
+import type { ReportInput } from './packages/report/index.ts';
+import { type SourceStore } from './packages/source-store/index.ts';
+export interface ScanDeps {
+    store: SourceStore;
+    catalog: SerializedCatalog;
+    /** The catalog changelog shipped with the catalog, which `explainedBy` comes from (§4 Catalog versions). */
+    changelog: CatalogChangelog;
+    resolver: Resolver;
+    monkeypatchlistVersion: string;
+    /**
+     * The baseline to compare with (§11), its path as given, and scan-level notes on it such as version skew (§4), or null
+     * for none. `previous` is the previous scan's values the reachability and install-context notes compare with (§11
+     * Never `changed`): `--previous`'s, or the baseline's when it is a full report, or null for none.
+     */
+    baseline: {
+        path: string;
+        baseline: Baseline;
+        notes: BaselineNote[];
+        previous: PreviousValues | null;
+    } | null;
+    crashGuard: CrashGuard;
+    /**
+     * The step budget per source byte of a link group, and the caps (§18). Implementation detail, never a user flag: the
+     * CLI passes the shipped constants, and the cost benchmark passes them multiplied for its raised-budget rerun.
+     */
+    budget: Budget;
+    /**
+     * What runs the link groups (§18 Parallelism): by default the resolver in process, one group after another. Results
+     * merge in group order whatever runs them, so a parallel runner prints the same report.
+     */
+    groups?: GroupRunner;
+    /**
+     * The lockfile `--lockfile` names, read by the CLI (§10 Introducing dependencies), or null when none is given. It only
+     * adds evidence: introducers, lockfile versions and workspaces (ADR 0006).
+     */
+    lockfile?: LockfileInput | null;
+}
+/**
+ * The wall-clock crash guard (§13, §18). The CLI reads the clock for it, so the pipeline stays free of wall-clock time.
+ * It is asked before each link group, never inside one: once it has fired, no further group runs, and the scan is
+ * `incomplete`. It never changes results: a scan whose guard fired reports no findings, whichever group it fired
+ * before, so every baseline entry is `unconfirmed`.
+ */
+export interface CrashGuard {
+    fired(): boolean;
+}
+/**
+ * Runs a scan, and returns everything the report needs except the `run` block.
+ *
+ * The scan runs in rounds (§19 References only the resolver can see): discover, analyze the link groups, take the
+ * references only the resolver can see, and discover again with them, until a round's groups find no reference the
+ * round didn't start from. Each round discovers and analyzes the whole artifact graph its references give, so the
+ * result is the last round's: analyzing, over the final artifact set, every referenced entry's group, then each swept
+ * artifact no group links, whatever rounds led there (The result doesn't depend on the rounds). A group whose job is
+ * the same as in an earlier round isn't analyzed again: the resolver is a pure function of its job. `seed` gives the
+ * first round's references.
+ */
+export declare function scan(config: ScanConfig, deps: ScanDeps, seed?: readonly ResolvedReference[]): Promise<Omit<ReportInput, 'run'>>;