[shuvroroy]

Local scopes on a custom Eloquent builder could lose the custom builder or infer a nested type such as PostBuilder<PostBuilder<Post>>|Post, breaking completion and reporting valid returns as type mismatches. Post::query()->published() now retains PostBuilder<Post> with or without ide-helper docblocks.

Scope resolution preserves real builder methods, registered macros, explicit non-builder results, and callback model inference. Regression tests cover inherited and attribute scopes, generic and non-generic builders, completion, hover, and return diagnostics. The Laravel playground includes a matching demo and runtime assertions.

Closes #571

Validation

• CI latency comparison passed all 100 paired benchmark cases with zero regressions. The go-to-definition, custom-builder, and WordPress cases measured head/base ratios of 1.016, 1.021, and 0.991.
• Full cargo test suite passed: 20,263 tests passed and 13 were ignored.
• cargo clippy --fix --allow-dirty -- -D warnings, cargo clippy --all-targets -- -D warnings, cargo fmt, and cargo fmt --check passed.
• cargo llvm-cov measured 100% coverage of the changed executable production Rust lines (38/38).
• PHP lint and runtime assertions passed for the PHP, Laravel, Symfony, Yii, WordPress, Drupal, and Tempest playgrounds.
• Framework analysis reported only Laravel's four intentional demo errors; all other playgrounds reported no errors.
• The original reproduction no longer reports type_mismatch_return.

The macOS linker emitted an unwind-table size warning during test builds.

Paired local release benchmarks against the PR base, using the same toolchain and normal Criterion sampling:

Case	Base	PR	PR / base
goto_definition_method	27.220 µs	27.267 µs	1.002
custom_builder_completion/custom_builder_deep_inheritance	38.797 µs	38.814 µs	1.000
wordpress_completion/stub_member_get_post	50.999 µs	52.104 µs	1.022

Checklist

If applicable:

• I have updated CHANGELOG.md
• I have updated the documentation (README.md, docs/, examples/)
• I have updated the config schema (config-schema.json) — not applicable; no configuration changes
• I have added/updated tests to cover my changes
• If I used AI tools, I have reviewed what they produced and can explain
  the changes and why they are needed.
• I have read through any AI-generated text, especially documentation,
  the changelog, and other user-facing content, and removed or corrected
  anything inaccurate, unclear, or unnecessary.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!