cluaupp 1.5.2 → 2.0.0-beta.1

package/generated/api/surface/luau-defs.js

@@ -0,0 +1,595 @@
+"use strict";
+/**
+ * Parser for Luau definition files (`*.d.luau`, the luau-lsp format):
+ * `declare extern type X [extends Y] with … end`, `declare name: Type`, `declare function f(…): R`,
+ * `type Alias = Type`, `export type Alias<T> = Type`, `@deprecated` / `@[deprecated {use = "…"}]`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseDefinitions = parseDefinitions;
+const OPS = ["...", "->", "::", "@[", "(", ")", "{", "}", "[", "]", "<", ">", ",", ":", ";", "?", "|", "&", "=", ".", "@"];
+function lex(text) {
+    const out = [];
+    let i = 0;
+    let line = 1;
+    while (i < text.length) {
+        const c = text[i];
+        if (c === "\n") {
+            line++;
+            i++;
+            continue;
+        }
+        if (c === " " || c === "\t" || c === "\r") {
+            i++;
+            continue;
+        }
+        if (c === "-" && text[i + 1] === "-") {
+            if (text.startsWith("--[[", i) || text.startsWith("--[=[", i)) {
+                const close = text.indexOf("]]", i);
+                const chunk = text.slice(i, close < 0 ? text.length : close + 2);
+                line += chunk.split("\n").length - 1;
+                i = close < 0 ? text.length : close + 2;
+                continue;
+            }
+            while (i < text.length && text[i] !== "\n") {
+                i++;
+            }
+            continue;
+        }
+        if (/[A-Za-z_]/.test(c)) {
+            let j = i + 1;
+            while (j < text.length && /[A-Za-z0-9_]/.test(text[j])) {
+                j++;
+            }
+            out.push({ t: "name", v: text.slice(i, j), line });
+            i = j;
+            continue;
+        }
+        if (/[0-9]/.test(c)) {
+            let j = i + 1;
+            while (j < text.length && /[0-9.]/.test(text[j])) {
+                j++;
+            }
+            out.push({ t: "number", v: text.slice(i, j), line });
+            i = j;
+            continue;
+        }
+        if (c === '"' || c === "'") {
+            let j = i + 1;
+            while (j < text.length && text[j] !== c) {
+                if (text[j] === "\\") {
+                    j++;
+                }
+                j++;
+            }
+            out.push({ t: "string", v: text.slice(i + 1, j), line });
+            i = j + 1;
+            continue;
+        }
+        const op = OPS.find((o) => text.startsWith(o, i));
+        if (op) {
+            out.push({ t: "op", v: op, line });
+            i += op.length;
+            continue;
+        }
+        i++;
+    }
+    out.push({ t: "eof", v: "", line });
+    return out;
+}
+class DefParser {
+    toks;
+    i = 0;
+    /** Defaults of the generic parameters read last (`<T = BasePart>`). */
+    lastDefaults = {};
+    constructor(toks) {
+        this.toks = toks;
+    }
+    peek(n = 0) {
+        return this.toks[Math.min(this.i + n, this.toks.length - 1)];
+    }
+    next() {
+        return this.toks[this.i++] ?? this.toks[this.toks.length - 1];
+    }
+    is(v, n = 0) {
+        const t = this.peek(n);
+        return (t.t === "op" || t.t === "name") && t.v === v;
+    }
+    eat(v) {
+        if (this.is(v)) {
+            this.i++;
+            return true;
+        }
+        return false;
+    }
+    expect(v) {
+        if (!this.eat(v)) {
+            const t = this.peek();
+            throw new Error(`definitions: expected '${v}' at line ${t.line}, found '${t.v}'`);
+        }
+    }
+    name() {
+        const t = this.next();
+        if (t.t !== "name") {
+            throw new Error(`definitions: expected name at line ${t.line}, found '${t.v}'`);
+        }
+        return t.v;
+    }
+    file() {
+        const out = { metadata: {}, externs: [], declares: [], aliases: {}, aliasParams: {} };
+        while (this.peek().t !== "eof") {
+            const deprecated = this.attributes();
+            if (this.is("declare")) {
+                this.next();
+                if (this.is("extern")) {
+                    this.next();
+                    this.expect("type");
+                    out.externs.push(this.externType());
+                    continue;
+                }
+                if (this.is("class")) {
+                    this.next();
+                    out.externs.push(this.externType(true));
+                    continue;
+                }
+                if (this.is("function")) {
+                    this.next();
+                    const name = this.name();
+                    const fn = this.funcSignature(false);
+                    out.declares.push({ name, type: fn, ...(deprecated ? { deprecated } : {}) });
+                    continue;
+                }
+                const name = this.name();
+                this.expect(":");
+                const type = this.type();
+                out.declares.push({ name, type, ...(deprecated ? { deprecated } : {}) });
+                continue;
+            }
+            if (this.is("export")) {
+                this.next();
+            }
+            if (this.is("type")) {
+                this.next();
+                const name = this.name();
+                this.lastDefaults = {};
+                const params = this.genericParamNames();
+                const defaults = this.lastDefaults;
+                this.expect("=");
+                out.aliases[name] = substituteNames(this.type(), defaults);
+                if (params.length) {
+                    out.aliasParams[name] = params;
+                }
+                continue;
+            }
+            this.next();
+        }
+        return out;
+    }
+    /** `@deprecated`, `@[deprecated {use = "X"}]`, `@checked` … — returns the deprecation, if any. */
+    attributes() {
+        let deprecated;
+        for (;;) {
+            if (this.is("@[")) {
+                this.next();
+                let depth = 1;
+                let sawDeprecated = false;
+                while (depth > 0 && this.peek().t !== "eof") {
+                    const t = this.next();
+                    if (t.t === "op" && (t.v === "[" || t.v === "@[")) {
+                        depth++;
+                    }
+                    else if (t.t === "op" && t.v === "]") {
+                        depth--;
+                    }
+                    else if (t.t === "name" && t.v === "deprecated") {
+                        sawDeprecated = true;
+                        deprecated = true;
+                    }
+                    else if (sawDeprecated && t.t === "string") {
+                        deprecated = t.v;
+                    }
+                }
+                continue;
+            }
+            if (this.is("@")) {
+                this.next();
+                const word = this.name();
+                if (word === "deprecated") {
+                    deprecated = true;
+                }
+                continue;
+            }
+            return deprecated;
+        }
+    }
+    genericParamNames() {
+        const names = [];
+        if (this.eat("<")) {
+            while (!this.is(">") && this.peek().t !== "eof") {
+                const t = this.next();
+                if (t.t === "name") {
+                    names.push(t.v);
+                }
+                if (this.eat("=")) {
+                    const def = this.type();
+                    if (t.t === "name") {
+                        this.lastDefaults[t.v] = def;
+                    }
+                }
+                this.eat("...");
+                this.eat(",");
+            }
+            this.expect(">");
+        }
+        return names;
+    }
+    externType(isClass = false) {
+        const line = this.peek().line;
+        const name = this.name();
+        let ext = null;
+        if (this.eat("extends")) {
+            ext = this.name();
+        }
+        if (!isClass) {
+            this.expect("with");
+        }
+        const members = [];
+        while (!this.is("end") && this.peek().t !== "eof") {
+            const deprecated = this.attributes();
+            if (this.is("function")) {
+                this.next();
+                const mname = this.name();
+                const fn = this.funcSignature(true);
+                members.push({ name: mname, fn, ...(deprecated ? { deprecated } : {}) });
+                continue;
+            }
+            if (this.is("[")) {
+                // indexer `[string]: any`
+                this.next();
+                this.type();
+                this.expect("]");
+                this.expect(":");
+                this.type();
+                continue;
+            }
+            if (this.peek().t === "name" && (this.is(":", 1))) {
+                const mname = this.name();
+                this.expect(":");
+                const type = this.type();
+                members.push({ name: mname, type, ...(deprecated ? { deprecated } : {}) });
+                continue;
+            }
+            if (this.is("read") || this.is("write")) {
+                this.next();
+                continue;
+            }
+            this.next();
+        }
+        this.expect("end");
+        return { name, extends: ext, members, line };
+    }
+    /** `(self, a: T, b: U?, ...: V): R` after the function name. */
+    funcSignature(method) {
+        const generics = this.genericParamNames();
+        this.expect("(");
+        const params = [];
+        let variadic;
+        let first = true;
+        while (!this.is(")") && this.peek().t !== "eof") {
+            if (this.eat("...")) {
+                variadic = this.eat(":") ? this.type() : { k: "name", name: "any" };
+                this.eat(",");
+                continue;
+            }
+            const pname = this.name();
+            if (first && method && pname === "self") {
+                if (this.eat(":")) {
+                    this.type();
+                }
+                first = false;
+                this.eat(",");
+                continue;
+            }
+            first = false;
+            let t = { k: "name", name: "any" };
+            if (this.eat(":")) {
+                t = this.type();
+            }
+            params.push({ name: pname, t });
+            this.eat(",");
+        }
+        this.expect(")");
+        const fn = { k: "fn", params, returns: [] };
+        if (variadic) {
+            fn.variadic = variadic;
+        }
+        if (generics.length) {
+            fn.generics = generics;
+        }
+        if (this.eat(":")) {
+            this.returnTypes(fn);
+        }
+        return fn;
+    }
+    returnTypes(fn) {
+        if (this.is("(")) {
+            // tuple `(A, B)` or a parenthesized function type `((a) -> b)`
+            const mark = this.i;
+            this.next();
+            if (this.eat(")")) {
+                if (this.is("->")) {
+                    this.i = mark;
+                    fn.returns = [this.type()];
+                }
+                return;
+            }
+            const list = [];
+            let tail;
+            while (!this.is(")") && this.peek().t !== "eof") {
+                if (this.eat("...")) {
+                    tail = this.type();
+                }
+                else {
+                    list.push(this.type());
+                }
+                this.eat(",");
+            }
+            this.expect(")");
+            if (this.is("->") || this.is("|") || this.is("?") || this.is("&")) {
+                this.i = mark;
+                fn.returns = [this.type()];
+                return;
+            }
+            fn.returns = list;
+            if (tail) {
+                fn.returnsVariadic = tail;
+            }
+            return;
+        }
+        if (this.eat("...")) {
+            fn.returnsVariadic = this.type();
+            return;
+        }
+        const t = this.type();
+        if (t.k === "name" && (t.name === "nil" || t.name === "()")) {
+            return;
+        }
+        fn.returns = [t];
+    }
+    type() {
+        this.eat("|");
+        const first = this.intersection();
+        if (!this.is("|")) {
+            return first;
+        }
+        const ts = [first];
+        while (this.eat("|")) {
+            ts.push(this.intersection());
+        }
+        return { k: "union", ts };
+    }
+    intersection() {
+        const first = this.postfix();
+        if (!this.is("&")) {
+            return first;
+        }
+        const ts = [first];
+        while (this.eat("&")) {
+            ts.push(this.postfix());
+        }
+        return { k: "inter", ts };
+    }
+    postfix() {
+        let t = this.primary();
+        while (this.eat("?")) {
+            t = { k: "opt", t };
+        }
+        return t;
+    }
+    primary() {
+        const tok = this.peek();
+        if (tok.t === "string") {
+            this.next();
+            return { k: "lit", value: tok.v };
+        }
+        if (this.is("typeof")) {
+            this.next();
+            this.expect("(");
+            let depth = 1;
+            while (depth > 0 && this.peek().t !== "eof") {
+                const t = this.next();
+                if (t.v === "(") {
+                    depth++;
+                }
+                else if (t.v === ")") {
+                    depth--;
+                }
+            }
+            return { k: "name", name: "any" };
+        }
+        if (this.is("{")) {
+            return this.table();
+        }
+        if (this.is("<")) {
+            // generic function type `<T>(a: T) -> T`
+            const generics = this.genericParamNames();
+            const fn = this.parenType();
+            if (fn.k === "fn" && generics.length) {
+                fn.generics = generics;
+            }
+            return fn;
+        }
+        if (this.is("(")) {
+            return this.parenType();
+        }
+        if (this.is("...")) {
+            this.next();
+            const inner = this.type();
+            return inner.k === "name" ? { k: "pack", name: inner.name } : inner;
+        }
+        if (tok.t === "name") {
+            this.next();
+            let name = tok.v;
+            while (this.is(".") && this.peek(1).t === "name") {
+                this.next();
+                name += `.${this.next().v}`;
+            }
+            if (name === "true" || name === "false") {
+                return { k: "lit", value: name === "true" };
+            }
+            if (this.eat("...")) {
+                return { k: "pack", name };
+            }
+            if (this.is("<")) {
+                this.next();
+                const args = [];
+                while (!this.is(">") && this.peek().t !== "eof") {
+                    if (this.is("(") && this.is(")", 1)) {
+                        this.next();
+                        this.next();
+                        args.push({ k: "name", name: "()" });
+                    }
+                    else {
+                        const arg = this.type();
+                        if (arg.k === "name" && arg.name === "__pack") {
+                            args.push(...(arg.args || []));
+                        }
+                        else {
+                            args.push(arg);
+                        }
+                    }
+                    this.eat(",");
+                }
+                this.expect(">");
+                return { k: "name", name, args };
+            }
+            return { k: "name", name };
+        }
+        throw new Error(`definitions: unexpected '${tok.v}' at line ${tok.line}`);
+    }
+    /** `( … )` — a function type when followed by `->`, else grouping. */
+    parenType() {
+        this.expect("(");
+        const params = [];
+        let variadic;
+        while (!this.is(")") && this.peek().t !== "eof") {
+            if (this.eat("...")) {
+                variadic = this.is(",") || this.is(")") ? { k: "name", name: "any" } : this.type();
+                this.eat(",");
+                continue;
+            }
+            let pname;
+            if (this.peek().t === "name" && this.is(":", 1)) {
+                pname = this.next().v;
+                this.next();
+            }
+            const t = this.type();
+            if (t.k === "pack") {
+                variadic = { k: "name", name: "any" };
+                this.eat(",");
+                continue;
+            }
+            params.push(pname ? { name: pname, t } : { t });
+            this.eat(",");
+        }
+        this.expect(")");
+        if (this.eat("->")) {
+            const fn = { k: "fn", params, returns: [] };
+            if (variadic) {
+                fn.variadic = variadic;
+            }
+            this.returnTypes(fn);
+            return fn;
+        }
+        if (params.length === 1 && !variadic) {
+            return params[0].t;
+        }
+        if (params.length === 0) {
+            return { k: "name", name: "()" };
+        }
+        // a type pack `(A, B)`, as in RBXScriptSignal<(InputObject, boolean)>
+        return { k: "name", name: "__pack", args: params.map((p) => p.t) };
+    }
+    table() {
+        this.expect("{");
+        if (this.eat("}")) {
+            return { k: "table", fields: {} };
+        }
+        // `{ T }` array
+        const mark = this.i;
+        const isField = (this.peek().t === "name" && this.is(":", 1)) || this.is("[") || ((this.is("read") || this.is("write")) && this.peek(1).t === "name");
+        if (!isField) {
+            const elem = this.type();
+            if (this.eat("}")) {
+                return { k: "array", t: elem };
+            }
+            this.i = mark;
+        }
+        const fields = {};
+        let indexer;
+        while (!this.is("}") && this.peek().t !== "eof") {
+            if ((this.is("read") || this.is("write")) && this.peek(1).t === "name" && this.is(":", 2)) {
+                this.next();
+            }
+            if (this.eat("[")) {
+                const key = this.type();
+                this.expect("]");
+                this.expect(":");
+                indexer = [key, this.type()];
+            }
+            else {
+                const fname = this.name();
+                this.expect(":");
+                fields[fname] = this.type();
+            }
+            if (!this.eat(",")) {
+                this.eat(";");
+            }
+        }
+        this.expect("}");
+        if (indexer && Object.keys(fields).length === 0) {
+            return { k: "map", key: indexer[0], value: indexer[1] };
+        }
+        return { k: "table", fields };
+    }
+}
+/** Replace generic parameter names by their defaults (`RaycastResult<T = BasePart>` → BasePart). */
+function substituteNames(t, map) {
+    if (Object.keys(map).length === 0) {
+        return t;
+    }
+    const sub = (x) => substituteNames(x, map);
+    switch (t.k) {
+        case "name":
+            return map[t.name] && !t.args ? map[t.name] : t.args ? { ...t, args: t.args.map(sub) } : t;
+        case "opt":
+            return { k: "opt", t: sub(t.t) };
+        case "union":
+        case "inter":
+            return { k: t.k, ts: t.ts.map(sub) };
+        case "array":
+            return { k: "array", t: sub(t.t) };
+        case "map":
+            return { k: "map", key: sub(t.key), value: sub(t.value) };
+        case "table":
+            return { k: "table", fields: Object.fromEntries(Object.entries(t.fields).map(([k, v]) => [k, sub(v)])) };
+        case "fn":
+            return { ...t, params: t.params.map((p) => ({ ...p, t: sub(p.t) })), returns: t.returns.map(sub) };
+        default:
+            return t;
+    }
+}
+function parseDefinitions(text) {
+    let metadata = {};
+    const first = text.split("\n", 1)[0];
+    if (first.startsWith("--#METADATA#")) {
+        try {
+            metadata = JSON.parse(first.slice("--#METADATA#".length));
+        }
+        catch {
+            metadata = {};
+        }
+    }
+    const file = new DefParser(lex(text)).file();
+    file.metadata = metadata;
+    return file;
+}

