@packall/core 0.0.1 → 0.2.0

package/src/Download.ts

@@ -1,132 +0,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 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)
-    }
-  })

package/src/Errors.ts

@@ -1,216 +0,0 @@
-/**
- * Failure types for the bundler.
- *
- * These are deliberately plain classes carrying a literal `_tag` rather than
- * `Data.TaggedError`. They work with `Effect.catchTag` / `Effect.catchTags`
- * exactly the same way, and they keep the public error surface independent of
- * any single Effect release — useful while Effect v4 is still in beta.
- *
- * Every error carries enough context to be actionable without a stack trace,
- * because the primary consumer is somebody staring at a terminal on a
- * locked-down network trying to work out why a download did not happen.
- */
-
-/** Discriminant union of every failure the bundler can produce. */
-export type BundlerError =
-  | InvalidSpecError
-  | InvalidInputFileError
-  | RegistryUnreachableError
-  | PackageNotFoundError
-  | VersionNotFoundError
-  | NoMatchingVersionsError
-  | RegistryResponseError
-  | AuthenticationError
-  | IntegrityError
-  | ArchiveError
-  | OutputError
-
-abstract class BundlerErrorBase extends Error {
-  abstract readonly _tag: string
-  constructor(message: string, options?: { cause?: unknown }) {
-    super(message, options as ErrorOptions)
-    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
-  }
-}
-
-/** `--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
-  }
-}
-
-/**
- * The registry could not be reached at all — DNS failure, refused connection,
- * 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 timeoutMillis: number | undefined
-  constructor(
-    registry: string,
-    detail: string,
-    options?: { cause?: unknown; timeoutMillis?: 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.timeoutMillis = options?.timeoutMillis
-  }
-}
-
-/** 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
-  }
-}
-
-/** 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
-  }
-}
-
-/** 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
-  }
-}
-
-/** 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
-  }
-}
-
-/** 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
-  }
-}
-
-/**
- * A downloaded tarball did not match the checksum the registry advertised.
- *
- * Never soft-fail this: a bundle is a supply-chain artifact and a corrupt or
- * 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
-  }
-}
-
-/** 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
-  }
-}
-
-/** 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
-  }
-}
-
-const safeHost = (registry: string): string => {
-  try {
-    const url = new URL(registry)
-    return url.host + url.pathname.replace(/\/+$/, "")
-  } catch {
-    return registry
-  }
-}

package/src/InputFile.ts

@@ -1,229 +0,0 @@
-/**
- * `--file` handling.
- *
- * One flag, two accepted shapes, detected from the content rather than the
- * extension so that `--file deps.json` and `--file my-packages` both do the
- * obvious thing:
- *
- * - a **package.json** — bundle everything it depends on
- * - a **newline-delimited list** — one spec per line, `#` and `//` comments
- *   allowed, blank lines ignored
- */
-import * as Effect from "effect/Effect"
-import * as FileSystem from "effect/FileSystem"
-import { parseDependencyTarget } from "./DependencyRange.js"
-import { InvalidInputFileError } from "./Errors.js"
-import type { InvalidSpecError } from "./Errors.js"
-import type { PackageSpec } from "./Spec.js"
-import { parseSpecs } from "./Spec.js"
-
-/** Which of the two shapes a file turned out to be. */
-export type InputFileKind = "package.json" | "list"
-
-export interface InputFileResult {
-  readonly kind: InputFileKind
-  readonly specs: ReadonlyArray<PackageSpec>
-  /** Entries that were recognised but cannot be bundled from a registry. */
-  readonly warnings: ReadonlyArray<string>
-}
-
-/** Which dependency blocks of a package.json become root specs. */
-export interface InputFileOptions {
-  /**
-   * Include `devDependencies`.
-   *
-   * On by default: if you are pointing this tool at a package.json, you are
-   * almost certainly trying to make that project installable behind the
-   * firewall, and a project without its dev tooling does not build. `--prod`
-   * turns it off.
-   */
-  readonly includeDev: boolean
-}
-
-export const defaultInputFileOptions: InputFileOptions = { includeDev: true }
-
-/** Reads and parses an input file. */
-export const readInputFile = (
-  filePath: string,
-  options: InputFileOptions = defaultInputFileOptions
-): Effect.Effect<InputFileResult, InvalidInputFileError, FileSystem.FileSystem> =>
-  Effect.gen(function*() {
-    const fs = yield* FileSystem.FileSystem
-
-    const exists = yield* fs.exists(filePath).pipe(
-      Effect.mapError((cause) => new InvalidInputFileError(filePath, "could not be read", { cause }))
-    )
-    if (!exists) {
-      return yield* Effect.fail(new InvalidInputFileError(filePath, "file does not exist"))
-    }
-
-    const content = yield* fs.readFileString(filePath).pipe(
-      Effect.mapError((cause) => new InvalidInputFileError(filePath, "could not be read", { cause }))
-    )
-
-    return yield* Effect.try({
-      try: () => parseInputFile(filePath, content, options),
-      catch: (error) =>
-        error instanceof InvalidInputFileError
-          ? error
-          : new InvalidInputFileError(filePath, describe(error), { cause: error })
-    })
-  })
-
-/**
- * Parses file content that has already been read.
- *
- * Split out from the IO so the whole of this logic is testable with plain
- * strings and no file system at all.
- */
-export const parseInputFile = (
-  filePath: string,
-  content: string,
-  options: InputFileOptions = defaultInputFileOptions
-): InputFileResult => {
-  const trimmed = content.trim()
-  if (trimmed.length === 0) {
-    throw new InvalidInputFileError(filePath, "file is empty")
-  }
-
-  return looksLikeJson(trimmed)
-    ? fromPackageJson(filePath, trimmed, options)
-    : fromList(filePath, content)
-}
-
-const looksLikeJson = (trimmed: string): boolean => trimmed.startsWith("{")
-
-/* -------------------------------------------------------------------------- */
-/* package.json                                                               */
-/* -------------------------------------------------------------------------- */
-
-interface PackageJsonShape {
-  readonly dependencies?: Record<string, string>
-  readonly devDependencies?: Record<string, string>
-  readonly optionalDependencies?: Record<string, string>
-  readonly peerDependencies?: Record<string, string>
-  readonly peerDependenciesMeta?: Record<string, { optional?: boolean }>
-}
-
-const fromPackageJson = (
-  filePath: string,
-  content: string,
-  options: InputFileOptions
-): InputFileResult => {
-  let parsed: PackageJsonShape
-  try {
-    parsed = JSON.parse(content) as PackageJsonShape
-  } catch (error) {
-    throw new InvalidInputFileError(filePath, `not valid JSON — ${describe(error)}`, {
-      cause: error
-    })
-  }
-
-  const specs: Array<PackageSpec> = []
-  const warnings: Array<string> = []
-  const seen = new Set<string>()
-
-  const collect = (
-    entries: Record<string, string> | undefined,
-    label: string,
-    skip?: (name: string) => boolean
-  ): void => {
-    if (entries === undefined) return
-    for (const [name, raw] of Object.entries(entries)) {
-      if (skip?.(name)) continue
-      const target = parseDependencyTarget(name, raw)
-      if (target._tag === "Unsupported") {
-        warnings.push(
-          `${label}: skipped ${name}@${target.raw} (${target.reason}) — not fetchable from a registry`
-        )
-        continue
-      }
-      const key = `${target.name}|${JSON.stringify(target.selector)}`
-      if (seen.has(key)) continue
-      seen.add(key)
-      specs.push({
-        name: target.name,
-        selector: target.selector,
-        raw: `${target.name}@${raw}`
-      })
-    }
-  }
-
-  collect(parsed.dependencies, "dependencies")
-  collect(parsed.optionalDependencies, "optionalDependencies")
-  if (options.includeDev) {
-    collect(parsed.devDependencies, "devDependencies")
-  }
-  const meta = parsed.peerDependenciesMeta ?? {}
-  collect(parsed.peerDependencies, "peerDependencies", (name) => meta[name]?.optional === true)
-
-  if (specs.length === 0) {
-    throw new InvalidInputFileError(
-      filePath,
-      options.includeDev
-        ? "package.json declares no dependencies to bundle"
-        : "package.json declares no non-dev dependencies to bundle (drop --prod to include devDependencies)"
-    )
-  }
-
-  return { kind: "package.json", specs, warnings }
-}
-
-/* -------------------------------------------------------------------------- */
-/* Spec list                                                                  */
-/* -------------------------------------------------------------------------- */
-
-const fromList = (filePath: string, content: string): InputFileResult => {
-  const lines: Array<string> = []
-  const rawLines = content.split(/\r?\n/)
-
-  for (const line of rawLines) {
-    const withoutComment = stripComment(line).trim()
-    if (withoutComment.length === 0) continue
-    lines.push(withoutComment)
-  }
-
-  if (lines.length === 0) {
-    throw new InvalidInputFileError(filePath, "no package specs found (only blank lines and comments)")
-  }
-
-  const { specs, errors } = parseSpecs(lines)
-  if (errors.length > 0) {
-    throw new InvalidInputFileError(filePath, formatSpecErrors(errors, rawLines))
-  }
-
-  return { kind: "list", specs, warnings: [] }
-}
-
-/**
- * Strips `#` and `//` comments.
- *
- * `//` only counts when it is not part of a URL, so a future line containing
- * `https://…` does not get silently truncated.
- */
-const stripComment = (line: string): string => {
-  const hash = line.indexOf("#")
-  let result = hash === -1 ? line : line.slice(0, hash)
-  const slashes = result.indexOf("//")
-  if (slashes > 0 && result[slashes - 1] !== ":") {
-    result = result.slice(0, slashes)
-  } else if (slashes === 0) {
-    result = ""
-  }
-  return result
-}
-
-const formatSpecErrors = (
-  errors: ReadonlyArray<InvalidSpecError>,
-  rawLines: ReadonlyArray<string>
-): string => {
-  const details = errors.map((error) => {
-    const index = rawLines.findIndex((line) => stripComment(line).trim() === error.spec)
-    const where = index === -1 ? "" : ` (line ${index + 1})`
-    return `    ${error.spec}${where}: ${error.reason}`
-  })
-  return `${errors.length} invalid spec(s):\n${details.join("\n")}`
-}
-
-const describe = (error: unknown): string =>
-  error instanceof Error ? error.message : String(error)

