@effected/workspaces 0.1.0

package/CatalogAssemblyError.js

@@ -0,0 +1,43 @@
+import { Schema } from "effect";
+
+//#region src/CatalogAssemblyError.ts
+/**
+* Raised when a workspace's catalogs cannot be assembled — a `pnpm-workspace.yaml`
+* that is unreadable or not valid YAML, a root `package.json` `workspaces` field
+* whose shape or catalog blocks are malformed in a way pnpm itself rejects
+* (including the default catalog declared twice), or a config dependency whose
+* `pnpmfile.cjs` cannot be loaded or replayed.
+*
+* @remarks
+* A *missing* `pnpm-workspace.yaml`, an *absent* `workspaces` field, or one
+* explicitly `null` is not an error: there is simply nothing to misread, so
+* assembly yields the empty set. The reader is otherwise **hard-fail by design** —
+* a silently-empty catalog read is the "every dependency looks newly added" bug,
+* because catalog output is load-bearing for snapshot diffing.
+*
+* @public
+*/
+var CatalogAssemblyError = class extends Schema.TaggedErrorClass()("CatalogAssemblyError", {
+	/**
+	* Which input failed: `manifest` for a file-level or top-level shape problem,
+	* `catalog` for a malformed catalog block or the double-default duplication,
+	* `hooks` for a config-dependency `pnpmfile.cjs` load or replay failure.
+	*/
+	source: Schema.Literals([
+		"manifest",
+		"catalog",
+		"hooks"
+	]),
+	/** The file, the catalog name, or the config dependency name. */
+	path: Schema.String,
+	/** The originating failure. */
+	cause: Schema.Defect()
+}) {
+	/** Renders the failing source into a one-line message. */
+	get message() {
+		return `Failed to assemble catalogs from ${this.source} ${this.path}`;
+	}
+};
+
+//#endregion
+export { CatalogAssemblyError };

package/ChangeDetector.js

