Detect missing or incorrect overload defaults

Feature

Is it in-scope for either mypy or stubtest to detect incorrect or missing defaults in overloads?

Incorrect default

from typing import Literal, overload, reveal_type

@overload
def foo(a: Literal[True] = ...) -> None: ...
@overload
def foo(a: Literal[False]) -> int: ...
def foo(a: bool = False) -> None | int:
    return 1 if not a else None

reveal_type(foo())

Here, the default for a is False, yet the overload has a: Literal[True] = ..., meaning that foo() will be revealed to be of type None instead of type int

Missing overload example

from typing import Literal, overload

@overload
def foo(a: Literal[True]) -> None: ...
@overload
def foo(a: Literal[False]) -> int: ...
def foo(a: bool = False) -> None | int:
    return 1 if not a else None

The default for a is False, so the second overload should probably include a: Literal[False] = ...?

Pitch

I tried putting together a little static analysis tool to detect simple cases of the above: https://github.com/MarcoGorelli/fix-overload-defaults

It only uses ast parsing, and is very simple, so it can't detect much, but it was already enough to find issues in a few libraries where I tried it:

• https://github.com/numpy/numpy/pull/29331
• https://github.com/numpy/numpy/pull/29340
• https://github.com/pola-rs/polars/pull/23442
• https://github.com/pola-rs/polars/pull/23413
• https://github.com/narwhals-dev/narwhals/pull/2778

So, I figured that this might be broadly useful?

I'm much more bothered about detecting incorrect defaults than potentially missing ones. Might this be in-scope for mypy or mypy.stubtest?

Start by reviewing mypy and mypy.stubtest's existing overload checks, then compare them with the AST-based fix-overload-defaults tool linked in the issue. Validate behavior against the two foo examples and determine whether detecting incorrect defaults, missing defaults, or both is in scope.