cluaupp 1.0.0 → 1.4.0

package/src/clpp/index.ts

@@ -1,6 +1,6 @@
-export type { CompileArtifact, CompileRequest, LanguageManifest } from "./contract.js";
-export { CLPP_INSTALL_HINT } from "./contract.js";
-export { compileViaClpp, clppManifest, clppVersion, hasClpp, resolveClppBinary } from "./runner.js";
+export type { CompileArtifact, CompileDiagnostic, CompileRequest, LanguageManifest } from "./contract.js";
+export { CLPP_INSTALL_HINT, MIN_CLPP_VERSION } from "./contract.js";
+export { compileViaClpp, compileViaClppAsync, clppManifest, clppVersion, hasClpp, resolveClppBinary } from "./runner.js";
 export { clppLuauToGame, shouldSkipInit } from "./postprocess.js";
 export {
 	SOURCE_EXTS,

package/src/clpp/paths.ts

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { isGeneratedHeader } from "../flare/index.js";
 
 export const SOURCE_EXTS = [".clpp", ".clp", ".clh"];
 
@@ -14,8 +15,6 @@ export function isEngineStub(filePath: string): boolean {
 		normalized.includes("/include/clpp/") ||
 		normalized.includes("/include/cluau/") ||
 		normalized.includes("/stdlib/") ||
-		normalized.endsWith("/roblox.hpp") ||
-		normalized.endsWith("/roblox.h") ||
 		normalized.endsWith("/roblox.clh")
 	);
 }
@@ -109,7 +108,7 @@ export function collectSources(dir: string, files: string[] = []): string[] {
 		const full = path.join(dir, entry.name);
 		if (entry.isDirectory()) {
 			collectSources(full, files);
-		} else if (isSourceFile(entry.name)) {
+		} else if (isSourceFile(entry.name) && !isGeneratedHeader(full)) {
 			files.push(full);
 		}
 	}

package/src/clpp/postprocess.ts

@@ -1,4 +1,4 @@
-import { insertPreamble, MODULES, requireCluauppLib } from "../libs.js";
+import { insertPreamble, libraryNamesFromIncludes, MODULES, requireCluauppLib } from "../libs.js";
 import type { CompileArtifact } from "./contract.js";
 import { isTaggedScript } from "./paths.js";
 
