Move the type engine out of the compleation module

Author: AJenbo

AGENTS.md

@@ -20,13 +20,14 @@ and pipeline sections of [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)
 for how the pieces fit together. A few durable landmarks, since the
 module tree moves around:
 
-- **The shared type engine lives under `src/completion/`**, despite the
-  name. `completion/resolver/` resolves a subject expression to a
-  `ClassInfo`, and `completion/variable/forward_walk/` is the forward
+- **The shared type engine lives under `src/type_engine/`.**
+  `type_engine/resolver/` resolves a subject expression to a
+  `ClassInfo`, and `type_engine/variable/forward_walk/` is the forward
   walker that answers "what is the type of this expression here?" — it
   is shared by diagnostics, hover, go-to-definition, and signature help,
-  not just completion. Do not build a second type-resolution path (see
-  the anti-patterns below).
+  not just completion. `completion/` holds completion-specific code only.
+  Do not build a second type-resolution path (see the anti-patterns
+  below).
 - **Parsing** is in `parser/` (PHP source → `ClassInfo`/`FunctionInfo`)
   and `docblock/` (PHPDoc tags, templates, conditional types).
 - **The data model** is in `types/` and `php_type/`.

docs/ARCHITECTURE.md

@@ -53,8 +53,6 @@ src/
 │   # Data model
 ├── types/                  # Core structures (ClassInfo, MethodInfo, ResolvedType, SubjectExpr, …)
 ├── php_type/               # PHP type representation: parse, display, normalize, subtype, transform
-├── subject_expr.rs, subject_extraction.rs, subject_resolution.rs
-│                           # Extracting and resolving the subject before ->, ?->, ::
 │
 │   # Parsing & indexing
 ├── parser/                 # mago-syntax AST → ClassInfo/FunctionInfo (classes, functions, use statements, attributes, incremental update_ast)
@@ -74,20 +72,25 @@ src/
 ├── stubs.rs, stub_patches.rs  # Embedded phpstorm-stubs index + hand patches
 ├── phar.rs                 # Class discovery inside PHAR archives
 │
-│   # The shared type engine (lives under completion/, see note below)
-├── completion/
+│   # The shared type engine ("what is the type of this expression here?")
+├── type_engine/
+│   ├── subject_expr.rs, subject_extraction.rs, subject_resolution.rs
+│   │                       # Extracting and resolving the subject before ->, ?->, ::
 │   ├── resolver/           # Subject expression → ClassInfo (type engine entry point) + chain cache, property narrowing
 │   ├── variable/           # Variable type resolution via assignment scanning
 │   │   ├── forward_walk/   #   the forward walker (shared by diagnostics, hover, go-to-def, sig help)
 │   │   ├── rhs_resolution/ #   right-hand-side expression resolution
 │   │   └── …               #   closure/foreach/class-string/raw-type resolution
 │   ├── call_resolution/    # Call expression + callable target resolution, return types, arg types
-│   ├── types/              # Type-hint → ClassInfo, narrowing/, conditional return types
-│   │                       # ---- completion-specific below ----
+│   └── types/              # Type-hint → ClassInfo, narrowing/, conditional return types
+│
+│   # Completion (uses the type engine above)
+├── completion/
 │   ├── handler/            # Completion request orchestration (member access, class constants, named args, phpdoc)
 │   ├── context/            # Context-specific completion (catch, class, keyword, namespace, override, type-hint, …)
 │   ├── phpdoc/             # PHPDoc tag completion + docblock generation/
 │   ├── source/             # Source-text scanning (comment position, throws analysis)
+│   ├── variable/           # Variable-name completion + scope collection
 │   ├── builder.rs          # Build LSP CompletionItems from resolved ClassInfo
 │   └── …                   # target.rs, array_shape.rs, named_args.rs, use_edit.rs, eloquent_string.rs, laravel_route_controller.rs, …
 │
