monkeypatchlist 0.0.0-stage → 0.1.0

package/dist/packages/discovery/lib/swept-code.js

@@ -0,0 +1,107 @@
+// What discovery reads from the code of a file only the sweep found (§2 Sweep, Realm): no reference says how it is
+// loaded or where it runs, so its source type, and the worker markers that make its assumed `window` realm uncertain,
+// come from its syntax. A file only a `<link rel=preload as=script>` names, or only preloads that disagree, and a
+// worker's script whose options can't be read statically take their source type the same way, and any file whose
+// realm is assumed has its worker markers read (§2 Discovery, Files that don't run as referenced, §13
+// `realm-uncertain`). Syntax only.
+import { visitorKeys } from 'oxc-parser';
+import { isNode, parseCode } from "./syntax.js";
+/** The events whose listeners on `self` mark a worker: a service worker's `install` and `fetch`, and `message`. */
+const workerEvents = new Set(['install', 'fetch', 'message']);
+/** The words every worker marker holds: code without them has none, and needs no parse to say so. */
+const markerWords = /\b(?:importScripts|addEventListener)\b/;
+/**
+ * The source type of a file no reference loads, and its worker markers in source order. Its source type comes from its
+ * syntax (`bySyntax`), and code that parses as neither has no markers.
+ */
+export function sweptCode(text) {
+    const mayHaveMarkers = markerWords.test(text);
+    const { sourceType, program } = bySyntax(text, mayHaveMarkers);
+    return { sourceType, markers: program === undefined ? [] : workerMarkers(program) };
+}
+/**
+ * The worker markers in code of the source type `sourceType`, in source order: none when it doesn't parse as that type.
+ */
+export function workerMarkersAs(text, sourceType) {
+    if (!markerWords.test(text))
+        return [];
+    const parsed = parseCode(text, sourceType);
+    return parsed === undefined ? [] : workerMarkers(parsed.program);
+}
+/**
+ * The source type of code no reference says how to load, as a sweep-only file's (§2 Sweep): a `module` when it parses
+ * only as a module, because it holds an `import` or `export` declaration, `import.meta` or a top-level `await`, and a
+ * `script` otherwise. Code that parses as neither is a `script`, which the resolver reports as a `parse-failure`.
+ */
+export function sourceTypeBySyntax(text) {
+    return bySyntax(text, false).sourceType;
+}
+/** The source type of code by its syntax, and its program as that type when `withProgram` asks for it and it parses. */
+function bySyntax(text, withProgram) {
+    // Only these words let a module parse accept what a script parse refuses; every other difference goes the other way.
+    const mayBeModule = /\b(?:import|export|await)\b/.test(text);
+    if (!mayBeModule && !withProgram)
+        return { sourceType: 'script' };
+    const script = parseCode(text, 'script');
+    const module = script === undefined && mayBeModule ? parseCode(text, 'module') : undefined;
+    const parsed = script?.program ?? module?.program;
+    const sourceType = module === undefined ? 'script' : 'module';
+    return withProgram && parsed !== undefined ? { sourceType, program: parsed } : { sourceType };
+}
+/**
+ * The worker markers in a program, in source order. `importScripts` counts only in top-level code, outside every
+ * function and class body; a listener on `self` counts anywhere, when its event is named by a literal.
+ */
+function workerMarkers(program) {
+    const markers = [];
+    const stack = [{ node: program, topLevel: true }];
+    for (let item = stack.pop(); item !== undefined; item = stack.pop()) {
+        const { node, topLevel } = item;
+        if (node.type === 'CallExpression') {
+            const marker = markerOf(node, topLevel);
+            if (marker !== undefined)
+                markers.push({ marker, start: node.start, end: node.end });
+        }
+        const nested = topLevel && !scopes.has(node.type);
+        for (const key of visitorKeys[node.type] ?? []) {
+            const value = node[key];
+            for (const child of Array.isArray(value) ? value : [value]) {
+                if (isNode(child))
+                    stack.push({ node: child, topLevel: nested });
+            }
+        }
+    }
+    return markers.sort((a, b) => a.start - b.start);
+}
+/** The nodes whose code does not run at the top level: functions, and class bodies. */
+const scopes = new Set(['FunctionDeclaration', 'FunctionExpression', 'ArrowFunctionExpression', 'ClassBody']);
+/** The worker marker a call is, if any. */
+function markerOf(call, topLevel) {
+    const callee = call['callee'];
+    if (callee.type === 'Identifier')
+        return topLevel && callee['name'] === 'importScripts' ? 'importScripts' : undefined;
+    if (callee.type !== 'MemberExpression')
+        return undefined;
+    const object = callee['object'];
+    if (object.type !== 'Identifier' || object['name'] !== 'self')
+        return undefined;
+    if (literal(callee['property'], callee['computed'] === true) !== 'addEventListener')
+        return undefined;
+    const [event] = call['arguments'];
+    const name = event === undefined ? undefined : literal(event, true);
+    return name !== undefined && workerEvents.has(name) ? name : undefined;
+}
+/**
+ * The string a property key or an argument spells: an identifier's name, when it is not computed, or a string literal
+ * or template literal without substitutions.
+ */
+function literal(node, computed) {
+    if (!computed)
+        return node.type === 'Identifier' ? node['name'] : undefined;
+    if (node.type === 'Literal' && typeof node['value'] === 'string')
+        return node['value'];
+    if (node.type === 'TemplateLiteral' && node['expressions'].length === 0) {
+        return node['quasis'][0]['value'].cooked ?? undefined;
+    }
+    return undefined;
+}

