cluaupp 1.5.2 → 2.0.0-beta.1

package/src/compiler/checker/symbols.ts

@@ -0,0 +1,219 @@
+/** Symbols, scopes and the per-module declaration registries shared by checker and emitter. */
+
+import type { EnumDecl, Expr, FuncDecl, StructDecl, SymbolRef } from "../ast.js";
+import type { RunContext } from "../roblox/context.js";
+import type { Span } from "../source.js";
+import type { StdModule } from "../stdlib.js";
+import type { Type } from "../types.js";
+
+export type SymKind = "var" | "param" | "func" | "const" | "signal" | "module" | "struct" | "enum" | "variant" | "alias" | "namespace" | "self" | "typeparam";
+
+export interface Sym extends SymbolRef {
+	kind: SymKind;
+	type: Type;
+	mutable: boolean;
+	span: Span;
+	file: string;
+	topLevel: boolean;
+	/** Function nesting depth where it was declared (0 = file level). */
+	depth: number;
+	constValue?: number | string | boolean | null;
+	observable?: boolean;
+	atomic?: boolean;
+	/** Referenced from a function nested deeper than its declaration. */
+	captured?: boolean;
+	used?: boolean;
+	assigned?: boolean;
+	/** Struct/enum/variant id for type symbols. */
+	typeId?: string;
+	link?: LinkTarget;
+	decl?: FuncDecl;
+	/** CL++ signal: handlers connected with `~>`. */
+	handlers?: Expr[];
+	signalParams?: Type[] | null;
+	/** Mutated after declaration (copy elision needs to know). */
+	mutatedFields?: boolean;
+	/** Declared with `[[server]]` / `[[client]]`. */
+	contextOnly?: "server" | "client";
+	/** Doc comment. */
+	doc?: string;
+}
+
+export class Scope {
+	readonly values = new Map<string, Sym>();
+	readonly types = new Map<string, Sym>();
+	/** Narrowed types for paths (`sym#3`, `sym#3.Character`). */
+	readonly narrowed = new Map<string, Type>();
+
+	constructor(
+		readonly parent: Scope | null,
+		readonly kind: "file" | "function" | "block" | "loop",
+		readonly depth: number,
+	) {}
+
+	lookup(name: string): Sym | undefined {
+		let cur: Scope | null = this;
+		while (cur) {
+			const s = cur.values.get(name);
+			if (s) {
+				return s;
+			}
+			cur = cur.parent;
+		}
+		return undefined;
+	}
+
+	lookupType(name: string): Sym | undefined {
+		let cur: Scope | null = this;
+		while (cur) {
+			const s = cur.types.get(name);
+			if (s) {
+				return s;
+			}
+			cur = cur.parent;
+		}
+		return undefined;
+	}
+
+	narrowedType(key: string): Type | undefined {
+		let cur: Scope | null = this;
+		while (cur) {
+			if (cur.narrowed.has(key)) {
+				return cur.narrowed.get(key);
+			}
+			cur = cur.parent;
+		}
+		return undefined;
+	}
+
+	/** Drop narrowings of a path and everything below it (after an assignment). */
+	invalidate(prefix: string): void {
+		let cur: Scope | null = this;
+		while (cur) {
+			for (const key of [...cur.narrowed.keys()]) {
+				if (key === prefix || key.startsWith(`${prefix}.`)) {
+					cur.narrowed.delete(key);
+				}
+			}
+			cur = cur.parent;
+		}
+		// Mark as explicitly unknown at this level so outer narrowings stop applying.
+	}
+
+	allValueNames(): string[] {
+		const out: string[] = [];
+		let cur: Scope | null = this;
+		while (cur) {
+			out.push(...cur.values.keys());
+			cur = cur.parent;
+		}
+		return out;
+	}
+}
+
+export interface FieldInfo {
+	name: string;
+	type: Type;
+	owner: string;
+	isPrivate: boolean;
+	defaultValue: Expr | null;
+	span: Span;
+	doc?: string;
+}
+
+export interface MethodInfo {
+	name: string;
+	owner: string;
+	/** Struct id that first declared this method (the root of overrides). */
+	root: string;
+	decl: FuncDecl;
+	type: Extract<Type, { k: "func" }>;
+	isStatic: boolean;
+	isAbstract: boolean;
+	isFinal: boolean;
+	isPrivate: boolean;
+	/** Does the method assign to `self` fields? */
+	mutatesSelf?: boolean;
+}
+
+export interface StructInfo {
+	id: string;
+	name: string;
+	/** Name used in emitted Luau (renamed on collisions with Roblox types). */
+	luauName: string;
+	moduleId: string;
+	decl: StructDecl;
+	typeParams: string[];
+	bases: string[];
+	/** Every field in constructor order (inherited first, diamond-deduplicated). */
+	fields: FieldInfo[];
+	methods: Map<string, MethodInfo>;
+	subclasses: string[];
+	isAbstract: boolean;
+	isFinal: boolean;
+	resolved: boolean;
+}
+
+export interface EnumInfo {
+	id: string;
+	name: string;
+	luauName: string;
+	moduleId: string;
+	decl: EnumDecl;
+	cases: Array<{ name: string; payload: Type | null }>;
+	hasPayload: boolean;
+}
+
+export interface VariantInfo {
+	id: string;
+	name: string;
+	alternatives: Type[];
+}
+
+export interface ExportedFunc {
+	name: string;
+	type: Extract<Type, { k: "func" }>;
+	contextOnly?: "server" | "client";
+	yields?: boolean;
+	doc?: string;
+}
+
+export interface ModuleExports {
+	moduleId: string;
+	file: string;
+	kind: "script" | "module";
+	context: RunContext;
+	funcs: Map<string, ExportedFunc>;
+	structs: Map<string, StructInfo>;
+	enums: Map<string, EnumInfo>;
+	variants: Map<string, VariantInfo>;
+	aliases: Map<string, Type>;
+	consts: Map<string, { type: Type; value: number | string | boolean | null }>;
+	namespaces: Map<string, Map<string, ExportedFunc>>;
+	/** DataModel path of the compiled ModuleScript, when known. */
+	dmPath: string[] | null;
+}
+
+export type LinkTarget =
+	| { kind: "roblox" }
+	| { kind: "std"; module: StdModule }
+	| { kind: "clp"; exports: ModuleExports; dmPath: string[] | null; file: string }
+	| { kind: "luau"; dmPath: string[]; exports?: ModuleExports; label: string }
+	| { kind: "error"; message: string; notes?: string[] };
+
+export function emptyExports(moduleId: string, file: string, kind: "script" | "module", context: RunContext): ModuleExports {
+	return {
+		moduleId,
+		file,
+		kind,
+		context,
+		funcs: new Map(),
+		structs: new Map(),
+		enums: new Map(),
+		variants: new Map(),
+		aliases: new Map(),
+		consts: new Map(),
+		namespaces: new Map(),
+		dmPath: null,
+	};
+}

