monkeypatchlist 0.0.0-stage → 0.1.0

package/dist/packages/compare/index.js

@@ -0,0 +1,274 @@
+// Compare (§19, module 7): matches findings against a baseline or previous report, giving baseline states,
+// `changedReasons` and notes (§11). It knows nothing of the policy.
+import { installContexts, reachabilities, } from "../analysis/index.js";
+import { compareStrings, targetKey } from "../findings/index.js";
+export { withCatalogStatus, withExplainedBy } from "./lib/catalog-notes.js";
+/**
+ * The limitation kinds that say a scan skipped or refused a remote script (§13): `offline-skipped` in `offline` mode,
+ * and `remote-refused` by the safety floor (§17). A remote baseline entry may be in the code the scan didn't see.
+ */
+const remoteGapKinds = new Set(['offline-skipped', 'remote-refused']);
+/**
+ * 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 function compare(findings, baseline, completeness, packages = {}, previous = null) {
+    if (baseline === null) {
+        return findings.map((finding) => ({
+            ...finding,
+            baselineState: null,
+            matchedBy: null,
+            changedReasons: [],
+            notes: [],
+        }));
+    }
+    return states(findings, baseline, completeness).map(([finding, paired]) => {
+        const notes = [...finding.notes];
+        const name = finding.attribution.package;
+        const [before, after] = name === undefined ? [] : [baseline.packages[name], packages[name]];
+        if (name !== undefined && before !== undefined && after !== undefined && before.version !== after.version) {
+            notes.push({ kind: 'previous-version', package: name, before: before.version, after: after.version });
+        }
+        if (previous !== null)
+            notes.push(...previousNotes(finding, paired, previous));
+        return notes.length === finding.notes.length ? finding : { ...finding, notes };
+    });
+}
+/**
+ * A paired finding's `reachability-change` and `install-context-change` notes (§11 Never `changed`): for each attribute,
+ * one per distinct value that the previous scan gave a paired entry's fingerprint and that differs from the finding's
+ * own, in the attribute's order.
+ */
+function previousNotes(finding, paired, previous) {
+    const { reachability, installContext } = finding;
+    if (reachability === null || installContext === null)
+        return [];
+    const values = paired.flatMap(({ fingerprint }) => previous.get(fingerprint) ?? []);
+    const differing = (order, before, after) => order.filter((value) => value !== after && before.includes(value));
+    return [
+        ...differing(reachabilities, values.map((value) => value.reachability), reachability).map((before) => ({ kind: 'reachability-change', before, after: reachability })),
+        ...differing(installContexts, values.map((value) => value.installContext), installContext).map((before) => ({ kind: 'install-context-change', before, after: installContext })),
+    ];
+}
+/**
+ * Each finding's baseline state, how it was matched, its `changedReasons` and its matching notes (§11), with the
+ * baseline entries it paired with (none for an `added` finding or an entry the scan didn't find).
+ */
+function states(findings, baseline, completeness) {
+    const entries = new Map(baseline.entries.map((entry) => [entry.fingerprint, entry]));
+    const pairs = new Map();
+    const pair = (finding, pairing) => {
+        const found = pairs.get(finding);
+        if (found === undefined)
+            pairs.set(finding, [pairing]);
+        else
+            found.push(pairing);
+    };
+    // `unknown` findings and entries the exact or the effect pass paired still take part in the target-key pass.
+    const rejoin = { findings: [], entries: [] };
+    const rejoinUnknown = (finding, entry) => {
+        if (finding.attribution.key === unknownKey)
+            rejoin.findings.push(finding);
+        if (entry.attribution.key === unknownKey)
+            rejoin.entries.push(entry);
+    };
+    for (const finding of findings) {
+        const entry = entries.get(finding.fingerprint);
+        if (entry === undefined)
+            continue;
+        pair(finding, { entry, by: 'fingerprint' });
+        entries.delete(finding.fingerprint);
+        rejoinUnknown(finding, entry);
+    }
+    for (const [finding, entry] of effectPairs(findings.filter((finding) => !pairs.has(finding)), [...entries.values()])) {
+        pair(finding, { entry, by: 'effect' });
+        entries.delete(entry.fingerprint);
+        rejoinUnknown(finding, entry);
+    }
+    const shared = new Map();
+    for (const [finding, pairing] of targetKeyPairs([...findings.filter((finding) => !pairs.has(finding)), ...rejoin.findings], [...entries.values(), ...rejoin.entries], shared)) {
+        pair(finding, pairing);
+        entries.delete(pairing.entry.fingerprint);
+    }
+    const scanned = findings.map((finding) => {
+        const notes = sharedNote(shared.get(finding));
+        const pairings = pairs.get(finding);
+        if (pairings === undefined) {
+            return [{ ...finding, baselineState: 'added', matchedBy: null, changedReasons: [], notes }, []];
+        }
+        const changedReasons = pairings
+            .flatMap(({ entry, by }) => reasons(entry, finding, by))
+            .sort((a, b) => reasonOrder.indexOf(a.reason) - reasonOrder.indexOf(b.reason));
+        const rekeyed = [...new Set(pairings.flatMap(({ entry, by }) => (by === 'rekeyed' ? [entry.attribution.key] : [])))];
+        const compared = {
+            ...finding,
+            baselineState: changedReasons.length === 0 ? 'existing' : 'changed',
+            matchedBy: matchedBy(pairings[0].by),
+            changedReasons,
+            notes: rekeyed.length === 0
+                ? notes
+                : [{ kind: 'rekeyed', before: rekeyed.sort(compareStrings), after: finding.attribution.key }, ...notes],
+        };
+        return [compared, pairings.map(({ entry }) => entry)];
+    });
+    // An incomplete scan failed to analyze something its configuration asks for, so it can't confirm that any entry is
+    // gone, and nor can one in which any link group exhausted its step budget; a Principle 5 cap cut alone can. A
+    // scan that skipped or refused a remote script can't confirm that a remote entry is.
+    const incomplete = completeness.level === 'incomplete' || completeness.counters.statistics.budgetExhausted > 0;
+    const remoteGap = completeness.limitations.some(({ kind }) => remoteGapKinds.has(kind));
+    const unseen = ({ attribution }) => incomplete || (remoteGap && attribution.provenance === 'remote');
+    const missing = [...entries.values()].map((entry) => [
+        unmatched(entry, unseen(entry) ? 'unconfirmed' : 'removed', sharedNote(shared.get(entry))),
+        [],
+    ]);
+    return [...scanned, ...missing].sort(([a], [b]) => compareStrings(a.fingerprint, b.fingerprint));
+}
+/** The attribution key of code that can't be attributed (§11). */
+const unknownKey = 'unknown';
+/** The §11 table's order of `changed` reasons. */
+const reasonOrder = ['attribution', 'effect', 'locks'];
+const matchedBy = (by) => (by === 'attribution' || by === 'rekeyed' ? 'target-key' : by);
+const sharedNote = (fingerprints) => fingerprints === undefined ? [] : [{ kind: 'shared-target-key', fingerprints }];
+/**
+ * The target-key pass (§11 Baseline states and matching, step 3) over `findings` and `entries` grouped by target key.
+ * In each group, a lone known finding and a lone known entry pair (`attribution`); an `unknown` finding pairs with every
+ * known entry, and an `unknown` entry with every known finding (`rekeyed`). A group whose known findings and entries
+ * aren't 1:1 is ambiguous: `shared` gets, for each of its known members nothing pairs, the other side's fingerprints.
+ */
+function targetKeyPairs(findings, entries, shared) {
+    const groups = new Map();
+    const group = (key) => {
+        let found = groups.get(key);
+        if (found === undefined)
+            groups.set(key, (found = { findings: [], entries: [] }));
+        return found;
+    };
+    for (const finding of findings)
+        group(targetKey(finding.target, finding.effect)).findings.push(finding);
+    for (const entry of entries)
+        group(targetKey(entry.target, entry.effect)).entries.push(entry);
+    const pairs = [];
+    for (const { findings: groupFindings, entries: groupEntries } of groups.values()) {
+        const knownFindings = groupFindings.filter(({ attribution }) => attribution.key !== unknownKey);
+        const knownEntries = groupEntries.filter(({ attribution }) => attribution.key !== unknownKey);
+        const unknownFinding = groupFindings.find(({ attribution }) => attribution.key === unknownKey);
+        const unknownEntry = groupEntries.find(({ attribution }) => attribution.key === unknownKey);
+        const paired = new Set();
+        const add = (finding, entry, by) => {
+            pairs.push([finding, { entry, by }]);
+            paired.add(finding).add(entry);
+        };
+        const [knownFinding] = knownFindings;
+        const [knownEntry] = knownEntries;
+        if (knownFindings.length === 1 && knownEntries.length === 1)
+            add(knownFinding, knownEntry, 'attribution');
+        if (unknownFinding !== undefined)
+            for (const entry of knownEntries)
+                add(unknownFinding, entry, 'rekeyed');
+        if (unknownEntry !== undefined)
+            for (const finding of knownFindings)
+                add(finding, unknownEntry, 'rekeyed');
+        if (knownFinding === undefined || knownEntry === undefined)
+            continue;
+        for (const finding of knownFindings) {
+            if (!paired.has(finding))
+                shared.set(finding, knownEntries.map(({ fingerprint }) => fingerprint).sort(compareStrings));
+        }
+        for (const entry of knownEntries) {
+            if (!paired.has(entry))
+                shared.set(entry, knownFindings.map(({ fingerprint }) => fingerprint).sort(compareStrings));
+        }
+    }
+    return pairs;
+}
+/** A finding's or entry's `(realm, target, attribution key)`: its fingerprint without the effect (§11). */
+const effectGroup = ({ target, attribution }) => `${target.realm}|${target.name}|${attribution.key}`;
+/**
+ * The effect pass (§11 Baseline states and matching, step 2): the findings and entries left over, grouped by `(realm,
+ * target, attribution key)`, pair where a group holds exactly one of each. They differ in effect, since the exact
+ * fingerprints didn't match. Any other group is ambiguous and pairs nothing here.
+ */
+function effectPairs(findings, entries) {
+    const groups = new Map();
+    const group = (key) => {
+        let found = groups.get(key);
+        if (found === undefined)
+            groups.set(key, (found = { findings: [], entries: [] }));
+        return found;
+    };
+    for (const finding of findings)
+        group(effectGroup(finding)).findings.push(finding);
+    for (const entry of entries)
+        group(effectGroup(entry)).entries.push(entry);
+    return [...groups.values()].flatMap(({ findings: [finding, ...moreFindings], entries: [entry, ...moreEntries] }) => finding !== undefined && entry !== undefined && moreFindings.length === 0 && moreEntries.length === 0
+        ? [[finding, entry]]
+        : []);
+}
+/**
+ * Why a finding paired with `entry` is `changed` (§11 `changed`), before → after, in the table's order. The comparison
+ * is symmetric. Nothing else, such as mechanism, confidence or occurrences, makes a finding `changed`.
+ */
+function reasons(entry, finding, by) {
+    const changed = [];
+    if (by === 'attribution') {
+        changed.push({ reason: 'attribution', before: entry.attribution.key, after: finding.attribution.key });
+    }
+    if (entry.effect !== finding.effect)
+        changed.push({ reason: 'effect', before: entry.effect, after: finding.effect });
+    // A derived `locks` difference is a change `true` ↔ `false` only: `unknown` ↔ known is not.
+    const [before, after] = [entry.locks, finding.locks];
+    if (typeof before === 'boolean' && typeof after === 'boolean' && before !== after) {
+        changed.push({ reason: 'locks', before, after });
+    }
+    return changed;
+}
+/**
+ * A baseline entry no finding matched, `removed` or `unconfirmed`, reported with its readable context and no
+ * occurrences (§15 Findings).
+ */
+function unmatched({ fingerprint, target, surface, effect, locks, attribution }, baselineState, notes) {
+    return {
+        fingerprint,
+        targetKey: targetKey(target, effect),
+        target,
+        surface,
+        effect,
+        locks,
+        attribution,
+        reachability: null,
+        reachabilityBasis: null,
+        installContext: null,
+        confidence: null,
+        occurrences: [],
+        baselineState,
+        matchedBy: null,
+        changedReasons: [],
+        notes,
+    };
+}

