@effected/workspaces 0.15.1 → 0.17.0

package/README.md

@@ -218,6 +218,25 @@ const packages = root === null ? [] : getWorkspacePackagesSync(root, options);
 // packages: the discovered workspace packages, empty when there is no root
 ```
 
+Those four operations are the whole requirement. A fifth, `readDirectoryWithTypes`, is optional: supply it and package enumeration reads a directory's entries and their types in one call instead of a `readDirectory` plus an `isDirectory` per entry, which on a large workspace is a syscall per file. `nodeFileSystem` already implements it over `readdirSync(p, { withFileTypes: true })`, so the `node-sync` bindings get the fast path for free. Omit it and enumeration falls back to the four required operations with identical results — a cost optimization, never a behavior switch.
+
+Each entry reports `name`, `isDirectory` and `isSymbolicLink` as a `SyncDirectoryEntry`, which Node's `Dirent` satisfies once its predicate methods are called. The link flag is load-bearing: a `Dirent` describes the entry itself, so a symlink pointing at a directory reports `isDirectory: false`, while the `stat`-based path resolves the link and calls the same entry a directory. Enumeration re-resolves links through `isDirectory` rather than trusting the flag, which is what keeps a workspace with symlinked packages discovered identically on both paths.
+
+```ts
+import { readdirSync } from "node:fs";
+import type { SyncDirectoryEntry } from "@effected/workspaces";
+
+const readDirectoryWithTypes = (p: string): ReadonlyArray<SyncDirectoryEntry> =>
+  readdirSync(p, { withFileTypes: true }).map((entry) => ({
+    name: entry.name,
+    isDirectory: entry.isDirectory(),
+    isSymbolicLink: entry.isSymbolicLink(),
+  }));
+// pass alongside the four required operations: { ...options.fileSystem, readDirectoryWithTypes }
+```
+
+For a test fake, `@effected/memfs`' `MemoryFileSystem.syncFileSystem(volume)` satisfies `SyncFileSystem` structurally — neither package imports the other — so a config-time discovery path can be exercised against a virtual workspace with nothing on disk.
+
 Windows correctness is therefore the operations you pass, and nothing else. Both entry points drive one traversal state machine (the same dequeue order, depth rule, visit budget and `node_modules` prune), so the sync and Effect surfaces can never disagree about what a pattern means. The one deliberate difference is at a bound: the Effect enumerator fails typed, the sync one truncates. Prefer the Effect API everywhere you can run one.
 
 ## Error handling
@@ -286,7 +305,7 @@ A name miss in the derived `getPackage` fails with the service's own typed `Pack
 - `ReleaseTag` / `TrackingTag` — release-tag formatting (`ReleaseTag.single` / `.scoped`, strict SemVer by default with no `v` prefix) and the floating major/minor alias derivation GitHub Actions-style consumers expect (`v1`, `v1.2`), plus `classifyTag` to tell a release tag from a tracking alias.
 - `VersioningStrategy` — classify a workspace as `single`, `fixed-group` or `independent` from package names and fixed groups, or detect it live against `PublishabilityDetector`, and produce the release tags for a batch with `tagsFor`.
 - `findWorkspaceRootSync` / `getWorkspacePackagesSync` — the synchronous escape hatch for config-time callers that cannot await, over file and path operations you supply.
-- `@effected/workspaces/node-sync` — a second entry point holding the Node bindings for those operations (`nodeFileSystem`, `nodePath` and the `nodeSyncOps` bag), kept off the main entry so `node:*` never reaches a consumer that supplies its own.
+- `@effected/workspaces/node-sync` — a second entry point holding the Node bindings for those operations (`nodeFileSystem`, `nodePath` and the `nodeSyncOps` bag), kept off the main entry so `node:*` never reaches a consumer that supplies its own. `nodeFileSystem` implements the optional `readDirectoryWithTypes` fast path, so the bindings enumerate a workspace in one `readdirSync` per directory.
 
 ## License
 

package/WorkspaceCatalogs.js

