Skip to content

Commit b0172c8

Browse files
lukaszsamsonlukaszsamson
committed
Merge branch 'mcp-fun'
2 parents b8850fc + 9a16d46 commit b0172c8

13 files changed

+1899
-0
lines changed

‎.claude/settings.local.json

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"permissions": {
3+
"allow": [
4+
"Bash(find:*)",
5+
"WebFetch(domain:code.visualstudio.com)",
6+
"Bash(rg:*)",
7+
"Bash(npm run compile:*)",
8+
"Bash(mix compile)"
9+
],
10+
"deny": []
11+
}
12+
}

‎CLAUDE.md

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
This is the Visual Studio Code extension for ElixirLS (Elixir Language Server). It consists of two main parts:
8+
1. **VS Code Extension** (TypeScript/Node.js) - manages VS Code integration and spawns ElixirLS processes
9+
2. **ElixirLS** (Elixir) - implements Language Server Protocol (LSP) and Debug Adapter Protocol (DAP)
10+
11+
## Essential Commands
12+
13+
### Building the Project
14+
15+
```bash
16+
# Install VS Code extension dependencies
17+
npm install
18+
19+
# Compile TypeScript
20+
npm run compile
21+
22+
# Build ElixirLS
23+
cd elixir-ls
24+
mix deps.get
25+
MIX_ENV=prod mix compile
26+
27+
# Full build for release
28+
npm run vscode:prepublish
29+
```
30+
31+
### Running Tests
32+
33+
```bash
34+
# VS Code extension tests
35+
npm test
36+
37+
# ElixirLS tests
38+
cd elixir-ls
39+
mix test
40+
41+
# Run specific test file
42+
mix test test/diagnostics_test.exs
43+
44+
# Run specific test line
45+
mix test test/diagnostics_test.exs:42
46+
47+
# Test specific app
48+
cd apps/language_server && mix test
49+
```
50+
51+
### Code Quality
52+
53+
```bash
54+
# TypeScript linting/formatting (uses Biome)
55+
npm run lint
56+
npm run fix-formatting
57+
58+
# Elixir formatting
59+
cd elixir-ls
60+
mix format
61+
mix format --check # Check without changing
62+
63+
# Type checking
64+
mix dialyzer
65+
```
66+
67+
### Development
68+
69+
```bash
70+
# Launch extension development host (press F5 in VS Code)
71+
# Or manually:
72+
code --extensionDevelopmentPath=.
73+
74+
# Watch TypeScript changes
75+
npm run watch
76+
```
77+
78+
## Architecture
79+
80+
### Directory Structure
81+
- `/src/` - VS Code extension TypeScript source
82+
- `/elixir-ls/` - Git submodule containing ElixirLS
83+
- `/apps/language_server/` - Language server implementation
84+
- `/apps/debug_adapter/` - Debug adapter implementation
85+
- `/apps/elixir_ls_utils/` - Shared utilities
86+
- `/syntaxes/` - TextMate grammars for syntax highlighting
87+
88+
### Communication Flow
89+
1. VS Code extension spawns ElixirLS processes via launch scripts
90+
2. Communication happens over stdio using JSON-RPC
91+
3. Language server handles LSP requests (completion, diagnostics, etc.)
92+
4. Debug adapter handles DAP requests (breakpoints, stepping, etc.)
93+
94+
### Key Extension Components
95+
- `src/extension.ts` - Extension entry point
96+
- `src/vscode-elixir-ls-client.ts` - Language client implementation
97+
- `src/commands.ts` - VS Code command implementations
98+
- `src/task-provider.ts` - Mix task integration
99+
- `src/test-controller.ts` - Test Explorer integration
100+
101+
### Key ElixirLS Components
102+
- `apps/language_server/lib/language_server.ex` - LSP server entry
103+
- `apps/language_server/lib/language_server/server.ex` - Request handling
104+
- `apps/language_server/lib/language_server/providers/` - Feature providers
105+
- `apps/debug_adapter/lib/debug_adapter.ex` - DAP server entry
106+
107+
## Important Notes
108+
109+
- ElixirLS is a git submodule - remember to initialize/update it
110+
- Tests on Linux require xvfb: `xvfb-run -a npm test`
111+
- The extension spawns Erlang/Elixir processes - ensure proper cleanup
112+
- Launch scripts in `elixir-ls/scripts/` handle environment setup
113+
- Both LSP and DAP use stdio for communication, not TCP/IP

