add declaration provider

Author: lukaszsamson

apps/language_server/lib/language_server/location.ex

@@ -11,13 +11,13 @@ defmodule ElixirLS.LanguageServer.Location do
 
   alias ElixirSense.Core.Metadata
   alias ElixirSense.Core.Parser
-  alias ElixirSense.Core.State.{ModFunInfo, TypeInfo}
+  alias ElixirSense.Core.State.{ModFunInfo, TypeInfo, SpecInfo}
   alias ElixirSense.Core.Normalized.Code, as: CodeNormalized
   require ElixirSense.Core.Introspection, as: Introspection
   alias ElixirLS.LanguageServer.Location.Erl
 
   @type t :: %__MODULE__{
-          type: :module | :function | :variable | :typespec | :macro | :attribute,
+          type: :module | :function | :variable | :typespec | :macro | :attribute | :callback,
           file: String.t() | nil,
           line: pos_integer,
           column: pos_integer,
@@ -50,6 +50,18 @@ defmodule ElixirLS.LanguageServer.Location do
     end
   end
 
+  @spec find_callback_source(module, atom, non_neg_integer | {:gte, non_neg_integer} | :any) ::
+          t() | nil
+  def find_callback_source(mod, type, arity) do
+    case find_mod_file(mod) do
+      file when is_binary(file) ->
+        find_callback_position({mod, file}, type, arity)
+
+      _ ->
+        nil
+    end
+  end
+
   defp find_mod_file(Elixir), do: nil
 
   defp find_mod_file(module) do
@@ -343,6 +355,19 @@ defmodule ElixirLS.LanguageServer.Location do
     |> min_by_line
   end
 
+  def get_callback_position_using_metadata(mod, fun, call_arity, specs) do
+    specs
+    |> Enum.filter(fn
+      {{^mod, ^fun, spec_arity}, _type_info}
+      when not is_nil(spec_arity) and Introspection.matches_arity?(spec_arity, call_arity) ->
+        true
+
+      _ ->
+        false
+    end)
+    |> min_by_line
+  end
+
   defp min_by_line(list) do
     result =
       list
@@ -385,4 +410,73 @@ defmodule ElixirLS.LanguageServer.Location do
 
     {begin_position, end_position}
   end
+
+  defp find_callback_position({mod, file}, fun, arity) do
+    result =
+      if String.ends_with?(file, ".erl") do
+        Erl.find_callback_range(file, fun)
+      else
+        file_metadata = Parser.parse_file(file, false, false, nil)
+        get_callback_position(file_metadata, mod, fun, arity)
+      end
+
+    case result do
+      {{line, column}, {end_line, end_column}} ->
+        %__MODULE__{
+          type: :callback,
+          file: file,
+          line: line,
+          column: column,
+          end_line: end_line,
+          end_column: end_column
+        }
+
+      # TODO remove
+      {line, column} ->
+        %__MODULE__{
+          type: :callback,
+          file: file,
+          line: line,
+          column: column,
+          end_line: line,
+          end_column: column
+        }
+
+      _ ->
+        nil
+    end
+  end
+
+  defp get_callback_position(metadata, module, callback, arity) do
+    case get_callback_position_using_metadata(module, callback, arity, metadata.specs) do
+      nil ->
+        get_callback_position_using_docs(module, callback, arity)
+
+      %SpecInfo{} = info ->
+        info_to_range(info)
+    end
+  end
+
+  defp get_callback_position_using_docs(module, callback_name, arity) do
+    case CodeNormalized.fetch_docs(module) do
+      {:error, _} ->
+        nil
+
+      {_, _, _, _, _, _, docs} ->
+        docs
+        |> Enum.filter(fn
+          {{category, ^callback_name, doc_arity}, _line, _arg3, _arg4, _meta}
+          when category in [:callback, :macrocallback] ->
+            Introspection.matches_arity?(doc_arity, arity)
+
+          _ ->
+            false
+        end)
+        |> Enum.map(fn
+          {{_category, _function, _arity}, anno, _, _, _} ->
+            anno_to_range(anno)
+        end)
+        |> Enum.min_by(fn {position, _end_position} -> position end, &<=/2, fn -> nil end)
+    end
+  end
 end

apps/language_server/lib/language_server/location/erl.ex

@@ -30,6 +30,30 @@ defmodule ElixirLS.LanguageServer.Location.Erl do
     find_range_by_regex(file, regex)
   end
 
+  @doc """
+  Finds the position range of a callback definition in an Erlang `.erl` file.
+
+  ## Parameters
+
+    - `file`: The path to the Erlang file.
+    - `name`: The name of the type (as an atom).
+
+  ## Returns
+
+    - `{{line, start_column}, {line, end_column}}` if found.
+    - `nil` if not found.
+  """
+  def find_callback_range(file, name) do
+    escaped =
+      name
+      |> Atom.to_string()
+      |> Regex.escape()
+
+    regex = ~r/^-callback\s+(?<name>#{escaped})\b/u
+
+    find_range_by_regex(file, regex)
+  end
+
   @doc """
   Finds the position range of a function definition in an Erlang `.erl` file.
 

apps/language_server/lib/language_server/protocol.ex

@@ -101,6 +101,15 @@ defmodule ElixirLS.LanguageServer.Protocol do
     end
   end
 
+  defmacro declaration_req(id, uri, line, character) do
+    quote do
+      request(unquote(id), "textDocument/declaration", %{
+        "textDocument" => %{"uri" => unquote(uri)},
+        "position" => %{"line" => unquote(line), "character" => unquote(character)}
+      })
+    end
+  end
+
   defmacro implementation_req(id, uri, line, character) do
     quote do
       request(unquote(id), "textDocument/implementation", %{

apps/language_server/lib/language_server/providers/declaration.ex

@@ -0,0 +1,27 @@
+defmodule ElixirLS.LanguageServer.Providers.Declaration do
+  @moduledoc """
+  textDocument/declaration provider utilizing Elixir Sense
+  """
+
+  alias ElixirLS.LanguageServer.{Protocol, Parser}
+  alias ElixirLS.LanguageServer.Providers.Declaration.Locator
+
+  def declaration(
+        uri,
+        %Parser.Context{source_file: source_file, metadata: metadata},
+        line,
+        character,
+        project_dir
+      ) do
+    result =
+      case Locator.declaration(source_file.text, line, character, metadata: metadata) do
+        nil ->
+          nil
+
+        %ElixirLS.LanguageServer.Location{} = location ->
+          Protocol.Location.new(location, uri, source_file.text, project_dir)
+      end
+
+    {:ok, result}
+  end
+end

apps/language_server/lib/language_server/providers/declaration/locator.ex

@@ -0,0 +1,104 @@
+defmodule ElixirLS.LanguageServer.Providers.Declaration.Locator do
+  @moduledoc """
+  Provides a function to find the declaration of a callback or protocol function,
+  that is, the place where a behaviour or protocol defines the callback that is being
+  implemented.
+
+  This is effectively the reverse of the "go to implementations" provider.
+  """
+
+  alias ElixirSense.Core.Behaviours
+  alias ElixirSense.Core.Binding
+  alias ElixirSense.Core.Metadata
+  alias ElixirSense.Core.Normalized.Code, as: NormalizedCode
+  alias ElixirSense.Core.State
+  alias ElixirLS.LanguageServer.Location
+  alias ElixirSense.Core.Parser
+
+  require ElixirSense.Core.Introspection, as: Introspection
+
+  @doc """
+  Finds the declaration (callback or protocol definition) for the function under the cursor.
+
+  It parses the code, determines the environment and then checks if the current function
+  is an implementation of any behaviour (or protocol). For each matching behaviour,
+  it returns the location where the callback is declared.
+
+  Returns either a single `%Location{}` or a list of locations if multiple declarations are found.
+  """
+  def declaration(code, line, column, options \\ []) do
+    case NormalizedCode.Fragment.surround_context(code, {line, column}) do
+      :none ->
+        nil
+
+      context ->
+        metadata =
+          Keyword.get_lazy(options, :metadata, fn ->
+            Parser.parse_string(code, true, false, {line, column})
+          end)
+
+        env = Metadata.get_cursor_env(metadata, {line, column}, {context.begin, context.end})
+        find(context, env, metadata)
+    end
+  end
+
+  @doc false
+  def find(context, %State.Env{module: module} = env, metadata) do
+    # Get the binding environment as in the other providers.
+    # binding_env = Binding.from_env(env, metadata, context.begin)
+
+    case env.function do
+      nil ->
+        nil
+
+      {fun, arity} ->
+        # Get the behaviours (and possibly protocols) declared for the current module.
+        behaviours = Metadata.get_module_behaviours(metadata, env, module)
+
+        # For each behaviour, if the current function is a callback for it,
+        # try to find the callback’s declaration.
+        locations =
+          for behaviour <- behaviours,
+              Introspection.is_callback(behaviour, fun, arity, metadata),
+              location = get_callback_location(behaviour, fun, arity, metadata),
+              location != nil do
+            location
+          end
+
+        case locations do
+          [] -> nil
+          [single] -> single
+          multiple -> multiple
+        end
+    end
+  end
+
+  # Attempts to find the callback declaration in the behaviour (or protocol) module.
+  # First it checks for a callback spec in the metadata; if none is found, it falls back
+  # to trying to locate the source code.
+  defp get_callback_location(behaviour, fun, arity, metadata) do
+    case Enum.find(metadata.specs, fn
+           {{^behaviour, ^fun, a}, _spec_info} ->
+             Introspection.matches_arity?(a, arity)
+
+           _ ->
+             false
+         end) do
+      nil ->
+        # Fallback: try to locate the function in the behaviour module’s source.
+        Location.find_callback_source(behaviour, fun, arity)
+
+      {{^behaviour, ^fun, _a}, spec_info} ->
+        {{line, column}, {end_line, end_column}} = Location.info_to_range(spec_info)
+
+        %Location{
+          file: nil,
+          type: :callback,
+          line: line,
+          column: column,
+          end_line: end_line,
+          end_column: end_column
+        }
+    end
+  end
+end

apps/language_server/lib/language_server/server.ex

@@ -34,6 +34,7 @@ defmodule ElixirLS.LanguageServer.Server do
     Completion,
     Hover,
     Definition,
+    Declaration,
     Implementation,
     References,
     Formatting,
@@ -979,6 +980,18 @@ defmodule ElixirLS.LanguageServer.Server do
     {:async, fun, state}
   end
 
+  defp handle_request(declaration_req(_id, uri, line, character), state = %__MODULE__{}) do
+    source_file = get_source_file(state, uri)
+
+    fun = fn ->
+      {line, character} = SourceFile.lsp_position_to_elixir(source_file.text, {line, character})
+      parser_context = Parser.parse_immediate(uri, source_file, {line, character})
+      Declaration.declaration(uri, parser_context, line, character, state.project_dir)
+    end
+
+    {:async, fun, state}
+  end
+
   defp handle_request(implementation_req(_id, uri, line, character), state = %__MODULE__{}) do
     source_file = get_source_file(state, uri)
 
@@ -1291,6 +1304,7 @@ defmodule ElixirLS.LanguageServer.Server do
       "hoverProvider" => true,
       "completionProvider" => %{"triggerCharacters" => Completion.trigger_characters()},
       "definitionProvider" => true,
+      "declarationProvider" => true,
       "implementationProvider" => true,
       "referencesProvider" => true,
       "documentFormattingProvider" => true,