cluaupp 1.5.2 → 2.0.0-beta.1

package/generated/compiler/roblox/api.js

@@ -0,0 +1,388 @@
+"use strict";
+/**
+ * `@clpp.roblox` — the typed Roblox API surface (classes, datatypes, enums, services, globals,
+ * libraries) as the checker sees it. Loaded once from `api/roblox/surface.json`.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RobloxApi = void 0;
+exports.surfacePath = surfacePath;
+exports.robloxApi = robloxApi;
+exports.setRobloxApi = setRobloxApi;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const package_info_js_1 = require("../../package-info.js");
+const types_js_1 = require("../types.js");
+/** Library functions whose `number` results are always integers on Roblox. */
+const INT_RESULTS = new Set([
+    "math.floor", "math.ceil", "math.round", "math.sign", "string.len", "string.byte", "utf8.len", "utf8.codepoint",
+    "os.time", "buffer.len", "buffer.readi8", "buffer.readu8", "buffer.readi16", "buffer.readu16", "buffer.readi32",
+    "buffer.readu32", "buffer.readbits", "table.find", "table.maxn", "bit32.band", "bit32.bor", "bit32.bxor", "bit32.bnot",
+    "bit32.lshift", "bit32.rshift", "bit32.arshift", "bit32.lrotate", "bit32.rrotate", "bit32.extract", "bit32.replace",
+    "bit32.countlz", "bit32.countrz", "bit32.byteswap", "rawlen",
+]);
+class RobloxApi {
+    surface;
+    classes;
+    datatypes;
+    enums;
+    globals;
+    libraries;
+    aliases;
+    services;
+    memberCache = new Map();
+    convertCache = new WeakMap();
+    constructor(surface) {
+        this.surface = surface;
+        this.classes = surface.classes;
+        this.datatypes = surface.datatypes;
+        this.enums = surface.enums;
+        this.globals = surface.globals;
+        this.libraries = surface.libraries;
+        this.aliases = surface.aliases;
+        this.services = Object.values(surface.classes)
+            .filter((c) => c.service)
+            .map((c) => c.name);
+    }
+    hasClass(name) {
+        return Object.prototype.hasOwnProperty.call(this.classes, name);
+    }
+    hasDatatype(name) {
+        return Object.prototype.hasOwnProperty.call(this.datatypes, name);
+    }
+    hasEnum(name) {
+        return Object.prototype.hasOwnProperty.call(this.enums, name);
+    }
+    isService(name) {
+        return this.hasClass(name) && this.classes[name].service;
+    }
+    isA(cls, base) {
+        let cur = cls;
+        let guard = 0;
+        while (cur && guard++ < 64) {
+            if (cur === base) {
+                return true;
+            }
+            cur = this.classes[cur]?.superclass ?? null;
+        }
+        return false;
+    }
+    /** All members visible on a class (own first, then inherited). */
+    members(cls) {
+        const cached = this.memberCache.get(cls);
+        if (cached) {
+            return cached;
+        }
+        const out = new Map();
+        let cur = cls;
+        let guard = 0;
+        while (cur && guard++ < 64) {
+            const c = this.classes[cur];
+            if (!c) {
+                break;
+            }
+            for (const [name, member] of Object.entries(c.members)) {
+                if (!out.has(name)) {
+                    out.set(name, { member, owner: cur });
+                }
+            }
+            cur = c.superclass;
+        }
+        this.memberCache.set(cls, out);
+        return out;
+    }
+    member(cls, name) {
+        return this.members(cls).get(name) ?? null;
+    }
+    datatypeMember(name, member) {
+        return this.datatypes[name]?.members[member] ?? null;
+    }
+    datatypeStatic(name, member) {
+        return this.datatypes[name]?.statics[member] ?? null;
+    }
+    library(name) {
+        return this.libraries[name] ?? null;
+    }
+    // ---------- LType → Type ----------
+    convert(lt, context) {
+        const cached = this.convertCache.get(lt);
+        if (cached && !context) {
+            return cached;
+        }
+        const out = this.convertUncached(lt, context);
+        if (!context) {
+            this.convertCache.set(lt, out);
+        }
+        return out;
+    }
+    convertUncached(lt, context) {
+        switch (lt.k) {
+            case "name":
+                return this.convertName(lt.name, lt.args);
+            case "opt":
+                return types_js_1.T.option(this.convert(lt.t));
+            case "union": {
+                const hasNil = lt.ts.some((t) => t.k === "name" && t.name === "nil");
+                const rest = lt.ts.filter((t) => !(t.k === "name" && t.name === "nil")).map((t) => this.convert(t));
+                const allLit = rest.every((r) => r.k === "lit");
+                let base;
+                if (rest.length === 1) {
+                    base = rest[0];
+                }
+                else if (!allLit && rest.every((r) => r.k === "instance")) {
+                    base = types_js_1.T.instance("Instance");
+                }
+                else if (!allLit && rest.some((r) => r.k === "any")) {
+                    base = types_js_1.T.any;
+                }
+                else {
+                    base = { k: "union", members: rest };
+                }
+                return hasNil ? types_js_1.T.option(base) : base;
+            }
+            case "inter": {
+                const fns = lt.ts.filter((t) => t.k === "fn");
+                if (fns.length === lt.ts.length && fns.length > 0) {
+                    const converted = fns.map((f) => this.convertFn(f));
+                    const first = converted[0];
+                    return { ...first, overloads: converted };
+                }
+                const fields = {};
+                for (const t of lt.ts) {
+                    if (t.k === "table") {
+                        for (const [k, v] of Object.entries(t.fields)) {
+                            fields[k] = this.convert(v);
+                        }
+                    }
+                }
+                return { k: "table", fields };
+            }
+            case "array":
+                return types_js_1.T.list(this.convert(lt.t));
+            case "map":
+                return types_js_1.T.dict(this.convert(lt.key), this.convert(lt.value));
+            case "table": {
+                const fields = {};
+                for (const [k, v] of Object.entries(lt.fields)) {
+                    fields[k] = this.convert(v);
+                }
+                return { k: "table", fields };
+            }
+            case "fn":
+                return this.convertFn(lt, context);
+            case "lit":
+                return { k: "lit", value: lt.value };
+            case "pack":
+                return types_js_1.T.any;
+            default:
+                return types_js_1.T.any;
+        }
+    }
+    convertFn(fn, qualifiedName) {
+        const params = fn.params.map((p, i) => {
+            const t = this.convert(p.t);
+            return { name: p.name || `arg${i + 1}`, type: t.k === "option" ? t.inner : t, optional: t.k === "option" || (t.k === "any" && false) };
+        });
+        let ret;
+        const rets = fn.returns.map((r) => this.convert(r));
+        if (rets.length === 0) {
+            ret = fn.returnsVariadic ? types_js_1.T.any : types_js_1.T.void;
+        }
+        else if (rets.length === 1) {
+            ret = rets[0];
+        }
+        else {
+            ret = { k: "tuple", elems: rets };
+        }
+        if (qualifiedName && INT_RESULTS.has(qualifiedName)) {
+            ret = ret.k === "option" ? types_js_1.T.option(types_js_1.T.int) : ret.k === "float" ? types_js_1.T.int : ret;
+        }
+        const out = { k: "func", params, ret, variadic: fn.variadic ? this.convert(fn.variadic) : null };
+        if (fn.generics?.length) {
+            out.generics = fn.generics;
+        }
+        return out;
+    }
+    convertName(name, args) {
+        switch (name) {
+            case "number":
+            case "double":
+            case "float":
+                return types_js_1.T.float;
+            case "int":
+            case "int64":
+                return types_js_1.T.int;
+            case "string":
+                return types_js_1.T.string;
+            case "boolean":
+            case "bool":
+                return types_js_1.T.bool;
+            case "nil":
+            case "()":
+                return types_js_1.T.void;
+            case "any":
+            case "unknown":
+            case "userdata":
+            case "Object":
+                return name === "Object" ? types_js_1.T.instance("Object") : types_js_1.T.any;
+            case "never":
+                return types_js_1.T.never;
+            case "thread":
+                return types_js_1.T.thread;
+            case "buffer":
+                return types_js_1.T.buffer;
+            case "vector":
+                return types_js_1.T.datatype("Vector3");
+            case "RBXScriptSignal":
+                return { k: "rbxSignal", args: (args || []).filter((a) => !(a.k === "name" && a.name === "()")).map((a) => this.convert(a)) };
+            case "Instances":
+                return types_js_1.T.list(types_js_1.T.instance("Instance"));
+            case "Objects":
+                return types_js_1.T.list(types_js_1.T.instance("Instance"));
+            case "Enum":
+                return { k: "rbxEnum", enumName: "*" };
+            case "EnumItem":
+                return { k: "rbxEnumItem", enumName: "*" };
+            default:
+                break;
+        }
+        if (this.hasClass(name)) {
+            return types_js_1.T.instance(name);
+        }
+        if (this.hasDatatype(name)) {
+            return types_js_1.T.datatype(name);
+        }
+        if (name.startsWith("Enum") && this.hasEnum(name.slice(4))) {
+            return { k: "rbxEnumItem", enumName: name.slice(4) };
+        }
+        if (name.startsWith("Enum.") && this.hasEnum(name.slice(5))) {
+            return { k: "rbxEnumItem", enumName: name.slice(5) };
+        }
+        const alias = this.aliases[name];
+        if (alias) {
+            return this.convert(alias);
+        }
+        return types_js_1.T.any;
+    }
+    /** Function type of a library member (`math.floor`), with integer results applied. */
+    libraryFunction(lib, member) {
+        const st = this.libraries[lib]?.[member];
+        if (!st) {
+            return null;
+        }
+        if (st.kind === "value") {
+            return st.type ? this.convert(st.type) : types_js_1.T.any;
+        }
+        const fns = (st.overloads || []).map((f) => this.convertFn(f, `${lib}.${member}`));
+        if (fns.length === 0) {
+            return types_js_1.T.any;
+        }
+        const first = fns[0];
+        return fns.length > 1 ? { ...first, overloads: fns } : first;
+    }
+    globalFunction(name) {
+        const g = this.globals[name];
+        if (!g) {
+            return null;
+        }
+        if (g.overloads) {
+            const fns = g.overloads.map((f) => this.convertFn(f, name));
+            const first = fns[0];
+            return fns.length > 1 ? { ...first, overloads: fns } : first;
+        }
+        return g.type ? this.convert(g.type) : types_js_1.T.any;
+    }
+    methodType(member) {
+        const fns = (member.overloads || []).map((f) => this.convertFn(f));
+        if (fns.length === 0) {
+            return types_js_1.T.func([], types_js_1.T.void);
+        }
+        const first = fns[0];
+        return fns.length > 1 ? { ...first, overloads: fns } : first;
+    }
+    staticFunctionType(st) {
+        if (st.kind === "value") {
+            return st.type ? this.convert(st.type) : types_js_1.T.any;
+        }
+        const fns = (st.overloads || []).map((f) => this.convertFn(f));
+        const first = fns[0];
+        return fns.length > 1 ? { ...first, overloads: fns } : first;
+    }
+    /** Result type of `left <op> right` for datatypes (Vector3 + Vector3, CFrame * Vector3, 2 * v). */
+    operator(op, left, right) {
+        const meta = { "+": "__add", "-": "__sub", "*": "__mul", "/": "__div", "%": "__mod" };
+        const name = meta[op];
+        if (!name) {
+            return null;
+        }
+        const tryOn = (dt, other) => {
+            for (const fn of this.datatypes[dt]?.operators[name] || []) {
+                const param = fn.params[0] ? this.convert(fn.params[0].t) : null;
+                if (!param || this.acceptsOperand(param, other)) {
+                    return fn.returns[0] ? this.convert(fn.returns[0]) : null;
+                }
+            }
+            return null;
+        };
+        if (left.k === "datatype") {
+            const r = tryOn(left.name, right);
+            if (r) {
+                return r;
+            }
+        }
+        if (right.k === "datatype" && (op === "*" || op === "+") && (left.k === "int" || left.k === "float" || left.k === "lit")) {
+            return tryOn(right.name, left);
+        }
+        return null;
+    }
+    acceptsOperand(param, arg) {
+        if (param.k === "union") {
+            return param.members.some((m) => this.acceptsOperand(m, arg));
+        }
+        if (param.k === "float" || param.k === "int") {
+            return arg.k === "int" || arg.k === "float" || (arg.k === "lit" && typeof arg.value === "number");
+        }
+        if (param.k === "datatype") {
+            return arg.k === "datatype" && arg.name === param.name;
+        }
+        return param.k === "any";
+    }
+    unaryMinus(t) {
+        return t.k === "datatype" && Boolean(this.datatypes[t.name]?.operators.__unm);
+    }
+    /** Creation policy for `Instance.new("X")` / `X()`. */
+    creationError(cls) {
+        const c = this.classes[cls];
+        if (!c) {
+            return `'${cls}' is not a Roblox class`;
+        }
+        if (c.service) {
+            return `${cls} is a service; get it with game.GetService("${cls}") instead of creating it`;
+        }
+        if (!c.creatable) {
+            return `${cls} cannot be created with Instance.new (it is ${c.abstract ? "abstract" : "not creatable"})`;
+        }
+        return null;
+    }
+}
+exports.RobloxApi = RobloxApi;
+let shared = null;
+function surfacePath() {
+    return node_path_1.default.join(package_info_js_1.projectRoot, "api", "roblox", "surface.json");
+}
+function robloxApi() {
+    if (!shared) {
+        const file = surfacePath();
+        if (!node_fs_1.default.existsSync(file)) {
+            throw new Error(`cluaupp: missing Roblox surface ${file}. Run \`cluaupp api surface\` to rebuild it.`);
+        }
+        shared = new RobloxApi(JSON.parse(node_fs_1.default.readFileSync(file, "utf8")));
+    }
+    return shared;
+}
+/** Test hook. */
+function setRobloxApi(api) {
+    shared = api;
+}

