monkeypatchlist 0.0.0-stage → 0.1.0

package/dist/packages/attribution/lib/yarn.js

@@ -0,0 +1,227 @@
+// `yarn.lock` (§10 Introducing dependencies): Yarn v1, and Berry at every `__metadata.version`. It resolves each
+// descriptor (`name@range`) to a package, but records neither the importer's direct dependencies nor the dev/prod
+// split, so those come from the `package.json` manifests beside it: its own directory's, and the workspaces'
+// (v1 through its `workspaces` globs, Berry through its workspace entries). A missing or unreadable one leaves the
+// importer unresolved. It isn't keyed by install path, so it gives no version (§10 Version), and what it derives is
+// capped at `medium`. Pure.
+import { graph, isRecord, normalizeFolder, placeByName, readManifest, } from "./lockfile-graph.js";
+import { readYaml } from "./yaml.js";
+const v1Header = /^# yarn lockfile v1\s*$/m;
+/** A descriptor's package name: `name@range`, a scope's `@` kept. */
+function nameOf(descriptor) {
+    const split = descriptor.indexOf('@', 1);
+    return split <= 0 ? null : descriptor.slice(0, split);
+}
+/** A dependency map's `[name, range]` pairs. */
+function ranges(value) {
+    if (!isRecord(value))
+        return [];
+    return Object.entries(value).flatMap(([name, range]) => (typeof range === 'string' ? [[name, range]] : []));
+}
+/** A key's descriptors: `a@1, "a@2"` lists several. */
+function descriptorsOf(key) {
+    return key
+        .split(/,\s*/)
+        .map((part) => part.trim().replace(/^"(.*)"$/, '$1'))
+        .filter((part) => part !== '');
+}
+/** The entries of a Yarn v1 lockfile, or null when it isn't one. */
+function readV1(text) {
+    const entries = [];
+    /** The open maps, by indent: the entry's fields, then a dependency block. */
+    let stack = [];
+    for (const raw of text.split(/\r?\n/)) {
+        if (raw.trim() === '' || raw.trimStart().startsWith('#'))
+            continue;
+        const indent = raw.length - raw.trimStart().length;
+        const line = raw.trim();
+        if (indent === 0) {
+            if (!line.endsWith(':'))
+                return null;
+            const fields = {};
+            entries.push({ descriptors: descriptorsOf(line.slice(0, -1)), fields });
+            stack = [{ indent: 0, map: fields }];
+            continue;
+        }
+        while (stack.length > 1 && stack.at(-1).indent >= indent)
+            stack.pop();
+        const holder = stack.at(-1);
+        if (holder === undefined)
+            return null;
+        const pair = /^("(?:[^"\\]|\\.)*"|[^\s"]+)(?::$|\s+(.*)$)/.exec(line);
+        if (pair === null)
+            return null;
+        const key = unquote(pair[1]);
+        if (pair[2] === undefined) {
+            const map = {};
+            Object.defineProperty(holder.map, key, { value: map, enumerable: true, writable: true, configurable: true });
+            stack.push({ indent, map });
+        }
+        else {
+            Object.defineProperty(holder.map, key, { value: unquote(pair[2]), enumerable: true, writable: true, configurable: true });
+        }
+    }
+    return entries;
+}
+function unquote(text) {
+    if (!text.startsWith('"'))
+        return text;
+    try {
+        const value = JSON.parse(text);
+        return typeof value === 'string' ? value : text;
+    }
+    catch {
+        return text.slice(1, -1);
+    }
+}
+/** The entries of a Yarn Berry lockfile and its `__metadata.version`, or null when it isn't one. */
+function readBerry(text) {
+    const doc = readYaml(text);
+    if (!isRecord(doc) || !isRecord(doc.__metadata) || typeof doc.__metadata.version !== 'string')
+        return null;
+    return Object.entries(doc).flatMap(([key, fields]) => key === '__metadata' || !isRecord(fields) ? [] : [{ descriptors: descriptorsOf(key), fields }]);
+}
+/** A Berry workspace entry's folder, from its resolution `name@workspace:<folder>`, or null for a package. */
+function workspaceFolder(fields) {
+    const resolution = typeof fields.resolution === 'string' ? fields.resolution : null;
+    const name = resolution === null ? null : nameOf(resolution);
+    if (resolution === null || name === null)
+        return null;
+    const reference = resolution.slice(name.length + 1);
+    return reference.startsWith('workspace:') ? normalizeFolder(reference.slice('workspace:'.length)) : null;
+}
+/** The manifests a `yarn.lock` needs besides its own directory's: Berry's workspace folders, or v1's globs. */
+export function yarnManifests(text, root) {
+    if (v1Header.test(text)) {
+        let value;
+        try {
+            value = root === null ? null : JSON.parse(root.startsWith('') ? root.slice(1) : root);
+        }
+        catch {
+            value = null;
+        }
+        const declared = isRecord(value) ? value.workspaces : undefined;
+        const list = Array.isArray(declared) ? declared : isRecord(declared) && Array.isArray(declared.packages) ? declared.packages : [];
+        return { folders: [], globs: list.filter((each) => typeof each === 'string') };
+    }
+    const entries = readBerry(text) ?? [];
+    const folders = entries.flatMap(({ fields }) => {
+        const folder = workspaceFolder(fields);
+        return folder === null || folder === '' ? [] : [folder];
+    });
+    return { folders, globs: [] };
+}
+export function readYarn(text, file, manifests) {
+    const v1 = v1Header.test(text);
+    const entries = v1 ? readV1(text) : readBerry(text);
+    if (entries === null)
+        return { unusable: `${file} is no Yarn lockfile: it has neither the v1 header nor a __metadata version` };
+    const byDescriptor = new Map();
+    const nodes = [];
+    /** Each workspace's folder, with its node, and its manifest when it could be read. */
+    const workspaces = new Map();
+    const unreadable = [];
+    const manifestAt = (folder) => {
+        const manifest = readManifest(manifests[folder]);
+        if (manifest === null)
+            unreadable.push(folder === '' ? 'package.json' : `${folder}/package.json`);
+        return manifest;
+    };
+    for (const { descriptors, fields } of entries) {
+        const folder = v1 ? null : workspaceFolder(fields);
+        const resolution = typeof fields.resolution === 'string' ? fields.resolution : null;
+        const name = (resolution === null || v1 ? null : nameOf(resolution)) ?? nameOf(descriptors[0] ?? '');
+        if (name === null)
+            continue;
+        const production = [...ranges(fields.dependencies), ...ranges(fields.optionalDependencies)];
+        const peers = Object.keys(isRecord(fields.peerDependencies) ? fields.peerDependencies : {});
+        let node;
+        if (folder !== null) {
+            // A Berry workspace entry merges dev dependencies in: its manifest splits them.
+            const manifest = manifestAt(folder);
+            node = { key: `workspace:${folder}`, name, version: manifest?.version ?? '', production: manifest?.production ?? production, peers: [], folder };
+            workspaces.set(folder, { node, name, manifest });
+        }
+        else {
+            const version = typeof fields.version === 'string' ? fields.version : '';
+            node = { key: resolution ?? descriptors.join(', '), name, version, production, peers };
+        }
+        nodes.push(node);
+        for (const descriptor of descriptors)
+            byDescriptor.set(descriptor, node);
+    }
+    if (v1) {
+        // v1 records no workspace: the manifests the root's `workspaces` globs match are them, the root's own included.
+        for (const folder of ['', ...Object.keys(manifests).filter((each) => each !== '')].sort()) {
+            const manifest = manifestAt(folder);
+            const node = {
+                key: `workspace:${folder}`,
+                name: manifest?.name ?? '',
+                version: manifest?.version ?? '',
+                production: manifest?.production ?? [],
+                peers: [],
+                folder,
+            };
+            workspaces.set(folder, { node, name: null, manifest });
+            if (folder !== '' && node.name !== '')
+                nodes.push(node);
+        }
+    }
+    else if (!workspaces.has('')) {
+        manifestAt('');
+    }
+    const byName = new Map();
+    // A named workspace is installed too (linked into `node_modules`), so code under its name there is no vendored code.
+    // The root is no package anything installs.
+    for (const node of nodes) {
+        if (node.folder === '' || node.name === '')
+            continue;
+        const list = byName.get(node.name);
+        if (list === undefined)
+            byName.set(node.name, [node]);
+        else
+            list.push(node);
+    }
+    const workspaceNamed = (name) => [...workspaces.values()].find(({ node }) => node.name === name)?.node;
+    /** What a dependency `name@range` resolves to: its descriptor's entry, or a workspace of that name. */
+    const target = (name, range) => {
+        const found = byDescriptor.get(`${name}@${range}`) ?? (v1 ? undefined : byDescriptor.get(`${name}@npm:${range}`));
+        if (found !== undefined)
+            return [found];
+        const workspace = v1 || range.startsWith('workspace:') ? workspaceNamed(name) : undefined;
+        return workspace === undefined ? [] : [workspace];
+    };
+    /** A peer resolves when the lockfile installs one version of it. */
+    const peer = (name) => {
+        const found = byName.get(name) ?? [];
+        return found.length > 0 && found.every((node) => node.version === found[0].version) ? found : [];
+    };
+    const edges = (node) => {
+        const own = node;
+        return [...own.production.flatMap(([name, range]) => target(name, range)), ...own.peers.flatMap(peer)];
+    };
+    const direct = (workspace) => {
+        const manifest = workspaces.get(workspace.folder)?.manifest;
+        if (manifest === null || manifest === undefined)
+            return [];
+        return [...manifest.production, ...manifest.development].flatMap(([name, range]) => target(name, range));
+    };
+    const listed = [...workspaces.entries()]
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        // Berry's entry names a workspace; its `0.0.0-use.local` version is none.
+        .map(([folder, { name }]) => ({ folder, name, version: null }));
+    const missing = [...new Set(unreadable)].sort();
+    return {
+        lockfile: graph({
+            format: 'yarn',
+            keyedByInstallPath: false,
+            confidence: 'medium',
+            nodes,
+            workspaces: listed,
+            unresolved: missing.length === 0 ? null : `the manifest ${missing[0]} beside the lockfile is missing or unreadable`,
+            edges,
+            direct,
+            place: (directory) => placeByName(directory, byName, listed, edges, direct),
+        }),
+    };
+}

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

