monkeypatchlist 0.0.0-stage → 0.1.0

package/dist/packages/findings/lib/scope.js

@@ -0,0 +1,110 @@
+// The protected surface (§12 Matching): which targets the protected-surface list covers, in each realm.
+/** The suffix of a `prototype-change` target's name: `<holder>.[[Prototype]]`. */
+const prototypeSuffix = '.[[Prototype]]';
+/**
+ * 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 function protectedSurface(catalog) {
+    const byRealm = new Map();
+    const coveredIn = (realm) => {
+        let covered = byRealm.get(realm);
+        if (covered === undefined) {
+            covered = cover(catalog, realm);
+            byRealm.set(realm, covered);
+        }
+        return covered;
+    };
+    return ({ realm, name, shadows, matches }, effect) => {
+        const covered = coveredIn(realm);
+        if (name.endsWith('*')) {
+            if (!name.endsWith('.*'))
+                return false;
+            if (matches !== undefined)
+                return matches.some((match) => covered.targets.has(match));
+            const holder = name.slice(0, -'.*'.length);
+            return covered.singletons.get(holder) ?? covered.holdersOfTargets.has(holder);
+        }
+        if (covered.targets.has(name))
+            return true;
+        if (shadows !== undefined && covered.targets.has(shadows))
+            return true;
+        if (effect === 'add') {
+            const holder = holderOf(name, catalog.holders[realm]);
+            return holder !== undefined && covered.addHolders.has(holder);
+        }
+        if (effect === 'prototype-change' && name.endsWith(prototypeSuffix)) {
+            return covered.prototypeHolders.has(name.slice(0, -prototypeSuffix.length));
+        }
+        return false;
+    };
+}
+function cover(catalog, realm) {
+    const targets = new Set();
+    const whole = new Set();
+    for (const entries of Object.values(catalog.protectedSurface)) {
+        for (const entry of entries ?? []) {
+            for (const target of entry.targets[realm])
+                targets.add(target);
+            if (entry.member === undefined)
+                whole.add(entry.interface);
+        }
+    }
+    const holders = catalog.holders[realm];
+    const catalogTargets = catalog.targets[realm];
+    const holdersOfTargets = new Set();
+    const coveredOwners = new Set();
+    for (const target of targets) {
+        const holder = holderOf(target, holders);
+        if (holder !== undefined)
+            holdersOfTargets.add(holder);
+        coveredOwners.add(catalogTargets[target].owner);
+    }
+    const addHolders = new Set();
+    const prototypeHolders = new Set();
+    for (const [name, { kind, owner }] of Object.entries(holders)) {
+        if (!whole.has(owner))
+            continue;
+        if (kind === 'constructor' || kind === 'prototype' || kind === 'namespace')
+            addHolders.add(name);
+        if (kind === 'prototype' || kind === 'namespace')
+            prototypeHolders.add(name);
+    }
+    const singletons = new Map();
+    for (const [path, singleton] of Object.entries(catalog.singletons[realm])) {
+        const owner = 'interface' in singleton ? singleton.interface : singleton.namespace;
+        const covered = whole.has(owner) || coveredOwners.has(owner);
+        singletons.set(path, covered);
+        if (covered)
+            prototypeHolders.add(path);
+    }
+    return { targets, holdersOfTargets, addHolders, prototypeHolders, singletons };
+}
+/**
+ * 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 function holderOf(name, holders) {
+    const bracket = name.indexOf('["');
+    if (bracket >= 0)
+        return Object.hasOwn(holders, name.slice(0, bracket)) ? name.slice(0, bracket) : undefined;
+    for (let dot = name.lastIndexOf('.'); dot > 0; dot = name.lastIndexOf('.', dot - 1)) {
+        if (Object.hasOwn(holders, name.slice(0, dot)))
+            return name.slice(0, dot);
+    }
+    return undefined;
+}

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

@@ -0,0 +1,2 @@
+export { defaultMemoryBudget, inProcessRunner, workerRunner, type GroupRunner, type WorkerRunnerOptions, } from './lib/runner.ts';
+export { schedule, type ScheduleOptions } from './lib/schedule.ts';

package/dist/packages/parallel/index.js

@@ -0,0 +1,5 @@
+// Parallel link groups (§18 Parallelism): link groups run one after another by default, and an internal worker-count
+// setting lets them run in worker threads, each only while the estimated peak heaps of the groups running fit the
+// memory budget. Results merge in group order. Everything that crosses a worker boundary is plain JSON (§19).
+export { defaultMemoryBudget, inProcessRunner, workerRunner, } from "./lib/runner.js";
+export { schedule } from "./lib/schedule.js";

package/dist/packages/parallel/lib/protocol.d.ts

@@ -0,0 +1,15 @@
+/** A worker's setup: the catalog and the budget, each as JSON. */
+export interface Setup {
+    catalog: string;
+    budget: string;
+}
+/** A job for a worker: one `GroupJob`, as JSON. */
+export interface Request {
+    job: string;
+}
+/** A worker's answer: the group's `AnalyzeGroupOutput` as JSON, or the message of the error analysing it threw. */
+export type Reply = {
+    output: string;
+} | {
+    error: string;
+};

