feat: add textDocument/references support to language server (#527)

## Summary
- Adds `textDocument/references` support to the nadle language server,
enabling "Find All References" for task names
- Handles cursor on both `tasks.register("name")` registration sites and
`dependsOn` string references
- Collects references across all open documents via new
`DocumentStore.getAllAnalyses()` method
- Respects `includeDeclaration` context flag per LSP spec

Closes #526

## Test plan
- [x] 7 new test cases in `references.test.ts` covering:
  - References from registration cursor (includeDeclaration true/false)
  - References from dependsOn cursor
  - Unreferenced tasks
  - Workspace-qualified refs (skipped)
  - Non-task strings (empty result)
- [x] All 58 language-server tests pass
- [x] Type-check passes
- [ ] Verify "Find All References" works in VS Code with the extension

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: nam-hle

packages/language-server/src/definitions.ts

@@ -4,7 +4,7 @@ import type { TextDocument } from "vscode-languageserver-textdocument";
 
 import type { DocumentAnalysis } from "./analyzer.js";
 
-function findDependsOnNameAtPosition(content: string, offset: number): { name: string; isWorkspaceQualified: boolean } | null {
+export function findDependsOnNameAtPosition(content: string, offset: number): { name: string; isWorkspaceQualified: boolean } | null {
 	const file = ts.createSourceFile("def.ts", content, ts.ScriptTarget.Latest, true);
 	let result: { name: string; isWorkspaceQualified: boolean } | null = null;
 

packages/language-server/src/document-store.ts

@@ -16,6 +16,10 @@ export class DocumentStore {
 		return result;
 	}
 
+	public getAllAnalyses(): DocumentAnalysis[] {
+		return [...this.cache.values()];
+	}
+
 	public removeDocument(uri: string): void {
 		this.cache.delete(uri);
 	}

packages/language-server/src/index.ts

@@ -1,3 +1,4 @@
 export { analyzeDocument } from "./analyzer.js";
+export { getReferences } from "./references.js";
 export { DocumentStore } from "./document-store.js";
 export type { DependencyRef, DocumentAnalysis, TaskConfigInfo, TaskRegistration } from "./analyzer.js";

packages/language-server/src/references.ts

@@ -0,0 +1,73 @@
+import type { TextDocument } from "vscode-languageserver-textdocument";
+import type { Location, Position, ReferenceContext } from "vscode-languageserver";
+
+import type { DocumentAnalysis } from "./analyzer.js";
+import { findDependsOnNameAtPosition } from "./definitions.js";
+
+function findRegistrationNameAtPosition(analysis: DocumentAnalysis, offset: number, document: TextDocument): string | null {
+	for (const reg of analysis.registrations) {
+		if (reg.name === null) {
+			continue;
+		}
+
+		const start = document.offsetAt(reg.nameRange.start);
+		const end = document.offsetAt(reg.nameRange.end);
+
+		if (offset > start && offset < end) {
+			return reg.name;
+		}
+	}
+
+	return null;
+}
+
+export function getReferences(analyses: DocumentAnalysis[], position: Position, document: TextDocument, context: ReferenceContext): Location[] {
+	const offset = document.offsetAt(position);
+	const content = document.getText();
+	const currentUri = document.uri;
+
+	const currentAnalysis = analyses.find((a) => a.uri === currentUri);
+	let taskName: string | null = null;
+
+	const depRef = findDependsOnNameAtPosition(content, offset);
+
+	if (depRef && !depRef.isWorkspaceQualified) {
+		taskName = depRef.name;
+	}
+
+	if (!taskName && currentAnalysis) {
+		taskName = findRegistrationNameAtPosition(currentAnalysis, offset, document);
+	}
+
+	if (!taskName) {
+		return [];
+	}
+
+	const locations: Location[] = [];
+
+	for (const analysis of analyses) {
+		if (context.includeDeclaration) {
+			const entries = analysis.taskNames.get(taskName);
+
+			if (entries) {
+				for (const entry of entries) {
+					locations.push({ uri: analysis.uri, range: entry.nameRange });
+				}
+			}
+		}
+
+		for (const reg of analysis.registrations) {
+			if (!reg.configuration) {
+				continue;
+			}
+
+			for (const dep of reg.configuration.dependsOn) {
+				if (dep.name === taskName && !dep.isWorkspaceQualified) {
+					locations.push({ range: dep.range, uri: analysis.uri });
+				}
+			}
+		}
+	}
+
+	return locations;
+}

packages/language-server/src/server.ts

@@ -6,6 +6,7 @@ import { TextDocument } from "vscode-languageserver-textdocument";
 import { TextDocuments, createConnection, ProposedFeatures, TextDocumentSyncKind } from "vscode-languageserver/node";
 
 import { getHover } from "./hover.js";
+import { getReferences } from "./references.js";
 import { getDefinition } from "./definitions.js";
 import { getCompletions } from "./completions.js";
 import { DocumentStore } from "./document-store.js";
@@ -24,6 +25,7 @@ connection.onInitialize((): InitializeResult => {
 		capabilities: {
 			hoverProvider: true,
 			definitionProvider: true,
+			referencesProvider: true,
 			textDocumentSync: TextDocumentSyncKind.Incremental,
 			completionProvider: {
 				resolveProvider: false,
@@ -129,5 +131,15 @@ connection.onDefinition(({ position, textDocument }) => {
 	return getDefinition(analysis, position, doc);
 });
 
+connection.onReferences(({ context, position, textDocument }) => {
+	const doc = documents.get(textDocument.uri);
+
+	if (!doc) {
+		return [];
+	}
+
+	return getReferences(store.getAllAnalyses(), position, doc, context);
+});
+
 documents.listen(connection);
 connection.listen();

packages/language-server/test/references.test.ts

@@ -0,0 +1,119 @@
+import Path from "node:path";
+import Fs from "node:fs/promises";
+
+import { it, expect, describe } from "vitest";
+import { analyzeDocument } from "src/analyzer.js";
+import { getReferences } from "src/references.js";
+import { TextDocument } from "vscode-languageserver-textdocument";
+
+const fixturesDir = Path.resolve(import.meta.dirname, "__fixtures__");
+
+async function setupFixture(name: string) {
+	const filePath = Path.resolve(fixturesDir, name);
+	const content = await Fs.readFile(filePath, "utf-8");
+	const analysis = analyzeDocument(content, name);
+	const uri = `file:///${name}`;
+	const doc = TextDocument.create(uri, "typescript", 1, content);
+
+	return { doc, analysis: { ...analysis, uri } };
+}
+
+describe("getReferences", () => {
+	it("finds dependsOn refs when cursor is on a registration name", async () => {
+		const { doc, analysis } = await setupFixture("valid.ts");
+		const content = doc.getText();
+		const idx = content.indexOf('"compile"');
+		const offset = idx + 1;
+		const position = doc.positionAt(offset);
+		const locations = getReferences([analysis], position, doc, { includeDeclaration: true });
+
+		expect(locations.length).toBe(2);
+
+		const compileReg = analysis.registrations.find((r) => r.name === "compile");
+		expect(locations).toContainEqual({ uri: analysis.uri, range: compileReg!.nameRange });
+
+		const buildReg = analysis.registrations.find((r) => r.name === "build");
+		const compileDep = buildReg!.configuration!.dependsOn.find((d) => d.name === "compile");
+		expect(locations).toContainEqual({ uri: analysis.uri, range: compileDep!.range });
+	});
+
+	it("finds registration + dependsOn refs from a dependsOn cursor", async () => {
+		const { doc, analysis } = await setupFixture("valid.ts");
+		const content = doc.getText();
+		const dependsOnIdx = content.indexOf('dependsOn: ["compile"');
+		const offset = dependsOnIdx + 'dependsOn: ["'.length + 1;
+		const position = doc.positionAt(offset);
+		const locations = getReferences([analysis], position, doc, { includeDeclaration: true });
+
+		expect(locations.length).toBe(2);
+
+		const compileReg = analysis.registrations.find((r) => r.name === "compile");
+		expect(locations).toContainEqual({ uri: analysis.uri, range: compileReg!.nameRange });
+
+		const buildReg = analysis.registrations.find((r) => r.name === "build");
+		const compileDep = buildReg!.configuration!.dependsOn.find((d) => d.name === "compile");
+		expect(locations).toContainEqual({ uri: analysis.uri, range: compileDep!.range });
+	});
+
+	it("excludes declaration when includeDeclaration is false", async () => {
+		const { doc, analysis } = await setupFixture("valid.ts");
+		const content = doc.getText();
+		const idx = content.indexOf('"compile"');
+		const offset = idx + 1;
+		const position = doc.positionAt(offset);
+		const locations = getReferences([analysis], position, doc, { includeDeclaration: false });
+
+		expect(locations.length).toBe(1);
+
+		const buildReg = analysis.registrations.find((r) => r.name === "build");
+		const compileDep = buildReg!.configuration!.dependsOn.find((d) => d.name === "compile");
+		expect(locations).toContainEqual({ uri: analysis.uri, range: compileDep!.range });
+	});
+
+	it("returns only declaration for unreferenced task", async () => {
+		const { doc, analysis } = await setupFixture("valid.ts");
+		const content = doc.getText();
+		const idx = content.indexOf('"clean-cache"');
+		const offset = idx + 1;
+		const position = doc.positionAt(offset);
+		const locations = getReferences([analysis], position, doc, { includeDeclaration: true });
+
+		expect(locations.length).toBe(1);
+
+		const reg = analysis.registrations.find((r) => r.name === "clean-cache");
+		expect(locations[0]).toEqual({ uri: analysis.uri, range: reg!.nameRange });
+	});
+
+	it("returns empty for unreferenced task with includeDeclaration false", async () => {
+		const { doc, analysis } = await setupFixture("valid.ts");
+		const content = doc.getText();
+		const idx = content.indexOf('"clean-cache"');
+		const offset = idx + 1;
+		const position = doc.positionAt(offset);
+		const locations = getReferences([analysis], position, doc, { includeDeclaration: false });
+
+		expect(locations).toEqual([]);
+	});
+
+	it("returns empty for workspace-qualified references", async () => {
+		const { doc, analysis } = await setupFixture("unresolved-deps.ts");
+		const content = doc.getText();
+		const idx = content.indexOf('"other-pkg:build"');
+		const offset = idx + 1;
+		const position = doc.positionAt(offset);
+		const locations = getReferences([analysis], position, doc, { includeDeclaration: true });
+
+		expect(locations).toEqual([]);
+	});
+
+	it("returns empty for non-task strings", async () => {
+		const { doc, analysis } = await setupFixture("valid.ts");
+		const content = doc.getText();
+		const idx = content.indexOf('"Compile TypeScript"');
+		const offset = idx + 1;
+		const position = doc.positionAt(offset);
+		const locations = getReferences([analysis], position, doc, { includeDeclaration: true });
+
+		expect(locations).toEqual([]);
+	});
+});