package/generated/api/surface/model.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Roblox surface: the typed Roblox API the CL++ checker validates against.
+ * Built from luau-lsp's Roblox definitions (types, nullability, overloads, operators) merged with
+ * the Roblox API dump profile (security, read-only, creatable, services, int vs float).
+ * Stored as `api/roblox/surface.json` and loaded once per process.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/generated/clpp/contract.js

@@ -1,6 +1,9 @@
 "use strict";
-/** Stable CL++ ↔ Cluaupp contract (CL++ 0.8.x). Cluaupp invokes the `clpp` binary. */
+/** Legacy adapter policy for CL++ 0.8.x. Requires an upstream compiler implementing the handshake. */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CLPP_INSTALL_HINT = exports.MIN_CLPP_VERSION = void 0;
+exports.CLPP_INSTALL_HINT = exports.CLPP_CONTRACT_VERSION = exports.CLPP_VERSION_RANGE = exports.MAX_CLPP_VERSION_EXCLUSIVE = exports.MIN_CLPP_VERSION = void 0;
 exports.MIN_CLPP_VERSION = "0.8.0";
-exports.CLPP_INSTALL_HINT = "Install CL++ 0.8.0+ (`clpp` from https://github.com/KartzRbx/CLPP/releases). Put it on PATH. Prefer `import { Name } from \"./x.clh\"` for language modules; angle `#include <clpp/…>` stays for host prelude. Override with CLPP or CLPP_PATH.";
+exports.MAX_CLPP_VERSION_EXCLUSIVE = "0.9.0";
+exports.CLPP_VERSION_RANGE = ">=0.8.0 <0.9.0";
+exports.CLPP_CONTRACT_VERSION = 1;
+exports.CLPP_INSTALL_HINT = "Install the legacy Luau compiler >=0.8.0 <0.9.0 with contractVersion 1 (the CL++ VM is incompatible) (`clpp` from https://github.com/KartzRbx/CLPP/releases). Put it on PATH. Prefer `import { Name } from \"./x.clh\"` for language modules; angle `#include <clpp/…>` stays for host prelude. Override with CLPP or CLPP_PATH.";

