@packall/core 0.0.1 → 0.1.0

package/src/{DependencyRange.ts → dependency-range.ts}

@@ -1,115 +1,115 @@
-/**
- * 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 }
-}
+/**
+ * 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 → download.ts}

@@ -1,132 +1,133 @@
-/**
- * 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 * as Effect from "effect/Effect"
-import * as FileSystem from "effect/FileSystem"
-import * as Path from "effect/Path"
-import type { PlatformError } from "effect/PlatformError"
-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 interface 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
-> =>
-  Effect.gen(function*() {
-    const fs = yield* FileSystem.FileSystem
-    const path = yield* Path.Path
-    const registry = yield* Registry
-
-    yield* Progress.emit({ _tag: "PhaseStarted", 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 = 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: "download" })
-
-    return {
-      sizes,
-      unverified,
-      totalBytes: results.reduce((sum, r) => sum + r.bytes, 0)
-    }
-  })
+/**
+ * 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 * 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
+> =>
+  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 = 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>