taskchampion-rb 0.9.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d661bc07cbe2c900550df0973e28fbc8ca3ed34fb8f607e91bdff8824239a6dc
-  data.tar.gz: e4c5b2908fcac0ec63dcaa1c9e179a6a0b17701cb9c04c884738b4977f86ed64
+  metadata.gz: 97cd610777ff12232ab4625cbbca59e2a9241d1789926dd9a5f21d982876f25d
+  data.tar.gz: d8b3232d7fe7fe9cdc518136e08e7b3873683c90ac32cf62e1947179f53ded8c
 SHA512:
-  metadata.gz: 7aa047cb7dc2adb780e8c2616f726126df2e07bc53e8a357d507d4742ef099a438ed126a7f5849bb43e86136b14dc8044a6038fe7104e94c9a633db6d61101d1
-  data.tar.gz: 5fb6d41847c431265d85114505b385e36d05c9e5dc7006c92c3c1e29a89adb015a2486f7620b613b28a8132bb1b30f3e6e4d777ee1ba81e623e17aaae7cc441b
+  metadata.gz: 61a011d70095d38bb2009a653fa151115b5327282977243cf6bc56947ab38d488b62a027470c363fe45ee40e17c5673f95857207ceb7d5f1d150b109dc60b469
+  data.tar.gz: 71e0d7baa33d944308f03d5ae5fb210b840b8834c7081980073e68f1649f2c21b86c0c7a39763a21f8c676019ae3d94bef1f82803071164c6963d59546c015c9

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,10 +6,19 @@ 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(())
 }
 
+pub fn base_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>("Error")
+        .expect("Error class not initialized")
+}
+
 pub fn thread_error() -> magnus::ExceptionClass {
     let ruby = magnus::Ruby::get().expect("Ruby not available");
     let module = ruby.class_object().const_get::<_, RModule>("Taskchampion")
@@ -34,45 +43,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/lib/taskchampion/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Taskchampion
-  VERSION = "0.9.0"
+  VERSION = "0.9.1"
 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.1
 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