rolldown-pnpm-config 0.1.0

package/plugin/freeze.js

@@ -0,0 +1,79 @@
+import { normalizeCatalogs } from "../catalogs.js";
+import { DESCRIPTORS, deriveSchemas } from "../descriptors/index.js";
+import { FIELD_REGISTRY } from "../registry.js";
+import { Data, Effect, Schema } from "effect";
+
+//#region src/plugin/freeze.ts
+/**
+* Typed failure for invalid plugin configuration, surfaced as a build error.
+*
+* @internal
+*/
+var ConfigError = class extends Data.TaggedError("ConfigError") {};
+/** Per-field value-shape schemas; only declared fields are validated. */
+const FIELD_SCHEMAS = deriveSchemas(DESCRIPTORS);
+const CatalogsSchema = FIELD_SCHEMAS.catalogs;
+/** Keys recognized by the wrapped `{ value, enforcement?, excludeByRepo? }` form. */
+const WRAPPED_KEYS = /* @__PURE__ */ new Set([
+	"value",
+	"enforcement",
+	"excludeByRepo"
+]);
+/** True only when `input` is the wrapped form: a `value` key and no foreign keys.
+*  This disambiguates from a record-valued field that happens to contain a
+*  `value` key (e.g. `overrides: { value: ">=1", lodash: ">=4" }`), which has
+*  keys outside the recognized set and is therefore treated as a bare value. */
+function isWrappedField(input) {
+	const keys = Object.keys(input);
+	return keys.includes("value") && keys.every((k) => WRAPPED_KEYS.has(k));
+}
+function normalizeField(input) {
+	if (input !== null && typeof input === "object" && isWrappedField(input)) {
+		const o = input;
+		return {
+			value: o.value,
+			...o.enforcement !== void 0 ? { enforcement: o.enforcement } : {},
+			...o.excludeByRepo !== void 0 ? { options: { excludeByRepo: o.excludeByRepo } } : {}
+		};
+	}
+	return { value: input };
+}
+/**
+* Validate + freeze the plugin config into base data + a strategy manifest. The
+* only place Effect runs; invoked once at build time inside the plugin.
+*
+* @internal
+*/
+function freeze(config) {
+	return Effect.gen(function* () {
+		const base = {};
+		const manifest = {};
+		base.catalogs = yield* Schema.decodeUnknown(CatalogsSchema)(normalizeCatalogs(config.catalogs)).pipe(Effect.mapError((error) => new ConfigError({ message: `Invalid catalogs: ${String(error)}` })));
+		manifest.catalogs = {
+			strategy: "catalogs",
+			enforcement: "warn"
+		};
+		if (typeof config.name !== "string" || config.name.trim() === "") return yield* Effect.fail(new ConfigError({ message: "Config `name` is required and must be a non-empty string" }));
+		for (const [field, reg] of Object.entries(FIELD_REGISTRY)) {
+			if (field === "catalogs") continue;
+			const raw = config[field];
+			if (raw === void 0) continue;
+			const decl = normalizeField(raw);
+			const schema = FIELD_SCHEMAS[field];
+			base[field] = schema ? yield* Schema.decodeUnknown(schema)(decl.value).pipe(Effect.mapError((error) => new ConfigError({ message: `Invalid ${field}: ${String(error)}` }))) : decl.value;
+			manifest[field] = {
+				strategy: reg.strategy,
+				enforcement: decl.enforcement ?? reg.enforcement,
+				...decl.options ? { options: decl.options } : {}
+			};
+		}
+		return {
+			base,
+			manifest,
+			name: config.name
+		};
+	});
+}
+
+//#endregion
+export { ConfigError, freeze };

package/plugin/index.js