package/dist/packages/discovery/lib/syntax.d.ts

@@ -0,0 +1,17 @@
+import { parseSync } from 'oxc-parser';
+export interface Node {
+    type: string;
+    start: number;
+    end: number;
+    [key: string]: unknown;
+}
+/**
+ * Parses `text` with `sourceType`: its program and module record, or undefined when it doesn't parse, as then nothing
+ * of it runs. That includes a classic script with an `import` or `export` declaration, which oxc reports only among the
+ * semantic errors §5's options leave out.
+ */
+export declare function parseCode(text: string, sourceType: 'script' | 'module'): {
+    program: Node;
+    module: ReturnType<typeof parseSync>['module'];
+} | undefined;
+export declare function isNode(value: unknown): value is Node;

package/dist/packages/discovery/lib/syntax.js

@@ -0,0 +1,39 @@
+// The oxc parse discovery reads syntax from (§5 Parsing and scope, §19 Discovery): the references in a script or module
+// (`requests.ts`), and the source type and worker markers of a file only the sweep found (`swept-code.ts`). Syntax only.
+import { parseSync, rawTransferSupported } from 'oxc-parser';
+/** Raw transfer where the platform supports it (§5 Parsing and scope). The option is not in oxc's typings. */
+const rawTransfer = rawTransferSupported();
+/** The parser options §5 fixes, with the `sourceType` always explicit, as the resolver parses. */
+const parserOptions = (sourceType) => ({
+    lang: 'js',
+    sourceType,
+    range: true,
+    preserveParens: false,
+    experimentalRawTransfer: rawTransfer,
+});
+/** The import and export declarations, which a classic script cannot hold. */
+const moduleDeclarations = new Set([
+    'ImportDeclaration',
+    'ExportAllDeclaration',
+    'ExportNamedDeclaration',
+    'ExportDefaultDeclaration',
+]);
+/**
+ * Parses `text` with `sourceType`: its program and module record, or undefined when it doesn't parse, as then nothing
+ * of it runs. That includes a classic script with an `import` or `export` declaration, which oxc reports only among the
+ * semantic errors §5's options leave out.
+ */
+export function parseCode(text, sourceType) {
+    const parsed = parseSync('artifact.js', text, parserOptions(sourceType));
+    if (parsed.errors.length > 0)
+        return undefined;
+    const program = parsed.program;
+    // Import and export declarations can only be top-level statements.
+    if (sourceType === 'script' && program['body'].some(({ type }) => moduleDeclarations.has(type))) {
+        return undefined;
+    }
+    return { program, module: parsed.module };
+}
+export function isNode(value) {
+    return typeof value === 'object' && value !== null && typeof value.type === 'string';
+}

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

