Centralise VRT capability validator at both read entry points (#2371)

[brendancol]

Closes #2371.

Summary

• Extend validate_parsed_vrt to reject nested VRTs, per-source <UseMaskBand> flags, and per-source <MaskBand> children with VRTUnsupportedError.
• Extend parse_vrt to reject dataset-level and band-level <GDALWarpOptions> blocks with UnsupportedGeoTIFFFeatureError.
• Wire the internal _vrt.read_vrt entry point through validate_parsed_vrt so direct callers and the chunked dask path get the same capability rejections as the public _backends/vrt.read_vrt entry point.
• Expose validate_vrt_capability as a public alias on _vrt_validation matching the epic naming.

Backend coverage

The validator is a metadata gate that runs before any backend dispatch, so numpy, cupy, dask+numpy, and dask+cupy all see the same rejections at graph-build / eager-read setup time.

Test plan

• New file xrspatial/geotiff/tests/test_vrt_capability_validator_2371.py (22 tests) covers every new rejection path at four entry points: validator-direct, internal _vrt.read_vrt, public _backends/vrt.read_vrt, and open_geotiff.
• test_vrt_resample_alg_1751.py accepts VRTUnsupportedError alongside the historical NotImplementedError. Both encode the same contract.
• Full xrspatial/geotiff/tests/ suite passes (5661 passed).

Sub-task of epic #2342. Sibling PRs in flight: positive simple-mosaic tests, negative tests for unsupported VRT features, missing-source policy tests, and VRT contract docs.

[brendancol]

PR Review: Centralise VRT capability validator at both read entry points (#2371)

Blockers (must fix before merge)

None.

Suggestions (should fix, not blocking)

• xrspatial/geotiff/_vrt.py:713: the <UseMaskBand> truthy set is ('1', 'true', 'yes'). GDAL writes lowercase true, so '1' and 'yes' are spellings the parser will never see from GDAL itself. Tightening to ('1', 'true') keeps the surface narrow and matches what real VRTs contain. Not blocking; the wider set is harmless.

Nits (optional improvements)

• xrspatial/geotiff/_vrt_validation.py:303: the nested-VRT message ends with "are not a supported feature in this release". The parse_vrt rejections point readers at xrspatial.geotiff.SUPPORTED_FEATURES. Adding the same pointer here keeps the rejection messages aligned on one discovery anchor.
• xrspatial/geotiff/_vrt.py:1247: the validator import is lazy inside the function body. That matches the existing pattern elsewhere in the file, but a one-line comment ("lazy to avoid circular import") would help the next reader.
• xrspatial/geotiff/tests/test_vrt_capability_validator_2371.py:339: the test_use_mask_band_truthy_spellings_rejected parametrize list includes 'yes'. If you tighten the truthy set per the suggestion above, drop that row or move it to a "must be accepted as not-truthy" test.

What looks good

• The validator extends cleanly. Every new rejection names the offending source path and field, so the error message tells the caller where to look.
• validate_vrt_capability as an alias keeps every existing call site working.
• Test coverage is strong: every new rejection path runs at four entry points (validator-direct, internal _vrt.read_vrt, public _backends/vrt.read_vrt, open_geotiff).
• The test_vrt_resample_alg_1751.py fix accepts both NotImplementedError and VRTUnsupportedError, so the legacy contract intent is preserved without breaking the new routing.
• The parsed is None short-circuit in _vrt.read_vrt avoids double-validation when the chunked path threads a pre-validated instance in.
• <GDALWarpOptions> rejection covers dataset-level, band-level, and the existing subClass="VRTWarpedRasterBand" marker. All three locations a warp config can appear are caught.

Checklist

• Algorithm matches the VRT spec
• Implemented backends produce consistent results (validator runs before backend dispatch)
• NaN handling not applicable (metadata-only gate)
• Edge cases covered: uppercase .VRT, false flag accepted, truthy spellings, both source tag types
• Dask chunk boundaries handled correctly (chunked path threads a pre-validated VRT)
• No premature materialization (metadata gate runs before any decode)
• Benchmark not needed (cheap XML-only check)
• README feature matrix not applicable (no new public API)
• Docstrings present and accurate

[brendancol]

Follow-up review after addressing prior comments

Disposition of original findings

• Suggestion (_vrt.py:713 UseMaskBand truthy set): Fixed. Narrowed to ('1', 'true'). Added test_use_mask_band_non_canonical_truthy_accepted to lock in the contract for non-canonical tokens.
• Nit 1 (_vrt_validation.py:303 SUPPORTED_FEATURES anchor): Fixed. Nested-VRT message now references xrspatial.geotiff.SUPPORTED_FEATURES.
• Nit 2 (lazy import comment): Fixed. Added a one-line note explaining the circular-import avoidance.
• Nit 3 (drop 'yes' parametrize row): Fixed. Row removed; non-canonical tokens are covered by the new explicit test instead.

Verification

• Full geotiff test suite: 5663 passed, 68 skipped, 4 xfailed, 1 xpassed.
• New test count: 24 (was 22). The two new tests cover the narrowed truthy set.

No further findings.