@effected/workspaces 0.44.2 → 0.46.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/WorkspacesSync.js CHANGED
@@ -3,6 +3,7 @@ import { decidePackageManager } from "./internal/packageManagerDecision.js";
3
3
  import { manifestPatternsOf, pnpmPatternsOf } from "./internal/patterns.js";
4
4
  import { Traversal, badMaxDepthMessage, isPruned, isValidMaxDepth, joinRelative } from "./internal/traverse.js";
5
5
  import { DetectedPackageManager, PackageManagerDetectionError, PackageManagerEvidence } from "./PackageManagerName.js";
6
+ import { WorkspaceDiscoveryError, WorkspacePatternError } from "./WorkspaceDiscovery.js";
6
7
  import { WorkspaceRootMatch, probedMarkers } from "./WorkspaceMarker.js";
7
8
  import { PublishConfig, WorkspaceManifestError, WorkspacePackage } from "./WorkspacePackage.js";
8
9
  import { Effect, Exit, Option, Result, Schema } from "effect";
@@ -17,8 +18,8 @@ import { LocalExec, LocalExecError } from "@effected/commands";
17
18
  *
18
19
  * The three failures are kept apart — a throwing consumer `readFile`, a JSON
19
20
  * syntax error, and valid JSON that is not an object — because the skip report
20
- * carries the distinction; the two other callers of {@link readJson} do not
21
- * need it and keep the collapsed form.
21
+ * carries the distinction; the root ascent's {@link readJson} does not
22
+ * need it and keeps the collapsed form.
22
23
  */
23
24
  const readManifest = (fileSystem, file) => {
24
25
  let text;
@@ -200,24 +201,68 @@ const locateWorkspaceRootSync = (cwd, options) => {
200
201
  }
201
202
  return null;
202
203
  };
203
- /** The workspace `packages:` patterns for `root`, matching `internal/patterns.ts`'s precedence. */
204
+ /**
205
+ * The workspace `packages:` patterns for `root`, matching `internal/patterns.ts`'s
206
+ * precedence: `pnpm-workspace.yaml` first, then the root `package.json`
207
+ * `workspaces` field.
208
+ *
209
+ * A `pnpm-workspace.yaml` that EXISTS but cannot be read or parsed throws the
210
+ * `WorkspaceDiscoveryError` (`read` / `invalidYaml`) the Effect surface fails
211
+ * with. Falling back to `package.json#workspaces` there would answer from the
212
+ * wrong config, and an empty list would read as "no packages" — both decisions
213
+ * taken on a corrupt file. An ABSENT one is still the ordinary fallback.
214
+ *
215
+ * The root `package.json`, when it is the pattern source, follows the same
216
+ * rule: absent is no patterns, a throwing read is `read`, unparseable text is
217
+ * `invalidJson`, and valid JSON that is not an object declares no patterns.
218
+ */
204
219
  const readPatternsSync = (options, root) => {
205
220
  const { fileSystem, path } = options;
206
221
  const workspaceYaml = path.join(root, "pnpm-workspace.yaml");
207
222
  if (fileSystem.exists(workspaceYaml)) {
208
- let text = "";
223
+ let text;
209
224
  try {
210
225
  text = fileSystem.readFile(workspaceYaml);
211
- } catch {
212
- text = "";
213
- }
214
- const exit = Effect.runSyncExit(Yaml.parse(text));
215
- if (Exit.isSuccess(exit)) {
216
- const patterns = pnpmPatternsOf(exit.value);
217
- if (patterns.length > 0) return patterns;
226
+ } catch (cause) {
227
+ throw new WorkspaceDiscoveryError({
228
+ root,
229
+ path: workspaceYaml,
230
+ kind: "read",
231
+ cause
232
+ });
218
233
  }
234
+ const parsed = Yaml.parseResult(text);
235
+ if (Result.isFailure(parsed)) throw new WorkspaceDiscoveryError({
236
+ root,
237
+ path: workspaceYaml,
238
+ kind: "invalidYaml",
239
+ cause: parsed.failure
240
+ });
241
+ const patterns = pnpmPatternsOf(parsed.success);
242
+ if (patterns.length > 0) return patterns;
219
243
  }
220
- return manifestPatternsOf(readJson(fileSystem, path.join(root, "package.json")) ?? {});
244
+ const manifestPath = path.join(root, "package.json");
245
+ if (!fileSystem.exists(manifestPath)) return [];
246
+ let content;
247
+ try {
248
+ content = fileSystem.readFile(manifestPath);
249
+ } catch (cause) {
250
+ throw new WorkspaceDiscoveryError({
251
+ root,
252
+ path: manifestPath,
253
+ kind: "read",
254
+ cause
255
+ });
256
+ }
257
+ const manifest = PackageJsonFormat.parseObjectResult(content);
258
+ if (Result.isSuccess(manifest)) return manifestPatternsOf(manifest.success);
259
+ if (manifest.failure.reason === "not-an-object") return [];
260
+ throw new WorkspaceDiscoveryError({
261
+ root,
262
+ path: manifestPath,
263
+ kind: "invalidJson",
264
+ cause: manifest.failure
265
+ });
221
266
  };