@@ -0,0 +1,106 @@
+import { type SerializedCatalog, type Surface } from '../../catalog.ts';
+import type { Effect, IneffectiveReason, InstallContext, Limitation, Locks, Reachability, ReachabilityBasis, Target } from '../analysis/index.ts';
+import { type AttributedIneffectiveWrite, type AttributedOccurrence, type Attribution, type PackageVersion } from '../attribution/index.ts';
+import { type Confidence } from '../confidence/index.ts';
+import type { SurfaceScope } from '../config/index.ts';
+import { protectedSurface, type IsProtected, type ScopeTarget } from './lib/scope.ts';
+export { protectedSurface, type IsProtected, type ScopeTarget };
+/** The fingerprint scheme version (§11), recorded in the report's `tool` block and the baseline header. */
+export declare const fingerprintScheme = 1;
+/** An occurrence of a finding: everything but the finding-level fields. */
+export type Occurrence = Omit<AttributedOccurrence, 'target' | 'effect' | 'locks' | 'attribution'>;
+/** One platform mutation, identified by its fingerprint, with every site that makes it (§8). */
+export interface Finding {
+    /** `(realm, target, effect, attribution key)` as a readable string: `window|Window.fetch|wrap|pkg:@sentry/core`. */
+    fingerprint: string;
+    /** `(realm, target, effect)`, written as the fingerprint is: `window|Window.fetch|wrap`. */
+    targetKey: string;
+    target: Target;
+    surface: Surface;
+    effect: Effect;
+    /** The most-locking occurrence's (§8): `true` over `unknown` over `false`. */
+    locks: Locks;
+    attribution: Attribution;
+    /**
+     * The union of the occurrences' introducing dependencies (§10 Record), sorted: absent when none of them has any.
+     * Evidence only: never in the fingerprint, the baseline or `changed`.
+     */
+    introducedBy?: string[];
+    /** The most-reaching occurrence's (§7, §8): `unconditional` over `conditional` over `unknown` over absence. */
+    reachability: Reachability;
+    /**
+     * The basis of the occurrences that give its reachability (§7): `call-path` when any of them is `call-path`, else
+     * `creation-site`.
+     */
+    reachabilityBasis: ReachabilityBasis;
+    /** `load` if any occurrence is `load`, else `deferred` (§7 Install context, §11). */
+    installContext: InstallContext;
+    /** The highest level per dimension across the occurrences (§9). */
+    confidence: Confidence;
+    occurrences: Occurrence[];
+}
+/**
+ * The `packages` map (§10 Version, §11 Baseline): each containing package of a finding, by name in code-unit order,
+ * with its strong version (store path or lockfile) and that version's source. Only the occurrences of findings keyed on
+ * the package count. A name with no strong version gets no entry, and nor does one with more than one strong version in
+ * the scan. One version from two strong sources takes the stronger.
+ */
+export declare function packageVersions(findings: readonly Pick<Finding, 'attribution' | 'occurrences'>[]): Record<string, PackageVersion>;
+/**
+ * Merges occurrences into findings by fingerprint, and rolls their confidence (§9), `locks` (§8), reachability and install context (§7)
+ * up. Findings are sorted by fingerprint, and each finding's occurrences by artifact URL, then position, then artifact
+ * hash: one key URL reached through two fetched URLs is an artifact of each (§11).
+ */
+export declare function buildFindings(occurrences: readonly AttributedOccurrence[], catalog: SerializedCatalog): Finding[];
+/** An occurrence of an ineffective write: everything but the record-level fields. */
+export type IneffectiveOccurrence = Omit<AttributedIneffectiveWrite, 'target' | 'reason'>;
+/**
+ * The ineffective writes to one target for one reason (§3 Record): never a finding, so no fingerprint, baseline state
+ * or effect of its own. Each occurrence carries its intended effect, mechanism, strictness and `throws`.
+ */
+export interface IneffectiveWriteRecord {
+    target: Target;
+    /** The target's surface, as a finding's (§12): records follow `--surface` as findings do. */
+    surface: Surface;
+    reason: IneffectiveReason;
+    occurrences: IneffectiveOccurrence[];
+}
+/**
+ * Groups the occurrences of ineffective writes per `(realm, target, reason)` (§3 Record). Records are sorted by realm,
+ * target and reason, and each record's occurrences by artifact URL, then position, then artifact hash.
+ */
+export declare function buildIneffectiveWrites(writes: readonly AttributedIneffectiveWrite[], catalog: SerializedCatalog): IneffectiveWriteRecord[];
+/** The target key `(realm, target, effect)` (§11), written as the fingerprint is: `window|Window.fetch|wrap`. */
+export declare function targetKey(target: Pick<Target, 'realm' | 'name'>, effect: Effect): string;
+/** Orders strings by UTF-16 code unit, independent of locale. */
+export declare function compareStrings(a: string, b: string): number;
+/** How many findings a `protected` scan leaves out, per surface (§12). Every surface is listed, in `surfaces` order. */
+export type OutOfScopeBySurface = Record<Surface, number>;
+/**
+ * A record that may name the targets it could be about (§5 Partially resolved writes): an `unresolved-holder` record's
+ * candidate targets, which analysis returns as data for this stage to filter. Its `detail` ends with their names,
+ * joined by `, `.
+ */
+export type ScopedLimitation<R extends Pick<Limitation, 'detail'>> = R & {
+    candidates?: readonly ScopeTarget[];
+};
+/**
+ * Applies `--surface` (§12) to what a scan reports. `all` keeps everything. `protected` keeps:
+ * - the findings the protected surface covers, and counts the others per surface
+ * - the ineffective-write records it covers, matched as findings are, through `shadows` (§3 Record): a record is kept
+ *   when its target is covered with the intended effect of any of its occurrences
+ * - each record with candidate targets (`unresolved-holder`) when at least one candidate is covered, with its `detail`
+ *   listing only the covered ones
+ *
+ * A record's `candidates` never cross into the output.
+ */
+export declare function applySurface<R extends Pick<Limitation, 'detail'>>(input: {
+    findings: readonly Finding[];
+    ineffectiveWrites: readonly IneffectiveWriteRecord[];
+    limitations: readonly ScopedLimitation<R>[];
+}, scope: SurfaceScope, catalog: SerializedCatalog): {
+    findings: Finding[];
+    outOfScopeBySurface: OutOfScopeBySurface;
+    ineffectiveWrites: IneffectiveWriteRecord[];
+    limitations: R[];
+};

