monkeypatchlist 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,219 @@
+// Reading a baseline file's text (§11 Baseline, Format versions). The CLI reads the bytes; this checks them.
+import { Ajv2020 } from 'ajv/dist/2020.js';
+import { holders, realms, surfaces } from "../../../catalog.js";
+import { effects } from "../../analysis/index.js";
+import { provenances } from "../../attribution/index.js";
+import { levels } from "../../completeness/index.js";
+import { fingerprintScheme } from "../../findings/index.js";
+import { BaselineError, problem } from "./error.js";
+import { entry, formatVersion } from "./format.js";
+import { migrations as shipped } from "./migrations.js";
+import { previousOfReport } from "./previous.js";
+import { baselineOfReport, isReport } from "./report.js";
+import { semver } from "./skew.js";
+export { BaselineError } from "./error.js";
+const scopes = ['protected', 'all'];
+/** The shape of a `formatVersion` 1 baseline. Keys it doesn't name are ignored. */
+const schema = {
+    type: 'object',
+    required: [
+        'formatVersion',
+        'scanConfigId',
+        'fingerprintScheme',
+        'catalogVersion',
+        'monkeypatchlistVersion',
+        'completeness',
+        'surface',
+        'packages',
+        'entries',
+    ],
+    properties: {
+        formatVersion: { const: formatVersion },
+        scanConfigId: { type: 'string' },
+        fingerprintScheme: { type: 'integer' },
+        catalogVersion: { type: 'integer', minimum: 1 },
+        monkeypatchlistVersion: { type: 'string', format: 'semver' },
+        completeness: { enum: levels },
+        surface: { enum: scopes },
+        packages: {
+            type: 'object',
+            additionalProperties: {
+                type: 'object',
+                required: ['version', 'versionSource'],
+                properties: { version: { type: 'string' }, versionSource: { type: 'string' } },
+            },
+        },
+        entries: {
+            type: 'array',
+            items: {
+                type: 'object',
+                required: ['fingerprint', 'target', 'surface', 'effect', 'locks', 'attribution'],
+                properties: {
+                    fingerprint: { type: 'string', minLength: 1 },
+                    target: {
+                        type: 'object',
+                        required: ['realm', 'holder', 'name'],
+                        properties: {
+                            realm: { enum: realms },
+                            holder: { enum: holders },
+                            name: { type: 'string', minLength: 1 },
+                            shadows: { type: 'string', minLength: 1 },
+                        },
+                    },
+                    surface: { enum: surfaces },
+                    effect: { enum: effects },
+                    locks: { enum: [true, false, 'unknown'] },
+                    attribution: {
+                        type: 'object',
+                        required: ['key', 'provenance'],
+                        properties: {
+                            key: { type: 'string', minLength: 1 },
+                            provenance: { enum: provenances },
+                            package: { type: 'string', minLength: 1 },
+                        },
+                    },
+                },
+            },
+        },
+    },
+};
+let validate;
+/**
+ * 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 function readBaseline(text, migrations = shipped, options = {}) {
+    let value;
+    try {
+        value = parseJson(text);
+    }
+    catch (error) {
+        throw new BaselineError(`it is not valid JSON: ${error.message}`);
+    }
+    // `scan --baseline` also reads a full scan report, as the baseline `baseline update` would write from its scan (§11
+    // Baseline, ADR 0020). Nothing else reads one as a baseline.
+    let previous = null;
+    if (isReport(value)) {
+        if (options.report === undefined)
+            throw new BaselineError('it is a scan report, not a baseline file');
+        const report = value;
+        value = baselineOfReport(report, options.report);
+        previous = previousOfReport(report, options.report.reportVersion).values;
+    }
+    const version = value?.formatVersion;
+    if (typeof version === 'number' && version > formatVersion) {
+        throw new BaselineError(`its formatVersion ${version} is newer than this monkeypatchlist reads (${formatVersion})`, {
+            newerFormat: true,
+        });
+    }
+    if (typeof version === 'number' && Number.isInteger(version)) {
+        for (let from = version; from < formatVersion; from++) {
+            const migrate = migrations.format.get(from);
+            if (migrate === undefined) {
+                throw new BaselineError(`its formatVersion ${version} is older than this monkeypatchlist can migrate to the one it reads (${formatVersion})`);
+            }
+            // A format migration reads the file before any schema check, so one that throws on it read a file that isn't a
+            // baseline in that format.
+            try {
+                value = migrate(value);
+            }
+            catch (error) {
+                throw new BaselineError(`it is not a baseline in formatVersion ${from}: ${error.message}`);
+            }
+        }
+    }
+    // `monkeypatchlistVersion` is checked as a named format, so a bad one is reported as not `semver`, not by the regex.
+    validate ??= new Ajv2020({ allErrors: true, strict: true, formats: { semver } }).compile(schema);
+    if (!validate(value)) {
+        const problems = (validate.errors ?? []).map(problem);
+        throw new BaselineError(`it is not a baseline:\n${problems.map((line) => `  ${line}`).join('\n')}`);
+    }
+    const baseline = value;
+    const scheme = baseline.fingerprintScheme;
+    let migrated = baseline.entries;
+    for (let from = scheme; from !== fingerprintScheme; from++) {
+        const migrate = from < fingerprintScheme ? migrations.fingerprintScheme.get(from) : undefined;
+        if (migrate === undefined) {
+            // A newer scheme comes from a newer monkeypatchlist: replacing it with this one is a downgrade (§4 Version skew).
+            const [skew, remedy] = scheme > fingerprintScheme
+                ? [
+                    'is newer than',
+                    'Upgrade monkeypatchlist, or write a new baseline with monkeypatchlist baseline init --allow-downgrade',
+                ]
+                : ["can't be migrated to", 'Write a new baseline with monkeypatchlist baseline init'];
+            throw new BaselineError(`its fingerprint scheme ${scheme} ${skew} this monkeypatchlist's (${fingerprintScheme}), so its fingerprints never ` +
+                `match this scan's. ${remedy}`);
+        }
+        migrated = migrate(migrated);
+    }
+    const entries = migrated.map(entry);
+    const seen = new Set();
+    for (const { fingerprint } of entries) {
+        if (seen.has(fingerprint))
+            throw new BaselineError(`it lists the fingerprint ${fingerprint} twice`);
+        seen.add(fingerprint);
+    }
+    const { catalogVersion, monkeypatchlistVersion } = baseline;
+    return {
+        baseline: {
+            formatVersion,
+            scanConfigId: baseline.scanConfigId,
+            fingerprintScheme,
+            catalogVersion,
+            monkeypatchlistVersion,
+            completeness: baseline.completeness,
+            surface: baseline.surface,
+            packages: Object.fromEntries(Object.entries(baseline.packages).map(([name, { version, versionSource }]) => [name, { version, versionSource }])),
+            entries,
+        },
+        written: { formatVersion: version, fingerprintScheme: scheme, catalogVersion, monkeypatchlistVersion },
+        previous,
+    };
+}
+/**
+ * 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 function writtenVersions(text, migrations = shipped) {
+    try {
+        return readBaseline(text, migrations).written;
+    }
+    catch (error) {
+        if (!(error instanceof BaselineError))
+            throw error;
+    }
+    let value;
+    try {
+        value = parseJson(text);
+    }
+    catch {
+        return {};
+    }
+    if (typeof value !== 'object' || value === null)
+        return {};
+    const header = value;
+    const written = {};
+    for (const name of ['formatVersion', 'fingerprintScheme', 'catalogVersion']) {
+        if (Number.isInteger(header[name]))
+            written[name] = header[name];
+    }
+    const { monkeypatchlistVersion } = header;
+    if (typeof monkeypatchlistVersion === 'string' && semver.test(monkeypatchlistVersion))
+        written.monkeypatchlistVersion = monkeypatchlistVersion;
+    return written;
+}
+/** The JSON value in a baseline file's `text`, with a leading UTF-8 byte order mark dropped. */
+function parseJson(text) {
+    return JSON.parse(text.startsWith('') ? text.slice(1) : text);
+}

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

