WIP

Two related changes.  For context:

1. We were maintaining two separate arenas of `Constraint`s in each
use-def map. One was used for narrowing constraints, and the other for
visibility constraints. The visibility constraint arena was interned,
ensuring that we always used the same ID for any particular
`Constraint`. The narrowing constraint arena was not interned.

2. The TDD code relies on _all_ TDD nodes being interned and reduced.
This is an important requirement for TDDs to be a canonical form, which
allows us to use a single int comparison to test for "always true/false"
and to compare two TDDs for equivalence. But we also need to support an
individual `Constraint` having multiple values in a TDD evaluation (e.g.
to handle a `while` condition having different values the first time
it's evaluated vs later times). Previously, we handled that by
introducing a "copy" number, which was only there as a disambiguator, to
allow an interned, deduplicated constraint ID to appear in the TDD
formula multiple times.

A better way to handle (2) is to not intern the constraints in the
visibility constraint arena! The caller now gets to decide: if they add
a `Constraint` to the arena more than once, they get distinct
`ScopedConstraintId`s — which the TDD code will treat as distinct
variables, allowing them to take on different values in the ternary
function.

With that in place, we can then consolidate on a single (non-interned)
arena, which is shared for both narrowing and visibility constraints.

---------

Co-authored-by: Carl Meyer <carl@astral.sh>

.cargo/config.toml

@@ -8,3 +8,7 @@ benchmark = "bench -p ruff_benchmark --bench linter --bench formatter --"
 # See: https://github.com/astral-sh/ruff/issues/11503
 [target.'cfg(all(target_env="msvc", target_os = "windows"))']
 rustflags = ["-C", "target-feature=+crt-static"]
+
+[target.'wasm32-unknown-unknown']
+# See https://docs.rs/getrandom/latest/getrandom/#webassembly-support
+rustflags = ["--cfg", 'getrandom_backend="wasm_js"']

.github/renovate.json5

@@ -58,6 +58,12 @@
       description: "Disable PRs updating GitHub runners (e.g. 'runs-on: macos-14')",
       enabled: false,
     },
+    {
+      // TODO: Remove this once the codebase is upgrade to v4 (https://github.com/astral-sh/ruff/pull/16069)
+      matchPackageNames: ["tailwindcss"],
+      matchManagers: ["npm"],
+      enabled: false,
+    },
     {
       // Disable updates of `zip-rs`; intentionally pinned for now due to ownership change
       // See: https://github.com/astral-sh/uv/issues/3642

.github/workflows/ci.yaml

@@ -280,7 +280,7 @@ jobs:
 
   cargo-build-msrv:
     name: "cargo build (msrv)"
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-latest-8
     needs: determine_changes
     if: ${{ !contains(github.event.pull_request.labels.*.name, 'no-test') && (needs.determine_changes.outputs.code == 'true' || github.ref == 'refs/heads/main') }}
     timeout-minutes: 20
@@ -430,7 +430,7 @@ jobs:
           name: ruff
           path: target/debug
 
-      - uses: dawidd6/action-download-artifact@v7
+      - uses: dawidd6/action-download-artifact@v8
         name: Download baseline Ruff binary
         with:
           name: ruff
@@ -712,7 +712,7 @@ jobs:
           just test
 
   benchmarks:
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
     needs: determine_changes
     if: ${{ github.repository == 'astral-sh/ruff' && !contains(github.event.pull_request.labels.*.name, 'no-test') && (needs.determine_changes.outputs.code == 'true' || github.ref == 'refs/heads/main') }}
     timeout-minutes: 20

.github/workflows/pr-comment.yaml

@@ -16,7 +16,7 @@ jobs:
     permissions:
       pull-requests: write
     steps:
-      - uses: dawidd6/action-download-artifact@v7
+      - uses: dawidd6/action-download-artifact@v8
         name: Download pull request number
         with:
           name: pr-number
@@ -32,7 +32,7 @@ jobs:
             echo "pr-number=$(<pr-number)" >> "$GITHUB_OUTPUT"
           fi
 
-      - uses: dawidd6/action-download-artifact@v7
+      - uses: dawidd6/action-download-artifact@v8
         name: "Download ecosystem results"
         id: download-ecosystem-result
         if: steps.pr-number.outputs.pr-number

.github/workflows/publish-playground.yml

@@ -35,6 +35,8 @@ jobs:
           cache: "npm"
           cache-dependency-path: playground/package-lock.json
       - uses: jetli/wasm-pack-action@v0.4.0
+        with:
+          version: v0.13.1
       - uses: jetli/wasm-bindgen-action@v0.2.0
       - name: "Run wasm-pack"
         run: wasm-pack build --target web --out-dir ../../playground/src/pkg crates/ruff_wasm
@@ -49,7 +51,7 @@ jobs:
         working-directory: playground
       - name: "Deploy to Cloudflare Pages"
         if: ${{ env.CF_API_TOKEN_EXISTS == 'true' }}
-        uses: cloudflare/wrangler-action@v3.13.1
+        uses: cloudflare/wrangler-action@v3.14.0
         with:
           apiToken: ${{ secrets.CF_API_TOKEN }}
           accountId: ${{ secrets.CF_ACCOUNT_ID }}

.github/workflows/publish-wasm.yml

@@ -35,6 +35,8 @@ jobs:
       - name: "Install Rust toolchain"
         run: rustup target add wasm32-unknown-unknown
       - uses: jetli/wasm-pack-action@v0.4.0
+        with:
+          version: v0.13.1
       - uses: jetli/wasm-bindgen-action@v0.2.0
       - name: "Run wasm-pack build"
         run: wasm-pack build --target ${{ matrix.target }} crates/ruff_wasm

.gitignore

@@ -30,7 +30,7 @@ tracing-flamechart.svg
 tracing-flamegraph.svg
 
 # insta
-.rs.pending-snap
+*.rs.pending-snap
 
 
 ###

.pre-commit-config.yaml

@@ -5,6 +5,7 @@ exclude: |
     .github/workflows/release.yml|
     crates/red_knot_vendored/vendor/.*|
     crates/red_knot_project/resources/.*|
+    crates/ruff_benchmark/resources/.*|
     crates/ruff_linter/resources/.*|
     crates/ruff_linter/src/rules/.*/snapshots/.*|
     crates/ruff_notebook/resources/.*|
@@ -23,7 +24,7 @@ repos:
       - id: validate-pyproject
 
   - repo: https://github.com/executablebooks/mdformat
-    rev: 0.7.21
+    rev: 0.7.22
     hooks:
       - id: mdformat
         additional_dependencies:
@@ -36,7 +37,7 @@ repos:
           )$
 
   - repo: https://github.com/igorshubovych/markdownlint-cli
-    rev: v0.43.0
+    rev: v0.44.0
     hooks:
       - id: markdownlint-fix
         exclude: |
@@ -56,10 +57,10 @@ repos:
             .*?invalid(_.+)*_syntax\.md
           )$
         additional_dependencies:
-          - black==24.10.0
+          - black==25.1.0
 
   - repo: https://github.com/crate-ci/typos
-    rev: v1.29.4
+    rev: v1.29.7
     hooks:
       - id: typos
 
@@ -73,7 +74,7 @@ repos:
         pass_filenames: false # This makes it a lot faster
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.9.2
+    rev: v0.9.6
     hooks:
       - id: ruff-format
       - id: ruff
@@ -83,7 +84,7 @@ repos:
 
   # Prettier
   - repo: https://github.com/rbubley/mirrors-prettier
-    rev: v3.4.2
+    rev: v3.5.1
     hooks:
       - id: prettier
         types: [yaml]
@@ -91,12 +92,12 @@ repos:
   # zizmor detects security vulnerabilities in GitHub Actions workflows.
   # Additional configuration for the tool is found in `.github/zizmor.yml`
   - repo: https://github.com/woodruffw/zizmor-pre-commit
-    rev: v1.2.2
+    rev: v1.3.1
     hooks:
       - id: zizmor
 
   - repo: https://github.com/python-jsonschema/check-jsonschema
-    rev: 0.31.0
+    rev: 0.31.1
     hooks:
       - id: check-github-workflows
 

BREAKING_CHANGES.md

@@ -209,8 +209,8 @@ This change only affects those using Ruff under its default rule set. Users that
 
 ### Remove support for emoji identifiers ([#7212](https://github.com/astral-sh/ruff/pull/7212))
 
-Previously, Ruff supported the non-standard compliant emoji identifiers e.g. `📦 = 1`.
-We decided to remove this non-standard language extension, and Ruff now reports syntax errors for emoji identifiers in your code, the same as CPython.
+Previously, Ruff supported non-standards-compliant emoji identifiers such as `📦 = 1`.
+We decided to remove this non-standard language extension. Ruff now reports syntax errors for invalid emoji identifiers in your code, the same as CPython.
 
 ### Improved GitLab fingerprints ([#7203](https://github.com/astral-sh/ruff/pull/7203))
 

CHANGELOG.md

@@ -1,5 +1,191 @@
 # Changelog
 
+## 0.9.7
+
+### Preview features
+
+- Consider `__new__` methods as special function type for enforcing class method or static method rules ([#13305](https://github.com/astral-sh/ruff/pull/13305))
+- \[`airflow`\] Improve the internal logic to differentiate deprecated symbols (`AIR303`) ([#16013](https://github.com/astral-sh/ruff/pull/16013))
+- \[`refurb`\] Manual timezone monkeypatching (`FURB162`) ([#16113](https://github.com/astral-sh/ruff/pull/16113))
+- \[`ruff`\] Implicit class variable in dataclass (`RUF045`) ([#14349](https://github.com/astral-sh/ruff/pull/14349))
+- \[`ruff`\] Skip singleton starred expressions for `incorrectly-parenthesized-tuple-in-subscript` (`RUF031`) ([#16083](https://github.com/astral-sh/ruff/pull/16083))
+- \[`refurb`\] Check for subclasses includes subscript expressions (`FURB189`) ([#16155](https://github.com/astral-sh/ruff/pull/16155))
+
+### Rule changes
+
+- \[`flake8-comprehensions`\]: Handle trailing comma in `C403` fix ([#16110](https://github.com/astral-sh/ruff/pull/16110))
+- \[`flake8-debugger`\] Also flag `sys.breakpointhook` and `sys.__breakpointhook__` (`T100`) ([#16191](https://github.com/astral-sh/ruff/pull/16191))
+- \[`pydocstyle`\] Handle arguments with the same names as sections (`D417`) ([#16011](https://github.com/astral-sh/ruff/pull/16011))
+- \[`pylint`\] Correct ordering of arguments in fix for `if-stmt-min-max` (`PLR1730`) ([#16080](https://github.com/astral-sh/ruff/pull/16080))
+- \[`pylint`\] Do not offer fix for raw strings (`PLE251`) ([#16132](https://github.com/astral-sh/ruff/pull/16132))
+- \[`pyupgrade`\] Do not upgrade functional `TypedDicts` with private field names to the class-based syntax (`UP013`) ([#16219](https://github.com/astral-sh/ruff/pull/16219))
+- \[`pyupgrade`\] Handle micro version numbers correctly (`UP036`) ([#16091](https://github.com/astral-sh/ruff/pull/16091))
+- \[`pyupgrade`\] Unwrap unary expressions correctly (`UP018`) ([#15919](https://github.com/astral-sh/ruff/pull/15919))
+- \[`ruff`\] Skip `RUF001` diagnostics when visiting string type definitions ([#16122](https://github.com/astral-sh/ruff/pull/16122))
+- \[`flake8-pyi`\] Avoid flagging `custom-typevar-for-self` on metaclass methods (`PYI019`) ([#16141](https://github.com/astral-sh/ruff/pull/16141))
+- \[`pycodestyle`\] Exempt `site.addsitedir(...)` calls (`E402`) ([#16251](https://github.com/astral-sh/ruff/pull/16251))
+
+### Formatter
+
+- Fix unstable formatting of trailing end-of-line comments of parenthesized attribute values ([#16187](https://github.com/astral-sh/ruff/pull/16187))
+
+### Server
+
+- Fix handling of requests received after shutdown message ([#16262](https://github.com/astral-sh/ruff/pull/16262))
+- Ignore `source.organizeImports.ruff` and `source.fixAll.ruff` code actions for a notebook cell ([#16154](https://github.com/astral-sh/ruff/pull/16154))
+- Include document specific debug info for `ruff.printDebugInformation` ([#16215](https://github.com/astral-sh/ruff/pull/16215))
+- Update server to return the debug info as string with `ruff.printDebugInformation` ([#16214](https://github.com/astral-sh/ruff/pull/16214))
+
+### CLI
+
+- Warn on invalid `noqa` even when there are no diagnostics ([#16178](https://github.com/astral-sh/ruff/pull/16178))
+- Better error messages while loading configuration `extend`s ([#15658](https://github.com/astral-sh/ruff/pull/15658))
+
+### Bug fixes
+
+- \[`refurb`\] Correctly handle lengths of literal strings in `slice-to-remove-prefix-or-suffix` (`FURB188`) ([#16237](https://github.com/astral-sh/ruff/pull/16237))
+
+### Documentation
+
+- Add FAQ entry for `source.*` code actions in Notebook ([#16212](https://github.com/astral-sh/ruff/pull/16212))
+- Add `SECURITY.md` ([#16224](https://github.com/astral-sh/ruff/pull/16224))
+
+## 0.9.6
+
+### Preview features
+
+- \[`airflow`\] Add `external_task.{ExternalTaskMarker, ExternalTaskSensor}` for `AIR302` ([#16014](https://github.com/astral-sh/ruff/pull/16014))
+- \[`flake8-builtins`\] Make strict module name comparison optional (`A005`) ([#15951](https://github.com/astral-sh/ruff/pull/15951))
+- \[`flake8-pyi`\] Extend fix to Python \<= 3.9 for `redundant-none-literal` (`PYI061`) ([#16044](https://github.com/astral-sh/ruff/pull/16044))
+- \[`pylint`\] Also report when the object isn't a literal (`PLE1310`) ([#15985](https://github.com/astral-sh/ruff/pull/15985))
+- \[`ruff`\] Implement `indented-form-feed` (`RUF054`) ([#16049](https://github.com/astral-sh/ruff/pull/16049))
+- \[`ruff`\] Skip type definitions for `missing-f-string-syntax` (`RUF027`) ([#16054](https://github.com/astral-sh/ruff/pull/16054))
+
+### Rule changes
+
+- \[`flake8-annotations`\] Correct syntax for `typing.Union` in suggested return type fixes for `ANN20x` rules ([#16025](https://github.com/astral-sh/ruff/pull/16025))
+- \[`flake8-builtins`\] Match upstream module name comparison (`A005`) ([#16006](https://github.com/astral-sh/ruff/pull/16006))
+- \[`flake8-comprehensions`\] Detect overshadowed `list`/`set`/`dict`, ignore variadics and named expressions (`C417`) ([#15955](https://github.com/astral-sh/ruff/pull/15955))
+- \[`flake8-pie`\] Remove following comma correctly when the unpacked dictionary is empty (`PIE800`) ([#16008](https://github.com/astral-sh/ruff/pull/16008))
+- \[`flake8-simplify`\] Only trigger `SIM401` on known dictionaries ([#15995](https://github.com/astral-sh/ruff/pull/15995))
+- \[`pylint`\] Do not report calls when object type and argument type mismatch, remove custom escape handling logic (`PLE1310`) ([#15984](https://github.com/astral-sh/ruff/pull/15984))
+- \[`pyupgrade`\] Comments within parenthesized value ranges should not affect applicability (`UP040`) ([#16027](https://github.com/astral-sh/ruff/pull/16027))
+- \[`pyupgrade`\] Don't introduce invalid syntax when upgrading old-style type aliases with parenthesized multiline values (`UP040`) ([#16026](https://github.com/astral-sh/ruff/pull/16026))
+- \[`pyupgrade`\] Ensure we do not rename two type parameters to the same name (`UP049`) ([#16038](https://github.com/astral-sh/ruff/pull/16038))
+- \[`pyupgrade`\] \[`ruff`\] Don't apply renamings if the new name is shadowed in a scope of one of the references to the binding (`UP049`, `RUF052`) ([#16032](https://github.com/astral-sh/ruff/pull/16032))
+- \[`ruff`\] Update `RUF009` to behave similar to `B008` and ignore attributes with immutable types ([#16048](https://github.com/astral-sh/ruff/pull/16048))
+
+### Server
+
+- Root exclusions in the server to project root ([#16043](https://github.com/astral-sh/ruff/pull/16043))
+
+### Bug fixes
+
+- \[`flake8-datetime`\] Ignore `.replace()` calls while looking for `.astimezone` ([#16050](https://github.com/astral-sh/ruff/pull/16050))
+- \[`flake8-type-checking`\] Avoid `TC004` false positive where the runtime definition is provided by `__getattr__` ([#16052](https://github.com/astral-sh/ruff/pull/16052))
+
+### Documentation
+
+- Improve `ruff-lsp` migration document ([#16072](https://github.com/astral-sh/ruff/pull/16072))
+- Undeprecate `ruff.nativeServer` ([#16039](https://github.com/astral-sh/ruff/pull/16039))
+
+## 0.9.5
+
+### Preview features
+
+- Recognize all symbols named `TYPE_CHECKING` for `in_type_checking_block` ([#15719](https://github.com/astral-sh/ruff/pull/15719))
+- \[`flake8-comprehensions`\] Handle builtins at top of file correctly for `unnecessary-dict-comprehension-for-iterable` (`C420`) ([#15837](https://github.com/astral-sh/ruff/pull/15837))
+- \[`flake8-logging`\] `.exception()` and `exc_info=` outside exception handlers (`LOG004`, `LOG014`) ([#15799](https://github.com/astral-sh/ruff/pull/15799))
+- \[`flake8-pyi`\] Fix incorrect behaviour of `custom-typevar-return-type` preview-mode autofix if `typing` was already imported (`PYI019`) ([#15853](https://github.com/astral-sh/ruff/pull/15853))
+- \[`flake8-pyi`\] Fix more complex cases (`PYI019`) ([#15821](https://github.com/astral-sh/ruff/pull/15821))
+- \[`flake8-pyi`\] Make `PYI019` autofixable for `.py` files in preview mode as well as stubs ([#15889](https://github.com/astral-sh/ruff/pull/15889))
+- \[`flake8-pyi`\] Remove type parameter correctly when it is the last (`PYI019`) ([#15854](https://github.com/astral-sh/ruff/pull/15854))
+- \[`pylint`\] Fix missing parens in unsafe fix for `unnecessary-dunder-call` (`PLC2801`) ([#15762](https://github.com/astral-sh/ruff/pull/15762))
+- \[`pyupgrade`\] Better messages and diagnostic range (`UP015`) ([#15872](https://github.com/astral-sh/ruff/pull/15872))
+- \[`pyupgrade`\] Rename private type parameters in PEP 695 generics (`UP049`) ([#15862](https://github.com/astral-sh/ruff/pull/15862))
+- \[`refurb`\] Also report non-name expressions (`FURB169`) ([#15905](https://github.com/astral-sh/ruff/pull/15905))
+- \[`refurb`\] Mark fix as unsafe if there are comments (`FURB171`) ([#15832](https://github.com/astral-sh/ruff/pull/15832))
+- \[`ruff`\] Classes with mixed type variable style (`RUF053`) ([#15841](https://github.com/astral-sh/ruff/pull/15841))
+- \[`airflow`\] `BashOperator` has been moved to `airflow.providers.standard.operators.bash.BashOperator` (`AIR302`) ([#15922](https://github.com/astral-sh/ruff/pull/15922))
+- \[`flake8-pyi`\] Add autofix for unused-private-type-var (`PYI018`) ([#15999](https://github.com/astral-sh/ruff/pull/15999))
+- \[`flake8-pyi`\] Significantly improve accuracy of `PYI019` if preview mode is enabled ([#15888](https://github.com/astral-sh/ruff/pull/15888))
+
+### Rule changes
+
+- Preserve triple quotes and prefixes for strings ([#15818](https://github.com/astral-sh/ruff/pull/15818))
+- \[`flake8-comprehensions`\] Skip when `TypeError` present from too many (kw)args for `C410`,`C411`, and `C418` ([#15838](https://github.com/astral-sh/ruff/pull/15838))
+- \[`flake8-pyi`\] Rename `PYI019` and improve its diagnostic message ([#15885](https://github.com/astral-sh/ruff/pull/15885))
+- \[`pep8-naming`\] Ignore `@override` methods (`N803`) ([#15954](https://github.com/astral-sh/ruff/pull/15954))
+- \[`pyupgrade`\] Reuse replacement logic from `UP046` and `UP047` to preserve more comments (`UP040`) ([#15840](https://github.com/astral-sh/ruff/pull/15840))
+- \[`ruff`\] Analyze deferred annotations before enforcing `mutable-(data)class-default` and `function-call-in-dataclass-default-argument` (`RUF008`,`RUF009`,`RUF012`) ([#15921](https://github.com/astral-sh/ruff/pull/15921))
+- \[`pycodestyle`\] Exempt `sys.path += ...` calls (`E402`) ([#15980](https://github.com/astral-sh/ruff/pull/15980))
+
+### Configuration
+
+- Config error only when `flake8-import-conventions` alias conflicts with `isort.required-imports` bound name ([#15918](https://github.com/astral-sh/ruff/pull/15918))
+- Workaround Even Better TOML crash related to `allOf` ([#15992](https://github.com/astral-sh/ruff/pull/15992))
+
+### Bug fixes
+
+- \[`flake8-comprehensions`\] Unnecessary `list` comprehension (rewrite as a `set` comprehension) (`C403`) - Handle extraneous parentheses around list comprehension ([#15877](https://github.com/astral-sh/ruff/pull/15877))
+- \[`flake8-comprehensions`\] Handle trailing comma in fixes for `unnecessary-generator-list/set` (`C400`,`C401`) ([#15929](https://github.com/astral-sh/ruff/pull/15929))
+- \[`flake8-pyi`\] Fix several correctness issues with `custom-type-var-return-type` (`PYI019`) ([#15851](https://github.com/astral-sh/ruff/pull/15851))
+- \[`pep8-naming`\] Consider any number of leading underscore for `N801` ([#15988](https://github.com/astral-sh/ruff/pull/15988))
+- \[`pyflakes`\] Visit forward annotations in `TypeAliasType` as types (`F401`) ([#15829](https://github.com/astral-sh/ruff/pull/15829))
+- \[`pylint`\] Correct min/max auto-fix and suggestion for (`PL1730`) ([#15930](https://github.com/astral-sh/ruff/pull/15930))
+- \[`refurb`\] Handle unparenthesized tuples correctly (`FURB122`, `FURB142`) ([#15953](https://github.com/astral-sh/ruff/pull/15953))
+- \[`refurb`\] Avoid `None | None` as well as better detection and fix (`FURB168`) ([#15779](https://github.com/astral-sh/ruff/pull/15779))
+
+### Documentation
+
+- Add deprecation warning for `ruff-lsp` related settings ([#15850](https://github.com/astral-sh/ruff/pull/15850))
+- Docs (`linter.md`): clarify that Python files are always searched for in subdirectories ([#15882](https://github.com/astral-sh/ruff/pull/15882))
+- Fix a typo in `non_pep695_generic_class.rs` ([#15946](https://github.com/astral-sh/ruff/pull/15946))
+- Improve Docs: Pylint subcategories' codes ([#15909](https://github.com/astral-sh/ruff/pull/15909))
+- Remove non-existing `lint.extendIgnore` editor setting ([#15844](https://github.com/astral-sh/ruff/pull/15844))
+- Update black deviations ([#15928](https://github.com/astral-sh/ruff/pull/15928))
+- Mention `UP049` in `UP046` and `UP047`, add `See also` section to `UP040` ([#15956](https://github.com/astral-sh/ruff/pull/15956))
+- Add instance variable examples to `RUF012` ([#15982](https://github.com/astral-sh/ruff/pull/15982))
+- Explain precedence for `ignore` and `select` config ([#15883](https://github.com/astral-sh/ruff/pull/15883))
+
+## 0.9.4
+
+### Preview features
+
+- \[`airflow`\] Extend airflow context parameter check for `BaseOperator.execute` (`AIR302`) ([#15713](https://github.com/astral-sh/ruff/pull/15713))
+- \[`airflow`\] Update `AIR302` to check for deprecated context keys ([#15144](https://github.com/astral-sh/ruff/pull/15144))
+- \[`flake8-bandit`\] Permit suspicious imports within stub files (`S4`) ([#15822](https://github.com/astral-sh/ruff/pull/15822))
+- \[`pylint`\] Do not trigger `PLR6201` on empty collections ([#15732](https://github.com/astral-sh/ruff/pull/15732))
+- \[`refurb`\] Do not emit diagnostic when loop variables are used outside loop body (`FURB122`) ([#15757](https://github.com/astral-sh/ruff/pull/15757))
+- \[`ruff`\] Add support for more `re` patterns (`RUF055`) ([#15764](https://github.com/astral-sh/ruff/pull/15764))
+- \[`ruff`\] Check for shadowed `map` before suggesting fix (`RUF058`) ([#15790](https://github.com/astral-sh/ruff/pull/15790))
+- \[`ruff`\] Do not emit diagnostic when all arguments to `zip()` are variadic (`RUF058`) ([#15744](https://github.com/astral-sh/ruff/pull/15744))
+- \[`ruff`\] Parenthesize fix when argument spans multiple lines for `unnecessary-round` (`RUF057`) ([#15703](https://github.com/astral-sh/ruff/pull/15703))
+
+### Rule changes
+
+- Preserve quote style in generated code ([#15726](https://github.com/astral-sh/ruff/pull/15726), [#15778](https://github.com/astral-sh/ruff/pull/15778), [#15794](https://github.com/astral-sh/ruff/pull/15794))
+- \[`flake8-bugbear`\] Exempt `NewType` calls where the original type is immutable (`B008`) ([#15765](https://github.com/astral-sh/ruff/pull/15765))
+- \[`pylint`\] Honor banned top-level imports by `TID253` in `PLC0415`. ([#15628](https://github.com/astral-sh/ruff/pull/15628))
+- \[`pyupgrade`\] Ignore `is_typeddict` and `TypedDict` for `deprecated-import` (`UP035`) ([#15800](https://github.com/astral-sh/ruff/pull/15800))
+
+### CLI
+
+- Fix formatter warning message for `flake8-quotes` option ([#15788](https://github.com/astral-sh/ruff/pull/15788))
+- Implement tab autocomplete for `ruff config` ([#15603](https://github.com/astral-sh/ruff/pull/15603))
+
+### Bug fixes
+
+- \[`flake8-comprehensions`\] Do not emit `unnecessary-map` diagnostic when lambda has different arity (`C417`) ([#15802](https://github.com/astral-sh/ruff/pull/15802))
+- \[`flake8-comprehensions`\] Parenthesize `sorted` when needed for `unnecessary-call-around-sorted` (`C413`) ([#15825](https://github.com/astral-sh/ruff/pull/15825))
+- \[`pyupgrade`\] Handle end-of-line comments for `quoted-annotation` (`UP037`) ([#15824](https://github.com/astral-sh/ruff/pull/15824))
+
+### Documentation
+
+- Add missing config docstrings ([#15803](https://github.com/astral-sh/ruff/pull/15803))
+- Add references to `trio.run_process` and `anyio.run_process` ([#15761](https://github.com/astral-sh/ruff/pull/15761))
+- Use `uv init --lib` in tutorial ([#15718](https://github.com/astral-sh/ruff/pull/15718))
+
 ## 0.9.3
 
 ### Preview features

CONTRIBUTING.md

@@ -526,7 +526,7 @@ cargo benchmark
 #### Benchmark-driven Development
 
 Ruff uses [Criterion.rs](https://bheisler.github.io/criterion.rs/book/) for benchmarks. You can use
-`--save-baseline=<name>` to store an initial baseline benchmark (e.g. on `main`) and then use
+`--save-baseline=<name>` to store an initial baseline benchmark (e.g., on `main`) and then use
 `--benchmark=<name>` to compare against that benchmark. Criterion will print a message telling you
 if the benchmark improved/regressed compared to that baseline.
 
@@ -678,9 +678,9 @@ utils with it:
 23 Newline 24
 ```
 
-- `cargo dev print-cst <file>`: Print the CST of a python file using
+- `cargo dev print-cst <file>`: Print the CST of a Python file using
     [LibCST](https://github.com/Instagram/LibCST), which is used in addition to the RustPython parser
-    in Ruff. E.g. for `if True: pass # comment` everything including the whitespace is represented:
+    in Ruff. For example, for `if True: pass # comment`, everything, including the whitespace, is represented:
 
 ```text
 Module {

Cargo.toml

@@ -74,11 +74,13 @@ env_logger = { version = "0.11.0" }
 etcetera = { version = "0.8.0" }
 fern = { version = "0.7.0" }
 filetime = { version = "0.2.23" }
+getrandom = { version = "0.3.1" }
 glob = { version = "0.3.1" }
 globset = { version = "0.4.14" }
 globwalk = { version = "0.9.1" }
 hashbrown = { version = "0.15.0", default-features = false, features = [
     "raw-entry",
+    "equivalent",
     "inline-more",
 ] }
 ignore = { version = "0.4.22" }
@@ -116,12 +118,12 @@ proc-macro2 = { version = "1.0.79" }
 pyproject-toml = { version = "0.13.4" }
 quick-junit = { version = "0.5.0" }
 quote = { version = "1.0.23" }
-rand = { version = "0.8.5" }
+rand = { version = "0.9.0" }
 rayon = { version = "1.10.0" }
 regex = { version = "1.10.2" }
 rustc-hash = { version = "2.0.0" }
 # When updating salsa, make sure to also update the revision in `fuzz/Cargo.toml`
-salsa = { git = "https://github.com/salsa-rs/salsa.git", rev = "88a1d7774d78f048fbd77d40abca9ebd729fd1f0" }
+salsa = { git = "https://github.com/salsa-rs/salsa.git", rev = "c8826fa4d1d9e3cba4c6e578763878b71fa9a10d" }
 schemars = { version = "0.8.16" }
 seahash = { version = "4.1.0" }
 serde = { version = "1.0.197", features = ["derive"] }
@@ -134,10 +136,15 @@ serde_with = { version = "3.6.0", default-features = false, features = [
 shellexpand = { version = "3.0.0" }
 similar = { version = "2.4.0", features = ["inline"] }
 smallvec = { version = "1.13.2" }
-snapbox = { version = "0.6.0", features = ["diff", "term-svg", "cmd", "examples"] }
+snapbox = { version = "0.6.0", features = [
+    "diff",
+    "term-svg",
+    "cmd",
+    "examples",
+] }
 static_assertions = "1.1.0"
-strum = { version = "0.26.0", features = ["strum_macros"] }
-strum_macros = { version = "0.26.0" }
+strum = { version = "0.27.0", features = ["strum_macros"] }
+strum_macros = { version = "0.27.0" }
 syn = { version = "2.0.55" }
 tempfile = { version = "3.9.0" }
 test-case = { version = "3.3.1" }
@@ -159,7 +166,6 @@ unicode-ident = { version = "1.0.12" }
 unicode-width = { version = "0.2.0" }
 unicode_names2 = { version = "1.2.2" }
 unicode-normalization = { version = "0.1.23" }
-ureq = { version = "2.9.6" }
 url = { version = "2.5.0" }
 uuid = { version = "1.6.1", features = [
     "v4",
@@ -173,6 +179,10 @@ wasm-bindgen-test = { version = "0.3.42" }
 wild = { version = "2" }
 zip = { version = "0.6.6", default-features = false }
 
+[workspace.metadata.cargo-shear]
+ignored = ["getrandom"]
+
+
 [workspace.lints.rust]
 unsafe_code = "warn"
 unreachable_pub = "warn"
@@ -305,7 +315,11 @@ local-artifacts-jobs = ["./build-binaries", "./build-docker"]
 # Publish jobs to run in CI
 publish-jobs = ["./publish-pypi", "./publish-wasm"]
 # Post-announce jobs to run in CI
-post-announce-jobs = ["./notify-dependents", "./publish-docs", "./publish-playground"]
+post-announce-jobs = [
+    "./notify-dependents",
+    "./publish-docs",
+    "./publish-playground",
+]
 # Custom permissions for GitHub Jobs
 github-custom-job-permissions = { "build-docker" = { packages = "write", contents = "read" }, "publish-wasm" = { contents = "read", id-token = "write", packages = "write" } }
 # Whether to install an updater program

README.md

@@ -149,8 +149,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.9.3/install.sh | sh
-powershell -c "irm https://astral.sh/ruff/0.9.3/install.ps1 | iex"
+curl -LsSf https://astral.sh/ruff/0.9.7/install.sh | sh
+powershell -c "irm https://astral.sh/ruff/0.9.7/install.ps1 | iex"
 ```
 
 You can also install Ruff via [Homebrew](https://formulae.brew.sh/formula/ruff), [Conda](https://anaconda.org/conda-forge/ruff),
@@ -183,7 +183,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.9.3
+  rev: v0.9.7
   hooks:
     # Run the linter.
     - id: ruff
@@ -452,6 +452,7 @@ Ruff is used by a number of major open-source projects and companies, including:
 - ING Bank ([popmon](https://github.com/ing-bank/popmon), [probatus](https://github.com/ing-bank/probatus))
 - [Ibis](https://github.com/ibis-project/ibis)
 - [ivy](https://github.com/unifyai/ivy)
+- [JAX](https://github.com/jax-ml/jax)
 - [Jupyter](https://github.com/jupyter-server/jupyter_server)
 - [Kraken Tech](https://kraken.tech/)
 - [LangChain](https://github.com/hwchase17/langchain)

SECURITY.md

@@ -0,0 +1,15 @@
+# Security policy
+
+## Reporting a vulnerability
+
+If you have found a possible vulnerability, please email `security at astral dot sh`.
+
+## Bug bounties
+
+While we sincerely appreciate and encourage reports of suspected security problems, please note that
+Astral does not currently run any bug bounty programs.
+
+## Vulnerability disclosures
+
+Critical vulnerabilities will be disclosed via GitHub's
+[security advisory](https://github.com/astral-sh/ruff/security) system.

crates/red_knot/Cargo.toml

@@ -16,6 +16,7 @@ red_knot_python_semantic = { workspace = true }
 red_knot_project = { workspace = true, features = ["zstd"] }
 red_knot_server = { workspace = true }
 ruff_db = { workspace = true, features = ["os", "cache"] }
+ruff_python_ast = { workspace = true }
 
 anyhow = { workspace = true }
 chrono = { workspace = true }

crates/red_knot/README.md

@@ -0,0 +1,25 @@
+# Red Knot
+
+Red Knot is an extremely fast type checker.
+Currently, it is a work-in-progress and not ready for user testing.
+
+Red Knot is designed to prioritize good type inference, even in unannotated code,
+and aims to avoid false positives.
+
+While Red Knot will produce similar results to mypy and pyright on many codebases,
+100% compatibility with these tools is a non-goal.
+On some codebases, Red Knot's design decisions lead to different outcomes
+than you would get from running one of these more established tools.
+
+## Contributing
+
+Core type checking tests are written as Markdown code blocks.
+They can be found in [`red_knot_python_semantic/resources/mdtest`][resources-mdtest].
+See [`red_knot_test/README.md`][mdtest-readme] for more information
+on the test framework itself.
+
+The list of open issues can be found [here][open-issues].
+
+[mdtest-readme]: ../red_knot_test/README.md
+[open-issues]: https://github.com/astral-sh/ruff/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20label%3Ared-knot
+[resources-mdtest]: ../red_knot_python_semantic/resources/mdtest

crates/red_knot/build.rs

@@ -0,0 +1,104 @@
+use std::{
+    fs,
+    path::{Path, PathBuf},
+    process::Command,
+};
+
+fn main() {
+    // The workspace root directory is not available without walking up the tree
+    // https://github.com/rust-lang/cargo/issues/3946
+    let workspace_root = Path::new(&std::env::var("CARGO_MANIFEST_DIR").unwrap())
+        .join("..")
+        .join("..");
+
+    commit_info(&workspace_root);
+
+    #[allow(clippy::disallowed_methods)]
+    let target = std::env::var("TARGET").unwrap();
+    println!("cargo::rustc-env=RUST_HOST_TARGET={target}");
+}
+
+fn commit_info(workspace_root: &Path) {
+    // If not in a git repository, do not attempt to retrieve commit information
+    let git_dir = workspace_root.join(".git");
+    if !git_dir.exists() {
+        return;
+    }
+
+    if let Some(git_head_path) = git_head(&git_dir) {
+        println!("cargo:rerun-if-changed={}", git_head_path.display());
+
+        let git_head_contents = fs::read_to_string(git_head_path);
+        if let Ok(git_head_contents) = git_head_contents {
+            // The contents are either a commit or a reference in the following formats
+            // - "<commit>" when the head is detached
+            // - "ref <ref>" when working on a branch
+            // If a commit, checking if the HEAD file has changed is sufficient
+            // If a ref, we need to add the head file for that ref to rebuild on commit
+            let mut git_ref_parts = git_head_contents.split_whitespace();
+            git_ref_parts.next();
+            if let Some(git_ref) = git_ref_parts.next() {
+                let git_ref_path = git_dir.join(git_ref);
+                println!("cargo:rerun-if-changed={}", git_ref_path.display());
+            }
+        }
+    }
+
+    let output = match Command::new("git")
+        .arg("log")
+        .arg("-1")
+        .arg("--date=short")
+        .arg("--abbrev=9")
+        .arg("--format=%H %h %cd %(describe)")
+        .output()
+    {
+        Ok(output) if output.status.success() => output,
+        _ => return,
+    };
+    let stdout = String::from_utf8(output.stdout).unwrap();
+    let mut parts = stdout.split_whitespace();
+    let mut next = || parts.next().unwrap();
+    let _commit_hash = next();
+    println!("cargo::rustc-env=RED_KNOT_COMMIT_SHORT_HASH={}", next());
+    println!("cargo::rustc-env=RED_KNOT_COMMIT_DATE={}", next());
+
+    // Describe can fail for some commits
+    // https://git-scm.com/docs/pretty-formats#Documentation/pretty-formats.txt-emdescribeoptionsem
+    if let Some(describe) = parts.next() {
+        let mut describe_parts = describe.split('-');
+        let _last_tag = describe_parts.next().unwrap();
+
+        // If this is the tagged commit, this component will be missing
+        println!(
+            "cargo::rustc-env=RED_KNOT_LAST_TAG_DISTANCE={}",
+            describe_parts.next().unwrap_or("0")
+        );
+    }
+}
+
+fn git_head(git_dir: &Path) -> Option<PathBuf> {
+    // The typical case is a standard git repository.
+    let git_head_path = git_dir.join("HEAD");
+    if git_head_path.exists() {
+        return Some(git_head_path);
+    }
+    if !git_dir.is_file() {
+        return None;
+    }
+    // If `.git/HEAD` doesn't exist and `.git` is actually a file,
+    // then let's try to attempt to read it as a worktree. If it's
+    // a worktree, then its contents will look like this, e.g.:
+    //
+    //     gitdir: /home/andrew/astral/uv/main/.git/worktrees/pr2
+    //
+    // And the HEAD file we want to watch will be at:
+    //
+    //     /home/andrew/astral/uv/main/.git/worktrees/pr2/HEAD
+    let contents = fs::read_to_string(git_dir).ok()?;
+    let (label, worktree_path) = contents.split_once(':')?;
+    if label != "gitdir" {
+        return None;
+    }
+    let worktree_path = worktree_path.trim();
+    Some(PathBuf::from(worktree_path))
+}

crates/red_knot/src/args.rs

@@ -0,0 +1,204 @@
+use crate::logging::Verbosity;
+use crate::python_version::PythonVersion;
+use clap::{ArgAction, ArgMatches, Error, Parser};
+use red_knot_project::metadata::options::{EnvironmentOptions, Options, TerminalOptions};
+use red_knot_project::metadata::value::{RangedValue, RelativePathBuf};
+use red_knot_python_semantic::lint;
+use ruff_db::system::SystemPathBuf;
+
+#[derive(Debug, Parser)]
+#[command(
+    author,
+    name = "red-knot",
+    about = "An extremely fast Python type checker."
+)]
+#[command(version)]
+pub(crate) struct Args {
+    #[command(subcommand)]
+    pub(crate) command: Command,
+}
+
+#[derive(Debug, clap::Subcommand)]
+pub(crate) enum Command {
+    /// Check a project for type errors.
+    Check(CheckCommand),
+
+    /// Start the language server
+    Server,
+
+    /// Display Red Knot's version
+    Version,
+}
+
+#[derive(Debug, Parser)]
+pub(crate) struct CheckCommand {
+    /// Run the command within the given project directory.
+    ///
+    /// All `pyproject.toml` files will be discovered by walking up the directory tree from the given project directory,
+    /// as will the project's virtual environment (`.venv`) unless the `venv-path` option is set.
+    ///
+    /// Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+    #[arg(long, value_name = "PROJECT")]
+    pub(crate) project: Option<SystemPathBuf>,
+
+    /// Path to the virtual environment the project uses.
+    ///
+    /// If provided, red-knot will use the `site-packages` directory of this virtual environment
+    /// to resolve type information for the project's third-party dependencies.
+    #[arg(long, value_name = "PATH")]
+    pub(crate) venv_path: Option<SystemPathBuf>,
+
+    /// Custom directory to use for stdlib typeshed stubs.
+    #[arg(long, value_name = "PATH", alias = "custom-typeshed-dir")]
+    pub(crate) typeshed: Option<SystemPathBuf>,
+
+    /// Additional path to use as a module-resolution source (can be passed multiple times).
+    #[arg(long, value_name = "PATH")]
+    pub(crate) extra_search_path: Option<Vec<SystemPathBuf>>,
+
+    /// Python version to assume when resolving types.
+    #[arg(long, value_name = "VERSION", alias = "target-version")]
+    pub(crate) python_version: Option<PythonVersion>,
+
+    #[clap(flatten)]
+    pub(crate) verbosity: Verbosity,
+
+    #[clap(flatten)]
+    pub(crate) rules: RulesArg,
+
+    /// Use exit code 1 if there are any warning-level diagnostics.
+    #[arg(long, conflicts_with = "exit_zero", default_missing_value = "true", num_args=0..1)]
+    pub(crate) error_on_warning: Option<bool>,
+
+    /// Always use exit code 0, even when there are error-level diagnostics.
+    #[arg(long)]
+    pub(crate) exit_zero: bool,
+
+    /// Run in watch mode by re-running whenever files change.
+    #[arg(long, short = 'W')]
+    pub(crate) watch: bool,
+}
+
+impl CheckCommand {
+    pub(crate) fn into_options(self) -> Options {
+        let rules = if self.rules.is_empty() {
+            None
+        } else {
+            Some(
+                self.rules
+                    .into_iter()
+                    .map(|(rule, level)| (RangedValue::cli(rule), RangedValue::cli(level)))
+                    .collect(),
+            )
+        };
+
+        Options {
+            environment: Some(EnvironmentOptions {
+                python_version: self
+                    .python_version
+                    .map(|version| RangedValue::cli(version.into())),
+                venv_path: self.venv_path.map(RelativePathBuf::cli),
+                typeshed: self.typeshed.map(RelativePathBuf::cli),
+                extra_paths: self.extra_search_path.map(|extra_search_paths| {
+                    extra_search_paths
+                        .into_iter()
+                        .map(RelativePathBuf::cli)
+                        .collect()
+                }),
+                ..EnvironmentOptions::default()
+            }),
+            terminal: Some(TerminalOptions {
+                error_on_warning: self.error_on_warning,
+            }),
+            rules,
+            ..Default::default()
+        }
+    }
+}
+
+/// A list of rules to enable or disable with a given severity.
+///
+/// This type is used to parse the `--error`, `--warn`, and `--ignore` arguments
+/// while preserving the order in which they were specified (arguments last override previous severities).
+#[derive(Debug)]
+pub(crate) struct RulesArg(Vec<(String, lint::Level)>);
+
+impl RulesArg {
+    fn is_empty(&self) -> bool {
+        self.0.is_empty()
+    }
+
+    fn into_iter(self) -> impl Iterator<Item = (String, lint::Level)> {
+        self.0.into_iter()
+    }
+}
+
+impl clap::FromArgMatches for RulesArg {
+    fn from_arg_matches(matches: &ArgMatches) -> Result<Self, Error> {
+        let mut rules = Vec::new();
+
+        for (level, arg_id) in [
+            (lint::Level::Ignore, "ignore"),
+            (lint::Level::Warn, "warn"),
+            (lint::Level::Error, "error"),
+        ] {
+            let indices = matches.indices_of(arg_id).into_iter().flatten();
+            let levels = matches.get_many::<String>(arg_id).into_iter().flatten();
+            rules.extend(
+                indices
+                    .zip(levels)
+                    .map(|(index, rule)| (index, rule, level)),
+            );
+        }
+
+        // Sort by their index so that values specified later override earlier ones.
+        rules.sort_by_key(|(index, _, _)| *index);
+
+        Ok(Self(
+            rules
+                .into_iter()
+                .map(|(_, rule, level)| (rule.to_owned(), level))
+                .collect(),
+        ))
+    }
+
+    fn update_from_arg_matches(&mut self, matches: &ArgMatches) -> Result<(), Error> {
+        self.0 = Self::from_arg_matches(matches)?.0;
+        Ok(())
+    }
+}
+
+impl clap::Args for RulesArg {
+    fn augment_args(cmd: clap::Command) -> clap::Command {
+        const HELP_HEADING: &str = "Enabling / disabling rules";
+
+        cmd.arg(
+            clap::Arg::new("error")
+                .long("error")
+                .action(ArgAction::Append)
+                .help("Treat the given rule as having severity 'error'. Can be specified multiple times.")
+                .value_name("RULE")
+                .help_heading(HELP_HEADING),
+        )
+        .arg(
+            clap::Arg::new("warn")
+                .long("warn")
+                .action(ArgAction::Append)
+                .help("Treat the given rule as having severity 'warn'. Can be specified multiple times.")
+                .value_name("RULE")
+                .help_heading(HELP_HEADING),
+        )
+        .arg(
+            clap::Arg::new("ignore")
+                .long("ignore")
+                .action(ArgAction::Append)
+                .help("Disables the rule. Can be specified multiple times.")
+                .value_name("RULE")
+                .help_heading(HELP_HEADING),
+        )
+    }
+
+    fn augment_args_for_update(cmd: clap::Command) -> clap::Command {
+        Self::augment_args(cmd)
+    }
+}

crates/red_knot/src/main.rs

@@ -1,101 +1,28 @@
+use std::io::{self, BufWriter, Write};
 use std::process::{ExitCode, Termination};
+
+use anyhow::Result;
 use std::sync::Mutex;
 
+use crate::args::{Args, CheckCommand, Command};
+use crate::logging::setup_tracing;
 use anyhow::{anyhow, Context};
 use clap::Parser;
 use colored::Colorize;
 use crossbeam::channel as crossbeam_channel;
-use python_version::PythonVersion;
-use red_knot_project::metadata::options::{EnvironmentOptions, Options};
-use red_knot_project::metadata::value::{RangedValue, RelativePathBuf};
-use red_knot_project::watch;
+use red_knot_project::metadata::options::Options;
 use red_knot_project::watch::ProjectWatcher;
+use red_knot_project::{watch, Db};
 use red_knot_project::{ProjectDatabase, ProjectMetadata};
 use red_knot_server::run_server;
-use ruff_db::diagnostic::Diagnostic;
+use ruff_db::diagnostic::{Diagnostic, DisplayDiagnosticConfig, Severity};
 use ruff_db::system::{OsSystem, System, SystemPath, SystemPathBuf};
 use salsa::plumbing::ZalsaDatabase;
 
-use crate::logging::{setup_tracing, Verbosity};
-
+mod args;
 mod logging;
 mod python_version;
-mod verbosity;
-
-#[derive(Debug, Parser)]
-#[command(
-    author,
-    name = "red-knot",
-    about = "An extremely fast Python type checker."
-)]
-#[command(version)]
-struct Args {
-    #[command(subcommand)]
-    pub(crate) command: Option<Command>,
-
-    /// Run the command within the given project directory.
-    ///
-    /// All `pyproject.toml` files will be discovered by walking up the directory tree from the given project directory,
-    /// as will the project's virtual environment (`.venv`) unless the `venv-path` option is set.
-    ///
-    /// Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
-    #[arg(long, value_name = "PROJECT")]
-    project: Option<SystemPathBuf>,
-
-    /// Path to the virtual environment the project uses.
-    ///
-    /// If provided, red-knot will use the `site-packages` directory of this virtual environment
-    /// to resolve type information for the project's third-party dependencies.
-    #[arg(long, value_name = "PATH")]
-    venv_path: Option<SystemPathBuf>,
-
-    /// Custom directory to use for stdlib typeshed stubs.
-    #[arg(long, value_name = "PATH", alias = "custom-typeshed-dir")]
-    typeshed: Option<SystemPathBuf>,
-
-    /// Additional path to use as a module-resolution source (can be passed multiple times).
-    #[arg(long, value_name = "PATH")]
-    extra_search_path: Option<Vec<SystemPathBuf>>,
-
-    /// Python version to assume when resolving types.
-    #[arg(long, value_name = "VERSION", alias = "target-version")]
-    python_version: Option<PythonVersion>,
-
-    #[clap(flatten)]
-    verbosity: Verbosity,
-
-    /// Run in watch mode by re-running whenever files change.
-    #[arg(long, short = 'W')]
-    watch: bool,
-}
-
-impl Args {
-    fn to_options(&self) -> Options {
-        Options {
-            environment: Some(EnvironmentOptions {
-                python_version: self
-                    .python_version
-                    .map(|version| RangedValue::cli(version.into())),
-                venv_path: self.venv_path.as_ref().map(RelativePathBuf::cli),
-                typeshed: self.typeshed.as_ref().map(RelativePathBuf::cli),
-                extra_paths: self.extra_search_path.as_ref().map(|extra_search_paths| {
-                    extra_search_paths
-                        .iter()
-                        .map(RelativePathBuf::cli)
-                        .collect()
-                }),
-                ..EnvironmentOptions::default()
-            }),
-            ..Default::default()
-        }
-    }
-}
-
-#[derive(Debug, clap::Subcommand)]
-pub enum Command {
-    /// Start the language server
-    Server,
-}
+mod version;
 
 #[allow(clippy::print_stdout, clippy::unnecessary_wraps, clippy::print_stderr)]
 pub fn main() -> ExitStatus {
@@ -122,10 +49,21 @@ pub fn main() -> ExitStatus {
 fn run() -> anyhow::Result<ExitStatus> {
     let args = Args::parse_from(std::env::args());
 
-    if matches!(args.command, Some(Command::Server)) {
-        return run_server().map(|()| ExitStatus::Success);
+    match args.command {
+        Command::Server => run_server().map(|()| ExitStatus::Success),
+        Command::Check(check_args) => run_check(check_args),
+        Command::Version => version().map(|()| ExitStatus::Success),
     }
+}
 
+pub(crate) fn version() -> Result<()> {
+    let mut stdout = BufWriter::new(io::stdout().lock());
+    let version_info = crate::version::version();
+    writeln!(stdout, "red knot {}", &version_info)?;
+    Ok(())
+}
+
+fn run_check(args: CheckCommand) -> anyhow::Result<ExitStatus> {
     let verbosity = args.verbosity.level();
     countme::enable(verbosity.is_trace());
     let _guard = setup_tracing(verbosity)?;
@@ -156,11 +94,15 @@ fn run() -> anyhow::Result<ExitStatus> {
         .unwrap_or_else(|| cli_base_path.clone());
 
     let system = OsSystem::new(cwd);
-    let cli_options = args.to_options();
-    let mut workspace_metadata = ProjectMetadata::discover(system.current_directory(), &system)?;
-    workspace_metadata.apply_cli_options(cli_options.clone());
+    let watch = args.watch;
+    let exit_zero = args.exit_zero;
 
-    let mut db = ProjectDatabase::new(workspace_metadata, system)?;
+    let cli_options = args.into_options();
+    let mut project_metadata = ProjectMetadata::discover(system.current_directory(), &system)?;
+    project_metadata.apply_cli_options(cli_options.clone());
+    project_metadata.apply_configuration_files(&system)?;
+
+    let mut db = ProjectDatabase::new(project_metadata, system)?;
 
     let (main_loop, main_loop_cancellation_token) = MainLoop::new(cli_options);
 
@@ -174,7 +116,7 @@ fn run() -> anyhow::Result<ExitStatus> {
         }
     })?;
 
-    let exit_status = if args.watch {
+    let exit_status = if watch {
         main_loop.watch(&mut db)?
     } else {
         main_loop.run(&mut db)
@@ -184,7 +126,11 @@ fn run() -> anyhow::Result<ExitStatus> {
 
     std::mem::forget(db);
 
-    Ok(exit_status)
+    if exit_zero {
+        Ok(ExitStatus::Success)
+    } else {
+        Ok(exit_status)
+    }
 }
 
 #[derive(Copy, Clone)]
@@ -285,11 +231,24 @@ impl MainLoop {
                     result,
                     revision: check_revision,
                 } => {
-                    let has_diagnostics = !result.is_empty();
+                    let display_config = DisplayDiagnosticConfig::default()
+                        .color(colored::control::SHOULD_COLORIZE.should_colorize());
+
+                    let min_error_severity =
+                        if db.project().settings(db).terminal().error_on_warning {
+                            Severity::Warning
+                        } else {
+                            Severity::Error
+                        };
+
+                    let failed = result
+                        .iter()
+                        .any(|diagnostic| diagnostic.severity() >= min_error_severity);
+
                     if check_revision == revision {
                         #[allow(clippy::print_stdout)]
                         for diagnostic in result {
-                            println!("{}", diagnostic.display(db));
+                            println!("{}", diagnostic.display(db, &display_config));
                         }
                     } else {
                         tracing::debug!(
@@ -298,7 +257,7 @@ impl MainLoop {
                     }
 
                     if self.watcher.is_none() {
-                        return if has_diagnostics {
+                        return if failed {
                             ExitStatus::Failure
                         } else {
                             ExitStatus::Success

crates/red_knot/src/python_version.rs

@@ -40,7 +40,7 @@ impl std::fmt::Display for PythonVersion {
     }
 }
 
-impl From<PythonVersion> for red_knot_python_semantic::PythonVersion {
+impl From<PythonVersion> for ruff_python_ast::PythonVersion {
     fn from(value: PythonVersion) -> Self {
         match value {
             PythonVersion::Py37 => Self::PY37,
@@ -61,8 +61,8 @@ mod tests {
     #[test]
     fn same_default_as_python_version() {
         assert_eq!(
-            red_knot_python_semantic::PythonVersion::from(PythonVersion::default()),
-            red_knot_python_semantic::PythonVersion::default()
+            ruff_python_ast::PythonVersion::from(PythonVersion::default()),
+            ruff_python_ast::PythonVersion::default()
         );
     }
 }

crates/red_knot/src/verbosity.rs

@@ -1 +0,0 @@
-

crates/red_knot/src/version.rs

@@ -0,0 +1,105 @@
+//! Code for representing Red Knot's release version number.
+use std::fmt;
+
+/// Information about the git repository where Red Knot was built from.
+pub(crate) struct CommitInfo {
+    short_commit_hash: String,
+    commit_date: String,
+    commits_since_last_tag: u32,
+}
+
+/// Red Knot's version.
+pub(crate) struct VersionInfo {
+    /// Red Knot's version, such as "0.5.1"
+    version: String,
+    /// Information about the git commit we may have been built from.
+    ///
+    /// `None` if not built from a git repo or if retrieval failed.
+    commit_info: Option<CommitInfo>,
+}
+
+impl fmt::Display for VersionInfo {
+    /// Formatted version information: `<version>[+<commits>] (<commit> <date>)`
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}", self.version)?;
+
+        if let Some(ref ci) = self.commit_info {
+            if ci.commits_since_last_tag > 0 {
+                write!(f, "+{}", ci.commits_since_last_tag)?;
+            }
+            write!(f, " ({} {})", ci.short_commit_hash, ci.commit_date)?;
+        }
+
+        Ok(())
+    }
+}
+
+/// Returns information about Red Knot's version.
+pub(crate) fn version() -> VersionInfo {
+    // Environment variables are only read at compile-time
+    macro_rules! option_env_str {
+        ($name:expr) => {
+            option_env!($name).map(|s| s.to_string())
+        };
+    }
+
+    // This version is pulled from Cargo.toml and set by Cargo
+    let version = option_env_str!("CARGO_PKG_VERSION").unwrap();
+
+    // Commit info is pulled from git and set by `build.rs`
+    let commit_info =
+        option_env_str!("RED_KNOT_COMMIT_SHORT_HASH").map(|short_commit_hash| CommitInfo {
+            short_commit_hash,
+            commit_date: option_env_str!("RED_KNOT_COMMIT_DATE").unwrap(),
+            commits_since_last_tag: option_env_str!("RED_KNOT_LAST_TAG_DISTANCE")
+                .as_deref()
+                .map_or(0, |value| value.parse::<u32>().unwrap_or(0)),
+        });
+
+    VersionInfo {
+        version,
+        commit_info,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use insta::assert_snapshot;
+
+    use super::{CommitInfo, VersionInfo};
+
+    #[test]
+    fn version_formatting() {
+        let version = VersionInfo {
+            version: "0.0.0".to_string(),
+            commit_info: None,
+        };
+        assert_snapshot!(version, @"0.0.0");
+    }
+
+    #[test]
+    fn version_formatting_with_commit_info() {
+        let version = VersionInfo {
+            version: "0.0.0".to_string(),
+            commit_info: Some(CommitInfo {
+                short_commit_hash: "53b0f5d92".to_string(),
+                commit_date: "2023-10-19".to_string(),
+                commits_since_last_tag: 0,
+            }),
+        };
+        assert_snapshot!(version, @"0.0.0 (53b0f5d92 2023-10-19)");
+    }
+
+    #[test]
+    fn version_formatting_with_commits_since_last_tag() {
+        let version = VersionInfo {
+            version: "0.0.0".to_string(),
+            commit_info: Some(CommitInfo {
+                short_commit_hash: "53b0f5d92".to_string(),
+                commit_date: "2023-10-19".to_string(),
+                commits_since_last_tag: 24,
+            }),
+        };
+        assert_snapshot!(version, @"0.0.0+24 (53b0f5d92 2023-10-19)");
+    }
+}

crates/red_knot/tests/cli.rs

@@ -1,5 +1,5 @@
 use anyhow::Context;
-use insta::Settings;
+use insta::internals::SettingsBindDropGuard;
 use insta_cmd::{assert_cmd_snapshot, get_cargo_bin};
 use std::path::{Path, PathBuf};
 use std::process::Command;
@@ -28,24 +28,29 @@ fn config_override() -> anyhow::Result<()> {
         ),
     ])?;
 
-    case.insta_settings().bind(|| {
-        assert_cmd_snapshot!(case.command(), @r"
-            success: false
-            exit_code: 1
-            ----- stdout -----
-            error[lint:unresolved-attribute] <temp_dir>/test.py:5:7 Type `<module 'sys'>` has no attribute `last_exc`
+    assert_cmd_snapshot!(case.command(), @r###"
+    success: false
+    exit_code: 1
+    ----- stdout -----
+    error: lint:unresolved-attribute
+     --> <temp_dir>/test.py:5:7
+      |
+    4 | # Access `sys.last_exc` that was only added in Python 3.12
+    5 | print(sys.last_exc)
+      |       ^^^^^^^^^^^^ Type `<module 'sys'>` has no attribute `last_exc`
+      |
 
-            ----- stderr -----
-        ");
 
-        assert_cmd_snapshot!(case.command().arg("--python-version").arg("3.12"), @r"
-            success: true
-            exit_code: 0
-            ----- stdout -----
+    ----- stderr -----
+    "###);
 
-            ----- stderr -----
-        ");
-    });
+    assert_cmd_snapshot!(case.command().arg("--python-version").arg("3.12"), @r"
+        success: true
+        exit_code: 0
+        ----- stdout -----
+
+        ----- stderr -----
+    ");
 
     Ok(())
 }
@@ -92,25 +97,31 @@ fn cli_arguments_are_relative_to_the_current_directory() -> anyhow::Result<()> {
         ),
     ])?;
 
-    case.insta_settings().bind(|| {
-        // Make sure that the CLI fails when the `libs` directory is not in the search path.
-        assert_cmd_snapshot!(case.command().current_dir(case.project_dir().join("child")), @r#"
-            success: false
-            exit_code: 1
-            ----- stdout -----
-            error[lint:unresolved-import] <temp_dir>/child/test.py:2:1 Cannot resolve import `utils`
+    // Make sure that the CLI fails when the `libs` directory is not in the search path.
+    assert_cmd_snapshot!(case.command().current_dir(case.root().join("child")), @r###"
+    success: false
+    exit_code: 1
+    ----- stdout -----
+    error: lint:unresolved-import
+     --> <temp_dir>/child/test.py:2:6
+      |
+    2 | from utils import add
+      |      ^^^^^ Cannot resolve import `utils`
+    3 |
+    4 | stat = add(10, 15)
+      |
 
-            ----- stderr -----
-        "#);
 
-        assert_cmd_snapshot!(case.command().current_dir(case.project_dir().join("child")).arg("--extra-search-path").arg("../libs"), @r"
-            success: true
-            exit_code: 0
-            ----- stdout -----
+    ----- stderr -----
+    "###);
 
-            ----- stderr -----
-        ");
-    });
+    assert_cmd_snapshot!(case.command().current_dir(case.root().join("child")).arg("--extra-search-path").arg("../libs"), @r"
+        success: true
+        exit_code: 0
+        ----- stdout -----
+
+        ----- stderr -----
+    ");
 
     Ok(())
 }
@@ -156,22 +167,20 @@ fn paths_in_configuration_files_are_relative_to_the_project_root() -> anyhow::Re
         ),
     ])?;
 
-    case.insta_settings().bind(|| {
-        assert_cmd_snapshot!(case.command().current_dir(case.project_dir().join("child")), @r"
-            success: true
-            exit_code: 0
-            ----- stdout -----
+    assert_cmd_snapshot!(case.command().current_dir(case.root().join("child")), @r"
+        success: true
+        exit_code: 0
+        ----- stdout -----
 
-            ----- stderr -----
-        ");
-    });
+        ----- stderr -----
+    ");
 
     Ok(())
 }
 
 /// The rule severity can be changed in the configuration file
 #[test]
-fn rule_severity() -> anyhow::Result<()> {
+fn configuration_rule_severity() -> anyhow::Result<()> {
     let case = TestCase::with_file(
         "test.py",
         r#"
@@ -184,41 +193,238 @@ fn rule_severity() -> anyhow::Result<()> {
             "#,
     )?;
 
-    case.insta_settings().bind(|| {
-        // Assert that there's a possibly unresolved reference diagnostic
-        // and that division-by-zero has a severity of error by default.
-        assert_cmd_snapshot!(case.command(), @r"
-            success: false
-            exit_code: 1
-            ----- stdout -----
-            error[lint:division-by-zero] <temp_dir>/test.py:2:5 Cannot divide object of type `Literal[4]` by zero
-            warning[lint:possibly-unresolved-reference] <temp_dir>/test.py:7:7 Name `x` used when possibly not defined
+    // Assert that there's a possibly unresolved reference diagnostic
+    // and that division-by-zero has a severity of error by default.
+    assert_cmd_snapshot!(case.command(), @r###"
+    success: false
+    exit_code: 1
+    ----- stdout -----
+    error: lint:division-by-zero
+     --> <temp_dir>/test.py:2:5
+      |
+    2 | y = 4 / 0
+      |     ^^^^^ Cannot divide object of type `Literal[4]` by zero
+    3 |
+    4 | for a in range(0, y):
+      |
 
-            ----- stderr -----
-        ");
+    warning: lint:possibly-unresolved-reference
+     --> <temp_dir>/test.py:7:7
+      |
+    5 |     x = a
+    6 |
+    7 | print(x)  # possibly-unresolved-reference
+      |       - Name `x` used when possibly not defined
+      |
 
-        case.write_file("pyproject.toml", r#"
-            [tool.knot.rules]
-            division-by-zero = "warn" # demote to warn
-            possibly-unresolved-reference = "ignore"
-        "#)?;
 
-        assert_cmd_snapshot!(case.command(), @r"
-            success: false
-            exit_code: 1
-            ----- stdout -----
-            warning[lint:division-by-zero] <temp_dir>/test.py:2:5 Cannot divide object of type `Literal[4]` by zero
+    ----- stderr -----
+    "###);
 
-            ----- stderr -----
-        ");
+    case.write_file(
+        "pyproject.toml",
+        r#"
+        [tool.knot.rules]
+        division-by-zero = "warn" # demote to warn
+        possibly-unresolved-reference = "ignore"
+    "#,
+    )?;
 
-        Ok(())
-    })
+    assert_cmd_snapshot!(case.command(), @r###"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+    warning: lint:division-by-zero
+     --> <temp_dir>/test.py:2:5
+      |
+    2 | y = 4 / 0
+      |     ----- Cannot divide object of type `Literal[4]` by zero
+    3 |
+    4 | for a in range(0, y):
+      |
+
+
+    ----- stderr -----
+    "###);
+
+    Ok(())
 }
 
-/// Red Knot warns about unknown rules
+/// The rule severity can be changed using `--ignore`, `--warn`, and `--error`
 #[test]
-fn unknown_rules() -> anyhow::Result<()> {
+fn cli_rule_severity() -> anyhow::Result<()> {
+    let case = TestCase::with_file(
+        "test.py",
+        r#"
+        import does_not_exit
+
+        y = 4 / 0
+
+        for a in range(0, y):
+            x = a
+
+        print(x)  # possibly-unresolved-reference
+        "#,
+    )?;
+
+    // Assert that there's a possibly unresolved reference diagnostic
+    // and that division-by-zero has a severity of error by default.
+    assert_cmd_snapshot!(case.command(), @r###"
+    success: false
+    exit_code: 1
+    ----- stdout -----
+    error: lint:unresolved-import
+     --> <temp_dir>/test.py:2:8
+      |
+    2 | import does_not_exit
+      |        ^^^^^^^^^^^^^ Cannot resolve import `does_not_exit`
+    3 |
+    4 | y = 4 / 0
+      |
+
+    error: lint:division-by-zero
+     --> <temp_dir>/test.py:4:5
+      |
+    2 | import does_not_exit
+    3 |
+    4 | y = 4 / 0
+      |     ^^^^^ Cannot divide object of type `Literal[4]` by zero
+    5 |
+    6 | for a in range(0, y):
+      |
+
+    warning: lint:possibly-unresolved-reference
+     --> <temp_dir>/test.py:9:7
+      |
+    7 |     x = a
+    8 |
+    9 | print(x)  # possibly-unresolved-reference
+      |       - Name `x` used when possibly not defined
+      |
+
+
+    ----- stderr -----
+    "###);
+
+    assert_cmd_snapshot!(
+        case
+            .command()
+            .arg("--ignore")
+            .arg("possibly-unresolved-reference")
+            .arg("--warn")
+            .arg("division-by-zero")
+            .arg("--warn")
+            .arg("unresolved-import"),
+        @r###"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+    warning: lint:unresolved-import
+     --> <temp_dir>/test.py:2:8
+      |
+    2 | import does_not_exit
+      |        ------------- Cannot resolve import `does_not_exit`
+    3 |
+    4 | y = 4 / 0
+      |
+
+    warning: lint:division-by-zero
+     --> <temp_dir>/test.py:4:5
+      |
+    2 | import does_not_exit
+    3 |
+    4 | y = 4 / 0
+      |     ----- Cannot divide object of type `Literal[4]` by zero
+    5 |
+    6 | for a in range(0, y):
+      |
+
+
+    ----- stderr -----
+    "###
+    );
+
+    Ok(())
+}
+
+/// The rule severity can be changed using `--ignore`, `--warn`, and `--error` and
+/// values specified last override previous severities.
+#[test]
+fn cli_rule_severity_precedence() -> anyhow::Result<()> {
+    let case = TestCase::with_file(
+        "test.py",
+        r#"
+        y = 4 / 0
+
+        for a in range(0, y):
+            x = a
+
+        print(x)  # possibly-unresolved-reference
+        "#,
+    )?;
+
+    // Assert that there's a possibly unresolved reference diagnostic
+    // and that division-by-zero has a severity of error by default.
+    assert_cmd_snapshot!(case.command(), @r###"
+    success: false
+    exit_code: 1
+    ----- stdout -----
+    error: lint:division-by-zero
+     --> <temp_dir>/test.py:2:5
+      |
+    2 | y = 4 / 0
+      |     ^^^^^ Cannot divide object of type `Literal[4]` by zero
+    3 |
+    4 | for a in range(0, y):
+      |
+
+    warning: lint:possibly-unresolved-reference
+     --> <temp_dir>/test.py:7:7
+      |
+    5 |     x = a
+    6 |
+    7 | print(x)  # possibly-unresolved-reference
+      |       - Name `x` used when possibly not defined
+      |
+
+
+    ----- stderr -----
+    "###);
+
+    assert_cmd_snapshot!(
+        case
+            .command()
+            .arg("--error")
+            .arg("possibly-unresolved-reference")
+            .arg("--warn")
+            .arg("division-by-zero")
+            // Override the error severity with warning
+            .arg("--ignore")
+            .arg("possibly-unresolved-reference"),
+        @r###"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+    warning: lint:division-by-zero
+     --> <temp_dir>/test.py:2:5
+      |
+    2 | y = 4 / 0
+      |     ----- Cannot divide object of type `Literal[4]` by zero
+    3 |
+    4 | for a in range(0, y):
+      |
+
+
+    ----- stderr -----
+    "###
+    );
+
+    Ok(())
+}
+
+/// Red Knot warns about unknown rules specified in a configuration file
+#[test]
+fn configuration_unknown_rules() -> anyhow::Result<()> {
     let case = TestCase::with_files([
         (
             "pyproject.toml",
@@ -230,22 +436,393 @@ fn unknown_rules() -> anyhow::Result<()> {
         ("test.py", "print(10)"),
     ])?;
 
-    case.insta_settings().bind(|| {
-        assert_cmd_snapshot!(case.command(), @r"
-            success: false
-            exit_code: 1
-            ----- stdout -----
-            warning[unknown-rule] <temp_dir>/pyproject.toml:3:1 Unknown lint rule `division-by-zer`
+    assert_cmd_snapshot!(case.command(), @r###"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+    warning: unknown-rule
+     --> <temp_dir>/pyproject.toml:3:1
+      |
+    2 | [tool.knot.rules]
+    3 | division-by-zer = "warn" # incorrect rule name
+      | --------------- Unknown lint rule `division-by-zer`
+      |
 
-            ----- stderr -----
-        ");
-    });
+
+    ----- stderr -----
+    "###);
+
+    Ok(())
+}
+
+/// Red Knot warns about unknown rules specified in a CLI argument
+#[test]
+fn cli_unknown_rules() -> anyhow::Result<()> {
+    let case = TestCase::with_file("test.py", "print(10)")?;
+
+    assert_cmd_snapshot!(case.command().arg("--ignore").arg("division-by-zer"), @r###"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+    warning: unknown-rule: Unknown lint rule `division-by-zer`
+
+
+    ----- stderr -----
+    "###);
+
+    Ok(())
+}
+
+#[test]
+fn exit_code_only_warnings() -> anyhow::Result<()> {
+    let case = TestCase::with_file("test.py", r"print(x)  # [unresolved-reference]")?;
+
+    assert_cmd_snapshot!(case.command(), @r###"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+    warning: lint:unresolved-reference
+     --> <temp_dir>/test.py:1:7
+      |
+    1 | print(x)  # [unresolved-reference]
+      |       - Name `x` used when not defined
+      |
+
+
+    ----- stderr -----
+    "###);
+
+    Ok(())
+}
+
+#[test]
+fn exit_code_only_info() -> anyhow::Result<()> {
+    let case = TestCase::with_file(
+        "test.py",
+        r#"
+        from typing_extensions import reveal_type
+        reveal_type(1)
+        "#,
+    )?;
+
+    assert_cmd_snapshot!(case.command(), @r###"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+    info: revealed-type
+     --> <temp_dir>/test.py:3:1
+      |
+    2 | from typing_extensions import reveal_type
+    3 | reveal_type(1)
+      | -------------- info: Revealed type is `Literal[1]`
+      |
+
+
+    ----- stderr -----
+    "###);
+
+    Ok(())
+}
+
+#[test]
+fn exit_code_only_info_and_error_on_warning_is_true() -> anyhow::Result<()> {
+    let case = TestCase::with_file(
+        "test.py",
+        r#"
+        from typing_extensions import reveal_type
+        reveal_type(1)
+        "#,
+    )?;
+
+    assert_cmd_snapshot!(case.command().arg("--error-on-warning"), @r###"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+    info: revealed-type
+     --> <temp_dir>/test.py:3:1
+      |
+    2 | from typing_extensions import reveal_type
+    3 | reveal_type(1)
+      | -------------- info: Revealed type is `Literal[1]`
+      |
+
+
+    ----- stderr -----
+    "###);
+
+    Ok(())
+}
+
+#[test]
+fn exit_code_no_errors_but_error_on_warning_is_true() -> anyhow::Result<()> {
+    let case = TestCase::with_file("test.py", r"print(x)  # [unresolved-reference]")?;
+
+    assert_cmd_snapshot!(case.command().arg("--error-on-warning"), @r###"
+    success: false
+    exit_code: 1
+    ----- stdout -----
+    warning: lint:unresolved-reference
+     --> <temp_dir>/test.py:1:7
+      |
+    1 | print(x)  # [unresolved-reference]
+      |       - Name `x` used when not defined
+      |
+
+
+    ----- stderr -----
+    "###);
+
+    Ok(())
+}
+
+#[test]
+fn exit_code_no_errors_but_error_on_warning_is_enabled_in_configuration() -> anyhow::Result<()> {
+    let case = TestCase::with_files([
+        ("test.py", r"print(x)  # [unresolved-reference]"),
+        (
+            "knot.toml",
+            r#"
+            [terminal]
+            error-on-warning = true
+        "#,
+        ),
+    ])?;
+
+    assert_cmd_snapshot!(case.command(), @r###"
+    success: false
+    exit_code: 1
+    ----- stdout -----
+    warning: lint:unresolved-reference
+     --> <temp_dir>/test.py:1:7
+      |
+    1 | print(x)  # [unresolved-reference]
+      |       - Name `x` used when not defined
+      |
+
+
+    ----- stderr -----
+    "###);
+
+    Ok(())
+}
+
+#[test]
+fn exit_code_both_warnings_and_errors() -> anyhow::Result<()> {
+    let case = TestCase::with_file(
+        "test.py",
+        r#"
+        print(x)     # [unresolved-reference]
+        print(4[1])  # [non-subscriptable]
+        "#,
+    )?;
+
+    assert_cmd_snapshot!(case.command(), @r###"
+    success: false
+    exit_code: 1
+    ----- stdout -----
+    warning: lint:unresolved-reference
+     --> <temp_dir>/test.py:2:7
+      |
+    2 | print(x)     # [unresolved-reference]
+      |       - Name `x` used when not defined
+    3 | print(4[1])  # [non-subscriptable]
+      |
+
+    error: lint:non-subscriptable
+     --> <temp_dir>/test.py:3:7
+      |
+    2 | print(x)     # [unresolved-reference]
+    3 | print(4[1])  # [non-subscriptable]
+      |       ^ Cannot subscript object of type `Literal[4]` with no `__getitem__` method
+      |
+
+
+    ----- stderr -----
+    "###);
+
+    Ok(())
+}
+
+#[test]
+fn exit_code_both_warnings_and_errors_and_error_on_warning_is_true() -> anyhow::Result<()> {
+    let case = TestCase::with_file(
+        "test.py",
+        r###"
+        print(x)     # [unresolved-reference]
+        print(4[1])  # [non-subscriptable]
+        "###,
+    )?;
+
+    assert_cmd_snapshot!(case.command().arg("--error-on-warning"), @r###"
+    success: false
+    exit_code: 1
+    ----- stdout -----
+    warning: lint:unresolved-reference
+     --> <temp_dir>/test.py:2:7
+      |
+    2 | print(x)     # [unresolved-reference]
+      |       - Name `x` used when not defined
+    3 | print(4[1])  # [non-subscriptable]
+      |
+
+    error: lint:non-subscriptable
+     --> <temp_dir>/test.py:3:7
+      |
+    2 | print(x)     # [unresolved-reference]
+    3 | print(4[1])  # [non-subscriptable]
+      |       ^ Cannot subscript object of type `Literal[4]` with no `__getitem__` method
+      |
+
+
+    ----- stderr -----
+    "###);
+
+    Ok(())
+}
+
+#[test]
+fn exit_code_exit_zero_is_true() -> anyhow::Result<()> {
+    let case = TestCase::with_file(
+        "test.py",
+        r#"
+        print(x)     # [unresolved-reference]
+        print(4[1])  # [non-subscriptable]
+        "#,
+    )?;
+
+    assert_cmd_snapshot!(case.command().arg("--exit-zero"), @r###"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+    warning: lint:unresolved-reference
+     --> <temp_dir>/test.py:2:7
+      |
+    2 | print(x)     # [unresolved-reference]
+      |       - Name `x` used when not defined
+    3 | print(4[1])  # [non-subscriptable]
+      |
+
+    error: lint:non-subscriptable
+     --> <temp_dir>/test.py:3:7
+      |
+    2 | print(x)     # [unresolved-reference]
+    3 | print(4[1])  # [non-subscriptable]
+      |       ^ Cannot subscript object of type `Literal[4]` with no `__getitem__` method
+      |
+
+
+    ----- stderr -----
+    "###);
+
+    Ok(())
+}
+
+#[test]
+fn user_configuration() -> anyhow::Result<()> {
+    let case = TestCase::with_files([
+        (
+            "project/knot.toml",
+            r#"
+            [rules]
+            division-by-zero = "warn"
+            "#,
+        ),
+        (
+            "project/main.py",
+            r#"
+            y = 4 / 0
+
+            for a in range(0, y):
+                x = a
+
+            print(x)
+            "#,
+        ),
+    ])?;
+
+    let config_directory = case.root().join("home/.config");
+    let config_env_var = if cfg!(windows) {
+        "APPDATA"
+    } else {
+        "XDG_CONFIG_HOME"
+    };
+
+    assert_cmd_snapshot!(
+        case.command().current_dir(case.root().join("project")).env(config_env_var, config_directory.as_os_str()),
+        @r###"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+    warning: lint:division-by-zero
+     --> <temp_dir>/project/main.py:2:5
+      |
+    2 | y = 4 / 0
+      |     ----- Cannot divide object of type `Literal[4]` by zero
+    3 |
+    4 | for a in range(0, y):
+      |
+
+    warning: lint:possibly-unresolved-reference
+     --> <temp_dir>/project/main.py:7:7
+      |
+    5 |     x = a
+    6 |
+    7 | print(x)
+      |       - Name `x` used when possibly not defined
+      |
+
+
+    ----- stderr -----
+    "###
+    );
+
+    // The user-level configuration promotes `possibly-unresolved-reference` to an error.
+    // Changing the level for `division-by-zero` has no effect, because the project-level configuration
+    // has higher precedence.
+    case.write_file(
+        config_directory.join("knot/knot.toml"),
+        r#"
+        [rules]
+        division-by-zero = "error"
+        possibly-unresolved-reference = "error"
+        "#,
+    )?;
+
+    assert_cmd_snapshot!(
+        case.command().current_dir(case.root().join("project")).env(config_env_var, config_directory.as_os_str()),
+        @r###"
+    success: false
+    exit_code: 1
+    ----- stdout -----
+    warning: lint:division-by-zero
+     --> <temp_dir>/project/main.py:2:5
+      |
+    2 | y = 4 / 0
+      |     ----- Cannot divide object of type `Literal[4]` by zero
+    3 |
+    4 | for a in range(0, y):
+      |
+
+    error: lint:possibly-unresolved-reference
+     --> <temp_dir>/project/main.py:7:7
+      |
+    5 |     x = a
+    6 |
+    7 | print(x)
+      |       ^ Name `x` used when possibly not defined
+      |
+
+
+    ----- stderr -----
+    "###
+    );
 
     Ok(())
 }
 
 struct TestCase {
     _temp_dir: TempDir,
+    _settings_scope: SettingsBindDropGuard,
     project_dir: PathBuf,
 }
 
@@ -260,9 +837,16 @@ impl TestCase {
             .canonicalize()
             .context("Failed to canonicalize project path")?;
 
+        let mut settings = insta::Settings::clone_current();
+        settings.add_filter(&tempdir_filter(&project_dir), "<temp_dir>/");
+        settings.add_filter(r#"\\(\w\w|\s|\.|")"#, "/$1");
+
+        let settings_scope = settings.bind_to_scope();
+
         Ok(Self {
             project_dir,
             _temp_dir: temp_dir,
+            _settings_scope: settings_scope,
         })
     }
 
@@ -303,21 +887,13 @@ impl TestCase {
         Ok(())
     }
 
-    fn project_dir(&self) -> &Path {
+    fn root(&self) -> &Path {
         &self.project_dir
     }
 
-    // Returns the insta filters to escape paths in snapshots
-    fn insta_settings(&self) -> Settings {
-        let mut settings = insta::Settings::clone_current();
-        settings.add_filter(&tempdir_filter(&self.project_dir), "<temp_dir>/");
-        settings.add_filter(r#"\\(\w\w|\s|\.|")"#, "/$1");
-        settings
-    }
-
     fn command(&self) -> Command {
         let mut command = Command::new(get_cargo_bin("red_knot"));
-        command.current_dir(&self.project_dir);
+        command.current_dir(&self.project_dir).arg("check");
         command
     }
 }

crates/red_knot/tests/file_watching.rs

@@ -9,11 +9,14 @@ use red_knot_project::metadata::pyproject::{PyProject, Tool};
 use red_knot_project::metadata::value::{RangedValue, RelativePathBuf};
 use red_knot_project::watch::{directory_watcher, ChangeEvent, ProjectWatcher};
 use red_knot_project::{Db, ProjectDatabase, ProjectMetadata};
-use red_knot_python_semantic::{resolve_module, ModuleName, PythonPlatform, PythonVersion};
+use red_knot_python_semantic::{resolve_module, ModuleName, PythonPlatform};
 use ruff_db::files::{system_path_to_file, File, FileError};
 use ruff_db::source::source_text;
-use ruff_db::system::{OsSystem, SystemPath, SystemPathBuf};
+use ruff_db::system::{
+    OsSystem, System, SystemPath, SystemPathBuf, UserConfigDirectoryOverrideGuard,
+};
 use ruff_db::Upcast;
+use ruff_python_ast::PythonVersion;
 
 struct TestCase {
     db: ProjectDatabase,
@@ -47,7 +50,7 @@ impl TestCase {
         #[track_caller]
         fn panic_with_formatted_events(events: Vec<ChangeEvent>) -> Vec<ChangeEvent> {
             panic!(
-                "Didn't observe expected change:\n{}",
+                "Didn't observe the expected event. The following events occurred:\n{}",
                 events
                     .into_iter()
                     .map(|event| format!("  - {event:?}"))
@@ -220,17 +223,44 @@ where
 }
 
 trait SetupFiles {
-    fn setup(self, root_path: &SystemPath, project_path: &SystemPath) -> anyhow::Result<()>;
+    fn setup(self, context: &SetupContext) -> anyhow::Result<()>;
+}
+
+struct SetupContext<'a> {
+    system: &'a OsSystem,
+    root_path: &'a SystemPath,
+}
+
+impl<'a> SetupContext<'a> {
+    fn system(&self) -> &'a OsSystem {
+        self.system
+    }
+
+    fn join_project_path(&self, relative: impl AsRef<SystemPath>) -> SystemPathBuf {
+        self.project_path().join(relative)
+    }
+
+    fn project_path(&self) -> &SystemPath {
+        self.system.current_directory()
+    }
+
+    fn root_path(&self) -> &'a SystemPath {
+        self.root_path
+    }
+
+    fn join_root_path(&self, relative: impl AsRef<SystemPath>) -> SystemPathBuf {
+        self.root_path().join(relative)
+    }
 }
 
 impl<const N: usize, P> SetupFiles for [(P, &'static str); N]
 where
     P: AsRef<SystemPath>,
 {
-    fn setup(self, _root_path: &SystemPath, project_path: &SystemPath) -> anyhow::Result<()> {
+    fn setup(self, context: &SetupContext) -> anyhow::Result<()> {
         for (relative_path, content) in self {
             let relative_path = relative_path.as_ref();
-            let absolute_path = project_path.join(relative_path);
+            let absolute_path = context.join_project_path(relative_path);
             if let Some(parent) = absolute_path.parent() {
                 std::fs::create_dir_all(parent).with_context(|| {
                     format!("Failed to create parent directory for file `{relative_path}`")
@@ -250,10 +280,10 @@ where
 
 impl<F> SetupFiles for F
 where
-    F: FnOnce(&SystemPath, &SystemPath) -> anyhow::Result<()>,
+    F: FnOnce(&SetupContext) -> anyhow::Result<()>,
 {
-    fn setup(self, root_path: &SystemPath, project_path: &SystemPath) -> anyhow::Result<()> {
-        self(root_path, project_path)
+    fn setup(self, context: &SetupContext) -> anyhow::Result<()> {
+        self(context)
     }
 }
 
@@ -261,13 +291,12 @@ fn setup<F>(setup_files: F) -> anyhow::Result<TestCase>
 where
     F: SetupFiles,
 {
-    setup_with_options(setup_files, |_root, _project_path| None)
+    setup_with_options(setup_files, |_context| None)
 }
 
-// TODO: Replace with configuration?
 fn setup_with_options<F>(
     setup_files: F,
-    create_options: impl FnOnce(&SystemPath, &SystemPath) -> Option<Options>,
+    create_options: impl FnOnce(&SetupContext) -> Option<Options>,
 ) -> anyhow::Result<TestCase>
 where
     F: SetupFiles,
@@ -295,13 +324,17 @@ where
     std::fs::create_dir_all(project_path.as_std_path())
         .with_context(|| format!("Failed to create project directory `{project_path}`"))?;
 
+    let system = OsSystem::new(&project_path);
+    let setup_context = SetupContext {
+        system: &system,
+        root_path: &root_path,
+    };
+
     setup_files
-        .setup(&root_path, &project_path)
+        .setup(&setup_context)
         .context("Failed to setup test files")?;
 
-    let system = OsSystem::new(&project_path);
-
-    if let Some(options) = create_options(&root_path, &project_path) {
+    if let Some(options) = create_options(&setup_context) {
         std::fs::write(
             project_path.join("pyproject.toml").as_std_path(),
             toml::to_string(&PyProject {
@@ -315,7 +348,9 @@ where
         .context("Failed to write configuration")?;
     }
 
-    let project = ProjectMetadata::discover(&project_path, &system)?;
+    let mut project = ProjectMetadata::discover(&project_path, &system)?;
+    project.apply_configuration_files(&system)?;
+
     let program_settings = project.to_program_settings(&system);
 
     for path in program_settings
@@ -789,10 +824,12 @@ fn directory_deleted() -> anyhow::Result<()> {
 
 #[test]
 fn search_path() -> anyhow::Result<()> {
-    let mut case = setup_with_options([("bar.py", "import sub.a")], |root_path, _project_path| {
+    let mut case = setup_with_options([("bar.py", "import sub.a")], |context| {
         Some(Options {
             environment: Some(EnvironmentOptions {
-                extra_paths: Some(vec![RelativePathBuf::cli(root_path.join("site_packages"))]),
+                extra_paths: Some(vec![RelativePathBuf::cli(
+                    context.join_root_path("site_packages"),
+                )]),
                 ..EnvironmentOptions::default()
             }),
             ..Options::default()
@@ -853,10 +890,12 @@ fn add_search_path() -> anyhow::Result<()> {
 
 #[test]
 fn remove_search_path() -> anyhow::Result<()> {
-    let mut case = setup_with_options([("bar.py", "import sub.a")], |root_path, _project_path| {
+    let mut case = setup_with_options([("bar.py", "import sub.a")], |context| {
         Some(Options {
             environment: Some(EnvironmentOptions {
-                extra_paths: Some(vec![RelativePathBuf::cli(root_path.join("site_packages"))]),
+                extra_paths: Some(vec![RelativePathBuf::cli(
+                    context.join_root_path("site_packages"),
+                )]),
                 ..EnvironmentOptions::default()
             }),
             ..Options::default()
@@ -894,7 +933,7 @@ import os
 print(sys.last_exc, os.getegid())
 "#,
         )],
-        |_root_path, _project_path| {
+        |_context| {
             Some(Options {
                 environment: Some(EnvironmentOptions {
                     python_version: Some(RangedValue::cli(PythonVersion::PY311)),
@@ -942,21 +981,31 @@ print(sys.last_exc, os.getegid())
 #[test]
 fn changed_versions_file() -> anyhow::Result<()> {
     let mut case = setup_with_options(
-        |root_path: &SystemPath, project_path: &SystemPath| {
-            std::fs::write(project_path.join("bar.py").as_std_path(), "import sub.a")?;
-            std::fs::create_dir_all(root_path.join("typeshed/stdlib").as_std_path())?;
-            std::fs::write(root_path.join("typeshed/stdlib/VERSIONS").as_std_path(), "")?;
+        |context: &SetupContext| {
             std::fs::write(
-                root_path.join("typeshed/stdlib/os.pyi").as_std_path(),
+                context.join_project_path("bar.py").as_std_path(),
+                "import sub.a",
+            )?;
+            std::fs::create_dir_all(context.join_root_path("typeshed/stdlib").as_std_path())?;
+            std::fs::write(
+                context
+                    .join_root_path("typeshed/stdlib/VERSIONS")
+                    .as_std_path(),
+                "",
+            )?;
+            std::fs::write(
+                context
+                    .join_root_path("typeshed/stdlib/os.pyi")
+                    .as_std_path(),
                 "# not important",
             )?;
 
             Ok(())
         },
-        |root_path, _project_path| {
+        |context| {
             Some(Options {
                 environment: Some(EnvironmentOptions {
-                    typeshed: Some(RelativePathBuf::cli(root_path.join("typeshed"))),
+                    typeshed: Some(RelativePathBuf::cli(context.join_root_path("typeshed"))),
                     ..EnvironmentOptions::default()
                 }),
                 ..Options::default()
@@ -1007,12 +1056,12 @@ fn changed_versions_file() -> anyhow::Result<()> {
 /// we're seeing is that Windows only emits a single event, similar to Linux.
 #[test]
 fn hard_links_in_project() -> anyhow::Result<()> {
-    let mut case = setup(|_root: &SystemPath, project: &SystemPath| {
-        let foo_path = project.join("foo.py");
+    let mut case = setup(|context: &SetupContext| {
+        let foo_path = context.join_project_path("foo.py");
         std::fs::write(foo_path.as_std_path(), "print('Version 1')")?;
 
         // Create a hardlink to `foo`
-        let bar_path = project.join("bar.py");
+        let bar_path = context.join_project_path("bar.py");
         std::fs::hard_link(foo_path.as_std_path(), bar_path.as_std_path())
             .context("Failed to create hard link from foo.py -> bar.py")?;
 
@@ -1078,12 +1127,12 @@ fn hard_links_in_project() -> anyhow::Result<()> {
     ignore = "windows doesn't support observing changes to hard linked files."
 )]
 fn hard_links_to_target_outside_project() -> anyhow::Result<()> {
-    let mut case = setup(|root: &SystemPath, project: &SystemPath| {
-        let foo_path = root.join("foo.py");
+    let mut case = setup(|context: &SetupContext| {
+        let foo_path = context.join_root_path("foo.py");
         std::fs::write(foo_path.as_std_path(), "print('Version 1')")?;
 
         // Create a hardlink to `foo`
-        let bar_path = project.join("bar.py");
+        let bar_path = context.join_project_path("bar.py");
         std::fs::hard_link(foo_path.as_std_path(), bar_path.as_std_path())
             .context("Failed to create hard link from foo.py -> bar.py")?;
 
@@ -1186,9 +1235,9 @@ mod unix {
         ignore = "FSEvents doesn't emit change events for symlinked directories outside of the watched paths."
     )]
     fn symlink_target_outside_watched_paths() -> anyhow::Result<()> {
-        let mut case = setup(|root: &SystemPath, project: &SystemPath| {
+        let mut case = setup(|context: &SetupContext| {
             // Set up the symlink target.
-            let link_target = root.join("bar");
+            let link_target = context.join_root_path("bar");
             std::fs::create_dir_all(link_target.as_std_path())
                 .context("Failed to create link target directory")?;
             let baz_original = link_target.join("baz.py");
@@ -1196,7 +1245,7 @@ mod unix {
                 .context("Failed to write link target file")?;
 
             // Create a symlink inside the project
-            let bar = project.join("bar");
+            let bar = context.join_project_path("bar");
             std::os::unix::fs::symlink(link_target.as_std_path(), bar.as_std_path())
                 .context("Failed to create symlink to bar package")?;
 
@@ -1267,9 +1316,9 @@ mod unix {
     /// ```
     #[test]
     fn symlink_inside_project() -> anyhow::Result<()> {
-        let mut case = setup(|_root: &SystemPath, project: &SystemPath| {
+        let mut case = setup(|context: &SetupContext| {
             // Set up the symlink target.
-            let link_target = project.join("patched/bar");
+            let link_target = context.join_project_path("patched/bar");
             std::fs::create_dir_all(link_target.as_std_path())
                 .context("Failed to create link target directory")?;
             let baz_original = link_target.join("baz.py");
@@ -1277,7 +1326,7 @@ mod unix {
                 .context("Failed to write link target file")?;
 
             // Create a symlink inside site-packages
-            let bar_in_project = project.join("bar");
+            let bar_in_project = context.join_project_path("bar");
             std::os::unix::fs::symlink(link_target.as_std_path(), bar_in_project.as_std_path())
                 .context("Failed to create symlink to bar package")?;
 
@@ -1358,9 +1407,9 @@ mod unix {
     #[test]
     fn symlinked_module_search_path() -> anyhow::Result<()> {
         let mut case = setup_with_options(
-            |root: &SystemPath, project: &SystemPath| {
+            |context: &SetupContext| {
                 // Set up the symlink target.
-                let site_packages = root.join("site-packages");
+                let site_packages = context.join_root_path("site-packages");
                 let bar = site_packages.join("bar");
                 std::fs::create_dir_all(bar.as_std_path())
                     .context("Failed to create bar directory")?;
@@ -1369,7 +1418,8 @@ mod unix {
                     .context("Failed to write baz.py")?;
 
                 // Symlink the site packages in the venv to the global site packages
-                let venv_site_packages = project.join(".venv/lib/python3.12/site-packages");
+                let venv_site_packages =
+                    context.join_project_path(".venv/lib/python3.12/site-packages");
                 std::fs::create_dir_all(venv_site_packages.parent().unwrap())
                     .context("Failed to create .venv directory")?;
                 std::os::unix::fs::symlink(
@@ -1380,7 +1430,7 @@ mod unix {
 
                 Ok(())
             },
-            |_root, _project| {
+            |_context| {
                 Some(Options {
                     environment: Some(EnvironmentOptions {
                         extra_paths: Some(vec![RelativePathBuf::cli(
@@ -1450,9 +1500,9 @@ mod unix {
 
 #[test]
 fn nested_projects_delete_root() -> anyhow::Result<()> {
-    let mut case = setup(|root: &SystemPath, project_root: &SystemPath| {
+    let mut case = setup(|context: &SetupContext| {
         std::fs::write(
-            project_root.join("pyproject.toml").as_std_path(),
+            context.join_project_path("pyproject.toml").as_std_path(),
             r#"
             [project]
             name = "inner"
@@ -1462,7 +1512,7 @@ fn nested_projects_delete_root() -> anyhow::Result<()> {
         )?;
 
         std::fs::write(
-            root.join("pyproject.toml").as_std_path(),
+            context.join_root_path("pyproject.toml").as_std_path(),
             r#"
             [project]
             name = "outer"
@@ -1487,3 +1537,79 @@ fn nested_projects_delete_root() -> anyhow::Result<()> {
 
     Ok(())
 }
+
+#[test]
+fn changes_to_user_configuration() -> anyhow::Result<()> {
+    let mut _config_dir_override: Option<UserConfigDirectoryOverrideGuard> = None;
+
+    let mut case = setup(|context: &SetupContext| {
+        std::fs::write(
+            context.join_project_path("pyproject.toml").as_std_path(),
+            r#"
+            [project]
+            name = "test"
+            "#,
+        )?;
+
+        std::fs::write(
+            context.join_project_path("foo.py").as_std_path(),
+            "a = 10 / 0",
+        )?;
+
+        let config_directory = context.join_root_path("home/.config");
+        std::fs::create_dir_all(config_directory.join("knot").as_std_path())?;
+        std::fs::write(
+            config_directory.join("knot/knot.toml").as_std_path(),
+            r#"
+            [rules]
+            division-by-zero = "ignore"
+            "#,
+        )?;
+
+        _config_dir_override = Some(
+            context
+                .system()
+                .with_user_config_directory(Some(config_directory)),
+        );
+
+        Ok(())
+    })?;
+
+    let foo = case
+        .system_file(case.project_path("foo.py"))
+        .expect("foo.py to exist");
+    let diagnostics = case
+        .db()
+        .check_file(foo)
+        .context("Failed to check project.")?;
+
+    assert!(
+        diagnostics.is_empty(),
+        "Expected no diagnostics but got: {diagnostics:#?}"
+    );
+
+    // Enable division-by-zero in the user configuration with warning severity
+    update_file(
+        case.root_path().join("home/.config/knot/knot.toml"),
+        r#"
+        [rules]
+        division-by-zero = "warn"
+        "#,
+    )?;
+
+    let changes = case.stop_watch(event_for_file("knot.toml"));
+
+    case.apply_changes(changes);
+
+    let diagnostics = case
+        .db()
+        .check_file(foo)
+        .context("Failed to check project.")?;
+
+    assert!(
+        diagnostics.len() == 1,
+        "Expected exactly one diagnostic but got: {diagnostics:#?}"
+    );
+
+    Ok(())
+}

crates/red_knot_project/Cargo.toml

@@ -13,7 +13,7 @@ license.workspace = true
 
 [dependencies]
 ruff_cache = { workspace = true }
-ruff_db = { workspace = true, features = ["os", "cache", "serde"] }
+ruff_db = { workspace = true, features = ["cache", "serde"] }
 ruff_macros = { workspace = true }
 ruff_python_ast = { workspace = true, features = ["serde"] }
 ruff_text_size = { workspace = true }
@@ -24,10 +24,11 @@ anyhow = { workspace = true }
 crossbeam = { workspace = true }
 glob = { workspace = true }
 notify = { workspace = true }
-pep440_rs = { workspace = true }
+pep440_rs = { workspace = true, features = ["version-ranges"] }
 rayon = { workspace = true }
 rustc-hash = { workspace = true }
 salsa = { workspace = true }
+schemars = { workspace = true, optional = true }
 serde = { workspace = true }
 thiserror = { workspace = true }
 toml = { workspace = true }
@@ -40,8 +41,9 @@ insta = { workspace = true, features = ["redactions", "ron"] }
 
 [features]
 default = ["zstd"]
-zstd = ["red_knot_vendored/zstd"]
 deflate = ["red_knot_vendored/deflate"]
+schemars = ["dep:schemars", "ruff_db/schemars", "red_knot_python_semantic/schemars"]
+zstd = ["red_knot_vendored/zstd"]
 
 [lints]
 workspace = true

crates/red_knot_project/src/combine.rs

@@ -1,7 +1,8 @@
 use std::{collections::HashMap, hash::BuildHasher};
 
-use red_knot_python_semantic::{PythonPlatform, PythonVersion, SitePackages};
+use red_knot_python_semantic::{PythonPlatform, SitePackages};
 use ruff_db::system::SystemPathBuf;
+use ruff_python_ast::PythonVersion;
 
 /// Combine two values, preferring the values in `self`.
 ///

crates/red_knot_project/src/db.rs

@@ -114,8 +114,8 @@ impl SemanticDb for ProjectDatabase {
         project.is_file_open(self, file)
     }
 
-    fn rule_selection(&self) -> &RuleSelection {
-        self.project().rule_selection(self)
+    fn rule_selection(&self) -> Arc<RuleSelection> {
+        self.project().rules(self)
     }
 
     fn lint_registry(&self) -> &LintRegistry {
@@ -186,7 +186,6 @@ pub(crate) mod tests {
         files: Files,
         system: TestSystem,
         vendored: VendoredFileSystem,
-        rule_selection: RuleSelection,
         project: Option<Project>,
     }
 
@@ -198,7 +197,6 @@ pub(crate) mod tests {
                 vendored: red_knot_vendored::file_system().clone(),
                 files: Files::default(),
                 events: Arc::default(),
-                rule_selection: RuleSelection::from_registry(&DEFAULT_LINT_REGISTRY),
                 project: None,
             };
 
@@ -270,8 +268,8 @@ pub(crate) mod tests {
             !file.path(self).is_vendored_path()
         }
 
-        fn rule_selection(&self) -> &RuleSelection {
-            &self.rule_selection
+        fn rule_selection(&self) -> Arc<RuleSelection> {
+            self.project().rules(self)
         }
 
         fn lint_registry(&self) -> &LintRegistry {

crates/red_knot_project/src/db/changes.rs

@@ -8,6 +8,7 @@ use ruff_db::files::{system_path_to_file, File, Files};
 use ruff_db::system::walk_directory::WalkState;
 use ruff_db::system::SystemPath;
 use ruff_db::Db as _;
+use ruff_python_ast::PySourceType;
 use rustc_hash::FxHashSet;
 
 impl ProjectDatabase {
@@ -47,7 +48,7 @@ impl ProjectDatabase {
             if let Some(path) = change.system_path() {
                 if matches!(
                     path.file_name(),
-                    Some(".gitignore" | ".ignore" | "ruff.toml" | ".ruff.toml" | "pyproject.toml")
+                    Some(".gitignore" | ".ignore" | "knot.toml" | "pyproject.toml")
                 ) {
                     // Changes to ignore files or settings can change the project structure or add/remove files.
                     project_changed = true;
@@ -144,6 +145,12 @@ impl ProjectDatabase {
                         metadata.apply_cli_options(cli_options.clone());
                     }
 
+                    if let Err(error) = metadata.apply_configuration_files(self.system()) {
+                        tracing::error!(
+                            "Failed to apply configuration files, continuing without applying them: {error}"
+                        );
+                    }
+
                     let program_settings = metadata.to_program_settings(self.system());
 
                     let program = Program::get(self);
@@ -201,9 +208,16 @@ impl ProjectDatabase {
                         return WalkState::Continue;
                     }
 
-                    let mut paths = added_paths.lock().unwrap();
+                    if entry
+                        .path()
+                        .extension()
+                        .and_then(PySourceType::try_from_extension)
+                        .is_some()
+                    {
+                        let mut paths = added_paths.lock().unwrap();
 
-                    paths.push(entry.into_path());
+                        paths.push(entry.into_path());
+                    }
 
                     WalkState::Continue
                 })

crates/red_knot_project/src/lib.rs

@@ -3,18 +3,18 @@
 use crate::metadata::options::OptionDiagnostic;
 pub use db::{Db, ProjectDatabase};
 use files::{Index, Indexed, IndexedFiles};
+use metadata::settings::Settings;
 pub use metadata::{ProjectDiscoveryError, ProjectMetadata};
 use red_knot_python_semantic::lint::{LintRegistry, LintRegistryBuilder, RuleSelection};
 use red_knot_python_semantic::register_lints;
 use red_knot_python_semantic::types::check_types;
-use ruff_db::diagnostic::{Diagnostic, DiagnosticId, ParseDiagnostic, Severity};
+use ruff_db::diagnostic::{Diagnostic, DiagnosticId, ParseDiagnostic, Severity, Span};
 use ruff_db::files::{system_path_to_file, File};
 use ruff_db::parsed::parsed_module;
 use ruff_db::source::{source_text, SourceTextError};
 use ruff_db::system::walk_directory::WalkState;
 use ruff_db::system::{FileType, SystemPath};
 use ruff_python_ast::PySourceType;
-use ruff_text_size::TextRange;
 use rustc_hash::{FxBuildHasher, FxHashSet};
 use salsa::Durability;
 use salsa::Setter;
@@ -66,12 +66,22 @@ pub struct Project {
     /// The metadata describing the project, including the unresolved options.
     #[return_ref]
     pub metadata: ProjectMetadata,
+
+    /// The resolved project settings.
+    #[return_ref]
+    pub settings: Settings,
+
+    /// Diagnostics that were generated when resolving the project settings.
+    #[return_ref]
+    settings_diagnostics: Vec<OptionDiagnostic>,
 }
 
 #[salsa::tracked]
 impl Project {
     pub fn from_metadata(db: &dyn Db, metadata: ProjectMetadata) -> Self {
-        Project::builder(metadata)
+        let (settings, settings_diagnostics) = metadata.options().to_settings(db);
+
+        Project::builder(metadata, settings, settings_diagnostics)
             .durability(Durability::MEDIUM)
             .open_fileset_durability(Durability::LOW)
             .file_set_durability(Durability::LOW)
@@ -86,30 +96,37 @@ impl Project {
         self.metadata(db).name()
     }
 
+    /// Returns the resolved linter rules for the project.
+    ///
+    /// This is a salsa query to prevent re-computing queries if other, unrelated
+    /// settings change. For example, we don't want that changing the terminal settings
+    /// invalidates any type checking queries.
+    #[salsa::tracked]
+    pub fn rules(self, db: &dyn Db) -> Arc<RuleSelection> {
+        self.settings(db).to_rules()
+    }
+
     pub fn reload(self, db: &mut dyn Db, metadata: ProjectMetadata) {
         tracing::debug!("Reloading project");
         assert_eq!(self.root(db), metadata.root());
 
         if &metadata != self.metadata(db) {
+            let (settings, settings_diagnostics) = metadata.options().to_settings(db);
+
+            if self.settings(db) != &settings {
+                self.set_settings(db).to(settings);
+            }
+
+            if self.settings_diagnostics(db) != &settings_diagnostics {
+                self.set_settings_diagnostics(db).to(settings_diagnostics);
+            }
+
             self.set_metadata(db).to(metadata);
         }
 
         self.reload_files(db);
     }
 
-    pub fn rule_selection(self, db: &dyn Db) -> &RuleSelection {
-        let (selection, _) = self.rule_selection_with_diagnostics(db);
-        selection
-    }
-
-    #[salsa::tracked(return_ref)]
-    fn rule_selection_with_diagnostics(
-        self,
-        db: &dyn Db,
-    ) -> (RuleSelection, Vec<OptionDiagnostic>) {
-        self.metadata(db).options().to_rule_selection(db)
-    }
-
     /// Checks all open files in the project and its dependencies.
     pub(crate) fn check(self, db: &ProjectDatabase) -> Vec<Box<dyn Diagnostic>> {
         let project_span = tracing::debug_span!("Project::check");
@@ -118,8 +135,7 @@ impl Project {
         tracing::debug!("Checking project '{name}'", name = self.name(db));
 
         let mut diagnostics: Vec<Box<dyn Diagnostic>> = Vec::new();
-        let (_, options_diagnostics) = self.rule_selection_with_diagnostics(db);
-        diagnostics.extend(options_diagnostics.iter().map(|diagnostic| {
+        diagnostics.extend(self.settings_diagnostics(db).iter().map(|diagnostic| {
             let diagnostic: Box<dyn Diagnostic> = Box::new(diagnostic.clone());
             diagnostic
         }));
@@ -151,9 +167,8 @@ impl Project {
     }
 
     pub(crate) fn check_file(self, db: &dyn Db, file: File) -> Vec<Box<dyn Diagnostic>> {
-        let (_, options_diagnostics) = self.rule_selection_with_diagnostics(db);
-
-        let mut file_diagnostics: Vec<_> = options_diagnostics
+        let mut file_diagnostics: Vec<_> = self
+            .settings_diagnostics(db)
             .iter()
             .map(|diagnostic| {
                 let diagnostic: Box<dyn Diagnostic> = Box::new(diagnostic.clone());
@@ -329,7 +344,13 @@ fn check_file_impl(db: &dyn Db, file: File) -> Vec<Box<dyn Diagnostic>> {
         boxed
     }));
 
-    diagnostics.sort_unstable_by_key(|diagnostic| diagnostic.range().unwrap_or_default().start());
+    diagnostics.sort_unstable_by_key(|diagnostic| {
+        diagnostic
+            .span()
+            .and_then(|span| span.range())
+            .unwrap_or_default()
+            .start()
+    });
 
     diagnostics
 }
@@ -442,12 +463,8 @@ impl Diagnostic for IOErrorDiagnostic {
         self.error.to_string().into()
     }
 
-    fn file(&self) -> Option<File> {
-        Some(self.file)
-    }
-
-    fn range(&self) -> Option<TextRange> {
-        None
+    fn span(&self) -> Option<Span> {
+        Some(Span::from(self.file))
     }
 
     fn severity(&self) -> Severity {

crates/red_knot_project/src/metadata.rs

@@ -1,3 +1,4 @@
+use configuration_file::{ConfigurationFile, ConfigurationFileError};
 use red_knot_python_semantic::ProgramSettings;
 use ruff_db::system::{System, SystemPath, SystemPathBuf};
 use ruff_python_ast::name::Name;
@@ -5,13 +6,15 @@ use std::sync::Arc;
 use thiserror::Error;
 
 use crate::combine::Combine;
-use crate::metadata::pyproject::{Project, PyProject, PyProjectError};
+use crate::metadata::pyproject::{Project, PyProject, PyProjectError, ResolveRequiresPythonError};
 use crate::metadata::value::ValueSource;
 use options::KnotTomlError;
 use options::Options;
 
+mod configuration_file;
 pub mod options;
 pub mod pyproject;
+pub mod settings;
 pub mod value;
 
 #[derive(Debug, PartialEq, Eq)]
@@ -23,6 +26,15 @@ pub struct ProjectMetadata {
 
     /// The raw options
     pub(super) options: Options,
+
+    /// Paths of configurations other than the project's configuration that were combined into [`Self::options`].
+    ///
+    /// This field stores the paths of the configuration files, mainly for
+    /// knowing which files to watch for changes.
+    ///
+    /// The path ordering doesn't imply precedence.
+    #[cfg_attr(test, serde(skip_serializing_if = "Vec::is_empty"))]
+    pub(super) extra_configuration_paths: Vec<SystemPathBuf>,
 }
 
 impl ProjectMetadata {
@@ -31,12 +43,16 @@ impl ProjectMetadata {
         Self {
             name,
             root,
+            extra_configuration_paths: Vec::default(),
             options: Options::default(),
         }
     }
 
     /// Loads a project from a `pyproject.toml` file.
-    pub(crate) fn from_pyproject(pyproject: PyProject, root: SystemPathBuf) -> Self {
+    pub(crate) fn from_pyproject(
+        pyproject: PyProject,
+        root: SystemPathBuf,
+    ) -> Result<Self, ResolveRequiresPythonError> {
         Self::from_options(
             pyproject
                 .tool
@@ -49,21 +65,37 @@ impl ProjectMetadata {
 
     /// Loads a project from a set of options with an optional pyproject-project table.
     pub(crate) fn from_options(
-        options: Options,
+        mut options: Options,
         root: SystemPathBuf,
         project: Option<&Project>,
-    ) -> Self {
+    ) -> Result<Self, ResolveRequiresPythonError> {
         let name = project
-            .and_then(|project| project.name.as_ref())
-            .map(|name| Name::new(&***name))
+            .and_then(|project| project.name.as_deref())
+            .map(|name| Name::new(&**name))
             .unwrap_or_else(|| Name::new(root.file_name().unwrap_or("root")));
 
-        // TODO(https://github.com/astral-sh/ruff/issues/15491): Respect requires-python
-        Self {
+        // If the `options` don't specify a python version but the `project.requires-python` field is set,
+        // use that as a lower bound instead.
+        if let Some(project) = project {
+            if !options
+                .environment
+                .as_ref()
+                .is_some_and(|env| env.python_version.is_some())
+            {
+                if let Some(requires_python) = project.resolve_requires_python_lower_bound()? {
+                    let mut environment = options.environment.unwrap_or_default();
+                    environment.python_version = Some(requires_python);
+                    options.environment = Some(environment);
+                }
+            }
+        }
+
+        Ok(Self {
             name,
             root,
             options,
-        }
+            extra_configuration_paths: Vec::new(),
+        })
     }
 
     /// Discovers the closest project at `path` and returns its metadata.
@@ -131,19 +163,34 @@ impl ProjectMetadata {
                 }
 
                 tracing::debug!("Found project at '{}'", project_root);
-                return Ok(ProjectMetadata::from_options(
+
+                let metadata = ProjectMetadata::from_options(
                     options,
                     project_root.to_path_buf(),
                     pyproject
                         .as_ref()
                         .and_then(|pyproject| pyproject.project.as_ref()),
-                ));
+                )
+                .map_err(|err| {
+                    ProjectDiscoveryError::InvalidRequiresPythonConstraint {
+                        source: err,
+                        path: pyproject_path,
+                    }
+                })?;
+
+                return Ok(metadata);
             }
 
             if let Some(pyproject) = pyproject {
                 let has_knot_section = pyproject.knot().is_some();
                 let metadata =
-                    ProjectMetadata::from_pyproject(pyproject, project_root.to_path_buf());
+                    ProjectMetadata::from_pyproject(pyproject, project_root.to_path_buf())
+                        .map_err(
+                            |err| ProjectDiscoveryError::InvalidRequiresPythonConstraint {
+                                source: err,
+                                path: pyproject_path,
+                            },
+                        )?;
 
                 if has_knot_section {
                     tracing::debug!("Found project at '{}'", project_root);
@@ -191,6 +238,10 @@ impl ProjectMetadata {
         &self.options
     }
 
+    pub fn extra_configuration_paths(&self) -> &[SystemPathBuf] {
+        &self.extra_configuration_paths
+    }
+
     pub fn to_program_settings(&self, system: &dyn System) -> ProgramSettings {
         self.options.to_program_settings(self.root(), system)
     }
@@ -200,9 +251,31 @@ impl ProjectMetadata {
         self.options = options.combine(std::mem::take(&mut self.options));
     }
 
-    /// Combine the project options with the user options where project options take precedence.
-    pub fn apply_user_options(&mut self, options: Options) {
-        self.options.combine_with(options);
+    /// Applies the options from the configuration files to the project's options.
+    ///
+    /// This includes:
+    ///
+    /// * The user-level configuration
+    pub fn apply_configuration_files(
+        &mut self,
+        system: &dyn System,
+    ) -> Result<(), ConfigurationFileError> {
+        if let Some(user) = ConfigurationFile::user(system)? {
+            tracing::debug!(
+                "Applying user-level configuration loaded from `{path}`.",
+                path = user.path()
+            );
+            self.apply_configuration_file(user);
+        }
+
+        Ok(())
+    }
+
+    /// Applies a lower-precedence configuration files to the project's options.
+    fn apply_configuration_file(&mut self, options: ConfigurationFile) {
+        self.extra_configuration_paths
+            .push(options.path().to_owned());
+        self.options.combine_with(options.into_options());
     }
 }
 
@@ -222,16 +295,22 @@ pub enum ProjectDiscoveryError {
         source: Box<KnotTomlError>,
         path: SystemPathBuf,
     },
+
+    #[error("Invalid `requires-python` version specifier (`{path}`): {source}")]
+    InvalidRequiresPythonConstraint {
+        source: ResolveRequiresPythonError,
+        path: SystemPathBuf,
+    },
 }
 
 #[cfg(test)]
 mod tests {
     //! Integration tests for project discovery
 
-    use crate::snapshot_project;
     use anyhow::{anyhow, Context};
     use insta::assert_ron_snapshot;
     use ruff_db::system::{SystemPathBuf, TestSystem};
+    use ruff_python_ast::PythonVersion;
 
     use crate::{ProjectDiscoveryError, ProjectMetadata};
 
@@ -250,7 +329,15 @@ mod tests {
 
         assert_eq!(project.root(), &*root);
 
-        snapshot_project!(project);
+        with_escaped_paths(|| {
+            assert_ron_snapshot!(&project, @r#"
+                ProjectMetadata(
+                  name: Name("app"),
+                  root: "/app",
+                  options: Options(),
+                )
+            "#);
+        });
 
         Ok(())
     }
@@ -279,7 +366,16 @@ mod tests {
             ProjectMetadata::discover(&root, &system).context("Failed to discover project")?;
 
         assert_eq!(project.root(), &*root);
-        snapshot_project!(project);
+
+        with_escaped_paths(|| {
+            assert_ron_snapshot!(&project, @r#"
+                ProjectMetadata(
+                  name: Name("backend"),
+                  root: "/app",
+                  options: Options(),
+                )
+            "#);
+        });
 
         // Discovering the same package from a subdirectory should give the same result
         let from_src = ProjectMetadata::discover(&root.join("db"), &system)
@@ -362,7 +458,19 @@ expected `.`, `]`
 
         let sub_project = ProjectMetadata::discover(&root.join("packages/a"), &system)?;
 
-        snapshot_project!(sub_project);
+        with_escaped_paths(|| {
+            assert_ron_snapshot!(sub_project, @r#"
+            ProjectMetadata(
+              name: Name("nested-project"),
+              root: "/app/packages/a",
+              options: Options(
+                src: Some(SrcOptions(
+                  root: Some("src"),
+                )),
+              ),
+            )
+            "#);
+        });
 
         Ok(())
     }
@@ -400,7 +508,19 @@ expected `.`, `]`
 
         let root = ProjectMetadata::discover(&root, &system)?;
 
-        snapshot_project!(root);
+        with_escaped_paths(|| {
+            assert_ron_snapshot!(root, @r#"
+                              ProjectMetadata(
+                                name: Name("project-root"),
+                                root: "/app",
+                                options: Options(
+                                  src: Some(SrcOptions(
+                                    root: Some("src"),
+                                  )),
+                                ),
+                              )
+                              "#);
+        });
 
         Ok(())
     }
@@ -432,7 +552,15 @@ expected `.`, `]`
 
         let sub_project = ProjectMetadata::discover(&root.join("packages/a"), &system)?;
 
-        snapshot_project!(sub_project);
+        with_escaped_paths(|| {
+            assert_ron_snapshot!(sub_project, @r#"
+            ProjectMetadata(
+              name: Name("nested-project"),
+              root: "/app/packages/a",
+              options: Options(),
+            )
+            "#);
+        });
 
         Ok(())
     }
@@ -467,7 +595,19 @@ expected `.`, `]`
 
         let root = ProjectMetadata::discover(&root.join("packages/a"), &system)?;
 
-        snapshot_project!(root);
+        with_escaped_paths(|| {
+            assert_ron_snapshot!(root, @r#"
+            ProjectMetadata(
+              name: Name("project-root"),
+              root: "/app",
+              options: Options(
+                environment: Some(EnvironmentOptions(
+                  r#python-version: Some("3.10"),
+                )),
+              ),
+            )
+            "#);
+        });
 
         Ok(())
     }
@@ -487,27 +627,304 @@ expected `.`, `]`
                 (
                     root.join("pyproject.toml"),
                     r#"
-                        [project]
-                        name = "super-app"
-                        requires-python = ">=3.12"
+                    [project]
+                    name = "super-app"
+                    requires-python = ">=3.12"
 
-                        [tool.knot.src]
-                        root = "this_option_is_ignored"
-                        "#,
+                    [tool.knot.src]
+                    root = "this_option_is_ignored"
+                    "#,
                 ),
                 (
                     root.join("knot.toml"),
                     r#"
-                        [src]
-                        root = "src"
-                        "#,
+                    [src]
+                    root = "src"
+                    "#,
                 ),
             ])
             .context("Failed to write files")?;
 
         let root = ProjectMetadata::discover(&root, &system)?;
 
-        snapshot_project!(root);
+        with_escaped_paths(|| {
+            assert_ron_snapshot!(root, @r#"
+            ProjectMetadata(
+              name: Name("super-app"),
+              root: "/app",
+              options: Options(
+                environment: Some(EnvironmentOptions(
+                  r#python-version: Some("3.12"),
+                )),
+                src: Some(SrcOptions(
+                  root: Some("src"),
+                )),
+              ),
+            )
+            "#);
+        });
+
+        Ok(())
+    }
+    #[test]
+    fn requires_python_major_minor() -> anyhow::Result<()> {
+        let system = TestSystem::default();
+        let root = SystemPathBuf::from("/app");
+
+        system
+            .memory_file_system()
+            .write_file(
+                root.join("pyproject.toml"),
+                r#"
+                [project]
+                requires-python = ">=3.12"
+                "#,
+            )
+            .context("Failed to write file")?;
+
+        let root = ProjectMetadata::discover(&root, &system)?;
+
+        assert_eq!(
+            root.options
+                .environment
+                .unwrap_or_default()
+                .python_version
+                .as_deref(),
+            Some(&PythonVersion::PY312)
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn requires_python_major_only() -> anyhow::Result<()> {
+        let system = TestSystem::default();
+        let root = SystemPathBuf::from("/app");
+
+        system
+            .memory_file_system()
+            .write_file(
+                root.join("pyproject.toml"),
+                r#"
+                [project]
+                requires-python = ">=3"
+                "#,
+            )
+            .context("Failed to write file")?;
+
+        let root = ProjectMetadata::discover(&root, &system)?;
+
+        assert_eq!(
+            root.options
+                .environment
+                .unwrap_or_default()
+                .python_version
+                .as_deref(),
+            Some(&PythonVersion::from((3, 0)))
+        );
+
+        Ok(())
+    }
+
+    /// A `requires-python` constraint with major, minor and patch can be simplified
+    /// to major and minor (e.g. 3.12.1 -> 3.12).
+    #[test]
+    fn requires_python_major_minor_patch() -> anyhow::Result<()> {
+        let system = TestSystem::default();
+        let root = SystemPathBuf::from("/app");
+
+        system
+            .memory_file_system()
+            .write_file(
+                root.join("pyproject.toml"),
+                r#"
+                [project]
+                requires-python = ">=3.12.8"
+                "#,
+            )
+            .context("Failed to write file")?;
+
+        let root = ProjectMetadata::discover(&root, &system)?;
+
+        assert_eq!(
+            root.options
+                .environment
+                .unwrap_or_default()
+                .python_version
+                .as_deref(),
+            Some(&PythonVersion::PY312)
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn requires_python_beta_version() -> anyhow::Result<()> {
+        let system = TestSystem::default();
+        let root = SystemPathBuf::from("/app");
+
+        system
+            .memory_file_system()
+            .write_file(
+                root.join("pyproject.toml"),
+                r#"
+                [project]
+                requires-python = ">= 3.13.0b0"
+                "#,
+            )
+            .context("Failed to write file")?;
+
+        let root = ProjectMetadata::discover(&root, &system)?;
+
+        assert_eq!(
+            root.options
+                .environment
+                .unwrap_or_default()
+                .python_version
+                .as_deref(),
+            Some(&PythonVersion::PY313)
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn requires_python_greater_than_major_minor() -> anyhow::Result<()> {
+        let system = TestSystem::default();
+        let root = SystemPathBuf::from("/app");
+
+        system
+            .memory_file_system()
+            .write_file(
+                root.join("pyproject.toml"),
+                r#"
+                [project]
+                # This is somewhat nonsensical because 3.12.1 > 3.12 is true.
+                # That's why simplifying the constraint to >= 3.12 is correct
+                requires-python = ">3.12"
+                "#,
+            )
+            .context("Failed to write file")?;
+
+        let root = ProjectMetadata::discover(&root, &system)?;
+
+        assert_eq!(
+            root.options
+                .environment
+                .unwrap_or_default()
+                .python_version
+                .as_deref(),
+            Some(&PythonVersion::PY312)
+        );
+
+        Ok(())
+    }
+
+    /// `python-version` takes precedence if both `requires-python` and `python-version` are configured.
+    #[test]
+    fn requires_python_and_python_version() -> anyhow::Result<()> {
+        let system = TestSystem::default();
+        let root = SystemPathBuf::from("/app");
+
+        system
+            .memory_file_system()
+            .write_file(
+                root.join("pyproject.toml"),
+                r#"
+                [project]
+                requires-python = ">=3.12"
+
+                [tool.knot.environment]
+                python-version = "3.10"
+                "#,
+            )
+            .context("Failed to write file")?;
+
+        let root = ProjectMetadata::discover(&root, &system)?;
+
+        assert_eq!(
+            root.options
+                .environment
+                .unwrap_or_default()
+                .python_version
+                .as_deref(),
+            Some(&PythonVersion::PY310)
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn requires_python_less_than() -> anyhow::Result<()> {
+        let system = TestSystem::default();
+        let root = SystemPathBuf::from("/app");
+
+        system
+            .memory_file_system()
+            .write_file(
+                root.join("pyproject.toml"),
+                r#"
+                [project]
+                requires-python = "<3.12"
+                "#,
+            )
+            .context("Failed to write file")?;
+
+        let Err(error) = ProjectMetadata::discover(&root, &system) else {
+            return Err(anyhow!("Expected project discovery to fail because the `requires-python` doesn't specify a lower bound (it only specifies an upper bound)."));
+        };
+
+        assert_error_eq(&error, "Invalid `requires-python` version specifier (`/app/pyproject.toml`): value `<3.12` does not contain a lower bound. Add a lower bound to indicate the minimum compatible Python version (e.g., `>=3.13`) or specify a version in `environment.python-version`.");
+
+        Ok(())
+    }
+
+    #[test]
+    fn requires_python_no_specifiers() -> anyhow::Result<()> {
+        let system = TestSystem::default();
+        let root = SystemPathBuf::from("/app");
+
+        system
+            .memory_file_system()
+            .write_file(
+                root.join("pyproject.toml"),
+                r#"
+                [project]
+                requires-python = ""
+                "#,
+            )
+            .context("Failed to write file")?;
+
+        let Err(error) = ProjectMetadata::discover(&root, &system) else {
+            return Err(anyhow!("Expected project discovery to fail because the `requires-python` specifiers are empty and don't define a lower bound."));
+        };
+
+        assert_error_eq(&error, "Invalid `requires-python` version specifier (`/app/pyproject.toml`): value `` does not contain a lower bound. Add a lower bound to indicate the minimum compatible Python version (e.g., `>=3.13`) or specify a version in `environment.python-version`.");
+
+        Ok(())
+    }
+
+    #[test]
+    fn requires_python_too_large_major_version() -> anyhow::Result<()> {
+        let system = TestSystem::default();
+        let root = SystemPathBuf::from("/app");
+
+        system
+            .memory_file_system()
+            .write_file(
+                root.join("pyproject.toml"),
+                r#"
+                [project]
+                requires-python = ">=999.0"
+                "#,
+            )
+            .context("Failed to write file")?;
+
+        let Err(error) = ProjectMetadata::discover(&root, &system) else {
+            return Err(anyhow!("Expected project discovery to fail because of the requires-python major version that is larger than 255."));
+        };
+
+        assert_error_eq(&error, "Invalid `requires-python` version specifier (`/app/pyproject.toml`): The major version `999` is larger than the maximum supported value 255");
 
         Ok(())
     }
@@ -517,15 +934,12 @@ expected `.`, `]`
         assert_eq!(error.to_string().replace('\\', "/"), message);
     }
 
-    /// Snapshots a project but with all paths using unix separators.
-    #[macro_export]
-    macro_rules! snapshot_project {
-    ($project:expr) => {{
-        assert_ron_snapshot!($project,{
-            ".root" => insta::dynamic_redaction(|content, _content_path| {
-                content.as_str().unwrap().replace("\\", "/")
-            }),
+    fn with_escaped_paths<R>(f: impl FnOnce() -> R) -> R {
+        let mut settings = insta::Settings::clone_current();
+        settings.add_dynamic_redaction(".root", |content, _path| {
+            content.as_str().unwrap().replace('\\', "/")
         });
-    }};
-}
+
+        settings.bind(f)
+    }
 }

crates/red_knot_project/src/metadata/configuration_file.rs

@@ -0,0 +1,69 @@
+use std::sync::Arc;
+
+use ruff_db::system::{System, SystemPath, SystemPathBuf};
+use thiserror::Error;
+
+use crate::metadata::value::ValueSource;
+
+use super::options::{KnotTomlError, Options};
+
+/// A `knot.toml` configuration file with the options it contains.
+pub(crate) struct ConfigurationFile {
+    path: SystemPathBuf,
+    options: Options,
+}
+
+impl ConfigurationFile {
+    /// Loads the user-level configuration file if it exists.
+    ///
+    /// Returns `None` if the file does not exist or if the concept of user-level configurations
+    /// doesn't exist on `system`.
+    pub(crate) fn user(system: &dyn System) -> Result<Option<Self>, ConfigurationFileError> {
+        let Some(configuration_directory) = system.user_config_directory() else {
+            return Ok(None);
+        };
+
+        let knot_toml_path = configuration_directory.join("knot").join("knot.toml");
+
+        tracing::debug!(
+            "Searching for a user-level configuration at `{path}`",
+            path = &knot_toml_path
+        );
+
+        let Ok(knot_toml_str) = system.read_to_string(&knot_toml_path) else {
+            return Ok(None);
+        };
+
+        match Options::from_toml_str(
+            &knot_toml_str,
+            ValueSource::File(Arc::new(knot_toml_path.clone())),
+        ) {
+            Ok(options) => Ok(Some(Self {
+                path: knot_toml_path,
+                options,
+            })),
+            Err(error) => Err(ConfigurationFileError::InvalidKnotToml {
+                source: Box::new(error),
+                path: knot_toml_path,
+            }),
+        }
+    }
+
+    /// Returns the path to the configuration file.
+    pub(crate) fn path(&self) -> &SystemPath {
+        &self.path
+    }
+
+    pub(crate) fn into_options(self) -> Options {
+        self.options
+    }
+}
+
+#[derive(Debug, Error)]
+pub enum ConfigurationFileError {
+    #[error("{path} is not a valid `knot.toml`: {source}")]
+    InvalidKnotToml {
+        source: Box<KnotTomlError>,
+        path: SystemPathBuf,
+    },
+}

crates/red_knot_project/src/metadata/options.rs

@@ -1,32 +1,38 @@
 use crate::metadata::value::{RangedValue, RelativePathBuf, ValueSource, ValueSourceGuard};
 use crate::Db;
 use red_knot_python_semantic::lint::{GetLintError, Level, LintSource, RuleSelection};
-use red_knot_python_semantic::{
-    ProgramSettings, PythonPlatform, PythonVersion, SearchPathSettings, SitePackages,
-};
-use ruff_db::diagnostic::{Diagnostic, DiagnosticId, Severity};
-use ruff_db::files::{system_path_to_file, File};
+use red_knot_python_semantic::{ProgramSettings, PythonPlatform, SearchPathSettings, SitePackages};
+use ruff_db::diagnostic::{Diagnostic, DiagnosticId, Severity, Span};
+use ruff_db::files::system_path_to_file;
 use ruff_db::system::{System, SystemPath};
 use ruff_macros::Combine;
-use ruff_text_size::TextRange;
+use ruff_python_ast::PythonVersion;
 use rustc_hash::FxHashMap;
 use serde::{Deserialize, Serialize};
 use std::borrow::Cow;
 use std::fmt::Debug;
 use thiserror::Error;
 
+use super::settings::{Settings, TerminalSettings};
+
 /// The options for the project.
 #[derive(Debug, Default, Clone, PartialEq, Eq, Combine, Serialize, Deserialize)]
 #[serde(rename_all = "kebab-case", deny_unknown_fields)]
+#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
 pub struct Options {
+    /// Configures the type checking environment.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub environment: Option<EnvironmentOptions>,
 
     #[serde(skip_serializing_if = "Option::is_none")]
     pub src: Option<SrcOptions>,
 
+    /// Configures the enabled lints and their severity.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub rules: Option<Rules>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub terminal: Option<TerminalOptions>,
 }
 
 impl Options {
@@ -107,7 +113,22 @@ impl Options {
     }
 
     #[must_use]
-    pub(crate) fn to_rule_selection(&self, db: &dyn Db) -> (RuleSelection, Vec<OptionDiagnostic>) {
+    pub(crate) fn to_settings(&self, db: &dyn Db) -> (Settings, Vec<OptionDiagnostic>) {
+        let (rules, diagnostics) = self.to_rule_selection(db);
+
+        let mut settings = Settings::new(rules);
+
+        if let Some(terminal) = self.terminal.as_ref() {
+            settings.set_terminal(TerminalSettings {
+                error_on_warning: terminal.error_on_warning.unwrap_or_default(),
+            });
+        }
+
+        (settings, diagnostics)
+    }
+
+    #[must_use]
+    fn to_rule_selection(&self, db: &dyn Db) -> (RuleSelection, Vec<OptionDiagnostic>) {
         let registry = db.lint_registry();
         let mut diagnostics = Vec::new();
 
@@ -149,6 +170,16 @@ impl Options {
                             format!("Unknown lint rule `{rule_name}`"),
                             Severity::Warning,
                         ),
+                        GetLintError::PrefixedWithCategory { suggestion, .. } => {
+                            OptionDiagnostic::new(
+                                DiagnosticId::UnknownRule,
+                                format!(
+                                    "Unknown lint rule `{rule_name}`. Did you mean `{suggestion}`?"
+                                ),
+                                Severity::Warning,
+                            )
+                        }
+
                         GetLintError::Removed(_) => OptionDiagnostic::new(
                             DiagnosticId::UnknownRule,
                             format!("Unknown lint rule `{rule_name}`"),
@@ -156,7 +187,14 @@ impl Options {
                         ),
                     };
 
-                    diagnostics.push(diagnostic.with_file(file).with_range(rule_name.range()));
+                    let span = file.map(Span::from).map(|span| {
+                        if let Some(range) = rule_name.range() {
+                            span.with_range(range)
+                        } else {
+                            span
+                        }
+                    });
+                    diagnostics.push(diagnostic.with_span(span));
                 }
             }
         }
@@ -167,10 +205,22 @@ impl Options {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, Combine, Serialize, Deserialize)]
 #[serde(rename_all = "kebab-case", deny_unknown_fields)]
+#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
 pub struct EnvironmentOptions {
+    /// Specifies the version of Python that will be used to execute the source code.
+    /// The version should be specified as a string in the format `M.m` where `M` is the major version
+    /// and `m` is the minor (e.g. "3.0" or "3.6").
+    /// If a version is provided, knot will generate errors if the source code makes use of language features
+    /// that are not supported in that version.
+    /// It will also tailor its use of type stub files, which conditionalizes type definitions based on the version.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub python_version: Option<RangedValue<PythonVersion>>,
 
+    /// Specifies the target platform that will be used to execute the source code.
+    /// If specified, Red Knot will tailor its use of type stub files,
+    /// which conditionalize type definitions based on the platform.
+    ///
+    /// If no platform is specified, knot will use `all` or the current platform in the LSP use case.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub python_platform: Option<RangedValue<PythonPlatform>>,
 
@@ -194,6 +244,7 @@ pub struct EnvironmentOptions {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, Combine, Serialize, Deserialize)]
 #[serde(rename_all = "kebab-case", deny_unknown_fields)]
+#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
 pub struct SrcOptions {
     /// The root of the project, used for finding first-party modules.
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -202,10 +253,95 @@ pub struct SrcOptions {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, Combine, Serialize, Deserialize)]
 #[serde(rename_all = "kebab-case", transparent)]
+#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
 pub struct Rules {
+    #[cfg_attr(feature = "schemars", schemars(with = "schema::Rules"))]
     inner: FxHashMap<RangedValue<String>, RangedValue<Level>>,
 }
 
+impl FromIterator<(RangedValue<String>, RangedValue<Level>)> for Rules {
+    fn from_iter<T: IntoIterator<Item = (RangedValue<String>, RangedValue<Level>)>>(
+        iter: T,
+    ) -> Self {
+        Self {
+            inner: iter.into_iter().collect(),
+        }
+    }
+}
+
+#[derive(Debug, Default, Clone, Eq, PartialEq, Combine, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case", deny_unknown_fields)]
+#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
+pub struct TerminalOptions {
+    /// Use exit code 1 if there are any warning-level diagnostics.
+    ///
+    /// Defaults to `false`.
+    pub error_on_warning: Option<bool>,
+}
+
+#[cfg(feature = "schemars")]
+mod schema {
+    use crate::DEFAULT_LINT_REGISTRY;
+    use red_knot_python_semantic::lint::Level;
+    use schemars::gen::SchemaGenerator;
+    use schemars::schema::{
+        InstanceType, Metadata, ObjectValidation, Schema, SchemaObject, SubschemaValidation,
+    };
+    use schemars::JsonSchema;
+
+    pub(super) struct Rules;
+
+    impl JsonSchema for Rules {
+        fn schema_name() -> String {
+            "Rules".to_string()
+        }
+
+        fn json_schema(gen: &mut SchemaGenerator) -> Schema {
+            let registry = &*DEFAULT_LINT_REGISTRY;
+
+            let level_schema = gen.subschema_for::<Level>();
+
+            let properties: schemars::Map<String, Schema> = registry
+                .lints()
+                .iter()
+                .map(|lint| {
+                    (
+                        lint.name().to_string(),
+                        Schema::Object(SchemaObject {
+                            metadata: Some(Box::new(Metadata {
+                                title: Some(lint.summary().to_string()),
+                                description: Some(lint.documentation()),
+                                deprecated: lint.status.is_deprecated(),
+                                default: Some(lint.default_level.to_string().into()),
+                                ..Metadata::default()
+                            })),
+                            subschemas: Some(Box::new(SubschemaValidation {
+                                one_of: Some(vec![level_schema.clone()]),
+                                ..Default::default()
+                            })),
+                            ..Default::default()
+                        }),
+                    )
+                })
+                .collect();
+
+            Schema::Object(SchemaObject {
+                instance_type: Some(InstanceType::Object.into()),
+                object: Some(Box::new(ObjectValidation {
+                    properties,
+                    // Allow unknown rules: Red Knot will warn about them.
+                    // It gives a better experience when using an older Red Knot version because
+                    // the schema will not deny rules that have been removed in newer versions.
+                    additional_properties: Some(Box::new(level_schema)),
+                    ..ObjectValidation::default()
+                })),
+
+                ..Default::default()
+            })
+        }
+    }
+}
+
 #[derive(Error, Debug)]
 pub enum KnotTomlError {
     #[error(transparent)]
@@ -217,8 +353,7 @@ pub struct OptionDiagnostic {
     id: DiagnosticId,
     message: String,
     severity: Severity,
-    file: Option<File>,
-    range: Option<TextRange>,
+    span: Option<Span>,
 }
 
 impl OptionDiagnostic {
@@ -227,21 +362,13 @@ impl OptionDiagnostic {
             id,
             message,
             severity,
-            file: None,
-            range: None,
+            span: None,
         }
     }
 
     #[must_use]
-    fn with_file(mut self, file: Option<File>) -> Self {
-        self.file = file;
-        self
-    }
-
-    #[must_use]
-    fn with_range(mut self, range: Option<TextRange>) -> Self {
-        self.range = range;
-        self
+    fn with_span(self, span: Option<Span>) -> Self {
+        OptionDiagnostic { span, ..self }
     }
 }
 
@@ -254,12 +381,8 @@ impl Diagnostic for OptionDiagnostic {
         Cow::Borrowed(&self.message)
     }
 
-    fn file(&self) -> Option<File> {
-        self.file
-    }
-
-    fn range(&self) -> Option<TextRange> {
-        self.range
+    fn span(&self) -> Option<Span> {
+        self.span.clone()
     }
 
     fn severity(&self) -> Severity {

crates/red_knot_project/src/metadata/pyproject.rs

@@ -1,10 +1,11 @@
-use pep440_rs::{Version, VersionSpecifiers};
-use serde::{Deserialize, Deserializer, Serialize};
-use std::ops::Deref;
-use thiserror::Error;
-
 use crate::metadata::options::Options;
 use crate::metadata::value::{RangedValue, ValueSource, ValueSourceGuard};
+use pep440_rs::{release_specifiers_to_ranges, Version, VersionSpecifiers};
+use ruff_python_ast::PythonVersion;
+use serde::{Deserialize, Deserializer, Serialize};
+use std::collections::Bound;
+use std::ops::Deref;
+use thiserror::Error;
 
 /// A `pyproject.toml` as specified in PEP 517.
 #[derive(Deserialize, Serialize, Debug, Default, Clone)]
@@ -55,6 +56,73 @@ pub struct Project {
     pub requires_python: Option<RangedValue<VersionSpecifiers>>,
 }
 
+impl Project {
+    pub(super) fn resolve_requires_python_lower_bound(
+        &self,
+    ) -> Result<Option<RangedValue<PythonVersion>>, ResolveRequiresPythonError> {
+        let Some(requires_python) = self.requires_python.as_ref() else {
+            return Ok(None);
+        };
+
+        tracing::debug!("Resolving requires-python constraint: `{requires_python}`");
+
+        let ranges = release_specifiers_to_ranges((**requires_python).clone());
+        let Some((lower, _)) = ranges.bounding_range() else {
+            return Ok(None);
+        };
+
+        let version = match lower {
+            // Ex) `>=3.10.1` -> `>=3.10`
+            Bound::Included(version) => version,
+
+            // Ex) `>3.10.1` -> `>=3.10` or `>3.10` -> `>=3.10`
+            // The second example looks obscure at first but it is required because
+            // `3.10.1 > 3.10` is true but we only have two digits here. So including 3.10 is the
+            // right move. Overall, using `>` without a patch release is most likely bogus.
+            Bound::Excluded(version) => version,
+
+            // Ex) `<3.10` or ``
+            Bound::Unbounded => {
+                return Err(ResolveRequiresPythonError::NoLowerBound(
+                    requires_python.to_string(),
+                ))
+            }
+        };
+
+        // Take the major and minor version
+        let mut versions = version.release().iter().take(2);
+
+        let Some(major) = versions.next().copied() else {
+            return Ok(None);
+        };
+
+        let minor = versions.next().copied().unwrap_or_default();
+
+        tracing::debug!("Resolved requires-python constraint to: {major}.{minor}");
+
+        let major =
+            u8::try_from(major).map_err(|_| ResolveRequiresPythonError::TooLargeMajor(major))?;
+        let minor =
+            u8::try_from(minor).map_err(|_| ResolveRequiresPythonError::TooLargeMajor(minor))?;
+
+        Ok(Some(
+            requires_python
+                .clone()
+                .map_value(|_| PythonVersion::from((major, minor))),
+        ))
+    }
+}
+
+#[derive(Debug, Error)]
+pub enum ResolveRequiresPythonError {
+    #[error("The major version `{0}` is larger than the maximum supported value 255")]
+    TooLargeMajor(u64),
+    #[error("The minor version `{0}` is larger than the maximum supported value 255")]
+    TooLargeMinor(u64),
+    #[error("value `{0}` does not contain a lower bound. Add a lower bound to indicate the minimum compatible Python version (e.g., `>=3.13`) or specify a version in `environment.python-version`.")]
+    NoLowerBound(String),
+}
+
 #[derive(Deserialize, Serialize, Debug, Clone, PartialEq, Eq)]
 #[serde(rename_all = "kebab-case")]
 pub struct Tool {

crates/red_knot_project/src/metadata/settings.rs

@@ -0,0 +1,53 @@
+use std::sync::Arc;
+
+use red_knot_python_semantic::lint::RuleSelection;
+
+/// The resolved [`super::Options`] for the project.
+///
+/// Unlike [`super::Options`], the struct has default values filled in and
+/// uses representations that are optimized for reads (instead of preserving the source representation).
+/// It's also not required that this structure precisely resembles the TOML schema, although
+/// it's encouraged to use a similar structure.
+///
+/// It's worth considering to adding a salsa query for specific settings to
+/// limit the blast radius when only some settings change. For example,
+/// changing the terminal settings shouldn't invalidate any core type-checking queries.
+/// This can be achieved by adding a salsa query for the type checking specific settings.
+///
+/// Settings that are part of [`red_knot_python_semantic::ProgramSettings`] are not included here.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct Settings {
+    rules: Arc<RuleSelection>,
+
+    terminal: TerminalSettings,
+}
+
+impl Settings {
+    pub fn new(rules: RuleSelection) -> Self {
+        Self {
+            rules: Arc::new(rules),
+            terminal: TerminalSettings::default(),
+        }
+    }
+
+    pub fn rules(&self) -> &RuleSelection {
+        &self.rules
+    }
+
+    pub fn to_rules(&self) -> Arc<RuleSelection> {
+        self.rules.clone()
+    }
+
+    pub fn terminal(&self) -> &TerminalSettings {
+        &self.terminal
+    }
+
+    pub fn set_terminal(&mut self, terminal: TerminalSettings) {
+        self.terminal = terminal;
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub struct TerminalSettings {
+    pub error_on_warning: bool,
+}

crates/red_knot_project/src/metadata/value.rs

@@ -1,8 +1,9 @@
 use crate::combine::Combine;
 use crate::Db;
 use ruff_db::system::{System, SystemPath, SystemPathBuf};
+use ruff_macros::Combine;
 use ruff_text_size::{TextRange, TextSize};
-use serde::{Deserialize, Deserializer, Serialize, Serializer};
+use serde::{Deserialize, Deserializer};
 use std::cell::RefCell;
 use std::cmp::Ordering;
 use std::fmt;
@@ -70,15 +71,19 @@ impl Drop for ValueSourceGuard {
 ///
 /// This ensures that two resolved configurations are identical even if the position of a value has changed
 /// or if the values were loaded from different sources.
-#[derive(Clone)]
+#[derive(Clone, serde::Serialize)]
+#[serde(transparent)]
+#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
 pub struct RangedValue<T> {
     value: T,
+    #[serde(skip)]
     source: ValueSource,
 
     /// The byte range of `value` in `source`.
     ///
     /// Can be `None` because not all sources support a range.
     /// For example, arguments provided on the CLI won't have a range attached.
+    #[serde(skip)]
     range: Option<TextRange>,
 }
 
@@ -113,6 +118,15 @@ impl<T> RangedValue<T> {
         self
     }
 
+    #[must_use]
+    pub fn map_value<R>(self, f: impl FnOnce(T) -> R) -> RangedValue<R> {
+        RangedValue {
+            value: f(self.value),
+            source: self.source,
+            range: self.range,
+        }
+    }
+
     pub fn into_inner(self) -> T {
         self.value
     }
@@ -266,18 +280,6 @@ where
     }
 }
 
-impl<T> Serialize for RangedValue<T>
-where
-    T: Serialize,
-{
-    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
-    where
-        S: Serializer,
-    {
-        self.value.serialize(serializer)
-    }
-}
-
 /// A possibly relative path in a configuration file.
 ///
 /// Relative paths in configuration files or from CLI options
@@ -286,9 +288,19 @@ where
 /// * CLI: The path is relative to the current working directory
 /// * Configuration file: The path is relative to the project's root.
 #[derive(
-    Debug, Clone, serde::Serialize, serde::Deserialize, PartialEq, Eq, PartialOrd, Ord, Hash,
+    Debug,
+    Clone,
+    serde::Serialize,
+    serde::Deserialize,
+    PartialEq,
+    Eq,
+    PartialOrd,
+    Ord,
+    Hash,
+    Combine,
 )]
 #[serde(transparent)]
+#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
 pub struct RelativePathBuf(RangedValue<SystemPathBuf>);
 
 impl RelativePathBuf {
@@ -325,13 +337,3 @@ impl RelativePathBuf {
         SystemPath::absolute(&self.0, relative_to)
     }
 }
-
-impl Combine for RelativePathBuf {
-    fn combine(self, other: Self) -> Self {
-        Self(self.0.combine(other.0))
-    }
-
-    fn combine_with(&mut self, other: Self) {
-        self.0.combine_with(other.0);
-    }
-}

crates/red_knot_project/src/snapshots/red_knot_project__metadata__tests__nested_projects_in_root_project.snap

@@ -1,13 +0,0 @@
----
-source: crates/red_knot_project/src/metadata.rs
-expression: root
----
-ProjectMetadata(
-  name: Name("project-root"),
-  root: "/app",
-  options: Options(
-    src: Some(SrcOptions(
-      root: Some("src"),
-    )),
-  ),
-)

crates/red_knot_project/src/snapshots/red_knot_project__metadata__tests__nested_projects_in_sub_project.snap

@@ -1,13 +0,0 @@
----
-source: crates/red_knot_project/src/metadata.rs
-expression: sub_project
----
-ProjectMetadata(
-  name: Name("nested-project"),
-  root: "/app/packages/a",
-  options: Options(
-    src: Some(SrcOptions(
-      root: Some("src"),
-    )),
-  ),
-)

crates/red_knot_project/src/snapshots/red_knot_project__metadata__tests__nested_projects_with_outer_knot_section.snap

@@ -1,13 +0,0 @@
----
-source: crates/red_knot_project/src/metadata.rs
-expression: root
----
-ProjectMetadata(
-  name: Name("project-root"),
-  root: "/app",
-  options: Options(
-    environment: Some(EnvironmentOptions(
-      r#python-version: Some("3.10"),
-    )),
-  ),
-)

crates/red_knot_project/src/snapshots/red_knot_project__metadata__tests__nested_projects_without_knot_sections.snap

@@ -1,9 +0,0 @@
----
-source: crates/red_knot_project/src/metadata.rs
-expression: sub_project
----
-ProjectMetadata(
-  name: Name("nested-project"),
-  root: "/app/packages/a",
-  options: Options(),
-)

crates/red_knot_project/src/snapshots/red_knot_project__metadata__tests__project_with_knot_and_pyproject_toml.snap

@@ -1,13 +0,0 @@
----
-source: crates/red_knot_project/src/metadata.rs
-expression: root
----
-ProjectMetadata(
-  name: Name("super-app"),
-  root: "/app",
-  options: Options(
-    src: Some(SrcOptions(
-      root: Some("src"),
-    )),
-  ),
-)

crates/red_knot_project/src/snapshots/red_knot_project__metadata__tests__project_with_pyproject.snap

@@ -1,9 +0,0 @@
----
-source: crates/red_knot_project/src/metadata.rs
-expression: project
----
-ProjectMetadata(
-  name: Name("backend"),
-  root: "/app",
-  options: Options(),
-)

crates/red_knot_project/src/snapshots/red_knot_project__metadata__tests__project_without_pyproject.snap

@@ -1,9 +0,0 @@
----
-source: crates/red_knot_project/src/metadata.rs
-expression: project
----
-ProjectMetadata(
-  name: Name("app"),
-  root: "/app",
-  options: Options(),
-)

crates/red_knot_project/src/watch/project_watcher.rs

@@ -73,6 +73,13 @@ impl ProjectWatcher {
             .canonicalize_path(&project_path)
             .unwrap_or(project_path);
 
+        let config_paths = db
+            .project()
+            .metadata(db)
+            .extra_configuration_paths()
+            .iter()
+            .cloned();
+
         // Find the non-overlapping module search paths and filter out paths that are already covered by the project.
         // Module search paths are already canonicalized.
         let unique_module_paths = ruff_db::system::deduplicate_nested_paths(
@@ -83,8 +90,11 @@ impl ProjectWatcher {
         .map(SystemPath::to_path_buf);
 
         // Now add the new paths, first starting with the project path and then
-        // adding the library search paths.
-        for path in std::iter::once(project_path).chain(unique_module_paths) {
+        // adding the library search paths, and finally the paths for configurations.
+        for path in std::iter::once(project_path)
+            .chain(unique_module_paths)
+            .chain(config_paths)
+        {
             // Log a warning. It's not worth aborting if registering a single folder fails because
             // Ruff otherwise stills works as expected.
             if let Err(error) = self.watcher.watch(&path) {

crates/red_knot_project/tests/check.rs

@@ -270,6 +270,8 @@ impl SourceOrderVisitor<'_> for PullTypesVisitor<'_> {
 /// Whether or not the .py/.pyi version of this file is expected to fail
 #[rustfmt::skip]
 const KNOWN_FAILURES: &[(&str, bool, bool)] = &[
+    // related to circular references in nested functions
+    ("crates/ruff_linter/resources/test/fixtures/flake8_return/RET503.py", false, true),
     // related to circular references in class definitions
     ("crates/ruff_linter/resources/test/fixtures/pyflakes/F821_26.py", true, true),
     ("crates/ruff_linter/resources/test/fixtures/pyflakes/F821_27.py", true, true),

crates/red_knot_python_semantic/Cargo.toml

@@ -12,9 +12,9 @@ license = { workspace = true }
 
 [dependencies]
 ruff_db = { workspace = true }
-ruff_index = { workspace = true }
+ruff_index = { workspace = true, features = ["salsa"] }
 ruff_macros = { workspace = true }
-ruff_python_ast = { workspace = true }
+ruff_python_ast = { workspace = true, features = ["salsa"] }
 ruff_python_parser = { workspace = true }
 ruff_python_stdlib = { workspace = true }
 ruff_source_file = { workspace = true }
@@ -31,11 +31,12 @@ drop_bomb = { workspace = true }
 indexmap = { workspace = true }
 itertools = { workspace = true }
 ordermap = { workspace = true }
-salsa = { workspace = true }
+salsa = { workspace = true, features = ["compact_str"] }
 thiserror = { workspace = true }
 tracing = { workspace = true }
 rustc-hash = { workspace = true }
 hashbrown = { workspace = true }
+schemars = { workspace = true, optional = true }
 serde = { workspace = true, optional = true }
 smallvec = { workspace = true }
 static_assertions = { workspace = true }
@@ -43,7 +44,7 @@ test-case = { workspace = true }
 memchr = { workspace = true }
 
 [dev-dependencies]
-ruff_db = { workspace = true, features = ["os", "testing"] }
+ruff_db = { workspace = true, features = ["testing", "os"] }
 ruff_python_parser = { workspace = true }
 red_knot_test = { workspace = true }
 red_knot_vendored = { workspace = true }
@@ -56,7 +57,7 @@ quickcheck = { version = "1.0.3", default-features = false }
 quickcheck_macros = { version = "1.0.0" }
 
 [features]
-serde = ["ruff_db/serde", "dep:serde"]
+serde = ["ruff_db/serde", "dep:serde", "ruff_python_ast/serde"]
 
 [lints]
 workspace = true

crates/red_knot_python_semantic/resources/mdtest/annotations/deferred.md

@@ -2,7 +2,9 @@
 
 ## Deferred annotations in stubs always resolve
 
-```pyi path=mod.pyi
+`mod.pyi`:
+
+```pyi
 def get_foo() -> Foo: ...
 class Foo: ...
 ```

crates/red_knot_python_semantic/resources/mdtest/annotations/int_float_complex.md

@@ -0,0 +1,90 @@
+# Special cases for int/float/complex in annotations
+
+In order to support common use cases, an annotation of `float` actually means `int | float`, and an
+annotation of `complex` actually means `int | float | complex`. See
+[the specification](https://typing.readthedocs.io/en/latest/spec/special-types.html#special-cases-for-float-and-complex)
+
+## float
+
+An annotation of `float` means `int | float`, so `int` is assignable to it:
+
+```py
+def takes_float(x: float):
+    pass
+
+def passes_int_to_float(x: int):
+    # no error!
+    takes_float(x)
+```
+
+It also applies to variable annotations:
+
+```py
+def assigns_int_to_float(x: int):
+    # no error!
+    y: float = x
+```
+
+It doesn't work the other way around:
+
+```py
+def takes_int(x: int):
+    pass
+
+def passes_float_to_int(x: float):
+    # error: [invalid-argument-type]
+    takes_int(x)
+
+def assigns_float_to_int(x: float):
+    # error: [invalid-assignment]
+    y: int = x
+```
+
+Unlike other type checkers, we choose not to obfuscate this special case by displaying `int | float`
+as just `float`; we display the actual type:
+
+```py
+def f(x: float):
+    reveal_type(x)  # revealed: int | float
+```
+
+## complex
+
+An annotation of `complex` means `int | float | complex`, so `int` and `float` are both assignable
+to it (but not the other way around):
+
+```py
+def takes_complex(x: complex):
+    pass
+
+def passes_to_complex(x: float, y: int):
+    # no errors!
+    takes_complex(x)
+    takes_complex(y)
+
+def assigns_to_complex(x: float, y: int):
+    # no errors!
+    a: complex = x
+    b: complex = y
+
+def takes_int(x: int):
+    pass
+
+def takes_float(x: float):
+    pass
+
+def passes_complex(x: complex):
+    # error: [invalid-argument-type]
+    takes_int(x)
+    # error: [invalid-argument-type]
+    takes_float(x)
+
+def assigns_complex(x: complex):
+    # error: [invalid-assignment]
+    y: int = x
+    # error: [invalid-assignment]
+    z: float = x
+
+def f(x: complex):
+    reveal_type(x)  # revealed: int | float | complex
+```

crates/red_knot_python_semantic/resources/mdtest/annotations/literal.md

@@ -106,7 +106,7 @@ def union_example(
         Literal["B"],
         Literal[True],
         None,
-    ]
+    ],
 ):
     reveal_type(x)  # revealed: Unknown | Literal[-1, "A", b"A", b"\x00", b"\x07", 0, 1, "B", "foo", "bar", True] | None
 ```
@@ -116,7 +116,9 @@ def union_example(
 Only Literal that is defined in typing and typing_extension modules is detected as the special
 Literal.
 
-```pyi path=other.pyi
+`other.pyi`:
+
+```pyi
 from typing import _SpecialForm
 
 Literal: _SpecialForm

crates/red_knot_python_semantic/resources/mdtest/annotations/literal_string.md

@@ -73,12 +73,12 @@ qux = (foo, bar)
 reveal_type(qux)  # revealed: tuple[Literal["foo"], Literal["bar"]]
 
 # TODO: Infer "LiteralString"
-reveal_type(foo.join(qux))  # revealed: @Todo(Attribute access on `StringLiteral` types)
+reveal_type(foo.join(qux))  # revealed: @Todo(decorated method)
 
 template: LiteralString = "{}, {}"
 reveal_type(template)  # revealed: Literal["{}, {}"]
 # TODO: Infer `LiteralString`
-reveal_type(template.format(foo, bar))  # revealed: @Todo(Attribute access on `StringLiteral` types)
+reveal_type(template.format(foo, bar))  # revealed: @Todo(decorated method)
 ```
 
 ### Assignability

crates/red_knot_python_semantic/resources/mdtest/annotations/union.md

@@ -9,9 +9,9 @@ from typing import Union
 
 a: Union[int, str]
 a1: Union[int, bool]
-a2: Union[int, Union[float, str]]
+a2: Union[int, Union[bytes, str]]
 a3: Union[int, None]
-a4: Union[Union[float, str]]
+a4: Union[Union[bytes, str]]
 a5: Union[int]
 a6: Union[()]
 
@@ -21,11 +21,11 @@ def f():
     # Since bool is a subtype of int we simplify to int here. But we do allow assigning boolean values (see below).
     # revealed: int
     reveal_type(a1)
-    # revealed: int | float | str
+    # revealed: int | bytes | str
     reveal_type(a2)
     # revealed: int | None
     reveal_type(a3)
-    # revealed: float | str
+    # revealed: bytes | str
     reveal_type(a4)
     # revealed: int
     reveal_type(a5)

crates/red_knot_python_semantic/resources/mdtest/assignment/annotations.md

@@ -25,7 +25,9 @@ x = "foo"  # error: [invalid-assignment] "Object of type `Literal["foo"]` is not
 
 ## Tuple annotations are understood
 
-```py path=module.py
+`module.py`:
+
+```py
 from typing_extensions import Unpack
 
 a: tuple[()] = ()
@@ -40,7 +42,9 @@ i: tuple[str | int, str | int] = (42, 42)
 j: tuple[str | int] = (42,)
 ```
 
-```py path=script.py
+`script.py`:
+
+```py
 from module import a, b, c, d, e, f, g, h, i, j
 
 reveal_type(a)  # revealed: tuple[()]
@@ -114,7 +118,7 @@ reveal_type(x)  # revealed: Foo
 
 ## Annotations in stub files are deferred
 
-```pyi path=main.pyi
+```pyi
 x: Foo
 
 class Foo: ...
@@ -125,7 +129,7 @@ reveal_type(x)  # revealed: Foo
 
 ## Annotated assignments in stub files are inferred correctly
 
-```pyi path=main.pyi
+```pyi
 x: int = 1
 reveal_type(x) # revealed: Literal[1]
 ```

crates/red_knot_python_semantic/resources/mdtest/assignment/augmented.md

@@ -9,7 +9,7 @@ reveal_type(x)  # revealed: Literal[2]
 
 x = 1.0
 x /= 2
-reveal_type(x)  # revealed: float
+reveal_type(x)  # revealed: int | float
 ```
 
 ## Dunder methods
@@ -24,12 +24,12 @@ x -= 1
 reveal_type(x)  # revealed: str
 
 class C:
-    def __iadd__(self, other: str) -> float:
-        return 1.0
+    def __iadd__(self, other: str) -> int:
+        return 1
 
 x = C()
 x += "Hello"
-reveal_type(x)  # revealed: float
+reveal_type(x)  # revealed: int
 ```
 
 ## Unsupported types
@@ -40,7 +40,7 @@ class C:
         return 42
 
 x = C()
-# error: [invalid-argument-type]
+# error: [unsupported-operator] "Operator `-=` is unsupported between objects of type `C` and `Literal[1]`"
 x -= 1
 
 reveal_type(x)  # revealed: int
@@ -130,10 +130,10 @@ def _(flag: bool):
     if flag:
         f = Foo()
     else:
-        f = 42.0
+        f = 42
     f += 12
 
-    reveal_type(f)  # revealed: str | float
+    reveal_type(f)  # revealed: str | Literal[54]
 ```
 
 ## Partially bound target union with `__add__`

crates/red_knot_python_semantic/resources/mdtest/attributes.md

@@ -13,123 +13,94 @@ accessed on the class itself.
 
 ```py
 class C:
-    def __init__(self, value2: int, flag: bool = False) -> None:
-        # bound but not declared
-        self.pure_instance_variable1 = "value set in __init__"
-
-        # bound but not declared - with type inferred from parameter
-        self.pure_instance_variable2 = value2
-
-        # declared but not bound
-        self.pure_instance_variable3: bytes
-
-        # declared and bound
-        self.pure_instance_variable4: bool = True
-
-        # possibly undeclared/unbound
+    def __init__(self, param: int | None, flag: bool = False) -> None:
+        value = 1 if flag else "a"
+        self.inferred_from_value = value
+        self.inferred_from_other_attribute = self.inferred_from_value
+        self.inferred_from_param = param
+        self.declared_only: bytes
+        self.declared_and_bound: bool = True
         if flag:
-            self.pure_instance_variable5: str = "possibly set in __init__"
+            self.possibly_undeclared_unbound: str = "possibly set in __init__"
 
 c_instance = C(1)
 
-# TODO: should be `Literal["value set in __init__"]`, or `Unknown | Literal[…]` to allow
-# assignments to this unannotated attribute from other scopes.
-reveal_type(c_instance.pure_instance_variable1)  # revealed: @Todo(implicit instance attribute)
+reveal_type(c_instance.inferred_from_value)  # revealed: Unknown | Literal[1, "a"]
 
-# TODO: should be `int`
-reveal_type(c_instance.pure_instance_variable2)  # revealed: @Todo(implicit instance attribute)
+# TODO: Same here. This should be `Unknown | Literal[1, "a"]`
+reveal_type(c_instance.inferred_from_other_attribute)  # revealed: Unknown
 
-# TODO: should be `bytes`
-reveal_type(c_instance.pure_instance_variable3)  # revealed: @Todo(implicit instance attribute)
+# There is no special handling of attributes that are (directly) assigned to a declared parameter,
+# which means we union with `Unknown` here, since the attribute itself is not declared. This is
+# something that we might want to change in the future.
+#
+# See https://github.com/astral-sh/ruff/issues/15960 for a related discussion.
+reveal_type(c_instance.inferred_from_param)  # revealed: Unknown | int | None
 
-# TODO: should be `bool`
-reveal_type(c_instance.pure_instance_variable4)  # revealed: @Todo(implicit instance attribute)
+reveal_type(c_instance.declared_only)  # revealed: bytes
+
+reveal_type(c_instance.declared_and_bound)  # revealed: bool
 
-# TODO: should be `str`
 # We probably don't want to emit a diagnostic for this being possibly undeclared/unbound.
 # mypy and pyright do not show an error here.
-reveal_type(c_instance.pure_instance_variable5)  # revealed: @Todo(implicit instance attribute)
+reveal_type(c_instance.possibly_undeclared_unbound)  # revealed: str
 
-# TODO: If we choose to infer a precise `Literal[…]` type for the instance attribute (see
-# above), this should be an error: incompatible types in assignment. If we choose to infer
-# a gradual `Unknown | Literal[…]` type, this assignment is fine.
-c_instance.pure_instance_variable1 = "value set on instance"
+# This assignment is fine, as we infer `Unknown | Literal[1, "a"]` for `inferred_from_value`.
+c_instance.inferred_from_value = "value set on instance"
 
-# TODO: this should be an error (incompatible types in assignment)
-c_instance.pure_instance_variable2 = "incompatible"
+# This assignment is also fine:
+c_instance.declared_and_bound = False
+
+# error: [invalid-assignment] "Object of type `Literal["incompatible"]` is not assignable to attribute `declared_and_bound` of type `bool`"
+c_instance.declared_and_bound = "incompatible"
 
 # TODO: we already show an error here but the message might be improved?
 # mypy shows no error here, but pyright raises "reportAttributeAccessIssue"
-# error: [unresolved-attribute] "Type `Literal[C]` has no attribute `pure_instance_variable1`"
-reveal_type(C.pure_instance_variable1)  # revealed: Unknown
+# error: [unresolved-attribute] "Type `Literal[C]` has no attribute `inferred_from_value`"
+reveal_type(C.inferred_from_value)  # revealed: Unknown
 
 # TODO: this should be an error (pure instance variables cannot be accessed on the class)
 # mypy shows no error here, but pyright raises "reportAttributeAccessIssue"
-C.pure_instance_variable1 = "overwritten on class"
+C.inferred_from_value = "overwritten on class"
 
-c_instance.pure_instance_variable4 = False
+# This assignment is fine:
+c_instance.declared_and_bound = False
 
 # TODO: After this assignment to the attribute within this scope, we may eventually want to narrow
 # the `bool` type (see above) for this instance variable to `Literal[False]` here. This is unsound
 # in general (we don't know what else happened to `c_instance` between the assignment and the use
 # here), but mypy and pyright support this. In conclusion, this could be `bool` but should probably
 # be `Literal[False]`.
-reveal_type(c_instance.pure_instance_variable4)  # revealed: @Todo(implicit instance attribute)
+reveal_type(c_instance.declared_and_bound)  # revealed: bool
 ```
 
-#### Variable declared in class body and declared/bound in `__init__`
+#### Variable declared in class body and possibly bound in `__init__`
 
 The same rule applies even if the variable is *declared* (not bound!) in the class body: it is still
 a pure instance variable.
 
 ```py
 class C:
-    pure_instance_variable: str
+    declared_and_bound: str | None
 
     def __init__(self) -> None:
-        self.pure_instance_variable = "value set in __init__"
+        self.declared_and_bound = "value set in __init__"
 
 c_instance = C()
 
-reveal_type(c_instance.pure_instance_variable)  # revealed: str
+reveal_type(c_instance.declared_and_bound)  # revealed: str | None
 
 # TODO: we currently plan to emit a diagnostic here. Note that both mypy
 # and pyright show no error in this case! So we may reconsider this in
 # the future, if it turns out to produce too many false positives.
-reveal_type(C.pure_instance_variable)  # revealed: str
+reveal_type(C.declared_and_bound)  # revealed: str | None
 
 # TODO: same as above. We plan to emit a diagnostic here, even if both mypy
 # and pyright allow this.
-C.pure_instance_variable = "overwritten on class"
+C.declared_and_bound = "overwritten on class"
 
-# error: [invalid-assignment] "Object of type `Literal[1]` is not assignable to attribute `pure_instance_variable` of type `str`"
-c_instance.pure_instance_variable = 1
-```
-
-#### Variable only defined in unrelated method
-
-We also recognize pure instance variables if they are defined in a method that is not `__init__`.
-
-```py
-class C:
-    def set_instance_variable(self) -> None:
-        self.pure_instance_variable = "value set in method"
-
-c_instance = C()
-
-# Not that we would use this in static analysis, but for a more realistic example, let's actually
-# call the method, so that the attribute is bound if this example is actually run.
-c_instance.set_instance_variable()
-
-# TODO: should be `Literal["value set in method"]` or `Unknown | Literal[…]` (see above).
-reveal_type(c_instance.pure_instance_variable)  # revealed: @Todo(implicit instance attribute)
-
-# TODO: We already show an error here, but the message might be improved?
-# error: [unresolved-attribute]
-reveal_type(C.pure_instance_variable)  # revealed: Unknown
-
-# TODO: this should be an error
-C.pure_instance_variable = "overwritten on class"
+# error: [invalid-assignment] "Object of type `Literal[1]` is not assignable to attribute `declared_and_bound` of type `str | None`"
+c_instance.declared_and_bound = 1
 ```
 
 #### Variable declared in class body and not bound anywhere
@@ -139,18 +110,426 @@ instance variable and allow access to it via instances.
 
 ```py
 class C:
-    pure_instance_variable: str
+    only_declared: str
 
 c_instance = C()
 
-reveal_type(c_instance.pure_instance_variable)  # revealed: str
+reveal_type(c_instance.only_declared)  # revealed: str
 
 # TODO: mypy and pyright do not show an error here, but we plan to emit a diagnostic.
 # The type could be changed to 'Unknown' if we decide to emit an error?
-reveal_type(C.pure_instance_variable)  # revealed: str
+reveal_type(C.only_declared)  # revealed: str
 
 # TODO: mypy and pyright do not show an error here, but we plan to emit one.
-C.pure_instance_variable = "overwritten on class"
+C.only_declared = "overwritten on class"
+```
+
+#### Mixed declarations/bindings in class body and `__init__`
+
+```py
+class C:
+    only_declared_in_body: str | None
+    declared_in_body_and_init: str | None
+
+    declared_in_body_defined_in_init: str | None
+
+    bound_in_body_declared_in_init = "a"
+
+    bound_in_body_and_init = None
+
+    def __init__(self, flag) -> None:
+        self.only_declared_in_init: str | None
+        self.declared_in_body_and_init: str | None = None
+
+        self.declared_in_body_defined_in_init = "a"
+
+        self.bound_in_body_declared_in_init: str | None
+
+        if flag:
+            self.bound_in_body_and_init = "a"
+
+c_instance = C(True)
+
+reveal_type(c_instance.only_declared_in_body)  # revealed: str | None
+reveal_type(c_instance.only_declared_in_init)  # revealed: str | None
+reveal_type(c_instance.declared_in_body_and_init)  # revealed: str | None
+
+reveal_type(c_instance.declared_in_body_defined_in_init)  # revealed: str | None
+
+reveal_type(c_instance.bound_in_body_declared_in_init)  # revealed: str | None
+
+reveal_type(c_instance.bound_in_body_and_init)  # revealed: Unknown | None | Literal["a"]
+```
+
+#### Variable defined in non-`__init__` method
+
+We also recognize pure instance variables if they are defined in a method that is not `__init__`.
+
+```py
+class C:
+    def __init__(self, param: int | None, flag: bool = False) -> None:
+        self.initialize(param, flag)
+
+    def initialize(self, param: int | None, flag: bool) -> None:
+        value = 1 if flag else "a"
+        self.inferred_from_value = value
+        self.inferred_from_other_attribute = self.inferred_from_value
+        self.inferred_from_param = param
+        self.declared_only: bytes
+        self.declared_and_bound: bool = True
+
+c_instance = C(1)
+
+reveal_type(c_instance.inferred_from_value)  # revealed: Unknown | Literal[1, "a"]
+
+# TODO: Should be `Unknown | Literal[1, "a"]`
+reveal_type(c_instance.inferred_from_other_attribute)  # revealed: Unknown
+
+reveal_type(c_instance.inferred_from_param)  # revealed: Unknown | int | None
+
+reveal_type(c_instance.declared_only)  # revealed: bytes
+
+reveal_type(c_instance.declared_and_bound)  # revealed: bool
+
+# TODO: We already show an error here, but the message might be improved?
+# error: [unresolved-attribute]
+reveal_type(C.inferred_from_value)  # revealed: Unknown
+
+# TODO: this should be an error
+C.inferred_from_value = "overwritten on class"
+```
+
+#### Variable defined in multiple methods
+
+If we see multiple un-annotated assignments to a single attribute (`self.x` below), we build the
+union of all inferred types (and `Unknown`). If we see multiple conflicting declarations of the same
+attribute, that should be an error.
+
+```py
+def get_int() -> int:
+    return 0
+
+def get_str() -> str:
+    return "a"
+
+class C:
+    z: int
+
+    def __init__(self) -> None:
+        self.x = get_int()
+        self.y: int = 1
+
+    def other_method(self):
+        self.x = get_str()
+
+        # TODO: this redeclaration should be an error
+        self.y: str = "a"
+
+        # TODO: this redeclaration should be an error
+        self.z: str = "a"
+
+c_instance = C()
+
+reveal_type(c_instance.x)  # revealed: Unknown | int | str
+reveal_type(c_instance.y)  # revealed: int
+reveal_type(c_instance.z)  # revealed: int
+```
+
+#### Attributes defined in multi-target assignments
+
+```py
+class C:
+    def __init__(self) -> None:
+        self.a = self.b = 1
+
+c_instance = C()
+
+reveal_type(c_instance.a)  # revealed: Unknown | Literal[1]
+reveal_type(c_instance.b)  # revealed: Unknown | Literal[1]
+```
+
+#### Augmented assignments
+
+```py
+class Weird:
+    def __iadd__(self, other: None) -> str:
+        return "a"
+
+class C:
+    def __init__(self) -> None:
+        self.w = Weird()
+        self.w += None
+
+# TODO: Mypy and pyright do not support this, but it would be great if we could
+# infer `Unknown | str` or at least `Unknown | Weird | str` here.
+reveal_type(C().w)  # revealed: Unknown | Weird
+```
+
+#### Attributes defined in tuple unpackings
+
+```py
+def returns_tuple() -> tuple[int, str]:
+    return (1, "a")
+
+class C:
+    a1, b1 = (1, "a")
+    c1, d1 = returns_tuple()
+
+    def __init__(self) -> None:
+        self.a2, self.b2 = (1, "a")
+        self.c2, self.d2 = returns_tuple()
+
+c_instance = C()
+
+reveal_type(c_instance.a1)  # revealed: Unknown | Literal[1]
+reveal_type(c_instance.b1)  # revealed: Unknown | Literal["a"]
+reveal_type(c_instance.c1)  # revealed: Unknown | int
+reveal_type(c_instance.d1)  # revealed: Unknown | str
+
+reveal_type(c_instance.a2)  # revealed: Unknown | Literal[1]
+
+reveal_type(c_instance.b2)  # revealed: Unknown | Literal["a"]
+
+reveal_type(c_instance.c2)  # revealed: Unknown | int
+reveal_type(c_instance.d2)  # revealed: Unknown | str
+```
+
+#### Starred assignments
+
+```py
+class C:
+    def __init__(self) -> None:
+        self.a, *self.b = (1, 2, 3)
+
+c_instance = C()
+reveal_type(c_instance.a)  # revealed: Unknown | Literal[1]
+reveal_type(c_instance.b)  # revealed: Unknown | @Todo(starred unpacking)
+```
+
+#### Attributes defined in for-loop (unpacking)
+
+```py
+class IntIterator:
+    def __next__(self) -> int:
+        return 1
+
+class IntIterable:
+    def __iter__(self) -> IntIterator:
+        return IntIterator()
+
+class TupleIterator:
+    def __next__(self) -> tuple[int, str]:
+        return (1, "a")
+
+class TupleIterable:
+    def __iter__(self) -> TupleIterator:
+        return TupleIterator()
+
+class NonIterable: ...
+
+class C:
+    def __init__(self):
+        for self.x in IntIterable():
+            pass
+
+        for _, self.y in TupleIterable():
+            pass
+
+        # TODO: We should emit a diagnostic here
+        for self.z in NonIterable():
+            pass
+
+reveal_type(C().x)  # revealed: Unknown | int
+
+reveal_type(C().y)  # revealed: Unknown | str
+```
+
+#### Attributes defined in `with` statements
+
+```py
+class ContextManager:
+    def __enter__(self) -> int | None: ...
+    def __exit__(self, exc_type, exc_value, traceback) -> None: ...
+
+class C:
+    def __init__(self) -> None:
+        with ContextManager() as self.x:
+            pass
+
+c_instance = C()
+
+# TODO: Should be `Unknown | int | None`
+# error: [unresolved-attribute]
+reveal_type(c_instance.x)  # revealed: Unknown
+```
+
+#### Attributes defined in comprehensions
+
+```py
+class IntIterator:
+    def __next__(self) -> int:
+        return 1
+
+class IntIterable:
+    def __iter__(self) -> IntIterator:
+        return IntIterator()
+
+class C:
+    def __init__(self) -> None:
+        [... for self.a in IntIterable()]
+
+c_instance = C()
+
+# TODO: Should be `Unknown | int`
+# error: [unresolved-attribute]
+reveal_type(c_instance.a)  # revealed: Unknown
+```
+
+#### Conditionally declared / bound attributes
+
+We currently do not raise a diagnostic or change behavior if an attribute is only conditionally
+defined. This is consistent with what mypy and pyright do.
+
+```py
+def flag() -> bool:
+    return True
+
+class C:
+    def f(self) -> None:
+        if flag():
+            self.a1: str | None = "a"
+            self.b1 = 1
+    if flag():
+        def f(self) -> None:
+            self.a2: str | None = "a"
+            self.b2 = 1
+
+c_instance = C()
+
+reveal_type(c_instance.a1)  # revealed: str | None
+reveal_type(c_instance.a2)  # revealed: str | None
+reveal_type(c_instance.b1)  # revealed: Unknown | Literal[1]
+reveal_type(c_instance.b2)  # revealed: Unknown | Literal[1]
+```
+
+#### Methods that does not use `self` as a first parameter
+
+```py
+class C:
+    # This might trigger a stylistic lint like `invalid-first-argument-name-for-method`, but
+    # it should be supported in general:
+    def __init__(this) -> None:
+        this.declared_and_bound: str | None = "a"
+
+reveal_type(C().declared_and_bound)  # revealed: str | None
+```
+
+#### Aliased `self` parameter
+
+```py
+class C:
+    def __init__(self) -> None:
+        this = self
+        this.declared_and_bound: str | None = "a"
+
+# This would ideally be `str | None`, but mypy/pyright don't support this either,
+# so `Unknown` + a diagnostic is also fine.
+# error: [unresolved-attribute]
+reveal_type(C().declared_and_bound)  # revealed: Unknown
+```
+
+#### Static methods do not influence implicitly defined attributes
+
+```py
+class Other:
+    x: int
+
+class C:
+    @staticmethod
+    def f(other: Other) -> None:
+        other.x = 1
+
+# error: [unresolved-attribute]
+reveal_type(C.x)  # revealed: Unknown
+
+# TODO: this should raise `unresolved-attribute` as well, and the type should be `Unknown`
+reveal_type(C().x)  # revealed: Unknown | Literal[1]
+
+# This also works if `staticmethod` is aliased:
+
+my_staticmethod = staticmethod
+
+class D:
+    @my_staticmethod
+    def f(other: Other) -> None:
+        other.x = 1
+
+# error: [unresolved-attribute]
+reveal_type(D.x)  # revealed: Unknown
+
+# TODO: this should raise `unresolved-attribute` as well, and the type should be `Unknown`
+reveal_type(D().x)  # revealed: Unknown | Literal[1]
+```
+
+If `staticmethod` is something else, that should not influence the behavior:
+
+```py
+def staticmethod(f):
+    return f
+
+class C:
+    @staticmethod
+    def f(self) -> None:
+        self.x = 1
+
+reveal_type(C().x)  # revealed: Unknown | Literal[1]
+```
+
+And if `staticmethod` is fully qualified, that should also be recognized:
+
+```py
+import builtins
+
+class Other:
+    x: int
+
+class C:
+    @builtins.staticmethod
+    def f(other: Other) -> None:
+        other.x = 1
+
+# error: [unresolved-attribute]
+reveal_type(C.x)  # revealed: Unknown
+
+# TODO: this should raise `unresolved-attribute` as well, and the type should be `Unknown`
+reveal_type(C().x)  # revealed: Unknown | Literal[1]
+```
+
+#### Attributes defined in statically-known-to-be-false branches
+
+```py
+class C:
+    def __init__(self) -> None:
+        # We use a "significantly complex" condition here (instead of just `False`)
+        # for a proper comparison with mypy and pyright, which distinguish between
+        # conditions that can be resolved from a simple pattern matching and those
+        # that need proper type inference.
+        if (2 + 3) < 4:
+            self.x: str = "a"
+
+# TODO: Ideally, this would result in a `unresolved-attribute` error. But mypy and pyright
+# do not support this either (for conditions that can only be resolved to `False` in type
+# inference), so it does not seem to be particularly important.
+reveal_type(C().x)  # revealed: str
+```
+
+#### Diagnostics are reported for the right-hand side of attribute assignments
+
+```py
+class C:
+    def __init__(self) -> None:
+        # error: [too-many-positional-arguments]
+        self.x: int = len(1, 2, 3)
 ```
 
 ### Pure class variables (`ClassVar`)
@@ -221,13 +600,13 @@ reveal_type(C.pure_class_variable)  # revealed: Unknown
 
 C.pure_class_variable = "overwritten on class"
 
-# TODO: should be `Literal["overwritten on class"]`
+# TODO: should be  `Unknown | Literal["value set in class method"]` or
+# Literal["overwritten on class"]`, once/if we support local narrowing.
 # error: [unresolved-attribute]
 reveal_type(C.pure_class_variable)  # revealed: Unknown
 
 c_instance = C()
-# TODO: should be `Literal["overwritten on class"]`
-reveal_type(c_instance.pure_class_variable)  # revealed: @Todo(implicit instance attribute)
+reveal_type(c_instance.pure_class_variable)  # revealed: Unknown | Literal["value set in class method"]
 
 # TODO: should raise an error.
 c_instance.pure_class_variable = "value set on instance"
@@ -277,6 +656,53 @@ reveal_type(C.variable_with_class_default1)  # revealed: str
 reveal_type(c_instance.variable_with_class_default1)  # revealed: str
 ```
 
+### Inheritance of class/instance attributes
+
+#### Instance variable defined in a base class
+
+```py
+class Base:
+    declared_in_body: int | None = 1
+
+    base_class_attribute_1: str | None
+    base_class_attribute_2: str | None
+    base_class_attribute_3: str | None
+
+    def __init__(self) -> None:
+        self.defined_in_init: str | None = "value in base"
+
+class Intermediate(Base):
+    # Re-declaring base class attributes with the *same *type is fine:
+    base_class_attribute_1: str | None = None
+
+    # Re-declaring them with a *narrower type* is unsound, because modifications
+    # through a `Base` reference could violate that constraint.
+    #
+    # Mypy does not report an error here, but pyright does: "… overrides symbol
+    # of same name in class "Base". Variable is mutable so its type is invariant"
+    #
+    # We should introduce a diagnostic for this. Whether or not that should be
+    # enabled by default can still be discussed.
+    #
+    # TODO: This should be an error
+    base_class_attribute_2: str
+
+    # Re-declaring attributes with a *wider type* directly violates LSP.
+    #
+    # In this case, both mypy and pyright report an error.
+    #
+    # TODO: This should be an error
+    base_class_attribute_3: str | int | None
+
+class Derived(Intermediate): ...
+
+reveal_type(Derived.declared_in_body)  # revealed: int | None
+
+reveal_type(Derived().declared_in_body)  # revealed: int | None
+
+reveal_type(Derived().defined_in_init)  # revealed: str | None
+```
+
 ## Union of attributes
 
 ```py
@@ -381,6 +807,67 @@ def _(flag: bool, flag1: bool, flag2: bool):
     reveal_type(C.x)  # revealed: Unknown | Literal[1, 2, 3]
 ```
 
+### Attribute possibly unbound on a subclass but not on a superclass
+
+```py
+def _(flag: bool):
+    class Foo:
+        x = 1
+
+    class Bar(Foo):
+        if flag:
+            x = 2
+
+    reveal_type(Bar.x)  # revealed: Unknown | Literal[2, 1]
+```
+
+### Attribute possibly unbound on a subclass and on a superclass
+
+```py
+def _(flag: bool):
+    class Foo:
+        if flag:
+            x = 1
+
+    class Bar(Foo):
+        if flag:
+            x = 2
+
+    # error: [possibly-unbound-attribute]
+    reveal_type(Bar.x)  # revealed: Unknown | Literal[2, 1]
+```
+
+### Attribute access on `Any`
+
+The union of the set of types that `Any` could materialise to is equivalent to `object`. It follows
+from this that attribute access on `Any` resolves to `Any` if the attribute does not exist on
+`object` -- but if the attribute *does* exist on `object`, the type of the attribute is
+`<type as it exists on object> & Any`.
+
+```py
+from typing import Any
+
+class Foo(Any): ...
+
+reveal_type(Foo.bar)  # revealed: Any
+reveal_type(Foo.__repr__)  # revealed: Literal[__repr__] & Any
+```
+
+Similar principles apply if `Any` appears in the middle of an inheritance hierarchy:
+
+```py
+from typing import ClassVar, Literal
+
+class A:
+    x: ClassVar[Literal[1]] = 1
+
+class B(Any): ...
+class C(B, A): ...
+
+reveal_type(C.__mro__)  # revealed: tuple[Literal[C], Literal[B], Any, Literal[A], Literal[object]]
+reveal_type(C.x)  # revealed: Literal[1] & Any
+```
+
 ### Unions with all paths unbound
 
 If the symbol is unbound in all elements of the union, we detect that:
@@ -437,7 +924,9 @@ reveal_type(Foo.__class__)  # revealed: Literal[type]
 
 ## Module attributes
 
-```py path=mod.py
+`mod.py`:
+
+```py
 global_symbol: str = "a"
 ```
 
@@ -471,13 +960,19 @@ for mod.global_symbol in IntIterable():
 
 ## Nested attributes
 
-```py path=outer/__init__.py
+`outer/__init__.py`:
+
+```py
 ```
 
-```py path=outer/nested/__init__.py
+`outer/nested/__init__.py`:
+
+```py
 ```
 
-```py path=outer/nested/inner.py
+`outer/nested/inner.py`:
+
+```py
 class Outer:
     class Nested:
         class Inner:
@@ -500,7 +995,7 @@ outer.nested.inner.Outer.Nested.Inner.attr = "a"
 Most attribute accesses on function-literal types are delegated to `types.FunctionType`, since all
 functions are instances of that class:
 
-```py path=a.py
+```py
 def f(): ...
 
 reveal_type(f.__defaults__)  # revealed: @Todo(full tuple[...] support) | None
@@ -509,11 +1004,9 @@ reveal_type(f.__kwdefaults__)  # revealed: @Todo(generics) | None
 
 Some attributes are special-cased, however:
 
-```py path=b.py
-def f(): ...
-
-reveal_type(f.__get__)  # revealed: @Todo(`__get__` method on functions)
-reveal_type(f.__call__)  # revealed: @Todo(`__call__` method on functions)
+```py
+reveal_type(f.__get__)  # revealed: <method-wrapper `__get__` of `f`>
+reveal_type(f.__call__)  # revealed: <bound method `__call__` of `Literal[f]`>
 ```
 
 ### Int-literal attributes
@@ -521,14 +1014,14 @@ reveal_type(f.__call__)  # revealed: @Todo(`__call__` method on functions)
 Most attribute accesses on int-literal types are delegated to `builtins.int`, since all literal
 integers are instances of that class:
 
-```py path=a.py
-reveal_type((2).bit_length)  # revealed: @Todo(bound method)
+```py
+reveal_type((2).bit_length)  # revealed: <bound method `bit_length` of `Literal[2]`>
 reveal_type((2).denominator)  # revealed: @Todo(@property)
 ```
 
 Some attributes are special-cased, however:
 
-```py path=b.py
+```py
 reveal_type((2).numerator)  # revealed: Literal[2]
 reveal_type((2).real)  # revealed: Literal[2]
 ```
@@ -536,27 +1029,145 @@ reveal_type((2).real)  # revealed: Literal[2]
 ### Bool-literal attributes
 
 Most attribute accesses on bool-literal types are delegated to `builtins.bool`, since all literal
-bols are instances of that class:
+bools are instances of that class:
 
-```py path=a.py
-reveal_type(True.__and__)  # revealed: @Todo(bound method)
-reveal_type(False.__or__)  # revealed: @Todo(bound method)
+```py
+reveal_type(True.__and__)  # revealed: @Todo(decorated method)
+reveal_type(False.__or__)  # revealed: @Todo(decorated method)
 ```
 
 Some attributes are special-cased, however:
 
-```py path=b.py
+```py
 reveal_type(True.numerator)  # revealed: Literal[1]
 reveal_type(False.real)  # revealed: Literal[0]
 ```
 
 ### Bytes-literal attributes
 
-All attribute access on literal `bytes` types is currently delegated to `buitins.bytes`:
+All attribute access on literal `bytes` types is currently delegated to `builtins.bytes`:
 
 ```py
-reveal_type(b"foo".join)  # revealed: @Todo(bound method)
-reveal_type(b"foo".endswith)  # revealed: @Todo(bound method)
+reveal_type(b"foo".join)  # revealed: <bound method `join` of `Literal[b"foo"]`>
+reveal_type(b"foo".endswith)  # revealed: <bound method `endswith` of `Literal[b"foo"]`>
+```
+
+## Instance attribute edge cases
+
+### Assignment to attribute that does not correspond to the instance
+
+```py
+class Other:
+    x: int = 1
+
+class C:
+    def __init__(self, other: Other) -> None:
+        other.x = 1
+
+def f(c: C):
+    # error: [unresolved-attribute]
+    reveal_type(c.x)  # revealed: Unknown
+```
+
+### Nested classes
+
+```py
+class Outer:
+    def __init__(self):
+        self.x: int = 1
+
+    class Middle:
+        # has no 'x' attribute
+
+        class Inner:
+            def __init__(self):
+                self.x: str = "a"
+
+reveal_type(Outer().x)  # revealed: int
+
+# error: [unresolved-attribute]
+Outer.Middle().x
+
+reveal_type(Outer.Middle.Inner().x)  # revealed: str
+```
+
+### Shadowing of `self`
+
+```py
+class Other:
+    x: int = 1
+
+class C:
+    def __init__(self) -> None:
+        # Redeclaration of self. `self` does not refer to the instance anymore.
+        self: Other = Other()
+        self.x: int = 1
+
+# TODO: this should be an error
+C().x
+```
+
+### Assignment to `self` after nested function
+
+```py
+class Other:
+    x: str = "a"
+
+class C:
+    def __init__(self) -> None:
+        def nested_function(self: Other):
+            self.x = "b"
+        self.x: int = 1
+
+reveal_type(C().x)  # revealed: int
+```
+
+### Assignment to `self` from nested function
+
+```py
+class C:
+    def __init__(self) -> None:
+        def set_attribute(value: str):
+            self.x: str = value
+        set_attribute("a")
+
+# TODO: ideally, this would be `str`. Mypy supports this, pyright does not.
+# error: [unresolved-attribute]
+reveal_type(C().x)  # revealed: Unknown
+```
+
+### Builtin types attributes
+
+This test can probably be removed eventually, but we currently include it because we do not yet
+understand generic bases and protocols, and we want to make sure that we can still use builtin types
+in our tests in the meantime. See the corresponding TODO in `Type::static_member` for more
+information.
+
+```py
+class C:
+    a_int: int = 1
+    a_str: str = "a"
+    a_bytes: bytes = b"a"
+    a_bool: bool = True
+    a_float: float = 1.0
+    a_complex: complex = 1 + 1j
+    a_tuple: tuple[int] = (1,)
+    a_range: range = range(1)
+    a_slice: slice = slice(1)
+    a_type: type = int
+    a_none: None = None
+
+reveal_type(C.a_int)  # revealed: int
+reveal_type(C.a_str)  # revealed: str
+reveal_type(C.a_bytes)  # revealed: bytes
+reveal_type(C.a_bool)  # revealed: bool
+reveal_type(C.a_float)  # revealed: int | float
+reveal_type(C.a_complex)  # revealed: int | float | complex
+reveal_type(C.a_tuple)  # revealed: tuple[int]
+reveal_type(C.a_range)  # revealed: range
+reveal_type(C.a_slice)  # revealed: slice
+reveal_type(C.a_type)  # revealed: type
+reveal_type(C.a_none)  # revealed: None
 ```
 
 ## References

crates/red_knot_python_semantic/resources/mdtest/binary/booleans.md

@@ -56,7 +56,7 @@ def _(a: bool):
         reveal_type(x - a)  # revealed: int
         reveal_type(x * a)  # revealed: int
         reveal_type(x // a)  # revealed: int
-        reveal_type(x / a)  # revealed: float
+        reveal_type(x / a)  # revealed: int | float
         reveal_type(x % a)  # revealed: int
 
     def rhs_is_int(x: int):
@@ -64,7 +64,7 @@ def _(a: bool):
         reveal_type(a - x)  # revealed: int
         reveal_type(a * x)  # revealed: int
         reveal_type(a // x)  # revealed: int
-        reveal_type(a / x)  # revealed: float
+        reveal_type(a / x)  # revealed: int | float
         reveal_type(a % x)  # revealed: int
 
     def lhs_is_bool(x: bool):
@@ -72,7 +72,7 @@ def _(a: bool):
         reveal_type(x - a)  # revealed: int
         reveal_type(x * a)  # revealed: int
         reveal_type(x // a)  # revealed: int
-        reveal_type(x / a)  # revealed: float
+        reveal_type(x / a)  # revealed: int | float
         reveal_type(x % a)  # revealed: int
 
     def rhs_is_bool(x: bool):
@@ -80,7 +80,7 @@ def _(a: bool):
         reveal_type(a - x)  # revealed: int
         reveal_type(a * x)  # revealed: int
         reveal_type(a // x)  # revealed: int
-        reveal_type(a / x)  # revealed: float
+        reveal_type(a / x)  # revealed: int | float
         reveal_type(a % x)  # revealed: int
 
     def both_are_bool(x: bool, y: bool):
@@ -88,6 +88,6 @@ def _(a: bool):
         reveal_type(x - y)  # revealed: int
         reveal_type(x * y)  # revealed: int
         reveal_type(x // y)  # revealed: int
-        reveal_type(x / y)  # revealed: float
+        reveal_type(x / y)  # revealed: int | float
         reveal_type(x % y)  # revealed: int
 ```

crates/red_knot_python_semantic/resources/mdtest/binary/custom.md

@@ -3,6 +3,8 @@
 ## Class instances
 
 ```py
+from typing import Literal
+
 class Yes:
     def __add__(self, other) -> Literal["+"]:
         return "+"
@@ -136,6 +138,8 @@ reveal_type(No() // Yes())  # revealed: Unknown
 ## Subclass reflections override superclass dunders
 
 ```py
+from typing import Literal
+
 class Yes:
     def __add__(self, other) -> Literal["+"]:
         return "+"
@@ -294,6 +298,8 @@ itself. (For these operators to work on the class itself, they would have to be
 class's type, i.e. `type`.)
 
 ```py
+from typing import Literal
+
 class Yes:
     def __add__(self, other) -> Literal["+"]:
         return "+"
@@ -312,6 +318,8 @@ reveal_type(No + No)  # revealed: Unknown
 ## Subclass
 
 ```py
+from typing import Literal
+
 class Yes:
     def __add__(self, other) -> Literal["+"]:
         return "+"

crates/red_knot_python_semantic/resources/mdtest/binary/instances.md

@@ -244,10 +244,7 @@ class B:
     def __rsub__(self, other: A) -> B:
         return B()
 
-# TODO: this should be `B` (the return annotation of `B.__rsub__`),
-# because `A.__sub__` is annotated as only accepting `A`,
-# but `B.__rsub__` will accept `A`.
-reveal_type(A() - B())  # revealed: A
+reveal_type(A() - B())  # revealed: B
 ```
 
 ## Callable instances as dunders
@@ -263,31 +260,31 @@ class B:
     __add__ = A()
 
 # TODO: this could be `int` if we declare `B.__add__` using a `Callable` type
-reveal_type(B() + B())  # revealed: Unknown | int
+# TODO: Should not be an error: `A` instance is not a method descriptor, don't prepend `self` arg.
+#   Revealed type should be `Unknown | int`.
+# error: [unsupported-operator] "Operator `+` is unsupported between objects of type `B` and `B`"
+reveal_type(B() + B())  # revealed: Unknown
 ```
 
 ## Integration test: numbers from typeshed
 
+We get less precise results from binary operations on float/complex literals due to the special case
+for annotations of `float` or `complex`, which applies also to return annotations for typeshed
+dunder methods. Perhaps we could have a special-case on the special-case, to exclude these typeshed
+return annotations from the widening, and preserve a bit more precision here?
+
 ```py
-reveal_type(3j + 3.14)  # revealed: complex
-reveal_type(4.2 + 42)  # revealed: float
-reveal_type(3j + 3)  # revealed: complex
-
-# TODO should be complex, need to check arg type and fall back to `rhs.__radd__`
-reveal_type(3.14 + 3j)  # revealed: float
-
-# TODO should be float, need to check arg type and fall back to `rhs.__radd__`
-reveal_type(42 + 4.2)  # revealed: int
-
-# TODO should be complex, need to check arg type and fall back to `rhs.__radd__`
-reveal_type(3 + 3j)  # revealed: int
+reveal_type(3j + 3.14)  # revealed: int | float | complex
+reveal_type(4.2 + 42)  # revealed: int | float
+reveal_type(3j + 3)  # revealed: int | float | complex
+reveal_type(3.14 + 3j)  # revealed: int | float | complex
+reveal_type(42 + 4.2)  # revealed: int | float
+reveal_type(3 + 3j)  # revealed: int | float | complex
 
 def _(x: bool, y: int):
     reveal_type(x + y)  # revealed: int
-    reveal_type(4.2 + x)  # revealed: float
-
-    # TODO should be float, need to check arg type and fall back to `rhs.__radd__`
-    reveal_type(y + 4.12)  # revealed: int
+    reveal_type(4.2 + x)  # revealed: int | float
+    reveal_type(y + 4.12)  # revealed: int | float
 ```
 
 ## With literal types
@@ -304,8 +301,7 @@ class A:
         return self
 
 reveal_type(A() + 1)  # revealed: A
-# TODO should be `A` since `int.__add__` doesn't support `A` instances
-reveal_type(1 + A())  # revealed: int
+reveal_type(1 + A())  # revealed: A
 
 reveal_type(A() + "foo")  # revealed: A
 # TODO should be `A` since `str.__add__` doesn't support `A` instances

crates/red_knot_python_semantic/resources/mdtest/binary/integers.md

@@ -10,16 +10,16 @@ reveal_type(-3 // 3)  # revealed: Literal[-1]
 reveal_type(-3 / 3)  # revealed: float
 reveal_type(5 % 3)  # revealed: Literal[2]
 
-# TODO: We don't currently verify that the actual parameter to int.__add__ matches the declared
-# formal parameter type.
-reveal_type(2 + "f")  # revealed: int
+# TODO: Should emit `unsupported-operator` but we don't understand the bases of `str`, so we think
+#       it inherits `Unknown`, so we think `str.__radd__` is `Unknown` instead of nonexistent.
+reveal_type(2 + "f")  # revealed: Unknown
 
 def lhs(x: int):
     reveal_type(x + 1)  # revealed: int
     reveal_type(x - 4)  # revealed: int
     reveal_type(x * -1)  # revealed: int
     reveal_type(x // 3)  # revealed: int
-    reveal_type(x / 3)  # revealed: float
+    reveal_type(x / 3)  # revealed: int | float
     reveal_type(x % 3)  # revealed: int
 
 def rhs(x: int):
@@ -27,7 +27,7 @@ def rhs(x: int):
     reveal_type(3 - x)  # revealed: int
     reveal_type(3 * x)  # revealed: int
     reveal_type(-3 // x)  # revealed: int
-    reveal_type(-3 / x)  # revealed: float
+    reveal_type(-3 / x)  # revealed: int | float
     reveal_type(5 % x)  # revealed: int
 
 def both(x: int):
@@ -35,7 +35,7 @@ def both(x: int):
     reveal_type(x - x)  # revealed: int
     reveal_type(x * x)  # revealed: int
     reveal_type(x // x)  # revealed: int
-    reveal_type(x / x)  # revealed: float
+    reveal_type(x / x)  # revealed: int | float
     reveal_type(x % x)  # revealed: int
 ```
 
@@ -80,24 +80,20 @@ c = 3 % 0  # error: "Cannot reduce object of type `Literal[3]` modulo zero"
 reveal_type(c)  # revealed: int
 
 # error: "Cannot divide object of type `int` by zero"
-# revealed: float
-reveal_type(int() / 0)
+reveal_type(int() / 0)  # revealed: int | float
 
 # error: "Cannot divide object of type `Literal[1]` by zero"
-# revealed: float
-reveal_type(1 / False)
+reveal_type(1 / False)  # revealed: float
 # error: [division-by-zero] "Cannot divide object of type `Literal[True]` by zero"
 True / False
 # error: [division-by-zero] "Cannot divide object of type `Literal[True]` by zero"
 bool(1) / False
 
 # error: "Cannot divide object of type `float` by zero"
-# revealed: float
-reveal_type(1.0 / 0)
+reveal_type(1.0 / 0)  # revealed: int | float
 
 class MyInt(int): ...
 
 # No error for a subclass of int
-# revealed: float
-reveal_type(MyInt(3) / 0)
+reveal_type(MyInt(3) / 0)  # revealed: int | float
 ```

crates/red_knot_python_semantic/resources/mdtest/boundness_declaredness/public.md

@@ -1,6 +1,6 @@
 # Boundness and declaredness: public uses
 
-This document demonstrates how type-inference and diagnostics works for *public* uses of a symbol,
+This document demonstrates how type-inference and diagnostics work for *public* uses of a symbol,
 that is, a use of a symbol from another scope. If a symbol has a declared type in its local scope
 (e.g. `int`), we use that as the symbol's "public type" (the type of the symbol from the perspective
 of other scopes) even if there is a more precise local inferred type for the symbol (`Literal[1]`).
@@ -34,20 +34,28 @@ In particular, we should raise errors in the "possibly-undeclared-and-unbound" a
 ### Declared and bound
 
 If a symbol has a declared type (`int`), we use that even if there is a more precise inferred type
-(`Literal[1]`), or a conflicting inferred type (`Literal[2]`):
+(`Literal[1]`), or a conflicting inferred type (`str` vs. `Literal[2]` below):
 
-```py path=mod.py
-x: int = 1
+`mod.py`:
 
-# error: [invalid-assignment]
-y: str = 2
+```py
+from typing import Any
+
+def any() -> Any: ...
+
+a: int = 1
+b: str = 2  # error: [invalid-assignment]
+c: Any = 3
+d: int = any()
 ```
 
 ```py
-from mod import x, y
+from mod import a, b, c, d
 
-reveal_type(x)  # revealed: int
-reveal_type(y)  # revealed: str
+reveal_type(a)  # revealed: int
+reveal_type(b)  # revealed: str
+reveal_type(c)  # revealed: Any
+reveal_type(d)  # revealed: int
 ```
 
 ### Declared and possibly unbound
@@ -55,22 +63,33 @@ reveal_type(y)  # revealed: str
 If a symbol is declared and *possibly* unbound, we trust that other module and use the declared type
 without raising an error.
 
-```py path=mod.py
+`mod.py`:
+
+```py
+from typing import Any
+
+def any() -> Any: ...
 def flag() -> bool: ...
 
-x: int
-y: str
+a: int
+b: str
+c: Any
+d: int
+
 if flag:
-    x = 1
-    # error: [invalid-assignment]
-    y = 2
+    a = 1
+    b = 2  # error: [invalid-assignment]
+    c = 3
+    d = any()
 ```
 
 ```py
-from mod import x, y
+from mod import a, b, c, d
 
-reveal_type(x)  # revealed: int
-reveal_type(y)  # revealed: str
+reveal_type(a)  # revealed: int
+reveal_type(b)  # revealed: str
+reveal_type(c)  # revealed: Any
+reveal_type(d)  # revealed: int
 ```
 
 ### Declared and unbound
@@ -78,14 +97,20 @@ reveal_type(y)  # revealed: str
 Similarly, if a symbol is declared but unbound, we do not raise an error. We trust that this symbol
 is available somehow and simply use the declared type.
 
-```py path=mod.py
-x: int
+`mod.py`:
+
+```py
+from typing import Any
+
+a: int
+b: Any
 ```
 
 ```py
-from mod import x
+from mod import a, b
 
-reveal_type(x)  # revealed: int
+reveal_type(a)  # revealed: int
+reveal_type(b)  # revealed: Any
 ```
 
 ## Possibly undeclared
@@ -95,61 +120,70 @@ reveal_type(x)  # revealed: int
 If a symbol is possibly undeclared but definitely bound, we use the union of the declared and
 inferred types:
 
-```py path=mod.py
+`mod.py`:
+
+```py
 from typing import Any
 
+def any() -> Any: ...
 def flag() -> bool: ...
 
-x = 1
-y = 2
-z = 3
+a = 1
+b = 2
+c = 3
+d = any()
 if flag():
-    x: int
-    y: Any
-    # error: [invalid-declaration]
-    z: str
+    a: int
+    b: Any
+    c: str  # error: [invalid-declaration]
+    d: int
 ```
 
 ```py
-from mod import x, y, z
+from mod import a, b, c, d
 
-reveal_type(x)  # revealed: int
-reveal_type(y)  # revealed: Literal[2] | Any
-reveal_type(z)  # revealed: Literal[3] | Unknown
+reveal_type(a)  # revealed: int
+reveal_type(b)  # revealed: Literal[2] | Any
+reveal_type(c)  # revealed: Literal[3] | Unknown
+reveal_type(d)  # revealed: Any | int
 
-# External modifications of `x` that violate the declared type are not allowed:
+# External modifications of `a` that violate the declared type are not allowed:
 # error: [invalid-assignment]
-x = None
+a = None
 ```
 
 ### Possibly undeclared and possibly unbound
 
 If a symbol is possibly undeclared and possibly unbound, we also use the union of the declared and
 inferred types. This case is interesting because the "possibly declared" definition might not be the
-same as the "possibly bound" definition (symbol `y`). Note that we raise a `possibly-unbound-import`
-error for both `x` and `y`:
+same as the "possibly bound" definition (symbol `b`). Note that we raise a `possibly-unbound-import`
+error for both `a` and `b`:
+
+`mod.py`:
+
+```py
+from typing import Any
 
-```py path=mod.py
 def flag() -> bool: ...
 
 if flag():
-    x: Any = 1
-    y = 2
+    a: Any = 1
+    b = 2
 else:
-    y: str
+    b: str
 ```
 
 ```py
 # error: [possibly-unbound-import]
 # error: [possibly-unbound-import]
-from mod import x, y
+from mod import a, b
 
-reveal_type(x)  # revealed: Literal[1] | Any
-reveal_type(y)  # revealed: Literal[2] | str
+reveal_type(a)  # revealed: Literal[1] | Any
+reveal_type(b)  # revealed: Literal[2] | str
 
-# External modifications of `y` that violate the declared type are not allowed:
+# External modifications of `b` that violate the declared type are not allowed:
 # error: [invalid-assignment]
-y = None
+b = None
 ```
 
 ### Possibly undeclared and unbound
@@ -157,40 +191,53 @@ y = None
 If a symbol is possibly undeclared and definitely unbound, we currently do not raise an error. This
 seems inconsistent when compared to the case just above.
 
-```py path=mod.py
+`mod.py`:
+
+```py
 def flag() -> bool: ...
 
 if flag():
-    x: int
+    a: int
 ```
 
 ```py
 # TODO: this should raise an error. Once we fix this, update the section description and the table
 # on top of this document.
-from mod import x
+from mod import a
 
-reveal_type(x)  # revealed: int
+reveal_type(a)  # revealed: int
 
-# External modifications to `x` that violate the declared type are not allowed:
+# External modifications to `a` that violate the declared type are not allowed:
 # error: [invalid-assignment]
-x = None
+a = None
 ```
 
 ## Undeclared
 
 ### Undeclared but bound
 
-```py path=mod.py
-x = 1
+If a symbol is *undeclared*, we use the union of `Unknown` with the inferred type. Note that we
+treat this case differently from the case where a symbol is implicitly declared with `Unknown`,
+possibly due to the usage of an unknown name in the annotation:
+
+`mod.py`:
+
+```py
+# Undeclared:
+a = 1
+
+# Implicitly declared with `Unknown`, due to the usage of an unknown name in the annotation:
+b: SomeUnknownName = 1  # error: [unresolved-reference]
 ```
 
 ```py
-from mod import x
+from mod import a, b
 
-reveal_type(x)  # revealed: Unknown | Literal[1]
+reveal_type(a)  # revealed: Unknown | Literal[1]
+reveal_type(b)  # revealed: Unknown
 
-# All external modifications of `x` are allowed:
-x = None
+# All external modifications of `a` are allowed:
+a = None
 ```
 
 ### Undeclared and possibly unbound
@@ -198,39 +245,45 @@ x = None
 If a symbol is undeclared and *possibly* unbound, we currently do not raise an error. This seems
 inconsistent when compared to the "possibly-undeclared-and-possibly-unbound" case.
 
-```py path=mod.py
+`mod.py`:
+
+```py
 def flag() -> bool: ...
 
 if flag:
-    x = 1
+    a = 1
+    b: SomeUnknownName = 1  # error: [unresolved-reference]
 ```
 
 ```py
 # TODO: this should raise an error. Once we fix this, update the section description and the table
 # on top of this document.
-from mod import x
+from mod import a, b
 
-reveal_type(x)  # revealed: Unknown | Literal[1]
+reveal_type(a)  # revealed: Unknown | Literal[1]
+reveal_type(b)  # revealed: Unknown
 
-# All external modifications of `x` are allowed:
-x = None
+# All external modifications of `a` are allowed:
+a = None
 ```
 
 ### Undeclared and unbound
 
 If a symbol is undeclared *and* unbound, we infer `Unknown` and raise an error.
 
-```py path=mod.py
+`mod.py`:
+
+```py
 if False:
-    x: int = 1
+    a: int = 1
 ```
 
 ```py
 # error: [unresolved-import]
-from mod import x
+from mod import a
 
-reveal_type(x)  # revealed: Unknown
+reveal_type(a)  # revealed: Unknown
 
 # Modifications allowed in this case:
-x = None
+a = None
 ```

crates/red_knot_python_semantic/resources/mdtest/call/callable_instance.md

@@ -4,14 +4,14 @@
 
 ```py
 class Multiplier:
-    def __init__(self, factor: float):
+    def __init__(self, factor: int):
         self.factor = factor
 
-    def __call__(self, number: float) -> float:
+    def __call__(self, number: int) -> int:
         return number * self.factor
 
-a = Multiplier(2.0)(3.0)
-reveal_type(a)  # revealed: float
+a = Multiplier(2)(3)
+reveal_type(a)  # revealed: int
 
 class Unit: ...
 
@@ -52,7 +52,7 @@ class NonCallable:
     __call__ = 1
 
 a = NonCallable()
-# error: "Object of type `Unknown | Literal[1]` is not callable (due to union element `Literal[1]`)"
+# error: [call-non-callable] "Object of type `Literal[1]` is not callable"
 reveal_type(a())  # revealed: Unknown
 ```
 
@@ -67,8 +67,8 @@ def _(flag: bool):
             def __call__(self) -> int: ...
 
     a = NonCallable()
-    # error: "Object of type `Literal[1] | Literal[__call__]` is not callable (due to union element `Literal[1]`)"
-    reveal_type(a())  # revealed: Unknown | int
+    # error: [call-non-callable] "Object of type `Literal[1]` is not callable"
+    reveal_type(a())  # revealed: int | Unknown
 ```
 
 ## Call binding errors
@@ -99,3 +99,26 @@ c = C()
 # error: 13 [invalid-argument-type] "Object of type `C` cannot be assigned to parameter 1 (`self`) of function `__call__`; expected type `int`"
 reveal_type(c())  # revealed: int
 ```
+
+## Union over callables
+
+### Possibly unbound `__call__`
+
+```py
+def outer(cond1: bool):
+    class Test:
+        if cond1:
+            def __call__(self): ...
+
+    class Other:
+        def __call__(self): ...
+
+    def inner(cond2: bool):
+        if cond2:
+            a = Test()
+        else:
+            a = Other()
+
+            # error: [call-non-callable] "Object of type `Test` is not callable (possibly unbound `__call__` method)"
+        a()
+```

crates/red_knot_python_semantic/resources/mdtest/call/function.md

@@ -278,10 +278,10 @@ proper diagnostics in case of missing or superfluous arguments.
 from typing_extensions import reveal_type
 
 # error: [missing-argument] "No argument provided for required parameter `obj` of function `reveal_type`"
-reveal_type()  # revealed: Unknown
+reveal_type()
 
 # error: [too-many-positional-arguments] "Too many positional arguments to function `reveal_type`: expected 1, got 2"
-reveal_type(1, 2)  # revealed: Literal[1]
+reveal_type(1, 2)
 ```
 
 ### `static_assert`
@@ -290,7 +290,6 @@ reveal_type(1, 2)  # revealed: Literal[1]
 from knot_extensions import static_assert
 
 # error: [missing-argument] "No argument provided for required parameter `condition` of function `static_assert`"
-# error: [static-assert-error]
 static_assert()
 
 # error: [too-many-positional-arguments] "Too many positional arguments to function `static_assert`: expected 2, got 3"

crates/red_knot_python_semantic/resources/mdtest/call/getattr_static.md

@@ -0,0 +1,133 @@
+# `inspect.getattr_static`
+
+## Basic usage
+
+`inspect.getattr_static` is a function that returns attributes of an object without invoking the
+descriptor protocol (for caveats, see the [official documentation]).
+
+Consider the following example:
+
+```py
+import inspect
+
+class Descriptor:
+    def __get__(self, instance, owner) -> str:
+        return 1
+
+class C:
+    normal: int = 1
+    descriptor: Descriptor = Descriptor()
+```
+
+If we access attributes on an instance of `C` as usual, the descriptor protocol is invoked, and we
+get a type of `str` for the `descriptor` attribute:
+
+```py
+c = C()
+
+reveal_type(c.normal)  # revealed: int
+reveal_type(c.descriptor)  # revealed: str
+```
+
+However, if we use `inspect.getattr_static`, we can see the underlying `Descriptor` type:
+
+```py
+reveal_type(inspect.getattr_static(c, "normal"))  # revealed: int
+reveal_type(inspect.getattr_static(c, "descriptor"))  # revealed: Descriptor
+```
+
+For non-existent attributes, a default value can be provided:
+
+```py
+reveal_type(inspect.getattr_static(C, "normal", "default-arg"))  # revealed: int
+reveal_type(inspect.getattr_static(C, "non_existent", "default-arg"))  # revealed: Literal["default-arg"]
+```
+
+When a non-existent attribute is accessed without a default value, the runtime raises an
+`AttributeError`. We could emit a diagnostic for this case, but that is currently not supported:
+
+```py
+# TODO: we could emit a diagnostic here
+reveal_type(inspect.getattr_static(C, "non_existent"))  # revealed: Never
+```
+
+We can access attributes on objects of all kinds:
+
+```py
+import sys
+
+reveal_type(inspect.getattr_static(sys, "platform"))  # revealed: LiteralString
+reveal_type(inspect.getattr_static(inspect, "getattr_static"))  # revealed: Literal[getattr_static]
+
+reveal_type(inspect.getattr_static(1, "real"))  # revealed: Literal[1]
+```
+
+(Implicit) instance attributes can also be accessed through `inspect.getattr_static`:
+
+```py
+class D:
+    def __init__(self) -> None:
+        self.instance_attr: int = 1
+
+reveal_type(inspect.getattr_static(D(), "instance_attr"))  # revealed: int
+```
+
+## Error cases
+
+We can only infer precise types if the attribute is a literal string. In all other cases, we fall
+back to `Any`:
+
+```py
+import inspect
+
+class C:
+    x: int = 1
+
+def _(attr_name: str):
+    reveal_type(inspect.getattr_static(C(), attr_name))  # revealed: Any
+    reveal_type(inspect.getattr_static(C(), attr_name, 1))  # revealed: Any
+```
+
+But we still detect errors in the number or type of arguments:
+
+```py
+# error: [missing-argument] "No arguments provided for required parameters `obj`, `attr` of function `getattr_static`"
+inspect.getattr_static()
+
+# error: [missing-argument] "No argument provided for required parameter `attr`"
+inspect.getattr_static(C())
+
+# error: [invalid-argument-type] "Object of type `Literal[1]` cannot be assigned to parameter 2 (`attr`) of function `getattr_static`; expected type `str`"
+inspect.getattr_static(C(), 1)
+
+# error: [too-many-positional-arguments] "Too many positional arguments to function `getattr_static`: expected 3, got 4"
+inspect.getattr_static(C(), "x", "default-arg", "one too many")
+```
+
+## Possibly unbound attributes
+
+```py
+import inspect
+
+def _(flag: bool):
+    class C:
+        if flag:
+            x: int = 1
+
+    reveal_type(inspect.getattr_static(C, "x", "default"))  # revealed: int | Literal["default"]
+```
+
+## Gradual types
+
+```py
+import inspect
+from typing import Any
+
+def _(a: Any, tuple_of_any: tuple[Any]):
+    reveal_type(inspect.getattr_static(a, "x", "default"))  # revealed: Any | Literal["default"]
+
+    # TODO: Ideally, this would just be `Literal[index]`
+    reveal_type(inspect.getattr_static(tuple_of_any, "index", "default"))  # revealed: Literal[index] | Literal["default"]
+```
+
+[official documentation]: https://docs.python.org/3/library/inspect.html#inspect.getattr_static

crates/red_knot_python_semantic/resources/mdtest/call/methods.md

@@ -0,0 +1,258 @@
+# Methods
+
+## Background: Functions as descriptors
+
+> Note: See also this related section in the descriptor guide: [Functions and methods].
+
+Say we have a simple class `C` with a function definition `f` inside its body:
+
+```py
+class C:
+    def f(self, x: int) -> str:
+        return "a"
+```
+
+Whenever we access the `f` attribute through the class object itself (`C.f`) or through an instance
+(`C().f`), this access happens via the descriptor protocol. Functions are (non-data) descriptors
+because they implement a `__get__` method. This is crucial in making sure that method calls work as
+expected. In general, the signature of the `__get__` method in the descriptor protocol is
+`__get__(self, instance, owner)`. The `self` argument is the descriptor object itself (`f`). The
+passed value for the `instance` argument depends on whether the attribute is accessed from the class
+object (in which case it is `None`), or from an instance (in which case it is the instance of type
+`C`). The `owner` argument is the class itself (`C` of type `Literal[C]`). To summarize:
+
+- `C.f` is equivalent to `getattr_static(C, "f").__get__(None, C)`
+- `C().f` is equivalent to `getattr_static(C, "f").__get__(C(), C)`
+
+Here, `inspect.getattr_static` is used to bypass the descriptor protocol and directly access the
+function attribute. The way the special `__get__` method *on functions* works is as follows. In the
+former case, if the `instance` argument is `None`, `__get__` simply returns the function itself. In
+the latter case, it returns a *bound method* object:
+
+```py
+from inspect import getattr_static
+
+reveal_type(getattr_static(C, "f"))  # revealed: Literal[f]
+
+reveal_type(getattr_static(C, "f").__get__)  # revealed: <method-wrapper `__get__` of `f`>
+
+reveal_type(getattr_static(C, "f").__get__(None, C))  # revealed: Literal[f]
+reveal_type(getattr_static(C, "f").__get__(C(), C))  # revealed: <bound method `f` of `C`>
+```
+
+In conclusion, this is why we see the following two types when accessing the `f` attribute on the
+class object `C` and on an instance `C()`:
+
+```py
+reveal_type(C.f)  # revealed: Literal[f]
+reveal_type(C().f)  # revealed: <bound method `f` of `C`>
+```
+
+A bound method is a callable object that contains a reference to the `instance` that it was called
+on (can be inspected via `__self__`), and the function object that it refers to (can be inspected
+via `__func__`):
+
+```py
+bound_method = C().f
+
+reveal_type(bound_method.__self__)  # revealed: C
+reveal_type(bound_method.__func__)  # revealed: Literal[f]
+```
+
+When we call the bound method, the `instance` is implicitly passed as the first argument (`self`):
+
+```py
+reveal_type(C().f(1))  # revealed: str
+reveal_type(bound_method(1))  # revealed: str
+```
+
+When we call the function object itself, we need to pass the `instance` explicitly:
+
+```py
+C.f(1)  # error: [missing-argument]
+
+reveal_type(C.f(C(), 1))  # revealed: str
+```
+
+When we access methods from derived classes, they will be bound to instances of the derived class:
+
+```py
+class D(C):
+    pass
+
+reveal_type(D().f)  # revealed: <bound method `f` of `D`>
+```
+
+If we access an attribute on a bound method object itself, it will defer to `types.MethodType`:
+
+```py
+reveal_type(bound_method.__hash__)  # revealed: <bound method `__hash__` of `MethodType`>
+```
+
+If an attribute is not available on the bound method object, it will be looked up on the underlying
+function object. We model this explicitly, which means that we can access `__kwdefaults__` on bound
+methods, even though it is not available on `types.MethodType`:
+
+```py
+reveal_type(bound_method.__kwdefaults__)  # revealed: @Todo(generics) | None
+```
+
+## Basic method calls on class objects and instances
+
+```py
+class Base:
+    def method_on_base(self, x: int | None) -> str:
+        return "a"
+
+class Derived(Base):
+    def method_on_derived(self, x: bytes) -> tuple[int, str]:
+        return (1, "a")
+
+reveal_type(Base().method_on_base(1))  # revealed: str
+reveal_type(Base.method_on_base(Base(), 1))  # revealed: str
+
+Base().method_on_base("incorrect")  # error: [invalid-argument-type]
+Base().method_on_base()  # error: [missing-argument]
+Base().method_on_base(1, 2)  # error: [too-many-positional-arguments]
+
+reveal_type(Derived().method_on_base(1))  # revealed: str
+reveal_type(Derived().method_on_derived(b"abc"))  # revealed: tuple[int, str]
+reveal_type(Derived.method_on_base(Derived(), 1))  # revealed: str
+reveal_type(Derived.method_on_derived(Derived(), b"abc"))  # revealed: tuple[int, str]
+```
+
+## Method calls on literals
+
+### Boolean literals
+
+```py
+reveal_type(True.bit_length())  # revealed: int
+reveal_type(True.as_integer_ratio())  # revealed: tuple[int, Literal[1]]
+```
+
+### Integer literals
+
+```py
+reveal_type((42).bit_length())  # revealed: int
+```
+
+### String literals
+
+```py
+reveal_type("abcde".find("abc"))  # revealed: int
+reveal_type("foo".encode(encoding="utf-8"))  # revealed: bytes
+
+"abcde".find(123)  # error: [invalid-argument-type]
+```
+
+### Bytes literals
+
+```py
+reveal_type(b"abcde".startswith(b"abc"))  # revealed: bool
+```
+
+## Method calls on `LiteralString`
+
+```py
+from typing_extensions import LiteralString
+
+def f(s: LiteralString) -> None:
+    reveal_type(s.find("a"))  # revealed: int
+```
+
+## Method calls on `tuple`
+
+```py
+def f(t: tuple[int, str]) -> None:
+    reveal_type(t.index("a"))  # revealed: int
+```
+
+## Method calls on unions
+
+```py
+from typing import Any
+
+class A:
+    def f(self) -> int:
+        return 1
+
+class B:
+    def f(self) -> str:
+        return "a"
+
+def f(a_or_b: A | B, any_or_a: Any | A):
+    reveal_type(a_or_b.f)  # revealed: <bound method `f` of `A`> | <bound method `f` of `B`>
+    reveal_type(a_or_b.f())  # revealed: int | str
+
+    reveal_type(any_or_a.f)  # revealed: Any | <bound method `f` of `A`>
+    reveal_type(any_or_a.f())  # revealed: Any | int
+```
+
+## Method calls on `KnownInstance` types
+
+```toml
+[environment]
+python-version = "3.12"
+```
+
+```py
+type IntOrStr = int | str
+
+reveal_type(IntOrStr.__or__)  # revealed: <bound method `__or__` of `typing.TypeAliasType`>
+```
+
+## Error cases: Calling `__get__` for methods
+
+The `__get__` method on `types.FunctionType` has the following overloaded signature in typeshed:
+
+```py
+from types import FunctionType, MethodType
+from typing import overload
+
+@overload
+def __get__(self, instance: None, owner: type, /) -> FunctionType: ...
+@overload
+def __get__(self, instance: object, owner: type | None = None, /) -> MethodType: ...
+```
+
+Here, we test that this signature is enforced correctly:
+
+```py
+from inspect import getattr_static
+
+class C:
+    def f(self, x: int) -> str:
+        return "a"
+
+method_wrapper = getattr_static(C, "f").__get__
+
+reveal_type(method_wrapper)  # revealed: <method-wrapper `__get__` of `f`>
+
+# All of these are fine:
+method_wrapper(C(), C)
+method_wrapper(C())
+method_wrapper(C(), None)
+method_wrapper(None, C)
+
+# Passing `None` without an `owner` argument is an
+# error: [missing-argument] "No argument provided for required parameter `owner`"
+method_wrapper(None)
+
+# Passing something that is not assignable to `type` as the `owner` argument is an
+# error: [invalid-argument-type] "Object of type `Literal[1]` cannot be assigned to parameter 2 (`owner`); expected type `type`"
+method_wrapper(None, 1)
+
+# Passing `None` as the `owner` argument when `instance` is `None` is an
+# error: [invalid-argument-type] "Object of type `None` cannot be assigned to parameter 2 (`owner`); expected type `type`"
+method_wrapper(None, None)
+
+# Calling `__get__` without any arguments is an
+# error: [missing-argument] "No argument provided for required parameter `instance`"
+method_wrapper()
+
+# Calling `__get__` with too many positional arguments is an
+# error: [too-many-positional-arguments] "Too many positional arguments: expected 2, got 3"
+method_wrapper(C(), C, "one too many")
+```
+
+[functions and methods]: https://docs.python.org/3/howto/descriptor.html#functions-and-methods

crates/red_knot_python_semantic/resources/mdtest/call/union.md

@@ -39,8 +39,8 @@ def _(flag: bool):
     else:
         def f() -> int:
             return 1
-    x = f()  # error: "Object of type `Literal[1] | Literal[f]` is not callable (due to union element `Literal[1]`)"
-    reveal_type(x)  # revealed: Unknown | int
+    x = f()  # error: [call-non-callable] "Object of type `Literal[1]` is not callable"
+    reveal_type(x)  # revealed: int | Unknown
 ```
 
 ## Multiple non-callable elements in a union
@@ -56,8 +56,8 @@ def _(flag: bool, flag2: bool):
     else:
         def f() -> int:
             return 1
-    # error: "Object of type `Literal[1, "foo"] | Literal[f]` is not callable (due to union elements Literal[1], Literal["foo"])"
-    # revealed: Unknown | int
+    # error: [call-non-callable] "Object of type `Literal[1]` is not callable"
+    # revealed: int | Unknown
     reveal_type(f())
 ```
 
@@ -72,6 +72,39 @@ def _(flag: bool):
     else:
         f = "foo"
 
-    x = f()  # error: "Object of type `Literal[1, "foo"]` is not callable"
+    x = f()  # error: [call-non-callable] "Object of type `Literal[1, "foo"]` is not callable"
+    reveal_type(x)  # revealed: Unknown
+```
+
+## Mismatching signatures
+
+Calling a union where the arguments don't match the signature of all variants.
+
+```py
+def f1(a: int) -> int: ...
+def f2(a: str) -> str: ...
+def _(flag: bool):
+    if flag:
+        f = f1
+    else:
+        f = f2
+
+    # error: [invalid-argument-type] "Object of type `Literal[3]` cannot be assigned to parameter 1 (`a`) of function `f2`; expected type `str`"
+    x = f(3)
+    reveal_type(x)  # revealed: int | str
+```
+
+## Any non-callable variant
+
+```py
+def f1(a: int): ...
+def _(flag: bool):
+    if flag:
+        f = f1
+    else:
+        f = "This is a string literal"
+
+    # error: [call-non-callable] "Object of type `Literal["This is a string literal"]` is not callable"
+    x = f(3)
     reveal_type(x)  # revealed: Unknown
 ```

crates/red_knot_python_semantic/resources/mdtest/comparison/instances/membership_test.md

@@ -21,8 +21,9 @@ class A:
 
 reveal_type("hello" in A())  # revealed: bool
 reveal_type("hello" not in A())  # revealed: bool
-# TODO: should emit diagnostic, need to check arg type, will fail
+# error: [unsupported-operator] "Operator `in` is not supported for types `int` and `A`, in comparing `Literal[42]` with `A`"
 reveal_type(42 in A())  # revealed: bool
+# error: [unsupported-operator] "Operator `not in` is not supported for types `int` and `A`, in comparing `Literal[42]` with `A`"
 reveal_type(42 not in A())  # revealed: bool
 ```
 
@@ -126,9 +127,9 @@ class A:
 
 reveal_type(CheckContains() in A())  # revealed: bool
 
-# TODO: should emit diagnostic, need to check arg type,
-# should not fall back to __iter__ or __getitem__
+# error: [unsupported-operator] "Operator `in` is not supported for types `CheckIter` and `A`"
 reveal_type(CheckIter() in A())  # revealed: bool
+# error: [unsupported-operator] "Operator `in` is not supported for types `CheckGetItem` and `A`"
 reveal_type(CheckGetItem() in A())  # revealed: bool
 
 class B:
@@ -154,7 +155,8 @@ class A:
     def __getitem__(self, key: str) -> str:
         return "foo"
 
-# TODO should emit a diagnostic
+# error: [unsupported-operator] "Operator `in` is not supported for types `int` and `A`, in comparing `Literal[42]` with `A`"
 reveal_type(42 in A())  # revealed: bool
+# error: [unsupported-operator] "Operator `in` is not supported for types `str` and `A`, in comparing `Literal["hello"]` with `A`"
 reveal_type("hello" in A())  # revealed: bool
 ```

crates/red_knot_python_semantic/resources/mdtest/comparison/instances/rich_comparison.md

@@ -16,31 +16,38 @@ most common case involves implementing these methods for the same type:
 ```py
 from __future__ import annotations
 
+class EqReturnType: ...
+class NeReturnType: ...
+class LtReturnType: ...
+class LeReturnType: ...
+class GtReturnType: ...
+class GeReturnType: ...
+
 class A:
-    def __eq__(self, other: A) -> int:
-        return 42
+    def __eq__(self, other: A) -> EqReturnType:
+        return EqReturnType()
 
-    def __ne__(self, other: A) -> float:
-        return 42.0
+    def __ne__(self, other: A) -> NeReturnType:
+        return NeReturnType()
 
-    def __lt__(self, other: A) -> str:
-        return "42"
+    def __lt__(self, other: A) -> LtReturnType:
+        return LtReturnType()
 
-    def __le__(self, other: A) -> bytes:
-        return b"42"
+    def __le__(self, other: A) -> LeReturnType:
+        return LeReturnType()
 
-    def __gt__(self, other: A) -> list:
-        return [42]
+    def __gt__(self, other: A) -> GtReturnType:
+        return GtReturnType()
 
-    def __ge__(self, other: A) -> set:
-        return {42}
+    def __ge__(self, other: A) -> GeReturnType:
+        return GeReturnType()
 
-reveal_type(A() == A())  # revealed: int
-reveal_type(A() != A())  # revealed: float
-reveal_type(A() < A())  # revealed: str
-reveal_type(A() <= A())  # revealed: bytes
-reveal_type(A() > A())  # revealed: list
-reveal_type(A() >= A())  # revealed: set
+reveal_type(A() == A())  # revealed: EqReturnType
+reveal_type(A() != A())  # revealed: NeReturnType
+reveal_type(A() < A())  # revealed: LtReturnType
+reveal_type(A() <= A())  # revealed: LeReturnType
+reveal_type(A() > A())  # revealed: GtReturnType
+reveal_type(A() >= A())  # revealed: GeReturnType
 ```
 
 ## Rich Comparison Dunder Implementations for Other Class
@@ -51,33 +58,40 @@ type:
 ```py
 from __future__ import annotations
 
+class EqReturnType: ...
+class NeReturnType: ...
+class LtReturnType: ...
+class LeReturnType: ...
+class GtReturnType: ...
+class GeReturnType: ...
+
 class A:
-    def __eq__(self, other: B) -> int:
-        return 42
+    def __eq__(self, other: B) -> EqReturnType:
+        return EqReturnType()
 
-    def __ne__(self, other: B) -> float:
-        return 42.0
+    def __ne__(self, other: B) -> NeReturnType:
+        return NeReturnType()
 
-    def __lt__(self, other: B) -> str:
-        return "42"
+    def __lt__(self, other: B) -> LtReturnType:
+        return LtReturnType()
 
-    def __le__(self, other: B) -> bytes:
-        return b"42"
+    def __le__(self, other: B) -> LeReturnType:
+        return LeReturnType()
 
-    def __gt__(self, other: B) -> list:
-        return [42]
+    def __gt__(self, other: B) -> GtReturnType:
+        return GtReturnType()
 
-    def __ge__(self, other: B) -> set:
-        return {42}
+    def __ge__(self, other: B) -> GeReturnType:
+        return GeReturnType()
 
 class B: ...
 
-reveal_type(A() == B())  # revealed: int
-reveal_type(A() != B())  # revealed: float
-reveal_type(A() < B())  # revealed: str
-reveal_type(A() <= B())  # revealed: bytes
-reveal_type(A() > B())  # revealed: list
-reveal_type(A() >= B())  # revealed: set
+reveal_type(A() == B())  # revealed: EqReturnType
+reveal_type(A() != B())  # revealed: NeReturnType
+reveal_type(A() < B())  # revealed: LtReturnType
+reveal_type(A() <= B())  # revealed: LeReturnType
+reveal_type(A() > B())  # revealed: GtReturnType
+reveal_type(A() >= B())  # revealed: GeReturnType
 ```
 
 ## Reflected Comparisons
@@ -89,58 +103,64 @@ these methods will be ignored here because they require a mismatched operand typ
 ```py
 from __future__ import annotations
 
+class EqReturnType: ...
+class NeReturnType: ...
+class LtReturnType: ...
+class LeReturnType: ...
+class GtReturnType: ...
+class GeReturnType: ...
+
 class A:
-    def __eq__(self, other: B) -> int:
-        return 42
+    def __eq__(self, other: B) -> EqReturnType:
+        return EqReturnType()
 
-    def __ne__(self, other: B) -> float:
-        return 42.0
+    def __ne__(self, other: B) -> NeReturnType:
+        return NeReturnType()
 
-    def __lt__(self, other: B) -> str:
-        return "42"
+    def __lt__(self, other: B) -> LtReturnType:
+        return LtReturnType()
 
-    def __le__(self, other: B) -> bytes:
-        return b"42"
+    def __le__(self, other: B) -> LeReturnType:
+        return LeReturnType()
 
-    def __gt__(self, other: B) -> list:
-        return [42]
+    def __gt__(self, other: B) -> GtReturnType:
+        return GtReturnType()
 
-    def __ge__(self, other: B) -> set:
-        return {42}
+    def __ge__(self, other: B) -> GeReturnType:
+        return GeReturnType()
+
+class Unrelated: ...
 
 class B:
     # To override builtins.object.__eq__ and builtins.object.__ne__
     # TODO these should emit an invalid override diagnostic
-    def __eq__(self, other: str) -> B:
+    def __eq__(self, other: Unrelated) -> B:
         return B()
 
-    def __ne__(self, other: str) -> B:
+    def __ne__(self, other: Unrelated) -> B:
         return B()
 
-# TODO: should be `int` and `float`.
-# Need to check arg type and fall back to `rhs.__eq__` and `rhs.__ne__`.
-#
 # Because `object.__eq__` and `object.__ne__` accept `object` in typeshed,
 # this can only happen with an invalid override of these methods,
 # but we still support it.
-reveal_type(B() == A())  # revealed: B
-reveal_type(B() != A())  # revealed: B
+reveal_type(B() == A())  # revealed: EqReturnType
+reveal_type(B() != A())  # revealed: NeReturnType
 
-reveal_type(B() < A())  # revealed: list
-reveal_type(B() <= A())  # revealed: set
+reveal_type(B() < A())  # revealed: GtReturnType
+reveal_type(B() <= A())  # revealed: GeReturnType
 
-reveal_type(B() > A())  # revealed: str
-reveal_type(B() >= A())  # revealed: bytes
+reveal_type(B() > A())  # revealed: LtReturnType
+reveal_type(B() >= A())  # revealed: LeReturnType
 
 class C:
-    def __gt__(self, other: C) -> int:
+    def __gt__(self, other: C) -> EqReturnType:
         return 42
 
-    def __ge__(self, other: C) -> float:
-        return 42.0
+    def __ge__(self, other: C) -> NeReturnType:
+        return NeReturnType()
 
-reveal_type(C() < C())  # revealed: int
-reveal_type(C() <= C())  # revealed: float
+reveal_type(C() < C())  # revealed: EqReturnType
+reveal_type(C() <= C())  # revealed: NeReturnType
 ```
 
 ## Reflected Comparisons with Subclasses
@@ -152,6 +172,13 @@ than `A`.
 ```py
 from __future__ import annotations
 
+class EqReturnType: ...
+class NeReturnType: ...
+class LtReturnType: ...
+class LeReturnType: ...
+class GtReturnType: ...
+class GeReturnType: ...
+
 class A:
     def __eq__(self, other: A) -> A:
         return A()
@@ -172,32 +199,32 @@ class A:
         return A()
 
 class B(A):
-    def __eq__(self, other: A) -> int:
-        return 42
+    def __eq__(self, other: A) -> EqReturnType:
+        return EqReturnType()
 
-    def __ne__(self, other: A) -> float:
-        return 42.0
+    def __ne__(self, other: A) -> NeReturnType:
+        return NeReturnType()
 
-    def __lt__(self, other: A) -> str:
-        return "42"
+    def __lt__(self, other: A) -> LtReturnType:
+        return LtReturnType()
 
-    def __le__(self, other: A) -> bytes:
-        return b"42"
+    def __le__(self, other: A) -> LeReturnType:
+        return LeReturnType()
 
-    def __gt__(self, other: A) -> list:
-        return [42]
+    def __gt__(self, other: A) -> GtReturnType:
+        return GtReturnType()
 
-    def __ge__(self, other: A) -> set:
-        return {42}
+    def __ge__(self, other: A) -> GeReturnType:
+        return GeReturnType()
 
-reveal_type(A() == B())  # revealed: int
-reveal_type(A() != B())  # revealed: float
+reveal_type(A() == B())  # revealed: EqReturnType
+reveal_type(A() != B())  # revealed: NeReturnType
 
-reveal_type(A() < B())  # revealed: list
-reveal_type(A() <= B())  # revealed: set
+reveal_type(A() < B())  # revealed: GtReturnType
+reveal_type(A() <= B())  # revealed: GeReturnType
 
-reveal_type(A() > B())  # revealed: str
-reveal_type(A() >= B())  # revealed: bytes
+reveal_type(A() > B())  # revealed: LtReturnType
+reveal_type(A() >= B())  # revealed: LeReturnType
 ```
 
 ## Reflected Comparisons with Subclass But Falls Back to LHS
@@ -222,9 +249,8 @@ class B(A):
     def __gt__(self, other: int) -> B:
         return B()
 
-# TODO: should be `A`, need to check argument type and fall back to LHS method
-reveal_type(A() < B())  # revealed: B
-reveal_type(A() > B())  # revealed: B
+reveal_type(A() < B())  # revealed: A
+reveal_type(A() > B())  # revealed: A
 ```
 
 ## Operations involving instances of classes inheriting from `Any`
@@ -272,9 +298,8 @@ class A:
     def __ne__(self, other: int) -> A:
         return A()
 
-# TODO: it should be `bool`, need to check arg type and fall back to `is` and `is not`
-reveal_type(A() == A())  # revealed: A
-reveal_type(A() != A())  # revealed: A
+reveal_type(A() == A())  # revealed: bool
+reveal_type(A() != A())  # revealed: bool
 ```
 
 ## Object Comparisons with Typeshed
@@ -305,12 +330,14 @@ reveal_type(1 >= 1.0)  # revealed: bool
 reveal_type(1 == 2j)  # revealed: bool
 reveal_type(1 != 2j)  # revealed: bool
 
-# TODO: should be Unknown and emit diagnostic,
-# need to check arg type and should be failed
-reveal_type(1 < 2j)  # revealed: bool
-reveal_type(1 <= 2j)  # revealed: bool
-reveal_type(1 > 2j)  # revealed: bool
-reveal_type(1 >= 2j)  # revealed: bool
+# error: [unsupported-operator] "Operator `<` is not supported for types `int` and `complex`, in comparing `Literal[1]` with `complex`"
+reveal_type(1 < 2j)  # revealed: Unknown
+# error: [unsupported-operator] "Operator `<=` is not supported for types `int` and `complex`, in comparing `Literal[1]` with `complex`"
+reveal_type(1 <= 2j)  # revealed: Unknown
+# error: [unsupported-operator] "Operator `>` is not supported for types `int` and `complex`, in comparing `Literal[1]` with `complex`"
+reveal_type(1 > 2j)  # revealed: Unknown
+# error: [unsupported-operator] "Operator `>=` is not supported for types `int` and `complex`, in comparing `Literal[1]` with `complex`"
+reveal_type(1 >= 2j)  # revealed: Unknown
 
 def f(x: bool, y: int):
     reveal_type(x < y)  # revealed: bool

crates/red_knot_python_semantic/resources/mdtest/comparison/integers.md

@@ -12,8 +12,8 @@ reveal_type(1 is 1)  # revealed: bool
 reveal_type(1 is not 1)  # revealed: bool
 reveal_type(1 is 2)  # revealed: Literal[False]
 reveal_type(1 is not 7)  # revealed: Literal[True]
-# TODO: should be Unknown, and emit diagnostic, once we check call argument types
-reveal_type(1 <= "" and 0 < 1)  # revealed: bool
+# error: [unsupported-operator] "Operator `<=` is not supported for types `int` and `str`, in comparing `Literal[1]` with `Literal[""]`"
+reveal_type(1 <= "" and 0 < 1)  # revealed: Unknown & ~AlwaysTruthy | Literal[True]
 ```
 
 ## Integer instance

crates/red_knot_python_semantic/resources/mdtest/comparison/intersections.md

@@ -6,7 +6,11 @@ If we have an intersection type `A & B` and we get a definitive true/false answe
 types, we can infer that the result for the intersection type is also true/false:
 
 ```py
-class Base: ...
+from typing import Literal
+
+class Base:
+    def __gt__(self, other) -> bool:
+        return False
 
 class Child1(Base):
     def __eq__(self, other) -> Literal[True]:

crates/red_knot_python_semantic/resources/mdtest/comparison/non_bool_returns.md

@@ -23,6 +23,7 @@ from __future__ import annotations
 
 class A:
     def __lt__(self, other) -> A: ...
+    def __gt__(self, other) -> bool: ...
 
 class B:
     def __lt__(self, other) -> B: ...

crates/red_knot_python_semantic/resources/mdtest/comparison/tuples.md

@@ -33,7 +33,7 @@ reveal_type(a >= b)  # revealed: Literal[False]
 
 Even when tuples have different lengths, comparisons should be handled appropriately.
 
-```py path=different_length.py
+```py
 a = (1, 2, 3)
 b = (1, 2, 3, 4)
 
@@ -92,17 +92,20 @@ reveal_type(a == b)  # revealed: bool
 # TODO: should be Literal[True], once we implement (in)equality for mismatched literals
 reveal_type(a != b)  # revealed: bool
 
-# TODO: should be Unknown and add more informative diagnostics
-reveal_type(a < b)  # revealed: bool
-reveal_type(a <= b)  # revealed: bool
-reveal_type(a > b)  # revealed: bool
-reveal_type(a >= b)  # revealed: bool
+# error: [unsupported-operator] "Operator `<` is not supported for types `int` and `str`, in comparing `tuple[Literal[1], Literal[2]]` with `tuple[Literal[1], Literal["hello"]]`"
+reveal_type(a < b)  # revealed: Unknown
+# error: [unsupported-operator] "Operator `<=` is not supported for types `int` and `str`, in comparing `tuple[Literal[1], Literal[2]]` with `tuple[Literal[1], Literal["hello"]]`"
+reveal_type(a <= b)  # revealed: Unknown
+# error: [unsupported-operator] "Operator `>` is not supported for types `int` and `str`, in comparing `tuple[Literal[1], Literal[2]]` with `tuple[Literal[1], Literal["hello"]]`"
+reveal_type(a > b)  # revealed: Unknown
+# error: [unsupported-operator] "Operator `>=` is not supported for types `int` and `str`, in comparing `tuple[Literal[1], Literal[2]]` with `tuple[Literal[1], Literal["hello"]]`"
+reveal_type(a >= b)  # revealed: Unknown
 ```
 
 However, if the lexicographic comparison completes without reaching a point where str and int are
 compared, Python will still produce a result based on the prior elements.
 
-```py path=short_circuit.py
+```py
 a = (1, 2)
 b = (999999, "hello")
 
@@ -144,33 +147,40 @@ of the dunder methods.)
 ```py
 from __future__ import annotations
 
+class EqReturnType: ...
+class NeReturnType: ...
+class LtReturnType: ...
+class LeReturnType: ...
+class GtReturnType: ...
+class GeReturnType: ...
+
 class A:
-    def __eq__(self, o: object) -> str:
-        return "hello"
+    def __eq__(self, o: object) -> EqReturnType:
+        return EqReturnType()
 
-    def __ne__(self, o: object) -> bytes:
-        return b"world"
+    def __ne__(self, o: object) -> NeReturnType:
+        return NeReturnType()
 
-    def __lt__(self, o: A) -> float:
-        return 3.14
+    def __lt__(self, o: A) -> LtReturnType:
+        return LtReturnType()
 
-    def __le__(self, o: A) -> complex:
-        return complex(0.5, -0.5)
+    def __le__(self, o: A) -> LeReturnType:
+        return LeReturnType()
 
-    def __gt__(self, o: A) -> tuple:
-        return (1, 2, 3)
+    def __gt__(self, o: A) -> GtReturnType:
+        return GtReturnType()
 
-    def __ge__(self, o: A) -> list:
-        return [1, 2, 3]
+    def __ge__(self, o: A) -> GeReturnType:
+        return GeReturnType()
 
 a = (A(), A())
 
 reveal_type(a == a)  # revealed: bool
 reveal_type(a != a)  # revealed: bool
-reveal_type(a < a)  # revealed: float | Literal[False]
-reveal_type(a <= a)  # revealed: complex | Literal[True]
-reveal_type(a > a)  # revealed: tuple | Literal[False]
-reveal_type(a >= a)  # revealed: list | Literal[True]
+reveal_type(a < a)  # revealed: LtReturnType | Literal[False]
+reveal_type(a <= a)  # revealed: LeReturnType | Literal[True]
+reveal_type(a > a)  # revealed: GtReturnType | Literal[False]
+reveal_type(a >= a)  # revealed: GeReturnType | Literal[True]
 
 # If lexicographic comparison is finished before comparing A()
 b = ("1_foo", A())
@@ -183,11 +193,13 @@ reveal_type(b <= c)  # revealed: Literal[True]
 reveal_type(b > c)  # revealed: Literal[False]
 reveal_type(b >= c)  # revealed: Literal[False]
 
+class LtReturnTypeOnB: ...
+
 class B:
-    def __lt__(self, o: B) -> set:
+    def __lt__(self, o: B) -> LtReturnTypeOnB:
         return set()
 
-reveal_type((A(), B()) < (A(), B()))  # revealed: float | set | Literal[False]
+reveal_type((A(), B()) < (A(), B()))  # revealed: LtReturnType | LtReturnTypeOnB | Literal[False]
 ```
 
 #### Special Handling of Eq and NotEq in Lexicographic Comparisons

crates/red_knot_python_semantic/resources/mdtest/comparison/unsupported.md

@@ -9,28 +9,22 @@ def _(flag: bool, flag1: bool, flag2: bool):
     b = 0 not in 10  # error: "Operator `not in` is not supported for types `Literal[0]` and `Literal[10]`"
     reveal_type(b)  # revealed: bool
 
-    # TODO: should error, once operand type check is implemented
-    # ("Operator `<` is not supported for types `object` and `int`")
+    # error: [unsupported-operator] "Operator `<` is not supported for types `object` and `int`, in comparing `object` with `Literal[5]`"
     c = object() < 5
-    # TODO: should be Unknown, once operand type check is implemented
-    reveal_type(c)  # revealed: bool
+    reveal_type(c)  # revealed: Unknown
 
-    # TODO: should error, once operand type check is implemented
-    # ("Operator `<` is not supported for types `int` and `object`")
+    # error: [unsupported-operator] "Operator `<` is not supported for types `int` and `object`, in comparing `Literal[5]` with `object`"
     d = 5 < object()
-    # TODO: should be Unknown, once operand type check is implemented
-    reveal_type(d)  # revealed: bool
+    reveal_type(d)  # revealed: Unknown
 
     int_literal_or_str_literal = 1 if flag else "foo"
     # error: "Operator `in` is not supported for types `Literal[42]` and `Literal[1]`, in comparing `Literal[42]` with `Literal[1, "foo"]`"
     e = 42 in int_literal_or_str_literal
     reveal_type(e)  # revealed: bool
 
-    # TODO: should error, need to check if __lt__ signature is valid for right operand
-    # error may be "Operator `<` is not supported for types `int` and `str`, in comparing `tuple[Literal[1], Literal[2]]` with `tuple[Literal[1], Literal["hello"]]`
+    # error: [unsupported-operator] "Operator `<` is not supported for types `int` and `str`, in comparing `tuple[Literal[1], Literal[2]]` with `tuple[Literal[1], Literal["hello"]]`"
     f = (1, 2) < (1, "hello")
-    # TODO: should be Unknown, once operand type check is implemented
-    reveal_type(f)  # revealed: bool
+    reveal_type(f)  # revealed: Unknown
 
     # error: [unsupported-operator] "Operator `<` is not supported for types `A` and `A`, in comparing `tuple[bool, A]` with `tuple[bool, A]`"
     g = (flag1, A()) < (flag2, A())

crates/red_knot_python_semantic/resources/mdtest/comprehensions/basic.md

@@ -43,8 +43,7 @@ class IntIterable:
     def __iter__(self) -> IntIterator:
         return IntIterator()
 
-# TODO: This could be a `tuple[int, int]` if we model that `y` can not be modified in the outer comprehension scope
-# revealed: tuple[int, Unknown | int]
+# revealed: tuple[int, int]
 [[reveal_type((x, y)) for x in IntIterable()] for y in IntIterable()]
 ```
 
@@ -67,8 +66,7 @@ class IterableOfIterables:
     def __iter__(self) -> IteratorOfIterables:
         return IteratorOfIterables()
 
-# TODO: This could be a `tuple[int, int]` (see above)
-# revealed: tuple[int, Unknown | IntIterable]
+# revealed: tuple[int, IntIterable]
 [[reveal_type((x, y)) for x in y] for y in IterableOfIterables()]
 ```
 

crates/red_knot_python_semantic/resources/mdtest/descriptor_protocol.md

@@ -0,0 +1,419 @@
+# Descriptor protocol
+
+[Descriptors] let objects customize attribute lookup, storage, and deletion.
+
+A descriptor is an attribute value that has one of the methods in the descriptor protocol. Those
+methods are `__get__()`, `__set__()`, and `__delete__()`. If any of those methods are defined for an
+attribute, it is said to be a descriptor.
+
+## Basic example
+
+An introductory example, modeled after a [simple example] in the primer on descriptors, involving a
+descriptor that returns a constant value:
+
+```py
+from typing import Literal
+
+class Ten:
+    def __get__(self, instance: object, owner: type | None = None) -> Literal[10]:
+        return 10
+
+    def __set__(self, instance: object, value: Literal[10]) -> None:
+        pass
+
+class C:
+    ten: Ten = Ten()
+
+c = C()
+
+reveal_type(c.ten)  # revealed: Literal[10]
+
+reveal_type(C.ten)  # revealed: Literal[10]
+
+# These are fine:
+# TODO: This should not be an error
+c.ten = 10  # error: [invalid-assignment]
+C.ten = 10
+
+# TODO: This should be an error (as the wrong type is being implicitly passed to `Ten.__set__`),
+# but the error message is misleading.
+# error: [invalid-assignment] "Object of type `Literal[11]` is not assignable to attribute `ten` of type `Ten`"
+c.ten = 11
+
+# TODO: same as above
+# error: [invalid-assignment] "Object of type `Literal[11]` is not assignable to attribute `ten` of type `Literal[10]`"
+C.ten = 11
+```
+
+## Different types for `__get__` and `__set__`
+
+The return type of `__get__` and the value type of `__set__` can be different:
+
+```py
+class FlexibleInt:
+    def __init__(self):
+        self._value: int | None = None
+
+    def __get__(self, instance: object, owner: type | None = None) -> int | None:
+        return self._value
+
+    def __set__(self, instance: object, value: int | str) -> None:
+        self._value = int(value)
+
+class C:
+    flexible_int: FlexibleInt = FlexibleInt()
+
+c = C()
+
+reveal_type(c.flexible_int)  # revealed: int | None
+
+# TODO: These should not be errors
+# error: [invalid-assignment]
+c.flexible_int = 42  # okay
+# error: [invalid-assignment]
+c.flexible_int = "42"  # also okay!
+
+reveal_type(c.flexible_int)  # revealed: int | None
+
+# TODO: This should be an error, but the message needs to be improved.
+# error: [invalid-assignment] "Object of type `None` is not assignable to attribute `flexible_int` of type `FlexibleInt`"
+c.flexible_int = None  # not okay
+
+reveal_type(c.flexible_int)  # revealed: int | None
+```
+
+## Data and non-data descriptors
+
+Descriptors that define `__set__` or `__delete__` are called *data descriptors*. An example\
+of a data descriptor is a `property` with a setter and/or a deleter.\
+Descriptors that only define `__get__`, meanwhile, are called *non-data descriptors*. Examples
+include\
+functions, `classmethod` or `staticmethod`).
+
+The precedence chain for attribute access is (1) data descriptors, (2) instance attributes, and (3)
+non-data descriptors.
+
+```py
+from typing import Literal
+
+class DataDescriptor:
+    def __get__(self, instance: object, owner: type | None = None) -> Literal["data"]:
+        return "data"
+
+    def __set__(self, instance: int, value) -> None:
+        pass
+
+class NonDataDescriptor:
+    def __get__(self, instance: object, owner: type | None = None) -> Literal["non-data"]:
+        return "non-data"
+
+class C:
+    data_descriptor = DataDescriptor()
+    non_data_descriptor = NonDataDescriptor()
+
+    def f(self):
+        # This explains why data descriptors come first in the precedence chain. If
+        # instance attributes would take priority, we would override the descriptor
+        # here. Instead, this calls `DataDescriptor.__set__`, i.e. it does not affect
+        # the type of the `data_descriptor` attribute.
+        self.data_descriptor = 1
+
+        # However, for non-data descriptors, instance attributes do take precedence.
+        # So it is possible to override them.
+        self.non_data_descriptor = 1
+
+c = C()
+
+# TODO: This should ideally be `Unknown | Literal["data"]`.
+#
+#     - Pyright also wrongly shows `int | Literal['data']` here
+#     - Mypy shows Literal["data"] here, but also shows Literal["non-data"] below.
+#
+reveal_type(c.data_descriptor)  # revealed: Unknown | Literal["data", 1]
+
+reveal_type(c.non_data_descriptor)  # revealed: Unknown | Literal["non-data", 1]
+
+reveal_type(C.data_descriptor)  # revealed: Unknown | Literal["data"]
+
+reveal_type(C.non_data_descriptor)  # revealed: Unknown | Literal["non-data"]
+
+# It is possible to override data descriptors via class objects. The following
+# assignment does not call `DataDescriptor.__set__`. For this reason, we infer
+# `Unknown | …` for all (descriptor) attributes.
+C.data_descriptor = "something else"  # This is okay
+```
+
+## Built-in `property` descriptor
+
+The built-in `property` decorator creates a descriptor. The names for attribute reads/writes are
+determined by the return type of the `name` method and the parameter type of the setter,
+respectively.
+
+```py
+class C:
+    _name: str | None = None
+
+    @property
+    def name(self) -> str:
+        return self._name or "Unset"
+    # TODO: No diagnostic should be emitted here
+    # error: [unresolved-attribute] "Type `Literal[name]` has no attribute `setter`"
+    @name.setter
+    def name(self, value: str | None) -> None:
+        self._value = value
+
+c = C()
+
+reveal_type(c._name)  # revealed: str | None
+
+# Should be `str`
+reveal_type(c.name)  # revealed: @Todo(decorated method)
+
+# Should be `builtins.property`
+reveal_type(C.name)  # revealed: Literal[name]
+
+# This is fine:
+c.name = "new"
+
+c.name = None
+
+# TODO: this should be an error
+c.name = 42
+```
+
+## Built-in `classmethod` descriptor
+
+Similarly to `property`, `classmethod` decorator creates an implicit descriptor that binds the first
+argument to the class instead of the instance.
+
+```py
+class C:
+    def __init__(self, value: str) -> None:
+        self._name: str = value
+
+    @classmethod
+    def factory(cls, value: str) -> "C":
+        return cls(value)
+
+    @classmethod
+    def get_name(cls) -> str:
+        return cls.__name__
+
+c1 = C.factory("test")  # okay
+
+# TODO: should be `C`
+reveal_type(c1)  # revealed: @Todo(return type)
+
+# TODO: should be `str`
+reveal_type(C.get_name())  # revealed: @Todo(return type)
+
+# TODO: should be `str`
+reveal_type(C("42").get_name())  # revealed: @Todo(decorated method)
+```
+
+## Descriptors only work when used as class variables
+
+From the descriptor guide:
+
+> Descriptors only work when used as class variables. When put in instances, they have no effect.
+
+```py
+from typing import Literal
+
+class Ten:
+    def __get__(self, instance: object, owner: type | None = None) -> Literal[10]:
+        return 10
+
+class C:
+    def __init__(self):
+        self.ten: Ten = Ten()
+
+# TODO: Should be Ten
+reveal_type(C().ten)  # revealed: Literal[10]
+```
+
+## Descriptors distinguishing between class and instance access
+
+Overloads can be used to distinguish between when a descriptor is accessed on a class object and
+when it is accessed on an instance. A real-world example of this is the `__get__` method on
+`types.FunctionType`.
+
+```py
+from typing_extensions import Literal, LiteralString, overload
+
+class Descriptor:
+    @overload
+    def __get__(self, instance: None, owner: type, /) -> Literal["called on class object"]: ...
+    @overload
+    def __get__(self, instance: object, owner: type | None = None, /) -> Literal["called on instance"]: ...
+    def __get__(self, instance, owner=None, /) -> LiteralString:
+        if instance:
+            return "called on instance"
+        else:
+            return "called on class object"
+
+class C:
+    d: Descriptor = Descriptor()
+
+# TODO: should be `Literal["called on class object"]
+reveal_type(C.d)  # revealed: LiteralString
+
+# TODO: should be `Literal["called on instance"]
+reveal_type(C().d)  # revealed: LiteralString
+```
+
+## Undeclared descriptor arguments
+
+If a descriptor attribute is not declared, we union with `Unknown`, just like for regular
+attributes, since that attribute could be overwritten externally. Even a data descriptor with a
+`__set__` method can be overwritten when accessed through a class object.
+
+```py
+class Descriptor:
+    def __get__(self, instance: object, owner: type | None = None) -> int:
+        return 1
+
+    def __set__(self, instance: object, value: int) -> None:
+        pass
+
+class C:
+    descriptor = Descriptor()
+
+C.descriptor = "something else"
+
+# This could also be `Literal["something else"]` if we support narrowing of attribute types based on assignments
+reveal_type(C.descriptor)  # revealed: Unknown | int
+```
+
+## Descriptors with incorrect `__get__` signature
+
+```py
+class Descriptor:
+    # `__get__` method with missing parameters:
+    def __get__(self) -> int:
+        return 1
+
+class C:
+    descriptor: Descriptor = Descriptor()
+
+# TODO: This should be an error
+reveal_type(C.descriptor)  # revealed: Descriptor
+```
+
+## Possibly-unbound `__get__` method
+
+```py
+def _(flag: bool):
+    class MaybeDescriptor:
+        if flag:
+            def __get__(self, instance: object, owner: type | None = None) -> int:
+                return 1
+
+    class C:
+        descriptor: MaybeDescriptor = MaybeDescriptor()
+
+    # TODO: This should be `MaybeDescriptor | int`
+    reveal_type(C.descriptor)  # revealed: int
+```
+
+## Dunder methods
+
+Dunder methods are looked up on the meta type, but we still need to invoke the descriptor protocol:
+
+```py
+class SomeCallable:
+    def __call__(self, x: int) -> str:
+        return "a"
+
+class Descriptor:
+    def __get__(self, instance: object, owner: type | None = None) -> SomeCallable:
+        return SomeCallable()
+
+class B:
+    __call__: Descriptor = Descriptor()
+
+b_instance = B()
+reveal_type(b_instance(1))  # revealed: str
+
+b_instance("bla")  # error: [invalid-argument-type]
+```
+
+## Functions as descriptors
+
+Functions are descriptors because they implement a `__get__` method. This is crucial in making sure
+that method calls work as expected. See [this test suite](./call/methods.md) for more information.
+Here, we only demonstrate how `__get__` works on functions:
+
+```py
+from inspect import getattr_static
+
+def f(x: object) -> str:
+    return "a"
+
+reveal_type(f)  # revealed: Literal[f]
+reveal_type(f.__get__)  # revealed: <method-wrapper `__get__` of `f`>
+reveal_type(f.__get__(None, type(f)))  # revealed: Literal[f]
+reveal_type(f.__get__(None, type(f))(1))  # revealed: str
+
+wrapper_descriptor = getattr_static(f, "__get__")
+
+reveal_type(wrapper_descriptor)  # revealed: <wrapper-descriptor `__get__` of `function` objects>
+reveal_type(wrapper_descriptor(f, None, type(f)))  # revealed: Literal[f]
+
+# Attribute access on the method-wrapper `f.__get__` falls back to `MethodWrapperType`:
+reveal_type(f.__get__.__hash__)  # revealed: <bound method `__hash__` of `MethodWrapperType`>
+
+# Attribute access on the wrapper-descriptor falls back to `WrapperDescriptorType`:
+reveal_type(wrapper_descriptor.__qualname__)  # revealed: @Todo(@property)
+```
+
+We can also bind the free function `f` to an instance of a class `C`:
+
+```py
+class C: ...
+
+bound_method = wrapper_descriptor(f, C(), C)
+
+reveal_type(bound_method)  # revealed: <bound method `f` of `C`>
+```
+
+We can then call it, and the instance of `C` is implicitly passed to the first parameter of `f`
+(`x`):
+
+```py
+reveal_type(bound_method())  # revealed: str
+```
+
+Finally, we test some error cases for the call to the wrapper descriptor:
+
+```py
+# Calling the wrapper descriptor without any arguments is an
+# error: [missing-argument] "No arguments provided for required parameters `self`, `instance`"
+wrapper_descriptor()
+
+# Calling it without the `instance` argument is an also an
+# error: [missing-argument] "No argument provided for required parameter `instance`"
+wrapper_descriptor(f)
+
+# Calling it without the `owner` argument if `instance` is not `None` is an
+# error: [missing-argument] "No argument provided for required parameter `owner`"
+wrapper_descriptor(f, None)
+
+# But calling it with an instance is fine (in this case, the `owner` argument is optional):
+wrapper_descriptor(f, C())
+
+# Calling it with something that is not a `FunctionType` as the first argument is an
+# error: [invalid-argument-type] "Object of type `Literal[1]` cannot be assigned to parameter 1 (`self`); expected type `FunctionType`"
+wrapper_descriptor(1, None, type(f))
+
+# Calling it with something that is not a `type` as the `owner` argument is an
+# error: [invalid-argument-type] "Object of type `Literal[f]` cannot be assigned to parameter 3 (`owner`); expected type `type`"
+wrapper_descriptor(f, None, f)
+
+# Calling it with too many positional arguments is an
+# error: [too-many-positional-arguments] "Too many positional arguments: expected 3, got 4"
+wrapper_descriptor(f, None, type(f), "one too many")
+```
+
+[descriptors]: https://docs.python.org/3/howto/descriptor.html
+[simple example]: https://docs.python.org/3/howto/descriptor.html#simple-example-a-descriptor-that-returns-a-constant

crates/red_knot_python_semantic/resources/mdtest/diagnostics/invalid_argument_type.md

@@ -0,0 +1,184 @@
+# Invalid argument type diagnostics
+
+<!-- snapshot-diagnostics -->
+
+## Basic
+
+This is a basic test demonstrating that a diagnostic points to the function definition corresponding
+to the invalid argument.
+
+```py
+def foo(x: int) -> int:
+    return x * x
+
+foo("hello")  # error: [invalid-argument-type]
+```
+
+## Different source order
+
+This is like the basic test, except we put the call site above the function definition.
+
+```py
+def bar():
+    foo("hello")  # error: [invalid-argument-type]
+
+def foo(x: int) -> int:
+    return x * x
+```
+
+## Different files
+
+This tests that a diagnostic can point to a function definition in a different file in which an
+invalid call site was found.
+
+`package.py`:
+
+```py
+def foo(x: int) -> int:
+    return x * x
+```
+
+```py
+import package
+
+package.foo("hello")  # error: [invalid-argument-type]
+```
+
+## Many parameters
+
+This checks that a diagnostic renders reasonably when there are multiple parameters.
+
+```py
+def foo(x: int, y: int, z: int) -> int:
+    return x * y * z
+
+foo(1, "hello", 3)  # error: [invalid-argument-type]
+```
+
+## Many parameters across multiple lines
+
+This checks that a diagnostic renders reasonably when there are multiple parameters spread out
+across multiple lines.
+
+```py
+def foo(
+    x: int,
+    y: int,
+    z: int,
+) -> int:
+    return x * y * z
+
+foo(1, "hello", 3)  # error: [invalid-argument-type]
+```
+
+## Many parameters with multiple invalid arguments
+
+This checks that a diagnostic renders reasonably when there are multiple parameters and multiple
+invalid argument types.
+
+```py
+def foo(x: int, y: int, z: int) -> int:
+    return x * y * z
+
+# error: [invalid-argument-type]
+# error: [invalid-argument-type]
+# error: [invalid-argument-type]
+foo("a", "b", "c")
+```
+
+At present (2025-02-18), this renders three different diagnostic messages. But arguably, these could
+all be folded into one diagnostic. Fixing this requires at least better support for multi-spans in
+the diagnostic model and possibly also how diagnostics are emitted by the type checker itself.
+
+## Test calling a function whose type is vendored from `typeshed`
+
+This tests that diagnostic rendering is reasonable when the function being called is from the
+standard library.
+
+```py
+import json
+
+json.loads(5)  # error: [invalid-argument-type]
+```
+
+## Tests for a variety of argument types
+
+These tests check that diagnostic output is reasonable regardless of the kinds of arguments used in
+a function definition.
+
+### Only positional
+
+Tests a function definition with only positional parameters.
+
+```py
+def foo(x: int, y: int, z: int, /) -> int:
+    return x * y * z
+
+foo(1, "hello", 3)  # error: [invalid-argument-type]
+```
+
+### Variadic arguments
+
+Tests a function definition with variadic arguments.
+
+```py
+def foo(*numbers: int) -> int:
+    return len(numbers)
+
+foo(1, 2, 3, "hello", 5)  # error: [invalid-argument-type]
+```
+
+### Keyword only arguments
+
+Tests a function definition with keyword-only arguments.
+
+```py
+def foo(x: int, y: int, *, z: int = 0) -> int:
+    return x * y * z
+
+foo(1, 2, z="hello")  # error: [invalid-argument-type]
+```
+
+### One keyword argument
+
+Tests a function definition with keyword-only arguments.
+
+```py
+def foo(x: int, y: int, z: int = 0) -> int:
+    return x * y * z
+
+foo(1, 2, "hello")  # error: [invalid-argument-type]
+```
+
+### Variadic keyword arguments
+
+```py
+def foo(**numbers: int) -> int:
+    return len(numbers)
+
+foo(a=1, b=2, c=3, d="hello", e=5)  # error: [invalid-argument-type]
+```
+
+### Mix of arguments
+
+Tests a function definition with multiple different kinds of arguments.
+
+```py
+def foo(x: int, /, y: int, *, z: int = 0) -> int:
+    return x * y * z
+
+foo(1, 2, z="hello")  # error: [invalid-argument-type]
+```
+
+### Synthetic arguments
+
+Tests a function call with synthetic arguments.
+
+```py
+class C:
+    def __call__(self, x: int) -> int:
+        return 1
+
+c = C()
+c("wrong")  # error: [invalid-argument-type]
+```

crates/red_knot_python_semantic/resources/mdtest/diagnostics/unpacking.md

@@ -0,0 +1,21 @@
+# Unpacking
+
+<!-- snapshot-diagnostics -->
+
+## Right hand side not iterable
+
+```py
+a, b = 1  # error: [not-iterable]
+```
+
+## Too many values to unpack
+
+```py
+a, b = (1, 2, 3)  # error: [invalid-assignment]
+```
+
+## Too few values to unpack
+
+```py
+a, b = (1,)  # error: [invalid-assignment]
+```

crates/red_knot_python_semantic/resources/mdtest/diagnostics/unresolved_import.md

@@ -0,0 +1,87 @@
+# Unresolved import diagnostics
+
+<!-- snapshot-diagnostics -->
+
+## Using `from` with an unresolvable module
+
+This example demonstrates the diagnostic when a `from` style import is used with a module that could
+not be found:
+
+```py
+from does_not_exist import add  # error: [unresolved-import]
+
+stat = add(10, 15)
+```
+
+## Using `from` with too many leading dots
+
+This example demonstrates the diagnostic when a `from` style import is used with a presumptively
+valid path, but where there are too many leading dots.
+
+`package/__init__.py`:
+
+```py
+```
+
+`package/foo.py`:
+
+```py
+def add(x, y):
+    return x + y
+```
+
+`package/subpackage/subsubpackage/__init__.py`:
+
+```py
+from ....foo import add  # error: [unresolved-import]
+
+stat = add(10, 15)
+```
+
+## Using `from` with an unknown current module
+
+This is another case handled separately in Red Knot, where a `.` provokes relative module name
+resolution, but where the module name is not resolvable.
+
+```py
+from .does_not_exist import add  # error: [unresolved-import]
+
+stat = add(10, 15)
+```
+
+## Using `from` with an unknown nested module
+
+Like the previous test, but with sub-modules to ensure the span is correct.
+
+```py
+from .does_not_exist.foo.bar import add  # error: [unresolved-import]
+
+stat = add(10, 15)
+```
+
+## Using `from` with a resolvable module but unresolvable item
+
+This ensures that diagnostics for an unresolvable item inside a resolvable import highlight the item
+and not the entire `from ... import ...` statement.
+
+`a.py`:
+
+```py
+does_exist1 = 1
+does_exist2 = 2
+```
+
+```py
+from a import does_exist1, does_not_exist, does_exist2  # error: [unresolved-import]
+```
+
+## An unresolvable import that does not use `from`
+
+This ensures that an unresolvable `import ...` statement highlights just the module name and not the
+entire statement.
+
+```py
+import does_not_exist  # error: [unresolved-import]
+
+x = does_not_exist.foo
+```

crates/red_knot_python_semantic/resources/mdtest/directives/assert_type.md

@@ -78,7 +78,7 @@ def _(a: type[Unknown], b: type[Any]):
 Tuple types with the same elements are the same.
 
 ```py
-from typing_extensions import assert_type
+from typing_extensions import Any, assert_type
 
 from knot_extensions import Unknown
 

crates/red_knot_python_semantic/resources/mdtest/doc/README.md

@@ -0,0 +1,2 @@
+This directory contains user-facing documentation, but also doubles as an extended test suite that
+makes sure that our documentation stays up to date.

crates/red_knot_python_semantic/resources/mdtest/doc/public_type_undeclared_symbols.md

@@ -0,0 +1,125 @@
+# Public type of undeclared symbols
+
+## Summary
+
+One major deviation from the behavior of existing Python type checkers is our handling of 'public'
+types for undeclared symbols. This is best illustrated with an example:
+
+```py
+class Wrapper:
+    value = None
+
+wrapper = Wrapper()
+
+reveal_type(wrapper.value)  # revealed: Unknown | None
+
+wrapper.value = 1
+```
+
+Mypy and Pyright both infer a type of `None` for the type of `wrapper.value`. Consequently, both
+tools emit an error when trying to assign `1` to `wrapper.value`. But there is nothing wrong with
+this program. Emitting an error here violates the [gradual guarantee] which states that *"Removing
+type annotations (making the program more dynamic) should not result in additional static type
+errors."*: If `value` were annotated with `int | None` here, Mypy and Pyright would not emit any
+errors.
+
+By inferring `Unknown | None` instead, we allow arbitrary values to be assigned to `wrapper.value`.
+This is a deliberate choice to prevent false positive errors on untyped code.
+
+More generally, we infer `Unknown | T_inferred` for undeclared symbols, where `T_inferred` is the
+inferred type of the right-hand side of the assignment. This gradual type represents an *unknown*
+fully-static type that is *at least as large as* `T_inferred`. It accurately describes our static
+knowledge about this type. In the example above, we don't know what values `wrapper.value` could
+possibly contain, but we *do know* that `None` is a possibility. This allows us to catch errors
+where `wrapper.value` is used in a way that is incompatible with `None`:
+
+```py
+def accepts_int(i: int) -> None:
+    pass
+
+def f(w: Wrapper) -> None:
+    # This is fine
+    v: int | None = w.value
+
+    # This function call is incorrect, because `w.value` could be `None`. We therefore emit the following
+    # error: "`Unknown | None` cannot be assigned to parameter 1 (`i`) of function `accepts_int`; expected type `int`"
+    c = accepts_int(w.value)
+```
+
+## Explicit lack of knowledge
+
+The following example demonstrates how Mypy and Pyright's type inference of fully-static types in
+these situations can lead to false-negatives, even though everything appears to be (statically)
+typed. To make this a bit more realistic, imagine that `OptionalInt` is imported from an external,
+untyped module:
+
+`optional_int.py`:
+
+```py
+class OptionalInt:
+    value = 10
+
+def reset(o):
+    o.value = None
+```
+
+It is then used like this:
+
+```py
+from optional_int import OptionalInt, reset
+
+o = OptionalInt()
+reset(o)  # Oh no...
+
+# Mypy and Pyright infer a fully-static type of `int` here, which appears to make the
+# subsequent division operation safe -- but it is not. We infer the following type:
+reveal_type(o.value)  # revealed: Unknown | Literal[10]
+
+print(o.value // 2)  # Runtime error!
+```
+
+We do not catch this mistake either, but we accurately reflect our lack of knowledge about
+`o.value`. Together with a possible future type-checker mode that would detect the prevalence of
+dynamic types, this could help developers catch such mistakes.
+
+## Stricter behavior
+
+Users can always opt in to stricter behavior by adding type annotations. For the `OptionalInt`
+class, this would probably be:
+
+```py
+class OptionalInt:
+    value: int | None = 10
+
+o = OptionalInt()
+
+# The following public type is now
+# revealed: int | None
+reveal_type(o.value)
+
+# Incompatible assignments are now caught:
+# error: "Object of type `Literal["a"]` is not assignable to attribute `value` of type `int | None`"
+o.value = "a"
+```
+
+## What is meant by 'public' type?
+
+We apply different semantics depending on whether a symbol is accessed from the same scope in which
+it was originally defined, or whether it is accessed from an external scope. External scopes will
+see the symbol's "public type", which has been discussed above. But within the same scope the symbol
+was defined in, we use a narrower type of `T_inferred` for undeclared symbols. This is because, from
+the perspective of this scope, there is no way that the value of the symbol could have been
+reassigned from external scopes. For example:
+
+```py
+class Wrapper:
+    value = None
+
+    # Type as seen from the same scope:
+    reveal_type(value)  # revealed: None
+
+# Type as seen from another scope:
+reveal_type(Wrapper.value)  # revealed: Unknown | None
+```
+
+[gradual guarantee]: https://typing.readthedocs.io/en/latest/spec/concepts.html#the-gradual-guarantee

crates/red_knot_python_semantic/resources/mdtest/exception/basic.md

@@ -124,42 +124,49 @@ def _(e: Exception | type[Exception] | None):
 ## Exception cause is not an exception
 
 ```py
-try:
-    raise EOFError() from GeneratorExit  # fine
-except:
-    ...
+def _():
+    try:
+        raise EOFError() from GeneratorExit  # fine
+    except:
+        ...
 
-try:
-    raise StopIteration from MemoryError()  # fine
-except:
-    ...
+def _():
+    try:
+        raise StopIteration from MemoryError()  # fine
+    except:
+        ...
 
-try:
-    raise BufferError() from None  # fine
-except:
-    ...
+def _():
+    try:
+        raise BufferError() from None  # fine
+    except:
+        ...
 
-try:
-    raise ZeroDivisionError from False  # error: [invalid-raise]
-except:
-    ...
+def _():
+    try:
+        raise ZeroDivisionError from False  # error: [invalid-raise]
+    except:
+        ...
 
-try:
-    raise SystemExit from bool()  # error: [invalid-raise]
-except:
-    ...
+def _():
+    try:
+        raise SystemExit from bool()  # error: [invalid-raise]
+    except:
+        ...
 
-try:
-    raise
-except KeyboardInterrupt as e:  # fine
-    reveal_type(e)  # revealed: KeyboardInterrupt
-    raise LookupError from e  # fine
+def _():
+    try:
+        raise
+    except KeyboardInterrupt as e:  # fine
+        reveal_type(e)  # revealed: KeyboardInterrupt
+        raise LookupError from e  # fine
 
-try:
-    raise
-except int as e:  # error: [invalid-exception-caught]
-    reveal_type(e)  # revealed: Unknown
-    raise KeyError from e
+def _():
+    try:
+        raise
+    except int as e:  # error: [invalid-exception-caught]
+        reveal_type(e)  # revealed: Unknown
+        raise KeyError from e
 
 def _(e: Exception | type[Exception]):
     raise ModuleNotFoundError from e  # fine

crates/red_knot_python_semantic/resources/mdtest/exception/control_flow.md

@@ -29,7 +29,7 @@ completing. The type of `x` at the beginning of the `except` suite in this examp
 `x = could_raise_returns_str()` redefinition, but we *also* could have jumped to the `except` suite
 *after* that redefinition.
 
-```py path=union_type_inferred.py
+```py
 def could_raise_returns_str() -> str:
     return "foo"
 
@@ -50,10 +50,7 @@ reveal_type(x)  # revealed: str | Literal[2]
 If `x` has the same type at the end of both branches, however, the branches unify and `x` is not
 inferred as having a union type following the `try`/`except` block:
 
-```py path=branches_unify_to_non_union_type.py
-def could_raise_returns_str() -> str:
-    return "foo"
-
+```py
 x = 1
 
 try:
@@ -133,7 +130,7 @@ the `except` suite:
 - At the end of `else`, `x == 3`
 - At the end of `except`, `x == 2`
 
-```py path=single_except.py
+```py
 def could_raise_returns_str() -> str:
     return "foo"
 
@@ -161,9 +158,6 @@ been executed in its entirety, or the `try` suite and the `else` suite must both
 in their entireties:
 
 ```py
-def could_raise_returns_str() -> str:
-    return "foo"
-
 x = 1
 
 try:
@@ -192,7 +186,7 @@ A `finally` suite is *always* executed. As such, if we reach the `reveal_type` c
 this example, we know that `x` *must* have been reassigned to `2` during the `finally` suite. The
 type of `x` at the end of the example is therefore `Literal[2]`:
 
-```py path=redef_in_finally.py
+```py
 def could_raise_returns_str() -> str:
     return "foo"
 
@@ -217,10 +211,7 @@ at this point than there were when we were inside the `finally` block.
 (Our current model does *not* correctly infer the types *inside* `finally` suites, however; this is
 still a TODO item for us.)
 
-```py path=no_redef_in_finally.py
-def could_raise_returns_str() -> str:
-    return "foo"
-
+```py
 x = 1
 
 try:
@@ -249,31 +240,35 @@ suites:
     exception raised in the `except` suite to cause us to jump to the `finally` suite before the
     `except` suite ran to completion
 
-```py path=redef_in_finally.py
-def could_raise_returns_str() -> str:
-    return "foo"
+```py
+class A: ...
+class B: ...
+class C: ...
 
-def could_raise_returns_bytes() -> bytes:
-    return b"foo"
+def could_raise_returns_A() -> A:
+    return A()
 
-def could_raise_returns_bool() -> bool:
-    return True
+def could_raise_returns_B() -> B:
+    return B()
+
+def could_raise_returns_C() -> C:
+    return C()
 
 x = 1
 
 try:
     reveal_type(x)  # revealed: Literal[1]
-    x = could_raise_returns_str()
-    reveal_type(x)  # revealed: str
+    x = could_raise_returns_A()
+    reveal_type(x)  # revealed: A
 except TypeError:
-    reveal_type(x)  # revealed: Literal[1] | str
-    x = could_raise_returns_bytes()
-    reveal_type(x)  # revealed: bytes
-    x = could_raise_returns_bool()
-    reveal_type(x)  # revealed: bool
+    reveal_type(x)  # revealed: Literal[1] | A
+    x = could_raise_returns_B()
+    reveal_type(x)  # revealed: B
+    x = could_raise_returns_C()
+    reveal_type(x)  # revealed: C
 finally:
-    # TODO: should be `Literal[1] | str | bytes | bool`
-    reveal_type(x)  # revealed: str | bool
+    # TODO: should be `Literal[1] | A | B | C`
+    reveal_type(x)  # revealed: A | C
     x = 2
     reveal_type(x)  # revealed: Literal[2]
 
@@ -286,76 +281,61 @@ itself. (In some control-flow possibilities, some exceptions were merely *suspen
 `finally` suite; these lead to the scope's termination following the conclusion of the `finally`
 suite.)
 
-```py path=no_redef_in_finally.py
-def could_raise_returns_str() -> str:
-    return "foo"
-
-def could_raise_returns_bytes() -> bytes:
-    return b"foo"
-
-def could_raise_returns_bool() -> bool:
-    return True
-
+```py
 x = 1
 
 try:
     reveal_type(x)  # revealed: Literal[1]
-    x = could_raise_returns_str()
-    reveal_type(x)  # revealed: str
+    x = could_raise_returns_A()
+    reveal_type(x)  # revealed: A
 except TypeError:
-    reveal_type(x)  # revealed: Literal[1] | str
-    x = could_raise_returns_bytes()
-    reveal_type(x)  # revealed: bytes
-    x = could_raise_returns_bool()
-    reveal_type(x)  # revealed: bool
+    reveal_type(x)  # revealed: Literal[1] | A
+    x = could_raise_returns_B()
+    reveal_type(x)  # revealed: B
+    x = could_raise_returns_C()
+    reveal_type(x)  # revealed: C
 finally:
-    # TODO: should be `Literal[1] | str | bytes | bool`
-    reveal_type(x)  # revealed: str | bool
+    # TODO: should be `Literal[1] | A | B | C`
+    reveal_type(x)  # revealed: A | C
 
-reveal_type(x)  # revealed: str | bool
+reveal_type(x)  # revealed: A | C
 ```
 
 An example with multiple `except` branches and a `finally` branch:
 
-```py path=multiple_except_branches.py
-def could_raise_returns_str() -> str:
-    return "foo"
+```py
+class D: ...
+class E: ...
 
-def could_raise_returns_bytes() -> bytes:
-    return b"foo"
+def could_raise_returns_D() -> D:
+    return D()
 
-def could_raise_returns_bool() -> bool:
-    return True
-
-def could_raise_returns_memoryview() -> memoryview:
-    return memoryview(b"")
-
-def could_raise_returns_float() -> float:
-    return 3.14
+def could_raise_returns_E() -> E:
+    return E()
 
 x = 1
 
 try:
     reveal_type(x)  # revealed: Literal[1]
-    x = could_raise_returns_str()
-    reveal_type(x)  # revealed: str
+    x = could_raise_returns_A()
+    reveal_type(x)  # revealed: A
 except TypeError:
-    reveal_type(x)  # revealed: Literal[1] | str
-    x = could_raise_returns_bytes()
-    reveal_type(x)  # revealed: bytes
-    x = could_raise_returns_bool()
-    reveal_type(x)  # revealed: bool
+    reveal_type(x)  # revealed: Literal[1] | A
+    x = could_raise_returns_B()
+    reveal_type(x)  # revealed: B
+    x = could_raise_returns_C()
+    reveal_type(x)  # revealed: C
 except ValueError:
-    reveal_type(x)  # revealed: Literal[1] | str
-    x = could_raise_returns_memoryview()
-    reveal_type(x)  # revealed: memoryview
-    x = could_raise_returns_float()
-    reveal_type(x)  # revealed: float
+    reveal_type(x)  # revealed: Literal[1] | A
+    x = could_raise_returns_D()
+    reveal_type(x)  # revealed: D
+    x = could_raise_returns_E()
+    reveal_type(x)  # revealed: E
 finally:
-    # TODO: should be `Literal[1] | str | bytes | bool | memoryview | float`
-    reveal_type(x)  # revealed: str | bool | float
+    # TODO: should be `Literal[1] | A | B | C | D | E`
+    reveal_type(x)  # revealed: A | C | E
 
-reveal_type(x)  # revealed: str | bool | float
+reveal_type(x)  # revealed: A | C | E
 ```
 
 ## Combining `except`, `else` and `finally` branches
@@ -364,100 +344,94 @@ If the exception handler has an `else` branch, we must also take into account th
 control flow could have jumped to the `finally` suite from partway through the `else` suite due to
 an exception raised *there*.
 
-```py path=single_except_branch.py
-def could_raise_returns_str() -> str:
-    return "foo"
+```py
+class A: ...
+class B: ...
+class C: ...
+class D: ...
+class E: ...
 
-def could_raise_returns_bytes() -> bytes:
-    return b"foo"
+def could_raise_returns_A() -> A:
+    return A()
 
-def could_raise_returns_bool() -> bool:
-    return True
+def could_raise_returns_B() -> B:
+    return B()
 
-def could_raise_returns_memoryview() -> memoryview:
-    return memoryview(b"")
+def could_raise_returns_C() -> C:
+    return C()
 
-def could_raise_returns_float() -> float:
-    return 3.14
+def could_raise_returns_D() -> D:
+    return D()
+
+def could_raise_returns_E() -> E:
+    return E()
 
 x = 1
 
 try:
     reveal_type(x)  # revealed: Literal[1]
-    x = could_raise_returns_str()
-    reveal_type(x)  # revealed: str
+    x = could_raise_returns_A()
+    reveal_type(x)  # revealed: A
 except TypeError:
-    reveal_type(x)  # revealed: Literal[1] | str
-    x = could_raise_returns_bytes()
-    reveal_type(x)  # revealed: bytes
-    x = could_raise_returns_bool()
-    reveal_type(x)  # revealed: bool
+    reveal_type(x)  # revealed: Literal[1] | A
+    x = could_raise_returns_B()
+    reveal_type(x)  # revealed: B
+    x = could_raise_returns_C()
+    reveal_type(x)  # revealed: C
 else:
-    reveal_type(x)  # revealed: str
-    x = could_raise_returns_memoryview()
-    reveal_type(x)  # revealed: memoryview
-    x = could_raise_returns_float()
-    reveal_type(x)  # revealed: float
+    reveal_type(x)  # revealed: A
+    x = could_raise_returns_D()
+    reveal_type(x)  # revealed: D
+    x = could_raise_returns_E()
+    reveal_type(x)  # revealed: E
 finally:
-    # TODO: should be `Literal[1] | str | bytes | bool | memoryview | float`
-    reveal_type(x)  # revealed: bool | float
+    # TODO: should be `Literal[1] | A | B | C | D | E`
+    reveal_type(x)  # revealed: C | E
 
-reveal_type(x)  # revealed: bool | float
+reveal_type(x)  # revealed: C | E
 ```
 
 The same again, this time with multiple `except` branches:
 
-```py path=multiple_except_branches.py
-def could_raise_returns_str() -> str:
-    return "foo"
+```py
+class F: ...
+class G: ...
 
-def could_raise_returns_bytes() -> bytes:
-    return b"foo"
+def could_raise_returns_F() -> F:
+    return F()
 
-def could_raise_returns_bool() -> bool:
-    return True
-
-def could_raise_returns_memoryview() -> memoryview:
-    return memoryview(b"")
-
-def could_raise_returns_float() -> float:
-    return 3.14
-
-def could_raise_returns_range() -> range:
-    return range(42)
-
-def could_raise_returns_slice() -> slice:
-    return slice(None)
+def could_raise_returns_G() -> G:
+    return G()
 
 x = 1
 
 try:
     reveal_type(x)  # revealed: Literal[1]
-    x = could_raise_returns_str()
-    reveal_type(x)  # revealed: str
+    x = could_raise_returns_A()
+    reveal_type(x)  # revealed: A
 except TypeError:
-    reveal_type(x)  # revealed: Literal[1] | str
-    x = could_raise_returns_bytes()
-    reveal_type(x)  # revealed: bytes
-    x = could_raise_returns_bool()
-    reveal_type(x)  # revealed: bool
+    reveal_type(x)  # revealed: Literal[1] | A
+    x = could_raise_returns_B()
+    reveal_type(x)  # revealed: B
+    x = could_raise_returns_C()
+    reveal_type(x)  # revealed: C
 except ValueError:
-    reveal_type(x)  # revealed: Literal[1] | str
-    x = could_raise_returns_memoryview()
-    reveal_type(x)  # revealed: memoryview
-    x = could_raise_returns_float()
-    reveal_type(x)  # revealed: float
+    reveal_type(x)  # revealed: Literal[1] | A
+    x = could_raise_returns_D()
+    reveal_type(x)  # revealed: D
+    x = could_raise_returns_E()
+    reveal_type(x)  # revealed: E
 else:
-    reveal_type(x)  # revealed: str
-    x = could_raise_returns_range()
-    reveal_type(x)  # revealed: range
-    x = could_raise_returns_slice()
-    reveal_type(x)  # revealed: slice
+    reveal_type(x)  # revealed: A
+    x = could_raise_returns_F()
+    reveal_type(x)  # revealed: F
+    x = could_raise_returns_G()
+    reveal_type(x)  # revealed: G
 finally:
-    # TODO: should be `Literal[1] | str | bytes | bool | memoryview | float | range | slice`
-    reveal_type(x)  # revealed: bool | float | slice
+    # TODO: should be `Literal[1] | A | B | C | D | E | F | G`
+    reveal_type(x)  # revealed: C | E | G
 
-reveal_type(x)  # revealed: bool | float | slice
+reveal_type(x)  # revealed: C | E | G
 ```
 
 ## Nested `try`/`except` blocks
@@ -471,92 +445,101 @@ a suite containing statements that could possibly raise exceptions, which would
 jumping out of that suite prior to the suite running to completion.
 
 ```py
-def could_raise_returns_str() -> str:
-    return "foo"
+class A: ...
+class B: ...
+class C: ...
+class D: ...
+class E: ...
+class F: ...
+class G: ...
+class H: ...
+class I: ...
+class J: ...
+class K: ...
 
-def could_raise_returns_bytes() -> bytes:
-    return b"foo"
+def could_raise_returns_A() -> A:
+    return A()
 
-def could_raise_returns_bool() -> bool:
-    return True
+def could_raise_returns_B() -> B:
+    return B()
 
-def could_raise_returns_memoryview() -> memoryview:
-    return memoryview(b"")
+def could_raise_returns_C() -> C:
+    return C()
 
-def could_raise_returns_float() -> float:
-    return 3.14
+def could_raise_returns_D() -> D:
+    return D()
 
-def could_raise_returns_range() -> range:
-    return range(42)
+def could_raise_returns_E() -> E:
+    return E()
 
-def could_raise_returns_slice() -> slice:
-    return slice(None)
+def could_raise_returns_F() -> F:
+    return F()
 
-def could_raise_returns_complex() -> complex:
-    return 3j
+def could_raise_returns_G() -> G:
+    return G()
 
-def could_raise_returns_bytearray() -> bytearray:
-    return bytearray()
+def could_raise_returns_H() -> H:
+    return H()
 
-class Foo: ...
-class Bar: ...
+def could_raise_returns_I() -> I:
+    return I()
 
-def could_raise_returns_Foo() -> Foo:
-    return Foo()
+def could_raise_returns_J() -> J:
+    return J()
 
-def could_raise_returns_Bar() -> Bar:
-    return Bar()
+def could_raise_returns_K() -> K:
+    return K()
 
 x = 1
 
 try:
     try:
         reveal_type(x)  # revealed: Literal[1]
-        x = could_raise_returns_str()
-        reveal_type(x)  # revealed: str
+        x = could_raise_returns_A()
+        reveal_type(x)  # revealed: A
     except TypeError:
-        reveal_type(x)  # revealed: Literal[1] | str
-        x = could_raise_returns_bytes()
-        reveal_type(x)  # revealed: bytes
-        x = could_raise_returns_bool()
-        reveal_type(x)  # revealed: bool
+        reveal_type(x)  # revealed: Literal[1] | A
+        x = could_raise_returns_B()
+        reveal_type(x)  # revealed: B
+        x = could_raise_returns_C()
+        reveal_type(x)  # revealed: C
     except ValueError:
-        reveal_type(x)  # revealed: Literal[1] | str
-        x = could_raise_returns_memoryview()
-        reveal_type(x)  # revealed: memoryview
-        x = could_raise_returns_float()
-        reveal_type(x)  # revealed: float
+        reveal_type(x)  # revealed: Literal[1] | A
+        x = could_raise_returns_D()
+        reveal_type(x)  # revealed: D
+        x = could_raise_returns_E()
+        reveal_type(x)  # revealed: E
     else:
-        reveal_type(x)  # revealed: str
-        x = could_raise_returns_range()
-        reveal_type(x)  # revealed: range
-        x = could_raise_returns_slice()
-        reveal_type(x)  # revealed: slice
+        reveal_type(x)  # revealed: A
+        x = could_raise_returns_F()
+        reveal_type(x)  # revealed: F
+        x = could_raise_returns_G()
+        reveal_type(x)  # revealed: G
     finally:
-        # TODO: should be `Literal[1] | str | bytes | bool | memoryview | float | range | slice`
-        reveal_type(x)  # revealed: bool | float | slice
+        # TODO: should be `Literal[1] | A | B | C | D | E | F | G`
+        reveal_type(x)  # revealed: C | E | G
         x = 2
         reveal_type(x)  # revealed: Literal[2]
     reveal_type(x)  # revealed: Literal[2]
 except:
-    reveal_type(x)  # revealed: Literal[1, 2] | str | bytes | bool | memoryview | float | range | slice
-    x = could_raise_returns_complex()
-    reveal_type(x)  # revealed: complex
-    x = could_raise_returns_bytearray()
-    reveal_type(x)  # revealed: bytearray
+    reveal_type(x)  # revealed: Literal[1, 2] | A | B | C | D | E | F | G
+    x = could_raise_returns_H()
+    reveal_type(x)  # revealed: H
+    x = could_raise_returns_I()
+    reveal_type(x)  # revealed: I
 else:
     reveal_type(x)  # revealed: Literal[2]
-    x = could_raise_returns_Foo()
-    reveal_type(x)  # revealed: Foo
-    x = could_raise_returns_Bar()
-    reveal_type(x)  # revealed: Bar
+    x = could_raise_returns_J()
+    reveal_type(x)  # revealed: J
+    x = could_raise_returns_K()
+    reveal_type(x)  # revealed: K
 finally:
-    # TODO: should be `Literal[1, 2] | str | bytes | bool | memoryview | float | range | slice | complex | bytearray | Foo | Bar`
-    reveal_type(x)  # revealed: bytearray | Bar
+    # TODO: should be `Literal[1, 2] | A | B | C | D | E | F | G | H | I | J | K`
+    reveal_type(x)  # revealed: I | K
 
 # Either one `except` branch or the `else`
 # must have been taken and completed to get here:
-reveal_type(x)  # revealed: bytearray | Bar
+reveal_type(x)  # revealed: I | K
 ```
 
 ## Nested scopes inside `try` blocks
@@ -565,50 +548,56 @@ Shadowing a variable in an inner scope has no effect on type inference of the va
 in the outer scope:
 
 ```py
-def could_raise_returns_str() -> str:
-    return "foo"
+class A: ...
+class B: ...
+class C: ...
+class D: ...
+class E: ...
 
-def could_raise_returns_bytes() -> bytes:
-    return b"foo"
+def could_raise_returns_A() -> A:
+    return A()
 
-def could_raise_returns_range() -> range:
-    return range(42)
+def could_raise_returns_B() -> B:
+    return B()
 
-def could_raise_returns_bytearray() -> bytearray:
-    return bytearray()
+def could_raise_returns_C() -> C:
+    return C()
 
-def could_raise_returns_float() -> float:
-    return 3.14
+def could_raise_returns_D() -> D:
+    return D()
+
+def could_raise_returns_E() -> E:
+    return E()
 
 x = 1
 
 try:
 
-    def foo(param=could_raise_returns_str()):
-        x = could_raise_returns_str()
+    def foo(param=could_raise_returns_A()):
+        x = could_raise_returns_A()
 
         try:
-            reveal_type(x)  # revealed: str
-            x = could_raise_returns_bytes()
-            reveal_type(x)  # revealed: bytes
+            reveal_type(x)  # revealed: A
+            x = could_raise_returns_B()
+            reveal_type(x)  # revealed: B
         except:
-            reveal_type(x)  # revealed: str | bytes
-            x = could_raise_returns_bytearray()
-            reveal_type(x)  # revealed: bytearray
-            x = could_raise_returns_float()
-            reveal_type(x)  # revealed: float
+            reveal_type(x)  # revealed: A | B
+            x = could_raise_returns_C()
+            reveal_type(x)  # revealed: C
+            x = could_raise_returns_D()
+            reveal_type(x)  # revealed: D
         finally:
-            # TODO: should be `str | bytes | bytearray | float`
-            reveal_type(x)  # revealed: bytes | float
-        reveal_type(x)  # revealed: bytes | float
+            # TODO: should be `A | B | C | D`
+            reveal_type(x)  # revealed: B | D
+        reveal_type(x)  # revealed: B | D
     x = foo
     reveal_type(x)  # revealed: Literal[foo]
 except:
     reveal_type(x)  # revealed: Literal[1] | Literal[foo]
 
     class Bar:
-        x = could_raise_returns_range()
-        reveal_type(x)  # revealed: range
+        x = could_raise_returns_E()
+        reveal_type(x)  # revealed: E
 
     x = Bar
     reveal_type(x)  # revealed: Literal[Bar]

crates/red_knot_python_semantic/resources/mdtest/expression/boolean.md

@@ -54,7 +54,9 @@ reveal_type("x" or "y" and "")  # revealed: Literal["x"]
 
 ## Evaluates to builtin
 
-```py path=a.py
+`a.py`:
+
+```py
 redefined_builtin_bool: type[bool] = bool
 
 def my_bool(x) -> bool:

crates/red_knot_python_semantic/resources/mdtest/expression/if.md

@@ -28,6 +28,8 @@ reveal_type(1 if 0 else 2)  # revealed: Literal[2]
 The test inside an if expression should not affect code outside of the expression.
 
 ```py
+from typing import Literal
+
 def _(flag: bool):
     x: Literal[42, "hello"] = 42 if flag else "hello"
 

crates/red_knot_python_semantic/resources/mdtest/generics.md

@@ -51,7 +51,7 @@ In type stubs, classes can reference themselves in their base class definitions.
 
 This should hold true even with generics at play.
 
-```py path=a.pyi
+```pyi
 class Seq[T]: ...
 
 # TODO not error on the subscripting

crates/red_knot_python_semantic/resources/mdtest/import/basic.md

@@ -9,7 +9,9 @@ E = D
 reveal_type(E)  # revealed: Literal[C]
 ```
 
-```py path=b.py
+`b.py`:
+
+```py
 class C: ...
 ```
 
@@ -22,7 +24,9 @@ D = b.C
 reveal_type(D)  # revealed: Literal[C]
 ```
 
-```py path=b.py
+`b.py`:
+
+```py
 class C: ...
 ```
 
@@ -34,10 +38,14 @@ import a.b
 reveal_type(a.b.C)  # revealed: Literal[C]
 ```
 
-```py path=a/__init__.py
+`a/__init__.py`:
+
+```py
 ```
 
-```py path=a/b.py
+`a/b.py`:
+
+```py
 class C: ...
 ```
 
@@ -49,13 +57,19 @@ import a.b.c
 reveal_type(a.b.c.C)  # revealed: Literal[C]
 ```
 
-```py path=a/__init__.py
+`a/__init__.py`:
+
+```py
 ```
 
-```py path=a/b/__init__.py
+`a/b/__init__.py`:
+
+```py
 ```
 
-```py path=a/b/c.py
+`a/b/c.py`:
+
+```py
 class C: ...
 ```
 
@@ -67,10 +81,14 @@ import a.b as b
 reveal_type(b.C)  # revealed: Literal[C]
 ```
 
-```py path=a/__init__.py
+`a/__init__.py`:
+
+```py
 ```
 
-```py path=a/b.py
+`a/b.py`:
+
+```py
 class C: ...
 ```
 
@@ -82,18 +100,34 @@ import a.b.c as c
 reveal_type(c.C)  # revealed: Literal[C]
 ```
 
-```py path=a/__init__.py
+`a/__init__.py`:
+
+```py
 ```
 
-```py path=a/b/__init__.py
+`a/b/__init__.py`:
+
+```py
 ```
 
-```py path=a/b/c.py
+`a/b/c.py`:
+
+```py
 class C: ...
 ```
 
+## Unresolvable module import
+
+<!-- snapshot-diagnostics -->
+
+```py
+import zqzqzqzqzqzqzq  # error: [unresolved-import] "Cannot resolve import `zqzqzqzqzqzqzq`"
+```
+
 ## Unresolvable submodule imports
 
+<!-- snapshot-diagnostics -->
+
 ```py
 # Topmost component resolvable, submodule not resolvable:
 import a.foo  # error: [unresolved-import] "Cannot resolve import `a.foo`"
@@ -102,5 +136,7 @@ import a.foo  # error: [unresolved-import] "Cannot resolve import `a.foo`"
 import b.foo  # error: [unresolved-import] "Cannot resolve import `b.foo`"
 ```
 
-```py path=a/__init__.py
+`a/__init__.py`:
+
+```py
 ```

crates/red_knot_python_semantic/resources/mdtest/import/builtins.md

@@ -29,13 +29,17 @@ builtins from the "actual" vendored typeshed:
 typeshed = "/typeshed"
 ```
 
-```pyi path=/typeshed/stdlib/builtins.pyi
+`/typeshed/stdlib/builtins.pyi`:
+
+```pyi
 class Custom: ...
 
 custom_builtin: Custom
 ```
 
-```pyi path=/typeshed/stdlib/typing_extensions.pyi
+`/typeshed/stdlib/typing_extensions.pyi`:
+
+```pyi
 def reveal_type(obj, /): ...
 ```
 
@@ -56,12 +60,16 @@ that point:
 typeshed = "/typeshed"
 ```
 
-```pyi path=/typeshed/stdlib/builtins.pyi
+`/typeshed/stdlib/builtins.pyi`:
+
+```pyi
 foo = bar
 bar = 1
 ```
 
-```pyi path=/typeshed/stdlib/typing_extensions.pyi
+`/typeshed/stdlib/typing_extensions.pyi`:
+
+```pyi
 def reveal_type(obj, /): ...
 ```
 

crates/red_knot_python_semantic/resources/mdtest/import/conditional.md

@@ -2,7 +2,9 @@
 
 ## Maybe unbound
 
-```py path=maybe_unbound.py
+`maybe_unbound.py`:
+
+```py
 def coinflip() -> bool:
     return True
 
@@ -29,7 +31,9 @@ reveal_type(y)  # revealed: Unknown | Literal[3]
 
 ## Maybe unbound annotated
 
-```py path=maybe_unbound_annotated.py
+`maybe_unbound_annotated.py`:
+
+```py
 def coinflip() -> bool:
     return True
 
@@ -60,7 +64,9 @@ reveal_type(y)  # revealed: int
 
 Importing a possibly undeclared name still gives us its declared type:
 
-```py path=maybe_undeclared.py
+`maybe_undeclared.py`:
+
+```py
 def coinflip() -> bool:
     return True
 
@@ -76,11 +82,15 @@ reveal_type(x)  # revealed: int
 
 ## Reimport
 
-```py path=c.py
+`c.py`:
+
+```py
 def f(): ...
 ```
 
-```py path=b.py
+`b.py`:
+
+```py
 def coinflip() -> bool:
     return True
 
@@ -102,11 +112,15 @@ reveal_type(f)  # revealed: Literal[f, f]
 When we have a declared type in one path and only an inferred-from-definition type in the other, we
 should still be able to unify those:
 
-```py path=c.pyi
+`c.pyi`:
+
+```pyi
 x: int
 ```
 
-```py path=b.py
+`b.py`:
+
+```py
 def coinflip() -> bool:
     return True
 

crates/red_knot_python_semantic/resources/mdtest/import/conflicts.md

@@ -8,11 +8,15 @@ import a.b
 reveal_type(a.b)  # revealed: <module 'a.b'>
 ```
 
-```py path=a/__init__.py
+`a/__init__.py`:
+
+```py
 b: int = 42
 ```
 
-```py path=a/b.py
+`a/b.py`:
+
+```py
 ```
 
 ## Via from/import
@@ -23,11 +27,15 @@ from a import b
 reveal_type(b)  # revealed: int
 ```
 
-```py path=a/__init__.py
+`a/__init__.py`:
+
+```py
 b: int = 42
 ```
 
-```py path=a/b.py
+`a/b.py`:
+
+```py
 ```
 
 ## Via both
@@ -40,11 +48,15 @@ reveal_type(b)  # revealed: <module 'a.b'>
 reveal_type(a.b)  # revealed: <module 'a.b'>
 ```
 
-```py path=a/__init__.py
+`a/__init__.py`:
+
+```py
 b: int = 42
 ```
 
-```py path=a/b.py
+`a/b.py`:
+
+```py
 ```
 
 ## Via both (backwards)
@@ -65,11 +77,15 @@ reveal_type(b)  # revealed: <module 'a.b'>
 reveal_type(a.b)  # revealed: <module 'a.b'>
 ```
 
-```py path=a/__init__.py
+`a/__init__.py`:
+
+```py
 b: int = 42
 ```
 
-```py path=a/b.py
+`a/b.py`:
+
+```py
 ```
 
 [from-import]: https://docs.python.org/3/reference/simple_stmts.html#the-import-statement

crates/red_knot_python_semantic/resources/mdtest/import/conventions.md

@@ -0,0 +1,371 @@
+# Import conventions
+
+This document describes the conventions for importing symbols.
+
+Reference:
+
+- <https://typing.readthedocs.io/en/latest/spec/distributing.html#import-conventions>
+
+## Builtins scope
+
+When looking up for a name, red knot will fallback to using the builtins scope if the name is not
+found in the global scope. The `builtins.pyi` file, that will be used to resolve any symbol in the
+builtins scope, contains multiple symbols from other modules (e.g., `typing`) but those are not
+re-exported.
+
+```py
+# These symbols are being imported in `builtins.pyi` but shouldn't be considered as being
+# available in the builtins scope.
+
+# error: "Name `Literal` used when not defined"
+reveal_type(Literal)  # revealed: Unknown
+
+# error: "Name `sys` used when not defined"
+reveal_type(sys)  # revealed: Unknown
+```
+
+## Builtins import
+
+Similarly, trying to import the symbols from the builtins module which aren't re-exported should
+also raise an error.
+
+```py
+# error: "Module `builtins` has no member `Literal`"
+# error: "Module `builtins` has no member `sys`"
+from builtins import Literal, sys
+
+reveal_type(Literal)  # revealed: Unknown
+reveal_type(sys)  # revealed: Unknown
+
+# error: "Module `math` has no member `Iterable`"
+from math import Iterable
+
+reveal_type(Iterable)  # revealed: Unknown
+```
+
+## Re-exported symbols in stub files
+
+When a symbol is re-exported, importing it should not raise an error. This tests both `import ...`
+and `from ... import ...` forms.
+
+Note: Submodule imports in `import ...` form doesn't work because it's a syntax error. For example,
+in `import os.path as os.path` the `os.path` is not a valid identifier.
+
+```py
+from b import Any, Literal, foo
+
+reveal_type(Any)  # revealed: typing.Any
+reveal_type(Literal)  # revealed: typing.Literal
+reveal_type(foo)  # revealed: <module 'foo'>
+```
+
+`b.pyi`:
+
+```pyi
+import foo as foo
+from typing import Any as Any, Literal as Literal
+```
+
+`foo.py`:
+
+```py
+```
+
+## Non-exported symbols in stub files
+
+Here, none of the symbols are being re-exported in the stub file.
+
+```py
+# error: 15 [unresolved-import] "Module `b` has no member `foo`"
+# error: 20 [unresolved-import] "Module `b` has no member `Any`"
+# error: 25 [unresolved-import] "Module `b` has no member `Literal`"
+from b import foo, Any, Literal
+
+reveal_type(Any)  # revealed: Unknown
+reveal_type(Literal)  # revealed: Unknown
+reveal_type(foo)  # revealed: Unknown
+```
+
+`b.pyi`:
+
+```pyi
+import foo
+from typing import Any, Literal
+```
+
+`foo.pyi`:
+
+```pyi
+```
+
+## Nested non-exports
+
+Here, a chain of modules all don't re-export an import.
+
+```py
+# error: "Module `a` has no member `Any`"
+from a import Any
+
+reveal_type(Any)  # revealed: Unknown
+```
+
+`a.pyi`:
+
+```pyi
+# error: "Module `b` has no member `Any`"
+from b import Any
+
+reveal_type(Any)  # revealed: Unknown
+```
+
+`b.pyi`:
+
+```pyi
+# error: "Module `c` has no member `Any`"
+from c import Any
+
+reveal_type(Any)  # revealed: Unknown
+```
+
+`c.pyi`:
+
+```pyi
+from typing import Any
+
+reveal_type(Any)  # revealed: typing.Any
+```
+
+## Nested mixed re-export and not
+
+But, if the symbol is being re-exported explicitly in one of the modules in the chain, it should not
+raise an error at that step in the chain.
+
+```py
+# error: "Module `a` has no member `Any`"
+from a import Any
+
+reveal_type(Any)  # revealed: Unknown
+```
+
+`a.pyi`:
+
+```pyi
+from b import Any
+
+reveal_type(Any)  # revealed: Unknown
+```
+
+`b.pyi`:
+
+```pyi
+# error: "Module `c` has no member `Any`"
+from c import Any as Any
+
+reveal_type(Any)  # revealed: Unknown
+```
+
+`c.pyi`:
+
+```pyi
+from typing import Any
+
+reveal_type(Any)  # revealed: typing.Any
+```
+
+## Exported as different name
+
+The re-export convention only works when the aliased name is exactly the same as the original name.
+
+```py
+# error: "Module `a` has no member `Foo`"
+from a import Foo
+
+reveal_type(Foo)  # revealed: Unknown
+```
+
+`a.pyi`:
+
+```pyi
+from b import AnyFoo as Foo
+
+reveal_type(Foo)  # revealed: Literal[AnyFoo]
+```
+
+`b.pyi`:
+
+```pyi
+class AnyFoo: ...
+```
+
+## Exported using `__all__`
+
+Here, the symbol is re-exported using the `__all__` variable.
+
+```py
+# TODO: This should *not* be an error but we don't understand `__all__` yet.
+# error: "Module `a` has no member `Foo`"
+from a import Foo
+```
+
+`a.pyi`:
+
+```pyi
+from b import Foo
+
+__all__ = ['Foo']
+```
+
+`b.pyi`:
+
+```pyi
+class Foo: ...
+```
+
+## Re-exports in `__init__.pyi`
+
+Similarly, for an `__init__.pyi` (stub) file, importing a non-exported name should raise an error
+but the inference would be `Unknown`.
+
+```py
+# error: 15 "Module `a` has no member `Foo`"
+# error: 20 "Module `a` has no member `c`"
+from a import Foo, c, foo
+
+reveal_type(Foo)  # revealed: Unknown
+reveal_type(c)  # revealed: Unknown
+reveal_type(foo)  # revealed: <module 'a.foo'>
+```
+
+`a/__init__.pyi`:
+
+```pyi
+from .b import c
+from .foo import Foo
+```
+
+`a/foo.pyi`:
+
+```pyi
+class Foo: ...
+```
+
+`a/b/__init__.pyi`:
+
+```pyi
+```
+
+`a/b/c.pyi`:
+
+```pyi
+```
+
+## Conditional re-export in stub file
+
+The following scenarios are when a re-export happens conditionally in a stub file.
+
+### Global import
+
+```py
+# error: "Member `Foo` of module `a` is possibly unbound"
+from a import Foo
+
+reveal_type(Foo)  # revealed: str
+```
+
+`a.pyi`:
+
+```pyi
+from b import Foo
+
+def coinflip() -> bool: ...
+
+if coinflip():
+    Foo: str = ...
+
+reveal_type(Foo)  # revealed: Literal[Foo] | str
+```
+
+`b.pyi`:
+
+```pyi
+class Foo: ...
+```
+
+### Both branch is an import
+
+Here, both the branches of the condition are import statements where one of them re-exports while
+the other does not.
+
+```py
+# error: "Member `Foo` of module `a` is possibly unbound"
+from a import Foo
+
+reveal_type(Foo)  # revealed: Literal[Foo]
+```
+
+`a.pyi`:
+
+```pyi
+def coinflip() -> bool: ...
+
+if coinflip():
+    from b import Foo
+else:
+    from b import Foo as Foo
+
+reveal_type(Foo)  # revealed: Literal[Foo]
+```
+
+`b.pyi`:
+
+```pyi
+class Foo: ...
+```
+
+### Re-export in one branch
+
+```py
+# error: "Member `Foo` of module `a` is possibly unbound"
+from a import Foo
+
+reveal_type(Foo)  # revealed: Literal[Foo]
+```
+
+`a.pyi`:
+
+```pyi
+def coinflip() -> bool: ...
+
+if coinflip():
+    from b import Foo as Foo
+```
+
+`b.pyi`:
+
+```pyi
+class Foo: ...
+```
+
+### Non-export in one branch
+
+```py
+# error: "Module `a` has no member `Foo`"
+from a import Foo
+
+reveal_type(Foo)  # revealed: Unknown
+```
+
+`a.pyi`:
+
+```pyi
+def coinflip() -> bool: ...
+
+if coinflip():
+    from b import Foo
+```
+
+`b.pyi`:
+
+```pyi
+class Foo: ...
+```

crates/red_knot_python_semantic/resources/mdtest/import/errors.md

@@ -18,7 +18,9 @@ reveal_type(baz)  # revealed: Unknown
 
 ## Unresolved import from resolved module
 
-```py path=a.py
+`a.py`:
+
+```py
 ```
 
 ```py
@@ -29,7 +31,9 @@ reveal_type(thing)  # revealed: Unknown
 
 ## Resolved import of symbol from unresolved import
 
-```py path=a.py
+`a.py`:
+
+```py
 import foo as foo  # error: "Cannot resolve import `foo`"
 
 reveal_type(foo)  # revealed: Unknown
@@ -46,7 +50,9 @@ reveal_type(foo)  # revealed: Unknown
 
 ## No implicit shadowing
 
-```py path=b.py
+`b.py`:
+
+```py
 x: int
 ```
 
@@ -58,7 +64,9 @@ x = "foo"  # error: [invalid-assignment] "Object of type `Literal["foo"]"
 
 ## Import cycle
 
-```py path=a.py
+`a.py`:
+
+```py
 class A: ...
 
 reveal_type(A.__mro__)  # revealed: tuple[Literal[A], Literal[object]]
@@ -69,7 +77,9 @@ class C(b.B): ...
 reveal_type(C.__mro__)  # revealed: tuple[Literal[C], Literal[B], Literal[A], Literal[object]]
 ```
 
-```py path=b.py
+`b.py`:
+
+```py
 from a import A
 
 class B(A): ...

crates/red_knot_python_semantic/resources/mdtest/import/invalid_syntax.md

@@ -23,9 +23,13 @@ reveal_type(b)  # revealed: <module 'a.b'>
 reveal_type(b.c)  # revealed: int
 ```
 
-```py path=a/__init__.py
+`a/__init__.py`:
+
+```py
 ```
 
-```py path=a/b.py
+`a/b.py`:
+
+```py
 c: int = 1
 ```

crates/red_knot_python_semantic/resources/mdtest/import/relative.md

@@ -2,10 +2,14 @@
 
 ## Non-existent
 
-```py path=package/__init__.py
+`package/__init__.py`:
+
+```py
 ```
 
-```py path=package/bar.py
+`package/bar.py`:
+
+```py
 from .foo import X  # error: [unresolved-import]
 
 reveal_type(X)  # revealed: Unknown
@@ -13,14 +17,20 @@ reveal_type(X)  # revealed: Unknown
 
 ## Simple
 
-```py path=package/__init__.py
+`package/__init__.py`:
+
+```py
 ```
 
-```py path=package/foo.py
+`package/foo.py`:
+
+```py
 X: int = 42
 ```
 
-```py path=package/bar.py
+`package/bar.py`:
+
+```py
 from .foo import X
 
 reveal_type(X)  # revealed: int
@@ -28,14 +38,20 @@ reveal_type(X)  # revealed: int
 
 ## Dotted
 
-```py path=package/__init__.py
+`package/__init__.py`:
+
+```py
 ```
 
-```py path=package/foo/bar/baz.py
+`package/foo/bar/baz.py`:
+
+```py
 X: int = 42
 ```
 
-```py path=package/bar.py
+`package/bar.py`:
+
+```py
 from .foo.bar.baz import X
 
 reveal_type(X)  # revealed: int
@@ -43,11 +59,15 @@ reveal_type(X)  # revealed: int
 
 ## Bare to package
 
-```py path=package/__init__.py
+`package/__init__.py`:
+
+```py
 X: int = 42
 ```
 
-```py path=package/bar.py
+`package/bar.py`:
+
+```py
 from . import X
 
 reveal_type(X)  # revealed: int
@@ -55,7 +75,9 @@ reveal_type(X)  # revealed: int
 
 ## Non-existent + bare to package
 
-```py path=package/bar.py
+`package/bar.py`:
+
+```py
 from . import X  # error: [unresolved-import]
 
 reveal_type(X)  # revealed: Unknown
@@ -63,19 +85,25 @@ reveal_type(X)  # revealed: Unknown
 
 ## Dunder init
 
-```py path=package/__init__.py
+`package/__init__.py`:
+
+```py
 from .foo import X
 
 reveal_type(X)  # revealed: int
 ```
 
-```py path=package/foo.py
+`package/foo.py`:
+
+```py
 X: int = 42
 ```
 
 ## Non-existent + dunder init
 
-```py path=package/__init__.py
+`package/__init__.py`:
+
+```py
 from .foo import X  # error: [unresolved-import]
 
 reveal_type(X)  # revealed: Unknown
@@ -83,14 +111,20 @@ reveal_type(X)  # revealed: Unknown
 
 ## Long relative import
 
-```py path=package/__init__.py
+`package/__init__.py`:
+
+```py
 ```
 
-```py path=package/foo.py
+`package/foo.py`:
+
+```py
 X: int = 42
 ```
 
-```py path=package/subpackage/subsubpackage/bar.py
+`package/subpackage/subsubpackage/bar.py`:
+
+```py
 from ...foo import X
 
 reveal_type(X)  # revealed: int
@@ -98,14 +132,20 @@ reveal_type(X)  # revealed: int
 
 ## Unbound symbol
 
-```py path=package/__init__.py
+`package/__init__.py`:
+
+```py
 ```
 
-```py path=package/foo.py
+`package/foo.py`:
+
+```py
 x  # error: [unresolved-reference]
 ```
 
-```py path=package/bar.py
+`package/bar.py`:
+
+```py
 from .foo import x  # error: [unresolved-import]
 
 reveal_type(x)  # revealed: Unknown
@@ -113,14 +153,20 @@ reveal_type(x)  # revealed: Unknown
 
 ## Bare to module
 
-```py path=package/__init__.py
+`package/__init__.py`:
+
+```py
 ```
 
-```py path=package/foo.py
+`package/foo.py`:
+
+```py
 X: int = 42
 ```
 
-```py path=package/bar.py
+`package/bar.py`:
+
+```py
 from . import foo
 
 reveal_type(foo.X)  # revealed: int
@@ -131,10 +177,14 @@ reveal_type(foo.X)  # revealed: int
 This test verifies that we emit an error when we try to import a symbol that is neither a submodule
 nor an attribute of `package`.
 
-```py path=package/__init__.py
+`package/__init__.py`:
+
+```py
 ```
 
-```py path=package/bar.py
+`package/bar.py`:
+
+```py
 from . import foo  # error: [unresolved-import]
 
 reveal_type(foo)  # revealed: Unknown
@@ -148,17 +198,41 @@ submodule when that submodule name appears in the `imported_modules` set. That m
 that are imported via `from...import` are not visible to our type inference if you also access that
 submodule via the attribute on its parent package.
 
-```py path=package/__init__.py
+`package/__init__.py`:
+
+```py
 ```
 
-```py path=package/foo.py
+`package/foo.py`:
+
+```py
 X: int = 42
 ```
 
-```py path=package/bar.py
+`package/bar.py`:
+
+```py
 from . import foo
 import package
 
 # error: [unresolved-attribute] "Type `<module 'package'>` has no attribute `foo`"
 reveal_type(package.foo.X)  # revealed: Unknown
 ```
+
+## Relative imports at the top of a search path
+
+Relative imports at the top of a search path result in a runtime error:
+`ImportError: attempted relative import with no known parent package`. That's why Red Knot should
+disallow them.
+
+`parser.py`:
+
+```py
+X: int = 42
+```
+
+`__main__.py`:
+
+```py
+from .parser import X  # error: [unresolved-import]
+```

crates/red_knot_python_semantic/resources/mdtest/import/stubs.md

@@ -9,7 +9,9 @@ y = x
 reveal_type(y)  # revealed: int
 ```
 
-```py path=b.pyi
+`b.pyi`:
+
+```pyi
 x: int
 ```
 
@@ -22,6 +24,8 @@ y = x
 reveal_type(y)  # revealed: int
 ```
 
-```py path=b.py
+`b.py`:
+
+```py
 x: int = 1
 ```

crates/red_knot_python_semantic/resources/mdtest/import/tracking.md

@@ -32,10 +32,14 @@ reveal_type(a.b.C)  # revealed: Literal[C]
 import a.b
 ```
 
-```py path=a/__init__.py
+`a/__init__.py`:
+
+```py
 ```
 
-```py path=a/b.py
+`a/b.py`:
+
+```py
 class C: ...
 ```
 
@@ -55,14 +59,20 @@ reveal_type(a.b)  # revealed: <module 'a.b'>
 reveal_type(a.b.C)  # revealed: Literal[C]
 ```
 
-```py path=a/__init__.py
+`a/__init__.py`:
+
+```py
 ```
 
-```py path=a/b.py
+`a/b.py`:
+
+```py
 class C: ...
 ```
 
-```py path=q.py
+`q.py`:
+
+```py
 import a as a
 import a.b as b
 ```
@@ -83,18 +93,26 @@ reveal_type(sub.b)  # revealed: <module 'sub.b'>
 reveal_type(attr.b)  # revealed: <module 'attr.b'>
 ```
 
-```py path=sub/__init__.py
+`sub/__init__.py`:
+
+```py
 b = 1
 ```
 
-```py path=sub/b.py
+`sub/b.py`:
+
+```py
 ```
 
-```py path=attr/__init__.py
+`attr/__init__.py`:
+
+```py
 from . import b as _
 
 b = 1
 ```
 
-```py path=attr/b.py
+`attr/b.py`:
+
+```py
 ```

crates/red_knot_python_semantic/resources/mdtest/intersection_types.md

@@ -808,6 +808,7 @@ Dynamic types do not cancel each other out. Intersecting an unknown set of value
 of another unknown set of values is not necessarily empty, so we keep the positive contribution:
 
 ```py
+from typing import Any
 from knot_extensions import Intersection, Not, Unknown
 
 def any(
@@ -830,6 +831,7 @@ def unknown(
 We currently do not simplify mixed dynamic types, but might consider doing so in the future:
 
 ```py
+from typing import Any
 from knot_extensions import Intersection, Not, Unknown
 
 def mixed(

crates/red_knot_python_semantic/resources/mdtest/known_constants.md

@@ -31,7 +31,9 @@ reveal_type(TC)  # revealed: Literal[True]
 Make sure we only use our special handling for `typing.TYPE_CHECKING` and not for other constants
 with the same name:
 
-```py path=constants.py
+`constants.py`:
+
+```py
 TYPE_CHECKING: bool = False
 ```
 

crates/red_knot_python_semantic/resources/mdtest/loops/for.md

@@ -183,25 +183,32 @@ for x in Test():
 ## Union type as iterable and union type as iterator
 
 ```py
-class TestIter:
-    def __next__(self) -> int | Exception:
-        return 42
+class Result1A: ...
+class Result1B: ...
+class Result2A: ...
+class Result2B: ...
+class Result3: ...
+class Result4: ...
+
+class TestIter1:
+    def __next__(self) -> Result1A | Result1B:
+        return Result1B()
 
 class TestIter2:
-    def __next__(self) -> str | tuple[int, int]:
-        return "42"
+    def __next__(self) -> Result2A | Result2B:
+        return Result2B()
 
 class TestIter3:
-    def __next__(self) -> bytes:
-        return b"42"
+    def __next__(self) -> Result3:
+        return Result3()
 
 class TestIter4:
-    def __next__(self) -> memoryview:
-        return memoryview(b"42")
+    def __next__(self) -> Result4:
+        return Result4()
 
 class Test:
-    def __iter__(self) -> TestIter | TestIter2:
-        return TestIter()
+    def __iter__(self) -> TestIter1 | TestIter2:
+        return TestIter1()
 
 class Test2:
     def __iter__(self) -> TestIter3 | TestIter4:
@@ -209,7 +216,7 @@ class Test2:
 
 def _(flag: bool):
     for x in Test() if flag else Test2():
-        reveal_type(x)  # revealed: int | Exception | str | tuple[int, int] | bytes | memoryview
+        reveal_type(x)  # revealed: Result1A | Result1B | Result2A | Result2B | Result3 | Result4
 ```
 
 ## Union type as iterable where one union element has no `__iter__` method
@@ -245,9 +252,10 @@ class Test2:
         return 42
 
 def _(flag: bool):
+    # TODO: Improve error message to state which union variant isn't iterable (https://github.com/astral-sh/ruff/issues/13989)
     # error: "Object of type `Test | Test2` is not iterable"
     for x in Test() if flag else Test2():
-        reveal_type(x)  # revealed: Unknown
+        reveal_type(x)  # revealed: int
 ```
 
 ## Union type as iterator where one union element has no `__next__` method
@@ -263,5 +271,5 @@ class Test:
 
 # error: [not-iterable] "Object of type `Test` is not iterable"
 for x in Test():
-    reveal_type(x)  # revealed: Unknown
+    reveal_type(x)  # revealed: int
 ```

crates/red_knot_python_semantic/resources/mdtest/mdtest_config.md

@@ -13,6 +13,8 @@ python-version = "3.10"
 Here, we simply make sure that we pick up the global configuration from the root section:
 
 ```py
+import sys
+
 reveal_type(sys.version_info[:2] == (3, 10))  # revealed: Literal[True]
 ```
 
@@ -25,6 +27,8 @@ reveal_type(sys.version_info[:2] == (3, 10))  # revealed: Literal[True]
 The same should work for arbitrarily nested sections:
 
 ```py
+import sys
+
 reveal_type(sys.version_info[:2] == (3, 10))  # revealed: Literal[True]
 ```
 
@@ -38,6 +42,8 @@ python-version = "3.11"
 ```
 
 ```py
+import sys
+
 reveal_type(sys.version_info[:2] == (3, 11))  # revealed: Literal[True]
 ```
 
@@ -46,6 +52,8 @@ reveal_type(sys.version_info[:2] == (3, 11))  # revealed: Literal[True]
 There is no global state. This section should again use the root configuration:
 
 ```py
+import sys
+
 reveal_type(sys.version_info[:2] == (3, 10))  # revealed: Literal[True]
 ```
 
@@ -63,5 +71,7 @@ python-version = "3.12"
 ### Grandchild
 
 ```py
+import sys
+
 reveal_type(sys.version_info[:2] == (3, 12))  # revealed: Literal[True]
 ```

crates/red_knot_python_semantic/resources/mdtest/mdtest_custom_typeshed.md

@@ -19,13 +19,17 @@ typeshed = "/typeshed"
 
 We can then place custom stub files in `/typeshed/stdlib`, for example:
 
-```pyi path=/typeshed/stdlib/builtins.pyi
+`/typeshed/stdlib/builtins.pyi`:
+
+```pyi
 class BuiltinClass: ...
 
 builtin_symbol: BuiltinClass
 ```
 
-```pyi path=/typeshed/stdlib/sys/__init__.pyi
+`/typeshed/stdlib/sys/__init__.pyi`:
+
+```pyi
 version = "my custom Python"
 ```
 
@@ -54,15 +58,21 @@ python-version = "3.10"
 typeshed = "/typeshed"
 ```
 
-```pyi path=/typeshed/stdlib/old_module.pyi
+`/typeshed/stdlib/old_module.pyi`:
+
+```pyi
 class OldClass: ...
 ```
 
-```pyi path=/typeshed/stdlib/new_module.pyi
+`/typeshed/stdlib/new_module.pyi`:
+
+```pyi
 class NewClass: ...
 ```
 
-```text path=/typeshed/stdlib/VERSIONS
+`/typeshed/stdlib/VERSIONS`:
+
+```text
 old_module: 3.0-
 new_module: 3.11-
 ```
@@ -86,7 +96,9 @@ simple untyped definition is enough to make `reveal_type` work in tests:
 typeshed = "/typeshed"
 ```
 
-```pyi path=/typeshed/stdlib/typing_extensions.pyi
+`/typeshed/stdlib/typing_extensions.pyi`:
+
+```pyi
 def reveal_type(obj, /): ...
 ```
 

crates/red_knot_python_semantic/resources/mdtest/metaclass.md

@@ -205,7 +205,7 @@ reveal_type(D.__class__)  # revealed: Literal[SignatureMismatch]
 
 Retrieving the metaclass of a cyclically defined class should not cause an infinite loop.
 
-```py path=a.pyi
+```pyi
 class A(B): ...  # error: [cyclic-class-definition]
 class B(C): ...  # error: [cyclic-class-definition]
 class C(A): ...  # error: [cyclic-class-definition]