facebook / facebook/pyrefly

Module resolution identity mismatch between installed stub package and local source code

Open
#4,425 0 comments 0 reactions 0 assignees View on GitHub
configuration
Dominant language
Rust
Stars
7k
Forks
516
PR merge metrics
No merged PRs in 30d

Description

## Description
When checking local test files against an installed stub-only package (e.g. `pandas-stubs`), Pyrefly resolves third-party types inconsistently between the two contexts. This leads to false-positive type mismatch errors where the identical underlying type is treated as two separate nominal types.

For example, when both contexts import `openpyxl.workbook.workbook.Workbook`:
* The **installed stub package** resolves it to the source implementation (`/openpyxl/workbook/workbook.py` at line 51).
* The **local test file** resolves it to Pyrefly's bundled typeshed stub (`/stubs/openpyxl/openpyxl/workbook/workbook.pyi` at line 39).

This causes `assert-type` and `bad-specialization` errors because `Workbook@39` is not recognized as the same type as `Workbook@51`.

*(Note: See pandas-dev/pandas-stubs#1801 for the original upstream issue where this was identified).*

## To Reproduce

Using the `pandas-stubs` repository:

1. Clone `pandas-stubs` and install dependencies.
2. `pyrefly_dist` is currently disabled in main. Re-enable it by uncommenting `_step.pyrefly_dist` in `scripts/test/__init__.py` under `_DIST_STEPS`.
3. Run `poe pyrefly_dist` (this command builds/installs the `pandas-stubs` wheel, hides the local source directory, and runs `pyrefly check tests`).

**Observed Error:**
```text
ERROR assert_type(ExcelWriter[Workbook], ExcelWriter[Workbook]) failed [assert-type]
--> tests/test_io.py:1360:24

ERROR `openpyxl.workbook.workbook.Workbook@39:7-15` is not assignable to upper bound `OpenDocument | xlsxwriter.workbook.Workbook | openpyxl.workbook.workbook.Workbook@51:7-15` of type variable `_WorkbookT` [bad-specialization]
--> tests/test_io.py:1360:29
```

## Expected Behavior
Pyrefly should resolve the third-party import consistently to the same path (either both to the typeshed stub or both to the site-packages source) regardless of whether the import originates from an installed package or a local test file, avoiding split-identity errors.

Contributor guide

Open the contributing guide

Research direction

Start with scripts/test/__init__.py and re-enable _step.pyrefly_dist under _DIST_STEPS, then run poe pyrefly_dist against the pandas-stubs reproduction. Trace the module-resolution paths for imports from tests/test_io.py and the installed stub package. Done means both contexts resolve openpyxl.workbook.workbook.Workbook consistently and the reported assert-type and bad-specialization errors disappear.

Written by the indexing model from the issue text.

Assessment

Tech stack
python, rust
Domain
compilers, devtools
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.