Refactor code in preperation for additional feature work

Author: AJenbo

docs/ARCHITECTURE.md

@@ -24,7 +24,10 @@ src/
 ├── stubs.rs                # Embedded phpstorm-stubs (build-time generated index)
 ├── resolution.rs           # Multi-phase class/function lookup and name resolution
 ├── inheritance.rs          # Base class inheritance merging (traits, parent chain)
-├── symbol_map.rs           # Precomputed per-file symbol location map (SymbolSpan, VarDefSite, CallSite, SymbolMap)
+├── symbol_map/
+│   ├── mod.rs              # Data structures (SymbolSpan, SymbolKind, VarDefSite, CallSite, SymbolMap) and impl
+│   ├── docblock.rs         # Docblock symbol extraction (type span emission, @template/@method tag scanning, navigability filter)
+│   └── extraction.rs       # AST walk that builds a SymbolMap (extract_symbol_map and all extract_from_* helpers)
 ├── virtual_members/
 │   ├── mod.rs              # VirtualMemberProvider trait, VirtualMembers struct, merge logic
 │   ├── laravel.rs          # LaravelModelProvider (relationships, scopes, casts, accessors)
@@ -51,9 +54,14 @@ src/
 │   ├── resolver.rs         # Resolve subject → ClassInfo (type resolution engine), shared resolve_callable_target
 │   ├── source_helpers.rs   # Source-text scanning helpers (closure/callable return types, new-expression parsing, array access)
 │   ├── builder.rs          # Build LSP CompletionItems from resolved ClassInfo
-│   ├── class_completion.rs # Class name, constant, and function completions
+│   ├── class_completion.rs # Class name completions (class, interface, trait, enum)
+│   ├── constant_completion.rs  # Global constant name completions
+│   ├── function_completion.rs  # Standalone function name completions
+│   ├── namespace_completion.rs # Namespace declaration completions
 │   ├── variable_completion.rs  # Variable name completions and scope collection
 │   ├── variable_resolution.rs  # Variable type resolution via assignment scanning
+│   ├── class_string_resolution.rs  # Class-string variable resolution ($cls = User::class)
+│   ├── raw_type_inference.rs   # Raw type inference for variable assignments (array shapes, array functions, generators)
 │   ├── foreach_resolution.rs   # Foreach value/key and array destructuring type resolution
 │   ├── closure_resolution.rs   # Closure and arrow-function parameter resolution
 │   ├── type_narrowing.rs       # instanceof / assert / custom type guard narrowing
@@ -74,7 +82,10 @@ src/
 │   ├── mod.rs              # Submodule declarations
 │   ├── resolve.rs          # Core go-to-definition: symbol-map dispatch + text-based fallback
 │   ├── member.rs           # Member-access resolution (->method, ::$prop, ::CONST) with stored offsets
-│   ├── variable.rs         # Variable definition resolution (symbol-map → AST walk → text fallback)
+│   ├── variable/
+│   │   ├── mod.rs          # VarDefSearchResult enum, Backend methods, tests
+│   │   ├── var_definition.rs # AST walk finding variable definition sites
+│   │   └── type_hint.rs    # AST walk extracting type hints at definition sites
 │   └── implementation.rs   # Go-to-implementation (interface/abstract → concrete classes)
 build.rs                    # Parses PhpStormStubsMap.php, generates stub index
 stubs/                      # Composer vendor dir for jetbrains/phpstorm-stubs

docs/todo-laravel.md

@@ -74,7 +74,27 @@ benefit) and an **Effort** estimate (implementation complexity):
 
 ---
 
