hookfix 0.1.0__tar.gz

hookfix-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        include:
+          - os: macos-latest
+            python-version: "3.12"
+          - os: windows-latest
+            python-version: "3.12"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+      - name: Test
+        run: python -m pytest -q
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+      - name: Ruff
+        run: python -m ruff check src tests
+      - name: Mypy
+        run: python -m mypy

hookfix-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,48 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Check artefacts
+        run: |
+          python -m pip install --upgrade twine
+          python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # Trusted Publishing: PyPI verifies this workflow's OIDC identity, so no
+    # API token is stored in the repository. Configure the publisher at
+    # https://pypi.org/manage/account/publishing/ before the first release.
+    environment:
+      name: pypi
+      url: https://pypi.org/project/hookfix/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

hookfix-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+wheels/
+
+# Unit test / coverage reports
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+
+# Environments
+.venv/
+venv/
+env/
+ENV/
+
+# Tooling caches
+.mypy_cache/
+.ruff_cache/
+
+# hookfix's own working directory
+.hookfix/
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store

hookfix-0.1.0/AGENTS.md

@@ -0,0 +1,84 @@
+# AGENTS.md
+
+Repository notes for AI agents and contributors working on hookfix.
+
+## What this project is
+
+`hookfix` finds the imports that break frozen Python apps. It runs a program
+under a runtime import tracer, subtracts the imports a static scan can see, and
+emits PyInstaller/Nuitka configuration for the difference.
+
+## Commands
+
+```console
+python -m pip install -e ".[dev]"     # install with test/lint tools
+python -m pytest                      # test suite (28 tests)
+python -m ruff check src tests        # lint
+python -m mypy                        # strict type check (src/hookfix only)
+```
+
+All three must pass before a change is considered done. CI runs them on
+Linux (3.10-3.13) plus macOS and Windows (3.12).
+
+## Layout
+
+- `src/hookfix/` — src-layout package. No runtime dependencies; standard
+  library only.
+- `src/hookfix/tracer.py` — the technical heart. Records imports via a
+  `sys.meta_path` finder.
+- `src/hookfix/_bootstrap.py` — runs the target script in a child process.
+  Deliberately imports nothing from the rest of hookfix, so its own
+  dependencies are not mistaken for the user's.
+- `src/hookfix/scanner.py` — `ast`-based static scan.
+- `src/hookfix/differ.py` — runtime trace minus static imports.
+- `src/hookfix/spec_writer.py` — hook file / spec snippet rendering.
+- `tests/fixtures/dynamic_app/` — fixture that loads a plugin through
+  `importlib.import_module`.
+- `examples/demo_app/` — the app used in `DEMO.md`.
+
+## Things worth knowing before you change code
+
+1. **Do not switch the tracer back to CPython audit hooks.**
+   `importlib.import_module` calls `_gcd_import` directly and never raises the
+   `import` audit event, so audit hooks miss the exact dynamic case this tool
+   exists to catch. Verified on Python 3.13. A `sys.meta_path` finder sees
+   every path. `README.md` explains this with a runnable example.
+
+2. **Report fully-qualified module names.** PyInstaller needs
+   `--hidden-import=reporters.json_reporter`; the bare package name does not
+   pull in a submodule that nothing imports statically. This was a real bug,
+   caught only by testing against an actual PyInstaller build.
+
+3. **Verify against a real freeze.** The unit tests use a fixture, but the
+   bugs that mattered were found by actually building with PyInstaller. If you
+   change the differ, scanner or spec writer, freeze `examples/demo_app` and
+   confirm the binary runs.
+
+4. **The tool reports one execution.** An unexercised code path stays
+   invisible. That is the contract, documented in `README.md` and shown in
+   `DEMO.md`. Do not paper over it with guesswork.
+
+## Releasing
+
+`main` is the release branch. To cut a release:
+
+1. Bump `__version__` in `src/hookfix/__init__.py` (hatchling reads it from
+   there) and add a dated section to `CHANGELOG.md`.
+2. `python -m build && python -m twine check dist/*` — both must pass.
+3. Commit, push, then `git tag -a vX.Y.Z -m "..." && git push origin vX.Y.Z`.
+4. `gh release create vX.Y.Z --title ... --notes ...` — publishing the release
+   triggers `.github/workflows/publish.yml`, which builds and uploads to PyPI.
+
+Publishing uses PyPI Trusted Publishing (OIDC), so no API token is stored here.
+This requires a one-time setup on PyPI that only a human can do: at
+<https://pypi.org/manage/account/publishing/>, add a pending publisher with
+
+- PyPI project name: `hookfix`
+- Owner: `sqmyou`
+- Repository: `hookfix`
+- Workflow name: `publish.yml`
+- Environment: `pypi`
+
+Until that exists, the `publish` job fails with `invalid-publisher`. The
+`build` job still succeeds, so the artefacts can be checked without PyPI.
+

