monkeypatchlist 0.0.0-stage → 0.1.0

package/dist/packages/config/lib/scan-config-id.js

@@ -0,0 +1,54 @@
+// The scan-config id (§16 Scan configuration identity, ADR 0017): a hash of the settings that decide which findings
+// can exist, recorded in a baseline so that it is never compared with a scan of something else.
+import { createHash } from 'node:crypto';
+import { posix } from 'node:path';
+import { realms } from "../../../catalog.js";
+/**
+ * The fields the id is made of, in the order of its parts. The mode, the source-map directories and the lockfile are
+ * not among them: remote gaps already become `unconfirmed`, and maps and lockfile are optional evidence (ADR 0006).
+ */
+export const scanConfigFields = ['entries', 'mappings', 'surface', 'realms'];
+/**
+ * The scan-config id: one 12-hex-digit part per field of `scanConfigFields`, joined with `.`, so that two ids name the
+ * fields that differ (§16). Each part is the start of the SHA-256 of the field's canonical JSON:
+ *
+ * - entries: `[file, url]` pairs, sorted
+ * - mappings: `[url, dir]` pairs, sorted
+ * - surface: the scope
+ * - realms: the realm set, sorted. R1 has no setting that narrows it, so every scan covers all four realms (§2).
+ *
+ * Only what decides the findings counts: the order of entries and mappings doesn't (the longest mapping prefix wins),
+ * and a path is normalized, without a trailing `/`.
+ */
+export function scanConfigId(config) {
+    const fields = {
+        entries: config.entries.map(({ file, url }) => [path(file), url]).sort(comparePairs),
+        mappings: config.mappings.map(({ url, dir }) => [url, path(dir)]).sort(comparePairs),
+        surface: config.surface,
+        realms: [...realms].sort(),
+    };
+    return scanConfigFields.map((field) => digest(fields[field])).join('.');
+}
+/**
+ * The fields in which two scan-config ids differ, in the order of `scanConfigFields`: none when they are the same id.
+ * An id that doesn't have one part per field can't be read part by part, so it differs in every field.
+ */
+export function differingScanConfigFields(a, b) {
+    const [ours, theirs] = [a.split('.'), b.split('.')];
+    const readable = ours.length === scanConfigFields.length && theirs.length === scanConfigFields.length;
+    return scanConfigFields.filter((_, i) => !readable || ours[i] !== theirs[i]);
+}
+function digest(value) {
+    return createHash('sha256').update(JSON.stringify(value)).digest('hex').slice(0, 12);
+}
+/** A relative path in one spelling: `./assets/` and `assets` are the same directory. */
+function path(value) {
+    const normalized = posix.normalize(value);
+    return normalized.length > 1 && normalized.endsWith('/') ? normalized.slice(0, -1) : normalized;
+}
+function comparePairs(a, b) {
+    return compare(a[0], b[0]) || compare(a[1], b[1]);
+}
+function compare(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}

package/dist/packages/config/lib/schema.d.ts

@@ -0,0 +1,2 @@
+/** Validates a parsed config file against the shipped schema. Returns one line per problem, each naming its path. */
+export declare function schemaProblems(value: unknown): string[];

package/dist/packages/config/lib/schema.js

@@ -0,0 +1,31 @@
+// The config JSON Schema (§16) that ships in the package, at `schema/config.schema.json`. It validates the file.
+import { readFileSync } from 'node:fs';
+import { Ajv2020 } from 'ajv/dist/2020.js';
+let validate;
+/** Validates a parsed config file against the shipped schema. Returns one line per problem, each naming its path. */
+export function schemaProblems(value) {
+    validate ??= new Ajv2020({ allErrors: true, strict: true }).compile(JSON.parse(readFileSync(new URL('../../../../schema/config.schema.json', import.meta.url), 'utf8')));
+    return validate(value) ? [] : (validate.errors ?? []).map(problem);
+}
+/** A validation error as `<JSON Pointer>: <what is wrong>`. */
+function problem({ keyword, instancePath, params, message }) {
+    switch (keyword) {
+        case 'additionalProperties':
+            return `${instancePath}/${escape(params.additionalProperty)}: unknown key`;
+        case 'required':
+            return `${instancePath}/${escape(params.missingProperty)}: is required`;
+        case 'enum': {
+            const allowed = params.allowedValues;
+            return `${at(instancePath)}: must be one of ${allowed.map((value) => JSON.stringify(value)).join(', ')}`;
+        }
+        default:
+            return `${at(instancePath)}: ${message}`;
+    }
+}
+function at(pointer) {
+    return pointer === '' ? '(top level)' : pointer;
+}
+/** Escapes a key as a JSON Pointer reference token (RFC 6901). */
+function escape(key) {
+    return key.replaceAll('~', '~0').replaceAll('/', '~1');
+}

