@vzn/vx-lockfile 0.0.0 → 0.0.485

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vx contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,52 @@
+# @vzn/vx-lockfile
+
+Lockfile plugins for [`@vzn/vx`](https://github.com/vznjs/vx): `pnpm()`, `bun()`, `npm()` and `yarn()`. Each keys every task on its **own project's resolved dependency closure** from the package manager's lockfile, not on the whole file. `pnpm update foo` (or `bun add`, `npm install`, `yarn up`) re-keys exactly the projects that reach `foo` — through their dependencies, transitively, and through workspace links — and `vx run … --affected` selects the same projects. Zero dependencies: Bun's own YAML and JSONC parsers, and a classic-yarn reader.
+
+Without a plugin, core folds the whole lockfile into the workspace fingerprint that every cache key sees, so one install invalidates every task in the workspace.
+
+## Usage
+
+```sh
+npm install -D @vzn/vx @vzn/vx-lockfile   # or: pnpm add -D -w · yarn add -D (-W on Yarn 1) · bun add -d
+```
+
+```ts
+// vx.workspace.ts
+import { defineWorkspace } from '@vzn/vx/config'
+import { pnpm } from '@vzn/vx-lockfile' // or bun, npm, yarn
+
+export default defineWorkspace({
+  plugins: [pnpm()],
+})
+```
+
+That is the whole setup. The plugin **claims** its lockfile (`VxPlugin.fingerprint`), so core leaves it out of the workspace fingerprint, and its `key` hook folds one digest per project. `vx why <task>` names the material as `plugin @vzn/vx-lockfile/pnpm` (or `/bun`, `/npm`, `/yarn`).
+
+| Option  | Values                               | Meaning                                                                                                                                                                                        |
+| ------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `scope` | `'project'` (default), `'workspace'` | `project`: each task folds its own project's closure. `workspace`: the whole file, as core folds it — the coarse key through the plugin, for a workspace not yet ready to trust the precision. |
+
+## What a project's digest covers
+
+Every package the project can reach, by resolved identity (name, version, integrity), and under bun and npm by the name it installs under, not where it sits, so a re-hoist of one version re-keys nothing, plus the install-wide material every project folds — and **the root package's own closure**. The root's `dependencies` and `devDependencies` reach every task: their bins run from the root `node_modules/.bin`, which vx puts on every task's PATH, and Node's resolution walks up to the root `node_modules` (`@types/*`, a plugin a root tool's config names). So a root devDependency bump (`pnpm add -Dw oxlint@next`) re-keys every project and `--affected` selects every project; a package only project A reaches still moves only A. A root `workspace:` dependency folds that package's closure into every project too. Per manager:
+
+- **pnpm** (`pnpm-lock.yaml`, lockfile v5, v6, v9): importers → snapshots, transitively; each package by name, version **and resolved peers** (`foo@1(react@18)` is not `foo@1(react@19)`), resolution and any `patchedDependencies` entry; `link:` folds the linked importer's reach, and a `file:` directory dependency folds its own closure (v9 keys it `name@file:…`, v5/v6 by the bare `file:…`); every other top-level field but `overrides` and the catalogs, whose effect is the snapshot an importer reaches (`settings`, `packageExtensionsChecksum`, `pnpmfileChecksum`, `ignoredOptionalDependencies`, v6's `onlyBuiltDependencies`, and any field pnpm adds later) and the lockfile version into every project. A multi-document lockfile (pnpm 10.x and 11 write the env lockfile — `configDependencies`, the package manager's own install — ahead of the project's) reads its last document as the lockfile and folds the ones before it into every project.
+- **bun** (`bun.lock`): Bun's hoisted layout — a dependency `d` of the package at path `p` is `p/d` when that key exists, else the nearest ancestor's, else the root's, so a nested version counts for the package it is nested under and no other; `workspace:` entries fold the linked package's reach; each `patchedDependencies` entry and the CONTENT of its patch file (bun.lock records only its path) with the package it patches, so a patch edit re-keys only the projects reaching it; every top-level field but `workspaces`, `packages`, the catalogs, `overrides` and `patchedDependencies` (`trustedDependencies`, and any field Bun adds later), and any patch naming no entry, into every project — a catalog bump reaches only the projects whose `catalog:` dependency resolves anew, through the `packages` entry it installs.
+- **npm** (`package-lock.json`, lockfileVersion 2 and 3): the `packages` map — `p/node_modules/d`, then each ancestor directory's (a workspace nested in another's directory resolves through the outer one's `node_modules`, as Node does), then `node_modules/d`; a `link: true` entry folds its target workspace's reach; root `overrides` reach a project through the entries they force (npm 10 does not write them to the lockfile). Version 1 (npm 6) has no `packages` map and is refused.
+- **yarn** (`yarn.lock`): berry (yarn 2+) resolves `name@npm:range` descriptors to entries, workspaces included, each entry folding every field but its dependency lists (so the root workspace's `dependenciesMeta` reaches every project), `__metadata`'s `version` and `cacheKey` into every project. A Yarn 4 catalog dependency (`catalog:`, `catalog:<name>`) is recorded as that literal and its range lives in `.yarnrc.yml`, so it reaches every entry of its package: a bump of any of them re-keys the workspace. So does a descriptor the file does not key: a root `resolutions` override (to a `patch:`, or another range) leaves the original descriptor out of `yarn.lock`, and the entry installed in its place is reached through the package's name, so a patch edit re-keys the workspaces that depend on it. A path range (`portal:`, `file:`, `link:`) reaches the entry keyed bound to the package naming it (`::locator=…`), not another workspace's of the same name. Yarn's builtin compat patches (`resolve`, `typescript`, `fsevents`) are reached too: the workspace asks for the plain descriptor, and the patched entry is the one Yarn installs. `.yarnrc.yml` itself is in core's workspace fingerprint, so a catalog edit re-keys every project, as a `pnpm-workspace.yaml` edit does. Classic (yarn 1) records no workspaces, so it yields one digest for the root that every project folds — coarse, and honest about what the file records.
+
+A project the lockfile has no entry for folds the root's digest alone — the only `node_modules` it can resolve from. A phantom dependency (imported, never declared by the project or the root — a sibling's package hoisted to the root) is not in any closure; declare it.
+
+A lockfile the parser cannot read **refuses the run**, naming the file, the reason and the install that regenerates it. That is deliberate: the alternative to reading the lockfile is keying on nothing, and a key that is missing material is a stale hit waiting to happen. Under `--affected` the refusal also says which side could not be read — the working tree's copy, or the one at the base ref (a lockfile-migration commit hits the second). A lockfile holding git merge conflict markers is refused the same way: it names two installs at once, and yarn classic's format parsed one side of it without a word.
+
+## Cost
+
+The claim, the per-project key, the memo and the `--affected` diff are core's `lockfileClaim`; this package is the parsers, and they are internal: it exports `pnpm`, `bun`, `npm`, `yarn` and `LockfileOptions`. A lockfile is parsed **once per content**: the digests are memoised under the cache dir (`lockfile-claims/<file>.json`) by the file's xxh3, so a warm run pays one read, one hash and one small JSON read — never a parse — and the read happens once per run, not per task. The digest is one hash per strongly connected component of the dependency graph (lockfiles carry cycles), children first, so a 1000-importer / 3000-package lockfile digests in ~20 ms when it does change.
+
+## `--affected`
+
+`vx run test --affected=origin/main` after a lockfile change used to select every project. With a plugin declared at `scope: 'project'`, core hands it the lockfile at the base ref and in the working tree; it digests both and names the projects whose digest moved. At `scope: 'workspace'` a change still selects every project. A lockfile that appeared or was deleted still selects everything — every project's `node_modules` is in question.
+
+## Testing
+
+`bun test` covers each parser's digests (transitive bumps, nested versions, workspace links, peer suffixes, patches, install-wide knobs, cycles, key order, aliases, refusals) and `vx run` / `vx why` / `--affected` end to end. vx's own repository declares `bun()`.

package/index.ts

@@ -0,0 +1,4 @@
+// Root entry shim: Bun 1.4.0's `--compile` binaries resolve an on-disk
+// package by `<pkg>/index.ts` and ignore package.json `exports` / `main`
+// (see packages/vx/index.ts). Same module as the exports map names.
+export * from './src/index.js'

package/package.json

@@ -1,13 +1,47 @@
 {
   "name": "@vzn/vx-lockfile",
-  "version": "0.0.0",
-  "description": "Placeholder; real releases are published by CI.",
+  "version": "0.0.485",
   "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/vznjs/vx.git"
+  "description": "Lockfile plugins for vx — pnpm(), bun(), npm(), yarn(): each keys every task on its project's own resolved dependency closure from the package manager's lockfile, so a lockfile change re-keys only the projects it reaches; --affected follows the same answer.",
+  "keywords": [
+    "vx",
+    "vx-plugin",
+    "monorepo",
+    "lockfile",
+    "pnpm",
+    "bun",
+    "npm",
+    "yarn"
+  ],
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.4"
   },
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "peerDependencies": {
+    "@vzn/vx": "^0.0.485"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vznjs/vx.git",
+    "directory": "packages/vx-lockfile"
+  },
+  "homepage": "https://github.com/vznjs/vx/tree/main/packages/vx-lockfile#readme",
+  "bugs": "https://github.com/vznjs/vx/issues"
 }

