cluaupp 1.0.0 → 1.4.0

package/src/native/index.ts

@@ -0,0 +1,509 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export type NativeEmit = {
+	headerRel: string;
+	headerPath: string;
+	header: string;
+	luauRel: string;
+	luau: string;
+};
+
+const IDENT = "[A-Za-z_][A-Za-z0-9_]*";
+
+function fail(file: string, line: number, message: string): never {
+	throw new Error(`cluaupp schema: ${file}:${line}: ${message}`);
+}
+
+function headerBanner(kind: string): string {
+	return `// cluaupp generated — do not edit. Change the .${kind} schema and run cluaupp build.\n#pragma once\n`;
+}
+
+function luauBanner(): string {
+	return `--!native\n--!optimize 2\n-- cluaupp generated — do not edit.\n`;
+}
+
+function posixRel(from: string, file: string): string {
+	return path.relative(from, file).replace(/\\/g, "/");
+}
+
+function emitPaths(rel: string, stem: string) {
+	const relDir = path.posix.dirname(rel);
+	const dir = relDir === "." ? "" : relDir;
+	const headerRel = dir ? `${dir}/${stem}.clh` : `${stem}.clh`;
+	const luauRel = dir ? `${dir}/${stem}.luau` : `${stem}.luau`;
+	return { headerRel, luauRel };
+}
+
+export function isNativeSchemaFile(fileName: string): boolean {
+	const ext = path.extname(fileName).toLowerCase();
+	return [".mint", ".bloom", ".helm", ".shift", ".hive", ".axiom"].includes(ext);
+}
+
+export function collectNativeSchemaFiles(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()) {
+			collectNativeSchemaFiles(full, files);
+		} else if (isNativeSchemaFile(entry.name)) {
+			files.push(full);
+		}
+	}
+	return files;
+}
+
+function parseOptName(source: string, file: string, defaultName: string): { name: string; lines: string[] } {
+	let name = defaultName;
+	const lines: string[] = [];
+	const raw = String(source).replace(/\r\n/g, "\n").split("\n");
+	for (let i = 0; i < raw.length; i++) {
+		const lineNo = i + 1;
+		const line = raw[i].trim();
+		if (!line || line.startsWith("#") || line.startsWith("//")) {
+			continue;
+		}
+		const opt = line.match(/^opt\s+name\s*=\s*(.+)$/i);
+		if (opt) {
+			const value = opt[1].trim().replace(/^["']|["']$/g, "");
+			if (!new RegExp(`^${IDENT}$`).test(value)) {
+				fail(file, lineNo, "opt name must be an identifier");
+			}
+			name = value;
+			continue;
+		}
+		lines.push(`${lineNo}\t${line}`);
+	}
+	return { name, lines };
+}
+
+function compileMint(source: string, file: string, defaultName: string, dir: string): NativeEmit {
+	const { name, lines } = parseOptName(source, file, defaultName);
+	if (lines.length === 0) {
+		fail(file, 1, "schema is empty — add a formatter");
+	}
+	const formatters: Array<{ name: string; kind: string; suffixes: string[]; fraction: number; grouping: boolean }> = [];
+	for (const tagged of lines) {
+		const [lineNoRaw, line] = tagged.split("\t");
+		const lineNo = Number(lineNoRaw);
+		const match = line.match(
+			new RegExp(
+				`^formatter\\s+(${IDENT})\\s+(compact|group|integer|percent|scientific)(?:\\s*\\((.*)\\))?(?:\\s+fraction\\s+(\\d+))?(?:\\s+grouping\\s+(on|off))?\\s*$`,
+				"i",
+			),
+		);
+		if (!match) {
+			fail(file, lineNo, `expected formatter Name compact("K","M") fraction 1`);
+		}
+		const suffixes = match[3]
+			? match[3]
+					.split(",")
+					.map((part) => part.trim().replace(/^["']|["']$/g, ""))
+					.filter(Boolean)
+			: ["K", "M", "B", "T"];
+		formatters.push({
+			name: match[1],
+			kind: match[2].toLowerCase(),
+			suffixes,
+			fraction: match[4] ? Number(match[4]) : 1,
+			grouping: (match[5] || "on").toLowerCase() !== "off",
+		});
+	}
+	const { headerRel, luauRel } = emitPaths(file, name);
+	const header = `${headerBanner("mint")}
+namespace ${name} {
+${formatters.map((item) => `\tstring ${item.name}(double value);`).join("\n")}
+}
+`;
+	const fns = formatters
+		.map((item) => {
+			if (item.kind === "compact") {
+				const table = item.suffixes.map((suffix, index) => `\t\t{ ${10 ** ((index + 1) * 3)}, "${suffix}" }`).join(",\n");
+				return `function ${name}.${item.name}(value: number): string
+	return Mint.Compact(value, {
+		Fraction = ${item.fraction},
+		Suffixes = {
+${table}
+		},
+	})
+end`;
+			}
+			if (item.kind === "percent") {
+				return `function ${name}.${item.name}(value: number): string
+	return Mint.Percent(value, ${item.fraction})
+end`;
+			}
+			if (item.kind === "integer") {
+				return `function ${name}.${item.name}(value: number): string
+	return Mint.Group(value, 0)
+end`;
+			}
+			return `function ${name}.${item.name}(value: number): string
+	return Mint.Group(value, ${item.fraction})
+end`;
+		})
+		.join("\n\n");
+	const luau = `${luauBanner()}local ReplicatedStorage = game:GetService("ReplicatedStorage")
+local Mint = require(ReplicatedStorage.CluauppLibs.Mint)
+local ${name} = {}
+
+${fns}
+
+return ${name}
+`;
+	return { headerRel, headerPath: headerRel, header, luauRel, luau };
+}
+
+function parseBloomGradient(body: string, file: string, lineNo: number): { stops: Array<{ t: number; hex: string }>; speed: number } {
+	const speedMatch = body.match(/\bspeed\s+([0-9.]+)\b/i);
+	const speed = speedMatch ? Number(speedMatch[1]) : 0.4;
+	const grad = body.match(/\bgradient((?:\s+[0-9.]+\s+#[0-9A-Fa-f]{6})+)/i);
+	if (!grad) {
+		fail(file, lineNo, `expected preset Shine { gradient 0 #FFC832 ... }`);
+	}
+	const stops: Array<{ t: number; hex: string }> = [];
+	for (const pair of grad[1].trim().matchAll(/([0-9.]+)\s+(#[0-9A-Fa-f]{6})/g)) {
+		stops.push({ t: Number(pair[1]), hex: pair[2] });
+	}
+	if (stops.length === 0) {
+		fail(file, lineNo, `expected preset Shine { gradient 0 #FFC832 ... }`);
+	}
+	return { stops, speed };
+}
+
+function compileBloom(source: string, file: string, defaultName: string): NativeEmit {
+	const { name, lines } = parseOptName(source, file, defaultName);
+	if (lines.length === 0) {
+		fail(file, 1, "schema is empty — add a preset");
+	}
+	const presets: Array<{ name: string; stops: Array<{ t: number; hex: string }>; speed: number }> = [];
+	for (let i = 0; i < lines.length; i++) {
+		const [lineNoRaw, line] = lines[i].split("\t");
+		const lineNo = Number(lineNoRaw);
+		const inline = line.match(
+			new RegExp(`^preset\\s+(${IDENT})\\s+gradient((?:\\s+[0-9.]+\\s+#[0-9A-Fa-f]{6})+)(?:\\s+speed\\s+([0-9.]+))?\\s*$`),
+		);
+		if (inline) {
+			presets.push({
+				name: inline[1],
+				...parseBloomGradient(`gradient${inline[2]}${inline[3] ? ` speed ${inline[3]}` : ""}`, file, lineNo),
+			});
+			continue;
+		}
+		const blockOpen = line.match(new RegExp(`^preset\\s+(${IDENT})\\s*\\{(.*)$`, "i"));
+		if (blockOpen) {
+			let body = blockOpen[2];
+			if (!body.includes("}")) {
+				i += 1;
+				while (i < lines.length) {
+					const inner = lines[i].split("\t").slice(1).join("\t");
+					if (inner.includes("}")) {
+						body += ` ${inner.replace(/\}.*$/, "")}`;
+						break;
+					}
+					body += ` ${inner}`;
+					i += 1;
+				}
+			} else {
+				body = body.replace(/\}.*$/, "");
+			}
+			presets.push({ name: blockOpen[1], ...parseBloomGradient(body, file, lineNo) });
+			continue;
+		}
+		fail(file, lineNo, `expected preset Shine { gradient 0 #FFC832 ... }`);
+	}
+	if (presets.length === 0 || presets.some((item) => item.stops.length === 0)) {
+		fail(file, 1, "schema is empty — add a preset with gradient stops");
+	}
+	const { headerRel, luauRel } = emitPaths(file, name);
+	const header = `${headerBanner("bloom")}
+#include <clpp/libs/bloom.clh>
+namespace ${name} {
+${presets.map((item) => `\tBloomHandle ${item.name}(GuiObject target);`).join("\n")}
+}
+`;
+	const fns = presets
+		.map((item) => {
+			const keys = item.stops
+				.map((stop) => `\t\tColorSequenceKeypoint.new(${stop.t}, Color3.fromHex("${stop.hex}"))`)
+				.join(",\n");
+			return `function ${name}.${item.name}(target: GuiObject)
+	return Bloom.Play(target, Bloom.Shine, {
+		Speed = ${item.speed},
+		Gradient = ColorSequence.new({
+${keys}
+		}),
+	})
+end`;
+		})
+		.join("\n\n");
+	const luau = `${luauBanner()}local ReplicatedStorage = game:GetService("ReplicatedStorage")
+local Bloom = require(ReplicatedStorage.CluauppLibs.Bloom)
+local ${name} = {}
+
+${fns}
+
+return ${name}
+`;
+	return { headerRel, headerPath: headerRel, header, luauRel, luau };
+}
+
+function compileHelm(source: string, file: string, defaultName: string): NativeEmit {
+	const { name, lines } = parseOptName(source, file, defaultName);
+	if (lines.length === 0) {
+		fail(file, 1, "schema is empty — add a command");
+	}
+	const commands: Array<{ name: string; args: Array<{ type: string; name: string }>; permission: string }> = [];
+	let id = 1;
+	for (const tagged of lines) {
+		const [lineNoRaw, line] = tagged.split("\t");
+		const lineNo = Number(lineNoRaw);
+		const match = line.match(
+			new RegExp(`^command\\s+(${IDENT})\\s*\\((.*)\\)\\s*(?:permission\\s+(${IDENT}))?\\s*$`, "i"),
+		);
+		if (!match) {
+			fail(file, lineNo, `expected command Give(Player target, i32 amount) permission Admin`);
+		}
+		const args: Array<{ type: string; name: string }> = [];
+		if (match[2].trim()) {
+			for (const part of match[2].split(",")) {
+				const piece = part.trim().match(new RegExp(`^(${IDENT})\\s+(${IDENT})$`));
+				if (!piece) {
+					fail(file, lineNo, `expected Type name in '${part}'`);
+				}
+				args.push({ type: piece[1], name: piece[2] });
+			}
+		}
+		commands.push({ name: match[1], args, permission: match[3] || "Admin" });
+		id += 1;
+	}
+	const { headerRel, luauRel } = emitPaths(file, name);
+	const headerFns = commands
+		.map((cmd) => {
+			const params = cmd.args.map((arg) => `${arg.type === "i32" ? "int" : arg.type} ${arg.name}`).join(", ");
+			return `\tvoid ${cmd.name}(${params});`;
+		})
+		.join("\n");
+	const header = `${headerBanner("helm")}
+namespace ${name} {
+${headerFns}
+}
+`;
+	const rows = commands
+		.map((cmd, index) => {
+			const argNames = cmd.args.map((arg) => arg.name).join(", ");
+			return `\t${cmd.name} = { Id = ${index + 1}, Permission = "${cmd.permission}", Args = { ${cmd.args
+				.map((arg) => `{ Type = "${arg.type}", Name = "${arg.name}" }`)
+				.join(", ")} } },`;
+		})
+		.join("\n");
+	const luau = `${luauBanner()}local ReplicatedStorage = game:GetService("ReplicatedStorage")
+local Helm = require(ReplicatedStorage.CluauppLibs.Helm)
+local ${name} = {
+${rows}
+}
+
+function ${name}.Open(player: Player)
+	return Helm.Open(player, ${name})
+end
+
+return ${name}
+`;
+	return { headerRel, headerPath: headerRel, header, luauRel, luau };
+}
+
+function compileShift(source: string, file: string, defaultName: string): NativeEmit {
+	const { name, lines } = parseOptName(source, file, defaultName);
+	const states: string[] = [];
+	const parents: Record<string, string> = {};
+	const transitions: Array<{ from: string; to: string; guard: string }> = [];
+	for (const tagged of lines) {
+		const [lineNoRaw, line] = tagged.split("\t");
+		const lineNo = Number(lineNoRaw);
+		const state = line.match(new RegExp(`^state\\s+(${IDENT})(?:\\s+parent\\s+(${IDENT}))?\\s*$`, "i"));
+		if (state) {
+			states.push(state[1]);
+			if (state[2]) {
+				parents[state[1]] = state[2];
+			}
+			continue;
+		}
+		const edge = line.match(new RegExp(`^(${IDENT})\\s*->\\s*(${IDENT})(?:\\s+when\\s+(${IDENT}))?\\s*$`));
+		if (edge) {
+			transitions.push({ from: edge[1], to: edge[2], guard: edge[3] || "" });
+			continue;
+		}
+		const machine = line.match(new RegExp(`^machine\\s+(${IDENT})\\s*$`, "i"));
+		if (machine) {
+			continue;
+		}
+		fail(file, lineNo, `expected state Idle or Idle -> Chase when SeePlayer`);
+	}
+	if (states.length === 0) {
+		fail(file, 1, "schema is empty — add a state");
+	}
+	if (states.length > 255) {
+		fail(file, 1, "too many states (max 255)");
+	}
+	const { headerRel, luauRel } = emitPaths(file, name);
+	const header = `${headerBanner("shift")}
+#include <clpp/libs/shift.clh>
+namespace ${name} {
+${states.map((state, index) => `\tconst int ${state} = ${index};`).join("\n")}
+	ShiftMachine New();
+}
+`;
+	const ids = states.map((state, index) => `\t${state} = ${index},`).join("\n");
+	const edges = transitions
+		.map((edge) => `\t{ From = "${edge.from}", To = "${edge.to}", Guard = "${edge.guard}" },`)
+		.join("\n");
+	const luau = `${luauBanner()}local ReplicatedStorage = game:GetService("ReplicatedStorage")
+local Shift = require(ReplicatedStorage.CluauppLibs.Shift)
+local ${name} = {
+	Ids = {
+${ids}
+	},
+	Parents = {
+${Object.entries(parents)
+		.map(([child, parent]) => `\t\t${child} = "${parent}",`)
+		.join("\n")}
+	},
+	Transitions = {
+${edges}
+	},
+}
+
+function ${name}.New()
+	return Shift.New(${name}.Ids, ${name}.Transitions, ${name}.Parents)
+end
+
+return ${name}
+`;
+	return { headerRel, headerPath: headerRel, header, luauRel, luau };
+}
+
+function compileHive(source: string, file: string, defaultName: string): NativeEmit {
+	const { name, lines } = parseOptName(source, file, defaultName);
+	const components: Array<{ name: string; fields: Array<{ type: string; name: string }> }> = [];
+	for (const tagged of lines) {
+		const [lineNoRaw, line] = tagged.split("\t");
+		const lineNo = Number(lineNoRaw);
+		const match = line.match(new RegExp(`^component\\s+(${IDENT})\\s*\\{(.*)\\}\\s*$`, "i"));
+		if (!match) {
+			fail(file, lineNo, `expected component Health { i32 current, i32 max }`);
+		}
+		const fields: Array<{ type: string; name: string }> = [];
+		if (match[2].trim()) {
+			for (const part of match[2].split(",")) {
+				const piece = part.trim().match(new RegExp(`^(${IDENT})\\s+(${IDENT})$`));
+				if (!piece) {
+					fail(file, lineNo, `expected Type name in '${part}'`);
+				}
+				fields.push({ type: piece[1], name: piece[2] });
+			}
+		}
+		components.push({ name: match[1], fields });
+	}
+	if (components.length === 0) {
+		fail(file, 1, "schema is empty — add a component");
+	}
+	if (components.length > 255) {
+		fail(file, 1, "too many components (max 255)");
+	}
+	const { headerRel, luauRel } = emitPaths(file, name);
+	const header = `${headerBanner("hive")}
+#include <clpp/libs/hive.clh>
+namespace ${name} {
+${components.map((item, index) => `\tconst int ${item.name} = ${index + 1};`).join("\n")}
+	HiveWorld New();
+}
+`;
+	const rows = components
+		.map(
+			(item, index) =>
+				`\t${item.name} = { Id = ${index + 1}, Fields = { ${item.fields
+					.map((field) => `{ Type = "${field.type}", Name = "${field.name}" }`)
+					.join(", ")} } },`,
+		)
+		.join("\n");
+	const luau = `${luauBanner()}local ReplicatedStorage = game:GetService("ReplicatedStorage")
+local Hive = require(ReplicatedStorage.CluauppLibs.Hive)
+local ${name} = {
+${rows}
+}
+
+function ${name}.New()
+	return Hive.World(${name})
+end
+
+return ${name}
+`;
+	return { headerRel, headerPath: headerRel, header, luauRel, luau };
+}
+
+function compileAxiom(source: string, file: string, defaultName: string): NativeEmit {
+	const { name, lines } = parseOptName(source, file, defaultName);
+	const groups: string[] = [];
+	for (const tagged of lines) {
+		const [lineNoRaw, line] = tagged.split("\t");
+		const lineNo = Number(lineNoRaw);
+		const match = line.match(new RegExp(`^group\\s+(${IDENT})\\s*$`, "i"));
+		if (!match) {
+			fail(file, lineNo, `expected group Scalar`);
+		}
+		groups.push(match[1]);
+	}
+	if (groups.length === 0) {
+		fail(file, 1, "schema is empty — add group Scalar");
+	}
+	const { headerRel, luauRel } = emitPaths(file, name);
+	const header = `${headerBanner("axiom")}
+#include <clpp/libs/axiom.clh>
+namespace ${name} {
+${groups.map((group) => `\t// group ${group}`).join("\n")}
+}
+`;
+	const luau = `${luauBanner()}local ReplicatedStorage = game:GetService("ReplicatedStorage")
+local Axiom = require(ReplicatedStorage.CluauppLibs.Axiom)
+local ${name} = Axiom.Select({ ${groups.map((group) => `"${group}"`).join(", ")} })
+-- out/ only binds groups: ${groups.join(", ")}
+return ${name}
+`;
+	return { headerRel, headerPath: headerRel, header, luauRel, luau };
+}
+
+export function compileNativeSchemaFile(file: string, srcDir: string): NativeEmit {
+	const source = fs.readFileSync(file, "utf8");
+	const rel = posixRel(srcDir, file);
+	const stem = path.basename(file, path.extname(file));
+	const ext = path.extname(file).toLowerCase();
+	const dir = path.posix.dirname(rel);
+	if (ext === ".mint") {
+		return compileMint(source, rel, stem, dir);
+	}
+	if (ext === ".bloom") {
+		return compileBloom(source, rel, stem);
+	}
+	if (ext === ".helm") {
+		return compileHelm(source, rel, stem);
+	}
+	if (ext === ".shift") {
+		return compileShift(source, rel, stem);
+	}
+	if (ext === ".hive") {
+		return compileHive(source, rel, stem);
+	}
+	if (ext === ".axiom") {
+		return compileAxiom(source, rel, stem);
+	}
+	throw new Error(`cluaupp schema: unknown extension ${ext}`);
+}
+
+export const compileMintSchema = compileMint;
+export const compileBloomSchema = compileBloom;
+export const compileHelmSchema = compileHelm;
+export const compileShiftSchema = compileShift;
+export const compileHiveSchema = compileHive;
+export const compileAxiomSchema = compileAxiom;

package/src/transpile.ts

@@ -1,6 +1,6 @@
 import path from "node:path";
 import type { CompileOptions, CompileServiceResult } from "./types.js";
-import { compileService } from "./compile.js";
+import { compileService, compileServiceAsync } from "./compile.js";
 import type { RojoMapper } from "./utils/rojo-mapper.js";
 
 export function transpileSource(
@@ -12,6 +12,15 @@ export function transpileSource(
 	return compileService(source, fileName, options);
 }
 
+export function transpileSourceAsync(
+	source: string,
+	fileName: string,
+	options: CompileOptions,
+	_mapper?: RojoMapper,
+): Promise<CompileServiceResult> {
+	return compileServiceAsync(source, fileName, options);
+}
+
 export function outputNameFor(inputFile: string, outputPath: string): string {
 	if (/\.luau$/i.test(outputPath)) {
 		return outputPath;

package/src/types.ts

@@ -53,6 +53,7 @@ export interface BuildOptions {
 	format?: boolean;
 	analyze?: boolean;
 	rojo?: string;
+	strict?: boolean;
 }
 
 export interface BuildResult {