taskchampion-rb 0.3.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7110e37a7e2a8af13267d10879260e10b920b1ba49c3d9f5b124cc7d618862b
-  data.tar.gz: '029792b10587e8a680b80936e1156ac2e1a15d2ba19970219b4f1d5496570bc7'
+  metadata.gz: 494521791e308dacc686f45ef7ff87937a0038e46729092a4e145952971a5f56
+  data.tar.gz: ac3a7b7367b2d8565ac902981fb4c7a9ee45b7d0c825868b15591211debc733b
 SHA512:
-  metadata.gz: 7e7ba27d8a5202767273e9221d115640493dbba79b8de6563e0cfeb0d9d2c75945244f649d1874745c0c80fe769eb7efd089737843baf843c47dd3e649fa6db4
-  data.tar.gz: d75725f6f197a67195d290a44ebd045434c1ada09779551a2e3c08e8430e4cfd5c6266d86d000135bc444aea77ac945034cdb2218835d48f706e4b8961efea5f
+  metadata.gz: 3d5c1e59e10ac46d98a8fc30d666dac904fcf2d14742c12713a16050a7a67d87c21e1a42ebaf7d25762541d0335c3c36ab2cf6a93bd3ed778046cd1a739840f4
+  data.tar.gz: 8f69921b628b5b1803a940584b05dd46abc854e50d9a3555646a141298a6c2a55008b2c8ca60b508fd53566bc6d0bd28a69f8caf76021e37a56e9fbf69bd362c

data/.ruby-version

@@ -1 +1 @@
-3.2.0
+3.2.0

data/CLAUDE.md

@@ -0,0 +1,67 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build and Development Commands
+
+### Building the gem
+```bash
+bundle install
+bundle exec rake compile  # Compiles the Rust extension
+```
+
+### Running tests
+```bash
+bundle exec rake test              # Run all tests
+bundle exec rake test TEST=test/test_replica.rb  # Run specific test file
+```
+
+### Linting
+```bash
+bundle exec rake rubocop           # Run RuboCop linter
+```
+
+### Publishing new version
+```bash
+rake publish[patch]  # Bump patch version and release
+rake publish[minor]  # Bump minor version and release
+rake publish[major]  # Bump major version and release
+```
+
+## Architecture Overview
+
+This is a Ruby gem that provides bindings to TaskChampion (Rust library) for task management. The architecture consists of:
+
+### Key Components
+
+1. **Rust Extension** (`ext/taskchampion/`)
+   - Written in Rust using Magnus for Ruby-Rust interop
+   - Entry point: `ext/taskchampion/src/lib.rs`
+   - Implements core classes: Replica, Task, WorkingSet, Operations, etc.
+   - Thread safety enforced via `thread_check.rs` - objects can only be accessed from their creation thread
+
+2. **Ruby Layer** (`lib/taskchampion.rb`)
+   - Thin wrapper that loads the Rust extension
+   - Extends WorkingSet and Replica classes with Ruby-specific convenience methods
+   - Maintains Ruby idioms (snake_case methods, `?` suffix for booleans)
+
+3. **Core Classes**
+   - `Replica`: Main database interface for task storage (in-memory or on-disk)
+   - `Task`: Individual task with properties and methods
+   - `Operations`: Collection of operations for batch changes
+   - `WorkingSet`: Active subset of tasks
+   - `DependencyMap`: Task dependency management
+   - Error hierarchy: Error → ThreadError, StorageError, ValidationError, ConfigError
+
+### Testing Structure
+- Uses Minitest framework
+- Tests organized in `test/unit/`, `test/integration/`, and `test/performance/`
+- Base test class: `TaskchampionTest` in `test/test_helper.rb`
+- Tests use temporary directories for file-based replicas
+
+### Ruby API Design Principles
+- Methods use snake_case (not get_/set_ prefixes)
+- Boolean methods end with `?`
+- Symbols for enums (`:pending`, `:completed`, `:read_only`)
+- `nil` instead of None
+- Keyword arguments for optional parameters