package/dist/packages/compare/lib/catalog-notes.d.ts

@@ -0,0 +1,73 @@
+import type { CatalogChangelog, ChangeRecord, Realm, SerializedCatalog } from '../../../catalog.ts';
+import type { BaselineState } from '../../baseline/index.ts';
+/** A finding's target as the catalog notes read it. */
+type Targeted = {
+    target: {
+        realm: Realm;
+        name: string;
+        shadows?: string;
+    };
+};
+/**
+ * Sets `catalogStatus: retained` on each finding whose target, or the member it shadows, is a retained target of the
+ * catalog. It is information only.
+ */
+export declare function withCatalogStatus<F extends Targeted>(findings: readonly F[], catalog: SerializedCatalog): (F & {
+    catalogStatus?: 'retained';
+})[];
+/** A change record as `explainedBy` carries it: with the catalog version that made the change. */
+export type ExplainingRecord = ChangeRecord & {
+    catalogVersion: number;
+};
+/** What `explainedBy` reads of a compared finding. */
+export type Explainable = Targeted & {
+    effect: string;
+    attribution: {
+        key: string;
+    };
+    baselineState: BaselineState | null;
+    changedReasons: readonly {
+        reason: string;
+        before: unknown;
+        after: unknown;
+    }[];
+    notes: readonly {
+        kind: string;
+        before?: unknown;
+    }[];
+    occurrences: readonly {
+        evidence: {
+            pathRule?: string;
+        };
+    }[];
+};
+/**
+ * Sets `explainedBy` (§4 Catalog versions) on each delta that a change record between the baseline's catalog version
+ * and the scan's could explain, with those records in changelog order. Only `added`, `removed` and `changed` findings,
+ * and `existing` ones with a `rekeyed` note, are deltas: never `unconfirmed` or plain `existing`. A baseline from the
+ * same or a newer catalog version gives none.
+ *
+ * A record is about a delta when it names the delta's target, the member the target shadows on the current side (its
+ * `shadows`) or the baseline side (worked out from the current catalog, with the record's own targets, since a
+ * `removed` entry stores none), or a wildcard's holder. Then, by the §4 table:
+ * - `target` added / dropped: `added` / `removed`, and `changed` (`effect`) where the finding was or becomes an `add`
+ * - `protected-entry` gained / lost: `added` / `removed` that the entry covers (§12 Matching), under `--surface protected`
+ * - `member-data`: `added`, `removed`, and `changed` (`locks` or `effect`)
+ * - `holder` added, dropped or re-chained: `added` / `removed` of targets named on it, shadowing through it, or reached
+ *   through it (on the holder its prototype was or becomes)
+ * - `immutable-prototype`: `added` / `removed` of its `prototype-change`
+ * - `framework-path-rule`: `changed` (`attribution`), and a `rekeyed` pair, where an occurrence was named by the rule
+ *   or either side's key is a package the rule names
+ * - `url-normalization`: `changed` (`attribution`) between `url:` keys, and an `added` / `removed` pair: an `added` and
+ *   a `removed` finding of the same target and effect, both with `url:` keys
+ */
+export declare function withExplainedBy<F extends Explainable>(findings: readonly F[], input: {
+    catalog: SerializedCatalog;
+    changelog: CatalogChangelog;
+    /** The baseline's catalog version, or null without a baseline. */
+    baselineCatalogVersion: number | null;
+    surface: 'protected' | 'all';
+}): (F & {
+    explainedBy?: ExplainingRecord[];
+})[];
+export {};

