cluaupp 1.5.2 → 2.0.0-beta.2

package/generated/api/loader.js

@@ -22,7 +22,7 @@ function loadJsonFile(id, filePath) {
         meta: {
             id,
             path: absolute,
-            hash: (0, resolver_js_1.hashBuffer)(raw),
+            hash: (0, resolver_js_1.hashBuffer)(text.replace(/\r\n/g, "\n")),
             loadedAt: new Date().toISOString(),
             version: typeof data.Version !== "undefined"
                 ? data.Version
@@ -51,7 +51,7 @@ function overridesHash() {
         if (!name.endsWith(".json")) {
             continue;
         }
-        parts.push(name, node_fs_1.default.readFileSync(node_path_1.default.join(dir, name), "utf8"));
+        parts.push(name, node_fs_1.default.readFileSync(node_path_1.default.join(dir, name), "utf8").replace(/\r\n/g, "\n"));
     }
     return (0, resolver_js_1.hashBuffer)(parts.join("\n"));
 }

package/generated/api/surface/build.js

@@ -0,0 +1,328 @@
+"use strict";
+/**
+ * Builds `api/roblox/surface.json` from:
+ *  1. luau-lsp Roblox definitions (`globalTypes.*.d.luau`) — types, nullability, overloads, operators;
+ *  2. `api/roblox/luau-builtins.d.luau` — math, string, table, coroutine, bit32, buffer, os, vector, globals;
+ *  3. the Roblox API dump profile (`api/normalized/roblox-target.profile.json`) — security, read-only,
+ *     creatable/service, deprecation tags and integer-typed members.
+ *
+ * Run with `cluaupp api surface --defs <globalTypes.d.luau>`.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSurface = buildSurface;
+exports.writeSurface = writeSurface;
+exports.findLuauLspDefinitions = findLuauLspDefinitions;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const luau_defs_js_1 = require("./luau-defs.js");
+const package_info_js_1 = require("../../package-info.js");
+const INT_PRIMITIVES = new Set(["int", "int64", "int32", "int16", "int8"]);
+function hasTag(m, tag) {
+    return (m.tags || []).some((t) => t === tag);
+}
+function isSignal(t) {
+    return !!t && t.k === "name" && t.name === "RBXScriptSignal";
+}
+function intify(t) {
+    // keep the union wide: callers store the result back into an LType slot
+    if (t.k === "name" && t.name === "number") {
+        return { k: "name", name: "int" };
+    }
+    if (t.k === "opt") {
+        return { k: "opt", t: intify(t.t) };
+    }
+    return t;
+}
+function security(level) {
+    return level && level !== "None" ? level : undefined;
+}
+function convertMembers(ext, profileClass) {
+    const members = {};
+    const pProps = new Map((profileClass?.properties || []).map((p) => [p.name, p]));
+    const pMethods = new Map();
+    for (const m of profileClass?.methods || []) {
+        const list = pMethods.get(m.name) || [];
+        list.push(m);
+        pMethods.set(m.name, list);
+    }
+    const pEvents = new Map((profileClass?.events || []).map((p) => [p.name, p]));
+    const pCallbacks = new Map((profileClass?.callbacks || []).map((p) => [p.name, p]));
+    for (const m of ext.members) {
+        if (m.fn) {
+            if (m.name.startsWith("__")) {
+                continue;
+            }
+            const existing = members[m.name];
+            if (existing && existing.kind === "method") {
+                existing.overloads.push(m.fn);
+                continue;
+            }
+            const pm = pMethods.get(m.name)?.[0];
+            const member = { kind: "method", overloads: [m.fn] };
+            if (pm) {
+                const ret = pm.returnTypes?.[0];
+                if (ret && ret.kind === "Primitive" && INT_PRIMITIVES.has(ret.name || "") && m.fn.returns.length === 1) {
+                    m.fn.returns[0] = intify(m.fn.returns[0]);
+                }
+                const sec = security(pm.security);
+                if (sec) {
+                    member.security = sec;
+                }
+                if (pm.canYield || hasTag(pm, "Yields") || hasTag(pm, "CanYield")) {
+                    member.yields = true;
+                }
+                if (hasTag(pm, "NotScriptable")) {
+                    member.notScriptable = true;
+                }
+            }
+            else if (/Async$/.test(m.name)) {
+                member.yields = true;
+            }
+            if (m.deprecated) {
+                member.deprecated = m.deprecated;
+            }
+            members[m.name] = member;
+            continue;
+        }
+        const type = m.type;
+        if (isSignal(type)) {
+            const args = (type.args || []).filter((a) => !(a.k === "name" && a.name === "()"));
+            const member = { kind: "event", args };
+            const pe = pEvents.get(m.name);
+            const sec = security(pe?.security);
+            if (sec) {
+                member.security = sec;
+            }
+            if (m.deprecated) {
+                member.deprecated = m.deprecated;
+            }
+            members[m.name] = member;
+            continue;
+        }
+        const pc = pCallbacks.get(m.name);
+        if (pc || (type.k === "fn" && !pProps.has(m.name))) {
+            const member = { kind: "callback", type };
+            const sec = security(pc?.security);
+            if (sec) {
+                member.security = sec;
+            }
+            members[m.name] = member;
+            continue;
+        }
+        const pp = pProps.get(m.name);
+        let propType = type;
+        if (pp?.valueType?.kind === "Primitive" && INT_PRIMITIVES.has(pp.valueType.name || "")) {
+            propType = intify(propType);
+        }
+        const member = { kind: "property", type: propType };
+        if (pp) {
+            if (pp.writable === false || hasTag(pp, "ReadOnly")) {
+                member.readonly = true;
+            }
+            const rs = security(pp.readSecurity);
+            const ws = security(pp.writeSecurity);
+            if (rs) {
+                member.security = rs;
+            }
+            if (ws) {
+                member.writeSecurity = ws;
+            }
+            if (hasTag(pp, "NotScriptable")) {
+                member.notScriptable = true;
+            }
+            if (hasTag(pp, "NotReplicated")) {
+                member.notReplicated = true;
+            }
+        }
+        if (m.deprecated) {
+            member.deprecated = m.deprecated;
+        }
+        members[m.name] = member;
+    }
+    return members;
+}
+function staticsFrom(type) {
+    const out = {};
+    const tables = type.k === "inter" ? type.ts : [type];
+    for (const t of tables) {
+        if (t.k !== "table") {
+            continue;
+        }
+        for (const [name, value] of Object.entries(t.fields)) {
+            if (value.k === "fn") {
+                out[name] = { kind: "function", overloads: [value] };
+            }
+            else if (value.k === "inter" && value.ts.every((x) => x.k === "fn")) {
+                out[name] = { kind: "function", overloads: value.ts };
+            }
+            else {
+                out[name] = { kind: "value", type: value };
+            }
+        }
+    }
+    return out;
+}
+function datatypeFrom(ext, statics) {
+    const operators = {};
+    for (const m of ext.members) {
+        if (m.fn && m.name.startsWith("__")) {
+            (operators[m.name] ||= []).push(m.fn);
+        }
+    }
+    return {
+        name: ext.name,
+        members: convertMembers(ext, undefined),
+        operators,
+        statics: statics ? staticsFrom(statics) : {},
+    };
+}
+function buildSurface(options) {
+    const defsText = node_fs_1.default.readFileSync(options.definitions, "utf8");
+    const builtinsPath = options.builtins || node_path_1.default.join(package_info_js_1.projectRoot, "api", "roblox", "luau-builtins.d.luau");
+    const profilePath = options.profile || node_path_1.default.join(package_info_js_1.projectRoot, "api", "normalized", "roblox-target.profile.json");
+    const roblox = (0, luau_defs_js_1.parseDefinitions)(defsText);
+    const builtins = (0, luau_defs_js_1.parseDefinitions)(node_fs_1.default.readFileSync(builtinsPath, "utf8"));
+    const profile = node_fs_1.default.existsSync(profilePath) ? JSON.parse(node_fs_1.default.readFileSync(profilePath, "utf8")) : { classes: {}, enums: {} };
+    return assemble(roblox, builtins, profile, {
+        definitions: node_path_1.default.basename(options.definitions),
+        builtins: node_path_1.default.basename(builtinsPath),
+        profile: node_fs_1.default.existsSync(profilePath) ? node_path_1.default.basename(profilePath) : "none",
+    });
+}
+function assemble(roblox, builtins, profile, sources) {
+    const surface = {
+        schema: 1,
+        generatedAt: new Date().toISOString().slice(0, 10),
+        sources,
+        classes: {},
+        datatypes: {},
+        enums: {},
+        globals: {},
+        libraries: {},
+        aliases: {},
+    };
+    const declared = new Map();
+    for (const d of [...roblox.declares, ...builtins.declares]) {
+        declared.set(d.name, d);
+    }
+    const externByName = new Map();
+    for (const ext of roblox.externs) {
+        externByName.set(ext.name, ext);
+    }
+    const isClass = (name) => {
+        let cur = name;
+        let guard = 0;
+        while (cur && guard++ < 64) {
+            if (cur === "Object" || cur === "Instance") {
+                return true;
+            }
+            cur = externByName.get(cur)?.extends ?? null;
+        }
+        return false;
+    };
+    const services = new Set(roblox.metadata.SERVICES || []);
+    const creatable = new Set(roblox.metadata.CREATABLE_INSTANCES || []);
+    for (const ext of roblox.externs) {
+        if (ext.name.startsWith("Enum") && ext.name.endsWith("_INTERNAL") && ext.extends === "Enum") {
+            const enumName = ext.name.slice(4, -"_INTERNAL".length);
+            const items = [];
+            const deprecated = [];
+            for (const m of ext.members) {
+                if (m.type) {
+                    items.push(m.name);
+                    if (m.deprecated) {
+                        deprecated.push(m.name);
+                    }
+                }
+            }
+            surface.enums[enumName] = { name: enumName, items, ...(deprecated.length ? { deprecated } : {}) };
+            continue;
+        }
+        if (ext.extends === "EnumItem" || ext.name === "Enum" || ext.name === "EnumItem") {
+            continue;
+        }
+        if (ext.name === "Object" || isClass(ext.extends) || ext.name === "Instance") {
+            const pc = profile.classes[ext.name];
+            const cls = {
+                name: ext.name,
+                superclass: ext.extends,
+                members: convertMembers(ext, pc),
+                creatable: creatable.has(ext.name),
+                service: services.has(ext.name),
+            };
+            if (pc?.creation?.abstract) {
+                cls.abstract = true;
+            }
+            if (pc && hasTag(pc, "Deprecated")) {
+                cls.deprecated = true;
+            }
+            if (pc && hasTag(pc, "NotCreatable")) {
+                cls.notCreatable = true;
+            }
+            surface.classes[ext.name] = cls;
+            continue;
+        }
+        surface.datatypes[ext.name] = datatypeFrom(ext, declared.get(ext.name)?.type);
+    }
+    // Datatype-like statics without an extern body (e.g. `declare Instance: {…}` is handled by the checker).
+    for (const [name, d] of declared) {
+        if (surface.datatypes[name]) {
+            continue;
+        }
+        if (["Instance", "Enum", "game", "workspace", "script", "plugin", "shared", "task", "debug", "utf8"].includes(name)) {
+            continue;
+        }
+        if (/^[A-Z]/.test(name) && d.type.k === "table" && !surface.classes[name]) {
+            surface.datatypes[name] = { name, members: {}, operators: {}, statics: staticsFrom(d.type) };
+        }
+    }
+    for (const [name, d] of declared) {
+        if (d.type.k === "table" && /^[a-z]/.test(name)) {
+            surface.libraries[name] = staticsFrom(d.type);
+            continue;
+        }
+        if (d.type.k === "fn") {
+            surface.globals[name] = { overloads: [d.type], ...(d.deprecated ? { deprecated: d.deprecated } : {}) };
+            continue;
+        }
+        if (["game", "workspace", "script", "plugin", "shared", "Enum"].includes(name)) {
+            surface.globals[name] = { type: d.type };
+        }
+    }
+    surface.globals.Instance = { type: declared.get("Instance").type };
+    for (const [name, t] of Object.entries(roblox.aliases)) {
+        if (name === "ENUM_LIST" || name.startsWith("Enum")) {
+            continue;
+        }
+        surface.aliases[name] = t;
+    }
+    return surface;
+}
+function writeSurface(surface, dest = node_path_1.default.join(package_info_js_1.projectRoot, "api", "roblox", "surface.json")) {
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(dest), { recursive: true });
+    node_fs_1.default.writeFileSync(dest, `${JSON.stringify(surface)}\n`, "utf8");
+    return dest;
+}
+/** Default location of the luau-lsp definitions downloaded by the VS Code extension. */
+function findLuauLspDefinitions() {
+    const roots = [
+        process.env.APPDATA && node_path_1.default.join(process.env.APPDATA, "Code", "User", "globalStorage", "johnnymorganz.luau-lsp"),
+        process.env.APPDATA && node_path_1.default.join(process.env.APPDATA, "Cursor", "User", "globalStorage", "johnnymorganz.luau-lsp"),
+        process.env.HOME && node_path_1.default.join(process.env.HOME, ".config", "Code", "User", "globalStorage", "johnnymorganz.luau-lsp"),
+        process.env.HOME && node_path_1.default.join(process.env.HOME, "Library", "Application Support", "Code", "User", "globalStorage", "johnnymorganz.luau-lsp"),
+    ].filter(Boolean);
+    for (const root of roots) {
+        if (!node_fs_1.default.existsSync(root)) {
+            continue;
+        }
+        const files = node_fs_1.default.readdirSync(root).filter((f) => /^globalTypes.*\.d\.luau$/.test(f));
+        const preferred = files.find((f) => /PluginSecurity/.test(f)) || files[0];
+        if (preferred) {
+            return node_path_1.default.join(root, preferred);
+        }
+    }
+    return null;
+}