@effected/lockfiles 0.14.0 → 0.15.0

package/ImporterDependency.js

@@ -24,7 +24,7 @@ import { DependencyField, DependencySpecifier } from "@effected/npm";
 *   `name` against `Lockfile.packages`.
 * - `peerSuffix` — pnpm's peer-disambiguation context: the raw parenthesized
 *   chain the lockfile recorded after the version, e.g.
-*   `(effect@4.0.0-beta.101)(ioredis@5.11.1(supports-color@8.1.1))`. Present
+*   `(effect@4.0.0)(ioredis@5.11.1(supports-color@8.1.1))`. Present
 *   only when the lockfile recorded one — never for suffix-free pnpm entries,
 *   and never for the other formats, which do not record peer context per
 *   importer dependency.

package/Lockfile.js

@@ -31,8 +31,11 @@ const EMPTY_IMPORTERS = [];
 * @public
 */
 var LockfileParseError = class extends Schema.TaggedError()("LockfileParseError", {
+	/** The lockfile format that was being parsed. */
 	format: LockfileFormat,
+	/** Whether the text itself failed to parse (`"syntax"`) or parsed but had the wrong shape (`"validation"`). */
 	stage: Schema.Literals(["syntax", "validation"]),
+	/** The underlying engine or schema failure, preserved structurally. */
 	cause: Schema.Defect()
 }) {
 	get message() {
@@ -44,14 +47,13 @@ var LockfileParseError = class extends Schema.TaggedError()("LockfileParseError"
 * lockfile document could be located in it.
 *
 * @remarks
-* `pnpm-lock.yaml` is a YAML **stream**. pnpm 11 and 12 write an env
-* preamble document ahead of the lockfile whenever the workspace declares
-* `configDependencies` or `devEngines.packageManager`, so the file holds two
-* documents. The
+* `pnpm-lock.yaml` is a YAML **stream**. pnpm writes an env preamble document
+* ahead of the lockfile whenever the workspace declares `configDependencies`
+* or `devEngines.packageManager`, 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.
+* parser that read only the first document would get the preamble: a document
+* that *validates*, yielding a lockfile with an empty workspace. This error
+* makes that case fail instead of succeeding quietly.
 *
 * - `format` — which format was being parsed.
 * - `documents` — how many YAML documents the stream carried.
@@ -82,12 +84,15 @@ var LockfileParseError = class extends Schema.TaggedError()("LockfileParseError"
 * @public
 */
 var LockfileFramingError = class extends Schema.TaggedError()("LockfileFramingError", {
+	/** The lockfile format that was being parsed. */
 	format: LockfileFormat,
+	/** Which framing check failed; see the class remarks for each. */
 	reason: Schema.Literals([
 		"noLockfileDocument",
 		"noImporters",
 		"unexpectedDocuments"
 	]),
+	/** How many YAML documents the stream carried. */
 	documents: Schema.Int
 }) {
 	get message() {
@@ -288,9 +293,8 @@ var Lockfile = class Lockfile extends Schema.Class("Lockfile")({
 	*
 	* @remarks
 	* `ResolvedPackage.instanceId` is what a resolved edge points at, so peer and
-	* dependency resolution is a lookup through this index rather than a scan.
-	* Without it every consumer rebuilds the same map — `new Map(lockfile.packages.map((p) => [p.instanceId, p]))` —
-	* which is O(n) per walk and one more place for the key choice to drift.
+	* dependency resolution is a lookup through this index rather than a scan
+	* over `packages`.
 	*
 	* The index is a `Map`, so an instance id that collides with an `Object`
 	* member name (`__proto__`, `constructor`) neither pollutes nor

package/LockfileIntegrity.js

@@ -61,7 +61,7 @@ var LockfileIntegrity = class LockfileIntegrity extends Schema.Class("LockfileIn
 	* @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.
+	* not parse as SemVer are skipped.
 	* 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
@@ -69,9 +69,9 @@ var LockfileIntegrity = class LockfileIntegrity extends Schema.Class("LockfileIn
 	* `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.)
+	* (Named `compare`, not `check`: every `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.

package/PnpmEnvLockfile.js

@@ -16,6 +16,8 @@ const configDependencies = Effect.fn("PnpmEnvLockfile.configDependencies")((cont
 * import { PnpmEnvLockfile } from "@effected/lockfiles";
 * import { Effect, Option } from "effect";
 *
+* declare const content: string; // the text of a pnpm-lock.yaml
+*
 * const program = Effect.gen(function* () {
 *   const lock = yield* PnpmEnvLockfile.packageManager(content);
 *   const configDependencies = yield* PnpmEnvLockfile.configDependencies(content);

package/README.md

@@ -7,10 +7,10 @@
 
 Lockfile parsing for [Effect](https://effect.website) v4: bun (`bun.lock`), npm (`package-lock.json`), 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 prerelease. 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
+> **Pre-`1.0.0`.** This package is part of the `@effected/*` kit, built on stable
+> Effect v4 (`effect` `^4.0.0`) and still in `0.x` development. Stable Effect
+> makes a kit `1.0.0` possible, not automatic. To keep your `effect` and
+> `@effect/*` versions on the line 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

package/index.d.ts

@@ -85,7 +85,7 @@ declare const ImporterDependency_base: Schema.Class<ImporterDependency, Schema.S
  *   `name` against `Lockfile.packages`.
  * - `peerSuffix` — pnpm's peer-disambiguation context: the raw parenthesized
  *   chain the lockfile recorded after the version, e.g.
- *   `(effect@4.0.0-beta.101)(ioredis@5.11.1(supports-color@8.1.1))`. Present
+ *   `(effect@4.0.0)(ioredis@5.11.1(supports-color@8.1.1))`. Present
  *   only when the lockfile recorded one — never for suffix-free pnpm entries,
  *   and never for the other formats, which do not record peer context per
  *   importer dependency.
@@ -355,8 +355,11 @@ export declare const fromFilename: (name: string) => Option.Option<LockfileForma
 //#endregion
 //#region src/Lockfile.d.ts
 declare const LockfileParseError_base: Schema.Class<LockfileParseError, Schema.TaggedStruct<"LockfileParseError", {
+  /** The lockfile format that was being parsed. */
   readonly format: Schema.Literals<readonly ["bun", "npm", "pnpm", "yarn"]>;
+  /** Whether the text itself failed to parse (`"syntax"`) or parsed but had the wrong shape (`"validation"`). */
   readonly stage: Schema.Literals<readonly ["syntax", "validation"]>;
+  /** The underlying engine or schema failure, preserved structurally. */
   readonly cause: Schema.Defect;
 }>, import("effect/Cause").YieldableError>;
 /**
@@ -381,8 +384,11 @@ export declare class LockfileParseError extends LockfileParseError_base {
   get message(): string;
 }
 declare const LockfileFramingError_base: Schema.Class<LockfileFramingError, Schema.TaggedStruct<"LockfileFramingError", {
+  /** The lockfile format that was being parsed. */
   readonly format: Schema.Literals<readonly ["bun", "npm", "pnpm", "yarn"]>;
+  /** Which framing check failed; see the class remarks for each. */
   readonly reason: Schema.Literals<readonly ["noLockfileDocument", "noImporters", "unexpectedDocuments"]>;
+  /** How many YAML documents the stream carried. */
   readonly documents: Schema.Int;
 }>, import("effect/Cause").YieldableError>;
 /**
@@ -390,14 +396,13 @@ declare const LockfileFramingError_base: Schema.Class<LockfileFramingError, Sche
  * lockfile document could be located in it.
  *
  * @remarks
- * `pnpm-lock.yaml` is a YAML **stream**. pnpm 11 and 12 write an env
- * preamble document ahead of the lockfile whenever the workspace declares
- * `configDependencies` or `devEngines.packageManager`, so the file holds two
- * documents. The
+ * `pnpm-lock.yaml` is a YAML **stream**. pnpm writes an env preamble document
+ * ahead of the lockfile whenever the workspace declares `configDependencies`
+ * or `devEngines.packageManager`, 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.
+ * parser that read only the first document would get the preamble: a document
+ * that *validates*, yielding a lockfile with an empty workspace. This error
+ * makes that case fail instead of succeeding quietly.
  *
  * - `format` — which format was being parsed.
  * - `documents` — how many YAML documents the stream carried.
@@ -529,9 +534,8 @@ export declare class Lockfile extends Lockfile_base {
    *
    * @remarks
    * `ResolvedPackage.instanceId` is what a resolved edge points at, so peer and
-   * dependency resolution is a lookup through this index rather than a scan.
-   * Without it every consumer rebuilds the same map — `new Map(lockfile.packages.map((p) => [p.instanceId, p]))` —
-   * which is O(n) per walk and one more place for the key choice to drift.
+   * dependency resolution is a lookup through this index rather than a scan
+   * over `packages`.
    *
    * The index is a `Map`, so an instance id that collides with an `Object`
    * member name (`__proto__`, `constructor`) neither pollutes nor
@@ -603,7 +607,7 @@ export declare class LockfileIntegrity extends LockfileIntegrity_base {
    * @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.
+   * not parse as SemVer are skipped.
    * 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
@@ -611,9 +615,9 @@ export declare class LockfileIntegrity extends LockfileIntegrity_base {
    * `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.)
+   * (Named `compare`, not `check`: every `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.
@@ -733,6 +737,8 @@ interface PnpmEnvLockfileReaders {
  * import { PnpmEnvLockfile } from "@effected/lockfiles";
  * import { Effect, Option } from "effect";
  *
+ * declare const content: string; // the text of a pnpm-lock.yaml
+ *
  * const program = Effect.gen(function* () {
  *   const lock = yield* PnpmEnvLockfile.packageManager(content);
  *   const configDependencies = yield* PnpmEnvLockfile.configDependencies(content);

package/internal/bun.js

@@ -49,7 +49,7 @@ const BunLockfileRaw = Schema.Struct({
 /**
 * Parse bun `bun.lock` (JSONC) content into the unified field bundle.
 * Resolved packages are tuples whose first element is `"name@version"`;
-* the integrity hash is assumed at tuple index 3 (the permissive v3
+* the integrity hash is assumed at tuple index 3 (a permissive
 * reading of an under-documented upstream shape).
 *
 * @internal

package/internal/shared.js

@@ -6,7 +6,7 @@ import { DependencySpecifier, IntegrityHash } from "@effected/npm";
 //#region src/internal/shared.ts
 /**
 * The four dependency sections of a manifest, in a stable order — the shared
-* dependency-sections table (v3's `DEP_SECTIONS`). Each entry is both the
+* dependency-sections table. Each entry is both the
 * manifest field name to read and the `@effected/npm` `DependencyField` it maps
 * to, since the two coincide. Consumed by `extractWorkspaceDeps` and by the
 * pnpm/bun/npm importer builders.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/lockfiles",
-	"version": "0.14.0",
+	"version": "0.15.0",
 	"private": false,
 	"description": "Pure lockfile parsing for bun, npm, pnpm and yarn Berry into one unified Effect schema model, with pure integrity checking against workspace manifests.",
 	"keywords": [
@@ -40,11 +40,11 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"@effected/jsonc": "^0.14.0",
-		"@effected/npm": "^0.19.0",
-		"@effected/semver": "^0.10.0",
-		"@effected/yaml": "^0.18.0",
-		"effect": "4.0.0-rc.118"
+		"@effected/jsonc": "^0.15.0",
+		"@effected/npm": "^0.20.0",
+		"@effected/semver": "^0.11.0",
+		"@effected/yaml": "^0.19.0",
+		"effect": "^4.0.0"
 	},
 	"engines": {
 		"node": ">=24.11.0"