@effected/workspaces 0.7.0 → 0.8.0

package/LockfileReader.js

@@ -27,6 +27,8 @@ var LockfileReadError = class extends Schema.TaggedErrorClass()("LockfileReadErr
 		return `Cannot read ${this.format} lockfile at ${this.lockfilePath}`;
 	}
 };
+/** A defect naming the unstubbed test-double method — a test-wiring mistake, not a typed failure. */
+const unstubbed = (method) => Effect.die(/* @__PURE__ */ new Error(`LockfileReader.makeTest: ${method}() was called but not stubbed — pass a \`${method}\` override.`));
 /**
 * Reads and parses the workspace's lockfile.
 *
@@ -112,6 +114,74 @@ var LockfileReader = class LockfileReader extends Context.Service()("@effected/w
 	* `const` and reuse it.
 	*/
 	static layer = (options) => Layer.effect(LockfileReader, LockfileReader.make(options));
+	/**
+	* A test double satisfying the full {@link LockfileReaderShape} with no
+	* filesystem, root walk, or package-manager detection.
+	*
+	* @remarks
+	* There is **no honest default lockfile**: an empty one that looks like a
+	* legitimate answer is indistinguishable from "this workspace resolves
+	* nothing" — the silent-empty failure class this package documents on the
+	* live paths — so `read` **dies** with an instructive defect until stubbed.
+	*
+	* The one derivation mirrors `WorkspaceDiscovery.makeTest`'s
+	* derived-from-the-primary rule: when a `read` override is supplied,
+	* `resolvedVersion` answers as the live service does — the **first** entry
+	* of `lockfile.packagesNamed(name)` in lockfile order, `Option.none()` on a
+	* miss — so the two stay consistent by construction. `integrity` is **not**
+	* derivable: the live method compares the lockfile against the workspace
+	* manifests discovery enumerates, and the double has no discovery to ask, so
+	* it dies unless stubbed.
+	*
+	* `refresh` defaults to `Effect.void` honestly: the live contract is "drop
+	* the memoized read so the next call re-reads", and this double memoizes
+	* nothing — every `read()` call re-invokes the override — so there is
+	* nothing to drop and the no-op is truthful, the same reasoning as
+	* `WorkspaceDiscovery.makeTest`'s `refresh`.
+	*
+	* @example
+	* ```ts
+	* import { Lockfile } from "@effected/lockfiles";
+	* import { LockfileReader } from "@effected/workspaces";
+	* import { Effect } from "effect";
+	*
+	* const double = LockfileReader.makeTest({
+	*   read: () =>
+	*     Effect.succeed(
+	*       Lockfile.make({ format: "pnpm", lockfileVersion: "9.0", packages: [], workspaceDependencies: [] }),
+	*     ),
+	* });
+	* // `resolvedVersion` now answers consistently from that lockfile.
+	* ```
+	*/
+	static makeTest = (overrides = {}) => {
+		const read = overrides.read;
+		return {
+			read: () => unstubbed("read"),
+			resolvedVersion: read !== void 0 ? (packageName) => Effect.map(read(), (lockfile) => Option.fromUndefinedOr(lockfile.packagesNamed(packageName)[0])) : () => unstubbed("resolvedVersion"),
+			integrity: () => unstubbed("integrity"),
+			refresh: () => Effect.void,
+			...overrides
+		};
+	};
+	/**
+	* The test layer: {@link LockfileReader.makeTest} behind `Layer.succeed`, so
+	* a suite provides only the methods it exercises.
+	*
+	* @remarks
+	* A parameterized layer factory mints a **fresh reference per call**, and
+	* layers memoize by reference — bind the result to a `const` and reuse it
+	* rather than calling `layerTest(...)` at each composition site.
+	*
+	* @example
+	* ```ts
+	* import { LockfileReader } from "@effected/workspaces";
+	*
+	* const TestLockfiles = LockfileReader.layerTest();
+	* // program.pipe(Effect.provide(TestLockfiles)) — dies loudly if touched.
+	* ```
+	*/
+	static layerTest = (overrides = {}) => Layer.succeed(LockfileReader, LockfileReader.makeTest(overrides));
 };
 
 //#endregion

package/README.md

