@packall/core 0.0.1 → 0.1.0

package/src/lockfile/detect.ts

@@ -0,0 +1,80 @@
+/**
+ * Working out which lockfile — if any — some content is.
+ *
+ * Detection is by content, matching how `--file` treats everything else: a
+ * lockfile renamed to `deps.txt` still parses, and a `package-lock.json` that
+ * is actually a package.json still gets read as one.
+ */
+import { LockfileFormat } from "../enums/lockfile-format.js"
+import { tryParseJsonc } from "./json.js"
+import { isRecord } from "../utils/is-record.js"
+
+/** What a blob of file content turned out to be. */
+export type LockfileDetection =
+  | { readonly _tag: "Supported"; readonly format: LockfileFormat }
+  /**
+   * Recognisably a lockfile, but not one we can read. Named explicitly so the
+   * error says "yarn.lock is not supported yet" rather than leaving somebody to
+   * work out why their file parsed as a spec list.
+   */
+  | { readonly _tag: "Unsupported"; readonly label: string; readonly hint: string }
+  | { readonly _tag: "NotALockfile" }
+
+/**
+ * Deliberately cheap and total: it never throws, so `--file` can try this
+ * first and fall through to its other shapes when the answer is `NotALockfile`.
+ */
+export const detectLockfile = (content: string): LockfileDetection => {
+  const trimmed = content.trimStart()
+
+  // bun's binary lockfile leads with its own magic string. Worth naming,
+  // because `bun install` wrote this by default until 1.2 and the fix is one
+  // command.
+  if (trimmed.startsWith("bun-lockfile-format-v0")) {
+    return {
+      _tag: "Unsupported",
+      label: "a binary bun lockfile (bun.lockb)",
+      hint: "Run `bun install --save-text-lockfile` to produce a bun.lock, and pass that instead."
+    }
+  }
+
+  if (/^__metadata:/m.test(trimmed) || /^# yarn lockfile v\d/m.test(trimmed)) {
+    return {
+      _tag: "Unsupported",
+      label: "a yarn lockfile",
+      hint: "yarn is not supported yet. Point --file at the package.json instead, or pass --lockfile off."
+    }
+  }
+
+  if (trimmed.startsWith("{")) return detectJsonLockfile(trimmed)
+
+  // pnpm is the only YAML one, and it always declares its version first.
+  if (/^lockfileVersion:/m.test(trimmed) || /^(importers|snapshots):/m.test(trimmed)) {
+    return { _tag: "Supported", format: LockfileFormat.Pnpm }
+  }
+
+  return { _tag: "NotALockfile" }
+}
+
+/**
+ * Separates the two JSON lockfiles from each other and from a package.json.
+ *
+ * Both npm and bun write a numeric `lockfileVersion`, so that field alone
+ * cannot decide it. bun is the one that carries a `workspaces` map keyed by the
+ * empty string; npm keeps the root project under `packages[""]` instead.
+ */
+const detectJsonLockfile = (trimmed: string): LockfileDetection => {
+  const parsed = tryParseJsonc(trimmed)
+  if (!isRecord(parsed)) return { _tag: "NotALockfile" }
+
+  const workspaces = parsed["workspaces"]
+  if (isRecord(workspaces) && Object.hasOwn(workspaces, "")) {
+    return { _tag: "Supported", format: LockfileFormat.Bun }
+  }
+
+  if (typeof parsed["lockfileVersion"] === "number") {
+    return { _tag: "Supported", format: LockfileFormat.Npm }
+  }
+
+  return { _tag: "NotALockfile" }
+}

package/src/lockfile/json.ts