‎IDEAS.md

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
# Language Tool Ideas for ElixirLS
2+
3+
## Overview
4+
These are language tool ideas that would be particularly useful for LLMs working with Elixir codebases. The focus is on information that is difficult to obtain via command-line tools but readily available through the language server's compiled beam files and AST analysis.
5+
6+
## High-Priority Tools
7+
8+
### 1. **Module Dependency Graph Tool**
9+
**Problem**: LLMs struggle to understand complex module relationships, especially with aliases, imports, and use statements.
10+
**Solution**: Return a graph of module dependencies showing:
11+
- Which modules a given module depends on
12+
- Which modules depend on a given module
13+
- Transitive dependencies
14+
- Alias mappings in context
15+
16+
### 2. **Behaviour Implementation Finder**
17+
**Problem**: Finding all modules that implement a specific behaviour requires searching through entire codebases.
18+
**Solution**: Given a behaviour module (e.g., `GenServer`), return all modules that implement it with:
19+
- Module name and location
20+
- Which callbacks are implemented
21+
- Which callbacks are missing/using defaults
22+
23+
### 3. **Function Call Hierarchy Tool**
24+
**Problem**: Understanding which functions call a given function is nearly impossible via CLI.
25+
**Solution**: Provide bidirectional call information:
26+
- All callers of a function
27+
- All functions called by a function
28+
- Call sites with line numbers
29+
- Distinguishes between local and remote calls
30+
31+
### 4. **Type Information Extractor**
32+
**Problem**: Getting complete type information including specs, types, and Dialyzer inferences.
33+
**Solution**: For a given function/module, return:
34+
- @spec definitions
35+
- @type definitions
36+
- Dialyzer's inferred types
37+
- Parameter names with their types
38+
- Return type information
39+
40+
### 5. **OTP Supervision Tree Analyzer**
41+
**Problem**: Understanding GenServer/Supervisor relationships in running systems.
42+
**Solution**: Extract and visualize:
43+
- Supervisor hierarchy
44+
- Child specifications
45+
- Restart strategies
46+
- Process registration names
47+
- GenServer state structure
48+
49+
## Medium-Priority Tools
50+
51+
### 6. **Protocol Implementation Finder**
52+
**Problem**: Finding all implementations of a protocol across the codebase.
53+
**Solution**: Given a protocol, return:
54+
- All implementing modules
55+
- Implementation details
56+
- Consolidated status
57+
58+
### 7. **Compile-Time Dependency Analyzer**
59+
**Problem**: Understanding what will trigger recompilation.
60+
**Solution**: Show:
61+
- Compile-time dependencies between modules
62+
- Runtime-only dependencies
63+
- Modules that will recompile if a given module changes
64+
65+
### 8. **Mix Task Inspector**
66+
**Problem**: Discovering and understanding project-specific Mix tasks.
67+
**Solution**: List all available Mix tasks with:
68+
- Task name and module
69+
- Documentation
70+
- Required arguments
71+
- Task dependencies
72+
73+
### 9. **Module Documentation Aggregator**
74+
**Problem**: Getting comprehensive documentation beyond just function docs.
75+
**Solution**: Extract:
76+
- @moduledoc
77+
- All @doc entries
78+
- @typedoc entries
79+
- Examples from docs
80+
- Related modules mentioned in docs
81+
82+
### 10. **Function Arity Explorer**
83+
**Problem**: Understanding all versions of overloaded functions.
84+
**Solution**: Given a function name, return:
85+
- All arities with their specs
86+
- Default arguments expansion
87+
- Clause patterns
88+
- Guard conditions
89+
90+
## Lower-Priority Tools
91+
92+
### 11. **Test Coverage Mapper**
93+
**Problem**: Understanding which tests cover specific functions.
94+
**Solution**: Map between:
95+
- Functions and their test files
96+
- Test names that exercise specific code
97+
- Uncovered functions
98+
99+
### 12. **Message Flow Tracer**
100+
**Problem**: Understanding inter-process communication.
101+
**Solution**: Analyze:
102+
- send/receive patterns
103+
- GenServer call/cast usage
104+
- Message types between processes
105+
106+
### 13. **Configuration Explorer**
107+
**Problem**: Understanding application configuration.
108+
**Solution**: Extract:
109+
- Config values for all environments
110+
- Config dependencies
111+
- Runtime vs compile-time config
112+
113+
### 14. **Macro Usage Analyzer**
114+
**Problem**: Understanding where and how macros are used.
115+
**Solution**: For a given macro:
116+
- All usage sites
117+
- Expanded forms at each site
118+
- Import/require chains
119+
120+
## Implementation Considerations
121+
122+
### Advantages of Language Server Implementation:
123+
1. **Already compiled code**: Access to beam files with debug info
124+
2. **AST availability**: Parsed and analyzed code ready for querying
125+
3. **Incremental updates**: Changes tracked in real-time
126+
4. **Cross-reference data**: Xref information already maintained
127+
5. **Type information**: Dialyzer PLTs already built
128+
129+
### Why These Are Hard via CLI:
130+
1. Would require repeated compilation/parsing
131+
2. No persistent state between queries
132+
3. Complex grep patterns miss context
133+
4. No semantic understanding
134+
5. Can't follow compile-time transformations
135+
136+
### Priority Rationale:
137+
- **High**: Fundamental to understanding code structure
138+
- **Medium**: Useful for specific tasks but not always needed
139+
- **Lower**: Nice to have but can be worked around
140+
141+
## Next Steps
142+
1. Start with Module Dependency Graph as it provides the most value
143+
2. Implement Type Information Extractor to help with code generation
144+
3. Add Function Call Hierarchy for refactoring support
145+
4. Build on existing ElixirLS infrastructure (e.g., Xref, Dialyzer integration)