@@ -0,0 +1,45 @@
+import type { Level } from '../completeness/index.ts';
+import type { SurfaceScope } from '../config/index.ts';
+import { type Baseline, type BaselineEntry, type PackageVersion } from './lib/format.ts';
+export { formatVersion, type Baseline, type BaselineEntry, type PackageVersion } from './lib/format.ts';
+export { migrations, type Migrations } from './lib/migrations.ts';
+export type { ReportReading } from './lib/report.ts';
+export { readPrevious, type PreviousValue, type PreviousValues, type ReadPrevious } from './lib/previous.ts';
+export { BaselineError, readBaseline, writtenVersions, type ReadBaseline } from './lib/read.ts';
+export { newerVersions, versionSkew, type BaselineNote, type NewerVersion, type VersionPair, type Versions, type VersionSkew, } from './lib/skew.ts';
+/**
+ * How a finding compares with the baseline (§11 Baseline states and matching). The compare module gives it, and a
+ * baseline accepts every finding except a `removed` one.
+ */
+export type BaselineState = 'added' | 'existing' | 'changed' | 'removed' | 'unconfirmed';
+/**
+ * A finding of a scan, as a baseline accepts it: its entry fields, and its baseline state when the scan was compared
+ * with a baseline (§11 Baseline states and matching).
+ */
+export interface ScannedFinding extends BaselineEntry {
+    baselineState?: BaselineState | null;
+}
+/**
+ * The baseline that accepts the whole current finding set of a scan (§11 Commands: `baseline init` and `baseline
+ * update`). That is every finding except a `removed` one, which is a baseline entry the scan no longer finds. A paired
+ * finding is accepted under its current fingerprint (ADR 0020).
+ */
+export declare function buildBaseline(input: {
+    scanConfigId: string;
+    surface: SurfaceScope;
+    tool: {
+        fingerprintScheme: number;
+        catalogVersion: number;
+        monkeypatchlistVersion: string;
+    };
+    completeness: Level;
+    /** The scan's findings: an entry keeps only their entry fields. */
+    findings: readonly ScannedFinding[];
+    /** The scan's `packages` map: its findings' containing packages, strong versions only (§10, §11). */
+    packages: Readonly<Record<string, PackageVersion>>;
+}): Baseline;
+/**
+ * The baseline file's text (§11 Determinism): 2-space indent, LF line endings and a trailing newline. With the fixed
+ * key order and sorted entries, an unchanged build rewrites it byte for byte.
+ */
+export declare function renderBaseline(baseline: Baseline): string;

