monkeypatchlist 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,107 @@
+import { type BaselineCommand, type Entry, type FailOnState, type Mapping, type Mode, type SurfaceScope } from './lib/types.ts';
+export { differingScanConfigFields } from './lib/scan-config-id.ts';
+export { failOnStates, UsageError, type Entry, type FailOnState, type Mapping, type Mode, type SurfaceScope, } from './lib/types.ts';
+/**
+ * The default baseline file (§16): the one `baseline init` writes and `baseline update` rewrites (`--out`), and the one
+ * a scan compares with under `--fail-on` (`--baseline`). It is relative to the working directory.
+ */
+export declare const defaultBaselineFile = "monkeypatchlist.baseline.json";
+/**
+ * A validated scan configuration: `scan`'s, which names the baseline it compares with, or a baseline command's, which
+ * names the baseline file it writes. `baseline update` also compares with that file before it rewrites it.
+ */
+export type ScanConfig = CommonConfig & ({
+    command: 'scan';
+    /**
+     * `--baseline`: the baseline to compare with, relative to the working directory, or null for none (§11): a
+     * baseline file, or a full JSON scan report (ADR 0020). Under `--fail-on` it defaults to `monkeypatchlist.baseline.json`.
+     */
+    baseline: string | null;
+    /**
+     * `--previous`: a previous JSON scan report, relative to the working directory, or null for none (§16). Its
+     * values feed the reachability and install-context notes, overriding a report baseline's; it needs a baseline.
+     */
+    previous: string | null;
+    /** `--fail-on`: the baseline states that fail the gate, in the order of `failOnStates`; none runs no gate. */
+    failOn: FailOnState[];
+} | {
+    command: BaselineCommand;
+    /** `--out`: the baseline file it writes, relative to the working directory. `baseline update` rewrites it. */
+    out: string;
+    /**
+     * `--allow-downgrade` (§4 Version skew, §16): `baseline init` replaces, and `baseline update` rewrites, a
+     * baseline written by a newer catalog or monkeypatchlist version.
+     */
+    allowDowngrade: boolean;
+});
+interface CommonConfig {
+    /** The build directory, as given. */
+    buildDir: string;
+    /** The application name (§16): the report header and the terminal title. It is not identity. */
+    name: string;
+    entries: Entry[];
+    mappings: Mapping[];
+    /**
+     * `--source-maps`: the source-map directories (§2 Source maps), relative to the working directory, in the order they
+     * are searched: the flags' order, or the config array's when no flag is given. They are not in the scan-config id
+     * (§16).
+     */
+    sourceMaps: string[];
+    /** The surface the scan reports, baselines and gates (§12). The findings module applies it. */
+    surface: SurfaceScope;
+    /** `--mode`: the remote retrieval mode (§17). Only `resolve` fetches remote references. */
+    mode: Mode;
+    /**
+     * `--lockfile` and `lockfile.importer` (§10 Introducing dependencies): the lockfile, relative to the working
+     * directory, and the workspace of the scanned application in it, or null when the first-party source paths pick it.
+     * Null when no lockfile is given. It isn't in the scan-config id (§16).
+     */
+    lockfile: {
+        path: string;
+        importer: string | null;
+    } | null;
+    /** `--json`: a path to write the JSON report to, `-` for stdout instead of the terminal report, or null. */
+    json: string | null;
+    /** The scan-config id (§16): what the baseline records, to be compared only with scans of the same configuration. */
+    scanConfigId: string;
+    /**
+     * `--allow-incomplete` (§13, §16): an `incomplete` scan under `--fail-on` warns instead of exiting 3, and `baseline
+     * init` and `baseline update` write one. After a fired crash guard, `baseline init` still refuses, and `baseline
+     * update` leaves the baseline unchanged (§13). On `scan`, it also makes an `incomplete` report readable as the
+     * baseline, read as `baseline update --allow-incomplete` would write it (§11).
+     */
+    allowIncomplete: boolean;
+    /** `--verbose` (§16): the terminal report cards existing findings too. Only `scan` takes the flag. */
+    verbose: boolean;
+    /** `--list-ineffective` (§16): the terminal report lists the ineffective writes. Only `scan` takes the flag. */
+    listIneffective: boolean;
+    /**
+     * False under `--no-color` (§16). The terminal report is colored only when this is true, stdout is a TTY and
+     * `NO_COLOR` is unset or empty (§15 Formatting); the CLI judges the last two.
+     */
+    color: boolean;
+}
+export declare const usage: string;
+/**
+ * The scan configuration for `monkeypatchlist <argv…>` run in `cwd`, or a `UsageError`. It reads the config file `--config`
+ * names, or `monkeypatchlist.config.json` in `cwd` if there is one, and the flags override it field by field (§16). Its paths
+ * are relative to `cwd`, except entry files and mapping directories, which are relative to the build directory.
+ */
+export declare function loadConfig(argv: readonly string[], options: {
+    cwd: string;
+}): ScanConfig;
+/** What `monkeypatchlist explain` reads (§16 Commands): the finding asked for, and the saved JSON report it is found in. */
+export interface ExplainConfig {
+    command: 'explain';
+    /** The fingerprint or target, as given. */
+    query: string;
+    /** The saved JSON report, relative to the working directory: `--report`, or the config file's `report`. */
+    report: string;
+}
+/**
+ * The configuration for `monkeypatchlist explain <argv…>` run in `cwd` (the arguments after `explain`), or a `UsageError`.
+ * Only `report` is read from the config file; explain reads no build directory, so the scan settings don't apply.
+ */
+export declare function loadExplainConfig(argv: readonly string[], options: {
+    cwd: string;
+}): ExplainConfig;

