@effected/workspaces 0.14.2 → 0.15.0

package/ConfigDependencyHooks.js

@@ -7,6 +7,27 @@ import { Run } from "@effected/commands";
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
 
 //#region src/ConfigDependencyHooks.ts
+/**
+* The empty {@link PeerDependencyRules}: every axis present and empty.
+*
+* @remarks
+* Exported so that "I assert this workspace's rules are empty" is **one token**
+* rather than three hand-written empty axes. That matters where the distinction
+* is load-bearing — supplying rules asserts they were looked up, while omitting
+* them asserts nothing — and a caller spelling the object out by hand will
+* eventually fill two of the three axes and mean the third.
+*
+* Frozen, since it is shared.
+*
+* @public
+*/
+const NoPeerDependencyRules = Object.freeze({
+	allowedVersions: Object.freeze({}),
+	ignoreMissing: Object.freeze([]),
+	allowAny: Object.freeze([])
+});
+/** Internal alias, kept short at the many call sites in this module. */
+const NO_PEER_RULES = NoPeerDependencyRules;
 /** Whether `value` is a non-null, non-array object. */
 const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /**
@@ -34,7 +55,7 @@ const moduleNotFoundUrl = (cause) => isObject(cause) && cause.code === "ERR_MODU
 */
 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 seedToConfig = (seed, rules) => {
 	const catalogs = {};
 	let catalog = {};
 	for (const [name, entries] of Object.entries(seed)) if (name === "default") catalog = { ...entries };
@@ -43,7 +64,8 @@ const seedToConfig = (seed) => {
 		catalog,
 		catalogs,
 		minimumReleaseAge: void 0,
-		minimumReleaseAgeExclude: void 0
+		minimumReleaseAgeExclude: void 0,
+		peerDependencyRules: rules
 	};
 };
 /** A finite number if `value` is one, else the prior threaded value — a garbage age is dropped, not fatal. */
@@ -68,9 +90,32 @@ const configOf = (value, fallback) => {
 		catalog: isObject(value.catalog) ? value.catalog : fallback.catalog,
 		catalogs: isObject(value.catalogs) ? value.catalogs : fallback.catalogs,
 		minimumReleaseAge: finiteNumberOr(value.minimumReleaseAge, fallback.minimumReleaseAge),
-		minimumReleaseAgeExclude: stringArrayOr(value.minimumReleaseAgeExclude, fallback.minimumReleaseAgeExclude)
+		minimumReleaseAgeExclude: stringArrayOr(value.minimumReleaseAgeExclude, fallback.minimumReleaseAgeExclude),
+		peerDependencyRules: peerRulesOr(value.peerDependencyRules, fallback.peerDependencyRules)
+	};
+};
+/**
+* A peer-rules block if `value` is one, else the prior threaded value — a
+* malformed block is dropped, not fatal, matching the other slices.
+*
+* Each axis is normalized independently: a hook that rewrites `allowedVersions`
+* and leaves `ignoreMissing` alone must not blank the latter.
+*/
+const stringRecordOr = (value, fallback) => isObject(value) && Object.values(value).every((entry) => typeof entry === "string") ? value : fallback;
+const peerRulesOr = (value, fallback) => {
+	if (!isObject(value)) return fallback;
+	const allowed = stringRecordOr(value.allowedVersions, fallback?.allowedVersions);
+	const ignoreMissing = stringArrayOr(value.ignoreMissing, fallback?.ignoreMissing);
+	const allowAny = stringArrayOr(value.allowAny, fallback?.allowAny);
+	if (allowed === void 0 && ignoreMissing === void 0 && allowAny === void 0) return fallback;
+	return {
+		allowedVersions: allowed ?? {},
+		ignoreMissing: ignoreMissing ?? [],
+		allowAny: allowAny ?? []
 	};
 };
