hookfix 0.1.1__tar.gz → 0.1.2__tar.gz

{hookfix-0.1.1 → hookfix-0.1.2}/AGENTS.md

@@ -6,13 +6,15 @@ Repository notes for AI agents and contributors working on hookfix.
 
 `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.
+emits PyInstaller configuration for the difference. The reported list is
+freezer-agnostic; only `fix`'s output format is PyInstaller-specific (hook files
+and `.spec` snippets). There is no Nuitka config writer.
 
 ## Commands
 
 ```console
 python -m pip install -e ".[dev]"     # install with test/lint tools
-python -m pytest                      # test suite (28 tests)
+python -m pytest                      # test suite
 python -m ruff check src tests        # lint
 python -m mypy                        # strict type check (src/hookfix only)
 ```
@@ -67,6 +69,29 @@ Linux (3.10-3.13) plus macOS and Windows (3.12).
    fixed in 0.1.1 — hookfix's own advice produced a binary that crashed. `diff`
    raises rather than fall back to `imports`.
 
+6. **A hook file only fires for a module PyInstaller processes.** PyInstaller
+   reads `hook-NAME.py` while processing a module called `NAME`. The entry
+   script is never imported as a module — PyInstaller knows it as `__main__` —
+   so a hook named after the script file is silently dead. Key hooks to the
+   top-level package that owns the hidden imports (`hook-reporters.py`). If
+   nothing imports that package, no hook can cover its submodules: emit
+   `--hidden-import` instead. `hook_targets()` and `_cmd_fix` enforce this.
+
+7. **A name with no origin is not a hidden import.** The tracer records an
+   import it attempted but could not resolve with an empty origin. There is no
+   file to bundle, so `--hidden-import` cannot help; `diff` reports these under
+   `unresolved`. Namespace packages resolve without a file, so the tracer logs
+   their search location instead of leaving the origin empty.
+
+8. **Keep PyInstaller in the dev extras.** The freeze integration test is
+   skipped without it, and a skipped test is how the dead hook file shipped in
+   the first place. CI installs `.[dev]` and must actually run the freeze.
+
+9. **A leading underscore is not noise.** `_mylib._core` is a real private
+   package. Filter only `importlib`, hookfix's own modules, and stdlib/built-in
+   names — the latter by name, not by prefix, since `_csv` and `_sre` are
+   stdlib but `_priv` is not. A prefix rule here silently hides real gaps.
+
 ## Releasing
 
 `main` is the release branch. To cut a release:

hookfix-0.1.2/CHANGELOG.md

@@ -0,0 +1,141 @@
+# 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.2] - 2026-10-07
+
+### Fixed
+
+- **Packages sharing a filtered prefix were silently dropped.** The noise filter
+  used `startswith("importlib")` and `startswith("hookfix")`, so
+  `importlib_resources` — a real, widely used package — and any `hookfix_*` name
+  vanished from the report. The user saw a clean result and shipped a binary
+  that crashed. The filter now matches the exact top-level name, so
+  `importlib._bootstrap` is still noise but `importlib_resources` is not.
+- **Private packages were silently dropped.** The noise filter excluded every
+  module whose name started with `_`, so a legitimate package like `_mylib`
+  whose `_mylib._core` was loaded at runtime never appeared in the report and
+  the frozen app died with `ModuleNotFoundError`. A leading underscore is part
+  of a name, not a sign of import-machinery noise; only `importlib`, hookfix's
+  own modules, and standard-library/built-in names are filtered now. `_csv`,
+  `_sre` and friends are still excluded, by name rather than by prefix.
+- **Nested package entry points resolved to the wrong module.** For an app run
+  as `python -m a.b`, the tracer returned only the leaf name `b` and put the
+  package directory itself on `sys.path`, so the program could not import its
+  own package (`ModuleNotFoundError: No module named 'a'`) and the run died
+  before writing a trace. The dotted package name and its true parent directory
+  are now derived by walking up the `__init__.py` chain.
+- **`fix -o FILE` wrote one hook and silently dropped the rest.** When the
+  hidden imports belonged to several top-level packages, `-o` naming a single
+  file wrote only the first hook; the others were discarded, leaving a partial
+  fix that looked complete. It now refuses and names the packages, pointing at
+  a directory or `--spec` instead.
+- **`fix --module` could still write a dead hook file.** Naming a package that
+  nothing imports produced `hook-<name>.py` even though PyInstaller would never
+  process that name, repeating the exact bug this tool exists to catch. It now
+  fails with an explanation instead of emitting an inert artefact.
+- `hookfix fix` on a trace with no hidden imports printed "none of the hidden
+  imports are modules PyInstaller processes", which implies there were some.
+  It now says plainly that the trace found none.
+
+### Added
+
+- **`--entry` for `diff` and `fix`.** A trace records the entry-point path from
+  the machine that took it, so a trace copied into a different checkout failed
+  to re-scan. `--entry path/to/app.py` points at the entry script here.
+- **A child-process notice in the report.** The tracer only sees its own
+  interpreter, so a program that spawns another Python process (`subprocess`,
+  `multiprocessing`) and does dynamic imports there would otherwise report a
+  clean result. The report now warns that child imports are not traced.
+
+### Changed
+
+- **The generated hook file was never loaded.** `hookfix fix --module app`
+  wrote `hook-app.py`, and PyInstaller only reads `hook-NAME.py` while it is
+  processing a module called `NAME`. The entry script is never imported as a
+  module — PyInstaller knows it as `__main__` — so the hook was silently dead
+  and the binary still crashed with `ModuleNotFoundError`. The hook is now keyed
+  to the top-level package that owns the hidden imports (`hook-reporters.py`),
+  which PyInstaller does process, and `--module` refuses a name that matches the
+  entry script. Verified against a real PyInstaller build.
+- When *nothing* imports the top-level package, no hook can ever fire for its
+  submodules — that is precisely why they were invisible. `hookfix fix` now
+  writes no hook file in that case and prints the `--hidden-import` flags to use
+  instead, rather than emitting an artefact that does nothing.
+- **False negative for package entry points.** An app run as `python -m mypkg`
+  whose `mypkg/__main__.py` loaded `mypkg.worker` at runtime reported
+  `missing: []`, and the frozen binary then died. Two causes: the scanner
+  treated a reachable parent package as covering its submodules (so
+  `mypkg.worker` looked bundled), and the tracer put the package directory on
+  `sys.path`, so the traced program could not even resolve its own package. The
+  parent rule is gone and the tracer now handles a package `__main__.py`,
+  putting the package's parent on `sys.path` and running it with `runpy`.
+- A trace of a program that crashed is incomplete by construction, but
+  `hookfix run` printed a clean report and exited 0, so `missing: []` looked
+  like a clean bill of health. It now warns on stderr and propagates the exit
+  status.
+
+### Changed
+
+- Imports that nothing could resolve are no longer reported as hidden imports.
+  The tracer records attempted-but-unresolved names with an empty origin, and
+  they were listed as build settings even though there is no file to bundle.
+  They now appear under a separate *Unresolved imports* section, which points at
+  the environment rather than the build. Namespace packages, which resolve
+  without a file, record their search location so they are not mistaken for
+  missing.
+- The hidden-import list is grouped by top-level package in the report
+  (`yaml.*  (17 modules)`), and the copy-paste flags list only the leaves, so a
+  package hidden as many submodules no longer buries everything else.
+- The README and package docstring no longer imply Nuitka output. `run` and
+  `diff` are freezer-agnostic and their list suits any freezer; only `fix`
+  writes PyInstaller-specific files, and that is now stated where it matters.
+
+## [0.1.1] - 2026-10-07
+
+### Fixed
+
+- The diff compared a runtime trace against *every* import in the scanned tree,
+  but a freezer only bundles what it can reach from the entry point. A module
+  imported inside a dynamically loaded package — the case this tool exists for
+  — was treated as already covered and dropped from the report, so applying
+  hookfix's complete advice still produced a binary that crashed with
+  `ModuleNotFoundError`. The scanner now walks the static import graph from the
+  entry point (following relative imports and adding parent packages) and the
+  diff compares against that set.
+
+### Changed
+
+- The JSON trace format is now schema 2: traces record the entry point that was
+  traced. `hookfix diff` and `hookfix fix` reject a schema-1 trace instead of
+  guessing which modules are reachable. Re-run `hookfix run --trace-out` to
+  regenerate an old trace.
+
+## [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.1]: https://github.com/sqmyou/hookfix/releases/tag/v0.1.1
+[0.1.0]: https://github.com/sqmyou/hookfix/releases/tag/v0.1.0
+[Unreleased]: https://github.com/sqmyou/hookfix/compare/v0.1.1...HEAD

{hookfix-0.1.1 → hookfix-0.1.2}/DEMO.md

@@ -39,11 +39,12 @@ $ pyinstaller --onedir --name demo_broken --paths . main.py
 $ ./dist/demo_broken/demo_broken json
 Traceback (most recent call last):
   ...
-ModuleNotFoundError: No module named 'reporters'
+ModuleNotFoundError: No module named 'reporters.json_reporter'
 [PYI-2105:ERROR] Failed to execute script 'main' due to unhandled exception!
 ```
 
