cluaupp 1.5.0 → 1.5.1

package/src/native/index.ts

@@ -280,15 +280,14 @@ function compileHelm(source: string, file: string, defaultName: string): NativeE
 		id += 1;
 	}
 	const { headerRel, luauRel } = emitPaths(file, name);
-	const headerFns = commands
-		.map((cmd) => {
-			const params = cmd.args.map((arg) => `${arg.type === "i32" ? "int" : arg.type} ${arg.name}`).join(", ");
-			return `\tvoid ${cmd.name}(${params});`;
-		})
+	const headerCmds = commands
+		.map((cmd, index) => `\t// command ${cmd.name} permission ${cmd.permission}\n\tconst int ${cmd.name} = ${index + 1};`)
 		.join("\n");
 	const header = `${headerBanner("helm")}
+#include <clpp/libs/helm.clh>
 namespace ${name} {
-${headerFns}
+${headerCmds}
+	HelmSession Open(Player player);
 }
 `;
 	const rows = commands
@@ -417,7 +416,7 @@ function compileHive(source: string, file: string, defaultName: string): NativeE
 #include <clpp/libs/hive.clh>
 namespace ${name} {
 ${components.map((item, index) => `\tconst int ${item.name} = ${index + 1};`).join("\n")}
-	HiveWorld New();
+	auto New();
 }
 `;
 	const rows = components
@@ -443,32 +442,242 @@ return ${name}
 	return { headerRel, headerPath: headerRel, header, luauRel, luau };
 }
 
+/** Mirrors Axiom.Groups + axiom.clh prototypes for IntelliSense on selected namespaces. */
+const AXIOM_GROUP_DECLS: Record<string, string[]> = {
+	Scalar: [
+		"double Clamp(double value, double min, double max);",
+		"double Map(double value, double inMin, double inMax, double outMin, double outMax);",
+		"double Wrap(double value, double min, double max);",
+		"double Sign(double value);",
+		"double Round(double value);",
+		"double Round(double value, int digits);",
+		"double Snap(double value, double step);",
+		"double PingPong(double t, double length);",
+		"double Saturate(double value);",
+		"double Fract(double value);",
+		"double InvLerp(double from, double to, double value);",
+		"double Approach(double current, double target, double maxDelta);",
+		"bool IsFinite(double value);",
+		"double Abs(double value);",
+		"double Min(double a, double b);",
+		"double Max(double a, double b);",
+		"double Pow(double base, double exp);",
+		"double Sqrt(double value);",
+		"double Cbrt(double value);",
+		"double Hypot(double a, double b);",
+		"double Log(double value);",
+		"double Exp(double value);",
+		"double Smoothstep(double edge0, double edge1, double x);",
+		"double Smootherstep(double edge0, double edge1, double x);",
+		"double Gcd(double a, double b);",
+		"double Lcm(double a, double b);",
+		"bool IsEven(double value);",
+		"bool IsOdd(double value);",
+		"double Factorial(double n);",
+		"double Scale(double value, int index);",
+	],
+	Lerp: [
+		"double Lerp(double from, double to, double alpha);",
+		"double LerpClamped(double from, double to, double alpha);",
+		"Vector2 LerpVector2(Vector2 from, Vector2 to, double alpha);",
+		"Vector3 LerpVector3(Vector3 from, Vector3 to, double alpha);",
+		"Vector3 LerpVector(Vector3 from, Vector3 to, double alpha);",
+		"Color3 LerpColor3(Color3 from, Color3 to, double alpha);",
+		"CFrame LerpCFrame(CFrame from, CFrame to, double alpha);",
+		"UDim2 LerpUDim2(UDim2 from, UDim2 to, double alpha);",
+		"double LerpAngle(double from, double to, double alpha);",
+		"double Inverse(double from, double to, double value);",
+	],
+	Vector: [
+		"Vector3 Project(Vector3 a, Vector3 b);",
+		"Vector3 Reject(Vector3 a, Vector3 b);",
+		"Vector3 Reflect(Vector3 incident, Vector3 normal);",
+		"double Angle(Vector3 a, Vector3 b);",
+		"double Distance(Vector3 a, Vector3 b);",
+		"double Distance2(Vector2 a, Vector2 b);",
+		"CFrame Orthonormal(Vector3 forward);",
+		"CFrame Orthonormal(Vector3 forward, Vector3 up);",
+		"Vector3 Slerp(Vector3 a, Vector3 b, double t);",
+		"CFrame LookAt(Vector3 from, Vector3 look);",
+	],
+	CFrame: ["CFrame SlerpCFrame(CFrame a, CFrame b, double t);", "CFrame Flat(CFrame cf);"],
+	Easing: [
+		"double InSine(double t);",
+		"double OutSine(double t);",
+		"double InOutSine(double t);",
+		"double InQuad(double t);",
+		"double OutQuad(double t);",
+		"double InOutQuad(double t);",
+		"double InCubic(double t);",
+		"double OutCubic(double t);",
+		"double InOutCubic(double t);",
+		"double InQuart(double t);",
+		"double OutQuart(double t);",
+		"double InOutQuart(double t);",
+		"double InQuint(double t);",
+		"double OutQuint(double t);",
+		"double InOutQuint(double t);",
+		"double InExpo(double t);",
+		"double OutExpo(double t);",
+		"double InOutExpo(double t);",
+		"double InCirc(double t);",
+		"double OutCirc(double t);",
+		"double InOutCirc(double t);",
+		"double InBack(double t);",
+		"double OutBack(double t);",
+		"double InOutBack(double t);",
+		"double InElastic(double t);",
+		"double OutElastic(double t);",
+		"double InOutElastic(double t);",
+		"double InBounce(double t);",
+		"double OutBounce(double t);",
+		"double InOutBounce(double t);",
+		"double Linear(double t);",
+	],
+	Bezier: [
+		"Vector3 CubicBezier(double t, Vector3 p0, Vector3 p1, Vector3 p2, Vector3 p3);",
+		"Vector3 QuadraticBezier(double t, Vector3 p0, Vector3 p1, Vector3 p2);",
+		"CFrame Hover(double elapsed, Vector3 anchor, Vector3 look);",
+		"CFrame Float(double elapsed, Vector3 anchor, Vector3 look);",
+		"CFrame FloatSpin(double elapsed, CFrame anchor);",
+	],
+	Geometry: [
+		"bool AabbContains(Vector3 point, Vector3 min, Vector3 max);",
+		"bool SphereContains(Vector3 point, Vector3 center, double radius);",
+		"Vector3 RayPlane(Vector3 origin, Vector3 dir, Vector3 point, Vector3 normal);",
+		"Vector3 Barycentric(Vector3 p, Vector3 a, Vector3 b, Vector3 c);",
+		"Vector3 ClosestPointOnSegment(Vector3 p, Vector3 a, Vector3 b);",
+	],
+	Trig: [
+		"double Deg(double rad);",
+		"double Rad(double deg);",
+		"double DeltaAngle(double from, double to);",
+		"double AngleDiff(double from, double to);",
+		"double DeltaAngleDegrees(double from, double to);",
+		"double NormalizeAngle(double angle);",
+		"double Sin(double x);",
+		"double Cos(double x);",
+		"double Tan(double x);",
+		"double Asin(double x);",
+		"double Acos(double x);",
+		"double Atan2(double y, double x);",
+	],
+	Probability: [
+		"double RandomRange(double min, double max);",
+		"double Random(double min, double max);",
+		"int Weighted(LuaArray<double> weights);",
+		"double Gaussian();",
+		"double Gaussian(double mean, double std);",
+		"double Average(LuaArray<double> values);",
+		"double Sum(LuaArray<double> values);",
+	],
+	Noise: [
+		"double HashU32(double n);",
+		"double Value1(double x);",
+		"double Value2(double x, double y);",
+		"double Value3(double x, double y, double z);",
+	],
+	Color: [
+		"Color3 FromHSV(double h, double s, double v);",
+		"Color3 Contrast(Color3 color, double amount);",
+		"Color3 LerpHSV(Color3 a, Color3 b, double t);",
+	],
+};
+
+function axiomFnDecls(): Record<string, string[]> {
+	const byFn: Record<string, string[]> = {};
+	for (const decls of Object.values(AXIOM_GROUP_DECLS)) {
+		for (const decl of decls) {
+			const match = decl.match(/\b([A-Za-z_][A-Za-z0-9_]*)\s*\(/);
+			if (!match) {
+				continue;
+			}
+			const fn = match[1];
+			if (!byFn[fn]) {
+				byFn[fn] = [];
+			}
+			byFn[fn].push(decl);
+		}
+	}
+	return byFn;
+}
+
+const AXIOM_FN_DECLS = axiomFnDecls();
+
+function axiomHeaderBody(groups: string[], fns: string[], file: string, lineNo: number): string {
+	const decls: string[] = [];
+	const seen = new Set<string>();
+	const pushDecl = (decl: string) => {
+		if (seen.has(decl)) {
+			return;
+		}
+		seen.add(decl);
+		decls.push(`\t${decl}`);
+	};
+	for (const group of groups) {
+		const key = Object.keys(AXIOM_GROUP_DECLS).find((name) => name.toLowerCase() === group.toLowerCase());
+		if (!key) {
+			fail(
+				file,
+				lineNo,
+				`unknown group "${group}" — use Scalar Lerp Vector CFrame Easing Bezier Geometry Trig Probability Noise Color`,
+			);
+		}
+		decls.push(`\t// group ${key}`);
+		for (const decl of AXIOM_GROUP_DECLS[key]) {
+			pushDecl(decl);
+		}
+	}
+	for (const fn of fns) {
+		const key = Object.keys(AXIOM_FN_DECLS).find((name) => name.toLowerCase() === fn.toLowerCase());
+		if (!key) {
+			fail(file, lineNo, `unknown fn "${fn}" — use a name from axiom.clh (e.g. fn LerpVector2)`);
+		}
+		decls.push(`\t// fn ${key}`);
+		for (const decl of AXIOM_FN_DECLS[key]) {
+			pushDecl(decl);
+		}
+	}
+	return decls.join("\n");
+}
+
 function compileAxiom(source: string, file: string, defaultName: string): NativeEmit {
 	const { name, lines } = parseOptName(source, file, defaultName);
 	const groups: string[] = [];
+	const fns: string[] = [];
+	let lastLine = 1;
 	for (const tagged of lines) {
 		const [lineNoRaw, line] = tagged.split("\t");
 		const lineNo = Number(lineNoRaw);
-		const match = line.match(new RegExp(`^group\\s+(${IDENT})\\s*$`, "i"));
-		if (!match) {
-			fail(file, lineNo, `expected group Scalar`);
+		lastLine = lineNo;
+		const groupMatch = line.match(new RegExp(`^group\\s+(${IDENT})\\s*$`, "i"));
+		if (groupMatch) {
+			groups.push(groupMatch[1]);
+			continue;
+		}
+		const fnMatch = line.match(new RegExp(`^fn\\s+(${IDENT})\\s*$`, "i"));
+		if (fnMatch) {
+			fns.push(fnMatch[1]);
+			continue;
 		}
-		groups.push(match[1]);
+		fail(file, lineNo, `expected group Lerp or fn LerpVector2`);
 	}
-	if (groups.length === 0) {
-		fail(file, 1, "schema is empty — add group Scalar");
+	if (groups.length === 0 && fns.length === 0) {
+		fail(file, 1, "schema is empty — add group Lerp or fn LerpVector2");
 	}
+	const body = axiomHeaderBody(groups, fns, file, lastLine);
+	const selectArgs = [...groups, ...fns].map((item) => `"${item}"`).join(", ");
 	const { headerRel, luauRel } = emitPaths(file, name);
 	const header = `${headerBanner("axiom")}
 #include <clpp/libs/axiom.clh>
 namespace ${name} {
-${groups.map((group) => `\t// group ${group}`).join("\n")}
+${body}
 }
 `;
 	const luau = `${luauBanner()}local ReplicatedStorage = game:GetService("ReplicatedStorage")
 local Axiom = require(ReplicatedStorage.CluauppLibs.Axiom)
-local ${name} = Axiom.Select({ ${groups.map((group) => `"${group}"`).join(", ")} })
--- out/ only binds groups: ${groups.join(", ")}
+local ${name} = Axiom.Select({ ${selectArgs} })
+-- out/ binds: ${[...groups.map((g) => `group ${g}`), ...fns.map((f) => `fn ${f}`)].join(", ")}
 return ${name}
 `;
 	return { headerRel, headerPath: headerRel, header, luauRel, luau };

package/src/target/authority-check.ts

@@ -0,0 +1,162 @@
+/**
+ * Authority / architecture rules — import boundaries (CLUAU-AUTH*).
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { runContextFromFileName, type RunContext } from "./roblox.js";
+import { type PlatformDiagnostic, lineColAt, stripCommentsKeepStrings } from "./diagnostics.js";
+
+export interface ArchitectureRules {
+	clientCannotImport?: string[];
+	sharedCannotUse?: string[];
+	serverCannotImport?: string[];
+}
+
+export interface ComponentContract {
+	/** Instance path suffix or exact path, e.g. "Enemy" or "Workspace.Mobs.Enemy" */
+	path: string;
+	children: Record<string, string>; // name → expected className (or BasePart etc.)
+}
+
+export interface PlatformPolicy {
+	rules?: ArchitectureRules;
+	components?: ComponentContract[];
+}
+
+export function loadPlatformPolicy(projectRoot: string): PlatformPolicy {
+	const file = path.join(projectRoot, "cluaupp.config.json");
+	if (!fs.existsSync(file)) {
+		return defaultPolicy();
+	}
+	try {
+		const raw = JSON.parse(fs.readFileSync(file, "utf8")) as Record<string, unknown>;
+		const rules = (raw.rules as ArchitectureRules) || {};
+		const components = Array.isArray(raw.components) ? (raw.components as ComponentContract[]) : [];
+		return {
+			rules: { ...defaultPolicy().rules, ...rules },
+			components: components.length ? components : defaultPolicy().components,
+		};
+	} catch {
+		return defaultPolicy();
+	}
+}
+
+function defaultPolicy(): PlatformPolicy {
+	return {
+		rules: {
+			clientCannotImport: ["ServerScriptService", "ServerStorage"],
+			sharedCannotUse: ["DataStoreService", "MessagingService", "ServerStorage"],
+			serverCannotImport: [],
+		},
+		components: [],
+	};
+}
+
+const INCLUDE_RE = /#include\s*[<"]([^>"]+)[>"]/g;
+const IMPORT_RE = /\bimport\s*\{[^}]*\}\s*from\s*"([^"]+)"/g;
+const REQUIRE_RE = /require\s*\(\s*([^)]+)\)/g;
+const GET_SERVICE = /GetService\s*(?:<\s*([A-Za-z_]\w*)\s*>|\(\s*"([A-Za-z_]\w*)"\s*\))/g;
+
+export function checkAuthority(
+	source: string,
+	fileName: string,
+	policy: PlatformPolicy = defaultPolicy(),
+): PlatformDiagnostic[] {
+	const ctx = runContextFromFileName(fileName);
+	const clean = stripCommentsKeepStrings(source);
+	const out: PlatformDiagnostic[] = [];
+	const rules = policy.rules || {};
+
+	const bannedImports =
+		ctx === "Client"
+			? rules.clientCannotImport || []
+			: ctx === "Shared"
+				? []
+				: ctx === "Server"
+					? rules.serverCannotImport || []
+					: [];
+
+	const checkToken = (token: string, index: number, code: string, message: string) => {
+		const { line, column } = lineColAt(clean, index);
+		out.push({ code, message, line, column, severity: "error", file: fileName });
+	};
+
+	for (const banned of bannedImports) {
+		const re = new RegExp(`\\b${banned}\\b`);
+		INCLUDE_RE.lastIndex = 0;
+		let m: RegExpExecArray | null;
+		while ((m = INCLUDE_RE.exec(clean))) {
+			if (re.test(m[1])) {
+				checkToken(m[1], m.index, "CLUAU_AUTH001", `Architecture: ${ctx} must not import/include path involving ${banned}`);
+			}
+		}
+		IMPORT_RE.lastIndex = 0;
+		while ((m = IMPORT_RE.exec(clean))) {
+			if (re.test(m[1])) {
+				checkToken(m[1], m.index, "CLUAU_AUTH001", `Architecture: ${ctx} must not import path involving ${banned}`);
+			}
+		}
+		REQUIRE_RE.lastIndex = 0;
+		while ((m = REQUIRE_RE.exec(clean))) {
+			if (re.test(m[1])) {
+				checkToken(m[1], m.index, "CLUAU_AUTH001", `Architecture: ${ctx} must not require ${banned}`);
+			}
+		}
+		if (re.test(clean) && (clean.includes(`"${banned}`) || clean.includes(`'${banned}`) || clean.includes(`<${banned}`))) {
+			/* covered above */
+		}
+	}
+
+	if (ctx === "Shared" || ctx === "Client") {
+		const forbiddenServices = rules.sharedCannotUse || [];
+		GET_SERVICE.lastIndex = 0;
+		let m: RegExpExecArray | null;
+		while ((m = GET_SERVICE.exec(clean))) {
+			const svc = m[1] || m[2];
+			if (svc && forbiddenServices.includes(svc) && ctx === "Shared") {
+				const { line, column } = lineColAt(clean, m.index);
+				out.push({
+					code: "CLUAU_AUTH002",
+					message: `Architecture: Shared must not use ${svc}`,
+					line,
+					column,
+					severity: "error",
+					file: fileName,
+				});
+			}
+		}
+	}
+
+	// Client writing Keep/DataStore style authority smells
+	if (ctx === "Client") {
+		const smells = [
+			{ re: /\bDataStoreService\b/, msg: "Client must not touch DataStoreService" },
+			{ re: /Keep\.Server\.(Set|SetPersisted|Trade)/, msg: "Client must not mutate Keep.Server persistence APIs" },
+		];
+		for (const smell of smells) {
+			const m = smell.re.exec(clean);
+			if (m) {
+				const { line, column } = lineColAt(clean, m.index);
+				out.push({
+					code: "CLUAU_AUTH003",
+					message: smell.msg,
+					line,
+					column,
+					severity: "error",
+					file: fileName,
+				});
+			}
+		}
+	}
+
+	return out;
+}
+
+export function assertAuthoritySafe(source: string, fileName: string, policy?: PlatformPolicy): void {
+	const errors = checkAuthority(source, fileName, policy).filter((d) => d.severity === "error");
+	if (!errors.length) return;
+	throw new Error(`Authority:\n${errors.map((e) => `  ${e.line}:${e.column} ${e.code} ${e.message}`).join("\n")}`);
+}
+
+export type { RunContext };

