Skip to content

Latest commit

 

History

History
224 lines (172 loc) · 10.2 KB

design.md

File metadata and controls

224 lines (172 loc) · 10.2 KB

rules_pyrefly Design

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.

Purpose

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.

Goals

  • 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.

Non-Goals

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.toml discovery or merging. Bazel-facing configuration stays on the aspect for v1.
  • Automatic types-* or *-stubs dependency 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 through PyInfo.
  • Label-specific severity maps. Global severity tuning is enough for the first API.

Major Decisions

Separate Ruleset

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.

Aspect-Based Integration

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.

Check Owned Files, Import Dependencies

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.

Keep Rule Layer Thin

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.

Be Explicit About Import-Layout Limits

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.

Model the Target Environment

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.

Hermetic Toolchains With an Escape Hatch

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.

Statically-Linked musl Binaries on Linux

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.

Public Shape

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_cli executable override.
  • Modeled python_version and system_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 Strategy

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.

Deferred Work

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.typed package-data modeling.
  • Richer target runtime metadata from rules_python providers or toolchains.
  • Richer integration with pyrefly.toml.