-The classic symptom, and the reason this tool exists.
+The classic symptom, and the reason this tool exists. The `reporters` package
+itself made it into the bundle — only the reporter chosen at runtime is missing.
 
 ## 3. hookfix finds the hidden import
 
@@ -56,7 +57,7 @@ hookfix report
 script        /tmp/hookfix_demo/main.py
 python        3.13.15
 exit status   0
-scanned       4 files, 4 static imports
+scanned       5 files, 6 static imports
 observed      18 modules imported at runtime
 
 Hidden imports (1)
@@ -68,9 +69,13 @@ Add them to your build:
 
   pyinstaller --hidden-import=reporters.json_reporter ...
 
+Or generate a hook file for all of them at once:
+
+  hookfix fix
+
 Dynamic import sites (1)
 ------------------------
-  main.py:25:12  importlib.import_module
+  main.py:31:11  importlib.import_module
 
 These call sites are why the imports above are invisible to static analysis.
 ```
@@ -84,18 +89,20 @@ hiddenimports = [
 ]
 ```
 
-or a ready-to-use hook file:
+or a ready-to-use hook file, keyed to the package PyInstaller processes:
 
 ```console
-$ hookfix fix trace.json --path . --module main -o hook-main.py
-wrote hook-main.py (1 hidden imports)
+$ hookfix fix trace.json --path . -o hooks/
+wrote hooks/hook-reporters.py (1 hidden imports)
 ```
 
 ## 5. The frozen binary works
 
