cluaupp 1.4.1 → 1.5.1

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));
+}

package/src/target/capabilities.ts

@@ -0,0 +1,115 @@
+/**
+ * Context Safety — capability profile for CL++ compile (Cluaupp target).
+ * CLPP may consume this JSON later; Cluaupp enforces rules today.
+ */
+
+import type { RunContext } from "./roblox.js";
+
+export const CAPABILITY_PROFILE_SCHEMA_VERSION = 1 as const;
+
+export type CapabilityId =
+	| "client_player"
+	| "server_storage"
+	| "data_stores"
+	| "messaging"
+	| "fire_server"
+	| "fire_client";
+
+export interface CapabilityRule {
+	id: string;
+	/** Human message for diagnostics */
+	message: string;
+	/** Regex source matched against comment-stripped CL++ lines */
+	pattern: string;
+	/** Contexts where this pattern is illegal */
+	forbiddenIn: RunContext[];
+	severity: "error" | "warning";
+	capability?: CapabilityId;
+}
+
+export interface CapabilityProfile {
+	schemaVersion: typeof CAPABILITY_PROFILE_SCHEMA_VERSION;
+	target: "roblox";
+	rules: CapabilityRule[];
+}
+
+/** Builtin Roblox platform capability rules (v1). */
+export function builtinCapabilityProfile(): CapabilityProfile {
+	return {
+		schemaVersion: CAPABILITY_PROFILE_SCHEMA_VERSION,
+		target: "roblox",
+		rules: [
+			{
+				id: "CLUAUPP_CTX_LOCALPLAYER",
+				message: "`LocalPlayer` is client-only — illegal in Server scripts",
+				pattern: String.raw`\bLocalPlayer\b`,
+				forbiddenIn: ["Server"],
+				severity: "error",
+				capability: "client_player",
+			},
+			{
+				id: "CLUAUPP_CTX_LOCALPLAYER_SHARED",
+				message: "`LocalPlayer` in Shared modules is unsafe if required from the server — prefer Client scripts",
+				pattern: String.raw`\bLocalPlayer\b`,
+				forbiddenIn: ["Shared"],
+				severity: "warning",
+				capability: "client_player",
+			},
+			{
+				id: "CLUAUPP_CTX_DATASTORE",
+				message: "`DataStoreService` is server-only — illegal in Client scripts",
+				pattern: String.raw`\bDataStoreService\b|GetService\s*<\s*DataStoreService\s*>|GetService\s*\(\s*["']DataStoreService["']\s*\)`,
+				forbiddenIn: ["Client"],
+				severity: "error",
+				capability: "data_stores",
+			},
+			{
+				id: "CLUAUPP_CTX_MESSAGING",
+				message: "`MessagingService` is server-only — illegal in Client scripts",
+				pattern: String.raw`\bMessagingService\b|GetService\s*<\s*MessagingService\s*>`,
+				forbiddenIn: ["Client"],
+				severity: "error",
+				capability: "messaging",
+			},
+			{
+				id: "CLUAUPP_CTX_SERVERSTORAGE",
+				message: "`ServerStorage` is server-only — illegal in Client scripts",
+				pattern: String.raw`\bServerStorage\b|GetService\s*<\s*ServerStorage\s*>`,
+				forbiddenIn: ["Client"],
+				severity: "error",
+				capability: "server_storage",
+			},
+			{
+				id: "CLUAUPP_CTX_FIRE_SERVER",
+				message: "`FireServer` is client→server — illegal in Server scripts",
+				pattern: String.raw`\bFireServer\b`,
+				forbiddenIn: ["Server"],
+				severity: "error",
+				capability: "fire_server",
+			},
+			{
+				id: "CLUAUPP_CTX_FIRE_CLIENT",
+				message: "`FireClient` / `FireAllClients` are server→client — illegal in Client scripts",
+				pattern: String.raw`\bFireAllClients\b|\bFireClient\b`,
+				forbiddenIn: ["Client"],
+				severity: "error",
+				capability: "fire_client",
+			},
+		],
+	};
+}
+
+export function capabilitiesForContext(context: RunContext): CapabilityId[] {
+	switch (context) {
+		case "Client":
+			return ["client_player", "fire_server"];
+		case "Server":
+			return ["server_storage", "data_stores", "messaging", "fire_client"];
+		case "Plugin":
+			return ["client_player", "server_storage", "data_stores", "messaging", "fire_server", "fire_client"];
+		case "Shared":
+			return [];
+		default:
+			return [];
+	}
+}

