Pyrefly: Static Type Checking¶

Pyrefly is Meta's static type checker for Python written in Rust. It provides fast type inference, strict sound type validation, and native support for modern Python 3.12+ type system syntax.

What It Does¶

Pyrefly validates type soundness across Python codebases by evaluating Abstract Syntax Trees in Rust. It natively supports modern Python 3.12+ features—including PEP 695 generic syntax (def get_item[T](items: list[T]) -> T:), type aliases, and structural subtyping through typing.Protocol without requiring inheritance.

By validating function boundaries at compile time, Pyrefly catches missing type annotations, implicit dynamic conversions, and unsafe coercions with instant feedback.

Why It's in Zenith¶

Zenith runs Pyrefly in its highest-assurance configuration (preset = "strict"). This eliminates implicit Any and ensures that every public interface, parameter, and return value is explicitly typed and sound.

Autonomous AI agents frequently introduce loose type annotations or unconstrained generics when generating code. Operating Pyrefly in strict mode acts as an automated anti-hallucination guardrail, blocking untyped code from passing quality gates before human review.

Configuration in Zenith¶

Configured in pyrefly.toml at the project root:

# ==============================================================================
# Pyrefly Configuration (pyrefly.toml)
#
# Tool: Pyrefly (https://github.com/facebook/pyrefly)
# Purpose: Meta's next-generation, high-performance static type checker.
# Why it's in Zenith: Zenith standardizes on Pyrefly in "strict" preset mode as
# its sole type checker, delivering rapid type analysis and ensuring that all
# source and test files adhere to rigorous type contracts.
# ==============================================================================

enabled-ignores      = ["pyrefly"]
infer-with-first-use = false
preset               = "strict"
project-excludes     = ["**/.*", "**/site", "**/dist", "**/build", "**/.venv"]
project-includes     = ["src", "tests"]
python-version       = "{{ cookiecutter.python_version }}.0"

Strict Mode Invariants¶

Under strict mode, all function parameters and return types must be fully annotated. Implicit Any inference is strictly prohibited, structural protocols are validated at call sites, and any untyped third-party libraries require explicit stub declarations or typed wrappers.

Editor Experience & Alternative Type Checkers¶

Developers typically author code inside VS Code, Cursor, PyCharm, or Neovim:

Editor Language Servers (LSP): If your editor uses Pylance or Pyright for inline completions, Pyrefly operates harmoniously in the background, executing in milliseconds during uv run poe type-check, prek pre-commit hooks, and CI pipelines.
Third-Party Stubs & PEP 561: Pyrefly automatically ingests inline types from PEP 561 compliant libraries and community typeshed definitions. For legacy untyped dependencies, install typeshed stubs (e.g. uv add --dev types-requests) or wrap external APIs in typed boundary adapters.
Flexibility: If your organization mandates mypy or pyright, you can swap type checkers at any time by updating the [tasks.type-check] command in poe_tasks.toml.

Type Coverage & Completeness Enforcement¶

Beyond checking type correctness, Pyrefly provides native type coverage and completeness measurement via pyrefly coverage:

Coverage Metrics: Evaluates all typables across your package—function return types, parameters, module-level variables, and class attributes.
Strict Coverage (--strict): Annotations that resolve to Any count as untyped. Only sound, concrete types satisfy the threshold.
Public API Completeness (--public-only): Checks symbols reachable from public modules via re-export chains, guaranteeing PEP 561 completeness for library consumers.
Automated Gate: Zenith wires uv run poe type-coverage (pyrefly coverage check src --fail-under 100 --strict) directly into poe code-quality and CI pipelines.

Key Invocations¶

# Run static type analysis across project.
uv run pyrefly check

# Enforce 100% strict type coverage.
uv run pyrefly coverage check src --fail-under 100 --strict

# Check public API completeness.
uv run pyrefly coverage check src --public-only

# Generate detailed JSON coverage report.
uv run pyrefly coverage report src

# Run the strict type-checking task in Poe.
uv run poe type-check

# Run the type-coverage gate in Poe.
uv run poe type-coverage