pants-pyrefly 0.1.0__py3-none-any.whl

pants_pyrefly/goals.py

@@ -0,0 +1,320 @@
+# Copyright 2026 Tague Griffith
+# Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Iterable
+
+import toml  # pants: no-infer-dep  (provided by the Pants runtime)
+
+from pants_pyrefly.rules import (
+    _BASELINE_OUTPUT,
+    PyreflyFieldSet,
+    PyreflyRequest,
+    _setup_pyrefly_process,
+    pyrefly_determine_partitions,
+)
+from pants_pyrefly.subsystems import Pyrefly
+
+from pants.backend.python.subsystems.setup import PythonSetup
+from pants.backend.python.util_rules.interpreter_constraints import InterpreterConstraints
+from pants.backend.python.util_rules.python_sources import (
+    PythonSourceFilesRequest,
+    prepare_python_sources,
+)
+from pants.engine.fs import (
+    EMPTY_DIGEST,
+    CreateDigest,
+    FileContent,
+    GlobMatchErrorBehavior,
+    PathGlobs,
+    Workspace,
+)
+from pants.engine.console import Console
+from pants.engine.goal import Goal, GoalSubsystem
+from pants.engine.intrinsics import (
+    create_digest,
+    execute_process,
+    get_digest_contents,
+    path_globs_to_digest,
+)
+from pants.engine.platform import Platform
+from pants.engine.process import ProcessCacheScope
+from pants.engine.rules import Rule, collect_rules, concurrently, goal_rule, implicitly
+from pants.engine.target import AllTargets, Targets
+from pants.engine.unions import UnionRule
+from pants.option.option_types import FloatOption
+from pants.util.strutil import softwrap
+
+logger = logging.getLogger(__name__)
+
+
+# ---
+# `pyrefly-update-baseline`
+# ---
+
+
+class PyreflyUpdateBaselineSubsystem(GoalSubsystem):
+    name = "pyrefly-update-baseline"
+    help = softwrap(
+        """
+        Run Pyrefly and (re)write the baseline file configured by `[pyrefly].baseline`, recording
+        the current type errors so that a subsequent `pants check` reports only NEW ones.
+        """
+    )
+
+
+class PyreflyUpdateBaseline(Goal):
+    subsystem_cls = PyreflyUpdateBaselineSubsystem
+    environment_behavior = Goal.EnvironmentBehavior.LOCAL_ONLY
+
+
+@goal_rule
+async def pyrefly_update_baseline(
+    targets: Targets,
+    pyrefly: Pyrefly,
+    workspace: Workspace,
+    platform: Platform,
+    python_setup: PythonSetup,
+) -> PyreflyUpdateBaseline:
+    if not pyrefly.baseline:
+        logger.error(
+            softwrap(
+                """
+                Set `[pyrefly].baseline` to the path where the baseline file should be written,
+                then re-run `pants pyrefly-update-baseline`.
+                """
+            )
+        )
+        return PyreflyUpdateBaseline(exit_code=1)
+
+    field_sets = tuple(
+        PyreflyFieldSet.create(tgt)
+        for tgt in targets
+        if PyreflyFieldSet.is_applicable(tgt) and not PyreflyFieldSet.opt_out(tgt)
+    )
+    if not field_sets:
+        logger.warning("No Pyrefly-applicable targets in scope; the baseline was not changed.")
+        return PyreflyUpdateBaseline(exit_code=0)
+
+    partitions = await pyrefly_determine_partitions(PyreflyRequest(field_sets), **implicitly())
+    processes = await concurrently(
+        _setup_pyrefly_process(
+            partition,
+            pyrefly,
+            platform,
+            python_setup,
+            update_baseline=True,
+            cache_scope=ProcessCacheScope.PER_SESSION,
+        )
+        for partition in partitions
+    )
+    results = await concurrently(execute_process(process, **implicitly()) for process in processes)
+
+    for result in results:
+        # 0 == no errors, 1 == errors found (both expected); anything else is a tool failure, and
+        # we must not clobber a good baseline with a partial/empty one.
+        if result.exit_code not in (0, 1):
+            logger.error(
+                f"Pyrefly exited with code {result.exit_code} while updating the baseline; "
+                f"leaving the existing baseline unchanged.\n"
+                f"{result.stderr.decode(errors='replace')}"
+            )
+            return PyreflyUpdateBaseline(exit_code=result.exit_code)
+
+    # Merge the per-partition baselines (each is `{"errors": [...]}`) into a single file.
+    all_errors: list = []
+    for result in results:
+        for file_content in await get_digest_contents(result.output_digest):
+            if file_content.path == _BASELINE_OUTPUT and file_content.content.strip():
+                all_errors.extend(json.loads(file_content.content).get("errors", []))
+
+    merged = json.dumps({"errors": all_errors}, indent=2).encode()
+    output_digest = await create_digest(CreateDigest([FileContent(pyrefly.baseline, merged)]))
+    workspace.write_digest(output_digest)
+    logger.info(f"Wrote Pyrefly baseline with {len(all_errors)} error(s) to `{pyrefly.baseline}`.")
+    return PyreflyUpdateBaseline(exit_code=0)
+
+
+# ---
+# `pyrefly-lsp-config`
+# ---
+
+
+class PyreflyLspConfigSubsystem(GoalSubsystem):
+    name = "pyrefly-lsp-config"
+    help = softwrap(
+        """
+        Write Pants's source roots (and target Python version) into `pyrefly.toml` as `search-path`,
+        so the Pyrefly IDE/LSP resolves first-party imports the way Pants does. Point your editor's
+        interpreter at a venv (e.g. `pants export`) for third-party imports.
+        """
+    )
+
+
+class PyreflyLspConfig(Goal):
+    subsystem_cls = PyreflyLspConfigSubsystem
+    environment_behavior = Goal.EnvironmentBehavior.LOCAL_ONLY
+
+
+@goal_rule
+async def pyrefly_lsp_config(
+    all_targets: AllTargets,
+    python_setup: PythonSetup,
+    workspace: Workspace,
+) -> PyreflyLspConfig:
+    python_targets = [tgt for tgt in all_targets if PyreflyFieldSet.is_applicable(tgt)]
+    if not python_targets:
+        logger.warning("No Python source targets found; not writing a Pyrefly LSP config.")
+        return PyreflyLspConfig(exit_code=0)
+
+    sources = await prepare_python_sources(PythonSourceFilesRequest(python_targets), **implicitly())
+    python_version = InterpreterConstraints(
+        python_setup.interpreter_constraints
+    ).minimum_python_version(python_setup.interpreter_versions_universe)
+
+    settings: dict = {"search-path": sorted(sources.source_roots)}
+    if python_version:
+        settings["python-version"] = python_version
+
+    pyrefly_toml_digest, pyproject_digest = await concurrently(
+        path_globs_to_digest(
+            PathGlobs(["pyrefly.toml"], glob_match_error_behavior=GlobMatchErrorBehavior.ignore)
+        ),
+        path_globs_to_digest(
+            PathGlobs(["pyproject.toml"], glob_match_error_behavior=GlobMatchErrorBehavior.ignore)
+        ),
+    )
+
+    pyproject_has_pyrefly = False
+    if pyproject_digest != EMPTY_DIGEST:
+        pyproject_text = (await get_digest_contents(pyproject_digest))[0].content.decode()
+        pyproject_has_pyrefly = "pyrefly" in toml.loads(pyproject_text).get("tool", {})
+
+    # Don't create a `pyrefly.toml` that would shadow an existing `pyproject.toml [tool.pyrefly]`.
+    if pyrefly_toml_digest == EMPTY_DIGEST and pyproject_has_pyrefly:
+        logger.warning(
+            softwrap(
+                """
+                Your Pyrefly config lives in `pyproject.toml` under `[tool.pyrefly]`. A separate
+                `pyrefly.toml` would take precedence over it, so it was not written. Add these keys
+                to your `[tool.pyrefly]` table instead:
+                """
+            )
+            + f"\n\n{toml.dumps(settings).strip()}\n"
+        )
+        return PyreflyLspConfig(exit_code=0)
+
+    # Merge into an existing `pyrefly.toml` (preserving other keys) or create a new one.
+    existing: dict = {}
+    if pyrefly_toml_digest != EMPTY_DIGEST:
+        existing = toml.loads((await get_digest_contents(pyrefly_toml_digest))[0].content.decode())
+    existing.update(settings)
+
+    output_digest = await create_digest(
+        CreateDigest([FileContent("pyrefly.toml", toml.dumps(existing).encode())])
+    )
+    workspace.write_digest(output_digest)
+    logger.info(
+        f"Wrote {len(settings['search-path'])} source root(s) to `pyrefly.toml` as Pyrefly "
+        f"`search-path`. Point your editor's interpreter at a venv (e.g. `pants export`) for "
+        f"third-party imports."
+    )
+    return PyreflyLspConfig(exit_code=0)
+
+
+# ---
+# `pyrefly-coverage`
+# ---
+
+
+class PyreflyCoverageSubsystem(GoalSubsystem):
+    name = "pyrefly-coverage"
+    help = softwrap(
+        """
+        Report Pyrefly type coverage — the share of typable symbols that have a non-`Any` type —
+        across the targeted Python sources.
+        """
+    )
+
+    fail_under = FloatOption(
+        default=None,
+        help="If set, exit non-zero when overall type coverage is below this percentage (0-100).",
+    )
+
+
+class PyreflyCoverage(Goal):
+    subsystem_cls = PyreflyCoverageSubsystem
+    environment_behavior = Goal.EnvironmentBehavior.LOCAL_ONLY
+
+
+@goal_rule
+async def pyrefly_coverage(
+    targets: Targets,
+    pyrefly: Pyrefly,
+    coverage_subsystem: PyreflyCoverageSubsystem,
+    console: Console,
+    platform: Platform,
+    python_setup: PythonSetup,
+) -> PyreflyCoverage:
+    field_sets = tuple(
+        PyreflyFieldSet.create(tgt)
+        for tgt in targets
+        if PyreflyFieldSet.is_applicable(tgt) and not PyreflyFieldSet.opt_out(tgt)
+    )
+    if not field_sets:
+        logger.warning("No Pyrefly-applicable targets in scope.")
+        return PyreflyCoverage(exit_code=0)
+
+    partitions = await pyrefly_determine_partitions(PyreflyRequest(field_sets), **implicitly())
+    processes = await concurrently(
+        _setup_pyrefly_process(
+            partition,
+            pyrefly,
+            platform,
+            python_setup,
+            subcommand=("coverage", "report"),
+            cache_scope=ProcessCacheScope.SUCCESSFUL,
+        )
+        for partition in partitions
+    )
+    results = await concurrently(execute_process(process, **implicitly()) for process in processes)
+
+    total_typable = 0
+    total_typed = 0
+    for result in results:
+        if result.exit_code != 0:
+            logger.error(
+                f"Pyrefly coverage failed (exit {result.exit_code}):\n"
+                f"{result.stderr.decode(errors='replace')}"
+            )
+            return PyreflyCoverage(exit_code=result.exit_code)
+        try:
+            report = json.loads(result.stdout)
+        except json.JSONDecodeError:
+            logger.error(
+                "Could not parse Pyrefly coverage output as JSON:\n"
+                f"{result.stdout.decode(errors='replace')[:500]}"
+            )
+            return PyreflyCoverage(exit_code=1)
+        for module_report in report.get("module_reports", []):
+            for symbol in module_report.get("symbol_reports", []):
+                total_typable += symbol.get("n_typable", 0)
+                total_typed += symbol.get("n_typed", 0)
+
+    pct = (100.0 * total_typed / total_typable) if total_typable else 100.0
+    console.print_stdout(
+        f"Pyrefly type coverage: {pct:.1f}% ({total_typed}/{total_typable} typable symbols)"
+    )
+    if coverage_subsystem.fail_under is not None and pct < coverage_subsystem.fail_under:
+        console.print_stderr(
+            f"Type coverage {pct:.1f}% is below the required {coverage_subsystem.fail_under}%."
+        )
+        return PyreflyCoverage(exit_code=1)
+    return PyreflyCoverage(exit_code=0)
+
+
+def rules() -> Iterable[Rule | UnionRule]:
+    return (*collect_rules(),)