package/dist/packages/findings/index.js

@@ -0,0 +1,254 @@
+// Findings (§19, module 6): computes each occurrence's fingerprint and target key (§11), and merges occurrences into
+// findings by fingerprint. It knows nothing of the baseline.
+import { ecmascriptSpecs, surfaces } from "../../catalog.js";
+import { strongVersionSources, versionSources, } from "../attribution/index.js";
+import { rollUp } from "../confidence/index.js";
+import { holderOf, protectedSurface } from "./lib/scope.js";
+export { protectedSurface };
+/** The fingerprint scheme version (§11), recorded in the report's `tool` block and the baseline header. */
+export const fingerprintScheme = 1;
+/**
+ * The `packages` map (§10 Version, §11 Baseline): each containing package of a finding, by name in code-unit order,
+ * with its strong version (store path or lockfile) and that version's source. Only the occurrences of findings keyed on
+ * the package count. A name with no strong version gets no entry, and nor does one with more than one strong version in
+ * the scan. One version from two strong sources takes the stronger.
+ */
+export function packageVersions(findings) {
+    const seen = new Map();
+    for (const { attribution, occurrences } of findings) {
+        const name = attribution.package;
+        if (name === undefined)
+            continue;
+        let versions = seen.get(name);
+        if (versions === undefined)
+            seen.set(name, (versions = []));
+        for (const { evidence } of occurrences) {
+            if (evidence.version !== undefined && strongVersionSources.has(evidence.version.versionSource)) {
+                versions.push(evidence.version);
+            }
+        }
+    }
+    const packages = [];
+    for (const [name, versions] of seen) {
+        if (new Set(versions.map(({ version }) => version)).size !== 1)
+            continue;
+        const strongest = versions.reduce((a, b) => versionSources.indexOf(b.versionSource) < versionSources.indexOf(a.versionSource) ? b : a);
+        packages.push([name, { version: strongest.version, versionSource: strongest.versionSource }]);
+    }
+    return Object.fromEntries(packages.sort(([a], [b]) => compareStrings(a, b)));
+}
+/**
+ * Merges occurrences into findings by fingerprint, and rolls their confidence (§9), `locks` (§8), reachability and install context (§7)
+ * up. Findings are sorted by fingerprint, and each finding's occurrences by artifact URL, then position, then artifact
+ * hash: one key URL reached through two fetched URLs is an artifact of each (§11).
+ */
+export function buildFindings(occurrences, catalog) {
+    const merged = new Map();
+    const surfaces = surfaceLookup(catalog);
+    for (const { target, effect, locks, attribution, ...occurrence } of occurrences) {
+        const key = targetKey(target, effect);
+        const fingerprint = `${key}|${attribution.key}`;
+        let finding = merged.get(fingerprint);
+        if (finding === undefined) {
+            const surface = surfaces.of(target);
+            finding = { fingerprint, targetKey: key, target, surface, effect, locks, attribution, occurrences: [] };
+            merged.set(fingerprint, finding);
+        }
+        finding.locks = mostLocking(finding.locks, locks);
+        finding.occurrences.push(occurrence);
+    }
+    const findings = [...merged.values()].map(({ occurrences, ...finding }) => {
+        occurrences.sort(byArtifactAndPosition);
+        const reachability = occurrences.map((occurrence) => occurrence.reachability).reduce(mostReaching);
+        const giving = occurrences.filter((occurrence) => occurrence.reachability === reachability);
+        const reachabilityBasis = giving.some((occurrence) => occurrence.reachabilityBasis === 'call-path')
+            ? 'call-path'
+            : 'creation-site';
+        const installContext = occurrences.some((occurrence) => occurrence.installContext === 'load') ? 'load' : 'deferred';
+        const confidence = rollUp(occurrences.map((occurrence) => occurrence.confidence));
+        const attribution = withWorkspace(withVendoredBy(finding.attribution, occurrences), occurrences);
+        const introducers = occurrences.flatMap(({ introducedBy }) => (introducedBy === undefined ? [] : [introducedBy]));
+        const introducedBy = introducers.length === 0 ? {} : { introducedBy: [...new Set(introducers.flat())].sort(compareStrings) };
+        return { ...finding, attribution, ...introducedBy, reachability, reachabilityBasis, installContext, confidence, occurrences };
+    });
+    return findings.sort((a, b) => compareStrings(a.fingerprint, b.fingerprint));
+}
+/**
+ * A finding's attribution, with `vendoredBy` when its code is vendored (§10 Provenance, §15): when every occurrence is
+ * vendored by one package. A copy that isn't vendored, or two vendoring packages, leave it to the occurrences' evidence.
+ * Evidence only: the fingerprint is computed before it, and neither the baseline nor `changed` reads it.
+ */
+function withVendoredBy(attribution, occurrences) {
+    const by = new Set(occurrences.map(({ evidence }) => evidence.vendoredBy));
+    const [only] = by;
+    return by.size === 1 && only !== undefined && attribution.provenance === 'bundled-dependency'
+        ? { ...attribution, vendoredBy: only }
+        : attribution;
+}
+/**
+ * A finding's attribution, with `workspace` when its first-party code is in one lockfile workspace (§10 Provenance,
+ * §15): when every occurrence names that workspace. Evidence only, as `vendoredBy` is.
+ */
+function withWorkspace(attribution, occurrences) {
+    const workspaces = new Set(occurrences.map(({ evidence }) => evidence.workspace));
+    const [only] = workspaces;
+    return workspaces.size === 1 && only !== undefined && attribution.provenance === 'first-party'
+        ? { ...attribution, workspace: only }
+        : attribution;
+}
+/**
+ * Groups the occurrences of ineffective writes per `(realm, target, reason)` (§3 Record). Records are sorted by realm,
+ * target and reason, and each record's occurrences by artifact URL, then position, then artifact hash.
+ */
+export function buildIneffectiveWrites(writes, catalog) {
+    const grouped = new Map();
+    const surfaces = surfaceLookup(catalog);
+    for (const { target, reason, ...occurrence } of writes) {
+        const key = `${target.realm}|${target.name}|${reason}`;
+        let record = grouped.get(key);
+        if (record === undefined) {
+            record = { target, surface: surfaces.of(target), reason, occurrences: [] };
+            grouped.set(key, record);
+        }
+        record.occurrences.push(occurrence);
+    }
+    return [...grouped.entries()]
+        .sort(([a], [b]) => compareStrings(a, b))
+        .map(([, record]) => {
+        record.occurrences.sort(byArtifactAndPosition);
+        return record;
+    });
+}
+/** The `locks` values from the least locking to the most. */
+const lockingOrder = [false, 'unknown', true];
+/**
+ * The more locking of two occurrences' `locks` (§8): `true` over `unknown` over `false`. One site that locks the target
+ * locks it when it runs, and one the analyzer can't tell about leaves it unable to say the target stays unlocked.
+ */
+function mostLocking(a, b) {
+    return lockingOrder.indexOf(a) >= lockingOrder.indexOf(b) ? a : b;
+}
+/** The reachability values from the least reaching to the most (§7 Combining guards, across alternatives). */
+const reachingOrder = ['guarded-native-absence', 'unknown', 'conditional', 'unconditional'];
+/** The more reaching of two occurrences' reachability (§7): a finding reports the most-reaching over its occurrences. */
+function mostReaching(a, b) {
+    return reachingOrder.indexOf(a) >= reachingOrder.indexOf(b) ? a : b;
+}
+/** The target key `(realm, target, effect)` (§11), written as the fingerprint is: `window|Window.fetch|wrap`. */
+export function targetKey(target, effect) {
+    return `${target.realm}|${target.name}|${effect}`;
+}
+/**
+ * A target's surface (§12 Surfaces and data): a catalog member's own, and for a shadowing target, which is derived and
+ * not catalogued (ADR 0002), the member's it shadows. For a target the catalog doesn't list (an `add`, or a holder's
+ * `prototype-change`), it is that of its holder's owner in the owner → surface map. An ECMAScript owner is always
+ * `ECMAScript`, and an owner the map doesn't name is `other`.
+ */
+function surfaceLookup(catalog) {
+    // An ECMAScript owner is one whose every member ECMA-262, ECMA-402, an ES addition or an engine extension defines.
+    // `Window` is not: it has Web IDL members as well as ECMAScript globals.
+    const specs = ecmascriptSpecs(catalog);
+    const ecmascriptOwners = new Map();
+    const ecmascript = (realm) => {
+        let owners = ecmascriptOwners.get(realm);
+        if (owners === undefined) {
+            const idl = new Set();
+            const es = new Set();
+            for (const { owner, spec } of Object.values(catalog.targets[realm]))
+                (specs.has(spec) ? es : idl).add(owner);
+            owners = new Set([...es].filter((owner) => !idl.has(owner)));
+            ecmascriptOwners.set(realm, owners);
+        }
+        return owners;
+    };
+    return {
+        of({ realm, name, shadows }) {
+            const targets = catalog.targets[realm];
+            const catalogued = shadows ?? name;
+            if (Object.hasOwn(targets, catalogued))
+                return targets[catalogued].surface;
+            if (shadows !== undefined)
+                throw new Error(`an occurrence shadows ${shadows}, which the ${realm} catalog lacks`);
+            const holders = catalog.holders[realm];
+            const holderName = holderOf(name, holders);
+            if (holderName === undefined) {
+                throw new Error(`an occurrence names ${name}, which is on no holder of the ${realm} catalog`);
+            }
+            const { owner } = holders[holderName];
+            if (Object.hasOwn(catalog.surfaceMap.owners, owner))
+                return catalog.surfaceMap.owners[owner];
+            return ecmascript(realm).has(owner) ? 'ECMAScript' : 'other';
+        },
+    };
+}
+/** Orders strings by UTF-16 code unit, independent of locale. */
+export function compareStrings(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * Applies `--surface` (§12) to what a scan reports. `all` keeps everything. `protected` keeps:
+ * - the findings the protected surface covers, and counts the others per surface
+ * - the ineffective-write records it covers, matched as findings are, through `shadows` (§3 Record): a record is kept
+ *   when its target is covered with the intended effect of any of its occurrences
+ * - each record with candidate targets (`unresolved-holder`) when at least one candidate is covered, with its `detail`
+ *   listing only the covered ones
+ *
+ * A record's `candidates` never cross into the output.
+ */
+export function applySurface(input, scope, catalog) {
+    const covers = scope === 'all' ? () => true : protectedSurface(catalog);
+    const outOfScopeBySurface = Object.fromEntries(surfaces.map((surface) => [surface, 0]));
+    const findings = input.findings.flatMap((finding) => {
+        const covered = covers(narrowed(finding.target, finding.occurrences), finding.effect);
+        if (!covered)
+            outOfScopeBySurface[finding.surface]++;
+        return covered ? [withoutMatches(finding)] : [];
+    });
+    const ineffectiveWrites = input.ineffectiveWrites.flatMap((record) => record.occurrences.some(({ effect }) => covers(narrowed(record.target, record.occurrences), effect))
+        ? [withoutMatches(record)]
+        : []);
+    const limitations = input.limitations.flatMap(({ candidates, ...rest }) => {
+        const record = rest;
+        if (candidates === undefined)
+            return [record];
+        const kept = candidates.filter((candidate) => covers(candidate, ''));
+        if (kept.length === 0)
+            return [];
+        if (kept.length === candidates.length)
+            return [record];
+        const listed = candidates.map(({ name }) => name).join(', ');
+        if (!record.detail.endsWith(listed))
+            throw new Error(`a record's detail doesn't end with its candidates: ${record.detail}`);
+        const detail = record.detail.slice(0, record.detail.length - listed.length) + kept.map(({ name }) => name).join(', ');
+        return [{ ...record, detail }];
+    });
+    return { findings, outOfScopeBySurface, ineffectiveWrites, limitations };
+}
+/**
+ * A target as the surface sees it (§12): a wildcard each of whose occurrences a candidate set narrows matches the
+ * members they match, and any other the members its name gives.
+ */
+function narrowed(target, occurrences) {
+    if (!target.name.endsWith('.*') || occurrences.length === 0)
+        return target;
+    if (occurrences.some(({ matches }) => matches === undefined))
+        return target;
+    return { ...target, matches: [...new Set(occurrences.flatMap(({ matches }) => matches ?? []))] };
+}
+/** A finding or record whose occurrences carry no matched members, which never cross into the output. */
+function withoutMatches(found) {
+    if (!found.target.name.endsWith('.*'))
+        return found;
+    const occurrences = found.occurrences.map((occurrence) => {
+        const copy = { ...occurrence };
+        delete copy.matches;
+        return copy;
+    });
+    return { ...found, occurrences };
+}
+/** Orders occurrences by artifact URL, then position, then artifact hash. */
+function byArtifactAndPosition(a, b) {
+    return (compareStrings(a.artifact.url, b.artifact.url) ||
+        a.generated.start - b.generated.start ||
+        compareStrings(a.artifact.hash, b.artifact.hash));
+}

package/dist/packages/findings/lib/scope.d.ts

@@ -0,0 +1,38 @@
+import type { Realm, SerializedCatalog } from '../../../catalog.ts';
+/** A target as the protected surface sees it: its realm, its name, and the member it shadows (ADR 0002). */
+export interface ScopeTarget {
+    realm: Realm;
+    name: string;
+    shadows?: string;
+    /**
+     * For a wildcard narrowed to a candidate set (§5), the catalog targets it matches: it is covered when one of
+     * them is.
+     */
+    matches?: readonly string[];
+}
+/** Whether the protected surface covers a target with this effect. */
+export type IsProtected = (target: ScopeTarget, effect: string) => boolean;
+/**
+ * The protected surface of a catalog (§12 Matching). Entries are keyed on (interface, member), independent of realm
+ * and holder. A target is covered when:
+ * - it is a catalog target an entry names: a member entry's member, in every realm and on each interface that
+ *   includes its mixin, and its worker-realm equivalent; a whole entry's global binding and the static, prototype and
+ *   namespace members the catalog lists for it, without `onX`
+ * - it shadows one of those, on whatever holder it lands (`history.pushState`, `XMLHttpRequest.prototype.toString`)
+ * - it is an `add` of a named member, whatever its key, to a whole entry's constructor, prototype or namespace
+ * - it is a `prototype-change` of a whole entry's prototype or namespace (never of its constructor), or of a covered
+ *   singleton
+ * - it is a wildcard over native members (`<holder>.*`) of a holder a covered target sits on, or of a covered singleton;
+ *   one a candidate set narrows when a member it matches is a covered target
+ *
+ * A singleton is covered when its interface or namespace is a whole entry (`history`, `localStorage`, `crypto.subtle`,
+ * `navigator.serviceWorker`), or when an entry names a member of its interface (`navigator`, through
+ * `Navigator.sendBeacon`). A pattern wildcard of non-native adds (`<holder>.<prefix>*`) is never covered.
+ */
+export declare function protectedSurface(catalog: SerializedCatalog): IsProtected;
+/**
+ * The holder a target is on (§4 Property keys): the part before a member written in JSON-quoted brackets
+ * (`Array["prototype.map"]`), and otherwise the longest holder the name continues with a dot, since a canonical numeric
+ * member keeps the dot form (`Array.prototype.1.5`).
+ */
+export declare function holderOf(name: string, holders: SerializedCatalog['holders'][Realm]): string | undefined;