syntaxis/.claude/CODE_STANDARDS.md

# Code Standards & Verification - syntaxis

## Essential Commands

```bash
# 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

```bash
# 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
```rust
#[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
```bash
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

```bash
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

```bash
# 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](./.claude/PROJECT_RULES.md) - Code standards explained
- [DEVELOPMENT.md](./.claude/DEVELOPMENT.md) - Workflow & patterns