@effected/lockfiles 0.1.0

package/README.md

@@ -0,0 +1,109 @@
+# @effected/lockfiles
+
+[![npm](https://img.shields.io/npm/v/@effected%2Flockfiles?label=npm&color=cb3837)](https://www.npmjs.com/package/@effected/lockfiles)
+[![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
+[![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
+[![TypeScript 6.0](https://img.shields.io/badge/TypeScript-6.0-3178c6.svg)](https://www.typescriptlang.org/)
+
+Lockfile parsing for [Effect](https://effect.website) v4: bun (`bun.lock`), npm (`package-lock.json` v2/v3), pnpm (`pnpm-lock.yaml`) and yarn Berry (`yarn.lock`) all normalized into one `Lockfile` schema model, plus pure integrity checking of that model against workspace manifests. Four formats, one model, no IO and no external runtime dependencies.
+
+> **Pre-release.** This package is part of the `@effected/*` kit, in pre-`1.0.0`
+> development against a single pinned Effect v4 beta. Packages graduate to
+> `1.0.0` once Effect `4.0.0` ships. To hold your own `effect` versions at
+> exactly the ones the kit is built and tested against, install
+> [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
+>
+> **Stability: unstable.** This package's API surface is not yet considered
+> complete and may change across `0.x` releases. Pin an exact version — even a
+> package marked *stable* before `1.0.0` can introduce a breaking change by
+> accident, and an exact pin turns that into a type-check error rather than a
+> runtime surprise. Full policy: [release strategy](https://github.com/spencerbeggs/effected#release-strategy).
+
+## Why @effected/lockfiles
+
+Every package manager writes its lockfile in a different dialect — JSONC for bun, JSON for npm, YAML for pnpm and yarn — and each encodes packages, workspace edges and integrity data differently. Tooling that wants to answer "which version of `typescript` is resolved here" ends up with four code paths and four sets of bugs. This package normalizes all four into one model, so the question is asked once regardless of which package manager produced the file.
+
+Every entrypoint takes content as a **string**. The package performs no IO at all: reading files, finding workspace roots and detecting which package manager a repo uses belong to its consumers, and keeping them out means the parser is a pure function you can drive from a fixture, a network response or a git blob. Malformed input always exits through a typed error channel, never as a defect, and the two ways a lockfile can be unusable are distinct tags rather than one blurry `reason` string. Yarn support is Berry only, and that is enforced: classic v1 content fails typed instead of being mis-normalized into something that looks plausible.
+
+## Install
+
+```bash
+npm install @effected/lockfiles @effected/jsonc @effected/semver @effected/yaml effect
+```
+
+```bash
+pnpm add @effected/lockfiles @effected/jsonc @effected/semver @effected/yaml effect
+```
+
+Requires Node.js >=24.11.0. `effect` v4, `@effected/jsonc`, `@effected/semver` and `@effected/yaml` are peer dependencies — the JSONC and YAML engines and the SemVer range checker all arrive through those siblings, so nothing outside `effect` and `@effected/*` reaches your tree. Package managers that install peers automatically will pull them in; add them to your manifest explicitly if yours does not.
+
+## Quick start
+
+```ts
+import { Lockfile, LockfileIntegrity, WorkspaceManifest } from "@effected/lockfiles";
+import { Effect } from "effect";
+
+declare const content: string; // lockfile text, read by the caller
+
+const program = Effect.gen(function* () {
+  // The only fallible boundary in the package.
+  const lockfile = yield* Lockfile.parse(content, { format: "pnpm" });
+
+  // pnpm workspace packages come back keyed by importer path; rewrite them
+  // once you have read the manifests. Total and pure — no error channel.
+  const named = lockfile.withImporterNames(new Map([["packages/core", "@acme/core"]]));
+
+  // Total lookups over the model.
+  const versions = named.packagesNamed("typescript").map((p) => p.version);
+
+  // Pure integrity checking — no Effect, no error channel, no IO.
+  const report = LockfileIntegrity.compare(named, [
+    WorkspaceManifest.make({ name: "@acme/core", dependencies: { lodash: "^4.17.0" } }),
+  ]);
+
+  return { versions, workspaces: named.workspacePackages.length, valid: report.valid };
+});
+
+Effect.runPromise(program).then(console.log);
+// { versions: [...resolved typescript versions], workspaces: <count>, valid: true | false }
+```
+
+## Formats
+
+`format` is a literal, and `filenameFor` / `fromFilename` map between the literal and the file on disk so a consumer that detected a package manager never has to hard-code a filename.
+
+| Format | Filename | Dialect | Notes |
+| ------ | -------- | ------- | ----- |
+| `"bun"` | `bun.lock` | JSONC | Trusted dependencies preserved on `BunExtension` |
+| `"npm"` | `package-lock.json` | JSON | v2 and v3 |
+| `"pnpm"` | `pnpm-lock.yaml` | YAML | Catalogs preserved on `PnpmExtension`; see below |
+| `"yarn"` | `yarn.lock` | YAML | Berry only — classic v1 fails typed |
+
+## Errors
+
+`Lockfile.parse` is the only fallible entrypoint, and it fails two ways.
+
+| Tag | Means | Fields |
+| --- | ----- | ------ |
+| `LockfileParseError` | The content is not a valid lockfile of that format. | `format`, `stage` (`"syntax"` when the text itself did not parse, `"validation"` when it parsed but did not have the expected shape), `cause` (structural, never stringified) |
+| `LockfileFramingError` | The text parsed, but no single lockfile document could be located in it. | `format`, `documents`, `reason` (`"noLockfileDocument"`, `"noImporters"`, `"unexpectedDocuments"`) |
+
+The framing error exists because `pnpm-lock.yaml` is a YAML **stream**, not a YAML document. pnpm 11 writes a config-dependencies preamble ahead of the lockfile whenever a workspace uses `configDependencies`, so the file carries two documents — and the preamble declares `lockfileVersion`, `importers` and `packages` too, so a parser that reads only the first document gets a lockfile that *validates* and describes an empty workspace. That is a wrong answer shaped exactly like a right one. The rule here is positional and deterministic rather than a heuristic: pnpm composes the preamble as a prefix, so the lockfile is the **last** document. A stream carrying no lockfile document fails typed. It never degrades into an empty `Lockfile`.
+
+yarn defines no document framing at all, so multi-document `yarn.lock` content fails with `"unexpectedDocuments"` rather than being silently truncated to its first document. Where a format states no rule, this package refuses to guess.
+
+## Features
+
+- `Lockfile.parse(content, { format })` — the package's only fallible boundary; fails with `LockfileParseError` or `LockfileFramingError`.
+- `Lockfile#withImporterNames(names)` — the pure second stage for pnpm: rewrites importer-path names and both ends of each dependency edge once the consumer has read the manifests.
+- `Lockfile#packagesNamed(name)` and `Lockfile#workspacePackages` — total lookups over the model.
+- `LockfileFormat` with `filenameFor` / `fromFilename` — the format literal and its mapping to lockfile filenames.
+- `LockfileIntegrity.compare(lockfile, manifests)` — total, pure integrity checking with no error channel; the report carries `valid`, `missingWorkspaces`, `extraWorkspaces` and `unsatisfiedConstraints`. Constraint checking is best-effort by design: `workspace:` / `link:` / `file:` specifiers and rows whose range does not parse as SemVer are skipped.
+- `WorkspaceManifest` — the manifest input shape for integrity checking: a package name plus four optional dependency records. Deliberately a plain value rather than a strict manifest model, so consumers can derive it from anything.
+- `ResolvedPackage` — name, version, optional integrity hash, workspace flag and relative path, dependency map.
+- `WorkspaceDependency` and `DependencyType` — a `from`/`to` edge between workspace packages with its dependency type and constraint.
+- `PnpmExtension` and `BunExtension` — format-specific data such as pnpm catalogs and bun trusted dependencies, preserved on the model's optional `extension` field.
+
+## License
+
+[MIT](LICENSE)

package/ResolvedPackage.js

@@ -0,0 +1,40 @@
+import { Effect, Schema } from "effect";
+import { IntegrityHash } from "@effected/npm";
+
+//#region src/ResolvedPackage.ts
+const EMPTY_DEPENDENCIES = {};
+/**
+* A package resolved from a lockfile.
+*
+* @remarks
+* The common shape every format's entries normalize into:
+*
+* - `name` — the resolved package name. For pnpm *workspace* packages
+*   straight out of `Lockfile.parse` this is the importer path until
+*   `Lockfile#withImporterNames` rewrites it.
+* - `version` — the resolved version string (pnpm workspace packages carry
+*   `"0.0.0"`; the lockfile does not record their real versions).
+* - `integrity` — optional `@effected/npm` `IntegrityHash`, covering npm/pnpm
+*   `sha512-...` SRI and yarn Berry's `10c0/...` cache checksums (the yarn
+*   textual form). An *absent* integrity is omitted, so a `ResolvedPackage` may
+*   carry none; a *present but unparseable* integrity fails the parse typed at
+*   validation rather than being silently dropped.
+* - `isWorkspace` — `true` for workspace-local packages.
+* - `relativePath` — the workspace-relative directory for workspace
+*   packages, when the lockfile records one.
+* - `dependencies` — the package's own dependency map, defaulting to `{}`
+*   both at construction and when decoding serialized data.
+*
+* @public
+*/
+var ResolvedPackage = class extends Schema.Class("ResolvedPackage")({
+	name: Schema.NonEmptyString,
+	version: Schema.String,
+	integrity: Schema.optionalKey(IntegrityHash),
+	isWorkspace: Schema.Boolean,
+	relativePath: Schema.optionalKey(Schema.String),
+	dependencies: Schema.Record(Schema.String, Schema.String).pipe(Schema.withDecodingDefaultKey(Effect.succeed(EMPTY_DEPENDENCIES)), Schema.withConstructorDefault(Effect.succeed(EMPTY_DEPENDENCIES)))
+}) {};
+
+//#endregion
+export { ResolvedPackage };

package/WorkspaceDependency.js

@@ -0,0 +1,27 @@
+import { Schema } from "effect";
+import { DependencyField } from "@effected/npm";
+
+//#region src/WorkspaceDependency.ts
+/**
+* A directed dependency edge between two workspace packages as recorded in
+* the lockfile.
+*
+* @remarks
+* - `from` — the workspace package declaring the dependency. For pnpm this
+*   is the importer path until `Lockfile#withImporterNames` rewrites it.
+* - `to` — the workspace package depended upon.
+* - `depType` — which dependency map holds the edge, spelled with
+*   `@effected/npm`'s kit-wide `DependencyField` vocabulary.
+* - `constraint` — the declared specifier (e.g. `"workspace:*"`, `"^1.0.0"`).
+*
+* @public
+*/
+var WorkspaceDependency = class extends Schema.Class("WorkspaceDependency")({
+	from: Schema.NonEmptyString,
+	to: Schema.NonEmptyString,
+	depType: DependencyField,
+	constraint: Schema.String
+}) {};
+
+//#endregion
+export { WorkspaceDependency };

package/index.d.ts

@@ -0,0 +1,457 @@
+import { Effect, Option, Schema } from "effect";
+//#region src/BunExtension.d.ts
+declare const BunExtension_base: Schema.Class<BunExtension, Schema.Struct<{
+  readonly _tag: Schema.tag<"bun">;
+  readonly catalog: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
+  readonly catalogs: Schema.optionalKey<Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.Unknown>>>;
+  readonly overrides: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+  readonly trustedDependencies: Schema.optionalKey<Schema.$Array<Schema.String>>;
+}>, {}>;
+/**
+ * Extension data specific to bun lockfiles, attached to `Lockfile.extension`
+ * when the format is `"bun"`.
+ *
+ * @remarks
+ * - `catalog` — the default (unnamed) catalog.
+ * - `catalogs` — named catalog definitions.
+ * - `overrides` — the version override map.
+ * - `trustedDependencies` — packages allowed to run install scripts.
+ *
+ * @public
+ */
+declare class BunExtension extends BunExtension_base {}
+//#endregion
+//#region src/ImporterDependency.d.ts
+declare const ImporterDependency_base: Schema.Class<ImporterDependency, Schema.Struct<{
+  readonly name: Schema.NonEmptyString;
+  readonly specifier: Schema.Codec<import("@effected/npm").ClassifiedSpecifier, string, never, never>;
+  readonly version: Schema.optionalKey<Schema.String>;
+  readonly depType: Schema.Literals<readonly ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"]>;
+}>, {}>;
+/**
+ * One declared dependency of one workspace importer, as the lockfile records it.
+ *
+ * @remarks
+ * - `name` — the dependency's package name.
+ * - `specifier` — the declared range, typed through `@effected/npm`'s
+ *   `DependencySpecifier.FromString` codec: the decoded value is a tag-matchable
+ *   `ClassifiedSpecifier` (`catalog:` / `workspace:` / range / dist-tag / raw),
+ *   while encoding round-trips the **exact original string byte-for-byte** — the
+ *   guarantee a before/after lockfile diff relies on.
+ * - `version` — the concrete resolved version, **populated by pnpm only**. pnpm
+ *   records `{ specifier, version }` per importer dependency; bun and npm record
+ *   resolved versions on their package entries instead, so for those formats
+ *   `version` is absent and a consumer joins by `name` against
+ *   `Lockfile.packages`.
+ * - `depType` — which dependency map declared it, spelled with `@effected/npm`'s
+ *   kit-wide `DependencyField` vocabulary.
+ *
+ * @public
+ */
+declare class ImporterDependency extends ImporterDependency_base {}
+//#endregion
+//#region src/LockfileFormat.d.ts
+/**
+ * The lockfile formats this package parses: bun's `bun.lock` (JSONC), npm's
+ * `package-lock.json` (v2/v3 JSON), pnpm's `pnpm-lock.yaml` and yarn Berry's
+ * `yarn.lock` (both YAML).
+ *
+ * @remarks
+ * The literal names the *lockfile format*, not the package manager that
+ * happens to write it — this package models lockfiles. Yarn support is
+ * Berry only; classic (v1) `yarn.lock` is not YAML and fails
+ * `Lockfile.parse` with a typed `LockfileParseError`.
+ *
+ * @public
+ */
+declare const LockfileFormat: Schema.Literals<readonly ["bun", "npm", "pnpm", "yarn"]>;
+/**
+ * The union of supported lockfile format names.
+ *
+ * @public
+ */
+type LockfileFormat = typeof LockfileFormat.Type;
+/**
+ * The conventional lockfile filename for a format: `"bun.lock"`,
+ * `"package-lock.json"`, `"pnpm-lock.yaml"` or `"yarn.lock"`.
+ *
+ * @public
+ */
+declare const filenameFor: (format: LockfileFormat) => string;
+/**
+ * The format a lockfile filename identifies, if any.
+ *
+ * @remarks
+ * Matches exact conventional filenames only (`"bun.lock"`,
+ * `"package-lock.json"`, `"pnpm-lock.yaml"`, `"yarn.lock"`) — paths and
+ * other spellings return `Option.none()`.
+ *
+ * @public
+ */
+declare const fromFilename: (name: string) => Option.Option<LockfileFormat>;
+//#endregion
+//#region src/LockfileImporter.d.ts
+declare const LockfileImporter_base: Schema.Class<LockfileImporter, Schema.Struct<{
+  readonly path: Schema.NonEmptyString;
+  readonly dependencies: Schema.$Array<typeof ImporterDependency>;
+}>, {}>;
+/**
+ * One workspace importer's declared dependencies, as the lockfile records them.
+ *
+ * @remarks
+ * - `path` — the importer path relative to the workspace root, `"."` for the
+ *   root package (never empty — a `NonEmptyString`) — the same keys as
+ *   `WorkspaceDiscovery.importerMap()` in
+ *   `@effected/workspaces`. This is the stable join key: `Lockfile#importer`
+ *   looks importers up by it, and `Lockfile#withImporterNames` deliberately
+ *   leaves importers untouched because the path — not a package name — keys
+ *   them.
+ * - `dependencies` — each declared dependency as an {@link ImporterDependency}.
+ *
+ * Populated by the pnpm, bun and npm parsers. yarn does not record importers,
+ * so a yarn lockfile always yields an empty `importers` array.
+ *
+ * @public
+ */
+declare class LockfileImporter extends LockfileImporter_base {}
+//#endregion
+//#region src/PnpmExtension.d.ts
+/**
+ * The pnpm `catalogs:` record shape as it appears in `pnpm-lock.yaml`:
+ * catalog name → package name → pinned version string or
+ * `{ specifier, version }` pair.
+ *
+ * @remarks
+ * Exported so consumers (e.g. a `CatalogSet.fromLockfileCatalogs`) can type
+ * against the lockfile's own shape instead of re-declaring it.
+ *
+ * @public
+ */
+type PnpmCatalogs = Record<string, Record<string, string | {
+  readonly specifier: string;
+  readonly version: string;
+}>>;
+declare const PnpmExtension_base: Schema.Class<PnpmExtension, Schema.Struct<{
+  readonly _tag: Schema.tag<"pnpm">;
+  readonly catalogs: Schema.optionalKey<Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Struct<{
+    readonly specifier: Schema.String;
+    readonly version: Schema.String;
+  }>]>>>>;
+  readonly overrides: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+  readonly settings: Schema.optionalKey<Schema.Struct<{
+    readonly autoInstallPeers: Schema.optionalKey<Schema.Boolean>;
+    readonly excludeLinksFromLockfile: Schema.optionalKey<Schema.Boolean>;
+  }>>;
+}>, {}>;
+/**
+ * Extension data specific to pnpm lockfiles, attached to `Lockfile.extension`
+ * when the format is `"pnpm"`.
+ *
+ * @remarks
+ * - `catalogs` — pnpm catalog definitions ({@link PnpmCatalogs}).
+ * - `overrides` — the version override map recorded in the lockfile header.
+ * - `settings` — pnpm settings recorded in the lockfile header.
+ *
+ * @public
+ */
+declare class PnpmExtension extends PnpmExtension_base {}
+//#endregion
+//#region src/ResolvedPackage.d.ts
+declare const ResolvedPackage_base: Schema.Class<ResolvedPackage, Schema.Struct<{
+  readonly name: Schema.NonEmptyString;
+  readonly version: Schema.String;
+  readonly integrity: Schema.optionalKey<Schema.brand<Schema.String, "IntegrityHash"> & {
+    isSri: (value: string) => boolean;
+    isCorepack: (value: string) => boolean;
+    isYarnChecksum: (value: string) => boolean;
+    isValid: (value: string) => boolean;
+    algorithmOf: (value: string) => import("effect/Option").Option<import("@effected/npm").IntegrityAlgorithm>;
+    decode: (input: string) => Effect.Effect<import("@effected/npm").IntegrityHashBrand, import("@effected/npm").InvalidIntegrityHashError>;
+  }>;
+  readonly isWorkspace: Schema.Boolean;
+  readonly relativePath: Schema.optionalKey<Schema.String>;
+  readonly dependencies: Schema.withConstructorDefault<Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.String>, never>>;
+}>, {}>;
+/**
+ * A package resolved from a lockfile.
+ *
+ * @remarks
+ * The common shape every format's entries normalize into:
+ *
+ * - `name` — the resolved package name. For pnpm *workspace* packages
+ *   straight out of `Lockfile.parse` this is the importer path until
+ *   `Lockfile#withImporterNames` rewrites it.
+ * - `version` — the resolved version string (pnpm workspace packages carry
+ *   `"0.0.0"`; the lockfile does not record their real versions).
+ * - `integrity` — optional `@effected/npm` `IntegrityHash`, covering npm/pnpm
+ *   `sha512-...` SRI and yarn Berry's `10c0/...` cache checksums (the yarn
+ *   textual form). An *absent* integrity is omitted, so a `ResolvedPackage` may
+ *   carry none; a *present but unparseable* integrity fails the parse typed at
+ *   validation rather than being silently dropped.
+ * - `isWorkspace` — `true` for workspace-local packages.
+ * - `relativePath` — the workspace-relative directory for workspace
+ *   packages, when the lockfile records one.
+ * - `dependencies` — the package's own dependency map, defaulting to `{}`
+ *   both at construction and when decoding serialized data.
+ *
+ * @public
+ */
+declare class ResolvedPackage extends ResolvedPackage_base {}
+//#endregion
+//#region src/WorkspaceDependency.d.ts
+declare const WorkspaceDependency_base: Schema.Class<WorkspaceDependency, Schema.Struct<{
+  readonly from: Schema.NonEmptyString;
+  readonly to: Schema.NonEmptyString;
+  readonly depType: Schema.Literals<readonly ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"]>;
+  readonly constraint: Schema.String;
+}>, {}>;
+/**
+ * A directed dependency edge between two workspace packages as recorded in
+ * the lockfile.
+ *
+ * @remarks
+ * - `from` — the workspace package declaring the dependency. For pnpm this
+ *   is the importer path until `Lockfile#withImporterNames` rewrites it.
+ * - `to` — the workspace package depended upon.
+ * - `depType` — which dependency map holds the edge, spelled with
+ *   `@effected/npm`'s kit-wide `DependencyField` vocabulary.
+ * - `constraint` — the declared specifier (e.g. `"workspace:*"`, `"^1.0.0"`).
+ *
+ * @public
+ */
+declare class WorkspaceDependency extends WorkspaceDependency_base {}
+//#endregion
+//#region src/Lockfile.d.ts
+declare const LockfileParseError_base: Schema.Class<LockfileParseError, Schema.TaggedStruct<"LockfileParseError", {
+  readonly format: Schema.Literals<readonly ["bun", "npm", "pnpm", "yarn"]>;
+  readonly stage: Schema.Literals<readonly ["syntax", "validation"]>;
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Failure of `Lockfile.parse`: the given content is not a valid lockfile of
+ * the requested format.
+ *
+ * @remarks
+ * - `format` — which format was being parsed.
+ * - `stage` — `"syntax"` when the text itself failed to parse (YAML, JSON,
+ *   JSONC), `"validation"` when the text parsed but did not have the
+ *   format's expected shape.
+ * - `cause` — the underlying jsonc/yaml/JSON/Schema error, preserved
+ *   structurally.
+ *
+ * Malformed input always exits through this typed failure, never as a
+ * defect. Parse takes content, not a path — the caller that did the IO owns
+ * any path context.
+ *
+ * @public
+ */
+declare class LockfileParseError extends LockfileParseError_base {
+  get message(): string;
+}
+declare const LockfileFramingError_base: Schema.Class<LockfileFramingError, Schema.TaggedStruct<"LockfileFramingError", {
+  readonly format: Schema.Literals<readonly ["bun", "npm", "pnpm", "yarn"]>;
+  readonly reason: Schema.Literals<readonly ["noLockfileDocument", "noImporters", "unexpectedDocuments"]>;
+  readonly documents: Schema.Int;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Failure of `Lockfile.parse`: the content parsed as text, but no single
+ * lockfile document could be located in it.
+ *
+ * @remarks
+ * `pnpm-lock.yaml` is a YAML **stream**. pnpm 11 writes a
+ * config-dependencies preamble document ahead of the lockfile whenever the
+ * workspace uses `configDependencies`, so the file holds two documents. The
+ * lockfile is the last one — pnpm composes the preamble as a prefix — and a
+ * parser that reads only the first document gets the preamble: a document
+ * that *validates*, and yields a lockfile with an empty workspace. This error
+ * exists so that case can never again succeed quietly.
+ *
+ * - `format` — which format was being parsed.
+ * - `documents` — how many YAML documents the stream carried.
+ * - `reason`:
+ *   - `"noLockfileDocument"` — the stream carries no lockfile document. An
+ *     env-only `pnpm-lock.yaml` (a config-dependencies preamble and nothing
+ *     after it) reads this way, as does empty content. pnpm itself treats
+ *     such a file as having no lockfile.
+ *   - `"noImporters"` — the located document declares no importers, so it
+ *     describes no workspace. pnpm always records at least the root importer.
+ *   - `"unexpectedDocuments"` — the stream carries several documents in a
+ *     format that defines no document framing (yarn). Rather than silently
+ *     taking the first, parsing refuses to guess.
+ *
+ * It carries typed fields rather than a `cause`: unlike
+ * {@link LockfileParseError}, there is no underlying engine failure to wrap —
+ * the text parsed fine.
+ *
+ * @public
+ */
+declare class LockfileFramingError extends LockfileFramingError_base {
+  get message(): string;
+}
+declare const Lockfile_base: Schema.Class<Lockfile, Schema.Struct<{
+  readonly format: Schema.Literals<readonly ["bun", "npm", "pnpm", "yarn"]>;
+  readonly lockfileVersion: Schema.String;
+  readonly packages: Schema.$Array<typeof ResolvedPackage>;
+  readonly workspaceDependencies: Schema.$Array<typeof WorkspaceDependency>;
+  readonly importers: Schema.withConstructorDefault<Schema.withDecodingDefaultKey<Schema.$Array<typeof LockfileImporter>, never>>;
+  readonly extension: Schema.optionalKey<Schema.Union<readonly [typeof PnpmExtension, typeof BunExtension]>>;
+}>, {}>;
+/**
+ * The unified lockfile model all four formats normalize into.
+ *
+ * @remarks
+ * - `format` — which lockfile format produced the data.
+ * - `lockfileVersion` — the lockfile format version string.
+ * - `packages` — every resolved package.
+ * - `workspaceDependencies` — inter-workspace dependency edges.
+ * - `importers` — each workspace importer's declared dependencies
+ *   ({@link LockfileImporter}), keyed by importer path. Populated by the pnpm,
+ *   bun and npm parsers; always empty for yarn, which records no importers.
+ * - `extension` — format-specific residue (`PnpmExtension` or
+ *   `BunExtension`) when the format records any.
+ *
+ * For pnpm, `Lockfile.parse` emits the honest importer-path-keyed model
+ * (workspace packages named by importer path, version `"0.0.0"`);
+ * {@link Lockfile.withImporterNames} is the explicit, pure second stage
+ * that rewrites those names once the caller has read the workspace
+ * manifests. npm, yarn and bun lockfiles carry real names and need no
+ * second stage.
+ *
+ * @public
+ */
+declare class Lockfile extends Lockfile_base {
+  #private;
+  /**
+   * Parse lockfile content of a known format into the unified model — the
+   * package's only fallible boundary.
+   *
+   * @param content - The lockfile text (this package does no IO; the caller
+   *   reads the file).
+   * @param options - The lockfile format to parse as.
+   * @returns An `Effect` succeeding with the {@link Lockfile}, or failing
+   *   with {@link LockfileParseError} (malformed text or the wrong shape) or
+   *   {@link LockfileFramingError} (the text parsed, but no lockfile document
+   *   could be located in the stream — see that error for why a
+   *   multi-document `pnpm-lock.yaml` needs it).
+   */
+  static readonly parse: (content: string, options: {
+    readonly format: LockfileFormat;
+  }) => Effect.Effect<Lockfile, LockfileFramingError | LockfileParseError, never>;
+  /**
+   * Rewrite pnpm importer-path names to real package names — the explicit
+   * second stage of pnpm parsing. Total and pure.
+   *
+   * @remarks
+   * Workspace packages whose `relativePath` appears in `names` are renamed;
+   * dependency edge ends are rewritten through the same map. Entries not in
+   * the map keep their path name, and non-pnpm lockfiles are unaffected (no
+   * key matches). Versions are not touched — pnpm workspace packages keep
+   * `"0.0.0"` (the lockfile does not record their real versions).
+   *
+   * @param names - Importer path → real package name.
+   * @returns A new {@link Lockfile} with names rewritten.
+   */
+  withImporterNames(names: ReadonlyMap<string, string>): Lockfile;
+  /**
+   * Every resolved package with the given name — one entry per resolved
+   * version. Backed by a lazily built index, so repeated lookups are O(1).
+   *
+   * @param name - The package name to look up.
+   * @returns The matching packages, empty when the name is not in the
+   *   lockfile.
+   */
+  packagesNamed(name: string): ReadonlyArray<ResolvedPackage>;
+  /**
+   * The importer at the given path — `"."` for the workspace root — or
+   * `Option.none()` when the lockfile records no importer there. Backed by a
+   * lazily built index, so repeated lookups are O(1). The index is a `Map`,
+   * so an attacker-adjacent path (`__proto__`, `constructor`) neither pollutes
+   * nor collides.
+   *
+   * @param path - The importer path to look up.
+   * @returns The matching {@link LockfileImporter}, or `Option.none()`.
+   */
+  importer(path: string): Option.Option<LockfileImporter>;
+  /** The workspace-local packages. */
+  get workspacePackages(): ReadonlyArray<ResolvedPackage>;
+}
+//#endregion
+//#region src/LockfileIntegrity.d.ts
+declare const WorkspaceManifest_base: Schema.Class<WorkspaceManifest, Schema.Struct<{
+  readonly name: Schema.NonEmptyString;
+  readonly dependencies: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+  readonly devDependencies: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+  readonly peerDependencies: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+  readonly optionalDependencies: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+}>, {}>;
+/**
+ * The minimal manifest shape {@link LockfileIntegrity.compare} checks a
+ * lockfile against: a package name plus the four optional dependency maps.
+ *
+ * @remarks
+ * Deliberately *not* a `@effected/package-json` type — this package takes
+ * manifests as plain values so its consumers own the manifest IO (and may
+ * derive these from any richer model).
+ *
+ * @public
+ */
+declare class WorkspaceManifest extends WorkspaceManifest_base {}
+declare const LockfileIntegrity_base: Schema.Class<LockfileIntegrity, Schema.Struct<{
+  readonly valid: Schema.Boolean;
+  readonly missingWorkspaces: Schema.$Array<Schema.String>;
+  readonly extraWorkspaces: Schema.$Array<Schema.String>;
+  readonly unsatisfiedConstraints: Schema.$Array<Schema.Struct<{
+    readonly workspace: Schema.String;
+    readonly dependency: Schema.String;
+    readonly constraint: Schema.String;
+    readonly resolved: Schema.String;
+    readonly depType: Schema.Literals<readonly ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"]>;
+  }>>;
+}>, {}>;
+/**
+ * Result of checking a parsed lockfile against the workspace's declared
+ * manifests.
+ *
+ * @remarks
+ * A data type, not an error: it reports *what* mismatches exist without
+ * failing anything.
+ *
+ * - `valid` — `true` when the lockfile is fully consistent.
+ * - `missingWorkspaces` — workspace names present in the manifests but
+ *   absent from the lockfile.
+ * - `extraWorkspaces` — workspace names in the lockfile with no matching
+ *   manifest.
+ * - `unsatisfiedConstraints` — declared constraints the lockfile's resolved
+ *   versions do not satisfy.
+ *
+ * @public
+ */
+declare class LockfileIntegrity extends LockfileIntegrity_base {
+  /**
+   * Check a lockfile's consistency against workspace manifests — a total,
+   * pure function: no Effect, no error channel, no IO.
+   *
+   * @remarks
+   * Constraint checking is best-effort by design: `workspace:` / `link:` /
+   * `file:` specifiers and rows whose range (or every resolved version) does
+   * not parse as SemVer are skipped, exactly as in the v3 implementation.
+   * A lockfile may resolve the same package at several versions; a
+   * constraint is satisfied when *any* resolved version matches, and an
+   * unsatisfied row reports every candidate in `resolved`. The
+   * caller reads the manifests (this package does no IO). For pnpm, apply
+   * `Lockfile#withImporterNames` first so workspace names align with
+   * manifest names.
+   *
+   * (Named `compare`, not `check`: every v4 `Schema.Class` already carries
+   * a `static check(...checks)` for attaching schema checks, and statics
+   * cannot be shadowed with an incompatible signature.)
+   *
+   * @param lockfile - The parsed lockfile.
+   * @param manifests - The workspace manifests to compare against.
+   * @returns The integrity report.
+   */
+  static compare(lockfile: Lockfile, manifests: ReadonlyArray<WorkspaceManifest>): LockfileIntegrity;
+}
+//#endregion
+export { BunExtension, ImporterDependency, Lockfile, LockfileFormat, LockfileFramingError, LockfileImporter, LockfileIntegrity, LockfileParseError, type PnpmCatalogs, PnpmExtension, ResolvedPackage, WorkspaceDependency, WorkspaceManifest, filenameFor, fromFilename };
+//# sourceMappingURL=index.d.ts.map

package/index.js

@@ -0,0 +1,11 @@
+import { BunExtension } from "./BunExtension.js";
+import { ImporterDependency } from "./ImporterDependency.js";
+import { LockfileImporter } from "./LockfileImporter.js";
+import { ResolvedPackage } from "./ResolvedPackage.js";
+import { WorkspaceDependency } from "./WorkspaceDependency.js";
+import { PnpmExtension } from "./PnpmExtension.js";
+import { LockfileFormat, filenameFor, fromFilename } from "./LockfileFormat.js";
+import { Lockfile, LockfileFramingError, LockfileParseError } from "./Lockfile.js";
+import { LockfileIntegrity, WorkspaceManifest } from "./LockfileIntegrity.js";
+
+export { BunExtension, ImporterDependency, Lockfile, LockfileFormat, LockfileFramingError, LockfileImporter, LockfileIntegrity, LockfileParseError, PnpmExtension, ResolvedPackage, WorkspaceDependency, WorkspaceManifest, filenameFor, fromFilename };