aigroup-workflow 2.1.2 → 2.2.0

package/skills/rust-engineer/references/error-handling.md

@@ -1,334 +0,0 @@
-# Error Handling in Rust
-
-## Result and Option Basics
-
-```rust
-// Result: operation that can fail
-fn divide(a: f64, b: f64) -> Result<f64, String> {
-    if b == 0.0 {
-        Err("Division by zero".to_string())
-    } else {
-        Ok(a / b)
-    }
-}
-
-// Option: value that might be absent
-fn find_user(id: u64) -> Option<User> {
-    if id == 1 {
-        Some(User { id, name: "Alice".to_string() })
-    } else {
-        None
-    }
-}
-
-// Using ? operator for propagation
-fn calculate(a: f64, b: f64, c: f64) -> Result<f64, String> {
-    let x = divide(a, b)?;  // Returns Err early if division fails
-    let y = divide(x, c)?;
-    Ok(y)
-}
-```
-
-## Custom Error Types
-
-```rust
-use std::fmt;
-
-// Manual error type
-#[derive(Debug)]
-enum AppError {
-    NotFound(String),
-    InvalidInput(String),
-    DatabaseError(String),
-}
-
-impl fmt::Display for AppError {
-    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
-        match self {
-            AppError::NotFound(msg) => write!(f, "Not found: {}", msg),
-            AppError::InvalidInput(msg) => write!(f, "Invalid input: {}", msg),
-            AppError::DatabaseError(msg) => write!(f, "Database error: {}", msg),
-        }
-    }
-}
-
-impl std::error::Error for AppError {}
-
-// Usage
-fn get_user(id: u64) -> Result<User, AppError> {
-    if id == 0 {
-        return Err(AppError::InvalidInput("ID cannot be zero".to_string()));
-    }
-    // ... fetch user
-    Err(AppError::NotFound(format!("User {} not found", id)))
-}
-```
-
-## Using thiserror
-
-```rust
-use thiserror::Error;
-
-#[derive(Error, Debug)]
-enum DataError {
-    #[error("Data not found: {0}")]
-    NotFound(String),
-
-    #[error("Invalid ID: {id}, reason: {reason}")]
-    InvalidId { id: u64, reason: String },
-
-    #[error("IO error")]
-    Io(#[from] std::io::Error),
-
-    #[error("Parse error")]
-    Parse(#[from] std::num::ParseIntError),
-
-    #[error("Database error: {0}")]
-    Database(#[from] sqlx::Error),
-}
-
-// Usage with automatic conversions
-fn read_config(path: &str) -> Result<Config, DataError> {
-    let content = std::fs::read_to_string(path)?;  // Auto-converts io::Error
-    let port: u16 = content.parse()?;  // Auto-converts ParseIntError
-    Ok(Config { port })
-}
-```
-
-## Using anyhow for Applications
-
-```rust
-use anyhow::{Result, Context, bail, ensure};
-
-// Simple error handling for applications
-fn process_file(path: &str) -> Result<()> {
-    let content = std::fs::read_to_string(path)
-        .context(format!("Failed to read file: {}", path))?;
-
-    ensure!(!content.is_empty(), "File is empty");
-
-    if content.len() > 1000 {
-        bail!("File too large");
-    }
-
-    // Process content...
-    Ok(())
-}
-
-// Adding context to errors
-fn main() -> Result<()> {
-    process_file("config.txt")
-        .context("Failed to process configuration")?;
-    Ok(())
-}
-```
-
-## Option Combinators
-
-```rust
-// map: transform Option<T> to Option<U>
-let num: Option<i32> = Some(5);
-let doubled = num.map(|n| n * 2);  // Some(10)
-
-// and_then: chain operations
-let result = Some(5)
-    .and_then(|n| if n > 0 { Some(n * 2) } else { None })
-    .and_then(|n| Some(n + 1));  // Some(11)
-
-// or: provide alternative
-let value = None.or(Some(42));  // Some(42)
-
-// unwrap_or: provide default
-let value = None.unwrap_or(42);  // 42
-
-// unwrap_or_else: compute default lazily
-let value = None.unwrap_or_else(|| expensive_computation());
-
-// filter: conditional None
-let num = Some(5).filter(|&n| n > 10);  // None
-
-// Pattern matching
-match find_user(1) {
-    Some(user) => println!("Found: {}", user.name),
-    None => println!("User not found"),
-}
-
-// if let for simple cases
-if let Some(user) = find_user(1) {
-    println!("Found: {}", user.name);
-}
-```
-
-## Result Combinators
-
-```rust
-// map: transform Ok value
-let result: Result<i32, String> = Ok(5);
-let doubled = result.map(|n| n * 2);  // Ok(10)
-
-// map_err: transform error
-let result: Result<i32, &str> = Err("error");
-let mapped = result.map_err(|e| e.to_uppercase());  // Err("ERROR")
-
-// and_then: chain fallible operations
-fn parse_then_double(s: &str) -> Result<i32, std::num::ParseIntError> {
-    s.parse::<i32>()
-        .and_then(|n| Ok(n * 2))
-}
-
-// or_else: provide alternative computation
-let result = Err("error").or_else(|_| Ok(42));  // Ok(42)
-
-// unwrap_or: provide default
-let value = Err("error").unwrap_or(42);  // 42
-
-// expect: unwrap with custom panic message
-let value = result.expect("Failed to parse number");
-
-// Pattern matching
-match divide(10.0, 2.0) {
-    Ok(result) => println!("Result: {}", result),
-    Err(e) => eprintln!("Error: {}", e),
-}
-```
-
-## Error Conversion and From Trait
-
-```rust
-use std::io;
-use std::num::ParseIntError;
-
-#[derive(Debug)]
-enum MyError {
-    Io(io::Error),
-    Parse(ParseIntError),
-}
-
-impl From<io::Error> for MyError {
-    fn from(err: io::Error) -> Self {
-        MyError::Io(err)
-    }
-}
-
-impl From<ParseIntError> for MyError {
-    fn from(err: ParseIntError) -> Self {
-        MyError::Parse(err)
-    }
-}
-
-// Now ? operator works with automatic conversion
-fn read_and_parse(path: &str) -> Result<i32, MyError> {
-    let content = std::fs::read_to_string(path)?;  // io::Error -> MyError
-    let number = content.trim().parse()?;  // ParseIntError -> MyError
-    Ok(number)
-}
-```
-
-## Advanced Error Patterns
-
-```rust
-// Multiple error sources with Box<dyn Error>
-use std::error::Error;
-
-fn complex_operation() -> Result<String, Box<dyn Error>> {
-    let file = std::fs::read_to_string("data.txt")?;
-    let number: i32 = file.trim().parse()?;
-    Ok(format!("Number: {}", number))
-}
-
-// Error with backtrace (nightly)
-#[derive(Debug)]
-struct DetailedError {
-    message: String,
-    backtrace: std::backtrace::Backtrace,
-}
-
-impl DetailedError {
-    fn new(message: impl Into<String>) -> Self {
-        Self {
-            message: message.into(),
-            backtrace: std::backtrace::Backtrace::capture(),
-        }
-    }
-}
-
-// Recoverable vs unrecoverable errors
-fn might_fail(value: i32) -> Result<i32, String> {
-    if value < 0 {
-        Err("Negative value".to_string())  // Recoverable
-    } else if value > 1000 {
-        panic!("Value too large!");  // Unrecoverable
-    } else {
-        Ok(value * 2)
-    }
-}
-```
-
-## Try Blocks (Nightly)
-
-```rust
-#![feature(try_blocks)]
-
-// Try block for localized error handling
-let result: Result<i32, Box<dyn Error>> = try {
-    let file = std::fs::read_to_string("config.txt")?;
-    let num: i32 = file.trim().parse()?;
-    num * 2
-};
-```
-
-## Error Context Pattern
-
-```rust
-use thiserror::Error;
-
-#[derive(Error, Debug)]
-#[error("{message}")]
-struct ContextError {
-    message: String,
-    #[source]
-    source: Option<Box<dyn Error + Send + Sync>>,
-}
-
-impl ContextError {
-    fn new(message: impl Into<String>) -> Self {
-        Self {
-            message: message.into(),
-            source: None,
-        }
-    }
-
-    fn with_source(mut self, source: impl Error + Send + Sync + 'static) -> Self {
-        self.source = Some(Box::new(source));
-        self
-    }
-}
-
-// Extension trait for adding context
-trait Context<T> {
-    fn context(self, message: impl Into<String>) -> Result<T, ContextError>;
-}
-
-impl<T, E: Error + Send + Sync + 'static> Context<T> for Result<T, E> {
-    fn context(self, message: impl Into<String>) -> Result<T, ContextError> {
-        self.map_err(|e| ContextError::new(message).with_source(e))
-    }
-}
-```
-
-## Best Practices
-
-- Use Result for recoverable errors, panic! for unrecoverable bugs
-- Prefer ? operator over unwrap() in production code
-- Use expect() with descriptive messages instead of unwrap()
-- Use thiserror for libraries (structured errors)
-- Use anyhow for applications (simple error handling)
-- Implement std::error::Error trait for custom error types
-- Add context to errors as they propagate up the stack
-- Use #[from] in thiserror for automatic conversions
-- Document error conditions in function documentation
-- Use Option::ok_or() to convert Option to Result
-- Use Result::ok() to convert Result to Option (discarding error)
-- Avoid String as error type (use custom types instead)
-- Use ensure! and bail! from anyhow for cleaner checks
-- Log errors at boundaries, return them in library code

