vs-code-colored-references/README.md

Colored References

Find All References results shown the way Visual Studio does it — in two views.

Editor view (default) writes the results into a read-only virtual document in the same language as your source file, so your theme colors every line for free — including identifiers, because the semantic tokens are fetched from the real source files and relocated into the results (see Semantic tokens below). File headers show the containing project (.csproj/.fsproj/.vbproj) and reference count; line numbers are shown in the gutter. Read references are highlighted like search matches; writes are bold on the theme's stronger write-occurrence background, the same colour the editor itself uses for a write.

Panel view shows the same results as a table with resizable, sortable columns — Code, File, Line, Kind, Project and Containing member — grouped by file, with a text filter plus filters for reads/writes, project and test code. By default it docks in the bottom panel alongside Terminal and Problems, where a wide, short table reads best; you can drag it to either side bar, or set coloredReferences.panelLocation to put it in an editor group instead.

Works with any language server that implements references: DotRush, C# Dev Kit, OmniSharp, TypeScript, Rust, Go, ...

Usage

Action	How
Find references	Ctrl+Alt+F12 (Cmd+Alt+F12 on mac), right-click → Find All References (Colored), or the command palette
Pick a view explicitly	References: Find All References in Colored Editor / … in Results Panel
Switch the current results to the other view	Ctrl+Alt+Shift+F12, or the split icon in the tab bar
Go to a reference	Enter, F12, or Ctrl+Click on a result line. Enter on a file header opens the file.
Re-run the search	F5, or the refresh icon in the tab bar / panel toolbar

In the panel, a single click previews a reference without leaving the panel, Enter or a double-click jumps to it, arrow keys walk the list, Ctrl+F focuses the filter, and clicking a column header sorts by it. Drag a column edge to resize it; double-click the edge to reset it.

The All / Reads / Writes buttons filter by kind, and the summary line counts the writes. Kind also works in the text filter, so typing write narrows to writes as well. See Known limitations for where the kind comes from.

Filters opens a menu to hide test code or to include only some projects, each with its result count. The button shows how many filters are active, and the summary line reads "12 of 43 references" while anything is filtered. Choices persist per panel, and projects are remembered as an exclusion list — a project that only turns up in a later search shows up rather than being silently hidden.

What counts as test code is a regular expression, coloredReferences.testPattern, matched against each result's workspace-relative path and against its containing project name. The built-in pattern covers test/tests directories, FooTests.cs, Tests.cs, foo_test.go, test_foo.py, foo.spec.ts and projects named Something.Tests — without catching names that merely contain the word, like Latest.cs or a contest directory. coloredReferences.hideTests sets whether the filter starts on.

These filters narrow what the panel shows; the editor view always lists every reference.

Semantic tokens

VS Code colors code twice: a TextMate grammar handles keywords, strings and comments from the text alone, then the language server's semantic tokens recolor identifiers by what they actually are — a class, a method, a parameter. That second pass is why a C# file settles into its final colors a moment after you open it.

Language servers will not serve semantic tokens for the results document: its colored-refs URI has no file and no compilation behind it. So the tokens are fetched for each source file instead and relocated into results-document coordinates — the same line and column mapping the extension already uses to place the highlights. The colouring you get is the server's own answer, moved, rather than a guess.

In the editor view this happens after the results are on screen and only ever changes colours, never text, so nothing waits on it. The panel gets the same token types but paints them from its own palette, since a webview is not given the theme’s token colours. Set coloredReferences.semanticTokens to false for grammar-only colouring; results spanning more than 40 files skip it.

Settings

• coloredReferences.view — which view Find All References (Colored) opens: document (default) or panel
• coloredReferences.panelLocation — where the panel opens: bottom (default, docked next to Terminal / Problems and draggable to a side bar), beside (editor group to the side), or below (editor group underneath, so the table is wide and short)
• coloredReferences.semanticTokens — colour identifiers by what the language server says they are, in both views (default true)
• coloredReferences.openBeside — open results beside the current editor (default true)
• coloredReferences.showProject — show the containing project in file headers (default true)
• coloredReferences.reuseTab — reuse one results tab/panel instead of opening a new one per search (default true)
• coloredReferences.hideTests — start the panel with test code hidden (default false)
• coloredReferences.testPattern — regular expression deciding what counts as test code; empty uses the built-in pattern

Install

Either install the .vsix (Extensions view → … → Install from VSIX…) or open this folder in VS Code, run npm install, and press F5 to launch an Extension Development Host.

Tests

npm test launches a real VS Code against a C# solution, waits for the language server to answer, and asserts on the rendered results — that every displayed line maps back to the source line it claims, that navigation and hover work, that the panel's rows highlight the right occurrence, and that the containing member resolves.

Point it at your own solution with COLORED_REFS_TEST_FOLDER:

COLORED_REFS_TEST_FOLDER=/path/to/solution npm test

The run opens a generated .code-workspace that pins DotRush to the solution found in that folder, so your repository's own .vscode/settings.json is left alone. C# Dev Kit and OmniSharp are disabled for the run so the expected results stay deterministic.

Known limitations

• The panel's code column cannot use your theme's token colors: webviews are not given them as CSS variables. What each token is comes from the language server, so Profiler.Frames.Count is correctly a class then two properties — but the hues are approximated Dark+/Light+ values, so a custom theme will not match exactly. Only the editor view can be theme-exact. Without a server that serves semantic tokens the panel falls back to a small regex tokenizer, which does guess that any capitalised identifier is a type.
• Read/write kind is not part of the reference request, so it is derived two ways. Every reference is first classified from the surrounding text (assignment and compound-assignment operators, ++/--, ref/out arguments), then textDocument/documentHighlight is asked per file and its Read/Write kinds override that wherever the server has an opinion. Servers that answer with plain Text highlights, or not at all, leave the syntactic answer standing — which is good for straightforward code and can be wrong for exotic expressions. Results spanning more than 60 files skip the server round-trip entirely. The editor view paints the syntactic answer immediately and re-paints if the server disagrees, so it never waits on highlights.
• Some language servers try to attach to every document of their language, including the virtual one, and may log a harmless error about an unknown URI scheme.

Roadmap

1. Webview panel with resizable, sortable columns — done; missing: virtualized rendering for very large result sets, and remembering column layout per workspace rather than per panel
2. Semantic token overlay — done in both views
3. Filter by project / exclude tests — done in the panel
4. Read/write kind — done in both views