@effected/workspaces 0.1.0

package/index.js

@@ -0,0 +1,17 @@
+import { CatalogAssemblyError } from "./CatalogAssemblyError.js";
+import { PublishConfig, WorkspaceManifestError, WorkspacePackage } from "./WorkspacePackage.js";
+import { WORKSPACE_MARKERS, WorkspaceRoot, WorkspaceRootNotFoundError } from "./WorkspaceRoot.js";
+import { PackageNotFoundError, WorkspaceDiscovery, WorkspaceDiscoveryError, WorkspaceInfo, WorkspacePatternError } from "./WorkspaceDiscovery.js";
+import { CyclicDependencyError, DependencyGraph } from "./DependencyGraph.js";
+import { ChangeDetectionError, ChangeDetectionOptions, ChangeDetector } from "./ChangeDetector.js";
+import { ConfigDependencyHooks } from "./ConfigDependencyHooks.js";
+import { DetectedPackageManager, PackageManagerDetectionError, PackageManagerDetector, PackageManagerName } from "./PackageManagerName.js";
+import { LockfileReadError, LockfileReader } from "./LockfileReader.js";
+import { PublishTarget, PublishabilityDetector } from "./Publishability.js";
+import { CatalogSet, WorkspaceCatalogs } from "./WorkspaceCatalogs.js";
+import { PackageStateSnapshot, WorkspaceStateSnapshot } from "./WorkspaceStateSnapshot.js";
+import { WorkspaceSnapshots } from "./WorkspaceSnapshots.js";
+import { Workspaces } from "./Workspaces.js";
+import { findWorkspaceRootSync, getWorkspacePackagesSync } from "./WorkspacesSync.js";
+
+export { CatalogAssemblyError, CatalogSet, ChangeDetectionError, ChangeDetectionOptions, ChangeDetector, ConfigDependencyHooks, CyclicDependencyError, DependencyGraph, DetectedPackageManager, LockfileReadError, LockfileReader, PackageManagerDetectionError, PackageManagerDetector, PackageManagerName, PackageNotFoundError, PackageStateSnapshot, PublishConfig, PublishTarget, PublishabilityDetector, WORKSPACE_MARKERS, WorkspaceCatalogs, WorkspaceDiscovery, WorkspaceDiscoveryError, WorkspaceInfo, WorkspaceManifestError, WorkspacePackage, WorkspacePatternError, WorkspaceRoot, WorkspaceRootNotFoundError, WorkspaceSnapshots, WorkspaceStateSnapshot, Workspaces, findWorkspaceRootSync, getWorkspacePackagesSync };

package/internal/catalogs.js

@@ -0,0 +1,70 @@
+import { getCatalogsFromWorkspaceManifest, mergeCatalogs } from "@pnpm/catalogs.config";
+import { parseCatalogProtocol } from "@pnpm/catalogs.protocol-parser";
+import { matchCatalogResolveResult, resolveFromCatalog } from "@pnpm/catalogs.resolver";
+
+//#region src/internal/catalogs.ts
+/** Project a pnpm-workspace manifest's `catalog` / `catalogs` fields into a `Catalogs` map. */
+const inlineCatalogs = (manifest) => {
+	if (manifest.catalog === void 0 && manifest.catalogs === void 0) return {};
+	try {
+		return getCatalogsFromWorkspaceManifest({
+			catalog: manifest.catalog,
+			catalogs: manifest.catalogs
+		});
+	} catch {
+		return {};
+	}
+};
+/** Merge catalog sources; later sources win per dependency within a catalog. */
+const merge = (...sources) => mergeCatalogs(...sources);
+/** Whether `specifier` is a `catalog:` protocol reference, and which catalog it names. */
+const catalogNameOf = (specifier) => parseCatalogProtocol(specifier);
+/** Normalize the arbitrary shape of a catalog map into `CatalogEntries`, dropping anything unusable. */
+const normalize = (raw) => {
+	if (raw === null || typeof raw !== "object") return {};
+	const entries = {};
+	for (const [catalogName, catalog] of Object.entries(raw)) {
+		if (catalog === null || typeof catalog !== "object") continue;
+		const clean = {};
+		for (const [dependency, value] of Object.entries(catalog)) if (typeof value === "string") define(clean, dependency, value);
+		else if (value !== null && typeof value === "object" && "specifier" in value) {
+			const specifier = value.specifier;
+			if (typeof specifier === "string") define(clean, dependency, specifier);
+		}
+		define(entries, catalogName, clean);
+	}
+	return entries;
+};
+const define = (target, key, value) => {
+	if (key === "__proto__") Object.defineProperty(target, key, {
+		value,
+		writable: true,
+		enumerable: true,
+		configurable: true
+	});
+	else target[key] = value;
+};
+/**
+* Resolve one `catalog:` specifier against an assembled catalog set.
+*
+* Returns the range on a hit, `undefined` on a miss (the specifier names no
+* catalog entry — an ordinary `Option.none()` to the caller), and a
+* `CatalogMisconfiguration` when pnpm reports the catalog itself is malformed.
+*/
+const rangeOf = (catalogs, dependency, specifier) => {
+	if (catalogNameOf(specifier) === null) return void 0;
+	return matchCatalogResolveResult(resolveFromCatalog(catalogs, {
+		alias: dependency,
+		bareSpecifier: specifier
+	}), {
+		found: (hit) => hit.resolution.specifier,
+		misconfiguration: (bad) => ({
+			catalogName: bad.catalogName,
+			detail: bad.error.message
+		}),
+		unused: () => void 0
+	});
+};
+
+//#endregion
+export { catalogNameOf, inlineCatalogs, merge, normalize, rangeOf };

