Laravel Builder-as-static forwarding

Author: AJenbo

docs/CHANGELOG.md

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Virtual member provider abstraction.** Introduced the `VirtualMemberProvider` trait and `VirtualMembers` struct in a new `virtual_members` module. This provides a priority-ordered pipeline for synthesizing members from `@method`/`@property` tags, `@mixin` classes, and framework-specific patterns (e.g. Laravel relationships, scopes, Builder forwarding). All completion and go-to-definition call sites now use the new `resolve_class_fully` entry point, which applies base inheritance resolution followed by virtual member providers. No providers are registered yet, so behavior is unchanged. This is the foundation for upcoming Laravel support.
 - **Laravel relationship properties.** Classes extending `Illuminate\Database\Eloquent\Model` now get virtual properties synthesized from relationship methods. A method returning `HasMany<Post, $this>` produces a `$posts` property typed as `\Illuminate\Database\Eloquent\Collection<Post>`, and `HasOne<Profile, $this>` produces a `$profile` property typed as `Profile`. Supports `HasOne`, `HasMany`, `BelongsTo`, `BelongsToMany`, `MorphOne`, `MorphMany`, `MorphTo`, `MorphToMany`, and `HasManyThrough`. Generic type parameters are extracted from Larastan-style `@return` annotations. The synthesized properties sit at the highest virtual member priority, beating `@property` tags from ide-helper and `@mixin` members. Works with `$this->`, instance variables, relationship methods defined in traits, indirect Model subclasses (through a BaseModel), fully-qualified return types, and cross-file PSR-4 resolution. Chaining through relationship properties (e.g. `$user->profile->getBio()`) resolves to the related model's members.
 - **Laravel scope methods.** Methods starting with `scope` on Eloquent model classes (e.g. `scopeActive`, `scopeOfType`) now produce virtual methods with the prefix stripped and the first letter lowercased (`active`, `ofType`). The first `$query` parameter is removed since Laravel injects it automatically. Scope methods are available as both static and instance methods, so `User::active()` and `$user->active()` both resolve. If the scope method returns `void` or has no return type, the synthesized method defaults to `\Illuminate\Database\Eloquent\Builder<static>`. Custom return types and extra parameters beyond `$query` are preserved.
+- **Laravel Builder-as-static forwarding.** Static method calls on Eloquent model classes are forwarded to the Eloquent Builder. `User::where('email', $e)->orderBy('name')->get()` now resolves end-to-end. The provider loads `\Illuminate\Database\Eloquent\Builder`, fully resolves it (including `@mixin` members from `Query\Builder`), and presents its public instance methods as static virtual methods on the model. Return types are mapped so that `static`/`$this`/`self` on Builder resolve to `Builder<ConcreteModel>` (the chain continues on the builder), and template parameters like `TModel` resolve to the concrete model class. Methods like `get()` return `Collection<User>`, `first()` returns `User|null`, and chain methods like `where()` and `orderBy()` return `Builder<User>` for continued chaining. Works with indirect model subclasses, coexists with scope methods and relationship properties, and includes Query Builder methods forwarded via `@mixin`.
 - **Union completion sorting.** When a variable has a union type (e.g. `Dog|Cat` from a match or ternary), members shared by all types in the union (the intersection) now sort above members that only exist on a subset of types. Branch-only members display their originating class name as a label detail suffix, giving an at-a-glance visual hint in the completion popup. No completions are removed. Single-type completions are unaffected.
 - **Context-aware class name filtering.** Class name completions are now filtered by syntactic context. `extends` in a class declaration only offers non-final classes, `extends` in an interface only offers interfaces, `implements` offers interfaces only, `use` inside a class body offers traits only, and `instanceof` excludes traits. Constants and functions are also suppressed in these positions. Multi-line declarations and comma-separated lists are handled. Built-in (stub) classes are filtered correctly even before they are fully parsed, using a lightweight source scanner that detects the declaration keyword from the raw PHP source already in memory. Classmap entries whose source is not yet loaded pass through the filter since their kind is unknown.
 - **First-class callable syntax.** PHP 8.1's `strlen(...)`, `$obj->method(...)`, and `ClassName::method(...)` syntax now resolves correctly. The variable holding the callable is typed as `Closure` (for `$fn->bindTo()` etc.), and invoking it with `$fn()` resolves to the underlying function or method's return type. Works with function references, instance methods, static methods, `$this->method(...)`, `self::method(...)`, chained calls on the result, and cross-file resolution.