-#### 1. `$dates` array (deprecated)
+#### 1. `morphedByMany` missing from relationship method map
+
+| | |
+|---|---|
+| **Impact** | ★★ — Any model using `morphedByMany` (the inverse of a polymorphic many-to-many) gets no virtual property or `_count` property for that relationship. |
+| **Effort** | ★ — One-line addition to `RELATIONSHIP_METHOD_MAP` in `virtual_members/laravel.rs`. |
+
+`morphedByMany` is the inverse side of a polymorphic many-to-many
+relationship. It returns a `MorphToMany` instance (the same class as
+`morphToMany`), but the method name is not listed in
+`RELATIONSHIP_METHOD_MAP`. This means body inference
+(`infer_relationship_from_body`) does not recognise
+`$this->morphedByMany(Tag::class)` calls, so no virtual property or
+`_count` property is synthesized.
+
+**Where to change:** Add `("morphedByMany", "MorphToMany")` to
+`RELATIONSHIP_METHOD_MAP` in `src/virtual_members/laravel.rs`.
+No other changes needed since `MorphToMany` is already in
+`COLLECTION_RELATIONSHIPS`.
+
+#### 2. `$dates` array (deprecated)
 
 | | |
 |---|---|
@@ -93,7 +113,7 @@ Merge these into `casts_definitions` at a lower priority than explicit
 `$casts` entries, or add a separate field on `ClassInfo` and handle
 priority in the provider.
 
-#### 2. Custom Eloquent builders (`HasBuilder` / `#[UseEloquentBuilder]`)
+#### 3. Custom Eloquent builders (`HasBuilder` / `#[UseEloquentBuilder]`)
 
 | | |
 |---|---|
@@ -131,7 +151,7 @@ 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.
 
-#### 3. `abort_if`/`abort_unless` type narrowing
+#### 4. `abort_if`/`abort_unless` type narrowing
 
 | | |
 |---|---|
@@ -175,7 +195,7 @@ to subsequent code:
 This is similar to the existing guard clause narrowing but triggered
 by specific function names rather than `if` + early return.
 
-#### 4. `collect()` and other helper functions lose generic type info
+#### 5. `collect()` and other helper functions lose generic type info
 
 | | |
 |---|---|
