@packall/core 0.0.1 → 0.2.0

package/src/platform.ts

@@ -0,0 +1,178 @@
+/**
+ * Platform matching for optional dependencies.
+ *
+ * The default is "keep every platform" and narrowing is opt-in — see
+ * `notes/requirements.md` § FR-13 for the failure mode that decides it.
+ *
+ * The mechanics that decision rests on are here rather than there: a package
+ * declares `os`, `cpu` and `libc` in its own manifest, and this module keeps a
+ * package when the filter *could* install it, not when it matches exactly.
+ */
+
+/** A target to keep, e.g. `linux-x64`, `linux-x64-musl`, or just `linux`. */
+export type PlatformTarget = {
+	readonly os: string;
+	/** Undefined means "every architecture for this OS". */
+	readonly cpu?: string | undefined;
+	/** `glibc` / `musl`. Undefined means "don't care". */
+	readonly libc?: string | undefined;
+};
+
+/**
+ * Which platforms optional dependencies should be resolved for.
+ *
+ * - `All` — keep everything, regardless of `os`/`cpu`/`libc` (the default).
+ * - `Targets` — keep only packages that could install on one of these.
+ */
+export type PlatformFilter =
+	| { readonly _tag: "All" }
+	| { readonly _tag: "Targets"; readonly targets: ReadonlyArray<PlatformTarget> };
+
+/** Constraints declared by a package, as they appear in its manifest. */
+export type PlatformConstraints = {
+	readonly os?: ReadonlyArray<string> | undefined;
+	readonly cpu?: ReadonlyArray<string> | undefined;
+	readonly libc?: ReadonlyArray<string> | undefined;
+};
+
+export const allPlatforms: PlatformFilter = { _tag: "All" };
+
+export const platformTargets = (targets: ReadonlyArray<PlatformTarget>): PlatformFilter => ({
+	_tag: "Targets",
+	targets,
+});
+
+/** The machine we are currently running on. */
+export const currentPlatform = (): PlatformTarget => ({
+	os: process.platform,
+	cpu: process.arch,
+});
+
+/**
+ * npm's documented `os` values, plus the names people actually type.
+ *
+ * An OS on its own is a valid target, so a typo has to be caught here — the
+ * whole failure mode this tool exists to prevent is a bundle that looks fine
+ * and installs nothing. `--platform windows` silently matching no binding at
+ * all would be precisely that, so it is corrected rather than accepted.
+ */
+const osByAlias: Readonly<Record<string, string | undefined>> = {
+	win: "win32",
+	windows: "win32",
+	mac: "darwin",
+	macos: "darwin",
+	osx: "darwin",
+};
+
+const KNOWN_OS: ReadonlySet<string> = new Set([
+	"aix",
+	"android",
+	"cygwin",
+	"darwin",
+	"freebsd",
+	"haiku",
+	"linux",
+	"netbsd",
+	"openbsd",
+	"sunos",
+	"win32",
+]);
+
+const LIBC: ReadonlySet<string> = new Set(["musl", "glibc"]);
+
+/**
+ * Parses `linux`, `linux-x64`, `darwin-arm64`, `win32-x64`, `linux-x64-musl`,
+ * `linux-musl`.
+ *
+ * An OS on its own means every architecture for that OS, which is almost always
+ * what you want: "the Windows and Linux bindings" is a far more natural way to
+ * describe a target set than enumerating four `os-arch` pairs, and it keeps
+ * working when a package adds an arm64 build.
+ *
+ * Returns `null` rather than throwing so the CLI can report every bad value at
+ * once alongside the list of accepted forms.
+ */
+export const parsePlatformTarget = (input: string): PlatformTarget | null => {
+	const parts = input
+		.trim()
+		.toLowerCase()
+		.split("-")
+		.filter((part) => part.length > 0);
+	const [rawOs, second, third] = parts;
+	if (rawOs === undefined || parts.length > 3) return null;
+
+	const os = osByAlias[rawOs] ?? rawOs;
+	if (!KNOWN_OS.has(os)) return null;
+
+	if (second === undefined) return { os };
+
+	// `linux-musl` is an OS plus a libc, not an OS plus an architecture.
+	if (third === undefined) {
+		return LIBC.has(second) ? { os, libc: second } : { os, cpu: second };
+	}
+
+	if (!LIBC.has(third)) return null;
+	return { os, cpu: second, libc: third };
+};
+
+/**
+ * npm's `os`/`cpu`/`libc` fields use a list of allowed values, where a leading
+ * `!` negates. An empty or absent list means "no constraint".
+ *
+ * The semantics npm implements: if any negated entry matches, reject. Otherwise
+ * if there are any positive entries, at least one must match.
+ */
+const listAllows = (list: ReadonlyArray<string> | undefined, value: string): boolean => {
+	if (list === undefined || list.length === 0) return true;
+
+	let hasPositive = false;
+	let positiveMatched = false;
+
+	for (const entry of list) {
+		const normalized = entry.trim().toLowerCase();
+		if (normalized.length === 0) continue;
+		if (normalized === "any" || normalized === "*") return true;
+
+		if (normalized.startsWith("!")) {
+			if (normalized.slice(1) === value) return false;
+		} else {
+			hasPositive = true;
+			if (normalized === value) positiveMatched = true;
+		}
+	}
+
+	return hasPositive ? positiveMatched : true;
+};
+
+/** Would this package install on this specific target? */
+export const matchesTarget = (
+	constraints: PlatformConstraints,
+	target: PlatformTarget,
+): boolean => {
+	if (!listAllows(constraints.os, target.os)) return false;
+	// An undefined cpu means the target is the whole OS, so any architecture the
+	// package declares qualifies.
+	if (target.cpu !== undefined && !listAllows(constraints.cpu, target.cpu)) return false;
+	if (target.libc !== undefined && !listAllows(constraints.libc, target.libc)) return false;
+	return true;
+};
+
+/**
+ * Should this package be included, given the active filter?
+ *
+ * Under `All` this is unconditionally `true` — that is the whole point.
+ */
+export const isIncluded = (constraints: PlatformConstraints, filter: PlatformFilter): boolean => {
+	if (filter._tag === "All") return true;
+	return filter.targets.some((target) => matchesTarget(constraints, target));
+};
+
+/** Renders a filter for the manifest and for `--dry-run` output. */
+export const formatPlatformFilter = (filter: PlatformFilter): string => {
+	if (filter._tag === "All") return "all";
+	return filter.targets
+		.map((target) =>
+			[target.os, target.cpu, target.libc].filter((part) => part !== undefined).join("-"),
+		)
+		.join(",");
+};