package/generated/clpp/handshake.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCompilerVersion = parseCompilerVersion;
+exports.acceptsCompilerVersion = acceptsCompilerVersion;
+exports.validateCompilerHandshake = validateCompilerHandshake;
+const contract_js_1 = require("./contract.js");
+function parseCompilerVersion(text) {
+    const m = /^(?:clpp\s+|CL\+\+\s+)?(\d+)\.(\d+)\.(\d+)(?:-[\w.-]+)?(?:\+[\w.-]+)?$/i.exec(text.trim());
+    return m ? m.slice(1, 4).map(Number) : null;
+}
+function compare(a, b) {
+    return a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+}
+function acceptsCompilerVersion(text) {
+    const v = parseCompilerVersion(text);
+    return !!v && compare(v, parseCompilerVersion(contract_js_1.MIN_CLPP_VERSION)) >= 0 && compare(v, parseCompilerVersion(contract_js_1.MAX_CLPP_VERSION_EXCLUSIVE)) < 0;
+}
+function validateCompilerHandshake(version, value) {
+    const fail = (reason) => { throw new Error(`cluaupp: incompatible clpp (${version || "unknown"}): ${reason}. Require Luau compiler ${contract_js_1.CLPP_VERSION_RANGE}, contractVersion ${contract_js_1.CLPP_CONTRACT_VERSION}. The clpp game VM cannot emit Roblox Luau. Set CLPP or CLPP_PATH to the Luau compiler.`); };
+    if (!acceptsCompilerVersion(version))
+        fail("unsupported version");
+    if (!value || typeof value !== "object")
+        fail("missing api manifest");
+    const m = value;
+    if (m.id !== "clpp" || m.name !== "CL++")
+        fail("wrong compiler identity");
+    if (m.contractVersion !== contract_js_1.CLPP_CONTRACT_VERSION)
+        fail("missing or unsupported contractVersion");
+    if (!acceptsCompilerVersion(m.version) || compare(parseCompilerVersion(version), parseCompilerVersion(m.version)) !== 0)
+        fail("binary and manifest versions disagree");
+    if (!Array.isArray(m.extensions) || ![".clpp", ".clp", ".clh"].every(x => m.extensions.includes(x)))
+        fail("missing source extensions");
+    if (!Array.isArray(m.tags) || ![["*.server.clpp", "server", "Script"], ["*.client.clpp", "client", "LocalScript"], ["*.clh", "header", "ModuleScript"]].every(([pattern, kind, cls]) => m.tags.some(t => t.pattern === pattern && t.scriptKind === kind && t.rojoClass === cls)))
+        fail("missing Roblox file tags");
+    return m;
+}

