monkeypatchlist 0.0.0-stage → 0.1.0

package/dist/packages/attribution/lib/containing-package.js

@@ -0,0 +1,304 @@
+// The containing package (§10 Containing package): read from a source map's raw `sources` entry alone, after
+// normalizing it.
+/**
+ * The relative `sourceRoot` a map's entries may be joined to (§10 step 1), or null: a URL or an absolute or
+ * drive-letter root is ignored, and so is an empty or non-string one.
+ */
+export function relativeSourceRoot(sourceRoot) {
+    if (typeof sourceRoot !== 'string' || sourceRoot === '')
+        return null;
+    if (scheme.test(sourceRoot) || absolute(sourceRoot))
+        return null;
+    return sourceRoot;
+}
+/** Whether a path is absolute: it starts with `/` or `\`, or with a drive letter. */
+function absolute(path) {
+    return /^[/\\]/.test(path) || driveLetter.test(path);
+}
+/** A URL scheme at the start of a string. */
+const scheme = /^[A-Za-z][A-Za-z0-9+.-]*:/;
+/** A drive letter at the start of a path, which is no scheme. */
+const driveLetter = /^[A-Za-z]:(?:[/\\]|$)/;
+/**
+ * The recognized schemes (§10 Source schemes), each with the prefix stripped before the path is read. A relative, an
+ * absolute or a drive-letter path has none. `turbopack:///[turbopack]/…` is the bundler's runtime.
+ */
+const recognized = [
+    [/^webpack:\/\/([^/]*)(?:\/|$)/, (match) => `webpack:${match[1]}`],
+    [/^webpack-internal:\/\/\//, () => 'webpack-internal'],
+    [/^turbopack:\/\/\/\[project\]\//, () => 'turbopack'],
+    [/^vite:/, () => 'vite'],
+    [/^file:\/\//, () => 'absolute'],
+];
+/** The synthetic and bundler-runtime sources, once the scheme is stripped (§10 step 1). */
+const synthetic = [
+    /^webpack\/runtime\//,
+    /^webpack\/bootstrap/,
+    /^<anon>$/,
+    /^ignored\|/,
+    /^external\s/,
+];
+/**
+ * What a raw `sources` entry names, under a map's relative `sourceRoot` (§10 Containing package):
+ *
+ * 1. **Normalize.** A null or empty entry, or one holding `\0` (a Rollup virtual module), is synthetic. A BOM or a
+ *    `)]}'` prefix is stripped, then a recognized scheme; any other scheme is foreign. A synthetic source is then
+ *    recognized on the entry, before any root is joined: `webpack/runtime/*`, `webpack/bootstrap`, `<anon>`,
+ *    `turbopack:///[turbopack]/…`, `ignored|…` and `external "x"`, and an entry whose resource path is empty.
+ *    Only an entry that had no scheme and isn't absolute is joined to the root, as a string, with a `/` between them
+ *    unless the root ends with one. Loader prefixes (up to the last `!`), a `?query` (webpack's `?hash`
+ *    included) and `*` suffixes are stripped, so the resource path decides. The path is percent-decoded, `\` becomes
+ *    `/`, and `.` and `x/..` segments collapse (leading `..` stay). A `file://`, absolute or drive-letter path is
+ *    `absolute`, whatever scheme wraps it.
+ * 2. **Read the name** from the segment after the last `node_modules` segment that a dot segment doesn't follow, or the
+ *    two segments after it for a scoped package. Under Yarn's pnpm linker the package is in
+ *    `node_modules/.store/<slug>-npm-<version>-<hash>/package/` (or `<slug>-virtual-<hash>`): an unscoped slug is its
+ *    name, and a scoped one is lossy. A path that climbs out of its package inside `node_modules` names none.
+ */
+export function sourceKind(source, sourceRoot) {
+    if (source === null || source === '' || source.includes('\0'))
+        return { kind: 'synthetic' };
+    let path = source;
+    if (path.startsWith('\ufeff'))
+        path = path.slice(1);
+    if (path.startsWith(")]}'"))
+        path = path.slice(4);
+    if (/^turbopack:\/\/\/\[turbopack\]\//.test(path))
+        return { kind: 'synthetic' };
+    const match = recognized.map(([pattern, name]) => [pattern.exec(path), name]).find(([found]) => found);
+    let namespace = 'relative';
+    if (match !== undefined) {
+        const [found, name] = match;
+        namespace = name(found);
+        path = path.slice(found[0].length);
+        // `file:///C:/x` names the drive-letter path `C:/x`.
+        if (namespace === 'absolute' && /^\/[A-Za-z]:(?:[/\\]|$)/.test(path))
+            path = path.slice(1);
+    }
+    else if (scheme.test(path) && !driveLetter.test(path))
+        return { kind: 'foreign-scheme' };
+    if (synthetic.some((pattern) => pattern.test(path)))
+        return { kind: 'synthetic' };
+    // An entry whose resource path is empty once the namespace, `./` and `?query` are stripped is synthetic too, such
+    // as Next's context and hash stubs `webpack://_N_E/?6505`, whatever the root.
+    if (segments(normalized(resourcePath(path))).length === 0)
+        return { kind: 'synthetic' };
+    if (absolute(path))
+        namespace = 'absolute';
+    else if (namespace === 'relative' && sourceRoot !== null) {
+        path = `${sourceRoot}${sourceRoot.endsWith('/') ? '' : '/'}${path}`;
+    }
+    const read = segments(normalized(resourcePath(path)));
+    return packageOf(read, { namespace, segments: read });
+}
+/** A path with its loader prefixes (up to the last `!`), `?query` (from the first `?`) and `*` suffixes stripped. */
+function resourcePath(path) {
+    const resource = path.slice(path.lastIndexOf('!') + 1);
+    const query = resource.indexOf('?');
+    return (query >= 0 ? resource.slice(0, query) : resource).replace(/\*+$/, '');
+}
+/** A path percent-decoded, with POSIX separators. */
+const normalized = (path) => percentDecoded(path).replaceAll('\\', '/');
+/** The path's segments, with empty and `.` segments dropped and each `x/..` collapsed. Leading `..` segments stay. */
+function segments(path) {
+    const out = [];
+    for (const segment of path.split('/')) {
+        if (segment === '' || segment === '.')
+            continue;
+        if (segment === '..' && out.length > 0 && out.at(-1) !== '..')
+            out.pop();
+        else
+            out.push(segment);
+    }
+    return out;
+}
+/** A Yarn pnpm-linker store entry's directory: `<slug>-npm-<version>-<hash>` or `<slug>-virtual-<hash>`. */
+const yarnStoreEntry = /^(.+)-(?:npm-.+|virtual)-[0-9a-f]{10}$/;
+/** A Yarn pnpm-linker store entry's directory with a version: `<slug>-npm-<version>-<hash>`. */
+const yarnStoreVersion = /^(.+)-npm-(.+)-[0-9a-f]{10}$/;
+/** A Yarn cache archive, local or global: `<slug>-npm-<version>-<hash>[-<hash>].zip`. */
+const yarnArchive = /^(.+)-npm-(.+?)-[0-9a-f]{10}(?:-[0-9a-f]+)?\.zip$/;
+/**
+ * A semver version at the start of a store entry's version part, and what may follow it: nothing, or pnpm's peer and
+ * patch suffixes (`_react@18.2.0`, `(react@18.2.0)`).
+ */
+const storeVersion = /^(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?)(?:[_(].*)?$/;
+/** The version a store entry's version part gives, or null when it isn't a registry version (a git or file spec). */
+function versionIn(part) {
+    return storeVersion.exec(part)?.[1] ?? null;
+}
+/** Yarn's slug of a package name: a scoped name's `/` becomes `-`. */
+const yarnSlug = (name) => name.replace('/', '-');
+/**
+ * The version a store path gives the package `name`, whose `node_modules` segment is at `at` (§10 Version): only when
+ * the store entry right in front of that segment names the package itself, so a package inside another package's entry
+ * (vendored code) gets none.
+ *
+ * - pnpm: `.pnpm/<name>@<version>/node_modules/<name>`, a scope's `/` written `+`
+ * - Bun: `.bun/<name>@<version>/node_modules/<name>`, likewise
+ * - Yarn: `<slug>-npm-<version>-<hash>.zip/node_modules/<name>`, in the project's cache or the global one
+ * - pnpm's global virtual store: `<store>/v<n>/links/<name>/<version>/<hash>/node_modules/<name>`
+ */
+function storePathVersion(path, at, name) {
+    const entry = path[at - 1];
+    if (entry === undefined)
+        return null;
+    const store = path[at - 2];
+    if (store === '.pnpm' || store === '.bun') {
+        const prefix = `${name.replace('/', '+')}@`;
+        return entry.startsWith(prefix) ? versionIn(entry.slice(prefix.length)) : null;
+    }
+    const archive = yarnArchive.exec(entry);
+    if (archive !== null)
+        return archive[1] === yarnSlug(name) ? versionIn(archive[2]) : null;
+    const parts = name.split('/');
+    const links = at - 3 - parts.length;
+    if (path[links] === 'links' && /^v\d+$/.test(path[links - 1] ?? '')) {
+        const named = parts.every((part, k) => path[links + 1 + k] === part);
+        return named ? versionIn(path[at - 2]) : null;
+    }
+    return null;
+}
+/**
+ * The vendoring package of the package `name`, whose `node_modules` segment is at `at`, as `name@version` (§10
+ * Provenance, vendored code; ADR 0006), or null: a **store-name mismatch**, where the nearest store entry the path lies
+ * in names another package. Every store layout §10 Version reads counts:
+ *
+ * - pnpm `.pnpm/<n>@<v>` and Bun `.bun/<n>@<v>`, a scope's `/` written `+`
+ * - Yarn's cache archives `<slug>-npm-<v>-<hash>.zip`, named by an unscoped slug, or for a scoped slug by the package
+ *   directory inside the archive
+ * - Yarn's pnpm-linker store `.store/<slug>-npm-<v>-<hash>`, named by an unscoped slug
+ * - pnpm's global virtual store `v<n>/links/<name>/<v>/<hash>`
+ *
+ * So `.pnpm/telemetry-agent@1.2.0/node_modules/telemetry-agent/node_modules/tiny-helper/…` and the collapsed
+ * `.pnpm/telemetry-agent@1.2.0/node_modules/tiny-helper/…`, which a hoisted build of telemetry-agent composes, are both
+ * tiny-helper vendored in telemetry-agent@1.2.0. A store entry that gives no registry version (a git or file
+ * dependency), or whose package can't be named (a lossy scoped slug), detects nothing.
+ */
+function vendoringPackage(path, at, name) {
+    for (let j = at - 1; j >= 0; j--) {
+        const owner = storeOwner(path, j, at);
+        if (owner === undefined)
+            continue;
+        return owner === null || owner.name === name ? null : `${owner.name}@${owner.version}`;
+    }
+    return null;
+}
+/**
+ * The package the store entry at `j` names, when `path[j]` is a store entry before the segment `at`: null when it is
+ * one but can't be named with a registry version, undefined when it is none.
+ */
+function storeOwner(path, j, at) {
+    const entry = path[j];
+    const store = path[j - 1];
+    if ((store === '.pnpm' || store === '.bun') && path[j + 1] === 'node_modules') {
+        const split = entry.indexOf('@', 1);
+        if (split <= 0)
+            return null;
+        const version = versionIn(entry.slice(split + 1));
+        const named = entry.slice(0, split);
+        const name = named.startsWith('@') ? named.replace('+', '/') : named;
+        return version === null ? null : { name, version };
+    }
+    const archive = yarnArchive.exec(entry);
+    if (archive !== null && path[j + 1] === 'node_modules') {
+        const version = versionIn(archive[2]);
+        if (version === null)
+            return null;
+        if (!archive[1].startsWith('@'))
+            return { name: archive[1], version };
+        // A scoped slug is lossy: the package directory inside the archive names it, when the path passes through it.
+        const scope = path[j + 2];
+        const inner = path[j + 3];
+        if (scope?.startsWith('@') !== true || inner === undefined || j + 3 >= at)
+            return null;
+        const name = `${scope}/${inner}`;
+        return yarnSlug(name) === archive[1] ? { name, version } : null;
+    }
+    if (store === '.store' && path[j - 2] === 'node_modules' && yarnStoreEntry.test(entry)) {
+        const versioned = yarnStoreVersion.exec(entry);
+        const version = versioned === null ? null : versionIn(versioned[2]);
+        if (versioned === null || version === null || versioned[1].startsWith('@'))
+            return null;
+        return { name: versioned[1], version };
+    }
+    if (path[j + 1] === 'node_modules') {
+        for (const parts of [1, 2]) {
+            const links = j - 2 - parts;
+            if (path[links] !== 'links' || !/^v\d+$/.test(path[links - 1] ?? ''))
+                continue;
+            const name = path.slice(links + 1, links + 1 + parts).join('/');
+            if (parts === 2 && !name.startsWith('@'))
+                continue;
+            const version = versionIn(path[j - 1]);
+            return version === null ? null : { name, version };
+        }
+    }
+    return undefined;
+}
+/**
+ * Whether a normalized path climbs out of its own package inside `node_modules` (§10 Escaped sources): it holds,
+ * as whole segments anywhere, `node_modules/src/`, `node_modules/@<scope>/src/` or `node_modules/node_modules/`, as
+ * esbuild gives when it composes a dependency's own shipped maps (Sentry 7's `node_modules/@sentry/src/…`).
+ */
+function climbsOutOfPackage(path) {
+    return path.some((segment, i) => {
+        if (segment !== 'node_modules')
+            return false;
+        const next = path[i + 1];
+        if (next === 'node_modules' || next === 'src')
+            return i + 2 < path.length;
+        return next?.startsWith('@') === true && path[i + 2] === 'src' && i + 3 < path.length;
+    });
+}
+/** The package a normalized path is in: the last `node_modules` segment that a dot segment doesn't follow decides. */
+function packageOf(path, read) {
+    if (climbsOutOfPackage(path))
+        return { kind: 'escaped', path: read };
+    for (let i = path.length - 1; i >= 0; i--) {
+        if (path[i] !== 'node_modules')
+            continue;
+        const next = path[i + 1];
+        if (next === undefined)
+            continue;
+        if (next.startsWith('.')) {
+            const slug = next === '.store' && path[i + 3] === 'package' ? yarnStoreEntry.exec(path[i + 2] ?? '')?.[1] : undefined;
+            if (slug === undefined)
+                continue;
+            if (slug.startsWith('@'))
+                return { kind: 'yarn-slug', slug, path: read };
+            const versioned = yarnStoreVersion.exec(path[i + 2]);
+            const version = versioned === null ? null : versionIn(versioned[2]);
+            const directory = path.slice(0, i + 4);
+            const vendoredBy = vendoringPackage(path, i, slug);
+            return { kind: 'package', name: slug, subpath: path.slice(i + 4), path: read, directory, version, vendoredBy };
+        }
+        const scoped = next.startsWith('@');
+        if (scoped && path[i + 2] === undefined)
+            continue;
+        const name = scoped ? `${next}/${path[i + 2]}` : next;
+        const end = i + (scoped ? 3 : 2);
+        const version = storePathVersion(path, i, name);
+        const vendoredBy = vendoringPackage(path, i, name);
+        return { kind: 'package', name, subpath: path.slice(end), path: read, directory: path.slice(0, end), version, vendoredBy };
+    }
+    return { kind: 'other', path: read };
+}
+const decoder = new TextDecoder('utf-8');
+/** A path percent-decoded as UTF-8 (URL § percent-decode): an invalid escape is left as it is. */
+function percentDecoded(text) {
+    if (!text.includes('%'))
+        return text;
+    const bytes = [...new TextEncoder().encode(text)];
+    const out = [];
+    for (let i = 0; i < bytes.length; i++) {
+        const hex = String.fromCharCode(bytes[i + 1] ?? 0, bytes[i + 2] ?? 0);
+        if (bytes[i] === 0x25 && /^[0-9a-f]{2}$/i.test(hex)) {
+            out.push(Number.parseInt(hex, 16));
+            i += 2;
+        }
+        else
+            out.push(bytes[i]);
+    }
+    return decoder.decode(Uint8Array.from(out));
+}

package/dist/packages/attribution/lib/first-party.d.ts

@@ -0,0 +1,37 @@
+import type { SourceKind, SourcePath } from './containing-package.ts';
+/**
+ * The frame of a map, for its relative sources: its build-relative directory's segments (§10), or null for a
+ * fetched map, which has no place in the build. A relative entry is resolved against it.
+ */
+export type MapDirectory = readonly string[] | null;
+/** A verified map of local-build code, as root inference reads it: its sources' kinds, and its directory. */
+export interface MapSources {
+    kinds: readonly SourceKind[];
+    directory: MapDirectory;
+}
+/**
+ * How a source that names no package is attributed (§10 Provenance):
+ * - `first-party`: inside its namespace's inferred root, named by its root-relative `path`, and `inferred` when that
+ *   root lies above the bundler base (§9 `first-party-inferred`)
+ * - `outside`: outside the root, or in a namespace with none, so it is escaped
+ * - `unplaced`: a relative entry of a map with no place in the build, a fetched one, whose code is remote and keyed
+ *   by its URL, not by a root
+ */
+export type Classified = {
+    kind: 'first-party';
+    path: string;
+    inferred: boolean;
+} | {
+    kind: 'outside';
+} | {
+    kind: 'unplaced';
+};
+/**
+ * Infers one root per bundler namespace across the scan (§10 Provenance): the common ancestor of every
+ * in-project package-source prefix in it. A namespace with none takes the bundler's own base: the webpack context or
+ * the project root for `webpack://`, `webpack-internal:///`, `turbopack:///[project]/` and `vite:` paths, and for
+ * relative paths each map's own directory (§10 Roots with no shared place). Absolute paths, under every wrapper, share
+ * one namespace with no base, so with no package source among them they have no root. Returns how each source
+ * that names no package is attributed.
+ */
+export declare function firstPartyRoots(maps: readonly MapSources[]): (path: SourcePath, directory: MapDirectory) => Classified;

package/dist/packages/attribution/lib/first-party.js

@@ -0,0 +1,153 @@
+// First-party code (§10 Provenance, §11 Attribution keys): the inferred root of each bundler namespace, and the
+// root-relative path first-party code is named by.
+/**
+ * A source's path resolved into its namespace's frame: a relative entry against its map's build-relative
+ * directory, into the one namespace the relative-path maps of the build share, and any other path as it is. Null for
+ * a relative entry of a map whose directory isn't known.
+ */
+function resolved(path, directory) {
+    const segments = path.namespace === 'relative' ? (directory === null ? null : [...directory, ...path.segments]) : path.segments;
+    if (segments === null)
+        return null;
+    return { namespace: path.namespace, place: placeOf(collapsed(segments)) };
+}
+/** Segments with each `x/..` collapsed; leading `..` segments stay. */
+function collapsed(segments) {
+    const out = [];
+    for (const segment of segments) {
+        if (segment === '..' && out.length > 0 && out.at(-1) !== '..')
+            out.pop();
+        else
+            out.push(segment);
+    }
+    return out;
+}
+function placeOf(segments) {
+    let up = 0;
+    while (segments[up] === '..')
+        up++;
+    return { up, down: segments.slice(up) };
+}
+/**
+ * The in-project package-source prefix of a package source (§10 Provenance): the place in front of its first
+ * `node_modules` or `.yarn` segment. Null for a source in the pnpm or Bun global store or Yarn's global cache, which
+ * don't count.
+ */
+function packagePrefix(place) {
+    const { down } = place;
+    if (globalStore(down))
+        return null;
+    const at = down.findIndex((segment) => segment === 'node_modules' || segment === '.yarn');
+    if (at < 0)
+        return null;
+    return { up: place.up, down: down.slice(0, at) };
+}
+/**
+ * Whether a path lies in a global store: the pnpm global virtual store (`<store>/v<n>/links/…`), Bun's
+ * (`.bun/install/cache/…`), or Yarn's global cache (`.yarn/berry/cache/…`).
+ */
+function globalStore(down) {
+    return down.some((segment, i) => (segment === 'links' && /^v\d+$/.test(down[i - 1] ?? '')) ||
+        (segment === '.bun' && down[i + 1] === 'install' && down[i + 2] === 'cache') ||
+        (segment === '.yarn' && down[i + 1] === 'berry' && down[i + 2] === 'cache'));
+}
+/**
+ * A place as tokens in a frame `frame` levels above the namespace's: each level of the frame the place doesn't name is
+ * a marker, which stands for the same unnamed directory in every place, and differs from every named segment.
+ */
+function tokens(place, frame) {
+    return [...Array.from({ length: frame - place.up }, (_, level) => `\0${level}`), ...place.down];
+}
+/** The common ancestor of places in one namespace's frame (§10 Provenance). */
+function commonAncestor(places) {
+    const frame = Math.max(...places.map(({ up }) => up));
+    const all = places.map((place) => tokens(place, frame));
+    const [first = []] = all;
+    let length = 0;
+    while (length < first.length && all.every((each) => each[length] === first[length]))
+        length++;
+    const common = first.slice(0, length);
+    const markers = common.filter((token) => token.startsWith('\0')).length;
+    return { up: frame - markers, down: common.slice(markers) };
+}
+/**
+ * The root-relative path of a place under `root` (§11 Root-relative paths), or null when the place lies outside
+ * it. The root's prefix is stripped where the path has it, and a level of the frame the path climbs to without naming
+ * it is dropped with its `../`.
+ */
+function rootRelative(place, root) {
+    const frame = Math.max(place.up, root.up);
+    const path = tokens(place, frame);
+    const prefix = tokens(root, frame);
+    if (!prefix.every((token, i) => path[i] === token))
+        return null;
+    const rest = path.slice(prefix.length).filter((token) => !token.startsWith('\0'));
+    return rest.length === 0 ? null : rest.join('/');
+}
+/** Whether `root` lies strictly above `base`: it is an ancestor of `base`, and not `base` itself (§9). */
+function above(root, base) {
+    const frame = Math.max(root.up, base.up);
+    const ancestor = tokens(root, frame);
+    const of = tokens(base, frame);
+    return ancestor.length < of.length && ancestor.every((token, i) => of[i] === token);
+}
+/**
+ * The bundler namespaces whose base is the webpack context or the project root, the frame of their paths. `vite:` is
+ * based like webpack (§10 Roots with no shared place).
+ */
+const basedNamespaces = /^(?:webpack:.*|webpack-internal|turbopack|vite)$/;
+/**
+ * Infers one root per bundler namespace across the scan (§10 Provenance): the common ancestor of every
+ * in-project package-source prefix in it. A namespace with none takes the bundler's own base: the webpack context or
+ * the project root for `webpack://`, `webpack-internal:///`, `turbopack:///[project]/` and `vite:` paths, and for
+ * relative paths each map's own directory (§10 Roots with no shared place). Absolute paths, under every wrapper, share
+ * one namespace with no base, so with no package source among them they have no root. Returns how each source
+ * that names no package is attributed.
+ */
+export function firstPartyRoots(maps) {
+    const prefixes = new Map();
+    for (const { kinds, directory } of maps) {
+        for (const kind of kinds) {
+            if (kind.kind === 'synthetic' || kind.kind === 'foreign-scheme' || kind.kind === 'other')
+                continue;
+            const at = resolved(kind.path, directory);
+            const prefix = at === null ? null : packagePrefix(at.place);
+            if (at === null || prefix === null)
+                continue;
+            prefixes.set(at.namespace, [...(prefixes.get(at.namespace) ?? []), prefix]);
+        }
+    }
+    const roots = new Map();
+    const rootOf = (namespace) => {
+        let root = roots.get(namespace);
+        if (root !== undefined)
+            return root;
+        const found = prefixes.get(namespace);
+        if (found !== undefined)
+            root = commonAncestor(found);
+        else if (basedNamespaces.test(namespace))
+            root = { up: 0, down: [] };
+        // Relative maps with no package source anywhere each take their own directory as root (§10 Roots with no shared
+        // place).
+        else if (namespace === 'relative')
+            root = 'own';
+        else
+            root = 'none';
+        roots.set(namespace, root);
+        return root;
+    };
+    return (path, directory) => {
+        const at = resolved(path, directory);
+        if (at === null)
+            return { kind: 'unplaced' };
+        // The bundler base: the map's directory for relative paths, the webpack context or project root otherwise. An
+        // absolute path has none.
+        const base = at.namespace === 'relative' ? placeOf(directory ?? []) : at.namespace === 'absolute' ? null : { up: 0, down: [] };
+        const found = rootOf(at.namespace);
+        const root = found === 'own' ? base : found;
+        const name = root === 'none' || root === null ? null : rootRelative(at.place, root);
+        if (root === 'none' || root === null || name === null)
+            return { kind: 'outside' };
+        return { kind: 'first-party', path: name, inferred: base !== null && above(root, base) };
+    };
+}

package/dist/packages/attribution/lib/lockfile-graph.d.ts

@@ -0,0 +1,99 @@
+/** An installed package: its key in the lockfile, its name and version (`''` when the lockfile records none). */
+export interface Node {
+    key: string;
+    name: string;
+    version: string;
+}
+/**
+ * A workspace (importer): its folder relative to the lockfile's directory (`''` for the root), and its name and version
+ * as the lockfile records them, which are evidence (§10 Provenance) and what `lockfile.importer` may name.
+ */
+export interface Workspace {
+    folder: string;
+    name: string | null;
+    version: string | null;
+}
+/**
+ * Where a lockfile puts a package directory (§10 Walk, Vendored):
+ * - `installed`: the nodes it is (several only for one version's peer variants)
+ * - `vendored`: the lockfile says it isn't installed; `around` is the installed package whose directory holds it, if any
+ * - `unplaced`: the lockfile can't say which copy it is
+ */
+export type Placed = {
+    kind: 'installed';
+    nodes: Node[];
+} | {
+    kind: 'vendored';
+    around: Node[];
+} | {
+    kind: 'unplaced';
+};
+/** A lockfile read into an installed-package graph. */
+export interface Lockfile {
+    format: 'npm' | 'bun' | 'pnpm' | 'yarn';
+    /** Whether it is keyed by install path, so a strong version source (§10 Version): `package-lock.json`, `bun.lock`. */
+    keyedByInstallPath: boolean;
+    /** How certain what it derives is: `yarn.lock`'s facts are capped at `medium` (§10 Formats). */
+    confidence: 'high' | 'medium';
+    workspaces: Workspace[];
+    /**
+     * Why no importer can be picked, whatever the first-party paths are: a manifest that the importer's direct
+     * dependencies needed and that is missing or unreadable. Null otherwise.
+     */
+    unresolved: string | null;
+    /** Where the lockfile puts a package's directory, as a map path gives it. */
+    place(directory: readonly string[]): Placed;
+    /** The nodes of `name` at `version`, wherever installed. */
+    named(name: string, version: string): Node[];
+    /**
+     * The introducers of the nodes `from` for the importer `workspace` (§10 Walk): its direct dependencies whose
+     * installed tree includes one of them, as `name@version`, sorted. A direct dependency introduces itself.
+     */
+    introducers(from: readonly Node[], workspace: Workspace): string[];
+}
+/** A lockfile read, or why none is usable, with the format version as evidence. */
+export type ReadLockfile = {
+    lockfile: Lockfile;
+} | {
+    unusable: string;
+};
+/** A node's `name@version`, or its name alone when the lockfile records no version. */
+export declare const nameAtVersion: ({ name, version }: Node) => string;
+/** A lockfile over `nodes`, whose dependency edges and workspaces' direct dependencies are resolved by the format. */
+export declare function graph(parts: {
+    format: Lockfile['format'];
+    keyedByInstallPath: boolean;
+    confidence: Lockfile['confidence'];
+    nodes: Iterable<Node>;
+    workspaces: Workspace[];
+    unresolved?: string | null;
+    /** The nodes a node depends on: `dependencies`, `optionalDependencies` and resolved peers. */
+    edges: (node: Node) => Node[];
+    /** A workspace's direct dependencies, its dev dependencies included. */
+    direct: (workspace: Workspace) => Node[];
+    place: (directory: readonly string[]) => Placed;
+}): Lockfile;
+/** The package names of a `node_modules/<a>/node_modules/<b>` chain, or null when it is no such chain. */
+export declare function installChain(segments: readonly string[]): string[] | null;
+/**
+ * Where a lockfile that isn't keyed by install path (`pnpm-lock.yaml`, `yarn.lock`) puts a package directory: by the
+ * names of its `node_modules` chain. The first name is the workspace's (the folder before the chain) or else the root's
+ * direct dependency of that name, or else the lockfile's only version of it; each further name is what the package
+ * before it depends on by that name. A name the lockfile doesn't install at all is vendored, in the package before it.
+ * Anything else is unplaced: the lockfile doesn't record where its copies are installed.
+ */
+export declare function placeByName(directory: readonly string[], byName: ReadonlyMap<string, Node[]>, workspaces: readonly Workspace[], edges: (node: Node) => Node[], direct: (workspace: Workspace) => Node[]): Placed;
+/** A `package.json` manifest's dependency lists: only these are read from it. */
+export interface Manifest {
+    name: string | null;
+    version: string | null;
+    /** `dependencies`, `optionalDependencies` and `peerDependencies`, by name, with their ranges. */
+    production: [string, string][];
+    /** `devDependencies`, by name, with their ranges. */
+    development: [string, string][];
+}
+/** A manifest's text read, or null when it is missing or isn't a manifest. */
+export declare function readManifest(text: string | null | undefined): Manifest | null;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** A folder relative to the lockfile's directory, normalized: `.` is `''`, and `./`, `x/..` and a trailing `/` go. */
+export declare function normalizeFolder(folder: string): string;