cluaupp 0.2.3 → 1.3.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "cluaupp",
-	"version": "0.2.3",
-	"description": "Cluaupp — the definitive merge of C++ and modern Luau. Source-to-source transpiler with first-class Roblox APIs.",
+	"version": "1.3.0",
+	"description": "Cluaupp toolchain — compile CL++ to Luau with Rojo and CluauppLibs.",
 	"author": "KartzDev",
 	"license": "MIT",
 	"bin": {
@@ -24,7 +24,9 @@
 		"runtime",
 		"README.md",
 		"LICENSE",
-		"CHANGELOG.md",
+		"CHANGELOG.md"
+	],
+	"workspaces": [
 		"docs"
 	],
 	"scripts": {
@@ -34,14 +36,12 @@
 		"build:cli": "tsc",
 		"dev:cli": "tsx src/cli.ts",
 		"prepare": "tsc",
-		"test": "node test/out.test.js && node test/types.test.js && node test/modules.test.js && node test/security.test.js && node test/understander.test.js",
+		"test": "node test/security.test.js && node test/understander.test.js && node test/out.test.js && node test/types.test.js && node test/modules.test.js && node test/clpp.test.js",
+		"test:clpp-contract": "node test/clpp.test.js",
 		"generate-api": "node scripts/generate-api.js",
-		"check-highlight": "tsx web/src/check-content.ts",
 		"vendor-libs": "node scripts/vendor-libs.js",
-		"docs": "moonwave dev",
-		"docs:build": "moonwave build",
-		"site": "vite build --config web/vite.config.mts && npm run check-highlight",
-		"site:dev": "vite --config web/vite.config.mts",
+		"site": "npm run build -w @cluaupp/docs",
+		"site:dev": "npm run dev -w @cluaupp/docs",
 		"dev": "node scripts/dev.js",
 		"stop": "node scripts/stop.js",
 		"prepublishOnly": "tsc && npm test"
@@ -52,13 +52,12 @@
 	"keywords": [
 		"luau",
 		"roblox",
-		"cpp",
-		"c++",
+		"clpp",
+		"cl++",
 		"transpiler",
 		"compiler",
 		"rojo",
-		"cluaupp",
-		"cluau"
+		"cluaupp"
 	],
 	"repository": {
 		"type": "git",
@@ -69,30 +68,14 @@
 	},
 	"homepage": "https://github.com/KartzRbx/Cluaupp#readme",
 	"dependencies": {
-		"cluaupp": "^0.2.2",
 		"commander": "^15.0.0",
 		"comment-json": "^5.0.0",
-		"tree-sitter": "0.21.1",
-		"tree-sitter-c": "0.23.2",
-		"tree-sitter-cpp": "0.23.4",
 		"vscode-languageserver": "^10.1.1",
 		"vscode-languageserver-textdocument": "^1.0.14"
 	},
-	"overrides": {
-		"tree-sitter-c": "0.23.2"
-	},
 	"devDependencies": {
 		"@types/node": "^22.20.3",
-		"@types/react": "^19.3.0",
-		"@types/react-dom": "^19.3.0",
-		"@vitejs/plugin-react": "^6.0.1",
-		"@vitejs/plugin-vue": "^6.0.1",
-		"react": "^19.1.1",
-		"react-dom": "^19.1.1",
-		"react-router-dom": "^7.8.2",
 		"tsx": "^4.23.13",
-		"typescript": "^7.0.2",
-		"vite": "^8.0.0",
-		"vue": "^3.5.21"
+		"typescript": "^7.0.2"
 	}
 }

package/src/cli.ts

@@ -3,11 +3,13 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { pkg } from "./package-info.js";
 import { start as startLsp } from "./lsp.js";
-import { toLuauPath } from "./preprocess.js";
+import { collectSources, toLuauPath } from "./clpp/paths.js";
+import { CLPP_INSTALL_HINT } from "./clpp/contract.js";
+import { clppInstalls, clppManifest, clppVersion, hasClpp, resolveClppBinary } from "./clpp/runner.js";
 import { installEditorSupport, syncEditorSupport } from "./intellisense.js";
 import { RojoMapper } from "./utils/rojo-mapper.js";
 import { ProcessOrchestrator } from "./utils/process-orchestrator.js";
-import { build as buildProject, init, loadConfig, watch, collectCpp } from "./utils/project.js";
+import { build as buildProject, init, loadConfig, watch } from "./utils/project.js";
 import { transpileSource } from "./transpile.js";
 import type { BuildOptions, BuildResult } from "./types.js";
 
@@ -15,7 +17,7 @@ const program = new Command();
 
 program
 	.name("cluaupp")
