@antongolub/lockfile 0.0.0-snapshot.43 → 0.0.0-snapshot.45

package/README.md

@@ -1,238 +1,166 @@
 # @antongolub/lockfile
-> Read and write lockfiles with reasonable losses
 
-<p><img alt="@antongolub/lockfile" src="./pics/pic.png" align="right" width="300">
-Each package manager brings its own philosophy of how to describe, store and control project dependencies.
-It <i>seems</i> acceptable for developers, but literally becomes a <strike>pain in *** ***</strike> headache for isec, devops and release engineers.
-This lib is a naive attempt to build a pm-independent, generic, extensible and reliable deps representation.
+> Universal lockfile model and converter for **npm**, **yarn**, **pnpm**, **bun**.
+
+<p><img alt="@antongolub/lockfile — universal lockfile model and converter for npm, yarn, pnpm, bun" src="./pics/lockfile.svg" align="right" width="300">
+
+Each package manager brings its own philosophy of how to describe, store and
+control project dependencies. It looks acceptable to a developer staring at a
+single repo, but it becomes a real headache for IS, DevOps and release
+engineers — and impossible for any tool that needs to reason about
+dependency graphs across the ecosystem.
+
+This library models the dependency graph independent of any specific
+package manager, then projects it back into the format you need.
+Conversion is one use case; modification (audit-fix, override pinning,
+license filtering) is the headline.
 
-The `package.json` manifest contains its own deps requirements, the `lockfile` holds the deps resolution snapshot<sup>*</sup>,
-so both of them are required to build a dependency graph. We can try to convert this data into a normalized representation for further analysis and processing (for example, to fix vulnerabilities).
-And then, if necessary, try convert it back to the original/another format.
 </p>
 
 ## Status
-Proof of concept. The API may change significantly ⚠️
 
-## Getting started
-### Install
-```shell
-yarn add @antongolub/lockfile@snapshot
-```
+🔒 **Contract preview, implementation in progress.** The public API
+(`parse` / `stringify`) is locked. Adapter implementations are landing
+incrementally — see [SCHEMAS.md](./SCHEMAS.md) for what's recognised.
+Not yet published; `npm install` will appear once the first adapters
+ship end-to-end.
 
-## Usage
-_tl;dr_
-```ts
-import fs from 'fs/promises'
-import {parse, analyze} from '@antongolub/lockfile'
+## Concept
 
-const lf = await fs.readFile('yarn.lock', 'utf-8')
-const pkg = await fs.readFile('package.json', 'utf-8')
+A target lockfile is **constructed** from facts gathered across whatever
+sources are available: the input lockfile bytes, project `package.json`s,
+the package-manager cache, and (opt-in) the registry. The simplest case is
+*conversion* — parse one format, stringify another. The general case is
+*construction*: assemble what the target requires from whichever source can
+supply it.
 
-const snapshot = parse(lf, pkg) // Holds JSON-friendly TEntries[]
-const idx = analyze(snapshot)   // An index to represent repo dep graphs
+Three layers, never collapsed:
 
-// idx.entries
-// idx.prod
-// idx.edges
-```
+- **Manifest** — declared constraints from `package.json`(s).
+- **Graph** — resolved package instances (peer-aware) and the edges
+  between them. The canonical internal model. Modifiers operate here.
+- **Layout** — physical projection on disk: hoisted, isolated (pnpm-style),
+  PnP, nm-linked.
+
+Conversion is **lossy by design**. We aim for *semantically equivalent*,
+not *byte-identical*. Irreducible facts (integrity hashes, resolution URLs,
+signatures) are the exception — they are never silently lost.
 
 ## API
-### JS/TS
-```ts
-import { parse, format, analyze, convert } from '@antongolub/lockfile'
 
-const lf = await fs.readFile('yarn.lock', 'utf-8')
-const pkgJson = await fs.readFile('package.json', 'utf-8')
-const snapshot = parse(lf, pkgJson)
+```ts
+import { parse, stringify } from '@antongolub/lockfile'
 