package/dist/packages/compare/lib/catalog-notes.js

@@ -0,0 +1,224 @@
+// What the catalog says about each compared finding (§4 Catalog versions): `catalogStatus` for a retained target, and
+// `explainedBy`, the catalog changelog's records that could explain a delta.
+import { protectedSurface } from "../../findings/index.js";
+/**
+ * Sets `catalogStatus: retained` on each finding whose target, or the member it shadows, is a retained target of the
+ * catalog. It is information only.
+ */
+export function withCatalogStatus(findings, catalog) {
+    return findings.map((finding) => {
+        const { realm, name, shadows } = finding.target;
+        const retained = [name, shadows].some((member) => member !== undefined && catalog.targets[realm][member]?.catalogStatus === 'retained');
+        return retained ? { ...finding, catalogStatus: 'retained' } : finding;
+    });
+}
+/**
+ * Sets `explainedBy` (§4 Catalog versions) on each delta that a change record between the baseline's catalog version
+ * and the scan's could explain, with those records in changelog order. Only `added`, `removed` and `changed` findings,
+ * and `existing` ones with a `rekeyed` note, are deltas: never `unconfirmed` or plain `existing`. A baseline from the
+ * same or a newer catalog version gives none.
+ *
+ * A record is about a delta when it names the delta's target, the member the target shadows on the current side (its
+ * `shadows`) or the baseline side (worked out from the current catalog, with the record's own targets, since a
+ * `removed` entry stores none), or a wildcard's holder. Then, by the §4 table:
+ * - `target` added / dropped: `added` / `removed`, and `changed` (`effect`) where the finding was or becomes an `add`
+ * - `protected-entry` gained / lost: `added` / `removed` that the entry covers (§12 Matching), under `--surface protected`
+ * - `member-data`: `added`, `removed`, and `changed` (`locks` or `effect`)
+ * - `holder` added, dropped or re-chained: `added` / `removed` of targets named on it, shadowing through it, or reached
+ *   through it (on the holder its prototype was or becomes)
+ * - `immutable-prototype`: `added` / `removed` of its `prototype-change`
+ * - `framework-path-rule`: `changed` (`attribution`), and a `rekeyed` pair, where an occurrence was named by the rule
+ *   or either side's key is a package the rule names
+ * - `url-normalization`: `changed` (`attribution`) between `url:` keys, and an `added` / `removed` pair: an `added` and
+ *   a `removed` finding of the same target and effect, both with `url:` keys
+ */
+export function withExplainedBy(findings, input) {
+    const { catalog, changelog, baselineCatalogVersion: since } = input;
+    if (since === null)
+        return [...findings];
+    const current = catalog.metadata.catalogVersion;
+    const records = changelog.versions
+        .filter(({ catalogVersion }) => catalogVersion > since && catalogVersion <= current)
+        .flatMap(({ catalogVersion, changes }) => changes.map((change) => ({ catalogVersion, ...change })));
+    if (records.length === 0)
+        return [...findings];
+    const context = explainContext(catalog, records, input.surface, findings);
+    return findings.map((finding) => {
+        const delta = deltaOf(finding);
+        if (delta === undefined)
+            return finding;
+        const explainedBy = records.filter((record) => explains(record, finding, delta, context));
+        return explainedBy.length === 0 ? finding : { ...finding, explainedBy };
+    });
+}
+function deltaOf(finding) {
+    const { baselineState: state } = finding;
+    const rekeyed = finding.notes.some(({ kind }) => kind === 'rekeyed');
+    if (state === 'added' || state === 'removed' || state === 'changed' || (state === 'existing' && rekeyed)) {
+        return { state, reasons: new Set(finding.changedReasons.map(({ reason }) => reason)), rekeyed };
+    }
+    return undefined;
+}
+/** A finding's realm, target, effect and baseline state, which an `added` / `removed` pair matches on. */
+function pairKey({ target, effect }, state) {
+    return JSON.stringify([target.realm, target.name, effect, state]);
+}
+function explainContext(catalog, records, surface, findings) {
+    const recordTargets = new Map();
+    const droppedHolders = new Map();
+    const add = (map, realm, name) => {
+        let names = map.get(realm);
+        if (names === undefined)
+            map.set(realm, (names = new Set()));
+        names.add(name);
+    };
+    const covers = new Map();
+    for (const record of records) {
+        if (record.kind === 'target')
+            add(recordTargets, record.realm, record.name);
+        if (record.kind === 'holder' && record.change === 'dropped')
+            add(droppedHolders, record.realm, record.holder);
+        if (record.kind === 'protected-entry') {
+            covers.set(record, protectedSurface({ ...catalog, protectedSurface: { [record.surface]: [record.entry] } }));
+        }
+    }
+    const urlDeltas = new Set(findings
+        .filter(({ baselineState: state, attribution }) => (state === 'added' || state === 'removed') && attribution.key.startsWith('url:'))
+        .map((finding) => pairKey(finding, finding.baselineState)));
+    return { catalog, recordTargets, droppedHolders, surface, covers, urlDeltas };
+}
+/** The holder a target name is on in the current catalog, or on a holder the records drop. */
+function holderIn(name, realm, context) {
+    const holders = context.catalog.holders[realm];
+    const dropped = context.droppedHolders.get(realm);
+    const known = (holder) => Object.hasOwn(holders, holder) || dropped?.has(holder) === true;
+    const bracket = name.indexOf('["');
+    if (bracket >= 0)
+        return known(name.slice(0, bracket)) ? name.slice(0, bracket) : undefined;
+    for (let dot = name.lastIndexOf('.'); dot > 0; dot = name.lastIndexOf('.', dot - 1)) {
+        if (known(name.slice(0, dot)))
+            return name.slice(0, dot);
+    }
+    return undefined;
+}
+/**
+ * The catalog members a finding's target is about: its name, its `shadows`, and the member it shadows worked out from
+ * the current catalog: the first holder up its chain whose member of that key the catalog lists or a record adds or
+ * drops. A wildcard is about no member.
+ */
+function membersOf({ realm, name, shadows }, context) {
+    if (name.endsWith('*'))
+        return [];
+    const members = [name, ...(shadows === undefined ? [] : [shadows])];
+    const holder = holderIn(name, realm, context);
+    if (holder === undefined)
+        return members;
+    const key = name.slice(holder.length);
+    const holders = context.catalog.holders[realm];
+    const recorded = context.recordTargets.get(realm);
+    for (let at = holders[holder]?.proto ?? null; at !== null; at = holders[at]?.proto ?? null) {
+        const member = at + key;
+        if (recorded?.has(member) === true || Object.hasOwn(context.catalog.targets[realm], member)) {
+            if (!members.includes(member))
+                members.push(member);
+            break;
+        }
+    }
+    return members;
+}
+/** The holder of a wildcard target (`<holder>.*`, `<holder>.<prefix>*`), or undefined for any other target. */
+function wildcardHolder({ realm, name }, context) {
+    return name.endsWith('*') ? holderIn(name, realm, context) : undefined;
+}
+function explains(record, finding, delta, context) {
+    const { state, reasons } = delta;
+    const addOrRemove = state === 'added' || state === 'removed';
+    const { target } = finding;
+    switch (record.kind) {
+        case 'target': {
+            if (record.realm !== target.realm || !touches(record.name, finding, context))
+                return false;
+            if (state === (record.change === 'added' ? 'added' : 'removed'))
+                return true;
+            const effect = finding.changedReasons.find(({ reason }) => reason === 'effect');
+            return state === 'changed' && effect !== undefined && (effect.before === 'add' || effect.after === 'add');
+        }
+        case 'protected-entry': {
+            if (context.surface !== 'protected' || state !== (record.change === 'gained' ? 'added' : 'removed'))
+                return false;
+            const covers = context.covers.get(record);
+            const shadows = membersOf(target, context).slice(1);
+            return [undefined, ...shadows].some((shadow) => covers({ realm: target.realm, name: target.name, ...(shadow === undefined ? {} : { shadows: shadow }) }, finding.effect));
+        }
+        case 'member-data':
+            return (record.realm === target.realm &&
+                touches(record.name, finding, context) &&
+                (addOrRemove || (state === 'changed' && (reasons.has('locks') || reasons.has('effect')))));
+        case 'holder': {
+            if (record.realm !== target.realm || !addOrRemove)
+                return false;
+            const neighbours = [record.before?.proto, record.after?.proto].filter((proto) => typeof proto === 'string');
+            const wildcard = wildcardHolder(target, context);
+            if (wildcard !== undefined)
+                return wildcard === record.holder;
+            const members = membersOf(target, context);
+            const holders = members.map((member) => holderIn(member, target.realm, context));
+            if (holders.some((holder) => holder === record.holder || neighbours.includes(holder)))
+                return true;
+            return throughChain(holders[0], holders.slice(1), record.holder, target.realm, context);
+        }
+        case 'immutable-prototype':
+            return (record.realm === target.realm &&
+                addOrRemove &&
+                finding.effect === 'prototype-change' &&
+                target.name === `${record.holder}.[[Prototype]]`);
+        case 'framework-path-rule': {
+            if (!((state === 'changed' && reasons.has('attribution')) || delta.rekeyed))
+                return false;
+            if (finding.occurrences.some(({ evidence }) => evidence.pathRule === record.id))
+                return true;
+            const packages = [record.before?.package, record.after?.package].filter((name) => name !== undefined);
+            return keysOf(finding).some((key) => packages.some((name) => packagePattern(name).test(key)));
+        }
+        case 'url-normalization':
+            if (addOrRemove) {
+                const other = state === 'added' ? 'removed' : 'added';
+                return finding.attribution.key.startsWith('url:') && context.urlDeltas.has(pairKey(finding, other));
+            }
+            return state === 'changed' && reasons.has('attribution') && keysOf(finding).some((key) => key.startsWith('url:'));
+    }
+}
+/** Whether a record's target is one the finding is about, or a wildcard finding's holder is the target's holder. */
+function touches(name, finding, context) {
+    const wildcard = wildcardHolder(finding.target, context);
+    if (wildcard !== undefined)
+        return holderIn(name, finding.target.realm, context) === wildcard;
+    return membersOf(finding.target, context).includes(name);
+}
+/** Whether `holder` is on the chain from `from` up to any of `to`, the holders of the members the target shadows. */
+function throughChain(from, to, holder, realm, context) {
+    if (from === undefined)
+        return false;
+    const holders = context.catalog.holders[realm];
+    for (let at = holders[from]?.proto ?? null; at !== null && !to.includes(at); at = holders[at]?.proto ?? null) {
+        if (at === holder)
+            return true;
+    }
+    return false;
+}
+/** The attribution keys a finding had and has: its own, a `changed` (`attribution`) before, and a `rekeyed` before. */
+function keysOf(finding) {
+    const keys = [finding.attribution.key];
+    for (const { reason, before } of finding.changedReasons)
+        if (reason === 'attribution')
+            keys.push(String(before));
+    for (const { kind, before } of finding.notes)
+        if (kind === 'rekeyed' && Array.isArray(before))
+            keys.push(...before.map(String));
+    return keys;
+}
+/** The `pkg:` keys of the package a framework path rule names, where `<name>` stands for any captured value. */
+function packagePattern(template) {
+    const parts = template.split(/<[^>]+>/).map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+    return new RegExp(`^pkg:${parts.join('[^/]+')}$`);
+}