data/examples/basic_usage.rb

@@ -18,7 +18,7 @@ db_path = File.join(temp_dir, "tasks")
 begin
   # 1. CREATE TASK DATABASE
   puts "\n1. Creating task database at #{db_path}"
-  replica = Taskchampion::Replica.new_on_disk(db_path, create_if_missing: true)
+  replica = Taskchampion::Replica.new_on_disk(db_path, true, :read_write)
 
   # 2. CREATE AND MODIFY TASKS
   puts "\n2. Creating and modifying tasks"
@@ -39,8 +39,7 @@ begin
   task1.add_tag(Taskchampion::Tag.new("ruby"), operations)
 
   # Add annotation
-  annotation = Taskchampion::Annotation.new(Time.now, "Started learning TaskChampion")
-  task1.add_annotation(annotation, operations)
+  task1.add_annotation("Started learning TaskChampion", operations)
 
   # Create second task
   uuid2 = SecureRandom.uuid
@@ -61,7 +60,6 @@ begin
   task3.set_description("Read TaskChampion documentation", operations)
   task3.set_status(Taskchampion::Status.completed, operations)
   task3.add_tag(Taskchampion::Tag.new("learning"), operations)
-  task3.set_end(Time.now, operations)
 
   # 3. COMMIT CHANGES TO STORAGE
   puts "\n3. Committing changes to storage"
@@ -88,14 +86,13 @@ begin
 
     # Display tags
     if !task.tags.empty?
-      tag_names = task.tags.map(&:name)
+      tag_names = task.tags.map(&:to_s)
       puts "  Tags: #{tag_names.join(', ')}"
     end
 
     # Display dates
     puts "  Created: #{task.entry.strftime('%Y-%m-%d %H:%M:%S')}" if task.entry
     puts "  Due: #{task.due.strftime('%Y-%m-%d %H:%M:%S')}" if task.due
-    puts "  Completed: #{task.end.strftime('%Y-%m-%d %H:%M:%S')}" if task.end
 
     # Display annotations
     if !task.annotations.empty?
@@ -136,29 +133,42 @@ begin
 
   # Find tasks due today or tomorrow
   tomorrow = Time.now + 86400
-  due_soon = all_tasks.select { |t| t.due && t.due <= tomorrow }
+  due_soon = all_tasks.select { |t| t.due && t.due.to_time <= tomorrow }
   puts "Tasks due soon: #{due_soon.length}"
 
   # 6. MODIFY EXISTING TASKS
   puts "\n6. Modifying existing tasks"
 
-  # Complete the first task
+  # Complete the first task using the done method
   operations2 = Taskchampion::Operations.new
 
   # Retrieve task fresh from storage
   task_to_complete = replica.task(uuid1)
   if task_to_complete && task_to_complete.pending?
     puts "Completing task: #{task_to_complete.description}"
-    task_to_complete.set_status(Taskchampion::Status.completed, operations2)
-    task_to_complete.set_end(Time.now, operations2)
+
+    # Use the done() method - a convenience method for marking tasks as completed
+    task_to_complete.done(operations2)
 
     # Add completion annotation
-    completion_note = Taskchampion::Annotation.new(Time.now, "Completed successfully!")
-    task_to_complete.add_annotation(completion_note, operations2)
+    task_to_complete.add_annotation("Completed successfully!", operations2)
 
     # Commit the changes
     replica.commit_operations(operations2)
-    puts "Task completed and committed"
+    puts "Task completed using done() method and committed"
+  end
+
+  # Complete the second task using traditional set_status for comparison
+  operations2b = Taskchampion::Operations.new
+  task_to_complete2 = replica.task(uuid2)
+  if task_to_complete2 && task_to_complete2.pending?
+    puts "Completing second task: #{task_to_complete2.description}"
+
+    # Alternative way: using set_status directly
+    task_to_complete2.set_status(Taskchampion::Status.completed, operations2b)
+
+    replica.commit_operations(operations2b)
+    puts "Task completed using set_status() method and committed"
   end
 
   # 7. WORKING WITH WORKING SET