package/dist/packages/baseline/index.js

@@ -0,0 +1,41 @@
+// Baseline (§11 Baseline, ADR 0001): the committed, deterministic JSON file of accepted findings that `baseline init`
+// writes, `baseline update` rewrites and a scan is compared with. It holds one entry per finding, with the attributes that decide `changed` and
+// readable context, and nothing that churns on a rebuild. It knows nothing of files: the CLI reads and writes the text.
+import { compareStrings } from "../findings/index.js";
+import { entry, formatVersion } from "./lib/format.js";
+export { formatVersion } from "./lib/format.js";
+export { migrations } from "./lib/migrations.js";
+export { readPrevious } from "./lib/previous.js";
+export { BaselineError, readBaseline, writtenVersions } from "./lib/read.js";
+export { newerVersions, versionSkew, } from "./lib/skew.js";
+/**
+ * The baseline that accepts the whole current finding set of a scan (§11 Commands: `baseline init` and `baseline
+ * update`). That is every finding except a `removed` one, which is a baseline entry the scan no longer finds. A paired
+ * finding is accepted under its current fingerprint (ADR 0020).
+ */
+export function buildBaseline(input) {
+    const { tool } = input;
+    return {
+        formatVersion,
+        scanConfigId: input.scanConfigId,
+        fingerprintScheme: tool.fingerprintScheme,
+        catalogVersion: tool.catalogVersion,
+        monkeypatchlistVersion: tool.monkeypatchlistVersion,
+        completeness: input.completeness,
+        surface: input.surface,
+        packages: Object.fromEntries(Object.entries(input.packages)
+            .sort(([a], [b]) => compareStrings(a, b))
+            .map(([name, { version, versionSource }]) => [name, { version, versionSource }])),
+        entries: input.findings
+            .filter((finding) => finding.baselineState !== 'removed')
+            .map(entry)
+            .sort((a, b) => compareStrings(a.fingerprint, b.fingerprint)),
+    };
+}
+/**
+ * The baseline file's text (§11 Determinism): 2-space indent, LF line endings and a trailing newline. With the fixed
+ * key order and sorted entries, an unchanged build rewrites it byte for byte.
+ */
+export function renderBaseline(baseline) {
+    return `${JSON.stringify(baseline, null, 2)}\n`;
+}

