Go Smart Find Usages

Go Smart Find Usages is a VS Code and Trae extension that organizes Go references by file role and usage kind. It consumes the editor's existing semantic Reference and Definition Providers (normally the official Go extension and gopls) and does not replace Go to Definition, Peek References, Rename, or Command/Control-click.

What it does

• Runs vscode.executeReferenceProvider for the symbol under the cursor.
• Shows references in a dedicated Smart Usages container, grouped by package and file.
• Opens an optional Smart Definition & Usages Peek in the editor area, with definitions, filtered usages, and a read-only source preview side by side.
• Opens an independent Smart Native Peek at the invoking source position by passing all definitions and the currently visible usages to the editor's built-in Peek widget.
• Uses one query and filter state for the Sidebar and enhanced Smart Peek, so preset and checkbox changes stay synchronized; Smart Native Peek snapshots that same state when invoked.
• Classifies files as Production, Unit test, External test, Generated, Dependency, or Unknown.
• Classifies usages as Declaration, Call, Read, Write, Read & write, Type/implementation, or Other.
• Applies filters without deleting the underlying result set. The Results title always shows visible / total, and hidden results are called out explicitly.
• Preserves an in-memory history of the most recent queries and their filter state.
• Marks a result set stale when a relevant open document changes.
• Keeps useful basic results when deep AST analysis is unavailable or fails.

No network request or telemetry is made by the extension.

Requirements

• VS Code API 1.85 or a compatible Trae build. Native Tree View checkboxes require an API implementation compatible with VS Code 1.80 or newer.
• A Go Reference Provider. The usual choice is the official Go extension with a working gopls, but the extension does not hard-depend on a particular provider.
• A compatible Go Definition Provider is recommended for both Peek commands. If definitions are unavailable, either Peek mode can continue with usages.
• Smart Native Peek also requires a host editor compatible with the public editor.action.peekLocations command. A command failure leaves the Sidebar and enhanced Smart Peek available.
• A local filesystem workspace. Virtual/web workspaces are not supported in the initial release.
• A trusted workspace for deep classification. Basic semantic results remain available in an untrusted workspace.

See the compatibility matrix for the current validation status.

Installation

VS Code Marketplace

After the first public release, open Extensions (Ctrl/Cmd+Shift+X), search for Go Smart Find Usages, verify that the publisher is kizuna-lek, and choose Install.

Install a VSIX

Build the current-platform VSIX:

npm ci
npm run check
npm run package:vsix

Then run Extensions: Install from VSIX... in VS Code or Trae and select the platform-tagged file in release/, for example go-smart-find-usages-0.1.0-darwin-arm64.vsix.

The package contains exactly one target analyzer. By default that target is the current host; set VSIX_TARGET to one of the six targets in COMPATIBILITY.md to cross-build, for example VSIX_TARGET=linux-arm64 npm run package:vsix.

Quick start

For the shortest path:

1. Confirm that native Find All References works in the current Go file.
2. Place the cursor on a Go identifier and press Alt/Option+F7.
3. Start with Mainline to hide tests and generated code, then switch presets or individual checkboxes as needed.
4. Select a result to preview it; use Open Usage to pin it, or press F4 / Shift+F4 to move through visible results.

Use the Smart Usages Sidebar

1. Open a Go file and place the cursor on a function, method, type, field, variable, or parameter.
2. Run Go Smart Usages: Find Usages from the Command Palette, choose Smart Find Usages from the editor context menu, or press Alt+F7 (Option+F7 on macOS; some keyboards also require Fn).
3. Use the Filters view to change the visible file roles or usage kinds.
4. Select a location to preview it. Use Open Usage to pin the editor, or Open Usage to the Side from the location context menu.
5. Use F4 and Shift+F4, or the Results toolbar arrows, to move through visible usages only. Navigation wraps at the first and last result.

The stable custom Tree View API does not expose a portable double-click event. VS Code normally pins a repeatedly opened preview, while Open Usage is the explicit, cross-editor way to guarantee a pinned tab.

Use Smart Definition & Usages Peek

Place the cursor on a Go symbol and run Go Smart Usages: Peek Definition and Usages from the Command Palette, or choose Smart Definition & Usages Peek from the editor context menu. The extension intentionally contributes no default shortcut for this command and never writes keybindings.json; bind goSmartUsages.peek from Preferences: Open Keyboard Shortcuts if desired.

