@packall/core 0.0.1 → 0.1.0

package/src/locked-resolve.ts

@@ -0,0 +1,461 @@
+/**
+ * Resolution driven by a lockfile instead of by semver.
+ *
+ * The distinction matters more than it first looks. Feeding a lockfile's
+ * versions in as exact root specs and letting the ordinary walk run would still
+ * produce the wrong bundle: every *transitive* edge is a range, and
+ * `Resolve.walk` answers a range with whatever is newest today. Lock `tslib` at
+ * 2.6.0 and let something depending on `tslib@^2` be re-resolved, and the
+ * bundle grows a second copy at 2.8.1 that CI never installed.
+ *
+ * So the lockfile is treated as the graph, not as a set of hints. The package
+ * set *is* what the file pins, and every edge is satisfied from inside it.
+ * Nothing here calls `selectVersions`; the only thing the registry is asked for
+ * is the metadata that a lockfile does not record — `dist`, and the `os`/`cpu`
+ * constraints that `--platform` narrows on.
+ *
+ * The result is an ordinary `Resolution`, so layout, archiving, the manifest
+ * and the summary cannot tell which path produced it.
+ */
+import * as Effect from "effect/Effect"
+import semver from "semver"
+import type { EdgeKind } from "./enums/edge-kind.js"
+import { LockedRootKind } from "./enums/edge-kind.js"
+import { Phase } from "./enums/phase.js"
+import type { BundlerError } from "./errors.js"
+import { LockfileIncompleteError, LockfileOutOfDateError } from "./errors.js"
+import type { LockedRoot, LockedTree } from "./lockfile/types.js"
+import type { ResolveOptions } from "./options.js"
+import { isIncluded } from "./platform.js"
+import * as Progress from "./progress.js"
+import type { PackageManifest } from "./registry.js"
+import { Registry } from "./registry.js"
+import type {
+    PackageKey,
+    Reason,
+    Resolution,
+    ResolutionWarning,
+    ResolvedPackage,
+    RootResolution
+} from "./resolve.js"
+import { packageKey } from "./resolve.js"
+import type { PackageSpec } from "./spec.js"
+import { formatSpec } from "./spec.js"
+
+/** Options for a lockfile-pinned resolution. */
+export type LockedResolveOptions = ResolveOptions & {
+    /**
+     * Include the project's `devDependencies`.
+     *
+     * Matches `--file package.json`: on by default, because a project without its
+     * dev tooling does not build behind the firewall either.
+     */
+    readonly includeDev: boolean
+    /**
+     * Direct dependency names declared by the accompanying package.json.
+     *
+     * When present, anything declared there but absent from the lockfile's roots
+     * means the two have drifted — which is exactly the silent-mismatch case this
+     * whole feature exists to catch, so it is reported rather than papered over.
+     */
+    readonly declared?: ReadonlyArray<string> | undefined
+}
+
+/** Turns a parsed lockfile into a resolution, pinning every version. */
+export const resolveLocked = (
+    lock: LockedTree,
+    options: LockedResolveOptions
+): Effect.Effect<Resolution, BundlerError, Registry | Progress.Progress> =>
+    Effect.gen(function* () {
+        const roots = selectRoots(lock, options)
+
+        yield* Progress.emit({ _tag: "PhaseStarted", phase: Phase.Resolve, total: roots.length })
+
+        const gap = findGaps(lock, roots, options.declared)
+        if (gap !== null) return yield* Effect.fail(gap)
+
+        // Everything the lockfile can reach, before the platform filter has had a
+        // say. Cheap — no network at all — and it is what decides the fetch list.
+        const reachable = reachableKeys(lock, roots, options)
+        const manifests = yield* fetchManifests(lock, reachable, options)
+
+        const warnings: Array<ResolutionWarning> = lock.warnings.map((message) => ({ message }))
+        const resolved = new Map<PackageKey, ResolvedPackage>()
+        const seenWarnings = new Set<string>()
+
+        const addWarning = (warning: ResolutionWarning): void => {
+            const key = `${warning.from ?? ""}|${warning.message}`
+            if (seenWarnings.has(key)) return
+            seenWarnings.add(key)
+            warnings.push(warning)
+        }
+
+        const rootResolutions: Array<RootResolution> = []
+
+        for (const root of roots) {
+            const key = packageKey(root.name, root.version)
+            if (!manifests.has(key)) continue
+
+            const spec: PackageSpec = {
+                name: root.name,
+                selector: { _tag: "Exact", version: root.version },
+                raw: `${root.name}@${root.version}`
+            }
+
+            // Platform narrowing applies to optional roots for the same reason it
+            // applies to optional edges: a native binding for another OS is exactly
+            // what --platform is there to drop.
+            if (root.kind === LockedRootKind.Optional && !platformAllows(manifests, key, options)) continue
+
+            const closure = walkLocked({
+                lock,
+                manifests,
+                options,
+                seed: key,
+                rootSpec: formatSpec(spec),
+                resolved,
+                addWarning
+            })
+
+            rootResolutions.push({
+                spec,
+                versions: [root.version],
+                closures: new Map([[root.version, closure]]),
+                closure
+            })
+        }
+
+        for (const pkg of resolved.values()) {
+            const deprecated = pkg.manifest.deprecated
+            if (deprecated !== undefined && deprecated !== "") {
+                addWarning({
+                    from: packageKey(pkg.name, pkg.version),
+                    message: `${packageKey(pkg.name, pkg.version)} is deprecated: ${deprecated}`
+                })
+            }
+        }
+
+        yield* Progress.emit({ _tag: "PhaseCompleted", phase: Phase.Resolve })
+
+        return {
+            roots: rootResolutions,
+            packages: [...resolved.values()].toSorted(compareResolved),
+            warnings
+        }
+    })
+
+/* -------------------------------------------------------------------------- */
+/* Roots                                                                      */
+/* -------------------------------------------------------------------------- */
+
+/** Which of the project's direct dependencies this run should bundle. */
+const selectRoots = (
+    lock: LockedTree,
+    options: LockedResolveOptions
+): ReadonlyArray<LockedRoot> =>
+    lock.roots
+        .filter((root) => {
+            if (root.kind === LockedRootKind.Dev) return options.includeDev
+            if (root.kind === LockedRootKind.Optional) return options.scope.optional
+            if (root.kind === LockedRootKind.Peer) return options.scope.peer
+            return true
+        })
+        // Sorted so the artifact order is a property of the dependency set rather
+        // than of which manager wrote the file.
+        .toSorted((a, b) => (a.name === b.name ? 0 : a.name < b.name ? -1 : 1))
+
+/**
+ * The two ways a lockfile can be partial, checked before anything is fetched.
+ *
+ * Both mean the same thing to whoever is waiting on the bundle — a package they
+ * expected will not be in it — and both are invisible unless something says so,
+ * because the run otherwise succeeds and simply produces less.
+ */
+const findGaps = (
+    lock: LockedTree,
+    roots: ReadonlyArray<LockedRoot>,
+    declared: ReadonlyArray<string> | undefined
+): LockfileIncompleteError | null => {
+    const remedy = `Run \`${lock.format} install\` to bring the lockfile up to date.`
+
+    // A dependency added to package.json without re-running the install. The
+    // commonest way the two drift, and the cheapest to detect.
+    //
+    // Checked against everything the file pins rather than against its roots,
+    // because the managers disagree about which blocks appear in the root entry —
+    // pnpm's importers omit peers, npm's `packages[""]` includes them — and a
+    // package that is pinned somewhere will be in the bundle either way.
+    if (declared !== undefined && declared.length > 0) {
+        const locked = new Set<string>()
+        for (const pkg of lock.packages.values()) locked.add(pkg.name)
+        for (const root of roots) locked.add(root.name)
+
+        const missing = declared.filter((name) => !locked.has(name))
+        if (missing.length > 0) {
+            return new LockfileIncompleteError(
+                lock.path,
+                missing,
+                `the package.json declares ${missing.length} ` +
+                `dependenc${missing.length === 1 ? "y" : "ies"} it does not pin`,
+                remedy
+            )
+        }
+    }
+
+    // A required edge inside the file pointing at nothing the file pins.
+    if (lock.incomplete.length > 0) {
+        return new LockfileIncompleteError(
+            lock.path,
+            lock.incomplete,
+            `${lock.incomplete.length} required ` +
+            `dependenc${lock.incomplete.length === 1 ? "y is" : "ies are"} not pinned`,
+            remedy
+        )
+    }
+
+    return null
+}
+
+/* -------------------------------------------------------------------------- */
+/* Reachability                                                               */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Every package the roots can reach through the locked edges.
+ *
+ * Scope filters apply here — `--no-optional` genuinely removes a subtree — but
+ * the platform filter does not, because deciding it needs the `os`/`cpu` fields
+ * that only the registry has.
+ */
+const reachableKeys = (
+    lock: LockedTree,
+    roots: ReadonlyArray<LockedRoot>,
+    options: LockedResolveOptions
+): ReadonlySet<PackageKey> => {
+    const seen = new Set<PackageKey>()
+    const queue = roots.map((root) => packageKey(root.name, root.version))
+
+    while (queue.length > 0) {
+        const key = queue.pop()
+        if (key === undefined || seen.has(key)) continue
+        seen.add(key)
+
+        for (const edge of lock.packages.get(key)?.dependencies ?? []) {
+            if (!followsEdge(edge.kind, options)) continue
+            queue.push(packageKey(edge.name, edge.version))
+        }
+    }
+
+    return seen
+}
+
+const followsEdge = (kind: EdgeKind, options: LockedResolveOptions): boolean => {
+    if (kind === LockedRootKind.Optional) return options.scope.optional
+    if (kind === LockedRootKind.Peer) return options.scope.peer
+    return true
+}
+
+/* -------------------------------------------------------------------------- */
+/* Metadata                                                                   */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Fetches the published manifest for every pinned version.
+ *
+ * One packument per distinct *name*, not per version — a lockfile holding four
+ * versions of `tslib` costs one request. Every pinned version that the registry
+ * does not serve is collected and reported together, because "refresh your
+ * lockfile" is a single action and finding out about the gaps one run at a time
+ * would be miserable.
+ */
+const fetchManifests = (
+    lock: LockedTree,
+    reachable: ReadonlySet<PackageKey>,
+    options: LockedResolveOptions
+): Effect.Effect<
+    ReadonlyMap<PackageKey, PackageManifest>,
+    BundlerError,
+    Registry | Progress.Progress
+> =>
+    Effect.gen(function* () {
+        const registry = yield* Registry
+
+        const wanted = new Map<string, Array<string>>()
+        for (const key of reachable) {
+            const pkg = lock.packages.get(key)
+            if (pkg === undefined) continue
+            const versions = wanted.get(pkg.name)
+            if (versions === undefined) wanted.set(pkg.name, [pkg.version])
+            else versions.push(pkg.version)
+        }
+
+        const manifests = new Map<PackageKey, PackageManifest>()
+        const missing: Array<{ name: string; version: string; detail: string }> = []
+
+        const fetched = yield* Effect.forEach(
+            [...wanted.entries()],
+            ([name, versions]) =>
+                registry.packument(name).pipe(
+                    Effect.map((packument) => ({ name, versions, packument })),
+                    // A package the registry has never heard of is the same problem as a
+                    // version it no longer serves, and belongs in the same report.
+                    Effect.catch((error) =>
+                        error._tag === "PackageNotFoundError"
+                            ? Effect.succeed({ name, versions, packument: null })
+                            : Effect.fail(error)
+                    )
+                ),
+            { concurrency: options.concurrency }
+        )
+
+        for (const { name, versions, packument } of fetched) {
+            for (const version of versions) {
+                if (packument === null) {
+                    missing.push({ name, version, detail: "package not found" })
+                    continue
+                }
+
+                const manifest = packument.versions[version]
+                if (manifest === undefined) {
+                    missing.push({ name, version, detail: describeAvailable(Object.keys(packument.versions)) })
+                    continue
+                }
+
+                manifests.set(packageKey(name, version), manifest)
+                yield* Progress.emit({
+                    _tag: "PackageResolved",
+                    name,
+                    version,
+                    resolvedCount: manifests.size,
+                    pendingCount: reachable.size - manifests.size
+                })
+            }
+        }
+
+        if (missing.length > 0) {
+            return yield* Effect.fail(
+                new LockfileOutOfDateError(lock.path, registry.registryFor(missing[0]?.name ?? ""), missing)
+            )
+        }
+
+        return manifests
+    })
+
+const describeAvailable = (available: ReadonlyArray<string>): string => {
+    const recent = available
+        .toSorted((a, b) =>
+            semver.valid(a) && semver.valid(b) ? semver.compare(a, b) : a.localeCompare(b)
+        )
+        .slice(-3)
+    return recent.length === 0
+        ? "no published versions"
+        : `no longer published (latest: ${recent.join(", ")})`
+}
+
+/* -------------------------------------------------------------------------- */
+/* The walk                                                                   */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Collects one root's closure by following locked edges.
+ *
+ * Pure and synchronous — every manifest is already in hand — so a per-root
+ * closure costs nothing beyond the traversal, which is what makes `per-spec`
+ * layout as cheap here as it is for a range-resolved run.
+ */
+const walkLocked = (input: {
+    readonly lock: LockedTree
+    readonly manifests: ReadonlyMap<PackageKey, PackageManifest>
+    readonly options: LockedResolveOptions
+    readonly seed: PackageKey
+    readonly rootSpec: string
+    readonly resolved: Map<PackageKey, ResolvedPackage>
+    readonly addWarning: (warning: ResolutionWarning) => void
+}): ReadonlyArray<PackageKey> => {
+    const closure = new Set<PackageKey>()
+    const queue: Array<{ key: PackageKey; reason: Reason }> = [
+        { key: input.seed, reason: { _tag: "Root", spec: input.rootSpec } }
+    ]
+
+    while (queue.length > 0) {
+        const next = queue.pop()
+        if (next === undefined) continue
+
+        const manifest = input.manifests.get(next.key)
+        const locked = input.lock.packages.get(next.key)
+        if (manifest === undefined || locked === undefined) continue
+
+        record(input.resolved, next.key, manifest, locked, next.reason)
+
+        if (closure.has(next.key)) continue
+        closure.add(next.key)
+
+        for (const edge of locked.dependencies) {
+            if (!followsEdge(edge.kind, input.options)) continue
+
+            const target = packageKey(edge.name, edge.version)
+            if (!input.manifests.has(target)) continue
+
+            if (edge.kind === LockedRootKind.Optional && !platformAllows(input.manifests, target, input.options)) {
+                input.addWarning({
+                    from: next.key,
+                    message:
+                        `Skipped optional ${target} — it does not build for the selected platforms.`
+                })
+                continue
+            }
+
+            queue.push({ key: target, reason: { _tag: "Edge", from: next.key, kind: edge.kind } })
+        }
+    }
+
+    return [...closure]
+}
+
+/** Adds a package, or merges one more justification into an existing entry. */
+const record = (
+    resolved: Map<PackageKey, ResolvedPackage>,
+    key: PackageKey,
+    manifest: PackageManifest,
+    locked: { readonly name: string; readonly version: string },
+    reason: Reason
+): void => {
+    const existing = resolved.get(key)
+    if (existing === undefined) {
+        resolved.set(key, {
+            name: locked.name,
+            version: locked.version,
+            manifest,
+            reasons: [reason]
+        })
+        return
+    }
+    if (hasReason(existing.reasons, reason)) return
+    resolved.set(key, { ...existing, reasons: [...existing.reasons, reason] })
+}
+
+const hasReason = (reasons: ReadonlyArray<Reason>, candidate: Reason): boolean =>
+    reasons.some((reason) => {
+        if (reason._tag === "Root" && candidate._tag === "Root") return reason.spec === candidate.spec
+        if (reason._tag === "Edge" && candidate._tag === "Edge") {
+            return reason.from === candidate.from && reason.kind === candidate.kind
+        }
+        return false
+    })
+
+const platformAllows = (
+    manifests: ReadonlyMap<PackageKey, PackageManifest>,
+    key: PackageKey,
+    options: LockedResolveOptions
+): boolean => {
+    const manifest = manifests.get(key)
+    if (manifest === undefined) return false
+    return isIncluded(manifest, options.scope.platforms)
+}
+
+const compareResolved = (a: ResolvedPackage, b: ResolvedPackage): number => {
+    if (a.name !== b.name) return a.name < b.name ? -1 : 1
+    return semver.valid(a.version) && semver.valid(b.version)
+        ? semver.compare(a.version, b.version)
+        : a.version.localeCompare(b.version)
+}

