pyflashkit 1.0.0__py3-none-any.whl

flashkit/workspace/resource.py

@@ -0,0 +1,189 @@
+"""
+Resource: a single loaded SWF or SWZ file.
+
+A Resource holds the parsed content of one file — its SWF tags (if SWF),
+the extracted AbcFile objects, and the resolved ClassInfo list.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from ..errors import ResourceError
+from ..abc.types import AbcFile
+from ..abc.parser import parse_abc
+from ..abc.writer import serialize_abc
+from ..swf.tags import SWFTag, TAG_DO_ABC, TAG_DO_ABC2
+from ..swf.parser import parse_swf
+from ..info.class_info import ClassInfo, build_all_classes
+
+
+@dataclass
+class Resource:
+    """A loaded SWF or SWZ file with parsed ABC content.
+
+    Attributes:
+        path: Original file path.
+        kind: File type (``"swf"`` or ``"swz"``).
+        swf_header: SWF header bytes (None for SWZ).
+        swf_tags: SWF tag list (None for SWZ).
+        swf_version: SWF version number (None for SWZ).
+        abc_blocks: List of parsed AbcFile objects from this resource.
+        classes: All ClassInfo objects resolved from the ABC blocks.
+    """
+    path: str = ""
+    kind: str = "swf"
+    swf_header: bytes | None = None
+    swf_tags: list[SWFTag] | None = None
+    swf_version: int | None = None
+    abc_blocks: list[AbcFile] = field(default_factory=list)
+    classes: list[ClassInfo] = field(default_factory=list)
+
+    @property
+    def class_count(self) -> int:
+        return len(self.classes)
+
+    @property
+    def method_count(self) -> int:
+        return sum(len(abc.methods) for abc in self.abc_blocks)
+
+    @property
+    def string_count(self) -> int:
+        return sum(len(abc.string_pool) for abc in self.abc_blocks)
+
+
+def _extract_abc_from_tag(tag: SWFTag) -> bytes | None:
+    """Extract raw ABC bytes from a DoABC or DoABC2 tag."""
+    if tag.tag_type == TAG_DO_ABC:
+        return tag.payload
+    elif tag.tag_type == TAG_DO_ABC2 and len(tag.payload) > 4:
+        try:
+            null_idx = tag.payload.index(0, 4)
+            return tag.payload[null_idx + 1:]
+        except ValueError:
+            return None
+    return None
+
+
+def load_swf(path: str | Path) -> Resource:
+    """Load a SWF file into a Resource.
+
+    Parses the SWF, extracts all DoABC/DoABC2 tags, parses each into
+    an AbcFile, and resolves all classes.
+
+    Args:
+        path: Path to the SWF file.
+
+    Returns:
+        Resource with all ABC content and resolved classes.
+
+    Raises:
+        ResourceError: If the file cannot be read or is not a valid SWF.
+    """
+    path = Path(path)
+    try:
+        with open(path, "rb") as f:
+            data = f.read()
+    except OSError as e:
+        raise ResourceError(f"Cannot read SWF file '{path}': {e}") from e
+
+    if not data:
+        raise ResourceError(f"SWF file is empty: '{path}'")
+
+    try:
+        header, tags, version, file_length = parse_swf(data)
+    except Exception as e:
+        raise ResourceError(f"Failed to parse SWF '{path}': {e}") from e
+
+    abc_blocks: list[AbcFile] = []
+    all_classes: list[ClassInfo] = []
+
+    for tag in tags:
+        abc_data = _extract_abc_from_tag(tag)
+        if abc_data and len(abc_data) > 4:
+            abc = parse_abc(abc_data)
+            abc_blocks.append(abc)
+            all_classes.extend(build_all_classes(abc))
+
+    return Resource(
+        path=str(path),
+        kind="swf",
+        swf_header=header,
+        swf_tags=tags,
+        swf_version=version,
+        abc_blocks=abc_blocks,
+        classes=all_classes,
+    )
+
+
+def load_swz(path: str | Path) -> Resource:
+    """Load a SWZ file into a Resource.
+
+    SWZ files are signed and compressed ABC modules used by Adobe AIR.
+    Format: RSA signature (variable length) + zlib-compressed ABC data.
+    There is no fixed magic header — we scan for a valid zlib stream
+    and verify the decompressed content starts with ABC version 46.16.
+
+    Args:
+        path: Path to the SWZ file.
+
+    Returns:
+        Resource with the parsed ABC content and resolved classes.
+
+    Raises:
+        ResourceError: If the file cannot be read or contains no valid ABC.
+    """
+    import zlib
+
+    path = Path(path)
+    try:
+        with open(path, "rb") as f:
+            data = f.read()
+    except OSError as e:
+        raise ResourceError(f"Cannot read SWZ file '{path}': {e}") from e
+
+    if not data:
+        raise ResourceError(f"SWZ file is empty: '{path}'")
+
+    # SWZ format: RSA signature + zlib-compressed ABC.
+    # Scan for a zlib stream (0x78 byte) and verify decompressed ABC version.
+    abc_data = None
+    for i in range(min(len(data), 256)):
+        if data[i] == 0x78 and i + 2 < len(data):
+            try:
+                decompressed = zlib.decompress(data[i:])
+                if len(decompressed) >= 4:
+                    minor = decompressed[0] | (decompressed[1] << 8)
+                    major = decompressed[2] | (decompressed[3] << 8)
+                    if major == 46 and minor == 16:
+                        abc_data = decompressed
+                        break
+            except zlib.error:
+                continue
+
+    if abc_data is None:
+        # Try raw (uncompressed) ABC
+        if len(data) >= 4:
+            minor = data[0] | (data[1] << 8)
+            major = data[2] | (data[3] << 8)
+            if major == 46 and minor == 16:
+                abc_data = data
+
+    if abc_data is None:
+        raise ResourceError(
+            f"No valid ABC data found in SWZ file: '{path}'")
+
+    abc_blocks: list[AbcFile] = []
+    all_classes: list[ClassInfo] = []
+
+    abc = parse_abc(abc_data)
+    abc_blocks.append(abc)
+    all_classes.extend(build_all_classes(abc))
+
+    return Resource(
+        path=str(path),
+        kind="swz",
+        abc_blocks=abc_blocks,
+        classes=all_classes,
+    )

flashkit/workspace/workspace.py

@@ -0,0 +1,232 @@
+"""
+Workspace: the top-level container for loaded SWF/SWZ content.
+
+The Workspace loads one or more files, aggregates all ABC content,
+and provides unified access to classes, strings, and analysis.
+
+Usage::
+
+    from flashkit.workspace import Workspace
+
+    ws = Workspace()
+    ws.load_swf("application.swf")
+    ws.load_swz("module.swz")
+
+    for cls in ws.classes:
+        print(f"{cls.qualified_name} ({len(cls.fields)} fields)")
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..abc.types import AbcFile
+from ..info.class_info import ClassInfo
+from ..info.package_info import PackageInfo, group_by_package
+from .resource import Resource, load_swf, load_swz
+
+
+class Workspace:
+    """Unified workspace for analyzing SWF/SWZ content.
+
+    Load one or more files, then query the aggregated class index.
+
+    Attributes:
+        resources: List of loaded Resource objects.
+    """
+
+    def __init__(self) -> None:
+        self.resources: list[Resource] = []
+        self._class_index: dict[str, ClassInfo] = {}
+        self._classes: list[ClassInfo] = []
+        self._packages: list[PackageInfo] | None = None
+
+    def load_swf(self, path: str | Path) -> Resource:
+        """Load a SWF file into the workspace.
+
+        Args:
+            path: Path to the SWF file.
+
+        Returns:
+            The loaded Resource.
+        """
+        res = load_swf(path)
+        self._add_resource(res)
+        return res
+
+    def load_swz(self, path: str | Path) -> Resource:
+        """Load a SWZ file into the workspace.
+
+        Args:
+            path: Path to the SWZ file.
+
+        Returns:
+            The loaded Resource.
+        """
+        res = load_swz(path)
+        self._add_resource(res)
+        return res
+
+    def load_swf_bytes(self, data: bytes, name: str = "<memory>") -> Resource:
+        """Load a SWF from raw bytes (no file needed).
+
+        Useful for programmatically constructed SWFs or testing.
+
+        Args:
+            data: Raw SWF file bytes.
+            name: Display name for the resource.
+
+        Returns:
+            The loaded Resource.
+        """
+        from ..swf.parser import parse_swf
+        from ..swf.tags import TAG_DO_ABC, TAG_DO_ABC2
+        from ..abc.parser import parse_abc
+        from ..info.class_info import build_all_classes
+
+        header, tags, version, file_length = parse_swf(data)
+        abc_blocks: list[AbcFile] = []
+        all_classes: list[ClassInfo] = []
+
+        for tag in tags:
+            abc_data = None
+            if tag.tag_type == TAG_DO_ABC:
+                abc_data = tag.payload
+            elif tag.tag_type == TAG_DO_ABC2 and len(tag.payload) > 4:
+                try:
+                    null_idx = tag.payload.index(0, 4)
+                    abc_data = tag.payload[null_idx + 1:]
+                except ValueError:
+                    pass
+
+            if abc_data and len(abc_data) > 4:
+                abc = parse_abc(abc_data)
+                abc_blocks.append(abc)
+                all_classes.extend(build_all_classes(abc))
+
+        res = Resource(
+            path=name,
+            kind="swf",
+            swf_header=header,
+            swf_tags=tags,
+            swf_version=version,
+            abc_blocks=abc_blocks,
+            classes=all_classes,
+        )
+        self._add_resource(res)
+        return res
+
+    def load(self, path: str | Path) -> Resource:
+        """Load a file, auto-detecting format by extension.
+
+        Args:
+            path: Path to a SWF or SWZ file.
+
+        Returns:
+            The loaded Resource.
+        """
+        p = Path(path)
+        if p.suffix.lower() == ".swz":
+            return self.load_swz(p)
+        else:
+            return self.load_swf(p)
+
+    def _add_resource(self, res: Resource) -> None:
+        """Add a resource and update indexes."""
+        self.resources.append(res)
+        for cls in res.classes:
+            self._classes.append(cls)
+            # Index by both simple name and qualified name
+            self._class_index[cls.name] = cls
+            if cls.qualified_name != cls.name:
+                self._class_index[cls.qualified_name] = cls
+        self._packages = None  # invalidate cache
+
+    @property
+    def classes(self) -> list[ClassInfo]:
+        """All classes across all loaded resources."""
+        return self._classes
+
+    @property
+    def abc_blocks(self) -> list[AbcFile]:
+        """All AbcFile objects across all loaded resources."""
+        result: list[AbcFile] = []
+        for res in self.resources:
+            result.extend(res.abc_blocks)
+        return result
+
+    @property
+    def packages(self) -> list[PackageInfo]:
+        """All packages, computed from the class index."""
+        if self._packages is None:
+            self._packages = group_by_package(self._classes)
+        return self._packages
+
+    def get_class(self, name: str) -> ClassInfo | None:
+        """Look up a class by name or qualified name.
+
+        Args:
+            name: Simple name (e.g. ``"MyClass"``) or qualified
+                  (e.g. ``"com.example.MyClass"``).
+
+        Returns:
+            ClassInfo if found, None otherwise.
+        """
+        return self._class_index.get(name)
+
+    def find_classes(
+        self,
+        *,
+        name: str | None = None,
+        extends: str | None = None,
+        implements: str | None = None,
+        package: str | None = None,
+        is_interface: bool | None = None,
+    ) -> list[ClassInfo]:
+        """Find classes matching the given criteria.
+
+        All criteria are AND-combined.
+
+        Args:
+            name: Substring match on class name.
+            extends: Exact match on superclass name.
+            implements: Exact match on one of the interface names.
+            package: Exact match on package name.
+            is_interface: Filter by interface flag.
+
+        Returns:
+            List of matching ClassInfo objects.
+        """
+        results = self._classes
+        if name is not None:
+            results = [c for c in results if name in c.name]
+        if extends is not None:
+            results = [c for c in results if c.super_name == extends]
+        if implements is not None:
+            results = [c for c in results if implements in c.interfaces]
+        if package is not None:
+            results = [c for c in results if c.package == package]
+        if is_interface is not None:
+            results = [c for c in results if c.is_interface == is_interface]
+        return results
+
+    @property
+    def class_count(self) -> int:
+        return len(self._classes)
+
+    @property
+    def interface_count(self) -> int:
+        return sum(1 for c in self._classes if c.is_interface)
+
+    def summary(self) -> str:
+        """Return a human-readable summary of the workspace."""
+        lines = [f"Workspace: {len(self.resources)} resource(s)"]
+        for res in self.resources:
+            lines.append(
+                f"  {res.path}: {res.class_count} classes, "
+                f"{res.method_count} methods, {res.string_count} strings")
+        lines.append(
+            f"Total: {self.class_count} classes, "
+            f"{self.interface_count} interfaces, "
+            f"{len(self.packages)} packages")
+        return "\n".join(lines)