package/dist/packages/config/lib/types.d.ts

@@ -0,0 +1,64 @@
+/** A URL→path mapping (§2): URLs under `url` are files under `dir`, relative to the build directory. */
+export interface Mapping {
+    url: string;
+    dir: string;
+}
+/** An entry document (§2): its file, relative to the build directory, and its URL. */
+export interface Entry {
+    file: string;
+    url: string;
+}
+/** The surface a scan reports, baselines and gates (§12, §16 `--surface`). */
+export type SurfaceScope = 'protected' | 'all';
+/** The remote retrieval mode (§17 Modes, §16 `--mode`): `offline` never fetches, and `resolve` does. */
+export type Mode = 'offline' | 'resolve';
+/** The baseline states the gate can fail on (§11 The gate, §16 `--fail-on`): `removed` and `unconfirmed` can't gate. */
+export declare const failOnStates: readonly ["added", "changed"];
+export type FailOnState = (typeof failOnStates)[number];
+/** The commands (§16 Commands) built so far. */
+export type Command = 'scan' | BaselineCommand;
+/** The baseline commands (§11 Commands): each writes the baseline `--out` names. */
+export type BaselineCommand = 'baseline init' | 'baseline update';
+/** Bad flags or configuration: exit code 2 (§16). */
+export declare class UsageError extends Error {
+    name: string;
+}
+/**
+ * What the config file and the flags each give (§16): every field is optional, and a flag overrides the file field by
+ * field. An entry's URL may be left out; it defaults to the first mapping's URL.
+ */
+export interface Settings {
+    name?: string;
+    entries?: {
+        file: string;
+        url?: string;
+    }[];
+    mappings?: Mapping[];
+    sourceMaps?: string[];
+    surface?: SurfaceScope;
+    mode?: Mode;
+    /**
+     * The lockfile (§10 Introducing dependencies): `--lockfile` sets `path`, and the config key `lockfile.importer` names
+     * the workspace of the scanned application.
+     */
+    lockfile?: {
+        path?: string;
+        importer?: string;
+    };
+    json?: string;
+    out?: string;
+    baseline?: string;
+    /** `--previous`: a previous JSON scan report, for the reachability and install-context notes (§16). */
+    previous?: string;
+    failOn?: FailOnState[];
+    allowIncomplete?: boolean;
+    allowDowngrade?: boolean;
+    /** The saved JSON report `explain` reads (§16 `--report`). */
+    report?: string;
+    /** `--verbose`: the terminal report cards existing findings too (§15 Terminal). */
+    verbose?: boolean;
+    /** `--list-ineffective`: the terminal report lists the ineffective-write records (§3, §16). */
+    listIneffective?: boolean;
+    /** `--no-color`: the terminal report is never colored (§15 Formatting). */
+    noColor?: boolean;
+}

package/dist/packages/config/lib/types.js

@@ -0,0 +1,6 @@
+/** The baseline states the gate can fail on (§11 The gate, §16 `--fail-on`): `removed` and `unconfirmed` can't gate. */
+export const failOnStates = ['added', 'changed'];
+/** Bad flags or configuration: exit code 2 (§16). */
+export class UsageError extends Error {
+    name = 'UsageError';
+}

package/dist/packages/config/lib/urls.d.ts