@@ -223,7 +243,7 @@ before passing it to `type_hint_to_classes`.  See the general TODO
 item (§ PHP Language Feature Gaps, "Function-level `@template`
 generic resolution") for the full implementation plan.
 
-#### 5. Factory `has*`/`for*` relationship methods
+#### 6. Factory `has*`/`for*` relationship methods
 
 | | |
 |---|---|
@@ -261,7 +281,7 @@ The `has*` variant should accept optional `int $count` and
 `array|callable $state` parameters; `for*` should accept
 `array|callable $state`.
 
-#### 6. `$pivot` property on BelongsToMany related models
+#### 7. `$pivot` property on BelongsToMany related models
 
 | | |
 |---|---|
@@ -307,7 +327,7 @@ the `BelongsToMany` relationship stubs. If the user's stub set
 includes these annotations, it already works through our PHPDoc
 provider.
 
-#### 7. `withSum()` / `withAvg()` / `withMin()` / `withMax()` aggregate properties
+#### 8. `withSum()` / `withAvg()` / `withMin()` / `withMax()` aggregate properties
 
 | | |
 |---|---|
@@ -323,7 +343,7 @@ aggregate function (`withSum`/`withAvg` → `float`,
 
 The `@property` workaround applies here too.
 
-#### 8. Higher-order collection proxies
+#### 9. Higher-order collection proxies
 
 | | |
 |---|---|
@@ -346,7 +366,7 @@ and `HigherOrderCollectionProxyExtension`, which resolve the proxy's
 template types and delegate property/method lookups to the collection's
 value type.
 
-#### 9. `SoftDeletes` trait methods on Builder
+#### 10. `SoftDeletes` trait methods on Builder
 
 | | |
 |---|---|
@@ -374,7 +394,7 @@ type — e.g. `Builder<static>` instead of `Builder<User>`.  This is
 a minor gap but not worth a dedicated fix until custom builder
 support (gap §7) is implemented.
 
-#### 10. `View::withX()` and `RedirectResponse::withX()` dynamic methods
+#### 11. `View::withX()` and `RedirectResponse::withX()` dynamic methods
 
 | | |
 |---|---|
@@ -406,7 +426,7 @@ hard-coding the two known classes.  A simpler approach: add
 `@method` tags to bundled stubs for the most common dynamic `with*`
 methods, or document this as a known limitation.
 
-#### 11. `$appends` array
+#### 12. `$appends` array
 
 | | |
 |---|---|
@@ -417,4 +437,25 @@ The `$appends` property lists accessor names that should always be
 included in `toArray()` / `toJson()`. These reference existing
 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.
+accessor is defined in an unloaded parent class.
+
+#### 13. Relationship classification matches short name only
+
+| | |
+|---|---|
+| **Impact** | ★ — Nearly all codebases use Laravel's built-in relationship classes, so false positives are rare in practice. |
+| **Effort** | ★★ — Need to resolve the return type's FQN before matching, which may require a class loader call. |
+
+`classify_relationship` in `virtual_members/laravel.rs` strips the
+return type down to its short name (via `short_name`) and matches
+against a hardcoded list (`HasMany`, `BelongsTo`, etc.). This means
+any class whose short name collides with a Laravel relationship class
+(e.g. a custom `App\Relations\HasMany` that does not extend
+Eloquent's) would be incorrectly classified as a relationship.
+
+The fix would be to resolve the return type to its FQN (using the
+class loader or use-map) and verify it lives under
+`Illuminate\Database\Eloquent\Relations\` (or extends a class that
+does) before classifying. The short-name-only path could remain as a
+fast-path fallback when the FQN is already in the
+`Illuminate\Database\Eloquent\Relations` namespace.

src/completion/array_shape.rs

@@ -749,205 +749,5 @@ pub(super) fn build_list_type_from_push_types(types: &[String]) -> Option<String
 }
 
 #[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn test_detect_single_quote_empty() {
-        // $config['
-        let content = "<?php\n$config['";
-        let pos = Position {
-            line: 1,
-            character: 9,
-        };
-        let ctx = detect_array_key_context(content, pos).unwrap();
-        assert_eq!(ctx.var_name, "$config");
-        assert_eq!(ctx.partial_key, "");
-        assert_eq!(ctx.quote_char, Some('\''));
-        assert_eq!(ctx.key_start_col, 9);
-        assert!(ctx.prefix_keys.is_empty());
-    }
-
-    #[test]
-    fn test_detect_single_quote_partial() {
-        // $config['na
-        let content = "<?php\n$config['na";
-        let pos = Position {
-            line: 1,
-            character: 11,
-        };
-        let ctx = detect_array_key_context(content, pos).unwrap();
-        assert_eq!(ctx.var_name, "$config");
-        assert_eq!(ctx.partial_key, "na");
-        assert_eq!(ctx.quote_char, Some('\''));
-        assert_eq!(ctx.key_start_col, 9);
-        assert!(ctx.prefix_keys.is_empty());
-    }
-
-    #[test]
-    fn test_detect_double_quote_empty() {
-        let content = "<?php\n$config[\"";
-        let pos = Position {
-            line: 1,
-            character: 9,
-        };
-        let ctx = detect_array_key_context(content, pos).unwrap();
-        assert_eq!(ctx.var_name, "$config");
-        assert_eq!(ctx.partial_key, "");
-        assert_eq!(ctx.quote_char, Some('"'));
-        assert_eq!(ctx.key_start_col, 9);
-        assert!(ctx.prefix_keys.is_empty());
-    }
-
-    #[test]
-    fn test_detect_bracket_only() {
-        // $config[
-        let content = "<?php\n$config[";
-        let pos = Position {
-            line: 1,
-            character: 8,
-        };
-        let ctx = detect_array_key_context(content, pos).unwrap();
-        assert_eq!(ctx.var_name, "$config");
-        assert_eq!(ctx.partial_key, "");
-        assert_eq!(ctx.quote_char, None);
-        assert_eq!(ctx.key_start_col, 8);
-        assert!(ctx.prefix_keys.is_empty());
-    }
-
-    #[test]
-    fn test_no_context_without_bracket() {
-        let content = "<?php\n$config";
-        let pos = Position {
-            line: 1,
-            character: 7,
-        };
-        assert!(detect_array_key_context(content, pos).is_none());
-    }
-
-    #[test]
-    fn test_no_context_without_variable() {
-        let content = "<?php\nfoo['";
-        let pos = Position {
-            line: 1,
-            character: 5,
-        };
-        assert!(detect_array_key_context(content, pos).is_none());
-    }
-
-    #[test]
-    fn test_detect_chained_single_key() {
-        // $response['meta'][
-        let content = "<?php\n$response['meta'][";
-        let pos = Position {
-            line: 1,
-            character: 18,
-        };
-        let ctx = detect_array_key_context(content, pos).unwrap();
-        assert_eq!(ctx.var_name, "$response");
-        assert_eq!(ctx.partial_key, "");
-        assert_eq!(ctx.quote_char, None);
-        assert_eq!(ctx.prefix_keys, vec!["meta"]);
-    }
-
-    #[test]
-    fn test_detect_chained_single_key_with_quote() {
-        // $response['meta']['
-        let content = "<?php\n$response['meta']['";
-        let pos = Position {
-            line: 1,
-            character: 19,
-        };
-        let ctx = detect_array_key_context(content, pos).unwrap();
-        assert_eq!(ctx.var_name, "$response");
-        assert_eq!(ctx.partial_key, "");
-        assert_eq!(ctx.quote_char, Some('\''));
-        assert_eq!(ctx.prefix_keys, vec!["meta"]);
-    }
-
-    #[test]
-    fn test_detect_chained_two_keys() {
-        // $data['a']['b'][
-        let content = "<?php\n$data['a']['b'][";
-        let pos = Position {
-            line: 1,
-            character: 16,
-        };
-        let ctx = detect_array_key_context(content, pos).unwrap();
-        assert_eq!(ctx.var_name, "$data");
-        assert_eq!(ctx.prefix_keys, vec!["a", "b"]);
-    }
-
-    #[test]
-    fn test_detect_autoclosed_bracket() {
-        // $config[] — cursor between [ and ]
-        let content = "<?php\n$config[]";
-        let pos = Position {
-            line: 1,
-            character: 8,
-        };
-        let ctx = detect_array_key_context(content, pos).unwrap();
-        assert_eq!(ctx.var_name, "$config");
-        assert_eq!(ctx.partial_key, "");
-        assert_eq!(ctx.quote_char, None);
-        assert_eq!(ctx.key_start_col, 8);
-    }
-
-    #[test]
-    fn test_detect_autoclosed_quote_bracket() {
-        // $config[''] — cursor between the two quotes
-        let content = "<?php\n$config['']";
-        let pos = Position {
-            line: 1,
-            character: 9,
-        };
-        let ctx = detect_array_key_context(content, pos).unwrap();
-        assert_eq!(ctx.var_name, "$config");
-        assert_eq!(ctx.partial_key, "");
-        assert_eq!(ctx.quote_char, Some('\''));
-        assert_eq!(ctx.key_start_col, 9);
-    }
-
-    #[test]
-    fn test_build_list_type_single() {
-        let types = vec!["User".to_string()];
-        assert_eq!(
-            build_list_type_from_push_types(&types),
-            Some("list<User>".to_string())
-        );
-    }
-
-    #[test]
-    fn test_build_list_type_union() {
-        let types = vec!["User".to_string(), "AdminUser".to_string()];
-        assert_eq!(
-            build_list_type_from_push_types(&types),
-            Some("list<User|AdminUser>".to_string())
-        );
-    }
-
-    #[test]
-    fn test_build_list_type_deduplicates() {
-        let types = vec![
-            "User".to_string(),
-            "User".to_string(),
-            "AdminUser".to_string(),
-        ];
-        assert_eq!(
-            build_list_type_from_push_types(&types),
-            Some("list<User|AdminUser>".to_string())
-        );
-    }
-
-    #[test]
-    fn test_build_list_type_empty() {
-        let types: Vec<String> = vec![];
-        assert_eq!(build_list_type_from_push_types(&types), None);
-    }
-
-    #[test]
-    fn test_build_list_type_all_mixed() {
-        let types = vec!["mixed".to_string(), "mixed".to_string()];
-        assert_eq!(build_list_type_from_push_types(&types), None);
-    }
-}
+#[path = "array_shape_tests.rs"]
+mod tests;