@@ -0,0 +1,154 @@
+import { WorkspaceDiscovery } from "./WorkspaceDiscovery.js";
+import { DependencyGraph } from "./DependencyGraph.js";
+import { Context, Effect, Layer, Schema } from "effect";
+import { Git } from "@effected/git";
+
+//#region src/ChangeDetector.ts
+/**
+* Which git refs to compare, and whether to fold in the working tree.
+*
+* @example
+* ```ts
+* import { ChangeDetectionOptions } from "@effected/workspaces";
+*
+* ChangeDetectionOptions.make({});                       // HEAD~1...HEAD
+* ChangeDetectionOptions.make({ base: "origin/main" });  // against a branch
+* ```
+*
+* @public
+*/
+var ChangeDetectionOptions = class extends Schema.Class("ChangeDetectionOptions")({
+	/**
+	* The ref to compare against.
+	*
+	* @defaultValue `"HEAD~1"`
+	*/
+	base: Schema.String.pipe(Schema.withDecodingDefaultKey(Effect.succeed("HEAD~1")), Schema.withConstructorDefault(Effect.succeed("HEAD~1"))),
+	/**
+	* The ref to compare to.
+	*
+	* @defaultValue `"HEAD"`
+	*/
+	head: Schema.String.pipe(Schema.withDecodingDefaultKey(Effect.succeed("HEAD")), Schema.withConstructorDefault(Effect.succeed("HEAD"))),
+	/**
+	* Whether to include staged, unstaged and untracked working-tree changes on
+	* top of the committed range.
+	*
+	* @defaultValue `false`
+	*/
+	includeUncommitted: Schema.Boolean.pipe(Schema.withDecodingDefaultKey(Effect.succeed(false)), Schema.withConstructorDefault(Effect.succeed(false)))
+}) {};
+/**
+* Raised when change detection cannot proceed for a reason that is not one of
+* git's own typed failures — the wrapper for "detection has no ground to stand
+* on".
+*
+* @remarks
+* A git command that merely *fails* surfaces as one of `@effected/git`'s typed
+* errors ({@link ChangeDetectionFailure} carries `GitCommandError`,
+* `NotARepositoryError` and `UnknownRefError`) rather than being flattened into
+* this wrapper — a caller branches on git's taxonomy directly.
+*
+* @public
+*/
+var ChangeDetectionError = class extends Schema.TaggedErrorClass()("ChangeDetectionError", {
+	/** The operation that could not run. */
+	operation: Schema.String,
+	/** The originating failure. */
+	cause: Schema.Defect()
+}) {
+	/** Renders the failed operation into a one-line message. */
+	get message() {
+		return `Change detection failed during ${this.operation}`;
+	}
+};
+/**
+* Detects which workspace packages a git range touches.
+*
+* @remarks
+* Three depths on one service, cheapest first — raw file paths, the packages
+* owning them, and the transitive blast radius through the dependency graph.
+*
+* @example
+* ```ts
+* import { ChangeDetectionOptions, ChangeDetector } from "@effected/workspaces";
+* import { Effect } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const detector = yield* ChangeDetector;
+*   const affected = yield* detector.affectedPackages(
+*     ChangeDetectionOptions.make({ base: "origin/main" }),
+*   );
+*   return affected.map((pkg) => pkg.name);
+* });
+* ```
+*
+* @public
+*/
+var ChangeDetector = class ChangeDetector extends Context.Service()("@effected/workspaces/ChangeDetector") {
+	/** Builds the service over `Git` and {@link WorkspaceDiscovery}. */
+	static make = Effect.gen(function* () {
+		const git = yield* Git;
+		const discovery = yield* WorkspaceDiscovery;
+		/**
+		* The changed files of the range, plus the working tree when asked.
+		*
+		* Every query runs with `relative: true`, so `Git` reports paths relative
+		* to `cwd` — the workspace root — and excludes changes outside it. That is
+		* what makes a workspace nested inside a larger git repository correct:
+		* without it, `git diff` reports repository-top-level paths that resolve to
+		* nothing under the workspace root. `Git` owns the `--relative` mechanics;
+		* this detector only asks for the relative mode.
+		*/
+		const filesOf = (root, options) => Effect.gen(function* () {
+			const committed = yield* git.changedFiles(root, {
+				base: options.base,
+				head: options.head,
+				relative: true
+			});
+			if (!options.includeUncommitted) return [...committed].sort();
+			const working = yield* git.workingChanges(root, { relative: true });
+			return [.../* @__PURE__ */ new Set([...committed, ...working])].sort();
+		});
+		/**
+		* Every git query above reports paths relative to `cwd` — the workspace
+		* root — so the workspace root is the correct bridge to the absolute paths
+		* discovery indexes by. That holds whether or not the workspace root and
+		* the git root coincide, which is the point: a workspace nested inside a
+		* larger repository is legitimate.
+		*/
+		const rootOf = () => discovery.info().pipe(Effect.map((info) => info.root));
+		const packagesOf = (options) => Effect.gen(function* () {
+			const root = yield* rootOf();
+			const absolute = (yield* filesOf(root, options)).map((file) => file.startsWith("/") ? file : `${root}/${file}`);
+			return yield* discovery.resolveFiles(absolute);
+		});
+		return {
+			changedFiles: Effect.fn("ChangeDetector.changedFiles")(function* (options) {
+				const root = yield* rootOf();
+				const files = yield* filesOf(root, options ?? ChangeDetectionOptions.make({}));
+				yield* Effect.logDebug("Changed files detected").pipe(Effect.annotateLogs("workspace.files.count", files.length));
+				return files;
+			}),
+			changedPackages: Effect.fn("ChangeDetector.changedPackages")(function* (options) {
+				const packages = yield* packagesOf(options ?? ChangeDetectionOptions.make({}));
+				yield* Effect.logDebug("Changed packages detected").pipe(Effect.annotateLogs("workspace.packages.count", packages.length));
+				return packages;
+			}),
+			affectedPackages: Effect.fn("ChangeDetector.affectedPackages")(function* (options) {
+				const changed = yield* packagesOf(options ?? ChangeDetectionOptions.make({}));
+				const all = yield* discovery.listPackages();
+				const names = yield* DependencyGraph.make({ packages: all }).affectedBy(changed.map((pkg) => pkg.name));
+				const byName = new Map(all.map((pkg) => [pkg.name, pkg]));
+				const affected = names.map((name) => byName.get(name)).filter((pkg) => pkg !== void 0);
+				yield* Effect.logDebug("Affected packages detected").pipe(Effect.annotateLogs("workspace.packages.count", affected.length));
+				return affected;
+			})
+		};
+	});
+	/** The live layer. */
+	static layer = Layer.effect(ChangeDetector, ChangeDetector.make);
+};
+
+//#endregion
+export { ChangeDetectionError, ChangeDetectionOptions, ChangeDetector };