package/dist/packages/config/index.js

@@ -0,0 +1,95 @@
+// Config (§19, module 1): CLI flags and `monkeypatchlist.config.json` into a validated scan configuration. It knows nothing
+// about artifacts.
+import { basename, resolve } from 'node:path';
+import { parseCommandLine, parseExplainCommandLine } from "./lib/command-line.js";
+import { readConfigFile } from "./lib/config-file.js";
+import { scanConfigId } from "./lib/scan-config-id.js";
+import { failOnStates, UsageError, } from "./lib/types.js";
+export { differingScanConfigFields } from "./lib/scan-config-id.js";
+export { failOnStates, UsageError, } from "./lib/types.js";
+/**
+ * The default baseline file (§16): the one `baseline init` writes and `baseline update` rewrites (`--out`), and the one
+ * a scan compares with under `--fail-on` (`--baseline`). It is relative to the working directory.
+ */
+export const defaultBaselineFile = 'monkeypatchlist.baseline.json';
+const flags = '[--config <path>] [--map <urlPrefix>=<dir>]... [--entry <file>[@<url>]]... [--source-maps <dir>]... ' +
+    '[--surface protected|all] [--mode offline|resolve] [--lockfile <path>] [--json <path|->] [--no-color]';
+export const usage = [
+    `usage: monkeypatchlist scan <buildDir> ${flags} [--baseline <path>] [--previous <report.json>] [--fail-on added,changed] [--allow-incomplete] [--verbose] [--list-ineffective]`,
+    `       monkeypatchlist baseline init <buildDir> ${flags} [--out <path>] [--allow-incomplete] [--allow-downgrade]`,
+    `       monkeypatchlist baseline update <buildDir> ${flags} [--out <path>] [--allow-incomplete] [--allow-downgrade]`,
+    '       monkeypatchlist explain <fingerprint|target> --report <file> [--config <path>] [--no-color]',
+].join('\n');
+/**
+ * The scan configuration for `monkeypatchlist <argv…>` run in `cwd`, or a `UsageError`. It reads the config file `--config`
+ * names, or `monkeypatchlist.config.json` in `cwd` if there is one, and the flags override it field by field (§16). Its paths
+ * are relative to `cwd`, except entry files and mapping directories, which are relative to the build directory.
+ */
+export function loadConfig(argv, options) {
+    const { cwd } = options;
+    const commandLine = parseCommandLine(argv);
+    const file = readConfigFile(commandLine.config, cwd) ?? {};
+    const settings = { ...file, ...commandLine.settings };
+    // `--lockfile` sets only the path: the file's importer stays (§16 Flags).
+    const lockfile = { ...file.lockfile, ...commandLine.settings.lockfile };
+    const { mappings = [] } = settings;
+    const [mapping] = mappings;
+    if (mapping === undefined) {
+        throw new UsageError('no URL mapping given: pass --map <urlPrefix>=<dir>, or give mappings in the config file');
+    }
+    // An entry document's URL defaults to the first mapping's URL (§16).
+    const entries = (settings.entries ?? [{ file: 'index.html' }]).map(({ file, url }) => ({
+        file,
+        url: url ?? mapping.url,
+    }));
+    entries.forEach(({ file, url }, i) => {
+        if (entries.findIndex((other) => other.file === file && other.url === url) < i) {
+            throw new UsageError(`entry document '${file}' at ${url} is given twice`);
+        }
+    });
+    // The application name defaults to the build directory's basename (§16). A filesystem root has none.
+    const buildDir = resolve(cwd, commandLine.buildDir);
+    // The surface defaults to protected (§12).
+    const surface = settings.surface ?? 'protected';
+    const common = {
+        buildDir: commandLine.buildDir,
+        name: settings.name ?? (basename(buildDir) || buildDir),
+        entries,
+        mappings,
+        sourceMaps: settings.sourceMaps ?? [],
+        surface,
+        // The mode defaults to offline (§17): no command touches the network unless `--mode resolve` is given.
+        mode: settings.mode ?? 'offline',
+        lockfile: lockfile.path === undefined ? null : { path: lockfile.path, importer: lockfile.importer ?? null },
+        json: settings.json ?? null,
+        scanConfigId: scanConfigId({ entries, mappings, surface }),
+        allowIncomplete: settings.allowIncomplete ?? false,
+        // Only `scan` reads `verbose` and `listIneffective` (§16), from its flags or the file.
+        verbose: commandLine.command === 'scan' && (settings.verbose ?? false),
+        listIneffective: commandLine.command === 'scan' && (settings.listIneffective ?? false),
+        color: !(settings.noColor ?? false),
+    };
+    if (commandLine.command !== 'scan') {
+        const { command } = commandLine;
+        const allowDowngrade = settings.allowDowngrade ?? false;
+        return { command, ...common, out: settings.out ?? defaultBaselineFile, allowDowngrade };
+    }
+    const failOn = failOnStates.filter((state) => settings.failOn?.includes(state));
+    // Under `--fail-on`, the baseline defaults to `monkeypatchlist.baseline.json` (§16): a gate never runs without one.
+    const baseline = settings.baseline ?? (failOn.length > 0 ? defaultBaselineFile : null);
+    return { command: 'scan', ...common, baseline, previous: settings.previous ?? null, failOn };
+}
+/**
+ * The configuration for `monkeypatchlist explain <argv…>` run in `cwd` (the arguments after `explain`), or a `UsageError`.
+ * Only `report` is read from the config file; explain reads no build directory, so the scan settings don't apply.
+ */
+export function loadExplainConfig(argv, options) {
+    const commandLine = parseExplainCommandLine(argv);
+    // The config file is read and validated as for every command; the flag overrides its key (§16).
+    const file = readConfigFile(commandLine.config, options.cwd);
+    const report = commandLine.report ?? file?.report;
+    if (report === undefined) {
+        throw new UsageError('explain needs the saved JSON report to read: pass --report <file>');
+    }
+    return { command: 'explain', query: commandLine.query, report };
+}