package/src/bun.ts

@@ -0,0 +1,263 @@
+// bun.lock → one digest per workspace package over the packages it can
+// reach. The text lockfile is JSONC: `workspaces` (root-relative dir →
+// manifest: name + dependency maps) and `packages` (a node_modules path →
+// `[id, registry, { dependencies, optionalDependencies, peerDependencies }, integrity]`;
+// a workspace package is `[name@workspace:dir]`, a git or tarball
+// package a shorter tuple). Bun hoists: a dependency `d` of the package
+// at path `p` resolves to `p/d` when that key exists, else to the nearest
+// ancestor's `…/d`, else to `d` at the root — the same walk Node's
+// resolver makes through nested node_modules.
+//
+// Bun.JSONC is the parser: no dependency, and the file is Bun's own.
+
+import { reachDigests } from '@vzn/vx'
+
+export interface Lockfile {
+  readonly version: string
+  /** root-relative dir (`.` for the root) → dependency name → specifier */
+  readonly workspaces: ReadonlyMap<string, ReadonlyMap<string, string>>
+  /** workspace package name → its dir */
+  readonly workspaceDirs: ReadonlyMap<string, string>
+  /** node_modules path → the package there */
+  readonly packages: ReadonlyMap<string, Entry>
+  /** `patchedDependencies`: `name@version` (or `name`) → the patch file's path */
+  readonly patches: ReadonlyMap<string, string>
+  /** Material every workspace folds: the lockfile version and install-wide knobs. */
+  readonly global: string
+}
+
+export interface Entry {
+  /** `name@version`, `name@workspace:dir`, `name@github:…` */
+  readonly id: string
+  readonly deps: ReadonlyMap<string, string>
+  /** integrity / commit — whatever pins the bytes */
+  readonly resolution: string
+}
+
+type Json = Record<string, unknown>
+/** The top-level fields the digest reads per workspace. */
+// Read per workspace: the workspaces and packages themselves, and the fields
+// whose whole effect is the `packages` entry a workspace reaches — how a
+// range was written (catalogs, D-141), what an override forced (D-142) and
+// what a patch changed (D-143). Folded into every workspace, one such edit
+// re-keyed them all.
+const PER_WORKSPACE = new Set([
+  'workspaces',
+  'packages',
+  'catalog',
+  'catalogs',
+  'overrides',
+  'patchedDependencies',
+])
+
+const DEP_FIELDS = [
+  'dependencies',
+  'devDependencies',
+  'optionalDependencies',
+  'peerDependencies',
+] as const
+
+export function parseLockfile(text: string): Lockfile {
+  let doc: unknown
+  try {
+    doc = Bun.JSONC.parse(text)
+  } catch (err) {
+    throw new Error(`bun.lock: ${err instanceof Error ? err.message : String(err)}`)
+  }
+  const d = record(doc)
+  if (d === undefined || typeof d['lockfileVersion'] !== 'number') {
+    throw new Error('bun.lock: not a Bun text lockfile (no lockfileVersion)')
+  }
+  const workspaces = new Map<string, ReadonlyMap<string, string>>()
+  const workspaceDirs = new Map<string, string>()
+  for (const [dir, manifest] of Object.entries(record(d['workspaces']) ?? {})) {
+    const m = record(manifest) ?? {}
+    const key = dir === '' ? '.' : dir
+    workspaces.set(key, depsOf(m))
+    if (typeof m['name'] === 'string') workspaceDirs.set(m['name'], key)
+  }
+  const packages = new Map<string, Entry>()
+  for (const [p, tuple] of Object.entries(record(d['packages']) ?? {})) {
+    if (!Array.isArray(tuple) || typeof tuple[0] !== 'string') continue
+    const meta = tuple.find((v) => record(v) !== undefined)
+    const resolution = tuple.slice(1).findLast((v) => typeof v === 'string' && v.length > 0)
+    packages.set(p, {
+      id: tuple[0],
+      deps: depsOf(record(meta) ?? {}),
+      resolution: typeof resolution === 'string' ? resolution : '',
+    })
+  }
+  // Every top-level field but the two read per workspace, so a field this
+  // parser has not heard of moves every workspace rather than none: an
+  // allow-list dropped `trustedDependencies`, which decides whose install
+  // scripts run (item 933).
+  const rest: Json = {}
+  for (const [k, v] of Object.entries(d)) if (!PER_WORKSPACE.has(k)) rest[k] = v
+
+  const patches = new Map<string, string>()
+  for (const [k, v] of Object.entries(record(d['patchedDependencies']) ?? {})) {
+    patches.set(k, typeof v === 'string' ? v : JSON.stringify(v))
+  }
+  const global = JSON.stringify(rest)
+  return {
+    version: String(d['lockfileVersion']),
+    workspaces,
+    workspaceDirs,
+    packages,
+    patches,
+    global,
+  }
+}
+
+function depsOf(m: Json): ReadonlyMap<string, string> {
+  const out = new Map<string, string>()
+  for (const field of DEP_FIELDS) {
+    const deps = record(m[field])
+    if (deps === undefined) continue
+    for (const [name, spec] of Object.entries(deps)) out.set(name, String(spec))
+  }
+  return out
+}
+
+function record(v: unknown): Json | undefined {
+  return v !== null && typeof v === 'object' && !Array.isArray(v) ? (v as Json) : undefined
+}
+
+/**
+ * Where dependency `name` of the package at node_modules path `from`
+ * lives: the deepest `…/name` key up the path, then the root. A workspace
+ * package sits at its own name (`@vzn/vx`) and resolves from there.
+ */
+function resolve(lock: Lockfile, from: string, name: string): string | undefined {
+  // A scoped name (`@s/x`) is one level at ANY depth: `foo/@s/y` → `foo` →
+  // ''. Only a root-level scope was joined, so `foo/@s/y` stepped to
+  // `foo/@s` and its `bar` resolved to `foo/@s/bar`, another package
+  // (`@s/bar`); the root `bar` it installs was never folded (item 901).
+  const levels = packageLevels(from)
+  for (let n = levels.length; ; n--) {
+    const base = levels.slice(0, n).join('/')
+    const key = base === '' ? name : `${base}/${name}`
+    if (lock.packages.has(key)) return key
+    if (n === 0) return undefined
+  }
+}
+
+/** A node_modules path's package levels: `foo/@s/y/z` → foo, @s/y, z. */
+function packageLevels(path: string): string[] {
+  if (path === '') return []
+  const parts = path.split('/')
+  const out: string[] = []
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i]!
+    out.push(part.startsWith('@') && i + 1 < parts.length ? `${part}/${parts[++i]}` : part)
+  }
+  return out
+}
+
+/**
+ * The patch files `patchedDependencies` names. bun.lock records a patch by
+ * PATH, never by a hash of its content, so an edited patch left the lockfile
+ * byte-identical and every key unmoved while the install applied the new
+ * one (item 1014): the claim hashes these files and hands them back.
+ */
+export function patchFiles(text: string): string[] {
+  const d = record(Bun.JSONC.parse(text))
+  return Object.values(record(d?.['patchedDependencies']) ?? {}).filter(
+    (v): v is string => typeof v === 'string',
+  )
+}
+
+/**
+ * Every workspace package's digest (by dir): the lockfile as one graph —
+ * a node per node_modules path, its material the id + resolution, an edge
+ * per resolved dependency — folded by core's `reachDigests`. A workspace
+ * dependency (`workspace:` id) is a node like any other, so what project
+ * A can import through workspace package B is B's whole reach.
+ */
+export function importerDigests(
+  lock: Lockfile,
+  files: ReadonlyMap<string, string> = new Map(),
+): ReadonlyMap<string, string> {
+  const index = new Map<string, number>()
+  const material: string[] = []
+  const edges: number[][] = []
+  const node = (id: string, own: string): number => {
+    let i = index.get(id)
+    if (i === undefined) {
+      i = material.length
+      index.set(id, i)
+      material.push(own)
+      edges.push([])
+    }
+    return i
+  }
+  // The name a package is installed under and what it is, not where: a
+  // re-hoist (`is-odd/is-number` → `is-number`, one version) re-keyed
+  // every project reaching it with the same bytes installed (D-140). Where
+  // it sits still decides what it resolves; that is the edges.
+  for (const [p, e] of lock.packages) node(p, `${installName(p)}\0${e.id}\0${e.resolution}`)
+  // A patch is part of the package it patches: an edit to one only `b`
+  // reaches re-keyed every workspace while it was install-wide (D-143).
+  // One that names no entry stays install-wide, so it still moves a key.
+  const loose: [string, string, string][] = []
+  for (const [key, file] of [...lock.patches].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) {
+    const own = `\npatch\0${key}\0${file}\0${files.get(file) ?? ''}`
+    let hit = false
+    for (const [p, e] of lock.packages) {
+      if (e.id !== key && e.id.slice(0, e.id.lastIndexOf('@')) !== key) continue
+      material[index.get(p)!] += own
+      hit = true
+    }
+    if (!hit) loose.push([key, file, files.get(file) ?? ''])
+  }
+  for (const [p, e] of lock.packages) {
+    const from = index.get(p)!
+    for (const [name, spec] of e.deps) {
+      const target = resolve(lock, p, name)
+      if (target !== undefined) edges[from]!.push(index.get(target)!)
+      else material[from] += `\nunresolved\0${name}\0${spec}`
+    }
+  }
+  // A workspace importer resolves like the package at its own name; the
+  // root importer ('') resolves from the root.
+  const importers = new Map<string, number>()
+  for (const [dir, deps] of lock.workspaces) {
+    // Its dir, as pnpm's importers fold theirs (item 1073).
+    const own = node(`workspace\0${dir}`, `workspace\0${dir}`)
+    importers.set(dir, own)
+    let from = ''
+    for (const [name, wsDir] of lock.workspaceDirs) if (wsDir === dir && dir !== '.') from = name
+    for (const [name, spec] of deps) {
+      const target = resolve(lock, from, name)
+      if (target !== undefined) edges[own]!.push(index.get(target)!)
+      else material[own] += `\nunresolved\0${name}\0${spec}`
+    }
+  }
+  // A workspace package's node carries no dependencies of its own — they
+  // live on its importer — so the node points at the importer: what a
+  // project can import through workspace package B is B's whole reach.
+  for (const [p, e] of lock.packages) {
+    const at = e.id.indexOf('@workspace:')
+    if (at === -1) continue
+    const target = importers.get(e.id.slice(at + '@workspace:'.length) || '.')
+    if (target !== undefined) edges[index.get(p)!]!.push(target)
+  }
+  const digests = reachDigests({ material, edges })
+  const out = new Map<string, string>()
+  // The global digest rides as DATA: Bun's xxHash3 reads only the low 32
+  // bits of a seed, so two lockfiles' globals could share one (item 682).
+  const globalMaterial =
+    loose.length === 0 ? lock.global : `${lock.global}\0${JSON.stringify(loose)}`
+  const global = Bun.hash.xxHash3(globalMaterial).toString(16).padStart(16, '0')
+  for (const [dir, i] of importers) {
+    out.set(dir, Bun.hash.xxHash3(`${global}\0${digests[i]!}`).toString(16).padStart(16, '0'))
+  }
+  return out
+}
+
+/** The name a package key installs under: its last segment, scope included. */
+function installName(key: string): string {
+  const parts = key.split('/')
+  const scoped = parts.length >= 2 && parts[parts.length - 2]!.startsWith('@')
+  return scoped ? parts.slice(-2).join('/') : parts[parts.length - 1]!
+}