@@ -0,0 +1,48 @@
+import { freeze } from "./freeze.js";
+import { emitCatalogsModule, emitPnpmfileModule } from "./serialize.js";
+import { Effect } from "effect";
+
+//#region src/plugin/index.ts
+const PNPMFILE_SPEC = "rolldown-pnpm-config/virtual/pnpmfile";
+const CATALOGS_SPEC = "rolldown-pnpm-config/virtual/catalogs";
+/**
+* Internal factory for the rolldown plugin. Accepts an optional DI seam for
+* testing (freeze spy). The Effect freeze runs once (memoized) and is reused
+* across every tsdown pass (JS, dts, declarations, looseFiles).
+*
+* @internal
+*/
+function createPnpmConfigPlugin(config, deps = { freeze }) {
+	let frozen;
+	const getFrozen = () => frozen ??= Effect.runPromise(deps.freeze(config));
+	return {
+		name: "rolldown-pnpm-config",
+		resolveId(source) {
+			if (source === PNPMFILE_SPEC || source === CATALOGS_SPEC) return `\0${source}`;
+			return null;
+		},
+		async load(id) {
+			if (id === `\0${PNPMFILE_SPEC}`) {
+				const { base, manifest, name } = await getFrozen();
+				return emitPnpmfileModule(base, manifest, name);
+			}
+			if (id === `\0${CATALOGS_SPEC}`) {
+				const { base } = await getFrozen();
+				return emitCatalogsModule(base.catalogs ?? {});
+			}
+			return null;
+		}
+	};
+}
+/**
+* Rolldown plugin that serves the two virtual pnpm-config modules. Pass a
+* `PluginConfig` object and the plugin handles the rest.
+*
+* @public
+*/
+function PnpmConfigPlugin(config) {
+	return createPnpmConfigPlugin(config);
+}
+
+//#endregion
+export { PnpmConfigPlugin, createPnpmConfigPlugin };

package/plugin/serialize.js

@@ -0,0 +1,26 @@
+//#region src/plugin/serialize.ts
+/** Recursively sort object keys for deterministic output; arrays keep order. */
+function sortKeys(value) {
+	if (Array.isArray(value)) return value.map(sortKeys);
+	if (value !== null && typeof value === "object") return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => [k, sortKeys(v)]));
+	return value;
+}
+/** Source for the `catalogs` virtual module: a sorted Map literal (plain-JS branch). */
+function emitCatalogsModule(catalogs) {
+	const sorted = sortKeys(catalogs);
+	return `export const catalogs = new Map([${Object.entries(sorted).map(([name, entries]) => {
+		const inner = Object.entries(entries).map(([pkg, range]) => `[${JSON.stringify(pkg)}, ${JSON.stringify(range)}]`).join(", ");
+		return `[${JSON.stringify(name)}, new Map([${inner}])]`;
+	}).join(", ")}]);\n`;
+}
+/** Source for the `pnpmfile` virtual module: createHooks over base + manifest. */
+function emitPnpmfileModule(base, manifest, name) {
+	return [
+		"import { createHooks } from \"rolldown-pnpm-config/runtime\";",
+		`export const hooks = createHooks(${JSON.stringify(sortKeys(base))}, ${JSON.stringify(sortKeys(manifest))}, ${JSON.stringify(name)});`,
+		""
+	].join("\n");
+}
+
+//#endregion
+export { emitCatalogsModule, emitPnpmfileModule, sortKeys };

package/registry.js

@@ -0,0 +1,8 @@
+import { DESCRIPTORS, deriveRegistry } from "./descriptors/index.js";
+
+//#region src/registry.ts
+/** Maps each known pnpm field to its strategy + default enforcement. Derived from the descriptor table. @internal */
+const FIELD_REGISTRY = deriveRegistry(DESCRIPTORS);
+
+//#endregion
+export { FIELD_REGISTRY };

package/runtime/ctx.js

@@ -0,0 +1,39 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+//#region src/runtime/ctx.ts
+/**
+* Resolve the consuming repo's root package name. Prefers pnpm's
+* `rootProjectManifest.name`, falling back to reading `package.json` from the
+* workspace/lockfile dir.
+*
+* @internal
+*/
+function resolveRootName(config) {
+	const c = config;
+	if (c.rootProjectManifest?.name) return c.rootProjectManifest.name;
+	const rootDir = c.rootProjectManifestDir ?? c.lockfileDir ?? c.workspaceDir ?? c.dir ?? process.cwd();
+	try {
+		return JSON.parse(readFileSync(join(rootDir, "package.json"), "utf8")).name;
+	} catch {
+		return;
+	}
+}
+/**
+* Drop packages assigned to the consuming repo from a merged hoist list.
+* Drop packages listed in the per-repo exclusion table (`byRepo`).
+*
+* @param merged - The full merged hoist-pattern list before repo-specific exclusions.
+* @param ctx - Runtime context; `ctx.rootName` is the consuming repo's root `package.json` `name`.
+* @param byRepo Keyed by consuming-repo package.json name; value = hoist patterns dropped in that repo.
+* @internal
+*/
+function excludeByRepo(merged, ctx, byRepo) {
+	const exclude = ctx.rootName ? byRepo[ctx.rootName] : void 0;
+	if (!exclude || exclude.length === 0) return merged;
+	const set = new Set(exclude);
+	return merged.filter((p) => !set.has(p));
+}
+
+//#endregion
+export { excludeByRepo, resolveRootName };

