diet-guard/docs/DOCS-patch-targets.md
Krzysztof kuhy Rudnicki abd8793e60
Some checks are pending
dependency freshness / dependencies on newest stable (push) Waiting to run
file-length / file length <= 250 lines (push) Waiting to run
md-naming / markdown naming convention (push) Waiting to run
pre-commit / pre-commit (${{ matrix.group }}) (mypy, mypy, ) (push) Waiting to run
pre-commit / pre-commit (${{ matrix.group }}) (pylint, pylint, ) (push) Waiting to run
pre-commit / pre-commit (${{ matrix.group }}) (rest, , mypy,pylint) (push) Waiting to run
Tests / test (push) Waiting to run
release-apk / release (APK) (push) Waiting to run
repo-contract / repo contract (push) Waiting to run
check_patch_targets: package as a CLI argument
The script hard-coded PACKAGE='diet_guard', so other guard repos could
not run it (build-background-service R3). PACKAGE is now a required
positional (no silent default: that is the fail-open shape the gate
guards against); --tests-root defaults to PACKAGE/tests. Targets match
PACKAGE or PACKAGE.*, so pkg_a no longer claims pkg_ab. Adoption
snippet in docs/DOCS-patch-targets.md. A shared
~/src/utils/patch_targets/ package is a separate follow-up, once a
second repo adopts the script.

Todo: 6d0ec573
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 14:18:21 +01:00

1.8 KiB

Patch-target gate (scripts/check_patch_targets.py)

mock.patch("pkg.module.NAME", ...) fails open. When a refactor moves NAME, the old path still imports, the patch redirects nothing, and the test stays green while it writes to real user state. The script reads every test file, finds each literal patch("<package>....") target, and exits 1 when a target no longer resolves.

Usage

Run it from the repo root:

python3 scripts/check_patch_targets.py PACKAGE [--tests-root DIR]
  • PACKAGE is required. The script checks only targets inside it (pkg or pkg.*; pkg_other is not pkg). It has no default, because a silent default would check the wrong package and pass, which is the fail-open shape the gate exists to catch.
  • --tests-root defaults to PACKAGE/tests.
  • The package must be a flat package at the repo root (./PACKAGE/__init__.py). There is no src/ layout support yet.
  • Exit codes: 0 clean, 1 stale targets (each printed as file:line: patch target does not resolve: ...), a package that will not import or a missing tests root, 2 usage error.

Adopting it in another guard repo

Copy scripts/check_patch_targets.py into the repo's scripts/, then add this hook to .pre-commit-config.yaml under a repo: local block:

      - id: patch-targets
        name: test patch targets resolve
        entry: python3 scripts/check_patch_targets.py <your_package>
        language: system
        pass_filenames: false
        files: ^<your_package>/

The script puts the repo root on sys.path itself, so the hook works on a CI runner that never installed the package.

Follow-up: a shared copy

Each adopter copies the script today. Moving it to a shared ~/src/utils/patch_targets/ package is a separate follow-up, done once a second repo actually adopts it.