hookfix 0.1.0__py3-none-any.whl

hookfix/__init__.py

@@ -0,0 +1,15 @@
+"""hookfix — find the hidden imports that break your frozen Python app.
+
+Freezers such as PyInstaller and Nuitka discover dependencies by reading your
+source code. Imports that are constructed at runtime are invisible to that
+analysis, so the resulting executable crashes with ``ModuleNotFoundError`` on
+the user's machine and not on yours.
+
+hookfix runs your program once under a CPython audit hook, records every module
+the interpreter actually imports, and compares that against the static import
+graph. The difference is exactly the set of modules your build is missing.
+"""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

hookfix/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m hookfix``."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

hookfix/_bootstrap.py

@@ -0,0 +1,76 @@
+"""Entry point for the tracer subprocess.
+
+Invoked by the CLI as::
+
+    python -m hookfix._bootstrap <logfile> <script> [args...]
+
+It installs the recording meta path finder, writes one ``module<TAB>origin``
+line per import to ``logfile``, then hands control to the user's script with
+:func:`runpy.run_path` so the script sees ``__name__ == "__main__"`` exactly as
+it would under a plain ``python script.py`` invocation.
+
+This module is deliberately self-contained: the child process must not import
+the rest of hookfix before the tracer is installed, or those imports would be
+recorded as if the user's program had made them.
+"""
+
+from __future__ import annotations
+
+import os
+import runpy
+import sys
+from typing import Any
+
+
+class _Recorder:
+    """Minimal meta path finder that logs every resolved module."""
+
+    def __init__(self, log: Any) -> None:
+        self._log = log
+
+    def find_spec(
+        self,
+        fullname: str,
+        path: Any | None = None,
+        target: Any | None = None,
+    ) -> Any:
+        for finder in list(sys.meta_path):
+            if finder is self:
+                continue
+            find_spec = getattr(finder, "find_spec", None)
+            if find_spec is None:
+                continue
+            spec = find_spec(fullname, path, target)
+            if spec is not None:
+                origin = getattr(spec, "origin", None) or ""
+                self._log.write(f"{fullname}\t{origin}\n")
+                return spec
+        self._log.write(f"{fullname}\t\n")
+        return None
+
+
+def _main() -> None:  # pragma: no cover - exercised via subprocess in tests
+    if len(sys.argv) < 3:
+        print("usage: python -m hookfix._bootstrap <logfile> <script> [args...]", file=sys.stderr)
+        raise SystemExit(2)
+
+    logfile = sys.argv[1]
+    script = sys.argv[2]
+
+    # Mimic a plain ``python script.py`` invocation: the script's directory
+    # becomes the first entry on sys.path, so sibling packages resolve.
+    script_dir = os.path.dirname(os.path.abspath(script))
+    sys.path.insert(0, script_dir)
+
+    # Present the script the way a normal ``python script.py`` invocation does.
+    sys.argv = [script, *sys.argv[3:]]
+
+    with open(logfile, "w", encoding="utf-8", buffering=1) as log:
+        # Install the recorder last, so nothing hookfix itself imported is
+        # logged as if the user's program had imported it.
+        sys.meta_path.insert(0, _Recorder(log))
+        runpy.run_path(script, run_name="__main__")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    _main()

hookfix/cli.py