@@ -0,0 +1,132 @@
+/**
+ * Narrowing helpers for the untyped JSON and YAML a lockfile parses into.
+ *
+ * Everything here takes `unknown` and hands back something narrowed, which is
+ * what keeps the parsers free of casts against files nobody controls. The
+ * shape-level narrowing is Effect Schema — the same decoders the registry
+ * response boundary uses — so "tolerated" means one thing across the codebase
+ * rather than being re-decided per parser.
+ */
+import * as Option from "effect/Option"
+import * as Schema from "effect/Schema"
+import { LockfileError } from "../errors.js"
+import { OptionalFlagRecordSchema, StringRecordSchema } from "../schemas/lenient.js"
+import { isRecord } from "../utils/is-record.js"
+
+export const stringOr = (value: unknown, fallback: string): string =>
+  typeof value === "string" ? value : fallback
+
+const decodeStringRecord = Schema.decodeUnknownOption(StringRecordSchema)
+
+/** Keeps only the string-valued members of an untyped object. */
+export const stringRecord = (value: unknown): Readonly<Record<string, string>> =>
+  Option.getOrElse(decodeStringRecord(value), (): Record<string, string> => ({}))
+
+const decodeOptionalFlags = Schema.decodeUnknownOption(OptionalFlagRecordSchema)
+
+/** Names a package marked its peers optional with. */
+export const optionalPeerNames = (value: unknown): ReadonlySet<string> => {
+  const flags = Option.getOrElse(
+    decodeOptionalFlags(value),
+    (): Record<string, { readonly optional: boolean }> => ({})
+  )
+  return new Set(
+    Object.entries(flags).flatMap(([name, meta]) => (meta.optional ? name : []))
+  )
+}
+
+export const parseJsonObject = (path: string, content: string): Record<string, unknown> => {
+  const parsed = tryParseJsonc(content)
+  if (parsed === undefined) {
+    throw new LockfileError(path, "not valid JSON")
+  }
+  if (!isRecord(parsed)) {
+    throw new LockfileError(path, "top level is not an object")
+  }
+  return parsed
+}
+
+/**
+ * Parses JSON, tolerating the comments and trailing commas bun writes.
+ *
+ * `bun.lock` is JSONC by design — bun puts explanatory comments in it — so
+ * plain `JSON.parse` rejects real lockfiles. Returns `undefined` rather than
+ * throwing so detection can use it as a probe.
+ */
+export const tryParseJsonc = (content: string): unknown => {
+  try {
+    return JSON.parse(content)
+  } catch {
+    try {
+      return JSON.parse(stripJsonc(content))
+    } catch {
+      return undefined
+    }
+  }
+}
+
+/**
+ * Removes comments and trailing commas.
+ *
+ * String-aware, because a `//` inside a tarball URL is not a comment and an
+ * escaped quote does not end a string. Both appear in every real lockfile.
+ */
+export const stripJsonc = (content: string): string => {
+  let out = ""
+  let index = 0
+  let inString = false
+
+  while (index < content.length) {
+    const char = content[index]
+
+    if (inString) {
+      out += char
+      if (char === "\\") {
+        out += content[index + 1] ?? ""
+        index += 2
+        continue
+      }
+      if (char === '"') inString = false
+      index += 1
+      continue
+    }
+
+    if (char === '"') {
+      inString = true
+      out += char
+      index += 1
+      continue
+    }
+
+    if (char === "/" && content[index + 1] === "/") {
+      const end = content.indexOf("\n", index)
+      index = end === -1 ? content.length : end
+      continue
+    }
+
+    if (char === "/" && content[index + 1] === "*") {
+      const end = content.indexOf("*/", index + 2)
+      index = end === -1 ? content.length : end + 2
+      continue
+    }
+
+    // A comma is trailing when the next thing that is not whitespace closes the
+    // structure it sits in.
+    if (char === ",") {
+      const next = content.slice(index + 1).search(/\S/)
+      const following = next === -1 ? "" : content[index + 1 + next]
+      if (following === "}" || following === "]") {
+        index += 1
+        continue
+      }
+    }
+
+    out += char
+    index += 1
+  }
+
+  return out
+}
+
+export const describeError = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error)

package/src/lockfile/names.ts

@@ -0,0 +1,20 @@
+import { LockfileFormat } from "../enums/lockfile-format.js"
+
+/**
+ * The file name each supported manager writes, in detection order.
+ *
+ * Ordered: `package-lock.json` before `npm-shrinkwrap.json` before pnpm's and
+ * bun's, so a directory holding several is searched the way npm itself would.
+ */
+export const formatByLockfileName = {
+  "package-lock.json": LockfileFormat.Npm,
+  "npm-shrinkwrap.json": LockfileFormat.Npm,
+  "pnpm-lock.yaml": LockfileFormat.Pnpm,
+  "bun.lock": LockfileFormat.Bun
+} as const satisfies Record<string, LockfileFormat>
+
+/** The names a given manager writes. */
+export const lockfileNamesFor = (format: LockfileFormat): ReadonlyArray<string> =>
+  Object.entries(formatByLockfileName).flatMap(([name, candidate]) =>
+    candidate === format ? name : []
+  )

package/src/lockfile/npm.ts

