feat: add pyright script for type checking with configuration - #1123

* ci(pyright): gate on the rules a file decides for itself

Pyright catches what ruff and mypy miss: locals bound on only some paths,
names that resolve nowhere, statements with no effect. Running it is easy;
gating on it is not, because most of its rules read third-party stubs.

Measured over five environments (python 3.8/3.11/3.12/3.14, and a workstation
carrying polars, cudf, scipy and scikit-learn) on one unchanged tree,
reportAttributeAccessIssue ranges from 146 to 810 findings, reportReturnType
from 2 to 78. A gate on those fails for whoever has cudf installed and passes
in CI. So only five rules gate -- the ones decided by a file's own control
flow, names and syntax -- and the rest are reported but never enforced.

Agreement across environments was necessary but not sufficient evidence:
reportOptionalSubscript, reportTypedDictNotRequiredAccess and reportIndexIssue
all matched across four environments and then diverged on the fifth, being rare
enough to agree by luck. The admission bar is the principle, not the sample.

- bin/pyright.sh pins pyright 1.1.414, and uses a local install only when it
  is that version; an unpinned tool moves the baseline underneath us.
- bin/ci_pyright_guard.py ratchets per-file counts against
  bin/ci_pyright_baseline.json, the same shape as the type-hygiene and
  comment-density guards: counts may shrink, never grow, and a file absent
  from the baseline must be clean.
- python-pyright runs it on py3.12 only. All seven lint matrix cells would
  produce byte-identical output for these rules.

273 findings are grandfathered. 195 of them are one module that builds its
namespace with globals().update(vars(...)) and already carries
`# mypy: ignore-errors` and `# ruff: noqa: F821`; its count is left visible
rather than excluded so that fixing it shows up as slack under --strict.

Builds on #1123 by Jithin Bathula, whose bin/pyright.sh and pyrightconfig.json
this keeps. Closes #1075.

Co-Authored-By: Jithin Bathula <[email protected]>
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_017ropeBMLJUuy6ViYwy15ud

* ci(pyright): fail on a collapsed gate and on files that do not parse

Review of the previous commit found the ratchet could go quiet without anyone
noticing, which defeats its purpose.

Scope lives in pyrightconfig.json, a different file from the baseline, so
widening an exclude silenced the gate with no baseline change and no failure:
appending "graphistry/compute" to exclude dropped the gated findings from 273
to 56 and still exited 0 -- while printing "10 file(s) now below baseline". The
guard observed the collapse and passed anyway. Shrinking findings and shrinking
scope are indistinguishable from counts alone, so the baseline now records the
file count it was built over and a run that sees materially less fails. A real
scope change is still fine; it just has to go through --update-baseline, where
the delta shows up in review.

Pyright reports a file it cannot parse with no rule at all, so those findings
were routed to the ungated pile and could never fail. An unparseable file also
yields fewer gated findings, so it read as an improvement. Parse failures
consult no type either, so they are gated under <unparseable> and must stay at
zero; the tree has none today.

Also aligns Finding with the sibling guard's `@dataclass(frozen=True)` and
real annotations rather than a hand-rolled __slots__ class and `# type:`
comments.

Verified: exclude-widening and a fabricated zero-file report now exit 1; an
unparseable file exits 1 naming it; the injected possibly-unbound local still
exits 1 and reverts to 0; one baseline still passes in all five environments.
19 tests, 13-mutant battery -- 12 caught, the 2 survivors inert alone and
caught in combination.

Co-Authored-By: Jithin Bathula <[email protected]>
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_017ropeBMLJUuy6ViYwy15ud

* docs(develop): trim the pyright ratchet section to the size of its siblings

63 lines re-derived the environment measurement in prose; that argument lives
in the PR and does not need repeating for someone reaching for the commands.
42 lines now, next to Type Hygiene at 39 and Comment Density at 43.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_017ropeBMLJUuy6ViYwy15ud

---------

Co-authored-by: Jithin Bathula <[email protected]>
Co-authored-by: Claude Opus 5 (1M context) <[email protected]>