package/ConfigDependencyHooks.js

@@ -0,0 +1,153 @@
+import { CatalogAssemblyError } from "./CatalogAssemblyError.js";
+import { normalize } from "./internal/catalogs.js";
+import { Context, Effect, Layer, Predicate, Result } from "effect";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+//#region src/ConfigDependencyHooks.ts
+/** Whether `value` is a non-null, non-array object. */
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+* The file URL a Node ESM `ERR_MODULE_NOT_FOUND` reports as unresolvable, or
+* `undefined` when the failure is anything else.
+*
+* @remarks
+* Node sets `err.url` (an own string property) to the offending module's URL.
+* For an absent *entry* module it is that entry's own URL; for a module the entry
+* `import`s that fails to resolve it is the **nested** module's URL. That
+* distinction is exactly what separates "this pnpmfile does not exist" (a
+* legitimate skip, `err.url` equal to the candidate) from "the pnpmfile's own
+* import failed to resolve" (a real error, `err.url` pointing elsewhere) — a
+* discrimination `err.code` alone cannot make, since both raise
+* `ERR_MODULE_NOT_FOUND`. Verified against Node's ESM loader: the entry-absent
+* case yields `err.url === pathToFileURL(candidate).href`; the nested case yields
+* the nested module's URL.
+*/
+const moduleNotFoundUrl = (cause) => isObject(cause) && cause.code === "ERR_MODULE_NOT_FOUND" && typeof cause.url === "string" ? cause.url : void 0;
+/**
+* Whether a config-dependency `name` carries a `..` path segment. A scoped name
+* legitimately contains `/` (`@scope/pkg`), so only a `..` *segment* is rejected —
+* it would traverse out of `.pnpm-config` and feed an attacker-chosen path to the
+* dynamic `import()` below.
+*/
+const hasTraversalSegment = (name) => name.split(/[/\\]/).includes("..");
+/** Turn the seed record into the pnpm hook config, with the default catalog split out under `catalog`. */
+const seedToConfig = (seed) => {
+	const catalogs = {};
+	let catalog = {};
+	for (const [name, entries] of Object.entries(seed)) if (name === "default") catalog = { ...entries };
+	else catalogs[name] = { ...entries };
+	return {
+		catalog,
+		catalogs
+	};
+};
+/** Read the catalog slice back out of whatever a hook returned, falling back to the prior config. */
+const configOf = (value, fallback) => {
+	if (!isObject(value)) return fallback;
+	return {
+		catalog: isObject(value.catalog) ? value.catalog : fallback.catalog,
+		catalogs: isObject(value.catalogs) ? value.catalogs : fallback.catalogs
+	};
+};
+/** Fold the hook config back into the normalized `catalog name → dependency → range` record. */
+const configToEntries = (config) => {
+	const raw = { ...config.catalogs };
+	if (Object.keys(config.catalog).length > 0) raw.default = {
+		...isObject(raw.default) ? raw.default : {},
+		...config.catalog
+	};
+	return normalize(raw);
+};
+/** Locate the `updateConfig` hook across the CJS/ESM export shapes a `pnpmfile.cjs` can present. */
+const updateConfigOf = (mod) => {
+	for (const candidate of [mod, isObject(mod) ? mod.default : void 0]) {
+		if (!isObject(candidate)) continue;
+		const hooks = candidate.hooks;
+		if (isObject(hooks) && Predicate.isFunction(hooks.updateConfig)) return hooks.updateConfig;
+		if (Predicate.isFunction(candidate.updateConfig)) return candidate.updateConfig;
+	}
+};
+/**
+* Replays a workspace's `configDependencies` `updateConfig` hooks over the inline
+* catalogs — the opt-in seam that lets hook-injected catalogs participate in
+* assembly.
+*
+* @remarks
+* A contract-only service: it declares the shape and ships two layers, never a
+* baked-in default. {@link ConfigDependencyHooks.layerNoop} executes no
+* config-dependency code (it returns the seed untouched) and is what the default
+* {@link WorkspaceCatalogs} layer wires; {@link ConfigDependencyHooks.layerLive}
+* dynamically imports each `pnpmfile.cjs` and replays it, and is wired only by the
+* explicit `WorkspaceCatalogs.layerWithConfigDependencies` opt-in.
+*
+* @public
+*/
+var ConfigDependencyHooks = class ConfigDependencyHooks extends Context.Service()("@effected/workspaces/ConfigDependencyHooks") {
+	/**
+	* The no-op layer: `inject` returns the seed unchanged and never touches a
+	* config dependency. The default {@link WorkspaceCatalogs} layer wires this, so
+	* the default catalog path provably executes no config-dependency code.
+	*/
+	static layerNoop = Layer.succeed(ConfigDependencyHooks, { inject: (_root, _configDependencies, seed) => Effect.succeed(seed) });
+	/**
+	* The live layer: dynamically imports each config dependency's `pnpmfile.cjs`
+	* (in process, no subprocess) and replays its `updateConfig` hook over the
+	* seed, in declaration order. A dependency without a `pnpmfile.cjs` contributes
+	* nothing; a dependency whose file fails to load or replay fails typed with a
+	* `hooks`-source {@link CatalogAssemblyError}, never a silent skip.
+	*
+	* @remarks
+	* Node-coupled by design — the `node:fs` / `node:path` / `node:url` imports are
+	* the sanctioned Node-only overlay, matching the other seams here. Only ever
+	* wired by `WorkspaceCatalogs.layerWithConfigDependencies`.
+	*/
+	static layerLive = Layer.succeed(ConfigDependencyHooks, { inject: (root, configDependencies, seed) => Effect.gen(function* () {
+		const names = Object.keys(configDependencies);
+		if (names.length === 0) return seed;
+		let config = seedToConfig(seed);
+		for (const name of names) {
+			if (hasTraversalSegment(name)) return yield* Effect.fail(new CatalogAssemblyError({
+				source: "hooks",
+				path: name,
+				cause: /* @__PURE__ */ new Error(`config dependency name has a '..' path segment: ${name}`)
+			}));
+			let loaded;
+			let found = false;
+			for (const filename of ["pnpmfile.mjs", "pnpmfile.cjs"]) {
+				const candidateUrl = pathToFileURL(join(root, "node_modules", ".pnpm-config", name, filename)).href;
+				const result = yield* Effect.result(Effect.tryPromise({
+					try: () => import(candidateUrl),
+					catch: (cause) => cause
+				}));
+				if (Result.isSuccess(result)) {
+					loaded = result.success;
+					found = true;
+					break;
+				}
+				if (moduleNotFoundUrl(result.failure) === candidateUrl) continue;
+				return yield* Effect.fail(new CatalogAssemblyError({
+					source: "hooks",
+					path: name,
+					cause: result.failure
+				}));
+			}
+			if (!found) continue;
+			const updateConfig = updateConfigOf(loaded);
+			if (updateConfig === void 0) continue;
+			const currentConfig = config;
+			config = yield* Effect.try({
+				try: () => configOf(updateConfig(currentConfig), currentConfig),
+				catch: (cause) => new CatalogAssemblyError({
+					source: "hooks",
+					path: name,
+					cause
+				})
+			});
+		}
+		return configToEntries(config);
+	}) });
+};
+
+//#endregion
+export { ConfigDependencyHooks };

