cluaupp 1.5.2 → 2.0.0-beta.1

package/src/compiler/roblox/api.ts

@@ -0,0 +1,408 @@
+/**
+ * `@clpp.roblox` — the typed Roblox API surface (classes, datatypes, enums, services, globals,
+ * libraries) as the checker sees it. Loaded once from `api/roblox/surface.json`.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import type { LFn, LType, RobloxSurface, SurfaceClass, SurfaceDatatype, SurfaceMember, SurfaceStatic } from "../../api/surface/model.js";
+import { projectRoot } from "../../package-info.js";
+import { T, type FnParam, type Type } from "../types.js";
+
+/** Library functions whose `number` results are always integers on Roblox. */
+const INT_RESULTS = new Set([
+	"math.floor", "math.ceil", "math.round", "math.sign", "string.len", "string.byte", "utf8.len", "utf8.codepoint",
+	"os.time", "buffer.len", "buffer.readi8", "buffer.readu8", "buffer.readi16", "buffer.readu16", "buffer.readi32",
+	"buffer.readu32", "buffer.readbits", "table.find", "table.maxn", "bit32.band", "bit32.bor", "bit32.bxor", "bit32.bnot",
+	"bit32.lshift", "bit32.rshift", "bit32.arshift", "bit32.lrotate", "bit32.rrotate", "bit32.extract", "bit32.replace",
+	"bit32.countlz", "bit32.countrz", "bit32.byteswap", "rawlen",
+]);
+
+export interface MemberHit {
+	member: SurfaceMember;
+	owner: string;
+}
+
+export class RobloxApi {
+	readonly classes: Record<string, SurfaceClass>;
+	readonly datatypes: Record<string, SurfaceDatatype>;
+	readonly enums: RobloxSurface["enums"];
+	readonly globals: RobloxSurface["globals"];
+	readonly libraries: RobloxSurface["libraries"];
+	readonly aliases: RobloxSurface["aliases"];
+	readonly services: string[];
+	private readonly memberCache = new Map<string, Map<string, MemberHit>>();
+	private readonly convertCache = new WeakMap<object, Type>();
+
+	constructor(readonly surface: RobloxSurface) {
+		this.classes = surface.classes;
+		this.datatypes = surface.datatypes;
+		this.enums = surface.enums;
+		this.globals = surface.globals;
+		this.libraries = surface.libraries;
+		this.aliases = surface.aliases;
+		this.services = Object.values(surface.classes)
+			.filter((c) => c.service)
+			.map((c) => c.name);
+	}
+
+	hasClass(name: string): boolean {
+		return Object.prototype.hasOwnProperty.call(this.classes, name);
+	}
+
+	hasDatatype(name: string): boolean {
+		return Object.prototype.hasOwnProperty.call(this.datatypes, name);
+	}
+
+	hasEnum(name: string): boolean {
+		return Object.prototype.hasOwnProperty.call(this.enums, name);
+	}
+
+	isService(name: string): boolean {
+		return this.hasClass(name) && this.classes[name].service;
+	}
+
+	isA(cls: string, base: string): boolean {
+		let cur: string | null = cls;
+		let guard = 0;
+		while (cur && guard++ < 64) {
+			if (cur === base) {
+				return true;
+			}
+			cur = this.classes[cur]?.superclass ?? null;
+		}
+		return false;
+	}
+
+	/** All members visible on a class (own first, then inherited). */
+	members(cls: string): Map<string, MemberHit> {
+		const cached = this.memberCache.get(cls);
+		if (cached) {
+			return cached;
+		}
+		const out = new Map<string, MemberHit>();
+		let cur: string | null = cls;
+		let guard = 0;
+		while (cur && guard++ < 64) {
+			const c: SurfaceClass | undefined = this.classes[cur];
+			if (!c) {
+				break;
+			}
+			for (const [name, member] of Object.entries(c.members)) {
+				if (!out.has(name)) {
+					out.set(name, { member, owner: cur });
+				}
+			}
+			cur = c.superclass;
+		}
+		this.memberCache.set(cls, out);
+		return out;
+	}
+
+	member(cls: string, name: string): MemberHit | null {
+		return this.members(cls).get(name) ?? null;
+	}
+
+	datatypeMember(name: string, member: string): SurfaceMember | null {
+		return this.datatypes[name]?.members[member] ?? null;
+	}
+
+	datatypeStatic(name: string, member: string): SurfaceStatic | null {
+		return this.datatypes[name]?.statics[member] ?? null;
+	}
+
+	library(name: string): Record<string, SurfaceStatic> | null {
+		return this.libraries[name] ?? null;
+	}
+
+	// ---------- LType → Type ----------
+
+	convert(lt: LType, context?: string): Type {
+		const cached = this.convertCache.get(lt);
+		if (cached && !context) {
+			return cached;
+		}
+		const out = this.convertUncached(lt, context);
+		if (!context) {
+			this.convertCache.set(lt, out);
+		}
+		return out;
+	}
+
+	private convertUncached(lt: LType, context?: string): Type {
+		switch (lt.k) {
+			case "name":
+				return this.convertName(lt.name, lt.args);
+			case "opt":
+				return T.option(this.convert(lt.t));
+			case "union": {
+				const hasNil = lt.ts.some((t) => t.k === "name" && t.name === "nil");
+				const rest = lt.ts.filter((t) => !(t.k === "name" && t.name === "nil")).map((t) => this.convert(t));
+				const allLit = rest.every((r) => r.k === "lit");
+				let base: Type;
+				if (rest.length === 1) {
+					base = rest[0];
+				} else if (!allLit && rest.every((r) => r.k === "instance")) {
+					base = T.instance("Instance");
+				} else if (!allLit && rest.some((r) => r.k === "any")) {
+					base = T.any;
+				} else {
+					base = { k: "union", members: rest };
+				}
+				return hasNil ? T.option(base) : base;
+			}
+			case "inter": {
+				const fns = lt.ts.filter((t) => t.k === "fn") as LFn[];
+				if (fns.length === lt.ts.length && fns.length > 0) {
+					const converted = fns.map((f) => this.convertFn(f));
+					const first = converted[0] as Extract<Type, { k: "func" }>;
+					return { ...first, overloads: converted };
+				}
+				const fields: Record<string, Type> = {};
+				for (const t of lt.ts) {
+					if (t.k === "table") {
+						for (const [k, v] of Object.entries(t.fields)) {
+							fields[k] = this.convert(v);
+						}
+					}
+				}
+				return { k: "table", fields };
+			}
+			case "array":
+				return T.list(this.convert(lt.t));
+			case "map":
+				return T.dict(this.convert(lt.key), this.convert(lt.value));
+			case "table": {
+				const fields: Record<string, Type> = {};
+				for (const [k, v] of Object.entries(lt.fields)) {
+					fields[k] = this.convert(v);
+				}
+				return { k: "table", fields };
+			}
+			case "fn":
+				return this.convertFn(lt, context);
+			case "lit":
+				return { k: "lit", value: lt.value };
+			case "pack":
+				return T.any;
+			default:
+				return T.any;
+		}
+	}
+
+	convertFn(fn: LFn, qualifiedName?: string): Type {
+		const params: FnParam[] = fn.params.map((p, i) => {
+			const t = this.convert(p.t);
+			return { name: p.name || `arg${i + 1}`, type: t.k === "option" ? t.inner : t, optional: t.k === "option" || (t.k === "any" && false) };
+		});
+		let ret: Type;
+		const rets = fn.returns.map((r) => this.convert(r));
+		if (rets.length === 0) {
+			ret = fn.returnsVariadic ? T.any : T.void;
+		} else if (rets.length === 1) {
+			ret = rets[0];
+		} else {
+			ret = { k: "tuple", elems: rets };
+		}
+		if (qualifiedName && INT_RESULTS.has(qualifiedName)) {
+			ret = ret.k === "option" ? T.option(T.int) : ret.k === "float" ? T.int : ret;
+		}
+		const out: Type = { k: "func", params, ret, variadic: fn.variadic ? this.convert(fn.variadic) : null };
+		if (fn.generics?.length) {
+			out.generics = fn.generics;
+		}
+		return out;
+	}
+
+	private convertName(name: string, args?: LType[]): Type {
+		switch (name) {
+			case "number":
+			case "double":
+			case "float":
+				return T.float;
+			case "int":
+			case "int64":
+				return T.int;
+			case "string":
+				return T.string;
+			case "boolean":
+			case "bool":
+				return T.bool;
+			case "nil":
+			case "()":
+				return T.void;
+			case "any":
+			case "unknown":
+			case "userdata":
+			case "Object":
+				return name === "Object" ? T.instance("Object") : T.any;
+			case "never":
+				return T.never;
+			case "thread":
+				return T.thread;
+			case "buffer":
+				return T.buffer;
+			case "vector":
+				return T.datatype("Vector3");
+			case "RBXScriptSignal":
+				return { k: "rbxSignal", args: (args || []).filter((a) => !(a.k === "name" && a.name === "()")).map((a) => this.convert(a)) };
+			case "Instances":
+				return T.list(T.instance("Instance"));
+			case "Objects":
+				return T.list(T.instance("Instance"));
+			case "Enum":
+				return { k: "rbxEnum", enumName: "*" };
+			case "EnumItem":
+				return { k: "rbxEnumItem", enumName: "*" };
+			default:
+				break;
+		}
+		if (this.hasClass(name)) {
+			return T.instance(name);
+		}
+		if (this.hasDatatype(name)) {
+			return T.datatype(name);
+		}
+		if (name.startsWith("Enum") && this.hasEnum(name.slice(4))) {
+			return { k: "rbxEnumItem", enumName: name.slice(4) };
+		}
+		if (name.startsWith("Enum.") && this.hasEnum(name.slice(5))) {
+			return { k: "rbxEnumItem", enumName: name.slice(5) };
+		}
+		const alias = this.aliases[name];
+		if (alias) {
+			return this.convert(alias);
+		}
+		return T.any;
+	}
+
+	/** Function type of a library member (`math.floor`), with integer results applied. */
+	libraryFunction(lib: string, member: string): Type | null {
+		const st = this.libraries[lib]?.[member];
+		if (!st) {
+			return null;
+		}
+		if (st.kind === "value") {
+			return st.type ? this.convert(st.type) : T.any;
+		}
+		const fns = (st.overloads || []).map((f) => this.convertFn(f, `${lib}.${member}`));
+		if (fns.length === 0) {
+			return T.any;
+		}
+		const first = fns[0] as Extract<Type, { k: "func" }>;
+		return fns.length > 1 ? { ...first, overloads: fns } : first;
+	}
+
+	globalFunction(name: string): Type | null {
+		const g = this.globals[name];
+		if (!g) {
+			return null;
+		}
+		if (g.overloads) {
+			const fns = g.overloads.map((f) => this.convertFn(f, name));
+			const first = fns[0] as Extract<Type, { k: "func" }>;
+			return fns.length > 1 ? { ...first, overloads: fns } : first;
+		}
+		return g.type ? this.convert(g.type) : T.any;
+	}
+
+	methodType(member: SurfaceMember): Type {
+		const fns = (member.overloads || []).map((f) => this.convertFn(f));
+		if (fns.length === 0) {
+			return T.func([], T.void);
+		}
+		const first = fns[0] as Extract<Type, { k: "func" }>;
+		return fns.length > 1 ? { ...first, overloads: fns } : first;
+	}
+
+	staticFunctionType(st: SurfaceStatic): Type {
+		if (st.kind === "value") {
+			return st.type ? this.convert(st.type) : T.any;
+		}
+		const fns = (st.overloads || []).map((f) => this.convertFn(f));
+		const first = fns[0] as Extract<Type, { k: "func" }>;
+		return fns.length > 1 ? { ...first, overloads: fns } : first;
+	}
+
+	/** Result type of `left <op> right` for datatypes (Vector3 + Vector3, CFrame * Vector3, 2 * v). */
+	operator(op: string, left: Type, right: Type): Type | null {
+		const meta: Record<string, string> = { "+": "__add", "-": "__sub", "*": "__mul", "/": "__div", "%": "__mod" };
+		const name = meta[op];
+		if (!name) {
+			return null;
+		}
+		const tryOn = (dt: string, other: Type): Type | null => {
+			for (const fn of this.datatypes[dt]?.operators[name] || []) {
+				const param = fn.params[0] ? this.convert(fn.params[0].t) : null;
+				if (!param || this.acceptsOperand(param, other)) {
+					return fn.returns[0] ? this.convert(fn.returns[0]) : null;
+				}
+			}
+			return null;
+		};
+		if (left.k === "datatype") {
+			const r = tryOn(left.name, right);
+			if (r) {
+				return r;
+			}
+		}
+		if (right.k === "datatype" && (op === "*" || op === "+") && (left.k === "int" || left.k === "float" || left.k === "lit")) {
+			return tryOn(right.name, left);
+		}
+		return null;
+	}
+
+	private acceptsOperand(param: Type, arg: Type): boolean {
+		if (param.k === "union") {
+			return param.members.some((m) => this.acceptsOperand(m, arg));
+		}
+		if (param.k === "float" || param.k === "int") {
+			return arg.k === "int" || arg.k === "float" || (arg.k === "lit" && typeof arg.value === "number");
+		}
+		if (param.k === "datatype") {
+			return arg.k === "datatype" && arg.name === param.name;
+		}
+		return param.k === "any";
+	}
+
+	unaryMinus(t: Type): boolean {
+		return t.k === "datatype" && Boolean(this.datatypes[t.name]?.operators.__unm);
+	}
+
+	/** Creation policy for `Instance.new("X")` / `X()`. */
+	creationError(cls: string): string | null {
+		const c = this.classes[cls];
+		if (!c) {
+			return `'${cls}' is not a Roblox class`;
+		}
+		if (c.service) {
+			return `${cls} is a service; get it with game.GetService("${cls}") instead of creating it`;
+		}
+		if (!c.creatable) {
+			return `${cls} cannot be created with Instance.new (it is ${c.abstract ? "abstract" : "not creatable"})`;
+		}
+		return null;
+	}
+}
+
+let shared: RobloxApi | null = null;
+
+export function surfacePath(): string {
+	return path.join(projectRoot, "api", "roblox", "surface.json");
+}
+
+export function robloxApi(): RobloxApi {
+	if (!shared) {
+		const file = surfacePath();
+		if (!fs.existsSync(file)) {
+			throw new Error(`cluaupp: missing Roblox surface ${file}. Run \`cluaupp api surface\` to rebuild it.`);
+		}
+		shared = new RobloxApi(JSON.parse(fs.readFileSync(file, "utf8")) as RobloxSurface);
+	}
+	return shared;
+}
+
+/** Test hook. */
+export function setRobloxApi(api: RobloxApi | null): void {
+	shared = api;
+}