Definitions remain pinned at the top of the location list and are not affected by usage filters. The Usages section applies the same presets, file roles, usage kinds, excludes, and visible / total / hidden counts as the Sidebar. Changing a preset or individual filter in either UI immediately updates the other.

Selecting a definition or usage updates only the read-only source preview. Press Enter or choose Open to pin the selected source in a real editor, choose Open to Side for the adjacent editor group, and press Esc to close Smart Peek. Next/Previous traverses only currently visible usages; definitions are not part of that sequence. Closing without opening a location returns focus to the invoking editor and cursor, while an explicit Open keeps the new editor focus.

Smart Peek uses the stable Editor Area Webview Panel API. It does not modify the native Peek References UI, inject Workbench DOM, register a competing provider, or take over Go to Definition.

Use Smart Native Peek

Place the cursor on a Go symbol and run Go Smart Usages: Smart Native Peek from the Command Palette, or choose Smart Native Peek from the editor context menu. The extension contributes no default shortcut and never writes keybindings.json; bind goSmartUsages.nativePeek from Preferences: Open Keyboard Shortcuts if desired.

Smart Native Peek and enhanced Smart Peek remain independent, simultaneously available commands. There is no mutually exclusive setting, and using one mode never disables or replaces the other.

The command opens the host editor's line-anchored Peek widget at the invoking editor and cursor. Its one-time location snapshot contains every normalized Definition Provider result plus only the usages visible under the query's frozen preset, file-role filters, usage-kind filters, and excludes. Definitions are not filtered, and a definition and usage with the same URI and full range are passed to the host only once.

If there is no reusable query for the symbol under the cursor, Smart Native Peek runs the same Definition and Reference Provider query used by enhanced Smart Peek and updates the Sidebar. At command invocation it clones any shared Sidebar Filter State and uses it for the new query and snapshot even when the target changes; only an idle state with no shared filters falls back to goSmartUsages.defaultPreset. It waits until both provider branches have succeeded, become unavailable, or failed before opening one complete snapshot. If Smart Native Peek is invoked again for the same in-flight query, the newer invocation cancels the older invocation's wait listener and reuses that query. A cancelled or superseded invocation cannot open over a newer result.

Changing Sidebar filters after the native widget opens does not rewrite it. Run Smart Native Peek again to replace it with a snapshot made from the latest filter state. Grouping, sorting, source preview, selection, opening, closing, focus, keyboard behavior, accessibility, and theme rendering belong to the host widget; classifications, counts, and filter controls remain in the Sidebar and enhanced Smart Peek.

Definitions being unavailable does not block visible usages, and an all-hidden usage set does not block definitions. If both sides are empty, the extension reports that there is no displayable location and does not open an empty widget. Because the stable public command set does not provide a portable way for the extension to close an existing native Peek, an older widget remains open with its earlier snapshot until the user closes it; the no-result message makes this explicit. If the host command is unavailable or fails, existing Sidebar results remain intact and the extension suggests enhanced Smart Peek as the fallback.

Presets

Within a dimension, enabled entries are ORed; file-role and usage-kind dimensions are ANDed.

A generated test keeps both Generated and Unit/External test tags, with Generated shown as its primary role. Because enabled entries are positive OR selections inside the file-role dimension, that result is visible when either matching role is enabled. Mainline still hides it because Production is its only enabled file role.

excludePatterns never removes Reference Provider data. Excluded records remain part of total and are reported as hidden.

File and usage classification

The extension performs classification in two stages:

1. TypeScript reads each unique result file once, preferring the in-memory text of an open document. It classifies file roles, captures a single-line preview, and publishes results immediately.
2. A bundled, long-lived Go analyzer parses the frozen in-memory content and classifies each referenced identifier with go/ast and best-effort go/types information. Results that cannot be classified safely remain Other.

The sidecar uses UTF-8 NDJSON over stdin/stdout, receives source overlays only for files returned by the Reference Provider, and does not write them to disk. Its binary is verified against the packaged SHA-256 manifest before launch.

Settings

Pattern and analysis settings apply to the next query. Preview settings apply when Tree items are refreshed. The extension never writes workspace settings automatically.

Cancellation, refresh, and history

