@effected/workspaces 0.39.0 → 0.40.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/testing.d.ts CHANGED
@@ -5,6 +5,33 @@ import { WorkspaceManifest } from "@effected/lockfiles";
5
5
  import { Package } from "@effected/package-json";
6
6
  import { CommandOutput } from "@effected/commands";
7
7
  import { ChildProcess, ChildProcessSpawner } from "effect/process";
8
+ /**
9
+ * A file that marks a workspace root: a `pnpm-workspace.yaml`, or a
10
+ * `package.json` carrying a `workspaces` field.
11
+ *
12
+ * @public
13
+ */
14
+ export declare const WorkspaceMarker: Schema.Literals<readonly ["pnpm-workspace.yaml", "package.json"]>;
15
+ /**
16
+ * The decoded type of {@link (WorkspaceMarker:variable)}.
17
+ *
18
+ * @public
19
+ */
20
+ export type WorkspaceMarker = typeof WorkspaceMarker.Type;
21
+ declare const WorkspaceRootMatch_base: Schema.Class<WorkspaceRootMatch, Schema.Struct<{
22
+ /** The workspace root directory. */
23
+ readonly root: Schema.String;
24
+ /** Which marker matched. */
25
+ readonly marker: Schema.Literals<readonly ["pnpm-workspace.yaml", "package.json"]>;
26
+ /** The marker file's path: `root` joined with `marker`. */
27
+ readonly path: Schema.String;
28
+ }>, {}>;
29
+ /**
30
+ * A workspace root, and the marker file that made it one.
31
+ *
32
+ * @public
33
+ */
34
+ export declare class WorkspaceRootMatch extends WorkspaceRootMatch_base {}
8
35
  declare const PublishConfig_base: Schema.Class<PublishConfig, Schema.Struct<{
9
36
  /** Scoped-package visibility. Its presence overrides `private`. */
10
37
  readonly access: Schema.optionalKey<Schema.Literals<readonly ["public", "restricted"]>>;
@@ -271,6 +298,19 @@ interface FindWorkspaceRootOptions {
271
298
  * @defaultValue 256
272
299
  */
273
300
  readonly maxDepth?: number;
301
+ /**
302
+ * The markers that count, matched in their fixed priority order
303
+ * (`pnpm-workspace.yaml` first) whatever order they are listed in.
304
+ *
305
+ * @remarks
306
+ * Pass `["pnpm-workspace.yaml"]` for a pnpm-only tool: pnpm ignores
307
+ * `package.json#workspaces`, so a member package that kept the field (common
308
+ * after a yarn migration) must not read as the root. An empty list is a
309
+ * **defect**, like a bad `maxDepth`.
310
+ *
311
+ * @defaultValue every marker, `WORKSPACE_MARKERS`
312
+ */
313
+ readonly markers?: ReadonlyArray<WorkspaceMarker>;
274
314
  }
275
315
  declare const WorkspaceRootNotFoundError_base: Schema.Class<WorkspaceRootNotFoundError, Schema.TaggedStruct<"WorkspaceRootNotFoundError", {
276
316
  /** The directory the ascent started from. */
@@ -357,6 +397,42 @@ declare const WorkspaceRoot_base: Context.ServiceClass<WorkspaceRoot, "@effected
357
397
  export declare class WorkspaceRoot extends WorkspaceRoot_base {
358
398
  /** Builds the service over core `FileSystem` and `Path`. */
359
399
  static readonly make: Effect.Effect<WorkspaceRootShape, never, FileSystem.FileSystem | Path.Path>;
400
+ /**
401
+ * The nearest workspace root at or above `cwd` and the marker file that made
402
+ * it one — the Effect form of `locateWorkspaceRootSync`.
403
+ *
404
+ * @remarks
405
+ * The same ascent as the service's `find`, with the same `stopAt`,
406
+ * `maxDepth` and `markers`, answering a {@link WorkspaceRootMatch} whose
407
+ * `path` is the matched file. A tool that rewrites the marker (an `export`
408
+ * writing `pnpm-workspace.yaml`) reads the path from here rather than
409
+ * re-deriving it from the root.
410
+ *
411
+ * It is a static over core `FileSystem` and `Path` in `R`, not a member of
412
+ * {@link WorkspaceRootShape}: a new member would break every hand-written
413
+ * `Layer.succeed(WorkspaceRoot, { find })` double. The consequence is that
414
+ * it never consults a provided `WorkspaceRoot` — a
415
+ * {@link WorkspaceRoot.layerTest} double does not answer it; a test gives it
416
+ * a filesystem (an `@effected/memfs` volume) instead. On the same inputs it
417
+ * agrees with `locateWorkspaceRootSync`, which answers `null` where this
418
+ * fails {@link WorkspaceRootNotFoundError}.
419
+ *
420
+ * @param cwd - The directory to start the ascent from; resolved to an
421
+ * absolute path first.
422
+ * @param options - The ascent bounds and marker filter of `find`.
423
+ *
424
+ * @example
425
+ * ```ts
426
+ * import { WorkspaceRoot } from "@effected/workspaces";
427
+ * import { Effect } from "effect";
428
+ *
429
+ * const program = Effect.gen(function* () {
430
+ * const match = yield* WorkspaceRoot.locate("/repo/packages/a", { markers: ["pnpm-workspace.yaml"] });
431
+ * return match.path; // "/repo/pnpm-workspace.yaml"
432
+ * });
433
+ * ```
434
+ */
435
+ static readonly locate: (cwd: string, options?: FindWorkspaceRootOptions) => Effect.Effect<WorkspaceRootMatch, WorkspaceRootNotFoundError, FileSystem.FileSystem | Path.Path>;
360
436
  /** The live layer. */
361
437
  static readonly layer: Layer.Layer<WorkspaceRoot, never, FileSystem.FileSystem | Path.Path>;
362
438
  /**
@@ -379,13 +455,21 @@ export declare class WorkspaceRoot extends WorkspaceRoot_base {
379
455
  * `Path.layer` internally, so the requirement never surfaces at their call
380
456
  * site.
381
457
  *
458
+ * `markers` is honoured the same way: the double's root is marked by
459
+ * `marker` (`"pnpm-workspace.yaml"` unless given), so a `find` whose
460
+ * `markers` leave that marker out fails as the live service would, and a
461
+ * `find` with an empty list dies.
462
+ *
382
463
  * `maxDepth` is deliberately NOT modelled: the double does not walk, so it has
383
464
  * no depth to cap, and pretending otherwise would encode a fiction. A suite
384
465
  * exercising the depth guard wants the live service over a fixture tree.
385
466
  *
386
467
  * @param root - The root every unbounded `find` resolves to.
468
+ * @param options - `marker`: the marker the double's root carries.
387
469
  */
388
- static readonly makeTest: (root: string) => Effect.Effect<WorkspaceRootShape, never, Path.Path>;
470
+ static readonly makeTest: (root: string, options?: {
471
+ readonly marker?: WorkspaceMarker | undefined;
472
+ }) => Effect.Effect<WorkspaceRootShape, never, Path.Path>;
389
473
  /**
390
474
  * The test layer: {@link WorkspaceRoot.makeTest} with `Path.layer` provided.
391
475
  *
@@ -415,7 +499,9 @@ export declare class WorkspaceRoot extends WorkspaceRoot_base {
415
499
  * // program.pipe(Effect.provide(TestRoot), Effect.provide(TestDiscovery))
416
500
  * ```
417
501
  */
418
- static readonly layerTest: (root: string) => Layer.Layer<WorkspaceRoot>;
502
+ static readonly layerTest: (root: string, options?: {
503
+ readonly marker?: WorkspaceMarker | undefined;
504
+ }) => Layer.Layer<WorkspaceRoot>;
419
505
  }
420
506
  declare const WorkspaceDiscoveryError_base: Schema.Class<WorkspaceDiscoveryError, Schema.TaggedStruct<"WorkspaceDiscoveryError", {
421
507
  /** The workspace root discovery was running against. */
@@ -557,6 +643,26 @@ interface WorkspaceDiscoveryOptions {
557
643
  * @defaultValue no ceiling — the ascent runs to the filesystem root.
558
644
  */
559
645
  readonly stopAt?: string | undefined;
646
+ /**
647
+ * The markers that count as a workspace root, passed straight through to
648
+ * the `markers` of {@link WorkspaceRoot}'s `find`.
649
+ *
650
+ * @remarks
651
+ * Pass `["pnpm-workspace.yaml"]` for a pnpm-only tool: pnpm ignores
652
+ * `package.json#workspaces`, so a member package that kept the field
653
+ * (common after a yarn migration) must not read as the root. An empty
654
+ * list is a **defect** at first use, as it is for `find`.
655
+ *
656
+ * Unlike `stopAt`, it applies to the per-call `infoIn`, `listPackagesIn`
657
+ * and `refreshIn` too: which file marks a root is a property of the
658
+ * tool, not of the directory it starts from. `LockfileReader`,
659
+ * `WorkspaceCatalogs` and `WorkspaceSnapshots` each take the same
660
+ * option; the `Workspaces.*` composites forward one `markers` to all of
661
+ * them, so no service stops at a root another passed.
662
+ *
663
+ * @defaultValue every marker, `WORKSPACE_MARKERS`
664
+ */
665
+ readonly markers?: ReadonlyArray<WorkspaceMarker> | undefined;
560
666
  /** Descent cap for segment-crossing patterns. Defaults to 32. */
561
667
  readonly maxDepth?: number;
562
668
  }
@@ -1954,6 +2060,15 @@ export declare class PackedInstall {
1954
2060
  * trailing `*` (so `"node:*"` and `"@effect/platform*"` are prefixes).
1955
2061
  * `{ forbidTokens }` forbids each entry's exact text wherever it appears in
1956
2062
  * code (see {@link SourceBoundary.check} for how a token is matched).
2063
+ * `{ forbidImportedNames: { from, names } }` forbids importing any of `names`
2064
+ * from the module `from` while leaving its other exports free: a named import
2065
+ * (aliased or not, `type`-only included, and a string-literal name such as
2066
+ * `import { "App" as A }`), a default import (named `"default"`), a named
2067
+ * re-export (`export { App } from ...`), an `export * from` of the module,
2068
+ * and a member access on a namespace binding (`import * as m from ...` or the
2069
+ * TypeScript `import m = require(...)`, then `m.App`). `from` must equal the specifier
2070
+ * exactly; a subpath is a different module. See {@link SourceBoundary}'s
2071
+ * remarks for what this lexer cannot see.
1957
2072
  *
1958
2073
  * To confine a token to named files rather than forbid it everywhere, forbid
1959
2074
  * it and waive the rule for those files through
@@ -1977,7 +2092,21 @@ type BoundaryRule = "process" | "node:process" | "stdout-write" | "console" | "c
1977
2092
  readonly forbidImports: ReadonlyArray<string>;
1978
2093
  } | {
1979
2094
  readonly forbidTokens: ReadonlyArray<string>;
2095
+ } | {
2096
+ readonly forbidImportedNames: ForbiddenImportedNames;
1980
2097
  };
2098
+ /**
2099
+ * The names a `{ forbidImportedNames }` rule forbids, and the module they must
2100
+ * not be imported from.
2101
+ *
2102
+ * @public
2103
+ */
2104
+ interface ForbiddenImportedNames {
2105
+ /** The module specifier, matched exactly. */
2106
+ readonly from: string;
2107
+ /** The export names that must not be imported from it. `"default"` names the default export. */
2108
+ readonly names: ReadonlyArray<string>;
2109
+ }
1981
2110
  /**
1982
2111
  * Options for the `process` rule.
1983
2112
  *
@@ -2016,8 +2145,12 @@ declare const Offence_base: Schema.Class<Offence, Schema.Struct<{
2016
2145
  /** The 1-based column, in UTF-16 code units. */
2017
2146
  readonly column: Schema.Number;
2018
2147
  /** The rule broken. */
2019
- readonly rule: Schema.Literals<readonly ["process", "node:process", "stdout-write", "console", "console-stdout", "forbidImports", "forbidTokens"]>;
2020
- /** What matched: the identifier, the call, the import specifier, or the token. */
2148
+ readonly rule: Schema.Literals<readonly ["process", "node:process", "stdout-write", "console", "console-stdout", "forbidImports", "forbidTokens", "forbidImportedNames"]>;
2149
+ /**
2150
+ * What matched: the identifier, the call, the import specifier, the token,
2151
+ * or, for `forbidImportedNames`, `<name> from <specifier>` (`*` for an
2152
+ * `export * from`).
2153
+ */
2021
2154
  readonly detail: Schema.String;
2022
2155
  }>, {}>;
2023
2156
  /**
@@ -2031,8 +2164,9 @@ export declare class Offence extends Offence_base {
2031
2164
  }
2032
2165
  /**
2033
2166
  * The rule an {@link Offence} names: every string {@link BoundaryRule}, plus
2034
- * `"forbidImports"` for any `{ forbidImports }` rule and `"forbidTokens"` for
2035
- * any `{ forbidTokens }` rule. These are the keys of
2167
+ * `"forbidImports"` for any `{ forbidImports }` rule, `"forbidTokens"` for
2168
+ * any `{ forbidTokens }` rule and `"forbidImportedNames"` for any
2169
+ * `{ forbidImportedNames }` rule. These are the keys of
2036
2170
  * {@link ScanOptions.allowRules}.
2037
2171
  *
2038
2172
  * @public
@@ -2078,8 +2212,9 @@ interface ScanOptions extends ReferenceOptions {
2078
2212
  * rule. A matching file is still checked against every other rule, and
2079
2213
  * each offence a glob waives is reported in `SourceScan.waived`
2080
2214
  * rather than dropped. The `"forbidImports"` key covers every
2081
- * `{ forbidImports }` rule, and the `"forbidTokens"` key every
2082
- * `{ forbidTokens }` rule, which is how a token is confined to named files.
2215
+ * `{ forbidImports }` rule, the `"forbidTokens"` key every
2216
+ * `{ forbidTokens }` rule, which is how a token is confined to named files,
2217
+ * and the `"forbidImportedNames"` key every `{ forbidImportedNames }` rule.
2083
2218
  * A file `allow` matches is exempt from every rule, so nothing in it is
2084
2219
  * waived.
2085
2220
  */
@@ -2128,7 +2263,18 @@ interface ScanOptions extends ReferenceOptions {
2128
2263
  * both words);
2129
2264
  *
2130
2265
  * - `forbidImports: ["node:*"]` does not catch a bare built-in such as
2131
- * `"fs"` (see {@link BoundaryRule}).
2266
+ * `"fs"` (see {@link BoundaryRule});
2267
+ *
2268
+ * - `{ forbidImportedNames }` reads static `import` and `export ... from`
2269
+ * clauses and member accesses on a namespace binding (an `import * as m` or
2270
+ * an `import m = require(...)`). It does not see a
2271
+ * name taken from a dynamic `import()` or a plain `require()` call
2272
+ * (`const { App } = await import(...)`), a computed member (`m["App"]`), a
2273
+ * string-literal name written with an escape (`"\u0041pp"` reads as its
2274
+ * escaped text, not `App`), a
2275
+ * destructuring of a namespace binding (`const { App } = m`), or a
2276
+ * namespace binding passed on whole. Without scope analysis, a local that
2277
+ * shadows the namespace binding's name is read as the binding.
2132
2278
  *
2133
2279
  * Assert on {@link SourceBoundary.verifyFixtures} beside your own scan: it
2134
2280
  * proves the scanner you are trusting still flags what it must and spares
@@ -2297,5 +2443,5 @@ export declare class WorkspaceLayering {
2297
2443
  /** Discover the workspace and check it against `policy`. */
2298
2444
  static readonly checkWorkspace: (policy: LayerPolicy) => Effect.Effect<LayeringReport, WorkspaceDiscoveryFailure, WorkspaceDiscovery>;
2299
2445
  }
2300
- 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 };
2446
+ export type { BinCommandOptions, BinProvenance, BoundaryFixture, BoundaryRule, DependencyDiff, FindWorkspaceRootOptions, ForbiddenImportedNames, LayeringGraph, OffenceRule, PackSource, PackedInstallBudget, PackedInstallClosureOptions, PackedInstallGate, PackedInstallOptions, PackedInstallPreflight, PackedInstallPreflightOptions, ReachabilityOptions, ReferenceOptions, RunBinOptions, ScanOptions, UndeclaredOptions, WorkspaceDiscoveryFailure, WorkspaceDiscoveryOptions, WorkspaceDiscoveryShape, WorkspaceLookupFailure, WorkspaceRootShape };
2301
2447
  //# sourceMappingURL=testing.d.ts.map
package/testing.js CHANGED
@@ -1,4 +1,5 @@
1
1
  import { PublishConfig, WorkspaceManifestError, WorkspacePackage } from "./WorkspacePackage.js";
2
+ import { WorkspaceMarker, WorkspaceRootMatch } from "./WorkspaceMarker.js";
2
3
  import { WorkspaceRoot, WorkspaceRootNotFoundError } from "./WorkspaceRoot.js";
3
4
  import { PackageNotFoundError, WorkspaceDiscovery, WorkspaceDiscoveryError, WorkspaceInfo, WorkspacePatternError } from "./WorkspaceDiscovery.js";
4
5
  import { PackageManagerName } from "./PackageManagerName.js";
@@ -8,4 +9,4 @@ import { LayerPolicy, LayerPolicyError } from "./LayerPolicy.js";
8
9
  import { InstalledConsumer, PackedInstall, PackedInstallError, PackedInstallResult } from "./PackedInstall.js";
9
10
  import { LayerEdge, LayeringReport, WorkspaceLayering } from "./WorkspaceLayering.js";
10
11
 
11
- export { EntryNotFoundError, ImportGraph, InstalledConsumer, LayerEdge, LayerPolicy, LayerPolicyError, LayeringReport, NoEntriesError, Offence, PackageManagerName, PackageNotFoundError, PackedInstall, PackedInstallError, PackedInstallResult, PublishConfig, ReachOffence, ReachabilityScan, SourceBoundary, SourceScan, UndeclaredImport, UndeclaredScan, UnresolvedImport, WorkspaceDiscovery, WorkspaceDiscoveryError, WorkspaceInfo, WorkspaceLayering, WorkspaceManifestError, WorkspacePackage, WorkspacePatternError, WorkspaceRoot, WorkspaceRootNotFoundError };
12
+ export { EntryNotFoundError, ImportGraph, InstalledConsumer, LayerEdge, LayerPolicy, LayerPolicyError, LayeringReport, NoEntriesError, Offence, PackageManagerName, PackageNotFoundError, PackedInstall, PackedInstallError, PackedInstallResult, PublishConfig, ReachOffence, ReachabilityScan, SourceBoundary, SourceScan, UndeclaredImport, UndeclaredScan, UnresolvedImport, WorkspaceDiscovery, WorkspaceDiscoveryError, WorkspaceInfo, WorkspaceLayering, WorkspaceManifestError, WorkspaceMarker, WorkspacePackage, WorkspacePatternError, WorkspaceRoot, WorkspaceRootMatch, WorkspaceRootNotFoundError };