ci: mypy ratchet -- keep type-clean modules clean (71 modules, 536 -> 442 errors) (#661)

* ci: mypy ratchet -- keep type-clean modules clean

mypy-clean.txt lists the 71 modules under src/ that type-check clean;
scripts/check_types.py runs mypy (--follow-imports=silent) on exactly
those files and fails on any error or a missing/unsorted/duplicate entry.
A new "Type check (mypy ratchet)" CI job runs it with mypy 1.20.2 and
pinned stubs; the manual pre-commit mypy hook now runs the same script
(a local hook, so mypy sees the installed requirements like CI does).

35 modules were made clean with annotation-only fixes: hints, typing.cast,
TYPE_CHECKING imports, implicit-Optional defaults made explicit, and
annotations widened (never guards removed) where mypy called a defensive
isinstance check unreachable. No runtime behaviour change.

mypy.ini: numpy and orjson are treated as Any (follow_imports=skip, also
for stubs). numpy 2.3+ stubs use 3.12 `type` statements that mypy won't
parse at python_version 3.10, and orjson is optional, so seeing its stubs
made the result depend on whether it was installed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore: annotate check_types.py's list-form mypy subprocess

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

.pre-commit-config.yaml

@@ -37,19 +37,21 @@ repos:
         types: [python]
         pass_filenames: false
 
-  # Manual only: src/ still has ~500 type errors, so running this on every
-  # commit would block every contributor. Run it with
+  # The mypy ratchet -- the same check as CI's "Type check (mypy ratchet)"
+  # job: mypy on exactly the modules listed in mypy-clean.txt. Run it with
   #   pre-commit run mypy --hook-stage manual
-  # and don't add new errors in the files you touch. mypy.ini's `files = src`
-  # is what gives it a target, since pass_filenames is off.
-  - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.8.0
+  # A local hook rather than mirrors-mypy so mypy sees the packages installed
+  # from requirements.txt, as CI does; an isolated hook env without them types
+  # PIL, requests and friends as Any and reports different errors. Needs
+  # mypy==1.20.2 (the version CI pins) in the environment you commit from.
+  - repo: local
     hooks:
       - id: mypy
-        additional_dependencies: [types-requests, types-pytz]
-        args: [--ignore-missing-imports, --no-error-summary]
+        name: mypy (ratchet, mypy-clean.txt)
+        entry: python scripts/check_types.py
+        language: system
         pass_filenames: false
-        files: ^src/
+        always_run: true
         stages: [manual]
 
   - repo: https://github.com/PyCQA/bandit