@@ -0,0 +1,25 @@
+/** How `scan --baseline` reads a report (§11 Baseline). */
+export interface ReportReading {
+    /** The `reportVersion` this monkeypatchlist writes: a newer one is a hard error, as a newer `formatVersion` is (§11). */
+    reportVersion: number;
+    /**
+     * `--allow-incomplete`: a report whose completeness is `incomplete` is a readable baseline only with it, and then
+     * reads as `baseline update --allow-incomplete` would write it.
+     */
+    allowIncomplete: boolean;
+}
+/** Whether a parsed JSON value is a scan report rather than a baseline file: only a report has a `reportVersion`. */
+export declare function isReport(value: unknown): boolean;
+/**
+ * The baseline value `baseline update` would have written from the scan `value` reports (§11 Baseline, ADR 0020), or
+ * a `BaselineError` that says why the report is no readable baseline:
+ *
+ * - Every finding except a `removed` one is an entry, `added` and `changed` included, under its current fingerprint,
+ *   and `unconfirmed` entries carry forward. The header is the scan's: its scan-config id, surface, completeness level,
+ *   versions and `packages` map.
+ * - An `incomplete` report is refused without `--allow-incomplete`.
+ * - A report whose crash guard fired holds no findings, so `update --allow-incomplete` would have left its baseline as
+ *   it was (§13): it gives back that baseline, its header and its `unconfirmed` entries. One with no baseline of its own
+ *   is refused even with the flag, as `baseline init` refuses its scan.
+ */
+export declare function baselineOfReport(value: unknown, reading: ReportReading): unknown;

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