package/runtime/enforcement.js

@@ -0,0 +1,36 @@
+//#region src/runtime/enforcement.ts
+/**
+* Thrown when an `error`-enforced field diverges. A zero-dependency plain
+* `Error` subclass (NOT an Effect type) so it survives in the bundled pnpmfile.
+* It is intended to fail the install and must never be swallowed by an install
+* guard — see the note in `runtime/index.ts`.
+*
+* @internal
+*/
+var EnforcementError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "EnforcementError";
+	}
+};
+/**
+* Apply enforcement to a strategy result, partitioning its divergences into
+* override and security buckets for the runtime to print. When enforcement is
+* `error` and there is at least one divergence, throws {@link EnforcementError}.
+*
+* @internal
+*/
+function applyEnforcement(field, result, enforcement) {
+	const overrides = [];
+	const security = [];
+	if (result.divergences.length > 0 && enforcement === "error") throw new EnforcementError(`Field "${field}" is enforced (error) but the local config diverges: ${result.divergences.map((d) => d.setting).join(", ")}`);
+	if (result.divergences.length > 0 && enforcement === "warn") for (const d of result.divergences) (d.kind === "security" ? security : overrides).push(d);
+	return {
+		value: result.merged,
+		overrides,
+		security
+	};
+}
+
+//#endregion
+export { EnforcementError, applyEnforcement };

package/runtime/strategies/arrays.js

@@ -0,0 +1,37 @@
+//#region src/runtime/strategies/arrays.ts
+function unionSort(managed, local) {
+	const set = new Set(managed);
+	for (const item of local ?? []) set.add(item);
+	return [...set].sort((a, b) => a.localeCompare(b));
+}
+/**
+* Union + sort string arrays; child entries are added to the managed set. Quiet.
+*
+* @internal
+*/
+const arrayUnion = (base, local) => ({
+	merged: unionSort(base ?? [], local),
+	divergences: []
+});
+/**
+* Per-axis union of a record of string arrays; drops empty axes. Quiet.
+*
+* @internal
+*/
+const arrayRecordUnion = (base, local) => {
+	const managed = base ?? {};
+	const child = local ?? {};
+	const keys = /* @__PURE__ */ new Set([...Object.keys(managed), ...Object.keys(child)]);
+	const result = {};
+	for (const key of [...keys].sort((a, b) => a.localeCompare(b))) {
+		const merged = unionSort(managed[key] ?? [], child[key]);
+		if (merged.length > 0) result[key] = merged;
+	}
+	return {
+		merged: result,
+		divergences: []
+	};
+};
+
+//#endregion
+export { arrayRecordUnion, arrayUnion };

package/runtime/strategies/catalogs.js

@@ -0,0 +1,36 @@
+//#region src/runtime/strategies/catalogs.ts
+/**
+* Merge each named catalog; child wins per package. Emits override divergences
+* when a local version differs from the managed one.
+*
+* @internal
+*/
+const catalogs = (base, local) => {
+	const managed = base ?? {};
+	const child = local ?? {};
+	const divergences = [];
+	const merged = { ...child };
+	for (const [name, entries] of Object.entries(managed)) {
+		const childCat = child[name] ?? {};
+		const out = { ...entries };
+		for (const [pkg, childVersion] of Object.entries(childCat)) {
+			const managedVersion = entries[pkg];
+			if (managedVersion !== void 0 && managedVersion !== childVersion) divergences.push({
+				setting: `catalogs.${name}.${pkg}`,
+				managedValue: managedVersion,
+				localValue: childVersion,
+				detail: "Local version overrides the managed version.",
+				kind: "override"
+			});
+			out[pkg] = childVersion;
+		}
+		merged[name] = out;
+	}
+	return {
+		merged,
+		divergences
+	};
+};
+
+//#endregion
+export { catalogs };