package/src/index.ts

@@ -0,0 +1,159 @@
+// @vzn/vx-lockfile — one plugin per package manager, each keying every
+// task on its project's own resolved dependency closure from the
+// lockfile instead of the whole file.
+//
+// Core folds every lockfile at the root into the workspace fingerprint
+// that every task key sees, so one install re-keys the workspace and
+// `--affected` selects every project. Each plugin here CLAIMS its file
+// (`VxPlugin.fingerprint`) through core's `lockfileClaim`: the file leaves
+// the key digest, each task folds one digest per project — what that
+// project can reach through its dependencies, by resolved identity — and
+// `--affected` names the projects whose digest moved. This package is the
+// parsers; the claim, the per-project key (which folds the root
+// importer's digest into every project: the root's tools are on every
+// task's PATH), the memo (one parse per file content), the per-run read
+// and the diff are core's.
+//
+// Imports core only through the public `@vzn/vx` specifier.
+import {
+  refuseUnknownOptions,
+  type PluginOptionKinds,
+  definePlugin,
+  lockfileClaim,
+  type VxPlugin,
+} from '@vzn/vx'
+import * as pnpmLock from './pnpm.js'
+import * as bunLock from './bun.js'
+import * as npmLock from './npm.js'
+import * as yarnLock from './yarn.js'
+
+export interface LockfileOptions {
+  /**
+   * `'project'` (default): each task folds its own project's dependency
+   * closure — a lockfile change re-keys only the projects it reaches.
+   * `'workspace'`: the whole file, as core folds it — the coarse key,
+   * through the plugin, for a workspace that wants the claim but not yet
+   * the precision (`vx why` names it either way).
+   */
+  readonly scope?: 'project' | 'workspace'
+}
+
+/** Bumps when a digest folds differently (the memo's identity). */
+const DIGEST_VERSION = 14
+
+interface Manager {
+  readonly name: string
+  readonly file: string
+  readonly digest: (text: string, files: ReadonlyMap<string, string>) => ReadonlyMap<string, string>
+  readonly extraFiles?: (text: string) => readonly string[]
+}
+
+const MANAGERS = {
+  pnpm: {
+    name: 'pnpm',
+    file: 'pnpm-lock.yaml',
+    digest: (t) => pnpmLock.importerDigests(pnpmLock.parseLockfile(t)),
+  },
+  bun: {
+    name: 'bun',
+    file: 'bun.lock',
+    digest: (t, files) => bunLock.importerDigests(bunLock.parseLockfile(t), files),
+    extraFiles: (t) => bunLock.patchFiles(t),
+  },
+  npm: {
+    name: 'npm',
+    file: 'package-lock.json',
+    digest: (t) => npmLock.importerDigests(npmLock.parseLockfile(t)),
+  },
+  yarn: {
+    name: 'yarn',
+    file: 'yarn.lock',
+    digest: (t) => yarnLock.importerDigests(yarnLock.parseLockfile(t)),
+  },
+} satisfies Record<string, Manager>
+
+const CONFLICT = /^(?:<{7}|={7}|>{7})(?: |$)/m
+
+function plugin(manager: Manager, options: LockfileOptions): VxPlugin {
+  const scope = options.scope ?? 'project'
+  if (scope !== 'project' && scope !== 'workspace') {
+    throw new Error(
+      `@vzn/vx-lockfile: ${manager.name}() scope must be 'project' or 'workspace', not ${JSON.stringify(scope)}`,
+    )
+  }
+  // The parsers name their own file, so prefixing unconditionally said it
+  // twice — "bun.lock: bun.lock: Failed to parse JSONC" (2026-09-20).
+  // Prefix only what does not already name it, and say what fixes it: a
+  // lockfile vx cannot read is an install away from readable, and the
+  // alternative to reading it is a WRONG key, so the run refuses rather
+  // than guessing.
+  const refused = (err: unknown): Error => {
+    const message = err instanceof Error ? err.message : String(err)
+    const named = message.startsWith(`${manager.file}:`) ? message : `${manager.file}: ${message}`
+    return new Error(`${named} — regenerate it with \`${manager.name} install\``)
+  }
+  const extraFiles = manager.extraFiles
+  return definePlugin(
+    import.meta,
+    lockfileClaim({
+      file: manager.file,
+      part: manager.name,
+      version: DIGEST_VERSION,
+      scope,
+      // Read before `digest` on the key path: a malformed bun.lock refused
+      // there as a bare "JSONC Parse error", no file named (fuzzed, L-16).
+      ...(extraFiles !== undefined
+        ? {
+            extraFiles: (text: string) => {
+              try {
+                return extraFiles(text)
+              } catch (err) {
+                throw refused(err)
+              }
+            },
+          }
+        : {}),
+      digest: (text, files) => {
+        try {
+          // A conflicted lockfile names two installs at once. Yarn
+          // classic's line parser took the second side without a word, so
+          // the key named an install that may not be the one on disk.
+          if (CONFLICT.test(text))
+            throw new Error(`${manager.file}: holds git merge conflict markers`)
+          return manager.digest(text, files)
+        } catch (err) {
+          throw refused(err)
+        }
+      },
+    }),
+  )
+}
+
+/** Each option `LockfileOptions` names, with its kind: derived from the type, so the two cannot drift. */
+const LOCKFILE_KEYS: PluginOptionKinds<LockfileOptions> = {
+  scope: 'string',
+}
+
+/** `pnpm-lock.yaml` (lockfile v5, v6, v9, one document or pnpm 11's two): importers, snapshots, peers, patches, `link:`. */
+export function pnpm(options: LockfileOptions = {}): VxPlugin {
+  refuseUnknownOptions('pnpm()', options, LOCKFILE_KEYS)
+  return plugin(MANAGERS.pnpm, options)
+}
+
+/** `bun.lock` (the text lockfile): Bun's hoisted layout, nested versions, `workspace:` links. */
+export function bun(options: LockfileOptions = {}): VxPlugin {
+  refuseUnknownOptions('bun()', options, LOCKFILE_KEYS)
+  return plugin(MANAGERS.bun, options)
+}
+
+/** `package-lock.json` (lockfileVersion 2, 3): the `packages` map, nested `node_modules`, workspace links. */
+export function npm(options: LockfileOptions = {}): VxPlugin {
+  refuseUnknownOptions('npm()', options, LOCKFILE_KEYS)
+  return plugin(MANAGERS.npm, options)
+}
+
+/** `yarn.lock`: berry (yarn 2+, per workspace) and classic (yarn 1, one digest for the root). */
+export function yarn(options: LockfileOptions = {}): VxPlugin {
+  refuseUnknownOptions('yarn()', options, LOCKFILE_KEYS)
+  return plugin(MANAGERS.yarn, options)
+}

