Scope-first FAR/rename: derive the candidate file set from the declaration's scope instead of iterating solution files

[msarson]

Proposed by Mark during the #315 investigation: rather than collecting a broad file list and scanning/filtering, FAR should start from the current file, resolve the symbol's declaration and its SCOPE, and let Clarion's scope model dictate which files can possibly hold references.

Scope table (each row to be docs-verified and pinned):

Declaration site	Reference universe
Routine-local / procedure-local	current file only
Module data in a MEMBER file	current file only
Global data in the PROGRAM file	program + MEMBER family (FRG)
MAP / MAP-include procedure	program family
INC-declared shared class / global	reverse-INCLUDE set (FRG), pruned by the reference index's per-file word counts

#315 already shipped several rows as targeted patches inside ReferencesProvider (program-family widening for program-file cursors, file-local class scoping, mayContain word-prune, frontier-pruned class-family walk). This issue is the structural version: one scope → candidate set resolver consumed by FAR, RenameProvider, and document highlight, replacing the per-route file-list assembly.

Substrates already in place: FileRelationshipGraph (MEMBER/INCLUDE/MODULE edges, persisted), ReferenceCountIndex (per-file word counts, mtime-verified), ScopeTypeIndexService (tiered declaration lookup).

Risks to manage:

• Under-scoping fails SILENTLY (rename miss = broken compile). Every scope row needs a docs citation + fixture pin, including OMIT/COMPILE and EXTERNAL/DLL edge cases.
• Rename and FAR must consume the same resolver — asymmetry between them is the historic bug pattern (FAR call-site cursor: dot-access chainPrefix path matches sibling receiver lines TEXTUALLY (shadowed receiver leaks in, other-name receivers missed) #269, 0c289e16).

Post-1.0. Raised from the #315 thread.

[msarson]

How other LSPs handle reference-count lenses (research, 2026-07-11 — relevant to this redesign and #318)

Surveyed engines fall into two camps; none displays word-occurrence estimates.

Camp A — exact but lazy, and mostly OFF by default. TypeScript (referencesCodeLens.enabled defaults to false), rust-analyzer (each references-lens flavor individually disabled by default), C#/OmniSharp (exact, notoriously slow on large solutions). They run a real find-references per visible lens, cache the result, and hide the cost behind opt-in. This is the model we abandoned in #294 — correctly, because our per-scan cost was 0.5–106s at the time.

Camp B — persisted resolved-reference index (clangd). clangd background-parses every file in the project and stores resolved Ref objects (uses of a symbol, keyed by SymbolID) per file, persisted as .idx shards under .cache/clangd/index, reloaded incrementally when nothing changed. Find-references (and any count) is an index lookup — exact and O(1)-ish. Roslyn takes a hybrid: a per-document syntactic identifier index prunes the candidate set before semantic resolution (structurally identical to our mayContain pruning).

Structural fit: Clarion resembles C/C++ here, not Rust/TS/Go — textual INCLUDE/MEMBER, no import graph, case-insensitive, so the candidate set for a global symbol is the whole app family. That's exactly the shape clangd's index was built for; import-graph pruning isn't available to us either.

Implications, in order of effort:

1. Lens estimate counts can be wildly off (~195 shown, FAR finds 3): bare last-segment counting ignores the receiver #318 dotted-bigram estimates — cheap precision fix inside the current architecture; still an estimate.
2. Exact-lazy is newly viable — after the Reference-count lenses: absurd counts for common method names, lenses on libsrc files, click shows nothing (15s FAR timeout races to null) #315 arc, an app-scoped FAR is ~100ms, and the counting…/refresh/cache machinery in server.ts already exists. Per-visible-lens exact scans, time-sliced, may now be affordable — the Camp A model with a fast FAR under it.
3. clangd model = this issue's endgame — the scope→candidate-set resolver proposed here IS the resolution step you'd run once per file in the background and persist (refs keyed by symbol + mtime, SDI/FRG-style shards). Lens counts become exact index lookups; FAR reads the same index. ReferenceCountIndex then retires into the pruning role Roslyn uses its syntactic index for.

Sources: clangd indexing design, rust-analyzer config, VS Code TS lens default, rust-analyzer lens issue #5836.

[msarson]

Requirement from Mark (2026-07-11): cross-project FAR for exported DLL procedures

Confirmed against getFilesToSearch (ReferencesProvider.ts): global-scope symbols search the declaring project's files only, on the stated premise that 'global symbols are visible only within their own program unit (project)'. That premise is FALSE for the multi-app DLL shape this solution is built on:

• A procedure exported from a DLL project (IBSCommon / DMCommon / XMLFunctions…) is consumed by many app projects; each consumer re-declares it in its own MAP (MODULE('IBSCOMMON.DLL') blocks) and calls it freely.
• FAR from the declaration → only the DLL project's internal sites. FAR from a call site in ap1 → resolves to ap1's own MAP re-declaration → only ap1's sites; misses gl1/py1/… AND the implementation in the DLL project.
• So for exported procedures, FAR is currently 'find some references'. Within a single app, global-procedure FAR is complete (project scope covers the family) — the gap is strictly cross-project.

Design input for the scope resolver this issue proposes: the .cwproj files carry project/library references — build a project-dependency graph once, then the candidate set for an EXPORTED symbol = declaring project + every project that links it (transitively). Neither 'one project' (today, wrong) nor 'all 40' (pre-#315, slow). External-MAP re-declarations (MODULE('x.dll') entries naming the same procedure) should unify to one logical symbol so declaration/implementation/call-sites all land in one result set — the same unification rename will need.

Slots into the scope→candidate-set table as a new row: exported (DLL) procedure → declaring project ∪ dependent projects.

[msarson]

The banked DLL cross-project row shipped via #330 tier 2 (7750332): exported-procedure FAR spans defining + consuming projects using lazy .exp export edges + the load-time-cached projectReferences reverse lookup — no load-time work, no persisted index needed for this row. Rename unification deliberately excluded (generated consumer MAPs — #325). The row can be struck from this epic's scope.

[msarson]

Bounded slice shipped (5f15315, version-1.0.1) — epic stays open

Root cause of the ~9.5s startup hit found in the 2026-07-15 warm-start trace: the exact-count scan in onCodeLensResolve has no readiness gate — a visible lens resolves the instant its file opens, so the full find-all-references runs during the cold, contended startup burst and cold-tokenizes ~293 candidate files (FAR trace ... files=293, total_ms=9498).

Fix: while startupBackgroundActive is set, the resolve returns the approximate ~ estimate (or counting…) without starting the exact scan; scheduleLensRefresh() fires when the flag clears (both the solution and no-solution-timeout paths) so every visible lens re-resolves once the burst is over — warm cache, uncontended. Routine lenses stay exempt (same-file, cheap). FAR results unchanged; only the timing of the exact count moves.

Still open (the epic): the scope→candidate-set resolver and the persisted resolved-reference index (clangd model) described above — the structural endgame that makes lens counts O(1) lookups and scopes FAR's file set by declaration scope. This slice just stops the eager scan from landing in the worst possible window. Needs VM perf retest.