@packall/core 0.0.1 → 0.1.0

package/src/{Errors.ts → errors.ts}

@@ -15,6 +15,9 @@
 export type BundlerError =
   | InvalidSpecError
   | InvalidInputFileError
+  | LockfileError
+  | LockfileIncompleteError
+  | LockfileOutOfDateError
   | RegistryUnreachableError
   | PackageNotFoundError
   | VersionNotFoundError
@@ -27,8 +30,8 @@ export type BundlerError =
 
 abstract class BundlerErrorBase extends Error {
   abstract readonly _tag: string
-  constructor(message: string, options?: { cause?: unknown }) {
-    super(message, options as ErrorOptions)
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options)
     this.name = new.target.name
   }
 }
@@ -57,6 +60,85 @@ export class InvalidInputFileError extends BundlerErrorBase {
   }
 }
 
+/** 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
+  }
+}
+
+/**
+ * The lockfile parsed, but does not pin everything the bundle needs.
+ *
+ * Falling back to a range here would defeat the entire point of reading a
+ * lockfile — you would get a bundle that is *mostly* what CI installed, with no
+ * indication of which parts were guessed. So this is fatal, and it names every
+ * 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
+  }
+}
+
+/**
+ * The lockfile pins versions the registry no longer serves.
+ *
+ * Unpublished, or never mirrored into a private registry. Either way the
+ * bundle cannot be built as specified, and quietly substituting a nearby
+ * 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 }))
+  }
+}
+
 /**
  * The registry could not be reached at all — DNS failure, refused connection,
  * proxy blackhole, or a preflight that timed out.
@@ -67,11 +149,11 @@ export class InvalidInputFileError extends BundlerErrorBase {
 export class RegistryUnreachableError extends BundlerErrorBase {
   readonly _tag = "RegistryUnreachableError" as const
   readonly registry: string
-  readonly timeoutMillis: number | undefined
+  readonly timeoutMs: number | undefined
   constructor(
     registry: string,
     detail: string,
-    options?: { cause?: unknown; timeoutMillis?: number }
+    options?: { cause?: unknown; timeoutMs?: number }
   ) {
     super(
       `Cannot reach registry ${registry}: ${detail}.\n` +
@@ -79,7 +161,7 @@ export class RegistryUnreachableError extends BundlerErrorBase {
       options
     )
     this.registry = registry
-    this.timeoutMillis = options?.timeoutMillis
+    this.timeoutMs = options?.timeoutMs
   }
 }
 

package/src/index.ts

@@ -4,41 +4,139 @@
  * Nothing in here knows about npm specifically. Point it at any implementation
  * of the `Registry` service and it will resolve, download, verify and package
  * a dependency closure.
+ *
+ * This is the package's whole public API. Everything not named here is an
+ * implementation detail, including modules that happen to be reachable.
  */
 