-const lf1 = format(snapshot)
-const lf2 = format(snapshot, 'npm-1')         // Throws err: npm v1 meta does not support workspaces
+const lf  = parse(rawLockfileBytes)
+const str = stringify(lf, { format: 'npm-3' })
+```
 
-const meta = await readMeta()                 // reads local package.jsons data to gather required data like `engines`, `license`, `bins`, etc
-const meta2 = await fetchMeta(snapshot)       // does the same, but from the remote registry
-const lf3 = format(snapshot, 'npm-3', {meta}) // format with options
+Two top-level operations, modelled on `JSON.parse` / `JSON.stringify`:
 
-const idx = analyze(snapshot)
-idx.edges
-// [
-//  [ '', '@antongolub/npm-test@4.0.1' ],
-//  [ '@antongolub/npm-test@4.0.1', '@antongolub/npm-test@3.0.1' ],
-//  [ '@antongolub/npm-test@3.0.1', '@antongolub/npm-test@2.0.1' ],
-//  [ '@antongolub/npm-test@2.0.1', '@antongolub/npm-test@1.0.0' ]
-// ]
+```ts
+parse(input: string | Uint8Array, options?: ParseOptions): Lockfile
 
-const lf4 = await convert(lf, pkgJson, 'yarn-berry')
+stringify(lockfile: Lockfile, options: StringifyOptions): string
 ```
 
-### CLI
-```shell
-npx @antongolub/lockfile@snapshot <cmd> [options]
+- `parse` auto-detects the format by content sniffing. Pass
+  `{ format: '<id>' }` to skip detection. Pass `{ manifests }` for
+  formats that need extra workspace context (notably `yarn-classic`).
+- `stringify`'s `options.format` is **required** — there is no implicit
+  "same as parsed". Round-tripping is an explicit choice the caller makes.
 
-npx @antongolub/lockfile@snapshot parse --input=yarn.lock,package.json --output=snapshot.json
-npx @antongolub/lockfile@snapshot format --input=snapshot.json --output=yarn.lock
-```
+`Lockfile` is the public alias for the internal canonical-graph type.
+`FormatId` is a string-literal union — see
+[SCHEMAS.md](./SCHEMAS.md) for the full list.
+
+### Options
 
-| Command / Option | Description                                                                           |
-|------------------|---------------------------------------------------------------------------------------|
-| `parse`          | Parses lockfiles and package manifests into a snapshot                                |
-| `format`         | Formats a snapshot into a lockfile                                                    |
-| `convert`        | Converts a lockfile into another format. Shortcut for `parse` + `format`              |
-| `--input`        | A comma-separated list of files to parse: `snapshot.json` or `yarn.lock,package.json` |
-| `--output`       | A file to write the result to: `snapshot.json` or `yarn.lock`                         |
-| `--format`       | A lockfile format: `npm-1`, `npm-2`, `npm-3`, `yarn-berry`, `yarn-classic`            |
-
-### Terms
-`nmtree` — fs projection of deps, directories structure  
-`deptree` — bounds full dep paths with their resolved packages  
-`depgraph` — describes how resolved pkgs are related with each other
-
-### Lockfiles types
-| Package manager      | Meta format | Read | Write |
-|----------------------|-------------|------|-------|
-| npm <7               | 1           | ✓    | ✓     |
-| npm >=7              | 2           | ✓    |       |
-| npm >=9              | 3           | ✓    |       | 
-| yarn 1 (classic)     | 1           | ✓    | ✓     |
-| yarn 2, 3, 4 (berry) | 5, 6, 7     | ✓    | ✓     |
-
-### Dependency protocols
-| Type      | Supported | Example                                 | Description                                                    |
-|-----------|-----------|-----------------------------------------|----------------------------------------------------------------|
-| semver    | ✓         | `^1.2.3`                                | Resolves from the default registry                             |
-| tag       |           | `latest`                                | Resolves from the default registry                             |
-| npm       | ✓         | `npm:name@...`                          | Resolves from the npm registry                                 |
-| git       |           | `git@github.com:foo/bar.git`            | Downloads a public package from a Git repository               |
-| github    |           | `github:foo/bar`                        | Downloads a public package from GitHub                         |
-| github    | ✓         | `foo/bar`                               | Alias for the github: protocol                                 |
-| file      |           | `file:./my-package`                     | Copies the target location into the cache                      |
-| link      |           | `link:./my-folder`                      | Creates a link to the ./my-folder folder (ignore dependencies) |
-| patch     | _limited_ | `patch:left-pad@1.0.0#./my-patch.patch` | Creates a patched copy of the original package                 |
-| portal    |           | `portal:./my-folder`                    | Creates a link to the ./my-folder folder (follow dependencies) |
-| workspace | _limited_ | `workspace:*`                           | Creates a link to a package in another workspace               |
-
-https://v3.yarnpkg.com/features/protocols  
-https://yarnpkg.com/protocols  
-https://docs.npmjs.com/cli/v10/configuring-npm/package-json#dependencies
-
-### `TSnapshot`
 ```ts
-export type TSnapshot = Record<string, TEntry>
-
-export type TEntry = {
-  name:       string
-  version:    string
-  ranges:     string[]
-  hashes:     {
-    sha512?:  string
-    sha256?:  string
-    sha1?:    string
-    checksum?: string
-    md5?:     string
-  }
-  source:     {
-    type:     TSourceType // npm, workspace, gh, patch, etc
-    id:       string
-    registry?: string
-  }
-  // optional pm-specific lockfile meta
-  manifest?:              TManifest
-  conditions?:            string
-  dependencies?:          TDependencies
-  dependenciesMeta?:      TDependenciesMeta
-  devDependencies?:       TDependencies
-  optionalDependencies?:  TDependencies
-  peerDependencies?:      TDependencies
-  peerDependenciesMeta?:  TDependenciesMeta
-  bin?:                   Record<string, string>
-  engines?:               Record<string, string>
-  funding?:               Record<string, string>
+type ParseOptions = {
+  format?:     FormatId          // skip auto-detect
+  manifests?:  Manifests         // package.jsons keyed by workspace path
+  pmConfig?:   PmConfig          // .npmrc / .yarnrc.yml / pnpm-workspace.yaml / bunfig.toml
+  installDir?: string            // path to node_modules / .pnp.cjs (refinement)
+  cache?:      CacheAdapter      // PM cache (refinement)
+  registry?:   RegistryAdapter   // network access (opt-in)
 }
-```
 