package/src/compiler/checker/typeops.ts

@@ -0,0 +1,355 @@
+/** Assignability, joins and member lookups that do not need checker state. */
+
+import type { RobloxApi } from "../roblox/api.js";
+import { isDynamic, prune, sameType, T, type Type } from "../types.js";
+import type { StructInfo } from "./symbols.js";
+
+export interface TypeEnv {
+	api: RobloxApi;
+	struct(id: string): StructInfo | undefined;
+}
+
+export type Assignability = "ok" | "nullable" | "narrowing" | "no";
+
+/**
+ * Can a value of type `from` be stored where `to` is expected?
+ * "nullable": only differs by a possible null (`Part?` into `Part`) — error in strict, warning otherwise.
+ * "narrowing": float into int — always an error (would lose the fraction).
+ */
+export function assignable(env: TypeEnv, to: Type, from: Type): Assignability {
+	const a = prune(to);
+	const b = prune(from);
+	if (a === b || isDynamic(a) || isDynamic(b) || b.k === "never") {
+		return "ok";
+	}
+	if (a.k === "infer") {
+		a.resolved = b;
+		return "ok";
+	}
+	if (a.k === "param" || b.k === "param") {
+		return "ok";
+	}
+	if (b.k === "union") {
+		let worst: Assignability = "ok";
+		for (const m of b.members) {
+			const r = assignable(env, a, m);
+			if (r === "no") {
+				return "no";
+			}
+			if (r !== "ok") {
+				worst = r;
+			}
+		}
+		return worst;
+	}
+	switch (a.k) {
+		case "void":
+			return b.k === "void" ? "ok" : "no";
+		case "null":
+			return b.k === "null" ? "ok" : "no";
+		case "option": {
+			if (b.k === "null") {
+				return "ok";
+			}
+			if (b.k === "option") {
+				return assignable(env, a.inner, b.inner) === "no" ? "no" : assignable(env, a.inner, b.inner);
+			}
+			return assignable(env, a.inner, b);
+		}
+		case "union": {
+			let best: Assignability = "no";
+			for (const m of a.members) {
+				const r = assignable(env, m, b);
+				if (r === "ok") {
+					return "ok";
+				}
+				if (r !== "no") {
+					best = r;
+				}
+			}
+			if (b.k === "null" && a.members.some((m) => prune(m).k === "null")) {
+				return "ok";
+			}
+			return best;
+		}
+		case "float":
+			return b.k === "float" || b.k === "int" || (b.k === "lit" && typeof b.value === "number") ? "ok" : nullableOr(env, a, b);
+		case "int":
+			if (b.k === "int" || (b.k === "lit" && typeof b.value === "number" && Number.isInteger(b.value))) {
+				return "ok";
+			}
+			if (b.k === "float" || (b.k === "lit" && typeof b.value === "number")) {
+				return "narrowing";
+			}
+			if (b.k === "enum") {
+				return "ok";
+			}
+			return nullableOr(env, a, b);
+		case "bool":
+			return b.k === "bool" || (b.k === "lit" && typeof b.value === "boolean") ? "ok" : nullableOr(env, a, b);
+		case "string":
+			return b.k === "string" || (b.k === "lit" && typeof b.value === "string") ? "ok" : nullableOr(env, a, b);
+		case "lit":
+			return b.k === "lit" && b.value === a.value ? "ok" : nullableOr(env, a, b);
+		case "list":
+			if (b.k === "list") {
+				if (!a.typed || !b.typed) {
+					return "ok";
+				}
+				const r = assignable(env, a.elem, b.elem);
+				return r === "ok" || r === "nullable" ? r : "no";
+			}
+			if (b.k === "tuple") {
+				return b.elems.every((e) => assignable(env, a.elem, e) === "ok") ? "ok" : "no";
+			}
+			return nullableOr(env, a, b);
+		case "dict":
+			if (b.k === "dict") {
+				return assignable(env, a.key, b.key) !== "no" && assignable(env, a.value, b.value) !== "no" ? "ok" : "no";
+			}
+			if (b.k === "table") {
+				return Object.values(b.fields).every((f) => assignable(env, a.value, f) !== "no") ? "ok" : "no";
+			}
+			return nullableOr(env, a, b);
+		case "table":
+			if (b.k === "table") {
+				for (const [k, v] of Object.entries(a.fields)) {
+					const bf = b.fields[k];
+					if (!bf) {
+						if (prune(v).k !== "option") {
+							return "no";
+						}
+						continue;
+					}
+					if (assignable(env, v, bf) === "no") {
+						return "no";
+					}
+				}
+				return "ok";
+			}
+			if (b.k === "dict") {
+				return "ok";
+			}
+			return nullableOr(env, a, b);
+		case "struct":
+			if (b.k === "struct") {
+				if (a.id === b.id) {
+					return a.args.length === 0 || b.args.length === 0 || a.args.every((x, i) => sameType(x, b.args[i] ?? T.any)) ? "ok" : "no";
+				}
+				return structExtends(env, b.id, a.id) ? "ok" : "no";
+			}
+			return nullableOr(env, a, b);
+		case "enum":
+		case "variant":
+			if (b.k === a.k && b.id === a.id) {
+				return "ok";
+			}
+			if (a.k === "variant") {
+				return a.alternatives.some((alt) => assignable(env, alt, b) === "ok") ? "ok" : nullableOr(env, a, b);
+			}
+			return nullableOr(env, a, b);
+		case "result":
+			if (b.k === "result") {
+				const ok = assignable(env, a.ok, b.ok);
+				const err = assignable(env, a.err, b.err);
+				return ok !== "no" && err !== "no" ? "ok" : "no";
+			}
+			return nullableOr(env, a, b);
+		case "task":
+			return b.k === "task" ? "ok" : nullableOr(env, a, b);
+		case "func":
+			if (b.k === "func") {
+				return "ok";
+			}
+			return nullableOr(env, a, b);
+		case "instance":
+			if (b.k === "instance") {
+				return b.cls === a.cls || env.api.isA(b.cls, a.cls) ? "ok" : "no";
+			}
+			return nullableOr(env, a, b);
+		case "datatype":
+			if (b.k === "datatype") {
+				return b.name === a.name ? "ok" : "no";
+			}
+			return nullableOr(env, a, b);
+		case "rbxEnumItem":
+			if (b.k === "rbxEnumItem") {
+				return a.enumName === "*" || b.enumName === a.enumName || b.enumName === "*" ? "ok" : "no";
+			}
+			return nullableOr(env, a, b);
+		case "rbxEnum":
+			return b.k === "rbxEnum" && (a.enumName === "*" || a.enumName === b.enumName) ? "ok" : "no";
+		case "rbxSignal":
+			return b.k === "rbxSignal" ? "ok" : "no";
+		case "tuple":
+			return b.k === "tuple" && b.elems.length >= a.elems.length ? "ok" : "no";
+		case "thread":
+		case "buffer":
+			return b.k === a.k ? "ok" : nullableOr(env, a, b);
+		default:
+			return sameType(a, b) ? "ok" : "no";
+	}
+}
+
+function nullableOr(env: TypeEnv, to: Type, from: Type): Assignability {
+	if (from.k === "option") {
+		return assignable(env, to, from.inner) === "ok" ? "nullable" : "no";
+	}
+	if (from.k === "null") {
+		return "nullable";
+	}
+	return "no";
+}
+
+export function structExtends(env: TypeEnv, childId: string, baseId: string): boolean {
+	const seen = new Set<string>();
+	const stack = [childId];
+	while (stack.length) {
+		const id = stack.pop()!;
+		if (id === baseId) {
+			return true;
+		}
+		if (seen.has(id)) {
+			continue;
+		}
+		seen.add(id);
+		const info = env.struct(id);
+		if (info) {
+			stack.push(...info.bases);
+		}
+	}
+	return false;
+}
+
+/** Least upper bound used for ternaries, list literals and inferred returns. */
+export function join(env: TypeEnv, a: Type, b: Type): Type {
+	const x = prune(a);
+	const y = prune(b);
+	if (isDynamic(x)) {
+		return y;
+	}
+	if (isDynamic(y)) {
+		return x;
+	}
+	if (x.k === "never") {
+		return y;
+	}
+	if (y.k === "never") {
+		return x;
+	}
+	if (sameType(x, y)) {
+		return x;
+	}
+	if (x.k === "null") {
+		return T.option(y);
+	}
+	if (y.k === "null") {
+		return T.option(x);
+	}
+	if (x.k === "option" || y.k === "option") {
+		const inner = join(env, x.k === "option" ? x.inner : x, y.k === "option" ? y.inner : y);
+		return T.option(inner);
+	}
+	const numeric = (t: Type) => t.k === "int" || t.k === "float" || (t.k === "lit" && typeof t.value === "number");
+	if (numeric(x) && numeric(y)) {
+		const isInt = (t: Type) => t.k === "int" || (t.k === "lit" && Number.isInteger(t.value));
+		return isInt(x) && isInt(y) ? T.int : T.float;
+	}
+	if (x.k === "lit" && y.k === "lit" && typeof x.value === typeof y.value) {
+		return typeof x.value === "string" ? T.string : typeof x.value === "boolean" ? T.bool : T.float;
+	}
+	if ((x.k === "lit" && typeof x.value === "string" && y.k === "string") || (y.k === "lit" && typeof y.value === "string" && x.k === "string")) {
+		return T.string;
+	}
+	if (x.k === "instance" && y.k === "instance") {
+		return T.instance(commonClass(env, x.cls, y.cls));
+	}
+	if (x.k === "struct" && y.k === "struct") {
+		if (structExtends(env, x.id, y.id)) {
+			return y;
+		}
+		if (structExtends(env, y.id, x.id)) {
+			return x;
+		}
+	}
+	if (x.k === "list" && y.k === "list") {
+		return T.list(join(env, x.elem, y.elem), x.typed && y.typed);
+	}
+	return { k: "union", members: [x, y] };
+}
+
+function commonClass(env: TypeEnv, a: string, b: string): string {
+	const chain = new Set<string>();
+	let cur: string | null = a;
+	while (cur) {
+		chain.add(cur);
+		cur = env.api.classes[cur]?.superclass ?? null;
+	}
+	cur = b;
+	while (cur) {
+		if (chain.has(cur)) {
+			return cur;
+		}
+		cur = env.api.classes[cur]?.superclass ?? null;
+	}
+	return "Instance";
+}
+
+/** Replace generic parameters by their bindings. */
+export function substitute(t: Type, bindings: Map<string, Type>): Type {
+	if (bindings.size === 0) {
+		return t;
+	}
+	const p = prune(t);
+	switch (p.k) {
+		case "param":
+			return bindings.get(p.name) ?? p;
+		case "list":
+			return T.list(substitute(p.elem, bindings), p.typed);
+		case "dict":
+			return T.dict(substitute(p.key, bindings), substitute(p.value, bindings));
+		case "option":
+			return T.option(substitute(p.inner, bindings));
+		case "result":
+			return { k: "result", ok: substitute(p.ok, bindings), err: substitute(p.err, bindings) };
+		case "task":
+			return { k: "task", result: substitute(p.result, bindings) };
+		case "struct":
+			return p.args.length ? { ...p, args: p.args.map((x) => substitute(x, bindings)) } : p;
+		case "func":
+			return {
+				...p,
+				params: p.params.map((x) => ({ ...x, type: substitute(x.type, bindings) })),
+				ret: substitute(p.ret, bindings),
+				variadic: p.variadic ? substitute(p.variadic, bindings) : null,
+			};
+		case "union":
+			return { k: "union", members: p.members.map((m) => substitute(m, bindings)) };
+		case "tuple":
+			return { k: "tuple", elems: p.elems.map((m) => substitute(m, bindings)) };
+		default:
+			return p;
+	}
+}
+
+/** Bind generic parameters by matching a declared type against an argument type. */
+export function bindGenerics(declared: Type, actual: Type, bindings: Map<string, Type>): void {
+	const d = prune(declared);
+	const a = prune(actual);
+	if (d.k === "param") {
+		if (!bindings.has(d.name) && !isDynamic(a)) {
+			bindings.set(d.name, a.k === "lit" ? (typeof a.value === "string" ? T.string : typeof a.value === "boolean" ? T.bool : Number.isInteger(a.value) ? T.int : T.float) : a);
+		}
+		return;
+	}
+	if (d.k === "list" && a.k === "list") {
+		bindGenerics(d.elem, a.elem, bindings);
+	} else if (d.k === "option") {
+		bindGenerics(d.inner, a.k === "option" ? a.inner : a, bindings);
+	} else if (d.k === "dict" && a.k === "dict") {
+		bindGenerics(d.key, a.key, bindings);
+		bindGenerics(d.value, a.value, bindings);
+	} else if (d.k === "struct" && a.k === "struct") {
+		d.args.forEach((x, i) => a.args[i] && bindGenerics(x, a.args[i], bindings));
+	}
+}

