@packall/core 0.0.1 → 0.2.0

package/src/dependency-range.ts

@@ -0,0 +1,121 @@
+/**
+ * Classification of the right-hand side of a dependency entry.
+ *
+ * `"dependencies": { "x": "^1.0.0" }` is the easy case. Real package.json files
+ * also contain aliases, git URLs, tarball URLs, `file:` links and
+ * `workspace:` protocols — none of which can be fetched from a registry.
+ *
+ * Rather than crashing or silently producing a bundle that will not install,
+ * we classify each edge and let the caller report precisely what was skipped
+ * and why.
+ */
+import semver from "semver";
+
+import type { Selector } from "./spec.js";
+
+/** What a dependency edge points at. */
+export type DependencyTarget =
+	/** A normal registry dependency. `name` may differ from the key under an alias. */
+	| {
+			readonly _tag: "Registry";
+			readonly name: string;
+			readonly selector: Selector;
+			/** Set when the edge is an `npm:` alias, e.g. `"lodash4": "npm:lodash@^4"`. */
+			readonly aliasOf?: string | undefined;
+	  }
+	/** Something we cannot fetch from a registry. */
+	| {
+			readonly _tag: "Unsupported";
+			readonly name: string;
+			readonly raw: string;
+			readonly reason: string;
+	  };
+
+const UNSUPPORTED_PROTOCOLS: ReadonlyArray<readonly [string, string]> = [
+	["file:", "local file path"],
+	["link:", "local link"],
+	["workspace:", "workspace protocol"],
+	["portal:", "portal protocol"],
+	["patch:", "patch protocol"],
+	["git:", "git dependency"],
+	["git+", "git dependency"],
+	["github:", "GitHub shorthand"],
+	["gitlab:", "GitLab shorthand"],
+	["bitbucket:", "Bitbucket shorthand"],
+	["http:", "remote tarball URL"],
+	["https:", "remote tarball URL"],
+];
+
+/**
+ * Classifies one `name -> range` entry.
+ *
+ * An empty range, `*`, and `latest` all mean "any published version"; npm
+ * treats them interchangeably and so do we.
+ */
+export const parseDependencyTarget = (name: string, raw: string): DependencyTarget => {
+	const text = raw.trim();
+
+	if (text.length === 0 || text === "*" || text === "x" || text === "latest") {
+		return { _tag: "Registry", name, selector: { _tag: "Range", range: "*" } };
+	}
+
+	if (text.startsWith("npm:")) {
+		return parseAlias(name, text);
+	}
+
+	for (const [prefix, reason] of UNSUPPORTED_PROTOCOLS) {
+		if (text.startsWith(prefix)) {
+			return { _tag: "Unsupported", name, raw: text, reason };
+		}
+	}
+
+	// Bare `owner/repo` is GitHub shorthand, but only when it is not a valid
+	// range — `>=1.0.0/2` is not a thing, so this ordering is safe.
+	if (semver.validRange(text, { loose: true }) === null && /^[\w.-]+\/[\w.-]+/.test(text)) {
+		return { _tag: "Unsupported", name, raw: text, reason: "git shorthand" };
+	}
+
+	const exact = semver.valid(text, { loose: true });
+	if (exact !== null) {
+		return { _tag: "Registry", name, selector: { _tag: "Exact", version: exact } };
+	}
+
+	if (semver.validRange(text, { loose: true }) !== null) {
+		return { _tag: "Registry", name, selector: { _tag: "Range", range: text } };
+	}
+
+	// Whatever is left is most plausibly a dist-tag published by a private
+	// registry, e.g. `"@acme/sdk": "stable"`.
+	if (/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(text)) {
+		return { _tag: "Registry", name, selector: { _tag: "Tag", tag: text } };
+	}
+
+	return { _tag: "Unsupported", name, raw: text, reason: "unrecognised version specifier" };
+};
+
+/**
+ * Parses `npm:<name>[@<range>]`.
+ *
+ * The nested name may itself be scoped, so the `@` split has the same
+ * "not at index 0" caveat as top-level spec parsing.
+ */
+const parseAlias = (key: string, text: string): DependencyTarget => {
+	const body = text.slice("npm:".length);
+	if (body.length === 0) {
+		return { _tag: "Unsupported", name: key, raw: text, reason: "empty npm: alias" };
+	}
+
+	const at = body.lastIndexOf("@");
+	const target = at > 0 ? body.slice(0, at) : body;
+	const rangeText = at > 0 ? body.slice(at + 1) : "";
+
+	if (target.length === 0) {
+		return { _tag: "Unsupported", name: key, raw: text, reason: "empty npm: alias target" };
+	}
+
+	const inner = parseDependencyTarget(target, rangeText);
+	if (inner._tag === "Unsupported") {
+		return { ...inner, name: key, raw: text };
+	}
+	return { _tag: "Registry", name: target, selector: inner.selector, aliasOf: key };
+};

