@effected/workspaces 0.28.0-next-20260927071821 → 0.29.0

package/README.md

@@ -163,16 +163,21 @@ A specifier the workspace cannot answer fails typed as `UnresolvedDependencyErro
 `PeerCheck.run(lockfile, options?)` reports unsatisfied peer dependencies as a pure value: no IO, no error channel, nothing in `R`, and no per-manager traversal logic. It reads `lockfile.format` once, to reject a format whose lockfile does not record peer resolution; past that gate the walk is the same for every manager. The answer comes from the resolved graph `@effected/lockfiles` normalizes, not from shelling out to a package manager's own peer command — bun has none, so the subprocess route cannot answer for every manager the rest of this package supports.
 
 ```ts
-import { LockfileReader, PeerCheck, WorkspaceCatalogs } from "@effected/workspaces";
+import { LockfileReader, PeerCheck, WorkspaceCatalogs, WorkspaceDiscovery } from "@effected/workspaces";
 import { Effect } from "effect";
 
 const program = Effect.gen(function* () {
   const reader = yield* LockfileReader;
   const catalogs = yield* WorkspaceCatalogs;
+  const discovery = yield* WorkspaceDiscovery;
 
   const lockfile = yield* reader.read();
-  // Presence of the key is the assertion — see below.
-  const report = PeerCheck.run(lockfile, { peerDependencyRules: yield* catalogs.peerDependencyRules() });
+  // Presence of each key is the assertion — see below.
+  const report = PeerCheck.run(lockfile, {
+    peerDependencyRules: yield* catalogs.peerDependencyRules(),
+    workspacePackages: yield* discovery.listPackages(),
+    catalogs: yield* catalogs.set(),
+  });
 
   return {
     clean:
@@ -190,10 +195,20 @@ const program = Effect.gen(function* () {
 
 - `supported` is `false` for yarn, which resolves peers virtually and does not record which virtual instance satisfied which peer. The answer is unrecoverable, so it is not fabricated.
 - `unresolvedImporters` names importers that could not be joined to package instances — in practice the root importer under npm and bun, neither of which records a resolved version per importer dependency.
-- `unverified` says why the report is not a complete answer: `"peerRulesNotApplied"` when the suppression policy could not be applied, `"unresolvedEdge"` when an instance records an edge the model could not name. Both mean fail closed.
+- `unverified` says why the report is not a complete answer, and every reason means fail closed:
+  - `"peerRulesNotApplied"` — the `peerDependencyRules` key was omitted, so pnpm's suppression policy was not applied.
+  - `"unresolvedEdge"` — an instance records an edge the model could not name, or an importer dependency resolved through `link:` whose linked manifest's peers were not judged: its target was not supplied in `workspacePackages`, or the lockfile records no workspace row to walk. A linked parent's manifest peers are never in the lockfile, though `pnpm peers check` reads them from disk.
+  - `"peerRangeUnresolved"` — a linked manifest declares a peer as a protocol specifier that could not be turned into a range (`catalog:` with the `catalogs` key omitted or no matching entry, `workspace:*`), and something resolved for that peer, so the comparison never ran.
+  - `"peerVersionUnresolved"` — a peer resolved to a non-workspace provider whose version is a protocol specifier rather than a version: a `file:` directory or tarball, directly or through a `file:` override, which the lockfile records as `file:vendor/x` with no version for a directory, and a git or remote-tarball provider, which pnpm keys by its URL (`https://codeload.github.com/…`). The comparison never runs, so the peer is neither reported nor passed as satisfied; for a `file:` directory `pnpm peers check` reports it as a `bad` row even when the directory's manifest satisfies the range. It applies to peers declared by lockfile rows and by joined manifests alike.
 - `required` is the getter for the rows a gate should act on — the non-optional ones. An unsatisfied *optional* peer is normal, so `optional` travels with the row rather than being filtered out at the source.
 
-`WorkspaceCatalogs.peerDependencyRules()` returns the workspace's effective merged pnpm suppression rules, which the lockfile records nowhere; without them a checker reports findings pnpm itself calls clean. **Presence of the `peerDependencyRules` option key is the assertion, not its contents.** Passing `NoPeerDependencyRules` asserts the workspace has none, so the report carries no `"peerRulesNotApplied"` — though it can still be unverified for another reason, or unsupported; omitting the key says nobody looked, and always yields `"peerRulesNotApplied"`. Only `allowedVersions` is applied — rules populating `ignoreMissing` or `allowAny` describe a policy this package does not replicate, so they fail closed through the same reason rather than being silently ignored. All three key spellings pnpm accepts are honoured: `parent@version>peer` (what `pnpm:export` writes), `parent>peer` (what a config-dependency plugin injects) and a bare `peer`, which pnpm applies to every parent that declares it.
+`WorkspaceCatalogs.peerDependencyRules()` returns the workspace's effective merged pnpm suppression rules, which the lockfile records nowhere; without them a checker reports findings pnpm itself calls clean. **Presence of the `peerDependencyRules` option key is the assertion, not its contents.** Passing `NoPeerDependencyRules` asserts the workspace has none, so the report carries no `"peerRulesNotApplied"` — though it can still be unverified for another reason, or unsupported; omitting the key says nobody looked, and always yields `"peerRulesNotApplied"`. **All three axes of the supplied rules are applied**, with pnpm's measured semantics. `allowedVersions` hides a row whose resolved version a matching key's range permits, in all three key spellings pnpm accepts: `parent@version>peer` (what `pnpm:export` writes; the parent version is ignored, as pnpm ignores it), `parent>peer` (what a config-dependency plugin injects) and a bare `peer`, which pnpm applies to every parent that declares it. `ignoreMissing` hides a required peer nothing resolved for, and `allowAny` hides a peer that resolved outside its range; both are `@pnpm/matcher` patterns over the PEER name (`*` wildcard, leading `!` negates), never `parent>peer` keys, and the two never cross.
+
+The `workspacePackages` option takes the packages `WorkspaceDiscovery` already returned, and supplying it is what turns a `link:`-resolved parent from a refusal into an answer: the matched manifest's declared peers join the walk, named from the manifest (`probe-a@1.0.0`, not the row's `packages/a@0.0.0`) and judged against the **importer's own** dependency set, which is where pnpm resolves them from. Measured one variable at a time on the probe workspace, against pnpm 12.5.1 and 12.6.0: a consumer's own `react@18.3.1` satisfies the linked parent's `^18.0.0` peer, the same version installed only by a sibling importer does not, and a consumer's own `react@17.0.2` is a `bad` row carrying `foundVersion`. A target the set does not cover — every target, when the key is omitted — keeps `"unresolvedEdge"`, so the option answers only for what it covers and says so about the rest. A covered target the walk cannot reach — one the lockfile records no workspace row for — keeps the marker too; the root importer's linked targets are walked and judged against the root's own dependencies, as pnpm does.
+
+A `link:` target matches a supplied package by its directory or by its publish directory: pnpm links a workspace dependency into `publishConfig.directory` unless `publishConfig.linkDirectory` is `false` (it defaults to true), recording `link:../a/dist`. For such a link pnpm reads the built manifest at the target, while `PeerCheck` reads the source manifest and resolves its `catalog:` ranges through `catalogs`; the two agree when the build emits the ranges the source's specifiers resolve to. Attribution stops at a workspace package: a linked package's manifest peers are judged only for the importer that links it directly, and its own dependencies (registry or linked) only for its own importer, never for a consumer one link further out. Each `link:` edge is cleared only by the walk of the importer that records it.
+
+The `catalogs` option takes `WorkspaceCatalogs.set()`, which already includes hook-injected catalogs. A linked manifest may declare a peer as a catalog specifier (`"typescript": "catalog:build:peers"`) rather than a range; with the set supplied it is resolved, judged, and reported by the resolved range, which is what `pnpm peers check` reports as `wantedRange`. A specifier that stays unresolvable — the key omitted, a catalog naming nothing for the peer, or another protocol such as `workspace:*` — is never passed as satisfied: when something resolved for that peer the report carries `"peerRangeUnresolved"`, and when nothing did the `found: null` row is reported anyway, since a missing provider needs no range.
 
 ## The synchronous escape hatch
 

package/WorkspaceCatalogs.js

@@ -1,3 +1,4 @@
+import { findLayerRoot } from "./internal/layerRoot.js";
 import { WorkspaceRoot } from "./WorkspaceRoot.js";
 import { inlineCatalogs, merge, normalize, rangeOf } from "./internal/catalogs.js";
 import { ConfigDependencyHooks, NoPeerDependencyRules } from "./ConfigDependencyHooks.js";
@@ -342,7 +343,7 @@ var WorkspaceCatalogs = class WorkspaceCatalogs extends Context.Service()("@effe
 			}));
 		}));
 		const assemble = Effect.gen(function* () {
-			const root = yield* Effect.suspend(() => roots.find(options?.cwd ?? process.cwd()));
+			const root = yield* findLayerRoot(roots, options);
 			const lockfileOutputs = yield* lockfiles.read().pipe(Effect.map((lockfile) => ({
 				catalogs: CatalogSet.fromLockfile(lockfile),
 				importerVersions: importerVersionsOf(lockfile)

package/WorkspaceDiscovery.js

@@ -1,4 +1,5 @@
 import { enumerate } from "./internal/enumerate.js";
+import { findLayerRoot } from "./internal/layerRoot.js";
 import { readPatterns } from "./internal/patterns.js";
 import { WorkspacePackage } from "./WorkspacePackage.js";
 import { WorkspaceRoot } from "./WorkspaceRoot.js";
@@ -256,8 +257,7 @@ var WorkspaceDiscovery = class WorkspaceDiscovery extends Context.Service()("@ef
 			};
 		}).pipe(Effect.provideService(FileSystem.FileSystem, fs), Effect.provideService(Path.Path, path));
 		const discover = Effect.gen(function* () {
-			const stopAt = options?.stopAt;
-			const root = yield* Effect.suspend(() => roots.find(options?.cwd ?? process.cwd(), stopAt === void 0 ? void 0 : { stopAt }));
+			const root = yield* findLayerRoot(roots, options);
 			return yield* discoverAt(root);
 		});
 		const [resolveOnce, invalidate] = yield* Effect.cachedInvalidateWithTTL(discover, Duration.infinity);
@@ -548,7 +548,8 @@ var WorkspaceDiscovery = class WorkspaceDiscovery extends Context.Service()("@ef
 				const version = index.get(packageName);
 				return version === void 0 ? Effect.fail(new DependencyResolutionError({
 					specifier,
-					cause: /* @__PURE__ */ new Error(`Workspace member "${packageName}" declares no version`)
+					reason: "no-version",
+					cause: void 0
 				})) : Effect.succeed(Option.some(version));
 			}));
 		} };

