monkeypatchlist 0.0.0-stage → 0.1.0

package/dist/packages/report/terminal.js

@@ -0,0 +1,331 @@
+// The terminal report (§15 Terminal): change first, then completeness, what each missing input costs (§2 Input tiers),
+// what the surface left out, the ineffective writes and the gate. Every line reads a field the JSON report holds;
+// nothing is recomputed. It is pure: whether to use color is the caller's to decide (a TTY, `NO_COLOR`, `--no-color`).
+import { surfaces } from "../../catalog.js";
+import { limitationKinds } from "../analysis/index.js";
+import { strongVersionSources } from "../attribution/index.js";
+import { compareStrings } from "../findings/index.js";
+const defaults = { color: false, verbose: false, listIneffective: false };
+/** The SGR codes the report uses. */
+const styles = { bold: 1, red: 31, green: 32, yellow: 33, dim: 2 };
+/** The terminal report for `report` (§15 Terminal). */
+export function renderTerminal(report, options = {}) {
+    const { color, verbose, listIneffective } = { ...defaults, ...options };
+    const paint = color ? (style, text) => `\u001b[${styles[style]}m${text}\u001b[0m` : (_, text) => text;
+    const lines = [title(report), ''];
+    lines.push(...changes(report, paint, verbose), '');
+    lines.push(...completeness(report, paint));
+    lines.push(...inputs(report));
+    lines.push(outsideScope(report));
+    lines.push(...ineffective(report, listIneffective));
+    lines.push('', gateLine(report, paint));
+    return `${lines.join('\n')}\n`;
+}
+/** `monkeypatchlist <version> · catalog <n> · <name> · surface <surface> · <mode>`. */
+function title({ tool, application, config }) {
+    return [
+        `monkeypatchlist ${tool.monkeypatchlistVersion}`,
+        `catalog ${tool.catalogVersion}`,
+        application.name,
+        `surface ${config.surface}`,
+        config.mode,
+    ].join(' · ');
+}
+/**
+ * The change since the baseline: the counts, a card per `added` and `changed` finding (and per `existing` one under
+ * `--verbose`), a line per `removed` and `unconfirmed` entry, and the notes. Without a baseline no finding has a state,
+ * so every finding gets a card.
+ */
+function changes(report, paint, verbose) {
+    const { summary, findings } = report;
+    if (report.baseline === null) {
+        if (findings.length === 0)
+            return ['No platform mutations found.'];
+        return [
+            `${paint('bold', 'Findings')} ${findings.length}   (no baseline: run with --baseline to see the change)`,
+            ...findings.flatMap((finding) => card(report, finding)),
+        ];
+    }
+    const lines = [
+        paint('bold', 'Change since baseline'),
+        `  Added ${summary.added}   Changed ${summary.changed}   Removed ${summary.removed}   ` +
+            `Unconfirmed ${summary.unconfirmed}   Existing ${summary.existing}`,
+    ];
+    const inState = (state) => findings.filter((finding) => finding.baselineState === state);
+    const section = (heading, style, body) => body.length === 0 ? [] : ['', paint(style, heading), ...body];
+    lines.push(...section('Added', 'yellow', inState('added').flatMap((finding) => card(report, finding))));
+    lines.push(...section('Changed', 'yellow', inState('changed').flatMap((finding) => card(report, finding))));
+    lines.push(...section('Removed', 'bold', inState('removed').map(entryLine)));
+    lines.push(...section('Unconfirmed', 'bold', inState('unconfirmed').map(entryLine)));
+    if (verbose)
+        lines.push(...section('Existing', 'bold', inState('existing').flatMap((finding) => card(report, finding))));
+    const notes = [
+        ...report.baseline.notes.map(skewLine),
+        ...findings.flatMap((finding) => finding.notes.map((note) => noteLine(finding, note))),
+    ];
+    lines.push(...section('Notes', 'bold', notes));
+    return lines;
+}
+/** The width of a card's or an entry's target column. */
+const targetWidth = 32;
+/** A finding's target as a card names it: its name, and its realm when that isn't `window`. */
+function targetName({ target }) {
+    return target.realm === 'window' ? target.name : `${target.name} (${target.realm})`;
+}
+/**
+ * A finding's card (§15 Terminal): its target and effect, led for a `changed` one by its `changedReasons` before →
+ * after, then Package (with its Previous version), Source (original, then generated), Provenance · install context · reachability, Confidence
+ * (with its reasons below `high`) and Fingerprint.
+ */
+function card(report, finding) {
+    const reasons = finding.changedReasons.map(changedReason).join(' · ');
+    const head = `  ${targetName(finding).padEnd(targetWidth)} ${finding.effect}${reasons === '' ? '' : `   ${reasons}`}`;
+    const [first] = finding.occurrences;
+    const more = finding.occurrences.length - 1;
+    const context = [provenanceLabels[finding.attribution.provenance]];
+    if (finding.installContext !== null)
+        context.push(finding.installContext);
+    if (finding.reachability !== null)
+        context.push(finding.reachability);
+    return [
+        head,
+        field('Package', packageLine(report, finding)),
+        ...finding.notes.flatMap((note) => note.kind === 'previous-version' ? [field('Previous version', `${note.package}@${note.before}`)] : []),
+        ...introducedByLine(report, finding),
+        ...(first === undefined
+            ? []
+            : [field('Source', `${sourceOf(report, first)}${more > 0 ? ` (+${more} more ${more === 1 ? 'occurrence' : 'occurrences'})` : ''}`)]),
+        field('Provenance', context.join(' · ')),
+        ...(finding.confidence === null ? [] : [field('Confidence', confidenceOf(finding.confidence))]),
+        field('Fingerprint', finding.fingerprint),
+    ];
+}
+/**
+ * The card's `Introduced by` (§10 Terminal wording), for bundled-dependency code the scan found: the introducers, unless
+ * every one is the containing package itself, a direct dependency; `unknown (no lockfile)`, or the recorded reason,
+ * when they are unknown.
+ */
+function introducedByLine(report, finding) {
+    if (finding.attribution.provenance !== 'bundled-dependency' || finding.occurrences.length === 0)
+        return [];
+    const { introducedBy } = finding;
+    if (introducedBy !== undefined) {
+        const own = finding.attribution.package;
+        const itself = introducedBy.every((each) => each.slice(0, each.lastIndexOf('@')) === own);
+        // Yarn's introducers are capped at medium (§10 Formats).
+        const capped = report.completeness.attribution.introducers.confidence === 'medium' ? ' (medium)' : '';
+        return itself ? [] : [field('Introduced by', `${introducedBy.join(', ')}${capped}`)];
+    }
+    const { reason } = report.completeness.attribution.introducers;
+    const why = reason === null ? '' : ` (${reason === 'no-lockfile' ? 'no lockfile' : reason})`;
+    return [field('Introduced by', `unknown${why}`)];
+}
+function field(label, value) {
+    return `    ${label.padEnd(16)} ${value}`;
+}
+/** How the card writes each provenance (§10 Provenance). */
+const provenanceLabels = {
+    'first-party': 'first-party',
+    'bundled-dependency': 'bundled dependency',
+    remote: 'remote',
+    inline: 'inline',
+    unknown: 'unknown',
+};
+/**
+ * The card's Package: the containing package's name, `unknown` when the code is bundled but no package is known, or
+ * `none` with the provenance for code that has no package (§10).
+ */
+function packageOf({ attribution }) {
+    if (attribution.package !== undefined)
+        return attribution.package;
+    if (attribution.provenance === 'unknown' || attribution.provenance === 'bundled-dependency')
+        return 'unknown';
+    return `none (${provenanceLabels[attribution.provenance]})`;
+}
+/**
+ * The card's Package with its version (§10 Terminal wording): `name@version` for the strong version in `packages`;
+ * every strong version the scan gives the package when it has several, counted over all the findings keyed on it,
+ * as `packages` counts them; else the finding's weak version with its source; else the name alone. Vendored code
+ * reads `tiny-helper (vendored in telemetry-agent@x)` with no version of its own: a vendored copy never gives one, and
+ * a version in `packages` would be another, installed copy's.
+ */
+function packageLine(report, finding) {
+    const name = packageOf(finding);
+    const { vendoredBy } = finding.attribution;
+    if (vendoredBy !== undefined)
+        return `${name} (vendored in ${vendoredBy})`;
+    if (finding.attribution.package === undefined)
+        return name;
+    const known = report.packages[name];
+    if (known !== undefined)
+        return `${name}@${known.version}`;
+    const strongVersions = [
+        ...new Set(report.findings
+            .filter(({ attribution }) => attribution.package === name)
+            .flatMap(({ occurrences }) => occurrences)
+            .flatMap(({ evidence }) => evidence.version !== undefined && strongVersionSources.has(evidence.version.versionSource)
+            ? [evidence.version.version]
+            : [])),
+    ].sort(compareStrings);
+    if (strongVersions.length > 1)
+        return `${name} (versions ${strongVersions.join(', ')})`;
+    const weak = finding.occurrences.find(({ evidence }) => evidence.version !== undefined)?.evidence.version;
+    if (strongVersions.length === 0 && weak !== undefined)
+        return `${name} (${weak.version} from ${weak.versionSource}, a weak signal)`;
+    return name;
+}
+/** An attribution key as a change line shows it: a package key by its package name. */
+function keyLabel(key) {
+    return key.startsWith('pkg:') ? key.slice('pkg:'.length) : key;
+}
+function changedReason(reason) {
+    if (reason.reason === 'attribution')
+        return `attribution ${keyLabel(reason.before)} → ${keyLabel(reason.after)}`;
+    if (reason.reason === 'locks')
+        return `locks ${reason.before ? 'yes' : 'no'} → ${reason.after ? 'yes' : 'no'}`;
+    return `effect ${reason.before} → ${reason.after}`;
+}
+/** A `removed` or `unconfirmed` entry: its target, effect and attribution key. */
+function entryLine(finding) {
+    return `  ${targetName(finding).padEnd(targetWidth)} ${finding.effect}   ${finding.attribution.key}`;
+}
+function noteLine(finding, note) {
+    const name = targetName(finding).padEnd(targetWidth);
+    if (note.kind === 'rekeyed')
+        return `  ${name} rekeyed ${note.before.join(', ')} → ${note.after}`;
+    if (note.kind === 'previous-version')
+        return `  ${name} ${note.package} ${note.before} → ${note.after}`;
+    if (note.kind === 'reachability-change')
+        return `  ${name} reachability ${note.before} → ${note.after}`;
+    if (note.kind === 'install-context-change')
+        return `  ${name} install context ${note.before} → ${note.after}`;
+    return `  ${name} shared target key: not paired with ${note.fingerprints.join(', ')}`;
+}
+/** A version-skew note (§4) as one line: the versions on each side, and what the skew means for the comparison. */
+function skewLine(note) {
+    const side = (which) => `monkeypatchlist ${note.monkeypatchlistVersion[which]} · catalog ${note.catalogVersion[which]} · format ` +
+        `${note.formatVersion[which]} · fingerprint scheme ${note.fingerprintScheme[which]}`;
+    const meaning = note.newer === 'baseline'
+        ? 'The baseline is newer, so no delta carries explainedBy'
+        : 'A delta without explainedBy may come from analyzer changes';
+    return `  Baseline written by ${side('baseline')} (this scan: ${side('scan')}). ${meaning}`;
+}
+/** An occurrence's place: its original location when a map resolves one, then its generated location. */
+function sourceOf(report, occurrence) {
+    const path = report.artifacts.find((artifact) => artifact.url === occurrence.artifact.url)?.path;
+    const generated = `${path ?? occurrence.artifact.url}:${occurrence.generated.line}:${occurrence.generated.column}`;
+    const { original } = occurrence;
+    return original === null ? generated : `${original.source}:${original.line} (${generated})`;
+}
+/** Each confidence dimension's level, with its reasons when it is below `high` (§9). */
+function confidenceOf(confidence) {
+    return ['target', 'mutation', 'attribution']
+        .map((dimension) => {
+        const { level, reasons } = confidence[dimension];
+        return `${dimension} ${level}${reasons.length === 0 ? '' : ` (${reasons.join(', ')})`}`;
+    })
+        .join(' · ');
+}
+/** Nonzero counts as `name n`, joined. */
+function counts(entries) {
+    return entries
+        .filter(([, n]) => n > 0)
+        .map(([name, n]) => `${name} ${n}`)
+        .join(' · ');
+}
+/** The completeness block (§13): the level, the artifact counters and the limitation kinds. */
+function completeness(report, paint) {
+    const { level, counters, limitations } = report.completeness;
+    const { artifacts, statistics } = counters;
+    const style = level === 'complete' ? 'green' : level === 'incomplete' ? 'red' : 'yellow';
+    const sum = (record) => Object.values(record).reduce((a, b) => a + b, 0);
+    const breakdown = (record) => {
+        const listed = counts(Object.entries(record));
+        return listed === '' ? '' : ` (${listed})`;
+    };
+    const lines = [
+        `Completeness   ${paint(style, level)}`,
+        `  Known ${artifacts.known} · analyzed ${artifacts.analyzed} · failed ${sum(artifacts.failed)}${breakdown(artifacts.failed)}` +
+            ` · skipped ${sum(artifacts.skipped)}${breakdown(artifacts.skipped)}` +
+            (artifacts.sweepOnly > 0 ? ` · sweep-only ${artifacts.sweepOnly}` : ''),
+    ];
+    const kinds = counts(limitationKinds.map((kind) => [kind, limitations.filter((record) => record.kind === kind).length]));
+    if (kinds !== '')
+        lines.push(`  Limitations  ${kinds}`);
+    if (statistics.budgetExhausted > 0) {
+        const groups = statistics.budgetExhausted;
+        lines.push(`  Step budget  exhausted in ${groups} link ${groups === 1 ? 'group' : 'groups'}`);
+    }
+    if (statistics.crashGuard === 'fired')
+        lines.push('  Crash guard  fired: the scan reports no findings');
+    return lines;
+}
+/**
+ * The Inputs block (§15 Terminal): what each missing input costs, following the input tiers (§2). Without a source map,
+ * bundled code has no containing package and no original locations; without a lockfile, there are no lockfile versions
+ * and no introducing dependencies.
+ */
+function inputs(report) {
+    const { withMap, withoutMap, withBrokenMap } = report.completeness.attribution.artifacts;
+    const total = withMap + withoutMap + withBrokenMap;
+    let maps = `${withMap} / ${total} artifacts`;
+    if (withBrokenMap > 0)
+        maps += ` · ${withBrokenMap} with broken maps`;
+    if (withMap < total)
+        maps += ' · without a map: Package unknown for bundled code, no original locations';
+    // A mapped artifact can still leave lines unmapped, so the findings with no package are counted either way: the
+    // current findings whose card reads `Package unknown`.
+    const unknown = report.findings.filter((finding) => finding.occurrences.length > 0 && packageOf(finding) === 'unknown').length;
+    if (unknown > 0)
+        maps += ` · ${unknown} ${unknown === 1 ? 'finding has' : 'findings have'} Package unknown`;
+    return ['Inputs', `  Source maps  ${maps}`, `  Lockfile     ${lockfile(report)}`];
+}
+/**
+ * The Inputs block's Lockfile (§10, §15): the lockfile as given, and when introducers are unknown, why, what that
+ * costs, and the evidence.
+ */
+function lockfile(report) {
+    const given = report.config.lockfile;
+    if (given === null)
+        return 'not given · no lockfile versions; Introduced by unknown';
+    const { reason, evidence, confidence } = report.completeness.attribution.introducers;
+    if (reason === null)
+        return confidence === 'medium' ? `${given.path} · Introduced by medium` : given.path;
+    const why = `${reason}${evidence === null ? '' : `: ${evidence}`}`;
+    const cost = reason === 'importer-unresolved' ? 'Introduced by unknown' : 'no lockfile versions; Introduced by unknown';
+    return `${given.path} · ${why} · ${cost}`;
+}
+/** How many findings a `protected` scan left out, per surface (§12), with the flag that shows them. */
+function outsideScope({ summary }) {
+    const listed = counts(surfaces.map((surface) => [surface, summary.outOfScopeBySurface[surface]]));
+    return listed === '' ? 'Outside scope  none' : `Outside scope  ${listed}   (run with --surface all)`;
+}
+/** The ineffective writes (§3): a count, or under `--list-ineffective` a line per record and occurrence. */
+function ineffective(report, list) {
+    const count = report.summary.ineffectiveWrites;
+    if (count === 0)
+        return ['Ineffective writes 0'];
+    if (!list)
+        return [`Ineffective writes ${count}   (--list-ineffective)`];
+    return [
+        `Ineffective writes ${count}`,
+        ...report.ineffectiveWrites.flatMap((record) => [
+            `  ${targetName(record).padEnd(targetWidth)} ${record.reason}`,
+            ...record.occurrences.map((occurrence) => `    ${occurrence.effect} · ${occurrence.mechanism} · throws ${occurrence.throws} · ` +
+                `${sourceOf(report, occurrence)}`),
+        ]),
+    ];
+}
+/** The gate line (§15 Terminal): the states it fails on, its result and the exit code. */
+function gateLine(report, paint) {
+    const { gate } = report;
+    if (gate.result === 'not-run')
+        return 'Gate  not run (no --fail-on)';
+    const failed = report.findings.filter((finding) => finding.policy !== null).length;
+    const result = gate.result === 'fail'
+        ? paint('red', `FAIL (${failed} ${failed === 1 ? 'finding' : 'findings'})`)
+        : paint('green', 'pass');
+    // Exit code 3 is the scan's, not the findings' (§16): the line says why.
+    const incomplete = gate.exitCode === 3 ? ' · scan incomplete' : '';
+    return `Gate  fail-on ${gate.failOn.join(',')} → ${result}${incomplete}   exit ${gate.exitCode}`;
+}

