unidecompiler-plugin-lua 0.1.1__py3-none-any.whl

unidecompiler_plugin_lua/normalize.py

@@ -0,0 +1,241 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Literal
+
+from unidecompiler_plugin_lua.luac import LuaFunctionListing, LuaInstructionListing
+
+
+BranchKind = Literal["conditional-pair", "unconditional"]
+
+BRANCH_OPCODES = {
+    "EQ",
+    "LT",
+    "LE",
+    "TEST",
+    "TESTSET",
+}
+UNCONDITIONAL_JUMP_OPCODES = {"JMP"}
+TERMINATOR_OPCODES = {
+    "RETURN",
+    "RETURN0",
+    "RETURN1",
+    "RETURN2",
+    "RETURNI",
+    "RETURNK",
+}
+UNSUPPORTED_FOR_LINEAR_LIFTING = {
+    "FORPREP",
+    "FORLOOP",
+    "TFORPREP",
+    "TFORCALL",
+    "TFORLOOP",
+    "JMP",
+    "TEST",
+    "TESTSET",
+    "NEWTABLE",
+    "SETLIST",
+    "LEN",
+}
+TARGET_COMMENT_RE = re.compile(r"\bto\s+(?P<target>\d+)\b")
+
+
+@dataclass(frozen=True)
+class NormalizedLuaBranch:
+    pc: int
+    opcode: str
+    target_pc: int
+    kind: BranchKind
+    fallthrough_pc: int | None
+
+    def to_metadata(self) -> dict:
+        data = {
+            "pc": self.pc,
+            "opcode": self.opcode,
+            "target_pc": self.target_pc,
+            "kind": self.kind,
+        }
+        if self.fallthrough_pc is not None:
+            data["fallthrough_pc"] = self.fallthrough_pc
+        return data
+
+
+@dataclass(frozen=True)
+class NormalizedLuaInstruction:
+    pc: int
+    line: int | None
+    opcode: str
+    operands: tuple[str, ...]
+    next_pc: int | None
+    explicit_target_pc: int | None
+
+    def to_metadata(self) -> dict:
+        return {
+            "pc": self.pc,
+            "line": self.line,
+            "opcode": self.opcode,
+            "operands": list(self.operands),
+            "next_pc": self.next_pc,
+            "explicit_target_pc": self.explicit_target_pc,
+        }
+
+
+@dataclass(frozen=True)
+class NormalizedLuaFunction:
+    name: str
+    source: str
+    line_start: int | None
+    line_end: int | None
+    entry_pc: int | None
+    instructions: tuple[NormalizedLuaInstruction, ...]
+    branches: tuple[NormalizedLuaBranch, ...]
+    basic_block_leaders: tuple[int, ...]
+    unsupported_opcodes: tuple[str, ...]
+
+    def to_metadata(self) -> dict:
+        return {
+            "name": self.name,
+            "source": self.source,
+            "line_start": self.line_start,
+            "line_end": self.line_end,
+            "entry_pc": self.entry_pc,
+            "instruction_pcs": [instruction.pc for instruction in self.instructions],
+            "instructions": [
+                instruction.to_metadata() for instruction in self.instructions
+            ],
+            "branch_targets": [branch.to_metadata() for branch in self.branches],
+            "basic_block_leaders": list(self.basic_block_leaders),
+            "unsupported_opcodes": list(self.unsupported_opcodes),
+        }
+
+
+def normalize_lua_functions(
+    functions: tuple[LuaFunctionListing, ...],
+) -> tuple[NormalizedLuaFunction, ...]:
+    return tuple(normalize_lua_function(function) for function in functions)
+
+
+def normalize_lua_function(function: LuaFunctionListing) -> NormalizedLuaFunction:
+    instructions = _normalize_instructions(function.instructions)
+    branches = _normalize_branches(function.instructions)
+    leaders = _basic_block_leaders(function.instructions, branches)
+    unsupported_opcodes = tuple(
+        sorted(
+            {
+                instruction.opcode
+                for instruction in function.instructions
+                if instruction.opcode in UNSUPPORTED_FOR_LINEAR_LIFTING
+            }
+        )
+    )
+
+    return NormalizedLuaFunction(
+        name=function.inferred_name or "<function>",
+        source=function.source,
+        line_start=function.line_start,
+        line_end=function.line_end,
+        entry_pc=instructions[0].pc if instructions else None,
+        instructions=instructions,
+        branches=branches,
+        basic_block_leaders=leaders,
+        unsupported_opcodes=unsupported_opcodes,
+    )
+
+
+def normalized_functions_metadata(
+    functions: tuple[LuaFunctionListing, ...],
+) -> list[dict]:
+    return [
+        normalized.to_metadata() for normalized in normalize_lua_functions(functions)
+    ]
+
+
+def _normalize_instructions(
+    instructions: tuple[LuaInstructionListing, ...],
+) -> tuple[NormalizedLuaInstruction, ...]:
+    return tuple(
+        NormalizedLuaInstruction(
+            pc=instruction.pc,
+            line=instruction.line,
+            opcode=instruction.opcode,
+            operands=instruction.operands,
+            next_pc=_next_pc(instructions, index),
+            explicit_target_pc=_target_from_comment(instruction.comment),
+        )
+        for index, instruction in enumerate(instructions)
+    )
+
+
+def _normalize_branches(
+    instructions: tuple[LuaInstructionListing, ...],
+) -> tuple[NormalizedLuaBranch, ...]:
+    branches: list[NormalizedLuaBranch] = []
+
+    for index, instruction in enumerate(instructions):
+        target_pc = _target_from_comment(instruction.comment)
+        if target_pc is None:
+            continue
+
+        if instruction.opcode in UNCONDITIONAL_JUMP_OPCODES:
+            previous = instructions[index - 1] if index > 0 else None
+            kind: BranchKind = (
+                "conditional-pair"
+                if previous is not None and previous.opcode in BRANCH_OPCODES
+                else "unconditional"
+            )
+            branches.append(
+                NormalizedLuaBranch(
+                    pc=instruction.pc,
+                    opcode=instruction.opcode,
+                    target_pc=target_pc,
+                    kind=kind,
+                    fallthrough_pc=_next_pc(instructions, index),
+                )
+            )
+
+    return tuple(branches)
+
+
+def _basic_block_leaders(
+    instructions: tuple[LuaInstructionListing, ...],
+    branches: tuple[NormalizedLuaBranch, ...],
+) -> tuple[int, ...]:
+    if not instructions:
+        return ()
+
+    instruction_pcs = {instruction.pc for instruction in instructions}
+    leaders = {instructions[0].pc}
+
+    for branch in branches:
+        if branch.target_pc in instruction_pcs:
+            leaders.add(branch.target_pc)
+        if branch.fallthrough_pc in instruction_pcs:
+            leaders.add(branch.fallthrough_pc)
+
+    for index, instruction in enumerate(instructions):
+        if instruction.opcode in TERMINATOR_OPCODES:
+            next_pc = _next_pc(instructions, index)
+            if next_pc in instruction_pcs:
+                leaders.add(next_pc)
+
+    return tuple(sorted(leaders))
+
+
+def _next_pc(
+    instructions: tuple[LuaInstructionListing, ...],
+    index: int,
+) -> int | None:
+    next_index = index + 1
+    if next_index >= len(instructions):
+        return None
+    return instructions[next_index].pc
+
+
+def _target_from_comment(comment: str | None) -> int | None:
+    if comment is None:
+        return None
+    match = TARGET_COMMENT_RE.search(comment)
+    if match is None:
+        return None
+    return int(match.group("target"))

