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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pants-pyrefly
3
- Version: 0.2.0
3
+ Version: 0.4.0
4
4
  Summary: A Pants plugin that runs the Pyrefly type checker in the `check` goal.
5
5
  License: Apache-2.0
6
6
  Keywords: pants,pantsbuild,pants-plugin,pyrefly,typecheck
@@ -48,7 +48,7 @@ Add the plugin and enable its backend in `pants.toml`:
48
48
 
49
49
  ```toml
50
50
  [GLOBAL]
51
- plugins = ["pants-pyrefly==0.2.0"]
51
+ plugins = ["pants-pyrefly==0.3.0"]
52
52
  backend_packages.add = [
53
53
  "pants.backend.python",
54
54
  "pants_pyrefly",
@@ -69,6 +69,20 @@ backend_packages.add = ["pants.backend.python", "pants_pyrefly"]
69
69
  If you keep plugin code in a dedicated `pants-plugins` resolve, add it there and run
70
70
  `pants generate-lockfiles`.
71
71
 
72
+ ## Getting started
73
+
74
+ Bootstrap a Pyrefly config for the repo (wraps `pyrefly init`). If you already have a MyPy or
75
+ Pyright configuration, it is migrated into the new `pyrefly.toml`:
76
+
77
+ ```bash
78
+ pants pyrefly-init # create pyrefly.toml (auto-migrates mypy/pyright)
79
+ pants pyrefly-init --pyrefly-init-migrate-from=mypy # force migrating from a MyPy config
80
+ ```
81
+
82
+ It refuses to overwrite an existing `pyrefly.toml` (or a `[tool.pyrefly]` table in
83
+ `pyproject.toml`) — remove it first to regenerate. Then run `pants pyrefly-lsp-config` (see
84
+ [Editor / IDE](#editor--ide-lsp)) so your editor resolves first-party imports the way Pants does.
85
+
72
86
  ## Usage
73
87
 
74
88
  ```bash
@@ -91,6 +105,7 @@ pants check path/to/dir:: # type-check a subtree
91
105
  | `config` | `--pyrefly-config` | Path to a `pyrefly.toml` / `pyproject.toml` (disables discovery). |
92
106
  | `config_discovery` | `--[no-]pyrefly-config-discovery` | Auto-discover `pyrefly.toml` / `[tool.pyrefly]`. |
93
107
  | `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`. |
108
+ | `exclude_source_roots` | `--pyrefly-exclude-source-roots` (advanced) | Source roots to omit from `--search-path`. Rarely needed — nested roots are deduped automatically (see below); use this only to force-drop a root the automatic logic keeps. |
94
109
  | `version` / `known_versions` / `url_template` | (advanced) | Pin or override the downloaded Pyrefly binary. |
95
110
 
96
111
  Opt a target out of Pyrefly:
@@ -154,16 +169,38 @@ pants pyrefly-coverage --pyrefly-coverage-fail-under=80 :: # also fails if bel
154
169
 
155
170
  ## How import resolution works
156
171
 
157
- - **First-party code:** every source root is passed to Pyrefly via `--search-path` (the analogue of
158
- `MYPYPATH` / `sys.path`).
172
+ - **First-party code:** your source roots are passed to Pyrefly via `--search-path` (the analogue of
173
+ `MYPYPATH` / `sys.path`). When source roots nest — e.g. `[source] root_patterns` lists both `src`
174
+ and `src/python` — the plugin emits only each file's *nearest* root, dropping a redundant ancestor.
175
+ Otherwise a module under `src/python` would be reachable under two names (`pkg.mod` and
176
+ `python.pkg.mod`), which Pyrefly flags as spurious duplicate-module errors. If first-party code
177
+ genuinely lives directly under both an ancestor and a nested root, the plugin keeps both and warns;
178
+ use `[pyrefly].exclude_source_roots` to force-drop one.
159
179
  - **Third-party deps:** Pants materializes the target's resolved requirements into a venv and points
160
180
  Pyrefly's `--python-interpreter-path` at it, so Pyrefly discovers `site-packages` and the target
161
181
  Python version exactly as `import` would at runtime.
162
182
 
183
+ ## Diagnostics
184
+
185
+ When Pyrefly resolves imports or the interpreter differently than you expect, dump the effective
186
+ configuration Pants assembles — the first-party `search-path`s, the interpreter used for third-party
187
+ resolution, and the config file in effect:
188
+
189
+ ```bash
190
+ pants pyrefly-dump-config :: # whole repo
191
+ pants pyrefly-dump-config src/project:: # a subtree
192
+ ```
193
+
194
+ This runs Pyrefly's `dump-config` subcommand with exactly the arguments Pants passes to `check`, so
195
+ what you see is what `pants check` sees. It does not type-check. When targets span multiple resolves
196
+ or interpreter constraints, each partition's config is printed under its own heading.
197
+
163
198
  ## Pants compatibility