‎LLM_DEFINITION_TOOL.md

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# LLM Definition Tool for ElixirLS
2+
3+
This feature adds a VS Code language model tool that allows LLMs to look up Elixir symbol definitions and retrieve their source code.
4+
5+
## Implementation Overview
6+
7+
### VS Code Extension (TypeScript)
8+
- **package.json**: Registers the `elixir-definition` language model tool
9+
- **src/definition-tool.ts**: Implements the `DefinitionTool` class that handles tool invocations
10+
- **src/extension.ts**: Registers the tool when language clients are ready
11+
12+
### ElixirLS Language Server (Elixir)
13+
- **execute_command.ex**: Added `llmDefinition` to the command handlers
14+
- **llm_definition.ex**: Implements the command handler that:
15+
- Parses symbol strings (e.g., "MyModule", "MyModule.function", "MyModule.function/2")
16+
- Locates definitions using the existing `Location.find_mod_fun_source/3`
17+
- Uses the Location's range (start_line, start_column, end_line, end_column) to extract the exact definition text
18+
- Extracts additional context like @doc and @spec attributes before the definition
19+
- Returns formatted source with file location information
20+
21+
## Usage
22+
23+
The tool can be invoked by LLMs with symbol names in various formats:
24+
- Module: `"MyModule"` or `"MyModule.SubModule"`
25+
- Function: `"MyModule.my_function"` or `"MyModule.my_function/2"`
26+
- Erlang module: `":erlang"` or `":ets"`
27+
28+
## Example Response
29+
30+
```elixir
31+
# Definition found in /path/to/file.ex:42
32+
33+
@doc """
34+
Documentation for the function
35+
"""
36+
@spec my_function(term()) :: {:ok, term()} | {:error, String.t()}
37+
def my_function(arg) do
38+
# Implementation
39+
end
40+
```
41+
42+
## Testing
43+
44+
To test the implementation:
45+
1. Build the extension: `npm run compile && npm run vscode:prepublish`
46+
2. Launch VS Code with the extension
47+
3. Open an Elixir project
48+
4. Use GitHub Copilot or another LLM that supports language tools
49+
5. Reference the tool with `@elixir-definition` and provide a symbol name
50+
51+
## Future Enhancements
52+
53+
- Support for more symbol types (macros, structs, protocols)
54+
- Include @doc and @spec in all cases
55+
- Better handling of multi-clause functions
56+
- Support for finding references/usages
57+
- Caching for improved performance

0 commit comments

Comments
 (0)