unidecompiler_plugin_lua/plugin.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+from unidecompiler.core.ir import ModuleIR
+from unidecompiler.plugins import FrontendModule
+from unidecompiler_plugin_lua.lifter import lift_lua_chunk
+from unidecompiler_plugin_lua.chunk54 import decode_lua54_chunk, Lua54ChunkError
+from unidecompiler_plugin_lua.luac import (
+    looks_like_luac,
+    PreferredLuaChunkDecoder,
+    LuaChunkDecoder,
+)
+from unidecompiler_plugin_lua.normalize import normalized_functions_metadata
+from unidecompiler_plugin_lua.simulation import LuaSimulationAdapter
+from unidecompiler_plugin_lua.support import LUA_VERSION_SUPPORT
+
+
+class LuaFrontendPlugin:
+    id = "lua"
+    display_name = "Lua bytecode"
+    supported_inputs = (".luac",)
+    version_support = LUA_VERSION_SUPPORT
+    simulation_adapter = LuaSimulationAdapter
+
+    def __init__(self, decoder: LuaChunkDecoder | None = None) -> None:
+        self.decoder = decoder or PreferredLuaChunkDecoder()
+
+    def can_load(self, data: bytes, filename: str | None = None) -> bool:
+        return looks_like_luac(data) and self.decoder.can_decode(data, filename)
+
+    def decode(self, data: bytes, filename: str | None = None) -> FrontendModule:
+        chunk = self.decoder.decode(data, filename)
+        normalized_functions = normalized_functions_metadata(chunk.functions)
+        diagnostics = _normalization_diagnostics(normalized_functions)
+        return FrontendModule(
+            frontend_id=self.id,
+            payload=chunk,
+            metadata={
+                "filename": filename,
+                "format": "luac",
+                "version": chunk.header.version_label,
+                "endianness": (
+                    None
+                    if chunk.header.little_endian is None
+                    else "little"
+                    if chunk.header.little_endian
+                    else "big"
+                ),
+                "debug_info_present": chunk.disassembly is not None,
+                "diagnostics": diagnostics,
+                "lua": {
+                    "int_size": chunk.header.int_size,
+                    "size_t_size": chunk.header.size_t_size,
+                    "instruction_size": chunk.header.instruction_size,
+                    "number_size": chunk.header.lua_number_size,
+                    "integral_numbers": chunk.header.integral_numbers,
+                    "decoder": chunk.decoder_id or self.decoder.id,
+                    "decoder_policy": self.decoder.id,
+                    "has_disassembly": chunk.disassembly is not None,
+                    "normalized_functions": normalized_functions,
+                },
+            },
+        )
+
+    def lift(self, module: FrontendModule) -> ModuleIR:
+        if module.frontend_id != self.id:
+            raise TypeError(
+                f"Lua frontend cannot lift module from {module.frontend_id!r}"
+            )
+
+        return lift_lua_chunk(module.payload, module.metadata)
+
+
+class Lua54BinaryChunkDecoder:
+    id = "lua54-binary"
+
+    def can_decode(self, data: bytes, filename: str | None = None) -> bool:
+        return looks_like_luac(data) and len(data) >= 8 and data[4] == 0x54
+
+    def decode(self, data: bytes, filename: str | None = None):
+        try:
+            return decode_lua54_chunk(data, filename)
+        except Lua54ChunkError as exc:
+            from unidecompiler_plugin_lua.luac import LuacDecodeError
+
+            raise LuacDecodeError(str(exc)) from exc
+
+
+def _normalization_diagnostics(
+    normalized_functions: list[dict],
+) -> list[dict[str, object]]:
+    diagnostics: list[dict[str, object]] = []
+    for function in normalized_functions:
+        unsupported_opcodes = function["unsupported_opcodes"]
+        if not unsupported_opcodes:
+            continue
+        diagnostics.append(
+            {
+                "severity": "info",
+                "code": "lua.requires-cfg-structuring",
+                "function": function["name"],
+                "message": (
+                    "Function contains Lua instructions that require CFG/"
+                    "structuring before safe pseudocode lifting."
+                ),
+                "opcodes": unsupported_opcodes,
+            }
+        )
+    return diagnostics

