taskchampion-rb 0.9.0 → 0.9.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d661bc07cbe2c900550df0973e28fbc8ca3ed34fb8f607e91bdff8824239a6dc
-  data.tar.gz: e4c5b2908fcac0ec63dcaa1c9e179a6a0b17701cb9c04c884738b4977f86ed64
+  metadata.gz: 6d963e64502ad438957e3345671387a3915de84947a63bbcced83270f5c50848
+  data.tar.gz: 19309ecfe6ccf1a5a077a513a7b6ff769109ba7949c0282617b8b74e3b54f116
 SHA512:
-  metadata.gz: 7aa047cb7dc2adb780e8c2616f726126df2e07bc53e8a357d507d4742ef099a438ed126a7f5849bb43e86136b14dc8044a6038fe7104e94c9a633db6d61101d1
-  data.tar.gz: 5fb6d41847c431265d85114505b385e36d05c9e5dc7006c92c3c1e29a89adb015a2486f7620b613b28a8132bb1b30f3e6e4d777ee1ba81e623e17aaae7cc441b
+  metadata.gz: '052509a0688871de92bc3d4219d7c257b712b7f4b7f5693f4e051d2ff38f891d5b6095d66aaf0cec8d06466ec272ec1fe5bd7e166dd790fb2a0c649592a29d4b'
+  data.tar.gz: f21cca16bd5da5921474361eb81d18937a1e328313a4c3dac2ea521ccc4d7b93cf356816d11e67abfa7292bbcfb76e40548766b94718030e42a315a80c3e5531

data/TaskchampionRbErrors.md

@@ -0,0 +1,54 @@
+# Taskchampion Ruby Errors
+
+## Hierarchy
+
+```
+StandardError
+└── Taskchampion::Error
+    ├── Taskchampion::ThreadError
+    ├── Taskchampion::StorageError
+    ├── Taskchampion::ValidationError
+    ├── Taskchampion::ConfigError
+    └── Taskchampion::SyncError
+        └── Taskchampion::OutOfSyncError
+```
+
+## Error Classes
+
+- **`Taskchampion::Error`** — Base class for all Taskchampion errors.
+- **`Taskchampion::ThreadError`** — Raised when an object (Replica, Task, etc.) is accessed from a thread other than the one that created it.
+- **`Taskchampion::StorageError`** — Raised for database and storage failures (`Error::Database`), and for wrapped IO/SQLite/cloud infrastructure errors (`Error::Other`).
+- **`Taskchampion::ValidationError`** — Raised for incorrect API usage (`Error::Usage`): bad tag names, empty descriptions, invalid UUIDs, wrong argument types, invalid status symbols.
+- **`Taskchampion::ConfigError`** — Defined for compatibility; not raised by the current TaskChampion error variants. Missing sync keyword arguments raise Ruby `ArgumentError` instead.
+- **`Taskchampion::SyncError`** — Raised for server communication errors (`Error::Server`).
+- **`Taskchampion::OutOfSyncError`** — Raised when the local replica is irrecoverably out of sync with the server (`Error::OutOfSync`). Subclass of `SyncError`. Signals that re-syncing from scratch is required, not just a retry.
+
+## Mapping from TaskChampion Rust errors
+
+| Rust variant | Ruby class |
+|---|---|
+| `Error::Database(msg)` | `StorageError` |
+| `Error::Server(msg)` | `SyncError` |
+| `Error::OutOfSync` | `OutOfSyncError` |
+| `Error::Usage(msg)` | `ValidationError` |
+| `Error::Other(_)` / unknown | `StorageError` |
+
+## Usage
+
+Rescue any error via the base class or individually:
+
+```ruby
+begin
+  replica.sync(config)
+rescue Taskchampion::OutOfSyncError => e
+  # local replica is irrecoverably diverged — must re-sync from scratch
+rescue Taskchampion::SyncError => e
+  # transient server/network error — may retry
+rescue Taskchampion::StorageError => e
+  # database or IO failure
+rescue Taskchampion::ValidationError => e
+  # bad input
+rescue Taskchampion::Error => e
+  # catch-all for any Taskchampion error
+end
+```

data/ext/taskchampion/src/error.rs

@@ -6,7 +6,8 @@ pub fn init_errors(module: &RModule) -> Result<(), Error> {
     module.define_error("StorageError", error_class)?;
     module.define_error("ValidationError", error_class)?;
     module.define_error("ConfigError", error_class)?;
-    module.define_error("SyncError", error_class)?;
+    let sync_error_class = module.define_error("SyncError", error_class)?;
+    module.define_error("OutOfSyncError", sync_error_class)?;
     Ok(())
 }
 
