monkeypatchlist 0.0.0-stage → 0.1.0

package/dist/packages/analysis/visit-order.d.ts

@@ -0,0 +1,3 @@
+import type { Resolver } from './lib/types.ts';
+/** The JS resolver, visiting its call lists in an order `seed` shuffles (Fisher–Yates over a mulberry32 stream). */
+export declare function shuffledResolver(seed: number): Resolver;

package/dist/packages/analysis/visit-order.js

@@ -0,0 +1,23 @@
+// Visit order (§18 Context policy): results are independent of the order the resolver visits its work in. A shuffled
+// resolver visits the calls of each function, and of each program, in a seeded pseudo-random order, so a permutation
+// test can show that a scan's report stays byte-identical. It is for tests only; the CLI ships `jsResolver`.
+import { createJsResolver } from "./lib/resolver.js";
+/** The JS resolver, visiting its call lists in an order `seed` shuffles (Fisher–Yates over a mulberry32 stream). */
+export function shuffledResolver(seed) {
+    let state = seed >>> 0;
+    const next = () => {
+        state = (state + 0x6d2b79f5) >>> 0;
+        let t = state;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+    return createJsResolver(undefined, (items) => {
+        const out = [...items];
+        for (let index = out.length - 1; index > 0; index--) {
+            const other = Math.floor(next() * (index + 1));
+            [out[index], out[other]] = [out[other], out[index]];
+        }
+        return out;
+    });
+}

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

@@ -0,0 +1,233 @@
+import type { RemoteUrlNormalization } from '../../catalog.ts';
+import type { GeneratedLocation, IneffectiveWrite, RawOccurrence, TraceStep } from '../analysis/index.ts';
+import { type Confidence } from '../confidence/index.ts';
+import { introducerReasons, type IntroducerReason } from './lib/lockfile.ts';
+import { type PathRules } from './lib/path-rules.ts';
+import { type LineReading } from './lib/source-map.ts';
+export type { PathRules } from './lib/path-rules.ts';
+export { introducerReasons, type IntroducerReason };
+export { lockfileManifests } from './lib/lockfile.ts';
+/**
+ * The lockfile a scan was given (§10 Introducing dependencies): its path as given, its text (null when it can't be
+ * read), and the `lockfile.importer` setting, or null.
+ */
+export interface LockfileInput {
+    path: string;
+    text: string | null;
+    importer: string | null;
+    /**
+     * The `package.json` texts beside the lockfile (§2 Inputs), by folder relative to its directory (`''` for its
+     * own), null for one that couldn't be read: its own, and the workspaces' it names. Absent for npm and Bun, which
+     * record what they give.
+     */
+    manifests?: Readonly<Record<string, string | null>>;
+}
+/**
+ * Why introducers are unknown, for the attribution block (§10 Unknown is not empty, §13): null with a usable lockfile.
+ * `evidence` says what made it so: the format version of a lockfile that isn't usable, the store path the
+ * lockfile disagrees with, or why no importer was picked.
+ */
+export interface Introducers {
+    reason: IntroducerReason | null;
+    evidence: string | null;
+    /**
+     * How certain the introducers are, with a usable lockfile: `high` from `package-lock.json`, `bun.lock` and
+     * `pnpm-lock.yaml`, and `medium` from `yarn.lock`, whose derived facts are capped there (§10 Formats).
+     */
+    confidence?: 'high' | 'medium';
+}
+/**
+ * The catalog data attribution reads (§4 Catalog versions): the framework path rules and escape-only shapes (§10), and
+ * the remote URL normalization rules (§11).
+ */
+export interface AttributionRules extends PathRules {
+    remoteUrlNormalization: RemoteUrlNormalization;
+}
+/** Where an artifact is served from (§8 Origin and provenance). */
+export type Origin = 'local-build' | 'same-origin' | 'cross-origin' | 'inline';
+/** How the code behind a finding got into its artifact (§10 Provenance). */
+export declare const provenances: readonly ["first-party", "bundled-dependency", "remote", "inline", "unknown"];
+export type Provenance = (typeof provenances)[number];
+/** The artifact fields attribution reads, and that occurrences carry: URL, hash and origin (§8). */
+export interface ArtifactIdentity {
+    url: string;
+    hash: string;
+    origin: Origin;
+}
+/**
+ * An artifact as attribution reads it: its identity, its text, and the source map that verified against it (§2), with
+ * the method that paired it, the line reading that verified it and the build-relative path whose directory its
+ * relative sources resolve against (null when it has none in the build), or null when none did.
+ */
+export interface MappedArtifact extends ArtifactIdentity {
+    /**
+     * The name occurrences give the artifact, when it isn't its URL: one key URL reached through two fetched URLs is an
+     * artifact of each (§11).
+     */
+    id?: string;
+    text: string;
+    map: {
+        raw: unknown;
+        reading: LineReading;
+        method: string;
+        base: string | null;
+    } | null;
+}
+/**
+ * The attribution of an occurrence: its attribution key (§11), the provenance that follows from it, and for a `pkg:`
+ * key the containing package's name (§10). A finding's also carries `vendoredBy` when its code is vendored (§10
+ * Provenance, §15): evidence only, never in the fingerprint, the baseline or `changed`.
+ */
+export interface Attribution {
+    key: string;
+    provenance: Provenance;
+    package?: string;
+    vendoredBy?: string;
+    workspace?: string;
+}
+/** A position in an original source (§10): the raw `sources` entry, a 1-based line and a 0-based column. */
+export interface OriginalLocation {
+    source: string;
+    line: number;
+    column: number;
+}
+/**
+ * An occurrence's attribution evidence (§8, §10), each field present only when it applies:
+ * - `source`: the raw `sources` entry of the synthetic or bundler-runtime source the lookup reached (null for a null
+ *   entry), which counts as unmapped
+ * - `rejected`: the lookup candidate a failed token check discarded
+ * - `slug`: the lossy slug that names a scoped package under Yarn's pnpm linker
+ * - `pathRule`: the id of the framework path rule that named the package of an escaped source
+ * - `package`: the package a remote artifact's map names at the occurrence, which is evidence only: remote code keys
+ *   `url:` (§9, §10 Provenance)
+ * - `vendoredBy`: the vendoring package, `name@version`, when the containing package's path lies inside another
+ *   package's store entry (a store-name mismatch), or inside an installed package when the lockfile says it isn't
+ *   installed itself (§10 Provenance), which is evidence only
+ * - `version`: the containing package's version, from its strongest source (§10 Version), which is evidence only
+ * - `workspace`: the lockfile workspace (`name@version`) that holds first-party code, which only a lockfile gives
+ *   (§10 Provenance; ADR 0006), evidence only
+ */
+export interface AttributionEvidence {
+    source?: string | null;
+    rejected?: OriginalLocation;
+    slug?: string;
+    pathRule?: string;
+    package?: string;
+    vendoredBy?: string;
+    version?: PackageVersion;
+    workspace?: string;
+}
+/**
+ * Where a package's version came from (§10 Version), strongest first: a store path, a lockfile keyed by install path,
+ * then the weak content signals: the package's `package.json` in `sourcesContent`, an in-package `VERSION`
+ * constant, a banner.
+ */
+export declare const versionSources: readonly ["store-path", "lockfile", "package-json", "version-constant", "banner"];
+export type VersionSource = (typeof versionSources)[number];
+/** The strong version sources, the only ones that feed `packages` and the `previousVersion` note (§10, §11). */
+export declare const strongVersionSources: ReadonlySet<VersionSource>;
+/** A package's version and where it came from (§10 Version). */
+export interface PackageVersion {
+    version: string;
+    versionSource: VersionSource;
+}
+/**
+ * A `token-check` trace step (§14): the token check's result at the lookup point (§10), the token, and the lookup
+ * candidate it checked: the mapped original position, kept when the check passes or doesn't apply, and discarded when
+ * it fails.
+ */
+export interface TokenCheckStep {
+    kind: 'token-check';
+    result: 'passed' | 'failed' | 'n/a';
+    token: string | null;
+    lookup: GeneratedLocation;
+    candidate: OriginalLocation;
+    text: string;
+}
+/**
+ * A `path-rule` trace step (§14): the framework path rule that named the package of an escaped source (§10), the
+ * package it named, and the raw source it matched.
+ */
+export interface PathRuleStep {
+    kind: 'path-rule';
+    rule: string;
+    package: string;
+    source: string;
+    text: string;
+}
+/** A trace step of an attributed occurrence: the resolver's, or one attribution adds (§14, §19 Attribution). */
+export type AttributedTraceStep = TraceStep | TokenCheckStep | PathRuleStep;
+export interface AttributedOccurrence extends Omit<RawOccurrence, 'artifact' | 'confidence' | 'lookup' | 'trace'> {
+    artifact: ArtifactIdentity;
+    attribution: Attribution;
+    /** The original location a source map resolves, when attribution kept one (§8). */
+    original: OriginalLocation | null;
+    evidence: AttributionEvidence;
+    /**
+     * The introducing dependencies (§10), `name@version`, sorted: present only for bundled-dependency code that a usable
+     * lockfile places, and absent when they are unknown.
+     */
+    introducedBy?: string[];
+    /** The resolver's target and mutation confidence, and attribution's own (§9). */
+    confidence: Confidence;
+    /** The resolver's trace, then attribution's `token-check` and `path-rule` steps, if any. */
+    trace: AttributedTraceStep[];
+}
+/**
+ * Attributes each occurrence (§10):
+ *
+ * - Inline code is the entry document's (`inline`), and has high attribution confidence.
+ * - Remote code keys `url:` with its URL normalized by the catalog's rules (§11 Remote URL normalization), provenance
+ *   `remote`, and is `high` on that key (§9). A verified map still gives its occurrences original locations, looked up
+ *   as for local code, and a package the map names is evidence only (`evidence.package`).
+ * - Local code without a source map is `unknown`, with `no-map`.
+ * - Local code with a verified map is looked up there at the occurrence's lookup point, with the line reading that
+ *   verified the map. A position that is unmapped, or maps to a synthetic or bundler-runtime source, is `unknown` with
+ *   `no-map`. Otherwise the token check runs, and a position that fails it is discarded: `unknown`, with
+ *   `token-check-failed` and the rejected candidate. A kept position's source path names the containing package, which
+ *   keys `pkg:<name>` with provenance `bundled-dependency`. A source with an unrecognized scheme is `unknown` with
+ *   `foreign-scheme`, and a scoped package under Yarn's pnpm linker `unknown` with `yarn-slug`. A source under no
+ *   `node_modules` segment inside its namespace's inferred root is first-party, keyed `app:<root-relative path>`
+ *   (`first-party-inferred` when the root lies above the bundler base), unless its map's ignore list demotes it to
+ *   `unknown` (`ignore-list-demoted`). One outside the root is escaped: `unknown` with `escaped-source`. Before the
+ *   root decides, the catalog's framework path rules are tried, then its escape-only shapes: a source a rule
+ *   matches keys the package the rule names (`bundled-dependency`, `framework-path-rule`, with a `path-rule` step),
+ *   and one an escape-only shape matches is escaped, wherever the root is.
+ */
+export declare function attribute(occurrences: readonly RawOccurrence[], artifacts: readonly MappedArtifact[], rules: AttributionRules): AttributedOccurrence[];
+/**
+ * An occurrence of an ineffective write (§3 Record), attributed as a finding's occurrence is: its location, attribution
+ * and evidence, and the resolver's trace, then attribution's `token-check` step, if any.
+ */
+export interface AttributedIneffectiveWrite extends Omit<IneffectiveWrite, 'artifact' | 'lookup' | 'trace'> {
+    artifact: ArtifactIdentity;
+    attribution: Attribution;
+    original: OriginalLocation | null;
+    evidence: AttributionEvidence;
+    trace: AttributedTraceStep[];
+}
+/** Attributes each occurrence of an ineffective write (§3 Record), as `attribute` attributes a finding's. */
+export declare function attributeIneffective(writes: readonly IneffectiveWrite[], artifacts: readonly MappedArtifact[], rules: AttributionRules): AttributedIneffectiveWrite[];
+/** A scan's attribution: one inferred root per namespace, and the lockfile as the scan reads it. */
+export interface ScanAttribution {
+    /** Attributes each occurrence of a finding, as `attribute` does, with the lockfile's evidence and introducers. */
+    attribute(occurrences: readonly RawOccurrence[]): AttributedOccurrence[];
+    /** Attributes each occurrence of an ineffective write, as `attributeIneffective` does, with the lockfile's evidence. */
+    attributeIneffective(writes: readonly IneffectiveWrite[]): AttributedIneffectiveWrite[];
+    /** Why introducers are unknown, for the attribution block (§13). */
+    introducers: Introducers;
+}
+/**
+ * The attribution of a scan over `artifacts` (§10), with the lockfile it was given, or null. The lockfile only adds
+ * evidence, never a key (ADR 0006):
+ *
+ * - A lockfile that can't be read or parsed, or a format version R1 doesn't read (`package-lock.json` v1), gives
+ *   `no-lockfile`, with the format version as evidence, as no lockfile does.
+ * - A lockfile with no installed copy of a package at the version a store path in the scan's maps gives it is stale
+ *   for the whole scan: `lockfile-stale`, and it derives nothing.
+ * - Otherwise a package's install path gives it its lockfile version (§10 Version), and a package path the lockfile
+ *   says isn't installed is vendored, in the installed package around it (§10 Provenance). First-party code gets its
+ *   workspace as evidence.
+ * - The importer is picked as `importerOf` says; with none, `importer-unresolved`, and no introducers.
+ */
+export declare function attribution(artifacts: readonly MappedArtifact[], rules: AttributionRules, lockfileInput: LockfileInput | null): ScanAttribution;