pyflashkit 1.0.0__py3-none-any.whl

flashkit/analysis/inheritance.py

@@ -0,0 +1,267 @@
+"""
+Inheritance graph for ABC classes.
+
+Builds a directed graph of class inheritance and interface implementation
+from resolved ClassInfo data. Supports ancestor/descendant queries,
+interface implementor lookup, and subclass checks.
+
+Usage::
+
+    from flashkit.workspace import Workspace
+    from flashkit.analysis.inheritance import InheritanceGraph
+
+    ws = Workspace()
+    ws.load_swf("application.swf")
+    graph = InheritanceGraph.from_classes(ws.classes)
+
+    parent = graph.get_parent("MySprite")
+    children = graph.get_children("BaseEntity")
+    implementors = graph.get_implementors("IDisposable")
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from collections import defaultdict
+
+from ..info.class_info import ClassInfo
+
+
+@dataclass
+class InheritanceGraph:
+    """Directed graph of class inheritance and interface relationships.
+
+    Attributes:
+        classes: Map of qualified name → ClassInfo.
+        parent_map: Map of class name → superclass name.
+        children_map: Map of class name → set of direct subclass names.
+        interface_map: Map of class name → set of interface names it implements.
+        implementors_map: Map of interface name → set of class names implementing it.
+    """
+    classes: dict[str, ClassInfo] = field(default_factory=dict)
+    parent_map: dict[str, str] = field(default_factory=dict)
+    children_map: dict[str, set[str]] = field(default_factory=lambda: defaultdict(set))
+    interface_map: dict[str, set[str]] = field(default_factory=lambda: defaultdict(set))
+    implementors_map: dict[str, set[str]] = field(default_factory=lambda: defaultdict(set))
+
+    @classmethod
+    def from_classes(cls, classes: list[ClassInfo]) -> InheritanceGraph:
+        """Build an InheritanceGraph from a list of ClassInfo objects.
+
+        Args:
+            classes: All resolved classes (typically from Workspace.classes).
+
+        Returns:
+            Populated InheritanceGraph.
+        """
+        graph = cls()
+
+        for ci in classes:
+            key = ci.qualified_name
+            graph.classes[key] = ci
+
+            # Parent → child edge
+            if ci.super_name and ci.super_name != "*":
+                super_qualified = (
+                    f"{ci.super_package}.{ci.super_name}"
+                    if ci.super_package else ci.super_name
+                )
+                graph.parent_map[key] = super_qualified
+                graph.children_map[super_qualified].add(key)
+
+            # Interface edges
+            for iface in ci.interfaces:
+                graph.interface_map[key].add(iface)
+                graph.implementors_map[iface].add(key)
+
+        return graph
+
+    def get_parent(self, name: str) -> str | None:
+        """Get the direct superclass of a class.
+
+        Args:
+            name: Class name (simple or qualified).
+
+        Returns:
+            Superclass qualified name, or None if not found / root class.
+        """
+        key = self._resolve_name(name)
+        return self.parent_map.get(key) if key else None
+
+    def get_children(self, name: str) -> list[str]:
+        """Get direct subclasses of a class.
+
+        Args:
+            name: Class name (simple or qualified).
+
+        Returns:
+            List of direct subclass qualified names.
+        """
+        key = self._resolve_name(name)
+        if key is None:
+            return []
+        return sorted(self.children_map.get(key, set()))
+
+    def get_all_parents(self, name: str) -> list[str]:
+        """Get the full ancestor chain (class → superclass → ... → root).
+
+        Args:
+            name: Class name (simple or qualified).
+
+        Returns:
+            List of ancestor qualified names, from immediate parent to root.
+        """
+        key = self._resolve_name(name)
+        if key is None:
+            return []
+        result: list[str] = []
+        visited: set[str] = set()
+        current = key
+        while current in self.parent_map:
+            parent = self.parent_map[current]
+            if parent in visited:
+                break  # circular inheritance guard
+            visited.add(parent)
+            result.append(parent)
+            current = parent
+        return result
+
+    def get_all_children(self, name: str) -> list[str]:
+        """Get all descendants (transitive closure of subclasses).
+
+        Args:
+            name: Class name (simple or qualified).
+
+        Returns:
+            List of all descendant qualified names (breadth-first order).
+        """
+        key = self._resolve_name(name)
+        if key is None:
+            return []
+        result: list[str] = []
+        visited: set[str] = set()
+        queue = [key]
+        while queue:
+            current = queue.pop(0)
+            for child in sorted(self.children_map.get(current, set())):
+                if child not in visited:
+                    visited.add(child)
+                    result.append(child)
+                    queue.append(child)
+        return result
+
+    def get_implementors(self, interface_name: str) -> list[str]:
+        """Get all classes that directly implement an interface.
+
+        Args:
+            interface_name: Interface name (simple or qualified).
+
+        Returns:
+            List of implementing class qualified names.
+        """
+        # Try exact match first, then simple name scan
+        if interface_name in self.implementors_map:
+            return sorted(self.implementors_map[interface_name])
+        # Try matching simple name in the implementors keys
+        for key, impls in self.implementors_map.items():
+            if key == interface_name or key.endswith(f".{interface_name}"):
+                return sorted(impls)
+        return []
+
+    def get_interfaces(self, name: str) -> list[str]:
+        """Get all interfaces directly implemented by a class.
+
+        Args:
+            name: Class name (simple or qualified).
+
+        Returns:
+            List of interface name strings.
+        """
+        key = self._resolve_name(name)
+        if key is None:
+            return []
+        return sorted(self.interface_map.get(key, set()))
+
+    def get_siblings(self, name: str) -> list[str]:
+        """Get classes sharing the same direct parent (excluding self).
+
+        Args:
+            name: Class name (simple or qualified).
+
+        Returns:
+            List of sibling class qualified names.
+        """
+        key = self._resolve_name(name)
+        if key is None:
+            return []
+        parent = self.parent_map.get(key)
+        if parent is None:
+            return []
+        return sorted(c for c in self.children_map.get(parent, set()) if c != key)
+
+    def is_subclass(self, child: str, parent: str) -> bool:
+        """Check if *child* is a (transitive) subclass of *parent*.
+
+        Args:
+            child: Potential subclass name.
+            parent: Potential ancestor name.
+
+        Returns:
+            True if child inherits from parent (directly or transitively).
+        """
+        child_key = self._resolve_name(child)
+        parent_key = self._resolve_name(parent)
+        if child_key is None or parent_key is None:
+            return False
+        ancestors = self.get_all_parents(child_key)
+        return parent_key in ancestors
+
+    def get_roots(self) -> list[str]:
+        """Get all root classes (no superclass in the graph).
+
+        Returns:
+            List of root class qualified names.
+        """
+        roots: list[str] = []
+        for name in self.classes:
+            parent = self.parent_map.get(name)
+            if parent is None or parent not in self.classes:
+                roots.append(name)
+        return sorted(roots)
+
+    def get_depth(self, name: str) -> int:
+        """Get the inheritance depth of a class (0 for roots).
+
+        Args:
+            name: Class name (simple or qualified).
+
+        Returns:
+            Number of ancestors in the graph, or -1 if not found.
+        """
+        key = self._resolve_name(name)
+        if key is None:
+            return -1
+        return len(self.get_all_parents(key))
+
+    def _resolve_name(self, name: str) -> str | None:
+        """Resolve a simple or qualified name to a name known in the graph.
+
+        Checks loaded classes first, then parent/children map keys
+        (for external classes like Object that aren't loaded but appear
+        as superclasses).
+        """
+        # Exact match in loaded classes
+        if name in self.classes:
+            return name
+        # Exact match in external references (parent/child keys)
+        if name in self.children_map or name in self.parent_map:
+            return name
+        # Try simple name match in loaded classes
+        for qname, ci in self.classes.items():
+            if ci.name == name:
+                return qname
+        # Try simple name match in children_map keys (external classes)
+        for key in self.children_map:
+            if key.endswith(f".{name}") or key == name:
+                return key
+        return None

flashkit/analysis/references.py

@@ -0,0 +1,371 @@
+"""
+Cross-reference index for ABC elements.
+
+Builds indexes that answer "where is X used?" questions by scanning
+class traits (field types, method signatures) and method body opcodes.
+
+Usage::
+
+    from flashkit.workspace import Workspace
+    from flashkit.analysis.references import ReferenceIndex
+
+    ws = Workspace()
+    ws.load_swf("application.swf")
+    refs = ReferenceIndex.from_workspace(ws)
+
+    users = refs.field_type_users("int")
+    creators = refs.instantiators("Point")
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from collections import defaultdict
+
+from ..abc.types import AbcFile
+from ..abc.disasm import decode_instructions
+from ..abc.constants import (
+    OP_pushstring, OP_constructprop, OP_callproperty, OP_callpropvoid,
+    OP_getlex, OP_coerce, OP_newclass,
+)
+from ..info.member_info import resolve_multiname, build_method_body_map
+from ..info.class_info import ClassInfo
+
+
+@dataclass
+class Reference:
+    """A single cross-reference entry.
+
+    Attributes:
+        source_class: Qualified name of the class containing this reference.
+        source_member: Member name (method or field) where this reference occurs.
+        target: The referenced name (type name, class name, or string).
+        ref_kind: Category: ``"field_type"``, ``"param_type"``, ``"return_type"``,
+                  ``"instantiation"``, ``"call"``, ``"string_use"``, ``"coerce"``,
+                  ``"class_ref"``.
+        method_index: Method index if this reference is from a method body, else -1.
+        offset: Bytecode offset if from a method body, else -1.
+    """
+    source_class: str
+    source_member: str
+    target: str
+    ref_kind: str
+    method_index: int = -1
+    offset: int = -1
+
+
+@dataclass
+class ReferenceIndex:
+    """Cross-reference index over all classes and method bodies.
+
+    Provides efficient lookup for "where is X used?" queries.
+
+    Attributes:
+        refs: All reference entries.
+        by_target: Map of target name → list of references to it.
+        by_source: Map of source class name → list of references from it.
+    """
+    refs: list[Reference] = field(default_factory=list)
+    by_target: dict[str, list[Reference]] = field(
+        default_factory=lambda: defaultdict(list))
+    by_source: dict[str, list[Reference]] = field(
+        default_factory=lambda: defaultdict(list))
+
+    def _add(self, ref: Reference) -> None:
+        """Add a reference to all indexes."""
+        self.refs.append(ref)
+        self.by_target[ref.target].append(ref)
+        self.by_source[ref.source_class].append(ref)
+
+    @classmethod
+    def from_workspace(cls, workspace: object) -> ReferenceIndex:
+        """Build a ReferenceIndex from a Workspace.
+
+        Scans all class traits and method bodies.
+
+        Args:
+            workspace: A Workspace instance.
+
+        Returns:
+            Populated ReferenceIndex.
+        """
+        from ..workspace.workspace import Workspace
+        ws: Workspace = workspace  # type: ignore[assignment]
+
+        index = cls()
+
+        for ci in ws.classes:
+            index._index_class_traits(ci)
+
+        for abc in ws.abc_blocks:
+            index._index_method_bodies(abc, ws.classes)
+
+        return index
+
+    @classmethod
+    def from_classes_and_abc(cls, classes: list[ClassInfo],
+                             abc_blocks: list[AbcFile]) -> ReferenceIndex:
+        """Build a ReferenceIndex from class and ABC lists directly.
+
+        Args:
+            classes: All resolved ClassInfo objects.
+            abc_blocks: All AbcFile objects.
+
+        Returns:
+            Populated ReferenceIndex.
+        """
+        index = cls()
+        for ci in classes:
+            index._index_class_traits(ci)
+        for abc in abc_blocks:
+            index._index_method_bodies(abc, classes)
+        return index
+
+    def _index_class_traits(self, ci: ClassInfo) -> None:
+        """Index field types, method param types, and return types from a class."""
+        qname = ci.qualified_name
+
+        # Field types (instance + static)
+        for f in ci.all_fields:
+            if f.type_name and f.type_name != "*":
+                self._add(Reference(
+                    source_class=qname,
+                    source_member=f.name,
+                    target=f.type_name,
+                    ref_kind="field_type",
+                ))
+
+        # Method signatures (instance + static)
+        for m in ci.all_methods:
+            # Return type
+            if m.return_type and m.return_type != "*":
+                self._add(Reference(
+                    source_class=qname,
+                    source_member=m.name,
+                    target=m.return_type,
+                    ref_kind="return_type",
+                    method_index=m.method_index,
+                ))
+            # Parameter types
+            for pt in m.param_types:
+                if pt and pt != "*":
+                    self._add(Reference(
+                        source_class=qname,
+                        source_member=m.name,
+                        target=pt,
+                        ref_kind="param_type",
+                        method_index=m.method_index,
+                    ))
+
+        # Superclass reference
+        if ci.super_name and ci.super_name != "*" and ci.super_name != "Object":
+            super_qualified = (
+                f"{ci.super_package}.{ci.super_name}"
+                if ci.super_package else ci.super_name
+            )
+            self._add(Reference(
+                source_class=qname,
+                source_member="<extends>",
+                target=super_qualified,
+                ref_kind="extends",
+            ))
+
+        # Interface references
+        for iface in ci.interfaces:
+            self._add(Reference(
+                source_class=qname,
+                source_member="<implements>",
+                target=iface,
+                ref_kind="implements",
+            ))
+
+    def _index_method_bodies(self, abc: AbcFile,
+                             classes: list[ClassInfo]) -> None:
+        """Index references from method body opcodes."""
+        method_name_map = _build_method_owner_map(abc, classes)
+
+        for body in abc.method_bodies:
+            owner_class = method_name_map.get(body.method, "")
+            method_name = f"method_{body.method}"
+
+            # Find the method name from classes
+            for ci in classes:
+                for m in ci.all_methods:
+                    if m.method_index == body.method:
+                        method_name = m.name
+                        if not owner_class:
+                            owner_class = ci.qualified_name
+                        break
+                if ci.constructor_index == body.method:
+                    method_name = "<init>"
+                    if not owner_class:
+                        owner_class = ci.qualified_name
+
+            try:
+                instructions = decode_instructions(body.code)
+            except Exception:
+                continue
+
+            for instr in instructions:
+                if not instr.operands:
+                    continue
+
+                mn_index = instr.operands[0]
+
+                if instr.opcode == OP_constructprop:
+                    target = resolve_multiname(abc, mn_index)
+                    if target != "*" and not target.startswith("multiname["):
+                        self._add(Reference(
+                            source_class=owner_class,
+                            source_member=method_name,
+                            target=target,
+                            ref_kind="instantiation",
+                            method_index=body.method,
+                            offset=instr.offset,
+                        ))
+
+                elif instr.opcode in (OP_callproperty, OP_callpropvoid):
+                    target = resolve_multiname(abc, mn_index)
+                    if target != "*" and not target.startswith("multiname["):
+                        self._add(Reference(
+                            source_class=owner_class,
+                            source_member=method_name,
+                            target=target,
+                            ref_kind="call",
+                            method_index=body.method,
+                            offset=instr.offset,
+                        ))
+
+                elif instr.opcode == OP_getlex:
+                    target = resolve_multiname(abc, mn_index)
+                    if target != "*" and not target.startswith("multiname["):
+                        self._add(Reference(
+                            source_class=owner_class,
+                            source_member=method_name,
+                            target=target,
+                            ref_kind="class_ref",
+                            method_index=body.method,
+                            offset=instr.offset,
+                        ))
+
+                elif instr.opcode == OP_coerce:
+                    target = resolve_multiname(abc, mn_index)
+                    if target != "*" and not target.startswith("multiname["):
+                        self._add(Reference(
+                            source_class=owner_class,
+                            source_member=method_name,
+                            target=target,
+                            ref_kind="coerce",
+                            method_index=body.method,
+                            offset=instr.offset,
+                        ))
+
+                elif instr.opcode == OP_pushstring:
+                    str_index = instr.operands[0]
+                    if 0 < str_index < len(abc.string_pool):
+                        self._add(Reference(
+                            source_class=owner_class,
+                            source_member=method_name,
+                            target=abc.string_pool[str_index],
+                            ref_kind="string_use",
+                            method_index=body.method,
+                            offset=instr.offset,
+                        ))
+
+    def field_type_users(self, type_name: str) -> list[Reference]:
+        """Find all fields of a given type.
+
+        Args:
+            type_name: The type name to search for.
+
+        Returns:
+            List of references where a field has this type.
+        """
+        return [r for r in self.by_target.get(type_name, [])
+                if r.ref_kind == "field_type"]
+
+    def method_param_users(self, type_name: str) -> list[Reference]:
+        """Find all methods that take a parameter of a given type.
+
+        Args:
+            type_name: The type name to search for.
+
+        Returns:
+            List of references where a method parameter has this type.
+        """
+        return [r for r in self.by_target.get(type_name, [])
+                if r.ref_kind == "param_type"]
+
+    def method_return_users(self, type_name: str) -> list[Reference]:
+        """Find all methods that return a given type.
+
+        Args:
+            type_name: The type name to search for.
+
+        Returns:
+            List of references where a method returns this type.
+        """
+        return [r for r in self.by_target.get(type_name, [])
+                if r.ref_kind == "return_type"]
+
+    def instantiators(self, class_name: str) -> list[Reference]:
+        """Find all places that construct instances of a class.
+
+        Args:
+            class_name: The class being instantiated.
+
+        Returns:
+            List of instantiation references.
+        """
+        return [r for r in self.by_target.get(class_name, [])
+                if r.ref_kind == "instantiation"]
+
+    def string_users(self, string: str) -> list[Reference]:
+        """Find all places that push a specific string constant.
+
+        Args:
+            string: The exact string value.
+
+        Returns:
+            List of string usage references.
+        """
+        return [r for r in self.by_target.get(string, [])
+                if r.ref_kind == "string_use"]
+
+    def references_from(self, class_name: str) -> list[Reference]:
+        """Get all outgoing references from a class.
+
+        Args:
+            class_name: The source class qualified name.
+
+        Returns:
+            All references originating from this class.
+        """
+        return self.by_source.get(class_name, [])
+
+    def references_to(self, target: str) -> list[Reference]:
+        """Get all incoming references to a target.
+
+        Args:
+            target: The target name (type, class, method, or string).
+
+        Returns:
+            All references pointing to this target.
+        """
+        return self.by_target.get(target, [])
+
+    @property
+    def total_refs(self) -> int:
+        return len(self.refs)
+
+
+def _build_method_owner_map(abc: AbcFile,
+                            classes: list[ClassInfo]) -> dict[int, str]:
+    """Map method_index → owning class qualified name."""
+    owner: dict[int, str] = {}
+    for ci in classes:
+        owner[ci.constructor_index] = ci.qualified_name
+        owner[ci.static_init_index] = ci.qualified_name
+        for m in ci.all_methods:
+            owner[m.method_index] = ci.qualified_name
+    return owner