@packall/core 0.0.1 → 0.2.0

package/src/lockfile/npm.ts

@@ -0,0 +1,328 @@
+/**
+ * `package-lock.json` / `npm-shrinkwrap.json`.
+ *
+ * npm records *ranges* on its edges and relies on the directory nesting to say
+ * which copy of a package a range resolved to, so the node resolution walk-up —
+ * look beside me, then in my parent, then my grandparent — is reimplemented
+ * here.
+ */
+import { EdgeKind, LockedRootKind } from "../enums/edge-kind.js";
+import { LockfileFormat } from "../enums/lockfile-format.js";
+import { isRecord } from "../utils/is-record.js";
+import { optionalPeerNames, parseJsonObject, stringOr, stringRecord } from "./json.js";
+import {
+	asExactVersion,
+	fieldByRootKind,
+	importerKey,
+	notCovered,
+	TreeBuilder,
+} from "./tree-builder.js";
+import type { LockedEdge, LockedTree } from "./types.js";
+
+/** One entry of the v2/v3 `packages` map, after narrowing. */
+type NpmEntry = {
+	readonly path: string;
+	readonly version: string;
+	/** Set when the install name differs from the real one — an `npm:` alias. */
+	readonly realName: string;
+	readonly dependencies: Readonly<Record<string, string>>;
+	readonly optionalDependencies: Readonly<Record<string, string>>;
+	readonly peerDependencies: Readonly<Record<string, string>>;
+	readonly optionalPeers: ReadonlySet<string>;
+};
+
+/** Root blocks in npm's precedence order — the first mention of a name wins. */
+const ROOT_KINDS = [
+	LockedRootKind.Prod,
+	LockedRootKind.Optional,
+	LockedRootKind.Dev,
+	LockedRootKind.Peer,
+] as const;
+
+/**
+ * The node resolution walk-up, over a flat map of install paths.
+ *
+ * A package at `node_modules/a/node_modules/b` depending on `c` gets, in order,
+ * `node_modules/a/node_modules/b/node_modules/c`, then
+ * `node_modules/a/node_modules/c`, then `node_modules/c`. This is what makes a
+ * range on an edge unambiguous: the nesting already recorded which copy won.
+ */
+const NESTING = "/node_modules/";
+
+export const parseNpmLockfile = (
+	path: string,
+	content: string,
+	importer: string | undefined,
+): LockedTree => {
+	const root = parseJsonObject(path, content);
+	const version = String(root["lockfileVersion"] ?? "?");
+	const builder = new TreeBuilder();
+
+	// v2 carries both shapes for backwards compatibility; `packages` is the
+	// accurate one, so it wins whenever it is there.
+	const packages = root["packages"];
+	const entries = isRecord(packages)
+		? collectEntries(builder, packages)
+		: collectLegacyEntries(builder, root);
+
+	for (const entry of entries.values()) {
+		builder.add({
+			name: entry.realName,
+			version: entry.version,
+			dependencies: edgesOf(builder, entries, entry),
+		});
+	}
+
+	collectRoots(builder, entries, isRecord(packages) ? packages : root, path, importer);
+
+	return builder.finish({ format: LockfileFormat.Npm, lockfileVersion: version, path, importer });
+};
+
+/** Narrows the v2/v3 `packages` map, dropping what cannot be bundled. */
+const collectEntries = (
+	builder: TreeBuilder,
+	packages: Record<string, unknown>,
+): Map<string, NpmEntry> => {
+	const entries = new Map<string, NpmEntry>();
+
+	for (const [entryPath, raw] of Object.entries(packages)) {
+		// The root project itself, and workspace members, are not things to fetch.
+		const installName = installNameFromPath(entryPath);
+		if (installName === null) continue;
+		if (!isRecord(raw)) continue;
+
+		// A symlinked workspace member. Nothing to fetch, but an edge into it has
+		// to be explained rather than counted as a hole in the file.
+		if (raw["link"] === true) {
+			builder.skip(installName, stringOr(raw["resolved"], "link"), "workspace link");
+			continue;
+		}
+
+		const rawVersion = raw["version"];
+		if (typeof rawVersion !== "string") {
+			builder.warn(
+				`skipped ${installName} — its lockfile entry records no version, so there is nothing to pin`,
+			);
+			continue;
+		}
+
+		const resolvedName = typeof raw["name"] === "string" ? raw["name"] : installName;
+		const version = asExactVersion(resolvedName, rawVersion);
+		if (version._tag === "Unsupported") {
+			builder.skip(resolvedName, rawVersion, version.reason);
+			continue;
+		}
+
+		// `resolved` names a git or tarball URL for anything not from a registry,
+		// even when `version` looks ordinary.
+		const resolvedUrl = raw["resolved"];
+		if (typeof resolvedUrl === "string" && !isRegistryUrl(resolvedUrl)) {
+			builder.skip(resolvedName, resolvedUrl, "not a registry tarball");
+			continue;
+		}
+
+		entries.set(entryPath, {
+			path: entryPath,
+			version: version.version,
+			realName: resolvedName,
+			dependencies: stringRecord(raw["dependencies"]),
+			optionalDependencies: stringRecord(raw["optionalDependencies"]),
+			peerDependencies: stringRecord(raw["peerDependencies"]),
+			optionalPeers: optionalPeerNames(raw["peerDependenciesMeta"]),
+		});
+	}
+
+	return entries;
+};
+
+/**
+ * Flattens a v1 lockfile's nested `dependencies` tree into the same
+ * path-keyed shape v2 uses.
+ *
+ * v1 is old — npm 6 — but it is exactly the vintage still pinned inside a lot
+ * of the locked-down environments this tool exists for, so it is worth the
+ * thirty lines rather than an error telling somebody to upgrade npm.
+ */
+const collectLegacyEntries = (
+	builder: TreeBuilder,
+	root: Record<string, unknown>,
+): Map<string, NpmEntry> => {
+	const entries = new Map<string, NpmEntry>();
+
+	const visit = (tree: unknown, prefix: string): void => {
+		if (!isRecord(tree)) return;
+		for (const [name, raw] of Object.entries(tree)) {
+			if (!isRecord(raw)) continue;
+			const entryPath =
+				prefix === "" ? `node_modules/${name}` : `${prefix}/node_modules/${name}`;
+
+			const rawVersion = raw["version"];
+			if (typeof rawVersion === "string") {
+				const version = asExactVersion(name, rawVersion);
+				if (version._tag === "Unsupported") {
+					builder.skip(name, rawVersion, version.reason);
+				} else {
+					entries.set(entryPath, {
+						path: entryPath,
+						version: version.version,
+						realName: name,
+						// v1 calls the edge set `requires`.
+						dependencies: stringRecord(raw["requires"]),
+						optionalDependencies: {},
+						peerDependencies: {},
+						optionalPeers: new Set(),
+					});
+				}
+			}
+
+			visit(raw["dependencies"], entryPath);
+		}
+	};
+
+	visit(root["dependencies"], "");
+	return entries;
+};
+
+/** Turns one entry's ranges into edges, resolved through the directory nesting. */
+const edgesOf = (
+	builder: TreeBuilder,
+	entries: ReadonlyMap<string, NpmEntry>,
+	entry: NpmEntry,
+): ReadonlyArray<LockedEdge> => {
+	const edges: Array<LockedEdge> = [];
+
+	const add = (names: ReadonlyArray<string>, kind: EdgeKind): void => {
+		for (const name of names) {
+			const targetPath = resolveNestedEdge(entries, entry.path, name);
+			const target = targetPath === null ? undefined : entries.get(targetPath);
+			if (target === undefined) {
+				// Only required edges are worth raising: an optional or peer edge that
+				// resolves to nothing is how a lockfile records "not installed here",
+				// which npm itself tolerates.
+				if (kind === EdgeKind.Prod)
+					builder.dangling(`${entry.realName}@${entry.version}`, name);
+				continue;
+			}
+			edges.push({ name: target.realName, version: target.version, kind });
+		}
+	};
+
+	const optionalNames = Object.keys(entry.optionalDependencies);
+	const optional = new Set(optionalNames);
+
+	// An entry listed in both is optional: that is how npm records "wanted, but
+	// the install may proceed without it".
+	add(
+		Object.keys(entry.dependencies).filter((name) => !optional.has(name)),
+		EdgeKind.Prod,
+	);
+	add(optionalNames, EdgeKind.Optional);
+	add(
+		Object.keys(entry.peerDependencies).filter((name) => !entry.optionalPeers.has(name)),
+		EdgeKind.Peer,
+	);
+
+	return edges;
+};
+
+/**
+ * Reads the root project's direct dependencies.
+ *
+ * The lockfile records these under `packages[""]` for v2/v3. v1 has no such
+ * entry, so every top-level `node_modules/x` is treated as direct — which
+ * over-counts roots slightly on v1 and is the best that file can support.
+ */
+const collectRoots = (
+	builder: TreeBuilder,
+	entries: ReadonlyMap<string, NpmEntry>,
+	source: Record<string, unknown>,
+	path: string,
+	importer: string | undefined,
+): void => {
+	// Resolution starts from the member's own directory, so a dependency it
+	// nests privately wins over the hoisted copy — the same rule node applies,
+	// which is why the walk-up is shared with ordinary edges.
+	const collectFrom = (from: string, project: Record<string, unknown>): void => {
+		for (const kind of ROOT_KINDS) {
+			const field = fieldByRootKind[kind];
+			for (const [name, specifier] of Object.entries(stringRecord(project[field]))) {
+				const targetPath = resolveNestedEdge(entries, from, name);
+				const target = targetPath === null ? undefined : entries.get(targetPath);
+				if (target === undefined) continue;
+				builder.addRoot({
+					name: target.realName,
+					version: target.version,
+					kind,
+					specifier,
+				});
+			}
+		}
+	};
+
+	if (importer !== undefined) {
+		const key = importerKey(importer);
+		const project = source[key];
+		if (!isRecord(project)) notCovered(path, importer, workspacePaths(source));
+		else collectFrom(key, project);
+		return;
+	}
+
+	// No member named: every project the file records contributes, which is what
+	// pointing --file straight at a monorepo's lockfile should mean.
+	const projects = Object.entries(source).flatMap(([key, value]) =>
+		isRecord(value) && !key.includes("node_modules/") ? [[key, value] as const] : [],
+	);
+
+	if (projects.length > 0) {
+		for (const [key, project] of projects) collectFrom(key, project);
+		return;
+	}
+
+	// v1 records no project entry at all, so every top-level install is direct.
+	for (const entry of entries.values()) {
+		if (entry.path.includes(NESTING)) continue;
+		builder.addRoot({
+			name: entry.realName,
+			version: entry.version,
+			kind: LockedRootKind.Prod,
+		});
+	}
+};
+
+/** The workspace paths a v2/v3 lockfile records, for a "does not cover" message. */
+const workspacePaths = (source: Record<string, unknown>): ReadonlyArray<string> =>
+	Object.keys(source).flatMap((key) =>
+		key === "" ? "." : key.includes("node_modules/") ? [] : key,
+	);
+
+/**
+ * npm records non-registry sources as a URL in `resolved`. Registry tarballs
+ * are ordinary http(s); anything with a `git+`, `file:` or bare path form is
+ * something we cannot fetch.
+ */
+const isRegistryUrl = (url: string): boolean =>
+	url.startsWith("http://") || url.startsWith("https://");
+
+const resolveNestedEdge = (
+	entries: ReadonlyMap<string, NpmEntry>,
+	fromPath: string,
+	name: string,
+): string | null => {
+	let scope = fromPath;
+	for (;;) {
+		const candidate = scope === "" ? `node_modules/${name}` : `${scope}${NESTING}${name}`;
+		if (entries.has(candidate)) return candidate;
+		if (scope === "") return null;
+		const at = scope.lastIndexOf(NESTING);
+		scope = at === -1 ? "" : scope.slice(0, at);
+	}
+};
+
+/** `node_modules/@babel/core` -> `@babel/core`; a workspace path -> `null`. */
+const installNameFromPath = (entryPath: string): string | null => {
+	const marker = "node_modules/";
+	const at = entryPath.lastIndexOf(marker);
+	if (at === -1) return null;
+	const name = entryPath.slice(at + marker.length);
+	return name.length === 0 ? null : name;
+};