package/dist/packages/source-store/fixture.d.ts

@@ -0,0 +1,22 @@
+import type { Fetcher } from './index.ts';
+/**
+ * A recorded HTTP response: its status (200 when left out), its headers (names in any case) and its body. A 3xx
+ * response with a `Location` header redirects to that URL, resolved against the one requested.
+ */
+export interface RecordedResponse {
+    status?: number;
+    headers?: Record<string, string>;
+    body?: string | Uint8Array;
+}
+/**
+ * A fetcher that serves `responses`, by URL. A fragment is never part of a request, so it is dropped before the lookup.
+ * It follows recorded redirects, and gives:
+ *
+ * - `ok`, with the bytes and the final response, for a 2xx response, or `sri-mismatch` when its bytes don't match the
+ *   request's integrity value (§17 Integrity)
+ * - `fetch-failed` with the response, for any other status (§17 Outcomes)
+ * - `fetch-failed` with no response, for a URL with no recorded response, as for a host that doesn't answer
+ * - `remote-refused` with no response, for a sixth redirect, as the safety floor gives (§17 Safety floor). A redirect
+ *   loop is refused so too: there is no separate loop check.
+ */
+export declare function fixtureFetcher(responses: Readonly<Record<string, RecordedResponse>>): Fetcher;

package/dist/packages/source-store/fixture.js