package/dist/packages/config/lib/command-line.d.ts

@@ -0,0 +1,23 @@
+import { type Command, type Settings } from './types.ts';
+export interface CommandLine {
+    command: Command;
+    /** The build directory, as given. */
+    buildDir: string;
+    /** `--config <path>`, as given. */
+    config: string | undefined;
+    /** The settings the flags give. */
+    settings: Settings;
+}
+/** Parses `monkeypatchlist <argv…>`, or throws a `UsageError`. */
+export declare function parseCommandLine(argv: readonly string[]): CommandLine;
+/** `monkeypatchlist explain <fingerprint|target> [--report <file>] [--config <path>]`, as given. */
+export interface ExplainCommandLine {
+    /** The fingerprint or target to explain. */
+    query: string;
+    /** `--config <path>`, as given. */
+    config: string | undefined;
+    /** `--report <file>`, as given, relative to the working directory. */
+    report: string | undefined;
+}
+/** Parses the arguments after `monkeypatchlist explain`, or throws a `UsageError`. */
+export declare function parseExplainCommandLine(argv: readonly string[]): ExplainCommandLine;

package/dist/packages/config/lib/command-line.js

@@ -0,0 +1,239 @@
+// The command line (§16 Commands, Flags).
+import { parseArgs } from 'node:util';
+import { failOnStates, UsageError, } from "./types.js";
+import { httpUrl } from "./urls.js";
+/** Parses `monkeypatchlist <argv…>`, or throws a `UsageError`. */
+export function parseCommandLine(argv) {
+    const { command, rest } = parseCommand(argv);
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: [...rest],
+            allowPositionals: true,
+            strict: true,
+            options: {
+                config: { type: 'string', multiple: true },
+                entry: { type: 'string', multiple: true },
+                map: { type: 'string', multiple: true },
+                'source-maps': { type: 'string', multiple: true },
+                surface: { type: 'string', multiple: true },
+                mode: { type: 'string', multiple: true },
+                lockfile: { type: 'string', multiple: true },
+                json: { type: 'string', multiple: true },
+                out: { type: 'string', multiple: true },
+                baseline: { type: 'string', multiple: true },
+                previous: { type: 'string', multiple: true },
+                'fail-on': { type: 'string', multiple: true },
+                'allow-incomplete': { type: 'boolean' },
+                'allow-downgrade': { type: 'boolean' },
+                verbose: { type: 'boolean' },
+                'list-ineffective': { type: 'boolean' },
+                'no-color': { type: 'boolean' },
+            },
+        });
+    }
+    catch (error) {
+        throw new UsageError(error.message);
+    }
+    const { positionals, values } = parsed;
+    if (positionals.length !== 1) {
+        throw new UsageError(positionals.length === 0 ? 'no build directory given' : `unexpected argument '${positionals[1]}'`);
+    }
+    const settings = {};
+    if (values.map !== undefined)
+        settings.mappings = mappings(values.map.map(parseMapping));
+    if (values.entry !== undefined)
+        settings.entries = values.entry.map(parseEntry);
+    if (values['source-maps'] !== undefined)
+        settings.sourceMaps = sourceMaps(values['source-maps']);
+    const surface = one('--surface', values.surface);
+    if (surface !== undefined)
+        settings.surface = parseSurface(surface);
+    const mode = one('--mode', values.mode);
+    if (mode !== undefined)
+        settings.mode = parseMode(mode);
+    // `--lockfile` sets `lockfile.path`; the importer is only a config key (§16 Flags).
+    const lockfile = one('--lockfile', values.lockfile);
+    if (lockfile === '')
+        throw new UsageError('--lockfile needs a path');
+    if (lockfile !== undefined)
+        settings.lockfile = { path: lockfile };
+    const json = one('--json', values.json);
+    if (json !== undefined)
+        settings.json = json;
+    // `--out` names the file a baseline command writes.
+    if (command === 'scan' && values.out !== undefined) {
+        throw new UsageError("--out is a baseline flag: scan doesn't write a baseline");
+    }
+    const out = one('--out', values.out);
+    if (out !== undefined)
+        settings.out = out;
+    // `--baseline` names the baseline a scan compares with, `--previous` the previous report its notes compare with, and
+    // `--fail-on` gates on the baseline.
+    for (const flag of ['baseline', 'previous', 'fail-on']) {
+        if (command !== 'scan' && values[flag] !== undefined) {
+            throw new UsageError(`--${flag} is a scan flag: ${command} accepts the whole finding set`);
+        }
+    }
+    const baseline = one('--baseline', values.baseline);
+    if (baseline !== undefined)
+        settings.baseline = baseline;
+    const previous = one('--previous', values.previous);
+    if (previous !== undefined)
+        settings.previous = previous;
+    const failOn = one('--fail-on', values['fail-on']);
+    if (failOn !== undefined)
+        settings.failOn = parseFailOn(failOn);
+    // `--allow-incomplete` downgrades exit code 3 to a warning, and lets `baseline init` and `baseline update` write
+    // (§16), except after a fired crash guard (§13). On `scan` it also lets an incomplete report be the baseline (§11).
+    if (values['allow-incomplete'] === true)
+        settings.allowIncomplete = true;
+    // `--allow-downgrade` lets `baseline init` and `baseline update` replace a baseline written by a newer version (§4
+    // Version skew, §16).
+    if (values['allow-downgrade'] === true) {
+        if (command === 'scan')
+            throw new UsageError("--allow-downgrade is a baseline flag: scan writes no baseline");
+        settings.allowDowngrade = true;
+    }
+    // `--verbose` and `--list-ineffective` are scan flags (§16): what a baseline command accepts is the whole finding set.
+    for (const flag of ['verbose', 'list-ineffective']) {
+        if (command !== 'scan' && values[flag] === true)
+            throw new UsageError(`--${flag} is a scan flag`);
+    }
+    if (values.verbose === true)
+        settings.verbose = true;
+    if (values['list-ineffective'] === true)
+        settings.listIneffective = true;
+    if (values['no-color'] === true)
+        settings.noColor = true;
+    return { command, buildDir: positionals[0], config: one('--config', values.config), settings };
+}
+/** The command (`scan`, `baseline init` or `baseline update`), and the arguments after it. */
+function parseCommand(argv) {
+    const [command, ...rest] = argv;
+    if (command === 'scan')
+        return { command, rest };
+    if (command === 'baseline') {
+        const [subcommand, ...after] = rest;
+        if (subcommand === 'init' || subcommand === 'update')
+            return { command: `baseline ${subcommand}`, rest: after };
+        throw new UsageError(subcommand === undefined ? 'no baseline command given' : `unknown command 'baseline ${subcommand}'`);
+    }
+    throw new UsageError(command === undefined ? 'no command given' : `unknown command '${command}'`);
+}
+/** The one value of a flag that may be given once. */
+function one(flag, values) {
+    if (values !== undefined && values.length > 1)
+        throw new UsageError(`${flag} can be given only once`);
+    return values?.[0];
+}
+/** Parses `added,changed`: a comma-separated list of the states the gate fails on, each named once. */
+function parseFailOn(value) {
+    const states = [];
+    for (const state of value.split(',')) {
+        if (state === 'removed' || state === 'unconfirmed') {
+            throw new UsageError(`--fail-on can't gate on ${state}: only added and changed can`);
+        }
+        if (!isFailOnState(state)) {
+            throw new UsageError(`--fail-on takes added and changed, separated by commas, got '${value}'`);
+        }
+        if (states.includes(state))
+            throw new UsageError(`--fail-on names ${state} twice`);
+        states.push(state);
+    }
+    return states;
+}
+function isFailOnState(state) {
+    return failOnStates.includes(state);
+}
+/** Parses `protected|all`. */
+function parseSurface(value) {
+    if (value === 'protected' || value === 'all')
+        return value;
+    throw new UsageError(`--surface must be protected or all, got '${value}'`);
+}
+/** Parses `offline|resolve`. */
+function parseMode(value) {
+    if (value === 'offline' || value === 'resolve')
+        return value;
+    throw new UsageError(`--mode must be offline or resolve, got '${value}'`);
+}
+/**
+ * Parses `<file>[@<url>]`. The URL starts after the first `@` that begins an absolute URL, so a file name may hold an
+ * `@` of its own. It must be an `http:` or `https:` URL.
+ */
+function parseEntry(value) {
+    for (let at = value.indexOf('@'); at !== -1; at = value.indexOf('@', at + 1)) {
+        if (URL.parse(value.slice(at + 1)) === null)
+            continue;
+        const file = value.slice(0, at);
+        if (file === '')
+            throw new UsageError(`--entry needs a file before @<url>, got '${value}'`);
+        const url = httpUrl(value.slice(at + 1));
+        if ('problem' in url)
+            throw new UsageError(`--entry URL ${url.problem}`);
+        return { file, url: url.href };
+    }
+    if (value === '')
+        throw new UsageError('--entry needs a file');
+    return { file: value };
+}
+/** The `--map` flags, with no URL prefix mapped twice: under longest-prefix-wins, the second would never be used. */
+function mappings(list) {
+    list.forEach(({ url }, i) => {
+        if (list.findIndex((other) => other.url === url) < i)
+            throw new UsageError(`--map maps '${url}' twice`);
+    });
+    return list;
+}
+/**
+ * The `--source-maps` flags, in the order given, which is the order the directories are searched in (§2 Source maps).
+ * A directory given twice would only be searched again.
+ */
+function sourceMaps(list) {
+    list.forEach((dir, i) => {
+        if (dir === '')
+            throw new UsageError('--source-maps needs a directory');
+        if (list.indexOf(dir) < i)
+            throw new UsageError(`--source-maps names '${dir}' twice`);
+    });
+    return list;
+}
+/** Parses `<urlPrefix>=<dir>`. The prefix is an absolute `http:` or `https:` URL. */
+function parseMapping(value) {
+    const split = value.indexOf('=');
+    if (split <= 0 || split === value.length - 1)
+        throw new UsageError(`--map needs <urlPrefix>=<dir>, got '${value}'`);
+    const url = httpUrl(value.slice(0, split));
+    if ('problem' in url)
+        throw new UsageError(`--map URL prefix ${url.problem}`);
+    return { url: url.href, dir: value.slice(split + 1) };
+}
+/** Parses the arguments after `monkeypatchlist explain`, or throws a `UsageError`. */
+export function parseExplainCommandLine(argv) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: [...argv],
+            allowPositionals: true,
+            strict: true,
+            options: {
+                config: { type: 'string', multiple: true },
+                report: { type: 'string', multiple: true },
+                // Every command takes `--no-color` (§16); explain's output has no color to turn off.
+                'no-color': { type: 'boolean' },
+            },
+        });
+    }
+    catch (error) {
+        throw new UsageError(error.message);
+    }
+    const { positionals, values } = parsed;
+    if (positionals.length !== 1) {
+        throw new UsageError(positionals.length === 0 ? 'explain needs a fingerprint or target' : `unexpected argument '${positionals[1]}'`);
+    }
+    const report = one('--report', values.report);
+    if (report === '')
+        throw new UsageError('--report needs a file');
+    return { query: positionals[0], config: one('--config', values.config), report };
+}

