From dc41101dcbda3441027d1a81dfa43fa1bc93bcfe Mon Sep 17 00:00:00 2001
From: Jeremiah Russell <jerry@jrussell.ie>
Date: Thu, 30 Oct 2025 12:20:41 +0000
Subject: [PATCH] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20refactor(rules):=20execute?=
 =?UTF-8?q?=20rules=20by=20action?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- executes rules by action: `Trash` first, then `Delete`
- a label may have a `trash` and `delete` rule applied
---
 src/cli/main.rs | 10 ++++++----
 src/rules.rs    |  8 +++++++-
 2 files changed, 13 insertions(+), 5 deletions(-)

diff --git a/src/cli/main.rs b/src/cli/main.rs
index f5e4b5f..a8a284b 100644
--- a/src/cli/main.rs
+++ b/src/cli/main.rs
@@ -452,12 +452,13 @@ fn get_config() -> Result<(Config, ClientConfig)> {
     ))
 }
 
-/// Executes automated message retention rules across Gmail labels.
+/// Executes automated message retention rules across Gmail labels by action.
 ///
 /// This function orchestrates the rule-based message processing workflow by:
-/// 1. Organizing rules by their target labels
-/// 2. Processing each label according to its configured rule
-/// 3. Executing or simulating actions based on execution mode
+/// 1. Executing rules by action: `Trash` first, then `Delete`
+/// 2. Organizing rules by their target labels
+/// 3. Processing each label according to its configured rule
+/// 4. Executing or simulating actions based on execution mode
 ///
 /// # Arguments
 ///
@@ -506,6 +507,7 @@ async fn run_rules(client: &mut GmailClient, rules: Rules, execute: bool) -> Res
 /// * `client` - Mutable Gmail client for API operations
 /// * `rules` - Loaded rules configuration containing all retention policies
 /// * `execute` - Whether to actually perform actions (true) or dry-run (false)
+/// * `action` - The action the rule will execute
 ///
 /// # Returns
 ///
diff --git a/src/rules.rs b/src/rules.rs
index d90e89f..d5d2211 100644
--- a/src/rules.rs
+++ b/src/rules.rs
@@ -247,7 +247,13 @@ impl Rules {
         self.rules.values().flat_map(|rule| rule.labels()).collect()
     }
 
-    /// Find the id of the rule that contains a label
+    /// Find the ids of the rules that contains a label
+    ///
+    /// A label may have a `trash` and `delete` rule applied to return a
+    /// maximum of two rules.
+    ///
+    /// If a label has more than one `trash` or `delete` rules only the id
+    /// for the last rule will be returned.
     fn find_label(&self, label: &str) -> Vec<usize> {
         let mut rwl = Vec::new();