package/src/progress.ts

@@ -0,0 +1,105 @@
+/**
+ * Progress reporting.
+ *
+ * The engine emits structured events; it never writes to a terminal. That
+ * separation is what lets the CLI draw a live TTY view, CI print plain lines,
+ * and the test suite assert on an array of events without any of them
+ * interfering with each other.
+ */
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Ref from "effect/Ref";
+
+import type { Phase } from "./enums/phase.js";
+
+/** A structured progress event. */
+export type ProgressEvent =
+	/** A phase began. `total` is set only when it is known up front. */
+	| { readonly _tag: "PhaseStarted"; readonly phase: Phase; readonly total?: number | undefined }
+	/** A phase finished. */
+	| { readonly _tag: "PhaseCompleted"; readonly phase: Phase }
+	/** The resolver discovered a package that has to be included. */
+	| {
+			readonly _tag: "PackageResolved";
+			readonly name: string;
+			readonly version: string;
+			/** Running count of resolved packages, for a live counter. */
+			readonly resolvedCount: number;
+			/** Packages still queued for resolution. */
+			readonly pendingCount: number;
+	  }
+	/** A tarball download started. */
+	| { readonly _tag: "DownloadStarted"; readonly name: string; readonly version: string }
+	/** A tarball download finished. */
+	| {
+			readonly _tag: "DownloadCompleted";
+			readonly name: string;
+			readonly version: string;
+			readonly bytes: number;
+			readonly completedCount: number;
+			readonly totalCount: number;
+	  }
+	/** A download failed and will be retried. */
+	| {
+			readonly _tag: "DownloadRetrying";
+			readonly name: string;
+			readonly version: string;
+			readonly attempt: number;
+			readonly reason: string;
+	  }
+	/** An archive is being written. */
+	| { readonly _tag: "ArchiveStarted"; readonly path: string; readonly entryCount: number }
+	/** An archive finished. */
+	| { readonly _tag: "ArchiveCompleted"; readonly path: string; readonly bytes: number }
+	/** Something noteworthy but non-fatal, e.g. a deprecated package. */
+	| { readonly _tag: "Warning"; readonly message: string };
+
+export declare namespace Progress {
+	/** The reporting sink. */
+	export type Service = {
+		readonly emit: (event: ProgressEvent) => Effect.Effect<void>;
+	};
+}
+
+/** Service tag for progress reporting. */
+export class Progress extends Context.Service<Progress, Progress.Service>()(
+	"@packall/core/Progress",
+) {}
+
+/** Emits an event to whichever reporter is installed. */
+export const emit = (event: ProgressEvent): Effect.Effect<void, never, Progress> =>
+	Effect.gen(function* () {
+		const progress = yield* Progress;
+		yield* progress.emit(event);
+	});
+
+/**
+ * Discards every event.
+ *
+ * The default for library consumers and for tests that do not care about
+ * progress — silence should never require ceremony.
+ */
+export const layerSilent: Layer.Layer<Progress> = Layer.succeed(Progress)({
+	emit: () => Effect.void,
+});
+
+/** Sends every event to a callback. Used by the CLI renderer. */
+export const layerCallback = (onEvent: (event: ProgressEvent) => void): Layer.Layer<Progress> =>
+	Layer.succeed(Progress)({
+		emit: (event) => Effect.sync(() => onEvent(event)),
+	});
+
+/**
+ * Accumulates every event into a `Ref`, for assertions.
+ *
+ * Returned as `{ layer, events }` so a test can provide the layer and then read
+ * the transcript afterwards.
+ */
+export const makeCollector = Effect.gen(function* () {
+	const ref = yield* Ref.make<ReadonlyArray<ProgressEvent>>([]);
+	const layer = Layer.succeed(Progress)({
+		emit: (event: ProgressEvent) => Ref.update(ref, (events) => [...events, event]),
+	});
+	return { layer, events: Ref.get(ref) } as const;
+});

