@antongolub/lockfile 0.0.0-snapshot.7 → 0.0.0-snapshot.71

package/README.md

@@ -1,114 +1,193 @@
-# lockfile
-> Read and write lockfiles with reasonable losses
+# @antongolub/lockfile
 
-## Motivation
-Each package manager brings its own philosophy of how to describe, store and control project dependencies.
-It _seems_ acceptable for developers, but literally becomes a ~~pain in *** ***~~ 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**.
 
-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/other format.
+<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. Inside a single repo it's invisible to the
+developer — but it becomes a recurring cost for InfoSec, DevOps and release
+engineers, and makes consistent policy unenforceable across the enterprise.
+
+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.
+
+</p>
 
 ## Status
-⚠️ Initial draft. Alpha-version
 
-## Getting started
-### Install
-```shell
-yarn add @antongolub/lockfile
+**Snapshot preview.** Every format below parses and stringifies; conversion is
+*semantically equivalent*, not byte-identical (see [Concept](#concept)).
+Published as `0.0.0-snapshot.*` builds — the first stable release is pending.
+[SCHEMAS.md](./SCHEMAS.md) maps each format id to the package-manager versions
+that emit it.
+
+> **ℹ️ Active R&D — snapshot channel.** While the project is under active research &
+> development, every release ships to the **snapshot channel** (`0.0.0-snapshot.N`,
+> published under the `snapshot` npm dist-tag) rather than `latest`. Install the newest
+> snapshot with `npm i @antongolub/lockfile@snapshot`, or pin an exact build
+> (e.g. `npm i @antongolub/lockfile@0.0.0-snapshot.61`). The first stable `latest`
+> release is pending.
+
+| Format | `detect` | `parse` | `stringify` |
+|--------|:-:|:-:|:-:|
+| `npm-1` · `npm-2` · `npm-3`        | ✓ | ✓ | ✓ |
+| `yarn-classic`                    | ✓ | ✓ | ✓ |
+| `yarn-berry-v4` … `yarn-berry-v10`| ✓ | ✓ | ✓ |
+| `pnpm-v5` · `pnpm-v6` · `pnpm-v9`  | ✓ | ✓ | ✓ |
+| `bun-text`                        | ✓ | ✓ | ✓ |
+
+Graph-level operations apply to **any** parsed graph, regardless of source
+format: `convert` (parse any → stringify any), `modify` (audit-fix,
+override-pin, license-filter), and `optimize` (orphan GC / dedup).
+
+## Concept
+
+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.
+
+Three layers, never collapsed:
+
+- **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
+
+```ts
+import { parse, stringify, convert } from '@antongolub/lockfile'
+
+// explicit format (it's always the first argument):
+const graph = parse('pnpm-v9', raw)
+const out   = stringify('npm-3', graph)
+
+// or one step, auto-detecting the source:
+const npm = convert(raw, { to: 'npm-3' })
 ```
 
-## Usage
+The format is **explicit**, never implicit — `parse` and `stringify` both take
+it as the first argument; `detect` sniffs it from the bytes when you don't know
+it. Round-tripping is a choice the caller makes, not a default.
+
 ```ts