package/dist/packages/parallel/lib/protocol.js

@@ -0,0 +1,2 @@
+// What crosses the worker boundary (§19 Serializable seams): JSON text only.
+export {};

package/dist/packages/parallel/lib/runner.d.ts

@@ -0,0 +1,36 @@
+import type { SerializedCatalog } from '../../../catalog.ts';
+import type { AnalyzeGroupOutput, Budget, Resolver } from '../../analysis/index.ts';
+import { type GroupJob } from '../../analysis/job.ts';
+/**
+ * Runs a scan's link groups. `proceed()` is asked before each group starts, in group order: once it says no, no
+ * further group runs, and each group not run gives `undefined`. Results come back in group order.
+ */
+export interface GroupRunner {
+    run(jobs: readonly GroupJob[], proceed: () => boolean): Promise<(AnalyzeGroupOutput | undefined)[]>;
+}
+/**
+ * The estimated peak heap per source byte of a link group (§18 Target: at most 400× per source byte, so that a 5 MB
+ * group fits in 2 GB).
+ */
+export declare const heapPerSourceByte = 400;
+/**
+ * The memory budget a parallel run's estimated peak heaps share by default, in bytes: half of the 8 GB runner the cost
+ * target is set on (§18), which leaves room for the main thread's own heap, the source store and the catalog copies.
+ */
+export declare const defaultMemoryBudget: number;
+/** Runs the groups in process, one after another, with `resolver`. */
+export declare function inProcessRunner(resolver: Resolver, catalog: SerializedCatalog, budget: Budget): GroupRunner;
+export interface WorkerRunnerOptions {
+    /** How many worker threads may analyze groups at once. */
+    workers: number;
+    /** The memory, in bytes, the estimated peak heaps of the groups running must fit in. */
+    memoryBudget: number;
+    catalog: SerializedCatalog;
+    budget: Budget;
+}
+/**
+ * Runs the groups in up to `workers` worker threads, each with the shipped JS resolver, while their estimated peak heaps
+ * fit `memoryBudget`. Each job and each result crosses the boundary as JSON text. Workers start when a run needs them,
+ * and stop when it ends.
+ */
+export declare function workerRunner({ workers, memoryBudget, catalog, budget }: WorkerRunnerOptions): GroupRunner;

package/dist/packages/parallel/lib/runner.js