@@ -0,0 +1,58 @@
+// The fixture fetcher (§19 Source store and retrieval): serves recorded responses, for tests and build-time tools. It
+// never touches the network.
+import { verified } from "./lib/integrity.js";
+import { defaultLimits } from "./resolve.js";
+const encoder = new TextEncoder();
+/**
+ * A fetcher that serves `responses`, by URL. A fragment is never part of a request, so it is dropped before the lookup.
+ * It follows recorded redirects, and gives:
+ *
+ * - `ok`, with the bytes and the final response, for a 2xx response, or `sri-mismatch` when its bytes don't match the
+ *   request's integrity value (§17 Integrity)
+ * - `fetch-failed` with the response, for any other status (§17 Outcomes)
+ * - `fetch-failed` with no response, for a URL with no recorded response, as for a host that doesn't answer
+ * - `remote-refused` with no response, for a sixth redirect, as the safety floor gives (§17 Safety floor). A redirect
+ *   loop is refused so too: there is no separate loop check.
+ */
+export function fixtureFetcher(responses) {
+    const recorded = new Map(Object.entries(responses).map(([url, response]) => [withoutFragment(url), response]));
+    return {
+        async fetch(url, { integrity = '' }) {
+            const { redirects: most } = defaultLimits;
+            for (let current = withoutFragment(url), redirects = 0;; redirects++) {
+                const response = recorded.get(current);
+                if (response === undefined) {
+                    return { status: 'fetch-failed', detail: `no recorded response for ${current}`, response: null };
+                }
+                const status = response.status ?? 200;
+                const headers = new Map(Object.entries(response.headers ?? {}).map(([name, value]) => [name.toLowerCase(), value]));
+                const location = headers.get('location');
+                if (status >= 300 && status < 400 && location !== undefined) {
+                    if (redirects === most) {
+                        const detail = `the safety floor follows at most ${most} redirects`;
+                        return { status: 'remote-refused', detail, response: null };
+                    }
+                    current = withoutFragment(new URL(location, current).href);
+                    continue;
+                }
+                const fetched = {
+                    finalUrl: current,
+                    contentType: headers.get('content-type') ?? null,
+                    etag: headers.get('etag') ?? null,
+                    lastModified: headers.get('last-modified') ?? null,
+                    sourceMap: headers.get('sourcemap') ?? headers.get('x-sourcemap') ?? null,
+                };
+                if (status < 200 || status > 299)
+                    return { status: 'fetch-failed', detail: `HTTP ${status}`, response: fetched };
+                const body = response.body ?? '';
+                return verified(typeof body === 'string' ? encoder.encode(body) : body, fetched, integrity);
+            }
+        },
+    };
+}
+/** The URL without its fragment. */
+function withoutFragment(url) {
+    const parsed = new URL(url);
+    parsed.hash = '';
+    return parsed.href;
+}