package/src/npm.ts

@@ -0,0 +1,166 @@
+// package-lock.json (lockfileVersion 2 and 3) → one digest per workspace
+// package over the packages it can reach. `packages` is keyed by
+// node_modules path: `""` is the root manifest, `node_modules/foo` a
+// hoisted package, `node_modules/foo/node_modules/bar` one nested under
+// it, `packages/a` a workspace package, and `node_modules/a` a link to it
+// (`link: true, resolved: "packages/a"`). A dependency `d` of the package
+// at path `p` is `p/node_modules/d` when that key exists, else the nearest
+// ancestor directory's, else `node_modules/d` — Node's own walk.
+
+import { reachDigests } from '@vzn/vx'
+
+export interface Lockfile {
+  readonly version: number
+  /** path → entry */
+  readonly packages: ReadonlyMap<string, Entry>
+  /** Material every workspace folds. */
+  readonly global: string
+}
+
+export interface Entry {
+  readonly deps: ReadonlyMap<string, string>
+  /** version + resolved + integrity — whatever pins the bytes; '' for a link */
+  readonly resolution: string
+  /** the path a `link: true` entry points at */
+  readonly link: string | undefined
+  readonly isWorkspace: boolean
+}
+
+type Json = Record<string, unknown>
+const DEP_FIELDS = [
+  'dependencies',
+  'devDependencies',
+  'optionalDependencies',
+  'peerDependencies',
+] as const
+
+export function parseLockfile(text: string): Lockfile {
+  let doc: unknown
+  try {
+    doc = JSON.parse(text)
+  } catch (err) {
+    throw new Error(`package-lock.json: ${err instanceof Error ? err.message : String(err)}`)
+  }
+  const d = record(doc)
+  const version = d === undefined ? undefined : d['lockfileVersion']
+  if (typeof version !== 'number') {
+    throw new Error('package-lock.json: not an npm lockfile (no lockfileVersion)')
+  }
+  if (version < 2) {
+    throw new Error(
+      `package-lock.json: lockfileVersion ${version} has no \`packages\` map — npm 7+ writes version 2 or 3`,
+    )
+  }
+  const packages = new Map<string, Entry>()
+  for (const [p, raw] of Object.entries(record(d!['packages']) ?? {})) {
+    const e = record(raw) ?? {}
+    const link = e['link'] === true && typeof e['resolved'] === 'string' ? e['resolved'] : undefined
+    packages.set(p, {
+      deps: depsOf(e),
+      resolution:
+        link === undefined
+          ? [e['version'], e['resolved'], e['integrity']]
+              .map((v) => (typeof v === 'string' ? v : ''))
+              .join('\0')
+          : '',
+      link,
+      isWorkspace: p !== '' && !p.startsWith('node_modules/') && !p.includes('/node_modules/'),
+    })
+  }
+  // Root `overrides` are not folded: what an override forced is the entry a
+  // workspace reaches, and npm 10 does not write them here at all (D-142).
+  const global = JSON.stringify({ lockfileVersion: version })
+  return { version, packages, global }
+}
+
+function depsOf(e: Json): ReadonlyMap<string, string> {
+  const out = new Map<string, string>()
+  for (const field of DEP_FIELDS) {
+    const deps = record(e[field])
+    if (deps === undefined) continue
+    for (const [name, spec] of Object.entries(deps)) out.set(name, String(spec))
+  }
+  return out
+}
+
+function record(v: unknown): Json | undefined {
+  return v !== null && typeof v === 'object' && !Array.isArray(v) ? (v as Json) : undefined
+}
+
+/**
+ * Node's walk: `p/node_modules/name`, then the same under each ancestor
+ * directory that is not itself a `node_modules`, then `node_modules/name`.
+ * A workspace nested in another's directory (`packages/a/packages/n`)
+ * resolves through `packages/a/node_modules`, where npm nests what only it
+ * needs; stepping from one `/node_modules/` boundary to the next skipped
+ * that directory, and `n` was keyed on its spec alone (D-139).
+ */
+function resolve(lock: Lockfile, from: string, name: string): string | undefined {
+  let base = from
+  for (;;) {
+    if (base !== 'node_modules' && !base.endsWith('/node_modules')) {
+      const key = base === '' ? `node_modules/${name}` : `${base}/node_modules/${name}`
+      if (lock.packages.has(key)) return key
+    }
+    if (base === '') return undefined
+    const i = base.lastIndexOf('/')
+    base = i === -1 ? '' : base.slice(0, i)
+  }
+}
+
+/**
+ * Every workspace package's digest (by dir, `.` for the root): the
+ * lockfile as one graph — a node per path, its material the resolution,
+ * an edge per resolved dependency, a link's edge to its target — folded
+ * by core's `reachDigests`.
+ */
+export function importerDigests(lock: Lockfile): ReadonlyMap<string, string> {
+  const index = new Map<string, number>()
+  const material: string[] = []
+  const edges: number[][] = []
+  for (const [p, e] of lock.packages) {
+    index.set(p, material.length)
+    // An installed package is its install name and what it is, not where
+    // it sits: a re-hoist of one version re-keyed every project reaching it
+    // (D-140). Where it sits decides what it resolves; that is the edges.
+    // The root and a workspace keep their path, which is who they are.
+    material.push(`${p === '' || e.isWorkspace ? p : installName(p)}\0${e.resolution}`)
+    edges.push([])
+  }
+  for (const [p, e] of lock.packages) {
+    const from = index.get(p)!
+    if (e.link !== undefined) {
+      const target = index.get(e.link)
+      if (target !== undefined) edges[from]!.push(target)
+      else material[from] += `\nlink\0${e.link}`
+      continue
+    }
+    for (const [name, spec] of e.deps) {
+      const target = resolve(lock, p, name)
+      if (target !== undefined) edges[from]!.push(index.get(target)!)
+      else material[from] += `\nunresolved\0${name}\0${spec}`
+    }
+  }
+  const digests = reachDigests({ material, edges })
+  const out = new Map<string, string>()
+  // The global digest rides as DATA: Bun's xxHash3 reads only the low 32
+  // bits of a seed, so two lockfiles' globals could share one (item 682).
+  const global = Bun.hash.xxHash3(lock.global).toString(16).padStart(16, '0')
+  for (const [p, e] of lock.packages) {
+    if (p !== '' && !e.isWorkspace) continue
+    out.set(
+      p === '' ? '.' : p,
+      Bun.hash
+        .xxHash3(`${global}\0${digests[index.get(p)!]!}`)
+        .toString(16)
+        .padStart(16, '0'),
+    )
+  }
+  return out
+}
+
+/** `node_modules/a/node_modules/@s/b` → `@s/b`. */
+function installName(p: string): string {
+  const i = p.lastIndexOf('node_modules/')
+  return i === -1 ? p : p.slice(i + 'node_modules/'.length)
+}

