cluaupp 1.5.0 → 1.5.1

package/src/target/luau-stamp.ts

@@ -0,0 +1,33 @@
+/**
+ * Stamp emitted Luau with CL++ provenance and --!native when source used #pragma native.
+ */
+
+export function stampLuauFromClpp(luau: string, sourceRel: string, clppSource?: string): string {
+	let next = String(luau);
+	const stamp = `-- cluaupp-source: ${sourceRel.replace(/\\/g, "/")}`;
+	if (!next.includes("cluaupp-source:")) {
+		if (/^--!/.test(next.trimStart())) {
+			const lines = next.split(/\r?\n/);
+			let i = 0;
+			while (i < lines.length && /^--!/.test(lines[i])) i++;
+			lines.splice(i, 0, stamp);
+			next = lines.join("\n");
+		} else if (next.startsWith("--")) {
+			next = `${stamp}\n${next}`;
+		} else {
+			next = `${stamp}\n${next}`;
+		}
+	}
+
+	const wantsNative = Boolean(clppSource && /#pragma\s+native\b/.test(clppSource));
+	if (wantsNative && !/--!native\b/.test(next)) {
+		if (/^\s*--!strict\b/m.test(next)) {
+			next = next.replace(/^\s*--!strict\b/m, "--!native\n--!strict");
+		} else if (/^\s*--!optimize\b/m.test(next)) {
+			next = `--!native\n${next}`;
+		} else {
+			next = `--!native\n${next}`;
+		}
+	}
+	return next;
+}

package/src/target/optimizer-advise.ts

@@ -0,0 +1,93 @@
+/**
+ * Cluaupp Optimizer advisor (v1) — suggestions only; does not rewrite Luau yet.
+ * Philosophy: write idiomatic CL++; compiler advises best representation.
+ */
+
+import { type PlatformDiagnostic, lineColAt, stripCommentsKeepStrings } from "./diagnostics.js";
+
+export interface OptimizeAdvice {
+	kind: "storage" | "native" | "parallel" | "layout";
+	target: string;
+	message: string;
+	severity: "info" | "warning";
+}
+
+export function adviseOptimizer(source: string, fileName: string): OptimizeAdvice[] {
+	const clean = stripCommentsKeepStrings(source);
+	const advice: OptimizeAdvice[] = [];
+
+	const structRe = /struct\s+([A-Za-z_]\w*)\s*\{([^}]*)\}/g;
+	let m: RegExpExecArray | null;
+	while ((m = structRe.exec(clean))) {
+		const name = m[1];
+		const body = m[2];
+		const fields = body.split(";").map((s) => s.trim()).filter(Boolean);
+		if (fields.length < 2) continue;
+		const numeric = fields.filter((f) => /^(float|double|int|i32|f32|f64|bool)\b/.test(f) || /\bVector3\b/.test(f));
+		const ratio = numeric.length / fields.length;
+		if (ratio >= 0.75 && fields.length >= 3) {
+			advice.push({
+				kind: "storage",
+				target: name,
+				message: `Hot numeric struct ${name} (${numeric.length}/${fields.length} fields) — candidate for SoA / dense storage (Optimizer Level 1–3)`,
+				severity: "info",
+			});
+		}
+		const bools = fields.filter((f) => /^bool\b/.test(f));
+		if (bools.length >= 4) {
+			advice.push({
+				kind: "layout",
+				target: name,
+				message: `${name} has ${bools.length} bool fields — candidate for internal bitset packing`,
+				severity: "info",
+			});
+		}
+	}
+
+	const fnRe = /(?:void|int|float|double|bool|auto)\s+([A-Za-z_]\w*)\s*\([^)]*\)\s*\{/g;
+	while ((m = fnRe.exec(clean))) {
+		const name = m[1];
+		if (name === "init") continue;
+		const start = m.index + m[0].length;
+		let depth = 1;
+		let i = start;
+		for (; i < clean.length && depth > 0; i++) {
+			if (clean[i] === "{") depth++;
+			else if (clean[i] === "}") depth--;
+		}
+		const body = clean.slice(start, i);
+		const apiHits = (body.match(/GetService|WaitForChild|Instance|FindFirstChild|FireServer|FireClient/g) || []).length;
+		const numericHits = (body.match(/\b(sin|cos|sqrt|Vector3|CFrame|math::)\b|[+\-*/]=|[+\-*/]/g) || []).length;
+		if (numericHits >= 6 && apiHits <= 1 && body.length > 40) {
+			advice.push({
+				kind: "native",
+				target: name,
+				message: `${name} looks numeric-hot / low Instance API — good @native / --!native candidate (CLUAU-PERF-001)`,
+				severity: "info",
+			});
+		}
+		if (apiHits === 0 && /for\s*\(/.test(body) && !/shared|static/.test(body)) {
+			advice.push({
+				kind: "parallel",
+				target: name,
+				message: `${name} may be parallelizable (independent loop, no shared Instance API) — review ThreadSafety`,
+				severity: "info",
+			});
+		}
+	}
+
+	void fileName;
+	void lineColAt;
+	return advice;
+}
+
+export function adviceAsDiagnostics(advice: OptimizeAdvice[], fileName: string): PlatformDiagnostic[] {
+	return advice.map((a) => ({
+		code: a.kind === "native" ? "CLUAU_PERF001" : a.kind === "parallel" ? "CLUAU_PAR_ADVISE" : "CLUAU_OPT001",
+		message: a.message,
+		line: 1,
+		column: 1,
+		severity: a.severity === "warning" ? "warning" : "info",
+		file: fileName,
+	}));
+}

package/src/target/optimizer-apply.ts

@@ -0,0 +1,63 @@
+/**
+ * Apply Optimizer transforms to CL++ source:
+ * - `#pragma native` on numeric-hot functions
+ * - `#pragma layout soa` + SoA Luau modules when --layout
+ */
+
+import { adviseOptimizer } from "./optimizer-advise.js";
+import type { CluauppProfile } from "./pgo.js";
+import { rankAdvice } from "./pgo.js";
+import { applyLayoutPragmas, writeSoaArtifacts, type SoaPlan } from "./optimizer-soa.js";
+
+export interface ApplyResult {
+	source: string;
+	changed: boolean;
+	applied: string[];
+	soaPlans?: SoaPlan[];
+}
+
+export function applyOptimizerHints(
+	source: string,
+	fileName: string,
+	profile: CluauppProfile | null = null,
+	opts: { layout?: boolean; useBuffer?: boolean; projectRoot?: string } = {},
+): ApplyResult {
+	const advice = rankAdvice(adviseOptimizer(source, fileName), profile);
+	const nativeTargets = new Set(advice.filter((a) => a.kind === "native").map((a) => a.target));
+	let out = source;
+	const applied: string[] = [];
+
+	for (const name of nativeTargets) {
+		const re = new RegExp(
+			`((?:^|\\n)(?:\\s*))((?:void|int|float|double|bool|auto)\\s+${name}\\s*\\()`,
+			"m",
+		);
+		const m = out.match(re);
+		if (!m) continue;
+		const before = out.slice(0, m.index! + m[1].length);
+		if (
+			/#pragma\s+native\s*$/m.test(before.slice(-80)) ||
+			/#pragma\s+native/.test(out.slice(Math.max(0, m.index! - 40), m.index!))
+		) {
+			continue;
+		}
+		out = out.replace(re, `$1#pragma native\n$1$2`);
+		applied.push(`#pragma native → ${name}`);
+	}
+
+	let soaPlans: SoaPlan[] | undefined;
+	if (opts.layout) {
+		const layout = applyLayoutPragmas(out, fileName, profile);
+		out = layout.source;
+		applied.push(...layout.applied);
+		soaPlans = layout.plans;
+		if (opts.projectRoot && layout.plans.length) {
+			const files = writeSoaArtifacts(opts.projectRoot, layout.plans, { useBuffer: opts.useBuffer });
+			for (const f of files) {
+				applied.push(`SoA emit → ${f.replace(/\\/g, "/")}`);
+			}
+		}
+	}
+
+	return { source: out, changed: applied.length > 0 || out !== source, applied, soaPlans };
+}

package/src/target/optimizer-soa.ts

@@ -0,0 +1,270 @@
+/**
+ * Opt-in SoA / dense storage codegen.
+ * Triggered by `#pragma layout soa StructName` (or optimize --apply --layout).
+ * Emits a Luau ModuleScript companion — does not silently rewrite gameplay structs.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { adviseOptimizer } from "./optimizer-advise.js";
+import type { CluauppProfile } from "./pgo.js";
+import { rankAdvice } from "./pgo.js";
+
+export type SoaScalar = "f32" | "i32" | "bool" | "Vector3";
+
+export interface SoaField {
+	name: string;
+	kind: SoaScalar;
+}
+
+export interface SoaPlan {
+	structName: string;
+	fields: SoaField[];
+}
+
+const FIELD_RE =
+	/^(?:float|f32|double|f64)\s+([A-Za-z_]\w*)|^(?:int|i32)\s+([A-Za-z_]\w*)|^bool\s+([A-Za-z_]\w*)|^Vector3\s+([A-Za-z_]\w*)/;
+
+export function parseSoaFields(structBody: string): SoaField[] {
+	const fields: SoaField[] = [];
+	for (const piece of structBody.split(";")) {
+		const line = piece.trim().replace(/=.*/, "").trim();
+		if (!line) continue;
+		const m = line.match(FIELD_RE);
+		if (!m) continue;
+		if (m[1]) fields.push({ name: m[1], kind: "f32" });
+		else if (m[2]) fields.push({ name: m[2], kind: "i32" });
+		else if (m[3]) fields.push({ name: m[3], kind: "bool" });
+		else if (m[4]) fields.push({ name: m[4], kind: "Vector3" });
+	}
+	return fields;
+}
+
+export function findStructBody(source: string, structName: string): string | null {
+	const re = new RegExp(`struct\\s+${structName}\\s*\\{([^}]*)\\}`);
+	const m = source.match(re);
+	return m ? m[1] : null;
+}
+
+export function listLayoutTargets(source: string): string[] {
+	const names = new Set<string>();
+	const re = /#pragma\s+layout\s+soa\s+([A-Za-z_]\w*)/g;
+	let m: RegExpExecArray | null;
+	while ((m = re.exec(source))) {
+		names.add(m[1]);
+	}
+	return [...names];
+}
+
+export function planSoa(source: string, structName: string): SoaPlan | null {
+	const body = findStructBody(source, structName);
+	if (!body) return null;
+	const fields = parseSoaFields(body);
+	if (fields.length < 2) return null;
+	return { structName, fields };
+}
+
+function defaultFor(kind: SoaScalar): string {
+	if (kind === "f32") return "0";
+	if (kind === "i32") return "0";
+	if (kind === "bool") return "false";
+	return "Vector3.zero";
+}
+
+/** Generate a standalone Luau SoA module (table-columns; buffer pack optional for floats). */
+export function generateSoaLuau(plan: SoaPlan, useBuffer = false): string {
+	const { structName, fields } = plan;
+	const cols = fields
+		.map((f) => {
+			if (useBuffer && (f.kind === "f32" || f.kind === "i32")) {
+				return `\t\t${f.name} = buffer.create(0), -- grown on ensure`;
+			}
+			return `\t\t${f.name} = table.create(capacity),`;
+		})
+		.join("\n");
+
+	const pushLines = fields
+		.map((f) => {
+			if (useBuffer && f.kind === "f32") {
+				return `\tbuffer.writef32(store.${f.name}, (i - 1) * 4, row.${f.name} or 0)`;
+			}
+			if (useBuffer && f.kind === "i32") {
+				return `\tbuffer.writei32(store.${f.name}, (i - 1) * 4, row.${f.name} or 0)`;
+			}
+			return `\tstore.${f.name}[i] = row.${f.name}`;
+		})
+		.join("\n");
+
+	const getLines = fields
+		.map((f) => {
+			if (useBuffer && f.kind === "f32") {
+				return `\t\t${f.name} = buffer.readf32(store.${f.name}, (i - 1) * 4),`;
+			}
+			if (useBuffer && f.kind === "i32") {
+				return `\t\t${f.name} = buffer.readi32(store.${f.name}, (i - 1) * 4),`;
+			}
+			return `\t\t${f.name} = store.${f.name}[i],`;
+		})
+		.join("\n");
+
+	const ensureBuf = useBuffer
+		? fields
+				.filter((f) => f.kind === "f32" || f.kind === "i32")
+				.map(
+					(f) => `
+	local need = capacity * 4
+	if buffer.len(store.${f.name}) < need then
+		local nb = buffer.create(need)
+		buffer.copy(nb, 0, store.${f.name})
+		store.${f.name} = nb
+	end`,
+				)
+				.join("\n")
+		: "";
+
+	return `--!native
+--!optimize 2
+--!strict
+-- cluaupp generated SoA for ${structName} — do not edit by hand.
+-- Use via: local ${structName}Soa = require(...${structName}Soa)
+
+export type ${structName}Row = {
+${fields.map((f) => `\t${f.name}: ${f.kind === "f32" ? "number" : f.kind === "i32" ? "number" : f.kind === "bool" ? "boolean" : "Vector3"},`).join("\n")}
+}
+
+export type ${structName}Store = {
+	len: number,
+	capacity: number,
+${fields.map((f) => `\t${f.name}: ${useBuffer && (f.kind === "f32" || f.kind === "i32") ? "buffer" : "{}"},`).join("\n")}
+}
+
+local ${structName}Soa = {}
+
+function ${structName}Soa.new(capacity: number): ${structName}Store
+	capacity = math.max(1, capacity or 64)
+	local store = {
+		len = 0,
+		capacity = capacity,
+${cols}
+	}
+	return store
+end
+
+function ${structName}Soa.ensure(store: ${structName}Store, capacity: number)
+	if capacity <= store.capacity then
+		return
+	end
+	store.capacity = capacity
+${ensureBuf}
+${useBuffer ? "" : fields.map((f) => `\t-- table.create columns grow on index assign`).join("\n")}
+end
+
+function ${structName}Soa.push(store: ${structName}Store, row: ${structName}Row): number
+	local i = store.len + 1
+	${structName}Soa.ensure(store, i)
+	store.len = i
+${pushLines}
+	return i
+end
+
+function ${structName}Soa.get(store: ${structName}Store, i: number): ${structName}Row
+	return {
+${getLines}
+	}
+end
+
+function ${structName}Soa.set(store: ${structName}Store, i: number, row: ${structName}Row)
+${pushLines}
+end
+
+return ${structName}Soa
+`;
+}
+
+export interface LayoutApplyResult {
+	source: string;
+	changed: boolean;
+	applied: string[];
+	plans: SoaPlan[];
+}
+
+/** Insert `#pragma layout soa Name` before advised storage structs. */
+export function applyLayoutPragmas(
+	source: string,
+	fileName: string,
+	profile: CluauppProfile | null = null,
+): LayoutApplyResult {
+	const advice = rankAdvice(adviseOptimizer(source, fileName), profile);
+	const targets = new Set(advice.filter((a) => a.kind === "storage").map((a) => a.target));
+	const applied: string[] = [];
+	const plans: SoaPlan[] = [];
+	let out = source;
+
+	for (const name of targets) {
+		if (new RegExp(`#pragma\\s+layout\\s+soa\\s+${name}\\b`).test(out)) {
+			const plan = planSoa(out, name);
+			if (plan) plans.push(plan);
+			continue;
+		}
+		const re = new RegExp(`((?:^|\\n)(?:\\s*))(struct\\s+${name}\\s*\\{)`, "m");
+		if (!re.test(out)) continue;
+		out = out.replace(re, `$1#pragma layout soa ${name}\n$1$2`);
+		applied.push(`#pragma layout soa → ${name}`);
+		const plan = planSoa(out, name);
+		if (plan) plans.push(plan);
+	}
+
+	for (const name of listLayoutTargets(out)) {
+		if (plans.some((p) => p.structName === name)) continue;
+		const plan = planSoa(out, name);
+		if (plan) plans.push(plan);
+	}
+
+	return { source: out, changed: applied.length > 0, applied, plans };
+}
+
+export function writeSoaArtifacts(
+	projectRoot: string,
+	plans: SoaPlan[],
+	opts: { useBuffer?: boolean } = {},
+): string[] {
+	if (!plans.length) return [];
+	const outDir = path.join(projectRoot, ".cluaupp", "generated", "soa");
+	fs.mkdirSync(outDir, { recursive: true });
+	const written: string[] = [];
+	for (const plan of plans) {
+		const file = path.join(outDir, `${plan.structName}Soa.luau`);
+		fs.writeFileSync(file, generateSoaLuau(plan, opts.useBuffer === true), "utf8");
+		written.push(file);
+	}
+	return written;
+}
+
+/** Collect SoA plans from all sources that already have layout pragmas. */
+export function collectSoaPlansFromProject(projectRoot: string, rootDir = "src"): SoaPlan[] {
+	const srcDir = path.join(projectRoot, rootDir);
+	if (!fs.existsSync(srcDir)) return [];
+	const plans: SoaPlan[] = [];
+	const seen = new Set<string>();
+	const walk = (dir: string) => {
+		for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+			const full = path.join(dir, entry.name);
+			if (entry.isDirectory()) {
+				walk(full);
+				continue;
+			}
+			if (!/\.(clpp|clp|clh)$/i.test(entry.name)) continue;
+			const source = fs.readFileSync(full, "utf8");
+			for (const name of listLayoutTargets(source)) {
+				if (seen.has(name)) continue;
+				const plan = planSoa(source, name);
+				if (plan) {
+					seen.add(name);
+					plans.push(plan);
+				}
+			}
+		}
+	};
+	walk(srcDir);
+	return plans;
+}

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