subcog: Instructions file for GitHub Copilot

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:

// 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:

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:

// 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:

/// 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
}