Update readme and related docs

Author: AJenbo

README.md

@@ -1,169 +1,110 @@
 # PHPantomLSP
 
-A fast, lightweight PHP language server that stays out of your way. Using only a few MB of RAM regardless of project size and fully usable in milliseconds without requiring high-end hardware.
+A fast, lightweight PHP language server written in Rust. Uses only a few MB of RAM regardless of project size and is fully responsive in milliseconds — no indexing phase, no background workers, no waiting.
 
-> **Note:** This project is in active development.
+> [!NOTE]
+> PHPantomLSP is in active development. Completion and go-to-definition are solid and used daily. More LSP features (hover, signature help, find references) are on the roadmap.
+
+<img width="683" height="339" alt="Completion demo" src="https://github.com/user-attachments/assets/65e8220d-5d94-466f-aea7-2f239a8d4b19" />
 
 ## Features
 
-### Completion
-
-- **Instance members** via `->` — methods, properties, constructor-promoted properties
-- **Static members** via `::` — static methods, static properties, constants, enum cases
-- **`parent::`** — inherited and overridden members (excludes private)
-- **Traits and interfaces** — trait members appear on the using class; interface contracts are resolved
-- **`@mixin` classes** — members from `@mixin` annotations are included
-- **Magic members** — `@property`, `@property-read`, `@method` from PHPDoc
-- **Method chaining** — return types are followed through arbitrarily long chains
-- **Null-safe chaining** — `?->` is handled identically to `->`
-- **Full signatures** in completion labels (parameters, types, return type)
-- Magic methods (`__construct`, `__call`, etc.) are only suggested interally
-- **Named argument completion** — when typing inside call parentheses, parameter names are suggested with a trailing `:`.
-- **PHPDoc tag completion** — context-aware suggestions inside `/** … */` blocks.
-- **Variable name completion** — typing `$` suggests variables that are in scope.
-- **Class name completion** — unqualified and partially-qualified class names are completed from the current file
-- **Function completion** — standalone functions are completed
-- **Constant completion** — constants defined via `define()` are offered alongside class names
-- **Deprecated detection** — members, classes, and functions marked with `@deprecated` in their PHPDoc are shown with strikethrough in the completion list
-
-<img width="683" height="339" alt="image" src="https://github.com/user-attachments/assets/65e8220d-5d94-466f-aea7-2f239a8d4b19" />
+### Code Completion
+
+Full completion for PHP class members, functions, variables, and more:
+
+- **Instance and static members** — methods, properties, constants, and enum cases via `->`, `?->`, and `::`
+- **Inheritance-aware** — parent classes, traits, interfaces, and `@mixin` classes are fully resolved with correct precedence
+- **Magic members** — `@property`, `@property-read`, and `@method` from PHPDoc
+- **Method chaining** — follows return types through arbitrarily long `->` and `?->` chains
+- **Callable snippets** — methods and functions insert with parameter tab-stops
+- **Named arguments** — parameter names are suggested inside call parentheses
+- **Variable completion** — `$` triggers scope-aware variable suggestions
+- **Class and function completion** — with automatic `use` statement insertion
+- **Type hint completion** — parameter types, return types, and property types offer scalars and class names
+- **PHPDoc completion** — context-aware tag suggestions with smart `@throws` (detects uncaught exceptions) and `@param` pre-fill
+- **Array shape keys** — from annotations, literal array inference, and `$_SERVER` superglobals
+- **Object shape properties** — `object{name: string, age: int}` resolves to property completions
+- **`new` filtering** — interfaces, traits, and abstract classes are hidden or demoted
+- **Deprecated detection** — `@deprecated` members show with strikethrough
 
 ### Go to Definition
 
-- **Classes, interfaces, traits, enums** — same-file and cross-file
-- **Methods, properties, constants** — resolves through inheritance, traits, and mixins
-- **Standalone functions** — including PHP built-ins via embedded stubs
-- **Variables** — jumps to the most recent assignment or declaration (assignment, parameter, `foreach`, `catch`, `static`/`global`)
-- **Property type definition** — when the cursor is on a property or parameter at its declaration site, jumps to the class definition of its type hint
-- **Namespace resolution** — fully-qualified, partially-qualified, and aliased names via `use ... as ...`
+- **Classes, interfaces, traits, enums** — same-file and cross-file via PSR-4
+- **Members** — methods, properties, and constants resolved through the full inheritance chain
+- **Variables** — jumps to the assignment, parameter, `foreach`, `catch`, or other declaration site
+- **Type hints and docblock types** — click a class name in a parameter type, return type, `@param`, `@return`, `@throws`, etc.
+- **Functions and constants** — including PHP built-ins via embedded stubs
 
 ### Type Resolution
 