164
199
 
165
200
  | Plugin version | Pants | Pyrefly (default) |
166
201
  | --- | --- | --- |
202
+ | `0.4.0` | `2.27`–`2.32` | `1.1.1` |
203
+ | `0.3.0` | `2.27`–`2.32` | `1.1.1` |
167
204
  | `0.2.0` | `2.27`–`2.32` | `1.1.1` |
168
205
  | `0.1.0` | `2.27`–`2.32` | `1.1.1` |
169
206
 
@@ -184,6 +221,20 @@ pants test :: # run the integration tests
184
221
  pants package pants-plugins/pants_pyrefly:dist # build the wheel + sdist into dist/
185
222
  ```
186
223
 
224
+ ### Bumping the pinned Pyrefly version
225
+
226
+ The four `default_known_versions` pins in `subsystems.py` (`<version>|<platform>|<sha256>|<size>`)
227
+ are generated, not hand-edited. To move to a new Pyrefly release:
228
+
229
+ ```bash
230
+ python3 build-support/bin/generate_known_versions.py --version <new> --write
231
+ ```
232
+
233
+ It reads the URL template and platform mapping straight from `subsystems.py`, fetches each asset's
234
+ published `.sha256` sidecar and size from the GitHub release, and rewrites `default_version` + the
235
+ pins. CI runs the same script with `--check` and fails if the committed pins drift from what the
236
+ release actually publishes. (Set `GITHUB_TOKEN` to avoid GitHub API rate limits.)
237
+
187
238
  ## Releasing
188
239
 
189
240
  Push a `vX.Y.Z` tag. The [release workflow](.github/workflows/release.yml) builds the wheel and
@@ -5,6 +5,7 @@ from __future__ import annotations
5
5
 
6
6
  import json
7
7
  import logging
8
+ import os
8
9
  from collections.abc import Iterable
9
10
 
10
11
  import toml # pants: no-infer-dep (provided by the Pants runtime)
@@ -13,6 +14,7 @@ from pants_pyrefly.rules import (
13
14
  _BASELINE_OUTPUT,
14
15
  PyreflyFieldSet,
15
16
  PyreflyRequest,
17
+ _dedupe_search_path_roots,
16
18
  _setup_pyrefly_process,
17
19
  pyrefly_determine_partitions,
18
20
  )
@@ -42,12 +44,14 @@ from pants.engine.intrinsics import (
42
44
  merge_digests,
43
45
  path_globs_to_digest,
44
46
  )
47
+ from pants.core.util_rules.external_tool import download_external_tool
45
48
  from pants.engine.platform import Platform
46
- from pants.engine.process import ProcessCacheScope
49
+ from pants.engine.process import Process, ProcessCacheScope
47
50
  from pants.engine.rules import Rule, collect_rules, concurrently, goal_rule, implicitly
48
51
  from pants.engine.target import AllTargets, Targets
49
52
  from pants.engine.unions import UnionRule
50
- from pants.option.option_types import BoolOption, FloatOption
53
+ from pants.option.option_types import BoolOption, FloatOption, StrOption
54
+ from pants.util.logging import LogLevel
51
55
  from pants.util.strutil import softwrap
52
56
 
53
57
  logger = logging.getLogger(__name__)
@@ -164,6 +168,7 @@ class PyreflyLspConfig(Goal):
164
168
  @goal_rule
165
169
  async def pyrefly_lsp_config(
166
170
  all_targets: AllTargets,
171
+ pyrefly: Pyrefly,
167
172
  python_setup: PythonSetup,
168
173
  workspace: Workspace,
169
174
  ) -> PyreflyLspConfig:
@@ -177,7 +182,14 @@ async def pyrefly_lsp_config(
177
182
  python_setup.interpreter_constraints
178
183
  ).minimum_python_version(python_setup.interpreter_versions_universe)
179
184
 
180
- settings: dict = {"search-path": sorted(sources.source_roots)}
185
+ # Match `check`'s search path: dedupe nested source roots so the LSP resolves imports the same
186
+ # way and doesn't see modules under two names.
187
+ search_path = _dedupe_search_path_roots(
188
+ sources.source_roots,
189
+ sources.source_files.snapshot.files,
190
+ pyrefly.exclude_source_roots,
191
+ )
192
+ settings: dict = {"search-path": list(search_path)}
181
193
  if python_version:
182
194
  settings["python-version"] = python_version
183
195
 
@@ -406,5 +418,204 @@ async def pyrefly_suppress(
406
418
  return PyreflySuppress(exit_code=0)
407
419
 
408
420
 
421
+ # ---
422
+ # `pyrefly-init`
423
+ # ---
424
+
425
+ _MIGRATE_FROM_CHOICES = ("auto", "mypy", "pyright")
426
+
427
+
428
+ class PyreflyInitSubsystem(GoalSubsystem):
429
+ name = "pyrefly-init"
430
+ help = softwrap(
431
+ """
432
+ Bootstrap a Pyrefly config for this repo by running `pyrefly init`. Writes a `pyrefly.toml`
433
+ in the build root, migrating an existing MyPy or Pyright configuration when one is found.
434
+ Run once when adopting Pyrefly. After it writes the config, run `pants pyrefly-lsp-config`
435
+ to add Pants's source roots so the editor/LSP resolves first-party imports.
436
+ """
437
+ )
438
+
439
+ migrate_from = StrOption(
440
+ default=None,
441
+ help=softwrap(
442
+ """
443
+ Which existing type-checker config to migrate from: `auto` (try MyPy, then Pyright),
444
+ `mypy`, or `pyright`. When unset, Pyrefly's own default (`auto`) is used.
445
+ """
446
+ ),
447
+ )
448
+
449
+
450
+ class PyreflyInit(Goal):
451
+ subsystem_cls = PyreflyInitSubsystem
452
+ environment_behavior = Goal.EnvironmentBehavior.LOCAL_ONLY
453
+
454
+
455
+ @goal_rule
456
+ async def pyrefly_init(
457
+ init_subsystem: PyreflyInitSubsystem,
458
+ pyrefly: Pyrefly,
459
+ workspace: Workspace,
460
+ platform: Platform,
461
+ ) -> PyreflyInit:
462
+ if (
463
+ init_subsystem.migrate_from is not None
464
+ and init_subsystem.migrate_from not in _MIGRATE_FROM_CHOICES
465
+ ):
466
+ logger.error(
467
+ f"`--pyrefly-init-migrate-from` must be one of {', '.join(_MIGRATE_FROM_CHOICES)}; "
468
+ f"got `{init_subsystem.migrate_from}`."
469
+ )
470
+ return PyreflyInit(exit_code=1)
471
+
472
+ # `pyrefly init` reads any existing type-checker config from the working directory; materialize
473
+ # the candidates into the sandbox (no source files are needed — init does not type-check).
474
+ downloaded_pyrefly, config_digest = await concurrently(
475
+ download_external_tool(pyrefly.get_request(platform)),
476
+ path_globs_to_digest(
477
+ PathGlobs(
478
+ ["pyproject.toml", "mypy.ini", "setup.cfg", "pyrefly.toml"],
479
+ glob_match_error_behavior=GlobMatchErrorBehavior.ignore,
480
+ )
481
+ ),
482
+ )
483
+ input_files = {fc.path: fc.content for fc in await get_digest_contents(config_digest)}
484
+
485
+ # `pyrefly init` refuses to overwrite an existing config; surface that as a clear message
486
+ # rather than a bare nonzero exit. The `b"[tool.pyrefly"` sentinel matches `config_request()`.
487
+ already_configured = "pyrefly.toml" in input_files or (
488
+ b"[tool.pyrefly" in input_files.get("pyproject.toml", b"")
489
+ )
490
+ if already_configured:
491
+ logger.error(
492
+ softwrap(
493
+ """
494
+ A Pyrefly config already exists (`pyrefly.toml`, or `[tool.pyrefly]` in
495
+ `pyproject.toml`). Remove it and re-run `pants pyrefly-init` to regenerate.
496
+ """
497
+ )
498
+ )
499
+ return PyreflyInit(exit_code=1)
500
+
501
+ tool_key = "__pyrefly_tool"
502
+ exe_path = os.path.normpath(os.path.join(tool_key, downloaded_pyrefly.exe))
503
+ argv = [exe_path, "init", "--non-interactive"]
504
+ if init_subsystem.migrate_from is not None:
505
+ argv += ["--migrate-from", init_subsystem.migrate_from]
506
+ argv.append(".")
507
+
508
+ result = await execute_process(
509
+ Process(
510
+ argv=tuple(argv),
511
+ input_digest=config_digest,
512
+ immutable_input_digests={tool_key: downloaded_pyrefly.digest},
513
+ # Capture both possible targets; a nonexistent output file is simply omitted, so this
514
+ # grabs whichever file `init` writes without us needing to predict it.
515
+ output_files=("pyrefly.toml", "pyproject.toml"),
516
+ description="Bootstrap a Pyrefly config (`pyrefly init`).",
517
+ level=LogLevel.DEBUG,
518
+ cache_scope=ProcessCacheScope.PER_SESSION,
519
+ ),
520
+ **implicitly(),
521
+ )
522
+ if result.exit_code != 0:
523
+ logger.error(
524
+ f"`pyrefly init` failed (exit {result.exit_code}):\n"
525
+ f"{result.stderr.decode(errors='replace')}"
526
+ )
527
+ return PyreflyInit(exit_code=result.exit_code)
528
+
529
+ # Write back only the files `init` actually created or changed (it also captures an untouched
530
+ # pyproject.toml as a maybe-target — don't rewrite it needlessly).
531
+ changed = [
532
+ fc
533
+ for fc in await get_digest_contents(result.output_digest)
534
+ if input_files.get(fc.path) != fc.content
535
+ ]
536
+ if not changed:
537
+ logger.warning("`pyrefly init` produced no config changes.")
538
+ return PyreflyInit(exit_code=0)
539
+
540
+ output_digest = await create_digest(CreateDigest(changed))
541
+ workspace.write_digest(output_digest)
542
+ logger.info(f"Wrote Pyrefly config: {', '.join(sorted(fc.path for fc in changed))}.")
543
+ return PyreflyInit(exit_code=0)
544
+
545
+
546
+ # ---
547
+ # `pyrefly-dump-config`
548
+ # ---
549
+
550
+
551
+ class PyreflyDumpConfigSubsystem(GoalSubsystem):
552
+ name = "pyrefly-dump-config"
553
+ help = softwrap(
554
+ """
555
+ Print the effective Pyrefly configuration Pants assembles for the targeted sources — the
556
+ first-party `search-path`s, the interpreter Pyrefly resolves third-party imports from, and
557
+ the config file in effect — by running Pyrefly's `dump-config` subcommand. Diagnostic only;
558
+ it does not type-check. Use it to debug import or interpreter resolution.
559
+ """
560
+ )
561
+
562
+
563
+ class PyreflyDumpConfig(Goal):
564
+ subsystem_cls = PyreflyDumpConfigSubsystem
565
+ environment_behavior = Goal.EnvironmentBehavior.LOCAL_ONLY
566
+
567
+
568
+ @goal_rule
569
+ async def pyrefly_dump_config(
570
+ targets: Targets,
571
+ pyrefly: Pyrefly,
572
+ console: Console,
573
+ platform: Platform,
574
+ python_setup: PythonSetup,
575
+ ) -> PyreflyDumpConfig:
576
+ field_sets = tuple(
577
+ PyreflyFieldSet.create(tgt)
578
+ for tgt in targets
579
+ if PyreflyFieldSet.is_applicable(tgt) and not PyreflyFieldSet.opt_out(tgt)
580
+ )
581
+ if not field_sets:
582
+ logger.warning("No Pyrefly-applicable targets in scope.")
583
+ return PyreflyDumpConfig(exit_code=0)
584
+
585
+ partitions = list(
586
+ await pyrefly_determine_partitions(PyreflyRequest(field_sets), **implicitly())
587
+ )
588
+ processes = await concurrently(
589
+ _setup_pyrefly_process(
590
+ partition,
591
+ pyrefly,
592
+ platform,
593
+ python_setup,
594
+ # `dump-config` reports the config it would apply to the given files, mirroring what
595
+ # `check` sees; the argfile of files is passed just as it is for `check`.
596
+ subcommand=("dump-config",),
597
+ cache_scope=ProcessCacheScope.PER_SESSION,
598
+ )
599
+ for partition in partitions
600
+ )
601
+ results = await concurrently(execute_process(process, **implicitly()) for process in processes)
602
+
603
+ label_partitions = len(partitions) > 1
604
+ exit_code = 0
605
+ for partition, result in zip(partitions, results):
606
+ if result.exit_code != 0:
607
+ # `dump-config` is expected to exit 0; a nonzero code is a Pyrefly tool failure.
608
+ logger.error(
609
+ f"Pyrefly `dump-config` failed (exit {result.exit_code}) on partition "
610
+ f"({partition.description()}):\n{result.stderr.decode(errors='replace')}"
611
+ )
612
+ exit_code = result.exit_code
613
+ continue
614
+ if label_partitions:
615
+ console.print_stdout(f"# {partition.description()}")
616
+ console.print_stdout(result.stdout.decode(errors="replace").rstrip())
617
+ return PyreflyDumpConfig(exit_code=exit_code)
618
+
619
+
409
620
  def rules() -> Iterable[Rule | UnionRule]:
410
621
  return (*collect_rules(),)
@@ -141,6 +141,70 @@ async def pyrefly_determine_partitions(
141
141
  _BASELINE_OUTPUT = "__pyrefly_baseline_out.json"
142
142
 
143
143
 
144
+ def _root_covers(root: str, dir_path: str) -> bool:
145
+ """Whether `root` is `dir_path` or an ancestor of it, matching on path-segment boundaries."""
146
+ if root in (".", ""):
147
+ return True
148
+ return dir_path == root or dir_path.startswith(root + "/")
149
+
150
+
151
+ def _dedupe_search_path_roots(
152
+ source_roots: Iterable[str],
153
+ source_files: Iterable[str],
154
+ exclude: Iterable[str] = (),
155
+ ) -> tuple[str, ...]:
156
+ """Reduce Pants' source roots to the minimal set to hand Pyrefly as `--search-path`.
157
+
158
+ Pants aggregates one source root per *target* (its BUILD-file directory), so a repo whose
159
+ `[source] root_patterns` nests roots — e.g. both `src` and `src/python` — can surface an
160
+ ancestor root (`src`) alongside a descendant (`src/python`). Emitting both makes every module
161
+ under `src/python` reachable twice — as `pkg.mod` via `src/python` and as `python.pkg.mod` via
162
+ `src` — which Pyrefly treats as two distinct types, producing spurious "not assignable to
163
+ itself" errors.
164
+
165
+ Mirror Pants' own one-root-per-file model: keep only the roots that are the nearest
166
+ (longest-matching) root of an actual source file. An ancestor root that no file resolves to is
167
+ dropped; one that a file genuinely needs is kept. If a kept root still shadows a nested kept
168
+ root (a real layout collision — first-party code lives directly under the ancestor as well as
169
+ under the descendant), warn rather than silently hide code; `[pyrefly].exclude_source_roots`
170
+ can force-drop a root in that case.
171
+ """
172
+ excluded = set(exclude)
173
+ candidates = sorted({root for root in source_roots if root not in excluded})
174
+
175
+ needed: set[str] = set()
176
+ for source_file in source_files:
177
+ dir_path = os.path.dirname(source_file)
178
+ nearest: str | None = None
179
+ for root in candidates:
180
+ if _root_covers(root, dir_path) and (nearest is None or len(root) > len(nearest)):
181
+ nearest = root
182
+ if nearest is not None:
183
+ needed.add(nearest)
184
+
185
+ emitted = sorted(needed)
186
+
187
+ # Surface any remaining ancestor/descendant shadowing (a genuine layout collision we cannot
188
+ # resolve without hiding code).
189
+ for root in emitted:
190
+ shadowed = [other for other in emitted if other != root and _root_covers(root, other)]
191
+ if shadowed:
192
+ logger.warning(
193
+ softwrap(
194
+ f"""
195
+ Pyrefly source root `{root}` is an ancestor of
196
+ {", ".join(f"`{s}`" for s in shadowed)}; modules under the nested root(s) are
197
+ importable under two names and may produce spurious duplicate-module errors.
198
+ This happens when first-party code lives directly under `{root}` as well as
199
+ under a nested source root. Consolidate the layout, or drop a root with
200
+ `[pyrefly].exclude_source_roots`.
201
+ """
202
+ )
203
+ )
204
+
205
+ return tuple(emitted)
206
+
207
+
144
208
  async def _setup_pyrefly_process(
145
209
  partition: PyreflyPartition,
146
210
  pyrefly: Pyrefly,
@@ -276,8 +340,16 @@ async def _setup_pyrefly_process(
276
340
  )
277
341
 
278
342
  argv: list[str] = [exe_path, *subcommand]
279
- # First-party import roots (the analogue of MYPYPATH / sys.path).
280
- argv.extend(f"--search-path={source_root}" for source_root in transitive_sources.source_roots)
343
+ # First-party import roots (the analogue of MYPYPATH / sys.path). Dedupe nested roots so a
344
+ # module reachable under both `src` and `src/python` is not assigned two identities.
345
+ argv.extend(
346
+ f"--search-path={source_root}"
347
+ for source_root in _dedupe_search_path_roots(
348
+ transitive_sources.source_roots,
349
+ transitive_sources.source_files.snapshot.files,
350
+ pyrefly.exclude_source_roots,
351
+ )
352
+ )
281
353
  # Third-party deps + interpreter introspection.
282
354
  argv.append(f"--python-interpreter-path={requirements_venv_pex.python.argv0}")
283
355
  if python_version:
@@ -88,6 +88,22 @@ class Pyrefly(TemplatedExternalTool):
88
88
  ),
89
89
  )
90
90
 
91
+ exclude_source_roots = StrListOption(
92
+ advanced=True,
93
+ default=[],
94
+ help=help_text(
95
+ """
96
+ Pants source roots to omit from the `--search-path` Pyrefly resolves first-party
97
+ imports against.
98
+
99
+ The plugin already drops a source root that is redundant with a more specific one
100
+ (e.g. `src` when `src/python` already covers every module beneath it), so you rarely
101
+ need this. Use it to force-drop a root the automatic logic keeps — for example when
102
+ first-party code lives directly under a parent root that also shadows a nested one.
103
+ """
104
+ ),
105
+ )
106
+
91
107
  extra_type_stubs = StrListOption(
92
108
  advanced=True,
93
109
  default=[],
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pants-pyrefly
3
- Version: 0.2.0
3
+ Version: 0.4.0
4
4
  Summary: A Pants plugin that runs the Pyrefly type checker in the `check` goal.
5
5
  License: Apache-2.0
6
6
  Keywords: pants,pantsbuild,pants-plugin,pyrefly,typecheck
@@ -48,7 +48,7 @@ Add the plugin and enable its backend in `pants.toml`:
48
48
 
49
49
  ```toml
