cluaupp 1.5.2 → 2.0.0-beta.1

package/src/compiler/emit/luau-types.ts

@@ -0,0 +1,143 @@
+/** CL++ types → Luau type annotations. `null` means "omit the annotation" (let Luau infer). */
+
+import { prune, type Type } from "../types.js";
+
+export interface TypeNaming {
+	/** Luau name for a struct type (`Fighter`, `Combat.Fighter`), or null when it cannot be named here. */
+	struct(id: string): string | null;
+	/** Luau type of a payload enum, or null for plain enums (numbers). */
+	enumType(id: string): string | null;
+}
+
+export function luauType(t: Type, names: TypeNaming, depth = 0): string | null {
+	const p = prune(t);
+	if (depth > 8) {
+		return null;
+	}
+	const sub = (x: Type) => luauType(x, names, depth + 1);
+	switch (p.k) {
+		case "int":
+		case "float":
+			return "number";
+		case "bool":
+			return "boolean";
+		case "string":
+			return "string";
+		case "lit":
+			return typeof p.value === "string" ? JSON.stringify(p.value) : typeof p.value === "boolean" ? String(p.value) : "number";
+		case "null":
+			return "nil";
+		case "void":
+			return "()";
+		case "any":
+			return "any";
+		case "buffer":
+			return "buffer";
+		case "thread":
+			return "thread";
+		case "list": {
+			const e = sub(p.elem);
+			return e ? `{ ${e} }` : null;
+		}
+		case "dict": {
+			const k = sub(p.key);
+			const v = sub(p.value);
+			return k && v ? `{ [${k}]: ${v} }` : null;
+		}
+		case "table": {
+			const parts: string[] = [];
+			for (const [k, v] of Object.entries(p.fields)) {
+				const vt = sub(v);
+				if (!vt) {
+					return null;
+				}
+				parts.push(`${/^[A-Za-z_][A-Za-z0-9_]*$/.test(k) ? k : `[${JSON.stringify(k)}]`}: ${vt}`);
+			}
+			return `{ ${parts.join(", ")} }`;
+		}
+		case "tuple": {
+			const parts = p.elems.map(sub);
+			return parts.every(Boolean) ? `(${parts.join(", ")})` : null;
+		}
+		case "struct": {
+			const base = names.struct(p.id);
+			if (!base) {
+				return null;
+			}
+			if (p.args.length) {
+				const args = p.args.map(sub);
+				return args.every(Boolean) ? `${base}<${args.join(", ")}>` : null;
+			}
+			return base;
+		}
+		case "enum":
+			return names.enumType(p.id) ?? "number";
+		case "variant": {
+			const parts = p.alternatives.map(sub);
+			return parts.every(Boolean) && parts.length ? [...new Set(parts)].join(" | ") : null;
+		}
+		case "option": {
+			const inner = sub(p.inner);
+			if (!inner) {
+				return null;
+			}
+			if (inner === "any") {
+				return "any";
+			}
+			return /->|\|/.test(inner) ? `(${inner})?` : `${inner}?`;
+		}
+		case "result": {
+			const ok = sub(p.ok) ?? "any";
+			const err = sub(p.err) ?? "any";
+			const opt = (x: string) => (x === "any" ? x : /->|\|/.test(x) ? `(${x})?` : `${x}?`);
+			return `{ ok: boolean, value: ${opt(ok)}, error: ${opt(err)} }`;
+		}
+		case "task": {
+			const r = sub(p.result);
+			return `ClTask<${r && r !== "()" ? r : "any"}>`;
+		}
+		case "func": {
+			const params = p.params.map((x) => {
+				const pt = sub(x.type);
+				return pt ? (x.optional && !pt.endsWith("?") ? (/->|\|/.test(pt) ? `(${pt})?` : `${pt}?`) : pt) : null;
+			});
+			if (!params.every(Boolean)) {
+				return null;
+			}
+			if (p.variadic) {
+				const v = sub(p.variadic);
+				params.push(`...${v ?? "any"}`);
+			}
+			const ret = prune(p.ret).k === "void" ? "()" : sub(p.ret);
+			if (!ret) {
+				return null;
+			}
+			return `(${params.join(", ")}) -> ${ret}`;
+		}
+		case "union": {
+			const parts = p.members.map(sub);
+			return parts.every(Boolean) ? [...new Set(parts)].join(" | ") : null;
+		}
+		case "param":
+			return p.name;
+		case "instance":
+			return p.cls === "Object" ? "Instance" : p.cls;
+		case "datatype":
+			if (p.name === "__Mutex") {
+				return "ClMutex";
+			}
+			return p.name;
+		case "rbxEnumItem":
+			return p.enumName === "*" ? "EnumItem" : `Enum.${p.enumName}`;
+		case "rbxEnum":
+			return "Enum";
+		case "rbxEnums":
+			return "Enums";
+		case "rbxSignal":
+			return "RBXScriptSignal";
+		case "clSignal":
+			return null;
+		default:
+			return null;
+	}
+}

