Skip to content

Commit 167319e

Browse files
coder3101coder3101
authored
Merge branch 'main' into copilot/fix-90
2 parents 8118090 + 9c47359 commit 167319e

File tree

1 file changed

+205
-0
lines changed

1 file changed

+205
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
# Protols - Protocol Buffers Language Server
2+
3+
Protols is an open-source Language Server Protocol (LSP) implementation for Protocol Buffers (proto) files, written in Rust. It provides intelligent code assistance for protobuf development, including auto-completion, diagnostics, formatting, go-to-definition, hover information, and more.
4+
5+
Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
6+
7+
## Working Effectively
8+
9+
### Bootstrap and Build
10+
- Install dependencies and build the project:
11+
- Rust toolchain is already available (cargo 1.89.0, rustc 1.89.0)
12+
- Install protoc: `sudo apt update && sudo apt install -y protobuf-compiler` -- takes 2-3 minutes. NEVER CANCEL. Installs libprotoc 3.21.12.
13+
- clang-format is already installed and available at `/usr/bin/clang-format` (Ubuntu clang-format version 18.1.3)
14+
- `cargo build --verbose` -- takes about 1 minute to complete. NEVER CANCEL. Set timeout to 90+ minutes for safety.
15+
- `cargo test --verbose` -- takes about 6 seconds, runs 22 tests. NEVER CANCEL. Set timeout to 30+ minutes.
16+
17+
### Essential Commands
18+
- Check code formatting: `cargo fmt --check` -- takes under 1 second
19+
- Run linter: `cargo clippy` -- takes about 15 seconds. NEVER CANCEL. Set timeout to 30+ minutes.
20+
- Run the binary: `./target/debug/protols --help` or `./target/debug/protols --version`
21+
- Build release version: `cargo build --release` -- takes about 1 minute. NEVER CANCEL. Set timeout to 90+ minutes.
22+
- Test specific functionality: `cargo test <test_name>` for individual tests
23+
24+
### External Dependencies Verification
25+
- **protoc (Protocol Buffers Compiler)**: Required for advanced diagnostics. Install with `sudo apt install -y protobuf-compiler`. Verify with `protoc --version`.
26+
- **clang-format**: Required for code formatting. Already available. Verify with `clang-format --version`.
27+
28+
## Validation and Testing
29+
30+
### Manual Validation Scenarios
31+
After making changes to the LSP functionality, ALWAYS test these scenarios:
32+
33+
1. **Basic Build and Test Validation**:
34+
- `cargo build` -- should complete in ~1 minute without errors
35+
- `cargo test --verbose` -- should pass all 22 tests in ~6 seconds
36+
- `cargo fmt --check` -- should pass formatting check
37+
- `cargo clippy` -- should pass linting with no warnings
38+
- `./target/debug/protols --help` -- should show help message
39+
- `./target/debug/protols --version` -- should show version 0.12.8
40+
41+
2. **External Dependencies Validation**:
42+
- `protoc --version` -- should show libprotoc 3.21.12
43+
- `clang-format --version` -- should show Ubuntu clang-format version 18.1.3
44+
- Test protoc with sample file: `protoc sample/simple.proto --descriptor_set_out=/tmp/test.desc`
45+
- Test clang-format with sample file: `clang-format sample/simple.proto`
46+
47+
3. **LSP Functionality Testing**:
48+
- Test specific LSP features: `cargo test parser::hover::test::test_hover`
49+
- Test workspace functionality: `cargo test workspace`
50+
- Test with include paths: `./target/debug/protols --include-paths=/tmp,/home` (will start LSP server)
51+
- Verify LSP server starts correctly (shows logging directory and waits for input)
52+
53+
4. **Sample File Validation**:
54+
- Ensure sample proto files in `/sample/` directory are valid
55+
- Test parsing with `sample/simple.proto`, `sample/everything.proto`, `sample/test.proto`
56+
- Verify protoc can process sample files without errors
57+
58+
### CRITICAL Build and Test Timing
59+
- **NEVER CANCEL builds or tests** - they may take longer than expected
60+
- **cargo build**: 1 minute typical, set timeout to 90+ minutes
61+
- **cargo test**: 6 seconds typical, set timeout to 30+ minutes
62+
- **cargo clippy**: 15 seconds typical, set timeout to 30+ minutes
63+
- **External dependency installation**: 2-3 minutes, set timeout to 30+ minutes
64+
65+
### CI Validation Requirements
66+
Always run these commands before committing changes:
67+
- `cargo fmt --check` -- validates code formatting
68+
- `cargo clippy` -- validates code quality and catches common issues
69+
- `cargo test --verbose` -- runs full test suite
70+
- `cargo build --release` -- ensures release build works
71+
72+
## Key Project Structure
73+
74+
### Root Directory
75+
```
76+
├── Cargo.toml # Main project configuration
77+
├── Cargo.lock # Dependency lock file
78+
├── README.md # Project documentation
79+
├── protols.toml # LSP configuration file
80+
├── .clang-format # Formatting configuration for proto files
81+
├── src/ # Main source code
82+
├── sample/ # Sample proto files for testing
83+
└── .github/workflows/ # CI/CD pipelines
84+
```
85+
86+
### Important Source Files
87+
- `src/main.rs` - Entry point, command-line argument parsing, LSP server setup
88+
- `src/server.rs` - Core LSP server implementation
89+
- `src/lsp.rs` - LSP message handling and protocol implementation
90+
- `src/parser/` - Tree-sitter based proto file parsing
91+
- `src/formatter/` - Code formatting using clang-format
92+
- `src/workspace/` - Workspace and multi-file support
93+
- `src/config/` - Configuration management
94+
95+
### Key Features to Test
96+
When modifying functionality, always validate:
97+
- **Code Completion**: Auto-complete messages, enums, keywords
98+
- **Diagnostics**: Syntax errors from tree-sitter and protoc
99+
- **Document Symbols**: Navigate symbols in proto files
100+
- **Code Formatting**: Format proto files using clang-format
101+
- **Go to Definition**: Jump to symbol definitions
102+
- **Hover Information**: Documentation on hover
103+
- **Rename Symbols**: Rename and propagate changes
104+
- **Find References**: Find symbol usage across files
105+
106+
## Configuration Details
107+
108+
### protols.toml Example
109+
```toml
110+
[config]
111+
include_paths = ["src/workspace/input"]
112+
113+
[config.path]
114+
clang_format = "clang-format"
115+
protoc = "protoc"
116+
```
117+
118+
### Command Line Options
119+
- `-i, --include-paths <PATHS>`: Comma-separated include paths for proto files
120+
- `-V, --version`: Print version information
121+
- `-h, --help`: Print help information
122+
123+
## Common Development Tasks
124+
125+
### Common Development Tasks
126+
127+
### Adding New Features
128+
1. Write tests first in appropriate `src/*/test/` directories or `src/*/input/` test data
129+
2. Implement feature in relevant module (`src/parser/`, `src/workspace/`, `src/formatter/`, etc.)
130+
3. Update LSP message handlers in `src/lsp.rs` if needed
131+
4. Test with sample proto files in `sample/` directory
132+
5. Run all validation commands before committing
133+
134+
### Debugging Issues
135+
- Check logs in system temp directory (output shows location on startup: "file logging at directory: /tmp")
136+
- Use `cargo test <module_name>` to run specific test modules
137+
- Use `cargo test <test_name> --verbose` for detailed test output
138+
- Test with sample files: `sample/simple.proto`, `sample/everything.proto`, `sample/test.proto`
139+
- Test files available in `src/parser/input/` and `src/workspace/input/` for unit tests
140+
- Verify external dependencies: `protoc --version`, `clang-format --version`
141+
142+
### Working with Proto Files
143+
- Sample files available in `sample/` directory for testing
144+
- Test input files in `src/parser/input/test_*.proto` for specific functionality
145+
- Test workspace files in `src/workspace/input/` for multi-file scenarios
146+
- Always test with various proto3 syntax features: messages, enums, services, imports
147+
- Use `protoc <file.proto> --descriptor_set_out=/tmp/test.desc` to validate proto syntax
148+
149+
### Performance and Timing Expectations
150+
- Small project: ~1400 lines of Rust code
151+
- Fast incremental builds after first build
152+
- Test suite is comprehensive but fast (22 tests in 6 seconds)
153+
- LSP server starts quickly but will wait for client input (normal behavior)
154+
155+
## Environment Notes
156+
- This is a Rust project using edition 2024
157+
- Uses tree-sitter for parsing proto files
158+
- Integrates with external tools (protoc, clang-format) for enhanced functionality
159+
- Logging goes to system temp directory with daily rotation
160+
- Supports both Unix pipes and fallback I/O for cross-platform compatibility
161+
162+
## Common Command Outputs (for reference)
163+
164+
### Repository Structure
165+
```
166+
├── Cargo.toml # Main project configuration
167+
├── Cargo.lock # Dependency lock file
168+
├── README.md # Project documentation
169+
├── protols.toml # LSP configuration file
170+
├── .clang-format # Formatting configuration for proto files
171+
├── LICENSE # MIT license
172+
├── .gitignore # Git ignore rules
173+
├── src/ # Main source code (~1400 lines)
174+
│ ├── main.rs # Entry point (3956 bytes)
175+
│ ├── lsp.rs # LSP implementation (19116 bytes)
176+
│ ├── server.rs # Server logic (3561 bytes)
177+
│ ├── state.rs # State management (9991 bytes)
178+
│ ├── parser/ # Tree-sitter parsing
179+
│ ├── workspace/ # Multi-file support
180+
│ ├── formatter/ # Code formatting
181+
│ ├── config/ # Configuration management
182+
│ └── docs/ # Documentation generation
183+
├── sample/ # Sample proto files
184+
│ ├── simple.proto # Basic examples
185+
│ ├── everything.proto # Comprehensive features
186+
│ └── test.proto # Test scenarios
187+
└── .github/workflows/ # CI/CD pipelines
188+
├── ci.yml # Build and test
189+
└── release.yml # Release automation
190+
```
191+
192+
### Key Project Metadata
193+
```
194+
name = "protols"
195+
description = "Language server for proto3 files"
196+
version = "0.12.8"
197+
edition = "2024"
198+
license = "MIT"
199+
```
200+
201+
### Test Output Summary
202+
- **Total tests**: 22 tests across parser, workspace, config, and formatter modules
203+
- **Test categories**: hover, definition, rename, document symbols, diagnostics, workspace operations
204+
- **Performance**: All tests complete in under 6 seconds
205+
- **Coverage**: Core LSP features, configuration, and multi-file workspace scenarios

0 commit comments

Comments
 (0)