pants_pyrefly/register.py

@@ -0,0 +1,23 @@
+# Copyright 2026 Tague Griffith
+# Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+"""A Pants plugin that runs the Pyrefly type checker (https://pyrefly.org) in the `check` goal."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from pants_pyrefly import goals
+from pants_pyrefly import rules as pyrefly_rules
+from pants_pyrefly import skip_field, subsystems
+from pants.engine.rules import Rule
+from pants.engine.unions import UnionRule
+
+
+def rules() -> Iterable[Rule | UnionRule]:
+    return (
+        *pyrefly_rules.rules(),
+        *goals.rules(),
+        *skip_field.rules(),
+        *subsystems.rules(),
+    )

pants_pyrefly/rules.py

@@ -0,0 +1,368 @@
+# Copyright 2026 Tague Griffith
+# Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+from __future__ import annotations
+
+import logging
+import os
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+from pants_pyrefly.skip_field import SkipPyreflyField
+from pants_pyrefly.subsystems import Pyrefly
+
+from pants.backend.python.subsystems.setup import PythonSetup
+from pants.backend.python.target_types import (
+    InterpreterConstraintsField,
+    PythonResolveField,
+    PythonSourceField,
+)
+from pants.backend.python.util_rules import pex_from_targets
+from pants.backend.python.util_rules.interpreter_constraints import InterpreterConstraints
+from pants.backend.python.util_rules.partition import (
+    _partition_by_interpreter_constraints_and_resolve,
+)
+from pants.backend.python.util_rules.pex import Pex, PexRequest, create_pex, create_venv_pex
+from pants.backend.python.util_rules.pex_from_targets import RequirementsPexRequest
+from pants.backend.python.util_rules.pex_requirements import PexRequirements
+from pants.backend.python.util_rules.python_sources import (
+    PythonSourceFilesRequest,
+    prepare_python_sources,
+)
+from pants.core.goals.check import CheckRequest, CheckResult, CheckResults, CheckSubsystem
+from pants.core.util_rules import config_files
+from pants.core.util_rules.config_files import find_config_file
+from pants.core.util_rules.external_tool import download_external_tool
+from pants.core.util_rules.source_files import SourceFilesRequest, determine_source_files
+from pants.engine.collection import Collection
+from pants.engine.fs import (
+    EMPTY_DIGEST,
+    CreateDigest,
+    FileContent,
+    GlobMatchErrorBehavior,
+    MergeDigests,
+    PathGlobs,
+)
+
+try:
+    # Pants >= 2.30 renamed this call-by-name rule.
+    from pants.engine.internals.graph import resolve_coarsened_targets as coarsened_targets_get
+except ImportError:
+    # Pants < 2.30 (e.g. 2.27) — identical call signature, earlier name.
+    from pants.engine.internals.graph import coarsened_targets as coarsened_targets_get
+from pants.engine.intrinsics import (
+    create_digest,
+    execute_process,
+    merge_digests,
+    path_globs_to_digest,
+)
+from pants.engine.platform import Platform
+from pants.engine.process import Process, ProcessCacheScope
+from pants.engine.rules import Rule, collect_rules, concurrently, implicitly, rule
+from pants.engine.target import CoarsenedTargets, CoarsenedTargetsRequest, FieldSet, Target
+from pants.engine.unions import UnionRule
+from pants.util.logging import LogLevel
+from pants.util.ordered_set import FrozenOrderedSet, OrderedSet
+from pants.util.strutil import pluralize, softwrap
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class PyreflyFieldSet(FieldSet):
+    required_fields = (PythonSourceField,)
+
+    sources: PythonSourceField
+    resolve: PythonResolveField
+    interpreter_constraints: InterpreterConstraintsField
+
+    @classmethod
+    def opt_out(cls, tgt: Target) -> bool:
+        return tgt.get(SkipPyreflyField).value
+
+
+class PyreflyRequest(CheckRequest):
+    field_set_type = PyreflyFieldSet
+    tool_name = Pyrefly.options_scope
+
+
+@dataclass(frozen=True)
+class PyreflyPartition:
+    field_sets: FrozenOrderedSet[PyreflyFieldSet]
+    root_targets: CoarsenedTargets
+    resolve_description: str | None
+    interpreter_constraints: InterpreterConstraints
+
+    def description(self) -> str:
+        ics = str(sorted(str(c) for c in self.interpreter_constraints))
+        return f"{self.resolve_description}, {ics}" if self.resolve_description else ics
+
+
+class PyreflyPartitions(Collection[PyreflyPartition]):
+    pass
+
+
+@rule(
+    desc="Partition Pyrefly's input by resolve and interpreter constraints",
+    level=LogLevel.DEBUG,
+)
+async def pyrefly_determine_partitions(
+    request: PyreflyRequest, pyrefly: Pyrefly, python_setup: PythonSetup
+) -> PyreflyPartitions:
+    resolve_and_interpreter_constraints_to_field_sets = (
+        _partition_by_interpreter_constraints_and_resolve(request.field_sets, python_setup)
+    )
+
+    coarsened_targets = await coarsened_targets_get(
+        CoarsenedTargetsRequest(field_set.address for field_set in request.field_sets),
+        **implicitly(),
+    )
+    coarsened_targets_by_address = coarsened_targets.by_address()
+
+    return PyreflyPartitions(
+        PyreflyPartition(
+            FrozenOrderedSet(field_sets),
+            CoarsenedTargets(
+                OrderedSet(
+                    coarsened_targets_by_address[field_set.address] for field_set in field_sets
+                )
+            ),
+            resolve if len(python_setup.resolves) > 1 else None,
+            interpreter_constraints or pyrefly.interpreter_constraints,
+        )
+        for (resolve, interpreter_constraints), field_sets in sorted(
+            resolve_and_interpreter_constraints_to_field_sets.items()
+        )
+    )
+
+
+# Fixed sandbox path where `--update-baseline` writes the baseline; the update-baseline goal
+# relocates it to the user's configured `[pyrefly].baseline` path on write-back.
+_BASELINE_OUTPUT = "__pyrefly_baseline_out.json"
+
+
+async def _setup_pyrefly_process(
+    partition: PyreflyPartition,
+    pyrefly: Pyrefly,
+    platform: Platform,
+    python_setup: PythonSetup,
+    *,
+    subcommand: tuple[str, ...] = ("check",),
+    update_baseline: bool = False,
+    cache_scope: ProcessCacheScope,
+) -> Process:
+    # Gather, concurrently:
+    #   - the Pyrefly binary itself,
+    #   - the root source files we are reporting on,
+    #   - the full first-party dependency closure on disk (+ its source roots),
+    #   - a PEX of the third-party requirements, and
+    #   - any discovered Pyrefly config file.
+    (
+        downloaded_pyrefly,
+        root_sources,
+        transitive_sources,
+        requirements_pex,
+        config_file_snapshot,
+    ) = await concurrently(
+        download_external_tool(pyrefly.get_request(platform)),
+        determine_source_files(SourceFilesRequest(fs.sources for fs in partition.field_sets)),
+        prepare_python_sources(
+            PythonSourceFilesRequest(partition.root_targets.closure()), **implicitly()
+        ),
+        create_pex(
+            **implicitly(
+                RequirementsPexRequest(
+                    (fs.address for fs in partition.field_sets),
+                    hardcoded_interpreter_constraints=partition.interpreter_constraints,
+                )
+            )
+        ),
+        find_config_file(pyrefly.config_request()),
+    )
+
+    # Optionally resolve extra type-stub packages and merge them into the same venv, so Pyrefly
+    # sees their types without them becoming runtime dependencies of the checked code.
+    extra_stub_pexes: list[Pex] = []
+    if pyrefly.extra_type_stubs:
+        extra_stubs_pex = await create_pex(
+            **implicitly(
+                PexRequest(
+                    output_filename="pyrefly_extra_type_stubs.pex",
+                    internal_only=True,
+                    requirements=PexRequirements(
+                        pyrefly.extra_type_stubs,
+                        description_of_origin="the option `[pyrefly].extra_type_stubs`",
+                    ),
+                    interpreter_constraints=partition.interpreter_constraints,
+                )
+            )
+        )
+        extra_stub_pexes = [extra_stubs_pex]
+
+    # Wrap the third-party requirements (plus any extra type stubs) in a venv PEX. We point
+    # Pyrefly's `--python-interpreter-path` at this venv's Python so it can discover the third-party
+    # `site-packages` (and the target Python version) exactly the way `import` would at runtime.
+    requirements_venv_pex = await create_venv_pex(
+        **implicitly(
+            PexRequest(
+                output_filename="requirements_venv.pex",
+                internal_only=True,
+                pex_path=[requirements_pex, *extra_stub_pexes],
+                interpreter_constraints=partition.interpreter_constraints,
+            )
+        )
+    )
+
+    # Baseline handling (check only). In `update` mode we (re)write a baseline to a fixed sandbox
+    # path and capture it; otherwise we materialize the user's baseline (if set) and gate on it.
+    is_check = subcommand == ("check",)
+    baseline_args: list[str] = []
+    baseline_digest = EMPTY_DIGEST
+    output_files: tuple[str, ...] = ()
+    if update_baseline:
+        baseline_args = [f"--baseline={_BASELINE_OUTPUT}", "--update-baseline"]
+        output_files = (_BASELINE_OUTPUT,)
+    elif is_check and pyrefly.baseline:
+        baseline_digest = await path_globs_to_digest(
+            PathGlobs(
+                [pyrefly.baseline],
+                glob_match_error_behavior=GlobMatchErrorBehavior.ignore,
+            )
+        )
+        if baseline_digest != EMPTY_DIGEST:
+            baseline_args = [f"--baseline={pyrefly.baseline}"]
+        else:
+            logger.warning(
+                softwrap(
+                    f"""
+                    `[pyrefly].baseline` is set to `{pyrefly.baseline}`, but that file does not
+                    exist. Run `pants pyrefly-update-baseline` to create it; checking without a
+                    baseline for now.
+                    """
+                )
+            )
+
+    # Pass the files to check via an argfile rather than argv, so we never hit OS command-line
+    # length limits on targets with many files (Pyrefly reads `@<file>`, like other clap CLIs).
+    file_list_path = "__pyrefly_files.txt"
+    file_list_digest = await create_digest(
+        CreateDigest([FileContent(file_list_path, "\n".join(root_sources.snapshot.files).encode())])
+    )
+
+    input_digest = await merge_digests(
+        MergeDigests(
+            (
+                root_sources.snapshot.digest,
+                transitive_sources.source_files.snapshot.digest,
+                config_file_snapshot.snapshot.digest,
+                requirements_venv_pex.digest,
+                file_list_digest,
+                baseline_digest,
+            )
+        )
+    )
+
+    tool_key = "__pyrefly_tool"
+    exe_path = os.path.normpath(os.path.join(tool_key, downloaded_pyrefly.exe))
+
+    python_version = partition.interpreter_constraints.minimum_python_version(
+        python_setup.interpreter_versions_universe
+    )
+
+    argv: list[str] = [exe_path, *subcommand]
+    # First-party import roots (the analogue of MYPYPATH / sys.path).
+    argv.extend(f"--search-path={source_root}" for source_root in transitive_sources.source_roots)
+    # Third-party deps + interpreter introspection.
+    argv.append(f"--python-interpreter-path={requirements_venv_pex.python.argv0}")
+    if python_version:
+        argv.append(f"--python-version={python_version}")
+    # An explicitly-configured config file. Discovered configs are found by Pyrefly itself
+    # relative to the sandbox cwd; both are materialized into the input digest above.
+    if pyrefly.config:
+        argv.append(f"--config={pyrefly.config}")
+    if is_check:
+        # `check`-only flags; `coverage report`/`check` do not accept these.
+        if pyrefly.output_format:
+            argv.append(f"--output-format={pyrefly.output_format}")
+        if pyrefly.min_severity:
+            argv.append(f"--min-severity={pyrefly.min_severity}")
+        argv.extend(f"--only={error_kind}" for error_kind in pyrefly.only)
+        argv.extend(baseline_args)
+        # User-provided args (can override any of the above).
+        argv.extend(pyrefly.args)
+    # The files to report on, passed via the argfile created above.
+    argv.append(f"@{file_list_path}")
+
+    return Process(
+        argv=tuple(argv),
+        input_digest=input_digest,
+        immutable_input_digests={tool_key: downloaded_pyrefly.digest},
+        append_only_caches=requirements_venv_pex.append_only_caches or {},
+        output_files=output_files,
+        description=f"Run Pyrefly on {pluralize(len(root_sources.snapshot.files), 'file')}.",
+        level=LogLevel.DEBUG,
+        cache_scope=cache_scope,
+    )
+
+
+@rule(
+    desc="Pyrefly typecheck each partition based on its interpreter_constraints",
+    level=LogLevel.DEBUG,
+)
+async def pyrefly_typecheck_partition(
+    partition: PyreflyPartition,
+    pyrefly: Pyrefly,
+    check_subsystem: CheckSubsystem,
+    platform: Platform,
+    python_setup: PythonSetup,
+) -> CheckResult:
+    process = await _setup_pyrefly_process(
+        partition,
+        pyrefly,
+        platform,
+        python_setup,
+        update_baseline=False,
+        # `default_process_cache_scope` (which honors `--force`) exists on Pants >= 2.30;
+        # on 2.27 fall back to the normal "cache successful runs" scope.
+        cache_scope=getattr(
+            check_subsystem, "default_process_cache_scope", ProcessCacheScope.SUCCESSFUL
+        ),
+    )
+    process_result = await execute_process(process, **implicitly())
+    # Exit 0 == clean, 1 == type errors found. Anything else (e.g. 3, or a 101 panic) is a Pyrefly
+    # tool failure, not type errors — flag it so users don't misread a crash as code problems.
+    if process_result.exit_code not in (0, 1):
+        logger.warning(
+            softwrap(
+                f"""
+                Pyrefly exited with code {process_result.exit_code} on partition
+                ({partition.description()}). This usually indicates a Pyrefly tool error rather than
+                type errors in your code; see the output above.
+                """
+            )
+        )
+    return CheckResult.from_fallible_process_result(
+        process_result,
+        partition_description=partition.description(),
+    )
+
+
+@rule(desc="Typecheck using Pyrefly", level=LogLevel.DEBUG)
+async def pyrefly_typecheck(request: PyreflyRequest, pyrefly: Pyrefly) -> CheckResults:
+    if pyrefly.skip:
+        return CheckResults([], checker_name=request.tool_name)
+
+    partitions = await pyrefly_determine_partitions(request, **implicitly())
+    partitioned_results = await concurrently(
+        pyrefly_typecheck_partition(partition, **implicitly()) for partition in partitions
+    )
+    return CheckResults(partitioned_results, checker_name=request.tool_name)
+
+
+def rules() -> Iterable[Rule | UnionRule]:
+    return (
+        *collect_rules(),
+        *config_files.rules(),
+        *pex_from_targets.rules(),
+        UnionRule(CheckRequest, PyreflyRequest),
+    )