package/dist/packages/baseline/lib/error.d.ts

@@ -0,0 +1,15 @@
+import type { ErrorObject } from 'ajv/dist/2020.js';
+/** A baseline text that isn't a baseline this monkeypatchlist reads. The message says what is wrong with it. */
+export declare class BaselineError extends Error {
+    name: string;
+    /**
+     * Whether the text is a baseline in a `formatVersion` newer than this monkeypatchlist's, which is a hard error (§11 Format
+     * versions). Otherwise the text is not a readable baseline at all.
+     */
+    readonly newerFormat: boolean;
+    constructor(message: string, options?: {
+        newerFormat?: boolean;
+    });
+}
+/** A validation error as `<JSON Pointer>: <what is wrong>`. */
+export declare function problem({ keyword, instancePath, params, message }: ErrorObject): string;

package/dist/packages/baseline/lib/error.js

@@ -0,0 +1,25 @@
+// Why a text is no baseline this monkeypatchlist reads.
+/** A baseline text that isn't a baseline this monkeypatchlist reads. The message says what is wrong with it. */
+export class BaselineError extends Error {
+    name = 'BaselineError';
+    /**
+     * Whether the text is a baseline in a `formatVersion` newer than this monkeypatchlist's, which is a hard error (§11 Format
+     * versions). Otherwise the text is not a readable baseline at all.
+     */
+    newerFormat;
+    constructor(message, options = {}) {
+        super(message);
+        this.newerFormat = options.newerFormat ?? false;
+    }
+}
+/** A validation error as `<JSON Pointer>: <what is wrong>`. */
+export function problem({ keyword, instancePath, params, message }) {
+    const at = instancePath === '' ? '(top level)' : instancePath;
+    if (keyword === 'required')
+        return `${instancePath}/${params.missingProperty}: is required`;
+    if (keyword === 'enum') {
+        const allowed = params.allowedValues;
+        return `${at}: must be one of ${allowed.map((value) => JSON.stringify(value)).join(', ')}`;
+    }
+    return `${at}: ${message}`;
+}

