iris-decompiler 1.0.0

package/README.md

@@ -0,0 +1,78 @@
+# iris-decompiler
+
+A Luau / Roblox bytecode decompiler. Parses compiled Luau bytecode and
+reconstructs readable Luau source. Ships as a **library** plus a small
+**CLI** — no server, no runtime dependencies (Node's standard library only).
+
+## Install / build
+
+```bash
+npm install
+npm run build        # compiles src -> dist (CommonJS + .d.ts types)
+```
+
+## Library usage
+
+```ts
+import { Decompiler } from "iris-decompiler";
+
+// From raw bytes (Uint8Array / Buffer)
+const result = Decompiler.decompile(uint8Array);          // or { bytes }
+console.log(result.source);                               // reconstructed Luau
+
+// From a base64 string
+const r2 = Decompiler.decompile({ base64: b64String });   // r2.decodedFromBase64 === true
+
+// Disassembly instead of decompilation
+const asm = Decompiler.disassemble(uint8Array);           // all protos
+const one = Decompiler.disassembleProto({ bytes }, 0);    // single proto by index
+
+// Low-level parse only (inspect the IR)
+const { program } = Decompiler.parse(uint8Array);
+```
+
+`decompile` accepts either a `Uint8Array` or an object `{ bytes?, base64?, name? }`.
+It returns `{ source, program, decodedFromBase64 }`. Malformed input throws
+`DecompilerError`.
+
+### Direct function exports
+
+```ts
+import { decompile, disassemble, parseBytecode, base64Decode, Op, ConstKind } from "iris-decompiler";
+```
+
+| Export | Purpose |
+|---|---|
+| `Decompiler` | Object API (methods above) |
+| `decompile(program)` / `decompileProto(...)` | Core decompiler |
+| `disassemble(program)` / `disassembleProto(program, i)` | Disassembly |
+| `parseBytecode(bytes, program, err)` | Low-level parser |
+| `base64Decode(str)` | Base64 → `Uint8Array` |
+| `Op`, `ConstKind`, `Program`, `Proto`, `Constant` | Types / enums |
+| `DecompilerError` | Error thrown on invalid input |
+
+## CLI
+
+```bash
+node bin/cli.js <file>            # decompile to stdout
+node bin/cli.js --disasm <file>   # disassemble to stdout
+```
+
+The CLI also accepts a base64 file and auto-decodes it.
+After `npm link` or global install it's available as `iris-decompiler`.
+
+## Bytecode version support
+
+Luau bytecode **versions 3–13** (and the version-100 "classes" format). Anything
+outside that range is rejected with a clear error, e.g. current Roblox client
+bytecode is version 14 → `bytecode version mismatch (expected [3..13], got 14)`.
+
+## Test fixtures
+
+`test-fixtures/` contains sample bytecode. `animate.bin` and `last_raw.bin`
+decompile to ~568 lines of Luau; `health.bin` is version 14 and is expected to
+be rejected.
+
+```bash
+node bin/cli.js test-fixtures/animate.bin
+```

package/bin/cli.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// Usage:
+//   node bin/cli.js <file>            -> decompile
+//   node bin/cli.js --disasm <file>   -> disassemble
+
+const fs = require("fs");
+const path = require("path");
+
+function loadDecompiler() {
+    const distPath = path.join(__dirname, "..", "dist", "index.js");
+    if (fs.existsSync(distPath)) {
+        return require(distPath);
+    }
+    throw new Error("Could not load decompiler: dist/ is missing. Run `npm run build` first.");
+}
+
+function readFileBytes(p) {
+    return new Uint8Array(fs.readFileSync(p));
+}
+
+function main() {
+    const args = process.argv.slice(2);
+    if (args.length < 1) {
+        process.stderr.write("usage: iris-decompiler <file>\n");
+        process.stderr.write("            iris-decompiler --disasm <file>\n");
+        process.exit(1);
+    }
+
+    const D = loadDecompiler();
+
+    if (args[0] === "--disasm" && args.length >= 2) {
+        const data = readFileBytes(args[1]);
+        process.stdout.write(D.Decompiler.disassemble({ bytes: data }));
+        return;
+    }
+
+    const data = readFileBytes(args[0]);
+    try {
+        const result = D.Decompiler.decompile({ bytes: data });
+        process.stdout.write(result.source);
+    } catch (err) {
+        // If raw-byte parsing failed, try as base64.
+        const b64 = Buffer.from(data).toString("utf8");
+        try {
+            const result = D.Decompiler.decompile({ base64: b64 });
+            process.stdout.write(result.source);
+        } catch (e2) {
+            process.stderr.write("error: failed to parse bytecode: " + (err.message || err) + "\n");
+            process.exit(1);
+        }
+    }
+}
+
+main();

package/dist/base64.d.ts

@@ -0,0 +1 @@
+export declare function base64Decode(input: string): Uint8Array | null;

package/dist/base64.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.base64Decode = base64Decode;
+function base64Decode(input) {
+    const out = [];
+    let buffer = 0;
+    let bits = 0;
+    const b64val = (c) => {
+        const code = c.charCodeAt(0);
+        if (code >= 0x41 && code <= 0x5a)
+            return code - 0x41; // A-Z
+        if (code >= 0x61 && code <= 0x7a)
+            return code - 0x61 + 26; // a-z
+        if (code >= 0x30 && code <= 0x39)
+            return code - 0x30 + 52; // 0-9
+        if (code === 0x2b)
+            return 62; // +
+        if (code === 0x2f)
+            return 63; // /
+        return -1;
+    };
+    for (const c of input) {
+        if (c === "\r" || c === "\n" || c === " " || c === "\t")
+            continue;
+        if (c === "=")
+            break;
+        const v = b64val(c);
+        if (v < 0)
+            return null;
+        buffer = (buffer << 6) | v;
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            out.push((buffer >> bits) & 0xff);
+        }
+    }
+    return new Uint8Array(out);
+}

