@ngxtm/devkit 3.4.0 → 3.5.0

package/rules/rust/bevy/references/ecs-patterns.md

@@ -0,0 +1,226 @@
+# Bevy ECS Patterns
+
+## Basic App
+
+```rust
+use bevy::prelude::*;
+
+fn main() {
+    App::new()
+        .add_plugins(DefaultPlugins)
+        .add_systems(Startup, setup)
+        .add_systems(Update, (movement, collision))
+        .run();
+}
+
+fn setup(mut commands: Commands) {
+    commands.spawn(Camera2dBundle::default());
+}
+```
+
+## Components
+
+```rust
+#[derive(Component)]
+struct Player {
+    speed: f32,
+}
+
+#[derive(Component)]
+struct Health(f32);
+
+#[derive(Component)]
+struct Velocity(Vec2);
+
+// Bundle for related components
+#[derive(Bundle)]
+struct PlayerBundle {
+    player: Player,
+    health: Health,
+    velocity: Velocity,
+    sprite: SpriteBundle,
+}
+```
+
+## Spawning Entities
+
+```rust
+fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
+    // Simple entity
+    commands.spawn((
+        Player { speed: 200.0 },
+        Health(100.0),
+        Velocity(Vec2::ZERO),
+        SpriteBundle {
+            texture: asset_server.load("player.png"),
+            transform: Transform::from_xyz(0.0, 0.0, 0.0),
+            ..default()
+        },
+    ));
+
+    // With bundle
+    commands.spawn(PlayerBundle {
+        player: Player { speed: 200.0 },
+        health: Health(100.0),
+        velocity: Velocity(Vec2::ZERO),
+        sprite: SpriteBundle::default(),
+    });
+
+    // With children
+    commands.spawn(SpriteBundle::default())
+        .with_children(|parent| {
+            parent.spawn(SpriteBundle::default());
+        });
+}
+```
+
+## Systems
+
+```rust
+// Query for entities with components
+fn movement(
+    time: Res<Time>,
+    input: Res<ButtonInput<KeyCode>>,
+    mut query: Query<(&Player, &mut Transform)>,
+) {
+    for (player, mut transform) in &mut query {
+        let mut direction = Vec2::ZERO;
+        
+        if input.pressed(KeyCode::KeyW) { direction.y += 1.0; }
+        if input.pressed(KeyCode::KeyS) { direction.y -= 1.0; }
+        if input.pressed(KeyCode::KeyA) { direction.x -= 1.0; }
+        if input.pressed(KeyCode::KeyD) { direction.x += 1.0; }
+        
+        if direction != Vec2::ZERO {
+            direction = direction.normalize();
+            transform.translation.x += direction.x * player.speed * time.delta_seconds();
+            transform.translation.y += direction.y * player.speed * time.delta_seconds();
+        }
+    }
+}
+
+// Query filters
+fn update_enemies(
+    query: Query<&mut Health, (With<Enemy>, Without<Player>)>,
+) {
+    // Only entities with Enemy, without Player
+}
+```
+
+## Resources
+
+```rust
+#[derive(Resource)]
+struct GameState {
+    score: u32,
+    level: u32,
+}
+
+#[derive(Resource, Default)]
+struct GameTimer(Timer);
+
+fn setup(mut commands: Commands) {
+    commands.insert_resource(GameState { score: 0, level: 1 });
+    commands.insert_resource(GameTimer(Timer::from_seconds(1.0, TimerMode::Repeating)));
+}
+
+fn update_score(
+    mut game: ResMut<GameState>,
+    time: Res<Time>,
+    mut timer: ResMut<GameTimer>,
+) {
+    if timer.0.tick(time.delta()).just_finished() {
+        game.score += 10;
+    }
+}
+```
+
+## Events
+
+```rust
+#[derive(Event)]
+struct CollisionEvent {
+    entity_a: Entity,
+    entity_b: Entity,
+}
+
+fn detect_collisions(
+    query: Query<(Entity, &Transform), With<Collider>>,
+    mut events: EventWriter<CollisionEvent>,
+) {
+    // Check collisions
+    events.send(CollisionEvent {
+        entity_a: e1,
+        entity_b: e2,
+    });
+}
+
+fn handle_collisions(
+    mut events: EventReader<CollisionEvent>,
+    mut commands: Commands,
+) {
+    for event in events.read() {
+        commands.entity(event.entity_b).despawn();
+    }
+}
+
+// Register event
+App::new()
+    .add_event::<CollisionEvent>()
+    .add_systems(Update, (detect_collisions, handle_collisions).chain())
+```
+
+## States
+
+```rust
+#[derive(States, Debug, Clone, PartialEq, Eq, Hash, Default)]
+enum GameState {
+    #[default]
+    Menu,
+    Playing,
+    Paused,
+    GameOver,
+}
+
+fn main() {
+    App::new()
+        .init_state::<GameState>()
+        .add_systems(OnEnter(GameState::Playing), setup_game)
+        .add_systems(OnExit(GameState::Playing), cleanup_game)
+        .add_systems(Update, game_logic.run_if(in_state(GameState::Playing)))
+        .run();
+}
+
+fn pause_game(
+    input: Res<ButtonInput<KeyCode>>,
+    state: Res<State<GameState>>,
+    mut next_state: ResMut<NextState<GameState>>,
+) {
+    if input.just_pressed(KeyCode::Escape) {
+        match state.get() {
+            GameState::Playing => next_state.set(GameState::Paused),
+            GameState::Paused => next_state.set(GameState::Playing),
+            _ => {}
+        }
+    }
+}
+```
+
+## Asset Loading
+
+```rust
+#[derive(Resource)]
+struct GameAssets {
+    player: Handle<Image>,
+    enemy: Handle<Image>,
+    font: Handle<Font>,
+}
+
+fn load_assets(mut commands: Commands, asset_server: Res<AssetServer>) {
+    commands.insert_resource(GameAssets {
+        player: asset_server.load("player.png"),
+        enemy: asset_server.load("enemy.png"),
+        font: asset_server.load("fonts/main.ttf"),
+    });
+}
+```