pyflashkit-1.0.0.dist-info/METADATA

@@ -0,0 +1,281 @@
+Metadata-Version: 2.4
+Name: pyflashkit
+Version: 1.0.0
+Summary: SWF/ABC toolkit for parsing, analyzing, and manipulating Flash files and AVM2 bytecode
+License: MIT
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Disassemblers
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# flashkit
+
+Parse, analyze, and manipulate Adobe Flash SWF files and AVM2 bytecode.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+## Quick start
+
+```python
+from flashkit.workspace import Workspace
+
+ws = Workspace()
+ws.load_swf("application.swf")
+
+# Find all classes extending Sprite
+for cls in ws.find_classes(extends="Sprite"):
+    print(f"{cls.qualified_name} — {len(cls.fields)} fields, {len(cls.methods)} methods")
+
+# Inspect a specific class
+player = ws.get_class("PlayerManager")
+print(player.super_name)    # "EventDispatcher"
+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"):
+    print(s)
+```
+
+---
+
+## CLI
+
+### `flashkit info`
+
+```
+$ flashkit info application.swf
+File: application.swf
+  Format:     SWF
+  SWF version: 40
+  Tags:       142
+  ABC blocks: 1
+  Classes:    823
+  Methods:    14210
+  Strings:    35482
+  Packages:   47
+```
+
+### `flashkit classes`
+
+```bash
+flashkit classes app.swf                # all classes
+flashkit classes app.swf -s Manager     # search by name
+flashkit classes app.swf -p com.game    # filter by package
+flashkit classes app.swf -e Sprite      # filter by superclass
+flashkit classes app.swf -i             # interfaces only
+flashkit classes app.swf -v             # verbose output
+```
+
+### `flashkit class`
+
+```
+$ flashkit class application.swf PlayerManager
+PlayerManager
+  Package: com.game
+  Extends: EventDispatcher
+  Implements: IDisposable, ITickable
+
+  Instance Fields (3)
+    mHealth: Number
+    mName: String
+    mLevel: int
+
+  Instance Methods (5)
+    init(): void
+    get name(): String
+    set name(value: String): void
+    takeDamage(amount: Number): void
+    serialize(): ByteArray
+```
+
+### `flashkit strings`
+
+```bash
+flashkit strings app.swf                # list all
+flashkit strings app.swf -s config      # search
+flashkit strings app.swf -s config -v   # with usage locations
+flashkit strings app.swf -s "\\d+" -r   # regex
+flashkit strings app.swf -c             # classify (URLs, debug)
+```
+
+### `flashkit tags`
+
+```bash
+flashkit tags app.swf
+```
+
+### `flashkit disasm`
+
+```bash
+flashkit disasm app.swf --class PlayerManager
+flashkit disasm app.swf --method-index 42
+```
+
+### `flashkit tree`
+
+```bash
+flashkit tree app.swf BaseEntity              # show descendants
+flashkit tree app.swf PlayerManager -a        # show ancestors
+```
+
+### `flashkit callers` / `flashkit callees`
+
+```bash
+flashkit callers app.swf toString
+flashkit callees app.swf PlayerManager.init
+```
+
+### `flashkit refs`
+
+```bash
+flashkit refs app.swf Point
+```
+
+### `flashkit packages` / `flashkit extract` / `flashkit build`
+
+```bash
+flashkit packages app.swf                     # list packages
+flashkit extract app.swf -o ./output          # extract ABC blocks
+flashkit build app.swf -o rebuilt.swf         # rebuild (compressed)
+flashkit build app.swf -o out.swf -d          # rebuild (decompressed)
+```
+
+---
+
+## Library
+
+### Load and query
+
+```python
+from flashkit.workspace import Workspace
+
+ws = Workspace()
+ws.load_swf("application.swf")
+ws.load_swz("module.swz")
+
+print(ws.summary())
+
+cls = ws.get_class("MyClass")
+print(cls.name, cls.super_name, cls.interfaces)
+print(cls.fields)   # list of FieldInfo
+print(cls.methods)  # list of MethodInfoResolved
+
+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")
+
+calls = CallGraph.from_workspace(ws)
+calls.get_callers("toString")
+calls.get_callees("MyClass.init")
+
+strings = StringIndex.from_workspace(ws)
+strings.search("config")
+strings.url_strings()
+strings.classes_using_string("http://example.com")
+```
+
+<details>
+<summary><strong>Parse SWF and ABC directly</strong></summary>
+
+```python
+from flashkit.swf import parse_swf, TAG_DO_ABC2
+from flashkit.abc import parse_abc, serialize_abc
+
+header, tags, version, length = parse_swf(swf_bytes)
+
+for tag in tags:
+    if tag.tag_type == TAG_DO_ABC2:
+        null_idx = tag.payload.index(0, 4)
+        abc = parse_abc(tag.payload[null_idx + 1:])
+        print(f"{len(abc.instances)} classes, {len(abc.methods)} methods")
+
+        # Round-trip fidelity: serialize(parse(data)) == data
+        assert serialize_abc(abc) == tag.payload[null_idx + 1:]
+```
+
+</details>
+
+<details>
+<summary><strong>Build SWF programmatically</strong></summary>
+
+```python
+from flashkit.abc import AbcBuilder, serialize_abc
+from flashkit.swf import SwfBuilder
+
+b = AbcBuilder()
+b.simple_class("Player", package="com.game",
+               fields=[("hp", "int"), ("name", "String")])
+b.script()
+abc_bytes = serialize_abc(b.build())
+
+swf = SwfBuilder(version=40, width=800, height=600, fps=30)
+swf.add_abc("GameCode", abc_bytes)
+swf_bytes = swf.build(compress=True)
+```
+
+</details>
+
+<details>
+<summary><strong>Disassemble method bodies</strong></summary>
+
+```python
+from flashkit.abc import decode_instructions
+
+for body in abc.method_bodies:
+    for instr in decode_instructions(body.code):
+        print(f"0x{instr.offset:04X}  {instr.mnemonic}  {instr.operands}")
+```
+
+</details>
+
+---
+
+## Project structure
+
+```
+flashkit/
+  cli/           CLI (one module per command)
+  swf/           SWF container (parse, build, tags)
+  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
+```
+
+## References
+
+- [AVM2 Overview (Adobe)](https://www.adobe.com/content/dam/acom/en/devnet/pdf/avm2overview.pdf)
+- [SWF File Format Specification](https://open-flash.github.io/mirrors/swf-spec-19.pdf)
+
+## License
+
+MIT