package/src/target/capability-profile.ts

@@ -0,0 +1,25 @@
+import fs from "node:fs";
+import path from "node:path";
+import { projectRoot } from "../package-info.js";
+import { builtinCapabilityProfile, type CapabilityProfile } from "./capabilities.js";
+
+export function capabilityProfilePath(): string {
+	return path.join(projectRoot, "api", "generated", "capability-profile.json");
+}
+
+export function writeCapabilityProfile(profile: CapabilityProfile = builtinCapabilityProfile()): string {
+	const out = capabilityProfilePath();
+	fs.mkdirSync(path.dirname(out), { recursive: true });
+	const tmp = `${out}.${process.pid}.tmp`;
+	fs.writeFileSync(tmp, `${JSON.stringify(profile, null, "\t")}\n`, "utf8");
+	fs.renameSync(tmp, out);
+	return out;
+}
+
+export function loadCapabilityProfile(): CapabilityProfile {
+	const file = capabilityProfilePath();
+	if (!fs.existsSync(file)) {
+		return builtinCapabilityProfile();
+	}
+	return JSON.parse(fs.readFileSync(file, "utf8")) as CapabilityProfile;
+}

package/src/target/component-contracts.ts

@@ -0,0 +1,64 @@
+/**
+ * DataModel component contracts — validate expected children/classNames on graph nodes.
+ */
+
+import type { DatamodelProfile } from "./datamodel.js";
+import type { ComponentContract } from "./authority-check.js";
+import type { PlatformDiagnostic } from "./diagnostics.js";
+
+function isA(actual: string, expected: string): boolean {
+	if (actual === expected) return true;
+	// soft hierarchy aliases for v1
+	const basePart = new Set(["Part", "MeshPart", "UnionOperation", "BasePart", "SpawnLocation", "WedgePart", "CornerWedgePart", "TrussPart"]);
+	if (expected === "BasePart" && basePart.has(actual)) return true;
+	if (expected === "Instance") return true;
+	if (expected === "Folder" && (actual === "Folder" || actual === "Configuration")) return true;
+	return false;
+}
+
+export function checkComponentContracts(
+	profile: DatamodelProfile,
+	contracts: ComponentContract[],
+): PlatformDiagnostic[] {
+	const out: PlatformDiagnostic[] = [];
+	for (const contract of contracts) {
+		const matches = Object.values(profile.byPath).filter(
+			(n) => n.name === contract.path || n.path === contract.path || n.path.endsWith(`.${contract.path}`),
+		);
+		if (!matches.length) {
+			out.push({
+				code: "CLUAU_DM_CONTRACT_MISSING",
+				message: `Component contract "${contract.path}" — no matching Instance in Rojo DataModel graph`,
+				line: 1,
+				column: 1,
+				severity: "warning",
+			});
+			continue;
+		}
+		for (const node of matches) {
+			for (const [childName, expectedClass] of Object.entries(contract.children)) {
+				const child = node.children[childName];
+				if (!child) {
+					out.push({
+						code: "CLUAU_DM_CONTRACT_CHILD",
+						message: `Component ${node.path}: missing child "${childName}" (expected ${expectedClass})`,
+						line: 1,
+						column: 1,
+						severity: "error",
+					});
+					continue;
+				}
+				if (!isA(child.className, expectedClass)) {
+					out.push({
+						code: "CLUAU_DM_CONTRACT_TYPE",
+						message: `Component ${node.path}.${childName}: expected ${expectedClass}, got ${child.className}`,
+						line: 1,
+						column: 1,
+						severity: "error",
+					});
+				}
+			}
+		}
+	}
+	return out;
+}