package/DependencyGraph.js

@@ -0,0 +1,241 @@
+import { WorkspacePackage } from "./WorkspacePackage.js";
+import { PackageNotFoundError } from "./WorkspaceDiscovery.js";
+import { Effect, Schema } from "effect";
+
+//#region src/DependencyGraph.ts
+/**
+* Raised when the workspace dependency graph cannot be topologically ordered
+* because it contains a cycle.
+*
+* @remarks
+* `cycle` lists every package still carrying unsatisfied dependencies when
+* Kahn's algorithm stalls — the strongly-connected residue, sorted. It is the
+* set to break, not necessarily a single ordered loop.
+*
+* @public
+*/
+var CyclicDependencyError = class extends Schema.TaggedErrorClass()("CyclicDependencyError", { 
+/** The packages participating in the cycle. */
+cycle: Schema.Array(Schema.String) }) {
+	/** Renders the cycle members into a one-line message. */
+	get message() {
+		return `Cyclic workspace dependencies among: ${this.cycle.join(", ")}`;
+	}
+};
+/**
+* The directed graph of dependencies **between workspace packages**. External
+* npm dependencies are not nodes.
+*
+* @remarks
+* A pure value over the discovered package list, with the edge indexes built
+* lazily into `#private` fields the schema never encodes. Edges are drawn from
+* `dependencies`, `devDependencies`, `peerDependencies` and
+* `optionalDependencies`; a self-edge is dropped.
+*
+* Total accessors never fail; the four fallible operations are `Effect.fn`
+* boundaries.
+*
+* @example
+* ```ts
+* import { DependencyGraph, WorkspaceDiscovery } from "@effected/workspaces";
+* import { Effect } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const discovery = yield* WorkspaceDiscovery;
+*   const graph = DependencyGraph.make({ packages: yield* discovery.listPackages() });
+*   return yield* graph.levels();
+* });
+* ```
+*
+* @public
+*/
+var DependencyGraph = class extends Schema.Class("DependencyGraph")({ 
+/** The workspace packages the graph is drawn over. */
+packages: Schema.Array(WorkspacePackage) }) {
+	#edges;
+	#index() {
+		if (this.#edges !== void 0) return this.#edges;
+		const names = new Set(this.packages.map((pkg) => pkg.name));
+		const forward = /* @__PURE__ */ new Map();
+		const reverse = /* @__PURE__ */ new Map();
+		for (const name of names) {
+			forward.set(name, /* @__PURE__ */ new Set());
+			reverse.set(name, /* @__PURE__ */ new Set());
+		}
+		for (const pkg of this.packages) for (const dependency of Object.keys(pkg.allDependencies)) {
+			if (!names.has(dependency) || dependency === pkg.name) continue;
+			forward.get(pkg.name)?.add(dependency);
+			reverse.get(dependency)?.add(pkg.name);
+		}
+		this.#edges = {
+			forward,
+			reverse
+		};
+		return this.#edges;
+	}
+	/** Every workspace package name, sorted. Total. */
+	get names() {
+		return [...this.#index().forward.keys()].sort();
+	}
+	/** The adjacency map: name → the names it depends on. Total. */
+	get adjacency() {
+		return this.#index().forward;
+	}
+	/**
+	* Whether the graph contains a cycle. Total.
+	*
+	* @remarks
+	* An explicit-stack DFS with an on-stack set — never recursive, so a long
+	* dependency chain cannot overflow.
+	*/
+	get hasCycle() {
+		const { forward } = this.#index();
+		const visited = /* @__PURE__ */ new Set();
+		const onStack = /* @__PURE__ */ new Set();
+		for (const start of forward.keys()) {
+			if (visited.has(start)) continue;
+			const stack = [{
+				node: start,
+				deps: [...forward.get(start) ?? []],
+				cursor: 0
+			}];
+			visited.add(start);
+			onStack.add(start);
+			while (stack.length > 0) {
+				const frame = stack[stack.length - 1];
+				if (frame.cursor >= frame.deps.length) {
+					onStack.delete(frame.node);
+					stack.pop();
+					continue;
+				}
+				const next = frame.deps[frame.cursor];
+				frame.cursor += 1;
+				if (onStack.has(next)) return true;
+				if (visited.has(next)) continue;
+				visited.add(next);
+				onStack.add(next);
+				stack.push({
+					node: next,
+					deps: [...forward.get(next) ?? []],
+					cursor: 0
+				});
+			}
+		}
+		return false;
+	}
+	/** The workspace packages `name` depends on, sorted. */
+	dependenciesOf = Effect.fn("DependencyGraph.dependenciesOf")((name) => {
+		const deps = this.#index().forward.get(name);
+		return deps === void 0 ? Effect.fail(new PackageNotFoundError({
+			name,
+			available: this.names
+		})) : Effect.succeed([...deps].sort());
+	});
+	/** The workspace packages that depend on `name`, sorted. */
+	dependentsOf = Effect.fn("DependencyGraph.dependentsOf")((name) => {
+		const dependents = this.#index().reverse.get(name);
+		return dependents === void 0 ? Effect.fail(new PackageNotFoundError({
+			name,
+			available: this.names
+		})) : Effect.succeed([...dependents].sort());
+	});
+	/**
+	* `name` plus every package that transitively depends on it — the blast
+	* radius of a change. Sorted; includes `name` itself.
+	*/
+	affectedBy = Effect.fn("DependencyGraph.affectedBy")((names) => {
+		const { reverse } = this.#index();
+		const affected = /* @__PURE__ */ new Set();
+		const queue = [...names];
+		while (queue.length > 0) {
+			const current = queue.shift();
+			/* v8 ignore next */
+			if (current === void 0) break;
+			if (affected.has(current)) continue;
+			affected.add(current);
+			for (const dependent of reverse.get(current) ?? []) if (!affected.has(dependent)) queue.push(dependent);
+		}
+		return Effect.succeed([...affected].sort());
+	});
+	/**
+	* Packages grouped into parallel build levels: level 0 depends on nothing in
+	* the workspace, level *n* depends only on levels below it.
+	*
+	* @remarks
+	* Kahn's algorithm over the reverse-edge index — linear, where v3's rescanned
+	* the whole adjacency map per processed node. Each level is sorted
+	* lexicographically, so the output is deterministic.
+	*/
+	levels = Effect.fn("DependencyGraph.levels")(() => Effect.suspend(() => Effect.succeed(kahn(this.#index()))).pipe(Effect.flatMap((result) => result.stalled.length > 0 ? Effect.fail(new CyclicDependencyError({ cycle: result.stalled })) : Effect.succeed(result.levels))));
+	/** The flattened topological order — `levels()` concatenated. */
+	sort = Effect.fn("DependencyGraph.sort")(() => this.levels().pipe(Effect.map((levels) => levels.flat())));
+	/**
+	* A topological order over `names` plus their transitive workspace
+	* dependencies — the build order for a subset.
+	*/
+	sortSubset = Effect.fn("DependencyGraph.sortSubset")((names) => Effect.suspend(() => {
+		const { forward } = this.#index();
+		for (const name of names) if (!forward.has(name)) return Effect.fail(new PackageNotFoundError({
+			name,
+			available: this.names
+		}));
+		const needed = /* @__PURE__ */ new Set();
+		const queue = [...names];
+		while (queue.length > 0) {
+			const current = queue.shift();
+			/* v8 ignore next */
+			if (current === void 0) break;
+			if (needed.has(current)) continue;
+			needed.add(current);
+			for (const dependency of forward.get(current) ?? []) if (!needed.has(dependency)) queue.push(dependency);
+		}
+		const subForward = /* @__PURE__ */ new Map();
+		const subReverse = /* @__PURE__ */ new Map();
+		for (const node of needed) subReverse.set(node, /* @__PURE__ */ new Set());
+		for (const node of needed) {
+			const deps = new Set([...forward.get(node) ?? []].filter((dep) => needed.has(dep)));
+			subForward.set(node, deps);
+			for (const dep of deps) subReverse.get(dep)?.add(node);
+		}
+		const result = kahn({
+			forward: subForward,
+			reverse: subReverse
+		});
+		return result.stalled.length > 0 ? Effect.fail(new CyclicDependencyError({ cycle: result.stalled })) : Effect.succeed(result.levels.flat());
+	}));
+};
+/**
+* Kahn's algorithm. `forward[A] = {B}` reads "A depends on B", so level 0 is
+* the set with an out-degree of zero and each completed level decrements its
+* dependents through the reverse index.
+*/
+const kahn = (edges) => {
+	const remaining = /* @__PURE__ */ new Map();
+	for (const [node, deps] of edges.forward) remaining.set(node, deps.size);
+	const levels = [];
+	let current = [...remaining.entries()].filter(([, count]) => count === 0).map(([node]) => node);
+	current.sort();
+	while (current.length > 0) {
+		levels.push(current);
+		const next = [];
+		for (const done of current) {
+			remaining.delete(done);
+			for (const dependent of edges.reverse.get(done) ?? []) {
+				const count = remaining.get(dependent);
+				if (count === void 0) continue;
+				const decremented = count - 1;
+				remaining.set(dependent, decremented);
+				if (decremented === 0) next.push(dependent);
+			}
+		}
+		next.sort();
+		current = next;
+	}
+	return {
+		levels,
+		stalled: [...remaining.keys()].sort()
+	};
+};
+
+//#endregion
+export { CyclicDependencyError, DependencyGraph };

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C. Spencer Beggs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.