package/src/target/authority-graph.ts

@@ -0,0 +1,80 @@
+/**
+ * Call-graph authority — transitive Client → banned Server paths via include graph.
+ * CLUAU_AUTH004 when a client/shared module reaches ServerScriptService/ServerStorage.
+ */
+
+import { buildProjectGraph, type ProjectGraph } from "./project-graph.js";
+import { runContextFromFileName } from "./roblox.js";
+import type { PlatformDiagnostic } from "./diagnostics.js";
+import { loadPlatformPolicy, type PlatformPolicy } from "./authority-check.js";
+
+function pathLooksBanned(rel: string, banned: string[]): boolean {
+	const norm = rel.replace(/\\/g, "/");
+	return banned.some((b) => norm.includes(b));
+}
+
+function reachable(graph: ProjectGraph, from: string): Set<string> {
+	const adj = new Map<string, string[]>();
+	for (const n of graph.nodes) adj.set(n, []);
+	for (const e of graph.edges) {
+		if (!adj.has(e.from)) adj.set(e.from, []);
+		adj.get(e.from)!.push(e.to);
+	}
+	const seen = new Set<string>();
+	const stack = [from];
+	while (stack.length) {
+		const n = stack.pop()!;
+		if (seen.has(n)) continue;
+		seen.add(n);
+		for (const to of adj.get(n) || []) {
+			if (!seen.has(to)) stack.push(to);
+		}
+	}
+	seen.delete(from);
+	return seen;
+}
+
+export function checkAuthorityGraph(
+	projectRoot: string,
+	rootDir = "src",
+	policy: PlatformPolicy = loadPlatformPolicy(projectRoot),
+): PlatformDiagnostic[] {
+	const graph = buildProjectGraph(projectRoot, rootDir);
+	const out: PlatformDiagnostic[] = [];
+	const clientBanned = policy.rules?.clientCannotImport || ["ServerScriptService", "ServerStorage"];
+
+	for (const node of graph.nodes) {
+		const ctx = runContextFromFileName(node);
+		if (ctx !== "Client" && ctx !== "Shared") continue;
+
+		const banned = ctx === "Client" ? clientBanned : ["ServerScriptService", "ServerStorage"];
+
+		if (pathLooksBanned(node, banned)) {
+			out.push({
+				code: "CLUAU_AUTH004",
+				message: `Architecture call-graph: ${ctx} file lives under banned path (${node})`,
+				line: 1,
+				column: 1,
+				severity: "error",
+				file: node,
+			});
+			continue;
+		}
+
+		for (const dep of reachable(graph, node)) {
+			if (pathLooksBanned(dep, banned)) {
+				out.push({
+					code: "CLUAU_AUTH004",
+					message: `Architecture call-graph: ${ctx} \`${node}\` transitively reaches banned \`${dep}\``,
+					line: 1,
+					column: 1,
+					severity: "error",
+					file: node,
+				});
+				break;
+			}
+		}
+	}
+
+	return out;
+}

