[trissim]

The ratchet says which line got worse; this makes it also say how to fix it, as a Nominal Refactor Advisor plan you can preview or apply.

What it adds

tools/repairs.py

• Repair (a DeclaredFamily) declares the located measure it removes (repairs = FunctionLocalImport).
• It writes one NRA operation per occurrence it can remove, and keeps each other occurrence with the reason it stays.
• NRA simulates the plan, so the diff shows before anything is written.
• --apply goes through NRA's source-revision guards, then runs ruff's import sorter on the touched files. Black runs only on files Black already accepted.

python tools/repairs.py --root src --base origin/main --head HEAD   # the files whose count grew
python tools/repairs.py --root src --all --apply

ImportHoist moves a function-local import to its module's top. It refuses when a module-level import cycle runs through the import. It judges with every accepted move already in the load graph, because two local imports that name each other each pass alone and deadlock together. Other reasons it keeps an import: it is third-party, the module binds the name another way, the function rebinds the name, or it is not one plain line.

tools/module_layers.py: Import is now a family whose members say whether they run at module load:

• LoadTimeImport
• CallTimeImport
• CheckerImport, for imports under if TYPE_CHECKING:

This also fixes a bug. The old visitor counted a function's decorators and default arguments as call-time, but those run when the def runs. Only the body is call-time now. Package.load_graph() gives the edges that load their target. Package.unreached uses the same ImportGraph.

tools/typing_names.py: TypingImports and TypingReference move out of debt_ratchet, so module_layers resolves if TYPE_CHECKING: by what the name is bound to, not by its spelling, without importing the ratchet (0.04 s vs 0.95 s). Moving them made the ratchet count their debt from zero, so it is removed instead of carried:

• Untyped is the declared value for "bound to no typing declaration", replacing the None that dict.get returned.
• raw_access_count asks self.value is Untyped instead of getattr(value, "__module__", None).
• is_any lives on AnyReference in debt_ratchet, beside AnyName, the one measure that asks.
• StringSubscript and AnyName lines are identical on all 1,014 tracked files, except the one moved Any site.

docs/layout/MODULE_LAYERS.md: regenerated on current main. The committed copy had drifted 13 units, because --check (debt-ratchet.yml:64) checks client imports and never compares the doc with the generator. The doc depends on the stack clients' branch heads, so a freshness gate would fail PRs whenever Toad pushes. The honest options are to regenerate it, or to stop committing a generated copy. This PR regenerates it; deleting it is a separate call.

Dependency: NRA joins the dev extra as a direct git reference. CI installs with pip, which ignores uv sources, and a bare name would resolve on PyPI to whoever registers it.

Evidence

• tests/test_repairs.py: on a fixture package, the hoist moves the leaf import, keeps the import whose cycle runs through a module-level import, and the applied tree imports cleanly.
• tests/test_module_layers_loads.py: covers module-level, decorator, default, TYPE_CHECKING, body and lambda-body imports. It fails on the old visitor (decorator and default came out call-time).
• tests/test_module_layers_clients.py passes.
• module_layers.py --check: 0 missing modules, 0 missing names. Generator output is unchanged by the Import family (diffed against main's generator).
• On main, ImportHoist --all simulates 81 files changing. It leaves 160 imports for cycles, 42 that bind a name another way, 8 third-party, 4 that clash with another moved import, and 3 that are not one plain line. Move 225 function-local imports that nothing cycles back through to their module tops #3166 is that hoist applied.
• ruff is clean on every changed .py file. The N815 on the NodeVisitor alias carries a reasoned noqa, following the repo's idiom: NodeVisitor dispatches on those names.

NRA: uv.lock takes 3fc2f084, which ships py.typed (OpenHCSDev/NominalRefactorAdvisor#21), so mypy checks repairs.py against NRA's types. The placement bug found on the way, OpenHCSDev/NominalRefactorAdvisor#20 (ensure_import stops at if TYPE_CHECKING:), is fixed in OpenHCSDev/NominalRefactorAdvisor#22. Until that lands, the ruff I001 step after apply repairs the order.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Q8rVa3cPyXzpCKyR8XvM8W

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

[github-actions]

debt-tools at 0f54df8, every finding:

grew OwnTypeTest:tools/typing_names.py +1

[github-actions]

debt-src at 6951c22, every finding:

grew StringIdentity:tools/typing_names.py +1

[trissim]

Sent back at 4b5e52e (commander review, recorded in Core).

debt-tools is red on real slop: OwnTypeTest:tools/typing_names.py +1.

• class Untyped: has no members and is used as a bare marker. Readers check self.value is Untyped (typing_names.py:139) and is not Untyped (:110). That's IMPL-4, a half-finished family: the value can't say what it is, so every caller asks.
• Fix: a small Resolution family whose base methods are raw_access_count() and declares(obj). Declared(value) returns 0 and value is obj; Untyped() returns 1 and False. Bindings store the members, and both identity checks are deleted.

Also:

• Merge main. The head predates DonePhaseBroken counts sites by phase and site; fix main's ratchet red after #3151 #3216, so test_debt_ratchet.py fails 3 (StoreLockCalls.key / DonePhaseBroken.key) on reds main already fixed.
• The body says uv.lock pins NRA at 3fc2f084, but the lock pins a25f0a77.

What's good: ImportGraph replaces the copied reachability loop, the visitor counts def-time loads (decorators and defaults), and ImportHoist checks each move against the load graph with every other accepted move in it.

🤖 Generated with Claude Code

https://claude.ai/code/session_013ejYrMLnLWah8wCDDcb57V