Skip to content

Commit d2791a6

Browse files
AJenboAJenbo
committed
Update roadmap
1 parent 66ecfee commit d2791a6

8 files changed

Lines changed: 420 additions & 141 deletions

File tree

‎docs/ARCHITECTURE.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -284,8 +284,8 @@ find_or_load_class("Iterator")
284284
│ Direct hash lookup in the classmap parsed from
285285
│ vendor/composer/autoload_classmap.php. More targeted than PSR-4
286286
│ and covers classes that don't follow PSR-4 conventions. When the
287-
│ user runs `composer dump-autoload -o`, *all* classes (including
288-
│ vendor) end up in the classmap, giving complete coverage.
287+
│ classmap is complete, all classes (including vendor) are resolved
288+
│ here without further searching.
289289
│ ↓ miss
290290
│
291291
├── Phase 2: PSR-4 resolution
@@ -634,7 +634,7 @@ find_implementors("Cacheable", "App\\Contracts\\Cacheable")
634634
│ Skips files already covered by the classmap (Phase 3) or ast_map.
635635
│ Reads raw source, applies the same string pre-filter.
636636
│ Matching files are parsed via parse_and_cache_file.
637-
│ Discovers classes in projects without `composer dump-autoload -o`.
637+
│ Discovers classes missing from the classmap.
638638
│ ↓ done
639639
│
640640
└── Vec<ClassInfo> (concrete implementors only)
@@ -644,7 +644,7 @@ find_implementors("Cacheable", "App\\Contracts\\Cacheable")
644644

645645
Phase 5 walks PSR-4 roots from `composer.json` (`autoload` and `autoload-dev`). Since PSR-4 mappings are sourced exclusively from the project's own `composer.json` (vendor PSR-4 is not loaded), Phase 5 inherently only discovers classes in the user's own source directories (e.g. `src/`, `app/`, `tests/`). Vendor dependencies are fully covered by the classmap (Phase 3).
646646

