@effected/workspaces 0.30.4 → 0.32.0

package/WorkspacePackage.js

@@ -119,13 +119,9 @@ var WorkspacePackage = class WorkspacePackage extends Schema.Class("WorkspacePac
 	* Absolute path to the workspace root this package was discovered under.
 	*
 	* @remarks
-	* Carried, not derived. Whoever built this value already knew the root —
-	* `WorkspaceDiscovery` resolved it before enumerating, and the sync entry
-	* point is handed it — so dropping it forced every consumer into per-package
-	* root arithmetic (counting `relativePath` segments and re-ascending that
-	* many `..`). That reconstruction is exact only while `path` and
-	* `relativePath` agree, and it re-derives something the kit never had to
-	* lose.
+	* Carried, not derived: `WorkspaceDiscovery` resolves the root before
+	* enumerating, so every package arrives with it and consumers need no
+	* per-package root arithmetic over `relativePath`.
 	*
 	* For the root package this equals `path`, and `relativePath` is `"."`.
 	*/
@@ -152,8 +148,7 @@ var WorkspacePackage = class WorkspacePackage extends Schema.Class("WorkspacePac
 	* validated beyond being a record. For the strict typed model use
 	* `manifest()`, which deliberately **re-reads** the file — a point-in-time
 	* refresh this captured record cannot provide. Defaults to `{}` for
-	* construction sites and previously-serialized values that predate the
-	* field.
+	* values constructed or decoded without the field.
 	*/
 	manifestRecord: Schema.Record(Schema.String, Schema.Unknown).pipe(Schema.withDecodingDefaultKey(Effect.succeed(EMPTY_MANIFEST)), Schema.withConstructorDefault(Effect.succeed(EMPTY_MANIFEST)))
 }) {
@@ -218,8 +213,8 @@ var WorkspacePackage = class WorkspacePackage extends Schema.Class("WorkspacePac
 		return version === void 0 ? Option.none() : Option.some(version);
 	}
 	/**
-	* Whether any dependency name matches `pattern` — the `minimatch` runtime
-	* dependency's one call site, now over `@effected/glob`'s vendored engine.
+	* Whether any dependency name (across all four kinds) matches the glob
+	* `pattern`, using `@effected/glob`.
 	*
 	* @remarks
 	* A `GlobPattern` is total and free to test. A `string` is compiled on every
@@ -235,7 +230,12 @@ var WorkspacePackage = class WorkspacePackage extends Schema.Class("WorkspacePac
 		const compiled = typeof pattern === "string" ? GlobPattern.make({ source: pattern }) : pattern;
 		return Object.keys(this.allDependencies).some((dependency) => compiled.matches(dependency));
 	}
-	/** Compare this package's dependencies against `other`'s. */
+	/**
+	* Compare this package's dependencies against `other`'s, treating `other` as
+	* the baseline: what this package added, removed or re-specified.
+	*
+	* @param other - The package to compare against.
+	*/
 	dependencyDiff(other) {
 		const mine = this.allDependencies;
 		const theirs = other.allDependencies;
@@ -271,6 +271,10 @@ var WorkspacePackage = class WorkspacePackage extends Schema.Class("WorkspacePac
 	* Read and decode this package's `package.json` into the strict
 	* `@effected/package-json` `Package` model — the bridge from the
 	* tolerant discovery projection to the fully typed manifest.
+	*
+	* @remarks
+	* Fails with {@link WorkspaceManifestError} (`kind: "read"` or `"decode"`) and
+	* requires core `FileSystem`.
 	*/
 	static manifest = Effect.fn("WorkspacePackage.manifest")(function* (self) {
 		const content = yield* (yield* FileSystem.FileSystem).readFileString(self.packageJsonPath).pipe(Effect.mapError((cause) => new WorkspaceManifestError({

package/WorkspaceRoot.js

@@ -127,12 +127,10 @@ var WorkspaceRoot = class WorkspaceRoot extends Context.Service()("@effected/wor
 	* A test double resolving every `find` to `root`, with no filesystem.
 	*
 	* @remarks
-	* The nine-copies-of-a-four-line-mock case — a `Layer.succeed` over a `find`
-	* that ignores its arguments and succeeds with a fixed root is what consumers
-	* were writing by hand. The difference is that this double **honours
-	* `stopAt`**: a hand-rolled `find` that ignores the ceiling makes a bounded
-	* call pass under test and fail against the live service, which is the
-	* failure mode the option exists to catch. A `root` above the ceiling fails
+	* Stands in for a hand-written `Layer.succeed` over a `find` that ignores its
+	* arguments. Unlike that, this double **honours `stopAt`**: a `find` that
+	* ignores the ceiling makes a bounded call pass under test and fail against
+	* the live service, which is the failure mode the option exists to catch. A `root` above the ceiling fails
 	* here exactly as it would live, with the same
 	* {@link WorkspaceRootNotFoundError}.
 	*

package/WorkspaceSnapshots.js

@@ -250,11 +250,14 @@ var WorkspaceSnapshots = class WorkspaceSnapshots extends Context.Service()("@ef
 		};
 	});
 	/**
-	* The live layer.
+	* The live layer, reading workspace state at a git ref or from the live
+	* worktree.
 	*
 	* @remarks
 	* Parameterized, so it mints a fresh reference per call — bind it to a
 	* `const` and reuse it, or layer memoization does not apply.
+	*
+	* @param options - Root resolution and the optional `seedCatalogs`.
 	*/
 	static layer = (options) => Layer.effect(WorkspaceSnapshots, WorkspaceSnapshots.make(options));
 	/**

package/WorkspaceStateSnapshot.js

@@ -12,10 +12,9 @@ const DependencyMap = Schema.Record(Schema.String, Schema.String).pipe(Schema.wi
 *
 * @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.
+* encoded side stays a plain optional string so that a stored value carrying
+* `""` still decodes, to the absent key it meant — a 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 !== ""),
@@ -47,8 +46,7 @@ var PackageStateSnapshot = class extends Schema.Class("PackageStateSnapshot")({
 	* 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.
+	* rejects it, and a stored `""` 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
@@ -125,11 +123,9 @@ var WorkspaceStateSnapshot = class WorkspaceStateSnapshot extends Schema.Class("
 	* lockfile recorded it at this moment.
 	*
 	* @remarks
-	* Defaults to `{}`, so a `WorkspaceStateSnapshot` serialized before this field
-	* existed still decodes — and an empty index simply makes the `catalog:`
-	* fallback in {@link WorkspaceStateSnapshot.resolve} inert, which is exactly
-	* the behavior those older values were captured under. Only pnpm records
-	* importer versions; bun and npm yield an empty index.
+	* Defaults to `{}` when absent from a stored value; an empty index makes the
+	* `catalog:` fallback in {@link WorkspaceStateSnapshot.resolve} inert. Only
+	* pnpm records importer versions; bun and npm yield an empty index.
 	*/
 	importerVersions: Schema.optionalKey(Schema.Record(Schema.String, Schema.Record(Schema.String, Schema.String))),
 	/**
@@ -143,9 +139,8 @@ var WorkspaceStateSnapshot = class WorkspaceStateSnapshot extends Schema.Class("
 	* diagnostic and off this serializable value. Every fresh read sets the
 	* field: `{}` under the no-op layer, which resolves nothing, when the file
 	* declares no config dependencies, or on the bun / `package.json` path,
-	* where config dependencies do not exist. Absent only when decoding a
-	* snapshot serialized before the field existed, so stored values stay
-	* readable. Carried through `withSeededCatalogs` and `crossSeed`
+	* where config dependencies do not exist. Absent only when decoding a stored
+	* value that omits it. Carried through `withSeededCatalogs` and `crossSeed`
 	* unchanged, like `importerVersions`.
 	*/
 	hookReplays: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)),
@@ -171,8 +166,7 @@ var WorkspaceStateSnapshot = class WorkspaceStateSnapshot extends Schema.Class("
 	* replays the ref's own pinned hook and the seed answers only what neither
 	* source declared.
 	*
-	* Defaults to absent, which makes the seed inert — exactly the behavior of
-	* every snapshot captured before this field existed.
+	* Defaults to absent, which makes the seed inert.
 	*/
 	seededCatalogs: Schema.optionalKey(CatalogSet)
 }) {

package/Workspaces.js

@@ -83,10 +83,9 @@ var Workspaces = class {
 	* `@effected/memfs` volume).
 	*
 	* **`PublishabilityDetector` is neither provided nor required here.** The
-	* composite used to bake in npm semantics, which a naively-ordered override
-	* silently lost to; now it supplies no default, and — because nothing inside
-	* the composite asks a publishability question — it does not require one in
-	* `R` either. The requirement surfaces in the `R` of each operation that
+	* composite supplies no default policy, and — because nothing inside it asks
+	* a publishability question — it does not require one in `R` either. The
+	* requirement surfaces in the `R` of each operation that
 	* asks (`VersioningStrategy.detect`, e.g.), so a program that asks and never
 	* wires a detector fails to compile at that operation, and a program that
 	* never asks never supplies a publish policy. Wire one explicitly where
@@ -167,10 +166,9 @@ var Workspaces = class {
 	* `pnpmfile.cjs` hooks**.
 	*
 	* @remarks
-	* The composite that did not exist. `layerWithGit` hard-wires the no-op
-	* catalogs layer, so a consumer wanting snapshots + git + hook replay had to
-	* rebuild the entire service graph by hand — which is exactly what
-	* `@savvy-web/silk-effects` did, and the copy this static deletes.
+	* `layerWithGit` wires the no-op catalogs layer, so this is the composite to
+	* reach for when you want snapshots, git and hook replay together without
+	* assembling the service graph by hand.
 	*
 	* Requirements are unchanged from {@link Workspaces.layerWithGit}: a
 	* filesystem, a path service, and core's `ChildProcessSpawner` (behind
@@ -233,8 +231,7 @@ var Workspaces = class {
 	* and {@link ConfigDependencyHooks.layerSubprocess}. It exists for the fourth
 	* policy: {@link ConfigDependencyHooks.layerFrom}, the hermetic seam, which a
 	* snapshot-backed test otherwise cannot reach without rebuilding the whole
-	* git graph by hand — the copy `layerWithGitAndConfigDependencies` was added
-	* to delete. The ONE hooks reference is handed to both `WorkspaceCatalogs`
+	* git graph by hand. The ONE hooks reference is handed to both `WorkspaceCatalogs`
 	* and `WorkspaceSnapshots`, so `at(ref)` and `worktree()` cannot drift on
 	* which policy they replay. A hooks layer carrying its own requirement (the
 	* subprocess variant's `ChildProcessSpawner`) threads it through to the
@@ -264,13 +261,11 @@ var Workspaces = class {
 	* contract: how to run a project-local binary here.
 	*
 	* @remarks
-	* **An inverted contract, the `@effected/npm` `CatalogResolver`
-	* precedent.** Tool discovery needs package-manager detection and
-	* workspace-root resolution, both of which live here — but a direct edge
-	* from `@effected/commands` to this package would make that boundary-tier
-	* package integrated, and through the planned `npm` → `commands` edge
-	* would drag `npm`, `lockfiles` (pure!) and `package-json` up a tier with
-	* it. So `commands` declares the narrow contract and we ship the layer.
+	* **An inverted contract, like `@effected/npm`'s `CatalogResolver`.** Tool
+	* discovery needs package-manager detection and workspace-root resolution,
+	* both of which live here, but `@effected/commands` must not depend on this
+	* package. So `commands` declares the narrow `LocalExec` contract and this
+	* package ships the layer.
 	*
 	* **The argv knowledge is not duplicated.** `LocalExec.prefixes(name)` is
 	* the one home of the four managers' `exec`/`dlx`/script-runner prefixes;
@@ -304,6 +299,7 @@ var Workspaces = class {
 	*
 	* @example
 	* ```ts
+	* import { NodeServices } from "@effect/platform-node";
 	* import { ToolDiscovery } from "@effected/commands";
 	* import { Workspaces } from "@effected/workspaces";
 	* import { Layer } from "effect";

package/WorkspacesSync.js

@@ -113,9 +113,7 @@ const isPackage = (options, dir) => options.fileSystem.exists(options.path.join(
 * The signature is path-first, options second — the same shape as
 * {@link getWorkspacePackagesSync} and the rest of the kit's sync facades
 * (`TsconfigLoaderSync.load(configPath, options)`). `cwd` is required and
-* positional: the earlier options-bag form defaulted it to an ambient
-* `process.cwd()` read, which both broke the symmetry with its sibling and
-* was the module's one platform assumption.
+* positional, so the function reads no ambient `process.cwd()`.
 *
 * Markers match the async service exactly: a `pnpm-workspace.yaml`, or a
 * `package.json` carrying a `workspaces` field.