package/src/registry.ts

@@ -0,0 +1,116 @@
+/**
+ * The registry seam.
+ *
+ * This is the **only** place in the engine that knows a registry exists.
+ * Everything downstream — range resolution, the dependency walk, layout,
+ * archiving — is expressed against these three operations, so swapping npm for
+ * something else means implementing this interface and nothing more.
+ *
+ * `@packall/registry-npm` provides the implementation that speaks the plain
+ * npm registry protocol, which is what Artifactory, Nexus, Verdaccio, GitHub
+ * Packages and registry.npmjs.org all serve.
+ */
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
+
+import type { BundlerError } from "./errors.js";
+
+/** Where the tarball lives and how to prove it arrived intact. */
+export type PackageDist = {
+	readonly tarball: string;
+	/** SRI string, e.g. `sha512-...`. Preferred over `shasum`. */
+	readonly integrity?: string | undefined;
+	/** Legacy hex sha1. Still the only checksum on very old versions. */
+	readonly shasum?: string | undefined;
+	readonly unpackedSize?: number | undefined;
+	readonly fileCount?: number | undefined;
+};
+
+/**
+ * A single published version, as the registry describes it.
+ *
+ * This is a narrowed view of a package.json — only the fields that affect what
+ * has to be downloaded. Unknown fields are ignored rather than rejected,
+ * because registries add metadata over time and a bundler that breaks on new
+ * metadata is worse than useless.
+ */
+export type PackageManifest = {
+	readonly name: string;
+	readonly version: string;
+
+	readonly dependencies?: Readonly<Record<string, string>> | undefined;
+	readonly optionalDependencies?: Readonly<Record<string, string>> | undefined;
+	readonly peerDependencies?: Readonly<Record<string, string>> | undefined;
+	readonly peerDependenciesMeta?:
+		| Readonly<Record<string, { readonly optional?: boolean | undefined }>>
+		| undefined;
+	readonly devDependencies?: Readonly<Record<string, string>> | undefined;
+	readonly bundleDependencies?: ReadonlyArray<string> | undefined;
+
+	/** Platform constraints, used when `--platform` narrows optional deps. */
+	readonly os?: ReadonlyArray<string> | undefined;
+	readonly cpu?: ReadonlyArray<string> | undefined;
+	readonly libc?: ReadonlyArray<string> | undefined;
+
+	readonly deprecated?: string | undefined;
+
+	readonly dist: PackageDist;
+};
+
+/** Everything the registry knows about one package. */
+export type Packument = {
+	readonly name: string;
+	/** `{ latest: "1.2.3", next: "2.0.0-beta.1" }` */
+	readonly distTags: Readonly<Record<string, string>>;
+	/** Every published version, keyed by version string. */
+	readonly versions: Readonly<Record<string, PackageManifest>>;
+};
+
+export declare namespace Registry {
+	/** The set of operations a registry backend has to provide. */
+	export type Service = {
+		/** Short identifier for the manifest and for error messages, e.g. `"npm"`. */
+		readonly kind: string;
+
+		/**
+		 * The registry URL that will actually be used for a given package, after
+		 * per-scope configuration is applied. Used for reporting only.
+		 */
+		readonly registryFor: (packageName: string) => string;
+
+		/**
+		 * Cheap liveness check, run once before any real work.
+		 *
+		 * This is what turns "hangs forever behind a dead VPN" into a five-second
+		 * error naming the host we could not reach.
+		 */
+		readonly preflight: Effect.Effect<void, BundlerError>;
+
+		/**
+		 * Full metadata for a package. Implementations are expected to memoise:
+		 * the dependency walk asks for the same popular packages repeatedly.
+		 */
+		readonly packument: (packageName: string) => Effect.Effect<Packument, BundlerError>;
+
+		/** Fetches the tarball bytes for one published version. */
+		readonly download: (manifest: PackageManifest) => Effect.Effect<Uint8Array, BundlerError>;
+	};
+}
+
+/**
+ * Service tag for the registry backend.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { Registry } from "@packall/core"
+ *
+ * const program = Effect.gen(function*() {
+ *   const registry = yield* Registry
+ *   return yield* registry.packument("lodash")
+ * })
+ * ```
+ */
+export class Registry extends Context.Service<Registry, Registry.Service>()(
+	"@packall/core/Registry",
+) {}