data/examples/pending_tasks.rb

@@ -0,0 +1,56 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'taskchampion'
+require 'securerandom'
+
+# Create an in-memory replica
+replica = Taskchampion::Replica.new_in_memory
+
+# Create several tasks with different statuses
+puts "Creating tasks..."
+
+# Create pending tasks
+3.times do |i|
+  ops = Taskchampion::Operations.new
+  task = replica.create_task(SecureRandom.uuid, ops)
+  task.set_description("Pending task #{i + 1}", ops)
+  task.set_status(Taskchampion::PENDING, ops)
+  replica.commit_operations(ops)
+  puts "  Created pending task: #{task.description}"
+end
+
+# Create completed tasks
+2.times do |i|
+  ops = Taskchampion::Operations.new
+  task = replica.create_task(SecureRandom.uuid, ops)
+  task.set_description("Completed task #{i + 1}", ops)
+  task.set_status(Taskchampion::COMPLETED, ops)
+  replica.commit_operations(ops)
+  puts "  Created completed task: #{task.description}"
+end
+
+# Create a deleted task
+ops = Taskchampion::Operations.new
+task = replica.create_task(SecureRandom.uuid, ops)
+task.set_description("Deleted task", ops)
+task.set_status(Taskchampion::DELETED, ops)
+replica.commit_operations(ops)
+puts "  Created deleted task: #{task.description}"
+
+puts "\n" + "=" * 50
+puts "Getting pending tasks..."
+puts "=" * 50
+
+# Use the pending_tasks method to get only pending tasks
+pending = replica.pending_tasks
+
+puts "\nFound #{pending.length} pending tasks:"
+pending.each_with_index do |task, index|
+  puts "  #{index + 1}. [#{task.uuid[0..7]}...] #{task.description}"
+  puts "     Status: #{task.status}"
+  puts "     Active: #{task.active?}"
+end
+
+puts "\n" + "=" * 50
+puts "For comparison, all_tasks returns #{replica.all_tasks.size} tasks total"

data/ext/taskchampion/src/replica.rs

@@ -260,6 +260,20 @@ impl Replica {
 
         Ok(tc_replica.num_undo_points().map_err(into_error)?)
     }
+
+    fn pending_tasks(&self) -> Result<RArray, Error> {
+        let mut tc_replica = self.0.get_mut()?;
+
+        let tc_tasks = tc_replica.pending_tasks().map_err(into_error)?;
+
+        let array = RArray::new();
+        for tc_task in tc_tasks {
+            let ruby_task = crate::task::Task::from_tc_task(tc_task);
+            array.push(ruby_task)?;
+        }
+
+        Ok(array)
+    }
 }
 
 pub fn init(module: &RModule) -> Result<(), Error> {
@@ -285,6 +299,7 @@ pub fn init(module: &RModule) -> Result<(), Error> {
     class.define_method("expire_tasks", method!(Replica::expire_tasks, 0))?;
     class.define_method("num_local_operations", method!(Replica::num_local_operations, 0))?;
     class.define_method("num_undo_points", method!(Replica::num_undo_points, 0))?;
+    class.define_method("pending_tasks", method!(Replica::pending_tasks, 0))?;
 
     Ok(())
 }

data/ext/taskchampion/src/task.rs

@@ -7,7 +7,7 @@ use crate::annotation::Annotation;
 use crate::status::Status;
 use crate::tag::Tag;
 use crate::thread_check::ThreadBound;
-use crate::util::{datetime_to_ruby, into_error, option_to_ruby, ruby_to_datetime, ruby_to_option, vec_to_ruby};
+use crate::util::{datetime_to_ruby, option_to_ruby, ruby_to_datetime, ruby_to_option, vec_to_ruby};
 
 #[magnus::wrap(class = "Taskchampion::Task", free_immediately)]
 pub struct Task(ThreadBound<TCTask>);
@@ -326,6 +326,14 @@ impl Task {
         Ok(())
     }
 
+    fn done(&self, operations: &crate::operations::Operations) -> Result<(), Error> {
+        let mut task = self.0.get_mut()?;
+        operations.with_inner_mut(|ops| {
+            task.done(ops)
+        })?;
+        Ok(())
+    }
+
 }
 
 // Remove AsRef implementation as it doesn't work well with thread bounds