package/src/pnpm.ts

@@ -0,0 +1,292 @@
+// pnpm-lock.yaml → one digest per importer (workspace project) over the
+// packages that importer can actually reach: its own dependencies, their
+// dependencies, and so on through `snapshots` (v9) or `packages` (v5/v6),
+// with `link:` dependencies followed into the linked importer's closure.
+// A package's identity is its snapshot key — name, version AND the
+// resolved-peer suffix, since `foo@1(react@18)` and `foo@1(react@19)` are
+// different node_modules — plus its resolution (integrity / tarball /
+// commit) and any patch applied to it. Everything that changes what an
+// install produces for EVERY importer (pnpmfile, package extensions,
+// overrides, settings) is folded into every digest.
+//
+// Bun.YAML is the parser: no dependency, and the file is plain YAML.
+
+import { reachDigests } from '@vzn/vx'
+
+export interface Lockfile {
+  readonly version: string
+  /** importer path (`.`, `packages/a`) → dependency name → version or `link:…` */
+  readonly importers: ReadonlyMap<string, ReadonlyMap<string, string>>
+  /** snapshot key → dependency name → version (v9 `snapshots`; v5/v6 `packages`) */
+  readonly snapshots: ReadonlyMap<string, ReadonlyMap<string, string>>
+  /** package key (v9: `name@version`; v5/v6: the snapshot key) → resolution digest */
+  readonly resolutions: ReadonlyMap<string, string>
+  /** `name` or `name@version` → patch hash */
+  readonly patches: ReadonlyMap<string, string>
+  /** Material every importer folds: the lockfile version and the install-wide knobs. */
+  readonly global: string
+}
+
+type Yaml = Record<string, unknown>
+
+const DEP_FIELDS = ['dependencies', 'devDependencies', 'optionalDependencies'] as const
+
+/**
+ * The top-level fields the digest reads per importer: the importers, the
+ * packages and snapshots they reach, their patches, and the catalogs their
+ * specifiers resolved. `overrides` too: what an override did is the
+ * snapshot an importer now reaches, and folded into every digest one
+ * override that only `b` reached re-keyed `a` and the root as well (probed
+ * on pnpm 9, D-142). (v5's lone importer, written at the top, may fold as
+ * global too: it is the only importer there is.)
+ */
+const PER_IMPORTER = new Set([
+  'importers',
+  'packages',
+  'snapshots',
+  'patchedDependencies',
+  'catalogs',
+  'overrides',
+])
+
+export function parseLockfile(text: string): Lockfile {
+  // pnpm 10.x and 11 write the env lockfile (`configDependencies`, the
+  // package manager's own install) as a leading YAML document; the
+  // project lockfile is the last one, as Turbo reads it. Read as one
+  // document, the pair was an array and every such repo was refused
+  // with "regenerate it", which regenerates the same two documents.
+  const parsed: unknown = Bun.YAML.parse(text)
+  const docs = (Array.isArray(parsed) ? parsed : [parsed]).filter((d) => d !== null)
+  const doc = docs.at(-1) as Yaml | undefined
+  const leading = docs.slice(0, -1)
+  if (doc === undefined || typeof doc !== 'object' || Array.isArray(doc)) {
+    throw new Error('pnpm-lock.yaml: not a YAML document')
+  }
+  const version = scalar(doc['lockfileVersion'])
+  const major = Number.parseInt(version, 10)
+  if (!Number.isFinite(major) || major < 5) {
+    throw new Error(`pnpm-lock.yaml: unsupported lockfileVersion ${JSON.stringify(version)}`)
+  }
+
+  const importers = new Map<string, ReadonlyMap<string, string>>()
+  const rawImporters = record(doc['importers'])
+  if (rawImporters !== undefined) {
+    for (const [dir, entry] of Object.entries(rawImporters)) importers.set(dir, depsOf(entry))
+  } else if (DEP_FIELDS.some((f) => doc[f] !== undefined)) {
+    // A single-package lockfile keeps its dependencies at the top level.
+    importers.set('.', depsOf(doc))
+  }
+
+  const snapshots = new Map<string, ReadonlyMap<string, string>>()
+  const resolutions = new Map<string, string>()
+  const packages = record(doc['packages']) ?? {}
+  for (const [key, entry] of Object.entries(packages)) {
+    const e = record(entry) ?? {}
+    resolutions.set(key, resolutionOf(e))
+    if (major < 9) snapshots.set(key, depsOf(e))
+  }
+  if (major >= 9) {
+    for (const [key, entry] of Object.entries(record(doc['snapshots']) ?? {})) {
+      snapshots.set(key, depsOf(entry))
+    }
+  }
+
+  const patches = new Map<string, string>()
+  for (const [name, entry] of Object.entries(record(doc['patchedDependencies']) ?? {})) {
+    const e = record(entry)
+    patches.set(name, e === undefined ? scalar(entry) : scalar(e['hash']) || stable(e))
+  }
+
+  // Every top-level field but those read per importer above, so a field
+  // this parser has not heard of moves every importer rather than none: an
+  // allow-list dropped v6's `onlyBuiltDependencies`, which decides whether
+  // install scripts run anywhere (item 933).
+  const rest: Record<string, unknown> = {}
+  for (const [k, v] of Object.entries(doc)) if (!PER_IMPORTER.has(k)) rest[k] = v
+  // The env lockfile moves every importer: a config dependency can carry
+  // the pnpmfile that rewrites every install, and the package manager's
+  // own version installs all of them. Folded only when present, so a
+  // one-document lockfile keys as it did.
+  const global = stable(
+    leading.length === 0
+      ? { lockfileVersion: version, rest }
+      : { lockfileVersion: version, rest, leading },
+  )
+  return { version, importers, snapshots, resolutions, patches, global }
+}
+
+/** `dependencies` + `devDependencies` + `optionalDependencies` of an entry, as name → version. */
+function depsOf(entry: unknown): ReadonlyMap<string, string> {
+  const out = new Map<string, string>()
+  const e = record(entry)
+  if (e === undefined) return out
+  for (const field of DEP_FIELDS) {
+    const deps = record(e[field])
+    if (deps === undefined) continue
+    for (const [name, v] of Object.entries(deps)) {
+      // v6/v9: `{ specifier, version }`; v5 and every snapshot: the version.
+      const spec = record(v)
+      out.set(name, spec === undefined ? scalar(v) : scalar(spec['version']))
+    }
+  }
+  return out
+}
+
+function resolutionOf(entry: Yaml): string {
+  const r = record(entry['resolution'])
+  return r === undefined ? '' : stable(r)
+}
+
+/** A YAML scalar as text; an object or a missing value reads as ''. */
+function scalar(v: unknown): string {
+  return typeof v === 'string'
+    ? v
+    : typeof v === 'number' || typeof v === 'boolean'
+      ? String(v)
+      : ''
+}
+
+function record(v: unknown): Yaml | undefined {
+  return v !== null && typeof v === 'object' && !Array.isArray(v) ? (v as Yaml) : undefined
+}
+
+/** JSON with sorted keys, so YAML key order cannot move a digest. */
+export function stable(v: unknown): string {
+  return JSON.stringify(v, (_k, val: unknown) =>
+    val !== null && typeof val === 'object' && !Array.isArray(val)
+      ? Object.fromEntries(Object.entries(val as Yaml).sort(([a], [b]) => (a < b ? -1 : 1)))
+      : val,
+  )
+}
+
+/**
+ * The snapshot key a dependency `name@version` resolves to, per lockfile
+ * generation: `name@1.0.0(peer@2)` (v9), `/name@1.0.0(peer@2)` (v6),
+ * `/name/1.0.0_peer@2` (v5). A version that is already a key (`/…`) is
+ * used as it is. Otherwise the generation's own key comes first, then
+ * the version itself when the lockfile has a snapshot under it: an alias
+ * (`name: other@1.0.0`), and a v5/v6 `file:…`, whose key is the bare
+ * version. A v9 `file:…` is keyed `name@file:…` like any other, and
+ * taking the version first made it a leaf: a bump behind a directory
+ * dependency moved no digest (item 802).
+ */
+function snapshotKey(lock: Lockfile, name: string, version: string): string {
+  if (version.startsWith('/')) return version
+  const major = Number.parseInt(lock.version, 10)
+  const own =
+    major >= 9 ? `${name}@${version}` : major >= 6 ? `/${name}@${version}` : `/${name}/${version}`
+  if (lock.snapshots.has(own)) return own
+  return lock.snapshots.has(version) ? version : own
+}
+
+/** `name@1.0.0(peer@2)` → `name@1.0.0`: the `packages` key a v9 snapshot resolves under. */
+function packageKey(snapshot: string): string {
+  const paren = snapshot.indexOf('(')
+  return paren === -1 ? snapshot : snapshot.slice(0, paren)
+}
+
+/** `foo@1.0.0(peer)` / `/foo@1.0.0` → `foo`; `/@s/foo/1.0.0` (v5) → `@s/foo`. */
+function packageName(lock: Lockfile, snapshot: string): string {
+  let s = packageKey(snapshot)
+  if (s.startsWith('/')) s = s.slice(1)
+  if (Number.parseInt(lock.version, 10) >= 6) {
+    const at = s.indexOf('@', 1)
+    return at === -1 ? s : s.slice(0, at)
+  }
+  const slash = s.lastIndexOf('/')
+  return slash === -1 ? s : s.slice(0, slash)
+}
+
+/**
+ * Every importer's digest: the lockfile as one graph (importers and
+ * snapshots alike), each node's material its identity, and core's
+ * `reachDigests` folding what every node reaches (components, so pnpm's
+ * cycles terminate). A `link:` dependency is an edge to the linked
+ * importer's node, so what project A can import through workspace
+ * package B is B's whole reach.
+ */
+export function importerDigests(lock: Lockfile): ReadonlyMap<string, string> {
+  const g = buildGraph(lock)
+  const hashes = reachDigests(g)
+  const out = new Map<string, string>()
+  // The global digest rides as DATA: Bun's xxHash3 reads only the low 32
+  // bits of a seed, so two lockfiles' globals could share one (item 682).
+  const global = Bun.hash.xxHash3(lock.global).toString(16).padStart(16, '0')
+  for (const dir of lock.importers.keys()) {
+    const h = Bun.hash.xxHash3(`${global}\0${hashes[g.index.get(importerNode(dir))!]!}`)
+    out.set(dir, h.toString(16).padStart(16, '0'))
+  }
+  return out
+}
+
+interface Graph {
+  /** node id → index */
+  readonly index: Map<string, number>
+  /** what each node folds of its own */
+  readonly material: string[]
+  /** out-edges, by index */
+  readonly edges: number[][]
+}
+
+function importerNode(dir: string): string {
+  return `importer\0${dir}`
+}
+
+function buildGraph(lock: Lockfile): Graph {
+  const index = new Map<string, number>()
+  const material: string[] = []
+  const edges: number[][] = []
+  const node = (id: string, own: string): number => {
+    let i = index.get(id)
+    if (i === undefined) {
+      i = material.length
+      index.set(id, i)
+      material.push(own)
+      edges.push([])
+    }
+    return i
+  }
+  for (const key of lock.snapshots.keys()) {
+    const resolution = lock.resolutions.get(key) ?? lock.resolutions.get(packageKey(key)) ?? ''
+    const patch =
+      lock.patches.get(packageKey(key)) ?? lock.patches.get(packageName(lock, key)) ?? ''
+    node(key, `${key}\0${resolution}\0${patch}`)
+  }
+  // Each importer folds its own dir: with one material for all, two
+  // importers that link each other were told apart by their edges alone,
+  // and swapping which reaches which version gave the same lines, so a
+  // lockfile that moved both installs keyed neither (item 1073).
+  for (const dir of lock.importers.keys()) node(importerNode(dir), importerNode(dir))
+  const link = (from: number, dir: string, name: string, version: string): void => {
+    if (version.startsWith('link:')) {
+      const target = joinPosix(dir, version.slice('link:'.length))
+      if (lock.importers.has(target)) edges[from]!.push(index.get(importerNode(target))!)
+      else material[from] += `\nlink\0${name}\0${version}`
+      return
+    }
+    const key = snapshotKey(lock, name, version)
+    // A dependency with no snapshot (a leaf the file lists only by version)
+    // is a node of its own, so its version still counts.
+    edges[from]!.push(node(key, `${key}\0${lock.resolutions.get(packageKey(key)) ?? ''}\0`))
+  }
+  for (const [dir, deps] of lock.importers) {
+    const from = index.get(importerNode(dir))!
+    for (const [name, version] of deps) link(from, dir, name, version)
+  }
+  for (const [key, deps] of lock.snapshots) {
+    const from = index.get(key)!
+    for (const [name, version] of deps) link(from, '.', name, version)
+  }
+  return { index, material, edges }
+}
+
+/** `packages/a` + `../b` → `packages/b`; `.` + `packages/a` → `packages/a`. POSIX, as the lockfile writes paths. */
+function joinPosix(base: string, rel: string): string {
+  const parts: string[] = []
+  for (const seg of `${base}/${rel}`.split('/')) {
+    if (seg === '' || seg === '.') continue
+    if (seg === '..') parts.pop()
+    else parts.push(seg)
+  }
+  return parts.length === 0 ? '.' : parts.join('/')
+}