package/dist/packages/baseline/lib/format.d.ts

@@ -0,0 +1,49 @@
+import type { Surface } from '../../../catalog.ts';
+import type { Effect, Locks, Target } from '../../analysis/index.ts';
+import type { Attribution } from '../../attribution/index.ts';
+import type { Level } from '../../completeness/index.ts';
+import type { SurfaceScope } from '../../config/index.ts';
+/** The baseline format's version (§11 Format versions). */
+export declare const formatVersion = 1;
+/**
+ * One accepted finding. The fingerprint, and the attributes that decide `changed` (attribution key, effect and
+ * `locks`), with the readable context that reports it when it is `removed` (target and its realm, surface, provenance,
+ * and for a `pkg:` key the containing package in `attribution`).
+ */
+export interface BaselineEntry {
+    fingerprint: string;
+    target: Target;
+    surface: Surface;
+    effect: Effect;
+    locks: Locks;
+    attribution: Attribution;
+}
+/** A package's strong version, and where it came from (§10 Version): `store-path` or `lockfile`. */
+export interface PackageVersion {
+    version: string;
+    versionSource: string;
+}
+/** A baseline: its header, then its entries, sorted by fingerprint. */
+export interface Baseline {
+    formatVersion: typeof formatVersion;
+    /** The scan-config id of the scan it was written from (§16). */
+    scanConfigId: string;
+    fingerprintScheme: number;
+    catalogVersion: number;
+    monkeypatchlistVersion: string;
+    /** The completeness level it was written under (§13: only the summary level is stored). */
+    completeness: Level;
+    /** The surface scope it covers (§12): each scope has its own baseline. */
+    surface: SurfaceScope;
+    /**
+     * Name → version and version source, strong versions only (§10), for the containing packages of the scan's findings. A
+     * name with more than one strong version in the scan has no entry.
+     */
+    packages: Record<string, PackageVersion>;
+    entries: BaselineEntry[];
+}
+/**
+ * The entry of a finding, or of an entry read from a file, with its keys in a fixed order: the fingerprint first, then
+ * the fields in the report's order. Nothing else is kept.
+ */
+export declare function entry({ fingerprint, target, surface, effect, locks, attribution }: BaselineEntry): BaselineEntry;

package/dist/packages/baseline/lib/format.js

@@ -0,0 +1,22 @@
+// The baseline format (§11 Baseline): its header and entries, in the fixed key order `baseline init` writes.
+/** The baseline format's version (§11 Format versions). */
+export const formatVersion = 1;
+/**
+ * The entry of a finding, or of an entry read from a file, with its keys in a fixed order: the fingerprint first, then
+ * the fields in the report's order. Nothing else is kept.
+ */
+export function entry({ fingerprint, target, surface, effect, locks, attribution }) {
+    const { realm, holder, name, shadows } = target;
+    return {
+        fingerprint,
+        target: { realm, holder, name, ...(shadows === undefined ? {} : { shadows }) },
+        surface,
+        effect,
+        locks,
+        attribution: {
+            key: attribution.key,
+            provenance: attribution.provenance,
+            ...(attribution.package === undefined ? {} : { package: attribution.package }),
+        },
+    };
+}

package/dist/packages/baseline/lib/migrations.d.ts