package/runtime/strategies/maps.js

@@ -0,0 +1,46 @@
+//#region src/runtime/strategies/maps.ts
+/**
+* `{...managed, ...child}` — child wins per key. Quiet. Merges two maps,
+* preferring child values.
+*
+* @internal
+*/
+const mapChildWins = (base, local) => {
+	const managed = base ?? {};
+	const child = local;
+	return {
+		merged: child ? {
+			...managed,
+			...child
+		} : { ...managed },
+		divergences: []
+	};
+};
+/**
+* `{...managed, ...child}`; flags enabling a build the managed config blocked.
+* Detects allow-builds loosening.
+*
+* @internal
+*/
+const allowBuilds = (base, local) => {
+	const managed = base ?? {};
+	const child = local ?? {};
+	const divergences = [];
+	for (const [pkg, childAllowed] of Object.entries(child)) if (childAllowed === true && managed[pkg] === false) divergences.push({
+		setting: `allowBuilds.${pkg}`,
+		managedValue: "false",
+		localValue: "true",
+		detail: `Enables build scripts for "${pkg}" that the managed config blocked.`,
+		kind: "security"
+	});
+	return {
+		merged: {
+			...managed,
+			...child
+		},
+		divergences
+	};
+};
+
+//#endregion
+export { allowBuilds, mapChildWins };

package/runtime/strategies/overrides.js

@@ -0,0 +1,57 @@
+//#region src/runtime/strategies/overrides.ts
+function mergeMapDetect(prefix, managed, child) {
+	const merged = { ...managed };
+	const divergences = [];
+	for (const [k, childVersion] of Object.entries(child)) {
+		const managedVersion = managed[k];
+		if (managedVersion !== void 0 && managedVersion !== childVersion) divergences.push({
+			setting: `${prefix}.${k}`,
+			managedValue: managedVersion,
+			localValue: childVersion,
+			detail: "Local version overrides the managed version.",
+			kind: "override"
+		});
+		merged[k] = childVersion;
+	}
+	return {
+		merged,
+		divergences
+	};
+}
+/**
+* Security overrides: child wins per key; any diff → override divergence.
+* Merge overrides, flagging local divergences.
+*
+* @internal
+*/
+const overrides = (base, local) => {
+	const { merged, divergences } = mergeMapDetect("overrides", base ?? {}, local ?? {});
+	return {
+		merged,
+		divergences
+	};
+};
+/**
+* peerDependencyRules: `allowedVersions` is override-detected; `ignoreMissing`
+* and `allowAny` are unioned + sorted. Merges peer-dependency rules,
+* flagging version overrides.
+*
+* @internal
+*/
+const peerDependencyRules = (base, local) => {
+	const managed = base ?? {};
+	const child = local ?? {};
+	const av = mergeMapDetect("peerDependencyRules.allowedVersions", managed.allowedVersions ?? {}, child.allowedVersions ?? {});
+	const union = (s = [], c = []) => [.../* @__PURE__ */ new Set([...s, ...c])].sort((a, b) => a.localeCompare(b));
+	return {
+		merged: {
+			allowedVersions: av.merged,
+			ignoreMissing: union(managed.ignoreMissing, child.ignoreMissing),
+			allowAny: union(managed.allowAny, child.allowAny)
+		},
+		divergences: av.divergences
+	};
+};
+
+//#endregion
+export { overrides, peerDependencyRules };

package/runtime/strategies/scalar.js

