teamai-test/.teamai/skills/common/golang-gopls/references/features.md

gopls feature catalog

Source: tip.golang.org/gopls/features. Each entry names the LSP request or CodeAction kind so a specific behavior can be looked up in the upstream docs by exact term.

Table of contents

• Navigation
• Passive (always-on)
• Diagnostics
• Transformation
• Web-based features
• Non-Go files
• Completion

Navigation

Definition (textDocument/definition, CLI gopls definition) — jumps to a symbol's declaration. Handles more than plain identifiers: on an import path it lists the imported package's declarations; on a go:linkname directive it finds the linked symbol; on a go:embed pattern it finds the embedded file; on a doc-comment link it follows the reference; on a non-Go function it can return the assembly implementation; on return it locates the named result variables; on goto/break/continue it finds the target label or block. Already at the declaration → most clients reinterpret the request as "find references" instead.

Type Definition (textDocument/typeDefinition, no CLI equivalent) — jumps to the named type underlying a symbol, unwrapping pointer, array, slice, channel, and map constructors first. For x chan []*T, this reports the definition of T. Only works on symbols, not arbitrary expressions. No agent-invocable path: it is absent from the native LSP tool's fixed operation list (goToDefinition, findReferences, hover, documentSymbol, workspaceSymbol, goToImplementation, call hierarchy), so only a full editor LSP client can reach it.

References (textDocument/references, CLI gopls references) — lists every use of a symbol. For an interface method, this includes concrete implementations; for a package declaration, it includes both direct imports and other files' package clauses; for an embedded field, it reports only field references (use Type Definition to find references to the type itself). Scoping gotcha: results reflect only the build configuration of the queried file — a query issued against foo_windows.go will not surface a match in bar_linux.go. Built-in symbols (int, append) are rejected as too numerous to be useful.

Implementation (textDocument/implementation, CLI gopls implementation) — on an interface, returns concrete implementations and sub-interfaces; on a concrete type, returns interfaces it satisfies; on an interface method, returns the concrete methods satisfying it, and vice versa. Matching uses method sets for types and signatures for functions. Generic types are treated as wildcards: a candidate is included if any instantiation would allow one to implement the other, without full unification checking. LSP's built-in bias toward subtypes makes this query directionally asymmetric — for full bidirectional traversal, use Type Hierarchy instead.

Document Symbol (textDocument/documentSymbol, CLI gopls symbols) — outline of a single file's top-level declarations. File-scoped; use Symbol for cross-file search.

Symbol / Workspace Symbol (workspace/symbol, CLI gopls workspace_symbol) — fuzzy search across the whole workspace. Default matcher is fastFuzzy (FZF-inspired), so abbreviations and typos still match — DocSym matches DocumentSymbol. Controlled by the symbolMatcher, symbolStyle, and symbolScope settings (see settings.md); directoryFilters excludes directories from the search.

Selection Range (textDocument/selectionRange, no CLI equivalent) — expands or contracts the current selection along syntactic boundaries (expression → statement → block → function). Useful for selecting exactly the region an Extract refactor needs.

Call Hierarchy (textDocument/prepareCallHierarchy + callHierarchyItem/incomingCalls/outgoingCalls, CLI gopls call_hierarchy) — shows a function's callers and callees as a static graph. Only static calls are included — calls made through a function value or an interface method are invisible, since detecting them isn't analytically tractable. Corroborate with References when a dynamically-dispatched call site matters. Invoke on the function declaration's name.

Type Hierarchy (textDocument/prepareTypeHierarchy + typeHierarchyItem/subtypes/typeHierarchy/supertypes, no CLI equivalent yet) — bidirectional view of the subtyping relation: which types implement an interface, and which interfaces a type satisfies. Resolves the asymmetry Implementation has. Limited to named types (unlike Implementation, which also matches unnamed function types); alias types are excluded; function-local types are visible only within the same package.

Passive (always-on)

These need no explicit invocation — they fire continuously as an editor session progresses. Most degrade if the surrounding package has build errors, since they depend on successful type-checking.

Hover (textDocument/hover) — symbol name/kind/type/value, doc comment (with clickable doc links like [fmt.Printf]), promoted methods from embedded fields, struct field size/offset and wasted-space percentage (flagged at ≥20% waste), expanded //go:embed patterns, //go:linkname targets, and which Go release introduced a given stdlib symbol. Controlled by hoverKind (verbosity) and linkTarget (base URI for doc links).

Signature Help (textDocument/signatureHelp) — parameter names/types/docs for the function being called, with the active parameter highlighted; works even while the cursor sits inside the function name, not just inside the parens.

Document Highlight (textDocument/documentHighlight) — highlights every identifier referring to the same symbol in view, plus related tokens: named results and their return statements, loop control keywords (for/break/continue), switch tokens, a function and its own return statements. Read vs. write references are typically color-coded differently by the client.

