Status: v1 design, experimental implementation
Author: Python Language Tooling
This document records the high-level design choices for rules_pyrefly: what
the ruleset is trying to provide, which responsibilities belong in Bazel versus
Pyrefly, and which tradeoffs are intentional. Low-level action details and the
JSON interface between the rules and Pyrefly live in
integration.md.
rules_pyrefly is an open-source Bazel ruleset for running
Pyrefly type checking over
rules_python targets. Users should be able to add it to an existing Bazel
Python project, pin one Pyrefly release, and run type checks through ordinary
Bazel commands without changing every py_library, py_binary, or py_test.
The ruleset is intentionally small. It handles Bazel concerns such as target selection, toolchain resolution, action creation, and configuration handoff. Pyrefly handles checker concerns such as module resolution, stub precedence, typeshed lookup, and diagnostics.
- Provide a Bazel aspect that checks Python targets without requiring wrapper rules or BUILD-file rewrites.
- Surface Pyrefly diagnostics through normal Bazel UX: action stderr, diagnostic outputs, and non-zero action failures.
- Keep setup hermetic and version-pinned through Bzlmod toolchains.
- Preserve the target's modeled Python environment, not the host or execution environment.
- Keep the public Bazel API small by exposing only Bazel-facing configuration. Complicated module-resolution logic belongs in Pyrefly itself.
These are intentionally out of scope for v1:
- Cross-target incremental caches. Bazel's action cache plus one action per checked target are the initial caching model.
pyrefly.tomldiscovery or merging. Bazel-facing configuration stays on the aspect for v1.- Automatic
types-*or*-stubsdependency discovery. Stub packages are ordinary Bazel dependencies. - Checking dependency-owned modules as part of a reverse dependency's action. Each target action checks only that target's own sources.
- Full
py.typed/ PEP 561 package-data modeling. v1 uses Python source and stub files exposed throughPyInfo. - Label-specific severity maps. Global severity tuning is enough for the first API.
rules_pyrefly lives outside the main Pyrefly repository. That gives the Bazel
rules their own release cadence, BCR packaging, examples, and compatibility
policy. It also lets Pyrefly binary releases and rules-only fixes move
independently.
Compatibility is expressed by mapping ruleset releases to supported Pyrefly
binary versions. The ruleset release owns the Bazel API and the generated
protocol shape; the selected Pyrefly release owns the checker behavior that
consumes that shape. This is enough while rules_pyrefly is the only producer
of the Bazel input and Pyrefly is the only consumer.
If the protocol grows beyond that single producer/consumer pair, we should
revisit the choice and consider adding an explicit version field to the
pyrefly bazel-check input. That would make compatibility negotiation more
visible, but it is extra schema surface that v1 does not need.
The ruleset uses an aspect instead of replacement Python rules. This lets users
apply Pyrefly to existing py_* targets with .bazelrc configuration and no
BUILD-file migration. It also matches how many Bazel projects already integrate
type checkers.
The tradeoff is that configuration is mostly aspect-level rather than target-level. That is a deliberate v1 simplification. Projects can use tags for broad opt-in/opt-out behavior, and more granular policy can be added later if real usage shows the need.
If users need configuration-sensitive policy later, such as checking a target on
one platform but skipping it on another, plain tags may not be expressive
enough. aspect_hints could be a better extension point because they can point
to labels that carry structured policy for the aspect to inspect.
Each Pyrefly action checks the current target's direct Python sources and stubs. Dependency sources and stubs are available for import resolution, but they are not rechecked as part of the reverse dependency's action.
This keeps action ownership clear and avoids repeatedly reporting dependency diagnostics from every target that imports them. The tradeoff is that users must run the aspect over the targets they want checked, typically a package or repository-wide pattern, rather than expecting one top-level binary to validate the whole dependency graph.
rules_pyrefly should keep the Starlark layer thin. Its job is to select
targets and forward the relevant PyInfo facts to pyrefly bazel-check, which
performs the downstream processing. Tasks such as deriving Python module names,
implementing stub precedence, or recreating rules_python runtime path behavior
beyond passing required Bazel facts should stay out of Starlark.
This keeps the ruleset simpler and reduces the risk of Bazel-specific behavior drifting from Pyrefly's normal import model.
Bazel and rules_python can alter runtime import layout in ways that are not
visible from ordinary source files alone. v1 should model the common
PyInfo-based path facts that Pyrefly needs, but it should not pretend to
support every runtime-materialization mode.
In particular, rules_python can build a virtualenv-style site-packages
layout for PyPI dependencies. Accurate support for that mode should be treated
as a first-class compatibility question and should be based on
PyInfo.venv_symlinks, not guessed from PyInfo.imports.
Bazel can also generate missing __init__.py files for Python runfiles. That
legacy behavior changes package and namespace-package semantics in ways that are
hard to infer from source inputs. rules_pyrefly needs an explicit policy for
that mode instead of silently claiming it matches Bazel's runtime behavior.
python_version and system_platform describe the Python environment being
checked, not the machine running Pyrefly. This matters for cross-builds and
remote execution, where the execution platform can differ from the target
Python platform.
The preferred path is to infer these values from Bazel toolchains and target platform constraints. When Bazel cannot expose enough information, the aspect asks users to pass explicit values rather than silently checking with host assumptions.
python_version and system_platform are only the initial target-environment
facts. If rules_python exposes richer runtime metadata later, such as runtime
implementation, stdlib layout, ABI facts, or site-package layout, the Bazel
input should be able to grow to carry those facts. That direction fits the
thin-Starlark design as long as the ruleset forwards provider data instead of
hardcoding Python runtime knowledge itself.
The default setup uses a Bzlmod extension to select one Pyrefly version, fetch checksummed release assets, and register platform-specific toolchains. This matches Bazel's hermeticity model and gives repositories a single, reviewable checker version.
The aspect also accepts a pyrefly_cli executable override. That keeps local
Pyrefly development, patched binaries, mirrors, and unsupported platforms
practical without complicating the default toolchain path.
The v1 policy intentionally selects one Pyrefly version per repository. Gradual
version rollout can be revisited later; for now, projects can test a candidate
binary by defining a second aspect configuration that uses pyrefly_cli.
The Linux toolchains download Pyrefly's musl release assets rather than the
default glibc ones. musl builds are statically linked, so they carry no
dependency on the execution host's glibc version and run identically on old
enterprise distros, Alpine images, and distroless containers. glibc binaries
instead couple the toolchain to the host's glibc and can fail at startup with
an opaque GLIBC_x.yy not found error when Bazel resolves a binary that was
built against a newer libc than the execution platform provides. Static linking
matches Bazel's hermeticity model: the resolved toolchain should behave the
same regardless of which machine runs it.
Static musl and dynamic glibc builds can still differ in performance. Pyrefly
uses jemalloc on Linux, so the usual musl allocator concern does not apply, but
representative benchmarks remain worthwhile. If a real regression shows up, a
repository can point the aspect's pyrefly_cli override at a glibc build as an
escape hatch.
Users configure rules_pyrefly in two places:
- A Bzlmod extension tag selects the Pyrefly binary version and optional release asset checksums.
- An aspect factory configures the checking policy for a build.
The aspect factory exposes only Bazel-relevant knobs:
- Optional
pyrefly_cliexecutable override. - Modeled
python_versionandsystem_platform. - Optional Pyrefly
preset. - Severity threshold and global per-error-kind severity overrides.
- Opt-out and opt-in tags.
- Diagnostic color mode.
The full API sketch and examples are in README.md.
Testing should stay focused on observable behavior rather than implementation shape. The examples should demonstrate realistic setup and failure modes, while focused tests should cover the Bazel-facing contract: target selection, action inputs, import-path facts, toolchain resolution, and error reporting.
The detailed contract tests for the Bazel/Pyrefly boundary are tracked in integration.md.
These areas are intentionally left for later versions unless early users show they are needed sooner:
- Per-target severity overrides.
- Structured or configuration-sensitive target policy, possibly through
aspect_hints. - First-class gradual Pyrefly version rollout.
- Cross-target Pyrefly cache propagation.
- Exact
py.typedpackage-data modeling. - Richer target runtime metadata from
rules_pythonproviders or toolchains. - Richer integration with
pyrefly.toml.