@ngxtm/devkit 3.4.0 → 3.5.0

package/rules/rust/core/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: Rust Core
+description: Rust language fundamentals, ownership, error handling, and project patterns.
+metadata:
+  labels: [rust, core, language]
+  triggers:
+    files: ['Cargo.toml', '**/*.rs']
+    keywords: [fn, impl, struct, enum, Result, Option]
+---
+
+# Rust Core Standards
+
+## Ownership & Borrowing
+
+1. **Ownership Rules**:
+   - Each value has exactly one owner
+   - Value dropped when owner goes out of scope
+   - **Do**: Move or clone explicitly when needed
+   - **Don't**: Fight the borrow checker with unsafe
+
+2. **Borrowing**:
+   - Immutable: `&T` - multiple allowed
+   - Mutable: `&mut T` - only one, no immutable refs
+   - **Rule**: References must not outlive data
+
+## Error Handling
+
+```rust
+// Use Result for recoverable errors
+fn parse_config(path: &str) -> Result<Config, ConfigError> {
+    let content = std::fs::read_to_string(path)?;
+    toml::from_str(&content).map_err(ConfigError::Parse)
+}
+
+// Use Option for optional values
+fn find_user(id: u64) -> Option<User> { /* ... */ }
+
+// Custom error types
+#[derive(Debug, thiserror::Error)]
+enum AppError {
+    #[error("database error: {0}")]
+    Database(#[from] sqlx::Error),
+    #[error("not found: {0}")]
+    NotFound(String),
+}
+```
+
+**Patterns**:
+- `?` operator for propagation
+- `thiserror` for library errors
+- `anyhow` for application errors
+- **Never**: `unwrap()` in production code (use `expect` with context)
+
+## Async/Await
+
+- **Runtime**: Tokio for production
+- **Rule**: Async functions return `Future`, need executor
+
+```rust
+#[tokio::main]
+async fn main() {
+    let result = fetch_data().await;
+}
+
+async fn fetch_data() -> Result<Data, Error> {
+    let response = reqwest::get("https://api.example.com").await?;
+    response.json().await.map_err(Into::into)
+}
+```
+
+**Concurrency Patterns**:
+- `tokio::spawn` for background tasks
+- `tokio::select!` for racing futures
+- `tokio::sync::Mutex` for shared async state
+- **Warning**: `std::sync::Mutex` blocks; use `tokio::sync` in async
+
+## Traits & Generics
+
+```rust
+// Define trait bounds
+fn process<T: Serialize + Debug>(item: T) -> String { /* ... */ }
+
+// Impl blocks
+impl<T: Clone> Container<T> {
+    fn duplicate(&self) -> Self { /* ... */ }
+}
+
+// Associated types for clarity
+trait Iterator {
+    type Item;
+    fn next(&mut self) -> Option<Self::Item>;
+}
+```
+
+**Best Practices**:
+- Prefer `impl Trait` for return types
+- Use `where` clauses for complex bounds
+- `#[derive]` for common traits: `Debug, Clone, PartialEq`
+
+## Project Structure
+
+```
+my-project/
+├── Cargo.toml
+├── src/
+│   ├── main.rs          # Entry point
+│   ├── lib.rs           # Library root (optional)
+│   ├── config.rs        # Configuration
+│   ├── error.rs         # Error types
+│   ├── handlers/        # Request handlers
+│   │   └── mod.rs
+│   └── models/          # Data structures
+│       └── mod.rs
+└── tests/
+    └── integration.rs   # Integration tests
+```
+
+**Conventions**:
+- `mod.rs` for module roots
+- `pub` only what's needed
+- Re-export with `pub use` at module root
+
+## Testing
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_parse() {
+        let result = parse("valid");
+        assert_eq!(result, Ok(Expected));
+    }
+
+    #[tokio::test]
+    async fn test_async_fn() {
+        let data = fetch().await;
+        assert!(data.is_ok());
+    }
+}
+```
+
+- Unit tests in same file with `#[cfg(test)]`
+- Integration tests in `tests/` directory
+- Use `mockall` for mocking traits
+
+## Security
+
+1. **Input Validation**: Validate all external input before processing
+2. **SQL Injection**: Use parameterized queries (sqlx, diesel)
+3. **Dependencies**: Run `cargo audit` regularly
+4. **Unsafe**: Minimize `unsafe` blocks, document invariants
+5. **Secrets**: Use `secrecy` crate for sensitive data in memory

package/rules/rust/core/references/REFERENCE.md

