@effected/workspaces 0.39.1 → 0.40.1

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
@@ -2,6 +2,7 @@ import { Traversal, badMaxDepthMessage, isPruned, isValidMaxDepth, joinRelative
2
2
  import { isStringRecord } from "./internal/guards.js";
3
3
  import { manifestPatternsOf, pnpmPatternsOf } from "./internal/patterns.js";
4
4
  import { PublishConfig, WorkspaceManifestError, WorkspacePackage } from "./WorkspacePackage.js";
5
+ import { WorkspaceRootMatch, probedMarkers } from "./WorkspaceMarker.js";
5
6
  import { decidePackageManager } from "./internal/packageManagerDecision.js";
6
7
  import { DetectedPackageManager, PackageManagerDetectionError, PackageManagerEvidence } from "./PackageManagerName.js";
7
8
  import { Effect, Exit, Option, Result, Schema } from "effect";
@@ -114,7 +115,9 @@ const isPackage = (options, dir) => options.fileSystem.exists(options.path.join(
114
115
  * positional, so the function reads no ambient `process.cwd()`.
115
116
  *
116
117
  * Markers match the async service exactly: a `pnpm-workspace.yaml`, or a
117
- * `package.json` carrying a `workspaces` field.
118
+ * `package.json` carrying a `workspaces` field, narrowed by
119
+ * `options.markers` ({@link FindWorkspaceRootSyncOptions.markers}). For the
120
+ * matched file as well as the root, use {@link locateWorkspaceRootSync}.
118
121
  *
119
122
  * The ascent is unbounded unless `options.stopAt` names a ceiling
120
123
  * ({@link FindWorkspaceRootSyncOptions.stopAt}), with the Effect surface's
@@ -147,14 +150,49 @@ const isPackage = (options, dir) => options.fileSystem.exists(options.path.join(
147
150
  *
148
151
  * @public
149
152
  */
150
- const findWorkspaceRootSync = (cwd, options) => {
153
+ const findWorkspaceRootSync = (cwd, options) => locateWorkspaceRootSync(cwd, options)?.root ?? null;
154
+ /**
155
+ * The nearest workspace root at or above `cwd` and the marker file that made
156
+ * it one, or `null`.
157
+ *
158
+ * @remarks
159
+ * {@link findWorkspaceRootSync} with the match kept: the same ascent, the same
160
+ * `stopAt` and `markers`, answering a `WorkspaceRootMatch` whose `path` is the
161
+ * matched file. A tool that rewrites the marker (an `export` writing
162
+ * `pnpm-workspace.yaml`) reads the path from here rather than re-deriving it.
163
+ *
164
+ * @param cwd - Where to start the ascent.
165
+ * @param options - The consumer-supplied file and path operations, plus the
166
+ * optional `stopAt` ceiling and `markers` filter.
167
+ *
168
+ * @example
169
+ * ```ts
170
+ * import { locateWorkspaceRootSync } from "@effected/workspaces";
171
+ * import { nodeSyncOps } from "@effected/workspaces/node-sync";
172
+ *
173
+ * const match = locateWorkspaceRootSync(process.cwd(), { ...nodeSyncOps, markers: ["pnpm-workspace.yaml"] });
174
+ * console.log(match?.path);
175
+ * // => /repo/pnpm-workspace.yaml
176
+ * ```
177
+ *
178
+ * @public
179
+ */
180
+ const locateWorkspaceRootSync = (cwd, options) => {
151
181
  const { fileSystem, path } = options;
182
+ const markers = probedMarkers(options.markers);
183
+ const matched = (root, marker) => WorkspaceRootMatch.make({
184
+ root,
185
+ marker,
186
+ path: path.join(root, marker)
187
+ });
152
188
  let current = path.resolve(cwd);
153
189
  const ceiling = options.stopAt === void 0 ? void 0 : path.resolve(options.stopAt);
154
190
  for (let depth = 0; depth < 32 * 8; depth++) {
155
- if (fileSystem.exists(path.join(current, "pnpm-workspace.yaml"))) return current;
156
- const manifest = readJson(fileSystem, path.join(current, "package.json"));
157
- if (manifest?.workspaces !== void 0 && manifest.workspaces !== null) return current;
191
+ if (markers.includes("pnpm-workspace.yaml") && fileSystem.exists(path.join(current, "pnpm-workspace.yaml"))) return matched(current, "pnpm-workspace.yaml");
192
+ if (markers.includes("package.json")) {
193
+ const manifest = readJson(fileSystem, path.join(current, "package.json"));
194
+ if (manifest?.workspaces !== void 0 && manifest.workspaces !== null) return matched(current, "package.json");
195
+ }
158
196
  if (ceiling !== void 0 && current === ceiling) return null;
159
197
  const parent = path.dirname(current);
160
198
  if (parent === current) return null;
@@ -463,4 +501,4 @@ const localExecContextSync = (cwd, options) => {
463
501
  return Result.succeed(Option.some(LocalExec.contextFor(detected.success.name, { directory: root })));
464
502
  };
465
503
 
466
- export { detectPackageManagerSync, findWorkspaceRootSync, getWorkspacePackagesSync, localExecContextSync };
504
+ export { detectPackageManagerSync, findWorkspaceRootSync, getWorkspacePackagesSync, localExecContextSync, locateWorkspaceRootSync };
package/index.d.ts CHANGED
@@ -7,6 +7,39 @@ import { Package } from "@effected/package-json";
7
7
  import { ChildProcessSpawner } from "effect/process";
8
8
  import { SemVer } from "@effected/semver";
9
9
  import { ExecContext, LocalExec, LocalExecError } from "@effected/commands";
10
+ /**
11
+ * A file that marks a workspace root: a `pnpm-workspace.yaml`, or a
12
+ * `package.json` carrying a `workspaces` field.
13
+ *
14
+ * @public
15
+ */
16
+ export declare const WorkspaceMarker: Schema.Literals<readonly ["pnpm-workspace.yaml", "package.json"]>;
17
+ /**
18
+ * The decoded type of {@link (WorkspaceMarker:variable)}.
19
+ *
20
+ * @public
21
+ */
22
+ export type WorkspaceMarker = typeof WorkspaceMarker.Type;
23
+ /**
24
+ * The marker filenames {@link WorkspaceRoot} probes for, in priority order.
25
+ *
26
+ * @public
27
+ */
28
+ export declare const WORKSPACE_MARKERS: ReadonlyArray<WorkspaceMarker>;
29
+ declare const WorkspaceRootMatch_base: Schema.Class<WorkspaceRootMatch, Schema.Struct<{
30
+ /** The workspace root directory. */
31
+ readonly root: Schema.String;
32
+ /** Which marker matched. */
33
+ readonly marker: Schema.Literals<readonly ["pnpm-workspace.yaml", "package.json"]>;
34
+ /** The marker file's path: `root` joined with `marker`. */
35
+ readonly path: Schema.String;
36
+ }>, {}>;
37
+ /**
38
+ * A workspace root, and the marker file that made it one.
39
+ *
40
+ * @public
41
+ */
42
+ export declare class WorkspaceRootMatch extends WorkspaceRootMatch_base {}
10
43
  declare const PublishConfig_base: Schema.Class<PublishConfig, Schema.Struct<{
11
44
  /** Scoped-package visibility. Its presence overrides `private`. */
12
45
  readonly access: Schema.optionalKey<Schema.Literals<readonly ["public", "restricted"]>>;
@@ -242,12 +275,6 @@ export declare class WorkspacePackage extends WorkspacePackage_base {
242
275
  /** Instance form of `WorkspacePackage.manifest`. */
243
276
  manifest(): Effect.Effect<Package, WorkspaceManifestError, FileSystem.FileSystem>;
244
277
  }
245
- /**
246
- * The marker filenames {@link WorkspaceRoot} probes for, in priority order.
247
- *
248
- * @public
249
- */
250
- export declare const WORKSPACE_MARKERS: ReadonlyArray<string>;
251
278
  /**
252
279
  * Options for {@link WorkspaceRoot}'s `find`.
253
280
  *
@@ -279,6 +306,19 @@ interface FindWorkspaceRootOptions {
279
306
  * @defaultValue 256
280
307
  */
281
308
  readonly maxDepth?: number;
309
+ /**
310
+ * The markers that count, matched in their fixed priority order
311
+ * (`pnpm-workspace.yaml` first) whatever order they are listed in.
312
+ *
313
+ * @remarks
314
+ * Pass `["pnpm-workspace.yaml"]` for a pnpm-only tool: pnpm ignores
315
+ * `package.json#workspaces`, so a member package that kept the field (common
316
+ * after a yarn migration) must not read as the root. An empty list is a
317
+ * **defect**, like a bad `maxDepth`.
318
+ *
319
+ * @defaultValue every marker, `WORKSPACE_MARKERS`
320
+ */
321
+ readonly markers?: ReadonlyArray<WorkspaceMarker>;
282
322
  }
283
323
  declare const WorkspaceRootNotFoundError_base: Schema.Class<WorkspaceRootNotFoundError, Schema.TaggedStruct<"WorkspaceRootNotFoundError", {
284
324
  /** The directory the ascent started from. */
@@ -365,6 +405,42 @@ declare const WorkspaceRoot_base: Context.ServiceClass<WorkspaceRoot, "@effected
365
405
  export declare class WorkspaceRoot extends WorkspaceRoot_base {
366
406
  /** Builds the service over core `FileSystem` and `Path`. */
367
407
  static readonly make: Effect.Effect<WorkspaceRootShape, never, FileSystem.FileSystem | Path.Path>;
408
+ /**
409
+ * The nearest workspace root at or above `cwd` and the marker file that made
410
+ * it one — the Effect form of `locateWorkspaceRootSync`.
411
+ *
412
+ * @remarks
413
+ * The same ascent as the service's `find`, with the same `stopAt`,
414
+ * `maxDepth` and `markers`, answering a {@link WorkspaceRootMatch} whose
415
+ * `path` is the matched file. A tool that rewrites the marker (an `export`
416
+ * writing `pnpm-workspace.yaml`) reads the path from here rather than
417
+ * re-deriving it from the root.
418
+ *
419
+ * It is a static over core `FileSystem` and `Path` in `R`, not a member of
420
+ * {@link WorkspaceRootShape}: a new member would break every hand-written
421
+ * `Layer.succeed(WorkspaceRoot, { find })` double. The consequence is that
422
+ * it never consults a provided `WorkspaceRoot` — a
423
+ * {@link WorkspaceRoot.layerTest} double does not answer it; a test gives it
424
+ * a filesystem (an `@effected/memfs` volume) instead. On the same inputs it
425
+ * agrees with `locateWorkspaceRootSync`, which answers `null` where this
426
+ * fails {@link WorkspaceRootNotFoundError}.
427
+ *
428
+ * @param cwd - The directory to start the ascent from; resolved to an
429
+ * absolute path first.
430
+ * @param options - The ascent bounds and marker filter of `find`.
431
+ *
432
+ * @example
433
+ * ```ts
434
+ * import { WorkspaceRoot } from "@effected/workspaces";
435
+ * import { Effect } from "effect";
436
+ *
437
+ * const program = Effect.gen(function* () {
438
+ * const match = yield* WorkspaceRoot.locate("/repo/packages/a", { markers: ["pnpm-workspace.yaml"] });
439
+ * return match.path; // "/repo/pnpm-workspace.yaml"
440
+ * });
441
+ * ```
442
+ */
443
+ static readonly locate: (cwd: string, options?: FindWorkspaceRootOptions) => Effect.Effect<WorkspaceRootMatch, WorkspaceRootNotFoundError, FileSystem.FileSystem | Path.Path>;
368
444
  /** The live layer. */
369
445
  static readonly layer: Layer.Layer<WorkspaceRoot, never, FileSystem.FileSystem | Path.Path>;
370
446
  /**
@@ -387,13 +463,21 @@ export declare class WorkspaceRoot extends WorkspaceRoot_base {
387
463
  * `Path.layer` internally, so the requirement never surfaces at their call
388
464
  * site.
389
465
  *
466
+ * `markers` is honoured the same way: the double's root is marked by
467
+ * `marker` (`"pnpm-workspace.yaml"` unless given), so a `find` whose
468
+ * `markers` leave that marker out fails as the live service would, and a
469
+ * `find` with an empty list dies.
470
+ *
390
471
  * `maxDepth` is deliberately NOT modelled: the double does not walk, so it has
391
472
  * no depth to cap, and pretending otherwise would encode a fiction. A suite
392
473
  * exercising the depth guard wants the live service over a fixture tree.
393
474
  *
394
475
  * @param root - The root every unbounded `find` resolves to.
476
+ * @param options - `marker`: the marker the double's root carries.
395
477
  */
396
- static readonly makeTest: (root: string) => Effect.Effect<WorkspaceRootShape, never, Path.Path>;
478
+ static readonly makeTest: (root: string, options?: {
479
+ readonly marker?: WorkspaceMarker | undefined;
480
+ }) => Effect.Effect<WorkspaceRootShape, never, Path.Path>;
397
481
  /**
398
482
  * The test layer: {@link WorkspaceRoot.makeTest} with `Path.layer` provided.
399
483
  *
@@ -423,7 +507,9 @@ export declare class WorkspaceRoot extends WorkspaceRoot_base {
423
507
  * // program.pipe(Effect.provide(TestRoot), Effect.provide(TestDiscovery))
424
508
  * ```
425
509
  */
426
- static readonly layerTest: (root: string) => Layer.Layer<WorkspaceRoot>;
510
+ static readonly layerTest: (root: string, options?: {
511
+ readonly marker?: WorkspaceMarker | undefined;
512
+ }) => Layer.Layer<WorkspaceRoot>;
427
513
  }
428
514
  declare const WorkspaceDiscoveryError_base: Schema.Class<WorkspaceDiscoveryError, Schema.TaggedStruct<"WorkspaceDiscoveryError", {
429
515
  /** The workspace root discovery was running against. */
@@ -565,6 +651,26 @@ interface WorkspaceDiscoveryOptions {
565
651
  * @defaultValue no ceiling — the ascent runs to the filesystem root.
566
652
  */
567
653
  readonly stopAt?: string | undefined;
654
+ /**
655
+ * The markers that count as a workspace root, passed straight through to
656
+ * the `markers` of {@link WorkspaceRoot}'s `find`.
657
+ *
658
+ * @remarks
659
+ * Pass `["pnpm-workspace.yaml"]` for a pnpm-only tool: pnpm ignores
660
+ * `package.json#workspaces`, so a member package that kept the field
661
+ * (common after a yarn migration) must not read as the root. An empty
662
+ * list is a **defect** at first use, as it is for `find`.
663
+ *
664
+ * Unlike `stopAt`, it applies to the per-call `infoIn`, `listPackagesIn`
665
+ * and `refreshIn` too: which file marks a root is a property of the
666
+ * tool, not of the directory it starts from. `LockfileReader`,
667
+ * `WorkspaceCatalogs` and `WorkspaceSnapshots` each take the same
668
+ * option; the `Workspaces.*` composites forward one `markers` to all of
669
+ * them, so no service stops at a root another passed.
670
+ *
671
+ * @defaultValue every marker, `WORKSPACE_MARKERS`
672
+ */
673
+ readonly markers?: ReadonlyArray<WorkspaceMarker> | undefined;
568
674
  /** Descent cap for segment-crossing patterns. Defaults to 32. */
569
675
  readonly maxDepth?: number;
570
676
  }
@@ -2071,6 +2177,23 @@ interface LockfileReaderOptions {
2071
2177
  * @defaultValue no ceiling — the ascent runs to the filesystem root.
2072
2178
  */
2073
2179
  readonly stopAt?: string | undefined;
2180
+ /**
2181
+ * The markers that count as a workspace root, passed straight through to
2182
+ * the `markers` of {@link WorkspaceRoot}'s `find`.
2183
+ *
2184
+ * @remarks
2185
+ * Pass `["pnpm-workspace.yaml"]` for a pnpm-only tool: pnpm ignores
2186
+ * `package.json#workspaces`, so a member package that kept the field
2187
+ * (common after a yarn migration) must not read as the root. An empty
2188
+ * list is a **defect** at first use, as it is for `find`.
2189
+ *
2190
+ * Give it the same value as {@link WorkspaceDiscoveryOptions.markers}
2191
+ * when wiring by hand; the `Workspaces.*` composites forward one
2192
+ * `markers` to every root-resolving service.
2193
+ *
2194
+ * @defaultValue every marker, `WORKSPACE_MARKERS`
2195
+ */
2196
+ readonly markers?: ReadonlyArray<WorkspaceMarker> | undefined;
2074
2197
  }
2075
2198
  declare const LockfileReader_base: Context.ServiceClass<LockfileReader, "@effected/workspaces/LockfileReader", LockfileReaderShape>;
2076
2199
  /**
@@ -2413,6 +2536,23 @@ interface WorkspaceCatalogsOptions {
2413
2536
  * @defaultValue no ceiling — the ascent runs to the filesystem root.
2414
2537
  */
2415
2538
  readonly stopAt?: string | undefined;
2539
+ /**
2540
+ * The markers that count as a workspace root, passed straight through to
2541
+ * the `markers` of {@link WorkspaceRoot}'s `find`.
2542
+ *
2543
+ * @remarks
2544
+ * Pass `["pnpm-workspace.yaml"]` for a pnpm-only tool: pnpm ignores
2545
+ * `package.json#workspaces`, so a member package that kept the field
2546
+ * (common after a yarn migration) must not read as the root. An empty
2547
+ * list is a **defect** at first use, as it is for `find`.
2548
+ *
2549
+ * Give it the same value as {@link WorkspaceDiscoveryOptions.markers}
2550
+ * when wiring by hand; the `Workspaces.*` composites forward one
2551
+ * `markers` to every root-resolving service.
2552
+ *
2553
+ * @defaultValue every marker, `WORKSPACE_MARKERS`
2554
+ */
2555
+ readonly markers?: ReadonlyArray<WorkspaceMarker> | undefined;
2416
2556
  }
2417
2557
  declare const WorkspaceCatalogs_base: Context.ServiceClass<WorkspaceCatalogs, "@effected/workspaces/WorkspaceCatalogs", WorkspaceCatalogsShape>;
2418
2558
  /**
@@ -3854,6 +3994,23 @@ interface WorkspaceSnapshotsOptions {
3854
3994
  * @defaultValue no ceiling — the ascent runs to the filesystem root.
3855
3995
  */
3856
3996
  readonly stopAt?: string | undefined;
3997
+ /**
3998
+ * The markers that count as a workspace root, passed straight through to
3999
+ * the `markers` of {@link WorkspaceRoot}'s `find`.
4000
+ *
4001
+ * @remarks
4002
+ * Pass `["pnpm-workspace.yaml"]` for a pnpm-only tool: pnpm ignores
4003
+ * `package.json#workspaces`, so a member package that kept the field
4004
+ * (common after a yarn migration) must not read as the root. An empty
4005
+ * list is a **defect** at first use, as it is for `find`.
4006
+ *
4007
+ * Give it the same value as {@link WorkspaceDiscoveryOptions.markers}
4008
+ * when wiring by hand; the `Workspaces.*` composites forward one
4009
+ * `markers` to every root-resolving service.
4010
+ *
4011
+ * @defaultValue every marker, `WORKSPACE_MARKERS`
4012
+ */
4013
+ readonly markers?: ReadonlyArray<WorkspaceMarker> | undefined;
3857
4014
  /**
3858
4015
  * Catalogs every snapshot this service produces carries as its
3859
4016
  * `seededCatalogs` — consulted only where the snapshot's own catalogs cannot
@@ -4026,7 +4183,7 @@ export declare class WorkspaceSnapshots extends WorkspaceSnapshots_base {
4026
4183
  * {@link WorkspaceDiscoveryOptions}, {@link LockfileReaderOptions} and
4027
4184
  * {@link WorkspaceCatalogsOptions} — and handed to each of them unchanged, so a
4028
4185
  * root-resolving option one service grows cannot silently stop at the
4029
- * composite. `cwd` and `stopAt` are re-declared here only to document them as
4186
+ * composite. `cwd`, `stopAt` and `markers` are re-declared here only to document them as
4030
4187
  * the one concern they are across the composite.
4031
4188
  *
4032
4189
  * @public
@@ -4057,6 +4214,20 @@ interface WorkspacesOptions extends WorkspaceDiscoveryOptions, LockfileReaderOpt
4057
4214
  * @defaultValue no ceiling — the ascent runs to the filesystem root.
4058
4215
  */
4059
4216
  readonly stopAt?: string | undefined;
4217
+ /**
4218
+ * The markers that count as a workspace root, forwarded to EVERY
4219
+ * root-resolving service the composite builds, exactly as `stopAt` is.
4220
+ *
4221
+ * @remarks
4222
+ * Pass `["pnpm-workspace.yaml"]` for a pnpm-only tool: a member package that
4223
+ * kept `package.json#workspaces` then reads as a member of the enclosing pnpm
4224
+ * workspace for discovery, the lockfile, the catalogs and `at(ref)` alike,
4225
+ * never as a root of its own for some of them. An empty list is a
4226
+ * **defect** at first use.
4227
+ *
4228
+ * @defaultValue every marker, `WORKSPACE_MARKERS`
4229
+ */
4230
+ readonly markers?: ReadonlyArray<WorkspaceMarker> | undefined;
4060
4231
  }
4061
4232
  /**
4062
4233
  * Options for the composites that additionally provide {@link WorkspaceSnapshots}
@@ -4300,7 +4471,10 @@ export declare class Workspaces {
4300
4471
  * project-local launcher has to run where the workspace is. `stopAt` caps
4301
4472
  * that ascent exactly as {@link WorkspacesOptions.stopAt} does, and a
4302
4473
  * ceiling with no root at or below it is the same `Option.none()` as no
4303
- * root at all.
4474
+ * root at all. `markers` filters the ascent exactly as
4475
+ * {@link WorkspacesOptions.markers} does, so a pnpm-only tool's launcher
4476
+ * runs from the pnpm workspace root, not from a member that kept
4477
+ * `package.json#workspaces`.
4304
4478
  *
4305
4479
  * An omitted `cwd` is `"."`, which `WorkspaceRoot.find` resolves through
4306
4480
  * the injected core `Path` on every call — this layer reads no `process`
@@ -4338,6 +4512,7 @@ export declare class Workspaces {
4338
4512
  static localExecLayer(options?: {
4339
4513
  readonly cwd?: string;
4340
4514
  readonly stopAt?: string | undefined;
4515
+ readonly markers?: ReadonlyArray<WorkspaceMarker> | undefined;
4341
4516
  }): Layer.Layer<LocalExec, never, PackageManagerDetector | WorkspaceRoot>;
4342
4517
  /**
4343
4518
  * Resolve every `catalog:` and `workspace:` specifier in one `Manifest`
@@ -4643,6 +4818,18 @@ interface FindWorkspaceRootSyncOptions extends WorkspacesSyncOptions {
4643
4818
  * itself a root still resolves, and one that is not returns `null`.
4644
4819
  */
4645
4820
  readonly stopAt?: string | undefined;
4821
+ /**
4822
+ * The markers that count, with the semantics of
4823
+ * `FindWorkspaceRootOptions.markers`: matched in their fixed priority order
4824
+ * whatever order they are listed in, every marker when omitted.
4825
+ *
4826
+ * @remarks
4827
+ * Pass `["pnpm-workspace.yaml"]` for a pnpm-only tool, which must not take a
4828
+ * member package that kept `package.json#workspaces` for the root. An empty
4829
+ * list throws: it is developer wiring, and a search that probes nothing
4830
+ * would answer `null` everywhere.
4831
+ */
4832
+ readonly markers?: ReadonlyArray<WorkspaceMarker> | undefined;
4646
4833
  }
4647
4834
  /**
4648
4835
  * The nearest workspace root at or above `cwd`, or `null`.
@@ -4660,7 +4847,9 @@ interface FindWorkspaceRootSyncOptions extends WorkspacesSyncOptions {
4660
4847
  * positional, so the function reads no ambient `process.cwd()`.
4661
4848
  *
4662
4849
  * Markers match the async service exactly: a `pnpm-workspace.yaml`, or a
4663
- * `package.json` carrying a `workspaces` field.
4850
+ * `package.json` carrying a `workspaces` field, narrowed by
4851
+ * `options.markers` ({@link FindWorkspaceRootSyncOptions.markers}). For the
4852
+ * matched file as well as the root, use {@link locateWorkspaceRootSync}.
4664
4853
  *
4665
4854
  * The ascent is unbounded unless `options.stopAt` names a ceiling
4666
4855
  * ({@link FindWorkspaceRootSyncOptions.stopAt}), with the Effect surface's
@@ -4694,6 +4883,33 @@ interface FindWorkspaceRootSyncOptions extends WorkspacesSyncOptions {
4694
4883
  * @public
4695
4884
  */
4696
4885
  export declare const findWorkspaceRootSync: (cwd: string, options: FindWorkspaceRootSyncOptions) => string | null;
4886
+ /**
4887
+ * The nearest workspace root at or above `cwd` and the marker file that made
4888
+ * it one, or `null`.
4889
+ *
4890
+ * @remarks
4891
+ * {@link findWorkspaceRootSync} with the match kept: the same ascent, the same
4892
+ * `stopAt` and `markers`, answering a `WorkspaceRootMatch` whose `path` is the
4893
+ * matched file. A tool that rewrites the marker (an `export` writing
4894
+ * `pnpm-workspace.yaml`) reads the path from here rather than re-deriving it.
4895
+ *
4896
+ * @param cwd - Where to start the ascent.
4897
+ * @param options - The consumer-supplied file and path operations, plus the
4898
+ * optional `stopAt` ceiling and `markers` filter.
4899
+ *
4900
+ * @example
4901
+ * ```ts
4902
+ * import { locateWorkspaceRootSync } from "@effected/workspaces";
4903
+ * import { nodeSyncOps } from "@effected/workspaces/node-sync";
4904
+ *
4905
+ * const match = locateWorkspaceRootSync(process.cwd(), { ...nodeSyncOps, markers: ["pnpm-workspace.yaml"] });
4906
+ * console.log(match?.path);
4907
+ * // => /repo/pnpm-workspace.yaml
4908
+ * ```
4909
+ *
4910
+ * @public
4911
+ */
4912
+ export declare const locateWorkspaceRootSync: (cwd: string, options: FindWorkspaceRootSyncOptions) => WorkspaceRootMatch | null;
4697
4913
  /**
4698
4914
  * Options for {@link getWorkspacePackagesSync}: the required consumer-supplied
4699
4915
  * operations plus the traversal bound.
package/index.js CHANGED
@@ -1,5 +1,6 @@
1
1
  import { PublishConfig, WorkspaceManifestError, WorkspacePackage } from "./WorkspacePackage.js";
2
- import { WORKSPACE_MARKERS, WorkspaceRoot, WorkspaceRootNotFoundError } from "./WorkspaceRoot.js";
2
+ import { WORKSPACE_MARKERS, WorkspaceMarker, WorkspaceRootMatch } from "./WorkspaceMarker.js";
3
+ import { WorkspaceRoot, WorkspaceRootNotFoundError } from "./WorkspaceRoot.js";
3
4
  import { PackageNotFoundError, WorkspaceDiscovery, WorkspaceDiscoveryError, WorkspaceInfo, WorkspacePatternError } from "./WorkspaceDiscovery.js";
4
5
  import { CyclicDependencyError, DependencyGraph } from "./DependencyGraph.js";
5
6
  import { ChangeDetectionError, ChangeDetectionOptions, ChangeDetector } from "./ChangeDetector.js";
@@ -16,6 +17,6 @@ import { CatalogSet, WorkspaceCatalogs } from "./WorkspaceCatalogs.js";
16
17
  import { PackageStateSnapshot, WorkspaceStateSnapshot } from "./WorkspaceStateSnapshot.js";
17
18
  import { WorkspaceSnapshots } from "./WorkspaceSnapshots.js";
18
19
  import { Workspaces } from "./Workspaces.js";
19
- import { detectPackageManagerSync, findWorkspaceRootSync, getWorkspacePackagesSync, localExecContextSync } from "./WorkspacesSync.js";
20
+ import { detectPackageManagerSync, findWorkspaceRootSync, getWorkspacePackagesSync, localExecContextSync, locateWorkspaceRootSync } from "./WorkspacesSync.js";
20
21
 
21
- export { CatalogSet, ChangeDetectionError, ChangeDetectionOptions, ChangeDetector, ConfigDependencyHooks, ConfigDependencySpec, CyclicDependencyError, DependencyGraph, Dependent, DetectedPackageManager, DuplicateCheck, DuplicateInstance, DuplicatedPackage, DuplicatedVersion, InvalidConfigDependencySpecError, LockfileReadError, LockfileReader, NoPeerDependencyRules, PackageManagerDetectionError, PackageManagerDetector, PackageManagerEvidence, PackageManagerName, PackageNotFoundError, PackageStateSnapshot, PeerCheck, PeerParent, PublishConfig, PublishTarget, PublishabilityDetector, ReleaseTag, TagStyle, TrackingTag, UnsatisfiedPeer, VersioningStrategy, VersioningStrategyType, WORKSPACE_MARKERS, WorkspaceCatalogs, WorkspaceDiscovery, WorkspaceDiscoveryError, WorkspaceInfo, WorkspaceManifestError, WorkspacePackage, WorkspacePatternError, WorkspaceRoot, WorkspaceRootNotFoundError, WorkspaceSnapshots, WorkspaceStateSnapshot, Workspaces, classifyTag, detectPackageManagerSync, findWorkspaceRootSync, getWorkspacePackagesSync, localExecContextSync };
22
+ export { CatalogSet, ChangeDetectionError, ChangeDetectionOptions, ChangeDetector, ConfigDependencyHooks, ConfigDependencySpec, CyclicDependencyError, DependencyGraph, Dependent, DetectedPackageManager, DuplicateCheck, DuplicateInstance, DuplicatedPackage, DuplicatedVersion, InvalidConfigDependencySpecError, LockfileReadError, LockfileReader, NoPeerDependencyRules, PackageManagerDetectionError, PackageManagerDetector, PackageManagerEvidence, PackageManagerName, PackageNotFoundError, PackageStateSnapshot, PeerCheck, PeerParent, PublishConfig, PublishTarget, PublishabilityDetector, ReleaseTag, TagStyle, TrackingTag, UnsatisfiedPeer, VersioningStrategy, VersioningStrategyType, WORKSPACE_MARKERS, WorkspaceCatalogs, WorkspaceDiscovery, WorkspaceDiscoveryError, WorkspaceInfo, WorkspaceManifestError, WorkspaceMarker, WorkspacePackage, WorkspacePatternError, WorkspaceRoot, WorkspaceRootMatch, WorkspaceRootNotFoundError, WorkspaceSnapshots, WorkspaceStateSnapshot, Workspaces, classifyTag, detectPackageManagerSync, findWorkspaceRootSync, getWorkspacePackagesSync, localExecContextSync, locateWorkspaceRootSync };
@@ -1,5 +1,21 @@
1
1
  // src/internal/layerRoot.ts
2
2
  /**
3
+ * The `find` options a layer's options name: `stopAt` and `markers`, each
4
+ * present only when set, or `undefined` when neither is.
5
+ *
6
+ * Shared with `Workspaces.localExecLayer`, which resolves its root the same
7
+ * way but reads a not-found as `Option.none()`.
8
+ */
9
+ const layerFindOptions = (options) => {
10
+ const stopAt = options?.stopAt;
11
+ const markers = options?.markers;
12
+ if (stopAt === void 0 && markers === void 0) return void 0;
13
+ return {
14
+ ...stopAt === void 0 ? {} : { stopAt },
15
+ ...markers === void 0 ? {} : { markers }
16
+ };
17
+ };
18
+ /**
3
19
  * Resolve the workspace root a layer's options name.
4
20
  *
5
21
  * An omitted `cwd` is passed to `find` as `"."`, which the live
@@ -11,9 +27,6 @@
11
27
  * an omitted `cwd` is a defect (core `Path.resolve` throws), not a typed
12
28
  * failure — pass `cwd` explicitly there.
13
29
  */
14
- const findLayerRoot = (roots, options) => {
15
- const stopAt = options?.stopAt;
16
- return roots.find(options?.cwd ?? ".", stopAt === void 0 ? void 0 : { stopAt });
17
- };
30
+ const findLayerRoot = (roots, options) => roots.find(options?.cwd ?? ".", layerFindOptions(options));
18
31
 
19
- export { findLayerRoot };
32
+ export { findLayerRoot, layerFindOptions };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@effected/workspaces",
3
- "version": "0.39.1",
3
+ "version": "0.40.1",
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.17.0",
55
- "@effected/git": "^0.26.0",
56
- "@effected/glob": "^0.15.0",
57
- "@effected/jsonc": "^0.20.1",
58
- "@effected/lockfiles": "^0.19.5",
59
- "@effected/npm": "^0.27.1",
60
- "@effected/package-json": "^0.26.1",
61
- "@effected/semver": "^0.18.0",
62
- "@effected/walker": "^0.21.0",
63
- "@effected/yaml": "^0.25.1",
54
+ "@effected/commands": "^0.18.0",
55
+ "@effected/git": "^0.28.0",
56
+ "@effected/glob": "^0.16.0",
57
+ "@effected/jsonc": "^0.21.0",
58
+ "@effected/lockfiles": "^0.20.0",
59
+ "@effected/npm": "^0.28.0",
60
+ "@effected/package-json": "^0.27.0",
61
+ "@effected/semver": "^0.19.0",
62
+ "@effected/walker": "^0.23.0",
63
+ "@effected/yaml": "^0.26.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",