package/src/compiler/emit/names.ts

@@ -0,0 +1,130 @@
+/** Luau-safe identifiers: keywords, globals the output relies on, and non-ASCII names. */
+
+import type { RobloxApi } from "../roblox/api.js";
+
+export const LUAU_KEYWORDS = new Set([
+	"and", "break", "do", "else", "elseif", "end", "false", "for", "function", "if", "in", "local", "nil", "not", "or",
+	"repeat", "return", "then", "true", "until", "while",
+]);
+
+/** Names emitted code may reference as globals; user symbols are renamed away from them. */
+export function reservedGlobals(api: RobloxApi): Set<string> {
+	const out = new Set<string>([
+		"self", "continue", "type", "typeof", "export",
+		"game", "workspace", "script", "plugin", "shared", "Enum", "Instance", "Vector3", "Vector2",
+		"print", "warn", "error", "assert", "tostring", "tonumber", "select", "pairs", "ipairs", "next", "pcall",
+		"xpcall", "require", "setmetatable", "getmetatable", "rawget", "rawset", "rawequal", "rawlen", "unpack",
+		"tick", "time", "wait", "delay", "spawn",
+	]);
+	for (const name of Object.keys(api.libraries)) {
+		out.add(name);
+	}
+	for (const name of Object.keys(api.datatypes)) {
+		out.add(name);
+	}
+	return out;
+}
+
+const LUAU_BUILTIN_TYPES = new Set(["number", "string", "boolean", "any", "unknown", "never", "nil", "thread", "buffer", "userdata", "vector", "Enum", "EnumItem", "Instance"]);
+
+/** Names that may not be used for an emitted type alias. */
+export function isReservedTypeName(api: RobloxApi, name: string): boolean {
+	return LUAU_BUILTIN_TYPES.has(name) || api.hasClass(name) || api.hasDatatype(name) || name === "RBXScriptSignal" || name === "RBXScriptConnection" || name.startsWith("Cl");
+}
+
+export function sanitizeIdentifier(name: string): string {
+	if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+		return name;
+	}
+	let out = "";
+	for (const ch of name) {
+		if (/[A-Za-z0-9_]/.test(ch)) {
+			out += ch;
+		} else {
+			out += `_${ch.codePointAt(0)!.toString(16)}`;
+		}
+	}
+	return /^[0-9]/.test(out) ? `_${out}` : out;
+}
+
+export function isIdentifier(name: string): boolean {
+	return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) && !LUAU_KEYWORDS.has(name);
+}
+
+/** Luau string literal with the shortest correct escaping. */
+export function luauString(value: string): string {
+	let out = '"';
+	for (const ch of value) {
+		const code = ch.codePointAt(0)!;
+		switch (ch) {
+			case '"':
+				out += '\\"';
+				break;
+			case "\\":
+				out += "\\\\";
+				break;
+			case "\n":
+				out += "\\n";
+				break;
+			case "\r":
+				out += "\\r";
+				break;
+			case "\t":
+				out += "\\t";
+				break;
+			case "\0":
+				out += "\\0";
+				break;
+			default:
+				out += code < 32 || code === 127 ? `\\${code}` : ch;
+		}
+	}
+	return `${out}"`;
+}
+
+/** Escape literal text inside a Luau interpolated string. */
+export function interpolationText(value: string): string {
+	let out = "";
+	for (const ch of value) {
+		switch (ch) {
+			case "`":
+				out += "\\`";
+				break;
+			case "{":
+				out += "\\{";
+				break;
+			case "}":
+				out += "\\}";
+				break;
+			case "\\":
+				out += "\\\\";
+				break;
+			case "\n":
+				out += "\\n";
+				break;
+			case "\r":
+				out += "\\r";
+				break;
+			case "\t":
+				out += "\\t";
+				break;
+			default:
+				out += ch;
+		}
+	}
+	return out;
+}
+
+/** Number literal: integers stay integral, floats use the shortest round-trip form. */
+export function luauNumber(value: number): string {
+	if (Number.isNaN(value)) {
+		return "(0 / 0)";
+	}
+	if (!Number.isFinite(value)) {
+		return value > 0 ? "math.huge" : "-math.huge";
+	}
+	if (Number.isInteger(value) && Math.abs(value) < 2 ** 53) {
+		return String(value);
+	}
+	return String(value);
+}