package/src/download.ts

@@ -0,0 +1,155 @@
+/**
+ * Fetching tarballs into the staging tree.
+ *
+ * Downloads run concurrently, every one is checksum-verified before it is
+ * written, and the destination is always the scoped temp directory — nothing
+ * lands next to the user's own files.
+ */
+import type * as Crypto from "effect/Crypto";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import type { PlatformError } from "effect/PlatformError";
+
+import { Phase } from "./enums/phase.js";
+import type { BundlerError } from "./errors.js";
+import { IntegrityError, OutputError } from "./errors.js";
+import * as Integrity from "./integrity.js";
+import { packagePath } from "./layout.js";
+import * as Progress from "./progress.js";
+import { Registry } from "./registry.js";
+import type { ResolvedPackage } from "./resolve.js";
+
+/** What a completed download run produced. */
+export type DownloadReport = {
+	/** `name@version` -> bytes written. */
+	readonly sizes: ReadonlyMap<string, number>;
+	/** Packages the registry advertised no usable checksum for. */
+	readonly unverified: ReadonlyArray<string>;
+	readonly totalBytes: number;
+};
+
+/**
+ * Downloads every package into `destDir`, laid out the way a registry serves
+ * them.
+ *
+ * `verifyIntegrity` defaulting to on is deliberate: a corrupt tarball that
+ * makes it into a corporate registry is far more expensive than a failed run.
+ */
+export const downloadAll = (
+	packages: ReadonlyArray<ResolvedPackage>,
+	destDir: string,
+	options: { readonly concurrency: number; readonly verifyIntegrity: boolean },
+): Effect.Effect<
+	DownloadReport,
+	BundlerError | PlatformError,
+	Registry | Progress.Progress | FileSystem.FileSystem | Path.Path | Crypto.Crypto
+> =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		const registry = yield* Registry;
+
+		yield* Progress.emit({
+			_tag: "PhaseStarted",
+			phase: Phase.Download,
+			total: packages.length,
+		});
+
+		let completed = 0;
+		const sizes = new Map<string, number>();
+		const unverified: Array<string> = [];
+
+		const results = yield* Effect.forEach(
+			packages,
+			(pkg) =>
+				Effect.gen(function* () {
+					const key = `${pkg.name}@${pkg.version}`;
+
+					yield* Progress.emit({
+						_tag: "DownloadStarted",
+						name: pkg.name,
+						version: pkg.version,
+					});
+
+					const bytes = yield* registry.download(pkg.manifest);
+
+					if (options.verifyIntegrity) {
+						const result = yield* Integrity.verify(bytes, pkg.manifest.dist);
+						if (result._tag === "Mismatch") {
+							return yield* Effect.fail(
+								new IntegrityError(
+									pkg.name,
+									pkg.version,
+									result.expected,
+									result.actual,
+								),
+							);
+						}
+						if (result._tag === "Unverifiable") {
+							yield* Progress.emit({
+								_tag: "Warning",
+								message: `${key} could not be verified (${result.reason})`,
+							});
+						}
+					}
+
+					const verifiable =
+						(pkg.manifest.dist.integrity?.length ?? 0) > 0 ||
+						(pkg.manifest.dist.shasum?.length ?? 0) > 0;
+
+					const relative = packagePath(pkg.name, pkg.version);
+					const target = path.join(destDir, ...relative.split("/"));
+
+					yield* fs
+						.makeDirectory(path.dirname(target), { recursive: true })
+						.pipe(
+							Effect.mapError(
+								(cause) =>
+									new OutputError(
+										path.dirname(target),
+										"could not create directory",
+										{ cause },
+									),
+							),
+						);
+					yield* fs
+						.writeFile(target, bytes)
+						.pipe(
+							Effect.mapError(
+								(cause) =>
+									new OutputError(target, "could not write tarball", { cause }),
+							),
+						);
+
+					// Counting here rather than inside the concurrent body would be
+					// wrong; each fiber increments as it finishes, which is what makes
+					// the progress counter monotonic.
+					completed += 1;
+					yield* Progress.emit({
+						_tag: "DownloadCompleted",
+						name: pkg.name,
+						version: pkg.version,
+						bytes: bytes.byteLength,
+						completedCount: completed,
+						totalCount: packages.length,
+					});
+
+					return { key, bytes: bytes.byteLength, verifiable } as const;
+				}),
+			{ concurrency: options.concurrency },
+		);
+
+		for (const result of results) {
+			sizes.set(result.key, result.bytes);
+			if (!result.verifiable) unverified.push(result.key);
+		}
+
+		yield* Progress.emit({ _tag: "PhaseCompleted", phase: Phase.Download });
+
+		return {
+			sizes,
+			unverified,
+			totalBytes: results.reduce((sum, result) => sum + result.bytes, 0),
+		};
+	});