pants_pyrefly/skip_field.py

@@ -0,0 +1,33 @@
+# Copyright 2026 Tague Griffith
+# Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from pants.backend.python.target_types import (
+    PythonSourcesGeneratorTarget,
+    PythonSourceTarget,
+    PythonTestsGeneratorTarget,
+    PythonTestTarget,
+    PythonTestUtilsGeneratorTarget,
+)
+from pants.engine.rules import Rule
+from pants.engine.target import BoolField
+from pants.engine.unions import UnionRule
+
+
+class SkipPyreflyField(BoolField):
+    alias = "skip_pyrefly"
+    default = False
+    help = "If true, don't run Pyrefly on this target's code."
+
+
+def rules() -> Iterable[Rule | UnionRule]:
+    return (
+        PythonSourcesGeneratorTarget.register_plugin_field(SkipPyreflyField),
+        PythonSourceTarget.register_plugin_field(SkipPyreflyField),
+        PythonTestsGeneratorTarget.register_plugin_field(SkipPyreflyField),
+        PythonTestTarget.register_plugin_field(SkipPyreflyField),
+        PythonTestUtilsGeneratorTarget.register_plugin_field(SkipPyreflyField),
+    )

pants_pyrefly/subsystems.py

@@ -0,0 +1,174 @@
+# Copyright 2026 Tague Griffith
+# Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from pants.backend.python.util_rules.interpreter_constraints import InterpreterConstraints
+from pants.core.goals.resolves import ExportableTool
+from pants.core.util_rules.config_files import ConfigFilesRequest
+from pants.core.util_rules.external_tool import TemplatedExternalTool
+from pants.engine.platform import Platform
+from pants.engine.rules import Rule, collect_rules
+from pants.engine.unions import UnionRule
+from pants.option.option_types import (
+    ArgsListOption,
+    BoolOption,
+    FileOption,
+    SkipOption,
+    StrListOption,
+    StrOption,
+)
+from pants.util.strutil import help_text
+
+
+class Pyrefly(TemplatedExternalTool):
+    options_scope = "pyrefly"
+    name = "Pyrefly"
+    help = help_text(
+        """
+        Pyrefly, a fast Python type checker written in Rust (https://pyrefly.org).
+
+        Pants downloads the official prebuilt Pyrefly binary from the project's GitHub
+        releases and runs it as part of the `check` goal.
+        """
+    )
+
+    default_version = "1.1.1"
+    default_url_template = (
+        "https://github.com/facebook/pyrefly/releases/download/{version}/pyrefly-{platform}.tar.gz"
+    )
+    # Linux uses the statically-linked musl builds so the binary runs on any distro
+    # regardless of the host glibc version.
+    default_url_platform_mapping = {
+        "macos_arm64": "macos-arm64",
+        "macos_x86_64": "macos-x86_64",
+        "linux_arm64": "linux-arm64-musl",
+        "linux_x86_64": "linux-x86_64-musl",
+    }
+    default_known_versions = [
+        "1.1.1|macos_arm64|022a989d2af4748e4d75a48fed7dbb0cc49f30a4b83745d4e4f742d0920ada70|12621775",
+        "1.1.1|macos_x86_64|191c7ee2891d2ab55a05b078c94832266e1dda78a9a0381a95fde13a2a27a38b|13278762",
+        "1.1.1|linux_arm64|f55454ac41ed1c086af1bd3cfbe2c2a25b960e46551df50ce047bc1ccb11fb35|13028969",
+        "1.1.1|linux_x86_64|fc591b4b283ceddb81116a8dd5c0e70d4f1a7dd291521c4debe0cd588c7fd74c|13660591",
+    ]
+
+    skip = SkipOption("check")
+    args = ArgsListOption(example="--python-version 3.12")
+
+    output_format = StrOption(
+        default=None,
+        help=help_text(
+            """
+            Override Pyrefly's error output format: one of `min-text`, `full-text`, `json`,
+            `github` (GitHub Actions annotations), `junit-xml`, or `omit-errors`. Defaults to
+            Pyrefly's own default.
+            """
+        ),
+    )
+
+    min_severity = StrOption(
+        default=None,
+        help=help_text(
+            """
+            Only display errors at or above this severity: one of `ignore`, `info`, `warn`, or
+            `error`.
+            """
+        ),
+    )
+
+    only = StrListOption(
+        default=[],
+        help=help_text(
+            """
+            Only report these Pyrefly error kinds (e.g. `bad-assignment`, `missing-attribute`),
+            filtering out all others. Useful for triaging one category at a time.
+            """
+        ),
+    )
+
+    extra_type_stubs = StrListOption(
+        advanced=True,
+        default=[],
+        help=help_text(
+            """
+            Extra type-stub requirements to make available to Pyrefly without adding them as
+            runtime dependencies of your code, e.g.
+            `["types-requests", "sqlalchemy2-stubs==0.0.2a38"]`.
+
+            They are resolved and merged into the third-party environment Pyrefly inspects. Pin
+            versions in the requirement strings for reproducible results, since they are resolved
+            directly rather than from a lockfile.
+            """
+        ),
+    )
+
+    config = FileOption(
+        default=None,
+        advanced=True,
+        help=help_text(
+            """
+            Path to a Pyrefly config file (a `pyrefly.toml`, or a `pyproject.toml` with a
+            `[tool.pyrefly]` table).
+
+            Setting this option disables config discovery; use it only when the config lives in a
+            non-standard location.
+            """
+        ),
+    )
+    config_discovery = BoolOption(
+        default=True,
+        advanced=True,
+        help=help_text(
+            """
+            If true, Pants will include any relevant config files during runs (`pyrefly.toml` and
+            `pyproject.toml` files with a `[tool.pyrefly]` table).
+
+            Use `[pyrefly].config` instead if your config is in a non-standard location.
+            """
+        ),
+    )
+
+    # Deliberately a StrOption, not a FileOption: the path need not exist yet (it is created by
+    # `pants pyrefly-update-baseline`), and FileOption validates existence at option-parse time.
+    baseline = StrOption(
+        default=None,
+        help=help_text(
+            """
+            Path to a Pyrefly baseline JSON file. When set, `pants check` reports only type errors
+            introduced *after* the baseline was taken — handy for adopting Pyrefly on code that
+            already has errors. Create or refresh it with `pants pyrefly-update-baseline`.
+            """
+        ),
+    )
+
+    _interpreter_constraints = StrListOption(
+        advanced=True,
+        default=["CPython>=3.9,<3.15"],
+        help="Fallback interpreter constraints to use when a target has none of its own.",
+    )
+
+    @property
+    def interpreter_constraints(self) -> InterpreterConstraints:
+        return InterpreterConstraints(self._interpreter_constraints)
+
+    def generate_exe(self, plat: Platform) -> str:
+        # Every release archive unpacks to a single `pyrefly` binary at the root.
+        return "./pyrefly"
+
+    def config_request(self) -> ConfigFilesRequest:
+        return ConfigFilesRequest(
+            specified=self.config,
+            specified_option_name=f"[{self.options_scope}].config",
+            discovery=self.config_discovery,
+            check_existence=["pyrefly.toml"],
+            check_content={"pyproject.toml": b"[tool.pyrefly"},
+        )
+
+
+def rules() -> Iterable[Rule | UnionRule]:
+    return (
+        *collect_rules(),
+        UnionRule(ExportableTool, Pyrefly),
+    )

