cluaupp 1.5.0 → 1.5.1

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

package/src/target/studio-bridge.ts

@@ -0,0 +1,140 @@
+/**
+ * Local HTTP bridge: Studio plugin ↔ IDE (VS Code / Cursor).
+ * Default port 3847. Studio POSTs open requests; IDE polls /events.
+ */
+
+import http from "node:http";
+import fs from "node:fs";
+import path from "node:path";
+import { EventEmitter } from "node:events";
+
+export const BRIDGE_DEFAULT_PORT = 3847;
+
+export interface BridgeEvent {
+	id: number;
+	at: string;
+	type: "open" | "select" | "error" | "ping";
+	path?: string;
+	line?: number;
+	message?: string;
+	instancePath?: string;
+}
+
+export interface BridgeServer {
+	port: number;
+	close: () => void;
+	onEvent: (fn: (ev: BridgeEvent) => void) => () => void;
+	getEventsSince: (id: number) => BridgeEvent[];
+}
+
+export function startStudioBridge(opts: {
+	port?: number;
+	projectRoot?: string;
+	onEvent?: (ev: BridgeEvent) => void;
+} = {}): BridgeServer {
+	const port = opts.port ?? BRIDGE_DEFAULT_PORT;
+	const bus = new EventEmitter();
+	const events: BridgeEvent[] = [];
+	let nextId = 1;
+
+	const push = (partial: Omit<BridgeEvent, "id" | "at">) => {
+		const ev: BridgeEvent = {
+			id: nextId++,
+			at: new Date().toISOString(),
+			...partial,
+		};
+		events.push(ev);
+		if (events.length > 200) events.shift();
+		bus.emit("event", ev);
+		opts.onEvent?.(ev);
+		return ev;
+	};
+
+	const server = http.createServer((req, res) => {
+		const url = new URL(req.url || "/", `http://127.0.0.1:${port}`);
+		res.setHeader("Access-Control-Allow-Origin", "*");
+		res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+		res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+		if (req.method === "OPTIONS") {
+			res.writeHead(204);
+			res.end();
+			return;
+		}
+
+		if (req.method === "GET" && url.pathname === "/health") {
+			res.writeHead(200, { "Content-Type": "application/json" });
+			res.end(JSON.stringify({ ok: true, service: "cluaupp-bridge", port }));
+			return;
+		}
+
+		if (req.method === "GET" && url.pathname === "/events") {
+			const since = Number(url.searchParams.get("since") || "0");
+			const batch = events.filter((e) => e.id > since);
+			res.writeHead(200, { "Content-Type": "application/json" });
+			res.end(JSON.stringify({ events: batch }));
+			return;
+		}
+
+		if (req.method === "POST" && url.pathname === "/open") {
+			let body = "";
+			req.on("data", (c) => {
+				body += c;
+				if (body.length > 1_000_000) req.destroy();
+			});
+			req.on("end", () => {
+				try {
+					const data = JSON.parse(body || "{}") as {
+						path?: string;
+						line?: number;
+						instancePath?: string;
+						type?: BridgeEvent["type"];
+						message?: string;
+					};
+					const rel = (data.path || "").replace(/\\/g, "/");
+					if (opts.projectRoot && rel && !rel.includes("..")) {
+						const abs = path.resolve(opts.projectRoot, rel);
+						if (!abs.startsWith(path.resolve(opts.projectRoot))) {
+							res.writeHead(400);
+							res.end("bad path");
+							return;
+						}
+						if (!fs.existsSync(abs) && !rel.endsWith(".clpp") && !rel.endsWith(".clh")) {
+							/* still emit — file may be unsaved emit path */
+						}
+					}
+					const ev = push({
+						type: data.type || "open",
+						path: rel || undefined,
+						line: data.line,
+						instancePath: data.instancePath,
+						message: data.message,
+					});
+					res.writeHead(200, { "Content-Type": "application/json" });
+					res.end(JSON.stringify({ ok: true, id: ev.id }));
+				} catch (err) {
+					res.writeHead(400);
+					res.end(String(err instanceof Error ? err.message : err));
+				}
+			});
+			return;
+		}
+
+		res.writeHead(404);
+		res.end("not found");
+	});
+
+	server.listen(port, "127.0.0.1");
+
+	return {
+		port,
+		close: () => {
+			server.close();
+			bus.removeAllListeners();
+		},
+		onEvent: (fn) => {
+			bus.on("event", fn);
+			return () => bus.off("event", fn);
+		},
+		getEventsSince: (id) => events.filter((e) => e.id > id),
+	};
+}

package/src/types.ts

@@ -26,6 +26,8 @@ export interface RequireBinding {
 export interface CompileOptions {
 	strict?: boolean;
 	architecture?: boolean;
+	/** Pass through to clpp (default true). */
+	optimize?: boolean;
 	rootDir?: string;
 	outDir?: string;
 	filePath?: string;
@@ -44,6 +46,12 @@ export interface ProjectConfig {
 	outDir: string;
 	strict: boolean;
 	architecture: boolean;
+	rules?: {
+		clientCannotImport?: string[];
+		sharedCannotUse?: string[];
+		serverCannotImport?: string[];
+	};
+	components?: Array<{ path: string; children: Record<string, string> }>;
 }
 
 export interface BuildOptions {
@@ -54,6 +62,12 @@ export interface BuildOptions {
 	analyze?: boolean;
 	rojo?: string;
 	strict?: boolean;
+	/** Fail if api lock / Flare versions / component contracts are dirty. */
+	frozen?: boolean;
+	/** Skip transpile when source fingerprint matches `.cluaupp/compile-cache` (default true). */
+	incremental?: boolean;
+	/** Parallel transpile workers for async build (default: CPU-bounded). Set 1 to disable. */
+	jobs?: number;
 }
 
 export interface BuildResult {