Add stubtest to CI for type annotation validation

[kkollsga]

• Closes more sophisticated type checking with numpy #11086
• Tests added
• User visible changes (including notable bug fixes) are documented in whats-new.rst
• New functions/methods are listed in api.rst (N/A - no new public API)

Summary

This PR integrates mypy's stubtest tool into xarray's CI pipeline to validate that type annotations match runtime behavior.

What's included

CI Integration:

• New stubtest job in .github/workflows/ci-additional.yaml
• Runs on every PR with continue-on-error: true (Phase 1: informational)
• Tests core modules: dataarray, dataset, variable

Infrastructure:

• _stubtest/allowlist.txt - Comprehensive allowlist for TYPE_CHECKING imports and intentional stub/runtime differences
• _stubtest/run_stubtest.py - Runner script with reporting
• ci_tests/ - Pytest-based tests for stubtest compliance and type regressions

Code cleanup:

• Removed 14 obsolete # type: ignore comments revealed by scipy-stubs and pandas-stubs
• Added 6 targeted type ignores for legitimate typing limitations
• Net improvement: -8 type ignores

Phased rollout

The stubtest job is currently non-blocking (continue-on-error: true). Once maintainers are confident it's stable, it can be made required by changing to continue-on-error: false.

Verification

Stubtest errors reduced from 1,084 → 0 with the allowlist.

[VeckoTheGecko]

Hi @kkollsga , I'm curious about this issue so am happy to dig into this PR a bit - but before I do that I would like to know to what extent AI has been used on this PR.

It seems like a heavy PR and from a glance (on mobile) I dont see the connections to the original work done in Scipy. An AI disclosure statement would be really helpful for me to know how its been used 😊

(Note I am not a maintainer, and Xarray - AFAICT - doesn't have LLM disclosure as a contributing policy. This is a request from myself)

[kkollsga]

This PR was developed with assistance from Claude Code. AI usage is disclosed via the Co-authored-by: Claude <noreply@anthropic.com> trailer in the main commit, following xarray's CLAUDE.md guidelines.

The original issue references stubtest tooling from NumPy's fellowship work, with a cross-reference to #10273 (scipy-stubs compliance). The allowlist was built specifically for xarray's patterns by iteratively running stubtest on core modules. This PR also cleans up some obsolete type ignores that scipy-stubs made redundant, partially addressing #10273.

The categorized allowlist (TYPE_CHECKING imports, dynamic methods, protocol differences) is designed to be maintainable as xarray evolves.

[kkollsga]

Earlier iterations ran into issues with pixi lock validation when modifying pyproject.toml, and the initial allowlist (~600 lines) had overly broad patterns causing conflicts.

The fix was to keep this PR as pure infrastructure with no source changes, and rebuild the allowlist from scratch using efficient grouped regex patterns. This brought it down to 170 lines with 0 stubtest errors and 0 unused patterns.

Future work: Expand coverage to additional modules (backends, computation, indexes), then transition from continue-on-error: true to a required check once stable.