-export * as Archive from "./Archive.js"
-export * as Bundle from "./Bundle.js"
-export * as DependencyRange from "./DependencyRange.js"
-export * as Download from "./Download.js"
-export * as Integrity from "./Integrity.js"
-export * as InputFile from "./InputFile.js"
-export * as Layout from "./Layout.js"
-export * as Manifest from "./Manifest.js"
-export * as Options from "./Options.js"
-export * as Platform from "./Platform.js"
-export * as Progress from "./Progress.js"
-export * as Resolve from "./Resolve.js"
-export * as Spec from "./Spec.js"
-
-// Flat re-exports of the things a consumer reaches for constantly.
-export { bundle, bundleResolved, plan, plannedOutputs, summarize, withLayout } from "./Bundle.js"
-export type { BundleArtifact, BundleContext, BundleResult, PlanSummary } from "./Bundle.js"
-export { Registry } from "./Registry.js"
-export type { Packument, PackageDist, PackageManifest, RegistryService } from "./Registry.js"
-export { Progress as ProgressTag } from "./Progress.js"
-export type { ProgressEvent } from "./Progress.js"
-export { resolve } from "./Resolve.js"
-export type { Resolution, ResolvedPackage, RootResolution } from "./Resolve.js"
-export { parseSpec, parseSpecs } from "./Spec.js"
-export type { PackageSpec, Selector } from "./Spec.js"
-export type { BundleOptions, DependencyScope, Layout as LayoutKind, ResolveOptions } from "./Options.js"
+export type * from "./errors.js"
+export {
+  ArchiveError,
+  AuthenticationError,
+  IntegrityError,
+  InvalidInputFileError,
+  InvalidSpecError,
+  LockfileError,
+  LockfileIncompleteError,
+  LockfileOutOfDateError,
+  NoMatchingVersionsError,
+  OutputError,
+  PackageNotFoundError,
+  RegistryResponseError,
+  RegistryUnreachableError,
+  VersionNotFoundError
+} from "./errors.js"
+
+export { ArtifactKind } from "./enums/artifact-kind.js"
+export { DirectOnlyKind, EdgeKind, LockedRootKind } from "./enums/edge-kind.js"
+export { InputFileKind } from "./enums/input-file-kind.js"
+export { Layout, Layouts } from "./enums/layout.js"
+export { LockfileFormat } from "./enums/lockfile-format.js"
+export { Phase } from "./enums/phase.js"
+
+export type { ValueOf } from "./types/value-of.js"
+export { isRecord } from "./utils/is-record.js"
+
+// The tolerant decoders every boundary that reads untrusted JSON is built from
+// — registry responses here, package.json and lockfiles inside the engine.
+export {
+  OptionalFlagRecordOrAbsentSchema,
+  OptionalFlagRecordSchema,
+  OptionalStringArraySchema,
+  OptionalStringRecordSchema,
+  StringArraySchema,
+  StringRecordSchema,
+  tolerant
+} from "./schemas/lenient.js"
+
+export type { PackageSpec, Selector } from "./spec.js"
+export { dedupeSpecs, formatSelector, formatSpec, parseSpec, parseSpecs } from "./spec.js"
+
+export type { DependencyTarget } from "./dependency-range.js"
+export { parseDependencyTarget } from "./dependency-range.js"
+
+export type { PlatformConstraints, PlatformFilter, PlatformTarget } from "./platform.js"
+export {
+  allPlatforms,
+  currentPlatform,
+  formatPlatformFilter,
+  isIncluded,
+  parsePlatformTarget,
+  platformTargets
+} from "./platform.js"
+
+export type { BundleOptions, DependencyScope, ResolveOptions } from "./options.js"
+export { defaultBundleOptions, defaultResolveOptions, defaultScope } from "./options.js"
+
+export type { Packument, PackageDist, PackageManifest } from "./registry.js"
+// `Registry.Service` and `Progress.Service` travel with their class through
+// declaration merging, so the one name carries the tag and its shape.
+export { Registry } from "./registry.js"
+
+export type { ProgressEvent } from "./progress.js"
+// Aliased: `emit` and `layerSilent` say what they do inside `progress.ts`, and
+// nothing at all on a package's public surface.
+export {
+  emit as emitProgress,
+  layerCallback as layerCallbackProgress,
+  layerSilent as layerSilentProgress,
+  makeCollector as makeProgressCollector,
+  Progress
+} from "./progress.js"
+
+export type { IntegrityHash, VerificationResult } from "./integrity.js"
+export { digestOf, hexDigestOf, parseIntegrity, verify as verifyIntegrity } from "./integrity.js"
+
+export {
+  importGuide,
+  MANIFEST_FILE,
+  packagePath,
+  perSpecArchiveName,
+  README_FILE,
+  singleArchiveName,
+  splitName,
+  tarballFileName
+} from "./layout.js"
+
+export type { BundleManifest, ManifestEntry } from "./manifest.js"
+export { buildManifest, MANIFEST_VERSION, serializeManifest } from "./manifest.js"
+
+export type {
+  PackageKey,
+  Reason,
+  Resolution,
+  ResolutionWarning,
+  ResolvedPackage,
+  RootResolution
+} from "./resolve.js"
+export { indexPackages, packageKey, resolve, selectVersions } from "./resolve.js"
+
+export type { LockedResolveOptions } from "./locked-resolve.js"
+export { resolveLocked } from "./locked-resolve.js"
+
+export type { LockfileDetection } from "./lockfile/detect.js"
+export { detectLockfile } from "./lockfile/detect.js"
+export type {
+  LockedEdge,
+  LockedPackage,
+  LockedRoot,
+  LockedTree,
+  LockfileParseOptions
+} from "./lockfile/types.js"
+export { formatByLockfileName, lockfileNamesFor } from "./lockfile/names.js"
+export { parseLockfile } from "./lockfile/parse.js"
+
+export type { InputFileOptions, InputFileResult } from "./input-file.js"
+export { defaultInputFileOptions, parseInputFile, readInputFile } from "./input-file.js"
+
+export type { BundleArtifact, BundleContext, BundleResult, PlannedOutput, PlanSummary } from "./bundle.js"
 export {
-  defaultBundleOptions,
-  defaultResolveOptions,
-  defaultScope,
-  layouts
-} from "./Options.js"
-export type { PlatformFilter, PlatformTarget } from "./Platform.js"
-export { allPlatforms, currentPlatform, parsePlatformTarget, platformTargets } from "./Platform.js"
-
-export * from "./Errors.js"
+  bundle,
+  bundleLocked,
+  bundleResolved,
+  plan,
+  planLocked,
+  plannedOutputs,
+  summarize,
+  withLayout
+} from "./bundle.js"

