@ngxtm/devkit 3.4.0 → 3.4.1

package/rules/rust/sea-orm/references/entity-patterns.md

@@ -0,0 +1,221 @@
+# Sea ORM Entity Patterns
+
+## Entity Definition
+
+```rust
+use sea_orm::entity::prelude::*;
+
+#[derive(Clone, Debug, PartialEq, Eq, DeriveEntityModel)]
+#[sea_orm(table_name = "users")]
+pub struct Model {
+    #[sea_orm(primary_key)]
+    pub id: i32,
+    pub name: String,
+    #[sea_orm(unique)]
+    pub email: String,
+    pub age: Option<i32>,
+    pub active: bool,
+    pub created_at: DateTimeUtc,
+}
+
+#[derive(Copy, Clone, Debug, EnumIter, DeriveRelation)]
+pub enum Relation {
+    #[sea_orm(has_many = "super::post::Entity")]
+    Posts,
+}
+
+impl Related<super::post::Entity> for Entity {
+    fn to() -> RelationDef {
+        Relation::Posts.def()
+    }
+}
+
+impl ActiveModelBehavior for ActiveModel {}
+```
+
+## Basic CRUD
+
+```rust
+use sea_orm::{Database, EntityTrait, ActiveModelTrait, Set};
+
+async fn crud_examples(db: &DatabaseConnection) -> Result<(), DbErr> {
+    // Create
+    let user = user::ActiveModel {
+        name: Set("John".to_owned()),
+        email: Set("john@example.com".to_owned()),
+        active: Set(true),
+        ..Default::default()
+    };
+    let user = user.insert(db).await?;
+    
+    // Read one
+    let user = User::find_by_id(1).one(db).await?;
+    
+    // Read with conditions
+    let users = User::find()
+        .filter(user::Column::Active.eq(true))
+        .filter(user::Column::Age.gt(18))
+        .order_by_asc(user::Column::Name)
+        .limit(10)
+        .all(db)
+        .await?;
+    
+    // Update
+    let mut user: user::ActiveModel = user.unwrap().into();
+    user.name = Set("Jane".to_owned());
+    let user = user.update(db).await?;
+    
+    // Delete
+    User::delete_by_id(1).exec(db).await?;
+    
+    Ok(())
+}
+```
+
+## Relations
+
+```rust
+// Post entity
+#[derive(Clone, Debug, PartialEq, Eq, DeriveEntityModel)]
+#[sea_orm(table_name = "posts")]
+pub struct Model {
+    #[sea_orm(primary_key)]
+    pub id: i32,
+    pub title: String,
+    pub user_id: i32,
+}
+
+#[derive(Copy, Clone, Debug, EnumIter, DeriveRelation)]
+pub enum Relation {
+    #[sea_orm(
+        belongs_to = "super::user::Entity",
+        from = "Column::UserId",
+        to = "super::user::Column::Id"
+    )]
+    User,
+}
+
+impl Related<super::user::Entity> for Entity {
+    fn to() -> RelationDef {
+        Relation::User.def()
+    }
+}
+
+// Query with relations
+async fn with_relations(db: &DatabaseConnection) -> Result<(), DbErr> {
+    // Eager loading
+    let users_with_posts = User::find()
+        .find_with_related(Post)
+        .all(db)
+        .await?;
+    
+    for (user, posts) in users_with_posts {
+        println!("User: {}", user.name);
+        for post in posts {
+            println!("  Post: {}", post.title);
+        }
+    }
+    
+    // Join
+    let results = User::find()
+        .inner_join(Post)
+        .filter(post::Column::Title.contains("rust"))
+        .all(db)
+        .await?;
+    
+    Ok(())
+}
+```
+
+## Transactions
+
+```rust
+use sea_orm::TransactionTrait;
+
+async fn transfer(db: &DatabaseConnection, from: i32, to: i32, amount: i64) -> Result<(), DbErr> {
+    db.transaction::<_, (), DbErr>(|txn| {
+        Box::pin(async move {
+            // Debit
+            let from_account = Account::find_by_id(from).one(txn).await?.unwrap();
+            let mut from_account: account::ActiveModel = from_account.into();
+            from_account.balance = Set(from_account.balance.unwrap() - amount);
+            from_account.update(txn).await?;
+            
+            // Credit
+            let to_account = Account::find_by_id(to).one(txn).await?.unwrap();
+            let mut to_account: account::ActiveModel = to_account.into();
+            to_account.balance = Set(to_account.balance.unwrap() + amount);
+            to_account.update(txn).await?;
+            
+            Ok(())
+        })
+    })
+    .await
+}
+```
+
+## Custom Queries
+
+```rust
+use sea_orm::{FromQueryResult, Statement};
+
+#[derive(Debug, FromQueryResult)]
+struct UserStats {
+    name: String,
+    post_count: i64,
+}
+
+async fn custom_query(db: &DatabaseConnection) -> Result<Vec<UserStats>, DbErr> {
+    UserStats::find_by_statement(Statement::from_sql_and_values(
+        db.get_database_backend(),
+        r#"
+        SELECT u.name, COUNT(p.id) as post_count
+        FROM users u
+        LEFT JOIN posts p ON u.id = p.user_id
+        GROUP BY u.id, u.name
+        "#,
+        vec![],
+    ))
+    .all(db)
+    .await
+}
+```
+
+## Migrations
+
+```rust
+// migration/src/m20220101_000001_create_users.rs
+use sea_orm_migration::prelude::*;
+
+#[derive(DeriveMigrationName)]
+pub struct Migration;
+
+#[async_trait::async_trait]
+impl MigrationTrait for Migration {
+    async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
+        manager
+            .create_table(
+                Table::create()
+                    .table(Users::Table)
+                    .if_not_exists()
+                    .col(ColumnDef::new(Users::Id).integer().not_null().auto_increment().primary_key())
+                    .col(ColumnDef::new(Users::Name).string().not_null())
+                    .col(ColumnDef::new(Users::Email).string().unique_key().not_null())
+                    .to_owned(),
+            )
+            .await
+    }
+
+    async fn down(&self, manager: &SchemaManager) -> Result<(), DbErr> {
+        manager.drop_table(Table::drop().table(Users::Table).to_owned()).await
+    }
+}
+
+#[derive(Iden)]
+enum Users {
+    Table,
+    Id,
+    Name,
+    Email,
+}
+```

