The IDE you know, rebuilt in Rust. IntelliJ IDEA–style keymap, tool windows and search-everywhere in a fast native app: editor, code insight, debugger, Git, terminal, database and HTTP clients for 60+ languages.
TypeScript code-editorcross-platformdapdatabase-clientdebuggerdesktop-appdeveloper-toolsgithttp-clientideintellijlsprusttauriterminal
/** Find Usages (⌥F7 → "usages" tool window) and Show Usages (⌥⌘F7 → popup). */
import { create } from "zustand";
import { Channel } from "@tauri-apps/api/core";
import type { ClassifiedReference, ReferenceAccess, ReferenceKind, Location, References, RequestId } from "@/bindings";
import { clearLineTokens } from "@/editor/lineTokens";
import { incompleteNote } from "@/editor/lsp/lsp";
import { commands, IpcError, isCancelled, nextRequestId } from "@/platform/ipc";
import { shortcutLabel } from "@/platform/keymap";
import { synchronizeDocumentIndexes, toolWindowService } from "@/workbench/contributions";
import {
caretContext,
caretPoint,
hint,
lspRequest,
openLocation,
readManyFileLines,
reportError,
type CaretContext,
} from "./ipc";
import { syntaxUsages } from "./syntaxUsages";
export interface Usage {
kind?: ReferenceKind;
access?: ReferenceAccess | null;
/** Exact semantic range, retained when the line preview is clamped. */
sourceLocation?: Location;
path: string;
line: number;
col: number;
/** End column on `line` (clamped to the line for multi-line ranges). */
endCol: number;
/** The usage's line text (empty when the file couldn't be read). */
text: string;
}
export interface UsageGroup {
path: string;
usages: Usage[];
}
/** Groups reference locations by file (sorted by path, then position), attaching line previews. */
export function groupUsages(
locs: readonly Location[],
files: ReadonlyMap<string, readonly string[] | null>,
classified: readonly ClassifiedReference[] = [],
): UsageGroup[] {
const kinds = new Map(classified.map((r) => [usageLocationKey(r.location), r]));
const byPath = new Map<string, Usage[]>();
const seen = new Set<string>();
for (const l of locs) {
const key = usageLocationKey(l);
if (seen.has(key)) continue;
seen.add(key);
const text = files.get(l.path)?.[l.range.start.line] ?? kinds.get(key)?.text ?? "";
const endCol = l.range.end.line === l.range.start.line ? l.range.end.col : Math.max(text.length, l.range.start.col);
let list = byPath.get(l.path);
if (!list) byPath.set(l.path, (list = []));
list.push({
...(kinds.has(usageLocationKey(l))
? {
kind: kinds.get(usageLocationKey(l))!.kind,
access: kinds.get(usageLocationKey(l))!.access,
sourceLocation: l,
}
: {}),
path: l.path,
line: l.range.start.line,
col: l.range.start.col,
endCol,
text,
});
}
return [...byPath.entries()]
.sort(([a], [b]) => a.localeCompare(b))
.map(([path, usages]) => ({ path, usages: usages.sort((a, b) => a.line - b.line || a.col - b.col) }));
}
export function usageCount(groups: readonly UsageGroup[]): number {
return groups.reduce((n, g) => n + g.usages.length, 0);
}
/** Trims leading whitespace of a preview line, shifting the match range accordingly. */
export function trimPreview(u: Usage): { text: string; textCol: number; from: number; to: number } {
const lead = u.text.length - u.text.trimStart().length;
const text = u.text.trim();
const from = Math.max(0, u.col - lead);
const to = Math.max(from, Math.min(text.length, u.endCol - lead));
return { text, textCol: lead, from, to };
}
/** Project Files, or Project and Libraries (Java's dependency jars and JDK too). */
export type UsageScope = "project" | "libraries";
/** The scope a search ran in, when there was a choice (`null` when the server has none). */
function searchedScope(libraries: boolean, librariesSkipped: boolean, widenable: boolean): UsageScope | null {
if (librariesSkipped) return "project";
return libraries && widenable ? "libraries" : null;
}
export interface UsageSearch {
/** Identifies one search run (UI state such as expansion resets per run). */
id: number;
symbol: string | null;
loading: boolean;
groups: UsageGroup[];
error: string | null;
/** Results came from the syntax fallback: says so (e.g. "Text occurrences (language server not ready)"). */
note: string | null;
/** Re-runs the same query (rerun button). */
rerun: (() => void) | null;
/** Where it searched, when the server can search beyond Project Files (Java's jars and JDK). */
scope?: UsageScope | null;
/** Runs it again in Project and Libraries. */
searchLibraries?: (() => void) | null;
/** Kept when a new search runs (Pin Tab). */
pinned?: boolean;
}
let searchSeq = 0;
/** One tab per search; as in IDEA a new search replaces the selected tab unless it is pinned. */
interface UsagesState {
tabs: UsageSearch[];
active: number | null;
}
export const useUsages = create<UsagesState>(() => ({ tabs: [], active: null }));
/** The selected tab's search. */
export const activeUsageSearch = (s: UsagesState): UsageSearch | null =>
s.tabs.find((t) => t.id === s.active) ?? s.tabs.at(-1) ?? null;
const MAX_TABS = 8;
/** Shows `search` in a new tab, or in place of the selected one unless that is pinned. */
export function openUsageTab(search: UsageSearch) {
useUsages.setState((s) => {
const reused = s.tabs.find((t) => t.id === s.active && !t.pinned);
const tabs = reused ? s.tabs.map((t) => (t === reused ? search : t)) : [...s.tabs, search];
return { tabs: tabs.slice(-MAX_TABS), active: search.id };
});
}
/** Replaces tab `id` (a rerun or a finished search), keeping its pin and selection. */
function replaceUsageTab(id: number, search: UsageSearch): boolean {
const s = useUsages.getState();
const old = s.tabs.find((t) => t.id === id);
if (!old) return false;
useUsages.setState({
tabs: s.tabs.map((t) => (t === old ? { ...search, pinned: old.pinned } : t)),
active: s.active === id ? search.id : s.active,
});
return true;
}
export function pinUsageTab(id: number, pinned: boolean) {
useUsages.setState((s) => ({ tabs: s.tabs.map((t) => (t.id === id ? { ...t, pinned } : t)) }));
}
export function closeUsageTab(id: number) {
cancelSearch(id);
useUsages.setState((s) => {
const i = s.tabs.findIndex((t) => t.id === id);
const tabs = s.tabs.filter((t) => t.id !== id);
const active = s.active === id ? (tabs[Math.min(i, tabs.length - 1)]?.id ?? null) : s.active;
return { tabs, active };
});
}
/** Rerun of the selected tab (⌘R in the Find Usages tool window). */
export function rerunActiveUsages() {
activeUsageSearch(useUsages.getState())?.rerun?.();
}
interface UsagesPopupState {
open: boolean;
anchor: { x: number; y: number };
symbol: string | null;
groups: UsageGroup[];
note: string | null;
/** Shows those found so far while the search goes on. */
loading: boolean;
/** Where it searched, when the server can search beyond Project Files. */
scope: UsageScope | null;
}
export const useUsagesPopup = create<UsagesPopupState>(() => ({
open: false,
anchor: { x: 0, y: 0 },
symbol: null,
groups: [],
note: null,
loading: false,
scope: null,
}));
interface FetchedUsages {
groups: UsageGroup[];
note: string | null;
librariesSkipped: boolean;
}
/** Paths whose lines are read to show these usages: not those the server gave along. */
function pathsToRead(locs: readonly Location[], classified: readonly ClassifiedReference[]): string[] {
const given = new Set(classified.filter((r) => r.text != null).map((r) => usageLocationKey(r.location)));
return locs.filter((l) => !given.has(usageLocationKey(l))).map((l) => l.path);
}
/**
* The server's references across the project (files outside its analysis scope
* included); when it is not ready or fails, the syntax fallback (an empty server
* answer is respected). Without a fallback the server error stands. Without
* `libraries`, Java's dependencies and JDK are not searched (Project Files); with it,
* those found in the sources go to `onPartial` before the slower search for the rest.
* Cancel with `commands.cancelRequest(request)`.
*/
export async function fetchUsages(
c: CaretContext,
request: RequestId = nextRequestId(),
onPartial?: (found: FetchedUsages) => void,
libraries = false,
): Promise<FetchedUsages> {
// Usage lines are read afresh: so are the files their syntax colours come from.
clearLineTokens();
const before = c.view?.state.doc;
let locs: Location[];
let classified: ClassifiedReference[] = [];
let note: string | null = null;
let librariesSkipped = false;
await synchronizeDocumentIndexes(c.path);
if (c.view && c.view.state.doc !== before) throw new IpcError({ kind: "cancelled", message: "", data: null });
let settled = false;
const channel = new Channel<References>();
channel.onmessage = (refs) => {
if (!onPartial) return;
void readManyFileLines(pathsToRead(refs.locations, refs.classified ?? [])).then((files) => {
if (settled) return;
onPartial({
groups: groupUsages(refs.locations, files, refs.classified ?? []),
note: refs.incomplete ? incompleteNote(refs.incomplete, c.word) : null,
librariesSkipped: false,
});
});
};
try {
const refs = await lspRequest(() =>
commands.lspReferences(request, c.doc, { line: c.line, col: c.col }, false, true, libraries, channel),
).finally(() => {
settled = true;
});
locs = refs.locations;
classified = refs.classified ?? [];
librariesSkipped = refs.librariesSkipped ?? false;
if (refs.incomplete) note = incompleteNote(refs.incomplete, c.word);
} catch (e) {
if (isCancelled(e)) throw e;
let fb = null;
try {
fb = await syntaxUsages(c);
} catch (fe) {
if (isCancelled(fe)) throw fe;
console.debug("[syntax] usages fallback", fe);
}
if (!fb) throw e;
locs = fb.locs;
note = fb.note;
}
const files = await readManyFileLines(pathsToRead(locs, classified));
return { groups: groupUsages(locs, files, classified), note, librariesSkipped };
}
/** In-flight server requests: of tool window searches by search id, and of the popup. */
const inflight = new Map<number, RequestId>();
let popupRequest: RequestId | null = null;
function cancelSearch(id: number) {
const request = inflight.get(id);
if (request === undefined) return;
inflight.delete(id);
void commands.cancelRequest(request).catch(() => {});
}
/** The window switched projects: results (and in-flight searches) of the previous one are dropped. */
export function resetUsages() {
for (const id of [...inflight.keys()]) cancelSearch(id);
if (popupRequest !== null) void commands.cancelRequest(popupRequest).catch(() => {});
popupRequest = null;
useUsages.setState({ tabs: [], active: null });
useUsagesPopup.setState({ open: false, symbol: null, groups: [], note: null, loading: false, scope: null });
popupTarget = null;
}
export async function findUsages() {
const c = caretContext();
if (!c) {
hint("Open a file to find usages");
return;
}
// `widenable`: an earlier run of this search skipped the libraries.
const run = async (prev: number | null, libraries: boolean, widenable: boolean) => {
const id = ++searchSeq;
const base = {
id,
symbol: c.word,
rerun: () => void run(id, libraries, widenable),
searchLibraries: () => void run(id, true, true),
};
const loading = { ...base, loading: true, groups: [], error: null, note: null };
if (prev !== null) cancelSearch(prev);
if (prev === null || !replaceUsageTab(prev, loading)) openUsageTab(loading);
toolWindowService().show("usages");
const request = nextRequestId();
inflight.set(id, request);
try {
const { groups, note, librariesSkipped } = await fetchUsages(
c,
request,
(found) => {
if (inflight.get(id) === request) replaceUsageTab(id, { ...loading, groups: found.groups, note: found.note });
},
libraries,
);
const scope = searchedScope(libraries, librariesSkipped, widenable);
replaceUsageTab(id, { ...base, loading: false, groups, error: null, note, scope });
} catch (e) {
// Cancelled here (closed tab, rerun): a newer state already replaced it.
if (isCancelled(e) && !inflight.has(id)) return;
const message = e instanceof Error ? e.message : String(e);
if (!replaceUsageTab(id, { ...base, loading: false, groups: [], error: message, note: null })) return;
reportError(e);
} finally {
if (inflight.get(id) === request) inflight.delete(id);
}
};
await run(null, false, false);
}
/**
* Shows already-found usages in the tool window (Safe Delete's "View Usages").
* Ignores malformed arguments.
*/
export async function showUsageResults(arg: unknown) {
const a = (arg ?? {}) as {
symbol?: unknown;
locations?: unknown;
classified?: ClassifiedReference[];
note?: unknown;
};
if (!Array.isArray(a.locations)) return;
const locs = a.locations as Location[];
const symbol = typeof a.symbol === "string" ? a.symbol : null;
const id = ++searchSeq;
const base = { id, symbol, rerun: null };
openUsageTab({ ...base, loading: true, groups: [], error: null, note: null });
toolWindowService().show("usages");
clearLineTokens();
const files = await readManyFileLines(locs.map((l) => l.path));
replaceUsageTab(id, {
...base,
loading: false,
groups: groupUsages(locs, files, a.classified),
error: null,
note: typeof a.note === "string" ? a.note : null,
});
}
export function dismissUsagesPopup() {
if (popupRequest !== null) void commands.cancelRequest(popupRequest).catch(() => {});
popupRequest = null;
useUsagesPopup.setState({ open: false });
}
/** How long Show Usages waits for all usages before it shows those found first. */
const EARLY_POPUP_DELAY_MS = 300;
/** How long the hint after Show Usages stays (and invoking it again widens its search). */
const HINT_MS = 4000;
/**
* What the popup, or the hint after it, shows usages of: invoked again meanwhile, Show
* Usages searches it in Project and Libraries, wherever the caret is now.
*/
let popupTarget: { c: CaretContext; widenable: boolean; hintUntil: number } | null = null;
export async function showUsagesPopup() {
const target = popupTarget;
const popup = useUsagesPopup.getState();
if (target?.widenable && ((popup.open && popup.scope === "project") || Date.now() < target.hintUntil)) {
await searchPopup(target.c, true, true);
return;
}
const c = caretContext();
if (!c) {
hint("Open a file to show usages");
return;
}
await searchPopup(c, false, false);
}
/** The popup's scope chooser: searches its symbol again in `scope`. */
export function setUsagesPopupScope(scope: UsageScope) {
const target = popupTarget;
if (!target || scope === useUsagesPopup.getState().scope) return;
void searchPopup(target.c, scope === "libraries", target.widenable);
}
async function searchPopup(c: CaretContext, libraries: boolean, widenable: boolean) {
// Set from the start: the scope chooser can switch while this search goes on.
popupTarget = { c, widenable, hintUntil: 0 };
const reopened = useUsagesPopup.getState().open;
if (reopened) useUsagesPopup.setState({ loading: true, scope: libraries ? "libraries" : "project" });
if (popupRequest !== null) void commands.cancelRequest(popupRequest).catch(() => {});
const request = nextRequestId();
popupRequest = request;
// Opened with those found first when the rest take a while; it then stays open, even
// when they were all. A quick search still jumps to a single usage.
let early = false;
let found: FetchedUsages | null = null;
let timer: ReturnType<typeof setTimeout> | undefined;
const openEarly = () => {
if (popupRequest !== request || !found) return;
if (!early && !reopened) useUsagesPopup.setState({ open: true, anchor: caretPoint(), symbol: c.word });
early = true;
useUsagesPopup.setState({ ...found, loading: true, scope: widenable ? "libraries" : null });
};
const again = shortcutLabel("find.showUsages");
try {
const { groups, note, librariesSkipped } = await fetchUsages(
c,
request,
(partial) => {
if (!usageCount(partial.groups)) return;
found = partial;
if (early) openEarly();
else timer ??= setTimeout(openEarly, EARLY_POPUP_DELAY_MS);
},
libraries,
).finally(() => clearTimeout(timer));
if (popupRequest !== request) return;
const scope = searchedScope(libraries, librariesSkipped, widenable);
popupTarget = { c, widenable: widenable || scope !== null, hintUntil: 0 };
const total = usageCount(groups);
if (early || reopened || total > 1) {
if (!early && !reopened) useUsagesPopup.setState({ open: true, anchor: caretPoint(), symbol: c.word });
useUsagesPopup.setState({ groups, note, loading: false, scope });
return;
}
// As in IDEA, the hint offers to widen the search, which Show Usages does while it shows.
const widen = scope === "project" && again !== "";
if (widen) popupTarget.hintUntil = Date.now() + HINT_MS;
if (!total) {
if (widen) hint(`No usages found in Project Files. Press ${again} again to search in 'Project and Libraries'`);
else if (scope === "project") hint("No usages found in Project Files");
else {
const none = c.word ? `No usages of '${c.word}' found` : "No usages found";
hint(note ? `${none}. ${note}` : none);
}
return;
}
// IDEA jumps to the only usage and says so in the target editor.
const u = groups[0]!.usages[0]!;
await openLocation(u.path, u.line, u.col);
if (widen) hint(`Only one usage in Project Files. Press ${again} again to search in 'Project and Libraries'`);
else if (scope === "libraries") hint("Only one usage in Project and Libraries");
else hint("Only one usage in Project Files");
} catch (e) {
if (popupRequest !== request || isCancelled(e)) return;
if (early || reopened) useUsagesPopup.setState({ loading: false });
reportError(e);
} finally {
if (popupRequest === request) popupRequest = null;
}
}
function usageLocationKey(l: Location): string {
return JSON.stringify([l.path, l.range.start.line, l.range.start.col, l.range.end.line, l.range.end.col]);
}