hookfix-0.1.0/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-10-07
+
+First release.
+
+### Added
+
+- `hookfix run <script>` — run a program under a runtime import tracer and
+  report the modules it imported that a static scan cannot see.
+- `hookfix diff <trace>` — re-compare a saved trace against the source tree.
+- `hookfix fix <trace>` — emit a PyInstaller hook file (`hook-<name>.py`) or a
+  `hiddenimports = [...]` snippet for an existing `.spec`.
+- Static scanner built on `ast`, reporting dynamic import call sites with exact
+  line and column numbers.
+- Versioned JSON trace format (`--trace-out`) so traces can be saved, inspected
+  and re-used across machines and CI steps.
+- `py.typed` marker, so downstream type checkers see the package's annotations.
+
+### Notes
+
+- No runtime dependencies; Python 3.10+.
+- The tracer records what a single execution imported. A code path that never
+  runs stays invisible; see "What it does and does not do" in the README.
+
+[0.1.0]: https://github.com/sqmyou/hookfix/releases/tag/v0.1.0
+[Unreleased]: https://github.com/sqmyou/hookfix/compare/v0.1.0...HEAD

hookfix-0.1.0/DEMO.md

@@ -0,0 +1,120 @@
+# Demo: a hidden import, end to end
+
+This is a real transcript, not a mock-up. Every command below was run against
+the app in `examples/demo_app`, which selects a reporter at runtime through
+`importlib.import_module` — the pattern static analysis cannot see.
+
+The point of the demo is the last step: `hookfix`'s output, applied to an
+actual PyInstaller build, turns a crashing binary into a working one.
+
+## The app
+
+```
+examples/demo_app/
+├── main.py                     # REPORTERS registry + importlib.import_module
+└── reporters/
+    ├── __init__.py
+    ├── json_reporter.py        # never named in an import statement
+    └── text_reporter.py
+```
+
+`main.py` maps `"json"` to `"reporters.json_reporter"` and loads it by name.
+Nothing in the source says `import reporters.json_reporter`, so PyInstaller's
+module graph never contains it.
+
+## 1. It works from source
+
+```console
+$ python main.py json
+{
+  "status": "ok",
+  "items": 3
+}
+```
+
+## 2. Freeze it, and it breaks
+
+```console
+$ pyinstaller --onedir --name demo_broken --paths . main.py
+$ ./dist/demo_broken/demo_broken json
+Traceback (most recent call last):
+  ...
+ModuleNotFoundError: No module named 'reporters'
+[PYI-2105:ERROR] Failed to execute script 'main' due to unhandled exception!
+```
+
+The classic symptom, and the reason this tool exists.
+
+## 3. hookfix finds the hidden import
+
+```console
+$ hookfix run main.py --path . --quiet --trace-out trace.json
+
+hookfix report
+==============
+
+script        /tmp/hookfix_demo/main.py
+python        3.13.15
+exit status   0
+scanned       4 files, 4 static imports
+observed      18 modules imported at runtime
+
+Hidden imports (1)
+-----------------
+  reporters.json_reporter
+
+These modules were imported at runtime but are invisible to a static scan.
+Add them to your build:
+
+  pyinstaller --hidden-import=reporters.json_reporter ...
+
+Dynamic import sites (1)
+------------------------
+  main.py:25:12  importlib.import_module
+
+These call sites are why the imports above are invisible to static analysis.
+```
+
+## 4. Generate the build configuration
+
+```console
+$ hookfix fix trace.json --path . --spec
+hiddenimports = [
+    'reporters.json_reporter',
+]
+```
+
+or a ready-to-use hook file:
+
+```console
+$ hookfix fix trace.json --path . --module main -o hook-main.py
+wrote hook-main.py (1 hidden imports)
+```
+
+## 5. The frozen binary works
+
+```console
+$ pyinstaller --onedir --name demo_proof --paths . \
+      --hidden-import=reporters.json_reporter main.py
+$ ./dist/demo_proof/demo_proof json
+{
+  "status": "ok",
+  "items": 3
+}
+```
+
+## What the demo also shows: the honest boundary
+
+The app has a second reporter, `text_reporter`, that the run above never
+exercised. It does not appear in the report, and the frozen binary still fails
+if you ask for it:
+
+```console
+$ ./dist/demo_proof/demo_proof text
+ModuleNotFoundError: No module named 'reporters.text_reporter'
+```
+
+That is not a bug — it is the contract. `hookfix` reports what a run actually
+imported. Trace the paths you care about (the same ones your smoke tests use),
+and the report tells you which call sites are dynamic so you can see what you
+might still be missing.

hookfix-0.1.0/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.

hookfix-0.1.0/PKG-INFO

@@ -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).