Suppress unknown class diagnostic for class_index lazy loads

Author: AJenbo

docs/CHANGELOG.md

@@ -38,6 +38,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **False-positive type errors on generic class methods resolved through return types.** When a method returns a generic class (e.g. `@return HasMany<Translation, Tag>`), calling a method on the result whose parameter references a class-level template parameter (e.g. `@param TRelatedModel $model`) no longer produces a spurious "expects TRelatedModel, got Translation" diagnostic. The return type's generic arguments are now preserved and used for template substitution. Covers instance methods, static methods, standalone functions, inherited methods, trait methods, and nullable generic return types.
 - **Variables prefixed with `$this` receiving stale type information.** Variables like `$thisItem` or `$thisValue` no longer receive stale type information from `$this`-related narrowing.
 - **False-positive type errors on generic class methods and templated static methods.** Class-level `@template` parameters (e.g. `Collection<User>`) are now substituted into method parameter types before checking argument compatibility. Method-level `@template` parameters (e.g. PHPUnit's `assertSame`) are resolved from call-site argument types, covering literals, variables, enum cases, property accesses, and method call return types. Argument type checking correctly rejects `float` passed where an int-range type like `positive-int` is expected.
+- **False "class not found" for global-namespace classes loaded via Composer's `files` autoloading.** Classes like `Mockery` that live in the global namespace and are autoloaded through Composer's `files` directive (rather than PSR-4 or classmap) are now resolved correctly. The class index populated during initialization was never consulted by the class resolver, causing false diagnostics when such classes were imported with `use Mockery;` in namespaced files.
 - **Unbound template parameters resolved to their declared bounds.** When a template parameter cannot be inferred from call-site arguments (e.g. `new Collection()` without a generic annotation, `collect()` with no arguments, or a method-level `@template` with no matching parameter), the parameter is now replaced with its declared upper bound (`@template T of Foo` resolves to `Foo`) or `mixed` when no bound exists. The same resolution now applies to interface-level template parameters: when a class implements a generic interface without providing `@implements` generics, the interface's template params are substituted with their bounds instead of leaking as raw names into inherited method signatures. Previously the raw template name leaked through as a type (e.g. `TValue`, `TReduceReturnType`, `TKey`), causing false "expects TValue, got string" diagnostics on every call site that used the unresolved generic.
 - **Foreach key variable type from static properties and scalar keys.** Iterating over a static property with a generic array annotation (e.g. `self::$map` typed as `array<string, string>`) now correctly resolves the foreach key variable's type. Static property access (`self::$prop`, `static::$prop`, `ClassName::$prop`) is resolved through the class's property type hints. Scalar key types (`string`, `int`, `array-key`) are now extracted from generic iterables for key variable resolution, where previously only class-typed keys were handled.
 - **Foreach loop prescan no longer leaks reassigned types into same-statement RHS.** When a foreach key variable is reassigned inside the loop body (e.g. `$type = DeviationType::from($type)`), the `$type` argument in `from()` now correctly resolves to the foreach key type (`string`) instead of the reassigned type (`DeviationType`). The loop-body prescan results are deferred until after the normal body walk completes.

docs/todo/bugs.md

@@ -267,3 +267,27 @@ function test(): void {
     $store->products()->filter()->add($product);
 }
 ```
+
+## B12 — Hover cross-file property docblock cache invalidation fails after edits
+
+**Root cause:** When a class is loaded from a cross-file source
+(PSR-4 or classmap) and its docblock is later edited, hover
+continues to show the stale docblock content instead of the updated
+version. The parsed `ClassInfo` cached in `ast_map` and/or
+`fqn_index` is not invalidated when the dependency file changes.
+
+Six integration tests document the failure:
+
+- `hover_cross_file_property_docblock_cache_invalidation_psr4_then_edit`
+- `hover_cross_file_property_docblock_cache_invalidation_dependent_class`
+- `hover_cross_file_property_docblock_cache_invalidation_via_var_annotation`
+- `hover_cross_file_property_docblock_cache_invalidation_dependent_class_with_model`
+- `hover_cross_file_property_docblock_cache_invalidation_via_method_chain`
+- `hover_cross_file_property_docblock_cache_warm_then_invalidate`
+
+**Where to fix:** The cache layer that stores cross-file
+`ClassInfo` results must be invalidated (or re-parsed) when
+`didChange` or `didSave` fires for the dependency file. The
+`resolved_class_cache` and/or `fqn_index` entries for the changed
+URI must be evicted so that the next hover request re-parses the
+file and picks up the new docblock content.

src/diagnostics/unknown_classes.rs

@@ -1089,4 +1089,47 @@ mod tests {
             diags.iter().map(|d| &d.message).collect::<Vec<_>>()
         );
     }
+
+    #[test]
+    fn no_diagnostic_for_global_class_via_class_index_lazy_load() {
+        // A global-namespace class (like Mockery) that is discovered by
+        // `scan_autoload_files` and placed in class_index — but NOT yet
+        // parsed into ast_map — should be lazily loaded via Phase 0 of
+        // find_or_load_class and suppress the diagnostic.
+        let dir = tempfile::tempdir().expect("failed to create temp dir");
+        let dep_path = dir.path().join("Mockery.php");
+        std::fs::write(&dep_path, "<?php\nclass Mockery {}\n").expect("failed to write temp file");
+        let dep_uri = crate::util::path_to_uri(&dep_path);
+
+        let backend = Backend::new_test();
+
+        // Only populate class_index (simulating scan_autoload_files).
+        // Do NOT call update_ast for the dependency — it must be lazily
+        // parsed by find_or_load_class Phase 0.
+        {
+            let mut idx = backend.class_index.write();
+            idx.insert("Mockery".to_string(), dep_uri);
+        }
+
+        let uri = "file:///test.php";
+        let content = concat!(
+            "<?php\n",
+            "namespace Tests\\Feature;\n",
+            "\n",
+            "use Mockery;\n",
+            "\n",
+            "class ApiTest {\n",
+            "    public function test(): void {\n",
+            "        Mockery::mock();\n",
+            "    }\n",
+            "}\n",
+        );
+
+        let diags = collect(&backend, uri, content);
+        assert!(
+            !diags.iter().any(|d| d.message.contains("Mockery")),
+            "should not flag Mockery resolved via class_index lazy load, got: {:?}",
+            diags.iter().map(|d| &d.message).collect::<Vec<_>>()
+        );
+    }
 }

src/resolution.rs

@@ -37,6 +37,8 @@ use std::sync::Arc;
 
 use std::path::Path;
 
+use tower_lsp::lsp_types::Url;
+
 use crate::Backend;
 use crate::composer;
 use crate::php_type::PhpType;
@@ -90,6 +92,24 @@ impl Backend {
             return None;
         }
 
+        // ── Phase 0: Try the class_index (FQN → URI) ──
+        // The class_index is populated by `scan_autoload_files` (Composer
+        // `autoload_files.php` entries and their `require_once` chains),
+        // by `update_ast` for every opened/changed file, and by the
+        // workspace full-scan for non-Composer projects.  It covers
+        // classes that don't follow PSR-4 conventions and aren't in the
+        // Composer classmap — e.g. global-namespace classes like `Mockery`
+        // that are loaded via Composer's `files` autoloading.
+        if let Some(file_uri) = self.class_index.read().get(class_name).cloned()
+            && let Some(file_path) = Url::parse(&file_uri)
+                .ok()
+                .and_then(|u| u.to_file_path().ok())
+            && let Some(classes) = self.parse_and_cache_file(&file_path)
+            && let Some(cls) = classes.iter().find(|c| c.name == last_segment)
+        {
+            return Some(Arc::clone(cls));
+        }
+
         // ── Phase 1: Search all already-parsed files in the ast_map ──
         // Checks short name + namespace to avoid false positives (e.g.
         // "Demo\\PDO" won't match the global "PDO" stub).