@@ -127,16 +130,15 @@ tests/
 └── assert_type_runner.rs, fixture_runner.rs
 ```
 
-**The shared type engine lives under `completion/`, despite the name.**
-`completion/resolver/`, `completion/variable/` (including the
-`forward_walk/` forward walker), `completion/call_resolution/`, and
-`completion/types/` are the project's single type-resolution engine —
-they answer "what is the type of this expression here?" and are consumed
-by diagnostics, hover, go-to-definition, and signature help, not just
-completion (see [Forward Walker](#forward-walker) and
-[Name Resolution](#name-resolution) below). This naming is a known wart;
-extracting the engine into its own top-level module is tracked in
-[`docs/todo/refactor.md`](todo/refactor.md).
+**The shared type engine lives under `type_engine/`.** `type_engine/resolver/`,
+`type_engine/variable/` (including the `forward_walk/` forward walker),
+`type_engine/call_resolution/`, `type_engine/types/`, and the subject
+extraction/resolution files are the project's single type-resolution engine —
+they answer "what is the type of this expression here?" and are consumed by
+diagnostics, hover, go-to-definition, and signature help, not just completion
+(see [Forward Walker](#forward-walker) and [Name Resolution](#name-resolution)
+below). Do not build a second type-resolution path: extend the engine here so
+every consumer benefits.
 
 ## External Crates
 
@@ -514,7 +516,7 @@ Current patches:
 
 This is analogous to the [Laravel Class Patches](#laravel-class-patches) system but for built-in PHP functions rather than framework classes. When phpstorm-stubs gains proper annotations for a patched function, the corresponding patch can be deleted.
 
-**When to add a patch here vs. hardcoded logic in `rhs_resolution.rs`:** if the correct behaviour can be expressed with `@template` / `@return` annotations (i.e. PHPStan's own stubs already have the fix), it belongs in `stub_patches.rs`. If the behaviour requires inspecting call-site argument *values* at resolution time (e.g. `array_map`'s callback return type, or `array_filter` preserving the input array's element type), it must stay as hardcoded logic in `rhs_resolution.rs` / `raw_type_inference.rs`. Those functions are tracked in `ARRAY_PRESERVING_FUNCS` and `ARRAY_ELEMENT_FUNCS` in `completion/variable/mod.rs`, with the full inventory in `docs/todo/completion.md` C1.
+**When to add a patch here vs. hardcoded logic in `rhs_resolution.rs`:** if the correct behaviour can be expressed with `@template` / `@return` annotations (i.e. PHPStan's own stubs already have the fix), it belongs in `stub_patches.rs`. If the behaviour requires inspecting call-site argument *values* at resolution time (e.g. `array_map`'s callback return type, or `array_filter` preserving the input array's element type), it must stay as hardcoded logic in `rhs_resolution.rs` / `raw_type_inference.rs`. Those functions are tracked in `ARRAY_PRESERVING_FUNCS` and `ARRAY_ELEMENT_FUNCS` in `type_engine/variable/mod.rs`, with the full inventory in `docs/todo/completion.md` C1.
 
 #### Class patches
 
@@ -636,9 +638,9 @@ Scope methods (both `scopeX` convention and `#[Scope]` attribute) are synthesize
 
 Instead, scope injection happens in three places:
 
-1. **Post-generic-substitution hook** (`completion/resolver.rs`, inside `type_hint_to_classes_depth`): after `resolve_class_fully` + `apply_generic_args` produces a `Builder<User>` class, the resolver detects that the result is an Eloquent Builder with a concrete model generic argument. It calls `build_scope_methods_for_builder(model_name, class_loader)` which loads the model, fully resolves it, extracts scope methods, and returns them as instance methods with `static` in return types substituted to the concrete model name. These are merged onto the Builder's method list, giving `$q->active()` after `$q = User::where(...)`.
+1. **Post-generic-substitution hook** (`type_engine/resolver/`, inside `type_hint_to_classes_depth`): after `resolve_class_fully` + `apply_generic_args` produces a `Builder<User>` class, the resolver detects that the result is an Eloquent Builder with a concrete model generic argument. It calls `build_scope_methods_for_builder(model_name, class_loader)` which loads the model, fully resolves it, extracts scope methods, and returns them as instance methods with `static` in return types substituted to the concrete model name. These are merged onto the Builder's method list, giving `$q->active()` after `$q = User::where(...)`.
 