package/src/compiler/emit/runtime.ts

@@ -0,0 +1,438 @@
+/**
+ * File-local runtime helpers. Only the helpers a file uses are emitted (with their dependencies),
+ * as `local function`s so `--!optimize 2` can inline them. No shared runtime module, no require.
+ */
+
+export interface Helper {
+	/** Luau source (one or more top-level statements). */
+	code: string;
+	deps?: string[];
+	/** Type aliases the helper declares. */
+	types?: string;
+}
+
+export const HELPERS: Record<string, Helper> = {
+	__cl_idiv: {
+		code: `local function __cl_idiv(a: number, b: number): number
+	local q = a / b
+	return if q < 0 then math.ceil(q) else math.floor(q)
+end`,
+	},
+	__cl_trunc: {
+		code: `local function __cl_trunc(x: number): number
+	return if x < 0 then math.ceil(x) else math.floor(x)
+end`,
+	},
+	__cl_toint: {
+		deps: ["__cl_tonumber", "__cl_trunc"],
+		code: `local function __cl_toint(text: string): number
+	return __cl_trunc(__cl_tonumber(text))
+end`,
+	},
+	__cl_tonumber: {
+		code: `local function __cl_tonumber(text: string): number
+	local n = tonumber(text)
+	if n == nil then
+		error(\`not a number: "{text}"\`, 2)
+	end
+	return n
+end`,
+	},
+	__cl_strlen: {
+		code: `local function __cl_strlen(s: string): number
+	return utf8.len(s) or #s
+end`,
+	},
+	__cl_char: {
+		code: `local function __cl_char(s: string, i: number): string
+	local from = utf8.offset(s, i + 1)
+	if from == nil or from > #s then
+		error(\`index out of range: {i} (size {utf8.len(s) or #s})\`, 2)
+	end
+	local to = (utf8.offset(s, i + 2) or #s + 1) - 1
+	return string.sub(s, from, to)
+end`,
+	},
+	__cl_slice: {
+		code: `local function __cl_slice<T>(x: T, a: number, b: number): T
+	if type(x) == "string" then
+		local s = x :: any
+		local from = utf8.offset(s, a + 1) or #s + 1
+		local to = (utf8.offset(s, b + 1) or #s + 1) - 1
+		return string.sub(s, from, to) :: any
+	end
+	return table.move(x :: any, a + 1, b, 1, {}) :: any
+end`,
+	},
+	__cl_count: {
+		code: `local function __cl_count(t: { [any]: any }): number
+	local n = 0
+	for _ in t do
+		n += 1
+	end
+	return n
+end`,
+	},
+	__cl_take: {
+		code: `local function __cl_take<K, V>(t: { [K]: V }, key: K): V
+	local value = t[key]
+	t[key] = nil
+	return value
+end`,
+	},
+	__cl_sorted: {
+		code: `local function __cl_sorted<T>(list: { T }): { T }
+	local out = table.clone(list)
+	table.sort(out :: any)
+	return out
+end`,
+	},
+	__cl_str: {
+		code: `local function __cl_str(value: any): string
+	local kind = typeof(value)
+	if kind == "string" then
+		return value
+	elseif kind == "boolean" or kind == "number" or kind == "nil" then
+		return if value == nil then "null" else tostring(value)
+	elseif kind == "Vector3" then
+		return \`({value.X}, {value.Y}, {value.Z})\`
+	elseif kind == "Vector2" then
+		return \`({value.X}, {value.Y})\`
+	elseif kind ~= "table" then
+		return tostring(value)
+	end
+	local meta = getmetatable(value)
+	local fields = if type(meta) == "table" then rawget(meta, "__fields") else nil
+	local parts = {}
+	local function item(v: any): string
+		return if type(v) == "string" then \`"{v}"\` else __cl_str(v)
+	end
+	if fields then
+		for i, name in fields do
+			parts[i] = __cl_str(value[name])
+		end
+		return "(" .. table.concat(parts, ", ") .. ")"
+	end
+	if rawget(value, "tag") ~= nil and type(rawget(value, "tag")) == "number" then
+		return if value.value ~= nil then __cl_str(value.value) else tostring(value.tag)
+	end
+	if #value > 0 or next(value) == nil then
+		for i, v in value do
+			parts[i] = item(v)
+		end
+		return "[" .. table.concat(parts, ", ") .. "]"
+	end
+	for k, v in value do
+		table.insert(parts, \`{k}: {__cl_str(v)}\`)
+	end
+	return "{" .. table.concat(parts, ", ") .. "}"
+end`,
+	},
+	__cl_copy: {
+		code: `local function __cl_copy<T>(value: T): T
+	if type(value) ~= "table" then
+		return value
+	end
+	local source = value :: any
+	local meta = getmetatable(source)
+	if meta ~= nil and (type(meta) ~= "table" or rawget(meta, "__fields") == nil) then
+		return value -- foreign object: shared by reference
+	end
+	local out = table.clone(source)
+	for k, v in out do
+		if type(v) == "table" then
+			out[k] = __cl_copy(v)
+		end
+	end
+	if meta ~= nil then
+		setmetatable(out, meta)
+	end
+	return out :: any
+end`,
+	},
+	__cl_eq: {
+		code: `local function __cl_eq(a: any, b: any): boolean
+	if a == b then
+		return true
+	end
+	if type(a) ~= "table" or type(b) ~= "table" or getmetatable(a) ~= getmetatable(b) then
+		return false
+	end
+	for k, v in a do
+		if not __cl_eq(v, b[k]) then
+			return false
+		end
+	end
+	for k in b do
+		if a[k] == nil then
+			return false
+		end
+	end
+	return true
+end`,
+	},
+	__cl_findeq: {
+		deps: ["__cl_eq"],
+		code: `local function __cl_findeq(list: { any }, value: any): number
+	for i, v in list do
+		if __cl_eq(v, value) then
+			return i - 1
+		end
+	end
+	return -1
+end`,
+	},
+	__cl_task: {
+		types: `type ClTask<T> = { done: boolean, ok: boolean, value: T?, err: any, waiting: { thread } }`,
+		code: `local function __cl_spawn<T>(work: () -> T): ClTask<T>
+	local job: ClTask<T> = { done = false, ok = true, value = nil, err = nil, waiting = {} }
+	task.spawn(function()
+		local ok, result = pcall(work)
+		job.ok = ok
+		if ok then
+			job.value = result
+		else
+			job.err = result
+		end
+		job.done = true
+		for _, waiter in job.waiting do
+			task.spawn(waiter)
+		end
+	end)
+	return job
+end
+
+local function __cl_await<T>(job: ClTask<T>): T
+	if not job.done then
+		table.insert(job.waiting, coroutine.running())
+		coroutine.yield()
+	end
+	if not job.ok then
+		error(job.err, 0)
+	end
+	return job.value :: T
+end`,
+	},
+	__cl_parallel: {
+		deps: ["__cl_task"],
+		code: `local function __cl_parallel<T>(jobs: { ClTask<T> }): { T }
+	local results = table.create(#jobs)
+	for i, job in jobs do
+		results[i] = __cl_await(job)
+	end
+	return results
+end`,
+	},
+	__cl_mutex: {
+		types: `type ClMutex = { locked: boolean, queue: { thread } }`,
+		code: `local function __cl_mutex(): ClMutex
+	return { locked = false, queue = {} }
+end
+
+local function __cl_lock(m: ClMutex)
+	if m.locked then
+		table.insert(m.queue, coroutine.running())
+		coroutine.yield()
+	end
+	m.locked = true
+end
+
+local function __cl_unlock(m: ClMutex)
+	local nextThread = table.remove(m.queue, 1)
+	if nextThread then
+		task.spawn(nextThread)
+	else
+		m.locked = false
+	end
+end`,
+	},
+	__cl_errmsg: {
+		code: `local function __cl_errmsg(err: any): string
+	if type(err) == "string" then
+		return (string.gsub(err, "^[^:]+:%d+: ", ""))
+	end
+	return tostring(err)
+end`,
+	},
+	trim: {
+		code: `local function __cl_trim(text: string): string
+	return (string.match(text, "^%s*(.-)%s*$")) or ""
+end`,
+	},
+	replace: {
+		code: `local function __cl_replace(text: string, target: string, replacement: string): string
+	if target == "" then
+		return text
+	end
+	local out = {}
+	local start = 1
+	while true do
+		local i, j = string.find(text, target, start, true)
+		if i == nil or j == nil then
+			break
+		end
+		table.insert(out, string.sub(text, start, i - 1))
+		table.insert(out, replacement)
+		start = j + 1
+	end
+	table.insert(out, string.sub(text, start))
+	return table.concat(out)
+end`,
+	},
+	endsWith: {
+		code: `local function __cl_endsWith(text: string, part: string): boolean
+	return part == "" or string.sub(text, -#part) == part
+end`,
+	},
+	toNumber: {
+		deps: ["__cl_tonumber"],
+		code: "",
+	},
+	indexOf: {
+		code: `local function __cl_indexOf(text: string, part: string): number
+	local at = string.find(text, part, 1, true)
+	if at == nil then
+		return -1
+	end
+	return (utf8.len(string.sub(text, 1, at - 1)) or (at - 1))
+end`,
+	},
+	joinAll: {
+		deps: ["__cl_str"],
+		code: `local function __cl_joinAll(parts: { any }, separator: string): string
+	local out = table.create(#parts)
+	for i, part in parts do
+		out[i] = __cl_str(part)
+	end
+	return table.concat(out, separator)
+end`,
+	},
+	jsonParse: {
+		code: `local function __cl_jsonParse(text: string): any
+	return game:GetService("HttpService"):JSONDecode(text)
+end`,
+	},
+	jsonValid: {
+		code: `local function __cl_jsonValid(text: string): boolean
+	return (pcall(function()
+		return game:GetService("HttpService"):JSONDecode(text)
+	end))
+end`,
+	},
+	jsonStringify: {
+		code: `local function __cl_jsonStringify(value: any): string
+	return game:GetService("HttpService"):JSONEncode(value)
+end`,
+	},
+	jsonPretty: {
+		deps: ["jsonStringify"],
+		code: `local function __cl_jsonPretty(value: any): string
+	local text = __cl_jsonStringify(value)
+	local out, depth, inString = {}, 0, false
+	for i = 1, #text do
+		local ch = string.sub(text, i, i)
+		if ch == '"' and string.sub(text, i - 1, i - 1) ~= "\\\\" then
+			inString = not inString
+		end
+		if inString then
+			table.insert(out, ch)
+		elseif ch == "{" or ch == "[" then
+			depth += 1
+			table.insert(out, ch .. "\\n" .. string.rep("  ", depth))
+		elseif ch == "}" or ch == "]" then
+			depth -= 1
+			table.insert(out, "\\n" .. string.rep("  ", depth) .. ch)
+		elseif ch == "," then
+			table.insert(out, ",\\n" .. string.rep("  ", depth))
+		elseif ch == ":" then
+			table.insert(out, ": ")
+		else
+			table.insert(out, ch)
+		end
+	end
+	return table.concat(out)
+end`,
+	},
+	jsonGet: {
+		code: `local function __cl_jsonGet(value: any, path: string): any
+	local node = value
+	for key in string.gmatch(path, "[^%.]+") do
+		if type(node) ~= "table" then
+			return nil
+		end
+		local index = tonumber(key)
+		node = if index ~= nil and node[index + 1] ~= nil then node[index + 1] else node[key]
+	end
+	return node
+end`,
+	},
+	jsonHas: {
+		deps: ["jsonGet"],
+		code: `local function __cl_jsonHas(value: any, path: string): boolean
+	return __cl_jsonGet(value, path) ~= nil
+end`,
+	},
+	jsonSet: {
+		code: `local function __cl_jsonSet(target: any, key: string, value: any): any
+	local copy = if type(target) == "table" then table.clone(target) else {}
+	local index = tonumber(key)
+	if index ~= nil and #copy > 0 then
+		copy[index + 1] = value
+	else
+		copy[key] = value
+	end
+	return copy
+end`,
+	},
+	jsonKeys: {
+		code: `local function __cl_jsonKeys(object: any): { string }
+	local keys = {}
+	if type(object) == "table" then
+		for k in object do
+			table.insert(keys, tostring(k))
+		end
+	end
+	return keys
+end`,
+	},
+	urlHost: {
+		code: `local function __cl_urlHost(url: string): string
+	local rest = string.match(url, "^%a[%w+.-]*://(.*)$") or url
+	local host = string.match(rest, "^[^/?#]*") or ""
+	host = string.match(host, "^[^@]*@(.*)$") or host
+	return (string.match(host, "^([^:]*)")) or host
+end`,
+	},
+};
+
+/** Luau name a std helper is called by. */
+export function helperFunctionName(helper: string): string {
+	if (helper === "toNumber") {
+		return "__cl_tonumber";
+	}
+	return helper.startsWith("__cl_") ? helper : `__cl_${helper}`;
+}
+
+/** Ordered, de-duplicated helper set including dependencies. */
+export function resolveHelpers(used: Iterable<string>): string[] {
+	const out: string[] = [];
+	const seen = new Set<string>();
+	const visit = (name: string) => {
+		if (seen.has(name)) {
+			return;
+		}
+		seen.add(name);
+		const h = HELPERS[name];
+		if (!h) {
+			return;
+		}
+		for (const d of h.deps || []) {
+			visit(d);
+		}
+		out.push(name);
+	};
+	for (const u of used) {
+		visit(u);
+	}
+	return out;
+}