🎨 style(cli): apply rustfmt formatting standards to CLI modules
- Apply cargo fmt to ensure consistent code formatting across CLI modules - Fix trailing whitespace in documentation comments - Optimize comment formatting and indentation - All clippy checks pass with no warnings - Documentation generates cleanly with strict nightly flags - All tests continue to pass after formatting changes
This commit is contained in:
Jeremiah Russell
committed by
Jeremiah Russell
Jeremiah Russell
parent
97947033ce
commit
3979379795
@@ -83,18 +83,18 @@ use clap::{Parser, Subcommand};
|
||||
use cull_gmail::{GmailClient, MessageList, Result, RuleProcessor};
|
||||
|
||||
/// Available actions for Gmail message operations.
|
||||
///
|
||||
///
|
||||
/// This enum defines the three primary operations that can be performed on Gmail messages
|
||||
/// through the CLI, each with different levels of safety and reversibility.
|
||||
///
|
||||
///
|
||||
/// # Action Safety Levels
|
||||
///
|
||||
///
|
||||
/// - **List**: Safe inspection operation with no modifications
|
||||
/// - **Trash**: Recoverable operation (messages can be restored for ~30 days)
|
||||
/// - **Delete**: Permanent operation (irreversible)
|
||||
///
|
||||
///
|
||||
/// # Usage Context
|
||||
///
|
||||
///
|
||||
/// Actions are typically used in this progression:
|
||||
/// 1. **List** - Preview messages that match criteria
|
||||
/// 2. **Trash** - Move messages to recoverable trash
|
||||
@@ -102,25 +102,25 @@ use cull_gmail::{GmailClient, MessageList, Result, RuleProcessor};
|
||||
#[derive(Debug, Subcommand)]
|
||||
enum MessageAction {
|
||||
/// Display message information without making any changes.
|
||||
///
|
||||
///
|
||||
/// This is the safest operation, showing message details including:
|
||||
/// - Message subject and sender
|
||||
/// - Date and size information
|
||||
/// - Labels and threading information
|
||||
/// - Internal Gmail message IDs
|
||||
List,
|
||||
|
||||
|
||||
/// Move messages to Gmail's Trash folder.
|
||||
///
|
||||
///
|
||||
/// This operation:
|
||||
/// - Moves messages to the Trash label
|
||||
/// - Allows recovery for approximately 30 days
|
||||
/// - Is reversible through Gmail's web interface
|
||||
/// - Provides a safety buffer before permanent deletion
|
||||
Trash,
|
||||
|
||||
|
||||
/// Permanently delete messages from Gmail.
|
||||
///
|
||||
///
|
||||
/// **WARNING**: This operation is irreversible!
|
||||
/// - Messages are permanently removed from Gmail
|
||||
/// - No recovery is possible after deletion
|
||||
@@ -130,43 +130,43 @@ enum MessageAction {
|
||||
}
|
||||
|
||||
/// Command-line interface for Gmail message querying and batch operations.
|
||||
///
|
||||
///
|
||||
/// This structure encapsulates all configuration options for the messages subcommand,
|
||||
/// providing comprehensive filtering, pagination, and action capabilities for Gmail
|
||||
/// message management. It supports complex queries using Gmail's search syntax and
|
||||
/// multiple filtering mechanisms.
|
||||
///
|
||||
///
|
||||
/// # Configuration Categories
|
||||
///
|
||||
///
|
||||
/// - **Pagination**: Control result set size and page limits
|
||||
/// - **Filtering**: Label-based and query-based message selection
|
||||
/// - **Actions**: Operations to perform on selected messages
|
||||
///
|
||||
///
|
||||
/// # Usage Patterns
|
||||
///
|
||||
///
|
||||
/// ## Safe Exploration
|
||||
/// ```bash
|
||||
/// # Start with list to preview results
|
||||
/// cull-gmail messages -Q "older_than:1y" list
|
||||
///
|
||||
///
|
||||
/// # Then perform actions on the same query
|
||||
/// cull-gmail messages -Q "older_than:1y" trash
|
||||
/// ```
|
||||
///
|
||||
///
|
||||
/// ## Controlled Processing
|
||||
/// ```bash
|
||||
/// # Process in small batches
|
||||
/// cull-gmail messages -m 50 -p 5 -Q "label:newsletters" list
|
||||
/// ```
|
||||
///
|
||||
///
|
||||
/// ## Multi-Criteria Filtering
|
||||
/// ```bash
|
||||
/// # Combine labels and query filters
|
||||
/// cull-gmail messages -l "promotions" -l "social" -Q "older_than:6m" trash
|
||||
/// ```
|
||||
///
|
||||
///
|
||||
/// # Safety Considerations
|
||||
///
|
||||
///
|
||||
/// - Always use `list` action first to preview results
|
||||
/// - Start with small page sizes for destructive operations
|
||||
/// - Use `trash` instead of `delete` when possible for recoverability
|
||||
@@ -174,21 +174,21 @@ enum MessageAction {
|
||||
#[derive(Debug, Parser)]
|
||||
pub struct MessagesCli {
|
||||
/// Maximum number of messages to retrieve per page.
|
||||
///
|
||||
///
|
||||
/// Controls the batch size for Gmail API requests. Larger values are more
|
||||
/// efficient but may hit API rate limits. Smaller values provide more
|
||||
/// granular control and progress feedback.
|
||||
///
|
||||
///
|
||||
/// **Range**: 1-500 (Gmail API limit)
|
||||
/// **Performance**: 100-200 is typically optimal
|
||||
#[arg(short, long,display_order = 1, help_heading = "Config", default_value = cull_gmail::DEFAULT_MAX_RESULTS)]
|
||||
max_results: u32,
|
||||
|
||||
|
||||
/// Maximum number of pages to process.
|
||||
///
|
||||
///
|
||||
/// Limits the total number of API requests and messages processed.
|
||||
/// Use 0 for unlimited pages (process all matching messages).
|
||||
///
|
||||
///
|
||||
/// **Safety**: Start with 1-2 pages for testing destructive operations
|
||||
/// **Performance**: Higher values process more messages but take longer
|
||||
#[arg(
|
||||
@@ -199,32 +199,32 @@ pub struct MessagesCli {
|
||||
default_value = "1"
|
||||
)]
|
||||
pages: u32,
|
||||
|
||||
|
||||
/// Gmail labels to filter messages (can be specified multiple times).
|
||||
///
|
||||
///
|
||||
/// Filters messages to only those containing ALL specified labels.
|
||||
/// Use `cull-gmail labels` to see available labels in your account.
|
||||
///
|
||||
/// **Examples**:
|
||||
///
|
||||
/// **Examples**:
|
||||
/// - `-l "INBOX"` - Messages in inbox
|
||||
/// - `-l "promotions" -l "unread"` - Unread promotional messages
|
||||
#[arg(short, long, display_order = 1, help_heading = "Config")]
|
||||
labels: Vec<String>,
|
||||
|
||||
|
||||
/// Gmail query string using Gmail's advanced search syntax.
|
||||
///
|
||||
///
|
||||
/// Supports the same query syntax as Gmail's web interface search box.
|
||||
/// Can be combined with label filters for more precise targeting.
|
||||
///
|
||||
///
|
||||
/// **Examples**:
|
||||
/// - `"older_than:1y"` - Messages older than 1 year
|
||||
/// - `"from:noreply@example.com older_than:30d"` - Old automated emails
|
||||
/// - `"has:attachment larger:10M"` - Large attachments
|
||||
#[arg(short = 'Q', long, display_order = 1, help_heading = "Config")]
|
||||
query: Option<String>,
|
||||
|
||||
|
||||
/// Action to perform on the filtered messages.
|
||||
///
|
||||
///
|
||||
/// Determines what operation to execute on messages matching the filter criteria.
|
||||
/// Actions range from safe inspection (list) to permanent deletion (delete).
|
||||
#[command(subcommand)]
|
||||
@@ -233,52 +233,52 @@ pub struct MessagesCli {
|
||||
|
||||
impl MessagesCli {
|
||||
/// Executes the messages command with the configured parameters and action.
|
||||
///
|
||||
///
|
||||
/// This method orchestrates the complete message processing workflow:
|
||||
/// 1. **Parameter Configuration**: Apply filters, pagination, and query settings
|
||||
/// 2. **Message Retrieval**: Fetch messages from Gmail API based on criteria
|
||||
/// 3. **Action Execution**: Perform the specified operation on retrieved messages
|
||||
///
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
///
|
||||
/// * `client` - Mutable Gmail client for API operations and state management
|
||||
///
|
||||
///
|
||||
/// # Returns
|
||||
///
|
||||
///
|
||||
/// Returns `Result<()>` indicating success or failure of the complete operation.
|
||||
///
|
||||
///
|
||||
/// # Processing Flow
|
||||
///
|
||||
///
|
||||
/// ## Parameter Setup
|
||||
/// - Apply label filters to restrict message scope
|
||||
/// - Configure Gmail query string for advanced filtering
|
||||
/// - Set pagination parameters for controlled processing
|
||||
///
|
||||
///
|
||||
/// ## Message Retrieval
|
||||
/// - Execute Gmail API requests to fetch matching messages
|
||||
/// - Handle pagination according to configured limits
|
||||
/// - Process results in manageable batches
|
||||
///
|
||||
///
|
||||
/// ## Action Execution
|
||||
/// - **List**: Display message information with logging level awareness
|
||||
/// - **Trash**: Move messages to Gmail Trash (recoverable)
|
||||
/// - **Delete**: Permanently remove messages (irreversible)
|
||||
///
|
||||
///
|
||||
/// # Error Handling
|
||||
///
|
||||
///
|
||||
/// The method handles various error conditions:
|
||||
/// - **Parameter errors**: Invalid labels or malformed queries
|
||||
/// - **API errors**: Network issues, authentication failures, rate limits
|
||||
/// - **Action errors**: Failures during trash or delete operations
|
||||
///
|
||||
///
|
||||
/// # Performance Considerations
|
||||
///
|
||||
///
|
||||
/// - **Batch processing**: Messages are processed in configurable batches
|
||||
/// - **Rate limiting**: Respects Gmail API quotas and limits
|
||||
/// - **Memory management**: Efficient handling of large result sets
|
||||
///
|
||||
///
|
||||
/// # Safety Features
|
||||
///
|
||||
///
|
||||
/// - **Logging awareness**: List output adapts to logging verbosity
|
||||
/// - **Error isolation**: Individual message failures don't stop batch processing
|
||||
/// - **Progress tracking**: Detailed logging for operation monitoring
|
||||
@@ -303,45 +303,45 @@ impl MessagesCli {
|
||||
}
|
||||
|
||||
/// Configures the Gmail client with filtering and pagination parameters.
|
||||
///
|
||||
///
|
||||
/// This method applies all user-specified configuration to the Gmail client,
|
||||
/// preparing it for message retrieval operations. It handles label filters,
|
||||
/// query strings, and pagination settings with comprehensive error checking.
|
||||
///
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
///
|
||||
/// * `client` - Mutable Gmail client to configure
|
||||
///
|
||||
///
|
||||
/// # Returns
|
||||
///
|
||||
///
|
||||
/// Returns `Result<()>` indicating success or failure of parameter configuration.
|
||||
///
|
||||
///
|
||||
/// # Configuration Steps
|
||||
///
|
||||
///
|
||||
/// ## Label Filtering
|
||||
/// - Validates label names against available Gmail labels
|
||||
/// - Applies multiple label filters with AND logic
|
||||
/// - Skips label configuration if no labels specified
|
||||
///
|
||||
///
|
||||
/// ## Query Configuration
|
||||
/// - Applies Gmail query string if provided
|
||||
/// - Combines with label filters for refined targeting
|
||||
/// - Uses Gmail's native query syntax parsing
|
||||
///
|
||||
///
|
||||
/// ## Pagination Setup
|
||||
/// - Configures maximum results per page for API efficiency
|
||||
/// - Logs configuration values for debugging and verification
|
||||
/// - Ensures values are within Gmail API limits
|
||||
///
|
||||
///
|
||||
/// # Error Conditions
|
||||
///
|
||||
///
|
||||
/// The method can fail due to:
|
||||
/// - **Invalid labels**: Label names that don't exist in the Gmail account
|
||||
/// - **Malformed queries**: Query syntax that Gmail API cannot parse
|
||||
/// - **Parameter limits**: Values outside Gmail API acceptable ranges
|
||||
///
|
||||
///
|
||||
/// # Logging
|
||||
///
|
||||
///
|
||||
/// Configuration steps are logged at appropriate levels:
|
||||
/// - **Trace**: Detailed parameter values for debugging
|
||||
/// - **Debug**: Configuration confirmation and validation results
|
||||
@@ -362,13 +362,13 @@ impl MessagesCli {
|
||||
}
|
||||
|
||||
/// Returns a reference to the configured Gmail labels for filtering.
|
||||
///
|
||||
///
|
||||
/// This accessor provides access to the list of labels that will be used
|
||||
/// to filter messages. Labels are combined with AND logic, meaning messages
|
||||
/// must have ALL specified labels to be included in results.
|
||||
///
|
||||
///
|
||||
/// # Returns
|
||||
///
|
||||
///
|
||||
/// Returns a reference to the vector of label names as configured by the user.
|
||||
/// An empty vector indicates no label-based filtering will be applied.
|
||||
pub(crate) fn labels(&self) -> &Vec<String> {
|
||||
@@ -376,13 +376,13 @@ impl MessagesCli {
|
||||
}
|
||||
|
||||
/// Returns a reference to the configured Gmail query string.
|
||||
///
|
||||
///
|
||||
/// This accessor provides access to the advanced query string that will be
|
||||
/// applied to message filtering. The query uses Gmail's native search syntax
|
||||
/// and can be combined with label filters for precise targeting.
|
||||
///
|
||||
///
|
||||
/// # Returns
|
||||
///
|
||||
///
|
||||
/// Returns a reference to the optional query string. `None` indicates
|
||||
/// no advanced query filtering will be applied.
|
||||
pub(crate) fn query(&self) -> &Option<String> {
|
||||
@@ -390,13 +390,13 @@ impl MessagesCli {
|
||||
}
|
||||
|
||||
/// Returns the maximum number of messages to retrieve per page.
|
||||
///
|
||||
///
|
||||
/// This accessor provides the configured batch size for Gmail API requests.
|
||||
/// The value determines how many messages are fetched in each API call,
|
||||
/// affecting both performance and memory usage.
|
||||
///
|
||||
///
|
||||
/// # Returns
|
||||
///
|
||||
///
|
||||
/// Returns the maximum results per page as configured by the user or default value.
|
||||
/// The value is guaranteed to be within Gmail API acceptable limits.
|
||||
pub(crate) fn max_results(&self) -> u32 {
|
||||
|
||||
Reference in New Issue
Block a user