cluaupp 1.5.2 → 2.0.0-beta.2

package/src/compiler/checker/members.ts

@@ -0,0 +1,793 @@
+/** Member access: CL++ structs/modules/enums and the Roblox API (properties, methods, events, children). */
+
+import type { Expr } from "../ast.js";
+import { suggest } from "../diagnostics.js";
+import type { SurfaceMember } from "../../api/surface/model.js";
+import { MEMBER_RULES, RISKY_MEMBERS } from "../roblox/context.js";
+import { stdFunctionType, stdModule } from "../stdlib.js";
+import { isDynamic, prune, T, typeToString, type DataModelNode, type Namespace, type Type } from "../types.js";
+import type { Checker } from "./checker.js";
+import { checkExpr, exprPathKey, rootSymbol } from "./exprs.js";
+import type { ModuleExports, StructInfo, Sym } from "./symbols.js";
+import { substitute } from "./typeops.js";
+
+const VECTOR_COMPONENTS: Record<string, string[]> = {
+	Vector3: ["x", "y", "z"],
+	Vector2: ["x", "y"],
+	Vector3int16: ["x", "y", "z"],
+	Vector2int16: ["x", "y"],
+};
+
+const SIGNAL_METHODS = new Set(["Connect", "Once", "ConnectParallel", "Wait"]);
+
+/** `string` library members usable with method syntax: `name.upper()` → `name:upper()`. */
+const STRING_METHODS = new Set(["byte", "find", "format", "gmatch", "gsub", "len", "lower", "match", "rep", "reverse", "split", "sub", "upper"]);
+
+export interface MemberContext {
+	/** The member is being called (methods are fine). */
+	forCall: boolean;
+}
+
+export function checkMember(c: Checker, e: Extract<Expr, { kind: "Member" }>, expected?: Type, ctx: MemberContext = { forCall: false }): Type {
+	// observable: `coins.OnChange(f)`
+	if (e.name === "OnChange" && e.object.kind === "Name") {
+		const sym = c.scope.lookup(e.object.name);
+		if (sym && sym.observable) {
+			sym.used = true;
+			e.object.res = { kind: "local", sym };
+			e.object.ty = sym.type;
+			e.res = { kind: "builtin", name: "OnChange" };
+			return T.func([{ name: "handler", type: T.func([{ name: "value", type: sym.type, optional: false }], T.void), optional: false }], T.void);
+		}
+	}
+	const objType = prune(checkExpr(c, e.object));
+	return memberOf(c, e, objType, expected, ctx);
+}
+
+export function memberOf(c: Checker, e: Extract<Expr, { kind: "Member" }>, objType: Type, expected: Type | undefined, ctx: MemberContext): Type {
+	const name = e.name;
+	switch (objType.k) {
+		case "namespace":
+			return namespaceMember(c, e, objType.ns, ctx);
+		case "rbxEnums": {
+			if (name === "GetEnums") {
+				e.res = { kind: "rbxMethod", owner: "Enums" };
+				return T.func([], T.list({ k: "rbxEnum", enumName: "*" }));
+			}
+			if (!c.api.hasEnum(name)) {
+				const s = suggest(name, Object.keys(c.api.enums));
+				c.error("RBX5001", e.nameSpan, `Enum.${name} is not a Roblox enum`, s ? [`did you mean Enum.${s}?`] : undefined);
+				return T.unknown;
+			}
+			e.res = { kind: "rbxEnum", enumName: name };
+			return { k: "rbxEnum", enumName: name };
+		}
+		case "rbxEnum": {
+			if (name === "GetEnumItems" || name === "FromName" || name === "FromValue") {
+				requireCall(c, e, ctx);
+				e.res = { kind: "rbxMethod", owner: "Enum" };
+				const item: Type = { k: "rbxEnumItem", enumName: objType.enumName };
+				if (name === "GetEnumItems") {
+					return T.func([], T.list(item));
+				}
+				return T.func([{ name: name === "FromName" ? "name" : "value", type: name === "FromName" ? T.string : T.int, optional: false }], T.option(item));
+			}
+			const en = c.api.enums[objType.enumName];
+			if (!en || !en.items.includes(name)) {
+				const s = en ? suggest(name, en.items) : null;
+				c.error("RBX5003", e.nameSpan, `Enum.${objType.enumName} has no item '${name}'`, s ? [`did you mean Enum.${objType.enumName}.${s}?`] : en ? [`items: ${en.items.slice(0, 12).join(", ")}${en.items.length > 12 ? ", …" : ""}`] : undefined);
+				return T.unknown;
+			}
+			if (en.deprecated?.includes(name)) {
+				c.warn("RBX5010", e.nameSpan, `Enum.${objType.enumName}.${name} is deprecated`);
+			}
+			e.res = { kind: "rbxEnumItem", enumName: objType.enumName, item: name };
+			return { k: "rbxEnumItem", enumName: objType.enumName };
+		}
+		case "rbxEnumItem":
+			switch (name) {
+				case "Name":
+					e.res = { kind: "rbxProperty", owner: "EnumItem" };
+					return T.string;
+				case "Value":
+					e.res = { kind: "rbxProperty", owner: "EnumItem" };
+					return T.int;
+				case "EnumType":
+					e.res = { kind: "rbxProperty", owner: "EnumItem" };
+					return { k: "rbxEnum", enumName: objType.enumName };
+				case "IsA":
+					requireCall(c, e, ctx);
+					e.res = { kind: "rbxMethod", owner: "EnumItem" };
+					return T.func([{ name: "enumName", type: T.string, optional: false }], T.bool);
+				default:
+					c.error("RBX5004", e.nameSpan, `an EnumItem has Name, Value and EnumType, not '${name}'`);
+					return T.unknown;
+			}
+		case "instance":
+			return instanceMember(c, e, objType, ctx);
+		case "datatype":
+			return datatypeMember(c, e, objType.name, ctx);
+		case "rbxSignal": {
+			if (!SIGNAL_METHODS.has(name)) {
+				const s = suggest(name, [...SIGNAL_METHODS]);
+				c.error("RBX5005", e.nameSpan, `an event has Connect, Once, ConnectParallel and Wait, not '${name}'`, s ? [`did you mean '${s}'?`] : undefined);
+				return T.unknown;
+			}
+			requireCall(c, e, ctx);
+			e.res = { kind: "datatypeMember", datatype: "RBXScriptSignal", member: name, isMethod: true };
+			const handler = T.func(objType.args.map((a, i) => ({ name: `arg${i + 1}`, type: a, optional: false })), T.void);
+			if (name === "Wait") {
+				c.noteYield();
+				return T.func([], objType.args.length === 0 ? T.void : objType.args.length === 1 ? objType.args[0] : { k: "tuple", elems: objType.args });
+			}
+			if (name === "ConnectParallel") {
+				c.warn("PAR7001", e.nameSpan, "ConnectParallel handlers run in parallel: they cannot write Instance properties", ["only works in a script parented under an Actor"]);
+			}
+			return T.func([{ name: "handler", type: handler, optional: false }], T.datatype("RBXScriptConnection"));
+		}
+		case "struct":
+			return structMember(c, e, objType, ctx);
+		case "string":
+		case "lit": {
+			if (objType.k === "lit" && typeof objType.value !== "string") {
+				break;
+			}
+			if (STRING_METHODS.has(name)) {
+				requireCall(c, e, ctx);
+				c.requireRoblox(e.nameSpan, `string.${name}`);
+				const fn = prune(c.api.libraryFunction("string", name) ?? T.any);
+				e.res = { kind: "library", lib: "string", member: name, stringMethod: true };
+				if (fn.k === "func") {
+					return { ...fn, params: fn.params.slice(1) };
+				}
+				return T.any;
+			}
+			c.error("CL3090", e.nameSpan, `text has no member '${name}'`, name === "length" || name === "size" ? ["use len(text)"] : ["link @clpp.text and use Text." + name + "(…)"]);
+			return T.unknown;
+		}
+		case "list":
+			c.error("CL3091", e.nameSpan, `lists have no member '${name}'`, name === "length" || name === "size" || name === "Length" ? ["use len(list)"] : ["use push/pop/insert/remove/find/sort"]);
+			return T.unknown;
+		case "dict":
+			c.error("CL3092", e.nameSpan, `dictionaries are read with [key], not .${name}`, [`write d["${name}"]`]);
+			return T.unknown;
+		case "table": {
+			const f = objType.fields[name];
+			if (f) {
+				e.res = { kind: "dynamic" };
+				return f;
+			}
+			c.error("CL3093", e.nameSpan, `this table has no field '${name}'`, [`fields: ${Object.keys(objType.fields).join(", ")}`]);
+			return T.unknown;
+		}
+		case "option": {
+			c.strictError("CL3011", e.object.span, `${typeToString(objType)} may be null here`, [
+				`check it first: \`if (${describe(e.object)} != null) { … }\``,
+			]);
+			const inner = memberOf(c, e, prune(objType.inner), expected, ctx);
+			return inner;
+		}
+		case "null":
+			c.error("CL3011", e.object.span, "this value is always null");
+			return T.unknown;
+		case "any":
+		case "unknown":
+		case "infer":
+			e.res = { kind: "dynamic" };
+			return T.any;
+		case "task":
+			c.error("CL3094", e.nameSpan, "a task has no members; get its result with `await`");
+			return T.unknown;
+		default:
+			break;
+	}
+	c.error("CL3095", e.nameSpan, `${typeToString(objType)} has no member '${name}'`);
+	return T.unknown;
+}
+
+function describe(e: Expr): string {
+	switch (e.kind) {
+		case "Name":
+			return e.name;
+		case "Member":
+			return `${describe(e.object)}.${e.name}`;
+		case "SelfField":
+			return `@${e.name}`;
+		default:
+			return "value";
+	}
+}
+
+function requireCall(c: Checker, e: Extract<Expr, { kind: "Member" }>, ctx: MemberContext): void {
+	if (!ctx.forCall) {
+		c.error("CL3096", e.nameSpan, `'${e.name}' is a method; call it: ${describe(e)}(…)`, ["to pass it around, wrap it: `func () { " + describe(e) + "(); }`"]);
+	}
+}
+
+// ---------- namespaces ----------
+
+function namespaceMember(c: Checker, e: Extract<Expr, { kind: "Member" }>, ns: Namespace, ctx: MemberContext): Type {
+	const name = e.name;
+	switch (ns.kind) {
+		case "module":
+			return moduleMember(c, e, ns.alias, ns.moduleId);
+		case "luauModule":
+			e.res = { kind: "moduleMember", alias: ns.alias, moduleId: ns.alias, member: name, memberKind: "value" };
+			return T.any;
+		case "library": {
+			const lib = c.api.library(ns.name);
+			const member = lib?.[name];
+			if (!member) {
+				if (ns.name === "task" && name === "defer") {
+					// CL++ core task.defer is the Roblox one
+				}
+				const s = lib ? suggest(name, Object.keys(lib)) : null;
+				c.error("RBX5006", e.nameSpan, `${ns.name}.${name} does not exist`, s ? [`did you mean ${ns.name}.${s}?`] : undefined);
+				return T.unknown;
+			}
+			if (member.deprecated) {
+				c.warn("RBX5010", e.nameSpan, `${ns.name}.${name} is deprecated`);
+			}
+			e.res = { kind: "library", lib: ns.name, member: name };
+			if (ns.name === "task" && name === "wait") {
+				c.noteYield();
+			}
+			if (ns.name === "coroutine" && name === "yield") {
+				c.noteYield();
+			}
+			return c.api.libraryFunction(ns.name, name) ?? T.any;
+		}
+		case "datatype": {
+			const st = c.api.datatypeStatic(ns.name, name);
+			if (!st) {
+				const statics = c.api.datatypes[ns.name]?.statics ?? {};
+				const s = suggest(name, Object.keys(statics));
+				c.error("RBX5007", e.nameSpan, `${ns.name}.${name} does not exist`, s ? [`did you mean ${ns.name}.${s}?`] : [`available: ${Object.keys(statics).join(", ")}`]);
+				return T.unknown;
+			}
+			if (st.deprecated) {
+				c.warn("RBX5010", e.nameSpan, `${ns.name}.${name} is deprecated`);
+			}
+			if (ns.name !== "Vector3" && ns.name !== "Vector2") {
+				c.requireRoblox(e.span, ns.name);
+			}
+			e.res = { kind: "datatypeStatic", datatype: ns.name, member: name };
+			return c.api.staticFunctionType(st);
+		}
+		case "instanceStatic":
+			if (name === "new" || name === "fromExisting") {
+				e.res = { kind: "datatypeStatic", datatype: "Instance", member: name };
+				return name === "new"
+					? T.func([{ name: "className", type: T.string, optional: false }, { name: "parent", type: T.instance("Instance"), optional: true }], T.instance("Instance"))
+					: T.func([{ name: "existing", type: T.instance("Instance"), optional: false }], T.instance("Instance"));
+			}
+			c.error("RBX5007", e.nameSpan, `Instance.${name} does not exist`, ["Instance.new(className) or Instance.fromExisting(instance)"]);
+			return T.unknown;
+		case "struct": {
+			const info = c.structs.get(ns.id);
+			const m = info?.methods.get(name);
+			if (m && m.isStatic) {
+				e.res = { kind: "method", struct: ns.id, name, isStatic: true };
+				return m.type;
+			}
+			if (m) {
+				c.error("CL3097", e.nameSpan, `'${name}' is an instance method; call it on a ${ns.name} value`);
+				return m.type;
+			}
+			const s = info ? suggest(name, [...info.methods.keys()]) : null;
+			c.error("CL3098", e.nameSpan, `struct ${ns.name} has no static member '${name}'`, s ? [`did you mean '${s}'?`] : undefined);
+			return T.unknown;
+		}
+		case "enum": {
+			const info = c.enums.get(ns.id);
+			if (!info) {
+				return T.unknown;
+			}
+			const index = info.cases.findIndex((k) => k.name === name);
+			if (index < 0) {
+				const s = suggest(name, info.cases.map((k) => k.name));
+				c.error("CL3099", e.nameSpan, `enum ${info.name} has no case '${name}'`, s ? [`did you mean ${info.name}.${s}?`] : [`cases: ${info.cases.map((k) => k.name).join(", ")}`]);
+				return T.unknown;
+			}
+			const kase = info.cases[index];
+			e.res = { kind: "enumCase", enumName: info.id, index, hasPayload: Boolean(kase.payload), anyPayload: info.hasPayload };
+			const enumType: Type = { k: "enum", id: info.id, name: info.name };
+			if (kase.payload) {
+				if (!ctx.forCall) {
+					c.error("CL3100", e.nameSpan, `${info.name}.${name} carries a ${typeToString(kase.payload)}; build it with ${info.name}.${name}(value)`);
+				}
+				return T.func([{ name: "value", type: kase.payload, optional: false }], enumType);
+			}
+			return enumType;
+		}
+		case "clNamespace": {
+			const funcs = ns.moduleId === c.input.moduleId ? c.exports.namespaces.get(ns.name) : undefined;
+			const f = funcs?.get(name);
+			if (!f) {
+				const s = funcs ? suggest(name, [...funcs.keys()]) : null;
+				c.error("CL2022", e.nameSpan, `namespace ${ns.name} has no function '${name}'`, s ? [`did you mean '${s}'?`] : undefined);
+				return T.unknown;
+			}
+			e.res = { kind: "moduleMember", alias: ns.name, moduleId: "namespace", member: name, memberKind: "func" };
+			return f.type;
+		}
+		case "stdlib": {
+			const fn = stdModule(ns.module).get(name);
+			if (!fn) {
+				const s = suggest(name, [...stdModule(ns.module).keys()]);
+				c.error("CL2023", e.nameSpan, `${ns.alias}.${name} does not exist`, s ? [`did you mean ${ns.alias}.${s}?`] : undefined);
+				return T.unknown;
+			}
+			e.res = { kind: "stdlib", module: ns.module, member: name };
+			return stdFunctionType(fn);
+		}
+		default:
+			return T.unknown;
+	}
+}
+
+function moduleMember(c: Checker, e: Extract<Expr, { kind: "Member" }>, alias: string, moduleId: string): Type {
+	const sym = c.scope.lookup(alias);
+	const target = sym?.link;
+	const exports: ModuleExports | undefined = target && (target.kind === "clp" ? target.exports : target.kind === "luau" ? target.exports : undefined);
+	if (!exports) {
+		e.res = { kind: "moduleMember", alias, moduleId, member: e.name, memberKind: "value" };
+		return T.any;
+	}
+	const name = e.name;
+	const f = exports.funcs.get(name);
+	if (f) {
+		e.res = { kind: "moduleMember", alias, moduleId, member: name, memberKind: "func" };
+		if (f.contextOnly) {
+			c.checkContext(f.contextOnly, e.nameSpan, `${alias}.${name}`, `it is marked [[${f.contextOnly}]]`);
+		}
+		return f.type;
+	}
+	const k = exports.consts.get(name);
+	if (k) {
+		e.res = { kind: "const", value: k.value };
+		return k.type;
+	}
+	const s = exports.structs.get(name);
+	if (s) {
+		e.res = { kind: "moduleMember", alias, moduleId, member: name, memberKind: "struct" };
+		return { k: "namespace", ns: { kind: "struct", id: s.id, name: s.name } };
+	}
+	const en = exports.enums.get(name);
+	if (en) {
+		e.res = { kind: "moduleMember", alias, moduleId, member: name, memberKind: "enum" };
+		return { k: "namespace", ns: { kind: "enum", id: en.id, name: en.name } };
+	}
+	const nsFuncs = exports.namespaces.get(name);
+	if (nsFuncs) {
+		e.res = { kind: "moduleMember", alias, moduleId, member: name, memberKind: "value" };
+		return { k: "namespace", ns: { kind: "clNamespace", name, moduleId: exports.moduleId } };
+	}
+	const v = exports.variants.get(name);
+	if (v) {
+		e.res = { kind: "moduleMember", alias, moduleId, member: name, memberKind: "func" };
+		return T.func([{ name: "value", type: { k: "union", members: v.alternatives }, optional: false }], { k: "variant", id: v.id, name: v.name, alternatives: v.alternatives });
+	}
+	const names = [...exports.funcs.keys(), ...exports.consts.keys(), ...exports.structs.keys(), ...exports.enums.keys()];
+	const hint = suggest(name, names);
+	c.error("CL2024", e.nameSpan, `module ${alias} has no member '${name}'`, hint ? [`did you mean ${alias}.${hint}?`] : names.length ? [`it exports: ${names.slice(0, 10).join(", ")}${names.length > 10 ? ", …" : ""}`] : ["it exports nothing"]);
+	return T.unknown;
+}
+
+// ---------- Roblox instances ----------
+
+function memberRuleFor(c: Checker, cls: string, member: string): (typeof MEMBER_RULES)[string] | undefined {
+	let cur: string | null = cls;
+	let guard = 0;
+	while (cur && guard++ < 64) {
+		const rule = MEMBER_RULES[`${cur}.${member}`];
+		if (rule) {
+			return rule;
+		}
+		cur = c.api.classes[cur]?.superclass ?? null;
+	}
+	return undefined;
+}
+
+function checkSecurity(c: Checker, e: Extract<Expr, { kind: "Member" }>, owner: string, member: SurfaceMember, write: boolean): void {
+	const level = write ? member.writeSecurity : member.security;
+	if (member.notScriptable) {
+		c.error("RBX5040", e.nameSpan, `${owner}.${e.name} is not scriptable`);
+		return;
+	}
+	if (!level) {
+		return;
+	}
+	if (level === "PluginSecurity") {
+		if (c.input.context !== "plugin") {
+			c.error("RBX5041", e.nameSpan, `${owner}.${e.name} needs plugin security; game scripts cannot ${write ? "set" : "use"} it`);
+		}
+		return;
+	}
+	c.error("RBX5042", e.nameSpan, `${owner}.${e.name} is restricted (${level}); game scripts cannot ${write ? "set" : "use"} it`);
+}
+
+function deprecation(c: Checker, e: Extract<Expr, { kind: "Member" }>, owner: string, member: SurfaceMember): void {
+	if (!member.deprecated) {
+		return;
+	}
+	const use = typeof member.deprecated === "string" ? member.deprecated.replace(/^.*?:/, "") : null;
+	c.warn("RBX5010", e.nameSpan, `${owner}.${e.name} is deprecated${use ? `; use ${use}` : ""}`);
+}
+
+function instanceMember(c: Checker, e: Extract<Expr, { kind: "Member" }>, obj: Extract<Type, { k: "instance" }>, ctx: MemberContext): Type {
+	const name = e.name;
+	const api = c.api;
+	// game.Players → GetService("Players")
+	if (obj.cls === "DataModel" && api.isService(name) && !api.member("DataModel", name)) {
+		c.useService(name, e.nameSpan);
+		e.res = { kind: "service", service: name };
+		const dm = obj.dm?.children.get(name);
+		return { k: "instance", cls: name, ...(dm ? { dm } : {}) };
+	}
+	const hit = api.member(obj.cls, name);
+	if (hit) {
+		const m = hit.member;
+		deprecation(c, e, hit.owner, m);
+		checkSecurity(c, e, hit.owner, m, false);
+		const rule = memberRuleFor(c, obj.cls, name);
+		if (rule) {
+			c.checkContext(rule.only, e.nameSpan, `${obj.cls}.${name}`, rule.why, rule.severity);
+		}
+		const risky = RISKY_MEMBERS[`${hit.owner}.${name}`];
+		if (risky) {
+			c.warn("RBX5043", e.nameSpan, `${hit.owner}.${name}: ${risky}`);
+		}
+		switch (m.kind) {
+			case "property": {
+				e.res = { kind: "rbxProperty", owner: hit.owner };
+				const t = m.type ? api.convert(m.type) : T.any;
+				if (c.fn?.isParallel) {
+					// reading is fine in parallel; writes are checked in checkAssignTarget
+				}
+				return t;
+			}
+			case "method":
+				requireCall(c, e, ctx);
+				e.res = { kind: "rbxMethod", owner: hit.owner };
+				if (m.yields || name === "WaitForChild" || /Async$/.test(name)) {
+					c.noteYield();
+				}
+				return api.methodType(m);
+			case "event":
+				e.res = { kind: "rbxEvent", owner: hit.owner };
+				return { k: "rbxSignal", args: (m.args || []).map((a) => api.convert(a)) };
+			case "callback":
+				e.res = { kind: "rbxProperty", owner: hit.owner };
+				return m.type ? api.convert(m.type) : T.any;
+			default:
+				return T.any;
+		}
+	}
+	// Typed DataModel: children known from the project layout.
+	const child = obj.dm?.children.get(name);
+	if (child) {
+		e.res = { kind: "rbxChild", owner: obj.cls, childName: name, safe: true };
+		return dmType(child);
+	}
+	const members = [...api.members(obj.cls).keys()];
+	const typo = suggest(name, members);
+	if (typo) {
+		c.error("RBX5020", e.nameSpan, `${obj.cls} has no member '${name}'`, [`did you mean '${typo}'?`]);
+		return T.unknown;
+	}
+	if (/^[a-z]/.test(name) && !obj.dm) {
+		c.error("RBX5020", e.nameSpan, `${obj.cls} has no member '${name}'`, ["Roblox members are PascalCase"]);
+		return T.unknown;
+	}
+	const known = obj.dm ? [...obj.dm.children.keys()] : [];
+	const notes = [
+		`if '${name}' is a child Instance, prefer ${describe(e.object)}.WaitForChild("${name}") (it may not exist yet) or FindFirstChild`,
+	];
+	if (known.length) {
+		notes.unshift(`known children: ${known.slice(0, 8).join(", ")}${known.length > 8 ? ", …" : ""}`);
+	}
+	c.strictError("RBX5021", e.nameSpan, `'${name}' is not a property of ${obj.cls}; it is read as a child Instance`, notes);
+	e.res = { kind: "rbxChild", owner: obj.cls, childName: name, safe: false };
+	return T.instance("Instance");
+}
+
+export function dmType(node: DataModelNode): Type {
+	return { k: "instance", cls: node.className, dm: node };
+}
+
+function datatypeMember(c: Checker, e: Extract<Expr, { kind: "Member" }>, name: string, ctx: MemberContext): Type {
+	const member = e.name;
+	const components = VECTOR_COMPONENTS[name];
+	if (components && components.includes(member)) {
+		e.res = { kind: "vectorComponent", component: member.toUpperCase() };
+		return T.float;
+	}
+	if (name === "RBXScriptConnection") {
+		if (member === "Disconnect") {
+			requireCall(c, e, ctx);
+			e.res = { kind: "datatypeMember", datatype: name, member, isMethod: true };
+			return T.func([], T.void);
+		}
+		if (member === "Connected") {
+			e.res = { kind: "datatypeMember", datatype: name, member, isMethod: false };
+			return T.bool;
+		}
+	}
+	const m = c.api.datatypeMember(name, member);
+	if (!m) {
+		const dt = c.api.datatypes[name];
+		const s = dt ? suggest(member, Object.keys(dt.members)) : null;
+		c.error("RBX5022", e.nameSpan, `${name} has no member '${member}'`, s ? [`did you mean '${s}'?`] : components ? [`components: ${components.join(", ")} (or ${components.map((x) => x.toUpperCase()).join(", ")})`] : undefined);
+		return T.unknown;
+	}
+	if (m.deprecated) {
+		c.warn("RBX5010", e.nameSpan, `${name}.${member} is deprecated`);
+	}
+	if (m.kind === "method") {
+		requireCall(c, e, ctx);
+		e.res = { kind: "datatypeMember", datatype: name, member, isMethod: true };
+		return c.api.methodType(m);
+	}
+	if (components && /^[XYZ]$/.test(member)) {
+		e.res = { kind: "vectorComponent", component: member };
+		return T.float;
+	}
+	e.res = { kind: "datatypeMember", datatype: name, member, isMethod: false };
+	return m.type ? c.api.convert(m.type) : T.any;
+}
+
+// ---------- CL++ structs ----------
+
+function structMember(c: Checker, e: Extract<Expr, { kind: "Member" }>, obj: Extract<Type, { k: "struct" }>, ctx: MemberContext): Type {
+	const info = c.structs.get(obj.id);
+	if (!info) {
+		return T.unknown;
+	}
+	const bindings = new Map<string, Type>();
+	info.typeParams.forEach((p, i) => {
+		const arg = obj.args[i];
+		if (arg && !(prune(arg).k === "param" && (prune(arg) as { name: string }).name === p)) {
+			bindings.set(p, arg);
+		}
+	});
+	const field = info.fields.find((f) => f.name === e.name);
+	if (field) {
+		if (field.isPrivate && !canSeePrivate(c, info)) {
+			c.error("CL2041", e.nameSpan, `'${e.name}' is a private member of ${field.owner}`, ["only methods of the struct can use it"]);
+		}
+		e.res = { kind: "field", struct: info.id };
+		return substitute(field.type, bindings);
+	}
+	const method = info.methods.get(e.name);
+	if (method) {
+		if (method.isPrivate && !canSeePrivate(c, info)) {
+			c.error("CL2041", e.nameSpan, `'${e.name}' is a private method of ${method.owner}`);
+		}
+		requireCall(c, e, ctx);
+		e.res = { kind: "method", struct: info.id, name: e.name, isStatic: method.isStatic };
+		return substitute(method.type, bindings);
+	}
+	const s = suggest(e.name, [...info.fields.map((f) => f.name), ...info.methods.keys()]);
+	c.error("CL2006", e.nameSpan, `${info.name} has no field or method '${e.name}'`, s ? [`did you mean '${s}'?`] : [`fields: ${info.fields.map((f) => f.name).join(", ") || "none"}`]);
+	return T.unknown;
+}
+
+function canSeePrivate(c: Checker, info: StructInfo): boolean {
+	const here = c.fn?.structId;
+	if (!here) {
+		return false;
+	}
+	if (here === info.id) {
+		return true;
+	}
+	return info.fields.some((f) => f.owner === c.structs.get(here)?.name);
+}
+
+// ---------- a::b ----------
+
+const NATIVE_RENAMES: Record<string, Record<string, string>> = {
+	buffer: { size: "len", write_string: "writestring", read_string: "readstring", from_string: "fromstring", to_string: "tostring" },
+	string: { trim: "__trim", upper: "upper", lower: "lower", starts_with: "__startsWith", ends_with: "__endsWith" },
+};
+
+export function checkScopeAccess(c: Checker, e: Extract<Expr, { kind: "Scope" }>): Type {
+	const objType = prune(checkExpr(c, e.object));
+	if (objType.k === "namespace") {
+		let name = e.name;
+		if (objType.ns.kind === "library") {
+			const renamed = NATIVE_RENAMES[objType.ns.name]?.[name] ?? name.replace(/_/g, "");
+			if (renamed.startsWith("__")) {
+				const text = stdModule("text");
+				const fn = text.get(renamed.slice(2));
+				if (fn) {
+					e.res = { kind: "stdlib", module: "text", member: fn.name };
+					return stdFunctionType(fn);
+				}
+			}
+			name = renamed;
+		}
+		const fake: Extract<Expr, { kind: "Member" }> = { kind: "Member", object: e.object, name, nameSpan: e.nameSpan, typeArgs: null, span: e.span };
+		const t = namespaceMember(c, fake, objType.ns, { forCall: true });
+		e.res = fake.res;
+		return t;
+	}
+	// explicit Luau method call on a value: obj::Method(args) → obj:Method(args)
+	e.res = { kind: "luauMethod" };
+	if (objType.k === "instance") {
+		const hit = c.api.member(objType.cls, e.name);
+		if (hit && hit.member.kind === "method") {
+			return c.api.methodType(hit.member);
+		}
+	}
+	if (objType.k === "datatype") {
+		const m = c.api.datatypeMember(objType.name, e.name);
+		if (m && m.kind === "method") {
+			return c.api.methodType(m);
+		}
+	}
+	return T.any;
+}
+
+// ---------- assignment targets ----------
+
+export interface AssignTarget {
+	type: Type;
+}
+
+export function checkAssignTarget(c: Checker, target: Expr, compound: boolean): AssignTarget {
+	switch (target.kind) {
+		case "Name": {
+			const sym = c.scope.lookup(target.name);
+			if (!sym) {
+				const t = checkExpr(c, target);
+				return { type: t };
+			}
+			sym.used = sym.used || compound;
+			if (c.fn && sym.depth < c.fn.depth) {
+				sym.captured = true;
+			}
+			target.res = { kind: "local", sym };
+			target.ty = sym.type;
+			switch (sym.kind) {
+				case "var":
+				case "param":
+					if (!sym.mutable) {
+						c.diags.error("CL2040", target.span, `cannot assign to '${sym.name}': it is declared with let`, ["declare it with `let mut` to change it"], {
+							span: sym.span,
+							text: `mut ${sym.name}`,
+							title: `Make '${sym.name}' mutable (let mut)`,
+						});
+					}
+					if (sym.atomic) {
+						c.error("CL2042", target.span, `'${sym.name}' is atomic; change it with fetch_add(${sym.name}, n)`);
+					}
+					sym.assigned = true;
+					return { type: sym.type };
+				case "self":
+					c.error("CL2043", target.span, "cannot replace self; assign its fields instead (`@hp = …`)");
+					return { type: sym.type };
+				case "const":
+					c.error("CL2044", target.span, `'${sym.name}' is a constant`);
+					return { type: sym.type };
+				default:
+					c.error("CL2045", target.span, `cannot assign to ${sym.kind} '${sym.name}'`);
+					return { type: T.unknown };
+			}
+		}
+		case "SelfField": {
+			const t = checkExpr(c, target);
+			if (target.res?.kind === "field" && c.fn) {
+				c.fn.mutatesSelf = true;
+			} else if (target.res?.kind === "method") {
+				c.error("CL2045", target.span, `cannot assign to method '${target.name}'`);
+			} else if (target.res?.kind === "dataModel") {
+				c.error("CL2045", target.span, "cannot replace @game");
+			}
+			return { type: t };
+		}
+		case "Member": {
+			const objType = prune(checkExpr(c, target.object));
+			const t = memberOf(c, target, objType, undefined, { forCall: false });
+			target.ty = t;
+			const res = target.res;
+			if (!res) {
+				return { type: t };
+			}
+			switch (res.kind) {
+				case "field": {
+					requireMutableRoot(c, target);
+					return { type: t };
+				}
+				case "rbxProperty": {
+					const owner = res.owner;
+					if (objType.k === "instance") {
+						const hit = c.api.member(objType.cls, target.name);
+						if (hit) {
+							if (hit.member.readonly) {
+								c.error("RBX5030", target.nameSpan, `${hit.owner}.${target.name} is read-only`);
+							}
+							checkSecurity(c, target, hit.owner, hit.member, true);
+							if (c.fn?.isParallel) {
+								c.error("PAR7002", target.span, `[[parallel]] code cannot write ${hit.owner}.${target.name}`, ["write Instance properties after task.synchronize()"]);
+							}
+						}
+					} else {
+						c.error("RBX5030", target.nameSpan, `${owner}.${target.name} is read-only`);
+					}
+					return { type: t };
+				}
+				case "vectorComponent": {
+					const inner = checkAssignTarget(c, target.object, true);
+					void inner;
+					return { type: T.float };
+				}
+				case "datatypeMember":
+					c.error("RBX5031", target.nameSpan, `${typeToString(objType)} values are immutable; build a new one`, objType.k === "datatype" && objType.name === "CFrame" ? ["e.g. part.CFrame = CFrame.new(position) * rotation"] : undefined);
+					return { type: t };
+				case "rbxChild":
+					c.error("RBX5032", target.nameSpan, `cannot assign to the child '${target.name}'; set its Parent instead`);
+					return { type: t };
+				case "service":
+					c.error("RBX5032", target.nameSpan, "services cannot be replaced");
+					return { type: t };
+				case "rbxEvent":
+				case "rbxMethod":
+					c.error("RBX5033", target.nameSpan, `cannot assign to ${target.name}; connect to an event with \`${describe(target)} ~> handler;\``);
+					return { type: t };
+				case "moduleMember":
+				case "const":
+				case "enumCase":
+				case "rbxEnumItem":
+				case "library":
+				case "datatypeStatic":
+				case "stdlib":
+					c.error("CL2045", target.nameSpan, `cannot assign to ${describe(target)}`);
+					return { type: t };
+				default:
+					return { type: t };
+			}
+		}
+		case "Index": {
+			const objType = prune(checkExpr(c, target.object));
+			if (objType.k === "string" || objType.k === "lit") {
+				c.error("CL2046", target.span, "text is immutable; build a new string");
+			} else if (objType.k === "list" || objType.k === "dict") {
+				requireMutableRoot(c, target);
+			}
+			const t = checkExpr(c, target);
+			return { type: t };
+		}
+		default:
+			c.error("CL1108", target.span, "cannot assign to this expression");
+			return { type: T.unknown };
+	}
+}
+
+/** Fields/elements of a `let` binding are frozen; `self` fields mark the method as mutating. */
+function requireMutableRoot(c: Checker, target: Expr): void {
+	const root = rootSymbol(target);
+	if (!root) {
+		return;
+	}
+	if (root.kind === "self") {
+		if (c.fn) {
+			c.fn.mutatesSelf = true;
+		}
+		return;
+	}
+	if ((root.kind === "var" || root.kind === "param") && !root.mutable) {
+		c.diags.error("CL2040", target.span, `cannot change '${describe(target)}': '${root.name}' is declared with let`, ["declare it with `let mut`"], {
+			span: root.span,
+			text: `mut ${root.name}`,
+			title: `Make '${root.name}' mutable (let mut)`,
+		});
+	}
+	(root as Sym).mutatedFields = true;
+	const key = exprPathKey(target);
+	if (key) {
+		c.scope.invalidate(key);
+	}
+}
+
+export { isDynamic };