cluaupp 1.5.0 → 1.5.2-cf

package/src/target/parallel-check.ts

@@ -0,0 +1,135 @@
+/**
+ * Parallel Luau / ThreadSafety diagnostics (CLUAU-PAR*).
+ * Flags Unsafe mutations inside parallel { } / desynchronize regions.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { projectRoot } from "../package-info.js";
+import type { RobloxTargetProfile, ThreadSafety } from "../api/model.js";
+import { type PlatformDiagnostic, lineColAt, stripCommentsKeepStrings } from "./diagnostics.js";
+
+let cachedUnsafeMembers: Set<string> | null = null;
+
+function loadUnsafeMemberNames(): Set<string> {
+	if (cachedUnsafeMembers) {
+		return cachedUnsafeMembers;
+	}
+	const set = new Set<string>(["Parent", "Name"]); // Parent writes always unsafe in parallel
+	const profilePath = path.join(projectRoot, "api", "normalized", "roblox-target.profile.json");
+	if (fs.existsSync(profilePath)) {
+		try {
+			const profile = JSON.parse(fs.readFileSync(profilePath, "utf8")) as RobloxTargetProfile;
+			for (const cls of Object.values(profile.classes || {})) {
+				for (const prop of Object.values(cls.properties || {})) {
+					if (prop.threadSafety === "Unsafe") {
+						set.add(prop.name);
+					}
+				}
+				for (const method of Object.values(cls.methods || {})) {
+					if (method.threadSafety === "Unsafe") {
+						set.add(method.name);
+					}
+				}
+			}
+		} catch {
+			/* fallback set only */
+		}
+	}
+	cachedUnsafeMembers = set;
+	return set;
+}
+
+function extractParallelRegions(source: string): Array<{ start: number; body: string }> {
+	const regions: Array<{ start: number; body: string }> = [];
+	const reParallel = /\bparallel\s*\{/g;
+	let m: RegExpExecArray | null;
+	while ((m = reParallel.exec(source))) {
+		const open = m.index + m[0].length - 1;
+		let depth = 0;
+		for (let i = open; i < source.length; i++) {
+			if (source[i] === "{") depth++;
+			else if (source[i] === "}") {
+				depth--;
+				if (depth === 0) {
+					regions.push({ start: m.index, body: source.slice(open + 1, i) });
+					break;
+				}
+			}
+		}
+	}
+	const reDesync = /task\s*::\s*desynchronize\s*\(\s*\)/g;
+	while ((m = reDesync.exec(source))) {
+		const rest = source.slice(m.index);
+		const sync = rest.search(/task\s*::\s*synchronize\s*\(\s*\)/);
+		const body = sync >= 0 ? rest.slice(0, sync) : rest.slice(0, Math.min(rest.length, 800));
+		regions.push({ start: m.index, body });
+	}
+	if (/\bConnectParallel\b/.test(source)) {
+		regions.push({ start: source.indexOf("ConnectParallel"), body: source });
+	}
+	return regions;
+}
+
+export function checkParallelSafety(source: string, fileName = "input.clpp"): PlatformDiagnostic[] {
+	const clean = stripCommentsKeepStrings(source);
+	const unsafe = loadUnsafeMemberNames();
+	const out: PlatformDiagnostic[] = [];
+	const regions = extractParallelRegions(clean);
+	if (!regions.length) {
+		return out;
+	}
+	for (const region of regions) {
+		const parentAssign = /\.Parent\s*=/g;
+		let pm: RegExpExecArray | null;
+		while ((pm = parentAssign.exec(region.body))) {
+			const { line, column } = lineColAt(clean, region.start + pm.index);
+			out.push({
+				code: "CLUAU_PAR001",
+				message: "Unsafe Instance write `.Parent =` inside parallel / desynchronized region",
+				line,
+				column,
+				severity: "error",
+				file: fileName,
+			});
+		}
+		const memberWrite = /\.([A-Za-z_]\w*)\s*=/g;
+		while ((pm = memberWrite.exec(region.body))) {
+			const name = pm[1];
+			if (name === "Parent") continue;
+			if (!unsafe.has(name)) continue;
+			const { line, column } = lineColAt(clean, region.start + pm.index);
+			out.push({
+				code: "CLUAU_PAR002",
+				message: `API member \`.${name}\` is ThreadSafety=Unsafe inside parallel region`,
+				line,
+				column,
+				severity: "error",
+				file: fileName,
+			});
+		}
+		const destroy = /\.Destroy\s*\(/g;
+		while ((pm = destroy.exec(region.body))) {
+			const { line, column } = lineColAt(clean, region.start + pm.index);
+			out.push({
+				code: "CLUAU_PAR003",
+				message: "`Destroy()` is Unsafe inside parallel region",
+				line,
+				column,
+				severity: "error",
+				file: fileName,
+			});
+		}
+	}
+	return out;
+}
+
+export function assertParallelSafe(source: string, fileName?: string): void {
+	const errors = checkParallelSafety(source, fileName).filter((d) => d.severity === "error");
+	if (!errors.length) return;
+	throw new Error(
+		`Parallel safety:\n${errors.map((e) => `  ${e.line}:${e.column} ${e.code} ${e.message}`).join("\n")}`,
+	);
+}
+
+export type { ThreadSafety };

package/src/target/pgo.ts

@@ -0,0 +1,157 @@
+/**
+ * Profile-Guided Optimization (PGO) — format, load, Studio ingest.
+ * cluaupp.profile.json weights optimizer advice toward hot symbols.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import type { OptimizeAdvice } from "./optimizer-advise.js";
+
+export const PGO_SCHEMA_VERSION = 1 as const;
+
+export interface CluauppProfile {
+	schemaVersion: typeof PGO_SCHEMA_VERSION;
+	generatedAt?: string;
+	/** Symbol / function name → call counts (or relative weight). */
+	hot: Record<string, number>;
+	/** Optional struct names observed as hot. */
+	structs?: Record<string, number>;
+}
+
+/** One Studio / playtest hit — JSONL or JSON array. */
+export interface ProfileEvent {
+	symbol: string;
+	kind?: "hot" | "struct";
+	count?: number;
+}
+
+export function defaultProfilePath(projectRoot: string): string {
+	return path.join(projectRoot, "cluaupp.profile.json");
+}
+
+export function loadProfile(file: string): CluauppProfile | null {
+	if (!fs.existsSync(file)) {
+		return null;
+	}
+	try {
+		const raw = JSON.parse(fs.readFileSync(file, "utf8")) as CluauppProfile;
+		if (!raw || typeof raw.hot !== "object") {
+			return null;
+		}
+		return { schemaVersion: PGO_SCHEMA_VERSION, hot: raw.hot, structs: raw.structs, generatedAt: raw.generatedAt };
+	} catch {
+		return null;
+	}
+}
+
+/** Write an empty / template profile for games to fill from Studio logging. */
+export function writeProfileTemplate(projectRoot: string): string {
+	const file = defaultProfilePath(projectRoot);
+	const template: CluauppProfile = {
+		schemaVersion: PGO_SCHEMA_VERSION,
+		generatedAt: new Date().toISOString(),
+		hot: {
+			CalculateDamage: 0,
+			EnemyUpdate: 0,
+		},
+		structs: {
+			EnemyState: 0,
+		},
+	};
+	fs.writeFileSync(file, JSON.stringify(template, null, "\t") + "\n", "utf8");
+	return file;
+}
+
+function parseEvents(raw: string): ProfileEvent[] {
+	const trimmed = raw.trim();
+	if (!trimmed) return [];
+	if (trimmed.startsWith("[")) {
+		const arr = JSON.parse(trimmed) as unknown;
+		if (!Array.isArray(arr)) return [];
+		return arr.filter((e) => e && typeof (e as ProfileEvent).symbol === "string") as ProfileEvent[];
+	}
+	if (trimmed.startsWith("{") && !trimmed.includes("\n")) {
+		const one = JSON.parse(trimmed) as Record<string, unknown>;
+		if (typeof one.symbol === "string") {
+			return [one as unknown as ProfileEvent];
+		}
+		if (one.hot && typeof one.hot === "object") {
+			return Object.entries(one.hot as Record<string, number>).map(([symbol, count]) => ({
+				symbol,
+				kind: "hot" as const,
+				count: Number(count) || 0,
+			}));
+		}
+	}
+	const events: ProfileEvent[] = [];
+	for (const line of trimmed.split(/\r?\n/)) {
+		const t = line.trim();
+		if (!t || t.startsWith("#")) continue;
+		try {
+			const e = JSON.parse(t) as ProfileEvent;
+			if (e && typeof e.symbol === "string") events.push(e);
+		} catch {
+			/* skip bad line */
+		}
+	}
+	return events;
+}
+
+/** Merge Studio/playtest events into cluaupp.profile.json (additive counts). */
+export function ingestProfile(
+	projectRoot: string,
+	eventsPath: string,
+): { profilePath: string; profile: CluauppProfile; merged: number } {
+	const eventsFile = path.resolve(eventsPath);
+	if (!fs.existsSync(eventsFile)) {
+		throw new Error(`cluaupp profile ingest: missing ${eventsFile}`);
+	}
+	const events = parseEvents(fs.readFileSync(eventsFile, "utf8"));
+	const profilePath = defaultProfilePath(projectRoot);
+	const existing = loadProfile(profilePath) || {
+		schemaVersion: PGO_SCHEMA_VERSION,
+		hot: {},
+		structs: {},
+	};
+	const hot = { ...(existing.hot || {}) };
+	const structs = { ...(existing.structs || {}) };
+	let merged = 0;
+	for (const e of events) {
+		const n = typeof e.count === "number" && Number.isFinite(e.count) ? e.count : 1;
+		if (e.kind === "struct") {
+			structs[e.symbol] = (structs[e.symbol] || 0) + n;
+		} else {
+			hot[e.symbol] = (hot[e.symbol] || 0) + n;
+		}
+		merged++;
+	}
+	const profile: CluauppProfile = {
+		schemaVersion: PGO_SCHEMA_VERSION,
+		generatedAt: new Date().toISOString(),
+		hot,
+		structs,
+	};
+	fs.writeFileSync(profilePath, JSON.stringify(profile, null, "\t") + "\n", "utf8");
+	return { profilePath, profile, merged };
+}
+
+export function rankAdvice(advice: OptimizeAdvice[], profile: CluauppProfile | null): OptimizeAdvice[] {
+	if (!profile) {
+		return advice;
+	}
+	return [...advice]
+		.sort((a, b) => {
+			const wa = profile.hot[a.target] || profile.structs?.[a.target] || 0;
+			const wb = profile.hot[b.target] || profile.structs?.[b.target] || 0;
+			return wb - wa;
+		})
+		.map((a) => {
+			const w = profile.hot[a.target] || profile.structs?.[a.target];
+			if (!w) return a;
+			return {
+				...a,
+				message: `${a.message} [PGO weight=${w}]`,
+				severity: w > 1000 ? "warning" : a.severity,
+			};
+		});
+}

package/src/target/project-docs.ts

@@ -0,0 +1,68 @@
+/**
+ * Generate project documentation from DataModel + graph + Flare + advice.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { buildDatamodelProfile } from "./datamodel.js";
+import { buildProjectGraph } from "./project-graph.js";
+import { checkFlareVersions } from "./flare-version.js";
+import { collectSources } from "../clpp/paths.js";
+import { adviseOptimizer } from "./optimizer-advise.js";
+
+export function generateProjectDocs(projectRoot: string, rootDir = "src"): { outPath: string; markdown: string } {
+	const dm = buildDatamodelProfile(projectRoot);
+	const graph = buildProjectGraph(projectRoot, rootDir);
+	const flare = checkFlareVersions(projectRoot, rootDir);
+	const srcDir = path.join(projectRoot, rootDir);
+	const files = fs.existsSync(srcDir) ? collectSources(srcDir) : [];
+	const advice: string[] = [];
+	for (const file of files) {
+		const rel = path.relative(projectRoot, file).replace(/\\/g, "/");
+		for (const a of adviseOptimizer(fs.readFileSync(file, "utf8"), rel)) {
+			advice.push(`- **${a.target}** (${a.kind}): ${a.message}`);
+		}
+	}
+
+	const paths = dm
+		? Object.keys(dm.byPath)
+				.filter((p) => p !== "DataModel")
+				.sort()
+				.map((p) => `- \`${p}\` — ${dm.byPath[p].className}`)
+				.join("\n")
+		: "_no default.project.json_";
+
+	const markdown = [
+		`# Cluaupp project docs`,
+		``,
+		`Generated: ${new Date().toISOString()}`,
+		``,
+		`## DataModel`,
+		``,
+		paths,
+		``,
+		`## Modules (${graph.nodes.length})`,
+		``,
+		graph.nodes.map((n) => `- \`${n}\``).join("\n") || "_none_",
+		``,
+		`## Dependencies`,
+		``,
+		graph.edges.map((e) => `- \`${e.from}\` → \`${e.to}\``).join("\n") || "_none_",
+		``,
+		graph.cycles.length ? `### Cycles\n\n${graph.cycles.map((c) => `- ${c.join(" → ")}`).join("\n")}\n` : "",
+		`## Flare contracts`,
+		``,
+		flare.files.map((f) => `- \`${f.file}\` name=\`${f.name}\` version=${f.version ?? "unset"}`).join("\n") || "_none_",
+		``,
+		`## Optimizer advice`,
+		``,
+		advice.slice(0, 40).join("\n") || "_none_",
+		``,
+	].join("\n");
+
+	const outDir = path.join(projectRoot, ".cluaupp");
+	fs.mkdirSync(outDir, { recursive: true });
+	const outPath = path.join(outDir, "PROJECT.md");
+	fs.writeFileSync(outPath, markdown, "utf8");
+	return { outPath, markdown };
+}

package/src/target/project-graph.ts

@@ -0,0 +1,75 @@
+/** Project include/import/require graph + circular dependency detection. */
+import fs from "node:fs";
+import path from "node:path";
+import { collectLanguageModulePaths, resolveModuleFile } from "../clpp/modules.js";
+import { collectSources } from "../clpp/paths.js";
+
+export interface GraphEdge {
+	from: string;
+	to: string;
+}
+
+export interface ProjectGraph {
+	nodes: string[];
+	edges: GraphEdge[];
+	cycles: string[][];
+}
+
+function findCycles(nodes: string[], edges: GraphEdge[]): string[][] {
+	const adj = new Map<string, string[]>();
+	for (const n of nodes) adj.set(n, []);
+	for (const e of edges) {
+		if (!adj.has(e.from)) adj.set(e.from, []);
+		adj.get(e.from)!.push(e.to);
+	}
+	const cycles: string[][] = [];
+	const visiting = new Set<string>();
+	const visited = new Set<string>();
+	const stack: string[] = [];
+
+	function dfs(n: string) {
+		if (visiting.has(n)) {
+			const i = stack.indexOf(n);
+			if (i >= 0) cycles.push(stack.slice(i).concat(n));
+			return;
+		}
+		if (visited.has(n)) return;
+		visiting.add(n);
+		stack.push(n);
+		for (const to of adj.get(n) || []) dfs(to);
+		stack.pop();
+		visiting.delete(n);
+		visited.add(n);
+	}
+	for (const n of nodes) dfs(n);
+	return cycles;
+}
+
+export function buildProjectGraph(projectRoot: string, rootDir = "src"): ProjectGraph {
+	const srcDir = path.join(projectRoot, rootDir);
+	const files = fs.existsSync(srcDir) ? collectSources(srcDir) : [];
+	const nodes: string[] = [];
+	const edges: GraphEdge[] = [];
+	const byAbs = new Map<string, string>();
+
+	for (const file of files) {
+		const rel = path.relative(projectRoot, file).replace(/\\/g, "/");
+		nodes.push(rel);
+		byAbs.set(path.resolve(file), rel);
+	}
+
+	for (const file of files) {
+		const rel = path.relative(projectRoot, file).replace(/\\/g, "/");
+		const source = fs.readFileSync(file, "utf8");
+		for (const mod of collectLanguageModulePaths(source)) {
+			const resolved = resolveModuleFile(mod, file, srcDir);
+			if (!resolved) continue;
+			const hit = byAbs.get(path.resolve(resolved));
+			if (hit && hit !== rel) {
+				edges.push({ from: rel, to: hit });
+			}
+		}
+	}
+
+	return { nodes, edges, cycles: findCycles(nodes, edges) };
+}

package/src/target/roblox.ts

@@ -0,0 +1,78 @@
+import type { RobloxTargetProfile } from "../api/model.js";
+import { ROBLOX_TARGET_SCHEMA_VERSION } from "../api/model.js";
+import { buildRobloxTargetProfile } from "../api/build-profile.js";
+
+/** Cluaupp-owned run contexts — never push these into CLPP core. */
+export type RunContext = "Server" | "Client" | "Plugin" | "Shared";
+
+export const FILE_TAG_TO_CONTEXT: Record<string, RunContext> = {
+	".server": "Server",
+	".client": "Client",
+	".plugin": "Plugin",
+};
+
+export function runContextFromFileName(fileName: string): RunContext {
+	const lower = fileName.toLowerCase();
+	if (lower.includes(".server.")) {
+		return "Server";
+	}
+	if (lower.includes(".client.")) {
+		return "Client";
+	}
+	if (lower.includes(".plugin.")) {
+		return "Plugin";
+	}
+	return "Shared";
+}
+
+export interface RobloxProjectModel {
+	kind: "roblox";
+	rojoProjectPath?: string;
+	libsFolderName: "CluauppLibs";
+	/** Historical CLPP postprocess name — remapped in Cluaupp only. */
+	legacyLibsAlias: "ClppLibs";
+}
+
+export function defaultRobloxProject(): RobloxProjectModel {
+	return {
+		kind: "roblox",
+		libsFolderName: "CluauppLibs",
+		legacyLibsAlias: "ClppLibs",
+	};
+}
+
+/**
+ * Target-side GetService\<T\> — **Cluaupp Roblox Target feature**, not a CL++ language rule.
+ * CL++ only provides generic-call syntax (`GetService<Players>()`); Cluaupp maps T via the
+ * Canonical Registry, Context Safety, and headers under `#include <clpp/roblox.clh>`.
+ */
+export function resolveGetServiceType(typeName: string, profile?: RobloxTargetProfile): string | null {
+	const p = profile || buildRobloxTargetProfile({ skipValidate: true });
+	if (p.services[typeName]) {
+		return typeName;
+	}
+	if (p.classes[typeName]?.service || p.classes[typeName]?.creation.service) {
+		return typeName;
+	}
+	return null;
+}
+
+/** True when `name` is a registered Roblox service class. */
+export function isRegisteredService(name: string, profile?: RobloxTargetProfile): boolean {
+	return resolveGetServiceType(name, profile) != null;
+}
+
+export function targetProfileSummary(): {
+	schemaVersion: number;
+	target: "roblox";
+	classes: number;
+	services: number;
+} {
+	const profile = buildRobloxTargetProfile({ skipValidate: true });
+	return {
+		schemaVersion: ROBLOX_TARGET_SCHEMA_VERSION,
+		target: "roblox",
+		classes: Object.keys(profile.classes).length,
+		services: Object.keys(profile.services).length,
+	};
+}

package/src/target/security-check.ts

@@ -0,0 +1,40 @@
+/** Static security patterns (CLUAU-SEC*) — not a runtime anti-cheat. */
+import { runContextFromFileName } from "./roblox.js";
+import { type PlatformDiagnostic, lineColAt, stripCommentsKeepStrings } from "./diagnostics.js";
+
+const CLIENT_PATTERNS: Array<{ code: string; re: RegExp; message: string }> = [
+	{ code: "CLUAU_SEC001", re: /\bCoins\s*=/, message: "Client appears to assign Coins — server must own currency" },
+	{ code: "CLUAU_SEC002", re: /\bDamage\s*=\s*[^=]/, message: "Client appears to set Damage — prefer server authority" },
+	{ code: "CLUAU_SEC003", re: /FireServer\s*\([^)]*Instance/, message: "Remote may accept unrestricted Instance from client" },
+	{ code: "CLUAU_SEC004", re: /Inventory.*=.*FireServer|FireServer.*Inventory/, message: "Client-supplied inventory result smell" },
+];
+
+const SERVER_PATTERNS: Array<{ code: string; re: RegExp; message: string }> = [
+	{ code: "CLUAU_SEC010", re: /FireServer/, message: "Server calling FireServer is inverted authority" },
+	{
+		code: "CLUAU_SEC011",
+		re: /\.Position\b[^\n]*player|player[^\n]*\.Position/,
+		message: "Server may be trusting client Position — validate or ignore client transform",
+	},
+];
+
+export function checkSecurity(source: string, fileName: string): PlatformDiagnostic[] {
+	const ctx = runContextFromFileName(fileName);
+	const clean = stripCommentsKeepStrings(source);
+	const out: PlatformDiagnostic[] = [];
+	const list = ctx === "Client" ? CLIENT_PATTERNS : ctx === "Server" ? SERVER_PATTERNS : [];
+	for (const p of list) {
+		const m = p.re.exec(clean);
+		if (!m) continue;
+		const { line, column } = lineColAt(clean, m.index);
+		out.push({
+			code: p.code,
+			message: p.message,
+			line,
+			column,
+			severity: "warning",
+			file: fileName,
+		});
+	}
+	return out;
+}

package/src/target/source-map.ts

@@ -0,0 +1,36 @@
+/** Minimal source map: CL++ path ↔ emitted Luau (1:1 file mapping for v1). */
+import fs from "node:fs";
+import path from "node:path";
+
+export interface CluauppSourceMap {
+	version: 1;
+	file: string;
+	sourceRoot: string;
+	sources: string[];
+	mappings: string;
+	cluaupp: {
+		source: string;
+		generated: string;
+	};
+}
+
+export function writeSourceMap(opts: {
+	outLuauPath: string;
+	sourceClppRel: string;
+	projectRoot: string;
+}): string {
+	const map: CluauppSourceMap = {
+		version: 1,
+		file: path.basename(opts.outLuauPath),
+		sourceRoot: opts.projectRoot.replace(/\\/g, "/"),
+		sources: [opts.sourceClppRel.replace(/\\/g, "/")],
+		mappings: "AAAA", // identity stub — refine when clpp emits VLQ maps
+		cluaupp: {
+			source: opts.sourceClppRel.replace(/\\/g, "/"),
+			generated: path.relative(opts.projectRoot, opts.outLuauPath).replace(/\\/g, "/"),
+		},
+	};
+	const mapPath = opts.outLuauPath + ".map.json";
+	fs.writeFileSync(mapPath, JSON.stringify(map, null, "\t") + "\n", "utf8");
+	return mapPath;
+}