Add definitionStyle option to control multi-head goto definition

[flowerett]

Solves this issue

When a function has multiple heads/clauses, editors like Zed show a picker UI instead of jumping directly.

The new "definitionStyle" initializationOption ("all" or "first") lets users choose whether to return all definition sites or just the first one.

the new initializationOption will look like:

"dexter": {
      "initialization_options": {
        ...
        "definitionStyle": "first" # or "all"
      }
}

---

Note

Medium Risk
Changes core LSP definition resolution (arity parsing, delegate following, use chains); broad test coverage but heuristic arity detection can mis-resolve ambiguous calls.

Overview
Adds definitionStyle ("all" | "first", default "all") as an LSP initializationOption and applies it at the end of go-to-definition so editors can jump to a single site instead of showing a multi-head picker (e.g. Zed).

Go-to-definition is now arity-aware. The server infers call arity at the cursor (ArityAtCallsite, including keyword lists, pipes, captures, and many edge cases) and threads it through lookups: indexed store queries (LookupFunctionByArity, per-arity LookupFollowDelegateByArity), current-buffer FindDefinitionLines, generated BEAM symbols, and use / __using__ chains (including inline defs and dynamic imports). When arity is unknown, behavior stays broad; when it matches, overloads and mixed defdelegate/def names resolve to the right clause.

use-chain visiting keys visits on consumer opts so the same injector used with different options is not skipped incorrectly.

README documents definitionStyle for Neovim and JSON LSP config.

^{Reviewed by Cursor Bugbot for commit 6fac4f1. Bugbot is set up for automated code reviews on this repo. Configure here.}

[flowerett]

@JesseHerrick would be great to know your thoughts about this approach and naming.

[JesseHerrick]

Hey @flowerett, thanks for the PR! This same thing happens with all editors and LSPs when there are multiple function heads for the same definition with the same arity. IMO that is a feature. While it's something we could change in the LSP, this is something I'd actually leave up to the LSP client and editor to configure to their liking. Editors should be able to just say "give me the first option" instead of opening the list if they want it. In NeoVim this isn't too tricky to configure, but maybe in Zed it's a pain. Thoughts?

[flowerett]

Hey @JesseHerrick, thanks for the feedback!
Agreed this would be better to put into the client. The practical blocker is specifically Zed though:

• The Zed extension API is a passthrough for LSP responses — it doesn't expose a hook to filter a Location array, so we can't solve this in the elixir-zed extension.
• Zed core doesn't currently expose a "jump to first definition" setting either.

So for Zed users today there's no client-side option at all.
For NeoVim / VS Code users who can configure it, this PR's option is a no-op (default "all").

While validating the original report locally I also found two real bugs that were producing multi-location results for calls with a single intended target:
LookupFunction wasn't filtering by arity, and lookupFollowDelegate didn't follow when a module mixed a defdelegate with a def of the same name. I'm pushing those fixes as a separate commit on this branch. With them in, definitionStyle is narrowly the opt-in for what you described as the feature case (same module, same arity, multiple heads) rather than a workaround for the broader issue.

I've created a small Elixir project to debug and reproduce the issues - [dummy_dexter_ex}(https://github.com/flowerett/dummy_dexter_ex)

My preference would be to keep it in this PR with default "all", this won't change default behavior and Zed users get a workable option - "first" if they want to.

[cursor]

Stale Bugbot comment from a previous run.

[JesseHerrick]

Thanks @flowerett. You're right - I was confusing the go-to-ref arity checking with go-to-definition. We indeed should add that filtering.

I'm totally fine with adding this change as default off so that those who want it can enable it. I'll review the PR later today.

[flowerett]

Hey @JesseHerrick should I finish this fix or is it better to close the PR, wdyt?

[JesseHerrick]

Hey @flowerett, sorry, yes I think we should finish this one up. There's two important elements:

• The lookup by arity is a really nice improvement.
• The disabled-by-default only give me one result option will also be nice to have.

[flowerett]

Hey @JesseHerrick !
I finally found some time to fix this MR, I believe all the feedback is addressed now and it's now ready to merge.

[flowerett]

Some findings

• [important] internal/lsp/elixir.go:85 miscomputes arity for valid nested, block, capture-like, interpolation, and parenthesis-free forms, so go-to-definition can select the wrong function.
• [important] internal/lsp/server.go:1134 leaves bare current-module calls on the old first-name-match path, bypassing both arity filtering and definitionStyle.
• [important] internal/lsp/name_navigation.go:74 filters use-chain results after choosing a provider, so an earlier matching-arity import is missed; initialization coverage and the three direct token loops also need follow-up.

[flowerett]

New findings

• [important] internal/lsp/elixir.go:191 still assigns special-form commas to the outer call, so exact lookup can select the wrong arity or fall back to the module. (narrowed)
• [important] internal/lsp/elixir.go:298 scans every module in the buffer, so a bare call in the first module can navigate to an unrelated nested or later declaration. (new)
• [important] internal/lsp/server.go:2538 shares cycle state across parameterized uses, so a valid earlier provider can be skipped and navigation falls back to the consumer module. (repeat)

Round 2 · reviewed at fd8780a

[cursor]

Cursor Bugbot has reviewed your changes and found 3 potential issues.

^{Reviewed by Cursor Bugbot for commit 4c6d467. Configure here.}

[flowerett]

✅ Approve

Round 3 · reviewed at 1d5ae1a

automatic review done by (claude-opus-5-5 medium)

[flowerett]

🔴 Request changes

• [critical] internal/lsp/server_test.go:333 and :614 preserve personal attributions in repository history; replace them with issue/PR references and remove them from the branch’s commits. (new)

Blocking remaining: 1

Round 4 · reviewed at 1d5ae1a

automatic review done by (gpt-6.1-sol medium)

[flowerett]

🔴 Request changes

• [critical] internal/store/store.go:2084 follows default-argument delegates at the wrapper’s arity, selecting an unrelated overload or stopping before the implementation. (new)

Round 5 · reviewed at 18b453e

automatic review done by (gpt-6.1-sol medium)

[flowerett]

✅ Approve

Blocking remaining: none

Round 6 · reviewed at 6fac4f1

automatic review done by (gpt-6.1-sol medium)