Skip to content

Commit 5644db7

Browse files
claudeclaude
committed
Add comprehensive CLAUDE.md documentation
0 parents  commit 5644db7

1 file changed

Lines changed: 211 additions & 0 deletions

File tree

‎CLAUDE.md‎

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
# CLAUDE.md - Universal Language Server Plugin
2+
3+
## Project Overview
4+
5+
This is a **Universal Language Server Plugin** project that aims to provide a flexible and extensible language server implementation that can support multiple programming languages through a plugin architecture.
6+
7+
### Purpose
8+
9+
The plugin enables IDE features such as:
10+
- Code completion and IntelliSense
11+
- Go to definition and references
12+
- Diagnostics and linting
13+
- Code formatting and refactoring
14+
- Hover information and documentation
15+
- Syntax highlighting
16+
17+
## Project Structure
18+
19+
```
20+
universal-language-server-plugin/
21+
├── src/ # Source code
22+
│ ├── core/ # Core language server functionality
23+
│ ├── plugins/ # Language-specific plugin implementations
24+
│ ├── protocol/ # LSP protocol implementation
25+
│ ├── utils/ # Utility functions and helpers
26+
│ └── index.ts # Main entry point
27+
├── tests/ # Test files
28+
├── docs/ # Documentation
29+
├── examples/ # Example configurations and plugins
30+
└── package.json # Project dependencies and scripts
31+
```
32+
33+
## Development Guidelines
34+
35+
### Technology Stack
36+
37+
- **Language**: TypeScript (for type safety and better tooling)
38+
- **Runtime**: Node.js
39+
- **Protocol**: Language Server Protocol (LSP)
40+
- **Testing**: Jest or Vitest
41+
- **Build**: ESBuild or TSC
42+
43+
### Code Style
44+
45+
- Use TypeScript strict mode
46+
- Follow functional programming principles where appropriate
47+
- Prefer composition over inheritance
48+
- Use descriptive variable and function names
49+
- Write comprehensive JSDoc comments for public APIs
50+
- Keep functions small and focused (single responsibility)
51+
52+
### Key Concepts
53+
54+
1. **Plugin Architecture**: Each language should be implemented as a separate plugin
55+
2. **LSP Compliance**: Strictly follow the Language Server Protocol specification
56+
3. **Async Operations**: Use async/await for all I/O operations
57+
4. **Error Handling**: Implement robust error handling with detailed error messages
58+
5. **Performance**: Optimize for fast response times, especially for completion requests
59+
60+
### Testing
61+
62+
- Write unit tests for core functionality
63+
- Write integration tests for plugin implementations
64+
- Aim for >80% code coverage
65+
- Test edge cases and error conditions
66+
- Mock external dependencies
67+
68+
### Plugin Development
69+
70+
When creating a new language plugin:
71+
72+
1. Implement the `LanguagePlugin` interface
73+
2. Register language-specific features (completion, diagnostics, etc.)
74+
3. Handle language-specific parsing and analysis
75+
4. Provide configuration options
76+
5. Include comprehensive tests
77+
78+
Example plugin structure:
79+
```typescript
80+
interface LanguagePlugin {
81+
name: string;
82+
languages: string[];
83+
initialize(): Promise<void>;
84+
getCompletions(params: CompletionParams): Promise<CompletionItem[]>;
85+
getDiagnostics(params: DocumentDiagnosticParams): Promise<Diagnostic[]>;
86+
// ... other LSP methods
87+
}
88+
```
89+
90+
## Common Tasks
91+
92+
### Adding a New Language Plugin
93+
94+
1. Create a new file in `src/plugins/<language>/`
95+
2. Implement the `LanguagePlugin` interface
96+
3. Register the plugin in the plugin registry
97+
4. Add configuration schema
98+
5. Write tests in `tests/plugins/<language>/`
99+
6. Update documentation
100+
101+
### Implementing LSP Features
102+
103+
- Follow the official LSP specification: https://microsoft.github.io/language-server-protocol/
104+
- Use the `vscode-languageserver` npm package for protocol handling
105+
- Implement capabilities progressively (start with basic features)
106+
- Test with multiple LSP clients (VS Code, Neovim, Emacs)
107+
108+
### Performance Optimization
109+
110+
- Use incremental parsing for document updates
111+
- Implement caching for expensive operations
112+
- Debounce/throttle diagnostic requests
113+
- Profile and benchmark critical code paths
114+
- Consider using worker threads for CPU-intensive tasks
115+
116+
## Dependencies
117+
118+
### Core Dependencies
119+
- `vscode-languageserver`: LSP protocol implementation
120+
- `vscode-languageserver-textdocument`: Document management
121+
- Language-specific parsers (tree-sitter, etc.)
122+
123+
### Development Dependencies
124+
- TypeScript
125+
- Testing framework (Jest/Vitest)
126+
- ESLint for linting
127+
- Prettier for formatting
128+
129+
## Configuration
130+
131+
The plugin should support configuration through:
132+
- `.universal-lsp.json` in project root
133+
- LSP initialization options
134+
- Environment variables
135+
136+
Example configuration:
137+
```json
138+
{
139+
"plugins": ["javascript", "python", "rust"],
140+
"diagnostics": {
141+
"enabled": true,
142+
"debounce": 500
143+
},
144+
"completion": {
145+
"triggerCharacters": [".", ":", ">"]
146+
}
147+
}
148+
```
149+
150+
## Architecture Decisions
151+
152+
### Why Plugin-Based?
153+
- Allows incremental language support
154+
- Keeps core lightweight
155+
- Enables community contributions
156+
- Facilitates testing and maintenance
157+
158+
### Why TypeScript?
159+
- Type safety reduces runtime errors
160+
- Better IDE support and autocomplete
161+
- Self-documenting code
162+
- Easier refactoring
163+
164+
### Why LSP?
165+
- Industry standard protocol
166+
- Works with multiple editors
167+
- Well-documented specification
168+
- Large ecosystem of tools
169+
170+
## Error Handling
171+
172+
- Use custom error classes for different error types
173+
- Log errors with appropriate severity levels
174+
- Return meaningful error messages to the client
175+
- Never crash the language server
176+
- Implement graceful degradation
177+
178+
## Security Considerations
179+
180+
- Validate all input from clients
181+
- Sandbox plugin execution if possible
182+
- Limit file system access
183+
- Be cautious with code execution
184+
- Validate configuration files
185+
186+
## Contributing
187+
188+
When contributing:
189+
1. Fork the repository
190+
2. Create a feature branch
191+
3. Write tests for new features
192+
4. Ensure all tests pass
193+
5. Update documentation
194+
6. Submit a pull request
195+
196+
## Resources
197+
198+
- [LSP Specification](https://microsoft.github.io/language-server-protocol/)
199+
- [VS Code Extension API](https://code.visualstudio.com/api)
200+
- [Tree-sitter](https://tree-sitter.github.io/tree-sitter/)
201+
- [Language Server Protocol SDK](https://github.com/Microsoft/language-server-protocol)
202+
203+
## Notes for Claude
204+
205+
- When implementing features, always consider LSP compatibility
206+
- Prioritize performance and responsiveness
207+
- Write clear, maintainable code
208+
- Test thoroughly before committing
209+
- Follow existing patterns in the codebase
210+
- Document complex logic with comments
211+
- Consider backward compatibility when making changes

0 commit comments

Comments
 (0)