fix: key URI caches by NormalizedUri (text cache, settings cache)

TextCache and the per-document settings cache were keyed by raw URI strings, so a differently-encoded URI for the same file (Windows `%3A` vs `:`) could leak a duplicate entry or miss the cache - the same class as the diagnostic-store slip. Both now normalize at the boundary, matching how the reference and symbol indexes already key. Also tighten `lookupUris` and `isVisibleInContext` to `NormalizedUri` (values were already normalized; the type just dropped the brand).

Docs: correct a stale architecture note calling MSG/TRA purely highlight-only - they are now parsed server-side for diagnostics.

Author: burner1024

docs/architecture.md

@@ -516,7 +516,8 @@ Snapshot contract:
 
 ### Tree-Sitter Grammars
 
-Six tree-sitter grammars compiled to WASM (4 LSP + 2 highlight-only for external editors).
+Six tree-sitter grammars compiled to WASM: 4 back full LSP providers, and 2 (MSG, TRA) are
+parsed by the server for parse-error diagnostics and provide highlighting for external editors.
 See [grammars/README.md](../grammars/README.md) for the full list, build commands,
 WASM rationale, and type generation details.
 

server/src/core/symbol-index.ts

@@ -574,7 +574,7 @@ export class Symbols {
     /**
      * Check if a symbol is visible in the given context.
      */
-    private isVisibleInContext(symbol: IndexedSymbol, uri: string, context?: QueryContext): boolean {
+    private isVisibleInContext(symbol: IndexedSymbol, uri: NormalizedUri, context?: QueryContext): boolean {
         // Global and workspace symbols are always visible
         if (symbol.scope.level === ScopeLevel.Global || symbol.scope.level === ScopeLevel.Workspace) {
             return true;

server/src/handlers/document-lifecycle.ts

@@ -1,6 +1,6 @@
 import type { Connection } from "vscode-languageserver/node";
 import { isHeaderFile } from "../core/location-utils";
-import { normalizeUri } from "../core/normalized-uri";
+import { type NormalizedUri, normalizeUri } from "../core/normalized-uri";
 import { registry } from "../provider-registry";
 import { getServerContext, tryGetServerContext } from "../server-context";
 import { compile } from "../compile";
@@ -16,7 +16,9 @@ import {
 } from "../settings";
 import type { HandlerContext } from "./context";
 
-const documentSettings: Map<string, Thenable<MLSsettings>> = new Map();
+// Keyed by NormalizedUri so a differently-encoded URI for the same file does not
+// leak a duplicate cache entry (or miss the cached settings on close).
+const documentSettings: Map<NormalizedUri, Thenable<MLSsettings>> = new Map();
 
 /**
  * Build the `getDocumentSettings` function used by compile.ts and the
@@ -30,15 +32,18 @@ export function makeGetDocumentSettings(connection: Connection): (resource: stri
         if (!serverCtx?.capabilities.configuration) {
             return Promise.resolve(serverCtx?.settings ?? defaultSettings);
         }
-        let result = documentSettings.get(resource);
+        // Normalize only the cache key; the `scopeUri` request keeps the
+        // caller's original resource string.
+        const key = normalizeUri(resource);
+        let result = documentSettings.get(key);
         if (!result) {
             result = connection.workspace
                 .getConfiguration({
                     scopeUri: resource,
                     section: "bgforge",
                 })
                 .then(normalizeSettings);
-            documentSettings.set(resource, result);
+            documentSettings.set(key, result);
         }
         return result;
     };
@@ -51,7 +56,7 @@ export function clearDocumentSettings(): void {
 
 export function register(ctx: HandlerContext): void {
     ctx.documents.onDidClose((e) => {
-        documentSettings.delete(e.document.uri);
+        documentSettings.delete(normalizeUri(e.document.uri));
         registry.handleDocumentClosed(e.document.languageId, e.document.uri);
     });
 

server/src/shared/references-index.ts

@@ -40,8 +40,8 @@ export class ReferencesIndex {
      * Look up URIs of all files that reference a symbol name.
      * More efficient than lookup() when only file membership is needed (e.g., rename).
      */
-    lookupUris(symbolName: string): ReadonlySet<string> {
-        const uris = new Set<string>();
+    lookupUris(symbolName: string): ReadonlySet<NormalizedUri> {
+        const uris = new Set<NormalizedUri>();
         for (const [uri, fileRefs] of this.files) {
             if (fileRefs.has(symbolName)) {
                 uris.add(uri);

server/src/shared/text-cache.ts

@@ -13,6 +13,8 @@
  * the implementation a plain insertion-ordered Map with no reordering on read.
  */
 
+import { type NormalizedUri, normalizeUri } from "../core/normalized-uri";
+
 /** Cache entry with version and parsed data */
 interface CacheEntry<T> {
     version: number;
@@ -29,7 +31,9 @@ const DEFAULT_MAX_SIZE = 50;
  * @typeParam T - The type of parsed data to cache
  */
 export class TextCache<T> {
-    private readonly cache = new Map<string, CacheEntry<T>>();
+    // Keyed by NormalizedUri so a differently-encoded URI for the same file
+    // (Windows `%3A` vs `:`) hits the same entry instead of leaking a duplicate.
+    private readonly cache = new Map<NormalizedUri, CacheEntry<T>>();
     private readonly maxSize: number;
 
     constructor(maxSize: number = DEFAULT_MAX_SIZE) {
@@ -59,8 +63,12 @@ export class TextCache<T> {
             return parse(text, uri);
         }
 
+        // Normalize only the cache key; `parse` still receives the caller's
+        // original URI so any locations it embeds keep the caller's encoding.
+        const key = normalizeUri(uri);
+
         // Check cache
-        const cached = this.cache.get(uri);
+        const cached = this.cache.get(key);
         if (cached && cached.version === version) {
             return cached.data;
         }
@@ -79,13 +87,13 @@ export class TextCache<T> {
             }
         }
 
-        this.cache.set(uri, { version, data });
+        this.cache.set(key, { version, data });
         return data;
     }
 
     /** Clear cache for a specific URI. */
     clear(uri: string): void {
-        this.cache.delete(uri);
+        this.cache.delete(normalizeUri(uri));
     }
 
     /** Clear entire cache. */