fix(lsp-server): improve rename feature cache invalidation and test coverage

Author: fengkx

docs/specs/beancount-lsp-p0-correctness-implementation-summary-2026-02-25.md

@@ -357,6 +357,56 @@ Validated behaviors in VSCode Web playground (WASM v3):
   - message
   - source
 
+### G6. Rename cache invalidation follow-up + playground FSA verification (2026-02-27)
+
+Problem observed after the initial P0 rename fixes:
+
+- `rename` can modify unopened files, but server-side caches for those files were not explicitly invalidated in the rename request path.
+- `RenameFeature` also queued async reindex work before client-side workspace edits were guaranteed to be applied, which could create short-lived stale index/range behavior.
+
+Fix implemented:
+
+- `packages/lsp-server/src/common/features/rename.ts`
+  - Added `private invalidateAffectedUris(uris: string[])`
+  - For every URI in rename results:
+    - `documents.removeFile(uri)`
+    - `trees.invalidateCache(uri)`
+  - Removed rename-time `symbolIndex.addAsyncFile(uri)` enqueueing (reindex now relies on actual document/watch events)
+
+Test coverage added/updated:
+
+- `packages/lsp-server/src/test/features/references-rename.test.ts`
+  - Added regression test to assert:
+    - rename invalidates affected document/tree caches
+    - rename no longer enqueues async reindex directly
+- `packages/lsp-server/src/test/utils/test-server-harness.ts`
+  - Adjusted `InMemoryDocumentStore.removeFile()` semantics to match production `DocumentStore.removeFile()` behavior (clear retrieved-file cache semantics instead of deleting open documents)
+
+Playground browser verification (VSCode Web + FSA mode, Chrome DevTools MCP):
+
+- Repro fixture created in local filesystem (`/tmp/bean-rename-fsa-case`) with:
+  - `main.bean`
+  - `a.bean`
+  - `b.bean`
+- Verified scenario:
+  1. Open `a.bean` only (keep `b.bean` unopened)
+  2. Rename `Assets:Cash` -> `Assets:Cash:Wallet`
+  3. Confirmed browser reports `Made 4 text edits in 2 files`
+  4. Confirmed unopened `b.bean` content was updated on disk
+  5. Opened `b.bean`, invoked `F2` on renamed token, prepare-rename succeeded
+  6. Renamed back `Assets:Cash:Wallet` -> `Assets:Cash`
+  7. Confirmed both files reverted correctly on disk
+
+Validation outcome:
+
+- Cross-file rename on unopened documents works in playground FSA mode.
+- No obvious prepare-rename position mismatch was observed on the renamed token after opening `b.bean`.
+- `Find References` in this playground repro did not produce usable baseline results (`No references found`), so this iteration did **not** validate post-rename reference-location accuracy in browser UI.
+
+Reviewer note:
+
+- During reverse rename, an editor-side list item (outline/symbol-like UI) briefly appeared stale while on-disk file contents were already correct. This may be a UI refresh lag rather than AST/range corruption, but it remains a good follow-up target if position issues are reported again.
+
 ### Review focus
 
 - Confirm config loading remains safe when `getConfiguration` returns non-object values.

packages/lsp-server/src/common/features/rename.ts