@@ -134,7 +134,21 @@ A specifier the workspace cannot answer fails typed as `UnresolvedDependencyErro
 
 ## The synchronous escape hatch
 
-Vitest's config-time project discovery cannot await. Two functions exist for exactly that case, and they run synchronously over file and path operations you supply — the module itself imports nothing platform-shaped, and Node's built-ins satisfy the operations one-liner each:
+Vitest's config-time project discovery cannot await. Two functions exist for exactly that case, and they run synchronously over file and path operations you supply. On Node you do not have to write them: the `@effected/workspaces/node-sync` subpath exports `nodeSyncOps`, the ready-made `node:fs` and `node:path` bindings, so adopting the sync path is one extra import.
+
+```ts
+import { findWorkspaceRootSync, getWorkspacePackagesSync } from "@effected/workspaces";
+import { nodeSyncOps } from "@effected/workspaces/node-sync";
+
+const root = findWorkspaceRootSync(process.cwd(), nodeSyncOps);
+const packages = root === null ? [] : getWorkspacePackagesSync(root, nodeSyncOps);
+// root: the workspace root path, or null when none is found above the cwd
+// 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.
+
+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:
 
 ```ts
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
@@ -157,7 +171,7 @@ const packages = root === null ? [] : getWorkspacePackagesSync(root, options);
 // packages: the discovered workspace packages, empty when there is no root
 ```
 
-Windows correctness is the operations you pass — `node:path` on Windows is already win32-appropriate. Both entry points drive one traversal state machine (the same dequeue order, depth rule, visit budget and `node_modules` prune), so the sync and Effect surfaces can never disagree about what a pattern means. The one deliberate difference is at a bound: the Effect enumerator fails typed, the sync one truncates. Prefer the Effect API everywhere you can run one.
+Windows correctness is therefore the operations you pass, and nothing else. Both entry points drive one traversal state machine (the same dequeue order, depth rule, visit budget and `node_modules` prune), so the sync and Effect surfaces can never disagree about what a pattern means. The one deliberate difference is at a bound: the Effect enumerator fails typed, the sync one truncates. Prefer the Effect API everywhere you can run one.
 
 ## Error handling
 
@@ -220,6 +234,7 @@ A name miss in the derived `getPackage` fails with the service's own typed `Pack
 - `ChangeDetector` — git-range change detection over `@effected/git`'s `Git` service; swap the layer to mock it with no repository.
 - `PublishabilityDetector` — whether a package publishes and to where, as a `PublishTarget` (registry, directory, access, provenance). The default layer implements npm's semantics; swap the layer if yours differ.
 - `findWorkspaceRootSync` / `getWorkspacePackagesSync` — the synchronous escape hatch for config-time callers that cannot await, over file and path operations you supply.
+- `@effected/workspaces/node-sync` — a second entry point holding the Node bindings for those operations (`nodeFileSystem`, `nodePath` and the `nodeSyncOps` bag), kept off the main entry so `node:*` never reaches a consumer that supplies its own.
 
 ## License
 

package/WorkspaceCatalogs.js

@@ -283,6 +283,8 @@ const validatePnpmWorkspaceCatalogs = (document) => {
 		catalogs: "catalogs"
 	}));
 };
