[ty] Fix super() with TypeVar-annotated self and cls parameter (#22208)

## Summary

This PR fixes `super()` handling when the first parameter (`self` or
`cls`) is annotated with a TypeVar, like `Self`.

Previously, `super()` would incorrectly resolve TypeVars to their bounds
before creating the `BoundSuperType`. So if you had `self: Self` where
`Self` is bounded by `Parent`, we'd process `Parent` as a
`NominalInstance` and end up with `SuperOwnerKind::Instance(Parent)`.

As a result:

```python
class Parent:
    @classmethod
    def create(cls) -> Self:
        return cls()

class Child(Parent):
    @classmethod
    def create(cls) -> Self:
        return super().create()  # Error: Argument type `Self@create` does not satisfy upper bound `Parent`
```

We now track two additional variants on `SuperOwnerKind` for TypeVar
owners:

- `InstanceTypeVar`: for instance methods where self is a TypeVar (e.g.,
`self: Self`).
- `ClassTypeVar`: for classmethods where `cls` is a `TypeVar` wrapped in
`type[...]` (e.g., `cls: type[Self]`).

Closes astral-sh/ty#2122.

---------

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

Author: charliermarsh

crates/ty_python_semantic/resources/mdtest/annotations/self.md

@@ -359,6 +359,51 @@ reveal_type(GenericCircle[int].bar())  # revealed: GenericCircle[int]
 reveal_type(GenericCircle.baz(1))  # revealed: GenericShape[Literal[1]]
 ```
 
+### Calling `super()` in overridden methods with `Self` return type
+
+This is a regression test for <https://github.com/astral-sh/ty/issues/2122>.
+
+When a child class overrides a parent method with a `Self` return type and calls `super().method()`,
+the return type should be the child's `Self` type variable, not the concrete child class type.
+
+```py
+from typing import Self
+
+class Parent:
+    def copy(self) -> Self:
+        return self
+
+class Child(Parent):
+    def copy(self) -> Self:
+        result = super().copy()
+        reveal_type(result)  # revealed: Self@copy
+        return result
+
+# When called on concrete types, Self is substituted correctly.
+reveal_type(Child().copy())  # revealed: Child
+```
+
+The same applies to classmethods with `Self` return types:
+
+```py
+from typing import Self
+
+class Parent:
+    @classmethod
+    def create(cls) -> Self:
+        return cls()
+
+class Child(Parent):
+    @classmethod
+    def create(cls) -> Self:
+        result = super().create()
+        reveal_type(result)  # revealed: Self@create
+        return result
+
+# When called on concrete types, Self is substituted correctly.
+reveal_type(Child.create())  # revealed: Child
+```
+
 ## Attributes
 
 TODO: The use of `Self` to annotate the `next_node` attribute should be

crates/ty_python_semantic/resources/mdtest/class/super.md

@@ -168,13 +168,13 @@ class A:
 
 class B(A):
     def __init__(self, a: int):
-        reveal_type(super())  # revealed: <super: <class 'B'>, B>
+        reveal_type(super())  # revealed: <super: <class 'B'>, Self@__init__>
         reveal_type(super(object, super()))  # revealed: <super: <class 'object'>, super>
         super().__init__(a)
 
     @classmethod
     def f(cls):
-        reveal_type(super())  # revealed: <super: <class 'B'>, <class 'B'>>
+        reveal_type(super())  # revealed: <super: <class 'B'>, type[Self@f]>
         super().f()
 
 super(B, B(42)).__init__(42)
@@ -229,16 +229,16 @@ class Foo[T]:
         reveal_type(super())
 
     def method4(self: Self):
-        # revealed: <super: <class 'Foo'>, Foo[T@Foo]>
+        # revealed: <super: <class 'Foo'>, Self@method4>
         reveal_type(super())
 
     def method5[S: Foo[int]](self: S, other: S) -> S:
-        # revealed: <super: <class 'Foo'>, Foo[int]>
+        # revealed: <super: <class 'Foo'>, S@method5>
         reveal_type(super())
         return self
 
     def method6[S: (Foo[int], Foo[str])](self: S, other: S) -> S:
-        # revealed: <super: <class 'Foo'>, Foo[int]> | <super: <class 'Foo'>, Foo[str]>
+        # revealed: <super: <class 'Foo'>, S@method6> | <super: <class 'Foo'>, S@method6>
         reveal_type(super())
         return self
 
@@ -265,6 +265,19 @@ class Foo[T]:
         # revealed: Unknown
         reveal_type(super())
         return self
+    # TypeVar bounded by `type[Foo]` rather than `Foo`
+    # TODO: Should error on signature - `self` is annotated as a class type, not an instance type
+    def method11[S: type[Foo[int]]](self: S, other: S) -> S:
+        # Delegates to the bound to resolve the super type
+        reveal_type(super())  # revealed: <super: <class 'Foo'>, <class 'Foo[int]'>>
+        return self
+    # TypeVar bounded by `type[Foo]`, used in `type[T]` position
+    # TODO: Should error on signature - `cls` would be `type[type[Foo[int]]]`, a metaclass
+    # Delegates to `type[Unknown]` since `type[type[Foo[int]]]` can't be constructed
+    @classmethod
+    def method12[S: type[Foo[int]]](cls: type[S]) -> S:
+        reveal_type(super())  # revealed: <super: <class 'Foo'>, Unknown>
+        raise NotImplementedError
 
 type Alias = Bar
 
@@ -359,15 +372,15 @@ from __future__ import annotations
 
 class A:
     def test(self):
-        reveal_type(super())  # revealed: <super: <class 'A'>, A>
+        reveal_type(super())  # revealed: <super: <class 'A'>, Self@test>
 
     class B:
         def test(self):
-            reveal_type(super())  # revealed: <super: <class 'B'>, B>
+            reveal_type(super())  # revealed: <super: <class 'B'>, Self@test>
 
             class C(A.B):
                 def test(self):
-                    reveal_type(super())  # revealed: <super: <class 'C'>, C>
+                    reveal_type(super())  # revealed: <super: <class 'C'>, Self@test>
 
             def inner(t: C):
                 reveal_type(super())  # revealed: <super: <class 'B'>, C>
@@ -645,7 +658,7 @@ class A:
 class B(A):
     def __init__(self, a: int):
         super().__init__(a)
-        # error: [unresolved-attribute] "Object of type `<super: <class 'B'>, B>` has no attribute `a`"
+        # error: [unresolved-attribute] "Object of type `<super: <class 'B'>, Self@__init__>` has no attribute `a`"
         super().a
 
 # error: [unresolved-attribute] "Object of type `<super: <class 'B'>, B>` has no attribute `a`"
@@ -670,3 +683,58 @@ reveal_type(super(B, B()).__getitem__)  # revealed: bound method B.__getitem__(k
 # error: [not-subscriptable] "Cannot subscript object of type `<super: <class 'B'>, B>` with no `__getitem__` method"
 super(B, B())[0]
 ```
+
+## Subclass Using Concrete Type Instead of `Self`
+
+When a parent class uses `Self` in a parameter type and a subclass overrides it with a concrete
+type, passing that parameter to `super().__init__()` is a type error. This is because `Self` in the
+parent could represent a further subclass. The fix is to use `Self` consistently in the subclass.
+
+```toml
+[environment]
+python-version = "3.12"
+```
+
+```py
+from __future__ import annotations
+from collections.abc import Mapping
+from typing import Self
+
+class Parent:
+    def __init__(self, children: Mapping[str, Self] | None = None) -> None:
+        self.children = children
+
+class Child(Parent):
+    def __init__(self, children: Mapping[str, Child] | None = None) -> None:
+        # error: [invalid-argument-type] "Argument to bound method `__init__` is incorrect: Expected `Mapping[str, Self@__init__] | None`, found `Mapping[str, Child] | None`"
+        super().__init__(children)
+
+# The fix is to use `Self` consistently in the subclass:
+
+class Parent2:
+    def __init__(self, children: Mapping[str, Self] | None = None) -> None:
+        self.children = children
+
+class Child2(Parent2):
+    def __init__(self, children: Mapping[str, Self] | None = None) -> None:
+        super().__init__(children)  # OK
+```
+
+## Super in Protocol Classes
+
+Using `super()` in a class that inherits from `typing.Protocol` (similar to beartype's caching
+Protocol):
+
+```py
+from typing import Protocol, Generic, TypeVar
+
+_T_co = TypeVar("_T_co", covariant=True)
+
+class MyProtocol(Protocol, Generic[_T_co]):
+    def __class_getitem__(cls, item):
+        # Accessing parent's __class_getitem__ through super()
+        reveal_type(super())  # revealed: <super: <class 'MyProtocol'>, type[Self@__class_getitem__]>
+        parent_method = super().__class_getitem__
+        reveal_type(parent_method)  # revealed: @Todo(super in generic class)
+        return parent_method(item)
+```

crates/ty_python_semantic/resources/mdtest/snapshots/super.md_-_Super_-_Basic_Usage_-_Implicit_Super_Objec…_(f9e5e48e3a4a4c12).snap

@@ -22,13 +22,13 @@ mdtest path: crates/ty_python_semantic/resources/mdtest/class/super.md
   7 | 
   8 | class B(A):
   9 |     def __init__(self, a: int):
- 10 |         reveal_type(super())  # revealed: <super: <class 'B'>, B>
+ 10 |         reveal_type(super())  # revealed: <super: <class 'B'>, Self@__init__>
  11 |         reveal_type(super(object, super()))  # revealed: <super: <class 'object'>, super>
  12 |         super().__init__(a)
  13 | 
  14 |     @classmethod
  15 |     def f(cls):
- 16 |         reveal_type(super())  # revealed: <super: <class 'B'>, <class 'B'>>
+ 16 |         reveal_type(super())  # revealed: <super: <class 'B'>, type[Self@f]>
  17 |         super().f()
  18 | 
  19 | super(B, B(42)).__init__(42)
@@ -78,16 +78,16 @@ mdtest path: crates/ty_python_semantic/resources/mdtest/class/super.md
  63 |         reveal_type(super())
  64 | 
  65 |     def method4(self: Self):
- 66 |         # revealed: <super: <class 'Foo'>, Foo[T@Foo]>
+ 66 |         # revealed: <super: <class 'Foo'>, Self@method4>
  67 |         reveal_type(super())
  68 | 
  69 |     def method5[S: Foo[int]](self: S, other: S) -> S:
- 70 |         # revealed: <super: <class 'Foo'>, Foo[int]>
+ 70 |         # revealed: <super: <class 'Foo'>, S@method5>
  71 |         reveal_type(super())
  72 |         return self
  73 | 
  74 |     def method6[S: (Foo[int], Foo[str])](self: S, other: S) -> S:
- 75 |         # revealed: <super: <class 'Foo'>, Foo[int]> | <super: <class 'Foo'>, Foo[str]>
+ 75 |         # revealed: <super: <class 'Foo'>, S@method6> | <super: <class 'Foo'>, S@method6>
  76 |         reveal_type(super())
  77 |         return self
  78 | 
@@ -114,35 +114,48 @@ mdtest path: crates/ty_python_semantic/resources/mdtest/class/super.md
  99 |         # revealed: Unknown
 100 |         reveal_type(super())
 101 |         return self
-102 | 
-103 | type Alias = Bar
-104 | 
-105 | class Bar:
-106 |     def method(self: Alias):
-107 |         # revealed: <super: <class 'Bar'>, Bar>
-108 |         reveal_type(super())
-109 | 
-110 |     def pls_dont_call_me(self: Never):
-111 |         # revealed: <super: <class 'Bar'>, Unknown>
-112 |         reveal_type(super())
-113 | 
-114 |     def only_call_me_on_callable_subclasses(self: Intersection[Bar, Callable[..., object]]):
-115 |         # revealed: <super: <class 'Bar'>, Bar>
-116 |         reveal_type(super())
+102 |     # TypeVar bounded by `type[Foo]` rather than `Foo`
+103 |     # TODO: Should error on signature - `self` is annotated as a class type, not an instance type
+104 |     def method11[S: type[Foo[int]]](self: S, other: S) -> S:
+105 |         # Delegates to the bound to resolve the super type
+106 |         reveal_type(super())  # revealed: <super: <class 'Foo'>, <class 'Foo[int]'>>
+107 |         return self
+108 |     # TypeVar bounded by `type[Foo]`, used in `type[T]` position
+109 |     # TODO: Should error on signature - `cls` would be `type[type[Foo[int]]]`, a metaclass
+110 |     # Delegates to `type[Unknown]` since `type[type[Foo[int]]]` can't be constructed
+111 |     @classmethod
+112 |     def method12[S: type[Foo[int]]](cls: type[S]) -> S:
+113 |         reveal_type(super())  # revealed: <super: <class 'Foo'>, Unknown>
+114 |         raise NotImplementedError
+115 | 
+116 | type Alias = Bar
 117 | 
-118 | class P(Protocol):
-119 |     def method(self: P):
-120 |         # revealed: <super: <class 'P'>, P>
+118 | class Bar:
+119 |     def method(self: Alias):
+120 |         # revealed: <super: <class 'Bar'>, Bar>
 121 |         reveal_type(super())
 122 | 
-123 | class E(enum.Enum):
-124 |     X = 1
-125 | 
-126 |     def method(self: E):
-127 |         match self:
-128 |             case E.X:
-129 |                 # revealed: <super: <class 'E'>, E>
-130 |                 reveal_type(super())
+123 |     def pls_dont_call_me(self: Never):
+124 |         # revealed: <super: <class 'Bar'>, Unknown>
+125 |         reveal_type(super())
+126 | 
+127 |     def only_call_me_on_callable_subclasses(self: Intersection[Bar, Callable[..., object]]):
+128 |         # revealed: <super: <class 'Bar'>, Bar>
+129 |         reveal_type(super())
+130 | 
+131 | class P(Protocol):
+132 |     def method(self: P):
+133 |         # revealed: <super: <class 'P'>, P>
+134 |         reveal_type(super())
+135 | 
+136 | class E(enum.Enum):
+137 |     X = 1
+138 | 
+139 |     def method(self: E):
+140 |         match self:
+141 |             case E.X:
+142 |                 # revealed: <super: <class 'E'>, E>
+143 |                 reveal_type(super())
 ```
 
 # Diagnostics
@@ -205,6 +218,7 @@ error[invalid-super-argument]: `S@method10` is a type variable with an abstract/
 100 |         reveal_type(super())
     |                     ^^^^^^^
 101 |         return self
+102 |     # TypeVar bounded by `type[Foo]` rather than `Foo`
     |
 info: Type variable `S` has upper bound `(...) -> str`
 info: rule `invalid-super-argument` is enabled by default