@@ -444,7 +444,8 @@ var WorkspaceCatalogs = class WorkspaceCatalogs extends Context.Service()("@effe
 			}),
 			importerVersions: Effect.fn("WorkspaceCatalogs.importerVersions")(function* () {
 				return (yield* memo).importerVersions;
-			})
+			}),
+			refresh: () => invalidate
 		};
 	});
 	/**
@@ -509,6 +510,11 @@ var WorkspaceCatalogs = class WorkspaceCatalogs extends Context.Service()("@effe
 	* the importer index from the lockfile's importer blocks — neither is in a
 	* `CatalogSet`) and always die unless stubbed.
 	*
+	* `refresh` defaults to `Effect.void` honestly: the double holds no memo,
+	* so "drop the memoized assembly" is genuinely a no-op — the stubs answer
+	* fresh on every call already. This mirrors `WorkspaceDiscovery.makeTest`'s
+	* `refresh`.
+	*
 	* @example
 	* ```ts
 	* import { CatalogSet, WorkspaceCatalogs } from "@effected/workspaces";
@@ -528,6 +534,7 @@ var WorkspaceCatalogs = class WorkspaceCatalogs extends Context.Service()("@effe
 			peerDependencyRules: () => unstubbed("peerDependencyRules"),
 			releaseAgeGate: () => unstubbed("releaseAgeGate"),
 			importerVersions: () => unstubbed("importerVersions"),
+			refresh: () => Effect.void,
 			...overrides
 		};
 	};

package/WorkspacesSync.js

@@ -35,6 +35,37 @@ const isDirectory = (fileSystem, dir) => {
 		return false;
 	}
 };
+/**
+* The entries of `absoluteDir`, each carrying whether it is a directory, or
+* `undefined` when the directory could not be read at all (the degraded-skip
+* case). Uses {@link SyncFileSystem.readDirectoryWithTypes} when the consumer
+* supplied it and the four-operation fallback otherwise — the two agree by
+* construction, including on symbolic links, which are always re-resolved
+* through `isDirectory` because a `Dirent` describes the link and not its
+* target.
+*/
+const readResolvedEntries = (options, absoluteDir) => {
+	const { fileSystem, path } = options;
+	const withTypes = fileSystem.readDirectoryWithTypes;
+	if (withTypes !== void 0) try {
+		return withTypes(absoluteDir).map((entry) => ({
+			name: entry.name,
+			directory: entry.isSymbolicLink ? isDirectory(fileSystem, path.join(absoluteDir, entry.name)) : entry.isDirectory
+		}));
+	} catch {
+		return;
+	}
+	let names;
+	try {
+		names = fileSystem.readDirectory(absoluteDir);
+	} catch {
+		return;
+	}
+	return names.map((name) => ({
+		name,
+		directory: isDirectory(fileSystem, path.join(absoluteDir, name))
+	}));
+};
 /** Whether `dir` holds a `package.json`. */
 const isPackage = (options, dir) => options.fileSystem.exists(options.path.join(dir, "package.json"));
 /**
@@ -212,17 +243,13 @@ const getWorkspacePackagesSync = (root, options) => {
 		let stopped = false;
 		for (let current = traversal.next(); current !== void 0 && !stopped; current = traversal.next()) {
 			if (traversal.charge() !== void 0) break;
-			let entries = [];
-			try {
-				entries = fileSystem.readDirectory(current.absolute);
-			} catch {
-				continue;
-			}
+			const entries = readResolvedEntries(options, current.absolute);
+			if (entries === void 0) continue;
 			for (const entry of entries) {
-				if (isPruned(entry)) continue;
-				const relative = joinRelative(current.relative, entry);
-				const absolute = path.join(current.absolute, entry);
-				if (!isDirectory(fileSystem, absolute)) continue;
+				if (isPruned(entry.name)) continue;
+				const relative = joinRelative(current.relative, entry.name);
+				const absolute = path.join(current.absolute, entry.name);
+				if (!entry.directory) continue;
 				if (wildcard.crossesSegments && !traversal.admits(current)) {
 					stopped = true;
 					break;

package/index.d.ts

@@ -2449,6 +2449,26 @@ interface WorkspaceCatalogsShape {
    * nothing rather than failing.
    */
   readonly importerVersions: () => Effect.Effect<ImporterVersions, CatalogAssemblyFailure>;
