Send generated functions to the line that declared them

[JesseHerrick]

Closes #108. Supersedes #102, which is folded in here. Go-to-definition for DSL-generated functions such as Ash code interfaces. It does not special-case any framework. The Ash side is ash-project/ash#2971, which is merged and will ship in the next Ash release after v3.33.11. With released Ash, a code interface goes to its define line too, from the generic declaring-call search described below.

Summary

A function that a macro generates has no source definition, so go-to-definition fell back to the top of its module. The compiled module's Dbgi chunk records the location of each def:

• Its :line is the line in the module's own file that was compiled when the def was made. Usually this is the macro call or the line where a before-compile hook ran, but a generator can expand the def at any line.
• A file: {path, line} entry comes from @file or from quote location: :keep. When path is the module's own source, this line is where the code asked for the function. When path is another file, it is the generator's own implementation, and :line is used instead.

Released Ash records line: 1, file: {"deps/ash/lib/ash/code_interface.ex", N} for every generated def. After ash#2971, Ash expands each generated def at its define line, so the debug info is line: <define line>, file: {"deps/ash/lib/ash/code_interface.ex", N}. The foreign-file rule above picks up :line. Ash did not use @file, because the function body's lines still come from code_interface.ex, so stacktraces would show the user's file with Ash's line numbers. Their approach keeps stacktraces unchanged.

Changes

• beam.ReadDefinitionLines walks {:debug_info_v1, :elixir_erl, {:elixir_v1, map, specs}} and reads only file, relative_file, and definitions. It steps over clause bodies without allocating. Clause ASTs can nest very deep, so the ETF reader now steps over a term with a count of the terms still to skip instead of recursion: any nesting costs no stack, a count larger than the bytes left is rejected as corrupt, and the old depth guard is gone. This is also about 1.8x faster on large Dbgi chunks; Docs parsing speed is unchanged. Modules without Elixir debug info (debug_info: false, Erlang modules, no chunk) return an error and keep the fallback.
• generatedDefinitionResultsFor uses a recorded line only when all of these conditions are true:
  • The debug info was compiled from the file being opened (same absolute path, or the relative path matches as a suffix, for a project that was moved or is reached through a symlink).
  • The line is after the module's own line. A line at or before it adds nothing to the module result.
    In all other cases, the result stays as before. A BEAM older than the source still gives its line. Dexter cannot compile the project, so a stale BEAM is the usual state while you edit, and the line from the last compile is closer than the module line. Only edits to the declaring file move it, and the next compile makes it exact. The line is not corrected for those edits: every way to do that meant guessing at the compiled text, and could send the editor to a wrong line that looked right.
