pyflashkit 1.0.0__py3-none-any.whl

flashkit/analysis/strings.py

@@ -0,0 +1,299 @@
+"""
+String pool analysis and search.
+
+Provides filtered views into the ABC string pool and tracks where each
+string constant is used in method bodies via OP_pushstring instructions.
+
+Usage::
+
+    from flashkit.workspace import Workspace
+    from flashkit.analysis.strings import StringIndex
+
+    ws = Workspace()
+    ws.load_swf("application.swf")
+    idx = StringIndex.from_workspace(ws)
+
+    results = idx.search("config")
+    classes = idx.classes_using_string("http://")
+"""
+
+from __future__ import annotations
+
+import re
+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_debugfile
+from ..info.member_info import resolve_multiname, build_method_body_map
+from ..info.class_info import ClassInfo
+
+
+@dataclass
+class StringUsage:
+    """A single occurrence of a string constant in bytecode.
+
+    Attributes:
+        string: The string value.
+        class_name: Qualified name of the owning class.
+        method_name: Method name where the string is pushed.
+        method_index: Index into AbcFile.methods.
+        offset: Bytecode offset of the OP_pushstring instruction.
+        opcode: The opcode (OP_pushstring or OP_debugfile).
+    """
+    string: str
+    class_name: str
+    method_name: str
+    method_index: int
+    offset: int
+    opcode: int = OP_pushstring
+
+
+@dataclass
+class StringIndex:
+    """Index of string constant usage across all method bodies.
+
+    Attributes:
+        usages: All string usage entries.
+        by_string: Map of string value → list of usages.
+        by_class: Map of class name → list of usages.
+        all_strings: Set of all unique string values found in code.
+        pool_strings: Set of all strings in all string pools (superset).
+    """
+    usages: list[StringUsage] = field(default_factory=list)
+    by_string: dict[str, list[StringUsage]] = field(
+        default_factory=lambda: defaultdict(list))
+    by_class: dict[str, list[StringUsage]] = field(
+        default_factory=lambda: defaultdict(list))
+    all_strings: set[str] = field(default_factory=set)
+    pool_strings: set[str] = field(default_factory=set)
+
+    def _add(self, usage: StringUsage) -> None:
+        """Add a string usage to all indexes."""
+        self.usages.append(usage)
+        self.by_string[usage.string].append(usage)
+        self.by_class[usage.class_name].append(usage)
+        self.all_strings.add(usage.string)
+
+    @classmethod
+    def from_workspace(cls, workspace: object) -> StringIndex:
+        """Build a StringIndex from a Workspace.
+
+        Walks all method bodies, decodes instructions, and collects
+        OP_pushstring and OP_debugfile references.
+
+        Args:
+            workspace: A Workspace instance.
+
+        Returns:
+            Populated StringIndex.
+        """
+        from ..workspace.workspace import Workspace
+        ws: Workspace = workspace  # type: ignore[assignment]
+
+        index = cls()
+
+        # Collect all pool strings
+        for abc in ws.abc_blocks:
+            for s in abc.string_pool:
+                if s:
+                    index.pool_strings.add(s)
+
+        for abc in ws.abc_blocks:
+            index._index_abc(abc, ws.classes)
+
+        return index
+
+    @classmethod
+    def from_abc(cls, abc: AbcFile,
+                 classes: list[ClassInfo] | None = None) -> StringIndex:
+        """Build a StringIndex from a single AbcFile.
+
+        Args:
+            abc: The AbcFile to analyze.
+            classes: Optional class list for method name resolution.
+
+        Returns:
+            Populated StringIndex.
+        """
+        index = cls()
+        for s in abc.string_pool:
+            if s:
+                index.pool_strings.add(s)
+        index._index_abc(abc, classes or [])
+        return index
+
+    def _index_abc(self, abc: AbcFile, classes: list[ClassInfo]) -> None:
+        """Walk all method bodies in an AbcFile and index string usages."""
+        method_owner_map = _build_method_owner_map(abc, classes)
+        method_name_map = _build_method_name_map(abc, classes)
+
+        for body in abc.method_bodies:
+            owner_class = method_owner_map.get(body.method, "")
+            method_name = method_name_map.get(
+                body.method, f"method_{body.method}")
+
+            try:
+                instructions = decode_instructions(body.code)
+            except Exception:
+                continue
+
+            for instr in instructions:
+                if instr.opcode in (OP_pushstring, OP_debugfile):
+                    if not instr.operands:
+                        continue
+                    str_index = instr.operands[0]
+                    if 0 < str_index < len(abc.string_pool):
+                        string_val = abc.string_pool[str_index]
+                        self._add(StringUsage(
+                            string=string_val,
+                            class_name=owner_class,
+                            method_name=method_name,
+                            method_index=body.method,
+                            offset=instr.offset,
+                            opcode=instr.opcode,
+                        ))
+
+    def search(self, pattern: str, regex: bool = False) -> list[str]:
+        """Search for strings matching a pattern.
+
+        Args:
+            pattern: Substring to search for, or regex if regex=True.
+            regex: If True, treat pattern as a regular expression.
+
+        Returns:
+            List of matching string values (from code usage).
+        """
+        if regex:
+            try:
+                compiled = re.compile(pattern, re.IGNORECASE)
+            except re.error:
+                return []
+            return sorted(s for s in self.all_strings if compiled.search(s))
+        else:
+            pattern_lower = pattern.lower()
+            return sorted(
+                s for s in self.all_strings if pattern_lower in s.lower())
+
+    def search_pool(self, pattern: str, regex: bool = False) -> list[str]:
+        """Search all string pool entries (not just those used in code).
+
+        Args:
+            pattern: Substring or regex pattern.
+            regex: If True, treat as regex.
+
+        Returns:
+            List of matching strings from the pool.
+        """
+        if regex:
+            try:
+                compiled = re.compile(pattern, re.IGNORECASE)
+            except re.error:
+                return []
+            return sorted(s for s in self.pool_strings if compiled.search(s))
+        else:
+            pattern_lower = pattern.lower()
+            return sorted(
+                s for s in self.pool_strings if pattern_lower in s.lower())
+
+    def strings_in_class(self, class_name: str) -> list[str]:
+        """Get all unique strings referenced by a class.
+
+        Args:
+            class_name: Qualified or simple class name.
+
+        Returns:
+            Sorted list of unique string values.
+        """
+        usages = self.by_class.get(class_name, [])
+        if not usages:
+            # Try simple name match
+            for key, u_list in self.by_class.items():
+                if key.endswith(f".{class_name}") or key == class_name:
+                    usages = u_list
+                    break
+        return sorted(set(u.string for u in usages))
+
+    def classes_using_string(self, string: str) -> list[str]:
+        """Get all classes that reference a specific string.
+
+        Args:
+            string: The exact string value.
+
+        Returns:
+            Sorted list of unique class qualified names.
+        """
+        return sorted(set(
+            u.class_name for u in self.by_string.get(string, [])
+            if u.class_name
+        ))
+
+    def debug_markers(self) -> list[str]:
+        """Find strings that look like debug source markers (e.g. ``[Foo.hx]``).
+
+        Returns:
+            Sorted list of matching strings.
+        """
+        return sorted(
+            s for s in self.all_strings
+            if s.endswith(".hx") or s.endswith(".as")
+            or (s.startswith("[") and s.endswith("]"))
+        )
+
+    def url_strings(self) -> list[str]:
+        """Find strings that look like URLs or file paths.
+
+        Returns:
+            Sorted list of matching strings.
+        """
+        return sorted(
+            s for s in self.all_strings
+            if s.startswith("http://") or s.startswith("https://")
+            or s.startswith("file://") or s.startswith("/")
+            or ".xml" in s or ".json" in s or ".swf" in s
+        )
+
+    def ui_strings(self) -> list[str]:
+        """Find strings that likely represent UI labels (contain spaces, mixed case).
+
+        Returns:
+            Sorted list of matching strings.
+        """
+        return sorted(
+            s for s in self.all_strings
+            if " " in s and len(s) > 3 and not s.startswith("http")
+            and not s.endswith(".hx") and not s.endswith(".as")
+        )
+
+    @property
+    def unique_string_count(self) -> int:
+        return len(self.all_strings)
+
+    @property
+    def total_usages(self) -> int:
+        return len(self.usages)
+
+
+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
+
+
+def _build_method_name_map(abc: AbcFile,
+                           classes: list[ClassInfo]) -> dict[int, str]:
+    """Map method_index → readable method name."""
+    name_map: dict[int, str] = {}
+    for ci in classes:
+        name_map[ci.constructor_index] = "<init>"
+        name_map[ci.static_init_index] = "<cinit>"
+        for m in ci.all_methods:
+            name_map[m.method_index] = m.name
+    return name_map