+  /**
+   * Discard the memoized assembly so the **next** read re-assembles — the same
+   * single read and hook replay as the first, over the workspace as it stands
+   * then.
+   *
+   * @remarks
+   * The explicit memoization boundary for a tool that **mutates the workspace
+   * mid-run** — installs, bumps a config dependency, regenerates the lockfile.
+   * Release-age gating wants the before-state, a post-install peer check the
+   * after-state, and one infinite memo cannot serve both without this call in
+   * between; without it, `peerDependencyRules` keeps answering from the
+   * pre-mutation hook replay and the checker reports findings the new rules
+   * suppress.
+   *
+   * Unconditional and infallible: the memo is already success-only (a failed
+   * or interrupted assembly retries by itself), so `refresh` exists solely to
+   * discard a *successful* assembly that mutation has made stale. Calling it
+   * before any read is harmless.
+   */
+  readonly refresh: () => Effect.Effect<void>;
 }
 /**
  * Options for the {@link WorkspaceCatalogs} layer.
@@ -2554,6 +2574,11 @@ declare class WorkspaceCatalogs extends WorkspaceCatalogs_base {
    * the importer index from the lockfile's importer blocks — neither is in a
    * `CatalogSet`) and always die unless stubbed.
    *
+   * `refresh` defaults to `Effect.void` honestly: the double holds no memo,
+   * so "drop the memoized assembly" is genuinely a no-op — the stubs answer
+   * fresh on every call already. This mirrors `WorkspaceDiscovery.makeTest`'s
+   * `refresh`.
+   *
    * @example
    * ```ts
    * import { CatalogSet, WorkspaceCatalogs } from "@effected/workspaces";
@@ -3227,6 +3252,53 @@ interface SyncFileSystem {
   readonly readDirectory: (path: string) => ReadonlyArray<string>;
   /** Whether `path` is a directory. May throw; a throw reads as `false`. */
   readonly isDirectory: (path: string) => boolean;
+  /**
+   * Optional fast path: the entries inside `path` with their types already
+   * known, in ONE call.
+   *
+   * @remarks
+   * Package enumeration otherwise costs a `readDirectory` plus one
+   * `isDirectory` per entry — the readdir-then-stat-per-entry shape, which on
+   * a large workspace is a syscall per file. Supplying this collapses that to
+   * a single `readdirSync(path, { withFileTypes: true })`; `nodeFileSystem`
+   * does. Omit it and enumeration falls back to the four required operations
+   * with identical results, so this is purely a cost optimization and never a
+   * behavior switch.
+   *
+   * May throw; a throw skips the directory, exactly like `readDirectory`.
+   */
+  readonly readDirectoryWithTypes?: ((path: string) => ReadonlyArray<SyncDirectoryEntry>) | undefined;
+}
+/**
+ * One directory entry with its type resolved, as the optional
+ * {@link SyncFileSystem.readDirectoryWithTypes} fast path reports it. Node's
+ * `Dirent` satisfies it after mapping its predicate methods to booleans.
+ *
+ * @remarks
+ * `isSymbolicLink` is not decoration. A `Dirent` describes the entry ITSELF, so
+ * a symbolic link pointing at a directory reports `isDirectory: false` — while
+ * the `stat`-based slow path, which resolves the link, calls the same entry a
+ * directory. Enumeration therefore re-resolves links through `isDirectory`
+ * rather than trusting `isDirectory` on a link, which is what keeps the fast
+ * and slow paths in agreement on a workspace whose packages are symlinked.
+ *
+ * Which behavior is *correct* is domain-dependent, so the flag is reported
+ * rather than resolved away. Enumeration follows links because a symlinked
+ * package is still a package. A test-file discovery walk usually must NOT: in a
+ * pnpm workspace `node_modules` is a farm of links into the content-addressed
+ * store, and following them walks the whole store or hits a cycle. A consumer
+ * building its own walker on this shape wants `isDirectory` verbatim — there,
+ * not following is the requirement, not the hazard.
+ *
+ * @public
+ */
+interface SyncDirectoryEntry {
+  /** The entry's own name, not a path. */
+  readonly name: string;
+  /** Whether the entry itself is a directory. `false` for a symbolic link, even one targeting a directory. */
+  readonly isDirectory: boolean;
+  /** Whether the entry itself is a symbolic link. */
+  readonly isSymbolicLink: boolean;
 }
 /**
  * The synchronous path operations the sync entry points need, supplied by the
@@ -3382,5 +3454,5 @@ interface GetWorkspacePackagesSyncOptions extends WorkspacesSyncOptions {
  */
 declare const getWorkspacePackagesSync: (root: string, options: GetWorkspacePackagesSyncOptions) => ReadonlyArray<WorkspacePackage>;
 //#endregion