@@ -0,0 +1,308 @@
+/**
+ * `package-lock.json` / `npm-shrinkwrap.json`.
+ *
+ * npm records *ranges* on its edges and relies on the directory nesting to say
+ * which copy of a package a range resolved to, so the node resolution walk-up —
+ * look beside me, then in my parent, then my grandparent — is reimplemented
+ * here.
+ */
+import { EdgeKind, LockedRootKind } from "../enums/edge-kind.js"
+import { LockfileFormat } from "../enums/lockfile-format.js"
+import { optionalPeerNames, parseJsonObject, stringOr, 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 entry of the v2/v3 `packages` map, after narrowing. */
+type NpmEntry = {
+  readonly path: string
+  readonly version: string
+  /** Set when the install name differs from the real one — an `npm:` alias. */
+  readonly realName: 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 npm's precedence order — the first mention of a name wins. */
+const ROOT_KINDS = [
+  LockedRootKind.Prod,
+  LockedRootKind.Optional,
+  LockedRootKind.Dev,
+  LockedRootKind.Peer
+] as const
+
+/**
+ * The node resolution walk-up, over a flat map of install paths.
+ *
+ * A package at `node_modules/a/node_modules/b` depending on `c` gets, in order,
+ * `node_modules/a/node_modules/b/node_modules/c`, then
+ * `node_modules/a/node_modules/c`, then `node_modules/c`. This is what makes a
+ * range on an edge unambiguous: the nesting already recorded which copy won.
+ */
+const NESTING = "/node_modules/"
+
+export const parseNpmLockfile = (
+  path: string,
+  content: string,
+  importer: string | undefined
+): LockedTree => {
+  const root = parseJsonObject(path, content)
+  const version = String(root["lockfileVersion"] ?? "?")
+  const builder = new TreeBuilder()
+
+  // v2 carries both shapes for backwards compatibility; `packages` is the
+  // accurate one, so it wins whenever it is there.
+  const packages = root["packages"]
+  const entries = isRecord(packages)
+    ? collectEntries(builder, packages)
+    : collectLegacyEntries(builder, root)
+
+  for (const entry of entries.values()) {
+    builder.add({
+      name: entry.realName,
+      version: entry.version,
+      dependencies: edgesOf(builder, entries, entry)
+    })
+  }
+
+  collectRoots(builder, entries, isRecord(packages) ? packages : root, path, importer)
+
+  return builder.finish({ format: LockfileFormat.Npm, lockfileVersion: version, path, importer })
+}
+
+/** Narrows the v2/v3 `packages` map, dropping what cannot be bundled. */
+const collectEntries = (
+  builder: TreeBuilder,
+  packages: Record<string, unknown>
+): Map<string, NpmEntry> => {
+  const entries = new Map<string, NpmEntry>()
+
+  for (const [entryPath, raw] of Object.entries(packages)) {
+    // The root project itself, and workspace members, are not things to fetch.
+    const installName = installNameFromPath(entryPath)
+    if (installName === null) continue
+    if (!isRecord(raw)) continue
+
+    // A symlinked workspace member. Nothing to fetch, but an edge into it has
+    // to be explained rather than counted as a hole in the file.
+    if (raw["link"] === true) {
+      builder.skip(installName, stringOr(raw["resolved"], "link"), "workspace link")
+      continue
+    }
+
+    const rawVersion = raw["version"]
+    if (typeof rawVersion !== "string") {
+      builder.warn(
+        `skipped ${installName} — its lockfile entry records no version, so there is nothing to pin`
+      )
+      continue
+    }
+
+    const resolvedName = typeof raw["name"] === "string" ? raw["name"] : installName
+    const version = asExactVersion(resolvedName, rawVersion)
+    if (version._tag === "Unsupported") {
+      builder.skip(resolvedName, rawVersion, version.reason)
+      continue
+    }
+
+    // `resolved` names a git or tarball URL for anything not from a registry,
+    // even when `version` looks ordinary.
+    const resolvedUrl = raw["resolved"]
+    if (typeof resolvedUrl === "string" && !isRegistryUrl(resolvedUrl)) {
+      builder.skip(resolvedName, resolvedUrl, "not a registry tarball")
+      continue
+    }
+
+    entries.set(entryPath, {
+      path: entryPath,
+      version: version.version,
+      realName: resolvedName,
+      dependencies: stringRecord(raw["dependencies"]),
+      optionalDependencies: stringRecord(raw["optionalDependencies"]),
+      peerDependencies: stringRecord(raw["peerDependencies"]),
+      optionalPeers: optionalPeerNames(raw["peerDependenciesMeta"])
+    })
+  }
+
+  return entries
+}
+
+/**
+ * Flattens a v1 lockfile's nested `dependencies` tree into the same
+ * path-keyed shape v2 uses.
+ *
+ * v1 is old — npm 6 — but it is exactly the vintage still pinned inside a lot
+ * of the locked-down environments this tool exists for, so it is worth the
+ * thirty lines rather than an error telling somebody to upgrade npm.
+ */
+const collectLegacyEntries = (
+  builder: TreeBuilder,
+  root: Record<string, unknown>
+): Map<string, NpmEntry> => {
+  const entries = new Map<string, NpmEntry>()
+
+  const visit = (tree: unknown, prefix: string): void => {
+    if (!isRecord(tree)) return
+    for (const [name, raw] of Object.entries(tree)) {
+      if (!isRecord(raw)) continue
+      const entryPath = prefix === "" ? `node_modules/${name}` : `${prefix}/node_modules/${name}`
+
+      const rawVersion = raw["version"]
+      if (typeof rawVersion === "string") {
+        const version = asExactVersion(name, rawVersion)
+        if (version._tag === "Unsupported") {
+          builder.skip(name, rawVersion, version.reason)
+        } else {
+          entries.set(entryPath, {
+            path: entryPath,
+            version: version.version,
+            realName: name,
+            // v1 calls the edge set `requires`.
+            dependencies: stringRecord(raw["requires"]),
+            optionalDependencies: {},
+            peerDependencies: {},
+            optionalPeers: new Set()
+          })
+        }
+      }
+
+      visit(raw["dependencies"], entryPath)
+    }
+  }
+
+  visit(root["dependencies"], "")
+  return entries
+}
+
+/** Turns one entry's ranges into edges, resolved through the directory nesting. */
+const edgesOf = (
+  builder: TreeBuilder,
+  entries: ReadonlyMap<string, NpmEntry>,
+  entry: NpmEntry
+): ReadonlyArray<LockedEdge> => {
+  const edges: Array<LockedEdge> = []
+
+  const add = (names: ReadonlyArray<string>, kind: EdgeKind): void => {
+    for (const name of names) {
+      const targetPath = resolveNestedEdge(entries, entry.path, name)
+      const target = targetPath === null ? undefined : entries.get(targetPath)
+      if (target === undefined) {
+        // Only required edges are worth raising: an optional or peer edge that
+        // resolves to nothing is how a lockfile records "not installed here",
+        // which npm itself tolerates.
+        if (kind === EdgeKind.Prod) builder.dangling(`${entry.realName}@${entry.version}`, name)
+        continue
+      }
+      edges.push({ name: target.realName, version: target.version, kind })
+    }
+  }
+
+  const optionalNames = Object.keys(entry.optionalDependencies)
+  const optional = new Set(optionalNames)
+
+  // An entry listed in both is optional: that is how npm records "wanted, but
+  // the install may proceed without it".
+  add(Object.keys(entry.dependencies).filter((name) => !optional.has(name)), EdgeKind.Prod)
+  add(optionalNames, EdgeKind.Optional)
+  add(
+    Object.keys(entry.peerDependencies).filter((name) => !entry.optionalPeers.has(name)),
+    EdgeKind.Peer
+  )
+
+  return edges
+}
+
+/**
+ * Reads the root project's direct dependencies.
+ *
+ * The lockfile records these under `packages[""]` for v2/v3. v1 has no such
+ * entry, so every top-level `node_modules/x` is treated as direct — which
+ * over-counts roots slightly on v1 and is the best that file can support.
+ */
+const collectRoots = (
+  builder: TreeBuilder,
+  entries: ReadonlyMap<string, NpmEntry>,
+  source: Record<string, unknown>,
+  path: string,
+  importer: string | undefined
+): void => {
+  // Resolution starts from the member's own directory, so a dependency it
+  // nests privately wins over the hoisted copy — the same rule node applies,
+  // which is why the walk-up is shared with ordinary edges.
+  const collectFrom = (from: string, project: Record<string, unknown>): void => {
+    for (const kind of ROOT_KINDS) {
+      const field = fieldByRootKind[kind]
+      for (const [name, specifier] of Object.entries(stringRecord(project[field]))) {
+        const targetPath = resolveNestedEdge(entries, from, name)
+        const target = targetPath === null ? undefined : entries.get(targetPath)
+        if (target === undefined) continue
+        builder.addRoot({ name: target.realName, version: target.version, kind, specifier })
+      }
+    }
+  }
+
+  if (importer !== undefined) {
+    const key = importerKey(importer)
+    const project = source[key]
+    if (!isRecord(project)) notCovered(path, importer, workspacePaths(source))
+    else collectFrom(key, project)
+    return
+  }
+
+  // No member named: every project the file records contributes, which is what
+  // pointing --file straight at a monorepo's lockfile should mean.
+  const projects = Object.entries(source).flatMap(([key, value]) =>
+    isRecord(value) && !key.includes("node_modules/") ? [[key, value] as const] : []
+  )
+
+  if (projects.length > 0) {
+    for (const [key, project] of projects) collectFrom(key, project)
+    return
+  }
+
+  // v1 records no project entry at all, so every top-level install is direct.
+  for (const entry of entries.values()) {
+    if (entry.path.includes(NESTING)) continue
+    builder.addRoot({ name: entry.realName, version: entry.version, kind: LockedRootKind.Prod })
+  }
+}
+
+/** The workspace paths a v2/v3 lockfile records, for a "does not cover" message. */
+const workspacePaths = (source: Record<string, unknown>): ReadonlyArray<string> =>
+  Object.keys(source).flatMap((key) =>
+    key === "" ? "." : key.includes("node_modules/") ? [] : key
+  )
+
+/**
+ * npm records non-registry sources as a URL in `resolved`. Registry tarballs
+ * are ordinary http(s); anything with a `git+`, `file:` or bare path form is
+ * something we cannot fetch.
+ */
+const isRegistryUrl = (url: string): boolean =>
+  url.startsWith("http://") || url.startsWith("https://")
+
+const resolveNestedEdge = (
+  entries: ReadonlyMap<string, NpmEntry>,
+  fromPath: string,
+  name: string
+): string | null => {
+  let scope = fromPath
+  for (;;) {
+    const candidate = scope === "" ? `node_modules/${name}` : `${scope}${NESTING}${name}`
+    if (entries.has(candidate)) return candidate
+    if (scope === "") return null
+    const at = scope.lastIndexOf(NESTING)
+    scope = at === -1 ? "" : scope.slice(0, at)
+  }
+}
+
+/** `node_modules/@babel/core` -> `@babel/core`; a workspace path -> `null`. */
+const installNameFromPath = (entryPath: string): string | null => {
+  const marker = "node_modules/"
+  const at = entryPath.lastIndexOf(marker)
+  if (at === -1) return null
+  const name = entryPath.slice(at + marker.length)
+  return name.length === 0 ? null : name
+}

package/src/lockfile/parse.ts

@@ -0,0 +1,56 @@
+/**
+ * Lockfile parsing — npm, pnpm and bun.
+ *
+ * `--file package.json` reads *ranges*, and a range resolves to whatever is
+ * newest at the moment the command runs. That is the right answer for "bundle
+ * me something installable" and the wrong one for "bundle exactly what CI
+ * installed" — which is what a lockfile records and what this module reads.
+ *
+ * Three formats, one output shape. Each parser's real job is the same: turn a
+ * manager-specific encoding of "package X at path P depends on Y" into a flat
+ * graph keyed by `name@version`, with every edge already pointing at a concrete
+ * version. Once that is done, nothing downstream has to know which manager
+ * wrote the file.
+ */
+import { LockfileFormat } from "../enums/lockfile-format.js"
+import { LockfileError } from "../errors.js"
+import { parseBunLockfile } from "./bun.js"
+import { detectLockfile } from "./detect.js"
+import { parseNpmLockfile } from "./npm.js"
+import { parsePnpmLockfile } from "./pnpm.js"
+import type { LockedTree, LockfileParseOptions } from "./types.js"
+
+/**
+ * Parses lockfile content into a flat graph.
+ *
+ * Throws `LockfileError`; the caller is expected to be inside an `Effect.try`.
+ */
+export const parseLockfile = (
+  path: string,
+  content: string,
+  format?: LockfileFormat,
+  options: LockfileParseOptions = {}
+): LockedTree => {
+  const resolved = format ?? resolveFormat(path, content)
+  const importer = options.importer
+  switch (resolved) {
+    case LockfileFormat.Npm:
+      return parseNpmLockfile(path, content, importer)
+    case LockfileFormat.Pnpm:
+      return parsePnpmLockfile(path, content, importer)
+    case LockfileFormat.Bun:
+      return parseBunLockfile(path, content, importer)
+  }
+}
+
+const resolveFormat = (path: string, content: string): LockfileFormat => {
+  const detected = detectLockfile(content)
+  if (detected._tag === "Supported") return detected.format
+  if (detected._tag === "Unsupported") {
+    throw new LockfileError(path, `${detected.label} — ${detected.hint}`)
+  }
+  throw new LockfileError(
+    path,
+    "content does not look like a package-lock.json, pnpm-lock.yaml or bun.lock"
+  )
+}