pants-pyrefly 0.1.0__tar.gz

pants_pyrefly-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+include *.py

pants_pyrefly-0.1.0/PKG-INFO

@@ -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/backend_shim.py

@@ -0,0 +1,31 @@
+
+# DO NOT EDIT THIS FILE -- AUTOGENERATED BY PANTS
+
+import errno
+import os
+import setuptools.build_meta
+
+backend = setuptools.build_meta.__legacy__
+
+dist_dir = "dist/"
+build_wheel = True
+build_sdist = True
+wheel_config_settings = {
+}
+sdist_config_settings = {
+}
+
+# Python 2.7 doesn't have the exist_ok arg on os.makedirs().
+try:
+    os.makedirs(dist_dir)
+except OSError as e:
+    if e.errno != errno.EEXIST:
+        raise
+
+wheel_path = backend.build_wheel(dist_dir, wheel_config_settings) if build_wheel else None
+sdist_path = backend.build_sdist(dist_dir, sdist_config_settings) if build_sdist else None
+
+if wheel_path:
+    print("wheel: {wheel_path}".format(wheel_path=wheel_path))
+if sdist_path:
+    print("sdist: {sdist_path}".format(sdist_path=sdist_path))

pants_pyrefly-0.1.0/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-0.1.0/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(),
+    )