-PHPantom infers variable types from assignments, parameter hints, return types, and PHPDoc annotations, then uses them to power both completion and go-to-definition.
-
-- **Union types** (`A|B`) and **intersection types** (`A&B`), including PHP 8.2 DNF types like `(A&B)|C`
-- **Conditional return types** — PHPStan-style `@return ($param is class-string<T> ? T : mixed)`, used by patterns like `app(User::class)->getEmail()`
-- **`@var` overrides** — inline `/** @var Type $var */` docblocks refine variable types
-- **Ambiguous variables** — when a variable is assigned different types in conditional branches, all candidates are offered
+PHPantomLSP infers variable types from assignments, type hints, return types, and PHPDoc — then uses them to power completion and go-to-definition.
+
+- **Union, intersection, and DNF types** — `A|B`, `A&B`, `(A&B)|C`
+- **Generics** — class-level `@template` with substitution through inheritance (`@extends Base<User>`)
+- **Conditional return types** — `@return ($param is class-string<T> ? T : mixed)`
+- **Type aliases** — `@phpstan-type` and `@phpstan-import-type` with full resolution
+- **Array shapes** — from annotations and inferred from literal arrays and incremental `$data['key'] = ...` assignments
+- **Object shapes** — `object{foo: int, bar: string}` with nested chaining
+- **Generators** — `Generator<TKey, TValue, TSend, TReturn>` yield type extraction
+- **Array functions** — `array_filter`, `array_map`, `array_pop`, etc. preserve element types
+- **Foreach** — resolves value and key types from annotations, generic collections, method calls, and property access
+- **Destructuring** — `['key' => $var] = $data` maps named keys to array shape entry types
+- **Clone, catch, list inference** — `clone $x`, `catch (E $e)`, and `$arr[] = new Foo()` all resolve correctly
+- **Multi-line docblocks** — broken `@return` types spanning multiple lines are joined and recovered
 
 ### Type Narrowing
 
-Completion results adapt to runtime type checks. PHPantomLSP narrows union types in both the positive and inverse branches of `if`/`else`, `while`, and `match(true)`:
+Completion adapts to runtime type checks in `if`/`else`, `while`, ternaries, and `match(true)`:
 
-- `instanceof` and negated `!instanceof`
-- `is_a($var, ClassName::class)`
-- `get_class($var) === ClassName::class` and `$var::class === ClassName::class` (including `!==` and reversed operand order)
+- `instanceof` and `!instanceof`
+- `is_a()`, `get_class() ===`, `$var::class ===`
 - `assert($var instanceof ClassName)`
-- **Custom assertion functions** via `@phpstan-assert` / `@psalm-assert` annotations:
-  - `@phpstan-assert Type $param` — unconditional narrowing after the call
-  - `@phpstan-assert-if-true Type $param` — narrows in the then-branch
-  - `@phpstan-assert-if-false Type $param` — narrows in the else-branch
-
-### Composer & Project Awareness
-
-- Parses `composer.json` for PSR-4, classmap, and file autoload mappings
-- Resolves cross-file class lookups on demand
-- Discovers classes and functions from `require_once` files
-
-> **Note:**
-> - Run `composer install -o` (or `composer dump-autoload -o`) to generate autoload files needed for full class completion.
-> - If your project doesn’t use Composer, you can create a minimal `composer.json` to generate a classmap:
->
->   ```json
->   {
->     "autoload": {
->       "classmap": ["src/"]
->     }
->   }
->   ```
->
->   Then run:
->   ```bash
->   composer dump-autoload -o
->   ```
-
-## Building
-
-The PHP stubs are managed as a Composer dependency in `stubs/`. Install them before building:
-
-```bash
-# Install the PHP stubs (requires Composer)
-composer install
-
-# Build
-cargo build
-
-# or for a release build
-cargo build --release
-```
-
-> **Note:** The build will succeed without `composer install`, but the resulting binary won't know about built-in PHP symbols like `Iterator`, `Countable`, `UnitEnum`, etc. Always run `composer install` first for a fully functional build.
+- **Guard clauses** — `if (!$var instanceof Foo) { return; }` narrows subsequent code
+- **Custom assertions** — `@phpstan-assert`, `@phpstan-assert-if-true`, `@phpstan-assert-if-false`
 
