subcog

# GitHub Copilot Instructions

This document provides context for GitHub Copilot when working with this Rust project.

## Project Context

This is a Rust crate using modern tooling:
- **Rust**: 1.80+ (2024 edition)
- **Build System**: Cargo
- **Linting**: clippy with pedantic and nursery lints
- **Formatting**: rustfmt
- **Testing**: Built-in test framework + proptest
- **Supply Chain Security**: cargo-deny

## Code Generation Guidelines

### Error Handling

Use `Result` types instead of panicking:

```rust
// Good - Returns Result
pub fn parse_value(input: &str) -> Result<i64, ParseError> {
    input.parse().map_err(|e| ParseError::InvalidFormat(e))
}

// Avoid - Panics on failure
pub fn parse_value(input: &str) -> i64 {
    input.parse().unwrap() // Never do this
}
```

Use `thiserror` for custom error types:

```rust
use thiserror::Error;

#[derive(Error, Debug)]
pub enum AppError {
    #[error("invalid input: {0}")]
    InvalidInput(String),

    #[error("operation failed: {operation}")]
    OperationFailed { operation: String },

    #[error(transparent)]
    Io(#[from] std::io::Error),
}
```

### Type Annotations

Provide explicit return types for public functions:

```rust
// Good - explicit return type
pub fn process_data(items: &[String]) -> Vec<ProcessedItem> {
    // implementation
}

// Avoid for public APIs
pub fn process_data(items: &[String]) -> impl Iterator<Item = ProcessedItem> {
    // implementation
}
```

### Documentation

Use doc comments with examples:

```rust
/// Processes a list of items according to the given configuration.
///
/// # Arguments
///
/// * `items` - The items to process.
/// * `config` - Configuration options for processing.
///
/// # Returns
///
/// A vector of processed items.
///
/// # Errors
///
/// Returns [`Error::InvalidInput`] if any item is invalid.
///
/// # Examples
///
/// ```rust
/// use {{crate_name}}::{process, Config};
///
/// let items = vec!["a", "b", "c"];
/// let config = Config::default();
/// let result = process(&items, &config)?;
/// # Ok::<(), {{crate_name}}::Error>(())
/// ```
pub fn process(items: &[&str], config: &Config) -> Result<Vec<Item>> {
    // implementation
}
```

### Ownership and Borrowing

Prefer borrowing over ownership when possible:

```rust
// Good - borrows the slice
pub fn sum_values(values: &[i64]) -> i64 {
    values.iter().sum()
}

// Avoid - takes ownership unnecessarily
pub fn sum_values(values: Vec<i64>) -> i64 {
    values.iter().sum()
}
```

Use `Cow` for efficient string handling:

```rust
use std::borrow::Cow;

pub fn normalize_name(name: &str) -> Cow<'_, str> {
    if name.contains(' ') {
        Cow::Owned(name.replace(' ', "_"))
    } else {
        Cow::Borrowed(name)
    }
}
```

### Structs and Enums

Use builder pattern for complex structs:

```rust
#[derive(Debug, Clone, Default)]
pub struct Config {
    pub timeout: Duration,
    pub retries: u32,
    pub verbose: bool,
}

impl Config {
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    #[must_use]
    pub fn with_timeout(mut self, timeout: Duration) -> Self {
        self.timeout = timeout;
        self
    }

    #[must_use]
    pub fn with_retries(mut self, retries: u32) -> Self {
        self.retries = retries;
        self
    }
}
```

### Testing

Write comprehensive unit tests:

```rust
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_add_positive_numbers() {
        assert_eq!(add(2, 3), 5);
    }

    #[test]
    fn test_divide_by_zero_returns_error() {
        let result = divide(10, 0);
        assert!(matches!(result, Err(Error::DivisionByZero)));
    }
}
```

Use proptest for property-based testing:

```rust
use proptest::prelude::*;

proptest! {
    #[test]
    fn add_is_commutative(a in any::<i64>(), b in any::<i64>()) {
        prop_assert_eq!(add(a, b), add(b, a));
    }
}
```

### Async Code

Use async/await with tokio:

```rust
pub async fn fetch_data(url: &str) -> Result<Data> {
    let response = reqwest::get(url).await?;
    let data = response.json().await?;
    Ok(data)
}
```

## Common Patterns

### Iterator Chains

```rust
let result: Vec<_> = items
    .iter()
    .filter(|item| item.is_valid())
    .map(|item| item.transform())
    .collect();
```

### Option and Result Combinators

```rust
// Option chaining
let value = config
    .get_setting("key")
    .and_then(|s| s.parse().ok())
    .unwrap_or_default();

// Result chaining with ?
fn process() -> Result<Output> {
    let data = load_data()?;
    let parsed = parse_data(&data)?;
    let result = transform(parsed)?;
    Ok(result)
}
```

### Const Functions

Prefer `const fn` for compile-time evaluation:

```rust
#[must_use]
pub const fn new() -> Self {
    Self { value: 0 }
}
```

## File Locations

- Source code: `src/`
- Library entry: `src/lib.rs`
- Binary entry: `src/main.rs`
- Integration tests: `tests/`
- Benchmarks: `benches/` (with criterion)

## Commands

```bash
cargo build           # Build
cargo test            # Run tests
cargo clippy          # Lint
cargo fmt             # Format
cargo doc --open      # Generate and view docs
cargo deny check      # Check supply chain
```