ruff_db

The shared file abstraction and Salsa database building blocks. Source: crates/ruff_db/.

Purpose

ty needs a uniform way to read files from disk, in-memory test fixtures, or a WASM virtual file system, and to participate in Salsa's incremental computation model. ruff_db provides those primitives.

(Ruff's linter and formatter do not depend on ruff_db; they're one-shot, file-by-file. The database layer exists primarily for ty.)

Directory layout

crates/ruff_db/src/
├── lib.rs
├── system/         # file system abstraction
├── files.rs        # File handles
├── parsed.rs       # cached parser results
├── source.rs       # source files + line tables
├── vendored.rs     # in-binary embedded files
├── diagnostic/     # database-aware diagnostic helpers
└── ...

Key abstractions

Type	Purpose
System (trait)	The file-system abstraction. Implementations: OsSystem, MemorySystem, WasmSystem.
SystemPath, SystemPathBuf	UTF-8 paths used throughout ty (instead of std::path::Path).
File	A salsa-tracked handle for a file on a System.
Database	Trait extending salsa::Database with file-aware methods.
parsed_module(db, file)	Salsa query: parse a file, cache the result.
source_text(db, file)	Salsa query: read the source.
Vendored	Files embedded into the binary at compile time (used for typeshed).

How it powers ty

graph LR
    System[System impl<br/>Os / Memory / Wasm]
    Files[Files store<br/>FxHashMap]
    File[File handle]
    Source[source_text query]
    Parsed[parsed_module query]
    AST[ruff_python_ast::Mod]

    System --> Files
    Files --> File
    File --> Source
    File --> Parsed
    Parsed --> AST

ty's ProjectDatabase (crates/ty_python_semantic/src/db.rs) implements Database and adds project-specific queries on top.

Why the file system is abstracted

• Tests. mdtest fixtures define multi-file projects in memory; MemorySystem lets ty operate on them without touching disk.
• WASM. The browser playground has no real file system; WasmSystem provides one.
• LSP. ty_server keeps unsaved buffers in memory and falls back to disk for the rest.

Integration points

• Used by every ty crate: ty_project, ty_python_semantic, ty_server, ty_module_resolver, ty_site_packages, ty_wasm.
• Not used by Ruff's linter or formatter (the linter is intentionally Salsa-free for raw throughput).

Modifying

• Adding a new System capability: extend the trait, update all three implementations, add tests.
• Adding a new tracked query: place it next to source_text / parsed_module and ensure it's #[salsa::tracked] if it depends on file content.

See ty_python_semantic for the consumer side and Architecture for the broader picture.