Feature: Add virtual workspace support

[jianyexi]

Summary

I'd like to propose adding virtual workspace support to ruff-vscode by exporting a registerUriTranslator API — the same pattern Pylance already uses.

Problem

The extension currently declares virtualWorkspaces.supported: false. This blocks Ruff from providing linting/formatting in virtual workspace environments (GitHub Repositories, Microsoft Fabric notebooks, custom FileSystemProvider workspaces).

No Python linter or formatter currently supports virtual workspaces (see microsoft/vscode-python#21459).

Proposed approach

Ruff exports registerUriTranslator(), the VFS provider owns the cache.

This is the exact pattern Pylance uses. The VFS provider extension (which already maintains a disk cache for its own purposes) registers a translator with Ruff:

const ruff = vscode.extensions.getExtension('charliermarsh.ruff');
await ruff.activate();
ruff.exports.registerUriTranslator({
  translateToDisk(uri)    { /* virtual URI → cached file:// URI */ },
  translateToVirtual(uri) { /* file:// URI → virtual URI */ },
  clearTranslationCache() { /* invalidate */ }
});

On registration, Ruff restarts its language server with LSP middleware that calls the translator.

Key point addressing the copy-all-files concern: Ruff does NOT need to copy any files itself. The VFS provider already maintains a persistent disk cache (for Pylance integration, editor operations, etc.). Ruff simply plugs into that existing cache via the translator interface. The caching is lazy — only files that are actually opened/referenced get cached by the VFS provider.

Changes needed in ruff-vscode

1. package.json — set virtualWorkspaces.supported: true
2. New src/common/uriTranslator.ts — interface definitions + registerUriTranslator export
3. src/extension.ts — activate() returns the API; on registration triggers server restart
4. src/common/server.ts — configure LSP middleware when translator is registered
5. src/common/settings.ts / utilities.ts — handle non-file:// URI schemes

Zero changes needed in the Ruff binary — the native ruff server already speaks LSP and doesn't care about URI schemes.

Context

I work on the Microsoft Fabric Data Engineering VS Code extension which uses a custom VFS. We already register a URI translator with Pylance for Python IntelliSense. Adding the same integration for Ruff would give our users linting/formatting in virtual workspaces.

Environment

• Extension version: 2026.40.0
• Ruff version: Any (native server)

[MichaReiser]

Hi @jianyexi

Did you write this issue using AI? If so, please read our AI policy (https://github.com/astral-sh/.github/blob/main/AI_POLICY.md) and update your issue accordingly.

Copying all files seems fairly expensive, especially because it isn't sufficient to only copy the current file, it requires copying the entire project. So this would certainly require more work.

See https://code.visualstudio.com/api/extension-guides/virtual-workspaces

[jianyexi]

Hi @MichaReiser, thanks for the quick review and the pointer to the AI policy.

Yes, the initial issue was drafted with AI assistance. I've rewritten the issue body to reflect my own understanding and the actual proposal more clearly.

Regarding the copy-all-files concern — you're absolutely right that copying an entire project would be expensive and impractical. The updated proposal avoids that entirely:

Ruff doesn't copy any files. Instead, Ruff exports a registerUriTranslator() API (same pattern as Pylance). The VFS provider — which already maintains a lazy disk cache for Pylance and editor operations — registers its existing translator with Ruff. Ruff just calls translateToDisk(uri) / translateToVirtual(uri) on the translator it receives. The caching strategy, invalidation, and what gets cached is entirely the VFS provider's responsibility.

In practice, only files that are actually opened by the user get cached (lazily), plus their ancestor config files (pyproject.toml, ruff.toml). No upfront project-wide copy.

I work on the Fabric Data Engineering VS Code extension and we already have this translator infrastructure working with Pylance. Happy to contribute a PR if this approach seems reasonable.

Thanks for the VS Code virtual workspaces guide link — I've reviewed it and the approach aligns with the "limited" support model described there.

[MichaReiser]

In practice, only files that are actually opened by the user get cached (lazily), plus their ancestor config files (pyproject.toml, ruff.toml). No upfront project-wide copy.

I don't know a lot about virtual workspaces, but Ruff walks the directory tree for multiple features like config discovery and Python package discovery. It's unclear to me how that would work (and how the LSP would call translateToDisk)

A PR with an extensive test plan would help better understand this feature. But it might take some time before i get to review it (and test it).

[jianyexi]

Hi @MichaReiser, I've submitted a PR with a working implementation: #1008

The approach addresses the directory walk concern — the VFS provider's initialize() method syncs config files (pyproject.toml, ruff.toml) to a local disk cache before the server starts, so filesystem walks find them naturally. The translator handles all URI translation bidirectionally.

E2E tests verify diagnostics, formatting, and auto-fix all work on virtual files. Would appreciate your review when you have time. Thanks!

[jianyexi]

Hi @MichaReiser, gentle ping on this — PR #1008 has been open for about two weeks now with the working implementation (including the initialize() config-file sync to address the directory-walk concern you raised). Whenever you have a chance, I'd really appreciate a review or any feedback on the approach. Happy to iterate on anything that doesn't fit Ruff's direction. Thanks!

[MichaReiser]

Thanks for opening the PR. Unfortunately, there are other features that I have to review first. I'm not sure when I'll get to looking into the PR (it's just not a highly requested feature). The PR also looks heavily AI generated. You may want to take a look at our Contribution guidelines, specifically the AI Policy (https://github.com/astral-sh/.github/blob/main/AI_POLICY.md)

[jianyexi]

Hi @MichaReiser, thanks for the heads-up on the AI policy. I want to clarify — yes, I used AI as a coding tool during development, but I manually verified the entire PR myself:

• I tested diagnostics, formatting, and code actions on virtual files in our Fabric VS Code extension (the actual VFS environment I work on daily).
• I stepped through the LSP middleware to confirm URI translation works bidirectionally.
• I verified config discovery works after the initialize() sync by checking ruff picks up pyproject.toml/ruff.toml rules correctly.
• I also wrote and ran E2E tests that cover the full flow — virtual file diagnostics, formatting, and auto-fix. These aren't just generated stubs; they reflect real scenarios I hit during development and validated by hand first.

I understand and own every change in that PR — the translator pattern, the middleware injection, the config sync on initialize. This is the same architecture I built for our Pylance integration at work, so I'm deeply familiar with the approach.

Happy to answer any questions about specific implementation choices. No rush on the review — I understand priorities. Just wanted to make sure you know there's a real human behind the code who tested it end-to-end.