Generalize the class locator to a kind-agnostic SymbolLocator

[Firehed]

Slice S3.7 (build manifest) — plan step 3b (docs/architecture/0002-execution-plan.md §3, §3b, §5.3), RFC 1 §5.1, §5.2, §5.3.

Generalizes ClassLocator into a kind-agnostic SymbolLocator and folds in autoload.files, so S3.8 can add lookupFunction / lookupConstant over a finished interface.

What's here

SymbolLocator::locate(QualifiedName, NameKind): ?string (src/Knowledge/) — one entry for all three of PHP's symbol namespaces. The kind is a parameter rather than a method per kind, keeping the backends × kinds cross-product closed (§5.6). It is not redundant with the name: QualifiedName is deliberately kind-neutral, and Foo\bar names a different symbol as a function than as a constant.

ComposerSymbolLocator (src/Index/) — the two halves work differently because Composer's data does. Class-likes have a name→file map (PSR-4/PSR-0/classmap), so a lookup is arithmetic on the name and reads no file. Functions and constants have no such map and never can, so a name→file index is derived by parsing the autoload.files set — explicit and usually tiny, which is what makes it affordable (§3).

DeclarationScanner / FileDeclarations — reads the functions and constants a parsed file declares, using the namespacedName that NameResolver already sets in ParserService, rather than tracking namespace statements by hand. Constant reach covers const declarations and literal-name define(); a computed-name define() is a runtime call invisible to a static parse and is out of scope (§3b), which a test asserts rather than leaving to prose.

QualifiedName (src/Domain/) — the kind-neutral base FQN value type from §5.3.

Lazy index, warmed at initialized — the index builds on the first function/constant lookup, so nothing depends on startup ordering and §1's lazy-first principle holds. KnowledgeWarmer (an InitializedListener) also triggers the build so the cost lands before the first keystroke; Cache\Warmable states that this is latency only and an unwarmed implementation must answer identically. Per-file scans sit behind the PSR-16 seam keyed by path, and FilesystemBackend::invalidate() forwards to the locator, so an external change to an autoload.files entry re-reads exactly that file (§5.2, §5.3).

ClassLocator / ComposerClassLocator are removed; all eight of their test cases were ported to ComposerSymbolLocatorTest first.

Acceptance criteria

• ClassLocator is generalized to a kind-agnostic SymbolLocator
• autoload.files is folded in — read by ComposerAutoloadMap, split by partitionByVendorDirectory, and indexed by the locator
• locate answers definitively for all three kinds; absence is a bare null (§5.3)
• Names are typed identifiers, not bare strings (§5.1)
• Function names match case-insensitively, constant names case-sensitively
• Constant reach covers const and literal-name define(); computed-name define() is out of scope and tested as such
• External-change invalidation reaches the locator's per-file scans
• FilesystemBackend and KnowledgeStack resolve through the new seam; the superseded locator is gone
• Behavior-preserving on every Step P surface — all goldens unchanged
• 100% line/method coverage on new and touched classes

Notes

• Deviation from the manifest's JIT note, recorded in build-manifest.md: it scheduled QualifiedName for S3.8, but the kind-agnostic signature makes S3.7 its first caller, so it lands here. NameKind already existed in src/Resolution/. FunctionName / ConstantName still have no caller and remain S3.8's.
• Naming overlap: plan §5.2 reserves a deferred SymbolSource::locate(QualifiedName, NameKind): ?SymbolDefinition for the workspace scope. That is a different layer (a SymbolDefinition on the read interface) from this one (a file path below the backend). Followed the manifest's SymbolLocator naming verbatim; worth a look if the collision reads badly.
• The warm-up adds startup parses. The two Step 0 parse-budget tests in ServerTest counted from zero, so they now measure a startup baseline instead of hard-coding one — a change to the fixture project's files autoload no longer silently moves a budget it has nothing to do with.
• The warm-up is synchronous, since Step 6's scheduler tier is deferred. This repository's own autoload.files set is 12 files / 139 KB, ~35 ms at §8.1's measured 4 MB/s.
• New fixtures tests/Fixtures/AutoloadFiles/{globals,helpers}.php are outside src/ and reached only through the files autoload, so they are absent from the PSR-4 corpus and move no golden. tests/Fixtures needs a composer dump-autoload (or install) to pick them up.

Candidate closes (pending review verification): the manifest lists #239 / #181 / #317 as landing somewhere in S3.7–S3.10; #181 (autoload.files reach) is the plausible one here, but I have not read the issues, so none are wired.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.61%. Comparing base (7c91158) to head (f6d5e6f).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@             Coverage Diff              @@
##               main     #388      +/-   ##
============================================
+ Coverage     98.55%   98.61%   +0.05%     
- Complexity     1753     1794      +41     
============================================
  Files           115      120       +5     
  Lines          4434     4534     +100     
============================================
+ Hits           4370     4471     +101     
+ Misses           64       63       -1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.