Show read/write kind and let the panel filter on it

The reference request carries no read/write information, so derive it:

- Classify every reference syntactically first — assignment and compound
  assignment, ++/--, and ref/out arguments are writes, everything else is a
  read. The suffix test only looks past the end of the reference, so the `=`
  in `previous = x` does not make the read of `x` look like a write.
- Then ask textDocument/documentHighlight per file, whose Read/Write kinds
  override the syntactic answer. Plain Text highlights carry no kind and
  leave it standing, so servers without the feature still get a sensible
  column. Files have to be opened as text documents for the server to
  answer, so results spanning more than 60 files skip this step.

In the panel: a sortable Kind column with read/write badges, All / Reads /
Writes buttons, the kind included in the text filter, and a write count in
the summary line. The kind filter is persisted with the rest of the view
state. Line and Kind columns carry minimum widths that fit their own
headers, which Line previously did not.

Verified against DotRush on a field that is both read and written: the
assignment and the `ref` argument classify as writes, the subscript, the
comparison and the right-hand-side use as reads.

The editor view does not mark writes yet.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

src/panel.ts

@@ -1,7 +1,7 @@
 import * as vscode from 'vscode';
 import * as path from 'path';
 import {
-    ReferenceResults, containingMembers, displayLine, relativePath,
+    RefKind, ReferenceResults, containingMembers, displayLine, refKey, referenceKinds, relativePath,
 } from './references';
 
 /** Where the results table is shown. */
@@ -24,6 +24,8 @@ export interface PanelRow {
     col: number;
     project: string;
     member: string;
+    /** Whether this reference reads or writes the symbol. */
+    kind: RefKind;
 }
 
 /**
@@ -33,7 +35,9 @@ export interface PanelRow {
  * Returns the rows plus the location each row navigates to, keyed by row id.
  */
 export function buildRows(
-    results: ReferenceResults, members: Map<string, string>,
+    results: ReferenceResults,
+    members: Map<string, string>,
+    kinds: Map<string, RefKind> = new Map(),
 ): { rows: PanelRow[]; locations: Map<number, vscode.Location> } {
     const rows: PanelRow[] = [];
     const locations = new Map<number, vscode.Location>();
@@ -57,6 +61,7 @@ export function buildRows(
                     col: range.start.character + 1,
                     project: file.project ?? '',
                     member,
+                    kind: kinds.get(refKey(file.uri, source.line, range.start.character)) ?? 'read',
                 });
                 locations.set(id, new vscode.Location(file.uri, range.start));
                 id++;