@@ -0,0 +1,267 @@
+"""Command line interface.
+
+Three subcommands, each a step of the same workflow:
+
+``hookfix run``   run a script under the tracer and print a report
+``hookfix diff``  compare a saved trace against a static scan
+``hookfix fix``   turn a saved trace into a hook file or spec snippet
+
+``run`` is the whole workflow in one command; ``diff`` and ``fix`` exist so the
+trace can be taken once (for example in CI, on the platform that will actually
+be packaged) and inspected later.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+import tempfile
+from collections.abc import Sequence
+from pathlib import Path
+
+from . import __version__
+from .differ import diff
+from .errors import HookfixError
+from .model import TraceResult
+from .report import format_report
+from .scanner import scan
+from .spec_writer import render_hook_file, render_spec_patch
+from .tracer import parse_audit_log
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="hookfix",
+        description="Find the hidden imports that break your frozen Python app.",
+    )
+    parser.add_argument("--version", action="version", version=f"hookfix {__version__}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    run = subparsers.add_parser(
+        "run",
+        help="run a script under the tracer and report hidden imports",
+        description=(
+            "Run a script under a CPython audit hook, record every module it "
+            "imports, and compare that against a static scan of the source. "
+            "Arguments after '--' are passed through to the traced script."
+        ),
+    )
+    run.add_argument("script", help="path to the entry point to trace")
+    run.add_argument(
+        "--path",
+        default=None,
+        help="directory to scan statically (default: the script's directory)",
+    )
+    run.add_argument(
+        "--exclude",
+        action="append",
+        default=[],
+        metavar="DIR",
+        help="additional directory name to skip while scanning (repeatable)",
+    )
+    run.add_argument(
+        "--trace-out",
+        default=None,
+        metavar="FILE",
+        help="write the raw runtime trace to FILE as JSON",
+    )
+    run.add_argument(
+        "--json",
+        action="store_true",
+        help="print the diff as JSON instead of a human-readable report",
+    )
+    run.add_argument(
+        "--quiet",
+        action="store_true",
+        help="suppress the traced program's own output",
+    )
+
+    diff_cmd = subparsers.add_parser(
+        "diff",
+        help="compare a saved trace against a static scan",
+        description="Read a trace written by 'hookfix run --trace-out' and diff it.",
+    )
+    diff_cmd.add_argument("trace", help="path to a trace JSON file")
+    diff_cmd.add_argument(
+        "--path",
+        default=None,
+        metavar="DIR",
+        help="directory to scan statically (default: the trace's directory)",
+    )
+    diff_cmd.add_argument(
+        "--exclude",
+        action="append",
+        default=[],
+        metavar="DIR",
+        help="additional directory name to skip while scanning (repeatable)",
+    )
+    diff_cmd.add_argument("--json", action="store_true", help="print the diff as JSON")
+
+    fix = subparsers.add_parser(
+        "fix",
+        help="generate a hook file or spec snippet from a trace",
+        description="Turn a saved trace into build configuration.",
+    )
+    fix.add_argument("trace", help="path to a trace JSON file")
+    fix.add_argument(
+        "--path",
+        default=None,
+        metavar="DIR",
+        help="directory to scan statically (default: the trace's directory)",
+    )
+    fix.add_argument(
+        "--exclude",
+        action="append",
+        default=[],
+        metavar="DIR",
+        help="additional directory name to skip while scanning (repeatable)",
+    )
+    fix.add_argument(
+        "--module",
+        default=None,
+        metavar="NAME",
+        help="name the generated hook file 'hook-NAME.py'",
+    )
+    fix.add_argument(
+        "--spec",
+        action="store_true",
+        help="emit a spec-file snippet instead of a hook file",
+    )
+    fix.add_argument(
+        "-o",
+        "--output",
+        default=None,
+        metavar="FILE",
+        help="write to FILE instead of stdout",
+    )
+
+    return parser
+
+
+def _trace_script(script: Path, script_args: Sequence[str], quiet: bool) -> TraceResult:
+    """Run ``script`` in a child process under the audit hook and collect the trace."""
+    with tempfile.TemporaryDirectory(prefix="hookfix-") as tmp:
+        logfile = Path(tmp) / "imports.log"
+        cmd: list[str] = [
+            sys.executable,
+            "-m",
+            "hookfix._bootstrap",
+            str(logfile),
+            str(script),
+            *script_args,
+        ]
+        completed = subprocess.run(
+            cmd,
+            stdout=subprocess.DEVNULL if quiet else None,
+            stderr=subprocess.DEVNULL if quiet else None,
+            check=False,
+        )
+        log_text = logfile.read_text(encoding="utf-8") if logfile.exists() else ""
+
+    modules, origins = parse_audit_log(log_text)
+    return TraceResult(
+        modules=sorted(modules),
+        origins=origins,
+        returncode=completed.returncode,
+    )
+
+
+def _load_trace(path: str) -> TraceResult:
+    data = json.loads(Path(path).read_text(encoding="utf-8"))
+    return TraceResult.from_dict(data)
+
+
+def _cmd_run(args: argparse.Namespace) -> int:
+    script = Path(args.script).resolve()
+    if not script.exists():
+        raise HookfixError(f"script does not exist: {script}")
+
+    trace = _trace_script(script, args.script_args, args.quiet)
+
+    scan_root = Path(args.path).resolve() if args.path else script.parent
+    static = scan(scan_root, excludes=args.exclude)
+    result = diff(trace, static)
+
+    if args.trace_out:
+        Path(args.trace_out).write_text(
+            json.dumps(trace.to_dict(), indent=2) + "\n", encoding="utf-8"
+        )
+
+    if args.json:
+        print(json.dumps(result.to_dict(), indent=2))
+    else:
+        print(format_report(trace=trace, static=static, result=result, script=str(script)))
+
+    # A non-zero exit from the traced program is reported, but the diff itself
+    # is still useful, so we only propagate the traced status when there is
+    # nothing to report.
+    if trace.returncode != 0 and not result.missing:
+        return trace.returncode
+    return 0
+
+
+def _cmd_diff(args: argparse.Namespace) -> int:
+    trace = _load_trace(args.trace)
+    scan_root = args.path or str(Path(args.trace).resolve().parent)
+    static = scan(scan_root, excludes=args.exclude)
+    result = diff(trace, static)
+
+    if args.json:
+        print(json.dumps(result.to_dict(), indent=2))
+    else:
+        print(
+            format_report(
+                trace=trace,
+                static=static,
+                result=result,
+                script="(from trace)",
+            )
+        )
+    return 0
+
+
+def _cmd_fix(args: argparse.Namespace) -> int:
+    trace = _load_trace(args.trace)
+    scan_root = args.path or str(Path(args.trace).resolve().parent)
+    static = scan(scan_root, excludes=args.exclude)
+    result = diff(trace, static)
+
+    if args.spec:
+        rendered = render_spec_patch(result.missing)
+    else:
+        rendered = render_hook_file(result.missing, module_name=args.module)
+
+    if args.output:
+        Path(args.output).write_text(rendered, encoding="utf-8")
+        print(f"wrote {args.output} ({len(result.missing)} hidden imports)")
+    else:
+        print(rendered, end="")
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    raw = list(sys.argv[1:] if argv is None else argv)
+    # Split pass-through arguments before argparse sees them, so the traced
+    # script's own flags are not mistaken for hookfix's.
+    script_args: list[str] = []
+    if "--" in raw:
+        split = raw.index("--")
+        script_args = raw[split + 1 :]
+        raw = raw[:split]
+
+    parser = _build_parser()
+    args = parser.parse_args(raw)
+    args.script_args = script_args
+
+    handlers = {"run": _cmd_run, "diff": _cmd_diff, "fix": _cmd_fix}
+    try:
+        return handlers[args.command](args)
+    except HookfixError as exc:
+        print(f"hookfix: error: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

hookfix/differ.py

@@ -0,0 +1,66 @@
+"""Compare a runtime trace against the static import graph."""
+
+from __future__ import annotations
+
+import sys
+
+from .model import DiffResult, StaticResult, TraceResult
+
+#: Modules the interpreter itself provides. They are always available in a
+#: frozen build, so a runtime-only standard-library import is not a defect.
+_STDLIB = frozenset(getattr(sys, "stdlib_module_names", ()))
+
+#: Import machinery internals that appear in every trace and mean nothing to a
+#: user reading the report.
+_INTERNAL_PREFIXES = ("_", "importlib")
+
+
+def _is_noise(name: str) -> bool:
+    if name in {"builtins", "sys", "os", "io", "abc", "codecs", "site", "types", "warnings"}:
+        return False
+    return name.startswith(_INTERNAL_PREFIXES) or name.startswith("hookfix")
+
+
+def _stdlib_names() -> set[str]:
+    if _STDLIB:
+        return set(_STDLIB)
+    # Very old interpreters have no ``sys.stdlib_module_names``. Fall back to a
+    # conservative empty set: better to over-report than to hide a real gap.
+    return set()
+
+
+def diff(trace: TraceResult, static: StaticResult) -> DiffResult:
+    """Return the runtime imports that the static scan did not find.
+
+    ``missing`` holds fully-qualified module names, because that is what a
+    freezer needs: ``--hidden-import=reporters.json_reporter``, not the bare
+    package name. ``stdlib_only`` is kept separate because a freezer bundles
+    the standard library regardless.
+    """
+    static_names = set(static.imports)
+    runtime_names = {name for name in trace.modules if not _is_noise(name)}
+    stdlib = _stdlib_names()
+
+    missing: set[str] = set()
+    stdlib_only: set[str] = set()
+    common: set[str] = set()
+
+    for name in runtime_names:
+        if name in static_names:
+            common.add(name)
+        elif name.split(".")[0] in stdlib:
+            stdlib_only.add(name)
+        else:
+            missing.add(name)
+
+    # A package whose own submodule is reported is redundant: importing the
+    # submodule pulls the package in, and listing both clutters the config.
+    missing = {name for name in missing if not any(
+        other != name and other.startswith(name + ".") for other in missing
+    )}
+
+    return DiffResult(
+        missing=sorted(missing),
+        stdlib_only=sorted(stdlib_only),
+        common=sorted(common),
+    )

hookfix/errors.py

@@ -0,0 +1,19 @@
+"""Exceptions raised by hookfix."""
+
+from __future__ import annotations
+
+
+class HookfixError(Exception):
+    """Base class for every error hookfix raises deliberately.
+
+    The CLI catches this and prints the message without a traceback, so
+    user-facing failures stay readable.
+    """
+
+
+class TraceError(HookfixError):
+    """The traced program could not be run or its trace could not be collected."""
+
+
+class ScanError(HookfixError):
+    """The static scan could not complete."""

hookfix/model.py

@@ -0,0 +1,135 @@
+"""Shared data model for hookfix results.
+
+The types here are deliberately plain dataclasses with ``to_dict``/``from_dict``
+so that a trace or report can be serialised to JSON, committed as a CI artifact,
+and re-read later on a different machine.
+"""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+#: Schema version for the JSON artefacts we write. Bump when the shape changes
+#: in a way that older readers cannot understand.
+SCHEMA_VERSION = 1
+
+
+@dataclass
+class DynamicSite:
+    """A call site in the source that imports a module at runtime.
+
+    These are the places static analysis is blind to. Recording them lets the
+    report point at the exact line responsible for a module that only appears
+    at runtime.
+    """
+
+    path: str
+    lineno: int
+    col: int
+    #: ``importlib.import_module``, ``__import__``, ``exec`` or ``eval``.
+    kind: str
+    #: The literal argument, when it could be resolved statically.
+    target: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> DynamicSite:
+        return cls(**data)
+
+
+@dataclass
+class StaticResult:
+    """What a static scan of the source tree can see."""
+
+    #: Top-level module names referenced by ``import`` statements.
+    imports: list[str] = field(default_factory=list)
+    #: Locations of dynamic import calls.
+    dynamic_sites: list[DynamicSite] = field(default_factory=list)
+    #: Files that were scanned.
+    files: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": SCHEMA_VERSION,
+            "imports": self.imports,
+            "dynamic_sites": [site.to_dict() for site in self.dynamic_sites],
+            "files": self.files,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> StaticResult:
+        return cls(
+            imports=list(data.get("imports", [])),
+            dynamic_sites=[DynamicSite.from_dict(d) for d in data.get("dynamic_sites", [])],
+            files=list(data.get("files", [])),
+        )
+
+
+@dataclass
+class TraceResult:
+    """What actually happened when the program ran."""
+
+    #: Every fully-qualified module name the interpreter imported.
+    modules: list[str] = field(default_factory=list)
+    #: ``name -> file`` for modules that reported a filesystem origin.
+    origins: dict[str, str] = field(default_factory=dict)
+    #: Interpreter version the trace was taken under.
+    python: str = field(default_factory=lambda: sys.version.split()[0])
+    #: Exit status of the traced program.
+    returncode: int = 0
+
+    @property
+    def top_level(self) -> list[str]:
+        """Top-level names only (``a.b.c`` collapses to ``a``), sorted."""
+        return sorted({name.split(".")[0] for name in self.modules})
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": SCHEMA_VERSION,
+            "python": self.python,
+            "returncode": self.returncode,
+            "modules": self.modules,
+            "origins": self.origins,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> TraceResult:
+        return cls(
+            modules=list(data.get("modules", [])),
+            origins=dict(data.get("origins", {})),
+            python=data.get("python", ""),
+            returncode=int(data.get("returncode", 0)),
+        )
+
+
+@dataclass
+class DiffResult:
+    """Modules imported at runtime that static analysis could not see."""
+
+    #: Top-level names present at runtime but absent from the static scan.
+    missing: list[str] = field(default_factory=list)
+    #: Runtime-only names that live in the standard library. Informational:
+    #: a freezer normally bundles these already.
+    stdlib_only: list[str] = field(default_factory=list)
+    #: Names seen by both, for context.
+    common: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": SCHEMA_VERSION,
+            "missing": self.missing,
+            "stdlib_only": self.stdlib_only,
+            "common": self.common,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> DiffResult:
+        return cls(
+            missing=list(data.get("missing", [])),
+            stdlib_only=list(data.get("stdlib_only", [])),
+            common=list(data.get("common", [])),
+        )

hookfix/report.py

@@ -0,0 +1,89 @@
+"""Render results as a human-readable report."""
+
+from __future__ import annotations
+
+from .model import DiffResult, StaticResult, TraceResult
+
+
+def _plural(count: int, singular: str, plural: str | None = None) -> str:
+    word = singular if count == 1 else (plural or singular + "s")
+    return f"{count} {word}"
+
+
+def format_report(
+    *,
+    trace: TraceResult,
+    static: StaticResult,
+    result: DiffResult,
+    script: str,
+) -> str:
+    """Build the multi-section report printed by ``hookfix run``."""
+    lines: list[str] = []
+
+    lines.append("hookfix report")
+    lines.append("=" * 14)
+    lines.append("")
+    lines.append(f"script        {script}")
+    lines.append(f"python        {trace.python}")
+    lines.append(f"exit status   {trace.returncode}")
+    lines.append(
+        f"scanned       {_plural(len(static.files), 'file')}, "
+        f"{_plural(len(static.imports), 'static import')}"
+    )
+    lines.append(f"observed      {_plural(len(trace.modules), 'module')} imported at runtime")
+    lines.append("")
+
+    if not result.missing:
+        lines.append("No hidden imports found.")
+        lines.append("")
+        lines.append(
+            "Every third-party module this run imported is also visible to a "
+            "static scan, so the build should already include it."
+        )
+    else:
+        lines.append(f"Hidden imports ({len(result.missing)})")
+        lines.append("-" * (16 + len(str(len(result.missing)))))
+        for name in result.missing:
+            lines.append(f"  {name}")
+        lines.append("")
+        lines.append(
+            "These modules were imported at runtime but are invisible to a "
+            "static scan. Add them to your build:"
+        )
+        lines.append("")
+        for name in result.missing:
+            lines.append(f"  pyinstaller --hidden-import={name} ...")
+        lines.append("")
+        lines.append("Or generate a hook file for all of them at once:")
+        lines.append("")
+        lines.append("  hookfix fix")
+
+    if result.stdlib_only:
+        lines.append("")
+        lines.append(f"Standard library only ({len(result.stdlib_only)})")
+        lines.append("-" * (23 + len(str(len(result.stdlib_only)))))
+        lines.append("  " + ", ".join(result.stdlib_only))
+        lines.append("")
+        lines.append(
+            "Imported at runtime, but part of the standard library. A freezer "
+            "bundles these already; listed for completeness."
+        )
+
+    if static.dynamic_sites:
+        lines.append("")
+        lines.append(f"Dynamic import sites ({len(static.dynamic_sites)})")
+        lines.append("-" * (22 + len(str(len(static.dynamic_sites)))))
+        for site in static.dynamic_sites[:20]:
+            location = f"{site.path}:{site.lineno}:{site.col}"
+            target = f" -> {site.target!r}" if site.target else ""
+            lines.append(f"  {location}  {site.kind}{target}")
+        if len(static.dynamic_sites) > 20:
+            lines.append(f"  ... and {len(static.dynamic_sites) - 20} more")
+        lines.append("")
+        lines.append(
+            "These call sites are why the imports above are invisible to "
+            "static analysis."
+        )
+
+    lines.append("")
+    return "\n".join(lines)

hookfix/scanner.py

@@ -0,0 +1,164 @@
+"""Static analysis of a source tree.
+
+This module reproduces the part of the problem freezers already solve: reading
+``import`` statements out of source files. hookfix needs it so that it can
+subtract the statically visible imports from the runtime trace and leave only
+the imports the build is actually missing.
+
+We parse with :mod:`ast` rather than regular expressions so that imports inside
+functions, conditionals and ``try`` blocks are all found, and so that the
+location of every dynamic import call can be reported precisely.
+"""
+
+from __future__ import annotations
+
+import ast
+import os
+from collections.abc import Iterable
+from pathlib import Path
+
+from .errors import ScanError
+from .model import DynamicSite, StaticResult
+
+#: Functions that import a module from a string. ``importlib.import_module``
+#: and ``__import__`` are the common ones; ``exec``/``eval`` can execute an
+#: import statement assembled at runtime.
+_DYNAMIC_CALLS = {
+    ("importlib", "import_module"),
+    ("__import__", None),
+    ("builtins", "__import__"),
+}
+
+_EXEC_CALLS = {"exec", "eval"}
+
+_DEFAULT_EXCLUDES = {
+    ".git",
+    ".hg",
+    ".svn",
+    ".venv",
+    "venv",
+    "env",
+    "build",
+    "dist",
+    "__pycache__",
+    "node_modules",
+    ".tox",
+    ".nox",
+    ".mypy_cache",
+    ".ruff_cache",
+    ".pytest_cache",
+    ".hookfix",
+}
+
+
+def _iter_python_files(root: Path, excludes: set[str]) -> Iterable[Path]:
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = sorted(d for d in dirnames if d not in excludes and not d.startswith("."))
+        for filename in sorted(filenames):
+            if filename.endswith(".py"):
+                yield Path(dirpath) / filename
+
+
+def _call_name(node: ast.Call) -> list[str]:
+    """Return the dotted components of a call target, e.g. ``["importlib", "import_module"]``."""
+    func = node.func
+    parts: list[str] = []
+    while isinstance(func, ast.Attribute):
+        parts.append(func.attr)
+        func = func.value
+    if isinstance(func, ast.Name):
+        parts.append(func.id)
+        return list(reversed(parts))
+    return []
+
+
+def _literal_arg(node: ast.Call) -> str | None:
+    if not node.args:
+        return None
+    first = node.args[0]
+    if isinstance(first, ast.Constant) and isinstance(first.value, str):
+        return first.value
+    return None
+
+
+def _scan_tree(tree: ast.AST, relpath: str) -> tuple[set[str], list[DynamicSite]]:
+    imports: set[str] = set()
+    sites: list[DynamicSite] = []
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                # Keep the fully-qualified name: ``import a.b`` tells a freezer
+                # about ``a.b``, and the differ compares full names.
+                imports.add(alias.name)
+        elif isinstance(node, ast.ImportFrom):
+            # ``from . import x`` has module=None and level>0; that is a
+            # relative import and never a missing third-party dependency.
+            if node.level == 0 and node.module:
+                imports.add(node.module)
+                for alias in node.names:
+                    if alias.name != "*":
+                        imports.add(f"{node.module}.{alias.name}")
+        elif isinstance(node, ast.Call):
+            parts = _call_name(node)
+            if not parts:
+                continue
+            dotted = tuple(parts[-2:]) if len(parts) >= 2 else (parts[0], None)
+            simple = parts[-1]
+            if dotted in _DYNAMIC_CALLS or (simple == "__import__" and len(parts) == 1):
+                sites.append(
+                    DynamicSite(
+                        path=relpath,
+                        lineno=node.lineno,
+                        col=node.col_offset,
+                        kind=".".join(parts),
+                        target=_literal_arg(node),
+                    )
+                )
+            elif simple in _EXEC_CALLS:
+                sites.append(
+                    DynamicSite(
+                        path=relpath,
+                        lineno=node.lineno,
+                        col=node.col_offset,
+                        kind=simple,
+                        target=_literal_arg(node),
+                    )
+                )
+
+    return imports, sites
+
+
+def scan(root: os.PathLike[str] | str, excludes: Iterable[str] = ()) -> StaticResult:
+    """Scan ``root`` for import statements and dynamic import call sites."""
+    root_path = Path(root).resolve()
+    if not root_path.exists():
+        raise ScanError(f"path does not exist: {root_path}")
+
+    exclude_set = set(_DEFAULT_EXCLUDES) | set(excludes)
+    all_imports: set[str] = set()
+    all_sites: list[DynamicSite] = []
+    scanned: list[str] = []
+
+    for path in _iter_python_files(root_path, exclude_set):
+        relpath = str(path.relative_to(root_path))
+        try:
+            source = path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        try:
+            tree = ast.parse(source, filename=str(path))
+        except SyntaxError:
+            # A file we cannot parse is not a reason to fail the whole scan;
+            # a freezer would report it separately.
+            continue
+        imports, sites = _scan_tree(tree, relpath)
+        all_imports |= imports
+        all_sites.extend(sites)
+        scanned.append(relpath)
+
+    return StaticResult(
+        imports=sorted(all_imports),
+        dynamic_sites=all_sites,
+        files=scanned,
+    )

hookfix/spec_writer.py

@@ -0,0 +1,41 @@
+"""Turn a diff result into something a freezer understands."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+_HEADER = (
+    "# Generated by hookfix. https://github.com/sqmyou/hookfix\n"
+    "#\n"
+    "# These modules were imported at runtime by the traced program but are not\n"
+    "# reachable from a static scan of the source, so PyInstaller would omit them.\n"
+    "# Review the list before committing: it reflects one execution of the program.\n"
+)
+
+
+def render_hook_file(modules: Sequence[str], *, module_name: str | None = None) -> str:
+    """Render a PyInstaller hook file (``hook-<name>.py``).
+
+    A hook is the reusable form of ``--hidden-import``: it applies automatically
+    whenever the named module is imported, including inside a frozen build.
+    """
+    title = module_name or "your_app"
+    body = "\n".join(f"    {name!r}," for name in modules) or "    # (none)"
+    return (
+        f"{_HEADER}"
+        f"# hook-{title}.py\n"
+        f"\n"
+        f"hiddenimports = [\n"
+        f"{body}\n"
+        f"]\n"
+    )
+
+
+def render_spec_patch(modules: Sequence[str]) -> str:
+    """Render the ``hiddenimports`` line to paste into an existing ``.spec`` file.
+
+    PyInstaller's generated spec files already contain a ``hiddenimports = []``
+    entry; this is the drop-in replacement for it.
+    """
+    body = "\n".join(f"    {name!r}," for name in modules) or "    # (none)"
+    return f"hiddenimports = [\n{body}\n]\n"