package/rules/rust/clap/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: Clap CLI Framework
+description: Command-line argument parsing with derive macros.
+metadata:
+  labels: [rust, clap, cli, args]
+  triggers:
+    files: ['**/main.rs', '**/cli.rs']
+    keywords: [clap, Parser, Subcommand, Args, command]
+---
+
+# Clap Standards
+
+## Basic CLI
+
+```rust
+use clap::Parser;
+
+#[derive(Parser)]
+#[command(name = "myapp")]
+#[command(version, about, long_about = None)]
+struct Cli {
+    /// Name to greet
+    #[arg(short, long)]
+    name: String,
+
+    /// Number of times to greet
+    #[arg(short, long, default_value_t = 1)]
+    count: u8,
+
+    /// Enable verbose output
+    #[arg(short, long)]
+    verbose: bool,
+}
+
+fn main() {
+    let cli = Cli::parse();
+    for _ in 0..cli.count {
+        println!("Hello, {}!", cli.name);
+    }
+}
+```
+
+## Subcommands
+
+```rust
+use clap::{Parser, Subcommand};
+
+#[derive(Parser)]
+#[command(name = "git-like")]
+struct Cli {
+    #[command(subcommand)]
+    command: Commands,
+}
+
+#[derive(Subcommand)]
+enum Commands {
+    /// Add files to staging
+    Add {
+        #[arg(required = true)]
+        files: Vec<String>,
+    },
+    /// Commit changes
+    Commit {
+        #[arg(short, long)]
+        message: String,
+    },
+    /// Push to remote
+    Push {
+        #[arg(short, long, default_value = "origin")]
+        remote: String,
+    },
+}
+
+fn main() {
+    let cli = Cli::parse();
+    match cli.command {
+        Commands::Add { files } => println!("Adding: {:?}", files),
+        Commands::Commit { message } => println!("Commit: {}", message),
+        Commands::Push { remote } => println!("Push to {}", remote),
+    }
+}
+```
+
+## Argument Types
+
+```rust
+use std::path::PathBuf;
+use clap::{Parser, ValueEnum};
+
+#[derive(Copy, Clone, ValueEnum)]
+enum Format {
+    Json,
+    Yaml,
+    Toml,
+}
+
+#[derive(Parser)]
+struct Cli {
+    /// Input file
+    #[arg(short, long, value_name = "FILE")]
+    input: PathBuf,
+
+    /// Output format
+    #[arg(short, long, value_enum, default_value_t = Format::Json)]
+    format: Format,
+
+    /// Port number (1-65535)
+    #[arg(short, long, value_parser = clap::value_parser!(u16).range(1..))]
+    port: u16,
+
+    /// Environment variables
+    #[arg(short, long, value_parser = parse_key_val)]
+    env: Vec<(String, String)>,
+}
+
+fn parse_key_val(s: &str) -> Result<(String, String), String> {
+    let pos = s.find('=').ok_or("no `=` found")?;
+    Ok((s[..pos].to_string(), s[pos + 1..].to_string()))
+}
+```
+
+## Global Arguments
+
+```rust
+#[derive(Parser)]
+struct Cli {
+    #[command(flatten)]
+    global: GlobalArgs,
+
+    #[command(subcommand)]
+    command: Commands,
+}
+
+#[derive(Args)]
+struct GlobalArgs {
+    /// Config file path
+    #[arg(short, long, global = true)]
+    config: Option<PathBuf>,
+
+    /// Verbose mode
+    #[arg(short, long, global = true)]
+    verbose: bool,
+}
+```
+
+## Validation
+
+```rust
+use clap::Parser;
+
+#[derive(Parser)]
+struct Cli {
+    /// Must be positive
+    #[arg(value_parser = positive_number)]
+    count: i32,
+
+    /// Must exist
+    #[arg(value_parser = existing_path)]
+    path: PathBuf,
+}
+
+fn positive_number(s: &str) -> Result<i32, String> {
+    let n: i32 = s.parse().map_err(|_| "not a number")?;
+    if n <= 0 { return Err("must be positive".into()); }
+    Ok(n)
+}
+
+fn existing_path(s: &str) -> Result<PathBuf, String> {
+    let path = PathBuf::from(s);
+    if !path.exists() { return Err("path does not exist".into()); }
+    Ok(path)
+}
+```
+
+## Environment Variables
+
+```rust
+#[derive(Parser)]
+struct Cli {
+    /// API key (or MYAPP_API_KEY env var)
+    #[arg(short, long, env = "MYAPP_API_KEY")]
+    api_key: String,
+
+    /// Database URL
+    #[arg(long, env)]  // Uses MYAPP_DATABASE_URL
+    database_url: String,
+}
+```
+
+## Shell Completions
+
+```rust
+use clap::CommandFactory;
+use clap_complete::{generate, Shell};
+
+fn generate_completions(shell: Shell) {
+    let mut cmd = Cli::command();
+    generate(shell, &mut cmd, "myapp", &mut std::io::stdout());
+}
+
+// Build script (build.rs)
+fn main() {
+    let outdir = std::env::var("OUT_DIR").unwrap();
+    let mut cmd = Cli::command();
+    for shell in [Shell::Bash, Shell::Zsh, Shell::Fish] {
+        clap_complete::generate_to(shell, &mut cmd, "myapp", &outdir).unwrap();
+    }
+}
+```
+
+## Best Practices
+
+1. **Derive API**: Prefer over builder for most cases
+2. **Help text**: Use doc comments (`///`) for descriptions
+3. **Defaults**: Provide sensible defaults with `default_value`
+4. **Validation**: Use `value_parser` for custom validation
+5. **Env vars**: Support config via environment with `env`

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