@@ -0,0 +1,14 @@
+# Rust Core References
+
+## References
+
+- [**Error Handling**](error-handling.md) - Result, thiserror, anyhow patterns
+- [**Ownership Patterns**](ownership-patterns.md) - Borrowing, lifetimes, smart pointers
+
+## Quick Checks
+
+- [ ] Use Result for fallible operations
+- [ ] Use thiserror for library errors, anyhow for applications
+- [ ] Prefer borrowing over ownership transfer
+- [ ] Use `?` operator for error propagation
+- [ ] Derive Clone, Debug for data types

package/rules/rust/core/references/error-handling.md

@@ -0,0 +1,92 @@
+# Error Handling Patterns
+
+## Using thiserror (Libraries)
+
+```rust
+use thiserror::Error;
+
+#[derive(Error, Debug)]
+pub enum UserError {
+    #[error("user not found: {0}")]
+    NotFound(String),
+
+    #[error("invalid email format")]
+    InvalidEmail,
+
+    #[error("database error")]
+    Database(#[from] sqlx::Error),
+
+    #[error("validation failed: {field} - {message}")]
+    Validation { field: String, message: String },
+}
+
+// Usage
+fn find_user(id: &str) -> Result<User, UserError> {
+    let user = db.find(id).map_err(UserError::Database)?;
+    user.ok_or_else(|| UserError::NotFound(id.to_string()))
+}
+```
+
+## Using anyhow (Applications)
+
+```rust
+use anyhow::{Context, Result, bail};
+
+fn process_config(path: &str) -> Result<Config> {
+    let content = std::fs::read_to_string(path)
+        .context("failed to read config file")?;
+
+    let config: Config = serde_json::from_str(&content)
+        .context("failed to parse config")?;
+
+    if config.port == 0 {
+        bail!("port cannot be zero");
+    }
+
+    Ok(config)
+}
+
+// In main
+fn main() -> Result<()> {
+    let config = process_config("config.json")?;
+    run_server(config)?;
+    Ok(())
+}
+```
+
+## Error Conversion
+
+```rust
+// From trait for automatic conversion
+impl From<std::io::Error> for AppError {
+    fn from(err: std::io::Error) -> Self {
+        AppError::Io(err.to_string())
+    }
+}
+
+// Or use #[from] with thiserror
+#[derive(Error, Debug)]
+pub enum AppError {
+    #[error("IO error: {0}")]
+    Io(#[from] std::io::Error),
+
+    #[error("Parse error: {0}")]
+    Parse(#[from] serde_json::Error),
+}
+```
+
+## Pattern Matching Errors
+
+```rust
+match result {
+    Ok(value) => println!("Success: {}", value),
+    Err(UserError::NotFound(id)) => println!("User {} not found", id),
+    Err(UserError::InvalidEmail) => println!("Invalid email"),
+    Err(e) => println!("Other error: {}", e),
+}
+
+// Or with if let
+if let Err(UserError::NotFound(id)) = result {
+    // handle not found
+}
+```

