@packall/core 0.0.1 → 0.1.0

package/src/lockfile/pnpm.ts

@@ -0,0 +1,225 @@
+/**
+ * `pnpm-lock.yaml`.
+ *
+ * The easy one: pnpm's snapshots already name exact versions, so there is no
+ * nesting walk-up to reimplement. The fiddly parts are the three package-key
+ * encodings still in the wild and the parenthesised peer-resolution suffix.
+ */
+import semver from "semver"
+import { parse as parseYaml } from "yaml"
+import { parseDependencyTarget } from "../dependency-range.js"
+import { EdgeKind, LockedRootKind } from "../enums/edge-kind.js"
+import { LockfileFormat } from "../enums/lockfile-format.js"
+import { LockfileError } from "../errors.js"
+import { describeError } from "./json.js"
+import { isRecord } from "../utils/is-record.js"
+import { fieldByRootKind, notCovered, TreeBuilder } from "./tree-builder.js"
+import type { LockedEdge, LockedTree } from "./types.js"
+
+/** `name@version`, as a snapshot or importer entry resolves to. */
+type PnpmReference = {
+  readonly name: string
+  readonly version: string
+}
+
+/** pnpm never records peer dependencies against an importer. */
+const ROOT_KINDS = [
+  LockedRootKind.Prod,
+  LockedRootKind.Optional,
+  LockedRootKind.Dev
+] as const
+
+export const parsePnpmLockfile = (
+  path: string,
+  content: string,
+  importer: string | undefined
+): LockedTree => {
+  let root: unknown
+  try {
+    root = parseYaml(content)
+  } catch (error) {
+    throw new LockfileError(path, `not valid YAML — ${describeError(error)}`, { cause: error })
+  }
+  if (!isRecord(root)) {
+    throw new LockfileError(path, "top level is not a mapping")
+  }
+
+  const version = String(root["lockfileVersion"] ?? "?")
+  const builder = new TreeBuilder()
+
+  // v9 split the graph in two: `packages` keeps resolution metadata, and
+  // `snapshots` keeps the edges. Before that both lived in `packages`.
+  const packages = isRecord(root["packages"]) ? root["packages"] : {}
+  const snapshots = isRecord(root["snapshots"]) ? root["snapshots"] : packages
+
+  const known = new Map<string, PnpmReference>()
+  for (const key of Object.keys(packages)) {
+    const parsed = parsePnpmKey(key)
+    if (parsed === null) continue
+    known.set(key, parsed)
+  }
+
+  for (const [key, raw] of Object.entries(snapshots)) {
+    const parsed = parsePnpmKey(key) ?? known.get(key)
+    if (parsed === undefined || parsed === null) {
+      const described = describeKey(key)
+      if (described !== null) builder.skip(described.name, described.spec, described.reason)
+      continue
+    }
+    builder.add({
+      name: parsed.name,
+      version: parsed.version,
+      dependencies: edgesOf(builder, parsed, isRecord(raw) ? raw : {})
+    })
+  }
+
+  collectRoots(builder, root, path, importer)
+
+  return builder.finish({ format: LockfileFormat.Pnpm, lockfileVersion: version, path, importer })
+}
+
+const edgesOf = (
+  builder: TreeBuilder,
+  from: PnpmReference,
+  snapshot: Record<string, unknown>
+): ReadonlyArray<LockedEdge> => {
+  const edges: Array<LockedEdge> = []
+
+  const add = (field: string, kind: EdgeKind): void => {
+    const entries = snapshot[field]
+    if (!isRecord(entries)) return
+    for (const [name, raw] of Object.entries(entries)) {
+      if (typeof raw !== "string") continue
+      const target = parsePnpmReference(name, raw)
+      if (target === null) {
+        if (kind === EdgeKind.Prod) builder.dangling(`${from.name}@${from.version}`, name)
+        continue
+      }
+      edges.push({ ...target, kind })
+    }
+  }
+
+  add(fieldByRootKind[LockedRootKind.Prod], EdgeKind.Prod)
+  add(fieldByRootKind[LockedRootKind.Optional], EdgeKind.Optional)
+  add(fieldByRootKind[LockedRootKind.Peer], EdgeKind.Peer)
+
+  return edges
+}
+
+/**
+ * The importers' direct dependencies become the roots.
+ *
+ * pnpm is the format that makes this easy: `importers` is already keyed by the
+ * path each package.json sits at, so scoping to one member is a lookup rather
+ * than a reconstruction.
+ */
+const collectRoots = (
+  builder: TreeBuilder,
+  root: Record<string, unknown>,
+  path: string,
+  member: string | undefined
+): void => {
+  // A single-project lockfile has no `importers` block; its dependencies sit at
+  // the top level, which is the same thing as an importer called ".".
+  const importers = isRecord(root["importers"]) ? root["importers"] : { ".": root }
+
+  const selected =
+    member === undefined
+      ? Object.values(importers)
+      : Object.hasOwn(importers, member)
+        ? [importers[member]]
+        : notCovered(path, member, Object.keys(importers))
+
+  for (const importer of selected) {
+    if (!isRecord(importer)) continue
+    for (const kind of ROOT_KINDS) {
+      const entries = importer[fieldByRootKind[kind]]
+      if (!isRecord(entries)) continue
+
+      for (const [name, raw] of Object.entries(entries)) {
+        // v5 wrote a bare version string; v6 and v9 write
+        // `{specifier, version}`.
+        const value = typeof raw === "string" ? raw : isRecord(raw) ? raw["version"] : undefined
+        if (typeof value !== "string") continue
+
+        const target = parsePnpmReference(name, value)
+        if (target === null) continue
+
+        const specifier =
+          isRecord(raw) && typeof raw["specifier"] === "string" ? raw["specifier"] : undefined
+        builder.addRoot({ ...target, kind, specifier })
+      }
+    }
+  }
+}
+
+/**
+ * Reads a dependency value from a snapshot or importer.
+ *
+ * The value is either a bare version (`1.4.0`) or a full package key
+ * (`/lodash@4.17.21`, used when the install name is an alias of another
+ * package). Both may carry a peer-resolution suffix in parentheses.
+ */
+const parsePnpmReference = (name: string, raw: string): PnpmReference | null => {
+  const value = stripSuffix(raw)
+
+  const exact = semver.valid(value, { loose: true })
+  if (exact !== null) return { name, version: exact }
+
+  return parsePnpmKey(raw)
+}
+
+/**
+ * Splits a package key into name and version.
+ *
+ * Three encodings across the versions still in the wild:
+ *   v5  `/@babel/core/7.0.0`
+ *   v6  `/@babel/core@7.0.0`
+ *   v9  `@babel/core@7.0.0`
+ *
+ * plus an optional `(peer@1.0.0)` or `(patch_hash=…)` suffix on any of them.
+ */
+export const parsePnpmKey = (key: string): PnpmReference | null => {
+  const body = stripSuffix(key.startsWith("/") ? key.slice(1) : key)
+
+  // A scoped name's own `@` sits at index 0, so only a later one separates the
+  // version. When there is none, this is the v5 form and the last `/` does it.
+  const at = body.lastIndexOf("@")
+  const cut = at > 0 ? at : body.lastIndexOf("/")
+  if (cut <= 0) return null
+
+  const name = body.slice(0, cut)
+  const version = semver.valid(body.slice(cut + 1), { loose: true })
+  if (version === null || name.length === 0) return null
+
+  return { name, version }
+}
+
+/** Describes a key we cannot pin, so the skip warning can say why. */
+const describeKey = (
+  key: string
+): { readonly name: string; readonly spec: string; readonly reason: string } | null => {
+  const body = key.startsWith("/") ? key.slice(1) : key
+  const at = body.lastIndexOf("@")
+  if (at <= 0) return null
+  const name = body.slice(0, at)
+  const spec = body.slice(at + 1)
+  const target = parseDependencyTarget(name, spec)
+  return {
+    name,
+    spec,
+    reason: target._tag === "Unsupported" ? target.reason : "not an exact version"
+  }
+}
+
+/**
+ * Drops the parenthesised peer-resolution suffix.
+ *
+ * pnpm distinguishes the same version installed against different peers —
+ * `react-dom@18.3.1(react@18.3.1)`. Those are the same published tarball, which
+ * is all this tool downloads, so the suffix is noise here.
+ */
+const stripSuffix = (value: string): string => {
+  const open = value.indexOf("(")
+  return open === -1 ? value : value.slice(0, open)
+}