@@ -0,0 +1,57 @@
+//#region src/runtime/strategies/scalar.ts
+/**
+* `child ?? base` — quiet (no divergences). Prefer local, fall back to managed.
+*
+* @internal
+*/
+const scalar = (base, local) => ({
+	merged: local ?? base,
+	divergences: []
+});
+/**
+* `child ?? base`; flags when child disables a managed boolean. The strategy is
+* field-agnostic, so it emits `setting: ""`; the runtime fills the field name.
+* Detects flag loosening.
+*
+* @internal
+*/
+const securityFlag = (base, local) => {
+	const merged = local ?? base;
+	const divergences = [];
+	if (base === true && local === false) divergences.push({
+		setting: "",
+		managedValue: "true",
+		localValue: "false",
+		detail: "Disables a security check the managed config enabled.",
+		kind: "security"
+	});
+	return {
+		merged,
+		divergences
+	};
+};
+/**
+* `child ?? base`; flags when child lowers the value. Field-agnostic, so it
+* emits `setting: ""`; the runtime fills the field name. Detects
+* minimum-release-age loosening.
+*
+* @internal
+*/
+const securityMin = (base, local) => {
+	const merged = local ?? base;
+	const divergences = [];
+	if (typeof base === "number" && typeof local === "number" && local < base) divergences.push({
+		setting: "",
+		managedValue: String(base),
+		localValue: String(local),
+		detail: `Shortens the release-age quarantine from ${base} to ${local} minutes.`,
+		kind: "security"
+	});
+	return {
+		merged,
+		divergences
+	};
+};
+
+//#endregion
+export { scalar, securityFlag, securityMin };

package/runtime/strategies/table.js

@@ -0,0 +1,27 @@
+import { arrayRecordUnion, arrayUnion } from "./arrays.js";
+import { catalogs } from "./catalogs.js";
+import { allowBuilds, mapChildWins } from "./maps.js";
+import { overrides, peerDependencyRules } from "./overrides.js";
+import { scalar, securityFlag, securityMin } from "./scalar.js";
+
+//#region src/runtime/strategies/table.ts
+/**
+* Built-in strategies keyed by manifest name.
+*
+* @internal
+*/
+const STRATEGY_TABLE = {
+	scalar,
+	catalogs,
+	mapChildWins,
+	arrayUnion,
+	arrayRecordUnion,
+	overrides,
+	peerDependencyRules,
+	securityFlag,
+	securityMin,
+	allowBuilds
+};
+
+//#endregion
+export { STRATEGY_TABLE };

package/runtime/warnings.js

@@ -0,0 +1,61 @@
+//#region src/runtime/warnings.ts
+const WARNING_BOX_WIDTH = 75;
+function pad(line) {
+	return `│${line}${" ".repeat(Math.max(0, WARNING_BOX_WIDTH - line.length - 2))}│`;
+}
+/**
+* Format override divergences into a prominent warning box for console output,
+* tagged with the emitting config's `name`. `Divergence.setting` is the
+* already-resolved config path, printed directly.
+*
+* @internal
+*/
+function formatOverrideWarning(divergences, name) {
+	if (divergences.length === 0) return "";
+	const border = "─".repeat(WARNING_BOX_WIDTH - 2);
+	const lines = [];
+	lines.push(`┌${border}┐`);
+	lines.push(pad(`  [${name}]`));
+	lines.push(pad("  ⚠️  CATALOG OVERRIDE DETECTED"));
+	lines.push(`├${border}┤`);
+	lines.push(pad("  The following entries override managed versions:"));
+	lines.push(pad(""));
+	for (const d of divergences) {
+		lines.push(pad(`  ${d.setting}`));
+		lines.push(pad(`    Managed version: ${d.managedValue}`));
+		lines.push(pad(`    Local override:  ${d.localValue}`));
+		lines.push(pad(""));
+	}
+	lines.push(pad("  Local versions will be used. To use the managed defaults, remove"));
+	lines.push(pad("  these entries from your pnpm-workspace.yaml."));
+	lines.push(`└${border}┘`);
+	return lines.join("\n");
+}
+/**
+* Format security-loosening divergences into a prominent box, tagged with the
+* emitting config's `name`.
+*
+* @internal
+*/
+function formatSecurityWarning(divergences, name) {
+	if (divergences.length === 0) return "";
+	const border = "─".repeat(WARNING_BOX_WIDTH - 2);
+	const lines = [];
+	lines.push(`┌${border}┐`);
+	lines.push(pad(`  [${name}]`));
+	lines.push(pad("  ⚠️  SECURITY OVERRIDE DETECTED"));
+	lines.push(`├${border}┤`);
+	lines.push(pad("  The following entries weaken managed security defaults:"));
+	lines.push(pad(""));
+	for (const d of divergences) {
+		lines.push(pad(`  ${d.setting}: managed=${d.managedValue} -> local=${d.localValue}`));
+		lines.push(pad(`    ${d.detail}`));
+		lines.push(pad(""));
+	}
+	lines.push(pad("  Local values will be used. Review these before shipping."));
+	lines.push(`└${border}┘`);
+	return lines.join("\n");
+}
+
+//#endregion
+export { formatOverrideWarning, formatSecurityWarning };

