@effected/workspaces 0.11.2 → 0.12.0

package/DependencyGraph.js

@@ -1,6 +1,6 @@
 import { WorkspacePackage } from "./WorkspacePackage.js";
 import { PackageNotFoundError } from "./WorkspaceDiscovery.js";
-import { Effect, Schema } from "effect";
+import { Effect, Graph, Schema } from "effect";
 
 //#region src/DependencyGraph.ts
 /**
@@ -8,9 +8,10 @@ import { Effect, Schema } from "effect";
 * 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.
+* `cycle` names the actual cycle members — the sorted union of every strongly
+* connected component with more than one package. Packages merely downstream
+* of a cycle are excluded, so it is exactly the set to break, not necessarily
+* a single ordered loop.
 *
 * @public
 */
@@ -165,7 +166,11 @@ packages: Schema.Array(WorkspacePackage) }) {
 	* 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))));
+	levels = Effect.fn("DependencyGraph.levels")(() => Effect.suspend(() => {
+		const edges = this.#index();
+		const result = kahn(edges);
+		return result.stalled.length > 0 ? Effect.fail(new CyclicDependencyError({ cycle: cycleMembers(edges) })) : Effect.succeed(result.levels);
+	}));
 	/** The flattened topological order — `levels()` concatenated. */
 	sort = Effect.fn("DependencyGraph.sort")(() => this.levels().pipe(Effect.map((levels) => levels.flat())));
 	/**
@@ -195,17 +200,78 @@ packages: Schema.Array(WorkspacePackage) }) {
 			subForward.set(node, deps);
 			for (const dep of deps) subReverse.get(dep)?.add(node);
 		}
-		const result = kahn({
+		const subEdges = {
 			forward: subForward,
 			reverse: subReverse
-		});
-		return result.stalled.length > 0 ? Effect.fail(new CyclicDependencyError({ cycle: result.stalled })) : Effect.succeed(result.levels.flat());
+		};
+		const result = kahn(subEdges);
+		return result.stalled.length > 0 ? Effect.fail(new CyclicDependencyError({ cycle: cycleMembers(subEdges) })) : Effect.succeed(result.levels.flat());
 	}));
+	/**
+	* The graph rendered as a Mermaid `flowchart TD`. Total.
+	*
+	* @remarks
+	* Renders through core's `Graph.toMermaid` over a transient graph built from
+	* the edge index. Node IDs are numeric indexes assigned in sorted-name order
+	* and package names appear only inside quoted labels, so scoped names
+	* (`@scope/a`) never break Mermaid syntax. Nodes and each node's edges are
+	* emitted in sorted order — the output is deterministic regardless of
+	* manifest key order.
+	*/
+	toMermaid() {
+		return Graph.toMermaid(materialize(this.#index()).graph, { edgeLabel: () => "" });
+	}
+};
+/**
+* Materializes the forward map into a transient core `Graph`: nodes in
+* sorted-name order (so `NodeIndex` *i* is `names[i]`) and each node's edges
+* in sorted-target order, making the graph — and everything derived from it —
+* deterministic for a given edge index.
+*/
+const materialize = (edges) => {
+	const names = [...edges.forward.keys()].sort();
+	return {
+		graph: Graph.directed((mutable) => {
+			const indexOf = /* @__PURE__ */ new Map();
+			for (const name of names) indexOf.set(name, Graph.addNode(mutable, name));
+			for (const name of names) {
+				const source = indexOf.get(name);
+				if (source === void 0) continue;
+				for (const dependency of [...edges.forward.get(name) ?? []].sort()) {
+					const target = indexOf.get(dependency);
+					if (target !== void 0) Graph.addEdge(mutable, source, target, "");
+				}
+			}
+		}),
+		names
+	};
+};
+/**
+* The packages participating in a dependency cycle — the sorted union of every
+* strongly connected component with more than one member, via core's
+* `Graph.stronglyConnectedComponents`. Self-edges are dropped at index time,
+* so a single-member component is never cyclic here.
+*/
+const cycleMembers = (edges) => {
+	const { graph, names } = materialize(edges);
+	const members = /* @__PURE__ */ new Set();
+	for (const component of Graph.stronglyConnectedComponents(graph)) {
+		if (component.length < 2) continue;
+		for (const index of component) {
+			const name = names[index];
+			if (name !== void 0) members.add(name);
+		}
+	}
+	return [...members].sort();
 };
 /**
 * 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.
+*
+* A non-empty `stalled` only signals *that* a cycle exists — it holds every
+* unprocessed node, including ones merely downstream of a cycle. The error
+* payload names the actual members via `cycleMembers`.
 */
 const kahn = (edges) => {
 	const remaining = /* @__PURE__ */ new Map();

package/README.md

@@ -70,7 +70,17 @@ Effect.runPromise(program.pipe(Effect.provide(WorkspacesLayer))).then(console.lo
 // [ [ ...names with no workspace dependencies ], [ ...names that depend only on level 0 ], ... ]
 ```
 
-`DependencyGraph` is a value class, not a service: build it from packages you already have. A cycle fails with `CyclicDependencyError` naming the packages that could not be ordered.
+`DependencyGraph` is a value class, not a service: build it from packages you already have. A cycle fails with `CyclicDependencyError`, whose `cycle` field names the packages actually in the cycle — the members of the strongly-connected components — and not the ones merely stalled behind it, which is the difference between a fix list and a suspect list.
+
+`toMermaid()` renders the same graph for a job summary, an issue or a design doc. It is total, deterministic (nodes and edges both in sorted order) and safe for scoped names, which appear only inside quoted labels:
+
+```ts
+console.log(graph.toMermaid());
+// flowchart TD
+//   0["@acme/app"]
+//   1["@acme/utils"]
+//   0 --> 1
+```
 
 ## Change detection
 
@@ -228,7 +238,7 @@ A name miss in the derived `getPackage` fails with the service's own typed `Pack
 - `WorkspaceRoot` — root discovery from a `cwd`, over `WORKSPACE_MARKERS`.
 - `WorkspaceDiscovery` — package enumeration with a bounded descent for segment-crossing `packages/**` patterns, per-package lookup and the `makeTest` / `layerTest` in-memory test doubles.
 - `WorkspacePackage` — a deliberately tolerant manifest model, so one member with an odd version cannot fail discovery for the whole repo. `manifestRecord` keeps the as-read `package.json` for tolerant access to fields outside the typed slice without a second read; `WorkspacePackage.manifest(pkg)` re-reads and is the opt-in bridge to `@effected/package-json`'s strict `Package`.
-- `DependencyGraph` — a value class over discovered packages: `levels()` for parallel build tiers, the flattened topological order, and `CyclicDependencyError` when there isn't one.
+- `DependencyGraph` — a value class over discovered packages: `levels()` for parallel build tiers, the flattened topological order, `toMermaid()` for a deterministic Mermaid `flowchart TD` of the whole graph, and `CyclicDependencyError` — naming the cycle's actual members — when there is no order.
 - `PackageManagerDetector` — npm, pnpm, yarn or bun from lockfiles and the `packageManager` field.
 - `WorkspaceCatalogs` — pnpm catalog assembly and `catalog:` resolution, on pnpm's own catalog packages; `releaseAgeGate()` assembles the effective `@effected/npm` `ReleaseAgeGate` from inline `pnpm-workspace.yaml` release-age keys and replayed hook contributions, strictest-wins, in the same pass as the catalogs.
 - `LockfileReader` — locate and parse the workspace's lockfile through `@effected/lockfiles`.

package/index.d.ts

@@ -960,9 +960,10 @@ declare const CyclicDependencyError_base: Schema.Class<CyclicDependencyError, Sc
  * 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.
+ * `cycle` names the actual cycle members — the sorted union of every strongly
+ * connected component with more than one package. Packages merely downstream
+ * of a cycle are excluded, so it is exactly the set to break, not necessarily
+ * a single ordered loop.
  *
  * @public
  */
@@ -1041,6 +1042,18 @@ declare class DependencyGraph extends DependencyGraph_base {
    * dependencies — the build order for a subset.
    */
   readonly sortSubset: (names: readonly string[]) => Effect.Effect<readonly string[], CyclicDependencyError | PackageNotFoundError, never>;
+  /**
+   * The graph rendered as a Mermaid `flowchart TD`. Total.
+   *
+   * @remarks
+   * Renders through core's `Graph.toMermaid` over a transient graph built from
+   * the edge index. Node IDs are numeric indexes assigned in sorted-name order
+   * and package names appear only inside quoted labels, so scoped names
+   * (`@scope/a`) never break Mermaid syntax. Nodes and each node's edges are
+   * emitted in sorted order — the output is deterministic regardless of
+   * manifest key order.
+   */
+  toMermaid(): string;
 }
 //#endregion
 //#region src/PackageManagerName.d.ts

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/workspaces",
-	"version": "0.11.2",
+	"version": "0.12.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": [