@@ -34,45 +35,29 @@ pub fn validation_error() -> magnus::ExceptionClass {
         .expect("ValidationError class not initialized")
 }
 
-pub fn config_error() -> magnus::ExceptionClass {
+pub fn sync_error() -> magnus::ExceptionClass {
     let ruby = magnus::Ruby::get().expect("Ruby not available");
     let module = ruby.class_object().const_get::<_, RModule>("Taskchampion")
         .expect("Taskchampion module not found");
-    module.const_get::<_, magnus::ExceptionClass>("ConfigError")
-        .expect("ConfigError class not initialized")
+    module.const_get::<_, magnus::ExceptionClass>("SyncError")
+        .expect("SyncError class not initialized")
 }
 
-pub fn sync_error() -> magnus::ExceptionClass {
+pub fn out_of_sync_error() -> magnus::ExceptionClass {
     let ruby = magnus::Ruby::get().expect("Ruby not available");
     let module = ruby.class_object().const_get::<_, RModule>("Taskchampion")
         .expect("Taskchampion module not found");
-    module.const_get::<_, magnus::ExceptionClass>("SyncError")
-        .expect("SyncError class not initialized")
+    module.const_get::<_, magnus::ExceptionClass>("OutOfSyncError")
+        .expect("OutOfSyncError class not initialized")
 }
 
-// Enhanced error mapping function with context-aware error types
 pub fn map_taskchampion_error(error: taskchampion::Error) -> Error {
-    let error_msg = error.to_string();
-
-    // Map TaskChampion errors to appropriate Ruby error types based on error content
-    if error_msg.contains("No such file") || error_msg.contains("Permission denied") ||
-       error_msg.contains("storage") || error_msg.contains("database") {
-        Error::new(storage_error(), format!("Storage error: {}", error_msg))
-    } else if error_msg.contains("sync") || error_msg.contains("server") ||
-              error_msg.contains("network") || error_msg.contains("remote") {
-        Error::new(sync_error(), format!("Synchronization error: {}", error_msg))
-    } else if error_msg.contains("config") || error_msg.contains("invalid config") {
-        Error::new(config_error(), format!("Configuration error: {}", error_msg))
-    } else if error_msg.contains("invalid") || error_msg.contains("parse") ||
-              error_msg.contains("format") || error_msg.contains("validation") {
-        Error::new(validation_error(), format!("Validation error: {}", error_msg))
-    } else {
-        // Generic TaskChampion error for unknown types
-        let ruby = magnus::Ruby::get().expect("Ruby not available");
-        let module = ruby.class_object().const_get::<_, RModule>("Taskchampion")
-            .expect("Taskchampion module not found");
-        let error_class = module.const_get::<_, magnus::ExceptionClass>("Error")
-            .expect("Error class not initialized");
-        Error::new(error_class, format!("TaskChampion error: {}", error_msg))
+    match error {
+        taskchampion::Error::Database(msg) => Error::new(storage_error(), msg),
+        taskchampion::Error::Server(msg)   => Error::new(sync_error(), msg),
+        taskchampion::Error::OutOfSync     => Error::new(out_of_sync_error(),
+                                                 "Local replica is out of sync with the server"),
+        taskchampion::Error::Usage(msg)    => Error::new(validation_error(), msg),
+        _                                  => Error::new(storage_error(), error.to_string()),
     }
 }

data/ext/taskchampion/src/replica.rs

@@ -58,7 +58,7 @@ impl Replica {
         let tc_task = tc_replica.create_task(tc_uuid, &mut tc_ops).map_err(into_error)?;
 
         // Add the resulting operations to the provided Operations object
-        operations.extend_from_tc(tc_ops);
+        operations.extend_from_tc(tc_ops)?;
 
         // Convert to Ruby Task object
         let task = Task::from_tc_task(tc_task);

data/ext/taskchampion/src/task.rs

@@ -137,24 +137,22 @@ impl Task {
 
     fn get_uda(&self, namespace: String, key: String) -> Result<Value, Error> {
         let task = self.0.get()?;
-        match task.get_uda(&namespace, &key) {
+        let combined_key = if namespace.is_empty() { key } else { format!("{}.{}", namespace, key) };
+        match task.get_user_defined_attribute(&combined_key) {
             Some(value) => Ok(value.into_value()),
-            None => Ok(().into_value()), // () converts to nil in Magnus
+            None => Ok(().into_value()),
         }
     }
 
     fn udas(&self) -> Result<RArray, Error> {
         let task = self.0.get()?;
-        let udas: Vec<((String, String), String)> = task.get_udas()
-            .map(|((ns, key), value)| ((ns.to_string(), key.to_string()), value.to_string()))
+        let udas: Vec<(String, String)> = task.get_user_defined_attributes()
+            .map(|(key, value)| (key.to_string(), value.to_string()))
             .collect();
 
-        vec_to_ruby(udas, |(key_tuple, value)| {
+        vec_to_ruby(udas, |(key, value)| {
             let array = RArray::new();
-            let key_array = RArray::new();
-            key_array.push(key_tuple.0)?;
-            key_array.push(key_tuple.1)?;
-            array.push(key_array)?;
+            array.push(key)?;
             array.push(value)?;
             Ok(array.into_value())
         })
@@ -360,7 +358,7 @@ impl Task {
             Some(timestamp_str) => {
                 // Parse the string as Unix timestamp (seconds since epoch)
                 if let Ok(timestamp_secs) = timestamp_str.parse::<i64>() {
-                    use chrono::{DateTime, Utc};
+                    use chrono::DateTime;
                     if let Some(dt) = DateTime::from_timestamp(timestamp_secs, 0) {
                         return datetime_to_ruby(dt);
                     }
@@ -387,8 +385,9 @@ impl Task {
         }
 
         let mut task = self.0.get_mut()?;
+        let combined_key = format!("{}.{}", namespace, key);
         operations.with_inner_mut(|ops| {
-            task.set_uda(&namespace, &key, &value, ops)
+            task.set_user_defined_attribute(&combined_key, &value, ops)
         })?;
         Ok(())
     }
@@ -408,8 +407,9 @@ impl Task {
         }
 
         let mut task = self.0.get_mut()?;
+        let combined_key = format!("{}.{}", namespace, key);
         operations.with_inner_mut(|ops| {
-            task.remove_uda(&namespace, &key, ops)
+            task.remove_user_defined_attribute(&combined_key, ops)
         })?;
         Ok(())
     }

data/ext/taskchampion/src/thread_check.rs

@@ -32,12 +32,12 @@ impl<T> ThreadBound<T> {
         Ok(())
     }
 
-    pub fn get(&self) -> Result<std::cell::Ref<T>, Error> {
+    pub fn get(&self) -> Result<std::cell::Ref<'_, T>, Error> {
         self.check_thread()?;
         Ok(self.inner.borrow())
     }
 
-    pub fn get_mut(&self) -> Result<std::cell::RefMut<T>, Error> {
+    pub fn get_mut(&self) -> Result<std::cell::RefMut<'_, T>, Error> {
         self.check_thread()?;
         Ok(self.inner.borrow_mut())
     }

data/ext/taskchampion/src/util.rs

@@ -31,8 +31,6 @@ pub fn datetime_to_ruby(dt: DateTime<Utc>) -> Result<Value, Error> {
 
 /// Convert Ruby DateTime/Time/String to Rust DateTime<Utc> with enhanced validation
 pub fn ruby_to_datetime(value: Value) -> Result<DateTime<Utc>, Error> {
-    let ruby = magnus::Ruby::get().map_err(|e| Error::new(magnus::exception::runtime_error(), e.to_string()))?;
-
     // If it's a string, parse it
     if let Ok(s) = RString::try_convert(value) {
         let s = unsafe { s.as_str()? };
@@ -99,15 +97,6 @@ where
     }
 }
 
-/// Convert HashMap to Ruby Hash
-pub fn hashmap_to_ruby(map: HashMap<String, String>) -> Result<RHash, Error> {
-    let hash = RHash::new();
-    for (k, v) in map {
-        hash.aset(k, v)?;
-    }
-    Ok(hash)
-}
-
 /// Convert Ruby Hash to HashMap
 pub fn ruby_to_hashmap(hash: RHash) -> Result<HashMap<String, String>, Error> {
     let mut map = HashMap::new();
@@ -130,15 +119,3 @@ where
     Ok(array)
 }
 
-/// Convert Ruby Array to Vec
-pub fn ruby_to_vec<T, F>(array: RArray, converter: F) -> Result<Vec<T>, Error>
-where
-    F: Fn(Value) -> Result<T, Error>,
-{
-    let mut vec = Vec::with_capacity(array.len());
-    for i in 0..array.len() {
-        let value: Value = array.entry(i as isize)?;
-        vec.push(converter(value)?);
-    }
-    Ok(vec)
-}

data/lib/taskchampion/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Taskchampion
-  VERSION = "0.9.0"
+  VERSION = "0.9.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: taskchampion-rb
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.9.2
 platform: ruby
 authors:
 - Tim Case
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-10-16 00:00:00.000000000 Z
+date: 2026-05-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb_sys
@@ -41,6 +41,7 @@ files:
 - Cargo.toml
 - README.md
 - Rakefile
+- TaskchampionRbErrors.md
 - docs/ANNOTATION_IMPLEMENTATION.md
 - docs/API_REFERENCE.md
 - docs/THREAD_SAFETY.md