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.
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.
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.
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.
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 stubFile.short_pathvalues 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.pyand.pyifiles whose readable action path differs from theirshort_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.
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.
The Pyrefly executable is resolved in this order:
pyrefly_cli, when supplied.- A registered Pyrefly toolchain for the execution platform.
- 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.
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.
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_cliand 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.