package/src/lockfile/tree-builder.ts

@@ -0,0 +1,166 @@
+/**
+ * The bookkeeping every lockfile parser shares.
+ *
+ * Packages, edges and skip warnings accumulate here while a parser walks a
+ * file, which is what lets each parser stay focused on its own encoding.
+ */
+import semver from "semver"
+import { parseDependencyTarget } from "../dependency-range.js"
+import { LockedRootKind } from "../enums/edge-kind.js"
+import type { LockfileFormat } from "../enums/lockfile-format.js"
+import { LockfileError } from "../errors.js"
+import { packageKey } from "../resolve.js"
+import type { LockedEdge, LockedPackage, LockedRoot, LockedTree } from "./types.js"
+
+/**
+ * Which manifest block each root kind is declared in.
+ *
+ * The block names are the same across npm, pnpm and bun; only which of them a
+ * given format writes differs, which is why each parser supplies its own order
+ * rather than iterating this.
+ */
+export const fieldByRootKind = {
+  [LockedRootKind.Prod]: "dependencies",
+  [LockedRootKind.Optional]: "optionalDependencies",
+  [LockedRootKind.Dev]: "devDependencies",
+  [LockedRootKind.Peer]: "peerDependencies"
+} as const satisfies Record<LockedRootKind, string>
+
+export class TreeBuilder {
+  readonly packages = new Map<string, LockedPackage>()
+  readonly roots: Array<LockedRoot> = []
+  readonly warnings: Array<string> = []
+  readonly incomplete: Array<string> = []
+  /** Names dropped on purpose, so an edge into one is explained, not alarming. */
+  private readonly skipped = new Set<string>()
+  private readonly seenWarnings = new Set<string>()
+
+  add(pkg: LockedPackage): void {
+    const key = packageKey(pkg.name, pkg.version)
+    const existing = this.packages.get(key)
+    if (existing === undefined) {
+      this.packages.set(key, pkg)
+      return
+    }
+    // The same package at the same version can appear at several paths in a
+    // nested layout. They are the same bytes; merge the edge sets so a copy
+    // recorded with fewer dependencies does not lose any.
+    this.packages.set(key, {
+      ...existing,
+      dependencies: mergeEdges(existing.dependencies, pkg.dependencies)
+    })
+  }
+
+  addRoot(root: LockedRoot): void {
+    if (this.roots.some((existing) => existing.name === root.name)) return
+    this.roots.push(root)
+  }
+
+  warn(message: string): void {
+    if (this.seenWarnings.has(message)) return
+    this.seenWarnings.add(message)
+    this.warnings.push(message)
+  }
+
+  /** Notes an entry that is real but cannot come from a registry. */
+  skip(name: string, spec: string, reason: string): void {
+    this.skipped.add(name)
+    this.warn(`skipped ${name}@${spec} (${reason}) — not fetchable from a registry`)
+  }
+
+  /**
+   * Records a required edge that resolved to nothing.
+   *
+   * An edge into something skipped on purpose is expected — you cannot bundle a
+   * `workspace:` sibling from a registry — so it stays a warning. Anything else
+   * means the file does not pin what it claims to.
+   */
+  dangling(from: string, name: string): void {
+    if (this.skipped.has(name)) {
+      this.warn(`${from} requires ${name}, which is not fetchable from a registry`)
+      return
+    }
+    this.incomplete.push(`${name} (required by ${from})`)
+  }
+
+  finish(input: {
+    readonly format: LockfileFormat
+    readonly lockfileVersion: string
+    readonly path: string
+    readonly importer?: string | undefined
+  }): LockedTree {
+    if (this.packages.size === 0) {
+      throw new LockfileError(input.path, "lockfile pins no packages that can be bundled")
+    }
+    return {
+      format: input.format,
+      lockfileVersion: input.lockfileVersion,
+      path: input.path,
+      importer: input.importer,
+      packages: this.packages,
+      roots: this.roots,
+      warnings: this.warnings,
+      incomplete: this.incomplete
+    }
+  }
+}
+
+const mergeEdges = (
+  a: ReadonlyArray<LockedEdge>,
+  b: ReadonlyArray<LockedEdge>
+): ReadonlyArray<LockedEdge> => {
+  const merged = new Map<string, LockedEdge>()
+  for (const edge of [...a, ...b]) {
+    merged.set(`${edge.name}@${edge.version}|${edge.kind}`, edge)
+  }
+  return [...merged.values()]
+}
+
+/**
+ * Reads the right-hand side of a locked entry as an exact version.
+ *
+ * Returns the version when it is one, or the reason it is not — `file:../x`,
+ * `workspace:*`, a git URL. `parseDependencyTarget` already classifies every
+ * one of those for package.json parsing, so the vocabulary of skip reasons
+ * stays identical between the two paths.
+ */
+export const asExactVersion = (
+  name: string,
+  raw: string
+):
+  | { readonly _tag: "Version"; readonly version: string }
+  | { readonly _tag: "Unsupported"; readonly reason: string } => {
+  const exact = semver.valid(raw, { loose: true })
+  if (exact !== null) return { _tag: "Version", version: exact }
+
+  const target = parseDependencyTarget(name, raw)
+  if (target._tag === "Unsupported") return { _tag: "Unsupported", reason: target.reason }
+  return { _tag: "Unsupported", reason: "not an exact version" }
+}
+
+/**
+ * Raised when a lockfile found by walking up turns out not to cover the
+ * package.json that went looking for it.
+ *
+ * Worth distinguishing from "no lockfile at all": the file exists and is
+ * readable, it simply belongs to a different project, and bundling it would
+ * produce someone else's dependency set.
+ */
+export const notCovered = (
+  path: string,
+  importer: string,
+  known: ReadonlyArray<string>
+): never => {
+  const listed = known.slice(0, 8).map((entry) => `    ${entry}`).join("\n")
+  throw new LockfileError(
+    path,
+    `it does not cover ${importer}.\n` +
+      (known.length === 0
+        ? "  It records no workspace members."
+        : `  Workspace members it does record:\n${listed}` +
+          (known.length > 8 ? `\n    … and ${known.length - 8} more` : ""))
+  )
+}
+
+/** `""` is how npm and bun spell the project at the lockfile's own level. */
+export const importerKey = (importer: string): string => (importer === "." ? "" : importer)

