@packall/core 0.0.1 → 0.1.0

package/src/{Manifest.ts → manifest.ts}

@@ -1,133 +1,133 @@
-/**
- * The manifest written into every bundle.
- *
- * This is the audit trail. Before anything is imported into a corporate
- * registry somebody is usually required to answer "what exactly is in here and
- * where did it come from" — this file answers that without unpacking a single
- * tarball.
- */
-import type { Resolution, ResolvedPackage } from "./Resolve.js"
-import { packagePath } from "./Layout.js"
-import type { BundleOptions } from "./Options.js"
-import { formatPlatformFilter } from "./Platform.js"
-import { formatSpec } from "./Spec.js"
-
-/** Schema version, bumped when the shape changes incompatibly. */
-export const MANIFEST_VERSION = 1
-
-export interface ManifestEntry {
-  readonly name: string
-  readonly version: string
-  /** Path of this tarball inside the bundle. */
-  readonly path: string
-  /** The URL it was downloaded from. */
-  readonly tarball: string
-  /** SRI integrity string as advertised by the source registry, when present. */
-  readonly integrity?: string | undefined
-  /** Legacy sha1, present on older published versions. */
-  readonly shasum?: string | undefined
-  /** Actual size on disk, in bytes. */
-  readonly bytes?: number | undefined
-  /** Human-readable justifications: `root:react@18.2.0`, `prod:scheduler@0.23.0`. */
-  readonly reasons: ReadonlyArray<string>
-}
-
-export interface BundleManifest {
-  readonly manifestVersion: number
-  readonly tool: { readonly name: string; readonly version: string }
-  readonly createdAt: string
-  readonly registry: { readonly kind: string; readonly url: string }
-  /** What the user asked for, verbatim. */
-  readonly requested: ReadonlyArray<string>
-  /** What each request expanded to. */
-  readonly roots: ReadonlyArray<{
-    readonly spec: string
-    readonly versions: ReadonlyArray<string>
-    readonly packageCount: number
-  }>
-  readonly options: {
-    readonly layout: string
-    readonly optionalDependencies: boolean
-    readonly peerDependencies: boolean
-    readonly platforms: string
-    readonly allVersions: boolean
-    readonly includePrerelease: boolean
-    readonly integrityVerified: boolean
-  }
-  readonly packages: ReadonlyArray<ManifestEntry>
-  readonly warnings: ReadonlyArray<string>
-  readonly totals: {
-    readonly packages: number
-    readonly bytes: number
-  }
-}
-
-/** Renders a package's reasons into short, greppable strings. */
-export const formatReasons = (pkg: ResolvedPackage): ReadonlyArray<string> =>
-  pkg.reasons.map((reason) =>
-    reason._tag === "Root" ? `root:${reason.spec}` : `${reason.kind}:${reason.from}`
-  )
-
-/** Builds the manifest for a completed (or dry) run. */
-export const buildManifest = (input: {
-  readonly resolution: Resolution
-  /** Only the packages actually included in *this* archive. */
-  readonly included: ReadonlyArray<ResolvedPackage>
-  readonly options: BundleOptions
-  readonly registry: { readonly kind: string; readonly url: string }
-  readonly toolVersion: string
-  readonly sizes: ReadonlyMap<string, number>
-  readonly createdAt?: Date | undefined
-}): BundleManifest => {
-  const includedNames = new Set(input.included.map((p) => `${p.name}@${p.version}`))
-
-  const packages: ReadonlyArray<ManifestEntry> = input.included.map((pkg) => {
-    const key = `${pkg.name}@${pkg.version}`
-    return {
-      name: pkg.name,
-      version: pkg.version,
-      path: packagePath(pkg.name, pkg.version),
-      tarball: pkg.manifest.dist.tarball,
-      integrity: pkg.manifest.dist.integrity,
-      shasum: pkg.manifest.dist.shasum,
-      bytes: input.sizes.get(key),
-      reasons: formatReasons(pkg)
-    }
-  })
-
-  const totalBytes = packages.reduce((sum, entry) => sum + (entry.bytes ?? 0), 0)
-
-  return {
-    manifestVersion: MANIFEST_VERSION,
-    tool: { name: "packall", version: input.toolVersion },
-    createdAt: (input.createdAt ?? new Date()).toISOString(),
-    registry: input.registry,
-    requested: input.resolution.roots.map((root) => formatSpec(root.spec)),
-    roots: input.resolution.roots.map((root) => ({
-      spec: formatSpec(root.spec),
-      versions: root.versions,
-      packageCount: root.closure.filter((key) => includedNames.has(key)).length
-    })),
-    options: {
-      layout: input.options.layout,
-      optionalDependencies: input.options.scope.optional,
-      peerDependencies: input.options.scope.peer,
-      platforms: formatPlatformFilter(input.options.scope.platforms),
-      allVersions: input.options.allVersions,
-      includePrerelease: input.options.includePrerelease,
-      integrityVerified: input.options.verifyIntegrity
-    },
-    packages,
-    warnings: input.resolution.warnings.map((warning) =>
-      warning.from === undefined ? warning.message : `${warning.from}: ${warning.message}`
-    ),
-    totals: {
-      packages: packages.length,
-      bytes: totalBytes
-    }
-  }
-}
-
-/** Serialises a manifest with stable key order and a trailing newline. */
-export const serializeManifest = (manifest: BundleManifest): string =>
-  `${JSON.stringify(manifest, null, 2)}\n`
+/**
+ * The manifest written into every bundle.
+ *
+ * This is the audit trail. Before anything is imported into a corporate
+ * registry somebody is usually required to answer "what exactly is in here and
+ * where did it come from" — this file answers that without unpacking a single
+ * tarball.
+ */
+import { packagePath } from "./layout.js"
+import type { BundleOptions } from "./options.js"
+import { formatPlatformFilter } from "./platform.js"
+import type { Resolution, ResolvedPackage } from "./resolve.js"
+import { formatSpec } from "./spec.js"
+
+/** Schema version, bumped when the shape changes incompatibly. */
+export const MANIFEST_VERSION = 1
+
+export type ManifestEntry = {
+  readonly name: string
+  readonly version: string
+  /** Path of this tarball inside the bundle. */
+  readonly path: string
+  /** The URL it was downloaded from. */
+  readonly tarball: string
+  /** SRI integrity string as advertised by the source registry, when present. */
+  readonly integrity?: string | undefined
+  /** Legacy sha1, present on older published versions. */
+  readonly shasum?: string | undefined
+  /** Actual size on disk, in bytes. */
+  readonly bytes?: number | undefined
+  /** Human-readable justifications: `root:react@18.2.0`, `prod:scheduler@0.23.0`. */
+  readonly reasons: ReadonlyArray<string>
+}
+
+export type BundleManifest = {
+  readonly manifestVersion: number
+  readonly tool: { readonly name: string; readonly version: string }
+  readonly createdAt: string
+  readonly registry: { readonly kind: string; readonly url: string }
+  /** What the user asked for, verbatim. */
+  readonly requested: ReadonlyArray<string>
+  /** What each request expanded to. */
+  readonly roots: ReadonlyArray<{
+    readonly spec: string
+    readonly versions: ReadonlyArray<string>
+    readonly packageCount: number
+  }>
+  readonly options: {
+    readonly layout: string
+    readonly optionalDependencies: boolean
+    readonly peerDependencies: boolean
+    readonly platforms: string
+    readonly allVersions: boolean
+    readonly includePrerelease: boolean
+    readonly integrityVerified: boolean
+  }
+  readonly packages: ReadonlyArray<ManifestEntry>
+  readonly warnings: ReadonlyArray<string>
+  readonly totals: {
+    readonly packages: number
+    readonly bytes: number
+  }
+}
+
+/** Renders a package's reasons into short, greppable strings. */
+export const formatReasons = (pkg: ResolvedPackage): ReadonlyArray<string> =>
+  pkg.reasons.map((reason) =>
+    reason._tag === "Root" ? `root:${reason.spec}` : `${reason.kind}:${reason.from}`
+  )
+
+/** Builds the manifest for a completed (or dry) run. */
+export const buildManifest = (input: {
+  readonly resolution: Resolution
+  /** Only the packages actually included in *this* archive. */
+  readonly included: ReadonlyArray<ResolvedPackage>
+  readonly options: BundleOptions
+  readonly registry: { readonly kind: string; readonly url: string }
+  readonly toolVersion: string
+  readonly sizes: ReadonlyMap<string, number>
+  readonly createdAt?: Date | undefined
+}): BundleManifest => {
+  const includedNames = new Set(input.included.map((pkg) => `${pkg.name}@${pkg.version}`))
+
+  const packages: ReadonlyArray<ManifestEntry> = input.included.map((pkg) => {
+    const key = `${pkg.name}@${pkg.version}`
+    return {
+      name: pkg.name,
+      version: pkg.version,
+      path: packagePath(pkg.name, pkg.version),
+      tarball: pkg.manifest.dist.tarball,
+      integrity: pkg.manifest.dist.integrity,
+      shasum: pkg.manifest.dist.shasum,
+      bytes: input.sizes.get(key),
+      reasons: formatReasons(pkg)
+    }
+  })
+
+  const totalBytes = packages.reduce((sum, entry) => sum + (entry.bytes ?? 0), 0)
+
+  return {
+    manifestVersion: MANIFEST_VERSION,
+    tool: { name: "packall", version: input.toolVersion },
+    createdAt: (input.createdAt ?? new Date()).toISOString(),
+    registry: input.registry,
+    requested: input.resolution.roots.map((root) => formatSpec(root.spec)),
+    roots: input.resolution.roots.map((root) => ({
+      spec: formatSpec(root.spec),
+      versions: root.versions,
+      packageCount: root.closure.filter((key) => includedNames.has(key)).length
+    })),
+    options: {
+      layout: input.options.layout,
+      optionalDependencies: input.options.scope.optional,
+      peerDependencies: input.options.scope.peer,
+      platforms: formatPlatformFilter(input.options.scope.platforms),
+      allVersions: input.options.allVersions,
+      includePrerelease: input.options.includePrerelease,
+      integrityVerified: input.options.verifyIntegrity
+    },
+    packages,
+    warnings: input.resolution.warnings.map((warning) =>
+      warning.from === undefined ? warning.message : `${warning.from}: ${warning.message}`
+    ),
+    totals: {
+      packages: packages.length,
+      bytes: totalBytes
+    }
+  }
+}
+
+/** Serialises a manifest with stable key order and a trailing newline. */
+export const serializeManifest = (manifest: BundleManifest): string =>
+  `${JSON.stringify(manifest, null, 2)}\n`

