Pyrefly does not resolve installed modules against the workspace venv in cell diagnostic vdocs

[seeM]

A user ran into this issue with cell diagnostics.

Sharing a repro in case it's useful:

1. Positron with a project that has a .venv containing dependencies not installed in the system/global Python (e.g., polars).
2. System Python on PATH = Homebrew (here python@3.14), without polars.
3. Open a .qmd with a cell that does import polars.

What I see: Pyrefly flags "Cannot find module 'polars'" and appears to resolve against the global Python rather than the project .venv.
python.defaultInterpreterPath, the interpreter picker, and QUARTO_PYTHON didn't change it.
Positron's own Pyrefly resolves the .venv fine, seems specific to the cell-diagnostics path.

Downgrading to 1.132.0 fixes it.

[seeM]

Repro

1. Setup a virtual env in a project folder, and install polars:

   mkdir my-project
   cd my-project
   uv venv
   source .venv/bin/activate
   uv pip install polars

2. Open the workspace in VS Code:

   code .

3. Run the "Python: Select Interpreter" command and choose the newly configured env.

4. Create a temporary file that imports polars:

   tmpdir = `mktemp -d`
   tmpfile = $tmpdir/1.py
   echo 'import polars\n' > $tmpfile

5. Verify that the pyrefly CLI works with the temp file:

   pyrefly check $tmpfile

6. Open the temp file in the same VS Code workspace setup above.

7. Verify that there is an import resolution error on the polars word:

   Cannot find module `polars`
     Looked in these locations:
     Fallback search path (guessed from importing file with heuristics): ["/var/folders/_r/pm17dpfn7lx5mf3wtd96kw3m0000gn/T/tmp.iDydisAKG2", "/var/folders/_r/pm17dpfn7lx5mf3wtd96kw3m0000gn/T", "/var/folders/_r/pm17dpfn7lx5mf3wtd96kw3m0000gn", "/var/folders/_r", "/var/folders", "/var", "/"]
     Site package path queried from interpreter: ["/Users/seem/.local/share/uv/python/cpython-3.11.13-macos-aarch64-none/lib/python3.11/site-packages"]Pyreflymissing-import
   

Possible fixes

Configure pyrefly in the temp file's parent

Create a pyrefly.toml or pyproject.toml file in the temp file's parent that sets python-interpreter-path and search-path. Replace <path-to-workspace> as needed.

Setting python-interpreter-path fixes import of installed packages, and search-path fixes import of locally imported modules.

pyrefly.toml:

python-interpreter-path = "<path-to-workspace>/.venv/bin/python"
search-path = ["<path-to-workspace>"]

pyproject.toml:

[tool.pyrefly]
python-interpreter-path = "<path-to-workspace>/.venv/bin/python"
search-path = ["<path-to-workspace>"]

Create the vdoc in the workspace

It would be simpler to create vdocs in the workspace, with the downside that we dirty the user's workspace.

[juliasilge]

Or we could handle diagnostics in the way that notebooks do and get rid of vdoc files. 😉

[seeM]

@juliasilge haha, true! This is another good motivation for moving away from vdoc files (posit-dev/positron#12837)

[chrishklee]

I think same issue here: posit-dev/positron#14324