-2. **Scope body Builder enrichment** (`completion/variable_resolution.rs`, `enrich_builder_type_in_scope`): inside a scope method body, the `$query` parameter is typically typed as `Builder` without generic arguments. The enrichment function detects when the enclosing method is a scope (either the `scopeX` naming convention or the `#[Scope]` attribute) on a class that extends Eloquent Model, and the parameter type is `Builder` without generics. It rewrites the type to `Builder<EnclosingModel>`, which then flows through the generic-args path and triggers the post-substitution hook above. This makes `$query->otherScope()` resolve inside scope bodies.
+2. **Scope body Builder enrichment** (`type_engine/variable/resolution.rs`, `enrich_builder_type_in_scope`): inside a scope method body, the `$query` parameter is typically typed as `Builder` without generic arguments. The enrichment function detects when the enclosing method is a scope (either the `scopeX` naming convention or the `#[Scope]` attribute) on a class that extends Eloquent Model, and the parameter type is `Builder` without generics. It rewrites the type to `Builder<EnclosingModel>`, which then flows through the generic-args path and triggers the post-substitution hook above. This makes `$query->otherScope()` resolve inside scope bodies.
 
 3. **Go-to-definition fallback** (`definition/member.rs`, `find_scope_on_builder_model`): when go-to-definition resolves a member on a Builder class and the normal lookup chain (own members, traits, parents, mixins, builder forwarding) fails, this fallback checks whether the member is a scope method injected from the model. It confirms the resolved candidate (with injected scopes) has the method, extracts the model name from the scope method's return type generic argument, loads the model, and finds the declaration through the model's inheritance chain. For `scopeX`-style scopes it looks for `scopeXxx`; for `#[Scope]`-attributed methods it falls back to the original method name. This bridges the gap between completion (which works on the merged ClassInfo) and GTD (which traces back to the declaring source file).
 