unidecompiler_plugin_lua/simulation.py

@@ -0,0 +1,78 @@
+"""Optional Lua runtime facts for the decoupled generic IR simulator."""
+
+from __future__ import annotations
+
+
+class LuaSimulationAdapter:
+    """Resolve Lua names and values without executing Lua bytecode."""
+
+    frontend_id = "lua"
+
+    def resolve_function(self, query, decoded_module, lifted_module):
+        from unidecompiler_simulator import NotHandled, ResolvedFunction
+
+        if not isinstance(query, str):
+            return NotHandled
+        matches = [
+            function
+            for function in self._walk(lifted_module.functions)
+            if function.name == query
+        ]
+        if len(matches) != 1:
+            return NotHandled
+        return ResolvedFunction(matches[0], identifier=query)
+
+    def resolve_global(self, name, context):
+        from unidecompiler_simulator import IntrinsicCall, NotHandled
+
+        if name == "vm_forloop_continues":
+            return IntrinsicCall("range_continues")
+        return NotHandled
+
+    def list_simulation_targets(self, decoded_module, lifted_module):
+        from unidecompiler_simulator import SimulationTargetCandidate
+
+        functions = tuple(self._walk(lifted_module.functions))
+        names = {function.name for function in functions}
+        return tuple(
+            SimulationTargetCandidate(function.name, function.name)
+            for function in functions
+            if sum(candidate.name == function.name for candidate in functions) == 1
+            and function.name in names
+        )
+
+    def unary_op(self, op, value, context):
+        from unidecompiler_simulator import NotHandled, TableValue
+
+        if op != "#":
+            return NotHandled
+        if isinstance(value, TableValue):
+            return len(value.array_items)
+        if isinstance(value, (list, str, tuple)):
+            return len(value)
+        return NotHandled
+
+    def get_item(self, obj, key, context):
+        from unidecompiler_simulator import NotHandled
+
+        if not isinstance(key, int):
+            return NotHandled
+        if isinstance(obj, list):
+            return obj[key - 1]
+        return NotHandled
+
+    def set_item(self, obj, key, value, context):
+        from unidecompiler_simulator import NotHandled
+
+        if not isinstance(key, int):
+            return NotHandled
+        if isinstance(obj, list):
+            obj[key - 1] = value
+            return None
+        return NotHandled
+
+    @staticmethod
+    def _walk(functions):
+        for function in functions:
+            yield function
+            yield from LuaSimulationAdapter._walk(function.nested_functions)

