feat: warn on common GPU env pitfalls before build (#56)

[johnyaku]

Implements the static guardrails from #56 (items 1, 3, 4). The network-based wheel-triple check (item 2) is tracked separately in #59.

Rebased onto main after #58 merged (clean — no file overlap).

Why

A valid GPU build is a 3-way intersection — (python cpXX) × (framework version) × (CUDA variant cuXXX). Pinning only two leaves the build at the mercy of resolver defaults, and the failure surfaces cryptically ~60s deep in the pip layer (No matching distribution found) rather than up front. This also bit the --base workflow: pointing --base at a CUDA image while leaving pytorch-cuda in the conda deps gives no benefit and still triggers the fragile conda CUDA solve.

What

New static checks in src/absconda/gpu_lint.py (no network — they warn, never block), surfaced at generate/build/publish/validate:

Pitfall	Warning
Floating python (>=/unpinned/absent) + a pinned CUDA wheel	binary wheels lag new Python releases → pin python=X.Y
Bare torch/jax/… + a CUDA --extra-index-url but no +cuXXX	may silently install the CPU wheel (cuda.is_available()==False) → pin +cuXXX
CUDA resolved by conda (pytorch-cuda/cudatoolkit/cuda-*)	fragile; message adapts when --base is set — the case that motivated this
Conda pytorch without a CUDA metapackage	CPU-only build

Wired into _render_dockerfile (the single choke point that has both the env and the resolved --base) and validate. Docs added to custom-base-images.md (incl. issue #56's note that the conda pytorch channel is not GPU).

Verified against the real cases

• Issue Validate (python, torch, cuda) wheel triple at publish time — floating python + pinned CUDA wheel fails cryptically #56 flash-scope (python>=3.11 + torch==2.2.2+cu118) → floating-python warning.
• Bare torch + cu118 index → silent-CPU warning.
• Original cell2location (conda pytorch-cuda + --base) → base-aware conda-CUDA warning.
• The restructured cell2location (pinned python=3.10, torch==2.2.2+cu118) → no false positives.

Deferred → #59

The network-based (python, torch, cuda) wheel-existence check (item 2 of #56) — querying download.pytorch.org/whl/<cuda>/torch/ to fail fast when no cpXX wheel exists for the pinned interpreter. It's the strongest check but adds a network dependency and needs careful offline/timeout/error-vs-warn UX, so it's tracked in #59. The static floating-python warning here already covers the exact incident in #56.

Testing

• tests/test_gpu_lint.py — 8 cases (each pitfall + negative/clean envs).
• Full suite: 109 passed, 2 skipped (docker smoke). ruff check/format clean.

🤖 Generated with Claude Code