@@ -0,0 +1,96 @@
+// Group runners (§18 Parallelism): in process, one group after another, or in worker threads under the memory budget.
+import { Worker } from 'node:worker_threads';
+import { analyzeJob, jobBytes } from "../../analysis/job.js";
+import { schedule } from "./schedule.js";
+/**
+ * The estimated peak heap per source byte of a link group (§18 Target: at most 400× per source byte, so that a 5 MB
+ * group fits in 2 GB).
+ */
+export const heapPerSourceByte = 400;
+/**
+ * The memory budget a parallel run's estimated peak heaps share by default, in bytes: half of the 8 GB runner the cost
+ * target is set on (§18), which leaves room for the main thread's own heap, the source store and the catalog copies.
+ */
+export const defaultMemoryBudget = 4 * 1024 ** 3;
+/** Runs the groups in process, one after another, with `resolver`. */
+export function inProcessRunner(resolver, catalog, budget) {
+    return {
+        async run(jobs, proceed) {
+            const results = [];
+            for (const job of jobs) {
+                if (!proceed())
+                    break;
+                results.push(analyzeJob(resolver, job, catalog, budget));
+            }
+            return jobs.map((_, index) => results[index]);
+        },
+    };
+}
+/**
+ * Runs the groups in up to `workers` worker threads, each with the shipped JS resolver, while their estimated peak heaps
+ * fit `memoryBudget`. Each job and each result crosses the boundary as JSON text. Workers start when a run needs them,
+ * and stop when it ends.
+ */
+export function workerRunner({ workers, memoryBudget, catalog, budget }) {
+    return {
+        async run(jobs, proceed) {
+            const setup = { catalog: JSON.stringify(catalog), budget: JSON.stringify(budget) };
+            const idle = [];
+            const all = [];
+            const take = () => {
+                const worker = idle.pop();
+                if (worker !== undefined)
+                    return worker;
+                const started = new Worker(workerUrl(), { workerData: setup });
+                // A worker that exits while idle is never handed another job, which would never be answered.
+                started.on('exit', () => {
+                    const at = idle.indexOf(started);
+                    if (at !== -1)
+                        idle.splice(at, 1);
+                });
+                all.push(started);
+                return started;
+            };
+            const analyze = (index) => new Promise((resolve, reject) => {
+                const worker = take();
+                const done = () => {
+                    worker.off('message', message);
+                    worker.off('error', error);
+                    worker.off('exit', exit);
+                };
+                const message = (reply) => {
+                    done();
+                    idle.push(worker);
+                    if ('error' in reply)
+                        reject(new Error(`link group ${jobs[index].entry.url} failed: ${reply.error}`));
+                    else
+                        resolve(JSON.parse(reply.output));
+                };
+                const error = (cause) => {
+                    done();
+                    reject(cause instanceof Error ? cause : new Error(String(cause)));
+                };
+                const exit = (code) => {
+                    done();
+                    reject(new Error(`a link-group worker exited with code ${code}`));
+                };
+                worker.on('message', message);
+                worker.on('error', error);
+                worker.on('exit', exit);
+                const request = { job: JSON.stringify(jobs[index]) };
+                worker.postMessage(request);
+            });
+            try {
+                const tasks = jobs.map((job) => ({ heap: heapPerSourceByte * jobBytes(job) }));
+                return await schedule(tasks, { workers, memoryBudget }, analyze, proceed);
+            }
+            finally {
+                await Promise.all(all.map((worker) => worker.terminate()));
+            }
+        },
+    };
+}
+/** The worker's module: its TypeScript source when this module runs from source, and its build output otherwise. */
+function workerUrl() {
+    return new URL(import.meta.url.endsWith('.ts') ? './worker.ts' : './worker.js', import.meta.url);
+}

package/dist/packages/parallel/lib/schedule.d.ts

@@ -0,0 +1,16 @@
+/** How many groups may run at once, and the memory their estimated peak heaps must fit in, in bytes. */
+export interface ScheduleOptions {
+    workers: number;
+    memoryBudget: number;
+}
+/**
+ * Runs `run(index)` for each task, in task order, at most `workers` at once. A task starts only once every task before
+ * it has started, and only while its estimated peak heap (`heap`) and those of the tasks running fit `memoryBudget`, or
+ * when no task is running, so a group whose estimate alone exceeds the budget waits until it can run alone.
+ * `proceed()` is asked before each task starts: once it says no, no further task starts, and each task not started
+ * gives `undefined`. The results come back in task order, whatever order the tasks finish in, so merging them never
+ * depends on completion order. A task that throws rejects the whole schedule once the tasks running have finished.
+ */
+export declare function schedule<T>(tasks: readonly {
+    heap: number;
+}[], { workers, memoryBudget }: ScheduleOptions, run: (index: number) => Promise<T>, proceed?: () => boolean): Promise<(T | undefined)[]>;

package/dist/packages/parallel/lib/schedule.js