flashkit/cli/__init__.py

@@ -0,0 +1,75 @@
+"""
+flashkit CLI — command-line interface for SWF/ABC analysis.
+
+Structured as a package with one module per subcommand.
+Entry point is :func:`main`, registered as ``flashkit`` console script.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .. import __version__
+from ..errors import FlashkitError
+from ._util import red
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the top-level argument parser with all subcommands."""
+    parser = argparse.ArgumentParser(
+        prog="flashkit",
+        description="SWF/ABC toolkit — inspect, analyze, and manipulate Flash files.",
+    )
+    parser.add_argument(
+        "--version", action="version",
+        version=f"flashkit {__version__}")
+
+    sub = parser.add_subparsers(dest="command", metavar="COMMAND")
+
+    # Import each command module — each one registers itself.
+    from . import (
+        info, tags, classes, class_cmd, strings,
+        disasm, callers, callees, refs, tree,
+        packages, extract, build,
+    )
+
+    info.register(sub)
+    tags.register(sub)
+    classes.register(sub)
+    class_cmd.register(sub)
+    strings.register(sub)
+    disasm.register(sub)
+    callers.register(sub)
+    callees.register(sub)
+    refs.register(sub)
+    tree.register(sub)
+    packages.register(sub)
+    extract.register(sub)
+    build.register(sub)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    """CLI entry point."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if not args.command:
+        parser.print_help()
+        sys.exit(0)
+
+    try:
+        args.func(args)
+    except FlashkitError as e:
+        print(f"{red('Error')}: {e}", file=sys.stderr)
+        sys.exit(1)
+    except BrokenPipeError:
+        pass
+    except KeyboardInterrupt:
+        sys.exit(130)
+
+
+if __name__ == "__main__":
+    main()

flashkit/cli/_util.py

@@ -0,0 +1,52 @@
+"""Shared CLI utilities — ANSI colors and workspace loading."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from ..workspace import Workspace
+
+# Respect NO_COLOR convention (https://no-color.org/) and non-TTY output.
+_NO_COLOR = not sys.stdout.isatty() or os.environ.get("NO_COLOR", "") != ""
+
+
+def _c(code: str, text: str) -> str:
+    if _NO_COLOR:
+        return text
+    return f"\033[{code}m{text}\033[0m"
+
+
+def bold(t: str) -> str:
+    return _c("1", t)
+
+
+def dim(t: str) -> str:
+    return _c("2", t)
+
+
+def green(t: str) -> str:
+    return _c("32", t)
+
+
+def cyan(t: str) -> str:
+    return _c("36", t)
+
+
+def yellow(t: str) -> str:
+    return _c("33", t)
+
+
+def red(t: str) -> str:
+    return _c("31", t)
+
+
+def magenta(t: str) -> str:
+    return _c("35", t)
+
+
+def load(path: str) -> Workspace:
+    """Load a SWF/SWZ file into a Workspace."""
+    ws = Workspace()
+    ws.load(path)
+    return ws

