taski 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: afd6114f6d0814be687181ddd8e0acfa45af1d1064f14247e2864be53c3103f0
-  data.tar.gz: 5b76552b037943f8b9555f01eb6b98d5a515be95b8f75e63f6f42314cf388294
+  metadata.gz: 0e593418f036752e5adf6bb989cfc800ee249be3b3a7ace71df377a5aa1b73bf
+  data.tar.gz: 4e69af8247ade3e1e585475dcab88ae73fa42a71a60d4bbcc420456b1b2d9de5
 SHA512:
-  metadata.gz: 6c37d3650e3a1af652e469bad4627964fa62763ad7acc93e54b07bdaa577777dda65f0e34265d7974209ab3b3ab5f5ef5299d4675f6a8810fcdcd5dcbad19306
-  data.tar.gz: f2d5295608ee67c5a2ecebdfb0416f73fe16569534a4f798252cf5bd101bec3c43507e1c0560be102cfb37c44fcdf603ff2a7cf9a6b0afdfb9b74c3624ff7553
+  metadata.gz: 339d64fa997095a68adffa2d7227c5e648dc147edf576824283328a1e655706d6e72666fd56a8d8f934283ddd399eb691467121381f995b8540c798bb7f28c87
+  data.tar.gz: 3d5d41b708ab1d9f715bc0848d22b7b4233b50b6f922440ec304fb3c32a2b86bddf936839387462370a8b2df0e9de9d8200b9733aa8fdafdf3fa2536e21835ab