-After updating stubs (`composer update`), just rebuild — the `build.rs` script watches `composer.lock` and re-embeds everything automatically.
+## Project Awareness
 
-For more details on how symbol resolution and stub loading work, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+PHPantomLSP understands Composer projects out of the box:
 
-## Testing
+- **PSR-4 autoloading** — resolves classes across files on demand
+- **Classmap and file autoloading** — `autoload_classmap.php` and `autoload_files.php`
+- **Embedded PHP stubs** — ~1,450 built-in classes, ~5,000 functions, and ~2,000 constants from [phpstorm-stubs](https://github.com/JetBrains/phpstorm-stubs) are bundled in the binary. No runtime downloads needed.
+- **`require_once` discovery** — functions from required files are available for completion
 
-Run the test suite:
-
-```bash
-cargo test
-```
-
-### Manual LSP Testing
-
-The included `test_lsp.sh` script sends JSON-RPC messages to the server over stdin/stdout, exercising the full LSP protocol flow (initialize, open file, hover, completion, shutdown):
-
-```bash
-./test_lsp.sh
-```
-
-This is useful for verifying end-to-end behavior outside of an editor.
-
-### Debugging
-
-Enable logging by setting the `RUST_LOG` environment variable:
-
-```bash
-RUST_LOG=debug cargo run 2>phpantom.log
-```
-
-Logs are written to stderr, so redirect as needed.
+> [!IMPORTANT]
+> Run `composer install -o` (or `composer dump-autoload -o`) in your project to generate the optimized autoload files PHPantomLSP needs for cross-file class resolution.
+>
+> If your project doesn't use Composer, you can create a minimal `composer.json`:
+> ```json
+> { "autoload": { "classmap": ["src/"] } }
+> ```
+> Then run `composer dump-autoload -o`.
 
-## Editor Integration
+## Getting Started
 
-PHPantomLSP communicates over stdin/stdout. Point your editor's LSP client at the binary:
+See **[docs/SETUP.md](docs/SETUP.md)** for editor-specific installation instructions (Zed, Neovim, and other editors).
 
-- **Path:** `target/release/phpantom_lsp` (after `cargo build --release`)
+## Building from Source
 
-### Zed
+See **[docs/BUILDING.md](docs/BUILDING.md)** for build, test, and debug instructions.
 
-Install it as a dev extension from the `zed-extension/` directory in this repo:
+## Contributing
 
-1. Open Zed
-2. Open the Extensions panel
-3. Click **Install Dev Extension**
-4. Select the `zed-extension/` directory
+See **[docs/CONTRIBUTING.md](docs/CONTRIBUTING.md)**.
 
-The extension automatically downloads the correct pre-built binary from GitHub releases for your platform. If you'd prefer to use a locally built binary, ensure `phpantom_lsp` is on your `PATH` and the extension will use it instead.
+## Architecture
 
-To configure PHPantom LSP as the default PHP language server in Zed, add the following to your Zed settings (`settings.json`):
+For details on how symbol resolution, stub loading, and inheritance merging work, see **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)**.
 
-```json
-{
-  "languages": {
-    "PHP": {
-      "language_servers": ["phpantom_lsp", "!intelephense", "!phpactor", "!phptools", "..."]
-    }
-  }
-}
-```
+## Acknowledgements
 
-## Contributing
+PHPantomLSP stands on the shoulders of:
 