package/src/{InputFile.ts → input-file.ts}

@@ -1,34 +1,62 @@
 /**
  * `--file` handling.
  *
- * One flag, two accepted shapes, detected from the content rather than the
+ * One flag, three 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 **lockfile** — npm, pnpm or bun; bundle the exact versions it pins
  * - a **newline-delimited list** — one spec per line, `#` and `//` comments
  *   allowed, blank lines ignored
+ *
+ * A lockfile is checked for first, because `package-lock.json` and
+ * `package.json` are both JSON objects and only the content tells them apart.
  */
 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"
+import * as Option from "effect/Option"
+import { parseDependencyTarget } from "./dependency-range.js"
+import { InputFileKind } from "./enums/input-file-kind.js"
+import type { LockfileFormat } from "./enums/lockfile-format.js"
+import type { InvalidSpecError, LockfileError } from "./errors.js"
+import { InvalidInputFileError } from "./errors.js"
+import { detectLockfile } from "./lockfile/detect.js"
+import { parseLockfile } from "./lockfile/parse.js"
+import type { LockedTree } from "./lockfile/types.js"
+import type { PackageJson } from "./schemas/package-json.js"
+import { decodePackageJson } from "./schemas/package-json.js"
+import type { PackageSpec } from "./spec.js"
+import { parseSpecs } from "./spec.js"
 