flashkit/cli/build.py

@@ -0,0 +1,36 @@
+"""``flashkit build`` — rebuild a SWF (recompress or decompress)."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from ._util import load
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("build", help="Rebuild SWF (recompress/decompress)")
+    p.add_argument("file", help="SWF file")
+    p.add_argument("-o", "--output", help="Output file path")
+    p.add_argument("-d", "--decompress", action="store_true",
+                   help="Output uncompressed FWS")
+    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("Cannot rebuild: not a SWF file.")
+        return
+
+    from ..swf.builder import rebuild_swf
+
+    compress = not args.decompress
+    output = rebuild_swf(res.swf_header, res.swf_tags, compress=compress)
+
+    out_path = args.output or args.file
+    Path(out_path).write_bytes(output)
+    mode = "compressed" if compress else "uncompressed"
+    print(f"Wrote {out_path} ({len(output)} bytes, {mode})")

flashkit/cli/callees.py

@@ -0,0 +1,30 @@
+"""``flashkit callees`` — find calls made from a method."""
+
+from __future__ import annotations
+
+import argparse
+
+from ._util import load, bold, dim
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("callees", help="Find calls from a method")
+    p.add_argument("file", help="SWF or SWZ file")
+    p.add_argument("name", help="Method name (e.g. Class.method)")
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> None:
+    ws = load(args.file)
+
+    from ..analysis.call_graph import CallGraph
+    graph = CallGraph.from_workspace(ws)
+    edges = graph.get_callees(args.name)
+
+    if not edges:
+        print(f"No callees found for '{args.name}'.")
+        return
+
+    print(bold(f"Callees from '{args.name}'") + f"  ({len(edges)} edges)")
+    for e in edges:
+        print(f"  -> {e.target}  {dim(e.mnemonic)}  @ 0x{e.offset:04X}")

flashkit/cli/callers.py

@@ -0,0 +1,30 @@
+"""``flashkit callers`` — find callers of a method/property."""
+
+from __future__ import annotations
+
+import argparse
+
+from ._util import load, bold, dim
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("callers", help="Find callers of a method")
+    p.add_argument("file", help="SWF or SWZ file")
+    p.add_argument("name", help="Method or property name")
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> None:
+    ws = load(args.file)
+
+    from ..analysis.call_graph import CallGraph
+    graph = CallGraph.from_workspace(ws)
+    edges = graph.get_callers(args.name)
+
+    if not edges:
+        print(f"No callers found for '{args.name}'.")
+        return
+
+    print(bold(f"Callers of '{args.name}'") + f"  ({len(edges)} edges)")
+    for e in edges:
+        print(f"  {e.caller}  {dim(e.mnemonic)}  @ 0x{e.offset:04X}")

flashkit/cli/class_cmd.py

@@ -0,0 +1,83 @@
+"""``flashkit class`` — show details for a single class."""
+
+from __future__ import annotations
+
+import argparse
+
+from ._util import load, bold, dim, cyan, green, yellow
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("class", help="Show class details")
+    p.add_argument("file", help="SWF or SWZ file")
+    p.add_argument("name", help="Class name (simple or qualified)")
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> None:
+    ws = load(args.file)
+    cls = ws.get_class(args.name)
+
+    if cls is None:
+        matches = ws.find_classes(name=args.name)
+        if len(matches) == 1:
+            cls = matches[0]
+        elif matches:
+            print(f"Ambiguous name '{args.name}', matches:")
+            for m in matches:
+                print(f"  {m.qualified_name}")
+            return
+        else:
+            print(f"Class '{args.name}' not found.")
+            return
+
+    flags = []
+    if cls.is_interface:
+        flags.append("interface")
+    if cls.is_final:
+        flags.append("final")
+    if cls.is_sealed:
+        flags.append("sealed")
+    flag_str = f"  [{', '.join(flags)}]" if flags else ""
+
+    print(bold(cls.qualified_name) + dim(flag_str))
+    if cls.package:
+        print(f"  Package: {cyan(cls.package)}")
+    print(f"  Extends: {cyan(cls.super_name)}")
+    if cls.interfaces:
+        print(f"  Implements: {', '.join(green(i) for i in cls.interfaces)}")
+
+    if cls.fields:
+        print(f"\n  {bold('Instance Fields')} ({len(cls.fields)})")
+        for f in cls.fields:
+            const = "const " if f.is_const else ""
+            print(f"    {const}{f.name}: {yellow(f.type_name)}")
+
+    if cls.static_fields:
+        print(f"\n  {bold('Static Fields')} ({len(cls.static_fields)})")
+        for f in cls.static_fields:
+            const = "const " if f.is_const else ""
+            print(f"    static {const}{f.name}: {yellow(f.type_name)}")
+
+    if cls.methods:
+        print(f"\n  {bold('Instance Methods')} ({len(cls.methods)})")
+        for m in cls.methods:
+            kind = ""
+            if m.is_getter:
+                kind = "get "
+            elif m.is_setter:
+                kind = "set "
+            params = ", ".join(
+                f"{n}: {t}" if n else t
+                for n, t in zip(m.param_names or [""] * len(m.param_types),
+                                m.param_types))
+            print(f"    {kind}{m.name}({params}): {yellow(m.return_type)}")
+
+    if cls.static_methods:
+        print(f"\n  {bold('Static Methods')} ({len(cls.static_methods)})")
+        for m in cls.static_methods:
+            params = ", ".join(
+                f"{n}: {t}" if n else t
+                for n, t in zip(m.param_names or [""] * len(m.param_types),
+                                m.param_types))
+            print(f"    static {m.name}({params}): {yellow(m.return_type)}")

flashkit/cli/classes.py

@@ -0,0 +1,71 @@
+"""``flashkit classes`` — list all classes with optional filters."""
+
+from __future__ import annotations
+
+import argparse
+
+from ._util import load, bold, dim, cyan, green
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("classes", help="List classes")
+    p.add_argument("file", help="SWF or SWZ file")
+    p.add_argument("-s", "--search", help="Filter by name substring")
+    p.add_argument("-p", "--package", help="Filter by package")
+    p.add_argument("-e", "--extends", help="Filter by superclass")
+    p.add_argument("-i", "--interfaces-only", action="store_true",
+                   help="Show only interfaces")
+    p.add_argument("-v", "--verbose", action="store_true",
+                   help="Show detailed info per class")
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> None:
+    ws = load(args.file)
+    classes = ws.classes
+
+    if args.package:
+        classes = [c for c in classes if c.package == args.package]
+    if args.extends:
+        classes = [c for c in classes if c.super_name == args.extends]
+    if args.interfaces_only:
+        classes = [c for c in classes if c.is_interface]
+    if args.search:
+        term = args.search.lower()
+        classes = [c for c in classes if term in c.qualified_name.lower()]
+
+    if not classes:
+        print("No classes found.")
+        return
+
+    if args.verbose:
+        for cls in classes:
+            flags = []
+            if cls.is_interface:
+                flags.append("interface")
+            if cls.is_final:
+                flags.append("final")
+            if cls.is_sealed:
+                flags.append("sealed")
+            flag_str = f" [{', '.join(flags)}]" if flags else ""
+
+            print(bold(cls.qualified_name) + dim(flag_str))
+            print(f"  extends {cyan(cls.super_name)}")
+            if cls.interfaces:
+                print(f"  implements {', '.join(green(i) for i in cls.interfaces)}")
+            print(f"  {len(cls.fields)} fields, {len(cls.methods)} methods"
+                  f", {len(cls.static_fields)} static fields"
+                  f", {len(cls.static_methods)} static methods")
+            print()
+    else:
+        print(bold(f"{'Class':<50} {'Super':<25} {'Fields':>6} {'Methods':>7}"))
+        print("-" * 92)
+        for cls in classes:
+            name = cls.qualified_name
+            prefix = ""
+            if cls.is_interface:
+                prefix = dim("[I] ")
+            print(f"{prefix}{name:<50} {cls.super_name:<25} "
+                  f"{len(cls.all_fields):>6} {len(cls.all_methods):>7}")
+
+    print(f"\n{len(classes)} class(es)")