diff --git a/.cursor/rules/rust/main.mdc b/.cursor/rules/rust/main.mdc index 737b34d..9f43eb4 100644 --- a/.cursor/rules/rust/main.mdc +++ b/.cursor/rules/rust/main.mdc @@ -35,10 +35,12 @@ graph TD Features --> Web{"Web Framework
needed?"} Features --> DB{"Database
access needed?"} Features --> Concurrent{"Heavy
concurrency?"} + Features --> Config{"Complex config
or templating?"} Web -->|Yes| WebRules["Load Axum Rules"] - DB -->|Yes| DBRules["Load SQLx Rules"] + DB -->|Yes| DBRules["Load Database Rules"] Concurrent -->|Yes| ConcurrencyRules["Load Concurrency Rules"] + Config -->|Yes| ToolsRules["Load Tools & Config Rules"] style Start fill:#4da6ff,stroke:#0066cc,color:white style Complex fill:#d94dbb,stroke:#a3378a,color:white @@ -143,18 +145,39 @@ sequenceDiagram - [ ] HTTP server needed - [ ] REST API endpoints - [ ] OpenAPI documentation required +- [ ] Axum framework planned +- [ ] SSE (Server-Sent Events) needed - [ ] → Load Axum rules if YES to any ### Database Requirements - [ ] Database queries needed -- [ ] SQL database integration -- [ ] Database migrations -- [ ] → Load SQLx rules if YES to any +- [ ] SQL database integration (PostgreSQL/SQLite) +- [ ] Database migrations required +- [ ] Repository pattern needed +- [ ] Connection pooling required +- [ ] → Load Database rules if YES to any + +### Concurrency Requirements +- [ ] Multi-threading needed +- [ ] Async/await extensively used +- [ ] Shared state across threads +- [ ] Event-driven architecture +- [ ] Background task processing +- [ ] → Load Concurrency rules if YES to any + +### Tools & Configuration Requirements +- [ ] Complex configuration files +- [ ] Template rendering needed +- [ ] Structured logging required +- [ ] Data transformation logic +- [ ] JSON path extraction +- [ ] → Load Tools & Config rules if YES to any ### Serialization Requirements - [ ] JSON handling required - [ ] External API integration - [ ] Configuration files +- [ ] camelCase JSON serialization - [ ] → Load Serde rules if YES to any ### Builder Pattern Requirements @@ -163,11 +186,21 @@ sequenceDiagram - [ ] Fluent API needed - [ ] → Load TypedBuilder rules if YES to any -### Concurrency Requirements -- [ ] Multi-threading needed -- [ ] Shared state across threads -- [ ] High-performance requirements -- [ ] → Load Concurrency rules if YES to any +### Utility Libraries Requirements +- [ ] Authentication/JWT needed +- [ ] CLI interface required +- [ ] Random data generation +- [ ] Enhanced derive macros +- [ ] Custom error types +- [ ] → Load Utilities rules if YES to any + +### HTTP Client Requirements +- [ ] External API integration +- [ ] HTTP requests needed +- [ ] REST client functionality +- [ ] Authentication headers +- [ ] Retry/resilience patterns +- [ ] → Load HTTP Client rules if YES to any ``` ## 🔧 RULE LOADING COMMANDS @@ -182,25 +215,27 @@ Based on project analysis, load specific rule sets: # Loads: core + complex + workspace + detected features # Feature-specific loading examples: -# Web: core + axum + serde + typed-builder -# Database: core + sqlx + error-handling -# CLI: core + simple + clap + error-handling +# Web: core + axum + serde + utilities (JWT) +# Database: core + sqlx + utilities (error handling) +# CLI: core + simple + utilities (clap + builders) +# Auth: core + utilities (JWT + validation) ``` ## 📚 AVAILABLE RULE MODULES | Module | File | Description | |--------|------|-------------| -| **Core** | `core/code-quality.mdc` | DRY/SRP, function size limits | +| **Core** | `core/code-quality.mdc` | Rust 2024, no unsafe, production-ready code | | **Simple** | `simple/single-crate.mdc` | Single crate project structure | | **Complex** | `complex/workspace.mdc` | Multi-crate workspace management | -| **Web** | `features/axum.mdc` | Axum framework best practices | -| **Database** | `features/sqlx.mdc` | SQLx patterns and testing | -| **Serialization** | `features/serde.mdc` | Serde configuration and patterns | -| **Builders** | `features/typed-builder.mdc` | TypedBuilder usage patterns | -| **Concurrency** | `features/concurrency.mdc` | Rust concurrency best practices | +| **Web** | `features/axum.mdc` | Axum 0.8 patterns, OpenAPI with utoipa | +| **Database** | `features/database.mdc` | SQLx patterns, repository design, testing | +| **Concurrency** | `features/concurrency.mdc` | Tokio, DashMap, async patterns | +| **Tools & Config** | `features/tools-and-config.mdc` | Tracing, YAML config, MiniJinja templates | +| **Utilities** | `features/utilities.mdc` | JWT auth, CLI tools, builders, enhanced derives | +| **HTTP Client** | `features/http-client.mdc` | reqwest patterns, error handling, retry logic | | **Testing** | `quality/testing.mdc` | Unit testing standards | -| **Errors** | `quality/error-handling.mdc` | Error handling patterns | +| **Errors** | `quality/error-handling.mdc` | thiserror/anyhow patterns | ## 🎯 PROJECT TYPE EXAMPLES @@ -211,11 +246,43 @@ Based on project analysis, load specific rule sets: - Desktop applications (single-window apps) ### Complex Project Examples -- Multi-service applications (auth + business + gateway) -- Enterprise applications (multiple domains) -- Large web applications (> 20 endpoints) -- Database systems with multiple engines -- Distributed systems +- **Workflow engines** (multi-node processing systems) +- **Multi-service applications** (auth + business + gateway) +- **Enterprise applications** (multiple domains) +- **Database systems** with multiple engines +- **Distributed systems** with event processing + +## 🚀 MODERN RUST STACK PREFERENCES + +Based on real-world experience, these are the recommended tools: + +### Core Dependencies +- **Rust Edition**: 2024 (always latest) +- **Error Handling**: `thiserror` for libraries, `anyhow` for binaries +- **Async Runtime**: `tokio` with full features +- **Serialization**: `serde` with `camelCase` for JSON APIs + +### Web Development Stack +- **Web Framework**: `axum` 0.8+ +- **API Documentation**: `utoipa` + `utoipa-swagger-ui` +- **HTTP Client**: `reqwest` +- **Database**: `sqlx` (never `rusqlite` or `tokio-postgres`) + +### Concurrency & Data Structures +- **Sync Primitives**: `tokio::sync` (never `std::sync` in async) +- **Concurrent Collections**: `dashmap` (never `Mutex`) +- **Channels**: `tokio::sync::{mpsc, broadcast, oneshot}` + +### Configuration & Templates +- **Config Format**: YAML (never TOML for complex configs) +- **Config Loading**: `serde_yaml` +- **Templates**: `minijinja` (never `handlebars`) +- **Data Extraction**: `jsonpath-rust` + +### Observability +- **Logging**: `tracing` + `tracing-subscriber` (never `env_logger`) +- **Structured Logging**: Always use `#[instrument]` and context +- **Log Rotation**: `tracing-appender` for production ## ⚡ OPTIMIZATION FEATURES @@ -223,6 +290,7 @@ Based on project analysis, load specific rule sets: - **Context Preservation**: Project decisions cached across sessions - **Template Generation**: Auto-generate boilerplate based on detected patterns - **Incremental Updates**: Update only changed components +- **Workspace Dependencies**: Always prefer workspace deps over crate-specific ## 🚨 MANDATORY VERIFICATION @@ -235,9 +303,29 @@ Before starting any Rust development: - Appropriate rules loaded? [YES/NO] - Cargo.toml structure verified? [YES/NO] - Error handling strategy selected? [thiserror/anyhow] +- Uses Rust 2024 edition? [YES/NO] +- No unsafe code planned? [YES/NO] +- Workspace dependencies configured? [YES/NO] → If all verified: Proceed with development → If missing: Complete project setup ``` -This system ensures optimal Rust development practices while maintaining flexibility for different project scales and requirements. +## 🔄 BUILD VERIFICATION WORKFLOW + +Every code change must pass this sequence: + +```bash +# 1. Build verification +cargo build + +# 2. Test execution +cargo test + +# 3. Linting verification +cargo clippy + +# All three must pass before code is considered complete +``` + +This system ensures optimal Rust development practices while maintaining flexibility for different project scales and requirements, based on real-world production experience.