package/WorkspaceSnapshots.js

@@ -1,3 +1,4 @@
+import { findLayerRoot } from "./internal/layerRoot.js";
 import { manifestPatternsOf, pnpmPatternsOf } from "./internal/patterns.js";
 import { WorkspaceRoot } from "./WorkspaceRoot.js";
 import { WorkspaceDiscovery } from "./WorkspaceDiscovery.js";
@@ -51,10 +52,10 @@ const snapshotOf = (content, relativePath) => {
 	const parsed = parseJsonObject(content.value);
 	const name = parsed.name;
 	if (typeof name !== "string" || name.length === 0) return Option.none();
-	const version = typeof parsed.version === "string" ? parsed.version : "";
+	const version = parsed.version;
 	return Option.some(PackageStateSnapshot.make({
 		name,
-		version,
+		...typeof version === "string" && version !== "" ? { version } : {},
 		relativePath,
 		...isStringRecord(parsed.dependencies) ? { dependencies: parsed.dependencies } : {},
 		...isStringRecord(parsed.devDependencies) ? { devDependencies: parsed.devDependencies } : {},
@@ -210,7 +211,7 @@ var WorkspaceSnapshots = class WorkspaceSnapshots extends Context.Service()("@ef
 		const atCaches = /* @__PURE__ */ new Map();
 		return {
 			at: Effect.fn("WorkspaceSnapshots.at")(function* (ref) {
-				const root = yield* Effect.suspend(() => roots.find(options?.cwd ?? process.cwd()));
+				const root = yield* findLayerRoot(roots, options);
 				const key = `${root}\0${ref}`;
 				let memo = atCaches.get(key);
 				if (memo === void 0) {
@@ -232,7 +233,7 @@ var WorkspaceSnapshots = class WorkspaceSnapshots extends Context.Service()("@ef
 				const hookReplays = yield* catalogsService.hookReplays();
 				const snapshotPackages = packages.map((pkg) => PackageStateSnapshot.make({
 					name: pkg.name,
-					version: pkg.version ?? "",
+					...pkg.version === void 0 ? {} : { version: pkg.version },
 					relativePath: pkg.relativePath,
 					dependencies: pkg.dependencies,
 					devDependencies: pkg.devDependencies,

package/WorkspaceStateSnapshot.js

@@ -1,12 +1,27 @@
 import { unanimousVersionOf } from "./internal/importerVersions.js";
 import { CatalogSet } from "./WorkspaceCatalogs.js";
-import { Effect, Exit, Layer, Option, Schema } from "effect";
+import { Effect, Exit, Layer, Option, Schema, SchemaTransformation } from "effect";
 import { CatalogResolver, DependencyResolutionError, DependencySpecifier, WorkspaceResolver } from "@effected/npm";
 
 //#region src/WorkspaceStateSnapshot.ts
 const EMPTY = Object.freeze(Object.create(null));
 const DependencyMap = Schema.Record(Schema.String, Schema.String).pipe(Schema.withDecodingDefaultKey(Effect.succeed(EMPTY)), Schema.withConstructorDefault(Effect.succeed(EMPTY)));
 /**
+* A snapshot's `version` field: absent when the manifest declared none, and
+* never `""`.
+*
+* @remarks
+* The Type side is a `NonEmptyString`, so `make` rejects `""` outright. The
+* encoded side stays a plain optional string for one reason only: snapshots
+* serialized while `""` was the "declared no version" sentinel must still
+* decode, and they decode to the absent key they always meant — so an old
+* stored value and a fresh capture of the same manifest compare equal.
+*/
+const SnapshotVersion = Schema.optionalKey(Schema.String).pipe(Schema.decodeTo(Schema.optionalKey(Schema.NonEmptyString), SchemaTransformation.transformOptional({
+	decode: (encoded) => Option.filter(encoded, (version) => version !== ""),
+	encode: (version) => version
+})));
+/**
 * One workspace member as captured in a {@link WorkspaceStateSnapshot} — the
 * serializable slice a snapshot diff reads: identity, version, location, and the
 * four dependency records.
@@ -24,23 +39,24 @@ var PackageStateSnapshot = class extends Schema.Class("PackageStateSnapshot")({
 	/** The package name. */
 	name: Schema.NonEmptyString,
 	/**
-	* The raw `version` string, as recorded at the captured moment — or `""` for
+	* The raw `version` string, as recorded at the captured moment — absent 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 `"^"`.
+	* Optional exactly as `WorkspacePackage.version` is: a version-less member is
+	* an ordinary pnpm shape. Both capture paths — `WorkspaceSnapshots.at(ref)`
+	* and `WorkspaceSnapshots.worktree()` — omit the key for such a member, so
+	* the two sides of a diff agree without a placeholder. Never `""`: `make`
+	* rejects it, and a snapshot serialized when `""` was the "no version"
+	* sentinel decodes to the absent key.
+	*
+	* A version-less member is still a member: it appears in `packages` and
+	* answers {@link WorkspaceStateSnapshot.package}, but is absent from
+	* {@link WorkspaceStateSnapshot.versions}, resolves a `workspace:` specifier
+	* to `Option.none()`, and fails its snapshot-bound `WorkspaceResolver`'s
+	* `versionOf` typed.
 	*/
-	version: Schema.String,
+	version: SnapshotVersion,
 	/** POSIX path relative to the workspace root; `"."` for the root package. */
 	relativePath: Schema.String,
 	/** Production dependencies. */
@@ -166,7 +182,11 @@ var WorkspaceStateSnapshot = class WorkspaceStateSnapshot extends Schema.Class("
 	#workspaceResolver;
 	#resolvers;
 	#versions() {
-		if (this.#versionIndex === void 0) this.#versionIndex = new Map(this.packages.map((pkg) => [pkg.name, pkg.version]));
+		if (this.#versionIndex === void 0) {
+			const index = /* @__PURE__ */ new Map();
+			for (const pkg of this.packages) if (pkg.version !== void 0) index.set(pkg.name, pkg.version);
+			this.#versionIndex = index;
+		}
 		return this.#versionIndex;
 	}
 	#packages() {
@@ -174,15 +194,13 @@ var WorkspaceStateSnapshot = class WorkspaceStateSnapshot extends Schema.Class("
 		return this.#packageIndex;
 	}
 	/**
-	* Every captured package's name → version. Total; O(1) after the first call.
+	* Every captured package's name → version, for the packages that declared
+	* one. 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.
+	* A member whose manifest declared no version is **absent** from this map,
+	* so every value is a real version and presence answers "has a version",
+	* not membership — ask {@link WorkspaceStateSnapshot.package} for that.
 	*/
 	get versions() {
 		return this.#versions();
@@ -268,10 +286,7 @@ var WorkspaceStateSnapshot = class WorkspaceStateSnapshot extends Schema.Class("
 				const fromCatalogs = this.#catalogRange(dependency, classified.name);
 				return Option.isSome(fromCatalogs) ? fromCatalogs : onUnresolvedCatalog();
 			}
-			case "workspace": {
-				const version = this.#versions().get(dependency);
-				return version === void 0 || version === "" ? Option.none() : Option.some(version);
-			}
+			case "workspace": return Option.fromUndefinedOr(this.#versions().get(dependency));
 			default: return Option.none();
 		}
 	}
@@ -422,11 +437,13 @@ var WorkspaceStateSnapshot = class WorkspaceStateSnapshot extends Schema.Class("
 	*/
 	get workspaceResolver() {
 		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({
+			const member = this.#packages().get(packageName);
+			if (member === void 0) return Effect.succeed(Option.none());
+			const version = member.version;
+			if (version === void 0) return Effect.fail(new DependencyResolutionError({
 				specifier: `workspace:${packageName}`,
-				cause: /* @__PURE__ */ new Error(`Workspace member "${packageName}" declares no version`)
+				reason: "no-version",
+				cause: void 0
 			}));
 			return Effect.succeed(Option.some(version));
 		} });

package/Workspaces.js

@@ -48,7 +48,8 @@ const localExecLayer = (options) => Layer.effect(LocalExec, Effect.gen(function*
 	const detector = yield* PackageManagerDetector;
 	return { context: Effect.gen(function* () {
 		const cwd = options?.cwd ?? globalThis.process?.cwd?.() ?? "/";
-		const root = yield* roots.find(cwd).pipe(Effect.asSome, Effect.orElseSucceed(Option.none));
+		const stopAt = options?.stopAt;
+		const root = yield* roots.find(cwd, stopAt === void 0 ? void 0 : { stopAt }).pipe(Effect.asSome, Effect.orElseSucceed(Option.none));
 		if (Option.isNone(root)) return Option.none();
 		const detected = yield* detector.detect(root.value).pipe(Effect.asSome, Effect.catchTag("PackageManagerDetectionError", () => Effect.succeed(Option.none())), Effect.mapError((cause) => new LocalExecError({
 			directory: root.value,
@@ -289,7 +290,10 @@ var Workspaces = class {
 	* verbatim.
 	*
 	* `directory` is the resolved **workspace root**, not the caller's cwd: a
-	* project-local launcher has to run where the workspace is.
+	* project-local launcher has to run where the workspace is. `stopAt` caps
+	* that ascent exactly as {@link WorkspacesOptions.stopAt} does, and a
+	* ceiling with no root at or below it is the same `Option.none()` as no
+	* root at all.
 	*
 	* A consumer with no monorepo never needs this layer, and therefore never
 	* installs this package — `LocalExec.layerNone` and `LocalExec.layerFor`

package/WorkspacesSync.js

@@ -120,9 +120,17 @@ const isPackage = (options, dir) => options.fileSystem.exists(options.path.join(
 * Markers match the async service exactly: a `pnpm-workspace.yaml`, or a
 * `package.json` carrying a `workspaces` field.
 *
+* The ascent is unbounded unless `options.stopAt` names a ceiling
+* ({@link FindWorkspaceRootSyncOptions.stopAt}), with the Effect surface's
+* semantics: inclusive, resolved at lookup time. Where `WorkspaceRoot.find`
+* fails `WorkspaceRootNotFoundError` carrying the resolved ceiling, this
+* returns `null` — the facade is total and has no error channel, and the
+* caller already holds the ceiling it passed.
+*
 * @param cwd - Where to start the ascent (typically `process.cwd()`),
 *   matching the Effect layers' `{ cwd }` option.
-* @param options - The consumer-supplied file and path operations.
+* @param options - The consumer-supplied file and path operations, plus an
+*   optional `stopAt` ceiling.
 *
 * @example
 * ```ts
@@ -146,10 +154,12 @@ const isPackage = (options, dir) => options.fileSystem.exists(options.path.join(
 const findWorkspaceRootSync = (cwd, options) => {
 	const { fileSystem, path } = options;
 	let current = path.resolve(cwd);
+	const ceiling = options.stopAt === void 0 ? void 0 : path.resolve(options.stopAt);
 	for (let depth = 0; depth < 32 * 8; depth++) {
 		if (fileSystem.exists(path.join(current, "pnpm-workspace.yaml"))) return current;
 		const manifest = readJson(fileSystem, path.join(current, "package.json"));
 		if (manifest?.workspaces !== void 0 && manifest.workspaces !== null) return current;
+		if (ceiling !== void 0 && current === ceiling) return null;
 		const parent = path.dirname(current);
 		if (parent === current) return null;
 		current = parent;