---
title: "feat: Add pyright type-checking to CI"
type: feat
status: active
date: 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)