@@ -9,6 +9,7 @@ export type PostprocessOptions = {
 	rootDir?: string;
 	strict?: boolean;
 	skipInit?: boolean;
+	source?: string;
 };
 
 function insertAfterHeader(luau: string, block: string): string {
@@ -21,10 +22,44 @@ function insertAfterHeader(luau: string, block: string): string {
 	return `${luau.slice(0, insertAt)}\n${block}\n${rest}`;
 }
 
-function rewriteClppLibs(luau: string): string {
-	return String(luau).replace(/require\(\s*ClppLibs\.([A-Za-z0-9_]+)\s*\)/g, (_all, name: string) => {
-		return requireCluauppLib(name);
+const CLPP_LIB_FILE: Record<string, string> = {
+	Janitor: "Sweep",
+	Signal: "Spark",
+	MathUtils: "Axiom",
+	FormatNumber: "Mint",
+	Module3D: "Stage",
+	Twinkle: "Bloom",
+	EzVisualz: "Bloom",
+	Spring: "Coil",
+	Display: "Trace",
+	StickyBillboard: "Pin",
+	Icon: "Crest",
+	TopbarPlus: "Crest",
+	Cmdr: "Helm",
+	Chrono: "Echo",
+	Iris: "Lens",
+	Fusion: "Gleam",
+	StateMachine: "Shift",
+	VfxUtil: "Ember",
+	DataService: "Keep",
+	TutorialKit: "Guide",
+	TutorialServer: "Guide",
+};
+
+function rewriteClppLibs(luau: string, relativeName?: string): string {
+	let next = String(luau).replace(/require\(\s*ClppLibs\.([A-Za-z0-9_]+)\s*\)/g, (_all, name: string) => {
+		return requireCluauppLib(CLPP_LIB_FILE[name] || name);
 	});
+	next = next.replace(/CluauppLibs\.Janitor\b/g, "CluauppLibs.Sweep");
+	next = next.replace(/CluauppLibs\.Signal\b/g, "CluauppLibs.Spark");
+	next = next.replace(/:Add\(([^,\n()]+),\s*"Disconnect"\s*\)/g, ":Add($1)");
+	const tagged = relativeName ? isTaggedScript(relativeName) : false;
+	const hasConnect = /:Connect\(/.test(next);
+	const hasSweep = /CluauppLibs\.Sweep/.test(next) || /\bjanitor\b/.test(next) || /\bsweep\b/.test(next);
+	if (tagged && hasConnect && !hasSweep) {
+		next = insertAfterHeader(next, "local sweep = require(ReplicatedStorage.CluauppLibs.Sweep).new()");
+	}
+	return next;
 }
 
 function ensureReplicatedStorage(luau: string): string {
@@ -51,11 +86,23 @@ function ensureStrict(luau: string, strict?: boolean): string {
 	return `--!strict\n${luau}`;
 }
 
+function normalizeLibraryName(name: string): string | null {
+	const mapped = CLPP_LIB_FILE[name] || name;
+	if ((MODULES as Record<string, { file: string; bind: string }>)[mapped]) {
+		return mapped;
+	}
+	return null;
+}
+
 function librarySpecs(names: string[] | undefined) {
 	const specs: Array<{ file: string; bind: string }> = [];
 	const seen = new Set<string>();
 	for (const name of names || []) {
-		const spec = (MODULES as Record<string, { file: string; bind: string }>)[name];
+		const mapped = normalizeLibraryName(name);
+		if (!mapped) {
+			continue;
+		}
+		const spec = (MODULES as Record<string, { file: string; bind: string }>)[mapped];
 		if (!spec || seen.has(spec.bind)) {
 			continue;
 		}
@@ -65,6 +112,21 @@ function librarySpecs(names: string[] | undefined) {
 	return specs;
 }
 
+function includedLibraryNames(artifact: CompileArtifact, source?: string): string[] {
+	const names: string[] = [];
+	for (const name of artifact.libraries || []) {
+		if (name === "*") {
+			names.push(...Object.keys(MODULES));
+			continue;
+		}
+		names.push(name);
+	}
+	if (source) {
+		names.push(...(libraryNamesFromIncludes(source) as string[]));
+	}
+	return names;
+}
+
 function missingLibraries(luau: string, names: string[] | undefined) {
 	return librarySpecs(names).filter((spec) => {
 		return !luau.includes(`CluauppLibs.${spec.file}`) && !new RegExp(`\\bconst ${spec.bind}\\b`).test(luau);
@@ -79,13 +141,13 @@ export function shouldSkipInit(fileName: string, hasSiblingHeader: boolean): boo
 }
 
 export function clppLuauToGame(artifact: CompileArtifact, options: PostprocessOptions): string {
-	let luau = rewriteClppLibs(artifact.luau || "");
+	let luau = rewriteClppLibs(artifact.luau || "", options.relativeName);
 	luau = ensureReplicatedStorage(luau);
 	if (options.skipInit) {
 		luau = stripInitCall(luau);
 	}
 	luau = ensureStrict(luau, options.strict);
-	const missing = missingLibraries(luau, artifact.libraries);
+	const missing = missingLibraries(luau, includedLibraryNames(artifact, options.source));
 	if (missing.length > 0) {
 		luau = insertPreamble(luau, [], missing, options.outName);
 	}

package/src/clpp/runner.ts

@@ -1,22 +1,127 @@
-import { spawnSync } from "node:child_process";
-import { CLPP_INSTALL_HINT, type CompileArtifact, type CompileRequest, type LanguageManifest } from "./contract.js";
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+	CLPP_INSTALL_HINT,
+	MIN_CLPP_VERSION,
+	type CompileArtifact,
+	type CompileDiagnostic,
+	type CompileRequest,
+	type LanguageManifest,
+} from "./contract.js";
 
 const MISSING_CLPP = `cluaupp: clpp not found. ${CLPP_INSTALL_HINT}`;
 
-function whichClpp(): string | null {
-	if (process.env.CLPP_PATH) {
-		return process.env.CLPP_PATH;
+type Semver = { major: number; minor: number; patch: number };
+
+let cachedBin: string | null | undefined;
+
+function parseSemver(text: string): Semver | null {
+	const match = String(text).match(/(\d+)\.(\d+)\.(\d+)/);
+	if (!match) {
+		return null;
 	}
+	return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) };
+}
+
+function cmpSemver(a: Semver, b: Semver): number {
+	return a.major - b.major || a.minor - b.minor || a.patch - b.patch;
+}
+
+function minClpp(): Semver {
+	return parseSemver(MIN_CLPP_VERSION) || { major: 0, minor: 3, patch: 2 };
+}
+
+function tooOldMessage(bin: string, version: string | null): string {
+	return `cluaupp: clpp ${version || "unknown"} is too old (${bin}). Need CL++ ${MIN_CLPP_VERSION}+. Install https://github.com/KartzRbx/CLPP/releases/download/v0.3.2/clpp-setup.exe or set CLPP / CLPP_PATH.`;
+}
+
+function probeVersion(bin: string): string | null {
+	const result = spawnSync(bin, ["--version"], { encoding: "utf8", windowsHide: true });
+	if (result.status !== 0) {
+		return null;
+	}
+	return String(result.stdout || result.stderr || "").trim() || null;
+}
+
+function pushCandidate(out: string[], seen: Set<string>, item: string | undefined): void {
+	const value = String(item || "").trim();
+	if (!value) {
+		return;
+	}
+	const key = value.toLowerCase();
+	if (seen.has(key)) {
+		return;
+	}
+	seen.add(key);
+	out.push(value);
+}
+
+function existsBin(bin: string): boolean {
+	try {
+		return fs.existsSync(bin);
+	} catch {
+		return false;
+	}
+}
+
+function listClppCandidates(): string[] {
+	const seen = new Set<string>();
+	const override: string[] = [];
+	pushCandidate(override, seen, process.env.CLPP);
+	pushCandidate(override, seen, process.env.CLPP_PATH);
+	const overrideExisting = override.filter(existsBin);
+	if (overrideExisting.length > 0) {
+		return overrideExisting;
+	}
+
+	const out: string[] = [];
 	const finder = process.platform === "win32" ? "where" : "which";
 	const found = spawnSync(finder, ["clpp"], { encoding: "utf8", windowsHide: true });
-	if (found.status !== 0) {
+	if (found.status === 0) {
+		for (const line of String(found.stdout || "").split(/\r?\n/)) {
+			pushCandidate(out, seen, line);
+		}
+	}
+
+	if (process.platform === "win32") {
+		const local = process.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local");
+		pushCandidate(out, seen, path.join(local, "Programs", "CLPP", "clpp.exe"));
+	}
+
+	return out.filter(existsBin);
+}
+
+function pickClppBinary(): string | null {
+	const candidates = listClppCandidates();
+	if (candidates.length === 0) {
 		return null;
 	}
-	const line = String(found.stdout || "")
-		.split(/\r?\n/)
-		.map((item) => item.trim())
-		.find((item) => item.length > 0);
-	return line || "clpp";
+	let best: { bin: string; parsed: Semver } | null = null;
+	let fallback: string | null = null;
+	for (const bin of candidates) {
+		const version = probeVersion(bin);
+		const parsed = parseSemver(version || "");
+		if (!fallback) {
+			fallback = bin;
+		}
+		if (!parsed) {
+			continue;
+		}
+		if (!best || cmpSemver(parsed, best.parsed) > 0) {
+			best = { bin, parsed };
+		}
+	}
+	return best?.bin || fallback;
+}
+
+function whichClpp(): string | null {
+	if (cachedBin !== undefined) {
+		return cachedBin;
+	}
+	cachedBin = pickClppBinary();
+	return cachedBin;
 }
 
 export function hasClpp(): boolean {
@@ -28,6 +133,11 @@ export function resolveClppBinary(): string {
 	if (!bin) {
 		throw new Error(MISSING_CLPP);
 	}
+	const version = probeVersion(bin);
+	const parsed = parseSemver(version || "");
+	if (!parsed || cmpSemver(parsed, minClpp()) < 0) {
+		throw new Error(tooOldMessage(bin, version));
+	}
 	return bin;
 }
 
@@ -55,12 +165,25 @@ function parseArtifact(stdout: string, fileName: string, fallbackError: string):
 	};
 }
 
+export function formatClppFailure(artifact: CompileArtifact, fallback: string): string {
+	const diags = Array.isArray(artifact.diagnostics) ? artifact.diagnostics : [];
+	if (diags.length > 0) {
+		return diags
+			.map((d: CompileDiagnostic) => {
+				const where = `${artifact.fileName || "clpp"}:${d.line}:${d.column}`;
+				return `${where}: ${d.message}`;
+			})
+			.join("\n");
+	}
+	return artifact.error || fallback;
+}
+
 export function compileViaClpp(request: CompileRequest): CompileArtifact {
 	const bin = resolveClppBinary();
 	const payload = JSON.stringify({
 		source: request.source,
 		fileName: request.fileName,
-		strict: request.strict,
+		strict: request.strict ?? null,
 	});
 	const result = spawnSync(bin, ["api", "compile"], {
 		input: payload,
@@ -72,11 +195,53 @@ export function compileViaClpp(request: CompileRequest): CompileArtifact {
 	const stderr = String(result.stderr || "").trim();
 	const artifact = parseArtifact(result.stdout, request.fileName, stderr || result.error?.message || "clpp api compile failed");
 	if (!artifact.ok) {
-		throw new Error(artifact.error || stderr || `clpp failed (${result.status})`);
+		throw new Error(formatClppFailure(artifact, stderr || result.error?.message || `clpp failed (${result.status})`));
 	}
 	return artifact;
 }
 
+export function compileViaClppAsync(request: CompileRequest): Promise<CompileArtifact> {
+	return new Promise((resolve, reject) => {
+		let bin: string;
+		try {
+			bin = resolveClppBinary();
+		} catch (err) {
+			reject(err);
+			return;
+		}
+		const child = spawn(bin, ["api", "compile"], {
+			cwd: request.cwd,
+			windowsHide: true,
+		});
+		let stdout = "";
+		let stderr = "";
+		child.stdout.setEncoding("utf8");
+		child.stderr.setEncoding("utf8");
+		child.stdout.on("data", (chunk) => {
+			stdout += chunk;
+		});
+		child.stderr.on("data", (chunk) => {
+			stderr += chunk;
+		});
+		child.on("error", reject);
+		child.on("close", (code) => {
+			const artifact = parseArtifact(stdout, request.fileName, stderr.trim() || `clpp api compile failed (${code})`);
+			if (!artifact.ok) {
+				reject(new Error(formatClppFailure(artifact, stderr.trim() || `clpp failed (${code})`)));
+				return;
+			}
+			resolve(artifact);
+		});
+		child.stdin.end(
+			JSON.stringify({
+				source: request.source,
+				fileName: request.fileName,
+				strict: request.strict ?? null,
+			}),
+		);
+	});
+}
+
 export function clppManifest(): LanguageManifest {
 	const bin = resolveClppBinary();
 	const result = spawnSync(bin, ["api", "manifest"], {
@@ -94,9 +259,14 @@ export function clppVersion(): string | null {
 	if (!bin) {
 		return null;
 	}
-	const result = spawnSync(bin, ["--version"], { encoding: "utf8", windowsHide: true });
-	if (result.status !== 0) {
-		return null;
-	}
-	return String(result.stdout || "").trim() || null;
+	return probeVersion(bin);
+}
+
+export function clppInstalls(): Array<{ bin: string; version: string | null; selected: boolean }> {
+	const selected = whichClpp();
+	return listClppCandidates().map((bin) => ({
+		bin,
+		version: probeVersion(bin),
+		selected: bin === selected,
+	}));
 }

package/src/compile.ts

@@ -1,25 +1,38 @@
 import path from "node:path";
 import type { CompileOptions, CompileServiceResult } from "./types.js";
-import { compileViaClpp } from "./clpp/runner.js";
+import { compileViaClpp, compileViaClppAsync } from "./clpp/runner.js";
 import { clppLuauToGame, shouldSkipInit } from "./clpp/postprocess.js";
 import { emitKind, siblingHeader, toLuauPath } from "./clpp/paths.js";
+import type { CompileArtifact } from "./clpp/contract.js";
 
-export function compileSource(source: string, fileName?: string, options: CompileOptions = {}): string {
-	return compileService(source, fileName, options).files[0]?.contents ?? "";
-}
-
-export function compileService(source: string, fileName?: string, options: CompileOptions = {}): CompileServiceResult {
+function compileArgs(source: string, fileName: string | undefined, options: CompileOptions) {
 	const relative = (options.relativeName || fileName || "input.clpp").replace(/\\/g, "/");
 	const outName = options.outName || toLuauPath(relative);
 	const header = options.filePath ? siblingHeader(options.filePath) : null;
 	const skipInit = options.skipInit === true || shouldSkipInit(relative, Boolean(header));
 	const diskPath = options.filePath ? path.resolve(options.filePath) : null;
-	const artifact = compileViaClpp({
-		source,
-		fileName: diskPath ? diskPath.replace(/\\/g, "/") : relative,
-		strict: options.strict,
-		cwd: diskPath ? path.dirname(diskPath) : options.srcDir,
-	});
+	return {
+		request: {
+			source,
+			fileName: diskPath ? diskPath.replace(/\\/g, "/") : relative,
+			strict: options.strict,
+			cwd: diskPath ? path.dirname(diskPath) : options.srcDir,
+		},
+		relative,
+		outName,
+		skipInit,
+		options,
+	};
+}
+
+function finishArtifact(
+	artifact: CompileArtifact,
+	relative: string,
+	outName: string,
+	options: CompileOptions,
+	skipInit: boolean,
+	source: string,
+): CompileServiceResult {
 	const luau = clppLuauToGame(artifact, {
 		relativeName: relative,
 		outName,
@@ -27,6 +40,7 @@ export function compileService(source: string, fileName?: string, options: Compi
 		rootDir: options.rootDir,
 		strict: options.strict,
 		skipInit,
+		source,
 	});
 	return {
 		kind: emitKind(relative),
@@ -35,3 +49,19 @@ export function compileService(source: string, fileName?: string, options: Compi
 		stale: [],
 	};
 }
+
+export function compileSource(source: string, fileName?: string, options: CompileOptions = {}): string {
+	return compileService(source, fileName, options).files[0]?.contents ?? "";
+}
+
+export function compileService(source: string, fileName?: string, options: CompileOptions = {}): CompileServiceResult {
+	const args = compileArgs(source, fileName, options);
+	const artifact = compileViaClpp(args.request);
+	return finishArtifact(artifact, args.relative, args.outName, args.options, args.skipInit, source);
+}
+
+export async function compileServiceAsync(source: string, fileName?: string, options: CompileOptions = {}): Promise<CompileServiceResult> {
+	const args = compileArgs(source, fileName, options);
+	const artifact = await compileViaClppAsync(args.request);
+	return finishArtifact(artifact, args.relative, args.outName, args.options, args.skipInit, source);
+}