@@ -230,13 +230,19 @@ export class RenameFeature {
 				Object.keys(changes).length
 			} files and ${allLocations.length} occurrences (${references.length} references, ${definitions.length} definitions)`,
 		);
-		Object.keys(changes).forEach(uri => {
-			this.symbolIndex.addAsyncFile(uri);
-		});
+		this.invalidateAffectedUris(Object.keys(changes));
 
 		return { changes };
 	}
 
+	private invalidateAffectedUris(uris: string[]): void {
+		for (const uri of uris) {
+			this.documents.removeFile(uri);
+			this.trees.invalidateCache(uri);
+			logger.debug(`Invalidated rename-affected caches for ${uri}`);
+		}
+	}
+
 	private async detectRenameTargetKind(
 		document: import('vscode-languageserver-textdocument').TextDocument,
 		position: lsp.Position,

packages/lsp-server/src/test/features/references-rename.test.ts

@@ -108,7 +108,7 @@ describe('references + rename correctness', () => {
 		'  Income:Salary',
 	].join('\n');
 	const docs = new InMemoryDocumentStore({ [uri]: text });
-	const trees = {} as never;
+	const trees = { invalidateCache() {} } as never;
 
 	const accountDef = makeSymbol(SymbolType.ACCOUNT_DEFINITION, uri, 'Assets:Cash', compact(rangeForOccurrence(text, 'Assets:Cash', 0)));
 	const accountUse = makeSymbol(SymbolType.ACCOUNT_USAGE, uri, 'Assets:Cash', compact(rangeForOccurrence(text, 'Assets:Cash', 1)));
@@ -120,6 +120,7 @@ describe('references + rename correctness', () => {
 	const narrationUse = makeSymbol(SymbolType.NARRATION, uri, 'Old Narration', compact(rangeForOccurrence(text, '"Old Narration"', 0)));
 	const all = [accountDef, accountUse, commodityDef, commodityUse, tagUse, linkUse, payeeUse, narrationUse];
 
+	const addAsyncFileSpy = vi.fn();
 	const symbolIndex = {
 		async findAsync(query: Record<string, unknown>) {
 			return all.filter((s) => {
@@ -130,11 +131,12 @@ describe('references + rename correctness', () => {
 		},
 		async getAccountDefinitions() { return [accountDef]; },
 		async getCommodityDefinitions() { return [commodityDef]; },
-		addAsyncFile() {},
+		addAsyncFile: addAsyncFileSpy,
 	} as unknown as import('../../common/features/symbol-index').SymbolIndex;
 
 	beforeEach(() => {
 		positionKinds.clear();
+		addAsyncFileSpy.mockReset();
 	});
 
 	it('honors includeDeclaration for account references', async () => {
@@ -177,6 +179,42 @@ describe('references + rename correctness', () => {
 		expect(Object.values(narrationEdit.changes).flat().some((e: any) => e.newText === '"New Narration"')).toBe(true);
 	});
 
+	it('rename invalidates affected document/tree caches and does not enqueue async reindex', async () => {
+		const secondaryUri = 'file:///secondary.bean';
+		const removeFileSpy = vi.spyOn(docs, 'removeFile');
+		const invalidateCacheSpy = vi.fn();
+		const treesWithInvalidate = { invalidateCache: invalidateCacheSpy } as never;
+		const rename = new RenameFeature(docs as never, treesWithInvalidate, symbolIndex);
+		const tagPos = positionAt(text, '#oldtag', 1);
+		positionKinds.set(posKey(tagPos.line, tagPos.character), 'tag');
+
+		const refsSpy = vi.spyOn(ReferencesFeature.prototype, 'onReferences').mockResolvedValue([
+			{ uri, range: rangeForOccurrence(text, '#oldtag', 0) },
+			{
+				uri: secondaryUri,
+				range: {
+					start: { line: 0, character: 0 },
+					end: { line: 0, character: 7 },
+				},
+			},
+		] as any);
+		const defsSpy = vi.spyOn((rename as any).definitions, 'getDefinition').mockResolvedValue(null);
+
+		try {
+			const edit = await (rename as any).onRename({ textDocument: { uri }, position: tagPos, newName: '#newtag' });
+			expect(edit).toBeTruthy();
+			expect(removeFileSpy).toHaveBeenCalledWith(uri);
+			expect(removeFileSpy).toHaveBeenCalledWith(secondaryUri);
+			expect(invalidateCacheSpy).toHaveBeenCalledWith(uri);
+			expect(invalidateCacheSpy).toHaveBeenCalledWith(secondaryUri);
+			expect(addAsyncFileSpy).not.toHaveBeenCalled();
+		} finally {
+			refsSpy.mockRestore();
+			defsSpy.mockRestore();
+			removeFileSpy.mockRestore();
+		}
+	});
+
 	it('rename rejects invalid wrapper-prefixed or malformed names', async () => {
 		const rename = new RenameFeature(docs as never, trees, symbolIndex);
 		const tagPos = positionAt(text, '#oldtag', 1);

packages/lsp-server/src/test/utils/test-server-harness.ts

@@ -43,7 +43,9 @@ export class InMemoryDocumentStore {
 	}
 
 	removeFile(uri: string): boolean {
-		return this.docs.delete(uri);
+		// Mirrors DocumentStore.removeFile semantics: clear only retrieved file cache,
+		// not LSP-opened documents tracked by TextDocuments.
+		return this.docs.has(uri);
 	}
 
 	isOpen(uri: string): boolean {