package/internal/enumerate.js

@@ -0,0 +1,75 @@
+import { Traversal, badMaxDepthMessage, isPruned, isValidMaxDepth, joinRelative } from "./traverse.js";
+import { Effect, FileSystem, Path } from "effect";
+
+//#region src/internal/enumerate.ts
+/** Strip a trailing slash from `GlobPattern.enumerationPrefix` to get a relative directory. */
+const baseOf = (pattern) => pattern.enumerationPrefix.replace(/\/$/, "");
+/**
+* Enumerate the workspace directories a compiled `packages:` set selects.
+*
+* Every returned directory holds a `package.json`, matches at least one include
+* (literal or wildcard), and is rejected by no exclude. Results are sorted by
+* relative path.
+*/
+const enumerate = (root, globs, options) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const maxDepth = options?.maxDepth ?? 32;
+	if (!isValidMaxDepth(maxDepth)) return yield* Effect.die(/* @__PURE__ */ new Error(`enumerate: ${badMaxDepthMessage(maxDepth)}`));
+	const isPackage = (absolute) => fs.exists(path.join(absolute, "package.json")).pipe(Effect.orElseSucceed(() => false));
+	const isDirectory = (absolute) => fs.stat(absolute).pipe(Effect.map((info) => info.type === "Directory"), Effect.orElseSucceed(() => false));
+	const included = /* @__PURE__ */ new Map();
+	/** A shared-traversal stop, materialized as this module's failure record. */
+	const failureOf = (stop, pattern) => ({
+		kind: stop.kind,
+		pattern,
+		detail: stop.detail
+	});
+	for (const literal of globs.literals) {
+		const absolute = path.join(root, literal);
+		if (yield* isPackage(absolute)) included.set(literal, absolute);
+	}
+	for (const wildcard of globs.wildcards) {
+		const base = baseOf(wildcard);
+		const absoluteBase = path.join(root, base);
+		if (!(yield* isDirectory(absoluteBase))) return yield* Effect.fail({
+			kind: "missingBaseDir",
+			pattern: wildcard.source,
+			detail: base === "" ? root : base
+		});
+		const traversal = new Traversal(base, absoluteBase, maxDepth);
+		for (let current = traversal.next(); current !== void 0; current = traversal.next()) {
+			const spent = traversal.charge();
+			if (spent !== void 0) return yield* Effect.fail(failureOf(spent, wildcard.source));
+			const frame = current;
+			const entries = yield* fs.readDirectory(frame.absolute).pipe(Effect.catch((error) => error.reason._tag === "NotFound" ? Effect.succeed([]) : Effect.fail({
+				kind: "unreadableDirectory",
+				pattern: wildcard.source,
+				detail: frame.relative === "" ? root : frame.relative
+			})));
+			for (const entry of entries) {
+				if (isPruned(entry)) continue;
+				const relative = joinRelative(frame.relative, entry);
+				const absolute = path.join(frame.absolute, entry);
+				if (!(yield* isDirectory(absolute))) continue;
+				if (wildcard.crossesSegments && !traversal.admits(frame)) return yield* Effect.fail(failureOf(traversal.depthStop(), wildcard.source));
+				if (wildcard.matches(relative) && (yield* isPackage(absolute))) included.set(relative, absolute);
+				if (!wildcard.crossesSegments) continue;
+				traversal.push(frame, relative, absolute);
+			}
+		}
+	}
+	const results = [];
+	for (const [relativePath, absolute] of included) {
+		if (globs.excludes.some((exclude) => exclude.matches(relativePath))) continue;
+		results.push({
+			relativePath,
+			path: absolute
+		});
+	}
+	results.sort((a, b) => a.relativePath < b.relativePath ? -1 : a.relativePath > b.relativePath ? 1 : 0);
+	return results;
+});
+
+//#endregion
+export { enumerate };