@@ -0,0 +1,104 @@
+// A full scan JSON report read as a baseline (§11 Baseline, ADR 0020): as if `baseline update` had just been run on
+// that scan. This turns the report's value into the baseline value `update` would have written, which `readBaseline`
+// then checks like a file's.
+import { Ajv2020 } from 'ajv/dist/2020.js';
+import { BaselineError, problem } from "./error.js";
+import { formatVersion } from "./format.js";
+/**
+ * The parts of a report this reads. The baseline value made from them is checked against the baseline schema, so this
+ * checks only what it reads to make one.
+ */
+const schema = {
+    type: 'object',
+    required: ['reportVersion', 'tool', 'config', 'completeness', 'baseline', 'packages', 'findings'],
+    properties: {
+        reportVersion: { type: 'integer' },
+        tool: {
+            type: 'object',
+            required: ['monkeypatchlistVersion', 'catalogVersion', 'fingerprintScheme'],
+            properties: { monkeypatchlistVersion: {}, catalogVersion: {}, fingerprintScheme: {} },
+        },
+        config: { type: 'object', required: ['scanConfigId', 'surface'], properties: { scanConfigId: {}, surface: {} } },
+        completeness: {
+            type: 'object',
+            required: ['level', 'counters'],
+            properties: {
+                level: {},
+                counters: {
+                    type: 'object',
+                    required: ['statistics'],
+                    properties: { statistics: { type: 'object', required: ['crashGuard'], properties: { crashGuard: {} } } },
+                },
+            },
+        },
+        baseline: {
+            oneOf: [{ type: 'null' }, { type: 'object', required: ['header'], properties: { header: { type: 'object' } } }],
+        },
+        packages: { type: 'object' },
+        findings: { type: 'array', items: { type: 'object' } },
+    },
+};
+let validate;
+/** Whether a parsed JSON value is a scan report rather than a baseline file: only a report has a `reportVersion`. */
+export function isReport(value) {
+    return typeof value === 'object' && value !== null && 'reportVersion' in value;
+}
+/**
+ * The baseline value `baseline update` would have written from the scan `value` reports (§11 Baseline, ADR 0020), or
+ * a `BaselineError` that says why the report is no readable baseline:
+ *
+ * - Every finding except a `removed` one is an entry, `added` and `changed` included, under its current fingerprint,
+ *   and `unconfirmed` entries carry forward. The header is the scan's: its scan-config id, surface, completeness level,
+ *   versions and `packages` map.
+ * - An `incomplete` report is refused without `--allow-incomplete`.
+ * - A report whose crash guard fired holds no findings, so `update --allow-incomplete` would have left its baseline as
+ *   it was (§13): it gives back that baseline, its header and its `unconfirmed` entries. One with no baseline of its own
+ *   is refused even with the flag, as `baseline init` refuses its scan.
+ */
+export function baselineOfReport(value, reading) {
+    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 > reading.reportVersion) {
+        throw new BaselineError(`it is a scan report in reportVersion ${report.reportVersion}, newer than this monkeypatchlist reads (${reading.reportVersion})`, { newerFormat: true });
+    }
+    if (report.reportVersion < reading.reportVersion) {
+        throw new BaselineError(`it is a scan report in reportVersion ${report.reportVersion}, older than this monkeypatchlist reads (${reading.reportVersion})`);
+    }
+    const { level } = report.completeness;
+    const fired = report.completeness.counters.statistics.crashGuard === 'fired';
+    if (fired && report.baseline === null) {
+        throw new BaselineError("it is the report of a scan whose crash guard fired, with no baseline of its own: it holds no findings, so it isn't " +
+            'read as a baseline even under --allow-incomplete, as baseline init refuses such a scan');
+    }
+    if (level === 'incomplete' && !reading.allowIncomplete) {
+        throw new BaselineError("it is the report of an incomplete scan (its completeness says what was not analyzed): pass --allow-incomplete to " +
+            'read it as baseline update --allow-incomplete would write it');
+    }
+    const entries = report.findings
+        .filter((finding) => finding.baselineState !== 'removed')
+        .map(({ fingerprint, target, surface, effect, locks, attribution }) => ({
+        fingerprint,
+        target,
+        surface,
+        effect,
+        locks,
+        attribution,
+    }));
+    if (fired)
+        return { ...report.baseline.header, formatVersion, entries };
+    return {
+        formatVersion,
+        scanConfigId: report.config.scanConfigId,
+        fingerprintScheme: report.tool.fingerprintScheme,
+        catalogVersion: report.tool.catalogVersion,
+        monkeypatchlistVersion: report.tool.monkeypatchlistVersion,
+        completeness: level,
+        surface: report.config.surface,
+        packages: report.packages,
+        entries,
+    };
+}

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

