@packall/core 0.1.0 → 0.2.0

package/src/platform.ts

@@ -1,27 +1,22 @@
 /**
  * Platform matching for optional dependencies.
  *
- * This module exists because of one specific, very annoying failure mode.
+ * The default is "keep every platform" and narrowing is opt-in — see
+ * `notes/requirements.md` § FR-13 for the failure mode that decides it.
  *
- * Packages with native code — esbuild, rollup, sharp, swc, lightningcss,
- * `@parcel/watcher` — publish their binary as a *set* of sibling packages, one
- * per platform, and list all of them in `optionalDependencies`. npm installs
- * only the one matching the current machine and silently skips the rest.
- *
- * So if you bundle on a Mac and skip the non-matching optional deps, the
- * resulting bundle installs fine on your Mac and fails on the Linux CI box
- * inside the firewall — which is the only place it actually matters. Hence the
- * default is "take every platform" and narrowing is opt-in.
+ * 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
-}
+	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.
@@ -30,28 +25,28 @@ export type PlatformTarget = {
  * - `Targets` — keep only packages that could install on one of these.
  */
 export type PlatformFilter =
-  | { readonly _tag: "All" }
-  | { readonly _tag: "Targets"; readonly targets: ReadonlyArray<PlatformTarget> }
+	| { 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
-}
+	readonly os?: ReadonlyArray<string> | undefined;
+	readonly cpu?: ReadonlyArray<string> | undefined;
+	readonly libc?: ReadonlyArray<string> | undefined;
+};
 
-export const allPlatforms: PlatformFilter = { _tag: "All" }
+export const allPlatforms: PlatformFilter = { _tag: "All" };
 
 export const platformTargets = (targets: ReadonlyArray<PlatformTarget>): PlatformFilter => ({
-  _tag: "Targets",
-  targets
-})
+	_tag: "Targets",
+	targets,
+});
 
 /** The machine we are currently running on. */
 export const currentPlatform = (): PlatformTarget => ({
-  os: process.platform,
-  cpu: process.arch
-})
+	os: process.platform,
+	cpu: process.arch,
+});
 
 /**
  * npm's documented `os` values, plus the names people actually type.
@@ -62,28 +57,28 @@ export const currentPlatform = (): PlatformTarget => ({
  * 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"
-}
+	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"])
+	"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`,
@@ -98,23 +93,27 @@ const LIBC: ReadonlySet<string> = new Set(["musl", "glibc"])
  * 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 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
+	const os = osByAlias[rawOs] ?? rawOs;
+	if (!KNOWN_OS.has(os)) return null;
 
-  if (second === undefined) return { os }
+	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 }
-  }
+	// `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 }
-}
+	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
@@ -124,59 +123,56 @@ export const parsePlatformTarget = (input: string): PlatformTarget | null => {
  * 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
+	if (list === undefined || list.length === 0) return true;
 
-  let hasPositive = false
-  let positiveMatched = false
+	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
+	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
-    }
-  }
+		if (normalized.startsWith("!")) {
+			if (normalized.slice(1) === value) return false;
+		} else {
+			hasPositive = true;
+			if (normalized === value) positiveMatched = true;
+		}
+	}
 
-  return hasPositive ? positiveMatched : true
-}
+	return hasPositive ? positiveMatched : true;
+};
 
 /** Would this package install on this specific target? */
 export const matchesTarget = (
-  constraints: PlatformConstraints,
-  target: PlatformTarget
+	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
-}
+	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))
-}
+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(",")
-}
+	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

@@ -1,106 +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
-})
+/**
+ * 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;
+});