@effected/workspaces 0.18.3 → 0.19.0

package/README.md

@@ -193,7 +193,7 @@ const packages = root === null ? [] : getWorkspacePackagesSync(root, nodeSyncOps
 // packages: the discovered workspace packages, empty when there is no root
 ```
 
-Both entry points take their path positionally, so the bag usually passes through verbatim; spread it to add `getWorkspacePackagesSync`'s traversal extras — `{ ...nodeSyncOps, maxDepth }`. The bindings are a separate subpath deliberately: the main entry imports nothing platform-shaped, and re-exporting them from it would drag `node:*` into every consumer, including the ones supplying their own operations. `nodePath` is the running platform's `node:path`, so on Windows the paths handed back are win32 paths.
+Both entry points take their path positionally, so the bag usually passes through verbatim; spread it to add `getWorkspacePackagesSync`'s traversal extras — `{ ...nodeSyncOps, maxDepth, onSkip }`. The function is total, so it cannot fail on a manifest it cannot use — but it never drops one silently either: `onSkip` receives a `WorkspaceDiscoverySkip` (`root`, `path`, `kind`, `cause`) for every manifest left out, with the same `kind` the Effect surface would have failed with, so "no packages" and "packages rejected" stay distinguishable. A manifest with no `version` is not skipped on either surface; it is a member with `version` absent, as pnpm treats it. The bindings are a separate subpath deliberately: the main entry imports nothing platform-shaped, and re-exporting them from it would drag `node:*` into every consumer, including the ones supplying their own operations. `nodePath` is the running platform's `node:path`, so on Windows the paths handed back are win32 paths.
 
 Write the operations yourself when Node's built-ins are not the platform you mean — a Bun or Deno binding, a test fake, or `node:path/win32` to pin a dialect rather than follow the running platform. Each one is a one-liner:
 
@@ -293,7 +293,7 @@ A name miss in the derived `getPackage` fails with the service's own typed `Pack
 - `Workspaces.resolverLayer` / `Workspaces.resolveManifest` — the one-call manifest-resolution path: a fresh, unmemoized layer per call so root discovery follows your cwd, and one-shot resolution of a whole `Manifest` against the real workspace.
 - `WorkspaceRoot` — root discovery from a `cwd`, over `WORKSPACE_MARKERS`.
 - `WorkspaceDiscovery` — package enumeration with a bounded descent for segment-crossing `packages/**` patterns, per-package lookup and the `makeTest` / `layerTest` in-memory test doubles.
-- `WorkspacePackage` — a deliberately tolerant manifest model, so one member with an odd version cannot fail discovery for the whole repo. `manifestRecord` keeps the as-read `package.json` for tolerant access to fields outside the typed slice without a second read; `WorkspacePackage.manifest(pkg)` re-reads and is the opt-in bridge to `@effected/package-json`'s strict `Package`.
+- `WorkspacePackage` — a deliberately tolerant manifest model, so one member with an odd version cannot fail discovery for the whole repo. `version` is optional and carried exactly as the manifest has it — absent for the ordinary version-less private root or member, never a `"0.0.0"` placeholder; a `version` that is present but not a string is `invalidShape`. `manifestRecord` keeps the as-read `package.json` for tolerant access to fields outside the typed slice without a second read; `WorkspacePackage.manifest(pkg)` re-reads and is the opt-in bridge to `@effected/package-json`'s strict `Package`.
 - `DependencyGraph` — a value class over discovered packages: `levels()` for parallel build tiers, the flattened topological order, `toMermaid()` for a deterministic Mermaid `flowchart TD` of the whole graph, and `CyclicDependencyError` — naming the cycle's actual members — when there is no order.
 - `PackageManagerDetector` — npm, pnpm, yarn or bun from lockfiles and the `packageManager` field.
 - `WorkspaceCatalogs` — pnpm catalog assembly and `catalog:` resolution, on pnpm's own catalog packages; `releaseAgeGate()` assembles the effective `@effected/npm` `ReleaseAgeGate` from inline `pnpm-workspace.yaml` release-age keys and replayed hook contributions, strictest-wins, in the same pass as the catalogs.

package/WorkspaceDiscovery.js

@@ -9,12 +9,20 @@ import { DependencyResolutionError, WorkspaceResolver } from "@effected/npm";
 //#region src/WorkspaceDiscovery.ts
 /**
 * Raised when a workspace member's `package.json` cannot be read, parsed, or
-* used — it is missing, malformed, or lacks a `name` or `version`.
+* used — it is missing, malformed, or lacks a `name`.
 *
 * @remarks
 * `kind` is the discriminant a caller branches on; `cause` preserves the
 * originating failure rather than flattening it into a sentence.
 *
+* A manifest with no `version` is NOT a failure: pnpm accepts a version-less
+* private package and a private monorepo root without one is the ordinary
+* shape, so the member is discovered with `WorkspacePackage.version` absent.
+* The former `missingVersion` kind is retired. Only ABSENCE is tolerated: a
+* `version` that is present but not a string — or present and `""`, which pnpm
+* never wrote and which would resolve `workspace:^` to a bare `"^"` — is the
+* manifest's shape being wrong and reports `invalidShape`.
+*
 * @public
 */
 var WorkspaceDiscoveryError = class extends Schema.TaggedError()("WorkspaceDiscoveryError", {
@@ -28,8 +36,7 @@ var WorkspaceDiscoveryError = class extends Schema.TaggedError()("WorkspaceDisco
 		"invalidJson",
 		"invalidShape",
 		"invalidYaml",
-		"missingName",
-		"missingVersion"
+		"missingName"
 	]),
 	/** The originating failure, if there was one. */
 	cause: Schema.Defect()
@@ -172,15 +179,21 @@ var WorkspaceDiscovery = class WorkspaceDiscovery extends Context.Service()("@ef
 				cause: void 0
 			}));
 			const version = raw.version;
