monkeypatchlist 0.0.0-stage → 0.1.0

package/dist/packages/attribution/index.js

@@ -0,0 +1,444 @@
+// Attribution (§19, module 5): adds where each occurrence's code came from (§10). It never changes the resolver's fields,
+// and knows nothing of how a target was resolved. It never reads chunk names.
+import { attributionConfidence } from "../confidence/index.js";
+import { sourceKind } from "./lib/containing-package.js";
+import { firstPartyRoots } from "./lib/first-party.js";
+import { importerOf, introducerReasons, nameAtVersion, readLockfile, workspaceOf, } from "./lib/lockfile.js";
+import { pathRuling } from "./lib/path-rules.js";
+import { normalizeRemoteUrl } from "./lib/remote-url.js";
+import { lineStarts, originalAt, position, readMap, tokenAppears, } from "./lib/source-map.js";
+export { introducerReasons };
+export { lockfileManifests } from "./lib/lockfile.js";
+/** How the code behind a finding got into its artifact (§10 Provenance). */
+export const provenances = ['first-party', 'bundled-dependency', 'remote', 'inline', 'unknown'];
+/**
+ * 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 const versionSources = ['store-path', 'lockfile', 'package-json', 'version-constant', 'banner'];
+/** The strong version sources, the only ones that feed `packages` and the `previousVersion` note (§10, §11). */
+export const strongVersionSources = new Set(['store-path', 'lockfile']);
+/**
+ * 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 function attribute(occurrences, artifacts, rules) {
+    return attribution(artifacts, rules, null).attribute(occurrences);
+}
+/** Attributes each occurrence of an ineffective write (§3 Record), as `attribute` attributes a finding's. */
+export function attributeIneffective(writes, artifacts, rules) {
+    return attribution(artifacts, rules, null).attributeIneffective(writes);
+}
+/**
+ * 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 function attribution(artifacts, rules, lockfileInput) {
+    const byId = new Map(artifacts.map((artifact) => [artifact.id ?? artifact.url, artifact]));
+    const verified = new Map();
+    const verifiedMapOf = (artifact) => {
+        const id = artifact.id ?? artifact.url;
+        let map = verified.get(id);
+        if (map === undefined)
+            verified.set(id, (map = verifiedMap(artifact)));
+        return map;
+    };
+    // One root per bundler namespace, inferred from every local-build map in the scan (§10 Provenance).
+    const local = artifacts.flatMap((artifact) => {
+        const map = artifact.origin === 'local-build' ? verifiedMapOf(artifact) : null;
+        return map === null ? [] : [map];
+    });
+    const roots = firstPartyRoots(local);
+    // The curated path data decides before the root does (§10 Escaped sources).
+    const classify = (path, directory) => {
+        const ruling = pathRuling(path, rules);
+        if (ruling.kind === 'rule')
+            return ruling;
+        if (ruling.kind === 'escaped')
+            return { kind: 'outside' };
+        return roots(path, directory);
+    };
+    const { lock, introducers } = lockState(lockfileInput, local, classify);
+    const each = (write) => {
+        const artifact = byId.get(write.artifact);
+        if (artifact === undefined)
+            throw new Error(`an occurrence names an unknown artifact ${write.artifact}`);
+        const { url, hash, origin } = artifact;
+        const { lookup, trace, ...owned } = write;
+        // A helper write's lookup point may be a call in another artifact of the write's origin (§10): that artifact's
+        // map is read there.
+        const at = lookup.artifact === undefined ? artifact : byId.get(lookup.artifact);
+        if (at === undefined)
+            throw new Error(`an occurrence's lookup names an unknown artifact ${lookup.artifact}`);
+        const found = attributionOf(artifact, lookup, verifiedMapOf, classify, rules.remoteUrlNormalization, lock, at);
+        const attributed = {
+            // `artifact` is replaced by the artifact's identity.
+            ...owned,
+            artifact: { url, hash, origin },
+            attribution: found.attribution,
+            original: found.original,
+            evidence: found.evidence,
+            // A token check at a lookup point in another artifact names it (§14).
+            trace: [
+                ...trace,
+                ...found.trace.map((step) => (at === artifact || step.kind !== 'token-check' ? step : { ...step, artifact: at.url })),
+            ],
+        };
+        return { attributed, found };
+    };
+    return {
+        attribute: (occurrences) => occurrences.map((occurrence) => {
+            const { attributed, found } = each(occurrence);
+            const { confidence, ...rest } = attributed;
+            // Introducers apply only to bundled-dependency code (§10 Record).
+            const introducedBy = found.attribution.provenance === 'bundled-dependency' ? found.introducedBy : undefined;
+            return {
+                ...rest,
+                ...(introducedBy === undefined ? {} : { introducedBy }),
+                confidence: { ...confidence, attribution: attributionConfidence(found.reasons) },
+            };
+        }),
+        attributeIneffective: (writes) => writes.map((write) => each(write).attributed),
+        introducers,
+    };
+}
+/** The scan's lockfile state, and why introducers are unknown (§10 Unknown is not empty). */
+function lockState(input, maps, classify) {
+    const unknown = (reason, evidence) => ({ lock: null, introducers: { reason, evidence } });
+    if (input === null)
+        return unknown('no-lockfile', null);
+    const read = readLockfile(input.path, input.text, input.manifests ?? {});
+    if ('unusable' in read)
+        return unknown('no-lockfile', read.unusable);
+    const { lockfile } = read;
+    // Any disagreement with a store-path version makes the whole lockfile stale.
+    const disagreements = new Set();
+    const firstParty = new Set();
+    for (const map of maps) {
+        map.kinds.forEach((kind, i) => {
+            if (kind.kind === 'package') {
+                // A store path gives a version to its own package, or, for vendored code (a store-name mismatch), to the
+                // vendoring package whose store entry holds it.
+                const stored = [
+                    ...(kind.version === null || kind.vendoredBy !== null ? [] : [`${kind.name}@${kind.version}`]),
+                    ...(kind.vendoredBy === null ? [] : [kind.vendoredBy]),
+                ];
+                for (const each of stored) {
+                    const at = each.lastIndexOf('@');
+                    if (lockfile.named(each.slice(0, at), each.slice(at + 1)).length === 0) {
+                        disagreements.add(`a store path gives ${each}, which the lockfile doesn't install`);
+                    }
+                }
+            }
+            if (kind.kind === 'other' && map.map.sources[i]?.ignored !== true) {
+                const classified = classify(kind.path, map.directory);
+                if (classified.kind === 'first-party')
+                    firstParty.add(classified.path);
+            }
+        });
+    }
+    if (disagreements.size > 0)
+        return unknown('lockfile-stale', [...disagreements].sort(compareText)[0]);
+    // A missing or unreadable manifest leaves the direct dependencies unknown.
+    if (lockfile.unresolved !== null) {
+        return { lock: { lockfile, importer: null }, introducers: { reason: 'importer-unresolved', evidence: lockfile.unresolved } };
+    }
+    const importer = importerOf(lockfile, input.importer, [...firstParty]);
+    if (importer === null) {
+        const why = input.importer !== null
+            ? `the importer ${input.importer} is no workspace of the lockfile`
+            : firstParty.size === 0
+                ? 'no first-party source picks one of the lockfile\'s workspaces'
+                : `the first-party sources lie in several workspaces: ${[
+                    ...new Set([...firstParty].map((path) => workspaceOf(lockfile, path)?.folder ?? '')),
+                ]
+                    .map((folder) => (folder === '' ? '.' : folder))
+                    .sort(compareText)
+                    .join(', ')}`;
+        return { lock: { lockfile, importer: null }, introducers: { reason: 'importer-unresolved', evidence: why } };
+    }
+    return { lock: { lockfile, importer }, introducers: { reason: null, evidence: null, confidence: lockfile.confidence } };
+}
+const compareText = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+function verifiedMap({ text, map }) {
+    if (map === null)
+        return null;
+    const read = readMap(map.raw);
+    if (read === null)
+        return null;
+    const lineSeparator = /[\u2028\u2029]/.test(text);
+    const kinds = read.sources.map((source) => sourceKind(source.raw, source.sourceRoot));
+    const directory = map.base === null ? null : map.base.split('/').slice(0, -1).filter((segment) => segment !== '');
+    const starts = lineStarts(text, map.reading);
+    return { map: read, starts, method: map.method, lineSeparator, kinds, directory, weakVersions: new Map() };
+}
+const unknown = { key: 'unknown', provenance: 'unknown' };
+/** A found attribution with `reasons`, and no original location, evidence or trace step unless `more` gives them. */
+function found(attribution, reasons, more = {}) {
+    return { attribution, original: null, evidence: {}, trace: [], reasons, ...more };
+}
+/** The attribution of an occurrence in `artifact`, looked up at `lookup` in `at` (§10). */
+function attributionOf(artifact, lookup, verifiedMapOf, classify, normalization, lock, at = artifact) {
+    if (artifact.origin === 'inline')
+        return found({ key: 'inline', provenance: 'inline' }, []);
+    // The map of the artifact the lookup point is in: the write's own, or another of its origin's.
+    const verified = verifiedMapOf(at);
+    if (artifact.origin !== 'local-build') {
+        // Remote code keys `url:` with its normalized URL, and is `high` on it (§9, §11).
+        const remote = { key: `url:${normalizeRemoteUrl(artifact.url, normalization)}`, provenance: 'remote' };
+        if (verified === null)
+            return found(remote, []);
+        // Its verified map still gives original locations, and a package the map names is evidence only (§9). The
+        // lockfile describes the scanned application's install, not remote code, so it adds nothing here (§10).
+        const mapped = mappedAttribution(verified, lookup, classify, null);
+        const named = mapped.attribution.package;
+        const evidence = named === undefined ? mapped.evidence : { ...mapped.evidence, package: named };
+        return found(remote, [], { original: mapped.original, evidence, trace: mapped.trace });
+    }
+    if (verified === null)
+        return found(unknown, ['no-map']);
+    return mappedAttribution(verified, lookup, classify, lock);
+}
+/** The attribution of an occurrence looked up at `lookup` in an artifact's verified map (§10). */
+function mappedAttribution(verified, lookup, classify, lock) {
+    // Raw U+2028/U+2029 can shift the positions a map gives (§5, §9).
+    const shifted = verified.lineSeparator ? ['line-separator'] : [];
+    const { line, column } = position(verified.starts, lookup.generated.start);
+    const mapped = originalAt(verified.map, line, column);
+    if (mapped === null)
+        return found(unknown, [...shifted, 'no-map']);
+    const { source } = mapped;
+    const kind = verified.kinds[mapped.index] ?? sourceKind(null, null);
+    // A synthetic or bundler-runtime source counts as unmapped, and its raw source is kept as evidence (§10).
+    if (kind.kind === 'synthetic')
+        return found(unknown, [...shifted, 'no-map'], { evidence: { source: source.raw } });
+    // Only a null or empty entry has no raw source, and both are synthetic.
+    const candidate = { source: source.raw ?? '', line: mapped.line + 1, column: mapped.column };
+    const result = lookup.token === null || source.content === null
+        ? 'n/a'
+        : tokenAppears(source.content, mapped.line, lookup.token)
+            ? 'passed'
+            : 'failed';
+    const trace = [tokenCheckStep(result, lookup, candidate)];
+    if (result === 'failed') {
+        return found(unknown, [...shifted, 'token-check-failed'], { evidence: { rejected: candidate }, trace });
+    }
+    // Without the token check, the map's position is capped at medium, and a mirrored sidecar is too (§10).
+    const unverified = result === 'n/a'
+        ? ['token-check-n/a', ...(verified.method === 'external-sidecar' ? ['sidecar-not-token-verified'] : [])]
+        : [];
+    const kept = { original: candidate, trace };
+    const reasons = [...unverified, ...shifted];
+    switch (kind.kind) {
+        case 'foreign-scheme':
+            return found(unknown, [...reasons, 'foreign-scheme'], kept);
+        case 'yarn-slug':
+            return found(unknown, [...reasons, 'yarn-slug'], { ...kept, evidence: { slug: kind.slug } });
+        // A composed path that climbs out of its package inside `node_modules` is escaped, wherever the root is.
+        case 'escaped':
+            return found(unknown, [...reasons, 'escaped-source'], kept);
+        case 'package': {
+            const { name, subpath } = kind;
+            // A package's `dist` file may hide vendored code (§9 `prebundled-dist`).
+            const dist = subpath.slice(0, -1).includes('dist');
+            const attribution = { key: `pkg:${name}`, provenance: 'bundled-dependency', package: name };
+            const installed = lock === null ? null : installedAs(lock.lockfile, kind);
+            const vendoredBy = kind.vendoredBy ?? installed?.vendoredBy ?? null;
+            // Only a lockfile keyed by install path is a version source (§10 Version).
+            const version = versionOf(verified, kind, lock?.lockfile.keyedByInstallPath === true ? (installed?.node ?? null) : null);
+            // Vendored code, a store-name mismatch or a package the lockfile says isn't installed, still names the package
+            // its path names (§10 Provenance; ADR 0006).
+            const vendored = vendoredBy === null && installed?.vendored !== true ? [] : ['vendored'];
+            const introducedBy = lock?.importer == null || installed === null || installed.from.length === 0
+                ? undefined
+                : lock.lockfile.introducers(installed.from, lock.importer);
+            return {
+                ...found(attribution, [...reasons, ...(dist ? ['prebundled-dist'] : []), ...vendored], {
+                    ...kept,
+                    evidence: { ...(vendoredBy === null ? {} : { vendoredBy }), ...(version === null ? {} : { version }) },
+                }),
+                ...(introducedBy === undefined ? {} : { introducedBy }),
+            };
+        }
+        case 'other': {
+            const classified = classify(kind.path, verified.directory);
+            switch (classified.kind) {
+                // A source outside the inferred root is escaped (§10 Escaped sources), and so is an absolute path that no
+                // root prefixes.
+                case 'outside':
+                    return found(unknown, [...reasons, 'escaped-source'], kept);
+                // An escaped source a framework path rule matches is a file of the package the rule names, with no version,
+                // and never `high` (§10 Framework path rules).
+                case 'rule': {
+                    const attribution = { key: `pkg:${classified.package}`, provenance: 'bundled-dependency', package: classified.package };
+                    const step = {
+                        kind: 'path-rule',
+                        rule: classified.rule,
+                        package: classified.package,
+                        source: candidate.source,
+                        text: `the framework path rule ${classified.rule} names ${classified.package} for the escaped source ${candidate.source}`,
+                    };
+                    return found(attribution, [...reasons, 'framework-path-rule'], {
+                        ...kept,
+                        evidence: { pathRule: classified.rule },
+                        trace: [...trace, step],
+                    });
+                }
+                // A fetched map's relative entry: remote code, keyed by its URL (§11), not by a root.
+                case 'unplaced':
+                    return found(unknown, reasons, kept);
+                case 'first-party': {
+                    // `ignoreList` only demotes: a listed first-party source is `unknown` (§10).
+                    if (source.ignored)
+                        return found(unknown, [...reasons, 'ignore-list-demoted'], kept);
+                    const attribution = { key: `app:${classified.path}`, provenance: 'first-party' };
+                    // Its workspace is evidence, which only a lockfile gives (§10 Provenance; ADR 0006).
+                    const workspace = lock === null ? undefined : workspaceOf(lock.lockfile, classified.path);
+                    const named = workspace?.name == null ? null : workspace.version === null ? workspace.name : `${workspace.name}@${workspace.version}`;
+                    return found(attribution, [...reasons, ...(classified.inferred ? ['first-party-inferred'] : [])], {
+                        ...kept,
+                        ...(named === null ? {} : { evidence: { workspace: named } }),
+                    });
+                }
+            }
+        }
+    }
+}
+/**
+ * How a fresh lockfile installs a package source (§10): the node its install path matches, the nodes the walk starts
+ * from, and whether it is vendored, with the vendoring package when the lockfile names one.
+ *
+ * - A store path's package is the lockfile's copies of it at the store version.
+ * - Vendored code by a store-name mismatch walks from the vendoring package's copies (§10 Walk).
+ * - Otherwise the install path is matched, by its longest suffix that is a lockfile key. A path the lockfile doesn't
+ *   install is vendored: in the installed package whose directory holds it, which the walk starts from, or in none
+ *   the lockfile names.
+ */
+function installedAs(lockfile, kind) {
+    if (kind.vendoredBy !== null) {
+        const at = kind.vendoredBy.lastIndexOf('@');
+        const from = lockfile.named(kind.vendoredBy.slice(0, at), kind.vendoredBy.slice(at + 1));
+        return { node: null, from, vendored: true, vendoredBy: null };
+    }
+    if (kind.version !== null)
+        return { node: null, from: lockfile.named(kind.name, kind.version), vendored: false, vendoredBy: null };
+    const placed = lockfile.place(kind.directory);
+    switch (placed.kind) {
+        case 'installed':
+            return { node: placed.nodes[0] ?? null, from: placed.nodes, vendored: false, vendoredBy: null };
+        case 'vendored': {
+            const [first] = placed.around;
+            return { node: null, from: placed.around, vendored: true, vendoredBy: first === undefined ? null : nameAtVersion(first) };
+        }
+        case 'unplaced':
+            return { node: null, from: [], vendored: false, vendoredBy: null };
+    }
+}
+/**
+ * A package's version, from its strongest source (§10 Version): the store path it is read from, or else the version a
+ * fresh lockfile installs at its install path, or else a weak content
+ * signal among its own files in the map, the sources in the same package directory: its `package.json` naming it, then
+ * an in-package `VERSION` constant, then a banner naming it. A signal is taken from the first source, in the map's
+ * order, that gives one.
+ */
+function versionOf(verified, kind, installed) {
+    if (kind.version !== null)
+        return { version: kind.version, versionSource: 'store-path' };
+    if (installed !== null && installed.version !== '')
+        return { version: installed.version, versionSource: 'lockfile' };
+    const key = `${kind.path.namespace}\0${kind.directory.join('/')}`;
+    let weak = verified.weakVersions.get(key);
+    if (weak === undefined)
+        verified.weakVersions.set(key, (weak = weakVersion(verified, kind, key)));
+    return weak;
+}
+const semver = String.raw `\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?`;
+const wholeSemver = new RegExp(`^${semver}$`);
+/** An in-package `VERSION` constant: `VERSION`, `SDK_VERSION` … assigned or keyed a version string. */
+const versionConstant = new RegExp(String.raw `\b(?:[A-Z][A-Z0-9]*_)*VERSION\s*[:=]\s*(['"\x60])(${semver})\1`);
+/** A source's leading block comment, where a banner is. */
+const leadingComment = /^\s*\/\*[\s\S]*?\*\//;
+/** The weak version of the package `kind`, from the content of its own files in the map (§10 Version), or null. */
+function weakVersion(verified, kind, key) {
+    const own = verified.map.sources.flatMap((source, i) => {
+        const each = verified.kinds[i];
+        if (each?.kind !== 'package' || source.content === null || each.name !== kind.name)
+            return [];
+        return `${each.path.namespace}\0${each.directory.join('/')}` === key ? [{ subpath: each.subpath, content: source.content }] : [];
+    });
+    for (const { subpath, content } of own) {
+        if (subpath.length !== 1 || subpath[0] !== 'package.json')
+            continue;
+        let manifest;
+        try {
+            manifest = JSON.parse(content);
+        }
+        catch {
+            continue;
+        }
+        if (typeof manifest !== 'object' || manifest === null)
+            continue;
+        const { name, version } = manifest;
+        if (name === kind.name && typeof version === 'string' && wholeSemver.test(version)) {
+            return { version, versionSource: 'package-json' };
+        }
+    }
+    for (const { content } of own) {
+        const found = versionConstant.exec(content);
+        if (found !== null)
+            return { version: found[2], versionSource: 'version-constant' };
+    }
+    const named = kind.name.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+    const banner = new RegExp(String.raw `(?:^|[\s*!])${named}(?:\s+|@)v?(${semver})(?![0-9A-Za-z.+-])`);
+    for (const { content } of own) {
+        const comment = leadingComment.exec(content)?.[0];
+        const found = comment === undefined ? null : banner.exec(comment);
+        if (found !== null && found !== undefined)
+            return { version: found[1], versionSource: 'banner' };
+    }
+    return null;
+}
+/** The `token-check` step for a check at `lookup` of `candidate` (§14). */
+function tokenCheckStep(result, lookup, candidate) {
+    const { token } = lookup;
+    const at = `${candidate.source}:${candidate.line}:${candidate.column}`;
+    const text = result === 'passed'
+        ? `\`${token}\` appears within one line of ${at}, where the map puts the write`
+        : result === 'failed'
+            ? `\`${token}\` does not appear within one line of ${at}, where the map puts the write, so that position is ` +
+                'discarded'
+            : token === null
+                ? `the write has no token at its site, so the token check does not apply to ${at}`
+                : `the map has no source content for ${candidate.source}, so the token check does not apply`;
+    return { kind: 'token-check', result, token, lookup: location(lookup.generated), candidate, text };
+}
+function location({ start, end, line, column }) {
+    return { start, end, line, column };
+}

