Fix LSP go-to-definition for ref command references

[kindermax]

Summary

• add ref cursor detection to the YAML LSP parser
• resolve ref: <command> through the existing command definition lookup path
• cover the new behavior with parser and definition tests
• update IDE support docs and the changelog

Testing

• lets fmt
• go test ./internal/lsp/...
• go test ./...

Summary by Sourcery

Extend LSP go-to-definition support to recognize YAML ref command references and resolve them to their command definitions.

Bug Fixes:

• Fix go-to-definition so that command references declared via ref: <command> are correctly resolved in the LSP server.

Enhancements:

• Add parser support to detect cursor positions on ref values and treat them as command references for navigation.

Documentation:

• Document that go-to-definition now works for command references from depends, ref, and YAML merge aliases, and note the fix in the changelog.

Tests:

• Add parser and definition handler tests covering detection and resolution of ref command references.

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[sourcery-ai]

Reviewer's Guide

Extends the LSP YAML parser so go-to-definition also works from ref: <command> mappings by detecting ref cursor positions, resolving them via the existing command definition lookup, and documenting the new behavior.

Sequence diagram for LSP go-to-definition from ref mappings

sequenceDiagram
    actor Developer
    participant IDE
    participant LSPServer
    participant Parser
    participant DefinitionHandler

    Developer->>IDE: Trigger go-to-definition on ref value
    IDE->>LSPServer: textDocument/definition(params)
    LSPServer->>Parser: getPositionType(document, position)
    Parser->>Parser: inMixinsPosition / inDependsPosition / inCommandAliasPosition
    Parser->>Parser: inRefPosition(document, position)
    Parser-->>LSPServer: PositionTypeRef

    LSPServer->>DefinitionHandler: findCommandDefinition(doc, params)
    DefinitionHandler->>Parser: extractCommandReference(document, position)
    Parser->>Parser: extractAliasCommandReference
    Parser->>Parser: extractRefCommandReference(document, position)
    Parser-->>DefinitionHandler: commandName

    DefinitionHandler->>Parser: findCommandNameByAnchor(document, commandName)
    Parser-->>DefinitionHandler: commandDefinitionLocation
    DefinitionHandler-->>LSPServer: lsp.Location
    LSPServer-->>IDE: textDocument/definition result
    IDE-->>Developer: Navigate to command definition

Loading

Class diagram for updated LSP parser and definition handling

classDiagram
    class parser {
        +log
        +getPositionType(document *string, position lsp_Position) PositionType
        +inMixinsPosition(document *string, position lsp_Position) bool
        +inDependsPosition(document *string, position lsp_Position) bool
        +inCommandAliasPosition(document *string, position lsp_Position) bool
        +inRefPosition(document *string, position lsp_Position) bool
        +extractFilenameFromMixins(document *string, position lsp_Position) string
        +extractCommandReference(document *string, position lsp_Position) string
        +extractAliasCommandReference(document *string, position lsp_Position) string
        +extractRefCommandReference(document *string, position lsp_Position) string
        +findCommandNameByAnchor(document *string, anchorName string) string
    }

    class PositionType {
        <<enumeration>>
        +PositionTypeMixins
        +PositionTypeDepends
        +PositionTypeCommandAlias
        +PositionTypeRef
        +PositionTypeNone
        +String() string
    }

    class lspServer {
        +log
        +textDocumentDefinition(context glsp_Context, params *lsp_DefinitionParams) interface
    }

    class definitionHandler {
        +findMixinsDefinition(doc *document, params *lsp_DefinitionParams) interface
        +findCommandDefinition(doc *document, params *lsp_DefinitionParams) interface
    }

    parser --> PositionType
    lspServer --> parser
    lspServer --> definitionHandler
    definitionHandler --> parser

Loading

File-Level Changes

Change	Details	Files
Detect ref value positions in the YAML LSP parser and classify them as a distinct position type.	Add PositionTypeRef enum value and string representation to the position type system. Update getPositionType to call a new inRefPosition helper for detecting cursors on ref values. Implement inRefPosition using a Tree-sitter YAML query that matches ref keys with scalar values and checks cursor containment.	internal/lsp/treesitter.go internal/lsp/treesitter_test.go
Resolve command references from ref: <command> using the existing command definition lookup path.	Extend extractCommandReference to fall back to extracting a ref command when alias resolution fails. Introduce extractRefCommandReference which uses a YAML query to read the scalar value of ref keys at the cursor position. Wire PositionTypeRef into textDocumentDefinition so ref positions route to findCommandDefinition. Add a dedicated test to assert that go-to-definition from a ref value finds the referenced command definition.	internal/lsp/treesitter.go internal/lsp/treesitter_test.go internal/lsp/handlers.go
Document and test the new ref-based go-to-definition behavior.	Add parser-level tests for ref position detection and command reference extraction from ref values. Add an integration-style test for findCommandDefinition when invoked from a ref mapping. Update IDE support docs to list ref and merge aliases as supported go-to-definition sources. Add a changelog entry describing the fix for go-to-definition from ref: build command references.	internal/lsp/treesitter_test.go docs/docs/ide_support.md docs/docs/changelog.md

Possibly linked issues

• #(none provided): PR adds parser, position detection, and definition resolution so LSP go-to-definition works for ref: <command>

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've found 1 issue, and left some high level feedback:

• The tree-sitter query for ref is duplicated in both inRefPosition and extractRefCommandReference; consider extracting this query (or a small helper that returns the matching node) to avoid repetition and keep the ref-handling behavior in one place.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The tree-sitter query for `ref` is duplicated in both `inRefPosition` and `extractRefCommandReference`; consider extracting this query (or a small helper that returns the matching node) to avoid repetition and keep the ref-handling behavior in one place.

## Individual Comments

### Comment 1
<location path="docs/docs/ide_support.md" line_range="36" />
<code_context>
 - [x] Goto definition
   - Navigate to definitions of mixins files
-  - Navigate to definitions of command from `depends`
+  - Navigate to definitions of command from `depends`, `ref`, and YAML merge aliases
 - [x] Completion
   - Complete commands in depends
</code_context>
<issue_to_address>
**suggestion (typo):** Consider using the plural 'commands' instead of 'command' for grammatical agreement.

Now that you mention multiple sources (`depends`, `ref`, and YAML merge aliases), please use the plural form “commands” to keep the sentence grammatically correct.

```suggestion
  - Navigate to definitions of commands from `depends`, `ref`, and YAML merge aliases
```
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[sourcery-ai]

suggestion (typo): Consider using the plural 'commands' instead of 'command' for grammatical agreement.

Now that you mention multiple sources (depends, ref, and YAML merge aliases), please use the plural form “commands” to keep the sentence grammatically correct.

Suggested change

	- Navigate to definitions of command from `depends`, `ref`, and YAML merge aliases
	- Navigate to definitions of commands from `depends`, `ref`, and YAML merge aliases