package/rules/rust/diesel-orm/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: Diesel ORM
+description: Type-safe Rust ORM with compile-time query validation.
+metadata:
+  labels: [rust, diesel, orm, database, postgresql]
+  triggers:
+    files: ['**/schema.rs', 'diesel.toml']
+    keywords: [diesel, Queryable, Insertable, table]
+---
+
+# Diesel ORM Standards
+
+## Schema Definition
+
+```rust
+// Generated by diesel migration run
+// src/schema.rs
+diesel::table! {
+    users (id) {
+        id -> Int4,
+        name -> Varchar,
+        email -> Varchar,
+        created_at -> Timestamp,
+    }
+}
+```
+
+## Model Structs
+
+```rust
+use diesel::prelude::*;
+use crate::schema::users;
+
+#[derive(Queryable, Selectable, Debug)]
+#[diesel(table_name = users)]
+pub struct User {
+    pub id: i32,
+    pub name: String,
+    pub email: String,
+    pub created_at: NaiveDateTime,
+}
+
+#[derive(Insertable)]
+#[diesel(table_name = users)]
+pub struct NewUser<'a> {
+    pub name: &'a str,
+    pub email: &'a str,
+}
+
+#[derive(AsChangeset)]
+#[diesel(table_name = users)]
+pub struct UpdateUser<'a> {
+    pub name: Option<&'a str>,
+    pub email: Option<&'a str>,
+}
+```
+
+## Connection Pool
+
+```rust
+use diesel::pg::PgConnection;
+use diesel::r2d2::{Pool, ConnectionManager};
+
+type DbPool = Pool<ConnectionManager<PgConnection>>;
+
+fn establish_pool(database_url: &str) -> DbPool {
+    let manager = ConnectionManager::<PgConnection>::new(database_url);
+    Pool::builder()
+        .max_size(15)
+        .build(manager)
+        .expect("Failed to create pool")
+}
+```
+
+## CRUD Operations
+
+```rust
+use diesel::prelude::*;
+use crate::schema::users::dsl::*;
+
+// Create
+fn create_user(conn: &mut PgConnection, new_user: &NewUser) -> QueryResult<User> {
+    diesel::insert_into(users)
+        .values(new_user)
+        .get_result(conn)
+}
+
+// Read
+fn find_user(conn: &mut PgConnection, user_id: i32) -> QueryResult<User> {
+    users.find(user_id).first(conn)
+}
+
+fn list_users(conn: &mut PgConnection) -> QueryResult<Vec<User>> {
+    users.load(conn)
+}
+
+// Update
+fn update_user(conn: &mut PgConnection, user_id: i32, changes: &UpdateUser) -> QueryResult<User> {
+    diesel::update(users.find(user_id))
+        .set(changes)
+        .get_result(conn)
+}
+
+// Delete
+fn delete_user(conn: &mut PgConnection, user_id: i32) -> QueryResult<usize> {
+    diesel::delete(users.find(user_id)).execute(conn)
+}
+```
+
+## Query Building
+
+```rust
+// Filtering
+let active_users = users
+    .filter(active.eq(true))
+    .filter(created_at.gt(cutoff_date))
+    .load::<User>(conn)?;
+
+// Ordering and pagination
+let page = users
+    .order(created_at.desc())
+    .limit(10)
+    .offset(20)
+    .load::<User>(conn)?;
+
+// Select specific columns
+let emails: Vec<String> = users
+    .select(email)
+    .load(conn)?;
+
+// Joins
+let user_posts = users
+    .inner_join(posts::table)
+    .select((users::name, posts::title))
+    .load::<(String, String)>(conn)?;
+```
+
+## Transactions
+
+```rust
+conn.transaction(|conn| {
+    diesel::insert_into(users)
+        .values(&new_user)
+        .execute(conn)?;
+
+    diesel::insert_into(audit_log)
+        .values(&log_entry)
+        .execute(conn)?;
+
+    Ok(())
+})
+```
+
+## Migrations
+
+```bash
+# Create migration
+diesel migration generate create_users
+
+# Run pending migrations
+diesel migration run
+
+# Revert last migration
+diesel migration revert
+
+# Redo last migration
+diesel migration redo
+```
+
+## Best Practices
+
+1. **Schema sync**: Run `diesel migration run` before compile
+2. **Pool sizing**: Match to expected concurrent connections
+3. **Derive macros**: Use `Queryable` for reads, `Insertable` for writes
+4. **Nullable**: Use `Option<T>` for nullable columns
+5. **Raw SQL**: Use `sql_query()` for complex queries when needed

package/rules/rust/diesel-orm/references/REFERENCE.md

@@ -0,0 +1,13 @@
+# Diesel ORM References
+
+## References
+
+- [**Schema Patterns**](schema-patterns.md) - Models, queries, associations
+
+## Quick Checks
+
+- [ ] Use diesel CLI for migrations
+- [ ] Derive Queryable for reads
+- [ ] Derive Insertable for writes
+- [ ] Type-safe query DSL
+- [ ] Connection pooling with r2d2

package/rules/rust/diesel-orm/references/schema-patterns.md

