pyflashkit 1.0.0__py3-none-any.whl

flashkit/cli/disasm.py

@@ -0,0 +1,77 @@
+"""``flashkit disasm`` — disassemble method bytecode."""
+
+from __future__ import annotations
+
+import argparse
+
+from ._util import load, bold
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("disasm", help="Disassemble method bytecode")
+    p.add_argument("file", help="SWF or SWZ file")
+    p.add_argument("--class", dest="class_name",
+                   help="Class to disassemble")
+    p.add_argument("--method-index", type=int,
+                   help="Method index to disassemble")
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> None:
+    ws = load(args.file)
+
+    from ..abc.disasm import decode_instructions
+
+    if args.method_index is not None:
+        for abc in ws.abc_blocks:
+            for mb in abc.method_bodies:
+                if mb.method == args.method_index:
+                    print(bold(f"Method {mb.method}") +
+                          f"  (max_stack={mb.max_stack}, "
+                          f"locals={mb.local_count}, "
+                          f"code={len(mb.code)} bytes)")
+                    for instr in decode_instructions(mb.code):
+                        ops = ", ".join(str(o) for o in instr.operands)
+                        print(f"  0x{instr.offset:04X}  "
+                              f"{instr.mnemonic:<24s} {ops}")
+                    return
+        print(f"Method index {args.method_index} not found.")
+        return
+
+    if args.class_name:
+        cls = ws.get_class(args.class_name)
+        if cls is None:
+            matches = ws.find_classes(name=args.class_name)
+            if len(matches) == 1:
+                cls = matches[0]
+            else:
+                print(f"Class '{args.class_name}' not found.")
+                return
+
+        for abc in ws.abc_blocks:
+            method_indices = set()
+            for m in cls.all_methods:
+                method_indices.add(m.method_index)
+            method_indices.add(cls.constructor_index)
+
+            for mb in abc.method_bodies:
+                if mb.method in method_indices:
+                    mname = f"method_{mb.method}"
+                    if mb.method == cls.constructor_index:
+                        mname = f"{cls.name}()"
+                    else:
+                        for m in cls.all_methods:
+                            if m.method_index == mb.method:
+                                mname = m.name
+                                break
+
+                    print(bold(f"{cls.name}.{mname}") +
+                          f"  ({len(mb.code)} bytes)")
+                    for instr in decode_instructions(mb.code):
+                        ops = ", ".join(str(o) for o in instr.operands)
+                        print(f"  0x{instr.offset:04X}  "
+                              f"{instr.mnemonic:<24s} {ops}")
+                    print()
+        return
+
+    print("Specify --class or --method-index.")

flashkit/cli/extract.py