package/rules/rust/serde-serialization/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: Serde Serialization
+description: Rust serialization/deserialization framework for JSON, YAML, TOML, and more.
+metadata:
+  labels: [rust, serde, serialization, json]
+  triggers:
+    files: ['**/*.rs']
+    keywords: [Serialize, Deserialize, serde, serde_json]
+---
+
+# Serde Standards
+
+## Basic Usage
+
+```rust
+use serde::{Serialize, Deserialize};
+
+#[derive(Serialize, Deserialize, Debug)]
+struct User {
+    id: u64,
+    name: String,
+    email: String,
+    #[serde(default)]
+    active: bool,
+}
+
+// Serialize to JSON
+let user = User { id: 1, name: "Alice".into(), email: "a@b.com".into(), active: true };
+let json = serde_json::to_string(&user)?;
+
+// Deserialize from JSON
+let user: User = serde_json::from_str(&json)?;
+```
+
+## Field Attributes
+
+```rust
+#[derive(Serialize, Deserialize)]
+struct Config {
+    // Rename field in JSON
+    #[serde(rename = "apiKey")]
+    api_key: String,
+
+    // Skip serializing if None
+    #[serde(skip_serializing_if = "Option::is_none")]
+    description: Option<String>,
+
+    // Default value if missing
+    #[serde(default = "default_timeout")]
+    timeout_secs: u64,
+
+    // Skip entirely
+    #[serde(skip)]
+    internal_state: bool,
+
+    // Flatten nested struct
+    #[serde(flatten)]
+    metadata: Metadata,
+}
+
+fn default_timeout() -> u64 { 30 }
+```
+
+## Enums
+
+```rust
+#[derive(Serialize, Deserialize)]
+#[serde(tag = "type")]  // Tagged union
+enum Event {
+    #[serde(rename = "user_created")]
+    UserCreated { id: u64, email: String },
+
+    #[serde(rename = "user_deleted")]
+    UserDeleted { id: u64 },
+}
+
+// Serializes as: {"type": "user_created", "id": 1, "email": "..."}
+
+// Untagged variant
+#[derive(Serialize, Deserialize)]
+#[serde(untagged)]
+enum Value {
+    Integer(i64),
+    Float(f64),
+    String(String),
+}
+```
+
+## Custom Serialization
+
+```rust
+use serde::{Serializer, Deserializer};
+
+#[derive(Serialize, Deserialize)]
+struct Record {
+    #[serde(serialize_with = "serialize_datetime")]
+    #[serde(deserialize_with = "deserialize_datetime")]
+    created_at: DateTime<Utc>,
+}
+
+fn serialize_datetime<S>(dt: &DateTime<Utc>, s: S) -> Result<S::Ok, S::Error>
+where S: Serializer {
+    s.serialize_str(&dt.to_rfc3339())
+}
+
+fn deserialize_datetime<'de, D>(d: D) -> Result<DateTime<Utc>, D::Error>
+where D: Deserializer<'de> {
+    let s = String::deserialize(d)?;
+    DateTime::parse_from_rfc3339(&s)
+        .map(|dt| dt.with_timezone(&Utc))
+        .map_err(serde::de::Error::custom)
+}
+```
+
+## Format Support
+
+| Format | Crate | Use Case |
+|--------|-------|----------|
+| JSON | `serde_json` | APIs, config |
+| YAML | `serde_yaml` | Config files |
+| TOML | `toml` | Cargo.toml style |
+| MessagePack | `rmp-serde` | Binary, compact |
+| CBOR | `ciborium` | Binary, standards |
+
+## Validation with Derive
+
+```rust
+use serde::Deserialize;
+use validator::Validate;
+
+#[derive(Deserialize, Validate)]
+struct CreateUser {
+    #[validate(length(min = 1, max = 100))]
+    name: String,
+
+    #[validate(email)]
+    email: String,
+
+    #[validate(range(min = 18, max = 120))]
+    age: u8,
+}
+```
+
+## Best Practices
+
+1. **Deny unknown fields**: `#[serde(deny_unknown_fields)]` for strict parsing
+2. **Rename all**: `#[serde(rename_all = "camelCase")]` for consistent naming
+3. **Default trait**: Implement `Default` for optional defaults
+4. **Error context**: Use `anyhow` or custom errors for better messages
+5. **Performance**: Use `serde_json::from_slice` for bytes, avoid string conversion

