iris-decompiler 1.0.0

package/dist/disasm.d.ts

@@ -0,0 +1,3 @@
+import { Program } from "./types";
+export declare function disassemble(program: Program): string;
+export declare function disassembleProto(program: Program, index: number): string;

package/dist/disasm.js

@@ -0,0 +1,321 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.disassemble = disassemble;
+exports.disassembleProto = disassembleProto;
+const types_1 = require("./types");
+function fmtNumber(v) {
+    if (Number.isNaN(v))
+        return "(0/0)";
+    if (!Number.isFinite(v))
+        return v < 0 ? "-(1/0)" : "(1/0)";
+    if (Math.floor(v) === v && Math.abs(v) < 1e15) {
+        return String(Math.trunc(v));
+    }
+    let s = v.toPrecision(10);
+    if (s.indexOf(".") !== -1) {
+        while (s.length > 0 && s[s.length - 1] === "0")
+            s = s.slice(0, -1);
+        if (s[s.length - 1] === ".")
+            s = s.slice(0, -1);
+    }
+    return s === "" ? "0" : s;
+}
+function escapeString(s) {
+    let out = '"';
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        switch (c) {
+            case 0x22:
+                out += '\\"';
+                break;
+            case 0x5c:
+                out += "\\\\";
+                break;
+            case 0x0a:
+                out += "\\n";
+                break;
+            case 0x0d:
+                out += "\\r";
+                break;
+            case 0x09:
+                out += "\\t";
+                break;
+            default:
+                if (c < 32) {
+                    out += "\\" + c;
+                }
+                else {
+                    out += s[i];
+                }
+        }
+    }
+    out += '"';
+    return out;
+}
+function importPath(p, id) {
+    const count = id >>> 30;
+    const c0 = (id >>> 20) & 1023;
+    const c1 = (id >>> 10) & 1023;
+    const c2 = id & 1023;
+    const name = (idx) => {
+        if (idx < 0 || idx >= p.k.length || p.k[idx].kind !== types_1.ConstKind.String)
+            return "?";
+        return p.k[idx].str;
+    };
+    let path = name(c0);
+    if (count >= 2)
+        path += "." + name(c1);
+    if (count >= 3)
+        path += "." + name(c2);
+    return path;
+}
+function renderConst(os, p, c) {
+    switch (c.kind) {
+        case types_1.ConstKind.Nil:
+            os.push("nil");
+            break;
+        case types_1.ConstKind.Boolean:
+            os.push(c.boolean ? "true" : "false");
+            break;
+        case types_1.ConstKind.Number:
+            os.push(fmtNumber(c.number));
+            break;
+        case types_1.ConstKind.Integer:
+            os.push(String(c.integer));
+            break;
+        case types_1.ConstKind.String:
+            os.push(escapeString(c.str));
+            break;
+        case types_1.ConstKind.Import:
+            os.push("@import:" + p.debugname + ":" + importPath(p, c.importId));
+            break;
+        case types_1.ConstKind.Table:
+        case types_1.ConstKind.TableWithConstants: {
+            os.push("{ ");
+            for (let i = 0; i < c.table.length; i++) {
+                if (i)
+                    os.push(", ");
+                const e = c.table[i];
+                if (e.key >= 0 && e.key < p.k.length)
+                    renderConst(os, p, p.k[e.key]);
+                else
+                    os.push("?key");
+                os.push(" = ");
+                if (e.value >= 0) {
+                    if (e.value < p.k.length)
+                        renderConst(os, p, p.k[e.value]);
+                    else
+                        os.push("?");
+                }
+                else
+                    os.push("0");
+            }
+            os.push(" }");
+            break;
+        }
+        case types_1.ConstKind.Closure:
+            os.push("@closure[" + c.closureProto + "]");
+            break;
+        case types_1.ConstKind.Vector:
+        case types_1.ConstKind.VectorD:
+            os.push("vector(" + c.vec[0] + ", " + c.vec[1] + ", " + c.vec[2] + ")");
+            break;
+        default:
+            os.push("?");
+            break;
+    }
+}
+function constText(program, p, k) {
+    if (k < 0 || k >= p.k.length)
+        return "?";
+    const os = [];
+    renderConst(os, p, p.k[k]);
+    return os.join("");
+}
+function dumpProto(out, program, pi) {
+    const p = program.protos[pi];
+    out.push("== proto " + pi + ' "' + p.debugname + '" line ' + p.linedefined + "\n");
+    out.push("-- maxstack=" + p.maxstack + " params=" + p.numparams + " nups=" + p.nups +
+        " vararg=" + p.is_vararg + " flags=" + p.flags + "\n");
+    out.push("-- upvalue names: ");
+    for (let u = 0; u < p.upnames.length; u++) {
+        if (u)
+            out.push(", ");
+        out.push('"' + p.upnames[u] + '"');
+    }
+    out.push("\n");
+    out.push("-- constants:\n");
+    for (let k = 0; k < p.k.length; k++) {
+        const os = [];
+        renderConst(os, p, p.k[k]);
+        out.push("  [" + k + "] " + os.join("") + "\n");
+    }
+    out.push("\n");
+    out.push("  idx     line  insn\n");
+    let i = 0;
+    while (i < p.code.length) {
+        const insn = p.code[i];
+        const op = (0, types_1.iOp)(insn);
+        const line = [];
+        line.push("  " + (insn >>> 0).toString(16) + "   ");
+        line.push(i + "      ");
+        line.push((p.lineinfo.length === 0 || p.lineinfo[i] < 0) ? "-" : String(p.lineinfo[i]));
+        line.push("     " + (0, types_1.opName)(op));
+        const pushAB = () => line.push(" A=" + (0, types_1.iA)(insn));
+        const pushABC = () => line.push(" B=" + (0, types_1.iB)(insn) + " C=" + (0, types_1.iC)(insn));
+        switch (op) {
+            case types_1.Op.NOP:
+            case types_1.Op.BREAK:
+            case types_1.Op.NATIVECALL:
+            case types_1.Op.COVERAGE:
+                line.push(" D=" + (0, types_1.iE)(insn));
+                break;
+            case types_1.Op.LOADNIL:
+            case types_1.Op.LOADB:
+            case types_1.Op.MOVE:
+            case types_1.Op.GETGLOBAL:
+            case types_1.Op.GETUPVAL:
+            case types_1.Op.SETUPVAL:
+            case types_1.Op.CLOSEUPVALS:
+            case types_1.Op.NEWCLOSURE:
+            case types_1.Op.RETURN:
+            case types_1.Op.JUMP:
+            case types_1.Op.JUMPBACK:
+            case types_1.Op.JUMPIF:
+            case types_1.Op.JUMPIFNOT:
+            case types_1.Op.NOT:
+            case types_1.Op.MINUS:
+            case types_1.Op.LENGTH:
+            case types_1.Op.DUPTABLE:
+            case types_1.Op.LOADKX:
+            case types_1.Op.JUMPX:
+            case types_1.Op.PREPVARARGS:
+            case types_1.Op.GETVARARGS:
+            case types_1.Op.SETLIST:
+            case types_1.Op.NEWTABLE:
+            case types_1.Op.FORNPREP:
+            case types_1.Op.FORNLOOP:
+            case types_1.Op.FORGPREP:
+            case types_1.Op.FORGPREP_INEXT:
+            case types_1.Op.FORGPREP_NEXT:
+            case types_1.Op.FORGLOOP:
+                pushAB();
+                break;
+            case types_1.Op.GETTABLE:
+            case types_1.Op.SETTABLE:
+            case types_1.Op.GETTABLEN:
+            case types_1.Op.SETTABLEN:
+            case types_1.Op.GETTABLEKS:
+            case types_1.Op.SETTABLEKS:
+            case types_1.Op.ADD:
+            case types_1.Op.SUB:
+            case types_1.Op.MUL:
+            case types_1.Op.DIV:
+            case types_1.Op.MOD:
+            case types_1.Op.POW:
+            case types_1.Op.AND:
+            case types_1.Op.OR:
+            case types_1.Op.ADDK:
+            case types_1.Op.SUBK:
+            case types_1.Op.MULK:
+            case types_1.Op.DIVK:
+            case types_1.Op.MODK:
+            case types_1.Op.POWK:
+            case types_1.Op.ANDK:
+            case types_1.Op.ORK:
+            case types_1.Op.SUBRK:
+            case types_1.Op.DIVRK:
+            case types_1.Op.IDIV:
+            case types_1.Op.IDIVK:
+                pushABC();
+                break;
+            case types_1.Op.CONCAT:
+                pushABC();
+                break;
+            case types_1.Op.SETGLOBAL:
+            case types_1.Op.SETUPVAL:
+                line.push(" A=" + (0, types_1.iA)(insn) + " B=" + (0, types_1.iB)(insn));
+                break;
+            case types_1.Op.GETTABLEKS:
+            case types_1.Op.SETTABLEKS:
+                line.push(" A=" + (0, types_1.iA)(insn) + " B=" + (0, types_1.iB)(insn));
+                break;
+            case types_1.Op.NAMECALL:
+                line.push(" A=" + (0, types_1.iA)(insn) + " B=" + (0, types_1.iB)(insn) + " C=" + (0, types_1.iC)(insn));
+                break;
+            case types_1.Op.CALL:
+            case types_1.Op.CALLFB:
+                line.push(" A=" + (0, types_1.iA)(insn) + " B=" + (0, types_1.iB)(insn) + " C=" + (0, types_1.iC)(insn));
+                break;
+            case types_1.Op.LOADN:
+                line.push(" D=" + (0, types_1.iD)(insn));
+                break;
+            case types_1.Op.LOADK:
+            case types_1.Op.DUPTABLE:
+                line.push(" D=" + (0, types_1.iD)(insn) + " (k" + constText(program, p, (0, types_1.iD)(insn)) + ")");
+                break;
+            case types_1.Op.RETURN:
+                line.push(" A=" + (0, types_1.iA)(insn) + " B=" + (0, types_1.iB)(insn));
+                break;
+            case types_1.Op.JUMP:
+            case types_1.Op.JUMPBACK:
+            case types_1.Op.JUMPIF:
+            case types_1.Op.JUMPIFNOT:
+                line.push(" A=" + (0, types_1.iA)(insn) + " D=" + (0, types_1.iD)(insn));
+                break;
+            default: break;
+        }
+        const tgt = (0, types_1.jumpTarget)(p.code, i);
+        if (tgt >= 0)
+            line.push(" -> " + tgt);
+        if ((0, types_1.opHasAux)(op) && i + 1 < p.code.length) {
+            const aux = p.code[i + 1];
+            line.push(" ; aux=" + (aux >>> 0).toString(16));
+            if (op === types_1.Op.NEWTABLE)
+                line.push(" (hash" + (0, types_1.iC)(insn) + ", array " + aux + ")");
+            if (op === types_1.Op.SETLIST)
+                line.push(" (base " + aux + ")");
+            if (op === types_1.Op.FORGLOOP)
+                line.push(" (vars " + (aux & 0xff) + ((aux >>> 31) ? " ipairs" : "") + ")");
+            if (op === types_1.Op.GETIMPORT)
+                line.push(" (import " + (aux >>> 30) + ": " + (0, types_1.auxA)(aux) + "," + (0, types_1.auxB)(aux) + "," + (aux & 0x3ff) + " => " + importPath(p, aux) + ")");
+            if (op === types_1.Op.JUMPIFEQ || op === types_1.Op.JUMPIFLE || op === types_1.Op.JUMPIFLT ||
+                op === types_1.Op.JUMPIFNOTEQ || op === types_1.Op.JUMPIFNOTLE || op === types_1.Op.JUMPIFNOTLT)
+                line.push(" (aux reg " + (aux & 0xff) + ")");
+            if (op === types_1.Op.GETTABLEKS || op === types_1.Op.SETTABLEKS || op === types_1.Op.NAMECALL ||
+                op === types_1.Op.GETGLOBAL || op === types_1.Op.SETGLOBAL || op === types_1.Op.LOADKX)
+                line.push(" (k" + aux + " " + constText(program, p, aux) + ")");
+        }
+        out.push(line.join("") + "\n");
+        if (op === types_1.Op.NEWCLOSURE && (0, types_1.iD)(insn) >= 0 && (0, types_1.iD)(insn) < p.children.length) {
+            const child = program.protos[p.children[(0, types_1.iD)(insn)]];
+            for (let u = 0; u < child.nups; u++) {
+                i++;
+                if (i >= p.code.length)
+                    break;
+                const cap = p.code[i];
+                const kind = (0, types_1.iA)(cap) === 1 ? "REF" : ((0, types_1.iA)(cap) === 2 ? "UPVAL" : "VAL");
+                out.push("  " + (cap >>> 0).toString(16) + "   " + i + "      -     CAPTURE " + kind + " B=" + (0, types_1.iB)(cap) + "\n");
+            }
+        }
+        if ((0, types_1.opHasAux)(op))
+            i++;
+        i++;
+    }
+    out.push("\n");
+}
+function disassemble(program) {
+    const out = [];
+    out.push("-- luau disassembly\n");
+    out.push("-- protos: " + program.protos.length + ", strings: " + program.strings.length + "\n\n");
+    for (let pi = 0; pi < program.protos.length; pi++)
+        dumpProto(out, program, pi);
+    return out.join("");
+}
+function disassembleProto(program, index) {
+    if (index < 0 || index >= program.protos.length)
+        return "-- no proto " + index + "\n";
+    const out = [];
+    dumpProto(out, program, index);
+    return out.join("");
+}

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+import { Program } from "./types";
+import { ClosureResult, UpvalBind } from "./decompile_internal";
+export { Program, Proto, Constant, ConstKind, Op } from "./types";
+export { base64Decode } from "./base64";
+export { disassemble, disassembleProto } from "./disasm";
+export { decompile, decompileProto } from "./decompiler";
+export { ClosureResult, Expr, Sink, UpvalBind } from "./decompile_internal";
+export interface DecompileInput {
+    /** Raw Luau bytecode bytes. */
+    bytes?: Uint8Array;
+    /** Base64-encoded Luau bytecode (tried automatically if `bytes` fails to parse). */
+    base64?: string;
+    /** Optional path/name, used only for error context. */
+    name?: string;
+}
+export interface DecompileResult {
+    /** Reconstructed, readable Luau source. */
+    source: string;
+    /** Parsed program IR (useful for further analysis). */
+    program: Program;
+    /** True when the bytes were base64-decoded before parsing. */
+    decodedFromBase64: boolean;
+}
+export declare class DecompilerError extends Error {
+    constructor(message: string);
+}
+export declare const Decompiler: {
+    /**
+     * Decompile Luau/Roblox bytecode to readable Luau source.
+     * Accepts raw bytes or a base64 string (the latter is auto-tried if raw bytes fail).
+     */
+    decompile(input: DecompileInput | Uint8Array): DecompileResult;
+    /** Produce a textual disassembly of the bytecode (all protos). */
+    disassemble(input: DecompileInput | Uint8Array): string;
+    /** Produce a textual disassembly of a single proto by index. */
+    disassembleProto(input: DecompileInput | Uint8Array, index: number): string;
+    /**
+     * Low-level: parse bytecode into the Program IR without decompiling.
+     * Returns { program, decodedFromBase64 }.
+     */
+    parse(input: DecompileInput | Uint8Array): {
+        program: Program;
+        decodedFromBase64: boolean;
+    };
+    /** Decompile a single proto (with upvalue bindings) to a ClosureResult. */
+    decompileProto(program: Program, protoIndex: number, upvals?: UpvalBind[]): ClosureResult;
+};
+export default Decompiler;