+Freeze with only the generated hook applied — no `--hidden-import`:
+
 ```console
 $ pyinstaller --onedir --name demo_proof --paths . \
-      --hidden-import=reporters.json_reporter main.py
+      --additional-hooks-dir=hooks main.py
 $ ./dist/demo_proof/demo_proof json
 {
   "status": "ok",
@@ -103,6 +110,19 @@ $ ./dist/demo_proof/demo_proof json
 }
 ```
 
+`--additional-hooks-dir=hooks` is the whole difference. Without it the binary
+dies with `ModuleNotFoundError`; with it, PyInstaller processes `reporters`,
+reads `hook-reporters.py`, and pulls in `reporters.json_reporter`.
+
+Two things make this work, and both matter. The hook is named after
+`reporters`, a module PyInstaller processes — a hook named `hook-main.py` would
+never be read, because PyInstaller knows the entry script as `__main__`. And the
+app imports `reporters` itself, so there is a module for the hook to attach to.
+
+If your app never imports the package, no hook can help: pass the module with
+`--hidden-import` instead, which is unconditional. `hookfix fix` says so and
+prints the exact flags when that happens.
+
 ## What the demo also shows: the honest boundary
 
 The app has a second reporter, `text_reporter`, that the run above never

{hookfix-0.1.1 → hookfix-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hookfix
-Version: 0.1.1
+Version: 0.1.2
 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
@@ -25,6 +25,7 @@ Classifier: Topic :: Software Development :: Quality Assurance
 Requires-Python: >=3.10
 Provides-Extra: dev
 Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pyinstaller>=6; extra == 'dev'
 Requires-Dist: pytest-cov>=5; extra == 'dev'
 Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: ruff>=0.6; extra == 'dev'
@@ -35,8 +36,8 @@ Description-Content-Type: text/markdown
 **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/)