-export interface InputFileResult {
+export type InputFileResult = {
   readonly kind: InputFileKind
   readonly specs: ReadonlyArray<PackageSpec>
   /** Entries that were recognised but cannot be bundled from a registry. */
   readonly warnings: ReadonlyArray<string>
+  /**
+   * The pinned graph, set only for a lockfile.
+   *
+   * `specs` carries the same roots for display, but a lockfile run must resolve
+   * from this — see `locked-resolve` for why re-resolving the roots' ranges
+   * would quietly produce a different bundle.
+   */
+  readonly lockfile?: LockedTree | undefined
+  /**
+   * Names from the blocks a package.json always installs — `dependencies` and,
+   * unless `--prod`, `devDependencies`.
+   *
+   * Used to check a lockfile against the manifest beside it. Deliberately
+   * excludes optional and peer entries: both are legitimately absent from a
+   * lockfile (an optional dependency that failed to build, a peer the consumer
+   * is expected to supply), so including them would turn a useful staleness
+   * check into a false alarm.
+   */
+  readonly required?: ReadonlyArray<string> | undefined
 }
 
 /** Which dependency blocks of a package.json become root specs. */
-export interface InputFileOptions {
+export type InputFileOptions = {
   /**
    * Include `devDependencies`.
    *
@@ -38,6 +66,13 @@ export interface InputFileOptions {
    * turns it off.
    */
   readonly includeDev: boolean
+  /**
+   * For a lockfile, which workspace member's dependencies are the roots.
+   *
+   * Set when a package.json found its lockfile by walking up: the file then
+   * covers the whole repository, and only one member of it was asked for.
+   */
+  readonly importer?: string | undefined
 }
 
 export const defaultInputFileOptions: InputFileOptions = { includeDev: true }
@@ -46,7 +81,7 @@ export const defaultInputFileOptions: InputFileOptions = { includeDev: true }
 export const readInputFile = (
   filePath: string,
   options: InputFileOptions = defaultInputFileOptions
-): Effect.Effect<InputFileResult, InvalidInputFileError, FileSystem.FileSystem> =>
+): Effect.Effect<InputFileResult, InvalidInputFileError | LockfileError, FileSystem.FileSystem> =>
   Effect.gen(function*() {
     const fs = yield* FileSystem.FileSystem
 
@@ -64,12 +99,17 @@ export const readInputFile = (
     return yield* Effect.try({
       try: () => parseInputFile(filePath, content, options),
       catch: (error) =>
-        error instanceof InvalidInputFileError
+        // A LockfileError already names the file and says what is wrong with
+        // it; wrapping it would only stutter.
+        error instanceof InvalidInputFileError || isLockfileError(error)
           ? error
-          : new InvalidInputFileError(filePath, describe(error), { cause: error })
+          : new InvalidInputFileError(filePath, describeError(error), { cause: error })
     })
   })
 
+const isLockfileError = (error: unknown): error is LockfileError =>
+  error instanceof Error && "_tag" in error && error._tag === "LockfileError"
+
 /**
  * Parses file content that has already been read.
  *
@@ -86,6 +126,17 @@ export const parseInputFile = (
     throw new InvalidInputFileError(filePath, "file is empty")
   }
 
+  // Checked first: a package-lock.json is also a JSON object whose top level
+  // looks a lot like a package.json, and reading one as the other would produce
+  // a bundle with none of the pinning that was asked for.
+  const detected = detectLockfile(trimmed)
+  if (detected._tag === "Unsupported") {
+    throw new InvalidInputFileError(filePath, `${detected.label} — ${detected.hint}`)
+  }
+  if (detected._tag === "Supported") {
+    return fromLockfile(filePath, content, detected.format, options)
+  }
+
   return looksLikeJson(trimmed)
     ? fromPackageJson(filePath, trimmed, options)
     : fromList(filePath, content)
@@ -94,33 +145,47 @@ export const parseInputFile = (
 const looksLikeJson = (trimmed: string): boolean => trimmed.startsWith("{")
 
 /* -------------------------------------------------------------------------- */
-/* package.json                                                               */
+/* Lockfile                                                                   */
 /* -------------------------------------------------------------------------- */
 
-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 fromLockfile = (
+  filePath: string,
+  content: string,
+  format: LockfileFormat,
+  options: InputFileOptions
+): InputFileResult => {
+  const lockfile = parseLockfile(filePath, content, format, { importer: options.importer })
+
+  // The same devDependency rule as a package.json, applied to the pinned roots
+  // so that `specs` shows exactly what the run will bundle.
+  const roots = lockfile.roots.filter((root) => options.includeDev || root.kind !== "dev")
+
+  return {
+    kind: InputFileKind.Lockfile,
+    specs: roots.map((root) => ({
+      name: root.name,
+      selector: { _tag: "Exact", version: root.version },
+      raw: `${root.name}@${root.version}`
+    })),
+    warnings: lockfile.warnings,
+    lockfile
+  }
 }
 
+/* -------------------------------------------------------------------------- */
+/* package.json                                                               */
+/* -------------------------------------------------------------------------- */
+
 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 parsed = parsePackageJson(filePath, content)
 
   const specs: Array<PackageSpec> = []
   const warnings: Array<string> = []
+  const required: Array<string> = []
   const seen = new Set<string>()
 
   const collect = (
@@ -138,6 +203,9 @@ const fromPackageJson = (
         )
         continue
       }
+      // `target.name` rather than the key, so an `npm:` alias is recorded under
+      // the name a lockfile would actually pin it as.
+      if (label === "dependencies" || label === "devDependencies") required.push(target.name)
       const key = `${target.name}|${JSON.stringify(target.selector)}`
       if (seen.has(key)) continue
       seen.add(key)
@@ -166,7 +234,28 @@ const fromPackageJson = (
     )
   }
 
-  return { kind: "package.json", specs, warnings }
+  return { kind: InputFileKind.PackageJson, specs, warnings, required }
+}
+
+/**
+ * Reads a package.json, or gives up on its contents rather than on the run.
+ *
+ * Invalid JSON is an error worth raising — somebody pointed `--file` at a
+ * broken file. A well-formed JSON document this schema cannot recognise is
+ * not: it decodes to no blocks, and the caller reports "declares no
+ * dependencies to bundle", which is both true and more useful.
+ */
+const parsePackageJson = (filePath: string, content: string): PackageJson => {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(content)
+  } catch (error) {
+    throw new InvalidInputFileError(filePath, `not valid JSON — ${describeError(error)}`, {
+      cause: error
+    })
+  }
+
+  return Option.getOrElse(decodePackageJson(parsed), (): PackageJson => ({}))
 }
 
 /* -------------------------------------------------------------------------- */
