@effected/package-json 0.19.1 → 0.20.0

package/EntryPoint.js

@@ -6,9 +6,8 @@ import { Result, Schema } from "effect";
 *
 * @remarks
 * The reason is discriminated rather than a bare "not found" because the three
-* shapes call for different responses, and a caller staring at a consumer's
-* plugin at 3am needs to know which one it hit. Collapsing them into one
-* sentinel is the same class of quiet wrong answer as an untyped error channel.
+* shapes call for different responses, and a caller needs to know which one it
+* hit.
 *
 * @public
 */
@@ -74,11 +73,10 @@ const resolveConditions = (conditionsObject, conditions) => {
 * Resolve a package's root entry point from its manifest.
 *
 * @remarks
-* The half of "read something out of a published package" that has no home
-* anywhere else: given a manifest, which file is the package's `"."` entry?
-* It is pure and IO-free by design — nothing here touches a filesystem, so it
-* is testable against plain manifest objects with no package on disk, and it
-* composes with a directory that arrived by any route.
+* Answers "given a manifest, which file is the package's `"."` entry?". It is
+* pure and IO-free by design — nothing here touches a filesystem, so it works
+* on plain manifest objects with no package on disk, and it composes with a
+* directory that arrived by any route.
 *
 * All three legal `exports` spellings are honoured, because all three appear in
 * real published packages:
@@ -105,7 +103,6 @@ const resolveConditions = (conditionsObject, conditions) => {
 * @example
 * ```ts
 * import { resolveEntryPoint } from "@effected/package-json";
-* import { Result, Schema } from "effect";
 *
 * resolveEntryPoint({ exports: { import: "./esm.js", require: "./cjs.js" } });
 * // Result.succeed("./esm.js")

package/LenientManifest.js

@@ -210,8 +210,8 @@ var LenientManifest = class LenientManifest extends Schema.Class("LenientManifes
 	* {@link LenientManifest.decodeResult}, adding the tracing span.
 	*
 	* @param input - the parsed package.json JSON value (e.g. from `JSON.parse`)
-	* @returns an Effect resolving to the decoded {@link LenientManifest}
-	* @throws (typed) `PackageDecodeError` when `input` is not a JSON object
+	* @returns an Effect resolving to the decoded {@link LenientManifest},
+	* failing with {@link PackageDecodeError} when `input` is not a JSON object
 	*/
 	static decode = Effect.fn("LenientManifest.decode")((input) => Effect.fromResult(LenientManifest.decodeResult(input)));
 	/**
@@ -242,8 +242,8 @@ var LenientManifest = class LenientManifest extends Schema.Class("LenientManifes
 	* {@link LenientManifest.parseResult}, adding the tracing span.
 	*
 	* @param text - the package.json source text
-	* @returns an Effect resolving to the decoded {@link LenientManifest}
-	* @throws (typed) `PackageJsonSyntaxError` when the text is not valid JSON
+	* @returns an Effect resolving to the decoded {@link LenientManifest},
+	* failing with {@link PackageJsonSyntaxError} when the text is not valid JSON
 	* or is not a JSON object
 	*/
 	static parse = Effect.fn("LenientManifest.parse")((text) => Effect.fromResult(LenientManifest.parseResult(text)));

package/License.js

@@ -53,9 +53,8 @@ const SpdxLicense = Schema.String.pipe(Schema.check(Schema.makeFilter((value) =>
 * @remarks
 * This is the accessor to reach for whenever a branded `SpdxLicense` has
 * to become an actual expression — a license URL, a badge, structured data, a
-* policy check. It exists because the brand and the grammar disagree, and that
-* disagreement is knowledge these two packages jointly own rather than
-* something each consumer should rediscover.
+* policy check. It exists because the brand and the grammar disagree, so no
+* consumer has to rediscover that disagreement.
 *
 * `UNLICENSED` and `SEE LICENSE IN <file>` are legal in a manifest and are not
 * SPDX expressions, so they yield `Option.none()`. Everything else parses.
@@ -66,12 +65,14 @@ const SpdxLicense = Schema.String.pipe(Schema.check(Schema.makeFilter((value) =>
 *
 * @example
 * ```ts
-* import { licenseExpressionOf } from "@effected/package-json";
-* import { SpdxExpression } from "@effected/spdx";
+* import { SpdxLicense, licenseExpressionOf } from "@effected/package-json";
+* import { Option, Schema } from "effect";
 *
-* // "MIT"          => Option.some(<LicenseNode MIT>)
-* // "UNLICENSED"   => Option.none()
-* // "SEE LICENSE IN LICENSE.txt" => Option.none()
+* const decode = Schema.decodeUnknownSync(SpdxLicense);
+*
+* Option.isSome(licenseExpressionOf(decode("MIT"))); // => true
+* Option.isSome(licenseExpressionOf(decode("UNLICENSED"))); // => false
+* Option.isSome(licenseExpressionOf(decode("SEE LICENSE IN LICENSE.txt"))); // => false
 * ```
 *
 * @param license - a branded manifest license value

package/Package.js

@@ -67,8 +67,8 @@ const PeerDependenciesMetaField = Schema.Record(Schema.String, Schema.Struct({ o
 *
 * @deprecated Superseded by {@link Repository.FromValue}, which decodes both
 * encodings into a typed {@link Repository} with normalization getters and
-* round-trips the original form. Kept as a named type for consumers that were
-* matching on the raw union; it is no longer what `Package.repository` uses.
+* round-trips the original form. Retained only as a name for the raw union;
+* `Package.repository` is a {@link Repository}.
 *
 * @public
 */
@@ -161,8 +161,8 @@ var Package = class Package extends Schema.Class("Package")({
 	* `SchemaError` to a typed {@link PackageDecodeError} at the boundary.
 	*
 	* @param input - the parsed package.json JSON value (e.g. from `JSON.parse`)
-	* @returns an Effect resolving to the decoded `Package`
-	* @throws (typed) `PackageDecodeError` when `input` does not satisfy the schema
+	* @returns an Effect resolving to the decoded `Package`, failing with
+	* {@link PackageDecodeError} when `input` does not satisfy the schema
 	*/
 	static decode = Effect.fn("Package.decode")(function* (input) {
 		return yield* Schema.decodeUnknownEffect(Package.schema)(input).pipe(Effect.catchTag("SchemaError", (cause) => new PackageDecodeError({ cause })));
@@ -262,20 +262,39 @@ var Package = class Package extends Schema.Class("Package")({
 	/**
 	* Resolve `catalog:` and `workspace:` specifiers across all four dependency
 	* maps using the `CatalogResolver` and `WorkspaceResolver` from context,
-	* classifying and projecting through `@effected/npm`'s `DependencySpecifier`
-	* statics (`workspace:` uses the pnpm publish-time projection; the alias
-	* form `workspace:<name>@<range>` resolves the TARGET package's version and
-	* becomes the published `npm:<name>@<range>` alias). Specifiers the
-	* resolvers return `None` for are left unchanged — resolution still
-	* succeeds. A `CatalogResolver` whose catalog assembly failed surfaces
-	* typed as `@effected/npm`'s `CatalogAssemblyError`, alongside the
-	* contracts' `DependencyResolutionError`. This is the explicit resolution
-	* step — `PackageJsonFile.write` never resolves.
+	* returning a new `Package`. This is the explicit resolution step —
+	* `PackageJsonFile.write` never resolves.
 	*
 	* @remarks
-	* Leaves unresolvable specifiers unchanged. For fail-typed manifest
+	* Classification and projection go through `@effected/npm`'s
+	* `DependencySpecifier` statics: `workspace:` uses the pnpm publish-time
+	* projection, and the alias form `workspace:<name>@<range>` resolves the
+	* TARGET package's version and becomes the published `npm:<name>@<range>`
+	* alias. Specifiers the resolvers answer `Option.none()` for are left
+	* unchanged — resolution still succeeds. Fails with `@effected/npm`'s
+	* `CatalogAssemblyError` when catalog assembly failed, or
+	* `DependencyResolutionError` when a resolver's mechanism failed; requires
+	* `CatalogResolver` and `WorkspaceResolver` in `R`. For fail-typed
 	* resolution over the tolerant model, see `@effected/npm`'s
 	* `Manifest#resolve`.
+	*
+	* @example
+	* ```ts
+	* import { Default } from "@effected/npm";
+	* import { Package } from "@effected/package-json";
+	* import { Effect } from "effect";
+	*
+	* const program = Effect.gen(function* () {
+	*   const pkg = yield* Package.decode({
+	*     name: "my-pkg",
+	*     version: "1.0.0",
+	*     dependencies: { effect: "catalog:" },
+	*   });
+	*   return yield* Package.resolve(pkg);
+	* }).pipe(Effect.provide(Default)); // the no-op resolvers leave `catalog:` unchanged
+	* ```
+	*
+	* @param pkg - the package whose specifiers to resolve
 	*/
 	static resolve = Effect.fn("Package.resolve")(function* (pkg) {
 		const workspace = yield* WorkspaceResolver;

package/PackageJsonFile.js

@@ -66,9 +66,10 @@ var PackageJsonWriteError = class extends Schema.TaggedError()("PackageJsonWrite
 	}
 };
 /**
-* Reads and writes package.json over core `FileSystem` / `Path`. The layer
-* requires those services; provide `@effect/platform-node`'s `NodeFileSystem` /
-* `NodePath` (or a bun equivalent) at the application boundary.
+* Reads, writes and surgically edits package.json files over core `FileSystem`
+* / `Path`. The layer requires those services; provide
+* `@effect/platform-node`'s `NodeFileSystem` / `NodePath` (or a bun equivalent)
+* at the application boundary.
 *
 * @example
 * ```ts

package/PackageManager.js

@@ -27,9 +27,8 @@ const invalid = (input, message) => Effect.fail(new SchemaIssue.InvalidValue({ m
 * - Corepack 0.34.0 (`specUtils.ts`, `parseSpec`) recognises **three** names —
 *   `npm`, `pnpm`, `yarn` — and throws an "unsupported package manager
 *   specification" usage error for any other. Adopting that set here would reject
-*   `bun@1.2.20`, which is real: six published packages in this repo's own
-*   `node_modules` carry exactly that value, and a manifest model that cannot
-*   read them is useless for the job it has.
+*   `bun@1.2.20`, which real published manifests carry, and a manifest model
+*   that cannot read them is useless for the job it has.
 * - Corepack does not treat the set as closed either. `parseSpec` skips the
 *   name check entirely when the spec is a URL, so a custom name is reachable
 *   in corepack's own grammar (behind `COREPACK_ENABLE_UNSAFE_CUSTOM_URLS`).
@@ -42,6 +41,17 @@ const invalid = (input, message) => Effect.fail(new SchemaIssue.InvalidValue({ m
 * and simply will not be installable through the pin — which is the honest
 * relationship between a document model and a provisioning contract.
 *
+* @example
+* ```ts
+* import { PackageManager } from "@effected/package-json";
+* import { Schema } from "effect";
+*
+* const pm = Schema.decodeUnknownSync(PackageManager.FromString)("pnpm@10.33.0+sha512.abc");
+* pm.name; // => "pnpm"
+* pm.version; // => "10.33.0"
+* pm.hasIntegrity; // => true
+* ```
+*
 * @public
 */
 var PackageManager = class PackageManager extends Schema.Class("PackageManager")({
@@ -54,8 +64,7 @@ var PackageManager = class PackageManager extends Schema.Class("PackageManager")
 	* allowed (`10.0.0-rc.1`); ranges, partial versions, dist-tags,
 	* leading-zero components and padded values are not, and a version
 	* carrying build metadata is rejected at construction because the grammar
-	* cannot express it. The shared schema is consumed by identity, not
-	* copied — the suite asserts `fields.version === SemVer.PinnableVersionString`.
+	* cannot express it.
 	*/
 	version: SemVer.PinnableVersionString,
 	/**

package/PackageManagerRange.js

@@ -198,8 +198,7 @@ var PackageManagerRange = class PackageManagerRange extends Schema.Class("Packag
 	* @remarks
 	* The entry's `name` is the package-manager name and its `version` is the
 	* same `<range>[+<integrity>]` tail the `packageManager` field carries after
-	* its `@` — `^12.6.0`, `12.6.0`, or `12.6.0+sha512.<hex>` as
-	* `pnpm self-update` historically wrote it. Both are validated exactly as
+	* its `@` — `^12.6.0`, `12.6.0`, or `12.6.0+sha512.<hex>`. Both are validated exactly as
 	* {@link PackageManagerRange.parseResult} validates them. The `version`
 	* slot is optional on a {@link DevEngine}, but an entry without one names
 	* no range, so it fails with `reason: "range"`; `onFail` is ignored. The

package/PackageManifest.js

@@ -40,11 +40,11 @@ import { SemVer } from "@effected/semver";
 * @example
 * ```ts
 * import { PackageManifest } from "@effected/package-json";
-* import { Effect, Option } from "effect";
+* import { Effect } from "effect";
 *
 * const program = Effect.gen(function* () {
 *   const root = yield* PackageManifest.decode({ private: true, packageManager: "pnpm@^11.20.0" });
-*   console.log(root.isPrivate, root.packageManager?.isExact); // true false
+*   console.log(root.isPrivate); // => true
 * });
 * ```
 *
@@ -67,9 +67,8 @@ var PackageManifest = class PackageManifest extends Schema.Class("PackageManifes
 	* any `SchemaError` to a typed {@link PackageDecodeError} at the boundary.
 	*
 	* @param input - the parsed package.json JSON value (e.g. from `JSON.parse`)
-	* @returns an Effect resolving to the decoded `PackageManifest`
-	* @throws (typed) `PackageDecodeError` when a present field does not satisfy
-	* its codec
+	* @returns an Effect resolving to the decoded `PackageManifest`, failing with
+	* {@link PackageDecodeError} when a present field does not satisfy its codec
 	*/
 	static decode = Effect.fn("PackageManifest.decode")(function* (input) {
 		return yield* Schema.decodeUnknownEffect(PackageManifest.schema)(input).pipe(Effect.catchTag("SchemaError", (cause) => new PackageDecodeError({ cause })));

package/PackageName.js

@@ -45,9 +45,19 @@ const unscoped = (name) => {
 const isScoped = (name) => name.startsWith("@");
 /**
 * The union of `ScopedPackageName` and `UnscopedPackageName`,
-* carrying the classification statics (`PackageName.isValid` and friends)
-* that absorb the v3 floating `PackageNameUtil` object. Use it as the schema
-* for a package-name field and reach for the statics to inspect a raw string.
+* carrying the classification statics (`PackageName.isValid`,
+* `PackageName.scope`, `PackageName.unscoped`, `PackageName.isScoped`). Use it as
+* the schema for a package-name field and reach for the statics to inspect a raw
+* string.
+*
+* @example
+* ```ts
+* import { PackageName } from "@effected/package-json";
+*
+* PackageName.isValid("@effected/semver"); // => true
+* PackageName.scope("@effected/semver"); // => Option.some("effected")
+* PackageName.unscoped("@effected/semver"); // => "semver"
+* ```
 *
 * @public
 */

package/PackageValidator.js

@@ -112,7 +112,9 @@ const runRules = Effect.fn("PackageValidator.validate")(function* (pkg, rules) {
 });
 /**
 * Validates a {@link Package} against a set of {@link ValidationRule}s,
-* aggregating every failure into one {@link PackageValidationError}.
+* aggregating every failure into one {@link PackageValidationError}. Use
+* `PackageValidator.layer` for {@link defaultRules} or `PackageValidator.layerRules`
+* for a custom rule set.
 *
 * @example
 * ```ts
@@ -124,6 +126,8 @@ const runRules = Effect.fn("PackageValidator.validate")(function* (pkg, rules) {
 *   const validator = yield* PackageValidator;
 *   yield* validator.validate(pkg);
 * }).pipe(Effect.provide(PackageValidator.layer));
+* // fails with PackageValidationError: the default rules require a license,
+* // a description and a repository, and forbid `private: true`
 * ```
 *
 * @public

package/Person.js

@@ -66,6 +66,17 @@ const encodePersonObject = (person) => {
 * A structured person object with `name`, optional `email` / `url`, and a
 * `rest` catch-all preserving any additional keys across a read/write cycle.
 *
+* @example
+* ```ts
+* import { Person } from "@effected/package-json";
+* import { Schema } from "effect";
+*
+* const ann = Schema.decodeUnknownSync(Person.FromValue)("Ann <ann@example.com> (https://example.com)");
+* ann.name; // => "Ann"
+* ann.email; // => "ann@example.com"
+* Schema.encodeSync(Person.FromValue)(ann); // => "Ann <ann@example.com> (https://example.com)"
+* ```
+*
 * @public
 */
 var Person = class Person extends Schema.Class("Person")({

package/README.md

@@ -7,10 +7,10 @@
 
 package.json parsing, editing, validation and file IO as Effect schemas. `Package` is a `Schema.Class` with the manifest's known fields typed — `name` is a branded npm name, `version` is a real `SemVer`, `packageManager` decodes into `{ name, version, integrity }` — and a `rest` catch-all that carries every unknown top-level key through a read, edit and write cycle without losing it. Editing is immutable and dual-signature, validation is a rule set you can replace, and `catalog:` / `workspace:` specifiers expand through the `@effected/npm` resolver contracts as an explicit step you opt into.
 
-> **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/Repository.js

@@ -28,8 +28,8 @@ const stripGitSuffix = (value) => value.endsWith(".git") ? value.slice(0, -4) :
 * The browsable `https://host/path` form of a repository reference, or none
 * when the value is not one this model recognizes.
 *
-* Total by construction: `repository` is caller data, and a value we cannot
-* interpret is a missing answer rather than a failure.
+* Total by construction: `repository` is caller data, and a value that cannot
+* be interpreted is a missing answer rather than a failure.
 */
 const browseUrlOf = (raw) => {
 	const url = raw.trim();
@@ -102,8 +102,13 @@ const isFaithfulBugs = (wire, bugs) => wire.url === bugs.url && wire.email === b
 *
 * @example
 * ```ts
-* // "effected/kit" → https://github.com/effected/kit
-* // "git@github.com:effected/kit.git" → https://github.com/effected/kit
+* import { Repository } from "@effected/package-json";
+* import { Schema } from "effect";
+*
+* const repo = Schema.decodeUnknownSync(Repository.FromValue)("effected/kit");
+* repo.url; // => "effected/kit"
+* repo.browseUrl; // => Option.some("https://github.com/effected/kit")
+* // "git@github.com:effected/kit.git" browses to the same URL
 * ```
 *
 * @public
@@ -166,8 +171,15 @@ var Repository = class Repository extends Schema.Class("Repository")({
 	*
 	* @example
 	* ```ts
-	* // { url: "effected/kit", directory: "packages/spdx" }
-	* // => https://github.com/effected/kit/tree/HEAD/packages/spdx
+	* import { Repository } from "@effected/package-json";
+	* import { Schema } from "effect";
+	*
+	* const repo = Schema.decodeUnknownSync(Repository.FromValue)({
+	*   url: "effected/kit",
+	*   directory: "packages/spdx",
+	* });
+	* repo.directoryUrl;
+	* // => Option.some("https://github.com/effected/kit/tree/HEAD/packages/spdx")
 	* ```
 	*/
 	get directoryUrl() {

package/index.d.ts

@@ -144,9 +144,8 @@ declare const UnresolvedEntryPointError_base: Schema.Class<UnresolvedEntryPointE
  *
  * @remarks
  * The reason is discriminated rather than a bare "not found" because the three
- * shapes call for different responses, and a caller staring at a consumer's
- * plugin at 3am needs to know which one it hit. Collapsing them into one
- * sentinel is the same class of quiet wrong answer as an untyped error channel.
+ * shapes call for different responses, and a caller needs to know which one it
+ * hit.
  *
  * @public
  */
@@ -165,18 +164,19 @@ export declare class UnresolvedEntryPointError extends UnresolvedEntryPointError
  * @public
  */
 interface EntryPointManifest {
+  /** The `exports` field, in any of its legal shapes. */
   readonly exports?: unknown;
+  /** The `main` field; consulted only when `exports` is absent. */
   readonly main?: unknown;
 }
 /**
  * Resolve a package's root entry point from its manifest.
  *
  * @remarks
- * The half of "read something out of a published package" that has no home
- * anywhere else: given a manifest, which file is the package's `"."` entry?
- * It is pure and IO-free by design — nothing here touches a filesystem, so it
- * is testable against plain manifest objects with no package on disk, and it
- * composes with a directory that arrived by any route.
+ * Answers "given a manifest, which file is the package's `"."` entry?". It is
+ * pure and IO-free by design — nothing here touches a filesystem, so it works
+ * on plain manifest objects with no package on disk, and it composes with a
+ * directory that arrived by any route.
  *
  * All three legal `exports` spellings are honoured, because all three appear in
  * real published packages:
@@ -203,7 +203,6 @@ interface EntryPointManifest {
  * @example
  * ```ts
  * import { resolveEntryPoint } from "@effected/package-json";
- * import { Result, Schema } from "effect";
  *
  * resolveEntryPoint({ exports: { import: "./esm.js", require: "./cjs.js" } });
  * // Result.succeed("./esm.js")
@@ -345,9 +344,8 @@ export type SpdxLicense = string & Brand.Brand<"SpdxLicense">;
  * @remarks
  * This is the accessor to reach for whenever a branded `SpdxLicense` has
  * to become an actual expression — a license URL, a badge, structured data, a
- * policy check. It exists because the brand and the grammar disagree, and that
- * disagreement is knowledge these two packages jointly own rather than
- * something each consumer should rediscover.
+ * policy check. It exists because the brand and the grammar disagree, so no
+ * consumer has to rediscover that disagreement.
  *
  * `UNLICENSED` and `SEE LICENSE IN <file>` are legal in a manifest and are not
  * SPDX expressions, so they yield `Option.none()`. Everything else parses.
@@ -358,12 +356,14 @@ export type SpdxLicense = string & Brand.Brand<"SpdxLicense">;
  *
  * @example
  * ```ts
- * import { licenseExpressionOf } from "@effected/package-json";
- * import { SpdxExpression } from "@effected/spdx";
+ * import { SpdxLicense, licenseExpressionOf } from "@effected/package-json";
+ * import { Option, Schema } from "effect";
  *
- * // "MIT"          => Option.some(<LicenseNode MIT>)
- * // "UNLICENSED"   => Option.none()
- * // "SEE LICENSE IN LICENSE.txt" => Option.none()
+ * const decode = Schema.decodeUnknownSync(SpdxLicense);
+ *
+ * Option.isSome(licenseExpressionOf(decode("MIT"))); // => true
+ * Option.isSome(licenseExpressionOf(decode("UNLICENSED"))); // => false
+ * Option.isSome(licenseExpressionOf(decode("SEE LICENSE IN LICENSE.txt"))); // => false
  * ```
  *
  * @param license - a branded manifest license value
@@ -384,8 +384,7 @@ declare const PackageManager_base: Schema.Class<PackageManager, Schema.Struct<{
    * allowed (`10.0.0-rc.1`); ranges, partial versions, dist-tags,
    * leading-zero components and padded values are not, and a version
    * carrying build metadata is rejected at construction because the grammar
-   * cannot express it. The shared schema is consumed by identity, not
-   * copied — the suite asserts `fields.version === SemVer.PinnableVersionString`.
+   * cannot express it.
    */
   readonly version: Schema.String;
   /**
@@ -420,9 +419,8 @@ declare const PackageManager_base: Schema.Class<PackageManager, Schema.Struct<{
  * - Corepack 0.34.0 (`specUtils.ts`, `parseSpec`) recognises **three** names —
  *   `npm`, `pnpm`, `yarn` — and throws an "unsupported package manager
  *   specification" usage error for any other. Adopting that set here would reject
- *   `bun@1.2.20`, which is real: six published packages in this repo's own
- *   `node_modules` carry exactly that value, and a manifest model that cannot
- *   read them is useless for the job it has.
+ *   `bun@1.2.20`, which real published manifests carry, and a manifest model
+ *   that cannot read them is useless for the job it has.
  * - Corepack does not treat the set as closed either. `parseSpec` skips the
  *   name check entirely when the spec is a URL, so a custom name is reachable
  *   in corepack's own grammar (behind `COREPACK_ENABLE_UNSAFE_CUSTOM_URLS`).
@@ -435,6 +433,17 @@ declare const PackageManager_base: Schema.Class<PackageManager, Schema.Struct<{
  * and simply will not be installable through the pin — which is the honest
  * relationship between a document model and a provisioning contract.
  *
+ * @example
+ * ```ts
+ * import { PackageManager } from "@effected/package-json";
+ * import { Schema } from "effect";
+ *
+ * const pm = Schema.decodeUnknownSync(PackageManager.FromString)("pnpm@10.33.0+sha512.abc");
+ * pm.name; // => "pnpm"
+ * pm.version; // => "10.33.0"
+ * pm.hasIntegrity; // => true
+ * ```
+ *
  * @public
  */
 export declare class PackageManager extends PackageManager_base {
@@ -504,9 +513,19 @@ export type UnscopedPackageName = string & Brand.Brand<"UnscopedPackageName">;
 export type PackageName = ScopedPackageName | UnscopedPackageName;
 /**
  * The union of `ScopedPackageName` and `UnscopedPackageName`,
- * carrying the classification statics (`PackageName.isValid` and friends)
- * that absorb the v3 floating `PackageNameUtil` object. Use it as the schema
- * for a package-name field and reach for the statics to inspect a raw string.
+ * carrying the classification statics (`PackageName.isValid`,
+ * `PackageName.scope`, `PackageName.unscoped`, `PackageName.isScoped`). Use it as
+ * the schema for a package-name field and reach for the statics to inspect a raw
+ * string.
+ *
+ * @example
+ * ```ts
+ * import { PackageName } from "@effected/package-json";
+ *
+ * PackageName.isValid("@effected/semver"); // => true
+ * PackageName.scope("@effected/semver"); // => Option.some("effected")
+ * PackageName.unscoped("@effected/semver"); // => "semver"
+ * ```
  *
  * @public
  */
@@ -532,6 +551,17 @@ declare const Person_base: Schema.Class<Person, Schema.Struct<{
  * A structured person object with `name`, optional `email` / `url`, and a
  * `rest` catch-all preserving any additional keys across a read/write cycle.
  *
+ * @example
+ * ```ts
+ * import { Person } from "@effected/package-json";
+ * import { Schema } from "effect";
+ *
+ * const ann = Schema.decodeUnknownSync(Person.FromValue)("Ann <ann@example.com> (https://example.com)");
+ * ann.name; // => "Ann"
+ * ann.email; // => "ann@example.com"
+ * Schema.encodeSync(Person.FromValue)(ann); // => "Ann <ann@example.com> (https://example.com)"
+ * ```
+ *
  * @public
  */
 export declare class Person extends Person_base {
@@ -603,8 +633,13 @@ declare const Repository_base: Schema.Class<Repository, Schema.Struct<{
  *
  * @example
  * ```ts
- * // "effected/kit" → https://github.com/effected/kit
- * // "git@github.com:effected/kit.git" → https://github.com/effected/kit
+ * import { Repository } from "@effected/package-json";
+ * import { Schema } from "effect";
+ *
+ * const repo = Schema.decodeUnknownSync(Repository.FromValue)("effected/kit");
+ * repo.url; // => "effected/kit"
+ * repo.browseUrl; // => Option.some("https://github.com/effected/kit")
+ * // "git@github.com:effected/kit.git" browses to the same URL
  * ```
  *
  * @public
@@ -654,8 +689,15 @@ export declare class Repository extends Repository_base {
    *
    * @example
    * ```ts
-   * // { url: "effected/kit", directory: "packages/spdx" }
-   * // => https://github.com/effected/kit/tree/HEAD/packages/spdx
+   * import { Repository } from "@effected/package-json";
+   * import { Schema } from "effect";
+   *
+   * const repo = Schema.decodeUnknownSync(Repository.FromValue)({
+   *   url: "effected/kit",
+   *   directory: "packages/spdx",
+   * });
+   * repo.directoryUrl;
+   * // => Option.some("https://github.com/effected/kit/tree/HEAD/packages/spdx")
    * ```
    */
   get directoryUrl(): Option.Option<string>;
@@ -745,8 +787,8 @@ export declare const PeerDependenciesMetaField: Schema.$Record<Schema.String, Sc
  *
  * @deprecated Superseded by {@link Repository.FromValue}, which decodes both
  * encodings into a typed {@link Repository} with normalization getters and
- * round-trips the original form. Kept as a named type for consumers that were
- * matching on the raw union; it is no longer what `Package.repository` uses.
+ * round-trips the original form. Retained only as a name for the raw union;
+ * `Package.repository` is a {@link Repository}.
  *
  * @public
  */
@@ -912,8 +954,8 @@ export declare class Package extends Package_base {
    * `SchemaError` to a typed {@link PackageDecodeError} at the boundary.
    *
    * @param input - the parsed package.json JSON value (e.g. from `JSON.parse`)
-   * @returns an Effect resolving to the decoded `Package`
-   * @throws (typed) `PackageDecodeError` when `input` does not satisfy the schema
+   * @returns an Effect resolving to the decoded `Package`, failing with
+   * {@link PackageDecodeError} when `input` does not satisfy the schema
    */
   static readonly decode: (input: unknown) => Effect.Effect<Package, PackageDecodeError, never>;
   /** Whether the package is marked private. */
@@ -1002,20 +1044,39 @@ export declare class Package extends Package_base {
   /**
    * Resolve `catalog:` and `workspace:` specifiers across all four dependency
    * maps using the `CatalogResolver` and `WorkspaceResolver` from context,
-   * classifying and projecting through `@effected/npm`'s `DependencySpecifier`
-   * statics (`workspace:` uses the pnpm publish-time projection; the alias
-   * form `workspace:<name>@<range>` resolves the TARGET package's version and
-   * becomes the published `npm:<name>@<range>` alias). Specifiers the
-   * resolvers return `None` for are left unchanged — resolution still
-   * succeeds. A `CatalogResolver` whose catalog assembly failed surfaces
-   * typed as `@effected/npm`'s `CatalogAssemblyError`, alongside the
-   * contracts' `DependencyResolutionError`. This is the explicit resolution
-   * step — `PackageJsonFile.write` never resolves.
+   * returning a new `Package`. This is the explicit resolution step —
+   * `PackageJsonFile.write` never resolves.
    *
    * @remarks
-   * Leaves unresolvable specifiers unchanged. For fail-typed manifest
+   * Classification and projection go through `@effected/npm`'s
+   * `DependencySpecifier` statics: `workspace:` uses the pnpm publish-time
+   * projection, and the alias form `workspace:<name>@<range>` resolves the
+   * TARGET package's version and becomes the published `npm:<name>@<range>`
+   * alias. Specifiers the resolvers answer `Option.none()` for are left
+   * unchanged — resolution still succeeds. Fails with `@effected/npm`'s
+   * `CatalogAssemblyError` when catalog assembly failed, or
+   * `DependencyResolutionError` when a resolver's mechanism failed; requires
+   * `CatalogResolver` and `WorkspaceResolver` in `R`. For fail-typed
    * resolution over the tolerant model, see `@effected/npm`'s
    * `Manifest#resolve`.
+   *
+   * @example
+   * ```ts
+   * import { Default } from "@effected/npm";
+   * import { Package } from "@effected/package-json";
+   * import { Effect } from "effect";
+   *
+   * const program = Effect.gen(function* () {
+   *   const pkg = yield* Package.decode({
+   *     name: "my-pkg",
+   *     version: "1.0.0",
+   *     dependencies: { effect: "catalog:" },
+   *   });
+   *   return yield* Package.resolve(pkg);
+   * }).pipe(Effect.provide(Default)); // the no-op resolvers leave `catalog:` unchanged
+   * ```
+   *
+   * @param pkg - the package whose specifiers to resolve
    */
   static readonly resolve: (pkg: Package) => Effect.Effect<Package, import("@effected/npm").CatalogAssemblyError | import("@effected/npm").DependencyResolutionError, CatalogResolver | WorkspaceResolver>;
   /**
@@ -1363,8 +1424,8 @@ export declare class LenientManifest extends LenientManifest_base {
    * {@link LenientManifest.decodeResult}, adding the tracing span.
    *
    * @param input - the parsed package.json JSON value (e.g. from `JSON.parse`)
-   * @returns an Effect resolving to the decoded {@link LenientManifest}
-   * @throws (typed) `PackageDecodeError` when `input` is not a JSON object
+   * @returns an Effect resolving to the decoded {@link LenientManifest},
+   * failing with {@link PackageDecodeError} when `input` is not a JSON object
    */
   static readonly decode: (input: unknown) => Effect.Effect<LenientManifest, PackageDecodeError, never>;
   /**
@@ -1383,8 +1444,8 @@ export declare class LenientManifest extends LenientManifest_base {
    * {@link LenientManifest.parseResult}, adding the tracing span.
    *
    * @param text - the package.json source text
-   * @returns an Effect resolving to the decoded {@link LenientManifest}
-   * @throws (typed) `PackageJsonSyntaxError` when the text is not valid JSON
+   * @returns an Effect resolving to the decoded {@link LenientManifest},
+   * failing with {@link PackageJsonSyntaxError} when the text is not valid JSON
    * or is not a JSON object
    */
   static readonly parse: (text: string) => Effect.Effect<LenientManifest, PackageJsonSyntaxError, never>;
@@ -1404,7 +1465,9 @@ export declare class LenientManifest extends LenientManifest_base {
  * @public
  */
 interface DevEnginePackageManagerEntry {
+  /** The package-manager name (e.g. `pnpm`). */
   readonly name: string;
+  /** The `<range>[+<integrity>]` version constraint; an entry without one names no range. */
   readonly version?: string | undefined;
 }
 declare const InvalidPackageManagerRangeError_base: Schema.Class<InvalidPackageManagerRangeError, Schema.TaggedStruct<"InvalidPackageManagerRangeError", {
@@ -1542,8 +1605,7 @@ export declare class PackageManagerRange extends PackageManagerRange_base {
    * @remarks
    * The entry's `name` is the package-manager name and its `version` is the
    * same `<range>[+<integrity>]` tail the `packageManager` field carries after
-   * its `@` — `^12.6.0`, `12.6.0`, or `12.6.0+sha512.<hex>` as
-   * `pnpm self-update` historically wrote it. Both are validated exactly as
+   * its `@` — `^12.6.0`, `12.6.0`, or `12.6.0+sha512.<hex>`. Both are validated exactly as
    * {@link PackageManagerRange.parseResult} validates them. The `version`
    * slot is optional on a {@link DevEngine}, but an entry without one names
    * no range, so it fails with `reason: "range"`; `onFail` is ignored. The
@@ -1725,11 +1787,11 @@ declare const PackageManifest_base: Schema.Class<PackageManifest, Schema.Struct<
  * @example
  * ```ts
  * import { PackageManifest } from "@effected/package-json";
- * import { Effect, Option } from "effect";
+ * import { Effect } from "effect";
  *
  * const program = Effect.gen(function* () {
  *   const root = yield* PackageManifest.decode({ private: true, packageManager: "pnpm@^11.20.0" });
- *   console.log(root.isPrivate, root.packageManager?.isExact); // true false
+ *   console.log(root.isPrivate); // => true
  * });
  * ```
  *
@@ -1749,9 +1811,8 @@ export declare class PackageManifest extends PackageManifest_base {
    * any `SchemaError` to a typed {@link PackageDecodeError} at the boundary.
    *
    * @param input - the parsed package.json JSON value (e.g. from `JSON.parse`)
-   * @returns an Effect resolving to the decoded `PackageManifest`
-   * @throws (typed) `PackageDecodeError` when a present field does not satisfy
-   * its codec
+   * @returns an Effect resolving to the decoded `PackageManifest`, failing with
+   * {@link PackageDecodeError} when a present field does not satisfy its codec
    */
   static readonly decode: (input: unknown) => Effect.Effect<PackageManifest, PackageDecodeError, never>;
   /** Whether the manifest is marked private. */
@@ -1891,9 +1952,10 @@ interface PackageJsonFileShape {
 }
 declare const PackageJsonFile_base: Context.ServiceClass<PackageJsonFile, "@effected/package-json/PackageJsonFile", PackageJsonFileShape>;
 /**
- * Reads and writes package.json over core `FileSystem` / `Path`. The layer
- * requires those services; provide `@effect/platform-node`'s `NodeFileSystem` /
- * `NodePath` (or a bun equivalent) at the application boundary.
+ * Reads, writes and surgically edits package.json files over core `FileSystem`
+ * / `Path`. The layer requires those services; provide
+ * `@effect/platform-node`'s `NodeFileSystem` / `NodePath` (or a bun equivalent)
+ * at the application boundary.
  *
  * @example
  * ```ts
@@ -1989,7 +2051,9 @@ declare const PackageValidator_base: Context.ServiceClass<PackageValidator, "@ef
 }>;
 /**
  * Validates a {@link Package} against a set of {@link ValidationRule}s,
- * aggregating every failure into one {@link PackageValidationError}.
+ * aggregating every failure into one {@link PackageValidationError}. Use
+ * `PackageValidator.layer` for {@link defaultRules} or `PackageValidator.layerRules`
+ * for a custom rule set.
  *
  * @example
  * ```ts
@@ -2001,6 +2065,8 @@ declare const PackageValidator_base: Context.ServiceClass<PackageValidator, "@ef
  *   const validator = yield* PackageValidator;
  *   yield* validator.validate(pkg);
  * }).pipe(Effect.provide(PackageValidator.layer));
+ * // fails with PackageValidationError: the default rules require a license,
+ * // a description and a repository, and forbid `private: true`
  * ```
  *
  * @public

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/package-json",
-	"version": "0.19.1",
+	"version": "0.20.0",
 	"private": false,
 	"description": "package.json parsing, editing, validation and file IO as Effect schemas.",
 	"keywords": [
@@ -38,13 +38,13 @@
 		"./package.json": "./package.json"
 	},
 	"dependencies": {
-		"@effected/jsonc": "^0.14.0",
-		"@effected/npm": "^0.19.0",
-		"@effected/semver": "^0.10.1",
-		"@effected/spdx": "^0.10.0"
+		"@effected/jsonc": "^0.15.0",
+		"@effected/npm": "^0.20.0",
+		"@effected/semver": "^0.11.0",
+		"@effected/spdx": "^0.11.0"
 	},
 	"peerDependencies": {
-		"effect": "4.0.0-rc.118"
+		"effect": "^4.0.0"
 	},
 	"engines": {
 		"node": ">=24.11.0"