Basic PSR-0 support

Author: AJenbo

docs/CHANGELOG.md

@@ -43,6 +43,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - **Phar archive class resolution.** Classes inside `.phar` archives (e.g. PHPStan's `phpstan.phar`) are now discovered and indexed automatically. During Composer autoload scanning, bootstrap files that reference a phar are detected, the archive is parsed in-process (no PHP runtime needed), and all PHP classes inside are registered for completion, hover, go-to-definition, and diagnostics. Anyone writing PHPStan extensions, custom rules, or dynamic return type extensions now gets full IDE support for the PHPStan API. Only uncompressed phars are supported (the format used by PHPStan and most other phar-distributed tools).
+- **PSR-0 autoload support.** Packages that use the legacy PSR-0 autoloading standard (e.g. HTMLPurifier) are now discovered automatically. Composer's `autoload_namespaces.php` is parsed at startup and the listed directories are scanned for classes. Previously these packages were invisible unless the user ran `composer install -o` to dump an optimised classmap.
 - **Analyze command.** `phpantom_lsp analyze` scans a Composer project and reports PHPantom's own diagnostics in a PHPStan-like table format. Useful for measuring type coverage across an entire codebase without opening files one by one. Accepts an optional path argument to limit the scan to a single file or directory. Only native diagnostics are reported (no PHPStan, no external tools). Output includes diagnostic identifiers and supports `--severity` filtering and `--no-colour` for CI.
 - **Add @throws.** New code action triggered by PHPStan's `missingType.checkedException` diagnostic. When PHPStan reports that a method or function throws a checked exception not documented in `@throws`, the quick-fix inserts a `@throws ShortName` tag into the existing docblock (or creates a new docblock) and adds a `use` import for the exception class when needed. Handles methods, standalone functions, and property hooks. Skips the action when the exception is already documented, already imported, or in the same namespace.
 - **Remove @throws.** New code action triggered by PHPStan's `throws.unusedType` (a `@throws` tag for a type that is never thrown) and `throws.notThrowable` (a `@throws` tag for a type that is not a subtype of `Throwable`). The quick-fix removes the offending `@throws` line from the docblock, cleans up orphaned blank separator lines, and removes the entire docblock when it would be empty after removal. Handles FQN, short-name, and leading-backslash variants, as well as single-line docblocks.

docs/todo/bugs.md

@@ -15,4 +15,107 @@ within the same impact tier.
 
 ---
 
-No outstanding items.
+#### B9. `assert($x instanceof self)` narrowing ignores `self`/`static`/`parent`
+
+| | |
+|---|---|
+| **Impact** | Medium-High |
+| **Effort** | Low |
+
+`try_extract_instanceof` in `completion/types/narrowing.rs` only matches
+`Expression::Identifier` for the RHS of an `instanceof` check. When the
+RHS is `self`, `static`, or `parent`, the Mago AST produces
+`Expression::Self_`, `Expression::Static`, or `Expression::Parent`
+instead, which fall through to `None`. This means
+`assert($feature instanceof self)` never narrows the variable.
+
+The fix is to add three arms to the `match bin.rhs` block in
+`try_extract_instanceof` that map `Self_` → `"self"`, `Static` →
+`"static"`, `Parent` → `"parent"`. The downstream
+`apply_instanceof_inclusion` already resolves `"self"` etc. to the
+current class via `type_hint_to_classes`.
+
+**Reproduce:** any method with a `BaseCatalogFeature` parameter that
+calls `assert($feature instanceof self)` then accesses subclass-only
+methods on `$feature`. Also affects Mockery test patterns:
+`$mock = $this->mock(X::class); assert($mock instanceof X);`.
+
+**Triage count:** ~30 diagnostics in luxplus/shared (18 BaseCatalogFeature,
+11 MockInterface, 1 Elasticsearch).
+
+---
+
+#### B10. Negative narrowing after early return not applied
+
+| | |
+|---|---|
+| **Impact** | Low-Medium |
+| **Effort** | Medium |
+
+After `if ($x instanceof Y) { return; }`, the variable `$x` should be
+narrowed to exclude `Y` for all subsequent code in the same scope.
+PHPantom does not apply this negative narrowing via early return.
+
+**Reproduce:**
+
+```php
+public static function toString(mixed $value): string
+{
+    if ($value instanceof Stringable) {
+        return $value->__toString();
+    }
+    if ($value instanceof BackedEnum) {
+        $value = $value->value; // PHPantom resolves $value as Stringable here
+    }
+}
+```
+
+The diagnostic reports `Property 'value' not found on class 'Stringable'`
+because `$value` is still resolved as `Stringable` inside the
+`BackedEnum` branch, even though that branch is only reachable when
+`$value` is NOT `Stringable`.
+
+Guard-clause narrowing already works for `if (!$x instanceof Y) { return; }`
+(positive narrowing after negated check). This is the inverse: positive
+check with exit should produce negative narrowing for subsequent code.
+
+**Triage count:** ~2 diagnostics directly, but a general correctness
+issue that affects any code using the early-return-after-instanceof
+pattern.
+
+---
+
+#### B11. Variables initialized to `null` and conditionally reassigned lose their type
+
+| | |
+|---|---|
+| **Impact** | Medium |
+| **Effort** | Medium |
+
+When a variable is initialized as `$x = null` and then conditionally
+reassigned inside a loop or branch (e.g. `$x = $transaction`), PHPantom
+resolves `$x` to `null` at the usage site even after a truthiness guard
+like `if (!$x) { continue; }` or `if ($x !== null)`.
+
+Three common patterns:
+
+1. **Null-init + loop assignment + guard:**
+   `$x = null; foreach (...) { if (cond) { $x = $expr; } } if ($x) { $x->method(); }`
+
+2. **Null coalesce + guard:**
+   `$x = $arr[$key] ?? null; if (!$x) { continue; } $x->property;`
+
+3. **assertNotNull:**
+   `$day = $arr['key'] ?? null; self::assertNotNull($day); $day->from;`
+
+The root cause is that PHPantom's variable resolution picks the first
+(or dominant) assignment and does not consider all assignment sites to
+build a union type. For pattern 1, only the `= null` is seen. For
+patterns 2 and 3, the `?? null` makes the type nullable but the
+subsequent guard or assertion is not recognized as narrowing.
+
+Pattern 3 overlaps with custom assert narrowing (`@phpstan-assert`) which
+requires recognizing `assertNotNull` as a type guard.
+
+**Triage count:** ~8 scalar_member_access diagnostics in luxplus/shared
+(AltapayGateway, PCNService, CustomerService, CoolrunnerClientTest).

src/composer.rs

@@ -433,6 +433,117 @@ pub fn extract_require_once_paths(content: &str) -> Vec<String> {
     paths
 }
 
+/// Parse `<vendor>/composer/autoload_namespaces.php` (PSR-0 map) and
+/// scan the listed directories for PHP classes.
+///
+/// PSR-0 is a legacy autoloading standard where underscores in class
+/// names map to directory separators.  For example, the prefix
+/// `HTMLPurifier` with base path `library/` means that the class
+/// `HTMLPurifier_Config` lives at `library/HTMLPurifier/Config.php`.
+///
+/// Composer generates `autoload_namespaces.php` for packages that
+/// declare `autoload.psr-0` in their `composer.json`.  The file
+/// contains lines like:
+///
+/// ```text
+///     'HTMLPurifier' => array($vendorDir . '/ezyang/htmlpurifier/library'),
+/// ```
+///
+/// Rather than implementing PSR-0 name-to-path resolution (which would
+/// require handling underscore splitting, prefix directories, and
+/// fallback rules), we simply scan each listed directory with the
+/// byte-level class scanner and return a classmap.  This gives us the
+/// same result as `composer install -o` for PSR-0 packages without
+/// requiring the user to run the optimised dump.
+///
+/// Returns an empty `HashMap` if the file does not exist or has no
+/// entries.
+pub fn parse_autoload_namespaces(
+    workspace_root: &Path,
+    vendor_dir: &str,
+) -> HashMap<String, PathBuf> {
+    let autoload_path = workspace_root
+        .join(vendor_dir)
+        .join("composer")
+        .join("autoload_namespaces.php");
+
+    let content = match fs::read_to_string(&autoload_path) {
+        Ok(c) => c,
+        Err(_) => return HashMap::new(),
+    };
+
+    // Collect all base directories listed in the PSR-0 map.
+    // Each line looks like:
+    //   'Prefix' => array($vendorDir . '/org/pkg/src'),
+    //   'Prefix' => array($vendorDir . '/org/pkg/src', $baseDir . '/lib'),
+    let mut base_dirs: Vec<PathBuf> = Vec::new();
+
+    for line in content.lines() {
+        let trimmed = line.trim();
+
+        // Skip lines that don't look like array entries.
+        if !trimmed.contains("=>") {
+            continue;
+        }
+
+        // Extract everything after `=> array(` or `=> [`
+        let rhs = if let Some(pos) = trimmed.find("=> array(") {
+            &trimmed[pos + "=> array(".len()..]
+        } else if let Some(pos) = trimmed.find("=> [") {
+            &trimmed[pos + "=> [".len()..]
+        } else {
+            continue;
+        };
+
+        // Strip trailing `)`, `],`, etc.
+        let rhs =
+            rhs.trim_end_matches(|c: char| c == ')' || c == ']' || c == ',' || c.is_whitespace());
+
+        // Split by comma to handle multiple paths per prefix.
+        for segment in rhs.split(',') {
+            let segment = segment.trim();
+            if let Some(relative_path) = resolve_autoload_path_entry(segment, vendor_dir) {
+                let full_path = workspace_root.join(&relative_path);
+                if full_path.is_dir() {
+                    base_dirs.push(full_path);
+                }
+            }
+        }
+    }
+
+    // Scan each base directory for PHP class files.
+    let mut classmap = HashMap::new();
+
+    for base_dir in &base_dirs {
+        scan_directory_for_classes(base_dir, &mut classmap);
+    }
+
+    classmap
+}
+
+/// Recursively scan a directory for PHP files and extract class names
+/// using the lightweight byte-level scanner.
+fn scan_directory_for_classes(dir: &Path, classmap: &mut HashMap<String, PathBuf>) {
+    let entries = match fs::read_dir(dir) {
+        Ok(e) => e,
+        Err(_) => return,
+    };
+
+    for entry in entries.flatten() {
+        let path = entry.path();
+        if path.is_dir() {
+            scan_directory_for_classes(&path, classmap);
+        } else if path.extension().is_some_and(|ext| ext == "php")
+            && let Ok(content) = fs::read(&path)
+        {
+            let classes = crate::classmap_scanner::find_classes(&content);
+            for fqn in classes {
+                classmap.entry(fqn).or_insert_with(|| path.clone());
+            }
+        }
+    }
+}
+
 /// Detect `.phar` archive references in a PHP bootstrap file.
 ///
 /// Scans the file content for patterns like:

src/server.rs

@@ -1071,6 +1071,21 @@ impl Backend {
         let symbol_count = classmap.len();
         *self.classmap.write() = classmap;
 
+        // ── PSR-0 (legacy) classmap ─────────────────────────────────
+        // Packages that declare `autoload.psr-0` in their composer.json
+        // (e.g. HTMLPurifier) are listed in `autoload_namespaces.php`.
+        // Scan the listed directories and merge discovered classes into
+        // the classmap so they are resolvable via `find_or_load_class`.
+        let psr0_cm = composer::parse_autoload_namespaces(root, &vendor_dir);
+        if !psr0_cm.is_empty() {
+            let count = psr0_cm.len();
+            let mut cm = self.classmap.write();
+            for (fqn, path) in psr0_cm {
+                cm.entry(fqn).or_insert(path);
+            }
+            tracing::info!("PSR-0: {} classes from autoload_namespaces.php", count);
+        }
+
         // ── Autoload files ──────────────────────────────────────────
         if let Some(tok) = progress_token {
             self.progress_report(tok, 70, Some("Scanning autoload files".to_string()))
@@ -1188,7 +1203,12 @@ impl Backend {
             // Load the subproject's Composer classmap as a skip set,
             // then self-scan its PSR-4 directories and vendor packages
             // for anything the classmap missed.
-            let sub_cm = composer::parse_autoload_classmap(sub_root, vendor_dir);
+            let mut sub_cm = composer::parse_autoload_classmap(sub_root, vendor_dir);
+            // Merge PSR-0 classes for this subproject.
+            let psr0_cm = composer::parse_autoload_namespaces(sub_root, vendor_dir);
+            for (fqn, path) in psr0_cm {
+                sub_cm.entry(fqn).or_insert(path);
+            }
             let sub_skip: HashSet<PathBuf> = sub_cm.values().cloned().collect();
             let scan = self.build_self_scan_composer(sub_root, vendor_dir, None, &sub_skip);
             self.populate_autoload_indices(&scan);