@@ -0,0 +1,206 @@
+# Diesel Schema Patterns
+
+## Schema Definition
+
+```rust
+// schema.rs (generated by diesel)
+diesel::table! {
+    users (id) {
+        id -> Int4,
+        name -> Varchar,
+        email -> Varchar,
+        active -> Bool,
+        created_at -> Timestamp,
+    }
+}
+
+diesel::table! {
+    posts (id) {
+        id -> Int4,
+        title -> Varchar,
+        body -> Text,
+        user_id -> Int4,
+        published -> Bool,
+    }
+}
+
+diesel::joinable!(posts -> users (user_id));
+diesel::allow_tables_to_appear_in_same_query!(users, posts);
+```
+
+## Models
+
+```rust
+use diesel::prelude::*;
+use crate::schema::users;
+
+#[derive(Queryable, Selectable, Debug)]
+#[diesel(table_name = users)]
+pub struct User {
+    pub id: i32,
+    pub name: String,
+    pub email: String,
+    pub active: bool,
+    pub created_at: chrono::NaiveDateTime,
+}
+
+#[derive(Insertable)]
+#[diesel(table_name = users)]
+pub struct NewUser<'a> {
+    pub name: &'a str,
+    pub email: &'a str,
+}
+
+#[derive(AsChangeset)]
+#[diesel(table_name = users)]
+pub struct UpdateUser<'a> {
+    pub name: Option<&'a str>,
+    pub email: Option<&'a str>,
+    pub active: Option<bool>,
+}
+```
+
+## CRUD Operations
+
+```rust
+use diesel::prelude::*;
+use crate::schema::users::dsl::*;
+
+// Create
+fn create_user(conn: &mut PgConnection, user_name: &str, user_email: &str) -> QueryResult<User> {
+    let new_user = NewUser {
+        name: user_name,
+        email: user_email,
+    };
+
+    diesel::insert_into(users)
+        .values(&new_user)
+        .returning(User::as_returning())
+        .get_result(conn)
+}
+
+// Read
+fn find_user(conn: &mut PgConnection, user_id: i32) -> QueryResult<Option<User>> {
+    users.find(user_id).first(conn).optional()
+}
+
+fn list_active_users(conn: &mut PgConnection) -> QueryResult<Vec<User>> {
+    users
+        .filter(active.eq(true))
+        .order(name.asc())
+        .limit(10)
+        .load(conn)
+}
+
+// Update
+fn update_user(conn: &mut PgConnection, user_id: i32, new_name: &str) -> QueryResult<User> {
+    diesel::update(users.find(user_id))
+        .set(name.eq(new_name))
+        .returning(User::as_returning())
+        .get_result(conn)
+}
+
+fn update_user_partial(conn: &mut PgConnection, user_id: i32, changes: &UpdateUser) -> QueryResult<User> {
+    diesel::update(users.find(user_id))
+        .set(changes)
+        .returning(User::as_returning())
+        .get_result(conn)
+}
+
+// Delete
+fn delete_user(conn: &mut PgConnection, user_id: i32) -> QueryResult<usize> {
+    diesel::delete(users.find(user_id)).execute(conn)
+}
+```
+
+## Associations
+
+```rust
+use diesel::prelude::*;
+
+#[derive(Queryable, Identifiable, Selectable)]
+#[diesel(table_name = users)]
+pub struct User {
+    pub id: i32,
+    pub name: String,
+}
+
+#[derive(Queryable, Identifiable, Selectable, Associations)]
+#[diesel(belongs_to(User))]
+#[diesel(table_name = posts)]
+pub struct Post {
+    pub id: i32,
+    pub title: String,
+    pub user_id: i32,
+}
+
+fn posts_for_user(conn: &mut PgConnection, user: &User) -> QueryResult<Vec<Post>> {
+    Post::belonging_to(user)
+        .select(Post::as_select())
+        .load(conn)
+}
+
+fn users_with_posts(conn: &mut PgConnection) -> QueryResult<Vec<(User, Vec<Post>)>> {
+    let all_users = users::table.load::<User>(conn)?;
+    let all_posts = Post::belonging_to(&all_users)
+        .select(Post::as_select())
+        .load(conn)?;
+    
+    Ok(all_posts.grouped_by(&all_users)
+        .into_iter()
+        .zip(all_users)
+        .map(|(posts, user)| (user, posts))
+        .collect())
+}
+```
+
+## Connection Pool
+
+```rust
+use diesel::r2d2::{ConnectionManager, Pool};
+
+type DbPool = Pool<ConnectionManager<PgConnection>>;
+
+fn establish_pool(database_url: &str) -> DbPool {
+    let manager = ConnectionManager::<PgConnection>::new(database_url);
+    Pool::builder()
+        .max_size(10)
+        .build(manager)
+        .expect("Failed to create pool")
+}
+
+// Usage
+let pool = establish_pool("postgres://localhost/mydb");
+let mut conn = pool.get().expect("Failed to get connection");
+let users = list_active_users(&mut conn)?;
+```
+
+## Migrations
+
+```bash
+# Install CLI
+cargo install diesel_cli --no-default-features --features postgres
+
+# Setup
+diesel setup
+
+# Create migration
+diesel migration generate create_users
+
+# Run migrations
+diesel migration run
+
+# Revert
+diesel migration revert
+```
+
+```sql
+-- migrations/00000000000000_create_users/up.sql
+CREATE TABLE users (
+    id SERIAL PRIMARY KEY,
+    name VARCHAR NOT NULL,
+    email VARCHAR NOT NULL UNIQUE,
+    active BOOLEAN NOT NULL DEFAULT TRUE,
+    created_at TIMESTAMP NOT NULL DEFAULT NOW()
+);
+```