package/dist/packages/config/lib/config-file.d.ts

@@ -0,0 +1,11 @@
+import { type Settings } from './types.ts';
+/** The file used when `--config` is not given, if it exists in the working directory. */
+export declare const defaultConfigFile = "monkeypatchlist.config.json";
+/**
+ * Reads the config file: `path` relative to `cwd`, or `monkeypatchlist.config.json` in `cwd` if it exists. Returns its
+ * settings, or undefined when there is no file. Throws a `UsageError` naming the failing path when the file is invalid.
+ *
+ * The file's own paths are relative to its directory, and come back relative to `cwd`, as a flag's are. Entry files and
+ * mapping directories stay relative to the build directory.
+ */
+export declare function readConfigFile(path: string | undefined, cwd: string): Settings | undefined;

package/dist/packages/config/lib/config-file.js

@@ -0,0 +1,119 @@
+// The configuration file (§16): `monkeypatchlist.config.json`, or the file `--config` names. It is JSON, only ever parsed.
+import { readFileSync } from 'node:fs';
+import { dirname, extname, isAbsolute, join, resolve } from 'node:path';
+import { schemaProblems } from "./schema.js";
+import { UsageError } from "./types.js";
+import { httpUrl } from "./urls.js";
+/** The file used when `--config` is not given, if it exists in the working directory. */
+export const defaultConfigFile = 'monkeypatchlist.config.json';
+/**
+ * Reads the config file: `path` relative to `cwd`, or `monkeypatchlist.config.json` in `cwd` if it exists. Returns its
+ * settings, or undefined when there is no file. Throws a `UsageError` naming the failing path when the file is invalid.
+ *
+ * The file's own paths are relative to its directory, and come back relative to `cwd`, as a flag's are. Entry files and
+ * mapping directories stay relative to the build directory.
+ */
+export function readConfigFile(path, cwd) {
+    const file = path ?? defaultConfigFile;
+    // A CI gate for platform integrity must not execute its own configuration, so a JS or TS config file is never
+    // loaded. Only a `.json` file is read, and it is only ever parsed.
+    if (extname(file).toLowerCase() !== '.json') {
+        throw new UsageError(`config file '${file}' is not a .json file: monkeypatchlist never loads JS or TS configuration`);
+    }
+    let text;
+    try {
+        text = readFileSync(resolve(cwd, file), 'utf8');
+    }
+    catch (error) {
+        const code = error.code;
+        // Only a missing default file means "no config file". Any other failure is a config error (exit 2), not exit 4.
+        if (path === undefined && code === 'ENOENT')
+            return undefined;
+        throw new UsageError(`config file '${file}' can't be read: ${code ?? error}`);
+    }
+    let value;
+    try {
+        // A leading UTF-8 byte order mark is dropped.
+        value = JSON.parse(text.startsWith('\uFEFF') ? text.slice(1) : text);
+    }
+    catch (error) {
+        throw new UsageError(`config file '${file}' is not valid JSON: ${error.message}`);
+    }
+    const problems = schemaProblems(value);
+    if (problems.length > 0)
+        throw invalid(file, problems);
+    const config = value;
+    // URLs are checked and canonicalized as the flags' are.
+    const canonical = (url, pointer) => {
+        const parsed = httpUrl(url);
+        if ('problem' in parsed)
+            throw invalid(file, [`${pointer}: ${parsed.problem}`]);
+        return parsed.href;
+    };
+    const fromFile = (relative) => (isAbsolute(relative) ? relative : join(dirname(file), relative));
+    const settings = {};
+    if (config.name !== undefined)
+        settings.name = config.name;
+    if (config.entries !== undefined) {
+        settings.entries = config.entries.map((entry, i) => entry.url === undefined ? { file: entry.file } : { file: entry.file, url: canonical(entry.url, `/entries/${i}/url`) });
+    }
+    if (config.mappings !== undefined) {
+        const mappings = config.mappings.map(({ url, dir }, i) => ({ url: canonical(url, `/mappings/${i}/url`), dir }));
+        // The longest matching prefix wins, so two mappings for one prefix would leave one unused.
+        mappings.forEach(({ url }, i) => {
+            const first = mappings.findIndex((other) => other.url === url);
+            if (first < i)
+                throw invalid(file, [`/mappings/${i}/url: '${url}' is already mapped by /mappings/${first}`]);
+        });
+        settings.mappings = mappings;
+    }
+    if (config.sourceMaps !== undefined) {
+        const sourceMaps = config.sourceMaps.map(fromFile);
+        // Two entries that name one directory relative to the file (`maps`, `./maps`) would only search it again, as a
+        // flag given twice would.
+        sourceMaps.forEach((dir, i) => {
+            const first = sourceMaps.indexOf(dir);
+            if (first < i)
+                throw invalid(file, [`/sourceMaps/${i}: '${dir}' is already declared by /sourceMaps/${first}`]);
+        });
+        settings.sourceMaps = sourceMaps;
+    }
+    if (config.surface !== undefined)
+        settings.surface = config.surface;
+    if (config.mode !== undefined)
+        settings.mode = config.mode;
+    if (config.lockfile !== undefined) {
+        // The lockfile's path is relative to the file, as every path in it is; the importer is a workspace of the lockfile.
+        const { path, importer } = config.lockfile;
+        settings.lockfile = {
+            ...(path === undefined ? {} : { path: fromFile(path) }),
+            ...(importer === undefined ? {} : { importer }),
+        };
+    }
+    if (config.json !== undefined)
+        settings.json = config.json === '-' ? '-' : fromFile(config.json);
+    if (config.out !== undefined)
+        settings.out = fromFile(config.out);
+    if (config.baseline !== undefined)
+        settings.baseline = fromFile(config.baseline);
+    if (config.previous !== undefined)
+        settings.previous = fromFile(config.previous);
+    if (config.failOn !== undefined)
+        settings.failOn = config.failOn;
+    if (config.allowIncomplete !== undefined)
+        settings.allowIncomplete = config.allowIncomplete;
+    if (config.allowDowngrade !== undefined)
+        settings.allowDowngrade = config.allowDowngrade;
+    if (config.report !== undefined)
+        settings.report = fromFile(config.report);
+    if (config.verbose !== undefined)
+        settings.verbose = config.verbose;
+    if (config.listIneffective !== undefined)
+        settings.listIneffective = config.listIneffective;
+    if (config.noColor !== undefined)
+        settings.noColor = config.noColor;
+    return settings;
+}
+function invalid(file, problems) {
+    return new UsageError(`config file '${file}' is invalid:\n${problems.map((problem) => `  ${problem}`).join('\n')}`);
+}

package/dist/packages/config/lib/scan-config-id.d.ts

@@ -0,0 +1,28 @@
+import type { Entry, Mapping, SurfaceScope } from './types.ts';
+/**
+ * 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 declare const scanConfigFields: readonly ["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 declare function scanConfigId(config: {
+    entries: readonly Entry[];
+    mappings: readonly Mapping[];
+    surface: SurfaceScope;
+}): string;
+/**
+ * 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 declare function differingScanConfigFields(a: string, b: string): (typeof scanConfigFields)[number][];