cluaupp 1.5.2 → 2.0.0-beta.2

package/src/compiler/checker/checker.ts

@@ -0,0 +1,1352 @@
+/**
+ * CL++ checker for the Roblox host. Resolves names, infers and checks types against CL++ rules and
+ * the typed Roblox API, enforces server/client authority, and annotates the tree for the emitter.
+ *
+ * Passes: declare (hoist every top-level name) → resolve (signatures, fields) → check (top-level
+ * statements in order, then function bodies on demand so call sites teach unannotated parameters)
+ * → finalize (exports, unused names, self mutation).
+ */
+
+import type {
+	Attribute,
+	Decl,
+	EnumDecl,
+	Expr,
+	FuncDecl,
+	LinkDecl,
+	Param,
+	Program,
+	Stmt,
+	StructDecl,
+	TypeNode,
+	VarName,
+} from "../ast.js";
+import { suggest, type DiagnosticBag } from "../diagnostics.js";
+import type { RobloxApi } from "../roblox/api.js";
+import { contextLabel, type RunContext } from "../roblox/context.js";
+import type { SourceFile, Span } from "../source.js";
+import { isDynamic, isValueTable, nonNull, prune, T, typeToString, type DataModelNode, type FnParam, type Type } from "../types.js";
+import { checkExpr, checkCondition, exprPathKey } from "./exprs.js";
+import { alwaysExits, applyNarrowings, conditionNarrowings } from "./flow.js";
+import {
+	emptyExports,
+	Scope,
+	type EnumInfo,
+	type ExportedFunc,
+	type FieldInfo,
+	type LinkTarget,
+	type MethodInfo,
+	type ModuleExports,
+	type StructInfo,
+	type Sym,
+	type SymKind,
+	type VariantInfo,
+} from "./symbols.js";
+import { assignable, join, type TypeEnv } from "./typeops.js";
+import { checkStatement } from "./statements.js";
+
+export interface CheckInput {
+	program: Program;
+	source: SourceFile;
+	diags: DiagnosticBag;
+	api: RobloxApi;
+	moduleId: string;
+	kind: "script" | "module";
+	context: RunContext;
+	/** Project-level strictness (`cluaupp.config.json` "strict"). */
+	strict: boolean;
+	resolveLink(link: LinkDecl): LinkTarget;
+	dataModel: DataModelNode | null;
+	dmPath: string[] | null;
+}
+
+export interface FnCtx {
+	decl: FuncDecl | null;
+	declaredRet: Type | null;
+	returns: Type[];
+	depth: number;
+	isMethod: boolean;
+	structId: string | null;
+	selfSym: Sym | null;
+	isAsync: boolean;
+	yields: boolean;
+	mutatesSelf: boolean;
+	contextOnly?: "server" | "client";
+	isParallel: boolean;
+	sym: Sym | null;
+}
+
+export interface LinkInfo {
+	decl: LinkDecl;
+	target: LinkTarget;
+	sym: Sym | null;
+}
+
+/** Everything the emitter needs to know about the checked file. */
+export interface FileInfo {
+	moduleId: string;
+	kind: "script" | "module";
+	context: RunContext;
+	mode: Program["mode"];
+	directives: string[];
+	robloxLinked: boolean;
+	links: LinkInfo[];
+	structs: StructInfo[];
+	enums: EnumInfo[];
+	structRegistry: Map<string, StructInfo>;
+	enumRegistry: Map<string, EnumInfo>;
+	topLevel: Sym[];
+	funcSyms: Map<FuncDecl, Sym>;
+	services: Set<string>;
+	usesShared: boolean;
+	exports: ModuleExports;
+	dmPath: string[] | null;
+	/** All value symbols declared in this file (for renaming). */
+	symbols: Sym[];
+}
+
+let nextSymId = 1;
+
+export class Checker implements TypeEnv {
+	readonly api: RobloxApi;
+	readonly diags: DiagnosticBag;
+	readonly source: SourceFile;
+	readonly program: Program;
+	readonly input: CheckInput;
+	readonly fileScope: Scope;
+	scope: Scope;
+	fn: FnCtx | null = null;
+	loopDepth = 0;
+	switchDepth = 0;
+	readonly structs = new Map<string, StructInfo>();
+	readonly enums = new Map<string, EnumInfo>();
+	readonly variants = new Map<string, VariantInfo>();
+	readonly links: LinkInfo[] = [];
+	readonly services = new Set<string>();
+	readonly symbols: Sym[] = [];
+	readonly funcSyms = new Map<FuncDecl, Sym>();
+	readonly ownStructs: StructInfo[] = [];
+	readonly ownEnums: EnumInfo[] = [];
+	readonly exports: ModuleExports;
+	robloxLinked = false;
+	usesShared = false;
+	/** Struct/list arguments passed to user functions: copied only if the callee mutates the parameter. */
+	readonly deferredCopies: Array<{ arg: Expr; decl: FuncDecl; index: number }> = [];
+	/** Method calls on a binding; a self-mutating method needs a mutable binding. */
+	readonly mutatingCalls: Array<{ root: Sym; method: MethodInfo; span: Span }> = [];
+	/** Function bodies not yet checked. */
+	private readonly pendingBodies = new Map<FuncDecl, () => void>();
+	private readonly checking = new Set<FuncDecl>();
+	readonly strict: boolean;
+
+	constructor(input: CheckInput) {
+		this.input = input;
+		this.api = input.api;
+		this.diags = input.diags;
+		this.source = input.source;
+		this.program = input.program;
+		this.fileScope = new Scope(null, "file", 0);
+		this.scope = this.fileScope;
+		this.strict = input.program.mode === "strict" || (input.strict && input.program.mode !== "nonstrict");
+		this.exports = emptyExports(input.moduleId, input.source.path, input.kind, input.context);
+		this.exports.dmPath = input.dmPath;
+	}
+
+	// ---------- TypeEnv ----------
+
+	struct(id: string): StructInfo | undefined {
+		return this.structs.get(id);
+	}
+
+	// ---------- diagnostics helpers ----------
+
+	get nocheck(): boolean {
+		return this.program.mode === "nocheck";
+	}
+
+	error(code: string, span: Span, message: string, notes?: string[]): void {
+		if (this.nocheck && !code.startsWith("CL1") && !code.startsWith("MOD")) {
+			return;
+		}
+		this.diags.error(code, span, message, notes);
+	}
+
+	warn(code: string, span: Span, message: string, notes?: string[]): void {
+		if (this.nocheck) {
+			return;
+		}
+		this.diags.warning(code, span, message, notes);
+	}
+
+	/** Error in strict mode, warning otherwise. */
+	strictError(code: string, span: Span, message: string, notes?: string[]): void {
+		if (this.strict) {
+			this.error(code, span, message, notes);
+		} else {
+			this.warn(code, span, message, notes);
+		}
+	}
+
+	// ---------- symbols ----------
+
+	newSym(name: string, kind: SymKind, type: Type, span: Span, mutable = false): Sym {
+		const sym: Sym = {
+			id: nextSymId++,
+			name,
+			kind,
+			type,
+			mutable,
+			span,
+			file: this.input.moduleId,
+			topLevel: this.scope === this.fileScope,
+			depth: this.fn ? this.fn.depth : 0,
+		};
+		this.symbols.push(sym);
+		return sym;
+	}
+
+	declare(name: string, kind: SymKind, type: Type, span: Span, mutable = false, scope: Scope = this.scope): Sym {
+		const existing = scope.values.get(name);
+		if (existing && existing.kind !== "module") {
+			this.error("CL2004", span, `'${name}' is already declared in this scope`, [`first declared at line ${this.source.position(existing.span.start).line}`]);
+		} else if (!existing) {
+			const outer = scope.parent?.lookup(name);
+			if (outer && (outer.kind === "var" || outer.kind === "param") && scope.kind !== "file" && !name.startsWith("_")) {
+				// shadowing is legal CL++ (blocks create scopes); mention only when it hides a parameter
+				if (outer.kind === "param" && outer.depth === (this.fn?.depth ?? 0)) {
+					this.warn("CL2010", span, `'${name}' shadows the parameter with the same name`);
+				}
+			}
+		}
+		const sym = this.newSym(name, kind, type, span, mutable);
+		sym.topLevel = scope === this.fileScope;
+		scope.values.set(name, sym);
+		return sym;
+	}
+
+	declareType(name: string, kind: SymKind, type: Type, span: Span, typeId?: string): Sym {
+		const existing = this.fileScope.types.get(name);
+		if (existing && existing.file === this.input.moduleId && existing.kind !== "module") {
+			this.error("CL2004", span, `type '${name}' is already declared`, [`first declared at line ${this.source.position(existing.span.start).line}`]);
+		}
+		const sym = this.newSym(name, kind, type, span);
+		sym.topLevel = true;
+		if (typeId) {
+			sym.typeId = typeId;
+		}
+		this.fileScope.types.set(name, sym);
+		return sym;
+	}
+
+	pushScope(kind: Scope["kind"] = "block"): Scope {
+		this.scope = new Scope(this.scope, kind, this.fn ? this.fn.depth : 0);
+		return this.scope;
+	}
+
+	popScope(): void {
+		this.reportUnused(this.scope);
+		this.scope = this.scope.parent ?? this.fileScope;
+	}
+
+	private reportUnused(scope: Scope): void {
+		if (scope === this.fileScope && this.input.kind === "module") {
+			return;
+		}
+		for (const sym of scope.values.values()) {
+			if (sym.kind === "var" && !sym.used && !sym.name.startsWith("_") && !sym.observable) {
+				this.warn("CL2011", sym.span, `'${sym.name}' is declared but never used`, ["prefix it with `_` to keep it on purpose"]);
+			}
+		}
+	}
+
+	// ---------- entry ----------
+
+	run(): FileInfo {
+		this.declarePass();
+		this.resolvePass();
+		this.checkTopLevel();
+		this.drainBodies();
+		this.finalize();
+		return {
+			moduleId: this.input.moduleId,
+			kind: this.input.kind,
+			context: this.input.context,
+			mode: this.program.mode,
+			directives: this.program.directives,
+			robloxLinked: this.robloxLinked,
+			links: this.links,
+			structs: this.ownStructs,
+			enums: this.ownEnums,
+			structRegistry: this.structs,
+			enumRegistry: this.enums,
+			topLevel: [...this.fileScope.values.values()],
+			funcSyms: this.funcSyms,
+			services: this.services,
+			usesShared: this.usesShared,
+			exports: this.exports,
+			dmPath: this.input.dmPath,
+			symbols: this.symbols,
+		};
+	}
+
+	// ---------- pass 1: declare ----------
+
+	private declarePass(): void {
+		for (const stmt of this.program.body) {
+			if (stmt.kind !== "Decl") {
+				if (stmt.kind === "Signal") {
+					const sym = this.declare(stmt.name.name, "signal", { k: "clSignal", params: null }, stmt.name.span);
+					sym.signalParams = null;
+					stmt.name.sym = sym;
+				} else if (stmt.kind === "Var" && (stmt.declKind === "const" || stmt.declKind === "constexpr") && !stmt.unpack) {
+					this.predeclareConst(stmt);
+				}
+				continue;
+			}
+			this.declareDecl(stmt.decl, stmt.attributes || []);
+		}
+	}
+
+	private predeclareConst(stmt: Extract<Stmt, { kind: "Var" }>): void {
+		const name = stmt.names[0];
+		const value = stmt.init ? foldConstant(stmt.init) : undefined;
+		const type: Type = value === undefined ? T.unknown : value === null ? T.null : typeof value === "string" ? T.string : typeof value === "boolean" ? T.bool : Number.isInteger(value) && !(stmt.init?.kind === "Number" && stmt.init.isFloat) ? T.int : T.float;
+		const sym = this.declare(name.name, "const", type, name.span);
+		if (value !== undefined) {
+			sym.constValue = value;
+		}
+		name.sym = sym;
+		stmt.predeclared = true;
+	}
+
+	private declareDecl(decl: Decl, attrs: Attribute[]): void {
+		switch (decl.kind) {
+			case "Link":
+				this.declareLink(decl);
+				return;
+			case "Struct": {
+				const id = `${this.input.moduleId}::${decl.name}`;
+				const info: StructInfo = {
+					id,
+					name: decl.name,
+					luauName: decl.name,
+					moduleId: this.input.moduleId,
+					decl,
+					typeParams: decl.typeParams,
+					bases: [],
+					fields: [],
+					methods: new Map(),
+					subclasses: [],
+					isAbstract: decl.isAbstract,
+					isFinal: decl.isFinal,
+					resolved: false,
+				};
+				this.structs.set(id, info);
+				this.ownStructs.push(info);
+				const ty: Type = { k: "struct", id, name: decl.name, args: decl.typeParams.map((p) => ({ k: "param", name: p }) as Type) };
+				this.declareType(decl.name, "struct", ty, decl.nameSpan, id);
+				const value = this.declare(decl.name, "struct", { k: "namespace", ns: { kind: "struct", id, name: decl.name } }, decl.nameSpan);
+				value.typeId = id;
+				value.doc = decl.doc;
+				return;
+			}
+			case "Enum": {
+				const id = `${this.input.moduleId}::${decl.name}`;
+				const info: EnumInfo = {
+					id,
+					name: decl.name,
+					luauName: decl.name,
+					moduleId: this.input.moduleId,
+					decl,
+					cases: decl.cases.map((c) => ({ name: c.name, payload: null })),
+					hasPayload: decl.cases.some((c) => c.payload),
+				};
+				this.enums.set(id, info);
+				this.ownEnums.push(info);
+				this.declareType(decl.name, "enum", { k: "enum", id, name: decl.name }, decl.nameSpan, id);
+				const value = this.declare(decl.name, "enum", { k: "namespace", ns: { kind: "enum", id, name: decl.name } }, decl.nameSpan);
+				value.typeId = id;
+				value.doc = decl.doc;
+				return;
+			}
+			case "Variant": {
+				const id = `${this.input.moduleId}::${decl.name}`;
+				const info: VariantInfo = { id, name: decl.name, alternatives: [] };
+				this.variants.set(id, info);
+				this.declareType(decl.name, "variant", { k: "variant", id, name: decl.name, alternatives: [] }, decl.nameSpan, id);
+				this.declare(decl.name, "variant", T.func([{ name: "value", type: T.any, optional: false }], { k: "variant", id, name: decl.name, alternatives: [] }), decl.nameSpan).typeId = id;
+				return;
+			}
+			case "TypeAlias":
+				this.declareType(decl.name, "alias", T.unknown, decl.nameSpan);
+				return;
+			case "Namespace": {
+				const sym = this.declare(decl.name, "namespace", { k: "namespace", ns: { kind: "clNamespace", name: decl.name, moduleId: this.input.moduleId } }, decl.nameSpan);
+				sym.doc = undefined;
+				return;
+			}
+			case "Func": {
+				if (decl.isExtern) {
+					this.error("RBX5101", decl.nameSpan, `extern func '${decl.name}' has no native provider on Roblox`, [
+						"Roblox functions come from `link @clpp.roblox;` — call them directly",
+						"declare Luau module functions in a linked module instead",
+					]);
+				}
+				const existing = this.fileScope.values.get(decl.name);
+				if (existing && existing.kind === "func") {
+					this.error("CL2004", decl.nameSpan, `function '${decl.name}' is already declared`, ["CL++ has no overloading by parameter count across declarations; rename one of them"]);
+					return;
+				}
+				const sym = this.declare(decl.name, "func", T.func([], T.unknown), decl.nameSpan);
+				sym.decl = decl;
+				sym.doc = decl.doc;
+				const ctx = contextAttribute(attrs.length ? attrs : decl.attributes);
+				if (ctx) {
+					sym.contextOnly = ctx;
+				}
+				this.funcSyms.set(decl, sym);
+				return;
+			}
+			default:
+				return;
+		}
+	}
+
+	private declareLink(decl: LinkDecl): void {
+		const target = this.input.resolveLink(decl);
+		const info: LinkInfo = { decl, target, sym: null };
+		this.links.push(info);
+		switch (target.kind) {
+			case "error":
+				this.error("MOD9001", decl.pathSpan, target.message, target.notes);
+				return;
+			case "roblox":
+				if (this.robloxLinked) {
+					this.warn("MOD9002", decl.span, "@clpp.roblox is already linked");
+				}
+				this.robloxLinked = true;
+				return;
+			case "std": {
+				const sym = this.declare(decl.alias, "module", { k: "namespace", ns: { kind: "stdlib", module: target.module, alias: decl.alias } }, decl.aliasSpan);
+				sym.link = target;
+				info.sym = sym;
+				return;
+			}
+			case "clp": {
+				const sym = this.declare(decl.alias, "module", { k: "namespace", ns: { kind: "module", moduleId: target.exports.moduleId, alias: decl.alias } }, decl.aliasSpan);
+				sym.link = target;
+				info.sym = sym;
+				// Types from linked modules are visible with and without the module prefix.
+				for (const s of target.exports.structs.values()) {
+					this.structs.set(s.id, s);
+					if (!this.fileScope.types.has(s.name)) {
+						const t = this.newSym(s.name, "struct", { k: "struct", id: s.id, name: s.name, args: s.typeParams.map((p) => ({ k: "param", name: p }) as Type) }, decl.span);
+						t.typeId = s.id;
+						t.file = s.moduleId;
+						this.fileScope.types.set(s.name, t);
+					}
+				}
+				for (const e of target.exports.enums.values()) {
+					this.enums.set(e.id, e);
+					if (!this.fileScope.types.has(e.name)) {
+						const t = this.newSym(e.name, "enum", { k: "enum", id: e.id, name: e.name }, decl.span);
+						t.typeId = e.id;
+						t.file = e.moduleId;
+						this.fileScope.types.set(e.name, t);
+					}
+				}
+				for (const v of target.exports.variants.values()) {
+					this.variants.set(v.id, v);
+				}
+				for (const [name, t] of target.exports.aliases) {
+					if (!this.fileScope.types.has(name)) {
+						const s = this.newSym(name, "alias", t, decl.span);
+						s.file = target.exports.moduleId;
+						this.fileScope.types.set(name, s);
+					}
+				}
+				this.checkLinkContext(decl, target.exports.context, target.dmPath);
+				return;
+			}
+			case "luau": {
+				const ns = target.exports ? { kind: "module" as const, moduleId: target.exports.moduleId, alias: decl.alias } : { kind: "luauModule" as const, alias: decl.alias };
+				const sym = this.declare(decl.alias, "module", { k: "namespace", ns }, decl.aliasSpan);
+				sym.link = target;
+				info.sym = sym;
+				if (target.exports) {
+					for (const s of target.exports.structs.values()) {
+						this.structs.set(s.id, s);
+						if (!this.fileScope.types.has(s.name)) {
+							const t = this.newSym(s.name, "struct", { k: "struct", id: s.id, name: s.name, args: [] }, decl.span);
+							t.typeId = s.id;
+							this.fileScope.types.set(s.name, t);
+						}
+					}
+				}
+				this.checkLinkContext(decl, "shared", target.dmPath);
+				return;
+			}
+			default:
+				return;
+		}
+	}
+
+	/** A LocalScript cannot require something that lives only on the server. */
+	private checkLinkContext(decl: LinkDecl, targetContext: RunContext, dmPath: string[] | null): void {
+		const here = this.input.context;
+		if (here === "client" && dmPath && (dmPath[0] === "ServerScriptService" || dmPath[0] === "ServerStorage")) {
+			this.error("CTX6001", decl.pathSpan, `this module lives in ${dmPath[0]}, which is never replicated to clients`, [
+				"move it to ReplicatedStorage (shared) or keep the code on the server",
+			]);
+			return;
+		}
+		if (targetContext === "server" || targetContext === "client") {
+			this.error("MOD9003", decl.pathSpan, `cannot link a ${targetContext} script; only modules (files without .server/.client) can be linked`);
+		}
+	}
+
+	// ---------- pass 2: resolve signatures ----------
+
+	private resolvePass(): void {
+		for (const stmt of this.program.body) {
+			if (stmt.kind !== "Decl") {
+				continue;
+			}
+			const decl = stmt.decl;
+			if (decl.kind === "TypeAlias") {
+				const sym = this.fileScope.types.get(decl.name)!;
+				sym.type = this.resolveType(decl.type);
+			} else if (decl.kind === "Variant") {
+				const info = this.variants.get(`${this.input.moduleId}::${decl.name}`)!;
+				info.alternatives = decl.alternatives.map((a) => this.resolveType(a));
+				const t = this.fileScope.types.get(decl.name)!;
+				t.type = { k: "variant", id: info.id, name: info.name, alternatives: info.alternatives };
+				const v = this.fileScope.values.get(decl.name)!;
+				v.type = T.func([{ name: "value", type: { k: "union", members: info.alternatives }, optional: false }], t.type);
+			} else if (decl.kind === "Enum") {
+				const info = this.enums.get(`${this.input.moduleId}::${decl.name}`)!;
+				info.cases = decl.cases.map((c) => ({ name: c.name, payload: c.payload ? this.resolveType(c.payload) : null }));
+			}
+		}
+		for (const info of this.ownStructs) {
+			this.resolveStruct(info, new Set());
+		}
+		for (const stmt of this.program.body) {
+			if (stmt.kind === "Decl" && stmt.decl.kind === "Func") {
+				const sym = this.funcSyms.get(stmt.decl);
+				if (sym) {
+					sym.type = this.signatureOf(stmt.decl, null);
+				}
+			} else if (stmt.kind === "Decl" && stmt.decl.kind === "Namespace") {
+				const funcs = new Map<string, ExportedFunc>();
+				for (const f of stmt.decl.funcs) {
+					const sym = this.newSym(f.name, "func", this.signatureOf(f, null), f.nameSpan);
+					sym.decl = f;
+					this.funcSyms.set(f, sym);
+					funcs.set(f.name, { name: f.name, type: sym.type as Extract<Type, { k: "func" }>, doc: f.doc });
+				}
+				this.exports.namespaces.set(stmt.decl.name, funcs);
+			} else if (stmt.kind === "Signal" && stmt.params.length && stmt.name.sym) {
+				const params = stmt.params.map((p) => this.resolveType(p));
+				const signalSym = stmt.name.sym as Sym;
+				signalSym.signalParams = params;
+				signalSym.type = { k: "clSignal", params };
+			}
+		}
+	}
+
+	resolveStruct(info: StructInfo, visiting: Set<string>): void {
+		if (info.resolved) {
+			return;
+		}
+		if (visiting.has(info.id)) {
+			this.error("CL3020", info.decl.nameSpan, `struct ${info.name} inherits from itself`);
+			info.resolved = true;
+			return;
+		}
+		visiting.add(info.id);
+		const decl = info.decl;
+		const fields: FieldInfo[] = [];
+		const seenFields = new Map<string, FieldInfo>();
+		const methods = new Map<string, MethodInfo>();
+		for (const baseNode of decl.bases) {
+			const baseType = this.resolveType(baseNode);
+			if (baseType.k !== "struct") {
+				if (baseType.k === "instance") {
+					this.error("CL3021", baseNode.span, `a struct cannot inherit from the Roblox class ${baseType.cls}`, [
+						"wrap the Instance in a field instead: `struct Door { Part part; }`",
+					]);
+				} else if (!isDynamic(baseType)) {
+					this.error("CL3021", baseNode.span, `'${typeToString(baseType)}' is not a struct and cannot be inherited`);
+				}
+				continue;
+			}
+			const base = this.structs.get(baseType.id);
+			if (!base) {
+				continue;
+			}
+			this.resolveStruct(base, visiting);
+			if (base.isFinal) {
+				this.error("CL3022", baseNode.span, `struct ${base.name} is final and cannot be inherited`);
+			}
+			info.bases.push(base.id);
+			if (!base.subclasses.includes(info.id)) {
+				base.subclasses.push(info.id);
+			}
+			for (const f of base.fields) {
+				const prev = seenFields.get(f.name);
+				if (prev) {
+					if (prev.owner !== f.owner) {
+						this.error("CL3023", baseNode.span, `field '${f.name}' comes from both ${prev.owner} and ${f.owner}`, ["rename one of them to resolve the ambiguity"]);
+					}
+					continue;
+				}
+				seenFields.set(f.name, f);
+				fields.push(f);
+			}
+			for (const [name, m] of base.methods) {
+				if (!methods.has(name)) {
+					methods.set(name, m);
+				}
+			}
+		}
+		this.pushTypeParams(info.typeParams);
+		for (const f of decl.fields) {
+			if (seenFields.has(f.name)) {
+				this.error("CL3024", f.nameSpan, `field '${f.name}' is already inherited from ${seenFields.get(f.name)!.owner}`);
+				continue;
+			}
+			const field: FieldInfo = { name: f.name, type: this.resolveType(f.type), owner: info.name, isPrivate: f.isPrivate, defaultValue: f.defaultValue ?? null, span: f.nameSpan, doc: f.doc };
+			seenFields.set(f.name, field);
+			fields.push(field);
+		}
+		info.fields = fields;
+		const selfType: Type = { k: "struct", id: info.id, name: info.name, args: info.typeParams.map((p) => ({ k: "param", name: p }) as Type) };
+		for (const m of decl.methods) {
+			const inherited = methods.get(m.name);
+			if (inherited && inherited.isFinal) {
+				this.error("CL3025", m.nameSpan, `method '${m.name}' is final in ${inherited.owner} and cannot be overridden`);
+			}
+			if (m.isOverride && !inherited) {
+				this.error("CL3026", m.nameSpan, `'${m.name}' is marked override but no parent struct declares it`);
+			}
+			if (fields.some((f) => f.name === m.name)) {
+				this.error("CL3027", m.nameSpan, `'${m.name}' is both a field and a method of ${info.name}`);
+			}
+			const type = this.signatureOf(m, m.isStatic ? null : selfType) as Extract<Type, { k: "func" }>;
+			const method: MethodInfo = {
+				name: m.name,
+				owner: info.name,
+				root: inherited ? inherited.root : info.id,
+				decl: m,
+				type,
+				isStatic: m.isStatic,
+				isAbstract: m.isAbstract,
+				isFinal: m.isFinal,
+				isPrivate: m.isPrivate,
+			};
+			if (m.isAbstract && !info.isAbstract) {
+				this.error("CL3028", m.nameSpan, `abstract method '${m.name}' needs an abstract struct`, ["write `abstract struct " + info.name + "`"]);
+			}
+			if (!m.body && !m.isAbstract) {
+				this.error("CL3029", m.nameSpan, `method '${m.name}' has no body`);
+			}
+			methods.set(m.name, method);
+			const sym = this.newSym(m.name, "func", type, m.nameSpan);
+			sym.decl = m;
+			sym.doc = m.doc;
+			this.funcSyms.set(m, sym);
+		}
+		this.popTypeParams();
+		info.methods = methods;
+		if (!info.isAbstract) {
+			for (const m of methods.values()) {
+				if (m.isAbstract) {
+					this.error("CL3030", decl.nameSpan, `struct ${info.name} must implement abstract method '${m.name}' from ${m.owner}`);
+				}
+			}
+		}
+		info.resolved = true;
+		visiting.delete(info.id);
+	}
+
+	private typeParamStack: Array<Set<string>> = [];
+
+	pushTypeParams(names: string[]): void {
+		this.typeParamStack.push(new Set(names));
+	}
+
+	popTypeParams(): void {
+		this.typeParamStack.pop();
+	}
+
+	private isTypeParam(name: string): boolean {
+		return this.typeParamStack.some((s) => s.has(name));
+	}
+
+	/** Signature of a function declaration (params without types learn from call sites). */
+	signatureOf(decl: FuncDecl, selfType: Type | null): Type {
+		this.pushTypeParams(decl.typeParams);
+		const params: FnParam[] = [];
+		let variadic: Type | null = null;
+		for (const p of decl.params) {
+			if (p.variadic) {
+				variadic = p.type ? this.resolveType(p.type) : T.any;
+				p.ty = T.list(variadic);
+				continue;
+			}
+			const t = p.type ? this.resolveType(p.type) : ({ k: "infer", resolved: null } as Type);
+			p.ty = t;
+			params.push({ name: p.name, type: t, optional: p.defaultValue !== null || prune(t).k === "option" });
+		}
+		let ret: Type = decl.returnType ? this.resolveType(decl.returnType) : decl.body === null ? T.void : ({ k: "infer", resolved: null } as Type);
+		if (decl.isAsync) {
+			ret = { k: "task", result: ret };
+		}
+		this.popTypeParams();
+		const fn: Type = { k: "func", params, ret, variadic };
+		if (decl.typeParams.length) {
+			fn.generics = decl.typeParams;
+		}
+		void selfType;
+		return fn;
+	}
+
+	// ---------- type nodes ----------
+
+	resolveType(node: TypeNode): Type {
+		switch (node.kind) {
+			case "Literal":
+				return { k: "lit", value: node.value };
+			case "Optional":
+				return T.option(this.resolveType(node.inner));
+			case "Union": {
+				const members = node.members.map((m) => this.resolveType(m));
+				const nonNullMembers = members.filter((m) => m.k !== "null");
+				if (nonNullMembers.length !== members.length) {
+					return T.option(nonNullMembers.length === 1 ? nonNullMembers[0] : { k: "union", members: nonNullMembers });
+				}
+				return { k: "union", members };
+			}
+			case "Intersection": {
+				const members = node.members.map((m) => this.resolveType(m));
+				return members[0];
+			}
+			case "Func":
+				return T.func(
+					node.params.map((p, i) => ({ name: `arg${i + 1}`, type: this.resolveType(p), optional: false })),
+					node.ret ? this.resolveType(node.ret) : T.void,
+				);
+			case "Named":
+				return this.resolveNamedType(node);
+			default:
+				return T.unknown;
+		}
+	}
+
+	private resolveNamedType(node: Extract<TypeNode, { kind: "Named" }>): Type {
+		const args = () => node.args.map((a) => this.resolveType(a));
+		const arity = (n: number, what: string): boolean => {
+			if (node.args.length !== n) {
+				this.error("CL3001", node.span, `${what} takes ${n} type argument${n === 1 ? "" : "s"}, got ${node.args.length}`);
+				return false;
+			}
+			return true;
+		};
+		if (node.qualifier) {
+			if (node.qualifier === "Enum") {
+				this.requireRoblox(node.span, "Enum");
+				if (!this.api.hasEnum(node.name)) {
+					const s = suggest(node.name, Object.keys(this.api.enums));
+					this.error("RBX5001", node.span, `Enum.${node.name} is not a Roblox enum`, s ? [`did you mean Enum.${s}?`] : undefined);
+					return T.unknown;
+				}
+				return { k: "rbxEnumItem", enumName: node.name };
+			}
+			const mod = this.scope.lookup(node.qualifier.split(".")[0]);
+			if (mod && mod.kind === "module" && mod.link && (mod.link.kind === "clp" || (mod.link.kind === "luau" && mod.link.exports))) {
+				mod.used = true;
+				const exp = mod.link.kind === "clp" ? mod.link.exports : mod.link.exports!;
+				const s = exp.structs.get(node.name);
+				if (s) {
+					return { k: "struct", id: s.id, name: s.name, args: args() };
+				}
+				const e = exp.enums.get(node.name);
+				if (e) {
+					return { k: "enum", id: e.id, name: e.name };
+				}
+				const a = exp.aliases.get(node.name);
+				if (a) {
+					return a;
+				}
+				const v = exp.variants.get(node.name);
+				if (v) {
+					return { k: "variant", id: v.id, name: v.name, alternatives: v.alternatives };
+				}
+				this.error("CL2020", node.span, `module ${node.qualifier} has no type '${node.name}'`);
+				return T.unknown;
+			}
+			if (mod && mod.kind === "module") {
+				mod.used = true;
+				return T.any;
+			}
+			// unknown qualifier: fall through to the bare name (CL++ ignores module prefixes on types)
+		}
+		const name = node.name;
+		if (this.isTypeParam(name)) {
+			return { k: "param", name };
+		}
+		const local = this.scope.lookupType(name);
+		if (local) {
+			local.used = true;
+			if (local.kind === "struct") {
+				const t = local.type as Extract<Type, { k: "struct" }>;
+				const info = this.structs.get(t.id);
+				const given = args();
+				if (info && given.length && given.length !== info.typeParams.length) {
+					this.error("CL3001", node.span, `${name} takes ${info.typeParams.length} type argument(s), got ${given.length}`);
+				}
+				return { k: "struct", id: t.id, name: t.name, args: given.length ? given : t.args };
+			}
+			return local.type;
+		}
+		switch (name) {
+			case "int":
+				return T.int;
+			case "float":
+			case "double":
+			case "number":
+				return T.float;
+			case "bool":
+			case "boolean":
+				return T.bool;
+			case "string":
+				return T.string;
+			case "void":
+				return T.void;
+			case "null":
+				return T.null;
+			case "any":
+				return T.any;
+			case "unknown":
+				return T.any;
+			case "buffer":
+				return T.buffer;
+			case "thread":
+				return T.thread;
+			case "task":
+				return { k: "task", result: node.args.length ? this.resolveType(node.args[0]) : T.any };
+			case "list":
+				return node.args.length ? T.list(this.resolveType(node.args[0])) : T.list(T.any, false);
+			case "array":
+				return arity(1, "array") ? T.list(this.resolveType(node.args[0])) : T.list(T.unknown);
+			case "dictionary":
+			case "dict":
+			case "map":
+				return arity(2, "dictionary") ? T.dict(this.resolveType(node.args[0]), this.resolveType(node.args[1])) : T.dict(T.unknown, T.unknown);
+			case "Option":
+				return arity(1, "Option") ? T.option(this.resolveType(node.args[0])) : T.unknown;
+			case "Result":
+				return arity(2, "Result") ? { k: "result", ok: this.resolveType(node.args[0]), err: this.resolveType(node.args[1]) } : T.unknown;
+			case "Vector4":
+				this.error("RBX5002", node.span, "Vector4 has no Roblox equivalent", ["use Color3 for colors, Rect/UDim2 for 2D boxes, or a struct"]);
+				return T.unknown;
+			case "signal":
+				return { k: "clSignal", params: null };
+			case "RBXScriptSignal":
+				return { k: "rbxSignal", args: args() };
+			default:
+				break;
+		}
+		if (name === "Vector2" || name === "Vector3") {
+			return T.datatype(name);
+		}
+		if (this.api.hasClass(name)) {
+			this.requireRoblox(node.span, name);
+			return T.instance(name);
+		}
+		if (this.api.hasDatatype(name) || name === "RBXScriptConnection") {
+			this.requireRoblox(node.span, name);
+			return T.datatype(name);
+		}
+		const candidates = [...this.allTypeNames()];
+		const s = suggest(name, candidates);
+		this.error("CL2021", node.span, `unknown type '${name}'`, s ? [`did you mean '${s}'?`] : this.robloxLinked ? undefined : ["Roblox types (Player, Part, CFrame…) need `link @clpp.roblox;`"]);
+		return T.unknown;
+	}
+
+	private *allTypeNames(): Iterable<string> {
+		let cur: Scope | null = this.scope;
+		while (cur) {
+			yield* cur.types.keys();
+			cur = cur.parent;
+		}
+		yield* ["int", "float", "bool", "string", "void", "list", "array", "dictionary", "Option", "Result", "task", "buffer", "Vector2", "Vector3"];
+		if (this.robloxLinked) {
+			yield* Object.keys(this.api.classes);
+			yield* Object.keys(this.api.datatypes);
+		}
+	}
+
+	/** Roblox names need `link @clpp.roblox;` so pure CL++ modules stay portable to the clpp VM. */
+	requireRoblox(span: Span, what: string): void {
+		if (!this.robloxLinked) {
+			this.error("MOD9004", span, `'${what}' is part of the Roblox API; add \`link @clpp.roblox;\` at the top of the file`, [
+				"files without it stay pure CL++ and also run on the clpp VM",
+			]);
+			this.robloxLinked = true; // report once
+		}
+	}
+
+	// ---------- pass 3: check ----------
+
+	private checkTopLevel(): void {
+		const moduleFile = this.input.kind === "module";
+		for (const stmt of this.program.body) {
+			if (stmt.kind === "Decl") {
+				this.checkDecl(stmt.decl);
+				continue;
+			}
+			if (moduleFile && !isModuleLevelStatement(stmt)) {
+				this.warn("MOD9010", stmt.span, "this statement runs once, when the module is first required", [
+					"CL++ modules only declare things; move the code into a function the scripts call",
+				]);
+			}
+			checkStatement(this, stmt);
+		}
+	}
+
+	private checkDecl(decl: Decl): void {
+		switch (decl.kind) {
+			case "Func": {
+				this.scheduleBody(decl, null);
+				return;
+			}
+			case "Struct": {
+				const info = this.structs.get(`${this.input.moduleId}::${decl.name}`);
+				if (!info) {
+					return;
+				}
+				for (const f of info.fields) {
+					if (f.defaultValue && f.owner === info.name) {
+						const t = checkExpr(this, f.defaultValue, f.type);
+						this.expectAssignable(f.type, t, f.defaultValue.span, `default value of field '${f.name}'`);
+					}
+				}
+				for (const m of decl.methods) {
+					this.scheduleBody(m, info);
+				}
+				return;
+			}
+			case "Namespace":
+				for (const f of decl.funcs) {
+					this.scheduleBody(f, null);
+				}
+				return;
+			default:
+				return;
+		}
+	}
+
+	private scheduleBody(decl: FuncDecl, owner: StructInfo | null): void {
+		if (!decl.body) {
+			return;
+		}
+		this.pendingBodies.set(decl, () => this.checkFunctionBody(decl, owner));
+	}
+
+	/** Check a function body now (used when a caller needs its inferred return type). */
+	ensureBodyChecked(decl: FuncDecl): void {
+		const job = this.pendingBodies.get(decl);
+		if (!job || this.checking.has(decl)) {
+			return;
+		}
+		this.pendingBodies.delete(decl);
+		this.checking.add(decl);
+		const savedScope = this.scope;
+		const savedFn = this.fn;
+		const savedLoop = this.loopDepth;
+		const savedSwitch = this.switchDepth;
+		this.scope = this.fileScope;
+		this.fn = null;
+		this.loopDepth = 0;
+		this.switchDepth = 0;
+		try {
+			job();
+		} finally {
+			this.scope = savedScope;
+			this.fn = savedFn;
+			this.loopDepth = savedLoop;
+			this.switchDepth = savedSwitch;
+			this.checking.delete(decl);
+		}
+	}
+
+	isChecking(decl: FuncDecl): boolean {
+		return this.checking.has(decl);
+	}
+
+	/**
+	 * Callers before callees: a call site records its argument types into the callee's unannotated
+	 * parameters (see calls.ts), so a body is checked once no pending function still calls it.
+	 */
+	private drainBodies(): void {
+		const callees = new Map<FuncDecl, Set<string>>();
+		for (const decl of this.pendingBodies.keys()) {
+			callees.set(decl, calledNames(decl.body || []));
+		}
+		while (this.pendingBodies.size) {
+			const pending = [...this.pendingBodies.keys()];
+			const next =
+				pending.find((d) => !pending.some((other) => other !== d && callees.get(other)?.has(d.name))) ?? pending[0];
+			this.ensureBodyChecked(next);
+		}
+	}
+
+	private checkFunctionBody(decl: FuncDecl, owner: StructInfo | null): void {
+		const sym = this.funcSyms.get(decl) ?? null;
+		const fnType = (sym?.type ?? this.signatureOf(decl, null)) as Extract<Type, { k: "func" }>;
+		this.pushTypeParams([...(owner?.typeParams ?? []), ...decl.typeParams]);
+		const isMethod = Boolean(owner) && !decl.isStatic;
+		const parallel = (decl.attributes || []).some((a) => a.name === "parallel");
+		const declaredRet = decl.returnType ? (decl.isAsync ? (prune(fnType.ret) as Extract<Type, { k: "task" }>).result : fnType.ret) : null;
+		const ctx: FnCtx = {
+			decl,
+			declaredRet,
+			returns: [],
+			depth: 1,
+			isMethod,
+			structId: owner?.id ?? null,
+			selfSym: null,
+			isAsync: decl.isAsync,
+			yields: false,
+			mutatesSelf: false,
+			contextOnly: sym?.contextOnly,
+			isParallel: parallel,
+			sym,
+		};
+		this.fn = ctx;
+		this.pushScope("function");
+		if (isMethod && owner) {
+			const selfType: Type = { k: "struct", id: owner.id, name: owner.name, args: owner.typeParams.map((p) => ({ k: "param", name: p }) as Type) };
+			ctx.selfSym = this.declare("self", "self", selfType, decl.nameSpan, true);
+			ctx.selfSym.used = true;
+		}
+		this.declareParams(decl.params);
+		for (const stmt of decl.body!) {
+			checkStatement(this, stmt);
+		}
+		this.finishFunction(ctx, decl.body!, decl.nameSpan, decl.name);
+		this.popScope();
+		this.popTypeParams();
+		if (sym) {
+			sym.type = fnType;
+		}
+		if (owner && isMethod) {
+			const m = owner.methods.get(decl.name);
+			if (m && m.decl === decl) {
+				m.mutatesSelf = ctx.mutatesSelf;
+			}
+		}
+		(decl.fn ||= {}).mayYield = ctx.yields;
+		decl.fn.isMethod = isMethod;
+		decl.fn.ownerStruct = owner?.id;
+		decl.fn.selfMutated = ctx.mutatesSelf;
+		this.fn = null;
+		if (!decl.returnType) {
+			const inferred = ctx.returns.length ? ctx.returns.reduce((a, b) => join(this, a, b)) : T.void;
+			const retSlot = decl.isAsync ? (prune(fnType.ret) as Extract<Type, { k: "task" }>).result : fnType.ret;
+			if (retSlot.k === "infer" && !retSlot.resolved) {
+				retSlot.resolved = inferred;
+			}
+		}
+	}
+
+	declareParams(params: Param[]): void {
+		for (const p of params) {
+			const t = p.ty ?? (p.type ? this.resolveType(p.type) : T.any);
+			const sym = this.declare(p.name, "param", t, p.span, true);
+			sym.used = true;
+			p.sym = sym;
+			if (p.defaultValue) {
+				const dt = checkExpr(this, p.defaultValue, prune(t).k === "infer" ? undefined : t);
+				if (prune(t).k === "infer" && !(prune(t) as { resolved: Type | null }).resolved) {
+					(prune(t) as { resolved: Type | null }).resolved = dt.k === "null" ? T.any : widenLiteral(dt);
+				} else {
+					this.expectAssignable(t, dt, p.defaultValue.span, `default value of '${p.name}'`);
+				}
+			}
+		}
+	}
+
+	/** Missing-return and unreachable-code checks shared by functions and lambdas. */
+	finishFunction(ctx: FnCtx, body: Stmt[], nameSpan: Span, name: string): void {
+		const ret = ctx.declaredRet ? prune(ctx.declaredRet) : null;
+		if (ret && ret.k !== "void" && ret.k !== "any" && !(ret.k === "option") && !alwaysExits(this, body)) {
+			this.error("CL4001", nameSpan, `missing return: '${name}' must return ${typeToString(ret)} on every path`);
+		} else if (ret && ret.k === "option" && !alwaysExits(this, body)) {
+			// Option<T> may fall through to null; mention it in strict mode only.
+			if (this.strict) {
+				this.warn("CL4002", nameSpan, `'${name}' can reach the end without returning; it returns null there`);
+			}
+		}
+	}
+
+	// ---------- shared checks ----------
+
+	expectAssignable(to: Type, from: Type, span: Span, what: string): boolean {
+		const r = assignable(this, to, from);
+		if (r === "ok") {
+			return true;
+		}
+		if (r === "nullable") {
+			this.strictError("CL3011", span, `${what}: ${typeToString(from)} may be null, but ${typeToString(to)} is expected`, [
+				"check it first (`if (x != null) { … }`) or declare the target as optional (`" + typeToString(to) + "?`)",
+			]);
+			return false;
+		}
+		if (r === "narrowing") {
+			this.strictError("CL3012", span, `${what}: ${typeToString(from)} does not fit in ${typeToString(to)} without losing the fraction`, [
+				"convert explicitly with `int(x)` (truncates) or `Axiom.Round(x)`",
+			]);
+			return false;
+		}
+		this.error("CL3010", span, `${what}: expected ${typeToString(to)}, got ${typeToString(from)}`);
+		return false;
+	}
+
+	/** Mark a value-table read as copied when it flows into a new owner (CL++ value semantics). */
+	markCopy(expr: Expr): void {
+		if (!isValueTable(expr.ty ?? T.unknown)) {
+			return;
+		}
+		switch (expr.kind) {
+			case "Name":
+			case "Member":
+			case "Index":
+			case "SelfField":
+				expr.copy = true;
+				return;
+			default:
+				return;
+		}
+	}
+
+	noteYield(): void {
+		if (this.fn) {
+			this.fn.yields = true;
+		}
+	}
+
+	effectiveContext(): RunContext {
+		if (this.fn?.contextOnly) {
+			return this.fn.contextOnly;
+		}
+		return this.input.context;
+	}
+
+	/** Enforce a server/client rule at a use site. */
+	checkContext(only: "server" | "client", span: Span, what: string, why: string, severity: "error" | "warning" = "error"): void {
+		const here = this.effectiveContext();
+		if (here === "shared" || here === "plugin" || here === only) {
+			return;
+		}
+		const message = `${what} cannot be used in ${contextLabel(here)}: ${why}`;
+		const notes = [only === "server" ? "move this code to a .server.clp script or ask the server through a RemoteEvent" : "move this code to a .client.clp LocalScript"];
+		if (severity === "error") {
+			this.error("CTX6002", span, message, notes);
+		} else {
+			this.warn("CTX6002", span, message, notes);
+		}
+	}
+
+	useService(name: string, span: Span): void {
+		this.requireRoblox(span, name);
+		this.services.add(name);
+	}
+
+	// ---------- pass 4 ----------
+
+	private finalize(): void {
+		this.reportUnused(this.fileScope);
+		for (const call of this.mutatingCalls) {
+			if (!call.method.mutatesSelf) {
+				continue;
+			}
+			const root = call.root;
+			root.mutatedFields = true;
+			if ((root.kind === "var" || root.kind === "param") && !root.mutable) {
+				this.error("CL2047", call.span, `${call.method.name}() changes '${root.name}', which is declared with let`, ["declare it with `let mut`"]);
+			}
+		}
+		for (const { arg, decl, index } of this.deferredCopies) {
+			const param = decl.params[index]?.sym as Sym | undefined;
+			if (!param || param.mutatedFields || param.assigned || param.captured) {
+				this.markCopy(arg);
+			}
+		}
+		for (const sym of this.fileScope.values.values()) {
+			switch (sym.kind) {
+				case "func":
+					if (sym.decl && !sym.decl.isExtern) {
+						this.exports.funcs.set(sym.name, {
+							name: sym.name,
+							type: sym.type as Extract<Type, { k: "func" }>,
+							contextOnly: sym.contextOnly,
+							yields: sym.decl.fn?.mayYield,
+							doc: sym.doc,
+						});
+					}
+					break;
+				case "const":
+					if (sym.constValue !== undefined) {
+						this.exports.consts.set(sym.name, { type: sym.type, value: sym.constValue });
+					}
+					break;
+				default:
+					break;
+			}
+		}
+		for (const s of this.ownStructs) {
+			this.exports.structs.set(s.name, s);
+		}
+		for (const e of this.ownEnums) {
+			this.exports.enums.set(e.name, e);
+		}
+		for (const [, v] of this.variants) {
+			if (v.id.startsWith(`${this.input.moduleId}::`)) {
+				this.exports.variants.set(v.name, v);
+			}
+		}
+		for (const [name, sym] of this.fileScope.types) {
+			if (sym.kind === "alias" && sym.file === this.input.moduleId) {
+				this.exports.aliases.set(name, sym.type);
+			}
+		}
+		if (this.input.kind === "script" && this.input.context !== "shared") {
+			const init = this.fileScope.values.get("init");
+			if (init && init.kind === "func" && !init.used && init.decl && init.decl.params.length === 0) {
+				this.warn("CL4010", init.span, "function init() is never called", [
+					"CL++ 0.9 has no entry function: top-level statements run when the script starts",
+					"call `init();` at the end of the file or move its body to the top level",
+				]);
+			}
+		}
+	}
+}
+
+export function widenLiteral(t: Type): Type {
+	const p = prune(t);
+	if (p.k === "lit") {
+		return typeof p.value === "string" ? T.string : typeof p.value === "boolean" ? T.bool : Number.isInteger(p.value) ? T.int : T.float;
+	}
+	return p;
+}
+
+/** Names called directly (`f(…)`, `obj.f(…)`) anywhere in a body — a cheap syntactic call graph. */
+function calledNames(body: Stmt[]): Set<string> {
+	const out = new Set<string>();
+	const visit = (node: unknown): void => {
+		if (!node || typeof node !== "object") {
+			return;
+		}
+		if (Array.isArray(node)) {
+			for (const n of node) {
+				visit(n);
+			}
+			return;
+		}
+		const rec = node as { kind?: string; callee?: { kind: string; name?: string } };
+		if (rec.kind === "Call" && rec.callee && (rec.callee.kind === "Name" || rec.callee.kind === "Member") && rec.callee.name) {
+			out.add(rec.callee.name);
+		}
+		for (const [key, value] of Object.entries(node)) {
+			if (key !== "ty" && key !== "res" && key !== "span" && value && typeof value === "object") {
+				visit(value);
+			}
+		}
+	};
+	visit(body);
+	return out;
+}
+
+function isModuleLevelStatement(stmt: Stmt): boolean {
+	switch (stmt.kind) {
+		case "Var":
+		case "Signal":
+		case "Using":
+		case "Decl":
+			return true;
+		case "Connect":
+			return false;
+		default:
+			return false;
+	}
+}
+
+function contextAttribute(attrs: Attribute[]): "server" | "client" | undefined {
+	for (const a of attrs) {
+		if (a.name === "server" || a.name === "client") {
+			return a.name;
+		}
+	}
+	return undefined;
+}
+
+/** Compile-time value of a literal/constant expression (`60 * 60`, `"a" .: "b"`). */
+export function foldConstant(expr: Expr): number | string | boolean | null | undefined {
+	switch (expr.kind) {
+		case "Number":
+			return expr.value;
+		case "String":
+			return expr.value;
+		case "Bool":
+			return expr.value;
+		case "Null":
+			return null;
+		case "Unary": {
+			const v = foldConstant(expr.operand);
+			if (expr.op === "-" && typeof v === "number") {
+				return -v;
+			}
+			if (expr.op === "not" && typeof v === "boolean") {
+				return !v;
+			}
+			return undefined;
+		}
+		case "Binary": {
+			const l = foldConstant(expr.left);
+			const r = foldConstant(expr.right);
+			if (typeof l === "number" && typeof r === "number") {
+				const isInt = Number.isInteger(l) && Number.isInteger(r) && !isFloatLiteral(expr.left) && !isFloatLiteral(expr.right);
+				switch (expr.op) {
+					case "+":
+						return l + r;
+					case "-":
+						return l - r;
+					case "*":
+						return l * r;
+					case "/":
+						return r === 0 ? undefined : isInt ? Math.trunc(l / r) : l / r;
+					case "%":
+						return r === 0 ? undefined : l % r;
+					default:
+						return undefined;
+				}
+			}
+			if (expr.op === ".:" && (typeof l === "string" || typeof l === "number") && (typeof r === "string" || typeof r === "number")) {
+				return `${l}${r}`;
+			}
+			return undefined;
+		}
+		default:
+			return undefined;
+	}
+}
+
+function isFloatLiteral(e: Expr): boolean {
+	return (e.kind === "Number" && e.isFloat) || (e.kind === "Binary" && (isFloatLiteral(e.left) || isFloatLiteral(e.right)));
+}
+
+export { applyNarrowings, checkCondition, conditionNarrowings, exprPathKey, nonNull };
+export type { VarName, StructDecl, EnumDecl };