+/** A defect naming the unstubbed test-double method — a test-wiring mistake, not a typed failure. */
+const unstubbed = (method) => Effect.die(/* @__PURE__ */ new Error(`WorkspaceCatalogs.makeTest: ${method}() was called but not stubbed — pass a \`${method}\` override.`));
 /**
 * Assembles a workspace's catalogs, package-manager-aware.
 *
@@ -426,6 +428,70 @@ var WorkspaceCatalogs = class WorkspaceCatalogs extends Context.Service()("@effe
 	*/
 	static layerWithConfigDependencies = (options) => Layer.effect(WorkspaceCatalogs, WorkspaceCatalogs.make(options)).pipe(Layer.provide(ConfigDependencyHooks.layerLive));
 	/**
+	* A test double satisfying the full {@link WorkspaceCatalogsShape} with no
+	* filesystem, lockfile read, or hook replay.
+	*
+	* @remarks
+	* There is **no honest default catalog set**: an empty `CatalogSet` that
+	* looks like a legitimate answer is the "every dependency looks newly added"
+	* failure class the live assembler hard-fails to prevent, so every method
+	* **dies** with an instructive defect until stubbed — a test-wiring mistake
+	* fails loudly as a defect rather than succeeding with a lie or failing with
+	* a dishonest typed error.
+	*
+	* The one derivation mirrors `WorkspaceDiscovery.makeTest`'s
+	* derived-from-the-primary rule: when a `set` override is supplied,
+	* `resolveSpecifier` answers from that `CatalogSet`'s own
+	* {@link CatalogSet.resolveSpecifier} — exactly what the live service runs
+	* over its assembled set — so the two stay consistent by construction.
+	* `releaseAgeGate` and `importerVersions` are **not** derivable from a
+	* catalog set (the gate comes from release-age keys and hook contributions,
+	* the importer index from the lockfile's importer blocks — neither is in a
+	* `CatalogSet`) and always die unless stubbed.
+	*
+	* @example
+	* ```ts
+	* import { CatalogSet, WorkspaceCatalogs } from "@effected/workspaces";
+	* import { Effect } from "effect";
+	*
+	* const double = WorkspaceCatalogs.makeTest({
+	*   set: () => Effect.succeed(CatalogSet.fromCatalogs({ default: { effect: "4.0.0" } })),
+	* });
+	* // `resolveSpecifier` now answers consistently from that set.
+	* ```
+	*/
+	static makeTest = (overrides = {}) => {
+		const set = overrides.set;
+		return {
+			set: () => unstubbed("set"),
+			resolveSpecifier: set !== void 0 ? (dependency, specifier) => Effect.map(set(), (catalogs) => catalogs.resolveSpecifier(dependency, specifier)) : () => unstubbed("resolveSpecifier"),
+			releaseAgeGate: () => unstubbed("releaseAgeGate"),
+			importerVersions: () => unstubbed("importerVersions"),
+			...overrides
+		};
+	};
+	/**
+	* The test layer: {@link WorkspaceCatalogs.makeTest} behind `Layer.succeed`,
+	* so a suite provides only the methods it exercises.
+	*
+	* @remarks
+	* A parameterized layer factory mints a **fresh reference per call**, and
+	* layers memoize by reference — bind the result to a `const` and reuse it
+	* rather than calling `layerTest(...)` at each composition site.
+	*
+	* @example
+	* ```ts
+	* import { CatalogSet, WorkspaceCatalogs } from "@effected/workspaces";
+	* import { Effect } from "effect";
+	*
+	* const TestCatalogs = WorkspaceCatalogs.layerTest({
+	*   set: () => Effect.succeed(CatalogSet.empty()),
+	* });
+	* // program.pipe(Effect.provide(TestCatalogs))
+	* ```
+	*/
+	static layerTest = (overrides = {}) => Layer.succeed(WorkspaceCatalogs, WorkspaceCatalogs.makeTest(overrides));
+	/**
 	* The real implementation of `@effected/npm`'s `CatalogResolver` contract —
 	* the one `@effected/package-json` declares but cannot fill.
 	*

package/index.d.ts

@@ -1212,6 +1212,65 @@ declare class LockfileReader extends LockfileReader_base {
    * `const` and reuse it.
    */
   static readonly layer: (options?: LockfileReaderOptions) => Layer.Layer<LockfileReader, never, WorkspaceRoot | PackageManagerDetector | WorkspaceDiscovery | FileSystem.FileSystem | Path.Path>;
+  /**
+   * A test double satisfying the full {@link LockfileReaderShape} with no
+   * filesystem, root walk, or package-manager detection.
+   *
+   * @remarks
+   * There is **no honest default lockfile**: an empty one that looks like a
+   * legitimate answer is indistinguishable from "this workspace resolves
+   * nothing" — the silent-empty failure class this package documents on the
+   * live paths — so `read` **dies** with an instructive defect until stubbed.
+   *
+   * The one derivation mirrors `WorkspaceDiscovery.makeTest`'s
+   * derived-from-the-primary rule: when a `read` override is supplied,
+   * `resolvedVersion` answers as the live service does — the **first** entry
+   * of `lockfile.packagesNamed(name)` in lockfile order, `Option.none()` on a
+   * miss — so the two stay consistent by construction. `integrity` is **not**
+   * derivable: the live method compares the lockfile against the workspace
+   * manifests discovery enumerates, and the double has no discovery to ask, so
+   * it dies unless stubbed.
+   *
+   * `refresh` defaults to `Effect.void` honestly: the live contract is "drop
+   * the memoized read so the next call re-reads", and this double memoizes
+   * nothing — every `read()` call re-invokes the override — so there is
+   * nothing to drop and the no-op is truthful, the same reasoning as
+   * `WorkspaceDiscovery.makeTest`'s `refresh`.
+   *
+   * @example
+   * ```ts
+   * import { Lockfile } from "@effected/lockfiles";
+   * import { LockfileReader } from "@effected/workspaces";
+   * import { Effect } from "effect";
+   *
+   * const double = LockfileReader.makeTest({
+   *   read: () =>
+   *     Effect.succeed(
+   *       Lockfile.make({ format: "pnpm", lockfileVersion: "9.0", packages: [], workspaceDependencies: [] }),
+   *     ),
+   * });
+   * // `resolvedVersion` now answers consistently from that lockfile.
+   * ```
+   */
+  static readonly makeTest: (overrides?: Partial<LockfileReaderShape>) => LockfileReaderShape;
+  /**
+   * The test layer: {@link LockfileReader.makeTest} behind `Layer.succeed`, so
+   * a suite provides only the methods it exercises.
+   *
+   * @remarks
+   * A parameterized layer factory mints a **fresh reference per call**, and
+   * layers memoize by reference — bind the result to a `const` and reuse it
+   * rather than calling `layerTest(...)` at each composition site.
+   *
+   * @example
+   * ```ts
+   * import { LockfileReader } from "@effected/workspaces";
+   *
+   * const TestLockfiles = LockfileReader.layerTest();
+   * // program.pipe(Effect.provide(TestLockfiles)) — dies loudly if touched.
+   * ```
+   */
+  static readonly layerTest: (overrides?: Partial<LockfileReaderShape>) => Layer.Layer<LockfileReader>;
 }
 //#endregion
 //#region src/Publishability.d.ts
