DEFAULT_ROOTS in tools/refcheck/src/refcheck/cli.py:17 is book, lessons, blueprints and README.md. Nothing else in the repository is scanned, so a citation written anywhere else is not resolved, not locked, and not reported when it drifts.
There are already citations outside those roots. pyxray/tests/test_symbols.py cites Python/symtable.c:2506-2513@v3.15.0rc1#anon_lambda in a docstring explaining why the lambda scope name changed in 3.15, and pyxray/tests/test_cite.py has two more. Those are exactly the citations that most want checking, because a docstring is where somebody writes down the reason a piece of code looks strange, and it is the last place anyone thinks to reread when the pin moves.
The obvious fix does not work. Widening the roots to the whole tree picks up tools/refcheck/tests/test_scan_and_lock.py, which contains deliberately fake citations like Objects/fake.c:1@v3.15.0rc1 as fixtures for the scanner's own tests. Those must not resolve, that is the point of them, so a naive widening turns a passing suite into a failing one and the fix would be to make the fixtures resolvable, which destroys the tests.
So this needs a decision about how a file says it is not to be scanned. Options in rough order of how much I like them: an ignore list in pyproject.toml under a refcheck table, which is explicit and greppable; a marker comment the scanner honours, which keeps the exclusion next to the thing being excluded; or moving the fake citations into a data file the scanner is told to skip. The first one is probably right, because there will be other fixture files later and they will not all be in refcheck.
Whichever it is, the roots should end up covering the whole repository by default, with the exclusions named. Opt out is safe here and opt in is not, because the failure mode of opt in is silence.
DEFAULT_ROOTSintools/refcheck/src/refcheck/cli.py:17isbook,lessons,blueprintsandREADME.md. Nothing else in the repository is scanned, so a citation written anywhere else is not resolved, not locked, and not reported when it drifts.There are already citations outside those roots.
pyxray/tests/test_symbols.pycitesPython/symtable.c:2506-2513@v3.15.0rc1#anon_lambdain a docstring explaining why the lambda scope name changed in 3.15, andpyxray/tests/test_cite.pyhas two more. Those are exactly the citations that most want checking, because a docstring is where somebody writes down the reason a piece of code looks strange, and it is the last place anyone thinks to reread when the pin moves.The obvious fix does not work. Widening the roots to the whole tree picks up
tools/refcheck/tests/test_scan_and_lock.py, which contains deliberately fake citations likeObjects/fake.c:1@v3.15.0rc1as fixtures for the scanner's own tests. Those must not resolve, that is the point of them, so a naive widening turns a passing suite into a failing one and the fix would be to make the fixtures resolvable, which destroys the tests.So this needs a decision about how a file says it is not to be scanned. Options in rough order of how much I like them: an ignore list in
pyproject.tomlunder a refcheck table, which is explicit and greppable; a marker comment the scanner honours, which keeps the exclusion next to the thing being excluded; or moving the fake citations into a data file the scanner is told to skip. The first one is probably right, because there will be other fixture files later and they will not all be in refcheck.Whichever it is, the roots should end up covering the whole repository by default, with the exclusions named. Opt out is safe here and opt in is not, because the failure mode of opt in is silence.