pyflashkit 1.0.0__tar.gz → 1.2.0__tar.gz

{pyflashkit-1.0.0 → pyflashkit-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyflashkit
-Version: 1.0.0
+Version: 1.2.0
 Summary: SWF/ABC toolkit for parsing, analyzing, and manipulating Flash files and AVM2 bytecode
 License: MIT
 Classifier: Development Status :: 5 - Production/Stable
@@ -26,6 +26,14 @@ Parse, analyze, and manipulate Adobe Flash SWF files and AVM2 bytecode.
 ## Install
 
 ```bash
+pip install pyflashkit
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/bitalizer/pyflashkit.git
+cd pyflashkit
 pip install -e .
 ```
 
@@ -48,9 +56,7 @@ print(player.interfaces)    # ["IDisposable", "ITickable"]
 print(player.fields[0].name, player.fields[0].type_name)  # "mHealth", "Number"
 
 # Search strings used in bytecode
-from flashkit.analysis import StringIndex
-strings = StringIndex.from_workspace(ws)
-for s in strings.search("config"):
+for s in ws.search_strings("config"):
     print(s)
 ```
 
@@ -149,6 +155,15 @@ flashkit callees app.swf PlayerManager.init
 flashkit refs app.swf Point
 ```
 
+### `flashkit fields`
+
+```bash
+flashkit fields app.swf PlayerManager              # field access summary (R/W counts)
+flashkit fields app.swf PlayerManager -c            # constructor assignments in order
+flashkit fields app.swf PlayerManager -f mHealth    # who reads/writes a specific field
+flashkit fields app.swf PlayerManager -m takeDamage # what fields a method accesses
+```
+
 ### `flashkit packages` / `flashkit extract` / `flashkit build`
 
 ```bash
@@ -182,24 +197,44 @@ ws.find_classes(extends="Sprite")
 ws.find_classes(package="com.example", is_interface=True)
 ```
 
-### Analysis
-
-```python
-from flashkit.analysis import InheritanceGraph, CallGraph, StringIndex
-
-graph = InheritanceGraph.from_classes(ws.classes)
-graph.get_children("BaseEntity")
-graph.get_all_parents("MyClass")
-graph.get_implementors("ISerializable")
+### Search and analysis
 
-calls = CallGraph.from_workspace(ws)
-calls.get_callers("toString")
-calls.get_callees("MyClass.init")
+All analysis is accessed directly through the Workspace — no separate imports needed.
 
-strings = StringIndex.from_workspace(ws)
-strings.search("config")
-strings.url_strings()
-strings.classes_using_string("http://example.com")
+```python
+# Inheritance
+ws.get_subclasses("BaseEntity")
+ws.get_descendants("BaseEntity")       # transitive
+ws.get_ancestors("PlayerManager")
+ws.get_implementors("ISerializable")
+
+# Call graph
+ws.callers("toString")
+ws.callees("PlayerManager.init")
+
+# References
+ws.references_to("Point")
+ws.references_from("PlayerManager")
+ws.find_instantiators("Point")
+ws.find_type_users("ByteArray")
+
+# Strings
+ws.search_strings("config")
+ws.classes_using_string("http://example.com")
+ws.strings_in_class("PlayerManager")
+
+# Field access
+ws.field_writers("PlayerManager", "mHealth")
+ws.field_readers("PlayerManager", "mHealth")
+ws.fields_written_by("PlayerManager", "takeDamage")
+ws.fields_read_by("PlayerManager", "takeDamage")
+ws.constructor_assignments("PlayerManager")
+ws.field_access_summary("PlayerManager")
+
+# Structural
+ws.find_classes_with_field_type("ByteArray")
+ws.find_methods(return_type="String", name="get")
+ws.find_fields(type_name="int")
 ```
 
 <details>
@@ -267,8 +302,7 @@ flashkit/
   abc/           AVM2 bytecode (parse, write, disasm, builder)
   info/          Resolved class model (ClassInfo, FieldInfo, MethodInfo)
   workspace/     File loading and class index
-  analysis/      Inheritance, call graph, references, strings
-  search/        Unified query engine
+  analysis/      Inheritance, call graph, references, strings, field access
 ```
 
 ## References

{pyflashkit-1.0.0 → pyflashkit-1.2.0}/README.md

@@ -5,6 +5,14 @@ Parse, analyze, and manipulate Adobe Flash SWF files and AVM2 bytecode.
 ## Install
 
 ```bash
+pip install pyflashkit
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/bitalizer/pyflashkit.git
+cd pyflashkit
 pip install -e .
 ```
 
@@ -27,9 +35,7 @@ print(player.interfaces)    # ["IDisposable", "ITickable"]
 print(player.fields[0].name, player.fields[0].type_name)  # "mHealth", "Number"
 
 # Search strings used in bytecode
-from flashkit.analysis import StringIndex
-strings = StringIndex.from_workspace(ws)
-for s in strings.search("config"):
+for s in ws.search_strings("config"):
     print(s)
 ```
 
@@ -128,6 +134,15 @@ flashkit callees app.swf PlayerManager.init
 flashkit refs app.swf Point
 ```
 
+### `flashkit fields`
+
+```bash
+flashkit fields app.swf PlayerManager              # field access summary (R/W counts)
+flashkit fields app.swf PlayerManager -c            # constructor assignments in order
+flashkit fields app.swf PlayerManager -f mHealth    # who reads/writes a specific field
+flashkit fields app.swf PlayerManager -m takeDamage # what fields a method accesses
+```
+
 ### `flashkit packages` / `flashkit extract` / `flashkit build`
 
 ```bash
@@ -161,24 +176,44 @@ ws.find_classes(extends="Sprite")
 ws.find_classes(package="com.example", is_interface=True)
 ```
 
-### Analysis
-
-```python
-from flashkit.analysis import InheritanceGraph, CallGraph, StringIndex
-
-graph = InheritanceGraph.from_classes(ws.classes)
-graph.get_children("BaseEntity")
-graph.get_all_parents("MyClass")
-graph.get_implementors("ISerializable")
+### Search and analysis
 
-calls = CallGraph.from_workspace(ws)
-calls.get_callers("toString")
-calls.get_callees("MyClass.init")
+All analysis is accessed directly through the Workspace — no separate imports needed.
 
-strings = StringIndex.from_workspace(ws)
-strings.search("config")
-strings.url_strings()
-strings.classes_using_string("http://example.com")
+```python
+# Inheritance
+ws.get_subclasses("BaseEntity")
+ws.get_descendants("BaseEntity")       # transitive
+ws.get_ancestors("PlayerManager")
+ws.get_implementors("ISerializable")
+
+# Call graph
+ws.callers("toString")
+ws.callees("PlayerManager.init")
+
+# References
+ws.references_to("Point")
+ws.references_from("PlayerManager")
+ws.find_instantiators("Point")
+ws.find_type_users("ByteArray")
+
+# Strings
+ws.search_strings("config")
+ws.classes_using_string("http://example.com")
+ws.strings_in_class("PlayerManager")
+
+# Field access
+ws.field_writers("PlayerManager", "mHealth")
+ws.field_readers("PlayerManager", "mHealth")
+ws.fields_written_by("PlayerManager", "takeDamage")
+ws.fields_read_by("PlayerManager", "takeDamage")
+ws.constructor_assignments("PlayerManager")
+ws.field_access_summary("PlayerManager")
+
+# Structural
+ws.find_classes_with_field_type("ByteArray")
+ws.find_methods(return_type="String", name="get")
+ws.find_fields(type_name="int")
 ```
 
 <details>
@@ -246,8 +281,7 @@ flashkit/
   abc/           AVM2 bytecode (parse, write, disasm, builder)
   info/          Resolved class model (ClassInfo, FieldInfo, MethodInfo)
   workspace/     File loading and class index
-  analysis/      Inheritance, call graph, references, strings
-  search/        Unified query engine
+  analysis/      Inheritance, call graph, references, strings, field access
 ```
 
 ## References

{pyflashkit-1.0.0 → pyflashkit-1.2.0}/flashkit/__init__.py

@@ -12,8 +12,6 @@ Packages:
     info: Rich resolved model (ClassInfo, FieldInfo, MethodInfo).
     workspace: Loaded binary workspace (SWF/SWZ resources).
     analysis: Inheritance graph, call graph, references, strings.
-    search: Query engine for workspace content.
-
 Quick start::
 
     from flashkit import parse_swf, parse_abc, serialize_abc
@@ -23,7 +21,7 @@ Quick start::
     output = serialize_abc(abc)
 """
 
-__version__ = "1.0.0"
+__version__ = "1.2.0"
 
 from .errors import (
     FlashkitError, ParseError, SWFParseError,
@@ -34,6 +32,8 @@ from .swf.builder import rebuild_swf, make_doabc2_tag
 from .abc.parser import parse_abc
 from .abc.writer import serialize_abc
 from .abc.types import AbcFile
+from .workspace.workspace import Workspace
+from .info.class_info import ClassInfo
 
 __all__ = [
     "__version__",
@@ -51,4 +51,6 @@ __all__ = [
     "parse_abc",
     "serialize_abc",
     "AbcFile",
+    "Workspace",
+    "ClassInfo",
 ]

{pyflashkit-1.0.0 → pyflashkit-1.2.0}/flashkit/abc/__init__.py

@@ -41,7 +41,7 @@ from .parser import (
     read_d64,
 )
 from .writer import serialize_abc
-from .disasm import Instruction, decode_instructions
+from .disasm import Instruction, ResolvedInstruction, decode_instructions, resolve_instructions, scan_relevant_opcodes
 from .builder import AbcBuilder
 
 __all__ = [
@@ -73,7 +73,10 @@ __all__ = [
     "serialize_abc",
     # Disassembler
     "Instruction",
+    "ResolvedInstruction",
     "decode_instructions",
+    "resolve_instructions",
+    "scan_relevant_opcodes",
     # Builder
     "AbcBuilder",
 ]

{pyflashkit-1.0.0 → pyflashkit-1.2.0}/flashkit/abc/builder.py

@@ -311,6 +311,25 @@ class AbcBuilder:
             kind=CONSTANT_RTQName, name=name))
         return idx
 
+    def typename(self, base: int, params: list[int]) -> int:
+        """Add a TypeName (parameterized type) multiname, e.g. Vector.<int>.
+
+        Args:
+            base: Multiname pool index for the base type (e.g. Vector).
+            params: List of multiname pool indices for type parameters.
+
+        Returns:
+            Multiname pool index.
+        """
+        param_bytes = bytearray()
+        for p in params:
+            param_bytes += write_u30(p)
+        idx = len(self._multiname_pool)
+        self._multiname_pool.append(MultinameInfo(
+            kind=CONSTANT_TypeName, ns=base, name=len(params),
+            data=bytes(param_bytes)))
+        return idx
+
     # ── Methods ────────────────────────────────────────────────────────
 
     def method(

{pyflashkit-1.0.0 → pyflashkit-1.2.0}/flashkit/abc/disasm.py

@@ -25,7 +25,7 @@ from .constants import *
 log = logging.getLogger(__name__)
 
 
-@dataclass
+@dataclass(slots=True)
 class Instruction:
     """A single decoded AVM2 instruction.
 
@@ -43,6 +43,24 @@ class Instruction:
     size: int = 1
 
 
+@dataclass(slots=True)
+class ResolvedInstruction:
+    """An AVM2 instruction with operands resolved to readable names.
+
+    Created by ``resolve_instructions()`` from raw ``Instruction`` objects.
+    Multiname indices become class/field/method names, string indices become
+    quoted literals, int/uint/double indices become numeric values.
+
+    Attributes:
+        offset: Byte offset in the method body.
+        mnemonic: Opcode name (e.g. ``"getproperty"``).
+        operands: Human-readable operand strings.
+    """
+    offset: int
+    mnemonic: str
+    operands: list[str] = field(default_factory=list)
+
+
 # ── Opcode table ────────────────────────────────────────────────────────────
 # Maps opcode → (mnemonic, operand_format)
 # Operand formats:
@@ -275,6 +293,116 @@ def _build_lookup() -> dict[int, tuple[str, str]]:
 _LOOKUP = _build_lookup()
 
 
+# ── Fast operand-format table for the lightweight scanner ──────────────────
+# Maps every known opcode to an integer encoding its operand format:
+#   0 = none, 1 = u8, 2 = u30, 3 = u30u30, 4 = s24, 5 = lookupswitch, 6 = debug
+_FMT_CODE = {"": 0, "u8": 1, "u30": 2, "u30u30": 3, "s24": 4, "u30u8": 3}
+
+def _build_skip_table() -> list[int]:
+    """Build a 256-entry table: opcode → operand format code.
+
+    Unknown opcodes get format code 0xFF (sentinel for "stop scanning").
+    """
+    tbl = [0xFF] * 256
+    for op, (_, fmt) in _LOOKUP.items():
+        if fmt == "special":
+            # OP_lookupswitch=5, OP_debug=6
+            tbl[op] = 5 if op == OP_lookupswitch else 6
+        else:
+            tbl[op] = _FMT_CODE.get(fmt, 0)
+    return tbl
+
+_SKIP_TABLE = _build_skip_table()
+
+
+def _skip_u30(data: bytes, off: int) -> int:
+    """Advance past a u30 without decoding its value."""
+    for _ in range(5):
+        if (data[off] & 0x80) == 0:
+            return off + 1
+        off += 1
+    return off
+
+
+def scan_relevant_opcodes(
+    code: bytes,
+    opcodes: frozenset[int],
+) -> list[tuple[int, int, int]]:
+    """Lightweight bytecode scanner that only decodes opcodes of interest.
+
+    Walks the bytecode stream, skipping operands for irrelevant opcodes
+    via a precomputed table lookup. For opcodes in *opcodes*, decodes
+    the first u30 operand and records the hit.
+
+    This avoids creating Instruction objects, mnemonic strings, and
+    operand lists for the vast majority of instructions.
+
+    Args:
+        code: Raw bytecode bytes (from MethodBodyInfo.code).
+        opcodes: Set of opcode values to capture.
+
+    Returns:
+        List of ``(offset, opcode, first_operand)`` tuples for matched
+        instructions. The first operand is always the first u30 in the
+        instruction's operand stream (valid for u30 and u30u30 formats).
+    """
+    results: list[tuple[int, int, int]] = []
+    off = 0
+    code_len = len(code)
+    skip_table = _SKIP_TABLE
+
+    while off < code_len:
+        start = off
+        op = code[off]
+        off += 1
+        fmt = skip_table[op]
+
+        if op in opcodes:
+            # All relevant opcodes have u30 or u30u30 format — decode first u30
+            try:
+                val, off = read_u30(code, off)
+            except (IndexError, ValueError):
+                break
+            results.append((start, op, val))
+            # If u30u30, skip the second u30
+            if fmt == 3:
+                try:
+                    off = _skip_u30(code, off)
+                except IndexError:
+                    break
+            continue
+
+        # Skip operands for irrelevant opcodes
+        try:
+            if fmt == 0:       # no operands
+                pass
+            elif fmt == 1:     # u8
+                off += 1
+            elif fmt == 2:     # u30
+                off = _skip_u30(code, off)
+            elif fmt == 3:     # u30u30
+                off = _skip_u30(code, off)
+                off = _skip_u30(code, off)
+            elif fmt == 4:     # s24
+                off += 3
+            elif fmt == 5:     # lookupswitch
+                off += 3  # default s24
+                case_count, off = read_u30(code, off)
+                off += (case_count + 1) * 3  # case s24s
+            elif fmt == 6:     # debug
+                off += 1  # debug_type u8
+                off = _skip_u30(code, off)  # index u30
+                off += 1  # reg u8
+                off = _skip_u30(code, off)  # extra u30
+            else:
+                # Unknown opcode — can't determine size, bail out
+                break
+        except (IndexError, ValueError):
+            break
+
+    return results
+
+
 def decode_instructions(code: bytes,
                         strict: bool = False) -> list[Instruction]:
     """Decode an AVM2 bytecode stream into a list of instructions.
@@ -362,3 +490,109 @@ def decode_instructions(code: bytes,
             operands=operands, size=off - start))
 
     return instructions
+
+
+# ── Opcodes grouped by operand resolution type ─────────────────────────────
+# First operand is a multiname pool index
+_MULTINAME_FIRST = frozenset({
+    OP_getproperty, OP_setproperty, OP_initproperty,
+    OP_getlex, OP_findpropstrict,
+    OP_callproperty, OP_callpropvoid, OP_constructprop,
+    OP_coerce,
+    # Extra opcodes (from _EXTRA_OPCODES)
+    0x04,  # getsuper
+    0x05,  # setsuper
+    0x5E,  # findproperty
+    0x45,  # callsuper
+    0x4C,  # callproplex
+    0x4E,  # callsupervoid
+    0x59,  # getdescendants
+    0x6A,  # deleteproperty
+    0x80,  # coerce
+    0x86,  # astype
+    0xB2,  # istype
+})
+
+# First operand is a string pool index
+_STRING_FIRST = frozenset({OP_pushstring})
+
+# First operand is an int pool index
+_INT_FIRST = frozenset({OP_pushint})
+
+# First operand is a uint pool index
+_UINT_FIRST = frozenset({OP_pushuint})
+
+# First operand is a double pool index
+_DOUBLE_FIRST = frozenset({OP_pushdouble})
+
+
+def resolve_instructions(
+    abc: "AbcFile",
+    instructions: list[Instruction],
+) -> list[ResolvedInstruction]:
+    """Resolve raw instruction operands to human-readable strings.
+
+    Multiname indices become names, string indices become quoted strings,
+    int/uint/double indices become literal values. Everything else stays
+    as raw numbers.
+
+    Args:
+        abc: The AbcFile for constant pool lookups.
+        instructions: Raw decoded instructions.
+
+    Returns:
+        List of ResolvedInstruction with string operands.
+    """
+    from .types import AbcFile as _AbcFile  # noqa: F811
+    from ..info.member_info import resolve_multiname
+
+    resolved = []
+    for instr in instructions:
+        ops: list[str] = []
+        op = instr.opcode
+
+        for i, val in enumerate(instr.operands):
+            if i == 0 and op in _MULTINAME_FIRST:
+                try:
+                    ops.append(resolve_multiname(abc, val))
+                except (IndexError, KeyError):
+                    ops.append(f"multiname[{val}]")
+            elif i == 0 and op in _STRING_FIRST:
+                if 0 < val < len(abc.string_pool):
+                    ops.append(f'"{abc.string_pool[val]}"')
+                else:
+                    ops.append(f"string[{val}]")
+            elif i == 0 and op in _INT_FIRST:
+                if 0 < val < len(abc.int_pool):
+                    ops.append(str(abc.int_pool[val]))
+                else:
+                    ops.append(f"int[{val}]")
+            elif i == 0 and op in _UINT_FIRST:
+                if 0 < val < len(abc.uint_pool):
+                    ops.append(str(abc.uint_pool[val]))
+                else:
+                    ops.append(f"uint[{val}]")
+            elif i == 0 and op in _DOUBLE_FIRST:
+                if 0 < val < len(abc.double_pool):
+                    ops.append(str(abc.double_pool[val]))
+                else:
+                    ops.append(f"double[{val}]")
+            elif i == 0 and op == OP_newclass:
+                # val = class index
+                if 0 <= val < len(abc.instances):
+                    try:
+                        ops.append(resolve_multiname(abc, abc.instances[val].name))
+                    except (IndexError, KeyError):
+                        ops.append(f"class[{val}]")
+                else:
+                    ops.append(f"class[{val}]")
+            else:
+                ops.append(str(val))
+
+        resolved.append(ResolvedInstruction(
+            offset=instr.offset,
+            mnemonic=instr.mnemonic,
+            operands=ops,
+        ))
+
+    return resolved

{pyflashkit-1.0.0 → pyflashkit-1.2.0}/flashkit/abc/types.py

@@ -16,7 +16,7 @@ from __future__ import annotations
 from dataclasses import dataclass, field
 
 
-@dataclass
+@dataclass(slots=True)
 class NamespaceInfo:
     """A namespace entry in the constant pool.
 
@@ -28,7 +28,7 @@ class NamespaceInfo:
     name: int
 
 
-@dataclass
+@dataclass(slots=True)
 class NsSetInfo:
     """A namespace set — an unordered collection of namespaces.
 
@@ -40,7 +40,7 @@ class NsSetInfo:
     namespaces: list[int]
 
 
-@dataclass
+@dataclass(slots=True)
 class MultinameInfo:
     """A multiname entry in the constant pool.
 
@@ -71,7 +71,7 @@ class MultinameInfo:
     ns_set: int = 0
 
 
-@dataclass
+@dataclass(slots=True)
 class MethodInfo:
     """A method signature (not the body — see MethodBodyInfo).
 
@@ -93,7 +93,7 @@ class MethodInfo:
     param_names: list[int] = field(default_factory=list)
 
 
-@dataclass
+@dataclass(slots=True)
 class MetadataInfo:
     """Metadata attached to traits (e.g. [SWF(width=800)]).
 
@@ -105,7 +105,7 @@ class MetadataInfo:
     items: list[tuple]
 
 
-@dataclass
+@dataclass(slots=True)
 class TraitInfo:
     """A trait (field, method, getter, setter, class, or const) on a class or script.
 
@@ -127,7 +127,7 @@ class TraitInfo:
     data: bytes
 
 
-@dataclass
+@dataclass(slots=True)
 class InstanceInfo:
     """An instance (non-static side) of a class definition.
 
@@ -152,7 +152,7 @@ class InstanceInfo:
     traits: list[TraitInfo] = field(default_factory=list)
 
 
-@dataclass
+@dataclass(slots=True)
 class ClassInfo:
     """The static side of a class definition.
 
@@ -166,7 +166,7 @@ class ClassInfo:
     traits: list[TraitInfo] = field(default_factory=list)
 
 
-@dataclass
+@dataclass(slots=True)
 class ScriptInfo:
     """A script entry point.
 
@@ -180,7 +180,7 @@ class ScriptInfo:
     traits: list[TraitInfo] = field(default_factory=list)
 
 
-@dataclass
+@dataclass(slots=True)
 class ExceptionInfo:
     """An exception handler within a method body.
 
@@ -198,7 +198,7 @@ class ExceptionInfo:
     var_name: int
 
 
-@dataclass
+@dataclass(slots=True)
 class MethodBodyInfo:
     """The bytecode body of a method.
 
@@ -222,7 +222,7 @@ class MethodBodyInfo:
     traits: list[TraitInfo] = field(default_factory=list)
 
 
-@dataclass
+@dataclass(slots=True)
 class AbcFile:
     """A complete ABC (ActionScript Byte Code) file.