Update Laravel todo with all known info

Author: AJenbo

docs/todo-laravel.md

@@ -110,4 +110,177 @@ accessors, so in most cases the accessor method itself already produces
 the virtual property. Parsing `$appends` would only help when the
 accessor is defined in an unloaded parent class.
 
-**Priority:** Low. The accessor method is the real source of truth.
+**Priority:** Low. The accessor method is the real source of truth.
+
+#### 5. `*_count` relationship count properties
+
+Accessing `$user->posts_count` is a very common Laravel pattern
+(`withCount`, `loadCount`, or eager-loaded counts). We don't
+synthesize these today.
+
+```php
+$user->posts_count; // int, but we know nothing about it
+```
+
+Larastan handles this **declaratively** — no call-site tracking
+required.  When a property name ends with `_count`, it strips the
+suffix, checks whether the remainder (converted to camelCase) is a
+relationship method, and if so types the property as `int`.
+
+**Where to change:** In `LaravelModelProvider::provide`, after
+synthesizing relationship properties, iterate the relationship methods
+again and push a `{snake_name}_count` property typed as `int` for
+each one.  The property should have lower priority than explicit
+`@property` tags.
+
+**Priority:** Medium.  Simple to implement using the Larastan
+approach and covers a very common pattern.
+
+#### 6. `withSum()` / `withAvg()` / `withMin()` / `withMax()` aggregate properties
+
+Similar to `withCount`, these aggregate methods produce virtual
+properties named `{relation}_{function}` (e.g.
+`Order::withSum('items', 'price')` → `$order->items_sum`). The same
+call-site tracking challenge applies, and the type depends on the
+aggregate function (`withSum`/`withAvg` → `float`,
+`withMin`/`withMax` → `mixed`).
+
+**Priority:** Low. Unlike gap 5, these can't be inferred declaratively
+from the model alone — you'd need to track call-site string arguments.
+The `@property` workaround applies here too.
+
+#### 7. `$pivot` property on BelongsToMany related models
+
+When a model is accessed through a `BelongsToMany` (or `MorphToMany`)
+relationship, each related model instance gains a `$pivot` property at
+runtime that provides access to intermediate table columns.
+
+```php
+/** @return BelongsToMany<Role, $this> */
+public function roles(): BelongsToMany {
+    return $this->belongsToMany(Role::class)->withPivot('expires_at');
+}
+
+$user->roles->first()->pivot;           // Pivot instance — we know nothing about it
+$user->roles->first()->pivot->expires_at; // accessible at runtime, invisible to us
+```
+
+There are several layers of complexity here:
+
+1. **Basic `$pivot` property.** Related models accessed through a
+   `BelongsToMany` or `MorphToMany` relationship should have a `$pivot`
+   property typed as `\Illuminate\Database\Eloquent\Relations\Pivot`
+   (or the custom pivot class when `->using(CustomPivot::class)` is
+   used). We don't currently synthesize this property at all.
+
+2. **`withPivot()` columns.** The `withPivot('col1', 'col2')` call
+   declares which extra columns are available on the pivot object.
+   Tracking these requires parsing the relationship method body for
+   chained `withPivot` calls — similar in difficulty to the
+   `withCount` call-site problem (gap 5).
+
+3. **Custom pivot models (`using()`).** When `->using(OrderItem::class)`
+   is declared, the pivot is an instance of that custom class, which
+   may have its own properties, casts, and accessors. Detecting this
+   requires parsing the `->using()` call in the relationship body.
+
+Note: Larastan does **not** handle pivot properties either — the
+`$pivot` property comes from Laravel's own `@property` annotations on
+the `BelongsToMany` relationship stubs. If the user's stub set
+includes these annotations, it already works through our PHPDoc
+provider.
+
+**Priority:** Low-medium. The basic `$pivot` typed as `Pivot` (layer 1)
+would be a modest improvement. Layers 2–3 require relationship body
+parsing that we don't currently do for this purpose. The `@property`
+workaround on a custom Pivot class covers most real-world needs.
+
+#### 8. Custom Eloquent builders (`HasBuilder` / `#[UseEloquentBuilder]`)
+
+Laravel 11+ introduced the `HasBuilder` trait and
+`#[UseEloquentBuilder(UserBuilder::class)]` attribute to let models
+declare a custom builder class. When present, `User::query()` and
+all static builder-forwarded calls should resolve to the custom
+builder instead of the base `Illuminate\Database\Eloquent\Builder`.
+
+```php
+/** @extends Builder<User> */
+class UserBuilder extends Builder {
+    /** @return $this */
+    public function active(): static { ... }
+}
+
+class User extends Model {
+    /** @use HasBuilder<UserBuilder> */
+    use HasBuilder;
+}
+
+User::query()->active()->get(); // active() should resolve on UserBuilder
+```
+
+Larastan handles this via `BuilderHelper::determineBuilderName()`,
+which inspects `newEloquentBuilder()`'s return type or the
+`#[UseEloquentBuilder]` attribute to find the custom builder class.
+
+**Where to change:** In `build_builder_forwarded_methods`, before
+loading the standard `Eloquent\Builder`, check whether the model
+declares a custom builder via `@use HasBuilder<X>` in `use_generics`
+or a `newEloquentBuilder()` method with a non-default return type.
+If found, load and resolve that builder class instead.
+
+**Priority:** Medium. Custom builders are the recommended pattern
+for complex query scoping in modern Laravel and Larastan supports
+them. Without this, users of custom builders get no completions for
+their builder-specific methods via static calls on the model.
+
+#### 9. `#[Scope]` attribute (Laravel 11+)
+
+Laravel 11 introduced the `#[Scope]` attribute as an alternative to
+the `scopeX` naming convention. Methods decorated with `#[Scope]`
+are available on the builder without needing the `scope` prefix:
+
+```php
+class User extends Model {
+    #[Scope]
+    protected function active(Builder $query): void { ... }
+}
+
+User::active()->get(); // works at runtime via #[Scope]
+```
+
+Larastan checks for this attribute in `BuilderHelper::searchOnEloquentBuilder()`.
+We currently only detect scopes via the `scopeX` naming convention in
+`is_scope_method`.
+
+**Where to change:** In the parser, extract `#[Scope]` attributes
+from method declarations. In `LaravelModelProvider::provide`, treat
+methods with the `#[Scope]` attribute the same as `scopeX` methods
+(strip the first `$query` parameter, expose as both static and
+instance virtual methods).
+
+**Priority:** Low-medium. The `scopeX` convention still works and
+is more common. The `#[Scope]` attribute is newer and adoption is
+growing.
+
+#### 10. Higher-order collection proxies
+
+Laravel collections support higher-order proxies via magic properties
+like `$users->map->name` or `$users->filter->isActive()`. These
+produce a `HigherOrderCollectionProxy` that delegates property
+access / method calls to each item in the collection.
+
+```php
+$users->map->email;           // Collection<int, string>
+$users->filter->isVerified(); // Collection<int, User>
+$users->each->notify();       // void (side-effect)
+```
+
+Larastan handles this with `HigherOrderCollectionProxyPropertyExtension`
+and `HigherOrderCollectionProxyExtension`, which resolve the proxy's
+template types and delegate property/method lookups to the collection's
+value type.
+
+**Priority:** Low. This is a convenience syntax and most users use
+closures instead. Requires synthesizing virtual properties on
+collection classes that return a proxy type parameterised with the
+collection's value type.