package/src/lockfile/parse.ts

@@ -0,0 +1,56 @@
+/**
+ * Lockfile parsing — npm, pnpm and bun.
+ *
+ * `--file package.json` reads *ranges*, and a range resolves to whatever is
+ * newest at the moment the command runs. That is the right answer for "bundle
+ * me something installable" and the wrong one for "bundle exactly what CI
+ * installed" — which is what a lockfile records and what this module reads.
+ *
+ * Three formats, one output shape. Each parser's real job is the same: turn a
+ * manager-specific encoding of "package X at path P depends on Y" into a flat
+ * graph keyed by `name@version`, with every edge already pointing at a concrete
+ * version. Once that is done, nothing downstream has to know which manager
+ * wrote the file.
+ */
+import { LockfileFormat } from "../enums/lockfile-format.js";
+import { LockfileError } from "../errors.js";
+import { parseBunLockfile } from "./bun.js";
+import { detectLockfile } from "./detect.js";
+import { parseNpmLockfile } from "./npm.js";
+import { parsePnpmLockfile } from "./pnpm.js";
+import type { LockedTree, LockfileParseOptions } from "./types.js";
+
+/**
+ * Parses lockfile content into a flat graph.
+ *
+ * Throws `LockfileError`; the caller is expected to be inside an `Effect.try`.
+ */
+export const parseLockfile = (
+	path: string,
+	content: string,
+	format?: LockfileFormat,
+	options: LockfileParseOptions = {},
+): LockedTree => {
+	const resolved = format ?? resolveFormat(path, content);
+	const importer = options.importer;
+	switch (resolved) {
+		case LockfileFormat.Npm:
+			return parseNpmLockfile(path, content, importer);
+		case LockfileFormat.Pnpm:
+			return parsePnpmLockfile(path, content, importer);
+		case LockfileFormat.Bun:
+			return parseBunLockfile(path, content, importer);
+	}
+};
+
+const resolveFormat = (path: string, content: string): LockfileFormat => {
+	const detected = detectLockfile(content);
+	if (detected._tag === "Supported") return detected.format;
+	if (detected._tag === "Unsupported") {
+		throw new LockfileError(path, `${detected.label} — ${detected.hint}`);
+	}
+	throw new LockfileError(
+		path,
+		"content does not look like a package-lock.json, pnpm-lock.yaml or bun.lock",
+	);
+};