@@ -0,0 +1,36 @@
+"""``flashkit extract`` — extract ABC bytecode from a SWF."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from ._util import load
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("extract", help="Extract ABC blocks from SWF")
+    p.add_argument("file", help="SWF file")
+    p.add_argument("-o", "--output", help="Output directory")
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> None:
+    ws = load(args.file)
+    res = ws.resources[0]
+    out_dir = Path(args.output) if args.output else Path(".")
+
+    if not res.abc_blocks:
+        print("No ABC blocks found.")
+        return
+
+    from ..abc.writer import serialize_abc
+
+    for i, abc in enumerate(res.abc_blocks):
+        raw = serialize_abc(abc)
+        name = f"abc_{i}.abc"
+        dest = out_dir / name
+        dest.write_bytes(raw)
+        print(f"  Wrote {dest} ({len(raw)} bytes)")
+
+    print(f"\nExtracted {len(res.abc_blocks)} ABC block(s)")

flashkit/cli/info.py

@@ -0,0 +1,41 @@
+"""``flashkit info`` — show high-level file summary."""
+
+from __future__ import annotations
+
+import argparse
+
+from ._util import load, bold
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("info", help="Show file summary")
+    p.add_argument("file", help="SWF or SWZ file")
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> None:
+    ws = load(args.file)
+    res = ws.resources[0]
+
+    print(bold(f"File: {res.path}"))
+    print(f"  Format:     {res.kind.upper()}")
+    if res.swf_version is not None:
+        print(f"  SWF version: {res.swf_version}")
+    if res.swf_tags is not None:
+        print(f"  Tags:       {len(res.swf_tags)}")
+    print(f"  ABC blocks: {len(res.abc_blocks)}")
+    print(f"  Classes:    {res.class_count}")
+    print(f"  Methods:    {res.method_count}")
+    print(f"  Strings:    {res.string_count}")
+
+    if res.abc_blocks:
+        abc = res.abc_blocks[0]
+        print(f"  Namespaces: {len(abc.namespace_pool)}")
+        print(f"  Multinames: {len(abc.multiname_pool)}")
+        interfaces = sum(1 for c in ws.classes if c.is_interface)
+        if interfaces:
+            print(f"  Interfaces: {interfaces}")
+
+    pkgs = ws.packages
+    if pkgs:
+        print(f"  Packages:   {len(pkgs)}")

flashkit/cli/packages.py

@@ -0,0 +1,30 @@
+"""``flashkit packages`` — list packages and their class counts."""
+
+from __future__ import annotations
+
+import argparse
+
+from ._util import load, bold, dim
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("packages", help="List packages")
+    p.add_argument("file", help="SWF or SWZ file")
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> None:
+    ws = load(args.file)
+    pkgs = ws.packages
+
+    if not pkgs:
+        print("No packages found.")
+        return
+
+    print(bold(f"{'Package':<50} {'Classes':>8}"))
+    print("-" * 60)
+    for p in sorted(pkgs, key=lambda p: p.name):
+        name = p.name or dim("(default)")
+        print(f"{name:<50} {len(p.classes):>8}")
+
+    print(f"\n{len(pkgs)} package(s)")

flashkit/cli/refs.py

@@ -0,0 +1,31 @@
+"""``flashkit refs`` — find cross-references to a name."""
+
+from __future__ import annotations
+
+import argparse
+
+from ._util import load, bold, dim
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("refs", help="Find cross-references to a name")
+    p.add_argument("file", help="SWF or SWZ file")
+    p.add_argument("name", help="Target name")
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> None:
+    ws = load(args.file)
+
+    from ..analysis.references import ReferenceIndex
+    refs = ReferenceIndex.from_workspace(ws)
+    results = refs.references_to(args.name)
+
+    if not results:
+        print(f"No references to '{args.name}'.")
+        return
+
+    print(bold(f"References to '{args.name}'") + f"  ({len(results)} refs)")
+    for r in results:
+        loc = f"{r.source_class}.{r.source_member}" if r.source_member else r.source_class
+        print(f"  {loc}  {dim(r.ref_kind)}")

flashkit/cli/strings.py

@@ -0,0 +1,58 @@
+"""``flashkit strings`` — list or search string constants."""
+
+from __future__ import annotations
+
+import argparse
+
+from ._util import load, bold, dim, green
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("strings", help="List or search strings")
+    p.add_argument("file", help="SWF or SWZ file")
+    p.add_argument("-s", "--search", help="Search term")
+    p.add_argument("-r", "--regex", action="store_true",
+                   help="Treat search term as regex")
+    p.add_argument("-c", "--classify", action="store_true",
+                   help="Classify strings (URLs, debug markers)")
+    p.add_argument("-v", "--verbose", action="store_true",
+                   help="Show usage locations")
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> None:
+    ws = load(args.file)
+
+    from ..analysis.strings import StringIndex
+    idx = StringIndex.from_workspace(ws)
+
+    if args.search:
+        matches = idx.search(args.search, regex=args.regex)
+        if not matches:
+            print("No matching strings.")
+            return
+
+        for s in matches:
+            print(f"  {green(repr(s))}")
+            if args.verbose:
+                for u in idx.by_string.get(s, []):
+                    print(f"    used in {dim(u.class_name)}.{u.method_name}")
+        print(f"\n{len(matches)} unique string(s)")
+    else:
+        all_strings = sorted(idx.pool_strings)
+        if args.classify:
+            urls = idx.url_strings()
+            files = idx.debug_markers()
+            print(bold("URLs:"))
+            for s in urls:
+                print(f"  {s}")
+            print(f"\n{bold('Debug markers:')}")
+            for s in files:
+                print(f"  {s}")
+            print(f"\n{len(urls)} URL(s), {len(files)} debug marker(s), "
+                  f"{len(all_strings)} total strings")
+        else:
+            for s in all_strings:
+                if s:
+                    print(f"  {s}")
+            print(f"\n{len(all_strings)} string(s)")

flashkit/cli/tags.py

@@ -0,0 +1,32 @@
+"""``flashkit tags`` — list all SWF tags."""
+
+from __future__ import annotations
+
+import argparse
+
+from ._util import load, bold
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("tags", help="List SWF tags")
+    p.add_argument("file", help="SWF file")
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> None:
+    ws = load(args.file)
+    res = ws.resources[0]
+
+    if res.swf_tags is None:
+        print("No SWF tags (file is SWZ format).")
+        return
+
+    print(bold(f"{'#':<6} {'Type':<8} {'Name':<35} {'Size':>10}"))
+    print("-" * 62)
+    for i, tag in enumerate(res.swf_tags):
+        type_str = str(tag.tag_type)
+        name = tag.type_name
+        size = len(tag.payload)
+        print(f"{i:<6} {type_str:<8} {name:<35} {size:>10}")
+
+    print(f"\n{len(res.swf_tags)} tags total")

flashkit/cli/tree.py

@@ -0,0 +1,52 @@
+"""``flashkit tree`` — show inheritance tree for a class."""
+
+from __future__ import annotations
+
+import argparse
+
+from ._util import load, bold, green
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("tree", help="Show inheritance tree")
+    p.add_argument("file", help="SWF or SWZ file")
+    p.add_argument("name", help="Class name")
+    p.add_argument("-a", "--ancestors", action="store_true",
+                   help="Show ancestors instead of descendants")
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> None:
+    ws = load(args.file)
+
+    from ..analysis.inheritance import InheritanceGraph
+    graph = InheritanceGraph.from_classes(ws.classes)
+
+    name = args.name
+
+    if args.ancestors:
+        chain = graph.get_all_parents(name)
+        if not chain:
+            print(f"No ancestors for '{name}' (root or not found).")
+            return
+        print(bold(f"Ancestors of {name}:"))
+        for i, c in enumerate(chain):
+            print(f"  {'  ' * i}{c}")
+        print(f"  {'  ' * len(chain)}{green(name)}")
+        return
+
+    children = graph.get_all_children(name)
+    direct = graph.get_children(name)
+
+    if not children and not direct:
+        print(f"No subclasses of '{name}'.")
+        return
+
+    def _print_tree(n: str, depth: int = 0) -> None:
+        prefix = "  " * depth
+        print(f"{prefix}{green(n) if depth == 0 else n}")
+        for child in sorted(graph.get_children(n)):
+            _print_tree(child, depth + 1)
+
+    _print_tree(name)
+    print(f"\n{len(children)} descendant(s)")

flashkit/errors.py

@@ -0,0 +1,33 @@
+"""
+flashkit error hierarchy.
+
+All flashkit-specific exceptions inherit from ``FlashkitError`` so
+consumers can ``except FlashkitError`` to catch any library error.
+"""
+
+
+class FlashkitError(Exception):
+    """Base exception for all flashkit errors."""
+
+
+class ParseError(FlashkitError):
+    """Raised when binary data cannot be parsed.
+
+    Covers both SWF container parsing and ABC bytecode parsing.
+    """
+
+
+class SWFParseError(ParseError):
+    """Raised when SWF data is invalid or corrupted."""
+
+
+class ABCParseError(ParseError):
+    """Raised when ABC bytecode is invalid or corrupted."""
+
+
+class SerializeError(FlashkitError):
+    """Raised when an AbcFile cannot be serialized back to bytes."""
+
+
+class ResourceError(FlashkitError):
+    """Raised when a resource file cannot be loaded."""

flashkit/info/__init__.py

@@ -0,0 +1,31 @@
+"""
+Rich resolved model for ABC class, field, and method information.
+
+This package resolves raw ABC constant pool indices into human-readable
+names, types, and signatures.
+"""
+
+from .class_info import ClassInfo, build_class_info, build_all_classes
+from .member_info import (
+    FieldInfo,
+    MethodInfoResolved,
+    resolve_multiname,
+    resolve_multiname_full,
+    resolve_traits,
+    build_method_body_map,
+)
+from .package_info import PackageInfo, group_by_package
+
+__all__ = [
+    "ClassInfo",
+    "build_class_info",
+    "build_all_classes",
+    "FieldInfo",
+    "MethodInfoResolved",
+    "resolve_multiname",
+    "resolve_multiname_full",
+    "resolve_traits",
+    "build_method_body_map",
+    "PackageInfo",
+    "group_by_package",
+]

flashkit/info/class_info.py

@@ -0,0 +1,176 @@
+"""
+Resolved class information.
+
+``ClassInfo`` wraps an ABC InstanceInfo + ClassInfo pair with all names
+resolved from the constant pool. Consumers get direct string access to
+class names, superclass names, interface names, and fully resolved
+field/method lists.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from ..abc.types import AbcFile
+from ..abc.constants import INSTANCE_Interface
+from .member_info import (
+    FieldInfo, MethodInfoResolved,
+    resolve_multiname, resolve_multiname_full, resolve_traits,
+    build_method_body_map,
+)
+
+
+@dataclass
+class ClassInfo:
+    """A fully resolved class definition.
+
+    All names are resolved from the ABC constant pool into strings.
+    Fields and methods are parsed from raw trait data into structured
+    ``FieldInfo`` and ``MethodInfoResolved`` objects.
+
+    Attributes:
+        name: Class name string.
+        package: Package/namespace string (empty for default package).
+        qualified_name: Full ``package.name`` string.
+        super_name: Superclass name (``"Object"`` for root, ``"*"`` if none).
+        super_package: Superclass package string.
+        interfaces: List of interface name strings.
+        is_interface: Whether this class is an interface.
+        is_sealed: Whether this class is sealed (no dynamic properties).
+        is_final: Whether this class is final (cannot be subclassed).
+        fields: Instance fields (FieldInfo list).
+        methods: Instance methods, getters, setters (MethodInfoResolved list).
+        static_fields: Static fields (FieldInfo list).
+        static_methods: Static methods (MethodInfoResolved list).
+        constructor_index: Method index for the instance initializer.
+        static_init_index: Method index for the static initializer.
+        instance_index: Index in AbcFile.instances (and AbcFile.classes).
+        multiname_index: Original multiname index for the class name.
+        super_multiname_index: Original multiname index for the superclass.
+        interface_multiname_indices: Original multiname indices for interfaces.
+    """
+    name: str = ""
+    package: str = ""
+    qualified_name: str = ""
+    super_name: str = "*"
+    super_package: str = ""
+    interfaces: list[str] = field(default_factory=list)
+    is_interface: bool = False
+    is_sealed: bool = False
+    is_final: bool = False
+    fields: list[FieldInfo] = field(default_factory=list)
+    methods: list[MethodInfoResolved] = field(default_factory=list)
+    static_fields: list[FieldInfo] = field(default_factory=list)
+    static_methods: list[MethodInfoResolved] = field(default_factory=list)
+    constructor_index: int = 0
+    static_init_index: int = 0
+    instance_index: int = 0
+    multiname_index: int = 0
+    super_multiname_index: int = 0
+    interface_multiname_indices: list[int] = field(default_factory=list)
+
+    @property
+    def all_fields(self) -> list[FieldInfo]:
+        """All fields (instance + static)."""
+        return self.fields + self.static_fields
+
+    @property
+    def all_methods(self) -> list[MethodInfoResolved]:
+        """All methods (instance + static)."""
+        return self.methods + self.static_methods
+
+    def get_field(self, name: str) -> FieldInfo | None:
+        """Find a field by name (searches instance then static)."""
+        for f in self.fields:
+            if f.name == name:
+                return f
+        for f in self.static_fields:
+            if f.name == name:
+                return f
+        return None
+
+    def get_method(self, name: str) -> MethodInfoResolved | None:
+        """Find a method by name (searches instance then static)."""
+        for m in self.methods:
+            if m.name == name:
+                return m
+        for m in self.static_methods:
+            if m.name == name:
+                return m
+        return None
+
+
+def build_class_info(abc: AbcFile, index: int,
+                     method_body_map: dict[int, int] | None = None) -> ClassInfo:
+    """Build a ClassInfo from an AbcFile instance/class pair.
+
+    Args:
+        abc: The AbcFile containing the class.
+        index: Index into abc.instances and abc.classes.
+        method_body_map: Optional pre-built method→body index map.
+            If None, one will be built automatically.
+
+    Returns:
+        Fully resolved ClassInfo.
+    """
+    if method_body_map is None:
+        method_body_map = build_method_body_map(abc)
+
+    inst = abc.instances[index]
+    cls = abc.classes[index]
+
+    # Resolve class name
+    package, name = resolve_multiname_full(abc, inst.name)
+    qualified = f"{package}.{name}" if package else name
+
+    # Resolve superclass
+    super_package, super_name = resolve_multiname_full(abc, inst.super_name)
+
+    # Resolve interfaces
+    iface_names = [resolve_multiname(abc, i) for i in inst.interfaces]
+
+    # Resolve instance traits (fields + methods)
+    inst_fields, inst_methods = resolve_traits(
+        abc, inst.traits, is_static=False, method_body_map=method_body_map)
+
+    # Resolve static traits (static fields + static methods)
+    static_fields, static_methods = resolve_traits(
+        abc, cls.traits, is_static=True, method_body_map=method_body_map)
+
+    return ClassInfo(
+        name=name,
+        package=package,
+        qualified_name=qualified,
+        super_name=super_name,
+        super_package=super_package,
+        interfaces=iface_names,
+        is_interface=bool(inst.flags & INSTANCE_Interface),
+        is_sealed=bool(inst.flags & 0x01),
+        is_final=bool(inst.flags & 0x02),
+        fields=inst_fields,
+        methods=inst_methods,
+        static_fields=static_fields,
+        static_methods=static_methods,
+        constructor_index=inst.iinit,
+        static_init_index=cls.cinit,
+        instance_index=index,
+        multiname_index=inst.name,
+        super_multiname_index=inst.super_name,
+        interface_multiname_indices=list(inst.interfaces),
+    )
+
+
+def build_all_classes(abc: AbcFile) -> list[ClassInfo]:
+    """Build ClassInfo objects for all classes in an AbcFile.
+
+    Args:
+        abc: The AbcFile to process.
+
+    Returns:
+        List of ClassInfo, one per class, in the same order as abc.instances.
+    """
+    method_body_map = build_method_body_map(abc)
+    return [
+        build_class_info(abc, i, method_body_map)
+        for i in range(len(abc.instances))
+    ]