package/rules/rust/serde-serialization/references/REFERENCE.md

@@ -0,0 +1,13 @@
+# Rust Serde References
+
+## References
+
+- [**Serialization Patterns**](serialization-patterns.md) - Derive, attributes, custom
+
+## Quick Checks
+
+- [ ] Use derive macros for simple cases
+- [ ] Field attributes for customization
+- [ ] rename_all for case conventions
+- [ ] skip_serializing_if for optional fields
+- [ ] Custom serializers for complex types

package/rules/rust/serde-serialization/references/serialization-patterns.md

@@ -0,0 +1,199 @@
+# Serde Serialization Patterns
+
+## Basic Derive
+
+```rust
+use serde::{Deserialize, Serialize};
+
+#[derive(Serialize, Deserialize, Debug)]
+struct User {
+    id: u64,
+    name: String,
+    email: String,
+    #[serde(default)]
+    active: bool,
+}
+
+// Usage
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let user = User {
+        id: 1,
+        name: "John".into(),
+        email: "john@example.com".into(),
+        active: true,
+    };
+
+    // To JSON
+    let json = serde_json::to_string(&user)?;
+    let json_pretty = serde_json::to_string_pretty(&user)?;
+
+    // From JSON
+    let parsed: User = serde_json::from_str(&json)?;
+
+    Ok(())
+}
+```
+
+## Field Attributes
+
+```rust
+#[derive(Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct User {
+    user_id: u64,  // Serializes as "userId"
+    
+    #[serde(rename = "userName")]
+    name: String,
+    
+    #[serde(skip_serializing_if = "Option::is_none")]
+    bio: Option<String>,
+    
+    #[serde(skip)]
+    internal_state: String,
+    
+    #[serde(default = "default_role")]
+    role: String,
+    
+    #[serde(flatten)]
+    metadata: Metadata,
+    
+    #[serde(with = "chrono::serde::ts_seconds")]
+    created_at: DateTime<Utc>,
+}
+
+fn default_role() -> String {
+    "user".into()
+}
+
+#[derive(Serialize, Deserialize)]
+struct Metadata {
+    source: String,
+    version: u32,
+}
+```
+
+## Enum Representations
+
+```rust
+// Default: externally tagged
+#[derive(Serialize, Deserialize)]
+enum Message {
+    Text(String),           // {"Text": "hello"}
+    Image { url: String },  // {"Image": {"url": "..."}}
+    Ping,                   // "Ping"
+}
+
+// Internally tagged
+#[derive(Serialize, Deserialize)]
+#[serde(tag = "type")]
+enum Event {
+    Click { x: i32, y: i32 },  // {"type": "Click", "x": 10, "y": 20}
+    KeyPress { key: String },
+}
+
+// Adjacently tagged
+#[derive(Serialize, Deserialize)]
+#[serde(tag = "type", content = "data")]
+enum Response {
+    Success(Data),  // {"type": "Success", "data": {...}}
+    Error(String),
+}
+
+// Untagged
+#[derive(Serialize, Deserialize)]
+#[serde(untagged)]
+enum Value {
+    Integer(i64),
+    Float(f64),
+    Text(String),
+}
+```
+
+## Custom Serializers
+
+```rust
+use serde::{Serializer, Deserializer};
+
+#[derive(Serialize, Deserialize)]
+struct Config {
+    #[serde(serialize_with = "serialize_duration")]
+    #[serde(deserialize_with = "deserialize_duration")]
+    timeout: Duration,
+}
+
+fn serialize_duration<S>(duration: &Duration, s: S) -> Result<S::Ok, S::Error>
+where
+    S: Serializer,
+{
+    s.serialize_u64(duration.as_secs())
+}
+
+fn deserialize_duration<'de, D>(d: D) -> Result<Duration, D::Error>
+where
+    D: Deserializer<'de>,
+{
+    let secs = u64::deserialize(d)?;
+    Ok(Duration::from_secs(secs))
+}
+
+// Or use a module
+mod duration_secs {
+    use super::*;
+    
+    pub fn serialize<S>(duration: &Duration, s: S) -> Result<S::Ok, S::Error>
+    where S: Serializer {
+        s.serialize_u64(duration.as_secs())
+    }
+    
+    pub fn deserialize<'de, D>(d: D) -> Result<Duration, D::Error>
+    where D: Deserializer<'de> {
+        let secs = u64::deserialize(d)?;
+        Ok(Duration::from_secs(secs))
+    }
+}
+
+#[derive(Serialize, Deserialize)]
+struct Config {
+    #[serde(with = "duration_secs")]
+    timeout: Duration,
+}
+```
+
+## Generic Types
+
+```rust
+#[derive(Serialize, Deserialize)]
+struct Response<T> {
+    success: bool,
+    data: Option<T>,
+    error: Option<String>,
+}
+
+#[derive(Serialize, Deserialize)]
+#[serde(bound = "T: Serialize + DeserializeOwned")]
+struct Paginated<T> {
+    items: Vec<T>,
+    page: u32,
+    total: u32,
+}
+```
+
+## Different Formats
+
+```rust
+// JSON
+let json = serde_json::to_string(&data)?;
+let data: Data = serde_json::from_str(&json)?;
+
+// YAML
+let yaml = serde_yaml::to_string(&data)?;
+let data: Data = serde_yaml::from_str(&yaml)?;
+
+// TOML
+let toml = toml::to_string(&data)?;
+let data: Data = toml::from_str(&toml)?;
+
+// Bincode (binary)
+let bytes = bincode::serialize(&data)?;
+let data: Data = bincode::deserialize(&bytes)?;
+```