data/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.7.0] - 2025-12-23
+
+### Added
+- Group block for organizing progress display messages (`Taski.group`) ([#105](https://github.com/ahogappa/taski/pull/105))
+- Scope-based execution with thread-local registry for independent task execution ([#103](https://github.com/ahogappa/taski/pull/103))
+- `TaskClass::Error` auto-generation for task-specific error handling ([#95](https://github.com/ahogappa/taski/pull/95))
+- `AggregateAware` module for transparent rescue matching with `AggregateError` ([#95](https://github.com/ahogappa/taski/pull/95))
+- `AggregateError#includes?` and `AggregateError#find` methods for searching aggregated errors ([#95](https://github.com/ahogappa/taski/pull/95))
+- Aggregation of multiple errors in parallel execution ([#95](https://github.com/ahogappa/taski/pull/95))
+- `workers` parameter to `Task.run`, `Task.clean`, and `Task.run_and_clean` for configurable parallelism ([#92](https://github.com/ahogappa/taski/pull/92))
+
+### Changed
+- Renamed `context` to `args` for API clarity (BREAKING CHANGE) ([#94](https://github.com/ahogappa/taski/pull/94))
+
+### Fixed
+- Thread-safety improvements in `Registry#get_or_create` ([#90](https://github.com/ahogappa/taski/pull/90))
+
+## [0.6.0] - 2025-12-21
+
+### Added
+- `Task#system` override for capturing subprocess output in progress display
+- `ExecutionContext` with observer pattern for managing execution state
+- Inline task output display in progress tree
+- Clean execution with reverse dependency order via `run_and_clean`
+- Comprehensive documentation for `TaskAbortException`
+- Unit tests for `ExecutionContext`, `WorkerPool`, and `Scheduler`
+
+### Changed
+- Replaced `ThreadOutputCapture` with pipe-based `TaskOutputRouter` for more reliable output capture
+- Split `Executor` into separate `Scheduler` and `WorkerPool` classes for better separation of concerns
+- Centralized tree building logic in `TreeProgressDisplay`
+- Improved `run_and_clean` implementation and display
+
+### Fixed
+- Added mutex protection to `impl_call_order` accessor for thread safety
+- Fixed `ExecutionContext` passing to `TaskWrapper` resolving progress display garbage
+- Improved output capture reliability for progress display
+
+## [0.5.0] - 2025-11-30
+
+- Initial release with core task execution functionality

data/README.md

@@ -115,7 +115,7 @@ end
 
 ## Advanced Usage
 
-### Context - Runtime Information and Options
+### Args - Runtime Information and Options
 
 Pass custom options and access execution context from any task:
 
@@ -123,43 +123,62 @@ Pass custom options and access execution context from any task:
 class DeployTask < Taski::Task
   def run
     # User-defined options
-    env = Taski.context[:env]
-    debug = Taski.context.fetch(:debug, false)
+    env = Taski.args[:env]
+    debug = Taski.args.fetch(:debug, false)
 
     # Runtime information
-    puts "Working directory: #{Taski.context.working_directory}"
-    puts "Started at: #{Taski.context.started_at}"
-    puts "Root task: #{Taski.context.root_task}"
+    puts "Working directory: #{Taski.args.working_directory}"
+    puts "Started at: #{Taski.args.started_at}"
+    puts "Root task: #{Taski.args.root_task}"
     puts "Deploying to: #{env}"
   end
 end
 
 # Pass options when running
-DeployTask.run(context: { env: "production", debug: true })
+DeployTask.run(args: { env: "production", debug: true })
 ```
 
-Context API:
-- `Taski.context[:key]` - Get option value (nil if not set)
-- `Taski.context.fetch(:key, default)` - Get with default value
-- `Taski.context.key?(:key)` - Check if option exists
-- `Taski.context.working_directory` - Execution directory
-- `Taski.context.started_at` - Execution start time
-- `Taski.context.root_task` - First task class called
+Args API:
+- `Taski.args[:key]` - Get option value (nil if not set)
+- `Taski.args.fetch(:key, default)` - Get with default value
+- `Taski.args.key?(:key)` - Check if option exists
+- `Taski.args.working_directory` - Execution directory
+- `Taski.args.started_at` - Execution start time
+- `Taski.args.root_task` - First task class called
 
-### Re-execution
+### Execution Model
 
 ```ruby
-# Cached execution (default)
+# Each class method call creates fresh execution
 RandomTask.value  # => 42
-RandomTask.value  # => 42 (cached)
+RandomTask.value  # => 99 (different value - fresh execution)
 
-# Fresh execution
-RandomTask.new.run  # => 123 (new instance)
+# Instance-level caching
+instance = RandomTask.new
+instance.run        # => 42
+instance.run        # => 42 (cached within instance)
+instance.value      # => 42
 
-# Reset all caches
-RandomTask.reset!
+# Dependencies within same execution share results
+DoubleConsumer.run  # RandomTask runs once, both accesses get same value
 ```
 
+### Aborting Execution
+
+Stop all pending tasks when a critical error occurs:
+
+```ruby
+class CriticalTask < Taski::Task
+  def run
+    if fatal_error?
+      raise Taski::TaskAbortException, "Cannot continue"
+    end
+  end
+end
+```
+
+When `TaskAbortException` is raised, no new tasks will start. Already running tasks will complete, then execution stops.
+
 ### Progress Display
 
 Tree-based progress visualization is enabled by default:

data/docs/GUIDE.md

@@ -0,0 +1,340 @@
+# Taski Guide
+
+This guide provides detailed documentation beyond the basics covered in the README.
+
+## Table of Contents
+
+- [Error Handling](#error-handling)
+- [Lifecycle Management](#lifecycle-management)
+- [Progress Display](#progress-display)
+- [Debugging](#debugging)
+
+---
+
+## Error Handling
+
+Taski provides comprehensive error handling for parallel task execution.
+
+### Error Types
+
+| Exception | Purpose |
+|-----------|---------|
+| `Taski::AggregateError` | Multiple tasks failed during parallel execution |
+| `Taski::TaskError` | Base class for task-specific errors |
+| `Taski::TaskAbortException` | Intentional abort (stops all tasks immediately) |
+| `Taski::CircularDependencyError` | Circular dependency detected |
+| `TaskClass::Error` | Auto-generated error class for each Task subclass |
+
+### AggregateError
+
+When multiple tasks fail during parallel execution, errors are collected into an `AggregateError`:
+
+```ruby
+class DatabaseTask < Taski::Task
+  exports :connection
+  def run
+    raise "Database connection failed"
+  end
+end
+
+class CacheTask < Taski::Task
+  exports :redis_client
+  def run
+    raise "Cache connection failed"
+  end
+end
+
+class AppTask < Taski::Task
+  def run
+    db = DatabaseTask.connection
+    cache = CacheTask.redis_client
+  end
+end
+
+begin
+  AppTask.run
+rescue Taski::AggregateError => e
+  puts "#{e.errors.size} tasks failed:"
+  e.errors.each do |failure|
+    puts "  - #{failure.task_class.name}: #{failure.error.message}"
+  end
+end
+# Output:
+# 2 tasks failed:
+#   - DatabaseTask: Database connection failed
+#   - CacheTask: Cache connection failed
+```
+
+### Task-Specific Error Classes
+
+Each Task subclass automatically gets an `::Error` class for targeted rescue:
+
+```ruby
+class DatabaseTask < Taski::Task
+  exports :connection
+  def run
+    raise "Connection failed"
+  end
+end
+
+# Rescue errors from a specific task
+begin
+  AppTask.run
+rescue DatabaseTask::Error => e
+  puts "Database task failed: #{e.message}"
+  # e.task_class returns DatabaseTask
+  # e.cause returns the original error
+end
+```
+
+This works transparently with `AggregateError` - when you rescue `DatabaseTask::Error`, it matches an `AggregateError` that contains a `DatabaseTask::Error`.
+
+### TaskAbortException
+
+Use `TaskAbortException` to immediately stop all task execution:
+
+```ruby
+class CriticalTask < Taski::Task
+  def run
+    if critical_condition_met?
+      raise Taski::TaskAbortException, "Critical error - aborting"
+    end
+  end
+end
+```
+
+`TaskAbortException` takes priority over regular errors. Already running tasks will complete, but no new tasks will start.
+
+### Error Handling Best Practices
+
+```ruby
+# 1. Handle errors within the task when recovery is possible
+class ResilientTask < Taski::Task
+  exports :data
+  def run
+    @data = fetch_from_primary
+  rescue Timeout::Error
+    @data = fetch_from_fallback
+  end
+end
+
+# 2. Use task-specific errors for clarity
+begin
+  AppTask.run
+rescue DatabaseTask::Error => e
+  handle_database_failure(e)
+rescue CacheTask::Error => e
+  handle_cache_failure(e)
+end
+
+# 3. Fail fast with clear messages
+class ValidatingTask < Taski::Task
+  def run
+    missing = %w[DATABASE_URL API_KEY].select { |v| ENV[v].nil? }
+    raise "Missing: #{missing.join(', ')}" if missing.any?
+  end
+end
+```
+
+---
+
+## Lifecycle Management
+
+Taski supports resource cleanup with `run`, `clean`, and `run_and_clean` methods.
+
+### Basic Lifecycle
+
+```ruby
+class DatabaseSetup < Taski::Task
+  exports :connection
+
+  def run
+    @connection = "postgresql://localhost:5432/myapp"
+    puts "Database connected"
+  end
+
+  def clean
+    puts "Database disconnected"
+  end
+end
+
+class WebServer < Taski::Task
+  def run
+    puts "Server started with #{DatabaseSetup.connection}"
+  end
+
+  def clean
+    puts "Server stopped"
+  end
+end
+
+# Start
+WebServer.run
+# => Database connected
+# => Server started with postgresql://localhost:5432/myapp
+
+# Clean (reverse dependency order)
+WebServer.clean
+# => Server stopped
+# => Database disconnected
+```
+
+### run_and_clean
+
+Execute run followed by clean in a single operation:
+
+```ruby
+WebServer.run_and_clean
+# => Database connected
+# => Server started
+# => Server stopped
+# => Database disconnected
+```
+
+### Idempotent Clean Methods
+
+Clean methods should be safe to call multiple times:
+
+```ruby
+class SafeFileTask < Taski::Task
+  exports :data_file
+
+  def run
+    @data_file = '/tmp/data.txt'
+    File.write(@data_file, 'data')
+  end
+
+  def clean
+    # Check before delete
+    if @data_file && File.exist?(@data_file)
+      File.delete(@data_file)
+    end
+  end
+end
+```
+
+---
+
+## Progress Display
+
+Taski provides real-time progress visualization during task execution.
+
+### Features
+
+- **Spinner Animation**: Animated spinner during execution
+- **Output Capture**: Real-time display of task output (last line)
+- **Status Indicators**: Success/failure icons with execution time
+- **Group Blocks**: Organize output messages into logical phases
+- **TTY Detection**: Clean output when redirected to files
+
+### Group Blocks
+
+Use `group` blocks to organize output within a task into logical phases. The current group name is displayed alongside the task's output in the progress display.
+
+```ruby
+class DeployTask < Taski::Task
+  def run
+    group("Preparing environment") do
+      puts "Checking dependencies..."
+      puts "Validating config..."
+    end
+
+    group("Building application") do
+      puts "Compiling source..."
+      puts "Running tests..."
+    end
+
+    group("Deploying") do
+      puts "Uploading files..."
+      puts "Restarting server..."
+    end
+  end
+end
+```
+
+Progress display output:
+
+```text
+During execution:
+⠋ DeployTask (Task) | Deploying: Uploading files...
+
+After completion:
+✓ DeployTask (Task) 520ms
+```
+
+The group name appears as a prefix to the output message: `| GroupName: output...`
+
+Groups are useful for:
+- **Logical organization**: Group related operations together
+- **Progress visibility**: See which phase is currently executing
+- **Error context**: Know which phase failed when errors occur
+
+### Example Output
+
+```
+During execution:
+  WebServer (Task)
+  ├── Config (Task) ...
+  │   ├── Database (Task) 45.2ms
+  │   └── Cache (Task) ...
+  └── Server (Task)
+
+After completion:
+  WebServer (Task) 120.5ms
+  ├── Config (Task) 50.3ms
+  │   ├── Database (Task) 45.2ms
+  │   └── Cache (Task) 48.1ms
+  └── Server (Task) 70.2ms
+```
+
+### Disabling Progress Display
+
+```bash
+TASKI_PROGRESS_DISABLE=1 ruby your_script.rb
+```
+
+### File Output Mode
+
+When output is redirected, interactive spinners are automatically disabled:
+
+```bash
+ruby build.rb > build.log 2>&1
+```
+
+---
+
+## Debugging
+
+### Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `TASKI_PROGRESS_DISABLE=1` | Disable progress display |
+| `TASKI_DEBUG=1` | Enable debug output |
+
+### Dependency Tree Visualization
+
+```ruby
+puts MyTask.tree
+# MyTask (Task)
+# ├── DatabaseTask (Task)
+# └── CacheTask (Task)
+#     └── ConfigTask (Task)
+```
+
+### Common Issues
+
+**Circular Dependencies**
+
+```ruby
+# Detected before execution
+begin
+  TaskA.run
+rescue Taski::CircularDependencyError => e
+  puts e.cyclic_tasks  # [[TaskA, TaskB]]
+end
+```
+
+**Static Analysis Requirements**
+
+Tasks must be defined in source files (not dynamically with `Class.new`) because static analysis uses Prism AST parsing which requires actual source files.

data/examples/README.md

@@ -34,36 +34,36 @@ ruby examples/section_demo.rb
 
 ---
 
-### 3. context_demo.rb - Runtime Context and Options
+### 3. args_demo.rb - Runtime Args and Options
 
-Access execution context and pass custom options to tasks.
+Access execution args and pass custom options to tasks.
 
 ```bash
-ruby examples/context_demo.rb
+ruby examples/args_demo.rb
 ```
 
 **Covers:**
-- User-defined options via `run(context: {...})`
-- `Taski.context[:key]` for option access
-- `Taski.context.fetch(:key, default)` for defaults
-- `Taski.context.working_directory`
-- `Taski.context.started_at`
-- `Taski.context.root_task`
+- User-defined options via `run(args: {...})`
+- `Taski.args[:key]` for option access
+- `Taski.args.fetch(:key, default)` for defaults
+- `Taski.args.working_directory`
+- `Taski.args.started_at`
+- `Taski.args.root_task`
 
 ---
 
-### 4. reexecution_demo.rb - Cache Control
+### 4. reexecution_demo.rb - Scope-Based Execution
 
-Understand caching behavior and re-execution patterns.
+Understand scope-based execution and caching behavior.
 
 ```bash
-ruby examples/reexecution_demo.rb
+TASKI_PROGRESS_DISABLE=1 ruby examples/reexecution_demo.rb
 ```
 
 **Covers:**
-- Default caching behavior
-- `Task.new` for fresh instances
-- `Task.reset!` for clearing caches
+- Fresh execution for each class method call
+- Instance-level caching with `Task.new`
+- Scope-based dependency caching
 
 ---
 
@@ -97,16 +97,64 @@ ruby examples/parallel_progress_demo.rb
 
 ---
 
+### 7. clean_demo.rb - Lifecycle Management
+
+Demonstrates resource cleanup with clean methods.
+
+```bash
+ruby examples/clean_demo.rb
+```
+
+**Covers:**
+- Defining `clean` methods for resource cleanup
+- Reverse dependency order execution
+- `run_and_clean` combined operation
+
+---
+
+### 8. system_call_demo.rb - Subprocess Output
+
+Capture subprocess output in progress display.
+
+```bash
+ruby examples/system_call_demo.rb
+```
+
+**Covers:**
+- `system()` output capture
+- Streaming output display
+- Parallel subprocess execution
+
+---
+
+### 9. nested_section_demo.rb - Nested Sections
+
+Sections that depend on other tasks for implementation selection.
+
+```bash
+TASKI_PROGRESS_DISABLE=1 ruby examples/nested_section_demo.rb
+```
+
+**Covers:**
+- Section inside Section
+- Dynamic implementation selection
+- Complex dependency hierarchies
+
+---
+
 ## Quick Reference
 
 | Example | Feature | Complexity |
 |---------|---------|------------|
 | quick_start | Exports API | Basic |
 | section_demo | Section API | Intermediate |
-| context_demo | Context API | Intermediate |
-| reexecution_demo | Cache Control | Intermediate |
+| args_demo | Args API | Intermediate |
+| reexecution_demo | Scope-Based Execution | Intermediate |
 | data_pipeline_demo | ETL Pipeline | Advanced |
 | parallel_progress_demo | Progress Display | Advanced |
+| clean_demo | Lifecycle Management | Intermediate |
+| system_call_demo | Subprocess Output | Advanced |
+| nested_section_demo | Nested Sections | Advanced |
 
 ## Running All Examples