cluaupp 1.5.2 → 2.0.0-beta.1

package/generated/compiler/checker/checker.js

@@ -0,0 +1,1215 @@
+"use strict";
+/**
+ * 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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nonNull = exports.exprPathKey = exports.conditionNarrowings = exports.checkCondition = exports.applyNarrowings = exports.Checker = void 0;
+exports.widenLiteral = widenLiteral;
+exports.foldConstant = foldConstant;
+const diagnostics_js_1 = require("../diagnostics.js");
+const context_js_1 = require("../roblox/context.js");
+const types_js_1 = require("../types.js");
+Object.defineProperty(exports, "nonNull", { enumerable: true, get: function () { return types_js_1.nonNull; } });
+const exprs_js_1 = require("./exprs.js");
+Object.defineProperty(exports, "checkCondition", { enumerable: true, get: function () { return exprs_js_1.checkCondition; } });
+Object.defineProperty(exports, "exprPathKey", { enumerable: true, get: function () { return exprs_js_1.exprPathKey; } });
+const flow_js_1 = require("./flow.js");
+Object.defineProperty(exports, "applyNarrowings", { enumerable: true, get: function () { return flow_js_1.applyNarrowings; } });
+Object.defineProperty(exports, "conditionNarrowings", { enumerable: true, get: function () { return flow_js_1.conditionNarrowings; } });
+const symbols_js_1 = require("./symbols.js");
+const typeops_js_1 = require("./typeops.js");
+const statements_js_1 = require("./statements.js");
+let nextSymId = 1;
+class Checker {
+    api;
+    diags;
+    source;
+    program;
+    input;
+    fileScope;
+    scope;
+    fn = null;
+    loopDepth = 0;
+    switchDepth = 0;
+    structs = new Map();
+    enums = new Map();
+    variants = new Map();
+    links = [];
+    services = new Set();
+    symbols = [];
+    funcSyms = new Map();
+    ownStructs = [];
+    ownEnums = [];
+    exports;
+    robloxLinked = false;
+    usesShared = false;
+    /** Struct/list arguments passed to user functions: copied only if the callee mutates the parameter. */
+    deferredCopies = [];
+    /** Method calls on a binding; a self-mutating method needs a mutable binding. */
+    mutatingCalls = [];
+    /** Function bodies not yet checked. */
+    pendingBodies = new Map();
+    checking = new Set();
+    strict;
+    constructor(input) {
+        this.input = input;
+        this.api = input.api;
+        this.diags = input.diags;
+        this.source = input.source;
+        this.program = input.program;
+        this.fileScope = new symbols_js_1.Scope(null, "file", 0);
+        this.scope = this.fileScope;
+        this.strict = input.program.mode === "strict" || (input.strict && input.program.mode !== "nonstrict");
+        this.exports = (0, symbols_js_1.emptyExports)(input.moduleId, input.source.path, input.kind, input.context);
+        this.exports.dmPath = input.dmPath;
+    }
+    // ---------- TypeEnv ----------
+    struct(id) {
+        return this.structs.get(id);
+    }
+    // ---------- diagnostics helpers ----------
+    get nocheck() {
+        return this.program.mode === "nocheck";
+    }
+    error(code, span, message, notes) {
+        if (this.nocheck && !code.startsWith("CL1") && !code.startsWith("MOD")) {
+            return;
+        }
+        this.diags.error(code, span, message, notes);
+    }
+    warn(code, span, message, notes) {
+        if (this.nocheck) {
+            return;
+        }
+        this.diags.warning(code, span, message, notes);
+    }
+    /** Error in strict mode, warning otherwise. */
+    strictError(code, span, message, notes) {
+        if (this.strict) {
+            this.error(code, span, message, notes);
+        }
+        else {
+            this.warn(code, span, message, notes);
+        }
+    }
+    // ---------- symbols ----------
+    newSym(name, kind, type, span, mutable = false) {
+        const 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, kind, type, span, mutable = false, scope = this.scope) {
+        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, kind, type, span, typeId) {
+        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 = "block") {
+        this.scope = new symbols_js_1.Scope(this.scope, kind, this.fn ? this.fn.depth : 0);
+        return this.scope;
+    }
+    popScope() {
+        this.reportUnused(this.scope);
+        this.scope = this.scope.parent ?? this.fileScope;
+    }
+    reportUnused(scope) {
+        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() {
+        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 ----------
+    declarePass() {
+        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 || []);
+        }
+    }
+    predeclareConst(stmt) {
+        const name = stmt.names[0];
+        const value = stmt.init ? foldConstant(stmt.init) : undefined;
+        const type = value === undefined ? types_js_1.T.unknown : value === null ? types_js_1.T.null : typeof value === "string" ? types_js_1.T.string : typeof value === "boolean" ? types_js_1.T.bool : Number.isInteger(value) && !(stmt.init?.kind === "Number" && stmt.init.isFloat) ? types_js_1.T.int : types_js_1.T.float;
+        const sym = this.declare(name.name, "const", type, name.span);
+        if (value !== undefined) {
+            sym.constValue = value;
+        }
+        name.sym = sym;
+        stmt.predeclared = true;
+    }
+    declareDecl(decl, attrs) {
+        switch (decl.kind) {
+            case "Link":
+                this.declareLink(decl);
+                return;
+            case "Struct": {
+                const id = `${this.input.moduleId}::${decl.name}`;
+                const info = {
+                    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 = { k: "struct", id, name: decl.name, args: decl.typeParams.map((p) => ({ k: "param", name: p })) };
+                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 = {
+                    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 = { 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", types_js_1.T.func([{ name: "value", type: types_js_1.T.any, optional: false }], { k: "variant", id, name: decl.name, alternatives: [] }), decl.nameSpan).typeId = id;
+                return;
+            }
+            case "TypeAlias":
+                this.declareType(decl.name, "alias", types_js_1.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", types_js_1.T.func([], types_js_1.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;
+        }
+    }
+    declareLink(decl) {
+        const target = this.input.resolveLink(decl);
+        const info = { 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 })) }, 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", moduleId: target.exports.moduleId, alias: decl.alias } : { kind: "luauModule", 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. */
+    checkLinkContext(decl, targetContext, dmPath) {
+        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 ----------
+    resolvePass() {
+        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 = types_js_1.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();
+                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, 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;
+                signalSym.signalParams = params;
+                signalSym.type = { k: "clSignal", params };
+            }
+        }
+    }
+    resolveStruct(info, visiting) {
+        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 = [];
+        const seenFields = new Map();
+        const methods = new Map();
+        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 (!(0, types_js_1.isDynamic)(baseType)) {
+                    this.error("CL3021", baseNode.span, `'${(0, types_js_1.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 = { 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 = { k: "struct", id: info.id, name: info.name, args: info.typeParams.map((p) => ({ k: "param", name: p })) };
+        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);
+            const method = {
+                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);
+    }
+    typeParamStack = [];
+    pushTypeParams(names) {
+        this.typeParamStack.push(new Set(names));
+    }
+    popTypeParams() {
+        this.typeParamStack.pop();
+    }
+    isTypeParam(name) {
+        return this.typeParamStack.some((s) => s.has(name));
+    }
+    /** Signature of a function declaration (params without types learn from call sites). */
+    signatureOf(decl, selfType) {
+        this.pushTypeParams(decl.typeParams);
+        const params = [];
+        let variadic = null;
+        for (const p of decl.params) {
+            if (p.variadic) {
+                variadic = p.type ? this.resolveType(p.type) : types_js_1.T.any;
+                p.ty = types_js_1.T.list(variadic);
+                continue;
+            }
+            const t = p.type ? this.resolveType(p.type) : { k: "infer", resolved: null };
+            p.ty = t;
+            params.push({ name: p.name, type: t, optional: p.defaultValue !== null || (0, types_js_1.prune)(t).k === "option" });
+        }
+        let ret = decl.returnType ? this.resolveType(decl.returnType) : decl.body === null ? types_js_1.T.void : { k: "infer", resolved: null };
+        if (decl.isAsync) {
+            ret = { k: "task", result: ret };
+        }
+        this.popTypeParams();
+        const fn = { k: "func", params, ret, variadic };
+        if (decl.typeParams.length) {
+            fn.generics = decl.typeParams;
+        }
+        void selfType;
+        return fn;
+    }
+    // ---------- type nodes ----------
+    resolveType(node) {
+        switch (node.kind) {
+            case "Literal":
+                return { k: "lit", value: node.value };
+            case "Optional":
+                return types_js_1.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 types_js_1.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 types_js_1.T.func(node.params.map((p, i) => ({ name: `arg${i + 1}`, type: this.resolveType(p), optional: false })), node.ret ? this.resolveType(node.ret) : types_js_1.T.void);
+            case "Named":
+                return this.resolveNamedType(node);
+            default:
+                return types_js_1.T.unknown;
+        }
+    }
+    resolveNamedType(node) {
+        const args = () => node.args.map((a) => this.resolveType(a));
+        const arity = (n, what) => {
+            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 = (0, diagnostics_js_1.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 types_js_1.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 types_js_1.T.unknown;
+            }
+            if (mod && mod.kind === "module") {
+                mod.used = true;
+                return types_js_1.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;
+                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 types_js_1.T.int;
+            case "float":
+            case "double":
+            case "number":
+                return types_js_1.T.float;
+            case "bool":
+            case "boolean":
+                return types_js_1.T.bool;
+            case "string":
+                return types_js_1.T.string;
+            case "void":
+                return types_js_1.T.void;
+            case "null":
+                return types_js_1.T.null;
+            case "any":
+                return types_js_1.T.any;
+            case "unknown":
+                return types_js_1.T.any;
+            case "buffer":
+                return types_js_1.T.buffer;
+            case "thread":
+                return types_js_1.T.thread;
+            case "task":
+                return { k: "task", result: node.args.length ? this.resolveType(node.args[0]) : types_js_1.T.any };
+            case "list":
+                return node.args.length ? types_js_1.T.list(this.resolveType(node.args[0])) : types_js_1.T.list(types_js_1.T.any, false);
+            case "array":
+                return arity(1, "array") ? types_js_1.T.list(this.resolveType(node.args[0])) : types_js_1.T.list(types_js_1.T.unknown);
+            case "dictionary":
+            case "dict":
+            case "map":
+                return arity(2, "dictionary") ? types_js_1.T.dict(this.resolveType(node.args[0]), this.resolveType(node.args[1])) : types_js_1.T.dict(types_js_1.T.unknown, types_js_1.T.unknown);
+            case "Option":
+                return arity(1, "Option") ? types_js_1.T.option(this.resolveType(node.args[0])) : types_js_1.T.unknown;
+            case "Result":
+                return arity(2, "Result") ? { k: "result", ok: this.resolveType(node.args[0]), err: this.resolveType(node.args[1]) } : types_js_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 types_js_1.T.unknown;
+            case "signal":
+                return { k: "clSignal", params: null };
+            case "RBXScriptSignal":
+                return { k: "rbxSignal", args: args() };
+            default:
+                break;
+        }
+        if (name === "Vector2" || name === "Vector3") {
+            return types_js_1.T.datatype(name);
+        }
+        if (this.api.hasClass(name)) {
+            this.requireRoblox(node.span, name);
+            return types_js_1.T.instance(name);
+        }
+        if (this.api.hasDatatype(name) || name === "RBXScriptConnection") {
+            this.requireRoblox(node.span, name);
+            return types_js_1.T.datatype(name);
+        }
+        const candidates = [...this.allTypeNames()];
+        const s = (0, diagnostics_js_1.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 types_js_1.T.unknown;
+    }
+    *allTypeNames() {
+        let cur = 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, what) {
+        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 ----------
+    checkTopLevel() {
+        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",
+                ]);
+            }
+            (0, statements_js_1.checkStatement)(this, stmt);
+        }
+    }
+    checkDecl(decl) {
+        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 = (0, exprs_js_1.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;
+        }
+    }
+    scheduleBody(decl, owner) {
+        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) {
+        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) {
+        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.
+     */
+    drainBodies() {
+        const callees = new Map();
+        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);
+        }
+    }
+    checkFunctionBody(decl, owner) {
+        const sym = this.funcSyms.get(decl) ?? null;
+        const fnType = (sym?.type ?? this.signatureOf(decl, null));
+        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 ? (0, types_js_1.prune)(fnType.ret).result : fnType.ret) : null;
+        const ctx = {
+            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 = { k: "struct", id: owner.id, name: owner.name, args: owner.typeParams.map((p) => ({ k: "param", name: p })) };
+            ctx.selfSym = this.declare("self", "self", selfType, decl.nameSpan, true);
+            ctx.selfSym.used = true;
+        }
+        this.declareParams(decl.params);
+        for (const stmt of decl.body) {
+            (0, statements_js_1.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) => (0, typeops_js_1.join)(this, a, b)) : types_js_1.T.void;
+            const retSlot = decl.isAsync ? (0, types_js_1.prune)(fnType.ret).result : fnType.ret;
+            if (retSlot.k === "infer" && !retSlot.resolved) {
+                retSlot.resolved = inferred;
+            }
+        }
+    }
+    declareParams(params) {
+        for (const p of params) {
+            const t = p.ty ?? (p.type ? this.resolveType(p.type) : types_js_1.T.any);
+            const sym = this.declare(p.name, "param", t, p.span, true);
+            sym.used = true;
+            p.sym = sym;
+            if (p.defaultValue) {
+                const dt = (0, exprs_js_1.checkExpr)(this, p.defaultValue, (0, types_js_1.prune)(t).k === "infer" ? undefined : t);
+                if ((0, types_js_1.prune)(t).k === "infer" && !(0, types_js_1.prune)(t).resolved) {
+                    (0, types_js_1.prune)(t).resolved = dt.k === "null" ? types_js_1.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, body, nameSpan, name) {
+        const ret = ctx.declaredRet ? (0, types_js_1.prune)(ctx.declaredRet) : null;
+        if (ret && ret.k !== "void" && ret.k !== "any" && !(ret.k === "option") && !(0, flow_js_1.alwaysExits)(this, body)) {
+            this.error("CL4001", nameSpan, `missing return: '${name}' must return ${(0, types_js_1.typeToString)(ret)} on every path`);
+        }
+        else if (ret && ret.k === "option" && !(0, flow_js_1.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, from, span, what) {
+        const r = (0, typeops_js_1.assignable)(this, to, from);
+        if (r === "ok") {
+            return true;
+        }
+        if (r === "nullable") {
+            this.strictError("CL3011", span, `${what}: ${(0, types_js_1.typeToString)(from)} may be null, but ${(0, types_js_1.typeToString)(to)} is expected`, [
+                "check it first (`if (x != null) { … }`) or declare the target as optional (`" + (0, types_js_1.typeToString)(to) + "?`)",
+            ]);
+            return false;
+        }
+        if (r === "narrowing") {
+            this.strictError("CL3012", span, `${what}: ${(0, types_js_1.typeToString)(from)} does not fit in ${(0, types_js_1.typeToString)(to)} without losing the fraction`, [
+                "convert explicitly with `int(x)` (truncates) or `Axiom.Round(x)`",
+            ]);
+            return false;
+        }
+        this.error("CL3010", span, `${what}: expected ${(0, types_js_1.typeToString)(to)}, got ${(0, types_js_1.typeToString)(from)}`);
+        return false;
+    }
+    /** Mark a value-table read as copied when it flows into a new owner (CL++ value semantics). */
+    markCopy(expr) {
+        if (!(0, types_js_1.isValueTable)(expr.ty ?? types_js_1.T.unknown)) {
+            return;
+        }
+        switch (expr.kind) {
+            case "Name":
+            case "Member":
+            case "Index":
+            case "SelfField":
+                expr.copy = true;
+                return;
+            default:
+                return;
+        }
+    }
+    noteYield() {
+        if (this.fn) {
+            this.fn.yields = true;
+        }
+    }
+    effectiveContext() {
+        if (this.fn?.contextOnly) {
+            return this.fn.contextOnly;
+        }
+        return this.input.context;
+    }
+    /** Enforce a server/client rule at a use site. */
+    checkContext(only, span, what, why, severity = "error") {
+        const here = this.effectiveContext();
+        if (here === "shared" || here === "plugin" || here === only) {
+            return;
+        }
+        const message = `${what} cannot be used in ${(0, context_js_1.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, span) {
+        this.requireRoblox(span, name);
+        this.services.add(name);
+    }
+    // ---------- pass 4 ----------
+    finalize() {
+        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;
+            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,
+                            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",
+                ]);
+            }
+        }
+    }
+}
+exports.Checker = Checker;
+function widenLiteral(t) {
+    const p = (0, types_js_1.prune)(t);
+    if (p.k === "lit") {
+        return typeof p.value === "string" ? types_js_1.T.string : typeof p.value === "boolean" ? types_js_1.T.bool : Number.isInteger(p.value) ? types_js_1.T.int : types_js_1.T.float;
+    }
+    return p;
+}
+/** Names called directly (`f(…)`, `obj.f(…)`) anywhere in a body — a cheap syntactic call graph. */
+function calledNames(body) {
+    const out = new Set();
+    const visit = (node) => {
+        if (!node || typeof node !== "object") {
+            return;
+        }
+        if (Array.isArray(node)) {
+            for (const n of node) {
+                visit(n);
+            }
+            return;
+        }
+        const rec = node;
+        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) {
+    switch (stmt.kind) {
+        case "Var":
+        case "Signal":
+        case "Using":
+        case "Decl":
+            return true;
+        case "Connect":
+            return false;
+        default:
+            return false;
+    }
+}
+function contextAttribute(attrs) {
+    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"`). */
+function foldConstant(expr) {
+    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) {
+    return (e.kind === "Number" && e.isFloat) || (e.kind === "Binary" && (isFloatLiteral(e.left) || isFloatLiteral(e.right)));
+}