package/src/compiler/roblox/context.ts

@@ -0,0 +1,108 @@
+/**
+ * Server/client authority rules. Each rule names a service, a class member or a service member,
+ * and the only run context where it works. Members apply to subclasses (RemoteEvent rules also
+ * cover UnreliableRemoteEvent through the explicit entries).
+ */
+
+export type RunContext = "server" | "client" | "shared" | "plugin";
+
+export interface ContextRule {
+	only: "server" | "client";
+	why: string;
+	severity?: "error" | "warning";
+}
+
+/** `service:Name` → rule for touching the service at all. */
+export const SERVICE_RULES: Record<string, ContextRule> = {
+	ServerStorage: { only: "server", why: "ServerStorage is never replicated to clients" },
+	ServerScriptService: { only: "server", why: "ServerScriptService is never replicated to clients" },
+	DataStoreService: { only: "server", why: "DataStores can only be accessed by the server" },
+	MessagingService: { only: "server", why: "MessagingService only works on the server" },
+	MemoryStoreService: { only: "server", why: "MemoryStoreService only works on the server" },
+	AnalyticsService: { only: "server", why: "AnalyticsService events are logged from the server" },
+	OpenCloudService: { only: "server", why: "OpenCloudService only works on the server" },
+	UserInputService: { only: "client", why: "UserInputService reads the local device; on the server it has no input" },
+	ContextActionService: { only: "client", why: "ContextActionService binds local input" },
+	HapticService: { only: "client", why: "HapticService drives local devices" },
+	VRService: { only: "client", why: "VRService reads the local headset" },
+	GuiService: { only: "client", why: "GuiService controls the local player's GUI", severity: "warning" },
+};
+
+/** `Class.Member` → rule (checked against the member's owner chain). */
+export const MEMBER_RULES: Record<string, ContextRule> = {
+	"Players.LocalPlayer": { only: "client", why: "Players.LocalPlayer is nil on the server" },
+	"Player.GetMouse": { only: "client", why: "GetMouse only works for the local player" },
+	"RunService.RenderStepped": { only: "client", why: "RenderStepped only fires on clients" },
+	"RunService.BindToRenderStep": { only: "client", why: "BindToRenderStep only works on clients" },
+	"RunService.UnbindFromRenderStep": { only: "client", why: "UnbindFromRenderStep only works on clients" },
+	"StarterGui.SetCore": { only: "client", why: "SetCore only works from a LocalScript" },
+	"StarterGui.GetCore": { only: "client", why: "GetCore only works from a LocalScript" },
+	"StarterGui.SetCoreGuiEnabled": { only: "client", why: "SetCoreGuiEnabled only works from a LocalScript" },
+	"RemoteEvent.FireServer": { only: "client", why: "FireServer sends from a client to the server" },
+	"RemoteEvent.OnClientEvent": { only: "client", why: "OnClientEvent fires on clients" },
+	"RemoteEvent.FireClient": { only: "server", why: "FireClient sends from the server to one client" },
+	"RemoteEvent.FireAllClients": { only: "server", why: "FireAllClients sends from the server" },
+	"RemoteEvent.OnServerEvent": { only: "server", why: "OnServerEvent fires on the server" },
+	"UnreliableRemoteEvent.FireServer": { only: "client", why: "FireServer sends from a client to the server" },
+	"UnreliableRemoteEvent.OnClientEvent": { only: "client", why: "OnClientEvent fires on clients" },
+	"UnreliableRemoteEvent.FireClient": { only: "server", why: "FireClient sends from the server to one client" },
+	"UnreliableRemoteEvent.FireAllClients": { only: "server", why: "FireAllClients sends from the server" },
+	"UnreliableRemoteEvent.OnServerEvent": { only: "server", why: "OnServerEvent fires on the server" },
+	"RemoteFunction.InvokeServer": { only: "client", why: "InvokeServer calls the server from a client" },
+	"RemoteFunction.OnClientInvoke": { only: "client", why: "OnClientInvoke runs on clients" },
+	"RemoteFunction.InvokeClient": { only: "server", why: "InvokeClient calls a client from the server" },
+	"RemoteFunction.OnServerInvoke": { only: "server", why: "OnServerInvoke runs on the server" },
+	"DataModel.BindToClose": { only: "server", why: "BindToClose runs when the server shuts down" },
+	"Players.BanAsync": { only: "server", why: "bans are issued by the server" },
+	"Players.UnbanAsync": { only: "server", why: "bans are issued by the server" },
+	"Players.CreateHumanoidModelFromUserId": { only: "server", why: "only the server can build character models" },
+	"Players.CreateHumanoidModelFromDescription": { only: "server", why: "only the server can build character models" },
+	"Player.LoadCharacter": { only: "server", why: "characters are spawned by the server" },
+	"Player.LoadCharacterAsync": { only: "server", why: "characters are spawned by the server" },
+	"BasePart.SetNetworkOwner": { only: "server", why: "network ownership is assigned by the server" },
+	"BasePart.SetNetworkOwnershipAuto": { only: "server", why: "network ownership is assigned by the server" },
+	"MarketplaceService.ProcessReceipt": { only: "server", why: "developer product receipts are processed by the server" },
+	"BadgeService.AwardBadge": { only: "server", why: "badges are awarded by the server" },
+	"BadgeService.AwardBadgeAsync": { only: "server", why: "badges are awarded by the server" },
+	"TextService.FilterStringAsync": { only: "server", why: "text filtering runs on the server" },
+	"HttpService.GetAsync": { only: "server", why: "HTTP requests can only be made by the server" },
+	"HttpService.PostAsync": { only: "server", why: "HTTP requests can only be made by the server" },
+	"HttpService.RequestAsync": { only: "server", why: "HTTP requests can only be made by the server" },
+	"TeleportService.TeleportAsync": { only: "server", why: "TeleportAsync is server-only" },
+	"TeleportService.ReserveServer": { only: "server", why: "ReserveServer is server-only" },
+	"TeleportService.ReserveServerAsync": { only: "server", why: "ReserveServerAsync is server-only" },
+	"InsertService.LoadAsset": { only: "server", why: "LoadAsset is server-only" },
+	"PhysicsService.RegisterCollisionGroup": { only: "server", why: "collision groups are registered by the server" },
+};
+
+/** Members that work but are a known exploit or freeze vector. */
+export const RISKY_MEMBERS: Record<string, string> = {
+	"RemoteFunction.InvokeClient": "the server yields until the client answers; a malicious client can hang it forever — prefer a RemoteEvent",
+};
+
+export function contextLabel(ctx: RunContext): string {
+	switch (ctx) {
+		case "server":
+			return "a server Script";
+		case "client":
+			return "a LocalScript";
+		case "plugin":
+			return "a plugin";
+		default:
+			return "a shared module";
+	}
+}
+
+export function runContextOf(fileName: string): RunContext {
+	const base = fileName.replace(/\\/g, "/").split("/").pop()!.toLowerCase();
+	if (/\.server\.clp$/.test(base)) {
+		return "server";
+	}
+	if (/\.client\.clp$/.test(base)) {
+		return "client";
+	}
+	if (/\.plugin\.clp$/.test(base)) {
+		return "plugin";
+	}
+	return "shared";
+}