@@ -0,0 +1,51 @@
+/** The versions a baseline's header records (§11 Baseline), or that a scan runs with (§15 `tool`). */
+export interface Versions {
+    formatVersion: number;
+    fingerprintScheme: number;
+    catalogVersion: number;
+    monkeypatchlistVersion: string;
+}
+/** A version on each side: the baseline's, as its file was written, and the scan's. */
+export interface VersionPair<Version> {
+    baseline: Version;
+    scan: Version;
+}
+/**
+ * The scan-level note that the baseline was written by another version (§4 Version skew, §15 `baseline.notes`). It
+ * names each version on both sides.
+ */
+export interface VersionSkew {
+    kind: 'version-skew';
+    /**
+     * The side written by the newer version. `baseline` when any of the baseline's versions is newer than the scan's: a
+     * stale install, which scans with a warning and no `explainedBy`, and which `baseline update` refuses to rewrite
+     * without `--allow-downgrade`. Otherwise `scan`: an upgrade, where a delta without `explainedBy` may come from analyzer
+     * changes.
+     */
+    newer: 'baseline' | 'scan';
+    formatVersion: VersionPair<number>;
+    fingerprintScheme: VersionPair<number>;
+    catalogVersion: VersionPair<number>;
+    monkeypatchlistVersion: VersionPair<string>;
+}
+/** A scan-level note on the baseline (§15 `baseline.notes`). */
+export type BaselineNote = VersionSkew;
+/**
+ * The version-skew note for a baseline written with the versions `baseline` and scanned with `scan`, or null when they
+ * are all the same.
+ */
+export declare function versionSkew(baseline: Versions, scan: Versions): VersionSkew | null;
+/** A version a baseline was written with that is newer than this monkeypatchlist's, with the version on each side. */
+export type NewerVersion = {
+    [Name in keyof Versions]: {
+        name: Name;
+    } & VersionPair<Versions[Name]>;
+}[keyof Versions];
+/**
+ * The versions of `baseline`'s that are newer than this monkeypatchlist's (`scan`), in the order of the baseline header (§4
+ * Version skew). A baseline with any was written by a newer monkeypatchlist or catalog: `baseline init` and `baseline update`
+ * refuse to replace it unless `--allow-downgrade` is given. A version `baseline` lacks is not compared.
+ */
+export declare function newerVersions(baseline: Partial<Versions>, scan: Versions): NewerVersion[];
+/** A semantic version: `major.minor.patch`, an optional `-prerelease` and optional `+build` metadata. */
+export declare const semver: RegExp;

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