@@ -0,0 +1,19 @@
+import type { BaselineEntry } from './format.ts';
+export interface Migrations {
+    /**
+     * Format migrations, by the `formatVersion` each reads. Each turns a baseline file's parsed JSON in that format into
+     * the next format's, `formatVersion` included. The JSON is unchecked: a migration that throws on it makes the file
+     * not a readable baseline, and the schema check judges what the last one gives.
+     */
+    format: ReadonlyMap<number, (baseline: unknown) => unknown>;
+    /**
+     * Fingerprint scheme migrations, by the scheme each reads (§4: a scheme bump ships one). Each gives the baseline's
+     * entries under the next scheme.
+     */
+    fingerprintScheme: ReadonlyMap<number, (entries: readonly BaselineEntry[]) => BaselineEntry[]>;
+}
+/**
+ * The migrations this monkeypatchlist ships. There are none yet: `formatVersion` 1 and fingerprint scheme 1 are the first. A
+ * scheme change that can't be migrated needs a major release (§4).
+ */
+export declare const migrations: Migrations;

package/dist/packages/baseline/lib/migrations.js

@@ -0,0 +1,7 @@
+// Migrations (§11 Format versions, §4 Version skew): how this monkeypatchlist reads a baseline written in an older format, or
+// under an older fingerprint scheme. The baseline is migrated in memory, and `baseline update` rewrites it.
+/**
+ * The migrations this monkeypatchlist ships. There are none yet: `formatVersion` 1 and fingerprint scheme 1 are the first. A
+ * scheme change that can't be migrated needs a major release (§4).
+ */
+export const migrations = { format: new Map(), fingerprintScheme: new Map() };

package/dist/packages/baseline/lib/previous.d.ts

@@ -0,0 +1,23 @@
+import { type InstallContext, type Reachability } from '../../analysis/index.ts';
+/** A finding's reachability and install context in the previous scan (§7). */
+export interface PreviousValue {
+    reachability: Reachability;
+    installContext: InstallContext;
+}
+/**
+ * The previous scan's values by fingerprint. A finding the previous scan reported with no occurrences (`removed` or
+ * `unconfirmed`) has none.
+ */
+export type PreviousValues = ReadonlyMap<string, PreviousValue>;
+/** A previous report as `--previous` reads it: the scan-config id it must share with the scan, and its values. */
+export interface ReadPrevious {
+    scanConfigId: string;
+    values: PreviousValues;
+}
+/**
+ * The previous values in a parsed report `value` (§11), or a `BaselineError` that says why it isn't a report they can
+ * be read from.
+ */
+export declare function previousOfReport(value: unknown, reportVersion: number): ReadPrevious;
+/** The previous report in `text` (§16 `--previous`), or a `BaselineError` that says why it can't be read. */
+export declare function readPrevious(text: string, reportVersion: number): ReadPrevious;

package/dist/packages/baseline/lib/previous.js

