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

[lmeyerov]

Takes over #1123 (@JithinBathula) and finishes it into an enforceable gate. Closes #1075.

#1123 added bin/pyright.sh and a pyrightconfig.json, and stopped there by design — the author listed CI integration and rule enforcement as non-goals. Two things had to be settled before it could gate: the tool was unpinned, and the config change was a net loosening with exactly one tightening. Both are resolved here. The contributor's bin/pyright.sh resolution order and pyrightconfig.json are kept.

The problem: most pyright rules are not reproducible

Pyright was run over one unchanged tree in five environments — python 3.8 (pandas 2.0.3), 3.11, 3.12 (the CI lint lockfile), 3.14 (pandas 3.0.5), and a workstation carrying polars 1.42, cudf 25.10, scipy and scikit-learn.

rule	py3.8	py3.12 CI	py3.14	py3.11 +polars	workstation
reportAttributeAccessIssue	776	778	778	146	810
reportOptionalMemberAccess	187	183	183	180	195
reportCallIssue	146	143	143	146	8
reportReturnType	10	7	7	23	2
reportInvalidTypeForm	35	35	35	34	1201
reportUndefinedVariable	195	195	195	195	195
reportPossiblyUnboundVariable	61	61	61	61	61
reportUnusedExpression	15	15	15	15	15

Gating on a rule from the top half means CI and the developer who ran the same command disagree, and the baseline drifts on every pandas release.

What gates

Five rules, admitted on a principle rather than a measurement: the rule must be decided by the source file's own control flow, names and syntax, with no type consulted. reportPossiblyUnboundVariable, reportUndefinedVariable, reportUnsupportedDunderAll, reportUnusedExpression, reportSelfClsParameterName.

The principle is doing real work here, because measurement alone was not enough: reportOptionalSubscript, reportTypedDictNotRequiredAccess and reportIndexIssue produced identical per-file counts across the first four environments and then diverged on the fifth. They are rare enough to agree by luck. Everything else is still collected and shown by --report; it just never gates.

Shape

Deliberately the same as bin/ci_type_hygiene_guard.py and bin/ci_comment_density_guard.py, down to the flags:

• bin/pyright.sh pins pyright 1.1.414, in both the uvx and npx fallbacks, and uses a local install only when it is that exact version — otherwise it says so and fetches the pinned build. An unpinned tool moves the baseline underneath the repo.
• bin/ci_pyright_guard.py ratchets per-file counts against bin/ci_pyright_baseline.json: counts may shrink, never grow; a file absent from the baseline must be clean. --report / --list / --strict / --update-baseline / --from-json.
• python-pyright runs it on py3.12 only. Putting it in bin/lint.sh would pay 21s plus a tool fetch in all seven matrix cells for output the table above shows is byte-identical in all seven.

Two things beyond the rule counts also gate, both added after reviewing the first commit:

• A collapsed gate fails. 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 dropped the gated findings from 273 to 56 and still exited 0, while printing "10 file(s) now below baseline". The baseline now records the file count it was built over, and a run that sees materially less fails. A real scope change still goes through --update-baseline, where the delta shows up in review.
• A file that does not parse fails. Pyright reports those with no rule at all, so they were routed to the ungated pile and could never fail — and an unparseable file 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.

273 findings are grandfathered, of which 195 are one module — graphistry/compute/gfql/cypher/projection_planning.py builds its namespace with globals().update(vars(_lowering)) and already carries # mypy: ignore-errors and # ruff: noqa: F821. Its count is left visible rather than excluded, so that fixing the module shows up as slack under --strict. That module being invisible to all three checkers is worth its own issue; I did not fold it in here.

Verification

• End to end: adding if flag: edge_map = 1 / return edge_map to graphistry/util.py turns the gate red with "edge_map" is possibly unbound — the exact case from feat: add pyright script for type checking with configuration #1123's motivation — and green again on revert.
• One baseline, five environments, exit 0 in all five.
• 19 tests pin the ratchet. A 13-mutant battery: 12 caught, and the 2 that survived were verified inert on their own (the comparison loop never reads the keys they add) and caught when combined.
• Run locally before pushing: bin/lint.sh (ruff + both guards), bin/typecheck.sh (mypy clean, 349 files), actionlint, zizmor (no new findings), and changed_line_coverage.py --min-percent 80 (0 eligible changed lines — this PR touches bin/, workflows, docs and a test).

Note for the reviewer

python-pyright is a new job, so it is not in branch protection's required checks — worth adding there if this lands.

Co-authored with @JithinBathula's work from #1123.

🤖 Generated with Claude Code

https://claude.ai/code/session_017ropeBMLJUuy6ViYwy15ud