• From Resolve generated definitions to their source annotation #102: beam.Function.Line keeps the Docs chunk anno, and beam.ReadSourcePath reads :source from the CInf chunk. The Docs anno is often the same line as the Dbgi :line, but not always: Ash's code interfaces give the docs line 1. It is used when a module has no debug info, and CInf says which file the line is in.
• From Resolve generated definitions to their source annotation #102: a generated module with no source row, such as a Spark entity module, goes to the file it was compiled from. When that path does not exist here (a BEAM built elsewhere), it is rebased onto lib/<app>, deps/<app>/lib/<app>, or deps/<app>. The app name comes from the recorded path, because Spark builds Ash's entity modules in Ash's ebin from Spark's source. If no file is found, the lexical parent stays the answer.
• Bare-call definition and call-hierarchy preparation call it directly. Qualified definition, the references declaration, and dexter lookup get it through LookupName (shared since Unify CLI and editor semantic navigation #107). A recorded line is the function's own definition, so LookupName returns it for a strict (ExactModule) lookup too. Without a recorded line, strict and fallback lookups do not change.
• The debug info and compile info are read on the first definition request that needs them. It is memoized on the module's generated-function cache entry, so the BEAM stamp invalidates it with everything else.

Also in this PR

• Declaring call. When the only line the BEAM records is the module line (a @before_compile hook, or released Ash), the module's body is searched for the call whose first argument is the function's name as an atom. When several calls spell the name, as an Ash action and the code interface that runs it do (update :publish and define :publish), the macro whose calls name the most of the module's generated functions wins: define names every interface, an action names only itself. A tie keeps the module line.
• Clauses. A function with a clause per DSL call (route :get, route :post) goes to every clause, from the line Dbgi records for each clause.
• Past the end of the file. A recorded line the current text does not have (quote line: 99) is dropped.
• Module names. Go-to-definition on a module that exists only as a BEAM (Module.create) goes to the file and line the compiler recorded. A module that a macro made with defmodule unquote(name) and a name it computed records no module line, so it goes to its first function's line.
• Imports. A bare call to a generated function of an imported module resolves.
• Defs in macro quotes. The parser no longer indexes a def inside a quote in a macro other than __using__ as a function of the macro's module. defmacro route ... quote do def handle made the index claim that the DSL defines handle/2, so a consumer that imports the DSL resolved Consumer.handle into the macro's body before the BEAM was asked. What __using__ injects and a quote in a helper function are still indexed.
• Older Elixir. Elixir 1.17 and earlier record the module line under line, not anno; both are read. A location: :keep macro defined above its caller in the same file is no longer taken for an @file stamp.
• Worktree moves (fix for Skip linked git worktrees nested in the project #111). git worktree move renames the directory and then rewrites its .git file in place, so a watcher can read it empty and take the worktree for a plain directory: the fsnotify backend reported every file in it, and the FSEvents backend ran a full reconcile. A .git file that names no git directory yet now makes the directory a pending top, which is checked again once git is done. This was the cause of the flaky TestFSNotifyWatcherSkipsWorktreeAddedWhileRunning on Linux; both backends now have a deterministic test for it.
• Compressed BEAMs. A BEAM compiled with the compressed option (a gzip stream, used by some Erlang dependencies) is decompressed instead of rejected.
• Integration tests. TestDefinition_GeneratedFunctionsFromCompiler* compile a DSL fixture of each shape with mix (with and without debug info, and with a stale source) and run in the integration job.

Performance

A cold read on real Ash modules takes 0.8–2 ms (inflate plus walk; Repro.Chat's Dbgi is 19 KB compressed and 350 KB inflated). It happens once per BEAM stamp and only on a definition miss for a generated function. The parser change below bumps IndexVersion (and the daemon contract), so each workspace rebuilds its index once after the upgrade, through the parallel full build.

Validation

• go test ./... and make lint pass.
• New internal/beam tests: own-file location, foreign location, plain :line, macros and private defs, stripped or Erlang debug info, truncation at every seventh byte, a clause body 200,000 ETF levels deep, and a test that compiles real modules with elixirc (skipped if Elixir is not installed) for @file, location: :keep, and plain quotes. It also checks that the Docs anno and the CInf source agree with the debug info.
• New LSP tests: qualified and bare definitions and call hierarchy go to the recorded line, for both the @file shape and the Ash shape (:line with a generator file). LookupName returns the recorded line with and without ExactModule, and a strict lookup without a recorded line keeps the module. A stale BEAM goes to the line it recorded, and never to a line past the end of the file. A foreign location with no useful :line, and debug info from a different source file, keep the module line. The Docs anno gives the line when there is no Dbgi, and does not when there is no CInf source. A sourceless generated module goes to its rebased deps file from Dbgi or Docs, and to its lexical parent when that file is missing.
• End to end on the repro app from Go-to-definition for Ash DSL-generated functions (code interfaces) resolves to line 1 #108 against Ash main (9fa5088, includes ash#2971), with lspprobe for definition and dexter lookup --strict for the CLI. Both give the same lines:

Probe	main	this branch
Chat.get_room_by_slug!	chat.ex:1	chat.ex:7
Chat.create_room	chat.ex:1	chat.ex:8
Repro.Chat.Room.rename (resource code_interface)	room.ex:1	room.ex:19

End to end on a project with no dependencies and a DSL in the project, for macros that are not Ash (main gives line 1 of user.ex for all of them except hello):

Generator	this branch
plain quote (field :email)	user.ex:4
location: :keep	user.ex:6
@file {file, line}	user.ex:8
__using__ injection	dsl.ex:5 (unchanged, the def in the quote)
nested defmodule from a macro	user.ex:10
Module.create in the generator's file (no source row)	dsl.ex:43

The same results hold for a copy of the project that was not recompiled, for an umbrella copied the same way (apps/<app>/lib), and for a project in a directory named with é and 日本.

🤖 Generated with Claude Code

[onnimonni]

I tried the Ash half of this. Findings, in case they change the plan:

@file has a cost Ash probably won't take: it breaks stacktraces. @file sets the file for the whole generated function, but with location: :keep its body's line numbers still come from code_interface.ex. So a crash inside a generated function reports the user's domain file with Ash's line numbers (e.g. lib/my_app/chat.ex:1150, a line unrelated to anything), where today it correctly says deps/ash/lib/ash/code_interface.ex:1150. "Stacktraces point at the define line" only holds for the function head, not the frames users see. Minimal repro (Elixir 1.20.4):

defmodule Gen do
  defmacro gen(name, override?) do
    quote bind_quoted: [name: name, override?: override?], location: :keep do
      if override?, do: @file({"/user/domain.ex", 42})
      def unquote(name)(x) do
        r = String.to_integer(x)   # line 7 of gen.ex
        r + 1
      end
    end
  end
end
# stamped frame: {User, :stamped, 1, [file: ~c"/user/domain.ex", line: 7]}

What works with this PR as it is: keep file pointing at code_interface.ex and set only the def's :line to the define line. :line is the environment's line when def expands, so Ash can evaluate each generated def with %{env | line: define_line} (dropping the def node's own :line meta). Debug info becomes line: 18, file: {"deps/ash/lib/ash/code_interface.ex", N}, stacktraces are unchanged, and this PR's foreign-file fallback to :line picks it up without changes. With this branch plus that Ash change, lspprobe on a Phoenix app gives chat_ash.ex:18 / :16 for get_room_by_slug! / list_rooms! (main: :1, the defmodule line).

Ash issue: ash-project/ash#2970, PR: ash-project/ash#2971.

One small thing I hit while testing: this branch indexes the enclosing checkout's .dexter when run inside a linked worktree nested in the repo. #111 fixes that, so I tested the two together.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

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

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 3bbd46a. Configure here.}