taski 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e593418f036752e5adf6bb989cfc800ee249be3b3a7ace71df377a5aa1b73bf
-  data.tar.gz: 4e69af8247ade3e1e585475dcab88ae73fa42a71a60d4bbcc420456b1b2d9de5
+  metadata.gz: f7677c0f3995a7c61b5850fb25c82c60626287584e5c7f918939ededc045e9ea
+  data.tar.gz: d470969c88a4df51503487aacdf2c6261b65e6ed75ee3c7cc2ff744dfd750365
 SHA512:
-  metadata.gz: 339d64fa997095a68adffa2d7227c5e648dc147edf576824283328a1e655706d6e72666fd56a8d8f934283ddd399eb691467121381f995b8540c798bb7f28c87
-  data.tar.gz: 3d5d41b708ab1d9f715bc0848d22b7b4233b50b6f922440ec304fb3c32a2b86bddf936839387462370a8b2df0e9de9d8200b9733aa8fdafdf3fa2536e21835ab
+  metadata.gz: 5f93d9e7d10f7104851266f0252ec4365d445a90d3a25b885f289df5d8caafbe9f9250ff9236e4cca0791749100c83c46735a8e98e5c1b675662199ba7a0e547
+  data.tar.gz: eb4fb9f806cdd5097e0d3321d4cda9e3df183d4850c4aa8161ba09b71666444166f05b5e795b330227076d85f7410adbe2fc4f1e2b19c66d007ff1632d354f97

data/CHANGELOG.md

