@effected/workspaces 0.30.4 → 0.32.0

package/DependencyGraph.js

@@ -33,8 +33,9 @@ cycle: Schema.Array(Schema.String) }) {
 * `dependencies`, `devDependencies`, `peerDependencies` and
 * `optionalDependencies`; a self-edge is dropped.
 *
-* Total accessors never fail; the four fallible operations are `Effect.fn`
-* boundaries.
+* Total accessors never fail. The lookups fail with `PackageNotFoundError` for
+* an unknown name, and the ordering operations (`levels`, `sort`, `sortSubset`)
+* fail with {@link CyclicDependencyError} when the graph has a cycle.
 *
 * @example
 * ```ts
@@ -141,8 +142,11 @@ packages: Schema.Array(WorkspacePackage) }) {
 		})) : Effect.succeed([...dependents].sort());
 	});
 	/**
-	* `name` plus every package that transitively depends on it — the blast
-	* radius of a change. Sorted; includes `name` itself.
+	* Each of `names` plus every package that transitively depends on any of
+	* them — the blast radius of a change. Sorted and de-duplicated; the given
+	* names are included, whether or not the graph knows them.
+	*
+	* @param names - The changed package names.
 	*/
 	affectedBy = Effect.fn("DependencyGraph.affectedBy")((names) => {
 		const { reverse } = this.#index();
@@ -162,9 +166,8 @@ packages: Schema.Array(WorkspacePackage) }) {
 	* the workspace, level *n* depends only on levels below it.
 	*
 	* @remarks
-	* Kahn's algorithm over the reverse-edge index — linear, where v3's rescanned
-	* the whole adjacency map per processed node. Each level is sorted
-	* lexicographically, so the output is deterministic.
+	* Kahn's algorithm over the reverse-edge index, linear in the edge count.
+	* Each level is sorted lexicographically, so the output is deterministic.
 	*/
 	levels = Effect.fn("DependencyGraph.levels")(() => Effect.suspend(() => {
 		const edges = this.#index();
@@ -176,6 +179,13 @@ packages: Schema.Array(WorkspacePackage) }) {
 	/**
 	* A topological order over `names` plus their transitive workspace
 	* dependencies — the build order for a subset.
+	*
+	* @remarks
+	* Fails with `PackageNotFoundError` for a name the graph does not contain,
+	* and with {@link CyclicDependencyError} when the subset's closure has a
+	* cycle.
+	*
+	* @param names - The packages to build; each must be a workspace package.
 	*/
 	sortSubset = Effect.fn("DependencyGraph.sortSubset")((names) => Effect.suspend(() => {
 		const { forward } = this.#index();

package/DuplicateCheck.js

@@ -85,10 +85,12 @@ var DuplicatedPackage = class extends Schema.Class("DuplicatedPackage")({
 *
 * @example
 * ```ts
-* import { DuplicateCheck } from "@effected/workspaces";
 * import { Lockfile } from "@effected/lockfiles";
+* import { DuplicateCheck } from "@effected/workspaces";
 * import { Effect } from "effect";
 *
+* declare const text: string; // the text of a pnpm-lock.yaml
+*
 * const program = Effect.gen(function* () {
 *   const lockfile = yield* Lockfile.parse(text, { format: "pnpm" });
 *   const report = DuplicateCheck.run(lockfile, { names: DuplicateCheck.kit });
@@ -119,8 +121,8 @@ var DuplicateCheck = class DuplicateCheck extends Schema.Class("DuplicateCheck")
 	* In practice this is the **root importer under npm and bun**: neither
 	* records a resolved version per importer dependency, and neither emits a
 	* package row for the root, so there is nothing to join on. pnpm records a
-	* version per importer dependency and is unaffected. The same limitation
-	* `PeerCheck` reports, measured by the same code.
+	* version per importer dependency and is unaffected. `PeerCheck` reports the
+	* same limitation.
 	*
 	* Reported rather than silently skipped: a gate that sees no duplicates is
 	* entitled to know whether that means "clean" or "not looked at".
@@ -147,8 +149,7 @@ var DuplicateCheck = class DuplicateCheck extends Schema.Class("DuplicateCheck")
 	* Exactly those — not `@effect/*`, and not names merely starting with
 	* `effect`. A duplicated kit package presents as a `Layer` requirement that
 	* looks provided yet cannot be satisfied, at the entry point, naming neither
-	* the package nor the skew (issue #298); this predicate is the check that
-	* names both.
+	* the package nor the skew; this predicate is the check that names both.
 	*
 	* @param name - a package name
 	* @returns whether the name belongs to the kit
@@ -222,7 +223,7 @@ var DuplicateCheck = class DuplicateCheck extends Schema.Class("DuplicateCheck")
 		const dependents = /* @__PURE__ */ new Map();
 		const seen = /* @__PURE__ */ new Set();
 		const record = (targetId, dependent) => {
-			const key = `${targetId}${renderKey(dependent)}`;
+			const key = `${targetId}\0${renderKey(dependent)}`;
 			if (seen.has(key)) return;
 			seen.add(key);
 			const list = dependents.get(targetId) ?? [];
@@ -287,7 +288,7 @@ const dependentOf = (from) => from.isWorkspace && from.relativePath !== void 0 ?
 	version: from.version
 };
 /** @internal */
-const renderKey = (dependent) => dependent._tag === "importer" ? `importer${dependent.path}` : `package${dependent.name}${dependent.version}`;
+const renderKey = (dependent) => dependent._tag === "importer" ? `importer\0${dependent.path}` : `package\0${dependent.name}\0${dependent.version}`;
 
 //#endregion
 export { Dependent, DuplicateCheck, DuplicateInstance, DuplicatedPackage, DuplicatedVersion };

package/LayerPolicy.js

@@ -59,7 +59,7 @@ var LayerPolicyError = class extends Schema.TaggedError()("LayerPolicyError", {
 * message names every such key. A typo on an optional key would otherwise be
 * silently dropped: `requiredEdge` would remove the non-vacuity guard and
 * leave the report green. `$schema` is always accepted. A file that carries
-* keys of its own, such as systems' `harness`, passes them in `allowKeys`.
+* keys of its own, such as a `harness` block, passes them in `allowKeys`.
 *
 * @example
 * ```ts

package/LockfileReader.js

@@ -112,11 +112,14 @@ var LockfileReader = class LockfileReader extends Context.Service()("@effected/w
 		};
 	});
 	/**
-	* The live layer.
+	* The live layer: reads the lockfile of the detected package manager at the
+	* workspace root.
 	*
 	* @remarks
 	* Parameterized, so it mints a fresh reference per call — bind it to a
 	* `const` and reuse it.
+	*
+	* @param options - Root resolution (`cwd`, `stopAt`).
 	*/
 	static layer = (options) => Layer.effect(LockfileReader, LockfileReader.make(options));
 	/**

package/PackageManagerName.js

@@ -82,8 +82,8 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 * is not an exact version.
 *
 * Reuses the corepack `name@version+integrity` grammar rather than a second
-* parser, so a `devEngines` version carrying a hash (`11.11.0+sha512.…`, which
-* this repo's own root manifest does) normalizes to the same `11.11.0` the
+* parser, so a `devEngines` version carrying a hash (`11.11.0+sha512.…`)
+* normalizes to the same `11.11.0` the
 * top-level field reports — and a *range* (`^11`, `11.x`) yields none, because a
 * range is not a version and corepack will not run one either.
 */
@@ -326,8 +326,7 @@ var PackageManagerDetector = class PackageManagerDetector extends Context.Servic
 	* `WorkspaceDiscovery.info` posture, for the same reason. A stand-in that
 	* answered `"pnpm"` would hand a consumer a fact nothing established, and it
 	* would contradict the very service it stands in for: the live detector's
-	* defining property is that it [refuses to
-	* guess](https://github.com/spencerbeggs/effected) when no evidence matches.
+	* defining property is that it refuses to guess when no evidence matches.
 	* A double that guesses is worse than no double.
 	*
 	* Failing typed would be the subtler mistake: `PackageManagerDetectionError`

package/PackedInstall.js

@@ -1,7 +1,7 @@
 import { WorkspaceDiscovery } from "./WorkspaceDiscovery.js";
 import { PackageManagerName } from "./PackageManagerName.js";
 import { binConflict, binTargetOf, closureOf, consumerFiles, fileOverridesOf, installArgs, overridePath, readPackedManifest, scrubEnv, versionOf } from "./internal/packedInstallPlan.js";
-import { Duration, Effect, FileSystem, Option, Path, Redacted, Result, Schema } from "effect";
+import { Config, Duration, Effect, FileSystem, Option, Path, Redacted, Result, Schema, Stream } from "effect";
 import { Yaml } from "@effected/yaml";
 import { Run } from "@effected/commands";
 import { ChildProcess } from "effect/process";
@@ -182,7 +182,9 @@ var InstalledConsumer = class extends Schema.Class("InstalledConsumer")({
 	* Run the installed bin `name` to completion and collect what it wrote.
 	*
 	* @remarks
-	* Spawns {@link InstalledConsumer.command} with stdin ignored: the bin
+	* Spawns {@link InstalledConsumer.command} with `options.stdin` as its
+	* input (the null device when omitted, so a bin never waits on an open
+	* pipe): the bin
 	* from the consumer's directory, under the install's scrubbed environment
 	* with `options.env` layered over it after the scrub, and nothing
 	* inherited beyond that. A
@@ -194,10 +196,10 @@ var InstalledConsumer = class extends Schema.Class("InstalledConsumer")({
 	*
 	* @param name - The bin, as named in `node_modules/.bin`.
 	* @param args - Its arguments.
-	* @param options - Extra environment, working directory and ceiling.
+	* @param options - Extra environment, working directory, ceiling and stdin.
 	*/
 	runBin(name, args = [], options = {}) {
-		return collectBin(this.command(name, args, options), this.manager, name, options.timeout);
+		return collectBin(this.command(name, args, options), this.manager, name, options);
 	}
 	/**
 	* The command that runs the CARRIER's own bin `name`, whichever package
@@ -271,7 +273,8 @@ var InstalledConsumer = class extends Schema.Class("InstalledConsumer")({
 	* the `node_modules/.bin` slot.
 	*
 	* @remarks
-	* Spawns {@link InstalledConsumer.carrierCommand} with stdin ignored, and
+	* Spawns {@link InstalledConsumer.carrierCommand} with `options.stdin` as
+	* its input (the null device when omitted), and
 	* reports as {@link InstalledConsumer.runBin} does: a non-zero exit is a
 	* result, and a bin that cannot spawn or outlives `options.timeout` (one
 	* minute by default) fails `BinFailed`. Use it beside `runBin` under
@@ -282,11 +285,11 @@ var InstalledConsumer = class extends Schema.Class("InstalledConsumer")({
 	*
 	* @param name - The bin, as the carrier's `bin` map names it.
 	* @param args - Its arguments.
-	* @param options - Extra environment, working directory and ceiling.
+	* @param options - Extra environment, working directory, ceiling and stdin.
 	*/
 	runCarrierBin(name, args = [], options = {}) {
 		const manager = this.manager;
-		return this.carrierCommand(name, args, options).pipe(Effect.flatMap((command) => collectBin(command, manager, name, options.timeout)));
+		return this.carrierCommand(name, args, options).pipe(Effect.flatMap((command) => collectBin(command, manager, name, options)));
 	}
 };
 /** The install's scrubbed environment with the caller's entries layered on after the scrub: a deliberate CI=true must survive it. */
@@ -296,14 +299,24 @@ const layeredEnv = (consumer, options) => {
 	else env[key] = value;
 	return env;
 };
-/** Run a bin's command to completion, stdin ignored, mapping a failed spawn or an expired ceiling to `BinFailed`. */
-const collectBin = (command, manager, name, timeout = DEFAULT_BIN_TIMEOUT) => Run.collect(ChildProcess.make(command.command, command.args, {
-	...command.options,
-	stdin: "ignore"
-}), { timeout }).pipe(Effect.mapError((cause) => failure("BinFailed", cause._tag === "CommandFailedError" && cause.kind === "timeout" ? `${manager}: ${name} timed out after ${describeDuration(timeout)}` : `${manager}: ${name} could not run`, {
-	manager,
-	cause
-})));
+/** A bin's stdin as `ChildProcess` takes it: absent or `""` is the null device (immediate end of input), anything else is written and closed. */
+const stdinOf = (stdin) => {
+	if (stdin === void 0 || stdin === "") return "ignore";
+	if (typeof stdin === "string") return Stream.make(new TextEncoder().encode(stdin));
+	if (stdin instanceof Uint8Array) return Stream.make(stdin);
+	return stdin;
+};
+/** Run a bin's command to completion with `options.stdin` as its input (the null device when omitted), mapping a failed spawn or an expired ceiling to `BinFailed`. */
+const collectBin = (command, manager, name, options) => {
+	const timeout = options.timeout ?? DEFAULT_BIN_TIMEOUT;
+	return Run.collect(ChildProcess.make(command.command, command.args, {
+		...command.options,
+		stdin: stdinOf(options.stdin)
+	}), { timeout }).pipe(Effect.mapError((cause) => failure("BinFailed", cause._tag === "CommandFailedError" && cause.kind === "timeout" ? `${manager}: ${name} timed out after ${describeDuration(timeout)}` : `${manager}: ${name} could not run`, {
+		manager,
+		cause
+	})));
+};
 /**
 * What a packed install produced.
 *
@@ -594,6 +607,113 @@ var PackedInstall = class PackedInstall {
 		...options.packTimeout === void 0 ? {} : { packTimeout: options.packTimeout },
 		...extra.perConsumer === void 0 ? {} : { perConsumer: extra.perConsumer }
 	})));
+	/**
+	* Whether the pack source {@link PackedInstall.run} would read is on disk,
+	* before any package manager is spawned.
+	*
+	* @remarks
+	* Plans the closure as the run does (`PackedInstall.closure`'s planner) and
+	* checks the `package.json` of each closure package under `packFrom`
+	* (default `{ directory: "dist/prod/npm/pkg" }`), the same file whose
+	* absence makes the run fail `PackSourceMissing`. Under `packFrom: "source"`
+	* the packer builds nothing of its own, so nothing is checked and the
+	* result is ready. A package a bundler's dev build produced is no
+	* substitute: the prod output exists only after the prod build, which a
+	* test job's usual `build:dev` pre-step does not run. Pair it with
+	* {@link PackedInstall.gate} to skip locally and fail under CI.
+	*
+	* Fails as `closure` does, plus `Io` when a path cannot be inspected.
+	*
+	* @example
+	* ```ts
+	* import { NodeServices } from "@effect/platform-node";
+	* import { Workspaces } from "@effected/workspaces";
+	* import { PackedInstall } from "@effected/workspaces/testing";
+	* import { Effect, Layer } from "effect";
+	*
+	* const Live = Workspaces.layer({ cwd: "/repo" }).pipe(Layer.provideMerge(NodeServices.layer));
+	* const preflight = await Effect.runPromise(
+	*   PackedInstall.preflight({ carrier: "my-tool", closure: "auto" }).pipe(Effect.provide(Live)),
+	* );
+	* console.log(preflight.ready, preflight.missing);
+	* ```
+	*
+	* @param options - The run's carrier, closure, overrides and pack source.
+	*/
+	static preflight = Effect.fn("PackedInstall.preflight")(function* (options) {
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		const plan = yield* planClosure(options.carrier, options);
+		const source = options.packFrom ?? DEFAULT_PACK_FROM;
+		if (source === "source") return {
+			ready: true,
+			missing: []
+		};
+		const missing = [];
+		for (const pkg of plan.closure) {
+			const manifest = path.join(pkg.path, source.directory, "package.json");
+			if (!(yield* fs.exists(manifest).pipe(Effect.mapError((cause) => failure("Io", `could not inspect ${manifest}`, { cause }))))) missing.push(manifest);
+		}
+		return {
+			ready: missing.length === 0,
+			missing
+		};
+	});
+	/**
+	* Turns a {@link PackedInstallPreflight} into the suite's decision: run,
+	* skip locally, or fail under CI.
+	*
+	* @remarks
+	* `CI` is read through `Config`, so the ambient `ConfigProvider` decides —
+	* the process environment at a test file's top level, and whatever a test
+	* provides in a test; nothing here reads `process`. `CI` counts as set when
+	* it is present and not `""`, `"0"` or `"false"` (case-insensitive), and an
+	* unreadable `CI` counts as unset. Ready is always `"run"`;
+	* missing is `"skip"` off CI and `"fail"` on it, so a CI job that never ran
+	* the prod build cannot pass by silently skipping the proof. The message
+	* names every missing path. The test job must run the prod build
+	* (`build:prod` for a `@savvy-web/bundler` package) before the packed-install
+	* tests: a dev build leaves `dist/prod` absent.
+	*
+	* @example
+	* ```ts
+	* import { assert, describe, it } from "@effect/vitest";
+	* import { PackedInstall } from "@effected/workspaces/testing";
+	* import { Effect } from "effect";
+	*
+	* declare const preflight: { readonly ready: boolean; readonly missing: ReadonlyArray<string> };
+	* const gate = Effect.runSync(PackedInstall.gate(preflight));
+	*
+	* describe.runIf(gate.action === "run")("packed install", () => {
+	*   it("installs", () => {});
+	* });
+	* describe.runIf(gate.action === "fail")("packed install prod build", () => {
+	*   it("exists", () => assert.fail(gate.message));
+	* });
+	* ```
+	*
+	* @param preflight - What {@link PackedInstall.preflight} answered.
+	*/
+	static gate = (preflight) => Effect.gen(function* () {
+		if (preflight.ready) return {
+			action: "run",
+			message: ""
+		};
+		const ci = yield* Config.option(Config.String("CI")).pipe(Effect.orElseSucceed(() => Option.none()));
+		const underCi = Option.isSome(ci) && ![
+			"",
+			"0",
+			"false"
+		].includes(ci.value.toLowerCase());
+		const message = `the pack source is missing: ${preflight.missing.join(", ")}; run the prod build (build:prod) before the packed-install tests`;
+		return underCi ? {
+			action: "fail",
+			message: `${message}; it must not be skipped under CI`
+		} : {
+			action: "skip",
+			message
+		};
+	});
 	/** Pack, then install under every available manager. */
 	static run = Effect.fn("PackedInstall.run")(function* (options) {
 		const fs = yield* FileSystem.FileSystem;

package/PeerCheck.js

@@ -402,10 +402,12 @@ const judgeJoined = (context, catalogs, peer, declared, optional) => {
 *
 * @example
 * ```ts
-* import { PeerCheck } from "@effected/workspaces";
 * import { Lockfile } from "@effected/lockfiles";
+* import { PeerCheck } from "@effected/workspaces";
 * import { Effect } from "effect";
 *
+* declare const text: string; // the text of a pnpm-lock.yaml
+*
 * const program = Effect.gen(function* () {
 *   const lockfile = yield* Lockfile.parse(text, { format: "pnpm" });
 *   const report = PeerCheck.run(lockfile);
@@ -508,7 +510,7 @@ var PeerCheck = class PeerCheck extends Schema.Class("PeerCheck")({
 	* `pnpm peers check` DOES report the linked parent's peers (it reads the
 	* manifest on disk): every `link:` edge whose target the caller did not
 	* supply therefore fails the report closed rather than letting the
-	* invisible parent pass as checked (effected#800).
+	* invisible parent pass as checked.
 	*
 	* Supplying {@link PeerCheckOptions.workspacePackages} closes that gap for
 	* every `link:` target the set covers — the root importer's included,
@@ -543,6 +545,8 @@ var PeerCheck = class PeerCheck extends Schema.Class("PeerCheck")({
 	* version check, and a plain unparseable version is still skipped.
 	*
 	* @param lockfile - a lockfile parsed by `@effected/lockfiles`
+	* @param options - the workspace's effective rules, manifests and catalogs; see
+	*   {@link PeerCheckOptions}
 	* @returns the report; never fails
 	*/
 	static run(lockfile, options) {

package/Publishability.js

@@ -87,16 +87,13 @@ var PublishTarget = class extends Schema.Class("PublishTarget")({
 var PublishabilityDetector = class extends Context.Service()("@effected/workspaces/PublishabilityDetector") {
 	/**
 	* Standard npm publishing semantics, **as a value**. Pure — no filesystem,
-	* no platform services.
+	* no platform services. Never publishes with provenance (`provenance: false`).
 	*
 	* @remarks
 	* Exposed as a shape and not only as a layer, because a consumer composing
-	* *around* these rules cannot reach them through a layer without re-entering
-	* the very tag it is replacing. `@savvy-web/silk-effects` had to write
-	* `Effect.provide(PublishabilityDetector, PublishabilityDetector.layer)`
-	* **inside its own implementation of that tag** to get at this function for
-	* its pass-through branch; with the value exposed that becomes
-	* `PublishabilityDetector.npm.detect(pkg)`.
+	* *around* these rules cannot reach them through a layer without
+	* re-entering the very tag it is replacing. A custom detector's pass-through
+	* branch calls `PublishabilityDetector.npm.detect(pkg)` directly.
 	*
 	* @example
 	* ```ts
@@ -131,13 +128,12 @@ var PublishabilityDetector = class extends Context.Service()("@effected/workspac
 	*
 	* @remarks
 	* Named for its policy rather than called `layer`, deliberately. **No
-	* composite in this package provides a publishability detector**: a
-	* `Workspaces.layer()` that quietly supplied npm semantics made the choice
-	* invisible, and worse, made a naively-ordered override lose to it in
-	* silence — `Layer.mergeAll(myDetector, Workspaces.layer())` resolved to the
-	* default, because `mergeAll` is last-wins. For a service that decides
-	* whether a package publishes and to which registry, that silent revert was
-	* the worst available failure.
+	* composite in this package provides a publishability detector**: one that
+	* quietly supplied npm semantics would hide the choice and, because
+	* `Layer.mergeAll` is last-wins, would let a naively-ordered override such
+	* as `Layer.mergeAll(myDetector, Workspaces.layer())` lose to the default in
+	* silence. For a service that decides whether a package publishes and to
+	* which registry, that silent revert is the worst available failure.
 	*
 	* The composites do not *require* a detector either — nothing inside them
 	* asks a publishability question, so their `R` stays `FileSystem | Path`.

package/README.md

@@ -7,10 +7,10 @@
 
 Monorepo workspace tooling for [Effect](https://effect.website) v4: find the workspace root, enumerate its packages, walk the dependency graph, detect the package manager, resolve pnpm catalogs, read the lockfile, check it for unsatisfied peer dependencies and work out which packages a git range touches. Every capability is a service you provide at the edge and swap in tests. Works with npm, pnpm, yarn Berry and bun.
 
-> **Pre-release.** This package is part of the `@effected/*` kit, in pre-`1.0.0`
-> development against a single pinned Effect v4 prerelease. Packages graduate to
-> `1.0.0` once Effect `4.0.0` ships. To hold your own `effect` versions at
-> exactly the ones the kit is built and tested against, install
+> **Pre-`1.0.0`.** This package is part of the `@effected/*` kit, built on stable
+> Effect v4 (`effect` `^4.0.0`) and still in `0.x` development. Stable Effect
+> makes a kit `1.0.0` possible, not automatic. To keep your `effect` and
+> `@effect/*` versions on the line the kit is built and tested against, install
 > [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
 >
 > **Stability: unstable.** This package's API surface is not yet considered

package/ReleaseTag.js

@@ -194,11 +194,11 @@ const classifyTag = (tag) => {
 * even when `value` carries a prefix, so a consumer comparing versions never
 * has to strip one back off.
 *
-* Formatting is **total**: there is no error channel, because the only failure
-* v3 modelled — an empty version — is caught by `Schema.NonEmptyString` when
-* the value is constructed. A bad version reaching these statics is developer
-* wiring rather than untrusted input, so it dies as a defect, the same posture
-* as an uncompilable glob literal in `WorkspacePackage.matchesDependency`.
+* Formatting has **no error channel**: an empty version is rejected by
+* `Schema.NonEmptyString` when the value is constructed. A bad version
+* reaching these statics is developer wiring rather than untrusted input, so it
+* dies as a defect, the same posture as an uncompilable glob literal in
+* `WorkspacePackage.matchesDependency`.
 *
 * @example
 * ```ts
@@ -227,6 +227,7 @@ var ReleaseTag = class ReleaseTag extends Schema.Class("ReleaseTag")({
 	*
 	* @param version - The version being released. Must not be empty.
 	* @param options - Formatting overrides.
+	* @returns the single-style {@link ReleaseTag}.
 	*/
 	static single(version, options) {
 		const prefix = options?.versionPrefix ?? "";

package/SourceBoundary.js

@@ -616,7 +616,7 @@ var SourceBoundary = class SourceBoundary {
 	});
 	/** The shipped positive- and negative-control snippets, at least one of each per rule kind. */
 	static fixtures = FIXTURES;
-	/** The names of shipped fixtures the scanner now gets wrong; `[]` means it still flags and spares what it must. */
+	/** The names of shipped fixtures the scanner gets wrong; `[]` means it still flags and spares what it must. */
 	static verifyFixtures = () => FIXTURES.filter((fixture) => SourceBoundary.check("fixture.ts", fixture.source, [fixture.rule]).length > 0 !== fixture.flagged).map((fixture) => `${fixture.flagged ? "missed" : "false positive"}: ${fixture.name}`);
 };
 

package/VersioningStrategy.js

@@ -30,13 +30,13 @@ const VersioningStrategyType = Schema.Literals([
 *
 * @example
 * ```ts
-* import { VersioningStrategy } from "@effected/workspaces";
+* import { PublishabilityDetector, VersioningStrategy } from "@effected/workspaces";
 * import { Effect } from "effect";
 *
 * const program = Effect.gen(function* () {
-*   const strategy = yield* VersioningStrategy.detect({ fixedGroups });
-*   return strategy.tagsFor(released).map((tag) => tag.value);
-* });
+*   const strategy = yield* VersioningStrategy.detect({ fixedGroups: [["@acme/a", "@acme/b"]] });
+*   return strategy.tagsFor([{ name: "@acme/a", version: "1.2.3" }]).map((tag) => tag.value);
+* }).pipe(Effect.provide(PublishabilityDetector.layerNpm));
 * ```
 *
 * @public
@@ -66,6 +66,9 @@ var VersioningStrategy = class VersioningStrategy extends Schema.Class("Versioni
 	* Pure and total — no IO, no error channel. `packages` is sorted and
 	* de-duplicated first, so a name listed twice cannot inflate a one-package
 	* repo into an independent one.
+	*
+	* @param options - The publishable package names and any fixed groups.
+	* @returns the classified {@link VersioningStrategy}.
 	*/
 	static classify(options) {
 		const fixedGroups = options.fixedGroups ?? [];
@@ -85,6 +88,10 @@ var VersioningStrategy = class VersioningStrategy extends Schema.Class("Versioni
 	* The publishability question is asked through the service precisely so a
 	* consumer with its own rules — honouring a release tool's ignore list, say —
 	* swaps the layer instead of filtering afterwards.
+	*
+	* Requires `WorkspaceDiscovery` and `PublishabilityDetector` (for example
+	* `PublishabilityDetector.layerNpm`) in `R`, and fails with
+	* `WorkspaceDiscoveryFailure` when discovery does.
 	*/
 	static detect = Effect.fn("VersioningStrategy.detect")(function* (options) {
 		const discovery = yield* WorkspaceDiscovery;
@@ -114,6 +121,9 @@ var VersioningStrategy = class VersioningStrategy extends Schema.Class("Versioni
 	* one-line check rather than a field here.
 	*
 	* An empty batch produces no tags under either style.
+	*
+	* @param releases - The packages released and their versions.
+	* @param options - Tag formatting overrides, such as `versionPrefix`.
 	*/
 	tagsFor(releases, options) {
 		if (releases.length === 0) return [];

package/WorkspaceCatalogs.js

@@ -578,10 +578,9 @@ var WorkspaceCatalogs = class WorkspaceCatalogs extends Context.Service()("@effe
 	* `rangeOf` returns `Option.none()` for a dependency no catalog declares, per
 	* the contract's convention. A failed catalog *assembly* — an unreadable or
 	* malformed `pnpm-workspace.yaml`, a broken config-dependency hook — passes
-	* through **typed** as the contract's `CatalogAssemblyError` (it used to be
-	* folded into `DependencyResolutionError`'s defect `cause`, which forced
-	* consumers to `_tag`-sniff `unknown`); only the remaining mechanism failure,
-	* an unfindable workspace root, is wrapped as `DependencyResolutionError`.
+	* through **typed** as the contract's `CatalogAssemblyError`; only the
+	* remaining mechanism failure, an unfindable workspace root, is wrapped as
+	* `DependencyResolutionError`.
 	*/
 	static catalogResolver = Layer.effect(CatalogResolver, Effect.gen(function* () {
 		const catalogs = yield* WorkspaceCatalogs;

package/WorkspaceDiscovery.js

@@ -19,7 +19,7 @@ import { DependencyResolutionError, WorkspaceResolver } from "@effected/npm";
 * 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
+* 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`.
@@ -118,11 +118,9 @@ const patternKindOf = (kind) => kind;
 * the lifetime of the layer. A Vitest reporter that builds the layer per call
 * site and never queries it pays nothing.
 *
-* The memo is **success-only**. `Effect.cached` memoizes the first `Exit`,
-* *including an interrupt* — an init interrupted by an unrelated timeout would
-* otherwise brick the layer permanently with a cause outside its declared error
-* channel. A failure or interrupt is therefore retried on the next call, which
-* is a deliberate behaviour change from the v3 library.
+* The memo is **success-only**: a failure or interrupt is not cached, so an
+* init interrupted by an unrelated timeout cannot brick the layer, and the next
+* call retries.
 *
 * @example
 * ```ts
@@ -380,12 +378,14 @@ var WorkspaceDiscovery = class WorkspaceDiscovery extends Context.Service()("@ef
 		};
 	});
 	/**
-	* The live layer.
+	* The live layer, discovering the workspace from `options.cwd`.
 	*
 	* @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 `layer(...)` at each composition site.
+	*
+	* @param options - Root resolution and enumeration bounds.
 	*/
 	static layer = (options) => Layer.effect(WorkspaceDiscovery, WorkspaceDiscovery.make(options));
 	/**