package/src/{Options.ts → options.ts}

@@ -5,32 +5,12 @@
  * actually installs offline on a machine that is not the one you built it on.
  * Every switch that makes the bundle smaller is opt-in.
  */
-import type { PlatformFilter } from "./Platform.js"
-import { allPlatforms } from "./Platform.js"
-
-/** How the resulting tarball(s) are shaped. */
-export type 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.
-   */
-  | "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"
-  /**
-   * No archive at all — just the npm-layout directory tree, ready for
-   * `jf rt upload` or rsync.
-   */
-  | "dir"
-
-export const layouts: ReadonlyArray<Layout> = ["per-spec", "single", "dir"]
+import { Layout } from "./enums/layout.js"
+import type { PlatformFilter } from "./platform.js"
+import { allPlatforms } from "./platform.js"
 
 /** Which dependency edges the resolver follows. */
-export interface DependencyScope {
+export type DependencyScope = {
   /**
    * Follow `optionalDependencies`. On by default — this is where per-platform
    * native binaries live, and omitting them is the most common reason an
@@ -53,7 +33,7 @@ export const defaultScope: DependencyScope = {
 }
 
 /** Options governing version selection and the dependency walk. */
-export interface ResolveOptions {
+export type ResolveOptions = {
   readonly scope: DependencyScope
   /**
    * When a root spec is a range, take *every* published version that satisfies
@@ -79,7 +59,7 @@ export const defaultResolveOptions: ResolveOptions = {
 }
 
 /** Options for a full bundle run. */
-export interface BundleOptions extends ResolveOptions {
+export type BundleOptions = ResolveOptions & {
   readonly layout: Layout
   /** Directory the finished artifacts are written to. */
   readonly outDir: string
@@ -116,7 +96,7 @@ export interface BundleOptions extends ResolveOptions {
 
 export const defaultBundleOptions: Omit<BundleOptions, "outDir"> = {
   ...defaultResolveOptions,
-  layout: "per-spec",
+  layout: Layout.PerSpec,
   dryRun: false,
   verifyIntegrity: true,
   force: false

package/src/{Platform.ts → platform.ts}

@@ -15,7 +15,7 @@
  */
 
 /** A target to keep, e.g. `linux-x64`, `linux-x64-musl`, or just `linux`. */
-export interface PlatformTarget {
+export type PlatformTarget = {
   readonly os: string
   /** Undefined means "every architecture for this OS". */
   readonly cpu?: string | undefined
@@ -33,6 +33,13 @@ 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 => ({
@@ -54,7 +61,7 @@ export const currentPlatform = (): PlatformTarget => ({
  * and installs nothing. `--platform windows` silently matching no binding at
  * all would be precisely that, so it is corrected rather than accepted.
  */
-const OS_ALIASES: Readonly<Record<string, string>> = {
+const osByAlias: Readonly<Record<string, string | undefined>> = {
   win: "win32",
   windows: "win32",
   mac: "darwin",
@@ -76,7 +83,7 @@ const KNOWN_OS: ReadonlySet<string> = new Set([
   "win32"
 ])
 
-const LIBC = new Set(["musl", "glibc"])
+const LIBC: ReadonlySet<string> = new Set(["musl", "glibc"])
 
 /**
  * Parses `linux`, `linux-x64`, `darwin-arm64`, `win32-x64`, `linux-x64-musl`,
@@ -91,24 +98,22 @@ const LIBC = 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((p) => p.length > 0)
-  if (parts.length === 0 || 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 rawOs = parts[0]!
-  const os = OS_ALIASES[rawOs] ?? rawOs
+  const os = osByAlias[rawOs] ?? rawOs
   if (!KNOWN_OS.has(os)) return null
 
-  if (parts.length === 1) return { os }
+  if (second === undefined) return { os }
 
   // `linux-musl` is an OS plus a libc, not an OS plus an architecture.
-  if (parts.length === 2 && LIBC.has(parts[1]!)) return { os, libc: parts[1]! }
-
-  const cpu = parts[1]!
-  if (parts.length === 2) return { os, cpu }
+  if (third === undefined) {
+    return LIBC.has(second) ? { os, libc: second } : { os, cpu: second }
+  }
 
-  const libc = parts[2]!
-  if (!LIBC.has(libc)) return null
-  return { os, cpu, libc }
+  if (!LIBC.has(third)) return null
+  return { os, cpu: second, libc: third }
 }
 
 /**
@@ -140,13 +145,6 @@ const listAllows = (list: ReadonlyArray<string> | undefined, value: string): boo
   return hasPositive ? positiveMatched : true
 }
 
-/** Constraints declared by a package, as they appear in its manifest. */
-export interface PlatformConstraints {
-  readonly os?: ReadonlyArray<string> | undefined
-  readonly cpu?: ReadonlyArray<string> | undefined
-  readonly libc?: ReadonlyArray<string> | undefined
-}
-
 /** Would this package install on this specific target? */
 export const matchesTarget = (
   constraints: PlatformConstraints,
@@ -177,6 +175,8 @@ export const isIncluded = (
 export const formatPlatformFilter = (filter: PlatformFilter): string => {
   if (filter._tag === "All") return "all"
   return filter.targets
-    .map((t) => [t.os, t.cpu, t.libc].filter((part) => part !== undefined).join("-"))
+    .map((target) =>
+      [target.os, target.cpu, target.libc].filter((part) => part !== undefined).join("-")
+    )
     .join(",")
 }

package/src/{Progress.ts → progress.ts}

@@ -1,106 +1,106 @@
-/**
- * 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"
-
-/** The phases a bundle run moves through, in order. */
-export type Phase = "preflight" | "resolve" | "download" | "archive" | "done"
-
-/** 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 }
-
-/** The reporting sink. */
-export interface ProgressService {
-  readonly emit: (event: ProgressEvent) => Effect.Effect<void>
-}
-
-/** Service tag for progress reporting. */
-export class Progress extends Context.Service<Progress, ProgressService>()(
-  "@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, ref]` 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
+})