@packall/core 0.0.1 → 0.2.0

package/src/lockfile/bun.ts

@@ -0,0 +1,214 @@
+/**
+ * `bun.lock`.
+ *
+ * Like npm, bun records ranges on its edges and resolves them through the
+ * install-path nesting — but it nests with a plain `/`, and package names
+ * contain `/` too, so the parent of a key can only be found by asking which
+ * prefixes are themselves entries.
+ */
+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, stringRecord } from "./json.js";
+import {
+	asExactVersion,
+	fieldByRootKind,
+	importerKey,
+	notCovered,
+	TreeBuilder,
+} from "./tree-builder.js";
+import type { LockedEdge, LockedTree } from "./types.js";
+
+/** One narrowed `packages` entry, keyed by its install path. */
+type BunEntry = {
+	readonly key: string;
+	readonly name: string;
+	readonly version: 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 bun's precedence order — the first mention of a name wins. */
+const ROOT_KINDS = [
+	LockedRootKind.Prod,
+	LockedRootKind.Optional,
+	LockedRootKind.Dev,
+	LockedRootKind.Peer,
+] as const;
+
+export const parseBunLockfile = (
+	path: string,
+	content: string,
+	importer: string | undefined,
+): LockedTree => {
+	const root = parseJsonObject(path, content);
+	const version = String(root["lockfileVersion"] ?? "?");
+	const builder = new TreeBuilder();
+
+	const packages = root["packages"];
+	const entries = isRecord(packages)
+		? collectEntries(builder, packages)
+		: new Map<string, BunEntry>();
+
+	const keys = new Set(entries.keys());
+	for (const entry of entries.values()) {
+		builder.add({
+			name: entry.name,
+			version: entry.version,
+			dependencies: edgesOf(builder, entries, keys, entry),
+		});
+	}
+
+	collectRoots(builder, entries, keys, root["workspaces"], path, importer);
+
+	return builder.finish({ format: LockfileFormat.Bun, lockfileVersion: version, path, importer });
+};
+
+/**
+ * Narrows bun's tuple entries.
+ *
+ * The value is a positional array whose shape depends on where the package came
+ * from. A registry package is `[id, registry, info, integrity]`; a workspace
+ * member or a git dependency is shorter and its `id` carries the protocol.
+ */
+const collectEntries = (
+	builder: TreeBuilder,
+	packages: Record<string, unknown>,
+): Map<string, BunEntry> => {
+	const entries = new Map<string, BunEntry>();
+
+	for (const [key, raw] of Object.entries(packages)) {
+		if (!Array.isArray(raw)) continue;
+
+		const [id, , info] = raw;
+		if (typeof id !== "string") continue;
+
+		const at = id.lastIndexOf("@");
+		if (at <= 0) continue;
+		const name = id.slice(0, at);
+		const spec = id.slice(at + 1);
+
+		const version = asExactVersion(name, spec);
+		if (version._tag === "Unsupported") {
+			builder.skip(name, spec, version.reason);
+			continue;
+		}
+
+		const details = isRecord(info) ? info : {};
+
+		entries.set(key, {
+			key,
+			name,
+			version: version.version,
+			dependencies: stringRecord(details["dependencies"]),
+			optionalDependencies: stringRecord(details["optionalDependencies"]),
+			peerDependencies: stringRecord(details["peerDependencies"]),
+			optionalPeers: collectOptionalPeers(details),
+		});
+	}
+
+	return entries;
+};
+
+/** bun lists optional peers as a name array rather than npm's metadata object. */
+const collectOptionalPeers = (details: Record<string, unknown>): ReadonlySet<string> => {
+	const listed = details["optionalPeers"];
+	const names = Array.isArray(listed)
+		? listed.flatMap((entry) => (typeof entry === "string" ? entry : []))
+		: [];
+	return new Set([...names, ...optionalPeerNames(details["peerDependenciesMeta"])]);
+};
+
+const edgesOf = (
+	builder: TreeBuilder,
+	entries: ReadonlyMap<string, BunEntry>,
+	keys: ReadonlySet<string>,
+	entry: BunEntry,
+): ReadonlyArray<LockedEdge> => {
+	const edges: Array<LockedEdge> = [];
+
+	const add = (names: ReadonlyArray<string>, kind: EdgeKind): void => {
+		for (const name of names) {
+			const target = findEntry(entries, keys, entry.key, name);
+			if (target === undefined) {
+				if (kind === EdgeKind.Prod)
+					builder.dangling(`${entry.name}@${entry.version}`, name);
+				continue;
+			}
+			edges.push({ name: target.name, version: target.version, kind });
+		}
+	};
+
+	add(Object.keys(entry.dependencies), EdgeKind.Prod);
+	add(Object.keys(entry.optionalDependencies), EdgeKind.Optional);
+	add(
+		Object.keys(entry.peerDependencies).filter((name) => !entry.optionalPeers.has(name)),
+		EdgeKind.Peer,
+	);
+
+	return edges;
+};
+
+const collectRoots = (
+	builder: TreeBuilder,
+	entries: ReadonlyMap<string, BunEntry>,
+	keys: ReadonlySet<string>,
+	workspaces: unknown,
+	path: string,
+	member: string | undefined,
+): void => {
+	if (!isRecord(workspaces)) return;
+
+	const selected =
+		member === undefined
+			? Object.values(workspaces)
+			: Object.hasOwn(workspaces, importerKey(member))
+				? [workspaces[importerKey(member)]]
+				: notCovered(path, member, workspacePaths(workspaces));
+
+	for (const workspace of selected) {
+		if (!isRecord(workspace)) continue;
+		for (const kind of ROOT_KINDS) {
+			const declared = stringRecord(workspace[fieldByRootKind[kind]]);
+			for (const [name, specifier] of Object.entries(declared)) {
+				const target = findEntry(entries, keys, "", name);
+				if (target === undefined) continue;
+				builder.addRoot({ name: target.name, version: target.version, kind, specifier });
+			}
+		}
+	}
+};
+
+const workspacePaths = (workspaces: Record<string, unknown>): ReadonlyArray<string> =>
+	Object.keys(workspaces).map((key) => (key === "" ? "." : key));
+
+/**
+ * bun nests with a plain `/`, and package names contain `/` too, so a parent
+ * key cannot be found by string-splitting alone — `@babel/core` would split
+ * into a scope that is not a key. `parentKey` only accepts a prefix that is
+ * itself an entry, which resolves the ambiguity.
+ */
+const findEntry = (
+	entries: ReadonlyMap<string, BunEntry>,
+	keys: ReadonlySet<string>,
+	fromKey: string,
+	name: string,
+): BunEntry | undefined => {
+	let scope = fromKey;
+	for (;;) {
+		const found = entries.get(scope === "" ? name : `${scope}/${name}`);
+		if (found !== undefined) return found;
+		if (scope === "") return undefined;
+		scope = parentKey(keys, scope);
+	}
+};
+
+const parentKey = (keys: ReadonlySet<string>, key: string): string => {
+	for (let at = key.lastIndexOf("/"); at > 0; at = key.lastIndexOf("/", at - 1)) {
+		const prefix = key.slice(0, at);
+		if (keys.has(prefix)) return prefix;
+	}
+	return "";
+};

package/src/lockfile/detect.ts

@@ -0,0 +1,80 @@
+/**
+ * Working out which lockfile — if any — some content is.
+ *
+ * Detection is by content, matching how `--file` treats everything else: a
+ * lockfile renamed to `deps.txt` still parses, and a `package-lock.json` that
+ * is actually a package.json still gets read as one.
+ */
+import { LockfileFormat } from "../enums/lockfile-format.js";
+import { isRecord } from "../utils/is-record.js";
+import { tryParseJsonc } from "./json.js";
+
+/** What a blob of file content turned out to be. */
+export type LockfileDetection =
+	| { readonly _tag: "Supported"; readonly format: LockfileFormat }
+	/**
+	 * Recognisably a lockfile, but not one we can read. Named explicitly so the
+	 * error says "yarn.lock is not supported yet" rather than leaving somebody to
+	 * work out why their file parsed as a spec list.
+	 */
+	| { readonly _tag: "Unsupported"; readonly label: string; readonly hint: string }
+	| { readonly _tag: "NotALockfile" };
+
+/**
+ * Deliberately cheap and total: it never throws, so `--file` can try this
+ * first and fall through to its other shapes when the answer is `NotALockfile`.
+ */
+export const detectLockfile = (content: string): LockfileDetection => {
+	const trimmed = content.trimStart();
+
+	// bun's binary lockfile leads with its own magic string. Worth naming,
+	// because `bun install` wrote this by default until 1.2 and the fix is one
+	// command.
+	if (trimmed.startsWith("bun-lockfile-format-v0")) {
+		return {
+			_tag: "Unsupported",
+			label: "a binary bun lockfile (bun.lockb)",
+			hint: "Run `bun install --save-text-lockfile` to produce a bun.lock, and pass that instead.",
+		};
+	}
+
+	if (/^__metadata:/m.test(trimmed) || /^# yarn lockfile v\d/m.test(trimmed)) {
+		return {
+			_tag: "Unsupported",
+			label: "a yarn lockfile",
+			hint: "yarn is not supported yet. Point --file at the package.json instead, or pass --lockfile off.",
+		};
+	}
+
+	if (trimmed.startsWith("{")) return detectJsonLockfile(trimmed);
+
+	// pnpm is the only YAML one, and it always declares its version first.
+	if (/^lockfileVersion:/m.test(trimmed) || /^(importers|snapshots):/m.test(trimmed)) {
+		return { _tag: "Supported", format: LockfileFormat.Pnpm };
+	}
+
+	return { _tag: "NotALockfile" };
+};
+
+/**
+ * Separates the two JSON lockfiles from each other and from a package.json.
+ *
+ * Both npm and bun write a numeric `lockfileVersion`, so that field alone
+ * cannot decide it. bun is the one that carries a `workspaces` map keyed by the
+ * empty string; npm keeps the root project under `packages[""]` instead.
+ */
+const detectJsonLockfile = (trimmed: string): LockfileDetection => {
+	const parsed = tryParseJsonc(trimmed);
+	if (!isRecord(parsed)) return { _tag: "NotALockfile" };
+
+	const workspaces = parsed["workspaces"];
+	if (isRecord(workspaces) && Object.hasOwn(workspaces, "")) {
+		return { _tag: "Supported", format: LockfileFormat.Bun };
+	}
+
+	if (typeof parsed["lockfileVersion"] === "number") {
+		return { _tag: "Supported", format: LockfileFormat.Npm };
+	}
+
+	return { _tag: "NotALockfile" };
+};

package/src/lockfile/json.ts

@@ -0,0 +1,131 @@
+/**
+ * Narrowing helpers for the untyped JSON and YAML a lockfile parses into.
+ *
+ * Everything here takes `unknown` and hands back something narrowed, which is
+ * what keeps the parsers free of casts against files nobody controls. The
+ * shape-level narrowing is Effect Schema — the same decoders the registry
+ * response boundary uses — so "tolerated" means one thing across the codebase
+ * rather than being re-decided per parser.
+ */
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+
+import { LockfileError } from "../errors.js";
+import { OptionalFlagRecordSchema, StringRecordSchema } from "../schemas/lenient.js";
+import { isRecord } from "../utils/is-record.js";
+
+export const stringOr = (value: unknown, fallback: string): string =>
+	typeof value === "string" ? value : fallback;
+
+const decodeStringRecord = Schema.decodeUnknownOption(StringRecordSchema);
+
+/** Keeps only the string-valued members of an untyped object. */
+export const stringRecord = (value: unknown): Readonly<Record<string, string>> =>
+	Option.getOrElse(decodeStringRecord(value), (): Record<string, string> => ({}));
+
+const decodeOptionalFlags = Schema.decodeUnknownOption(OptionalFlagRecordSchema);
+
+/** Names a package marked its peers optional with. */
+export const optionalPeerNames = (value: unknown): ReadonlySet<string> => {
+	const flags = Option.getOrElse(
+		decodeOptionalFlags(value),
+		(): Record<string, { readonly optional: boolean }> => ({}),
+	);
+	return new Set(Object.entries(flags).flatMap(([name, meta]) => (meta.optional ? name : [])));
+};
+
+export const parseJsonObject = (path: string, content: string): Record<string, unknown> => {
+	const parsed = tryParseJsonc(content);
+	if (parsed === undefined) {
+		throw new LockfileError(path, "not valid JSON");
+	}
+	if (!isRecord(parsed)) {
+		throw new LockfileError(path, "top level is not an object");
+	}
+	return parsed;
+};
+
+/**
+ * Parses JSON, tolerating the comments and trailing commas bun writes.
+ *
+ * `bun.lock` is JSONC by design — bun puts explanatory comments in it — so
+ * plain `JSON.parse` rejects real lockfiles. Returns `undefined` rather than
+ * throwing so detection can use it as a probe.
+ */
+export const tryParseJsonc = (content: string): unknown => {
+	try {
+		return JSON.parse(content);
+	} catch {
+		try {
+			return JSON.parse(stripJsonc(content));
+		} catch {
+			return undefined;
+		}
+	}
+};
+
+/**
+ * Removes comments and trailing commas.
+ *
+ * String-aware, because a `//` inside a tarball URL is not a comment and an
+ * escaped quote does not end a string. Both appear in every real lockfile.
+ */
+export const stripJsonc = (content: string): string => {
+	let out = "";
+	let index = 0;
+	let inString = false;
+
+	while (index < content.length) {
+		const char = content[index];
+
+		if (inString) {
+			out += char;
+			if (char === "\\") {
+				out += content[index + 1] ?? "";
+				index += 2;
+				continue;
+			}
+			if (char === '"') inString = false;
+			index += 1;
+			continue;
+		}
+
+		if (char === '"') {
+			inString = true;
+			out += char;
+			index += 1;
+			continue;
+		}
+
+		if (char === "/" && content[index + 1] === "/") {
+			const end = content.indexOf("\n", index);
+			index = end === -1 ? content.length : end;
+			continue;
+		}
+
+		if (char === "/" && content[index + 1] === "*") {
+			const end = content.indexOf("*/", index + 2);
+			index = end === -1 ? content.length : end + 2;
+			continue;
+		}
+
+		// A comma is trailing when the next thing that is not whitespace closes the
+		// structure it sits in.
+		if (char === ",") {
+			const next = content.slice(index + 1).search(/\S/);
+			const following = next === -1 ? "" : content[index + 1 + next];
+			if (following === "}" || following === "]") {
+				index += 1;
+				continue;
+			}
+		}
+
+		out += char;
+		index += 1;
+	}
+
+	return out;
+};
+
+export const describeError = (error: unknown): string =>
+	error instanceof Error ? error.message : String(error);

package/src/lockfile/names.ts

@@ -0,0 +1,20 @@
+import { LockfileFormat } from "../enums/lockfile-format.js";
+
+/**
+ * The file name each supported manager writes, in detection order.
+ *
+ * Ordered: `package-lock.json` before `npm-shrinkwrap.json` before pnpm's and
+ * bun's, so a directory holding several is searched the way npm itself would.
+ */
+export const formatByLockfileName = {
+	"package-lock.json": LockfileFormat.Npm,
+	"npm-shrinkwrap.json": LockfileFormat.Npm,
+	"pnpm-lock.yaml": LockfileFormat.Pnpm,
+	"bun.lock": LockfileFormat.Bun,
+} as const satisfies Record<string, LockfileFormat>;
+
+/** The names a given manager writes. */
+export const lockfileNamesFor = (format: LockfileFormat): ReadonlyArray<string> =>
+	Object.entries(formatByLockfileName).flatMap(([name, candidate]) =>
+		candidate === format ? name : [],
+	);