[WIP] working version of SSA-style use-def map

Stabilize support for Jupyter Notebooks (#12878 )
Co-authored-by: Alex Waygood <alex.waygood@gmail.com> Closes: #12456 Closes: https://github.com/astral-sh/ruff-vscode/issues/546
2024-08-14 17:10:11 -07:00 · 2024-08-14 18:15:45 +02:00 · 2024-08-14 18:15:45 +02:00 · 2024-08-14 18:15:45 +02:00 · 2024-08-14 18:15:45 +02:00 · 2024-08-14 18:15:45 +02:00
308 changed files with 9681 additions and 5155 deletions
--- a/.github/renovate.json5
+++ b/.github/renovate.json5
@@ -14,12 +14,26 @@
    rangeStrategy: "update-lockfile",
  },
  pep621: {
+    // The default for this package manager is to only search for `pyproject.toml` files
+    // found at the repository root: https://docs.renovatebot.com/modules/manager/pep621/#file-matching
    fileMatch: ["^(python|scripts)/.*pyproject\\.toml$"],
  },
  pip_requirements: {
-    fileMatch: ["^docs/requirements.*\\.txt$"],
+    // The default for this package manager is to run on all requirements.txt files:
+    // https://docs.renovatebot.com/modules/manager/pip_requirements/#file-matching
+    // `fileMatch` doesn't work for excluding files; to exclude `requirements.txt` files
+    // outside the `doc/` directory, we instead have to use `ignorePaths`. Unlike `fileMatch`,
+    // which takes a regex string, `ignorePaths` takes a glob string, so we have to use
+    // a "negative glob pattern".
+    // See:
+    // - https://docs.renovatebot.com/modules/manager/#ignoring-files-that-match-the-default-filematch
+    // - https://docs.renovatebot.com/configuration-options/#ignorepaths
+    // - https://docs.renovatebot.com/string-pattern-matching/#negative-matching
+    ignorePaths: ["!docs/requirements*.txt"]
  },
  npm: {
+    // The default for this package manager is to only search for `package.json` files
+    // found at the repository root: https://docs.renovatebot.com/modules/manager/npm/#file-matching
    fileMatch: ["^playground/.*package\\.json$"],
  },
  "pre-commit": {
--- a/.github/workflows/ci.yaml
+++ b/.github/workflows/ci.yaml
@@ -142,6 +142,13 @@ jobs:

      # Check for broken links in the documentation.
      - run: cargo doc --all --no-deps
+        env:
+          RUSTDOCFLAGS: "-D warnings"
+      # Use --document-private-items so that all our doc comments are kept in
+      # sync, not just public items. Eventually we should do this for all
+      # crates; for now add crates here as they are warning-clean to prevent
+      # regression.
+      - run: cargo doc --no-deps -p red_knot_python_semantic -p red_knot -p ruff_db --document-private-items
        env:
          # Setting RUSTDOCFLAGS because `cargo doc --check` isn't yet implemented (https://github.com/rust-lang/cargo/issues/10025).
          RUSTDOCFLAGS: "-D warnings"
--- a/.markdownlint.yaml
+++ b/.markdownlint.yaml
@@ -14,6 +14,9 @@ MD041: false
 # MD013/line-length
 MD013: false

+# MD014/commands-show-output
+MD014: false
+
 # MD024/no-duplicate-heading
 MD024:
  # Allow when nested under different parents e.g. CHANGELOG.md
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -57,7 +57,7 @@ repos:
        pass_filenames: false # This makes it a lot faster

  - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.5.6
+    rev: v0.5.7
    hooks:
      - id: ruff-format
      - id: ruff
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -911,9 +911,5 @@ There are three ways in which an import can be categorized as "first-party":
    the `src` setting and, for each directory, check for the existence of a subdirectory `foo` or a
    file `foo.py`.

-By default, `src` is set to the project root. In the above example, we'd want to set
-`src = ["./src"]` to ensure that we locate `./my_project/src/foo` and thus categorize `import foo`
-as first-party in `baz.py`. In practice, for this limited example, setting `src = ["./src"]` is
-unnecessary, as all imports within `./my_project/src/foo` would be categorized as first-party via
-the same-package heuristic; but if your project contains multiple packages, you'll want to set `src`
-explicitly.
+By default, `src` is set to the project root, along with `"src"` subdirectory in the project root.
+This ensures that Ruff supports both flat and "src" layouts out of the box.
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -95,9 +95,9 @@ dependencies = [

 [[package]]
 name = "anstyle"
-version = "1.0.6"
+version = "1.0.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8901269c6307e8d93993578286ac0edf7f195079ffff5ebdeea6a59ffb7e36bc"
+checksum = "1bec1de6f59aedf83baf9ff929c98f2ad654b97c9510f4e70cf6f661d49fd5b1"

 [[package]]
 name = "anstyle-parse"
@@ -288,7 +288,7 @@ dependencies = [
 "android-tzdata",
 "iana-time-zone",
 "num-traits",
- "windows-targets 0.52.5",
+ "windows-targets 0.52.6",
 ]

 [[package]]
@@ -320,9 +320,9 @@ dependencies = [

 [[package]]
 name = "clap"
-version = "4.5.13"
+version = "4.5.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0fbb260a053428790f3de475e304ff84cdbc4face759ea7a3e64c1edd938a7fc"
+checksum = "11d8838454fda655dafd3accb2b6e2bea645b9e4078abe84a22ceb947235c5cc"
 dependencies = [
 "clap_builder",
 "clap_derive",
@@ -330,9 +330,9 @@ dependencies = [

 [[package]]
 name = "clap_builder"
-version = "4.5.13"
+version = "4.5.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "64b17d7ea74e9f833c7dbf2cbe4fb12ff26783eda4782a8975b72f895c9b4d99"
+checksum = "216aec2b177652e3846684cbfe25c9964d18ec45234f0f5da5157b207ed1aab6"
 dependencies = [
 "anstream",
 "anstyle",
@@ -820,14 +820,14 @@ dependencies = [

 [[package]]
 name = "filetime"
-version = "0.2.23"
+version = "0.2.24"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1ee447700ac8aa0b2f2bd7bc4462ad686ba06baa6727ac149a2d6277f0d240fd"
+checksum = "bf401df4a4e3872c4fe8151134cf483738e74b67fc934d6532c882b3d24a4550"
 dependencies = [
 "cfg-if",
 "libc",
- "redox_syscall",
- "windows-sys 0.52.0",
+ "libredox",
+ "windows-sys 0.59.0",
 ]

 [[package]]
@@ -1143,9 +1143,9 @@ dependencies = [

 [[package]]
 name = "is-macro"
-version = "0.3.5"
+version = "0.3.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "59a85abdc13717906baccb5a1e435556ce0df215f242892f721dff62bf25288f"
+checksum = "2069faacbe981460232f880d26bf3c7634e322d49053aa48c27e3ae642f728f1"
 dependencies = [
 "Inflector",
 "proc-macro2",
@@ -1297,6 +1297,7 @@ checksum = "c0ff37bd590ca25063e35af745c343cb7a0271906fb7b37e4813e8f79f00268d"
 dependencies = [
 "bitflags 2.6.0",
 "libc",
+ "redox_syscall 0.5.3",
 ]

 [[package]]
@@ -1564,7 +1565,7 @@ checksum = "4c42a9226546d68acdd9c0a280d17ce19bfe27a46bf68784e4066115788d008e"
 dependencies = [
 "cfg-if",
 "libc",
- "redox_syscall",
+ "redox_syscall 0.4.1",
 "smallvec",
 "windows-targets 0.48.5",
 ]
@@ -1899,9 +1900,11 @@ dependencies = [
 "ruff_python_ast",
 "ruff_python_parser",
 "ruff_python_stdlib",
+ "ruff_source_file",
 "ruff_text_size",
 "rustc-hash 2.0.0",
 "salsa",
+ "smallvec",
 "tempfile",
 "tracing",
 "walkdir",
@@ -1918,6 +1921,7 @@ dependencies = [
 "libc",
 "lsp-server",
 "lsp-types",
+ "red_knot_python_semantic",
 "red_knot_workspace",
 "ruff_db",
 "ruff_linter",
@@ -1941,6 +1945,7 @@ dependencies = [
 "console_log",
 "js-sys",
 "log",
+ "red_knot_python_semantic",
 "red_knot_workspace",
 "ruff_db",
 "ruff_notebook",
@@ -1959,6 +1964,7 @@ dependencies = [
 "ruff_cache",
 "ruff_db",
 "ruff_python_ast",
+ "ruff_text_size",
 "rustc-hash 2.0.0",
 "salsa",
 "thiserror",
@@ -1974,6 +1980,15 @@ dependencies = [
 "bitflags 1.3.2",
 ]

+[[package]]
+name = "redox_syscall"
+version = "0.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2a908a6e00f1fdd0dfd9c0eb08ce85126f6d8bbda50017e74bc4a4b7d4a926a4"
+dependencies = [
+ "bitflags 2.6.0",
+]
+
 [[package]]
 name = "redox_users"
 version = "0.4.5"
@@ -2104,6 +2119,7 @@ dependencies = [
 "criterion",
 "mimalloc",
 "once_cell",
+ "red_knot_python_semantic",
 "red_knot_workspace",
 "ruff_db",
 "ruff_linter",
@@ -2153,7 +2169,10 @@ dependencies = [
 "rustc-hash 2.0.0",
 "salsa",
 "tempfile",
+ "thiserror",
 "tracing",
+ "tracing-subscriber",
+ "tracing-tree",
 "web-time",
 "zip",
 ]
@@ -2781,9 +2800,9 @@ checksum = "1c107b6f4780854c8b126e228ea8869f4d7b71260f962fefb57b996b8959ba6b"

 [[package]]
 name = "serde"
-version = "1.0.204"
+version = "1.0.206"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bc76f558e0cbb2a839d37354c575f1dc3fdc6546b5be373ba43d95f231bf7c12"
+checksum = "5b3e4cd94123dd520a128bcd11e34d9e9e423e7e3e50425cb1b4b1e3549d0284"
 dependencies = [
 "serde_derive",
 ]
@@ -2801,9 +2820,9 @@ dependencies = [

 [[package]]
 name = "serde_derive"
-version = "1.0.204"
+version = "1.0.206"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e0cd7e117be63d3c3678776753929474f3b04a43a080c744d6b0ae2a8c28e222"
+checksum = "fabfb6138d2383ea8208cf98ccf69cdfb1aff4088460681d84189aa259762f97"
 dependencies = [
 "proc-macro2",
 "quote",
@@ -2823,9 +2842,9 @@ dependencies = [

 [[package]]
 name = "serde_json"
-version = "1.0.122"
+version = "1.0.124"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "784b6203951c57ff748476b126ccb5e8e2959a5c19e5c617ab1956be3dbc68da"
+checksum = "66ad62847a56b3dba58cc891acd13884b9c61138d330c0d7b6181713d4fce38d"
 dependencies = [
 "itoa",
 "memchr",
@@ -2855,9 +2874,9 @@ dependencies = [

 [[package]]
 name = "serde_test"
-version = "1.0.176"
+version = "1.0.177"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5a2f49ace1498612d14f7e0b8245519584db8299541dfe31a06374a828d620ab"
+checksum = "7f901ee573cab6b3060453d2d5f0bae4e6d628c23c0a962ff9b5f1d7c8d4f1ed"
 dependencies = [
 "serde",
 ]
@@ -2984,9 +3003,9 @@ checksum = "81cdd64d312baedb58e21336b31bc043b77e01cc99033ce76ef539f78e965ebc"

 [[package]]
 name = "syn"
-version = "2.0.72"
+version = "2.0.74"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dc4b9b9bf2add8093d3f2c0204471e951b2285580335de42f9d2534f3ae7a8af"
+checksum = "1fceb41e3d546d0bd83421d3409b1460cc7444cd389341a4c880fe7a042cb3d7"
 dependencies = [
 "proc-macro2",
 "quote",
@@ -3006,15 +3025,15 @@ dependencies = [

 [[package]]
 name = "tempfile"
-version = "3.11.0"
+version = "3.12.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b8fcd239983515c23a32fb82099f97d0b11b8c72f654ed659363a95c3dad7a53"
+checksum = "04cbcdd0c794ebb0d4cf35e88edd2f7d2c4c3e9a5a6dab322839b321c6a87a64"
 dependencies = [
 "cfg-if",
 "fastrand",
 "once_cell",
 "rustix",
- "windows-sys 0.52.0",
+ "windows-sys 0.59.0",
 ]

 [[package]]
@@ -3390,9 +3409,9 @@ checksum = "8ecb6da28b8a351d773b68d5825ac39017e680750f980f3a1a85cd8dd28a47c1"

 [[package]]
 name = "ureq"
-version = "2.10.0"
+version = "2.10.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "72139d247e5f97a3eff96229a7ae85ead5328a39efe76f8bf5a06313d505b6ea"
+checksum = "b74fc6b57825be3373f7054754755f03ac3a8f5d70015ccad699ba2029956f4a"
 dependencies = [
 "base64",
 "flate2",
@@ -3684,7 +3703,7 @@ version = "0.52.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "33ab640c8d7e35bf8ba19b884ba838ceb4fba93a4e8c65a9059d08afcfc683d9"
 dependencies = [
- "windows-targets 0.52.5",
+ "windows-targets 0.52.6",
 ]

 [[package]]
@@ -3702,7 +3721,16 @@ version = "0.52.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d"
 dependencies = [
- "windows-targets 0.52.5",
+ "windows-targets 0.52.6",
+]
+
+[[package]]
+name = "windows-sys"
+version = "0.59.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e38bc4d79ed67fd075bcc251a1c39b32a1776bbe92e5bef1f0bf1f8c531853b"
+dependencies = [
+ "windows-targets 0.52.6",
 ]

 [[package]]
@@ -3722,18 +3750,18 @@ dependencies = [

 [[package]]
 name = "windows-targets"
-version = "0.52.5"
+version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6f0713a46559409d202e70e28227288446bf7841d3211583a4b53e3f6d96e7eb"
+checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973"
 dependencies = [
- "windows_aarch64_gnullvm 0.52.5",
- "windows_aarch64_msvc 0.52.5",
- "windows_i686_gnu 0.52.5",
+ "windows_aarch64_gnullvm 0.52.6",
+ "windows_aarch64_msvc 0.52.6",
+ "windows_i686_gnu 0.52.6",
 "windows_i686_gnullvm",
- "windows_i686_msvc 0.52.5",
- "windows_x86_64_gnu 0.52.5",
- "windows_x86_64_gnullvm 0.52.5",
- "windows_x86_64_msvc 0.52.5",
+ "windows_i686_msvc 0.52.6",
+ "windows_x86_64_gnu 0.52.6",
+ "windows_x86_64_gnullvm 0.52.6",
+ "windows_x86_64_msvc 0.52.6",
 ]

 [[package]]
@@ -3744,9 +3772,9 @@ checksum = "2b38e32f0abccf9987a4e3079dfb67dcd799fb61361e53e2882c3cbaf0d905d8"

 [[package]]
 name = "windows_aarch64_gnullvm"
-version = "0.52.5"
+version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7088eed71e8b8dda258ecc8bac5fb1153c5cffaf2578fc8ff5d61e23578d3263"
+checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3"

 [[package]]
 name = "windows_aarch64_msvc"
@@ -3756,9 +3784,9 @@ checksum = "dc35310971f3b2dbbf3f0690a219f40e2d9afcf64f9ab7cc1be722937c26b4bc"

 [[package]]
 name = "windows_aarch64_msvc"
-version = "0.52.5"
+version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9985fd1504e250c615ca5f281c3f7a6da76213ebd5ccc9561496568a2752afb6"
+checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469"

 [[package]]
 name = "windows_i686_gnu"
@@ -3768,15 +3796,15 @@ checksum = "a75915e7def60c94dcef72200b9a8e58e5091744960da64ec734a6c6e9b3743e"

 [[package]]
 name = "windows_i686_gnu"
-version = "0.52.5"
+version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "88ba073cf16d5372720ec942a8ccbf61626074c6d4dd2e745299726ce8b89670"
+checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b"

 [[package]]
 name = "windows_i686_gnullvm"
-version = "0.52.5"
+version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "87f4261229030a858f36b459e748ae97545d6f1ec60e5e0d6a3d32e0dc232ee9"
+checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66"

 [[package]]
 name = "windows_i686_msvc"
@@ -3786,9 +3814,9 @@ checksum = "8f55c233f70c4b27f66c523580f78f1004e8b5a8b659e05a4eb49d4166cca406"

 [[package]]
 name = "windows_i686_msvc"
-version = "0.52.5"
+version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "db3c2bf3d13d5b658be73463284eaf12830ac9a26a90c717b7f771dfe97487bf"
+checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66"

 [[package]]
 name = "windows_x86_64_gnu"
@@ -3798,9 +3826,9 @@ checksum = "53d40abd2583d23e4718fddf1ebec84dbff8381c07cae67ff7768bbf19c6718e"

 [[package]]
 name = "windows_x86_64_gnu"
-version = "0.52.5"
+version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4e4246f76bdeff09eb48875a0fd3e2af6aada79d409d33011886d3e1581517d9"
+checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78"

 [[package]]
 name = "windows_x86_64_gnullvm"
@@ -3810,9 +3838,9 @@ checksum = "0b7b52767868a23d5bab768e390dc5f5c55825b6d30b86c844ff2dc7414044cc"

 [[package]]
 name = "windows_x86_64_gnullvm"
-version = "0.52.5"
+version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "852298e482cd67c356ddd9570386e2862b5673c85bd5f88df9ab6802b334c596"
+checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d"

 [[package]]
 name = "windows_x86_64_msvc"
@@ -3822,9 +3850,9 @@ checksum = "ed94fce61571a4006852b7389a063ab983c02eb1bb37b47f8272ce92d06d9538"

 [[package]]
 name = "windows_x86_64_msvc"
-version = "0.52.5"
+version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bec47e5bfd1bff0eeaf6d8b485cc1074891a197ab4225d504cb7a1ab88b02bf0"
+checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"

 [[package]]
 name = "winnow"
--- a/crates/red_knot/docs/tracing.md
+++ b/crates/red_knot/docs/tracing.md
@@ -72,6 +72,26 @@ runs or when restoring from a persistent cache. This can be confusing for users
 don't understand why a specific lint violation isn't raised. Instead, change your
 query to return the failure as part of the query's result or use a Salsa accumulator.

+## Tracing in tests
+
+You can use `ruff_db::testing::setup_logging` or `ruff_db::testing::setup_logging_with_filter` to set up logging in tests.
+
+```rust
+use ruff_db::testing::setup_logging;
+
+#[test]
+fn test() {
+  let _logging = setup_logging();
+
+  tracing::info!("This message will be printed to stderr");
+}
+```
+
+Note: Most test runners capture stderr and only show its output when a test fails.
+
+Note also that `setup_logging` only sets up logging for the current thread because [`set_global_default`](https://docs.rs/tracing/latest/tracing/subscriber/fn.set_global_default.html) can only be
+called **once**.
+
 ## Release builds

 `trace!` events are removed in release builds.
--- a/crates/red_knot/src/main.rs
+++ b/crates/red_knot/src/main.rs
@@ -7,13 +7,13 @@ use colored::Colorize;
 use crossbeam::channel as crossbeam_channel;
 use salsa::plumbing::ZalsaDatabase;

+use red_knot_python_semantic::{ProgramSettings, SearchPathSettings};
 use red_knot_server::run_server;
 use red_knot_workspace::db::RootDatabase;
-use red_knot_workspace::site_packages::site_packages_dirs_of_venv;
+use red_knot_workspace::site_packages::VirtualEnvironment;
 use red_knot_workspace::watch;
 use red_knot_workspace::watch::WorkspaceWatcher;
 use red_knot_workspace::workspace::WorkspaceMetadata;
-use ruff_db::program::{ProgramSettings, SearchPathSettings};
 use ruff_db::system::{OsSystem, System, SystemPath, SystemPathBuf};
 use target_version::TargetVersion;

@@ -164,16 +164,9 @@ fn run() -> anyhow::Result<ExitStatus> {

    // TODO: Verify the remaining search path settings eagerly.
    let site_packages = venv_path
-        .map(|venv_path| {
-            let venv_path = SystemPath::absolute(venv_path, &cli_base_path);
-
-            if system.is_directory(&venv_path) {
-                Ok(site_packages_dirs_of_venv(&venv_path, &system)?)
-            } else {
-                Err(anyhow!(
-                    "Provided venv-path {venv_path} is not a directory!"
-                ))
-            }
+        .map(|path| {
+            VirtualEnvironment::new(path, &OsSystem::new(cli_base_path))
+                .and_then(|venv| venv.site_packages_directories(&system))
        })
        .transpose()?
        .unwrap_or_default();
@@ -191,7 +184,7 @@ fn run() -> anyhow::Result<ExitStatus> {

    // TODO: Use the `program_settings` to compute the key for the database's persistent
    //   cache and load the cache if it exists.
-    let mut db = RootDatabase::new(workspace_metadata, program_settings, system);
+    let mut db = RootDatabase::new(workspace_metadata, program_settings, system)?;

    let (main_loop, main_loop_cancellation_token) = MainLoop::new();

--- a/crates/red_knot/src/target_version.rs
+++ b/crates/red_knot/src/target_version.rs
@@ -13,22 +13,36 @@ pub enum TargetVersion {
    Py313,
 }

-impl std::fmt::Display for TargetVersion {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        ruff_db::program::TargetVersion::from(*self).fmt(f)
-    }
-}
-
-impl From<TargetVersion> for ruff_db::program::TargetVersion {
-    fn from(value: TargetVersion) -> Self {
-        match value {
-            TargetVersion::Py37 => Self::Py37,
-            TargetVersion::Py38 => Self::Py38,
-            TargetVersion::Py39 => Self::Py39,
-            TargetVersion::Py310 => Self::Py310,
-            TargetVersion::Py311 => Self::Py311,
-            TargetVersion::Py312 => Self::Py312,
-            TargetVersion::Py313 => Self::Py313,
+impl TargetVersion {
+    const fn as_str(self) -> &'static str {
+        match self {
+            Self::Py37 => "py37",
+            Self::Py38 => "py38",
+            Self::Py39 => "py39",
+            Self::Py310 => "py310",
+            Self::Py311 => "py311",
+            Self::Py312 => "py312",
+            Self::Py313 => "py313",
+        }
+    }
+}
+
+impl std::fmt::Display for TargetVersion {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
+
+impl From<TargetVersion> for red_knot_python_semantic::PythonVersion {
+    fn from(value: TargetVersion) -> Self {
+        match value {
+            TargetVersion::Py37 => Self::PY37,
+            TargetVersion::Py38 => Self::PY38,
+            TargetVersion::Py39 => Self::PY39,
+            TargetVersion::Py310 => Self::PY310,
+            TargetVersion::Py311 => Self::PY311,
+            TargetVersion::Py312 => Self::PY312,
+            TargetVersion::Py313 => Self::PY313,
        }
    }
 }
--- a/crates/red_knot/tests/file_watching.rs
+++ b/crates/red_knot/tests/file_watching.rs
@@ -4,15 +4,15 @@ use std::io::Write;
 use std::time::Duration;

 use anyhow::{anyhow, Context};
-use salsa::Setter;

-use red_knot_python_semantic::{resolve_module, ModuleName};
+use red_knot_python_semantic::{
+    resolve_module, ModuleName, Program, ProgramSettings, PythonVersion, SearchPathSettings,
+};
 use red_knot_workspace::db::RootDatabase;
 use red_knot_workspace::watch;
 use red_knot_workspace::watch::{directory_watcher, WorkspaceWatcher};
 use red_knot_workspace::workspace::WorkspaceMetadata;
 use ruff_db::files::{system_path_to_file, File, FileError};
-use ruff_db::program::{Program, ProgramSettings, SearchPathSettings, TargetVersion};
 use ruff_db::source::source_text;
 use ruff_db::system::{OsSystem, SystemPath, SystemPathBuf};
 use ruff_db::Upcast;
@@ -25,6 +25,7 @@ struct TestCase {
    /// We need to hold on to it in the test case or the temp files get deleted.
    _temp_dir: tempfile::TempDir,
    root_dir: SystemPathBuf,
+    search_path_settings: SearchPathSettings,
 }

 impl TestCase {
@@ -107,18 +108,20 @@ impl TestCase {
    fn update_search_path_settings(
        &mut self,
        f: impl FnOnce(&SearchPathSettings) -> SearchPathSettings,
-    ) {
+    ) -> anyhow::Result<()> {
        let program = Program::get(self.db());
-        let search_path_settings = program.search_paths(self.db());

-        let new_settings = f(search_path_settings);
+        let new_settings = f(&self.search_path_settings);

-        program.set_search_paths(&mut self.db).to(new_settings);
+        program.update_search_paths(&mut self.db, new_settings.clone())?;
+        self.search_path_settings = new_settings;

        if let Some(watcher) = &mut self.watcher {
            watcher.update(&self.db);
            assert!(!watcher.has_errored_paths());
        }
+
+        Ok(())
    }

    fn collect_package_files(&self, path: &SystemPath) -> Vec<File> {
@@ -220,24 +223,24 @@ where
    let system = OsSystem::new(&workspace_path);

    let workspace = WorkspaceMetadata::from_path(&workspace_path, &system)?;
-    let search_paths = create_search_paths(&root_path, workspace.root());
+    let search_path_settings = create_search_paths(&root_path, workspace.root());

-    for path in search_paths
+    for path in search_path_settings
        .extra_paths
        .iter()
-        .chain(search_paths.site_packages.iter())
-        .chain(search_paths.custom_typeshed.iter())
+        .chain(search_path_settings.site_packages.iter())
+        .chain(search_path_settings.custom_typeshed.iter())
    {
        std::fs::create_dir_all(path.as_std_path())
            .with_context(|| format!("Failed to create search path '{path}'"))?;
    }

    let settings = ProgramSettings {
-        target_version: TargetVersion::default(),
-        search_paths,
+        target_version: PythonVersion::default(),
+        search_paths: search_path_settings.clone(),
    };

-    let db = RootDatabase::new(workspace, settings, system);
+    let db = RootDatabase::new(workspace, settings, system)?;

    let (sender, receiver) = crossbeam::channel::unbounded();
    let watcher = directory_watcher(move |events| sender.send(events).unwrap())
@@ -252,6 +255,7 @@ where
        watcher: Some(watcher),
        _temp_dir: temp_dir,
        root_dir: root_path,
+        search_path_settings,
    };

    // Sometimes the file watcher reports changes for events that happened before the watcher was started.
@@ -736,7 +740,8 @@ fn add_search_path() -> anyhow::Result<()> {
    case.update_search_path_settings(|settings| SearchPathSettings {
        site_packages: vec![site_packages.clone()],
        ..settings.clone()
-    });
+    })
+    .expect("Search path settings to be valid");

    std::fs::write(site_packages.join("a.py").as_std_path(), "class A: ...")?;

@@ -766,7 +771,8 @@ fn remove_search_path() -> anyhow::Result<()> {
    case.update_search_path_settings(|settings| SearchPathSettings {
        site_packages: vec![],
        ..settings.clone()
-    });
+    })
+    .expect("Search path settings to be valid");

    std::fs::write(site_packages.join("a.py").as_std_path(), "class A: ...")?;

--- a/crates/red_knot_python_semantic/Cargo.toml
+++ b/crates/red_knot_python_semantic/Cargo.toml
@@ -15,8 +15,10 @@ ruff_db = { workspace = true }
 ruff_index = { workspace = true }
 ruff_python_ast = { workspace = true }
 ruff_python_stdlib = { workspace = true }
+ruff_source_file = { workspace = true }
 ruff_text_size = { workspace = true }

+anyhow = { workspace = true }
 bitflags = { workspace = true }
 camino = { workspace = true }
 compact_str = { workspace = true }
@@ -24,6 +26,7 @@ countme = { workspace = true }
 once_cell = { workspace = true }
 ordermap = { workspace = true }
 salsa = { workspace = true }
+smallvec = { workspace = true }
 tracing = { workspace = true }
 rustc-hash = { workspace = true }
 hashbrown = { workspace = true }
@@ -34,12 +37,14 @@ walkdir = { workspace = true }
 zip = { workspace = true, features = ["zstd", "deflate"] }

 [dev-dependencies]
+ruff_db = { workspace = true, features = ["os", "testing"] }
+ruff_python_parser = { workspace = true }
+
 anyhow = { workspace = true }
 insta = { workspace = true }
 tempfile = { workspace = true }
 walkdir = { workspace = true }
 zip = { workspace = true }
-ruff_python_parser = { workspace = true }

 [lints]
 workspace = true
--- a/crates/red_knot_python_semantic/src/lib.rs
+++ b/crates/red_knot_python_semantic/src/lib.rs
@@ -5,6 +5,8 @@ use rustc_hash::FxHasher;
 pub use db::Db;
 pub use module_name::ModuleName;
 pub use module_resolver::{resolve_module, system_module_search_paths, vendored_typeshed_stubs};
+pub use program::{Program, ProgramSettings, SearchPathSettings};
+pub use python_version::PythonVersion;
 pub use semantic_model::{HasTy, SemanticModel};

 pub mod ast_node_ref;
@@ -13,6 +15,8 @@ mod db;
 mod module_name;
 mod module_resolver;
 mod node_key;
+mod program;
+mod python_version;
 pub mod semantic_index;
 mod semantic_model;
 pub mod types;
--- a/crates/red_knot_python_semantic/src/module_resolver/mod.rs
+++ b/crates/red_knot_python_semantic/src/module_resolver/mod.rs
@@ -2,11 +2,13 @@ use std::iter::FusedIterator;

 pub(crate) use module::Module;
 pub use resolver::resolve_module;
+pub(crate) use resolver::SearchPaths;
 use ruff_db::system::SystemPath;
 pub use typeshed::vendored_typeshed_stubs;

+use crate::module_resolver::resolver::search_paths;
 use crate::Db;
-use resolver::{module_resolution_settings, SearchPathIterator};
+use resolver::SearchPathIterator;

 mod module;
 mod path;
@@ -20,7 +22,7 @@ mod testing;
 /// Returns an iterator over all search paths pointing to a system path
 pub fn system_module_search_paths(db: &dyn Db) -> SystemModuleSearchPathsIter {
    SystemModuleSearchPathsIter {
-        inner: module_resolution_settings(db).search_paths(db),
+        inner: search_paths(db),
    }
 }

--- a/crates/red_knot_python_semantic/src/module_resolver/path.rs
+++ b/crates/red_knot_python_semantic/src/module_resolver/path.rs
@@ -620,14 +620,13 @@ impl PartialEq<SearchPath> for VendoredPathBuf {

 #[cfg(test)]
 mod tests {
-    use ruff_db::program::TargetVersion;
    use ruff_db::Db;

    use crate::db::tests::TestDb;

-    use crate::module_resolver::testing::{FileSpec, MockedTypeshed, TestCase, TestCaseBuilder};
-
    use super::*;
+    use crate::module_resolver::testing::{FileSpec, MockedTypeshed, TestCase, TestCaseBuilder};
+    use crate::python_version::PythonVersion;

    impl ModulePath {
        #[must_use]
@@ -867,7 +866,7 @@ mod tests {

    fn typeshed_test_case(
        typeshed: MockedTypeshed,
-        target_version: TargetVersion,
+        target_version: PythonVersion,
    ) -> (TestDb, SearchPath) {
        let TestCase { db, stdlib, .. } = TestCaseBuilder::new()
            .with_custom_typeshed(typeshed)
@@ -879,11 +878,11 @@ mod tests {
    }

    fn py38_typeshed_test_case(typeshed: MockedTypeshed) -> (TestDb, SearchPath) {
-        typeshed_test_case(typeshed, TargetVersion::Py38)
+        typeshed_test_case(typeshed, PythonVersion::PY38)
    }

    fn py39_typeshed_test_case(typeshed: MockedTypeshed) -> (TestDb, SearchPath) {
-        typeshed_test_case(typeshed, TargetVersion::Py39)
+        typeshed_test_case(typeshed, PythonVersion::PY39)
    }

    #[test]
@@ -899,7 +898,7 @@ mod tests {
        };

        let (db, stdlib_path) = py38_typeshed_test_case(TYPESHED);
-        let resolver = ResolverState::new(&db, TargetVersion::Py38);
+        let resolver = ResolverState::new(&db, PythonVersion::PY38);

        let asyncio_regular_package = stdlib_path.join("asyncio");
        assert!(asyncio_regular_package.is_directory(&resolver));
@@ -927,7 +926,7 @@ mod tests {
        };

        let (db, stdlib_path) = py38_typeshed_test_case(TYPESHED);
-        let resolver = ResolverState::new(&db, TargetVersion::Py38);
+        let resolver = ResolverState::new(&db, PythonVersion::PY38);

        let xml_namespace_package = stdlib_path.join("xml");
        assert!(xml_namespace_package.is_directory(&resolver));
@@ -949,7 +948,7 @@ mod tests {
        };

        let (db, stdlib_path) = py38_typeshed_test_case(TYPESHED);
-        let resolver = ResolverState::new(&db, TargetVersion::Py38);
+        let resolver = ResolverState::new(&db, PythonVersion::PY38);

        let functools_module = stdlib_path.join("functools.pyi");
        assert!(functools_module.to_file(&resolver).is_some());
@@ -965,7 +964,7 @@ mod tests {
        };

        let (db, stdlib_path) = py38_typeshed_test_case(TYPESHED);
-        let resolver = ResolverState::new(&db, TargetVersion::Py38);
+        let resolver = ResolverState::new(&db, PythonVersion::PY38);

        let collections_regular_package = stdlib_path.join("collections");
        assert_eq!(collections_regular_package.to_file(&resolver), None);
@@ -981,7 +980,7 @@ mod tests {
        };

        let (db, stdlib_path) = py38_typeshed_test_case(TYPESHED);
-        let resolver = ResolverState::new(&db, TargetVersion::Py38);
+        let resolver = ResolverState::new(&db, PythonVersion::PY38);

        let importlib_namespace_package = stdlib_path.join("importlib");
        assert_eq!(importlib_namespace_package.to_file(&resolver), None);
@@ -1002,7 +1001,7 @@ mod tests {
        };

        let (db, stdlib_path) = py38_typeshed_test_case(TYPESHED);
-        let resolver = ResolverState::new(&db, TargetVersion::Py38);
+        let resolver = ResolverState::new(&db, PythonVersion::PY38);

        let non_existent = stdlib_path.join("doesnt_even_exist");
        assert_eq!(non_existent.to_file(&resolver), None);
@@ -1030,7 +1029,7 @@ mod tests {
        };

        let (db, stdlib_path) = py39_typeshed_test_case(TYPESHED);
-        let resolver = ResolverState::new(&db, TargetVersion::Py39);
+        let resolver = ResolverState::new(&db, PythonVersion::PY39);

        // Since we've set the target version to Py39,
        // `collections` should now exist as a directory, according to VERSIONS...
@@ -1059,7 +1058,7 @@ mod tests {
        };

        let (db, stdlib_path) = py39_typeshed_test_case(TYPESHED);
-        let resolver = ResolverState::new(&db, TargetVersion::Py39);
+        let resolver = ResolverState::new(&db, PythonVersion::PY39);

        // The `importlib` directory now also exists
        let importlib_namespace_package = stdlib_path.join("importlib");
@@ -1083,7 +1082,7 @@ mod tests {
        };

        let (db, stdlib_path) = py39_typeshed_test_case(TYPESHED);
-        let resolver = ResolverState::new(&db, TargetVersion::Py39);
+        let resolver = ResolverState::new(&db, PythonVersion::PY39);

        // The `xml` package no longer exists on py39:
        let xml_namespace_package = stdlib_path.join("xml");
--- a/crates/red_knot_python_semantic/src/module_resolver/resolver.rs
+++ b/crates/red_knot_python_semantic/src/module_resolver/resolver.rs
@@ -1,14 +1,15 @@
 use std::borrow::Cow;
 use std::iter::FusedIterator;

-use ruff_db::files::{File, FilePath, FileRootKind};
-use ruff_db::program::{Program, SearchPathSettings, TargetVersion};
-use ruff_db::system::{DirectoryEntry, System, SystemPath, SystemPathBuf};
-use ruff_db::vendored::VendoredPath;
 use rustc_hash::{FxBuildHasher, FxHashSet};

+use ruff_db::files::{File, FilePath, FileRootKind};
+use ruff_db::system::{DirectoryEntry, SystemPath, SystemPathBuf};
+use ruff_db::vendored::VendoredPath;
+
 use crate::db::Db;
 use crate::module_name::ModuleName;
+use crate::{Program, SearchPathSettings};

 use super::module::{Module, ModuleKind};
 use super::path::{ModulePath, SearchPath, SearchPathValidationError};
@@ -84,9 +85,7 @@ pub(crate) fn file_to_module(db: &dyn Db, file: File) -> Option<Module> {
        FilePath::SystemVirtual(_) => return None,
    };

-    let settings = module_resolution_settings(db);
-
-    let mut search_paths = settings.search_paths(db);
+    let mut search_paths = search_paths(db);

    let module_name = loop {
        let candidate = search_paths.next()?;
@@ -119,92 +118,122 @@ pub(crate) fn file_to_module(db: &dyn Db, file: File) -> Option<Module> {
    }
 }

-/// Validate and normalize the raw settings given by the user
-/// into settings we can use for module resolution
-///
-/// This method also implements the typing spec's [module resolution order].
-///
-/// [module resolution order]: https://typing.readthedocs.io/en/latest/spec/distributing.html#import-resolution-ordering
-fn try_resolve_module_resolution_settings(
-    db: &dyn Db,
-) -> Result<ModuleResolutionSettings, SearchPathValidationError> {
-    let program = Program::get(db.upcast());
-
-    let SearchPathSettings {
-        extra_paths,
-        src_root,
-        custom_typeshed,
-        site_packages,
-    } = program.search_paths(db.upcast());
-
-    if !extra_paths.is_empty() {
-        tracing::info!("Extra search paths: {extra_paths:?}");
-    }
-
-    if let Some(custom_typeshed) = custom_typeshed {
-        tracing::info!("Custom typeshed directory: {custom_typeshed}");
-    }
-
-    if !site_packages.is_empty() {
-        tracing::info!("Site-packages directories: {site_packages:?}");
-    }
-
-    let system = db.system();
-    let files = db.files();
-
-    let mut static_search_paths = vec![];
-
-    for path in extra_paths {
-        files.try_add_root(db.upcast(), path, FileRootKind::LibrarySearchPath);
-        static_search_paths.push(SearchPath::extra(system, path.clone())?);
-    }
-
-    static_search_paths.push(SearchPath::first_party(system, src_root.clone())?);
-
-    static_search_paths.push(if let Some(custom_typeshed) = custom_typeshed.as_ref() {
-        files.try_add_root(
-            db.upcast(),
-            custom_typeshed,
-            FileRootKind::LibrarySearchPath,
-        );
-        SearchPath::custom_stdlib(db, custom_typeshed.clone())?
-    } else {
-        SearchPath::vendored_stdlib()
-    });
-
-    // TODO vendor typeshed's third-party stubs as well as the stdlib and fallback to them as a final step
-
-    let target_version = program.target_version(db.upcast());
-    tracing::info!("Target version: {target_version}");
-
-    // Filter out module resolution paths that point to the same directory on disk (the same invariant maintained by [`sys.path` at runtime]).
-    // (Paths may, however, *overlap* -- e.g. you could have both `src/` and `src/foo`
-    // as module resolution paths simultaneously.)
-    //
-    // [`sys.path` at runtime]: https://docs.python.org/3/library/site.html#module-site
-    // This code doesn't use an `IndexSet` because the key is the system path and not the search root.
-    let mut seen_paths =
-        FxHashSet::with_capacity_and_hasher(static_search_paths.len(), FxBuildHasher);
-
-    static_search_paths.retain(|path| {
-        if let Some(path) = path.as_system_path() {
-            seen_paths.insert(path.to_path_buf())
-        } else {
-            true
-        }
-    });
-
-    Ok(ModuleResolutionSettings {
-        target_version,
-        static_search_paths,
-        site_packages_paths: site_packages.to_owned(),
-    })
+pub(crate) fn search_paths(db: &dyn Db) -> SearchPathIterator {
+    Program::get(db).search_paths(db).iter(db)
 }

-#[salsa::tracked(return_ref)]
-pub(crate) fn module_resolution_settings(db: &dyn Db) -> ModuleResolutionSettings {
-    // TODO proper error handling if this returns an error:
-    try_resolve_module_resolution_settings(db).unwrap()
+#[derive(Debug, PartialEq, Eq, Default)]
+pub(crate) struct SearchPaths {
+    /// Search paths that have been statically determined purely from reading Ruff's configuration settings.
+    /// These shouldn't ever change unless the config settings themselves change.
+    static_paths: Vec<SearchPath>,
+
+    /// site-packages paths are not included in the above field:
+    /// if there are multiple site-packages paths, editable installations can appear
+    /// *between* the site-packages paths on `sys.path` at runtime.
+    /// That means we can't know where a second or third `site-packages` path should sit
+    /// in terms of module-resolution priority until we've discovered the editable installs
+    /// for the first `site-packages` path
+    site_packages: Vec<SearchPath>,
+}
+
+impl SearchPaths {
+    /// Validate and normalize the raw settings given by the user
+    /// into settings we can use for module resolution
+    ///
+    /// This method also implements the typing spec's [module resolution order].
+    ///
+    /// [module resolution order]: https://typing.readthedocs.io/en/latest/spec/distributing.html#import-resolution-ordering
+    pub(crate) fn from_settings(
+        db: &dyn Db,
+        settings: SearchPathSettings,
+    ) -> Result<Self, SearchPathValidationError> {
+        let SearchPathSettings {
+            extra_paths,
+            src_root,
+            custom_typeshed,
+            site_packages: site_packages_paths,
+        } = settings;
+
+        let system = db.system();
+        let files = db.files();
+
+        let mut static_paths = vec![];
+
+        for path in extra_paths {
+            tracing::debug!("Adding static extra search-path '{path}'");
+
+            let search_path = SearchPath::extra(system, path)?;
+            files.try_add_root(
+                db.upcast(),
+                search_path.as_system_path().unwrap(),
+                FileRootKind::LibrarySearchPath,
+            );
+            static_paths.push(search_path);
+        }
+
+        tracing::debug!("Adding static search path '{src_root}'");
+        static_paths.push(SearchPath::first_party(system, src_root)?);
+
+        static_paths.push(if let Some(custom_typeshed) = custom_typeshed {
+            tracing::debug!("Adding static custom-sdtlib search-path '{custom_typeshed}'");
+
+            let search_path = SearchPath::custom_stdlib(db, custom_typeshed)?;
+            files.try_add_root(
+                db.upcast(),
+                search_path.as_system_path().unwrap(),
+                FileRootKind::LibrarySearchPath,
+            );
+            search_path
+        } else {
+            SearchPath::vendored_stdlib()
+        });
+
+        let mut site_packages: Vec<_> = Vec::with_capacity(site_packages_paths.len());
+
+        for path in site_packages_paths {
+            tracing::debug!("Adding site-package path '{path}'");
+            let search_path = SearchPath::site_packages(system, path)?;
+            files.try_add_root(
+                db.upcast(),
+                search_path.as_system_path().unwrap(),
+                FileRootKind::LibrarySearchPath,
+            );
+            site_packages.push(search_path);
+        }
+
+        // TODO vendor typeshed's third-party stubs as well as the stdlib and fallback to them as a final step
+
+        // Filter out module resolution paths that point to the same directory on disk (the same invariant maintained by [`sys.path` at runtime]).
+        // (Paths may, however, *overlap* -- e.g. you could have both `src/` and `src/foo`
+        // as module resolution paths simultaneously.)
+        //
+        // This code doesn't use an `IndexSet` because the key is the system path and not the search root.
+        //
+        // [`sys.path` at runtime]: https://docs.python.org/3/library/site.html#module-site
+        let mut seen_paths = FxHashSet::with_capacity_and_hasher(static_paths.len(), FxBuildHasher);
+
+        static_paths.retain(|path| {
+            if let Some(path) = path.as_system_path() {
+                seen_paths.insert(path.to_path_buf())
+            } else {
+                true
+            }
+        });
+
+        Ok(SearchPaths {
+            static_paths,
+            site_packages,
+        })
+    }
+
+    pub(crate) fn iter<'a>(&'a self, db: &'a dyn Db) -> SearchPathIterator<'a> {
+        SearchPathIterator {
+            db,
+            static_paths: self.static_paths.iter(),
+            dynamic_paths: None,
+        }
+    }
 }

 /// Collect all dynamic search paths. For each `site-packages` path:
@@ -217,19 +246,20 @@ pub(crate) fn module_resolution_settings(db: &dyn Db) -> ModuleResolutionSetting
 /// module-resolution priority.
 #[salsa::tracked(return_ref)]
 pub(crate) fn dynamic_resolution_paths(db: &dyn Db) -> Vec<SearchPath> {
-    let ModuleResolutionSettings {
-        target_version: _,
-        static_search_paths,
-        site_packages_paths,
-    } = module_resolution_settings(db);
+    tracing::debug!("Resolving dynamic module resolution paths");
+
+    let SearchPaths {
+        static_paths,
+        site_packages,
+    } = Program::get(db).search_paths(db);

    let mut dynamic_paths = Vec::new();

-    if site_packages_paths.is_empty() {
+    if site_packages.is_empty() {
        return dynamic_paths;
    }

-    let mut existing_paths: FxHashSet<_> = static_search_paths
+    let mut existing_paths: FxHashSet<_> = static_paths
        .iter()
        .filter_map(|path| path.as_system_path())
        .map(Cow::Borrowed)
@@ -238,15 +268,19 @@ pub(crate) fn dynamic_resolution_paths(db: &dyn Db) -> Vec<SearchPath> {
    let files = db.files();
    let system = db.system();

-    for site_packages_dir in site_packages_paths {
+    for site_packages_search_path in site_packages {
+        let site_packages_dir = site_packages_search_path
+            .as_system_path()
+            .expect("Expected site package path to be a system path");
+
        if !existing_paths.insert(Cow::Borrowed(site_packages_dir)) {
            continue;
        }
-        let site_packages_root = files.try_add_root(
-            db.upcast(),
-            site_packages_dir,
-            FileRootKind::LibrarySearchPath,
-        );
+
+        let site_packages_root = files
+            .root(db.upcast(), site_packages_dir)
+            .expect("Site-package root to have been created.");
+
        // This query needs to be re-executed each time a `.pth` file
        // is added, modified or removed from the `site-packages` directory.
        // However, we don't use Salsa queries to read the source text of `.pth` files;
@@ -254,8 +288,7 @@ pub(crate) fn dynamic_resolution_paths(db: &dyn Db) -> Vec<SearchPath> {
        // site-package directory's revision.
        site_packages_root.revision(db.upcast());

-        dynamic_paths
-            .push(SearchPath::site_packages(system, site_packages_dir.to_owned()).unwrap());
+        dynamic_paths.push(site_packages_search_path.clone());

        // As well as modules installed directly into `site-packages`,
        // the directory may also contain `.pth` files.
@@ -263,22 +296,38 @@ pub(crate) fn dynamic_resolution_paths(db: &dyn Db) -> Vec<SearchPath> {
        // containing a (relative or absolute) path.
        // Each of these paths may point to an editable install of a package,
        // so should be considered an additional search path.
-        let Ok(pth_file_iterator) = PthFileIterator::new(db, site_packages_dir) else {
-            continue;
+        let pth_file_iterator = match PthFileIterator::new(db, site_packages_dir) {
+            Ok(iterator) => iterator,
+            Err(error) => {
+                tracing::warn!(
+                    "Failed to search for editable installation in {site_packages_dir}: {error}"
+                );
+                continue;
+            }
        };

        // The Python documentation specifies that `.pth` files in `site-packages`
        // are processed in alphabetical order, so collecting and then sorting is necessary.
        // https://docs.python.org/3/library/site.html#module-site
        let mut all_pth_files: Vec<PthFile> = pth_file_iterator.collect();
-        all_pth_files.sort_by(|a, b| a.path.cmp(&b.path));
+        all_pth_files.sort_unstable_by(|a, b| a.path.cmp(&b.path));

-        for pth_file in &all_pth_files {
-            for installation in pth_file.editable_installations() {
-                if existing_paths.insert(Cow::Owned(
-                    installation.as_system_path().unwrap().to_path_buf(),
-                )) {
-                    dynamic_paths.push(installation);
+        let installations = all_pth_files.iter().flat_map(PthFile::items);
+
+        for installation in installations {
+            if existing_paths.insert(Cow::Owned(installation.clone())) {
+                match SearchPath::editable(system, installation) {
+                    Ok(search_path) => {
+                        tracing::debug!(
+                            "Adding editable installation to module resolution path {path}",
+                            path = search_path.as_system_path().unwrap()
+                        );
+                        dynamic_paths.push(search_path);
+                    }
+
+                    Err(error) => {
+                        tracing::debug!("Skipping editable installation: {error}");
+                    }
                }
            }
        }
@@ -324,7 +373,6 @@ impl<'db> FusedIterator for SearchPathIterator<'db> {}
 /// One or more lines in a `.pth` file may be a (relative or absolute)
 /// path that represents an editable installation of a package.
 struct PthFile<'db> {
-    system: &'db dyn System,
    path: SystemPathBuf,
    contents: String,
    site_packages: &'db SystemPath,
@@ -333,9 +381,8 @@ struct PthFile<'db> {
 impl<'db> PthFile<'db> {
    /// Yield paths in this `.pth` file that appear to represent editable installations,
    /// and should therefore be added as module-resolution search paths.
-    fn editable_installations(&'db self) -> impl Iterator<Item = SearchPath> + 'db {
+    fn items(&'db self) -> impl Iterator<Item = SystemPathBuf> + 'db {
        let PthFile {
-            system,
            path: _,
            contents,
            site_packages,
@@ -354,8 +401,8 @@ impl<'db> PthFile<'db> {
            {
                return None;
            }
-            let possible_editable_install = SystemPath::absolute(line, site_packages);
-            SearchPath::editable(*system, possible_editable_install).ok()
+
+            Some(SystemPath::absolute(line, site_packages))
        })
    }
 }
@@ -404,12 +451,15 @@ impl<'db> Iterator for PthFileIterator<'db> {
                continue;
            }

-            let Ok(contents) = db.system().read_to_string(&path) else {
-                continue;
+            let contents = match system.read_to_string(&path) {
+                Ok(contents) => contents,
+                Err(error) => {
+                    tracing::warn!("Failed to read .pth file '{path}': {error}");
+                    continue;
+                }
            };

            return Some(PthFile {
-                system,
                path,
                contents,
                site_packages,
@@ -418,38 +468,6 @@ impl<'db> Iterator for PthFileIterator<'db> {
    }
 }

-/// Validated and normalized module-resolution settings.
-#[derive(Clone, Debug, PartialEq, Eq)]
-pub(crate) struct ModuleResolutionSettings {
-    target_version: TargetVersion,
-
-    /// Search paths that have been statically determined purely from reading Ruff's configuration settings.
-    /// These shouldn't ever change unless the config settings themselves change.
-    static_search_paths: Vec<SearchPath>,
-
-    /// site-packages paths are not included in the above field:
-    /// if there are multiple site-packages paths, editable installations can appear
-    /// *between* the site-packages paths on `sys.path` at runtime.
-    /// That means we can't know where a second or third `site-packages` path should sit
-    /// in terms of module-resolution priority until we've discovered the editable installs
-    /// for the first `site-packages` path
-    site_packages_paths: Vec<SystemPathBuf>,
-}
-
-impl ModuleResolutionSettings {
-    fn target_version(&self) -> TargetVersion {
-        self.target_version
-    }
-
-    pub(crate) fn search_paths<'db>(&'db self, db: &'db dyn Db) -> SearchPathIterator<'db> {
-        SearchPathIterator {
-            db,
-            static_paths: self.static_search_paths.iter(),
-            dynamic_paths: None,
-        }
-    }
-}
-
 /// A thin wrapper around `ModuleName` to make it a Salsa ingredient.
 ///
 /// This is needed because Salsa requires that all query arguments are salsa ingredients.
@@ -462,14 +480,13 @@ struct ModuleNameIngredient<'db> {
 /// Given a module name and a list of search paths in which to lookup modules,
 /// attempt to resolve the module name
 fn resolve_name(db: &dyn Db, name: &ModuleName) -> Option<(SearchPath, File, ModuleKind)> {
-    let resolver_settings = module_resolution_settings(db);
-    let target_version = resolver_settings.target_version();
+    let program = Program::get(db);
+    let target_version = program.target_version(db);
    let resolver_state = ResolverState::new(db, target_version);
-    let (_, minor_version) = target_version.as_tuple();
    let is_builtin_module =
-        ruff_python_stdlib::sys::is_builtin_module(minor_version, name.as_str());
+        ruff_python_stdlib::sys::is_builtin_module(target_version.minor, name.as_str());

-    for search_path in resolver_settings.search_paths(db) {
+    for search_path in search_paths(db) {
        // When a builtin module is imported, standard module resolution is bypassed:
        // the module name always resolves to the stdlib module,
        // even if there's a module of the same name in the first-party root
@@ -623,6 +640,8 @@ mod tests {
    use crate::module_name::ModuleName;
    use crate::module_resolver::module::ModuleKind;
    use crate::module_resolver::testing::{FileSpec, MockedTypeshed, TestCase, TestCaseBuilder};
+    use crate::ProgramSettings;
+    use crate::PythonVersion;

    use super::*;

@@ -677,7 +696,7 @@ mod tests {
        let TestCase { db, stdlib, .. } = TestCaseBuilder::new()
            .with_src_files(SRC)
            .with_custom_typeshed(TYPESHED)
-            .with_target_version(TargetVersion::Py38)
+            .with_target_version(PythonVersion::PY38)
            .build();

        let builtins_module_name = ModuleName::new_static("builtins").unwrap();
@@ -695,7 +714,7 @@ mod tests {

        let TestCase { db, stdlib, .. } = TestCaseBuilder::new()
            .with_custom_typeshed(TYPESHED)
-            .with_target_version(TargetVersion::Py38)
+            .with_target_version(PythonVersion::PY38)
            .build();

        let functools_module_name = ModuleName::new_static("functools").unwrap();
@@ -748,7 +767,7 @@ mod tests {

        let TestCase { db, stdlib, .. } = TestCaseBuilder::new()
            .with_custom_typeshed(TYPESHED)
-            .with_target_version(TargetVersion::Py38)
+            .with_target_version(PythonVersion::PY38)
            .build();

        let existing_modules = create_module_names(&["asyncio", "functools", "xml.etree"]);
@@ -793,7 +812,7 @@ mod tests {

        let TestCase { db, .. } = TestCaseBuilder::new()
            .with_custom_typeshed(TYPESHED)
-            .with_target_version(TargetVersion::Py38)
+            .with_target_version(PythonVersion::PY38)
            .build();

        let nonexisting_modules = create_module_names(&[
@@ -837,7 +856,7 @@ mod tests {

        let TestCase { db, stdlib, .. } = TestCaseBuilder::new()
            .with_custom_typeshed(TYPESHED)
-            .with_target_version(TargetVersion::Py39)
+            .with_target_version(PythonVersion::PY39)
            .build();

        let existing_modules = create_module_names(&[
@@ -879,7 +898,7 @@ mod tests {

        let TestCase { db, .. } = TestCaseBuilder::new()
            .with_custom_typeshed(TYPESHED)
-            .with_target_version(TargetVersion::Py39)
+            .with_target_version(PythonVersion::PY39)
            .build();

        let nonexisting_modules = create_module_names(&["importlib", "xml", "xml.etree"]);
@@ -903,7 +922,7 @@ mod tests {
        let TestCase { db, src, .. } = TestCaseBuilder::new()
            .with_src_files(SRC)
            .with_custom_typeshed(TYPESHED)
-            .with_target_version(TargetVersion::Py38)
+            .with_target_version(PythonVersion::PY38)
            .build();

        let functools_module_name = ModuleName::new_static("functools").unwrap();
@@ -927,7 +946,7 @@ mod tests {
    fn stdlib_uses_vendored_typeshed_when_no_custom_typeshed_supplied() {
        let TestCase { db, stdlib, .. } = TestCaseBuilder::new()
            .with_vendored_typeshed()
-            .with_target_version(TargetVersion::default())
+            .with_target_version(PythonVersion::default())
            .build();

        let pydoc_data_topics_name = ModuleName::new_static("pydoc_data.topics").unwrap();
@@ -1143,7 +1162,7 @@ mod tests {
    fn symlink() -> anyhow::Result<()> {
        use anyhow::Context;

-        use ruff_db::program::Program;
+        use crate::program::Program;
        use ruff_db::system::{OsSystem, SystemPath};

        use crate::db::tests::TestDb;
@@ -1173,14 +1192,19 @@ mod tests {
        std::fs::write(foo.as_std_path(), "")?;
        std::os::unix::fs::symlink(foo.as_std_path(), bar.as_std_path())?;

-        let search_paths = SearchPathSettings {
-            extra_paths: vec![],
-            src_root: src.clone(),
-            custom_typeshed: Some(custom_typeshed.clone()),
-            site_packages: vec![site_packages],
-        };
-
-        Program::new(&db, TargetVersion::Py38, search_paths);
+        Program::from_settings(
+            &db,
+            ProgramSettings {
+                target_version: PythonVersion::PY38,
+                search_paths: SearchPathSettings {
+                    extra_paths: vec![],
+                    src_root: src.clone(),
+                    custom_typeshed: Some(custom_typeshed.clone()),
+                    site_packages: vec![site_packages],
+                },
+            },
+        )
+        .context("Invalid program settings")?;

        let foo_module = resolve_module(&db, ModuleName::new_static("foo").unwrap()).unwrap();
        let bar_module = resolve_module(&db, ModuleName::new_static("bar").unwrap()).unwrap();
@@ -1214,7 +1238,7 @@ mod tests {
    fn deleting_an_unrelated_file_doesnt_change_module_resolution() {
        let TestCase { mut db, src, .. } = TestCaseBuilder::new()
            .with_src_files(&[("foo.py", "x = 1"), ("bar.py", "x = 2")])
-            .with_target_version(TargetVersion::Py38)
+            .with_target_version(PythonVersion::PY38)
            .build();

        let foo_module_name = ModuleName::new_static("foo").unwrap();
@@ -1302,7 +1326,7 @@ mod tests {
            ..
        } = TestCaseBuilder::new()
            .with_custom_typeshed(TYPESHED)
-            .with_target_version(TargetVersion::Py38)
+            .with_target_version(PythonVersion::PY38)
            .build();

        let functools_module_name = ModuleName::new_static("functools").unwrap();
@@ -1350,7 +1374,7 @@ mod tests {
            ..
        } = TestCaseBuilder::new()
            .with_custom_typeshed(TYPESHED)
-            .with_target_version(TargetVersion::Py38)
+            .with_target_version(PythonVersion::PY38)
            .build();

        let functools_module_name = ModuleName::new_static("functools").unwrap();
@@ -1390,7 +1414,7 @@ mod tests {
        } = TestCaseBuilder::new()
            .with_src_files(SRC)
            .with_custom_typeshed(TYPESHED)
-            .with_target_version(TargetVersion::Py38)
+            .with_target_version(PythonVersion::PY38)
            .build();

        let functools_module_name = ModuleName::new_static("functools").unwrap();
@@ -1644,8 +1668,7 @@ not_a_directory
            .with_site_packages_files(&[("_foo.pth", "/src")])
            .build();

-        let search_paths: Vec<&SearchPath> =
-            module_resolution_settings(&db).search_paths(&db).collect();
+        let search_paths: Vec<&SearchPath> = search_paths(&db).collect();

        assert!(search_paths.contains(
            &&SearchPath::first_party(db.system(), SystemPathBuf::from("/src")).unwrap()
@@ -1674,16 +1697,19 @@ not_a_directory
        ])
        .unwrap();

-        Program::new(
+        Program::from_settings(
            &db,
-            TargetVersion::default(),
-            SearchPathSettings {
-                extra_paths: vec![],
-                src_root: SystemPathBuf::from("/src"),
-                custom_typeshed: None,
-                site_packages: vec![venv_site_packages, system_site_packages],
+            ProgramSettings {
+                target_version: PythonVersion::default(),
+                search_paths: SearchPathSettings {
+                    extra_paths: vec![],
+                    src_root: SystemPathBuf::from("/src"),
+                    custom_typeshed: None,
+                    site_packages: vec![venv_site_packages, system_site_packages],
+                },
            },
-        );
+        )
+        .expect("Valid program settings");

        // The editable installs discovered from the `.pth` file in the first `site-packages` directory
        // take precedence over the second `site-packages` directory...
--- a/crates/red_knot_python_semantic/src/module_resolver/state.rs
+++ b/crates/red_knot_python_semantic/src/module_resolver/state.rs
@@ -1,17 +1,17 @@
-use ruff_db::program::TargetVersion;
 use ruff_db::vendored::VendoredFileSystem;

 use super::typeshed::LazyTypeshedVersions;
 use crate::db::Db;
+use crate::python_version::PythonVersion;

 pub(crate) struct ResolverState<'db> {
    pub(crate) db: &'db dyn Db,
    pub(crate) typeshed_versions: LazyTypeshedVersions<'db>,
-    pub(crate) target_version: TargetVersion,
+    pub(crate) target_version: PythonVersion,
 }

 impl<'db> ResolverState<'db> {
-    pub(crate) fn new(db: &'db dyn Db, target_version: TargetVersion) -> Self {
+    pub(crate) fn new(db: &'db dyn Db, target_version: PythonVersion) -> Self {
        Self {
            db,
            typeshed_versions: LazyTypeshedVersions::new(),
--- a/crates/red_knot_python_semantic/src/module_resolver/testing.rs
+++ b/crates/red_knot_python_semantic/src/module_resolver/testing.rs
@@ -1,8 +1,10 @@
-use ruff_db::program::{Program, SearchPathSettings, TargetVersion};
 use ruff_db::system::{DbWithTestSystem, SystemPath, SystemPathBuf};
 use ruff_db::vendored::VendoredPathBuf;

 use crate::db::tests::TestDb;
+use crate::program::{Program, SearchPathSettings};
+use crate::python_version::PythonVersion;
+use crate::ProgramSettings;

 /// A test case for the module resolver.
 ///
@@ -16,7 +18,7 @@ pub(crate) struct TestCase<T> {
    // so this is a single directory instead of a `Vec` of directories,
    // like it is in `ruff_db::Program`.
    pub(crate) site_packages: SystemPathBuf,
-    pub(crate) target_version: TargetVersion,
+    pub(crate) target_version: PythonVersion,
 }

 /// A `(file_name, file_contents)` tuple
@@ -98,7 +100,7 @@ pub(crate) struct UnspecifiedTypeshed;
 /// to `()`.
 pub(crate) struct TestCaseBuilder<T> {
    typeshed_option: T,
-    target_version: TargetVersion,
+    target_version: PythonVersion,
    first_party_files: Vec<FileSpec>,
    site_packages_files: Vec<FileSpec>,
 }
@@ -117,7 +119,7 @@ impl<T> TestCaseBuilder<T> {
    }

    /// Specify the target Python version the module resolver should assume
-    pub(crate) fn with_target_version(mut self, target_version: TargetVersion) -> Self {
+    pub(crate) fn with_target_version(mut self, target_version: PythonVersion) -> Self {
        self.target_version = target_version;
        self
    }
@@ -144,7 +146,7 @@ impl TestCaseBuilder<UnspecifiedTypeshed> {
    pub(crate) fn new() -> TestCaseBuilder<UnspecifiedTypeshed> {
        Self {
            typeshed_option: UnspecifiedTypeshed,
-            target_version: TargetVersion::default(),
+            target_version: PythonVersion::default(),
            first_party_files: vec![],
            site_packages_files: vec![],
        }
@@ -219,16 +221,19 @@ impl TestCaseBuilder<MockedTypeshed> {
        let src = Self::write_mock_directory(&mut db, "/src", first_party_files);
        let typeshed = Self::build_typeshed_mock(&mut db, &typeshed_option);

-        Program::new(
+        Program::from_settings(
            &db,
-            target_version,
-            SearchPathSettings {
-                extra_paths: vec![],
-                src_root: src.clone(),
-                custom_typeshed: Some(typeshed.clone()),
-                site_packages: vec![site_packages.clone()],
+            ProgramSettings {
+                target_version,
+                search_paths: SearchPathSettings {
+                    extra_paths: vec![],
+                    src_root: src.clone(),
+                    custom_typeshed: Some(typeshed.clone()),
+                    site_packages: vec![site_packages.clone()],
+                },
            },
-        );
+        )
+        .expect("Valid program settings");

        TestCase {
            db,
@@ -272,16 +277,19 @@ impl TestCaseBuilder<VendoredTypeshed> {
            Self::write_mock_directory(&mut db, "/site-packages", site_packages_files);
        let src = Self::write_mock_directory(&mut db, "/src", first_party_files);

-        Program::new(
+        Program::from_settings(
            &db,
-            target_version,
-            SearchPathSettings {
-                extra_paths: vec![],
-                src_root: src.clone(),
-                custom_typeshed: None,
-                site_packages: vec![site_packages.clone()],
+            ProgramSettings {
+                target_version,
+                search_paths: SearchPathSettings {
+                    extra_paths: vec![],
+                    src_root: src.clone(),
+                    custom_typeshed: None,
+                    site_packages: vec![site_packages.clone()],
+                },
            },
-        );
+        )
+        .expect("Valid search path settings");

        TestCase {
            db,
--- a/crates/red_knot_python_semantic/src/module_resolver/typeshed/versions.rs
+++ b/crates/red_knot_python_semantic/src/module_resolver/typeshed/versions.rs
@@ -6,16 +6,15 @@ use std::ops::{RangeFrom, RangeInclusive};
 use std::str::FromStr;

 use once_cell::sync::Lazy;
-use ruff_db::program::TargetVersion;
 use ruff_db::system::SystemPath;
 use rustc_hash::FxHashMap;

 use ruff_db::files::{system_path_to_file, File};

+use super::vendored::vendored_typeshed_stubs;
 use crate::db::Db;
 use crate::module_name::ModuleName;
-
-use super::vendored::vendored_typeshed_stubs;
+use crate::python_version::PythonVersion;

 #[derive(Debug)]
 pub(crate) struct LazyTypeshedVersions<'db>(OnceCell<&'db TypeshedVersions>);
@@ -44,7 +43,7 @@ impl<'db> LazyTypeshedVersions<'db> {
        db: &'db dyn Db,
        module: &ModuleName,
        stdlib_root: Option<&SystemPath>,
-        target_version: TargetVersion,
+        target_version: PythonVersion,
    ) -> TypeshedVersionsQueryResult {
        let versions = self.0.get_or_init(|| {
            let versions_path = if let Some(system_path) = stdlib_root {
@@ -64,7 +63,7 @@ impl<'db> LazyTypeshedVersions<'db> {
            // Unwrapping here is not correct...
            parse_typeshed_versions(db, versions_file).as_ref().unwrap()
        });
-        versions.query_module(module, PyVersion::from(target_version))
+        versions.query_module(module, target_version)
    }
 }

@@ -178,7 +177,7 @@ impl TypeshedVersions {
    fn query_module(
        &self,
        module: &ModuleName,
-        target_version: PyVersion,
+        target_version: PythonVersion,
    ) -> TypeshedVersionsQueryResult {
        if let Some(range) = self.exact(module) {
            if range.contains(target_version) {
@@ -323,13 +322,13 @@ impl fmt::Display for TypeshedVersions {

 #[derive(Debug, Clone, Eq, PartialEq, Hash)]
 enum PyVersionRange {
-    AvailableFrom(RangeFrom<PyVersion>),
-    AvailableWithin(RangeInclusive<PyVersion>),
+    AvailableFrom(RangeFrom<PythonVersion>),
+    AvailableWithin(RangeInclusive<PythonVersion>),
 }

 impl PyVersionRange {
    #[must_use]
-    fn contains(&self, version: PyVersion) -> bool {
+    fn contains(&self, version: PythonVersion) -> bool {
        match self {
            Self::AvailableFrom(inner) => inner.contains(&version),
            Self::AvailableWithin(inner) => inner.contains(&version),
@@ -343,9 +342,14 @@ impl FromStr for PyVersionRange {
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        let mut parts = s.split('-').map(str::trim);
        match (parts.next(), parts.next(), parts.next()) {
-            (Some(lower), Some(""), None) => Ok(Self::AvailableFrom((lower.parse()?)..)),
+            (Some(lower), Some(""), None) => {
+                let lower = PythonVersion::from_versions_file_string(lower)?;
+                Ok(Self::AvailableFrom(lower..))
+            }
            (Some(lower), Some(upper), None) => {
-                Ok(Self::AvailableWithin((lower.parse()?)..=(upper.parse()?)))
+                let lower = PythonVersion::from_versions_file_string(lower)?;
+                let upper = PythonVersion::from_versions_file_string(upper)?;
+                Ok(Self::AvailableWithin(lower..=upper))
            }
            _ => Err(TypeshedVersionsParseErrorKind::UnexpectedNumberOfHyphens),
        }
@@ -363,74 +367,20 @@ impl fmt::Display for PyVersionRange {
    }
 }

-#[derive(Debug, Clone, Copy, Eq, PartialEq, Ord, PartialOrd, Hash)]
-struct PyVersion {
-    major: u8,
-    minor: u8,
-}
-
-impl FromStr for PyVersion {
-    type Err = TypeshedVersionsParseErrorKind;
-
-    fn from_str(s: &str) -> Result<Self, Self::Err> {
+impl PythonVersion {
+    fn from_versions_file_string(s: &str) -> Result<Self, TypeshedVersionsParseErrorKind> {
        let mut parts = s.split('.').map(str::trim);
        let (Some(major), Some(minor), None) = (parts.next(), parts.next(), parts.next()) else {
            return Err(TypeshedVersionsParseErrorKind::UnexpectedNumberOfPeriods(
                s.to_string(),
            ));
        };
-        let major = match u8::from_str(major) {
-            Ok(major) => major,
-            Err(err) => {
-                return Err(TypeshedVersionsParseErrorKind::IntegerParsingFailure {
-                    version: s.to_string(),
-                    err,
-                })
+        PythonVersion::try_from((major, minor)).map_err(|int_parse_error| {
+            TypeshedVersionsParseErrorKind::IntegerParsingFailure {
+                version: s.to_string(),
+                err: int_parse_error,
            }
-        };
-        let minor = match u8::from_str(minor) {
-            Ok(minor) => minor,
-            Err(err) => {
-                return Err(TypeshedVersionsParseErrorKind::IntegerParsingFailure {
-                    version: s.to_string(),
-                    err,
-                })
-            }
-        };
-        Ok(Self { major, minor })
-    }
-}
-
-impl fmt::Display for PyVersion {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        let PyVersion { major, minor } = self;
-        write!(f, "{major}.{minor}")
-    }
-}
-
-impl From<TargetVersion> for PyVersion {
-    fn from(value: TargetVersion) -> Self {
-        match value {
-            TargetVersion::Py37 => PyVersion { major: 3, minor: 7 },
-            TargetVersion::Py38 => PyVersion { major: 3, minor: 8 },
-            TargetVersion::Py39 => PyVersion { major: 3, minor: 9 },
-            TargetVersion::Py310 => PyVersion {
-                major: 3,
-                minor: 10,
-            },
-            TargetVersion::Py311 => PyVersion {
-                major: 3,
-                minor: 11,
-            },
-            TargetVersion::Py312 => PyVersion {
-                major: 3,
-                minor: 12,
-            },
-            TargetVersion::Py313 => PyVersion {
-                major: 3,
-                minor: 13,
-            },
-        }
+        })
    }
 }

@@ -440,7 +390,6 @@ mod tests {
    use std::path::Path;

    use insta::assert_snapshot;
-    use ruff_db::program::TargetVersion;

    use super::*;

@@ -478,27 +427,27 @@ mod tests {

        assert!(versions.contains_exact(&asyncio));
        assert_eq!(
-            versions.query_module(&asyncio, TargetVersion::Py310.into()),
+            versions.query_module(&asyncio, PythonVersion::PY310),
            TypeshedVersionsQueryResult::Exists
        );

        assert!(versions.contains_exact(&asyncio_staggered));
        assert_eq!(
-            versions.query_module(&asyncio_staggered, TargetVersion::Py38.into()),
+            versions.query_module(&asyncio_staggered, PythonVersion::PY38),
            TypeshedVersionsQueryResult::Exists
        );
        assert_eq!(
-            versions.query_module(&asyncio_staggered, TargetVersion::Py37.into()),
+            versions.query_module(&asyncio_staggered, PythonVersion::PY37),
            TypeshedVersionsQueryResult::DoesNotExist
        );

        assert!(versions.contains_exact(&audioop));
        assert_eq!(
-            versions.query_module(&audioop, TargetVersion::Py312.into()),
+            versions.query_module(&audioop, PythonVersion::PY312),
            TypeshedVersionsQueryResult::Exists
        );
        assert_eq!(
-            versions.query_module(&audioop, TargetVersion::Py313.into()),
+            versions.query_module(&audioop, PythonVersion::PY313),
            TypeshedVersionsQueryResult::DoesNotExist
        );
    }
@@ -590,15 +539,15 @@ foo: 3.8-   # trailing comment

        assert!(parsed_versions.contains_exact(&bar));
        assert_eq!(
-            parsed_versions.query_module(&bar, TargetVersion::Py37.into()),
+            parsed_versions.query_module(&bar, PythonVersion::PY37),
            TypeshedVersionsQueryResult::Exists
        );
        assert_eq!(
-            parsed_versions.query_module(&bar, TargetVersion::Py310.into()),
+            parsed_versions.query_module(&bar, PythonVersion::PY310),
            TypeshedVersionsQueryResult::Exists
        );
        assert_eq!(
-            parsed_versions.query_module(&bar, TargetVersion::Py311.into()),
+            parsed_versions.query_module(&bar, PythonVersion::PY311),
            TypeshedVersionsQueryResult::DoesNotExist
        );
    }
@@ -610,15 +559,15 @@ foo: 3.8-   # trailing comment

        assert!(parsed_versions.contains_exact(&foo));
        assert_eq!(
-            parsed_versions.query_module(&foo, TargetVersion::Py37.into()),
+            parsed_versions.query_module(&foo, PythonVersion::PY37),
            TypeshedVersionsQueryResult::DoesNotExist
        );
        assert_eq!(
-            parsed_versions.query_module(&foo, TargetVersion::Py38.into()),
+            parsed_versions.query_module(&foo, PythonVersion::PY38),
            TypeshedVersionsQueryResult::Exists
        );
        assert_eq!(
-            parsed_versions.query_module(&foo, TargetVersion::Py311.into()),
+            parsed_versions.query_module(&foo, PythonVersion::PY311),
            TypeshedVersionsQueryResult::Exists
        );
    }
@@ -630,15 +579,15 @@ foo: 3.8-   # trailing comment

        assert!(parsed_versions.contains_exact(&bar_baz));
        assert_eq!(
-            parsed_versions.query_module(&bar_baz, TargetVersion::Py37.into()),
+            parsed_versions.query_module(&bar_baz, PythonVersion::PY37),
            TypeshedVersionsQueryResult::Exists
        );
        assert_eq!(
-            parsed_versions.query_module(&bar_baz, TargetVersion::Py39.into()),
+            parsed_versions.query_module(&bar_baz, PythonVersion::PY39),
            TypeshedVersionsQueryResult::Exists
        );
        assert_eq!(
-            parsed_versions.query_module(&bar_baz, TargetVersion::Py310.into()),
+            parsed_versions.query_module(&bar_baz, PythonVersion::PY310),
            TypeshedVersionsQueryResult::DoesNotExist
        );
    }
@@ -650,15 +599,15 @@ foo: 3.8-   # trailing comment

        assert!(!parsed_versions.contains_exact(&bar_eggs));
        assert_eq!(
-            parsed_versions.query_module(&bar_eggs, TargetVersion::Py37.into()),
+            parsed_versions.query_module(&bar_eggs, PythonVersion::PY37),
            TypeshedVersionsQueryResult::MaybeExists
        );
        assert_eq!(
-            parsed_versions.query_module(&bar_eggs, TargetVersion::Py310.into()),
+            parsed_versions.query_module(&bar_eggs, PythonVersion::PY310),
            TypeshedVersionsQueryResult::MaybeExists
        );
        assert_eq!(
-            parsed_versions.query_module(&bar_eggs, TargetVersion::Py311.into()),
+            parsed_versions.query_module(&bar_eggs, PythonVersion::PY311),
            TypeshedVersionsQueryResult::DoesNotExist
        );
    }
@@ -670,11 +619,11 @@ foo: 3.8-   # trailing comment

        assert!(!parsed_versions.contains_exact(&spam));
        assert_eq!(
-            parsed_versions.query_module(&spam, TargetVersion::Py37.into()),
+            parsed_versions.query_module(&spam, PythonVersion::PY37),
            TypeshedVersionsQueryResult::DoesNotExist
        );
        assert_eq!(
-            parsed_versions.query_module(&spam, TargetVersion::Py313.into()),
+            parsed_versions.query_module(&spam, PythonVersion::PY313),
            TypeshedVersionsQueryResult::DoesNotExist
        );
    }
--- a/crates/red_knot_python_semantic/src/program.rs
+++ b/crates/red_knot_python_semantic/src/program.rs
@@ -0,0 +1,78 @@
+use crate::python_version::PythonVersion;
+use anyhow::Context;
+use salsa::Durability;
+use salsa::Setter;
+
+use ruff_db::system::SystemPathBuf;
+
+use crate::module_resolver::SearchPaths;
+use crate::Db;
+
+#[salsa::input(singleton)]
+pub struct Program {
+    pub target_version: PythonVersion,
+
+    #[default]
+    #[return_ref]
+    pub(crate) search_paths: SearchPaths,
+}
+
+impl Program {
+    pub fn from_settings(db: &dyn Db, settings: ProgramSettings) -> anyhow::Result<Self> {
+        let ProgramSettings {
+            target_version,
+            search_paths,
+        } = settings;
+
+        tracing::info!("Target version: {target_version}");
+
+        let search_paths = SearchPaths::from_settings(db, search_paths)
+            .with_context(|| "Invalid search path settings")?;
+
+        Ok(Program::builder(settings.target_version)
+            .durability(Durability::HIGH)
+            .search_paths(search_paths)
+            .new(db))
+    }
+
+    pub fn update_search_paths(
+        &self,
+        db: &mut dyn Db,
+        search_path_settings: SearchPathSettings,
+    ) -> anyhow::Result<()> {
+        let search_paths = SearchPaths::from_settings(db, search_path_settings)?;
+
+        if self.search_paths(db) != &search_paths {
+            tracing::debug!("Update search paths");
+            self.set_search_paths(db).to(search_paths);
+        }
+
+        Ok(())
+    }
+}
+
+#[derive(Debug, Eq, PartialEq)]
+pub struct ProgramSettings {
+    pub target_version: PythonVersion,
+    pub search_paths: SearchPathSettings,
+}
+
+/// Configures the search paths for module resolution.
+#[derive(Eq, PartialEq, Debug, Clone, Default)]
+pub struct SearchPathSettings {
+    /// List of user-provided paths that should take first priority in the module resolution.
+    /// Examples in other type checkers are mypy's MYPYPATH environment variable,
+    /// or pyright's stubPath configuration setting.
+    pub extra_paths: Vec<SystemPathBuf>,
+
+    /// The root of the workspace, used for finding first-party modules.
+    pub src_root: SystemPathBuf,
+
+    /// Optional path to a "custom typeshed" directory on disk for us to use for standard-library types.
+    /// If this is not provided, we will fallback to our vendored typeshed stubs for the stdlib,
+    /// bundled as a zip file in the binary
+    pub custom_typeshed: Option<SystemPathBuf>,
+
+    /// The path to the user's `site-packages` directory, where third-party packages from ``PyPI`` are installed.
+    pub site_packages: Vec<SystemPathBuf>,
+}
--- a/crates/red_knot_python_semantic/src/python_version.rs
+++ b/crates/red_knot_python_semantic/src/python_version.rs
@@ -0,0 +1,62 @@
+use std::fmt;
+
+/// Representation of a Python version.
+///
+/// Unlike the `TargetVersion` enums in the CLI crates,
+/// this does not necessarily represent a Python version that we actually support.
+#[derive(Debug, Clone, Copy, Eq, PartialEq, Ord, PartialOrd, Hash)]
+pub struct PythonVersion {
+    pub major: u8,
+    pub minor: u8,
+}
+
+impl PythonVersion {
+    pub const PY37: PythonVersion = PythonVersion { major: 3, minor: 7 };
+    pub const PY38: PythonVersion = PythonVersion { major: 3, minor: 8 };
+    pub const PY39: PythonVersion = PythonVersion { major: 3, minor: 9 };
+    pub const PY310: PythonVersion = PythonVersion {
+        major: 3,
+        minor: 10,
+    };
+    pub const PY311: PythonVersion = PythonVersion {
+        major: 3,
+        minor: 11,
+    };
+    pub const PY312: PythonVersion = PythonVersion {
+        major: 3,
+        minor: 12,
+    };
+    pub const PY313: PythonVersion = PythonVersion {
+        major: 3,
+        minor: 13,
+    };
+
+    pub fn free_threaded_build_available(self) -> bool {
+        self >= PythonVersion::PY313
+    }
+}
+
+impl Default for PythonVersion {
+    fn default() -> Self {
+        Self::PY38
+    }
+}
+
+impl TryFrom<(&str, &str)> for PythonVersion {
+    type Error = std::num::ParseIntError;
+
+    fn try_from(value: (&str, &str)) -> Result<Self, Self::Error> {
+        let (major, minor) = value;
+        Ok(Self {
+            major: major.parse()?,
+            minor: minor.parse()?,
+        })
+    }
+}
+
+impl fmt::Display for PythonVersion {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let PythonVersion { major, minor } = self;
+        write!(f, "{major}.{minor}")
+    }
+}
--- a/crates/red_knot_python_semantic/src/semantic_index.rs
+++ b/crates/red_knot_python_semantic/src/semantic_index.rs
@@ -89,8 +89,6 @@ pub(crate) struct SemanticIndex<'db> {
    scopes: IndexVec<FileScopeId, Scope>,

    /// Map expressions to their corresponding scope.
-    /// We can't use [`ExpressionId`] here, because the challenge is how to get from
-    /// an [`ast::Expr`] to an [`ExpressionId`] (which requires knowing the scope).
    scopes_by_expression: FxHashMap<ExpressionNodeKey, FileScopeId>,

    /// Map from a node creating a definition to its definition.
@@ -118,7 +116,7 @@ pub(crate) struct SemanticIndex<'db> {
 impl<'db> SemanticIndex<'db> {
    /// Returns the symbol table for a specific scope.
    ///
-    /// Use the Salsa cached [`symbol_table`] query if you only need the
+    /// Use the Salsa cached [`symbol_table()`] query if you only need the
    /// symbol table for a single scope.
    pub(super) fn symbol_table(&self, scope_id: FileScopeId) -> Arc<SymbolTable> {
        self.symbol_tables[scope_id].clone()
@@ -126,9 +124,9 @@ impl<'db> SemanticIndex<'db> {

    /// Returns the use-def map for a specific scope.
    ///
-    /// Use the Salsa cached [`use_def_map`] query if you only need the
+    /// Use the Salsa cached [`use_def_map()`] query if you only need the
    /// use-def map for a single scope.
-    pub(super) fn use_def_map(&self, scope_id: FileScopeId) -> Arc<UseDefMap> {
+    pub(super) fn use_def_map(&self, scope_id: FileScopeId) -> Arc<UseDefMap<'db>> {
        self.use_def_maps[scope_id].clone()
    }

@@ -309,10 +307,11 @@ mod tests {
    use ruff_db::parsed::parsed_module;
    use ruff_db::system::DbWithTestSystem;
    use ruff_python_ast as ast;
+    use ruff_text_size::{Ranged, TextRange};

    use crate::db::tests::TestDb;
    use crate::semantic_index::ast_ids::HasScopedUseId;
-    use crate::semantic_index::definition::DefinitionKind;
+    use crate::semantic_index::definition::{DefinitionKind, DefinitionNode};
    use crate::semantic_index::symbol::{FileScopeId, Scope, ScopeKind, SymbolTable};
    use crate::semantic_index::{global_scope, semantic_index, symbol_table, use_def_map};
    use crate::Db;
@@ -375,10 +374,11 @@ mod tests {
        let foo = global_table.symbol_id_by_name("foo").unwrap();

        let use_def = use_def_map(&db, scope);
-        let [definition] = use_def.public_definitions(foo) else {
-            panic!("expected one definition");
-        };
-        assert!(matches!(definition.node(&db), DefinitionKind::Import(_)));
+        let definition = use_def.public_definition(foo).unwrap();
+        assert!(matches!(
+            definition.kind(&db),
+            DefinitionKind::Node(DefinitionNode::Import(_))
+        ));
    }

    #[test]
@@ -412,16 +412,16 @@ mod tests {
        );

        let use_def = use_def_map(&db, scope);
-        let [definition] = use_def.public_definitions(
-            global_table
-                .symbol_id_by_name("foo")
-                .expect("symbol to exist"),
-        ) else {
-            panic!("expected one definition");
-        };
+        let definition = use_def
+            .public_definition(
+                global_table
+                    .symbol_id_by_name("foo")
+                    .expect("symbol to exist"),
+            )
+            .unwrap();
        assert!(matches!(
-            definition.node(&db),
-            DefinitionKind::ImportFrom(_)
+            definition.kind(&db),
+            DefinitionKind::Node(DefinitionNode::ImportFrom(_))
        ));
    }

@@ -439,14 +439,12 @@ mod tests {
            "a symbol used but not defined in a scope should have only the used flag"
        );
        let use_def = use_def_map(&db, scope);
-        let [definition] =
-            use_def.public_definitions(global_table.symbol_id_by_name("x").expect("symbol exists"))
-        else {
-            panic!("expected one definition");
-        };
+        let definition = use_def
+            .public_definition(global_table.symbol_id_by_name("x").expect("symbol exists"))
+            .unwrap();
        assert!(matches!(
-            definition.node(&db),
-            DefinitionKind::Assignment(_)
+            definition.kind(&db),
+            DefinitionKind::Node(DefinitionNode::Assignment(_))
        ));
    }

@@ -478,14 +476,12 @@ y = 2
        assert_eq!(names(&class_table), vec!["x"]);

        let use_def = index.use_def_map(class_scope_id);
-        let [definition] =
-            use_def.public_definitions(class_table.symbol_id_by_name("x").expect("symbol exists"))
-        else {
-            panic!("expected one definition");
-        };
+        let definition = use_def
+            .public_definition(class_table.symbol_id_by_name("x").expect("symbol exists"))
+            .unwrap();
        assert!(matches!(
-            definition.node(&db),
-            DefinitionKind::Assignment(_)
+            definition.kind(&db),
+            DefinitionKind::Node(DefinitionNode::Assignment(_))
        ));
    }

@@ -516,19 +512,151 @@ y = 2
        assert_eq!(names(&function_table), vec!["x"]);

        let use_def = index.use_def_map(function_scope_id);
-        let [definition] = use_def.public_definitions(
-            function_table
-                .symbol_id_by_name("x")
-                .expect("symbol exists"),
-        ) else {
-            panic!("expected one definition");
-        };
+        let definition = use_def
+            .public_definition(
+                function_table
+                    .symbol_id_by_name("x")
+                    .expect("symbol exists"),
+            )
+            .unwrap();
        assert!(matches!(
-            definition.node(&db),
-            DefinitionKind::Assignment(_)
+            definition.kind(&db),
+            DefinitionKind::Node(DefinitionNode::Assignment(_))
        ));
    }

+    /// Test case to validate that the comprehension scope is correctly identified and that the target
+    /// variable is defined only in the comprehension scope and not in the global scope.
+    #[test]
+    fn comprehension_scope() {
+        let TestCase { db, file } = test_case(
+            "
+[x for x in iter1]
+",
+        );
+
+        let index = semantic_index(&db, file);
+        let global_table = index.symbol_table(FileScopeId::global());
+
+        assert_eq!(names(&global_table), vec!["iter1"]);
+
+        let [(comprehension_scope_id, comprehension_scope)] = index
+            .child_scopes(FileScopeId::global())
+            .collect::<Vec<_>>()[..]
+        else {
+            panic!("expected one child scope")
+        };
+
+        assert_eq!(comprehension_scope.kind(), ScopeKind::Comprehension);
+        assert_eq!(
+            comprehension_scope_id.to_scope_id(&db, file).name(&db),
+            "<listcomp>"
+        );
+
+        let comprehension_symbol_table = index.symbol_table(comprehension_scope_id);
+
+        assert_eq!(names(&comprehension_symbol_table), vec!["x"]);
+    }
+
+    /// Test case to validate that the `x` variable used in the comprehension is referencing the
+    /// `x` variable defined by the inner generator (`for x in iter2`) and not the outer one.
+    #[test]
+    fn multiple_generators() {
+        let TestCase { db, file } = test_case(
+            "
+[x for x in iter1 for x in iter2]
+",
+        );
+
+        let index = semantic_index(&db, file);
+        let [(comprehension_scope_id, _)] = index
+            .child_scopes(FileScopeId::global())
+            .collect::<Vec<_>>()[..]
+        else {
+            panic!("expected one child scope")
+        };
+
+        let use_def = index.use_def_map(comprehension_scope_id);
+
+        let module = parsed_module(&db, file).syntax();
+        let element = module.body[0]
+            .as_expr_stmt()
+            .unwrap()
+            .value
+            .as_list_comp_expr()
+            .unwrap()
+            .elt
+            .as_name_expr()
+            .unwrap();
+        let element_use_id =
+            element.scoped_use_id(&db, comprehension_scope_id.to_scope_id(&db, file));
+
+        let definition = use_def.definition_for_use(element_use_id).unwrap();
+        let DefinitionKind::Node(DefinitionNode::Comprehension(comprehension)) =
+            definition.kind(&db)
+        else {
+            panic!("expected generator definition")
+        };
+        let ast::Comprehension { target, .. } = comprehension.node();
+        let name = target.as_name_expr().unwrap().id().as_str();
+
+        assert_eq!(name, "x");
+        assert_eq!(target.range(), TextRange::new(23.into(), 24.into()));
+    }
+
+    /// Test case to validate that the nested comprehension creates a new scope which is a child of
+    /// the outer comprehension scope and the variables are correctly defined in the respective
+    /// scopes.
+    #[test]
+    fn nested_comprehensions() {
+        let TestCase { db, file } = test_case(
+            "
+[{x for x in iter2} for y in iter1]
+",
+        );
+
+        let index = semantic_index(&db, file);
+        let global_table = index.symbol_table(FileScopeId::global());
+
+        assert_eq!(names(&global_table), vec!["iter1"]);
+
+        let [(comprehension_scope_id, comprehension_scope)] = index
+            .child_scopes(FileScopeId::global())
+            .collect::<Vec<_>>()[..]
+        else {
+            panic!("expected one child scope")
+        };
+
+        assert_eq!(comprehension_scope.kind(), ScopeKind::Comprehension);
+        assert_eq!(
+            comprehension_scope_id.to_scope_id(&db, file).name(&db),
+            "<listcomp>"
+        );
+
+        let comprehension_symbol_table = index.symbol_table(comprehension_scope_id);
+
+        assert_eq!(names(&comprehension_symbol_table), vec!["y", "iter2"]);
+
+        let [(inner_comprehension_scope_id, inner_comprehension_scope)] = index
+            .child_scopes(comprehension_scope_id)
+            .collect::<Vec<_>>()[..]
+        else {
+            panic!("expected one inner comprehension scope")
+        };
+
+        assert_eq!(inner_comprehension_scope.kind(), ScopeKind::Comprehension);
+        assert_eq!(
+            inner_comprehension_scope_id
+                .to_scope_id(&db, file)
+                .name(&db),
+            "<setcomp>"
+        );
+
+        let inner_comprehension_symbol_table = index.symbol_table(inner_comprehension_scope_id);
+
+        assert_eq!(names(&inner_comprehension_symbol_table), vec!["x"]);
+    }
+
    #[test]
    fn dupes() {
        let TestCase { db, file } = test_case(
@@ -562,14 +690,17 @@ def func():
        assert_eq!(names(&func2_table), vec!["y"]);

        let use_def = index.use_def_map(FileScopeId::global());
-        let [definition] = use_def.public_definitions(
-            global_table
-                .symbol_id_by_name("func")
-                .expect("symbol exists"),
-        ) else {
-            panic!("expected one definition");
-        };
-        assert!(matches!(definition.node(&db), DefinitionKind::Function(_)));
+        let definition = use_def
+            .public_definition(
+                global_table
+                    .symbol_id_by_name("func")
+                    .expect("symbol exists"),
+            )
+            .unwrap();
+        assert!(matches!(
+            definition.kind(&db),
+            DefinitionKind::Node(DefinitionNode::Function(_))
+        ));
    }

    #[test]
@@ -669,10 +800,9 @@ class C[T]:
        };
        let x_use_id = x_use_expr_name.scoped_use_id(&db, scope);
        let use_def = use_def_map(&db, scope);
-        let [definition] = use_def.use_definitions(x_use_id) else {
-            panic!("expected one definition");
-        };
-        let DefinitionKind::Assignment(assignment) = definition.node(&db) else {
+        let definition = use_def.definition_for_use(x_use_id).unwrap();
+        let DefinitionKind::Node(DefinitionNode::Assignment(assignment)) = definition.kind(&db)
+        else {
            panic!("should be an assignment definition")
        };
        let ast::Expr::NumberLiteral(ast::ExprNumberLiteral {
--- a/crates/red_knot_python_semantic/src/semantic_index/ast_ids.rs
+++ b/crates/red_knot_python_semantic/src/semantic_index/ast_ids.rs
@@ -26,9 +26,9 @@ use crate::Db;
 /// ```
 #[derive(Debug)]
 pub(crate) struct AstIds {
-    /// Maps expressions to their expression id. Uses `NodeKey` because it avoids cloning [`Parsed`].
+    /// Maps expressions to their expression id.
    expressions_map: FxHashMap<ExpressionNodeKey, ScopedExpressionId>,
-    /// Maps expressions which "use" a symbol (that is, [`ExprName`]) to a use id.
+    /// Maps expressions which "use" a symbol (that is, [`ast::ExprName`]) to a use id.
    uses_map: FxHashMap<ExpressionNodeKey, ScopedUseId>,
 }

--- a/crates/red_knot_python_semantic/src/semantic_index/builder.rs
+++ b/crates/red_knot_python_semantic/src/semantic_index/builder.rs
@@ -13,15 +13,15 @@ use crate::ast_node_ref::AstNodeRef;
 use crate::semantic_index::ast_ids::node_key::ExpressionNodeKey;
 use crate::semantic_index::ast_ids::AstIdsBuilder;
 use crate::semantic_index::definition::{
-    AssignmentDefinitionNodeRef, Definition, DefinitionNodeKey, DefinitionNodeRef,
-    ImportFromDefinitionNodeRef,
+    AssignmentDefinitionNodeRef, ComprehensionDefinitionNodeRef, Definition, DefinitionKind,
+    DefinitionNodeKey, DefinitionNodeRef, ImportFromDefinitionNodeRef,
 };
 use crate::semantic_index::expression::Expression;
 use crate::semantic_index::symbol::{
    FileScopeId, NodeWithScopeKey, NodeWithScopeRef, Scope, ScopeId, ScopedSymbolId, SymbolFlags,
    SymbolTableBuilder,
 };
-use crate::semantic_index::use_def::{FlowSnapshot, UseDefMapBuilder};
+use crate::semantic_index::use_def::{BasicBlockId, UseDefMapBuilder};
 use crate::semantic_index::SemanticIndex;
 use crate::Db;

@@ -33,8 +33,8 @@ pub(super) struct SemanticIndexBuilder<'db> {
    scope_stack: Vec<FileScopeId>,
    /// The assignment we're currently visiting.
    current_assignment: Option<CurrentAssignment<'db>>,
-    /// Flow states at each `break` in the current loop.
-    loop_break_states: Vec<FlowSnapshot>,
+    /// Basic block ending at each `break` in the current loop.
+    loop_breaks: Vec<BasicBlockId>,

    // Semantic Index fields
    scopes: IndexVec<FileScopeId, Scope>,
@@ -56,7 +56,7 @@ impl<'db> SemanticIndexBuilder<'db> {
            module: parsed,
            scope_stack: Vec::new(),
            current_assignment: None,
-            loop_break_states: vec![],
+            loop_breaks: vec![],

            scopes: IndexVec::new(),
            symbol_tables: IndexVec::new(),
@@ -98,7 +98,8 @@ impl<'db> SemanticIndexBuilder<'db> {

        let file_scope_id = self.scopes.push(scope);
        self.symbol_tables.push(SymbolTableBuilder::new());
-        self.use_def_maps.push(UseDefMapBuilder::new());
+        self.use_def_maps
+            .push(UseDefMapBuilder::new(self.db, self.file, file_scope_id));
        let ast_id_scope = self.ast_ids.push(AstIdsBuilder::new());

        #[allow(unsafe_code)]
@@ -132,41 +133,50 @@ impl<'db> SemanticIndexBuilder<'db> {
        &mut self.symbol_tables[scope_id]
    }

-    fn current_use_def_map_mut(&mut self) -> &mut UseDefMapBuilder<'db> {
+    fn current_use_def_map(&mut self) -> &mut UseDefMapBuilder<'db> {
        let scope_id = self.current_scope();
        &mut self.use_def_maps[scope_id]
    }

-    fn current_use_def_map(&self) -> &UseDefMapBuilder<'db> {
-        let scope_id = self.current_scope();
-        &self.use_def_maps[scope_id]
-    }
-
    fn current_ast_ids(&mut self) -> &mut AstIdsBuilder {
        let scope_id = self.current_scope();
        &mut self.ast_ids[scope_id]
    }

-    fn flow_snapshot(&self) -> FlowSnapshot {
-        self.current_use_def_map().snapshot()
+    /// Start a new basic block and return the previous block's ID.
+    fn next_block(&mut self) -> BasicBlockId {
+        self.current_use_def_map().next_block(/* sealed */ true)
    }

-    fn flow_restore(&mut self, state: FlowSnapshot) {
-        self.current_use_def_map_mut().restore(state);
+    /// Start a new unsealed basic block and return the previous block's ID.
+    fn next_block_unsealed(&mut self) -> BasicBlockId {
+        self.current_use_def_map().next_block(/* sealed */ false)
    }

-    fn flow_merge(&mut self, state: &FlowSnapshot) {
-        self.current_use_def_map_mut().merge(state);
+    /// Seal an unsealed basic block.
+    fn seal_block(&mut self) {
+        self.current_use_def_map().seal_current_block();
+    }
+
+    /// Start a new basic block with the given block as predecessor.
+    fn new_block_from(&mut self, predecessor: BasicBlockId) {
+        self.current_use_def_map()
+            .new_block_from(predecessor, /* sealed */ true);
+    }
+
+    /// Add a predecessor to the current block.
+    fn merge_block(&mut self, predecessor: BasicBlockId) {
+        self.current_use_def_map().merge_block(predecessor);
+    }
+
+    /// Add predecessors to the current block.
+    fn merge_blocks(&mut self, predecessors: Vec<BasicBlockId>) {
+        self.current_use_def_map().merge_blocks(predecessors);
    }

    fn add_or_update_symbol(&mut self, name: Name, flags: SymbolFlags) -> ScopedSymbolId {
        let symbol_table = self.current_symbol_table();
-        let (symbol_id, added) = symbol_table.add_or_update_symbol(name, flags);
-        if added {
-            let use_def_map = self.current_use_def_map_mut();
-            use_def_map.add_symbol(symbol_id);
-        }
-        symbol_id
+        symbol_table.add_or_update_symbol(name, flags)
    }

    fn add_definition<'a>(
@@ -174,22 +184,20 @@ impl<'db> SemanticIndexBuilder<'db> {
        symbol: ScopedSymbolId,
        definition_node: impl Into<DefinitionNodeRef<'a>>,
    ) -> Definition<'db> {
-        let definition_node = definition_node.into();
+        let definition_node: DefinitionNodeRef<'_> = definition_node.into();
        let definition = Definition::new(
            self.db,
            self.file,
            self.current_scope(),
            symbol,
            #[allow(unsafe_code)]
-            unsafe {
-                definition_node.into_owned(self.module.clone())
-            },
+            DefinitionKind::Node(unsafe { definition_node.into_owned(self.module.clone()) }),
            countme::Count::default(),
        );

        self.definitions_by_node
            .insert(definition_node.key(), definition);
-        self.current_use_def_map_mut()
+        self.current_use_def_map()
            .record_definition(symbol, definition);

        definition
@@ -258,6 +266,49 @@ impl<'db> SemanticIndexBuilder<'db> {
        nested_scope
    }

+    /// Visit a list of [`Comprehension`] nodes, assumed to be the "generators" that compose a
+    /// comprehension (that is, the `for x in y` and `for y in z` parts of `x for x in y for y in z`.)
+    ///
+    /// [`Comprehension`]: ast::Comprehension
+    fn visit_generators(&mut self, scope: NodeWithScopeRef, generators: &'db [ast::Comprehension]) {
+        let mut generators_iter = generators.iter();
+
+        let Some(generator) = generators_iter.next() else {
+            unreachable!("Expression must contain at least one generator");
+        };
+
+        // The `iter` of the first generator is evaluated in the outer scope, while all subsequent
+        // nodes are evaluated in the inner scope.
+        self.visit_expr(&generator.iter);
+        self.push_scope(scope);
+
+        self.current_assignment = Some(CurrentAssignment::Comprehension {
+            node: generator,
+            first: true,
+        });
+        self.visit_expr(&generator.target);
+        self.current_assignment = None;
+
+        for expr in &generator.ifs {
+            self.visit_expr(expr);
+        }
+
+        for generator in generators_iter {
+            self.visit_expr(&generator.iter);
+
+            self.current_assignment = Some(CurrentAssignment::Comprehension {
+                node: generator,
+                first: false,
+            });
+            self.visit_expr(&generator.target);
+            self.current_assignment = None;
+
+            for expr in &generator.ifs {
+                self.visit_expr(expr);
+            }
+        }
+    }
+
    pub(super) fn build(mut self) -> SemanticIndex<'db> {
        let module = self.module;
        self.visit_body(module.suite());
@@ -412,21 +463,19 @@ where
            }
            ast::Stmt::If(node) => {
                self.visit_expr(&node.test);
-                let pre_if = self.flow_snapshot();
+                let pre_if = self.next_block();
                self.visit_body(&node.body);
-                let mut post_clauses: Vec<FlowSnapshot> = vec![];
+                let mut post_clauses: Vec<BasicBlockId> = vec![];
                for clause in &node.elif_else_clauses {
                    // snapshot after every block except the last; the last one will just become
                    // the state that we merge the other snapshots into
-                    post_clauses.push(self.flow_snapshot());
+                    post_clauses.push(self.next_block());
                    // we can only take an elif/else branch if none of the previous ones were
                    // taken, so the block entry state is always `pre_if`
-                    self.flow_restore(pre_if.clone());
+                    self.new_block_from(pre_if);
                    self.visit_elif_else_clause(clause);
                }
-                for post_clause_state in post_clauses {
-                    self.flow_merge(&post_clause_state);
-                }
+                self.next_block_unsealed();
                let has_else = node
                    .elif_else_clauses
                    .last()
@@ -434,35 +483,39 @@ where
                if !has_else {
                    // if there's no else clause, then it's possible we took none of the branches,
                    // and the pre_if state can reach here
-                    self.flow_merge(&pre_if);
+                    self.merge_block(pre_if);
                }
+                self.merge_blocks(post_clauses);
+                self.seal_block();
            }
            ast::Stmt::While(node) => {
                self.visit_expr(&node.test);

-                let pre_loop = self.flow_snapshot();
+                let pre_loop = self.next_block();

                // Save aside any break states from an outer loop
-                let saved_break_states = std::mem::take(&mut self.loop_break_states);
+                let saved_break_states = std::mem::take(&mut self.loop_breaks);
                self.visit_body(&node.body);
                // Get the break states from the body of this loop, and restore the saved outer
                // ones.
-                let break_states =
-                    std::mem::replace(&mut self.loop_break_states, saved_break_states);
+                let break_states = std::mem::replace(&mut self.loop_breaks, saved_break_states);

                // We may execute the `else` clause without ever executing the body, so merge in
                // the pre-loop state before visiting `else`.
-                self.flow_merge(&pre_loop);
+                self.next_block_unsealed();
+                self.merge_block(pre_loop);
+                self.seal_block();
                self.visit_body(&node.orelse);

                // Breaking out of a while loop bypasses the `else` clause, so merge in the break
                // states after visiting `else`.
-                for break_state in break_states {
-                    self.flow_merge(&break_state);
-                }
+                self.next_block_unsealed();
+                self.merge_blocks(break_states);
+                self.seal_block();
            }
            ast::Stmt::Break(_) => {
-                self.loop_break_states.push(self.flow_snapshot());
+                let block_id = self.next_block();
+                self.loop_breaks.push(block_id);
            }
            _ => {
                walk_stmt(self, stmt);
@@ -476,8 +529,7 @@ where
        self.current_ast_ids().record_expression(expr);

        match expr {
-            ast::Expr::Name(name_node) => {
-                let ast::ExprName { id, ctx, .. } = name_node;
+            ast::Expr::Name(name_node @ ast::ExprName { id, ctx, .. }) => {
                let flags = match ctx {
                    ast::ExprContext::Load => SymbolFlags::IS_USED,
                    ast::ExprContext::Store => SymbolFlags::IS_DEFINED,
@@ -500,15 +552,24 @@ where
                            self.add_definition(symbol, ann_assign);
                        }
                        Some(CurrentAssignment::Named(named)) => {
+                            // TODO(dhruvmanila): If the current scope is a comprehension, then the
+                            // named expression is implicitly nonlocal. This is yet to be
+                            // implemented.
                            self.add_definition(symbol, named);
                        }
+                        Some(CurrentAssignment::Comprehension { node, first }) => {
+                            self.add_definition(
+                                symbol,
+                                ComprehensionDefinitionNodeRef { node, first },
+                            );
+                        }
                        None => {}
                    }
                }

                if flags.contains(SymbolFlags::IS_USED) {
                    let use_id = self.current_ast_ids().record_use(expr);
-                    self.current_use_def_map_mut().record_use(symbol, use_id);
+                    self.current_use_def_map().record_use(symbol, use_id);
                }

                walk_expr(self, expr);
@@ -527,7 +588,6 @@ where
                }
                self.push_scope(NodeWithScopeRef::Lambda(lambda));
                self.visit_expr(lambda.body.as_ref());
-                self.pop_scope();
            }
            ast::Expr::If(ast::ExprIf {
                body, test, orelse, ..
@@ -536,17 +596,75 @@ where
                // AST inspection, so we can't simplify here, need to record test expression for
                // later checking)
                self.visit_expr(test);
-                let pre_if = self.flow_snapshot();
+                let pre_if = self.next_block();
                self.visit_expr(body);
-                let post_body = self.flow_snapshot();
-                self.flow_restore(pre_if);
+                let post_body = self.next_block();
+                self.new_block_from(pre_if);
                self.visit_expr(orelse);
-                self.flow_merge(&post_body);
+                self.next_block_unsealed();
+                self.merge_block(post_body);
+                self.seal_block();
+            }
+            ast::Expr::ListComp(
+                list_comprehension @ ast::ExprListComp {
+                    elt, generators, ..
+                },
+            ) => {
+                self.visit_generators(
+                    NodeWithScopeRef::ListComprehension(list_comprehension),
+                    generators,
+                );
+                self.visit_expr(elt);
+            }
+            ast::Expr::SetComp(
+                set_comprehension @ ast::ExprSetComp {
+                    elt, generators, ..
+                },
+            ) => {
+                self.visit_generators(
+                    NodeWithScopeRef::SetComprehension(set_comprehension),
+                    generators,
+                );
+                self.visit_expr(elt);
+            }
+            ast::Expr::Generator(
+                generator @ ast::ExprGenerator {
+                    elt, generators, ..
+                },
+            ) => {
+                self.visit_generators(NodeWithScopeRef::GeneratorExpression(generator), generators);
+                self.visit_expr(elt);
+            }
+            ast::Expr::DictComp(
+                dict_comprehension @ ast::ExprDictComp {
+                    key,
+                    value,
+                    generators,
+                    ..
+                },
+            ) => {
+                self.visit_generators(
+                    NodeWithScopeRef::DictComprehension(dict_comprehension),
+                    generators,
+                );
+                self.visit_expr(key);
+                self.visit_expr(value);
            }
            _ => {
                walk_expr(self, expr);
            }
        }
+
+        if matches!(
+            expr,
+            ast::Expr::Lambda(_)
+                | ast::Expr::ListComp(_)
+                | ast::Expr::SetComp(_)
+                | ast::Expr::Generator(_)
+                | ast::Expr::DictComp(_)
+        ) {
+            self.pop_scope();
+        }
    }
 }

@@ -555,6 +673,10 @@ enum CurrentAssignment<'a> {
    Assign(&'a ast::StmtAssign),
    AnnAssign(&'a ast::StmtAnnAssign),
    Named(&'a ast::ExprNamed),
+    Comprehension {
+        node: &'a ast::Comprehension,
+        first: bool,
+    },
 }

 impl<'a> From<&'a ast::StmtAssign> for CurrentAssignment<'a> {
--- a/crates/red_knot_python_semantic/src/semantic_index/definition.rs
+++ b/crates/red_knot_python_semantic/src/semantic_index/definition.rs
@@ -1,5 +1,6 @@
 use ruff_db::files::File;
 use ruff_db::parsed::ParsedModule;
+use ruff_index::newtype_index;
 use ruff_python_ast as ast;

 use crate::ast_node_ref::AstNodeRef;
@@ -8,7 +9,7 @@ use crate::semantic_index::symbol::{FileScopeId, ScopeId, ScopedSymbolId};
 use crate::Db;

 #[salsa::tracked]
-pub struct Definition<'db> {
+pub(crate) struct Definition<'db> {
    /// The file in which the definition occurs.
    #[id]
    pub(crate) file: File,
@@ -23,7 +24,7 @@ pub struct Definition<'db> {

    #[no_eq]
    #[return_ref]
-    pub(crate) node: DefinitionKind,
+    pub(crate) kind: DefinitionKind,

    #[no_eq]
    count: countme::Count<Definition<'static>>,
@@ -35,6 +36,22 @@ impl<'db> Definition<'db> {
    }
 }

+#[derive(Clone, Debug)]
+pub(crate) enum DefinitionKind {
+    /// Inserted at control-flow merge points, if multiple definitions can reach the merge point.
+    ///
+    /// Operands are not kept inline, since it's not possible to construct cyclically-referential
+    /// Salsa tracked structs; they are kept instead in the
+    /// [`UseDefMap`](super::use_def::UseDefMap).
+    Phi(ScopedPhiId),
+
+    /// An assignment to the symbol.
+    Node(DefinitionNode),
+}
+
+#[newtype_index]
+pub(crate) struct ScopedPhiId;
+
 #[derive(Copy, Clone, Debug)]
 pub(crate) enum DefinitionNodeRef<'a> {
    Import(&'a ast::Alias),
@@ -44,6 +61,7 @@ pub(crate) enum DefinitionNodeRef<'a> {
    NamedExpression(&'a ast::ExprNamed),
    Assignment(AssignmentDefinitionNodeRef<'a>),
    AnnotatedAssignment(&'a ast::StmtAnnAssign),
+    Comprehension(ComprehensionDefinitionNodeRef<'a>),
 }

 impl<'a> From<&'a ast::StmtFunctionDef> for DefinitionNodeRef<'a> {
@@ -88,6 +106,12 @@ impl<'a> From<AssignmentDefinitionNodeRef<'a>> for DefinitionNodeRef<'a> {
    }
 }

+impl<'a> From<ComprehensionDefinitionNodeRef<'a>> for DefinitionNodeRef<'a> {
+    fn from(node: ComprehensionDefinitionNodeRef<'a>) -> Self {
+        Self::Comprehension(node)
+    }
+}
+
 #[derive(Copy, Clone, Debug)]
 pub(crate) struct ImportFromDefinitionNodeRef<'a> {
    pub(crate) node: &'a ast::StmtImportFrom,
@@ -100,36 +124,48 @@ pub(crate) struct AssignmentDefinitionNodeRef<'a> {
    pub(crate) target: &'a ast::ExprName,
 }

+#[derive(Copy, Clone, Debug)]
+pub(crate) struct ComprehensionDefinitionNodeRef<'a> {
+    pub(crate) node: &'a ast::Comprehension,
+    pub(crate) first: bool,
+}
+
 impl DefinitionNodeRef<'_> {
    #[allow(unsafe_code)]
-    pub(super) unsafe fn into_owned(self, parsed: ParsedModule) -> DefinitionKind {
+    pub(super) unsafe fn into_owned(self, parsed: ParsedModule) -> DefinitionNode {
        match self {
            DefinitionNodeRef::Import(alias) => {
-                DefinitionKind::Import(AstNodeRef::new(parsed, alias))
+                DefinitionNode::Import(AstNodeRef::new(parsed, alias))
            }
            DefinitionNodeRef::ImportFrom(ImportFromDefinitionNodeRef { node, alias_index }) => {
-                DefinitionKind::ImportFrom(ImportFromDefinitionKind {
+                DefinitionNode::ImportFrom(ImportFromDefinitionNode {
                    node: AstNodeRef::new(parsed, node),
                    alias_index,
                })
            }
            DefinitionNodeRef::Function(function) => {
-                DefinitionKind::Function(AstNodeRef::new(parsed, function))
+                DefinitionNode::Function(AstNodeRef::new(parsed, function))
            }
            DefinitionNodeRef::Class(class) => {
-                DefinitionKind::Class(AstNodeRef::new(parsed, class))
+                DefinitionNode::Class(AstNodeRef::new(parsed, class))
            }
            DefinitionNodeRef::NamedExpression(named) => {
-                DefinitionKind::NamedExpression(AstNodeRef::new(parsed, named))
+                DefinitionNode::NamedExpression(AstNodeRef::new(parsed, named))
            }
            DefinitionNodeRef::Assignment(AssignmentDefinitionNodeRef { assignment, target }) => {
-                DefinitionKind::Assignment(AssignmentDefinitionKind {
+                DefinitionNode::Assignment(AssignmentDefinitionNode {
                    assignment: AstNodeRef::new(parsed.clone(), assignment),
                    target: AstNodeRef::new(parsed, target),
                })
            }
            DefinitionNodeRef::AnnotatedAssignment(assign) => {
-                DefinitionKind::AnnotatedAssignment(AstNodeRef::new(parsed, assign))
+                DefinitionNode::AnnotatedAssignment(AstNodeRef::new(parsed, assign))
+            }
+            DefinitionNodeRef::Comprehension(ComprehensionDefinitionNodeRef { node, first }) => {
+                DefinitionNode::Comprehension(ComprehensionDefinitionNode {
+                    node: AstNodeRef::new(parsed, node),
+                    first,
+                })
            }
        }
    }
@@ -148,28 +184,46 @@ impl DefinitionNodeRef<'_> {
                target,
            }) => target.into(),
            Self::AnnotatedAssignment(node) => node.into(),
+            Self::Comprehension(ComprehensionDefinitionNodeRef { node, first: _ }) => node.into(),
        }
    }
 }

 #[derive(Clone, Debug)]
-pub enum DefinitionKind {
+pub enum DefinitionNode {
    Import(AstNodeRef<ast::Alias>),
-    ImportFrom(ImportFromDefinitionKind),
+    ImportFrom(ImportFromDefinitionNode),
    Function(AstNodeRef<ast::StmtFunctionDef>),
    Class(AstNodeRef<ast::StmtClassDef>),
    NamedExpression(AstNodeRef<ast::ExprNamed>),
-    Assignment(AssignmentDefinitionKind),
+    Assignment(AssignmentDefinitionNode),
    AnnotatedAssignment(AstNodeRef<ast::StmtAnnAssign>),
+    Comprehension(ComprehensionDefinitionNode),
 }

 #[derive(Clone, Debug)]
-pub struct ImportFromDefinitionKind {
+pub struct ComprehensionDefinitionNode {
+    node: AstNodeRef<ast::Comprehension>,
+    first: bool,
+}
+
+impl ComprehensionDefinitionNode {
+    pub(crate) fn node(&self) -> &ast::Comprehension {
+        self.node.node()
+    }
+
+    pub(crate) fn is_first(&self) -> bool {
+        self.first
+    }
+}
+
+#[derive(Clone, Debug)]
+pub struct ImportFromDefinitionNode {
    node: AstNodeRef<ast::StmtImportFrom>,
    alias_index: usize,
 }

-impl ImportFromDefinitionKind {
+impl ImportFromDefinitionNode {
    pub(crate) fn import(&self) -> &ast::StmtImportFrom {
        self.node.node()
    }
@@ -181,12 +235,12 @@ impl ImportFromDefinitionKind {

 #[derive(Clone, Debug)]
 #[allow(dead_code)]
-pub struct AssignmentDefinitionKind {
+pub struct AssignmentDefinitionNode {
    assignment: AstNodeRef<ast::StmtAssign>,
    target: AstNodeRef<ast::ExprName>,
 }

-impl AssignmentDefinitionKind {
+impl AssignmentDefinitionNode {
    pub(crate) fn assignment(&self) -> &ast::StmtAssign {
        self.assignment.node()
    }
@@ -230,3 +284,9 @@ impl From<&ast::StmtAnnAssign> for DefinitionNodeKey {
        Self(NodeKey::from_node(node))
    }
 }
+
+impl From<&ast::Comprehension> for DefinitionNodeKey {
+    fn from(node: &ast::Comprehension) -> Self {
+        Self(NodeKey::from_node(node))
+    }
+}
--- a/crates/red_knot_python_semantic/src/semantic_index/symbol.rs
+++ b/crates/red_knot_python_semantic/src/semantic_index/symbol.rs
@@ -114,6 +114,10 @@ impl<'db> ScopeId<'db> {
            NodeWithScopeKind::ClassTypeParameters(_)
                | NodeWithScopeKind::FunctionTypeParameters(_)
                | NodeWithScopeKind::Function(_)
+                | NodeWithScopeKind::ListComprehension(_)
+                | NodeWithScopeKind::SetComprehension(_)
+                | NodeWithScopeKind::DictComprehension(_)
+                | NodeWithScopeKind::GeneratorExpression(_)
        )
    }

@@ -127,6 +131,10 @@ impl<'db> ScopeId<'db> {
            NodeWithScopeKind::Function(function)
            | NodeWithScopeKind::FunctionTypeParameters(function) => function.name.as_str(),
            NodeWithScopeKind::Lambda(_) => "<lambda>",
+            NodeWithScopeKind::ListComprehension(_) => "<listcomp>",
+            NodeWithScopeKind::SetComprehension(_) => "<setcomp>",
+            NodeWithScopeKind::DictComprehension(_) => "<dictcomp>",
+            NodeWithScopeKind::GeneratorExpression(_) => "<generator>",
        }
    }
 }
@@ -170,6 +178,13 @@ pub enum ScopeKind {
    Annotation,
    Class,
    Function,
+    Comprehension,
+}
+
+impl ScopeKind {
+    pub const fn is_comprehension(self) -> bool {
+        matches!(self, ScopeKind::Comprehension)
+    }
 }

 /// Symbol table for a specific [`Scope`].
@@ -257,7 +272,7 @@ impl SymbolTableBuilder {
        &mut self,
        name: Name,
        flags: SymbolFlags,
-    ) -> (ScopedSymbolId, bool) {
+    ) -> ScopedSymbolId {
        let hash = SymbolTable::hash_name(&name);
        let entry = self
            .table
@@ -270,7 +285,7 @@ impl SymbolTableBuilder {
                let symbol = &mut self.table.symbols[*entry.key()];
                symbol.insert_flags(flags);

-                (*entry.key(), false)
+                *entry.key()
            }
            RawEntryMut::Vacant(entry) => {
                let mut symbol = Symbol::new(name);
@@ -280,7 +295,7 @@ impl SymbolTableBuilder {
                entry.insert_with_hasher(hash, id, (), |id| {
                    SymbolTable::hash_name(self.table.symbols[*id].name().as_str())
                });
-                (id, true)
+                id
            }
        }
    }
@@ -300,6 +315,10 @@ pub(crate) enum NodeWithScopeRef<'a> {
    Lambda(&'a ast::ExprLambda),
    FunctionTypeParameters(&'a ast::StmtFunctionDef),
    ClassTypeParameters(&'a ast::StmtClassDef),
+    ListComprehension(&'a ast::ExprListComp),
+    SetComprehension(&'a ast::ExprSetComp),
+    DictComprehension(&'a ast::ExprDictComp),
+    GeneratorExpression(&'a ast::ExprGenerator),
 }

 impl NodeWithScopeRef<'_> {
@@ -326,6 +345,18 @@ impl NodeWithScopeRef<'_> {
            NodeWithScopeRef::ClassTypeParameters(class) => {
                NodeWithScopeKind::ClassTypeParameters(AstNodeRef::new(module, class))
            }
+            NodeWithScopeRef::ListComprehension(comprehension) => {
+                NodeWithScopeKind::ListComprehension(AstNodeRef::new(module, comprehension))
+            }
+            NodeWithScopeRef::SetComprehension(comprehension) => {
+                NodeWithScopeKind::SetComprehension(AstNodeRef::new(module, comprehension))
+            }
+            NodeWithScopeRef::DictComprehension(comprehension) => {
+                NodeWithScopeKind::DictComprehension(AstNodeRef::new(module, comprehension))
+            }
+            NodeWithScopeRef::GeneratorExpression(generator) => {
+                NodeWithScopeKind::GeneratorExpression(AstNodeRef::new(module, generator))
+            }
        }
    }

@@ -337,6 +368,10 @@ impl NodeWithScopeRef<'_> {
            NodeWithScopeRef::Lambda(_) => ScopeKind::Function,
            NodeWithScopeRef::FunctionTypeParameters(_)
            | NodeWithScopeRef::ClassTypeParameters(_) => ScopeKind::Annotation,
+            NodeWithScopeRef::ListComprehension(_)
+            | NodeWithScopeRef::SetComprehension(_)
+            | NodeWithScopeRef::DictComprehension(_)
+            | NodeWithScopeRef::GeneratorExpression(_) => ScopeKind::Comprehension,
        }
    }

@@ -356,6 +391,18 @@ impl NodeWithScopeRef<'_> {
            NodeWithScopeRef::ClassTypeParameters(class) => {
                NodeWithScopeKey::ClassTypeParameters(NodeKey::from_node(class))
            }
+            NodeWithScopeRef::ListComprehension(comprehension) => {
+                NodeWithScopeKey::ListComprehension(NodeKey::from_node(comprehension))
+            }
+            NodeWithScopeRef::SetComprehension(comprehension) => {
+                NodeWithScopeKey::SetComprehension(NodeKey::from_node(comprehension))
+            }
+            NodeWithScopeRef::DictComprehension(comprehension) => {
+                NodeWithScopeKey::DictComprehension(NodeKey::from_node(comprehension))
+            }
+            NodeWithScopeRef::GeneratorExpression(generator) => {
+                NodeWithScopeKey::GeneratorExpression(NodeKey::from_node(generator))
+            }
        }
    }
 }
@@ -369,6 +416,10 @@ pub enum NodeWithScopeKind {
    Function(AstNodeRef<ast::StmtFunctionDef>),
    FunctionTypeParameters(AstNodeRef<ast::StmtFunctionDef>),
    Lambda(AstNodeRef<ast::ExprLambda>),
+    ListComprehension(AstNodeRef<ast::ExprListComp>),
+    SetComprehension(AstNodeRef<ast::ExprSetComp>),
+    DictComprehension(AstNodeRef<ast::ExprDictComp>),
+    GeneratorExpression(AstNodeRef<ast::ExprGenerator>),
 }

 #[derive(Copy, Clone, Debug, Eq, PartialEq, Hash)]
@@ -379,4 +430,8 @@ pub(crate) enum NodeWithScopeKey {
    Function(NodeKey),
    FunctionTypeParameters(NodeKey),
    Lambda(NodeKey),
+    ListComprehension(NodeKey),
+    SetComprehension(NodeKey),
+    DictComprehension(NodeKey),
+    GeneratorExpression(NodeKey),
 }
--- a/crates/red_knot_python_semantic/src/semantic_index/use_def.rs
+++ b/crates/red_knot_python_semantic/src/semantic_index/use_def.rs
@@ -56,299 +56,323 @@
 //! visible at the end of the scope.
 //!
 //! The data structure we build to answer these two questions is the `UseDefMap`. It has a
-//! `definitions_by_use` vector indexed by [`ScopedUseId`] and a `public_definitions` vector
-//! indexed by [`ScopedSymbolId`]. The values in each of these vectors are (in principle) a list of
-//! visible definitions at that use, or at the end of the scope for that symbol.
+//! `definitions_by_use` vector indexed by [`ScopedUseId`] and a `public_definitions` map
+//! indexed by [`ScopedSymbolId`]. The values in each are the visible definition of a symbol at
+//! that use, or at the end of the scope.
 //!
-//! In order to avoid vectors-of-vectors and all the allocations that would entail, we don't
-//! actually store these "list of visible definitions" as a vector of [`Definition`] IDs. Instead,
-//! the values in `definitions_by_use` and `public_definitions` are a [`Definitions`] struct that
-//! keeps a [`Range`] into a third vector of [`Definition`] IDs, `all_definitions`. The trick with
-//! this representation is that it requires that the definitions visible at any given use of a
-//! symbol are stored sequentially in `all_definitions`.
-//!
-//! There is another special kind of possible "definition" for a symbol: it might be unbound in the
-//! scope. (This isn't equivalent to "zero visible definitions", since we may go through an `if`
-//! that has a definition for the symbol, leaving us with one visible definition, but still also
-//! the "unbound" possibility, since we might not have taken the `if` branch.)
-//!
-//! The simplest way to model "unbound" would be as an actual [`Definition`] itself: the initial
-//! visible [`Definition`] for each symbol in a scope. But actually modeling it this way would
-//! dramatically increase the number of [`Definition`] that Salsa must track. Since "unbound" is a
-//! special definition in that all symbols share it, and it doesn't have any additional per-symbol
-//! state, we can represent it more efficiently: we use the `may_be_unbound` boolean on the
-//! [`Definitions`] struct. If this flag is `true`, it means the symbol/use really has one
-//! additional visible "definition", which is the unbound state. If this flag is `false`, it means
-//! we've eliminated the possibility of unbound: every path we've followed includes a definition
-//! for this symbol.
-//!
-//! To build a [`UseDefMap`], the [`UseDefMapBuilder`] is notified of each new use and definition
-//! as they are encountered by the
-//! [`SemanticIndexBuilder`](crate::semantic_index::builder::SemanticIndexBuilder) AST visit. For
-//! each symbol, the builder tracks the currently-visible definitions for that symbol. When we hit
-//! a use of a symbol, it records the currently-visible definitions for that symbol as the visible
-//! definitions for that use. When we reach the end of the scope, it records the currently-visible
-//! definitions for each symbol as the public definitions of that symbol.
-//!
-//! Let's walk through the above example. Initially we record for `x` that it has no visible
-//! definitions, and may be unbound. When we see `x = 1`, we record that as the sole visible
-//! definition of `x`, and flip `may_be_unbound` to `false`. Then we see `x = 2`, and it replaces
-//! `x = 1` as the sole visible definition of `x`. When we get to `y = x`, we record that the
-//! visible definitions for that use of `x` are just the `x = 2` definition.
-//!
-//! Then we hit the `if` branch. We visit the `test` node (`flag` in this case), since that will
-//! happen regardless. Then we take a pre-branch snapshot of the currently visible definitions for
-//! all symbols, which we'll need later. Then we go ahead and visit the `if` body. When we see `x =
-//! 3`, it replaces `x = 2` as the sole visible definition of `x`. At the end of the `if` body, we
-//! take another snapshot of the currently-visible definitions; we'll call this the post-if-body
-//! snapshot.
-//!
-//! Now we need to visit the `else` clause. The conditions when entering the `else` clause should
-//! be the pre-if conditions; if we are entering the `else` clause, we know that the `if` test
-//! failed and we didn't execute the `if` body. So we first reset the builder to the pre-if state,
-//! using the snapshot we took previously (meaning we now have `x = 2` as the sole visible
-//! definition for `x` again), then visit the `else` clause, where `x = 4` replaces `x = 2` as the
-//! sole visible definition of `x`.
-//!
-//! Now we reach the end of the if/else, and want to visit the following code. The state here needs
-//! to reflect that we might have gone through the `if` branch, or we might have gone through the
-//! `else` branch, and we don't know which. So we need to "merge" our current builder state
-//! (reflecting the end-of-else state, with `x = 4` as the only visible definition) with our
-//! post-if-body snapshot (which has `x = 3` as the only visible definition). The result of this
-//! merge is that we now have two visible definitions of `x`: `x = 3` and `x = 4`.
-//!
-//! The [`UseDefMapBuilder`] itself just exposes methods for taking a snapshot, resetting to a
-//! snapshot, and merging a snapshot into the current state. The logic using these methods lives in
-//! [`SemanticIndexBuilder`](crate::semantic_index::builder::SemanticIndexBuilder), e.g. where it
-//! visits a `StmtIf` node.
-//!
-//! (In the future we may have some other questions we want to answer as well, such as "is this
-//! definition used?", which will require tracking a bit more info in our map, e.g. a "used" bit
-//! for each [`Definition`] which is flipped to true when we record that definition for a use.)
+//! Rather than have multiple definitions, we use a Phi definition at control flow join points to
+//! merge the visible definition in each path. This means at any given point we always have exactly
+//! one definition for a symbol. (This is analogous to static-single-assignment, or SSA, form, and
+//! in fact we use the algorithm from [Simple and efficient construction of static single
+//! assignment form](https://dl.acm.org/doi/10.1007/978-3-642-37051-9_6) here.)
 use crate::semantic_index::ast_ids::ScopedUseId;
-use crate::semantic_index::definition::Definition;
-use crate::semantic_index::symbol::ScopedSymbolId;
-use ruff_index::IndexVec;
-use std::ops::Range;
+use crate::semantic_index::definition::{Definition, DefinitionKind, ScopedPhiId};
+use crate::semantic_index::symbol::{FileScopeId, ScopedSymbolId};
+use crate::Db;
+use ruff_db::files::File;
+use ruff_index::{newtype_index, IndexVec};
+use rustc_hash::{FxHashMap, FxHashSet};
+use smallvec::{smallvec, SmallVec};

-/// All definitions that can reach a given use of a name.
+/// Number of basic block predecessors we store inline.
+const PREDECESSORS: usize = 2;
+
+/// Input operands (definitions) for a Phi definition. None means not defined.
+// TODO would like to use SmallVec here but can't due to lifetime invariance issue.
+type PhiOperands<'db> = Vec<Option<Definition<'db>>>;
+
+/// Definition for each use of a name.
 #[derive(Debug, PartialEq, Eq)]
 pub(crate) struct UseDefMap<'db> {
    // TODO store constraints with definitions for type narrowing
-    /// Definition IDs array for `definitions_by_use` and `public_definitions` to slice into.
-    all_definitions: Vec<Definition<'db>>,
+    /// Definition that reaches each [`ScopedUseId`].
+    definitions_by_use: IndexVec<ScopedUseId, Option<Definition<'db>>>,

-    /// Definitions that can reach a [`ScopedUseId`].
-    definitions_by_use: IndexVec<ScopedUseId, Definitions>,
+    /// Definition of each symbol visible at end of scope.
+    ///
+    /// Sparse, because it only includes symbols defined in the scope.
+    public_definitions: FxHashMap<ScopedSymbolId, Definition<'db>>,

-    /// Definitions of each symbol visible at end of scope.
-    public_definitions: IndexVec<ScopedSymbolId, Definitions>,
+    /// Operands for each Phi definition in this scope.
+    phi_operands: IndexVec<ScopedPhiId, PhiOperands<'db>>,
 }

 impl<'db> UseDefMap<'db> {
-    pub(crate) fn use_definitions(&self, use_id: ScopedUseId) -> &[Definition<'db>] {
-        &self.all_definitions[self.definitions_by_use[use_id].definitions_range.clone()]
+    /// Return the dominating definition for a given use of a name; None means not-defined.
+    pub(crate) fn definition_for_use(&self, use_id: ScopedUseId) -> Option<Definition<'db>> {
+        self.definitions_by_use[use_id]
    }

-    pub(crate) fn use_may_be_unbound(&self, use_id: ScopedUseId) -> bool {
-        self.definitions_by_use[use_id].may_be_unbound
+    /// Return the definition visible at end of scope for a symbol.
+    ///
+    /// Return None if the symbol is never defined in the scope.
+    pub(crate) fn public_definition(&self, symbol_id: ScopedSymbolId) -> Option<Definition<'db>> {
+        self.public_definitions.get(&symbol_id).copied()
    }

-    pub(crate) fn public_definitions(&self, symbol: ScopedSymbolId) -> &[Definition<'db>] {
-        &self.all_definitions[self.public_definitions[symbol].definitions_range.clone()]
-    }
-
-    pub(crate) fn public_may_be_unbound(&self, symbol: ScopedSymbolId) -> bool {
-        self.public_definitions[symbol].may_be_unbound
+    /// Return the operands for a Phi in this scope; a None means not-defined.
+    pub(crate) fn phi_operands<'s>(&'s self, phi_id: ScopedPhiId) -> &'s [Option<Definition<'db>>] {
+        self.phi_operands[phi_id].as_slice()
    }
 }

-/// Definitions visible for a symbol at a particular use (or end-of-scope).
-#[derive(Clone, Debug, PartialEq, Eq)]
-struct Definitions {
-    /// [`Range`] in `all_definitions` of the visible definition IDs.
-    definitions_range: Range<usize>,
-    /// Is the symbol possibly unbound at this point?
-    may_be_unbound: bool,
-}
+type PredecessorBlocks = SmallVec<[BasicBlockId; PREDECESSORS]>;

-impl Definitions {
-    /// The default state of a symbol is "no definitions, may be unbound", aka definitely-unbound.
-    fn unbound() -> Self {
-        Self {
-            definitions_range: Range::default(),
-            may_be_unbound: true,
-        }
-    }
-}
+/// A basic block is a linear region of code (no branches.)
+#[newtype_index]
+pub(super) struct BasicBlockId;

-impl Default for Definitions {
-    fn default() -> Self {
-        Definitions::unbound()
-    }
-}
-
-/// A snapshot of the visible definitions for each symbol at a particular point in control flow.
-#[derive(Clone, Debug)]
-pub(super) struct FlowSnapshot {
-    definitions_by_symbol: IndexVec<ScopedSymbolId, Definitions>,
-}
-
-#[derive(Debug)]
 pub(super) struct UseDefMapBuilder<'db> {
-    /// Definition IDs array for `definitions_by_use` and `definitions_by_symbol` to slice into.
-    all_definitions: Vec<Definition<'db>>,
+    db: &'db dyn Db,
+    file: File,
+    file_scope: FileScopeId,

-    /// Visible definitions at each so-far-recorded use.
-    definitions_by_use: IndexVec<ScopedUseId, Definitions>,
+    /// Predecessor blocks for each basic block.
+    ///
+    /// Entry block has none, all other blocks have at least one, blocks that join control flow can
+    /// have two or more.
+    predecessors: IndexVec<BasicBlockId, PredecessorBlocks>,

-    /// Currently visible definitions for each symbol.
-    definitions_by_symbol: IndexVec<ScopedSymbolId, Definitions>,
+    /// The definition of each symbol which dominates each basic block.
+    ///
+    /// No entry means "lazily unfilled"; we haven't had to query for it yet, and we may never have
+    /// to, if the symbol isn't used in this block or any successor block.
+    ///
+    /// Each block has an [`FxHashMap`] of symbols instead of an [`IndexVec`] because it is lazy
+    /// and potentially sparse; it will only include a definition for a symbol that is actually
+    /// used in that block or a successor. An [`IndexVec`] would have to be eagerly filled with
+    /// placeholders.
+    definitions_per_block:
+        IndexVec<BasicBlockId, FxHashMap<ScopedSymbolId, Option<Definition<'db>>>>,
+
+    /// Incomplete Phi definitions in each block.
+    ///
+    /// An incomplete Phi is used when we don't know, while processing a block's body, what new
+    /// predecessors it may later gain (that is, backward jumps.)
+    ///
+    /// Sparse, because relative few blocks (just loop headers) will have any incomplete Phis.
+    incomplete_phis: FxHashMap<BasicBlockId, Vec<Definition<'db>>>,
+
+    /// Operands for each Phi definition in this scope.
+    phi_operands: IndexVec<ScopedPhiId, PhiOperands<'db>>,
+
+    /// Are this block's predecessors fully populated?
+    ///
+    /// If not, it isn't safe to recurse to predecessors yet; we might miss a predecessor block.
+    sealed_blocks: IndexVec<BasicBlockId, bool>,
+
+    /// Definition for each so-far-recorded use.
+    definitions_by_use: IndexVec<ScopedUseId, Option<Definition<'db>>>,
+
+    /// All symbols defined in this scope.
+    defined_symbols: FxHashSet<ScopedSymbolId>,
 }

 impl<'db> UseDefMapBuilder<'db> {
-    pub(super) fn new() -> Self {
-        Self {
-            all_definitions: Vec::new(),
+    pub(super) fn new(db: &'db dyn Db, file: File, file_scope: FileScopeId) -> Self {
+        let mut new = Self {
+            db,
+            file,
+            file_scope,
+            predecessors: IndexVec::new(),
+            definitions_per_block: IndexVec::new(),
+            incomplete_phis: FxHashMap::default(),
+            sealed_blocks: IndexVec::new(),
            definitions_by_use: IndexVec::new(),
-            definitions_by_symbol: IndexVec::new(),
-        }
-    }
-
-    pub(super) fn add_symbol(&mut self, symbol: ScopedSymbolId) {
-        let new_symbol = self.definitions_by_symbol.push(Definitions::unbound());
-        debug_assert_eq!(symbol, new_symbol);
+            phi_operands: IndexVec::new(),
+            defined_symbols: FxHashSet::default(),
+        };
+
+        // create the entry basic block
+        new.predecessors.push(PredecessorBlocks::default());
+        new.definitions_per_block.push(FxHashMap::default());
+        new.sealed_blocks.push(true);
+
+        new
    }

+    /// Record a definition for a symbol.
    pub(super) fn record_definition(
        &mut self,
-        symbol: ScopedSymbolId,
+        symbol_id: ScopedSymbolId,
        definition: Definition<'db>,
    ) {
-        // We have a new definition of a symbol; this replaces any previous definitions in this
-        // path.
-        let def_idx = self.all_definitions.len();
-        self.all_definitions.push(definition);
-        self.definitions_by_symbol[symbol] = Definitions {
-            #[allow(clippy::range_plus_one)]
-            definitions_range: def_idx..(def_idx + 1),
-            may_be_unbound: false,
-        };
+        self.memoize(self.current_block_id(), symbol_id, Some(definition));
+        self.defined_symbols.insert(symbol_id);
    }

-    pub(super) fn record_use(&mut self, symbol: ScopedSymbolId, use_id: ScopedUseId) {
-        // We have a use of a symbol; clone the currently visible definitions for that symbol, and
-        // record them as the visible definitions for this use.
-        let new_use = self
-            .definitions_by_use
-            .push(self.definitions_by_symbol[symbol].clone());
+    /// Record a use of a symbol.
+    pub(super) fn record_use(&mut self, symbol_id: ScopedSymbolId, use_id: ScopedUseId) {
+        let definition_id = self.lookup(symbol_id);
+        let new_use = self.definitions_by_use.push(definition_id);
        debug_assert_eq!(use_id, new_use);
    }

-    /// Take a snapshot of the current visible-symbols state.
-    pub(super) fn snapshot(&self) -> FlowSnapshot {
-        FlowSnapshot {
-            definitions_by_symbol: self.definitions_by_symbol.clone(),
+    /// Get the id of the current basic block.
+    pub(super) fn current_block_id(&self) -> BasicBlockId {
+        BasicBlockId::from(self.definitions_per_block.len() - 1)
+    }
+
+    /// Push a new basic block, with given block as predecessor.
+    pub(super) fn new_block_from(&mut self, block_id: BasicBlockId, sealed: bool) {
+        self.new_block_with_predecessors(smallvec![block_id], sealed);
+    }
+
+    /// Push a new basic block, with current block as predecessor; return the current block's ID.
+    pub(super) fn next_block(&mut self, sealed: bool) -> BasicBlockId {
+        let current_block_id = self.current_block_id();
+        self.new_block_from(current_block_id, sealed);
+        current_block_id
+    }
+
+    /// Add a predecessor to the current block.
+    pub(super) fn merge_block(&mut self, new_predecessor: BasicBlockId) {
+        let block_id = self.current_block_id();
+        debug_assert!(!self.sealed_blocks[block_id]);
+        self.predecessors[block_id].push(new_predecessor);
+    }
+
+    /// Add predecessors to the current block.
+    pub(super) fn merge_blocks(&mut self, new_predecessors: Vec<BasicBlockId>) {
+        let block_id = self.current_block_id();
+        debug_assert!(!self.sealed_blocks[block_id]);
+        self.predecessors[block_id].extend(new_predecessors);
+    }
+
+    /// Mark the current block as sealed; it cannot have any more predecessors added.
+    pub(super) fn seal_current_block(&mut self) {
+        self.seal_block(self.current_block_id());
+    }
+
+    /// Mark a block as sealed; it cannot have any more predecessors added.
+    pub(super) fn seal_block(&mut self, block_id: BasicBlockId) {
+        debug_assert!(!self.sealed_blocks[block_id]);
+        if let Some(phis) = self.incomplete_phis.get(&block_id) {
+            for phi in phis.clone() {
+                self.add_phi_operands(block_id, phi);
+            }
+            self.incomplete_phis.remove(&block_id);
+        }
+        self.sealed_blocks[block_id] = true;
+    }
+
+    pub(super) fn finish(mut self) -> UseDefMap<'db> {
+        debug_assert!(self.incomplete_phis.is_empty());
+        debug_assert!(self.sealed_blocks.iter().all(|&b| b));
+        self.definitions_by_use.shrink_to_fit();
+        self.phi_operands.shrink_to_fit();
+
+        let mut public_definitions: FxHashMap<ScopedSymbolId, Definition<'db>> =
+            FxHashMap::default();
+
+        for symbol_id in self.defined_symbols.clone() {
+            // SAFETY: We are only looking up defined symbols here, can't get None.
+            public_definitions.insert(symbol_id, self.lookup(symbol_id).unwrap());
+        }
+
+        UseDefMap {
+            definitions_by_use: self.definitions_by_use,
+            public_definitions,
+            phi_operands: self.phi_operands,
        }
    }

-    /// Restore the current builder visible-definitions state to the given snapshot.
-    pub(super) fn restore(&mut self, snapshot: FlowSnapshot) {
-        // We never remove symbols from `definitions_by_symbol` (it's an IndexVec, and the symbol
-        // IDs must line up), so the current number of known symbols must always be equal to or
-        // greater than the number of known symbols in a previously-taken snapshot.
-        let num_symbols = self.definitions_by_symbol.len();
-        debug_assert!(num_symbols >= snapshot.definitions_by_symbol.len());
+    /// Push a new basic block (with given predecessors) and return its ID.
+    fn new_block_with_predecessors(
+        &mut self,
+        predecessors: PredecessorBlocks,
+        sealed: bool,
+    ) -> BasicBlockId {
+        let new_block_id = self.predecessors.push(predecessors);
+        self.definitions_per_block.push(FxHashMap::default());
+        self.sealed_blocks.push(sealed);

-        // Restore the current visible-definitions state to the given snapshot.
-        self.definitions_by_symbol = snapshot.definitions_by_symbol;
-
-        // If the snapshot we are restoring is missing some symbols we've recorded since, we need
-        // to fill them in so the symbol IDs continue to line up. Since they don't exist in the
-        // snapshot, the correct state to fill them in with is "unbound", the default.
-        self.definitions_by_symbol
-            .resize(num_symbols, Definitions::unbound());
+        new_block_id
    }

-    /// Merge the given snapshot into the current state, reflecting that we might have taken either
-    /// path to get here. The new visible-definitions state for each symbol should include
-    /// definitions from both the prior state and the snapshot.
-    pub(super) fn merge(&mut self, snapshot: &FlowSnapshot) {
-        // The tricky thing about merging two Ranges pointing into `all_definitions` is that if the
-        // two Ranges aren't already adjacent in `all_definitions`, we will have to copy at least
-        // one or the other of the ranges to the end of `all_definitions` so as to make them
-        // adjacent. We can't ever move things around in `all_definitions` because previously
-        // recorded uses may still have ranges pointing to any part of it; all we can do is append.
-        // It's possible we may end up with some old entries in `all_definitions` that nobody is
-        // pointing to, but that's OK.
+    /// Look up the dominating definition for a symbol in the current block.
+    ///
+    /// If there isn't a local definition, recursively look up the symbol in predecessor blocks,
+    /// memoizing the found symbol in each block.
+    fn lookup(&mut self, symbol_id: ScopedSymbolId) -> Option<Definition<'db>> {
+        self.lookup_impl(self.current_block_id(), symbol_id)
+    }

-        // We never remove symbols from `definitions_by_symbol` (it's an IndexVec, and the symbol
-        // IDs must line up), so the current number of known symbols must always be equal to or
-        // greater than the number of known symbols in a previously-taken snapshot.
-        debug_assert!(self.definitions_by_symbol.len() >= snapshot.definitions_by_symbol.len());
-
-        for (symbol_id, current) in self.definitions_by_symbol.iter_mut_enumerated() {
-            let Some(snapshot) = snapshot.definitions_by_symbol.get(symbol_id) else {
-                // Symbol not present in snapshot, so it's unbound from that path.
-                current.may_be_unbound = true;
-                continue;
-            };
-
-            // If the symbol can be unbound in either predecessor, it can be unbound post-merge.
-            current.may_be_unbound |= snapshot.may_be_unbound;
-
-            // Merge the definition ranges.
-            let current = &mut current.definitions_range;
-            let snapshot = &snapshot.definitions_range;
-
-            // We never create reversed ranges.
-            debug_assert!(current.end >= current.start);
-            debug_assert!(snapshot.end >= snapshot.start);
-
-            if current == snapshot {
-                // Ranges already identical, nothing to do.
-            } else if snapshot.is_empty() {
-                // Merging from an empty range; nothing to do.
-            } else if (*current).is_empty() {
-                // Merging to an empty range; just use the incoming range.
-                *current = snapshot.clone();
-            } else if snapshot.end >= current.start && snapshot.start <= current.end {
-                // Ranges are adjacent or overlapping, merge them in-place.
-                *current = current.start.min(snapshot.start)..current.end.max(snapshot.end);
-            } else if current.end == self.all_definitions.len() {
-                // Ranges are not adjacent or overlapping, `current` is at the end of
-                // `all_definitions`, we need to copy `snapshot` to the end so they are adjacent
-                // and can be merged into one range.
-                self.all_definitions.extend_from_within(snapshot.clone());
-                current.end = self.all_definitions.len();
-            } else if snapshot.end == self.all_definitions.len() {
-                // Ranges are not adjacent or overlapping, `snapshot` is at the end of
-                // `all_definitions`, we need to copy `current` to the end so they are adjacent and
-                // can be merged into one range.
-                self.all_definitions.extend_from_within(current.clone());
-                current.start = snapshot.start;
-                current.end = self.all_definitions.len();
-            } else {
-                // Ranges are not adjacent and neither one is at the end of `all_definitions`, we
-                // have to copy both to the end so they are adjacent and we can merge them.
-                let start = self.all_definitions.len();
-                self.all_definitions.extend_from_within(current.clone());
-                self.all_definitions.extend_from_within(snapshot.clone());
-                current.start = start;
-                current.end = self.all_definitions.len();
+    fn lookup_impl(
+        &mut self,
+        block_id: BasicBlockId,
+        symbol_id: ScopedSymbolId,
+    ) -> Option<Definition<'db>> {
+        if let Some(local) = self.definitions_per_block[block_id].get(&symbol_id) {
+            return *local;
+        }
+        if !self.sealed_blocks[block_id] {
+            // we may still be missing predecessors; insert an incomplete Phi.
+            let definition = self.create_incomplete_phi(block_id, symbol_id);
+            self.incomplete_phis
+                .entry(block_id)
+                .or_default()
+                .push(definition);
+            return Some(definition);
+        }
+        match self.predecessors[block_id].as_slice() {
+            // entry block, no definition found: return None
+            [] => None,
+            // single predecessor, recurse
+            &[single_predecessor_id] => {
+                let definition = self.lookup_impl(single_predecessor_id, symbol_id);
+                self.memoize(block_id, symbol_id, definition);
+                definition
+            }
+            // multiple predecessors: create and memoize an incomplete Phi to break cycles, then
+            // recurse into predecessors and fill the Phi operands.
+            _ => {
+                let phi = self.create_incomplete_phi(block_id, symbol_id);
+                self.add_phi_operands(block_id, phi);
+                Some(phi)
            }
        }
    }

-    pub(super) fn finish(mut self) -> UseDefMap<'db> {
-        self.all_definitions.shrink_to_fit();
-        self.definitions_by_symbol.shrink_to_fit();
-        self.definitions_by_use.shrink_to_fit();
+    /// Recurse into predecessors to add operands for an incomplete Phi.
+    fn add_phi_operands(&mut self, block_id: BasicBlockId, phi: Definition<'db>) {
+        let predecessors: PredecessorBlocks = self.predecessors[block_id].clone();
+        let operands: PhiOperands = predecessors
+            .iter()
+            .map(|pred_id| self.lookup_impl(*pred_id, phi.symbol(self.db)))
+            .collect();
+        let DefinitionKind::Phi(phi_id) = phi.kind(self.db) else {
+            unreachable!("add_phi_operands called with non-Phi");
+        };
+        self.phi_operands[*phi_id] = operands;
+    }

-        UseDefMap {
-            all_definitions: self.all_definitions,
-            definitions_by_use: self.definitions_by_use,
-            public_definitions: self.definitions_by_symbol,
-        }
+    /// Remember a given definition for a given symbol in the given block.
+    fn memoize(
+        &mut self,
+        block_id: BasicBlockId,
+        symbol_id: ScopedSymbolId,
+        definition_id: Option<Definition<'db>>,
+    ) {
+        self.definitions_per_block[block_id].insert(symbol_id, definition_id);
+    }
+
+    /// Create an incomplete Phi for the given block and symbol, memoize it, and return its ID.
+    fn create_incomplete_phi(
+        &mut self,
+        block_id: BasicBlockId,
+        symbol_id: ScopedSymbolId,
+    ) -> Definition<'db> {
+        let phi_id = self.phi_operands.push(vec![]);
+        let definition = Definition::new(
+            self.db,
+            self.file,
+            self.file_scope,
+            symbol_id,
+            DefinitionKind::Phi(phi_id),
+            countme::Count::default(),
+        );
+        self.memoize(block_id, symbol_id, Some(definition));
+        definition
    }
 }
--- a/crates/red_knot_python_semantic/src/semantic_model.rs
+++ b/crates/red_knot_python_semantic/src/semantic_model.rs
@@ -1,6 +1,8 @@
-use ruff_db::files::File;
+use ruff_db::files::{File, FilePath};
+use ruff_db::source::line_index;
 use ruff_python_ast as ast;
 use ruff_python_ast::{Expr, ExpressionRef, StmtClassDef};
+use ruff_source_file::LineIndex;

 use crate::module_name::ModuleName;
 use crate::module_resolver::{resolve_module, Module};
@@ -25,6 +27,14 @@ impl<'db> SemanticModel<'db> {
        self.db
    }

+    pub fn file_path(&self) -> &FilePath {
+        self.file.path(self.db)
+    }
+
+    pub fn line_index(&self) -> LineIndex {
+        line_index(self.db.upcast(), self.file)
+    }
+
    pub fn resolve_module(&self, module_name: ModuleName) -> Option<Module> {
        resolve_module(self.db, module_name)
    }
@@ -141,7 +151,7 @@ impl HasTy for ast::StmtFunctionDef {
    fn ty<'db>(&self, model: &SemanticModel<'db>) -> Type<'db> {
        let index = semantic_index(model.db, model.file);
        let definition = index.definition(self);
-        definition_ty(model.db, definition)
+        definition_ty(model.db, Some(definition))
    }
 }

@@ -149,7 +159,7 @@ impl HasTy for StmtClassDef {
    fn ty<'db>(&self, model: &SemanticModel<'db>) -> Type<'db> {
        let index = semantic_index(model.db, model.file);
        let definition = index.definition(self);
-        definition_ty(model.db, definition)
+        definition_ty(model.db, Some(definition))
    }
 }

@@ -157,7 +167,7 @@ impl HasTy for ast::Alias {
    fn ty<'db>(&self, model: &SemanticModel<'db>) -> Type<'db> {
        let index = semantic_index(model.db, model.file);
        let definition = index.definition(self);
-        definition_ty(model.db, definition)
+        definition_ty(model.db, Some(definition))
    }
 }

@@ -165,34 +175,38 @@ impl HasTy for ast::Alias {
 mod tests {
    use ruff_db::files::system_path_to_file;
    use ruff_db::parsed::parsed_module;
-    use ruff_db::program::{Program, SearchPathSettings, TargetVersion};
    use ruff_db::system::{DbWithTestSystem, SystemPathBuf};

    use crate::db::tests::TestDb;
+    use crate::program::{Program, SearchPathSettings};
+    use crate::python_version::PythonVersion;
    use crate::types::Type;
-    use crate::{HasTy, SemanticModel};
+    use crate::{HasTy, ProgramSettings, SemanticModel};

-    fn setup_db() -> TestDb {
-        let db = TestDb::new();
-        Program::new(
+    fn setup_db<'a>(files: impl IntoIterator<Item = (&'a str, &'a str)>) -> anyhow::Result<TestDb> {
+        let mut db = TestDb::new();
+        db.write_files(files)?;
+
+        Program::from_settings(
            &db,
-            TargetVersion::Py38,
-            SearchPathSettings {
-                extra_paths: vec![],
-                src_root: SystemPathBuf::from("/src"),
-                site_packages: vec![],
-                custom_typeshed: None,
+            ProgramSettings {
+                target_version: PythonVersion::default(),
+                search_paths: SearchPathSettings {
+                    extra_paths: vec![],
+                    src_root: SystemPathBuf::from("/src"),
+                    site_packages: vec![],
+                    custom_typeshed: None,
+                },
            },
-        );
+        )?;

-        db
+        Ok(db)
    }

    #[test]
    fn function_ty() -> anyhow::Result<()> {
-        let mut db = setup_db();
+        let db = setup_db([("/src/foo.py", "def test(): pass")])?;

-        db.write_file("/src/foo.py", "def test(): pass")?;
        let foo = system_path_to_file(&db, "/src/foo.py").unwrap();

        let ast = parsed_module(&db, foo);
@@ -208,9 +222,8 @@ mod tests {

    #[test]
    fn class_ty() -> anyhow::Result<()> {
-        let mut db = setup_db();
+        let db = setup_db([("/src/foo.py", "class Test: pass")])?;

-        db.write_file("/src/foo.py", "class Test: pass")?;
        let foo = system_path_to_file(&db, "/src/foo.py").unwrap();

        let ast = parsed_module(&db, foo);
@@ -226,12 +239,11 @@ mod tests {

    #[test]
    fn alias_ty() -> anyhow::Result<()> {
-        let mut db = setup_db();
-
-        db.write_files([
+        let db = setup_db([
            ("/src/foo.py", "class Test: pass"),
            ("/src/bar.py", "from foo import Test"),
        ])?;
+
        let bar = system_path_to_file(&db, "/src/bar.py").unwrap();

        let ast = parsed_module(&db, bar);
--- a/crates/red_knot_python_semantic/src/types.rs
+++ b/crates/red_knot_python_semantic/src/types.rs
@@ -7,9 +7,11 @@ use crate::semantic_index::symbol::{ScopeId, ScopedSymbolId};
 use crate::semantic_index::{global_scope, symbol_table, use_def_map};
 use crate::{Db, FxOrderSet};

+mod builder;
 mod display;
 mod infer;

+pub(crate) use self::builder::UnionBuilder;
 pub(crate) use self::infer::{infer_definition_types, infer_scope_types};

 /// Infer the public type of a symbol (its type as seen from outside its scope).
@@ -21,13 +23,7 @@ pub(crate) fn symbol_ty<'db>(
    let _span = tracing::trace_span!("symbol_ty", ?symbol).entered();

    let use_def = use_def_map(db, scope);
-    definitions_ty(
-        db,
-        use_def.public_definitions(symbol),
-        use_def
-            .public_may_be_unbound(symbol)
-            .then_some(Type::Unbound),
-    )
+    definition_ty(db, use_def.public_definition(symbol))
 }

 /// Shorthand for `symbol_ty` that takes a symbol name instead of an ID.
@@ -58,49 +54,16 @@ pub(crate) fn builtins_symbol_ty_by_name<'db>(db: &'db dyn Db, name: &str) -> Ty
 }

 /// Infer the type of a [`Definition`].
-pub(crate) fn definition_ty<'db>(db: &'db dyn Db, definition: Definition<'db>) -> Type<'db> {
-    let inference = infer_definition_types(db, definition);
-    inference.definition_ty(definition)
-}
-
-/// Infer the combined type of an array of [`Definition`]s, plus one optional "unbound type".
-///
-/// Will return a union if there is more than one definition, or at least one plus an unbound
-/// type.
-///
-/// The "unbound type" represents the type in case control flow may not have passed through any
-/// definitions in this scope. If this isn't possible, then it will be `None`. If it is possible,
-/// and the result in that case should be Unbound (e.g. an unbound function local), then it will be
-/// `Some(Type::Unbound)`. If it is possible and the result should be something else (e.g. an
-/// implicit global lookup), then `unbound_type` will be `Some(the_global_symbol_type)`.
-///
-/// # Panics
-/// Will panic if called with zero definitions and no `unbound_ty`. This is a logic error,
-/// as any symbol with zero visible definitions clearly may be unbound, and the caller should
-/// provide an `unbound_ty`.
-pub(crate) fn definitions_ty<'db>(
+pub(crate) fn definition_ty<'db>(
    db: &'db dyn Db,
-    definitions: &[Definition<'db>],
-    unbound_ty: Option<Type<'db>>,
+    definition: Option<Definition<'db>>,
 ) -> Type<'db> {
-    let def_types = definitions.iter().map(|def| definition_ty(db, *def));
-    let mut all_types = unbound_ty.into_iter().chain(def_types);
-
-    let Some(first) = all_types.next() else {
-        panic!("definitions_ty should never be called with zero definitions and no unbound_ty.")
-    };
-
-    if let Some(second) = all_types.next() {
-        let mut builder = UnionTypeBuilder::new(db);
-        builder = builder.add(first).add(second);
-
-        for variant in all_types {
-            builder = builder.add(variant);
+    match definition {
+        Some(definition) => {
+            let inference = infer_definition_types(db, definition);
+            inference.definition_ty(definition)
        }
-
-        Type::Union(builder.build())
-    } else {
-        first
+        None => Type::Unbound,
    }
 }

@@ -117,7 +80,7 @@ pub enum Type<'db> {
    /// name does not exist or is not bound to any value (this represents an error, but with some
    /// leniency options it could be silently resolved to Unknown in some cases)
    Unbound,
-    /// the None object (TODO remove this in favor of Instance(types.NoneType)
+    /// the None object -- TODO remove this in favor of Instance(types.NoneType)
    None,
    /// a specific function object
    Function(FunctionType<'db>),
@@ -127,8 +90,11 @@ pub enum Type<'db> {
    Class(ClassType<'db>),
    /// the set of Python objects with the given class in their __class__'s method resolution order
    Instance(ClassType<'db>),
+    /// the set of objects in any of the types in the union
    Union(UnionType<'db>),
+    /// the set of objects in all of the types in the intersection
    Intersection(IntersectionType<'db>),
+    /// An integer literal
    IntLiteral(i64),
    /// A boolean literal, either `True` or `False`.
    BooleanLiteral(bool),
@@ -140,8 +106,27 @@ impl<'db> Type<'db> {
        matches!(self, Type::Unbound)
    }

-    pub const fn is_unknown(&self) -> bool {
-        matches!(self, Type::Unknown)
+    pub fn may_be_unbound(&self, db: &'db dyn Db) -> bool {
+        match self {
+            Type::Unbound => true,
+            Type::Union(union) => union.contains(db, Type::Unbound),
+            _ => false,
+        }
+    }
+
+    #[must_use]
+    pub fn replace_unbound_with(&self, db: &'db dyn Db, replacement: Type<'db>) -> Type<'db> {
+        match self {
+            Type::Unbound => replacement,
+            Type::Union(union) => union
+                .elements(db)
+                .into_iter()
+                .fold(UnionBuilder::new(db), |builder, ty| {
+                    builder.add(ty.replace_unbound_with(db, replacement))
+                })
+                .build(),
+            ty => *ty,
+        }
    }

    #[must_use]
@@ -159,15 +144,13 @@ impl<'db> Type<'db> {
                // TODO MRO? get_own_instance_member, get_instance_member
                todo!("attribute lookup on Instance type")
            }
-            Type::Union(union) => Type::Union(
-                union
-                    .elements(db)
-                    .iter()
-                    .fold(UnionTypeBuilder::new(db), |builder, element_ty| {
-                        builder.add(element_ty.member(db, name))
-                    })
-                    .build(),
-            ),
+            Type::Union(union) => union
+                .elements(db)
+                .iter()
+                .fold(UnionBuilder::new(db), |builder, element_ty| {
+                    builder.add(element_ty.member(db, name))
+                })
+                .build(),
            Type::Intersection(_) => {
                // TODO perform the get_member on each type in the intersection
                // TODO return the intersection of those results
@@ -251,7 +234,7 @@ impl<'db> ClassType<'db> {

 #[salsa::interned]
 pub struct UnionType<'db> {
-    /// the union type includes values in any of these types
+    /// The union type includes values in any of these types.
    elements: FxOrderSet<Type<'db>>,
 }

@@ -261,48 +244,15 @@ impl<'db> UnionType<'db> {
    }
 }

-struct UnionTypeBuilder<'db> {
-    elements: FxOrderSet<Type<'db>>,
-    db: &'db dyn Db,
-}
-
-impl<'db> UnionTypeBuilder<'db> {
-    fn new(db: &'db dyn Db) -> Self {
-        Self {
-            db,
-            elements: FxOrderSet::default(),
-        }
-    }
-
-    /// Adds a type to this union.
-    fn add(mut self, ty: Type<'db>) -> Self {
-        match ty {
-            Type::Union(union) => {
-                self.elements.extend(&union.elements(self.db));
-            }
-            _ => {
-                self.elements.insert(ty);
-            }
-        }
-
-        self
-    }
-
-    fn build(self) -> UnionType<'db> {
-        UnionType::new(self.db, self.elements)
-    }
-}
-
-// Negation types aren't expressible in annotations, and are most likely to arise from type
-// narrowing along with intersections (e.g. `if not isinstance(...)`), so we represent them
-// directly in intersections rather than as a separate type. This sacrifices some efficiency in the
-// case where a Not appears outside an intersection (unclear when that could even happen, but we'd
-// have to represent it as a single-element intersection if it did) in exchange for better
-// efficiency in the within-intersection case.
 #[salsa::interned]
 pub struct IntersectionType<'db> {
-    // the intersection type includes only values in all of these types
+    /// The intersection type includes only values in all of these types.
    positive: FxOrderSet<Type<'db>>,
-    // the intersection type does not include any value in any of these types
+
+    /// The intersection type does not include any value in any of these types.
+    ///
+    /// Negation types aren't expressible in annotations, and are most likely to arise from type
+    /// narrowing along with intersections (e.g. `if not isinstance(...)`), so we represent them
+    /// directly in intersections rather than as a separate type.
    negative: FxOrderSet<Type<'db>>,
 }
--- a/crates/red_knot_python_semantic/src/types/builder.rs
+++ b/crates/red_knot_python_semantic/src/types/builder.rs
@@ -0,0 +1,429 @@
+//! Smart builders for union and intersection types.
+//!
+//! Invariants we maintain here:
+//!   * No single-element union types (should just be the contained type instead.)
+//!   * No single-positive-element intersection types. Single-negative-element are OK, we don't
+//!     have a standalone negation type so there's no other representation for this.
+//!   * The same type should never appear more than once in a union or intersection. (This should
+//!     be expanded to cover subtyping -- see below -- but for now we only implement it for type
+//!     identity.)
+//!   * Disjunctive normal form (DNF): the tree of unions and intersections can never be deeper
+//!     than a union-of-intersections. Unions cannot contain other unions (the inner union just
+//!     flattens into the outer one), intersections cannot contain other intersections (also
+//!     flattens), and intersections cannot contain unions (the intersection distributes over the
+//!     union, inverting it into a union-of-intersections).
+//!
+//! The implication of these invariants is that a [`UnionBuilder`] does not necessarily build a
+//! [`Type::Union`]. For example, if only one type is added to the [`UnionBuilder`], `build()` will
+//! just return that type directly. The same is true for [`IntersectionBuilder`]; for example, if a
+//! union type is added to the intersection, it will distribute and [`IntersectionBuilder::build`]
+//! may end up returning a [`Type::Union`] of intersections.
+//!
+//! In the future we should have these additional invariants, but they aren't implemented yet:
+//!   * No type in a union can be a subtype of any other type in the union (just eliminate the
+//!     subtype from the union).
+//!   * No type in an intersection can be a supertype of any other type in the intersection (just
+//!     eliminate the supertype from the intersection).
+//!   * An intersection containing two non-overlapping types should simplify to [`Type::Never`].
+use crate::types::{IntersectionType, Type, UnionType};
+use crate::{Db, FxOrderSet};
+
+pub(crate) struct UnionBuilder<'db> {
+    elements: FxOrderSet<Type<'db>>,
+    db: &'db dyn Db,
+}
+
+impl<'db> UnionBuilder<'db> {
+    pub(crate) fn new(db: &'db dyn Db) -> Self {
+        Self {
+            db,
+            elements: FxOrderSet::default(),
+        }
+    }
+
+    /// Adds a type to this union.
+    pub(crate) fn add(mut self, ty: Type<'db>) -> Self {
+        match ty {
+            Type::Union(union) => {
+                self.elements.extend(&union.elements(self.db));
+            }
+            Type::Never => {}
+            _ => {
+                self.elements.insert(ty);
+            }
+        }
+
+        self
+    }
+
+    pub(crate) fn build(self) -> Type<'db> {
+        match self.elements.len() {
+            0 => Type::Never,
+            1 => self.elements[0],
+            _ => Type::Union(UnionType::new(self.db, self.elements)),
+        }
+    }
+}
+
+#[allow(unused)]
+#[derive(Clone)]
+pub(crate) struct IntersectionBuilder<'db> {
+    // Really this builds a union-of-intersections, because we always keep our set-theoretic types
+    // in disjunctive normal form (DNF), a union of intersections. In the simplest case there's
+    // just a single intersection in this vector, and we are building a single intersection type,
+    // but if a union is added to the intersection, we'll distribute ourselves over that union and
+    // create a union of intersections.
+    intersections: Vec<InnerIntersectionBuilder<'db>>,
+    db: &'db dyn Db,
+}
+
+impl<'db> IntersectionBuilder<'db> {
+    #[allow(dead_code)]
+    fn new(db: &'db dyn Db) -> Self {
+        Self {
+            db,
+            intersections: vec![InnerIntersectionBuilder::new()],
+        }
+    }
+
+    fn empty(db: &'db dyn Db) -> Self {
+        Self {
+            db,
+            intersections: vec![],
+        }
+    }
+
+    #[allow(dead_code)]
+    fn add_positive(mut self, ty: Type<'db>) -> Self {
+        if let Type::Union(union) = ty {
+            // Distribute ourself over this union: for each union element, clone ourself and
+            // intersect with that union element, then create a new union-of-intersections with all
+            // of those sub-intersections in it. E.g. if `self` is a simple intersection `T1 & T2`
+            // and we add `T3 | T4` to the intersection, we don't get `T1 & T2 & (T3 | T4)` (that's
+            // not in DNF), we distribute the union and get `(T1 & T3) | (T2 & T3) | (T1 & T4) |
+            // (T2 & T4)`. If `self` is already a union-of-intersections `(T1 & T2) | (T3 & T4)`
+            // and we add `T5 | T6` to it, that flattens all the way out to `(T1 & T2 & T5) | (T1 &
+            // T2 & T6) | (T3 & T4 & T5) ...` -- you get the idea.
+            union
+                .elements(self.db)
+                .iter()
+                .map(|elem| self.clone().add_positive(*elem))
+                .fold(IntersectionBuilder::empty(self.db), |mut builder, sub| {
+                    builder.intersections.extend(sub.intersections);
+                    builder
+                })
+        } else {
+            // If we are already a union-of-intersections, distribute the new intersected element
+            // across all of those intersections.
+            for inner in &mut self.intersections {
+                inner.add_positive(self.db, ty);
+            }
+            self
+        }
+    }
+
+    #[allow(dead_code)]
+    fn add_negative(mut self, ty: Type<'db>) -> Self {
+        // See comments above in `add_positive`; this is just the negated version.
+        if let Type::Union(union) = ty {
+            union
+                .elements(self.db)
+                .iter()
+                .map(|elem| self.clone().add_negative(*elem))
+                .fold(IntersectionBuilder::empty(self.db), |mut builder, sub| {
+                    builder.intersections.extend(sub.intersections);
+                    builder
+                })
+        } else {
+            for inner in &mut self.intersections {
+                inner.add_negative(self.db, ty);
+            }
+            self
+        }
+    }
+
+    #[allow(dead_code)]
+    fn build(mut self) -> Type<'db> {
+        // Avoid allocating the UnionBuilder unnecessarily if we have just one intersection:
+        if self.intersections.len() == 1 {
+            self.intersections.pop().unwrap().build(self.db)
+        } else {
+            let mut builder = UnionBuilder::new(self.db);
+            for inner in self.intersections {
+                builder = builder.add(inner.build(self.db));
+            }
+            builder.build()
+        }
+    }
+}
+
+#[allow(unused)]
+#[derive(Debug, Clone, Default)]
+struct InnerIntersectionBuilder<'db> {
+    positive: FxOrderSet<Type<'db>>,
+    negative: FxOrderSet<Type<'db>>,
+}
+
+impl<'db> InnerIntersectionBuilder<'db> {
+    fn new() -> Self {
+        Self::default()
+    }
+
+    /// Adds a positive type to this intersection.
+    fn add_positive(&mut self, db: &'db dyn Db, ty: Type<'db>) {
+        match ty {
+            Type::Intersection(inter) => {
+                let pos = inter.positive(db);
+                let neg = inter.negative(db);
+                self.positive.extend(pos.difference(&self.negative));
+                self.negative.extend(neg.difference(&self.positive));
+                self.positive.retain(|elem| !neg.contains(elem));
+                self.negative.retain(|elem| !pos.contains(elem));
+            }
+            _ => {
+                if !self.negative.remove(&ty) {
+                    self.positive.insert(ty);
+                };
+            }
+        }
+    }
+
+    /// Adds a negative type to this intersection.
+    fn add_negative(&mut self, db: &'db dyn Db, ty: Type<'db>) {
+        // TODO Any/Unknown actually should not self-cancel
+        match ty {
+            Type::Intersection(intersection) => {
+                let pos = intersection.negative(db);
+                let neg = intersection.positive(db);
+                self.positive.extend(pos.difference(&self.negative));
+                self.negative.extend(neg.difference(&self.positive));
+                self.positive.retain(|elem| !neg.contains(elem));
+                self.negative.retain(|elem| !pos.contains(elem));
+            }
+            Type::Never => {}
+            _ => {
+                if !self.positive.remove(&ty) {
+                    self.negative.insert(ty);
+                };
+            }
+        }
+    }
+
+    fn simplify(&mut self) {
+        // TODO this should be generalized based on subtyping, for now we just handle a few cases
+
+        // Never is a subtype of all types
+        if self.positive.contains(&Type::Never) {
+            self.positive.clear();
+            self.negative.clear();
+            self.positive.insert(Type::Never);
+        }
+    }
+
+    fn build(mut self, db: &'db dyn Db) -> Type<'db> {
+        self.simplify();
+        match (self.positive.len(), self.negative.len()) {
+            (0, 0) => Type::Never,
+            (1, 0) => self.positive[0],
+            _ => {
+                self.positive.shrink_to_fit();
+                self.negative.shrink_to_fit();
+                Type::Intersection(IntersectionType::new(db, self.positive, self.negative))
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{IntersectionBuilder, IntersectionType, Type, UnionBuilder, UnionType};
+    use crate::db::tests::TestDb;
+
+    fn setup_db() -> TestDb {
+        TestDb::new()
+    }
+
+    impl<'db> UnionType<'db> {
+        fn elements_vec(self, db: &'db TestDb) -> Vec<Type<'db>> {
+            self.elements(db).into_iter().collect()
+        }
+    }
+
+    #[test]
+    fn build_union() {
+        let db = setup_db();
+        let t0 = Type::IntLiteral(0);
+        let t1 = Type::IntLiteral(1);
+        let Type::Union(union) = UnionBuilder::new(&db).add(t0).add(t1).build() else {
+            panic!("expected a union");
+        };
+
+        assert_eq!(union.elements_vec(&db), &[t0, t1]);
+    }
+
+    #[test]
+    fn build_union_single() {
+        let db = setup_db();
+        let t0 = Type::IntLiteral(0);
+        let ty = UnionBuilder::new(&db).add(t0).build();
+
+        assert_eq!(ty, t0);
+    }
+
+    #[test]
+    fn build_union_empty() {
+        let db = setup_db();
+        let ty = UnionBuilder::new(&db).build();
+
+        assert_eq!(ty, Type::Never);
+    }
+
+    #[test]
+    fn build_union_never() {
+        let db = setup_db();
+        let t0 = Type::IntLiteral(0);
+        let ty = UnionBuilder::new(&db).add(t0).add(Type::Never).build();
+
+        assert_eq!(ty, t0);
+    }
+
+    #[test]
+    fn build_union_flatten() {
+        let db = setup_db();
+        let t0 = Type::IntLiteral(0);
+        let t1 = Type::IntLiteral(1);
+        let t2 = Type::IntLiteral(2);
+        let u1 = UnionBuilder::new(&db).add(t0).add(t1).build();
+        let Type::Union(union) = UnionBuilder::new(&db).add(u1).add(t2).build() else {
+            panic!("expected a union");
+        };
+
+        assert_eq!(union.elements_vec(&db), &[t0, t1, t2]);
+    }
+
+    impl<'db> IntersectionType<'db> {
+        fn pos_vec(self, db: &'db TestDb) -> Vec<Type<'db>> {
+            self.positive(db).into_iter().collect()
+        }
+
+        fn neg_vec(self, db: &'db TestDb) -> Vec<Type<'db>> {
+            self.negative(db).into_iter().collect()
+        }
+    }
+
+    #[test]
+    fn build_intersection() {
+        let db = setup_db();
+        let t0 = Type::IntLiteral(0);
+        let ta = Type::Any;
+        let Type::Intersection(inter) = IntersectionBuilder::new(&db)
+            .add_positive(ta)
+            .add_negative(t0)
+            .build()
+        else {
+            panic!("expected to be an intersection");
+        };
+
+        assert_eq!(inter.pos_vec(&db), &[ta]);
+        assert_eq!(inter.neg_vec(&db), &[t0]);
+    }
+
+    #[test]
+    fn build_intersection_flatten_positive() {
+        let db = setup_db();
+        let ta = Type::Any;
+        let t1 = Type::IntLiteral(1);
+        let t2 = Type::IntLiteral(2);
+        let i0 = IntersectionBuilder::new(&db)
+            .add_positive(ta)
+            .add_negative(t1)
+            .build();
+        let Type::Intersection(inter) = IntersectionBuilder::new(&db)
+            .add_positive(t2)
+            .add_positive(i0)
+            .build()
+        else {
+            panic!("expected to be an intersection");
+        };
+
+        assert_eq!(inter.pos_vec(&db), &[t2, ta]);
+        assert_eq!(inter.neg_vec(&db), &[t1]);
+    }
+
+    #[test]
+    fn build_intersection_flatten_negative() {
+        let db = setup_db();
+        let ta = Type::Any;
+        let t1 = Type::IntLiteral(1);
+        let t2 = Type::IntLiteral(2);
+        let i0 = IntersectionBuilder::new(&db)
+            .add_positive(ta)
+            .add_negative(t1)
+            .build();
+        let Type::Intersection(inter) = IntersectionBuilder::new(&db)
+            .add_positive(t2)
+            .add_negative(i0)
+            .build()
+        else {
+            panic!("expected to be an intersection");
+        };
+
+        assert_eq!(inter.pos_vec(&db), &[t2, t1]);
+        assert_eq!(inter.neg_vec(&db), &[ta]);
+    }
+
+    #[test]
+    fn intersection_distributes_over_union() {
+        let db = setup_db();
+        let t0 = Type::IntLiteral(0);
+        let t1 = Type::IntLiteral(1);
+        let ta = Type::Any;
+        let u0 = UnionBuilder::new(&db).add(t0).add(t1).build();
+
+        let Type::Union(union) = IntersectionBuilder::new(&db)
+            .add_positive(ta)
+            .add_positive(u0)
+            .build()
+        else {
+            panic!("expected a union");
+        };
+        let [Type::Intersection(i0), Type::Intersection(i1)] = union.elements_vec(&db)[..] else {
+            panic!("expected a union of two intersections");
+        };
+        assert_eq!(i0.pos_vec(&db), &[ta, t0]);
+        assert_eq!(i1.pos_vec(&db), &[ta, t1]);
+    }
+
+    #[test]
+    fn build_intersection_self_negation() {
+        let db = setup_db();
+        let ty = IntersectionBuilder::new(&db)
+            .add_positive(Type::None)
+            .add_negative(Type::None)
+            .build();
+
+        assert_eq!(ty, Type::Never);
+    }
+
+    #[test]
+    fn build_intersection_simplify_negative_never() {
+        let db = setup_db();
+        let ty = IntersectionBuilder::new(&db)
+            .add_positive(Type::None)
+            .add_negative(Type::Never)
+            .build();
+
+        assert_eq!(ty, Type::None);
+    }
+
+    #[test]
+    fn build_intersection_simplify_positive_never() {
+        let db = setup_db();
+        let ty = IntersectionBuilder::new(&db)
+            .add_positive(Type::None)
+            .add_positive(Type::Never)
+            .build();
+
+        assert_eq!(ty, Type::Never);
+    }
+}
--- a/crates/red_knot_python_semantic/src/types/infer.rs
+++ b/crates/red_knot_python_semantic/src/types/infer.rs
@@ -33,14 +33,18 @@ use crate::builtins::builtins_scope;
 use crate::module_name::ModuleName;
 use crate::module_resolver::resolve_module;
 use crate::semantic_index::ast_ids::{HasScopedAstId, HasScopedUseId, ScopedExpressionId};
-use crate::semantic_index::definition::{Definition, DefinitionKind, DefinitionNodeKey};
+use crate::semantic_index::definition::{
+    Definition, DefinitionKind, DefinitionNode, DefinitionNodeKey, ScopedPhiId,
+};
 use crate::semantic_index::expression::Expression;
 use crate::semantic_index::semantic_index;
-use crate::semantic_index::symbol::{FileScopeId, NodeWithScopeKind, NodeWithScopeRef, ScopeId};
+use crate::semantic_index::symbol::{
+    FileScopeId, NodeWithScopeKind, NodeWithScopeRef, ScopeId, Symbol,
+};
 use crate::semantic_index::SemanticIndex;
 use crate::types::{
-    builtins_symbol_ty_by_name, definitions_ty, global_symbol_ty_by_name, ClassType, FunctionType,
-    Name, Type, UnionTypeBuilder,
+    builtins_symbol_ty_by_name, definition_ty, global_symbol_ty_by_name, ClassType, FunctionType,
+    Name, Type, UnionBuilder,
 };
 use crate::Db;

@@ -61,7 +65,7 @@ pub(crate) fn infer_scope_types<'db>(db: &'db dyn Db, scope: ScopeId<'db>) -> Ty
    TypeInferenceBuilder::new(db, InferenceRegion::Scope(scope), index).finish()
 }

-/// Cycle recovery for [`infer_definition_types`]: for now, just [`Type::Unknown`]
+/// Cycle recovery for [`infer_definition_types()`]: for now, just [`Type::Unknown`]
 /// TODO fixpoint iteration
 fn infer_definition_types_cycle_recovery<'db>(
    _db: &'db dyn Db,
@@ -260,34 +264,61 @@ impl<'db> TypeInferenceBuilder<'db> {
            NodeWithScopeKind::FunctionTypeParameters(function) => {
                self.infer_function_type_params(function.node());
            }
+            NodeWithScopeKind::ListComprehension(comprehension) => {
+                self.infer_list_comprehension_expression_scope(comprehension.node());
+            }
+            NodeWithScopeKind::SetComprehension(comprehension) => {
+                self.infer_set_comprehension_expression_scope(comprehension.node());
+            }
+            NodeWithScopeKind::DictComprehension(comprehension) => {
+                self.infer_dict_comprehension_expression_scope(comprehension.node());
+            }
+            NodeWithScopeKind::GeneratorExpression(generator) => {
+                self.infer_generator_expression_scope(generator.node());
+            }
        }
    }

    fn infer_region_definition(&mut self, definition: Definition<'db>) {
-        match definition.node(self.db) {
-            DefinitionKind::Function(function) => {
-                self.infer_function_definition(function.node(), definition);
-            }
-            DefinitionKind::Class(class) => self.infer_class_definition(class.node(), definition),
-            DefinitionKind::Import(import) => {
-                self.infer_import_definition(import.node(), definition);
-            }
-            DefinitionKind::ImportFrom(import_from) => {
-                self.infer_import_from_definition(
-                    import_from.import(),
-                    import_from.alias(),
-                    definition,
-                );
-            }
-            DefinitionKind::Assignment(assignment) => {
-                self.infer_assignment_definition(assignment.assignment(), definition);
-            }
-            DefinitionKind::AnnotatedAssignment(annotated_assignment) => {
-                self.infer_annotated_assignment_definition(annotated_assignment.node(), definition);
-            }
-            DefinitionKind::NamedExpression(named_expression) => {
-                self.infer_named_expression_definition(named_expression.node(), definition);
-            }
+        match definition.kind(self.db) {
+            DefinitionKind::Phi(phi_id) => self.infer_phi_definition(*phi_id, definition),
+            DefinitionKind::Node(node) => match node {
+                DefinitionNode::Function(function) => {
+                    self.infer_function_definition(function.node(), definition);
+                }
+                DefinitionNode::Class(class) => {
+                    self.infer_class_definition(class.node(), definition);
+                }
+                DefinitionNode::Import(import) => {
+                    self.infer_import_definition(import.node(), definition);
+                }
+                DefinitionNode::ImportFrom(import_from) => {
+                    self.infer_import_from_definition(
+                        import_from.import(),
+                        import_from.alias(),
+                        definition,
+                    );
+                }
+                DefinitionNode::Assignment(assignment) => {
+                    self.infer_assignment_definition(assignment.assignment(), definition);
+                }
+                DefinitionNode::AnnotatedAssignment(annotated_assignment) => {
+                    self.infer_annotated_assignment_definition(
+                        annotated_assignment.node(),
+                        definition,
+                    );
+                }
+                DefinitionNode::NamedExpression(named_expression) => {
+                    self.infer_named_expression_definition(named_expression.node(), definition);
+                }
+                DefinitionNode::Comprehension(comprehension) => {
+                    self.infer_comprehension_definition(
+                        comprehension.node(),
+                        comprehension.is_first(),
+                        definition,
+                    );
+                }
+            },
        }
    }

@@ -377,6 +408,18 @@ impl<'db> TypeInferenceBuilder<'db> {
        self.extend(result);
    }

+    fn infer_phi_definition(&mut self, phi_id: ScopedPhiId, definition: Definition<'db>) {
+        let file_scope_id = self.scope.file_scope_id(self.db);
+        let use_def = self.index.use_def_map(file_scope_id);
+        let ty = use_def
+            .phi_operands(phi_id)
+            .iter()
+            .map(|&definition| definition_ty(self.db, definition))
+            .fold(UnionBuilder::new(self.db), UnionBuilder::add)
+            .build();
+        self.types.definitions.insert(definition, ty);
+    }
+
    fn infer_function_definition_statement(&mut self, function: &ast::StmtFunctionDef) {
        self.infer_definition(function);
    }
@@ -923,7 +966,6 @@ impl<'db> TypeInferenceBuilder<'db> {
        ty
    }

-    #[allow(clippy::unused_self)]
    fn infer_number_literal_expression(&mut self, literal: &ast::ExprNumberLiteral) -> Type<'db> {
        let ast::ExprNumberLiteral { range: _, value } = literal;

@@ -1054,18 +1096,24 @@ impl<'db> TypeInferenceBuilder<'db> {
        builtins_symbol_ty_by_name(self.db, "dict").instance()
    }

+    /// Infer the type of the `iter` expression of the first comprehension.
+    fn infer_first_comprehension_iter(&mut self, comprehensions: &[ast::Comprehension]) {
+        let mut generators_iter = comprehensions.iter();
+        let Some(first_generator) = generators_iter.next() else {
+            unreachable!("Comprehension must contain at least one generator");
+        };
+        self.infer_expression(&first_generator.iter);
+    }
+
    fn infer_generator_expression(&mut self, generator: &ast::ExprGenerator) -> Type<'db> {
        let ast::ExprGenerator {
            range: _,
-            elt,
+            elt: _,
            generators,
            parenthesized: _,
        } = generator;

-        self.infer_expression(elt);
-        for generator in generators {
-            self.infer_comprehension(generator);
-        }
+        self.infer_first_comprehension_iter(generators);

        // TODO generator type
        Type::Unknown
@@ -1074,20 +1122,71 @@ impl<'db> TypeInferenceBuilder<'db> {
    fn infer_list_comprehension_expression(&mut self, listcomp: &ast::ExprListComp) -> Type<'db> {
        let ast::ExprListComp {
            range: _,
-            elt,
+            elt: _,
            generators,
        } = listcomp;

-        self.infer_expression(elt);
-        for generator in generators {
-            self.infer_comprehension(generator);
-        }
+        self.infer_first_comprehension_iter(generators);

        // TODO list type
        Type::Unknown
    }

    fn infer_dict_comprehension_expression(&mut self, dictcomp: &ast::ExprDictComp) -> Type<'db> {
+        let ast::ExprDictComp {
+            range: _,
+            key: _,
+            value: _,
+            generators,
+        } = dictcomp;
+
+        self.infer_first_comprehension_iter(generators);
+
+        // TODO dict type
+        Type::Unknown
+    }
+
+    fn infer_set_comprehension_expression(&mut self, setcomp: &ast::ExprSetComp) -> Type<'db> {
+        let ast::ExprSetComp {
+            range: _,
+            elt: _,
+            generators,
+        } = setcomp;
+
+        self.infer_first_comprehension_iter(generators);
+
+        // TODO set type
+        Type::Unknown
+    }
+
+    fn infer_generator_expression_scope(&mut self, generator: &ast::ExprGenerator) {
+        let ast::ExprGenerator {
+            range: _,
+            elt,
+            generators,
+            parenthesized: _,
+        } = generator;
+
+        self.infer_expression(elt);
+        for comprehension in generators {
+            self.infer_comprehension(comprehension);
+        }
+    }
+
+    fn infer_list_comprehension_expression_scope(&mut self, listcomp: &ast::ExprListComp) {
+        let ast::ExprListComp {
+            range: _,
+            elt,
+            generators,
+        } = listcomp;
+
+        self.infer_expression(elt);
+        for comprehension in generators {
+            self.infer_comprehension(comprehension);
+        }
+    }
+
+    fn infer_dict_comprehension_expression_scope(&mut self, dictcomp: &ast::ExprDictComp) {
        let ast::ExprDictComp {
            range: _,
            key,
@@ -1097,46 +1196,51 @@ impl<'db> TypeInferenceBuilder<'db> {

        self.infer_expression(key);
        self.infer_expression(value);
-        for generator in generators {
-            self.infer_comprehension(generator);
+        for comprehension in generators {
+            self.infer_comprehension(comprehension);
        }
-
-        // TODO dict type
-        Type::Unknown
    }

-    fn infer_set_comprehension_expression(&mut self, setcomp: &ast::ExprSetComp) -> Type<'db> {
+    fn infer_set_comprehension_expression_scope(&mut self, setcomp: &ast::ExprSetComp) {
        let ast::ExprSetComp {
            range: _,
            elt,
            generators,
        } = setcomp;
-        self.infer_expression(elt);
-        for generator in generators {
-            self.infer_comprehension(generator);
-        }

-        // TODO set type
-        Type::Unknown
+        self.infer_expression(elt);
+        for comprehension in generators {
+            self.infer_comprehension(comprehension);
+        }
    }

-    fn infer_comprehension(&mut self, comprehension: &ast::Comprehension) -> Type<'db> {
+    fn infer_comprehension(&mut self, comprehension: &ast::Comprehension) {
+        self.infer_definition(comprehension);
+        for expr in &comprehension.ifs {
+            self.infer_expression(expr);
+        }
+    }
+
+    fn infer_comprehension_definition(
+        &mut self,
+        comprehension: &ast::Comprehension,
+        is_first: bool,
+        definition: Definition<'db>,
+    ) {
        let ast::Comprehension {
            range: _,
            target,
            iter,
-            ifs,
+            ifs: _,
            is_async: _,
        } = comprehension;

-        self.infer_expression(target);
-        self.infer_expression(iter);
-        for if_clause in ifs {
-            self.infer_expression(if_clause);
+        if !is_first {
+            self.infer_expression(iter);
        }
-
-        // TODO comprehension type
-        Type::Unknown
+        // TODO(dhruvmanila): The target type should be inferred based on the iter type instead.
+        let target_ty = self.infer_expression(target);
+        self.types.definitions.insert(definition, target_ty);
    }

    fn infer_named_expression(&mut self, named: &ast::ExprNamed) -> Type<'db> {
@@ -1179,12 +1283,10 @@ impl<'db> TypeInferenceBuilder<'db> {
        let body_ty = self.infer_expression(body);
        let orelse_ty = self.infer_expression(orelse);

-        let union = UnionTypeBuilder::new(self.db)
+        UnionBuilder::new(self.db)
            .add(body_ty)
            .add(orelse_ty)
-            .build();
-
-        Type::Union(union)
+            .build()
    }

    fn infer_lambda_body(&mut self, lambda_expression: &ast::ExprLambda) {
@@ -1260,6 +1362,22 @@ impl<'db> TypeInferenceBuilder<'db> {
        Type::Unknown
    }

+    fn infer_global_name_reference(&self, symbol: &Symbol) -> Type<'db> {
+        let file_scope_id = self.scope.file_scope_id(self.db);
+        // implicit global
+        let mut ty = if file_scope_id == FileScopeId::global() {
+            Type::Unbound
+        } else {
+            global_symbol_ty_by_name(self.db, self.file, symbol.name())
+        };
+        // fallback to builtins
+        if ty.may_be_unbound(self.db) && Some(self.scope) != builtins_scope(self.db) {
+            ty = ty
+                .replace_unbound_with(self.db, builtins_symbol_ty_by_name(self.db, symbol.name()));
+        }
+        ty
+    }
+
    fn infer_name_expression(&mut self, name: &ast::ExprName) -> Type<'db> {
        let ast::ExprName { range: _, id, ctx } = name;

@@ -1268,34 +1386,18 @@ impl<'db> TypeInferenceBuilder<'db> {
                let file_scope_id = self.scope.file_scope_id(self.db);
                let use_def = self.index.use_def_map(file_scope_id);
                let use_id = name.scoped_use_id(self.db, self.scope);
-                let may_be_unbound = use_def.use_may_be_unbound(use_id);
-
-                let unbound_ty = if may_be_unbound {
+                let mut ty = definition_ty(self.db, use_def.definition_for_use(use_id));
+                if ty.may_be_unbound(self.db) {
                    let symbols = self.index.symbol_table(file_scope_id);
-                    // SAFETY: the symbol table always creates a symbol for every Name node.
                    let symbol = symbols.symbol_by_name(id).unwrap();
                    if !symbol.is_defined() || !self.scope.is_function_like(self.db) {
-                        // implicit global
-                        let mut unbound_ty = if file_scope_id == FileScopeId::global() {
-                            Type::Unbound
-                        } else {
-                            global_symbol_ty_by_name(self.db, self.file, id)
-                        };
-                        // fallback to builtins
-                        if matches!(unbound_ty, Type::Unbound)
-                            && Some(self.scope) != builtins_scope(self.db)
-                        {
-                            unbound_ty = builtins_symbol_ty_by_name(self.db, id);
-                        }
-                        Some(unbound_ty)
-                    } else {
-                        Some(Type::Unbound)
+                        ty = ty.replace_unbound_with(
+                            self.db,
+                            self.infer_global_name_reference(symbol),
+                        );
                    }
-                } else {
-                    None
-                };
-
-                definitions_ty(self.db, use_def.use_definitions(use_id), unbound_ty)
+                }
+                ty
            }
            ExprContext::Store | ExprContext::Del => Type::None,
            ExprContext::Invalid => Type::Unknown,
@@ -1494,53 +1596,73 @@ impl<'db> TypeInferenceBuilder<'db> {

 #[cfg(test)]
 mod tests {
+    use anyhow::Context;
    use ruff_db::files::{system_path_to_file, File};
    use ruff_db::parsed::parsed_module;
-    use ruff_db::program::{Program, SearchPathSettings, TargetVersion};
    use ruff_db::system::{DbWithTestSystem, SystemPathBuf};
    use ruff_db::testing::assert_function_query_was_not_run;
    use ruff_python_ast::name::Name;

    use crate::builtins::builtins_scope;
    use crate::db::tests::TestDb;
+    use crate::program::{Program, SearchPathSettings};
+    use crate::python_version::PythonVersion;
    use crate::semantic_index::definition::Definition;
    use crate::semantic_index::symbol::FileScopeId;
    use crate::semantic_index::{global_scope, semantic_index, symbol_table, use_def_map};
    use crate::types::{global_symbol_ty_by_name, infer_definition_types, symbol_ty_by_name, Type};
-    use crate::{HasTy, SemanticModel};
+    use crate::{HasTy, ProgramSettings, SemanticModel};

    fn setup_db() -> TestDb {
        let db = TestDb::new();

-        Program::new(
+        let src_root = SystemPathBuf::from("/src");
+        db.memory_file_system()
+            .create_directory_all(&src_root)
+            .unwrap();
+
+        Program::from_settings(
            &db,
-            TargetVersion::Py38,
-            SearchPathSettings {
-                extra_paths: Vec::new(),
-                src_root: SystemPathBuf::from("/src"),
-                site_packages: vec![],
-                custom_typeshed: None,
+            ProgramSettings {
+                target_version: PythonVersion::default(),
+                search_paths: SearchPathSettings {
+                    extra_paths: Vec::new(),
+                    src_root,
+                    site_packages: vec![],
+                    custom_typeshed: None,
+                },
            },
-        );
+        )
+        .expect("Valid search path settings");

        db
    }

-    fn setup_db_with_custom_typeshed(typeshed: &str) -> TestDb {
-        let db = TestDb::new();
+    fn setup_db_with_custom_typeshed<'a>(
+        typeshed: &str,
+        files: impl IntoIterator<Item = (&'a str, &'a str)>,
+    ) -> anyhow::Result<TestDb> {
+        let mut db = TestDb::new();
+        let src_root = SystemPathBuf::from("/src");

-        Program::new(
+        db.write_files(files)
+            .context("Failed to write test files")?;
+
+        Program::from_settings(
            &db,
-            TargetVersion::Py38,
-            SearchPathSettings {
-                extra_paths: Vec::new(),
-                src_root: SystemPathBuf::from("/src"),
-                site_packages: vec![],
-                custom_typeshed: Some(SystemPathBuf::from(typeshed)),
+            ProgramSettings {
+                target_version: PythonVersion::default(),
+                search_paths: SearchPathSettings {
+                    extra_paths: Vec::new(),
+                    src_root,
+                    site_packages: vec![],
+                    custom_typeshed: Some(SystemPathBuf::from(typeshed)),
+                },
            },
-        );
+        )
+        .context("Failed to create Program")?;

-        db
+        Ok(db)
    }

    fn assert_public_ty(db: &TestDb, file_name: &str, symbol_name: &str, expected: &str) {
@@ -2065,6 +2187,38 @@ mod tests {
        Ok(())
    }

+    #[test]
+    fn conditionally_global_or_builtin() -> anyhow::Result<()> {
+        let mut db = setup_db();
+
+        db.write_dedented(
+            "/src/a.py",
+            "
+            if flag:
+                copyright = 1
+            def f():
+                y = copyright
+            ",
+        )?;
+
+        let file = system_path_to_file(&db, "src/a.py").expect("Expected file to exist.");
+        let index = semantic_index(&db, file);
+        let function_scope = index
+            .child_scopes(FileScopeId::global())
+            .next()
+            .unwrap()
+            .0
+            .to_scope_id(&db, file);
+        let y_ty = symbol_ty_by_name(&db, function_scope, "y");
+
+        assert_eq!(
+            y_ty.display(&db).to_string(),
+            "Literal[1] | Literal[copyright]"
+        );
+
+        Ok(())
+    }
+
    /// Class name lookups do fall back to globals, but the public type never does.
    #[test]
    fn unbound_class_local() -> anyhow::Result<()> {
@@ -2130,16 +2284,17 @@ mod tests {

    #[test]
    fn builtin_symbol_custom_stdlib() -> anyhow::Result<()> {
-        let mut db = setup_db_with_custom_typeshed("/typeshed");
-
-        db.write_files([
-            ("/src/a.py", "c = copyright"),
-            (
-                "/typeshed/stdlib/builtins.pyi",
-                "def copyright() -> None: ...",
-            ),
-            ("/typeshed/stdlib/VERSIONS", "builtins: 3.8-"),
-        ])?;
+        let db = setup_db_with_custom_typeshed(
+            "/typeshed",
+            [
+                ("/src/a.py", "c = copyright"),
+                (
+                    "/typeshed/stdlib/builtins.pyi",
+                    "def copyright() -> None: ...",
+                ),
+                ("/typeshed/stdlib/VERSIONS", "builtins: 3.8-"),
+            ],
+        )?;

        assert_public_ty(&db, "/src/a.py", "c", "Literal[copyright]");

@@ -2159,13 +2314,14 @@ mod tests {

    #[test]
    fn unknown_builtin_later_defined() -> anyhow::Result<()> {
-        let mut db = setup_db_with_custom_typeshed("/typeshed");
-
-        db.write_files([
-            ("/src/a.py", "x = foo"),
-            ("/typeshed/stdlib/builtins.pyi", "foo = bar; bar = 1"),
-            ("/typeshed/stdlib/VERSIONS", "builtins: 3.8-"),
-        ])?;
+        let db = setup_db_with_custom_typeshed(
+            "/typeshed",
+            [
+                ("/src/a.py", "x = foo"),
+                ("/typeshed/stdlib/builtins.pyi", "foo = bar; bar = 1"),
+                ("/typeshed/stdlib/VERSIONS", "builtins: 3.8-"),
+            ],
+        )?;

        assert_public_ty(&db, "/src/a.py", "x", "Unbound");

@@ -2286,11 +2442,10 @@ mod tests {
        Ok(())
    }

-    fn first_public_def<'db>(db: &'db TestDb, file: File, name: &str) -> Definition<'db> {
+    fn public_def<'db>(db: &'db TestDb, file: File, name: &str) -> Definition<'db> {
        let scope = global_scope(db, file);
-        *use_def_map(db, scope)
-            .public_definitions(symbol_table(db, scope).symbol_id_by_name(name).unwrap())
-            .first()
+        use_def_map(db, scope)
+            .public_definition(symbol_table(db, scope).symbol_id_by_name(name).unwrap())
            .unwrap()
    }

@@ -2433,7 +2588,7 @@ mod tests {
        assert_function_query_was_not_run(
            &db,
            infer_definition_types,
-            first_public_def(&db, a, "x"),
+            public_def(&db, a, "x"),
            &events,
        );

@@ -2469,7 +2624,7 @@ mod tests {
        assert_function_query_was_not_run(
            &db,
            infer_definition_types,
-            first_public_def(&db, a, "x"),
+            public_def(&db, a, "x"),
            &events,
        );
        Ok(())
--- a/crates/red_knot_server/Cargo.toml
+++ b/crates/red_knot_server/Cargo.toml
@@ -11,6 +11,7 @@ repository = { workspace = true }
 license = { workspace = true }

 [dependencies]
+red_knot_python_semantic = { workspace = true }
 red_knot_workspace = { workspace = true }
 ruff_db = { workspace = true }
 ruff_linter = { workspace = true }
--- a/crates/red_knot_server/src/edit/notebook.rs
+++ b/crates/red_knot_server/src/edit/notebook.rs
@@ -1,5 +1,6 @@
 use anyhow::Ok;
 use lsp_types::NotebookCellKind;
+use ruff_notebook::CellMetadata;
 use rustc_hash::{FxBuildHasher, FxHashMap};

 use crate::{PositionEncoding, TextDocument};
@@ -65,7 +66,7 @@ impl NotebookDocument {
                NotebookCellKind::Code => ruff_notebook::Cell::Code(ruff_notebook::CodeCell {
                    execution_count: None,
                    id: None,
-                    metadata: serde_json::Value::Null,
+                    metadata: CellMetadata::default(),
                    outputs: vec![],
                    source: ruff_notebook::SourceValue::String(
                        cell.document.contents().to_string(),
@@ -75,7 +76,7 @@ impl NotebookDocument {
                    ruff_notebook::Cell::Markdown(ruff_notebook::MarkdownCell {
                        attachments: None,
                        id: None,
-                        metadata: serde_json::Value::Null,
+                        metadata: CellMetadata::default(),
                        source: ruff_notebook::SourceValue::String(
                            cell.document.contents().to_string(),
                        ),
--- a/crates/red_knot_server/src/server/api/requests/diagnostic.rs
+++ b/crates/red_knot_server/src/server/api/requests/diagnostic.rs
@@ -2,8 +2,9 @@ use std::borrow::Cow;

 use lsp_types::request::DocumentDiagnosticRequest;
 use lsp_types::{
-    Diagnostic, DocumentDiagnosticParams, DocumentDiagnosticReport, DocumentDiagnosticReportResult,
-    FullDocumentDiagnosticReport, Range, RelatedFullDocumentDiagnosticReport, Url,
+    Diagnostic, DiagnosticSeverity, DocumentDiagnosticParams, DocumentDiagnosticReport,
+    DocumentDiagnosticReportResult, FullDocumentDiagnosticReport, Position, Range,
+    RelatedFullDocumentDiagnosticReport, Url,
 };

 use red_knot_workspace::db::RootDatabase;
@@ -56,16 +57,37 @@ fn compute_diagnostics(snapshot: &DocumentSnapshot, db: &RootDatabase) -> Vec<Di
    diagnostics
        .as_slice()
        .iter()
-        .map(|message| Diagnostic {
-            range: Range::default(),
-            severity: None,
-            tags: None,
-            code: None,
-            code_description: None,
-            source: Some("red-knot".into()),
-            message: message.to_string(),
-            related_information: None,
-            data: None,
-        })
+        .map(|message| to_lsp_diagnostic(message))
        .collect()
 }
+
+fn to_lsp_diagnostic(message: &str) -> Diagnostic {
+    let words = message.split(':').collect::<Vec<_>>();
+
+    let (range, message) = match words.as_slice() {
+        [_filename, line, column, message] => {
+            let line = line.parse::<u32>().unwrap_or_default();
+            let column = column.parse::<u32>().unwrap_or_default();
+            (
+                Range::new(
+                    Position::new(line.saturating_sub(1), column.saturating_sub(1)),
+                    Position::new(line, column),
+                ),
+                message.trim(),
+            )
+        }
+        _ => (Range::default(), message),
+    };
+
+    Diagnostic {
+        range,
+        severity: Some(DiagnosticSeverity::ERROR),
+        tags: None,
+        code: None,
+        code_description: None,
+        source: Some("red-knot".into()),
+        message: message.to_string(),
+        related_information: None,
+        data: None,
+    }
+}
--- a/crates/red_knot_server/src/session.rs
+++ b/crates/red_knot_server/src/session.rs
@@ -8,10 +8,10 @@ use std::sync::Arc;
 use anyhow::anyhow;
 use lsp_types::{ClientCapabilities, Url};

+use red_knot_python_semantic::{ProgramSettings, PythonVersion, SearchPathSettings};
 use red_knot_workspace::db::RootDatabase;
 use red_knot_workspace::workspace::WorkspaceMetadata;
 use ruff_db::files::{system_path_to_file, File};
-use ruff_db::program::{ProgramSettings, SearchPathSettings, TargetVersion};
 use ruff_db::system::SystemPath;

 use crate::edit::{DocumentKey, NotebookDocument};
@@ -70,7 +70,7 @@ impl Session {
            let metadata = WorkspaceMetadata::from_path(system_path, &system)?;
            // TODO(dhruvmanila): Get the values from the client settings
            let program_settings = ProgramSettings {
-                target_version: TargetVersion::default(),
+                target_version: PythonVersion::default(),
                search_paths: SearchPathSettings {
                    extra_paths: vec![],
                    src_root: system_path.to_path_buf(),
@@ -78,7 +78,8 @@ impl Session {
                    custom_typeshed: None,
                },
            };
-            workspaces.insert(path, RootDatabase::new(metadata, program_settings, system));
+            // TODO(micha): Handle the case where the program settings are incorrect more gracefully.
+            workspaces.insert(path, RootDatabase::new(metadata, program_settings, system)?);
        }

        Ok(Self {
--- a/crates/red_knot_wasm/Cargo.toml
+++ b/crates/red_knot_wasm/Cargo.toml
@@ -19,6 +19,7 @@ doctest = false
 default = ["console_error_panic_hook"]

 [dependencies]
+red_knot_python_semantic = { workspace = true }
 red_knot_workspace = { workspace = true }

 ruff_db = { workspace = true }
--- a/crates/red_knot_wasm/src/lib.rs
+++ b/crates/red_knot_wasm/src/lib.rs
@@ -3,10 +3,10 @@ use std::any::Any;
 use js_sys::Error;
 use wasm_bindgen::prelude::*;

+use red_knot_python_semantic::{ProgramSettings, SearchPathSettings};
 use red_knot_workspace::db::RootDatabase;
 use red_knot_workspace::workspace::WorkspaceMetadata;
 use ruff_db::files::{system_path_to_file, File};
-use ruff_db::program::{ProgramSettings, SearchPathSettings};
 use ruff_db::system::walk_directory::WalkDirectoryBuilder;
 use ruff_db::system::{
    DirectoryEntry, MemoryFileSystem, Metadata, System, SystemPath, SystemPathBuf,
@@ -49,7 +49,8 @@ impl Workspace {
            search_paths: SearchPathSettings::default(),
        };

-        let db = RootDatabase::new(workspace, program_settings, system.clone());
+        let db =
+            RootDatabase::new(workspace, program_settings, system.clone()).map_err(into_error)?;

        Ok(Self { db, system })
    }
@@ -184,16 +185,16 @@ pub enum TargetVersion {
    Py313,
 }

-impl From<TargetVersion> for ruff_db::program::TargetVersion {
+impl From<TargetVersion> for red_knot_python_semantic::PythonVersion {
    fn from(value: TargetVersion) -> Self {
        match value {
-            TargetVersion::Py37 => Self::Py37,
-            TargetVersion::Py38 => Self::Py38,
-            TargetVersion::Py39 => Self::Py39,
-            TargetVersion::Py310 => Self::Py310,
-            TargetVersion::Py311 => Self::Py311,
-            TargetVersion::Py312 => Self::Py312,
-            TargetVersion::Py313 => Self::Py313,
+            TargetVersion::Py37 => Self::PY37,
+            TargetVersion::Py38 => Self::PY38,
+            TargetVersion::Py39 => Self::PY39,
+            TargetVersion::Py310 => Self::PY310,
+            TargetVersion::Py311 => Self::PY311,
+            TargetVersion::Py312 => Self::PY312,
+            TargetVersion::Py313 => Self::PY313,
        }
    }
 }
--- a/crates/red_knot_wasm/tests/api.rs
+++ b/crates/red_knot_wasm/tests/api.rs
@@ -17,5 +17,5 @@ fn check() {

    let result = workspace.check_file(&test).expect("Check to succeed");

-    assert_eq!(result, vec!["Unresolved import 'random22'"]);
+    assert_eq!(result, vec!["/test.py:1:8: Unresolved import 'random22'"]);
 }
--- a/crates/red_knot_workspace/Cargo.toml
+++ b/crates/red_knot_workspace/Cargo.toml
@@ -17,6 +17,7 @@ red_knot_python_semantic = { workspace = true }
 ruff_cache = { workspace = true }
 ruff_db = { workspace = true, features = ["os", "cache"] }
 ruff_python_ast = { workspace = true }
+ruff_text_size = { workspace = true }

 anyhow = { workspace = true }
 crossbeam = { workspace = true }
--- a/crates/red_knot_workspace/resources/test/unix-uv-venv/CACHEDIR.TAG
+++ b/crates/red_knot_workspace/resources/test/unix-uv-venv/CACHEDIR.TAG
@@ -1 +0,0 @@
-Signature: 8a477f597d28d172789f06886806bc55
--- a/crates/red_knot_workspace/resources/test/unix-uv-venv/bin/python
+++ b/crates/red_knot_workspace/resources/test/unix-uv-venv/bin/python
@@ -1 +0,0 @@
-/Users/alexw/.pyenv/versions/3.12.4/bin/python3.12
--- a/crates/red_knot_workspace/resources/test/unix-uv-venv/bin/python3
+++ b/crates/red_knot_workspace/resources/test/unix-uv-venv/bin/python3
@@ -1 +0,0 @@
-python
--- a/crates/red_knot_workspace/resources/test/unix-uv-venv/bin/python3.12
+++ b/crates/red_knot_workspace/resources/test/unix-uv-venv/bin/python3.12
@@ -1 +0,0 @@
-python
--- a/crates/red_knot_workspace/resources/test/unix-uv-venv/lib/python3.12/site-packages/_virtualenv.pth
+++ b/crates/red_knot_workspace/resources/test/unix-uv-venv/lib/python3.12/site-packages/_virtualenv.pth
@@ -1 +0,0 @@
-import _virtualenv
--- a/crates/red_knot_workspace/resources/test/unix-uv-venv/lib/python3.12/site-packages/_virtualenv.py
+++ b/crates/red_knot_workspace/resources/test/unix-uv-venv/lib/python3.12/site-packages/_virtualenv.py
@@ -1,103 +0,0 @@
-"""Patches that are applied at runtime to the virtual environment."""
-
-from __future__ import annotations
-
-import os
-import sys
-
-VIRTUALENV_PATCH_FILE = os.path.join(__file__)
-
-
-def patch_dist(dist):
-    """
-    Distutils allows user to configure some arguments via a configuration file:
-    https://docs.python.org/3/install/index.html#distutils-configuration-files.
-
-    Some of this arguments though don't make sense in context of the virtual environment files, let's fix them up.
-    """  # noqa: D205
-    # we cannot allow some install config as that would get packages installed outside of the virtual environment
-    old_parse_config_files = dist.Distribution.parse_config_files
-
-    def parse_config_files(self, *args, **kwargs):
-        result = old_parse_config_files(self, *args, **kwargs)
-        install = self.get_option_dict("install")
-
-        if "prefix" in install:  # the prefix governs where to install the libraries
-            install["prefix"] = VIRTUALENV_PATCH_FILE, os.path.abspath(sys.prefix)
-        for base in ("purelib", "platlib", "headers", "scripts", "data"):
-            key = f"install_{base}"
-            if key in install:  # do not allow global configs to hijack venv paths
-                install.pop(key, None)
-        return result
-
-    dist.Distribution.parse_config_files = parse_config_files
-
-
-# Import hook that patches some modules to ignore configuration values that break package installation in case
-# of virtual environments.
-_DISTUTILS_PATCH = "distutils.dist", "setuptools.dist"
-# https://docs.python.org/3/library/importlib.html#setting-up-an-importer
-
-
-class _Finder:
-    """A meta path finder that allows patching the imported distutils modules."""
-
-    fullname = None
-
-    # lock[0] is threading.Lock(), but initialized lazily to avoid importing threading very early at startup,
-    # because there are gevent-based applications that need to be first to import threading by themselves.
-    # See https://github.com/pypa/virtualenv/issues/1895 for details.
-    lock = []  # noqa: RUF012
-
-    def find_spec(self, fullname, path, target=None):  # noqa: ARG002
-        if fullname in _DISTUTILS_PATCH and self.fullname is None:
-            # initialize lock[0] lazily
-            if len(self.lock) == 0:
-                import threading
-
-                lock = threading.Lock()
-                # there is possibility that two threads T1 and T2 are simultaneously running into find_spec,
-                # observing .lock as empty, and further going into hereby initialization. However due to the GIL,
-                # list.append() operation is atomic and this way only one of the threads will "win" to put the lock
-                # - that every thread will use - into .lock[0].
-                # https://docs.python.org/3/faq/library.html#what-kinds-of-global-value-mutation-are-thread-safe
-                self.lock.append(lock)
-
-            from functools import partial
-            from importlib.util import find_spec
-
-            with self.lock[0]:
-                self.fullname = fullname
-                try:
-                    spec = find_spec(fullname, path)
-                    if spec is not None:
-                        # https://www.python.org/dev/peps/pep-0451/#how-loading-will-work
-                        is_new_api = hasattr(spec.loader, "exec_module")
-                        func_name = "exec_module" if is_new_api else "load_module"
-                        old = getattr(spec.loader, func_name)
-                        func = self.exec_module if is_new_api else self.load_module
-                        if old is not func:
-                            try:  # noqa: SIM105
-                                setattr(spec.loader, func_name, partial(func, old))
-                            except AttributeError:
-                                pass  # C-Extension loaders are r/o such as zipimporter with <3.7
-                        return spec
-                finally:
-                    self.fullname = None
-        return None
-
-    @staticmethod
-    def exec_module(old, module):
-        old(module)
-        if module.__name__ in _DISTUTILS_PATCH:
-            patch_dist(module)
-
-    @staticmethod
-    def load_module(old, name):
-        module = old(name)
-        if module.__name__ in _DISTUTILS_PATCH:
-            patch_dist(module)
-        return module
-
-
-sys.meta_path.insert(0, _Finder())
--- a/crates/red_knot_workspace/resources/test/unix-uv-venv/pyvenv.cfg
+++ b/crates/red_knot_workspace/resources/test/unix-uv-venv/pyvenv.cfg
@@ -1,6 +0,0 @@
-home = /Users/alexw/.pyenv/versions/3.12.4/bin
-implementation = CPython
-uv = 0.2.32
-version_info = 3.12.4
-include-system-site-packages = false
-relocatable = false
--- a/crates/red_knot_workspace/src/db.rs
+++ b/crates/red_knot_workspace/src/db.rs
@@ -1,9 +1,10 @@
 use std::panic::RefUnwindSafe;
 use std::sync::Arc;

-use red_knot_python_semantic::{vendored_typeshed_stubs, Db as SemanticDb};
+use red_knot_python_semantic::{
+    vendored_typeshed_stubs, Db as SemanticDb, Program, ProgramSettings,
+};
 use ruff_db::files::{File, Files};
-use ruff_db::program::{Program, ProgramSettings};
 use ruff_db::system::System;
 use ruff_db::vendored::VendoredFileSystem;
 use ruff_db::{Db as SourceDb, Upcast};
@@ -27,7 +28,11 @@ pub struct RootDatabase {
 }

 impl RootDatabase {
-    pub fn new<S>(workspace: WorkspaceMetadata, settings: ProgramSettings, system: S) -> Self
+    pub fn new<S>(
+        workspace: WorkspaceMetadata,
+        settings: ProgramSettings,
+        system: S,
+    ) -> anyhow::Result<Self>
    where
        S: System + 'static + Send + Sync + RefUnwindSafe,
    {
@@ -40,10 +45,10 @@ impl RootDatabase {

        let workspace = Workspace::from_metadata(&db, workspace);
        // Initialize the `Program` singleton
-        Program::from_settings(&db, settings);
+        Program::from_settings(&db, settings)?;

        db.workspace = Some(workspace);
-        db
+        Ok(db)
    }

    pub fn workspace(&self) -> Workspace {
@@ -129,7 +134,18 @@ impl SourceDb for RootDatabase {

 #[salsa::db]
 impl salsa::Database for RootDatabase {
-    fn salsa_event(&self, _event: &dyn Fn() -> Event) {}
+    fn salsa_event(&self, event: &dyn Fn() -> Event) {
+        if !tracing::enabled!(tracing::Level::TRACE) {
+            return;
+        }
+
+        let event = event();
+        if matches!(event.kind, salsa::EventKind::WillCheckCancellation { .. }) {
+            return;
+        }
+
+        tracing::trace!("Salsa event: {event:?}");
+    }
 }

 #[salsa::db]
@@ -138,6 +154,7 @@ impl Db for RootDatabase {}
 #[cfg(test)]
 pub(crate) mod tests {
    use salsa::Event;
+    use std::sync::Arc;

    use red_knot_python_semantic::{vendored_typeshed_stubs, Db as SemanticDb};
    use ruff_db::files::Files;
@@ -150,6 +167,7 @@ pub(crate) mod tests {
    #[salsa::db]
    pub(crate) struct TestDb {
        storage: salsa::Storage<Self>,
+        events: std::sync::Arc<std::sync::Mutex<Vec<salsa::Event>>>,
        files: Files,
        system: TestSystem,
        vendored: VendoredFileSystem,
@@ -162,10 +180,24 @@ pub(crate) mod tests {
                system: TestSystem::default(),
                vendored: vendored_typeshed_stubs().clone(),
                files: Files::default(),
+                events: Arc::default(),
            }
        }
    }

+    impl TestDb {
+        /// Takes the salsa events.
+        ///
+        /// ## Panics
+        /// If there are any pending salsa snapshots.
+        pub(crate) fn take_salsa_events(&mut self) -> Vec<salsa::Event> {
+            let inner = Arc::get_mut(&mut self.events).expect("no pending salsa snapshots");
+
+            let events = inner.get_mut().unwrap();
+            std::mem::take(&mut *events)
+        }
+    }
+
    impl DbWithTestSystem for TestDb {
        fn test_system(&self) -> &TestSystem {
            &self.system
@@ -216,6 +248,9 @@ pub(crate) mod tests {

    #[salsa::db]
    impl salsa::Database for TestDb {
-        fn salsa_event(&self, _event: &dyn Fn() -> Event) {}
+        fn salsa_event(&self, event: &dyn Fn() -> Event) {
+            let mut events = self.events.lock().unwrap();
+            events.push(event());
+        }
    }
 }
--- a/crates/red_knot_workspace/src/lint.rs
+++ b/crates/red_knot_workspace/src/lint.rs
@@ -8,9 +8,10 @@ use red_knot_python_semantic::types::Type;
 use red_knot_python_semantic::{HasTy, ModuleName, SemanticModel};
 use ruff_db::files::File;
 use ruff_db::parsed::{parsed_module, ParsedModule};
-use ruff_db::source::{source_text, SourceText};
+use ruff_db::source::{line_index, source_text, SourceText};
 use ruff_python_ast as ast;
 use ruff_python_ast::visitor::{walk_expr, walk_stmt, Visitor};
+use ruff_text_size::{Ranged, TextSize};

 use crate::db::Db;

@@ -49,7 +50,18 @@ pub(crate) fn lint_syntax(db: &dyn Db, file_id: File) -> Diagnostics {
        visitor.visit_body(&ast.body);
        diagnostics = visitor.diagnostics;
    } else {
-        diagnostics.extend(parsed.errors().iter().map(ToString::to_string));
+        let path = file_id.path(db);
+        let line_index = line_index(db.upcast(), file_id);
+        diagnostics.extend(parsed.errors().iter().map(|err| {
+            let source_location = line_index.source_location(err.location.start(), source.as_str());
+            format!(
+                "{}:{}:{}: {}",
+                path.as_str(),
+                source_location.row,
+                source_location.column,
+                err,
+            )
+        }));
    }

    Diagnostics::from(diagnostics)
@@ -97,6 +109,20 @@ pub fn lint_semantic(db: &dyn Db, file_id: File) -> Diagnostics {
    Diagnostics::from(context.diagnostics.take())
 }

+fn format_diagnostic(context: &SemanticLintContext, message: &str, start: TextSize) -> String {
+    let source_location = context
+        .semantic
+        .line_index()
+        .source_location(start, context.source_text());
+    format!(
+        "{}:{}:{}: {}",
+        context.semantic.file_path().as_str(),
+        source_location.row,
+        source_location.column,
+        message,
+    )
+}
+
 fn lint_unresolved_imports(context: &SemanticLintContext, import: AnyImportRef) {
    match import {
        AnyImportRef::Import(import) => {
@@ -104,7 +130,11 @@ fn lint_unresolved_imports(context: &SemanticLintContext, import: AnyImportRef)
                let ty = alias.ty(&context.semantic);

                if ty.is_unbound() {
-                    context.push_diagnostic(format!("Unresolved import '{}'", &alias.name));
+                    context.push_diagnostic(format_diagnostic(
+                        context,
+                        &format!("Unresolved import '{}'", &alias.name),
+                        alias.start(),
+                    ));
                }
            }
        }
@@ -113,7 +143,11 @@ fn lint_unresolved_imports(context: &SemanticLintContext, import: AnyImportRef)
                let ty = alias.ty(&context.semantic);

                if ty.is_unbound() {
-                    context.push_diagnostic(format!("Unresolved import '{}'", &alias.name));
+                    context.push_diagnostic(format_diagnostic(
+                        context,
+                        &format!("Unresolved import '{}'", &alias.name),
+                        alias.start(),
+                    ));
                }
            }
        }
@@ -127,12 +161,17 @@ fn lint_maybe_undefined(context: &SemanticLintContext, name: &ast::ExprName) {
    let semantic = &context.semantic;
    match name.ty(semantic) {
        Type::Unbound => {
-            context.push_diagnostic(format!("Name '{}' used when not defined.", &name.id));
+            context.push_diagnostic(format_diagnostic(
+                context,
+                &format!("Name '{}' used when not defined.", &name.id),
+                name.start(),
+            ));
        }
        Type::Union(union) if union.contains(semantic.db(), Type::Unbound) => {
-            context.push_diagnostic(format!(
-                "Name '{}' used when possibly not defined.",
-                &name.id
+            context.push_diagnostic(format_diagnostic(
+                context,
+                &format!("Name '{}' used when possibly not defined.", &name.id),
+                name.start(),
            ));
        }
        _ => {}
@@ -303,15 +342,25 @@ enum AnyImportRef<'a> {
    ImportFrom(&'a ast::StmtImportFrom),
 }

+impl Ranged for AnyImportRef<'_> {
+    fn range(&self) -> ruff_text_size::TextRange {
+        match self {
+            AnyImportRef::Import(import) => import.range(),
+            AnyImportRef::ImportFrom(import) => import.range(),
+        }
+    }
+}
+
 #[cfg(test)]
 mod tests {
+    use red_knot_python_semantic::{Program, ProgramSettings, PythonVersion, SearchPathSettings};
    use ruff_db::files::system_path_to_file;
-    use ruff_db::program::{Program, SearchPathSettings, TargetVersion};
    use ruff_db::system::{DbWithTestSystem, SystemPathBuf};

-    use super::{lint_semantic, Diagnostics};
    use crate::db::tests::TestDb;

+    use super::{lint_semantic, Diagnostics};
+
    fn setup_db() -> TestDb {
        setup_db_with_root(SystemPathBuf::from("/src"))
    }
@@ -319,16 +368,23 @@ mod tests {
    fn setup_db_with_root(src_root: SystemPathBuf) -> TestDb {
        let db = TestDb::new();

-        Program::new(
+        db.memory_file_system()
+            .create_directory_all(&src_root)
+            .unwrap();
+
+        Program::from_settings(
            &db,
-            TargetVersion::Py38,
-            SearchPathSettings {
-                extra_paths: Vec::new(),
-                src_root,
-                site_packages: vec![],
-                custom_typeshed: None,
+            ProgramSettings {
+                target_version: PythonVersion::default(),
+                search_paths: SearchPathSettings {
+                    extra_paths: Vec::new(),
+                    src_root,
+                    site_packages: vec![],
+                    custom_typeshed: None,
+                },
            },
-        );
+        )
+        .expect("Valid program settings");

        db
    }
@@ -355,10 +411,17 @@ mod tests {

        assert_eq!(
            *messages,
-            vec![
-                "Name 'flag' used when not defined.",
-                "Name 'y' used when possibly not defined."
-            ]
+            if cfg!(windows) {
+                vec![
+                    "\\src\\a.py:3:4: Name 'flag' used when not defined.",
+                    "\\src\\a.py:5:1: Name 'y' used when possibly not defined.",
+                ]
+            } else {
+                vec![
+                    "/src/a.py:3:4: Name 'flag' used when not defined.",
+                    "/src/a.py:5:1: Name 'y' used when possibly not defined.",
+                ]
+            }
        );
    }
 }
--- a/crates/red_knot_workspace/src/site_packages.rs
+++ b/crates/red_knot_workspace/src/site_packages.rs
@@ -8,43 +8,270 @@
 //! reasonably ask us to type-check code assuming that the code runs
 //! on Linux.)

+use std::fmt;
 use std::io;
+use std::num::NonZeroUsize;
+use std::ops::Deref;

+use red_knot_python_semantic::PythonVersion;
 use ruff_db::system::{System, SystemPath, SystemPathBuf};

+type SitePackagesDiscoveryResult<T> = Result<T, SitePackagesDiscoveryError>;
+
+/// Abstraction for a Python virtual environment.
+///
+/// Most of this information is derived from the virtual environment's `pyvenv.cfg` file.
+/// The format of this file is not defined anywhere, and exactly which keys are present
+/// depends on the tool that was used to create the virtual environment.
+#[derive(Debug)]
+pub struct VirtualEnvironment {
+    venv_path: SysPrefixPath,
+    base_executable_home_path: PythonHomePath,
+    include_system_site_packages: bool,
+
+    /// The version of the Python executable that was used to create this virtual environment.
+    ///
+    /// The Python version is encoded under different keys and in different formats
+    /// by different virtual-environment creation tools,
+    /// and the key is never read by the standard-library `site.py` module,
+    /// so it's possible that we might not be able to find this information
+    /// in an acceptable format under any of the keys we expect.
+    /// This field will be `None` if so.
+    version: Option<PythonVersion>,
+}
+
+impl VirtualEnvironment {
+    pub fn new(
+        path: impl AsRef<SystemPath>,
+        system: &dyn System,
+    ) -> SitePackagesDiscoveryResult<Self> {
+        Self::new_impl(path.as_ref(), system)
+    }
+
+    fn new_impl(path: &SystemPath, system: &dyn System) -> SitePackagesDiscoveryResult<Self> {
+        fn pyvenv_cfg_line_number(index: usize) -> NonZeroUsize {
+            index.checked_add(1).and_then(NonZeroUsize::new).unwrap()
+        }
+
+        let venv_path = SysPrefixPath::new(path, system)?;
+        let pyvenv_cfg_path = venv_path.join("pyvenv.cfg");
+        tracing::debug!("Attempting to parse virtual environment metadata at {pyvenv_cfg_path}");
+
+        let pyvenv_cfg = system
+            .read_to_string(&pyvenv_cfg_path)
+            .map_err(SitePackagesDiscoveryError::NoPyvenvCfgFile)?;
+
+        let mut include_system_site_packages = false;
+        let mut base_executable_home_path = None;
+        let mut version_info_string = None;
+
+        // A `pyvenv.cfg` file *looks* like a `.ini` file, but actually isn't valid `.ini` syntax!
+        // The Python standard-library's `site` module parses these files by splitting each line on
+        // '=' characters, so that's what we should do as well.
+        //
+        // See also: https://snarky.ca/how-virtual-environments-work/
+        for (index, line) in pyvenv_cfg.lines().enumerate() {
+            if let Some((key, value)) = line.split_once('=') {
+                let key = key.trim();
+                if key.is_empty() {
+                    return Err(SitePackagesDiscoveryError::PyvenvCfgParseError(
+                        pyvenv_cfg_path,
+                        PyvenvCfgParseErrorKind::MalformedKeyValuePair {
+                            line_number: pyvenv_cfg_line_number(index),
+                        },
+                    ));
+                }
+
+                let value = value.trim();
+                if value.is_empty() {
+                    return Err(SitePackagesDiscoveryError::PyvenvCfgParseError(
+                        pyvenv_cfg_path,
+                        PyvenvCfgParseErrorKind::MalformedKeyValuePair {
+                            line_number: pyvenv_cfg_line_number(index),
+                        },
+                    ));
+                }
+
+                if value.contains('=') {
+                    return Err(SitePackagesDiscoveryError::PyvenvCfgParseError(
+                        pyvenv_cfg_path,
+                        PyvenvCfgParseErrorKind::TooManyEquals {
+                            line_number: pyvenv_cfg_line_number(index),
+                        },
+                    ));
+                }
+
+                match key {
+                    "include-system-site-packages" => {
+                        include_system_site_packages = value.eq_ignore_ascii_case("true");
+                    }
+                    "home" => base_executable_home_path = Some(value),
+                    // `virtualenv` and `uv` call this key `version_info`,
+                    // but the stdlib venv module calls it `version`
+                    "version" | "version_info" => version_info_string = Some(value),
+                    _ => continue,
+                }
+            }
+        }
+
+        // The `home` key is read by the standard library's `site.py` module,
+        // so if it's missing from the `pyvenv.cfg` file
+        // (or the provided value is invalid),
+        // it's reasonable to consider the virtual environment irredeemably broken.
+        let Some(base_executable_home_path) = base_executable_home_path else {
+            return Err(SitePackagesDiscoveryError::PyvenvCfgParseError(
+                pyvenv_cfg_path,
+                PyvenvCfgParseErrorKind::NoHomeKey,
+            ));
+        };
+        let base_executable_home_path = PythonHomePath::new(base_executable_home_path, system)
+            .map_err(|io_err| {
+                SitePackagesDiscoveryError::PyvenvCfgParseError(
+                    pyvenv_cfg_path,
+                    PyvenvCfgParseErrorKind::InvalidHomeValue(io_err),
+                )
+            })?;
+
+        // but the `version`/`version_info` key is not read by the standard library,
+        // and is provided under different keys depending on which virtual-environment creation tool
+        // created the `pyvenv.cfg` file. Lenient parsing is appropriate here:
+        // the file isn't really *invalid* if it doesn't have this key,
+        // or if the value doesn't parse according to our expectations.
+        let version = version_info_string.and_then(|version_string| {
+            let mut version_info_parts = version_string.split('.');
+            let (major, minor) = (version_info_parts.next()?, version_info_parts.next()?);
+            PythonVersion::try_from((major, minor)).ok()
+        });
+
+        let metadata = Self {
+            venv_path,
+            base_executable_home_path,
+            include_system_site_packages,
+            version,
+        };
+
+        tracing::trace!("Resolved metadata for virtual environment: {metadata:?}");
+        Ok(metadata)
+    }
+
+    /// Return a list of `site-packages` directories that are available from this virtual environment
+    ///
+    /// See the documentation for `site_packages_dir_from_sys_prefix` for more details.
+    pub fn site_packages_directories(
+        &self,
+        system: &dyn System,
+    ) -> SitePackagesDiscoveryResult<Vec<SystemPathBuf>> {
+        let VirtualEnvironment {
+            venv_path,
+            base_executable_home_path,
+            include_system_site_packages,
+            version,
+        } = self;
+
+        let mut site_packages_directories = vec![site_packages_directory_from_sys_prefix(
+            venv_path, *version, system,
+        )?];
+
+        if *include_system_site_packages {
+            let system_sys_prefix =
+                SysPrefixPath::from_executable_home_path(base_executable_home_path);
+
+            // If we fail to resolve the `sys.prefix` path from the base executable home path,
+            // or if we fail to resolve the `site-packages` from the `sys.prefix` path,
+            // we should probably print a warning but *not* abort type checking
+            if let Some(sys_prefix_path) = system_sys_prefix {
+                match site_packages_directory_from_sys_prefix(&sys_prefix_path, *version, system) {
+                    Ok(site_packages_directory) => {
+                        site_packages_directories.push(site_packages_directory);
+                    }
+                    Err(error) => tracing::warn!(
+                        "{error}. System site-packages will not be used for module resolution."
+                    ),
+                }
+            } else {
+                tracing::warn!(
+                    "Failed to resolve `sys.prefix` of the system Python installation \
+from the `home` value in the `pyvenv.cfg` file at {}. \
+System site-packages will not be used for module resolution.",
+                    venv_path.join("pyvenv.cfg")
+                );
+            }
+        }
+
+        tracing::debug!("Resolved site-packages directories for this virtual environment are: {site_packages_directories:?}");
+        Ok(site_packages_directories)
+    }
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum SitePackagesDiscoveryError {
+    #[error("Invalid --venv-path argument: {0} could not be canonicalized")]
+    VenvDirCanonicalizationError(SystemPathBuf, #[source] io::Error),
+    #[error("Invalid --venv-path argument: {0} does not point to a directory on disk")]
+    VenvDirIsNotADirectory(SystemPathBuf),
+    #[error("--venv-path points to a broken venv with no pyvenv.cfg file")]
+    NoPyvenvCfgFile(#[source] io::Error),
+    #[error("Failed to parse the pyvenv.cfg file at {0} because {1}")]
+    PyvenvCfgParseError(SystemPathBuf, PyvenvCfgParseErrorKind),
+    #[error("Failed to search the `lib` directory of the Python installation at {1} for `site-packages`")]
+    CouldNotReadLibDirectory(#[source] io::Error, SysPrefixPath),
+    #[error("Could not find the `site-packages` directory for the Python installation at {0}")]
+    NoSitePackagesDirFound(SysPrefixPath),
+}
+
+/// The various ways in which parsing a `pyvenv.cfg` file could fail
+#[derive(Debug)]
+pub enum PyvenvCfgParseErrorKind {
+    TooManyEquals { line_number: NonZeroUsize },
+    MalformedKeyValuePair { line_number: NonZeroUsize },
+    NoHomeKey,
+    InvalidHomeValue(io::Error),
+}
+
+impl fmt::Display for PyvenvCfgParseErrorKind {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::TooManyEquals { line_number } => {
+                write!(f, "line {line_number} has too many '=' characters")
+            }
+            Self::MalformedKeyValuePair { line_number } => write!(
+                f,
+                "line {line_number} has a malformed `<key> = <value>` pair"
+            ),
+            Self::NoHomeKey => f.write_str("the file does not have a `home` key"),
+            Self::InvalidHomeValue(io_err) => {
+                write!(
+                    f,
+                    "the following error was encountered \
+when trying to resolve the `home` value to a directory on disk: {io_err}"
+                )
+            }
+        }
+    }
+}
+
 /// Attempt to retrieve the `site-packages` directory
 /// associated with a given Python installation.
 ///
-/// `sys_prefix_path` is equivalent to the value of [`sys.prefix`]
-/// at runtime in Python. For the case of a virtual environment, where a
-/// Python binary is at `/.venv/bin/python`, `sys.prefix` is the path to
-/// the virtual environment the Python binary lies inside, i.e. `/.venv`,
-/// and `site-packages` will be at `.venv/lib/python3.X/site-packages`.
-/// System Python installations generally work the same way: if a system
-/// Python installation lies at `/opt/homebrew/bin/python`, `sys.prefix`
-/// will be `/opt/homebrew`, and `site-packages` will be at
-/// `/opt/homebrew/lib/python3.X/site-packages`.
-///
-/// This routine does not verify that `sys_prefix_path` points
-/// to an existing directory on disk; it is assumed that this has already
-/// been checked.
-///
-/// [`sys.prefix`]: https://docs.python.org/3/library/sys.html#sys.prefix
-fn site_packages_dir_from_sys_prefix(
-    sys_prefix_path: &SystemPath,
+/// The location of the `site-packages` directory can vary according to the
+/// Python version that this installation represents. The Python version may
+/// or may not be known at this point, which is why the `python_version`
+/// parameter is an `Option`.
+fn site_packages_directory_from_sys_prefix(
+    sys_prefix_path: &SysPrefixPath,
+    python_version: Option<PythonVersion>,
    system: &dyn System,
-) -> Result<SystemPathBuf, SitePackagesDiscoveryError> {
-    tracing::debug!("Searching for site-packages directory in '{sys_prefix_path}'");
+) -> SitePackagesDiscoveryResult<SystemPathBuf> {
+    tracing::debug!("Searching for site-packages directory in {sys_prefix_path}");

    if cfg!(target_os = "windows") {
-        let site_packages = sys_prefix_path.join("Lib/site-packages");
-
-        return if system.is_directory(&site_packages) {
-            tracing::debug!("Resolved site-packages directory to '{site_packages}'");
-            Ok(site_packages)
-        } else {
-            Err(SitePackagesDiscoveryError::NoSitePackagesDirFound)
-        };
+        let site_packages = sys_prefix_path.join(r"Lib\site-packages");
+        return system
+            .is_directory(&site_packages)
+            .then_some(site_packages)
+            .ok_or(SitePackagesDiscoveryError::NoSitePackagesDirFound(
+                sys_prefix_path.to_owned(),
+            ));
    }

    // In the Python standard library's `site.py` module (used for finding `site-packages`
@@ -69,7 +296,38 @@ fn site_packages_dir_from_sys_prefix(
    //
    // [the non-Windows branch]: https://github.com/python/cpython/blob/a8be8fc6c4682089be45a87bd5ee1f686040116c/Lib/site.py#L401-L410
    // [the `sys`-module documentation]: https://docs.python.org/3/library/sys.html#sys.platlibdir
-    for entry_result in system.read_directory(&sys_prefix_path.join("lib"))? {
+
+    // If we were able to figure out what Python version this installation is,
+    // we should be able to avoid iterating through all items in the `lib/` directory:
+    if let Some(version) = python_version {
+        let expected_path = sys_prefix_path.join(format!("lib/python{version}/site-packages"));
+        if system.is_directory(&expected_path) {
+            return Ok(expected_path);
+        }
+        if version.free_threaded_build_available() {
+            // Nearly the same as `expected_path`, but with an additional `t` after {version}:
+            let alternative_path =
+                sys_prefix_path.join(format!("lib/python{version}t/site-packages"));
+            if system.is_directory(&alternative_path) {
+                return Ok(alternative_path);
+            }
+        }
+    }
+
+    // Either we couldn't figure out the version before calling this function
+    // (e.g., from a `pyvenv.cfg` file if this was a venv),
+    // or we couldn't find a `site-packages` folder at the expected location given
+    // the parsed version
+    //
+    // Note: the `python3.x` part of the `site-packages` path can't be computed from
+    // the `--target-version` the user has passed, as they might be running Python 3.12 locally
+    // even if they've requested that we type check their code "as if" they're running 3.8.
+    for entry_result in system
+        .read_directory(&sys_prefix_path.join("lib"))
+        .map_err(|io_err| {
+            SitePackagesDiscoveryError::CouldNotReadLibDirectory(io_err, sys_prefix_path.to_owned())
+        })?
+    {
        let Ok(entry) = entry_result else {
            continue;
        };
@@ -80,16 +338,6 @@ fn site_packages_dir_from_sys_prefix(

        let mut path = entry.into_path();

-        // The `python3.x` part of the `site-packages` path can't be computed from
-        // the `--target-version` the user has passed, as they might be running Python 3.12 locally
-        // even if they've requested that we type check their code "as if" they're running 3.8.
-        //
-        // The `python3.x` part of the `site-packages` path *could* be computed
-        // by parsing the virtual environment's `pyvenv.cfg` file.
-        // Right now that seems like overkill, but in the future we may need to parse
-        // the `pyvenv.cfg` file anyway, in which case we could switch to that method
-        // rather than iterating through the whole directory until we find
-        // an entry where the last component of the path starts with `python3.`
        let name = path
            .file_name()
            .expect("File name to be non-null because path is guaranteed to be a child of `lib`");
@@ -100,55 +348,494 @@ fn site_packages_dir_from_sys_prefix(

        path.push("site-packages");
        if system.is_directory(&path) {
-            tracing::debug!("Resolved site-packages directory to '{path}'");
            return Ok(path);
        }
    }
-    Err(SitePackagesDiscoveryError::NoSitePackagesDirFound)
+    Err(SitePackagesDiscoveryError::NoSitePackagesDirFound(
+        sys_prefix_path.to_owned(),
+    ))
 }

-#[derive(Debug, thiserror::Error)]
-pub enum SitePackagesDiscoveryError {
-    #[error("Failed to search the virtual environment directory for `site-packages`")]
-    CouldNotReadLibDirectory(#[from] io::Error),
-    #[error("Could not find the `site-packages` directory in the virtual environment")]
-    NoSitePackagesDirFound,
+/// A path that represents the value of [`sys.prefix`] at runtime in Python
+/// for a given Python executable.
+///
+/// For the case of a virtual environment, where a
+/// Python binary is at `/.venv/bin/python`, `sys.prefix` is the path to
+/// the virtual environment the Python binary lies inside, i.e. `/.venv`,
+/// and `site-packages` will be at `.venv/lib/python3.X/site-packages`.
+/// System Python installations generally work the same way: if a system
+/// Python installation lies at `/opt/homebrew/bin/python`, `sys.prefix`
+/// will be `/opt/homebrew`, and `site-packages` will be at
+/// `/opt/homebrew/lib/python3.X/site-packages`.
+///
+/// [`sys.prefix`]: https://docs.python.org/3/library/sys.html#sys.prefix
+#[derive(Debug, PartialEq, Eq, Clone)]
+pub struct SysPrefixPath(SystemPathBuf);
+
+impl SysPrefixPath {
+    fn new(
+        unvalidated_path: impl AsRef<SystemPath>,
+        system: &dyn System,
+    ) -> SitePackagesDiscoveryResult<Self> {
+        Self::new_impl(unvalidated_path.as_ref(), system)
+    }
+
+    fn new_impl(
+        unvalidated_path: &SystemPath,
+        system: &dyn System,
+    ) -> SitePackagesDiscoveryResult<Self> {
+        // It's important to resolve symlinks here rather than simply making the path absolute,
+        // since system Python installations often only put symlinks in the "expected"
+        // locations for `home` and `site-packages`
+        let canonicalized = system
+            .canonicalize_path(unvalidated_path)
+            .map_err(|io_err| {
+                SitePackagesDiscoveryError::VenvDirCanonicalizationError(
+                    unvalidated_path.to_path_buf(),
+                    io_err,
+                )
+            })?;
+        system
+            .is_directory(&canonicalized)
+            .then_some(Self(canonicalized))
+            .ok_or_else(|| {
+                SitePackagesDiscoveryError::VenvDirIsNotADirectory(unvalidated_path.to_path_buf())
+            })
+    }
+
+    fn from_executable_home_path(path: &PythonHomePath) -> Option<Self> {
+        // No need to check whether `path.parent()` is a directory:
+        // the parent of a canonicalised path that is known to exist
+        // is guaranteed to be a directory.
+        if cfg!(target_os = "windows") {
+            Some(Self(path.to_path_buf()))
+        } else {
+            path.parent().map(|path| Self(path.to_path_buf()))
+        }
+    }
 }

-/// Given a validated, canonicalized path to a virtual environment,
-/// return a list of `site-packages` directories that are available from that environment.
+impl Deref for SysPrefixPath {
+    type Target = SystemPath;
+
+    fn deref(&self) -> &Self::Target {
+        &self.0
+    }
+}
+
+impl fmt::Display for SysPrefixPath {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "`sys.prefix` path {}", self.0)
+    }
+}
+
+/// The value given by the `home` key in `pyvenv.cfg` files.
 ///
-/// See the documentation for `site_packages_dir_from_sys_prefix` for more details.
+/// This is equivalent to `{sys_prefix_path}/bin`, and points
+/// to a directory in which a Python executable can be found.
+/// Confusingly, it is *not* the same as the [`PYTHONHOME`]
+/// environment variable that Python provides! However, it's
+/// consistent among all mainstream creators of Python virtual
+/// environments (the stdlib Python `venv` module, the third-party
+/// `virtualenv` library, and `uv`), was specified by
+/// [the original PEP adding the `venv` module],
+/// and it's one of the few fields that's read by the Python
+/// standard library's `site.py` module.
 ///
-/// TODO: Currently we only ever return 1 path from this function:
-/// the `site-packages` directory that is actually inside the virtual environment.
-/// Some `site-packages` directories are able to also access system `site-packages` and
-/// user `site-packages`, however.
-pub fn site_packages_dirs_of_venv(
-    venv_path: &SystemPath,
-    system: &dyn System,
-) -> Result<Vec<SystemPathBuf>, SitePackagesDiscoveryError> {
-    Ok(vec![site_packages_dir_from_sys_prefix(venv_path, system)?])
+/// Although it doesn't appear to be specified anywhere,
+/// all existing virtual environment tools always use an absolute path
+/// for the `home` value, and the Python standard library also assumes
+/// that the `home` value will be an absolute path.
+///
+/// Other values, such as the path to the Python executable or the
+/// base-executable `sys.prefix` value, are either only provided in
+/// `pyvenv.cfg` files by some virtual-environment creators,
+/// or are included under different keys depending on which
+/// virtual-environment creation tool you've used.
+///
+/// [`PYTHONHOME`]: https://docs.python.org/3/using/cmdline.html#envvar-PYTHONHOME
+/// [the original PEP adding the `venv` module]: https://peps.python.org/pep-0405/
+#[derive(Debug, PartialEq, Eq)]
+struct PythonHomePath(SystemPathBuf);
+
+impl PythonHomePath {
+    fn new(path: impl AsRef<SystemPath>, system: &dyn System) -> io::Result<Self> {
+        let path = path.as_ref();
+        // It's important to resolve symlinks here rather than simply making the path absolute,
+        // since system Python installations often only put symlinks in the "expected"
+        // locations for `home` and `site-packages`
+        let canonicalized = system.canonicalize_path(path)?;
+        system
+            .is_directory(&canonicalized)
+            .then_some(Self(canonicalized))
+            .ok_or_else(|| io::Error::new(io::ErrorKind::Other, "not a directory"))
+    }
+}
+
+impl Deref for PythonHomePath {
+    type Target = SystemPath;
+
+    fn deref(&self) -> &Self::Target {
+        &self.0
+    }
+}
+
+impl fmt::Display for PythonHomePath {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "`home` location {}", self.0)
+    }
+}
+
+impl PartialEq<SystemPath> for PythonHomePath {
+    fn eq(&self, other: &SystemPath) -> bool {
+        &*self.0 == other
+    }
+}
+
+impl PartialEq<SystemPathBuf> for PythonHomePath {
+    fn eq(&self, other: &SystemPathBuf) -> bool {
+        self == &**other
+    }
 }

 #[cfg(test)]
 mod tests {
-    use ruff_db::system::{OsSystem, System, SystemPath};
+    use ruff_db::system::TestSystem;

-    use crate::site_packages::site_packages_dirs_of_venv;
+    use super::*;
+
+    struct VirtualEnvironmentTester {
+        system: TestSystem,
+        minor_version: u8,
+        free_threaded: bool,
+        system_site_packages: bool,
+        pyvenv_cfg_version_field: Option<&'static str>,
+    }
+
+    impl VirtualEnvironmentTester {
+        /// Builds a mock virtual environment, and returns the path to the venv
+        fn build_mock_venv(&self) -> SystemPathBuf {
+            let VirtualEnvironmentTester {
+                system,
+                minor_version,
+                system_site_packages,
+                free_threaded,
+                pyvenv_cfg_version_field,
+            } = self;
+            let memory_fs = system.memory_file_system();
+            let unix_site_packages = if *free_threaded {
+                format!("lib/python3.{minor_version}t/site-packages")
+            } else {
+                format!("lib/python3.{minor_version}/site-packages")
+            };
+
+            let system_install_sys_prefix =
+                SystemPathBuf::from(&*format!("/Python3.{minor_version}"));
+            let (system_home_path, system_exe_path, system_site_packages_path) =
+                if cfg!(target_os = "windows") {
+                    let system_home_path = system_install_sys_prefix.clone();
+                    let system_exe_path = system_home_path.join("python.exe");
+                    let system_site_packages_path =
+                        system_install_sys_prefix.join(r"Lib\site-packages");
+                    (system_home_path, system_exe_path, system_site_packages_path)
+                } else {
+                    let system_home_path = system_install_sys_prefix.join("bin");
+                    let system_exe_path = system_home_path.join("python");
+                    let system_site_packages_path =
+                        system_install_sys_prefix.join(&unix_site_packages);
+                    (system_home_path, system_exe_path, system_site_packages_path)
+                };
+            memory_fs.write_file(system_exe_path, "").unwrap();
+            memory_fs
+                .create_directory_all(&system_site_packages_path)
+                .unwrap();
+
+            let venv_sys_prefix = SystemPathBuf::from("/.venv");
+            let (venv_exe, site_packages_path) = if cfg!(target_os = "windows") {
+                (
+                    venv_sys_prefix.join(r"Scripts\python.exe"),
+                    venv_sys_prefix.join(r"Lib\site-packages"),
+                )
+            } else {
+                (
+                    venv_sys_prefix.join("bin/python"),
+                    venv_sys_prefix.join(&unix_site_packages),
+                )
+            };
+            memory_fs.write_file(&venv_exe, "").unwrap();
+            memory_fs.create_directory_all(&site_packages_path).unwrap();
+
+            let pyvenv_cfg_path = venv_sys_prefix.join("pyvenv.cfg");
+            let mut pyvenv_cfg_contents = format!("home = {system_home_path}\n");
+            if let Some(version_field) = pyvenv_cfg_version_field {
+                pyvenv_cfg_contents.push_str(version_field);
+                pyvenv_cfg_contents.push('\n');
+            }
+            // Deliberately using weird casing here to test that our pyvenv.cfg parsing is case-insensitive:
+            if *system_site_packages {
+                pyvenv_cfg_contents.push_str("include-system-site-packages = TRuE\n");
+            }
+            memory_fs
+                .write_file(pyvenv_cfg_path, &pyvenv_cfg_contents)
+                .unwrap();
+
+            venv_sys_prefix
+        }
+
+        fn test(self) {
+            let venv_path = self.build_mock_venv();
+            let venv = VirtualEnvironment::new(venv_path.clone(), &self.system).unwrap();
+
+            assert_eq!(
+                venv.venv_path,
+                SysPrefixPath(self.system.canonicalize_path(&venv_path).unwrap())
+            );
+            assert_eq!(venv.include_system_site_packages, self.system_site_packages);
+
+            if self.pyvenv_cfg_version_field.is_some() {
+                assert_eq!(
+                    venv.version,
+                    Some(PythonVersion {
+                        major: 3,
+                        minor: self.minor_version
+                    })
+                );
+            } else {
+                assert_eq!(venv.version, None);
+            }
+
+            let expected_home = if cfg!(target_os = "windows") {
+                SystemPathBuf::from(&*format!(r"\Python3.{}", self.minor_version))
+            } else {
+                SystemPathBuf::from(&*format!("/Python3.{}/bin", self.minor_version))
+            };
+            assert_eq!(venv.base_executable_home_path, expected_home);
+
+            let site_packages_directories = venv.site_packages_directories(&self.system).unwrap();
+            let expected_venv_site_packages = if cfg!(target_os = "windows") {
+                SystemPathBuf::from(r"\.venv\Lib\site-packages")
+            } else if self.free_threaded {
+                SystemPathBuf::from(&*format!(
+                    "/.venv/lib/python3.{}t/site-packages",
+                    self.minor_version
+                ))
+            } else {
+                SystemPathBuf::from(&*format!(
+                    "/.venv/lib/python3.{}/site-packages",
+                    self.minor_version
+                ))
+            };
+
+            let expected_system_site_packages = if cfg!(target_os = "windows") {
+                SystemPathBuf::from(&*format!(
+                    r"\Python3.{}\Lib\site-packages",
+                    self.minor_version
+                ))
+            } else if self.free_threaded {
+                SystemPathBuf::from(&*format!(
+                    "/Python3.{minor_version}/lib/python3.{minor_version}t/site-packages",
+                    minor_version = self.minor_version
+                ))
+            } else {
+                SystemPathBuf::from(&*format!(
+                    "/Python3.{minor_version}/lib/python3.{minor_version}/site-packages",
+                    minor_version = self.minor_version
+                ))
+            };
+
+            if self.system_site_packages {
+                assert_eq!(
+                    &site_packages_directories,
+                    &[expected_venv_site_packages, expected_system_site_packages]
+                );
+            } else {
+                assert_eq!(&site_packages_directories, &[expected_venv_site_packages]);
+            }
+        }
+    }

    #[test]
-    // Windows venvs have different layouts, and we only have a Unix venv committed for now.
-    // This test is skipped on Windows until we commit a Windows venv.
-    #[cfg_attr(target_os = "windows", ignore = "Windows has a different venv layout")]
-    fn can_find_site_packages_dir_in_committed_venv() {
-        let path_to_venv = SystemPath::new("resources/test/unix-uv-venv");
-        let system = OsSystem::default();
+    fn can_find_site_packages_directory_no_version_field_in_pyvenv_cfg() {
+        let tester = VirtualEnvironmentTester {
+            system: TestSystem::default(),
+            minor_version: 12,
+            free_threaded: false,
+            system_site_packages: false,
+            pyvenv_cfg_version_field: None,
+        };
+        tester.test();
+    }

-        // if this doesn't hold true, the premise of the test is incorrect.
-        assert!(system.is_directory(path_to_venv));
+    #[test]
+    fn can_find_site_packages_directory_venv_style_version_field_in_pyvenv_cfg() {
+        let tester = VirtualEnvironmentTester {
+            system: TestSystem::default(),
+            minor_version: 12,
+            free_threaded: false,
+            system_site_packages: false,
+            pyvenv_cfg_version_field: Some("version = 3.12"),
+        };
+        tester.test();
+    }

-        let site_packages_dirs = site_packages_dirs_of_venv(path_to_venv, &system).unwrap();
-        assert_eq!(site_packages_dirs.len(), 1);
+    #[test]
+    fn can_find_site_packages_directory_uv_style_version_field_in_pyvenv_cfg() {
+        let tester = VirtualEnvironmentTester {
+            system: TestSystem::default(),
+            minor_version: 12,
+            free_threaded: false,
+            system_site_packages: false,
+            pyvenv_cfg_version_field: Some("version_info = 3.12"),
+        };
+        tester.test();
+    }
+
+    #[test]
+    fn can_find_site_packages_directory_virtualenv_style_version_field_in_pyvenv_cfg() {
+        let tester = VirtualEnvironmentTester {
+            system: TestSystem::default(),
+            minor_version: 12,
+            free_threaded: false,
+            system_site_packages: false,
+            pyvenv_cfg_version_field: Some("version_info = 3.12.0rc2"),
+        };
+        tester.test();
+    }
+
+    #[test]
+    fn can_find_site_packages_directory_freethreaded_build() {
+        let tester = VirtualEnvironmentTester {
+            system: TestSystem::default(),
+            minor_version: 13,
+            free_threaded: true,
+            system_site_packages: false,
+            pyvenv_cfg_version_field: Some("version_info = 3.13"),
+        };
+        tester.test();
+    }
+
+    #[test]
+    fn finds_system_site_packages() {
+        let tester = VirtualEnvironmentTester {
+            system: TestSystem::default(),
+            minor_version: 13,
+            free_threaded: true,
+            system_site_packages: true,
+            pyvenv_cfg_version_field: Some("version_info = 3.13"),
+        };
+        tester.test();
+    }
+
+    #[test]
+    fn reject_venv_that_does_not_exist() {
+        let system = TestSystem::default();
+        assert!(matches!(
+            VirtualEnvironment::new("/.venv", &system),
+            Err(SitePackagesDiscoveryError::VenvDirIsNotADirectory(_))
+        ));
+    }
+
+    #[test]
+    fn reject_venv_with_no_pyvenv_cfg_file() {
+        let system = TestSystem::default();
+        system
+            .memory_file_system()
+            .create_directory_all("/.venv")
+            .unwrap();
+        assert!(matches!(
+            VirtualEnvironment::new("/.venv", &system),
+            Err(SitePackagesDiscoveryError::NoPyvenvCfgFile(_))
+        ));
+    }
+
+    #[test]
+    fn parsing_pyvenv_cfg_with_too_many_equals() {
+        let system = TestSystem::default();
+        let memory_fs = system.memory_file_system();
+        let pyvenv_cfg_path = SystemPathBuf::from("/.venv/pyvenv.cfg");
+        memory_fs
+            .write_file(&pyvenv_cfg_path, "home = bar = /.venv/bin")
+            .unwrap();
+        let venv_result = VirtualEnvironment::new("/.venv", &system);
+        assert!(matches!(
+            venv_result,
+            Err(SitePackagesDiscoveryError::PyvenvCfgParseError(
+                path,
+                PyvenvCfgParseErrorKind::TooManyEquals { line_number }
+            ))
+            if path == pyvenv_cfg_path && Some(line_number) == NonZeroUsize::new(1)
+        ));
+    }
+
+    #[test]
+    fn parsing_pyvenv_cfg_with_key_but_no_value_fails() {
+        let system = TestSystem::default();
+        let memory_fs = system.memory_file_system();
+        let pyvenv_cfg_path = SystemPathBuf::from("/.venv/pyvenv.cfg");
+        memory_fs.write_file(&pyvenv_cfg_path, "home =").unwrap();
+        let venv_result = VirtualEnvironment::new("/.venv", &system);
+        assert!(matches!(
+            venv_result,
+            Err(SitePackagesDiscoveryError::PyvenvCfgParseError(
+                path,
+                PyvenvCfgParseErrorKind::MalformedKeyValuePair { line_number }
+            ))
+            if path == pyvenv_cfg_path && Some(line_number) == NonZeroUsize::new(1)
+        ));
+    }
+
+    #[test]
+    fn parsing_pyvenv_cfg_with_value_but_no_key_fails() {
+        let system = TestSystem::default();
+        let memory_fs = system.memory_file_system();
+        let pyvenv_cfg_path = SystemPathBuf::from("/.venv/pyvenv.cfg");
+        memory_fs
+            .write_file(&pyvenv_cfg_path, "= whatever")
+            .unwrap();
+        let venv_result = VirtualEnvironment::new("/.venv", &system);
+        assert!(matches!(
+            venv_result,
+            Err(SitePackagesDiscoveryError::PyvenvCfgParseError(
+                path,
+                PyvenvCfgParseErrorKind::MalformedKeyValuePair { line_number }
+            ))
+            if path == pyvenv_cfg_path && Some(line_number) == NonZeroUsize::new(1)
+        ));
+    }
+
+    #[test]
+    fn parsing_pyvenv_cfg_with_no_home_key_fails() {
+        let system = TestSystem::default();
+        let memory_fs = system.memory_file_system();
+        let pyvenv_cfg_path = SystemPathBuf::from("/.venv/pyvenv.cfg");
+        memory_fs.write_file(&pyvenv_cfg_path, "").unwrap();
+        let venv_result = VirtualEnvironment::new("/.venv", &system);
+        assert!(matches!(
+            venv_result,
+            Err(SitePackagesDiscoveryError::PyvenvCfgParseError(
+                path,
+                PyvenvCfgParseErrorKind::NoHomeKey
+            ))
+            if path == pyvenv_cfg_path
+        ));
+    }
+
+    #[test]
+    fn parsing_pyvenv_cfg_with_invalid_home_key_fails() {
+        let system = TestSystem::default();
+        let memory_fs = system.memory_file_system();
+        let pyvenv_cfg_path = SystemPathBuf::from("/.venv/pyvenv.cfg");
+        memory_fs
+            .write_file(&pyvenv_cfg_path, "home = foo")
+            .unwrap();
+        let venv_result = VirtualEnvironment::new("/.venv", &system);
+        assert!(matches!(
+            venv_result,
+            Err(SitePackagesDiscoveryError::PyvenvCfgParseError(
+                path,
+                PyvenvCfgParseErrorKind::InvalidHomeValue(_)
+            ))
+            if path == pyvenv_cfg_path
+        ));
    }
 }
--- a/crates/red_knot_workspace/src/workspace.rs
+++ b/crates/red_knot_workspace/src/workspace.rs
@@ -1,9 +1,10 @@
-use salsa::{Durability, Setter as _};
 use std::{collections::BTreeMap, sync::Arc};

 use rustc_hash::{FxBuildHasher, FxHashSet};
+use salsa::{Durability, Setter as _};

 pub use metadata::{PackageMetadata, WorkspaceMetadata};
+use ruff_db::source::{source_text, SourceDiagnostic};
 use ruff_db::{
    files::{system_path_to_file, File},
    system::{walk_directory::WalkState, SystemPath, SystemPathBuf},
@@ -345,12 +346,27 @@ impl Package {
    }
 }

+#[salsa::tracked]
 pub(super) fn check_file(db: &dyn Db, file: File) -> Diagnostics {
    let path = file.path(db);
    let _span = tracing::debug_span!("check_file", file=%path).entered();
    tracing::debug!("Checking file {path}");

    let mut diagnostics = Vec::new();
+
+    let source_diagnostics = source_text::accumulated::<SourceDiagnostic>(db.upcast(), file);
+    // TODO(micha): Consider using a single accumulator for all diagnostics
+    diagnostics.extend(
+        source_diagnostics
+            .iter()
+            .map(std::string::ToString::to_string),
+    );
+
+    // Abort checking if there are IO errors.
+    if source_text(db.upcast(), file).has_read_error() {
+        return Diagnostics::from(diagnostics);
+    }
+
    diagnostics.extend_from_slice(lint_syntax(db, file));
    diagnostics.extend_from_slice(lint_semantic(db, file));
    Diagnostics::from(diagnostics)
@@ -398,3 +414,48 @@ fn discover_package_files(db: &dyn Db, path: &SystemPath) -> FxHashSet<File> {

    files
 }
+
+#[cfg(test)]
+mod tests {
+    use ruff_db::files::system_path_to_file;
+    use ruff_db::source::source_text;
+    use ruff_db::system::{DbWithTestSystem, SystemPath};
+    use ruff_db::testing::assert_function_query_was_not_run;
+
+    use crate::db::tests::TestDb;
+    use crate::lint::{lint_syntax, Diagnostics};
+    use crate::workspace::check_file;
+
+    #[test]
+    fn check_file_skips_linting_when_file_cant_be_read() -> ruff_db::system::Result<()> {
+        let mut db = TestDb::new();
+        let path = SystemPath::new("test.py");
+
+        db.write_file(path, "x = 10")?;
+        let file = system_path_to_file(&db, path).unwrap();
+
+        // Now the file gets deleted before we had a chance to read its source text.
+        db.memory_file_system().remove_file(path)?;
+        file.sync(&mut db);
+
+        assert_eq!(source_text(&db, file).as_str(), "");
+        assert_eq!(
+            check_file(&db, file),
+            Diagnostics::List(vec![
+                "Failed to read file: No such file or directory".to_string()
+            ])
+        );
+
+        let events = db.take_salsa_events();
+        assert_function_query_was_not_run(&db, lint_syntax, file, &events);
+
+        // The user now creates a new file with an empty text. The source text
+        // content returned by `source_text` remains unchanged, but the diagnostics should get updated.
+        db.write_file(path, "").unwrap();
+
+        assert_eq!(source_text(&db, file).as_str(), "");
+        assert_eq!(check_file(&db, file), Diagnostics::Empty);
+
+        Ok(())
+    }
+}
--- a/crates/red_knot_workspace/tests/check.rs
+++ b/crates/red_knot_workspace/tests/check.rs
@@ -1,8 +1,8 @@
+use red_knot_python_semantic::{ProgramSettings, PythonVersion, SearchPathSettings};
 use red_knot_workspace::db::RootDatabase;
 use red_knot_workspace::lint::lint_semantic;
 use red_knot_workspace::workspace::WorkspaceMetadata;
 use ruff_db::files::system_path_to_file;
-use ruff_db::program::{ProgramSettings, SearchPathSettings, TargetVersion};
 use ruff_db::system::{OsSystem, SystemPathBuf};
 use std::fs;
 use std::path::PathBuf;
@@ -17,11 +17,10 @@ fn setup_db(workspace_root: SystemPathBuf) -> anyhow::Result<RootDatabase> {
        site_packages: vec![],
    };
    let settings = ProgramSettings {
-        target_version: TargetVersion::default(),
+        target_version: PythonVersion::default(),
        search_paths,
    };
-    let db = RootDatabase::new(workspace, settings, system);
-    Ok(db)
+    RootDatabase::new(workspace, settings, system)
 }

 /// Test that all snippets in testcorpus can be checked without panic
--- a/crates/ruff/src/commands/check.rs
+++ b/crates/ruff/src/commands/check.rs
@@ -268,8 +268,7 @@ mod test {

        // Run
        let diagnostics = check(
-            // Notebooks are not included by default
-            &[tempdir.path().to_path_buf(), notebook],
+            &[tempdir.path().to_path_buf()],
            &pyproject_config,
            &ConfigArguments::default(),
            flags::Cache::Disabled,
--- a/crates/ruff/tests/lint.rs
+++ b/crates/ruff/tests/lint.rs
@@ -1806,7 +1806,7 @@ select = ["UP006"]
 }

 #[test]
-fn checks_notebooks_in_preview_mode() -> anyhow::Result<()> {
+fn checks_notebooks_in_stable() -> anyhow::Result<()> {
    let tempdir = TempDir::new()?;
    std::fs::write(
        tempdir.path().join("main.ipynb"),
@@ -1853,7 +1853,6 @@ fn checks_notebooks_in_preview_mode() -> anyhow::Result<()> {
        .args(STDIN_BASE_OPTIONS)
        .arg("--select")
        .arg("F401")
-        .arg("--preview")
        .current_dir(&tempdir)
        , @r###"
    success: false
@@ -1867,64 +1866,3 @@ fn checks_notebooks_in_preview_mode() -> anyhow::Result<()> {
    "###);
    Ok(())
 }
-
-#[test]
-fn ignores_notebooks_in_stable() -> anyhow::Result<()> {
-    let tempdir = TempDir::new()?;
-    std::fs::write(
-        tempdir.path().join("main.ipynb"),
-        r#"
-{
- "cells": [
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "ad6f36d9-4b7d-4562-8d00-f15a0f1fbb6d",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import random"
-   ]
-  }
- ],
- "metadata": {
-  "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
-   "language": "python",
-   "name": "python3"
-  },
-  "language_info": {
-   "codemirror_mode": {
-    "name": "ipython",
-    "version": 3
-   },
-   "file_extension": ".py",
-   "mimetype": "text/x-python",
-   "name": "python",
-   "nbconvert_exporter": "python",
-   "pygments_lexer": "ipython3",
-   "version": "3.12.0"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 5
-}
-"#,
-    )?;
-
-    assert_cmd_snapshot!(Command::new(get_cargo_bin(BIN_NAME))
-        .args(STDIN_BASE_OPTIONS)
-        .arg("--select")
-        .arg("F401")
-        .current_dir(&tempdir)
-        , @r###"
-    success: true
-    exit_code: 0
-    ----- stdout -----
-    All checks passed!
-
-    ----- stderr -----
-    warning: No Python files found under the given path(s)
-    "###);
-    Ok(())
-}
--- a/crates/ruff/tests/snapshots/show_settings__display_default_settings.snap
+++ b/crates/ruff/tests/snapshots/show_settings__display_default_settings.snap
@@ -60,6 +60,7 @@ file_resolver.force_exclude = false
 file_resolver.include = [
 	"*.py",
 	"*.pyi",
+	"*.ipynb",
 	"**/pyproject.toml",
 ]
 file_resolver.extend_include = []
@@ -209,6 +210,7 @@ linter.logger_objects = []
 linter.namespace_packages = []
 linter.src = [
 	"[BASEPATH]",
+	"[BASEPATH]/src",
 ]
 linter.tab_size = 4
 linter.line_length = 88
@@ -260,10 +262,11 @@ linter.flake8_import_conventions.aliases = {
 	seaborn = sns,
 	tensorflow = tf,
 	tkinter = tk,
+	xml.etree.ElementTree = ET,
 }
 linter.flake8_import_conventions.banned_aliases = {}
 linter.flake8_import_conventions.banned_from = []
-linter.flake8_pytest_style.fixture_parentheses = true
+linter.flake8_pytest_style.fixture_parentheses = false
 linter.flake8_pytest_style.parametrize_names_type = tuple
 linter.flake8_pytest_style.parametrize_values_type = list
 linter.flake8_pytest_style.parametrize_values_row_type = tuple
@@ -277,7 +280,7 @@ linter.flake8_pytest_style.raises_require_match_for = [
 	socket.error,
 ]
 linter.flake8_pytest_style.raises_extend_require_match_for = []
-linter.flake8_pytest_style.mark_parentheses = true
+linter.flake8_pytest_style.mark_parentheses = false
 linter.flake8_quotes.inline_quotes = double
 linter.flake8_quotes.multiline_quotes = double
 linter.flake8_quotes.docstring_quotes = double
--- a/crates/ruff_benchmark/Cargo.toml
+++ b/crates/ruff_benchmark/Cargo.toml
@@ -52,6 +52,7 @@ ruff_python_ast = { workspace = true }
 ruff_python_formatter = { workspace = true }
 ruff_python_parser = { workspace = true }
 ruff_python_trivia = { workspace = true }
+red_knot_python_semantic = { workspace = true }
 red_knot_workspace = { workspace = true }

 [lints]
--- a/crates/ruff_benchmark/benches/red_knot.rs
+++ b/crates/ruff_benchmark/benches/red_knot.rs
@@ -1,11 +1,11 @@
 #![allow(clippy::disallowed_names)]

+use red_knot_python_semantic::{ProgramSettings, PythonVersion, SearchPathSettings};
 use red_knot_workspace::db::RootDatabase;
 use red_knot_workspace::workspace::WorkspaceMetadata;
 use ruff_benchmark::criterion::{criterion_group, criterion_main, BatchSize, Criterion};
 use ruff_benchmark::TestFile;
 use ruff_db::files::{system_path_to_file, File};
-use ruff_db::program::{ProgramSettings, SearchPathSettings, TargetVersion};
 use ruff_db::source::source_text;
 use ruff_db::system::{MemoryFileSystem, SystemPath, TestSystem};

@@ -43,7 +43,7 @@ fn setup_case() -> Case {
    let src_root = SystemPath::new("/src");
    let metadata = WorkspaceMetadata::from_path(src_root, &system).unwrap();
    let settings = ProgramSettings {
-        target_version: TargetVersion::Py312,
+        target_version: PythonVersion::PY312,
        search_paths: SearchPathSettings {
            extra_paths: vec![],
            src_root: src_root.to_path_buf(),
@@ -52,7 +52,7 @@ fn setup_case() -> Case {
        },
    };

-    let mut db = RootDatabase::new(metadata, settings, system);
+    let mut db = RootDatabase::new(metadata, settings, system).unwrap();
    let parser = system_path_to_file(&db, parser_path).unwrap();

    db.workspace().open_file(&mut db, parser);
@@ -89,7 +89,7 @@ fn benchmark_incremental(criterion: &mut Criterion) {
                let Case { db, parser, .. } = case;
                let result = db.check_file(*parser).unwrap();

-                assert_eq!(result.len(), 403);
+                assert_eq!(result.len(), 402);
            },
            BatchSize::SmallInput,
        );
@@ -104,7 +104,7 @@ fn benchmark_cold(criterion: &mut Criterion) {
                let Case { db, parser, .. } = case;
                let result = db.check_file(*parser).unwrap();

-                assert_eq!(result.len(), 403);
+                assert_eq!(result.len(), 402);
            },
            BatchSize::SmallInput,
        );
--- a/crates/ruff_db/Cargo.toml
+++ b/crates/ruff_db/Cargo.toml
@@ -27,7 +27,10 @@ ignore = { workspace = true, optional = true }
 matchit = { workspace = true }
 salsa = { workspace = true }
 path-slash = { workspace = true }
+thiserror = { workspace = true }
 tracing = { workspace = true }
+tracing-subscriber = { workspace = true, optional = true }
+tracing-tree = { workspace = true, optional = true }
 rustc-hash = { workspace = true }

 [target.'cfg(not(target_arch="wasm32"))'.dependencies]
@@ -44,3 +47,5 @@ tempfile = { workspace = true }
 [features]
 cache = ["ruff_cache"]
 os = ["ignore"]
+# Exposes testing utilities.
+testing = ["tracing-subscriber", "tracing-tree"]
--- a/crates/ruff_db/src/lib.rs
+++ b/crates/ruff_db/src/lib.rs
@@ -9,9 +9,9 @@ use crate::vendored::VendoredFileSystem;
 pub mod file_revision;
 pub mod files;
 pub mod parsed;
-pub mod program;
 pub mod source;
 pub mod system;
+#[cfg(feature = "testing")]
 pub mod testing;
 pub mod vendored;

--- a/crates/ruff_db/src/program.rs
+++ b/crates/ruff_db/src/program.rs
@@ -1,97 +0,0 @@
-use crate::{system::SystemPathBuf, Db};
-use salsa::Durability;
-
-#[salsa::input(singleton)]
-pub struct Program {
-    pub target_version: TargetVersion,
-
-    #[return_ref]
-    pub search_paths: SearchPathSettings,
-}
-
-impl Program {
-    pub fn from_settings(db: &dyn Db, settings: ProgramSettings) -> Self {
-        Program::builder(settings.target_version, settings.search_paths)
-            .durability(Durability::HIGH)
-            .new(db)
-    }
-}
-
-#[derive(Debug, Eq, PartialEq)]
-pub struct ProgramSettings {
-    pub target_version: TargetVersion,
-    pub search_paths: SearchPathSettings,
-}
-
-/// Enumeration of all supported Python versions
-///
-/// TODO: unify with the `PythonVersion` enum in the linter/formatter crates?
-#[derive(Copy, Clone, Hash, PartialEq, Eq, PartialOrd, Ord, Default)]
-pub enum TargetVersion {
-    Py37,
-    #[default]
-    Py38,
-    Py39,
-    Py310,
-    Py311,
-    Py312,
-    Py313,
-}
-
-impl TargetVersion {
-    pub const fn as_tuple(self) -> (u8, u8) {
-        match self {
-            Self::Py37 => (3, 7),
-            Self::Py38 => (3, 8),
-            Self::Py39 => (3, 9),
-            Self::Py310 => (3, 10),
-            Self::Py311 => (3, 11),
-            Self::Py312 => (3, 12),
-            Self::Py313 => (3, 13),
-        }
-    }
-
-    const fn as_str(self) -> &'static str {
-        match self {
-            Self::Py37 => "py37",
-            Self::Py38 => "py38",
-            Self::Py39 => "py39",
-            Self::Py310 => "py310",
-            Self::Py311 => "py311",
-            Self::Py312 => "py312",
-            Self::Py313 => "py313",
-        }
-    }
-}
-
-impl std::fmt::Display for TargetVersion {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        f.write_str(self.as_str())
-    }
-}
-
-impl std::fmt::Debug for TargetVersion {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        std::fmt::Display::fmt(self, f)
-    }
-}
-
-/// Configures the search paths for module resolution.
-#[derive(Eq, PartialEq, Debug, Clone, Default)]
-pub struct SearchPathSettings {
-    /// List of user-provided paths that should take first priority in the module resolution.
-    /// Examples in other type checkers are mypy's MYPYPATH environment variable,
-    /// or pyright's stubPath configuration setting.
-    pub extra_paths: Vec<SystemPathBuf>,
-
-    /// The root of the workspace, used for finding first-party modules.
-    pub src_root: SystemPathBuf,
-
-    /// Optional path to a "custom typeshed" directory on disk for us to use for standard-library types.
-    /// If this is not provided, we will fallback to our vendored typeshed stubs for the stdlib,
-    /// bundled as a zip file in the binary
-    pub custom_typeshed: Option<SystemPathBuf>,
-
-    /// The path to the user's `site-packages` directory, where third-party packages from ``PyPI`` are installed.
-    pub site_packages: Vec<SystemPathBuf>,
-}
--- a/crates/ruff_db/src/source.rs
+++ b/crates/ruff_db/src/source.rs
@@ -1,7 +1,9 @@
+use std::fmt::Formatter;
 use std::ops::Deref;
 use std::sync::Arc;

 use countme::Count;
+use salsa::Accumulator;

 use ruff_notebook::Notebook;
 use ruff_python_ast::PySourceType;
@@ -15,8 +17,42 @@ use crate::Db;
 pub fn source_text(db: &dyn Db, file: File) -> SourceText {
    let path = file.path(db);
    let _span = tracing::trace_span!("source_text", file = %path).entered();
+    let mut has_read_error = false;

-    let is_notebook = match path {
+    let kind = if is_notebook(file.path(db)) {
+        file.read_to_notebook(db)
+            .unwrap_or_else(|error| {
+                tracing::debug!("Failed to read notebook {path}: {error}");
+
+                has_read_error = true;
+                SourceDiagnostic(Arc::new(SourceTextError::FailedToReadNotebook(error)))
+                    .accumulate(db);
+                Notebook::empty()
+            })
+            .into()
+    } else {
+        file.read_to_string(db)
+            .unwrap_or_else(|error| {
+                tracing::debug!("Failed to read file {path}: {error}");
+
+                has_read_error = true;
+                SourceDiagnostic(Arc::new(SourceTextError::FailedToReadFile(error))).accumulate(db);
+                String::new()
+            })
+            .into()
+    };
+
+    SourceText {
+        inner: Arc::new(SourceTextInner {
+            kind,
+            has_read_error,
+            count: Count::new(),
+        }),
+    }
+}
+
+fn is_notebook(path: &FilePath) -> bool {
+    match path {
        FilePath::System(system) => system.extension().is_some_and(|extension| {
            PySourceType::try_from_extension(extension) == Some(PySourceType::Ipynb)
        }),
@@ -26,33 +62,6 @@ pub fn source_text(db: &dyn Db, file: File) -> SourceText {
            })
        }
        FilePath::Vendored(_) => false,
-    };
-
-    if is_notebook {
-        // TODO(micha): Proper error handling and emit a diagnostic. Tackle it together with `source_text`.
-        let notebook = file.read_to_notebook(db).unwrap_or_else(|error| {
-            tracing::error!("Failed to load notebook: {error}");
-            Notebook::empty()
-        });
-
-        return SourceText {
-            inner: Arc::new(SourceTextInner {
-                kind: SourceTextKind::Notebook(notebook),
-                count: Count::new(),
-            }),
-        };
-    }
-
-    let content = file.read_to_string(db).unwrap_or_else(|error| {
-        tracing::error!("Failed to load file: {error}");
-        String::default()
-    });
-
-    SourceText {
-        inner: Arc::new(SourceTextInner {
-            kind: SourceTextKind::Text(content),
-            count: Count::new(),
-        }),
    }
 }

@@ -87,6 +96,11 @@ impl SourceText {
    pub fn is_notebook(&self) -> bool {
        matches!(&self.inner.kind, SourceTextKind::Notebook(_))
    }
+
+    /// Returns `true` if there was an error when reading the content of the file.
+    pub fn has_read_error(&self) -> bool {
+        self.inner.has_read_error
+    }
 }

 impl Deref for SourceText {
@@ -118,6 +132,7 @@ impl std::fmt::Debug for SourceText {
 struct SourceTextInner {
    count: Count<SourceText>,
    kind: SourceTextKind,
+    has_read_error: bool,
 }

 #[derive(Eq, PartialEq)]
@@ -126,6 +141,35 @@ enum SourceTextKind {
    Notebook(Notebook),
 }

+impl From<String> for SourceTextKind {
+    fn from(value: String) -> Self {
+        SourceTextKind::Text(value)
+    }
+}
+
+impl From<Notebook> for SourceTextKind {
+    fn from(notebook: Notebook) -> Self {
+        SourceTextKind::Notebook(notebook)
+    }
+}
+
+#[salsa::accumulator]
+pub struct SourceDiagnostic(Arc<SourceTextError>);
+
+impl std::fmt::Display for SourceDiagnostic {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        std::fmt::Display::fmt(&self.0, f)
+    }
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum SourceTextError {
+    #[error("Failed to read notebook: {0}`")]
+    FailedToReadNotebook(#[from] ruff_notebook::NotebookError),
+    #[error("Failed to read file: {0}")]
+    FailedToReadFile(#[from] std::io::Error),
+}
+
 /// Computes the [`LineIndex`] for `file`.
 #[salsa::tracked]
 pub fn line_index(db: &dyn Db, file: File) -> LineIndex {
--- a/crates/ruff_db/src/testing.rs
+++ b/crates/ruff_db/src/testing.rs
@@ -1,5 +1,8 @@
 //! Test helpers for working with Salsa databases

+use tracing_subscriber::layer::SubscriberExt;
+use tracing_subscriber::EnvFilter;
+
 pub fn assert_function_query_was_not_run<Db, Q, QDb, I, R>(
    db: &Db,
    query: Q,
@@ -94,6 +97,116 @@ fn query_name<Q>(_query: &Q) -> &'static str {
        .unwrap_or(full_qualified_query_name)
 }

+/// Sets up logging for the current thread. It captures all `red_knot` and `ruff` events.
+///
+/// Useful for capturing the tracing output in a failing test.
+///
+/// # Examples
+/// ```
+/// use ruff_db::testing::setup_logging;
+/// let _logging = setup_logging();
+///
+/// tracing::info!("This message will be printed to stderr");
+/// ```
+pub fn setup_logging() -> LoggingGuard {
+    LoggingBuilder::new().build()
+}
+
+/// Sets up logging for the current thread and uses the passed filter to filter the shown events.
+/// Useful for capturing the tracing output in a failing test.
+///
+/// # Examples
+/// ```
+/// use ruff_db::testing::setup_logging_with_filter;
+/// let _logging = setup_logging_with_filter("red_knot_module_resolver::resolver");
+/// ```
+///
+/// # Filter
+/// See [`tracing_subscriber::EnvFilter`] for the `filter`'s syntax.
+///
+pub fn setup_logging_with_filter(filter: &str) -> Option<LoggingGuard> {
+    LoggingBuilder::with_filter(filter).map(LoggingBuilder::build)
+}
+
+#[derive(Debug)]
+pub struct LoggingBuilder {
+    filter: EnvFilter,
+    hierarchical: bool,
+}
+
+impl LoggingBuilder {
+    pub fn new() -> Self {
+        Self {
+            filter: EnvFilter::default()
+                .add_directive(
+                    "red_knot=trace"
+                        .parse()
+                        .expect("Hardcoded directive to be valid"),
+                )
+                .add_directive(
+                    "ruff=trace"
+                        .parse()
+                        .expect("Hardcoded directive to be valid"),
+                ),
+            hierarchical: true,
+        }
+    }
+
+    pub fn with_filter(filter: &str) -> Option<Self> {
+        let filter = EnvFilter::builder().parse(filter).ok()?;
+
+        Some(Self {
+            filter,
+            hierarchical: true,
+        })
+    }
+
+    pub fn with_hierarchical(mut self, hierarchical: bool) -> Self {
+        self.hierarchical = hierarchical;
+        self
+    }
+
+    pub fn build(self) -> LoggingGuard {
+        let registry = tracing_subscriber::registry().with(self.filter);
+
+        let guard = if self.hierarchical {
+            let subscriber = registry.with(
+                tracing_tree::HierarchicalLayer::default()
+                    .with_indent_lines(true)
+                    .with_indent_amount(2)
+                    .with_bracketed_fields(true)
+                    .with_thread_ids(true)
+                    .with_targets(true)
+                    .with_writer(std::io::stderr)
+                    .with_timer(tracing_tree::time::Uptime::default()),
+            );
+
+            tracing::subscriber::set_default(subscriber)
+        } else {
+            let subscriber = registry.with(
+                tracing_subscriber::fmt::layer()
+                    .compact()
+                    .with_writer(std::io::stderr)
+                    .with_timer(tracing_subscriber::fmt::time()),
+            );
+
+            tracing::subscriber::set_default(subscriber)
+        };
+
+        LoggingGuard { _guard: guard }
+    }
+}
+
+impl Default for LoggingBuilder {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+pub struct LoggingGuard {
+    _guard: tracing::subscriber::DefaultGuard,
+}
+
 #[test]
 fn query_was_not_run() {
    use crate::tests::TestDb;
--- a/crates/ruff_diagnostics/src/violation.rs
+++ b/crates/ruff_diagnostics/src/violation.rs
@@ -18,7 +18,7 @@ impl Display for FixAvailability {
 }

 pub trait Violation: Debug + PartialEq + Eq {
-    /// `None` in the case an fix is never available or otherwise Some
+    /// `None` in the case a fix is never available or otherwise Some
    /// [`FixAvailability`] describing the available fix.
    const FIX_AVAILABILITY: FixAvailability = FixAvailability::None;

--- a/crates/ruff_linter/resources/test/fixtures/flake8_comprehensions/C420.py
+++ b/crates/ruff_linter/resources/test/fixtures/flake8_comprehensions/C420.py
--- a/crates/ruff_linter/resources/test/fixtures/flake8_return/RET503.py
+++ b/crates/ruff_linter/resources/test/fixtures/flake8_return/RET503.py
@@ -368,3 +368,11 @@ def foo() -> int:
    if baz() > 3:
        return 1
    bar()
+
+
+def f():
+    if a:
+        return b
+    else:
+        with c:
+            d
--- a/crates/ruff_linter/resources/test/fixtures/flake8_return/RET505.py
+++ b/crates/ruff_linter/resources/test/fixtures/flake8_return/RET505.py
@@ -244,3 +244,11 @@ def f():
 	 return True
 	else:
 	 return False
+
+
+def has_untracted_files():
+    if b'Untracked files' in result.stdout:
+        return True
+    else:
+\
+        return False
--- a/crates/ruff_linter/resources/test/fixtures/flake8_simplify/SIM108.py
+++ b/crates/ruff_linter/resources/test/fixtures/flake8_simplify/SIM108.py
@@ -135,3 +135,62 @@ if TYPE_CHECKING:
    x = 3
 else:
    x = 5
+
+# SIM108 - should suggest
+# z = cond or other_cond
+if cond:
+    z = cond 
+else:
+    z = other_cond
+
+# SIM108 - should suggest
+# z = cond and other_cond
+if not cond:
+    z = cond
+else:
+    z = other_cond
+
+# SIM108 - should suggest
+# z = not cond and other_cond
+if cond:
+    z = not cond
+else:
+    z = other_cond
+
+# SIM108 does not suggest
+# a binary option in these cases,
+# despite the fact that `bool` 
+# is a subclass of both `int` and `float`
+# so, e.g. `True == 1`.
+# (Of course, these specific expressions 
+# should be simplified for other reasons...)
+if True:
+    z = 1
+else:
+    z = other
+
+if False:
+    z = 1
+else:
+    z = other
+
+if 1:
+    z = True
+else:
+    z = other
+
+# SIM108 does not suggest a binary option in this
+# case, since we'd be reducing the number of calls
+# from Two to one.
+if foo():
+    z = foo()
+else:
+    z = other
+
+# SIM108 does not suggest a binary option in this
+# case, since we'd be reducing the number of calls
+# from Two to one.
+if foo():
+    z = not foo()
+else:
+    z = other
--- a/crates/ruff_linter/resources/test/fixtures/flake8_type_checking/kw_only.py
+++ b/crates/ruff_linter/resources/test/fixtures/flake8_type_checking/kw_only.py
@@ -0,0 +1,18 @@
+"""Test: avoid marking a `KW_ONLY` annotation as typing-only."""
+
+from __future__ import annotations
+
+from dataclasses import KW_ONLY, dataclass, Field
+
+
+@dataclass
+class Test1:
+    a: int
+    _: KW_ONLY
+    b: str
+
+
+@dataclass
+class Test2:
+    a: int
+    b: Field
--- a/crates/ruff_linter/resources/test/fixtures/pep8_naming/N805.py
+++ b/crates/ruff_linter/resources/test/fixtures/pep8_naming/N805.py
@@ -123,3 +123,14 @@ class RenamingInMethodBodyClass:
 class RenamingWithNFKC:
    def formula(household):
        hºusehold(1)
+
+
+from typing import Protocol
+
+
+class MyMeta(type):
+    def __subclasscheck__(cls, other): ...
+
+
+class MyProtocolMeta(type(Protocol)):
+    def __subclasscheck__(cls, other): ...
--- a/crates/ruff_linter/resources/test/fixtures/pydoclint/DOC201_google.py
+++ b/crates/ruff_linter/resources/test/fixtures/pydoclint/DOC201_google.py
@@ -108,3 +108,14 @@ def f(num: int):
        num (int): A number
    """
    return 1
+
+
+import abc
+
+
+class A(metaclass=abc.abcmeta):
+    # DOC201
+    @abc.abstractmethod
+    def f(self):
+        """Lorem ipsum."""
+        return True
--- a/crates/ruff_linter/resources/test/fixtures/pydoclint/DOC201_numpy.py
+++ b/crates/ruff_linter/resources/test/fixtures/pydoclint/DOC201_numpy.py
@@ -74,3 +74,14 @@ class Bar:
            A number
        """
        return 'test'
+
+
+import abc
+
+
+class A(metaclass=abc.abcmeta):
+    # DOC201
+    @abc.abstractmethod
+    def f(self):
+        """Lorem ipsum."""
+        return True
--- a/crates/ruff_linter/resources/test/fixtures/pydoclint/DOC202_google.py
+++ b/crates/ruff_linter/resources/test/fixtures/pydoclint/DOC202_google.py
@@ -59,3 +59,17 @@ class C:
            x
        """
        raise NotImplementedError
+
+
+import abc
+
+
+class A(metaclass=abc.abcmeta):
+    @abc.abstractmethod
+    def f(self):
+        """Lorem ipsum
+
+        Returns:
+            dict: The values
+        """
+        return
--- a/crates/ruff_linter/resources/test/fixtures/pydoclint/DOC202_numpy.py
+++ b/crates/ruff_linter/resources/test/fixtures/pydoclint/DOC202_numpy.py
@@ -60,3 +60,19 @@ class Bar:
            A number
        """
        print('test')
+
+
+import abc
+
+
+class A(metaclass=abc.abcmeta):
+    @abc.abstractmethod
+    def f(self):
+        """Lorem ipsum
+
+        Returns
+        -------
+        dict:
+            The values
+        """
+        return
--- a/crates/ruff_linter/resources/test/fixtures/pyflakes/F821_17.py
+++ b/crates/ruff_linter/resources/test/fixtures/pyflakes/F821_17.py
@@ -111,3 +111,7 @@ def can_access_inside_nested[T](t: T) -> T:  # OK
        return x

    bar(t)
+
+
+def cannot_access_in_default[T](t: T = T):  # F821
+    pass
--- a/crates/ruff_linter/resources/test/fixtures/pyupgrade/UP031_0.py
+++ b/crates/ruff_linter/resources/test/fixtures/pyupgrade/UP031_0.py
@@ -139,3 +139,33 @@ print("%.20X" % 1)

 print("%2X" % 1)
 print("%02X" % 1)
+
+# UP031 (no longer false negatives, but offer no fix because of more complex syntax)
+
+"%d.%d" % (a, b)
+
+"%*s" % (5, "hi")
+
+"%d" % (flt,)
+
+"%c" % (some_string,)
+
+"%.2r" % (1.25)
+
+"%.*s" % (5, "hi")
+
+"%i" % (flt,)
+
+"%()s" % {"": "empty"}
+
+"%s" % {"k": "v"}
+
+"%()s" % {"": "bar"}
+
+"%(1)s" % {"1": "bar"}
+
+"%(a)s" % {"a": 1, "a": 2}
+
+"%(1)s" % {1: 2, "1": 2}
+
+"%(and)s" % {"and": 2}
--- a/crates/ruff_linter/resources/test/fixtures/pyupgrade/UP031_1.py
+++ b/crates/ruff_linter/resources/test/fixtures/pyupgrade/UP031_1.py
@@ -1,34 +1,8 @@
 # OK
 b"%s" % (b"bytestring",)

-"%*s" % (5, "hi")
-
-"%d" % (flt,)
-
-"%c" % (some_string,)
-
 "%4%" % ()

-"%.2r" % (1.25)
-
 i % 3

-"%.*s" % (5, "hi")
-
-"%i" % (flt,)
-
-"%()s" % {"": "empty"}
-
-"%s" % {"k": "v"}
-
-"%(1)s" % {"1": "bar"}
-
-"%(a)s" % {"a": 1, "a": 2}
-
 pytest.param('"%8s" % (None,)', id="unsafe width-string conversion"),
-
-"%()s" % {"": "bar"}
-
-"%(1)s" % {1: 2, "1": 2}
-
-"%(and)s" % {"and": 2}
--- a/crates/ruff_linter/resources/test/fixtures/ruff/RUF027_1.py
+++ b/crates/ruff_linter/resources/test/fixtures/ruff/RUF027_1.py
@@ -45,3 +45,17 @@ def negative_cases():

    import django.utils.translations
    y = django.utils.translations.gettext("This {should} be understood as a translation string too!")
+
+    # Calling `gettext.install()` literall monkey-patches `builtins._ = ...`,
+    # so even the fully qualified access of `builtins._()` should be considered
+    # a possible `gettext` call.
+    import builtins
+    another = 42
+    z = builtins._("{another} translation string")
+
+    # Usually logging strings use `%`-style string interpolation,
+    # but `logging` can be configured to use `{}` the same as f-strings,
+    # so these should also be ignored.
+    # See https://docs.python.org/3/howto/logging-cookbook.html#formatting-styles
+    import logging
+    logging.info("yet {another} non-f-string")
--- a/crates/ruff_linter/resources/test/fixtures/ruff/RUF031.py
+++ b/crates/ruff_linter/resources/test/fixtures/ruff/RUF031.py
@@ -26,4 +26,19 @@ token_features[

 d[1,]
 d[(1,)]
-d[()] # empty tuples should be ignored
+d[()] # empty tuples should be ignored
+d[:,] # slices in the subscript lead to syntax error if parens are added
+d[1,2,:]
+
+# Should keep these parentheses in
+# Python <=3.10 to avoid syntax error.
+# https://github.com/astral-sh/ruff/issues/12776
+d[(*foo,bar)]
+
+x: dict[str, int]  # tuples inside type annotations should never be altered
+
+import typing
+
+type Y = typing.Literal[1, 2]
+Z: typing.TypeAlias = dict[int, int]
+class Foo(dict[str, int]): pass
--- a/crates/ruff_linter/resources/test/fixtures/ruff/RUF031_prefer_parens.py
+++ b/crates/ruff_linter/resources/test/fixtures/ruff/RUF031_prefer_parens.py
@@ -25,4 +25,20 @@ token_features[
 ] = self._extract_raw_features_from_token
 d[1,]
 d[(1,)]
-d[()] # empty tuples should be ignored
+d[()] # empty tuples should be ignored
+
+d[:,] # slices in the subscript lead to syntax error if parens are added
+d[1,2,:]
+
+# Should keep these parentheses in
+# Python <=3.10 to avoid syntax error.
+# https://github.com/astral-sh/ruff/issues/12776
+d[(*foo,bar)]
+
+x: dict[str, int]  # tuples inside type annotations should never be altered
+
+import typing
+
+type Y = typing.Literal[1, 2]
+Z: typing.TypeAlias = dict[int, int]
+class Foo(dict[str, int]): pass
--- a/crates/ruff_linter/src/checkers/ast/analyze/expression.rs
+++ b/crates/ruff_linter/src/checkers/ast/analyze/expression.rs
@@ -1077,12 +1077,7 @@ pub(crate) fn expression(expr: &Expr, checker: &mut Checker) {
            }
            if checker.enabled(Rule::MissingFStringSyntax) {
                for string_literal in value.literals() {
-                    ruff::rules::missing_fstring_syntax(
-                        &mut checker.diagnostics,
-                        string_literal,
-                        checker.locator,
-                        &checker.semantic,
-                    );
+                    ruff::rules::missing_fstring_syntax(checker, string_literal);
                }
            }
        }
@@ -1378,12 +1373,7 @@ pub(crate) fn expression(expr: &Expr, checker: &mut Checker) {
            }
            if checker.enabled(Rule::MissingFStringSyntax) {
                for string_literal in value.as_slice() {
-                    ruff::rules::missing_fstring_syntax(
-                        &mut checker.diagnostics,
-                        string_literal,
-                        checker.locator,
-                        &checker.semantic,
-                    );
+                    ruff::rules::missing_fstring_syntax(checker, string_literal);
                }
            }
        }
@@ -1498,7 +1488,9 @@ pub(crate) fn expression(expr: &Expr, checker: &mut Checker) {
            }

            if checker.enabled(Rule::UnnecessaryDictComprehensionForIterable) {
-                ruff::rules::unnecessary_dict_comprehension_for_iterable(checker, dict_comp);
+                flake8_comprehensions::rules::unnecessary_dict_comprehension_for_iterable(
+                    checker, dict_comp,
+                );
            }

            if checker.enabled(Rule::FunctionUsesLoopVariable) {
--- a/crates/ruff_linter/src/checkers/ast/analyze/statement.rs
+++ b/crates/ruff_linter/src/checkers/ast/analyze/statement.rs
@@ -229,12 +229,7 @@ pub(crate) fn statement(stmt: &Stmt, checker: &mut Checker) {
                Rule::SuperfluousElseContinue,
                Rule::SuperfluousElseBreak,
            ]) {
-                flake8_return::rules::function(
-                    checker,
-                    body,
-                    decorator_list,
-                    returns.as_ref().map(AsRef::as_ref),
-                );
+                flake8_return::rules::function(checker, function_def);
            }
            if checker.enabled(Rule::UselessReturn) {
                pylint::rules::useless_return(
--- a/crates/ruff_linter/src/checkers/ast/mod.rs
+++ b/crates/ruff_linter/src/checkers/ast/mod.rs
@@ -691,6 +691,14 @@ impl<'a> Visitor<'a> for Checker<'a> {
                        self.semantic(),
                    );

+                // The default values of the parameters needs to be evaluated in the enclosing
+                // scope.
+                for parameter in &**parameters {
+                    if let Some(expr) = parameter.default() {
+                        self.visit_expr(expr);
+                    }
+                }
+
                self.semantic.push_scope(ScopeKind::Type);

                if let Some(type_params) = type_params {
@@ -715,9 +723,6 @@ impl<'a> Visitor<'a> for Checker<'a> {
                            }
                        }
                    }
-                    if let Some(expr) = parameter.default() {
-                        self.visit_expr(expr);
-                    }
                }
                if let Some(expr) = returns {
                    match annotation {
@@ -1290,8 +1295,8 @@ impl<'a> Visitor<'a> for Checker<'a> {
                            let Keyword { arg, value, .. } = keyword;
                            match (arg.as_ref(), value) {
                                // Ex) NamedTuple("a", **{"a": int})
-                                (None, Expr::Dict(ast::ExprDict { items, .. })) => {
-                                    for ast::DictItem { key, value } in items {
+                                (None, Expr::Dict(dict)) => {
+                                    for ast::DictItem { key, value } in dict {
                                        if let Some(key) = key.as_ref() {
                                            self.visit_non_type_definition(key);
                                            self.visit_type_definition(value);
--- a/crates/ruff_linter/src/codes.rs
+++ b/crates/ruff_linter/src/codes.rs
@@ -4,12 +4,12 @@
 /// `--select`. For pylint this is e.g. C0414 and E0118 but also C and E01.
 use std::fmt::Formatter;

+use strum_macros::{AsRefStr, EnumIter};
+
 use crate::registry::{AsRule, Linter};
 use crate::rule_selector::is_single_rule_selector;
 use crate::rules;

-use strum_macros::{AsRefStr, EnumIter};
-
 #[derive(PartialEq, Eq, PartialOrd, Ord)]
 pub struct NoqaCode(&'static str, &'static str);

@@ -206,12 +206,12 @@ pub fn code_to_rule(linter: Linter, code: &str) -> Option<(RuleGroup, Rule)> {
        (Pylint, "E0237") => (RuleGroup::Stable, rules::pylint::rules::NonSlotAssignment),
        (Pylint, "E0241") => (RuleGroup::Stable, rules::pylint::rules::DuplicateBases),
        (Pylint, "E0302") => (RuleGroup::Stable, rules::pylint::rules::UnexpectedSpecialMethodSignature),
-        (Pylint, "E0303") => (RuleGroup::Preview, rules::pylint::rules::InvalidLengthReturnType),
+        (Pylint, "E0303") => (RuleGroup::Stable, rules::pylint::rules::InvalidLengthReturnType),
        (Pylint, "E0304") => (RuleGroup::Preview, rules::pylint::rules::InvalidBoolReturnType),
-        (Pylint, "E0305") => (RuleGroup::Preview, rules::pylint::rules::InvalidIndexReturnType),
+        (Pylint, "E0305") => (RuleGroup::Stable, rules::pylint::rules::InvalidIndexReturnType),
        (Pylint, "E0307") => (RuleGroup::Stable, rules::pylint::rules::InvalidStrReturnType),
-        (Pylint, "E0308") => (RuleGroup::Preview, rules::pylint::rules::InvalidBytesReturnType),
-        (Pylint, "E0309") => (RuleGroup::Preview, rules::pylint::rules::InvalidHashReturnType),
+        (Pylint, "E0308") => (RuleGroup::Stable, rules::pylint::rules::InvalidBytesReturnType),
+        (Pylint, "E0309") => (RuleGroup::Stable, rules::pylint::rules::InvalidHashReturnType),
        (Pylint, "E0604") => (RuleGroup::Stable, rules::pylint::rules::InvalidAllObject),
        (Pylint, "E0605") => (RuleGroup::Stable, rules::pylint::rules::InvalidAllFormat),
        (Pylint, "E0643") => (RuleGroup::Stable, rules::pylint::rules::PotentialIndexError),
@@ -225,8 +225,8 @@ pub fn code_to_rule(linter: Linter, code: &str) -> Option<(RuleGroup, Rule)> {
        (Pylint, "E1307") => (RuleGroup::Stable, rules::pylint::rules::BadStringFormatType),
        (Pylint, "E1310") => (RuleGroup::Stable, rules::pylint::rules::BadStrStripCall),
        (Pylint, "E1507") => (RuleGroup::Stable, rules::pylint::rules::InvalidEnvvarValue),
-        (Pylint, "E1519") => (RuleGroup::Preview, rules::pylint::rules::SingledispatchMethod),
-        (Pylint, "E1520") => (RuleGroup::Preview, rules::pylint::rules::SingledispatchmethodFunction),
+        (Pylint, "E1519") => (RuleGroup::Stable, rules::pylint::rules::SingledispatchMethod),
+        (Pylint, "E1520") => (RuleGroup::Stable, rules::pylint::rules::SingledispatchmethodFunction),
        (Pylint, "E1700") => (RuleGroup::Stable, rules::pylint::rules::YieldFromInAsyncFunction),
        (Pylint, "E2502") => (RuleGroup::Stable, rules::pylint::rules::BidirectionalUnicode),
        (Pylint, "E2510") => (RuleGroup::Stable, rules::pylint::rules::InvalidCharacterBackspace),
@@ -256,7 +256,7 @@ pub fn code_to_rule(linter: Linter, code: &str) -> Option<(RuleGroup, Rule)> {
        (Pylint, "R1711") => (RuleGroup::Stable, rules::pylint::rules::UselessReturn),
        (Pylint, "R1714") => (RuleGroup::Stable, rules::pylint::rules::RepeatedEqualityComparison),
        (Pylint, "R1722") => (RuleGroup::Stable, rules::pylint::rules::SysExitAlias),
-        (Pylint, "R1730") => (RuleGroup::Preview, rules::pylint::rules::IfStmtMinMax),
+        (Pylint, "R1730") => (RuleGroup::Stable, rules::pylint::rules::IfStmtMinMax),
        (Pylint, "R1733") => (RuleGroup::Preview, rules::pylint::rules::UnnecessaryDictIndexLookup),
        (Pylint, "R1736") => (RuleGroup::Stable, rules::pylint::rules::UnnecessaryListIndexLookup),
        (Pylint, "R2004") => (RuleGroup::Stable, rules::pylint::rules::MagicValueComparison),
@@ -273,13 +273,13 @@ pub fn code_to_rule(linter: Linter, code: &str) -> Option<(RuleGroup, Rule)> {
        (Pylint, "W0129") => (RuleGroup::Stable, rules::pylint::rules::AssertOnStringLiteral),
        (Pylint, "W0131") => (RuleGroup::Stable, rules::pylint::rules::NamedExprWithoutContext),
        (Pylint, "W0133") => (RuleGroup::Stable, rules::pylint::rules::UselessExceptionStatement),
-        (Pylint, "W0211") => (RuleGroup::Preview, rules::pylint::rules::BadStaticmethodArgument),
+        (Pylint, "W0211") => (RuleGroup::Stable, rules::pylint::rules::BadStaticmethodArgument),
        (Pylint, "W0245") => (RuleGroup::Stable, rules::pylint::rules::SuperWithoutBrackets),
        (Pylint, "W0406") => (RuleGroup::Stable, rules::pylint::rules::ImportSelf),
        (Pylint, "W0602") => (RuleGroup::Stable, rules::pylint::rules::GlobalVariableNotAssigned),
        (Pylint, "W0603") => (RuleGroup::Stable, rules::pylint::rules::GlobalStatement),
        (Pylint, "W0604") => (RuleGroup::Stable, rules::pylint::rules::GlobalAtModuleLevel),
-        (Pylint, "W0642") => (RuleGroup::Preview, rules::pylint::rules::SelfOrClsAssignment),
+        (Pylint, "W0642") => (RuleGroup::Stable, rules::pylint::rules::SelfOrClsAssignment),
        (Pylint, "W0711") => (RuleGroup::Stable, rules::pylint::rules::BinaryOpException),
        (Pylint, "W1501") => (RuleGroup::Stable, rules::pylint::rules::BadOpenMode),
        (Pylint, "W1508") => (RuleGroup::Stable, rules::pylint::rules::InvalidEnvvarDefault),
@@ -378,6 +378,7 @@ pub fn code_to_rule(linter: Linter, code: &str) -> Option<(RuleGroup, Rule)> {
        (Flake8Comprehensions, "17") => (RuleGroup::Stable, rules::flake8_comprehensions::rules::UnnecessaryMap),
        (Flake8Comprehensions, "18") => (RuleGroup::Stable, rules::flake8_comprehensions::rules::UnnecessaryLiteralWithinDictCall),
        (Flake8Comprehensions, "19") => (RuleGroup::Stable, rules::flake8_comprehensions::rules::UnnecessaryComprehensionInCall),
+        (Flake8Comprehensions, "20") => (RuleGroup::Preview, rules::flake8_comprehensions::rules::UnnecessaryDictComprehensionForIterable),

        // flake8-debugger
        (Flake8Debugger, "0") => (RuleGroup::Stable, rules::flake8_debugger::rules::Debugger),
@@ -509,7 +510,7 @@ pub fn code_to_rule(linter: Linter, code: &str) -> Option<(RuleGroup, Rule)> {
        (Pyupgrade, "024") => (RuleGroup::Stable, rules::pyupgrade::rules::OSErrorAlias),
        (Pyupgrade, "025") => (RuleGroup::Stable, rules::pyupgrade::rules::UnicodeKindPrefix),
        (Pyupgrade, "026") => (RuleGroup::Stable, rules::pyupgrade::rules::DeprecatedMockImport),
-        (Pyupgrade, "027") => (RuleGroup::Stable, rules::pyupgrade::rules::UnpackedListComprehension),
+        (Pyupgrade, "027") => (RuleGroup::Deprecated, rules::pyupgrade::rules::UnpackedListComprehension),
        (Pyupgrade, "028") => (RuleGroup::Stable, rules::pyupgrade::rules::YieldInForLoop),
        (Pyupgrade, "029") => (RuleGroup::Stable, rules::pyupgrade::rules::UnnecessaryBuiltinImport),
        (Pyupgrade, "030") => (RuleGroup::Stable, rules::pyupgrade::rules::FormatLiterals),
@@ -778,9 +779,9 @@ pub fn code_to_rule(linter: Linter, code: &str) -> Option<(RuleGroup, Rule)> {
        (Flake8Pyi, "055") => (RuleGroup::Stable, rules::flake8_pyi::rules::UnnecessaryTypeUnion),
        (Flake8Pyi, "056") => (RuleGroup::Stable, rules::flake8_pyi::rules::UnsupportedMethodCallOnAll),
        (Flake8Pyi, "058") => (RuleGroup::Stable, rules::flake8_pyi::rules::GeneratorReturnFromIterMethod),
-        (Flake8Pyi, "057") => (RuleGroup::Preview, rules::flake8_pyi::rules::ByteStringUsage),
+        (Flake8Pyi, "057") => (RuleGroup::Stable, rules::flake8_pyi::rules::ByteStringUsage),
        (Flake8Pyi, "059") => (RuleGroup::Preview, rules::flake8_pyi::rules::GenericNotLastBaseClass),
-        (Flake8Pyi, "062") => (RuleGroup::Preview, rules::flake8_pyi::rules::DuplicateLiteralMember),
+        (Flake8Pyi, "062") => (RuleGroup::Stable, rules::flake8_pyi::rules::DuplicateLiteralMember),
        (Flake8Pyi, "063") => (RuleGroup::Preview, rules::flake8_pyi::rules::PrePep570PositionalArgument),
        (Flake8Pyi, "064") => (RuleGroup::Preview, rules::flake8_pyi::rules::RedundantFinalLiteral),
        (Flake8Pyi, "066") => (RuleGroup::Preview, rules::flake8_pyi::rules::BadVersionInfoOrder),
@@ -789,8 +790,8 @@ pub fn code_to_rule(linter: Linter, code: &str) -> Option<(RuleGroup, Rule)> {
        (Flake8PytestStyle, "001") => (RuleGroup::Stable, rules::flake8_pytest_style::rules::PytestFixtureIncorrectParenthesesStyle),
        (Flake8PytestStyle, "002") => (RuleGroup::Stable, rules::flake8_pytest_style::rules::PytestFixturePositionalArgs),
        (Flake8PytestStyle, "003") => (RuleGroup::Stable, rules::flake8_pytest_style::rules::PytestExtraneousScopeFunction),
-        (Flake8PytestStyle, "004") => (RuleGroup::Stable, rules::flake8_pytest_style::rules::PytestMissingFixtureNameUnderscore),
-        (Flake8PytestStyle, "005") => (RuleGroup::Stable, rules::flake8_pytest_style::rules::PytestIncorrectFixtureNameUnderscore),
+        (Flake8PytestStyle, "004") => (RuleGroup::Deprecated, rules::flake8_pytest_style::rules::PytestMissingFixtureNameUnderscore),
+        (Flake8PytestStyle, "005") => (RuleGroup::Deprecated, rules::flake8_pytest_style::rules::PytestIncorrectFixtureNameUnderscore),
        (Flake8PytestStyle, "006") => (RuleGroup::Stable, rules::flake8_pytest_style::rules::PytestParametrizeNamesWrongType),
        (Flake8PytestStyle, "007") => (RuleGroup::Stable, rules::flake8_pytest_style::rules::PytestParametrizeValuesWrongType),
        (Flake8PytestStyle, "008") => (RuleGroup::Stable, rules::flake8_pytest_style::rules::PytestPatchWithLambda),
@@ -951,7 +952,6 @@ pub fn code_to_rule(linter: Linter, code: &str) -> Option<(RuleGroup, Rule)> {
        (Ruff, "022") => (RuleGroup::Preview, rules::ruff::rules::UnsortedDunderAll),
        (Ruff, "023") => (RuleGroup::Preview, rules::ruff::rules::UnsortedDunderSlots),
        (Ruff, "024") => (RuleGroup::Stable, rules::ruff::rules::MutableFromkeysValue),
-        (Ruff, "025") => (RuleGroup::Preview, rules::ruff::rules::UnnecessaryDictComprehensionForIterable),
        (Ruff, "026") => (RuleGroup::Stable, rules::ruff::rules::DefaultFactoryKwarg),
        (Ruff, "027") => (RuleGroup::Preview, rules::ruff::rules::MissingFStringSyntax),
        (Ruff, "028") => (RuleGroup::Preview, rules::ruff::rules::InvalidFormatterSuppressionComment),
@@ -959,7 +959,7 @@ pub fn code_to_rule(linter: Linter, code: &str) -> Option<(RuleGroup, Rule)> {
        (Ruff, "030") => (RuleGroup::Preview, rules::ruff::rules::AssertWithPrintMessage),
        (Ruff, "031") => (RuleGroup::Preview, rules::ruff::rules::IncorrectlyParenthesizedTupleInSubscript),
        (Ruff, "100") => (RuleGroup::Stable, rules::ruff::rules::UnusedNOQA),
-        (Ruff, "101") => (RuleGroup::Preview, rules::ruff::rules::RedirectedNOQA),
+        (Ruff, "101") => (RuleGroup::Stable, rules::ruff::rules::RedirectedNOQA),

        (Ruff, "200") => (RuleGroup::Stable, rules::ruff::rules::InvalidPyprojectToml),
        #[cfg(any(feature = "test-rules", test))]
--- a/crates/ruff_linter/src/fix/edits.rs
+++ b/crates/ruff_linter/src/fix/edits.rs
@@ -151,16 +151,15 @@ pub(crate) fn add_to_dunder_all<'a>(
    stylist: &Stylist,
 ) -> Vec<Edit> {
    let (insertion_point, export_prefix_length) = match expr {
-        Expr::List(ExprList { elts, range, .. }) => (
-            elts.last()
-                .map_or(range.end() - "]".text_len(), Ranged::end),
+        Expr::List(ExprList { elts, .. }) => (
+            elts.last().map_or(expr.end() - "]".text_len(), Ranged::end),
            elts.len(),
        ),
        Expr::Tuple(tup) if tup.parenthesized => (
            tup.elts
                .last()
                .map_or(tup.end() - ")".text_len(), Ranged::end),
-            tup.elts.len(),
+            tup.len(),
        ),
        Expr::Tuple(tup) if !tup.parenthesized => (
            tup.elts
@@ -168,7 +167,7 @@ pub(crate) fn add_to_dunder_all<'a>(
                .expect("unparenthesized empty tuple is not possible")
                .range()
                .end(),
-            tup.elts.len(),
+            tup.len(),
        ),
        _ => {
            // we don't know how to insert into this expression
@@ -318,26 +317,28 @@ pub(crate) fn adjust_indentation(
        line_indentation.contains('\t') && line_indentation.contains(' ')
    });

-    if contains_multiline_string || mixed_indentation {
-        let module_text = format!("def f():{}{contents}", stylist.line_ending().as_str());
-
-        let mut tree = match_statement(&module_text)?;
-
-        let embedding = match_function_def(&mut tree)?;
-
-        let indented_block = match_indented_block(&mut embedding.body)?;
-        indented_block.indent = Some(indentation);
-
-        let module_text = indented_block.codegen_stylist(stylist);
-        let module_text = module_text
-            .strip_prefix(stylist.line_ending().as_str())
-            .unwrap()
-            .to_string();
-        Ok(module_text)
-    } else {
-        // Otherwise, we can do a simple adjustment ourselves.
-        Ok(dedent_to(contents, indentation))
+    // For simple cases, try to do a manual dedent.
+    if !contains_multiline_string && !mixed_indentation {
+        if let Some(dedent) = dedent_to(contents, indentation) {
+            return Ok(dedent);
+        }
    }
+
+    let module_text = format!("def f():{}{contents}", stylist.line_ending().as_str());
+
+    let mut tree = match_statement(&module_text)?;
+
+    let embedding = match_function_def(&mut tree)?;
+
+    let indented_block = match_indented_block(&mut embedding.body)?;
+    indented_block.indent = Some(indentation);
+
+    let module_text = indented_block.codegen_stylist(stylist);
+    let module_text = module_text
+        .strip_prefix(stylist.line_ending().as_str())
+        .unwrap()
+        .to_string();
+    Ok(module_text)
 }

 /// Determine if a vector contains only one, specific element.
--- a/crates/ruff_linter/src/linter.rs
+++ b/crates/ruff_linter/src/linter.rs
@@ -791,6 +791,23 @@ mod tests {
        Ok(())
    }

+    #[test]
+    fn test_vscode_language_id() -> Result<()> {
+        let actual = notebook_path("vscode_language_id.ipynb");
+        let expected = notebook_path("vscode_language_id_expected.ipynb");
+        let TestedNotebook {
+            messages,
+            source_notebook,
+            ..
+        } = assert_notebook_path(
+            &actual,
+            expected,
+            &settings::LinterSettings::for_rule(Rule::UnusedImport),
+        )?;
+        assert_messages!(messages, actual, source_notebook);
+        Ok(())
+    }
+
    #[test_case(Path::new("before_fix.ipynb"), true; "trailing_newline")]
    #[test_case(Path::new("no_trailing_newline.ipynb"), false; "no_trailing_newline")]
    fn test_trailing_newline(path: &Path, trailing_newline: bool) -> Result<()> {
--- a/crates/ruff_linter/src/rule_redirects.rs
+++ b/crates/ruff_linter/src/rule_redirects.rs
@@ -123,5 +123,7 @@ static REDIRECTS: Lazy<HashMap<&'static str, &'static str>> = Lazy::new(|| {
        ("RUF96", "RUF95"),
        // See: https://github.com/astral-sh/ruff/issues/10791
        ("PLW0117", "PLW0177"),
+        // See: https://github.com/astral-sh/ruff/issues/12110
+        ("RUF025", "C420"),
    ])
 });
--- a/crates/ruff_linter/src/rules/fastapi/rules/fastapi_redundant_response_model.rs
+++ b/crates/ruff_linter/src/rules/fastapi/rules/fastapi_redundant_response_model.rs
@@ -122,17 +122,15 @@ fn is_identical_types(
    return_value: &Expr,
    semantic: &SemanticModel,
 ) -> bool {
-    if let (Some(response_mode_name_expr), Some(return_value_name_expr)) = (
-        response_model_arg.as_name_expr(),
-        return_value.as_name_expr(),
-    ) {
+    if let (Expr::Name(response_mode_name_expr), Expr::Name(return_value_name_expr)) =
+        (response_model_arg, return_value)
+    {
        return semantic.resolve_name(response_mode_name_expr)
            == semantic.resolve_name(return_value_name_expr);
    }
-    if let (Some(response_mode_subscript), Some(return_value_subscript)) = (
-        response_model_arg.as_subscript_expr(),
-        return_value.as_subscript_expr(),
-    ) {
+    if let (Expr::Subscript(response_mode_subscript), Expr::Subscript(return_value_subscript)) =
+        (response_model_arg, return_value)
+    {
        return is_identical_types(
            &response_mode_subscript.value,
            &return_value_subscript.value,
@@ -143,15 +141,13 @@ fn is_identical_types(
            semantic,
        );
    }
-    if let (Some(response_mode_tuple), Some(return_value_tuple)) = (
-        response_model_arg.as_tuple_expr(),
-        return_value.as_tuple_expr(),
-    ) {
-        return response_mode_tuple.elts.len() == return_value_tuple.elts.len()
+    if let (Expr::Tuple(response_mode_tuple), Expr::Tuple(return_value_tuple)) =
+        (response_model_arg, return_value)
+    {
+        return response_mode_tuple.len() == return_value_tuple.len()
            && response_mode_tuple
-                .elts
                .iter()
-                .zip(return_value_tuple.elts.iter())
+                .zip(return_value_tuple)
                .all(|(x, y)| is_identical_types(x, y, semantic));
    }
    false
--- a/crates/ruff_linter/src/rules/flake8_annotations/rules/definition.rs
+++ b/crates/ruff_linter/src/rules/flake8_annotations/rules/definition.rs
@@ -24,15 +24,15 @@ use crate::rules::ruff::typing::type_hint_resolves_to_any;
 /// any provided arguments match expectation.
 ///
 /// ## Example
+///
 /// ```python
-/// def foo(x):
-///     ...
+/// def foo(x): ...
 /// ```
 ///
 /// Use instead:
+///
 /// ```python
-/// def foo(x: int):
-///     ...
+/// def foo(x: int): ...
 /// ```
 #[violation]
 pub struct MissingTypeFunctionArgument {
@@ -56,15 +56,15 @@ impl Violation for MissingTypeFunctionArgument {
 /// any provided arguments match expectation.
 ///
 /// ## Example
+///
 /// ```python
-/// def foo(*args):
-///     ...
+/// def foo(*args): ...
 /// ```
 ///
 /// Use instead:
+///
 /// ```python
-/// def foo(*args: int):
-///     ...
+/// def foo(*args: int): ...
 /// ```
 #[violation]
 pub struct MissingTypeArgs {
@@ -88,15 +88,15 @@ impl Violation for MissingTypeArgs {
 /// any provided arguments match expectation.
 ///
 /// ## Example
+///
 /// ```python
-/// def foo(**kwargs):
-///     ...
+/// def foo(**kwargs): ...
 /// ```
 ///
 /// Use instead:
+///
 /// ```python
-/// def foo(**kwargs: int):
-///     ...
+/// def foo(**kwargs: int): ...
 /// ```
 #[violation]
 pub struct MissingTypeKwargs {
@@ -127,17 +127,17 @@ impl Violation for MissingTypeKwargs {
 /// annotation is not strictly necessary.
 ///
 /// ## Example
+///
 /// ```python
 /// class Foo:
-///     def bar(self):
-///         ...
+///     def bar(self): ...
 /// ```
 ///
 /// Use instead:
+///
 /// ```python
 /// class Foo:
-///     def bar(self: "Foo"):
-///         ...
+///     def bar(self: "Foo"): ...
 /// ```
 #[violation]
 pub struct MissingTypeSelf {
@@ -168,19 +168,19 @@ impl Violation for MissingTypeSelf {
 /// annotation is not strictly necessary.
 ///
 /// ## Example
+///
 /// ```python
 /// class Foo:
 ///     @classmethod
-///     def bar(cls):
-///         ...
+///     def bar(cls): ...
 /// ```
 ///
 /// Use instead:
+///
 /// ```python
 /// class Foo:
 ///     @classmethod
-///     def bar(cls: Type["Foo"]):
-///         ...
+///     def bar(cls: Type["Foo"]): ...
 /// ```
 #[violation]
 pub struct MissingTypeCls {
@@ -449,29 +449,29 @@ impl Violation for MissingReturnTypeClassMethod {
 /// `Any` as an "escape hatch" only when it is really needed.
 ///
 /// ## Example
+///
 /// ```python
-/// def foo(x: Any):
-///     ...
+/// def foo(x: Any): ...
 /// ```
 ///
 /// Use instead:
+///
 /// ```python
-/// def foo(x: int):
-///     ...
+/// def foo(x: int): ...
 /// ```
 ///
 /// ## Known problems
 ///
 /// Type aliases are unsupported and can lead to false positives.
 /// For example, the following will trigger this rule inadvertently:
+///
 /// ```python
 /// from typing import Any
 ///
 /// MyAny = Any
 ///
 ///
-/// def foo(x: MyAny):
-///     ...
+/// def foo(x: MyAny): ...
 /// ```
 ///
 /// ## References
--- a/crates/ruff_linter/src/rules/flake8_async/helpers.rs
+++ b/crates/ruff_linter/src/rules/flake8_async/helpers.rs
@@ -115,44 +115,6 @@ impl MethodName {
                | MethodName::TrioCancelScope
        )
    }
-
-    /// Returns associated module
-    pub(super) fn module(self) -> AsyncModule {
-        match self {
-            MethodName::AsyncIoTimeout | MethodName::AsyncIoTimeoutAt => AsyncModule::AsyncIo,
-            MethodName::AnyIoMoveOnAfter
-            | MethodName::AnyIoFailAfter
-            | MethodName::AnyIoCancelScope => AsyncModule::AnyIo,
-            MethodName::TrioAcloseForcefully
-            | MethodName::TrioCancelScope
-            | MethodName::TrioCancelShieldedCheckpoint
-            | MethodName::TrioCheckpoint
-            | MethodName::TrioCheckpointIfCancelled
-            | MethodName::TrioFailAfter
-            | MethodName::TrioFailAt
-            | MethodName::TrioMoveOnAfter
-            | MethodName::TrioMoveOnAt
-            | MethodName::TrioOpenFile
-            | MethodName::TrioOpenProcess
-            | MethodName::TrioOpenSslOverTcpListeners
-            | MethodName::TrioOpenSslOverTcpStream
-            | MethodName::TrioOpenTcpListeners
-            | MethodName::TrioOpenTcpStream
-            | MethodName::TrioOpenUnixSocket
-            | MethodName::TrioPermanentlyDetachCoroutineObject
-            | MethodName::TrioReattachDetachedCoroutineObject
-            | MethodName::TrioRunProcess
-            | MethodName::TrioServeListeners
-            | MethodName::TrioServeSslOverTcp
-            | MethodName::TrioServeTcp
-            | MethodName::TrioSleep
-            | MethodName::TrioSleepForever
-            | MethodName::TrioTemporarilyDetachCoroutineObject
-            | MethodName::TrioWaitReadable
-            | MethodName::TrioWaitTaskRescheduled
-            | MethodName::TrioWaitWritable => AsyncModule::Trio,
-        }
-    }
 }

 impl MethodName {
--- a/crates/ruff_linter/src/rules/flake8_async/mod.rs
+++ b/crates/ruff_linter/src/rules/flake8_async/mod.rs
@@ -9,11 +9,10 @@ mod tests {
    use anyhow::Result;
    use test_case::test_case;

+    use crate::assert_messages;
    use crate::registry::Rule;
-    use crate::settings::types::PreviewMode;
    use crate::settings::LinterSettings;
    use crate::test::test_path;
-    use crate::{assert_messages, settings};

    #[test_case(Rule::CancelScopeNoCheckpoint, Path::new("ASYNC100.py"))]
    #[test_case(Rule::TrioSyncCall, Path::new("ASYNC105.py"))]
@@ -37,27 +36,4 @@ mod tests {
        assert_messages!(snapshot, diagnostics);
        Ok(())
    }
-
-    #[test_case(Rule::CancelScopeNoCheckpoint, Path::new("ASYNC100.py"))]
-    #[test_case(Rule::AsyncFunctionWithTimeout, Path::new("ASYNC109_0.py"))]
-    #[test_case(Rule::AsyncFunctionWithTimeout, Path::new("ASYNC109_1.py"))]
-    #[test_case(Rule::AsyncBusyWait, Path::new("ASYNC110.py"))]
-    #[test_case(Rule::AsyncZeroSleep, Path::new("ASYNC115.py"))]
-    #[test_case(Rule::LongSleepNotForever, Path::new("ASYNC116.py"))]
-    fn preview_rules(rule_code: Rule, path: &Path) -> Result<()> {
-        let snapshot = format!(
-            "preview__{}_{}",
-            rule_code.noqa_code(),
-            path.to_string_lossy()
-        );
-        let diagnostics = test_path(
-            Path::new("flake8_async").join(path).as_path(),
-            &settings::LinterSettings {
-                preview: PreviewMode::Enabled,
-                ..settings::LinterSettings::for_rule(rule_code)
-            },
-        )?;
-        assert_messages!(snapshot, diagnostics);
-        Ok(())
-    }
 }
--- a/crates/ruff_linter/src/rules/flake8_async/rules/async_busy_wait.rs
+++ b/crates/ruff_linter/src/rules/flake8_async/rules/async_busy_wait.rs
@@ -5,7 +5,6 @@ use ruff_text_size::Ranged;

 use crate::checkers::ast::Checker;
 use crate::rules::flake8_async::helpers::AsyncModule;
-use crate::settings::types::PreviewMode;

 /// ## What it does
 /// Checks for the use of an async sleep function in a `while` loop.
@@ -71,26 +70,15 @@ pub(crate) fn async_busy_wait(checker: &mut Checker, while_stmt: &ast::StmtWhile
        return;
    };

-    if matches!(checker.settings.preview, PreviewMode::Disabled) {
-        if matches!(qualified_name.segments(), ["trio", "sleep" | "sleep_until"]) {
-            checker.diagnostics.push(Diagnostic::new(
-                AsyncBusyWait {
-                    module: AsyncModule::Trio,
-                },
-                while_stmt.range(),
-            ));
-        }
-    } else {
-        if matches!(
-            qualified_name.segments(),
-            ["trio" | "anyio", "sleep" | "sleep_until"] | ["asyncio", "sleep"]
-        ) {
-            checker.diagnostics.push(Diagnostic::new(
-                AsyncBusyWait {
-                    module: AsyncModule::try_from(&qualified_name).unwrap(),
-                },
-                while_stmt.range(),
-            ));
-        }
+    if matches!(
+        qualified_name.segments(),
+        ["trio" | "anyio", "sleep" | "sleep_until"] | ["asyncio", "sleep"]
+    ) {
+        checker.diagnostics.push(Diagnostic::new(
+            AsyncBusyWait {
+                module: AsyncModule::try_from(&qualified_name).unwrap(),
+            },
+            while_stmt.range(),
+        ));
    }
 }
--- a/crates/ruff_linter/src/rules/flake8_async/rules/async_function_with_timeout.rs
+++ b/crates/ruff_linter/src/rules/flake8_async/rules/async_function_with_timeout.rs
@@ -6,7 +6,6 @@ use ruff_text_size::Ranged;

 use crate::checkers::ast::Checker;
 use crate::rules::flake8_async::helpers::AsyncModule;
-use crate::settings::types::PreviewMode;

 /// ## What it does
 /// Checks for `async` functions with a `timeout` argument.
@@ -17,9 +16,9 @@ use crate::settings::types::PreviewMode;
 /// or `anyio.move_on_after`, among others.
 ///
 /// ## Example
+///
 /// ```python
-/// async def long_running_task(timeout):
-///     ...
+/// async def long_running_task(timeout): ...
 ///
 ///
 /// async def main():
@@ -27,9 +26,9 @@ use crate::settings::types::PreviewMode;
 /// ```
 ///
 /// Use instead:
+///
 /// ```python
-/// async def long_running_task():
-///     ...
+/// async def long_running_task(): ...
 ///
 ///
 /// async def main():
@@ -87,17 +86,8 @@ pub(crate) fn async_function_with_timeout(
        AsyncModule::AsyncIo
    };

-    if matches!(checker.settings.preview, PreviewMode::Disabled) {
-        if matches!(module, AsyncModule::Trio) {
-            checker.diagnostics.push(Diagnostic::new(
-                AsyncFunctionWithTimeout { module },
-                timeout.range(),
-            ));
-        }
-    } else {
-        checker.diagnostics.push(Diagnostic::new(
-            AsyncFunctionWithTimeout { module },
-            timeout.range(),
-        ));
-    }
+    checker.diagnostics.push(Diagnostic::new(
+        AsyncFunctionWithTimeout { module },
+        timeout.range(),
+    ));
 }
--- a/crates/ruff_linter/src/rules/flake8_async/rules/async_zero_sleep.rs
+++ b/crates/ruff_linter/src/rules/flake8_async/rules/async_zero_sleep.rs
@@ -83,11 +83,7 @@ pub(crate) fn async_zero_sleep(checker: &mut Checker, call: &ExprCall) {
    };

    if let Some(module) = AsyncModule::try_from(&qualified_name) {
-        let is_relevant_module = if checker.settings.preview.is_enabled() {
-            matches!(module, AsyncModule::Trio | AsyncModule::AnyIo)
-        } else {
-            matches!(module, AsyncModule::Trio)
-        };
+        let is_relevant_module = matches!(module, AsyncModule::Trio | AsyncModule::AnyIo);

        let is_sleep = is_relevant_module && matches!(qualified_name.segments(), [_, "sleep"]);

--- a/crates/ruff_linter/src/rules/flake8_async/rules/cancel_scope_no_checkpoint.rs
+++ b/crates/ruff_linter/src/rules/flake8_async/rules/cancel_scope_no_checkpoint.rs
@@ -5,8 +5,7 @@ use ruff_python_ast::visitor::Visitor;
 use ruff_python_ast::{StmtWith, WithItem};

 use crate::checkers::ast::Checker;
-use crate::rules::flake8_async::helpers::{AsyncModule, MethodName};
-use crate::settings::types::PreviewMode;
+use crate::rules::flake8_async::helpers::MethodName;

 /// ## What it does
 /// Checks for timeout context managers which do not contain a checkpoint.
@@ -88,17 +87,8 @@ pub(crate) fn cancel_scope_no_checkpoint(
        return;
    }

-    if matches!(checker.settings.preview, PreviewMode::Disabled) {
-        if matches!(method_name.module(), AsyncModule::Trio) {
-            checker.diagnostics.push(Diagnostic::new(
-                CancelScopeNoCheckpoint { method_name },
-                with_stmt.range,
-            ));
-        }
-    } else {
-        checker.diagnostics.push(Diagnostic::new(
-            CancelScopeNoCheckpoint { method_name },
-            with_stmt.range,
-        ));
-    }
+    checker.diagnostics.push(Diagnostic::new(
+        CancelScopeNoCheckpoint { method_name },
+        with_stmt.range,
+    ));
 }
--- a/crates/ruff_linter/src/rules/flake8_async/rules/long_sleep_not_forever.rs
+++ b/crates/ruff_linter/src/rules/flake8_async/rules/long_sleep_not_forever.rs
@@ -107,11 +107,7 @@ pub(crate) fn long_sleep_not_forever(checker: &mut Checker, call: &ExprCall) {
        return;
    };

-    let is_relevant_module = if checker.settings.preview.is_enabled() {
-        matches!(module, AsyncModule::AnyIo | AsyncModule::Trio)
-    } else {
-        matches!(module, AsyncModule::Trio)
-    };
+    let is_relevant_module = matches!(module, AsyncModule::AnyIo | AsyncModule::Trio);

    let is_sleep = is_relevant_module && matches!(qualified_name.segments(), [_, "sleep"]);

--- a/crates/ruff_linter/src/rules/flake8_async/snapshots/ruff_linterrulesflake8_asynctestsASYNC100_ASYNC100.py.snap
+++ b/crates/ruff_linter/src/rules/flake8_async/snapshots/ruff_linterrulesflake8_asynctestsASYNC100_ASYNC100.py.snap
@@ -18,3 +18,84 @@ ASYNC100.py:18:5: ASYNC100 A `with trio.move_on_after(...):` context does not co
 19 | |         ...
   | |___________^ ASYNC100
   |
+
+ASYNC100.py:40:5: ASYNC100 A `with anyio.move_on_after(...):` context does not contain any `await` statements. This makes it pointless, as the timeout can only be triggered by a checkpoint.
+   |
+39 |   async def func():
+40 |       with anyio.move_on_after(delay=0.2):
+   |  _____^
+41 | |         ...
+   | |___________^ ASYNC100
+   |
+
+ASYNC100.py:45:5: ASYNC100 A `with anyio.fail_after(...):` context does not contain any `await` statements. This makes it pointless, as the timeout can only be triggered by a checkpoint.
+   |
+44 |   async def func():
+45 |       with anyio.fail_after():
+   |  _____^
+46 | |         ...
+   | |___________^ ASYNC100
+   |
+
+ASYNC100.py:50:5: ASYNC100 A `with anyio.CancelScope(...):` context does not contain any `await` statements. This makes it pointless, as the timeout can only be triggered by a checkpoint.
+   |
+49 |   async def func():
+50 |       with anyio.CancelScope():
+   |  _____^
+51 | |         ...
+   | |___________^ ASYNC100
+   |
+
+ASYNC100.py:55:5: ASYNC100 A `with anyio.CancelScope(...):` context does not contain any `await` statements. This makes it pointless, as the timeout can only be triggered by a checkpoint.
+   |
+54 |   async def func():
+55 |       with anyio.CancelScope(), nullcontext():
+   |  _____^
+56 | |         ...
+   | |___________^ ASYNC100
+   |
+
+ASYNC100.py:60:5: ASYNC100 A `with anyio.CancelScope(...):` context does not contain any `await` statements. This makes it pointless, as the timeout can only be triggered by a checkpoint.
+   |
+59 |   async def func():
+60 |       with nullcontext(), anyio.CancelScope():
+   |  _____^
+61 | |         ...
+   | |___________^ ASYNC100
+   |
+
+ASYNC100.py:65:5: ASYNC100 A `with asyncio.timeout(...):` context does not contain any `await` statements. This makes it pointless, as the timeout can only be triggered by a checkpoint.
+   |
+64 |   async def func():
+65 |       async with asyncio.timeout(delay=0.2):
+   |  _____^
+66 | |         ...
+   | |___________^ ASYNC100
+   |
+
+ASYNC100.py:70:5: ASYNC100 A `with asyncio.timeout_at(...):` context does not contain any `await` statements. This makes it pointless, as the timeout can only be triggered by a checkpoint.
+   |
+69 |   async def func():
+70 |       async with asyncio.timeout_at(when=0.2):
+   |  _____^
+71 | |         ...
+   | |___________^ ASYNC100
+   |
+
+ASYNC100.py:80:5: ASYNC100 A `with asyncio.timeout(...):` context does not contain any `await` statements. This makes it pointless, as the timeout can only be triggered by a checkpoint.
+   |
+79 |   async def func():
+80 |       async with asyncio.timeout(delay=0.2), asyncio.TaskGroup(), asyncio.timeout(delay=0.2):
+   |  _____^
+81 | |         ...
+   | |___________^ ASYNC100
+   |
+
+ASYNC100.py:90:5: ASYNC100 A `with asyncio.timeout(...):` context does not contain any `await` statements. This makes it pointless, as the timeout can only be triggered by a checkpoint.
+   |
+89 |   async def func():
+90 |       async with asyncio.timeout(delay=0.2), asyncio.timeout(delay=0.2):
+   |  _____^
+91 | |         ...
+   | |___________^ ASYNC100
+   |
--- a/crates/ruff_linter/src/rules/flake8_async/snapshots/ruff_linterrulesflake8_asynctestsASYNC109_ASYNC109_1.py.snap
+++ b/crates/ruff_linter/src/rules/flake8_async/snapshots/ruff_linterrulesflake8_asynctestsASYNC109_ASYNC109_1.py.snap
@@ -1,4 +1,18 @@
 ---
 source: crates/ruff_linter/src/rules/flake8_async/mod.rs
 ---
+ASYNC109_1.py:5:16: ASYNC109 Async function definition with a `timeout` parameter
+  |
+5 | async def func(timeout):
+  |                ^^^^^^^ ASYNC109
+6 |     ...
+  |
+  = help: Use `asyncio.timeout` instead

+ASYNC109_1.py:9:16: ASYNC109 Async function definition with a `timeout` parameter
+   |
+ 9 | async def func(timeout=10):
+   |                ^^^^^^^^^^ ASYNC109
+10 |     ...
+   |
+   = help: Use `asyncio.timeout` instead
--- a/crates/ruff_linter/src/rules/flake8_async/snapshots/ruff_linterrulesflake8_asynctestsASYNC110_ASYNC110.py.snap
+++ b/crates/ruff_linter/src/rules/flake8_async/snapshots/ruff_linterrulesflake8_asynctestsASYNC110_ASYNC110.py.snap
@@ -18,3 +18,30 @@ ASYNC110.py:12:5: ASYNC110 Use `trio.Event` instead of awaiting `trio.sleep` in
 13 | |         await trio.sleep_until(10)
   | |__________________________________^ ASYNC110
   |
+
+ASYNC110.py:22:5: ASYNC110 Use `asyncio.Event` instead of awaiting `asyncio.sleep` in a `while` loop
+   |
+21 |   async def func():
+22 |       while True:
+   |  _____^
+23 | |         await anyio.sleep(10)
+   | |_____________________________^ ASYNC110
+   |
+
+ASYNC110.py:27:5: ASYNC110 Use `asyncio.Event` instead of awaiting `asyncio.sleep` in a `while` loop
+   |
+26 |   async def func():
+27 |       while True:
+   |  _____^
+28 | |         await anyio.sleep_until(10)
+   | |___________________________________^ ASYNC110
+   |
+
+ASYNC110.py:37:5: ASYNC110 Use `anyio.Event` instead of awaiting `anyio.sleep` in a `while` loop
+   |
+36 |   async def func():
+37 |       while True:
+   |  _____^
+38 | |         await asyncio.sleep(10)
+   | |_______________________________^ ASYNC110
+   |
--- a/crates/ruff_linter/src/rules/flake8_async/snapshots/ruff_linterrulesflake8_asynctestsASYNC115_ASYNC115.py.snap
+++ b/crates/ruff_linter/src/rules/flake8_async/snapshots/ruff_linterrulesflake8_asynctestsASYNC115_ASYNC115.py.snap
@@ -132,3 +132,117 @@ ASYNC115.py:59:11: ASYNC115 [*] Use `trio.lowlevel.checkpoint()` instead of `tri
 60 60 | 
 61 61 | 
 62 62 | def func():
+
+ASYNC115.py:85:11: ASYNC115 [*] Use `asyncio.lowlevel.checkpoint()` instead of `asyncio.sleep(0)`
+   |
+83 |     from anyio import sleep
+84 | 
+85 |     await anyio.sleep(0)  # ASYNC115
+   |           ^^^^^^^^^^^^^^ ASYNC115
+86 |     await anyio.sleep(1)  # OK
+87 |     await anyio.sleep(0, 1)  # OK
+   |
+   = help: Replace with `asyncio.lowlevel.checkpoint()`
+
+ℹ Safe fix
+49 49 | 
+50 50 | 
+51 51 | from trio import Event, sleep
+   52 |+from asyncio import lowlevel
+52 53 | 
+53 54 | 
+54 55 | def func():
+--------------------------------------------------------------------------------
+82 83 |     import anyio
+83 84 |     from anyio import sleep
+84 85 | 
+85    |-    await anyio.sleep(0)  # ASYNC115
+   86 |+    await lowlevel.checkpoint()  # ASYNC115
+86 87 |     await anyio.sleep(1)  # OK
+87 88 |     await anyio.sleep(0, 1)  # OK
+88 89 |     await anyio.sleep(...)  # OK
+
+ASYNC115.py:91:5: ASYNC115 [*] Use `asyncio.lowlevel.checkpoint()` instead of `asyncio.sleep(0)`
+   |
+89 |     await anyio.sleep()  # OK
+90 | 
+91 |     anyio.sleep(0)  # ASYNC115
+   |     ^^^^^^^^^^^^^^ ASYNC115
+92 |     foo = 0
+93 |     anyio.sleep(foo)  # OK
+   |
+   = help: Replace with `asyncio.lowlevel.checkpoint()`
+
+ℹ Safe fix
+49 49 | 
+50 50 | 
+51 51 | from trio import Event, sleep
+   52 |+from asyncio import lowlevel
+52 53 | 
+53 54 | 
+54 55 | def func():
+--------------------------------------------------------------------------------
+88 89 |     await anyio.sleep(...)  # OK
+89 90 |     await anyio.sleep()  # OK
+90 91 | 
+91    |-    anyio.sleep(0)  # ASYNC115
+   92 |+    lowlevel.checkpoint()  # ASYNC115
+92 93 |     foo = 0
+93 94 |     anyio.sleep(foo)  # OK
+94 95 |     anyio.sleep(1)  # OK
+
+ASYNC115.py:97:5: ASYNC115 [*] Use `asyncio.lowlevel.checkpoint()` instead of `asyncio.sleep(0)`
+   |
+95 |     time.sleep(0)  # OK
+96 | 
+97 |     sleep(0)  # ASYNC115
+   |     ^^^^^^^^ ASYNC115
+98 | 
+99 |     bar = "bar"
+   |
+   = help: Replace with `asyncio.lowlevel.checkpoint()`
+
+ℹ Safe fix
+49 49 | 
+50 50 | 
+51 51 | from trio import Event, sleep
+   52 |+from asyncio import lowlevel
+52 53 | 
+53 54 | 
+54 55 | def func():
+--------------------------------------------------------------------------------
+94 95 |     anyio.sleep(1)  # OK
+95 96 |     time.sleep(0)  # OK
+96 97 | 
+97    |-    sleep(0)  # ASYNC115
+   98 |+    lowlevel.checkpoint()  # ASYNC115
+98 99 | 
+99 100 |     bar = "bar"
+100 101 |     anyio.sleep(bar)
+
+ASYNC115.py:128:15: ASYNC115 [*] Use `asyncio.lowlevel.checkpoint()` instead of `asyncio.sleep(0)`
+    |
+126 |     import anyio
+127 | 
+128 |     anyio.run(anyio.sleep(0))  # ASYNC115
+    |               ^^^^^^^^^^^^^^ ASYNC115
+    |
+    = help: Replace with `asyncio.lowlevel.checkpoint()`
+
+ℹ Safe fix
+49  49  | 
+50  50  | 
+51  51  | from trio import Event, sleep
+    52  |+from asyncio import lowlevel
+52  53  | 
+53  54  | 
+54  55  | def func():
+--------------------------------------------------------------------------------
+125 126 | def func():
+126 127 |     import anyio
+127 128 | 
+128     |-    anyio.run(anyio.sleep(0))  # ASYNC115
+    129 |+    anyio.run(lowlevel.checkpoint())  # ASYNC115
+129 130 | 
+130 131 | 
+131 132 | def func():
--- a/crates/ruff_linter/src/rules/flake8_async/snapshots/ruff_linterrulesflake8_asynctestsASYNC116_ASYNC116.py.snap
+++ b/crates/ruff_linter/src/rules/flake8_async/snapshots/ruff_linterrulesflake8_asynctestsASYNC116_ASYNC116.py.snap
@@ -146,3 +146,194 @@ ASYNC116.py:57:11: ASYNC116 [*] `trio.sleep()` with >24 hour interval should usu
 58 59 | 
 59 60 | 
 60 61 | async def import_anyio():
+
+ASYNC116.py:64:11: ASYNC116 [*] `asyncio.sleep()` with >24 hour interval should usually be `asyncio.sleep_forever()`
+   |
+63 |     # These examples are probably not meant to ever wake up:
+64 |     await anyio.sleep(100000)  # error: 116, "async"
+   |           ^^^^^^^^^^^^^^^^^^^ ASYNC116
+65 | 
+66 |     # 'inf literal' overflow trick
+   |
+   = help: Replace with `asyncio.sleep_forever()`
+
+ℹ Unsafe fix
+2  2  | # ASYNCIO_NO_ERROR - no asyncio.sleep_forever, so check intentionally doesn't trigger.
+3  3  | import math
+4  4  | from math import inf
+   5  |+from asyncio import sleep_forever
+5  6  | 
+6  7  | 
+7  8  | async def import_trio():
+--------------------------------------------------------------------------------
+61 62 |     import anyio
+62 63 | 
+63 64 |     # These examples are probably not meant to ever wake up:
+64    |-    await anyio.sleep(100000)  # error: 116, "async"
+   65 |+    await sleep_forever()  # error: 116, "async"
+65 66 | 
+66 67 |     # 'inf literal' overflow trick
+67 68 |     await anyio.sleep(1e999)  # error: 116, "async"
+
+ASYNC116.py:67:11: ASYNC116 [*] `asyncio.sleep()` with >24 hour interval should usually be `asyncio.sleep_forever()`
+   |
+66 |     # 'inf literal' overflow trick
+67 |     await anyio.sleep(1e999)  # error: 116, "async"
+   |           ^^^^^^^^^^^^^^^^^^ ASYNC116
+68 | 
+69 |     await anyio.sleep(86399)
+   |
+   = help: Replace with `asyncio.sleep_forever()`
+
+ℹ Unsafe fix
+2  2  | # ASYNCIO_NO_ERROR - no asyncio.sleep_forever, so check intentionally doesn't trigger.
+3  3  | import math
+4  4  | from math import inf
+   5  |+from asyncio import sleep_forever
+5  6  | 
+6  7  | 
+7  8  | async def import_trio():
+--------------------------------------------------------------------------------
+64 65 |     await anyio.sleep(100000)  # error: 116, "async"
+65 66 | 
+66 67 |     # 'inf literal' overflow trick
+67    |-    await anyio.sleep(1e999)  # error: 116, "async"
+   68 |+    await sleep_forever()  # error: 116, "async"
+68 69 | 
+69 70 |     await anyio.sleep(86399)
+70 71 |     await anyio.sleep(86400)
+
+ASYNC116.py:71:11: ASYNC116 [*] `asyncio.sleep()` with >24 hour interval should usually be `asyncio.sleep_forever()`
+   |
+69 |     await anyio.sleep(86399)
+70 |     await anyio.sleep(86400)
+71 |     await anyio.sleep(86400.01)  # error: 116, "async"
+   |           ^^^^^^^^^^^^^^^^^^^^^ ASYNC116
+72 |     await anyio.sleep(86401)  # error: 116, "async"
+   |
+   = help: Replace with `asyncio.sleep_forever()`
+
+ℹ Unsafe fix
+2  2  | # ASYNCIO_NO_ERROR - no asyncio.sleep_forever, so check intentionally doesn't trigger.
+3  3  | import math
+4  4  | from math import inf
+   5  |+from asyncio import sleep_forever
+5  6  | 
+6  7  | 
+7  8  | async def import_trio():
+--------------------------------------------------------------------------------
+68 69 | 
+69 70 |     await anyio.sleep(86399)
+70 71 |     await anyio.sleep(86400)
+71    |-    await anyio.sleep(86400.01)  # error: 116, "async"
+   72 |+    await sleep_forever()  # error: 116, "async"
+72 73 |     await anyio.sleep(86401)  # error: 116, "async"
+73 74 | 
+74 75 |     await anyio.sleep(-1)  # will raise a runtime error
+
+ASYNC116.py:72:11: ASYNC116 [*] `asyncio.sleep()` with >24 hour interval should usually be `asyncio.sleep_forever()`
+   |
+70 |     await anyio.sleep(86400)
+71 |     await anyio.sleep(86400.01)  # error: 116, "async"
+72 |     await anyio.sleep(86401)  # error: 116, "async"
+   |           ^^^^^^^^^^^^^^^^^^ ASYNC116
+73 | 
+74 |     await anyio.sleep(-1)  # will raise a runtime error
+   |
+   = help: Replace with `asyncio.sleep_forever()`
+
+ℹ Unsafe fix
+2  2  | # ASYNCIO_NO_ERROR - no asyncio.sleep_forever, so check intentionally doesn't trigger.
+3  3  | import math
+4  4  | from math import inf
+   5  |+from asyncio import sleep_forever
+5  6  | 
+6  7  | 
+7  8  | async def import_trio():
+--------------------------------------------------------------------------------
+69 70 |     await anyio.sleep(86399)
+70 71 |     await anyio.sleep(86400)
+71 72 |     await anyio.sleep(86400.01)  # error: 116, "async"
+72    |-    await anyio.sleep(86401)  # error: 116, "async"
+   73 |+    await sleep_forever()  # error: 116, "async"
+73 74 | 
+74 75 |     await anyio.sleep(-1)  # will raise a runtime error
+75 76 |     await anyio.sleep(0)  # handled by different check
+
+ASYNC116.py:101:5: ASYNC116 [*] `asyncio.sleep()` with >24 hour interval should usually be `asyncio.sleep_forever()`
+    |
+100 |     # does not require the call to be awaited, nor in an async fun
+101 |     anyio.sleep(86401)  # error: 116, "async"
+    |     ^^^^^^^^^^^^^^^^^^ ASYNC116
+102 |     # also checks that we don't break visit_Call
+103 |     anyio.run(anyio.sleep(86401))  # error: 116, "async"
+    |
+    = help: Replace with `asyncio.sleep_forever()`
+
+ℹ Unsafe fix
+2   2   | # ASYNCIO_NO_ERROR - no asyncio.sleep_forever, so check intentionally doesn't trigger.
+3   3   | import math
+4   4   | from math import inf
+    5   |+from asyncio import sleep_forever
+5   6   | 
+6   7   | 
+7   8   | async def import_trio():
+--------------------------------------------------------------------------------
+98  99  |     import anyio
+99  100 | 
+100 101 |     # does not require the call to be awaited, nor in an async fun
+101     |-    anyio.sleep(86401)  # error: 116, "async"
+    102 |+    sleep_forever()  # error: 116, "async"
+102 103 |     # also checks that we don't break visit_Call
+103 104 |     anyio.run(anyio.sleep(86401))  # error: 116, "async"
+104 105 | 
+
+ASYNC116.py:103:15: ASYNC116 [*] `asyncio.sleep()` with >24 hour interval should usually be `asyncio.sleep_forever()`
+    |
+101 |     anyio.sleep(86401)  # error: 116, "async"
+102 |     # also checks that we don't break visit_Call
+103 |     anyio.run(anyio.sleep(86401))  # error: 116, "async"
+    |               ^^^^^^^^^^^^^^^^^^ ASYNC116
+    |
+    = help: Replace with `asyncio.sleep_forever()`
+
+ℹ Unsafe fix
+2   2   | # ASYNCIO_NO_ERROR - no asyncio.sleep_forever, so check intentionally doesn't trigger.
+3   3   | import math
+4   4   | from math import inf
+    5   |+from asyncio import sleep_forever
+5   6   | 
+6   7   | 
+7   8   | async def import_trio():
+--------------------------------------------------------------------------------
+100 101 |     # does not require the call to be awaited, nor in an async fun
+101 102 |     anyio.sleep(86401)  # error: 116, "async"
+102 103 |     # also checks that we don't break visit_Call
+103     |-    anyio.run(anyio.sleep(86401))  # error: 116, "async"
+    104 |+    anyio.run(sleep_forever())  # error: 116, "async"
+104 105 | 
+105 106 | 
+106 107 | async def import_from_anyio():
+
+ASYNC116.py:110:11: ASYNC116 [*] `asyncio.sleep()` with >24 hour interval should usually be `asyncio.sleep_forever()`
+    |
+109 |     # catch from import
+110 |     await sleep(86401)  # error: 116, "async"
+    |           ^^^^^^^^^^^^ ASYNC116
+    |
+    = help: Replace with `asyncio.sleep_forever()`
+
+ℹ Unsafe fix
+2   2   | # ASYNCIO_NO_ERROR - no asyncio.sleep_forever, so check intentionally doesn't trigger.
+3   3   | import math
+4   4   | from math import inf
+    5   |+from asyncio import sleep_forever
+5   6   | 
+6   7   | 
+7   8   | async def import_trio():
+--------------------------------------------------------------------------------
+107 108 |     from anyio import sleep
+108 109 | 
+109 110 |     # catch from import
+110     |-    await sleep(86401)  # error: 116, "async"
+    111 |+    await sleep_forever()  # error: 116, "async"
--- a/crates/ruff_linter/src/rules/flake8_async/snapshots/ruff_linterrulesflake8_asynctestspreview__ASYNC100_ASYNC100.py.snap
+++ b/crates/ruff_linter/src/rules/flake8_async/snapshots/ruff_linterrulesflake8_asynctestspreview__ASYNC100_ASYNC100.py.snap
@@ -1,101 +0,0 @@
---
-source: crates/ruff_linter/src/rules/flake8_async/mod.rs
---
-ASYNC100.py:8:5: ASYNC100 A `with trio.fail_after(...):` context does not contain any `await` statements. This makes it pointless, as the timeout can only be triggered by a checkpoint.
-  |
-7 |   async def func():
-8 |       with trio.fail_after():
-  |  _____^
-9 | |         ...
-  | |___________^ ASYNC100
-  |
-
-ASYNC100.py:18:5: ASYNC100 A `with trio.move_on_after(...):` context does not contain any `await` statements. This makes it pointless, as the timeout can only be triggered by a checkpoint.
-   |
-17 |   async def func():
-18 |       with trio.move_on_after():
-   |  _____^
-19 | |         ...
-   | |___________^ ASYNC100
-   |
-
-ASYNC100.py:40:5: ASYNC100 A `with anyio.move_on_after(...):` context does not contain any `await` statements. This makes it pointless, as the timeout can only be triggered by a checkpoint.
-   |
-39 |   async def func():
-40 |       with anyio.move_on_after(delay=0.2):
-   |  _____^
-41 | |         ...
-   | |___________^ ASYNC100
-   |
-
-ASYNC100.py:45:5: ASYNC100 A `with anyio.fail_after(...):` context does not contain any `await` statements. This makes it pointless, as the timeout can only be triggered by a checkpoint.
-   |
-44 |   async def func():
-45 |       with anyio.fail_after():
-   |  _____^
-46 | |         ...
-   | |___________^ ASYNC100
-   |
-
-ASYNC100.py:50:5: ASYNC100 A `with anyio.CancelScope(...):` context does not contain any `await` statements. This makes it pointless, as the timeout can only be triggered by a checkpoint.
-   |
-49 |   async def func():
-50 |       with anyio.CancelScope():
-   |  _____^
-51 | |         ...
-   | |___________^ ASYNC100
-   |
-
-ASYNC100.py:55:5: ASYNC100 A `with anyio.CancelScope(...):` context does not contain any `await` statements. This makes it pointless, as the timeout can only be triggered by a checkpoint.
-   |
-54 |   async def func():
-55 |       with anyio.CancelScope(), nullcontext():
-   |  _____^
-56 | |         ...
-   | |___________^ ASYNC100
-   |
-
-ASYNC100.py:60:5: ASYNC100 A `with anyio.CancelScope(...):` context does not contain any `await` statements. This makes it pointless, as the timeout can only be triggered by a checkpoint.
-   |
-59 |   async def func():
-60 |       with nullcontext(), anyio.CancelScope():
-   |  _____^
-61 | |         ...
-   | |___________^ ASYNC100
-   |
-
-ASYNC100.py:65:5: ASYNC100 A `with asyncio.timeout(...):` context does not contain any `await` statements. This makes it pointless, as the timeout can only be triggered by a checkpoint.
-   |
-64 |   async def func():
-65 |       async with asyncio.timeout(delay=0.2):
-   |  _____^
-66 | |         ...
-   | |___________^ ASYNC100
-   |
-
-ASYNC100.py:70:5: ASYNC100 A `with asyncio.timeout_at(...):` context does not contain any `await` statements. This makes it pointless, as the timeout can only be triggered by a checkpoint.
-   |
-69 |   async def func():
-70 |       async with asyncio.timeout_at(when=0.2):
-   |  _____^
-71 | |         ...
-   | |___________^ ASYNC100
-   |
-
-ASYNC100.py:80:5: ASYNC100 A `with asyncio.timeout(...):` context does not contain any `await` statements. This makes it pointless, as the timeout can only be triggered by a checkpoint.
-   |
-79 |   async def func():
-80 |       async with asyncio.timeout(delay=0.2), asyncio.TaskGroup(), asyncio.timeout(delay=0.2):
-   |  _____^
-81 | |         ...
-   | |___________^ ASYNC100
-   |
-
-ASYNC100.py:90:5: ASYNC100 A `with asyncio.timeout(...):` context does not contain any `await` statements. This makes it pointless, as the timeout can only be triggered by a checkpoint.
-   |
-89 |   async def func():
-90 |       async with asyncio.timeout(delay=0.2), asyncio.timeout(delay=0.2):
-   |  _____^
-91 | |         ...
-   | |___________^ ASYNC100
-   |
--- a/crates/ruff_linter/src/rules/flake8_async/snapshots/ruff_linterrulesflake8_asynctestspreview__ASYNC109_ASYNC109_0.py.snap
+++ b/crates/ruff_linter/src/rules/flake8_async/snapshots/ruff_linterrulesflake8_asynctestspreview__ASYNC109_ASYNC109_0.py.snap
@@ -1,18 +0,0 @@
---
-source: crates/ruff_linter/src/rules/flake8_async/mod.rs
---
-ASYNC109_0.py:8:16: ASYNC109 Async function definition with a `timeout` parameter
-  |
-8 | async def func(timeout):
-  |                ^^^^^^^ ASYNC109
-9 |     ...
-  |
-  = help: Use `trio.fail_after` instead
-
-ASYNC109_0.py:12:16: ASYNC109 Async function definition with a `timeout` parameter
-   |
-12 | async def func(timeout=10):
-   |                ^^^^^^^^^^ ASYNC109
-13 |     ...
-   |
-   = help: Use `trio.fail_after` instead
--- a/Show More
+++ b/Show More
				`@@ -1 +0,0 @@`
				`Signature: 8a477f597d28d172789f06886806bc55`
				`@@ -1 +0,0 @@`
				`/Users/alexw/.pyenv/versions/3.12.4/bin/python3.12`