cluaupp 1.5.2 → 2.0.0-beta.2

package/src/compiler/checker/calls.ts

@@ -0,0 +1,1025 @@
+/**
+ * Calls: user functions (with call-site inference for unannotated parameters), methods, CL++
+ * builtins, struct/Instance/datatype construction, enum cases, Option/Result, `GetService`,
+ * generic class arguments (`WaitForChild<Model>("Map")`) and overload resolution on the Roblox API.
+ */
+
+import type { Arg, CallForm, Expr, FuncDecl, TypeNode } from "../ast.js";
+import { suggest } from "../diagnostics.js";
+import { isDynamic, isIntLike, isNumeric, isStringLike, nonNull, prune, T, typeToString, type FnParam, type Type } from "../types.js";
+import { widenLiteral, type Checker } from "./checker.js";
+import { checkExpr, rootSymbol } from "./exprs.js";
+import { checkMember } from "./members.js";
+import { checkHandler } from "./statements.js";
+import type { StructInfo, Sym } from "./symbols.js";
+import { assignable, bindGenerics, join, substitute } from "./typeops.js";
+
+type FnType = Extract<Type, { k: "func" }>;
+type CallExpr = Extract<Expr, { kind: "Call" }>;
+
+/** Methods whose class-name string argument can be written as a type argument. */
+const CLASS_ARG_METHODS = new Set([
+	"FindFirstChildOfClass", "FindFirstChildWhichIsA", "FindFirstAncestorOfClass", "FindFirstAncestorWhichIsA",
+	"IsA", "GetService", "FindService",
+]);
+/** Methods whose result can be narrowed with a type argument (a checked downcast). */
+/** Axiom functions that return an int when every argument is an int (`Axiom.Clamp(hp - 5, 0, 100)`). */
+const INT_PRESERVING = new Set(["Clamp", "Min", "Max", "Abs", "Sign", "Floor", "Ceil", "Round", "Trunc", "Snap", "Wrap", "Pow", "Gcd", "Lcm", "Factorial", "Sum", "Approach"]);
+const CAST_RESULT_METHODS = new Set(["WaitForChild", "FindFirstChild", "FindFirstDescendant", "FindFirstAncestor", "Clone"]);
+
+function setCall(e: CallExpr, call: CallForm, args: Array<Expr | null>, variadicArgs?: Expr[]): void {
+	e.res = { kind: "call", call, args, ...(variadicArgs && variadicArgs.length ? { variadicArgs } : {}) };
+}
+
+export function checkCall(c: Checker, e: CallExpr, expected?: Type): Type {
+	const callee = e.callee;
+	if (e.legacyConnect) {
+		c.warn("CL1204", callee.span, "`event~>Connect(fn)` is Cluaupp 1.x syntax", ["write `event.Connect(fn)` or the statement `event ~> fn;`"]);
+	}
+	if (callee.kind === "Name" && !c.scope.lookup(callee.name)) {
+		const special = checkSpecialName(c, e, callee, expected);
+		if (special) {
+			return special;
+		}
+	}
+	if (callee.kind === "Name") {
+		const sym = c.scope.lookup(callee.name);
+		if (sym && sym.kind === "struct" && sym.typeId) {
+			sym.used = true;
+			callee.res = { kind: "struct", name: sym.name, sym };
+			return constructStruct(c, e, sym.typeId, callee.typeArgs, e.args, expected);
+		}
+		if (sym && sym.kind === "signal") {
+			return fireSignal(c, e, sym);
+		}
+		if (sym && sym.kind === "variant") {
+			sym.used = true;
+			callee.res = { kind: "builtin", name: "variant" };
+			const fn = sym.type as FnType;
+			const r = checkArgs(c, e, fn, callee.span, null);
+			setCall(e, { form: "variant" }, r.args);
+			return fn.ret;
+		}
+	}
+	if (callee.kind === "SelfField") {
+		const t = checkExpr(c, callee);
+		if (callee.res?.kind === "method") {
+			return finishCall(c, e, prune(t), callee.span, { form: "call" }, expected);
+		}
+		return finishCall(c, e, prune(t), callee.span, { form: "call" }, expected);
+	}
+	if (callee.kind === "Member") {
+		return checkMemberCall(c, e, callee, expected);
+	}
+	const t = prune(checkExpr(c, callee));
+	if (t.k === "namespace" && t.ns.kind === "struct") {
+		return constructStruct(c, e, t.ns.id, null, e.args, expected);
+	}
+	if (t.k === "namespace" && t.ns.kind === "datatype") {
+		return constructDatatype(c, e, t.ns.name, e.args);
+	}
+	return finishCall(c, e, t, callee.span, { form: "call" }, expected);
+}
+
+// ---------- names with special meaning ----------
+
+function checkSpecialName(c: Checker, e: CallExpr, callee: Extract<Expr, { kind: "Name" }>, expected?: Type): Type | null {
+	const name = callee.name;
+	switch (name) {
+		case "len":
+		case "list":
+		case "array":
+		case "dictionary":
+		case "push":
+		case "pop":
+		case "insert":
+		case "remove":
+		case "find":
+		case "sort":
+		case "args":
+		case "mutex":
+		case "lock":
+		case "unlock":
+		case "fetch_add":
+		case "atomic_load":
+		case "actor":
+		case "Some":
+		case "Ok":
+		case "Err":
+		case "int":
+		case "float":
+		case "bool":
+		case "string":
+		case "GetService":
+			callee.res = { kind: "builtin", name };
+			callee.ty = T.any;
+			return checkBuiltin(c, e, name, callee.typeArgs, expected);
+		case "type":
+			c.requireRoblox(callee.span, "type");
+			callee.res = { kind: "global", luau: "type" };
+			callee.ty = T.any;
+			checkArgsLoose(c, e);
+			setCall(e, { form: "call" }, e.args.map((a) => a.value));
+			return T.string;
+		default:
+			break;
+	}
+	if (name === "Vector2" || name === "Vector3" || (c.api.hasDatatype(name) && !c.api.hasClass(name))) {
+		callee.res = { kind: "global", luau: name };
+		return constructDatatype(c, e, name, e.args);
+	}
+	if (name === "Vector4") {
+		c.error("RBX5002", callee.span, "Vector4 has no Roblox equivalent", ["use Color3 for colors or a struct"]);
+		checkArgsLoose(c, e);
+		return T.unknown;
+	}
+	if (c.api.hasClass(name) && !c.api.isService(name)) {
+		c.requireRoblox(callee.span, name);
+		callee.res = { kind: "global", luau: name };
+		return constructInstance(c, e, name, e.args, callee.span);
+	}
+	return null;
+}
+
+// ---------- builtins ----------
+
+function argValue(e: CallExpr, i: number): Expr | null {
+	return e.args[i]?.value ?? null;
+}
+
+function arity(c: Checker, e: CallExpr, name: string, min: number, max = min): boolean {
+	if (e.args.some((a) => a.name !== null) && name !== "dictionary") {
+		c.error("CL3101", e.span, `${name}(…) does not take named arguments`);
+	}
+	if (e.args.length < min || e.args.length > max) {
+		c.error("CL3102", e.span, `${name} takes ${min === max ? min : `${min} to ${max}`} argument${max === 1 ? "" : "s"}, got ${e.args.length}`);
+		return false;
+	}
+	return true;
+}
+
+function checkArgsLoose(c: Checker, e: CallExpr): Type[] {
+	return e.args.map((a) => checkExpr(c, a.value));
+}
+
+function listOf(c: Checker, x: Expr | null, what: string): Extract<Type, { k: "list" }> | null {
+	if (!x) {
+		return null;
+	}
+	const t = prune(checkExpr(c, x));
+	if (t.k === "list") {
+		return t;
+	}
+	if (!isDynamic(t)) {
+		c.error("CL3103", x.span, `${what} needs a list, got ${typeToString(t)}`);
+	}
+	return null;
+}
+
+function requireMutableList(c: Checker, x: Expr | null, what: string): void {
+	if (!x) {
+		return;
+	}
+	const root = rootSymbol(x);
+	if (root && (root.kind === "var" || root.kind === "param") && !root.mutable) {
+		c.diags.error("CL2040", x.span, `${what} changes '${root.name}', which is declared with let`, ["declare it with `let mut`"], {
+			span: root.span,
+			text: `mut ${root.name}`,
+			title: `Make '${root.name}' mutable (let mut)`,
+		});
+	}
+	if (root) {
+		root.mutatedFields = true;
+	}
+}
+
+function elementSlot(list: Extract<Type, { k: "list" }>, value: Type): Type {
+	const elem = prune(list.elem);
+	if (elem.k === "infer" && !elem.resolved) {
+		elem.resolved = widenLiteral(value);
+		return elem.resolved;
+	}
+	return list.elem;
+}
+
+function checkBuiltin(c: Checker, e: CallExpr, name: string, typeArgs: TypeNode[] | null, expected?: Type): Type {
+	const builtin = (elemType?: Type) => setCall(e, { form: "builtin", name, ...(elemType ? { elemType } : {}) }, e.args.map((a) => a.value));
+	switch (name) {
+		case "len": {
+			arity(c, e, "len", 1);
+			const x = argValue(e, 0);
+			const t = x ? prune(checkExpr(c, x)) : T.unknown;
+			if (!(t.k === "list" || t.k === "string" || t.k === "lit" || t.k === "dict" || t.k === "buffer" || t.k === "table" || isDynamic(t))) {
+				c.error("CL3104", x?.span ?? e.span, `len(…) needs a list, text or dictionary, got ${typeToString(t)}`, t.k === "instance" ? ["for children use len(x.GetChildren())"] : undefined);
+			}
+			builtin(t);
+			return T.int;
+		}
+		case "list": {
+			const ex = expected ? prune(expected) : null;
+			if (e.args.length === 0) {
+				builtin();
+				return ex && ex.k === "list" ? ex : T.list({ k: "infer", resolved: null });
+			}
+			const want = ex && ex.k === "list" ? ex.elem : undefined;
+			let elem: Type = T.never;
+			for (const a of e.args) {
+				if (a.name) {
+					c.error("CL3101", a.nameSpan ?? a.value.span, "list(…) takes values, not named arguments", ["use dictionary(Key: value, …) for named entries"]);
+				}
+				const t = checkExpr(c, a.value, want);
+				c.markCopy(a.value);
+				elem = join(c, elem, widenLiteral(t));
+			}
+			builtin();
+			if (want) {
+				for (const a of e.args) {
+					c.expectAssignable(want, a.value.ty ?? T.unknown, a.value.span, "list element");
+				}
+				return ex!;
+			}
+			return T.list(prune(elem).k === "never" ? T.any : elem);
+		}
+		case "array": {
+			if (!typeArgs || typeArgs.length !== 1) {
+				c.error("CL3105", e.span, "array needs its element type: array<int>(1, 2, 3)");
+				checkArgsLoose(c, e);
+				builtin();
+				return T.list(T.unknown);
+			}
+			const elem = c.resolveType(typeArgs[0]);
+			for (const a of e.args) {
+				const t = checkExpr(c, a.value, elem);
+				c.expectAssignable(elem, t, a.value.span, "array element");
+				c.markCopy(a.value);
+			}
+			builtin(elem);
+			return T.list(elem);
+		}
+		case "dictionary": {
+			if (e.args.length && e.args.every((a) => a.name !== null)) {
+				// dictionary(Transparency: 1, Color: c) → { Transparency = 1, Color = c }
+				const fields: Record<string, Type> = {};
+				for (const a of e.args) {
+					fields[a.name!] = widenLiteral(checkExpr(c, a.value));
+					c.markCopy(a.value);
+				}
+				setCall(e, { form: "table", keys: e.args.map((a) => a.name!) }, e.args.map((a) => a.value));
+				return { k: "table", fields };
+			}
+			let key: Type = T.any;
+			let value: Type = T.any;
+			if (typeArgs && typeArgs.length === 2) {
+				key = c.resolveType(typeArgs[0]);
+				value = c.resolveType(typeArgs[1]);
+			} else if (typeArgs) {
+				c.error("CL3105", e.span, "dictionary takes two type arguments: dictionary<string, int>(…)");
+			} else if (expected && prune(expected).k === "dict") {
+				const ex = prune(expected) as Extract<Type, { k: "dict" }>;
+				key = ex.key;
+				value = ex.value;
+			} else if (e.args.length === 0) {
+				key = { k: "infer", resolved: null };
+				value = { k: "infer", resolved: null };
+			}
+			if (e.args.length % 2 !== 0) {
+				c.error("CL3106", e.span, "dictionary(…) takes key/value pairs: dictionary<string, int>(\"a\", 1, \"b\", 2)");
+			}
+			let inferredKey: Type = T.never;
+			let inferredValue: Type = T.never;
+			e.args.forEach((a, i) => {
+				const isKey = i % 2 === 0;
+				const want = isKey ? key : value;
+				const t = checkExpr(c, a.value, isDynamic(want) ? undefined : want);
+				c.markCopy(a.value);
+				if (!isDynamic(want)) {
+					c.expectAssignable(want, t, a.value.span, isKey ? "dictionary key" : "dictionary value");
+				} else if (isKey) {
+					inferredKey = join(c, inferredKey, widenLiteral(t));
+				} else {
+					inferredValue = join(c, inferredValue, widenLiteral(t));
+				}
+			});
+			builtin();
+			if (!typeArgs && e.args.length && isDynamic(key)) {
+				return T.dict(prune(inferredKey).k === "never" ? T.any : inferredKey, prune(inferredValue).k === "never" ? T.any : inferredValue);
+			}
+			return T.dict(key, value);
+		}
+		case "push": {
+			arity(c, e, "push", 2);
+			const list = listOf(c, argValue(e, 0), "push");
+			requireMutableList(c, argValue(e, 0), "push");
+			const v = argValue(e, 1);
+			if (v) {
+				const want = list ? elementSlot(list, prune(checkExpr(c, v, list.typed && !isDynamic(list.elem) ? list.elem : undefined))) : T.any;
+				if (list && list.typed) {
+					c.expectAssignable(want, v.ty ?? T.unknown, v.span, "push");
+				}
+				c.markCopy(v);
+			}
+			builtin();
+			return T.void;
+		}
+		case "pop": {
+			arity(c, e, "pop", 1);
+			const list = listOf(c, argValue(e, 0), "pop");
+			requireMutableList(c, argValue(e, 0), "pop");
+			builtin();
+			return list ? list.elem : T.any;
+		}
+		case "insert": {
+			arity(c, e, "insert", 3);
+			const list = listOf(c, argValue(e, 0), "insert");
+			requireMutableList(c, argValue(e, 0), "insert");
+			const i = argValue(e, 1);
+			if (i) {
+				const it = checkExpr(c, i);
+				if (!isIntLike(it) && !isDynamic(it)) {
+					c.error("CL3060", i.span, `insert position must be int, got ${typeToString(it)}`);
+				}
+			}
+			const v = argValue(e, 2);
+			if (v) {
+				const vt = checkExpr(c, v, list?.elem);
+				if (list) {
+					c.expectAssignable(elementSlot(list, vt), vt, v.span, "insert");
+				}
+				c.markCopy(v);
+			}
+			builtin();
+			return T.void;
+		}
+		case "remove": {
+			arity(c, e, "remove", 2);
+			const target = argValue(e, 0);
+			const t = target ? prune(checkExpr(c, target)) : T.unknown;
+			requireMutableList(c, target, "remove");
+			const k = argValue(e, 1);
+			const kt = k ? checkExpr(c, k) : T.unknown;
+			if (t.k === "list") {
+				if (!isIntLike(kt) && !isDynamic(kt)) {
+					c.error("CL3060", k!.span, `remove position must be int, got ${typeToString(kt)}`);
+				}
+				builtin(T.list(T.any));
+				return t.elem;
+			}
+			if (t.k === "dict") {
+				if (assignable(c, t.key, kt) === "no") {
+					c.error("CL3063", k!.span, `dictionary key must be ${typeToString(t.key)}`);
+				}
+				builtin(T.dict(T.any, T.any));
+				return t.value;
+			}
+			if (!isDynamic(t)) {
+				c.error("CL3103", target?.span ?? e.span, `remove needs a list or dictionary, got ${typeToString(t)}`);
+			}
+			builtin();
+			return T.any;
+		}
+		case "find": {
+			arity(c, e, "find", 2);
+			const list = listOf(c, argValue(e, 0), "find");
+			const v = argValue(e, 1);
+			if (v) {
+				const vt = checkExpr(c, v, list?.elem);
+				if (list && assignable(c, list.elem, vt) === "no" && assignable(c, vt, list.elem) === "no") {
+					c.error("CL3107", v.span, `find looks for ${typeToString(list.elem)}, got ${typeToString(vt)}`);
+				}
+			}
+			builtin(list?.elem);
+			return T.int;
+		}
+		case "sort": {
+			arity(c, e, "sort", 1);
+			const list = listOf(c, argValue(e, 0), "sort");
+			if (list && !isNumeric(list.elem) && !isStringLike(list.elem) && !isDynamic(list.elem)) {
+				c.error("CL3108", e.span, `sort orders numbers or text, not ${typeToString(list.elem)}`);
+			}
+			builtin();
+			return list ?? T.list(T.any);
+		}
+		case "args":
+			c.error("RBX5100", e.span, "args() has no meaning on Roblox: scripts get no command line");
+			builtin();
+			return T.list(T.string);
+		case "actor":
+			c.error("RBX5100", e.span, "actor(...) is the clpp VM sandbox; on Roblox use an Actor instance with parallel Luau");
+			checkArgsLoose(c, e);
+			builtin();
+			return T.any;
+		case "mutex":
+			arity(c, e, "mutex", 0);
+			builtin();
+			return T.datatype("__Mutex");
+		case "lock":
+		case "unlock": {
+			arity(c, e, name, 1);
+			checkArgsLoose(c, e);
+			if (name === "lock") {
+				c.noteYield();
+			}
+			builtin();
+			return T.void;
+		}
+		case "fetch_add":
+		case "atomic_load": {
+			arity(c, e, name, name === "fetch_add" ? 2 : 1);
+			const a = argValue(e, 0);
+			if (a) {
+				checkExpr(c, a);
+				const sym = a.kind === "Name" ? c.scope.lookup(a.name) : undefined;
+				if (!sym || !sym.atomic) {
+					c.error("CL3109", a.span, `${name} needs a variable declared with \`atomic\``);
+				}
+			}
+			if (name === "fetch_add" && argValue(e, 1)) {
+				checkExpr(c, argValue(e, 1)!);
+			}
+			builtin();
+			return T.int;
+		}
+		case "Some": {
+			arity(c, e, "Some", 1);
+			const ex = expected ? prune(expected) : null;
+			const inner = ex && ex.k === "option" ? ex.inner : undefined;
+			const t = argValue(e, 0) ? checkExpr(c, argValue(e, 0)!, inner) : T.unknown;
+			if (prune(t).k === "option" || prune(t).k === "null") {
+				c.error("CL3110", e.span, "Some(…) of a value that may already be null cannot be told apart from None on Roblox");
+			}
+			if (argValue(e, 0)) {
+				c.markCopy(argValue(e, 0)!);
+			}
+			setCall(e, { form: "some" }, e.args.map((a) => a.value));
+			return T.option(inner ?? widenLiteral(t));
+		}
+		case "Ok":
+		case "Err": {
+			arity(c, e, name, 1);
+			const ex = expected ? prune(expected) : null;
+			const res = ex && ex.k === "result" ? ex : null;
+			const want = res ? (name === "Ok" ? res.ok : res.err) : undefined;
+			const t = argValue(e, 0) ? widenLiteral(checkExpr(c, argValue(e, 0)!, want)) : T.unknown;
+			if (argValue(e, 0)) {
+				c.markCopy(argValue(e, 0)!);
+			}
+			setCall(e, { form: name === "Ok" ? "ok" : "err" }, e.args.map((a) => a.value));
+			return name === "Ok" ? { k: "result", ok: res?.ok ?? t, err: res?.err ?? T.any } : { k: "result", ok: res?.ok ?? T.any, err: res?.err ?? t };
+		}
+		case "int":
+		case "float":
+		case "bool":
+		case "string": {
+			arity(c, e, name, 1);
+			const x = argValue(e, 0);
+			const t = x ? prune(checkExpr(c, x)) : T.unknown;
+			if ((name === "int" || name === "float") && !isNumeric(t) && !isStringLike(t) && !isDynamic(t) && t.k !== "enum" && t.k !== "rbxEnumItem") {
+				c.error("CL3111", x?.span ?? e.span, `cannot convert ${typeToString(t)} to ${name}`);
+			}
+			if ((name === "int" || name === "float") && isStringLike(t)) {
+				c.warn("CL3112", x!.span, `${name}(text) is null-free on Roblox only if the text is a number`, ["prefer Text.toNumber(text), which reports bad input"]);
+			}
+			setCall(e, { form: "convert", to: name }, [x]);
+			return name === "int" ? T.int : name === "float" ? T.float : name === "bool" ? T.bool : T.string;
+		}
+		case "GetService": {
+			let service: string | null = null;
+			if (typeArgs && typeArgs.length === 1 && typeArgs[0].kind === "Named") {
+				service = typeArgs[0].name;
+			} else if (e.args.length === 1 && e.args[0].value.kind === "String") {
+				service = e.args[0].value.value;
+			}
+			if (!service) {
+				c.error("RBX5050", e.span, "GetService needs the service name: GetService<Players>() or GetService(\"Players\")");
+				return T.unknown;
+			}
+			return serviceCall(c, e, service, e.span);
+		}
+		default:
+			return T.unknown;
+	}
+}
+
+function serviceCall(c: Checker, e: CallExpr, service: string, span: Expr["span"]): Type {
+	if (!c.api.isService(service)) {
+		const s = suggest(service, c.api.services);
+		c.error("RBX5051", span, `'${service}' is not a Roblox service`, s ? [`did you mean ${s}?`] : undefined);
+		return T.unknown;
+	}
+	c.useService(service, span);
+	setCall(e, { form: "service", service }, []);
+	const dm = c.input.dataModel?.children.get(service);
+	return { k: "instance", cls: service, ...(dm ? { dm } : {}) };
+}
+
+// ---------- member calls ----------
+
+function checkMemberCall(c: Checker, e: CallExpr, callee: Extract<Expr, { kind: "Member" }>, expected?: Type): Type {
+	const t = prune(checkMember(c, callee, undefined, { forCall: true }));
+	const res = callee.res;
+	if (!res) {
+		return finishCall(c, e, t, callee.span, { form: "call" }, expected);
+	}
+	switch (res.kind) {
+		case "enumCase":
+			if (res.hasPayload) {
+				const fn = t as FnType;
+				const r = checkArgs(c, e, fn, callee.span, null);
+				setCall(e, { form: "enumCase", enumId: res.enumName, index: res.index }, r.args);
+				return fn.ret;
+			}
+			c.error("CL3113", e.span, `this enum case carries no value; write it without parentheses`);
+			return t;
+		case "moduleMember":
+			if (res.memberKind === "struct" && t.k === "namespace" && t.ns.kind === "struct") {
+				return constructStruct(c, e, t.ns.id, callee.typeArgs, e.args, expected);
+			}
+			break;
+		case "builtin":
+			if (res.name === "OnChange") {
+				const fn = t as FnType;
+				const r = checkArgs(c, e, fn, callee.span, null);
+				const sym = c.scope.lookup((callee.object as Extract<Expr, { kind: "Name" }>).name)!;
+				(sym.handlers ||= []).push(...(r.args.filter(Boolean) as Expr[]));
+				setCall(e, { form: "observe", sym }, r.args);
+				return T.void;
+			}
+			break;
+		case "stdlib": {
+			const fn = t as FnType;
+			const r = checkArgs(c, e, fn, callee.span, null);
+			setCall(e, { form: "std", module: res.module, fn: res.member }, r.args);
+			if (res.module === "axiom" && INT_PRESERVING.has(res.member) && r.args.length && r.args.every((a) => a && isIntLike(a.ty ?? T.any))) {
+				return T.int;
+			}
+			return fn.ret;
+		}
+		case "library":
+			if (res.stringMethod) {
+				const r = checkArgs(c, e, t as FnType, callee.span, null);
+				setCall(e, { form: "stringMethod", name: callee.name }, r.args, r.rest);
+				return prune((t as FnType).ret);
+			}
+			break;
+		case "datatypeStatic":
+			if (res.datatype === "Instance" && res.member === "new") {
+				return instanceNewCall(c, e, callee);
+			}
+			break;
+		case "rbxMethod":
+			if (callee.name === "GetService" && (callee.typeArgs || e.args[0]?.value.kind === "String")) {
+				const name = callee.typeArgs?.[0]?.kind === "Named" ? callee.typeArgs[0].name : e.args[0]?.value.kind === "String" ? e.args[0].value.value : null;
+				if (name) {
+					return serviceCall(c, e, name, e.span);
+				}
+			}
+			if (callee.typeArgs && callee.typeArgs.length) {
+				return genericRobloxCall(c, e, callee, t as FnType, expected);
+			}
+			if (CLASS_ARG_METHODS.has(callee.name) && e.args[0]?.value.kind === "String") {
+				const cls = e.args[0].value.value;
+				if (!c.api.hasClass(cls)) {
+					const s = suggest(cls, Object.keys(c.api.classes));
+					c.error("RBX5052", e.args[0].value.span, `'${cls}' is not a Roblox class`, s ? [`did you mean "${s}"?`] : undefined);
+				}
+				const r = checkArgs(c, e, t as FnType, callee.span, null);
+				setCall(e, { form: "call" }, r.args, r.rest);
+				const ret = prune((t as FnType).ret);
+				if (c.api.hasClass(cls) && callee.name !== "IsA") {
+					return ret.k === "option" ? T.option(T.instance(cls)) : T.instance(cls);
+				}
+				return ret;
+			}
+			break;
+		case "datatypeMember":
+			if (res.datatype === "RBXScriptSignal" && (callee.name === "Connect" || callee.name === "Once" || callee.name === "ConnectParallel")) {
+				const signal = prune(callee.object.ty ?? T.any);
+				const r = checkArgs(c, e, t as FnType, callee.span, null);
+				if (signal.k === "rbxSignal" && r.args[0]) {
+					handlerCheck(c, r.args[0], signal.args);
+				}
+				setCall(e, { form: "call" }, r.args);
+				return T.datatype("RBXScriptConnection");
+			}
+			break;
+		default:
+			break;
+	}
+	if (t.k === "namespace" && t.ns.kind === "struct") {
+		return constructStruct(c, e, t.ns.id, callee.typeArgs, e.args, expected);
+	}
+	if (t.k === "namespace" && t.ns.kind === "datatype") {
+		return constructDatatype(c, e, t.ns.name, e.args);
+	}
+	return finishCall(c, e, t, callee.span, { form: "call" }, expected, callee.typeArgs);
+}
+
+function handlerCheck(c: Checker, handler: Expr, args: Type[]): void {
+	checkHandler(c, handler.ty ?? T.any, args, handler.span);
+}
+
+/** `x.WaitForChild<Model>("Map")`, `x.FindFirstChildOfClass<Humanoid>()`, `x.IsA<BasePart>()`. */
+function genericRobloxCall(c: Checker, e: CallExpr, callee: Extract<Expr, { kind: "Member" }>, fn: FnType, expected?: Type): Type {
+	const node = callee.typeArgs![0];
+	const target = c.resolveType(node);
+	const p = prune(target);
+	if (p.k !== "instance") {
+		c.error("RBX5053", node.span, `${callee.name}<…> needs a Roblox class, got ${typeToString(target)}`);
+		const r = checkArgs(c, e, fn, callee.span, null);
+		setCall(e, { form: "call" }, r.args, r.rest);
+		return fn.ret;
+	}
+	if (CLASS_ARG_METHODS.has(callee.name)) {
+		const shifted: FnType = { ...fn, params: fn.params.slice(1) };
+		const r = checkArgs(c, e, shifted, callee.span, null);
+		setCall(e, { form: "classArg", cls: p.cls, cast: callee.name !== "IsA" }, r.args, r.rest);
+		const ret = prune(fn.ret);
+		if (callee.name === "IsA") {
+			return T.bool;
+		}
+		return ret.k === "option" ? T.option(p) : p;
+	}
+	if (CAST_RESULT_METHODS.has(callee.name)) {
+		const r = checkArgs(c, e, fn, callee.span, null);
+		setCall(e, { form: "cast", to: p }, r.args, r.rest);
+		const ret = prune(fn.ret);
+		return ret.k === "option" ? T.option(p) : p;
+	}
+	c.error("RBX5054", node.span, `${callee.name} does not take a type argument`, [
+		`type arguments work on ${[...CLASS_ARG_METHODS, ...CAST_RESULT_METHODS].join(", ")}`,
+	]);
+	void expected;
+	return finishCall(c, e, fn, callee.span, { form: "call" }, undefined);
+}
+
+function instanceNewCall(c: Checker, e: CallExpr, callee: Extract<Expr, { kind: "Member" }>): Type {
+	const first = e.args[0]?.value;
+	checkArgsLoose(c, e);
+	setCall(e, { form: "call" }, e.args.map((a) => a.value));
+	if (!first || first.kind !== "String") {
+		if (first && !isStringLike(first.ty ?? T.any) && !isDynamic(first.ty ?? T.any)) {
+			c.error("RBX5055", first.span, "Instance.new needs a class name");
+		}
+		return T.instance("Instance");
+	}
+	const cls = first.value;
+	const problem = c.api.creationError(cls);
+	if (problem) {
+		const s = c.api.hasClass(cls) ? null : suggest(cls, Object.keys(c.api.classes));
+		c.error("RBX5056", first.span, problem, s ? [`did you mean "${s}"?`] : undefined);
+		return T.unknown;
+	}
+	if (e.args.length > 1) {
+		c.warn("PERF8001", e.args[1].value.span, "Instance.new with a parent sets Parent before the other properties (slow replication)", [
+			`create it first and set Parent last, or write ${cls}(Name: …, Parent: …)`,
+		]);
+	}
+	if (c.api.classes[cls].deprecated) {
+		c.warn("RBX5010", first.span, `${cls} is deprecated`);
+	}
+	void callee;
+	return T.instance(cls);
+}
+
+// ---------- construction ----------
+
+export function checkNew(c: Checker, e: Extract<Expr, { kind: "New" }>, expected?: Type): Type {
+	const target = e.target;
+	const asCall: CallExpr = { kind: "Call", callee: target, args: e.args, span: e.span };
+	let t: Type;
+	if (target.kind === "Name" && !c.scope.lookup(target.name) && c.api.hasClass(target.name)) {
+		c.requireRoblox(target.span, target.name);
+		target.res = { kind: "global", luau: target.name };
+		t = constructInstance(c, asCall, target.name, e.args, target.span);
+	} else {
+		t = checkCall(c, asCall, expected);
+		const form = asCall.res?.kind === "call" ? asCall.res.call.form : "call";
+		if (form !== "struct" && form !== "instance" && form !== "datatype") {
+			c.error("CL3114", e.span, "`new` builds a struct, a Roblox Instance or a datatype");
+		}
+	}
+	e.res = asCall.res;
+	return t;
+}
+
+function constructStruct(c: Checker, e: CallExpr, id: string, typeArgs: TypeNode[] | null, args: Arg[], expected?: Type): Type {
+	const info = c.structs.get(id);
+	if (!info) {
+		checkArgsLoose(c, e);
+		return T.unknown;
+	}
+	c.resolveStruct(info, new Set());
+	if (info.isAbstract) {
+		c.error("CL3115", e.span, `abstract type ${info.name} cannot be constructed`, ["construct one of the structs that inherit from it"]);
+	}
+	const bindings = new Map<string, Type>();
+	if (typeArgs && typeArgs.length) {
+		if (typeArgs.length !== info.typeParams.length) {
+			c.error("CL3001", e.span, `${info.name} takes ${info.typeParams.length} type argument(s)`);
+		}
+		info.typeParams.forEach((p, i) => typeArgs[i] && bindings.set(p, c.resolveType(typeArgs[i])));
+	} else if (expected && prune(expected).k === "struct" && (prune(expected) as Extract<Type, { k: "struct" }>).id === id) {
+		const ex = prune(expected) as Extract<Type, { k: "struct" }>;
+		info.typeParams.forEach((p, i) => ex.args[i] && prune(ex.args[i]).k !== "param" && bindings.set(p, ex.args[i]));
+	}
+	const params: FnParam[] = info.fields.map((f) => ({ name: f.name, type: f.type, optional: f.defaultValue !== null }));
+	const fn: FnType = { k: "func", params, ret: T.void, variadic: null };
+	const r = checkArgs(c, e, fn, e.callee.span, null, bindings);
+	setCall(e, { form: "struct", id }, r.args);
+	const args2 = info.typeParams.map((p) => bindings.get(p) ?? ({ k: "param", name: p } as Type));
+	void args;
+	return { k: "struct", id, name: info.name, args: info.typeParams.length ? args2 : [] };
+}
+
+function constructInstance(c: Checker, e: CallExpr, cls: string, args: Arg[], span: Expr["span"]): Type {
+	const problem = c.api.creationError(cls);
+	if (problem) {
+		c.error("RBX5056", span, problem);
+	}
+	if (c.api.classes[cls]?.deprecated) {
+		c.warn("RBX5010", span, `${cls} is deprecated`);
+	}
+	const props: Arg[] = [];
+	let parent: Expr | null = null;
+	for (const a of args) {
+		if (a.name === null) {
+			if (parent) {
+				c.error("RBX5057", a.value.span, `${cls}(…) takes properties by name; only one positional argument (the Parent) is allowed`, [`${cls}(Name: "X", Parent: workspace)`]);
+				checkExpr(c, a.value);
+				continue;
+			}
+			parent = a.value;
+			const pt = checkExpr(c, a.value);
+			c.expectAssignable(T.option(T.instance("Instance")), pt, a.value.span, "Parent");
+			continue;
+		}
+		const hit = c.api.member(cls, a.name);
+		if (!hit || (hit.member.kind !== "property" && hit.member.kind !== "callback")) {
+			const props2 = [...c.api.members(cls)].filter(([, h]) => h.member.kind === "property").map(([n]) => n);
+			const s = suggest(a.name, props2);
+			c.error("RBX5058", a.nameSpan ?? a.value.span, `${cls} has no property '${a.name}'`, s ? [`did you mean '${s}'?`] : undefined);
+			checkExpr(c, a.value);
+			continue;
+		}
+		if (hit.member.readonly) {
+			c.error("RBX5030", a.nameSpan ?? a.value.span, `${hit.owner}.${a.name} is read-only`);
+		}
+		const want = hit.member.type ? c.api.convert(hit.member.type) : T.any;
+		const vt = checkExpr(c, a.value, want);
+		c.expectAssignable(want, vt, a.value.span, `${cls}.${a.name}`);
+		if (a.name === "Parent") {
+			parent = a.value;
+			continue;
+		}
+		props.push(a);
+	}
+	setCall(e, { form: "instance", cls, props, parent }, []);
+	return T.instance(cls);
+}
+
+function constructDatatype(c: Checker, e: CallExpr, name: string, args: Arg[]): Type {
+	if (name !== "Vector3" && name !== "Vector2") {
+		c.requireRoblox(e.callee.span, name);
+	}
+	const positional = args.filter((a) => a.name === null);
+	const named = args.filter((a) => a.name !== null);
+	const ctor = c.api.datatypeStatic(name, "new");
+	if (!ctor || ctor.kind !== "function") {
+		c.error("RBX5059", e.callee.span, `${name} has no constructor`, Object.keys(c.api.datatypes[name]?.statics ?? {}).length ? [`use ${name}.${Object.keys(c.api.datatypes[name].statics)[0]}(…)`] : undefined);
+		checkArgsLoose(c, e);
+		return T.datatype(name);
+	}
+	const fn = prune(c.api.staticFunctionType(ctor)) as FnType;
+	const fake: CallExpr = { kind: "Call", callee: e.callee, args: positional, span: e.span };
+	const r = checkArgs(c, fake, fn, e.callee.span, null);
+	for (const a of named) {
+		const m = c.api.datatypeMember(name, a.name!);
+		if (!m || m.kind !== "property") {
+			c.error("RBX5058", a.nameSpan ?? a.value.span, `${name} has no property '${a.name}'`);
+			checkExpr(c, a.value);
+			continue;
+		}
+		const want = m.type ? c.api.convert(m.type) : T.any;
+		const vt = checkExpr(c, a.value, want);
+		c.expectAssignable(want, vt, a.value.span, `${name}.${a.name}`);
+	}
+	setCall(e, { form: "datatype", name, props: named }, r.args, r.rest);
+	return T.datatype(name);
+}
+
+function fireSignal(c: Checker, e: CallExpr, sym: Sym): Type {
+	sym.used = true;
+	(e.callee as Extract<Expr, { kind: "Name" }>).res = { kind: "signal", sym };
+	e.callee.ty = sym.type;
+	const types = checkArgsLoose(c, e);
+	if (sym.signalParams) {
+		if (types.length !== sym.signalParams.length) {
+			c.error("CL3102", e.span, `signal ${sym.name} passes ${sym.signalParams.length} value(s), got ${types.length}`);
+		}
+		types.forEach((t, i) => sym.signalParams![i] && c.expectAssignable(sym.signalParams![i], t, e.args[i].value.span, `signal ${sym.name}`));
+	}
+	setCall(e, { form: "signalFire", sym }, e.args.map((a) => a.value));
+	return T.void;
+}
+
+// ---------- generic calls ----------
+
+function finishCall(c: Checker, e: CallExpr, t: Type, calleeSpan: Expr["span"], form: CallForm, expected?: Type, typeArgs?: TypeNode[] | null): Type {
+	const p = prune(t);
+	const callee = e.callee;
+	const explicitTypeArgs = typeArgs ?? (callee.kind === "Name" ? callee.typeArgs : null);
+	if (p.k === "func") {
+		const decl = calleeDecl(c, callee);
+		const bindings = new Map<string, Type>();
+		if (explicitTypeArgs && explicitTypeArgs.length) {
+			const names = p.generics ?? [];
+			if (names.length !== explicitTypeArgs.length) {
+				c.error("CL3001", calleeSpan, `this function takes ${names.length} type argument(s), got ${explicitTypeArgs.length}`);
+			}
+			names.forEach((n, i) => explicitTypeArgs[i] && bindings.set(n, c.resolveType(explicitTypeArgs[i])));
+			for (const w of decl?.where ?? []) {
+				const bound = bindings.get(w.name);
+				const constraint = c.resolveType(w.type);
+				if (bound && assignable(c, constraint, bound) === "no") {
+					c.error("CL3116", calleeSpan, `${w.name} must be ${typeToString(constraint)}, got ${typeToString(bound)}`);
+				}
+			}
+		}
+		const r = checkArgs(c, e, p, calleeSpan, decl, bindings);
+		setCall(e, form, r.args, r.rest);
+		const sym = callee.res && (callee.res.kind === "func" || callee.res.kind === "local") ? (callee.res.sym as Sym) : null;
+		if (sym?.contextOnly) {
+			c.checkContext(sym.contextOnly, calleeSpan, `${sym.name}()`, `it is marked [[${sym.contextOnly}]]`);
+		}
+		let ret = r.fn.ret;
+		if (decl && prune(ret).k === "infer" && !(prune(ret) as { resolved: Type | null }).resolved) {
+			c.ensureBodyChecked(decl);
+			ret = r.fn.ret;
+		}
+		if (decl?.fn?.mayYield || (decl && c.isChecking(decl))) {
+			c.noteYield();
+		}
+		if (callee.kind === "Member" && callee.res?.kind === "method") {
+			const info = c.structs.get(callee.res.struct);
+			const m = info?.methods.get(callee.name);
+			const root = rootSymbol(callee.object);
+			if (m && root) {
+				c.mutatingCalls.push({ root, method: m, span: e.span });
+			}
+		}
+		const out = substitute(prune(ret), bindings);
+		return prune(out).k === "infer" ? T.any : out;
+	}
+	checkArgsLoose(c, e);
+	setCall(e, form, e.args.map((a) => a.value));
+	if (isDynamic(p)) {
+		if (callee.kind === "Member" && callee.res?.kind === "dynamic" && /^[A-Z]/.test(callee.name) && c.strict) {
+			c.warn("CL3117", callee.nameSpan, `'${callee.name}' is called on a dynamic value; for a Luau method use '::'`, [`x::${callee.name}(…) emits x:${callee.name}(…)`]);
+		}
+		return T.any;
+	}
+	if (p.k === "clSignal") {
+		return T.void;
+	}
+	c.error("CL3118", calleeSpan, `${typeToString(p)} is not callable`);
+	void expected;
+	return T.unknown;
+}
+
+function calleeDecl(c: Checker, callee: Expr): FuncDecl | null {
+	const res = callee.res;
+	if (!res) {
+		return null;
+	}
+	if (res.kind === "func") {
+		return (res.sym as Sym).decl ?? null;
+	}
+	if (res.kind === "method") {
+		return c.structs.get(res.struct)?.methods.get(callee.kind === "Member" || callee.kind === "SelfField" ? callee.name : "")?.decl ?? null;
+	}
+	return null;
+}
+
+export interface CheckedArgs {
+	args: Array<Expr | null>;
+	rest: Expr[];
+	fn: FnType;
+}
+
+/** Match arguments to parameters (named, defaults, variadic), choose an overload, bind generics. */
+export function checkArgs(c: Checker, e: CallExpr, fn: FnType, calleeSpan: Expr["span"], decl: FuncDecl | null, bindings: Map<string, Type> = new Map()): CheckedArgs {
+	const overloads = (fn.overloads as FnType[] | undefined) ?? [fn];
+	let chosen = overloads[0];
+	if (overloads.length > 1) {
+		const positional = e.args.filter((a) => a.name === null).map((a) => checkExpr(c, a.value));
+		const fits = (o: FnType) => {
+			const required = o.params.filter((p) => !p.optional).length;
+			if (positional.length < required || (positional.length > o.params.length && !o.variadic)) {
+				return false;
+			}
+			return positional.every((t, i) => {
+				const want = o.params[i]?.type ?? o.variadic ?? T.any;
+				return assignable(c, want, t) === "ok";
+			});
+		};
+		const match = overloads.find(fits);
+		if (!match) {
+			const sigs = overloads.map((o) => `(${o.params.map((p) => `${p.name}: ${typeToString(p.type)}${p.optional ? "?" : ""}`).join(", ")})`);
+			c.error("CL3119", calleeSpan, `no overload accepts (${positional.map((t) => typeToString(t)).join(", ")})`, sigs.slice(0, 6).map((s) => `candidate ${s}`));
+			return { args: e.args.map((a) => a.value), rest: [], fn: chosen };
+		}
+		chosen = match;
+	}
+	const params = chosen.params;
+	const slots: Array<Expr | null> = params.map(() => null);
+	const rest: Expr[] = [];
+	let position = 0;
+	let named = false;
+	for (const a of e.args) {
+		if (a.name !== null) {
+			named = true;
+			const idx = params.findIndex((p) => p.name === a.name);
+			if (idx < 0) {
+				const s = suggest(a.name, params.map((p) => p.name));
+				c.error("CL3120", a.nameSpan ?? a.value.span, `no parameter named '${a.name}'`, s ? [`did you mean '${s}'?`] : [`parameters: ${params.map((p) => p.name).join(", ") || "none"}`]);
+				checkExpr(c, a.value);
+				continue;
+			}
+			if (slots[idx]) {
+				c.error("CL3121", a.nameSpan ?? a.value.span, `'${a.name}' is passed twice`);
+			}
+			slots[idx] = a.value;
+			continue;
+		}
+		if (named) {
+			c.error("CL3122", a.value.span, "positional arguments must come before named ones");
+		}
+		if (position < params.length) {
+			slots[position++] = a.value;
+		} else if (chosen.variadic) {
+			rest.push(a.value);
+			position++;
+		} else {
+			position++;
+		}
+	}
+	const given = e.args.length;
+	const max = chosen.variadic ? Infinity : params.length;
+	if (given > max) {
+		c.error("CL3123", calleeSpan, `wrong number of arguments: expected ${params.length}, got ${given}`);
+	}
+	params.forEach((p, i) => {
+		const arg = slots[i];
+		if (!arg) {
+			if (!p.optional) {
+				c.error("CL3124", calleeSpan, `missing argument '${p.name}' (${typeToString(substitute(p.type, bindings))})`);
+			}
+			return;
+		}
+		let want = substitute(p.type, bindings);
+		const wantPruned = prune(want);
+		const learning = wantPruned.k === "infer" && !wantPruned.resolved;
+		const t = checkExpr(c, arg, learning ? undefined : want);
+		if (learning) {
+			// Learn the parameter type from its first call site.
+			const learned = widenLiteral(t);
+			if (prune(learned).k !== "null" && !isDynamic(learned)) {
+				(wantPruned as { resolved: Type | null }).resolved = learned;
+			}
+			want = learned;
+		} else {
+			bindGenerics(p.type, t, bindings);
+			want = substitute(p.type, bindings);
+			c.expectAssignable(want, t, arg.span, `argument '${p.name}'`);
+		}
+		if (decl) {
+			c.deferredCopies.push({ arg, decl, index: i });
+		} else {
+			c.markCopy(arg);
+		}
+	});
+	for (const r of rest) {
+		const t = checkExpr(c, r, chosen.variadic ?? undefined);
+		if (chosen.variadic && !isDynamic(chosen.variadic)) {
+			c.expectAssignable(substitute(chosen.variadic, bindings), t, r.span, "argument");
+		}
+		c.markCopy(r);
+	}
+	const resolvedFn: FnType = bindings.size ? (substitute(chosen, bindings) as FnType) : chosen;
+	return { args: trimTrailingNulls(slots), rest, fn: resolvedFn };
+}
+
+function trimTrailingNulls(args: Array<Expr | null>): Array<Expr | null> {
+	let end = args.length;
+	while (end > 0 && args[end - 1] === null) {
+		end--;
+	}
+	return args.slice(0, end);
+}
+
+export function joinTypes(c: Checker, types: Type[]): Type {
+	return types.reduce((a, b) => join(c, a, b), T.never);
+}
+
+export { nonNull };
+export type { StructInfo };