Allow subclass receivers on overloaded constructors

[Divyansh151005]

Summary

Overloads of __init__ and __new__ may annotate the receiver with a subclass of the defining class, so that constructing via that subclass selects a more specific overload:

class Path:
    @overload
    def __new__(cls: type[AbsPath], path: str) -> AbsPath: ...
    @overload
    def __new__(cls: type[RelPath], path: str) -> RelPath: ...
    @overload
    def __new__(cls: type[Path], path: str) -> AbsPath | RelPath: ...
    def __new__(cls: type[Path], path: str) -> Path: ...

class AbsPath(Path): ...
class RelPath(Path): ...

Pyrefly rejected these receivers as "not a superclass" of the defining class.

This change keeps constructor receiver validation in place and only widens the accepted set: on overload variants of __init__/__new__, a receiver whose class is a subclass of the defining class is also accepted. Everything else is unchanged:

• non-overloaded constructors and the overload implementation are validated as before;
• receivers of unrelated classes are still rejected on overloads (test_init_bad_receiver_annotation, test_new_bad_receiver_annotation unchanged);
• the __init__ class-scoped type parameter check still runs on overloads (test_constructor_overload_with_hint, test_constructor_typevar_scope_overload pass).

Fixes #4701

Test Plan

New tests in pyrefly/lib/test/constructors.rs:

• test_new_overload_subclass_receiver: the Path example above, with assert_type on each constructor call.
• test_init_overload_subclass_receiver: same pattern for __init__.
• test_constructor_subclass_receiver_requires_overload: a subclass receiver on a non-overloaded __new__/__init__ is still an error.

$ cargo test -p pyrefly --lib -- receiver constructor_overload_with_hint typevar_scope
test test::constructors::test_new_overload_subclass_receiver ... ok
test test::constructors::test_init_overload_subclass_receiver ... ok
test test::constructors::test_constructor_subclass_receiver_requires_overload ... ok
test test::constructors::test_init_bad_receiver_annotation ... ok
test test::constructors::test_new_bad_receiver_annotation ... ok
test test::overload::test_constructor_overload_with_hint ... ok
test test::type_variable_scope::test_constructor_typevar_scope_overload ... ok
...
test result: ok. 46 passed; 0 failed

$ cargo test -p pyrefly --lib
all tests in test::constructors, test::overload, test::typing_self and
test::type_variable_scope pass (220)

[meta-cla]

Hi @Divyansh151005!

Thank you for your pull request and welcome to our community.

Action Required

In order to merge any pull request (code, docs, etc.), we require contributors to sign our Contributor License Agreement, and we don't seem to have one on file for you.

Process

In order for us to review and merge your suggested changes, please sign at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need to sign the corporate CLA.

Once the CLA is signed, our tooling will perform checks and validations. Afterwards, the pull request will be tagged with CLA signed. The tagging process may take up to 1 hour after signing. Please give it that time before contacting us about it.

If you have received this in error or have any questions, please contact us at cla@meta.com. Thanks!

[meta-cla]

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Meta Open Source project. Thanks!

[codspeed]

Merging this PR will degrade performance by 43.72%

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

❌ 1 regressed benchmark
✅ 34 untouched benchmarks
⏩ 9 skipped benchmarks¹

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
❌	invalidate_all	29.6 ms	52.6 ms	-43.72%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing Divyansh151005:fix/constructor-overload-subclass-receivers (076572b) with main (9a8b4be)}

Footnotes

1. 9 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[rchen152]

Thanks for the PR! Sorry for the slow review. I think skipping validation altogether is too broad of a change. It causes a couple test failures due to pyrefly no longer detecting legitimate errors: https://github.com/facebook/pyrefly/actions/runs/36653011442/job/109691230864?pr=4722.

[Divyansh151005]

@rchen152 thanks for the review, agreed that was too broad. I've reworked it so constructor overloads are still validated and the only change is that a receiver whose class is a subclass of the defining class is now accepted on overload variants of __init__/__new__.

So the two failures from that run (test_constructor_overload_with_hint and test_constructor_typevar_scope_overload) pass again, since the __init__ class-scoped type parameter check still runs on overloads, and the unrelated-class receiver errors in test_init_bad_receiver_annotation / test_new_bad_receiver_annotation are back to their original expectations. I also added a test that a subclass receiver on a non-overloaded constructor is still reported. Rebased on current main; test details are in the description.

[meta-codesync]

This pull request has been imported. If you are a Meta employee, you can view this in D125874447. (Because this pull request was imported automatically, there will not be any future comments.)

[github-actions]

According to mypy_primer, this change doesn't affect type check results on a corpus of open source code. ✅