unidecompiler_plugin_lua/support.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from unidecompiler.plugins import FrontendVersionSupport
+
+
+LUA_VERSION_SUPPORT = FrontendVersionSupport(
+    family="Lua bytecode",
+    versions=("5.4", "5.1 header/resource fallback"),
+    parser="internal Lua 5.4 chunk parser; header-only fallback for older chunks",
+    status="Lua 5.4 instruction submission; older chunks are detected but not lifted",
+    notes=(
+        "Adding Lua 5.1 support should add a Lua 5.1 decoder/opcode table in this frontend.",
+        "The frontend must still submit thin VM steps only.",
+    ),
+)

unidecompiler_plugin_lua-0.1.1.dist-info/METADATA

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: unidecompiler-plugin-lua
+Version: 0.1.1
+Summary: Lua bytecode frontend plugin for unidecompiler
+Author-email: Wker <1670133844@qq.com>
+License-Expression: AGPL-3.0-or-later
+Project-URL: Homepage, https://github.com/Wker666/unidecompiler
+Project-URL: Repository, https://github.com/Wker666/unidecompiler
+Project-URL: Issues, https://github.com/Wker666/unidecompiler/issues
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: unidecompiler<0.2.0,>=0.1.1
+
+# unidecompiler-plugin-lua
+
+Frontend plugin for Lua `.luac` bytecode chunks. It decodes Lua bytecode and
+submits neutral thin IR to `unidecompiler` for recovery and rendering.
+
+Install with:
+
+```sh
+python -m pip install unidecompiler-plugin-lua
+```
+
+The plugin is discovered automatically by compatible CLI and GUI hosts.

unidecompiler_plugin_lua-0.1.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+unidecompiler_plugin_lua/__init__.py,sha256=ljweni-50I--HtwaMZFPbrGMQ5yW94FKaMUKCjnXT8I,30
+unidecompiler_plugin_lua/chunk54.py,sha256=oWTI-UmkQrfaLqr_qvUM4JjLNSJc-by7jtbyk2RY5jo,19535
+unidecompiler_plugin_lua/lifter.py,sha256=F--6eYjqEUFYNqjM68qDV4s23qR0MD6uOw6Eks-cTes,56041
+unidecompiler_plugin_lua/luac.py,sha256=uvVv6OlIBtqqP-gHYge_paaXtkLj8vylUyptSM1kGCo,18201
+unidecompiler_plugin_lua/normalize.py,sha256=1y0C9nFYXnAhAwbN61-8SW5nqVD0bdZ66OUZ8oLj_EE,6862
+unidecompiler_plugin_lua/plugin.py,sha256=qeaapfHSEeRf9sPEENd_ZZVyOMHkdcq7mo53VfvqEUY,4186
+unidecompiler_plugin_lua/simulation.py,sha256=K5rHem8blewEGFEY_MurKj7SncsisrS73cV65_70gFM,2575
+unidecompiler_plugin_lua/support.py,sha256=I5hM8JubH3pCBGWpwoXVDXI_gO42eoIMfCyQ0qM9f_s,569
+unidecompiler_plugin_lua-0.1.1.dist-info/METADATA,sha256=Mncv_aK4UrFp_Irl2CTDwOmRKglg6Qu-GOO8xJQt10Q,830
+unidecompiler_plugin_lua-0.1.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+unidecompiler_plugin_lua-0.1.1.dist-info/entry_points.txt,sha256=kA7THgRbo2r_aAVM5z4MCM0DqPZ3xiTB4GQQMMEHwvg,82
+unidecompiler_plugin_lua-0.1.1.dist-info/top_level.txt,sha256=D-0vATcYYrv-RckgazUaZyYJZcCAuth6N7H6hLtuSjw,25
+unidecompiler_plugin_lua-0.1.1.dist-info/RECORD,,

unidecompiler_plugin_lua-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

unidecompiler_plugin_lua-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[unidecompiler.frontends]
+lua = unidecompiler_plugin_lua.plugin:LuaFrontendPlugin

unidecompiler_plugin_lua-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+unidecompiler_plugin_lua