-	.description("Definitive transpiler from C++ subset to structured Luau")
+	.description("Cluaupp toolchain — compile CL++ to Luau, Rojo, and CluauppLibs")
 	.version(pkg.version, "-v, --version", "print version")
 	.showHelpAfterError()
 	.action(() => {
@@ -37,14 +39,14 @@ program
 
 program
 	.command("build")
-	.description("Transpila um arquivo, diretório ou projeto C++ para Luau")
+	.description("Compile a CL++ file, directory, or project to Luau")
 	.argument("[folder]", "project folder", ".")
-	.option("-i, --input <path>", "Arquivo ou diretório C++ de entrada")
-	.option("-o, --output <path>", "Arquivo ou diretório Luau de saída")
-	.option("-r, --rojo <path>", "Caminho para o default.project.json do Rojo", "./default.project.json")
-	.option("--strict", "Emitir --!strict")
-	.option("--format", "Rodar StyLua no output")
-	.option("--analyze", "Rodar luau-analyze no output")
+	.option("-i, --input <path>", "CL++ file or directory")
+	.option("-o, --output <path>", "Luau file or directory")
+	.option("-r, --rojo <path>", "Path to Rojo default.project.json", "./default.project.json")
+	.option("--strict", "Emit --!strict")
+	.option("--format", "Run StyLua on output")
+	.option("--analyze", "Run luau-analyze on output")
 	.action(async (folder: string, options: {
 		input?: string;
 		output?: string;
@@ -62,6 +64,7 @@ program
 				format: options.format === true,
 				analyze: options.analyze === true,
 				rojo: options.rojo,
+				strict: options.strict === true,
 			});
 		} catch (err) {
 			console.error(err instanceof Error ? err.message : err);
@@ -73,8 +76,8 @@ program
 	.command("watch")
 	.description("rebuild on save")
 	.argument("[folder]", "project folder", ".")
-	.option("-r, --rojo <path>", "Caminho para o default.project.json do Rojo", "./default.project.json")
-	.option("--format", "Rodar StyLua no output")
+	.option("-r, --rojo <path>", "Path to Rojo default.project.json", "./default.project.json")
+	.option("--format", "Run StyLua on output")
 	.action((folder: string, options: { rojo?: string; format?: boolean }) => {
 		try {
 			watch(path.resolve(process.cwd(), folder), {
@@ -89,7 +92,7 @@ program
 
 program
 	.command("lsp")
-	.description("Cluaupp subset diagnostics over stdio (JSON-RPC). C++ completion is clangd.")
+	.description("Language server stdio (JSON-RPC). Use `clpp install` for CL++ IntelliSense.")
 	.argument("[folder]", "project folder", ".")
 	.action((folder: string) => {
 		startLsp({ projectRoot: path.resolve(process.cwd(), folder) });
@@ -98,18 +101,37 @@ program
 program
 	.command("intellisense")
 	.alias("intelisense")
-	.description("install LLVM clangd and write compile_commands.json")
+	.description("Point the editor at CL++ (`clpp install`)")
 	.argument("[folder]", "project folder", ".")
 	.action(async (folder: string) => {
 		try {
 			const root = path.resolve(process.cwd(), folder);
 			syncEditorSupport(root, loadConfig(root));
-			const installed = await installEditorSupport();
-			console.log("cluaupp: compile_commands.json, .clangd, and .vscode updated in", root);
-			console.log("cluaupp: C++ completion is clangd (include/cluaupp/roblox.hpp)");
-			if (installed.clangd || installed.llvm) {
-				console.log("cluaupp: reload Cursor (Ctrl+Shift+P → Developer: Reload Window)");
+			await installEditorSupport();
+			console.log("cluaupp: editor associations written in", root);
+			console.log("cluaupp:", CLPP_INSTALL_HINT);
+		} catch (err) {
+			console.error(err instanceof Error ? err.message : err);
+			process.exit(1);
+		}
+	});
+
+program
+	.command("language")
+	.description("CL++ manifest (`clpp api manifest`)")
+	.action(() => {
+		try {
+			const bin = resolveClppBinary();
+			const version = clppVersion();
+			if (version) {
+				console.log(version, `(${bin})`);
 			}
+			for (const install of clppInstalls()) {
+				if (!install.selected) {
+					console.log(`skipped ${install.bin} (${install.version || "unknown"})`);
+				}
+			}
+			console.log(JSON.stringify(clppManifest(), null, "\t"));
 		} catch (err) {
 			console.error(err instanceof Error ? err.message : err);
 			process.exit(1);
@@ -139,17 +161,15 @@ async function buildInput(options: {
 		process.exit(1);
 	}
 
-	console.log("🏁 Inicializando Pipeline do Compilador Cluaupp V2...");
-
 	const mapper = new RojoMapper(path.resolve(options.rojo), path.dirname(inputPath));
 	await mapper.load();
 
 	const inputs = (await fs.stat(inputPath)).isDirectory()
-		? collectCpp(inputPath)
+		? collectSources(inputPath)
 		: [inputPath];
 
 	if (inputs.length === 0) {
-		console.error("no .cpp/.h/.hpp files in", inputPath);
+		console.error("no .clpp/.clp/.clh files in", inputPath);
 		process.exit(1);
 	}
 
@@ -184,7 +204,7 @@ async function buildInput(options: {
 				console.log("\nRelatório de Análise Estática do Luau:\n", analysisReport);
 			}
 		}
-		console.log(`Transpilação concluída! ${file} → ${dest}`);
+		console.log(`Compiled ${file} → ${dest}`);
 	}
 }
 
@@ -192,7 +212,7 @@ export function build(root: string, options: BuildOptions = {}): BuildResult {
 	return buildProject(root, options);
 }
 
-export { watch, init, program };
+export { watch, init, program, hasClpp };
 
 export function dispatch(args: string[]): Promise<Command> {
 	return program.parseAsync(["node", "cluaupp", ...args]);

package/src/clpp/contract.ts

@@ -0,0 +1,51 @@
+/** Stable CL++ ↔ Cluaupp contract (CL++ 0.3.2). Cluaupp invokes the `clpp` binary. */
+
+export interface CompileRequest {
+	source: string;
+	fileName: string;
+	strict?: boolean;
+	cwd?: string;
+}
+
+export interface CompileDiagnostic {
+	message: string;
+	/** 1-based */
+	line: number;
+	/** 1-based */
+	column: number;
+	severity: string;
+}
+
+export interface CompileArtifact {
+	ok: boolean;
+	luau: string;
+	fileName: string;
+	outputHint: string;
+	scriptKind: "server" | "client" | "plugin" | null;
+	isScript: boolean;
+	isHeader: boolean;
+	rojoClass: "Script" | "LocalScript" | "ModuleScript";
+	libraries: string[];
+	error?: string;
+	diagnostics?: CompileDiagnostic[];
+}
+
+export interface LanguageManifest {
+	name: "CL++";
+	id: "clpp";
+	version: string;
+	extensions: string[];
+	tags: Array<{
+		pattern: string;
+		scriptKind: string;
+		rojoClass: string;
+	}>;
+	builtins: string[];
+	operators: Array<{ clpp: string; luau: string; meaning: string }>;
+	io: Array<{ clpp: string; luau: string }>;
+}
+
+export const MIN_CLPP_VERSION = "0.3.2";
+
+export const CLPP_INSTALL_HINT =
+	"Install CL++ 0.3.2 (clpp-setup.exe or `clpp setup`) and put `clpp` on PATH. Instances are class names (`Player player`, not `Player*`). Override with CLPP or CLPP_PATH.";

package/src/clpp/index.ts

@@ -0,0 +1,18 @@
+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,
+	collectSources,
+	emitKind,
+	fileStem,
+	isEngineStub,
+	isHeaderFile,
+	isImplFile,
+	isSourceFile,
+	isTaggedScript,
+	scriptKind,
+	siblingHeader,
+	toLuauPath,
+} from "./paths.js";

package/src/clpp/paths.ts

@@ -0,0 +1,115 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export const SOURCE_EXTS = [".clpp", ".clp", ".clh"];
+
+export function isSourceFile(fileName: string): boolean {
+	return SOURCE_EXTS.includes(path.extname(fileName).toLowerCase());
+}
+
+export function isEngineStub(filePath: string): boolean {
+	const normalized = filePath.replace(/\\/g, "/").toLowerCase();
+	return (
+		normalized.includes("/include/cluaupp/") ||
+		normalized.includes("/include/clpp/") ||
+		normalized.includes("/include/cluau/") ||
+		normalized.includes("/stdlib/") ||
+		normalized.endsWith("/roblox.clh")
+	);
+}
+
+export function isHeaderFile(fileName: string): boolean {
+	return path.extname(fileName).toLowerCase() === ".clh";
+}
+
+export function isImplFile(fileName: string): boolean {
+	const ext = path.extname(fileName).toLowerCase();
+	return ext === ".clp" || ext === ".clpp";
+}
+
+export function toLuauPath(filePath: string): string {
+	return String(filePath).replace(/\.(clpp|clp|clh)$/i, ".luau");
+}
+
+export function fileStem(fileName: string): string {
+	let name = path.basename(fileName);
+	const lower = name.toLowerCase();
+	for (const ext of [".clpp", ".clp", ".clh"]) {
+		if (lower.endsWith(ext)) {
+			name = name.slice(0, -ext.length);
+			break;
+		}
+	}
+	const tagged = name.toLowerCase();
+	for (const tag of [".legacy.server", ".legacy.client", ".legacy", ".server", ".client", ".plugin"]) {
+		if (tagged.endsWith(tag)) {
+			name = name.slice(0, -tag.length);
+			break;
+		}
+	}
+	return name;
+}
+
+export function scriptKind(fileName: string): "server" | "client" | "plugin" | "legacy" | "module" | "header" {
+	const name = path.basename(fileName).toLowerCase();
+	if (name.endsWith(".clh")) {
+		return "header";
+	}
+	if (name.includes(".legacy.")) {
+		return "legacy";
+	}
+	if (name.includes(".server.")) {
+		return "server";
+	}
+	if (name.includes(".client.")) {
+		return "client";
+	}
+	if (name.includes(".plugin.")) {
+		return "plugin";
+	}
+	return "module";
+}
+
+export function emitKind(fileName: string): "flat" | "module" | "legacy" {
+	const kind = scriptKind(fileName);
+	if (kind === "legacy") {
+		return "legacy";
+	}
+	if (kind === "module" || kind === "header") {
+		return "module";
+	}
+	return "flat";
+}
+
+export function isTaggedScript(fileName: string): boolean {
+	const kind = scriptKind(fileName);
+	return kind === "server" || kind === "client" || kind === "plugin" || kind === "legacy";
+}
+
+export function siblingHeader(implPath: string | null | undefined): string | null {
+	if (!implPath || isHeaderFile(implPath)) {
+		return null;
+	}
+	const dir = path.dirname(implPath);
+	const stem = fileStem(implPath);
+	const candidate = path.join(dir, `${stem}.clh`);
+	if (fs.existsSync(candidate)) {
+		return candidate;
+	}
+	return null;
+}
+
+export function collectSources(dir: string, files: string[] = []): string[] {
+	if (!fs.existsSync(dir)) {
+		return files;
+	}
+	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+		const full = path.join(dir, entry.name);
+		if (entry.isDirectory()) {
+			collectSources(full, files);
+		} else if (isSourceFile(entry.name)) {
+			files.push(full);
+		}
+	}
+	return files;
+}

package/src/clpp/postprocess.ts

@@ -0,0 +1,93 @@
+import { insertPreamble, MODULES, requireCluauppLib } from "../libs.js";
+import type { CompileArtifact } from "./contract.js";
+import { isTaggedScript } from "./paths.js";
+
+export type PostprocessOptions = {
+	relativeName: string;
+	outName: string;
+	srcDir?: string;
+	rootDir?: string;
+	strict?: boolean;
+	skipInit?: boolean;
+};
+
+function insertAfterHeader(luau: string, block: string): string {
+	const match = String(luau).match(/^(?:--[^\n]*\n)+/);
+	if (!match) {
+		return `${block}\n${luau}`;
+	}
+	const insertAt = match[0].length;
+	const rest = luau.slice(insertAt).replace(/^\n*/, "\n");
+	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);
+	});
+}
+
+function ensureReplicatedStorage(luau: string): string {
+	if (!luau.includes("CluauppLibs")) {
+		return luau;
+	}
+	if (/GetService\(\s*"ReplicatedStorage"\s*\)/.test(luau)) {
+		return luau;
+	}
+	return insertAfterHeader(luau, 'const ReplicatedStorage = game:GetService("ReplicatedStorage")');
+}
+
+function stripInitCall(luau: string): string {
+	return String(luau).replace(/\ninit\(\)\s*\n?$/m, "\n");
+}
+
+function ensureStrict(luau: string, strict?: boolean): string {
+	if (!strict || /^\s*--!strict\b/m.test(luau)) {
+		return luau;
+	}
+	if (luau.startsWith("--")) {
+		return `--!strict\n${luau}`;
+	}
+	return `--!strict\n${luau}`;
+}
+
+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];
+		if (!spec || seen.has(spec.bind)) {
+			continue;
+		}
+		seen.add(spec.bind);
+		specs.push(spec);
+	}
+	return specs;
+}
+
+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);
+	});
+}
+
+export function shouldSkipInit(fileName: string, hasSiblingHeader: boolean): boolean {
+	if (!hasSiblingHeader) {
+		return false;
+	}
+	return !isTaggedScript(fileName);
+}
+
+export function clppLuauToGame(artifact: CompileArtifact, options: PostprocessOptions): string {
+	let luau = rewriteClppLibs(artifact.luau || "");
+	luau = ensureReplicatedStorage(luau);
+	if (options.skipInit) {
+		luau = stripInitCall(luau);
+	}
+	luau = ensureStrict(luau, options.strict);
+	const missing = missingLibraries(luau, artifact.libraries);
+	if (missing.length > 0) {
+		luau = insertPreamble(luau, [], missing, options.outName);
+	}
+	return luau;
+}