package/generated/compiler/roblox/context.js

@@ -0,0 +1,100 @@
+"use strict";
+/**
+ * Server/client authority rules. Each rule names a service, a class member or a service member,
+ * and the only run context where it works. Members apply to subclasses (RemoteEvent rules also
+ * cover UnreliableRemoteEvent through the explicit entries).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RISKY_MEMBERS = exports.MEMBER_RULES = exports.SERVICE_RULES = void 0;
+exports.contextLabel = contextLabel;
+exports.runContextOf = runContextOf;
+/** `service:Name` → rule for touching the service at all. */
+exports.SERVICE_RULES = {
+    ServerStorage: { only: "server", why: "ServerStorage is never replicated to clients" },
+    ServerScriptService: { only: "server", why: "ServerScriptService is never replicated to clients" },
+    DataStoreService: { only: "server", why: "DataStores can only be accessed by the server" },
+    MessagingService: { only: "server", why: "MessagingService only works on the server" },
+    MemoryStoreService: { only: "server", why: "MemoryStoreService only works on the server" },
+    AnalyticsService: { only: "server", why: "AnalyticsService events are logged from the server" },
+    OpenCloudService: { only: "server", why: "OpenCloudService only works on the server" },
+    UserInputService: { only: "client", why: "UserInputService reads the local device; on the server it has no input" },
+    ContextActionService: { only: "client", why: "ContextActionService binds local input" },
+    HapticService: { only: "client", why: "HapticService drives local devices" },
+    VRService: { only: "client", why: "VRService reads the local headset" },
+    GuiService: { only: "client", why: "GuiService controls the local player's GUI", severity: "warning" },
+};
+/** `Class.Member` → rule (checked against the member's owner chain). */
+exports.MEMBER_RULES = {
+    "Players.LocalPlayer": { only: "client", why: "Players.LocalPlayer is nil on the server" },
+    "Player.GetMouse": { only: "client", why: "GetMouse only works for the local player" },
+    "RunService.RenderStepped": { only: "client", why: "RenderStepped only fires on clients" },
+    "RunService.BindToRenderStep": { only: "client", why: "BindToRenderStep only works on clients" },
+    "RunService.UnbindFromRenderStep": { only: "client", why: "UnbindFromRenderStep only works on clients" },
+    "StarterGui.SetCore": { only: "client", why: "SetCore only works from a LocalScript" },
+    "StarterGui.GetCore": { only: "client", why: "GetCore only works from a LocalScript" },
+    "StarterGui.SetCoreGuiEnabled": { only: "client", why: "SetCoreGuiEnabled only works from a LocalScript" },
+    "RemoteEvent.FireServer": { only: "client", why: "FireServer sends from a client to the server" },
+    "RemoteEvent.OnClientEvent": { only: "client", why: "OnClientEvent fires on clients" },
+    "RemoteEvent.FireClient": { only: "server", why: "FireClient sends from the server to one client" },
+    "RemoteEvent.FireAllClients": { only: "server", why: "FireAllClients sends from the server" },
+    "RemoteEvent.OnServerEvent": { only: "server", why: "OnServerEvent fires on the server" },
+    "UnreliableRemoteEvent.FireServer": { only: "client", why: "FireServer sends from a client to the server" },
+    "UnreliableRemoteEvent.OnClientEvent": { only: "client", why: "OnClientEvent fires on clients" },
+    "UnreliableRemoteEvent.FireClient": { only: "server", why: "FireClient sends from the server to one client" },
+    "UnreliableRemoteEvent.FireAllClients": { only: "server", why: "FireAllClients sends from the server" },
+    "UnreliableRemoteEvent.OnServerEvent": { only: "server", why: "OnServerEvent fires on the server" },
+    "RemoteFunction.InvokeServer": { only: "client", why: "InvokeServer calls the server from a client" },
+    "RemoteFunction.OnClientInvoke": { only: "client", why: "OnClientInvoke runs on clients" },
+    "RemoteFunction.InvokeClient": { only: "server", why: "InvokeClient calls a client from the server" },
+    "RemoteFunction.OnServerInvoke": { only: "server", why: "OnServerInvoke runs on the server" },
+    "DataModel.BindToClose": { only: "server", why: "BindToClose runs when the server shuts down" },
+    "Players.BanAsync": { only: "server", why: "bans are issued by the server" },
+    "Players.UnbanAsync": { only: "server", why: "bans are issued by the server" },
+    "Players.CreateHumanoidModelFromUserId": { only: "server", why: "only the server can build character models" },
+    "Players.CreateHumanoidModelFromDescription": { only: "server", why: "only the server can build character models" },
+    "Player.LoadCharacter": { only: "server", why: "characters are spawned by the server" },
+    "Player.LoadCharacterAsync": { only: "server", why: "characters are spawned by the server" },
+    "BasePart.SetNetworkOwner": { only: "server", why: "network ownership is assigned by the server" },
+    "BasePart.SetNetworkOwnershipAuto": { only: "server", why: "network ownership is assigned by the server" },
+    "MarketplaceService.ProcessReceipt": { only: "server", why: "developer product receipts are processed by the server" },
+    "BadgeService.AwardBadge": { only: "server", why: "badges are awarded by the server" },
+    "BadgeService.AwardBadgeAsync": { only: "server", why: "badges are awarded by the server" },
+    "TextService.FilterStringAsync": { only: "server", why: "text filtering runs on the server" },
+    "HttpService.GetAsync": { only: "server", why: "HTTP requests can only be made by the server" },
+    "HttpService.PostAsync": { only: "server", why: "HTTP requests can only be made by the server" },
+    "HttpService.RequestAsync": { only: "server", why: "HTTP requests can only be made by the server" },
+    "TeleportService.TeleportAsync": { only: "server", why: "TeleportAsync is server-only" },
+    "TeleportService.ReserveServer": { only: "server", why: "ReserveServer is server-only" },
+    "TeleportService.ReserveServerAsync": { only: "server", why: "ReserveServerAsync is server-only" },
+    "InsertService.LoadAsset": { only: "server", why: "LoadAsset is server-only" },
+    "PhysicsService.RegisterCollisionGroup": { only: "server", why: "collision groups are registered by the server" },
+};
+/** Members that work but are a known exploit or freeze vector. */
+exports.RISKY_MEMBERS = {
+    "RemoteFunction.InvokeClient": "the server yields until the client answers; a malicious client can hang it forever — prefer a RemoteEvent",
+};
+function contextLabel(ctx) {
+    switch (ctx) {
+        case "server":
+            return "a server Script";
+        case "client":
+            return "a LocalScript";
+        case "plugin":
+            return "a plugin";
+        default:
+            return "a shared module";
+    }
+}
+function runContextOf(fileName) {
+    const base = fileName.replace(/\\/g, "/").split("/").pop().toLowerCase();
+    if (/\.server\.clp$/.test(base)) {
+        return "server";
+    }
+    if (/\.client\.clp$/.test(base)) {
+        return "client";
+    }
+    if (/\.plugin\.clp$/.test(base)) {
+        return "plugin";
+    }
+    return "shared";
+}

