@effected/workspaces 0.25.0 → 0.26.0

package/testing.d.ts

@@ -0,0 +1,1382 @@
+import { DependencyField, WorkspaceResolver } from "@effected/npm";
+import { Context, Duration, Effect, FileSystem, Layer, Option, Path, Schema } from "effect";
+import { GlobPattern } from "@effected/glob";
+import { WorkspaceManifest } from "@effected/lockfiles";
+import { Package } from "@effected/package-json";
+//#region src/LayerPolicy.d.ts
+declare const LayerPolicyError_base: Schema.Class<LayerPolicyError, Schema.TaggedStruct<"LayerPolicyError", {
+  /** `read`: the file could not be read. `json`: it is not JSON. `decode`: it is not a `LayerPolicy`. */
+  readonly reason: Schema.Literals<readonly ["read", "json", "decode"]>;
+  /** The file, when the policy came from one. */
+  readonly path: Schema.optionalKey<Schema.String>;
+  /** The originating failure. */
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when a layer policy cannot be read, parsed or decoded.
+ *
+ * @public
+ */
+export declare class LayerPolicyError extends LayerPolicyError_base {
+  /** Renders the failure kind and the file into one line. */
+  get message(): string;
+}
+declare const LayerPolicy_base: Schema.Class<LayerPolicy, Schema.Struct<{
+  /** Exact package names (never relative paths) per layer, top layer first. */
+  readonly layers: Schema.$Array<Schema.$Array<Schema.String>>;
+  /** Exact package names (never relative paths) any layer may depend on that never depend on a layer. */
+  readonly tooling: Schema.$Array<Schema.String>;
+  /** Globs matched against package names (never relative paths) for packages whose own edges are not checked. */
+  readonly unconstrained: Schema.$Array<Schema.String>;
+  /** The dependency maps to check. Absent means all four. */
+  readonly fields: Schema.optionalKey<Schema.$Array<Schema.Literals<readonly ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"]>>>;
+  /** Edges that must exist, written `"a -> b"`. */
+  readonly requiredEdges: Schema.optionalKey<Schema.$Array<Schema.String>>;
+}>, {}>;
+/**
+ * A committed dependency-layering policy (`layers.json`).
+ *
+ * @remarks
+ * `layers` is top-down: an edge may only point from a layer to one BELOW it
+ * (a higher index), or into `tooling`. `tooling` packages may depend on each
+ * other but never reach a layer. `unconstrained` holds globs (through
+ * `@effected/glob`) for packages whose own edges are not checked (a test
+ * harness, the private root). `fields` narrows which dependency maps count,
+ * defaulting to all four. `requiredEdges` (`"a -> b"`) are edges that must
+ * exist in a checked field: the non-vacuity guard against a discovery that
+ * quietly drops real edges.
+ *
+ * Every entry matches a package's `name`, never its `relativePath`: `layers`
+ * and `tooling` list exact names, and `unconstrained` globs match names. A
+ * private root named `my-monorepo` at `relativePath` `"."` is classified as
+ * `"my-monorepo"`; an entry of `"."` or `"packages/*"` classifies nothing.
+ *
+ * Decoding is strict: a key the policy does not model fails `decode`, and the
+ * 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`.
+ *
+ * @example
+ * ```ts
+ * import { NodeServices } from "@effect/platform-node";
+ * import { LayerPolicy } from "@effected/workspaces/testing";
+ * import { Effect } from "effect";
+ *
+ * const policy = LayerPolicy.load("/repo/layers.json").pipe(Effect.provide(NodeServices.layer));
+ * ```
+ *
+ * @public
+ */
+export declare class LayerPolicy extends LayerPolicy_base {
+  /** The dependency maps a check reads: `fields`, or all four. */
+  get effectiveFields(): ReadonlyArray<DependencyField>;
+  /**
+   * Decode a policy from a parsed JSON value.
+   *
+   * @remarks
+   * Every key the policy does not model fails, except `$schema` and the
+   * keys named in `options.allowKeys`, which are dropped before decoding.
+   * `options.path` names the file in the error.
+   */
+  static readonly decode: (input: unknown, options?: {
+    readonly path?: string | undefined;
+    readonly allowKeys?: ReadonlyArray<string> | undefined;
+  } | undefined) => Effect.Effect<LayerPolicy, LayerPolicyError, never>;
+  /** Read, parse and decode the policy file at `path`; `options.allowKeys` is passed to `decode`. */
+  static readonly load: (path: string, options?: {
+    readonly allowKeys?: ReadonlyArray<string> | undefined;
+  } | undefined) => Effect.Effect<LayerPolicy, LayerPolicyError, FileSystem.FileSystem>;
+}
+//#endregion
+//#region src/WorkspacePackage.d.ts
+declare const PublishConfig_base: Schema.Class<PublishConfig, Schema.Struct<{
+  /** Scoped-package visibility. Its presence overrides `private`. */
+  readonly access: Schema.optionalKey<Schema.Literals<readonly ["public", "restricted"]>>;
+  /** The registry to publish to. */
+  readonly registry: Schema.optionalKey<Schema.String>;
+  /** A subdirectory to publish instead of the package root. */
+  readonly directory: Schema.optionalKey<Schema.String>;
+  /**
+   * Whether workspace links point into `directory` during local development —
+   * pnpm symlinks the publish directory instead of the package root, so
+   * siblings resolve the built artifact they would install from the registry.
+   * Meaningful only alongside `directory`.
+   */
+  readonly linkDirectory: Schema.optionalKey<Schema.Boolean>;
+  /** The dist-tag to publish under. */
+  readonly tag: Schema.optionalKey<Schema.String>;
+}>, {}>;
+/**
+ * The `publishConfig` fields workspace tooling reads.
+ *
+ * @remarks
+ * Deliberately narrow. `@effected/package-json` models `publishConfig` as an
+ * open `Record<string, unknown>` for round-trip fidelity, which preserves every
+ * key but types none of them; this is the typed projection of the handful that
+ * decide *where, whether and as what* a package publishes. Unknown keys are
+ * ignored, not rejected.
+ *
+ * @public
+ */
+export declare class PublishConfig extends PublishConfig_base {}
+/**
+ * The result of comparing two {@link WorkspacePackage} dependency snapshots.
+ *
+ * @remarks
+ * Comparison runs across all four dependency kinds combined, so a dependency
+ * that moves between kinds at the same version does not appear in the diff.
+ *
+ * @public
+ */
+interface DependencyDiff {
+  /** Present in the receiver, absent from the other. */
+  readonly added: Record<string, string>;
+  /** Present in the other, absent from the receiver. */
+  readonly removed: Record<string, string>;
+  /** Present in both at different specifiers. */
+  readonly changed: Record<string, {
+    readonly from: string;
+    readonly to: string;
+  }>;
+}
+declare const WorkspaceManifestError_base: Schema.Class<WorkspaceManifestError, Schema.TaggedStruct<"WorkspaceManifestError", {
+  /** Absolute path to the `package.json` that failed. */
+  readonly packageJsonPath: Schema.String;
+  /** Whether the file could not be read, or read but not decoded. */
+  readonly kind: Schema.Literals<readonly ["read", "decode"]>;
+  /** The originating failure, preserved rather than flattened to a string. */
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when a workspace member's `package.json` cannot be read or decoded
+ * into the strict `@effected/package-json` `Package` model.
+ *
+ * @remarks
+ * Discovery itself never raises this — it uses the tolerant projection. Only
+ * `WorkspacePackage.manifest` does, so opting into the strict model is an
+ * explicit, individually recoverable step.
+ *
+ * @public
+ */
+export declare class WorkspaceManifestError extends WorkspaceManifestError_base {
+  /** Renders the path and failure kind into a one-line message. */
+  get message(): string;
+}
+declare const WorkspacePackage_base: Schema.Class<WorkspacePackage, Schema.Struct<{
+  /** The package name. */
+  readonly name: Schema.NonEmptyString;
+  /**
+   * The raw `version` string — deliberately not semver-validated — or absent
+   * when the manifest declares none.
+   *
+   * @remarks
+   * pnpm accepts a version-less private package, and a private monorepo root
+   * without a `version` is the ordinary shape, so discovery carries the field
+   * exactly as the manifest has it: a non-empty string when present, verbatim
+   * and un-validated, absent when the key is absent — never a `"0.0.0"`
+   * placeholder and never a present `undefined` key. **Only ABSENCE is
+   * tolerated**: a `version` that is present but not a string, or present and
+   * `""`, fails discovery as `invalidShape` on both surfaces. `""` in
+   * particular is not a pnpm shape and would resolve `workspace:^` to a bare
+   * `"^"`.
+   * Anything that needs a concrete version (`WorkspaceResolver.versionOf`,
+   * a release tag) answers the absence itself rather than inventing one.
+   */
+  readonly version: Schema.optionalKey<Schema.String>;
+  /** Absolute path to the package directory. */
+  readonly path: Schema.NonEmptyString;
+  /** Absolute path to the package's `package.json`. */
+  readonly packageJsonPath: Schema.NonEmptyString;
+  /** POSIX path relative to the workspace root; `"."` for the root package. */
+  readonly relativePath: Schema.String;
+  /**
+   * 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.
+   *
+   * For the root package this equals `path`, and `relativePath` is `"."`.
+   */
+  readonly workspaceRoot: Schema.NonEmptyString;
+  /** Whether the package is marked private. */
+  readonly private: Schema.withConstructorDefault<Schema.withDecodingDefaultKey<Schema.Boolean, never>>;
+  /** Production dependencies. */
+  readonly dependencies: Schema.withConstructorDefault<Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.String>, never>>;
+  /** Development dependencies. */
+  readonly devDependencies: Schema.withConstructorDefault<Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.String>, never>>;
+  /** Peer dependencies. */
+  readonly peerDependencies: Schema.withConstructorDefault<Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.String>, never>>;
+  /** Optional dependencies. */
+  readonly optionalDependencies: Schema.withConstructorDefault<Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.String>, never>>;
+  /** The `publishConfig` block, when present. */
+  readonly publishConfig: Schema.optionalKey<typeof PublishConfig>;
+  /**
+   * The package's `package.json` as read — tolerant access to every field
+   * outside the typed discovery slice (`scripts`, `exports`, …) without a
+   * second file read.
+   *
+   * @remarks
+   * Values are `unknown` and exactly what discovery parsed; nothing here is
+   * 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.
+   */
+  readonly manifestRecord: Schema.withConstructorDefault<Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.Unknown>, never>>;
+}>, {}>;
+/**
+ * A single package inside a workspace: the discovery-relevant slice of its
+ * `package.json` plus its filesystem location.
+ *
+ * @remarks
+ * Produced by `WorkspaceDiscovery` for every directory the `packages:` patterns
+ * enumerate. The root package is always present with `relativePath` `"."`.
+ *
+ * @example
+ * ```ts
+ * import { WorkspacePackage } from "@effected/workspaces";
+ *
+ * const pkg = WorkspacePackage.make({
+ *   name: "@my-org/utils",
+ *   version: "1.0.0",
+ *   path: "/repo/packages/utils",
+ *   packageJsonPath: "/repo/packages/utils/package.json",
+ *   relativePath: "packages/utils",
+ *   workspaceRoot: "/repo",
+ * });
+ *
+ * pkg.isRootWorkspace; // false
+ * pkg.unscopedName;    // "utils"
+ * pkg.workspaceRoot;   // "/repo"
+ * ```
+ *
+ * @public
+ */
+export declare class WorkspacePackage extends WorkspacePackage_base {
+  /** Whether this is the workspace root package. */
+  get isRootWorkspace(): boolean;
+  /** Whether the package is publishable in principle (not marked private). */
+  get isPublic(): boolean;
+  /** The npm scope (`@org`), or `Option.none()` for an unscoped name. */
+  get scope(): Option.Option<string>;
+  /** The name with any scope stripped. */
+  get unscopedName(): string;
+  /**
+   * Every dependency, merged across the four kinds.
+   *
+   * @remarks
+   * Precedence on a name declared in several kinds runs
+   * `dependencies` \> `devDependencies` \> `peerDependencies` \>
+   * `optionalDependencies`.
+   */
+  get allDependencies(): Record<string, string>;
+  /** Whether `name` is a production dependency. */
+  hasDependency(name: string): boolean;
+  /** Whether `name` is a development dependency. */
+  hasDevDependency(name: string): boolean;
+  /** Whether `name` is a peer dependency. */
+  hasPeerDependency(name: string): boolean;
+  /** Whether `name` is an optional dependency. */
+  hasOptionalDependency(name: string): boolean;
+  /** Whether `name` appears in any of the four dependency kinds. */
+  hasAnyDependencyOn(name: string): boolean;
+  /** 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.
+   *
+   * @remarks
+   * A `GlobPattern` is total and free to test. A `string` is compiled on every
+   * call and an **uncompilable** literal throws: a glob written into a call
+   * site is developer wiring, not untrusted input, so it belongs in the defect
+   * channel rather than widening the typed channel every caller must branch
+   * on. Compile once with `GlobPattern.compile` and pass the result when
+   * testing many packages.
+   *
+   * @param pattern - A compiled pattern, or a source string to compile.
+   */
+  matchesDependency(pattern: GlobPattern | string): boolean;
+  /** Compare this package's dependencies against `other`'s. */
+  dependencyDiff(other: WorkspacePackage): DependencyDiff;
+  /**
+   * Project to `@effected/lockfiles`' `WorkspaceManifest` — the input shape of
+   * `LockfileIntegrity.compare`. Total.
+   */
+  toWorkspaceManifest(): WorkspaceManifest;
+  /**
+   * 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.
+   */
+  static readonly manifest: (self: WorkspacePackage) => Effect.Effect<Package, WorkspaceManifestError, FileSystem.FileSystem>;
+  /** Instance form of `WorkspacePackage.manifest`. */
+  manifest(): Effect.Effect<Package, WorkspaceManifestError, FileSystem.FileSystem>;
+}
+//#endregion
+//#region src/PackageManagerName.d.ts
+/**
+ * The four package managers this package understands.
+ *
+ * @public
+ */
+export declare const PackageManagerName: Schema.Literals<readonly ["npm", "pnpm", "yarn", "bun"]>;
+/**
+ * The decoded type of {@link (PackageManagerName:variable)}: `"npm" | "pnpm" | "yarn" | "bun"`.
+ *
+ * @public
+ */
+export type PackageManagerName = typeof PackageManagerName.Type;
+//#endregion
+//#region src/WorkspaceRoot.d.ts
+/**
+ * Options for {@link WorkspaceRoot}'s `find`.
+ *
+ * @remarks
+ * Both bounds are passed straight through to `@effected/walker`'s
+ * `Walker.ascend`; this package does not re-decide either.
+ *
+ * @public
+ */
+interface FindWorkspaceRootOptions {
+  /**
+   * A ceiling directory. The ascent stops after probing it, so an unmarked
+   * `stopAt` fails typed as {@link WorkspaceRootNotFoundError} rather than
+   * silently escaping into an enclosing repository.
+   *
+   * @remarks
+   * Resolved to an absolute path before comparison, exactly as `cwd` is — a
+   * relative or non-normalized ceiling that never string-matched an ancestor
+   * would reintroduce the unbounded ascent it was passed to prevent.
+   */
+  readonly stopAt?: string;
+  /**
+   * Hard cap on the number of directories probed.
+   *
+   * @remarks
+   * A non-integer or non-positive value is a **defect**, not a typed failure —
+   * it is developer wiring, and walker's guard raises it.
+   *
+   * @defaultValue 256
+   */
+  readonly maxDepth?: number;
+}
+declare const WorkspaceRootNotFoundError_base: Schema.Class<WorkspaceRootNotFoundError, Schema.TaggedStruct<"WorkspaceRootNotFoundError", {
+  /** The directory the ascent started from. */
+  readonly searchPath: Schema.String;
+  /** The marker filenames probed at each ancestor. */
+  readonly markers: Schema.$Array<Schema.String>;
+  /**
+   * The resolved ceiling the ascent was bounded by, when one was supplied.
+   *
+   * @remarks
+   * Absent means the ascent ran to the filesystem root. Its presence is what
+   * lets a caller tell "there is no workspace root anywhere above me" from
+   * "there is none below the ceiling I set" — two failures that otherwise
+   * render identically.
+   */
+  readonly stopAt: Schema.optionalKey<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when no workspace root can be found by ascending from a directory.
+ *
+ * @remarks
+ * `markers` records what was probed, so the failure names the contract rather
+ * than paraphrasing it in prose.
+ *
+ * @public
+ */
+export declare class WorkspaceRootNotFoundError extends WorkspaceRootNotFoundError_base {
+  /** Renders the search path, probed markers and any ceiling into a one-line message. */
+  get message(): string;
+}
+/**
+ * The {@link WorkspaceRoot} service contract.
+ *
+ * @remarks
+ * Named so a consumer can type its own double — or a `Layer.succeed` — against
+ * the contract rather than re-deriving it, exactly as `WorkspaceDiscoveryShape`
+ * does. Prefer {@link WorkspaceRoot.layerTest} to hand-rolling one.
+ *
+ * @public
+ */
+interface WorkspaceRootShape {
+  /**
+   * The nearest workspace root at or above `cwd`.
+   *
+   * @param cwd - The directory to start the ascent from; resolved to an
+   *   absolute path first.
+   * @param options - Optional ascent bounds. Unbounded by default, which
+   *   walks to the filesystem root and can therefore resolve to an enclosing
+   *   repository's root; pass `stopAt` when the caller knows the ceiling.
+   */
+  readonly find: (cwd: string, options?: FindWorkspaceRootOptions) => Effect.Effect<string, WorkspaceRootNotFoundError>;
+}
+declare const WorkspaceRoot_base: Context.ServiceClass<WorkspaceRoot, "@effected/workspaces/WorkspaceRoot", WorkspaceRootShape>;
+/**
+ * Locates the workspace root by ascending from a starting directory.
+ *
+ * @example
+ * ```ts
+ * import { WorkspaceRoot } from "@effected/workspaces";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const root = yield* WorkspaceRoot;
+ *   return yield* root.find("/repo/packages/utils/src");
+ * });
+ * ```
+ *
+ * @example
+ * Bounded: an unmarked fixture directory fails typed instead of escaping into
+ * the enclosing repository.
+ *
+ * ```ts
+ * import { WorkspaceRoot } from "@effected/workspaces";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const roots = yield* WorkspaceRoot;
+ *   return yield* roots.find("/tmp/fixture/packages/a", { stopAt: "/tmp/fixture" });
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare class WorkspaceRoot extends WorkspaceRoot_base {
+  /** Builds the service over core `FileSystem` and `Path`. */
+  static readonly make: Effect.Effect<WorkspaceRootShape, never, FileSystem.FileSystem | Path.Path>;
+  /** The live layer. */
+  static readonly layer: Layer.Layer<WorkspaceRoot, never, FileSystem.FileSystem | Path.Path>;
+  /**
+   * 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
+   * here exactly as it would live, with the same
+   * {@link WorkspaceRootNotFoundError}.
+   *
+   * The ceiling is `path.resolve`d through the injected `Path` service before
+   * the comparison, exactly as the live `make` path does — so a `stopAt`
+   * carrying `..` segments bounds the double identically to the live service,
+   * not by raw string. This is why `makeTest` yields an `Effect` requiring
+   * `Path`: it captures the service once at construction, the same shape as
+   * `make`. Consumers reach for {@link WorkspaceRoot.layerTest}, which provides
+   * `Path.layer` internally, so the requirement never surfaces at their call
+   * site.
+   *
+   * `maxDepth` is deliberately NOT modelled: the double does not walk, so it has
+   * no depth to cap, and pretending otherwise would encode a fiction. A suite
+   * exercising the depth guard wants the live service over a fixture tree.
+   *
+   * @param root - The root every unbounded `find` resolves to.
+   */
+  static readonly makeTest: (root: string) => Effect.Effect<WorkspaceRootShape, never, Path.Path>;
+  /**
+   * The test layer: {@link WorkspaceRoot.makeTest} with `Path.layer` provided.
+   *
+   * @remarks
+   * `makeTest` requires `Path` to normalize the `stopAt` ceiling; this layer
+   * supplies core's `Path.layer` internally, so the requirement never reaches a
+   * consumer — the published type stays `Layer.Layer<WorkspaceRoot>`.
+   *
+   * 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.
+   *
+   * Pair it with `WorkspaceDiscovery.layerTest` to stand up the whole discovery
+   * path without a filesystem; between them there is nothing left for a
+   * module-level mock of `@effected/workspaces` to do, and a provided layer
+   * keeps the service graph — and its typed errors — intact.
+   *
+   * @example
+   * ```ts
+   * import { WorkspaceDiscovery, WorkspaceRoot } from "@effected/workspaces";
+   * import { Effect } from "effect";
+   *
+   * const TestRoot = WorkspaceRoot.layerTest("/repo");
+   * const TestDiscovery = WorkspaceDiscovery.layerTest({
+   *   listPackages: () => Effect.succeed([]),
+   * });
+   * // program.pipe(Effect.provide(TestRoot), Effect.provide(TestDiscovery))
+   * ```
+   */
+  static readonly layerTest: (root: string) => Layer.Layer<WorkspaceRoot>;
+}
+//#endregion
+//#region src/WorkspaceDiscovery.d.ts
+declare const WorkspaceDiscoveryError_base: Schema.Class<WorkspaceDiscoveryError, Schema.TaggedStruct<"WorkspaceDiscoveryError", {
+  /** The workspace root discovery was running against. */
+  readonly root: Schema.String;
+  /** The file that failed. */
+  readonly path: Schema.String;
+  /** What went wrong with it. */
+  readonly kind: Schema.Literals<readonly ["read", "invalidJson", "invalidShape", "invalidYaml", "missingName"]>;
+  /** The originating failure, if there was one. */
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when a workspace member's `package.json` cannot be read, parsed, or
+ * used — it is missing, malformed, or lacks a `name`.
+ *
+ * @remarks
+ * `kind` is the discriminant a caller branches on; `cause` preserves the
+ * originating failure rather than flattening it into a sentence.
+ *
+ * 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
+ * `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`.
+ *
+ * @public
+ */
+export declare class WorkspaceDiscoveryError extends WorkspaceDiscoveryError_base {
+  /** Renders the failing file and kind into a one-line message. */
+  get message(): string;
+}
+declare const WorkspacePatternError_base: Schema.Class<WorkspacePatternError, Schema.TaggedStruct<"WorkspacePatternError", {
+  /** The workspace root the patterns were expanded against. */
+  readonly root: Schema.String;
+  /** The offending pattern, verbatim. */
+  readonly pattern: Schema.String;
+  /** Why it could not be enumerated. */
+  readonly kind: Schema.Literals<readonly ["missingBaseDir", "uncompilable", "depthExceeded", "budgetExceeded", "unreadableDirectory"]>;
+  /** A short, structured detail — the missing directory, or the bound exceeded. */
+  readonly detail: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when a `packages:` pattern cannot be enumerated: its base directory is
+ * absent (usually a typo), the descent exceeded its depth cap, or the visit
+ * budget was exhausted.
+ *
+ * @public
+ */
+export declare class WorkspacePatternError extends WorkspacePatternError_base {
+  /** Renders the pattern and failure kind into a one-line message. */
+  get message(): string;
+}
+declare const PackageNotFoundError_base: Schema.Class<PackageNotFoundError, Schema.TaggedStruct<"PackageNotFoundError", {
+  /** The name that was requested. */
+  readonly name: Schema.String;
+  /** Every workspace package name that does exist. */
+  readonly available: Schema.$Array<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when a workspace package is requested by a name no member carries.
+ *
+ * @remarks
+ * `available` lists every known member, which is what makes the error
+ * actionable — a typo is obvious next to the list it missed.
+ *
+ * @public
+ */
+export declare class PackageNotFoundError extends PackageNotFoundError_base {
+  /** Renders the requested name into a one-line message. */
+  get message(): string;
+}
+declare const WorkspaceInfo_base: Schema.Class<WorkspaceInfo, Schema.Struct<{
+  /** Absolute path to the workspace root. */
+  readonly root: Schema.String;
+  /** The `packages:` patterns, verbatim. */
+  readonly patterns: Schema.$Array<Schema.String>;
+}>, {}>;
+/**
+ * Top-level facts about a workspace: where it is, what manages it, and the
+ * patterns that define its membership.
+ *
+ * @public
+ */
+export declare class WorkspaceInfo extends WorkspaceInfo_base {}
+/**
+ * Every failure `WorkspaceDiscovery.getPackage` can surface: the discovery
+ * failures plus a name that matches no member.
+ *
+ * @public
+ */
+type WorkspaceLookupFailure = WorkspaceRootNotFoundError | WorkspaceDiscoveryError | WorkspacePatternError | PackageNotFoundError;
+/**
+ * The error channel of the discovery methods that do not look a package up by
+ * name — everything except `getPackage`.
+ *
+ * @public
+ */
+type WorkspaceDiscoveryFailure = Exclude<WorkspaceLookupFailure, PackageNotFoundError>;
+/**
+ * Options for the {@link WorkspaceDiscovery} layer.
+ *
+ * @public
+ */
+interface WorkspaceDiscoveryOptions {
+  /**
+   * The directory the workspace root is resolved from.
+   *
+   * @defaultValue `process.cwd()`, read lazily on first use — so a
+   *   `process.chdir` between providing the layer and the first call is
+   *   honoured.
+   */
+  readonly cwd?: string;
+  /** Descent cap for segment-crossing patterns. Defaults to 32. */
+  readonly maxDepth?: number;
+}
+/**
+ * The {@link WorkspaceDiscovery} service shape.
+ *
+ * @public
+ */
+interface WorkspaceDiscoveryShape {
+  /** Facts about the resolved workspace. */
+  readonly info: () => Effect.Effect<WorkspaceInfo, WorkspaceDiscoveryFailure>;
+  /** Every workspace package, root first, then the rest sorted by relative path. */
+  readonly listPackages: () => Effect.Effect<ReadonlyArray<WorkspacePackage>, WorkspaceDiscoveryFailure>;
+  /** The discovered packages keyed by their root-relative importer path. */
+  readonly importerMap: () => Effect.Effect<ReadonlyMap<string, WorkspacePackage>, WorkspaceDiscoveryFailure>;
+  /** A single package by name. */
+  readonly getPackage: (name: string) => Effect.Effect<WorkspacePackage, WorkspaceLookupFailure>;
+  /** The package owning an absolute file path, by longest-prefix match. */
+  readonly resolveFile: (filePath: string) => Effect.Effect<Option.Option<WorkspacePackage>, WorkspaceDiscoveryFailure>;
+  /** The distinct packages owning any of `filePaths`. */
+  readonly resolveFiles: (filePaths: ReadonlyArray<string>) => Effect.Effect<ReadonlyArray<WorkspacePackage>, WorkspaceDiscoveryFailure>;
+  /**
+   * Facts about the workspace containing `directory`, discovered against THAT
+   * root rather than the layer-bound one.
+   */
+  readonly infoIn: (directory: string) => Effect.Effect<WorkspaceInfo, WorkspaceDiscoveryFailure>;
+  /**
+   * Every package of the workspace containing `directory`, discovered against
+   * THAT root rather than the layer-bound one.
+   *
+   * @remarks
+   * For a **long-lived host serving many roots** — an MCP server or a language
+   * server that resolves one workspace at startup and then answers calls
+   * scoped to a git worktree, a nested repository, or another project
+   * entirely. The layer-bound {@link WorkspaceDiscoveryShape.listPackages}
+   * answers about the root discovered from `options.cwd`, which such a host
+   * has no way to vary per call without building a fresh layer.
+   *
+   * **This re-reads; it does not re-root.** The tempting cheap fix — take the
+   * layer's package list and rewrite each `path` onto the caller's directory —
+   * produces correct-looking paths over the ORIGINAL root's manifests, so a
+   * worktree whose branch adds, removes or renames a package reports the other
+   * branch's membership with no error. Patterns, member manifests, names and
+   * versions all come from beneath `directory`'s own root here.
+   *
+   * `directory` may be the workspace root or anything inside it: the root is
+   * resolved by the same upward walk the layer-bound path uses, and results are
+   * memoized per RESOLVED root, so many directories in one workspace share one
+   * discovery. The memo holds one entry per distinct root for the layer's
+   * lifetime; {@link WorkspaceDiscoveryShape.refresh} drops all of them.
+   *
+   * @param directory - Absolute path to the workspace root, or to any
+   *   directory inside it.
+   */
+  readonly listPackagesIn: (directory: string) => Effect.Effect<ReadonlyArray<WorkspacePackage>, WorkspaceDiscoveryFailure>;
+  /**
+   * Drop every memoized discovery — the layer-bound one and each per-root memo
+   * — so the next call re-reads the filesystem.
+   */
+  readonly refresh: () => Effect.Effect<void>;
+  /**
+   * Drop only the memo for the workspace containing `directory`, leaving the
+   * layer-bound memo and every other root's untouched.
+   *
+   * @remarks
+   * The precise counterpart to {@link WorkspaceDiscoveryShape.refresh} for a
+   * host serving several roots: refreshing one worktree because it changed
+   * should not discard sibling worktrees that did not, which is all `refresh`
+   * can do.
+   *
+   * **Fails typed on a directory in no workspace**, exactly as
+   * {@link WorkspaceDiscoveryShape.listPackagesIn} does for the same input —
+   * the three per-root methods answer a bad path the same way, and a caller
+   * that would rather treat it as a no-op writes `Effect.ignore`. Refreshing a
+   * root that HAS no memo is an ordinary no-op and not an error.
+   *
+   * @param directory - Absolute path to the workspace root, or to any
+   *   directory inside it.
+   */
+  readonly refreshIn: (directory: string) => Effect.Effect<void, WorkspaceRootNotFoundError>;
+}
+declare const WorkspaceDiscovery_base: Context.ServiceClass<WorkspaceDiscovery, "@effected/workspaces/WorkspaceDiscovery", WorkspaceDiscoveryShape>;
+/**
+ * Discovers the packages of a workspace.
+ *
+ * @remarks
+ * Layer construction is O(1): the root walk, pattern read, enumeration and
+ * per-package decode all happen on the first method call and are memoized for
+ * 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.
+ *
+ * @example
+ * ```ts
+ * import { WorkspaceDiscovery } from "@effected/workspaces";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const discovery = yield* WorkspaceDiscovery;
+ *   const packages = yield* discovery.listPackages();
+ *   return packages.map((p) => p.name);
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare class WorkspaceDiscovery extends WorkspaceDiscovery_base {
+  /**
+   * Builds the service. Root resolution is one explicit concern: `cwd` is an
+   * option here, never an ambient `process.cwd()` read inside a method.
+   */
+  static readonly make: (options?: WorkspaceDiscoveryOptions) => Effect.Effect<WorkspaceDiscoveryShape, never, WorkspaceRoot | FileSystem.FileSystem | Path.Path>;
+  /**
+   * The live layer.
+   *
+   * @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.
+   */
+  static readonly layer: (options?: WorkspaceDiscoveryOptions) => Layer.Layer<WorkspaceDiscovery, never, WorkspaceRoot | FileSystem.FileSystem | Path.Path>;
+  /**
+   * An in-memory test double of the service shape, with every method
+   * defaulted so a test stubs only what it exercises.
+   *
+   * @remarks
+   * The defaults model an **empty workspace**, and the derived methods run
+   * over the *effective* `listPackages` — the override when one is supplied —
+   * so stubbing only `listPackages` yields a consistent double:
+   *
+   * - `listPackages` — succeeds with `[]`.
+   * - `importerMap` — derived: the packages keyed by `relativePath`.
+   * - `getPackage` — derived: a name lookup that fails with the service's own
+   *   typed {@link PackageNotFoundError} on a miss, exactly as the live
+   *   implementation does.
+   * - `resolveFile` / `resolveFiles` — derived: longest-prefix ownership over
+   *   `pkg.path`, POSIX-terminated (`"/"`); supply a win32 double explicitly
+   *   if your fixture paths are win32.
+   * - `refresh` — a no-op (`Effect.void`); there is nothing memoized to drop.
+   * - `info` — **dies** with an explanatory defect. No honest default exists
+   *   (a fabricated root path would leak into consumer path logic), so an
+   *   unstubbed `info()` call is a test-wiring mistake and fails loudly as a
+   *   defect rather than succeeding with a lie or failing with a dishonest
+   *   typed error. A defect is not absorbed by `Effect.catch` or any
+   *   typed-error handler — deliberately, so code under test with a
+   *   best-effort `catch` cannot make the mandatory stub look optional; the
+   *   unstubbed call still fails the test.
+   *
+   * @example
+   * ```ts
+   * import { WorkspaceDiscovery, WorkspacePackage } from "@effected/workspaces";
+   * import { Effect } from "effect";
+   *
+   * const double = WorkspaceDiscovery.makeTest({
+   *   listPackages: () =>
+   *     Effect.succeed([
+   *       WorkspacePackage.make({
+   *         name: "@my-org/utils",
+   *         version: "1.0.0",
+   *         path: "/repo/packages/utils",
+   *         packageJsonPath: "/repo/packages/utils/package.json",
+   *         relativePath: "packages/utils",
+   *         workspaceRoot: "/repo",
+   *       }),
+   *     ]),
+   * });
+   * // `getPackage`, `importerMap`, `resolveFile(s)` now answer consistently.
+   * ```
+   */
+  static readonly makeTest: (overrides?: Partial<WorkspaceDiscoveryShape>) => WorkspaceDiscoveryShape;
+  /**
+   * The test layer: {@link WorkspaceDiscovery.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 { WorkspaceDiscovery } from "@effected/workspaces";
+   * import { Effect } from "effect";
+   *
+   * const TestDiscovery = WorkspaceDiscovery.layerTest({
+   *   listPackages: () => Effect.succeed([]),
+   * });
+   * // program.pipe(Effect.provide(TestDiscovery))
+   * ```
+   */
+  static readonly layerTest: (overrides?: Partial<WorkspaceDiscoveryShape>) => Layer.Layer<WorkspaceDiscovery>;
+  /**
+   * The real implementation of `@effected/npm`'s `WorkspaceResolver` contract
+   * — the one `@effected/package-json` declares but cannot fill.
+   *
+   * @remarks
+   * `versionOf` returns `Option.none()` for a name that is not a workspace
+   * member, per the contract's convention; the `DependencyResolutionError`
+   * channel is reserved for a failure of the resolution *mechanism* (an
+   * unfindable root, an unreadable manifest), never an ordinary miss.
+   *
+   * A member that declares **no `version`** is neither: it is a known member
+   * with nothing for `workspace:` to resolve to. Answering `none` would read
+   * as "not a member" downstream, so it fails typed instead, naming the
+   * specifier — the same channel a consumer already handles for an
+   * unresolvable workspace.
+   *
+   * @example
+   * ```ts
+   * import { Package } from "@effected/package-json";
+   * import { WorkspaceDiscovery } from "@effected/workspaces";
+   * import { Layer } from "effect";
+   *
+   * const resolvers = WorkspaceDiscovery.workspaceResolver.pipe(
+   *   Layer.provide(WorkspaceDiscovery.layer()),
+   * );
+   * // `Package.resolve` now resolves `workspace:*` for real.
+   * ```
+   */
+  static readonly workspaceResolver: Layer.Layer<WorkspaceResolver, never, WorkspaceDiscovery>;
+}
+//#endregion
+//#region src/PackedInstall.d.ts
+/**
+ * Where each closure package is packed from.
+ *
+ * @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
+ * 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`
+ * 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
+ * fails with `ERR_PNPM_CANNOT_RESOLVE_WORKSPACE_PROTOCOL`, which
+ * `PackedInstall.run` reports as a `PackFailed` error naming the missing
+ * install.
+ *
+ * @public
+ */
+type PackSource = "source" | {
+  readonly directory: string;
+};
+/**
+ * Options for {@link PackedInstall.run}.
+ *
+ * @public
+ */
+interface PackedInstallOptions {
+  /** The carrier: a direct dependency of each scratch consumer, beside only `consumerDependencies`. */
+  readonly carrier: string;
+  /** The other workspace packages to pack and override; `"auto"` is the carrier's transitive runtime workspace dependencies. */
+  readonly closure: ReadonlyArray<string> | "auto";
+  /**
+   * The package managers to install with; each is used only if it answers
+   * `--version`. A manager listed twice is installed once; an empty list
+   * fails `NoManagerAvailable`.
+   */
+  readonly managers: ReadonlyArray<PackageManagerName>;
+  /** `"all"` fails if any listed manager is unavailable; `"any"` (the default) needs one. */
+  readonly require?: "all" | "any" | undefined;
+  /**
+   * Where to pack from. Defaults to `{ directory: "dist/prod/npm/pkg" }`, the
+   * published artifact; see {@link PackSource} for what `"source"` costs.
+   */
+  readonly packFrom?: PackSource | undefined;
+  /** Bin names every consumer must expose, executable, in `node_modules/.bin`. */
+  readonly bins: ReadonlyArray<string>;
+  /** The environment for every spawn: pass `process.env` from the test file. The parent manager's context is stripped. */
+  readonly env: Readonly<Record<string, string | undefined>>;
+  /**
+   * Extra consumer dependencies, name to range or `file:` tarball spec.
+   *
+   * @remarks
+   * Declare here every package the consumer's own code imports directly
+   * other than the carrier. pnpm's isolated layout links only the consumer's
+   * declared dependencies at its top level, so a closure package reached only
+   * through the carrier's peers or the overrides resolves inside the carrier
+   * but fails `ERR_MODULE_NOT_FOUND` when imported from the consumer root,
+   * while npm and bun hoist it and pass. That is a property of the consumer,
+   * not of the pack.
+   *
+   * An entry naming a packed package (the carrier or a closure member) is
+   * written as that package's `file:` tarball, whatever spec you pass, so
+   * any range will do: the packed tarball always wins. npm fails an install
+   * whose direct spec differs from its override (`EOVERRIDE`), so a range
+   * written through unchanged would break every npm consumer.
+   */
+  readonly consumerDependencies?: Readonly<Record<string, string>> | undefined;
+  /** Ceiling on each install. Defaults to four minutes. Expiry fails `InstallFailed` with a message naming the manager and this duration. */
+  readonly installTimeout?: Duration.Input | undefined;
+}
+declare const PackedInstallError_base: Schema.Class<PackedInstallError, Schema.TaggedStruct<"PackedInstallError", {
+  /** What failed. */
+  readonly reason: Schema.Literals<readonly ["UnsupportedPlatform", "NoManagerAvailable", "ManagerUnavailable", "UnknownPackage", "PackSourceMissing", "PackFailed", "UnresolvedProtocol", "InstallFailed", "MissingBin", "Discovery", "Io"]>;
+  /** One line, naming the package or manager involved. */
+  readonly message: Schema.String;
+  /** The package manager involved. */
+  readonly manager: Schema.optionalKey<Schema.Literals<readonly ["npm", "pnpm", "yarn", "bun"]>>;
+  /** The workspace package involved. */
+  readonly package: Schema.optionalKey<Schema.String>;
+  /** The tail of the failing command's output. */
+  readonly output: Schema.optionalKey<Schema.String>;
+  /** The originating failure. */
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Why a packed install could not be proven.
+ *
+ * @public
+ */
+export declare class PackedInstallError extends PackedInstallError_base {}
+declare const InstalledConsumer_base: Schema.Class<InstalledConsumer, Schema.Struct<{
+  /** The package manager that installed it. */
+  readonly manager: Schema.Literals<readonly ["npm", "pnpm", "yarn", "bun"]>;
+  /** The version it reported and was pinned to. */
+  readonly managerVersion: Schema.String;
+  /** The consumer project directory (realpath'd). */
+  readonly directory: Schema.String;
+}>, {}>;
+/**
+ * One scratch project, outside the workspace, with the carrier installed.
+ *
+ * @public
+ */
+export declare class InstalledConsumer extends InstalledConsumer_base {
+  /** The installed bin `name`, in `node_modules/.bin`. POSIX: `PackedInstall` runs only there. */
+  binPath(name: string): string;
+}
+declare const PackedInstallResult_base: Schema.Class<PackedInstallResult, Schema.Struct<{
+  /** One consumer per available manager, in the order requested. */
+  readonly consumers: Schema.$Array<typeof InstalledConsumer>;
+  /** The requested managers that did not answer `--version`. */
+  readonly unavailable: Schema.$Array<Schema.Literals<readonly ["npm", "pnpm", "yarn", "bun"]>>;
+  /** Every packed package: name to absolute tarball path. */
+  readonly tarballs: Schema.$Record<Schema.String, Schema.String>;
+}>, {}>;
+/**
+ * What a packed install produced.
+ *
+ * @public
+ */
+export declare class PackedInstallResult extends PackedInstallResult_base {}
+/**
+ * Prove a carrier's bins reach a consumer that is not part of the workspace,
+ * once per available package manager.
+ *
+ * @remarks
+ * Packs the carrier and its closure into a scoped, realpath'd scratch
+ * directory (so `file:` specs and the install cwd agree on macOS). Then, for
+ * each manager that answers `--version` from that directory (so a corepack
+ * pin in the repo cannot refuse it), it writes a consumer whose only direct
+ * dependency is the carrier tarball, steers the closure to its tarballs
+ * through the manager's own override field, pins the probed version (as
+ * `packageManager`, or for pnpm as `devEngines.packageManager` with `onFail:
+ * "ignore"`, since pnpm resolves a `packageManager` pin from the registry even
+ * when it names the running version), installs with lifecycle scripts skipped,
+ * and checks every
+ * expected bin is present and executable. A packed manifest that still
+ * carries `workspace:`, `catalog:`, `link:` or a relative `file:` specifier
+ * fails `UnresolvedProtocol` before any install.
+ *
+ * It asserts nothing about what the bins DO: run them from the test through
+ * `InstalledConsumer.binPath`, for an MCP bin with `McpProbe` from
+ * `@effected/mcp/testing`, inside the same scope, because the scratch
+ * directory is removed when the scope closes. POSIX only.
+ *
+ * @example
+ * ```ts
+ * import { NodeServices } from "@effect/platform-node";
+ * import { Run } from "@effected/commands";
+ * import { Workspaces } from "@effected/workspaces";
+ * import { PackedInstall } from "@effected/workspaces/testing";
+ * import { Effect, Layer } from "effect";
+ * import { ChildProcess } from "effect/unstable/process";
+ *
+ * const Live = Workspaces.layer({ cwd: "/repo" }).pipe(Layer.provideMerge(NodeServices.layer));
+ *
+ * // Use the consumers INSIDE the scope: closing it removes the scratch
+ * // directory, so a binPath returned out of Effect.scoped points at nothing.
+ * const program = Effect.gen(function* () {
+ *   const result = yield* PackedInstall.run({
+ *     carrier: "my-tool",
+ *     closure: "auto",
+ *     managers: ["npm", "pnpm"],
+ *     bins: ["my-tool"],
+ *     env: process.env,
+ *   });
+ *   const env = PackedInstall.scrubEnv(process.env);
+ *   for (const consumer of result.consumers) {
+ *     const version = yield* Run.text(
+ *       ChildProcess.make(consumer.binPath("my-tool"), ["--version"], { env, extendEnv: false }),
+ *     );
+ *     console.log(consumer.manager, version.trim());
+ *   }
+ * }).pipe(Effect.scoped, Effect.provide(Live));
+ * ```
+ *
+ * @public
+ */
+export declare class PackedInstall {
+  private constructor();
+  /** `env` without undefined values or the parent manager's context: the environment the installs run under. Reuse it to run the installed bins. */
+  static readonly scrubEnv: (env: Readonly<Record<string, string | undefined>>) => Record<string, string>;
+  /** Pack, then install under every available manager. */
+  static readonly run: (options: PackedInstallOptions) => Effect.Effect<PackedInstallResult, PackedInstallError, import("effect/unstable/process/ChildProcessSpawner").ChildProcessSpawner | FileSystem.FileSystem | Path.Path | import("effect/Scope").Scope | WorkspaceDiscovery>;
+}
+//#endregion
+//#region src/SourceBoundary.d.ts
+/**
+ * One rule a source file must keep.
+ *
+ * @remarks
+ * `"process"` forbids a read of the global `process`. `"node:process"` forbids
+ * importing `node:process` or `process`. `"stdout-write"` forbids a
+ * `stdout.write` on anything, and a `stdout.end(chunk)`, which writes its
+ * chunk before closing; an `end()` with no chunk is spared. It matches the
+ * name `stdout`, so a renamed receiver (`const { stdout: o } = process`) is
+ * not seen: the `"process"` rule is what backstops it, so waiving `"process"`
+ * for a file waives that backstop too. `"console"` forbids any reference to the
+ * global `console`. `"console-stdout"` forbids a reference to the global
+ * `console` except a member access to one of the methods Node's console
+ * writes to stderr: `error`, `warn`, `trace` and `assert`. A bare or aliased
+ * reference (`const c = console`, `f(console)`, `console[m]`) is still
+ * flagged, since it can reach the stdout methods. Neither console rule flags
+ * core's `Console` service. `{ forbidImports }` forbids an import whose specifier
+ * equals an entry, is a subpath of one, or starts with an entry's text before a
+ * trailing `*` (so `"node:*"` and `"@effect/platform*"` are prefixes).
+ *
+ * `"node:*"` matches only the `node:` spelling: a bare built-in such as `"fs"`
+ * is not caught. To forbid both, spread Node's own list from the test file,
+ * `{ forbidImports: ["node:*", ...builtinModules] }` with `builtinModules`
+ * from `node:module`. That also forbids npm packages that share a built-in's
+ * name (`events`, `buffer`, `punycode`). No built-in list ships here: it
+ * would drift with Node releases.
+ *
+ * @public
+ */
+type BoundaryRule = "process" | "node:process" | "stdout-write" | "console" | "console-stdout" | {
+  readonly forbidImports: ReadonlyArray<string>;
+};
+/**
+ * Options for the `process` rule.
+ *
+ * @public
+ */
+interface ReferenceOptions {
+  /**
+   * Exact tokens exempt from the `process` rule, each starting at the
+   * reference (`"process.env.MY_CONSTANT"`). `process.env.__PACKAGE_VERSION__`
+   * is always exempt: the bundler substitutes it at build time.
+   */
+  readonly ignoreTokens?: ReadonlyArray<string> | undefined;
+}
+/**
+ * A snippet with the verdict one rule must reach on it.
+ *
+ * @public
+ */
+interface BoundaryFixture {
+  /** What the snippet exercises. */
+  readonly name: string;
+  /** The source text. */
+  readonly source: string;
+  /** The rule it is checked against. */
+  readonly rule: BoundaryRule;
+  /** Whether that rule must flag it. */
+  readonly flagged: boolean;
+}
+declare const Offence_base: Schema.Class<Offence, Schema.Struct<{
+  /** The file, relative to the scanned root, with `/` separators. */
+  readonly file: Schema.String;
+  /** The 1-based line. */
+  readonly line: Schema.Number;
+  /** The 1-based column, in UTF-16 code units. */
+  readonly column: Schema.Number;
+  /** The rule broken. */
+  readonly rule: Schema.Literals<readonly ["process", "node:process", "stdout-write", "console", "console-stdout", "forbidImports"]>;
+  /** What matched: the identifier, the call, or the import specifier. */
+  readonly detail: Schema.String;
+}>, {}>;
+/**
+ * One place a source file breaks a {@link BoundaryRule}.
+ *
+ * @public
+ */
+export declare class Offence extends Offence_base {
+  /** `file:line:column rule detail`, the form an assertion message reads best in. */
+  get label(): string;
+}
+/**
+ * The rule an {@link Offence} names: every string {@link BoundaryRule}, plus
+ * `"forbidImports"` for any `{ forbidImports }` rule. These are the keys of
+ * {@link ScanOptions.allowRules}.
+ *
+ * @public
+ */
+type OffenceRule = Offence["rule"];
+declare const SourceScan_base: Schema.Class<SourceScan, Schema.Struct<{
+  /** Every source file visited, relative to the root with `/` separators, sorted. Assert it is non-empty. */
+  readonly files: Schema.$Array<Schema.String>;
+  /** The visited files an `allow` glob exempted from every rule. */
+  readonly allowed: Schema.$Array<Schema.String>;
+  /** Every offence, sorted by file, then line, then column. */
+  readonly offences: Schema.$Array<typeof Offence>;
+  /**
+   * Every offence an `allowRules` glob waived, sorted like `offences`. Assert
+   * it is exactly what you meant to waive: a waiver that no longer waives
+   * anything, or waives more than intended, shows up here.
+   */
+  readonly waived: Schema.$Array<typeof Offence>;
+}>, {}>;
+/**
+ * What a scan read and found.
+ *
+ * @public
+ */
+export declare class SourceScan extends SourceScan_base {
+  /** One `file:line:column rule detail` label per offence: `[]` means clean. */
+  get violations(): ReadonlyArray<string>;
+}
+/**
+ * Options for {@link SourceBoundary.scan}.
+ *
+ * @public
+ */
+interface ScanOptions extends ReferenceOptions {
+  /** The directory to scan. */
+  readonly root: string;
+  /** The rules every non-allowed file must keep. */
+  readonly rules: ReadonlyArray<BoundaryRule>;
+  /** Globs, relative to `root` with `/` separators, naming files exempt from every rule. */
+  readonly allow?: ReadonlyArray<string> | undefined;
+  /**
+   * Globs per rule, matched like `allow`, naming files exempt from that one
+   * rule. A matching file is still checked against every other rule, and
+   * each offence a glob waives is reported in `SourceScan.waived`
+   * rather than dropped. The `"forbidImports"` key covers every
+   * `{ forbidImports }` rule. A file `allow` matches is exempt from every
+   * rule, so nothing in it is waived.
+   */
+  readonly allowRules?: { readonly [R in OffenceRule]?: ReadonlyArray<string> | undefined; } | undefined;
+  /**
+   * File extensions to scan. Defaults to `.ts`, `.mts`, `.cts`, `.js`,
+   * `.mjs` and `.cjs`; declaration files are always skipped.
+   */
+  readonly extensions?: ReadonlyArray<string> | undefined;
+}
+/**
+ * Source-text boundary checks: which files read `process`, import a forbidden
+ * module, or write to stdout or the console.
+ *
+ * @remarks
+ * Every check runs over one lexer pass that separates code from comments,
+ * strings, template text and regex bodies, so `process` in prose, in a string
+ * or in an embedded script's template text never counts, and a `/*` inside a
+ * string never hides the code behind it. A `/` after an operand divides (an
+ * identifier, `)`, `]`, a postfix `++`/`--` or a non-null `!`), while one after
+ * an operator, a keyword or the `)` of an `if`/`while`/`for`/`with` condition
+ * opens a regex. An object-literal key or type member named `process`
+ * (`{ process: 1 }`) is not a read.
+ *
+ * It is a lexer, not a type checker, and these misses are known:
+ *
+ * - there is no scope analysis, so ANY local binding named `process` or
+ *   `console` is flagged like the global: a parameter
+ *   (`(process: Handle) => process.kill()`), a variable, a label, or an
+ *   unannotated class field (`process = 1`). An annotated class field
+ *   (`process: T`) reads as a type member and is spared. Prefer renaming the
+ *   binding; otherwise waive that one rule for the file with an
+ *   `allowRules` glob, which leaves every other rule in force and reports
+ *   what it waived. An `allow` glob exempts the file from every rule;
+ *
+ * - a computed access through a string key (`globalThis["process"]`) and a
+ *   destructuring of a global (`const { process: p } = globalThis`) are not seen;
+ *
+ * - a regex literal directly after a block-closing `}` reads as a division, so
+ *   a quote or `/*` inside it can hide the code after it;
+ *
+ * - JSX text reads as code;
+ *
+ * - `forbidImports: ["node:*"]` does not catch a bare built-in such as
+ *   `"fs"` (see {@link BoundaryRule}).
+ *
+ * Assert on {@link SourceBoundary.verifyFixtures} beside your own scan: it
+ * proves the scanner you are trusting still flags what it must and spares
+ * what it must.
+ *
+ * @example
+ * ```ts
+ * import { SourceBoundary } from "@effected/workspaces/testing";
+ *
+ * const offences = SourceBoundary.check("src/a.ts", "const { env } = process;", ["process"]);
+ * const clean = SourceBoundary.verifyFixtures().length === 0;
+ * console.log(offences.map((offence) => offence.label), clean);
+ * // => [ 'src/a.ts:1:17 process process' ] true
+ * ```
+ *
+ * @public
+ */
+export declare class SourceBoundary {
+  private constructor();
+  /** `text` with every comment blanked to spaces; strings, templates and regexes untouched, length and line breaks kept. */
+  static readonly stripComments: (text: string) => string;
+  /** Whether `text` reads the global `process` in code (see {@link BoundaryRule}). */
+  static readonly referencesProcess: (text: string, options?: ReferenceOptions) => boolean;
+  /** Every module specifier `text` imports: static, side-effect, re-export, type-only, `import(...)` with a literal, and `require(...)`. */
+  static readonly importSpecifiers: (text: string) => ReadonlyArray<string>;
+  /** Whether `text` imports the Node built-in `module`, in either its `node:` or bare form. */
+  static readonly importsNode: (text: string, module: string) => boolean;
+  /** Every place `text` breaks one of `rules`, in source order, attributed to `file`. */
+  static readonly check: (file: string, text: string, rules: ReadonlyArray<BoundaryRule>, options?: ReferenceOptions) => ReadonlyArray<Offence>;
+  /**
+   * Check every source file under `root` against `rules`.
+   *
+   * @remarks
+   * Walks with an explicit stack, visiting each real directory once (via
+   * `realPath`), so a symlink loop terminates and a linked directory is not
+   * scanned twice. `node_modules` is never entered. Paths come back relative
+   * and `/`-separated whatever the platform's separator, and that is also
+   * what `allow` globs match against. A missing root fails; it never scans
+   * nothing. A dangling symlink under the root is skipped, having nothing to
+   * scan; any other entry that cannot be read fails the scan.
+   *
+   * @example
+   * ```ts
+   * import { NodeServices } from "@effect/platform-node";
+   * import { SourceBoundary } from "@effected/workspaces/testing";
+   * import { Effect } from "effect";
+   *
+   * const scan = SourceBoundary.scan({
+   *   root: "/repo/packages/engine/src",
+   *   rules: ["process", "node:process", { forbidImports: ["node:*", "@effect/platform*"] }],
+   * }).pipe(Effect.provide(NodeServices.layer));
+   * ```
+   */
+  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. */
+  static readonly verifyFixtures: () => ReadonlyArray<string>;
+}
+//#endregion
+//#region src/WorkspaceLayering.d.ts
+declare const LayerEdge_base: Schema.Class<LayerEdge, Schema.Struct<{
+  /** The dependent package. */
+  readonly from: Schema.String;
+  /** The package depended on. */
+  readonly to: Schema.String;
+  /** The manifest map that declares it. */
+  readonly field: Schema.Literals<readonly ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"]>;
+}>, {}>;
+/**
+ * One dependency edge between two workspace packages, in one field.
+ *
+ * @public
+ */
+export declare class LayerEdge extends LayerEdge_base {
+  /** `from -> to (field)`. */
+  get label(): string;
+}
+/**
+ * The input to {@link WorkspaceLayering.check}: package names, and per-field edges between them.
+ *
+ * @public
+ */
+interface LayeringGraph {
+  /** Every workspace package name, the root included. */
+  readonly names: ReadonlyArray<string>;
+  /** One edge per declaring field. */
+  readonly edges: ReadonlyArray<LayerEdge>;
+}
+declare const LayeringReport_base: Schema.Class<LayeringReport, Schema.Struct<{
+  /** Packages the policy declares more than once, or declares and also matches with an unconstrained glob. */
+  readonly duplicates: Schema.$Array<Schema.String>;
+  /** Workspace packages the policy does not classify. */
+  readonly unclassified: Schema.$Array<Schema.String>;
+  /** Edges that break the policy, each with why. */
+  readonly offenders: Schema.$Array<Schema.Struct<{
+    readonly edge: typeof LayerEdge;
+    readonly reason: Schema.Literals<readonly ["upward", "sameLayer", "toolingReachesLayer", "intoUnconstrained", "intoUnclassified"]>;
+  }>>;
+  /** The members of every dependency cycle in the checked fields, or none. */
+  readonly cycle: Schema.Option<Schema.$Array<Schema.String>>;
+  /** Packages the policy names that the workspace does not contain. */
+  readonly missingDeclared: Schema.$Array<Schema.String>;
+  /** Required edges absent from the checked fields. */
+  readonly missingRequiredEdges: Schema.$Array<Schema.String>;
+  /** Edges in the checked fields; `0` is itself a violation. */
+  readonly edgeCount: Schema.Number;
+}>, {}>;
+/**
+ * What a layering check found.
+ *
+ * @public
+ */
+export declare class LayeringReport extends LayeringReport_base {
+  /** One line per violation: `[]` means the graph honours the policy and the check was not vacuous. */
+  get violations(): ReadonlyArray<string>;
+}
+/**
+ * Holds a workspace's package graph to a committed {@link LayerPolicy}.
+ *
+ * @remarks
+ * `check` is pure, so positive-control fixture graphs need no filesystem.
+ * `edgesOf` recomputes one edge per declaring field, because
+ * `DependencyGraph` merges the four fields into one adjacency and a policy
+ * may check only some of them. An edge exists wherever a dependency NAME is
+ * a workspace package, whatever its specifier protocol.
+ *
+ * @example
+ * ```ts
+ * import { NodeServices } from "@effect/platform-node";
+ * import { Workspaces } from "@effected/workspaces";
+ * import { LayerPolicy, WorkspaceLayering } from "@effected/workspaces/testing";
+ * import { Effect, Layer } from "effect";
+ *
+ * const Live = Workspaces.layer({ cwd: "/repo" }).pipe(Layer.provideMerge(NodeServices.layer));
+ *
+ * const violations = Effect.gen(function* () {
+ *   const policy = yield* LayerPolicy.load("/repo/layers.json");
+ *   const report = yield* WorkspaceLayering.checkWorkspace(policy);
+ *   return report.violations;
+ * }).pipe(Effect.provide(Live));
+ * ```
+ *
+ * @public
+ */
+export declare class WorkspaceLayering {
+  private constructor();
+  /** Check `graph` against `policy`, reading only the policy's fields. Pure. */
+  static readonly check: (graph: LayeringGraph, policy: LayerPolicy) => LayeringReport;
+  /** One edge per declaring field between workspace packages; self-edges dropped. */
+  static readonly edgesOf: (packages: ReadonlyArray<WorkspacePackage>) => ReadonlyArray<LayerEdge>;
+  /** Discover the workspace and check it against `policy`. */
+  static readonly checkWorkspace: (policy: LayerPolicy) => Effect.Effect<LayeringReport, WorkspaceDiscoveryFailure, WorkspaceDiscovery>;
+}
+//#endregion
+export type { BoundaryFixture, BoundaryRule, DependencyDiff, FindWorkspaceRootOptions, LayeringGraph, OffenceRule, PackSource, PackedInstallOptions, ReferenceOptions, ScanOptions, WorkspaceDiscoveryFailure, WorkspaceDiscoveryOptions, WorkspaceDiscoveryShape, WorkspaceLookupFailure, WorkspaceRootShape };
+//# sourceMappingURL=testing.d.ts.map