Inlay Hint (textDocument/inlayHint) — inline annotations, off by default (visual clutter), toggled per-kind via the hints setting: parameterNames (call-site argument labels), assignVariableTypes, compositeLiteralFields, compositeLiteralTypes, constantValues (including computed iota values), functionTypeParameters (generic instantiations), rangeVariableTypes.

Semantic Tokens (textDocument/semanticTokens) — richer syntax coloring than naive lexing: token types (function, keyword, macro, method, namespace, number, operator, parameter, string, type, typeParameter, variable, …) plus modifiers including a custom shadowing modifier that flags shadowed declarations. Off by default due to type-checking latency (semanticTokens setting); noSemanticString/noSemanticNumber let a client opt out of just those two kinds if it prefers its own lexical highlighting for them.

Folding Range (textDocument/foldingRange) — collapsible regions for large comments, functions, and blocks.

Document Link (textDocument/documentLink) — turns URLs in doc comments and import declarations into clickable links (imports link to their pkg.go.dev page). Controlled by importShortcut and linkTarget.

Diagnostics

Three sources, distinguished by the LSP diagnostic's source field:

1. Compilation errors — gopls doesn't invoke the real compiler; it runs go list for package metadata (source: "go list") then mimics the compiler front-end itself: read, scan, parse, type-check (source: "compiler").
2. Analysis findings — the go vet analysis framework plus gopls's own analyzers, each reporting under its own analyzer name as source. The printf analyzer (format-string/argument mismatches) is a representative example.
3. Compiler optimization details — off by default; toggled per-package with the source.toggleCompilerOptDetails code action. Surfaces escape-analysis results, nil-check elimination, and inlining decisions. Only available on packages that are otherwise error-free.

Recomputation timing: open-file compile errors update within tens of milliseconds of a keystroke. Workspace-wide analysis diagnostics recompute after roughly a second of idle time, tunable via diagnosticsDelay; diagnosticsTrigger can switch this to save-triggered instead of edit-triggered. Clients can also request diagnostics explicitly (textDocument/diagnostic, "pull diagnostics") if initialized with pullDiagnostics: true — off by default for performance.

Notable quick fixes, offered as code actions attached to a diagnostic:

• fillreturns — heuristically completes an incomplete return statement.
• stubMissingInterfaceMethods — generates stub methods when a concrete type doesn't yet satisfy a required interface.
• StubMissingCalledFunction — creates a stub for an undefined function/method, inferring its signature from the call site.
• CreateUndeclared — declares a missing variable or function based on how it's used.
• Fixes marked source.fixAll are considered unconditionally safe; most editors offer a single shortcut to apply all of them at once.

CLI: gopls check <file> (-severity=hint|info|warning|error, default warning).

Transformation

Three underlying mechanisms: Formatting and Rename are primary LSP requests; most everything else is a CodeAction (requested per-range, returns either a direct edit or a lazily-computed command); a handful of dependency-management actions are CodeLenses instead.

Formatting (textDocument/formatting, CLI gopls format) — canonical Go formatting; client-supplied formatting options are ignored. gofumpt: true switches to mvdan.cc/gofumpt's stricter rules.

Organize Imports (source.organizeImports, CLI gopls imports) — removes unused/duplicate imports, adds missing ones (via workspace-wide heuristics — occasionally surprising), sorts them. The local setting groups a path prefix as "local," matching goimports -local. Most editors run this on save; disable per-language if that's unwanted.

Rename (textDocument/rename, CLI gopls rename) — two-stage: prepareRename reports the current name, then rename applies the change everywhere. Refuses renames that would introduce shadowing or break interface satisfaction. Special positions unlock extra behavior:

• Rename a method's receiver declaration → renames the receiver identifier across every method of that type; rename a receiver use → renames only that one variable.
• Rename the package name in a package clause → moves every file in the package to a new directory (subpackages stay put unless renameMovesSubpackages is set); refused across module boundaries or into an existing package.
• Rename the func keyword of a declaration → lets you edit the whole signature; parameter/result count and types must stay the same (no adding/removing parameters this way — see refactor.rewrite.removeUnusedParam/moveParamLeft/moveParamRight for that).

Extract (refactor.extract.*) — replaces a selection with a reference to a new declaration:

• refactor.extract.variable / .constant — one new local binding for the selected expression, plus -all variants that rewrite every occurrence within the enclosing function.
• refactor.extract.function / .method — turns one or more complete statements into a call to a new function (or method, on the same receiver, if extracted inside a method).
• refactor.extract.toNewFile (gopls ≥ v0.17.0) — moves selected top-level declarations into a new file, adding imports as needed; the new filename derives from the first declared symbol.

Extract is less rigorous than Rename/Inline: comments are sometimes dropped, and files carrying a DO NOT EDIT generated-code marker receive no code actions at all.

Inline (refactor.inline.*):