@@ -0,0 +1,75 @@
+// Version skew (§4 Version skew, ADR 0008): a baseline written by another monkeypatchlist version than the one scanning.
+/**
+ * The version-skew note for a baseline written with the versions `baseline` and scanned with `scan`, or null when they
+ * are all the same.
+ */
+export function versionSkew(baseline, scan) {
+    const order = versionNames.map((name) => compare(name, baseline, scan));
+    if (order.every((sign) => sign === 0))
+        return null;
+    return {
+        kind: 'version-skew',
+        newer: order.some((sign) => sign > 0) ? 'baseline' : 'scan',
+        formatVersion: { baseline: baseline.formatVersion, scan: scan.formatVersion },
+        fingerprintScheme: { baseline: baseline.fingerprintScheme, scan: scan.fingerprintScheme },
+        catalogVersion: { baseline: baseline.catalogVersion, scan: scan.catalogVersion },
+        monkeypatchlistVersion: { baseline: baseline.monkeypatchlistVersion, scan: scan.monkeypatchlistVersion },
+    };
+}
+/**
+ * The versions of `baseline`'s that are newer than this monkeypatchlist's (`scan`), in the order of the baseline header (§4
+ * Version skew). A baseline with any was written by a newer monkeypatchlist or catalog: `baseline init` and `baseline update`
+ * refuse to replace it unless `--allow-downgrade` is given. A version `baseline` lacks is not compared.
+ */
+export function newerVersions(baseline, scan) {
+    return versionNames.flatMap((name) => {
+        if (baseline[name] === undefined || compare(name, baseline, scan) <= 0)
+            return [];
+        return [{ name, baseline: baseline[name], scan: scan[name] }];
+    });
+}
+/** The versions, in the order of the baseline header (§11 Baseline). */
+const versionNames = ['formatVersion', 'fingerprintScheme', 'catalogVersion', 'monkeypatchlistVersion'];
+/** Orders one version of `a` against the same version of `b`: negative when `a`'s is older, positive when newer. */
+function compare(name, a, b) {
+    return name === 'monkeypatchlistVersion'
+        ? compareVersions(a.monkeypatchlistVersion, b.monkeypatchlistVersion)
+        : Math.sign(a[name] - b[name]);
+}
+/** A semantic version: `major.minor.patch`, an optional `-prerelease` and optional `+build` metadata. */
+export const semver = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+/**
+ * Orders two monkeypatchlist versions by semantic-version precedence: negative when `a` is older, positive when it is newer,
+ * 0 when they rank the same. Build metadata is ignored, and a prerelease ranks below its release.
+ */
+function compareVersions(a, b) {
+    const [x, y] = [parse(a), parse(b)];
+    for (let i = 0; i < 3; i++)
+        if (x.core[i] !== y.core[i])
+            return Math.sign(x.core[i] - y.core[i]);
+    // A release ranks above its prereleases.
+    if (x.prerelease.length === 0 || y.prerelease.length === 0) {
+        return Math.sign(y.prerelease.length) - Math.sign(x.prerelease.length);
+    }
+    for (let i = 0; i < Math.min(x.prerelease.length, y.prerelease.length); i++) {
+        const order = compareIdentifiers(x.prerelease[i], y.prerelease[i]);
+        if (order !== 0)
+            return order;
+    }
+    return Math.sign(x.prerelease.length - y.prerelease.length);
+}
+function parse(version) {
+    const match = semver.exec(version);
+    if (match === null)
+        throw new Error(`'${version}' is not a semantic version`);
+    return { core: match.slice(1, 4).map(Number), prerelease: match[4]?.split('.') ?? [] };
+}
+/** Numeric identifiers rank by value and below alphanumeric ones, which rank by ASCII order. */
+function compareIdentifiers(a, b) {
+    const numeric = (identifier) => /^\d+$/.test(identifier);
+    if (numeric(a) && numeric(b))
+        return Math.sign(Number(a) - Number(b));
+    if (numeric(a) !== numeric(b))
+        return numeric(a) ? -1 : 1;
+    return a < b ? -1 : a > b ? 1 : 0;
+}

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