package/dist/decompile_internal.d.ts

@@ -0,0 +1,57 @@
+export declare enum ExprK {
+    Leaf = 0,
+    Bin = 1,
+    Un = 2,
+    Index = 3,
+    Dot = 4,
+    Call = 5,
+    MethodCall = 6,
+    Table = 7,
+    Func = 8,
+    Vararg = 9,
+    IfElse = 10
+}
+export interface Expr {
+    kind: ExprK;
+    prec: number;
+    rightAssoc: boolean;
+    multi: boolean;
+    built: boolean;
+    parenWrap: boolean;
+    text: string;
+    op: string;
+    a?: Expr;
+    b?: Expr;
+    c?: Expr;
+    args: Expr[];
+    name: string;
+    keys: Expr[];
+    vals: Expr[];
+    funcHeader: string;
+    funcComment: string;
+    funcBodyLines: Array<[number, string]>;
+}
+export declare function makeExpr(kind: ExprK): Expr;
+export interface Line {
+    level: number;
+    text: string;
+}
+export declare class Sink {
+    indent: number;
+    lines: Line[];
+    push(level: number, text: string): void;
+    emit(text: string): void;
+}
+export interface UpvalBind {
+    name: string;
+    byRef: boolean;
+    isParentUpvalue: boolean;
+}
+export interface ClosureResult {
+    header: string;
+    comment: string;
+    body: Sink;
+    upvalues: UpvalBind[];
+    selfRef: boolean;
+}
+export declare function makeClosureResult(): ClosureResult;

package/dist/decompile_internal.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Sink = exports.ExprK = void 0;
+exports.makeExpr = makeExpr;
+exports.makeClosureResult = makeClosureResult;
+var ExprK;
+(function (ExprK) {
+    ExprK[ExprK["Leaf"] = 0] = "Leaf";
+    ExprK[ExprK["Bin"] = 1] = "Bin";
+    ExprK[ExprK["Un"] = 2] = "Un";
+    ExprK[ExprK["Index"] = 3] = "Index";
+    ExprK[ExprK["Dot"] = 4] = "Dot";
+    ExprK[ExprK["Call"] = 5] = "Call";
+    ExprK[ExprK["MethodCall"] = 6] = "MethodCall";
+    ExprK[ExprK["Table"] = 7] = "Table";
+    ExprK[ExprK["Func"] = 8] = "Func";
+    ExprK[ExprK["Vararg"] = 9] = "Vararg";
+    ExprK[ExprK["IfElse"] = 10] = "IfElse";
+})(ExprK || (exports.ExprK = ExprK = {}));
+function makeExpr(kind) {
+    return {
+        kind, prec: 0, rightAssoc: false, multi: false, built: false, parenWrap: false,
+        text: "", op: "", args: [], name: "", keys: [], vals: [],
+        funcHeader: "", funcComment: "", funcBodyLines: [],
+    };
+}
+class Sink {
+    constructor() {
+        this.indent = 0;
+        this.lines = [];
+    }
+    push(level, text) {
+        this.lines.push({ level, text });
+    }
+    emit(text) {
+        this.lines.push({ level: this.indent, text });
+    }
+}
+exports.Sink = Sink;
+function makeClosureResult() {
+    return { header: "", comment: "", body: new Sink(), upvalues: [], selfRef: false };
+}

package/dist/decompiler.d.ts

@@ -0,0 +1,4 @@
+import { Program, Proto } from "./types";
+import { UpvalBind, ClosureResult } from "./decompile_internal";
+export declare function decompileProto(program: Program, proto: Proto, upvals: UpvalBind[]): ClosureResult;
+export declare function decompile(program: Program): string;