pyflashkit 1.1.0__tar.gz → 1.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyflashkit
-Version: 1.1.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

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

@@ -21,7 +21,7 @@ Quick start::
     output = serialize_abc(abc)
 """
 
-__version__ = "1.1.0"
+__version__ = "1.2.0"
 
 from .errors import (
     FlashkitError, ParseError, SWFParseError,
@@ -32,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__",
@@ -49,4 +51,6 @@ __all__ = [
     "parse_abc",
     "serialize_abc",
     "AbcFile",
+    "Workspace",
+    "ClassInfo",
 ]

{pyflashkit-1.1.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, scan_relevant_opcodes
+from .disasm import Instruction, ResolvedInstruction, decode_instructions, resolve_instructions, scan_relevant_opcodes
 from .builder import AbcBuilder
 
 __all__ = [
@@ -73,7 +73,9 @@ __all__ = [
     "serialize_abc",
     # Disassembler
     "Instruction",
+    "ResolvedInstruction",
     "decode_instructions",
+    "resolve_instructions",
     "scan_relevant_opcodes",
     # Builder
     "AbcBuilder",

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

@@ -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:
@@ -472,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.1.0 → pyflashkit-1.2.0}/flashkit/analysis/__init__.py

@@ -11,6 +11,8 @@ Modules:
     references: ReferenceIndex — cross-references (field types, instantiations, imports).
     strings: StringIndex — string constant search and classification.
     field_access: FieldAccessIndex — field read/write tracking from bytecode.
+    method_fingerprint: MethodFingerprint — structural features of method bodies.
+    class_graph: ClassGraph — class-to-class reference graph with typed edges.
 """
 
 from .inheritance import InheritanceGraph
@@ -18,6 +20,18 @@ from .call_graph import CallGraph, CallEdge
 from .references import ReferenceIndex, Reference
 from .strings import StringIndex, StringUsage
 from .field_access import FieldAccessIndex, FieldAccess
+from .method_fingerprint import (
+    MethodFingerprint,
+    extract_fingerprint,
+    extract_constructor_fingerprint,
+    extract_all_fingerprints,
+)
+from .class_graph import (
+    ClassGraph,
+    ClassNode,
+    FRAMEWORK_TYPES,
+    CLASS_EDGE_KINDS,
+)
 from .unified import build_all_indexes
 
 __all__ = [
@@ -30,5 +44,13 @@ __all__ = [
     "StringUsage",
     "FieldAccessIndex",
     "FieldAccess",
+    "MethodFingerprint",
+    "extract_fingerprint",
+    "extract_constructor_fingerprint",
+    "extract_all_fingerprints",
+    "ClassGraph",
+    "ClassNode",
+    "FRAMEWORK_TYPES",
+    "CLASS_EDGE_KINDS",
     "build_all_indexes",
 ]

{pyflashkit-1.1.0 → pyflashkit-1.2.0}/flashkit/analysis/call_graph.py

@@ -22,6 +22,10 @@ from __future__ import annotations
 
 from dataclasses import dataclass, field
 from collections import defaultdict
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..workspace.workspace import Workspace
 
 from ..abc.types import AbcFile
 from ..abc.disasm import scan_relevant_opcodes
@@ -115,7 +119,7 @@ class CallGraph:
         default_factory=lambda: defaultdict(list))
 
     @classmethod