package/runtime.d.ts

@@ -0,0 +1,111 @@
+//#region src/runtime/types.d.ts
+/**
+ * Minimal pnpm config shape — only the fields this plugin reads/writes.
+ *
+ * @public
+ */
+interface PnpmConfig {
+  /** Named catalogs injected into pnpm's workspace configuration. */
+  catalogs?: Record<string, Record<string, string>>;
+  [key: string]: unknown;
+}
+/**
+ * The pnpm pnpmfile hooks object.
+ *
+ * @public
+ */
+interface PnpmHooks {
+  /** Merges the frozen, managed config into the consumer's pnpm config. */
+  updateConfig(config: PnpmConfig): PnpmConfig;
+}
+/**
+ * A single detected difference between the managed value and the consumer's
+ * local value, classified as either an override or a security loosening.
+ *
+ * @internal
+ */
+interface Divergence {
+  readonly setting: string;
+  readonly managedValue: string;
+  readonly localValue: string;
+  readonly detail: string;
+  readonly kind: "override" | "security";
+}
+/**
+ * Per-install context resolved once and threaded into every strategy.
+ *
+ * @internal
+ */
+interface RuntimeCtx {
+  readonly rootName: string | undefined;
+}
+/**
+ * The result of running a strategy: the merged value plus any divergences the
+ * strategy detected along the way.
+ *
+ * @internal
+ */
+interface StrategyResult {
+  readonly merged: unknown;
+  readonly divergences: readonly Divergence[];
+}
+/**
+ * A pure merge function for one field: combine the managed base with the local
+ * value, reporting any divergences.
+ *
+ * @internal
+ */
+type Strategy = (base: unknown, local: unknown, ctx: RuntimeCtx) => StrategyResult;
+/**
+ * How a field's divergences are enforced: silent, console warning, or a thrown
+ * error that fails the install. Part of the public authoring API via
+ * `FieldInput` and the runtime `createHooks` manifest.
+ *
+ * @public
+ */
+type Enforcement = "absent" | "warn" | "error";
+/**
+ * One field's manifest entry: which strategy merges it, how it is enforced, and
+ * any strategy-specific options (e.g. a refine table). Part of the public
+ * `createHooks` contract.
+ *
+ * @public
+ */
+interface ManifestEntry {
+  readonly strategy: string;
+  readonly enforcement: Enforcement;
+  readonly options?: Record<string, unknown>;
+}
+/**
+ * The field → strategy/enforcement manifest emitted at build time and consumed
+ * by the public `createHooks`.
+ *
+ * @public
+ */
+type Manifest = Record<string, ManifestEntry>;
+/**
+ * The field → frozen value base emitted at build time and consumed by the
+ * public `createHooks`.
+ *
+ * @public
+ */
+type Base = Record<string, unknown>;
+//#endregion
+//#region src/runtime/index.d.ts
+/**
+ * Build the pnpm hooks from frozen base data + a field→strategy manifest.
+ * Zero dependencies — bundled verbatim into the shipped pnpmfile.
+ *
+ * @remarks
+ * `updateConfig` deliberately has no catch-and-fall-back-to-local guard: an
+ * `error`-enforced divergence throws `EnforcementError`, which is meant to
+ * propagate and fail the install. If a swallow-guard is ever added here, it MUST
+ * rethrow `EnforcementError` (check `err instanceof EnforcementError` /
+ * `err.name === "EnforcementError"`) rather than fall back to the local config.
+ *
+ * @public
+ */
+declare function createHooks(base: Base, manifest: Manifest, name: string): PnpmHooks;
+//#endregion
+export { Base, Divergence, Enforcement, Manifest, ManifestEntry, PnpmConfig, PnpmHooks, RuntimeCtx, Strategy, StrategyResult, createHooks };
+//# sourceMappingURL=runtime.d.ts.map