package/src/yarn.ts

@@ -0,0 +1,294 @@
+// yarn.lock → one digest per workspace over the packages it can reach.
+// Two generations, one graph. Berry (yarn 2+) is YAML: each entry is keyed
+// by the descriptors it satisfies (`"foo@npm:^1.0.0, foo@npm:^1.2.0":`),
+// carries `resolution`, `dependencies` / `peerDependencies` (name →
+// range) and `checksum`; a workspace is `"a@workspace:packages/a"`. A
+// dependency `bar: "npm:^2"` resolves to the entry keyed `bar@npm:^2`.
+// Classic (yarn 1) is its own text format: `"foo@^1.0.0", "foo@^1.2.0":`
+// then indented `version`, `resolved`, `integrity` and `dependencies:`
+// with `bar "^2"` lines; classic has no workspace entries, so workspaces
+// resolve from their own `package.json` — which the digest reads from the
+// lockfile's root descriptors only, so a workspace's digest is the root's
+// reach through the descriptors the file resolves.
+
+import { reachDigests } from '@vzn/vx'
+import { stable } from './pnpm.js'
+
+export interface Lockfile {
+  readonly generation: 'berry' | 'classic'
+  /** entry id (the resolution, or the first descriptor) → entry */
+  readonly entries: ReadonlyMap<string, Entry>
+  /** descriptor (`name@range`) → entry id */
+  readonly descriptors: ReadonlyMap<string, string>
+  /** workspace dir → entry id (berry only) */
+  readonly workspaces: ReadonlyMap<string, string>
+  /** package name → every entry a descriptor of that name resolves to (berry only) */
+  readonly names: ReadonlyMap<string, readonly string[]>
+  /**
+   * `name@npm:range` → the entry of Yarn's builtin compat patch of it
+   * (`resolve`, `typescript`, `fsevents`; berry only). The workspace keeps
+   * asking for the plain descriptor, which keys the unpatched entry, while
+   * the patched one is what Yarn installs (item 1074).
+   */
+  readonly builtinPatches: ReadonlyMap<string, string>
+  readonly global: string
+}
+
+export interface Entry {
+  readonly deps: ReadonlyMap<string, string>
+  /** resolution + checksum / version + resolved + integrity */
+  readonly resolution: string
+}
+
+type Json = Record<string, unknown>
+
+export function parseLockfile(text: string): Lockfile {
+  const head = text.slice(0, 400)
+  if (/^# yarn lockfile v1/m.test(head)) return parseClassic(text)
+  if (/^__metadata:/m.test(head) || /^\s*version: \d/m.test(head)) return parseBerry(text)
+  throw new Error(
+    'yarn.lock: neither a classic (`# yarn lockfile v1`) nor a berry (`__metadata`) lockfile',
+  )
+}
+
+function parseBerry(text: string): Lockfile {
+  let doc: unknown
+  try {
+    doc = Bun.YAML.parse(text)
+  } catch (err) {
+    throw new Error(`yarn.lock: ${err instanceof Error ? err.message : String(err)}`)
+  }
+  const d = record(doc)
+  if (d === undefined) throw new Error('yarn.lock: not a YAML document')
+  const entries = new Map<string, Entry>()
+  const descriptors = new Map<string, string>()
+  const workspaces = new Map<string, string>()
+  const names = new Map<string, string[]>()
+  const builtinPatches = new Map<string, string>()
+  for (const [keys, raw] of Object.entries(d)) {
+    if (keys === '__metadata') continue
+    const e = record(raw) ?? {}
+    const resolution = typeof e['resolution'] === 'string' ? e['resolution'] : keys
+    // Every field of the entry but the dependencies it links, so a field
+    // this parser has not heard of moves what reaches the entry: reading
+    // the resolution and checksum alone dropped the root workspace's
+    // `dependenciesMeta` (`built`, `unplugged`), which governs the whole
+    // install (item 933).
+    const material = Object.fromEntries(
+      Object.entries(e).filter(([k]) => k !== 'dependencies' && k !== 'peerDependencies'),
+    )
+    entries.set(resolution, {
+      deps: depsOf(e, ['dependencies', 'peerDependencies']),
+      resolution: `${resolution}\0${stable(material)}`,
+    })
+    // Yarn joins a key's descriptors with ', '; a range's own trailing
+    // space is kept (forge's `p-limit: "npm:^3.1.0 "`), or its lookup
+    // missed and fell back to every entry of the name.
+    for (const k of keys.split(',')) {
+      const descriptor = k.trimStart()
+      descriptors.set(descriptor, resolution)
+      const builtin = /@patch:(.+)#optional!builtin<[^>]*>$/.exec(descriptor)
+      if (builtin !== null) {
+        let inner: string
+        try {
+          inner = decodeURIComponent(builtin[1]!)
+        } catch {
+          inner = builtin[1]!
+        }
+        builtinPatches.set(inner, resolution)
+      }
+      const name = descriptor.slice(0, descriptor.indexOf('@', 1))
+      const ids = names.get(name)
+      if (ids === undefined) names.set(name, [resolution])
+      else if (!ids.includes(resolution)) ids.push(resolution)
+    }
+    const ws = resolution.indexOf('@workspace:')
+    if (ws !== -1) workspaces.set(resolution.slice(ws + '@workspace:'.length), resolution)
+  }
+  const meta = record(d['__metadata']) ?? {}
+  return {
+    generation: 'berry',
+    entries,
+    descriptors,
+    workspaces,
+    names,
+    builtinPatches,
+    global: JSON.stringify({ version: meta['version'], cacheKey: meta['cacheKey'] }),
+  }
+}
+
+/** The classic format: an unquoted-YAML dialect with `key value` lines. */
+function parseClassic(text: string): Lockfile {
+  const entries = new Map<string, Entry>()
+  const descriptors = new Map<string, string>()
+  let keys: string[] | null = null
+  let fields: Record<string, string> = {}
+  let deps = new Map<string, string>()
+  let inDeps = false
+  const flush = (): void => {
+    if (keys === null) return
+    const id = keys[0]!
+    // The descriptors an entry satisfies are part of what the file records:
+    // `foo@^1.0.0` moving from the 1.0.0 entry to the 1.1.0 one (a
+    // deduplication, `yarn upgrade`) changes what a workspace installs
+    // while every entry's version, url and integrity stay as they were, and
+    // the digest did not move (item 902). Classic has no workspace entries
+    // to carry that edge, so each entry carries its own descriptors.
+    entries.set(id, {
+      deps,
+      resolution: `${fields['version'] ?? ''}\0${fields['resolved'] ?? ''}\0${fields['integrity'] ?? ''}\0${[...keys].sort().join(',')}`,
+    })
+    for (const k of keys) descriptors.set(k, id)
+    keys = null
+    fields = {}
+    deps = new Map()
+    inDeps = false
+  }
+  for (const raw of text.split('\n')) {
+    const line = raw.replace(/\r$/, '')
+    if (line.length === 0 || line.startsWith('#')) continue
+    if (!line.startsWith(' ')) {
+      flush()
+      keys = line
+        .replace(/:$/, '')
+        .split(',')
+        .map((k) => unquote(k.trim()))
+      continue
+    }
+    if (keys === null) continue
+    const depth = line.length - line.trimStart().length
+    const body = line.trim()
+    if (depth === 2) {
+      inDeps = false
+      if (body === 'dependencies:' || body === 'optionalDependencies:') {
+        inDeps = true
+        continue
+      }
+      const sp = body.indexOf(' ')
+      if (sp !== -1) fields[body.slice(0, sp)] = unquote(body.slice(sp + 1).trim())
+      continue
+    }
+    if (depth >= 4 && inDeps) {
+      const sp = body.indexOf(' ')
+      if (sp !== -1) deps.set(unquote(body.slice(0, sp)), unquote(body.slice(sp + 1).trim()))
+    }
+  }
+  flush()
+  return {
+    generation: 'classic',
+    entries,
+    descriptors,
+    workspaces: new Map(),
+    names: new Map(),
+    builtinPatches: new Map(),
+    global: 'classic',
+  }
+}
+
+function unquote(s: string): string {
+  return s.length >= 2 && s.startsWith('"') && s.endsWith('"') ? s.slice(1, -1) : s
+}
+
+function depsOf(e: Json, fields: readonly string[]): ReadonlyMap<string, string> {
+  const out = new Map<string, string>()
+  for (const field of fields) {
+    const deps = record(e[field])
+    if (deps === undefined) continue
+    for (const [name, spec] of Object.entries(deps)) out.set(name, String(spec))
+  }
+  return out
+}
+
+function record(v: unknown): Json | undefined {
+  return v !== null && typeof v === 'object' && !Array.isArray(v) ? (v as Json) : undefined
+}
+
+/**
+ * `bar` + `npm:^2` → the entry keyed `bar@npm:^2`; classic: `bar@^2`. A
+ * bare range gets berry's `npm:` prefix. A `workspace:` range resolves to
+ * the workspace entry of that name whatever the range says (`*`, `^`, a
+ * path) — berry lists the range among the keys, but the name is enough.
+ *
+ * A Yarn 4 catalog range (`catalog:`, `catalog:<name>`) is recorded as
+ * that literal, and the range the catalog names lives in `.yarnrc.yml`,
+ * not here: the entry it resolved to is in the file, but nothing points
+ * at it. So it resolves to EVERY entry of that package — a bump of any
+ * of them moves the workspace, never a bump of none (turborepo#12635).
+ * Which one the catalog names is `.yarnrc.yml`'s to say, and core folds
+ * that file into every key.
+ */
+function resolveDescriptor(
+  lock: Lockfile,
+  from: string,
+  name: string,
+  range: string,
+): readonly string[] {
+  // A descriptor Yarn compat-patches reaches the patched entry it installs
+  // as well as the plain one it keys (item 1074).
+  const withPatch = (descriptor: string, id: string): readonly string[] => {
+    const patched = lock.builtinPatches.get(descriptor)
+    return patched === undefined || patched === id ? [id] : [id, patched]
+  }
+  const direct = lock.descriptors.get(`${name}@${range}`)
+  if (direct !== undefined) return withPatch(`${name}@${range}`, direct)
+  if (lock.generation !== 'berry') return []
+  // A path range (`portal:`, `file:`, `link:`) is keyed bound to the
+  // package that names it, `::locator=<its locator>`; unbound it fell
+  // back to every entry of the name, another workspace's included.
+  const bound = lock.descriptors.get(`${name}@${range}::locator=${encodeURIComponent(from)}`)
+  if (bound !== undefined) return [bound]
+  if (range.startsWith('workspace:')) {
+    for (const id of lock.workspaces.values()) if (id.startsWith(`${name}@workspace:`)) return [id]
+    return []
+  }
+  if (range.startsWith('catalog:')) return lock.names.get(name) ?? []
+  if (!range.includes(':')) {
+    const bare = lock.descriptors.get(`${name}@npm:${range}`)
+    if (bare !== undefined) return withPatch(`${name}@npm:${range}`, bare)
+  }
+  // A descriptor the file does not key: a root `resolutions` override
+  // rewrote it (to a `patch:`, another range), so what is installed is an
+  // entry nothing in the file points at. Edges to nowhere left that entry
+  // outside every workspace's reach, and a patch edit re-keyed nothing
+  // (item 903). Every entry of the name, as for a catalog: a bump of any
+  // of them moves the workspace, never a bump of none.
+  return lock.names.get(name) ?? []
+}
+
+/**
+ * Every workspace's digest. Berry: one node per entry, workspaces among
+ * them, keyed by dir. Classic: the file has no workspace entries, so the
+ * one digest is the root's (`.`) over every entry the file resolves —
+ * coarse, and honest about what classic records.
+ */
+export function importerDigests(lock: Lockfile): ReadonlyMap<string, string> {
+  const index = new Map<string, number>()
+  const material: string[] = []
+  const edges: number[][] = []
+  for (const [id, e] of lock.entries) {
+    index.set(id, material.length)
+    material.push(e.resolution)
+    edges.push([])
+  }
+  for (const [id, e] of lock.entries) {
+    const from = index.get(id)!
+    for (const [name, range] of e.deps) {
+      const targets = resolveDescriptor(lock, id, name, range)
+      for (const target of targets) edges[from]!.push(index.get(target)!)
+      if (targets.length === 0) material[from] += `\nunresolved\0${name}\0${range}`
+    }
+  }
+  const digests = reachDigests({ material, edges })
+  // The global digest rides as DATA: Bun's xxHash3 reads only the low 32
+  // bits of a seed, so two lockfiles' globals could share one (item 682).
+  const global = Bun.hash.xxHash3(lock.global).toString(16).padStart(16, '0')
+  const out = new Map<string, string>()
+  const fold = (h: string) => Bun.hash.xxHash3(`${global}\0${h}`).toString(16).padStart(16, '0')
+  if (lock.generation === 'classic') {
+    const all = ['classic', global, ...[...digests].sort()].join('\n')
+    out.set('.', Bun.hash.xxHash3(all).toString(16).padStart(16, '0'))
+    return out
+  }
+  for (const [dir, id] of lock.workspaces) out.set(dir, fold(digests[index.get(id)!]!))
+  return out
+}