-    def from_workspace(cls, workspace: object) -> CallGraph:
+    def from_workspace(cls, workspace: Workspace) -> CallGraph:
         """Build a CallGraph from a Workspace.
 
         Iterates all ABC blocks and their method bodies, decodes

pyflashkit-1.2.0/flashkit/analysis/class_graph.py

@@ -0,0 +1,270 @@
+"""Class-reference graph built from a Workspace.
+
+Wraps ``ReferenceIndex`` into a per-class adjacency structure with typed
+edges and per-node intrinsic features. Each user-defined class becomes a
+node; each cross-reference between two user-defined classes becomes a
+directed, typed edge.
+
+Edges to framework/builtin types (Sprite, Event, Array, etc.) are
+filtered out — they add noise without structural information. Strings
+are collected per class in ``string_pool`` and indexed globally in
+``ClassGraph.string_to_classes`` for quick reverse lookups.
+
+Each node also carries method fingerprints
+(see :mod:`flashkit.analysis.method_fingerprint`) so downstream code can
+reason about method shapes without re-walking the ABC.
+
+Typical usage::
+
+    from flashkit.workspace import Workspace
+    from flashkit.analysis import ClassGraph
+
+    ws = Workspace()
+    ws.load_swf("game.swf")
+    g = ClassGraph.from_workspace(ws)
+
+    node = g.nodes["PlayerController"]
+    print(node.out_degree_by_kind)          # {'call': 12, 'field_type': 3, ...}
+    print(len(node.method_fps), "methods fingerprinted")
+    print(g.string_to_classes["Hello"])     # which classes reference "Hello"
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..workspace.workspace import Workspace
+
+from .references import ReferenceIndex
+from .method_fingerprint import (
+    BUILTIN_TYPES,
+    MethodFingerprint,
+    extract_all_fingerprints,
+)
+
+
+__all__ = [
+    "FRAMEWORK_TYPES",
+    "CLASS_EDGE_KINDS",
+    "ClassNode",
+    "ClassGraph",
+]
+
+
+# Framework types filtered out of class-to-class edges. These are Flash
+# Player runtime / AS3 builtins; references to them aren't meaningful
+# when comparing user-defined class structure.
+FRAMEWORK_TYPES: frozenset[str] = frozenset({
+    "int", "uint", "Number", "String", "Boolean", "void", "Object",
+    "Array", "Class", "Function", "*", "Namespace", "QName",
+    "ByteArray", "Dictionary", "Date", "RegExp", "Error", "XML",
+    "XMLList",
+    # Display list
+    "Sprite", "MovieClip", "DisplayObject", "DisplayObjectContainer",
+    "BitmapData", "Bitmap", "Shape", "TextField", "TextFormat",
+    # Events
+    "Event", "EventDispatcher", "MouseEvent", "KeyboardEvent",
+    "TimerEvent", "IOErrorEvent", "SecurityErrorEvent", "ProgressEvent",
+    # Geometry
+    "Point", "Rectangle", "Matrix", "ColorTransform",
+    # Audio
+    "Sound", "SoundChannel", "SoundTransform",
+    # Network / IO
+    "URLRequest", "URLLoader", "SharedObject", "Socket",
+    # Misc
+    "Timer", "Stage", "Loader", "LoaderInfo", "NetConnection",
+    "Vector", "BlendMode",
+})
+
+# Edge kinds that represent class-to-class relationships.
+CLASS_EDGE_KINDS: frozenset[str] = frozenset({
+    "extends", "implements",
+    "field_type", "param_type", "return_type",
+    "call", "instantiation", "class_ref", "coerce",
+})
+
+
+def _normalize_super(super_name: str) -> str:
+    """Keep the super name if it's a known builtin, else collapse to '?'."""
+    if super_name in BUILTIN_TYPES:
+        return super_name
+    return "?"
+
+
+@dataclass
+class ClassNode:
+    """One node per class in the graph.
+
+    Stores intrinsic features (counts, flags) plus typed directed edges
+    to/from other ``ClassNode``s in the same graph.
+
+    Attributes:
+        name: Simple class name.
+        package: Package / namespace string (empty for default package).
+        method_count: Number of instance methods, getters, setters.
+        static_method_count: Number of static methods.
+        field_count: Number of instance fields.
+        static_field_count: Number of static fields.
+        super_name: Superclass name, normalized — builtins preserved,
+            user classes collapsed to ``"?"``.
+        is_interface: Whether the class is an interface.
+        is_sealed: Whether the class is sealed (no dynamic properties).
+        out_edges: ``(target_name, edge_kind)`` pairs for outgoing refs.
+        in_edges: ``(source_name, edge_kind)`` pairs for incoming refs.
+        out_degree_by_kind: Per-kind outgoing edge counts.
+        in_degree_by_kind: Per-kind incoming edge counts.
+        string_pool: String constants referenced by this class.
+        method_fps: Method fingerprints for all methods + constructor.
+        total_code_size: Sum of bytecode sizes across all fingerprints.
+    """
+
+    name: str = ""
+    package: str = ""
+
+    method_count: int = 0
+    static_method_count: int = 0
+    field_count: int = 0
+    static_field_count: int = 0
+    super_name: str = "?"
+    is_interface: bool = False
+    is_sealed: bool = False
+
+    out_edges: list[tuple[str, str]] = field(default_factory=list)
+    in_edges: list[tuple[str, str]] = field(default_factory=list)
+    out_degree_by_kind: dict[str, int] = field(
+        default_factory=lambda: defaultdict(int))
+    in_degree_by_kind: dict[str, int] = field(
+        default_factory=lambda: defaultdict(int))
+
+    string_pool: frozenset[str] = field(default_factory=frozenset)
+
+    method_fps: list[MethodFingerprint] = field(default_factory=list)
+    total_code_size: int = 0
+
+
+@dataclass
+class ClassGraph:
+    """Directed graph of class-to-class references with typed edges.
+
+    Nodes are keyed by simple class name (not qualified).
+
+    Attributes:
+        nodes: Simple class name → :class:`ClassNode`.
+        string_to_classes: Reverse index — string literal → set of
+            class names that reference that string.
+    """
+
+    nodes: dict[str, ClassNode] = field(default_factory=dict)
+    string_to_classes: dict[str, set[str]] = field(
+        default_factory=lambda: defaultdict(set))
+
+    def total_degree(self, name: str) -> int:
+        """Total degree (in + out) for a node, or 0 if the node is absent."""
+        node = self.nodes.get(name)
+        if node is None:
+            return 0
+        return len(node.out_edges) + len(node.in_edges)
+
+    @classmethod
+    def from_workspace(cls, workspace: Workspace) -> ClassGraph:
+        """Build a :class:`ClassGraph` from a loaded :class:`Workspace`.
+
+        Walks every class in the workspace, creates a node with intrinsic
+        features, then follows its references to populate typed edges to
+        other user-defined classes. Framework/builtin targets and
+        self-references are filtered out. Finally, method fingerprints are
+        extracted for every class.
+
+        Args:
+            workspace: A :class:`flashkit.workspace.Workspace` with at least
+                one loaded SWF.
+
+        Returns:
+            A fully populated :class:`ClassGraph`.
+        """
+        ref_index = ReferenceIndex.from_workspace(workspace)
+
+        # Map qualified + simple names → simple name for edge resolution.
+        all_class_names: set[str] = set()
+        qname_to_name: dict[str, str] = {}
+        for info in workspace.classes:
+            all_class_names.add(info.name)
+            qname_to_name[info.qualified_name] = info.name
+            qname_to_name[info.name] = info.name
+
+        graph = cls()
+
+        # Step 1: create nodes with intrinsic features.
+        for info in workspace.classes:
+            node = ClassNode(
+                name=info.name,
+                package=info.package,
+                method_count=len(info.methods),
+                static_method_count=len(info.static_methods),
+                field_count=len(info.fields),
+                static_field_count=len(info.static_fields),
+                super_name=_normalize_super(info.super_name),
+                is_interface=info.is_interface,
+                is_sealed=info.is_sealed,
+            )
+            graph.nodes[info.name] = node
+
+        # Step 2: walk references to build edges + string pools.
+        class_strings: dict[str, set[str]] = defaultdict(set)
+
+        for info in workspace.classes:
+            refs = ref_index.references_from(info.qualified_name)
+            node = graph.nodes[info.name]
+
+            for ref in refs:
+                if ref.ref_kind == "string_use":
+                    class_strings[info.name].add(ref.target)
+                    graph.string_to_classes[ref.target].add(info.name)
+                    continue
+
+                if ref.ref_kind not in CLASS_EDGE_KINDS:
+                    continue
+
+                target_name = qname_to_name.get(ref.target)
+                if target_name is None:
+                    if ref.target in all_class_names:
+                        target_name = ref.target
+                    else:
+                        continue
+
+                if target_name in FRAMEWORK_TYPES:
+                    continue
+                if target_name == info.name:
+                    continue
+
+                edge = (target_name, ref.ref_kind)
+                node.out_edges.append(edge)
+                node.out_degree_by_kind[ref.ref_kind] += 1
+
+                target_node = graph.nodes.get(target_name)
+                if target_node is not None:
+                    target_node.in_edges.append((info.name, ref.ref_kind))
+                    target_node.in_degree_by_kind[ref.ref_kind] += 1
+
+        for cls_name, strings in class_strings.items():
+            node = graph.nodes.get(cls_name)
+            if node is not None:
+                node.string_pool = frozenset(strings)
+
+        # Step 3: extract method fingerprints for each class.
+        for info in workspace.classes:
+            node = graph.nodes.get(info.name)
+            if node is None:
+                continue
+            try:
+                abc = info.abc
+            except RuntimeError:
+                continue
+            fps = extract_all_fingerprints(info, abc)
+            node.method_fps = fps
+            node.total_code_size = sum(fp.code_size for fp in fps)
+
+        return graph