The public navigation-provider commands do not accept a cancellation token. Cancel immediately stops this extension's classification and prevents late Reference or Definition Provider results from changing state, but it cannot force gopls to stop work already submitted to it. The Go analyzer itself supports cancellation and a timeout. Provider branches publish independently to the Sidebar and enhanced Smart Peek: a slow or failed Definition Provider does not delay classified usages, and definitions can appear while references are still pending. Smart Native Peek deliberately waits for both provider branches to reach a terminal state before taking its one-time snapshot; it does not wait for optional deep analysis.

Starting a new query invalidates the previous query generation, so stale asynchronous results cannot overwrite the new query. Refresh replaces the current history entry instead of adding a duplicate. History is not persisted across editor restarts in the initial release.

Troubleshooting

“No Go reference provider is available”

Open a Go file, verify that a compatible Go extension is enabled, and check that gopls has started successfully. Native Find All References should work before Smart Usages can consume it.

The public provider command can return an empty array both when there are genuinely no references and with some unavailable providers. If the empty state is unexpected, use native Find All References to distinguish those cases.

Results only say Other

Open Go Smart Usages: Open Logs. Deep analysis is intentionally disabled in untrusted workspaces and in analysisMode: basic. A missing, unsupported, timed-out, or checksum-invalid analyzer also degrades to basic results without losing references.

Smart Peek says definitions are unavailable

Smart Peek can continue with usages when no Definition Provider is available, a provider returns no definitions, or the definition request fails. Verify that native Go to Definition works for the symbol, then refresh or run Smart Peek again. Use Go Smart Usages: Open Logs for a provider error summary.

Smart Native Peek does not open

If neither definitions nor currently visible usages exist, Smart Native Peek intentionally shows a no-result message instead of opening an empty widget. If an older native Peek is already open, it remains the earlier snapshot until you close it; the extension does not use an undocumented close command. Check the Sidebar for hidden usages, adjust its preset or filters, and run the command again. If the host does not support editor.action.peekLocations or the command fails, use Go Smart Usages: Peek Definition and Usages and inspect Go Smart Usages: Open Logs. The Sidebar result set is preserved.

Alt/Option+F7 conflicts

VS Code's public extension API cannot reliably enumerate keybinding conflicts. The supplied binding is limited to focused Go editors and never writes keybindings.json. Change it in Preferences: Open Keyboard Shortcuts if another extension wins the keybinding.

Everything is hidden

The Results view reports the original total and offers Show all semantic usages. Exclude patterns can still keep matching locations hidden; adjust goSmartUsages.excludePatterns if needed.

Known limitations

• Results are limited to what the active Reference Provider and its current Go build context return. Mutually exclusive build tags, GOOS/GOARCH files, reflection, unsafe, string registration, templates, and runtime-generated calls may not be found.
• Ordinary comments, Go doc links, and strings are not scanned in the initial release. They are never presented as semantic references.
• Interface implementation relationships are preserved when the Reference Provider returns them, but the initial release does not add new locations through an Implementation Provider.
• Deep type information is best effort for partial packages. Ambiguous or broken code falls back conservatively.
• Stable extension APIs do not allow extensions to inject or customize content inside the native line-anchored Peek widget. Enhanced Smart Peek therefore uses an Editor Area Webview Panel for definitions/usages sections, counts, filters, and custom preview controls. Smart Native Peek can invoke the public editor.action.peekLocations command with a location snapshot, but its native UI and behavior remain host-owned.
• Remote SSH, WSL, Dev Containers, persistent history, pinned queries, custom presets, and web/virtual workspaces are outside the validated initial-release support matrix.
• A concrete Trae Stable build has not yet been selected. It must pass the checklist in COMPATIBILITY.md before production compatibility is claimed.

More detail is available in KNOWN_LIMITATIONS.md, PRIVACY.md, and SUPPORT.md.

Develop

Prerequisites: Node.js 22+, npm, and Go 1.22+.

npm ci
npm run compile
npm test
npm run build
npm run package:vsix

npm test runs pure TypeScript tests (including a 10,000-result filter case) and Go analyzer tests. npm run test:integration launches the VS Code Extension Test Runner and uses deterministic test Reference and Definition Providers; it may download the VS Code test build on first use.

The architecture and acceptance mapping live in docs/ARCHITECTURE.md and docs/ACCEPTANCE.md. See CONTRIBUTING.md before submitting a change.