package/generated/compiler/source.js

@@ -0,0 +1,59 @@
+"use strict";
+/** Source text with fast offset → line/column mapping. Columns are 1-based UTF-16 units. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SourceFile = void 0;
+exports.spanOf = spanOf;
+exports.joinSpans = joinSpans;
+class SourceFile {
+    path;
+    text;
+    lineStarts;
+    constructor(path, text) {
+        this.path = path;
+        this.text = text;
+        const starts = [0];
+        for (let i = 0; i < text.length; i++) {
+            const c = text.charCodeAt(i);
+            if (c === 10) {
+                starts.push(i + 1);
+            }
+            else if (c === 13) {
+                if (text.charCodeAt(i + 1) === 10) {
+                    i++;
+                }
+                starts.push(i + 1);
+            }
+        }
+        this.lineStarts = starts;
+    }
+    position(offset) {
+        const starts = this.lineStarts;
+        let lo = 0;
+        let hi = starts.length - 1;
+        while (lo < hi) {
+            const mid = (lo + hi + 1) >> 1;
+            if (starts[mid] <= offset) {
+                lo = mid;
+            }
+            else {
+                hi = mid - 1;
+            }
+        }
+        return { line: lo + 1, column: offset - starts[lo] + 1 };
+    }
+    lineText(line) {
+        const start = this.lineStarts[line - 1] ?? 0;
+        const next = this.lineStarts[line] ?? this.text.length;
+        return this.text.slice(start, next).replace(/\r?\n$|\r$/, "");
+    }
+    slice(span) {
+        return this.text.slice(span.start, span.end);
+    }
+}
+exports.SourceFile = SourceFile;
+function spanOf(start, end) {
+    return { start, end };
+}
+function joinSpans(a, b) {
+    return { start: Math.min(a.start, b.start), end: Math.max(a.end, b.end) };
+}