@@ -46,6 +47,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Go-to-definition on foreach variable no longer jumps to a previous loop.** When the same variable name appeared in consecutive `foreach` loops, clicking `$b` in the second loop's `as $b` clause incorrectly jumped to the first loop. The resolver now checks whether the cursor line itself defines the variable and returns `None` immediately, letting the caller fall through to type-hint resolution instead of scanning backwards past the current definition site.
 - **Multi-extends interfaces now fully stored.** Interfaces extending multiple parents (e.g. `interface C extends A, B`) now store all parent names, not just the first one.
 - **Conflicting use-import resolution.** When auto-importing a class whose short name collides with an existing `use` statement (e.g. accepting `App\Exception` while `use Cassandra\Exception;` is already present), the LSP now inserts a fully-qualified reference (`\App\Exception`) at the usage site instead of adding a duplicate `use` statement that would cause a compile error. Applies to all completion sources (class index, classmap, stubs) and to catch clause completions.
+- **Multi-namespace file class resolution.** Files containing multiple `namespace { }` blocks (e.g. a demo namespace alongside inline stubs) now resolve classes correctly. Each class carries the namespace of its enclosing block rather than inheriting the file-level namespace. This fixes `find_class_in_ast_map` returning the wrong class when two classes share the same short name but live in different namespace blocks. Parent class names and trait references are also resolved against the correct per-block namespace. The type resolver (`type_hint_to_classes`) and all local class lookups now use a namespace-aware `find_class_by_name` helper, so a fully-qualified return type like `\Illuminate\Database\Eloquent\Builder` no longer collides with a `Demo\Builder` class that happens to appear earlier in the same file.
+- **`$this`/`static`/`self` return type on trait methods resolved to the using class.** When a trait method declared `@return $this`, `@return static`, or `@return self`, chaining on the result resolved to the trait itself instead of the concrete class using it. For example, `$this->withHeaders([])->` on a class using `MakesHttpRequests` would not offer the class's own methods or parent methods. The resolver now returns the owning class directly for these return types, preserving the full member set for chaining. Works same-file and cross-file via PSR-4.
+- **Mixin `$this`/`self`/`static` return types no longer rewritten to mixin class name.** When a mixin method (e.g. `Query\Builder::orderBy()`) declared `@return $this`, the mixin merge code rewrote it to the mixin class's short name. In files with multiple classes sharing the same short name, this resolved to the wrong class and also prevented the builder-as-static substitution map from matching. These return types are now left as-is so that `$this` resolves to the consumer class at call sites, which is semantically correct for fluent APIs.
+- **Go-to-definition member position search scoped to declaring class.** `find_member_position` searched the entire file linearly for `function methodName`, finding the first match regardless of which class it belonged to. In files with multiple classes defining the same method name, this jumped to the wrong class. The new `find_member_position_in_range` accepts the declaring class's byte range and restricts the search accordingly. Docblock-based searches (`@method`, `@property`) are not scoped because docblocks precede the class body.
 
 ### Changed
 

docs/todo-laravel.md

@@ -329,14 +329,6 @@ end-to-end.
 
 ## Implementation sequence
 
-### Step 5: LaravelModelProvider — Builder-as-static
-
-- Load Eloquent Builder, extract public instance methods.
-- Present as static virtual methods on Model subclasses.
-- Handle return type mapping (`static` on Builder → Builder continuation,
-  model template parameter → concrete model class).
-- Tests: verify `User::where()->orderBy()->get()` chain resolves.
-
 ### Step 6: Completion builder adjustments
 
 - Virtual methods that are marked as "static forwarded" need to appear in
@@ -345,15 +337,6 @@ end-to-end.
   should respect whatever flag the provider sets.
 - Virtual properties from relationships should appear in `Arrow` completion.
 
-### Step 7: Go-to-definition support
-
-- When go-to-definition lands on a virtual property (relationship), jump to
-  the relationship method definition.
-- When go-to-definition lands on a virtual method (scope), jump to the
-  `scope*` method definition.
-- When go-to-definition lands on a forwarded Builder method, jump to the
-  Builder method definition.
-
 ---
 
 ## Out of scope (and why)

example.php

@@ -12,7 +12,7 @@
  *   3. SCAFFOLDING  — supporting definitions (scroll past these)
  */
 