222
267
  /**
223
268
  * Build a `WorkspacePackage` from a directory, or a {@link WorkspaceDiscoverySkip}
@@ -289,12 +334,32 @@ const readPackageSync = (options, root, directory, relativePath) => {
289
334
  * including at the depth boundary.
290
335
  *
291
336
  * The one deliberate difference is what happens at a bound: the Effect surface
292
- * fails typed (`depthExceeded` / `budgetExceeded`), while this one is **total**
293
- * and truncates. An unenumerable pattern or an unreadable manifest is skipped,
294
- * not raised — a function with no error channel should not pretend to have one,
295
- * and a Vitest config has nowhere to put a failure. Totality covers *data*, not
296
- * caller mistakes: a `maxDepth` that is not a positive integer throws, matching
297
- * the enumerator's defect.
337
+ * fails typed (`depthExceeded` / `budgetExceeded`), while this one truncates.
338
+ * An unenumerable pattern or an unreadable manifest is skipped, not raised —
339
+ * there the other patterns and members are still a real partial answer, and a
340
+ * Vitest config has nowhere to put a failure. A `maxDepth` that is not a
341
+ * positive integer throws a `RangeError`, matching the enumerator's defect.
342
+ *
343
+ * **A pattern set that does not compile throws.** The patterns compile as one
344
+ * `GlobSet`, and when that fails — one malformed member, or members that each
345
+ * compile alone but together exhaust the set's shared compile budget — there
346
+ * is no partial answer to degrade to: every pattern is lost at once. Returning
347
+ * the root alone would read as "no workspace packages", a decision taken on a
348
+ * corrupt config, so the facade throws the `WorkspacePatternError` (kind
349
+ * `"uncompilable"`, `pattern` the member the compile stopped at) that
350
+ * `WorkspaceDiscovery` fails with on the same root, before any manifest is
351
+ * read and before `onSkip` is called.
352
+ *
353
+ * **So does a `pnpm-workspace.yaml` that exists but cannot be used.** One
354
+ * whose `readFile` throws, or whose text does not parse as YAML, throws the
355
+ * `WorkspaceDiscoveryError` (kind `"read"` / `"invalidYaml"`, `path` the YAML
356
+ * file) the Effect surface fails with, rather than falling back to
357
+ * `package.json#workspaces`. A MISSING one is the ordinary fallback, as on
358
+ * the Effect surface. When that fallback is taken, the root `package.json`
359
+ * is held to the same rule: one whose `readFile` throws, or whose text is not
360
+ * JSON, throws kind `"read"` / `"invalidJson"`, while a missing one is a
361
+ * standalone directory (`[]`) and valid JSON that is not an object declares
362
+ * no patterns and is reported through `onSkip` as the root's `invalidShape`.
298
363
  *
299
364
  * **A skip is never silent.** Every manifest left out is reported through
300
365
  * `onSkip` with its path and the same `kind` the Effect surface would have
@@ -306,6 +371,13 @@ const readPackageSync = (options, root, directory, relativePath) => {
306
371
  * @param root - The workspace root, from {@link findWorkspaceRootSync}.
307
372
  * @param options - The consumer-supplied operations and traversal bounds; see
308
373
  * {@link GetWorkspacePackagesSyncOptions}.
374
+ * @throws `WorkspaceDiscoveryError` (kind `"read"` or `"invalidYaml"`) when
375
+ * `pnpm-workspace.yaml` exists but cannot be read or parsed, and (kind
376
+ * `"read"` or `"invalidJson"`) when the root `package.json` is the pattern
377
+ * source and exists but cannot be read or parsed;
378
+ * `WorkspacePatternError` (kind `"uncompilable"`) when the workspace's
379
+ * `packages:` patterns do not compile as one `GlobSet`; `RangeError` for a
380
+ * `maxDepth` that is not a positive integer.
309
381
  *
310
382
  * @example
311
383
  * ```ts
@@ -333,9 +405,14 @@ const getWorkspacePackagesSync = (root, options) => {
333
405
  const maxDepth = options.maxDepth ?? 32;
334
406
  if (!isValidMaxDepth(maxDepth)) throw new RangeError(`getWorkspacePackagesSync: ${badMaxDepthMessage(maxDepth)}`);
335
407
  const patterns = readPatternsSync(options, root);
336
- const compiled = Effect.runSyncExit(GlobSet.compile(patterns));
337
- if (Exit.isFailure(compiled)) return [];
338
- const globs = compiled.value;
408
+ const compiled = GlobSet.compileResult(patterns);
409
+ if (Result.isFailure(compiled)) throw new WorkspacePatternError({
410
+ root,
411
+ pattern: compiled.failure.pattern,
412
+ kind: "uncompilable",
413
+ detail: compiled.failure.message
414
+ });
415
+ const globs = compiled.success;
339
416
  const excludes = globs.excludes;
340
417
  const isExcluded = excludes.length === 0 ? (_) => false : (relative) => excludes.some((exclude) => exclude.matches(relative));
341
418
  const included = /* @__PURE__ */ new Map();