package/src/lockfile/bun.ts

@@ -0,0 +1,207 @@
+/**
+ * `bun.lock`.
+ *
+ * Like npm, bun records ranges on its edges and resolves them through the
+ * install-path nesting — but it nests with a plain `/`, and package names
+ * contain `/` too, so the parent of a key can only be found by asking which
+ * prefixes are themselves entries.
+ */
+import { EdgeKind, LockedRootKind } from "../enums/edge-kind.js"
+import { LockfileFormat } from "../enums/lockfile-format.js"
+import { optionalPeerNames, parseJsonObject, stringRecord } from "./json.js"
+import { isRecord } from "../utils/is-record.js"
+import { asExactVersion, fieldByRootKind, importerKey, notCovered, TreeBuilder } from "./tree-builder.js"
+import type { LockedEdge, LockedTree } from "./types.js"
+
+/** One narrowed `packages` entry, keyed by its install path. */
+type BunEntry = {
+  readonly key: string
+  readonly name: string
+  readonly version: string
+  readonly dependencies: Readonly<Record<string, string>>
+  readonly optionalDependencies: Readonly<Record<string, string>>
+  readonly peerDependencies: Readonly<Record<string, string>>
+  readonly optionalPeers: ReadonlySet<string>
+}
+
+/** Root blocks in bun's precedence order — the first mention of a name wins. */
+const ROOT_KINDS = [
+  LockedRootKind.Prod,
+  LockedRootKind.Optional,
+  LockedRootKind.Dev,
+  LockedRootKind.Peer
+] as const
+
+export const parseBunLockfile = (
+  path: string,
+  content: string,
+  importer: string | undefined
+): LockedTree => {
+  const root = parseJsonObject(path, content)
+  const version = String(root["lockfileVersion"] ?? "?")
+  const builder = new TreeBuilder()
+
+  const packages = root["packages"]
+  const entries = isRecord(packages)
+    ? collectEntries(builder, packages)
+    : new Map<string, BunEntry>()
+
+  const keys = new Set(entries.keys())
+  for (const entry of entries.values()) {
+    builder.add({
+      name: entry.name,
+      version: entry.version,
+      dependencies: edgesOf(builder, entries, keys, entry)
+    })
+  }
+
+  collectRoots(builder, entries, keys, root["workspaces"], path, importer)
+
+  return builder.finish({ format: LockfileFormat.Bun, lockfileVersion: version, path, importer })
+}
+
+/**
+ * Narrows bun's tuple entries.
+ *
+ * The value is a positional array whose shape depends on where the package came
+ * from. A registry package is `[id, registry, info, integrity]`; a workspace
+ * member or a git dependency is shorter and its `id` carries the protocol.
+ */
+const collectEntries = (
+  builder: TreeBuilder,
+  packages: Record<string, unknown>
+): Map<string, BunEntry> => {
+  const entries = new Map<string, BunEntry>()
+
+  for (const [key, raw] of Object.entries(packages)) {
+    if (!Array.isArray(raw)) continue
+
+    const [id, , info] = raw
+    if (typeof id !== "string") continue
+
+    const at = id.lastIndexOf("@")
+    if (at <= 0) continue
+    const name = id.slice(0, at)
+    const spec = id.slice(at + 1)
+
+    const version = asExactVersion(name, spec)
+    if (version._tag === "Unsupported") {
+      builder.skip(name, spec, version.reason)
+      continue
+    }
+
+    const details = isRecord(info) ? info : {}
+
+    entries.set(key, {
+      key,
+      name,
+      version: version.version,
+      dependencies: stringRecord(details["dependencies"]),
+      optionalDependencies: stringRecord(details["optionalDependencies"]),
+      peerDependencies: stringRecord(details["peerDependencies"]),
+      optionalPeers: collectOptionalPeers(details)
+    })
+  }
+
+  return entries
+}
+
+/** bun lists optional peers as a name array rather than npm's metadata object. */
+const collectOptionalPeers = (details: Record<string, unknown>): ReadonlySet<string> => {
+  const listed = details["optionalPeers"]
+  const names = Array.isArray(listed)
+    ? listed.flatMap((entry) => (typeof entry === "string" ? entry : []))
+    : []
+  return new Set([...names, ...optionalPeerNames(details["peerDependenciesMeta"])])
+}
+
+const edgesOf = (
+  builder: TreeBuilder,
+  entries: ReadonlyMap<string, BunEntry>,
+  keys: ReadonlySet<string>,
+  entry: BunEntry
+): ReadonlyArray<LockedEdge> => {
+  const edges: Array<LockedEdge> = []
+
+  const add = (names: ReadonlyArray<string>, kind: EdgeKind): void => {
+    for (const name of names) {
+      const target = findEntry(entries, keys, entry.key, name)
+      if (target === undefined) {
+        if (kind === EdgeKind.Prod) builder.dangling(`${entry.name}@${entry.version}`, name)
+        continue
+      }
+      edges.push({ name: target.name, version: target.version, kind })
+    }
+  }
+
+  add(Object.keys(entry.dependencies), EdgeKind.Prod)
+  add(Object.keys(entry.optionalDependencies), EdgeKind.Optional)
+  add(
+    Object.keys(entry.peerDependencies).filter((name) => !entry.optionalPeers.has(name)),
+    EdgeKind.Peer
+  )
+
+  return edges
+}
+
+const collectRoots = (
+  builder: TreeBuilder,
+  entries: ReadonlyMap<string, BunEntry>,
+  keys: ReadonlySet<string>,
+  workspaces: unknown,
+  path: string,
+  member: string | undefined
+): void => {
+  if (!isRecord(workspaces)) return
+
+  const selected =
+    member === undefined
+      ? Object.values(workspaces)
+      : Object.hasOwn(workspaces, importerKey(member))
+        ? [workspaces[importerKey(member)]]
+        : notCovered(path, member, workspacePaths(workspaces))
+
+  for (const workspace of selected) {
+    if (!isRecord(workspace)) continue
+    for (const kind of ROOT_KINDS) {
+      const declared = stringRecord(workspace[fieldByRootKind[kind]])
+      for (const [name, specifier] of Object.entries(declared)) {
+        const target = findEntry(entries, keys, "", name)
+        if (target === undefined) continue
+        builder.addRoot({ name: target.name, version: target.version, kind, specifier })
+      }
+    }
+  }
+}
+
+const workspacePaths = (workspaces: Record<string, unknown>): ReadonlyArray<string> =>
+  Object.keys(workspaces).map((key) => (key === "" ? "." : key))
+
+/**
+ * bun nests with a plain `/`, and package names contain `/` too, so a parent
+ * key cannot be found by string-splitting alone — `@babel/core` would split
+ * into a scope that is not a key. `parentKey` only accepts a prefix that is
+ * itself an entry, which resolves the ambiguity.
+ */
+const findEntry = (
+  entries: ReadonlyMap<string, BunEntry>,
+  keys: ReadonlySet<string>,
+  fromKey: string,
+  name: string
+): BunEntry | undefined => {
+  let scope = fromKey
+  for (;;) {
+    const found = entries.get(scope === "" ? name : `${scope}/${name}`)
+    if (found !== undefined) return found
+    if (scope === "") return undefined
+    scope = parentKey(keys, scope)
+  }
+}
+
+const parentKey = (keys: ReadonlySet<string>, key: string): string => {
+  for (let at = key.lastIndexOf("/"); at > 0; at = key.lastIndexOf("/", at - 1)) {
+    const prefix = key.slice(0, at)
+    if (keys.has(prefix)) return prefix
+  }
+  return ""
+}