@@ -0,0 +1,64 @@
+// A previous scan's values (§11 Never `changed`, §16 `--previous`): each finding's reachability and install context in
+// a full JSON scan report, which the reachability-change and install-context-change notes compare with. A baseline
+// stores neither (ADR 0014), so they come from `--previous`, or from `--baseline` when it is a full report.
+import { Ajv2020 } from 'ajv/dist/2020.js';
+import { installContexts, reachabilities } from "../../analysis/index.js";
+import { BaselineError, problem } from "./error.js";
+import { isReport } from "./report.js";
+/** The parts of a report the previous values are read from. */
+const schema = {
+    type: 'object',
+    required: ['reportVersion', 'config', 'findings'],
+    properties: {
+        reportVersion: { type: 'integer' },
+        config: { type: 'object', required: ['scanConfigId'], properties: { scanConfigId: { type: 'string' } } },
+        findings: {
+            type: 'array',
+            items: {
+                type: 'object',
+                required: ['fingerprint', 'reachability', 'installContext'],
+                properties: {
+                    fingerprint: { type: 'string', minLength: 1 },
+                    reachability: { enum: [...reachabilities, null] },
+                    installContext: { enum: [...installContexts, null] },
+                },
+            },
+        },
+    },
+};
+let validate;
+/**
+ * The previous values in a parsed report `value` (§11), or a `BaselineError` that says why it isn't a report they can
+ * be read from.
+ */
+export function previousOfReport(value, reportVersion) {
+    if (!isReport(value))
+        throw new BaselineError('it is not a scan report');
+    validate ??= new Ajv2020({ allErrors: true, strict: true }).compile(schema);
+    if (!validate(value)) {
+        const problems = (validate.errors ?? []).map(problem);
+        throw new BaselineError(`it is not a scan report:\n${problems.map((line) => `  ${line}`).join('\n')}`);
+    }
+    const report = value;
+    if (report.reportVersion !== reportVersion) {
+        const relation = report.reportVersion > reportVersion ? 'newer' : 'older';
+        throw new BaselineError(`it is a scan report in reportVersion ${report.reportVersion}, ${relation} than this monkeypatchlist reads (${reportVersion})`);
+    }
+    const values = new Map();
+    for (const { fingerprint, reachability, installContext } of report.findings) {
+        if (reachability !== null && installContext !== null)
+            values.set(fingerprint, { reachability, installContext });
+    }
+    return { scanConfigId: report.config.scanConfigId, values };
+}
+/** The previous report in `text` (§16 `--previous`), or a `BaselineError` that says why it can't be read. */
+export function readPrevious(text, reportVersion) {
+    let value;
+    try {
+        value = JSON.parse(text.startsWith('\uFEFF') ? text.slice(1) : text);
+    }
+    catch (error) {
+        throw new BaselineError(`it is not valid JSON: ${error.message}`);
+    }
+    return previousOfReport(value, reportVersion);
+}

package/dist/packages/baseline/lib/read.d.ts

@@ -0,0 +1,39 @@
+import { type Baseline } from './format.ts';
+import { type Migrations } from './migrations.ts';
+import { type PreviousValues } from './previous.ts';
+import { type ReportReading } from './report.ts';
+import { type Versions } from './skew.ts';
+export { BaselineError } from './error.ts';
+/** A baseline as this monkeypatchlist reads it, and the versions its file was written with (§4 Version skew). */
+export interface ReadBaseline {
+    baseline: Baseline;
+    written: Versions;
+    /**
+     * The previous scan's values when the text is a full report (§11 Never `changed`, §16 `--previous`): a report used as
+     * the baseline also supplies them. Null for a baseline file, which stores none (ADR 0014).
+     */
+    previous: PreviousValues | null;
+}
+/**
+ * The baseline in `text`, or a `BaselineError` that says why it isn't one. The baseline comes back with its keys in the
+ * fixed order `baseline init` writes, without keys this monkeypatchlist doesn't read.
+ *
+ * - A `formatVersion` newer than this monkeypatchlist's is an error, and an older one is migrated in memory (§11 Format
+ *   versions), by `migrations`. An older one that no migration reads is not a readable baseline.
+ * - A fingerprint scheme older than this monkeypatchlist's is migrated in memory, by `migrations`. A scheme that can't be
+ *   migrated (a newer one, or an older one that no migration reads) is not a readable baseline: a hard error under
+ *   `--fail-on`, and a scan without a baseline otherwise (§4 Version skew, §11 No baseline).
+ * - A fingerprint that two entries share is an error.
+ * - With `options.report`, the text may be a full scan report instead, read as the baseline `baseline update` would
+ *   have written from its scan (§11 Baseline, ADR 0020). Without it, a report is not a readable baseline.
+ */
+export declare function readBaseline(text: string, migrations?: Migrations, options?: {
+    report?: ReportReading;
+}): ReadBaseline;
+/**
+ * The versions a baseline's text was written with (§4 Version skew), for `baseline init` to tell whether the file it
+ * replaces came from a newer version. They are the versions `readBaseline` reads. A text that isn't a baseline this
+ * monkeypatchlist reads (a newer format or fingerprint scheme, or a newer catalog's holder) gives each version its header
+ * records in a well-formed value, and a text that isn't a JSON object gives none.
+ */
+export declare function writtenVersions(text: string, migrations?: Migrations): Partial<Versions>;