feat: add hex intelligence by dbernheisel · Pull Request #570 · expert-lsp/expert

dbernheisel · 2026-04-11T19:34:22Z

Adds hex package intelligence to mix.exs — package name completion, version completion, dep option suggestions, and hover documentation. Works across the public hex.pm registry and custom self-hosted repos like Oban with no configuration beyond what Mix already knows.

This is fairly self-contained with a few integrated points, so because of that, I felt a large PR would be ok for completeness. Happy to refactor/reorganize modules as you see fit.

Generally, this is porting hex-cmp

What it does

Package completion — type {:phoe and get phoenix, phoenix_live_view, etc. with download counts and descriptions. Custom repo packages (like oban_pro) appear alongside hexpm results with their repo labeled.
Version completion — type {:phoenix, "~> 1. and get filtered version candidates sorted newest-first. Retired versions are annotated with the retirement reason. Works for custom repos without needing repo: typed first.
Dep option completion — type {:phoenix, "~> 1.7", and get only, runtime, override, repo, etc.
Hover docs — hover a package atom to see description, installed vs latest version, license, download count, and links. For custom repos, metadata is extracted from locally-cached tarballs.

How it works

Engine.Deps runs in the project's Mix context (where the Hex archive is loaded) and exposes repo config, dep versions, project files, and cached tarball paths over RPC.
Hex.Context detects the cursor slot (name/version/opts) inside a deps function tuple using Sourceror's error-recovering parser, with a regex line fallback for cases where both parsers fail (unclosed strings). This assumes the conventional "deps" function within the project file (eg, mix.exs), and will not offer intelligence otherwise.
Hex.Api routes through the hex.pm HTTP API via :hex_core dep for public packages and the repo protocol (:hex_repo) for custom repos. Custom repo responses are enriched with tarball metadata if they're already cached.
Hex.Cache is a DETS-backed GenServer with 1-hour TTL and stale-on-error fallback so completions survive network failures and LSP restarts. This helps relieve the server from being hammered with repeated known info from the user.

Testing

Verified with a custom repo, eg, oban.
Verified with public packages
Verified with private hex repos.
Verified with umbrella apps, but it should work since it uses the engine's current InProject helpers.
Verified with projects with a non-standard project file, eg, not named mix.exs

dbernheisel · 2026-04-11T19:35:30Z

    document = Document.Container.context_document(params, nil)
    projects = ActiveProjects.projects()
    project = Project.project_for_document(projects, document)

-    document = Document.Container.context_document(params, nil)
-


not related, but a duplicated call (document is set on line 20 already)

andyl · 2026-04-12T17:33:33Z

@dbernheisel - if this is accepted, will we still need hex-cmp ?

ps hex-cmp has been very handy thanks for this great tool!

dbernheisel · 2026-04-12T18:04:45Z

Nope! It's more complete within Expert; supports custom repos, displays the installed version of the dep, and has access to the projects actual hex to know these things rather than reinventing what mix/hex do.

katafrakt

I tested it and it works really well! Just left some comments, mostly about minor things.

katafrakt · 2026-04-23T10:41:24Z

+  end
+
+  defp project_files(%Project{} = project) do
+    key = {__MODULE__, :project_files, Project.name(project)}


I think it's better to use project.root_uri for cache keys, similar to #575

katafrakt · 2026-04-23T10:48:46Z

+  end
+
+  def dep_version(app) when is_atom(app) do
+    case Application.spec(app, :vsn) do


This only returns dependencies that are actually loaded in the engine node, which means it does not return anything for deps with runtime: false or only: :dev (because IIRC engine node is run in test env). I actually noticed that while testing, before reading the code.

I wonder if it would make sense to use something like Mix.Dep.Lock.read, either as an alternative or as fallback.

Here's a dev-only dep (no remote version info):

and here's one with [:dev, :test]:

good catch. I switched over to using the lock file instead, and falling back onto the Application.spec

katafrakt · 2026-04-23T10:52:57Z

+  def project_scope(nil), do: :__local__
+  def project_scope(%Project{} = project), do: Project.name(project)


These should be private perhaps?

And also wondering if project.root_uri would not be better choice for a cache key here.

yes this is a better choice. I changed it to use project.root_uri

katafrakt · 2026-04-23T10:59:00Z

+    test "returns a list (possibly empty)" do
+      assert is_list(Deps.project_files())
+    end


I'm not sure this test is actually useful

you're right. I deleted it.

katafrakt · 2026-04-23T11:00:42Z

+    test "returns a string or nil (doesn't crash when Mix context is partial)" do
+      refute Deps.project_file(:app)
+      refute Deps.project_file(:umbrella)
+    end


The assertions and the test description here don't match. I think the biggest value is checking that it does not crash, so something like:

Suggested change

test "returns a string or nil (doesn't crash when Mix context is partial)" do

refute Deps.project_file(:app)

refute Deps.project_file(:umbrella)

end

test "doesn't crash when Mix context is partial" do

Deps.project_file(:app)

Deps.project_file(:umbrella)

end

(not sure how others feel about test cases without assertions though)

katafrakt · 2026-04-23T20:49:37Z

One additional thing I noticed is that the changes here don't play nice with expert engine clean. I'm getting this:

❯ ~/.local/bin/expert_darwin_arm64 engine clean --force
Kernel pid terminated (application_controller) ("{application_start_failure,xp_expert,{bad_return,{{'Elixir.XPExpert.Application',start,[normal,[]]},{'EXIT',{#{reason => enotdir,path => <<\"/Users/pawel.sw/Library/Caches/expert/hex.dets\">>,'__struct__' => 'Elixir.File.Error','__exception__' => true,action => <<\"list directory\">>},[{'Elixir.File','ls!',1,[{file,\"lib/file.ex\"},{line,2064}]},{'Elixir.XPExpert.Engine','-get_engine_dirs/0-fun-1-',3,[{file,\"lib/expert/engine.ex\"},{line,103}]},{'Elixir.Enum','-reduce/3-lists^foldl/2-0-',3,[{file,\"lib/enum.ex\"},{line,2520}]},{'Elixir.XPExpert.Engine',get_engine_dirs,0,[{file,\"lib/expert/engine.ex\"},{line,102}]},{'Elixir.XPExpert.Engine',clean_engines,1,[{file,\"lib/expert/engine.ex\"},{line,80}]},{'Elixir.XPExpert.Application',start,2,[{file,\"lib/expert/application.ex\"},{line,26}]},{application_master,start_it_old,4,[{file,\"application_master.erl\"},{line,299}]}]}}}}}")

Crash dump is being written to: erl_crash.dump...done

Looks like the code for clean only handles directories under expert dir. I think there's no reason to delete hex.dets on clean, so we need to just skip it. Not sure it needs to happen in this PR, which is already quite large. Just a prerequisite to merge this one.

This was found in a #570 , which added DETS file inside the cache directory. Then when `engine clean` was run, it failed because it could only handle directories. The failure looked like this: ``` ❯ ~/.local/bin/expert_darwin_arm64 engine clean --force Kernel pid terminated (application_controller) ("{application_start_failure,xp_expert,{bad_return,{{'Elixir.XPExpert.Application',start,[normal,[]]},{'EXIT',{#{reason => enotdir,path => <<\"/Users/pawel.sw/Library/Caches/expert/hex.dets\">>,'__struct__' => 'Elixir.File.Error','__exception__' => true,action => <<\"list directory\">>},[{'Elixir.File','ls!',1,[{file,\"lib/file.ex\"},{line,2064}]},{'Elixir.XPExpert.Engine','-get_engine_dirs/0-fun-1-',3,[{file,\"lib/expert/engine.ex\"},{line,103}]},{'Elixir.Enum','-reduce/3-lists^foldl/2-0-',3,[{file,\"lib/enum.ex\"},{line,2520}]},{'Elixir.XPExpert.Engine',get_engine_dirs,0,[{file,\"lib/expert/engine.ex\"},{line,102}]},{'Elixir.XPExpert.Engine',clean_engines,1,[{file,\"lib/expert/engine.ex\"},{line,80}]},{'Elixir.XPExpert.Application',start,2,[{file,\"lib/expert/application.ex\"},{line,26}]},{application_master,start_it_old,4,[{file,\"application_master.erl\"},{line,299}]}]}}}}}") Crash dump is being written to: erl_crash.dump...done ``` This PR makes the `clean` command skip any files in the cache directory.

mhanberg · 2026-04-25T00:42:11Z

Could you go over this code again manually, there seems to be a lot of pointless wrapping and unwrapping of return values, unnecessary intermediate variables, and some basic things.

I imagine the design can be improved and minimized with a closer inspection.

dbernheisel · 2026-04-25T01:20:30Z

Could you go over this code again manually, there seems to be a lot of pointless wrapping and unwrapping of return values, unnecessary intermediate variables, and some basic things.

I imagine the design can be improved and minimized with a closer inspection.

I did before I opened it and a couple times after, and I didn't see anything obvious. There are some "safe" rescues and catches that are annoying but they're at RPC boundaries that seem reasonable.

Feel free to modify it as you wish.

Add hex intelligence for mix.exs deps function

157b6ec

dbernheisel commented Apr 11, 2026

View reviewed changes

dbernheisel changed the title ~~Add Hex intelligence~~ feat: add hex intelligence Apr 11, 2026

dbernheisel added 2 commits April 11, 2026 23:05

Remove chatty comments

45a90e3

Fixup dialyzer errors

d96be52

katafrakt reviewed Apr 23, 2026

View reviewed changes

feedback: use project_uri instead. Read mix.lock instead

1060cc6

katafrakt mentioned this pull request Apr 24, 2026

fix: skip regular files on engine clean #613

Merged

		def project_scope(nil), do: :__local__
		def project_scope(%Project{} = project), do: Project.name(project)

Uh oh!

Conversation

dbernheisel commented Apr 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What it does

How it works

Uh oh!

Choose a reason for hiding this comment

Uh oh!

andyl commented Apr 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dbernheisel commented Apr 12, 2026

Uh oh!

katafrakt left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

katafrakt commented Apr 23, 2026

Uh oh!

mhanberg commented Apr 25, 2026

Uh oh!

dbernheisel commented Apr 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

dbernheisel commented Apr 11, 2026 •

edited

Loading

andyl commented Apr 12, 2026 •

edited

Loading