package/internal/limits.js

@@ -0,0 +1,20 @@
+//#region src/internal/limits.ts
+/**
+* Hard ceiling on directories the enumerator will visit for one pattern set.
+* Guards the pathological case a depth cap alone does not: a wide, shallow
+* tree. Exceeding it fails typed rather than hanging.
+*
+* @internal
+*/
+const MAX_ENUMERATION_ENTRIES = 1e5;
+/**
+* Directory names never descended into. pnpm, npm, yarn and bun all ignore
+* `node_modules` when expanding workspace globs; without the prune a
+* `packages/**` in an installed repo would walk the entire store.
+*
+* @internal
+*/
+const PRUNED_DIRECTORIES = /* @__PURE__ */ new Set([".git", "node_modules"]);
+
+//#endregion
+export { MAX_ENUMERATION_ENTRIES, PRUNED_DIRECTORIES };

package/internal/patterns.js

@@ -0,0 +1,62 @@
+import { Effect, FileSystem, Path } from "effect";
+import { Yaml } from "@effected/yaml";
+
+//#region src/internal/patterns.ts
+const stringsOf = (value) => Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : void 0;
+/** The `packages:` list of a `pnpm-workspace.yaml` document. Total on a parsed document. */
+const pnpmPatternsOf = (document) => {
+	if (document === null || typeof document !== "object") return [];
+	return stringsOf(document.packages) ?? [];
+};
+/** The `workspaces` field of a root package.json, in either supported shape. */
+const manifestPatternsOf = (manifest) => {
+	if (manifest === null || typeof manifest !== "object") return [];
+	const workspaces = manifest.workspaces;
+	const direct = stringsOf(workspaces);
+	if (direct !== void 0) return direct;
+	if (workspaces !== null && typeof workspaces === "object" && "packages" in workspaces) return stringsOf(workspaces.packages) ?? [];
+	return [];
+};
+/**
+* The workspace `packages:` patterns for `root`: `pnpm-workspace.yaml` first,
+* then the root package.json `workspaces` field. An absent config is a
+* standalone package, not an error — it yields an empty list.
+*/
+const readPatterns = (root) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const pnpmWorkspacePath = path.join(root, "pnpm-workspace.yaml");
+	if (yield* fs.exists(pnpmWorkspacePath).pipe(Effect.orElseSucceed(() => false))) {
+		const content = yield* fs.readFileString(pnpmWorkspacePath).pipe(Effect.mapError((cause) => ({
+			path: pnpmWorkspacePath,
+			kind: "read",
+			cause
+		})));
+		const document = yield* Yaml.parse(content).pipe(Effect.mapError((cause) => ({
+			path: pnpmWorkspacePath,
+			kind: "invalidYaml",
+			cause
+		})));
+		const patterns = pnpmPatternsOf(document);
+		if (patterns.length > 0) return patterns;
+	}
+	const manifestPath = path.join(root, "package.json");
+	if (!(yield* fs.exists(manifestPath).pipe(Effect.orElseSucceed(() => false)))) return [];
+	const content = yield* fs.readFileString(manifestPath).pipe(Effect.mapError((cause) => ({
+		path: manifestPath,
+		kind: "read",
+		cause
+	})));
+	const manifest = yield* Effect.try({
+		try: () => JSON.parse(content),
+		catch: (cause) => ({
+			path: manifestPath,
+			kind: "invalidJson",
+			cause
+		})
+	});
+	return manifestPatternsOf(manifest);
+});
+
+//#endregion
+export { manifestPatternsOf, pnpmPatternsOf, readPatterns };

package/internal/traverse.js