-See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md).
+- **[Mago](https://github.com/carthage-software/mago)** — the PHP parser that powers all of PHPantomLSP's AST analysis
+- **[PHPStan](https://phpstan.org/)** and **[Psalm](https://psalm.dev/)** — whose combined work on static analysis for PHP transformed the language's type ecosystem. Generics, array shapes, conditional return types, assertion annotations — these tools pushed each other forward and pushed the community toward rigorous PHPDoc annotations that make a language server like this possible. PHPantomLSP's author cut his teeth on PHPStan, which is why `@phpstan-*` annotations are a first-class citizen here.
+- **[JetBrains phpstorm-stubs](https://github.com/JetBrains/phpstorm-stubs)** — type information for the entire PHP standard library, embedded directly into the binary
 
 ## License
 
-MIT - see [LICENSE](LICENSE).
+MIT — see [LICENSE](LICENSE).

docs/BUILDING.md

@@ -0,0 +1,68 @@
+# Building & Development
+
+## Quick Start
+
+```bash
+composer install        # fetch PHP stubs (requires Composer)
+cargo build --release   # build the binary
+```
+
+## Prerequisites
+
+- [Rust](https://rustup.rs/) (stable toolchain)
+- [Composer](https://getcomposer.org/) (for PHP standard library stubs)
+
+## Build
+
+The PHP stubs are managed as a Composer dependency in `stubs/`. The `build.rs` script embeds the [JetBrains phpstorm-stubs](https://github.com/JetBrains/phpstorm-stubs) directly into the binary, giving the LSP full knowledge of built-in PHP classes, functions, and constants without any runtime dependencies.
+
+> [!NOTE]
+> The build will succeed without `composer install`, but the resulting binary won't know about built-in PHP symbols like `Iterator`, `Countable`, `UnitEnum`, etc. Always run `composer install` first for a fully functional build.
+
+After updating stubs (`composer update`), just rebuild — `build.rs` watches `composer.lock` and re-embeds everything automatically.
+
+For details on how symbol resolution and stub loading work, see [ARCHITECTURE.md](ARCHITECTURE.md).
+
+## Testing
+
+Run the full test suite:
+
+```bash
+cargo test
+```
+
+### CI Checks
+
+Before submitting changes, run exactly what CI runs:
+
+```bash
+cargo test
+cargo clippy -- -D warnings
+cargo clippy --tests -- -D warnings
+cargo fmt --check
+php -l example.php
+```
+
+All five must pass with zero warnings and zero failures.
+
+### Manual LSP Testing
+
+The included `test_lsp.sh` script sends JSON-RPC messages to the server over stdin/stdout, exercising the full LSP protocol flow (initialize, open file, hover, completion, shutdown):
+
+```bash
+./test_lsp.sh
+```
+
+This is useful for verifying end-to-end behavior outside of an editor.
+
+## Debugging
+
+Enable logging by setting the `RUST_LOG` environment variable:
+
+```bash
+RUST_LOG=debug cargo run 2>phpantom.log
+```
+
+Logs are written to stderr, so redirect as needed.
+
+For editor setup instructions, see [SETUP.md](SETUP.md).

docs/CONTRIBUTING.md

@@ -5,37 +5,43 @@ Thanks for your interest in contributing!
 ## Getting Started
 
 1. Fork and clone the repository
-2. Install Rust via [rustup](https://rustup.rs/)
-3. Install [Composer](https://getcomposer.org/) (PHP dependency manager)
-4. Run `composer install` to fetch the PHP standard library stubs
-5. Run `cargo build` to verify everything compiles
-
-> **Note:** The `composer install` step downloads [JetBrains phpstorm-stubs](https://github.com/JetBrains/phpstorm-stubs) into `stubs/`, which are then embedded into the binary at compile time. Without this step the build will succeed, but the LSP won't know about built-in PHP symbols like `Iterator`, `Countable`, `UnitEnum`, etc.
+2. Follow the [build instructions](BUILDING.md) to get a working development environment
+3. Read [ARCHITECTURE.md](ARCHITECTURE.md) for an overview of how the codebase is structured
 
 ## Before Submitting a PR
 
-Please make sure all checks pass:
+All five CI checks must pass with zero warnings and zero failures:
 
 ```bash
 cargo test
-cargo clippy
+cargo clippy -- -D warnings
+cargo clippy --tests -- -D warnings
 cargo fmt --check
+php -l example.php
 ```
 
+Note that clippy runs twice — once for library code and once including test code.
+
 ## Code Style
 
 - Run `cargo fmt` before committing
-- Address any `cargo clippy` warnings
-- Add tests for new functionality in `tests/integration_tests.rs`
+- Fix clippy warnings rather than suppressing them — avoid `#[allow(clippy::...)]` unless truly necessary
+- Add `///` doc comments to all public functions and struct fields
 
 ## Testing
 
-- Unit/integration tests: `cargo test`
-- Manual LSP testing: `./test_lsp.sh` (sends JSON-RPC messages over stdin/stdout)
+- Integration tests go in `tests/completion_*.rs` or `tests/definition_*.rs` — one file per feature area
+- Use `create_test_backend()` from `tests/common/mod.rs` for same-file tests
+- Use `create_psr4_workspace()` for cross-file / PSR-4 tests
+- Test the happy path, edge cases, and interactions with existing features
+- When adding a feature, update `example.php` with working examples (and verify with `php -l example.php`)
+
+See [BUILDING.md](BUILDING.md) for more on running tests and manual LSP testing.
 
 ## Reporting Issues
 
 Open an issue on GitHub with:
+
 - What you expected to happen
 - What actually happened
-- Steps to reproduce
+- Steps to reproduce (a minimal PHP snippet is ideal)