Skip to content

Commit ab300da

Browse files
Copilotbaronfel
Copilot
and
baronfel
committed
Add comprehensive Copilot instructions for FsAutoComplete
Co-authored-by: baronfel <[email protected]>
1 parent 275cc92 commit ab300da

File tree

1 file changed

+191
-0
lines changed

1 file changed

+191
-0
lines changed

‎.copilot/instructions.md‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
# FsAutoComplete Copilot Instructions
2+
3+
## Project Overview
4+
5+
FsAutoComplete (FSAC) is a Language Server Protocol (LSP) backend service that provides rich editing and intellisense features for F# development. It serves as the core engine behind F# support in various editors including Visual Studio Code (Ionide), Emacs, Neovim, Vim, Sublime Text, and Zed.
6+
7+
## Architecture
8+
9+
### Core Components
10+
11+
- **FsAutoComplete.Core**: Contains the core functionality, including:
12+
- F# compiler service interfaces
13+
- Code generation and refactoring utilities
14+
- Symbol resolution and type checking
15+
- Signature formatting and documentation
16+
- File system abstractions
17+
18+
- **FsAutoComplete**: Main LSP server implementation with:
19+
- LSP protocol handlers and endpoints
20+
- Code fixes and quick actions
21+
- Parser for LSP requests/responses
22+
- Program entry point
23+
24+
- **FsAutoComplete.Logging**: Centralized logging infrastructure
25+
26+
### Key Dependencies
27+
28+
- **FSharp.Compiler.Service**: Core F# compiler APIs for language analysis
29+
- **Ionide.ProjInfo**: Project and solution file parsing
30+
- **FSharpLint**: Code linting and static analysis
31+
- **Fantomas**: F# code formatting
32+
- **Language Server Protocol**: Communication with editors
33+
34+
## Development Workflow
35+
36+
### Building the Project
37+
38+
```bash
39+
# Restore .NET tools (including Paket)
40+
dotnet tool restore
41+
42+
# Build the entire solution
43+
dotnet build
44+
45+
# Run tests
46+
dotnet test
47+
```
48+
49+
### Project Dependencies
50+
51+
This project uses **Paket** for dependency management instead of NuGet directly:
52+
- Dependencies are declared in `paket.dependencies`
53+
- Lock file is `paket.lock`
54+
- Each project has its own `paket.references` file
55+
56+
### Code Organization
57+
58+
#### Code Fixes
59+
- Located in `src/FsAutoComplete/CodeFixes/`
60+
- Each code fix is typically a separate F# module
61+
- Follow the pattern: analyze issue → generate fix → apply transformation
62+
- Use the `build.fsx` script's `ScaffoldCodeFix` module to create new code fixes
63+
64+
#### LSP Endpoints
65+
- Standard LSP endpoints in `src/FsAutoComplete/LspServers/`
66+
- Custom F#-specific endpoints prefixed with `fsharp/`
67+
- Request/response types in `CommandResponse.fs`
68+
69+
#### Testing
70+
- Main test suite in `test/FsAutoComplete.Tests.Lsp/`
71+
- Tests organized by feature area (CompletionTests, CodeFixTests, etc.)
72+
- Uses F# testing frameworks with custom helpers in `Helpers.fs`
73+
- Test cases often in `TestCases/` subdirectories
74+
75+
## F# Language Conventions
76+
77+
### Coding Style
78+
- Follow F# community conventions
79+
- Use `fantomas` for code formatting (configured in the project)
80+
- Prefer immutable data structures and functional programming patterns
81+
- Use explicit type annotations where they improve clarity
82+
83+
### Module Organization
84+
- One primary type/feature per file
85+
- Use `.fs` and `.fsi` pairs for public APIs
86+
- Organize related functionality into modules
87+
- Follow naming conventions: `CamelCase` for types, `camelCase` for values
88+
89+
### Error Handling
90+
- Use F# Result types for error handling where appropriate
91+
- Use FsToolkit.ErrorHandling for railway-oriented programming
92+
- Prefer explicit error types over generic exceptions
93+
94+
## LSP Implementation Details
95+
96+
### Supported Standard LSP Features
97+
- `textDocument/completion` with `completionItem/resolve`
98+
- `textDocument/hover`, `textDocument/definition`, `textDocument/references`
99+
- `textDocument/codeAction`, `textDocument/codeLens`
100+
- `textDocument/formatting` (via Fantomas)
101+
- `textDocument/rename`, `textDocument/signatureHelp`
102+
- Workspace management and file watching
103+
104+
### Custom F# Extensions
105+
- `fsharp/signature`: Get formatted signature at position
106+
- `fsharp/compile`: Compile project and return diagnostics
107+
- `fsharp/workspacePeek`: Discover available projects/solutions
108+
- `fsproj/addFile`, `fsproj/removeFile`: Project file manipulation
109+
110+
## Testing Guidelines
111+
112+
### Test Structure
113+
- Tests are organized by feature area
114+
- Use descriptive test names that explain the scenario
115+
- Include both positive and negative test cases
116+
- Test with realistic F# code examples
117+
118+
### Adding New Tests
119+
1. Identify the appropriate test file (e.g., `CompletionTests.fs` for completion features)
120+
2. Follow existing patterns for test setup and assertions
121+
3. Use the helpers in `Helpers.fs` for common operations
122+
4. Include edge cases and error conditions
123+
124+
### Test Data
125+
- Sample F# projects in `TestCases/` directories
126+
- Use minimal, focused examples that demonstrate specific features
127+
- Avoid overly complex test scenarios that are hard to debug
128+
129+
## Performance Considerations
130+
131+
### Memory Management
132+
- Be mindful of memory usage in long-running language server scenarios
133+
- Dispose of compiler service resources appropriately
134+
- Use caching judiciously to balance performance and memory
135+
136+
### Responsiveness
137+
- LSP operations should be fast and non-blocking
138+
- Use async/await patterns for I/O operations
139+
- Consider cancellation tokens for long-running operations
140+
141+
## Debugging and Telemetry
142+
143+
### OpenTelemetry Integration
144+
- Tracing is available with `--otel-exporter-enabled` flag
145+
- Use Jaeger for trace visualization during development
146+
- Activity tracing helps debug performance issues
147+
148+
### Logging
149+
- Structured logging via Serilog
150+
- Use appropriate log levels (Debug, Info, Warning, Error)
151+
- Include relevant context in log messages
152+
153+
## Common Patterns
154+
155+
### Working with FCS (F# Compiler Service)
156+
- Always work with `FSharpCheckFileResults` and `FSharpParseFileResults`
157+
- Handle both parsed and typed ASTs appropriately
158+
- Be aware of file dependencies and project context
159+
160+
### LSP Request Handling
161+
- Validate input parameters
162+
- Handle exceptions gracefully
163+
- Return appropriate error responses for invalid requests
164+
- Use proper JSON serialization
165+
166+
### Code Generation
167+
- Use the F# AST utilities in `TypedAstUtils.fs` and `UntypedAstUtils.fs`
168+
- Consider both syntactic and semantic correctness
169+
- Test generated code compiles and has expected behavior
170+
171+
## Contributing Guidelines
172+
173+
### Before Submitting Changes
174+
1. Ensure all tests pass: `dotnet test`
175+
2. Run code formatting: `dotnet fantomas src/ test/`
176+
3. Verify the solution builds cleanly
177+
4. Test your changes with a real F# project if possible
178+
179+
### Code Review Focus Areas
180+
- Correctness of F# language analysis
181+
- Performance impact on language server operations
182+
- Compatibility with different F# project types
183+
- LSP protocol compliance
184+
- Test coverage for new features
185+
186+
## Resources
187+
188+
- [LSP Specification](https://microsoft.github.io/language-server-protocol/)
189+
- [F# Compiler Service Documentation](https://fsharp.github.io/FSharp.Compiler.Service/)
190+
- [F# Style Guide](https://docs.microsoft.com/en-us/dotnet/fsharp/style-guide/)
191+
- [Creating a New Code Fix Guide](./docs/Creating%20a%20new%20code%20fix.md)

0 commit comments

Comments
 (0)