pyflashkit 1.0.0__py3-none-any.whl

flashkit/abc/constants.py

@@ -0,0 +1,198 @@
+"""
+AVM2 constants — multiname kinds, namespace kinds, trait kinds, flags, and opcodes.
+
+All constants follow the naming convention from the AVM2 specification.
+Opcode constants use the ``OP_`` prefix and match the mnemonics from
+avm2overview.pdf Chapter 5 (AVM2 instructions).
+
+Reference: Adobe AVM2 Overview, Chapters 4.4–4.8, Chapter 5.
+"""
+
+# ── Multiname kinds ─────────────────────────────────────────────────────────
+# Used in MultinameInfo.kind to determine which fields are valid.
+
+CONSTANT_QName       = 0x07  # Qualified name: namespace + name
+CONSTANT_QNameA      = 0x0D  # Qualified name (attribute)
+CONSTANT_RTQName     = 0x0F  # Runtime qualified name: name only, ns from stack
+CONSTANT_RTQNameA    = 0x10  # Runtime qualified name (attribute)
+CONSTANT_RTQNameL    = 0x11  # Runtime qualified name (late-bound): both from stack
+CONSTANT_RTQNameLA   = 0x12  # Runtime qualified name (late-bound, attribute)
+CONSTANT_Multiname   = 0x09  # Multiname: name + namespace set
+CONSTANT_MultinameA  = 0x0E  # Multiname (attribute)
+CONSTANT_MultinameL  = 0x1B  # Late-bound multiname: name from stack + ns set
+CONSTANT_MultinameLA = 0x1C  # Late-bound multiname (attribute)
+CONSTANT_TypeName    = 0x1D  # Parameterized type: Vector.<T>
+
+# ── Namespace kinds ─────────────────────────────────────────────────────────
+# Used in NamespaceInfo.kind.
+
+CONSTANT_Namespace          = 0x08  # Regular namespace
+CONSTANT_PackageNamespace   = 0x16  # Public package namespace
+CONSTANT_PackageInternalNs  = 0x17  # Package-internal namespace
+CONSTANT_ProtectedNamespace = 0x18  # Protected namespace (class hierarchy)
+CONSTANT_ExplicitNamespace  = 0x19  # Explicit namespace (user-defined)
+CONSTANT_StaticProtectedNs  = 0x1A  # Static protected namespace
+CONSTANT_PrivateNs          = 0x05  # Private namespace (class-scoped)
+
+# ── Trait kinds ─────────────────────────────────────────────────────────────
+# Used in TraitInfo.kind (lower 4 bits of the kind byte).
+# Upper 4 bits are trait attributes (ATTR_Final=0x01, ATTR_Override=0x02, ATTR_Metadata=0x04).
+
+TRAIT_Slot     = 0  # Instance variable (field)
+TRAIT_Method   = 1  # Method
+TRAIT_Getter   = 2  # Getter property
+TRAIT_Setter   = 3  # Setter property
+TRAIT_Class    = 4  # Class definition
+TRAIT_Function = 5  # Function (closure)
+TRAIT_Const    = 6  # Constant (final field)
+
+# Trait attribute flags (upper 4 bits of kind byte)
+ATTR_Final    = 0x01
+ATTR_Override = 0x02
+ATTR_Metadata = 0x04
+
+# ── Method flags ────────────────────────────────────────────────────────────
+# Bitmask flags in MethodInfo.flags.
+
+METHOD_NeedArguments  = 0x01  # Method uses 'arguments' object
+METHOD_NeedActivation = 0x02  # Method needs an activation object
+METHOD_NeedRest       = 0x04  # Method uses ...rest parameter
+METHOD_HasOptional    = 0x08  # Method has optional parameters
+METHOD_SetDxns        = 0x40  # Method sets default XML namespace
+METHOD_HasParamNames  = 0x80  # Method has debug parameter names
+
+# ── Instance flags ──────────────────────────────────────────────────────────
+# Bitmask flags in InstanceInfo.flags.
+
+INSTANCE_Sealed      = 0x01  # Class is sealed (no dynamic properties)
+INSTANCE_Final       = 0x02  # Class is final (cannot be subclassed)
+INSTANCE_Interface   = 0x04  # Class is an interface
+INSTANCE_ProtectedNs = 0x08  # Class has a protected namespace
+
+# ── AVM2 opcodes ────────────────────────────────────────────────────────────
+# Instruction opcodes for AVM2 bytecode (MethodBodyInfo.code).
+# Organized by functional group.
+
+# Control flow
+OP_nop            = 0x02
+OP_throw          = 0x03
+OP_label          = 0x09
+OP_jump           = 0x10
+OP_iftrue         = 0x11
+OP_iffalse        = 0x12
+OP_ifeq           = 0x13
+OP_ifne           = 0x14
+OP_iflt           = 0x15
+OP_ifle           = 0x16
+OP_ifgt           = 0x17
+OP_ifge           = 0x18
+OP_ifstricteq     = 0x19
+OP_ifstrictne     = 0x1A
+OP_lookupswitch   = 0x1B
+
+# Scope management
+OP_pushwith       = 0x1C
+OP_popscope       = 0x1D
+OP_pushscope      = 0x30
+OP_getscopeobject = 0x65
+
+# Stack operations
+OP_pop            = 0x29
+OP_dup            = 0x2A
+OP_swap           = 0x2B
+
+# Push constants
+OP_pushnull       = 0x20
+OP_pushundefined  = 0x21
+OP_pushtrue       = 0x26
+OP_pushfalse      = 0x27
+OP_pushnan        = 0x28
+OP_pushbyte       = 0x24
+OP_pushshort      = 0x25
+OP_pushstring     = 0x2C
+OP_pushint        = 0x2D
+OP_pushuint       = 0x2E
+OP_pushdouble     = 0x2F
+
+# Iteration
+OP_nextname       = 0x1E
+OP_hasnext        = 0x1F
+OP_nextvalue      = 0x23
+OP_hasnext2       = 0x32
+
+# Locals
+OP_getlocal       = 0x62
+OP_setlocal       = 0x63
+OP_getlocal_0     = 0xD0
+OP_getlocal_1     = 0xD1
+OP_getlocal_2     = 0xD2
+OP_getlocal_3     = 0xD3
+OP_setlocal_0     = 0xD4
+OP_setlocal_1     = 0xD5
+OP_setlocal_2     = 0xD6
+OP_setlocal_3     = 0xD7
+
+# Properties
+OP_getproperty    = 0x66
+OP_setproperty    = 0x61
+OP_initproperty   = 0x68
+OP_getlex         = 0x60
+OP_findpropstrict = 0x5D
+
+# Calls
+OP_call           = 0x41
+OP_construct      = 0x42
+OP_callproperty   = 0x46
+OP_returnvoid     = 0x47
+OP_returnvalue    = 0x48
+OP_constructsuper = 0x49
+OP_constructprop  = 0x4A
+OP_callpropvoid   = 0x4F
+
+# Object creation
+OP_newfunction    = 0x40
+OP_newarray       = 0x56
+OP_newclass       = 0x58
+
+# Type conversion
+OP_convert_s      = 0x70
+OP_convert_i      = 0x73
+OP_convert_d      = 0x75
+OP_coerce         = 0x80
+OP_coerce_a       = 0x82
+OP_coerce_s       = 0x85
+
+# Comparison & logic
+OP_typeof         = 0x95
+OP_not            = 0x96
+OP_equals         = 0xAB
+OP_strictequals   = 0xAC
+OP_lessthan       = 0xAD
+OP_lessequals     = 0xAE
+OP_greaterthan    = 0xAF
+OP_greaterequals  = 0xB0
+
+# Arithmetic
+OP_increment      = 0x91
+OP_decrement      = 0x93
+OP_add            = 0xA0
+OP_subtract       = 0xA1
+OP_multiply       = 0xA2
+OP_divide         = 0xA3
+OP_modulo         = 0xA4
+OP_increment_i    = 0xC0
+OP_decrement_i    = 0xC1
+
+# Bitwise
+OP_bitor          = 0xA9
+OP_bitand         = 0xA8
+OP_bitxor         = 0xAA
+OP_lshift         = 0xA5
+OP_rshift         = 0xA6
+OP_urshift        = 0xA7
+OP_bitnot         = 0x97
+
+# Debugging
+OP_debug          = 0xEF
+OP_debugline      = 0xF0
+OP_debugfile      = 0xF1