@@ -0,0 +1,52 @@
+// The link-group schedule (§18 Parallelism): which group starts when, and the order results come back in.
+/**
+ * Runs `run(index)` for each task, in task order, at most `workers` at once. A task starts only once every task before
+ * it has started, and only while its estimated peak heap (`heap`) and those of the tasks running fit `memoryBudget`, or
+ * when no task is running, so a group whose estimate alone exceeds the budget waits until it can run alone.
+ * `proceed()` is asked before each task starts: once it says no, no further task starts, and each task not started
+ * gives `undefined`. The results come back in task order, whatever order the tasks finish in, so merging them never
+ * depends on completion order. A task that throws rejects the whole schedule once the tasks running have finished.
+ */
+export function schedule(tasks, { workers, memoryBudget }, run, proceed = () => true) {
+    const results = tasks.map(() => undefined);
+    return new Promise((resolve, reject) => {
+        let next = 0;
+        let running = 0;
+        let heap = 0;
+        let stopped = false;
+        let failure;
+        const pump = () => {
+            while (!stopped && failure === undefined && next < tasks.length && running < Math.max(1, workers)) {
+                const task = tasks[next];
+                if (running > 0 && heap + task.heap > memoryBudget)
+                    break;
+                if (!proceed()) {
+                    stopped = true;
+                    break;
+                }
+                const index = next++;
+                running++;
+                heap += task.heap;
+                run(index).then((result) => {
+                    results[index] = result;
+                    finished(task);
+                }, (error) => {
+                    failure ??= { error };
+                    finished(task);
+                });
+            }
+            if (running > 0)
+                return;
+            if (failure !== undefined)
+                reject(failure.error);
+            else
+                resolve(results);
+        };
+        const finished = (task) => {
+            running--;
+            heap -= task.heap;
+            pump();
+        };
+        pump();
+    });
+}

package/dist/packages/parallel/lib/worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/packages/parallel/lib/worker.js

@@ -0,0 +1,18 @@
+// A link-group worker (§18 Parallelism): analyzes one job at a time with the shipped JS resolver. Jobs and results
+// cross the boundary as JSON text (§19 Serializable seams).
+import { parentPort, workerData } from 'node:worker_threads';
+import { jsResolver } from "../../analysis/index.js";
+import { analyzeJob } from "../../analysis/job.js";
+const setup = workerData;
+const catalog = JSON.parse(setup.catalog);
+const budget = JSON.parse(setup.budget);
+parentPort.on('message', ({ job }) => {
+    let reply;
+    try {
+        reply = { output: JSON.stringify(analyzeJob(jsResolver, JSON.parse(job), catalog, budget)) };
+    }
+    catch (error) {
+        reply = { error: error instanceof Error ? (error.stack ?? error.message) : String(error) };
+    }
+    parentPort.postMessage(reply);
+});

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

@@ -0,0 +1,36 @@
+import type { ComparedFinding } from '../compare/index.ts';
+import type { Level } from '../completeness/index.ts';
+import type { FailOnState } from '../config/index.ts';
+/** A finding's policy slot (§15): in R1, `{ outcome: 'fail', by }` when it trips the gate, otherwise null. */
+export type PolicySlot = {
+    outcome: 'fail';
+    by: `fail-on:${FailOnState}`;
+} | null;
+export interface PolicedFinding extends ComparedFinding {
+    policy: PolicySlot;
+}
+/**
+ * The gate (§15): the states it fails on, whether it ran and passed, and the exit code it gives (§16). The result is
+ * the findings' alone; an `incomplete` scan shows in the exit code, 3, and the completeness level.
+ */
+export interface Gate {
+    failOn: FailOnState[];
+    result: 'pass' | 'fail' | 'not-run';
+    exitCode: 0 | 1 | 3;
+}
+/**
+ * Applies `--fail-on` (§11 The gate): a finding in a listed state trips the gate, and its policy slot says so. Every
+ * other slot is null (not evaluated). The gate fails, with exit code 1, when a finding trips it. With no states listed
+ * it does not run.
+ *
+ * When the gate runs over an `incomplete` scan, the exit code is 3 whether the gate passed or failed (§13, §16).
+ * `allowIncomplete` downgrades that to a warning, which the CLI writes, and the exit code is the gate's own.
+ */
+export declare function applyPolicy(findings: readonly ComparedFinding[], options: {
+    failOn: readonly FailOnState[];
+    level: Level;
+    allowIncomplete: boolean;
+}): {
+    findings: PolicedFinding[];
+    gate: Gate;
+};

package/dist/packages/policy/index.js