package/src/lockfile/types.ts

@@ -0,0 +1,74 @@
+/**
+ * The one output shape every lockfile parser produces.
+ *
+ * npm, pnpm and bun encode "package X at path P depends on Y" in three
+ * different ways; once flattened into this graph, nothing downstream has to
+ * know which manager wrote the file.
+ */
+import type { EdgeKind, LockedRootKind } from "../enums/edge-kind.js"
+import type { LockfileFormat } from "../enums/lockfile-format.js"
+
+/** One edge out of a locked package, already pinned to an exact version. */
+export type LockedEdge = {
+  readonly name: string
+  readonly version: string
+  readonly kind: EdgeKind
+}
+
+/** One package pinned by a lockfile. */
+export type LockedPackage = {
+  readonly name: string
+  readonly version: string
+  readonly dependencies: ReadonlyArray<LockedEdge>
+}
+
+/** A direct dependency of the locked project. */
+export type LockedRoot = {
+  readonly name: string
+  readonly version: string
+  readonly kind: LockedRootKind
+  /** The range the manifest asked for, kept for reporting. */
+  readonly specifier?: string | undefined
+}
+
+/** Options for reading a lockfile. */
+export type LockfileParseOptions = {
+  /**
+   * Which workspace member's dependencies become the roots, as a path relative
+   * to the lockfile in POSIX form — `"packages/core"`, or `"."` for the project
+   * at the lockfile's own level.
+   *
+   * Left undefined, every workspace member in the file contributes, which is
+   * what pointing `--file` straight at a lockfile should mean. It matters when
+   * a package.json found a lockfile by walking *up*: the file then pins the
+   * whole repository, and only one member of it was asked for.
+   */
+  readonly importer?: string | undefined
+}
+
+/** A whole lockfile, flattened. */
+export type LockedTree = {
+  readonly format: LockfileFormat
+  /** As the file declares it: `3`, `'9.0'`, `1`. */
+  readonly lockfileVersion: string
+  /** Where it was read from, for error messages. */
+  readonly path: string
+  /** The workspace member the roots came from, when one was selected. */
+  readonly importer?: string | undefined
+  /** Every pinned package, keyed by `name@version`. */
+  readonly packages: ReadonlyMap<string, LockedPackage>
+  /** The project's direct dependencies. */
+  readonly roots: ReadonlyArray<LockedRoot>
+  /** Entries that were recognised but cannot be fetched from a registry. */
+  readonly warnings: ReadonlyArray<string>
+  /**
+   * Required edges pointing at nothing the file pins.
+   *
+   * Distinct from `warnings`: a `workspace:` dependency that cannot be bundled
+   * is expected and gets a warning, while an ordinary registry dependency with
+   * no entry means the lockfile is genuinely partial and the bundle it produces
+   * would be missing a package. The caller decides what to do about it, but the
+   * two must not be confused.
+   */
+  readonly incomplete: ReadonlyArray<string>
+}