@effected/workspaces 0.25.0 → 0.26.0

package/WorkspaceLayering.js

@@ -0,0 +1,199 @@
+import { WorkspaceDiscovery } from "./WorkspaceDiscovery.js";
+import { ALL_DEPENDENCY_FIELDS } from "./internal/dependencyFields.js";
+import { Effect, Graph, Option, Schema } from "effect";
+import { GlobSet } from "@effected/glob";
+import { DependencyField } from "@effected/npm";
+
+//#region src/WorkspaceLayering.ts
+/**
+* One dependency edge between two workspace packages, in one field.
+*
+* @public
+*/
+var LayerEdge = class extends Schema.Class("LayerEdge")({
+	/** The dependent package. */
+	from: Schema.String,
+	/** The package depended on. */
+	to: Schema.String,
+	/** The manifest map that declares it. */
+	field: DependencyField
+}) {
+	/** `from -> to (field)`. */
+	get label() {
+		return `${this.from} -> ${this.to} (${this.field})`;
+	}
+};
+/**
+* What a layering check found.
+*
+* @public
+*/
+var LayeringReport = class extends Schema.Class("LayeringReport")({
+	/** Packages the policy declares more than once, or declares and also matches with an unconstrained glob. */
+	duplicates: Schema.Array(Schema.String),
+	/** Workspace packages the policy does not classify. */
+	unclassified: Schema.Array(Schema.String),
+	/** Edges that break the policy, each with why. */
+	offenders: Schema.Array(Schema.Struct({
+		edge: LayerEdge,
+		reason: Schema.Literals([
+			"upward",
+			"sameLayer",
+			"toolingReachesLayer",
+			"intoUnconstrained",
+			"intoUnclassified"
+		])
+	})),
+	/** The members of every dependency cycle in the checked fields, or none. */
+	cycle: Schema.Option(Schema.Array(Schema.String)),
+	/** Packages the policy names that the workspace does not contain. */
+	missingDeclared: Schema.Array(Schema.String),
+	/** Required edges absent from the checked fields. */
+	missingRequiredEdges: Schema.Array(Schema.String),
+	/** Edges in the checked fields; `0` is itself a violation. */
+	edgeCount: Schema.Number
+}) {
+	/** One line per violation: `[]` means the graph honours the policy and the check was not vacuous. */
+	get violations() {
+		return [
+			...this.duplicates.map((name) => `classified more than once: ${name}`),
+			...this.unclassified.map((name) => `not classified by the policy: ${name}`),
+			...this.offenders.map(({ edge, reason }) => `${reason}: ${edge.label}`),
+			...Option.match(this.cycle, {
+				onNone: () => [],
+				onSome: (members) => [`dependency cycle among: ${members.join(", ")}`]
+			}),
+			...this.missingDeclared.map((name) => `declared but not in the workspace: ${name}`),
+			...this.missingRequiredEdges.map((edge) => `required edge missing: ${edge}`),
+			...this.edgeCount === 0 ? ["no workspace edges in the checked fields: the check is vacuous"] : []
+		];
+	}
+};
+const offence = (from, to) => {
+	if (from.kind === "unconstrained" || from.kind === "unclassified") return void 0;
+	if (to.kind === "unconstrained") return "intoUnconstrained";
+	if (to.kind === "unclassified") return "intoUnclassified";
+	if (from.kind === "tooling") return to.kind === "layer" ? "toolingReachesLayer" : void 0;
+	if (to.kind === "tooling") return void 0;
+	return to.index > from.index ? void 0 : to.index === from.index ? "sameLayer" : "upward";
+};
+/** The sorted members of every strongly connected component larger than one (cf. `DependencyGraph.ts` `cycleMembers`). */
+const cycleOf = (names, edges) => {
+	const sorted = [.../* @__PURE__ */ new Set([...names, ...edges.flatMap((e) => [e.from, e.to])])].sort();
+	const graph = Graph.directed((mutable) => {
+		const index = /* @__PURE__ */ new Map();
+		for (const name of sorted) index.set(name, Graph.addNode(mutable, name));
+		for (const e of edges) {
+			const from = index.get(e.from);
+			const to = index.get(e.to);
+			if (from !== void 0 && to !== void 0 && from !== to) Graph.addEdge(mutable, from, to, e.field);
+		}
+	});
+	const members = /* @__PURE__ */ new Set();
+	for (const component of Graph.stronglyConnectedComponents(graph)) {
+		if (component.length < 2) continue;
+		for (const index of component) {
+			const name = sorted[index];
+			if (name !== void 0) members.add(name);
+		}
+	}
+	return members.size === 0 ? Option.none() : Option.some([...members].sort());
+};
+/**
+* Holds a workspace's package graph to a committed {@link LayerPolicy}.
+*
+* @remarks
+* `check` is pure, so positive-control fixture graphs need no filesystem.
+* `edgesOf` recomputes one edge per declaring field, because
+* `DependencyGraph` merges the four fields into one adjacency and a policy
+* may check only some of them. An edge exists wherever a dependency NAME is
+* a workspace package, whatever its specifier protocol.
+*
+* @example
+* ```ts
+* import { NodeServices } from "@effect/platform-node";
+* import { Workspaces } from "@effected/workspaces";
+* import { LayerPolicy, WorkspaceLayering } from "@effected/workspaces/testing";
+* import { Effect, Layer } from "effect";
+*
+* const Live = Workspaces.layer({ cwd: "/repo" }).pipe(Layer.provideMerge(NodeServices.layer));
+*
+* const violations = Effect.gen(function* () {
+*   const policy = yield* LayerPolicy.load("/repo/layers.json");
+*   const report = yield* WorkspaceLayering.checkWorkspace(policy);
+*   return report.violations;
+* }).pipe(Effect.provide(Live));
+* ```
+*
+* @public
+*/
+var WorkspaceLayering = class WorkspaceLayering {
+	constructor() {}
+	/** Check `graph` against `policy`, reading only the policy's fields. Pure. */
+	static check = (graph, policy) => {
+		const fields = new Set(policy.effectiveFields);
+		const edges = graph.edges.filter((e) => fields.has(e.field));
+		const unconstrained = GlobSet.make({ patterns: policy.unconstrained });
+		const layerOf = /* @__PURE__ */ new Map();
+		const declared = /* @__PURE__ */ new Map();
+		const count = (name) => {
+			declared.set(name, (declared.get(name) ?? 0) + 1);
+		};
+		policy.layers.forEach((members, index) => {
+			for (const name of members) {
+				count(name);
+				if (!layerOf.has(name)) layerOf.set(name, index);
+			}
+		});
+		for (const name of policy.tooling) count(name);
+		const tooling = new Set(policy.tooling);
+		const place = (name) => {
+			const index = layerOf.get(name);
+			if (index !== void 0) return {
+				kind: "layer",
+				index
+			};
+			if (tooling.has(name)) return { kind: "tooling" };
+			return unconstrained.matches(name) ? { kind: "unconstrained" } : { kind: "unclassified" };
+		};
+		const offenders = [];
+		for (const e of edges) {
+			const reason = offence(place(e.from), place(e.to));
+			if (reason !== void 0) offenders.push({
+				edge: e,
+				reason
+			});
+		}
+		const names = new Set(graph.names);
+		const present = new Set(edges.map((e) => `${e.from} -> ${e.to}`));
+		return LayeringReport.make({
+			duplicates: [...declared].filter(([name, times]) => times > 1 || unconstrained.matches(name)).map(([name]) => name).sort(),
+			unclassified: graph.names.filter((name) => place(name).kind === "unclassified").sort(),
+			offenders,
+			cycle: cycleOf(graph.names, edges),
+			missingDeclared: [...declared.keys()].filter((name) => !names.has(name)).sort(),
+			missingRequiredEdges: (policy.requiredEdges ?? []).filter((required) => !present.has(required)),
+			edgeCount: edges.length
+		});
+	};
+	/** One edge per declaring field between workspace packages; self-edges dropped. */
+	static edgesOf = (packages) => {
+		const names = new Set(packages.map((pkg) => pkg.name));
+		return packages.flatMap((pkg) => ALL_DEPENDENCY_FIELDS.flatMap((field) => Object.keys(pkg[field]).filter((name) => names.has(name) && name !== pkg.name).sort().map((to) => LayerEdge.make({
+			from: pkg.name,
+			to,
+			field
+		}))));
+	};
+	/** Discover the workspace and check it against `policy`. */
+	static checkWorkspace = Effect.fn("WorkspaceLayering.checkWorkspace")(function* (policy) {
+		const packages = yield* (yield* WorkspaceDiscovery).listPackages();
+		return WorkspaceLayering.check({
+			names: packages.map((pkg) => pkg.name),
+			edges: WorkspaceLayering.edgesOf(packages)
+		}, policy);
+	});
+};
+
+//#endregion
+export { LayerEdge, LayeringReport, WorkspaceLayering };

