Skip to content

Commit 8d2705b

Browse files
TheaxiomTheaxiom
authored
Merge pull request #7 from cloudfunnels/copilot/fix-6
Add comprehensive GitHub Copilot instructions for rust-guardian development
2 parents 84f8c3a + 55b18eb commit 8d2705b

File tree

2 files changed

+206
-0
lines changed

2 files changed

+206
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# Rust Guardian
2+
Rust Guardian is a self-contained, production-ready Rust crate providing comprehensive code quality analysis for detecting placeholder code, enforcing architectural boundaries, and maintaining code quality standards. It offers both a CLI tool and library API with async support for CI/CD integration.
3+
4+
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.
5+
6+
## Working Effectively
7+
- Bootstrap, build, and test the repository:
8+
- Install Rust: `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh && source ~/.cargo/env`
9+
- Check versions: `rustc --version && cargo --version` (requires Rust 1.70+)
10+
- Debug build: `cargo build` -- takes 1m 45s to complete. NEVER CANCEL. Set timeout to 120+ seconds.
11+
- Release build: `cargo build --release` -- takes 1m 5s to complete. NEVER CANCEL. Set timeout to 90+ seconds.
12+
- Run tests: `cargo test` -- takes 1m 35s to complete. NEVER CANCEL. Set timeout to 120+ seconds.
13+
- Install the CLI tool:
14+
- From source: `cargo install --path .` -- takes 35s to complete. NEVER CANCEL. Set timeout to 60+ seconds.
15+
- Verify installation: `rust-guardian --version`
16+
- Run the application:
17+
- ALWAYS run the bootstrapping steps first (build/install).
18+
- CLI usage: `rust-guardian check src/` (analyzes source files)
19+
- Watch mode: `rust-guardian watch src/` (real-time analysis)
20+
- Config validation: `rust-guardian validate-config guardian.yaml`
21+
22+
## Validation
23+
- Always manually validate any new code by running through complete end-to-end scenarios after making changes.
24+
- ALWAYS run at least one complete workflow after making changes: build → test → install → run on sample code.
25+
- You can build and run the CLI application in both debug and release modes.
26+
- Always run `cargo fmt` and `cargo clippy` before you are done or similar tools may fail in CI.
27+
28+
## Common tasks
29+
The following are outputs from frequently run commands. Reference them instead of viewing, searching, or running bash commands to save time.
30+
31+
### Repo root
32+
```
33+
.git
34+
.gitignore
35+
.guardianignore
36+
CHANGELOG.md
37+
Cargo.lock
38+
Cargo.toml
39+
LICENSE
40+
README.md
41+
examples/
42+
src/
43+
target/ (after build)
44+
.rust/ (cache directory)
45+
```
46+
47+
### Build and test performance
48+
- **Debug build**: ~1m 45s (set timeout: 120+ seconds)
49+
- **Release build**: ~1m 5s (set timeout: 90+ seconds)
50+
- **Tests**: ~1m 35s (set timeout: 120+ seconds)
51+
- **Install**: ~35s (set timeout: 60+ seconds)
52+
- **Runtime performance**: 20-150ms for typical projects (very fast)
53+
- **Memory usage**: ~50-100MB peak
54+
55+
### Key CLI commands validated to work
56+
```bash
57+
# Basic analysis
58+
rust-guardian check src/ # Analyze source directory
59+
rust-guardian check . --format json # JSON output for CI/CD
60+
rust-guardian check . --severity error # Show only errors
61+
62+
# Configuration and rules
63+
rust-guardian validate-config guardian.yaml # Validate config file
64+
rust-guardian rules # List all available rules
65+
rust-guardian explain todo_comments # Explain specific rule
66+
67+
# Performance and caching
68+
rust-guardian check . --cache # Enable caching
69+
rust-guardian cache stats # Show cache statistics
70+
rust-guardian cache clear # Clear cache
71+
72+
# Watch mode for development
73+
rust-guardian watch src/ # Real-time analysis
74+
75+
# Different output formats
76+
rust-guardian check . --format human # Human-readable (default)
77+
rust-guardian check . --format json # Machine-readable JSON
78+
rust-guardian check . --format junit # JUnit XML for CI
79+
rust-guardian check . --format github # GitHub Actions format
80+
```
81+
82+
### Sample analysis results
83+
When run on a typical Rust project with placeholder code:
84+
- **Execution time**: 20-150ms for small-medium projects
85+
- **Common violations found**: TODO comments, unimplemented!() macros, empty Ok(()) returns
86+
- **Exit codes**: 0 = success, 1 = violations found
87+
- **File support**: .rs files, respects .gitignore and .guardianignore patterns
88+
89+
### Configuration structure
90+
Default configuration includes:
91+
- **Placeholders**: TODO/FIXME/HACK comments, unimplemented!/todo!/panic! macros
92+
- **Incomplete implementations**: Empty Ok(()) returns
93+
- **Architectural violations**: Hardcoded paths, CDD header missing
94+
- **Severity levels**: error (fails CI), warning (informational), info (suggestions)
95+
- **Path filtering**: Supports .gitignore-style patterns with include/exclude
96+
97+
### Common validation scenarios
98+
After making changes, always test these scenarios:
99+
1. **Basic functionality**: `rust-guardian check src/` should analyze files and report violations
100+
2. **Clean code**: Run on clean code should return minimal/no violations
101+
3. **Problematic code**: Run on code with TODO comments should detect them
102+
4. **Performance**: Release mode should complete analysis in under 1 second for small projects
103+
5. **Configuration**: `rust-guardian validate-config` should validate YAML syntax
104+
6. **Help system**: `rust-guardian --help` and `rust-guardian rules` should work
105+
106+
### Project structure
107+
- **src/main.rs**: CLI application entry point
108+
- **src/lib.rs**: Library API for programmatic use
109+
- **src/analyzer/**: Core analysis engine with Rust AST parsing
110+
- **src/patterns/**: Pattern matching for different rule types (regex, AST, semantic)
111+
- **src/config/**: Configuration loading and validation
112+
- **src/report/**: Output formatting (human, JSON, JUnit, etc.)
113+
- **src/cache/**: File caching for performance
114+
- **examples/guardian.yaml**: Example configuration file
115+
- **Cargo.toml**: Dependencies include syn, regex, clap, tokio, rayon
116+
117+
### Dependencies and requirements
118+
- **Rust**: 1.70+ (tested with 1.88.0)
119+
- **Key dependencies**: syn (AST parsing), regex (pattern matching), clap (CLI), tokio (async), rayon (parallelism)
120+
- **Development dependencies**: tempfile, criterion, rstest, tokio-test
121+
- **Features**: cli (default), cache, colors, full
122+
- **No external system dependencies** - self-contained Rust application
123+
124+
### Sample workflow for testing changes
125+
```bash
126+
# Complete validation workflow (NEVER CANCEL any of these commands)
127+
cargo build # Build (1m 45s)
128+
cargo test # Test (1m 35s)
129+
cargo build --release # Release build (1m 5s)
130+
cargo install --path . # Install (35s)
131+
132+
# Test on sample problematic code
133+
echo '// TODO: implement this
134+
fn main() {
135+
todo!();
136+
}' > /tmp/test.rs
137+
138+
rust-guardian check /tmp/test.rs # Should find 2 violations
139+
rust-guardian check /tmp/test.rs --format json | jq '.summary'
140+
141+
# Test on clean code
142+
echo 'fn main() { println!("Hello!"); }' > /tmp/clean.rs
143+
rust-guardian check /tmp/clean.rs # Should find minimal violations
144+
145+
# Performance validation
146+
time rust-guardian check src/ # Should complete quickly (<1s)
147+
```
148+
149+
### Build troubleshooting
150+
- **Rust not found**: Install with `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`
151+
- **Build timeout**: NEVER CANCEL - builds take 1-2 minutes, set timeout to 120+ seconds
152+
- **Test failures**: All 55 tests should pass (51 unit + 4 CLI tests)
153+
- **Performance issues**: Use `--release` build for better performance
154+
- **Binary not found**: After `cargo install --path .`, binary is at `~/.cargo/bin/rust-guardian`
155+
156+
### CI/CD integration examples
157+
```bash
158+
# GitHub Actions
159+
rust-guardian check --format github --severity error >> $GITHUB_STEP_SUMMARY
160+
161+
# GitLab CI
162+
rust-guardian check --format junit --severity error > guardian-report.xml
163+
164+
# General CI
165+
rust-guardian check . --format json --severity error || exit 1
166+
```
167+
168+
### NEVER CANCEL commands - Required timeouts
169+
- `cargo build`: Set timeout to 120+ seconds (takes ~1m 45s)
170+
- `cargo build --release`: Set timeout to 90+ seconds (takes ~1m 5s)
171+
- `cargo test`: Set timeout to 120+ seconds (takes ~1m 35s)
172+
- `cargo install --path .`: Set timeout to 60+ seconds (takes ~35s)
173+
174+
### Quick reference for development
175+
```bash
176+
# Development cycle
177+
cargo check # Fast syntax check (~10s)
178+
cargo test # Run tests (1m 35s) - NEVER CANCEL
179+
cargo clippy # Lint code (~20s)
180+
cargo fmt # Format code (~5s)
181+
182+
# Testing the tool
183+
./target/release/rust-guardian check src/ # Test on own codebase
184+
./target/debug/rust-guardian --help # Verify CLI works
185+
rust-guardian rules # List available rules
186+
```

‎.rust/guardian_cache.json‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
{
2+
"version": 1,
3+
"config_fingerprint": "6b8edab3c93adcb8",
4+
"files": {
5+
"/tmp/test_sample.rs": {
6+
"content_hash": "e788800777bfaf4cea095632cd66708e7558d42708a4e26337f46d11688b39c9",
7+
"size": 521,
8+
"modified_at": 1754798592,
9+
"violation_count": 5,
10+
"analyzed_at": 1754798610,
11+
"config_fingerprint": "6b8edab3c93adcb8"
12+
}
13+
},
14+
"metadata": {
15+
"created_at": 1754798610,
16+
"updated_at": 1754798610,
17+
"hits": 0,
18+
"misses": 1
19+
}
20+
}

0 commit comments

Comments
 (0)