-### `TSnapshotIndex`
-```ts
-export interface TSnapshotIndex {
-  snapshot: TSnapshot
-  entries:  TEntry[]
-  roots:    TEntry[]
-  edges:    [string, string][]
-  tree:       Record<string, {
-    key:      string
-    chunks:   string[]
-    parents:  TEntry[]
-    id:       string
-    name:     string
-    version:  string
-    entry:    TEntry
-    depth:    number // the lowest level where the dep@ver first time occurs
-  }>
-  prod: Set<TEntry>
-  getEntryId ({name, version}: TEntry): string
-  getEntry (name: string, version?: string): TEntry | undefined,
-  getEntryByRange (name: string, range: string): TEntry | undefined
-  getEntryDeps(entry: TEntry): TEntry[]
+type StringifyOptions = {
+  format:        FormatId        // required
+  manifests?:    Manifests
+  pmConfig?:     PmConfig
+  installDir?:   string
+  cache?:        CacheAdapter
+  registry?:     RegistryAdapter
+  onDiagnostic?: (d: Diagnostic) => void
 }
 ```
 
-### Caveats
-* There is an infinite number of `nmtrees` that corresponds to the specified `deptree`, but among them there is a finite set of effective (sufficient) for the target criterion — for example, nesting, size, homogeneity of versions
-* npm1: `optional: true` label is not supported yet
-* yarn berry: no idea how to resolve and inject PnP patches https://github.com/yarnpkg/berry/tree/master/packages/plugin-compat
-* npm2 and npm3 requires `engines` and `funding` data, while yarn* or npm1 does not contain it
-* many `nmtree` projections may correspond to the specified `depgraph`
-* pkg.json `resolutions` and `overrides` directives are completely ignored for now
-* pkg aliases are not _fully_ supported yet [#2](https://github.com/antongolub/lockfile/issues/2#issuecomment-1786613893)
-
-### Snippets
-Extracts all deps by depth:
+`pmConfig` / `installDir` / `cache` / `registry` are progressive
+**refinement opt-ins**: each unlocks more information at higher cost. The
+default succeeds offline, against the lockfile bytes (and `manifests`)
+alone.
+
+### Sub-imports
+
+| Surface | Importable as | Contains |
+|---------|---------------|----------|
+| Root | `@antongolub/lockfile` | `parse`, `stringify`, plus types: `Lockfile`, `FormatId`, `ParseOptions`, `StringifyOptions`, `Manifest`, `Manifests` |
+| Modifiers | `@antongolub/lockfile/modify` | audit-fix, override-pin, license-filter |
+| Registry | `@antongolub/lockfile/registry` | adapters for live npm, file cache, frozen-from-lockfile |
+| Per-format | `@antongolub/lockfile/formats/<id>` | direct access to a single adapter (test surface; not a primary user API) |
+
+### Errors
+
+`parse` / `stringify` throw a single `LockfileError` discriminated by
+`code`:
+
 ```ts
-const getDepsByDepth = (idx: TSnapshotIndex, depth = 0) => Object.values(idx.tree)
-  .filter(({depth: d}) => d === depth)
-  .map(({entry}) => entry)
+'PARSE_FAILED' | 'FORMAT_DETECT_FAILED' | 'FORMAT_MISMATCH'
+| 'CAPABILITY_LACK' | 'MISSING_MANIFEST'
+| 'IRREDUCIBLE_LOSS' | 'INVARIANT_VIOLATION'
 ```
 
-Get the longest dep chain:
-```ts
-const getLongestChain = (): TEntry[] => {
-  let max = 0
-  let chain: TEntry[] = []
-
-  for (const e of Object.values(idx.tree)) {
-    if (e.depth > max) {
-      max = e.depth
-      chain = [...e.parents, e.entry]
-    }
-  }
-  return chain
-}
+Reducible losses (e.g. dropped patches when emitting `npm-1` from a
+yarn-berry source) surface as `Diagnostic` events via the
+`onDiagnostic` callback, not exceptions.
 
-constole.log(
-  getLongestChain()
-    .map((e) => idx.getEntryId(e))
-    .join(' -> ')
-)
-```
+## Schemas
+
+Every recognised lockfile schema is enumerated in
+[SCHEMAS.md](./SCHEMAS.md), with adapter ids, the schema-marker each
+carries, the package-manager versions that emit it by default, and
+permalinked sources. Use that table as the index when calling
+`parse({ format })` or `stringify({ format })`.
 
-### Inspired by
-* [synp](https://github.com/imsnif/synp)
-* [snyk-nodejs-lockfile-parser](https://github.com/snyk/nodejs-lockfile-parser)
-* [yarn](https://github.com/yarnpkg/yarn/blob/master/src/lockfile/parse.js)
-* [yarn-lockfile](https://github.com/yarnpkg/yarn/tree/master/packages/lockfile)
-
-### Refs
-* [yarn.lock](https://classic.yarnpkg.com/en/docs/yarn-lock/)
-* [package-lock-json](https://docs.npmjs.com/cli/v10/configuring-npm/package-lock-json)
-* [what-is-package-lock-json](https://snyk.io/blog/what-is-package-lock-json/)
-* [the-ultimate-guide-to-yarn-lock-lockfiles](https://www.arahansen.com/the-ultimate-guide-to-yarn-lock-lockfiles/)
-* [package-lock-json-the-complete-guide](https://medium.com/helpshift-engineering/package-lock-json-the-complete-guide-2ae40175ebdd)
-<details>
-  <summary>more</summary>
-
-* [cvent/pnpm-lock-export](https://github.com/cvent/pnpm-lock-export)
-* [why-keep-package-lockjson](https://blog.npmjs.org/post/621733939456933888/npm-v7-series-why-keep-package-lockjson.html)
-* [pnpm/lockfile-utils](https://github.com/pnpm/pnpm/tree/main/lockfile/lockfile-utils)
-</details>
+## Predecessor and inspirations
+
+This project is the architectural successor to
+[`yarn-audit-fix`](https://github.com/antongolub/yarn-audit-fix), generalised
+beyond yarn.
+
+Earlier work in this space:
+
+- [synp](https://github.com/imsnif/synp)
+- [snyk-nodejs-lockfile-parser](https://github.com/snyk/nodejs-lockfile-parser)
+- [`@yarnpkg/lockfile`](https://github.com/yarnpkg/yarn/tree/master/packages/lockfile)
+- [`pnpm/lockfile-utils`](https://github.com/pnpm/pnpm/tree/main/lockfile)
+
+## Package-manager docs
+
+- [`package-lock.json`](https://docs.npmjs.com/cli/v10/configuring-npm/package-lock-json)
+  — npm
+- [yarn lockfile (classic)](https://classic.yarnpkg.com/lang/en/docs/yarn-lock/)
+  / [yarn lockfile (berry)](https://github.com/yarnpkg/berry/blob/master/packages/yarnpkg-core/sources/Project.ts)
+- [`pnpm/spec/lockfile/`](https://github.com/pnpm/spec/tree/master/lockfile)
+  — pnpm
+- [bun lockfile](https://bun.com/docs/pm/lockfile) — bun
+
+## Compatibility
+
+- **Node ≥ 20.** No browser build planned.
+- **ESM only.** Consumers on CommonJS use dynamic `await import(…)`.
 
 ## License
+
 [MIT](./LICENSE)

package/SCHEMAS.md

@@ -0,0 +1,120 @@
+# Lockfile schemas
+
+Public reference for every lockfile schema this project recognises:
+how to identify each, which package-manager versions emit it by
+default, and which can install from it. Adapter ids match the
+`FormatId` literal accepted by `parse({ format })` and required by
+`stringify({ format })`.
+
+## npm
+
+| Adapter id | Marker | Default writer | Reader |
+|------------|--------|----------------|--------|
+| `npm-1`    | `lockfileVersion: 1` | npm `>=5 <7` | npm `>=5` |
+| `npm-2`    | `lockfileVersion: 2` | npm `>=7 <9` | npm `>=7` |
+| `npm-3`    | `lockfileVersion: 3` | npm `>=9`    | npm `>=7` |
+
+`npm install --lockfile-version=N` overrides the writer choice within
+the supported range.
+
+## yarn
+
+`yarn-classic` and `yarn-berry-*` use different lockfile schemas. The
+"v" suffix on berry adapters is `__metadata.version`. Yarn classic
+uses a `# yarn lockfile v1` *comment header* instead — unrelated to
+berry's `__metadata`.
+
+| Adapter id        | Marker                       | Default writer       | Reader  |
+|-------------------|------------------------------|----------------------|---------|
+| `yarn-classic`    | `# yarn lockfile v1` header  | yarn `>=1 <2`        | yarn `>=1 <2` (native); yarn `>=2` via `yarn import` |
+| `yarn-berry-v3`   | `__metadata.version: 3`      | yarn `>=2.0.0-rc.4 <2.0.0-rc.20` (pre-release only) | yarn `>=2` |
+| `yarn-berry-v4`   | `__metadata.version: 4`      | yarn `>=2.0.0-rc.20 <3.1` | yarn `>=2` |
+| `yarn-berry-v5`   | `__metadata.version: 5`      | yarn `=3.1.0` (one minor) | yarn `>=3.1` |
+| `yarn-berry-v6`   | `__metadata.version: 6`      | yarn `>=3.2 <4`      | yarn `>=3.2` |
+| `yarn-berry-v8`   | `__metadata.version: 8`      | yarn `>=4.0 <4.14`   | yarn `>=4` |
+| `yarn-berry-v9`   | `__metadata.version: 9`      | yarn `>=4.14`        | yarn `>=4.14` |
+
+**Schema numbers that don't exist:**
+- `__metadata.version: 1` and `2` were never used by berry.
+- `__metadata.version: 7` was skipped — yarn went `6 → 8` in 4.0.0.
+
+`YARN_LOCKFILE_VERSION_OVERRIDE` (yarn 4+) lets one binary write any
+schema version it can read; structural fidelity to the canonical
+writer is not guaranteed.
+
+## pnpm
+
+| Adapter id | Marker                   | Default writer       |
+|------------|--------------------------|----------------------|
+| `pnpm-v5`  | `lockfileVersion: 5.x`   | pnpm `>=3 <8`  (pnpm 7 stayed on `5.4` by default) |
+| `pnpm-v6`  | `lockfileVersion: '6.0'`/`'6.1'` | pnpm `>=8 <9` |
+| `pnpm-v9`  | `lockfileVersion: '9.0'` | pnpm `>=9`           |
+
+**Schema numbers that don't exist:** `7` and `8`. pnpm 9 jumped
+straight from `6.x` to `9.0`.
+
+## bun
+
+| Adapter id    | Marker                          | Default writer | Status |
+|---------------|---------------------------------|----------------|--------|
+| `bun-text`    | `bun.lock` filename + JSONC     | bun `>=1.2`    | primary bun target |
+| `bun-binary`  | `bun.lockb` filename + magic    | bun `<1.2`     | detect-only — not parsed |
+
+`bun-binary` is a **permanent non-goal**: when `parse()` detects
+`bun.lockb` magic bytes it throws with a hint to migrate via bun's
+own tooling (`bun install --save-text-lockfile`). The library handles
+the resulting `bun.lock` via the `bun-text` adapter. bun's own
+binary reader stays in bun for back-compat — that is bun's
+responsibility, not ours.
+
+## Sources
+
+Where each schema is canonically defined. Permalinks pinned at specific
+release tags / commits so claims here stay anchored.
+
+### npm
+
+- [npm v7 series — beta release & semver-major changes](https://blog.npmjs.org/post/626173315965468672/npm-v7-series-beta-release-and-semver-major.html)
+  — introduces `lockfileVersion: 2` (`packages` block, workspaces).
+- [package-lock.json docs (npm v9)](https://docs.npmjs.com/cli/v9/configuring-npm/package-lock-json/)
+  — schema reference for v3.
+- [GitHub: dependency-graph and Dependabot support npm v9](https://github.blog/changelog/2023-03-10-dependency-graph-and-dependabot-support-npm-v9/)
+  — confirms v3 drops the legacy `dependencies` mirror.
+
+### yarn
+
+- [`Project.ts` at @yarnpkg/cli/2.4.3](https://github.com/yarnpkg/berry/blob/@yarnpkg/cli/2.4.3/packages/yarnpkg-core/sources/Project.ts)
+  — `LOCKFILE_VERSION = 4`.
+- [`Project.ts` at @yarnpkg/cli/3.1.0](https://github.com/yarnpkg/berry/blob/@yarnpkg/cli/3.1.0/packages/yarnpkg-core/sources/Project.ts)
+  — `LOCKFILE_VERSION = 5` (one-minor window).
+- [`Project.ts` at @yarnpkg/cli/3.2.0](https://github.com/yarnpkg/berry/blob/@yarnpkg/cli/3.2.0/packages/yarnpkg-core/sources/Project.ts)
+  — `LOCKFILE_VERSION = 6`.
+- [`Project.ts` at @yarnpkg/cli/4.0.0](https://github.com/yarnpkg/berry/blob/@yarnpkg/cli/4.0.0/packages/yarnpkg-core/sources/Project.ts)
+  — bumps to 8; `YARN_LOCKFILE_VERSION_OVERRIDE` env var introduced here.
+- [`Project.ts` at @yarnpkg/cli/4.14.1](https://github.com/yarnpkg/berry/blob/@yarnpkg/cli/4.14.1/packages/yarnpkg-core/sources/Project.ts)
+  — current `LOCKFILE_VERSION = 9`.
+- [Yarn 4.0 release blog](https://yarnpkg.com/blog/release/4.0)
+  — narrative context (no explicit lockfile-bump mention).
+
+### pnpm
+
+- [`pnpm/spec` — lockfile/](https://github.com/pnpm/spec/tree/master/lockfile)
+  — official per-version schema docs (`5.md`, `5.2.md`, `6.0.md`, `9.0.md`).
+- [`pnpm/spec/lockfile/6.0.md`](https://github.com/pnpm/spec/blob/master/lockfile/6.0.md)
+  — pnpm 8's schema, including the package-id grammar shift.
+- [`pnpm/spec/lockfile/9.0.md`](https://github.com/pnpm/spec/blob/master/lockfile/9.0.md)
+  — pnpm 9's `packages` / `snapshots` split.
+- [pnpm Discussion #6857](https://github.com/orgs/pnpm/discussions/6857)
+  — maintainer rationale for the `6 → 9` jump:
+  *"in the future lockfile version will equal the pnpm version in
+  which it got introduced."*
+
+### bun
+
+- [Bun docs — Lockfile](https://bun.com/docs/pm/lockfile)
+  — current schema reference for `bun.lock`.
+- [Bun blog — text-based lockfile](https://bun.com/blog/bun-lock-text-lockfile)
+  — text format introduced in 1.1.39, default in 1.2.
+- [`bun-lock` source](https://github.com/oven-sh/bun) — `src/install/lockfile.zig`
+  for the binary serializer.
+

package/dist/_npm-flat-types-5XRp-_Te.d.ts

@@ -0,0 +1,14 @@
+import { D as Diagnostic } from './graph-DbCmOfBk.js';
+
+interface NpmFamilyParseOptions {
+}
+interface NpmFamilyStringifyOptions {
+    lineEnding?: 'lf' | 'crlf';
+    onDiagnostic?: (diagnostic: Diagnostic) => void;
+}
+interface NpmFamilyEnrichOptions {
+}
+interface NpmFamilyOptimizeOptions {
+}
+
+export type { NpmFamilyEnrichOptions as N, NpmFamilyOptimizeOptions as a, NpmFamilyParseOptions as b, NpmFamilyStringifyOptions as c };

package/dist/_pnpm-flat-core-DtT-PfX-.d.ts

@@ -0,0 +1,37 @@
+import { D as Diagnostic } from './graph-DbCmOfBk.js';
+
+interface PnpmFamilyParseOptions {
+    /**
+     * Filesystem root used by F2 patch-slot extraction (ADR-0014 §4.F2).
+     * When the `overrides:` block carries `patch:<spec>#<workspace-path>`
+     * entries the resolver reads `<workspaceRoot>/<workspace-path>` bytes
+     * and emits the canonical sha512-hex on `Node.patch`. Absent / unreadable
+     * patch sources fall back to the ADR-0011 `unresolved-<sha256-hex>`
+     * sentinel computed from the locator string.
+     */
+    workspaceRoot?: string;
+}
+interface PnpmFamilyStringifyOptions {
+    lineEnding?: 'lf' | 'crlf';
+    settings?: PnpmSettings;
+    onDiagnostic?: (diagnostic: Diagnostic) => void;
+}
+interface PnpmManifest {
+    name?: string;
+    version?: string;
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    optionalDependencies?: Record<string, string>;
+    peerDependencies?: Record<string, string>;
+}
+interface PnpmFamilyEnrichOptions {
+    manifests?: Record<string, PnpmManifest>;
+}
+interface PnpmFamilyOptimizeOptions {
+}
+interface PnpmSettings {
+    autoInstallPeers?: boolean;
+    excludeLinksFromLockfile?: boolean;
+}
+
+export type { PnpmFamilyEnrichOptions as P, PnpmManifest as a, PnpmFamilyOptimizeOptions as b, PnpmFamilyParseOptions as c, PnpmSettings as d, PnpmFamilyStringifyOptions as e };

package/dist/_yarn-berry-core-nexIf1L1.d.ts

@@ -0,0 +1,16 @@
+import { D as Diagnostic } from './graph-DbCmOfBk.js';
+
+interface YarnBerryFamilyParseOptions {
+    workspaceRoot?: string;
+}
+interface YarnBerryFamilyStringifyOptions {
+    lineEnding?: 'lf' | 'crlf';
+    cacheKey?: string;
+    onDiagnostic?: (diagnostic: Diagnostic) => void;
+}
+interface YarnBerryFamilyEnrichOptions {
+}
+interface YarnBerryFamilyOptimizeOptions {
+}
+
+export type { YarnBerryFamilyEnrichOptions as Y, YarnBerryFamilyOptimizeOptions as a, YarnBerryFamilyParseOptions as b, YarnBerryFamilyStringifyOptions as c };

package/dist/complete.d.ts

@@ -0,0 +1,68 @@
+import { N as NodeId, D as Diagnostic, G as Graph, E as EdgeTriple, a as Node, b as EdgeKind } from './graph-DbCmOfBk.js';
+import { R as RegistryAdapter } from './types-Ci06KZkZ.js';
+
+interface CompletionSeed {
+    /** NodeIds the modifier added in the just-completed mutate phase. */
+    recentlyAdded: Set<NodeId>;
+    /** NodeIds the mutate phase orphaned. The completion frontier excludes
+     *  these — optimize phase collects. */
+    recentlyOrphaned: Set<NodeId>;
+}
+interface CompletionResult {
+    graph: Graph;
+    added: NodeId[];
+    wired: EdgeTriple[];
+    unresolved: Diagnostic[];
+}
+interface CompletionOptions {
+    seed?: CompletionSeed;
+    onDiagnostic?: (d: Diagnostic) => void;
+}
+/**
+ * Walk graph, query registry for missing transitive deps, wire edges.
+ * Monotone-additive: returned graph ⊇ input graph (no removals).
+ */
+declare function completeTransitives(graph: Graph, registry: RegistryAdapter, options?: CompletionOptions): Promise<CompletionResult>;
+
+/**
+ * Walk consumer → root via incoming-edge BFS.
+ * Returns nodes in BFS order: consumer first, deeper ancestors last.
+ * Cycles tolerated via `seen`.
+ */
+declare function ancestorsOf(graph: Graph, consumer: NodeId): Node[];
+/**
+ * Find-up resolve per ADR-0023 §5.1.
+ *
+ * Returns the closest-ancestor satisfying node, or undefined if either
+ * (a) no ancestor declares `name` at all → caller may install nested at the
+ *     consumer's level, or
+ * (b) the closest ancestor that declares `name` does so with a conflicting
+ *     range → "block hoist", caller installs nested fallback (npm-3 style).
+ *
+ * Tiebreaker:
+ *   1. Highest semver-comparable version wins (`semver.rcompare`).
+ *   2. On version tie, lowest NodeId lex order wins.
+ *
+ * `depKind` is part of the §5.1 normative signature but does NOT affect the
+ * algorithm body in v1: every dep-kind (dep / dev / optional / peer) follows
+ * the same closest-ancestor reuse + block-hoist contract. The parameter is
+ * carried verbatim so future kind-filtered hoist policies (e.g. peer-deps
+ * needing a stricter find-up, or optional-deps allowed to silently fail
+ * differently from regular deps) can branch on it without a signature
+ * migration. Per the ADR §5.1 pseudocode body and the v1 normative scope, no
+ * kind-specific branch is taken yet.
+ */
+declare function resolveFindUp(graph: Graph, consumerId: NodeId, name: string, range: string, depKind: EdgeKind): NodeId | undefined;
+
+type CompletionDiagnosticCode = 'COMPLETION_NODE_ADDED' | 'COMPLETION_EDGE_RESOLVED' | 'COMPLETION_UNRESOLVED' | 'COMPLETION_NODE_UNKNOWN' | 'COMPLETION_VERSION_UNKNOWN' | 'COMPLETION_PEER_CONTEXT_INCOMPLETE';
+interface CompletionDiagnostic extends Diagnostic {
+    code: CompletionDiagnosticCode;
+}
+declare function completionNodeAdded(nodeId: NodeId): CompletionDiagnostic;
+declare function completionEdgeResolved(triple: EdgeTriple): CompletionDiagnostic;
+declare function completionUnresolved(consumer: NodeId, depName: string, depRange: string): CompletionDiagnostic;
+declare function completionNodeUnknown(nodeId: NodeId): CompletionDiagnostic;
+declare function completionVersionUnknown(nodeId: NodeId): CompletionDiagnostic;
+declare function completionPeerContextIncomplete(nodeId: NodeId, peerName: string, peerRange: string): CompletionDiagnostic;
+
+export { type CompletionDiagnostic, type CompletionDiagnosticCode, type CompletionOptions, type CompletionResult, type CompletionSeed, ancestorsOf, completeTransitives, completionEdgeResolved, completionNodeAdded, completionNodeUnknown, completionPeerContextIncomplete, completionUnresolved, completionVersionUnknown, resolveFindUp };