@effected/workspaces 0.32.1 → 0.33.0

package/internal/sourceWalk.js

@@ -0,0 +1,58 @@
+import { Effect, FileSystem, Option, Path } from "effect";
+
+//#region src/internal/sourceWalk.ts
+/** The file extensions a walk reads when the caller names none. */
+const DEFAULT_EXTENSIONS = [
+	".ts",
+	".mts",
+	".cts",
+	".js",
+	".mjs",
+	".cjs"
+];
+/** Declaration files: always skipped, whatever extensions the caller names. */
+const DECLARATION = /\.d\.[cm]?ts$/;
+/**
+* Every source file under `root`, in walk order.
+*
+* @remarks
+* Walks with an explicit stack, visiting each real directory once (via
+* `realPath`), so a symlink loop terminates and a linked directory is not
+* read twice. `node_modules` is never entered. A missing root fails; it never
+* walks nothing. A dangling symlink under the root is skipped, having nothing
+* to read; any other entry that cannot be read fails the walk.
+*/
+const walkSources = Effect.fn("walkSources")(function* (options) {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const posix = (relative) => relative.split(path.sep).join("/");
+	const found = [];
+	const visited = /* @__PURE__ */ new Set();
+	const pending = [options.root];
+	while (pending.length > 0) {
+		const directory = pending.pop();
+		if (directory === void 0) break;
+		const real = yield* fs.realPath(directory);
+		if (visited.has(real)) continue;
+		visited.add(real);
+		for (const name of yield* fs.readDirectory(directory)) {
+			const full = path.join(directory, name);
+			const entry = yield* fs.stat(full).pipe(Effect.map(Option.some), Effect.catch((error) => error.reason._tag === "NotFound" ? fs.readLink(full).pipe(Effect.as(Option.none()), Effect.mapError(() => error)) : Effect.fail(error)));
+			if (Option.isNone(entry)) continue;
+			const info = entry.value;
+			if (info.type === "Directory") {
+				if (name !== "node_modules") pending.push(full);
+				continue;
+			}
+			if (info.type !== "File" || DECLARATION.test(name) || !options.extensions.some((extension) => name.endsWith(extension))) continue;
+			found.push({
+				file: posix(path.relative(options.root, full)),
+				path: full
+			});
+		}
+	}
+	return found;
+});
+
+//#endregion
+export { DECLARATION, DEFAULT_EXTENSIONS, walkSources };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/workspaces",
-	"version": "0.32.1",
+	"version": "0.33.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.11.1",
-		"@effected/git": "^0.20.1",
-		"@effected/glob": "^0.10.1",
-		"@effected/jsonc": "^0.15.2",
-		"@effected/lockfiles": "^0.15.1",
-		"@effected/npm": "^0.20.1",
-		"@effected/package-json": "^0.20.2",
-		"@effected/semver": "^0.11.1",
-		"@effected/walker": "^0.15.1",
-		"@effected/yaml": "^0.19.2",
+		"@effected/commands": "^0.12.0",
+		"@effected/git": "^0.21.0",
+		"@effected/glob": "^0.11.0",
+		"@effected/jsonc": "^0.16.0",
+		"@effected/lockfiles": "^0.16.0",
+		"@effected/npm": "^0.21.0",
+		"@effected/package-json": "^0.21.0",
+		"@effected/semver": "^0.12.0",
+		"@effected/walker": "^0.16.0",
+		"@effected/yaml": "^0.20.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.2"
+		"effect": "^4.0.0"
 	},
 	"engines": {
 		"node": ">=24.11.0"

package/testing.d.ts

@@ -5,92 +5,6 @@ import { WorkspaceManifest } from "@effected/lockfiles";
 import { Package } from "@effected/package-json";
 import { CommandOutput } from "@effected/commands";
 import { ChildProcess, ChildProcessSpawner } from "effect/process";
-//#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 a `harness` block, 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`. */
@@ -328,20 +242,6 @@ export declare class WorkspacePackage extends WorkspacePackage_base {
   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`.
@@ -888,6 +788,419 @@ export declare class WorkspaceDiscovery extends WorkspaceDiscovery_base {
   static readonly workspaceResolver: Layer.Layer<WorkspaceResolver, never, WorkspaceDiscovery>;
 }
 //#endregion
+//#region src/ImportGraph.d.ts
+declare const NoEntriesError_base: Schema.Class<NoEntriesError, Schema.TaggedStruct<"NoEntriesError", {
+  /** The root the walk would have reported against. */
+  readonly root: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * The entries list named no file to start from, so a walk would prove nothing.
+ *
+ * @public
+ */
+export declare class NoEntriesError extends NoEntriesError_base {
+  /** Renders the root into a one-line message. */
+  get message(): string;
+}
+declare const EntryNotFoundError_base: Schema.Class<EntryNotFoundError, Schema.TaggedStruct<"EntryNotFoundError", {
+  /** The entry, verbatim. */
+  readonly entry: Schema.String;
+  /** The root it was resolved against. */
+  readonly root: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * An entry named a file no resolution candidate could find. The walk fails
+ * rather than starting from nothing: a typo'd entry must never read as clean.
+ *
+ * @public
+ */
+export declare class EntryNotFoundError extends EntryNotFoundError_base {
+  /** Renders the entry and root into a one-line message. */
+  get message(): string;
+}
+declare const UnresolvedImport_base: Schema.Class<UnresolvedImport, Schema.Struct<{
+  /** The importing file, relative to the root, with `/` separators. */
+  readonly file: Schema.String;
+  /** The specifier, verbatim. */
+  readonly specifier: Schema.String;
+}>, {}>;
+/**
+ * One relative import no file candidate resolved: a link of the graph the
+ * walk could not follow, so whatever it would have reached is unproven.
+ *
+ * @public
+ */
+export declare class UnresolvedImport extends UnresolvedImport_base {
+  /** `file specifier`, the form an assertion message reads best in. */
+  get label(): string;
+}
+declare const ReachOffence_base: Schema.Class<ReachOffence, Schema.Struct<{
+  /** The importing file, relative to the 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 forbidden specifier, verbatim. */
+  readonly specifier: Schema.String;
+  /**
+   * The files the walk took from an entry to `file`, entry first and `file`
+   * last, each relative to the root with `/` separators. Breadth-first, so
+   * this is a shortest chain; it is the chain the walk first reached `file`
+   * by, and a file is visited once whatever else reaches it.
+   */
+  readonly chain: Schema.$Array<Schema.String>;
+}>, {}>;
+/**
+ * One forbidden import a walk from the entries reached.
+ *
+ * @public
+ */
+export declare class ReachOffence extends ReachOffence_base {
+  /** `file:line:column specifier via chain`, the form an assertion message reads best in. */
+  get label(): string;
+}
+declare const ReachabilityScan_base: Schema.Class<ReachabilityScan, Schema.Struct<{
+  /**
+   * Every file the walk reached, entries included, relative to the root with
+   * `/` separators, sorted. Assert it is non-empty: a walk that reached
+   * nothing proves nothing.
+   */
+  readonly files: Schema.$Array<Schema.String>;
+  /**
+   * Every relative specifier no file candidate resolved, one per
+   * file-and-specifier pair, sorted by file then specifier. Assert it is
+   * empty, or exactly the generated files you expect: an unresolved link is
+   * a part of the graph the walk could not prove anything about.
+   */
+  readonly unresolved: Schema.$Array<typeof UnresolvedImport>;
+  /** Every forbidden import the walk reached, sorted by file, then line, then column. */
+  readonly offences: Schema.$Array<typeof ReachOffence>;
+}>, {}>;
+/**
+ * What a reachability walk read and found.
+ *
+ * @public
+ */
+export declare class ReachabilityScan extends ReachabilityScan_base {
+  /** One `file:line:column specifier via chain` label per offence: `[]` means the entries reach nothing forbidden. */
+  get violations(): ReadonlyArray<string>;
+}
+/**
+ * Options for {@link ImportGraph.reachability}.
+ *
+ * @public
+ */
+interface ReachabilityOptions {
+  /** The directory every entry and reported path is relative to. */
+  readonly root: string;
+  /**
+   * The files the walk starts from, relative to `root` with `/` separators,
+   * or absolute. Each resolves like a relative import (see `extensions`);
+   * one that resolves to no file fails `EntryNotFoundError`, and an empty
+   * list fails `NoEntriesError` — the walk never proves nothing silently.
+   */
+  readonly entries: ReadonlyArray<string>;
+  /**
+   * Specifiers no reached file may import, matched like a `SourceBoundary`
+   * `forbidImports` entry: equal to the specifier, a subpath of it, or its
+   * text before a trailing `*`.
+   */
+  readonly forbid: ReadonlyArray<string>;
+  /**
+   * File extensions a relative specifier resolves through: `./a.js` also
+   * tries `./a` with each extension, and `./a/index` with each. Defaults to
+   * `.ts`, `.mts`, `.cts`, `.js`, `.mjs` and `.cjs`; declaration files are
+   * never a candidate.
+   */
+  readonly extensions?: ReadonlyArray<string> | undefined;
+  /**
+   * The workspace-package extension point: called with every bare specifier
+   * a reached file imports, answering the file to continue the walk from
+   * (relative to `root` with `/` separators, or absolute, resolved like an
+   * entry), or `undefined` to stop at the specifier. A path that resolves to
+   * no file is reported in `unresolved` under the specifier it was reached
+   * by. The default stops at every bare specifier: the walk follows relative
+   * imports only.
+   */
+  readonly followPackage?: ((specifier: string) => string | undefined) | undefined;
+}
+declare const UndeclaredImport_base: Schema.Class<UndeclaredImport, Schema.Struct<{
+  /** The name of the package that owns the importing file. */
+  readonly package: Schema.String;
+  /** The importing file, relative to its package, 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 specifier, verbatim. */
+  readonly specifier: Schema.String;
+  /** The package name the specifier names: `effect` for `effect/Schema`. */
+  readonly dependency: Schema.String;
+}>, {}>;
+/**
+ * One runtime import the owning package's manifest does not declare.
+ *
+ * @public
+ */
+export declare class UndeclaredImport extends UndeclaredImport_base {
+  /** `package file:line:column undeclared dependency`, the form an assertion message reads best in. */
+  get label(): string;
+}
+declare const UndeclaredScan_base: Schema.Class<UndeclaredScan, Schema.Struct<{
+  /** Every package whose manifest the check read, sorted by name. Assert it is non-empty. */
+  readonly packages: Schema.$Array<Schema.String>;
+  /**
+   * Every file the check read, relative to the workspace root with `/`
+   * separators, sorted. Each file appears once, listed under its innermost
+   * package even when a wider package's glob also walked it. Assert it is
+   * non-empty: a check that read no file proves nothing, and a mistyped
+   * `include` shows up here.
+   */
+  readonly files: Schema.$Array<Schema.String>;
+  /** Every undeclared runtime import, sorted by package, then file, then line, then column. */
+  readonly undeclared: Schema.$Array<typeof UndeclaredImport>;
+}>, {}>;
+/**
+ * What an undeclared-import check read and found.
+ *
+ * @public
+ */
+export declare class UndeclaredScan extends UndeclaredScan_base {
+  /** One `package file:line:column undeclared dependency` label per import: `[]` means every runtime import is declared. */
+  get violations(): ReadonlyArray<string>;
+}
+/**
+ * Options for {@link ImportGraph.undeclared}.
+ *
+ * @public
+ */
+interface UndeclaredOptions {
+  /**
+   * Bare Node built-ins (`"fs"`, `"child_process"`), never flagged. A
+   * `node:`-prefixed specifier is always a built-in; no bare list ships
+   * here, because one would drift with Node releases — spread
+   * `builtinModules` from `node:module` in your test file. A bare built-in
+   * not on this list is flagged like any undeclared package.
+   */
+  readonly builtins?: ReadonlyArray<string> | undefined;
+  /**
+   * Globs, matched against each package-relative path with `/` separators,
+   * naming the runtime source files to read. Defaults to `["src/**"]`: the
+   * check compares against `dependencies`, `peerDependencies` and
+   * `optionalDependencies`, so test files importing devDependencies are out
+   * of scope by design. Each glob is walked from its static prefix (the text
+   * before its first pattern character), so the default walks `src/` and
+   * never `dist/` or `node_modules`; a glob with no static prefix walks the
+   * package directory. A file under a nested workspace package belongs to
+   * that innermost package alone: a root glob starting with `**` walks the
+   * whole repository but checks each nested file only against its own
+   * package's manifest.
+   */
+  readonly include?: ReadonlyArray<string> | undefined;
+  /**
+   * File extensions to read. Defaults to `.ts`, `.mts`, `.cts`, `.js`,
+   * `.mjs` and `.cjs`; declaration files are always skipped.
+   */
+  readonly extensions?: ReadonlyArray<string> | undefined;
+}
+/**
+ * Import-graph checks: properties of what the imports of a set of files
+ * reach, which no one-file rule can express.
+ *
+ * @remarks
+ * {@link SourceBoundary} checks one file at a time. Two guards consumers want
+ * are properties of the import graph itself:
+ *
+ * - {@link ImportGraph.reachability} answers "nothing reachable from entry X
+ *   imports Y". A directory rule approximates that, but a refactor which adds
+ *   a new static path from the root entry into an allowed directory still
+ *   passes it; a reachability walk follows the real import edges and reports
+ *   the chain that reaches the forbidden specifier.
+ * - {@link ImportGraph.undeclared} answers "every runtime import is
+ *   declared". Workspace hoisting resolves an import of a package the
+ *   manifest never declared, and only a packed install catches that today —
+ *   far too slow for the edit loop. This check is static and fast: each
+ *   package's literal specifiers against its own `dependencies`,
+ *   `peerDependencies` and `optionalDependencies`.
+ *
+ * Both are static analysis of literal specifiers: static imports,
+ * re-exports, and `import()`/`require()` calls whose argument is one string
+ * literal. There is no dynamic-import guarantee: a computed specifier
+ * (`import("./ui/" + name)`) is invisible to both, and a packed install
+ * (`PackedInstall`) remains the proof of what actually resolves at
+ * runtime. Both reuse the `SourceBoundary` lexer, so a specifier in a
+ * comment, a string, template text or a regex body is never an import, and
+ * both refuse to pass vacuously: every result reports what it read.
+ *
+ * @example
+ * ```ts
+ * import { NodeServices } from "@effect/platform-node";
+ * import { ImportGraph } from "@effected/workspaces/testing";
+ * import { Effect } from "effect";
+ *
+ * // Nothing reachable from the root entry may import ink or react.
+ * const walk = ImportGraph.reachability({
+ *   root: "/repo/packages/ui/src",
+ *   entries: ["index.ts"],
+ *   forbid: ["ink", "react"],
+ * }).pipe(Effect.provide(NodeServices.layer));
+ * ```
+ *
+ * @public
+ */
+export declare class ImportGraph {
+  private constructor();
+  /**
+   * Walk the import graph from `entries` through relative imports and report
+   * every forbidden specifier a reached file imports.
+   *
+   * @remarks
+   * The walk is breadth-first, so a violation's chain is a shortest path
+   * from an entry, and each file is visited once through its `realPath`, so
+   * a symlink loop terminates and a diamond reports one chain. The walk is
+   * conservative: it follows every literal specifier, type-only imports
+   * included, so a forbidden import only a type reaches is still reported.
+   * A bare specifier is checked against `forbid` — the same matcher
+   * `SourceBoundary.check` uses — but only walked into when `followPackage`
+   * names a file for it. A relative specifier that resolves to no file is
+   * reported in `unresolved`, never dropped: the part of the graph behind it
+   * is unproven.
+   */
+  static readonly reachability: (options: ReachabilityOptions) => Effect.Effect<ReachabilityScan, EntryNotFoundError | NoEntriesError | import("effect/PlatformError").PlatformError, FileSystem.FileSystem | Path.Path>;
+  /**
+   * Check every workspace package's runtime sources for imports its own
+   * manifest does not declare.
+   *
+   * @remarks
+   * For each discovered package, reads the files its `include` globs name
+   * (`src/**` by default) and compares every runtime specifier against the
+   * package's `dependencies`, `peerDependencies` and `optionalDependencies`.
+   * `devDependencies` never declares: an import of one from a runtime source
+   * is exactly the hoisting bug this check exists for. `optionalDependencies`
+   * does declare: npm and pnpm install one by default, so a packed install
+   * resolves the import. A relative,
+   * absolute, `#`-subpath or URL-scheme specifier is never a package import;
+   * a `node:` specifier is always a built-in, and a bare built-in is one only
+   * when `builtins` lists it. A package importing its own name (a
+   * self-reference through `exports`) is declared by definition. A file
+   * under two discovered packages (a nested package under the root) is
+   * checked against its innermost package's manifest only, so a root-wide
+   * `include` never double-reports it. Type-only imports are erased by the
+   * compiler and never flagged: `import type { X } from`, `export type`
+   * re-exports, and an `import()` in a type position (`typeof import("x")`,
+   * an annotation, a type alias right-hand side, a generic argument). The
+   * position is judged by the construct enclosing the call, not by the one
+   * token before it, so a runtime `import("x")` in a typed initializer, an
+   * object literal, a ternary branch or a call argument counts like any
+   * static import. One `import type from "x"` is runtime too — TypeScript
+   * reads it as a default import of a binding named `type`. What the static
+   * pass cannot see — a computed specifier — only `PackedInstall` proves.
+   */
+  static readonly undeclared: (options?: UndeclaredOptions | undefined) => Effect.Effect<UndeclaredScan, import("@effected/glob").GlobPatternError | import("effect/PlatformError").PlatformError | WorkspaceDiscoveryFailure, FileSystem.FileSystem | Path.Path | WorkspaceDiscovery>;
+}
+//#endregion
+//#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 a `harness` block, 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/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/PackedInstall.d.ts
 /**
  * Where each closure package is packed from.
@@ -1870,9 +2183,10 @@ export declare class SourceBoundary {
    * Check every source file under `root` against `rules`.
    *
    * @remarks
-   * Walks with an explicit stack, visiting each real directory once (via
+   * Walks with the shared source walker (`internal/sourceWalk.ts`, which the
+   * `ImportGraph` checks also use): each real directory is visited 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
+   * scanned twice, and `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
@@ -1890,7 +2204,7 @@ export declare class SourceBoundary {
    * }).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>;
+  static readonly scan: (options: ScanOptions) => Effect.Effect<SourceScan, import("@effected/glob").GlobPatternError | import("effect/PlatformError").PlatformError, FileSystem.FileSystem | import("effect/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 gets wrong; `[]` means it still flags and spares what it must. */
@@ -1992,5 +2306,5 @@ export declare class WorkspaceLayering {
   static readonly checkWorkspace: (policy: LayerPolicy) => Effect.Effect<LayeringReport, WorkspaceDiscoveryFailure, WorkspaceDiscovery>;
 }
 //#endregion
-export type { BinCommandOptions, BinProvenance, BoundaryFixture, BoundaryRule, DependencyDiff, FindWorkspaceRootOptions, LayeringGraph, OffenceRule, PackSource, PackedInstallBudget, PackedInstallClosureOptions, PackedInstallGate, PackedInstallOptions, PackedInstallPreflight, PackedInstallPreflightOptions, ReferenceOptions, RunBinOptions, ScanOptions, WorkspaceDiscoveryFailure, WorkspaceDiscoveryOptions, WorkspaceDiscoveryShape, WorkspaceLookupFailure, WorkspaceRootShape };
+export type { BinCommandOptions, BinProvenance, BoundaryFixture, BoundaryRule, DependencyDiff, FindWorkspaceRootOptions, LayeringGraph, OffenceRule, PackSource, PackedInstallBudget, PackedInstallClosureOptions, PackedInstallGate, PackedInstallOptions, PackedInstallPreflight, PackedInstallPreflightOptions, ReachabilityOptions, ReferenceOptions, RunBinOptions, ScanOptions, UndeclaredOptions, WorkspaceDiscoveryFailure, WorkspaceDiscoveryOptions, WorkspaceDiscoveryShape, WorkspaceLookupFailure, WorkspaceRootShape };
 //# sourceMappingURL=testing.d.ts.map