package/dist/packages/attribution/lib/containing-package.d.ts

@@ -0,0 +1,76 @@
+/**
+ * What a raw `sources` entry names:
+ * - `synthetic`: a synthetic or bundler-runtime source, which counts as unmapped (`no-map`)
+ * - `foreign-scheme`: a source with a scheme §10 doesn't recognize, which keys `unknown` whether or not it names a
+ *   package
+ * - `package`: a file of the package `name`, with the path segments inside the package after it, the segments of the
+ *   package's own directory (which hold its other files), the version its store path gives, or null (§10 Version), and
+ *   the vendoring package (`name@version`) when the path lies inside another package's store entry, or null (§10
+ *   Provenance, vendored code)
+ * - `yarn-slug`: a scoped package under Yarn's pnpm linker, which names it only by the lossy `slug`
+ * - `escaped`: a composed-map path that climbs out of its own package inside `node_modules` (`node_modules/@x/src/…`,
+ *   `node_modules/src/…`, `node_modules/node_modules/…`), which is escaped wherever the inferred root is
+ * - `other`: a path under no `node_modules` segment: first-party or escaped code
+ *
+ * Each but the first two carries the normalized `path` it was read from, which the inferred root is read from and
+ * first-party code is named by (§10 Provenance, §11).
+ */
+export type SourceKind = {
+    kind: 'synthetic';
+} | {
+    kind: 'foreign-scheme';
+} | {
+    kind: 'package';
+    name: string;
+    subpath: string[];
+    path: SourcePath;
+    directory: string[];
+    version: string | null;
+    vendoredBy: string | null;
+} | {
+    kind: 'yarn-slug';
+    slug: string;
+    path: SourcePath;
+} | {
+    kind: 'escaped';
+    path: SourcePath;
+} | {
+    kind: 'other';
+    path: SourcePath;
+};
+/**
+ * A source's normalized path (§10 Source schemes), with what it is relative to:
+ * - `relative`: a path with no scheme, relative to its map's directory (a relative `sourceRoot` joined)
+ * - `absolute`: a `file://`, absolute or drive-letter path, whose drive letter is its first segment
+ * - `webpack:<ns>`, `webpack-internal`, `turbopack` or `vite`: a path relative to that bundler's base (the webpack
+ *   context, or the project root), within the bundler namespace it names
+ *
+ * `segments` has `.` and `x/..` collapsed, and keeps leading `..` segments.
+ */
+export interface SourcePath {
+    namespace: string;
+    segments: string[];
+}
+/**
+ * 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 declare function relativeSourceRoot(sourceRoot: unknown): string | null;
+/**
+ * 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 declare function sourceKind(source: string | null, sourceRoot: string | null): SourceKind;