motief/docs/plans/2026-04-24-005-add-pyright-ci-plan.md

title	type	status	date
feat: Add pyright type-checking to CI	feat	active	2026-04-24

Add pyright Type-Checking to CI

Overview

pyright is in dev dependencies but never runs in CI. Adding it to the pytest workflow (or as a separate job) would catch type errors before merge.

Problem Frame

• Type errors are only caught locally (if the developer runs pyright)
• No enforcement of type annotations in PRs
• CODE_STYLE.md encourages typing but CI doesn't verify

Requirements Trace

• R1. pyright runs on every push/PR
• R2. pyright uses the same version as pyproject.toml
• R3. CI fails on type errors
• R4. Initial run establishes baseline (no new errors introduced)

Scope Boundaries

Included:

• Add pyright step to CI workflow
• Fix or suppress any existing type errors that block CI

Excluded:

• Adding type annotations to untyped code (do that incrementally)
• Changing pyright configuration beyond CI setup

Implementation Units

• U1. Add pyright CI job

Goal: Run pyright in GitHub Actions.

Requirements: R1, R2, R3

Dependencies: None

Files:

• Modify: .github/workflows/pytest.yml

Approach:

• Add a pyright job parallel to pytest
• Use uv run pyright (same version as local)

Test scenarios:

• Happy path: Typed code passes pyright
• Error path: Type error fails the CI job
• Integration: pyright version matches pyproject.toml

Verification:

• CI runs pyright successfully

---

• U2. Establish baseline

Goal: Ensure CI passes on current code.

Requirements: R4

Dependencies: U1

Files:

• Modify: Files with fixable type errors
• Modify: pyproject.toml (add suppressions for unfixable legacy issues)

Approach:

• Run uv run pyright locally
• Fix trivial errors; suppress complex legacy ones with # type: ignore or pyrightconfig
• Document suppressions

Test scenarios:

• Happy path: uv run pyright exits 0

Verification:

• uv run pyright passes locally
• CI pyright job passes

---

Risks & Dependencies

Risk	Mitigation
Many existing type errors	Fix batch-by-batch; don't block this PR on full cleanup
pyright is slow in CI	Run in parallel with pytest; cache node_modules

Sources & References

• pyproject.toml dev dependencies
• .github/workflows/pytest.yml (from P1-001)