package/index.d.ts CHANGED
@@ -1,3 +1,32 @@
1
+ /**
2
+ * Monorepo workspace tooling as Effect services: find the workspace root,
3
+ * enumerate its packages, walk the dependency graph, detect the package
4
+ * manager, resolve pnpm catalogs, read the lockfile, and work out which
5
+ * packages a git range touches.
6
+ *
7
+ * The pure halves live in siblings — `@effected/lockfiles` parses lockfile
8
+ * text, `@effected/glob` matches patterns, `@effected/walker` ascends
9
+ * directories. This package is the part that needs a filesystem and a package
10
+ * manager under it, and it is where `@effected/npm`'s `CatalogResolver` and
11
+ * `WorkspaceResolver` contracts are implemented.
12
+ *
13
+ * @example
14
+ * ```ts
15
+ * import * as NodeServices from "@effect/platform-node/NodeServices";
16
+ * import { WorkspaceDiscovery, Workspaces } from "@effected/workspaces";
17
+ * import { Effect, Layer } from "effect";
18
+ *
19
+ * const WorkspacesLayer = Workspaces.layer().pipe(Layer.provide(NodeServices.layer));
20
+ *
21
+ * const program = Effect.gen(function* () {
22
+ * const discovery = yield* WorkspaceDiscovery;
23
+ * const packages = yield* discovery.listPackages();
24
+ * return packages.map((pkg) => pkg.name);
25
+ * }).pipe(Effect.provide(WorkspacesLayer));
26
+ * ```
27
+ *
28
+ * @packageDocumentation
29
+ */
1
30
  import { Git, GitCommandError, NotARepositoryError, UnknownRefError } from "@effected/git";
2
31
  import { Context, Effect, FileSystem, Layer, Option, Path, Result, Schema } from "effect";