package/src/Integrity.ts

@@ -1,122 +0,0 @@
-/**
- * Checksum verification for downloaded tarballs.
- *
- * A bundle is a supply-chain artifact that gets imported wholesale into a
- * corporate registry, so "the bytes I got are the bytes the registry promised"
- * is the one property worth being strict about. A failed check discards the
- * download rather than warning and carrying on.
- *
- * Implemented directly against `node:crypto` rather than pulling in `ssri`,
- * because the subset of Subresource Integrity that npm actually publishes is
- * small and entirely mechanical.
- */
-import { createHash, timingSafeEqual } from "node:crypto"
-
-/** One parsed SRI hash. */
-export interface IntegrityHash {
-  readonly algorithm: string
-  /** Base64 digest, exactly as written in the SRI string. */
-  readonly digest: string
-}
-
-const SUPPORTED = new Set(["sha512", "sha384", "sha256", "sha1"])
-
-/**
- * Parses an SRI string such as `sha512-abc...==`.
- *
- * npm permits several space-separated hashes; we keep every one we can verify
- * and ignore algorithms Node does not implement.
- */
-export const parseIntegrity = (integrity: string): ReadonlyArray<IntegrityHash> => {
-  const hashes: Array<IntegrityHash> = []
-  for (const token of integrity.trim().split(/\s+/)) {
-    if (token.length === 0) continue
-    const dash = token.indexOf("-")
-    if (dash <= 0) continue
-    const algorithm = token.slice(0, dash).toLowerCase()
-    const digest = token.slice(dash + 1)
-    if (!SUPPORTED.has(algorithm) || digest.length === 0) continue
-    hashes.push({ algorithm, digest })
-  }
-  return hashes
-}
-
-/** Computes the base64 digest of some bytes under one algorithm. */
-export const digestOf = (data: Uint8Array, algorithm: string): string =>
-  createHash(algorithm).update(data).digest("base64")
-
-/** Computes the hex digest of some bytes — the form legacy `shasum` uses. */
-export const hexDigestOf = (data: Uint8Array, algorithm: string): string =>
-  createHash(algorithm).update(data).digest("hex")
-
-/** Result of checking a download. */
-export type VerificationResult =
-  /** Verified against at least one checksum. */
-  | { readonly _tag: "Verified"; readonly using: string }
-  /** The registry advertised no checksum we could use. */
-  | { readonly _tag: "Unverifiable"; readonly reason: string }
-  /** A checksum was present and did not match. */
-  | { readonly _tag: "Mismatch"; readonly expected: string; readonly actual: string }
-
-/** Constant-time comparison of two digest strings of equal length. */
-const digestsEqual = (a: string, b: string): boolean => {
-  const left = Buffer.from(a)
-  const right = Buffer.from(b)
-  // `timingSafeEqual` throws on unequal lengths, which is itself a mismatch.
-  return left.length === right.length && timingSafeEqual(left, right)
-}
-
-/**
- * Checks bytes against whichever checksums the registry supplied.
- *
- * SRI is preferred; `shasum` is the fallback for versions published before
- * integrity strings existed. If the registry gave us neither, that is reported
- * as `Unverifiable` rather than silently treated as a pass — the caller decides
- * whether to tolerate it.
- */
-export const verify = (
-  data: Uint8Array,
-  dist: { readonly integrity?: string | undefined; readonly shasum?: string | undefined }
-): VerificationResult => {
-  if (dist.integrity !== undefined && dist.integrity.length > 0) {
-    const hashes = parseIntegrity(dist.integrity)
-    if (hashes.length === 0) {
-      return { _tag: "Unverifiable", reason: `no supported algorithm in "${dist.integrity}"` }
-    }
-    // Strongest first, so a mismatch is reported against the best hash present.
-    const ordered = [...hashes].sort(
-      (a, b) => strength(b.algorithm) - strength(a.algorithm)
-    )
-    const best = ordered[0]!
-    const actual = digestOf(data, best.algorithm)
-    return digestsEqual(actual, best.digest)
-      ? { _tag: "Verified", using: best.algorithm }
-      : {
-          _tag: "Mismatch",
-          expected: `${best.algorithm}-${best.digest}`,
-          actual: `${best.algorithm}-${actual}`
-        }
-  }
-
-  if (dist.shasum !== undefined && dist.shasum.length > 0) {
-    const actual = hexDigestOf(data, "sha1")
-    return digestsEqual(actual.toLowerCase(), dist.shasum.toLowerCase())
-      ? { _tag: "Verified", using: "sha1" }
-      : { _tag: "Mismatch", expected: `sha1-${dist.shasum}`, actual: `sha1-${actual}` }
-  }
-
-  return { _tag: "Unverifiable", reason: "registry advertised no integrity or shasum" }
-}
-
-const strength = (algorithm: string): number => {
-  switch (algorithm) {
-    case "sha512":
-      return 4
-    case "sha384":
-      return 3
-    case "sha256":
-      return 2
-    default:
-      return 1
-  }
-}