-export { type CatalogAssemblyFailure, CatalogSet, ChangeDetectionError, type ChangeDetectionFailure, ChangeDetectionOptions, ChangeDetector, type ChangeDetectorShape, type ClassifyOptions, ConfigDependencyHooks, type ConfigDependencyHooksShape, CyclicDependencyError, type DependencyDiff, DependencyGraph, DetectedPackageManager, type FindWorkspaceRootOptions, type GetWorkspacePackagesSyncOptions, type HookInjection, type ImporterVersions, LockfileReadError, type LockfileReadFailure, LockfileReader, type LockfileReaderOptions, type LockfileReaderShape, NoPeerDependencyRules, PackageManagerDetectionError, type PackageManagerDetectionFailure, PackageManagerDetector, type PackageManagerDetectorShape, PackageManagerEvidence, PackageManagerName, PackageNotFoundError, type PackageRelease, PackageStateSnapshot, PeerCheck, type PeerCheckOptions, type PeerDependencyRules, PeerParent, PublishConfig, PublishTarget, PublishabilityDetector, type PublishabilityDetectorShape, ReleaseTag, type SyncFileSystem, type SyncPath, type TagClassification, type TagFormatOptions, TagStyle, TrackingTag, type TrackingTagOptions, UnsatisfiedPeer, type UnverifiedReason, type VersioningDetectOptions, VersioningStrategy, VersioningStrategyType, WORKSPACE_MARKERS, WorkspaceCatalogs, type WorkspaceCatalogsOptions, type WorkspaceCatalogsShape, WorkspaceDiscovery, WorkspaceDiscoveryError, type WorkspaceDiscoveryFailure, type WorkspaceDiscoveryOptions, type WorkspaceDiscoveryShape, WorkspaceInfo, type WorkspaceLookupFailure, WorkspaceManifestError, WorkspacePackage, WorkspacePatternError, WorkspaceRoot, WorkspaceRootNotFoundError, type WorkspaceRootShape, type WorkspaceSnapshotAtFailure, type WorkspaceSnapshotWorktreeFailure, WorkspaceSnapshots, type WorkspaceSnapshotsOptions, type WorkspaceSnapshotsShape, WorkspaceStateSnapshot, Workspaces, type WorkspacesOptions, type WorkspacesServices, type WorkspacesSyncOptions, classifyTag, findWorkspaceRootSync, getWorkspacePackagesSync };
+export { type CatalogAssemblyFailure, CatalogSet, ChangeDetectionError, type ChangeDetectionFailure, ChangeDetectionOptions, ChangeDetector, type ChangeDetectorShape, type ClassifyOptions, ConfigDependencyHooks, type ConfigDependencyHooksShape, CyclicDependencyError, type DependencyDiff, DependencyGraph, DetectedPackageManager, type FindWorkspaceRootOptions, type GetWorkspacePackagesSyncOptions, type HookInjection, type ImporterVersions, LockfileReadError, type LockfileReadFailure, LockfileReader, type LockfileReaderOptions, type LockfileReaderShape, NoPeerDependencyRules, PackageManagerDetectionError, type PackageManagerDetectionFailure, PackageManagerDetector, type PackageManagerDetectorShape, PackageManagerEvidence, PackageManagerName, PackageNotFoundError, type PackageRelease, PackageStateSnapshot, PeerCheck, type PeerCheckOptions, type PeerDependencyRules, PeerParent, PublishConfig, PublishTarget, PublishabilityDetector, type PublishabilityDetectorShape, ReleaseTag, type SyncDirectoryEntry, type SyncFileSystem, type SyncPath, type TagClassification, type TagFormatOptions, TagStyle, TrackingTag, type TrackingTagOptions, UnsatisfiedPeer, type UnverifiedReason, type VersioningDetectOptions, VersioningStrategy, VersioningStrategyType, WORKSPACE_MARKERS, WorkspaceCatalogs, type WorkspaceCatalogsOptions, type WorkspaceCatalogsShape, WorkspaceDiscovery, WorkspaceDiscoveryError, type WorkspaceDiscoveryFailure, type WorkspaceDiscoveryOptions, type WorkspaceDiscoveryShape, WorkspaceInfo, type WorkspaceLookupFailure, WorkspaceManifestError, WorkspacePackage, WorkspacePatternError, WorkspaceRoot, WorkspaceRootNotFoundError, type WorkspaceRootShape, type WorkspaceSnapshotAtFailure, type WorkspaceSnapshotWorktreeFailure, WorkspaceSnapshots, type WorkspaceSnapshotsOptions, type WorkspaceSnapshotsShape, WorkspaceStateSnapshot, Workspaces, type WorkspacesOptions, type WorkspacesServices, type WorkspacesSyncOptions, classifyTag, findWorkspaceRootSync, getWorkspacePackagesSync };
 //# sourceMappingURL=index.d.ts.map

package/node-sync.d.ts

