WIP: start on passing context to call

Use declared types in inference and checking. This means several things:

* Imports prefer declarations over inference, when declarations are
available.
* When we encounter a binding, we check that the bound value's inferred
type is assignable to the live declarations of the bound symbol, if any.
* When we encounter a declaration, we check that the declared type is
assignable from the inferred type of the symbol from previous bindings,
if any.
* When we encounter a binding+declaration, we check that the inferred
type of the bound value is assignable to the declared type.

.pre-commit-config.yaml

@@ -45,7 +45,7 @@ repos:
           )$
 
   - repo: https://github.com/crate-ci/typos
-    rev: v1.24.3
+    rev: v1.24.5
     hooks:
       - id: typos
 
@@ -59,7 +59,7 @@ repos:
         pass_filenames: false # This makes it a lot faster
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.6.3
+    rev: v0.6.5
     hooks:
       - id: ruff-format
       - id: ruff

CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 0.6.5
+
+### Preview features
+
+- \[`pydoclint`\] Ignore `DOC201` when function name is "**new**" ([#13300](https://github.com/astral-sh/ruff/pull/13300))
+- \[`refurb`\] Implement `slice-to-remove-prefix-or-suffix` (`FURB188`) ([#13256](https://github.com/astral-sh/ruff/pull/13256))
+
+### Rule changes
+
+- \[`eradicate`\] Ignore script-comments with multiple end-tags (`ERA001`) ([#13283](https://github.com/astral-sh/ruff/pull/13283))
+- \[`pyflakes`\] Improve error message for `UndefinedName` when a builtin was added in a newer version than specified in Ruff config (`F821`) ([#13293](https://github.com/astral-sh/ruff/pull/13293))
+
+### Server
+
+- Add support for extensionless Python files for server ([#13326](https://github.com/astral-sh/ruff/pull/13326))
+- Fix configuration inheritance for configurations specified in the LSP settings ([#13285](https://github.com/astral-sh/ruff/pull/13285))
+
+### Bug fixes
+
+- \[`ruff`\] Handle unary operators in `decimal-from-float-literal` (`RUF032`) ([#13275](https://github.com/astral-sh/ruff/pull/13275))
+
+### CLI
+
+- Only include rules with diagnostics in SARIF metadata ([#13268](https://github.com/astral-sh/ruff/pull/13268))
+
+### Playground
+
+- Add "Copy as pyproject.toml/ruff.toml" and "Paste from TOML" ([#13328](https://github.com/astral-sh/ruff/pull/13328))
+- Fix errors not shown for restored snippet on page load ([#13262](https://github.com/astral-sh/ruff/pull/13262))
+
 ## 0.6.4
 
 ### Preview features

Cargo.lock

@@ -194,6 +194,15 @@ version = "2.6.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b048fb63fd8b5923fc5aa7b340d8e156aec7ec02f0c78fa8a6ddc2613f6f71de"
 
+[[package]]
+name = "block-buffer"
+version = "0.10.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71"
+dependencies = [
+ "generic-array",
+]
+
 [[package]]
 name = "bstr"
 version = "1.10.0"
@@ -511,6 +520,15 @@ dependencies = [
  "rustc-hash 1.1.0",
 ]
 
+[[package]]
+name = "cpufeatures"
+version = "0.2.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "51e852e6dc9a5bed1fae92dd2375037bf2b768725bf3be87811edee3249d09ad"
+dependencies = [
+ "libc",
+]
+
 [[package]]
 name = "crc32fast"
 version = "1.4.0"
@@ -616,6 +634,16 @@ version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7a81dae078cea95a014a339291cec439d2f232ebe854a9d672b796c6afafa9b7"
 
+[[package]]
+name = "crypto-common"
+version = "0.1.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1bfb12502f3fc46cca1bb51ac28df9d618d813cdc3d2f25b9fe775a34af26bb3"
+dependencies = [
+ "generic-array",
+ "typenum",
+]
+
 [[package]]
 name = "ctrlc"
 version = "3.4.5"
@@ -694,6 +722,16 @@ version = "0.1.13"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "56254986775e3233ffa9c4d7d3faaf6d36a2c09d30b20687e9f88bc8bafc16c8"
 
+[[package]]
+name = "digest"
+version = "0.10.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
+dependencies = [
+ "block-buffer",
+ "crypto-common",
+]
+
 [[package]]
 name = "dirs"
 version = "4.0.0"
@@ -879,6 +917,16 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "generic-array"
+version = "0.14.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a"
+dependencies = [
+ "typenum",
+ "version_check",
+]
+
 [[package]]
 name = "getopts"
 version = "0.2.21"
@@ -1112,6 +1160,8 @@ dependencies = [
  "globset",
  "lazy_static",
  "linked-hash-map",
+ "pest",
+ "pest_derive",
  "regex",
  "serde",
  "similar",
@@ -1707,6 +1757,51 @@ version = "2.3.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e3148f5046208a5d56bcfc03053e3ca6334e51da8dfb19b6cdc8b306fae3283e"
 
+[[package]]
+name = "pest"
+version = "2.7.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cd53dff83f26735fdc1ca837098ccf133605d794cdae66acfc2bfac3ec809d95"
+dependencies = [
+ "memchr",
+ "thiserror",
+ "ucd-trie",
+]
+
+[[package]]
+name = "pest_derive"
+version = "2.7.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2a548d2beca6773b1c244554d36fcf8548a8a58e74156968211567250e48e49a"
+dependencies = [
+ "pest",
+ "pest_generator",
+]
+
+[[package]]
+name = "pest_generator"
+version = "2.7.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3c93a82e8d145725dcbaf44e5ea887c8a869efdcc28706df2d08c69e17077183"
+dependencies = [
+ "pest",
+ "pest_meta",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "pest_meta"
+version = "2.7.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a941429fea7e08bedec25e4f6785b6ffaacc6b755da98df5ef3e7dcf4a124c4f"
+dependencies = [
+ "once_cell",
+ "pest",
+ "sha2",
+]
+
 [[package]]
 name = "phf"
 version = "0.11.2"
@@ -1936,6 +2031,7 @@ dependencies = [
  "smallvec",
  "static_assertions",
  "tempfile",
+ "test-case",
  "thiserror",
  "tracing",
  "walkdir",
@@ -2091,7 +2187,7 @@ dependencies = [
 
 [[package]]
 name = "ruff"
-version = "0.6.4"
+version = "0.6.5"
 dependencies = [
  "anyhow",
  "argfile",
@@ -2284,7 +2380,7 @@ dependencies = [
 
 [[package]]
 name = "ruff_linter"
-version = "0.6.4"
+version = "0.6.5"
 dependencies = [
  "aho-corasick",
  "annotate-snippets 0.9.2",
@@ -2604,7 +2700,7 @@ dependencies = [
 
 [[package]]
 name = "ruff_wasm"
-version = "0.6.4"
+version = "0.6.5"
 dependencies = [
  "console_error_panic_hook",
  "console_log",
@@ -2935,6 +3031,17 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "sha2"
+version = "0.10.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "793db75ad2bcafc3ffa7c68b215fee268f537982cd901d132f89c6343f3a3dc8"
+dependencies = [
+ "cfg-if",
+ "cpufeatures",
+ "digest",
+]
+
 [[package]]
 name = "sharded-slab"
 version = "0.1.7"
@@ -3335,6 +3442,18 @@ version = "2.0.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6af6ae20167a9ece4bcb41af5b80f8a1f1df981f6391189ce00fd257af04126a"
 
+[[package]]
+name = "typenum"
+version = "1.17.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "42ff0bf0c66b8238c6f3b578df37d0b7848e55df8577b3f74f92a69acceeb825"
+
+[[package]]
+name = "ucd-trie"
+version = "0.1.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed646292ffc8188ef8ea4d1e0e0150fb15a5c2e12ad9b8fc191ae7a8a7f3c4b9"
+
 [[package]]
 name = "unic-char-property"
 version = "0.9.0"

README.md

@@ -136,8 +136,8 @@ curl -LsSf https://astral.sh/ruff/install.sh | sh
 powershell -c "irm https://astral.sh/ruff/install.ps1 | iex"
 
 # For a specific version.
-curl -LsSf https://astral.sh/ruff/0.6.4/install.sh | sh
-powershell -c "irm https://astral.sh/ruff/0.6.4/install.ps1 | iex"
+curl -LsSf https://astral.sh/ruff/0.6.5/install.sh | sh
+powershell -c "irm https://astral.sh/ruff/0.6.5/install.ps1 | iex"
 ```
 
 You can also install Ruff via [Homebrew](https://formulae.brew.sh/formula/ruff), [Conda](https://anaconda.org/conda-forge/ruff),
@@ -170,7 +170,7 @@ Ruff can also be used as a [pre-commit](https://pre-commit.com/) hook via [`ruff
 ```yaml
 - repo: https://github.com/astral-sh/ruff-pre-commit
   # Ruff version.
-  rev: v0.6.4
+  rev: v0.6.5
   hooks:
     # Run the linter.
     - id: ruff

crates/red_knot_python_semantic/Cargo.toml

@@ -33,6 +33,7 @@ rustc-hash = { workspace = true }
 hashbrown = { workspace = true }
 smallvec = { workspace = true }
 static_assertions = { workspace = true }
+test-case = { workspace = true }
 
 [build-dependencies]
 path-slash = { workspace = true }

crates/red_knot_python_semantic/src/lib.rs

@@ -23,4 +23,3 @@ mod stdlib;
 pub mod types;
 
 type FxOrderSet<V> = ordermap::set::OrderSet<V, BuildHasherDefault<FxHasher>>;
-type FxOrderMap<K, V> = ordermap::map::OrderMap<K, V, BuildHasherDefault<FxHasher>>;

crates/red_knot_python_semantic/src/module_resolver/path.rs

@@ -59,6 +59,10 @@ impl ModulePath {
         self.relative_path.push(component);
     }
 
+    pub(crate) fn pop(&mut self) -> bool {
+        self.relative_path.pop()
+    }
+
     #[must_use]
     pub(super) fn is_directory(&self, resolver: &ResolverContext) -> bool {
         let ModulePath {

crates/red_knot_python_semantic/src/module_resolver/resolver.rs

@@ -569,24 +569,16 @@ fn resolve_name(db: &dyn Db, name: &ModuleName) -> Option<(SearchPath, File, Mod
 
                 package_path.push(module_name);
 
-                // Must be a `__init__.pyi` or `__init__.py` or it isn't a package.
-                let kind = if package_path.is_directory(&resolver_state) {
-                    package_path.push("__init__");
-                    ModuleKind::Package
-                } else {
-                    ModuleKind::Module
-                };
-
-                // TODO Implement full https://peps.python.org/pep-0561/#type-checker-module-resolution-order resolution
-                if let Some(stub) = package_path.with_pyi_extension().to_file(&resolver_state) {
-                    return Some((search_path.clone(), stub, kind));
+                // Check for a regular package first (highest priority)
+                package_path.push("__init__");
+                if let Some(regular_package) = resolve_file_module(&package_path, &resolver_state) {
+                    return Some((search_path.clone(), regular_package, ModuleKind::Package));
                 }
 
-                if let Some(module) = package_path
-                    .with_py_extension()
-                    .and_then(|path| path.to_file(&resolver_state))
-                {
-                    return Some((search_path.clone(), module, kind));
+                // Check for a file module next
+                package_path.pop();
+                if let Some(file_module) = resolve_file_module(&package_path, &resolver_state) {
+                    return Some((search_path.clone(), file_module, ModuleKind::Module));
                 }
 
                 // For regular packages, don't search the next search path. All files of that
@@ -607,6 +599,23 @@ fn resolve_name(db: &dyn Db, name: &ModuleName) -> Option<(SearchPath, File, Mod
     None
 }
 
+/// If `module` exists on disk with either a `.pyi` or `.py` extension,
+/// return the [`File`] corresponding to that path.
+///
+/// `.pyi` files take priority, as they always have priority when
+/// resolving modules.
+fn resolve_file_module(module: &ModulePath, resolver_state: &ResolverContext) -> Option<File> {
+    // Stubs have precedence over source files
+    module
+        .with_pyi_extension()
+        .to_file(resolver_state)
+        .or_else(|| {
+            module
+                .with_py_extension()
+                .and_then(|path| path.to_file(resolver_state))
+        })
+}
+
 fn resolve_package<'a, 'db, I>(
     module_search_path: &SearchPath,
     components: I,
@@ -633,7 +642,10 @@ where
 
         if is_regular_package {
             in_namespace_package = false;
-        } else if package_path.is_directory(resolver_state) {
+        } else if package_path.is_directory(resolver_state)
+            // Pure modules hide namespace packages with the same name
+            && resolve_file_module(&package_path, resolver_state).is_none()
+        {
             // A directory without an `__init__.py` is a namespace package, continue with the next folder.
             in_namespace_package = true;
         } else if in_namespace_package {
@@ -1091,6 +1103,25 @@ mod tests {
         );
     }
 
+    #[test]
+    fn single_file_takes_priority_over_namespace_package() {
+        //const SRC: &[FileSpec] = &[("foo.py", "x = 1")];
+        const SRC: &[FileSpec] = &[("foo.py", "x = 1"), ("foo/bar.py", "x = 2")];
+
+        let TestCase { db, src, .. } = TestCaseBuilder::new().with_src_files(SRC).build();
+
+        let foo_module_name = ModuleName::new_static("foo").unwrap();
+        let foo_bar_module_name = ModuleName::new_static("foo.bar").unwrap();
+
+        // `foo.py` takes priority over the `foo` namespace package
+        let foo_module = resolve_module(&db, foo_module_name.clone()).unwrap();
+        assert_eq!(foo_module.file().path(&db), &src.join("foo.py"));
+
+        // `foo.bar` isn't recognised as a module
+        let foo_bar_module = resolve_module(&db, foo_bar_module_name.clone());
+        assert_eq!(foo_bar_module, None);
+    }
+
     #[test]
     fn typing_stub_over_module() {
         const SRC: &[FileSpec] = &[("foo.py", "print('Hello, world!')"), ("foo.pyi", "x: int")];

crates/red_knot_python_semantic/src/semantic_index.rs

@@ -21,12 +21,15 @@ use crate::Db;
 
 pub mod ast_ids;
 mod builder;
+pub(crate) mod constraint;
 pub mod definition;
 pub mod expression;
 pub mod symbol;
 mod use_def;
 
-pub(crate) use self::use_def::{DefinitionWithConstraints, DefinitionWithConstraintsIterator};
+pub(crate) use self::use_def::{
+    BindingWithConstraints, BindingWithConstraintsIterator, DeclarationsIterator,
+};
 
 type SymbolMap = hashbrown::HashMap<ScopedSymbolId, (), ()>;
 
@@ -325,16 +328,16 @@ mod tests {
     use crate::Db;
 
     impl UseDefMap<'_> {
-        fn first_public_definition(&self, symbol: ScopedSymbolId) -> Option<Definition<'_>> {
-            self.public_definitions(symbol)
+        fn first_public_binding(&self, symbol: ScopedSymbolId) -> Option<Definition<'_>> {
+            self.public_bindings(symbol)
                 .next()
-                .map(|constrained_definition| constrained_definition.definition)
+                .map(|constrained_binding| constrained_binding.binding)
         }
 
-        fn first_use_definition(&self, use_id: ScopedUseId) -> Option<Definition<'_>> {
-            self.use_definitions(use_id)
+        fn first_binding_at_use(&self, use_id: ScopedUseId) -> Option<Definition<'_>> {
+            self.bindings_at_use(use_id)
                 .next()
-                .map(|constrained_definition| constrained_definition.definition)
+                .map(|constrained_binding| constrained_binding.binding)
         }
     }
 
@@ -396,8 +399,8 @@ mod tests {
         let foo = global_table.symbol_id_by_name("foo").unwrap();
 
         let use_def = use_def_map(&db, scope);
-        let definition = use_def.first_public_definition(foo).unwrap();
-        assert!(matches!(definition.node(&db), DefinitionKind::Import(_)));
+        let binding = use_def.first_public_binding(foo).unwrap();
+        assert!(matches!(binding.kind(&db), DefinitionKind::Import(_)));
     }
 
     #[test]
@@ -426,22 +429,19 @@ mod tests {
         assert!(
             global_table
                 .symbol_by_name("foo")
-                .is_some_and(|symbol| { symbol.is_defined() && !symbol.is_used() }),
+                .is_some_and(|symbol| { symbol.is_bound() && !symbol.is_used() }),
             "symbols that are defined get the defined flag"
         );
 
         let use_def = use_def_map(&db, scope);
-        let definition = use_def
-            .first_public_definition(
+        let binding = use_def
+            .first_public_binding(
                 global_table
                     .symbol_id_by_name("foo")
                     .expect("symbol to exist"),
             )
             .unwrap();
-        assert!(matches!(
-            definition.node(&db),
-            DefinitionKind::ImportFrom(_)
-        ));
+        assert!(matches!(binding.kind(&db), DefinitionKind::ImportFrom(_)));
     }
 
     #[test]
@@ -454,17 +454,14 @@ mod tests {
         assert!(
             global_table
                 .symbol_by_name("foo")
-                .is_some_and(|symbol| { !symbol.is_defined() && symbol.is_used() }),
-            "a symbol used but not defined in a scope should have only the used flag"
+                .is_some_and(|symbol| { !symbol.is_bound() && symbol.is_used() }),
+            "a symbol used but not bound in a scope should have only the used flag"
         );
         let use_def = use_def_map(&db, scope);
-        let definition = use_def
-            .first_public_definition(global_table.symbol_id_by_name("x").expect("symbol exists"))
+        let binding = use_def
+            .first_public_binding(global_table.symbol_id_by_name("x").expect("symbol exists"))
             .unwrap();
-        assert!(matches!(
-            definition.node(&db),
-            DefinitionKind::Assignment(_)
-        ));
+        assert!(matches!(binding.kind(&db), DefinitionKind::Assignment(_)));
     }
 
     #[test]
@@ -476,12 +473,12 @@ mod tests {
         assert_eq!(names(&global_table), vec!["x"]);
 
         let use_def = use_def_map(&db, scope);
-        let definition = use_def
-            .first_public_definition(global_table.symbol_id_by_name("x").unwrap())
+        let binding = use_def
+            .first_public_binding(global_table.symbol_id_by_name("x").unwrap())
             .unwrap();
 
         assert!(matches!(
-            definition.node(&db),
+            binding.kind(&db),
             DefinitionKind::AugmentedAssignment(_)
         ));
     }
@@ -514,13 +511,10 @@ y = 2
         assert_eq!(names(&class_table), vec!["x"]);
 
         let use_def = index.use_def_map(class_scope_id);
-        let definition = use_def
-            .first_public_definition(class_table.symbol_id_by_name("x").expect("symbol exists"))
+        let binding = use_def
+            .first_public_binding(class_table.symbol_id_by_name("x").expect("symbol exists"))
             .unwrap();
-        assert!(matches!(
-            definition.node(&db),
-            DefinitionKind::Assignment(_)
-        ));
+        assert!(matches!(binding.kind(&db), DefinitionKind::Assignment(_)));
     }
 
     #[test]
@@ -550,17 +544,14 @@ y = 2
         assert_eq!(names(&function_table), vec!["x"]);
 
         let use_def = index.use_def_map(function_scope_id);
-        let definition = use_def
-            .first_public_definition(
+        let binding = use_def
+            .first_public_binding(
                 function_table
                     .symbol_id_by_name("x")
                     .expect("symbol exists"),
             )
             .unwrap();
-        assert!(matches!(
-            definition.node(&db),
-            DefinitionKind::Assignment(_)
-        ));
+        assert!(matches!(binding.kind(&db), DefinitionKind::Assignment(_)));
     }
 
     #[test]
@@ -592,27 +583,27 @@ def f(a: str, /, b: str, c: int = 1, *args, d: int = 2, **kwargs):
 
         let use_def = index.use_def_map(function_scope_id);
         for name in ["a", "b", "c", "d"] {
-            let definition = use_def
-                .first_public_definition(
+            let binding = use_def
+                .first_public_binding(
                     function_table
                         .symbol_id_by_name(name)
                         .expect("symbol exists"),
                 )
                 .unwrap();
             assert!(matches!(
-                definition.node(&db),
+                binding.kind(&db),
                 DefinitionKind::ParameterWithDefault(_)
             ));
         }
         for name in ["args", "kwargs"] {
-            let definition = use_def
-                .first_public_definition(
+            let binding = use_def
+                .first_public_binding(
                     function_table
                         .symbol_id_by_name(name)
                         .expect("symbol exists"),
                 )
                 .unwrap();
-            assert!(matches!(definition.node(&db), DefinitionKind::Parameter(_)));
+            assert!(matches!(binding.kind(&db), DefinitionKind::Parameter(_)));
         }
     }
 
@@ -640,23 +631,19 @@ def f(a: str, /, b: str, c: int = 1, *args, d: int = 2, **kwargs):
 
         let use_def = index.use_def_map(lambda_scope_id);
         for name in ["a", "b", "c", "d"] {
-            let definition = use_def
-                .first_public_definition(
-                    lambda_table.symbol_id_by_name(name).expect("symbol exists"),
-                )
+            let binding = use_def
+                .first_public_binding(lambda_table.symbol_id_by_name(name).expect("symbol exists"))
                 .unwrap();
             assert!(matches!(
-                definition.node(&db),
+                binding.kind(&db),
                 DefinitionKind::ParameterWithDefault(_)
             ));
         }
         for name in ["args", "kwargs"] {
-            let definition = use_def
-                .first_public_definition(
-                    lambda_table.symbol_id_by_name(name).expect("symbol exists"),
-                )
+            let binding = use_def
+                .first_public_binding(lambda_table.symbol_id_by_name(name).expect("symbol exists"))
                 .unwrap();
-            assert!(matches!(definition.node(&db), DefinitionKind::Parameter(_)));
+            assert!(matches!(binding.kind(&db), DefinitionKind::Parameter(_)));
         }
     }
 
@@ -694,15 +681,15 @@ def f(a: str, /, b: str, c: int = 1, *args, d: int = 2, **kwargs):
 
         let use_def = index.use_def_map(comprehension_scope_id);
         for name in ["x", "y"] {
-            let definition = use_def
-                .first_public_definition(
+            let binding = use_def
+                .first_public_binding(
                     comprehension_symbol_table
                         .symbol_id_by_name(name)
                         .expect("symbol exists"),
                 )
                 .unwrap();
             assert!(matches!(
-                definition.node(&db),
+                binding.kind(&db),
                 DefinitionKind::Comprehension(_)
             ));
         }
@@ -741,8 +728,8 @@ def f(a: str, /, b: str, c: int = 1, *args, d: int = 2, **kwargs):
         let element_use_id =
             element.scoped_use_id(&db, comprehension_scope_id.to_scope_id(&db, file));
 
-        let definition = use_def.first_use_definition(element_use_id).unwrap();
-        let DefinitionKind::Comprehension(comprehension) = definition.node(&db) else {
+        let binding = use_def.first_binding_at_use(element_use_id).unwrap();
+        let DefinitionKind::Comprehension(comprehension) = binding.kind(&db) else {
             panic!("expected generator definition")
         };
         let target = comprehension.target();
@@ -821,12 +808,10 @@ with item1 as x, item2 as y:
 
         let use_def = index.use_def_map(FileScopeId::global());
         for name in ["x", "y"] {
-            let Some(definition) = use_def.first_public_definition(
-                global_table.symbol_id_by_name(name).expect("symbol exists"),
-            ) else {
-                panic!("Expected with item definition for {name}");
-            };
-            assert!(matches!(definition.node(&db), DefinitionKind::WithItem(_)));
+            let binding = use_def
+                .first_public_binding(global_table.symbol_id_by_name(name).expect("symbol exists"))
+                .expect("Expected with item definition for {name}");
+            assert!(matches!(binding.kind(&db), DefinitionKind::WithItem(_)));
         }
     }
 
@@ -846,12 +831,10 @@ with context() as (x, y):
 
         let use_def = index.use_def_map(FileScopeId::global());
         for name in ["x", "y"] {
-            let Some(definition) = use_def.first_public_definition(
-                global_table.symbol_id_by_name(name).expect("symbol exists"),
-            ) else {
-                panic!("Expected with item definition for {name}");
-            };
-            assert!(matches!(definition.node(&db), DefinitionKind::WithItem(_)));
+            let binding = use_def
+                .first_public_binding(global_table.symbol_id_by_name(name).expect("symbol exists"))
+                .expect("Expected with item definition for {name}");
+            assert!(matches!(binding.kind(&db), DefinitionKind::WithItem(_)));
         }
     }
 
@@ -888,14 +871,14 @@ def func():
         assert_eq!(names(&func2_table), vec!["y"]);
 
         let use_def = index.use_def_map(FileScopeId::global());
-        let definition = use_def
-            .first_public_definition(
+        let binding = use_def
+            .first_public_binding(
                 global_table
                     .symbol_id_by_name("func")
                     .expect("symbol exists"),
             )
             .unwrap();
-        assert!(matches!(definition.node(&db), DefinitionKind::Function(_)));
+        assert!(matches!(binding.kind(&db), DefinitionKind::Function(_)));
     }
 
     #[test]
@@ -963,7 +946,7 @@ class C[T]:
         assert!(
             ann_table
                 .symbol_by_name("T")
-                .is_some_and(|s| s.is_defined() && !s.is_used()),
+                .is_some_and(|s| s.is_bound() && !s.is_used()),
             "type parameters are defined by the scope that introduces them"
         );
 
@@ -995,8 +978,8 @@ 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.first_use_definition(x_use_id).unwrap();
-        let DefinitionKind::Assignment(assignment) = definition.node(&db) else {
+        let binding = use_def.first_binding_at_use(x_use_id).unwrap();
+        let DefinitionKind::Assignment(assignment) = binding.kind(&db) else {
             panic!("should be an assignment definition")
         };
         let ast::Expr::NumberLiteral(ast::ExprNumberLiteral {
@@ -1126,12 +1109,10 @@ match subject:
             ("k", 0),
             ("l", 1),
         ] {
-            let definition = use_def
-                .first_public_definition(
-                    global_table.symbol_id_by_name(name).expect("symbol exists"),
-                )
+            let binding = use_def
+                .first_public_binding(global_table.symbol_id_by_name(name).expect("symbol exists"))
                 .expect("Expected with item definition for {name}");
-            if let DefinitionKind::MatchPattern(pattern) = definition.node(&db) {
+            if let DefinitionKind::MatchPattern(pattern) = binding.kind(&db) {
                 assert_eq!(pattern.index(), expected_index);
             } else {
                 panic!("Expected match pattern definition for {name}");
@@ -1158,12 +1139,10 @@ match 1:
 
         let use_def = use_def_map(&db, global_scope_id);
         for (name, expected_index) in [("first", 0), ("second", 0)] {
-            let definition = use_def
-                .first_public_definition(
-                    global_table.symbol_id_by_name(name).expect("symbol exists"),
-                )
+            let binding = use_def
+                .first_public_binding(global_table.symbol_id_by_name(name).expect("symbol exists"))
                 .expect("Expected with item definition for {name}");
-            if let DefinitionKind::MatchPattern(pattern) = definition.node(&db) {
+            if let DefinitionKind::MatchPattern(pattern) = binding.kind(&db) {
                 assert_eq!(pattern.index(), expected_index);
             } else {
                 panic!("Expected match pattern definition for {name}");
@@ -1180,11 +1159,11 @@ match 1:
         assert_eq!(&names(&global_table), &["a", "x"]);
 
         let use_def = use_def_map(&db, scope);
-        let definition = use_def
-            .first_public_definition(global_table.symbol_id_by_name("x").unwrap())
+        let binding = use_def
+            .first_public_binding(global_table.symbol_id_by_name("x").unwrap())
             .unwrap();
 
-        assert!(matches!(definition.node(&db), DefinitionKind::For(_)));
+        assert!(matches!(binding.kind(&db), DefinitionKind::For(_)));
     }
 
     #[test]
@@ -1196,15 +1175,15 @@ match 1:
         assert_eq!(&names(&global_table), &["a", "x", "y"]);
 
         let use_def = use_def_map(&db, scope);
-        let x_definition = use_def
-            .first_public_definition(global_table.symbol_id_by_name("x").unwrap())
+        let x_binding = use_def
+            .first_public_binding(global_table.symbol_id_by_name("x").unwrap())
             .unwrap();
-        let y_definition = use_def
-            .first_public_definition(global_table.symbol_id_by_name("y").unwrap())
+        let y_binding = use_def
+            .first_public_binding(global_table.symbol_id_by_name("y").unwrap())
             .unwrap();
 
-        assert!(matches!(x_definition.node(&db), DefinitionKind::For(_)));
-        assert!(matches!(y_definition.node(&db), DefinitionKind::For(_)));
+        assert!(matches!(x_binding.kind(&db), DefinitionKind::For(_)));
+        assert!(matches!(y_binding.kind(&db), DefinitionKind::For(_)));
     }
 
     #[test]
@@ -1216,10 +1195,10 @@ match 1:
         assert_eq!(&names(&global_table), &["e", "a", "b", "c", "d"]);
 
         let use_def = use_def_map(&db, scope);
-        let definition = use_def
-            .first_public_definition(global_table.symbol_id_by_name("a").unwrap())
+        let binding = use_def
+            .first_public_binding(global_table.symbol_id_by_name("a").unwrap())
             .unwrap();
 
-        assert!(matches!(definition.node(&db), DefinitionKind::For(_)));
+        assert!(matches!(binding.kind(&db), DefinitionKind::For(_)));
     }
 }

crates/red_knot_python_semantic/src/semantic_index/builder.rs

@@ -19,14 +19,18 @@ use crate::semantic_index::definition::{
 };
 use crate::semantic_index::expression::Expression;
 use crate::semantic_index::symbol::{
-    FileScopeId, NodeWithScopeKey, NodeWithScopeRef, Scope, ScopeId, ScopedSymbolId, SymbolFlags,
+    FileScopeId, NodeWithScopeKey, NodeWithScopeRef, Scope, ScopeId, ScopedSymbolId,
     SymbolTableBuilder,
 };
 use crate::semantic_index::use_def::{FlowSnapshot, UseDefMapBuilder};
 use crate::semantic_index::SemanticIndex;
 use crate::Db;
 
-use super::definition::{MatchPatternDefinitionNodeRef, WithItemDefinitionNodeRef};
+use super::constraint::{Constraint, PatternConstraint};
+use super::definition::{
+    DefinitionCategory, ExceptHandlerDefinitionNodeRef, MatchPatternDefinitionNodeRef,
+    WithItemDefinitionNodeRef,
+};
 
 pub(super) struct SemanticIndexBuilder<'db> {
     // Builder state
@@ -165,31 +169,38 @@ impl<'db> SemanticIndexBuilder<'db> {
         self.current_use_def_map_mut().merge(state);
     }
 
-    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);
+    fn add_symbol(&mut self, name: Name) -> ScopedSymbolId {
+        let (symbol_id, added) = self.current_symbol_table().add_symbol(name);
         if added {
-            let use_def_map = self.current_use_def_map_mut();
-            use_def_map.add_symbol(symbol_id);
+            self.current_use_def_map_mut().add_symbol(symbol_id);
         }
         symbol_id
     }
 
+    fn mark_symbol_bound(&mut self, id: ScopedSymbolId) {
+        self.current_symbol_table().mark_symbol_bound(id);
+    }
+
+    fn mark_symbol_used(&mut self, id: ScopedSymbolId) {
+        self.current_symbol_table().mark_symbol_used(id);
+    }
+
     fn add_definition<'a>(
         &mut self,
         symbol: ScopedSymbolId,
         definition_node: impl Into<DefinitionNodeRef<'a>>,
     ) -> Definition<'db> {
         let definition_node: DefinitionNodeRef<'_> = definition_node.into();
+        #[allow(unsafe_code)]
+        // SAFETY: `definition_node` is guaranteed to be a child of `self.module`
+        let kind = unsafe { definition_node.into_owned(self.module.clone()) };
+        let category = kind.category();
         let definition = Definition::new(
             self.db,
             self.file,
             self.current_scope(),
             symbol,
-            #[allow(unsafe_code)]
-            unsafe {
-                definition_node.into_owned(self.module.clone())
-            },
+            kind,
             countme::Count::default(),
         );
 
@@ -198,19 +209,55 @@ impl<'db> SemanticIndexBuilder<'db> {
             .insert(definition_node.key(), definition);
         debug_assert_eq!(existing_definition, None);
 
-        self.current_use_def_map_mut()
-            .record_definition(symbol, definition);
+        if category.is_binding() {
+            self.mark_symbol_bound(symbol);
+        }
+
+        let use_def = self.current_use_def_map_mut();
+        match category {
+            DefinitionCategory::DeclarationAndBinding => {
+                use_def.record_declaration_and_binding(symbol, definition);
+            }
+            DefinitionCategory::Declaration => use_def.record_declaration(symbol, definition),
+            DefinitionCategory::Binding => use_def.record_binding(symbol, definition),
+        }
 
         definition
     }
 
-    fn add_constraint(&mut self, constraint_node: &ast::Expr) -> Expression<'db> {
+    fn add_expression_constraint(&mut self, constraint_node: &ast::Expr) -> Expression<'db> {
         let expression = self.add_standalone_expression(constraint_node);
-        self.current_use_def_map_mut().record_constraint(expression);
+        self.current_use_def_map_mut()
+            .record_constraint(Constraint::Expression(expression));
 
         expression
     }
 
+    fn add_pattern_constraint(
+        &mut self,
+        subject: &ast::Expr,
+        pattern: &ast::Pattern,
+    ) -> PatternConstraint<'db> {
+        #[allow(unsafe_code)]
+        let (subject, pattern) = unsafe {
+            (
+                AstNodeRef::new(self.module.clone(), subject),
+                AstNodeRef::new(self.module.clone(), pattern),
+            )
+        };
+        let pattern_constraint = PatternConstraint::new(
+            self.db,
+            self.file,
+            self.current_scope(),
+            subject,
+            pattern,
+            countme::Count::default(),
+        );
+        self.current_use_def_map_mut()
+            .record_constraint(Constraint::Pattern(pattern_constraint));
+        pattern_constraint
+    }
+
     /// Record an expression that needs to be a Salsa ingredient, because we need to infer its type
     /// standalone (type narrowing tests, RHS of an assignment.)
     fn add_standalone_expression(&mut self, expression_node: &ast::Expr) -> Expression<'db> {
@@ -255,10 +302,13 @@ impl<'db> SemanticIndexBuilder<'db> {
                         ..
                     }) => (name, &None, default),
                 };
-                // TODO create Definition for typevars
-                self.add_or_update_symbol(name.id.clone(), SymbolFlags::IS_DEFINED);
-                if let Some(bound) = bound {
-                    self.visit_expr(bound);
+                let symbol = self.add_symbol(name.id.clone());
+                // TODO create Definition for PEP 695 typevars
+                // note that the "bound" on the typevar is a totally different thing than whether
+                // or not a name is "bound" by a typevar declaration; the latter is always true.
+                self.mark_symbol_bound(symbol);
+                if let Some(bounds) = bound {
+                    self.visit_expr(bounds);
                 }
                 if let Some(default) = default {
                     self.visit_expr(default);
@@ -275,11 +325,23 @@ 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`.)
+    /// This method does several things:
+    /// - It pushes a new scope onto the stack for visiting
+    ///   a list/dict/set comprehension or generator expression
+    /// - Inside that scope, it visits 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`).
+    /// - Inside that scope, it also calls a closure for visiting the outer `elt`
+    ///   of a list/dict/set comprehension or generator expression
+    /// - It then pops the new scope off the stack
     ///
     /// [`Comprehension`]: ast::Comprehension
-    fn visit_generators(&mut self, scope: NodeWithScopeRef, generators: &'db [ast::Comprehension]) {
+    fn with_generators_scope(
+        &mut self,
+        scope: NodeWithScopeRef,
+        generators: &'db [ast::Comprehension],
+        visit_outer_elt: impl FnOnce(&mut Self),
+    ) {
         let mut generators_iter = generators.iter();
 
         let Some(generator) = generators_iter.next() else {
@@ -318,11 +380,13 @@ impl<'db> SemanticIndexBuilder<'db> {
                 self.visit_expr(expr);
             }
         }
+
+        visit_outer_elt(self);
+        self.pop_scope();
     }
 
     fn declare_parameter(&mut self, parameter: AnyParameterRef) {
-        let symbol =
-            self.add_or_update_symbol(parameter.name().id().clone(), SymbolFlags::IS_DEFINED);
+        let symbol = self.add_symbol(parameter.name().id().clone());
 
         let definition = self.add_definition(symbol, parameter);
 
@@ -433,8 +497,7 @@ where
                 // The symbol for the function name itself has to be evaluated
                 // at the end to match the runtime evaluation of parameter defaults
                 // and return-type annotations.
-                let symbol = self
-                    .add_or_update_symbol(function_def.name.id.clone(), SymbolFlags::IS_DEFINED);
+                let symbol = self.add_symbol(function_def.name.id.clone());
                 self.add_definition(symbol, function_def);
             }
             ast::Stmt::ClassDef(class) => {
@@ -442,8 +505,7 @@ where
                     self.visit_decorator(decorator);
                 }
 
-                let symbol =
-                    self.add_or_update_symbol(class.name.id.clone(), SymbolFlags::IS_DEFINED);
+                let symbol = self.add_symbol(class.name.id.clone());
                 self.add_definition(symbol, class);
 
                 self.with_type_params(
@@ -469,7 +531,7 @@ where
                         Name::new(alias.name.id.split('.').next().unwrap())
                     };
 
-                    let symbol = self.add_or_update_symbol(symbol_name, SymbolFlags::IS_DEFINED);
+                    let symbol = self.add_symbol(symbol_name);
                     self.add_definition(symbol, alias);
                 }
             }
@@ -481,8 +543,7 @@ where
                         &alias.name.id
                     };
 
-                    let symbol =
-                        self.add_or_update_symbol(symbol_name.clone(), SymbolFlags::IS_DEFINED);
+                    let symbol = self.add_symbol(symbol_name.clone());
                     self.add_definition(symbol, ImportFromDefinitionNodeRef { node, alias_index });
                 }
             }
@@ -498,7 +559,6 @@ where
             }
             ast::Stmt::AnnAssign(node) => {
                 debug_assert!(self.current_assignment.is_none());
-                // TODO deferred annotation visiting
                 self.visit_expr(&node.annotation);
                 if let Some(value) = &node.value {
                     self.visit_expr(value);
@@ -524,7 +584,7 @@ where
             ast::Stmt::If(node) => {
                 self.visit_expr(&node.test);
                 let pre_if = self.flow_snapshot();
-                self.add_constraint(&node.test);
+                self.add_expression_constraint(&node.test);
                 self.visit_body(&node.body);
                 let mut post_clauses: Vec<FlowSnapshot> = vec![];
                 for clause in &node.elif_else_clauses {
@@ -549,14 +609,23 @@ where
                     self.flow_merge(pre_if);
                 }
             }
-            ast::Stmt::While(node) => {
-                self.visit_expr(&node.test);
+            ast::Stmt::While(ast::StmtWhile {
+                test,
+                body,
+                orelse,
+                range: _,
+            }) => {
+                self.visit_expr(test);
 
                 let pre_loop = self.flow_snapshot();
 
                 // Save aside any break states from an outer loop
                 let saved_break_states = std::mem::take(&mut self.loop_break_states);
-                self.visit_body(&node.body);
+
+                // TODO: definitions created inside the body should be fully visible
+                // to other statements/expressions inside the body --Alex/Carl
+                self.visit_body(body);
+
                 // Get the break states from the body of this loop, and restore the saved outer
                 // ones.
                 let break_states =
@@ -565,7 +634,7 @@ where
                 // 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.visit_body(&node.orelse);
+                self.visit_body(orelse);
 
                 // Breaking out of a while loop bypasses the `else` clause, so merge in the break
                 // states after visiting `else`.
@@ -599,15 +668,35 @@ where
                     orelse,
                 },
             ) => {
-                // TODO add control flow similar to `ast::Stmt::While` above
                 self.add_standalone_expression(iter);
                 self.visit_expr(iter);
+
+                let pre_loop = self.flow_snapshot();
+                let saved_break_states = std::mem::take(&mut self.loop_break_states);
+
                 debug_assert!(self.current_assignment.is_none());
                 self.current_assignment = Some(for_stmt.into());
                 self.visit_expr(target);
                 self.current_assignment = None;
+
+                // TODO: Definitions created by loop variables
+                // (and definitions created inside the body)
+                // are fully visible to other statements/expressions inside the body --Alex/Carl
                 self.visit_body(body);
+
+                let break_states =
+                    std::mem::replace(&mut self.loop_break_states, 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.visit_body(orelse);
+
+                // Breaking out of a `for` 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);
+                }
             }
             ast::Stmt::Match(ast::StmtMatch {
                 subject,
@@ -616,9 +705,74 @@ where
             }) => {
                 self.add_standalone_expression(subject);
                 self.visit_expr(subject);
-                for case in cases {
+
+                let after_subject = self.flow_snapshot();
+                let Some((first, remaining)) = cases.split_first() else {
+                    return;
+                };
+                self.add_pattern_constraint(subject, &first.pattern);
+                self.visit_match_case(first);
+
+                let mut post_case_snapshots = vec![];
+                for case in remaining {
+                    post_case_snapshots.push(self.flow_snapshot());
+                    self.flow_restore(after_subject.clone());
+                    self.add_pattern_constraint(subject, &case.pattern);
                     self.visit_match_case(case);
                 }
+                for post_clause_state in post_case_snapshots {
+                    self.flow_merge(post_clause_state);
+                }
+                if !cases
+                    .last()
+                    .is_some_and(|case| case.guard.is_none() && case.pattern.is_wildcard())
+                {
+                    self.flow_merge(after_subject);
+                }
+            }
+            ast::Stmt::Try(ast::StmtTry {
+                body,
+                handlers,
+                orelse,
+                finalbody,
+                is_star,
+                range: _,
+            }) => {
+                self.visit_body(body);
+
+                for except_handler in handlers {
+                    let ast::ExceptHandler::ExceptHandler(except_handler) = except_handler;
+                    let ast::ExceptHandlerExceptHandler {
+                        name: symbol_name,
+                        type_: handled_exceptions,
+                        body: handler_body,
+                        range: _,
+                    } = except_handler;
+
+                    if let Some(handled_exceptions) = handled_exceptions {
+                        self.visit_expr(handled_exceptions);
+                    }
+
+                    // If `handled_exceptions` above was `None`, it's something like `except as e:`,
+                    // which is invalid syntax. However, it's still pretty obvious here that the user
+                    // *wanted* `e` to be bound, so we should still create a definition here nonetheless.
+                    if let Some(symbol_name) = symbol_name {
+                        let symbol = self.add_symbol(symbol_name.id.clone());
+
+                        self.add_definition(
+                            symbol,
+                            DefinitionNodeRef::ExceptHandler(ExceptHandlerDefinitionNodeRef {
+                                handler: except_handler,
+                                is_star: *is_star,
+                            }),
+                        );
+                    }
+
+                    self.visit_body(handler_body);
+                }
+
+                self.visit_body(orelse);
+                self.visit_body(finalbody);
             }
             _ => {
                 walk_stmt(self, stmt);
@@ -633,23 +787,18 @@ where
 
         match expr {
             ast::Expr::Name(name_node @ ast::ExprName { id, ctx, .. }) => {
-                let mut flags = match ctx {
-                    ast::ExprContext::Load => SymbolFlags::IS_USED,
-                    ast::ExprContext::Store => SymbolFlags::IS_DEFINED,
-                    ast::ExprContext::Del => SymbolFlags::IS_DEFINED,
-                    ast::ExprContext::Invalid => SymbolFlags::empty(),
+                let (is_use, is_definition) = match (ctx, self.current_assignment) {
+                    (ast::ExprContext::Store, Some(CurrentAssignment::AugAssign(_))) => {
+                        // For augmented assignment, the target expression is also used.
+                        (true, true)
+                    }
+                    (ast::ExprContext::Load, _) => (true, false),
+                    (ast::ExprContext::Store, _) => (false, true),
+                    (ast::ExprContext::Del, _) => (false, true),
+                    (ast::ExprContext::Invalid, _) => (false, false),
                 };
-                if matches!(
-                    self.current_assignment,
-                    Some(CurrentAssignment::AugAssign(_))
-                ) && !ctx.is_invalid()
-                {
-                    // For augmented assignment, the target expression is also used, so we should
-                    // record that as a use.
-                    flags |= SymbolFlags::IS_USED;
-                }
-                let symbol = self.add_or_update_symbol(id.clone(), flags);
-                if flags.contains(SymbolFlags::IS_DEFINED) {
+                let symbol = self.add_symbol(id.clone());
+                if is_definition {
                     match self.current_assignment {
                         Some(CurrentAssignment::Assign(assignment)) => {
                             self.add_definition(
@@ -689,6 +838,7 @@ where
                                     iterable: &node.iter,
                                     target: name_node,
                                     first,
+                                    is_async: node.is_async,
                                 },
                             );
                         }
@@ -705,7 +855,8 @@ where
                     }
                 }
 
-                if flags.contains(SymbolFlags::IS_USED) {
+                if is_use {
+                    self.mark_symbol_used(symbol);
                     let use_id = self.current_ast_ids().record_use(expr);
                     self.current_use_def_map_mut().record_use(symbol, use_id);
                 }
@@ -742,6 +893,7 @@ where
                 }
 
                 self.visit_expr(lambda.body.as_ref());
+                self.pop_scope();
             }
             ast::Expr::If(ast::ExprIf {
                 body, test, orelse, ..
@@ -762,30 +914,33 @@ where
                     elt, generators, ..
                 },
             ) => {
-                self.visit_generators(
+                self.with_generators_scope(
                     NodeWithScopeRef::ListComprehension(list_comprehension),
                     generators,
+                    |builder| builder.visit_expr(elt),
                 );
-                self.visit_expr(elt);
             }
             ast::Expr::SetComp(
                 set_comprehension @ ast::ExprSetComp {
                     elt, generators, ..
                 },
             ) => {
-                self.visit_generators(
+                self.with_generators_scope(
                     NodeWithScopeRef::SetComprehension(set_comprehension),
                     generators,
+                    |builder| builder.visit_expr(elt),
                 );
-                self.visit_expr(elt);
             }
             ast::Expr::Generator(
                 generator @ ast::ExprGenerator {
                     elt, generators, ..
                 },
             ) => {
-                self.visit_generators(NodeWithScopeRef::GeneratorExpression(generator), generators);
-                self.visit_expr(elt);
+                self.with_generators_scope(
+                    NodeWithScopeRef::GeneratorExpression(generator),
+                    generators,
+                    |builder| builder.visit_expr(elt),
+                );
             }
             ast::Expr::DictComp(
                 dict_comprehension @ ast::ExprDictComp {
@@ -795,28 +950,19 @@ where
                     ..
                 },
             ) => {
-                self.visit_generators(
+                self.with_generators_scope(
                     NodeWithScopeRef::DictComprehension(dict_comprehension),
                     generators,
+                    |builder| {
+                        builder.visit_expr(key);
+                        builder.visit_expr(value);
+                    },
                 );
-                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();
-        }
     }
 
     fn visit_parameters(&mut self, parameters: &'ast ast::Parameters) {
@@ -845,7 +991,7 @@ where
             range: _,
         }) = pattern
         {
-            let symbol = self.add_or_update_symbol(name.id().clone(), SymbolFlags::IS_DEFINED);
+            let symbol = self.add_symbol(name.id().clone());
             let state = self.current_match_case.as_ref().unwrap();
             self.add_definition(
                 symbol,
@@ -866,7 +1012,7 @@ where
             rest: Some(name), ..
         }) = pattern
         {
-            let symbol = self.add_or_update_symbol(name.id().clone(), SymbolFlags::IS_DEFINED);
+            let symbol = self.add_symbol(name.id().clone());
             let state = self.current_match_case.as_ref().unwrap();
             self.add_definition(
                 symbol,

crates/red_knot_python_semantic/src/semantic_index/constraint.rs

@@ -0,0 +1,39 @@
+use ruff_db::files::File;
+use ruff_python_ast as ast;
+
+use crate::ast_node_ref::AstNodeRef;
+use crate::db::Db;
+use crate::semantic_index::expression::Expression;
+use crate::semantic_index::symbol::{FileScopeId, ScopeId};
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) enum Constraint<'db> {
+    Expression(Expression<'db>),
+    Pattern(PatternConstraint<'db>),
+}
+
+#[salsa::tracked]
+pub(crate) struct PatternConstraint<'db> {
+    #[id]
+    pub(crate) file: File,
+
+    #[id]
+    pub(crate) file_scope: FileScopeId,
+
+    #[no_eq]
+    #[return_ref]
+    pub(crate) subject: AstNodeRef<ast::Expr>,
+
+    #[no_eq]
+    #[return_ref]
+    pub(crate) pattern: AstNodeRef<ast::Pattern>,
+
+    #[no_eq]
+    count: countme::Count<PatternConstraint<'static>>,
+}
+
+impl<'db> PatternConstraint<'db> {
+    pub(crate) fn scope(self, db: &'db dyn Db) -> ScopeId<'db> {
+        self.file_scope(db).to_scope_id(db, self.file(db))
+    }
+}

crates/red_knot_python_semantic/src/semantic_index/definition.rs

@@ -23,7 +23,7 @@ pub struct Definition<'db> {
 
     #[no_eq]
     #[return_ref]
-    pub(crate) node: DefinitionKind,
+    pub(crate) kind: DefinitionKind,
 
     #[no_eq]
     count: countme::Count<Definition<'static>>,
@@ -33,6 +33,18 @@ impl<'db> Definition<'db> {
     pub(crate) fn scope(self, db: &'db dyn Db) -> ScopeId<'db> {
         self.file_scope(db).to_scope_id(db, self.file(db))
     }
+
+    pub(crate) fn category(self, db: &'db dyn Db) -> DefinitionCategory {
+        self.kind(db).category()
+    }
+
+    pub(crate) fn is_declaration(self, db: &'db dyn Db) -> bool {
+        self.kind(db).category().is_declaration()
+    }
+
+    pub(crate) fn is_binding(self, db: &'db dyn Db) -> bool {
+        self.kind(db).category().is_binding()
+    }
 }
 
 #[derive(Copy, Clone, Debug)]
@@ -50,6 +62,7 @@ pub(crate) enum DefinitionNodeRef<'a> {
     Parameter(ast::AnyParameterRef<'a>),
     WithItem(WithItemDefinitionNodeRef<'a>),
     MatchPattern(MatchPatternDefinitionNodeRef<'a>),
+    ExceptHandler(ExceptHandlerDefinitionNodeRef<'a>),
 }
 
 impl<'a> From<&'a ast::StmtFunctionDef> for DefinitionNodeRef<'a> {
@@ -155,11 +168,18 @@ pub(crate) struct ForStmtDefinitionNodeRef<'a> {
     pub(crate) is_async: bool,
 }
 
+#[derive(Copy, Clone, Debug)]
+pub(crate) struct ExceptHandlerDefinitionNodeRef<'a> {
+    pub(crate) handler: &'a ast::ExceptHandlerExceptHandler,
+    pub(crate) is_star: bool,
+}
+
 #[derive(Copy, Clone, Debug)]
 pub(crate) struct ComprehensionDefinitionNodeRef<'a> {
     pub(crate) iterable: &'a ast::Expr,
     pub(crate) target: &'a ast::ExprName,
     pub(crate) first: bool,
+    pub(crate) is_async: bool,
 }
 
 #[derive(Copy, Clone, Debug)]
@@ -220,10 +240,12 @@ impl DefinitionNodeRef<'_> {
                 iterable,
                 target,
                 first,
+                is_async,
             }) => DefinitionKind::Comprehension(ComprehensionDefinitionKind {
                 iterable: AstNodeRef::new(parsed.clone(), iterable),
                 target: AstNodeRef::new(parsed, target),
                 first,
+                is_async,
             }),
             DefinitionNodeRef::Parameter(parameter) => match parameter {
                 ast::AnyParameterRef::Variadic(parameter) => {
@@ -248,6 +270,13 @@ impl DefinitionNodeRef<'_> {
                 identifier: AstNodeRef::new(parsed, identifier),
                 index,
             }),
+            DefinitionNodeRef::ExceptHandler(ExceptHandlerDefinitionNodeRef {
+                handler,
+                is_star,
+            }) => DefinitionKind::ExceptHandler(ExceptHandlerDefinitionKind {
+                handler: AstNodeRef::new(parsed.clone(), handler),
+                is_star,
+            }),
         }
     }
 
@@ -280,10 +309,46 @@ impl DefinitionNodeRef<'_> {
             Self::MatchPattern(MatchPatternDefinitionNodeRef { identifier, .. }) => {
                 identifier.into()
             }
+            Self::ExceptHandler(ExceptHandlerDefinitionNodeRef { handler, .. }) => handler.into(),
         }
     }
 }
 
+#[derive(Clone, Copy, Debug)]
+pub(crate) enum DefinitionCategory {
+    /// A Definition which binds a value to a name (e.g. `x = 1`).
+    Binding,
+    /// A Definition which declares the upper-bound of acceptable types for this name (`x: int`).
+    Declaration,
+    /// A Definition which both declares a type and binds a value (e.g. `x: int = 1`).
+    DeclarationAndBinding,
+}
+
+impl DefinitionCategory {
+    /// True if this definition establishes a "declared type" for the symbol.
+    ///
+    /// If so, any assignments reached by this definition are in error if they assign a value of a
+    /// type not assignable to the declared type.
+    ///
+    /// Annotations establish a declared type. So do function and class definition.
+    pub(crate) fn is_declaration(self) -> bool {
+        matches!(
+            self,
+            DefinitionCategory::Declaration | DefinitionCategory::DeclarationAndBinding
+        )
+    }
+
+    /// True if this definition assigns a value to the symbol.
+    ///
+    /// False only for annotated assignments without a RHS.
+    pub(crate) fn is_binding(self) -> bool {
+        matches!(
+            self,
+            DefinitionCategory::Binding | DefinitionCategory::DeclarationAndBinding
+        )
+    }
+}
+
 #[derive(Clone, Debug)]
 pub enum DefinitionKind {
     Import(AstNodeRef<ast::Alias>),
@@ -300,6 +365,53 @@ pub enum DefinitionKind {
     ParameterWithDefault(AstNodeRef<ast::ParameterWithDefault>),
     WithItem(WithItemDefinitionKind),
     MatchPattern(MatchPatternDefinitionKind),
+    ExceptHandler(ExceptHandlerDefinitionKind),
+}
+
+impl DefinitionKind {
+    pub(crate) fn category(&self) -> DefinitionCategory {
+        match self {
+            // functions and classes always bind a value, and we always consider them declarations
+            DefinitionKind::Function(_) | DefinitionKind::Class(_) => {
+                DefinitionCategory::DeclarationAndBinding
+            }
+            // a parameter always binds a value, but is only a declaration if annotated
+            DefinitionKind::Parameter(parameter) => {
+                if parameter.annotation.is_some() {
+                    DefinitionCategory::DeclarationAndBinding
+                } else {
+                    DefinitionCategory::Binding
+                }
+            }
+            // presence of a default is irrelevant, same logic as for a no-default parameter
+            DefinitionKind::ParameterWithDefault(parameter_with_default) => {
+                if parameter_with_default.parameter.annotation.is_some() {
+                    DefinitionCategory::DeclarationAndBinding
+                } else {
+                    DefinitionCategory::Binding
+                }
+            }
+            // annotated assignment is always a declaration, only a binding if there is a RHS
+            DefinitionKind::AnnotatedAssignment(ann_assign) => {
+                if ann_assign.value.is_some() {
+                    DefinitionCategory::DeclarationAndBinding
+                } else {
+                    DefinitionCategory::Declaration
+                }
+            }
+            // all of these bind values without declaring a type
+            DefinitionKind::Import(_)
+            | DefinitionKind::ImportFrom(_)
+            | DefinitionKind::NamedExpression(_)
+            | DefinitionKind::Assignment(_)
+            | DefinitionKind::AugmentedAssignment(_)
+            | DefinitionKind::For(_)
+            | DefinitionKind::Comprehension(_)
+            | DefinitionKind::WithItem(_)
+            | DefinitionKind::MatchPattern(_)
+            | DefinitionKind::ExceptHandler(_) => DefinitionCategory::Binding,
+        }
+    }
 }
 
 #[derive(Clone, Debug)]
@@ -325,6 +437,7 @@ pub struct ComprehensionDefinitionKind {
     iterable: AstNodeRef<ast::Expr>,
     target: AstNodeRef<ast::ExprName>,
     first: bool,
+    is_async: bool,
 }
 
 impl ComprehensionDefinitionKind {
@@ -339,6 +452,10 @@ impl ComprehensionDefinitionKind {
     pub(crate) fn is_first(&self) -> bool {
         self.first
     }
+
+    pub(crate) fn is_async(&self) -> bool {
+        self.is_async
+    }
 }
 
 #[derive(Clone, Debug)]
@@ -410,6 +527,26 @@ impl ForStmtDefinitionKind {
     }
 }
 
+#[derive(Clone, Debug)]
+pub struct ExceptHandlerDefinitionKind {
+    handler: AstNodeRef<ast::ExceptHandlerExceptHandler>,
+    is_star: bool,
+}
+
+impl ExceptHandlerDefinitionKind {
+    pub(crate) fn node(&self) -> &ast::ExceptHandlerExceptHandler {
+        self.handler.node()
+    }
+
+    pub(crate) fn handled_exceptions(&self) -> Option<&ast::Expr> {
+        self.node().type_.as_deref()
+    }
+
+    pub(crate) fn is_star(&self) -> bool {
+        self.is_star
+    }
+}
+
 #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
 pub(crate) struct DefinitionNodeKey(NodeKey);
 
@@ -478,3 +615,9 @@ impl From<&ast::Identifier> for DefinitionNodeKey {
         Self(NodeKey::from_node(identifier))
     }
 }
+
+impl From<&ast::ExceptHandlerExceptHandler> for DefinitionNodeKey {
+    fn from(handler: &ast::ExceptHandlerExceptHandler) -> Self {
+        Self(NodeKey::from_node(handler))
+    }
+}

crates/red_knot_python_semantic/src/semantic_index/symbol.rs

@@ -44,16 +44,16 @@ impl Symbol {
     }
 
     /// Is the symbol defined in its containing scope?
-    pub fn is_defined(&self) -> bool {
-        self.flags.contains(SymbolFlags::IS_DEFINED)
+    pub fn is_bound(&self) -> bool {
+        self.flags.contains(SymbolFlags::IS_BOUND)
     }
 }
 
 bitflags! {
     #[derive(Copy, Clone, Debug, Eq, PartialEq)]
-    pub(super) struct SymbolFlags: u8 {
+    struct SymbolFlags: u8 {
         const IS_USED         = 1 << 0;
-        const IS_DEFINED      = 1 << 1;
+        const IS_BOUND      = 1 << 1;
         /// TODO: This flag is not yet set by anything
         const MARKED_GLOBAL   = 1 << 2;
         /// TODO: This flag is not yet set by anything
@@ -272,11 +272,7 @@ impl SymbolTableBuilder {
         }
     }
 
-    pub(super) fn add_or_update_symbol(
-        &mut self,
-        name: Name,
-        flags: SymbolFlags,
-    ) -> (ScopedSymbolId, bool) {
+    pub(super) fn add_symbol(&mut self, name: Name) -> (ScopedSymbolId, bool) {
         let hash = SymbolTable::hash_name(&name);
         let entry = self
             .table
@@ -285,15 +281,9 @@ impl SymbolTableBuilder {
             .from_hash(hash, |id| self.table.symbols[*id].name() == &name);
 
         match entry {
-            RawEntryMut::Occupied(entry) => {
-                let symbol = &mut self.table.symbols[*entry.key()];
-                symbol.insert_flags(flags);
-
-                (*entry.key(), false)
-            }
+            RawEntryMut::Occupied(entry) => (*entry.key(), false),
             RawEntryMut::Vacant(entry) => {
-                let mut symbol = Symbol::new(name);
-                symbol.insert_flags(flags);
+                let symbol = Symbol::new(name);
 
                 let id = self.table.symbols.push(symbol);
                 entry.insert_with_hasher(hash, id, (), |id| {
@@ -304,6 +294,14 @@ impl SymbolTableBuilder {
         }
     }
 
+    pub(super) fn mark_symbol_bound(&mut self, id: ScopedSymbolId) {
+        self.table.symbols[id].insert_flags(SymbolFlags::IS_BOUND);
+    }
+
+    pub(super) fn mark_symbol_used(&mut self, id: ScopedSymbolId) {
+        self.table.symbols[id].insert_flags(SymbolFlags::IS_USED);
+    }
+
     pub(super) fn finish(mut self) -> SymbolTable {
         self.table.shrink_to_fit();
         self.table

crates/red_knot_python_semantic/src/semantic_index/use_def.rs

@@ -1,5 +1,79 @@
-//! Build a map from each use of a symbol to the definitions visible from that use, and the
-//! type-narrowing constraints that apply to each definition.
+//! First, some terminology:
+//!
+//! * A "binding" gives a new value to a variable. This includes many different Python statements
+//!   (assignment statements of course, but also imports, `def` and `class` statements, `as`
+//!   clauses in `with` and `except` statements, match patterns, and others) and even one
+//!   expression kind (named expressions). It notably does not include annotated assignment
+//!   statements without a right-hand side value; these do not assign any new value to the
+//!   variable. We consider function parameters to be bindings as well, since (from the perspective
+//!   of the function's internal scope), a function parameter begins the scope bound to a value.
+//!
+//! * A "declaration" establishes an upper bound type for the values that a variable may be
+//!   permitted to take on. Annotated assignment statements (with or without an RHS value) are
+//!   declarations; annotated function parameters are also declarations. We consider `def` and
+//!   `class` statements to also be declarations, so as to prohibit accidentally shadowing them.
+//!
+//! Annotated assignments with a right-hand side, and annotated function parameters, are both
+//! bindings and declarations.
+//!
+//! We use [`Definition`] as the universal term (and Salsa tracked struct) encompassing both
+//! bindings and declarations. (This sacrifices a bit of type safety in exchange for improved
+//! performance via fewer Salsa tracked structs and queries, since most declarations -- typed
+//! parameters and annotated assignments with RHS -- are both bindings and declarations.)
+//!
+//! At any given use of a variable, we can ask about both its "declared type" and its "inferred
+//! type". These may be different, but the inferred type must always be assignable to the declared
+//! type; that is, the declared type is always wider, and the inferred type may be more precise. If
+//! we see an invalid assignment, we emit a diagnostic and abandon our inferred type, deferring to
+//! the declared type (this allows an explicit annotation to override bad inference, without a
+//! cast), maintaining the invariant.
+//!
+//! The **inferred type** represents the most precise type we believe encompasses all possible
+//! values for the variable at a given use. It is based on a union of the bindings which can reach
+//! that use through some control flow path, and the narrowing constraints that control flow must
+//! have passed through between the binding and the use. For example, in this code:
+//!
+//! ```python
+//! x = 1 if flag else None
+//! if x is not None:
+//!     use(x)
+//! ```
+//!
+//! For the use of `x` on the third line, the inferred type should be `Literal[1]`. This is based
+//! on the binding on the first line, which assigns the type `Literal[1] | None`, and the narrowing
+//! constraint on the second line, which rules out the type `None`, since control flow must pass
+//! through this constraint to reach the use in question.
+//!
+//! The **declared type** represents the code author's declaration (usually through a type
+//! annotation) that a given variable should not be assigned any type outside the declared type. In
+//! our model, declared types are also control-flow-sensitive; we allow the code author to
+//! explicitly re-declare the same variable with a different type. So for a given binding of a
+//! variable, we will want to ask which declarations of that variable can reach that binding, in
+//! order to determine whether the binding is permitted, or should be a type error. For example:
+//!
+//! ```python
+//! from pathlib import Path
+//! def f(path: str):
+//!     path: Path = Path(path)
+//! ```
+//!
+//! In this function, the initial declared type of `path` is `str`, meaning that the assignment
+//! `path = Path(path)` would be a type error, since it assigns to `path` a value whose type is not
+//! assignable to `str`. This is the purpose of declared types: they prevent accidental assignment
+//! of the wrong type to a variable.
+//!
+//! But in some cases it is useful to "shadow" or "re-declare" a variable with a new type, and we
+//! permit this, as long as it is done with an explicit re-annotation. So `path: Path =
+//! Path(path)`, with the explicit `: Path` annotation, is permitted.
+//!
+//! The general rule is that whatever declaration(s) can reach a given binding determine the
+//! validity of that binding. If there is a path in which the symbol is not declared, that is a
+//! declaration of `Unknown`. If multiple declarations can reach a binding, we union them, but by
+//! default we also issue a type error, since this implicit union of declared types may hide an
+//! error.
+//!
+//! To support type inference, we build a map from each use of a symbol to the bindings live at
+//! that use, and the type narrowing constraints that apply to each binding.
 //!
 //! Let's take this code sample:
 //!
@@ -7,148 +81,157 @@
 //! x = 1
 //! x = 2
 //! y = x
-//! if y is not None:
+//! if flag:
 //!     x = 3
 //! else:
 //!     x = 4
 //! z = x
 //! ```
 //!
-//! In this snippet, we have four definitions of `x` (the statements assigning `1`, `2`, `3`,
-//! and `4` to it), and two uses of `x` (the `y = x` and `z = x` assignments). The first
-//! [`Definition`] of `x` is never visible to any use, because it's immediately replaced by the
-//! second definition, before any use happens. (A linter could thus flag the statement `x = 1`
-//! as likely superfluous.)
+//! In this snippet, we have four bindings of `x` (the statements assigning `1`, `2`, `3`, and `4`
+//! to it), and two uses of `x` (the `y = x` and `z = x` assignments). The first binding of `x`
+//! does not reach any use, because it's immediately replaced by the second binding, before any use
+//! happens. (A linter could thus flag the statement `x = 1` as likely superfluous.)
 //!
-//! The first use of `x` has one definition visible to it: the assignment `x = 2`.
+//! The first use of `x` has one live binding: the assignment `x = 2`.
 //!
 //! Things get a bit more complex when we have branches. We will definitely take either the `if` or
-//! the `else` branch. Thus, the second use of `x` has two definitions visible to it: `x = 3` and
-//! `x = 4`. The `x = 2` definition is no longer visible, because it must be replaced by either `x
-//! = 3` or `x = 4`, no matter which branch was taken. We don't know which branch was taken, so we
-//! must consider both definitions as visible, which means eventually we would (in type inference)
-//! look at these two definitions and infer a type of `Literal[3, 4]` -- the union of `Literal[3]`
-//! and `Literal[4]` -- for the second use of `x`.
+//! the `else` branch. Thus, the second use of `x` has two live bindings: `x = 3` and `x = 4`. The
+//! `x = 2` assignment is no longer visible, because it must be replaced by either `x = 3` or `x =
+//! 4`, no matter which branch was taken. We don't know which branch was taken, so we must consider
+//! both bindings as live, which means eventually we would (in type inference) look at these two
+//! bindings and infer a type of `Literal[3, 4]` -- the union of `Literal[3]` and `Literal[4]` --
+//! for the second use of `x`.
 //!
 //! So that's one question our use-def map needs to answer: given a specific use of a symbol, which
-//! definition(s) is/are visible from that use. In
-//! [`AstIds`](crate::semantic_index::ast_ids::AstIds) we number all uses (that means a `Name` node
-//! with `Load` context) so we have a `ScopedUseId` to efficiently represent each use.
+//! binding(s) can reach that use. In [`AstIds`](crate::semantic_index::ast_ids::AstIds) we number
+//! all uses (that means a `Name` node with `Load` context) so we have a `ScopedUseId` to
+//! efficiently represent each use.
 //!
-//! Another case we need to handle is when a symbol is referenced from a different scope (the most
-//! obvious example of this is an import). We call this "public" use of a symbol. So the other
-//! question we need to be able to answer is, what are the publicly-visible definitions of each
-//! symbol?
-//!
-//! Technically, public use of a symbol could also occur from any point in control flow of the
-//! scope where the symbol is defined (via inline imports and import cycles, in the case of an
-//! import, or via a function call partway through the local scope that ends up using a symbol from
-//! the scope via a global or nonlocal reference.) But modeling this fully accurately requires
-//! whole-program analysis that isn't tractable for an efficient incremental compiler, since it
-//! means a given symbol could have a different type every place it's referenced throughout the
-//! program, depending on the shape of arbitrarily-sized call/import graphs. So we follow other
-//! Python type-checkers in making the simplifying assumption that usually the scope will finish
-//! execution before its symbols are made visible to other scopes; for instance, most imports will
-//! import from a complete module, not a partially-executed module. (We may want to get a little
-//! smarter than this in the future, in particular for closures, but for now this is where we
-//! start.)
-//!
-//! So this means that the publicly-visible definitions of a symbol are the definitions still
-//! visible at the end of the scope; effectively we have an implicit "use" of every symbol at the
-//! end of the scope.
-//!
-//! We also need to know, for a given definition of a symbol, what type-narrowing constraints apply
+//! We also need to know, for a given definition of a symbol, what type narrowing constraints apply
 //! to it. For instance, in this code sample:
 //!
 //! ```python
 //! x = 1 if flag else None
 //! if x is not None:
-//!     y = x
+//!     use(x)
 //! ```
 //!
-//! At the use of `x` in `y = x`, the visible definition of `x` is `1 if flag else None`, which
-//! would infer as the type `Literal[1] | None`. But the constraint `x is not None` dominates this
-//! use, which means we can rule out the possibility that `x` is `None` here, which should give us
-//! the type `Literal[1]` for this use.
+//! At the use of `x`, the live binding of `x` is `1 if flag else None`, which would infer as the
+//! type `Literal[1] | None`. But the constraint `x is not None` dominates this use, which means we
+//! can rule out the possibility that `x` is `None` here, which should give us the type
+//! `Literal[1]` for this use.
+//!
+//! For declared types, we need to be able to answer the question "given a binding to a symbol,
+//! which declarations of that symbol can reach the binding?" This allows us to emit a diagnostic
+//! if the binding is attempting to bind a value of a type that is not assignable to the declared
+//! type for that symbol, at that point in control flow.
+//!
+//! We also need to know, given a declaration of a symbol, what the inferred type of that symbol is
+//! at that point. This allows us to emit a diagnostic in a case like `x = "foo"; x: int`. The
+//! binding `x = "foo"` occurs before the declaration `x: int`, so according to our
+//! control-flow-sensitive interpretation of declarations, the assignment is not an error. But the
+//! declaration is an error, since it would violate the "inferred type must be assignable to
+//! declared type" rule.
+//!
+//! Another case we need to handle is when a symbol is referenced from a different scope (for
+//! example, an import or a nonlocal reference). We call this "public" use of a symbol. For public
+//! use of a symbol, we prefer the declared type, if there are any declarations of that symbol; if
+//! not, we fall back to the inferred type. So we also need to know which declarations and bindings
+//! can reach the end of the scope.
+//!
+//! Technically, public use of a symbol could occur from any point in control flow of the scope
+//! where the symbol is defined (via inline imports and import cycles, in the case of an import, or
+//! via a function call partway through the local scope that ends up using a symbol from the scope
+//! via a global or nonlocal reference.) But modeling this fully accurately requires whole-program
+//! analysis that isn't tractable for an efficient analysis, since it means a given symbol could
+//! have a different type every place it's referenced throughout the program, depending on the
+//! shape of arbitrarily-sized call/import graphs. So we follow other Python type checkers in
+//! making the simplifying assumption that usually the scope will finish execution before its
+//! symbols are made visible to other scopes; for instance, most imports will import from a
+//! complete module, not a partially-executed module. (We may want to get a little smarter than
+//! this in the future for some closures, but for now this is where we start.)
 //!
 //! The data structure we build to answer these 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, with a list of the
-//! dominating constraints for each of those definitions.
+//! `bindings_by_use` vector of [`SymbolBindings`] indexed by [`ScopedUseId`], a
+//! `declarations_by_binding` vector of [`SymbolDeclarations`] indexed by [`ScopedDefinitionId`], a
+//! `bindings_by_declaration` vector of [`SymbolBindings`] indexed by [`ScopedDefinitionId`], and
+//! `public_bindings` and `public_definitions` vectors indexed by [`ScopedSymbolId`]. The values in
+//! each of these vectors are (in principle) a list of live bindings at that use/definition, or at
+//! the end of the scope for that symbol, with a list of the dominating constraints for each
+//! binding.
 //!
 //! In order to avoid vectors-of-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`].
-//! Instead, the values in `definitions_by_use` and `public_definitions` are a [`SymbolState`]
-//! struct which uses bit-sets to track definitions and constraints in terms of
-//! [`ScopedDefinitionId`] and [`ScopedConstraintId`], which are indices into the `all_definitions`
-//! and `all_constraints` indexvecs in the [`UseDefMap`].
+//! Instead, [`SymbolBindings`] and [`SymbolDeclarations`] are structs which use bit-sets to track
+//! definitions (and constraints, in the case of bindings) in terms of [`ScopedDefinitionId`] and
+//! [`ScopedConstraintId`], which are indices into the `all_definitions` and `all_constraints`
+//! indexvecs in the [`UseDefMap`].
 //!
 //! There is another special kind of possible "definition" for a symbol: there might be a path from
 //! the scope entry to a given use in which the symbol is never bound.
 //!
-//! 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
-//! unnecessarily 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, and constraints are irrelevant to it, we can represent it more efficiently: we use the
-//! `may_be_unbound` boolean on the [`SymbolState`] 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.
+//! The simplest way to model "unbound" would be as a "binding" itself: the initial "binding" for
+//! each symbol in a scope. But actually modeling it this way would unnecessarily increase the
+//! number of [`Definition`]s that Salsa must track. Since "unbound" is special in that all symbols
+//! share it, and it doesn't have any additional per-symbol state, and constraints are irrelevant
+//! to it, we can represent it more efficiently: we use the `may_be_unbound` boolean on the
+//! [`SymbolBindings`] struct. If this flag is `true` for a use of a symbol, it means the symbol
+//! has a path to the use in which it is never bound. If this flag is `false`, it means we've
+//! eliminated the possibility of unbound: every control flow path to the use includes a binding
+//! for this symbol.
 //!
 //! To build a [`UseDefMap`], the [`UseDefMapBuilder`] is notified of each new use, definition, and
 //! constraint as they are encountered by the
 //! [`SemanticIndexBuilder`](crate::semantic_index::builder::SemanticIndexBuilder) AST visit. For
-//! each symbol, the builder tracks the `SymbolState` for that symbol. When we hit a use of a
-//! symbol, it records the current state for that symbol for that use. When we reach the end of the
-//! scope, it records the state for each symbol as the public definitions of that symbol.
+//! each symbol, the builder tracks the `SymbolState` (`SymbolBindings` and `SymbolDeclarations`)
+//! for that symbol. When we hit a use or definition of a symbol, we record the necessary parts of
+//! the current state for that symbol that we need for that use or definition. When we reach the
+//! end of the scope, it records the state 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.
+//! Let's walk through the above example. Initially we record for `x` that it has no bindings, and
+//! may be unbound. When we see `x = 1`, we record that as the sole live binding of `x`, and flip
+//! `may_be_unbound` to `false`. Then we see `x = 2`, and we replace `x = 1` as the sole live
+//! binding of `x`. When we get to `y = x`, we record that the live bindings 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 record `flag` as a possible constraint on the
-//! currently visible definition (`x = 2`), and go ahead and visit the `if` body. When we see `x =
-//! 3`, it replaces `x = 2` (constrained by `flag`) 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.
+//! happen regardless. Then we take a pre-branch snapshot of the current state for all symbols,
+//! which we'll need later. Then we record `flag` as a possible constraint on the current binding
+//! (`x = 2`), and go ahead and visit the `if` body. When we see `x = 3`, it replaces `x = 2`
+//! (constrained by `flag`) as the sole live binding of `x`. At the end of the `if` body, we take
+//! another snapshot of the current symbol state; 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`.
+//! using the snapshot we took previously (meaning we now have `x = 2` as the sole binding for `x`
+//! again), then visit the `else` clause, where `x = 4` replaces `x = 2` as the sole live binding
+//! 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`.
+//! (reflecting the end-of-else state, with `x = 4` as the only live binding) with our post-if-body
+//! snapshot (which has `x = 3` as the only live binding). The result of this merge is that we now
+//! have two live bindings 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.)
 use self::symbol_state::{
-    ConstraintIdIterator, DefinitionIdWithConstraintsIterator, ScopedConstraintId,
-    ScopedDefinitionId, SymbolState,
+    BindingIdWithConstraintsIterator, ConstraintIdIterator, DeclarationIdIterator,
+    ScopedConstraintId, ScopedDefinitionId, SymbolBindings, SymbolDeclarations, SymbolState,
 };
 use crate::semantic_index::ast_ids::ScopedUseId;
 use crate::semantic_index::definition::Definition;
-use crate::semantic_index::expression::Expression;
 use crate::semantic_index::symbol::ScopedSymbolId;
 use ruff_index::IndexVec;
+use rustc_hash::FxHashMap;
+
+use super::constraint::Constraint;
 
 mod bitset;
 mod symbol_state;
@@ -159,63 +242,135 @@ pub(crate) struct UseDefMap<'db> {
     /// Array of [`Definition`] in this scope.
     all_definitions: IndexVec<ScopedDefinitionId, Definition<'db>>,
 
-    /// Array of constraints (as [`Expression`]) in this scope.
-    all_constraints: IndexVec<ScopedConstraintId, Expression<'db>>,
+    /// Array of [`Constraint`] in this scope.
+    all_constraints: IndexVec<ScopedConstraintId, Constraint<'db>>,
 
-    /// [`SymbolState`] visible at a [`ScopedUseId`].
-    definitions_by_use: IndexVec<ScopedUseId, SymbolState>,
+    /// [`SymbolBindings`] reaching a [`ScopedUseId`].
+    bindings_by_use: IndexVec<ScopedUseId, SymbolBindings>,
+
+    /// [`SymbolBindings`] or [`SymbolDeclarations`] reaching a given [`Definition`].
+    ///
+    /// If the definition is a binding (only) -- `x = 1` for example -- then we need
+    /// [`SymbolDeclarations`] to know whether this binding is permitted by the live declarations.
+    ///
+    /// If the definition is a declaration (only) -- `x: int` for example -- then we need
+    /// [`SymbolBindings`] to know whether this declaration is consistent with the previously
+    /// inferred type.
+    ///
+    /// If the definition is both a declaration and a binding -- `x: int = 1` for example -- then
+    /// we don't actually need anything here, all we'll need to validate is that our own RHS is a
+    /// valid assignment to our own annotation.
+    definitions_by_definition: FxHashMap<Definition<'db>, SymbolDefinitions>,
 
     /// [`SymbolState`] visible at end of scope for each symbol.
-    public_definitions: IndexVec<ScopedSymbolId, SymbolState>,
+    public_symbols: IndexVec<ScopedSymbolId, SymbolState>,
 }
 
 impl<'db> UseDefMap<'db> {
-    pub(crate) fn use_definitions(
+    pub(crate) fn bindings_at_use(
         &self,
         use_id: ScopedUseId,
-    ) -> DefinitionWithConstraintsIterator<'_, 'db> {
-        DefinitionWithConstraintsIterator {
-            all_definitions: &self.all_definitions,
-            all_constraints: &self.all_constraints,
-            inner: self.definitions_by_use[use_id].visible_definitions(),
-        }
+    ) -> BindingWithConstraintsIterator<'_, 'db> {
+        self.bindings_iterator(&self.bindings_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()
+        self.bindings_by_use[use_id].may_be_unbound()
     }
 
-    pub(crate) fn public_definitions(
+    pub(crate) fn public_bindings(
         &self,
         symbol: ScopedSymbolId,
-    ) -> DefinitionWithConstraintsIterator<'_, 'db> {
-        DefinitionWithConstraintsIterator {
-            all_definitions: &self.all_definitions,
-            all_constraints: &self.all_constraints,
-            inner: self.public_definitions[symbol].visible_definitions(),
-        }
+    ) -> BindingWithConstraintsIterator<'_, 'db> {
+        self.bindings_iterator(self.public_symbols[symbol].bindings())
     }
 
     pub(crate) fn public_may_be_unbound(&self, symbol: ScopedSymbolId) -> bool {
-        self.public_definitions[symbol].may_be_unbound()
+        self.public_symbols[symbol].may_be_unbound()
+    }
+
+    pub(crate) fn bindings_at_declaration(
+        &self,
+        declaration: Definition<'db>,
+    ) -> BindingWithConstraintsIterator<'_, 'db> {
+        if let SymbolDefinitions::Bindings(bindings) = &self.definitions_by_definition[&declaration]
+        {
+            self.bindings_iterator(bindings)
+        } else {
+            unreachable!("Declaration has non-Bindings in definitions_by_definition");
+        }
+    }
+
+    pub(crate) fn declarations_at_binding(
+        &self,
+        binding: Definition<'db>,
+    ) -> DeclarationsIterator<'_, 'db> {
+        if let SymbolDefinitions::Declarations(declarations) =
+            &self.definitions_by_definition[&binding]
+        {
+            self.declarations_iterator(declarations)
+        } else {
+            unreachable!("Binding has non-Declarations in definitions_by_definition");
+        }
+    }
+
+    pub(crate) fn public_declarations(
+        &self,
+        symbol: ScopedSymbolId,
+    ) -> DeclarationsIterator<'_, 'db> {
+        let declarations = self.public_symbols[symbol].declarations();
+        self.declarations_iterator(declarations)
+    }
+
+    pub(crate) fn has_public_declarations(&self, symbol: ScopedSymbolId) -> bool {
+        !self.public_symbols[symbol].declarations().is_empty()
+    }
+
+    fn bindings_iterator<'a>(
+        &'a self,
+        bindings: &'a SymbolBindings,
+    ) -> BindingWithConstraintsIterator<'a, 'db> {
+        BindingWithConstraintsIterator {
+            all_definitions: &self.all_definitions,
+            all_constraints: &self.all_constraints,
+            inner: bindings.iter(),
+        }
+    }
+
+    fn declarations_iterator<'a>(
+        &'a self,
+        declarations: &'a SymbolDeclarations,
+    ) -> DeclarationsIterator<'a, 'db> {
+        DeclarationsIterator {
+            all_definitions: &self.all_definitions,
+            inner: declarations.iter(),
+            may_be_undeclared: declarations.may_be_undeclared(),
+        }
     }
 }
 
-#[derive(Debug)]
-pub(crate) struct DefinitionWithConstraintsIterator<'map, 'db> {
-    all_definitions: &'map IndexVec<ScopedDefinitionId, Definition<'db>>,
-    all_constraints: &'map IndexVec<ScopedConstraintId, Expression<'db>>,
-    inner: DefinitionIdWithConstraintsIterator<'map>,
+/// Either live bindings or live declarations for a symbol.
+#[derive(Debug, PartialEq, Eq)]
+enum SymbolDefinitions {
+    Bindings(SymbolBindings),
+    Declarations(SymbolDeclarations),
 }
 
-impl<'map, 'db> Iterator for DefinitionWithConstraintsIterator<'map, 'db> {
-    type Item = DefinitionWithConstraints<'map, 'db>;
+#[derive(Debug)]
+pub(crate) struct BindingWithConstraintsIterator<'map, 'db> {
+    all_definitions: &'map IndexVec<ScopedDefinitionId, Definition<'db>>,
+    all_constraints: &'map IndexVec<ScopedConstraintId, Constraint<'db>>,
+    inner: BindingIdWithConstraintsIterator<'map>,
+}
+
+impl<'map, 'db> Iterator for BindingWithConstraintsIterator<'map, 'db> {
+    type Item = BindingWithConstraints<'map, 'db>;
 
     fn next(&mut self) -> Option<Self::Item> {
         self.inner
             .next()
-            .map(|def_id_with_constraints| DefinitionWithConstraints {
-                definition: self.all_definitions[def_id_with_constraints.definition],
+            .map(|def_id_with_constraints| BindingWithConstraints {
+                binding: self.all_definitions[def_id_with_constraints.definition],
                 constraints: ConstraintsIterator {
                     all_constraints: self.all_constraints,
                     constraint_ids: def_id_with_constraints.constraint_ids,
@@ -224,20 +379,20 @@ impl<'map, 'db> Iterator for DefinitionWithConstraintsIterator<'map, 'db> {
     }
 }
 
-impl std::iter::FusedIterator for DefinitionWithConstraintsIterator<'_, '_> {}
+impl std::iter::FusedIterator for BindingWithConstraintsIterator<'_, '_> {}
 
-pub(crate) struct DefinitionWithConstraints<'map, 'db> {
-    pub(crate) definition: Definition<'db>,
+pub(crate) struct BindingWithConstraints<'map, 'db> {
+    pub(crate) binding: Definition<'db>,
     pub(crate) constraints: ConstraintsIterator<'map, 'db>,
 }
 
 pub(crate) struct ConstraintsIterator<'map, 'db> {
-    all_constraints: &'map IndexVec<ScopedConstraintId, Expression<'db>>,
+    all_constraints: &'map IndexVec<ScopedConstraintId, Constraint<'db>>,
     constraint_ids: ConstraintIdIterator<'map>,
 }
 
 impl<'map, 'db> Iterator for ConstraintsIterator<'map, 'db> {
-    type Item = Expression<'db>;
+    type Item = Constraint<'db>;
 
     fn next(&mut self) -> Option<Self::Item> {
         self.constraint_ids
@@ -248,25 +403,50 @@ impl<'map, 'db> Iterator for ConstraintsIterator<'map, 'db> {
 
 impl std::iter::FusedIterator for ConstraintsIterator<'_, '_> {}
 
+pub(crate) struct DeclarationsIterator<'map, 'db> {
+    all_definitions: &'map IndexVec<ScopedDefinitionId, Definition<'db>>,
+    inner: DeclarationIdIterator<'map>,
+    may_be_undeclared: bool,
+}
+
+impl DeclarationsIterator<'_, '_> {
+    pub(crate) fn may_be_undeclared(&self) -> bool {
+        self.may_be_undeclared
+    }
+}
+
+impl<'map, 'db> Iterator for DeclarationsIterator<'map, 'db> {
+    type Item = Definition<'db>;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        self.inner.next().map(|def_id| self.all_definitions[def_id])
+    }
+}
+
+impl std::iter::FusedIterator for DeclarationsIterator<'_, '_> {}
+
 /// A snapshot of the definitions and constraints state at a particular point in control flow.
 #[derive(Clone, Debug)]
 pub(super) struct FlowSnapshot {
-    definitions_by_symbol: IndexVec<ScopedSymbolId, SymbolState>,
+    symbol_states: IndexVec<ScopedSymbolId, SymbolState>,
 }
 
 #[derive(Debug, Default)]
 pub(super) struct UseDefMapBuilder<'db> {
-    /// Append-only array of [`Definition`]; None is unbound.
+    /// Append-only array of [`Definition`].
     all_definitions: IndexVec<ScopedDefinitionId, Definition<'db>>,
 
-    /// Append-only array of constraints (as [`Expression`]).
-    all_constraints: IndexVec<ScopedConstraintId, Expression<'db>>,
+    /// Append-only array of [`Constraint`].
+    all_constraints: IndexVec<ScopedConstraintId, Constraint<'db>>,
 
-    /// Visible definitions at each so-far-recorded use.
-    definitions_by_use: IndexVec<ScopedUseId, SymbolState>,
+    /// Live bindings at each so-far-recorded use.
+    bindings_by_use: IndexVec<ScopedUseId, SymbolBindings>,
 
-    /// Currently visible definitions for each symbol.
-    definitions_by_symbol: IndexVec<ScopedSymbolId, SymbolState>,
+    /// Live bindings or declarations for each so-far-recorded definition.
+    definitions_by_definition: FxHashMap<Definition<'db>, SymbolDefinitions>,
+
+    /// Currently live bindings and declarations for each symbol.
+    symbol_states: IndexVec<ScopedSymbolId, SymbolState>,
 }
 
 impl<'db> UseDefMapBuilder<'db> {
@@ -275,86 +455,104 @@ impl<'db> UseDefMapBuilder<'db> {
     }
 
     pub(super) fn add_symbol(&mut self, symbol: ScopedSymbolId) {
-        let new_symbol = self.definitions_by_symbol.push(SymbolState::unbound());
+        let new_symbol = self.symbol_states.push(SymbolState::undefined());
         debug_assert_eq!(symbol, new_symbol);
     }
 
-    pub(super) fn record_definition(
+    pub(super) fn record_binding(&mut self, symbol: ScopedSymbolId, binding: Definition<'db>) {
+        let def_id = self.all_definitions.push(binding);
+        let symbol_state = &mut self.symbol_states[symbol];
+        self.definitions_by_definition.insert(
+            binding,
+            SymbolDefinitions::Declarations(symbol_state.declarations().clone()),
+        );
+        symbol_state.record_binding(def_id);
+    }
+
+    pub(super) fn record_constraint(&mut self, constraint: Constraint<'db>) {
+        let constraint_id = self.all_constraints.push(constraint);
+        for state in &mut self.symbol_states {
+            state.record_constraint(constraint_id);
+        }
+    }
+
+    pub(super) fn record_declaration(
+        &mut self,
+        symbol: ScopedSymbolId,
+        declaration: Definition<'db>,
+    ) {
+        let def_id = self.all_definitions.push(declaration);
+        let symbol_state = &mut self.symbol_states[symbol];
+        self.definitions_by_definition.insert(
+            declaration,
+            SymbolDefinitions::Bindings(symbol_state.bindings().clone()),
+        );
+        symbol_state.record_declaration(def_id);
+    }
+
+    pub(super) fn record_declaration_and_binding(
         &mut self,
         symbol: ScopedSymbolId,
         definition: Definition<'db>,
     ) {
-        // We have a new definition of a symbol; this replaces any previous definitions in this
-        // path.
+        // We don't need to store anything in self.definitions_by_definition.
         let def_id = self.all_definitions.push(definition);
-        self.definitions_by_symbol[symbol] = SymbolState::with(def_id);
-    }
-
-    pub(super) fn record_constraint(&mut self, constraint: Expression<'db>) {
-        let constraint_id = self.all_constraints.push(constraint);
-        for definitions in &mut self.definitions_by_symbol {
-            definitions.add_constraint(constraint_id);
-        }
+        let symbol_state = &mut self.symbol_states[symbol];
+        symbol_state.record_declaration(def_id);
+        symbol_state.record_binding(def_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.
+        // We have a use of a symbol; clone the current bindings for that symbol, and record them
+        // as the live bindings for this use.
         let new_use = self
-            .definitions_by_use
-            .push(self.definitions_by_symbol[symbol].clone());
+            .bindings_by_use
+            .push(self.symbol_states[symbol].bindings().clone());
         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(),
+            symbol_states: self.symbol_states.clone(),
         }
     }
 
-    /// Restore the current builder visible-definitions state to the given snapshot.
+    /// Restore the current builder symbols 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
+        // We never remove symbols from `symbol_states` (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());
+        let num_symbols = self.symbol_states.len();
+        debug_assert!(num_symbols >= snapshot.symbol_states.len());
 
         // Restore the current visible-definitions state to the given snapshot.
-        self.definitions_by_symbol = snapshot.definitions_by_symbol;
+        self.symbol_states = snapshot.symbol_states;
 
         // 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".
-        self.definitions_by_symbol
-            .resize(num_symbols, SymbolState::unbound());
+        // snapshot, the correct state to fill them in with is "undefined".
+        self.symbol_states
+            .resize(num_symbols, SymbolState::undefined());
     }
 
     /// 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.
+    /// path to get here. The new 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.
-
-        // We never remove symbols from `definitions_by_symbol` (it's an IndexVec, and the symbol
+        // We never remove symbols from `symbol_states` (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());
+        debug_assert!(self.symbol_states.len() >= snapshot.symbol_states.len());
 
-        let mut snapshot_definitions_iter = snapshot.definitions_by_symbol.into_iter();
-        for current in &mut self.definitions_by_symbol {
+        let mut snapshot_definitions_iter = snapshot.symbol_states.into_iter();
+        for current in &mut self.symbol_states {
             if let Some(snapshot) = snapshot_definitions_iter.next() {
                 current.merge(snapshot);
             } else {
-                // Symbol not present in snapshot, so it's unbound from that path.
-                current.add_unbound();
+                // Symbol not present in snapshot, so it's unbound/undeclared from that path.
+                current.set_may_be_unbound();
+                current.set_may_be_undeclared();
             }
         }
     }
@@ -362,14 +560,16 @@ impl<'db> UseDefMapBuilder<'db> {
     pub(super) fn finish(mut self) -> UseDefMap<'db> {
         self.all_definitions.shrink_to_fit();
         self.all_constraints.shrink_to_fit();
-        self.definitions_by_symbol.shrink_to_fit();
-        self.definitions_by_use.shrink_to_fit();
+        self.symbol_states.shrink_to_fit();
+        self.bindings_by_use.shrink_to_fit();
+        self.definitions_by_definition.shrink_to_fit();
 
         UseDefMap {
             all_definitions: self.all_definitions,
             all_constraints: self.all_constraints,
-            definitions_by_use: self.definitions_by_use,
-            public_definitions: self.definitions_by_symbol,
+            bindings_by_use: self.bindings_by_use,
+            public_symbols: self.symbol_states,
+            definitions_by_definition: self.definitions_by_definition,
         }
     }
 }

crates/red_knot_python_semantic/src/semantic_index/use_def/bitset.rs

@@ -32,17 +32,25 @@ impl<const B: usize> BitSet<B> {
         bitset
     }
 
+    pub(super) fn is_empty(&self) -> bool {
+        self.blocks().iter().all(|&b| b == 0)
+    }
+
     /// Convert from Inline to Heap, if needed, and resize the Heap vector, if needed.
     fn resize(&mut self, value: u32) {
         let num_blocks_needed = (value / 64) + 1;
+        self.resize_blocks(num_blocks_needed as usize);
+    }
+
+    fn resize_blocks(&mut self, num_blocks_needed: usize) {
         match self {
             Self::Inline(blocks) => {
                 let mut vec = blocks.to_vec();
-                vec.resize(num_blocks_needed as usize, 0);
+                vec.resize(num_blocks_needed, 0);
                 *self = Self::Heap(vec);
             }
             Self::Heap(vec) => {
-                vec.resize(num_blocks_needed as usize, 0);
+                vec.resize(num_blocks_needed, 0);
             }
         }
     }
@@ -89,6 +97,19 @@ impl<const B: usize> BitSet<B> {
         }
     }
 
+    /// Union in-place with another [`BitSet`].
+    pub(super) fn union(&mut self, other: &BitSet<B>) {
+        let mut max_len = self.blocks().len();
+        let other_len = other.blocks().len();
+        if other_len > max_len {
+            max_len = other_len;
+            self.resize_blocks(max_len);
+        }
+        for (my_block, other_block) in self.blocks_mut().iter_mut().zip(other.blocks()) {
+            *my_block |= other_block;
+        }
+    }
+
     /// Return an iterator over the values (in ascending order) in this [`BitSet`].
     pub(super) fn iter(&self) -> BitSetIterator<'_, B> {
         let blocks = self.blocks();
@@ -218,6 +239,59 @@ mod tests {
         assert_bitset(&b1, &[89]);
     }
 
+    #[test]
+    fn union() {
+        let mut b1 = BitSet::<1>::with(2);
+        let b2 = BitSet::<1>::with(4);
+
+        b1.union(&b2);
+        assert_bitset(&b1, &[2, 4]);
+    }
+
+    #[test]
+    fn union_mixed_1() {
+        let mut b1 = BitSet::<1>::with(4);
+        let mut b2 = BitSet::<1>::with(4);
+        b1.insert(89);
+        b2.insert(5);
+
+        b1.union(&b2);
+        assert_bitset(&b1, &[4, 5, 89]);
+    }
+
+    #[test]
+    fn union_mixed_2() {
+        let mut b1 = BitSet::<1>::with(4);
+        let mut b2 = BitSet::<1>::with(4);
+        b1.insert(23);
+        b2.insert(89);
+
+        b1.union(&b2);
+        assert_bitset(&b1, &[4, 23, 89]);
+    }
+
+    #[test]
+    fn union_heap() {
+        let mut b1 = BitSet::<1>::with(4);
+        let mut b2 = BitSet::<1>::with(4);
+        b1.insert(89);
+        b2.insert(90);
+
+        b1.union(&b2);
+        assert_bitset(&b1, &[4, 89, 90]);
+    }
+
+    #[test]
+    fn union_heap_2() {
+        let mut b1 = BitSet::<1>::with(89);
+        let mut b2 = BitSet::<1>::with(89);
+        b1.insert(91);
+        b2.insert(90);
+
+        b1.union(&b2);
+        assert_bitset(&b1, &[89, 90, 91]);
+    }
+
     #[test]
     fn multiple_blocks() {
         let mut b = BitSet::<2>::with(120);
@@ -225,4 +299,11 @@ mod tests {
         assert!(matches!(b, BitSet::Inline(_)));
         assert_bitset(&b, &[45, 120]);
     }
+
+    #[test]
+    fn empty() {
+        let b = BitSet::<1>::default();
+
+        assert!(b.is_empty());
+    }
 }

crates/red_knot_python_semantic/src/semantic_index/use_def/symbol_state.rs

@@ -1,13 +1,13 @@
-//! Track visible definitions of a symbol, and applicable constraints per definition.
+//! Track live bindings per symbol, applicable constraints per binding, and live declarations.
 //!
 //! These data structures operate entirely on scope-local newtype-indices for definitions and
 //! constraints, referring to their location in the `all_definitions` and `all_constraints`
 //! indexvecs in [`super::UseDefMapBuilder`].
 //!
-//! We need to track arbitrary associations between definitions and constraints, not just a single
-//! set of currently dominating constraints (where "dominating" means "control flow must have
-//! passed through it to reach this point"), because we can have dominating constraints that apply
-//! to some definitions but not others, as in this code:
+//! We need to track arbitrary associations between bindings and constraints, not just a single set
+//! of currently dominating constraints (where "dominating" means "control flow must have passed
+//! through it to reach this point"), because we can have dominating constraints that apply to some
+//! bindings but not others, as in this code:
 //!
 //! ```python
 //! x = 1 if flag else None
@@ -18,11 +18,11 @@
 //! ```
 //!
 //! The `x is not None` constraint dominates the final use of `x`, but it applies only to the first
-//! definition of `x`, not the second, so `None` is a possible value for `x`.
+//! binding of `x`, not the second, so `None` is a possible value for `x`.
 //!
-//! And we can't just track, for each definition, an index into a list of dominating constraints,
-//! either, because we can have definitions which are still visible, but subject to constraints
-//! that are no longer dominating, as in this code:
+//! And we can't just track, for each binding, an index into a list of dominating constraints,
+//! either, because we can have bindings which are still visible, but subject to constraints that
+//! are no longer dominating, as in this code:
 //!
 //! ```python
 //! x = 0
@@ -33,13 +33,16 @@
 //! ```
 //!
 //! From the point of view of the final use of `x`, the `x is not None` constraint no longer
-//! dominates, but it does dominate the `x = 1 if flag2 else None` definition, so we have to keep
+//! dominates, but it does dominate the `x = 1 if flag2 else None` binding, so we have to keep
 //! track of that.
 //!
 //! The data structures used here ([`BitSet`] and [`smallvec::SmallVec`]) optimize for keeping all
 //! data inline (avoiding lots of scattered allocations) in small-to-medium cases, and falling back
-//! to heap allocation to be able to scale to arbitrary numbers of definitions and constraints when
-//! needed.
+//! to heap allocation to be able to scale to arbitrary numbers of live bindings and constraints
+//! when needed.
+//!
+//! Tracking live declarations is simpler, since constraints are not involved, but otherwise very
+//! similar to tracking live bindings.
 use super::bitset::{BitSet, BitSetIterator};
 use ruff_index::newtype_index;
 use smallvec::SmallVec;
@@ -53,93 +56,200 @@ pub(super) struct ScopedDefinitionId;
 pub(super) struct ScopedConstraintId;
 
 /// Can reference this * 64 total definitions inline; more will fall back to the heap.
-const INLINE_DEFINITION_BLOCKS: usize = 3;
+const INLINE_BINDING_BLOCKS: usize = 3;
 
-/// A [`BitSet`] of [`ScopedDefinitionId`], representing visible definitions of a symbol in a scope.
-type Definitions = BitSet<INLINE_DEFINITION_BLOCKS>;
-type DefinitionsIterator<'a> = BitSetIterator<'a, INLINE_DEFINITION_BLOCKS>;
+/// A [`BitSet`] of [`ScopedDefinitionId`], representing live bindings of a symbol in a scope.
+type Bindings = BitSet<INLINE_BINDING_BLOCKS>;
+type BindingsIterator<'a> = BitSetIterator<'a, INLINE_BINDING_BLOCKS>;
+
+/// Can reference this * 64 total declarations inline; more will fall back to the heap.
+const INLINE_DECLARATION_BLOCKS: usize = 3;
+
+/// A [`BitSet`] of [`ScopedDefinitionId`], representing live declarations of a symbol in a scope.
+type Declarations = BitSet<INLINE_DECLARATION_BLOCKS>;
+type DeclarationsIterator<'a> = BitSetIterator<'a, INLINE_DECLARATION_BLOCKS>;
 
 /// Can reference this * 64 total constraints inline; more will fall back to the heap.
 const INLINE_CONSTRAINT_BLOCKS: usize = 2;
 
-/// Can keep inline this many visible definitions per symbol at a given time; more will go to heap.
-const INLINE_VISIBLE_DEFINITIONS_PER_SYMBOL: usize = 4;
+/// Can keep inline this many live bindings per symbol at a given time; more will go to heap.
+const INLINE_BINDINGS_PER_SYMBOL: usize = 4;
 
-/// One [`BitSet`] of applicable [`ScopedConstraintId`] per visible definition.
-type InlineConstraintArray =
-    [BitSet<INLINE_CONSTRAINT_BLOCKS>; INLINE_VISIBLE_DEFINITIONS_PER_SYMBOL];
+/// One [`BitSet`] of applicable [`ScopedConstraintId`] per live binding.
+type InlineConstraintArray = [BitSet<INLINE_CONSTRAINT_BLOCKS>; INLINE_BINDINGS_PER_SYMBOL];
 type Constraints = SmallVec<InlineConstraintArray>;
 type ConstraintsIterator<'a> = std::slice::Iter<'a, BitSet<INLINE_CONSTRAINT_BLOCKS>>;
 type ConstraintsIntoIterator = smallvec::IntoIter<InlineConstraintArray>;
 
-/// Visible definitions and narrowing constraints for a single symbol at some point in control flow.
+/// Live declarations for a single symbol at some point in control flow.
 #[derive(Clone, Debug, PartialEq, Eq)]
-pub(super) struct SymbolState {
-    /// [`BitSet`]: which [`ScopedDefinitionId`] are visible for this symbol?
-    visible_definitions: Definitions,
+pub(super) struct SymbolDeclarations {
+    /// [`BitSet`]: which declarations (as [`ScopedDefinitionId`]) can reach the current location?
+    live_declarations: Declarations,
 
-    /// For each definition, which [`ScopedConstraintId`] apply?
+    /// Could the symbol be un-declared at this point?
+    may_be_undeclared: bool,
+}
+
+impl SymbolDeclarations {
+    fn undeclared() -> Self {
+        Self {
+            live_declarations: Declarations::default(),
+            may_be_undeclared: true,
+        }
+    }
+
+    /// Record a newly-encountered declaration for this symbol.
+    fn record_declaration(&mut self, declaration_id: ScopedDefinitionId) {
+        self.live_declarations = Declarations::with(declaration_id.into());
+        self.may_be_undeclared = false;
+    }
+
+    /// Add undeclared as a possibility for this symbol.
+    fn set_may_be_undeclared(&mut self) {
+        self.may_be_undeclared = true;
+    }
+
+    /// Return an iterator over live declarations for this symbol.
+    pub(super) fn iter(&self) -> DeclarationIdIterator {
+        DeclarationIdIterator {
+            inner: self.live_declarations.iter(),
+        }
+    }
+
+    pub(super) fn is_empty(&self) -> bool {
+        self.live_declarations.is_empty()
+    }
+
+    pub(super) fn may_be_undeclared(&self) -> bool {
+        self.may_be_undeclared
+    }
+}
+
+/// Live bindings and narrowing constraints for a single symbol at some point in control flow.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(super) struct SymbolBindings {
+    /// [`BitSet`]: which bindings (as [`ScopedDefinitionId`]) can reach the current location?
+    live_bindings: Bindings,
+
+    /// For each live binding, which [`ScopedConstraintId`] apply?
     ///
     /// This is a [`smallvec::SmallVec`] which should always have one [`BitSet`] of constraints per
-    /// definition in `visible_definitions`.
+    /// binding in `live_bindings`.
     constraints: Constraints,
 
     /// Could the symbol be unbound at this point?
     may_be_unbound: bool,
 }
 
-/// A single [`ScopedDefinitionId`] with an iterator of its applicable [`ScopedConstraintId`].
-#[derive(Debug)]
-pub(super) struct DefinitionIdWithConstraints<'a> {
-    pub(super) definition: ScopedDefinitionId,
-    pub(super) constraint_ids: ConstraintIdIterator<'a>,
-}
-
-impl SymbolState {
-    /// Return a new [`SymbolState`] representing an unbound symbol.
-    pub(super) fn unbound() -> Self {
+impl SymbolBindings {
+    fn unbound() -> Self {
         Self {
-            visible_definitions: Definitions::default(),
+            live_bindings: Bindings::default(),
             constraints: Constraints::default(),
             may_be_unbound: true,
         }
     }
 
-    /// Return a new [`SymbolState`] representing a symbol with a single visible definition.
-    pub(super) fn with(definition_id: ScopedDefinitionId) -> Self {
-        let mut constraints = Constraints::with_capacity(1);
-        constraints.push(BitSet::default());
-        Self {
-            visible_definitions: Definitions::with(definition_id.into()),
-            constraints,
-            may_be_unbound: false,
-        }
-    }
-
     /// Add Unbound as a possibility for this symbol.
-    pub(super) fn add_unbound(&mut self) {
+    fn set_may_be_unbound(&mut self) {
         self.may_be_unbound = true;
     }
 
-    /// Add given constraint to all currently-visible definitions.
-    pub(super) fn add_constraint(&mut self, constraint_id: ScopedConstraintId) {
+    /// Record a newly-encountered binding for this symbol.
+    pub(super) fn record_binding(&mut self, binding_id: ScopedDefinitionId) {
+        // The new binding replaces all previous live bindings in this path, and has no
+        // constraints.
+        self.live_bindings = Bindings::with(binding_id.into());
+        self.constraints = Constraints::with_capacity(1);
+        self.constraints.push(BitSet::default());
+        self.may_be_unbound = false;
+    }
+
+    /// Add given constraint to all live bindings.
+    pub(super) fn record_constraint(&mut self, constraint_id: ScopedConstraintId) {
         for bitset in &mut self.constraints {
             bitset.insert(constraint_id.into());
         }
     }
 
+    /// Iterate over currently live bindings for this symbol.
+    pub(super) fn iter(&self) -> BindingIdWithConstraintsIterator {
+        BindingIdWithConstraintsIterator {
+            definitions: self.live_bindings.iter(),
+            constraints: self.constraints.iter(),
+        }
+    }
+
+    pub(super) fn may_be_unbound(&self) -> bool {
+        self.may_be_unbound
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(super) struct SymbolState {
+    declarations: SymbolDeclarations,
+    bindings: SymbolBindings,
+}
+
+impl SymbolState {
+    /// Return a new [`SymbolState`] representing an unbound, undeclared symbol.
+    pub(super) fn undefined() -> Self {
+        Self {
+            declarations: SymbolDeclarations::undeclared(),
+            bindings: SymbolBindings::unbound(),
+        }
+    }
+
+    /// Add Unbound as a possibility for this symbol.
+    pub(super) fn set_may_be_unbound(&mut self) {
+        self.bindings.set_may_be_unbound();
+    }
+
+    /// Record a newly-encountered binding for this symbol.
+    pub(super) fn record_binding(&mut self, binding_id: ScopedDefinitionId) {
+        self.bindings.record_binding(binding_id);
+    }
+
+    /// Add given constraint to all live bindings.
+    pub(super) fn record_constraint(&mut self, constraint_id: ScopedConstraintId) {
+        self.bindings.record_constraint(constraint_id);
+    }
+
+    /// Add undeclared as a possibility for this symbol.
+    pub(super) fn set_may_be_undeclared(&mut self) {
+        self.declarations.set_may_be_undeclared();
+    }
+
+    /// Record a newly-encountered declaration of this symbol.
+    pub(super) fn record_declaration(&mut self, declaration_id: ScopedDefinitionId) {
+        self.declarations.record_declaration(declaration_id);
+    }
+
     /// Merge another [`SymbolState`] into this one.
     pub(super) fn merge(&mut self, b: SymbolState) {
         let mut a = Self {
-            visible_definitions: Definitions::default(),
-            constraints: Constraints::default(),
-            may_be_unbound: self.may_be_unbound || b.may_be_unbound,
+            bindings: SymbolBindings {
+                live_bindings: Bindings::default(),
+                constraints: Constraints::default(),
+                may_be_unbound: self.bindings.may_be_unbound || b.bindings.may_be_unbound,
+            },
+            declarations: SymbolDeclarations {
+                live_declarations: self.declarations.live_declarations.clone(),
+                may_be_undeclared: self.declarations.may_be_undeclared
+                    || b.declarations.may_be_undeclared,
+            },
         };
+
         std::mem::swap(&mut a, self);
-        let mut a_defs_iter = a.visible_definitions.iter();
-        let mut b_defs_iter = b.visible_definitions.iter();
-        let mut a_constraints_iter = a.constraints.into_iter();
-        let mut b_constraints_iter = b.constraints.into_iter();
+        self.declarations
+            .live_declarations
+            .union(&b.declarations.live_declarations);
+
+        let mut a_defs_iter = a.bindings.live_bindings.iter();
+        let mut b_defs_iter = b.bindings.live_bindings.iter();
+        let mut a_constraints_iter = a.bindings.constraints.into_iter();
+        let mut b_constraints_iter = b.bindings.constraints.into_iter();
 
         let mut opt_a_def: Option<u32> = a_defs_iter.next();
         let mut opt_b_def: Option<u32> = b_defs_iter.next();
@@ -152,7 +262,7 @@ impl SymbolState {
 
         // Helper to push `def`, with constraints in `constraints_iter`, onto `self`.
         let push = |def, constraints_iter: &mut ConstraintsIntoIterator, merged: &mut Self| {
-            merged.visible_definitions.insert(def);
+            merged.bindings.live_bindings.insert(def);
             // SAFETY: we only ever create SymbolState with either no definitions and no constraint
             // bitsets (`::unbound`) or one definition and one constraint bitset (`::with`), and
             // `::merge` always pushes one definition and one constraint bitset together (just
@@ -161,7 +271,7 @@ impl SymbolState {
             let constraints = constraints_iter
                 .next()
                 .expect("definitions and constraints length mismatch");
-            merged.constraints.push(constraints);
+            merged.bindings.constraints.push(constraints);
         };
 
         loop {
@@ -191,7 +301,8 @@ impl SymbolState {
                         // If the same definition is visible through both paths, any constraint
                         // that applies on only one path is irrelevant to the resulting type from
                         // unioning the two paths, so we intersect the constraints.
-                        self.constraints
+                        self.bindings
+                            .constraints
                             .last_mut()
                             .unwrap()
                             .intersect(&a_constraints);
@@ -214,40 +325,49 @@ impl SymbolState {
         }
     }
 
-    /// Get iterator over visible definitions with constraints.
-    pub(super) fn visible_definitions(&self) -> DefinitionIdWithConstraintsIterator {
-        DefinitionIdWithConstraintsIterator {
-            definitions: self.visible_definitions.iter(),
-            constraints: self.constraints.iter(),
-        }
+    pub(super) fn bindings(&self) -> &SymbolBindings {
+        &self.bindings
+    }
+
+    pub(super) fn declarations(&self) -> &SymbolDeclarations {
+        &self.declarations
     }
 
     /// Could the symbol be unbound?
     pub(super) fn may_be_unbound(&self) -> bool {
-        self.may_be_unbound
+        self.bindings.may_be_unbound()
     }
 }
 
-/// The default state of a symbol (if we've seen no definitions of it) is unbound.
+/// The default state of a symbol, if we've seen no definitions of it, is undefined (that is,
+/// both unbound and undeclared).
 impl Default for SymbolState {
     fn default() -> Self {
-        SymbolState::unbound()
+        SymbolState::undefined()
     }
 }
 
+/// A single binding (as [`ScopedDefinitionId`]) with an iterator of its applicable
+/// [`ScopedConstraintId`].
+#[derive(Debug)]
+pub(super) struct BindingIdWithConstraints<'a> {
+    pub(super) definition: ScopedDefinitionId,
+    pub(super) constraint_ids: ConstraintIdIterator<'a>,
+}
+
 #[derive(Debug)]
-pub(super) struct DefinitionIdWithConstraintsIterator<'a> {
-    definitions: DefinitionsIterator<'a>,
+pub(super) struct BindingIdWithConstraintsIterator<'a> {
+    definitions: BindingsIterator<'a>,
     constraints: ConstraintsIterator<'a>,
 }
 
-impl<'a> Iterator for DefinitionIdWithConstraintsIterator<'a> {
-    type Item = DefinitionIdWithConstraints<'a>;
+impl<'a> Iterator for BindingIdWithConstraintsIterator<'a> {
+    type Item = BindingIdWithConstraints<'a>;
 
     fn next(&mut self) -> Option<Self::Item> {
         match (self.definitions.next(), self.constraints.next()) {
             (None, None) => None,
-            (Some(def), Some(constraints)) => Some(DefinitionIdWithConstraints {
+            (Some(def), Some(constraints)) => Some(BindingIdWithConstraints {
                 definition: ScopedDefinitionId::from_u32(def),
                 constraint_ids: ConstraintIdIterator {
                     wrapped: constraints.iter(),
@@ -259,7 +379,7 @@ impl<'a> Iterator for DefinitionIdWithConstraintsIterator<'a> {
     }
 }
 
-impl std::iter::FusedIterator for DefinitionIdWithConstraintsIterator<'_> {}
+impl std::iter::FusedIterator for BindingIdWithConstraintsIterator<'_> {}
 
 #[derive(Debug)]
 pub(super) struct ConstraintIdIterator<'a> {
@@ -276,99 +396,193 @@ impl Iterator for ConstraintIdIterator<'_> {
 
 impl std::iter::FusedIterator for ConstraintIdIterator<'_> {}
 
+#[derive(Debug)]
+pub(super) struct DeclarationIdIterator<'a> {
+    inner: DeclarationsIterator<'a>,
+}
+
+impl<'a> Iterator for DeclarationIdIterator<'a> {
+    type Item = ScopedDefinitionId;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        self.inner.next().map(ScopedDefinitionId::from_u32)
+    }
+}
+
+impl std::iter::FusedIterator for DeclarationIdIterator<'_> {}
+
 #[cfg(test)]
 mod tests {
     use super::{ScopedConstraintId, ScopedDefinitionId, SymbolState};
 
-    impl SymbolState {
-        pub(crate) fn assert(&self, may_be_unbound: bool, expected: &[&str]) {
-            assert_eq!(self.may_be_unbound(), may_be_unbound);
-            let actual = self
-                .visible_definitions()
-                .map(|def_id_with_constraints| {
-                    format!(
-                        "{}<{}>",
-                        def_id_with_constraints.definition.as_u32(),
-                        def_id_with_constraints
-                            .constraint_ids
-                            .map(ScopedConstraintId::as_u32)
-                            .map(|idx| idx.to_string())
-                            .collect::<Vec<_>>()
-                            .join(", ")
-                    )
-                })
-                .collect::<Vec<_>>();
-            assert_eq!(actual, expected);
-        }
+    fn assert_bindings(symbol: &SymbolState, may_be_unbound: bool, expected: &[&str]) {
+        assert_eq!(symbol.may_be_unbound(), may_be_unbound);
+        let actual = symbol
+            .bindings()
+            .iter()
+            .map(|def_id_with_constraints| {
+                format!(
+                    "{}<{}>",
+                    def_id_with_constraints.definition.as_u32(),
+                    def_id_with_constraints
+                        .constraint_ids
+                        .map(ScopedConstraintId::as_u32)
+                        .map(|idx| idx.to_string())
+                        .collect::<Vec<_>>()
+                        .join(", ")
+                )
+            })
+            .collect::<Vec<_>>();
+        assert_eq!(actual, expected);
+    }
+
+    pub(crate) fn assert_declarations(
+        symbol: &SymbolState,
+        may_be_undeclared: bool,
+        expected: &[u32],
+    ) {
+        assert_eq!(symbol.declarations.may_be_undeclared(), may_be_undeclared);
+        let actual = symbol
+            .declarations()
+            .iter()
+            .map(ScopedDefinitionId::as_u32)
+            .collect::<Vec<_>>();
+        assert_eq!(actual, expected);
     }
 
     #[test]
     fn unbound() {
-        let cd = SymbolState::unbound();
+        let sym = SymbolState::undefined();
 
-        cd.assert(true, &[]);
+        assert_bindings(&sym, true, &[]);
     }
 
     #[test]
     fn with() {
-        let cd = SymbolState::with(ScopedDefinitionId::from_u32(0));
+        let mut sym = SymbolState::undefined();
+        sym.record_binding(ScopedDefinitionId::from_u32(0));
 
-        cd.assert(false, &["0<>"]);
+        assert_bindings(&sym, false, &["0<>"]);
     }
 
     #[test]
-    fn add_unbound() {
-        let mut cd = SymbolState::with(ScopedDefinitionId::from_u32(0));
-        cd.add_unbound();
+    fn set_may_be_unbound() {
+        let mut sym = SymbolState::undefined();
+        sym.record_binding(ScopedDefinitionId::from_u32(0));
+        sym.set_may_be_unbound();
 
-        cd.assert(true, &["0<>"]);
+        assert_bindings(&sym, true, &["0<>"]);
     }
 
     #[test]
-    fn add_constraint() {
-        let mut cd = SymbolState::with(ScopedDefinitionId::from_u32(0));
-        cd.add_constraint(ScopedConstraintId::from_u32(0));
+    fn record_constraint() {
+        let mut sym = SymbolState::undefined();
+        sym.record_binding(ScopedDefinitionId::from_u32(0));
+        sym.record_constraint(ScopedConstraintId::from_u32(0));
 
-        cd.assert(false, &["0<0>"]);
+        assert_bindings(&sym, false, &["0<0>"]);
     }
 
     #[test]
     fn merge() {
         // merging the same definition with the same constraint keeps the constraint
-        let mut cd0a = SymbolState::with(ScopedDefinitionId::from_u32(0));
-        cd0a.add_constraint(ScopedConstraintId::from_u32(0));
+        let mut sym0a = SymbolState::undefined();
+        sym0a.record_binding(ScopedDefinitionId::from_u32(0));
+        sym0a.record_constraint(ScopedConstraintId::from_u32(0));
 
-        let mut cd0b = SymbolState::with(ScopedDefinitionId::from_u32(0));
-        cd0b.add_constraint(ScopedConstraintId::from_u32(0));
+        let mut sym0b = SymbolState::undefined();
+        sym0b.record_binding(ScopedDefinitionId::from_u32(0));
+        sym0b.record_constraint(ScopedConstraintId::from_u32(0));
 
-        cd0a.merge(cd0b);
-        let mut cd0 = cd0a;
-        cd0.assert(false, &["0<0>"]);
+        sym0a.merge(sym0b);
+        let mut sym0 = sym0a;
+        assert_bindings(&sym0, false, &["0<0>"]);
 
         // merging the same definition with differing constraints drops all constraints
-        let mut cd1a = SymbolState::with(ScopedDefinitionId::from_u32(1));
-        cd1a.add_constraint(ScopedConstraintId::from_u32(1));
+        let mut sym1a = SymbolState::undefined();
+        sym1a.record_binding(ScopedDefinitionId::from_u32(1));
+        sym1a.record_constraint(ScopedConstraintId::from_u32(1));
 
-        let mut cd1b = SymbolState::with(ScopedDefinitionId::from_u32(1));
-        cd1b.add_constraint(ScopedConstraintId::from_u32(2));
+        let mut sym1b = SymbolState::undefined();
+        sym1b.record_binding(ScopedDefinitionId::from_u32(1));
+        sym1b.record_constraint(ScopedConstraintId::from_u32(2));
 
-        cd1a.merge(cd1b);
-        let cd1 = cd1a;
-        cd1.assert(false, &["1<>"]);
+        sym1a.merge(sym1b);
+        let sym1 = sym1a;
+        assert_bindings(&sym1, false, &["1<>"]);
 
         // merging a constrained definition with unbound keeps both
-        let mut cd2a = SymbolState::with(ScopedDefinitionId::from_u32(2));
-        cd2a.add_constraint(ScopedConstraintId::from_u32(3));
+        let mut sym2a = SymbolState::undefined();
+        sym2a.record_binding(ScopedDefinitionId::from_u32(2));
+        sym2a.record_constraint(ScopedConstraintId::from_u32(3));
 
-        let cd2b = SymbolState::unbound();
+        let sym2b = SymbolState::undefined();
 
-        cd2a.merge(cd2b);
-        let cd2 = cd2a;
-        cd2.assert(true, &["2<3>"]);
+        sym2a.merge(sym2b);
+        let sym2 = sym2a;
+        assert_bindings(&sym2, true, &["2<3>"]);
 
         // merging different definitions keeps them each with their existing constraints
-        cd0.merge(cd2);
-        let cd = cd0;
-        cd.assert(true, &["0<0>", "2<3>"]);
+        sym0.merge(sym2);
+        let sym = sym0;
+        assert_bindings(&sym, true, &["0<0>", "2<3>"]);
+    }
+
+    #[test]
+    fn no_declaration() {
+        let sym = SymbolState::undefined();
+
+        assert_declarations(&sym, true, &[]);
+    }
+
+    #[test]
+    fn record_declaration() {
+        let mut sym = SymbolState::undefined();
+        sym.record_declaration(ScopedDefinitionId::from_u32(1));
+
+        assert_declarations(&sym, false, &[1]);
+    }
+
+    #[test]
+    fn record_declaration_override() {
+        let mut sym = SymbolState::undefined();
+        sym.record_declaration(ScopedDefinitionId::from_u32(1));
+        sym.record_declaration(ScopedDefinitionId::from_u32(2));
+
+        assert_declarations(&sym, false, &[2]);
+    }
+
+    #[test]
+    fn record_declaration_merge() {
+        let mut sym = SymbolState::undefined();
+        sym.record_declaration(ScopedDefinitionId::from_u32(1));
+
+        let mut sym2 = SymbolState::undefined();
+        sym2.record_declaration(ScopedDefinitionId::from_u32(2));
+
+        sym.merge(sym2);
+
+        assert_declarations(&sym, false, &[1, 2]);
+    }
+
+    #[test]
+    fn record_declaration_merge_partial_undeclared() {
+        let mut sym = SymbolState::undefined();
+        sym.record_declaration(ScopedDefinitionId::from_u32(1));
+
+        let sym2 = SymbolState::undefined();
+
+        sym.merge(sym2);
+
+        assert_declarations(&sym, true, &[1]);
+    }
+
+    #[test]
+    fn set_may_be_undeclared() {
+        let mut sym = SymbolState::undefined();
+        sym.record_declaration(ScopedDefinitionId::from_u32(0));
+        sym.set_may_be_undeclared();
+
+        assert_declarations(&sym, true, &[0]);
     }
 }

crates/red_knot_python_semantic/src/semantic_model.rs

@@ -8,7 +8,7 @@ use crate::module_name::ModuleName;
 use crate::module_resolver::{resolve_module, Module};
 use crate::semantic_index::ast_ids::HasScopedAstId;
 use crate::semantic_index::semantic_index;
-use crate::types::{definition_ty, global_symbol_ty, infer_scope_types, Type};
+use crate::types::{binding_ty, global_symbol_ty, infer_scope_types, Type};
 use crate::Db;
 
 pub struct SemanticModel<'db> {
@@ -147,24 +147,24 @@ impl HasTy for ast::Expr {
     }
 }
 
-macro_rules! impl_definition_has_ty {
+macro_rules! impl_binding_has_ty {
     ($ty: ty) => {
         impl HasTy for $ty {
             #[inline]
             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)
+                let binding = index.definition(self);
+                binding_ty(model.db, binding)
             }
         }
     };
 }
 
-impl_definition_has_ty!(ast::StmtFunctionDef);
-impl_definition_has_ty!(ast::StmtClassDef);
-impl_definition_has_ty!(ast::Alias);
-impl_definition_has_ty!(ast::Parameter);
-impl_definition_has_ty!(ast::ParameterWithDefault);
+impl_binding_has_ty!(ast::StmtFunctionDef);
+impl_binding_has_ty!(ast::StmtClassDef);
+impl_binding_has_ty!(ast::Alias);
+impl_binding_has_ty!(ast::Parameter);
+impl_binding_has_ty!(ast::ParameterWithDefault);
 
 #[cfg(test)]
 mod tests {

crates/red_knot_python_semantic/src/types.rs

@@ -1,13 +1,14 @@
-use infer::TypeInferenceBuilder;
+use infer::TypeInferenceContext;
 use ruff_db::files::File;
 use ruff_python_ast as ast;
 
+use crate::module_resolver::file_to_module;
 use crate::semantic_index::ast_ids::HasScopedAstId;
 use crate::semantic_index::definition::{Definition, DefinitionKind};
 use crate::semantic_index::symbol::{ScopeId, ScopedSymbolId};
 use crate::semantic_index::{
-    global_scope, semantic_index, symbol_table, use_def_map, DefinitionWithConstraints,
-    DefinitionWithConstraintsIterator,
+    global_scope, semantic_index, symbol_table, use_def_map, BindingWithConstraints,
+    BindingWithConstraintsIterator, DeclarationsIterator,
 };
 use crate::stdlib::{builtins_symbol_ty, types_symbol_ty, typeshed_symbol_ty};
 use crate::types::narrow::narrowing_constraint;
@@ -15,9 +16,9 @@ use crate::{Db, FxOrderSet};
 
 pub(crate) use self::builder::{IntersectionBuilder, UnionBuilder};
 pub(crate) use self::diagnostic::TypeCheckDiagnostics;
+pub(crate) use self::display::TypeArrayDisplay;
 pub(crate) use self::infer::{
     infer_deferred_types, infer_definition_types, infer_expression_types, infer_scope_types,
-    TypeInference,
 };
 
 mod builder;
@@ -41,25 +42,31 @@ pub fn check_types(db: &dyn Db, file: File) -> TypeCheckDiagnostics {
 }
 
 /// Infer the public type of a symbol (its type as seen from outside its scope).
-pub(crate) fn symbol_ty_by_id<'db>(
-    db: &'db dyn Db,
-    scope: ScopeId<'db>,
-    symbol: ScopedSymbolId,
-) -> Type<'db> {
-    let _span = tracing::trace_span!("symbol_ty", ?symbol).entered();
+fn symbol_ty_by_id<'db>(db: &'db dyn Db, scope: ScopeId<'db>, symbol: ScopedSymbolId) -> Type<'db> {
+    let _span = tracing::trace_span!("symbol_ty_by_id", ?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),
-    )
+
+    // If the symbol is declared, the public type is based on declarations; otherwise, it's based
+    // on inference from bindings.
+    if use_def.has_public_declarations(symbol) {
+        let declarations = use_def.public_declarations(symbol);
+        // Intentionally ignore conflicting declared types; that's not our problem, it's the
+        // problem of the module we are importing from.
+        declarations_ty(db, declarations).unwrap_or_else(|(ty, _)| ty)
+    } else {
+        bindings_ty(
+            db,
+            use_def.public_bindings(symbol),
+            use_def
+                .public_may_be_unbound(symbol)
+                .then_some(Type::Unbound),
+        )
+    }
 }
 
 /// Shorthand for `symbol_ty` that takes a symbol name instead of an ID.
-pub(crate) fn symbol_ty<'db>(db: &'db dyn Db, scope: ScopeId<'db>, name: &str) -> Type<'db> {
+fn symbol_ty<'db>(db: &'db dyn Db, scope: ScopeId<'db>, name: &str) -> Type<'db> {
     let table = symbol_table(db, scope);
     table
         .symbol_id_by_name(name)
@@ -72,17 +79,23 @@ pub(crate) fn global_symbol_ty<'db>(db: &'db dyn Db, file: File, name: &str) ->
     symbol_ty(db, global_scope(db, file), name)
 }
 
-/// Infer the type of a [`Definition`].
-pub(crate) fn definition_ty<'db>(db: &'db dyn Db, definition: Definition<'db>) -> Type<'db> {
+/// Infer the type of a binding.
+pub(crate) fn binding_ty<'db>(db: &'db dyn Db, definition: Definition<'db>) -> Type<'db> {
     let inference = infer_definition_types(db, definition);
-    inference.definition_ty(definition)
+    inference.binding_ty(definition)
+}
+
+/// Infer the type of a declaration.
+fn declaration_ty<'db>(db: &'db dyn Db, definition: Definition<'db>) -> Type<'db> {
+    let inference = infer_definition_types(db, definition);
+    inference.declaration_ty(definition)
 }
 
 /// Infer the type of a (possibly deferred) sub-expression of a [`Definition`].
 ///
 /// ## Panics
 /// If the given expression is not a sub-expression of the given [`Definition`].
-pub(crate) fn definition_expression_ty<'db>(
+fn definition_expression_ty<'db>(
     db: &'db dyn Db,
     definition: Definition<'db>,
     expression: &ast::Expr,
@@ -96,45 +109,45 @@ pub(crate) fn definition_expression_ty<'db>(
     }
 }
 
-/// Infer the combined type of an array of [`Definition`]s, plus one optional "unbound type".
+/// Infer the combined type of an iterator of bindings, plus one optional "unbound type".
 ///
-/// Will return a union if there is more than one definition, or at least one plus an unbound
+/// Will return a union if there is more than one binding, 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
+/// bindings 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>(
+/// Will panic if called with zero bindings and no `unbound_ty`. This is a logic error, as any
+/// symbol with zero visible bindings clearly may be unbound, and the caller should provide an
+/// `unbound_ty`.
+fn bindings_ty<'db>(
     db: &'db dyn Db,
-    definitions_with_constraints: DefinitionWithConstraintsIterator<'_, 'db>,
+    bindings_with_constraints: BindingWithConstraintsIterator<'_, 'db>,
     unbound_ty: Option<Type<'db>>,
 ) -> Type<'db> {
-    let def_types = definitions_with_constraints.map(
-        |DefinitionWithConstraints {
-             definition,
+    let def_types = bindings_with_constraints.map(
+        |BindingWithConstraints {
+             binding,
              constraints,
          }| {
             let mut constraint_tys =
-                constraints.filter_map(|test| narrowing_constraint(db, test, definition));
-            let definition_ty = definition_ty(db, definition);
+                constraints.filter_map(|constraint| narrowing_constraint(db, constraint, binding));
+            let binding_ty = binding_ty(db, binding);
             if let Some(first_constraint_ty) = constraint_tys.next() {
                 let mut builder = IntersectionBuilder::new(db);
                 builder = builder
-                    .add_positive(definition_ty)
+                    .add_positive(binding_ty)
                     .add_positive(first_constraint_ty);
                 for constraint_ty in constraint_tys {
                     builder = builder.add_positive(constraint_ty);
                 }
                 builder.build()
             } else {
-                definition_ty
+                binding_ty
             }
         },
     );
@@ -142,19 +155,69 @@ pub(crate) fn definitions_ty<'db>(
 
     let first = all_types
         .next()
-        .expect("definitions_ty should never be called with zero definitions and no unbound_ty.");
+        .expect("bindings_ty should never be called with zero definitions and no unbound_ty.");
 
     if let Some(second) = all_types.next() {
-        let mut builder = UnionBuilder::new(db);
-        builder = builder.add(first).add(second);
+        UnionType::from_elements(db, [first, second].into_iter().chain(all_types))
+    } else {
+        first
+    }
+}
 
-        for variant in all_types {
-            builder = builder.add(variant);
+/// The result of looking up a declared type from declarations; see [`declarations_ty`].
+type DeclaredTypeResult<'db> = Result<Type<'db>, (Type<'db>, Box<[Type<'db>]>)>;
+
+/// Build a declared type from a [`DeclarationsIterator`].
+///
+/// If there is only one declaration, or all declarations declare the same type, returns
+/// `Ok(declared_type)`. If there are conflicting declarations, returns
+/// `Err((union_of_declared_types, conflicting_declared_types))`.
+///
+/// If undeclared is a possibility, `Unknown` type will be part of the return type (and may
+/// conflict with other declarations.)
+///
+/// # Panics
+/// Will panic if there are no declarations and no possibility of undeclared. This is a logic
+/// error, as any symbol with zero live declarations clearly must be undeclared.
+fn declarations_ty<'db>(
+    db: &'db dyn Db,
+    declarations: DeclarationsIterator<'_, 'db>,
+) -> DeclaredTypeResult<'db> {
+    let may_be_undeclared = declarations.may_be_undeclared();
+    let decl_types = declarations.map(|declaration| declaration_ty(db, declaration));
+
+    let mut all_types = (if may_be_undeclared {
+        Some(Type::Unknown)
+    } else {
+        None
+    })
+    .into_iter()
+    .chain(decl_types);
+
+    let first = all_types.next().expect(
+        "declarations_ty must not be called with zero declarations and no may-be-undeclared.",
+    );
+
+    let mut conflicting: Vec<Type<'db>> = vec![];
+    let declared_ty = if let Some(second) = all_types.next() {
+        let mut builder = UnionBuilder::new(db).add(first);
+        for other in [second].into_iter().chain(all_types) {
+            if !first.is_equivalent_to(db, other) {
+                conflicting.push(other);
+            }
+            builder = builder.add(other);
         }
-
         builder.build()
     } else {
         first
+    };
+    if conflicting.is_empty() {
+        DeclaredTypeResult::Ok(declared_ty)
+    } else {
+        DeclaredTypeResult::Err((
+            declared_ty,
+            [first].into_iter().chain(conflicting).collect(),
+        ))
     }
 }
 
@@ -196,6 +259,9 @@ pub enum Type<'db> {
     LiteralString,
     /// A bytes literal
     BytesLiteral(BytesLiteralType<'db>),
+    /// A heterogeneous tuple type, with elements of the given types in source order.
+    // TODO: Support variable length homogeneous tuple type like `tuple[int, ...]`.
+    Tuple(TupleType<'db>),
     // TODO protocols, callable types, overloads, generics, type vars
 }
 
@@ -301,6 +367,48 @@ impl<'db> Type<'db> {
         }
     }
 
+    /// Return true if this type is [assignable to] type `target`.
+    ///
+    /// [assignable to]: https://typing.readthedocs.io/en/latest/spec/concepts.html#the-assignable-to-or-consistent-subtyping-relation
+    pub(crate) fn is_assignable_to(self, db: &'db dyn Db, target: Type<'db>) -> bool {
+        if self.is_equivalent_to(db, target) {
+            return true;
+        }
+        match (self, target) {
+            (Type::Unknown | Type::Any | Type::Never, _) => true,
+            (_, Type::Unknown | Type::Any) => true,
+            (Type::IntLiteral(_), Type::Instance(class))
+                if class.is_stdlib_symbol(db, "builtins", "int") =>
+            {
+                true
+            }
+            (Type::StringLiteral(_), Type::LiteralString) => true,
+            (Type::StringLiteral(_) | Type::LiteralString, Type::Instance(class))
+                if class.is_stdlib_symbol(db, "builtins", "str") =>
+            {
+                true
+            }
+            (Type::BytesLiteral(_), Type::Instance(class))
+                if class.is_stdlib_symbol(db, "builtins", "bytes") =>
+            {
+                true
+            }
+            (ty, Type::Union(union)) => union
+                .elements(db)
+                .iter()
+                .any(|&elem_ty| ty.is_assignable_to(db, elem_ty)),
+            // TODO
+            _ => false,
+        }
+    }
+
+    /// Return true if this type is equivalent to type `other`.
+    pub(crate) fn is_equivalent_to(self, _db: &'db dyn Db, other: Type<'db>) -> bool {
+        // TODO equivalent but not identical structural types, differently-ordered unions and
+        // intersections, other cases?
+        self == other
+    }
+
     /// Resolve a member access of a type.
     ///
     /// For example, if `foo` is `Type::Instance(<Bar>)`,
@@ -363,6 +471,10 @@ impl<'db> Type<'db> {
                 // TODO defer to Type::Instance(<bytes from typeshed>).member
                 Type::Unknown
             }
+            Type::Tuple(_) => {
+                // TODO: implement tuple methods
+                Type::Unknown
+            }
         }
     }
 
@@ -370,14 +482,14 @@ impl<'db> Type<'db> {
     ///
     /// Returns `None` if `self` is not a callable type.
     #[must_use]
-    pub fn call(&self, db: &'db dyn Db) -> Option<Type<'db>> {
+    fn call(&self, db: &'db dyn Db, _context: &mut TypeInferenceContext<'db>) -> Option<Type<'db>> {
         match self {
             Type::Function(function_type) => Some(function_type.return_type(db)),
 
             // TODO annotated return type on `__new__` or metaclass `__call__`
             Type::Class(class) => Some(Type::Instance(*class)),
 
-            // TODO: handle classes which implement the Callable protocol
+            // TODO: handle classes which implement `__call__`
             Type::Instance(_instance_ty) => Some(Type::Unknown),
 
             // `Any` is callable, and its return type is also `Any`.
@@ -385,7 +497,7 @@ impl<'db> Type<'db> {
 
             Type::Unknown => Some(Type::Unknown),
 
-            // TODO: union and intersection types, if they reduce to `Callable`
+            // TODO: union and intersection types
             Type::Union(_) => Some(Type::Unknown),
             Type::Intersection(_) => Some(Type::Unknown),
 
@@ -401,26 +513,32 @@ impl<'db> Type<'db> {
     /// for y in x:
     ///     pass
     /// ```
-    fn iterate(&self, db: &'db dyn Db) -> IterationOutcome<'db> {
+    /// Return None and emit a diagnostic if this type is not iterable.
+    fn iterate(
+        &self,
+        db: &'db dyn Db,
+        context: &mut TypeInferenceContext<'db>,
+    ) -> Option<Type<'db>> {
+        if let Type::Tuple(tuple_type) = self {
+            return Some(UnionType::from_elements(db, &**tuple_type.elements(db)));
+        }
+
         // `self` represents the type of the iterable;
         // `__iter__` and `__next__` are both looked up on the class of the iterable:
         let iterable_meta_type = self.to_meta_type(db);
 
         let dunder_iter_method = iterable_meta_type.member(db, "__iter__");
         if !dunder_iter_method.is_unbound() {
-            let Some(iterator_ty) = dunder_iter_method.call(db) else {
-                return IterationOutcome::NotIterable {
-                    not_iterable_ty: *self,
-                };
+            let Some(iterator_ty) = dunder_iter_method.call(db, context) else {
+                context.not_iterable_diagnostic(*self);
+                return None;
             };
 
             let dunder_next_method = iterator_ty.to_meta_type(db).member(db, "__next__");
-            return dunder_next_method
-                .call(db)
-                .map(|element_ty| IterationOutcome::Iterable { element_ty })
-                .unwrap_or(IterationOutcome::NotIterable {
-                    not_iterable_ty: *self,
-                });
+            return dunder_next_method.call(db, context).or_else(|| {
+                context.not_iterable_diagnostic(*self);
+                None
+            });
         }
 
         // Although it's not considered great practice,
@@ -431,21 +549,35 @@ impl<'db> Type<'db> {
         // accepting `int` or `SupportsIndex`
         let dunder_get_item_method = iterable_meta_type.member(db, "__getitem__");
 
-        dunder_get_item_method
-            .call(db)
-            .map(|element_ty| IterationOutcome::Iterable { element_ty })
-            .unwrap_or(IterationOutcome::NotIterable {
-                not_iterable_ty: *self,
-            })
+        dunder_get_item_method.call(db, context).or_else(|| {
+            context.not_iterable_diagnostic(*self);
+            None
+        })
     }
 
     #[must_use]
-    pub fn to_instance(&self) -> Type<'db> {
+    pub fn to_instance(&self, db: &'db dyn Db) -> Type<'db> {
         match self {
             Type::Any => Type::Any,
             Type::Unknown => Type::Unknown,
+            Type::Unbound => Type::Unknown,
+            Type::Never => Type::Never,
             Type::Class(class) => Type::Instance(*class),
-            _ => Type::Unknown, // TODO type errors
+            Type::Union(union) => union.map(db, |element| element.to_instance(db)),
+            // TODO: we can probably do better here: --Alex
+            Type::Intersection(_) => Type::Unknown,
+            // TODO: calling `.to_instance()` on any of these should result in a diagnostic,
+            // since they already indicate that the object is an instance of some kind:
+            Type::BooleanLiteral(_)
+            | Type::BytesLiteral(_)
+            | Type::Function(_)
+            | Type::Instance(_)
+            | Type::Module(_)
+            | Type::IntLiteral(_)
+            | Type::StringLiteral(_)
+            | Type::Tuple(_)
+            | Type::LiteralString
+            | Type::None => Type::Unknown,
         }
     }
 
@@ -474,29 +606,14 @@ impl<'db> Type<'db> {
             Type::Unknown => Type::Unknown,
             // TODO intersections
             Type::Intersection(_) => Type::Unknown,
+            Type::Tuple(_) => builtins_symbol_ty(db, "tuple"),
         }
     }
 }
 
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-enum IterationOutcome<'db> {
-    Iterable { element_ty: Type<'db> },
-    NotIterable { not_iterable_ty: Type<'db> },
-}
-
-impl<'db> IterationOutcome<'db> {
-    fn unwrap_with_diagnostic(
-        self,
-        iterable_node: ast::AnyNodeRef,
-        inference_builder: &mut TypeInferenceBuilder<'db>,
-    ) -> Type<'db> {
-        match self {
-            Self::Iterable { element_ty } => element_ty,
-            Self::NotIterable { not_iterable_ty } => {
-                inference_builder.not_iterable_diagnostic(iterable_node, not_iterable_ty);
-                Type::Unknown
-            }
-        }
+impl<'db> From<&Type<'db>> for Type<'db> {
+    fn from(value: &Type<'db>) -> Self {
+        *value
     }
 }
 
@@ -509,7 +626,7 @@ pub struct FunctionType<'db> {
     definition: Definition<'db>,
 
     /// types of all decorators on this function
-    decorators: Vec<Type<'db>>,
+    decorators: Box<[Type<'db>]>,
 }
 
 impl<'db> FunctionType<'db> {
@@ -520,7 +637,7 @@ impl<'db> FunctionType<'db> {
     /// inferred return type for this function
     pub fn return_type(&self, db: &'db dyn Db) -> Type<'db> {
         let definition = self.definition(db);
-        let DefinitionKind::Function(function_stmt_node) = definition.node(db) else {
+        let DefinitionKind::Function(function_stmt_node) = definition.kind(db) else {
             panic!("Function type definition must have `DefinitionKind::Function`")
         };
 
@@ -560,13 +677,21 @@ pub struct ClassType<'db> {
 }
 
 impl<'db> ClassType<'db> {
+    /// Return true if this class is a standard library type with given module name and name.
+    pub(crate) fn is_stdlib_symbol(self, db: &'db dyn Db, module_name: &str, name: &str) -> bool {
+        name == self.name(db)
+            && file_to_module(db, self.body_scope(db).file(db)).is_some_and(|module| {
+                module.search_path().is_standard_library() && module.name() == module_name
+            })
+    }
+
     /// Return an iterator over the types of this class's bases.
     ///
     /// # Panics:
     /// If `definition` is not a `DefinitionKind::Class`.
     pub fn bases(&self, db: &'db dyn Db) -> impl Iterator<Item = Type<'db>> {
         let definition = self.definition(db);
-        let DefinitionKind::Class(class_stmt_node) = definition.node(db) else {
+        let DefinitionKind::Class(class_stmt_node) = definition.kind(db) else {
             panic!("Class type definition must have DefinitionKind::Class");
         };
         class_stmt_node
@@ -617,19 +742,28 @@ impl<'db> UnionType<'db> {
         self.elements(db).contains(&ty)
     }
 
+    /// Create a union from a list of elements
+    /// (which may be eagerly simplified into a different variant of [`Type`] altogether)
+    pub fn from_elements<T: Into<Type<'db>>>(
+        db: &'db dyn Db,
+        elements: impl IntoIterator<Item = T>,
+    ) -> Type<'db> {
+        elements
+            .into_iter()
+            .fold(UnionBuilder::new(db), |builder, element| {
+                builder.add(element.into())
+            })
+            .build()
+    }
+
     /// Apply a transformation function to all elements of the union,
     /// and create a new union from the resulting set of types
     pub fn map(
         &self,
         db: &'db dyn Db,
-        mut transform_fn: impl FnMut(&Type<'db>) -> Type<'db>,
+        transform_fn: impl Fn(&Type<'db>) -> Type<'db>,
     ) -> Type<'db> {
-        self.elements(db)
-            .into_iter()
-            .fold(UnionBuilder::new(db), |builder, element| {
-                builder.add(transform_fn(element))
-            })
-            .build()
+        Self::from_elements(db, self.elements(db).into_iter().map(transform_fn))
     }
 }
 
@@ -660,29 +794,35 @@ pub struct BytesLiteralType<'db> {
     value: Box<[u8]>,
 }
 
+#[salsa::interned]
+pub struct TupleType<'db> {
+    #[return_ref]
+    elements: Box<[Type<'db>]>,
+}
+
 #[cfg(test)]
 mod tests {
-    use anyhow::Context;
-
-    use ruff_db::files::system_path_to_file;
-    use ruff_db::system::{DbWithTestSystem, SystemPathBuf};
-
+    use super::{builtins_symbol_ty, BytesLiteralType, StringLiteralType, Type, UnionType};
     use crate::db::tests::TestDb;
-    use crate::{Program, ProgramSettings, PythonVersion, SearchPathSettings};
-
-    use super::TypeCheckDiagnostics;
+    use crate::program::{Program, SearchPathSettings};
+    use crate::python_version::PythonVersion;
+    use crate::ProgramSettings;
+    use ruff_db::system::{DbWithTestSystem, SystemPathBuf};
+    use test_case::test_case;
 
     fn setup_db() -> TestDb {
         let db = TestDb::new();
+
+        let src_root = SystemPathBuf::from("/src");
         db.memory_file_system()
-            .create_directory_all("/src")
+            .create_directory_all(&src_root)
             .unwrap();
 
         Program::from_settings(
             &db,
             &ProgramSettings {
                 target_version: PythonVersion::default(),
-                search_paths: SearchPathSettings::new(SystemPathBuf::from("/src")),
+                search_paths: SearchPathSettings::new(src_root),
             },
         )
         .expect("Valid search path settings");
@@ -690,201 +830,75 @@ mod tests {
         db
     }
 
-    fn assert_diagnostic_messages(diagnostics: &TypeCheckDiagnostics, expected: &[&str]) {
-        let messages: Vec<&str> = diagnostics
-            .iter()
-            .map(|diagnostic| diagnostic.message())
-            .collect();
-        assert_eq!(&messages, expected);
+    /// A test representation of a type that can be transformed unambiguously into a real Type,
+    /// given a db.
+    #[derive(Debug)]
+    enum Ty {
+        Never,
+        Unknown,
+        Any,
+        IntLiteral(i64),
+        StringLiteral(&'static str),
+        LiteralString,
+        BytesLiteral(&'static str),
+        BuiltinInstance(&'static str),
+        Union(Vec<Ty>),
     }
 
-    #[test]
-    fn unresolved_import_statement() -> anyhow::Result<()> {
-        let mut db = setup_db();
-
-        db.write_file("src/foo.py", "import bar\n")
-            .context("Failed to write foo.py")?;
-
-        let foo = system_path_to_file(&db, "src/foo.py").context("Failed to resolve foo.py")?;
-
-        let diagnostics = super::check_types(&db, foo);
-        assert_diagnostic_messages(&diagnostics, &["Cannot resolve import 'bar'."]);
-
-        Ok(())
+    impl Ty {
+        fn into_type(self, db: &TestDb) -> Type<'_> {
+            match self {
+                Ty::Never => Type::Never,
+                Ty::Unknown => Type::Unknown,
+                Ty::Any => Type::Any,
+                Ty::IntLiteral(n) => Type::IntLiteral(n),
+                Ty::StringLiteral(s) => {
+                    Type::StringLiteral(StringLiteralType::new(db, (*s).into()))
+                }
+                Ty::LiteralString => Type::LiteralString,
+                Ty::BytesLiteral(s) => {
+                    Type::BytesLiteral(BytesLiteralType::new(db, s.as_bytes().into()))
+                }
+                Ty::BuiltinInstance(s) => builtins_symbol_ty(db, s).to_instance(db),
+                Ty::Union(tys) => {
+                    UnionType::from_elements(db, tys.into_iter().map(|ty| ty.into_type(db)))
+                }
+            }
+        }
     }
 
-    #[test]
-    fn unresolved_import_from_statement() {
-        let mut db = setup_db();
-
-        db.write_file("src/foo.py", "from bar import baz\n")
-            .unwrap();
-        let foo = system_path_to_file(&db, "src/foo.py").unwrap();
-        let diagnostics = super::check_types(&db, foo);
-        assert_diagnostic_messages(&diagnostics, &["Cannot resolve import 'bar'."]);
+    #[test_case(Ty::Unknown, Ty::IntLiteral(1))]
+    #[test_case(Ty::Any, Ty::IntLiteral(1))]
+    #[test_case(Ty::Never, Ty::IntLiteral(1))]
+    #[test_case(Ty::IntLiteral(1), Ty::Unknown)]
+    #[test_case(Ty::IntLiteral(1), Ty::Any)]
+    #[test_case(Ty::IntLiteral(1), Ty::BuiltinInstance("int"))]
+    #[test_case(Ty::StringLiteral("foo"), Ty::BuiltinInstance("str"))]
+    #[test_case(Ty::StringLiteral("foo"), Ty::LiteralString)]
+    #[test_case(Ty::LiteralString, Ty::BuiltinInstance("str"))]
+    #[test_case(Ty::BytesLiteral("foo"), Ty::BuiltinInstance("bytes"))]
+    #[test_case(Ty::IntLiteral(1), Ty::Union(vec![Ty::BuiltinInstance("int"), Ty::BuiltinInstance("str")]))]
+    #[test_case(Ty::IntLiteral(1), Ty::Union(vec![Ty::Unknown, Ty::BuiltinInstance("str")]))]
+    fn is_assignable_to(from: Ty, to: Ty) {
+        let db = setup_db();
+        assert!(from.into_type(&db).is_assignable_to(&db, to.into_type(&db)));
     }
 
-    #[test]
-    fn unresolved_import_from_resolved_module() {
-        let mut db = setup_db();
-
-        db.write_files([("/src/a.py", ""), ("/src/b.py", "from a import thing")])
-            .unwrap();
-
-        let b_file = system_path_to_file(&db, "/src/b.py").unwrap();
-        let b_file_diagnostics = super::check_types(&db, b_file);
-        assert_diagnostic_messages(&b_file_diagnostics, &["Module 'a' has no member 'thing'"]);
+    #[test_case(Ty::IntLiteral(1), Ty::BuiltinInstance("str"))]
+    #[test_case(Ty::BuiltinInstance("int"), Ty::BuiltinInstance("str"))]
+    #[test_case(Ty::BuiltinInstance("int"), Ty::IntLiteral(1))]
+    fn is_not_assignable_to(from: Ty, to: Ty) {
+        let db = setup_db();
+        assert!(!from.into_type(&db).is_assignable_to(&db, to.into_type(&db)));
     }
 
-    #[test]
-    fn resolved_import_of_symbol_from_unresolved_import() {
-        let mut db = setup_db();
+    #[test_case(
+        Ty::Union(vec![Ty::IntLiteral(1), Ty::IntLiteral(2)]),
+        Ty::Union(vec![Ty::IntLiteral(1), Ty::IntLiteral(2)])
+    )]
+    fn is_equivalent_to(from: Ty, to: Ty) {
+        let db = setup_db();
 
-        db.write_files([
-            ("/src/a.py", "import foo as foo"),
-            ("/src/b.py", "from a import foo"),
-        ])
-        .unwrap();
-
-        let a_file = system_path_to_file(&db, "/src/a.py").unwrap();
-        let a_file_diagnostics = super::check_types(&db, a_file);
-        assert_diagnostic_messages(&a_file_diagnostics, &["Cannot resolve import 'foo'."]);
-
-        // Importing the unresolved import into a second first-party file should not trigger
-        // an additional "unresolved import" violation
-        let b_file = system_path_to_file(&db, "/src/b.py").unwrap();
-        let b_file_diagnostics = super::check_types(&db, b_file);
-        assert_eq!(&*b_file_diagnostics, &[]);
-    }
-
-    #[test]
-    fn invalid_callable() {
-        let mut db = setup_db();
-
-        db.write_dedented(
-            "src/a.py",
-            "
-            nonsense = 123
-            x = nonsense()
-            ",
-        )
-        .unwrap();
-
-        let a_file = system_path_to_file(&db, "/src/a.py").unwrap();
-        let a_file_diagnostics = super::check_types(&db, a_file);
-        assert_diagnostic_messages(
-            &a_file_diagnostics,
-            &["Object of type 'Literal[123]' is not callable"],
-        );
-    }
-
-    #[test]
-    fn invalid_iterable() {
-        let mut db = setup_db();
-
-        db.write_dedented(
-            "src/a.py",
-            "
-            nonsense = 123
-            for x in nonsense:
-                pass
-            ",
-        )
-        .unwrap();
-
-        let a_file = system_path_to_file(&db, "/src/a.py").unwrap();
-        let a_file_diagnostics = super::check_types(&db, a_file);
-        assert_diagnostic_messages(
-            &a_file_diagnostics,
-            &["Object of type 'Literal[123]' is not iterable"],
-        );
-    }
-
-    #[test]
-    fn new_iteration_protocol_takes_precedence_over_old_style() {
-        let mut db = setup_db();
-
-        db.write_dedented(
-            "src/a.py",
-            "
-            class NotIterable:
-                def __getitem__(self, key: int) -> int:
-                    return 42
-
-                __iter__ = None
-
-            for x in NotIterable():
-                pass
-            ",
-        )
-        .unwrap();
-
-        let a_file = system_path_to_file(&db, "/src/a.py").unwrap();
-        let a_file_diagnostics = super::check_types(&db, a_file);
-        assert_diagnostic_messages(
-            &a_file_diagnostics,
-            &["Object of type 'NotIterable' is not iterable"],
-        );
-    }
-
-    #[test]
-    fn starred_expressions_must_be_iterable() {
-        let mut db = setup_db();
-
-        db.write_dedented(
-            "src/a.py",
-            "
-            class NotIterable: pass
-
-            class Iterator:
-                def __next__(self) -> int:
-                    return 42
-
-            class Iterable:
-                def __iter__(self) -> Iterator:
-
-            x = [*NotIterable()]
-            y = [*Iterable()]
-            ",
-        )
-        .unwrap();
-
-        let a_file = system_path_to_file(&db, "/src/a.py").unwrap();
-        let a_file_diagnostics = super::check_types(&db, a_file);
-        assert_diagnostic_messages(
-            &a_file_diagnostics,
-            &["Object of type 'NotIterable' is not iterable"],
-        );
-    }
-
-    #[test]
-    fn yield_from_expression_must_be_iterable() {
-        let mut db = setup_db();
-
-        db.write_dedented(
-            "src/a.py",
-            "
-            class NotIterable: pass
-
-            class Iterator:
-                def __next__(self) -> int:
-                    return 42
-
-            class Iterable:
-                def __iter__(self) -> Iterator:
-
-            def generator_function():
-                yield from Iterable()
-                yield from NotIterable()
-            ",
-        )
-        .unwrap();
-
-        let a_file = system_path_to_file(&db, "/src/a.py").unwrap();
-        let a_file_diagnostics = super::check_types(&db, a_file);
-        assert_diagnostic_messages(
-            &a_file_diagnostics,
-            &["Object of type 'NotIterable' is not iterable"],
-        );
+        assert!(from.into_type(&db).is_equivalent_to(&db, to.into_type(&db)));
     }
 }

crates/red_knot_python_semantic/src/types/builder.rs

@@ -169,11 +169,12 @@ impl<'db> IntersectionBuilder<'db> {
         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()
+            UnionType::from_elements(
+                self.db,
+                self.intersections
+                    .into_iter()
+                    .map(|inner| inner.build(self.db)),
+            )
         }
     }
 }
@@ -271,11 +272,11 @@ impl<'db> InnerIntersectionBuilder<'db> {
 
 #[cfg(test)]
 mod tests {
-    use super::{IntersectionBuilder, IntersectionType, Type, UnionBuilder, UnionType};
+    use super::{IntersectionBuilder, IntersectionType, Type, UnionType};
     use crate::db::tests::TestDb;
     use crate::program::{Program, SearchPathSettings};
     use crate::python_version::PythonVersion;
-    use crate::types::builtins_symbol_ty;
+    use crate::types::{builtins_symbol_ty, UnionBuilder};
     use crate::ProgramSettings;
     use ruff_db::system::{DbWithTestSystem, SystemPathBuf};
 
@@ -310,11 +311,7 @@ mod tests {
         let db = setup_db();
         let t0 = Type::IntLiteral(0);
         let t1 = Type::IntLiteral(1);
-        let union = UnionBuilder::new(&db)
-            .add(t0)
-            .add(t1)
-            .build()
-            .expect_union();
+        let union = UnionType::from_elements(&db, [t0, t1]).expect_union();
 
         assert_eq!(union.elements_vec(&db), &[t0, t1]);
     }
@@ -323,8 +320,7 @@ mod tests {
     fn build_union_single() {
         let db = setup_db();
         let t0 = Type::IntLiteral(0);
-        let ty = UnionBuilder::new(&db).add(t0).build();
-
+        let ty = UnionType::from_elements(&db, [t0]);
         assert_eq!(ty, t0);
     }
 
@@ -332,7 +328,6 @@ mod tests {
     fn build_union_empty() {
         let db = setup_db();
         let ty = UnionBuilder::new(&db).build();
-
         assert_eq!(ty, Type::Never);
     }
 
@@ -340,8 +335,7 @@ mod tests {
     fn build_union_never() {
         let db = setup_db();
         let t0 = Type::IntLiteral(0);
-        let ty = UnionBuilder::new(&db).add(t0).add(Type::Never).build();
-
+        let ty = UnionType::from_elements(&db, [t0, Type::Never]);
         assert_eq!(ty, t0);
     }
 
@@ -355,21 +349,10 @@ mod tests {
         let t2 = Type::BooleanLiteral(false);
         let t3 = Type::IntLiteral(17);
 
-        let union = UnionBuilder::new(&db)
-            .add(t0)
-            .add(t1)
-            .add(t3)
-            .build()
-            .expect_union();
+        let union = UnionType::from_elements(&db, [t0, t1, t3]).expect_union();
         assert_eq!(union.elements_vec(&db), &[t0, t3]);
-        let union = UnionBuilder::new(&db)
-            .add(t0)
-            .add(t1)
-            .add(t2)
-            .add(t3)
-            .build()
-            .expect_union();
 
+        let union = UnionType::from_elements(&db, [t0, t1, t2, t3]).expect_union();
         assert_eq!(union.elements_vec(&db), &[bool_ty, t3]);
     }
 
@@ -379,12 +362,8 @@ mod tests {
         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 union = UnionBuilder::new(&db)
-            .add(u1)
-            .add(t2)
-            .build()
-            .expect_union();
+        let u1 = UnionType::from_elements(&db, [t0, t1]);
+        let union = UnionType::from_elements(&db, [u1, t2]).expect_union();
 
         assert_eq!(union.elements_vec(&db), &[t0, t1, t2]);
     }
@@ -460,7 +439,7 @@ mod tests {
         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 u0 = UnionType::from_elements(&db, [t0, t1]);
 
         let union = IntersectionBuilder::new(&db)
             .add_positive(ta)

crates/red_knot_python_semantic/src/types/display.rs

@@ -1,19 +1,20 @@
 //! Display implementations for types.
 
-use std::fmt::{Display, Formatter};
+use std::fmt::{self, Display, Formatter};
 
+use ruff_db::display::FormatterJoinExtension;
 use ruff_python_ast::str::Quote;
 use ruff_python_literal::escape::AsciiEscape;
 
 use crate::types::{IntersectionType, Type, UnionType};
-use crate::{Db, FxOrderMap};
+use crate::Db;
+use rustc_hash::FxHashMap;
 
 impl<'db> Type<'db> {
-    pub fn display(&'db self, db: &'db dyn Db) -> DisplayType<'db> {
+    pub fn display(&self, db: &'db dyn Db) -> DisplayType {
         DisplayType { ty: self, db }
     }
-
-    fn representation(&'db self, db: &'db dyn Db) -> DisplayRepresentation<'db> {
+    fn representation(self, db: &'db dyn Db) -> DisplayRepresentation<'db> {
         DisplayRepresentation { db, ty: self }
     }
 }
@@ -25,7 +26,7 @@ pub struct DisplayType<'db> {
 }
 
 impl Display for DisplayType<'_> {
-    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
         let representation = self.ty.representation(self.db);
         if matches!(
             self.ty,
@@ -43,9 +44,9 @@ impl Display for DisplayType<'_> {
     }
 }
 
-impl std::fmt::Debug for DisplayType<'_> {
-    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
-        std::fmt::Display::fmt(self, f)
+impl fmt::Debug for DisplayType<'_> {
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+        Display::fmt(self, f)
     }
 }
 
@@ -53,12 +54,12 @@ impl std::fmt::Debug for DisplayType<'_> {
 /// `Literal[<repr>]` or `Literal[<repr1>, <repr2>]` for literal types or as `<repr>` for
 /// non literals
 struct DisplayRepresentation<'db> {
-    ty: &'db Type<'db>,
+    ty: Type<'db>,
     db: &'db dyn Db,
 }
 
-impl std::fmt::Display for DisplayRepresentation<'_> {
-    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+impl Display for DisplayRepresentation<'_> {
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
         match self.ty {
             Type::Any => f.write_str("Any"),
             Type::Never => f.write_str("Never"),
@@ -74,8 +75,8 @@ impl std::fmt::Display for DisplayRepresentation<'_> {
             Type::Function(function) => f.write_str(function.name(self.db)),
             Type::Union(union) => union.display(self.db).fmt(f),
             Type::Intersection(intersection) => intersection.display(self.db).fmt(f),
-            Type::IntLiteral(n) => write!(f, "{n}"),
-            Type::BooleanLiteral(boolean) => f.write_str(if *boolean { "True" } else { "False" }),
+            Type::IntLiteral(n) => n.fmt(f),
+            Type::BooleanLiteral(boolean) => f.write_str(if boolean { "True" } else { "False" }),
             Type::StringLiteral(string) => {
                 write!(f, r#""{}""#, string.value(self.db).replace('"', r#"\""#))
             }
@@ -86,6 +87,16 @@ impl std::fmt::Display for DisplayRepresentation<'_> {
 
                 escape.bytes_repr().write(f)
             }
+            Type::Tuple(tuple) => {
+                f.write_str("tuple[")?;
+                let elements = tuple.elements(self.db);
+                if elements.is_empty() {
+                    f.write_str("()")?;
+                } else {
+                    elements.display(self.db).fmt(f)?;
+                }
+                f.write_str("]")
+            }
         }
     }
 }
@@ -102,11 +113,11 @@ struct DisplayUnionType<'db> {
 }
 
 impl Display for DisplayUnionType<'_> {
-    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
         let elements = self.ty.elements(self.db);
 
         // Group literal types by kind.
-        let mut grouped_literals = FxOrderMap::default();
+        let mut grouped_literals = FxHashMap::default();
 
         for element in elements {
             if let Ok(literal_kind) = LiteralTypeKind::try_from(*element) {
@@ -117,52 +128,51 @@ impl Display for DisplayUnionType<'_> {
             }
         }
 
-        let mut first = true;
+        let mut join = f.join(" | ");
 
-        // Print all types, but write all literals together (while preserving their position).
-        for ty in elements {
-            if let Ok(literal_kind) = LiteralTypeKind::try_from(*ty) {
+        for element in elements {
+            if let Ok(literal_kind) = LiteralTypeKind::try_from(*element) {
                 let Some(mut literals) = grouped_literals.remove(&literal_kind) else {
                     continue;
                 };
-
-                if !first {
-                    f.write_str(" | ")?;
-                };
-
-                f.write_str("Literal[")?;
-
                 if literal_kind == LiteralTypeKind::IntLiteral {
                     literals.sort_unstable_by_key(|ty| ty.expect_int_literal());
                 }
-
-                for (i, literal_ty) in literals.iter().enumerate() {
-                    if i > 0 {
-                        f.write_str(", ")?;
-                    }
-                    literal_ty.representation(self.db).fmt(f)?;
-                }
-                f.write_str("]")?;
+                join.entry(&DisplayLiteralGroup {
+                    literals,
+                    db: self.db,
+                });
             } else {
-                if !first {
-                    f.write_str(" | ")?;
-                };
-
-                ty.display(self.db).fmt(f)?;
+                join.entry(&element.display(self.db));
             }
-
-            first = false;
         }
 
+        join.finish()?;
+
         debug_assert!(grouped_literals.is_empty());
 
         Ok(())
     }
 }
 
-impl std::fmt::Debug for DisplayUnionType<'_> {
-    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
-        std::fmt::Display::fmt(self, f)
+impl fmt::Debug for DisplayUnionType<'_> {
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+        Display::fmt(self, f)
+    }
+}
+
+struct DisplayLiteralGroup<'db> {
+    literals: Vec<Type<'db>>,
+    db: &'db dyn Db,
+}
+
+impl Display for DisplayLiteralGroup<'_> {
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+        f.write_str("Literal[")?;
+        f.join(", ")
+            .entries(self.literals.iter().map(|ty| ty.representation(self.db)))
+            .finish()?;
+        f.write_str("]")
     }
 }
 
@@ -202,31 +212,77 @@ struct DisplayIntersectionType<'db> {
 }
 
 impl Display for DisplayIntersectionType<'_> {
-    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
-        let mut first = true;
-        for (neg, ty) in self
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+        let tys = self
             .ty
             .positive(self.db)
             .iter()
-            .map(|ty| (false, ty))
-            .chain(self.ty.negative(self.db).iter().map(|ty| (true, ty)))
-        {
-            if !first {
-                f.write_str(" & ")?;
-            };
-            first = false;
-            if neg {
-                f.write_str("~")?;
-            };
-            write!(f, "{}", ty.display(self.db))?;
-        }
-        Ok(())
+            .map(|&ty| DisplayMaybeNegatedType {
+                ty,
+                db: self.db,
+                negated: false,
+            })
+            .chain(
+                self.ty
+                    .negative(self.db)
+                    .iter()
+                    .map(|&ty| DisplayMaybeNegatedType {
+                        ty,
+                        db: self.db,
+                        negated: true,
+                    }),
+            );
+        f.join(" & ").entries(tys).finish()
     }
 }
 
-impl std::fmt::Debug for DisplayIntersectionType<'_> {
-    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
-        std::fmt::Display::fmt(self, f)
+impl fmt::Debug for DisplayIntersectionType<'_> {
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+        Display::fmt(self, f)
+    }
+}
+
+struct DisplayMaybeNegatedType<'db> {
+    ty: Type<'db>,
+    db: &'db dyn Db,
+    negated: bool,
+}
+
+impl<'db> Display for DisplayMaybeNegatedType<'db> {
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+        if self.negated {
+            f.write_str("~")?;
+        }
+        self.ty.display(self.db).fmt(f)
+    }
+}
+
+pub(crate) trait TypeArrayDisplay<'db> {
+    fn display(&self, db: &'db dyn Db) -> DisplayTypeArray;
+}
+
+impl<'db> TypeArrayDisplay<'db> for Box<[Type<'db>]> {
+    fn display(&self, db: &'db dyn Db) -> DisplayTypeArray {
+        DisplayTypeArray { types: self, db }
+    }
+}
+
+impl<'db> TypeArrayDisplay<'db> for Vec<Type<'db>> {
+    fn display(&self, db: &'db dyn Db) -> DisplayTypeArray {
+        DisplayTypeArray { types: self, db }
+    }
+}
+
+pub(crate) struct DisplayTypeArray<'b, 'db> {
+    types: &'b [Type<'db>],
+    db: &'db dyn Db,
+}
+
+impl<'db> Display for DisplayTypeArray<'_, 'db> {
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+        f.join(", ")
+            .entries(self.types.iter().map(|ty| ty.display(self.db)))
+            .finish()
     }
 }
 
@@ -236,7 +292,7 @@ mod tests {
     use ruff_db::system::{DbWithTestSystem, SystemPathBuf};
 
     use crate::db::tests::TestDb;
-    use crate::types::{global_symbol_ty, BytesLiteralType, StringLiteralType, Type, UnionBuilder};
+    use crate::types::{global_symbol_ty, BytesLiteralType, StringLiteralType, Type, UnionType};
     use crate::{Program, ProgramSettings, PythonVersion, SearchPathSettings};
 
     fn setup_db() -> TestDb {
@@ -278,7 +334,7 @@ mod tests {
         )?;
         let mod_file = system_path_to_file(&db, "src/main.py").expect("Expected file to exist.");
 
-        let vec: Vec<Type<'_>> = vec![
+        let union_elements = &[
             Type::Unknown,
             Type::IntLiteral(-1),
             global_symbol_ty(&db, mod_file, "A"),
@@ -294,10 +350,7 @@ mod tests {
             Type::BooleanLiteral(true),
             Type::None,
         ];
-        let builder = vec.iter().fold(UnionBuilder::new(&db), |builder, literal| {
-            builder.add(*literal)
-        });
-        let union = builder.build().expect_union();
+        let union = UnionType::from_elements(&db, union_elements).expect_union();
         let display = format!("{}", union.display(&db));
         assert_eq!(
             display,

crates/red_knot_python_semantic/src/types/narrow.rs

@@ -1,9 +1,10 @@
 use crate::semantic_index::ast_ids::HasScopedAstId;
+use crate::semantic_index::constraint::{Constraint, PatternConstraint};
 use crate::semantic_index::definition::Definition;
 use crate::semantic_index::expression::Expression;
 use crate::semantic_index::symbol::{ScopeId, ScopedSymbolId, SymbolTable};
 use crate::semantic_index::symbol_table;
-use crate::types::{infer_expression_types, IntersectionBuilder, Type, TypeInference};
+use crate::types::{infer_expression_types, IntersectionBuilder, Type};
 use crate::Db;
 use ruff_python_ast as ast;
 use rustc_hash::FxHashMap;
@@ -27,62 +28,114 @@ use std::sync::Arc;
 /// constraint is applied to that definition, so we'd just return `None`.
 pub(crate) fn narrowing_constraint<'db>(
     db: &'db dyn Db,
-    test: Expression<'db>,
+    constraint: Constraint<'db>,
     definition: Definition<'db>,
 ) -> Option<Type<'db>> {
-    all_narrowing_constraints(db, test)
-        .get(&definition.symbol(db))
-        .copied()
+    match constraint {
+        Constraint::Expression(expression) => {
+            all_narrowing_constraints_for_expression(db, expression)
+                .get(&definition.symbol(db))
+                .copied()
+        }
+        Constraint::Pattern(pattern) => all_narrowing_constraints_for_pattern(db, pattern)
+            .get(&definition.symbol(db))
+            .copied(),
+    }
 }
 
 #[salsa::tracked(return_ref)]
-fn all_narrowing_constraints<'db>(
+fn all_narrowing_constraints_for_pattern<'db>(
     db: &'db dyn Db,
-    test: Expression<'db>,
+    pattern: PatternConstraint<'db>,
 ) -> NarrowingConstraints<'db> {
-    NarrowingConstraintsBuilder::new(db, test).finish()
+    NarrowingConstraintsBuilder::new(db, Constraint::Pattern(pattern)).finish()
+}
+
+#[salsa::tracked(return_ref)]
+fn all_narrowing_constraints_for_expression<'db>(
+    db: &'db dyn Db,
+    expression: Expression<'db>,
+) -> NarrowingConstraints<'db> {
+    NarrowingConstraintsBuilder::new(db, Constraint::Expression(expression)).finish()
 }
 
 type NarrowingConstraints<'db> = FxHashMap<ScopedSymbolId, Type<'db>>;
 
 struct NarrowingConstraintsBuilder<'db> {
     db: &'db dyn Db,
-    expression: Expression<'db>,
+    constraint: Constraint<'db>,
     constraints: NarrowingConstraints<'db>,
 }
 
 impl<'db> NarrowingConstraintsBuilder<'db> {
-    fn new(db: &'db dyn Db, expression: Expression<'db>) -> Self {
+    fn new(db: &'db dyn Db, constraint: Constraint<'db>) -> Self {
         Self {
             db,
-            expression,
+            constraint,
             constraints: NarrowingConstraints::default(),
         }
     }
 
     fn finish(mut self) -> NarrowingConstraints<'db> {
-        if let ast::Expr::Compare(expr_compare) = self.expression.node_ref(self.db).node() {
-            self.add_expr_compare(expr_compare);
+        match self.constraint {
+            Constraint::Expression(expression) => self.evaluate_expression_constraint(expression),
+            Constraint::Pattern(pattern) => self.evaluate_pattern_constraint(pattern),
         }
-        // TODO other test expression kinds
 
         self.constraints.shrink_to_fit();
         self.constraints
     }
 
+    fn evaluate_expression_constraint(&mut self, expression: Expression<'db>) {
+        if let ast::Expr::Compare(expr_compare) = expression.node_ref(self.db).node() {
+            self.add_expr_compare(expr_compare, expression);
+        }
+        // TODO other test expression kinds
+    }
+
+    fn evaluate_pattern_constraint(&mut self, pattern: PatternConstraint<'db>) {
+        let subject = pattern.subject(self.db);
+
+        match pattern.pattern(self.db).node() {
+            ast::Pattern::MatchValue(_) => {
+                // TODO
+            }
+            ast::Pattern::MatchSingleton(singleton_pattern) => {
+                self.add_match_pattern_singleton(subject, singleton_pattern);
+            }
+            ast::Pattern::MatchSequence(_) => {
+                // TODO
+            }
+            ast::Pattern::MatchMapping(_) => {
+                // TODO
+            }
+            ast::Pattern::MatchClass(_) => {
+                // TODO
+            }
+            ast::Pattern::MatchStar(_) => {
+                // TODO
+            }
+            ast::Pattern::MatchAs(_) => {
+                // TODO
+            }
+            ast::Pattern::MatchOr(_) => {
+                // TODO
+            }
+        }
+    }
+
     fn symbols(&self) -> Arc<SymbolTable> {
         symbol_table(self.db, self.scope())
     }
 
     fn scope(&self) -> ScopeId<'db> {
-        self.expression.scope(self.db)
+        match self.constraint {
+            Constraint::Expression(expression) => expression.scope(self.db),
+            Constraint::Pattern(pattern) => pattern.scope(self.db),
+        }
     }
 
-    fn inference(&self) -> &'db TypeInference<'db> {
-        infer_expression_types(self.db, self.expression)
-    }
-
-    fn add_expr_compare(&mut self, expr_compare: &ast::ExprCompare) {
+    fn add_expr_compare(&mut self, expr_compare: &ast::ExprCompare, expression: Expression<'db>) {
         let ast::ExprCompare {
             range: _,
             left,
@@ -99,7 +152,7 @@ impl<'db> NarrowingConstraintsBuilder<'db> {
             // SAFETY: we should always have a symbol for every Name node.
             let symbol = self.symbols().symbol_id_by_name(id).unwrap();
             let scope = self.scope();
-            let inference = self.inference();
+            let inference = infer_expression_types(self.db, expression);
             for (op, comparator) in std::iter::zip(&**ops, &**comparators) {
                 let comp_ty = inference.expression_ty(comparator.scoped_ast_id(self.db, scope));
                 if matches!(op, ast::CmpOp::IsNot) {
@@ -112,4 +165,22 @@ impl<'db> NarrowingConstraintsBuilder<'db> {
             }
         }
     }
+
+    fn add_match_pattern_singleton(
+        &mut self,
+        subject: &ast::Expr,
+        pattern: &ast::PatternMatchSingleton,
+    ) {
+        if let Some(ast::ExprName { id, .. }) = subject.as_name_expr() {
+            // SAFETY: we should always have a symbol for every Name node.
+            let symbol = self.symbols().symbol_id_by_name(id).unwrap();
+
+            let ty = match pattern.value {
+                ast::Singleton::None => Type::None,
+                ast::Singleton::True => Type::BooleanLiteral(true),
+                ast::Singleton::False => Type::BooleanLiteral(false),
+            };
+            self.constraints.insert(symbol, ty);
+        }
+    }
 }

crates/red_knot_python_semantic/vendor/typeshed/source_commit.txt

@@ -1 +1 @@
-23d867efb2df6de5600f64656f1aa8a83e06109e
+9e506eb5e8fc2823db8c60ad561b1145ff114947

crates/red_knot_python_semantic/vendor/typeshed/stdlib/VERSIONS

@@ -41,7 +41,7 @@ _json: 3.0-
 _locale: 3.0-
 _lsprof: 3.0-
 _markupbase: 3.0-
-_msi: 3.0-
+_msi: 3.0-3.12
 _operator: 3.4-
 _osx_support: 3.0-
 _posixsubprocess: 3.2-

crates/red_knot_python_semantic/vendor/typeshed/stdlib/_curses.pyi

@@ -493,7 +493,7 @@ class _CursesWindow:
     def instr(self, y: int, x: int, n: int = ...) -> bytes: ...
     def is_linetouched(self, line: int, /) -> bool: ...
     def is_wintouched(self) -> bool: ...
-    def keypad(self, yes: bool) -> None: ...
+    def keypad(self, yes: bool, /) -> None: ...
     def leaveok(self, yes: bool) -> None: ...
     def move(self, new_y: int, new_x: int) -> None: ...
     def mvderwin(self, y: int, x: int) -> None: ...

crates/red_knot_python_semantic/vendor/typeshed/stdlib/_locale.pyi

@@ -1,17 +1,38 @@
 import sys
 from _typeshed import StrPath
-from collections.abc import Mapping
+from typing import Final, Literal, TypedDict, type_check_only
 
-LC_CTYPE: int
-LC_COLLATE: int
-LC_TIME: int
-LC_MONETARY: int
-LC_NUMERIC: int
-LC_ALL: int
-CHAR_MAX: int
+@type_check_only
+class _LocaleConv(TypedDict):
+    decimal_point: str
+    grouping: list[int]
+    thousands_sep: str
+    int_curr_symbol: str
+    currency_symbol: str
+    p_cs_precedes: Literal[0, 1, 127]
+    n_cs_precedes: Literal[0, 1, 127]
+    p_sep_by_space: Literal[0, 1, 127]
+    n_sep_by_space: Literal[0, 1, 127]
+    mon_decimal_point: str
+    frac_digits: int
+    int_frac_digits: int
+    mon_thousands_sep: str
+    mon_grouping: list[int]
+    positive_sign: str
+    negative_sign: str
+    p_sign_posn: Literal[0, 1, 2, 3, 4, 127]
+    n_sign_posn: Literal[0, 1, 2, 3, 4, 127]
+
+LC_CTYPE: Final[int]
+LC_COLLATE: Final[int]
+LC_TIME: Final[int]
+LC_MONETARY: Final[int]
+LC_NUMERIC: Final[int]
+LC_ALL: Final[int]
+CHAR_MAX: Final = 127
 
 def setlocale(category: int, locale: str | None = None, /) -> str: ...
-def localeconv() -> Mapping[str, int | str | list[int]]: ...
+def localeconv() -> _LocaleConv: ...
 
 if sys.version_info >= (3, 11):
     def getencoding() -> str: ...
@@ -25,67 +46,67 @@ def strxfrm(string: str, /) -> str: ...
 if sys.platform != "win32":
     LC_MESSAGES: int
 
-    ABDAY_1: int
-    ABDAY_2: int
-    ABDAY_3: int
-    ABDAY_4: int
-    ABDAY_5: int
-    ABDAY_6: int
-    ABDAY_7: int
+    ABDAY_1: Final[int]
+    ABDAY_2: Final[int]
+    ABDAY_3: Final[int]
+    ABDAY_4: Final[int]
+    ABDAY_5: Final[int]
+    ABDAY_6: Final[int]
+    ABDAY_7: Final[int]
 
-    ABMON_1: int
-    ABMON_2: int
-    ABMON_3: int
-    ABMON_4: int
-    ABMON_5: int
-    ABMON_6: int
-    ABMON_7: int
-    ABMON_8: int
-    ABMON_9: int
-    ABMON_10: int
-    ABMON_11: int
-    ABMON_12: int
+    ABMON_1: Final[int]
+    ABMON_2: Final[int]
+    ABMON_3: Final[int]
+    ABMON_4: Final[int]
+    ABMON_5: Final[int]
+    ABMON_6: Final[int]
+    ABMON_7: Final[int]
+    ABMON_8: Final[int]
+    ABMON_9: Final[int]
+    ABMON_10: Final[int]
+    ABMON_11: Final[int]
+    ABMON_12: Final[int]
 
-    DAY_1: int
-    DAY_2: int
-    DAY_3: int
-    DAY_4: int
-    DAY_5: int
-    DAY_6: int
-    DAY_7: int
+    DAY_1: Final[int]
+    DAY_2: Final[int]
+    DAY_3: Final[int]
+    DAY_4: Final[int]
+    DAY_5: Final[int]
+    DAY_6: Final[int]
+    DAY_7: Final[int]
 
-    ERA: int
-    ERA_D_T_FMT: int
-    ERA_D_FMT: int
-    ERA_T_FMT: int
+    ERA: Final[int]
+    ERA_D_T_FMT: Final[int]
+    ERA_D_FMT: Final[int]
+    ERA_T_FMT: Final[int]
 
-    MON_1: int
-    MON_2: int
-    MON_3: int
-    MON_4: int
-    MON_5: int
-    MON_6: int
-    MON_7: int
-    MON_8: int
-    MON_9: int
-    MON_10: int
-    MON_11: int
-    MON_12: int
+    MON_1: Final[int]
+    MON_2: Final[int]
+    MON_3: Final[int]
+    MON_4: Final[int]
+    MON_5: Final[int]
+    MON_6: Final[int]
+    MON_7: Final[int]
+    MON_8: Final[int]
+    MON_9: Final[int]
+    MON_10: Final[int]
+    MON_11: Final[int]
+    MON_12: Final[int]
 
-    CODESET: int
-    D_T_FMT: int
-    D_FMT: int
-    T_FMT: int
-    T_FMT_AMPM: int
-    AM_STR: int
-    PM_STR: int
+    CODESET: Final[int]
+    D_T_FMT: Final[int]
+    D_FMT: Final[int]
+    T_FMT: Final[int]
+    T_FMT_AMPM: Final[int]
+    AM_STR: Final[int]
+    PM_STR: Final[int]
 
-    RADIXCHAR: int
-    THOUSEP: int
-    YESEXPR: int
-    NOEXPR: int
-    CRNCYSTR: int
-    ALT_DIGITS: int
+    RADIXCHAR: Final[int]
+    THOUSEP: Final[int]
+    YESEXPR: Final[int]
+    NOEXPR: Final[int]
+    CRNCYSTR: Final[int]
+    ALT_DIGITS: Final[int]
 
     def nl_langinfo(key: int, /) -> str: ...
 

crates/red_knot_python_semantic/vendor/typeshed/stdlib/_winapi.pyi

@@ -99,6 +99,20 @@ if sys.platform == "win32":
     SEC_RESERVE: Final = 0x4000000
     SEC_WRITECOMBINE: Final = 0x40000000
 
+    if sys.version_info >= (3, 13):
+        STARTF_FORCEOFFFEEDBACK: Final = 0x80
+        STARTF_FORCEONFEEDBACK: Final = 0x40
+        STARTF_PREVENTPINNING: Final = 0x2000
+        STARTF_RUNFULLSCREEN: Final = 0x20
+        STARTF_TITLEISAPPID: Final = 0x1000
+        STARTF_TITLEISLINKNAME: Final = 0x800
+        STARTF_UNTRUSTEDSOURCE: Final = 0x8000
+        STARTF_USECOUNTCHARS: Final = 0x8
+        STARTF_USEFILLATTRIBUTE: Final = 0x10
+        STARTF_USEHOTKEY: Final = 0x200
+        STARTF_USEPOSITION: Final = 0x4
+        STARTF_USESIZE: Final = 0x2
+
     STARTF_USESHOWWINDOW: Final = 0x1
     STARTF_USESTDHANDLES: Final = 0x100
 
@@ -250,6 +264,20 @@ if sys.platform == "win32":
         def cancel(self) -> None: ...
         def getbuffer(self) -> bytes | None: ...
 
+    if sys.version_info >= (3, 13):
+        def BatchedWaitForMultipleObjects(
+            handle_seq: Sequence[int], wait_all: bool, milliseconds: int = 0xFFFFFFFF
+        ) -> list[int]: ...
+        def CreateEventW(security_attributes: int, manual_reset: bool, initial_state: bool, name: str | None) -> int: ...
+        def CreateMutexW(security_attributes: int, initial_owner: bool, name: str) -> int: ...
+        def GetLongPathName(path: str) -> str: ...
+        def GetShortPathName(path: str) -> str: ...
+        def OpenEventW(desired_access: int, inherit_handle: bool, name: str) -> int: ...
+        def OpenMutexW(desired_access: int, inherit_handle: bool, name: str) -> int: ...
+        def ReleaseMutex(mutex: int) -> None: ...
+        def ResetEvent(event: int) -> None: ...
+        def SetEvent(event: int) -> None: ...
+
     if sys.version_info >= (3, 12):
         def CopyFile2(existing_file_name: str, new_file_name: str, flags: int, progress_routine: int | None = None) -> int: ...
         def NeedCurrentDirectoryForExePath(exe_name: str, /) -> bool: ...

crates/red_knot_python_semantic/vendor/typeshed/stdlib/builtins.pyi

@@ -1,3 +1,4 @@
+# ruff: noqa: PYI036 # This is the module declaring BaseException
 import _ast
 import _typeshed
 import sys

crates/red_knot_python_semantic/vendor/typeshed/stdlib/codecs.pyi

@@ -80,7 +80,7 @@ class _Encoder(Protocol):
     def __call__(self, input: str, errors: str = ..., /) -> tuple[bytes, int]: ...  # signature of Codec().encode
 
 class _Decoder(Protocol):
-    def __call__(self, input: bytes, errors: str = ..., /) -> tuple[str, int]: ...  # signature of Codec().decode
+    def __call__(self, input: ReadableBuffer, errors: str = ..., /) -> tuple[str, int]: ...  # signature of Codec().decode
 
 class _StreamReader(Protocol):
     def __call__(self, stream: _ReadableStream, errors: str = ..., /) -> StreamReader: ...

crates/red_knot_python_semantic/vendor/typeshed/stdlib/copy.pyi

@@ -1,16 +1,15 @@
 import sys
 from typing import Any, Protocol, TypeVar
-from typing_extensions import ParamSpec, Self
+from typing_extensions import Self
 
 __all__ = ["Error", "copy", "deepcopy"]
 
 _T = TypeVar("_T")
-_SR = TypeVar("_SR", bound=_SupportsReplace[Any])
-_P = ParamSpec("_P")
+_SR = TypeVar("_SR", bound=_SupportsReplace)
 
-class _SupportsReplace(Protocol[_P]):
+class _SupportsReplace(Protocol):
     # In reality doesn't support args, but there's no other great way to express this.
-    def __replace__(self, *args: _P.args, **kwargs: _P.kwargs) -> Self: ...
+    def __replace__(self, *args: Any, **kwargs: Any) -> Self: ...
 
 # None in CPython but non-None in Jython
 PyStringMap: Any

crates/red_knot_python_semantic/vendor/typeshed/stdlib/distutils/dist.pyi

@@ -270,7 +270,7 @@ class Distribution:
     def has_data_files(self) -> bool: ...
     def is_pure(self) -> bool: ...
 
-    # Getter methods generated in __init__
+    # Default getter methods generated in __init__ from self.metadata._METHOD_BASENAMES
     def get_name(self) -> str: ...
     def get_version(self) -> str: ...
     def get_fullname(self) -> str: ...
@@ -292,3 +292,26 @@ class Distribution:
     def get_requires(self) -> list[str]: ...
     def get_provides(self) -> list[str]: ...
     def get_obsoletes(self) -> list[str]: ...
+
+    # Default attributes generated in __init__ from self.display_option_names
+    help_commands: bool | Literal[0]
+    name: str | Literal[0]
+    version: str | Literal[0]
+    fullname: str | Literal[0]
+    author: str | Literal[0]
+    author_email: str | Literal[0]
+    maintainer: str | Literal[0]
+    maintainer_email: str | Literal[0]
+    contact: str | Literal[0]
+    contact_email: str | Literal[0]
+    url: str | Literal[0]
+    license: str | Literal[0]
+    licence: str | Literal[0]
+    description: str | Literal[0]
+    long_description: str | Literal[0]
+    platforms: str | list[str] | Literal[0]
+    classifiers: str | list[str] | Literal[0]
+    keywords: str | list[str] | Literal[0]
+    provides: list[str] | Literal[0]
+    requires: list[str] | Literal[0]
+    obsoletes: list[str] | Literal[0]

crates/red_knot_python_semantic/vendor/typeshed/stdlib/doctest.pyi

@@ -1,9 +1,10 @@
+import sys
 import types
 import unittest
 from _typeshed import ExcInfo
 from collections.abc import Callable
-from typing import Any, NamedTuple
-from typing_extensions import TypeAlias
+from typing import Any, ClassVar, NamedTuple
+from typing_extensions import Self, TypeAlias
 
 __all__ = [
     "register_optionflag",
@@ -41,9 +42,22 @@ __all__ = [
     "debug",
 ]
 
-class TestResults(NamedTuple):
-    failed: int
-    attempted: int
+# MyPy errors on conditionals within named tuples.
+
+if sys.version_info >= (3, 13):
+    class TestResults(NamedTuple):
+        def __new__(cls, failed: int, attempted: int, *, skipped: int = 0) -> Self: ...  # type: ignore[misc]
+        skipped: int
+        failed: int
+        attempted: int
+        _fields: ClassVar = ("failed", "attempted")  # type: ignore[misc]
+        __match_args__ = ("failed", "attempted")  # type: ignore[misc]
+        __doc__: None  # type: ignore[misc]
+
+else:
+    class TestResults(NamedTuple):
+        failed: int
+        attempted: int
 
 OPTIONFLAGS_BY_NAME: dict[str, int]
 
@@ -134,6 +148,8 @@ class DocTestRunner:
     original_optionflags: int
     tries: int
     failures: int
+    if sys.version_info >= (3, 13):
+        skips: int
     test: DocTest
     def __init__(self, checker: OutputChecker | None = None, verbose: bool | None = None, optionflags: int = 0) -> None: ...
     def report_start(self, out: _Out, test: DocTest, example: Example) -> None: ...

crates/red_knot_python_semantic/vendor/typeshed/stdlib/email/_header_value_parser.pyi

@@ -16,6 +16,10 @@ TOKEN_ENDS: Final[set[str]]
 ASPECIALS: Final[set[str]]
 ATTRIBUTE_ENDS: Final[set[str]]
 EXTENDED_ATTRIBUTE_ENDS: Final[set[str]]
+# Added in Python 3.8.20, 3.9.20, 3.10.15, 3.11.10, 3.12.5
+NLSET: Final[set[str]]
+# Added in Python 3.8.20, 3.9.20, 3.10.15, 3.11.10, 3.12.5
+SPECIALSNL: Final[set[str]]
 
 def quote_string(value: Any) -> str: ...
 

crates/red_knot_python_semantic/vendor/typeshed/stdlib/email/_policybase.pyi

@@ -3,12 +3,34 @@ from collections.abc import Callable
 from email.errors import MessageDefect
 from email.header import Header
 from email.message import Message
-from typing import Any
 from typing_extensions import Self
 
 class _PolicyBase:
-    def __add__(self, other: Any) -> Self: ...
-    def clone(self, **kw: Any) -> Self: ...
+    def __init__(
+        self,
+        *,
+        max_line_length: int | None = 78,
+        linesep: str = "\n",
+        cte_type: str = "8bit",
+        raise_on_defect: bool = False,
+        mangle_from_: bool = ...,  # default depends on sub-class
+        message_factory: Callable[[Policy], Message] | None = None,
+        # Added in Python 3.8.20, 3.9.20, 3.10.15, 3.11.10, 3.12.5
+        verify_generated_headers: bool = True,
+    ) -> None: ...
+    def clone(
+        self,
+        *,
+        max_line_length: int | None = ...,
+        linesep: str = ...,
+        cte_type: str = ...,
+        raise_on_defect: bool = ...,
+        mangle_from_: bool = ...,
+        message_factory: Callable[[Policy], Message] | None = ...,
+        # Added in Python 3.8.20, 3.9.20, 3.10.15, 3.11.10, 3.12.5
+        verify_generated_headers: bool = ...,
+    ) -> Self: ...
+    def __add__(self, other: Policy) -> Self: ...
 
 class Policy(_PolicyBase, metaclass=ABCMeta):
     max_line_length: int | None
@@ -17,16 +39,9 @@ class Policy(_PolicyBase, metaclass=ABCMeta):
     raise_on_defect: bool
     mangle_from_: bool
     message_factory: Callable[[Policy], Message] | None
-    def __init__(
-        self,
-        *,
-        max_line_length: int | None = 78,
-        linesep: str = "\n",
-        cte_type: str = "8bit",
-        raise_on_defect: bool = False,
-        mangle_from_: bool = False,
-        message_factory: Callable[[Policy], Message] | None = None,
-    ) -> None: ...
+    # Added in Python 3.8.20, 3.9.20, 3.10.15, 3.11.10, 3.12.5
+    verify_generated_headers: bool
+
     def handle_defect(self, obj: Message, defect: MessageDefect) -> None: ...
     def register_defect(self, obj: Message, defect: MessageDefect) -> None: ...
     def header_max_count(self, name: str) -> int | None: ...

crates/red_knot_python_semantic/vendor/typeshed/stdlib/email/errors.pyi

@@ -7,6 +7,9 @@ class BoundaryError(MessageParseError): ...
 class MultipartConversionError(MessageError, TypeError): ...
 class CharsetError(MessageError): ...
 
+# Added in Python 3.8.20, 3.9.20, 3.10.15, 3.11.10, 3.12.5
+class HeaderWriteError(MessageError): ...
+
 class MessageDefect(ValueError):
     def __init__(self, line: str | None = None) -> None: ...
 

crates/red_knot_python_semantic/vendor/typeshed/stdlib/email/utils.pyi

@@ -30,20 +30,12 @@ _PDTZ: TypeAlias = tuple[int, int, int, int, int, int, int, int, int, int | None
 def quote(str: str) -> str: ...
 def unquote(str: str) -> str: ...
 
-if sys.version_info >= (3, 13):
-    def parseaddr(addr: str | list[str], *, strict: bool = True) -> tuple[str, str]: ...
-
-else:
-    def parseaddr(addr: str) -> tuple[str, str]: ...
-
+# `strict` parameter added in Python 3.8.20, 3.9.20, 3.10.15, 3.11.10, 3.12.5
+def parseaddr(addr: str | list[str], *, strict: bool = True) -> tuple[str, str]: ...
 def formataddr(pair: tuple[str | None, str], charset: str | Charset = "utf-8") -> str: ...
 
-if sys.version_info >= (3, 13):
-    def getaddresses(fieldvalues: Iterable[str], *, strict: bool = True) -> list[tuple[str, str]]: ...
-
-else:
-    def getaddresses(fieldvalues: Iterable[str]) -> list[tuple[str, str]]: ...
-
+# `strict` parameter added in Python 3.8.20, 3.9.20, 3.10.15, 3.11.10, 3.12.5
+def getaddresses(fieldvalues: Iterable[str], *, strict: bool = True) -> list[tuple[str, str]]: ...
 @overload
 def parsedate(data: None) -> None: ...
 @overload

crates/red_knot_python_semantic/vendor/typeshed/stdlib/io.pyi

@@ -84,7 +84,6 @@ class RawIOBase(IOBase):
     def read(self, size: int = -1, /) -> bytes | None: ...
 
 class BufferedIOBase(IOBase):
-    raw: RawIOBase  # This is not part of the BufferedIOBase API and may not exist on some implementations.
     def detach(self) -> RawIOBase: ...
     def readinto(self, buffer: WriteableBuffer, /) -> int: ...
     def write(self, buffer: ReadableBuffer, /) -> int: ...
@@ -119,11 +118,13 @@ class BytesIO(BufferedIOBase, BinaryIO):  # type: ignore[misc]  # incompatible d
     def read1(self, size: int | None = -1, /) -> bytes: ...
 
 class BufferedReader(BufferedIOBase, BinaryIO):  # type: ignore[misc]  # incompatible definitions of methods in the base classes
+    raw: RawIOBase
     def __enter__(self) -> Self: ...
     def __init__(self, raw: RawIOBase, buffer_size: int = ...) -> None: ...
     def peek(self, size: int = 0, /) -> bytes: ...
 
 class BufferedWriter(BufferedIOBase, BinaryIO):  # type: ignore[misc]  # incompatible definitions of writelines in the base classes
+    raw: RawIOBase
     def __enter__(self) -> Self: ...
     def __init__(self, raw: RawIOBase, buffer_size: int = ...) -> None: ...
     def write(self, buffer: ReadableBuffer, /) -> int: ...

crates/red_knot_python_semantic/vendor/typeshed/stdlib/subprocess.pyi

@@ -2582,6 +2582,11 @@ else:
 def list2cmdline(seq: Iterable[StrOrBytesPath]) -> str: ...  # undocumented
 
 if sys.platform == "win32":
+    if sys.version_info >= (3, 13):
+        from _winapi import STARTF_FORCEOFFFEEDBACK, STARTF_FORCEONFEEDBACK
+
+        __all__ += ["STARTF_FORCEOFFFEEDBACK", "STARTF_FORCEONFEEDBACK"]
+
     class STARTUPINFO:
         def __init__(
             self,

crates/red_knot_python_semantic/vendor/typeshed/stdlib/tempfile.pyi

@@ -253,11 +253,11 @@ class _TemporaryFileWrapper(IO[AnyStr]):
     def truncate(self, size: int | None = ...) -> int: ...
     def writable(self) -> bool: ...
     @overload
-    def write(self: _TemporaryFileWrapper[str], s: str) -> int: ...
+    def write(self: _TemporaryFileWrapper[str], s: str, /) -> int: ...
     @overload
-    def write(self: _TemporaryFileWrapper[bytes], s: ReadableBuffer) -> int: ...
+    def write(self: _TemporaryFileWrapper[bytes], s: ReadableBuffer, /) -> int: ...
     @overload
-    def write(self, s: AnyStr) -> int: ...
+    def write(self, s: AnyStr, /) -> int: ...
     @overload
     def writelines(self: _TemporaryFileWrapper[str], lines: Iterable[str]) -> None: ...
     @overload

crates/ruff/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ruff"
-version = "0.6.4"
+version = "0.6.5"
 publish = true
 authors = { workspace = true }
 edition = { workspace = true }

crates/ruff_benchmark/benches/linter.rs

@@ -28,6 +28,24 @@ static GLOBAL: mimalloc::MiMalloc = mimalloc::MiMalloc;
 #[global_allocator]
 static GLOBAL: tikv_jemallocator::Jemalloc = tikv_jemallocator::Jemalloc;
 
+// Disable decay after 10s because it can show up as *random* slow allocations
+// in benchmarks. We don't need purging in benchmarks because it isn't important
+// to give unallocated pages back to the OS.
+// https://jemalloc.net/jemalloc.3.html#opt.dirty_decay_ms
+#[cfg(all(
+    not(target_os = "windows"),
+    not(target_os = "openbsd"),
+    any(
+        target_arch = "x86_64",
+        target_arch = "aarch64",
+        target_arch = "powerpc64"
+    )
+))]
+#[allow(non_upper_case_globals)]
+#[export_name = "_rjem_malloc_conf"]
+#[allow(unsafe_code)]
+pub static _rjem_malloc_conf: &[u8] = b"dirty_decay_ms:-1,muzzy_decay_ms:-1\0";
+
 fn create_test_cases() -> Result<Vec<TestCase>, TestFileDownloadError> {
     Ok(vec![
         TestCase::fast(TestFile::try_download("numpy/globals.py", "https://raw.githubusercontent.com/numpy/numpy/89d64415e349ca75a25250f22b874aa16e5c0973/numpy/_globals.py")?),

crates/ruff_benchmark/benches/red_knot.rs

@@ -32,7 +32,6 @@ static EXPECTED_DIAGNOSTICS: &[&str] = &[
     "Use double quotes for strings",
     "Use double quotes for strings",
     "Use double quotes for strings",
-    "/src/tomllib/_parser.py:628:75: Name 'e' used when not defined.",
 ];
 
 fn get_test_file(name: &str) -> TestFile {

crates/ruff_db/src/display.rs

@@ -0,0 +1,52 @@
+use std::fmt::{self, Display, Formatter};
+
+pub trait FormatterJoinExtension<'b> {
+    fn join<'a>(&'a mut self, separator: &'static str) -> Join<'a, 'b>;
+}
+
+impl<'b> FormatterJoinExtension<'b> for Formatter<'b> {
+    fn join<'a>(&'a mut self, separator: &'static str) -> Join<'a, 'b> {
+        Join {
+            fmt: self,
+            separator,
+            result: fmt::Result::Ok(()),
+            seen_first: false,
+        }
+    }
+}
+
+pub struct Join<'a, 'b> {
+    fmt: &'a mut Formatter<'b>,
+    separator: &'static str,
+    result: fmt::Result,
+    seen_first: bool,
+}
+
+impl<'a, 'b> Join<'a, 'b> {
+    pub fn entry(&mut self, item: &dyn Display) -> &mut Self {
+        if self.seen_first {
+            self.result = self
+                .result
+                .and_then(|()| self.fmt.write_str(self.separator));
+        } else {
+            self.seen_first = true;
+        }
+        self.result = self.result.and_then(|()| item.fmt(self.fmt));
+        self
+    }
+
+    pub fn entries<I, F>(&mut self, items: I) -> &mut Self
+    where
+        I: IntoIterator<Item = F>,
+        F: Display,
+    {
+        for item in items {
+            self.entry(&item);
+        }
+        self
+    }
+
+    pub fn finish(&mut self) -> fmt::Result {
+        self.result
+    }
+}

crates/ruff_db/src/lib.rs

@@ -6,6 +6,7 @@ use crate::files::Files;
 use crate::system::System;
 use crate::vendored::VendoredFileSystem;
 
+pub mod display;
 pub mod file_revision;
 pub mod files;
 pub mod parsed;

crates/ruff_dev/src/generate_docs.rs

@@ -6,6 +6,7 @@ use std::fs;
 use std::path::PathBuf;
 
 use anyhow::Result;
+use itertools::Itertools;
 use regex::{Captures, Regex};
 use strum::IntoEnumIterator;
 
@@ -33,7 +34,26 @@ pub(crate) fn main(args: &Args) -> Result<()> {
 
             let (linter, _) = Linter::parse_code(&rule.noqa_code().to_string()).unwrap();
             if linter.url().is_some() {
-                output.push_str(&format!("Derived from the **{}** linter.", linter.name()));
+                let common_prefix: String = match linter.common_prefix() {
+                    "" => linter
+                        .upstream_categories()
+                        .unwrap()
+                        .iter()
+                        .map(|c| c.prefix)
+                        .join("-"),
+                    prefix => prefix.to_string(),
+                };
+                let anchor = format!(
+                    "{}-{}",
+                    linter.name().to_lowercase(),
+                    common_prefix.to_lowercase()
+                );
+
+                output.push_str(&format!(
+                    "Derived from the **[{}](../rules.md#{})** linter.",
+                    linter.name(),
+                    anchor
+                ));
                 output.push('\n');
                 output.push('\n');
             }

crates/ruff_linter/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ruff_linter"
-version = "0.6.4"
+version = "0.6.5"
 publish = false
 authors = { workspace = true }
 edition = { workspace = true }
@@ -73,7 +73,7 @@ unicode-normalization = { workspace = true }
 url = { workspace = true }
 
 [dev-dependencies]
-insta = { workspace = true }
+insta = { workspace = true, features = ["filters", "json", "redactions"] }
 test-case = { workspace = true }
 # Disable colored output in tests
 colored = { workspace = true, features = ["no-color"] }

crates/ruff_linter/resources/test/fixtures/eradicate/ERA001.py

@@ -57,7 +57,18 @@ dictionary = {
 # ]
 # ///
 
-# Script tag without a closing tag (OK)
+# Script tag with multiple closing tags (OK)
+# /// script
+# [tool.uv]
+# extra-index-url = ["https://pypi.org/simple", """\
+# https://example.com/
+# ///
+# """
+# ]
+# ///
+print(1)
+
+# Script tag without a closing tag (Error)
 
 # /// script
 # requires-python = ">=3.11"

crates/ruff_linter/resources/test/fixtures/pydoclint/DOC201_google.py

@@ -207,3 +207,10 @@ def foo(s: str) -> str | None:
         s (str): A string.
     """
     return None
+
+
+class Spam:
+    # OK
+    def __new__(cls) -> 'Spam':
+        """New!!"""
+        return cls()

crates/ruff_linter/resources/test/fixtures/refurb/FURB188.py

@@ -0,0 +1,154 @@
+# Test suite from Refurb
+# See https://github.com/dosisod/refurb/blob/db02242b142285e615a664a8d3324470bb711306/test/data/err_188.py
+
+# these should match
+
+def remove_extension_via_slice(filename: str) -> str:
+    if filename.endswith(".txt"):
+        filename = filename[:-4]
+
+    return filename
+
+
+def remove_extension_via_slice_len(filename: str, extension: str) -> str:
+    if filename.endswith(extension):
+        filename = filename[:-len(extension)]
+
+    return filename
+
+
+def remove_extension_via_ternary(filename: str) -> str:
+    return filename[:-4] if filename.endswith(".txt") else filename
+
+
+def remove_extension_via_ternary_with_len(filename: str, extension: str) -> str:
+    return filename[:-len(extension)] if filename.endswith(extension) else filename
+
+
+def remove_prefix(filename: str) -> str:
+    return filename[4:] if filename.startswith("abc-") else filename
+
+
+def remove_prefix_via_len(filename: str, prefix: str) -> str:
+    return filename[len(prefix):] if filename.startswith(prefix) else filename
+
+
+# these should not
+
+def remove_extension_with_mismatched_len(filename: str) -> str:
+    if filename.endswith(".txt"):
+        filename = filename[:3]
+
+    return filename
+
+
+def remove_extension_assign_to_different_var(filename: str) -> str:
+    if filename.endswith(".txt"):
+        other_var = filename[:-4]
+
+    return filename
+
+
+def remove_extension_with_multiple_stmts(filename: str) -> str:
+    if filename.endswith(".txt"):
+        print("do some work")
+
+        filename = filename[:-4]
+
+    if filename.endswith(".txt"):
+        filename = filename[:-4]
+
+        print("do some work")
+
+    return filename
+
+
+def remove_extension_from_unrelated_var(filename: str) -> str:
+    xyz = "abc.txt"
+
+    if filename.endswith(".txt"):
+        filename = xyz[:-4]
+
+    return filename
+
+
+def remove_extension_in_elif(filename: str) -> str:
+    if filename:
+        pass
+
+    elif filename.endswith(".txt"):
+        filename = filename[:-4]
+
+    return filename
+
+
+def remove_extension_in_multiple_elif(filename: str) -> str:
+    if filename:
+        pass
+
+    elif filename:
+        pass
+
+    elif filename.endswith(".txt"):
+        filename = filename[:-4]
+
+    return filename
+
+
+def remove_extension_in_if_with_else(filename: str) -> str:
+    if filename.endswith(".txt"):
+        filename = filename[:-4]
+
+    else:
+        pass
+
+    return filename
+
+
+def remove_extension_ternary_name_mismatch(filename: str):
+    xyz = ""
+
+    _ = xyz[:-4] if filename.endswith(".txt") else filename
+    _ = filename[:-4] if xyz.endswith(".txt") else filename
+    _ = filename[:-4] if filename.endswith(".txt") else xyz
+
+
+def remove_extension_slice_amount_mismatch(filename: str) -> None:
+    extension = ".txt"
+
+    _ = filename[:-1] if filename.endswith(".txt") else filename
+    _ = filename[:-1] if filename.endswith(extension) else filename
+    _ = filename[:-len("")] if filename.endswith(extension) else filename
+
+
+def remove_prefix_size_mismatch(filename: str) -> str:
+    return filename[3:] if filename.startswith("abc-") else filename
+
+
+def remove_prefix_name_mismatch(filename: str) -> None:
+    xyz = ""
+
+    _ = xyz[4:] if filename.startswith("abc-") else filename
+    _ = filename[4:] if xyz.startswith("abc-") else filename
+    _ = filename[4:] if filename.startswith("abc-") else xyz
+
+# ---- End of refurb test suite ---- #
+
+# ---- Begin ruff specific test suite --- #
+
+# these should be linted
+
+def remove_suffix_multiple_attribute_expr() -> None:
+    import foo.bar
+
+    SUFFIX = "suffix"
+
+    x = foo.bar.baz[:-len(SUFFIX)] if foo.bar.baz.endswith(SUFFIX) else foo.bar.baz
+
+def remove_prefix_comparable_literal_expr() -> None:
+    return ("abc" "def")[3:] if ("abc" "def").startswith("abc") else "abc" "def"
+
+def shadow_builtins(filename: str, extension: str) -> None:
+    from builtins import len as builtins_len
+
+    return filename[:-builtins_len(extension)] if filename.endswith(extension) else filename

crates/ruff_linter/resources/test/fixtures/ruff/RUF032.py

@@ -50,6 +50,13 @@ a = 10.0
 
 val = Decimal(a)
 
+# See https://github.com/astral-sh/ruff/issues/13258
+val = Decimal(~4.0) # Skip
+
+val = Decimal(++4.0) # Suggest `Decimal("4.0")`
+
+val = Decimal(-+--++--4.0) # Suggest `Decimal("-4.0")` 
+
 
 # Tests with shadowed name
 class Decimal():

crates/ruff_linter/src/checkers/ast/analyze/expression.rs

@@ -1407,6 +1407,9 @@ pub(crate) fn expression(expr: &Expr, checker: &mut Checker) {
             if checker.enabled(Rule::UselessIfElse) {
                 ruff::rules::useless_if_else(checker, if_exp);
             }
+            if checker.enabled(Rule::SliceToRemovePrefixOrSuffix) {
+                refurb::rules::slice_to_remove_affix_expr(checker, if_exp);
+            }
         }
         Expr::ListComp(
             comp @ ast::ExprListComp {

crates/ruff_linter/src/checkers/ast/analyze/statement.rs

@@ -1178,6 +1178,9 @@ pub(crate) fn statement(stmt: &Stmt, checker: &mut Checker) {
             if checker.enabled(Rule::CheckAndRemoveFromSet) {
                 refurb::rules::check_and_remove_from_set(checker, if_);
             }
+            if checker.enabled(Rule::SliceToRemovePrefixOrSuffix) {
+                refurb::rules::slice_to_remove_affix_stmt(checker, if_);
+            }
             if checker.enabled(Rule::TooManyBooleanExpressions) {
                 pylint::rules::too_many_boolean_expressions(checker, if_);
             }

crates/ruff_linter/src/checkers/ast/analyze/unresolved_references.rs

@@ -1,5 +1,6 @@
 use ruff_diagnostics::Diagnostic;
 use ruff_python_semantic::Exceptions;
+use ruff_python_stdlib::builtins::version_builtin_was_added;
 
 use crate::checkers::ast::Checker;
 use crate::codes::Rule;
@@ -35,9 +36,12 @@ pub(crate) fn unresolved_references(checker: &mut Checker) {
                     }
                 }
 
+                let symbol_name = reference.name(checker.locator);
+
                 checker.diagnostics.push(Diagnostic::new(
                     pyflakes::rules::UndefinedName {
-                        name: reference.name(checker.locator).to_string(),
+                        name: symbol_name.to_string(),
+                        minor_version_builtin_added: version_builtin_was_added(symbol_name),
                     },
                     reference.range(),
                 ));

crates/ruff_linter/src/checkers/ast/mod.rs

@@ -1951,20 +1951,25 @@ impl<'a> Checker<'a> {
     }
 
     fn bind_builtins(&mut self) {
-        let standard_builtins = python_builtins(
-            self.settings.target_version.minor(),
-            self.source_type.is_ipynb(),
-        );
-        for builtin in standard_builtins
-            .iter()
-            .chain(MAGIC_GLOBALS.iter())
-            .copied()
-            .chain(self.settings.builtins.iter().map(String::as_str))
-        {
+        let mut bind_builtin = |builtin| {
             // Add the builtin to the scope.
             let binding_id = self.semantic.push_builtin();
             let scope = self.semantic.global_scope_mut();
             scope.add(builtin, binding_id);
+        };
+
+        let standard_builtins = python_builtins(
+            self.settings.target_version.minor(),
+            self.source_type.is_ipynb(),
+        );
+        for builtin in standard_builtins {
+            bind_builtin(builtin);
+        }
+        for builtin in MAGIC_GLOBALS {
+            bind_builtin(builtin);
+        }
+        for builtin in &self.settings.builtins {
+            bind_builtin(builtin);
         }
     }
 

crates/ruff_linter/src/checkers/tokens.rs

@@ -63,7 +63,7 @@ pub(crate) fn check_tokens(
             ruff::rules::ambiguous_unicode_character_comment(
                 &mut diagnostics,
                 locator,
-                *range,
+                range,
                 settings,
             );
         }
@@ -154,7 +154,13 @@ pub(crate) fn check_tokens(
         Rule::ShebangNotFirstLine,
         Rule::ShebangMissingPython,
     ]) {
-        flake8_executable::rules::from_tokens(&mut diagnostics, path, locator, comment_ranges);
+        flake8_executable::rules::from_tokens(
+            &mut diagnostics,
+            path,
+            locator,
+            comment_ranges,
+            settings,
+        );
     }
 
     if settings.rules.any_enabled(&[

crates/ruff_linter/src/codes.rs

@@ -1067,6 +1067,7 @@ pub fn code_to_rule(linter: Linter, code: &str) -> Option<(RuleGroup, Rule)> {
         (Refurb, "180") => (RuleGroup::Preview, rules::refurb::rules::MetaClassABCMeta),
         (Refurb, "181") => (RuleGroup::Stable, rules::refurb::rules::HashlibDigestHex),
         (Refurb, "187") => (RuleGroup::Stable, rules::refurb::rules::ListReverseCopy),
+        (Refurb, "188") => (RuleGroup::Preview, rules::refurb::rules::SliceToRemovePrefixOrSuffix),
         (Refurb, "192") => (RuleGroup::Preview, rules::refurb::rules::SortedMinMax),
 
         // flake8-logging

crates/ruff_linter/src/message/sarif.rs

@@ -1,9 +1,9 @@
+use std::collections::HashSet;
 use std::io::Write;
 
 use anyhow::Result;
 use serde::{Serialize, Serializer};
 use serde_json::json;
-use strum::IntoEnumIterator;
 
 use ruff_source_file::OneIndexed;
 
@@ -27,6 +27,10 @@ impl Emitter for SarifEmitter {
             .map(SarifResult::from_message)
             .collect::<Result<Vec<_>>>()?;
 
+        let unique_rules: HashSet<_> = results.iter().filter_map(|result| result.rule).collect();
+        let mut rules: Vec<SarifRule> = unique_rules.into_iter().map(SarifRule::from).collect();
+        rules.sort_by(|a, b| a.code.cmp(&b.code));
+
         let output = json!({
             "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
             "version": "2.1.0",
@@ -35,7 +39,7 @@ impl Emitter for SarifEmitter {
                     "driver": {
                         "name": "ruff",
                         "informationUri": "https://github.com/astral-sh/ruff",
-                        "rules": Rule::iter().map(SarifRule::from).collect::<Vec<_>>(),
+                        "rules": rules,
                         "version": VERSION.to_string(),
                     }
                 },
@@ -182,7 +186,6 @@ impl Serialize for SarifResult {
 
 #[cfg(test)]
 mod tests {
-
     use crate::message::tests::{
         capture_emitter_output, create_messages, create_syntax_error_messages,
     };
@@ -209,16 +212,11 @@ mod tests {
     #[test]
     fn test_results() {
         let content = get_output();
-        let sarif = serde_json::from_str::<serde_json::Value>(content.as_str()).unwrap();
-        let rules = sarif["runs"][0]["tool"]["driver"]["rules"]
-            .as_array()
-            .unwrap();
-        let results = sarif["runs"][0]["results"].as_array().unwrap();
-        assert_eq!(results.len(), 3);
-        assert_eq!(
-            results[0]["message"]["text"].as_str().unwrap(),
-            "`os` imported but unused"
-        );
-        assert!(rules.len() > 3);
+        let value = serde_json::from_str::<serde_json::Value>(&content).unwrap();
+
+        insta::assert_json_snapshot!(value, {
+            ".runs[0].tool.driver.version" => "[VERSION]",
+            ".runs[0].results[].locations[].physicalLocation.artifactLocation.uri" => "[URI]",
+        });
     }
 }

crates/ruff_linter/src/message/snapshots/ruff_linter__message__sarif__tests__results.snap

@@ -0,0 +1,146 @@
+---
+source: crates/ruff_linter/src/message/sarif.rs
+expression: value
+---
+{
+  "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
+  "runs": [
+    {
+      "results": [
+        {
+          "level": "error",
+          "locations": [
+            {
+              "physicalLocation": {
+                "artifactLocation": {
+                  "uri": "[URI]"
+                },
+                "region": {
+                  "endColumn": 10,
+                  "endLine": 1,
+                  "startColumn": 8,
+                  "startLine": 1
+                }
+              }
+            }
+          ],
+          "message": {
+            "text": "`os` imported but unused"
+          },
+          "ruleId": "F401"
+        },
+        {
+          "level": "error",
+          "locations": [
+            {
+              "physicalLocation": {
+                "artifactLocation": {
+                  "uri": "[URI]"
+                },
+                "region": {
+                  "endColumn": 6,
+                  "endLine": 6,
+                  "startColumn": 5,
+                  "startLine": 6
+                }
+              }
+            }
+          ],
+          "message": {
+            "text": "Local variable `x` is assigned to but never used"
+          },
+          "ruleId": "F841"
+        },
+        {
+          "level": "error",
+          "locations": [
+            {
+              "physicalLocation": {
+                "artifactLocation": {
+                  "uri": "[URI]"
+                },
+                "region": {
+                  "endColumn": 5,
+                  "endLine": 1,
+                  "startColumn": 4,
+                  "startLine": 1
+                }
+              }
+            }
+          ],
+          "message": {
+            "text": "Undefined name `a`"
+          },
+          "ruleId": "F821"
+        }
+      ],
+      "tool": {
+        "driver": {
+          "informationUri": "https://github.com/astral-sh/ruff",
+          "name": "ruff",
+          "rules": [
+            {
+              "fullDescription": {
+                "text": "## What it does\nChecks for unused imports.\n\n## Why is this bad?\nUnused imports add a performance overhead at runtime, and risk creating\nimport cycles. They also increase the cognitive load of reading the code.\n\nIf an import statement is used to check for the availability or existence\nof a module, consider using `importlib.util.find_spec` instead.\n\nIf an import statement is used to re-export a symbol as part of a module's\npublic interface, consider using a \"redundant\" import alias, which\ninstructs Ruff (and other tools) to respect the re-export, and avoid\nmarking it as unused, as in:\n\n```python\nfrom module import member as member\n```\n\nAlternatively, you can use `__all__` to declare a symbol as part of the module's\ninterface, as in:\n\n```python\n# __init__.py\nimport some_module\n\n__all__ = [\"some_module\"]\n```\n\n## Fix safety\n\nFixes to remove unused imports are safe, except in `__init__.py` files.\n\nApplying fixes to `__init__.py` files is currently in preview. The fix offered depends on the\ntype of the unused import. Ruff will suggest a safe fix to export first-party imports with\neither a redundant alias or, if already present in the file, an `__all__` entry. If multiple\n`__all__` declarations are present, Ruff will not offer a fix. Ruff will suggest an unsafe fix\nto remove third-party and standard library imports -- the fix is unsafe because the module's\ninterface changes.\n\n## Example\n\n```python\nimport numpy as np  # unused import\n\n\ndef area(radius):\n    return 3.14 * radius**2\n```\n\nUse instead:\n\n```python\ndef area(radius):\n    return 3.14 * radius**2\n```\n\nTo check the availability of a module, use `importlib.util.find_spec`:\n\n```python\nfrom importlib.util import find_spec\n\nif find_spec(\"numpy\") is not None:\n    print(\"numpy is installed\")\nelse:\n    print(\"numpy is not installed\")\n```\n\n## Options\n- `lint.ignore-init-module-imports`\n\n## References\n- [Python documentation: `import`](https://docs.python.org/3/reference/simple_stmts.html#the-import-statement)\n- [Python documentation: `importlib.util.find_spec`](https://docs.python.org/3/library/importlib.html#importlib.util.find_spec)\n- [Typing documentation: interface conventions](https://typing.readthedocs.io/en/latest/source/libraries.html#library-interface-public-and-private-symbols)\n"
+              },
+              "help": {
+                "text": "`{name}` imported but unused; consider using `importlib.util.find_spec` to test for availability"
+              },
+              "helpUri": "https://docs.astral.sh/ruff/rules/unused-import",
+              "id": "F401",
+              "properties": {
+                "id": "F401",
+                "kind": "Pyflakes",
+                "name": "unused-import",
+                "problem.severity": "error"
+              },
+              "shortDescription": {
+                "text": "`{name}` imported but unused; consider using `importlib.util.find_spec` to test for availability"
+              }
+            },
+            {
+              "fullDescription": {
+                "text": "## What it does\nChecks for uses of undefined names.\n\n## Why is this bad?\nAn undefined name is likely to raise `NameError` at runtime.\n\n## Example\n```python\ndef double():\n    return n * 2  # raises `NameError` if `n` is undefined when `double` is called\n```\n\nUse instead:\n```python\ndef double(n):\n    return n * 2\n```\n\n## Options\n- [`target-version`]: Can be used to configure which symbols Ruff will understand\n  as being available in the `builtins` namespace.\n\n## References\n- [Python documentation: Naming and binding](https://docs.python.org/3/reference/executionmodel.html#naming-and-binding)\n"
+              },
+              "help": {
+                "text": "Undefined name `{name}`. {tip}"
+              },
+              "helpUri": "https://docs.astral.sh/ruff/rules/undefined-name",
+              "id": "F821",
+              "properties": {
+                "id": "F821",
+                "kind": "Pyflakes",
+                "name": "undefined-name",
+                "problem.severity": "error"
+              },
+              "shortDescription": {
+                "text": "Undefined name `{name}`. {tip}"
+              }
+            },
+            {
+              "fullDescription": {
+                "text": "## What it does\nChecks for the presence of unused variables in function scopes.\n\n## Why is this bad?\nA variable that is defined but not used is likely a mistake, and should\nbe removed to avoid confusion.\n\nIf a variable is intentionally defined-but-not-used, it should be\nprefixed with an underscore, or some other value that adheres to the\n[`lint.dummy-variable-rgx`] pattern.\n\nUnder [preview mode](https://docs.astral.sh/ruff/preview), this rule also\ntriggers on unused unpacked assignments (for example, `x, y = foo()`).\n\n## Example\n```python\ndef foo():\n    x = 1\n    y = 2\n    return x\n```\n\nUse instead:\n```python\ndef foo():\n    x = 1\n    return x\n```\n\n## Options\n- `lint.dummy-variable-rgx`\n"
+              },
+              "help": {
+                "text": "Local variable `{name}` is assigned to but never used"
+              },
+              "helpUri": "https://docs.astral.sh/ruff/rules/unused-variable",
+              "id": "F841",
+              "properties": {
+                "id": "F841",
+                "kind": "Pyflakes",
+                "name": "unused-variable",
+                "problem.severity": "error"
+              },
+              "shortDescription": {
+                "text": "Local variable `{name}` is assigned to but never used"
+              }
+            }
+          ],
+          "version": "[VERSION]"
+        }
+      }
+    }
+  ],
+  "version": "2.1.0"
+}

crates/ruff_linter/src/noqa.rs

@@ -361,7 +361,7 @@ impl<'a> FileNoqaDirectives<'a> {
         let mut lines = vec![];
 
         for range in comment_ranges {
-            match ParsedFileExemption::try_extract(&contents[*range]) {
+            match ParsedFileExemption::try_extract(&contents[range]) {
                 Err(err) => {
                     #[allow(deprecated)]
                     let line = locator.compute_line_index(range.start());
@@ -403,7 +403,7 @@ impl<'a> FileNoqaDirectives<'a> {
                     };
 
                     lines.push(FileNoqaDirectiveLine {
-                        range: *range,
+                        range,
                         parsed_file_exemption: exemption,
                         matches,
                     });
@@ -922,7 +922,7 @@ impl<'a> NoqaDirectives<'a> {
         let mut directives = Vec::new();
 
         for range in comment_ranges {
-            match Directive::try_extract(locator.slice(*range), range.start()) {
+            match Directive::try_extract(locator.slice(range), range.start()) {
                 Err(err) => {
                     #[allow(deprecated)]
                     let line = locator.compute_line_index(range.start());

crates/ruff_linter/src/rules/eradicate/rules/commented_out_code.rs

@@ -1,9 +1,9 @@
+use crate::settings::LinterSettings;
 use ruff_diagnostics::{Diagnostic, Edit, Fix, FixAvailability, Violation};
 use ruff_macros::{derive_message_formats, violation};
 use ruff_python_trivia::CommentRanges;
-use ruff_source_file::Locator;
-
-use crate::settings::LinterSettings;
+use ruff_source_file::{Locator, UniversalNewlineIterator};
+use ruff_text_size::TextRange;
 
 use super::super::detection::comment_contains_code;
 
@@ -50,40 +50,110 @@ pub(crate) fn commented_out_code(
     comment_ranges: &CommentRanges,
     settings: &LinterSettings,
 ) {
-    // Skip comments within `/// script` tags.
-    let mut in_script_tag = false;
-
+    let mut comments = comment_ranges.into_iter().peekable();
     // Iterate over all comments in the document.
-    for range in comment_ranges {
-        let line = locator.lines(*range);
+    while let Some(range) = comments.next() {
+        let line = locator.line(range.start());
 
-        // Detect `/// script` tags.
-        if in_script_tag {
-            if is_script_tag_end(line) {
-                in_script_tag = false;
+        if is_script_tag_start(line) {
+            if skip_script_comments(range, &mut comments, locator) {
+                continue;
             }
-        } else {
-            if is_script_tag_start(line) {
-                in_script_tag = true;
-            }
-        }
-
-        // Skip comments within `/// script` tags.
-        if in_script_tag {
-            continue;
         }
 
         // Verify that the comment is on its own line, and that it contains code.
         if is_own_line_comment(line) && comment_contains_code(line, &settings.task_tags[..]) {
-            let mut diagnostic = Diagnostic::new(CommentedOutCode, *range);
+            let mut diagnostic = Diagnostic::new(CommentedOutCode, range);
             diagnostic.set_fix(Fix::display_only_edit(Edit::range_deletion(
-                locator.full_lines_range(*range),
+                locator.full_lines_range(range),
             )));
             diagnostics.push(diagnostic);
         }
     }
 }
 
+/// Parses the rest of a [PEP 723](https://peps.python.org/pep-0723/)
+/// script comment and moves `comments` past the script comment's end unless
+/// the script comment is invalid.
+///
+/// Returns `true` if it is a valid script comment.
+fn skip_script_comments<I>(
+    script_start: TextRange,
+    comments: &mut std::iter::Peekable<I>,
+    locator: &Locator,
+) -> bool
+where
+    I: Iterator<Item = TextRange>,
+{
+    let line_end = locator.full_line_end(script_start.end());
+    let rest = locator.after(line_end);
+    let mut end_offset = None;
+    let mut lines = UniversalNewlineIterator::with_offset(rest, line_end).peekable();
+
+    while let Some(line) = lines.next() {
+        let Some(content) = script_line_content(&line) else {
+            break;
+        };
+
+        if content == "///" {
+            // > Precedence for an ending line # /// is given when the next line is not a valid
+            // > embedded content line as described above.
+            // > For example, the following is a single fully valid block:
+            // > ```python
+            // > # /// some-toml
+            // > # embedded-csharp = """
+            // > # /// <summary>
+            // > # /// text
+            // > # ///
+            // > # /// </summary>
+            // > # public class MyClass { }
+            // > # """
+            // > # ///
+            // ````
+            if lines.next().is_some_and(|line| is_valid_script_line(&line)) {
+                continue;
+            }
+            end_offset = Some(line.full_end());
+            break;
+        }
+    }
+
+    // > Unclosed blocks MUST be ignored.
+    let Some(end_offset) = end_offset else {
+        return false;
+    };
+
+    // Skip over all script-comments.
+    while let Some(comment) = comments.peek() {
+        if comment.start() >= end_offset {
+            break;
+        }
+
+        comments.next();
+    }
+
+    true
+}
+
+fn script_line_content(line: &str) -> Option<&str> {
+    let Some(rest) = line.strip_prefix('#') else {
+        // Not a comment
+        return None;
+    };
+
+    // An empty line
+    if rest.is_empty() {
+        return Some("");
+    }
+
+    // > If there are characters after the # then the first character MUST be a space.
+    rest.strip_prefix(' ')
+}
+
+fn is_valid_script_line(line: &str) -> bool {
+    script_line_content(line).is_some()
+}
+
 /// Returns `true` if line contains an own-line comment.
 fn is_own_line_comment(line: &str) -> bool {
     for char in line.chars() {
@@ -104,9 +174,77 @@ fn is_script_tag_start(line: &str) -> bool {
     line == "# /// script"
 }
 
-/// Returns `true` if the line appears to start a script tag.
-///
-/// See: <https://peps.python.org/pep-0723/>
-fn is_script_tag_end(line: &str) -> bool {
-    line == "# ///"
+#[cfg(test)]
+mod tests {
+    use crate::rules::eradicate::rules::commented_out_code::skip_script_comments;
+    use ruff_python_parser::parse_module;
+    use ruff_python_trivia::CommentRanges;
+    use ruff_source_file::Locator;
+    use ruff_text_size::TextSize;
+    #[test]
+    fn script_comment() {
+        let code = r#"
+# /// script
+# requires-python = ">=3.11"
+# dependencies = [
+#   "requests<3",
+#   "rich",
+# ]
+# ///
+
+a = 10 # abc
+        "#;
+
+        let parsed = parse_module(code).unwrap();
+        let locator = Locator::new(code);
+
+        let comments = CommentRanges::from(parsed.tokens());
+        let mut comments = comments.into_iter().peekable();
+
+        let script_start = code.find("# /// script").unwrap();
+        let script_start_range = locator.full_line_range(TextSize::try_from(script_start).unwrap());
+
+        let valid = skip_script_comments(script_start_range, &mut comments, &Locator::new(code));
+
+        assert!(valid);
+
+        let next_comment = comments.next();
+
+        assert!(next_comment.is_some());
+        assert_eq!(&code[next_comment.unwrap()], "# abc");
+    }
+
+    #[test]
+    fn script_comment_end_precedence() {
+        let code = r#"
+# /// script
+# [tool.uv]
+# extra-index-url = ["https://pypi.org/simple", """\
+# https://example.com/
+# ///
+# """
+# ]
+# ///
+
+a = 10 # abc
+        "#;
+
+        let parsed = parse_module(code).unwrap();
+        let locator = Locator::new(code);
+
+        let comments = CommentRanges::from(parsed.tokens());
+        let mut comments = comments.into_iter().peekable();
+
+        let script_start = code.find("# /// script").unwrap();
+        let script_start_range = locator.full_line_range(TextSize::try_from(script_start).unwrap());
+
+        let valid = skip_script_comments(script_start_range, &mut comments, &Locator::new(code));
+
+        assert!(valid);
+
+        let next_comment = comments.next();
+
+        assert!(next_comment.is_some());
+        assert_eq!(&code[next_comment.unwrap()], "# abc");
+    }
 }

crates/ruff_linter/src/rules/eradicate/snapshots/ruff_linter__rules__eradicate__tests__ERA001_ERA001.py.snap

@@ -321,3 +321,38 @@ ERA001.py:47:1: ERA001 Found commented-out code
 48 47 | # ///
 49 48 | 
 50 49 | # Script tag (OK)
+
+ERA001.py:75:1: ERA001 Found commented-out code
+   |
+73 | # /// script
+74 | # requires-python = ">=3.11"
+75 | # dependencies = [
+   | ^^^^^^^^^^^^^^^^^^ ERA001
+76 | #   "requests<3",
+77 | #   "rich",
+   |
+   = help: Remove commented-out code
+
+ℹ Display-only fix
+72 72 | 
+73 73 | # /// script
+74 74 | # requires-python = ">=3.11"
+75    |-# dependencies = [
+76 75 | #   "requests<3",
+77 76 | #   "rich",
+78 77 | # ]
+
+ERA001.py:78:1: ERA001 Found commented-out code
+   |
+76 | #   "requests<3",
+77 | #   "rich",
+78 | # ]
+   | ^^^ ERA001
+   |
+   = help: Remove commented-out code
+
+ℹ Display-only fix
+75 75 | # dependencies = [
+76 76 | #   "requests<3",
+77 77 | #   "rich",
+78    |-# ]

crates/ruff_linter/src/rules/flake8_executable/rules/mod.rs

@@ -1,5 +1,8 @@
 use std::path::Path;
 
+use crate::codes::Rule;
+use crate::comments::shebang::ShebangDirective;
+use crate::settings::LinterSettings;
 use ruff_diagnostics::Diagnostic;
 use ruff_python_trivia::CommentRanges;
 use ruff_source_file::Locator;
@@ -9,8 +12,6 @@ pub(crate) use shebang_missing_python::*;
 pub(crate) use shebang_not_executable::*;
 pub(crate) use shebang_not_first_line::*;
 
-use crate::comments::shebang::ShebangDirective;
-
 mod shebang_leading_whitespace;
 mod shebang_missing_executable_file;
 mod shebang_missing_python;
@@ -22,34 +23,39 @@ pub(crate) fn from_tokens(
     path: &Path,
     locator: &Locator,
     comment_ranges: &CommentRanges,
+    settings: &LinterSettings,
 ) {
     let mut has_any_shebang = false;
     for range in comment_ranges {
-        let comment = locator.slice(*range);
+        let comment = locator.slice(range);
         if let Some(shebang) = ShebangDirective::try_extract(comment) {
             has_any_shebang = true;
 
-            if let Some(diagnostic) = shebang_missing_python(*range, &shebang) {
+            if let Some(diagnostic) = shebang_missing_python(range, &shebang) {
                 diagnostics.push(diagnostic);
             }
 
-            if let Some(diagnostic) = shebang_not_executable(path, *range) {
+            if settings.rules.enabled(Rule::ShebangNotExecutable) {
+                if let Some(diagnostic) = shebang_not_executable(path, range) {
+                    diagnostics.push(diagnostic);
+                }
+            }
+
+            if let Some(diagnostic) = shebang_leading_whitespace(range, locator) {
                 diagnostics.push(diagnostic);
             }
 
-            if let Some(diagnostic) = shebang_leading_whitespace(*range, locator) {
-                diagnostics.push(diagnostic);
-            }
-
-            if let Some(diagnostic) = shebang_not_first_line(*range, locator) {
+            if let Some(diagnostic) = shebang_not_first_line(range, locator) {
                 diagnostics.push(diagnostic);
             }
         }
     }
 
     if !has_any_shebang {
-        if let Some(diagnostic) = shebang_missing_executable_file(path) {
-            diagnostics.push(diagnostic);
+        if settings.rules.enabled(Rule::ShebangMissingExecutableFile) {
+            if let Some(diagnostic) = shebang_missing_executable_file(path) {
+                diagnostics.push(diagnostic);
+            }
         }
     }
 }

crates/ruff_linter/src/rules/flake8_pyi/rules/type_comment_in_stub.rs

@@ -41,10 +41,10 @@ pub(crate) fn type_comment_in_stub(
     comment_ranges: &CommentRanges,
 ) {
     for range in comment_ranges {
-        let comment = locator.slice(*range);
+        let comment = locator.slice(range);
 
         if TYPE_COMMENT_REGEX.is_match(comment) && !TYPE_IGNORE_REGEX.is_match(comment) {
-            diagnostics.push(Diagnostic::new(TypeCommentInStub, *range));
+            diagnostics.push(Diagnostic::new(TypeCommentInStub, range));
         }
     }
 }

crates/ruff_linter/src/rules/isort/rules/add_required_imports.rs

@@ -35,6 +35,9 @@ use crate::settings::LinterSettings;
 ///
 /// import typing
 /// ```
+///
+/// ## Options
+/// - `lint.isort.required-imports`
 #[violation]
 pub struct MissingRequiredImport(pub String);
 

crates/ruff_linter/src/rules/pydoclint/rules/check_docstring.rs

@@ -741,6 +741,10 @@ fn returns_documented(
         || (matches!(convention, Some(Convention::Google)) && starts_with_returns(docstring))
 }
 
+fn should_document_returns(function_def: &ast::StmtFunctionDef) -> bool {
+    !matches!(function_def.name.as_str(), "__new__")
+}
+
 fn starts_with_yields(docstring: &Docstring) -> bool {
     if let Some(first_word) = docstring.body().as_str().split(' ').next() {
         return matches!(first_word, "Yield" | "Yields");
@@ -868,7 +872,9 @@ pub(crate) fn check_docstring(
 
     // DOC201
     if checker.enabled(Rule::DocstringMissingReturns) {
-        if !returns_documented(docstring, &docstring_sections, convention) {
+        if should_document_returns(function_def)
+            && !returns_documented(docstring, &docstring_sections, convention)
+        {
             let extra_property_decorators = checker.settings.pydocstyle.property_decorators();
             if !definition.is_property(extra_property_decorators, semantic) {
                 if let Some(body_return) = body_entries.returns.first() {

crates/ruff_linter/src/rules/pydocstyle/rules/triple_quotes.rs

@@ -67,9 +67,7 @@ impl Violation for TripleSingleQuotes {
 pub(crate) fn triple_quotes(checker: &mut Checker, docstring: &Docstring) {
     let leading_quote = docstring.leading_quote();
 
-    let prefixes = leading_quote
-        .trim_end_matches(|c| c == '\'' || c == '"')
-        .to_owned();
+    let prefixes = leading_quote.trim_end_matches(['\'', '"']).to_owned();
 
     let expected_quote = if docstring.body().contains("\"\"\"") {
         if docstring.body().contains("\'\'\'") {

crates/ruff_linter/src/rules/pyflakes/mod.rs

@@ -208,6 +208,18 @@ mod tests {
         Ok(())
     }
 
+    #[test]
+    fn f821_with_builtin_added_on_new_py_version_but_old_target_version_specified() {
+        let diagnostics = test_snippet(
+            "PythonFinalizationError",
+            &LinterSettings {
+                target_version: crate::settings::types::PythonVersion::Py312,
+                ..LinterSettings::for_rule(Rule::UndefinedName)
+            },
+        );
+        assert_messages!(diagnostics);
+    }
+
     #[test_case(Rule::UnusedVariable, Path::new("F841_4.py"))]
     #[test_case(Rule::UnusedImport, Path::new("__init__.py"))]
     #[test_case(Rule::UnusedImport, Path::new("F401_24/__init__.py"))]

crates/ruff_linter/src/rules/pyflakes/rules/undefined_name.rs

@@ -19,17 +19,35 @@ use ruff_macros::{derive_message_formats, violation};
 ///     return n * 2
 /// ```
 ///
+/// ## Options
+/// - [`target-version`]: Can be used to configure which symbols Ruff will understand
+///   as being available in the `builtins` namespace.
+///
 /// ## References
 /// - [Python documentation: Naming and binding](https://docs.python.org/3/reference/executionmodel.html#naming-and-binding)
 #[violation]
 pub struct UndefinedName {
     pub(crate) name: String,
+    pub(crate) minor_version_builtin_added: Option<u8>,
 }
 
 impl Violation for UndefinedName {
     #[derive_message_formats]
     fn message(&self) -> String {
-        let UndefinedName { name } = self;
-        format!("Undefined name `{name}`")
+        let UndefinedName {
+            name,
+            minor_version_builtin_added,
+        } = self;
+        let tip = minor_version_builtin_added.map(|version_added| {
+            format!(
+                r#"Consider specifying `requires-python = ">= 3.{version_added}"` or `tool.ruff.target-version = "py3{version_added}"` in your `pyproject.toml` file."#
+            )
+        });
+
+        if let Some(tip) = tip {
+            format!("Undefined name `{name}`. {tip}")
+        } else {
+            format!("Undefined name `{name}`")
+        }
     }
 }

crates/ruff_linter/src/rules/pyflakes/snapshots/ruff_linter__rules__pyflakes__tests__f821_with_builtin_added_on_new_py_version_but_old_target_version_specified.snap

@@ -0,0 +1,8 @@
+---
+source: crates/ruff_linter/src/rules/pyflakes/mod.rs
+---
+<filename>:1:1: F821 Undefined name `PythonFinalizationError`. Consider specifying `requires-python = ">= 3.13"` or `tool.ruff.target-version = "py313"` in your `pyproject.toml` file.
+  |
+1 | PythonFinalizationError
+  | ^^^^^^^^^^^^^^^^^^^^^^^ F821
+  |

crates/ruff_linter/src/rules/pygrep_hooks/rules/blanket_type_ignore.rs

@@ -55,7 +55,7 @@ pub(crate) fn blanket_type_ignore(
     locator: &Locator,
 ) {
     for range in comment_ranges {
-        let line = locator.slice(*range);
+        let line = locator.slice(range);
 
         // Match, e.g., `# type: ignore` or `# type: ignore[attr-defined]`.
         // See: https://github.com/python/mypy/blob/b43e0d34247a6d1b3b9d9094d184bbfcb9808bb9/mypy/fastparse.py#L248

crates/ruff_linter/src/rules/pylint/rules/empty_comment.rs

@@ -56,7 +56,7 @@ pub(crate) fn empty_comments(
         }
 
         // If the line contains an empty comment, add a diagnostic.
-        if let Some(diagnostic) = empty_comment(*range, locator) {
+        if let Some(diagnostic) = empty_comment(range, locator) {
             diagnostics.push(diagnostic);
         }
     }

crates/ruff_linter/src/rules/pyupgrade/rules/deprecated_unittest_alias.rs

@@ -13,7 +13,7 @@ use crate::checkers::ast::Checker;
 ///
 /// ## Why is this bad?
 /// The `unittest` module has deprecated aliases for some of its methods.
-/// The aliases may be removed in future versions of Python. Instead,
+/// The deprecated aliases were removed in Python 3.12. Instead of aliases,
 /// use their non-deprecated counterparts.
 ///
 /// ## Example
@@ -37,7 +37,7 @@ use crate::checkers::ast::Checker;
 /// ```
 ///
 /// ## References
-/// - [Python documentation: Deprecated aliases](https://docs.python.org/3/library/unittest.html#deprecated-aliases)
+/// - [Python 3.11 documentation: Deprecated aliases](https://docs.python.org/3.11/library/unittest.html#deprecated-aliases)
 #[violation]
 pub struct DeprecatedUnittestAlias {
     alias: String,

crates/ruff_linter/src/rules/refurb/mod.rs

@@ -46,6 +46,7 @@ mod tests {
     #[test_case(Rule::WriteWholeFile, Path::new("FURB103.py"))]
     #[test_case(Rule::FStringNumberFormat, Path::new("FURB116.py"))]
     #[test_case(Rule::SortedMinMax, Path::new("FURB192.py"))]
+    #[test_case(Rule::SliceToRemovePrefixOrSuffix, Path::new("FURB188.py"))]
     fn rules(rule_code: Rule, path: &Path) -> Result<()> {
         let snapshot = format!("{}_{}", rule_code.noqa_code(), path.to_string_lossy());
         let diagnostics = test_path(

crates/ruff_linter/src/rules/refurb/rules/mod.rs

@@ -23,6 +23,7 @@ pub(crate) use repeated_append::*;
 pub(crate) use repeated_global::*;
 pub(crate) use single_item_membership_test::*;
 pub(crate) use slice_copy::*;
+pub(crate) use slice_to_remove_prefix_or_suffix::*;
 pub(crate) use sorted_min_max::*;
 pub(crate) use type_none_comparison::*;
 pub(crate) use unnecessary_enumerate::*;
@@ -55,6 +56,7 @@ mod repeated_append;
 mod repeated_global;
 mod single_item_membership_test;
 mod slice_copy;
+mod slice_to_remove_prefix_or_suffix;
 mod sorted_min_max;
 mod type_none_comparison;
 mod unnecessary_enumerate;

crates/ruff_linter/src/rules/refurb/rules/slice_to_remove_prefix_or_suffix.rs

@@ -0,0 +1,474 @@
+use crate::{checkers::ast::Checker, settings::types::PythonVersion};
+use ruff_diagnostics::{AlwaysFixableViolation, Diagnostic, Edit, Fix};
+use ruff_macros::{derive_message_formats, violation};
+use ruff_python_ast as ast;
+use ruff_python_semantic::SemanticModel;
+use ruff_source_file::Locator;
+use ruff_text_size::{Ranged, TextLen};
+
+/// ## What it does
+/// Checks for the removal of a prefix or suffix from a string by assigning
+/// the string to a slice after checking `.startswith()` or `.endswith()`, respectively.
+///
+/// ## Why is this bad?
+/// The methods [`str.removeprefix`] and [`str.removesuffix`],
+/// introduced in Python 3.9, have the same behavior
+/// and are more readable and efficient.
+///
+/// ## Example
+/// ```python
+/// filename[:-4] if filename.endswith(".txt") else filename
+/// ```
+///
+/// ```python
+/// if text.startswith("pre"):
+///     text = text[3:]
+/// ```
+///
+/// Use instead:
+/// ```python
+/// filename = filename.removesuffix(".txt")
+/// ```
+///
+/// ```python
+/// text = text.removeprefix("pre")
+/// ```
+///
+/// [`str.removeprefix`]: https://docs.python.org/3/library/stdtypes.html#str.removeprefix
+/// [`str.removesuffix`]: https://docs.python.org/3/library/stdtypes.html#str.removesuffix
+#[violation]
+pub struct SliceToRemovePrefixOrSuffix {
+    string: String,
+    affix_kind: AffixKind,
+    stmt_or_expression: StmtOrExpr,
+}
+
+impl AlwaysFixableViolation for SliceToRemovePrefixOrSuffix {
+    #[derive_message_formats]
+    fn message(&self) -> String {
+        match self.affix_kind {
+            AffixKind::StartsWith => {
+                format!("Prefer `removeprefix` over conditionally replacing with slice.")
+            }
+            AffixKind::EndsWith => {
+                format!("Prefer `removesuffix` over conditionally replacing with slice.")
+            }
+        }
+    }
+
+    fn fix_title(&self) -> String {
+        let method_name = self.affix_kind.as_str();
+        let replacement = self.affix_kind.replacement();
+        let context = match self.stmt_or_expression {
+            StmtOrExpr::Statement => "assignment",
+            StmtOrExpr::Expression => "ternary expression",
+        };
+        format!("Use {replacement} instead of {context} conditional upon {method_name}.")
+    }
+}
+
+/// FURB188
+pub(crate) fn slice_to_remove_affix_expr(checker: &mut Checker, if_expr: &ast::ExprIf) {
+    if checker.settings.target_version < PythonVersion::Py39 {
+        return;
+    }
+
+    if let Some(removal_data) = affix_removal_data_expr(if_expr) {
+        if affix_matches_slice_bound(&removal_data, checker.semantic()) {
+            let kind = removal_data.affix_query.kind;
+            let text = removal_data.text;
+
+            let mut diagnostic = Diagnostic::new(
+                SliceToRemovePrefixOrSuffix {
+                    affix_kind: kind,
+                    string: checker.locator().slice(text).to_string(),
+                    stmt_or_expression: StmtOrExpr::Expression,
+                },
+                if_expr.range,
+            );
+            let replacement =
+                generate_removeaffix_expr(text, &removal_data.affix_query, checker.locator());
+
+            diagnostic.set_fix(Fix::safe_edit(Edit::replacement(
+                replacement,
+                if_expr.start(),
+                if_expr.end(),
+            )));
+            checker.diagnostics.push(diagnostic);
+        }
+    }
+}
+
+/// FURB188
+pub(crate) fn slice_to_remove_affix_stmt(checker: &mut Checker, if_stmt: &ast::StmtIf) {
+    if checker.settings.target_version < PythonVersion::Py39 {
+        return;
+    }
+    if let Some(removal_data) = affix_removal_data_stmt(if_stmt) {
+        if affix_matches_slice_bound(&removal_data, checker.semantic()) {
+            let kind = removal_data.affix_query.kind;
+            let text = removal_data.text;
+
+            let mut diagnostic = Diagnostic::new(
+                SliceToRemovePrefixOrSuffix {
+                    affix_kind: kind,
+                    string: checker.locator().slice(text).to_string(),
+                    stmt_or_expression: StmtOrExpr::Statement,
+                },
+                if_stmt.range,
+            );
+
+            let replacement = generate_assignment_with_removeaffix(
+                text,
+                &removal_data.affix_query,
+                checker.locator(),
+            );
+
+            diagnostic.set_fix(Fix::safe_edit(Edit::replacement(
+                replacement,
+                if_stmt.start(),
+                if_stmt.end(),
+            )));
+            checker.diagnostics.push(diagnostic);
+        }
+    }
+}
+
+/// Given an expression of the form:
+///
+/// ```python
+/// text[slice] if text.func(affix) else text
+/// ```
+///
+/// where `func` is either `startswith` or `endswith`,
+/// this function collects `text`,`func`, `affix`, and the non-null
+/// bound of the slice. Otherwise, returns `None`.
+fn affix_removal_data_expr(if_expr: &ast::ExprIf) -> Option<RemoveAffixData> {
+    let ast::ExprIf {
+        test,
+        body,
+        orelse,
+        range: _,
+    } = if_expr;
+
+    let ast::ExprSubscript { value, slice, .. } = body.as_subscript_expr()?;
+    // Variable names correspond to:
+    // ```python
+    // value[slice] if test else orelse
+    // ```
+    affix_removal_data(value, test, orelse, slice)
+}
+
+/// Given a statement of the form:
+///
+/// ```python
+///  if text.func(affix):
+///     text = text[slice]
+/// ```
+///
+/// where `func` is either `startswith` or `endswith`,
+/// this function collects `text`,`func`, `affix`, and the non-null
+/// bound of the slice. Otherwise, returns `None`.
+fn affix_removal_data_stmt(if_stmt: &ast::StmtIf) -> Option<RemoveAffixData> {
+    let ast::StmtIf {
+        test,
+        body,
+        elif_else_clauses,
+        range: _,
+    } = if_stmt;
+
+    // Cannot safely transform, e.g.,
+    // ```python
+    // if text.startswith(prefix):
+    //     text = text[len(prefix):]
+    // else:
+    //     text = "something completely different"
+    // ```
+    if !elif_else_clauses.is_empty() {
+        return None;
+    };
+
+    // Cannot safely transform, e.g.,
+    // ```python
+    // if text.startswith(prefix):
+    //     text = f"{prefix} something completely different"
+    //     text = text[len(prefix):]
+    // ```
+    let [statement] = body.as_slice() else {
+        return None;
+    };
+
+    // Variable names correspond to:
+    // ```python
+    // if test:
+    //     else_or_target_name = value[slice]
+    // ```
+    let ast::StmtAssign {
+        value,
+        targets,
+        range: _,
+    } = statement.as_assign_stmt()?;
+    let [target] = targets.as_slice() else {
+        return None;
+    };
+    let ast::ExprSubscript { value, slice, .. } = value.as_subscript_expr()?;
+
+    affix_removal_data(value, test, target, slice)
+}
+
+/// Suppose given a statement of the form:
+/// ```python
+/// if test:
+///     else_or_target_name = value[slice]
+/// ```
+/// or an expression of the form:
+/// ```python
+/// value[slice] if test else else_or_target_name
+/// ```
+/// This function verifies that
+///   - `value` and `else_or_target_name`
+///     are equal to a common name `text`
+///   - `test` is of the form `text.startswith(prefix)`
+///     or `text.endswith(suffix)`
+///   - `slice` has no upper bound in the case of a prefix,
+///     and no lower bound in the case of a suffix
+///
+/// If these conditions are satisfied, the function
+/// returns the corresponding `RemoveAffixData` object;
+/// otherwise it returns `None`.
+fn affix_removal_data<'a>(
+    value: &'a ast::Expr,
+    test: &'a ast::Expr,
+    else_or_target: &'a ast::Expr,
+    slice: &'a ast::Expr,
+) -> Option<RemoveAffixData<'a>> {
+    let compr_value = ast::comparable::ComparableExpr::from(value);
+    let compr_else_or_target = ast::comparable::ComparableExpr::from(else_or_target);
+    if compr_value != compr_else_or_target {
+        return None;
+    }
+    let slice = slice.as_slice_expr()?;
+    let compr_test_expr = ast::comparable::ComparableExpr::from(
+        &test.as_call_expr()?.func.as_attribute_expr()?.value,
+    );
+    let func_name = test
+        .as_call_expr()?
+        .func
+        .as_attribute_expr()?
+        .attr
+        .id
+        .as_str();
+
+    let func_args = &test.as_call_expr()?.arguments.args;
+
+    let [affix] = func_args.as_ref() else {
+        return None;
+    };
+    if compr_value != compr_test_expr || compr_test_expr != compr_else_or_target {
+        return None;
+    }
+    let (affix_kind, bound) = match func_name {
+        "startswith" if slice.upper.is_none() => (AffixKind::StartsWith, slice.lower.as_ref()?),
+        "endswith" if slice.lower.is_none() => (AffixKind::EndsWith, slice.upper.as_ref()?),
+        _ => return None,
+    };
+    Some(RemoveAffixData {
+        text: value,
+        bound,
+        affix_query: AffixQuery {
+            kind: affix_kind,
+            affix,
+        },
+    })
+}
+
+/// Tests whether the slice of the given string actually removes the
+/// detected affix.
+///
+/// For example, in the situation
+///
+/// ```python
+///  text[:bound] if text.endswith(suffix) else text
+/// ```
+///
+/// This function verifies that `bound == -len(suffix)` in two cases:
+///   - `suffix` is a string literal and `bound` is a number literal
+///   - `suffix` is an expression and `bound` is
+///     exactly `-len(suffix)` (as AST nodes, prior to evaluation.)
+fn affix_matches_slice_bound(data: &RemoveAffixData, semantic: &SemanticModel) -> bool {
+    let RemoveAffixData {
+        text: _,
+        bound,
+        affix_query: AffixQuery { kind, affix },
+    } = *data;
+
+    match (kind, bound, affix) {
+        (
+            AffixKind::StartsWith,
+            ast::Expr::NumberLiteral(ast::ExprNumberLiteral {
+                value: num,
+                range: _,
+            }),
+            ast::Expr::StringLiteral(ast::ExprStringLiteral {
+                range: _,
+                value: string_val,
+            }),
+        ) => num
+            .as_int()
+            .and_then(ast::Int::as_u32) // Only support prefix removal for size at most `u32::MAX`
+            .is_some_and(|x| x == string_val.to_str().text_len().to_u32()),
+        (
+            AffixKind::StartsWith,
+            ast::Expr::Call(ast::ExprCall {
+                range: _,
+                func,
+                arguments,
+            }),
+            _,
+        ) => {
+            arguments.len() == 1
+                && arguments.find_positional(0).is_some_and(|arg| {
+                    let compr_affix = ast::comparable::ComparableExpr::from(affix);
+                    let compr_arg = ast::comparable::ComparableExpr::from(arg);
+                    compr_affix == compr_arg
+                })
+                && semantic.match_builtin_expr(func, "len")
+        }
+        (
+            AffixKind::EndsWith,
+            ast::Expr::UnaryOp(ast::ExprUnaryOp {
+                op: ast::UnaryOp::USub,
+                operand,
+                range: _,
+            }),
+            ast::Expr::StringLiteral(ast::ExprStringLiteral {
+                range: _,
+                value: string_val,
+            }),
+        ) => operand.as_number_literal_expr().is_some_and(
+            |ast::ExprNumberLiteral { value, .. }| {
+                // Only support prefix removal for size at most `u32::MAX`
+                value
+                    .as_int()
+                    .and_then(ast::Int::as_u32)
+                    .is_some_and(|x| x == string_val.to_str().text_len().to_u32())
+            },
+        ),
+        (
+            AffixKind::EndsWith,
+            ast::Expr::UnaryOp(ast::ExprUnaryOp {
+                op: ast::UnaryOp::USub,
+                operand,
+                range: _,
+            }),
+            _,
+        ) => operand.as_call_expr().is_some_and(
+            |ast::ExprCall {
+                 range: _,
+                 func,
+                 arguments,
+             }| {
+                arguments.len() == 1
+                    && arguments.find_positional(0).is_some_and(|arg| {
+                        let compr_affix = ast::comparable::ComparableExpr::from(affix);
+                        let compr_arg = ast::comparable::ComparableExpr::from(arg);
+                        compr_affix == compr_arg
+                    })
+                    && semantic.match_builtin_expr(func, "len")
+            },
+        ),
+        _ => false,
+    }
+}
+
+/// Generates the source code string
+/// ```python
+/// text = text.removeprefix(prefix)
+/// ```
+/// or
+/// ```python
+/// text = text.removesuffix(prefix)
+/// ```
+/// as appropriate.
+fn generate_assignment_with_removeaffix(
+    text: &ast::Expr,
+    affix_query: &AffixQuery,
+    locator: &Locator,
+) -> String {
+    let text_str = locator.slice(text);
+    let affix_str = locator.slice(affix_query.affix);
+    let replacement = affix_query.kind.replacement();
+    format!("{text_str} = {text_str}.{replacement}({affix_str})")
+}
+
+/// Generates the source code string
+/// ```python
+/// text.removeprefix(prefix)
+/// ```
+/// or
+///
+/// ```python
+/// text.removesuffix(suffix)
+/// ```
+/// as appropriate.
+fn generate_removeaffix_expr(
+    text: &ast::Expr,
+    affix_query: &AffixQuery,
+    locator: &Locator,
+) -> String {
+    let text_str = locator.slice(text);
+    let affix_str = locator.slice(affix_query.affix);
+    let replacement = affix_query.kind.replacement();
+    format!("{text_str}.{replacement}({affix_str})")
+}
+
+#[derive(Debug, PartialEq, Eq, Clone, Copy)]
+enum StmtOrExpr {
+    Statement,
+    Expression,
+}
+
+#[derive(Debug, PartialEq, Eq, Clone, Copy)]
+enum AffixKind {
+    StartsWith,
+    EndsWith,
+}
+
+impl AffixKind {
+    const fn as_str(self) -> &'static str {
+        match self {
+            Self::StartsWith => "startswith",
+            Self::EndsWith => "endswith",
+        }
+    }
+
+    const fn replacement(self) -> &'static str {
+        match self {
+            Self::StartsWith => "removeprefix",
+            Self::EndsWith => "removesuffix",
+        }
+    }
+}
+
+/// Components of `startswith(prefix)` or `endswith(suffix)`.
+#[derive(Debug)]
+struct AffixQuery<'a> {
+    /// Whether the method called is `startswith` or `endswith`.
+    kind: AffixKind,
+    /// Node representing the prefix or suffix being passed to the string method.
+    affix: &'a ast::Expr,
+}
+
+/// Ingredients for a statement or expression
+/// which potentially removes a prefix or suffix from a string.
+///
+/// Specifically
+#[derive(Debug)]
+struct RemoveAffixData<'a> {
+    /// Node representing the string whose prefix or suffix we want to remove
+    text: &'a ast::Expr,
+    /// Node representing the bound used to slice the string
+    bound: &'a ast::Expr,
+    /// Contains the prefix or suffix used in `text.startswith(prefix)` or `text.endswith(suffix)`
+    affix_query: AffixQuery<'a>,
+}

crates/ruff_linter/src/rules/refurb/snapshots/ruff_linter__rules__refurb__tests__FURB188_FURB188.py.snap

@@ -0,0 +1,177 @@
+---
+source: crates/ruff_linter/src/rules/refurb/mod.rs
+---
+FURB188.py:7:5: FURB188 [*] Prefer `removesuffix` over conditionally replacing with slice.
+   |
+ 6 |   def remove_extension_via_slice(filename: str) -> str:
+ 7 |       if filename.endswith(".txt"):
+   |  _____^
+ 8 | |         filename = filename[:-4]
+   | |________________________________^ FURB188
+ 9 |   
+10 |       return filename
+   |
+   = help: Use removesuffix instead of assignment conditional upon endswith.
+
+ℹ Safe fix
+4 4 | # these should match
+5 5 | 
+6 6 | def remove_extension_via_slice(filename: str) -> str:
+7   |-    if filename.endswith(".txt"):
+8   |-        filename = filename[:-4]
+  7 |+    filename = filename.removesuffix(".txt")
+9 8 | 
+10 9 |     return filename
+11 10 | 
+
+FURB188.py:14:5: FURB188 [*] Prefer `removesuffix` over conditionally replacing with slice.
+   |
+13 |   def remove_extension_via_slice_len(filename: str, extension: str) -> str:
+14 |       if filename.endswith(extension):
+   |  _____^
+15 | |         filename = filename[:-len(extension)]
+   | |_____________________________________________^ FURB188
+16 |   
+17 |       return filename
+   |
+   = help: Use removesuffix instead of assignment conditional upon endswith.
+
+ℹ Safe fix
+11 11 | 
+12 12 | 
+13 13 | def remove_extension_via_slice_len(filename: str, extension: str) -> str:
+14    |-    if filename.endswith(extension):
+15    |-        filename = filename[:-len(extension)]
+   14 |+    filename = filename.removesuffix(extension)
+16 15 | 
+17 16 |     return filename
+18 17 | 
+
+FURB188.py:21:12: FURB188 [*] Prefer `removesuffix` over conditionally replacing with slice.
+   |
+20 | def remove_extension_via_ternary(filename: str) -> str:
+21 |     return filename[:-4] if filename.endswith(".txt") else filename
+   |            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ FURB188
+   |
+   = help: Use removesuffix instead of ternary expression conditional upon endswith.
+
+ℹ Safe fix
+18 18 | 
+19 19 | 
+20 20 | def remove_extension_via_ternary(filename: str) -> str:
+21    |-    return filename[:-4] if filename.endswith(".txt") else filename
+   21 |+    return filename.removesuffix(".txt")
+22 22 | 
+23 23 | 
+24 24 | def remove_extension_via_ternary_with_len(filename: str, extension: str) -> str:
+
+FURB188.py:25:12: FURB188 [*] Prefer `removesuffix` over conditionally replacing with slice.
+   |
+24 | def remove_extension_via_ternary_with_len(filename: str, extension: str) -> str:
+25 |     return filename[:-len(extension)] if filename.endswith(extension) else filename
+   |            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ FURB188
+   |
+   = help: Use removesuffix instead of ternary expression conditional upon endswith.
+
+ℹ Safe fix
+22 22 | 
+23 23 | 
+24 24 | def remove_extension_via_ternary_with_len(filename: str, extension: str) -> str:
+25    |-    return filename[:-len(extension)] if filename.endswith(extension) else filename
+   25 |+    return filename.removesuffix(extension)
+26 26 | 
+27 27 | 
+28 28 | def remove_prefix(filename: str) -> str:
+
+FURB188.py:29:12: FURB188 [*] Prefer `removeprefix` over conditionally replacing with slice.
+   |
+28 | def remove_prefix(filename: str) -> str:
+29 |     return filename[4:] if filename.startswith("abc-") else filename
+   |            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ FURB188
+   |
+   = help: Use removeprefix instead of ternary expression conditional upon startswith.
+
+ℹ Safe fix
+26 26 | 
+27 27 | 
+28 28 | def remove_prefix(filename: str) -> str:
+29    |-    return filename[4:] if filename.startswith("abc-") else filename
+   29 |+    return filename.removeprefix("abc-")
+30 30 | 
+31 31 | 
+32 32 | def remove_prefix_via_len(filename: str, prefix: str) -> str:
+
+FURB188.py:33:12: FURB188 [*] Prefer `removeprefix` over conditionally replacing with slice.
+   |
+32 | def remove_prefix_via_len(filename: str, prefix: str) -> str:
+33 |     return filename[len(prefix):] if filename.startswith(prefix) else filename
+   |            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ FURB188
+   |
+   = help: Use removeprefix instead of ternary expression conditional upon startswith.
+
+ℹ Safe fix
+30 30 | 
+31 31 | 
+32 32 | def remove_prefix_via_len(filename: str, prefix: str) -> str:
+33    |-    return filename[len(prefix):] if filename.startswith(prefix) else filename
+   33 |+    return filename.removeprefix(prefix)
+34 34 | 
+35 35 | 
+36 36 | # these should not
+
+FURB188.py:146:9: FURB188 [*] Prefer `removesuffix` over conditionally replacing with slice.
+    |
+144 |     SUFFIX = "suffix"
+145 | 
+146 |     x = foo.bar.baz[:-len(SUFFIX)] if foo.bar.baz.endswith(SUFFIX) else foo.bar.baz
+    |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ FURB188
+147 | 
+148 | def remove_prefix_comparable_literal_expr() -> None:
+    |
+    = help: Use removesuffix instead of ternary expression conditional upon endswith.
+
+ℹ Safe fix
+143 143 | 
+144 144 |     SUFFIX = "suffix"
+145 145 | 
+146     |-    x = foo.bar.baz[:-len(SUFFIX)] if foo.bar.baz.endswith(SUFFIX) else foo.bar.baz
+    146 |+    x = foo.bar.baz.removesuffix(SUFFIX)
+147 147 | 
+148 148 | def remove_prefix_comparable_literal_expr() -> None:
+149 149 |     return ("abc" "def")[3:] if ("abc" "def").startswith("abc") else "abc" "def"
+
+FURB188.py:149:12: FURB188 [*] Prefer `removeprefix` over conditionally replacing with slice.
+    |
+148 | def remove_prefix_comparable_literal_expr() -> None:
+149 |     return ("abc" "def")[3:] if ("abc" "def").startswith("abc") else "abc" "def"
+    |            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ FURB188
+150 | 
+151 | def shadow_builtins(filename: str, extension: str) -> None:
+    |
+    = help: Use removeprefix instead of ternary expression conditional upon startswith.
+
+ℹ Safe fix
+146 146 |     x = foo.bar.baz[:-len(SUFFIX)] if foo.bar.baz.endswith(SUFFIX) else foo.bar.baz
+147 147 | 
+148 148 | def remove_prefix_comparable_literal_expr() -> None:
+149     |-    return ("abc" "def")[3:] if ("abc" "def").startswith("abc") else "abc" "def"
+    149 |+    return "abc" "def".removeprefix("abc")
+150 150 | 
+151 151 | def shadow_builtins(filename: str, extension: str) -> None:
+152 152 |     from builtins import len as builtins_len
+
+FURB188.py:154:12: FURB188 [*] Prefer `removesuffix` over conditionally replacing with slice.
+    |
+152 |     from builtins import len as builtins_len
+153 | 
+154 |     return filename[:-builtins_len(extension)] if filename.endswith(extension) else filename
+    |            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ FURB188
+    |
+    = help: Use removesuffix instead of ternary expression conditional upon endswith.
+
+ℹ Safe fix
+151 151 | def shadow_builtins(filename: str, extension: str) -> None:
+152 152 |     from builtins import len as builtins_len
+153 153 | 
+154     |-    return filename[:-builtins_len(extension)] if filename.endswith(extension) else filename
+    154 |+    return filename.removesuffix(extension)

crates/ruff_linter/src/rules/ruff/rules/decimal_from_float_literal.rs

@@ -1,7 +1,10 @@
+use std::fmt;
+
 use ruff_diagnostics::{AlwaysFixableViolation, Diagnostic, Edit, Fix};
 use ruff_macros::{derive_message_formats, violation};
-use ruff_python_ast::{self as ast};
+use ruff_python_ast as ast;
 use ruff_python_codegen::Stylist;
+use ruff_source_file::Locator;
 use ruff_text_size::{Ranged, TextRange};
 
 use crate::checkers::ast::Checker;
@@ -49,37 +52,90 @@ pub(crate) fn decimal_from_float_literal_syntax(checker: &mut Checker, call: &as
         return;
     };
 
-    if !is_arg_float_literal(arg) {
-        return;
-    }
-
-    if checker
-        .semantic()
-        .resolve_qualified_name(call.func.as_ref())
-        .is_some_and(|qualified_name| matches!(qualified_name.segments(), ["decimal", "Decimal"]))
-    {
-        let diagnostic =
-            Diagnostic::new(DecimalFromFloatLiteral, arg.range()).with_fix(fix_float_literal(
-                arg.range(),
-                &checker.generator().expr(arg),
-                checker.stylist(),
-            ));
-        checker.diagnostics.push(diagnostic);
+    if let Some(float) = extract_float_literal(arg, Sign::Positive) {
+        if checker
+            .semantic()
+            .resolve_qualified_name(call.func.as_ref())
+            .is_some_and(|qualified_name| {
+                matches!(qualified_name.segments(), ["decimal", "Decimal"])
+            })
+        {
+            let diagnostic = Diagnostic::new(DecimalFromFloatLiteral, arg.range()).with_fix(
+                fix_float_literal(arg.range(), float, checker.locator(), checker.stylist()),
+            );
+            checker.diagnostics.push(diagnostic);
+        }
     }
 }
 
-fn is_arg_float_literal(arg: &ast::Expr) -> bool {
+#[derive(Debug, Clone, Copy)]
+enum Sign {
+    Positive,
+    Negative,
+}
+
+impl Sign {
+    const fn as_str(self) -> &'static str {
+        match self {
+            Self::Positive => "",
+            Self::Negative => "-",
+        }
+    }
+
+    const fn flip(self) -> Self {
+        match self {
+            Self::Negative => Self::Positive,
+            Self::Positive => Self::Negative,
+        }
+    }
+}
+
+impl fmt::Display for Sign {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
+
+#[derive(Debug, Copy, Clone)]
+struct Float {
+    /// The range of the float excluding the sign.
+    /// E.g. for `+--+-+-4.3`, this will be the range of `4.3`
+    value_range: TextRange,
+    /// The resolved sign of the float (either `-` or `+`)
+    sign: Sign,
+}
+
+fn extract_float_literal(arg: &ast::Expr, sign: Sign) -> Option<Float> {
     match arg {
-        ast::Expr::NumberLiteral(ast::ExprNumberLiteral {
-            value: ast::Number::Float(_),
+        ast::Expr::NumberLiteral(number_literal_expr) if number_literal_expr.value.is_float() => {
+            Some(Float {
+                value_range: arg.range(),
+                sign,
+            })
+        }
+        ast::Expr::UnaryOp(ast::ExprUnaryOp {
+            operand,
+            op: ast::UnaryOp::UAdd,
             ..
-        }) => true,
-        ast::Expr::UnaryOp(ast::ExprUnaryOp { operand, .. }) => is_arg_float_literal(operand),
-        _ => false,
+        }) => extract_float_literal(operand, sign),
+        ast::Expr::UnaryOp(ast::ExprUnaryOp {
+            operand,
+            op: ast::UnaryOp::USub,
+            ..
+        }) => extract_float_literal(operand, sign.flip()),
+        _ => None,
     }
 }
 
-fn fix_float_literal(range: TextRange, float_literal: &str, stylist: &Stylist) -> Fix {
-    let content = format!("{quote}{float_literal}{quote}", quote = stylist.quote());
-    Fix::unsafe_edit(Edit::range_replacement(content, range))
+fn fix_float_literal(
+    original_range: TextRange,
+    float: Float,
+    locator: &Locator,
+    stylist: &Stylist,
+) -> Fix {
+    let quote = stylist.quote();
+    let Float { value_range, sign } = float;
+    let float_value = locator.slice(value_range);
+    let content = format!("{quote}{sign}{float_value}{quote}");
+    Fix::unsafe_edit(Edit::range_replacement(content, original_range))
 }

crates/ruff_linter/src/rules/ruff/rules/invalid_formatter_suppression_comment.rs

@@ -75,7 +75,7 @@ pub(crate) fn ignored_formatter_suppression_comment(checker: &mut Checker, suite
         .into_iter()
         .filter_map(|range| {
             Some(SuppressionComment {
-                range: *range,
+                range,
                 kind: SuppressionKind::from_comment(locator.slice(range))?,
             })
         })

crates/ruff_linter/src/rules/ruff/snapshots/ruff_linter__rules__ruff__tests__RUF032_RUF032.py.snap

@@ -127,65 +127,105 @@ RUF032.py:45:15: RUF032 [*] `Decimal()` called with float literal argument
 47 47 | val = Decimal("-10.0")
 48 48 | 
 
-RUF032.py:81:23: RUF032 [*] `Decimal()` called with float literal argument
+RUF032.py:56:15: RUF032 [*] `Decimal()` called with float literal argument
    |
-79 | # Retest with fully qualified import
-80 | 
-81 | val = decimal.Decimal(0.0)  # Should error
+54 | val = Decimal(~4.0) # Skip
+55 | 
+56 | val = Decimal(++4.0) # Suggest `Decimal("4.0")`
+   |               ^^^^^ RUF032
+57 | 
+58 | val = Decimal(-+--++--4.0) # Suggest `Decimal("-4.0")` 
+   |
+   = help: Use a string literal instead
+
+ℹ Unsafe fix
+53 53 | # See https://github.com/astral-sh/ruff/issues/13258
+54 54 | val = Decimal(~4.0) # Skip
+55 55 | 
+56    |-val = Decimal(++4.0) # Suggest `Decimal("4.0")`
+   56 |+val = Decimal("4.0") # Suggest `Decimal("4.0")`
+57 57 | 
+58 58 | val = Decimal(-+--++--4.0) # Suggest `Decimal("-4.0")` 
+59 59 | 
+
+RUF032.py:58:15: RUF032 [*] `Decimal()` called with float literal argument
+   |
+56 | val = Decimal(++4.0) # Suggest `Decimal("4.0")`
+57 | 
+58 | val = Decimal(-+--++--4.0) # Suggest `Decimal("-4.0")` 
+   |               ^^^^^^^^^^^ RUF032
+   |
+   = help: Use a string literal instead
+
+ℹ Unsafe fix
+55 55 | 
+56 56 | val = Decimal(++4.0) # Suggest `Decimal("4.0")`
+57 57 | 
+58    |-val = Decimal(-+--++--4.0) # Suggest `Decimal("-4.0")` 
+   58 |+val = Decimal("-4.0") # Suggest `Decimal("-4.0")` 
+59 59 | 
+60 60 | 
+61 61 | # Tests with shadowed name
+
+RUF032.py:88:23: RUF032 [*] `Decimal()` called with float literal argument
+   |
+86 | # Retest with fully qualified import
+87 | 
+88 | val = decimal.Decimal(0.0)  # Should error
    |                       ^^^ RUF032
-82 | 
-83 | val = decimal.Decimal("0.0")
+89 | 
+90 | val = decimal.Decimal("0.0")
    |
    = help: Use a string literal instead
 
 ℹ Unsafe fix
-78 78 | 
-79 79 | # Retest with fully qualified import
-80 80 | 
-81    |-val = decimal.Decimal(0.0)  # Should error
-   81 |+val = decimal.Decimal("0.0")  # Should error
-82 82 | 
-83 83 | val = decimal.Decimal("0.0")
-84 84 | 
+85 85 | 
+86 86 | # Retest with fully qualified import
+87 87 | 
+88    |-val = decimal.Decimal(0.0)  # Should error
+   88 |+val = decimal.Decimal("0.0")  # Should error
+89 89 | 
+90 90 | val = decimal.Decimal("0.0")
+91 91 | 
 
-RUF032.py:85:23: RUF032 [*] `Decimal()` called with float literal argument
+RUF032.py:92:23: RUF032 [*] `Decimal()` called with float literal argument
    |
-83 | val = decimal.Decimal("0.0")
-84 | 
-85 | val = decimal.Decimal(10.0)  # Should error
+90 | val = decimal.Decimal("0.0")
+91 | 
+92 | val = decimal.Decimal(10.0)  # Should error
    |                       ^^^^ RUF032
-86 | 
-87 | val = decimal.Decimal("10.0")
+93 | 
+94 | val = decimal.Decimal("10.0")
    |
    = help: Use a string literal instead
 
 ℹ Unsafe fix
-82 82 | 
-83 83 | val = decimal.Decimal("0.0")
-84 84 | 
-85    |-val = decimal.Decimal(10.0)  # Should error
-   85 |+val = decimal.Decimal("10.0")  # Should error
-86 86 | 
-87 87 | val = decimal.Decimal("10.0")
-88 88 | 
+89 89 | 
+90 90 | val = decimal.Decimal("0.0")
+91 91 | 
+92    |-val = decimal.Decimal(10.0)  # Should error
+   92 |+val = decimal.Decimal("10.0")  # Should error
+93 93 | 
+94 94 | val = decimal.Decimal("10.0")
+95 95 | 
 
-RUF032.py:89:23: RUF032 [*] `Decimal()` called with float literal argument
+RUF032.py:96:23: RUF032 [*] `Decimal()` called with float literal argument
    |
-87 | val = decimal.Decimal("10.0")
-88 | 
-89 | val = decimal.Decimal(-10.0)  # Should error
+94 | val = decimal.Decimal("10.0")
+95 | 
+96 | val = decimal.Decimal(-10.0)  # Should error
    |                       ^^^^^ RUF032
-90 | 
-91 | val = decimal.Decimal("-10.0")
+97 | 
+98 | val = decimal.Decimal("-10.0")
    |
    = help: Use a string literal instead
 
 ℹ Unsafe fix
-86 86 | 
-87 87 | val = decimal.Decimal("10.0")
-88 88 | 
-89    |-val = decimal.Decimal(-10.0)  # Should error
-   89 |+val = decimal.Decimal("-10.0")  # Should error
-90 90 | 
-91 91 | val = decimal.Decimal("-10.0")
-92 92 |
+93 93 | 
+94 94 | val = decimal.Decimal("10.0")
+95 95 | 
+96    |-val = decimal.Decimal(-10.0)  # Should error
+   96 |+val = decimal.Decimal("-10.0")  # Should error
+97 97 | 
+98 98 | val = decimal.Decimal("-10.0")
+99 99 |

crates/ruff_python_ast/src/nodes.rs

@@ -3124,6 +3124,29 @@ impl Pattern {
             _ => false,
         }
     }
+
+    /// Checks if the [`Pattern`] is a [wildcard pattern].
+    ///
+    /// The following are wildcard patterns:
+    /// ```python
+    /// match subject:
+    ///     case _ as x: ...
+    ///     case _ | _: ...
+    ///     case _: ...
+    /// ```
+    ///
+    /// [wildcard pattern]: https://docs.python.org/3/reference/compound_stmts.html#wildcard-patterns
+    pub fn is_wildcard(&self) -> bool {
+        match self {
+            Pattern::MatchAs(PatternMatchAs { pattern, .. }) => {
+                pattern.as_deref().map_or(true, Pattern::is_wildcard)
+            }
+            Pattern::MatchOr(PatternMatchOr { patterns, .. }) => {
+                patterns.iter().all(Pattern::is_wildcard)
+            }
+            _ => false,
+        }
+    }
 }
 
 /// See also [MatchValue](https://docs.python.org/3/library/ast.html#ast.MatchValue)

crates/ruff_python_ast_integration_tests/tests/match_pattern.rs

@@ -0,0 +1,16 @@
+use ruff_python_parser::parse_module;
+
+#[test]
+fn pattern_is_wildcard() {
+    let source_code = r"
+match subject:
+    case _ as x: ...
+    case _ | _: ...
+    case _: ...
+";
+    let parsed = parse_module(source_code).unwrap();
+    let cases = &parsed.syntax().body[0].as_match_stmt().unwrap().cases;
+    for case in cases {
+        assert!(case.pattern.is_wildcard());
+    }
+}

crates/ruff_python_formatter/resources/test/fixtures/black/cases/backslash_before_indent.options.json

@@ -0,0 +1 @@
+{"target_version": "py310"}

crates/ruff_python_formatter/resources/test/fixtures/black/cases/backslash_before_indent.py

@@ -0,0 +1,10 @@
+class Plotter:
+\
+    pass
+
+class AnotherCase:
+  \
+    """Some
+    \
+    Docstring
+    """

crates/ruff_python_formatter/resources/test/fixtures/black/cases/backslash_before_indent.py.expect

@@ -0,0 +1,10 @@
+class Plotter:
+
+    pass
+
+
+class AnotherCase:
+    """Some
+    \
+    Docstring
+    """

crates/ruff_python_formatter/resources/test/fixtures/black/cases/comment_after_escaped_newline.py.expect

@@ -2,5 +2,7 @@ def bob():  # pylint: disable=W9016
     pass
 
 
-def bobtwo():  # some comment here
+def bobtwo():
+
+    # some comment here
     pass

crates/ruff_python_formatter/resources/test/fixtures/black/cases/dummy_implementations.py

@@ -67,3 +67,63 @@ async def async_function(self):
 @decorated
 async def async_function(self):
     ...
+
+class ClassA:
+    def f(self):
+        
+        ...
+
+
+class ClassB:
+    def f(self):
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        ...
+
+
+class ClassC:
+    def f(self):
+        
+        ...
+        # Comment
+
+
+class ClassD:
+    def f(self):# Comment 1
+        
+        ...# Comment 2
+        # Comment 3
+
+
+class ClassE:
+    def f(self):
+        
+        ...
+    def f2(self):
+        print(10)
+
+
+class ClassF:
+    def f(self):
+        
+        ...# Comment 2
+
+
+class ClassG:
+    def f(self):#Comment 1
+        
+        ...# Comment 2
+ 
+       
+class ClassH:
+    def f(self):
+        #Comment
+
+        ...

crates/ruff_python_formatter/resources/test/fixtures/black/cases/dummy_implementations.py.expect

@@ -70,3 +70,47 @@ async def async_function(self): ...
 
 @decorated
 async def async_function(self): ...
+
+
+class ClassA:
+    def f(self): ...
+
+
+class ClassB:
+    def f(self): ...
+
+
+class ClassC:
+    def f(self):
+
+        ...
+        # Comment
+
+
+class ClassD:
+    def f(self):  # Comment 1
+
+        ...  # Comment 2
+        # Comment 3
+
+
+class ClassE:
+    def f(self): ...
+    def f2(self):
+        print(10)
+
+
+class ClassF:
+    def f(self): ...  # Comment 2
+
+
+class ClassG:
+    def f(self):  # Comment 1
+        ...  # Comment 2
+
+
+class ClassH:
+    def f(self):
+        # Comment
+
+        ...

crates/ruff_python_formatter/resources/test/fixtures/black/cases/fmtonoff6.py

@@ -0,0 +1,13 @@
+# Regression test for https://github.com/psf/black/issues/2478.
+def foo():
+    arr = (
+        (3833567325051000, 5, 1, 2, 4229.25, 6, 0),
+        # fmt: off
+    )
+
+
+# Regression test for https://github.com/psf/black/issues/3458.
+dependencies = {
+    a: b,
+    # fmt: off
+}

crates/ruff_python_formatter/resources/test/fixtures/black/cases/fmtonoff6.py.expect

@@ -0,0 +1,13 @@
+# Regression test for https://github.com/psf/black/issues/2478.
+def foo():
+    arr = (
+        (3833567325051000, 5, 1, 2, 4229.25, 6, 0),
+        # fmt: off
+    )
+
+
+# Regression test for https://github.com/psf/black/issues/3458.
+dependencies = {
+    a: b,
+    # fmt: off
+}

crates/ruff_python_formatter/resources/test/fixtures/black/cases/form_feeds.py.expect

@@ -33,6 +33,7 @@
 
 #
 
+
 #
 pass
 

crates/ruff_python_formatter/resources/test/fixtures/black/cases/function_trailing_comma.py

@@ -59,3 +59,61 @@ some_module.some_function(
 some_module.some_function(
     argument1, (one, two,), argument4, argument5, argument6
 )
+
+def foo() -> (
+    # comment inside parenthesised return type
+    int
+):
+    ...
+
+def foo() -> (
+    # comment inside parenthesised return type
+    # more
+    int
+    # another
+):
+    ...
+
+def foo() -> (
+    # comment inside parenthesised new union return type
+    int | str | bytes
+):
+    ...
+
+def foo() -> (
+    # comment inside plain tuple
+):
+    pass
+
+def foo(arg: (# comment with non-return annotation
+        int
+        # comment with non-return annotation
+)):
+    pass
+
+def foo(arg: (# comment with non-return annotation
+        int | range | memoryview
+        # comment with non-return annotation
+)):
+    pass
+
+def foo(arg: (# only before
+        int
+)):
+    pass
+
+def foo(arg: (
+        int
+        # only after
+)):
+    pass
+
+variable: ( # annotation
+    because
+    # why not
+)
+
+variable: (
+    because
+    # why not
+)

crates/ruff_python_formatter/resources/test/fixtures/black/cases/function_trailing_comma.py.expect

@@ -112,3 +112,75 @@ some_module.some_function(
     argument5,
     argument6,
 )
+
+
+def foo() -> (
+    # comment inside parenthesised return type
+    int
+): ...
+
+
+def foo() -> (
+    # comment inside parenthesised return type
+    # more
+    int
+    # another
+): ...
+
+
+def foo() -> (
+    # comment inside parenthesised new union return type
+    int
+    | str
+    | bytes
+): ...
+
+
+def foo() -> (
+    # comment inside plain tuple
+):
+    pass
+
+
+def foo(
+    arg: (  # comment with non-return annotation
+        int
+        # comment with non-return annotation
+    ),
+):
+    pass
+
+
+def foo(
+    arg: (  # comment with non-return annotation
+        int
+        | range
+        | memoryview
+        # comment with non-return annotation
+    ),
+):
+    pass
+
+
+def foo(arg: int):  # only before
+    pass
+
+
+def foo(
+    arg: (
+        int
+        # only after
+    ),
+):
+    pass
+
+
+variable: (  # annotation
+    because
+    # why not
+)
+
+variable: (
+    because
+    # why not
+)

crates/ruff_python_formatter/resources/test/fixtures/black/cases/line_ranges_basic.py

@@ -6,7 +6,7 @@ def foo2(parameter_1, parameter_2, parameter_3, parameter_4, parameter_5, parame
 def foo3(parameter_1, parameter_2, parameter_3, parameter_4, parameter_5, parameter_6, parameter_7): pass
 def foo4(parameter_1, parameter_2, parameter_3, parameter_4, parameter_5, parameter_6, parameter_7): pass
 
-# Adding some unformatted code covering a wide range of syntaxes.
+# Adding some unformated code covering a wide range of syntaxes.
 
 if True:
       # Incorrectly indented prefix comments.

crates/ruff_python_formatter/resources/test/fixtures/black/cases/line_ranges_basic.py.expect

@@ -28,7 +28,7 @@ def foo3(
 
 def foo4(parameter_1, parameter_2, parameter_3, parameter_4, parameter_5, parameter_6, parameter_7): pass
 
-# Adding some unformatted code covering a wide range of syntaxes.
+# Adding some unformated code covering a wide range of syntaxes.
 
 if True:
       # Incorrectly indented prefix comments.

crates/ruff_python_formatter/resources/test/fixtures/black/cases/line_ranges_exceeding_end.py

@@ -0,0 +1,7 @@
+# flags: --line-ranges=6-1000
+# NOTE: If you need to modify this file, pay special attention to the --line-ranges=
+# flag above as it's formatting specifically these lines.
+def foo1(parameter_1, parameter_2, parameter_3, parameter_4, parameter_5, parameter_6, parameter_7): pass
+def foo2(parameter_1, parameter_2, parameter_3, parameter_4, parameter_5, parameter_6, parameter_7): pass
+def foo3(parameter_1, parameter_2, parameter_3, parameter_4, parameter_5, parameter_6, parameter_7): pass
+def foo4(parameter_1, parameter_2, parameter_3, parameter_4, parameter_5, parameter_6, parameter_7): pass

crates/ruff_python_formatter/resources/test/fixtures/black/cases/line_ranges_exceeding_end.py.expect

@@ -0,0 +1,27 @@
+# flags: --line-ranges=6-1000
+# NOTE: If you need to modify this file, pay special attention to the --line-ranges=
+# flag above as it's formatting specifically these lines.
+def foo1(parameter_1, parameter_2, parameter_3, parameter_4, parameter_5, parameter_6, parameter_7): pass
+def foo2(parameter_1, parameter_2, parameter_3, parameter_4, parameter_5, parameter_6, parameter_7): pass
+def foo3(
+    parameter_1,
+    parameter_2,
+    parameter_3,
+    parameter_4,
+    parameter_5,
+    parameter_6,
+    parameter_7,
+):
+    pass
+
+
+def foo4(
+    parameter_1,
+    parameter_2,
+    parameter_3,
+    parameter_4,
+    parameter_5,
+    parameter_6,
+    parameter_7,
+):
+    pass

crates/ruff_python_formatter/resources/test/fixtures/black/cases/pattern_matching_complex.py

@@ -82,7 +82,7 @@ match (0, 1, 2):
 match x:
     case [0]:
         y = 0
-    case [1, 0] if (x := x[:0]):
+    case [1, 0] if x := x[:0]:
         y = 1
     case [1, 0]:
         y = 2

crates/ruff_python_formatter/resources/test/fixtures/black/cases/pattern_matching_complex.py.expect

@@ -82,7 +82,7 @@ match (0, 1, 2):
 match x:
     case [0]:
         y = 0
-    case [1, 0] if (x := x[:0]):
+    case [1, 0] if x := x[:0]:
         y = 1
     case [1, 0]:
         y = 2

crates/ruff_python_formatter/resources/test/fixtures/black/cases/pattern_matching_with_if_stmt.options.json

@@ -0,0 +1 @@
+{"preview": "enabled", "target_version": "py310"}

crates/ruff_python_formatter/resources/test/fixtures/black/cases/pattern_matching_with_if_stmt.py

@@ -0,0 +1,32 @@
+match match:
+    case "test" if case != "not very loooooooooooooog condition":  # comment
+        pass
+
+match smth:
+    case "test" if "any long condition" != "another long condition" and "this is a long condition":
+        pass
+    case test if "any long condition" != "another long condition" and "this is a looooong condition":
+        pass
+    case test if "any long condition" != "another long condition" and "this is a looooong condition":  # some additional comments
+        pass
+    case test if (True): # some comment
+        pass
+    case test if (False
+        ): # some comment
+        pass
+    case test if (True  # some comment
+        ):
+        pass  # some comment
+    case cases if (True  # some comment
+                   ): # some other comment
+        pass  # some comment
+    case match if (True  # some comment
+                   ):
+        pass  # some comment
+
+# case black_test_patma_052 (originally in the pattern_matching_complex test case)
+match x:
+    case [1, 0] if x := x[:0]:
+        y = 1
+    case [1, 0] if (x := x[:0]):
+        y = 1