@packall/core 0.1.0 → 0.3.0

package/src/lockfile/npm.ts

@@ -1,308 +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 { optionalPeerNames, parseJsonObject, stringOr, stringRecord } from "./json.js"
-import { isRecord } from "../utils/is-record.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-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;
+};