--- type: Interface title: "@effected/workspaces discovery and detection" description: "Root finding, the packages: enumerator, the WorkspacePackage located-member model, and package-manager detection." status: stable kind: api resource: ../../packages/workspaces/src/WorkspaceDiscovery.ts tags: - architecture sources: - id: workspace-discovery-ts resource: ../../packages/workspaces/src/WorkspaceDiscovery.ts - id: workspace-package-ts resource: ../../packages/workspaces/src/WorkspacePackage.ts - id: workspace-root-ts resource: ../../packages/workspaces/src/WorkspaceRoot.ts - id: workspace-marker-ts resource: ../../packages/workspaces/src/WorkspaceMarker.ts - id: package-manager-name-ts resource: ../../packages/workspaces/src/PackageManagerName.ts - id: enumerate-ts resource: ../../packages/workspaces/src/internal/enumerate.ts - id: traverse-ts resource: ../../packages/workspaces/src/internal/traverse.ts - id: workspaces-ts resource: ../../packages/workspaces/src/Workspaces.ts - id: layer-root-ts resource: ../../packages/workspaces/src/internal/layerRoot.ts - id: workspaces-sync-ts resource: ../../packages/workspaces/src/WorkspacesSync.ts - id: package-manager-decision-ts resource: ../../packages/workspaces/src/internal/packageManagerDecision.ts generated: by: "okfit/claude-code" at: 2026-11-13T06:27:13Z verified: - by: human:spencer at: 2026-09-24T00:11:49.503Z - by: human:spencer at: 2026-10-13T21:42:59Z - by: human:spencer at: 2026-10-29T00:43:21Z - by: human:spencer at: 2026-11-06T01:54:11Z - by: human:spencer at: 2026-11-10T23:42:17Z - by: human:spencer at: 2026-11-16T16:59:20Z integrity: generated: body: 8370245e358fbaa1 verified: by: human:spencer at: 2026-11-16T16:59:20Z content: 5ea9a24d749828b0 --- # @effected/workspaces discovery and detection Discovery is the half of [`@effected/workspaces`](../modules/workspaces.md) that answers where the workspace is, what is in it, and which package manager runs it. The services live in `WorkspaceRoot`,[^workspace-root-ts] `WorkspaceDiscovery`,[^workspace-discovery-ts] and `PackageManagerName`, each with its layer in the same module; the located-member model is `WorkspacePackage`. ## The packages: enumerator `internal/enumerate.ts` compiles the `packages:` list once, with no options surface to diverge on, and enumerates the workspace.[^enumerate-ts] Literal entries fast-path to an exact manifest existence check. Wildcards read from the compiled enumeration prefix: a single-level read when the pattern cannot cross segments, and a bounded iterative descent from that prefix when it can, testing each visited directory's root-relative POSIX path against the pattern. The set it walks and the test each candidate must pass come from one membership (`internal/membership.ts`): on an npm root, npm's own `NpmWorkspacePatterns` predicate over the field's normalized positives; elsewhere, one `GlobSet`, whose excludes drop candidates after positive matching. A directory counts as a workspace package only if it holds a manifest. The npm rules and their six measured differences are in [the module](../modules/workspaces.md#npm-roots-npms-rules-not-globset-semantics). The descent is a worklist, not a recursion, so it cannot overflow the stack. It is bounded three ways: an integer-guarded depth cap (so `NaN` and fractional caps fail as a defect rather than silently enumerating nothing), a visited-directory budget, and unconditional pruning of `node_modules` and `.git`. A wildcard whose prefix names a nonexistent directory fails typed. This exists to fix a real degradation: a trailing globstar could silently collapse to a single-level wildcard, leaving a nested package undiscovered with no diagnostic. ### One traversal, two entry points `internal/traverse.ts` owns the worklist, the dequeue discipline (a head index, never `Array.shift()`, since `shift()` re-indexes the array on every dequeue and makes draining a near-budget worklist quadratic), the depth rule, the visit budget, and the prune list.[^traverse-ts] Both the Effect enumerator and the [sync escape hatch](../modules/workspaces.md#workspacessync--the-escape-hatch) drive this one state machine, and neither re-decides any of it. The depth cap bounds what is enumerated, not merely what is descended into. The one deliberate divergence between the two entry points is what happens at a bound: the Effect path fails typed, and the sync path truncates because it has no error channel. ## WorkspacePackage A `Schema.Class` carrying a located workspace member.[^workspace-package-ts] It keeps a tolerant manifest projection rather than embedding `@effected/package-json`'s strict `Package` model, because that model requires a valid name and a parseable semver version — one member with a non-semver version would otherwise fail discovery for the whole repository. The as-read manifest record is captured at discovery, so a consumer needing a field outside the typed slice reads it without a second file read or a strict decode that can fail on odd manifests; a re-reading manifest method stays available separately, because its point-in-time refresh semantics depend on re-reading a captured record cannot provide. `version` is optional, carried exactly as the manifest has it. A private monorepo root without a `version` field is the ordinary pnpm shape, and pnpm itself accepts a version-less private member anywhere in the tree, so the former `missingVersion` discriminant is gone: `WorkspaceDiscoveryError.kind` carries only `read`, `invalidJson`, `invalidShape`, `invalidYaml`, and `missingName`. Absence stays absence (no `"0.0.0"` placeholder, no present-but-`undefined` key), a string rides through verbatim, and a `version` that is present but not a string — or present but empty — is `invalidShape`, because an empty string was never a legitimate pnpm shape and would otherwise reach a `workspace:` resolution as a bare `^`. A root-only exemption was rejected because the class type cannot narrow per member: the public type would have become optional anyway while the runtime stayed needlessly strict. `WorkspaceResolver.versionOf` answers the two questions discovery keeps apart: `Option.none()` for a name that is not a workspace member at all, and a typed `DependencyResolutionError` with `reason: "no-version"` and no `cause` for a member that is one but declares no `version` — because the `workspace:` contract reserves `none` for "not a member", and answering it for a version-less member would read downstream as exactly that. `workspaceRoot` is a required carried field, not a derived getter. Discovery resolved the root before enumerating and the sync facade is handed it, so dropping it was pure information loss that consumers repaired by counting `relativePath` segments and re-ascending. The asymmetry with `manifestRecord`, which defaults to `{}`, is deliberate: `{}` is an honest "no record", but there is no honest default root, and a placeholder would hand back a wrong absolute path that a consumer then resolves configuration against. A `WorkspacePackage` serialized before the field existed therefore fails decode, which is the conservative direction because re-running discovery is cheap.[^workspace-package-ts] `getWorkspacePackagesSync`, the sync facade, has no error channel; its totality pairs with an `onSkip` diagnostic (`WorkspaceDiscoverySkip`, whose `kind` is the `WorkspaceDiscoveryError` vocabulary minus `invalidYaml`, which describes the `pnpm-workspace.yaml` read rather than a manifest) so a skip is never silent. Two inputs throw instead, because each loses every pattern at once and an empty or fallback answer would read as "no packages": a pattern source that exists but cannot be read or parsed (`pnpm-workspace.yaml`, or the root `package.json` in its absence) throws the `WorkspaceDiscoveryError` (kind `read`, `invalidYaml` or `invalidJson`), and a `packages:` set that does not compile as one `GlobSet`, or an npm root's field past an `NpmWorkspacePatterns` ceiling, throws the `WorkspacePatternError` (kind `uncompilable`) — each the error `WorkspaceDiscovery` fails with on that root (#1292). ## Root finding and discovery Root finding runs over `@effected/walker`'s upward ascent, inheriting per-probe error absorption. Markers are checked in priority order: the pnpm workspace file, then a manifest with a `workspaces` field. The ascent is bounded on request: `find(cwd, { stopAt, maxDepth })` passes both straight through to `Walker.ascend`, which already owned the two concepts. `stopAt` is inclusive — the ceiling itself is probed — and is resolved to an absolute path before the walk, because the walker compares it to each ancestor by string equality and an unresolved ceiling would never match, silently degrading to the unbounded ascent the option exists to prevent. An unmarked ceiling fails typed with `stopAt` recorded on `WorkspaceRootNotFoundError`, which is what distinguishes "no root anywhere above me" from "none below my ceiling".[^workspace-root-ts] The sync facade's `findWorkspaceRootSync` takes the same `stopAt` (inclusive, resolved through the consumer's `SyncPath.resolve` at lookup time, a non-ancestor never matching); being total, it answers `null` where the Effect surface fails typed.[^workspaces-sync-ts] It takes no `maxDepth`: its ascent is bounded only by the `dirname` fixpoint and an internal cap. Both surfaces take a `markers` filter (`WorkspaceMarker`, the two marker filenames as a literal schema). The markers keep their fixed priority whatever order a caller lists them in, and an empty list is a wiring defect (a die on the Effect surface, a throw on the sync one). A pnpm-only tool passes `["pnpm-workspace.yaml"]`, because pnpm ignores `package.json#workspaces`: a member that kept the field after a yarn migration would otherwise read as the root, and rolldown-pnpm-config's `export` would have written a new `pnpm-workspace.yaml` there. The not-found error's `markers` field records the filtered list. `locateWorkspaceRootSync` is `findWorkspaceRootSync` with the match kept: a `WorkspaceRootMatch` of `root`, `marker` and the marker file's `path`.[^workspace-marker-ts] Its Effect form is the static `WorkspaceRoot.locate(cwd, options)`, which takes `FileSystem` and `Path` from `R` and runs the same ascent the service's `find` does (one shared implementation), answering a `WorkspaceRootMatch` or failing `WorkspaceRootNotFoundError` where the sync form answers `null`. It is a static rather than a `WorkspaceRootShape` member because a new member would break every hand-written `Layer.succeed(WorkspaceRoot, { find })` double; the cost is that a `WorkspaceRoot.layerTest` double does not answer it, so a test gives it a filesystem instead. A memfs agreement matrix pins it to `locateWorkspaceRootSync` on the same inputs.[^workspace-root-ts] The layer-level options (`WorkspaceDiscovery`, `LockfileReader`, `WorkspaceCatalogs`, `WorkspaceSnapshots`) take the same `markers` and forward it through the one shared lookup alongside `stopAt`, and `WorkspacesOptions` and `Workspaces.localExecLayer` take it too, so a pnpm-only tool going through `Workspaces.layer({ markers: ["pnpm-workspace.yaml"] })` gets one root from every service. Unlike `stopAt`, discovery's per-call `infoIn` / `listPackagesIn` / `refreshIn` honour the layer's `markers`: which file marks a root is a property of the tool, not of the directory it starts from.[^layer-root-ts] Every service that resolves a root from its layer options takes the same ceiling as `stopAt`: `WorkspaceDiscovery`, `LockfileReader`, `WorkspaceCatalogs` and `WorkspaceSnapshots`. All four resolve through ONE lookup, so they cannot disagree about which root a layer's options name.[^layer-root-ts] Pass `stopAt: cwd` and a checkout nested under someone else's workspace fails `WorkspaceRootNotFoundError` instead of adopting that workspace, while a checkout that is itself a root still resolves. Discovery's per-call `infoIn` / `listPackagesIn` / `refreshIn` stay unbounded, because one layer-level ceiling does not fit an arbitrary caller-named directory.[^workspace-discovery-ts] `WorkspacesOptions` extends the per-service option shapes and every `Workspaces.*` composite hands one options object to every service it builds, so a composite given `stopAt` fails every root-resolving read consistently. A hand-built graph that bounds discovery but not the lockfile, catalog or snapshot service gets a split result instead: discovery refuses the enclosing workspace while the others adopt it. Give every service the same value, or use a composite. `Workspaces.localExecLayer` takes `stopAt` too, and a refused root reads as its ordinary `None`. The default is no ceiling anywhere.[^workspaces-ts] The not-found message words the manifest marker as `package.json with a "workspaces" field`, since a bare `package.json` reads as missing a file a single-package repository plainly has; the `markers` field and `WORKSPACE_MARKERS` keep the raw filenames.[^workspace-root-ts] Discovery reads the packages list from whichever source the workspace uses, enumerates it, reads each manifest, and absorbs the longest-prefix file-to-package lookup. Discovery is bound to one root, and `listPackagesIn` / `infoIn` are the escape from that binding, not a convenience — a long-lived host such as an MCP server or a language server resolves its root once at startup and then serves calls scoped to a git worktree of the same repository, a nested repository, or another project entirely. These two take a directory, resolve its root by the same upward walk, and re-read everything beneath it. The re-read is the point: re-rooting the layer's existing package list by rewriting each `path` onto the caller's directory would produce correct-looking paths over the original root's manifests, so a worktree whose branch adds, removes, or renames a package would silently report the other branch's membership. Memoization is per resolved root, kept in a map deliberately separate from the layer-bound memo, so many directories inside one workspace can share one discovery without every layer-bound call re-running the root ascent. `refresh()` clears every per-root memo plus the layer-bound one; `refreshIn(directory)` drops exactly one, invalidating the cell before dropping the map reference so a fiber already holding that memo keeps its own reference rather than replaying a discarded discovery. There is no eviction policy, because the consuming host's roots are unbounded in principle but single-digit in practice. Root resolution takes an optional cwd, read lazily at first use inside a suspend, so a directory change between provide and first call is honoured; no service method reaches for the ambient cwd on its own. ## Package-manager detection Lockfile evidence is the primary signal, because it is what says which manager actually ran. The workspace tier checks the pnpm workspace file, then a bun lockfile plus a manifest field naming bun, then a `workspaces` field for npm — the manifest conjunction on bun disambiguates a stray lockfile in an npm repo. Yarn is recognized and refused: a `yarn.lock` that is the root's only lockfile, or a manifest field naming yarn, reports an `UnsupportedPackageManagerError` rather than an npm answer read off the `workspaces` field yarn shares with npm. Discovery itself stays neutral and reads a yarn repository's members from `package.json#workspaces`.[^package-manager-name-ts] Two further tiers close the single-package case, running only after every workspace marker has missed, which makes the widening strictly additive: a standalone tier, where a pnpm or npm lockfile stands alone because each is written by exactly one manager (bun keeps the manifest conjunction, mirroring the workspace tier exactly), and a declaration tier, where no lockfile exists at all but a manifest field names one of the three supported managers — weaker evidence, consulted last, for a fresh clone before its first install. The detector refuses to guess: nothing matching is a typed error, never a fabricated default, because choosing a default is policy, not detection, and a library that makes that choice silently guarantees some caller is wrong. A consumer wanting a default writes the fallback where a reader can see it. Within the workspace tier the npm `workspaces` field is still consulted before any standalone lockfile, so a repository with both reports npm; this known asymmetry is deliberately unchanged, because reordering would be a behavior change to an already-shipped path. The two manifest fields that can declare a manager — the top-level field and `devEngines.packageManager` — are not interchangeable: the dev-engines name is authoritative for the name where both are present and disagree, and the top-level field is authoritative for the exact version because it carries the integrity hash. A version is reported only when the field it came from names the manager actually detected. A malformed manifest hint is ignored, never fatal, but a root manifest that is present yet unreadable or unparseable fails typed, because that is a real problem rather than a missing hint. `detectPackageManagerSync(root, ops)` gives the same answer synchronously, as a `Result` whose failure is the detector's own error union; it probes `root` as given, with no ascent. Both surfaces run one pure decision in `internal/packageManagerDecision.ts`, and a parity table pins their agreement.[^package-manager-decision-ts] See [the sync escape hatch](../modules/workspaces.md#workspacessync--the-escape-hatch). ## Test doubles All three services ship `makeTest` / `layerTest` doubles, so the whole discovery path stands up with no filesystem at all. The `WorkspaceRoot` double honours `stopAt` — a hand-rolled `find` that ignores the ceiling makes a bounded call pass under test and fail live, the very failure the option exists to catch — and deliberately does not model `maxDepth`, because it never walks, so there is no depth to cap and pretending otherwise would encode a fiction; `WorkspaceRootShape` is exported so a consumer can type a bespoke double against the contract.[^workspace-root-ts] Both per-root methods die unstubbed on the double, because deriving `listPackagesIn` from `listPackages` would model a world in which every root holds the same members — precisely the confusion the method exists to remove. Workspace info and detection also die as defects rather than returning a fabricated default: a double that answered a detection question with a manager would contradict the defining property of the live detector, which is that it refuses to guess, and failing typed would be the subtler mistake, because a detection error reads as a legitimate "no manager here" answer a consumer branches on and proceeds past. [^workspace-discovery-ts]: `packages/workspaces/src/WorkspaceDiscovery.ts` — the `WorkspaceDiscovery` service, `WorkspaceInfo`, and its error union. [^workspace-package-ts]: `packages/workspaces/src/WorkspacePackage.ts` — `WorkspacePackage`, `PublishConfig`, `DependencyDiff`, `WorkspaceManifestError`. [^workspace-root-ts]: `packages/workspaces/src/WorkspaceRoot.ts` — the `WorkspaceRoot` service, the `locate` static, `FindWorkspaceRootOptions` (`stopAt` / `maxDepth` / `markers`), and the `makeTest` / `layerTest` double. [^package-manager-name-ts]: `packages/workspaces/src/PackageManagerName.ts` — `PackageManagerName`, `DetectedPackageManager`, `PackageManagerDetector`. [^enumerate-ts]: `packages/workspaces/src/internal/enumerate.ts` — the compiled-pattern enumerator. [^workspaces-ts]: `packages/workspaces/src/Workspaces.ts` — `WorkspacesOptions`, the composites' one-options-object forwarding, and `localExecLayer`. [^layer-root-ts]: `packages/workspaces/src/internal/layerRoot.ts` — the one layer-bound root lookup the four root-resolving services share, and the `stopAt` / `markers` forwarding `localExecLayer` reuses. [^traverse-ts]: `packages/workspaces/src/internal/traverse.ts` — the shared worklist traversal. [^workspaces-sync-ts]: `packages/workspaces/src/WorkspacesSync.ts` — `findWorkspaceRootSync`, `locateWorkspaceRootSync` and `FindWorkspaceRootSyncOptions` (`stopAt`, `markers`). [^workspace-marker-ts]: `packages/workspaces/src/WorkspaceMarker.ts` — `WorkspaceMarker`, `WORKSPACE_MARKERS` and `WorkspaceRootMatch`. [^package-manager-decision-ts]: `packages/workspaces/src/internal/packageManagerDecision.ts` — `decidePackageManager`, shared by `PackageManagerDetector` and `detectPackageManagerSync`.