pants-pyrefly 0.2.0__tar.gz → 0.3.0__tar.gz

{pants_pyrefly-0.2.0 → pants_pyrefly-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pants-pyrefly
-Version: 0.2.0
+Version: 0.3.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
@@ -48,7 +48,7 @@ Add the plugin and enable its backend in `pants.toml`:
 
 ```toml
 [GLOBAL]
-plugins = ["pants-pyrefly==0.2.0"]
+plugins = ["pants-pyrefly==0.3.0"]
 backend_packages.add = [
     "pants.backend.python",
     "pants_pyrefly",
@@ -69,6 +69,20 @@ 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`.
 
+## Getting started
+
+Bootstrap a Pyrefly config for the repo (wraps `pyrefly init`). If you already have a MyPy or
+Pyright configuration, it is migrated into the new `pyrefly.toml`:
+
+```bash
+pants pyrefly-init                              # create pyrefly.toml (auto-migrates mypy/pyright)
+pants pyrefly-init --pyrefly-init-migrate-from=mypy   # force migrating from a MyPy config
+```
+
+It refuses to overwrite an existing `pyrefly.toml` (or a `[tool.pyrefly]` table in
+`pyproject.toml`) — remove it first to regenerate. Then run `pants pyrefly-lsp-config` (see
+[Editor / IDE](#editor--ide-lsp)) so your editor resolves first-party imports the way Pants does.
+
 ## Usage
 
 ```bash
@@ -160,10 +174,26 @@ pants pyrefly-coverage --pyrefly-coverage-fail-under=80 ::   # also fails if bel
   Pyrefly's `--python-interpreter-path` at it, so Pyrefly discovers `site-packages` and the target
   Python version exactly as `import` would at runtime.
 
+## Diagnostics
+
+When Pyrefly resolves imports or the interpreter differently than you expect, dump the effective
+configuration Pants assembles — the first-party `search-path`s, the interpreter used for third-party
+resolution, and the config file in effect:
+
+```bash
+pants pyrefly-dump-config ::                    # whole repo
+pants pyrefly-dump-config src/project::         # a subtree
+```
+
+This runs Pyrefly's `dump-config` subcommand with exactly the arguments Pants passes to `check`, so
+what you see is what `pants check` sees. It does not type-check. When targets span multiple resolves
+or interpreter constraints, each partition's config is printed under its own heading.
+
 ## Pants compatibility
 
 | Plugin version | Pants | Pyrefly (default) |
 | --- | --- | --- |
+| `0.3.0` | `2.27`–`2.32` | `1.1.1` |
 | `0.2.0` | `2.27`–`2.32` | `1.1.1` |
 | `0.1.0` | `2.27`–`2.32` | `1.1.1` |
 
@@ -184,6 +214,20 @@ pants test ::                     # run the integration tests
 pants package pants-plugins/pants_pyrefly:dist   # build the wheel + sdist into dist/
 ```
 
+### Bumping the pinned Pyrefly version
+
+The four `default_known_versions` pins in `subsystems.py` (`<version>|<platform>|<sha256>|<size>`)
+are generated, not hand-edited. To move to a new Pyrefly release:
+
+```bash
+python3 build-support/bin/generate_known_versions.py --version <new> --write
+```
+
+It reads the URL template and platform mapping straight from `subsystems.py`, fetches each asset's
+published `.sha256` sidecar and size from the GitHub release, and rewrites `default_version` + the
+pins. CI runs the same script with `--check` and fails if the committed pins drift from what the
+release actually publishes. (Set `GITHUB_TOKEN` to avoid GitHub API rate limits.)
+
 ## Releasing
 
 Push a `vX.Y.Z` tag. The [release workflow](.github/workflows/release.yml) builds the wheel and

{pants_pyrefly-0.2.0 → pants_pyrefly-0.3.0}/pants_pyrefly/goals.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 
 import json
 import logging
+import os
 from collections.abc import Iterable
 
 import toml  # pants: no-infer-dep  (provided by the Pants runtime)
@@ -42,12 +43,14 @@ from pants.engine.intrinsics import (
     merge_digests,
     path_globs_to_digest,
 )
+from pants.core.util_rules.external_tool import download_external_tool
 from pants.engine.platform import Platform
-from pants.engine.process import ProcessCacheScope
+from pants.engine.process import Process, 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 BoolOption, FloatOption
+from pants.option.option_types import BoolOption, FloatOption, StrOption
+from pants.util.logging import LogLevel
 from pants.util.strutil import softwrap
 
 logger = logging.getLogger(__name__)
@@ -406,5 +409,204 @@ async def pyrefly_suppress(
     return PyreflySuppress(exit_code=0)
 
 
+# ---
+# `pyrefly-init`
+# ---
+
+_MIGRATE_FROM_CHOICES = ("auto", "mypy", "pyright")
+
+
+class PyreflyInitSubsystem(GoalSubsystem):
+    name = "pyrefly-init"
+    help = softwrap(
+        """
+        Bootstrap a Pyrefly config for this repo by running `pyrefly init`. Writes a `pyrefly.toml`
+        in the build root, migrating an existing MyPy or Pyright configuration when one is found.
+        Run once when adopting Pyrefly. After it writes the config, run `pants pyrefly-lsp-config`
+        to add Pants's source roots so the editor/LSP resolves first-party imports.
+        """
+    )
+
+    migrate_from = StrOption(
+        default=None,
+        help=softwrap(
+            """
+            Which existing type-checker config to migrate from: `auto` (try MyPy, then Pyright),
+            `mypy`, or `pyright`. When unset, Pyrefly's own default (`auto`) is used.
+            """
+        ),
+    )
+
+
+class PyreflyInit(Goal):
+    subsystem_cls = PyreflyInitSubsystem
+    environment_behavior = Goal.EnvironmentBehavior.LOCAL_ONLY
+
+
+@goal_rule
+async def pyrefly_init(
+    init_subsystem: PyreflyInitSubsystem,
+    pyrefly: Pyrefly,
+    workspace: Workspace,
+    platform: Platform,
+) -> PyreflyInit:
+    if (
+        init_subsystem.migrate_from is not None
+        and init_subsystem.migrate_from not in _MIGRATE_FROM_CHOICES
+    ):
+        logger.error(
+            f"`--pyrefly-init-migrate-from` must be one of {', '.join(_MIGRATE_FROM_CHOICES)}; "
+            f"got `{init_subsystem.migrate_from}`."
+        )
+        return PyreflyInit(exit_code=1)
+
+    # `pyrefly init` reads any existing type-checker config from the working directory; materialize
+    # the candidates into the sandbox (no source files are needed — init does not type-check).
+    downloaded_pyrefly, config_digest = await concurrently(
+        download_external_tool(pyrefly.get_request(platform)),
+        path_globs_to_digest(
+            PathGlobs(
+                ["pyproject.toml", "mypy.ini", "setup.cfg", "pyrefly.toml"],
+                glob_match_error_behavior=GlobMatchErrorBehavior.ignore,
+            )
+        ),
+    )
+    input_files = {fc.path: fc.content for fc in await get_digest_contents(config_digest)}
+
+    # `pyrefly init` refuses to overwrite an existing config; surface that as a clear message
+    # rather than a bare nonzero exit. The `b"[tool.pyrefly"` sentinel matches `config_request()`.
+    already_configured = "pyrefly.toml" in input_files or (
+        b"[tool.pyrefly" in input_files.get("pyproject.toml", b"")
+    )
+    if already_configured:
+        logger.error(
+            softwrap(
+                """
+                A Pyrefly config already exists (`pyrefly.toml`, or `[tool.pyrefly]` in
+                `pyproject.toml`). Remove it and re-run `pants pyrefly-init` to regenerate.
+                """
+            )
+        )
+        return PyreflyInit(exit_code=1)
+
+    tool_key = "__pyrefly_tool"
+    exe_path = os.path.normpath(os.path.join(tool_key, downloaded_pyrefly.exe))
+    argv = [exe_path, "init", "--non-interactive"]
+    if init_subsystem.migrate_from is not None:
+        argv += ["--migrate-from", init_subsystem.migrate_from]
+    argv.append(".")
+
+    result = await execute_process(
+        Process(
+            argv=tuple(argv),
+            input_digest=config_digest,
+            immutable_input_digests={tool_key: downloaded_pyrefly.digest},
+            # Capture both possible targets; a nonexistent output file is simply omitted, so this
+            # grabs whichever file `init` writes without us needing to predict it.
+            output_files=("pyrefly.toml", "pyproject.toml"),
+            description="Bootstrap a Pyrefly config (`pyrefly init`).",
+            level=LogLevel.DEBUG,
+            cache_scope=ProcessCacheScope.PER_SESSION,
+        ),
+        **implicitly(),
+    )
+    if result.exit_code != 0:
+        logger.error(
+            f"`pyrefly init` failed (exit {result.exit_code}):\n"
+            f"{result.stderr.decode(errors='replace')}"
+        )
+        return PyreflyInit(exit_code=result.exit_code)
+
+    # Write back only the files `init` actually created or changed (it also captures an untouched
+    # pyproject.toml as a maybe-target — don't rewrite it needlessly).
+    changed = [
+        fc
+        for fc in await get_digest_contents(result.output_digest)
+        if input_files.get(fc.path) != fc.content
+    ]
+    if not changed:
+        logger.warning("`pyrefly init` produced no config changes.")
+        return PyreflyInit(exit_code=0)
+
+    output_digest = await create_digest(CreateDigest(changed))
+    workspace.write_digest(output_digest)
+    logger.info(f"Wrote Pyrefly config: {', '.join(sorted(fc.path for fc in changed))}.")
+    return PyreflyInit(exit_code=0)
+
+
+# ---
+# `pyrefly-dump-config`
+# ---
+
+
+class PyreflyDumpConfigSubsystem(GoalSubsystem):
+    name = "pyrefly-dump-config"
+    help = softwrap(
+        """
+        Print the effective Pyrefly configuration Pants assembles for the targeted sources — the
+        first-party `search-path`s, the interpreter Pyrefly resolves third-party imports from, and
+        the config file in effect — by running Pyrefly's `dump-config` subcommand. Diagnostic only;
+        it does not type-check. Use it to debug import or interpreter resolution.
+        """
+    )
+
+
+class PyreflyDumpConfig(Goal):
+    subsystem_cls = PyreflyDumpConfigSubsystem
+    environment_behavior = Goal.EnvironmentBehavior.LOCAL_ONLY
+
+
+@goal_rule
+async def pyrefly_dump_config(
+    targets: Targets,
+    pyrefly: Pyrefly,
+    console: Console,
+    platform: Platform,
+    python_setup: PythonSetup,
+) -> PyreflyDumpConfig:
+    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 PyreflyDumpConfig(exit_code=0)
+
+    partitions = list(
+        await pyrefly_determine_partitions(PyreflyRequest(field_sets), **implicitly())
+    )
+    processes = await concurrently(
+        _setup_pyrefly_process(
+            partition,
+            pyrefly,
+            platform,
+            python_setup,
+            # `dump-config` reports the config it would apply to the given files, mirroring what
+            # `check` sees; the argfile of files is passed just as it is for `check`.
+            subcommand=("dump-config",),
+            cache_scope=ProcessCacheScope.PER_SESSION,
+        )
+        for partition in partitions
+    )
+    results = await concurrently(execute_process(process, **implicitly()) for process in processes)
+
+    label_partitions = len(partitions) > 1
+    exit_code = 0
+    for partition, result in zip(partitions, results):
+        if result.exit_code != 0:
+            # `dump-config` is expected to exit 0; a nonzero code is a Pyrefly tool failure.
+            logger.error(
+                f"Pyrefly `dump-config` failed (exit {result.exit_code}) on partition "
+                f"({partition.description()}):\n{result.stderr.decode(errors='replace')}"
+            )
+            exit_code = result.exit_code
+            continue
+        if label_partitions:
+            console.print_stdout(f"# {partition.description()}")
+        console.print_stdout(result.stdout.decode(errors="replace").rstrip())
+    return PyreflyDumpConfig(exit_code=exit_code)
+
+
 def rules() -> Iterable[Rule | UnionRule]:
     return (*collect_rules(),)

{pants_pyrefly-0.2.0 → pants_pyrefly-0.3.0}/pants_pyrefly.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pants-pyrefly
-Version: 0.2.0
+Version: 0.3.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
@@ -48,7 +48,7 @@ Add the plugin and enable its backend in `pants.toml`:
 
 ```toml
 [GLOBAL]
-plugins = ["pants-pyrefly==0.2.0"]
+plugins = ["pants-pyrefly==0.3.0"]
 backend_packages.add = [
     "pants.backend.python",
     "pants_pyrefly",
@@ -69,6 +69,20 @@ 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`.
 
+## Getting started
+
+Bootstrap a Pyrefly config for the repo (wraps `pyrefly init`). If you already have a MyPy or
+Pyright configuration, it is migrated into the new `pyrefly.toml`:
+
+```bash
+pants pyrefly-init                              # create pyrefly.toml (auto-migrates mypy/pyright)
+pants pyrefly-init --pyrefly-init-migrate-from=mypy   # force migrating from a MyPy config
+```
+
+It refuses to overwrite an existing `pyrefly.toml` (or a `[tool.pyrefly]` table in
+`pyproject.toml`) — remove it first to regenerate. Then run `pants pyrefly-lsp-config` (see
+[Editor / IDE](#editor--ide-lsp)) so your editor resolves first-party imports the way Pants does.
+
 ## Usage
 
 ```bash
@@ -160,10 +174,26 @@ pants pyrefly-coverage --pyrefly-coverage-fail-under=80 ::   # also fails if bel
   Pyrefly's `--python-interpreter-path` at it, so Pyrefly discovers `site-packages` and the target
   Python version exactly as `import` would at runtime.
 
+## Diagnostics
+
+When Pyrefly resolves imports or the interpreter differently than you expect, dump the effective
+configuration Pants assembles — the first-party `search-path`s, the interpreter used for third-party
+resolution, and the config file in effect:
+
+```bash
+pants pyrefly-dump-config ::                    # whole repo
+pants pyrefly-dump-config src/project::         # a subtree
+```
+
+This runs Pyrefly's `dump-config` subcommand with exactly the arguments Pants passes to `check`, so
+what you see is what `pants check` sees. It does not type-check. When targets span multiple resolves
+or interpreter constraints, each partition's config is printed under its own heading.
+
 ## Pants compatibility
 
 | Plugin version | Pants | Pyrefly (default) |
 | --- | --- | --- |
+| `0.3.0` | `2.27`–`2.32` | `1.1.1` |
 | `0.2.0` | `2.27`–`2.32` | `1.1.1` |
 | `0.1.0` | `2.27`–`2.32` | `1.1.1` |
 
@@ -184,6 +214,20 @@ pants test ::                     # run the integration tests
 pants package pants-plugins/pants_pyrefly:dist   # build the wheel + sdist into dist/
 ```
 
+### Bumping the pinned Pyrefly version
+
+The four `default_known_versions` pins in `subsystems.py` (`<version>|<platform>|<sha256>|<size>`)
+are generated, not hand-edited. To move to a new Pyrefly release:
+
+```bash
+python3 build-support/bin/generate_known_versions.py --version <new> --write
+```
+
+It reads the URL template and platform mapping straight from `subsystems.py`, fetches each asset's
+published `.sha256` sidecar and size from the GitHub release, and rewrites `default_version` + the
+pins. CI runs the same script with `--check` and fails if the committed pins drift from what the
+release actually publishes. (Set `GITHUB_TOKEN` to avoid GitHub API rate limits.)
+
 ## Releasing
 
 Push a `vX.Y.Z` tag. The [release workflow](.github/workflows/release.yml) builds the wheel and

{pants_pyrefly-0.2.0 → pants_pyrefly-0.3.0}/setup.py

@@ -57,7 +57,7 @@ Add the plugin and enable its backend in `pants.toml`:
 
 ```toml
 [GLOBAL]
-plugins = ["pants-pyrefly==0.2.0"]
+plugins = ["pants-pyrefly==0.3.0"]
 backend_packages.add = [
     "pants.backend.python",
     "pants_pyrefly",
@@ -78,6 +78,20 @@ 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`.
 
+## Getting started
+
+Bootstrap a Pyrefly config for the repo (wraps `pyrefly init`). If you already have a MyPy or
+Pyright configuration, it is migrated into the new `pyrefly.toml`:
+
+```bash
+pants pyrefly-init                              # create pyrefly.toml (auto-migrates mypy/pyright)
+pants pyrefly-init --pyrefly-init-migrate-from=mypy   # force migrating from a MyPy config
+```
+
+It refuses to overwrite an existing `pyrefly.toml` (or a `[tool.pyrefly]` table in
+`pyproject.toml`) — remove it first to regenerate. Then run `pants pyrefly-lsp-config` (see
+[Editor / IDE](#editor--ide-lsp)) so your editor resolves first-party imports the way Pants does.
+
 ## Usage
 
 ```bash
@@ -169,10 +183,26 @@ pants pyrefly-coverage --pyrefly-coverage-fail-under=80 ::   # also fails if bel
   Pyrefly's `--python-interpreter-path` at it, so Pyrefly discovers `site-packages` and the target
   Python version exactly as `import` would at runtime.
 
+## Diagnostics
+
+When Pyrefly resolves imports or the interpreter differently than you expect, dump the effective
+configuration Pants assembles — the first-party `search-path`s, the interpreter used for third-party
+resolution, and the config file in effect:
+
+```bash
+pants pyrefly-dump-config ::                    # whole repo
+pants pyrefly-dump-config src/project::         # a subtree
+```
+
+This runs Pyrefly's `dump-config` subcommand with exactly the arguments Pants passes to `check`, so
+what you see is what `pants check` sees. It does not type-check. When targets span multiple resolves
+or interpreter constraints, each partition's config is printed under its own heading.
+
 ## Pants compatibility
 
 | Plugin version | Pants | Pyrefly (default) |
 | --- | --- | --- |
+| `0.3.0` | `2.27`–`2.32` | `1.1.1` |
 | `0.2.0` | `2.27`–`2.32` | `1.1.1` |
 | `0.1.0` | `2.27`–`2.32` | `1.1.1` |
 
@@ -193,6 +223,20 @@ pants test ::                     # run the integration tests
 pants package pants-plugins/pants_pyrefly:dist   # build the wheel + sdist into dist/
 ```
 
+### Bumping the pinned Pyrefly version
+
+The four `default_known_versions` pins in `subsystems.py` (`<version>|<platform>|<sha256>|<size>`)
+are generated, not hand-edited. To move to a new Pyrefly release:
+
+```bash
+python3 build-support/bin/generate_known_versions.py --version <new> --write
+```
+
+It reads the URL template and platform mapping straight from `subsystems.py`, fetches each asset's
+published `.sha256` sidecar and size from the GitHub release, and rewrites `default_version` + the
+pins. CI runs the same script with `--check` and fails if the committed pins drift from what the
+release actually publishes. (Set `GITHUB_TOKEN` to avoid GitHub API rate limits.)
+
 ## Releasing
 
 Push a `vX.Y.Z` tag. The [release workflow](.github/workflows/release.yml) builds the wheel and
@@ -213,5 +257,5 @@ no API tokens). Configure a PyPI trusted publisher for this repo + the `release.
         'pants_pyrefly',
     ),
     'python_requires': '>=3.11',
-    'version': '0.2.0',
+    'version': '0.3.0',
 })