flashkit/abc/disasm.py

@@ -0,0 +1,364 @@
+"""
+AVM2 bytecode disassembler / instruction decoder.
+
+Walks the raw bytecode in ``MethodBodyInfo.code`` and yields structured
+``Instruction`` objects. This is the foundation for call graph analysis,
+cross-reference indexing, and string constant discovery.
+
+Usage::
+
+    from flashkit.abc.disasm import decode_instructions
+
+    for instr in decode_instructions(method_body.code):
+        print(f"0x{instr.offset:04X}  {instr.mnemonic}  {instr.operands}")
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+
+from ..errors import ABCParseError
+from .parser import read_u30, read_u8
+from .constants import *
+
+log = logging.getLogger(__name__)
+
+
+@dataclass
+class Instruction:
+    """A single decoded AVM2 instruction.
+
+    Attributes:
+        offset: Byte offset of this instruction in the method body code.
+        opcode: Opcode byte value.
+        mnemonic: Human-readable opcode name.
+        operands: List of decoded operand values.
+        size: Total size in bytes (opcode + operands).
+    """
+    offset: int
+    opcode: int
+    mnemonic: str
+    operands: list[int] = field(default_factory=list)
+    size: int = 1
+
+
+# ── Opcode table ────────────────────────────────────────────────────────────
+# Maps opcode → (mnemonic, operand_format)
+# Operand formats:
+#   ""       = no operands
+#   "u30"    = one u30
+#   "u30u30" = two u30s
+#   "u8"     = one byte
+#   "s24"    = signed 24-bit offset
+#   "u30u8"  = u30 + byte (hasnext2 uses this differently, but close enough)
+#   "special" = handled individually (lookupswitch, debug)
+
+_OPCODE_TABLE: dict[int, tuple[str, str]] = {
+    # Control flow
+    OP_nop:            ("nop",            ""),
+    OP_throw:          ("throw",          ""),
+    OP_label:          ("label",          ""),
+    OP_jump:           ("jump",           "s24"),
+    OP_iftrue:         ("iftrue",         "s24"),
+    OP_iffalse:        ("iffalse",        "s24"),
+    OP_ifeq:           ("ifeq",           "s24"),
+    OP_ifne:           ("ifne",           "s24"),
+    OP_iflt:           ("iflt",           "s24"),
+    OP_ifle:           ("ifle",           "s24"),
+    OP_ifgt:           ("ifgt",           "s24"),
+    OP_ifge:           ("ifge",           "s24"),
+    OP_ifstricteq:     ("ifstricteq",     "s24"),
+    OP_ifstrictne:     ("ifstrictne",     "s24"),
+    OP_lookupswitch:   ("lookupswitch",   "special"),
+
+    # Scope
+    OP_pushwith:       ("pushwith",       ""),
+    OP_popscope:       ("popscope",       ""),
+    OP_pushscope:      ("pushscope",      ""),
+    OP_getscopeobject: ("getscopeobject", "u30"),
+
+    # Stack
+    OP_pop:            ("pop",            ""),
+    OP_dup:            ("dup",            ""),
+    OP_swap:           ("swap",           ""),
+
+    # Push constants
+    OP_pushnull:       ("pushnull",       ""),
+    OP_pushundefined:  ("pushundefined",  ""),
+    OP_pushtrue:       ("pushtrue",       ""),
+    OP_pushfalse:      ("pushfalse",      ""),
+    OP_pushnan:        ("pushnan",        ""),
+    OP_pushbyte:       ("pushbyte",       "u8"),
+    OP_pushshort:      ("pushshort",      "u30"),
+    OP_pushstring:     ("pushstring",     "u30"),
+    OP_pushint:        ("pushint",        "u30"),
+    OP_pushuint:       ("pushuint",       "u30"),
+    OP_pushdouble:     ("pushdouble",     "u30"),
+
+    # Iteration
+    OP_nextname:       ("nextname",       ""),
+    OP_hasnext:        ("hasnext",        ""),
+    OP_nextvalue:      ("nextvalue",      ""),
+    OP_hasnext2:       ("hasnext2",       "u30u30"),
+
+    # Locals
+    OP_getlocal:       ("getlocal",       "u30"),
+    OP_setlocal:       ("setlocal",       "u30"),
+    OP_getlocal_0:     ("getlocal_0",     ""),
+    OP_getlocal_1:     ("getlocal_1",     ""),
+    OP_getlocal_2:     ("getlocal_2",     ""),
+    OP_getlocal_3:     ("getlocal_3",     ""),
+    OP_setlocal_0:     ("setlocal_0",     ""),
+    OP_setlocal_1:     ("setlocal_1",     ""),
+    OP_setlocal_2:     ("setlocal_2",     ""),
+    OP_setlocal_3:     ("setlocal_3",     ""),
+
+    # Properties
+    OP_getproperty:    ("getproperty",    "u30"),
+    OP_setproperty:    ("setproperty",    "u30"),
+    OP_initproperty:   ("initproperty",   "u30"),
+    OP_getlex:         ("getlex",         "u30"),
+    OP_findpropstrict: ("findpropstrict", "u30"),
+
+    # Calls
+    OP_call:           ("call",           "u30"),
+    OP_construct:      ("construct",      "u30"),
+    OP_callproperty:   ("callproperty",   "u30u30"),
+    OP_returnvoid:     ("returnvoid",     ""),
+    OP_returnvalue:    ("returnvalue",    ""),
+    OP_constructsuper: ("constructsuper",  "u30"),
+    OP_constructprop:  ("constructprop",  "u30u30"),
+    OP_callpropvoid:   ("callpropvoid",   "u30u30"),
+
+    # Object creation
+    OP_newfunction:    ("newfunction",    "u30"),
+    OP_newarray:       ("newarray",       "u30"),
+    OP_newclass:       ("newclass",       "u30"),
+
+    # Type conversion
+    OP_convert_s:      ("convert_s",      ""),
+    OP_convert_i:      ("convert_i",      ""),
+    OP_convert_d:      ("convert_d",      ""),
+    OP_coerce:         ("coerce",         "u30"),
+    OP_coerce_a:       ("coerce_a",       ""),
+    OP_coerce_s:       ("coerce_s",       ""),
+
+    # Comparison & logic
+    OP_typeof:         ("typeof",         ""),
+    OP_not:            ("not",            ""),
+    OP_equals:         ("equals",         ""),
+    OP_strictequals:   ("strictequals",   ""),
+    OP_lessthan:       ("lessthan",       ""),
+    OP_lessequals:     ("lessequals",     ""),
+    OP_greaterthan:    ("greaterthan",    ""),
+    OP_greaterequals:  ("greaterequals",  ""),
+
+    # Arithmetic
+    OP_increment:      ("increment",      ""),
+    OP_decrement:      ("decrement",      ""),
+    OP_add:            ("add",            ""),
+    OP_subtract:       ("subtract",       ""),
+    OP_multiply:       ("multiply",       ""),
+    OP_divide:         ("divide",         ""),
+    OP_modulo:         ("modulo",         ""),
+    OP_increment_i:    ("increment_i",    ""),
+    OP_decrement_i:    ("decrement_i",    ""),
+
+    # Bitwise
+    OP_bitor:          ("bitor",          ""),
+    OP_bitand:         ("bitand",         ""),
+    OP_bitxor:         ("bitxor",         ""),
+    OP_lshift:         ("lshift",         ""),
+    OP_rshift:         ("rshift",         ""),
+    OP_urshift:        ("urshift",        ""),
+    OP_bitnot:         ("bitnot",         ""),
+
+    # Debugging
+    OP_debug:          ("debug",          "special"),
+    OP_debugline:      ("debugline",      "u30"),
+    OP_debugfile:      ("debugfile",      "u30"),
+}
+
+# Additional opcodes not in our OP_ constants but valid AVM2
+_EXTRA_OPCODES: dict[int, tuple[str, str]] = {
+    0x04: ("getsuper",        "u30"),
+    0x05: ("setsuper",        "u30"),
+    0x06: ("dxns",            "u30"),
+    0x07: ("dxnslate",        ""),
+    0x08: ("kill",            "u30"),
+    0x0C: ("ifnlt",           "s24"),
+    0x0D: ("ifnle",           "s24"),
+    0x0E: ("ifngt",           "s24"),
+    0x0F: ("ifnge",           "s24"),
+    0x1E: ("nextname",        ""),
+    0x30: ("pushscope",       ""),
+    0x43: ("callmethod",      "u30u30"),
+    0x44: ("callstatic",      "u30u30"),
+    0x45: ("callsuper",       "u30u30"),
+    0x4C: ("callproplex",     "u30u30"),
+    0x4E: ("callsupervoid",   "u30u30"),
+    0x53: ("applytype",       "u30"),
+    0x55: ("newobject",       "u30"),
+    0x57: ("newactivation",   ""),
+    0x59: ("getdescendants",  "u30"),
+    0x5A: ("newcatch",        "u30"),
+    0x5E: ("findproperty",    "u30"),
+    0x64: ("getglobalscope",  ""),
+    0x6A: ("deleteproperty",  "u30"),
+    0x6C: ("getslot",         "u30"),
+    0x6D: ("setslot",         "u30"),
+    0x6E: ("getglobalslot",   "u30"),
+    0x6F: ("setglobalslot",   "u30"),
+    0x70: ("convert_s",       ""),
+    0x71: ("esc_xelem",       ""),
+    0x72: ("esc_xattr",       ""),
+    0x73: ("convert_i",       ""),
+    0x74: ("convert_u",       ""),
+    0x75: ("convert_d",       ""),
+    0x76: ("convert_b",       ""),
+    0x77: ("convert_o",       ""),
+    0x78: ("checkfilter",     ""),
+    0x80: ("coerce",          "u30"),
+    0x81: ("coerce_b",        ""),
+    0x83: ("coerce_i",        ""),
+    0x84: ("coerce_d",        ""),
+    0x86: ("astype",          "u30"),
+    0x87: ("astypelate",      ""),
+    0x88: ("coerce_u",        ""),
+    0x89: ("coerce_o",        ""),
+    0x90: ("negate",          ""),
+    0x92: ("inclocal",        "u30"),
+    0x94: ("declocal",        "u30"),
+    0x96: ("not",             ""),
+    0x97: ("bitnot",          ""),
+    0x9A: ("concat",          ""),
+    0x9B: ("add_d",           ""),
+    0xA0: ("add",             ""),
+    0xA5: ("lshift",          ""),
+    0xA6: ("rshift",          ""),
+    0xA7: ("urshift",         ""),
+    0xA8: ("bitand",          ""),
+    0xA9: ("bitor",           ""),
+    0xAA: ("bitxor",          ""),
+    0xB1: ("instanceof",      ""),
+    0xB2: ("istype",          "u30"),
+    0xB3: ("istypelate",      ""),
+    0xB4: ("in",              ""),
+    0xC0: ("increment_i",     ""),
+    0xC1: ("decrement_i",     ""),
+    0xC2: ("inclocal_i",      "u30"),
+    0xC3: ("declocal_i",      "u30"),
+    0xC4: ("negate_i",        ""),
+    0xC5: ("add_i",           ""),
+    0xC6: ("subtract_i",      ""),
+    0xC7: ("multiply_i",      ""),
+    0xF0: ("debugline",       "u30"),
+    0xF1: ("debugfile",       "u30"),
+}
+
+
+def _read_s24(data: bytes, offset: int) -> tuple[int, int]:
+    """Read a signed 24-bit integer (little-endian)."""
+    val = data[offset] | (data[offset + 1] << 8) | (data[offset + 2] << 16)
+    if val & 0x800000:
+        val -= 0x1000000
+    return val, offset + 3
+
+
+def _build_lookup() -> dict[int, tuple[str, str]]:
+    """Build the combined opcode lookup table."""
+    lookup = dict(_EXTRA_OPCODES)
+    lookup.update(_OPCODE_TABLE)  # primary table takes precedence
+    return lookup
+
+_LOOKUP = _build_lookup()
+
+
+def decode_instructions(code: bytes,
+                        strict: bool = False) -> list[Instruction]:
+    """Decode an AVM2 bytecode stream into a list of instructions.
+
+    Args:
+        code: Raw bytecode bytes (from MethodBodyInfo.code).
+        strict: If True, raise ``ABCParseError`` on any decode problem
+                (unknown opcodes, truncated operands). If False (default),
+                log warnings and emit partial instructions.
+
+    Returns:
+        List of decoded Instruction objects.
+
+    Raises:
+        ABCParseError: Only when ``strict=True`` and a problem is found.
+    """
+    instructions: list[Instruction] = []
+    off = 0
+    code_len = len(code)
+
+    while off < code_len:
+        start = off
+        op = code[off]
+        off += 1
+
+        entry = _LOOKUP.get(op)
+        if entry is None:
+            msg = f"Unknown opcode 0x{op:02X} at offset 0x{start:04X}"
+            if strict:
+                raise ABCParseError(msg)
+            log.warning(msg)
+            instructions.append(Instruction(
+                offset=start, opcode=op, mnemonic=f"unknown_0x{op:02X}",
+                operands=[], size=1))
+            continue
+
+        mnemonic, fmt = entry
+        operands: list[int] = []
+
+        try:
+            if fmt == "":
+                pass
+            elif fmt == "u8":
+                val, off = read_u8(code, off)
+                operands.append(val)
+            elif fmt == "u30":
+                val, off = read_u30(code, off)
+                operands.append(val)
+            elif fmt == "u30u30":
+                val1, off = read_u30(code, off)
+                val2, off = read_u30(code, off)
+                operands.extend([val1, val2])
+            elif fmt == "s24":
+                val, off = _read_s24(code, off)
+                operands.append(val)
+            elif fmt == "special":
+                if op == OP_lookupswitch:
+                    default_off, off = _read_s24(code, off)
+                    case_count, off = read_u30(code, off)
+                    operands.append(default_off)
+                    operands.append(case_count)
+                    for _ in range(case_count + 1):
+                        case_off, off = _read_s24(code, off)
+                        operands.append(case_off)
+                elif op == OP_debug:
+                    debug_type, off = read_u8(code, off)
+                    index, off = read_u30(code, off)
+                    reg, off = read_u8(code, off)
+                    extra, off = read_u30(code, off)
+                    operands.extend([debug_type, index, reg, extra])
+        except (IndexError, ValueError) as e:
+            msg = (f"Truncated operand for {mnemonic} at offset "
+                   f"0x{start:04X}: {e}")
+            if strict:
+                raise ABCParseError(msg) from e
+            log.warning(msg)
+            # Emit what we have so far and stop decoding
+            instructions.append(Instruction(
+                offset=start, opcode=op, mnemonic=mnemonic,
+                operands=operands, size=off - start))
+            break
+
+        instructions.append(Instruction(
+            offset=start, opcode=op, mnemonic=mnemonic,
+            operands=operands, size=off - start))
+
+    return instructions