package/src/target/build-cache.ts

@@ -0,0 +1,129 @@
+/**
+ * Incremental compile cache + bounded parallel job runner.
+ * Cache lives under `.cluaupp/compile-cache/` (gitignored via `.cluaupp/`).
+ */
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const COMPILE_CACHE_SCHEMA = 1 as const;
+
+export interface CachedArtifact {
+	name: string;
+	contents: string;
+}
+
+export interface CachedJob {
+	rel: string;
+	sourceHash: string;
+	files: CachedArtifact[];
+	stale: string[];
+}
+
+export interface CompileCacheIndex {
+	schemaVersion: typeof COMPILE_CACHE_SCHEMA;
+	/** rel → sourceHash */
+	entries: Record<string, string>;
+}
+
+export function compileCacheDir(projectRoot: string): string {
+	return path.join(projectRoot, ".cluaupp", "compile-cache");
+}
+
+export function hashText(text: string): string {
+	return crypto.createHash("sha256").update(text, "utf8").digest("hex");
+}
+
+export function fingerprintSource(source: string, configKey: string): string {
+	return hashText(`${configKey}\n${source}`);
+}
+
+function indexPath(projectRoot: string): string {
+	return path.join(compileCacheDir(projectRoot), "index.json");
+}
+
+function jobPath(projectRoot: string, rel: string): string {
+	const safe = rel.replace(/[\\/]/g, "__");
+	return path.join(compileCacheDir(projectRoot), `${safe}.json`);
+}
+
+export function loadCompileCacheIndex(projectRoot: string): CompileCacheIndex {
+	const file = indexPath(projectRoot);
+	if (!fs.existsSync(file)) {
+		return { schemaVersion: COMPILE_CACHE_SCHEMA, entries: {} };
+	}
+	try {
+		const raw = JSON.parse(fs.readFileSync(file, "utf8")) as CompileCacheIndex;
+		if (!raw || typeof raw.entries !== "object") {
+			return { schemaVersion: COMPILE_CACHE_SCHEMA, entries: {} };
+		}
+		return { schemaVersion: COMPILE_CACHE_SCHEMA, entries: raw.entries };
+	} catch {
+		return { schemaVersion: COMPILE_CACHE_SCHEMA, entries: {} };
+	}
+}
+
+export function saveCompileCacheIndex(projectRoot: string, index: CompileCacheIndex): void {
+	const dir = compileCacheDir(projectRoot);
+	fs.mkdirSync(dir, { recursive: true });
+	fs.writeFileSync(indexPath(projectRoot), JSON.stringify(index, null, "\t") + "\n", "utf8");
+}
+
+export function readCachedJob(projectRoot: string, rel: string, sourceHash: string): CachedJob | null {
+	const index = loadCompileCacheIndex(projectRoot);
+	if (index.entries[rel] !== sourceHash) {
+		return null;
+	}
+	const file = jobPath(projectRoot, rel);
+	if (!fs.existsSync(file)) {
+		return null;
+	}
+	try {
+		const job = JSON.parse(fs.readFileSync(file, "utf8")) as CachedJob;
+		if (!job || job.sourceHash !== sourceHash || !Array.isArray(job.files)) {
+			return null;
+		}
+		return job;
+	} catch {
+		return null;
+	}
+}
+
+export function writeCachedJob(projectRoot: string, job: CachedJob): void {
+	const dir = compileCacheDir(projectRoot);
+	fs.mkdirSync(dir, { recursive: true });
+	fs.writeFileSync(jobPath(projectRoot, job.rel), JSON.stringify(job) + "\n", "utf8");
+	const index = loadCompileCacheIndex(projectRoot);
+	index.entries[job.rel] = job.sourceHash;
+	saveCompileCacheIndex(projectRoot, index);
+}
+
+/** Bounded concurrency over async work items. */
+export async function mapPool<T, R>(
+	items: T[],
+	concurrency: number,
+	fn: (item: T, index: number) => Promise<R>,
+): Promise<R[]> {
+	const limit = Math.max(1, Math.min(concurrency, items.length || 1));
+	const results = new Array<R>(items.length);
+	let next = 0;
+	async function worker(): Promise<void> {
+		while (true) {
+			const i = next++;
+			if (i >= items.length) return;
+			results[i] = await fn(items[i], i);
+		}
+	}
+	await Promise.all(Array.from({ length: limit }, () => worker()));
+	return results;
+}
+
+export function defaultJobCount(): number {
+	const env = Number(process.env.CLUAUPP_JOBS || process.env.CLPP_JOBS || "");
+	if (Number.isFinite(env) && env > 0) {
+		return Math.floor(env);
+	}
+	return Math.max(1, Math.min(8, os.cpus()?.length || 4));
+}