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 <[email protected]> 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.