package/src/compiler/checker/yields.ts

@@ -0,0 +1,120 @@
+/** Can executing these statements yield the current thread (task.wait, WaitForChild, *Async, :Wait())? */
+
+import type { Expr, Stmt } from "../ast.js";
+import { prune } from "../types.js";
+import type { Checker } from "./checker.js";
+
+const YIELDING_GLOBALS = new Set(["wait", "Wait"]);
+const YIELDING_LIBRARY = new Set(["task.wait", "coroutine.yield"]);
+
+export function mayYield(c: Checker, body: Stmt[]): boolean {
+	let found = false;
+	const visitExpr = (e: Expr | null | undefined): void => {
+		if (!e || found) {
+			return;
+		}
+		if (exprYields(c, e)) {
+			found = true;
+			return;
+		}
+		for (const [key, value] of Object.entries(e)) {
+			if (key === "ty" || key === "res" || key === "span" || key === "narrowedFrom") {
+				continue;
+			}
+			if (key === "body" && e.kind === "Function") {
+				continue; // a closure's body runs later
+			}
+			walk(value);
+		}
+	};
+	const walk = (node: unknown): void => {
+		if (found || !node || typeof node !== "object") {
+			return;
+		}
+		if (Array.isArray(node)) {
+			for (const n of node) {
+				walk(n);
+			}
+			return;
+		}
+		const rec = node as { kind?: string };
+		if (rec.kind && isExprKind(rec.kind)) {
+			visitExpr(node as Expr);
+			return;
+		}
+		for (const [key, value] of Object.entries(node)) {
+			if (key === "ty" || key === "res" || key === "span" || key === "sym") {
+				continue;
+			}
+			walk(value);
+		}
+	};
+	walk(body);
+	return found;
+}
+
+const EXPR_KINDS = new Set([
+	"Number", "String", "Template", "Bool", "Null", "Name", "SelfField", "Member", "Scope", "Index", "Call", "New", "Unary",
+	"Binary", "Ternary", "Function", "Spawn", "Await", "Thread", "Join", "Move", "PCall", "Parallel", "Update", "Cast", "Error",
+]);
+
+function isExprKind(kind: string): boolean {
+	return EXPR_KINDS.has(kind);
+}
+
+function exprYields(c: Checker, e: Expr): boolean {
+	if (e.kind === "Await" || e.kind === "Join" || e.kind === "Parallel") {
+		return true;
+	}
+	if (e.kind !== "Call") {
+		return false;
+	}
+	const callee = e.callee;
+	const res = callee.res;
+	if (!res) {
+		return true;
+	}
+	switch (res.kind) {
+		case "rbxMethod": {
+			const name = callee.kind === "Member" || callee.kind === "Scope" ? callee.name : "";
+			const hit = c.api.member(res.owner, name);
+			return Boolean(hit?.member.yields) || name === "WaitForChild" || /Async$/.test(name);
+		}
+		case "datatypeMember":
+			return res.datatype === "RBXScriptSignal" && res.member === "Wait";
+		case "global":
+			return YIELDING_GLOBALS.has(res.luau);
+		case "library":
+			return YIELDING_LIBRARY.has(`${res.lib}.${res.member}`);
+		case "func":
+		case "local": {
+			const decl = (res.sym as { decl?: { fn?: { mayYield?: boolean } } }).decl;
+			if (decl) {
+				return decl.fn?.mayYield ?? true;
+			}
+			const t = prune(callee.ty ?? { k: "any" });
+			return t.k !== "func";
+		}
+		case "method": {
+			const info = c.structs.get(res.struct);
+			const m = info?.methods.get(res.name);
+			return m?.decl.fn?.mayYield ?? true;
+		}
+		case "moduleMember":
+			return true;
+		case "builtin":
+		case "stdlib":
+		case "datatypeStatic":
+		case "rbxProperty":
+		case "rbxEvent":
+		case "enumCase":
+		case "struct":
+		case "signal":
+			return false;
+		case "dynamic":
+		case "luauMethod":
+			return true;
+		default:
+			return false;
+	}
+}