-namespace Demo;
+namespace Demo {
 
 use Exception;
 use Stringable;
@@ -821,6 +821,12 @@ public function switchInsideCase(string $driver): void
 // Methods starting with "scope" (e.g. scopeActive) produce virtual methods with
 // the prefix stripped and first letter lowercased (e.g. active). The $query
 // parameter is removed. Scopes are available as both static and instance methods.
+//
+// Eloquent Builder methods are forwarded as static methods on model classes.
+// User::where('active', true)->orderBy('name')->get() resolves end-to-end.
+// Return types are mapped: Builder chain methods return Builder<ConcreteModel>,
+// and TModel parameters resolve to the concrete model class. Methods from
+// Query\Builder (via @mixin) are included as well.
 
 class BlogAuthor extends \Illuminate\Database\Eloquent\Model
 {
@@ -869,6 +875,14 @@ public function demo(): void
         // Scope methods — static access
         BlogAuthor::active();             // also available as static
         BlogAuthor::ofGenre('fiction');    // $genre parameter preserved, $query stripped
+
+        // Builder-as-static forwarding
+        BlogAuthor::where('active', true);         // returns Builder<BlogAuthor>
+        BlogAuthor::where('active', 1)->get();     // returns Collection<BlogAuthor>
+        BlogAuthor::where('active', 1)->first();   // returns BlogAuthor|null
+        BlogAuthor::orderBy('name')->limit(10)->get(); // full chain resolution
+        // Query\Builder methods (@mixin) are also forwarded:
+        BlogAuthor::whereIn('id', [1, 2])->groupBy('genre')->get();
     }
 }
 
@@ -2584,4 +2598,101 @@ class BlogTag extends \Illuminate\Database\Eloquent\Model
     public function getLabel(): string { return ''; }
 }
 
+} // end namespace Demo
+
+// ── Illuminate Stubs ────────────────────────────────────────────────────────
+// Minimal stubs matching real Laravel classes so that the Eloquent demo models
+// above resolve Builder methods, relationship properties, and scope forwarding
+// without requiring a real Laravel installation.
+
+namespace Illuminate\Database\Eloquent {
+
+    abstract class Model {
+        /** @return \Illuminate\Database\Eloquent\Builder<static> */
+        public static function query() {}
+    }
+
+    /**
+     * @template TModel of \Illuminate\Database\Eloquent\Model
+     *
+     * @mixin \Illuminate\Database\Query\Builder
+     */
+    class Builder implements \Illuminate\Contracts\Database\Eloquent\Builder {
+        /** @use \Illuminate\Database\Concerns\BuildsQueries<TModel> */
+        use \Illuminate\Database\Concerns\BuildsQueries;
 
+        /**
+         * @param  (\Closure(static): mixed)|string|array  $column
+         * @return $this
+         */
+        public function where($column, $operator = null, $value = null, $boolean = 'and') {}
+
+        /** @return \Illuminate\Database\Eloquent\Collection<int, TModel> */
+        public function get($columns = ['*']) { return new Collection(); }
+    }
+
+    /**
+     * @template TKey of array-key
+     * @template TModel of \Illuminate\Database\Eloquent\Model
+     */
+    class Collection {
+        /** @return TModel|null */
+        public function first(): mixed { return null; }
+        public function count(): int { return 0; }
+    }
+}
+
+namespace Illuminate\Database\Eloquent\Relations {
+    class HasMany {}
+    class HasOne {}
+    class BelongsTo {}
+    class BelongsToMany {}
+    class MorphOne {}
+    class MorphMany {}
+    class MorphTo {}
+    class MorphToMany {}
+    class HasManyThrough {}
+}
+
+namespace Illuminate\Database\Concerns {
+
+    /**
+     * @template TValue
+     */
+    trait BuildsQueries {
+        /** @return TValue|null */
+        public function first($columns = ['*']) { return null; }
+    }
+}
+
+namespace Illuminate\Database\Query {
+
+    class Builder {
+        /**
+         * @param  string  $column
+         * @return $this
+         */
+        public function whereIn($column, $values, $boolean = 'and', $not = false) { return $this; }
+
+        /** @return $this */
+        public function groupBy(...$groups) { return $this; }
+
+        /** @return $this */
+        public function orderBy($column, $direction = 'asc') { return $this; }
+
+        /** @return $this */
+        public function limit($value) { return $this; }
+
+        /**
+         * @return \Illuminate\Support\Collection<int, \stdClass>
+         */
+        public function get($columns = ['*']) {}
+    }
+}
+
+namespace Illuminate\Contracts\Database\Eloquent {
+    /**
+     * @mixin \Illuminate\Database\Eloquent\Builder
+     */
+    interface Builder {}
+}