package/skills/rust-engineer/references/ownership.md

@@ -1,278 +0,0 @@
-# Ownership, Borrowing, and Lifetimes
-
-## Ownership Patterns
-
-```rust
-// Move semantics (ownership transfer)
-fn take_ownership(s: String) {
-    println!("{}", s);
-} // s dropped here
-
-// Borrowing (immutable reference)
-fn borrow(s: &String) {
-    println!("{}", s);
-} // s NOT dropped, caller still owns
-
-// Mutable borrowing
-fn borrow_mut(s: &mut String) {
-    s.push_str(" world");
-}
-
-// Usage
-let s = String::from("hello");
-borrow(&s);           // OK, immutable borrow
-let mut s2 = s;       // Move, s no longer valid
-borrow_mut(&mut s2);  // OK, mutable borrow
-```
-
-## Lifetime Annotations
-
-```rust
-// Explicit lifetime: returned reference lives as long as input
-fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
-    if x.len() > y.len() { x } else { y }
-}
-
-// Multiple lifetimes
-fn first_word<'a, 'b>(s: &'a str, _other: &'b str) -> &'a str {
-    s.split_whitespace().next().unwrap_or("")
-}
-
-// Lifetime in structs
-struct Excerpt<'a> {
-    part: &'a str,
-}
-
-impl<'a> Excerpt<'a> {
-    fn announce_and_return(&self, announcement: &str) -> &'a str {
-        println!("Attention: {}", announcement);
-        self.part
-    }
-}
-
-// Static lifetime (lives for entire program)
-const GREETING: &'static str = "Hello, world!";
-```
-
-## Smart Pointers
-
-```rust
-use std::rc::Rc;
-use std::cell::RefCell;
-use std::sync::{Arc, Mutex};
-
-// Box: heap allocation, single owner
-let b = Box::new(5);
-
-// Rc: reference counting (single-threaded)
-let rc1 = Rc::new(vec![1, 2, 3]);
-let rc2 = Rc::clone(&rc1);  // Increment count
-println!("Count: {}", Rc::strong_count(&rc1));  // 2
-
-// Arc: atomic reference counting (thread-safe)
-let arc1 = Arc::new(vec![1, 2, 3]);
-let arc2 = Arc::clone(&arc1);
-std::thread::spawn(move || {
-    println!("{:?}", arc2);
-});
-
-// RefCell: interior mutability (runtime borrow checking)
-let data = RefCell::new(5);
-*data.borrow_mut() += 1;  // Mutable borrow at runtime
-
-// Combining Rc + RefCell for shared mutable state
-let shared = Rc::new(RefCell::new(vec![1, 2, 3]));
-shared.borrow_mut().push(4);
-
-// Combining Arc + Mutex for thread-safe shared state
-let counter = Arc::new(Mutex::new(0));
-let counter_clone = Arc::clone(&counter);
-std::thread::spawn(move || {
-    let mut num = counter_clone.lock().unwrap();
-    *num += 1;
-});
-```
-
-## Interior Mutability
-
-```rust
-use std::cell::{Cell, RefCell};
-
-// Cell: Copy types only
-let c = Cell::new(5);
-c.set(10);
-let val = c.get();
-
-// RefCell: runtime borrow checking
-let data = RefCell::new(vec![1, 2, 3]);
-data.borrow_mut().push(4);
-
-// Pattern: mock objects with interior mutability
-struct MockLogger {
-    messages: RefCell<Vec<String>>,
-}
-
-impl MockLogger {
-    fn new() -> Self {
-        Self { messages: RefCell::new(Vec::new()) }
-    }
-
-    fn log(&self, msg: &str) {
-        self.messages.borrow_mut().push(msg.to_string());
-    }
-
-    fn get_messages(&self) -> Vec<String> {
-        self.messages.borrow().clone()
-    }
-}
-```
-
-## Pin and Self-Referential Types
-
-```rust
-use std::pin::Pin;
-use std::marker::PhantomPinned;
-
-// Self-referential struct (requires Pin)
-struct SelfReferential {
-    data: String,
-    pointer: *const String,
-    _pin: PhantomPinned,
-}
-
-impl SelfReferential {
-    fn new(data: String) -> Pin<Box<Self>> {
-        let mut boxed = Box::pin(Self {
-            data,
-            pointer: std::ptr::null(),
-            _pin: PhantomPinned,
-        });
-
-        // Safe: we're not moving the data after this
-        let ptr = &boxed.data as *const String;
-        unsafe {
-            let mut_ref = Pin::as_mut(&mut boxed);
-            Pin::get_unchecked_mut(mut_ref).pointer = ptr;
-        }
-
-        boxed
-    }
-}
-
-// Pin in async contexts
-async fn pinned_future() {
-    // Futures are often self-referential, hence Pin
-    let fut = async { 42 };
-    let pinned = Box::pin(fut);
-    pinned.await;
-}
-```
-
-## Cow (Clone on Write)
-
-```rust
-use std::borrow::Cow;
-
-fn process_text(input: &str) -> Cow<str> {
-    if input.contains("bad") {
-        // Need to modify: allocate new String
-        Cow::Owned(input.replace("bad", "good"))
-    } else {
-        // No modification needed: just borrow
-        Cow::Borrowed(input)
-    }
-}
-
-// Usage
-let text1 = "hello world";
-let result1 = process_text(text1);  // Borrowed (no allocation)
-
-let text2 = "bad word";
-let result2 = process_text(text2);  // Owned (allocated)
-```
-
-## Drop Trait and RAII
-
-```rust
-struct FileGuard {
-    name: String,
-}
-
-impl FileGuard {
-    fn new(name: String) -> Self {
-        println!("Opening {}", name);
-        Self { name }
-    }
-}
-
-impl Drop for FileGuard {
-    fn drop(&mut self) {
-        println!("Closing {}", self.name);
-    }
-}
-
-// Usage: automatic cleanup
-{
-    let _file = FileGuard::new("data.txt".to_string());
-    // Use file...
-} // Drop called automatically here
-```
-
-## Common Patterns
-
-```rust
-// Builder pattern with ownership
-struct Config {
-    host: String,
-    port: u16,
-}
-
-impl Config {
-    fn builder() -> ConfigBuilder {
-        ConfigBuilder::default()
-    }
-}
-
-struct ConfigBuilder {
-    host: Option<String>,
-    port: Option<u16>,
-}
-
-impl ConfigBuilder {
-    fn host(mut self, host: impl Into<String>) -> Self {
-        self.host = Some(host.into());
-        self
-    }
-
-    fn port(mut self, port: u16) -> Self {
-        self.port = Some(port);
-        self
-    }
-
-    fn build(self) -> Result<Config, &'static str> {
-        Ok(Config {
-            host: self.host.ok_or("host required")?,
-            port: self.port.unwrap_or(8080),
-        })
-    }
-}
-
-// Usage
-let config = Config::builder()
-    .host("localhost")
-    .port(3000)
-    .build()?;
-```
-
-## Best Practices
-
-- Prefer borrowing (&T) over ownership transfer when possible
-- Use &str over String for function parameters
-- Use &[T] over Vec<T> for function parameters
-- Clone only when necessary (profile first)
-- Use Cow<'a, T> for conditional cloning
-- Document lifetime relationships in complex cases
-- Use Arc<Mutex<T>> for shared mutable state across threads
-- Use Rc<RefCell<T>> for shared mutable state in single thread
-- Implement Drop for RAII patterns
-- Use PhantomData to constrain variance when needed