package/src/lockfile/pnpm.ts

@@ -0,0 +1,230 @@
+/**
+ * `pnpm-lock.yaml`.
+ *
+ * The easy one: pnpm's snapshots already name exact versions, so there is no
+ * nesting walk-up to reimplement. The fiddly parts are the three package-key
+ * encodings still in the wild and the parenthesised peer-resolution suffix.
+ */
+import semver from "semver";
+import { parse as parseYaml } from "yaml";
+
+import { parseDependencyTarget } from "../dependency-range.js";
+import { EdgeKind, LockedRootKind } from "../enums/edge-kind.js";
+import { LockfileFormat } from "../enums/lockfile-format.js";
+import { LockfileError } from "../errors.js";
+import { isRecord } from "../utils/is-record.js";
+import { describeError } from "./json.js";
+import { fieldByRootKind, notCovered, TreeBuilder } from "./tree-builder.js";
+import type { LockedEdge, LockedTree } from "./types.js";
+
+/** `name@version`, as a snapshot or importer entry resolves to. */
+type PnpmReference = {
+	readonly name: string;
+	readonly version: string;
+};
+
+/** pnpm never records peer dependencies against an importer. */
+const ROOT_KINDS = [LockedRootKind.Prod, LockedRootKind.Optional, LockedRootKind.Dev] as const;
+
+export const parsePnpmLockfile = (
+	path: string,
+	content: string,
+	importer: string | undefined,
+): LockedTree => {
+	let root: unknown;
+	try {
+		root = parseYaml(content);
+	} catch (error) {
+		throw new LockfileError(path, `not valid YAML — ${describeError(error)}`, { cause: error });
+	}
+	if (!isRecord(root)) {
+		throw new LockfileError(path, "top level is not a mapping");
+	}
+
+	const version = String(root["lockfileVersion"] ?? "?");
+	const builder = new TreeBuilder();
+
+	// v9 split the graph in two: `packages` keeps resolution metadata, and
+	// `snapshots` keeps the edges. Before that both lived in `packages`.
+	const packages = isRecord(root["packages"]) ? root["packages"] : {};
+	const snapshots = isRecord(root["snapshots"]) ? root["snapshots"] : packages;
+
+	const known = new Map<string, PnpmReference>();
+	for (const key of Object.keys(packages)) {
+		const parsed = parsePnpmKey(key);
+		if (parsed === null) continue;
+		known.set(key, parsed);
+	}
+
+	for (const [key, raw] of Object.entries(snapshots)) {
+		const parsed = parsePnpmKey(key) ?? known.get(key);
+		if (parsed === undefined || parsed === null) {
+			const described = describeKey(key);
+			if (described !== null) builder.skip(described.name, described.spec, described.reason);
+			continue;
+		}
+		builder.add({
+			name: parsed.name,
+			version: parsed.version,
+			dependencies: edgesOf(builder, parsed, isRecord(raw) ? raw : {}),
+		});
+	}
+
+	collectRoots(builder, root, path, importer);
+
+	return builder.finish({
+		format: LockfileFormat.Pnpm,
+		lockfileVersion: version,
+		path,
+		importer,
+	});
+};
+
+const edgesOf = (
+	builder: TreeBuilder,
+	from: PnpmReference,
+	snapshot: Record<string, unknown>,
+): ReadonlyArray<LockedEdge> => {
+	const edges: Array<LockedEdge> = [];
+
+	const add = (field: string, kind: EdgeKind): void => {
+		const entries = snapshot[field];
+		if (!isRecord(entries)) return;
+		for (const [name, raw] of Object.entries(entries)) {
+			if (typeof raw !== "string") continue;
+			const target = parsePnpmReference(name, raw);
+			if (target === null) {
+				if (kind === EdgeKind.Prod) builder.dangling(`${from.name}@${from.version}`, name);
+				continue;
+			}
+			edges.push({ ...target, kind });
+		}
+	};
+
+	add(fieldByRootKind[LockedRootKind.Prod], EdgeKind.Prod);
+	add(fieldByRootKind[LockedRootKind.Optional], EdgeKind.Optional);
+	add(fieldByRootKind[LockedRootKind.Peer], EdgeKind.Peer);
+
+	return edges;
+};
+
+/**
+ * The importers' direct dependencies become the roots.
+ *
+ * pnpm is the format that makes this easy: `importers` is already keyed by the
+ * path each package.json sits at, so scoping to one member is a lookup rather
+ * than a reconstruction.
+ */
+const collectRoots = (
+	builder: TreeBuilder,
+	root: Record<string, unknown>,
+	path: string,
+	member: string | undefined,
+): void => {
+	// A single-project lockfile has no `importers` block; its dependencies sit at
+	// the top level, which is the same thing as an importer called ".".
+	const importers = isRecord(root["importers"]) ? root["importers"] : { ".": root };
+
+	const selected =
+		member === undefined
+			? Object.values(importers)
+			: Object.hasOwn(importers, member)
+				? [importers[member]]
+				: notCovered(path, member, Object.keys(importers));
+
+	for (const importer of selected) {
+		if (!isRecord(importer)) continue;
+		for (const kind of ROOT_KINDS) {
+			const entries = importer[fieldByRootKind[kind]];
+			if (!isRecord(entries)) continue;
+
+			for (const [name, raw] of Object.entries(entries)) {
+				// v5 wrote a bare version string; v6 and v9 write
+				// `{specifier, version}`.
+				const value =
+					typeof raw === "string" ? raw : isRecord(raw) ? raw["version"] : undefined;
+				if (typeof value !== "string") continue;
+
+				const target = parsePnpmReference(name, value);
+				if (target === null) continue;
+
+				const specifier =
+					isRecord(raw) && typeof raw["specifier"] === "string"
+						? raw["specifier"]
+						: undefined;
+				builder.addRoot({ ...target, kind, specifier });
+			}
+		}
+	}
+};
+
+/**
+ * Reads a dependency value from a snapshot or importer.
+ *
+ * The value is either a bare version (`1.4.0`) or a full package key
+ * (`/lodash@4.17.21`, used when the install name is an alias of another
+ * package). Both may carry a peer-resolution suffix in parentheses.
+ */
+const parsePnpmReference = (name: string, raw: string): PnpmReference | null => {
+	const value = stripSuffix(raw);
+
+	const exact = semver.valid(value, { loose: true });
+	if (exact !== null) return { name, version: exact };
+
+	return parsePnpmKey(raw);
+};
+
+/**
+ * Splits a package key into name and version.
+ *
+ * Three encodings across the versions still in the wild:
+ *   v5  `/@babel/core/7.0.0`
+ *   v6  `/@babel/core@7.0.0`
+ *   v9  `@babel/core@7.0.0`
+ *
+ * plus an optional `(peer@1.0.0)` or `(patch_hash=…)` suffix on any of them.
+ */
+export const parsePnpmKey = (key: string): PnpmReference | null => {
+	const body = stripSuffix(key.startsWith("/") ? key.slice(1) : key);
+
+	// A scoped name's own `@` sits at index 0, so only a later one separates the
+	// version. When there is none, this is the v5 form and the last `/` does it.
+	const at = body.lastIndexOf("@");
+	const cut = at > 0 ? at : body.lastIndexOf("/");
+	if (cut <= 0) return null;
+
+	const name = body.slice(0, cut);
+	const version = semver.valid(body.slice(cut + 1), { loose: true });
+	if (version === null || name.length === 0) return null;
+
+	return { name, version };
+};
+
+/** Describes a key we cannot pin, so the skip warning can say why. */
+const describeKey = (
+	key: string,
+): { readonly name: string; readonly spec: string; readonly reason: string } | null => {
+	const body = key.startsWith("/") ? key.slice(1) : key;
+	const at = body.lastIndexOf("@");
+	if (at <= 0) return null;
+	const name = body.slice(0, at);
+	const spec = body.slice(at + 1);
+	const target = parseDependencyTarget(name, spec);
+	return {
+		name,
+		spec,
+		reason: target._tag === "Unsupported" ? target.reason : "not an exact version",
+	};
+};
+
+/**
+ * Drops the parenthesised peer-resolution suffix.
+ *
+ * pnpm distinguishes the same version installed against different peers —
+ * `react-dom@18.3.1(react@18.3.1)`. Those are the same published tarball, which
+ * is all this tool downloads, so the suffix is noise here.
+ */
+const stripSuffix = (value: string): string => {
+	const open = value.indexOf("(");
+	return open === -1 ? value : value.slice(0, open);
+};