@@ -0,0 +1,22 @@
+// Policy (§19, module 8): decides the policy slot of each finding and the gate result (§15). It knows nothing of
+// rendering.
+/**
+ * Applies `--fail-on` (§11 The gate): a finding in a listed state trips the gate, and its policy slot says so. Every
+ * other slot is null (not evaluated). The gate fails, with exit code 1, when a finding trips it. With no states listed
+ * it does not run.
+ *
+ * When the gate runs over an `incomplete` scan, the exit code is 3 whether the gate passed or failed (§13, §16).
+ * `allowIncomplete` downgrades that to a warning, which the CLI writes, and the exit code is the gate's own.
+ */
+export function applyPolicy(findings, options) {
+    const { failOn } = options;
+    const policed = findings.map((finding) => {
+        const state = failOn.find((listed) => listed === finding.baselineState);
+        return { ...finding, policy: state === undefined ? null : { outcome: 'fail', by: `fail-on:${state}` } };
+    });
+    if (failOn.length === 0)
+        return { findings: policed, gate: { failOn: [], result: 'not-run', exitCode: 0 } };
+    const failed = policed.some((finding) => finding.policy !== null);
+    const exitCode = options.level === 'incomplete' && !options.allowIncomplete ? 3 : failed ? 1 : 0;
+    return { findings: policed, gate: { failOn: [...failOn], result: failed ? 'fail' : 'pass', exitCode } };
+}

package/dist/packages/report/explain.d.ts

@@ -0,0 +1,26 @@
+import type { Report, ReportFinding } from './index.ts';
+/** The findings a fingerprint or target names in a report. */
+export type Explained = {
+    kind: 'found';
+    finding: ReportFinding;
+}
+/** A target that names several findings: each is a candidate, in the report's fingerprint order. */
+ | {
+    kind: 'ambiguous';
+    candidates: ReportFinding[];
+} | {
+    kind: 'unknown';
+};
+/**
+ * The finding `query` names in `report`. A fingerprint names its finding. Otherwise `query` is a target, written as
+ * its target key (`window|Window.fetch|replace`), as realm and name (`window|Window.fetch`) or as its name alone
+ * (`Window.fetch`), and it names every finding with that target.
+ */
+export declare function findExplained(report: Report, query: string): Explained;
+/** One line per candidate a target names: its fingerprint, effect and attribution. */
+export declare function renderCandidates(candidates: readonly ReportFinding[]): string;
+/**
+ * A finding as `monkeypatchlist explain` renders it: its identity, attribution, baseline state and confidence, then each
+ * occurrence with its location, mechanism, attribution evidence, confidence and the `text` of each trace step.
+ */
+export declare function renderExplanation(report: Report, finding: ReportFinding): string;

package/dist/packages/report/explain.js

