Skip to content

Latest commit

 

History

History
189 lines (148 loc) · 8.22 KB

integration.md

File metadata and controls

189 lines (148 loc) · 8.22 KB

rules_pyrefly / Pyrefly Bazel Integration

Status: v1 Starlark-side contract plus current gaps.

This document describes what the rules_pyrefly Starlark layer is responsible for when it invokes pyrefly bazel-check. The high-level product and release design is in design.md. Pyrefly's internal module-resolution and type-checking behavior belongs in the Pyrefly repository.

Boundary

rules_pyrefly owns Bazel plumbing. It selects targets, resolves the checker binary, prepares Bazel facts, declares action inputs, invokes Pyrefly, and exposes Bazel outputs. Pyrefly owns interpretation of those facts.

The Starlark layer should stay thin. Its job is to pass the raw Bazel information Pyrefly needs in a stable shape.

Target Selection

The aspect traverses deps and uses required_providers = [PyInfo] so Bazel does not invoke it on non-Python targets. A target is checked only when it is in the root workspace, it passes the configured tag policy, and it owns at least one direct Python source or stub after helper paths such as /_virtual_imports/ are filtered out.

Tag policy is intentionally simple: suppression_tags wins first, then opt_in_tags is checked. With no opt-in tags, all otherwise eligible Python targets are checked. The tag policy and initial target-selection structure were adapted from rules_mypy.

The check roots are the target-owned files from PyInfo.direct_original_sources and PyInfo.direct_pyi_files. Dependency-owned files are available for imports, but they are not check roots for the current target's action.

Action Model

For each selected target, the aspect writes one input JSON file and runs one pyrefly bazel-check action:

pyrefly --color <when> bazel-check \
  --output <diagnostics.json> \
  --min-severity <level> \
  <input.json>

The action inputs are the generated input JSON and the target's transitive Python source and stub files from PyInfo. Those transitive files are the importable file universe for the action. The ruleset should not add broad runfiles or package data just to approximate Python packaging metadata such as py.typed; exact PEP 561 marker visibility is deferred for v1.

The action returns diagnostic JSON in the pyrefly output group. The generated input JSON is also exposed in the debug-only pyrefly_input output group so the rules-side behavior can be inspected without reverse-engineering the action.

Input JSON

The input JSON names the target-owned check roots and carries enough Bazel facts for Pyrefly to construct its Bazel-mode import view. It should not list every ordinary dependency file; those files are already present as action inputs.

The top-level sections are:

  • target: identity and debugging information such as label, package, target name, rule kind, and workspace name.
  • check_roots: direct source and stub File.short_path values owned by the current target.
  • search_path: Bazel Python search-path facts, including explicit imports, workspace name, repository-root facts, and executable main-file facts.
  • path_overlays: sparse file facts for transitive .py and .pyi files whose readable action path differs from their short_path.
  • config: modeled Python environment and Pyrefly configuration passed through the aspect.

The shape is intentionally coarse-grained:

{
  "target": {},
  "check_roots": {
    "sources": [],
    "stubs": []
  },
  "search_path": {},
  "path_overlays": [],
  "config": {}
}

Field names are part of the v1 contract and should change only in lockstep with the Pyrefly release that consumes them. min_severity remains a CLI flag rather than a JSON field.

Search-Path Facts

PyInfo.imports is not a complete runtime search path. The ruleset must also pass the workspace and repository-root facts needed to model rules_python launcher behavior. Starlark should preserve the observed target[PyInfo].imports.to_list() order and should pass executable main-file facts for py_binary and py_test targets, but Pyrefly decides how those facts affect import resolution.

Generated files need sparse overlays because their readable action path can differ from the runtime-shaped File.short_path. The aspect should emit an overlay only when File.path != File.short_path, and the overlay should contain only short_path and path.

The implementation reads the rules_python import-all setting. When import-all mode is disabled, repository_roots contains only the current workspace. When it is enabled, repository_roots contains the sorted repository roots observed from the transitive Python source and stub inputs, including external repositories.

rules_python can also materialize PyPI dependencies as a virtualenv-style site-packages tree with --venvs_site_packages=yes. In that mode, PyInfo.imports is not the full runtime import layout; the relevant facts are available through PyInfo.venv_symlinks. The current implementation does not model this mode yet. That should be treated as an open compatibility gap: either support it using the venv symlink facts directly, or document a clear limitation before claiming PyPI import-layout coverage.

Bazel's legacy automatic __init__.py generation is another import-layout compatibility question. Those synthetic files can make directories importable even when the source tree does not contain package markers, which is especially confusing for namespace packages. The current implementation does not synthesize missing __init__.py files for Pyrefly. Before claiming support for generated init behavior, we should either model those synthetic files explicitly or document the limitation and recommend --incompatible_default_to_explicit_init_py=true.

Toolchain and Environment Resolution

The Pyrefly executable is resolved in this order:

  1. pyrefly_cli, when supplied.
  2. A registered Pyrefly toolchain for the execution platform.
  3. A clear setup failure explaining how to configure one of the above.

The Pyrefly toolchain is optional from the aspect's point of view so unsupported platforms can fail with that setup message instead of an opaque toolchain resolution error.

python_version and system_platform model the target Python environment, not the machine running Pyrefly. python_version comes from the explicit aspect argument or the active rules_python toolchain. system_platform comes from the explicit aspect argument or the target platform's OS constraint. The aspect must not use the exec platform or Bazel host platform as a fallback for system_platform.

Future target-runtime facts should come from rules_python providers or toolchains when possible. For example, runtime implementation, stdlib or site-package layout, and ABI facts would be better passed as Bazel-provided metadata than hardcoded in either Starlark or Pyrefly based only on the version string.

Current Status

The current implementation targets Bazel 8.x and 9.x with rules_python 1.7.0 or newer. The bazel-check interface it depends on remains experimental in Pyrefly. Pyrefly 1.2.0 is the checked-in supported baseline and the first stable Pyrefly release that includes this interface.

The main v1 action path is implemented: target filtering, input JSON emission, Pyrefly invocation, action inputs, output groups, executable resolution, target environment inference, import-all repository roots, and release-toolchain generation.

Before stable ruleset usage, coverage should also exercise more external repository shapes, PyInfo.venv_symlinks / site-packages layouts, duplicate modules across search roots, and compatibility across Pyrefly releases.

Test Focus

Tests should primarily validate observable Starlark behavior:

  • which targets produce Pyrefly actions;
  • which files become check roots versus transitive action inputs;
  • what search-path and overlay facts appear in the generated JSON;
  • whether pyrefly_cli and registered toolchains resolve correctly;
  • whether diagnostics reach Bazel stderr and failing diagnostics fail the action.

The demo workspace and Python integration tests cover the current happy path, generated inputs, local fake-Pyrefly execution, and release-toolchain execution. New tests should concentrate on the remaining rules-side gaps rather than duplicating Pyrefly's own checker tests.