pants_pyrefly-0.1.0.dist-info/METADATA

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: pants-pyrefly
+Version: 0.1.0
+Summary: A Pants plugin that runs the Pyrefly type checker in the `check` goal.
+License: Apache-2.0
+Keywords: pants,pantsbuild,pants-plugin,pyrefly,typecheck
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: keywords
+Dynamic: license
+Dynamic: requires-python
+Dynamic: summary
+
+# pants-pyrefly
+
+A [Pants](https://www.pantsbuild.org/) plugin that runs [Pyrefly](https://pyrefly.org/) —
+Meta's fast, Rust-based Python type checker — as part of the Pants `check` goal.
+
+Pants downloads the official prebuilt Pyrefly binary (pinned by SHA256) and runs it hermetically
+in a sandbox, wiring up your first-party source roots and the resolved third-party dependencies so
+that imports resolve correctly.
+
+## Requirements
+
+- **Pants 2.27–2.32.** A single codebase supports both the legacy (`Get`/`MultiGet`-era) and modern
+  (call-by-name) rules APIs via a small version-conditional import; verified on 2.27 and 2.32.
+- The **published wheel** is pure-Python — `Requires-Python: >=3.12`, with **no `pantsbuild.pants`
+  dependency** (Pants provides itself at runtime) — so it installs into any Pants whose runtime is
+  CPython 3.12+ (e.g. 2.32 → CPython 3.14). **Pants 2.27** runs on CPython 3.11, below the floor —
+  install **from source** there (see [Installation](#installation)); the plugin code still supports it.
+
+## Installation
+
+Add the plugin and enable its backend in `pants.toml`:
+
+```toml
+[GLOBAL]
+plugins = ["pants-pyrefly==0.1.0"]
+backend_packages.add = [
+    "pants.backend.python",
+    "pants_pyrefly",
+]
+```
+
+### From source (in-repo)
+
+Prefer to vendor the plugin — for rapid iteration, to pin to an exact source state, or to run on
+**Pants 2.27** (its CPython 3.11 runtime is below the published wheel's floor)? Consume it the way
+in-repo plugins are normally loaded: copy `pants-plugins/pants_pyrefly/` into your repo and:
+
+```toml
+[GLOBAL]
+pythonpath = ["%(buildroot)s/pants-plugins"]
+backend_packages.add = ["pants.backend.python", "pants_pyrefly"]
+```
+
+If you keep plugin code in a dedicated `pants-plugins` resolve, add it there and run
+`pants generate-lockfiles`.
+
+## Usage
+
+```bash
+pants check ::                 # type-check everything
+pants check path/to/dir::      # type-check a subtree
+```
+
+## Configuration
+
+`[pyrefly]` subsystem options:
+
+| Option | Env / flag | Description |
+| --- | --- | --- |
+| `skip` | `--pyrefly-skip` / `PANTS_PYREFLY_SKIP` | Don't run Pyrefly during `check`. |
+| `args` | `--pyrefly-args` | Extra args passed to Pyrefly, e.g. `--pyrefly-args='--python-version 3.12'`. |
+| `extra_type_stubs` | `--pyrefly-extra-type-stubs` | Stub-only packages to add to the type-check environment without making them runtime deps, e.g. `types-requests`, `sqlalchemy2-stubs==0.0.2a38`. Resolved directly, so pin versions for reproducibility. |
+| `output_format` | `--pyrefly-output-format` | Override Pyrefly's output format: `min-text`, `full-text`, `json`, `github`, `junit-xml`, `omit-errors`. |
+| `min_severity` | `--pyrefly-min-severity` | Only show errors at/above this severity (`ignore`/`info`/`warn`/`error`). |
+| `only` | `--pyrefly-only` | Only report these error kinds (e.g. `bad-assignment`); handy for triage. |
+| `config` | `--pyrefly-config` | Path to a `pyrefly.toml` / `pyproject.toml` (disables discovery). |
+| `config_discovery` | `--[no-]pyrefly-config-discovery` | Auto-discover `pyrefly.toml` / `[tool.pyrefly]`. |
+| `baseline` | `--pyrefly-baseline` | Path to a Pyrefly baseline JSON; `check` then reports only errors *new* since the baseline. Generate it with `pants pyrefly-update-baseline`. |
+| `version` / `known_versions` / `url_template` | (advanced) | Pin or override the downloaded Pyrefly binary. |
+
+Opt a target out of Pyrefly:
+
+```python
+python_sources(skip_pyrefly=True)
+```
+
+## Incremental adoption (baseline)
+
+Adopting Pyrefly on a codebase that already has type errors? Record them in a baseline so `check`
+only fails on *new* errors:
+
+```bash
+pants pyrefly-update-baseline ::   # writes the file named by [pyrefly].baseline
+pants check ::                     # now reports only errors introduced since the baseline
+```
+
+Configure the path (and commit the baseline file):
+
+```toml
+[pyrefly]
+baseline = "build-support/pyrefly-baseline.json"
+```
+
+Re-run `pants pyrefly-update-baseline` after fixing errors, or to refresh it. Baseline matching is
+Pyrefly's own (lenient by design, so it survives code churn).
+
+## Editor / IDE (LSP)
+
+Pyrefly ships an LSP server, but in a Pants repo your editor doesn't know the source roots. Generate
+a `pyrefly.toml` with them:
+
+```bash
+pants pyrefly-lsp-config        # writes search-path (= your source roots) + python-version
+```
+
+For third-party imports, point your editor's interpreter at a venv (e.g.
+`pants export --resolve=python-default`). If your Pyrefly config lives in `pyproject.toml`
+`[tool.pyrefly]`, the goal prints the keys to add instead of writing a shadowing `pyrefly.toml`.
+
+## Type coverage
+
+Track typing progress — useful as a migration ratchet:
+
+```bash
+pants pyrefly-coverage ::                                    # prints overall % typed
+pants pyrefly-coverage --pyrefly-coverage-fail-under=80 ::   # also fails if below 80%
+```
+
+## How import resolution works
+
+- **First-party code:** every source root is passed to Pyrefly via `--search-path` (the analogue of
+  `MYPYPATH` / `sys.path`).
+- **Third-party deps:** Pants materializes the target's resolved requirements into a venv and points
+  Pyrefly's `--python-interpreter-path` at it, so Pyrefly discovers `site-packages` and the target
+  Python version exactly as `import` would at runtime.
+
+## Pants compatibility
+
+| Plugin version | Pants | Pyrefly (default) |
+| --- | --- | --- |
+| `0.1.0` | `2.27`–`2.32` | `1.1.1` |
+
+The plugin supports both the legacy (`Get`/`MultiGet`) and modern (call-by-name) rules APIs through
+a small version-conditional import (the rules API changed at Pants 2.30, and again removed `Get`
+by 2.32). Verified on 2.27 and 2.32; in-between versions use the same modern API.
+
+## Development
+
+This repo dogfoods its own tooling: `ruff` (lint + format) and Pyrefly itself (`check`) run on the
+plugin's sources.
+
+```bash
+pants generate-lockfiles          # pants-plugins + python-default resolves
+pants fmt lint ::                 # ruff format + check
+pants check ::                    # Pyrefly type-checks the plugin (dogfood) + testprojects/
+pants test ::                     # run the integration tests
+pants package pants-plugins/pants_pyrefly:dist   # build the wheel + sdist into dist/
+```
+
+## Releasing
+
+Push a `vX.Y.Z` tag. The [release workflow](.github/workflows/release.yml) builds the wheel and
+publishes it to PyPI using [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC,
+no API tokens). Configure a PyPI trusted publisher for this repo + the `release.yml` workflow first.
+
+## License
+
+[Apache-2.0](LICENSE).

pants_pyrefly-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+pants_pyrefly/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pants_pyrefly/goals.py,sha256=7dsPU6ZO0uaLMVINRqHwJBeJSFWcTiRok1YRDWhWW7c,11275
+pants_pyrefly/register.py,sha256=FQW3z-YcFY9j5L3Eja3fZoRc2JgxOOamK4VMJOrdcXo,657
+pants_pyrefly/rules.py,sha256=Yf0CnEiLpLOwxoirzj0I2rZ5DNs2y3ZrCpm-H1BZ9IQ,14226
+pants_pyrefly/skip_field.py,sha256=vk0vZvJa4HZNqiC41iOKP25ECl1GkBuDe_Z_fenBV88,1068
+pants_pyrefly/subsystems.py,sha256=OqINGovLcV-g2AbFm6vHdxrpcJLR27v6UVeJjqpJ4q0,6110
+pants_pyrefly-0.1.0.dist-info/METADATA,sha256=4E7OdiETFoXzVaeWLCENnc4PXhNduPjmST3MwkE5s80,7379
+pants_pyrefly-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pants_pyrefly-0.1.0.dist-info/entry_points.txt,sha256=zsmc2XTk2lGkWilIEcw16FCxV3ziKw4-pc7MNbadG6Q,57
+pants_pyrefly-0.1.0.dist-info/namespace_packages.txt,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+pants_pyrefly-0.1.0.dist-info/top_level.txt,sha256=3ye01bqySdEJIjGqezAFXmKfg1G4niqb30BKZNC1M2Q,14
+pants_pyrefly-0.1.0.dist-info/RECORD,,

pants_pyrefly-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pants_pyrefly-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pantsbuild.plugin]
+rules = pants_pyrefly.register:rules

pants_pyrefly-0.1.0.dist-info/namespace_packages.txt

@@ -0,0 +1 @@
+

pants_pyrefly-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pants_pyrefly