@effected/workspaces 0.1.0

package/WorkspaceStateSnapshot.js

@@ -0,0 +1,165 @@
+import { CatalogSet } from "./WorkspaceCatalogs.js";
+import { Effect, Exit, Layer, Option, Schema } from "effect";
+import { CatalogResolver, DependencySpecifier, WorkspaceResolver } from "@effected/npm";
+
+//#region src/WorkspaceStateSnapshot.ts
+const EMPTY = Object.freeze(Object.create(null));
+const DependencyMap = Schema.Record(Schema.String, Schema.String).pipe(Schema.withDecodingDefaultKey(Effect.succeed(EMPTY)), Schema.withConstructorDefault(Effect.succeed(EMPTY)));
+/**
+* One workspace member as captured in a {@link WorkspaceStateSnapshot} — the
+* serializable slice a snapshot diff reads: identity, version, location, and the
+* four dependency records.
+*
+* @remarks
+* Deliberately narrower than {@link WorkspacePackage}: a snapshot is a value to
+* store and diff, not a located member to act on, so it carries no absolute
+* paths, `publishConfig`, or `private` flag. The four records are keyed by the
+* standard manifest field names, which are exactly `@effected/npm`'s
+* `DependencyField` values.
+*
+* @public
+*/
+var PackageStateSnapshot = class extends Schema.Class("PackageStateSnapshot")({
+	/** The package name. */
+	name: Schema.NonEmptyString,
+	/** The raw `version` string, as recorded at the captured moment. */
+	version: Schema.String,
+	/** POSIX path relative to the workspace root; `"."` for the root package. */
+	relativePath: Schema.String,
+	/** Production dependencies. */
+	dependencies: DependencyMap,
+	/** Development dependencies. */
+	devDependencies: DependencyMap,
+	/** Peer dependencies. */
+	peerDependencies: DependencyMap,
+	/** Optional dependencies. */
+	optionalDependencies: DependencyMap
+}) {
+	/**
+	* Every dependency, merged across the four kinds.
+	*
+	* @remarks
+	* Precedence on a name declared in several kinds runs
+	* `dependencies` \> `devDependencies` \> `peerDependencies` \>
+	* `optionalDependencies`.
+	*/
+	get allDependencies() {
+		return {
+			...this.optionalDependencies,
+			...this.peerDependencies,
+			...this.devDependencies,
+			...this.dependencies
+		};
+	}
+};
+/**
+* The state of a whole workspace at one moment — its packages and its assembled
+* catalog set — as a serializable value.
+*
+* @remarks
+* Produced by `WorkspaceSnapshots.at` (a git ref, read with no checkout)
+* or `WorkspaceSnapshots.worktree` (the live tree). The lookup and
+* resolution surfaces (`versions`, `package`, `resolve`, the resolver layers)
+* are backed by `#private` indexes built lazily on first use and never encoded —
+* the `DependencyGraph` edge-index precedent.
+*
+* `resolve` and the resolver layers answer specifiers against THIS snapshot's
+* own captured state, so a consumer can ask "what did `catalog:` /
+* `workspace:*` mean as of that ref". An unmatched specifier is always
+* `Option.none()`, never an error.
+*
+* @example
+* ```ts
+* import { WorkspaceSnapshots } from "@effected/workspaces";
+* import { Effect } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const snapshots = yield* WorkspaceSnapshots;
+*   const before = yield* snapshots.at("origin/main");
+*   return before.resolve("effect", "catalog:");
+* });
+* ```
+*
+* @public
+*/
+var WorkspaceStateSnapshot = class extends Schema.Class("WorkspaceStateSnapshot")({
+	/** Every workspace package captured at this moment. */
+	packages: Schema.Array(PackageStateSnapshot),
+	/** The catalog set assembled at this moment. */
+	catalogs: CatalogSet
+}) {
+	#versionIndex;
+	#packageIndex;
+	#catalogResolver;
+	#workspaceResolver;
+	#resolvers;
+	#versions() {
+		if (this.#versionIndex === void 0) this.#versionIndex = new Map(this.packages.map((pkg) => [pkg.name, pkg.version]));
+		return this.#versionIndex;
+	}
+	#packages() {
+		if (this.#packageIndex === void 0) this.#packageIndex = new Map(this.packages.map((pkg) => [pkg.name, pkg]));
+		return this.#packageIndex;
+	}
+	/** Every captured package's name → version. Total; O(1) after the first call. */
+	get versions() {
+		return this.#versions();
+	}
+	/** A single captured package by name, or `Option.none()`. Total. */
+	package(name) {
+		return Option.fromUndefinedOr(this.#packages().get(name));
+	}
+	/**
+	* The concrete range or version a specifier resolved to AS OF this snapshot.
+	*
+	* @remarks
+	* The specifier is classified through `@effected/npm`'s
+	* `DependencySpecifier.FromString` — never by prefix-sniffing.
+	* A `workspace:` specifier resolves to the captured version of `dependency`; a
+	* `catalog:` specifier resolves against the captured catalog set. Every other
+	* form — a plain range, a dist-tag, a `file:`/git/url specifier, or an
+	* unparseable string — is `Option.none()`, because there is no indirection to
+	* resolve. Total.
+	*
+	* @param dependency - The dependency's package name (what `workspace:` /
+	*   `catalog:` resolve for).
+	* @param specifier - The raw specifier string.
+	*/
+	resolve(dependency, specifier) {
+		const exit = Schema.decodeUnknownExit(DependencySpecifier.FromString)(specifier);
+		if (!Exit.isSuccess(exit)) return Option.none();
+		const classified = exit.value;
+		switch (classified._tag) {
+			case "catalog": return this.catalogs.rangeOf(dependency, classified.name);
+			case "workspace": return Option.fromUndefinedOr(this.#versions().get(dependency));
+			default: return Option.none();
+		}
+	}
+	/**
+	* A `CatalogResolver` layer implementing `@effected/npm`'s contract against
+	* THIS snapshot's catalog set — so code written to the contract resolves
+	* `catalog:` specifiers as of this ref. Built once per instance and cached, so
+	* it memoizes by reference.
+	*/
+	get catalogResolver() {
+		if (this.#catalogResolver === void 0) this.#catalogResolver = Layer.succeed(CatalogResolver, { rangeOf: (packageName, catalog) => Effect.succeed(this.catalogs.rangeOf(packageName, catalog)) });
+		return this.#catalogResolver;
+	}
+	/**
+	* A `WorkspaceResolver` layer implementing `@effected/npm`'s contract against
+	* THIS snapshot's captured versions — so code written to the contract resolves
+	* `workspace:` specifiers as of this ref. Built once per instance and cached.
+	*/
+	get workspaceResolver() {
+		if (this.#workspaceResolver === void 0) this.#workspaceResolver = Layer.succeed(WorkspaceResolver, { versionOf: (packageName) => Effect.succeed(Option.fromUndefinedOr(this.#versions().get(packageName))) });
+		return this.#workspaceResolver;
+	}
+	/** Both snapshot-scoped resolver layers merged. Built once per instance and cached. */
+	get resolvers() {
+		if (this.#resolvers === void 0) this.#resolvers = Layer.mergeAll(this.catalogResolver, this.workspaceResolver);
+		return this.#resolvers;
+	}
+};
+
+//#endregion
+export { PackageStateSnapshot, WorkspaceStateSnapshot };

package/Workspaces.js

@@ -0,0 +1,113 @@
+import { WorkspaceRoot } from "./WorkspaceRoot.js";
+import { WorkspaceDiscovery } from "./WorkspaceDiscovery.js";
+import { ChangeDetector } from "./ChangeDetector.js";
+import { PackageManagerDetector } from "./PackageManagerName.js";
+import { LockfileReader } from "./LockfileReader.js";
+import { PublishabilityDetector } from "./Publishability.js";
+import { WorkspaceCatalogs } from "./WorkspaceCatalogs.js";
+import { WorkspaceSnapshots } from "./WorkspaceSnapshots.js";
+import { Layer } from "effect";
+import { Git } from "@effected/git";
+
+//#region src/Workspaces.ts
+/**
+* Every service that needs only a filesystem: root, package-manager detection,
+* discovery, lockfile reading, catalogs and publishability.
+*
+* @remarks
+* Requires core `FileSystem` and `Path`, which the consumer provides at the
+* edge (`@effect/platform-node`, `@effect/platform-bun`, or a test's
+* `FileSystem.layerNoop`).
+*
+* **Bind the result to a `const`.** This is a parameterized factory and layers
+* memoize by reference, so calling it twice builds everything twice.
+*
+* @example
+* ```ts
+* import { Workspaces } from "@effected/workspaces";
+* import { Layer } from "effect";
+*
+* const WorkspacesLayer = Workspaces.layer();
+* const AppLayer = Layer.provide(WorkspacesLayer, PlatformLayer);
+* ```
+*
+* @public
+*/
+const compose = (options, catalogsFactory) => {
+	const roots = WorkspaceRoot.layer;
+	const detector = PackageManagerDetector.layer;
+	const discovery = WorkspaceDiscovery.layer(options).pipe(Layer.provide(roots));
+	const lockfiles = LockfileReader.layer(options).pipe(Layer.provide(roots), Layer.provide(detector), Layer.provide(discovery));
+	const catalogs = catalogsFactory(options).pipe(Layer.provide(roots), Layer.provide(lockfiles));
+	return Layer.mergeAll(roots, detector, discovery, lockfiles, catalogs, PublishabilityDetector.layer);
+};
+const layer = (options) => compose(options, WorkspaceCatalogs.layer);
+/**
+* The git-free composite plus {@link ChangeDetector} and
+* {@link WorkspaceSnapshots}, over `@effected/git`'s `Git` service.
+*
+* @remarks
+* The extra requirement is core's `ChildProcessSpawner` (behind `Git`), which
+* is why it is a separate layer rather than a flag: a consumer that never
+* detects changes or reads at a ref should not have to be able to spawn a
+* subprocess. The consumer provides `ChildProcessSpawner` once at the edge
+* (`@effect/platform-node`'s `NodeServices.layer`); a test provides
+* `Layer.succeed(Git, …)` and needs no repository on disk.
+*
+* @public
+*/
+const layerWithGit = (options) => {
+	const core = layer(options);
+	const git = Git.layer;
+	return Layer.mergeAll(core, git, ChangeDetector.layer.pipe(Layer.provide(git), Layer.provide(core)), WorkspaceSnapshots.layer(options).pipe(Layer.provide(git), Layer.provide(core)));
+};
+/**
+* The two `@effected/npm` resolver contracts, implemented for real.
+*
+* @remarks
+* Provide this alongside `@effected/package-json`'s `Package.resolve` and a
+* manifest's `catalog:` and `workspace:` specifiers resolve against the actual
+* workspace instead of the no-op layers' `Option.none()`.
+*
+* @example
+* ```ts
+* import { Package } from "@effected/package-json";
+* import { Workspaces } from "@effected/workspaces";
+* import { Layer } from "effect";
+*
+* const WorkspacesLayer = Workspaces.layer();
+* const Resolvers = Workspaces.resolvers.pipe(Layer.provide(WorkspacesLayer));
+* ```
+*
+* @public
+*/
+const resolvers = Layer.mergeAll(WorkspaceCatalogs.catalogResolver, WorkspaceDiscovery.workspaceResolver);
+/**
+* The git-free composite, but with catalog assembly that **replays config
+* dependency `pnpmfile.cjs` hooks** — {@link WorkspaceCatalogs.layerWithConfigDependencies}
+* in place of the default no-op catalogs layer.
+*
+* @remarks
+* Identical requirement set to {@link Workspaces.layer}; the only difference is
+* that config-dependency code is executed in process. Opt in deliberately — the
+* default {@link Workspaces.layer} never executes config-dependency code.
+*
+* **Bind the result to a `const`.**
+*
+* @public
+*/
+const layerWithConfigDependencies = (options) => compose(options, WorkspaceCatalogs.layerWithConfigDependencies);
+/**
+* The composite layers.
+*
+* @public
+*/
+const Workspaces = {
+	layer,
+	layerWithConfigDependencies,
+	layerWithGit,
+	resolvers
+};
+
+//#endregion
+export { Workspaces };

package/WorkspacesSync.js

@@ -0,0 +1,205 @@
+import { Traversal, badMaxDepthMessage, isPruned, isValidMaxDepth, joinRelative } from "./internal/traverse.js";
+import { manifestPatternsOf, pnpmPatternsOf } from "./internal/patterns.js";
+import { PublishConfig, WorkspacePackage } from "./WorkspacePackage.js";
+import { Effect, Exit, Schema } from "effect";
+import { GlobSet } from "@effected/glob";
+import { Yaml } from "@effected/yaml";
+import { dirname, join, resolve } from "node:path";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+
+//#region src/WorkspacesSync.ts
+/**
+* Read and JSON-parse a file into a plain object, or `undefined`. Never throws.
+*
+* The non-object check is load-bearing, not defensive noise. `JSON.parse`
+* returns `undefined` for *nothing* — a `package.json` whose entire content is
+* `null`, `42` or `"x"` parses successfully to that value, so a caller guarding
+* only on `undefined` sails straight into `raw.name` and throws a `TypeError`.
+* These functions are documented as total and are reached from a Vitest config,
+* which has nowhere to put a crash: malformed input must be *skipped*, never a
+* defect.
+*/
+const readJson = (file) => {
+	let parsed;
+	try {
+		parsed = JSON.parse(readFileSync(file, "utf8"));
+	} catch {
+		return;
+	}
+	return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : void 0;
+};
+/** Whether `dir` is a directory. Never throws. */
+const isDirectory = (dir) => {
+	try {
+		return statSync(dir).isDirectory();
+	} catch {
+		return false;
+	}
+};
+/** Whether `dir` holds a `package.json`. */
+const isPackage = (dir) => existsSync(join(dir, "package.json"));
+/**
+* The nearest workspace root at or above `cwd`, or `null`.
+*
+* @remarks
+* **Synchronous and Node-only.** The Effect surface is `WorkspaceRoot`; reach
+* for this one only where you genuinely cannot run an Effect — a Vitest config
+* being the motivating case.
+*
+* Markers match the async service exactly: a `pnpm-workspace.yaml`, or a
+* `package.json` carrying a `workspaces` field.
+*
+* @param cwd - Where to start the ascent. Defaults to `process.cwd()`.
+*
+* @example
+* ```ts
+* import { findWorkspaceRootSync } from "@effected/workspaces";
+*
+* const root = findWorkspaceRootSync();
+* ```
+*
+* @public
+*/
+const findWorkspaceRootSync = (cwd) => {
+	let current = resolve(cwd ?? process.cwd());
+	for (let depth = 0; depth < 32 * 8; depth++) {
+		if (existsSync(join(current, "pnpm-workspace.yaml"))) return current;
+		const manifest = readJson(join(current, "package.json"));
+		if (manifest?.workspaces !== void 0 && manifest.workspaces !== null) return current;
+		const parent = dirname(current);
+		if (parent === current) return null;
+		current = parent;
+	}
+	return null;
+};
+/** The workspace `packages:` patterns for `root`, matching `internal/patterns.ts`'s precedence. */
+const readPatternsSync = (root) => {
+	const workspaceYaml = join(root, "pnpm-workspace.yaml");
+	if (existsSync(workspaceYaml)) {
+		let text = "";
+		try {
+			text = readFileSync(workspaceYaml, "utf8");
+		} catch {
+			text = "";
+		}
+		const exit = Effect.runSyncExit(Yaml.parse(text));
+		if (Exit.isSuccess(exit)) {
+			const patterns = pnpmPatternsOf(exit.value);
+			if (patterns.length > 0) return patterns;
+		}
+	}
+	return manifestPatternsOf(readJson(join(root, "package.json")) ?? {});
+};
+/** Build a `WorkspacePackage` from a directory, or `null` if its manifest is unusable. */
+const readPackageSync = (directory, relativePath) => {
+	const packageJsonPath = join(directory, "package.json");
+	const raw = readJson(packageJsonPath);
+	if (raw === void 0) return null;
+	const name = raw.name;
+	const version = raw.version;
+	if (typeof name !== "string" || name.length === 0) return null;
+	if (typeof version !== "string" || version.length === 0) return null;
+	const stringRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value) && Object.values(value).every((entry) => typeof entry === "string") ? value : void 0;
+	const publishConfig = raw.publishConfig;
+	const config = publishConfig !== null && typeof publishConfig === "object" ? Effect.runSyncExit(Schema.decodeUnknownEffect(PublishConfig)(publishConfig)) : void 0;
+	return WorkspacePackage.make({
+		name,
+		version,
+		path: directory,
+		packageJsonPath,
+		relativePath,
+		private: raw.private === true,
+		dependencies: stringRecord(raw.dependencies) ?? {},
+		devDependencies: stringRecord(raw.devDependencies) ?? {},
+		peerDependencies: stringRecord(raw.peerDependencies) ?? {},
+		optionalDependencies: stringRecord(raw.optionalDependencies) ?? {},
+		...config !== void 0 && Exit.isSuccess(config) ? { publishConfig: config.value } : {}
+	});
+};
+/**
+* Every workspace package under `root`, root package first.
+*
+* @remarks
+* **Synchronous and Node-only.** The Effect surface is `WorkspaceDiscovery`.
+*
+* Pattern semantics are not merely "shared" with the Effect enumerator — both
+* drive the **same traversal state machine** (`internal/traverse.ts`), so the
+* dequeue order, the depth rule, the visit budget and the prune list cannot
+* drift apart. A `packages/**` finds exactly the same packages here as there,
+* including at the depth boundary.
+*
+* The one deliberate difference is what happens at a bound: the Effect surface
+* fails typed (`depthExceeded` / `budgetExceeded`), while this one is **total**
+* and truncates. An unenumerable pattern or an unreadable manifest is skipped,
+* not raised — a function with no error channel should not pretend to have one,
+* and a Vitest config has nowhere to put a failure. Totality covers *data*, not
+* caller mistakes: a `maxDepth` that is not a positive integer throws, matching
+* the enumerator's defect.
+*
+* @param root - The workspace root, from {@link findWorkspaceRootSync}.
+* @param options - Traversal bounds; see {@link GetWorkspacePackagesSyncOptions}.
+*
+* @example
+* ```ts
+* import { findWorkspaceRootSync, getWorkspacePackagesSync } from "@effected/workspaces";
+*
+* const root = findWorkspaceRootSync();
+* const packages = root === null ? [] : getWorkspacePackagesSync(root);
+* ```
+*
+* @public
+*/
+const getWorkspacePackagesSync = (root, options) => {
+	const maxDepth = options?.maxDepth ?? 32;
+	if (!isValidMaxDepth(maxDepth)) throw new RangeError(`getWorkspacePackagesSync: ${badMaxDepthMessage(maxDepth)}`);
+	const patterns = readPatternsSync(root);
+	const compiled = Effect.runSyncExit(GlobSet.compile(patterns));
+	if (Exit.isFailure(compiled)) return [];
+	const globs = compiled.value;
+	const included = /* @__PURE__ */ new Map();
+	for (const literal of globs.literals) {
+		const absolute = join(root, literal);
+		if (isPackage(absolute)) included.set(literal, absolute);
+	}
+	for (const wildcard of globs.wildcards) {
+		const base = wildcard.enumerationPrefix.replace(/\/$/, "");
+		const absoluteBase = join(root, base);
+		if (!isDirectory(absoluteBase)) continue;
+		const traversal = new Traversal(base, absoluteBase, maxDepth);
+		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 = readdirSync(current.absolute);
+			} catch {
+				continue;
+			}
+			for (const entry of entries) {
+				if (isPruned(entry)) continue;
+				const relative = joinRelative(current.relative, entry);
+				const absolute = join(current.absolute, entry);
+				if (!isDirectory(absolute)) continue;
+				if (wildcard.crossesSegments && !traversal.admits(current)) {
+					stopped = true;
+					break;
+				}
+				if (wildcard.matches(relative) && isPackage(absolute)) included.set(relative, absolute);
+				if (!wildcard.crossesSegments) continue;
+				traversal.push(current, relative, absolute);
+			}
+		}
+	}
+	const members = [];
+	for (const [relativePath, absolute] of [...included.entries()].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) {
+		if (relativePath === "." || absolute === root) continue;
+		if (globs.excludes.some((exclude) => exclude.matches(relativePath))) continue;
+		const pkg = readPackageSync(absolute, relativePath);
+		if (pkg !== null) members.push(pkg);
+	}
+	const rootPackage = readPackageSync(root, ".");
+	return rootPackage === null ? members : [rootPackage, ...members];
+};
+
+//#endregion
+export { findWorkspaceRootSync, getWorkspacePackagesSync };