package/dist/index.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Decompiler = exports.DecompilerError = exports.Sink = exports.decompileProto = exports.decompile = exports.disassembleProto = exports.disassemble = exports.base64Decode = exports.Op = exports.ConstKind = void 0;
+const types_1 = require("./types");
+const parser_1 = require("./parser");
+const base64_1 = require("./base64");
+const disasm_1 = require("./disasm");
+const decompiler_1 = require("./decompiler");
+var types_2 = require("./types");
+Object.defineProperty(exports, "ConstKind", { enumerable: true, get: function () { return types_2.ConstKind; } });
+Object.defineProperty(exports, "Op", { enumerable: true, get: function () { return types_2.Op; } });
+var base64_2 = require("./base64");
+Object.defineProperty(exports, "base64Decode", { enumerable: true, get: function () { return base64_2.base64Decode; } });
+var disasm_2 = require("./disasm");
+Object.defineProperty(exports, "disassemble", { enumerable: true, get: function () { return disasm_2.disassemble; } });
+Object.defineProperty(exports, "disassembleProto", { enumerable: true, get: function () { return disasm_2.disassembleProto; } });
+var decompiler_2 = require("./decompiler");
+Object.defineProperty(exports, "decompile", { enumerable: true, get: function () { return decompiler_2.decompile; } });
+Object.defineProperty(exports, "decompileProto", { enumerable: true, get: function () { return decompiler_2.decompileProto; } });
+var decompile_internal_1 = require("./decompile_internal");
+Object.defineProperty(exports, "Sink", { enumerable: true, get: function () { return decompile_internal_1.Sink; } });
+class DecompilerError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DecompilerError";
+    }
+}
+exports.DecompilerError = DecompilerError;
+function parseInput(input) {
+    const program = (0, types_1.makeProgram)();
+    let fromBase64 = false;
+    if (input.bytes && input.bytes.length > 0) {
+        const err = { msg: "" };
+        if ((0, parser_1.parseBytecode)(input.bytes, program, err)) {
+            return { program, fromBase64 };
+        }
+        if (input.base64) {
+            // fall through to base64 path on failure
+        }
+        else {
+            throw new DecompilerError(err.msg || "failed to parse bytecode");
+        }
+    }
+    if (input.base64) {
+        const decoded = (0, base64_1.base64Decode)(input.base64);
+        if (!decoded) {
+            throw new DecompilerError("invalid base64 input");
+        }
+        const err = { msg: "" };
+        if (!(0, parser_1.parseBytecode)(decoded, program, err)) {
+            throw new DecompilerError(err.msg || "failed to parse bytecode");
+        }
+        fromBase64 = true;
+        return { program, fromBase64 };
+    }
+    if (input.bytes && input.bytes.length > 0) {
+        const err = { msg: "" };
+        if (!(0, parser_1.parseBytecode)(input.bytes, program, err)) {
+            throw new DecompilerError(err.msg || "failed to parse bytecode");
+        }
+        return { program, fromBase64 };
+    }
+    throw new DecompilerError("no bytecode provided (expected `bytes` or `base64`)");
+}
+exports.Decompiler = {
+    /**
+     * Decompile Luau/Roblox bytecode to readable Luau source.
+     * Accepts raw bytes or a base64 string (the latter is auto-tried if raw bytes fail).
+     */
+    decompile(input) {
+        let resolved;
+        if (input instanceof Uint8Array)
+            resolved = { bytes: input };
+        else
+            resolved = input;
+        const { program, fromBase64 } = parseInput(resolved);
+        const source = (0, decompiler_1.decompile)(program);
+        return { source, program, decodedFromBase64: fromBase64 };
+    },
+    /** Produce a textual disassembly of the bytecode (all protos). */
+    disassemble(input) {
+        const resolved = input instanceof Uint8Array ? { bytes: input } : input;
+        const { program } = parseInput(resolved);
+        return (0, disasm_1.disassemble)(program);
+    },
+    /** Produce a textual disassembly of a single proto by index. */
+    disassembleProto(input, index) {
+        const resolved = input instanceof Uint8Array ? { bytes: input } : input;
+        const { program } = parseInput(resolved);
+        return (0, disasm_1.disassembleProto)(program, index);
+    },
+    /**
+     * Low-level: parse bytecode into the Program IR without decompiling.
+     * Returns { program, decodedFromBase64 }.
+     */
+    parse(input) {
+        const resolved = input instanceof Uint8Array ? { bytes: input } : input;
+        const { program, fromBase64 } = parseInput(resolved);
+        return { program, decodedFromBase64: fromBase64 };
+    },
+    /** Decompile a single proto (with upvalue bindings) to a ClosureResult. */
+    decompileProto(program, protoIndex, upvals = []) {
+        const proto = program.protos[protoIndex];
+        if (!proto)
+            throw new DecompilerError(`no proto at index ${protoIndex}`);
+        return (0, decompiler_1.decompileProto)(program, proto, upvals);
+    },
+};
+exports.default = exports.Decompiler;

package/dist/parser.d.ts

@@ -0,0 +1,4 @@
+import { Program } from "./types";
+export declare function parseBytecode(data: Uint8Array, out: Program, err: {
+    msg: string;
+}): boolean;