647-
Phase 5 exists to catch newly-created or not-yet-indexed user classes that are missing from the classmap (e.g. the user hasn't run `composer dump-autoload -o`).
647+
Phase 5 exists to catch newly-created or not-yet-indexed user classes that are missing from the classmap.
648648

649649
Note: `collect_php_files` still receives the vendor dir name because a fallback mapping like `"" => "."` resolves to the workspace root, where the walk must skip the vendor directory (and hidden directories like `.git`).
650650

‎docs/SETUP.md‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -26,9 +26,6 @@ cargo build --release
2626

2727
PHPantom works with any PHP project. It reads `composer.json` when present to discover autoload directories and vendor packages, and falls back to scanning the workspace when not present.
2828

29-
> [!TIP]
30-
> Running `composer dump-autoload -o` is optional but gives PHPantom a pre-built classmap, making startup almost instant.
31-
3229
## Configuration
3330

3431
PHPantom supports an optional per-project configuration file for settings like PHP version overrides and diagnostic toggles.

‎docs/todo.md‎

Lines changed: 115 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -32,35 +32,43 @@ with each step.
3232

3333
---
3434

35-
## Sprint 3 — Refactoring & deferred performance
35+
## Sprint 2 — Stabilise for 0.5.0 release
3636

37-
Extract Function is the remaining refactoring pillar. Inline Variable,
38-
Extract Variable, and Inline Function/Method round out the core
39-
refactoring toolkit, sharing scope analysis infrastructure with Extract
40-
Function. Find References and Rename provide the variable/symbol usage
41-
tracking infrastructure they depend on, and both are now complete.
37+
All Sprint 2+ feature work is done. Before tagging 0.5.0, fix the
38+
remaining bugs that would embarrass us in front of new users. No new
39+
features, no refactors, no "while I'm here" detours. Ship what we
40+
have, ship it correct.
4241

43-
The deferred performance items from Sprint 2.5 are included here. They
44-
improve lookup speed, reduce cloning overhead, and prepare the codebase
45-
for full background indexing (Phase 5), but are not prerequisites for
46-
parallel file processing.
42+
The common thread: our own diagnostics contradict our own demos in
43+
`example.php`. If PHPantom flags working code in its own showcase
44+
file, users will not trust any diagnostic it produces.
4745

4846
| # | Item | Effort | Domain | Doc Link |
4947
|---|---|---|---|---|
50-
| 17 | Extract Function refactoring | Very High | Code Actions | [actions.md §3](todo/actions.md#3-extract-function-refactoring) |
51-
| 76 | Inline Variable | Medium | Code Actions | [actions.md §7](todo/actions.md#7-inline-variable) |
52-
| 77 | Extract Variable | Medium | Code Actions | [actions.md §8](todo/actions.md#8-extract-variable) |
53-
| 78 | Inline Function/Method | High | Code Actions | [actions.md §9](todo/actions.md#9-inline-functionmethod) |
54-
| 87 | Reference-counted `ClassInfo` (`Arc<ClassInfo>`) | Medium | Performance | [performance.md §2](todo/performance.md#2-reference-counted-classinfo-arcclassinfo) |
55-
| 88 | Early-exit and `Cow` return in `apply_substitution` | Low | Performance | [performance.md §7](todo/performance.md#7-recursive-string-substitution-in-apply_substitution) |
56-
| 95 | Canonicalize FQN representation | High | Refactoring | [refactor.md §1](todo/refactor.md#1-canonicalize-fqn-representation) |
48+
| 106 | Diagnostics fire on type alias array shape object values | Low | Bug Fixes | [bugs.md §1](todo/bugs.md#1-diagnostics-fire-on-type-alias-array-shape-object-values) |
49+
| 107 | Inline array-element function calls resolve to native return type in diagnostics | Low | Bug Fixes | [bugs.md §2](todo/bugs.md#2-inline-array-element-function-calls-resolve-to-native-return-type-in-diagnostics) |
50+
| 108 | Flaky `unknown_member` diagnostic on Eloquent Builder scope chains | Medium | Bug Fixes | [bugs.md §3](todo/bugs.md#3-flaky-unknown_member-diagnostic-on-eloquent-builder-scope-chains) |
51+
52+
**Release gate:** `cargo test`, `cargo clippy -- -D warnings`,
53+
`cargo clippy --tests -- -D warnings`, `cargo fmt --check`,
54+
`php -l example.php`, and `php -d zend.assertions=1 example.php`
55+
all pass. Zero diagnostics on `example.php` from PHPantom itself.
56+
Tag 0.5.0, write release notes, publish.
5757

5858
---
5959

60-
## Sprint 4 — Close the LSP feature gap
60+
## Sprint 3 — Quick wins: close the visible gaps
61+
62+
Every item here is Low or Low-Medium effort and directly removes
63+
something a Neovim/Zed/VS Code user would notice as missing on day
64+
one. Document Symbols alone eliminates the single most visible gap
65+
(empty outline, no breadcrumbs). Workspace Symbols gives
66+
keyboard-driven navigation back to Neovim users. The remaining
67+
items round out the feature matrix with minimal risk.
6168

62-
These items close the most commonly expected LSP feature surface gaps.
63-
Each one removes a reason someone might look elsewhere.
69+
The deferred performance items from Sprint 2.5 are included here
70+
because they are prerequisites for keeping everything fast as the
71+
feature surface grows.
6472

6573
| # | Item | Effort | Domain | Doc Link |
6674
|---|---|---|---|---|
@@ -69,20 +77,79 @@ Each one removes a reason someone might look elsewhere.
6977
| 21 | Folding Ranges (`textDocument/foldingRange`) | Low | LSP Features | [lsp-features.md §12](todo/lsp-features.md#12-folding-ranges-textdocumentfoldingrange) |
7078
| 22 | Selection Ranges (`textDocument/selectionRange`) | Low | LSP Features | [lsp-features.md §13](todo/lsp-features.md#13-selection-ranges-textdocumentselectionrange) |
7179
| 23 | Type Definition (`textDocument/typeDefinition`) | Low | LSP Features | [lsp-features.md §14](todo/lsp-features.md#14-type-definition-textdocumenttypedefinition) |
72-
| 24 | PHPDoc block generation on `/**` | Medium | LSP Features | [lsp-features.md §3](todo/lsp-features.md#3-phpdoc-block-generation-on-) |
7380
| 81 | Work-done progress for GTI and Find References | Low | LSP Features | [lsp-features.md §18](todo/lsp-features.md#18-work-done-progress-for-gti-and-find-references) |
81+
| 101 | Argument count diagnostic | Low | Diagnostics | [diagnostics.md §7](todo/diagnostics.md#7-argument-count-diagnostic) |
82+
| 105 | Merged classmap + self-scan | Low | Indexing | [indexing.md §1.5](todo/indexing.md#phase-15-merged-classmap--self-scan) |
83+
| 88 | Early-exit and `Cow` return in `apply_substitution` | Low | Performance | [performance.md §7](todo/performance.md#7-recursive-string-substitution-in-apply_substitution) |
84+
| 87 | Reference-counted `ClassInfo` (`Arc<ClassInfo>`) | Medium | Performance | [performance.md §2](todo/performance.md#2-reference-counted-classinfo-arcclassinfo) |
85+
86+
**After Sprint 3:** PHPantom feels like a complete LSP to everyday
87+
users. Outline, breadcrumbs, workspace search, folding, and smart
88+
select all work. Argument count errors catch real bugs and serve as
89+
a canary for type engine correctness. No one says "it's missing X"
90+
for basic editing workflows.
91+
92+
---
93+
94+
## Sprint 4 — Refactoring toolkit
95+
96+
Extract Function is the #1 personal feature request and something
97+
that was available before the switch to PHPantom. Inline Variable,
98+
Extract Variable, and Inline Function/Method have been specifically
99+
requested by the Neovim tester. These share scope analysis
100+
infrastructure with Extract Function, so building them together is
101+
the most efficient path.
102+
103+
The deferred FQN canonicalization refactor is included here as a
104+
gate check before Sprint 5 widens the feature surface further.
105+
106+
| # | Item | Effort | Domain | Doc Link |
107+
|---|---|---|---|---|
108+
| 17 | Extract Function refactoring | Very High | Code Actions | [actions.md §3](todo/actions.md#3-extract-function-refactoring) |
109+
| 76 | Inline Variable | Medium | Code Actions | [actions.md §7](todo/actions.md#7-inline-variable) |
110+
| 77 | Extract Variable | Medium | Code Actions | [actions.md §8](todo/actions.md#8-extract-variable) |
111+
| 78 | Inline Function/Method | High | Code Actions | [actions.md §9](todo/actions.md#9-inline-functionmethod) |
112+
| 95 | Canonicalize FQN representation | High | Refactoring | [refactor.md §1](todo/refactor.md#1-canonicalize-fqn-representation) |
113+
114+
**After Sprint 4:** The core refactoring toolkit is complete. The
115+
two most active testers have the features they specifically asked
116+
for. Scope analysis infrastructure built here benefits future code
117+
actions.
118+
119+
---
120+
121+
## Sprint 5 — Polish for office adoption
122+
123+
These items close the gaps that PHPStorm and VS Code + Intelephense
124+
users at the office would notice. PHPDoc generation and formatting
125+
are the most common "where did that go?" moments. Inlay hints are
126+
high-visibility in VS Code. The implementation error diagnostic
127+
reuses existing code action logic and pairs with the quick-fix.
128+
File rename on class rename removes a friction point that
129+
Intelephense premium users expect.
130+
131+
| # | Item | Effort | Domain | Doc Link |
132+
|---|---|---|---|---|
133+
| 24 | PHPDoc block generation on `/**` | Medium | LSP Features | [lsp-features.md §3](todo/lsp-features.md#3-phpdoc-block-generation-on-) |
134+
| 100 | Formatting proxy (php-cs-fixer / phpcbf) | Medium | LSP Features | [lsp-features.md §19](todo/lsp-features.md#19-formatting-proxy-textdocumentformatting-textdocumentrangeformatting) |
135+
| 40 | Inlay hints (`textDocument/inlayHint`) | Medium | LSP Features | [lsp-features.md §9](todo/lsp-features.md#9-inlay-hints-textdocumentinlayhint) |
136+
| 102 | Implementation error diagnostic | Medium | Diagnostics | [diagnostics.md §9](todo/diagnostics.md#9-implementation-error-diagnostic) |
74137
| 99 | File rename on class rename | Medium | LSP Features | [lsp-features.md §20](todo/lsp-features.md#20-file-rename-on-class-rename) |
138+
| 103 | Stub extension selection (`[stubs] extensions`) | Low | Configuration | [config.md §stubs](todo/config.md#extension-stub-selection) |
75139

76-
**After Sprint 4:** PHPantom covers every commonly expected LSP feature
77-
and surpasses the field on type intelligence, generics, Laravel, and
78-
performance. No feature gaps remain for typical day-to-day editing.
140+
**After Sprint 5:** PHPantom is ready for office colleagues. They
141+
get formatting, PHPDoc generation, inlay hints, and the diagnostics
142+
they're used to. Nobody switching from Intelephense (free or
143+
premium) feels like they lost more than they gained.
79144

80145
---
81146

82-
## Sprint 5 — Type intelligence depth & polish
147+
## Sprint 6 — Type intelligence depth
83148

84149
Type intelligence depth is PHPantom's defining advantage. This sprint
85-
deepens that lead and rounds out the remaining feature surface.
150+
deepens that lead with features that benefit the PHPStan enthusiast
151+
and Laravel developer alike. File system watching eliminates the
152+
"restart the server after composer update" friction.
86153

87154
| # | Item | Effort | Domain | Doc Link |
88155
|---|---|---|---|---|
@@ -92,27 +159,32 @@ deepens that lead and rounds out the remaining feature surface.
92159
| 29 | Conditional return types `($param is T ? A : B)` | Medium | Type Inference | [type-inference.md §3](todo/type-inference.md#3-parse-and-resolve-param-is-t--a--b-return-types) |
93160
| 30 | `@param-closure-this` | Medium | Type Inference | [type-inference.md §15](todo/type-inference.md#15-param-closure-this) |
94161
| 31 | `key-of<T>` and `value-of<T>` resolution | Medium | Type Inference | [type-inference.md §16](todo/type-inference.md#16-key-oft-and-value-oft-resolution) |
95-
| 32 | Code Lens: jump to prototype method | Low | LSP Features | [lsp-features.md §8](todo/lsp-features.md#8-code-lens-jump-to-prototype-method) |
96-
| 34 | Document Links (`textDocument/documentLink`) | Low | LSP Features | [lsp-features.md §15](todo/lsp-features.md#15-document-links-textdocumentdocumentlink) |
97-
| 35 | Resolution-failure diagnostics (unresolved function, unresolved PHPDoc type) | Medium | Diagnostics | [diagnostics.md §3, §7](todo/diagnostics.md#3-unresolved-function-diagnostic-new) |
98-
| 36 | Warn when composer.json is missing or classmap not optimized | Medium | Diagnostics | [diagnostics.md §9](todo/diagnostics.md#9-warn-when-composerjson-is-missing-or-classmap-is-not-optimized) |
99162
| 37 | File system watching for vendor and project changes | Medium | Type Inference | [type-inference.md §5](todo/type-inference.md#5-file-system-watching-for-vendor-and-project-changes) |
100163
| 38 | Property hooks (PHP 8.4) | Medium | Type Inference | [type-inference.md §6](todo/type-inference.md#6-property-hooks-php-84) |
101-
| 39 | Simplify with null coalescing / null-safe operator (code action) | Medium | Code Actions | [actions.md §2](todo/actions.md#2-simplify-with-null-coalescing--null-safe-operator) |
102-
| 40 | Inlay hints (`textDocument/inlayHint`) | Medium | LSP Features | [lsp-features.md §9](todo/lsp-features.md#9-inlay-hints-textdocumentinlayhint) |
164+
| 35 | Resolution-failure diagnostics (unresolved function, unresolved PHPDoc type) | Medium | Diagnostics | [diagnostics.md §3, §7](todo/diagnostics.md#3-unresolved-function-diagnostic-new) |
103165
| 91 | GTD for built-in symbols via project-level phpstorm-stubs | Low | External Stubs | [external-stubs.md §1](todo/external-stubs.md#phase-1-project-level-phpstorm-stubs-for-gtd) |
104-
| 100 | Formatting proxy (php-cs-fixer / phpcbf) | Medium | LSP Features | [lsp-features.md §19](todo/lsp-features.md#19-formatting-proxy-textdocumentformatting-textdocumentrangeformatting) |
105-
| 101 | Argument count diagnostic | Low | Diagnostics | [diagnostics.md §8](todo/diagnostics.md#8-argument-count-diagnostic) |
106-
| 102 | Implementation error diagnostic | Medium | Diagnostics | [diagnostics.md §10](todo/diagnostics.md#10-implementation-error-diagnostic) |
107-
| 103 | Stub extension selection (`[stubs] extensions`) | Low | Configuration | [config.md §stubs](todo/config.md#extension-stub-selection) |
108166

109-
**After Sprint 5:** PHPantom has a complete, polished LSP feature set.
110-
Users moving to Zed/Neovim/Helix lose nothing on the intelligence side
111-
and gain 1000× faster startup. The remaining gaps are Blade.
167+
**After Sprint 6:** PHPantom has the deepest type intelligence of
168+
any PHP language server. Conditional return types, `key-of`/`value-of`,
169+
property hooks, and inherited docblock types all work. The type
170+
engine advantage is unambiguous.
171+
172+
---
173+
174+
## Sprint 7 — Remaining LSP features & code actions
175+
176+
Low-effort LSP features that didn't fit earlier sprints, plus
177+
code action polish.
178+
179+
| # | Item | Effort | Domain | Doc Link |
180+
|---|---|---|---|---|
181+
| 32 | Code Lens: jump to prototype method | Low | LSP Features | [lsp-features.md §8](todo/lsp-features.md#8-code-lens-jump-to-prototype-method) |
182+
| 34 | Document Links (`textDocument/documentLink`) | Low | LSP Features | [lsp-features.md §15](todo/lsp-features.md#15-document-links-textdocumentdocumentlink) |
183+
| 39 | Simplify with null coalescing / null-safe operator (code action) | Medium | Code Actions | [actions.md §2](todo/actions.md#2-simplify-with-null-coalescing--null-safe-operator) |
112184

113185
---
114186

115-
## Sprint 6 — Deep type accuracy & Laravel excellence
187+
## Sprint 8 — Deep type accuracy & Laravel excellence
116188

117189
These items push type resolution accuracy beyond what any tool offers.
118190
They're the long tail that makes PHPantom the definitive choice for
@@ -131,7 +203,7 @@ projects that care about types.
131203
| 52 | `class_alias()` support | Medium | Completion | [completion.md §8](todo/completion.md#8-class_alias-support) |
132204
| 53 | Attribute constructor signature help | Medium | Signature Help | [signature-help.md §4](todo/signature-help.md#4-attribute-constructor-signature-help) |
133205
| 54 | Closure/arrow function parameter signature help | Medium | Signature Help | [signature-help.md §5](todo/signature-help.md#5-closure--arrow-function-parameter-signature-help) |
134-
| 55 | Diagnostic suppression intelligence | Medium | Diagnostics | [diagnostics.md §8](todo/diagnostics.md#8-diagnostic-suppression-intelligence) |
206+
| 55 | Diagnostic suppression intelligence | Medium | Diagnostics | [diagnostics.md §6](todo/diagnostics.md#6-diagnostic-suppression-intelligence) |
135207
| 56 | Partial result streaming via `$/progress` | Medium-High | LSP Features | [lsp-features.md §6](todo/lsp-features.md#6-partial-result-streaming-via-progress) |
136208

137209
**Note:** Item 51 (Type Hierarchy) depends on the go-to-implementation
@@ -142,7 +214,7 @@ addresses the complementary inbound direction.
142214

143215
---
144216

145-
## Sprint 7 — Blade support
217+
## Sprint 9 — Blade support
146218

147219
Blade is a multi-phase project tracked in [todo/blade.md](todo/blade.md).
148220
Shipping Blade support makes PHPantom the first open-source PHP language
@@ -192,7 +264,7 @@ eventually but don't move the needle.
192264
|---|---|---|---|---|
193265
| 72 | Switch → match conversion | Medium | Code Actions | [actions.md §4](todo/actions.md#4-switch--match-conversion) |
194266
| 89 | Incremental text sync | Medium | Performance | [performance.md §8](todo/performance.md#8-incremental-text-sync) |
195-
| 104 | Unreachable code diagnostic | Low | Diagnostics | [diagnostics.md §9](todo/diagnostics.md#9-unreachable-code-diagnostic) |
267+
| 104 | Unreachable code diagnostic | Low | Diagnostics | [diagnostics.md §8](todo/diagnostics.md#8-unreachable-code-diagnostic) |
196268

197269
### Performance long-tail
198270

0 commit comments

Comments
 (0)