@@ -174,14 +263,11 @@ const fromPackageJson = (
 /* -------------------------------------------------------------------------- */
 
 const fromList = (filePath: string, content: string): InputFileResult => {
-  const lines: Array<string> = []
   const rawLines = content.split(/\r?\n/)
-
-  for (const line of rawLines) {
+  const lines = rawLines.flatMap((line) => {
     const withoutComment = stripComment(line).trim()
-    if (withoutComment.length === 0) continue
-    lines.push(withoutComment)
-  }
+    return withoutComment.length === 0 ? [] : withoutComment
+  })
 
   if (lines.length === 0) {
     throw new InvalidInputFileError(filePath, "no package specs found (only blank lines and comments)")
@@ -192,7 +278,7 @@ const fromList = (filePath: string, content: string): InputFileResult => {
     throw new InvalidInputFileError(filePath, formatSpecErrors(errors, rawLines))
   }
 
-  return { kind: "list", specs, warnings: [] }
+  return { kind: InputFileKind.List, specs, warnings: [] }
 }
 
 /**
@@ -203,13 +289,10 @@ const fromList = (filePath: string, content: string): InputFileResult => {
  */
 const stripComment = (line: string): string => {
   const hash = line.indexOf("#")
-  let result = hash === -1 ? line : line.slice(0, hash)
+  const 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 = ""
-  }
+  if (slashes === 0) return ""
+  if (slashes > 0 && result[slashes - 1] !== ":") return result.slice(0, slashes)
   return result
 }
 
@@ -225,5 +308,5 @@ const formatSpecErrors = (
   return `${errors.length} invalid spec(s):\n${details.join("\n")}`
 }
 
-const describe = (error: unknown): string =>
+const describeError = (error: unknown): string =>
   error instanceof Error ? error.message : String(error)