+[![PyPI](https://img.shields.io/pypi/v/hookfix.svg?style=flat)](https://pypi.org/project/hookfix/)
+[![Python versions](https://img.shields.io/pypi/pyversions/hookfix.svg?style=flat)](https://pypi.org/project/hookfix/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
 ---
@@ -85,6 +86,9 @@ Or generate a hook file for all of them at once:
 
   hookfix fix
 
+(That only works for modules PyInstaller actually processes. See
+[`hookfix fix`](#hookfix-fix--generate-build-configuration) for the details.)
+
 Dynamic import sites (2)
 ------------------------
   app.py:41:12         importlib.import_module
@@ -163,14 +167,53 @@ 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
+hookfix fix trace.json                        # -> hook-<package>.py on stdout
+hookfix fix trace.json -o hooks/              # -> hooks/hook-<package>.py
+hookfix fix trace.json --module reporters     # -> hook-reporters.py (explicit name)
+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.
+`--spec` prints just the `hiddenimports = [...]` list to drop into an existing
+`.spec` file, or to pass as `--hidden-import` flags. It always works.
+
+> **The generated fix is PyInstaller-specific.** `fix` writes PyInstaller hook
+> files and `.spec` snippets. `run` and `diff` are freezer-agnostic: the list
+> they report is exactly the set of modules missing from the build, and a Nuitka
+> user can feed that list to `--include-module` (or `--include-package`). There
+> is no Nuitka config writer yet.
+
+The hook file is the reusable form of `--hidden-import`, but it comes with a
+constraint worth understanding, because it is the difference between a build
+that works and one that fails silently:
+
+> PyInstaller reads `hook-NAME.py` only while it is processing a module called
+> `NAME`. A hook named after the entry script is never read — PyInstaller knows
+> the entry script as `__main__`, not by its file name.
+
+So a hook can only carry imports for a module PyInstaller already imports. The
+hidden imports are submodules (`reporters.json_reporter`), so `hookfix` keys the
+hook to the top-level package that owns them (`reporters`). That works when your
+program imports the package: PyInstaller processes `reporters`, reads
+`hook-reporters.py`, and picks up the submodule.
+
+It cannot work when *nothing* imports the package — which is precisely why the
+submodule was invisible in the first place. In that case `hookfix` writes no
+hook file and tells you to use `--hidden-import` instead, because a hook it
+wrote would be dead code:
+
+```console
+$ hookfix fix trace.json
+no hook file written: none of the hidden imports are modules PyInstaller
+processes, so a hook would never fire.
+
+1 module(s) cannot be covered by a hook (nothing imports them, so PyInstaller
+never processes them). Pass these instead:
+
+  pyinstaller --hidden-import=reporters.json_reporter ...
+```
+
+`--module NAME` overrides the name. It refuses a name that matches the entry
+script, since that hook would never be read.
 
 ## What it does and does not do
 
@@ -178,11 +221,28 @@ into an existing `.spec` file.
 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.
 
+**Child processes are not traced.** The tracer sees only the interpreter it
+runs in. If your program spawns another Python process (`subprocess`,
+`multiprocessing`) and that child does dynamic imports, those imports are not in
+the report. The report prints a *Child processes were used* notice when it sees
+`subprocess` or `multiprocessing` was imported, but it cannot tell whether a
+child actually ran. Trace a child script directly if it does the dynamic
+importing.
+
+**A moved trace needs `--entry`.** A trace records the entry-point path from the
+machine it was taken on, so re-scanning it from a different checkout fails with
+`entry point does not exist`. Pass `--entry path/to/app.py` to `diff` or `fix`
+to point at the entry script here.
+
 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.
 
+Imports that nothing could resolve are listed separately, under *Unresolved
+imports*. They are not build settings: there is no file to bundle, so the fix is
+to install the module (or accept that it is built in and always available).
+
 It also cannot tell you about data files, native libraries, or metadata that a
 freezer might drop. It is specifically about imports.
 
@@ -190,8 +250,10 @@ freezer might drop. It is specifically about imports.
 
 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`.
+   `runpy`, mimicking a plain `python script.py` invocation — or
+   `python -m package`, when the entry point is a package's `__main__.py`.
+   Every resolved module is logged as `name<TAB>origin`, and a module that
+   resolves without a file (a namespace package) logs its search location.
 
 2. **Scan.** `hookfix` walks the source tree with `ast`, collects every
    `import` statement, and records the location of every dynamic import call
@@ -202,7 +264,8 @@ freezer might drop. It is specifically about imports.
 
 3. **Diff.** The runtime modules minus the reachable ones are the hidden
    imports. Standard-library modules are split out (a freezer bundles those
-   anyway) and import-machinery internals are filtered as noise.
+   anyway), import-machinery internals are filtered as noise, and names that
+   resolved to no file are reported as unresolved rather than hidden.
 
 4. **Report.** The remainder is printed, or rendered as a hook file or spec
    snippet.

{hookfix-0.1.1 → hookfix-0.1.2}/README.md

@@ -3,8 +3,8 @@
 **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/)
+[![PyPI](https://img.shields.io/pypi/v/hookfix.svg?style=flat)](https://pypi.org/project/hookfix/)
+[![Python versions](https://img.shields.io/pypi/pyversions/hookfix.svg?style=flat)](https://pypi.org/project/hookfix/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
 ---
@@ -53,6 +53,9 @@ Or generate a hook file for all of them at once:
 
   hookfix fix
 
+(That only works for modules PyInstaller actually processes. See
+[`hookfix fix`](#hookfix-fix--generate-build-configuration) for the details.)
+
 Dynamic import sites (2)
 ------------------------
   app.py:41:12         importlib.import_module
@@ -131,14 +134,53 @@ 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
+hookfix fix trace.json                        # -> hook-<package>.py on stdout
+hookfix fix trace.json -o hooks/              # -> hooks/hook-<package>.py
+hookfix fix trace.json --module reporters     # -> hook-reporters.py (explicit name)
+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.
+`--spec` prints just the `hiddenimports = [...]` list to drop into an existing
+`.spec` file, or to pass as `--hidden-import` flags. It always works.
+
+> **The generated fix is PyInstaller-specific.** `fix` writes PyInstaller hook
+> files and `.spec` snippets. `run` and `diff` are freezer-agnostic: the list
+> they report is exactly the set of modules missing from the build, and a Nuitka
+> user can feed that list to `--include-module` (or `--include-package`). There
+> is no Nuitka config writer yet.
+
+The hook file is the reusable form of `--hidden-import`, but it comes with a
+constraint worth understanding, because it is the difference between a build
+that works and one that fails silently:
+
+> PyInstaller reads `hook-NAME.py` only while it is processing a module called
+> `NAME`. A hook named after the entry script is never read — PyInstaller knows
+> the entry script as `__main__`, not by its file name.
+
+So a hook can only carry imports for a module PyInstaller already imports. The
+hidden imports are submodules (`reporters.json_reporter`), so `hookfix` keys the
+hook to the top-level package that owns them (`reporters`). That works when your
+program imports the package: PyInstaller processes `reporters`, reads
+`hook-reporters.py`, and picks up the submodule.
+
+It cannot work when *nothing* imports the package — which is precisely why the
+submodule was invisible in the first place. In that case `hookfix` writes no
+hook file and tells you to use `--hidden-import` instead, because a hook it
+wrote would be dead code:
+
+```console
+$ hookfix fix trace.json
+no hook file written: none of the hidden imports are modules PyInstaller
+processes, so a hook would never fire.
+
+1 module(s) cannot be covered by a hook (nothing imports them, so PyInstaller
+never processes them). Pass these instead:
+
+  pyinstaller --hidden-import=reporters.json_reporter ...
+```
+
+`--module NAME` overrides the name. It refuses a name that matches the entry
+script, since that hook would never be read.
 
 ## What it does and does not do
 
@@ -146,11 +188,28 @@ into an existing `.spec` file.
 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.
 
+**Child processes are not traced.** The tracer sees only the interpreter it
+runs in. If your program spawns another Python process (`subprocess`,
+`multiprocessing`) and that child does dynamic imports, those imports are not in
+the report. The report prints a *Child processes were used* notice when it sees
+`subprocess` or `multiprocessing` was imported, but it cannot tell whether a
+child actually ran. Trace a child script directly if it does the dynamic
+importing.
+
+**A moved trace needs `--entry`.** A trace records the entry-point path from the
+machine it was taken on, so re-scanning it from a different checkout fails with
+`entry point does not exist`. Pass `--entry path/to/app.py` to `diff` or `fix`
+to point at the entry script here.
+
 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.
 
+Imports that nothing could resolve are listed separately, under *Unresolved
+imports*. They are not build settings: there is no file to bundle, so the fix is
+to install the module (or accept that it is built in and always available).
+
 It also cannot tell you about data files, native libraries, or metadata that a
 freezer might drop. It is specifically about imports.
 
@@ -158,8 +217,10 @@ freezer might drop. It is specifically about imports.
 
 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`.
+   `runpy`, mimicking a plain `python script.py` invocation — or
+   `python -m package`, when the entry point is a package's `__main__.py`.
+   Every resolved module is logged as `name<TAB>origin`, and a module that
+   resolves without a file (a namespace package) logs its search location.
 
 2. **Scan.** `hookfix` walks the source tree with `ast`, collects every
    `import` statement, and records the location of every dynamic import call
@@ -170,7 +231,8 @@ freezer might drop. It is specifically about imports.
 
 3. **Diff.** The runtime modules minus the reachable ones are the hidden
    imports. Standard-library modules are split out (a freezer bundles those
-   anyway) and import-machinery internals are filtered as noise.
+   anyway), import-machinery internals are filtered as noise, and names that
+   resolved to no file are reported as unresolved rather than hidden.
 
 4. **Report.** The remainder is printed, or rendered as a hook file or spec
    snippet.

{hookfix-0.1.1 → hookfix-0.1.2}/examples/demo_app/main.py

@@ -12,6 +12,12 @@ from __future__ import annotations
 import importlib
 import sys
 
+# The package itself is imported, so PyInstaller sees it and will read a
+# generated ``hook-reporters.py``. Which *reporter* runs is still decided at
+# runtime, and that module is never named in an import statement -- which is
+# exactly what a static scan cannot see.
+import reporters  # noqa: F401
+
 # A registry mapping a user-facing name to a module path. Nothing here is a
 # literal ``import``, so a static analyser cannot see what will be loaded.
 REPORTERS = {

{hookfix-0.1.1 → hookfix-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hookfix"
-version = "0.1.1"
+version = "0.1.2"
 description = "Find the hidden imports that break your frozen Python app."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -45,6 +45,10 @@ dev = [
     "pytest-cov>=5",
     "mypy>=1.10",
     "ruff>=0.6",
+    # The integration test freezes a real app and runs the binary. Without
+    # PyInstaller installed it is skipped, which is how a dead hook file shipped
+    # unnoticed. Keep it here so CI exercises the freeze.
+    "pyinstaller>=6",
 ]
 
 [project.urls]
@@ -58,6 +62,7 @@ dev = [
     "pytest-cov>=5",
     "mypy>=1.10",
     "ruff>=0.6",
+    "pyinstaller>=6",
 ]
 
 [tool.hatch.version]

{hookfix-0.1.1 → hookfix-0.1.2}/src/hookfix/__init__.py

@@ -8,9 +8,10 @@ the user's machine and not on yours.
 hookfix runs your program once under a meta path import tracer, records every
 module the interpreter actually imports, and compares that against the imports
 a freezer can reach from your entry point. The difference is exactly the set of
-modules your build is missing.
+modules your build is missing. That report is freezer-agnostic; ``hookfix fix``
+renders it as PyInstaller hook files or ``.spec`` snippets.
 """
 
-__version__ = "0.1.1"
+__version__ = "0.1.2"
 
 __all__ = ["__version__"]