@@ -128,8 +133,11 @@ export class ResultsView {
         this.results = results;
         this.host.setTitle(`References to ${results.symbol}`);
 
-        const members = await containingMembers(results);
-        const { rows, locations } = buildRows(results, members);
+        const [members, kinds] = await Promise.all([
+            containingMembers(results),
+            referenceKinds(results),
+        ]);
+        const { rows, locations } = buildRows(results, members, kinds);
         this.locations = locations;
 
         this.post({
@@ -137,6 +145,7 @@ export class ResultsView {
             symbol: results.symbol,
             languageId: results.languageId,
             fileCount: results.files.length,
+            writeCount: rows.filter(r => r.kind === 'write').length,
             rows,
         });
     }
@@ -225,6 +234,7 @@ export class ResultsView {
         <div id="toolbar">
             <span id="summary"></span>
             <input id="filter" type="text" placeholder="Filter results (Ctrl+F)" spellcheck="false">
+            <div id="kind-filter" class="segmented" role="group" aria-label="Filter by read or write"></div>
             <button id="toggle-group" class="toolbar-button" aria-pressed="true"
                     title="Group results by file">Group by file</button>
             <button id="refresh" class="toolbar-button" title="Re-run the search (F5)">Refresh</button>

src/references.ts

@@ -369,3 +369,104 @@ export async function containingMembers(results: ReferenceResults): Promise<Map<
 export function invalidateSymbols(uri: vscode.Uri): void {
     symbolCache.delete(uri.toString());
 }
+
+// ---------------------------------------------------------------------------
+// Read / write kind
+// ---------------------------------------------------------------------------
+
+export type RefKind = 'read' | 'write';
+
+/** Key for the per-reference maps: file, 0-based line, 0-based start column. */
+export function refKey(uri: vscode.Uri, line: number, character: number): string {
+    return `${uri.toString()}|${line}|${character}`;
+}
+
+/** Assignment operators, and `++`/`--`, immediately after the reference. */
+const ASSIGNED_AFTER = /^\s*(=(?!=)|[-+*/%&|^]=|<<=|>>>?=|\?\?=|\|\|=|&&=|\+\+|--)/;
+/** `++x` / `--x` immediately before the reference. */
+const INCDEC_BEFORE = /(\+\+|--)\s*$/;
+/** C# `ref`/`out` arguments, and `&x` in C/C++, hand the callee a writable alias. */
+const BYREF_BEFORE = /(?:^|[^\w$])(ref|out)\s+$/;
+
+/**
+ * Classifies a reference from the surrounding text. Used for language servers that
+ * do not answer document highlights, and as the baseline the server can override.
+ */
+export function syntacticKind(lineText: string, range: vscode.Range): RefKind {
+    const end = range.end.line === range.start.line ? range.end.character : lineText.length;
+    const before = lineText.slice(0, Math.min(range.start.character, lineText.length));
+    const after = lineText.slice(Math.min(end, lineText.length));
+
+    if (ASSIGNED_AFTER.test(after) || INCDEC_BEFORE.test(before) || BYREF_BEFORE.test(before)) {
+        return 'write';
+    }
+    return 'read';
+}
+
+/** Asking the server for highlights in every file of a huge result set is not worth it. */
+const HIGHLIGHT_FILE_LIMIT = 60;
+
+/**
+ * Document highlights for the symbol at `position`, which carry a read/write kind.
+ * The file has to be open as a text document for the language server to answer.
+ */
+async function documentHighlights(
+    uri: vscode.Uri, position: vscode.Position,
+): Promise<vscode.DocumentHighlight[]> {
+    try {
+        await vscode.workspace.openTextDocument(uri);
+    } catch {
+        return [];
+    }
+    const highlights = await timeout(
+        vscode.commands.executeCommand<vscode.DocumentHighlight[]>(
+            'vscode.executeDocumentHighlights', uri, position),
+        4000, undefined as unknown as vscode.DocumentHighlight[]);
+    return highlights ?? [];
+}
+
+/**
+ * Read/write kind per reference, keyed by {@link refKey}.
+ *
+ * Every reference gets a syntactic classification first, then the language server's
+ * document highlights override it wherever they express an opinion — `Text` highlights
+ * carry no kind, so those keep the syntactic answer.
+ */
+export async function referenceKinds(results: ReferenceResults): Promise<Map<string, RefKind>> {
+    const kinds = new Map<string, RefKind>();
+    for (const file of results.files) {
+        for (const line of file.lines) {
+            for (const range of line.ranges) {
+                kinds.set(refKey(file.uri, line.line, range.start.character),
+                    syntacticKind(line.text, range));
+            }
+        }
+    }
+
+    if (results.files.length > HIGHLIGHT_FILE_LIMIT) {
+        return kinds;
+    }
+
+    await Promise.all(results.files.map(async file => {
+        const first = file.lines[0];
+        if (!first) {
+            return;
+        }
+        const highlights = await documentHighlights(file.uri, first.ranges[0].start);
+        for (const highlight of highlights) {
+            const kind = highlight.kind === vscode.DocumentHighlightKind.Write ? 'write'
+                : highlight.kind === vscode.DocumentHighlightKind.Read ? 'read'
+                    : undefined;
+            if (!kind) {
+                continue;
+            }
+            const key = refKey(file.uri, highlight.range.start.line, highlight.range.start.character);
+            // Only for ranges that are actually in the results.
+            if (kinds.has(key)) {
+                kinds.set(key, kind);
+            }
+        }
+    }));
+
+    return kinds;
+}

src/test/suite/index.ts

@@ -12,6 +12,7 @@ export function run(): Promise<void> {
 
     mocha.addFile(path.resolve(__dirname, 'references.test.js'));
     mocha.addFile(path.resolve(__dirname, 'panel.test.js'));
+    mocha.addFile(path.resolve(__dirname, 'kinds.test.js'));
 
     return new Promise((resolve, reject) => {
         try {

src/test/suite/kinds.test.ts

@@ -0,0 +1,152 @@
+import * as assert from 'assert';
+import * as path from 'path';
+import * as vscode from 'vscode';
+
+import { buildRows } from '../../panel';
+import { gather, refKey, referenceKinds, syntacticKind } from '../../references';
+
+const KIND_FILE = path.join('Nerfed.Editor', 'Systems', 'EditorProfilerWindow.cs');
+const KIND_SYMBOL = 'selectedFrame';
+const KIND_DECL = 'private int selectedFrame';
+
+/** `syntacticKind` for the first occurrence of `symbol` in `text`. */
+function classify(text: string, symbol: string): string {
+    const start = text.indexOf(symbol);
+    assert.ok(start >= 0, `'${symbol}' not in '${text}'`);
+    return syntacticKind(text, new vscode.Range(0, start, 0, start + symbol.length));
+}
+
+suite('Read / write classification', () => {
+    test('plain assignment, compound assignment and increments are writes', () => {
+        assert.strictEqual(classify('x = 1;', 'x'), 'write');
+        assert.strictEqual(classify('    x   =   1;', 'x'), 'write');
+        assert.strictEqual(classify('x += 1;', 'x'), 'write');
+        assert.strictEqual(classify('x <<= 2;', 'x'), 'write');
+        assert.strictEqual(classify('x ??= y;', 'x'), 'write');
+        assert.strictEqual(classify('x++;', 'x'), 'write');
+        assert.strictEqual(classify('++x;', 'x'), 'write');
+        assert.strictEqual(classify('--x;', 'x'), 'write');
+    });
+
+    test('by-reference arguments are writes', () => {
+        assert.strictEqual(classify('Foo(ref x);', 'x'), 'write');
+        assert.strictEqual(classify('Foo(out x);', 'x'), 'write');
+        assert.strictEqual(classify('if (Bar(string.Empty, ref x, 0))', 'x'), 'write');
+    });
+
+    test('comparisons and uses are reads', () => {
+        assert.strictEqual(classify('if (x == 1)', 'x'), 'read');
+        assert.strictEqual(classify('if (x != 1)', 'x'), 'read');
+        assert.strictEqual(classify('if (x >= 1)', 'x'), 'read');
+        assert.strictEqual(classify('Foo(x);', 'x'), 'read');
+        assert.strictEqual(classify('return x;', 'x'), 'read');
+        assert.strictEqual(classify('Foo(in x);', 'x'), 'read');
+    });
+
+    test('the right-hand side of an assignment is a read', () => {
+        // `previous = x` must not be classified from the `=` that belongs to `previous`.
+        assert.strictEqual(classify('previous = x;', 'x'), 'read');
+        assert.strictEqual(classify('int y = x + 1;', 'x'), 'read');
+    });
+
+    test('a name that only looks like a prefix is not confused', () => {
+        // `refresh` starts with `ref` but is not a by-reference argument.
+        assert.strictEqual(classify('refresh(x);', 'x'), 'read');
+    });
+});
+
+suite('Read / write kind from the language server', () => {
+    test('kinds for a field that is both read and written', async () => {
+        const ext = vscode.extensions.getExtension('local.colored-references');
+        assert.ok(ext);
+        await ext.activate();
+
+        const folder = vscode.workspace.workspaceFolders?.[0];
+        assert.ok(folder, 'no workspace folder');
+        const uri = vscode.Uri.joinPath(folder.uri, ...KIND_FILE.split(path.sep));
+        const doc = await vscode.workspace.openTextDocument(uri);
+        const editor = await vscode.window.showTextDocument(doc, { preview: false });
+
+        let position: vscode.Position | undefined;
+        for (let i = 0; i < doc.lineCount; i++) {
+            const at = doc.lineAt(i).text.indexOf(KIND_DECL);
+            if (at >= 0) {
+                position = new vscode.Position(i, doc.lineAt(i).text.indexOf(KIND_SYMBOL, at) + 1);
+                break;
+            }
+        }
+        assert.ok(position, `'${KIND_DECL}' not found in ${KIND_FILE}`);
+        editor.selection = new vscode.Selection(position, position);
+
+        const locations = await vscode.commands.executeCommand<vscode.Location[]>(
+            'vscode.executeReferenceProvider', uri, position);
+        assert.ok(locations && locations.length >= 4,
+            `expected several references to ${KIND_SYMBOL}, got ${locations?.length ?? 0}`);
+
+        const results = await gather(KIND_SYMBOL, 'csharp', { uri, position }, locations, true);
+        const kinds = await referenceKinds(results);
+
+        const file = results.files.find(f => f.uri.fsPath === uri.fsPath);
+        assert.ok(file, `${KIND_FILE} missing from the results`);
+
+        const report: string[] = [];
+        const kindAt = (oneBasedLine: number) => {
+            const source = file.lines.find(l => l.line === oneBasedLine - 1);
+            if (!source) {
+                return undefined;
+            }
+            return kinds.get(refKey(file.uri, source.line, source.ranges[0].start.character));
+        };
+        for (const source of file.lines) {
+            report.push(`  ${source.line + 1}: ` +
+                `${kinds.get(refKey(file.uri, source.line, source.ranges[0].start.character))}` +
+                `  ${source.text.trim()}`);
+        }
+        console.log(`[test] ${KIND_SYMBOL} kinds:\n${report.join('\n')}`);
+
+        // 41: `selectedFrame = Profiler.Frames.Count - 1;`
+        assert.strictEqual(kindAt(41), 'write');
+        // 43: `ImGui.SliderInt(string.Empty, ref selectedFrame, 0, ...)`
+        assert.strictEqual(kindAt(43), 'write');
+        // 49: `Profiler.Frames.ElementAt(selectedFrame)`
+        assert.strictEqual(kindAt(49), 'read');
+        // 56: `if (previousSelectedFrame != selectedFrame)`
+        assert.strictEqual(kindAt(56), 'read');
+        // 58: `previousSelectedFrame = selectedFrame;` — a read of selectedFrame
+        assert.strictEqual(kindAt(58), 'read');
+
+        const writes = [...kinds.values()].filter(k => k === 'write').length;
+        const reads = [...kinds.values()].filter(k => k === 'read').length;
+        assert.ok(writes >= 2 && reads >= 3, `expected reads and writes, got ${reads}/${writes}`);
+    });
+
+    test('rows carry the kind, defaulting to read when unknown', async () => {
+        const folder = vscode.workspace.workspaceFolders?.[0];
+        assert.ok(folder);
+        const uri = vscode.Uri.joinPath(folder.uri, ...KIND_FILE.split(path.sep));
+        const doc = await vscode.workspace.openTextDocument(uri);
+
+        let position = new vscode.Position(0, 0);
+        for (let i = 0; i < doc.lineCount; i++) {
+            const at = doc.lineAt(i).text.indexOf(KIND_DECL);
+            if (at >= 0) {
+                position = new vscode.Position(i, doc.lineAt(i).text.indexOf(KIND_SYMBOL, at) + 1);
+                break;
+            }
+        }
+        const locations = await vscode.commands.executeCommand<vscode.Location[]>(
+            'vscode.executeReferenceProvider', uri, position);
+        const results = await gather(KIND_SYMBOL, 'csharp', { uri, position }, locations ?? [], true);
+
+        const kinds = await referenceKinds(results);
+        const { rows } = buildRows(results, new Map(), kinds);
+        assert.ok(rows.length > 0);
+        assert.ok(rows.every(r => r.kind === 'read' || r.kind === 'write'),
+            'every row needs a read/write kind');
+        assert.ok(rows.some(r => r.kind === 'write'), 'no write rows');
+
+        // With no kind map at all, rows still render as reads rather than blank.
+        const { rows: bare } = buildRows(results, new Map());
+        assert.ok(bare.every(r => r.kind === 'read'));
+    });
+});