@@ -1112,7 +1114,7 @@ Everything above diagnoses files the user has opened. `src/diagnostics/workspace
 
 ## Forward Walker
 
-The forward walker (`src/completion/variable/forward_walk.rs`) walks
+The forward walker (`src/type_engine/variable/forward_walk/`) walks
 method bodies top-to-bottom, building a scope of variable types at
 each statement boundary. It is shared by diagnostics, completion,
 hover, go-to-definition, and signature help.

docs/todo/bugs.md

@@ -32,9 +32,9 @@ process(class: Product::class, flag: true, function ($p) {
 
 The forward walker's closure-argument inference
 (`walk_closures_in_call_args` and `walk_closure_in_partial_call_args` in
-`src/completion/variable/forward_walk/diagnostic_walk.rs`, and the
+`src/type_engine/variable/forward_walk/diagnostic_walk.rs`, and the
 completion/hover-path counterpart `infer_callable_params_for_call` in
-`src/completion/variable/forward_walk/callable_inference.rs`) computes
+`src/type_engine/variable/forward_walk/callable_inference.rs`) computes
 `arg_idx` from `arguments.iter().enumerate()` — the argument's position
 in the *call*. That index is then used directly as the *declared*
 parameter index, both to decide whether the argument at that slot is a

docs/todo/diagnostics.md

@@ -176,7 +176,7 @@ resolution. This eliminates the secondary resolvers entirely.
 
 - `src/diagnostics/unknown_members.rs` — remove
   `resolve_scalar_subject_type` and `resolve_unresolvable_class_subject`
-- `src/completion/resolver.rs` — enrich the resolution result
+- `src/type_engine/resolver/` — enrich the resolution result
 
 ---
 

docs/todo/eager-resolution.md

@@ -263,7 +263,7 @@ removes those guards and the depth caps they protect:
    consumer queries them, so re-entry cannot happen.
 
 2. **`RESOLVE_DEPTH` and `MAX_RESOLVE_TARGET_DEPTH` (60) in
-   `completion/resolver.rs`.** Thread-local depth counter for
+   `type_engine/resolver/`.** Thread-local depth counter for
    `resolve_target_classes_expr_inner`. Guards against mutual
    recursion between subject resolution, call-return resolution,
    and variable resolution. The limit of 60 (vs typical chain

docs/todo/inline-completion.md

@@ -121,7 +121,7 @@ completion resolver. No model, no data files, no latency.
 
 The template engine reuses existing infrastructure:
 
-- **Variable types:** `completion/variable/resolution.rs` already
+- **Variable types:** `type_engine/variable/resolution.rs` already
   resolves every variable in scope to a type. The template engine
   calls the same pipeline.
 - **Containing function:** The AST map already stores `MethodInfo`

docs/todo/refactor.md

@@ -214,66 +214,4 @@ Each item must include:
 
 # Outstanding items
 
-One task remains. It is a pure internal refactor and gets no changelog
-entry unless the work uncovers and fixes a concrete user-visible bug. Run
-the Rust CI checks (`cargo nextest run`, `cargo clippy -- -D warnings`,
-`cargo clippy --tests -- -D warnings`, `cargo fmt`) after the task.
-
-## 5. Extract the shared type engine out of `completion/`
-
-**What to do.** Despite the name, `src/completion/` houses the
-project's single type-resolution engine — the code that answers "what
-is the type of this expression here?" — consumed by diagnostics, hover,
-go-to-definition, and signature help, not just completion. The name
-misleads every new contributor and buries the most load-bearing
-subsystem inside a feature module. Move the engine into a top-level
-module (proposed `src/type_engine/`; name negotiable but **not**
-`resolve`/`resolution`, which collide with the existing `resolution.rs`
-class/function *name* lookup), leaving `completion/` with only
-completion-specific code. This is pure code motion — `impl Backend`
-blocks can live in any file of the crate, so methods move without
-becoming free functions.
-
-**Engine subtrees to move** (whole directories): `completion/resolver/`,
-`completion/call_resolution/`, `completion/types/`, and the
-type-resolution half of `completion/variable/` — `resolution.rs`,
-`forward_walk/`, `rhs_resolution/`, `foreach_resolution.rs`,
-`closure_resolution.rs`, `class_string_resolution.rs`,
-`raw_type_inference.rs`. The root-level `subject_expr.rs`,
-`subject_extraction.rs`, and `subject_resolution.rs` are part of the
-engine too — fold them in.
-
-**Stays in `completion/`:** `handler/`, `context/`, `phpdoc/`,
-`builder.rs`, `target.rs`, `array_shape.rs`, `array_callable.rs`,
-`named_args.rs`, `use_edit.rs`, `eloquent_string.rs`,
-`laravel_route_controller.rs`, `laravel_string_keys.rs`, and the one
-non-clean split: `completion/variable/completion.rs` is variable *name*
-completion (scope collection for the completion list), not type
-resolution, so it stays while its sibling type-resolution files move.
-
-**Steps.**
-1. Create the new module and move the engine subtrees into it, updating
-   `mod`/`use` declarations.
-2. Split `completion/variable/`: keep `completion.rs` (and any
-   scope-collection helpers only it uses) under `completion/`; move the
-   rest under `<engine>/variable/`.
-3. Update imports crate-wide (`crate::completion::resolver::…` →
-   `crate::type_engine::resolver::…`, etc.). Add thin `pub use`
-   re-exports in `completion/mod.rs` only if they meaningfully shrink
-   the diff; otherwise fix call sites directly.
-4. Update the module map and the "shared type engine lives under
-   `completion/`" note in `docs/ARCHITECTURE.md`, and the Project
-   Structure landmark in `AGENTS.md`, to point at the new module.
-
-**Acceptance.** `cargo nextest run` passes with only mechanical
-import-path updates; behavior is unchanged; `completion/` contains only
-completion features; the type engine has one obvious top-level home.
-
-**Why it matters.** Anti-pattern #6 in `AGENTS.md` ("do not build a
-second type-resolution path") depends on the engine being
-discoverable. While it hides under `completion/`, contributors reach
-for a "simpler" local resolver instead of finding the shared one. This
-is the largest churn of the set (crate-wide import moves), so it goes
-last.
-
----
+No outstanding items.

docs/todo/type-inference.md

@@ -344,7 +344,7 @@ emits the concrete callable signature in the `@param` tag.
 ## T20. Type narrowing reconciliation engine
 **Impact: Medium-High · Effort: High**
 
-PHPantom's type narrowing in `completion/types/narrowing.rs` handles
+PHPantom's type narrowing in `type_engine/types/narrowing/` handles
 basic patterns (instanceof, is_* calls, null checks) but lacks the
 algebraic framework that PHPStan and Psalm use. Key gaps:
 

src/analyse/run.rs

@@ -283,9 +283,9 @@ pub async fn run(options: AnalyseOptions) -> i32 {
                         let _cache_guard =
                             with_active_resolved_class_cache(&backend.resolved_class_cache);
                         let _chain_guard =
-                            crate::completion::resolver::with_chain_resolution_cache();
+                            crate::type_engine::resolver::with_chain_resolution_cache();
                         let _callable_guard =
-                            crate::completion::call_resolution::with_callable_target_cache();
+                            crate::type_engine::call_resolution::with_callable_target_cache();
                         let _body_infer_guard = backend.activate_body_return_inferrer();
                         let _auth_user_guard = backend.activate_auth_user_resolver();
 
@@ -297,19 +297,19 @@ pub async fn run(options: AnalyseOptions) -> i32 {
                         // collectors hit the cache (O(log N) lookup)
                         // instead of doing a full backward scan.
                         let _scope_guard =
-                            crate::completion::variable::forward_walk::with_diagnostic_scope_cache(
+                            crate::type_engine::variable::forward_walk::with_diagnostic_scope_cache(
                             );
                         let scope_t0 = Instant::now();
                         {
                             let file_ctx = backend.file_context(uri);
                             let class_loader = backend.class_loader(&file_ctx);
                             let function_loader_cl = backend.function_loader(&file_ctx);
                             let constant_loader_cl = backend.constant_loader();
-                            let loaders = crate::completion::resolver::Loaders {
+                            let loaders = crate::type_engine::resolver::Loaders {
                                 function_loader: Some(&function_loader_cl),
                                 constant_loader: Some(&constant_loader_cl),
                             };
-                            crate::completion::variable::forward_walk::build_diagnostic_scopes(
+                            crate::type_engine::variable::forward_walk::build_diagnostic_scopes(
                                 content,
                                 &file_ctx.classes,
                                 &class_loader,

src/code_actions/extract_function/mod.rs

@@ -27,10 +27,10 @@ pub(crate) use crate::code_actions::{
     CodeActionData, indent_of_line_at, indent_unit, make_code_action_data,
 };
 pub(crate) use crate::completion::phpdoc::generation::enrichment_plain;
-pub(crate) use crate::completion::resolver::Loaders;
 pub(crate) use crate::php_type::PhpType;
 pub(crate) use crate::scope_collector::ScopeMap;
 use crate::text_position::{offset_to_position, position_to_byte_offset};
+pub(crate) use crate::type_engine::resolver::Loaders;
 pub(crate) use crate::types::ClassInfo;
 
 mod codegen;