-import { parse, format, analyze } from '@antongolub/lockfile'
+detect(input: string): FormatId | undefined
+check(format: FormatId, input: string): boolean
+parse(format: FormatId, input: string, opts?: ParseOptions): Graph
+stringify(format: FormatId, graph: Graph, opts?: StringifyOptions): string
+convert(input: string, opts: ConvertOptions): string   // parse(from) → stringify(to)
+```
+
+`Graph` is the canonical, package-manager-independent model; `FormatId` is a
+string-literal union (the [Status](#status) table lists every id, and
+[SCHEMAS.md](./SCHEMAS.md) maps each to the package-manager versions behind it).
+
+### Operating on the graph
 
-const snapshot = parse('yarn.lock <raw contents>', 'package.json <raw contents>', './packages/foo/package.json <raw contents>')
+The graph is where the value lives — `modify` and `optimize` transform it,
+format-agnostically:
 
-const lf = format(snapshot)
-const lf2 = format(snapshot, 'npm-1')         // Throws err: npm v1 meta does not support workspaces
+- **`modify`** applies a `Primitive[]` — `replaceVersion`, `pinOverride`,
+  `addDependency`, `removeDependency`, `applyPatch`, `filterLicense` — the
+  building blocks of audit-fix, override-pinning and license filtering.
+- **`optimize`** runs orphan GC / dedup over the graph.
+- **`overridesOf(graph)`** reads the canonical overrides back out.
 
-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
+### Options
 
-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
+type ParseOptions = {
+  workspaceRoot?: string                     // FS root for out-of-lockfile reads (patch bytes, manifests)
+  manifests?:     Record<string, Manifest>   // package.jsons keyed by workspace path
+  onDiagnostic?:  (d: Diagnostic) => void
+}
+
+type StringifyOptions = {
+  lineEnding?:   'lf' | 'crlf'
+  cacheKey?:     string                       // yarn-berry cache-key prefix
+  overrides?:    OverrideConstraint[]         // canonical overrides → native projection
+  onDiagnostic?: (d: Diagnostic) => void
+}
 ```
 
