@packall/core 0.1.0 → 0.3.0

package/src/enums/layout.ts

@@ -1,25 +1,25 @@
-import type { ValueOf } from "../types/value-of.js"
+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
+	/**
+	 * 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 type Layout = ValueOf<typeof Layout>;
 
-export const Layouts: ReadonlyArray<Layout> = Object.values(Layout)
+export const Layouts: ReadonlyArray<Layout> = Object.values(Layout);

package/src/enums/lockfile-format.ts

@@ -1,10 +1,10 @@
-import type { ValueOf } from "../types/value-of.js"
+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
+	Npm: "npm",
+	Pnpm: "pnpm",
+	Bun: "bun",
+} as const;
 
-export type LockfileFormat = ValueOf<typeof LockfileFormat>
+export type LockfileFormat = ValueOf<typeof LockfileFormat>;

package/src/enums/phase.ts

@@ -1,12 +1,12 @@
-import type { ValueOf } from "../types/value-of.js"
+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
+	Preflight: "preflight",
+	Resolve: "resolve",
+	Download: "download",
+	Archive: "archive",
+	Done: "done",
+} as const;
 
-export type Phase = ValueOf<typeof Phase>
+export type Phase = ValueOf<typeof Phase>;

package/src/errors.ts

@@ -13,66 +13,66 @@
 
 /** 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
+	| 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
-  }
+	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
-  }
+	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
-  }
+	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
-  }
+	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;
+	}
 }
 
 /**
@@ -84,25 +84,23 @@ export class LockfileError extends BundlerErrorBase {
  * 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
-  }
+	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;
+	}
 }
 
 /**
@@ -113,133 +111,147 @@ export class LockfileIncompleteError extends BundlerErrorBase {
  * 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 }))
-  }
+	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.
+ * a certificate the machine does not trust, 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
-  }
+	readonly _tag = "RegistryUnreachableError" as const;
+	readonly registry: string;
+	readonly timeoutMs: number | undefined;
+	/**
+	 * `hint` replaces the closing line of advice.
+	 *
+	 * The default suits the common case and is wrong for at least one: a
+	 * rejected certificate is not a network problem, and telling somebody to
+	 * check their VPN sends them to look at the one thing that is working. The
+	 * backend knows which failure it saw, so it is the backend that gets to say.
+	 */
+	constructor(
+		registry: string,
+		detail: string,
+		options?: { cause?: unknown; timeoutMs?: number; hint?: string | undefined },
+	) {
+		super(
+			`Cannot reach registry ${registry}: ${detail}.\n  ${options?.hint ?? NETWORK_HINT}`,
+			options,
+		);
+		this.registry = registry;
+		this.timeoutMs = options?.timeoutMs;
+	}
 }
 
+const NETWORK_HINT = "Check your network connection, VPN, and the proxy settings in your .npmrc.";
+
 /** 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
-  }
+	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
-  }
+	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
-  }
+	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
-  }
+	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
-  }
+	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;
+	}
 }
 
 /**
@@ -249,50 +261,50 @@ export class AuthenticationError extends BundlerErrorBase {
  * 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
-  }
+	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
-  }
+	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
-  }
+	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
-  }
-}
+	try {
+		const url = new URL(registry);
+		return url.host + url.pathname.replace(/\/+$/, "");
+	} catch {
+		return registry;
+	}
+};