deterministic-refactor
Moved to living-architecture.
The dr-refactor, dr-mock-lint and dr-compliance commands ship in the
living-architecture package (uv tool install living-architecture), and the
skills are in its la Claude Code plugin (la:deterministic-refactor,
la:make-diff-compliant, la:make-refactor-target-compliant). This repository
is archived and no longer maintained.
Rename and move Python code with automatic import/reference rewriting — and,
the actual point, a deterministic check that the refactor left nothing
dangling.
The rename tool (rope) is best-effort: no refactoring tool reliably rewrites
every type-annotated obj.attr, super() call, and subclass override. So it is
never trusted — it is verified. A strict type-check proves no dangling static
reference remains; @typing.override turns a missed override into an error; a
mock-spec lint turns a missed dynamic (mock) reference into a failure. Green ⇒
provably no dangling reference.
Tools (pip install deterministic-refactor):
dr-refactor — rope mutator: rename / move-symbol / move-module
dr-mock-lint — fail on mocks not bound to a spec
dr-compliance — report the constructs that make a refactor un-verifiable
What a fully compliant repo must fulfill
A repo is refactor-verifiable when a missed rename is guaranteed to surface
as a failing check. That holds only when:
- Target code is typed. Functions annotated (params + return), class
attributes annotated, and every variable/parameter that holds an instance of
a class annotated. An unannotated
x.attr is unresolvable, so a miss there
is invisible — determinism is bought with type coverage. (dr-compliance +
Ruff ANN* enforce this.)
- A type checker runs against the project's own environment. mypy or
basedpyright resolving imports via the project venv — the same interpreter
the tests use — passing, or at a recorded baseline.
- Overrides are marked.
@typing.override on every override, with
reportImplicitOverride (basedpyright) or mypy strict enabled, so a base
rename that orphans an override is an error, not a silent break.
- Mocks are spec-bound. No bare
Mock()/MagicMock()/patch(); every
double bound via spec_set= / autospec=True / a Protocol fake. A stale
mock member then fails (AttributeError, or a type error for typed fakes).
(dr-mock-lint enforces this.)
- The gate is wired into CI/pre-commit. type-check (no new errors vs
baseline) +
dr-mock-lint + the test suite, on every change.
dr-compliance mechanically checks 1, 3-adjacent (via the type checker), and 4,
and reports each violation as file:line: <kind>: <message>.
Using it on an existing repo
1. One-time setup
-
Install the tools in a tooling venv (or uvx deterministic-refactor, or add
to the dev group).
-
Add a type checker to the project's dev dependencies, pointed at its venv —
it must resolve imports the way the tests do:
# pyproject.toml
[tool.basedpyright]
venvPath = "."
venv = ".venv"
pythonVersion = "3.11"
typeCheckingMode = "standard" # already errors on attribute access
reportImplicitOverride = "error"
(Equivalently mypy --strict --python-executable .venv/bin/python.)
-
Add dr-mock-lint <tests> and the type checker to .pre-commit-config.yaml
and CI. Record the current type-error set as the baseline — you do not
need a clean whole repo, only "no new errors" per change.
The mutator (rope) does not belong in the project's dependencies — it
reads source and needs nothing installed. Only the verifier needs the env.
2. Keep every PR compliant — skill make-diff-compliant
Bring exactly the files a PR touches up to the five conditions before it merges,
so compliance grows monotonically with the diff instead of requiring a big-bang
migration. The skill runs dr-compliance on the changed files, adds the missing
annotations / @override / mock specs, and loops until the type checker and
dr-mock-lint are clean on the diff. See skills/make-diff-compliant/.
3. Do a refactor — skill deterministic-refactor
Locate the symbol with the editor/LSP → dr-refactor dry-run → apply → run the
gate (type checker shows no new errors, dr-mock-lint passes, tests pass, grep
the string-only references no static tool sees) → review the diff. See
skills/deterministic-refactor/.
4. Make a refactor's blast radius compliant first — skill make-refactor-target-compliant
Before renaming X or X.attr, close the blind spots the gate would otherwise
miss: code that might reference the target but is currently invisible to the
checker — untyped parameters/variables that could hold an X, classes whose
attribute names match the target ("right-looking" names), subclasses missing
@override. The skill drives dr-compliance --attr <name> to enumerate those
sites, annotates them, and re-checks until the blast radius is fully typed —
so the post-rename gate is sound. See skills/make-refactor-target-compliant/.