package/src/enums/artifact-kind.ts

@@ -0,0 +1,9 @@
+import type { ValueOf } from "../types/value-of.js";
+
+/** What a bundle run wrote to the output directory. */
+export const ArtifactKind = {
+	Archive: "archive",
+	Directory: "directory",
+} as const;
+
+export type ArtifactKind = ValueOf<typeof ArtifactKind>;

package/src/enums/edge-kind.ts

@@ -0,0 +1,32 @@
+import type { ValueOf } from "../types/value-of.js";
+
+/**
+ * Why one package depends on another.
+ *
+ * `EdgeKind` and `LockedRootKind` are one concept in two parts, which is why
+ * they share a file: `Dev` exists only at the top level, because lockfiles
+ * record dev dependencies for the project alone — a transitive devDependency is
+ * never installed, so it is never locked.
+ */
+export const EdgeKind = {
+	Prod: "prod",
+	Optional: "optional",
+	Peer: "peer",
+} as const;
+
+export type EdgeKind = ValueOf<typeof EdgeKind>;
+
+/** The kind that only a direct dependency of the locked project can have. */
+export const DirectOnlyKind = {
+	Dev: "dev",
+} as const;
+
+export type DirectOnlyKind = ValueOf<typeof DirectOnlyKind>;
+
+/** Why a direct dependency of the locked project is a root. */
+export const LockedRootKind = {
+	...EdgeKind,
+	...DirectOnlyKind,
+} as const;
+
+export type LockedRootKind = ValueOf<typeof LockedRootKind>;

package/src/enums/input-file-kind.ts

@@ -0,0 +1,13 @@
+import type { ValueOf } from "../types/value-of.js";
+
+/** Which of the three shapes a `--file` input turned out to be. */
+export const InputFileKind = {
+	/** Bundle everything a package.json depends on. */
+	PackageJson: "package.json",
+	/** Bundle the exact versions a lockfile pins. */
+	Lockfile: "lockfile",
+	/** A newline-delimited list of specs. */
+	List: "list",
+} as const;
+
+export type InputFileKind = ValueOf<typeof InputFileKind>;

package/src/enums/layout.ts

@@ -0,0 +1,25 @@
+import type { ValueOf } from "../types/value-of.js";
+
+/** How the resulting tarball(s) are shaped. */
+export const Layout = {
+	/**
+	 * One tarball per requested spec, each carrying its own complete dependency
+	 * closure. Shared dependencies repeat across tarballs, so the total is
+	 * larger — but each one imports, rolls back and hands off independently.
+	 */
+	PerSpec: "per-spec",
+	/**
+	 * One tarball for everything, with the union of all closures deduplicated.
+	 * Smallest output and a single import step; all-or-nothing to roll back.
+	 */
+	Single: "single",
+	/**
+	 * No archive at all — just the npm-layout directory tree, ready for
+	 * `jf rt upload` or rsync.
+	 */
+	Dir: "dir",
+} as const;
+
+export type Layout = ValueOf<typeof Layout>;
+
+export const Layouts: ReadonlyArray<Layout> = Object.values(Layout);

