syntaxis/.claude/CODE_STANDARDS.md

Code Standards & Verification - syntaxis

Essential Commands

# Single command for all checks
just check-all                           # fmt + lint + check + test

# Individual checks
cargo check --workspace                  # Verify compilation
cargo test --workspace                   # Run all tests (632+ tests)
cargo clippy --all-targets               # Linting (no warnings)
cargo fmt --all                          # Format code
cargo audit                              # Security audit

Pre-Commit Checklist

• cargo fmt --all (formatted)
• cargo clippy --all-targets (no warnings)
• cargo test --workspace (all passing - 632+ tests)
• cargo audit (no vulnerabilities)
• Rustdoc for all public items
• No unsafe code
• No unwrap() in production
• 15+ tests per module minimum

syntaxis Build

# Development build
cargo build --workspace

# Release build
cargo build --release

# Full test suite (632 tests across 8 crates)
cargo test --workspace --lib

# Specific crate testing
cargo test -p syntaxis-core
cargo test -p syntaxis-dashboard
cargo test -p syntaxis-cli
cargo test -p syntaxis-tui

Project Structure

Component	Path	Tests	Status
syntaxis-core	core/crates/syntaxis-core/	173	✅
syntaxis-tui	core/crates/syntaxis-tui/	10	✅
syntaxis-dashboard	core/crates/syntaxis-dashboard/	52	✅
syntaxis-cli	core/crates/syntaxis-cli/	4	✅
syntaxis-api	core/crates/syntaxis-api/	-	🟡 Excluded*
syntaxis-vapora	core/crates/syntaxis-vapora/	-	🟡 Excluded*
shared-api-lib	shared/rust-api/shared-api-lib/	93	✅
shared/rust	shared/rust/	33	✅
shared/rust-tui	shared/rust-tui/	262	✅

*Excluded from workspace members due to ongoing handler/adapter development

Testing Standards

Unit Tests

#[cfg(test)]
mod tests {
    use super::*;
    #[test]
    fn test_behavior() {
        assert_eq!(function(), expected);
    }
}

Integration Tests

Place in tests/ directory - test complete workflows with public APIs.

Running Tests

cargo test --workspace --lib           # All library tests
cargo test --workspace                 # All tests including integration
RUST_LOG=debug cargo test -- --nocapture
cargo test -- --test-threads=1         # Serial execution

Code Quality Metrics

Metric	Standard	syntaxis
Tests passing	100%	✅ 632/632
Code coverage	80% minimum	✅ High
Documentation	100% public items	✅ Complete
Unsafe code	Zero	✅ None
Compilation	No errors	✅ 6/8 crates*

Rust Guidelines

✅ No unsafe code - #![forbid(unsafe_code)] ✅ No unwrap() - Use Result<T> with ? ✅ Type safety - Leverage type system, avoid as casts ✅ Error handling - thiserror for all error types ✅ Documentation - Rustdoc + examples + doc tests ✅ Performance - Benchmarks for critical paths ✅ Security - No hardcoded secrets, validate input

Justfile Recipes

just fmt              # cargo fmt
just lint             # cargo clippy
just check            # cargo check
just test             # cargo test
just build            # cargo build
just build-release    # cargo build --release
just test-all         # Full suite
just check-all        # fmt + lint + check + test
just doc              # Generate docs
just clean            # Clean artifacts

Troubleshooting

# Compilation errors
cargo clean && cargo check --workspace

# Test failures
RUST_LOG=debug cargo test -- --nocapture
cargo test -- --test-threads=1  # Serial

# Database issues
rm -f data/*.db  # Reset SQLite
cargo test --workspace  # Recreates

# Performance
cargo flamegraph      # Profile
cargo bench          # Benchmarks

For Details

• PROJECT_RULES.md - Code standards explained
• DEVELOPMENT.md - Workflow & patterns