@@ -36,6 +36,53 @@ interface SyncFileSystem {
   readonly readDirectory: (path: string) => ReadonlyArray<string>;
   /** Whether `path` is a directory. May throw; a throw reads as `false`. */
   readonly isDirectory: (path: string) => boolean;
+  /**
+   * Optional fast path: the entries inside `path` with their types already
+   * known, in ONE call.
+   *
+   * @remarks
+   * Package enumeration otherwise costs a `readDirectory` plus one
+   * `isDirectory` per entry — the readdir-then-stat-per-entry shape, which on
+   * a large workspace is a syscall per file. Supplying this collapses that to
+   * a single `readdirSync(path, { withFileTypes: true })`; `nodeFileSystem`
+   * does. Omit it and enumeration falls back to the four required operations
+   * with identical results, so this is purely a cost optimization and never a
+   * behavior switch.
+   *
+   * May throw; a throw skips the directory, exactly like `readDirectory`.
+   */
+  readonly readDirectoryWithTypes?: ((path: string) => ReadonlyArray<SyncDirectoryEntry>) | undefined;
+}
+/**
+ * One directory entry with its type resolved, as the optional
+ * {@link SyncFileSystem.readDirectoryWithTypes} fast path reports it. Node's
+ * `Dirent` satisfies it after mapping its predicate methods to booleans.
+ *
+ * @remarks
+ * `isSymbolicLink` is not decoration. A `Dirent` describes the entry ITSELF, so
+ * a symbolic link pointing at a directory reports `isDirectory: false` — while
+ * the `stat`-based slow path, which resolves the link, calls the same entry a
+ * directory. Enumeration therefore re-resolves links through `isDirectory`
+ * rather than trusting `isDirectory` on a link, which is what keeps the fast
+ * and slow paths in agreement on a workspace whose packages are symlinked.
+ *
+ * Which behavior is *correct* is domain-dependent, so the flag is reported
+ * rather than resolved away. Enumeration follows links because a symlinked
+ * package is still a package. A test-file discovery walk usually must NOT: in a
+ * pnpm workspace `node_modules` is a farm of links into the content-addressed
+ * store, and following them walks the whole store or hits a cycle. A consumer
+ * building its own walker on this shape wants `isDirectory` verbatim — there,
+ * not following is the requirement, not the hazard.
+ *
+ * @public
+ */
+interface SyncDirectoryEntry {
+  /** The entry's own name, not a path. */
+  readonly name: string;
+  /** Whether the entry itself is a directory. `false` for a symbolic link, even one targeting a directory. */
+  readonly isDirectory: boolean;
+  /** Whether the entry itself is a symbolic link. */
+  readonly isSymbolicLink: boolean;
 }
 /**
  * The synchronous path operations the sync entry points need, supplied by the
@@ -114,5 +161,5 @@ declare const nodePath: SyncPath;
  */
 declare const nodeSyncOps: WorkspacesSyncOptions;
 //#endregion
-export { type SyncFileSystem, type SyncPath, type WorkspacesSyncOptions, nodeFileSystem, nodePath, nodeSyncOps };
+export { type SyncDirectoryEntry, type SyncFileSystem, type SyncPath, type WorkspacesSyncOptions, nodeFileSystem, nodePath, nodeSyncOps };
 //# sourceMappingURL=node-sync.d.ts.map

package/node-sync.js

@@ -41,7 +41,12 @@ const nodeFileSystem = {
 	exists: existsSync,
 	readFile: (p) => readFileSync(p, "utf8"),
 	readDirectory: (p) => readdirSync(p),
-	isDirectory: (p) => statSync(p).isDirectory()
+	isDirectory: (p) => statSync(p).isDirectory(),
+	readDirectoryWithTypes: (p) => readdirSync(p, { withFileTypes: true }).map((entry) => ({
+		name: entry.name,
+		isDirectory: entry.isDirectory(),
+		isSymbolicLink: entry.isSymbolicLink()
+	}))
 };
 /**
 * `SyncPath` as the running platform's `node:path` — win32 semantics on

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/workspaces",
-	"version": "0.15.1",
+	"version": "0.17.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": [
@@ -49,8 +49,8 @@
 		"@effected/commands": "^0.5.0",
 		"@effected/git": "^0.9.0",
 		"@effected/glob": "^0.4.0",
-		"@effected/lockfiles": "^0.6.1",
-		"@effected/npm": "^0.11.0",
+		"@effected/lockfiles": "^0.6.2",
+		"@effected/npm": "^0.11.1",
 		"@effected/package-json": "^0.10.2",
 		"@effected/semver": "^0.5.0",
 		"@effected/walker": "^0.5.0",

package/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.58.12"
+      "packageVersion": "7.58.13"
     }
   ]
 }