package/src/enums/lockfile-format.ts

@@ -0,0 +1,10 @@
+import type { ValueOf } from "../types/value-of.js";
+
+/** Which package manager wrote a lockfile. */
+export const LockfileFormat = {
+	Npm: "npm",
+	Pnpm: "pnpm",
+	Bun: "bun",
+} as const;
+
+export type LockfileFormat = ValueOf<typeof LockfileFormat>;

package/src/enums/phase.ts

@@ -0,0 +1,12 @@
+import type { ValueOf } from "../types/value-of.js";
+
+/** The phases a bundle run moves through, in order. */
+export const Phase = {
+	Preflight: "preflight",
+	Resolve: "resolve",
+	Download: "download",
+	Archive: "archive",
+	Done: "done",
+} as const;
+
+export type Phase = ValueOf<typeof Phase>;

package/src/errors.ts

@@ -0,0 +1,300 @@
+/**
+ * Failure types for the bundler.
+ *
+ * These are deliberately plain classes carrying a literal `_tag` rather than
+ * `Data.TaggedError`. They work with `Effect.catchTag` / `Effect.catchTags`
+ * exactly the same way, and they keep the public error surface independent of
+ * any single Effect release — useful while Effect v4 is still in beta.
+ *
+ * Every error carries enough context to be actionable without a stack trace,
+ * because the primary consumer is somebody staring at a terminal on a
+ * locked-down network trying to work out why a download did not happen.
+ */
+
+/** Discriminant union of every failure the bundler can produce. */
+export type BundlerError =
+	| InvalidSpecError
+	| InvalidInputFileError
+	| LockfileError
+	| LockfileIncompleteError
+	| LockfileOutOfDateError
+	| RegistryUnreachableError
+	| PackageNotFoundError
+	| VersionNotFoundError
+	| NoMatchingVersionsError
+	| RegistryResponseError
+	| AuthenticationError
+	| IntegrityError
+	| ArchiveError
+	| OutputError;
+
+abstract class BundlerErrorBase extends Error {
+	abstract readonly _tag: string;
+	constructor(message: string, options?: ErrorOptions) {
+		super(message, options);
+		this.name = new.target.name;
+	}
+}
+
+/** A package spec on the command line or in an input file could not be parsed. */
+export class InvalidSpecError extends BundlerErrorBase {
+	readonly _tag = "InvalidSpecError" as const;
+	readonly spec: string;
+	readonly reason: string;
+	constructor(spec: string, reason: string) {
+		super(`Invalid package spec ${JSON.stringify(spec)}: ${reason}`);
+		this.spec = spec;
+		this.reason = reason;
+	}
+}
+
+/** `--file` pointed at something that is neither a usable package.json nor a spec list. */
+export class InvalidInputFileError extends BundlerErrorBase {
+	readonly _tag = "InvalidInputFileError" as const;
+	readonly path: string;
+	readonly reason: string;
+	constructor(path: string, reason: string, options?: { cause?: unknown }) {
+		super(`Cannot read specs from ${path}: ${reason}`, options);
+		this.path = path;
+		this.reason = reason;
+	}
+}
+
+/** A lockfile could not be read, or is in a format we do not support. */
+export class LockfileError extends BundlerErrorBase {
+	readonly _tag = "LockfileError" as const;
+	readonly path: string;
+	readonly reason: string;
+	constructor(path: string, reason: string, options?: { cause?: unknown }) {
+		// Opens with "Lockfile" so the renderer's tag prefix does not stutter, and
+		// because not every reason is a read failure — "does not cover this
+		// package" is about a file that read perfectly well.
+		super(`Lockfile ${path}: ${reason}`, options);
+		this.path = path;
+		this.reason = reason;
+	}
+}
+
+/**
+ * The lockfile parsed, but does not pin everything the bundle needs.
+ *
+ * Falling back to a range here would defeat the entire point of reading a
+ * lockfile — you would get a bundle that is *mostly* what CI installed, with no
+ * indication of which parts were guessed. So this is fatal, and it names every
+ * gap at once so one `npm install` fixes all of them.
+ */
+export class LockfileIncompleteError extends BundlerErrorBase {
+	readonly _tag = "LockfileIncompleteError" as const;
+	readonly path: string;
+	readonly missing: ReadonlyArray<string>;
+	constructor(path: string, missing: ReadonlyArray<string>, detail: string, remedy: string) {
+		const shown = missing
+			.slice(0, 10)
+			.map((entry) => `    ${entry}`)
+			.join("\n");
+		const rest = missing.length > 10 ? `\n    … and ${missing.length - 10} more` : "";
+		super(
+			`${path} is incomplete — ${detail}:\n${shown}${rest}\n` +
+				`  ${remedy}\n` +
+				`  Or pass --lockfile off to resolve version ranges fresh instead.`,
+		);
+		this.path = path;
+		this.missing = missing;
+	}
+}
+
+/**
+ * The lockfile pins versions the registry no longer serves.
+ *
+ * Unpublished, or never mirrored into a private registry. Either way the
+ * bundle cannot be built as specified, and quietly substituting a nearby
+ * version would produce exactly the mismatch this feature exists to prevent.
+ */
+export class LockfileOutOfDateError extends BundlerErrorBase {
+	readonly _tag = "LockfileOutOfDateError" as const;
+	readonly path: string;
+	readonly registry: string;
+	readonly missing: ReadonlyArray<{ readonly name: string; readonly version: string }>;
+	constructor(
+		path: string,
+		registry: string,
+		missing: ReadonlyArray<{
+			readonly name: string;
+			readonly version: string;
+			readonly detail: string;
+		}>,
+	) {
+		const shown = missing
+			.slice(0, 10)
+			.map((entry) => `    ${entry.name}@${entry.version} — ${entry.detail}`)
+			.join("\n");
+		const rest = missing.length > 10 ? `\n    … and ${missing.length - 10} more` : "";
+		super(
+			`${path} pins ${missing.length} version${missing.length === 1 ? "" : "s"} ` +
+				`that ${registry} does not serve:\n${shown}${rest}\n` +
+				`  Refresh the lockfile against this registry, or pass --lockfile off to\n` +
+				`  resolve version ranges fresh instead.`,
+		);
+		this.path = path;
+		this.registry = registry;
+		this.missing = missing.map(({ name, version }) => ({ name, version }));
+	}
+}
+
+/**
+ * The registry could not be reached at all — DNS failure, refused connection,
+ * proxy blackhole, or a preflight that timed out.
+ *
+ * This is the error that fixes "hangs forever with no network": we surface it
+ * quickly and say which host we could not reach.
+ */
+export class RegistryUnreachableError extends BundlerErrorBase {
+	readonly _tag = "RegistryUnreachableError" as const;
+	readonly registry: string;
+	readonly timeoutMs: number | undefined;
+	constructor(
+		registry: string,
+		detail: string,
+		options?: { cause?: unknown; timeoutMs?: number },
+	) {
+		super(
+			`Cannot reach registry ${registry}: ${detail}.\n` +
+				`  Check your network connection, VPN, and the proxy settings in your .npmrc.`,
+			options,
+		);
+		this.registry = registry;
+		this.timeoutMs = options?.timeoutMs;
+	}
+}
+
+/** The registry answered, but has never heard of this package. */
+export class PackageNotFoundError extends BundlerErrorBase {
+	readonly _tag = "PackageNotFoundError" as const;
+	readonly packageName: string;
+	readonly registry: string;
+	constructor(packageName: string, registry: string) {
+		super(`Package "${packageName}" was not found on ${registry}`);
+		this.packageName = packageName;
+		this.registry = registry;
+	}
+}
+
+/** The package exists but the exact version requested does not. */
+export class VersionNotFoundError extends BundlerErrorBase {
+	readonly _tag = "VersionNotFoundError" as const;
+	readonly packageName: string;
+	readonly version: string;
+	readonly available: ReadonlyArray<string>;
+	constructor(packageName: string, version: string, available: ReadonlyArray<string>) {
+		const tail = available.slice(-5).join(", ");
+		super(
+			`${packageName}@${version} does not exist.` +
+				(tail.length > 0 ? ` Most recent published versions: ${tail}` : ""),
+		);
+		this.packageName = packageName;
+		this.version = version;
+		this.available = available;
+	}
+}
+
+/** A range (or dist-tag) matched nothing that is actually published. */
+export class NoMatchingVersionsError extends BundlerErrorBase {
+	readonly _tag = "NoMatchingVersionsError" as const;
+	readonly packageName: string;
+	readonly selector: string;
+	readonly available: ReadonlyArray<string>;
+	constructor(packageName: string, selector: string, available: ReadonlyArray<string>) {
+		const tail = available.slice(-5).join(", ");
+		super(
+			`No published version of ${packageName} satisfies "${selector}".` +
+				(tail.length > 0 ? ` Most recent published versions: ${tail}` : ""),
+		);
+		this.packageName = packageName;
+		this.selector = selector;
+		this.available = available;
+	}
+}
+
+/** The registry responded, but with something we cannot use. */
+export class RegistryResponseError extends BundlerErrorBase {
+	readonly _tag = "RegistryResponseError" as const;
+	readonly url: string;
+	readonly status: number | undefined;
+	constructor(url: string, detail: string, options?: { cause?: unknown; status?: number }) {
+		super(`Unexpected response from ${url}: ${detail}`, options);
+		this.url = url;
+		this.status = options?.status;
+	}
+}
+
+/** 401/403 — almost always a missing or stale token in `.npmrc`. */
+export class AuthenticationError extends BundlerErrorBase {
+	readonly _tag = "AuthenticationError" as const;
+	readonly registry: string;
+	readonly status: number;
+	constructor(registry: string, status: number, packageName?: string) {
+		super(
+			`Registry ${registry} rejected the request with HTTP ${status}` +
+				(packageName ? ` while fetching "${packageName}"` : "") +
+				`.\n  Add credentials to your .npmrc, e.g.\n` +
+				`    //${safeHost(registry)}/:_authToken=\${NPM_TOKEN}`,
+		);
+		this.registry = registry;
+		this.status = status;
+	}
+}
+
+/**
+ * A downloaded tarball did not match the checksum the registry advertised.
+ *
+ * Never soft-fail this: a bundle is a supply-chain artifact and a corrupt or
+ * substituted tarball is exactly what integrity checking exists to catch.
+ */
+export class IntegrityError extends BundlerErrorBase {
+	readonly _tag = "IntegrityError" as const;
+	readonly packageName: string;
+	readonly version: string;
+	readonly expected: string;
+	readonly actual: string;
+	constructor(packageName: string, version: string, expected: string, actual: string) {
+		super(
+			`Integrity check failed for ${packageName}@${version}.\n` +
+				`  expected: ${expected}\n` +
+				`  actual:   ${actual}\n` +
+				`  The download was discarded. This is either corruption in transit or a tampered artifact.`,
+		);
+		this.packageName = packageName;
+		this.version = version;
+		this.expected = expected;
+		this.actual = actual;
+	}
+}
+
+/** Something went wrong writing the `.tgz`. */
+export class ArchiveError extends BundlerErrorBase {
+	readonly _tag = "ArchiveError" as const;
+	readonly path: string;
+	constructor(path: string, detail: string, options?: { cause?: unknown }) {
+		super(`Failed to create archive ${path}: ${detail}`, options);
+		this.path = path;
+	}
+}
+
+/** Something went wrong preparing or writing to the output directory. */
+export class OutputError extends BundlerErrorBase {
+	readonly _tag = "OutputError" as const;
+	readonly path: string;
+	constructor(path: string, detail: string, options?: { cause?: unknown }) {
+		super(`Output error at ${path}: ${detail}`, options);
+		this.path = path;
+	}
+}
+
+const safeHost = (registry: string): string => {
+	try {
+		const url = new URL(registry);
+		return url.host + url.pathname.replace(/\/+$/, "");
+	} catch {
+		return registry;
+	}
+};