package/src/compiler/source.ts

@@ -0,0 +1,67 @@
+/** Source text with fast offset → line/column mapping. Columns are 1-based UTF-16 units. */
+
+export interface Span {
+	start: number;
+	end: number;
+}
+
+export interface Position {
+	line: number;
+	column: number;
+}
+
+export class SourceFile {
+	readonly lineStarts: number[];
+
+	constructor(
+		readonly path: string,
+		readonly text: string,
+	) {
+		const starts = [0];
+		for (let i = 0; i < text.length; i++) {
+			const c = text.charCodeAt(i);
+			if (c === 10) {
+				starts.push(i + 1);
+			} else if (c === 13) {
+				if (text.charCodeAt(i + 1) === 10) {
+					i++;
+				}
+				starts.push(i + 1);
+			}
+		}
+		this.lineStarts = starts;
+	}
+
+	position(offset: number): Position {
+		const starts = this.lineStarts;
+		let lo = 0;
+		let hi = starts.length - 1;
+		while (lo < hi) {
+			const mid = (lo + hi + 1) >> 1;
+			if (starts[mid] <= offset) {
+				lo = mid;
+			} else {
+				hi = mid - 1;
+			}
+		}
+		return { line: lo + 1, column: offset - starts[lo] + 1 };
+	}
+
+	lineText(line: number): string {
+		const start = this.lineStarts[line - 1] ?? 0;
+		const next = this.lineStarts[line] ?? this.text.length;
+		return this.text.slice(start, next).replace(/\r?\n$|\r$/, "");
+	}
+
+	slice(span: Span): string {
+		return this.text.slice(span.start, span.end);
+	}
+}
+
+export function spanOf(start: number, end: number): Span {
+	return { start, end };
+}
+
+export function joinSpans(a: Span, b: Span): Span {
+	return { start: Math.min(a.start, b.start), end: Math.max(a.end, b.end) };
+}