@effected/package-json 0.6.1 → 0.7.0

package/Package.js

@@ -331,7 +331,8 @@ var Package = class Package extends Schema.Class("Package")({
 	* sorting and empty-map stripping unless the options opt out. Pure.
 	*/
 	toJsonString(options) {
-		return renderJson(Schema.encodeUnknownSync(Package.schema)(this), resolveFormatOptions(options));
+		const raw = Schema.encodeUnknownSync(Package.schema)(this);
+		return renderJson(raw, resolveFormatOptions(options));
 	}
 };
 

package/PackageManager.js

@@ -1,50 +1,104 @@
-import { IntegrityHash } from "@effected/npm";
+import { CorepackIntegrityHash } from "@effected/npm";
 import { Effect, Exit, Option, Schema, SchemaIssue, SchemaTransformation } from "effect";
+import { SemVer } from "@effected/semver";
 
 //#region src/PackageManager.ts
-const PACKAGE_MANAGER_RE = /^([a-z]+)@(\d+\.\d+\.\d+(?:-[a-zA-Z0-9._-]+)?)(?:\+(.+))?$/;
-/**
-* The `packageManager` field only ever carries corepack's `<algo>.<hex>`
-* integrity form (the `name@version+sha512.<hex>` tail). Restrict the
-* `@effected/npm` `IntegrityHash` brand — which also admits the SRI and yarn
-* forms — to just the corepack shape, so an SRI or yarn integrity here fails
-* typed rather than being accepted into a field that can never legitimately
-* hold it.
-*/
-const CorepackIntegrity = IntegrityHash.pipe(Schema.check(Schema.makeFilter((value) => IntegrityHash.isCorepack(value) ? void 0 : "Expected a corepack (<algo>.<hex>) integrity hash")));
+const PACKAGE_MANAGER_NAME_RE = /^[a-z]+$/;
+const invalid = (input, message) => Effect.fail(new SchemaIssue.InvalidValue(Option.some(input), { message }));
 /**
 * A structured `packageManager` value with `name`, `version` and an optional
 * `integrity` hash.
 *
+* @remarks
+* The same `<name>@<version>[+<integrity>]` triple `@effected/npm`'s
+* `PackageManagerPin` models, in its `package.json` field form. Both share the
+* strict pieces — the version is `@effected/semver`'s
+* `SemVer.PinnableVersionString` (decode rules through `SemVer.isPinnable`),
+* the integrity is npm's `CorepackIntegrityHash` — and
+* both apply the first-`+`-is-integrity rule. Reach for the pin when
+* provisioning a package manager; reach for this class when reading or writing
+* the manifest field.
+*
+* **The one deliberate divergence is the name grammar**, and it points this
+* way: the pin closes the set to the four managers the kit can provision
+* (`npm | pnpm | yarn | bun`), while this field model accepts any lowercase
+* name. The evidence:
+*
+* - 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.
+* - 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`).
+* - npm documents no constraint on this field at all. Its `package.json`
+*   reference constrains only `devEngines.packageManager.name` — a different
+*   field, modeled here by `DevEngine` and out of scope for this class.
+*
+* So: field model = manifests as they exist in the wild; pin = the kit's
+* provisioning vocabulary. A name outside the pin's four is representable here
+* and simply will not be installable through the pin — which is the honest
+* relationship between a document model and a provisioning contract.
+*
 * @public
 */
 var PackageManager = class PackageManager extends Schema.Class("PackageManager")({
-	/** The package-manager name (e.g. `pnpm`). */
+	/** The package-manager name (e.g. `pnpm`). Any lowercase name — see the class remarks. */
 	name: Schema.String,
-	/** The version (e.g. `10.33.0`). */
-	version: Schema.String,
-	/** The optional integrity hash (e.g. `sha512.abc`), an `@effected/npm` `IntegrityHash` restricted to the corepack `<algo>.<hex>` form. */
-	integrity: Schema.Option(CorepackIntegrity)
+	/**
+	* The version (e.g. `10.33.0`): `@effected/semver`'s
+	* `SemVer.PinnableVersionString` — an exact SemVer 2.0.0 version with no
+	* build metadata and no surrounding whitespace. Prerelease versions are
+	* 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`.
+	*/
+	version: SemVer.PinnableVersionString,
+	/**
+	* The optional integrity hash (e.g. `sha512.abc`): `@effected/npm`'s
+	* `CorepackIntegrityHash`, the shared restriction of the `IntegrityHash`
+	* brand to the corepack `<algo>.<hex>` form.
+	*/
+	integrity: Schema.Option(CorepackIntegrityHash)
 }) {
 	/**
 	* Schema transformation between the `"name@version+integrity"` string and a
 	* {@link PackageManager}.
+	*
+	* @remarks
+	* Decoding splits on the first `@`, then on the first `+` — which always
+	* begins the integrity, never semver build metadata — and validates each
+	* component: the name against the lowercase grammar, the version through
+	* `@effected/semver`'s strict parse, the integrity through
+	* `CorepackIntegrityHash`. Every failure is a typed decode failure naming
+	* the component that failed. Encoding prints the canonical string, which is
+	* byte-identical to any input this codec accepts.
 	*/
 	static FromString = Schema.String.pipe(Schema.decodeTo(Schema.instanceOf(PackageManager), SchemaTransformation.transformOrFail({
 		decode: (input) => {
-			const match = input.match(PACKAGE_MANAGER_RE);
-			if (match === null) return Effect.fail(new SchemaIssue.InvalidValue(Option.some(input), { message: `Invalid packageManager format: "${input}"` }));
-			const rawIntegrity = match[3];
-			if (rawIntegrity === void 0) return Effect.succeed(PackageManager.make({
-				name: match[1],
-				version: match[2],
+			const at = input.indexOf("@");
+			if (at === -1) return invalid(input, `Invalid packageManager format: "${input}"`);
+			const name = input.slice(0, at);
+			if (!PACKAGE_MANAGER_NAME_RE.test(name)) return invalid(input, `Invalid packageManager name: "${name}"`);
+			const rest = input.slice(at + 1);
+			const plus = rest.indexOf("+");
+			const version = plus === -1 ? rest : rest.slice(0, plus);
+			if (!SemVer.isPinnable(version)) return invalid(input, `Invalid packageManager version: "${version}"`);
+			if (plus === -1) return Effect.succeed(PackageManager.make({
+				name,
+				version,
 				integrity: Option.none()
 			}));
-			const decoded = Schema.decodeUnknownExit(CorepackIntegrity)(rawIntegrity);
-			if (Exit.isFailure(decoded)) return Effect.fail(new SchemaIssue.InvalidValue(Option.some(input), { message: `Invalid packageManager integrity: "${rawIntegrity}"` }));
+			const rawIntegrity = rest.slice(plus + 1);
+			const decoded = Schema.decodeUnknownExit(CorepackIntegrityHash)(rawIntegrity);
+			if (Exit.isFailure(decoded)) return invalid(input, `Invalid packageManager integrity: "${rawIntegrity}"`);
 			return Effect.succeed(PackageManager.make({
-				name: match[1],
-				version: match[2],
+				name,
+				version,
 				integrity: Option.some(decoded.value)
 			}));
 		},

package/index.d.ts

@@ -144,23 +144,78 @@ type SpdxLicense = string & Brand.Brand<"SpdxLicense">;
 //#endregion
 //#region src/PackageManager.d.ts
 declare const PackageManager_base: Schema.Class<PackageManager, Schema.Struct<{
-  /** The package-manager name (e.g. `pnpm`). */
+  /** The package-manager name (e.g. `pnpm`). Any lowercase name — see the class remarks. */
   readonly name: Schema.String;
-  /** The version (e.g. `10.33.0`). */
+  /**
+   * The version (e.g. `10.33.0`): `@effected/semver`'s
+   * `SemVer.PinnableVersionString` — an exact SemVer 2.0.0 version with no
+   * build metadata and no surrounding whitespace. Prerelease versions are
+   * 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`.
+   */
   readonly version: Schema.String;
-  /** The optional integrity hash (e.g. `sha512.abc`), an `@effected/npm` `IntegrityHash` restricted to the corepack `<algo>.<hex>` form. */
+  /**
+   * The optional integrity hash (e.g. `sha512.abc`): `@effected/npm`'s
+   * `CorepackIntegrityHash`, the shared restriction of the `IntegrityHash`
+   * brand to the corepack `<algo>.<hex>` form.
+   */
   readonly integrity: Schema.Option<Schema.brand<Schema.String, "IntegrityHash">>;
 }>, {}>;
 /**
  * A structured `packageManager` value with `name`, `version` and an optional
  * `integrity` hash.
  *
+ * @remarks
+ * The same `<name>@<version>[+<integrity>]` triple `@effected/npm`'s
+ * `PackageManagerPin` models, in its `package.json` field form. Both share the
+ * strict pieces — the version is `@effected/semver`'s
+ * `SemVer.PinnableVersionString` (decode rules through `SemVer.isPinnable`),
+ * the integrity is npm's `CorepackIntegrityHash` — and
+ * both apply the first-`+`-is-integrity rule. Reach for the pin when
+ * provisioning a package manager; reach for this class when reading or writing
+ * the manifest field.
+ *
+ * **The one deliberate divergence is the name grammar**, and it points this
+ * way: the pin closes the set to the four managers the kit can provision
+ * (`npm | pnpm | yarn | bun`), while this field model accepts any lowercase
+ * name. The evidence:
+ *
+ * - 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.
+ * - 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`).
+ * - npm documents no constraint on this field at all. Its `package.json`
+ *   reference constrains only `devEngines.packageManager.name` — a different
+ *   field, modeled here by `DevEngine` and out of scope for this class.
+ *
+ * So: field model = manifests as they exist in the wild; pin = the kit's
+ * provisioning vocabulary. A name outside the pin's four is representable here
+ * and simply will not be installable through the pin — which is the honest
+ * relationship between a document model and a provisioning contract.
+ *
  * @public
  */
 declare class PackageManager extends PackageManager_base {
   /**
    * Schema transformation between the `"name@version+integrity"` string and a
    * {@link PackageManager}.
+   *
+   * @remarks
+   * Decoding splits on the first `@`, then on the first `+` — which always
+   * begins the integrity, never semver build metadata — and validates each
+   * component: the name against the lowercase grammar, the version through
+   * `@effected/semver`'s strict parse, the integrity through
+   * `CorepackIntegrityHash`. Every failure is a typed decode failure naming
+   * the component that failed. Encoding prints the canonical string, which is
+   * byte-identical to any input this codec accepts.
    */
   static readonly FromString: Schema.Codec<PackageManager, string>;
   /** Whether an integrity hash is present. */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/package-json",
-	"version": "0.6.1",
+	"version": "0.7.0",
 	"private": false,
 	"description": "package.json parsing, editing, validation and file IO as Effect schemas.",
 	"keywords": [
@@ -38,8 +38,8 @@
 		"./package.json": "./package.json"
 	},
 	"dependencies": {
-		"@effected/npm": "~0.6.0",
-		"@effected/semver": "~0.2.1",
+		"@effected/npm": "~0.7.0",
+		"@effected/semver": "~0.3.0",
 		"@effected/spdx": "~0.1.1"
 	},
 	"peerDependencies": {