Skip to content

Commit f2c1fa2

Browse files
author
Jeshua ben Joseph
committed
Initial Commit
0 parents  commit f2c1fa2

File tree

26 files changed

+9923
-0
lines changed

26 files changed

+9923
-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, architectural 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+
```

‎.github/mlc_config.json‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
{
2+
"ignorePatterns": [
3+
{
4+
"pattern": "^http://localhost"
5+
},
6+
{
7+
"pattern": "^https://localhost"
8+
}
9+
],
10+
"replacementPatterns": [],
11+
"httpHeaders": [
12+
{
13+
"urls": ["https://crates.io", "https://docs.rs"],
14+
"headers": {
15+
"User-Agent": "Mozilla/5.0 (compatible; link-checker)"
16+
}
17+
}
18+
],
19+
"timeout": "10s",
20+
"retryOn429": true,
21+
"retryCount": 3,
22+
"fallbackHttpStatus": [400, 401, 403, 404, 429, 500, 502, 503, 504]
23+
}

‎.github/workflows/ci.yml‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [ main, develop ]
6+
pull_request:
7+
branches: [ main, develop ]
8+
9+
env:
10+
CARGO_TERM_COLOR: always
11+
12+
jobs:
13+
test:
14+
name: Test
15+
runs-on: ubuntu-latest
16+
strategy:
17+
matrix:
18+
rust:
19+
- stable
20+
- beta
21+
- nightly
22+
23+
steps:
24+
- uses: actions/checkout@v4
25+
26+
- name: Install Rust
27+
uses: dtolnay/rust-toolchain@master
28+
with:
29+
toolchain: ${{ matrix.rust }}
30+
components: rustfmt, clippy
31+
32+
- name: Cache cargo registry
33+
uses: actions/cache@v4
34+
with:
35+
path: |
36+
~/.cargo/registry
37+
~/.cargo/git
38+
target
39+
key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
40+
restore-keys: |
41+
${{ runner.os }}-cargo-
42+
43+
# - name: Check formatting
44+
# if: matrix.rust == 'stable'
45+
# run: cargo fmt --all -- --check
46+
47+
- name: Run clippy
48+
if: matrix.rust == 'stable'
49+
run: cargo clippy --all-targets --all-features -- -D warnings
50+
51+
- name: Run rust-guardian self-assessment
52+
if: matrix.rust == 'stable'
53+
run: |
54+
# Build first to ensure rust-guardian binary is available
55+
cargo build --release
56+
# Run rust-guardian on its own source code
57+
cargo run --release -- check src/ --config guardian.yaml --format github
58+
59+
- name: Build
60+
run: cargo build --verbose --all-features
61+
62+
- name: Run tests
63+
run: cargo test --verbose --all-features
64+
65+
- name: Test CLI
66+
run: |
67+
cargo run -- --help
68+
cargo run -- check --help
69+
cargo run -- rules
70+
71+
coverage:
72+
name: Coverage
73+
runs-on: ubuntu-latest
74+
steps:
75+
- uses: actions/checkout@v4
76+
77+
- name: Install Rust
78+
uses: dtolnay/rust-toolchain@stable
79+
80+
- name: Install cargo-llvm-cov
81+
uses: taiki-e/install-action@cargo-llvm-cov
82+
83+
- name: Generate code coverage
84+
run: cargo llvm-cov --all-features --workspace --lcov --output-path lcov.info
85+
86+
- name: Upload coverage to Codecov
87+
uses: codecov/codecov-action@v4
88+
with:
89+
file: lcov.info
90+
fail_ci_if_error: true
91+
92+
security:
93+
name: Security Audit
94+
runs-on: ubuntu-latest
95+
steps:
96+
- uses: actions/checkout@v4
97+
98+
- name: Install Rust
99+
uses: dtolnay/rust-toolchain@stable
100+
101+
- name: Install cargo-audit
102+
run: cargo install cargo-audit
103+
104+
- name: Run security audit
105+
run: cargo audit
106+
107+
minimal-versions:
108+
name: Minimal Versions
109+
runs-on: ubuntu-latest
110+
steps:
111+
- uses: actions/checkout@v4
112+
113+
- name: Install Rust
114+
uses: dtolnay/rust-toolchain@nightly
115+
116+
- name: Install minimal-versions
117+
run: cargo install cargo-minimal-versions
118+
119+
- name: Check minimal versions
120+
run: cargo minimal-versions check

0 commit comments

Comments
 (0)