• refactor.inline.call — replaces a call with the function body, substituting parameters for arguments. Works only for static calls to accessible functions/methods (not through a function value or interface method, not to unexported names outside the package, not into internal packages, not for generic functions). Preserves side-effect ordering (introduces vars when an argument must not be duplicated or reordered), keeps qualified references correct (Printf → fmt.Printf with the import added), keeps implicit conversions explicit, and never drops a variable's last use. defer bodies stay wrapped in a closure since defer semantics are tied to function boundaries.
• refactor.inline.variable — replaces a local variable's use with its initializer expression; refuses if an identifier in that initializer has been shadowed since the declaration.

Miscellaneous rewrites (refactor.rewrite.*):

• removeUnusedParam — the unusedparams analyzer offers renaming to _ (trivial) or a full signature change that also updates every caller, preserving side-effecting arguments.
• moveParamLeft / moveParamRight — reorders one parameter, updating every call site.
• changeQuote — toggles a string literal between raw (`...`) and interpreted ("...") form; idempotent to apply twice.
• invertIf — negates a plain if/else condition (no else if chain) and swaps the two blocks.
• splitLines / joinLines — expands or collapses a bracketed list (composite literal, call arguments, signature) one item per line; skipped for lists that already contain // comments or have fewer than two items.
• fillStruct — populates missing struct-literal fields, matching field names to in-scope variables/constants/functions where possible, zero value otherwise. Searches only the current file, above the cursor — run source.organizeImports first if the struct type was just introduced.
• fillSwitch — adds missing cases for an enum-like set of named constants, or for a type switch (one case per concrete type implementing the interface, plus a default that panics on an unexpected type).
• eliminateDotImport — removes a dot import and qualifies every reference, offered only when no name collision would result.
• addTags / removeTags — adds or removes struct field tags (e.g. json); interactive clients can choose the naming transform (camelCase, snake_case, lisp-case, PascalCase, Title Case).
• implementInterface — adds placeholder method declarations so a named type satisfies a chosen interface (defaults to error); interactive-dialog only, gopls-specific.

Add Test For Function (source.addTest) — generates a table-driven test for the selected function/method, creating the _test.go file if needed (copying copyright/build-constraint comments), using an external p_test package to encourage testing exported API only, naming results got/got2/…, comparing against want/want2/…, and adding a wantErr bool field when the final result is error. For a method, searches the package for a constructor (preferring NewT for type T). A leading context.Context parameter gets t.Context() on Go 1.24+, context.Background() otherwise.

Web-based features

gopls runs a small localhost web server (LSP window/showDocument) for reports too rich for inline editor UI. Every endpoint URL embeds a random auth token; restarting gopls invalidates old links and shows a disconnected banner on any page still open.

• Package Documentation (source.doc) — a pkgsite-style rendered view of a package's docs, including internal, unpublished packages pkg.go.dev never sees. Symbol links jump the editor to the source declaration; reload without saving to see current edits reflected.
• Free Symbols (source.freesymbols) — lists the symbols a selection references but doesn't define itself, grouped as imported (with doc links), local, or package-level — the exact input list an Extract Function/Method refactor would need.
• Assembly (source.assembly) — the compiled assembly listing for a function, source-line-linked, recompiled on each reload. Architecture follows the file's build tags (e.g. foo_amd64.go). Not yet supported for generic functions, func init, or functions in test packages.
• Split Package (source.splitPackage) — an interactive dependency-graph tool for planning how to break a package into smaller, acyclic components. It visualizes the split but does not yet perform the actual code movement/renaming.

All of these send edits/navigation back to the editor via showDocument, which works even against modified-but-unsaved source.

Non-Go files

Templates (text/template/html/template) — disabled until templateExtensions lists at least one extension (templates have no canonical extension of their own); the editor also needs to associate that extension with the tmpl/gotmpl language ID (e.g. VS Code's files.associations). Inside {{ }} delimiters: diagnostics (parse errors; missing functions are not flagged), full syntax highlighting, definitions and references (all templates share one global scope), and completions. Hover, semantic tokens, symbol search, and document highlight are not yet implemented. Custom delimiters other than {{/}} are not understood.

go.mod / go.work — hover, hints, vulncheck-driven diagnostics, and code lenses (add dependency, upgrade dependency, tidy, run govulncheck) are supported; the upstream page marks the fine-grained behavior of each as still under documentation, so verify current behavior directly against a go.mod file in an editor session rather than relying on an exhaustive list here.

Assembly (.s) files — basic support exists; treat as best-effort.

Completion

Upstream documentation for this feature is a stub as of this writing (tracked as golang/go#62022) — rely on empirical behavior plus these known settings rather than a documented spec: usePlaceholders (fills in placeholder parameter names on completion), completeFunctionCalls (adds trailing parentheses, on by default), completeUnimported and matcher/deepCompletion-style settings shape whether not-yet-imported packages and nested field/method completions are offered. See settings.md for the full settings surface.