-			if (typeof version !== "string" || version.length === 0) return yield* Effect.fail(new WorkspaceDiscoveryError({
+			if (version !== void 0 && typeof version !== "string") return yield* Effect.fail(new WorkspaceDiscoveryError({
 				root,
 				path: packageJsonPath,
-				kind: "missingVersion",
-				cause: void 0
+				kind: "invalidShape",
+				cause: /* @__PURE__ */ new Error(`version must be a string, got ${typeof version}`)
+			}));
+			if (version === "") return yield* Effect.fail(new WorkspaceDiscoveryError({
+				root,
+				path: packageJsonPath,
+				kind: "invalidShape",
+				cause: /* @__PURE__ */ new Error("version must be a non-empty string")
 			}));
 			return yield* Schema.decodeUnknownEffect(WorkspacePackage)({
 				name,
-				version,
+				...version !== void 0 ? { version } : {},
 				path: directory,
 				packageJsonPath,
 				relativePath,
@@ -494,6 +507,12 @@ var WorkspaceDiscovery = class WorkspaceDiscovery extends Context.Service()("@ef
 	* channel is reserved for a failure of the resolution *mechanism* (an
 	* unfindable root, an unreadable manifest), never an ordinary miss.
 	*
+	* A member that declares **no `version`** is neither: it is a known member
+	* with nothing for `workspace:` to resolve to. Answering `none` would read
+	* as "not a member" downstream, so it fails typed instead, naming the
+	* specifier — the same channel a consumer already handles for an
+	* unresolvable workspace.
+	*
 	* @example
 	* ```ts
 	* import { Package } from "@effected/package-json";
@@ -517,10 +536,21 @@ var WorkspaceDiscovery = class WorkspaceDiscovery extends Context.Service()("@ef
 			versionIndexes.set(all, index);
 			return index;
 		};
-		return { versionOf: (packageName) => discovery.listPackages().pipe(Effect.map((all) => Option.fromUndefinedOr(versionsByName(all).get(packageName))), Effect.mapError((cause) => new DependencyResolutionError({
-			specifier: `workspace:${packageName}`,
-			cause
-		}))) };
+		return { versionOf: (packageName) => {
+			const specifier = `workspace:${packageName}`;
+			return discovery.listPackages().pipe(Effect.mapError((cause) => new DependencyResolutionError({
+				specifier,
+				cause
+			})), Effect.flatMap((all) => {
+				const index = versionsByName(all);
+				if (!index.has(packageName)) return Effect.succeed(Option.none());
+				const version = index.get(packageName);
+				return version === void 0 ? Effect.fail(new DependencyResolutionError({
+					specifier,
+					cause: /* @__PURE__ */ new Error(`Workspace member "${packageName}" declares no version`)
+				})) : Effect.succeed(Option.some(version));
+			}));
+		} };
 	}));
 };
 const isStringRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value) && Object.values(value).every((entry) => typeof entry === "string");

package/WorkspacePackage.js

@@ -91,8 +91,24 @@ var WorkspaceManifestError = class extends Schema.TaggedError()("WorkspaceManife
 var WorkspacePackage = class WorkspacePackage extends Schema.Class("WorkspacePackage")({
 	/** The package name. */
 	name: Schema.NonEmptyString,
-	/** The raw `version` string — deliberately not semver-validated. */
-	version: Schema.String,
+	/**
+	* The raw `version` string — deliberately not semver-validated — or absent
+	* when the manifest declares none.
+	*
+	* @remarks
+	* pnpm accepts a version-less private package, and a private monorepo root
+	* without a `version` is the ordinary shape, so discovery carries the field
+	* exactly as the manifest has it: a non-empty string when present, verbatim
+	* and un-validated, absent when the key is absent — never a `"0.0.0"`
+	* placeholder and never a present `undefined` key. **Only ABSENCE is
+	* tolerated**: a `version` that is present but not a string, or present and
+	* `""`, fails discovery as `invalidShape` on both surfaces. `""` in
+	* particular is not a pnpm shape and would resolve `workspace:^` to a bare
+	* `"^"`.
+	* Anything that needs a concrete version (`WorkspaceResolver.versionOf`,
+	* a release tag) answers the absence itself rather than inventing one.
+	*/
+	version: Schema.optionalKey(Schema.String),
 	/** Absolute path to the package directory. */
 	path: Schema.NonEmptyString,
 	/** Absolute path to the package's `package.json`. */

package/WorkspaceSnapshots.js

@@ -197,7 +197,7 @@ var WorkspaceSnapshots = class WorkspaceSnapshots extends Context.Service()("@ef
 				const importerVersions = yield* catalogsService.importerVersions();
 				const snapshotPackages = packages.map((pkg) => PackageStateSnapshot.make({
 					name: pkg.name,
-					version: pkg.version,
+					version: pkg.version ?? "",
 					relativePath: pkg.relativePath,
 					dependencies: pkg.dependencies,
 					devDependencies: pkg.devDependencies,

package/WorkspaceStateSnapshot.js

@@ -1,7 +1,7 @@
 import { unanimousVersionOf } from "./internal/importerVersions.js";
 import { CatalogSet } from "./WorkspaceCatalogs.js";
 import { Effect, Exit, Layer, Option, Schema } from "effect";
-import { CatalogResolver, DependencySpecifier, WorkspaceResolver } from "@effected/npm";
+import { CatalogResolver, DependencyResolutionError, DependencySpecifier, WorkspaceResolver } from "@effected/npm";
 
 //#region src/WorkspaceStateSnapshot.ts
 const EMPTY = Object.freeze(Object.create(null));
@@ -23,7 +23,23 @@ const DependencyMap = Schema.Record(Schema.String, Schema.String).pipe(Schema.wi
 var PackageStateSnapshot = class extends Schema.Class("PackageStateSnapshot")({
 	/** The package name. */
 	name: Schema.NonEmptyString,
-	/** The raw `version` string, as recorded at the captured moment. */
+	/**
+	* The raw `version` string, as recorded at the captured moment — or `""` for
+	* a manifest that declared none.
+	*
+	* @remarks
+	* `WorkspacePackage.version` is optional and a version-less member is an
+	* ordinary pnpm shape, but this field stays a plain required string because a
+	* snapshot is a serialized value someone stores and diffs: an absent key and
+	* a present one would read as a change the moment one side of a diff was
+	* captured by a different code path. **`""` is therefore the sentinel for
+	* "the manifest declared no version", not a version anyone can use** — both
+	* `snapshotOf` at a ref and the worktree snapshot write it, so the two sides
+	* agree. Every resolution surface treats it as absence:
+	* {@link WorkspaceStateSnapshot.resolve} answers `Option.none()` for a
+	* `workspace:` specifier against it, because `some("")` would rewrite
+	* `workspace:^` as a bare `"^"`.
+	*/
 	version: Schema.String,
 	/** POSIX path relative to the workspace root; `"."` for the root package. */
 	relativePath: Schema.String,
@@ -137,7 +153,17 @@ var WorkspaceStateSnapshot = class WorkspaceStateSnapshot extends Schema.Class("
 		if (this.#packageIndex === void 0) this.#packageIndex = new Map(this.packages.map((pkg) => [pkg.name, pkg]));
 		return this.#packageIndex;
 	}
-	/** Every captured package's name → version. Total; O(1) after the first call. */
+	/**
+	* Every captured package's name → version. Total; O(1) after the first call.
+	*
+	* @remarks
+	* Values are `PackageStateSnapshot.version` verbatim, so a member whose
+	* manifest declared no version maps to the **`""` sentinel** rather than
+	* being absent from the map — presence here answers membership, not
+	* "has a usable version". A caller reading a version out of this map owes
+	* the `""` check itself; {@link WorkspaceStateSnapshot.resolve} already
+	* makes it.
+	*/
 	get versions() {
 		return this.#versions();
 	}
@@ -222,7 +248,10 @@ var WorkspaceStateSnapshot = class WorkspaceStateSnapshot extends Schema.Class("
 				const fromCatalogs = this.#catalogRange(dependency, classified.name);
 				return Option.isSome(fromCatalogs) ? fromCatalogs : onUnresolvedCatalog();
 			}
-			case "workspace": return Option.fromUndefinedOr(this.#versions().get(dependency));
+			case "workspace": {
+				const version = this.#versions().get(dependency);
+				return version === void 0 || version === "" ? Option.none() : Option.some(version);
+			}
 			default: return Option.none();
 		}
 	}
@@ -368,7 +397,15 @@ var WorkspaceStateSnapshot = class WorkspaceStateSnapshot extends Schema.Class("
 	* `workspace:` specifiers as of this ref. Built once per instance and cached.
 	*/
 	get workspaceResolver() {
-		if (this.#workspaceResolver === void 0) this.#workspaceResolver = Layer.succeed(WorkspaceResolver, { versionOf: (packageName) => Effect.succeed(Option.fromUndefinedOr(this.#versions().get(packageName))) });
+		if (this.#workspaceResolver === void 0) this.#workspaceResolver = Layer.succeed(WorkspaceResolver, { versionOf: (packageName) => {
+			const version = this.#versions().get(packageName);
+			if (version === void 0) return Effect.succeed(Option.none());
+			if (version === "") return Effect.fail(new DependencyResolutionError({
+				specifier: `workspace:${packageName}`,
+				cause: /* @__PURE__ */ new Error(`Workspace member "${packageName}" declares no version`)
+			}));
+			return Effect.succeed(Option.some(version));
+		} });
 		return this.#workspaceResolver;
 	}
 	/** Both snapshot-scoped resolver layers merged. Built once per instance and cached. */

package/WorkspacesSync.js

@@ -7,6 +7,38 @@ import { Yaml } from "@effected/yaml";
 
 //#region src/WorkspacesSync.ts
 /**
+* Read one `package.json` into a plain record, or say why not. Never throws.
+*
+* The three failures are kept apart — a throwing consumer `readFile`, a JSON
+* syntax error, and valid JSON that is not an object — because the skip report
+* carries the distinction; the two other callers of {@link readJson} do not
+* need it and keep the collapsed form.
+*/
+const readManifest = (fileSystem, file) => {
+	let text;
+	try {
+		text = fileSystem.readFile(file);
+	} catch (cause) {
+		return {
+			kind: "read",
+			cause
+		};
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch (cause) {
+		return {
+			kind: "invalidJson",
+			cause
+		};
+	}
+	return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? { raw: parsed } : {
+		kind: "invalidShape",
+		cause: /* @__PURE__ */ new Error("package.json is not a JSON object")
+	};
+};
+/**
 * Read and JSON-parse a file into a plain object, or `undefined`. Never throws.
 *
 * The non-object check is load-bearing, not defensive noise. `JSON.parse`
@@ -143,21 +175,47 @@ const readPatternsSync = (options, root) => {
 	}
 	return manifestPatternsOf(readJson(fileSystem, path.join(root, "package.json")) ?? {});
 };
-/** Build a `WorkspacePackage` from a directory, or `null` if its manifest is unusable. */
+/**
+* Build a `WorkspacePackage` from a directory, or a {@link WorkspaceDiscoverySkip}
+* saying why its manifest is unusable — never `null`, so a skip cannot go
+* unreported.
+*/
 const readPackageSync = (options, root, directory, relativePath) => {
 	const packageJsonPath = options.path.join(directory, "package.json");
-	const raw = readJson(options.fileSystem, packageJsonPath);
-	if (raw === void 0) return null;
+	const read = readManifest(options.fileSystem, packageJsonPath);
+	if (!("raw" in read)) return {
+		root,
+		path: packageJsonPath,
+		kind: read.kind,
+		cause: read.cause
+	};
+	const raw = read.raw;
 	const name = raw.name;
+	if (typeof name !== "string" || name.length === 0) return {
+		root,
+		path: packageJsonPath,
+		kind: "missingName",
+		cause: void 0
+	};
 	const version = raw.version;
-	if (typeof name !== "string" || name.length === 0) return null;
-	if (typeof version !== "string" || version.length === 0) return null;
+	if (version !== void 0 && typeof version !== "string") return {
+		root,
+		path: packageJsonPath,
+		kind: "invalidShape",
+		cause: /* @__PURE__ */ new Error(`version must be a string, got ${typeof version}`)
+	};
+	if (version === "") return {
+		root,
+		path: packageJsonPath,
+		kind: "invalidShape",
+		cause: /* @__PURE__ */ new Error("version must be a non-empty string")
+	};
 	const stringRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value) && Object.values(value).every((entry) => typeof entry === "string") ? value : void 0;
 	const publishConfig = raw.publishConfig;
 	const config = publishConfig !== null && typeof publishConfig === "object" ? Effect.runSyncExit(Schema.decodeUnknownEffect(PublishConfig)(publishConfig)) : void 0;
 	return WorkspacePackage.make({
 		name,
-		version,
+		...version !== void 0 ? { version } : {},
 		path: directory,
 		packageJsonPath,
 		relativePath,
@@ -194,6 +252,13 @@ const readPackageSync = (options, root, directory, relativePath) => {
 * caller mistakes: a `maxDepth` that is not a positive integer throws, matching
 * the enumerator's defect.
 *
+* **A skip is never silent.** Every manifest left out is reported through
+* `onSkip` with its path and the same `kind` the Effect surface would have
+* failed with (a `WorkspaceDiscoverySkip`), so "no packages" and "packages
+* rejected" stay distinguishable. A manifest with no `version` is NOT skipped:
+* pnpm accepts a version-less private package, so it is a member with
+* `version` absent — on both surfaces.
+*
 * @param root - The workspace root, from {@link findWorkspaceRootSync}.
 * @param options - The consumer-supplied operations and traversal bounds; see
 *   {@link GetWorkspacePackagesSyncOptions}.
@@ -261,13 +326,18 @@ const getWorkspacePackagesSync = (root, options) => {
 		}
 	}
 	const members = [];
+	const admit = (read) => {
+		if (read instanceof WorkspacePackage) members.push(read);
+		else options.onSkip?.(read);
+	};
 	for (const [relativePath, absolute] of [...included.entries()].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) {
 		if (relativePath === "." || absolute === root) continue;
-		const pkg = readPackageSync(options, root, absolute, relativePath);
-		if (pkg !== null) members.push(pkg);
+		admit(readPackageSync(options, root, absolute, relativePath));
 	}
 	const rootPackage = readPackageSync(options, root, root, ".");
-	return rootPackage === null ? members : [rootPackage, ...members];
+	if (rootPackage instanceof WorkspacePackage) return [rootPackage, ...members];
+	options.onSkip?.(rootPackage);
+	return members;
 };
 
 //#endregion

package/index.d.ts

@@ -83,8 +83,24 @@ declare class WorkspaceManifestError extends WorkspaceManifestError_base {
 declare const WorkspacePackage_base: Schema.Class<WorkspacePackage, Schema.Struct<{
   /** The package name. */
   readonly name: Schema.NonEmptyString;
-  /** The raw `version` string — deliberately not semver-validated. */
-  readonly version: Schema.String;
+  /**
+   * The raw `version` string — deliberately not semver-validated — or absent
+   * when the manifest declares none.
+   *
+   * @remarks
+   * pnpm accepts a version-less private package, and a private monorepo root
+   * without a `version` is the ordinary shape, so discovery carries the field
+   * exactly as the manifest has it: a non-empty string when present, verbatim
+   * and un-validated, absent when the key is absent — never a `"0.0.0"`
+   * placeholder and never a present `undefined` key. **Only ABSENCE is
+   * tolerated**: a `version` that is present but not a string, or present and
+   * `""`, fails discovery as `invalidShape` on both surfaces. `""` in
+   * particular is not a pnpm shape and would resolve `workspace:^` to a bare
+   * `"^"`.
+   * Anything that needs a concrete version (`WorkspaceResolver.versionOf`,
+   * a release tag) answers the absence itself rather than inventing one.
+   */
+  readonly version: Schema.optionalKey<Schema.String>;
   /** Absolute path to the package directory. */
   readonly path: Schema.NonEmptyString;
   /** Absolute path to the package's `package.json`. */
@@ -417,18 +433,26 @@ declare const WorkspaceDiscoveryError_base: Schema.Class<WorkspaceDiscoveryError
   /** The file that failed. */
   readonly path: Schema.String;
   /** What went wrong with it. */
-  readonly kind: Schema.Literals<readonly ["read", "invalidJson", "invalidShape", "invalidYaml", "missingName", "missingVersion"]>;
+  readonly kind: Schema.Literals<readonly ["read", "invalidJson", "invalidShape", "invalidYaml", "missingName"]>;
   /** The originating failure, if there was one. */
   readonly cause: Schema.Defect;
 }>, import("effect/Cause").YieldableError>;
 /**
  * Raised when a workspace member's `package.json` cannot be read, parsed, or
- * used — it is missing, malformed, or lacks a `name` or `version`.
+ * used — it is missing, malformed, or lacks a `name`.
  *
  * @remarks
  * `kind` is the discriminant a caller branches on; `cause` preserves the
  * originating failure rather than flattening it into a sentence.
  *
+ * A manifest with no `version` is NOT a failure: pnpm accepts a version-less
+ * private package and a private monorepo root without one is the ordinary
+ * shape, so the member is discovered with `WorkspacePackage.version` absent.
+ * The former `missingVersion` kind is retired. Only ABSENCE is tolerated: a
+ * `version` that is present but not a string — or present and `""`, which pnpm
+ * never wrote and which would resolve `workspace:^` to a bare `"^"` — is the
+ * manifest's shape being wrong and reports `invalidShape`.
+ *
  * @public
  */
 declare class WorkspaceDiscoveryError extends WorkspaceDiscoveryError_base {
@@ -722,6 +746,12 @@ declare class WorkspaceDiscovery extends WorkspaceDiscovery_base {
    * channel is reserved for a failure of the resolution *mechanism* (an
    * unfindable root, an unreadable manifest), never an ordinary miss.
    *
+   * A member that declares **no `version`** is neither: it is a known member
+   * with nothing for `workspace:` to resolve to. Answering `none` would read
+   * as "not a member" downstream, so it fails typed instead, naming the
+   * specifier — the same channel a consumer already handles for an
+   * unresolvable workspace.
+   *
    * @example
    * ```ts
    * import { Package } from "@effected/package-json";
@@ -2689,7 +2719,23 @@ declare class WorkspaceCatalogs extends WorkspaceCatalogs_base {
 declare const PackageStateSnapshot_base: Schema.Class<PackageStateSnapshot, Schema.Struct<{
   /** The package name. */
   readonly name: Schema.NonEmptyString;
-  /** The raw `version` string, as recorded at the captured moment. */
+  /**
+   * The raw `version` string, as recorded at the captured moment — or `""` for
+   * a manifest that declared none.
+   *
+   * @remarks
+   * `WorkspacePackage.version` is optional and a version-less member is an
+   * ordinary pnpm shape, but this field stays a plain required string because a
+   * snapshot is a serialized value someone stores and diffs: an absent key and
+   * a present one would read as a change the moment one side of a diff was
+   * captured by a different code path. **`""` is therefore the sentinel for
+   * "the manifest declared no version", not a version anyone can use** — both
+   * `snapshotOf` at a ref and the worktree snapshot write it, so the two sides
+   * agree. Every resolution surface treats it as absence:
+   * {@link WorkspaceStateSnapshot.resolve} answers `Option.none()` for a
+   * `workspace:` specifier against it, because `some("")` would rewrite
+   * `workspace:^` as a bare `"^"`.
+   */
   readonly version: Schema.String;
   /** POSIX path relative to the workspace root; `"."` for the root package. */
   readonly relativePath: Schema.String;
@@ -2800,7 +2846,17 @@ declare const WorkspaceStateSnapshot_base: Schema.Class<WorkspaceStateSnapshot,
  */
 declare class WorkspaceStateSnapshot extends WorkspaceStateSnapshot_base {
   #private;
-  /** Every captured package's name → version. Total; O(1) after the first call. */
+  /**
+   * Every captured package's name → version. Total; O(1) after the first call.
+   *
+   * @remarks
+   * Values are `PackageStateSnapshot.version` verbatim, so a member whose
+   * manifest declared no version maps to the **`""` sentinel** rather than
+   * being absent from the map — presence here answers membership, not
+   * "has a usable version". A caller reading a version out of this map owes
+   * the `""` check itself; {@link WorkspaceStateSnapshot.resolve} already
+   * makes it.
+   */
   get versions(): ReadonlyMap<string, string>;
   /** A single captured package by name, or `Option.none()`. Total. */
   package(name: string): Option.Option<PackageStateSnapshot>;
@@ -3631,6 +3687,61 @@ interface WorkspacesSyncOptions {
   /** The synchronous path implementation (Node: the `node:path` module itself). */
   readonly path: SyncPath;
 }
+/**
+ * Why {@link getWorkspacePackagesSync} left a manifest out of its result — the
+ * `WorkspaceDiscoveryError.kind` values a single manifest read can produce.
+ *
+ * @remarks
+ * The same vocabulary the Effect surface fails with, deliberately: a member the
+ * async `listPackages()` rejects as `missingName` is the member the sync facade
+ * reports as `missingName`. `invalidYaml` is excluded because it describes the
+ * `pnpm-workspace.yaml` read, not a manifest. There is no `missingVersion` —
+ * a version-less manifest is a member on both surfaces.
+ *
+ * The vocabulary is shared; the CHECKS are shared only as far as this list.
+ * Both surfaces perform the same five: the file read (`read`), `JSON.parse`
+ * (`invalidJson`), the parsed value being a non-null non-array object
+ * (`invalidShape`), a non-empty string `name` (`missingName`), and a `version`
+ * that is either absent or a non-empty string (`invalidShape`). Beyond them
+ * they diverge, and one divergence is deliberate: a malformed `publishConfig`
+ * FAILS the async surface, because it reaches the decode, while the sync facade
+ * drops the field and keeps the member. A consumer that must reject such a
+ * manifest has to use the Effect surface.
+ *
+ * @public
+ */
+type WorkspaceDiscoverySkipKind = Exclude<WorkspaceDiscoveryError["kind"], "invalidYaml">;
+/**
+ * One manifest {@link getWorkspacePackagesSync} skipped, reported through
+ * {@link GetWorkspacePackagesSyncOptions.onSkip}.
+ *
+ * @remarks
+ * The sync facade is total, so it cannot fail the way `WorkspaceDiscovery`
+ * does — but a skipped member must still be observable. Before this record
+ * existed the skip was silent, and a hand-written fixture with one unusable
+ * manifest enumerated as a plausible empty array indistinguishable from "no
+ * workspaces configured" (issue #605). The fields mirror
+ * `WorkspaceDiscoveryError`: `root`, `path`, `kind`, and on `cause` either the
+ * caught throwable (`read` / `invalidJson`) or an `Error` carrying the same
+ * sentence the Effect surface fails with (`invalidShape`). Only `missingName`
+ * has `cause: undefined` — the field is simply absent, and nothing threw.
+ *
+ * @public
+ */
+interface WorkspaceDiscoverySkip {
+  /** The workspace root the enumeration ran against. */
+  readonly root: string;
+  /** Absolute path to the `package.json` that was skipped. */
+  readonly path: string;
+  /** Why it was skipped. */
+  readonly kind: WorkspaceDiscoverySkipKind;
+  /**
+   * The thrown value for `read` and `invalidJson`, an `Error` whose message
+   * matches the Effect surface's for `invalidShape`, and `undefined` for
+   * `missingName` alone.
+   */
+  readonly cause: unknown;
+}
 /**
  * The nearest workspace root at or above `cwd`, or `null`.
  *
@@ -3689,6 +3800,21 @@ interface GetWorkspacePackagesSyncOptions extends WorkspacesSyncOptions {
    * @defaultValue 32
    */
   readonly maxDepth?: number;
+  /**
+   * Called once for every manifest the enumeration found and could not use,
+   * with the file and the reason — so a skipped member is observable even
+   * though this function is total and has no error channel to raise it on.
+   *
+   * @remarks
+   * Omit it and skips are simply not reported, which is the pre-existing
+   * behaviour; nothing is logged in its place. The callback is invoked
+   * synchronously, before the result is returned, in enumeration order —
+   * members first, then the root, which is read last even though it is
+   * returned first. Its
+   * result is discarded, and a throw from it propagates: the facade is total
+   * over *data*, not over caller mistakes, exactly as a bad `maxDepth` is.
+   */
+  readonly onSkip?: ((skip: WorkspaceDiscoverySkip) => void) | undefined;
 }
 /**
  * Every workspace package under `root`, root package first.
@@ -3713,6 +3839,13 @@ interface GetWorkspacePackagesSyncOptions extends WorkspacesSyncOptions {
  * caller mistakes: a `maxDepth` that is not a positive integer throws, matching
  * the enumerator's defect.
  *
+ * **A skip is never silent.** Every manifest left out is reported through
+ * `onSkip` with its path and the same `kind` the Effect surface would have
+ * failed with (a `WorkspaceDiscoverySkip`), so "no packages" and "packages
+ * rejected" stay distinguishable. A manifest with no `version` is NOT skipped:
+ * pnpm accepts a version-less private package, so it is a member with
+ * `version` absent — on both surfaces.
+ *
  * @param root - The workspace root, from {@link findWorkspaceRootSync}.
  * @param options - The consumer-supplied operations and traversal bounds; see
  *   {@link GetWorkspacePackagesSyncOptions}.
@@ -3740,5 +3873,5 @@ interface GetWorkspacePackagesSyncOptions extends WorkspacesSyncOptions {
  */
 declare const getWorkspacePackagesSync: (root: string, options: GetWorkspacePackagesSyncOptions) => ReadonlyArray<WorkspacePackage>;
 //#endregion
-export { type CatalogAssemblyFailure, CatalogSet, ChangeDetectionError, type ChangeDetectionFailure, ChangeDetectionOptions, ChangeDetector, type ChangeDetectorShape, type ClassifyOptions, ConfigDependencyHooks, type ConfigDependencyHooksShape, CyclicDependencyError, type DependencyDiff, DependencyGraph, DetectedPackageManager, type FindWorkspaceRootOptions, type GetWorkspacePackagesSyncOptions, type HookInjection, type ImporterVersions, LockfileReadError, type LockfileReadFailure, LockfileReader, type LockfileReaderOptions, type LockfileReaderShape, NoPeerDependencyRules, PackageManagerDetectionError, type PackageManagerDetectionFailure, PackageManagerDetector, type PackageManagerDetectorShape, PackageManagerEvidence, PackageManagerName, PackageNotFoundError, type PackageRelease, PackageStateSnapshot, PeerCheck, type PeerCheckOptions, type PeerDependencyRules, PeerParent, PublishConfig, PublishTarget, PublishabilityDetector, type PublishabilityDetectorShape, ReleaseTag, type SyncDirectoryEntry, type SyncFileSystem, type SyncPath, type TagClassification, type TagFormatOptions, TagStyle, TrackingTag, type TrackingTagOptions, UnsatisfiedPeer, type UnverifiedReason, type VersioningDetectOptions, VersioningStrategy, VersioningStrategyType, WORKSPACE_MARKERS, WorkspaceCatalogs, type WorkspaceCatalogsOptions, type WorkspaceCatalogsShape, WorkspaceDiscovery, WorkspaceDiscoveryError, type WorkspaceDiscoveryFailure, type WorkspaceDiscoveryOptions, type WorkspaceDiscoveryShape, WorkspaceInfo, type WorkspaceLookupFailure, WorkspaceManifestError, WorkspacePackage, WorkspacePatternError, WorkspaceRoot, WorkspaceRootNotFoundError, type WorkspaceRootShape, type WorkspaceSnapshotAtFailure, type WorkspaceSnapshotWorktreeFailure, WorkspaceSnapshots, type WorkspaceSnapshotsOptions, type WorkspaceSnapshotsShape, WorkspaceStateSnapshot, Workspaces, type WorkspacesGitOptions, type WorkspacesOptions, type WorkspacesServices, type WorkspacesSyncOptions, classifyTag, findWorkspaceRootSync, getWorkspacePackagesSync };
+export { type CatalogAssemblyFailure, CatalogSet, ChangeDetectionError, type ChangeDetectionFailure, ChangeDetectionOptions, ChangeDetector, type ChangeDetectorShape, type ClassifyOptions, ConfigDependencyHooks, type ConfigDependencyHooksShape, CyclicDependencyError, type DependencyDiff, DependencyGraph, DetectedPackageManager, type FindWorkspaceRootOptions, type GetWorkspacePackagesSyncOptions, type HookInjection, type ImporterVersions, LockfileReadError, type LockfileReadFailure, LockfileReader, type LockfileReaderOptions, type LockfileReaderShape, NoPeerDependencyRules, PackageManagerDetectionError, type PackageManagerDetectionFailure, PackageManagerDetector, type PackageManagerDetectorShape, PackageManagerEvidence, PackageManagerName, PackageNotFoundError, type PackageRelease, PackageStateSnapshot, PeerCheck, type PeerCheckOptions, type PeerDependencyRules, PeerParent, PublishConfig, PublishTarget, PublishabilityDetector, type PublishabilityDetectorShape, ReleaseTag, type SyncDirectoryEntry, type SyncFileSystem, type SyncPath, type TagClassification, type TagFormatOptions, TagStyle, TrackingTag, type TrackingTagOptions, UnsatisfiedPeer, type UnverifiedReason, type VersioningDetectOptions, VersioningStrategy, VersioningStrategyType, WORKSPACE_MARKERS, WorkspaceCatalogs, type WorkspaceCatalogsOptions, type WorkspaceCatalogsShape, WorkspaceDiscovery, WorkspaceDiscoveryError, type WorkspaceDiscoveryFailure, type WorkspaceDiscoveryOptions, type WorkspaceDiscoveryShape, type WorkspaceDiscoverySkip, type WorkspaceDiscoverySkipKind, WorkspaceInfo, type WorkspaceLookupFailure, WorkspaceManifestError, WorkspacePackage, WorkspacePatternError, WorkspaceRoot, WorkspaceRootNotFoundError, type WorkspaceRootShape, type WorkspaceSnapshotAtFailure, type WorkspaceSnapshotWorktreeFailure, WorkspaceSnapshots, type WorkspaceSnapshotsOptions, type WorkspaceSnapshotsShape, WorkspaceStateSnapshot, Workspaces, type WorkspacesGitOptions, type WorkspacesOptions, type WorkspacesServices, type WorkspacesSyncOptions, classifyTag, findWorkspaceRootSync, getWorkspacePackagesSync };
 //# sourceMappingURL=index.d.ts.map

package/node-sync.d.ts

@@ -1,7 +1,8 @@
+import "@effected/npm";
+import "effect";
 import "@effected/glob";
 import "@effected/lockfiles";
 import "@effected/package-json";
-import "effect";
 //#region src/WorkspacesSync.d.ts
 /**
  * The synchronous file operations the sync entry points need, supplied by the

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/workspaces",
-	"version": "0.18.3",
+	"version": "0.19.0",
 	"private": false,
 	"description": "Monorepo workspace tooling as Effect services — root discovery, package enumeration, the dependency graph, package-manager detection, pnpm catalog resolution, lockfile IO and git-based change detection.",
 	"keywords": [
@@ -52,7 +52,7 @@
 		"@effected/lockfiles": "^0.7.1",
 		"@effected/npm": "^0.12.1",
 		"@effected/package-json": "^0.13.0",
-		"@effected/semver": "^0.5.0",
+		"@effected/semver": "^0.5.1",
 		"@effected/walker": "^0.5.0",
 		"@effected/yaml": "^0.12.0",
 		"@pnpm/catalogs.config": "^1100.0.5",