@@ -0,0 +1,99 @@
+// `monkeypatchlist explain` (§14 Where traces appear, §15 Terminal, §16 Commands): one finding from a saved JSON report,
+// rendered with every occurrence and its trace. Nothing is recomputed: every line reads a field the report holds.
+/**
+ * The finding `query` names in `report`. A fingerprint names its finding. Otherwise `query` is a target, written as
+ * its target key (`window|Window.fetch|replace`), as realm and name (`window|Window.fetch`) or as its name alone
+ * (`Window.fetch`), and it names every finding with that target.
+ */
+export function findExplained(report, query) {
+    const byFingerprint = report.findings.find((finding) => finding.fingerprint === query);
+    if (byFingerprint !== undefined)
+        return { kind: 'found', finding: byFingerprint };
+    const candidates = report.findings.filter(({ targetKey, target }) => query === targetKey || query === target.name || query === `${target.realm}|${target.name}`);
+    if (candidates.length === 0)
+        return { kind: 'unknown' };
+    if (candidates.length === 1)
+        return { kind: 'found', finding: candidates[0] };
+    return { kind: 'ambiguous', candidates };
+}
+/** One line per candidate a target names: its fingerprint, effect and attribution. */
+export function renderCandidates(candidates) {
+    const width = Math.max(...candidates.map((finding) => finding.fingerprint.length));
+    return candidates
+        .map((finding) => `  ${finding.fingerprint.padEnd(width)}   ${finding.effect} · ${finding.attribution.key}`)
+        .map((line) => `${line}\n`)
+        .join('');
+}
+/**
+ * A finding as `monkeypatchlist explain` renders it: its identity, attribution, baseline state and confidence, then each
+ * occurrence with its location, mechanism, attribution evidence, confidence and the `text` of each trace step.
+ */
+export function renderExplanation(report, finding) {
+    const { target } = finding;
+    const lines = [
+        `${target.name}   ${finding.effect}`,
+        field('Fingerprint', finding.fingerprint),
+        field('Target key', finding.targetKey),
+        field('Target', [`realm ${target.realm}`, `holder ${target.holder}`, ...(target.shadows === undefined ? [] : [`shadows ${target.shadows}`])].join(' · ')),
+        field('Surface', finding.surface),
+        // `locks` is true, false or 'unknown' (§8): only a finding known not to lock leaves the line out.
+        ...(finding.locks === false ? [] : [field('Locks', finding.locks === true ? 'yes' : 'unknown')]),
+        field('Attribution', attributionOf(finding)),
+        ...(finding.baselineState === null
+            ? []
+            : [field('Baseline', `${finding.baselineState}${finding.matchedBy === null ? '' : ` (matched by ${finding.matchedBy})`}`)]),
+        ...(finding.confidence === null ? [] : [field('Confidence', confidenceOf(finding.confidence))]),
+    ];
+    const count = finding.occurrences.length;
+    if (count === 0) {
+        lines.push('', 'No occurrences: the scan did not find this baseline entry.');
+    }
+    finding.occurrences.forEach((occurrence, i) => {
+        lines.push('', `Occurrence ${i + 1} of ${count}`, ...occurrenceLines(report, occurrence));
+    });
+    return `${lines.join('\n')}\n`;
+}
+function occurrenceLines(report, occurrence) {
+    const { artifact, generated, original, evidence } = occurrence;
+    const path = report.artifacts.find((candidate) => candidate.url === artifact.url)?.path ?? null;
+    const lines = [
+        field('Location', `${path ?? artifact.url}:${generated.line}:${generated.column}`),
+        ...(path === null ? [] : [field('Artifact', artifact.url)]),
+        ...(original === null ? [] : [field('Source', `${original.source}:${original.line}:${original.column}`)]),
+        field('Mechanism', `${occurrence.mechanism} · realm instance ${occurrence.realmInstance}`),
+    ];
+    const evidenceParts = [
+        ...(evidence.source === undefined ? [] : [`unmapped source ${evidence.source ?? 'null'}`]),
+        ...(evidence.rejected === undefined
+            ? []
+            : [`rejected ${evidence.rejected.source}:${evidence.rejected.line}:${evidence.rejected.column}`]),
+        ...(evidence.slug === undefined ? [] : [`slug ${evidence.slug}`]),
+        ...(evidence.vendoredBy === undefined ? [] : [`vendored in ${evidence.vendoredBy}`]),
+        ...(evidence.version === undefined
+            ? []
+            : [`version ${evidence.version.version} (${evidence.version.versionSource})`]),
+    ];
+    if (evidenceParts.length > 0)
+        lines.push(field('Evidence', evidenceParts.join(' · ')));
+    lines.push(field('Confidence', confidenceOf(occurrence.confidence)), '  Trace');
+    const width = Math.max(0, ...occurrence.trace.map((step) => step.kind.length));
+    lines.push(...occurrence.trace.map((step) => `    ${step.kind.padEnd(width)}  ${step.text}`));
+    return lines;
+}
+function field(label, value) {
+    return `  ${label.padEnd(12)} ${value}`;
+}
+function attributionOf({ attribution }) {
+    const name = attribution.package === undefined ? [] : [`package ${attribution.package}`];
+    const vendored = attribution.vendoredBy === undefined ? [] : [`vendored in ${attribution.vendoredBy}`];
+    return [attribution.key, ...name, ...vendored, `provenance ${attribution.provenance}`].join(' · ');
+}
+/** Each confidence dimension's level, with its reasons when it has any (§9). */
+function confidenceOf(confidence) {
+    return ['target', 'mutation', 'attribution']
+        .map((dimension) => {
+        const { level, reasons } = confidence[dimension];
+        return `${dimension} ${level}${reasons.length === 0 ? '' : ` (${reasons.join(', ')})`}`;
+    })
+        .join(' · ');
+}