{pyflashkit-1.1.0 → pyflashkit-1.2.0}/flashkit/analysis/field_access.py

@@ -23,6 +23,10 @@ from __future__ import annotations
 
 from dataclasses import dataclass, field
 from collections import defaultdict
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..workspace.workspace import Workspace
 
 from ..abc.types import AbcFile
 from ..abc.disasm import scan_relevant_opcodes
@@ -91,7 +95,7 @@ class FieldAccessIndex:
         self.by_class[access.class_name].append(access)
 
     @classmethod
-    def from_workspace(cls, workspace: object) -> FieldAccessIndex:
+    def from_workspace(cls, workspace: Workspace) -> FieldAccessIndex:
         """Build a FieldAccessIndex from a Workspace.
 
         Walks all method bodies, decodes instructions, and collects
@@ -103,8 +107,7 @@ class FieldAccessIndex:
         Returns:
             Populated FieldAccessIndex.
         """
-        from ..workspace.workspace import Workspace
-        ws: Workspace = workspace  # type: ignore[assignment]
+        ws = workspace
 
         index = cls()
         for abc in ws.abc_blocks:

{pyflashkit-1.1.0 → pyflashkit-1.2.0}/flashkit/analysis/inheritance.py

@@ -21,11 +21,15 @@ Usage::
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
 from dataclasses import dataclass, field
 from collections import defaultdict
 
 from ..info.class_info import ClassInfo
 
+if TYPE_CHECKING:
+    from ..workspace.workspace import Workspace
+
 
 @dataclass(slots=True)
 class InheritanceGraph:
@@ -76,6 +80,20 @@ class InheritanceGraph:
 
         return graph
 
+    @classmethod
+    def from_workspace(cls, workspace: Workspace) -> InheritanceGraph:
+        """Build an InheritanceGraph from a Workspace's loaded classes.
+
+        Equivalent to ``InheritanceGraph.from_classes(workspace.classes)``.
+
+        Args:
+            workspace: Workspace instance with loaded classes.
+
+        Returns:
+            Populated InheritanceGraph.
+        """
+        return cls.from_classes(workspace.classes)
+
     def get_parent(self, name: str) -> str | None:
         """Get the direct superclass of a class.