@@ -1553,6 +1612,61 @@ declare class WorkspaceCatalogs extends WorkspaceCatalogs_base {
    * Parameterized, so bind it to a `const` and reuse it.
    */
   static readonly layerWithConfigDependencies: (options?: WorkspaceCatalogsOptions) => Layer.Layer<WorkspaceCatalogs, never, WorkspaceRoot | LockfileReader | FileSystem.FileSystem | Path.Path>;
+  /**
+   * A test double satisfying the full {@link WorkspaceCatalogsShape} with no
+   * filesystem, lockfile read, or hook replay.
+   *
+   * @remarks
+   * There is **no honest default catalog set**: an empty `CatalogSet` that
+   * looks like a legitimate answer is the "every dependency looks newly added"
+   * failure class the live assembler hard-fails to prevent, so every method
+   * **dies** with an instructive defect until stubbed — a test-wiring mistake
+   * fails loudly as a defect rather than succeeding with a lie or failing with
+   * a dishonest typed error.
+   *
+   * The one derivation mirrors `WorkspaceDiscovery.makeTest`'s
+   * derived-from-the-primary rule: when a `set` override is supplied,
+   * `resolveSpecifier` answers from that `CatalogSet`'s own
+   * {@link CatalogSet.resolveSpecifier} — exactly what the live service runs
+   * over its assembled set — so the two stay consistent by construction.
+   * `releaseAgeGate` and `importerVersions` are **not** derivable from a
+   * catalog set (the gate comes from release-age keys and hook contributions,
+   * the importer index from the lockfile's importer blocks — neither is in a
+   * `CatalogSet`) and always die unless stubbed.
+   *
+   * @example
+   * ```ts
+   * import { CatalogSet, WorkspaceCatalogs } from "@effected/workspaces";
+   * import { Effect } from "effect";
+   *
+   * const double = WorkspaceCatalogs.makeTest({
+   *   set: () => Effect.succeed(CatalogSet.fromCatalogs({ default: { effect: "4.0.0" } })),
+   * });
+   * // `resolveSpecifier` now answers consistently from that set.
+   * ```
+   */
+  static readonly makeTest: (overrides?: Partial<WorkspaceCatalogsShape>) => WorkspaceCatalogsShape;
+  /**
+   * The test layer: {@link WorkspaceCatalogs.makeTest} behind `Layer.succeed`,
+   * so a suite provides only the methods it exercises.
+   *
+   * @remarks
+   * A parameterized layer factory mints a **fresh reference per call**, and
+   * layers memoize by reference — bind the result to a `const` and reuse it
+   * rather than calling `layerTest(...)` at each composition site.
+   *
+   * @example
+   * ```ts
+   * import { CatalogSet, WorkspaceCatalogs } from "@effected/workspaces";
+   * import { Effect } from "effect";
+   *
+   * const TestCatalogs = WorkspaceCatalogs.layerTest({
+   *   set: () => Effect.succeed(CatalogSet.empty()),
+   * });
+   * // program.pipe(Effect.provide(TestCatalogs))
+   * ```
+   */
+  static readonly layerTest: (overrides?: Partial<WorkspaceCatalogsShape>) => Layer.Layer<WorkspaceCatalogs>;
   /**
    * The real implementation of `@effected/npm`'s `CatalogResolver` contract —
    * the one `@effected/package-json` declares but cannot fill.
@@ -1828,6 +1942,62 @@ declare class WorkspaceSnapshots extends WorkspaceSnapshots_base {
    * `const` and reuse it, or layer memoization does not apply.
    */
   static readonly layer: (options?: WorkspaceSnapshotsOptions) => Layer.Layer<WorkspaceSnapshots, never, Git | WorkspaceRoot | WorkspaceDiscovery | WorkspaceCatalogs>;
+  /**
+   * A test double satisfying the full {@link WorkspaceSnapshotsShape} with no
+   * git, filesystem, discovery, or catalog assembly.
+   *
+   * @remarks
+   * There are **no honest defaults and no derivations** here: `at(ref)` and
+   * `worktree()` are two independent reads of two different sources (a git ref
+   * vs. the live tree), so neither can be honestly derived from the other, and
+   * a fabricated empty {@link WorkspaceStateSnapshot} on either side of a
+   * before/after diff reads as every dependency newly added or removed — the
+   * exact silent-empty failure class this package documents on the live paths.
+   * Both methods therefore **die** with an instructive defect until stubbed; a
+   * test-wiring mistake fails loudly as a defect rather than succeeding with a
+   * lie.
+   *
+   * @example
+   * ```ts
+   * import { CatalogSet, WorkspaceSnapshots, WorkspaceStateSnapshot } from "@effected/workspaces";
+   * import { Effect } from "effect";
+   *
+   * const empty = WorkspaceStateSnapshot.make({
+   *   packages: [],
+   *   catalogs: CatalogSet.empty(),
+   *   importerVersions: {},
+   * });
+   * const double = WorkspaceSnapshots.makeTest({
+   *   at: () => Effect.succeed(empty),
+   *   worktree: () => Effect.succeed(empty),
+   * });
+   * ```
+   */
+  static readonly makeTest: (overrides?: Partial<WorkspaceSnapshotsShape>) => WorkspaceSnapshotsShape;
+  /**
+   * The test layer: {@link WorkspaceSnapshots.makeTest} behind `Layer.succeed`,
+   * so a suite provides only the methods it exercises.
+   *
+   * @remarks
+   * A parameterized layer factory mints a **fresh reference per call**, and
+   * layers memoize by reference — bind the result to a `const` and reuse it
+   * rather than calling `layerTest(...)` at each composition site.
+   *
+   * @example
+   * ```ts
+   * import { CatalogSet, WorkspaceSnapshots, WorkspaceStateSnapshot } from "@effected/workspaces";
+   * import { Effect } from "effect";
+   *
+   * const TestSnapshots = WorkspaceSnapshots.layerTest({
+   *   worktree: () =>
+   *     Effect.succeed(
+   *       WorkspaceStateSnapshot.make({ packages: [], catalogs: CatalogSet.empty(), importerVersions: {} }),
+   *     ),
+   * });
+   * // program.pipe(Effect.provide(TestSnapshots))
+   * ```
+   */
+  static readonly layerTest: (overrides?: Partial<WorkspaceSnapshotsShape>) => Layer.Layer<WorkspaceSnapshots>;
 }
 //#endregion
 //#region src/Workspaces.d.ts

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/workspaces",
-	"version": "0.7.0",
+	"version": "0.8.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": [
@@ -46,14 +46,14 @@
 		"./package.json": "./package.json"
 	},
 	"dependencies": {
-		"@effected/git": "~0.4.2",
+		"@effected/git": "~0.5.0",
 		"@effected/glob": "~0.2.1",
-		"@effected/lockfiles": "~0.1.10",
-		"@effected/npm": "~0.3.1",
-		"@effected/package-json": "~0.5.1",
+		"@effected/lockfiles": "~0.2.0",
+		"@effected/npm": "~0.4.0",
+		"@effected/package-json": "~0.5.2",
 		"@effected/semver": "~0.2.1",
 		"@effected/walker": "~0.3.2",
-		"@effected/yaml": "~0.5.1",
+		"@effected/yaml": "~0.6.0",
 		"@pnpm/catalogs.config": "^1100.0.0",
 		"@pnpm/catalogs.protocol-parser": "^1100.0.0",
 		"@pnpm/catalogs.resolver": "^1100.0.0",