package/rules/rust/sqlx-database/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: SQLx Database
+description: Async Rust SQL toolkit with compile-time checked queries.
+metadata:
+  labels: [rust, sqlx, database, async, postgresql]
+  triggers:
+    files: ['**/*.rs', 'sqlx-data.json']
+    keywords: [sqlx, query, query_as, PgPool]
+---
+
+# SQLx Standards
+
+## Connection Pool
+
+```rust
+use sqlx::postgres::PgPoolOptions;
+
+let pool = PgPoolOptions::new()
+    .max_connections(5)
+    .connect("postgres://user:pass@localhost/db")
+    .await?;
+
+// Or from environment
+let pool = PgPool::connect(&std::env::var("DATABASE_URL")?).await?;
+```
+
+## Compile-Time Checked Queries
+
+```rust
+// Requires DATABASE_URL at compile time
+let user = sqlx::query_as!(
+    User,
+    "SELECT id, name, email FROM users WHERE id = $1",
+    user_id
+)
+.fetch_one(&pool)
+.await?;
+
+// Query with type override
+let count = sqlx::query_scalar!(
+    r#"SELECT COUNT(*) as "count!" FROM users"#
+)
+.fetch_one(&pool)
+.await?;
+```
+
+## Runtime Queries
+
+```rust
+use sqlx::{query, query_as, FromRow};
+
+#[derive(FromRow)]
+struct User {
+    id: i64,
+    name: String,
+    email: String,
+}
+
+// Named struct mapping
+let users: Vec<User> = query_as("SELECT * FROM users WHERE active = $1")
+    .bind(true)
+    .fetch_all(&pool)
+    .await?;
+
+// Dynamic query
+let user = query("SELECT * FROM users WHERE id = $1")
+    .bind(user_id)
+    .fetch_optional(&pool)
+    .await?;
+```
+
+## Fetch Methods
+
+| Method | Returns | Use Case |
+|--------|---------|----------|
+| `fetch_one` | `T` | Exactly one row expected |
+| `fetch_optional` | `Option<T>` | Zero or one row |
+| `fetch_all` | `Vec<T>` | All rows in memory |
+| `fetch` | `Stream<T>` | Large result sets |
+
+## Transactions
+
+```rust
+let mut tx = pool.begin().await?;
+
+sqlx::query("INSERT INTO users (name) VALUES ($1)")
+    .bind(&user.name)
+    .execute(&mut *tx)
+    .await?;
+
+sqlx::query("INSERT INTO audit_log (action) VALUES ($1)")
+    .bind("user_created")
+    .execute(&mut *tx)
+    .await?;
+
+tx.commit().await?;
+
+// Or automatic rollback on drop
+```
+
+## Migrations
+
+```bash
+# Create migration
+sqlx migrate add create_users_table
+
+# Run migrations
+sqlx migrate run
+
+# Revert last migration
+sqlx migrate revert
+```
+
+```rust
+// Run embedded migrations at startup
+sqlx::migrate!("./migrations")
+    .run(&pool)
+    .await?;
+```
+
+## Type Mappings
+
+| PostgreSQL | Rust | Notes |
+|------------|------|-------|
+| `BIGINT` | `i64` | |
+| `INTEGER` | `i32` | |
+| `TEXT/VARCHAR` | `String` | |
+| `BOOLEAN` | `bool` | |
+| `TIMESTAMP` | `chrono::NaiveDateTime` | Requires `chrono` feature |
+| `TIMESTAMPTZ` | `chrono::DateTime<Utc>` | |
+| `UUID` | `uuid::Uuid` | Requires `uuid` feature |
+| `JSONB` | `serde_json::Value` | Requires `json` feature |
+
+## Best Practices
+
+1. **Compile-time checks**: Use `query!` macros when possible
+2. **Connection limits**: Match pool size to Postgres `max_connections`
+3. **Prepared statements**: sqlx caches automatically per connection
+4. **Offline mode**: Generate `sqlx-data.json` for CI without database
+5. **Nullable columns**: Use `Option<T>` for nullable, or override with `"column!"`