@@ -384,5 +392,6 @@ pub fn init(module: &RModule) -> Result<(), Error> {
     class.define_method("set_value", method!(Task::set_value, 3))?;
     class.define_method("set_uda", method!(Task::set_uda, 4))?;
     class.define_method("delete_uda", method!(Task::delete_uda, 3))?;
+    class.define_method("done", method!(Task::done, 1))?;
     Ok(())
 }

data/ext/taskchampion/src/task_data.rs

@@ -14,8 +14,6 @@ impl TaskData {
     pub fn from_tc_task_data(tc_task_data: TCTaskData) -> Self {
         TaskData(ThreadBound::new(tc_task_data))
     }
-
-
     fn inspect(&self) -> Result<String, Error> {
         let task_data = self.0.get()?;
         Ok(format!("#<Taskchampion::TaskData: {}>", task_data.get_uuid()))
@@ -45,11 +43,11 @@ impl TaskData {
     fn to_hash(&self) -> Result<RHash, Error> {
         let task_data = self.0.get()?;
         let hash = RHash::new();
-        
+
         for (key, value) in task_data.iter() {
             hash.aset(key.clone(), value.clone())?;
         }
-        
+
         Ok(hash)
     }
 
@@ -78,7 +76,7 @@ impl TaskData {
 
     fn delete(&self, operations: &Operations) -> Result<(), Error> {
         let mut task_data = self.0.get_mut()?;
-        
+
         operations.with_inner_mut(|ops| {
             task_data.delete(ops);
             Ok(())
@@ -90,16 +88,16 @@ impl TaskData {
 
 fn create_task_data(uuid: String, operations: &Operations) -> Result<TaskData, Error> {
     let tc_uuid = uuid2tc(&uuid)?;
-    
+
     // Create operations for TaskChampion
     let mut tc_ops = taskchampion::Operations::new();
-    
+
     // Create the TaskData
     let tc_task_data = TCTaskData::create(tc_uuid, &mut tc_ops);
-    
+
     // Add the resulting operations to the provided Operations object
     operations.extend_from_tc(tc_ops.into_iter().collect())?;
-    
+
     Ok(TaskData(ThreadBound::new(tc_task_data)))
 }
 
@@ -121,4 +119,4 @@ pub fn init(module: &RModule) -> Result<(), Error> {
     class.define_method("delete", method!(TaskData::delete, 1))?;
 
     Ok(())
-}
+}

data/ext/taskchampion/src/util.rs

@@ -61,7 +61,7 @@ pub fn ruby_to_datetime(value: Value) -> Result<DateTime<Utc>, Error> {
                 ))
             }
         };
-        
+
         DateTime::parse_from_rfc3339(&iso_string)
             .map(|dt| dt.with_timezone(&Utc))
             .or_else(|_| {

data/lib/taskchampion/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: taskchampion-rb
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Tim Case
@@ -36,6 +36,7 @@ files:
 - ".rubocop.yml"
 - ".ruby-version"
 - CHANGELOG.md
+- CLAUDE.md
 - Cargo.lock
 - Cargo.toml
 - README.md
@@ -48,6 +49,7 @@ files:
 - docs/plan.md
 - example.md
 - examples/basic_usage.rb
+- examples/pending_tasks.rb
 - examples/sync_workflow.rb
 - ext/taskchampion/Cargo.toml
 - ext/taskchampion/extconf.rb