@effected/workspaces 0.30.3 → 0.31.0

package/internal/importerVersions.js

@@ -3,7 +3,7 @@
 * Strip pnpm's peer-disambiguation suffix from a recorded importer version.
 *
 * pnpm records an importer version as the resolved version followed by the peer
-* context it was resolved under — `4.0.0-beta.101(effect@4.0.0-beta.101)(ioredis@5.11.1(supports-color@8.1.1))`.
+* context it was resolved under — `4.0.0(effect@4.0.0)(ioredis@5.11.1(supports-color@8.1.1))`.
 * `@effected/lockfiles` stores that string verbatim (its `packages:` key parser
 * strips the suffix; the importer entries deliberately keep it), so the raw
 * value must never reach a consumer's dependency table — it would render the

package/node-sync.d.ts

@@ -92,7 +92,9 @@ interface SyncDirectoryEntry {
  * satisfies it verbatim:
  *
  * ```ts
+ * import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
  * import * as path from "node:path";
+ * import type { WorkspacesSyncOptions } from "@effected/workspaces";
  *
  * const options: WorkspacesSyncOptions = {
  * 	fileSystem: { exists: existsSync, readFile: (p) => readFileSync(p, "utf8"), readDirectory: (p) => readdirSync(p), isDirectory: (p) => statSync(p).isDirectory() },

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/workspaces",
-	"version": "0.30.3",
+	"version": "0.31.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": [
@@ -51,23 +51,23 @@
 		"./package.json": "./package.json"
 	},
 	"dependencies": {
-		"@effected/commands": "^0.10.0",
-		"@effected/git": "^0.19.0",
-		"@effected/glob": "^0.9.0",
-		"@effected/jsonc": "^0.14.0",
-		"@effected/lockfiles": "^0.14.0",
-		"@effected/npm": "^0.19.0",
-		"@effected/package-json": "^0.19.1",
-		"@effected/semver": "^0.10.1",
-		"@effected/walker": "^0.14.0",
-		"@effected/yaml": "^0.18.0",
+		"@effected/commands": "^0.11.0",
+		"@effected/git": "^0.20.0",
+		"@effected/glob": "^0.10.0",
+		"@effected/jsonc": "^0.15.0",
+		"@effected/lockfiles": "^0.15.0",
+		"@effected/npm": "^0.20.0",
+		"@effected/package-json": "^0.20.0",
+		"@effected/semver": "^0.11.0",
+		"@effected/walker": "^0.15.0",
+		"@effected/yaml": "^0.19.0",
 		"@pnpm/catalogs.config": "^1100.0.5",
 		"@pnpm/catalogs.protocol-parser": "^1100.0.0",
 		"@pnpm/catalogs.resolver": "^1100.0.0",
 		"@pnpm/catalogs.types": "^1100.0.0"
 	},
 	"peerDependencies": {
-		"effect": "4.0.0-rc.118"
+		"effect": "^4.0.0"
 	},
 	"engines": {
 		"node": ">=24.11.0"

package/testing.d.ts

@@ -57,7 +57,7 @@ declare const LayerPolicy_base: Schema.Class<LayerPolicy, Schema.Struct<{
  * 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
@@ -136,7 +136,7 @@ interface DependencyDiff {
   readonly added: Record<string, string>;
   /** Present in the other, absent from the receiver. */
   readonly removed: Record<string, string>;
-  /** Present in both at different specifiers. */
+  /** Present in both at different specifiers: `from` is the other package's, `to` the receiver's. */
   readonly changed: Record<string, {
     readonly from: string;
     readonly to: string;
@@ -196,13 +196,9 @@ declare const WorkspacePackage_base: Schema.Class<WorkspacePackage, Schema.Struc
    * 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 `"."`.
    */
@@ -229,8 +225,7 @@ declare const WorkspacePackage_base: Schema.Class<WorkspacePackage, Schema.Struc
    * 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.
    */
   readonly manifestRecord: Schema.withConstructorDefault<Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.Unknown>, never>>;
 }>, {}>;
@@ -293,8 +288,8 @@ export declare class WorkspacePackage extends WorkspacePackage_base {
   /** The declared specifier for `name`, searched across all four kinds. */
   dependencyVersion(name: string): Option.Option<string>;
   /**
-   * 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
@@ -307,7 +302,12 @@ export declare class WorkspacePackage extends WorkspacePackage_base {
    * @param pattern - A compiled pattern, or a source string to compile.
    */
   matchesDependency(pattern: GlobPattern | string): boolean;
-  /** 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: WorkspacePackage): DependencyDiff;
   /**
    * Project to `@effected/lockfiles`' `WorkspaceManifest` — the input shape of
@@ -318,6 +318,10 @@ export declare class WorkspacePackage extends WorkspacePackage_base {
    * 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 readonly manifest: (self: WorkspacePackage) => Effect.Effect<Package, WorkspaceManifestError, FileSystem.FileSystem>;
   /** Instance form of `WorkspacePackage.manifest`. */
@@ -462,12 +466,10 @@ export declare class WorkspaceRoot extends WorkspaceRoot_base {
    * 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}.
    *
@@ -541,7 +543,7 @@ declare const WorkspaceDiscoveryError_base: Schema.Class<WorkspaceDiscoveryError
  * 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`.
@@ -650,11 +652,10 @@ interface WorkspaceDiscoveryOptions {
    * `importerMap`, `getPackage`, `resolveFile`, `resolveFiles`). The per-call
    * `infoIn`, `listPackagesIn` and `refreshIn` resolve from an arbitrary
    * directory the caller names, which a single layer-level ceiling cannot
-   * sensibly bound, so they ascend unbounded as before.
+   * sensibly bound, so they ascend unbounded.
    *
    * `LockfileReader`, `WorkspaceCatalogs` and `WorkspaceSnapshots` each
-   * take the same option; give them the same
-   * value when wiring by hand, or let a `Workspaces.*` composite forward one
+   * take the same option; give them the same value when wiring by hand, or let a `Workspaces.*` composite forward one
    * `stopAt` to all of them, so no service adopts a root another refused.
    *
    * @defaultValue no ceiling — the ascent runs to the filesystem root.
@@ -751,11 +752,9 @@ declare const WorkspaceDiscovery_base: Context.ServiceClass<WorkspaceDiscovery,
  * 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
@@ -778,12 +777,14 @@ export declare class WorkspaceDiscovery extends WorkspaceDiscovery_base {
    */
   static readonly make: (options?: WorkspaceDiscoveryOptions) => Effect.Effect<WorkspaceDiscoveryShape, never, WorkspaceRoot | FileSystem.FileSystem | Path.Path>;
   /**
-   * 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 readonly layer: (options?: WorkspaceDiscoveryOptions) => Layer.Layer<WorkspaceDiscovery, never, WorkspaceRoot | FileSystem.FileSystem | Path.Path>;
   /**
@@ -894,12 +895,12 @@ export declare class WorkspaceDiscovery extends WorkspaceDiscovery_base {
  * @remarks
  * `{ directory }` runs `npm pack` in that subdirectory of each package, whose
  * manifest must already be publish-ready. The default,
- * `{ directory: "dist/prod/npm/pkg" }`, is the effected bundler's prod npm
+ * `{ directory: "dist/prod/npm/pkg" }`, is `@savvy-web/bundler`'s prod npm
  * output: the same file list a release publishes.
  *
  * `"source"` runs `pnpm pack` in the package directory: pnpm honours
  * `publishConfig.directory` and rewrites `workspace:` and `catalog:`
- * specifiers. Two costs. Under the effected bundler `publishConfig.directory`
+ * specifiers. Two costs. Under `@savvy-web/bundler`, `publishConfig.directory`
  * names the DEV build, so source mode proves the dev artifact, not the
  * published one. And pnpm can rewrite a `workspace:` specifier only in a
  * workspace that has been `pnpm install`ed: in a never-installed one the pack
@@ -937,10 +938,10 @@ interface PackedInstallClosureOptions {
    * `.tgz`, with or without a `file:` prefix.
    *
    * @remarks
-   * The dogfood case: a closure member imports a surface of a dependency
-   * that exists only in a sibling checkout's unreleased build, and the
-   * registry's copy lacks it. A directory is `npm pack`ed, so it must be
-   * publish-ready (for an effected-bundled package, its
+   * For a closure member that imports a surface of a dependency existing
+   * only in a sibling checkout's unreleased build, which the registry's copy
+   * lacks. A directory is `npm pack`ed, so it must be
+   * publish-ready (for a package built by `@savvy-web/bundler`, its
    * `dist/prod/npm/pkg`); a `.tgz` is used as it is. Either way the packed
    * manifest must be named as its key, carry no specifier only a workspace
    * could resolve, and it joins `PackedInstallResult.tarballs`. Each
@@ -957,9 +958,9 @@ interface PackedInstallClosureOptions {
   readonly overrides?: Readonly<Record<string, string>> | undefined;
   /**
    * Also read the workspace root's `pnpm-workspace.yaml` and take every
-   * `overrides:` entry of the dogfood link shape,
-   * `"@scope/name": "file:<dir>"`, as if passed through `overrides`: the
-   * linked sibling builds the workspace itself installs. Entries that are not `file:`, or
+   * `overrides:` entry of the link shape `"@scope/name": "file:<dir>"` as if
+   * passed through `overrides`: the linked sibling builds the workspace itself
+   * installs. Entries that are not `file:`, or
    * whose key carries a selector (`a>b`, `a@1`), are left out. A root with
    * no readable `pnpm-workspace.yaml`, or one that is not YAML, fails
    * `InvalidOverride`.
@@ -1761,7 +1762,7 @@ export declare class SourceBoundary {
   static readonly scan: (options: ScanOptions) => Effect.Effect<SourceScan, import("@effected/glob").GlobPatternError | import("effect/PlatformError").PlatformError, FileSystem.FileSystem | Path.Path>;
   /** The shipped positive- and negative-control snippets, at least one of each per rule kind. */
   static readonly fixtures: ReadonlyArray<BoundaryFixture>;
-  /** 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 readonly verifyFixtures: () => ReadonlyArray<string>;
 }
 //#endregion