@@ -0,0 +1,120 @@
+import { type Effect, type InstallContext, type Reachability, type ReachabilityBasis } from '../analysis/index.ts';
+import type { Baseline, BaselineState, PackageVersion, PreviousValues } from '../baseline/index.ts';
+import type { Completeness } from '../completeness/index.ts';
+import type { Confidence } from '../confidence/index.ts';
+import { type Finding } from '../findings/index.ts';
+import type { ExplainingRecord } from './lib/catalog-notes.ts';
+export { withCatalogStatus, withExplainedBy, type ExplainingRecord } from './lib/catalog-notes.ts';
+/** How a finding compares with the baseline (§11). The baseline package defines it, since what it accepts depends on it. */
+export type { BaselineState } from '../baseline/index.ts';
+/** The matching pass that paired a finding with a baseline entry (§11 Baseline states and matching). */
+export type MatchedBy = 'fingerprint' | 'effect' | 'target-key';
+/**
+ * Why a paired finding is `changed`, with the baseline entry's value before and the finding's after (§11 `changed`). An
+ * `attribution` reason's values are attribution keys.
+ */
+export type ChangedReason = {
+    reason: 'attribution';
+    before: string;
+    after: string;
+} | {
+    reason: 'effect';
+    before: Effect;
+    after: Effect;
+} | {
+    reason: 'locks';
+    before: boolean;
+    after: boolean;
+};
+/**
+ * A note on a finding (§11, §15 Findings). `rekeyed`: the target-key pass paired it across `unknown`, from the paired
+ * baseline entries' attribution keys (`before`) to its own (`after`). `shared-target-key`: it stays `added` or `removed`
+ * because its target-key group is ambiguous, and `fingerprints` are the other side's known keys it could have paired
+ * with. `previous-version`: its containing package has a strong version on both sides and they differ (§11
+ * `previousVersion`), from the baseline's version (`before`) to the scan's (`after`). `reachability-change` and
+ * `install-context-change`: its reachability or install context differs from the previous scan's value for the finding
+ * it paired with (§11 Never `changed`), from that value (`before`) to its own (`after`). They never decide a state.
+ */
+export type FindingNote = {
+    kind: 'rekeyed';
+    before: string[];
+    after: string;
+} | {
+    kind: 'shared-target-key';
+    fingerprints: string[];
+} | {
+    kind: 'previous-version';
+    package: string;
+    before: string;
+    after: string;
+} | {
+    kind: 'reachability-change';
+    before: Reachability;
+    after: Reachability;
+} | {
+    kind: 'install-context-change';
+    before: InstallContext;
+    after: InstallContext;
+};
+/**
+ * A scanned finding with its baseline state, or a baseline entry the scan didn't find. That one has the entry's readable
+ * context, no occurrences, and no confidence, which only occurrences give (§15 Findings).
+ */
+export interface ComparedFinding extends Omit<Finding, 'confidence' | 'reachability' | 'reachabilityBasis' | 'installContext'> {
+    confidence: Confidence | null;
+    /** Null for a baseline entry the scan didn't find, which has no occurrences (§15 Findings). */
+    reachability: Reachability | null;
+    /** Its basis (§7), null as `reachability` is. */
+    reachabilityBasis: ReachabilityBasis | null;
+    /** Null for a baseline entry the scan didn't find, as `reachability` is (§15 Findings). */
+    installContext: InstallContext | null;
+    /** Null when there is no readable baseline (§11 No baseline). */
+    baselineState: BaselineState | null;
+    /** The pass that paired it with a baseline entry, or null when nothing did. */
+    matchedBy: MatchedBy | null;
+    /** Before → after for each reason the finding is `changed`, in the §11 table's order. Empty unless it is `changed`. */
+    changedReasons: ChangedReason[];
+    /**
+     * Notes on how it was matched (§11), `rekeyed` or `shared-target-key`, then its `previous-version`, then its
+     * `reachability-change` and `install-context-change`.
+     */
+    notes: FindingNote[];
+    /** Set when its target, or the member it shadows, is a retained target (§4 Catalog versions): information only. */
+    catalogStatus?: 'retained';
+    /**
+     * The catalog changelog's records that could explain this delta (§4 Catalog versions), in changelog order. Absent when
+     * none does, and never set on `unconfirmed` or on `existing` without a `rekeyed` note. Never baselined.
+     */
+    explainedBy?: ExplainingRecord[];
+}
+/**
+ * Compares findings with the baseline (§11 Baseline states and matching), in order:
+ *
+ * 1. By exact fingerprint.
+ * 2. The effect pass: a finding and an entry left over with the same realm, target and attribution key but a different
+ *    effect pair when each is the only one left in that group (1:1). A paired finding is `changed`, reason `effect`.
+ * 3. The target-key pass, over the findings and entries left over by target key `(realm, target, effect)`, plus any
+ *    `unknown` finding or entry the exact pass matched. A known key pairs with a known key 1:1 only: `changed`,
+ *    reason `attribution`. An `unknown` finding pairs with every known entry left over in its group, and an `unknown`
+ *    entry with every known finding left over, as a `rekeyed` pair; both rules apply in one group. The known
+ *    findings and entries of a group with both but not 1:1 that nothing pairs stay `added` and `removed`, with a
+ *    `shared-target-key` note.
+ *
+ * A paired finding whose `locks` went `true` ↔ `false` against any entry it pairs with is `changed`, reason `locks`,
+ * once per such entry; `unknown` on either side is no change. A paired finding with no reason is `existing`, and a
+ * finding nothing paired is `added`. An entry that matches no finding is `unconfirmed` when the scan could not have seen
+ * it (§13 Effects on the baseline and the gate): it is `incomplete`, a link group exhausted its step budget, or the entry
+ * is remote and a remote script was skipped. It is `removed` otherwise. Without a baseline, every finding's state is
+ * null. The result is sorted by fingerprint.
+ *
+ * Whatever its state, a finding whose containing package has a strong version in both the scan's `packages` map and
+ * the baseline's, and they differ, gets a `previous-version` note (§11 `previousVersion`). The version never decides a
+ * state.
+ *
+ * With `previous`, the values of a previous scan, an `existing` or `changed` finding whose reachability or install
+ * context differs from the previous value of a baseline entry it paired with gets a `reachability-change` or
+ * `install-context-change` note, one per distinct previous value (§11 Never `changed`). The previous value is the
+ * one under the entry's fingerprint, so it follows the pairing, a `rekeyed` one included. These notes never decide a
+ * state, and need a baseline.
+ */
+export declare function compare(findings: readonly Finding[], baseline: Baseline | null, completeness: Pick<Completeness, 'level' | 'limitations' | 'counters'>, packages?: Readonly<Record<string, PackageVersion>>, previous?: PreviousValues | null): ComparedFinding[];