geotiff tests: consolidate writer cluster (cog, bigtiff, overview) (#2410)

* geotiff tests: consolidate writer cluster (cog, bigtiff, overview) (#2400)

Folds 26 writer/COG/BigTIFF/overview test files into a four-file
write/ subpackage per epic #2390 PR 7:

- write/test_basic.py: generic writer paths (compression, tiling,
  kwarg order, return path, layout monkeypatch, VRT writer surface).
- write/test_cog.py: COG writer compliance and invalid-input errors.
- write/test_bigtiff.py: BigTIFF + COG compliance.
- write/test_overview.py: overview-level and nodata-aware overview tests.

Tests-only restructure. No source changes.

The fold preserves 497 test ids (collect-only counts match before and
after). Module-level dedup removed identical-body shadowed helpers
(`_build_source_tif`, `_gpu_available`, `_HAS_GPU`) and renamed the
one private-import `write_vrt` so it does not shadow the public
re-export used by the kwarg-order signature tests in the same file.

The release gate checklist
(docs/source/reference/release_gate_geotiff.rst) and the user-facing
GeoTIFF docs (docs/source/reference/geotiff.rst) had their citations
re-pointed at the new file paths so the rst-parity gate
(test_release_gate_2321.py) keeps passing.

CLUSTER_AUDIT_PR7.md is in this commit and is deleted in a follow-up
commit on the same branch before merge per the epic contract.

Closes #2400
Part of #2390

* Address review feedback for PR 7 (#2400)

- Blocker: rasterio importorskip moved from module scope to per-test
  in write/test_basic.py and write/test_cog.py compliance section.
  Mid-file pytest.importorskip("rasterio") was skipping ALL prior
  tests in the same module when rasterio was absent. Each rasterio-
  using test now does its own importorskip and binds the module
  locally.
- Suggestion: write/test_overview.py, write/test_basic.py, and
  write/test_cog.py now use ``gpu_available`` from
  ``_helpers/markers.py`` instead of defining a local copy or routing
  through conftest.
- Suggestion: collapsed redundant ``from xrspatial.geotiff import ...``
  duplicates in write/test_basic.py and write/test_cog.py into one
  parenthesised group each. The private write_vrt alias is now next
  to a comment explaining why it exists.
- Suggestion: comment-only filename refs updated in
  xrspatial/geotiff/_writer.py, _attrs.py,
  tests/test_overview_block_order_2308.py, and
  tests/test_release_gate_cog.py to point at the new write/*.py paths.
- Nit: section banners changed from ``# Folded from: test_*_NNNN.py``
  to ``# Section: <thematic name>`` so the in-source markers no longer
  reference removed filenames.
- Nit: module docstrings on the four new files trimmed to describe
  the topical coverage rather than re-list deleted source filenames.

Verification: ``pytest xrspatial/geotiff/tests/write/ -v`` 497 pass;
``pytest xrspatial/geotiff/tests/ -x -q`` 5706 pass / 68 skipped.

* Remove CLUSTER_AUDIT_PR7.md before merge (#2400)

Per the epic #2390 contract, the per-PR cluster audit is a temporary
deliverable for the review pass. It is removed in a final commit on
the branch before the PR is approved so it does not land on main.

* Update cog-validator workflow path to write/test_cog.py (#2400)

PR 7 consolidated test_cog_writer_compliance.py and test_cog_parity_2286.py
into write/test_cog.py. The dedicated cog-validator CI workflow still
pointed at the old paths and exited 4 (no tests collected). Point at the
new consolidated module so the strict-validator gate runs again.

Author: brendancol

.github/workflows/test-cog-validator.yml

@@ -101,4 +101,4 @@ jobs:
       # missing rio-cogeo / GDAL install fail the suite instead of
       # skipping it -- the whole point of this gate.
       run: |
-        pytest xrspatial/geotiff/tests/test_cog_writer_compliance.py xrspatial/geotiff/tests/test_cog_parity_2286.py -x
+        pytest xrspatial/geotiff/tests/write/test_cog.py -x

docs/source/reference/geotiff.rst

@@ -207,7 +207,7 @@ COG validator CI gate
 on every PR. A dedicated Linux job (``pytest-cog-validator``)
 installs rio-cogeo and the GDAL Python bindings from conda-forge,
 sets ``XRSPATIAL_REQUIRE_COG_VALIDATOR=1``, and runs the compliance
-suite in ``xrspatial/geotiff/tests/test_cog_writer_compliance.py``.
+suite in ``xrspatial/geotiff/tests/write/test_cog.py``.
 With the env var set, a missing validator dependency is a hard
 failure instead of a silent skip, so a misconfigured install step
 cannot quietly let the gate pass. Contributors without rio-cogeo
@@ -493,7 +493,7 @@ is a plain GeoTIFF or a COG.
 
 ``SUPPORTED_FEATURES['writer.bigtiff_cog']`` is currently ``advanced``.
 The external-interop gate lives in
-``xrspatial/geotiff/tests/test_bigtiff_cog_compliance_2286.py`` and
+``xrspatial/geotiff/tests/write/test_bigtiff.py`` and
 covers the BigTIFF-specific layout (header, IFDs, tile and overview
 offset tables), one lossless integer codec, one lossless float codec,
 single-band and 3-band, one overview level, plus an auto-promotion row
@@ -515,9 +515,9 @@ regression test that locks the behaviour.
    * - Combination
      - Regression test
    * - ``to_geotiff(cog=True, tiled=False)``
-     - ``xrspatial/geotiff/tests/test_cog_requires_tiled_2312.py``
+     - ``xrspatial/geotiff/tests/write/test_cog.py``
    * - ``to_geotiff(cog=True, tile_size <= 0)``
-     - ``xrspatial/geotiff/tests/test_cog_tile_size_hang_2311.py``
+     - ``xrspatial/geotiff/tests/write/test_cog.py``
    * - Warped VRT
        (``<VRTDataset subClass="VRTWarpedDataset">`` or
        ``<VRTRasterBand subClass="VRTWarpedRasterBand">``)

docs/source/reference/release_gate_geotiff.rst

@@ -208,14 +208,14 @@ Local GeoTIFF read and write
      - stable
      - ``to_geotiff`` writes a file that ``open_geotiff`` reads back
        bit-exact for every stable codec.
-     - ``xrspatial/geotiff/tests/test_cog_writer_compliance.py``,
+     - ``xrspatial/geotiff/tests/write/test_cog.py``,
        ``xrspatial/geotiff/tests/parity/test_backend_matrix.py``
      - `#2341`_
    * - ``writer.overviews``
      - advanced
      - Internal overview IFDs round-trip; the reader can pick a level.
      - ``xrspatial/geotiff/tests/test_dask_overview_level.py``,
-       ``xrspatial/geotiff/tests/test_cog_overview_nodata_1613.py``
+       ``xrspatial/geotiff/tests/write/test_overview.py``
      - `#2286`_
    * - ``writer.bigtiff``
      - advanced
@@ -283,14 +283,13 @@ Cloud-optimized GeoTIFF (COG)
      - ``to_geotiff(cog=True)`` writes an IFD-first tiled file with internal
        overviews that ``rio-cogeo`` accepts (CI-gated by
        ``XRSPATIAL_REQUIRE_COG_VALIDATOR=1``).
-     - ``xrspatial/geotiff/tests/test_cog_writer_compliance.py``,
-       ``xrspatial/geotiff/tests/test_cog_parity_2286.py``
+     - ``xrspatial/geotiff/tests/write/test_cog.py``
      - `#2286`_
    * - ``reader.local_cog``
      - stable
      - Local COG with overview IFDs decodes byte-for-byte through eager and
        dask paths.
-     - ``xrspatial/geotiff/tests/test_cog.py``,
+     - ``xrspatial/geotiff/tests/write/test_cog.py``,
        ``xrspatial/geotiff/tests/test_golden_corpus_overview_cog_1930.py``
      - `#2286`_
    * - ``reader.http_cog``
@@ -305,19 +304,19 @@ Cloud-optimized GeoTIFF (COG)
      - advanced
      - BigTIFF + COG combination passes the dedicated compliance suite
        (header magic, IFDs, tile and overview offset tables).
-     - ``xrspatial/geotiff/tests/test_bigtiff_cog_compliance_2286.py``
+     - ``xrspatial/geotiff/tests/write/test_bigtiff.py``
      - `#2286`_
    * - ``writer.cog`` -- tile-layout pre-flight (``cog=True, tiled=False``)
      - stable
      - Raises ``ValueError`` at the writer entry point regardless of dtype
        or codec.
-     - ``xrspatial/geotiff/tests/test_cog_requires_tiled_2312.py``
+     - ``xrspatial/geotiff/tests/write/test_cog.py``
      - `#2286`_
    * - ``writer.cog`` -- tile-size pre-flight (non-positive ``tile_size``)
      - stable
      - Non-positive tile sizes raise ``ValueError`` regardless of the
        ``tiled`` flag.
-     - ``xrspatial/geotiff/tests/test_cog_tile_size_hang_2311.py``
+     - ``xrspatial/geotiff/tests/write/test_cog.py``
      - `#2286`_
 
 HTTP / fsspec reads

xrspatial/geotiff/_attrs.py

@@ -336,7 +336,7 @@
     # the BigTIFF + COG combination has its own external-interop surface
     # (8-byte offsets in tile/overview tables, BigTIFF-form IFDs, COG
     # layout invariants). Stays ``advanced`` even when every row of
-    # ``tests/test_bigtiff_cog_compliance_2286.py`` passes -- promotion
+    # ``tests/write/test_bigtiff.py`` passes -- promotion
     # to ``stable`` happens after the gate has lived in CI for a release
     # cycle. See the BigTIFF COG section in
     # ``docs/source/reference/geotiff.rst``.

xrspatial/geotiff/_writer.py

@@ -137,7 +137,7 @@
 # the array-level ``_write`` defense-in-depth gate. Keeping the message
 # string in one place stops the two raise sites from drifting if one
 # ever gets reworded. The substring assertions in
-# ``test_cog_requires_tiled_2312.py`` pin the actionable tokens
+# ``tests/write/test_cog.py`` pin the actionable tokens
 # (``tiled=True``, ``cog=False``, ``COG``) so a future rewrite still
 # has to satisfy the same contract.
 _COG_REQUIRES_TILED_MSG = (