package/generated/clpp/modules.js

@@ -135,19 +135,30 @@ function resolveLanguageDeps(source, fromFile, srcDir) {
     return out;
 }
 /**
- * Fingerprint source + one-hop language deps so import/include edits invalidate incremental cache.
+ * Fingerprint source + transitive language deps so import/include edits invalidate incremental cache.
  */
 function fingerprintSourceWithDeps(source, fromFile, configKey, srcDir, hashText) {
     const parts = [configKey, source];
-    for (const dep of resolveLanguageDeps(source, fromFile, srcDir)) {
-        try {
-            parts.push(`\n//dep:${dep.replace(/\\/g, "/")}\n`);
-            parts.push(node_fs_1.default.readFileSync(dep, "utf8"));
-        }
-        catch {
-            parts.push(`\n//dep-missing:${dep.replace(/\\/g, "/")}\n`);
+    const seen = new Set([node_path_1.default.resolve(fromFile)]);
+    const visit = (text, file) => {
+        for (const ref of collectModuleRefs(text)) {
+            if (ref.angled)
+                continue;
+            const dep = resolveModuleFile(ref.modulePath, file, srcDir);
+            if (!dep) {
+                parts.push("\n//missing:" + file + ":" + ref.modulePath);
+                continue;
+            }
+            const key = node_path_1.default.resolve(dep);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const contents = node_fs_1.default.readFileSync(key, "utf8");
+            parts.push("\n//dep:" + key.replace(/\\/g, "/") + "\n", contents);
+            visit(contents, key);
         }
-    }
+    };
+    visit(source, fromFile);
     return hashText(parts.join(""));
 }
 /** Rewrite CL++ `script.Parent…Service…` walks to game-rooted requires. */