@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-01-23
+
+### Added
+- `Taski::Env` class for system-managed execution environment information ([#125](https://github.com/ahogappa/taski/pull/125))
+  - Access via `Taski.env.working_directory`, `Taski.env.started_at`, `Taski.env.root_task`
+- `args` and `workers` parameters to `Task.new` for direct task instantiation ([#125](https://github.com/ahogappa/taski/pull/125))
+- `mock_env` helper in `TestHelper` for mocking environment in tests ([#125](https://github.com/ahogappa/taski/pull/125))
+
+### Changed
+- Separate system attributes from `Taski.args` to `Taski.env` ([#125](https://github.com/ahogappa/taski/pull/125))
+  - `Taski.args` now holds only user-defined options passed via `run(args: {...})`
+  - `Taski.env` holds system-managed execution environment (`root_task`, `started_at`, `working_directory`)
+
+## [0.7.1] - 2026-01-22
+
+### Added
+- `Taski::TestHelper` module for mocking task dependencies in unit tests ([#123](https://github.com/ahogappa/taski/pull/123))
+  - `mock_task(TaskClass, key: value)` to mock exported values without running tasks
+  - `assert_task_accessed` / `refute_task_accessed` for verifying dependency access
+  - Support for both Minitest and RSpec test frameworks
+- Simple one-line progress display mode (`Taski.progress_mode = :simple`) as an alternative to tree display ([#112](https://github.com/ahogappa/taski/pull/112))
+  - Configure via `TASKI_PROGRESS_MODE` environment variable or `Taski.progress_mode` API
+- Display captured task output (up to 30 lines) in AggregateError messages for better debugging ([#109](https://github.com/ahogappa/taski/pull/109))
+- Background polling thread in TaskOutputRouter to ensure pipes are drained reliably ([#122](https://github.com/ahogappa/taski/pull/122))
+- `Taski.with_args` helper method for safe argument lifecycle management ([#110](https://github.com/ahogappa/taski/pull/110))
+
+### Changed
+- Progress display now uses alternate screen buffer and shows summary line after completion ([#107](https://github.com/ahogappa/taski/pull/107))
+- Eliminate screen flickering in tree progress display with in-place overwrite rendering ([#121](https://github.com/ahogappa/taski/pull/121))
+- Extract `BaseProgressDisplay` class for shared progress display functionality ([#117](https://github.com/ahogappa/taski/pull/117))
+
+### Fixed
+- Wait for running dependencies in nested executor to prevent deadlock ([#106](https://github.com/ahogappa/taski/pull/106))
+- Preserve namespace path when following method calls in static analysis ([#108](https://github.com/ahogappa/taski/pull/108))
+- Prevent race condition in `Taski.args` lifecycle during concurrent execution ([#110](https://github.com/ahogappa/taski/pull/110))
+- Ensure progress display cleanup on interrupt (Ctrl+C) ([#107](https://github.com/ahogappa/taski/pull/107))
+- Always enable output in PlainProgressDisplay ([#117](https://github.com/ahogappa/taski/pull/117))
+
 ## [0.7.0] - 2025-12-23
 
 ### Added

data/README.md

@@ -113,6 +113,87 @@ 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
 
 ### Args - Runtime Information and Options
@@ -122,14 +203,14 @@ Pass custom options and access execution context from any task:
 ```ruby
 class DeployTask < Taski::Task
   def run
-    # User-defined options
+    # User-defined options (Taski.args)
     env = Taski.args[:env]
     debug = Taski.args.fetch(:debug, false)
 
-    # Runtime information
-    puts "Working directory: #{Taski.args.working_directory}"
-    puts "Started at: #{Taski.args.started_at}"
-    puts "Root task: #{Taski.args.root_task}"
+    # Runtime environment information (Taski.env)
+    puts "Working directory: #{Taski.env.working_directory}"
+    puts "Started at: #{Taski.env.started_at}"
+    puts "Root task: #{Taski.env.root_task}"
     puts "Deploying to: #{env}"
   end
 end
@@ -138,13 +219,15 @@ end
 DeployTask.run(args: { env: "production", debug: true })
 ```
 
-Args API:
+Args API (user-defined options):
 - `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
+
+Env API (execution environment):
+- `Taski.env.working_directory` - Execution directory
+- `Taski.env.started_at` - Execution start time
+- `Taski.env.root_task` - First task class called
 
 ### Execution Model
 
@@ -191,6 +274,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
@@ -203,6 +303,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

@@ -287,6 +287,59 @@ After completion:
   └── 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
@@ -310,6 +363,7 @@ ruby build.rb > build.log 2>&1
 | 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

data/examples/README.md

@@ -46,9 +46,9 @@ ruby examples/args_demo.rb
 - 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`
+- `Taski.env.working_directory`
+- `Taski.env.started_at`
+- `Taski.env.root_task`
 
 ---
 

data/examples/args_demo.rb

@@ -1,35 +1,36 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Taski Args API Example
+# Taski Args & Env API Example
 #
-# This example demonstrates the Args API for accessing runtime information:
-# - working_directory: Where execution started
-# - started_at: When execution began
-# - root_task: The first task class that was called
-# - User-defined options: Custom values passed via run(args: {...})
+# This example demonstrates the Args and Env APIs:
+# - Taski.env: Execution environment information
+#   - working_directory: Where execution started
+#   - started_at: When execution began
+#   - root_task: The first task class that was called
+# - Taski.args: User-defined options passed via run(args: {...})
 #
 # Run: ruby examples/args_demo.rb
 
 require_relative "../lib/taski"
 
-puts "Taski Args API Example"
+puts "Taski Args & Env API Example"
 puts "=" * 40
 
-# Task that uses args information for logging
+# Task that uses env information for logging
 class SetupTask < Taski::Task
   exports :setup_info
 
   def run
     puts "Setup running..."
-    puts "  Working directory: #{Taski.args.working_directory}"
-    puts "  Started at: #{Taski.args.started_at}"
-    puts "  Root task: #{Taski.args.root_task}"
+    puts "  Working directory: #{Taski.env.working_directory}"
+    puts "  Started at: #{Taski.env.started_at}"
+    puts "  Root task: #{Taski.env.root_task}"
     puts "  Environment: #{Taski.args[:env]}"
 
     @setup_info = {
-      directory: Taski.args.working_directory,
-      timestamp: Taski.args.started_at,
+      directory: Taski.env.working_directory,
+      timestamp: Taski.env.started_at,
       env: Taski.args[:env]
     }
   end
@@ -40,8 +41,8 @@ class FileProcessor < Taski::Task
   exports :output_path
 
   def run
-    # Use args to determine output location
-    base_dir = Taski.args.working_directory
+    # Use env to determine output location
+    base_dir = Taski.env.working_directory
     env = Taski.args.fetch(:env, "development")
     @output_path = File.join(base_dir, "tmp", env, "output.txt")
 
@@ -55,7 +56,7 @@ class TimingTask < Taski::Task
   exports :duration_info
 
   def run
-    start_time = Taski.args.started_at
+    start_time = Taski.env.started_at
     current_time = Time.now
     elapsed = current_time - start_time
 
@@ -76,7 +77,7 @@ class MainTask < Taski::Task
 
   def run
     puts "\nMainTask executing..."
-    puts "  Root task is: #{Taski.args.root_task}"
+    puts "  Root task is: #{Taski.env.root_task}"
     puts "  Environment: #{Taski.args[:env]}"
 
     # Access dependencies
@@ -88,7 +89,7 @@ class MainTask < Taski::Task
       setup: setup,
       output_path: output,
       timing: timing,
-      root_task: Taski.args.root_task.to_s
+      root_task: Taski.env.root_task.to_s
     }
 
     puts "\nExecution Summary:"
@@ -114,5 +115,5 @@ puts "-" * 40
 puts MainTask.tree
 
 puts "\n" + "=" * 40
-puts "Args API demonstration complete!"
-puts "Note: Args provides runtime information and user options without affecting dependency analysis."
+puts "Args & Env API demonstration complete!"
+puts "Note: Args provides user options, Env provides execution environment info."

data/examples/data_pipeline_demo.rb

@@ -129,7 +129,7 @@ class EnrichWithActivities < Taski::Task
 
     activities_by_user = activities.group_by { |a| a[:user_id] }
       .transform_values do |records|
-      records.to_h { |r| [r[:action], r[:count]] }
+        records.to_h { |r| [r[:action], r[:count]] }
     end
 
     @users_with_activities = users.map do |user|