-### 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 formats
-| Package manager  | Meta format | Read | Write |
-|------------------|-------------|------|-------|
-| npm <7           | 1           | ✓    | ✓     |
-| npm >=7          | 2           | ✓    |       |
-| npm >=9          | 3           | ✓    |       | 
-| yarn 1 (classic) | 1           | ✓    | ✓     |
-| yarn 2 (berry)   | 5, 6, 7     | ✓    | ✓     |
-
-### Reference protocols
-| Type      | Supported |
-|-----------|-----------|
-| semver    | ✓         |
-| npm       | ✓         |
-| workspace |           |
-| patch     |           |
-| file      |           |
-| github    |           |
-| tag       |           |
-
-https://yarnpkg.com/features/protocols
-
-### `TSnapshot`
+`manifests` supplies the workspace/override context the lockfile bytes cannot
+carry on their own (notably for `yarn-classic` monorepos); everything else
+succeeds offline against the bytes alone. Registry- and cache-backed refinement
+ships as opt-in adapters (see [Sub-imports](#sub-imports)).
+
+### Sub-imports
+
+| Surface | Importable as | Contains |
+|---------|---------------|----------|
+| Root | `@antongolub/lockfile` | `detect`, `check`, `parse`, `stringify`, `convert`, `modify`, `optimize`, `overridesOf`, plus types `Graph`, `FormatId`, `ParseOptions`, `StringifyOptions`, `ConvertOptions`, `Manifest` |
+| Modifiers | `@antongolub/lockfile/modify` | the individual `Primitive` functions behind `modify` (audit-fix, override-pin, license-filter) |
+| Optimize | `@antongolub/lockfile/optimize` | the individual GC passes behind `optimize` |
+| Registry | `@antongolub/lockfile/registry` | `frozenRegistry`, `liveRegistry`, `fsCache`, `npmCache`, `pnpmCache` |
+| Per-format | `@antongolub/lockfile/formats/<id>` | a single adapter directly (test surface; not a primary user API) |
+
+### Errors
+
+`parse` / `stringify` throw a single `LockfileError` discriminated by
+`code`:
+
 ```ts
-export type TSnapshot = Record<string, {
-  name:       string
-  version:    string
-  ranges:     string[]
-  hashes:     {
-    sha512?:  string
-    sha256?:  string
-    sha1?:    string
-    checksum?: string
-    md5?:     string
-  }
-  source:     string
-  sourceType: TSourceType
-
-  // optional pm-specific lockfile meta
-  manifest?: TManifest
-  conditions?: string
-  dependencies?: TDependencies
-  dependenciesMeta?: TDependenciesMeta
-  optionalDependencies?: TDependencies
-  peerDependencies?: TDependencies
-  peerDependenciesMeta?: TDependenciesMeta
-  bin?: Record<string, string>
-  engines?: Record<string, string>
-  funding?: Record<string, string>
-}>
+'PARSE_FAILED' | 'FORMAT_DETECT_FAILED' | 'FORMAT_MISMATCH'
+| 'CAPABILITY_LACK' | 'MISSING_MANIFEST' | 'MISSING_REQUIRED_FIELD'
+| 'INVALID_INPUT' | 'ENRICH_REQUIRED' | 'IRREDUCIBLE_LOSS'
+| 'PIPELINE_DIVERGED' | 'REGISTRY_UNREACHABLE' | 'INVARIANT_VIOLATION'
 ```
 
-### 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 by `format`
-* 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 the specified `depgraph`
+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.
+
+## 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 })`.
+
+## 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(…)`.
 
-### Inspired by
-* [synp](https://github.com/imsnif/synp)
-* [snyk-nodejs-lockfile-parser](https://github.com/snyk/nodejs-lockfile-parser)
+## License
 
-### License
 [MIT](./LICENSE)

package/SCHEMAS.md

@@ -0,0 +1,121 @@
+# 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` |
+| `yarn-berry-v10`  | `__metadata.version: 10`     | yarn 5 (dev branch)  | yarn 5+ (preview — reverse-engineered from yarnpkg/berry master) |
+
+**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-CR16JZFS.d.ts

@@ -0,0 +1,18 @@
+import { D as Diagnostic, O as OverrideConstraint } from './graph-CPo-SvS2.js';
+
+interface NpmFamilyParseOptions {
+}
+interface NpmFamilyStringifyOptions {
+    lineEnding?: 'lf' | 'crlf';
+    onDiagnostic?: (diagnostic: Diagnostic) => void;
+    /** Caller-declared overrides (ADR-0025 §4) projected into the root entry's
+     *  `overrides` block at `packages[""]`. npm-1 (no packages block) cannot
+     *  carry them — a loss diagnostic fires instead. */
+    overrides?: OverrideConstraint[];
+}
+interface NpmFamilyEnrichOptions {
+}
+interface NpmFamilyOptimizeOptions {
+}
+
+export type { NpmFamilyEnrichOptions as N, NpmFamilyOptimizeOptions as a, NpmFamilyParseOptions as b, NpmFamilyStringifyOptions as c };

package/dist/_pnpm-flat-core-DmGs4UQu.d.ts

@@ -0,0 +1,41 @@
+import { D as Diagnostic, O as OverrideConstraint } from './graph-CPo-SvS2.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;
+    /** Caller-declared overrides (ADR-0025 §4) overlaid onto the pnpm
+     *  `overrides:` block. Caller wins per key; pre-existing `patch:` directives
+     *  (F2) survive on collision. */
+    overrides?: OverrideConstraint[];
+}
+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-BhE-AhmX.d.ts

@@ -0,0 +1,19 @@
+import { O as OverrideConstraint, D as Diagnostic } from './graph-CPo-SvS2.js';
+
+interface YarnBerryFamilyParseOptions {
+    workspaceRoot?: string;
+    overrides?: OverrideConstraint[];
+}
+interface YarnBerryFamilyStringifyOptions {
+    lineEnding?: 'lf' | 'crlf';
+    cacheKey?: string;
+    onDiagnostic?: (diagnostic: Diagnostic) => void;
+}
+interface YarnBerryFamilyEnrichOptions {
+    workspaceRoot?: string;
+    peerMetaResolver?: (parentName: string, parentVersion: string, peerName: string) => boolean | undefined;
+}
+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-CPo-SvS2.js';
+import { R as RegistryAdapter } from './types-BPMSHpCF.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 };