Agent guidelines

For a detailed reference of the LSP code flows, use-chain resolution, variable scoping, and rename logic, see docs/architecture.md.

Building and testing

make build  # build dexter binary
make test   # run all tests
make lint   # run after completing a set of changes

Install golangci-lint if needed:

go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.11.4

Conventions

• Our guiding principles for all code written are: We want maximum performance and speed, but without sacrificing correctness of results. It's okay to sacrifice some readability in the name of performance, but be mindful of the tradeoffs.
• When fixing reported bugs, write the regression test first, verify the failure, and then write the fix.
• When given real code causing bugs, use fake/generic module and function names in tests (e.g. MyApp.Accounts, SharedLib.Worker) — never use real names from the user's codebase, even for regression tests
• When writing code that affects the in-document runtime parsing that is similar to the index parsing (or vice versa), see if the code can be unified to reduce deduplication. But we should never do this at the cost of performance. Indexing must be kept fast no matter what.
• Keep the CLI commands (init, reindex, lookup, references, stop) working with no editor open. They are frontends to the workspace daemon, not clients of the LSP; init is the only one that takes exclusive workspace ownership. The daemon is the only process that opens the index for normal operation, and it belongs to the workspace rather than to any frontend: dexter lsp is also a frontend, a stdio proxy, and nothing may serve an editor in-process
• Parser tests should cover real-world Elixir patterns from large codebases
• Version strings (Version, IndexVersion, and daemon.ContractVersion) live in internal/version/version.go and internal/daemon/endpoint.go. Do not bump them in feature PRs; version bumps are made together in a separate release PR. Whenever IndexVersion is bumped, bump daemon.ContractVersion with it: a running daemon from the older build would otherwise keep serving the new frontend from the stale index.

When a release PR should bump IndexVersion

Do not change Version or IndexVersion in a feature PR. Note when a parser or schema change makes existing indexes produce wrong results so the separate release PR can bump IndexVersion alongside Version. The LSP server checks this on startup and, on a mismatch, triggers a forced rebuild of a populated index. An empty index is left to the background full build, which stamps the current version itself — so a bump is not a way to force anything to happen on a store that has no rows.

What to check when making changes

Token walking

Use parser.TokenWalker for new code that iterates over tokens. It provides:

• Consistent depth tracking with automatic clamping (never goes negative)
• Forward progress guarantees via EnsureProgress()
• Module/function detection helpers
• Statement boundary handling

See internal/parser/token_walker.go for the API and token_walk_test.go for examples.

The consistency tests in elixir_test.go (TestModuleScopeConsistency, TestDepthTrackingConsistency) verify that similar functions handle edge cases the same way. Add new edge cases there when fixing scope-related bugs.

Common gotchas

• Nested modules: defmodule Inner do inside Outer creates Outer.Inner in the store but the raw line only says Inner. Use LookupModulesInFile / LookupEnclosingModule rather than regex-scanning lines for module names.
• as: aliases: alias Foo.Bar, as: Baz — Baz ≠ last segment of Foo.Bar. Detected in PrepareRename by comparing the alias short name to moduleLastSegment(resolved).
• Import-only sites in rename: Lines like import Module, only: [fn: 1] have the function name as a keyword key. They're flagged includeKeyword: true so buildTextEdits uses findAllTokenColumns instead of findFunctionTokenColumns.
• Dynamic use-chain imports: import unquote(mod) goes into optBindings, not imports. Static findModulesWhoseUsingImports won't find these — the fast opt-binding path in the References handler handles them instead.
• ExUnit.CaseTemplate: Uses using opts do instead of defmacro __using__. Only recognised when the module has use ExUnit.CaseTemplate. The body may delegate to a helper function (using_block(opts)) — parseHelperQuoteBlock follows this.
• Performance: findModulesWhoseUsingImports is expensive (~30-65ms). The References handler skips it when the fast opt-binding check already found injectors.
• A session is not a process: one daemon serves every editor and CLI client on a workspace, so nothing on a path shared with daemon-backed sessions may call os.Exit. Server.Exit closes the stream instead when manageWorkspace is false (every daemon session); Shutdown and disconnects go through CloseSession, which is sync.Once-guarded. The embedded manageWorkspace path exists for tests and library use only — the CLI never selects it, because one workspace has one owner
• Session state stays per-session, index state stays shared: open documents, client capabilities, and position encoding belong to one Server; the store, IndexCoordinator, watchers, and caches belong to the workspace.Runtime. A new field on Server is a new per-editor copy unless it deliberately goes on the coordinator.
• Daemon-backed sessions do not manage the workspace: with ManageWorkspace: false, Initialize starts no reindex and no .git/HEAD poll — the runtime does both. It still registers didChangeWatchedFiles, because the editor's glob covers deps/ and path dependencies that the native watcher deliberately skips; duplicate events from both sources coalesce by path. Editor notifications are routed through WorkspaceEvents into the one mutation queue rather than written to the index directly.
• A workspace has to look like one: init, reindex, lookup, and references refuse a directory with no mix.exs, .git, or Dexter database unless -y/--yes is passed, so a mistyped command cannot build an index over the home directory. lsp warns and serves anyway (the editor decides), and stop never checks, so a stray daemon can always be cleaned up