hookfix/tracer.py

@@ -0,0 +1,125 @@
+"""Runtime import tracer.
+
+The tracer works by installing a :class:`importlib.abc.MetaPathFinder` at the
+front of :data:`sys.meta_path`. Every module resolution that goes through the
+import system passes through the finders in ``sys.meta_path``, so a finder
+placed at the front observes imports that originate from an ``import``
+statement, from :func:`importlib.import_module`, from :func:`__import__`, and
+from lazy ``__getattr__`` loaders alike.
+
+Why not CPython audit hooks? The ``import`` audit event is raised only on the
+``import`` statement / ``__import__`` path. :func:`importlib.import_module`
+calls the internal ``_gcd_import`` directly and never raises it, which is
+precisely the dynamic case that breaks frozen builds. A meta path finder has no
+such blind spot.
+
+The finder records each module name the first time it is resolved, together
+with the file it came from. Modules already present in :data:`sys.modules`
+before the tracer is installed are not seen, so the tracer must be installed
+before the program under test runs.
+"""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable
+from typing import Any
+
+from .errors import TraceError
+
+
+class ImportTracer:
+    """Record module imports performed by the running interpreter."""
+
+    def __init__(self) -> None:
+        self.modules: set[str] = set()
+        self.origins: dict[str, str] = {}
+        self._installed = False
+
+    def install(self) -> None:
+        """Insert the recording finder at the front of ``sys.meta_path``."""
+        if self._installed:
+            raise TraceError("ImportTracer.install() may only be called once")
+        if not hasattr(sys, "meta_path"):
+            raise TraceError("this interpreter does not provide sys.meta_path")
+        sys.meta_path.insert(0, _RecordingFinder(self))
+        self._installed = True
+
+    def record(self, name: str, origin: str | None) -> None:
+        self.modules.add(name)
+        if origin and name not in self.origins:
+            self.origins[name] = origin
+
+
+class _RecordingFinder:
+    """A meta path finder that records names and delegates to the real finders.
+
+    It must reproduce the search the interpreter would otherwise perform, so it
+    walks the remaining ``sys.meta_path`` entries in order and returns the first
+    spec any of them produces. Returning a spec of our own, or delegating to a
+    single finder, would break built-in and frozen modules.
+    """
+
+    def __init__(self, tracer: ImportTracer) -> None:
+        self._tracer = tracer
+
+    def find_spec(
+        self,
+        fullname: str,
+        path: Any | None = None,
+        target: Any | None = None,
+    ) -> Any:
+        for finder in list(sys.meta_path):
+            if finder is self:
+                continue
+            find_spec = getattr(finder, "find_spec", None)
+            if find_spec is None:
+                continue
+            spec = find_spec(fullname, path, target)
+            if spec is not None:
+                self._tracer.record(fullname, getattr(spec, "origin", None))
+                return spec
+        # Nothing could resolve it. Record the attempt so that a name which is
+        # imported dynamically but absent from the environment is still visible.
+        self._tracer.record(fullname, None)
+        return None
+
+
+def traced_run(target: Callable[..., int], *args: Any, **kwargs: Any) -> tuple[ImportTracer, int]:
+    """Run ``target`` under a tracer and return ``(tracer, returncode)``."""
+    tracer = ImportTracer()
+    tracer.install()
+    try:
+        returncode = target(*args, **kwargs) or 0
+    except SystemExit as exc:  # a program is allowed to call sys.exit()
+        code = exc.code
+        if code is None:
+            returncode = 0
+        elif isinstance(code, int):
+            returncode = code
+        else:
+            print(code, file=sys.stderr)
+            returncode = 1
+    return tracer, returncode
+
+
+def parse_audit_log(text: str) -> tuple[set[str], dict[str, str]]:
+    """Parse the line-oriented log written by the subprocess bootstrap.
+
+    Each line is ``module<TAB>origin`` with an empty origin when the import
+    machinery did not report a file. This keeps the child process free of any
+    dependency on the rest of hookfix.
+    """
+    modules: set[str] = set()
+    origins: dict[str, str] = {}
+    for line in text.splitlines():
+        if not line.strip():
+            continue
+        name, _, origin = line.partition("\t")
+        name = name.strip()
+        if not name:
+            continue
+        modules.add(name)
+        if origin and name not in origins:
+            origins[name] = origin
+    return modules, origins

