@effected/workspaces 0.1.0

package/WorkspaceCatalogs.js

@@ -0,0 +1,392 @@
+import { CatalogAssemblyError } from "./CatalogAssemblyError.js";
+import { WorkspaceRoot } from "./WorkspaceRoot.js";
+import { inlineCatalogs, merge, normalize, rangeOf } from "./internal/catalogs.js";
+import { ConfigDependencyHooks } from "./ConfigDependencyHooks.js";
+import { LockfileReader } from "./LockfileReader.js";
+import { Context, Duration, Effect, Exit, FileSystem, Layer, Option, Path, PlatformError, Schema } from "effect";
+import { CatalogResolver, DependencyResolutionError } from "@effected/npm";
+import { Yaml } from "@effected/yaml";
+
+//#region src/WorkspaceCatalogs.ts
+/**
+* An immutable, fully-normalized catalog collection — the one catalog
+* resolution semantic in the package.
+*
+* @remarks
+* `entries` is catalog name → dependency → range, with pnpm's unnamed
+* top-level `catalog:` block normalized under the key `"default"`. Lockfile
+* catalog entries, which pnpm records as `{ specifier, version }`, are
+* normalized to their `specifier` — the declared range, which is what a catalog
+* resolves to.
+*
+* @public
+*/
+var CatalogSet = class CatalogSet extends Schema.Class("CatalogSet")({ 
+/** Catalog name → dependency name → version range. */
+entries: Schema.Record(Schema.String, Schema.Record(Schema.String, Schema.String)) }) {
+	/** The empty set — a workspace with no catalogs. */
+	static empty() {
+		return CatalogSet.make({ entries: {} });
+	}
+	/** Wrap a pnpm `Catalogs` map, dropping unusable entries. */
+	static fromCatalogs(catalogs) {
+		return CatalogSet.make({ entries: normalize(catalogs) });
+	}
+	/**
+	* The `catalog:` and `catalogs:` blocks of a `pnpm-workspace.yaml` document.
+	*
+	* @param text - The raw YAML text.
+	*/
+	static fromWorkspaceYaml = Effect.fn("CatalogSet.fromWorkspaceYaml")(function* (text) {
+		const document = yield* Yaml.parse(text).pipe(Effect.mapError((cause) => new CatalogAssemblyError({
+			source: "manifest",
+			path: "pnpm-workspace.yaml",
+			cause
+		})));
+		return CatalogSet.fromCatalogs(inlineCatalogs(catalogBlocksOf(document)));
+	});
+	/**
+	* The `catalogs:` section of a pnpm lockfile, whose entries are either a bare
+	* range or a `{ specifier, version }` pair.
+	*/
+	static fromLockfileCatalogs(raw) {
+		return CatalogSet.make({ entries: normalize(raw) });
+	}
+	/**
+	* The catalog set a parsed lockfile records, PM-aware.
+	*
+	* @remarks
+	* Both pnpm and bun record catalogs in the lockfile, in different shapes:
+	* pnpm under `extension.catalogs`, bun under `extension.catalog` /
+	* `extension.catalogs`. Assembly reads whichever the parsed lockfile carries
+	* rather than assuming the pnpm extension. A lockfile with no extension, or a
+	* pnpm one with no catalogs, yields the empty set.
+	*
+	* @param lockfile - A parsed lockfile from `@effected/lockfiles`.
+	*/
+	static fromLockfile(lockfile) {
+		const ext = lockfile.extension;
+		if (ext === void 0) return CatalogSet.empty();
+		if (ext._tag === "pnpm") return ext.catalogs !== void 0 ? CatalogSet.fromLockfileCatalogs(ext.catalogs) : CatalogSet.empty();
+		return CatalogSet.fromBunBlocks({
+			catalog: ext.catalog,
+			catalogs: ext.catalogs
+		});
+	}
+	/**
+	* A catalog set from bun's `{ catalog, catalogs }` blocks — used for the
+	* `bun.lock` extension and for the root `package.json` `workspaces` block. The
+	* unnamed default catalog normalizes under `"default"`. Tolerant: unusable
+	* values are dropped, never fatal.
+	*
+	* @param blocks - The `catalog` (default) and `catalogs` (named) blocks.
+	*/
+	static fromBunBlocks(blocks) {
+		const raw = {};
+		if (isObject(blocks.catalogs)) Object.assign(raw, blocks.catalogs);
+		if (isObject(blocks.catalog)) raw.default = {
+			...isObject(raw.default) ? raw.default : {},
+			...blocks.catalog
+		};
+		return CatalogSet.fromCatalogs(raw);
+	}
+	/**
+	* The `catalog` / `catalogs` blocks of a root `package.json` `workspaces` field
+	* — bun's package.json analogue of pnpm's `pnpm-workspace.yaml` blocks.
+	*
+	* @remarks
+	* **Hard-fail by design**, preserving the semantics catalog output is
+	* load-bearing for: a present-but-malformed `workspaces` shape (a number, a
+	* string, an object with a malformed `packages` / `catalog` / `catalogs`), or
+	* the default catalog declared twice — once as `workspaces.catalog` and again
+	* as `workspaces.catalogs.default` — fails with {@link CatalogAssemblyError}
+	* naming what was wrong. An absent `workspaces` field, one explicitly `null`,
+	* or the plain array form (npm/yarn patterns, which carry no catalogs) yields
+	* the empty set. Presence is checked structurally, so an explicitly-declared
+	* empty `catalog: {}` still counts as a declaration.
+	*
+	* @param text - The raw root `package.json` text.
+	*/
+	static fromManifestWorkspaces = Effect.fn("CatalogSet.fromManifestWorkspaces")(function* (text) {
+		const manifest = yield* Effect.try({
+			try: () => JSON.parse(text),
+			catch: (cause) => new CatalogAssemblyError({
+				source: "manifest",
+				path: "package.json",
+				cause
+			})
+		});
+		if (!isObject(manifest)) return yield* Effect.fail(new CatalogAssemblyError({
+			source: "manifest",
+			path: "package.json",
+			cause: /* @__PURE__ */ new Error("package.json is not a JSON object")
+		}));
+		const blocks = yield* manifestCatalogBlocks(manifest.workspaces);
+		return CatalogSet.fromBunBlocks(blocks);
+	});
+	/** Merge sets. Later sets win per dependency within a catalog. */
+	static merge(...sets) {
+		return CatalogSet.fromCatalogs(merge(...sets.map((set) => set.entries)));
+	}
+	/** Whether any catalog declares anything. */
+	get isEmpty() {
+		return Object.keys(this.entries).length === 0;
+	}
+	/**
+	* The range a `catalog:` specifier resolves to.
+	*
+	* @remarks
+	* Total: an unmatched dependency, an unknown catalog name, or a non-catalog
+	* specifier all yield `Option.none()`. A *malformed* catalog — one pnpm
+	* itself rejects — also yields `Option.none()` here; the fallible surface is
+	* {@link WorkspaceCatalogs}, which fails typed on assembly instead.
+	*
+	* @param dependency - The package name being resolved.
+	* @param specifier - The declared specifier, e.g. `catalog:` or `catalog:build`.
+	*/
+	resolveSpecifier(dependency, specifier) {
+		const resolved = rangeOf(this.entries, dependency, specifier);
+		return typeof resolved === "string" ? Option.some(resolved) : Option.none();
+	}
+	/**
+	* The range `dependency` carries in a named catalog, or in the default
+	* catalog when `catalog` is `Option.none()`.
+	*
+	* @remarks
+	* The shape `@effected/npm`'s `CatalogResolver` contract asks for.
+	*/
+	rangeOf(dependency, catalog) {
+		const name = Option.getOrElse(catalog, () => "default");
+		return Option.fromUndefinedOr(this.entries[name]?.[dependency]);
+	}
+};
+/** Whether `value` is a non-null, non-array object. */
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Whether every value in an object is a string — a usable `dependency → range` catalog. */
+const isStringRecord = (value) => isObject(value) && Object.values(value).every((entry) => typeof entry === "string");
+/** The `catalog` / `catalogs` blocks of a parsed pnpm-workspace document. */
+const catalogBlocksOf = (document) => {
+	if (document === null || typeof document !== "object") return {};
+	const raw = document;
+	return {
+		catalog: raw.catalog,
+		catalogs: raw.catalogs
+	};
+};
+/** The `configDependencies` map (name → version+integrity) of a parsed pnpm-workspace document. */
+const configDependenciesOf = (document) => {
+	if (!isObject(document) || !isObject(document.configDependencies)) return {};
+	const out = {};
+	for (const [name, spec] of Object.entries(document.configDependencies)) if (typeof spec === "string") out[name] = spec;
+	return out;
+};
+/** A hard-fail catalog-assembly failure naming the malformed part of a `workspaces` field. */
+const malformed = (source, path, detail) => new CatalogAssemblyError({
+	source,
+	path,
+	cause: new Error(detail)
+});
+/**
+* Validate a `catalog` (default) / `catalogs` (named) block pair, hard-failing on
+* a malformed shape or the default catalog declared twice.
+*
+* @remarks
+* Shared by the bun `package.json` `workspaces` reader
+* ({@link CatalogSet.fromManifestWorkspaces}) and the pnpm `pnpm-workspace.yaml`
+* reader, so both fail typed on exactly the same conditions rather than one
+* hard-failing and the other silently normalizing to `{}` — the "every dependency
+* looks newly added" bug. `labels` names the two blocks in the diagnostics so the
+* error reads in the caller's vocabulary (`workspaces.catalog` vs. `catalog`).
+*/
+const validatedCatalogBlocks = (catalog, catalogs, labels) => {
+	let validCatalog;
+	if (catalog !== void 0 && catalog !== null) {
+		if (!isStringRecord(catalog)) return Effect.fail(malformed("catalog", labels.catalog, `"${labels.catalog}" must map dependency names to version strings`));
+		validCatalog = catalog;
+	}
+	let validCatalogs;
+	if (catalogs !== void 0 && catalogs !== null) {
+		if (!isObject(catalogs)) return Effect.fail(malformed("catalog", labels.catalogs, `"${labels.catalogs}" must map catalog names to catalogs`));
+		for (const [name, entries] of Object.entries(catalogs)) if (!isStringRecord(entries)) return Effect.fail(malformed("catalog", `${labels.catalogs}.${name}`, `"${labels.catalogs}.${name}" must map dependency names to version strings`));
+		validCatalogs = catalogs;
+	}
+	if (validCatalog !== void 0 && validCatalogs !== void 0 && "default" in validCatalogs) return Effect.fail(malformed("catalog", "default", `The default catalog is declared twice: as "${labels.catalog}" and as "${labels.catalogs}.default"`));
+	return Effect.succeed({
+		...validCatalog !== void 0 ? { catalog: validCatalog } : {},
+		...validCatalogs !== void 0 ? { catalogs: validCatalogs } : {}
+	});
+};
+/**
+* The `catalog` / `catalogs` blocks of a root `package.json` `workspaces` field,
+* hard-failing on a malformed shape or the default catalog declared twice.
+*/
+const manifestCatalogBlocks = (workspaces) => {
+	if (workspaces === void 0 || workspaces === null || Array.isArray(workspaces)) return Effect.succeed({});
+	if (!isObject(workspaces)) return Effect.fail(malformed("manifest", "package.json", `"workspaces" must be an array or object, got ${typeof workspaces}`));
+	if (workspaces.packages !== void 0 && workspaces.packages !== null) {
+		const packages = workspaces.packages;
+		if (!Array.isArray(packages) || !packages.every((entry) => typeof entry === "string")) return Effect.fail(malformed("manifest", "package.json", `"workspaces.packages" must be an array of strings`));
+	}
+	return validatedCatalogBlocks(workspaces.catalog, workspaces.catalogs, {
+		catalog: "workspaces.catalog",
+		catalogs: "workspaces.catalogs"
+	});
+};
+/**
+* Validate the inline `catalog` / `catalogs` blocks of a parsed
+* `pnpm-workspace.yaml` document, hard-failing on the same malformed-shape and
+* duplicate-default conditions as the bun `package.json` path.
+*
+* @remarks
+* The live pnpm reader in {@link WorkspaceCatalogs.make} runs this BEFORE
+* normalizing with `inlineCatalogs`, so an invalid inline catalog fails typed
+* rather than normalizing to `{}` and reading as ABSENT. A non-object document,
+* or one with no catalog blocks, validates to `{}` — absent/empty still yields
+* empty. The return is discarded; normalization stays on the shared
+* `inlineCatalogs` path.
+*/
+const validatePnpmWorkspaceCatalogs = (document) => {
+	if (!isObject(document)) return Effect.void;
+	return Effect.asVoid(validatedCatalogBlocks(document.catalog, document.catalogs, {
+		catalog: "catalog",
+		catalogs: "catalogs"
+	}));
+};
+/**
+* Assembles a workspace's catalogs, package-manager-aware.
+*
+* @remarks
+* The inline source is picked by **file presence**, the same rule
+* `internal/patterns.ts` uses for globs: a `pnpm-workspace.yaml` selects the pnpm
+* path (its `catalog:` / `catalogs:` blocks); its absence selects the root
+* `package.json` `workspaces.catalog` / `workspaces.catalogs` (bun's analogue).
+* The lockfile source is PM-aware too — whichever extension the parsed lockfile
+* carries (pnpm or bun) contributes its recorded catalogs.
+*
+* Precedence, lowest first: catalogs recorded in the lockfile, then the inline
+* declaration, then — only under {@link WorkspaceCatalogs.layerWithConfigDependencies}
+* — the config-dependency `pnpmfile.cjs` hooks, each layer winning per dependency
+* within a catalog. An unreadable or absent lockfile degrades to no lockfile
+* catalogs rather than failing (the inline declaration is the source of truth, the
+* lockfile a record of what was installed); a malformed inline source **fails
+* typed** with {@link CatalogAssemblyError}, because a silently-empty catalog read
+* is the "every dependency looks newly added" bug.
+*
+* Assembly is deferred to the first call and memoized success-only, matching
+* {@link WorkspaceDiscovery}.
+*
+* @public
+*/
+var WorkspaceCatalogs = class WorkspaceCatalogs extends Context.Service()("@effected/workspaces/WorkspaceCatalogs") {
+	/** Builds the service. */
+	static make = (options) => Effect.gen(function* () {
+		const roots = yield* WorkspaceRoot;
+		const lockfiles = yield* LockfileReader;
+		const hooks = yield* ConfigDependencyHooks;
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		const probeExists = (target) => fs.exists(target).pipe(Effect.catchTag("PlatformError", (error) => {
+			const reason = error.reason;
+			return reason instanceof PlatformError.SystemError && reason._tag === "NotFound" ? Effect.succeed(false) : Effect.fail(new CatalogAssemblyError({
+				source: "manifest",
+				path: target,
+				cause: error
+			}));
+		}));
+		const assemble = Effect.gen(function* () {
+			const root = yield* Effect.suspend(() => roots.find(options?.cwd ?? process.cwd()));
+			const fromLockfile = yield* lockfiles.read().pipe(Effect.map(CatalogSet.fromLockfile), Effect.catch((_failure) => Effect.succeed(CatalogSet.empty())));
+			const workspaceYaml = path.join(root, "pnpm-workspace.yaml");
+			const hasPnpmWorkspace = yield* probeExists(workspaceYaml);
+			let inline;
+			let injected;
+			if (hasPnpmWorkspace) {
+				const text = yield* fs.readFileString(workspaceYaml).pipe(Effect.mapError((cause) => new CatalogAssemblyError({
+					source: "manifest",
+					path: workspaceYaml,
+					cause
+				})));
+				const document = yield* Yaml.parse(text).pipe(Effect.mapError((cause) => new CatalogAssemblyError({
+					source: "manifest",
+					path: "pnpm-workspace.yaml",
+					cause
+				})));
+				yield* validatePnpmWorkspaceCatalogs(document);
+				inline = CatalogSet.fromCatalogs(inlineCatalogs(catalogBlocksOf(document)));
+				const injectedEntries = yield* hooks.inject(root, configDependenciesOf(document), inline.entries);
+				injected = CatalogSet.fromCatalogs(injectedEntries);
+			} else {
+				const manifestPath = path.join(root, "package.json");
+				if (!(yield* probeExists(manifestPath))) return fromLockfile;
+				const text = yield* fs.readFileString(manifestPath).pipe(Effect.mapError((cause) => new CatalogAssemblyError({
+					source: "manifest",
+					path: manifestPath,
+					cause
+				})));
+				inline = yield* CatalogSet.fromManifestWorkspaces(text);
+				injected = CatalogSet.empty();
+			}
+			const assembled = CatalogSet.merge(fromLockfile, inline, injected);
+			yield* Effect.logDebug("Catalogs assembled").pipe(Effect.annotateLogs({
+				"workspace.root": root,
+				"workspace.catalogs": Object.keys(assembled.entries).join(",")
+			}));
+			return assembled;
+		});
+		const [resolveOnce, invalidate] = yield* Effect.cachedInvalidateWithTTL(assemble, Duration.infinity);
+		const memo = Effect.onExit(resolveOnce, (exit) => Exit.isSuccess(exit) ? Effect.void : invalidate);
+		return {
+			set: Effect.fn("WorkspaceCatalogs.set")(function* () {
+				return yield* memo;
+			}),
+			resolveSpecifier: Effect.fn("WorkspaceCatalogs.resolveSpecifier")(function* (dependency, specifier) {
+				return (yield* memo).resolveSpecifier(dependency, specifier);
+			})
+		};
+	});
+	/**
+	* The live layer — the default, which **never executes config-dependency
+	* code**: it wires {@link ConfigDependencyHooks.layerNoop}, whose hooks return
+	* the inline-catalog seed untouched.
+	*
+	* @remarks
+	* Parameterized, so it mints a fresh reference per call — bind it to a
+	* `const` and reuse it, or layer memoization does not apply.
+	*/
+	static layer = (options) => Layer.effect(WorkspaceCatalogs, WorkspaceCatalogs.make(options)).pipe(Layer.provide(ConfigDependencyHooks.layerNoop));
+	/**
+	* The opt-in live layer that **does** replay config-dependency `pnpmfile.cjs`
+	* hooks: it wires {@link ConfigDependencyHooks.layerLive}, which dynamically
+	* imports and runs each config dependency's `updateConfig` in process.
+	*
+	* @remarks
+	* Same output and requirement set as {@link WorkspaceCatalogs.layer} — the only
+	* difference is that config-dependency code is executed. Use it deliberately;
+	* the default catalog path stays free of any config-dependency execution.
+	* Parameterized, so bind it to a `const` and reuse it.
+	*/
+	static layerWithConfigDependencies = (options) => Layer.effect(WorkspaceCatalogs, WorkspaceCatalogs.make(options)).pipe(Layer.provide(ConfigDependencyHooks.layerLive));
+	/**
+	* The real implementation of `@effected/npm`'s `CatalogResolver` contract —
+	* the one `@effected/package-json` declares but cannot fill.
+	*
+	* @remarks
+	* `rangeOf` returns `Option.none()` for a dependency no catalog declares, per
+	* the contract's convention; `DependencyResolutionError` is reserved for a
+	* failure of the resolution *mechanism* — an unfindable workspace root, an
+	* unreadable or malformed `pnpm-workspace.yaml`.
+	*/
+	static catalogResolver = Layer.effect(CatalogResolver, Effect.gen(function* () {
+		const catalogs = yield* WorkspaceCatalogs;
+		return { rangeOf: (packageName, catalog) => catalogs.set().pipe(Effect.map((set) => set.rangeOf(packageName, catalog)), Effect.mapError((cause) => new DependencyResolutionError({
+			specifier: Option.match(catalog, {
+				onNone: () => "catalog:",
+				onSome: (name) => `catalog:${name}`
+			}),
+			cause
+		}))) };
+	}));
+};
+
+//#endregion
+export { CatalogSet, WorkspaceCatalogs };