refactor(apex-lsp-parser-ast): make ISymbolManager async, delegate to ops - W-22201104

[kylewalke]

What does this PR do?

Phase 2 of the Apex Language Server worker-topology refactor — flips
ISymbolManager from synchronous to Promise-returning and replaces
the ~6.3k-line ApexSymbolManager with an ~850-line coordinator that
delegates to the Effect ops/services added in Phase 1 (#351).
Behavior-preserving; the entire test suite still passes.

Stacked PR. Targets feature/W-22201103-effect-ops-services so
reviewers see only the Phase 2 diff. Will be retargeted to main
once #351 merges.

Why a single commit (the WI's 6a/6b note)

The interface flip is atomic: the moment ISymbolManager reads
become Promise<...>, every caller in the repo must await in the
same compile step. A clean 6a/6b split is not achievable without
adding backward-compat shims absent from phale/workers (much extra
work that deviates from the source-of-truth branch). Lands as one
atomic commit; one bisect step.

packages/apex-parser-ast/src/types/ISymbolManager.ts

• All read methods (getSymbol, findSymbolByName, findSymbolByFQN,
  findFQNForStandardClass, findSymbolsInFile, findFilesForSymbol,
  getAllReferencesInFile, getAllSymbolsForCompletion,
  findReferencesTo, findReferencesFrom, findRelatedSymbols,
  resolveSymbol, …) return Promise<...>.
• addSymbol returns Promise<void> so worker callers can await
  data-owner mutation completion.

packages/apex-parser-ast/src/symbols/ApexSymbolManager.ts

• ~6.3k → ~850 LoC. Becomes a thin coordinator that translates
  legacy call signatures into the Effect ops added in feat(apex-lsp-parser-ast): add Effect ops and services for symbol management - W-22201103 #351
  (symbolLookup, symbolMutation, symbolProvider,
  symbolResolution, referenceOps, graphAnalysis,
  typeHierarchy, stdlibLoading) via the live SymbolIndexStore,
  ReferenceStore, CacheStore, FileStateStore, and
  ResourceLoaderService.

packages/apex-parser-ast/src/symbols/services/symbolManagerFacade.ts

• Drops the Promise.resolve(legacyManager.addSymbol(...)) bridge
  added in feat(apex-lsp-parser-ast): add Effect ops and services for symbol management - W-22201103 #351 now that addSymbol is genuinely async.

packages/apex-parser-ast/src/symbols/{ApexSymbolIndexingService,ApexSymbolProcessingManager}.ts

• Add await on the new async ISymbolManager calls.

packages/apex-parser-ast/src/semantics/validation/

• All 25 validators (AnnotationProperty, AssignmentAccess,
  ClassHierarchy, Constructor, Deprecation, Exception, Expression,
  Instanceof, InterfaceHierarchy, MethodCall, MethodResolution,
  NewExpression, StaticContext, SwitchStatement, TypeAssignment,
  TypeResolution, TypeVisibility, UnknownAnnotation,
  VariableResolution, …) plus ArtifactLoadingHelper,
  ValidatorRegistry, and utils/visibilityUtils propagate await
  on ISymbolManager reads.

packages/apex-parser-ast/src/namespace/

• NamespaceResolutionService, NamespaceUtils, and
  ResolutionRules await ISymbolManager reads.

packages/lsp-compliant-services/src/services/ (and utils/)

• All processing services that read symbols (Hover, Definition,
  Implementation, References, Completion, Diagnostic, CodeAction,
  CodeLens, GraphData, Document, WorkspaceSymbol, SignatureHelp,
  LayerEnrichment, PrerequisiteOrchestration,
  MissingArtifactResolution, …) propagate await and convert local
  helpers that consume those reads into async /
  Promise-returning shapes.
• displayFQNUtils and missingArtifactUtils updated similarly.

Tests

• ~35 apex-parser-ast and 8 lsp-compliant-services test files
  updated to await the new async API. No coverage shape changes.
• Snapshot file semantic-errors.test.ts.snap was deliberately not
  pulled from phale/workers (its updates accompany Phase 3
  behavior). Existing snapshots still pass against Phase 2.

Out of scope (deferred to later stories)

• packages/apex-ls/ worker runtime (worker.platform,
  WorkerCoordinator, LCSAdapter, CoordinatorAssistanceMediator,
  ResourceLoaderProxy, WorkerExecArgvBuilder, WorkspaceBatchHandler)
• lsp-compliant-services/src/workers/WorkerBackendBootstrap.ts
• Phase 3 LSPQueueManager rewrite + ServiceFactory /
  ServiceConfiguration worker-topology wiring
• VS Code worker observability scripts
• docs/architecture/, docs/debugging/, docs/testing/ write-back
  documentation
• apex-lsp-shared/src/workerWireSchemas.ts Phase 3 additions

---

Follow-up fixes on this branch since original push

Additional commits beyond the original refactor (all small, targeted):

fix: stdlib availability (3f7b723b)

Fixes a cold-start regression surfaced by hover on bare standard-
library types (String, Integer, Assert, …).

Root cause. ApexSymbolManager's constructor defaults its
stdlibProvider to ResourceLoaderNoOpInstance
(ApexSymbolManager.ts:296-299).
ApexSymbolProcessingManager.getInstance(stdlibProvider?) only
applies the argument on the first call that creates the singleton —
and every production call site (hover, completion, diagnostics,
definition, rename, code lens, workspace symbol, etc.) uses the
no-arg form. Meanwhile LCSAdapter.initializeResourceLoader
dutifully loads the ZIP into the ResourceLoader singleton but
never injects it. Result: findNamespaceForClass('String') returns
an empty set forever, isStandardLibraryType returns false, and
hover on stdlib types falls into the "🔍 Searching for symbol…"
placeholder / returns the enclosing variable symbol.

Fix. After ResourceLoader.initialize() resolves in
LCSAdapter.initializeResourceLoader, call
ApexSymbolManager.setStdlibProvider({...}) with an inline adapter
that delegates to the initialized ResourceLoader singleton. Uses
the already-defined but previously-never-called setStdlibProvider
setter
(ApexSymbolManager.ts:392),
whose entire purpose was this scenario.

• Single-file, 32-line change in
  packages/apex-ls/src/server/LCSAdapter.ts.
• New 3-case regression test
  e2e-tests/tests/apex-hover-stdlib.spec.ts
  covering String as a method-call qualifier
  (String.isBlank(...)), a declared field type
  (private String instanceId;), and a method return type
  (public static String getCurrentUserName() {...}). All three
  fail on the original refactor commit and pass after the fix.
• Investigation notes captured in
  docs/hover-string-diagnosis.md.
• Considered but deferred — Alternative B: await initializeResourceLoader() at server startup instead of
  fire-and-forget
  (LCSAdapter.ts:1598).
  That would close the remaining 1-2s cold-start race window, but
  trades LSP readiness latency and warrants its own measurement;
  tracked as a follow-up ticket.

fix: pjson update (8ed91c4c)

package-lock.json housekeeping (-1 net line). No runtime change.

fix: remove extra cmt (ac1b00a2)

Drops a stray comment block in apex-hover-stdlib.spec.ts left over
from the investigation.

---

Notes

• Stats: 90 files changed, +3,047 / −7,248 (net −4,201 thanks to
  ApexSymbolManager.ts shedding ~5.4k LoC into the Phase 1 ops).
  Follow-up fix commits add ~100 LoC across LCSAdapter.ts and the
  new e2e spec; totals updated accordingly in the diff viewer.
• Verification (husky pre-commit + local runs):
  • compile / lint / format: clean
  • apex-parser-ast jest: 2762 passed / 0 failed
  • lsp-compliant-services jest: 551 passed / 0 failed
  • apex-ls jest: 53 passed / 0 failed
  • e2e-tests/tests/apex-hover-stdlib.spec.ts (new, 3 cases):
    passed (27.8s)
  • e2e-tests/tests/apex-hover.spec.ts (existing, 21 cases):
    passed (2.6m)

What issues does this PR fix or reference?

@W-22201104@

Made with Cursor