hookfix-0.1.0.dist-info/METADATA

@@ -0,0 +1,225 @@
+Metadata-Version: 2.5
+Name: hookfix
+Version: 0.1.0
+Summary: Find the hidden imports that break your frozen Python app.
+Project-URL: Homepage, https://github.com/sqmyou/hookfix
+Project-URL: Repository, https://github.com/sqmyou/hookfix
+Project-URL: Changelog, https://github.com/sqmyou/hookfix/blob/main/CHANGELOG.md
+Author-email: sqm <sqmyou@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bundling,freeze,hidden-imports,nuitka,packaging,pyinstaller
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# hookfix
+
+**Find the hidden imports that break your frozen Python app.**
+
+[![CI](https://github.com/sqmyou/hookfix/actions/workflows/ci.yml/badge.svg)](https://github.com/sqmyou/hookfix/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/hookfix.svg)](https://pypi.org/project/hookfix/)
+[![Python versions](https://img.shields.io/pypi/pyversions/hookfix.svg)](https://pypi.org/project/hookfix/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+---
+
+You build your app, it works perfectly. You freeze it with PyInstaller or
+Nuitka, ship the binary, and it dies on a user's machine with:
+
+```
+ModuleNotFoundError: No module named 'your_plugin'
+```
+
+The module is installed. It is in your source tree. It just never appears in an
+`import` statement that a static analyser can see — it is pulled in by
+`importlib.import_module`, a plugin registry, an entry point, or a
+`__getattr__` on a package. Freezers trace imports by reading source, so they
+miss it, and you get to add `--hidden-import` flags one error report at a time.
+
+`hookfix` takes the other route. It **runs** your program, watches every module
+the interpreter actually imports, subtracts the imports that are visible to a
+static scan, and hands you the difference — the hidden imports, ready to paste
+into your build.
+
+```console
+$ hookfix run app.py --path .
+
+hookfix report
+==============
+
+script        /home/you/app/app.py
+python        3.12.4
+exit status   0
+scanned       12 files, 34 static imports
+observed      87 modules imported at runtime
+
+Hidden imports (2)
+------------------
+  plugins.report
+  yaml
+
+These modules were imported at runtime but are invisible to a static scan.
+Add them to your build:
+
+  pyinstaller --hidden-import=plugins.report --hidden-import=yaml ...
+
+Or generate a hook file for all of them at once:
+
+  hookfix fix
+
+Dynamic import sites (2)
+------------------------
+  app.py:41:12         importlib.import_module
+  plugins/load.py:9:5  __import__
+
+These call sites are why the imports above are invisible to static analysis.
+```
+
+## Why not just use audit hooks?
+
+The obvious way to watch imports is a CPython audit hook
+([PEP 578](https://peps.python.org/pep-0578/)) listening for the `import`
+event. It does not work, and the reason is subtle enough to be worth stating:
+
+```python
+import importlib
+importlib.import_module("plugins.report")   # does NOT raise the import event
+__import__("plugins.report")                # raises it
+import plugins.report                       # raises it
+```
+
+`importlib.import_module` calls the internal `_gcd_import` directly and never
+raises the audit event. Since `importlib.import_module` is *the* standard way to
+load a module dynamically, an audit-hook-based tracer has a blind spot over
+precisely the case it is meant to catch.
+
+`hookfix` installs an `importlib.abc.MetaPathFinder` at the front of
+`sys.meta_path` instead. Every module resolution that goes through the import
+system passes through `sys.meta_path`, whatever triggered it — so statements,
+`importlib`, `__import__` and lazy loaders are all observed.
+
+## Installation
+
+```console
+pip install hookfix
+```
+
+`hookfix` has no runtime dependencies and needs Python 3.10 or newer.
+
+## Usage
+
+### `hookfix run` — trace a program
+
+```console
+hookfix run app.py --path .
+```
+
+Runs `app.py` under the tracer and prints the report above. `--path` sets the
+directory to scan statically (default: the script's directory). Arguments after
+`--` are passed through to your program:
+
+```console
+hookfix run app.py -- --config prod.yaml
+```
+
+Useful flags:
+
+| Flag | Meaning |
+| --- | --- |
+| `--path DIR` | directory to scan statically (default: the script's directory) |
+| `--exclude NAME` | skip a directory or module while scanning (repeatable) |
+| `--trace-out FILE` | save the trace as JSON for later use |
+| `--json` | print the report as JSON instead of text |
+| `--quiet` | suppress the traced program's own output |
+
+### `hookfix diff` — compare a saved trace against source
+
+```console
+hookfix run app.py --trace-out trace.json --quiet
+hookfix diff trace.json --path .
+```
+
+Re-runs the comparison without executing the program again. Handy in CI, where
+you want to trace once and check the result from a different step.
+
+### `hookfix fix` — generate build configuration
+
+```console
+hookfix fix trace.json --module app            # -> hook-app.py
+hookfix fix trace.json --module app -o out/    # -> out/hook-app.py
+hookfix fix trace.json --spec                  # -> hiddenimports = [...] snippet
+```
+
+`--module app` writes a PyInstaller hook file, the reusable form of
+`--hidden-import`. `--spec` prints just the `hiddenimports = [...]` list to drop
+into an existing `.spec` file.
+
+## What it does and does not do
+
+**It reports what one run actually imported.** That is the honest boundary of
+any runtime tool. If a code path never executed — a plugin for a mode you did
+not exercise, a platform-specific branch — its imports will not appear.
+
+So: run `hookfix` against the widest set of inputs you can, ideally the same
+ones your smoke tests use. The output tells you which call sites are dynamic, so
+you can see what you might have missed. Treat the generated hook file as a
+starting point to review, not as a finished artefact — the header says as much.
+
+It also cannot tell you about data files, native libraries, or metadata that a
+freezer might drop. It is specifically about imports.
+
+## How it works
+
+1. **Trace.** The CLI spawns a child process (`python -m hookfix._bootstrap`)
+   that installs a recording meta path finder and then runs your script with
+   `runpy`, mimicking a plain `python script.py` invocation. Every resolved
+   module is logged as `name<TAB>origin`.
+
+2. **Scan.** `hookfix` walks the source tree with `ast` and collects every
+   `import` statement, plus the location of every dynamic import call site.
+
+3. **Diff.** The runtime modules minus the statically visible ones are the
+   hidden imports. Standard-library modules are split out (a freezer bundles
+   those anyway) and import-machinery internals are filtered as noise.
+
+4. **Report.** The remainder is printed, or rendered as a hook file or spec
+   snippet.
+
+Everything is serialisable: `--trace-out` writes a versioned JSON document, and
+`diff`/`fix` read it back, so a trace taken on one machine can be inspected on
+another.
+
+## Development
+
+```console
+git clone https://github.com/sqmyou/hookfix
+cd hookfix
+python -m pip install -e ".[dev]"
+python -m pytest
+```
+
+The test suite includes a fixture (`tests/fixtures/dynamic_app`) that loads a
+plugin through `importlib.import_module` — the case that motivated the whole
+tool. `python -m ruff check src tests` and `python -m mypy` must both pass.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

hookfix-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+hookfix/__init__.py,sha256=g7shgfLSFdnAAblS0OHfZEPI0GaWe8YgpLm-99cxxPQ,631
+hookfix/__main__.py,sha256=1I0yUuTSpAXxOzfwFAL0pP_F_PnB_bJgjuTy66SUB9E,115
+hookfix/_bootstrap.py,sha256=9gSQDcEKbd-UkCJlQXIfcaQtJYRC2Lu1njZDpSk8Lgg,2541
+hookfix/cli.py,sha256=9-vFfpnGfPOlg0N_63XAHCPRJ6zXEQ4SdIbDu4ki2Hc,8398
+hookfix/differ.py,sha256=pjy7UG8nk0HO_94JrNyFHaWXQDxZFb4tPPkxWe_Gr3k,2299
+hookfix/errors.py,sha256=tgxIrPl-Ei32z3HtBMSsMjy7c_V8ng3jlh4Ihu1Y2eY,485
+hookfix/model.py,sha256=X7ua-q_NVHXzxL9o7l1DeFEEqvfLSKdbqo6nMF_4Uk8,4481
+hookfix/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hookfix/report.py,sha256=XXfrzYT8oj3KWEMv6U1NC-18kw4hZ1sN3BI9doOsjto,3233
+hookfix/scanner.py,sha256=_SapnnfsjHagoQhN5aKAYVwaWwMWwEOvJYSAA3xyO6c,5476
+hookfix/spec_writer.py,sha256=MVuxxoIOG-xNlFiHE5OojX003zHnDdc3kPwbNCoh7tw,1467
+hookfix/tracer.py,sha256=6Q9SYmotUC0W_g_3sBnDKBAnf7UFt_W0IrT9D4-9Or4,4651
+hookfix-0.1.0.dist-info/METADATA,sha256=bs-XIdbNouAbYvYlQTbwSIqB6wvDGSSykf4OoO_0RUA,8176
+hookfix-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+hookfix-0.1.0.dist-info/entry_points.txt,sha256=vSzIogL00l8T4sP5iRP2loWuCo419JulLgZ5MGwEGz0,45
+hookfix-0.1.0.dist-info/licenses/LICENSE,sha256=3dyz4DxrJIHePfCQ--8M4S9LtLEO9d3C7tV5a4ebd1Y,1060
+hookfix-0.1.0.dist-info/RECORD,,

hookfix-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

hookfix-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+hookfix = hookfix.cli:main

hookfix-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sqm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.