+/** Project the threaded config's rules into the slice, defaulting every axis to empty. */
+const peerRulesOf = (config) => config.peerDependencyRules ?? NO_PEER_RULES;
 /**
 * Project the threaded config's release-age keys into a partial gate
 * contribution, omitting a key the hooks never set (never an explicit
@@ -124,13 +169,23 @@ const updateConfigOf = (mod) => {
 * noise on stdout.
 */
 const REPLAY_SCRIPT = `
-const [root, seedJson, ...names] = process.argv.slice(1);
+const [root, seedJson, rulesJson, ...names] = process.argv.slice(1);
 const { pathToFileURL } = await import("node:url");
 const { join } = await import("node:path");
 const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const finiteNumberOr = (value, fallback) => (typeof value === "number" && Number.isFinite(value) ? value : fallback);
 const stringArrayOr = (value, fallback) =>
 	Array.isArray(value) && value.every((entry) => typeof entry === "string") ? value : fallback;
+const stringRecordOr = (value, fallback) =>
+	isObject(value) && Object.values(value).every((entry) => typeof entry === "string") ? value : fallback;
+const peerRulesOr = (value, fallback) => {
+	if (!isObject(value)) return fallback;
+	const allowed = stringRecordOr(value.allowedVersions, fallback && fallback.allowedVersions);
+	const ignoreMissing = stringArrayOr(value.ignoreMissing, fallback && fallback.ignoreMissing);
+	const allowAny = stringArrayOr(value.allowAny, fallback && fallback.allowAny);
+	if (allowed === undefined && ignoreMissing === undefined && allowAny === undefined) return fallback;
+	return { allowedVersions: allowed || {}, ignoreMissing: ignoreMissing || [], allowAny: allowAny || [] };
+};
 const configOf = (value, fallback) =>
 	isObject(value)
 		? {
@@ -138,6 +193,7 @@ const configOf = (value, fallback) =>
 				catalogs: isObject(value.catalogs) ? value.catalogs : fallback.catalogs,
 				minimumReleaseAge: finiteNumberOr(value.minimumReleaseAge, fallback.minimumReleaseAge),
 				minimumReleaseAgeExclude: stringArrayOr(value.minimumReleaseAgeExclude, fallback.minimumReleaseAgeExclude),
+				peerDependencyRules: peerRulesOr(value.peerDependencyRules, fallback.peerDependencyRules),
 			}
 		: fallback;
 const failure = (name, cause) => ({
@@ -153,7 +209,13 @@ const replay = async () => {
 		if (name === "default") catalog = { ...entries };
 		else catalogs[name] = { ...entries };
 	}
-	let config = { catalog, catalogs, minimumReleaseAge: undefined, minimumReleaseAgeExclude: undefined };
+	let config = {
+		catalog,
+		catalogs,
+		minimumReleaseAge: undefined,
+		minimumReleaseAgeExclude: undefined,
+		peerDependencyRules: JSON.parse(rulesJson),
+	};
 	for (const name of names) {
 		let loaded;
 		let found = false;
@@ -254,9 +316,10 @@ var ConfigDependencyHooks = class ConfigDependencyHooks extends Context.Service(
 	* 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({
+	static layerNoop = Layer.succeed(ConfigDependencyHooks, { inject: (_root, _configDependencies, seed, rules) => Effect.succeed({
 		catalogs: seed,
-		releaseAge: {}
+		releaseAge: {},
+		peerDependencyRules: rules ?? NO_PEER_RULES
 	}) });
 	/**
 	* The live layer: dynamically imports each config dependency's `pnpmfile.cjs`
@@ -274,13 +337,14 @@ var ConfigDependencyHooks = class ConfigDependencyHooks extends Context.Service(
 	* import, so this layer runs on either runtime. Only ever wired by
 	* `WorkspaceCatalogs.layerWithConfigDependencies`.
 	*/
-	static layerLive = Layer.succeed(ConfigDependencyHooks, { inject: (root, configDependencies, seed) => Effect.gen(function* () {
+	static layerLive = Layer.succeed(ConfigDependencyHooks, { inject: (root, configDependencies, seed, rules) => Effect.gen(function* () {
 		const names = Object.keys(configDependencies);
 		if (names.length === 0) return {
 			catalogs: seed,
-			releaseAge: {}
+			releaseAge: {},
+			peerDependencyRules: rules ?? NO_PEER_RULES
 		};
-		let config = seedToConfig(seed);
+		let config = seedToConfig(seed, rules);
 		for (const name of names) {
 			if (hasTraversalSegment(name)) return yield* Effect.fail(new CatalogAssemblyError({
 				source: "hooks",
@@ -326,7 +390,8 @@ var ConfigDependencyHooks = class ConfigDependencyHooks extends Context.Service(
 		}
 		return {
 			catalogs: configToEntries(config),
-			releaseAge: releaseAgeOf(config)
+			releaseAge: releaseAgeOf(config),
+			peerDependencyRules: peerRulesOf(config)
 		};
 	}) });
 	/**
@@ -382,11 +447,12 @@ var ConfigDependencyHooks = class ConfigDependencyHooks extends Context.Service(
 	*/
 	static layerSubprocess = Layer.effect(ConfigDependencyHooks, Effect.gen(function* () {
 		const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
-		return { inject: (root, configDependencies, seed) => Effect.gen(function* () {
+		return { inject: (root, configDependencies, seed, rules) => Effect.gen(function* () {
 			const names = Object.keys(configDependencies);
 			if (names.length === 0) return {
 				catalogs: seed,
-				releaseAge: {}
+				releaseAge: {},
+				peerDependencyRules: rules ?? NO_PEER_RULES
 			};
 			for (const name of names) if (hasTraversalSegment(name)) return yield* Effect.fail(new CatalogAssemblyError({
 				source: "hooks",
@@ -399,6 +465,7 @@ var ConfigDependencyHooks = class ConfigDependencyHooks extends Context.Service(
 				REPLAY_SCRIPT,
 				root,
 				JSON.stringify(seed),
+				JSON.stringify(rules ?? NO_PEER_RULES),
 				...names
 			]);
 			const payload = yield* Run.jsonLine(command, ReplayPayload, { timeout: REPLAY_TIMEOUT }).pipe(Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner), Effect.catch((cause) => Effect.fail(new CatalogAssemblyError({
@@ -411,14 +478,15 @@ var ConfigDependencyHooks = class ConfigDependencyHooks extends Context.Service(
 				path: payload.name ?? root,
 				cause: replayFailureCause(payload)
 			}));
-			const config = configOf(payload.config, seedToConfig(seed));
+			const config = configOf(payload.config, seedToConfig(seed, rules));
 			return {
 				catalogs: configToEntries(config),
-				releaseAge: releaseAgeOf(config)
+				releaseAge: releaseAgeOf(config),
+				peerDependencyRules: peerRulesOf(config)
 			};
 		}) };
 	}));
 };
 
 //#endregion
-export { ConfigDependencyHooks };
+export { ConfigDependencyHooks, NoPeerDependencyRules };

package/PeerCheck.js

@@ -0,0 +1,391 @@
+import { Result, Schema } from "effect";
+import { Range, SemVer } from "@effected/semver";
+
+//#region src/PeerCheck.ts
+/**
+* One link in the chain from an importer to the package that declared an
+* unsatisfied peer.
+*
+* @remarks
+* Mirrors the shape `pnpm peers check --json` reports, so the two can be
+* compared directly.
+*
+* @public
+*/
+var PeerParent = class extends Schema.Class("PeerParent")({
+	/** The package name. */
+	name: Schema.NonEmptyString,
+	/** The resolved version of that package. */
+	version: Schema.String
+}) {};
+/**
+* One peer dependency that is declared but not satisfied.
+*
+* @remarks
+* `found` carries the version that actually resolved, or `null` when nothing
+* resolved at all. There is deliberately **no separate discriminant** between
+* "missing" and "unmet": `found === null` is the whole distinction, and a
+* renderer reads it directly.
+*
+* `optional` must be respected by any gate — an unsatisfied *optional* peer is
+* normal and should not fail a build, which is why the flag travels with the
+* row rather than being filtered out here. {@link PeerCheck.required} is the
+* convenience for the common case.
+*
+* `parents` is the path from the importer down to the package that declared
+* the peer, nearest-to-the-importer first. It is a path rather than a single
+* package because a peer declared by a transitive dependency is still that
+* importer's problem, and the chain is what makes the report actionable.
+*
+* A package an importer reaches by more than one path yields **one** row, not
+* one per path, carrying the path the walk reached first — which is what
+* `pnpm peers check` reports for the same graph. Read `parents` as *a* route to
+* the declaring package, never as the complete set of them.
+*
+* @public
+*/
+var UnsatisfiedPeer = class extends Schema.Class("UnsatisfiedPeer")({
+	/** The importer path the problem belongs to (`"."` for the root). */
+	importer: Schema.NonEmptyString,
+	/** The peer dependency's name. */
+	dependency: Schema.NonEmptyString,
+	/** The range the declaring package asked for. */
+	wanted: Schema.String,
+	/** The version that resolved, or `null` when nothing resolved. */
+	found: Schema.NullOr(Schema.String),
+	/** Whether the declaring package marked the peer optional. */
+	optional: Schema.Boolean,
+	/** The path from the importer to the declaring package. */
+	parents: Schema.Array(PeerParent)
+}) {};
+/**
+* The formats whose lockfiles record peer resolution.
+*
+* An allowlist rather than a `!== "yarn"` denylist, so a format added to
+* `Lockfile["format"]` is unsupported until someone says otherwise. A denylist
+* would report the new format `supported: true` with an empty `unsatisfied`
+* before any parser records peer resolution for it — a clean bill of health
+* produced by a limitation, which is the failure this module exists to avoid.
+*
+* @internal
+*/
+const PEER_RESOLVING_FORMATS = /* @__PURE__ */ new Set([
+	"npm",
+	"pnpm",
+	"bun"
+]);
+/** @internal */
+const supportsPeerResolution = (format) => PEER_RESOLVING_FORMATS.has(format);
+/**
+* The result of checking a lockfile for unsatisfied peer dependencies.
+*
+* @remarks
+* A report rather than a bare array, because an empty array is the most
+* dangerous success shape this domain has: it is indistinguishable from "this
+* format cannot be checked". `supported` and `unresolvedImporters` make the
+* difference legible, so a consumer cannot read a limitation as a clean bill
+* of health.
+*
+* Pure and total — construct it with {@link PeerCheck.run}, which never fails.
+*
+* @example
+* ```ts
+* import { PeerCheck } from "@effected/workspaces";
+* import { Lockfile } from "@effected/lockfiles";
+* import { Effect } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const lockfile = yield* Lockfile.parse(text, { format: "pnpm" });
+*   const report = PeerCheck.run(lockfile);
+*   return report.supported ? report.required : [];
+* });
+* ```
+*
+* @public
+*/
+var PeerCheck = class PeerCheck extends Schema.Class("PeerCheck")({
+	/**
+	* Whether the lockfile's format records peer resolution at all.
+	*
+	* `false` for yarn: yarn resolves peers **virtually**, giving a
+	* peer-bearing package one `@virtual:` locator per consumer, and the
+	* lockfile does not record which virtual instance satisfied which peer.
+	* The answer is not recoverable, so it is not fabricated — `unsatisfied`
+	* is empty and this flag says why.
+	*/
+	supported: Schema.Boolean,
+	/** Every unsatisfied peer found, optional ones included. */
+	unsatisfied: Schema.Array(UnsatisfiedPeer),
+	/**
+	* Importers whose dependencies could not be resolved to instances, so no
+	* verdict was reached for them.
+	*
+	* @remarks
+	* In practice this is the **root importer under npm and bun**: neither
+	* records a resolved version per importer dependency, and neither emits a
+	* package row for the root, so there is nothing to join on. pnpm records a
+	* version per importer dependency and is unaffected.
+	*
+	* Reported rather than silently skipped, for the same reason `supported`
+	* exists: a gate that sees no rows is entitled to know whether that means
+	* "clean" or "not looked at".
+	*/
+	unresolvedImporters: Schema.Array(Schema.String),
+	/**
+	* Why this report is not a complete answer, or empty when it is.
+	*
+	* @remarks
+	* See {@link UnverifiedReason}. A gate must treat a non-empty `unverified`
+	* as **not proven clean** rather than as a pass: both reasons mean some
+	* finding may be missing or spurious, and failing closed is the requirement.
+	*/
+	unverified: Schema.Array(Schema.Literals(["peerRulesNotApplied", "unresolvedEdge"]))
+}) {
+	/** The unsatisfied peers a gate should act on — the non-optional ones. */
+	get required() {
+		return this.unsatisfied.filter((row) => !row.optional);
+	}
+	/**
+	* Compute the unsatisfied peer dependencies of a parsed lockfile.
+	*
+	* @remarks
+	* Pure, total and format-free: no IO, no error channel, and no knowledge of
+	* which package manager wrote the file. Range satisfaction is
+	* `@effected/semver`'s, never hand-rolled.
+	*
+	* The walk starts at each importer's resolved dependencies and follows
+	* `resolved` edges, so a peer declared by a *transitive* dependency is
+	* attributed to the importer that pulls it in, with the chain in
+	* `parents` — matching how `pnpm peers check` attributes them.
+	*
+	* Three judgements are deliberate:
+	*
+	* - **A required peer with nothing resolved is reported** (`found: null`),
+	*   whether or not the declared range is parseable — a peer with no
+	*   provider is a fact about the graph that needs no range arithmetic.
+	* - **An ABSENT optional peer is not reported at all**, because that is
+	*   what optional means. An optional peer resolved at the *wrong* version
+	*   still is, carrying `optional: true`. Both halves match
+	*   `pnpm peers check`, whose `missing` section contains only required
+	*   peers while its `bad` section carries optional ones.
+	* - **An unparseable range or version with something resolved is skipped.**
+	*   The check cannot judge it, and asserting "unsatisfied" on a comparison
+	*   that was never performed would be a wrong answer rather than a gap.
+	* - **A workspace-linked provider counts.** Resolution is followed through
+	*   whatever the edge names, including a workspace row.
+	*
+	* Known limits it does not paper over: yarn (see `supported`), the npm and
+	* bun root importer (see `unresolvedImporters`), and pnpm recording no peer
+	* declarations for workspace projects themselves — under pnpm a workspace
+	* package's *own* unsatisfied peers are not in the lockfile at all, and
+	* `pnpm peers check` does not report them either.
+	*
+	* @param lockfile - a lockfile parsed by `@effected/lockfiles`
+	* @returns the report; never fails
+	*/
+	static run(lockfile, options) {
+		const keySupplied = options !== void 0 && "peerDependencyRules" in options;
+		const rules = options?.peerDependencyRules;
+		const axesUnapplied = rules !== void 0 && (rules.ignoreMissing.length > 0 || rules.allowAny.length > 0);
+		const rulesApplied = keySupplied && !axesUnapplied;
+		const allowed = rules?.allowedVersions ?? {};
+		const unverified = rulesApplied ? [] : ["peerRulesNotApplied"];
+		if (!supportsPeerResolution(lockfile.format)) return PeerCheck.make({
+			supported: false,
+			unsatisfied: [],
+			unresolvedImporters: [],
+			unverified
+		});
+		const byId = new Map(lockfile.packages.map((pkg) => [pkg.instanceId, pkg]));
+		const workspaceByPath = /* @__PURE__ */ new Map();
+		for (const pkg of lockfile.packages) if (pkg.isWorkspace && pkg.relativePath !== void 0) workspaceByPath.set(pkg.relativePath, pkg);
+		const rows = [];
+		const unresolved = [];
+		const seen = /* @__PURE__ */ new Set();
+		for (const importer of lockfile.importers) {
+			const roots = rootInstances(lockfile, importer.path, workspaceByPath, byId);
+			if (roots === void 0) {
+				unresolved.push(importer.path);
+				continue;
+			}
+			collect(importer.path, roots, byId, rows, seen, allowed);
+		}
+		if (lockfile.packages.some((pkg) => pkg.unresolvedEdges.length > 0)) unverified.push("unresolvedEdge");
+		return PeerCheck.make({
+			supported: true,
+			unsatisfied: rows,
+			unresolvedImporters: unresolved,
+			unverified
+		});
+	}
+};
+/**
+* The instances an importer's dependencies resolved to, plus the importer's own
+* workspace row when the lockfile records one.
+*
+* Returns `undefined` when the importer cannot be resolved at all, which the
+* caller reports rather than treating as "no problems here".
+*
+* @internal
+*/
+const rootInstances = (lockfile, importerPath, workspaceByPath, byId) => {
+	const own = workspaceByPath.get(importerPath);
+	if (own !== void 0) return [{
+		instance: own,
+		path: []
+	}];
+	const importer = lockfile.importer(importerPath);
+	if (importer._tag === "None") return void 0;
+	const walks = [];
+	let resolvable = false;
+	for (const dep of importer.value.dependencies) {
+		if (dep.version === void 0) continue;
+		const composed = byId.get(`${dep.name}@${dep.version}${dep.peerSuffix ?? ""}`);
+		if (composed === void 0) continue;
+		resolvable = true;
+		walks.push({
+			instance: composed,
+			path: [PeerParent.make({
+				name: composed.name,
+				version: composed.version
+			})]
+		});
+	}
+	if (!resolvable && importer.value.dependencies.length > 0) return void 0;
+	return walks;
+};
+/**
+* Walk the resolution graph from an importer's roots, emitting a row for every
+* unsatisfied peer declared anywhere along the way.
+*
+* @internal
+*/
+const collect = (importerPath, roots, byId, rows, seen, allowed) => {
+	const visited = /* @__PURE__ */ new Set();
+	const queue = [...roots];
+	while (queue.length > 0) {
+		const current = queue.shift();
+		if (current === void 0) break;
+		if (visited.has(current.instance.instanceId)) continue;
+		visited.add(current.instance.instanceId);
+		for (const [peer, wanted] of Object.entries(current.instance.peerDependencies)) {
+			if (peer === "") continue;
+			const optional = current.instance.peerDependenciesMeta[peer]?.optional === true;
+			const verdict = judge(current.instance, peer, wanted, optional, byId);
+			if (verdict === void 0) continue;
+			if (suppressedByRule(allowed, current.instance.name, peer, verdict.found)) continue;
+			const key = `${importerPath}\u0000${peer}\u0000${current.instance.instanceId}`;
+			if (seen.has(key)) continue;
+			seen.add(key);
+			rows.push(UnsatisfiedPeer.make({
+				importer: importerPath,
+				dependency: peer,
+				wanted,
+				found: verdict.found,
+				optional,
+				parents: current.path
+			}));
+		}
+		for (const targetId of Object.values(current.instance.resolved)) {
+			const next = byId.get(targetId);
+			if (next === void 0 || visited.has(targetId)) continue;
+			queue.push({
+				instance: next,
+				path: [...current.path, PeerParent.make({
+					name: next.name,
+					version: next.version
+				})]
+			});
+		}
+	}
+};
+/**
+* The parent name a `peerDependencyRules.allowedVersions` key names, with the
+* parent's version stripped.
+*
+* @remarks
+* **pnpm ignores the parent version in a rule key**, so
+* `"react-dom@18.0.0>react"` suppresses a `react-dom@18.3.1` instance too.
+* Replicating that is not optional: matching on the version would suppress a
+* strictly smaller set than pnpm does, and every row in the difference is a
+* false positive.
+*
+* Both spellings occur in the wild and both must work — parent-versioned, as
+* `pnpm:export` materializes into `pnpm-workspace.yaml`, and unversioned, as a
+* config-dependency plugin injects. A scoped name keeps its leading `@`, so the
+* version separator is the LAST `@`, and only when it is not the first
+* character.
+*
+* A key naming no parent at all (`"react"`, with no `>`) never reaches this
+* function: {@link suppressedByRule} matches it against every parent, which is
+* what pnpm does with it.
+*
+* @internal
+*/
+const ruleParentName = (parent) => {
+	const at = parent.lastIndexOf("@");
+	return at > 0 ? parent.slice(0, at) : parent;
+};
+/**
+* Whether a rule permits the version that actually resolved for this peer.
+*
+* @remarks
+* Only `allowedVersions` is consulted. `ignoreMissing` and `allowAny` are
+* carried through the seam **unmeasured and unwired** — an unmeasured
+* suppression is exactly what produced the false positives this work removes,
+* so no code acts on them until someone measures them. Non-empty, they make the
+* whole report `"peerRulesNotApplied"` (see {@link PeerCheck.run}) rather than
+* being ignored here.
+*
+* A rule cannot rescue a peer that resolved to nothing: with no version there
+* is nothing for the rule to permit, and pnpm's own `missing` section is not
+* suppressed by `allowedVersions` either.
+*
+* @internal
+*/
+const suppressedByRule = (allowed, parentName, peer, found) => {
+	if (found === null) return false;
+	const version = SemVer.parseResult(found);
+	if (Result.isFailure(version)) return false;
+	for (const [key, permitted] of Object.entries(allowed)) {
+		const separator = key.indexOf(">");
+		if (separator === 0) continue;
+		if (separator === -1) {
+			if (key !== peer) continue;
+		} else {
+			if (key.slice(separator + 1) !== peer) continue;
+			if (ruleParentName(key.slice(0, separator)) !== parentName) continue;
+		}
+		const range = Range.parseResult(permitted);
+		if (Result.isFailure(range)) continue;
+		if (Range.satisfies(version.success, range.success)) return true;
+	}
+	return false;
+};
+/**
+* Decide whether one declared peer is unsatisfied.
+*
+* Returns `undefined` for "satisfied, or not judgeable" — the two cases that
+* produce no row. They are deliberately merged here and separated in the
+* TSDoc on {@link PeerCheck.run}, since neither yields output.
+*
+* @internal
+*/
+const judge = (instance, peer, wanted, optional, byId) => {
+	const providerId = instance.resolved[peer];
+	const provider = providerId === void 0 ? void 0 : byId.get(providerId);
+	if (provider === void 0) {
+		if (optional) return void 0;
+		if (instance.unresolvedEdges.includes(peer)) return void 0;
+		return { found: null };
+	}
+	if (provider.isWorkspace) return void 0;
+	const range = Range.parseResult(wanted);
+	const version = SemVer.parseResult(provider.version);
+	if (Result.isFailure(range) || Result.isFailure(version)) return void 0;
+	if (Range.satisfies(version.success, range.success)) return void 0;
+	return { found: provider.version };
+};
+
+//#endregion
+export { PeerCheck, PeerParent, UnsatisfiedPeer };

package/README.md

@@ -5,7 +5,7 @@
 [![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
 [![TypeScript 7.0](https://img.shields.io/badge/TypeScript-7.0-3178c6.svg)](https://www.typescriptlang.org/)
 
-Monorepo workspace tooling for [Effect](https://effect.website) v4: find the workspace root, enumerate its packages, walk the dependency graph, detect the package manager, resolve pnpm catalogs, read the lockfile and work out which packages a git range touches. Every capability is a service you provide at the edge and swap in tests. Works with npm, pnpm, yarn Berry and bun.
+Monorepo workspace tooling for [Effect](https://effect.website) v4: find the workspace root, enumerate its packages, walk the dependency graph, detect the package manager, resolve pnpm catalogs, read the lockfile, check it for unsatisfied peer dependencies and work out which packages a git range touches. Every capability is a service you provide at the edge and swap in tests. Works with npm, pnpm, yarn Berry and bun.
 
 > **Pre-release.** This package is part of the `@effected/*` kit, in pre-`1.0.0`
 > development against a single pinned Effect v4 prerelease. Packages graduate to
@@ -142,6 +142,43 @@ const program = Effect.gen(function* () {
 
 A specifier the workspace cannot answer fails typed as `UnresolvedDependencyError`: at the manifest level "no catalog entry" means the manifest cannot be projected to concrete ranges.
 
+## Peer dependency checking
+
+`PeerCheck.run(lockfile, options?)` reports unsatisfied peer dependencies as a pure value: no IO, no error channel, nothing in `R`, and no per-manager traversal logic. It reads `lockfile.format` once, to reject a format whose lockfile does not record peer resolution; past that gate the walk is the same for every manager. The answer comes from the resolved graph `@effected/lockfiles` normalizes, not from shelling out to a package manager's own peer command — bun has none, so the subprocess route cannot answer for every manager the rest of this package supports.
+
+```ts
+import { LockfileReader, PeerCheck, WorkspaceCatalogs } from "@effected/workspaces";
+import { Effect } from "effect";
+
+const program = Effect.gen(function* () {
+  const reader = yield* LockfileReader;
+  const catalogs = yield* WorkspaceCatalogs;
+
+  const lockfile = yield* reader.read();
+  // Presence of the key is the assertion — see below.
+  const report = PeerCheck.run(lockfile, { peerDependencyRules: yield* catalogs.peerDependencyRules() });
+
+  return {
+    clean:
+      report.supported &&
+      report.unresolvedImporters.length === 0 &&
+      report.unverified.length === 0 &&
+      report.required.length === 0,
+    required: report.required.length,
+  };
+});
+// { clean: whether the workspace is proven clean, required: count of non-optional findings }
+```
+
+**An empty `unsatisfied` is not the same as clean**, and reading it that way is the mistake this report's shape exists to prevent. Three other fields carry the difference between "nothing is wrong" and "nothing was checked", and a gate must read all four:
+
+- `supported` is `false` for yarn, which resolves peers virtually and does not record which virtual instance satisfied which peer. The answer is unrecoverable, so it is not fabricated.
+- `unresolvedImporters` names importers that could not be joined to package instances — in practice the root importer under npm and bun, neither of which records a resolved version per importer dependency.
+- `unverified` says why the report is not a complete answer: `"peerRulesNotApplied"` when the suppression policy could not be applied, `"unresolvedEdge"` when an instance records an edge the model could not name. Both mean fail closed.
+- `required` is the getter for the rows a gate should act on — the non-optional ones. An unsatisfied *optional* peer is normal, so `optional` travels with the row rather than being filtered out at the source.
+
+`WorkspaceCatalogs.peerDependencyRules()` returns the workspace's effective merged pnpm suppression rules, which the lockfile records nowhere; without them a checker reports findings pnpm itself calls clean. **Presence of the `peerDependencyRules` option key is the assertion, not its contents.** Passing `NoPeerDependencyRules` asserts the workspace has none, so the report carries no `"peerRulesNotApplied"` — though it can still be unverified for another reason, or unsupported; omitting the key says nobody looked, and always yields `"peerRulesNotApplied"`. Only `allowedVersions` is applied — rules populating `ignoreMissing` or `allowAny` describe a policy this package does not replicate, so they fail closed through the same reason rather than being silently ignored. All three key spellings pnpm accepts are honoured: `parent@version>peer` (what `pnpm:export` writes), `parent>peer` (what a config-dependency plugin injects) and a bare `peer`, which pnpm applies to every parent that declares it.
+
 ## The synchronous escape hatch
 
 Vitest's config-time project discovery cannot await. Two functions exist for exactly that case, and they run synchronously over file and path operations you supply. On Node you do not have to write them: the `@effected/workspaces/node-sync` subpath exports `nodeSyncOps`, the ready-made `node:fs` and `node:path` bindings, so adopting the sync path is one extra import.
@@ -242,6 +279,8 @@ A name miss in the derived `getPackage` fails with the service's own typed `Pack
 - `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`.
+- `PeerCheck` — unsatisfied peer-dependency detection as a pure, total value over a parsed lockfile, with `UnsatisfiedPeer` and `PeerParent` as the report's rows. Read `supported`, `unresolvedImporters` and `unverified` alongside `unsatisfied`: an empty finding list is a clean bill of health only when those three say so.
+- `NoPeerDependencyRules` / `PeerDependencyRules` — the effective pnpm suppression policy `WorkspaceCatalogs.peerDependencyRules()` assembles, and the "I assert none apply" value for callers that have checked.
 - `ChangeDetector` — git-range change detection over `@effected/git`'s `Git` service; swap the layer to mock it with no repository.
 - `PublishabilityDetector` — whether a package publishes and to where, as a `PublishTarget` (registry, directory, access, provenance). No composite provides one: pick `PublishabilityDetector.layerNpm` (standard npm semantics) or `.layerNone` (nothing publishes) and provide it explicitly.
 - `ReleaseTag` / `TrackingTag` — release-tag formatting (`ReleaseTag.single` / `.scoped`, strict SemVer by default with no `v` prefix) and the floating major/minor alias derivation GitHub Actions-style consumers expect (`v1`, `v1.2`), plus `classifyTag` to tell a release tag from a tracking alias.

package/VersioningStrategy.js

@@ -90,8 +90,12 @@ var VersioningStrategy = class VersioningStrategy extends Schema.Class("Versioni
 		const discovery = yield* WorkspaceDiscovery;
 		const publishability = yield* PublishabilityDetector;
 		const packages = yield* discovery.listPackages();
+		const detected = yield* Effect.forEach(packages, (candidate) => publishability.detect(candidate).pipe(Effect.map((targets) => ({
+			name: candidate.name,
+			publishable: targets.length > 0
+		}))), { concurrency: 10 });
 		const publishable = [];
-		for (const candidate of packages) if ((yield* publishability.detect(candidate)).length > 0) publishable.push(candidate.name);
+		for (const candidate of detected) if (candidate.publishable) publishable.push(candidate.name);
 		return VersioningStrategy.classify({
 			packages: publishable,
 			...options?.fixedGroups !== void 0 && { fixedGroups: options.fixedGroups }

package/WorkspaceCatalogs.js

@@ -211,6 +211,41 @@ const inlineReleaseAge = (document) => {
 		cause
 	})));
 };
+/**
+* The `peerDependencyRules` a `pnpm-workspace.yaml` declares inline — the half
+* `pnpm:export` materializes into the file, as opposed to the half a config
+* dependency injects at replay time.
+*
+* @remarks
+* **Tolerant, unlike the catalog blocks**, and the asymmetry is deliberate: a
+* malformed catalog block must hard-fail because a silently-empty catalog makes
+* every dependency look newly added, whereas a malformed rules block costs only
+* suppression — the failure mode is reporting a peer pnpm would have hidden,
+* which is visible and safe. Failing the whole assembly over it would take the
+* catalogs down with it.
+*
+* Every axis is read independently, so a malformed `ignoreMissing` does not
+* discard a well-formed `allowedVersions`.
+*/
+const EMPTY_PEER_RULES = {
+	allowedVersions: {},
+	ignoreMissing: [],
+	allowAny: []
+};
+const inlinePeerDependencyRules = (document) => {
+	if (!isObject(document) || !isObject(document.peerDependencyRules)) return EMPTY_PEER_RULES;
+	const block = document.peerDependencyRules;
+	const allowedVersions = {};
+	if (isObject(block.allowedVersions)) {
+		for (const [key, value] of Object.entries(block.allowedVersions)) if (typeof value === "string") allowedVersions[key] = value;
+	}
+	const strings = (value) => Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
+	return {
+		allowedVersions,
+		ignoreMissing: strings(block.ignoreMissing),
+		allowAny: strings(block.allowAny)
+	};
+};
 /** A hard-fail catalog-assembly failure naming the malformed part of a `workspaces` field. */
 const malformed = (source, path, detail) => new CatalogAssemblyError({
 	source,
@@ -343,6 +378,7 @@ var WorkspaceCatalogs = class WorkspaceCatalogs extends Context.Service()("@effe
 			let injected;
 			let inlineGate = {};
 			let hookGate = {};
+			let peerDependencyRules = EMPTY_PEER_RULES;
 			if (hasPnpmWorkspace) {
 				const text = yield* fs.readFileString(workspaceYaml).pipe(Effect.mapError((cause) => new CatalogAssemblyError({
 					source: "manifest",
@@ -357,15 +393,17 @@ var WorkspaceCatalogs = class WorkspaceCatalogs extends Context.Service()("@effe
 				yield* validatePnpmWorkspaceCatalogs(document);
 				inline = CatalogSet.fromCatalogs(inlineCatalogs(catalogBlocksOf(document)));
 				inlineGate = yield* inlineReleaseAge(document);
-				const injection = yield* hooks.inject(root, configDependenciesOf(document), inline.entries);
+				const injection = yield* hooks.inject(root, configDependenciesOf(document), inline.entries, inlinePeerDependencyRules(document));
 				injected = CatalogSet.fromCatalogs(injection.catalogs);
 				hookGate = injection.releaseAge;
+				peerDependencyRules = injection.peerDependencyRules;
 			} else {
 				const manifestPath = path.join(root, "package.json");
 				if (!(yield* probeExists(manifestPath))) return {
 					catalogs: fromLockfile,
 					releaseAgeGate: ReleaseAgeGate.combine(),
-					importerVersions
+					importerVersions,
+					peerDependencyRules: EMPTY_PEER_RULES
 				};
 				const text = yield* fs.readFileString(manifestPath).pipe(Effect.mapError((cause) => new CatalogAssemblyError({
 					source: "manifest",
@@ -385,7 +423,8 @@ var WorkspaceCatalogs = class WorkspaceCatalogs extends Context.Service()("@effe
 			return {
 				catalogs: assembled,
 				releaseAgeGate,
-				importerVersions
+				importerVersions,
+				peerDependencyRules
 			};
 		});
 		const [resolveOnce, invalidate] = yield* Effect.cachedInvalidateWithTTL(assemble, Duration.infinity);
@@ -397,6 +436,9 @@ var WorkspaceCatalogs = class WorkspaceCatalogs extends Context.Service()("@effe
 			resolveSpecifier: Effect.fn("WorkspaceCatalogs.resolveSpecifier")(function* (dependency, specifier) {
 				return (yield* memo).catalogs.resolveSpecifier(dependency, specifier);
 			}),
+			peerDependencyRules: Effect.fn("WorkspaceCatalogs.peerDependencyRules")(function* () {
+				return (yield* memo).peerDependencyRules;
+			}),
 			releaseAgeGate: Effect.fn("WorkspaceCatalogs.releaseAgeGate")(function* () {
 				return (yield* memo).releaseAgeGate;
 			}),
@@ -483,6 +525,7 @@ var WorkspaceCatalogs = class WorkspaceCatalogs extends Context.Service()("@effe
 		return {
 			set: () => unstubbed("set"),
 			resolveSpecifier: set !== void 0 ? (dependency, specifier) => Effect.map(set(), (catalogs) => catalogs.resolveSpecifier(dependency, specifier)) : () => unstubbed("resolveSpecifier"),
+			peerDependencyRules: () => unstubbed("peerDependencyRules"),
 			releaseAgeGate: () => unstubbed("releaseAgeGate"),
 			importerVersions: () => unstubbed("importerVersions"),
 			...overrides

package/WorkspacesSync.js

@@ -196,8 +196,11 @@ const getWorkspacePackagesSync = (root, options) => {
 	const compiled = Effect.runSyncExit(GlobSet.compile(patterns));
 	if (Exit.isFailure(compiled)) return [];
 	const globs = compiled.value;
+	const excludes = globs.excludes;
+	const isExcluded = excludes.length === 0 ? (_) => false : (relative) => excludes.some((exclude) => exclude.matches(relative));
 	const included = /* @__PURE__ */ new Map();
 	for (const literal of globs.literals) {
+		if (isExcluded(literal)) continue;
 		const absolute = path.join(root, literal);
 		if (isPackage(options, absolute)) included.set(literal, absolute);
 	}
@@ -224,7 +227,7 @@ const getWorkspacePackagesSync = (root, options) => {
 					stopped = true;
 					break;
 				}
-				if (wildcard.matches(relative) && isPackage(options, absolute)) included.set(relative, absolute);
+				if (wildcard.matches(relative) && !isExcluded(relative) && isPackage(options, absolute)) included.set(relative, absolute);
 				if (!wildcard.crossesSegments) continue;
 				traversal.push(current, relative, absolute);
 			}
@@ -233,7 +236,6 @@ const getWorkspacePackagesSync = (root, options) => {
 	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(options, root, absolute, relativePath);
 		if (pkg !== null) members.push(pkg);
 	}

package/index.d.ts

@@ -797,6 +797,52 @@ declare class ChangeDetector extends ChangeDetector_base {
 }
 //#endregion
 //#region src/ConfigDependencyHooks.d.ts
+/**
+ * pnpm's `peerDependencyRules` block — the suppression policy pnpm applies
+ * **after** computing peer violations, in pnpm's own shape.
+ *
+ * @remarks
+ * The shape is pnpm's rather than ours because that is what comes back off the
+ * threaded config: measured against `@savvy-web/pnpm-plugin-silk@0.27.0`, a
+ * replayed hook returns `{ allowedVersions, ignoreMissing, allowAny }` intact,
+ * needing no reshaping.
+ *
+ * Two keys are **carried but not yet consumed**. `ignoreMissing` and
+ * `allowAny` are separate suppression axes that have not been measured, and an
+ * unmeasured suppression is precisely what produced the false positives this
+ * seam exists to remove — so they travel through the seam and no kit code acts
+ * on them. Only `allowedVersions` is consumed today.
+ *
+ * `allowedVersions` keys come in two spellings in the wild, and both must be
+ * handled: parent-versioned (`"@effect/ai-anthropic@4.0.0-rc.109>effect"`, as
+ * `pnpm:export` materializes them into `pnpm-workspace.yaml`) and unversioned
+ * (`"@effect/vitest>vitest"`, as a config-dependency plugin injects them).
+ *
+ * @public
+ */
+interface PeerDependencyRules {
+  /** `parent>peer` → the peer version or range the rule permits. */
+  readonly allowedVersions: Readonly<Record<string, string>>;
+  /** Peer names whose absence pnpm does not report. Carried, not consumed. */
+  readonly ignoreMissing: ReadonlyArray<string>;
+  /** Peer names for which any version is accepted. Carried, not consumed. */
+  readonly allowAny: ReadonlyArray<string>;
+}
+/**
+ * The empty {@link PeerDependencyRules}: every axis present and empty.
+ *
+ * @remarks
+ * Exported so that "I assert this workspace's rules are empty" is **one token**
+ * rather than three hand-written empty axes. That matters where the distinction
+ * is load-bearing — supplying rules asserts they were looked up, while omitting
+ * them asserts nothing — and a caller spelling the object out by hand will
+ * eventually fill two of the three axes and mean the third.
+ *
+ * Frozen, since it is shared.
+ *
+ * @public
+ */
+declare const NoPeerDependencyRules: PeerDependencyRules;
 /**
  * The result of replaying a workspace's `configDependencies` hooks: the catalogs
  * the hooks yield, and the release-age gate contribution they leave on the
@@ -816,6 +862,24 @@ interface HookInjection {
   readonly catalogs: Readonly<Record<string, Readonly<Record<string, string>>>>;
   /** The release-age gate contribution the replayed hooks leave on the config. */
   readonly releaseAge: PartialReleaseAgeGate;
+  /**
+   * The **effective** peer-dependency rules: the seeded workspace-file rules
+   * with every replayed hook's contribution threaded over them.
+   *
+   * @remarks
+   * Effective rather than hook-only because the rules are **seeded** into the
+   * threaded config and the hooks merge onto them, exactly as pnpm seeds its
+   * own config and takes back what the hooks return. That is deliberate: a
+   * kit-owned merge function would be a second implementation of a rule this
+   * seam already enforces, and the two would drift the first time pnpm changed
+   * its threading.
+   *
+   * Measured caveat, and **not a bug to fix**: this repo's plugin *merges*
+   * onto the seeded rules; another plugin could overwrite them. Under seeding
+   * that is pnpm's own behaviour reproduced — a hook that overwrites
+   * overwrites for pnpm too — so do not "repair" it into a merger.
+   */
+  readonly peerDependencyRules: PeerDependencyRules;
 }
 /**
  * The {@link ConfigDependencyHooks} service shape.
@@ -853,8 +917,12 @@ interface ConfigDependencyHooksShape {
    * @param configDependencies - The `configDependencies` map (name →
    *   version+integrity) declared in `pnpm-workspace.yaml`.
    * @param seed - The inline catalogs, as `catalog name → dependency → range`.
+   * @param rules - The workspace file's `peerDependencyRules`, seeded into the
+   *   threaded config so hooks merge onto them rather than replacing them.
+   *   Omitted means "the workspace file declares none", which is different
+   *   from "nobody looked" — the caller owns that distinction.
    */
-  readonly inject: (root: string, configDependencies: Readonly<Record<string, string>>, seed: Readonly<Record<string, Readonly<Record<string, string>>>>) => Effect.Effect<HookInjection, CatalogAssemblyError>;
+  readonly inject: (root: string, configDependencies: Readonly<Record<string, string>>, seed: Readonly<Record<string, Readonly<Record<string, string>>>>, rules?: PeerDependencyRules) => Effect.Effect<HookInjection, CatalogAssemblyError>;
 }
 declare const ConfigDependencyHooks_base: Context.ServiceClass<ConfigDependencyHooks, "@effected/workspaces/ConfigDependencyHooks", ConfigDependencyHooksShape>;
 /**
@@ -1444,6 +1512,219 @@ declare class LockfileReader extends LockfileReader_base {
   static readonly layerTest: (overrides?: Partial<LockfileReaderShape>) => Layer.Layer<LockfileReader>;
 }
 //#endregion
+//#region src/PeerCheck.d.ts
+/**
+ * Why a report is not a complete answer.
+ *
+ * @remarks
+ * Closed at exactly two, by measurement rather than by guess:
+ *
+ * - `"peerRulesNotApplied"` — the effective suppression policy was not applied,
+ *   so pnpm's post-hoc suppression could not be replicated and some reported
+ *   rows may be ones pnpm hides. **Omitting the option always produces this**,
+ *   because "nobody looked" and "I looked and there are none" are different
+ *   facts. Supplied rules with a non-empty `ignoreMissing` or `allowAny` also
+ *   produce it: only `allowedVersions` is applied, so an unimplemented axis
+ *   degrades to fail-closed rather than to a wrong answer.
+ * - `"unresolvedEdge"` — some instance records an edge this model could not
+ *   name (`ResolvedPackage.unresolvedEdges`), so a peer that edge satisfies
+ *   cannot be verified either way.
+ *
+ * Both mean **fail closed**: a gate should treat an unverified report as "not
+ * proven clean" rather than as a pass.
+ *
+ * @public
+ */
+type UnverifiedReason = "peerRulesNotApplied" | "unresolvedEdge";
+/**
+ * Options for {@link PeerCheck.run}.
+ *
+ * @remarks
+ * **Presence of `peerDependencyRules` is the assertion; its contents are the
+ * value.** Supplying `NoPeerDependencyRules` asserts the workspace has none and
+ * yields a verified report; omitting the key entirely says nothing was looked
+ * up and always yields `"peerRulesNotApplied"`. The two are deliberately
+ * different results, because a gate must be able to tell "clean" from
+ * "unchecked".
+ *
+ * **Only `allowedVersions` is applied.** Rules whose `ignoreMissing` or
+ * `allowAny` is non-empty describe a suppression policy this module does not
+ * implement, so they also yield `"peerRulesNotApplied"` — the unimplemented
+ * axes fail closed instead of being silently ignored.
+ *
+ * @public
+ */
+interface PeerCheckOptions {
+  /** The workspace's effective rules, from `WorkspaceCatalogs.peerDependencyRules()`. */
+  readonly peerDependencyRules?: PeerDependencyRules;
+}
+declare const PeerParent_base: Schema.Class<PeerParent, Schema.Struct<{
+  /** The package name. */
+  readonly name: Schema.NonEmptyString;
+  /** The resolved version of that package. */
+  readonly version: Schema.String;
+}>, {}>;
+/**
+ * One link in the chain from an importer to the package that declared an
+ * unsatisfied peer.
+ *
+ * @remarks
+ * Mirrors the shape `pnpm peers check --json` reports, so the two can be
+ * compared directly.
+ *
+ * @public
+ */
+declare class PeerParent extends PeerParent_base {}
+declare const UnsatisfiedPeer_base: Schema.Class<UnsatisfiedPeer, Schema.Struct<{
+  /** The importer path the problem belongs to (`"."` for the root). */
+  readonly importer: Schema.NonEmptyString;
+  /** The peer dependency's name. */
+  readonly dependency: Schema.NonEmptyString;
+  /** The range the declaring package asked for. */
+  readonly wanted: Schema.String;
+  /** The version that resolved, or `null` when nothing resolved. */
+  readonly found: Schema.NullOr<Schema.String>;
+  /** Whether the declaring package marked the peer optional. */
+  readonly optional: Schema.Boolean;
+  /** The path from the importer to the declaring package. */
+  readonly parents: Schema.$Array<typeof PeerParent>;
+}>, {}>;
+/**
+ * One peer dependency that is declared but not satisfied.
+ *
+ * @remarks
+ * `found` carries the version that actually resolved, or `null` when nothing
+ * resolved at all. There is deliberately **no separate discriminant** between
+ * "missing" and "unmet": `found === null` is the whole distinction, and a
+ * renderer reads it directly.
+ *
+ * `optional` must be respected by any gate — an unsatisfied *optional* peer is
+ * normal and should not fail a build, which is why the flag travels with the
+ * row rather than being filtered out here. {@link PeerCheck.required} is the
+ * convenience for the common case.
+ *
+ * `parents` is the path from the importer down to the package that declared
+ * the peer, nearest-to-the-importer first. It is a path rather than a single
+ * package because a peer declared by a transitive dependency is still that
+ * importer's problem, and the chain is what makes the report actionable.
+ *
+ * A package an importer reaches by more than one path yields **one** row, not
+ * one per path, carrying the path the walk reached first — which is what
+ * `pnpm peers check` reports for the same graph. Read `parents` as *a* route to
+ * the declaring package, never as the complete set of them.
+ *
+ * @public
+ */
+declare class UnsatisfiedPeer extends UnsatisfiedPeer_base {}
+declare const PeerCheck_base: Schema.Class<PeerCheck, Schema.Struct<{
+  /**
+   * Whether the lockfile's format records peer resolution at all.
+   *
+   * `false` for yarn: yarn resolves peers **virtually**, giving a
+   * peer-bearing package one `@virtual:` locator per consumer, and the
+   * lockfile does not record which virtual instance satisfied which peer.
+   * The answer is not recoverable, so it is not fabricated — `unsatisfied`
+   * is empty and this flag says why.
+   */
+  readonly supported: Schema.Boolean;
+  /** Every unsatisfied peer found, optional ones included. */
+  readonly unsatisfied: Schema.$Array<typeof UnsatisfiedPeer>;
+  /**
+   * Importers whose dependencies could not be resolved to instances, so no
+   * verdict was reached for them.
+   *
+   * @remarks
+   * In practice this is the **root importer under npm and bun**: neither
+   * records a resolved version per importer dependency, and neither emits a
+   * package row for the root, so there is nothing to join on. pnpm records a
+   * version per importer dependency and is unaffected.
+   *
+   * Reported rather than silently skipped, for the same reason `supported`
+   * exists: a gate that sees no rows is entitled to know whether that means
+   * "clean" or "not looked at".
+   */
+  readonly unresolvedImporters: Schema.$Array<Schema.String>;
+  /**
+   * Why this report is not a complete answer, or empty when it is.
+   *
+   * @remarks
+   * See {@link UnverifiedReason}. A gate must treat a non-empty `unverified`
+   * as **not proven clean** rather than as a pass: both reasons mean some
+   * finding may be missing or spurious, and failing closed is the requirement.
+   */
+  readonly unverified: Schema.$Array<Schema.Literals<readonly ["peerRulesNotApplied", "unresolvedEdge"]>>;
+}>, {}>;
+/**
+ * The result of checking a lockfile for unsatisfied peer dependencies.
+ *
+ * @remarks
+ * A report rather than a bare array, because an empty array is the most
+ * dangerous success shape this domain has: it is indistinguishable from "this
+ * format cannot be checked". `supported` and `unresolvedImporters` make the
+ * difference legible, so a consumer cannot read a limitation as a clean bill
+ * of health.
+ *
+ * Pure and total — construct it with {@link PeerCheck.run}, which never fails.
+ *
+ * @example
+ * ```ts
+ * import { PeerCheck } from "@effected/workspaces";
+ * import { Lockfile } from "@effected/lockfiles";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const lockfile = yield* Lockfile.parse(text, { format: "pnpm" });
+ *   const report = PeerCheck.run(lockfile);
+ *   return report.supported ? report.required : [];
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class PeerCheck extends PeerCheck_base {
+  /** The unsatisfied peers a gate should act on — the non-optional ones. */
+  get required(): ReadonlyArray<UnsatisfiedPeer>;
+  /**
+   * Compute the unsatisfied peer dependencies of a parsed lockfile.
+   *
+   * @remarks
+   * Pure, total and format-free: no IO, no error channel, and no knowledge of
+   * which package manager wrote the file. Range satisfaction is
+   * `@effected/semver`'s, never hand-rolled.
+   *
+   * The walk starts at each importer's resolved dependencies and follows
+   * `resolved` edges, so a peer declared by a *transitive* dependency is
+   * attributed to the importer that pulls it in, with the chain in
+   * `parents` — matching how `pnpm peers check` attributes them.
+   *
+   * Three judgements are deliberate:
+   *
+   * - **A required peer with nothing resolved is reported** (`found: null`),
+   *   whether or not the declared range is parseable — a peer with no
+   *   provider is a fact about the graph that needs no range arithmetic.
+   * - **An ABSENT optional peer is not reported at all**, because that is
+   *   what optional means. An optional peer resolved at the *wrong* version
+   *   still is, carrying `optional: true`. Both halves match
+   *   `pnpm peers check`, whose `missing` section contains only required
+   *   peers while its `bad` section carries optional ones.
+   * - **An unparseable range or version with something resolved is skipped.**
+   *   The check cannot judge it, and asserting "unsatisfied" on a comparison
+   *   that was never performed would be a wrong answer rather than a gap.
+   * - **A workspace-linked provider counts.** Resolution is followed through
+   *   whatever the edge names, including a workspace row.
+   *
+   * Known limits it does not paper over: yarn (see `supported`), the npm and
+   * bun root importer (see `unresolvedImporters`), and pnpm recording no peer
+   * declarations for workspace projects themselves — under pnpm a workspace
+   * package's *own* unsatisfied peers are not in the lockfile at all, and
+   * `pnpm peers check` does not report them either.
+   *
+   * @param lockfile - a lockfile parsed by `@effected/lockfiles`
+   * @returns the report; never fails
+   */
+  static run(lockfile: Lockfile, options?: PeerCheckOptions): PeerCheck;
+}
+//#endregion
 //#region src/Publishability.d.ts
 declare const PublishTarget_base: Schema.Class<PublishTarget, Schema.Struct<{
   /** The package name being published. */
@@ -1479,7 +1760,16 @@ declare class PublishTarget extends PublishTarget_base {}
  * @public
  */
 interface PublishabilityDetectorShape {
-  /** The publish targets for a package; empty means it does not publish. */
+  /**
+   * The publish targets for a package; empty means it does not publish.
+   *
+   * @remarks
+   * `VersioningStrategy.detect` probes a whole workspace by invoking this
+   * concurrently — up to ten packages in flight at once, in no guaranteed
+   * order. An overriding implementation backed by shared mutable state or a
+   * rate-limited client must tolerate that interleaving itself; the caller
+   * does not serialize on its behalf.
+   */
   readonly detect: (pkg: WorkspacePackage) => Effect.Effect<ReadonlyArray<PublishTarget>>;
 }
 declare const PublishabilityDetector_base: Context.ServiceClass<PublishabilityDetector, "@effected/workspaces/PublishabilityDetector", PublishabilityDetectorShape>;
@@ -2126,6 +2416,26 @@ interface WorkspaceCatalogsShape {
    * workspace) has no release-age keys, so the gate is the inert zero gate.
    */
   readonly releaseAgeGate: () => Effect.Effect<ReleaseAgeGate, CatalogAssemblyFailure>;
+  /**
+   * The workspace's **effective** `peerDependencyRules` — pnpm's post-hoc
+   * suppression policy, which the lockfile does not record at all.
+   *
+   * @remarks
+   * Assembled from the same single read and hook replay as `set`, and memoized
+   * with it. The `pnpm-workspace.yaml` block (what `pnpm:export` materializes)
+   * is **seeded** into the replayed config and the config-dependency hooks
+   * merge onto it, so one object carries both sources — the kit never merges
+   * them itself, because that would be a second implementation of a rule the
+   * hook seam already enforces.
+   *
+   * A consumer needs these to avoid **reporting** what pnpm suppresses: pnpm
+   * computes the same peer violations and then hides the ones a rule allows,
+   * so a checker without them reports findings pnpm calls clean.
+   *
+   * `ignoreMissing` and `allowAny` are carried but unmeasured — no kit code
+   * acts on them today.
+   */
+  readonly peerDependencyRules: () => Effect.Effect<PeerDependencyRules, CatalogAssemblyFailure>;
   /**
    * Each importer's dependency-name → resolved-version map, as the manager's
    * lockfile records it. Read from the same single lockfile read as `set`, and
@@ -3072,5 +3382,5 @@ interface GetWorkspacePackagesSyncOptions extends WorkspacesSyncOptions {
  */
 declare const getWorkspacePackagesSync: (root: string, options: GetWorkspacePackagesSyncOptions) => ReadonlyArray<WorkspacePackage>;
 //#endregion
-export { type CatalogAssemblyFailure, CatalogSet, ChangeDetectionError, type ChangeDetectionFailure, ChangeDetectionOptions, ChangeDetector, type ChangeDetectorShape, type ClassifyOptions, ConfigDependencyHooks, type ConfigDependencyHooksShape, CyclicDependencyError, type DependencyDiff, DependencyGraph, DetectedPackageManager, type FindWorkspaceRootOptions, type GetWorkspacePackagesSyncOptions, type HookInjection, type ImporterVersions, LockfileReadError, type LockfileReadFailure, LockfileReader, type LockfileReaderOptions, type LockfileReaderShape, PackageManagerDetectionError, type PackageManagerDetectionFailure, PackageManagerDetector, type PackageManagerDetectorShape, PackageManagerEvidence, PackageManagerName, PackageNotFoundError, type PackageRelease, PackageStateSnapshot, PublishConfig, PublishTarget, PublishabilityDetector, type PublishabilityDetectorShape, ReleaseTag, type SyncFileSystem, type SyncPath, type TagClassification, type TagFormatOptions, TagStyle, TrackingTag, type TrackingTagOptions, type VersioningDetectOptions, VersioningStrategy, VersioningStrategyType, WORKSPACE_MARKERS, WorkspaceCatalogs, type WorkspaceCatalogsOptions, type WorkspaceCatalogsShape, WorkspaceDiscovery, WorkspaceDiscoveryError, type WorkspaceDiscoveryFailure, type WorkspaceDiscoveryOptions, type WorkspaceDiscoveryShape, WorkspaceInfo, type WorkspaceLookupFailure, WorkspaceManifestError, WorkspacePackage, WorkspacePatternError, WorkspaceRoot, WorkspaceRootNotFoundError, type WorkspaceRootShape, type WorkspaceSnapshotAtFailure, type WorkspaceSnapshotWorktreeFailure, WorkspaceSnapshots, type WorkspaceSnapshotsOptions, type WorkspaceSnapshotsShape, WorkspaceStateSnapshot, Workspaces, type WorkspacesOptions, type WorkspacesServices, type WorkspacesSyncOptions, classifyTag, findWorkspaceRootSync, getWorkspacePackagesSync };
+export { type CatalogAssemblyFailure, CatalogSet, ChangeDetectionError, type ChangeDetectionFailure, ChangeDetectionOptions, ChangeDetector, type ChangeDetectorShape, type ClassifyOptions, ConfigDependencyHooks, type ConfigDependencyHooksShape, CyclicDependencyError, type DependencyDiff, DependencyGraph, DetectedPackageManager, type FindWorkspaceRootOptions, type GetWorkspacePackagesSyncOptions, type HookInjection, type ImporterVersions, LockfileReadError, type LockfileReadFailure, LockfileReader, type LockfileReaderOptions, type LockfileReaderShape, NoPeerDependencyRules, PackageManagerDetectionError, type PackageManagerDetectionFailure, PackageManagerDetector, type PackageManagerDetectorShape, PackageManagerEvidence, PackageManagerName, PackageNotFoundError, type PackageRelease, PackageStateSnapshot, PeerCheck, type PeerCheckOptions, type PeerDependencyRules, PeerParent, PublishConfig, PublishTarget, PublishabilityDetector, type PublishabilityDetectorShape, ReleaseTag, type SyncFileSystem, type SyncPath, type TagClassification, type TagFormatOptions, TagStyle, TrackingTag, type TrackingTagOptions, UnsatisfiedPeer, type UnverifiedReason, type VersioningDetectOptions, VersioningStrategy, VersioningStrategyType, WORKSPACE_MARKERS, WorkspaceCatalogs, type WorkspaceCatalogsOptions, type WorkspaceCatalogsShape, WorkspaceDiscovery, WorkspaceDiscoveryError, type WorkspaceDiscoveryFailure, type WorkspaceDiscoveryOptions, type WorkspaceDiscoveryShape, WorkspaceInfo, type WorkspaceLookupFailure, WorkspaceManifestError, WorkspacePackage, WorkspacePatternError, WorkspaceRoot, WorkspaceRootNotFoundError, type WorkspaceRootShape, type WorkspaceSnapshotAtFailure, type WorkspaceSnapshotWorktreeFailure, WorkspaceSnapshots, type WorkspaceSnapshotsOptions, type WorkspaceSnapshotsShape, WorkspaceStateSnapshot, Workspaces, type WorkspacesOptions, type WorkspacesServices, type WorkspacesSyncOptions, classifyTag, findWorkspaceRootSync, getWorkspacePackagesSync };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -3,9 +3,10 @@ import { WORKSPACE_MARKERS, WorkspaceRoot, WorkspaceRootNotFoundError } from "./
 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 { ConfigDependencyHooks, NoPeerDependencyRules } from "./ConfigDependencyHooks.js";
 import { DetectedPackageManager, PackageManagerDetectionError, PackageManagerDetector, PackageManagerEvidence, PackageManagerName } from "./PackageManagerName.js";
 import { LockfileReadError, LockfileReader } from "./LockfileReader.js";
+import { PeerCheck, PeerParent, UnsatisfiedPeer } from "./PeerCheck.js";
 import { PublishTarget, PublishabilityDetector } from "./Publishability.js";
 import { ReleaseTag, TagStyle, TrackingTag, classifyTag } from "./ReleaseTag.js";
 import { VersioningStrategy, VersioningStrategyType } from "./VersioningStrategy.js";
@@ -15,4 +16,4 @@ import { WorkspaceSnapshots } from "./WorkspaceSnapshots.js";
 import { Workspaces } from "./Workspaces.js";
 import { findWorkspaceRootSync, getWorkspacePackagesSync } from "./WorkspacesSync.js";
 
-export { CatalogSet, ChangeDetectionError, ChangeDetectionOptions, ChangeDetector, ConfigDependencyHooks, CyclicDependencyError, DependencyGraph, DetectedPackageManager, LockfileReadError, LockfileReader, PackageManagerDetectionError, PackageManagerDetector, PackageManagerEvidence, PackageManagerName, PackageNotFoundError, PackageStateSnapshot, PublishConfig, PublishTarget, PublishabilityDetector, ReleaseTag, TagStyle, TrackingTag, VersioningStrategy, VersioningStrategyType, WORKSPACE_MARKERS, WorkspaceCatalogs, WorkspaceDiscovery, WorkspaceDiscoveryError, WorkspaceInfo, WorkspaceManifestError, WorkspacePackage, WorkspacePatternError, WorkspaceRoot, WorkspaceRootNotFoundError, WorkspaceSnapshots, WorkspaceStateSnapshot, Workspaces, classifyTag, findWorkspaceRootSync, getWorkspacePackagesSync };
+export { CatalogSet, ChangeDetectionError, ChangeDetectionOptions, ChangeDetector, ConfigDependencyHooks, CyclicDependencyError, DependencyGraph, DetectedPackageManager, LockfileReadError, LockfileReader, NoPeerDependencyRules, PackageManagerDetectionError, PackageManagerDetector, PackageManagerEvidence, PackageManagerName, PackageNotFoundError, PackageStateSnapshot, PeerCheck, PeerParent, PublishConfig, PublishTarget, PublishabilityDetector, ReleaseTag, TagStyle, TrackingTag, UnsatisfiedPeer, VersioningStrategy, VersioningStrategyType, WORKSPACE_MARKERS, WorkspaceCatalogs, WorkspaceDiscovery, WorkspaceDiscoveryError, WorkspaceInfo, WorkspaceManifestError, WorkspacePackage, WorkspacePatternError, WorkspaceRoot, WorkspaceRootNotFoundError, WorkspaceSnapshots, WorkspaceStateSnapshot, Workspaces, classifyTag, findWorkspaceRootSync, getWorkspacePackagesSync };

package/internal/enumerate.js

@@ -18,6 +18,8 @@ const enumerate = (root, globs, options) => Effect.gen(function* () {
 	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 excludes = globs.excludes;
+	const isExcluded = excludes.length === 0 ? (_) => false : (relative) => excludes.some((exclude) => exclude.matches(relative));
 	const included = /* @__PURE__ */ new Map();
 	/** A shared-traversal stop, materialized as this module's failure record. */
 	const failureOf = (stop, pattern) => ({
@@ -26,6 +28,7 @@ const enumerate = (root, globs, options) => Effect.gen(function* () {
 		detail: stop.detail
 	});
 	for (const literal of globs.literals) {
+		if (isExcluded(literal)) continue;
 		const absolute = path.join(root, literal);
 		if (yield* isPackage(absolute)) included.set(literal, absolute);
 	}
@@ -53,20 +56,17 @@ const enumerate = (root, globs, options) => Effect.gen(function* () {
 				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.matches(relative) && !isExcluded(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
-		});
-	}
+	for (const [relativePath, absolute] of included) results.push({
+		relativePath,
+		path: absolute
+	});
 	results.sort((a, b) => a.relativePath < b.relativePath ? -1 : a.relativePath > b.relativePath ? 1 : 0);
 	return results;
 });

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/workspaces",
-	"version": "0.14.2",
+	"version": "0.15.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": [
@@ -49,7 +49,7 @@
 		"@effected/commands": "^0.5.0",
 		"@effected/git": "^0.9.0",
 		"@effected/glob": "^0.4.0",
-		"@effected/lockfiles": "^0.5.1",
+		"@effected/lockfiles": "^0.6.0",
 		"@effected/npm": "^0.11.0",
 		"@effected/package-json": "^0.10.2",
 		"@effected/semver": "^0.5.0",