feat(check_dataset_allowlist): fail when a capped should_simulate deletes committed data

[Jammy2211]

Closes #252. Follow-up to PyAutoArray#470 / autolens_workspace_test#264, which fixed the single live instance by declaring full_datasets on the one offending script. This closes the general footgun.

Paired docstring-only PR: PyAutoArray#480.

What it adds

Leg 1 asserts nothing generated got committed. Leg 2 asserts nothing committed gets deleted. should_simulate() ends in shutil.rmtree, so a script reaching a committed dataset while PYAUTO_SMALL_DATASETS=1 is still in force destroys data the allowlist exists to protect. The library-side stamp guard can't cover this in general — it reads <dataset>/data.fits, so JSON-only datasets are invisible to it.

The predicate is containment, not prefix matching

This is the part worth reviewing. The obvious implementation — "does the resolved path sit under an !dataset/... allowlist prefix?" — is wrong, and I only caught it by running the guard across every workspace before trusting it:

[capped-deletion] FAIL — ... (6):
    scripts/overview/overview_4_charge_injection_data.py:131 -> dataset/overview/imaging_ci/uniform
    scripts/overview/overview_5_fitting.py:276              -> dataset/overview/dataset_1d
    ... 4 more

All six are safe. autocti_workspace commits five doc images directly in dataset/overview/; those scripts regenerate dataset/overview/imaging_ci/uniform and dataset/overview/dataset_1d, which hold nothing tracked. Deleting them destroys nothing.

So the predicate is "rmtree(path) would delete git-tracked files", which is the actual invariant. Six spurious release-blocking failures → zero.

Resolution is exact, and gaps are loud

This runs in pre_build, so a false positive blocks a release. Arguments are resolved by a restricted AST evaluator — literals, top-level names in source order (these scripts reassign dataset_name between sections), multi-arg Path(...), os.path.join, / chains, plain f-strings. Anything it can't evaluate is reported and skipped, never guessed, and the skipped count always prints so a partial sweep can't read as full coverage.

Multi-arg Path("dataset", "multi_galaxy", dataset_name) turned out to be the dominant idiom — handling only the single-arg form left 79 of ~253 autolens_workspace call sites (~31%) unresolved. With it, coverage is complete:

Workspace	Result	Unresolved
autolens_workspace	OK (49 committed files)	0
autogalaxy_workspace	OK (1)	0
autocti_workspace	OK (5)	0
autolens_workspace_test	OK (15)	0
autofit_workspace, *_test	no tracked dataset files	—
autolens_workspace_developer	SKIP (Group B, not in regime)	—

Regression proof

Reverting autolens_workspace_test to its pre-#264 state reproduces the failure exactly:

[capped-deletion] FAIL — should_simulate() would delete COMMITTED files without releasing PYAUTO_SMALL_DATASETS (1):
    scripts/point_source/visualization/visualization.py:39 -> dataset/point_source/simple   [ENV: real_plots]

Also

ENV_DECLARATION_TOKENS now documents real_output as a superset token (it releases all four managed vars). Treating the map as four single-var tokens under-counts the released set and reports such a script as an offender — that mis-read cost real time during the #470 sweep. _releasing_tokens() derives from the map rather than hardcoding the pair, so a future releasing token protects scripts without an edit here.

Tests

10 new tests covering the resolver (multi-arg Path, / chains, os.path.join, source-order reassignment, unresolvable-not-guessed, function-scope exclusion), token derivation, and the containment predicate end-to-end — including the autocti false-positive shape as an explicit regression. Full suite: 370 passed.

🤖 Generated with Claude Code

https://claude.ai/code/session_01F11sMzmaVWfU6NCz1PKVVb