package/internal/dependencyFields.js

@@ -0,0 +1,17 @@
+//#region src/internal/dependencyFields.ts
+/** Every dependency map a manifest declares, in manifest order. */
+const ALL_DEPENDENCY_FIELDS = [
+	"dependencies",
+	"devDependencies",
+	"peerDependencies",
+	"optionalDependencies"
+];
+/** The maps an installed package's own dependencies come from — never devDependencies. */
+const RUNTIME_DEPENDENCY_FIELDS = [
+	"dependencies",
+	"optionalDependencies",
+	"peerDependencies"
+];
+
+//#endregion
+export { ALL_DEPENDENCY_FIELDS, RUNTIME_DEPENDENCY_FIELDS };

package/internal/packedInstallPlan.js

@@ -0,0 +1,174 @@
+import { RUNTIME_DEPENDENCY_FIELDS } from "./dependencyFields.js";
+import { Result } from "effect";
+
+//#region src/internal/packedInstallPlan.ts
+/** Variables that carry the PARENT run's context into a child package manager. */
+const TRAPS = /* @__PURE__ */ new Set([
+	"CI",
+	"INIT_CWD",
+	"NODE_V8_COVERAGE",
+	"PNPM_SCRIPT_SRC_DIR",
+	"PNPM_PACKAGE_NAME"
+]);
+/** Prefixes of whole families of parent-run context: npm's, pnpm's config, and Yarn's. */
+const TRAP_PREFIXES = /^(npm_|pnpm_config_|yarn_)/i;
+/**
+* `env` without undefined values and without the parent's context: every
+* `npm_*` variable (a pnpm-run vitest leaks `npm_config_user_agent`), every
+* `pnpm_config_*` variable plus `PNPM_SCRIPT_SRC_DIR` and `PNPM_PACKAGE_NAME`
+* (a `pnpm exec` child carries all three, `pnpm_config_verify_deps_before_run`
+* among them), every `YARN_*` variable (Berry lets them override
+* `.yarnrc.yml`, so `YARN_NODE_LINKER=pnp` would defeat the consumer's
+* `nodeLinker`), `CI` (Yarn Berry turns on immutable installs), `INIT_CWD`,
+* and `NODE_V8_COVERAGE` (a spawned manager writes coverage files that race
+* vitest's V8 provider).
+*
+* Stripping `CI` does not make the child believe it runs locally: ci-info
+* also reads provider variables such as `GITHUB_ACTIONS`, which stay. That is
+* harmless today, because the only CI-conditional behaviour a consumer
+* install trips on (Berry's immutable installs, pnpm's frozen lockfile) keys
+* on a lockfile the fresh consumer does not have, or is switched off in the
+* files `consumerFiles` writes.
+*
+* User-level configuration is inherited by design: `HOME` stays, so each
+* manager still reads the user's `~/.npmrc`, `~/.yarnrc.yml` and friends, and
+* with them the registry, auth and proxy a real install on this machine
+* would use.
+*/
+const scrubEnv = (env) => {
+	const out = {};
+	for (const [key, value] of Object.entries(env)) if (value !== void 0 && !TRAP_PREFIXES.test(key) && !TRAPS.has(key)) out[key] = value;
+	return out;
+};
+/** The last version-shaped line of `--version` output, without a leading `v`. */
+const versionOf = (stdout) => {
+	for (const line of stdout.split(/\r?\n/).reverse()) {
+		const match = /^v?(\d+\.\d+\.\d+\S*)$/.exec(line.trim());
+		if (match?.[1] !== void 0) return match[1];
+	}
+};
+/** The carrier first, then the rest of the closure; the failure names the first package the workspace lacks. */
+const closureOf = (packages, carrier, closure) => {
+	const byName = new Map(packages.map((pkg) => [pkg.name, pkg]));
+	const root = byName.get(carrier);
+	if (root === void 0) return Result.fail(carrier);
+	if (closure !== "auto") {
+		const unknown = closure.find((name) => !byName.has(name));
+		if (unknown !== void 0) return Result.fail(unknown);
+		const rest = [...new Set(closure)].filter((name) => name !== carrier);
+		return Result.succeed([root, ...rest.flatMap((name) => byName.get(name) ?? [])]);
+	}
+	const ordered = [root];
+	const seen = /* @__PURE__ */ new Set([carrier]);
+	for (let head = 0; head < ordered.length; head++) {
+		const current = ordered[head];
+		if (current === void 0) continue;
+		for (const field of RUNTIME_DEPENDENCY_FIELDS) for (const name of Object.keys(current[field]).sort()) {
+			const dependency = byName.get(name);
+			if (dependency !== void 0 && !seen.has(name)) {
+				seen.add(name);
+				ordered.push(dependency);
+			}
+		}
+	}
+	return Result.succeed(ordered);
+};
+const major = (version) => Number.parseInt(version.split(".")[0] ?? "", 10);
+const YARNRC = "nodeLinker: node-modules\nenableImmutableInstalls: false\nenableScripts: false\nenableTelemetry: false\n";
+/** JSON strings are valid YAML double-quoted scalars. */
+const pnpmWorkspaceYaml = (specs) => {
+	const entries = Object.entries(specs);
+	return entries.length === 0 ? "overrides: {}\n" : `overrides:\n${entries.map(([name, spec]) => `  ${JSON.stringify(name)}: ${JSON.stringify(spec)}`).join("\n")}\n`;
+};
+/**
+* The files of one scratch consumer. The carrier and the caller's extra
+* dependencies are its only direct dependencies; every other packed package
+* is steered to its tarball through the field this manager reads:
+* `overrides` (npm, bun), `resolutions` (yarn), or a settings-only
+* `pnpm-workspace.yaml` (pnpm 10+ reads overrides there, and pnpm 11+ no
+* longer reads `package.json#pnpm`).
+*
+* An extra dependency that names a packed package (the carrier or a closure
+* member) is written as that package's `file:` tarball spec, whatever the
+* caller passed: the packed tarball always wins. npm fails an install whose
+* override differs from a direct spec for the same package (`EOVERRIDE`), and
+* accepts one that is identical; and a caller's range must never silently
+* replace the tarball the run exists to prove.
+*/
+const consumerFiles = (input) => {
+	const specs = Object.fromEntries(Object.entries(input.overrides).map(([name, tarball]) => [name, `file:${tarball}`]));
+	const carrierSpec = `file:${input.carrier.tarball}`;
+	const extra = Object.fromEntries(Object.entries(input.dependencies).filter(([name]) => name !== input.carrier.name).map(([name, spec]) => [name, Object.hasOwn(specs, name) ? specs[name] ?? spec : spec]));
+	const manifest = {
+		name: `packed-install-${input.manager}`,
+		version: "0.0.0",
+		private: true,
+		...input.manager === "pnpm" ? { devEngines: { packageManager: {
+			name: "pnpm",
+			version: input.version,
+			onFail: "ignore"
+		} } } : { packageManager: `${input.manager}@${input.version}` },
+		dependencies: {
+			[input.carrier.name]: carrierSpec,
+			...extra
+		},
+		...input.manager === "npm" || input.manager === "bun" ? { overrides: specs } : {},
+		...input.manager === "yarn" ? { resolutions: specs } : {}
+	};
+	const files = [{
+		file: "package.json",
+		content: `${JSON.stringify(manifest, null, 2)}\n`
+	}];
+	if (input.manager === "pnpm") files.push({
+		file: "pnpm-workspace.yaml",
+		content: pnpmWorkspaceYaml(specs)
+	});
+	if (input.manager === "yarn" && major(input.version) >= 2) files.push({
+		file: ".yarnrc.yml",
+		content: YARNRC
+	});
+	return files;
+};
+/** The install argv, lifecycle scripts skipped the way this manager spells it. */
+const installArgs = (manager, version) => {
+	switch (manager) {
+		case "npm": return [
+			"install",
+			"--ignore-scripts",
+			"--no-audit",
+			"--no-fund"
+		];
+		case "pnpm": return ["install", "--config.ignore-scripts=true"];
+		case "yarn": return major(version) >= 2 ? ["install"] : [
+			"install",
+			"--ignore-scripts",
+			"--non-interactive"
+		];
+		case "bun": return ["install", "--ignore-scripts"];
+	}
+};
+/**
+* A specifier no consumer outside the workspace can resolve: `workspace:`,
+* `catalog:`, `link:`, or a relative `file:` path. An absolute `file:` path
+* is left alone: it resolves wherever the file exists.
+*/
+const UNRESOLVABLE = /^(?:workspace:|catalog:|link:|file:(?!\/))/;
+/** Every specifier in a packed manifest's runtime maps that only the workspace could resolve (see `UNRESOLVABLE`). */
+const unresolvedSpecifiers = (manifestJson) => {
+	let manifest;
+	try {
+		manifest = JSON.parse(manifestJson);
+	} catch (cause) {
+		return Result.fail(cause);
+	}
+	if (typeof manifest !== "object" || manifest === null) return Result.fail(/* @__PURE__ */ new Error("package.json is not an object"));
+	const record = manifest;
+	return Result.succeed(RUNTIME_DEPENDENCY_FIELDS.flatMap((field) => {
+		const block = record[field];
+		if (typeof block !== "object" || block === null) return [];
+		return Object.entries(block).filter(([, spec]) => typeof spec === "string" && UNRESOLVABLE.test(spec)).map(([name, spec]) => `${field}.${name}: ${String(spec)}`);
+	}));
+};
+
+//#endregion
+export { closureOf, consumerFiles, installArgs, scrubEnv, unresolvedSpecifiers, versionOf };