@@ -0,0 +1,94 @@
+import { MAX_ENUMERATION_ENTRIES, PRUNED_DIRECTORIES } from "./limits.js";
+
+//#region src/internal/traverse.ts
+/** Directory names never descended into. */
+const isPruned = (entry) => PRUNED_DIRECTORIES.has(entry);
+/** Join root-relative POSIX segments; `""` is the root itself. */
+const joinRelative = (base, entry) => base === "" ? entry : `${base}/${entry}`;
+/**
+* Whether `maxDepth` is a usable bound.
+*
+* `NaN < 1` is `false` and so is `2.5 < 1` — a bare relational guard admits both,
+* and a `NaN` bound then runs the loop zero times and returns an empty result
+* indistinguishable from a legitimate one. Integrality first. A bad bound is a
+* PROGRAMMER error, not a data condition, so both entry points treat it as a
+* defect (an `Effect.die` / a thrown `RangeError`) rather than a typed failure.
+*/
+const isValidMaxDepth = (maxDepth) => Number.isInteger(maxDepth) && maxDepth >= 1;
+/** The message both entry points use when `maxDepth` is not a positive integer. */
+const badMaxDepthMessage = (maxDepth) => `maxDepth must be a positive integer, received ${String(maxDepth)}`;
+/**
+* The shared worklist for one wildcard's descent.
+*
+* A worklist, not a recursion: it cannot overflow the stack, so there is no cap
+* to get wrong.
+*/
+var Traversal = class {
+	#frames = [];
+	#head = 0;
+	#visited = 0;
+	#base;
+	#maxDepth;
+	#maxEntries;
+	constructor(base, absoluteBase, maxDepth, maxEntries = MAX_ENUMERATION_ENTRIES) {
+		this.#base = base;
+		this.#maxDepth = maxDepth;
+		this.#maxEntries = maxEntries;
+		this.#frames.push({
+			relative: base,
+			absolute: absoluteBase,
+			depth: 0
+		});
+	}
+	/**
+	* The next directory to read, or `undefined` when the worklist is drained.
+	*
+	* A head index, never `Array.shift()`. `shift()` re-indexes the whole array on
+	* every dequeue, so draining a worklist anywhere near `MAX_ENUMERATION_ENTRIES`
+	* (100,000) is quadratic — the very budget that bounds the walk would become
+	* the slow path.
+	*/
+	next() {
+		if (this.#head >= this.#frames.length) return void 0;
+		const frame = this.#frames[this.#head];
+		this.#head += 1;
+		return frame;
+	}
+	/** Charge one directory read against the visit budget. */
+	charge() {
+		this.#visited += 1;
+		if (this.#visited > this.#maxEntries) return {
+			kind: "budgetExceeded",
+			detail: `visited more than ${this.#maxEntries} directories`
+		};
+	}
+	/**
+	* Whether a child of `parent` lies within the depth cap.
+	*
+	* Callers must consult this BEFORE accepting a child as a package, not merely
+	* before descending into it. The cap bounds what the traversal *enumerates*;
+	* a directory beyond it is out of scope entirely, and gating only the descent
+	* is what let a package one level past the cap slip into the sync results.
+	*/
+	admits(parent) {
+		return parent.depth + 1 <= this.#maxDepth;
+	}
+	/** The stop a child beyond the depth cap produces. */
+	depthStop() {
+		return {
+			kind: "depthExceeded",
+			detail: `descended past ${this.#maxDepth} levels below "${this.#base}"`
+		};
+	}
+	/** Queue a child of `parent` for descent. Only call when {@link Traversal.admits} holds. */
+	push(parent, relative, absolute) {
+		this.#frames.push({
+			relative,
+			absolute,
+			depth: parent.depth + 1
+		});
+	}
+};
+
+//#endregion
+export { Traversal, badMaxDepthMessage, isPruned, isValidMaxDepth, joinRelative };

package/package.json

@@ -0,0 +1,61 @@
+{
+	"name": "@effected/workspaces",
+	"version": "0.1.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": [
+		"monorepo",
+		"workspaces",
+		"pnpm",
+		"npm",
+		"yarn",
+		"bun",
+		"dependency-graph",
+		"catalog",
+		"effect",
+		"effected"
+	],
+	"homepage": "https://github.com/spencerbeggs/effected/tree/main/packages/workspaces#readme",
+	"bugs": {
+		"url": "https://github.com/spencerbeggs/effected/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/spencerbeggs/effected.git",
+		"directory": "packages/workspaces"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "C. Spencer Beggs",
+		"email": "spencer@beggs.codes",
+		"url": "https://spencerbeg.gs"
+	},
+	"sideEffects": false,
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"dependencies": {
+		"@effected/git": "0.1.0",
+		"@effected/glob": "0.1.0",
+		"@effected/lockfiles": "0.1.0",
+		"@effected/npm": "0.1.0",
+		"@effected/package-json": "0.1.0",
+		"@effected/walker": "0.1.0",
+		"@effected/yaml": "0.1.0",
+		"@pnpm/catalogs.config": "^1100.0.0",
+		"@pnpm/catalogs.protocol-parser": "^1100.0.0",
+		"@pnpm/catalogs.resolver": "^1100.0.0",
+		"@pnpm/catalogs.types": "^1100.0.0"
+	},
+	"peerDependencies": {
+		"effect": "4.0.0-beta.98"
+	},
+	"engines": {
+		"node": ">=24.11.0"
+	}
+}

package/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.58.9"
+    }
+  ]
+}