3
32
  import { CatalogAssemblyError, CatalogResolver, DependencyResolutionError, Manifest, PartialReleaseAgeGate, ReleaseAgeGate, UnresolvedDependencyError, WorkspaceResolver } from "@effected/npm";
@@ -4943,14 +4972,19 @@ export declare class Workspaces {
4943
4972
  * permission error mid-read — and every throw is absorbed into the documented
4944
4973
  * degraded-skip semantics: a throwing `readFile` reads as an unusable
4945
4974
  * manifest, a throwing `readDirectory` as an unreadable directory, a throwing
4946
- * `isDirectory` as "not a directory". Nothing propagates.
4975
+ * `isDirectory` as "not a directory". The one exception is a `readFile` of
4976
+ * the file `getWorkspacePackagesSync` takes its patterns from (an existing
4977
+ * `pnpm-workspace.yaml`, or the root `package.json` in its absence): there is
4978
+ * no partial answer without it, so the throw comes back as a
4979
+ * `WorkspaceDiscoveryError` of kind `"read"` carrying it as `cause`. Nothing
4980
+ * propagates raw.
4947
4981
  *
4948
4982
  * @public
4949
4983
  */
4950
4984
  interface SyncFileSystem {
4951
4985
  /** Whether a file or directory exists at `path`. Must not throw. */
4952
4986
  readonly exists: (path: string) => boolean;
4953
- /** Read the file at `path` as text. May throw; a throw degrades to a skip. */
4987
+ /** Read the file at `path` as text. May throw; a throw degrades to a skip (the pattern source excepted). */
4954
4988
  readonly readFile: (path: string) => string;
4955
4989
  /** The entry names inside the directory at `path`. May throw; a throw skips the directory. */
4956
4990
  readonly readDirectory: (path: string) => ReadonlyArray<string>;
@@ -5274,12 +5308,32 @@ interface GetWorkspacePackagesSyncOptions extends WorkspacesSyncOptions {
5274
5308
  * including at the depth boundary.
5275
5309
  *
5276
5310
  * The one deliberate difference is what happens at a bound: the Effect surface
5277
- * fails typed (`depthExceeded` / `budgetExceeded`), while this one is **total**
5278
- * and truncates. An unenumerable pattern or an unreadable manifest is skipped,
5279
- * not raised — a function with no error channel should not pretend to have one,
5280
- * and a Vitest config has nowhere to put a failure. Totality covers *data*, not
5281
- * caller mistakes: a `maxDepth` that is not a positive integer throws, matching
5282
- * the enumerator's defect.
5311
+ * fails typed (`depthExceeded` / `budgetExceeded`), while this one truncates.
5312
+ * An unenumerable pattern or an unreadable manifest is skipped, not raised —
5313
+ * there the other patterns and members are still a real partial answer, and a
5314
+ * Vitest config has nowhere to put a failure. A `maxDepth` that is not a
5315
+ * positive integer throws a `RangeError`, matching the enumerator's defect.
5316
+ *
5317
+ * **A pattern set that does not compile throws.** The patterns compile as one
5318
+ * `GlobSet`, and when that fails — one malformed member, or members that each
5319
+ * compile alone but together exhaust the set's shared compile budget — there
5320
+ * is no partial answer to degrade to: every pattern is lost at once. Returning
5321
+ * the root alone would read as "no workspace packages", a decision taken on a
5322
+ * corrupt config, so the facade throws the `WorkspacePatternError` (kind
5323
+ * `"uncompilable"`, `pattern` the member the compile stopped at) that
5324
+ * `WorkspaceDiscovery` fails with on the same root, before any manifest is
5325
+ * read and before `onSkip` is called.
5326
+ *
5327
+ * **So does a `pnpm-workspace.yaml` that exists but cannot be used.** One
5328
+ * whose `readFile` throws, or whose text does not parse as YAML, throws the
5329
+ * `WorkspaceDiscoveryError` (kind `"read"` / `"invalidYaml"`, `path` the YAML
5330
+ * file) the Effect surface fails with, rather than falling back to
5331
+ * `package.json#workspaces`. A MISSING one is the ordinary fallback, as on
5332
+ * the Effect surface. When that fallback is taken, the root `package.json`
5333
+ * is held to the same rule: one whose `readFile` throws, or whose text is not
5334
+ * JSON, throws kind `"read"` / `"invalidJson"`, while a missing one is a
5335
+ * standalone directory (`[]`) and valid JSON that is not an object declares
5336
+ * no patterns and is reported through `onSkip` as the root's `invalidShape`.
5283
5337
  *
5284
5338
  * **A skip is never silent.** Every manifest left out is reported through
5285
5339
  * `onSkip` with its path and the same `kind` the Effect surface would have
@@ -5291,6 +5345,13 @@ interface GetWorkspacePackagesSyncOptions extends WorkspacesSyncOptions {
5291
5345
  * @param root - The workspace root, from {@link findWorkspaceRootSync}.
5292
5346
  * @param options - The consumer-supplied operations and traversal bounds; see
5293
5347
  * {@link GetWorkspacePackagesSyncOptions}.
5348
+ * @throws `WorkspaceDiscoveryError` (kind `"read"` or `"invalidYaml"`) when
5349
+ * `pnpm-workspace.yaml` exists but cannot be read or parsed, and (kind
5350
+ * `"read"` or `"invalidJson"`) when the root `package.json` is the pattern
5351
+ * source and exists but cannot be read or parsed;
5352
+ * `WorkspacePatternError` (kind `"uncompilable"`) when the workspace's
5353
+ * `packages:` patterns do not compile as one `GlobSet`; `RangeError` for a
5354
+ * `maxDepth` that is not a positive integer.
5294
5355
  *
5295
5356
  * @example
5296
5357
  * ```ts
package/node-sync.d.ts CHANGED
@@ -1,9 +1,28 @@
1
- import "@effected/commands";
2
- import "effect";
3
- import "@effected/glob";
4
- import "@effected/lockfiles";
5
- import "@effected/package-json";
6
- import "@effected/npm";
1
+ /**
2
+ * The Node.js binding for the sync entry points — ready-made `SyncFileSystem`
3
+ * and `SyncPath` operations over `node:fs` / `node:path`, so adopting
4
+ * `findWorkspaceRootSync` / `getWorkspacePackagesSync` is one import instead
5
+ * of four hand-wired one-liners.
6
+ *
7
+ * Deliberately a **separate subpath** (`@effected/workspaces/node-sync`), not
8
+ * part of the main entry: the main entry imports nothing platform-shaped, and
9
+ * re-exporting these from it would drag `node:*` imports into every consumer —
10
+ * including the ones supplying their own operations (a win32-explicit `path`,
11
+ * a Bun or Deno binding, a test fake). Import this module only where Node's
12
+ * built-ins are the platform you mean; `nodePath` is the running platform's
13
+ * `node:path`, so on Windows the paths handed back are win32 paths.
14
+ *
15
+ * @example
16
+ * ```ts
17
+ * import { findWorkspaceRootSync, getWorkspacePackagesSync } from "@effected/workspaces";
18
+ * import { nodeSyncOps } from "@effected/workspaces/node-sync";
19
+ *
20
+ * const root = findWorkspaceRootSync(process.cwd(), nodeSyncOps);
21
+ * const packages = root === null ? [] : getWorkspacePackagesSync(root, nodeSyncOps);
22
+ * ```
23
+ *
24
+ * @packageDocumentation
25
+ */
7
26
  /**
8
27
  * The synchronous file operations the sync entry points need, supplied by the
9
28
  * consumer. Node's built-ins satisfy it directly:
@@ -24,14 +43,19 @@ import "@effected/npm";
24
43
  * permission error mid-read — and every throw is absorbed into the documented
25
44
  * degraded-skip semantics: a throwing `readFile` reads as an unusable
26
45
  * manifest, a throwing `readDirectory` as an unreadable directory, a throwing
27
- * `isDirectory` as "not a directory". Nothing propagates.
46
+ * `isDirectory` as "not a directory". The one exception is a `readFile` of
47
+ * the file `getWorkspacePackagesSync` takes its patterns from (an existing
48
+ * `pnpm-workspace.yaml`, or the root `package.json` in its absence): there is
49
+ * no partial answer without it, so the throw comes back as a
50
+ * `WorkspaceDiscoveryError` of kind `"read"` carrying it as `cause`. Nothing
51
+ * propagates raw.
28
52
  *
29
53
  * @public
30
54
  */
31
55
  interface SyncFileSystem {
32
56
  /** Whether a file or directory exists at `path`. Must not throw. */
33
57
  readonly exists: (path: string) => boolean;
34
- /** Read the file at `path` as text. May throw; a throw degrades to a skip. */
58
+ /** Read the file at `path` as text. May throw; a throw degrades to a skip (the pattern source excepted). */
35
59
  readonly readFile: (path: string) => string;
36
60
  /** The entry names inside the directory at `path`. May throw; a throw skips the directory. */
37
61
  readonly readDirectory: (path: string) => ReadonlyArray<string>;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@effected/workspaces",
3
- "version": "0.44.2",
3
+ "version": "0.46.0",
4
4
  "private": false,
5
5
  "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.",
6
6
  "keywords": [
@@ -51,16 +51,16 @@
51
51
  "./package.json": "./package.json"
52
52
  },
53
53
  "dependencies": {
54
- "@effected/commands": "^0.20.1",
55
- "@effected/git": "^0.31.0",
56
- "@effected/glob": "^0.20.0",
57
- "@effected/jsonc": "^0.24.0",
58
- "@effected/lockfiles": "^0.23.2",
59
- "@effected/npm": "^0.32.1",
60
- "@effected/package-json": "^0.31.2",
61
- "@effected/semver": "^0.23.0",
62
- "@effected/walker": "^0.26.0",
63
- "@effected/yaml": "^0.29.0",
54
+ "@effected/commands": "^0.21.0",
55
+ "@effected/git": "^0.32.0",
56
+ "@effected/glob": "^0.21.0",
57
+ "@effected/jsonc": "^0.25.0",
58
+ "@effected/lockfiles": "^0.24.1",
59
+ "@effected/npm": "^0.34.0",
60
+ "@effected/package-json": "^0.32.1",
61
+ "@effected/semver": "^0.24.0",
62
+ "@effected/walker": "^0.28.0",
63
+ "@effected/yaml": "^0.30.0",
64
64
  "@pnpm/catalogs.config": "^1100.0.5",
65
65
  "@pnpm/catalogs.protocol-parser": "^1100.0.0",
66
66
  "@pnpm/catalogs.resolver": "^1100.0.0",
package/testing.d.ts CHANGED
@@ -1,3 +1,20 @@
1
+ /**
2
+ * Repo-shape checks for a monorepo's own test suite: `SourceBoundary` keeps
3
+ * `process`, `node:` imports and console writes out of modules meant to be
4
+ * free of them, `ImportGraph` answers the two questions that belong to the
5
+ * import graph rather than to any one file — whether the entries reach a
6
+ * forbidden import at all, and whether every runtime import is declared —
7
+ * `WorkspaceLayering` holds the package graph to a committed
8
+ * `LayerPolicy`, and `PackedInstall` proves a carrier's bins install from its
9
+ * packed tarballs under every available package manager.
10
+ *
11
+ * @remarks
12
+ * A separate subpath, never re-exported from `.`, so the main entry's
13
+ * consumers never load a scanner, a policy decoder or package-manager
14
+ * orchestration they do not use.
15
+ *
16
+ * @packageDocumentation
17
+ */
1
18
  import { DependencyField, WorkspaceResolver } from "@effected/npm";
2
19
  import { Context, Duration, Effect, FileSystem, Layer, Option, Path, PlatformError, Schema, Stream } from "effect";
3
20
  import { GlobPattern } from "@effected/glob";