taski 0.7.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e593418f036752e5adf6bb989cfc800ee249be3b3a7ace71df377a5aa1b73bf
-  data.tar.gz: 4e69af8247ade3e1e585475dcab88ae73fa42a71a60d4bbcc420456b1b2d9de5
+  metadata.gz: 0ca85800083318a5bc4d40151f14e5c55d6474a81a89a095de6d2433a8609043
+  data.tar.gz: d68b0a3f9bf5bab689882df7cdf22fe02a169008a3d4bd64a24eaea2699dce33
 SHA512:
-  metadata.gz: 339d64fa997095a68adffa2d7227c5e648dc147edf576824283328a1e655706d6e72666fd56a8d8f934283ddd399eb691467121381f995b8540c798bb7f28c87
-  data.tar.gz: 3d5d41b708ab1d9f715bc0848d22b7b4233b50b6f922440ec304fb3c32a2b86bddf936839387462370a8b2df0e9de9d8200b9733aa8fdafdf3fa2536e21835ab
+  metadata.gz: 3705a29cdf6e5fbe4a244b9431c35bc326e2c383f71e00fe7223a1e87f98728e565e1faebbd081111ab8127197e39294c89d05c6e35511b8405425f21b6a8af3
+  data.tar.gz: 87d334c0e053bbd164c260e304f642a26305f14021de17bf10bb8d50180fd0160338efbca0821a3fc3af996b8212e3a10c52d5e533c54b6141b069e17f21af7a

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
@@ -191,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
@@ -203,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

@@ -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/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|