50
50
  [GLOBAL]
51
- plugins = ["pants-pyrefly==0.2.0"]
51
+ plugins = ["pants-pyrefly==0.3.0"]
52
52
  backend_packages.add = [
53
53
  "pants.backend.python",
54
54
  "pants_pyrefly",
@@ -69,6 +69,20 @@ backend_packages.add = ["pants.backend.python", "pants_pyrefly"]
69
69
  If you keep plugin code in a dedicated `pants-plugins` resolve, add it there and run
70
70
  `pants generate-lockfiles`.
71
71
 
72
+ ## Getting started
73
+
74
+ Bootstrap a Pyrefly config for the repo (wraps `pyrefly init`). If you already have a MyPy or
75
+ Pyright configuration, it is migrated into the new `pyrefly.toml`:
76
+
77
+ ```bash
78
+ pants pyrefly-init # create pyrefly.toml (auto-migrates mypy/pyright)
79
+ pants pyrefly-init --pyrefly-init-migrate-from=mypy # force migrating from a MyPy config
80
+ ```
81
+
82
+ It refuses to overwrite an existing `pyrefly.toml` (or a `[tool.pyrefly]` table in
83
+ `pyproject.toml`) — remove it first to regenerate. Then run `pants pyrefly-lsp-config` (see
84
+ [Editor / IDE](#editor--ide-lsp)) so your editor resolves first-party imports the way Pants does.
85
+
72
86
  ## Usage
73
87
 
74
88
  ```bash
@@ -91,6 +105,7 @@ pants check path/to/dir:: # type-check a subtree
91
105
  | `config` | `--pyrefly-config` | Path to a `pyrefly.toml` / `pyproject.toml` (disables discovery). |
92
106
  | `config_discovery` | `--[no-]pyrefly-config-discovery` | Auto-discover `pyrefly.toml` / `[tool.pyrefly]`. |
93
107
  | `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`. |
108
+ | `exclude_source_roots` | `--pyrefly-exclude-source-roots` (advanced) | Source roots to omit from `--search-path`. Rarely needed — nested roots are deduped automatically (see below); use this only to force-drop a root the automatic logic keeps. |
94
109
  | `version` / `known_versions` / `url_template` | (advanced) | Pin or override the downloaded Pyrefly binary. |
95
110
 
96
111
  Opt a target out of Pyrefly:
@@ -154,16 +169,38 @@ pants pyrefly-coverage --pyrefly-coverage-fail-under=80 :: # also fails if bel
154
169
 
155
170
  ## How import resolution works
156
171
 
157
- - **First-party code:** every source root is passed to Pyrefly via `--search-path` (the analogue of
158
- `MYPYPATH` / `sys.path`).
172
+ - **First-party code:** your source roots are passed to Pyrefly via `--search-path` (the analogue of
173
+ `MYPYPATH` / `sys.path`). When source roots nest — e.g. `[source] root_patterns` lists both `src`
174
+ and `src/python` — the plugin emits only each file's *nearest* root, dropping a redundant ancestor.
175
+ Otherwise a module under `src/python` would be reachable under two names (`pkg.mod` and
176
+ `python.pkg.mod`), which Pyrefly flags as spurious duplicate-module errors. If first-party code
177
+ genuinely lives directly under both an ancestor and a nested root, the plugin keeps both and warns;
178
+ use `[pyrefly].exclude_source_roots` to force-drop one.
159
179
  - **Third-party deps:** Pants materializes the target's resolved requirements into a venv and points
160
180
  Pyrefly's `--python-interpreter-path` at it, so Pyrefly discovers `site-packages` and the target
161
181
  Python version exactly as `import` would at runtime.
162
182
 
183
+ ## Diagnostics
184
+
185
+ When Pyrefly resolves imports or the interpreter differently than you expect, dump the effective
186
+ configuration Pants assembles — the first-party `search-path`s, the interpreter used for third-party
187
+ resolution, and the config file in effect:
188
+
189
+ ```bash
190
+ pants pyrefly-dump-config :: # whole repo
191
+ pants pyrefly-dump-config src/project:: # a subtree
192
+ ```
193
+
194
+ This runs Pyrefly's `dump-config` subcommand with exactly the arguments Pants passes to `check`, so
195
+ what you see is what `pants check` sees. It does not type-check. When targets span multiple resolves
196
+ or interpreter constraints, each partition's config is printed under its own heading.
197
+
163
198
  ## Pants compatibility
164
199
 
165
200
  | Plugin version | Pants | Pyrefly (default) |
166
201
  | --- | --- | --- |
202
+ | `0.4.0` | `2.27`–`2.32` | `1.1.1` |
203
+ | `0.3.0` | `2.27`–`2.32` | `1.1.1` |
167
204
  | `0.2.0` | `2.27`–`2.32` | `1.1.1` |
168
205
  | `0.1.0` | `2.27`–`2.32` | `1.1.1` |
169
206
 
@@ -184,6 +221,20 @@ pants test :: # run the integration tests
184
221
  pants package pants-plugins/pants_pyrefly:dist # build the wheel + sdist into dist/
185
222
  ```
186
223
 
224
+ ### Bumping the pinned Pyrefly version
225
+
226
+ The four `default_known_versions` pins in `subsystems.py` (`<version>|<platform>|<sha256>|<size>`)
227
+ are generated, not hand-edited. To move to a new Pyrefly release:
228
+
229
+ ```bash
230
+ python3 build-support/bin/generate_known_versions.py --version <new> --write
231
+ ```
232
+
233
+ It reads the URL template and platform mapping straight from `subsystems.py`, fetches each asset's
234
+ published `.sha256` sidecar and size from the GitHub release, and rewrites `default_version` + the
235
+ pins. CI runs the same script with `--check` and fails if the committed pins drift from what the
236
+ release actually publishes. (Set `GITHUB_TOKEN` to avoid GitHub API rate limits.)
237
+
187
238
  ## Releasing
188
239
 
189
240
  Push a `vX.Y.Z` tag. The [release workflow](.github/workflows/release.yml) builds the wheel and
@@ -57,7 +57,7 @@ Add the plugin and enable its backend in `pants.toml`:
57
57
 
58
58
  ```toml
59
59
  [GLOBAL]
60
- plugins = ["pants-pyrefly==0.2.0"]
60
+ plugins = ["pants-pyrefly==0.3.0"]
61
61
  backend_packages.add = [
62
62
  "pants.backend.python",
63
63
  "pants_pyrefly",
@@ -78,6 +78,20 @@ backend_packages.add = ["pants.backend.python", "pants_pyrefly"]
78
78
  If you keep plugin code in a dedicated `pants-plugins` resolve, add it there and run
79
79
  `pants generate-lockfiles`.
80
80
 
81
+ ## Getting started
82
+
83
+ Bootstrap a Pyrefly config for the repo (wraps `pyrefly init`). If you already have a MyPy or
84
+ Pyright configuration, it is migrated into the new `pyrefly.toml`:
85
+
86
+ ```bash
87
+ pants pyrefly-init # create pyrefly.toml (auto-migrates mypy/pyright)
88
+ pants pyrefly-init --pyrefly-init-migrate-from=mypy # force migrating from a MyPy config
89
+ ```
90
+
91
+ It refuses to overwrite an existing `pyrefly.toml` (or a `[tool.pyrefly]` table in
92
+ `pyproject.toml`) — remove it first to regenerate. Then run `pants pyrefly-lsp-config` (see
93
+ [Editor / IDE](#editor--ide-lsp)) so your editor resolves first-party imports the way Pants does.
94
+
81
95
  ## Usage
82
96
 
83
97
  ```bash
@@ -100,6 +114,7 @@ pants check path/to/dir:: # type-check a subtree
100
114
  | `config` | `--pyrefly-config` | Path to a `pyrefly.toml` / `pyproject.toml` (disables discovery). |
101
115
  | `config_discovery` | `--[no-]pyrefly-config-discovery` | Auto-discover `pyrefly.toml` / `[tool.pyrefly]`. |
102
116
  | `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`. |
117
+ | `exclude_source_roots` | `--pyrefly-exclude-source-roots` (advanced) | Source roots to omit from `--search-path`. Rarely needed — nested roots are deduped automatically (see below); use this only to force-drop a root the automatic logic keeps. |
103
118
  | `version` / `known_versions` / `url_template` | (advanced) | Pin or override the downloaded Pyrefly binary. |
104
119
 
105
120
  Opt a target out of Pyrefly:
@@ -163,16 +178,38 @@ pants pyrefly-coverage --pyrefly-coverage-fail-under=80 :: # also fails if bel
163
178
 
164
179
  ## How import resolution works
165
180
 
166
- - **First-party code:** every source root is passed to Pyrefly via `--search-path` (the analogue of
167
- `MYPYPATH` / `sys.path`).
181
+ - **First-party code:** your source roots are passed to Pyrefly via `--search-path` (the analogue of
182
+ `MYPYPATH` / `sys.path`). When source roots nest — e.g. `[source] root_patterns` lists both `src`
183
+ and `src/python` — the plugin emits only each file's *nearest* root, dropping a redundant ancestor.
184
+ Otherwise a module under `src/python` would be reachable under two names (`pkg.mod` and
185
+ `python.pkg.mod`), which Pyrefly flags as spurious duplicate-module errors. If first-party code
186
+ genuinely lives directly under both an ancestor and a nested root, the plugin keeps both and warns;
187
+ use `[pyrefly].exclude_source_roots` to force-drop one.
168
188
  - **Third-party deps:** Pants materializes the target's resolved requirements into a venv and points
169
189
  Pyrefly's `--python-interpreter-path` at it, so Pyrefly discovers `site-packages` and the target
170
190
  Python version exactly as `import` would at runtime.
171
191
 
192
+ ## Diagnostics
193
+
194
+ When Pyrefly resolves imports or the interpreter differently than you expect, dump the effective
195
+ configuration Pants assembles — the first-party `search-path`s, the interpreter used for third-party
196
+ resolution, and the config file in effect:
197
+
198
+ ```bash
199
+ pants pyrefly-dump-config :: # whole repo
200
+ pants pyrefly-dump-config src/project:: # a subtree
201
+ ```
202
+
203
+ This runs Pyrefly's `dump-config` subcommand with exactly the arguments Pants passes to `check`, so
204
+ what you see is what `pants check` sees. It does not type-check. When targets span multiple resolves
205
+ or interpreter constraints, each partition's config is printed under its own heading.
206
+
172
207
  ## Pants compatibility
173
208
 
174
209
  | Plugin version | Pants | Pyrefly (default) |
175
210
  | --- | --- | --- |
211
+ | `0.4.0` | `2.27`–`2.32` | `1.1.1` |
212
+ | `0.3.0` | `2.27`–`2.32` | `1.1.1` |
176
213
  | `0.2.0` | `2.27`–`2.32` | `1.1.1` |
177
214
  | `0.1.0` | `2.27`–`2.32` | `1.1.1` |
178
215
 
@@ -193,6 +230,20 @@ pants test :: # run the integration tests
193
230
  pants package pants-plugins/pants_pyrefly:dist # build the wheel + sdist into dist/
194
231
  ```
195
232
 
233
+ ### Bumping the pinned Pyrefly version
234
+
235
+ The four `default_known_versions` pins in `subsystems.py` (`<version>|<platform>|<sha256>|<size>`)
236
+ are generated, not hand-edited. To move to a new Pyrefly release:
237
+
238
+ ```bash
239
+ python3 build-support/bin/generate_known_versions.py --version <new> --write
240
+ ```
241
+
242
+ It reads the URL template and platform mapping straight from `subsystems.py`, fetches each asset's
243
+ published `.sha256` sidecar and size from the GitHub release, and rewrites `default_version` + the
244
+ pins. CI runs the same script with `--check` and fails if the committed pins drift from what the
245
+ release actually publishes. (Set `GITHUB_TOKEN` to avoid GitHub API rate limits.)
246
+
196
247
  ## Releasing
197
248
 
198
249
  Push a `vX.Y.Z` tag. The [release workflow](.github/workflows/release.yml) builds the wheel and
@@ -213,5 +264,5 @@ no API tokens). Configure a PyPI trusted publisher for this repo + the `release.
213
264
  'pants_pyrefly',
214
265
  ),
215
266
  'python_requires': '>=3.11',
216
- 'version': '0.2.0',
267
+ 'version': '0.4.0',
217
268
  })
File without changes
File without changes