@@ -0,0 +1,13 @@
+# Clap CLI References
+
+## References
+
+- [**Derive Patterns**](derive-patterns.md) - Args, subcommands, value parsing
+
+## Quick Checks
+
+- [ ] Use derive macro for declarative CLI
+- [ ] Subcommands for complex CLIs
+- [ ] Value parsers for custom types
+- [ ] Environment variable fallbacks
+- [ ] Help and version auto-generation

package/rules/rust/clap/references/derive-patterns.md

@@ -0,0 +1,205 @@
+# Clap Derive Patterns
+
+## Basic CLI
+
+```rust
+use clap::Parser;
+
+#[derive(Parser)]
+#[command(name = "myapp")]
+#[command(author, version, about, long_about = None)]
+struct Cli {
+    /// Input file to process
+    #[arg(short, long)]
+    input: String,
+
+    /// Output file (optional)
+    #[arg(short, long)]
+    output: Option<String>,
+
+    /// Enable verbose output
+    #[arg(short, long, default_value_t = false)]
+    verbose: bool,
+
+    /// Number of iterations
+    #[arg(short = 'n', long, default_value_t = 1)]
+    count: u32,
+}
+
+fn main() {
+    let cli = Cli::parse();
+    
+    if cli.verbose {
+        println!("Processing: {}", cli.input);
+    }
+}
+```
+
+## Subcommands
+
+```rust
+use clap::{Parser, Subcommand};
+
+#[derive(Parser)]
+#[command(name = "git-lite")]
+struct Cli {
+    #[command(subcommand)]
+    command: Commands,
+}
+
+#[derive(Subcommand)]
+enum Commands {
+    /// Clone a repository
+    Clone {
+        /// Repository URL
+        url: String,
+        /// Local directory
+        #[arg(short, long)]
+        directory: Option<String>,
+    },
+    /// Commit changes
+    Commit {
+        /// Commit message
+        #[arg(short, long)]
+        message: String,
+        /// Amend previous commit
+        #[arg(long)]
+        amend: bool,
+    },
+    /// Push to remote
+    Push {
+        /// Remote name
+        #[arg(default_value = "origin")]
+        remote: String,
+        /// Branch name
+        branch: Option<String>,
+    },
+}
+
+fn main() {
+    let cli = Cli::parse();
+
+    match cli.command {
+        Commands::Clone { url, directory } => {
+            println!("Cloning {} to {:?}", url, directory);
+        }
+        Commands::Commit { message, amend } => {
+            println!("Committing: {} (amend: {})", message, amend);
+        }
+        Commands::Push { remote, branch } => {
+            println!("Pushing to {} branch {:?}", remote, branch);
+        }
+    }
+}
+```
+
+## Value Parsers
+
+```rust
+use clap::{Parser, ValueEnum};
+use std::path::PathBuf;
+
+#[derive(Copy, Clone, PartialEq, Eq, ValueEnum)]
+enum Format {
+    Json,
+    Yaml,
+    Toml,
+}
+
+#[derive(Parser)]
+struct Cli {
+    /// Output format
+    #[arg(short, long, value_enum, default_value_t = Format::Json)]
+    format: Format,
+
+    /// Config file path
+    #[arg(short, long, value_name = "FILE")]
+    config: PathBuf,
+
+    /// Port number (1-65535)
+    #[arg(short, long, value_parser = clap::value_parser!(u16).range(1..))]
+    port: u16,
+
+    /// Log levels
+    #[arg(short, long, value_delimiter = ',')]
+    levels: Vec<String>,
+}
+```
+
+## Environment Variables
+
+```rust
+#[derive(Parser)]
+struct Cli {
+    /// API key (or set API_KEY env var)
+    #[arg(long, env = "API_KEY")]
+    api_key: String,
+
+    /// Database URL
+    #[arg(long, env = "DATABASE_URL", default_value = "postgres://localhost/db")]
+    database_url: String,
+}
+```
+
+## Global Options
+
+```rust
+#[derive(Parser)]
+struct Cli {
+    /// Global verbose flag
+    #[arg(short, long, global = true)]
+    verbose: bool,
+
+    /// Config file (applies to all subcommands)
+    #[arg(short, long, global = true)]
+    config: Option<PathBuf>,
+
+    #[command(subcommand)]
+    command: Commands,
+}
+```
+
+## Argument Groups
+
+```rust
+use clap::{Args, Parser};
+
+#[derive(Args)]
+#[group(required = true, multiple = false)]
+struct Target {
+    /// Target by ID
+    #[arg(long)]
+    id: Option<u64>,
+
+    /// Target by name
+    #[arg(long)]
+    name: Option<String>,
+}
+
+#[derive(Parser)]
+struct Cli {
+    #[command(flatten)]
+    target: Target,
+}
+```
+
+## Validation
+
+```rust
+use clap::Parser;
+
+fn validate_port(s: &str) -> Result<u16, String> {
+    let port: u16 = s.parse().map_err(|_| "not a number")?;
+    if port > 0 {
+        Ok(port)
+    } else {
+        Err("port must be positive".to_string())
+    }
+}
+
+#[derive(Parser)]
+struct Cli {
+    #[arg(long, value_parser = validate_port)]
+    port: u16,
+}
+```