taski 0.5.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: afd6114f6d0814be687181ddd8e0acfa45af1d1064f14247e2864be53c3103f0
-  data.tar.gz: 5b76552b037943f8b9555f01eb6b98d5a515be95b8f75e63f6f42314cf388294
+  metadata.gz: 0ca85800083318a5bc4d40151f14e5c55d6474a81a89a095de6d2433a8609043
+  data.tar.gz: d68b0a3f9bf5bab689882df7cdf22fe02a169008a3d4bd64a24eaea2699dce33
 SHA512:
-  metadata.gz: 6c37d3650e3a1af652e469bad4627964fa62763ad7acc93e54b07bdaa577777dda65f0e34265d7974209ab3b3ab5f5ef5299d4675f6a8810fcdcd5dcbad19306
-  data.tar.gz: f2d5295608ee67c5a2ecebdfb0416f73fe16569534a4f798252cf5bd101bec3c43507e1c0560be102cfb37c44fcdf603ff2a7cf9a6b0afdfb9b74c3624ff7553
+  metadata.gz: 3705a29cdf6e5fbe4a244b9431c35bc326e2c383f71e00fe7223a1e87f98728e565e1faebbd081111ab8127197e39294c89d05c6e35511b8405425f21b6a8af3
+  data.tar.gz: 87d334c0e053bbd164c260e304f642a26305f14021de17bf10bb8d50180fd0160338efbca0821a3fc3af996b8212e3a10c52d5e533c54b6141b069e17f21af7a

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

@@ -113,9 +113,90 @@ end
 
 > **Note**: Nested implementation classes automatically inherit Section's `interfaces` as `exports`.
 
+## Best Practices
+
+### Keep Tasks Small and Focused
+
+Each task should do **one thing only**. While Taski allows you to write complex logic within a single task, keeping tasks small and focused provides significant benefits:
+
+```ruby
+# ✅ Good: Small, focused tasks
+class FetchData < Taski::Task
+  exports :data
+  def run
+    @data = API.fetch
+  end
+end
+
+class TransformData < Taski::Task
+  exports :result
+  def run
+    @result = FetchData.data.transform
+  end
+end
+
+class SaveData < Taski::Task
+  def run
+    Database.save(TransformData.result)
+  end
+end
+
+# ❌ Avoid: Monolithic task doing everything
+class DoEverything < Taski::Task
+  def run
+    data = API.fetch
+    result = data.transform
+    Database.save(result)
+  end
+end
+```
+
+**Why small tasks matter:**
+
+- **Parallel Execution**: Independent tasks run concurrently. Large monolithic tasks can't be parallelized
+- **Easier Cleanup**: `Task.clean` works per-task. Smaller tasks mean more granular cleanup control
+- **Better Reusability**: Small tasks can be composed into different workflows
+- **Clearer Dependencies**: The dependency graph becomes explicit and visible with `Task.tree`
+
+**Note:** Complex internal logic is perfectly fine. "One thing" means one responsibility, not one line of code. Other tasks only care about the exported results, not how they were computed.
+
+```ruby
+class RawData < Taski::Task
+  exports :data
+  def run
+    @data = API.fetch
+  end
+end
+
+class ProcessedData < Taski::Task
+  exports :result
+
+  def run
+    # Complex internal logic is OK - this task has one responsibility:
+    # producing the processed result
+    validated = validate_and_clean(RawData.data)
+    enriched = enrich_with_metadata(validated)
+    normalized = normalize_format(enriched)
+    @result = apply_business_rules(normalized)
+  end
+
+  private
+
+  def validate_and_clean(data)
+    # Complex validation logic...
+  end
+
+  def enrich_with_metadata(data)
+    # Complex enrichment logic...
+  end
+
+  # ... other private methods
+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 +204,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:
@@ -172,6 +272,23 @@ WebServer (Task)
 └── ◻ Server (Task)
 ```
 
+**Simple mode** provides a compact single-line display:
+
+```
+⠹ [3/5] DeployTask | Uploading files...
+✓ [5/5] All tasks completed (1234ms)
+```
+
+**Configuration:**
+
+```ruby
+# Via API
+Taski.progress_mode = :simple  # or :tree (default)
+
+# Via environment variable
+TASKI_PROGRESS_MODE=simple ruby your_script.rb
+```
+
 To disable: `TASKI_PROGRESS_DISABLE=1 ruby your_script.rb`
 
 ### Tree Visualization
@@ -184,6 +301,36 @@ puts WebServer.tree
 #     └── Cache (Task)
 ```
 
+## Testing
+
+### Test Helper for Mocking Dependencies
+
+Taski provides a test helper to mock task dependencies in your unit tests:
+
+```ruby
+require 'taski/test_helper/minitest'
+
+class BuildReportTest < Minitest::Test
+  include Taski::TestHelper::Minitest
+
+  def test_builds_report
+    # Mock direct dependencies - their run methods won't execute
+    mock_task(FetchData, users: [1, 2, 3])
+
+    # Task under test uses mocked values
+    assert_equal 3, BuildReport.user_count
+  end
+end
+```
+
+**Key features:**
+- Mock only direct dependencies; indirect dependencies are automatically isolated
+- Verify which dependencies were accessed with `assert_task_accessed` / `refute_task_accessed`
+- Automatic cleanup after each test
+- Supports both Minitest and RSpec
+
+For RSpec, use `include Taski::TestHelper::RSpec` instead.
+
 ## Development
 
 ```bash

data/docs/GUIDE.md

@@ -0,0 +1,394 @@
+# 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
+```
+
+### Display Modes
+
+Taski supports two progress display modes:
+
+#### Tree Mode (Default)
+
+Full dependency tree visualization with status for each task:
+
+```
+WebServer (Task)
+├── ⠋ Config (Task) | Reading config.yml...
+│   ├── ✅ Database (Task) 45.2ms
+│   └── ⠙ Cache (Task) | Connecting...
+└── ◻ Server (Task)
+```
+
+#### Simple Mode
+
+Compact single-line display showing current progress:
+
+```
+⠹ [3/5] DeployTask | Uploading files...
+✓ [5/5] All tasks completed (1234ms)
+```
+
+Format: `[spinner] [completed/total] TaskName | last output...`
+
+When multiple tasks run in parallel:
+```
+⠹ [2/5] DownloadLayer1, DownloadLayer2 | Downloading...
+```
+
+On failure:
+```
+✗ [3/5] DeployTask failed: Connection refused
+```
+
+### Configuring Progress Mode
+
+**Via API:**
+
+```ruby
+Taski.progress_mode = :simple  # Use simple mode
+Taski.progress_mode = :tree    # Use tree mode (default)
+```
+
+**Via environment variable:**
+
+```bash
+TASKI_PROGRESS_MODE=simple ruby your_script.rb
+TASKI_PROGRESS_MODE=tree ruby your_script.rb
+```
+
+### 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_PROGRESS_MODE=simple\|tree` | Set progress display mode (default: tree) |
+| `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.