@@ -0,0 +1,6 @@
+/** The canonical form of an absolute `http:` or `https:` URL, or why `value` is not one. */
+export declare function httpUrl(value: string): {
+    href: string;
+} | {
+    problem: string;
+};

package/dist/packages/config/lib/urls.js

@@ -0,0 +1,9 @@
+/** The canonical form of an absolute `http:` or `https:` URL, or why `value` is not one. */
+export function httpUrl(value) {
+    const url = URL.parse(value);
+    if (url === null)
+        return { problem: `'${value}' is not an absolute URL` };
+    if (url.protocol !== 'http:' && url.protocol !== 'https:')
+        return { problem: `'${value}' is not an http: or https: URL` };
+    return { href: url.href };
+}

package/dist/packages/discovery/index.d.ts

@@ -0,0 +1,277 @@
+import type { Realm, SerializedCatalog } from '../../catalog.ts';
+import type { GeneratedLocation } from '../analysis/index.ts';
+import type { HtmlCounters, LimitationRecord, SourceMapDirectoryCounts, SourceMapPairing, SweptFiles, UnreadMaps } from '../completeness/index.ts';
+import type { Entry } from '../config/index.ts';
+import { type Retrieval, type SourceStore } from '../source-store/index.ts';
+import { type LineReading } from './lib/source-maps.ts';
+/** A script artifact of the artifact graph (§2). */
+export interface Artifact {
+    url: string;
+    /** Build-relative POSIX path, for a local file; null for an inline script. */
+    path: string | null;
+    /**
+     * The content hash: `sha256:` and the hex digest of the artifact's bytes (an inline script's UTF-8 text); null when
+     * its bytes could not be read, or were withheld because they don't match their integrity value (§17 Integrity).
+     */
+    hash: string | null;
+    /**
+     * Where it is served from (§2): the build (`local-build`, through a URL mapping), the entry document itself
+     * (`inline`), or elsewhere, on the entry document's origin (`same-origin`) or another (`cross-origin`).
+     */
+    origin: 'local-build' | 'same-origin' | 'cross-origin' | 'inline';
+    /**
+     * How it was found (§2): by following a reference, as a script the page's code injects (`injected`), or only by the
+     * build-directory sweep.
+     */
+    discovery: 'reference' | 'injected' | 'sweep';
+    /**
+     * `module` for a module script: a `type=module` script, a `<link rel=modulepreload>`, what a module request (a
+     * static or dynamic import, or a re-export) names, or a worker created with `type: "module"`. `script` for a classic
+     * one. A file only a `<link rel=preload as=script>` names, or only preloads that disagree, and a worker created with
+     * options that can't be read statically, are typed by their syntax, as a sweep-only file is (§2). A URL a page runs
+     * both ways is an artifact each way.
+     */
+    sourceType: 'script' | 'module';
+    /**
+     * The realm it runs in, from how it was referenced (§2 Realm): `window` for what an entry document references, the
+     * worker's realm for a worker script (`new Worker`, `new SharedWorker`, `navigator.serviceWorker.register`), and the
+     * realm of the code that references it for an import or an `importScripts`. A URL referenced in two realms is an
+     * artifact in each.
+     */
+    realm: Realm;
+    /**
+     * How its realm is known (§2 Realm): from how it was referenced (`reference`), or assumed to be `window` because only
+     * the sweep found it, only a `<link rel=preload as=script>` names it, or only the module requests of code whose realm
+     * is assumed name it (`assumed`).
+     */
+    realmBasis: 'reference' | 'assumed';
+    /**
+     * The URL of what first references it in its realm (§2 parent or importer): the entry document whose element names
+     * it, or the script or module that imports it or creates the worker. Null for an artifact only the sweep found.
+     */
+    parent: string | null;
+    /**
+     * Its source map (§2 Source maps): the first candidate that verifies, found by the `SourceMap` header of a fetched
+     * artifact, then its `sourceMappingURL` annotation, then a `<file>.map` sidecar, then a map in the build directory with
+     * its `debugId`, then in each source-map directory, a map with its `debugId`, its annotation mirrored there, and its
+     * sidecar mirrored there.
+     */
+    sourceMap: SourceMapPairing;
+    /**
+     * The source map that verified, for attribution (§10), which reads it from its raw JSON: that JSON, and the line
+     * reading of the artifact's text that verified it (§2 Verification). Null when none did. It isn't reported.
+     */
+    map: PairedMap | null;
+    /**
+     * How many candidate maps failed verification against it (§2 Source maps), each counted `stale`: those before the
+     * one that verified, or every one, when none did. A source-map directory's map verified only to count it, after one
+     * already verified, is not counted.
+     */
+    staleCandidates: number;
+    /**
+     * The maps it names, as a remote artifact, that weren't read (§17 Content types): refused by the safety floor, failed,
+     * or a build file that exists but can't be read. They change counters only, never completeness.
+     */
+    unreadMaps: UnreadMaps;
+    /** How its bytes were retrieved (§17 What is recorded): whether they were read (`ok`), or why not. */
+    retrieval: Retrieval;
+    /**
+     * Whether a reference runs it. It does not when only preloads name it (`<link rel=preload as=script>` or `<link
+     * rel=modulepreload>`), or module requests of files that don't run: a preload joins the artifact graph, but never
+     * makes a file run (§19 HTML rules), and a module runs only when its importer does. Nor does it when only the sweep
+     * found it.
+     */
+    runs: boolean;
+    /** The script's source text, when its bytes were read. */
+    text: string | null;
+}
+/**
+ * A verified source map (§2 Source maps): its raw JSON, the line reading of the artifact that verified it, and `base`,
+ * the build-relative path whose directory its relative sources resolve against (§10): the map's own path. A
+ * source-map directory's map has its path inside the directory, as if the directory mirrored the build, however it
+ * was paired, and a `data:` URL map has its script's path (§10 Roots with no shared place). Null for a fetched map,
+ * which has no place in the build.
+ */
+export interface PairedMap {
+    raw: unknown;
+    reading: LineReading;
+    base: string | null;
+}
+export type { LineReading };
+/** What discovery finds: the artifact graph, and what it could not follow (§13). */
+export interface Discovered {
+    /** Every artifact, in the order it was first found. */
+    artifacts: Artifact[];
+    limitations: LimitationRecord[];
+    /** HTML content that is counted, not analyzed (§19 HTML rules). */
+    html: HtmlCounters;
+    /** The build files the sweep found and did not analyze (§2 Sweep, §13 Counters), by path, sorted. */
+    swept: SweptFiles;
+    /** What became of each source-map directory's maps (§13 Attribution block), in the order they were declared. */
+    sourceMapDirectories: SourceMapDirectoryCounts[];
+    /**
+     * Each module request a script's code makes that resolves to a URL (§6 Module links): the realm and URL of the script
+     * it is in, the entry document that followed it, whose import maps resolved it, its specifier, and the URL it names.
+     * A sweep-only file's requests are recorded too, with no document, resolved against its URL with no import map: they
+     * are followed (§2 Sweep), except that an import of another swept file leaves it the sweep's.
+     */
+    imports: ModuleImport[];
+    /**
+     * The artifacts that module requests name and no other reference runs, by realm and URL: no script element, worker
+     * or other reference does, though a preload may name them. They are analyzed only as members of their importers' link
+     * groups (§19 Link groups).
+     */
+    importedOnly: {
+        realm: Realm;
+        url: string;
+    }[];
+    /**
+     * The entry documents whose references other than module requests name each artifact, by realm and URL, in the order
+     * of the entries: each runs it with its own import maps.
+     */
+    documents: {
+        realm: Realm;
+        url: string;
+        documents: string[];
+    }[];
+    /**
+     * Each remote chunk a loader's folded chunk URL names (§2, §19 References only the resolver can see): the realm, the
+     * loader (its URL, and the URL it was fetched at when that isn't its URL) and the chunk's URL. A remote chunk joins
+     * the link group of a loader that loads it, and no other group, through the registry it pushes into (§6 idiom 6).
+     */
+    remoteChunks: {
+        realm: Realm;
+        loader: {
+            url: string;
+            fetched?: string;
+        };
+        chunk: string;
+    }[];
+}
+/** A module request that resolves to a URL (`Discovered.imports`). */
+export interface ModuleImport {
+    realm: Realm;
+    document: string | null;
+    /** The importing script's URL, and the URL it was fetched at when that isn't its URL (§11). */
+    from: {
+        url: string;
+        fetched?: string;
+    };
+    specifier: string;
+    /** The module's URL, and the URL it is fetched at when that isn't its URL (§11). */
+    to: {
+        url: string;
+        fetched?: string;
+    };
+}
+/**
+ * Finds the classic and module scripts each entry document runs, following the HTML rules of §19: its inline scripts,
+ * and the files its `script[src]` elements name, resolved against the document's base URL. A file that only a
+ * `<link rel=preload as=script>` or a `<link rel=modulepreload>` names joins the graph too, and does not run. It
+ * counts the HTML content it does not analyze: classic `nomodule` scripts, inline event handlers and `javascript:`
+ * URLs.
+ *
+ * Then it follows the module requests of every script it found, and of every module those name, in turn (§2): static
+ * imports, re-exports and dynamic imports with a literal specifier, resolved through the document's import maps in
+ * browser order (§2 Import maps). An inline module script's requests resolve through the maps before it in tree order,
+ * and every other request through all of them. Each names a module, which runs when its importer does. A request with
+ * an import attribute names no JavaScript module, and is not followed. A static import or re-export with an attribute a
+ * browser doesn't support fails every module graph that contains it (§2 Import attributes): each root of such a graph
+ * (a module script element, a dynamic import or a module worker) gives nothing, and nothing is followed through it
+ * from a hint. A dynamic import whose specifier is not a literal, or whose options have a part that can't be read and
+ * could decide whether it names a JavaScript module, and a specifier that doesn't resolve, such as a bare specifier no
+ * import map maps, give an `unresolved-reference` record.
+ *
+ * It follows the worker scripts they load with a literal URL too (§2, §19 Discovery), where the realm has the function
+ * that loads them: a `new Worker` is a dedicated worker, a `new SharedWorker` a shared worker, and a
+ * `navigator.serviceWorker.register` a service worker, each in its own realm, and an `importScripts` loads a classic
+ * script into its own worker. A service worker whose script falls outside every URL mapping, like a `<link
+ * rel=modulepreload as=serviceworker>` outside every mapping, gives an `unresolved-reference` record instead. A
+ * dedicated or shared worker's script on another origin than its creator's is not followed, as a browser won't run it,
+ * and a `data:` worker's is code the page carries, as a `data:` script is.
+ *
+ * A file a `<link rel=preload as=script>` names that no running reference names, in any realm, is followed last, as the
+ * syntax of the preload's own bytes says, in URL order. Its realm is assumed to be `window` when nothing else names it,
+ * as it is for the modules it requests (§2 Files that don't run as referenced). One a running reference runs in another
+ * realm has no window artifact. One whose code has worker markers gives a `realm-uncertain` record, as a file only the
+ * sweep found does.
+ *
+ * A remote script is fetched with the integrity metadata its reference carries (§17 Integrity): a `script` or `link`
+ * element's `integrity` attribute, or, for a module with none, its URL's entry in the document's import maps. A
+ * fetched script's own references are fetched against the URL its bytes came from, after any redirects, though it
+ * keeps the URL it was requested at. They are keyed, as artifacts, by the URL resolved against the script's own URL as
+ * requested (its key URL), so a key doesn't change when a redirect target moves (§11 Remote URL normalization). One
+ * fetched URL reached under two key URLs is an artifact of each, sharing the one fetch, and one key URL reached through
+ * two fetched URLs is an artifact of each too, both analyzed, told apart by `retrieval.requestedUrl`.
+ *
+ * A `data:` URL is code the page carries (§2 Other script URLs): its script is an `inline` artifact of the referencing
+ * realm, loaded as the reference loads it, unless a browser would refuse to run it, when it gives nothing, as a `data:`
+ * service worker always does. A script URL with any other scheme but `http:` and `https:` (`javascript:`, `blob:`,
+ * `file:`, `about:`, …) gives nothing wherever it appears.
+ *
+ * An entry document or a local script that can't be read gives an `unreadable` record, and a remote script that isn't
+ * read gives an `offline-skipped`, `remote-refused`, `fetch-failed` or `sri-mismatch` one (§17 Outcomes); the script
+ * is still an artifact. Each URL, and each inline script, is an artifact of its own, whatever bytes it shares with
+ * another (§2 Artifacts): the scan analyzes identical bytes once, and gives each copy its findings.
+ *
+ * Last, it pairs each artifact with the first source map that verifies against it (§2 Source maps): one a fetched
+ * artifact's `SourceMap` header names, then one its annotation names, then its sidecar in the build directory, then a
+ * map there with its `debugId`. A map that fails verification is `stale`, and counted. A missing or broken map gives no
+ * record: it is counted in the attribution block (§13), and never changes completeness. A map the annotation of a
+ * local-build or inline artifact names, or its sidecar, that exists but can't be read gives an `unreadable` record. A
+ * remote artifact's maps are fetched only here, after every script: each one the safety floor refuses, whose fetch
+ * fails, or that is a build file that exists but can't be read, is only counted (§17, `unreadMaps`).
+ * Then each source-map directory is searched, one at a time, in the order they were declared (`pairInDirectory`): one
+ * that can't be listed gives an `unreadable` record, and one none of whose maps verifies against an artifact a
+ * `source-maps-unpaired` record.
+ */
+export declare function discover(input: {
+    entries: readonly Entry[];
+    store: SourceStore;
+    /**
+     * The source-map directories (§2 Source maps), by their names as declared, in the order they are searched. The store
+     * reads them.
+     */
+    sourceMaps?: readonly string[];
+    /** The catalog, read for the names of event handlers and for the globals each realm has. */
+    catalog: SerializedCatalog;
+    /**
+     * The references only the resolver can see that earlier rounds found (§19 References only the resolver can see), in
+     * URL order. Discovery follows them as it follows its own, so a round's artifact graph depends only on the set.
+     */
+    references?: readonly ResolvedReference[];
+}): Promise<Discovered>;
+/**
+ * A reference only the resolver can see (§19 References only the resolver can see), as a round found it: the realm of
+ * the link group it was found in, the artifact whose code holds it (its URL, and the URL it was fetched at when that
+ * isn't its URL), its kind, and its URL as the code builds it, unresolved.
+ * - A `chunk` reference's `load` is how the load site loads it: a created script element's `src`, `importScripts` or
+ *   `import()`. A `partial` record's URL is only the constant prefix of an alternative that doesn't fold ('' for none),
+ *   which decides whether that chunk URL is local (§2).
+ * - An `injected` reference is a script element's `src` (§2), with the element's `type` as it folds (absent when
+ *   none is set, null when it doesn't fold) and its folded `integrity`, if any.
+ * - A `worker` reference is a worker URL that isn't a literal, located at the call's URL argument.
+ * A `partial` injected or worker record stands for one alternative that doesn't fold, located at `alternative`.
+ */
+export interface ResolvedReference {
+    realm: Realm;
+    from: {
+        url: string;
+        fetched?: string;
+    };
+    kind: 'chunk' | 'injected' | 'worker';
+    url: string;
+    load?: 'element' | 'import-scripts' | 'import';
+    partial?: true;
+    alternative?: GeneratedLocation;
+    /** For a `worker` site: its URL folds to no value, as when it throws (`new URL("x.js")`), so it loads nothing. */
+    none?: true;
+    type?: string | null;
+    /** The integrity value code sets on the chunk's script element, when it folds (§17 Integrity). */
+    integrity?: string;
+    /** For an `injected` reference: the constants its element's `integrity` may be, when each write folds. */
+    integrityAlternatives?: string[];
+    /** For an `injected` reference: its element's `noModule` is set (`yes`), or may be (`maybe`). */
+    noModule?: 'yes' | 'maybe';
+    location: GeneratedLocation;
+}