taski 0.3.1 → 0.4.1

data/examples/README.md

@@ -1,69 +1,125 @@
 # Taski Examples
 
-Learn Taski through practical examples, from basic concepts to advanced patterns.
+Practical examples demonstrating Taski's parallel task execution and automatic dependency resolution.
 
-## Getting Started
+## Examples
 
-Start with these examples in order:
+### 1. quick_start.rb - Getting Started
 
-### 1. **[quick_start.rb](quick_start.rb)** - Your First Taski Program
-- Basic task definition with Exports API
-- Automatic dependency resolution
-- Simple task execution
+Basic Exports API usage and automatic dependency resolution.
 
 ```bash
 ruby examples/quick_start.rb
 ```
 
-### 2. **[progress_demo.rb](progress_demo.rb)** - Rich CLI Progress Display
-- Animated spinner with ANSI colors
-- Real-time output capture and 5-line tail
-- Production build scenarios
-- TTY detection for clean file output
+**Covers:**
+- Task definition with `exports`
+- Automatic dependency detection
+- Accessing exported values
+
+---
+
+### 2. section_demo.rb - Runtime Implementation Selection
+
+Switch implementations based on environment using the Section API.
 
 ```bash
-# Interactive mode with rich spinner
-ruby examples/progress_demo.rb
+ruby examples/section_demo.rb
+```
+
+**Covers:**
+- `interfaces` for defining contracts
+- Environment-specific implementations
+- Dependency tree visualization with `.tree`
+
+---
+
+### 3. context_demo.rb - Runtime Context and Options
+
+Access execution context and pass custom options to tasks.
 
-# Clean output mode (no spinner)
-ruby examples/progress_demo.rb > build.log 2>&1
-cat build.log
+```bash
+ruby examples/context_demo.rb
 ```
 
-### 3. **[section_configuration.rb](section_configuration.rb)** - Section-based Configuration Management
-- Dynamic implementation selection with Taski::Section
-- Environment-specific configuration
-- Section dependency resolution
-- Complex configuration hierarchies
+**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`
+
+---
+
+### 4. reexecution_demo.rb - Cache Control
+
+Understand caching behavior and re-execution patterns.
 
 ```bash
-ruby examples/section_configuration.rb
+ruby examples/reexecution_demo.rb
 ```
 
-### 4. **[advanced_patterns.rb](advanced_patterns.rb)** - Complex Dependency Patterns
-- Mixed Exports API and Define API usage
-- Environment-specific dependencies
-- Feature flags and conditional logic
-- Task reset and rebuild scenarios
+**Covers:**
+- Default caching behavior
+- `Task.new` for fresh instances
+- `Task.reset!` for clearing caches
+
+---
+
+### 5. data_pipeline_demo.rb - Real-World Pipeline
+
+A realistic ETL pipeline with parallel data fetching.
 
 ```bash
-ruby examples/advanced_patterns.rb
+ruby examples/data_pipeline_demo.rb
 ```
 
-## Key Concepts Demonstrated
+**Covers:**
+- Multiple data sources in parallel
+- Data transformation stages
+- Aggregation and reporting
 
-- **Exports API**: Static dependencies with `exports :property`
-- **Define API**: Dynamic dependencies with `define :property, -> { ... }`
-- **Section API**: Dynamic implementation selection with `Taski::Section`
-- **Dependency Resolution**: Automatic dependency detection for sections
-- **Progress Display**: Rich terminal output with spinners and colors
-- **Output Capture**: Tail-style display of task output
-- **Environment Configuration**: Different behavior based on runtime settings
-- **Error Handling**: Graceful failure with progress indicators
+---
+
+### 6. parallel_progress_demo.rb - Progress Display
+
+Real-time progress visualization during parallel execution.
+
+```bash
+TASKI_FORCE_PROGRESS=1 ruby examples/parallel_progress_demo.rb
+```
+
+**Covers:**
+- Parallel task execution
+- Progress display with spinners
+- Execution timing
+
+---
+
+## 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 |
+| data_pipeline_demo | ETL Pipeline | Advanced |
+| parallel_progress_demo | Progress Display | Advanced |
+
+## Running All Examples
+
+```bash
+# Run each example
+for f in examples/*.rb; do echo "=== $f ===" && ruby "$f" && echo; done
+
+# With progress display (for parallel_progress_demo)
+TASKI_FORCE_PROGRESS=1 ruby examples/parallel_progress_demo.rb
+```
 
 ## Next Steps
 
-After exploring these examples:
-- Read the main documentation
-- Examine the test files for more usage patterns
-- Check out the source code in `lib/taski/`
+- [Main README](../README.md) - Full documentation
+- [Tests](../test/) - More usage patterns
+- [Source](../lib/taski/) - Implementation details

data/examples/context_demo.rb

@@ -0,0 +1,118 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Taski Context API Example
+#
+# This example demonstrates the Context 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(context: {...})
+#
+# Run: ruby examples/context_demo.rb
+
+require_relative "../lib/taski"
+
+puts "Taski Context API Example"
+puts "=" * 40
+
+# Task that uses context information for logging
+class SetupTask < Taski::Task
+  exports :setup_info
+
+  def run
+    puts "Setup running..."
+    puts "  Working directory: #{Taski.context.working_directory}"
+    puts "  Started at: #{Taski.context.started_at}"
+    puts "  Root task: #{Taski.context.root_task}"
+    puts "  Environment: #{Taski.context[:env]}"
+
+    @setup_info = {
+      directory: Taski.context.working_directory,
+      timestamp: Taski.context.started_at,
+      env: Taski.context[:env]
+    }
+  end
+end
+
+# Task that creates files relative to working directory
+class FileProcessor < Taski::Task
+  exports :output_path
+
+  def run
+    # Use context to determine output location
+    base_dir = Taski.context.working_directory
+    env = Taski.context.fetch(:env, "development")
+    @output_path = File.join(base_dir, "tmp", env, "output.txt")
+
+    puts "FileProcessor: Would write to #{@output_path}"
+    puts "  (relative to working directory, env: #{env})"
+  end
+end
+
+# Task that logs execution timing
+class TimingTask < Taski::Task
+  exports :duration_info
+
+  def run
+    start_time = Taski.context.started_at
+    current_time = Time.now
+    elapsed = current_time - start_time
+
+    puts "TimingTask: #{elapsed.round(3)}s since execution started"
+    puts "  Debug mode: #{Taski.context.fetch(:debug, false)}"
+
+    @duration_info = {
+      started: start_time,
+      current: current_time,
+      elapsed_seconds: elapsed
+    }
+  end
+end
+
+# Main task that depends on others
+class MainTask < Taski::Task
+  exports :summary
+
+  def run
+    puts "\nMainTask executing..."
+    puts "  Root task is: #{Taski.context.root_task}"
+    puts "  Environment: #{Taski.context[:env]}"
+
+    # Access dependencies
+    setup = SetupTask.setup_info
+    output = FileProcessor.output_path
+    timing = TimingTask.duration_info
+
+    @summary = {
+      setup: setup,
+      output_path: output,
+      timing: timing,
+      root_task: Taski.context.root_task.to_s
+    }
+
+    puts "\nExecution Summary:"
+    puts "  Setup directory: #{setup[:directory]}"
+    puts "  Output path: #{output}"
+    puts "  Total elapsed: #{timing[:elapsed_seconds].round(3)}s"
+  end
+end
+
+puts "\n1. Running MainTask with context options"
+puts "-" * 40
+MainTask.run(context: {env: "production", debug: true})
+
+puts "\n" + "=" * 40
+puts "\n2. Running SetupTask directly with different context"
+puts "-" * 40
+SetupTask.reset!
+SetupTask.run(context: {env: "staging"})
+
+puts "\n" + "=" * 40
+puts "\n3. Dependency Tree"
+puts "-" * 40
+puts MainTask.tree
+
+puts "\n" + "=" * 40
+puts "Context API demonstration complete!"
+puts "Note: Context provides runtime information and user options without affecting dependency analysis."

data/examples/data_pipeline_demo.rb

@@ -0,0 +1,231 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Taski Data Pipeline Example
+#
+# This example demonstrates a realistic data processing pipeline:
+# - Section API for switching data sources (production vs test)
+# - Multiple data sources fetched in parallel
+# - Data transformation and aggregation
+#
+# Run: ruby examples/data_pipeline_demo.rb
+# With progress: TASKI_FORCE_PROGRESS=1 ruby examples/data_pipeline_demo.rb
+
+require_relative "../lib/taski"
+
+# Section: Data source abstraction
+# Switch between production API and test fixtures
+class DataSourceSection < Taski::Section
+  interfaces :users, :sales, :activities
+
+  def impl
+    (ENV["USE_TEST_DATA"] == "true") ? TestData : ProductionData
+  end
+
+  # Production: Fetch from APIs (simulated with delays)
+  class ProductionData < Taski::Task
+    def run
+      puts "  [ProductionData] Fetching from APIs..."
+      sleep(0.3)
+
+      @users = [
+        {id: 1, name: "Alice", department: "Engineering"},
+        {id: 2, name: "Bob", department: "Sales"},
+        {id: 3, name: "Charlie", department: "Engineering"},
+        {id: 4, name: "Diana", department: "Marketing"}
+      ]
+
+      @sales = [
+        {user_id: 2, amount: 1000, date: "2024-01"},
+        {user_id: 2, amount: 1500, date: "2024-02"},
+        {user_id: 4, amount: 800, date: "2024-01"}
+      ]
+
+      @activities = [
+        {user_id: 1, action: :commit, count: 45},
+        {user_id: 3, action: :commit, count: 32},
+        {user_id: 1, action: :review, count: 12},
+        {user_id: 3, action: :review, count: 8}
+      ]
+
+      puts "  [ProductionData] Loaded #{@users.size} users, #{@sales.size} sales, #{@activities.size} activities"
+    end
+  end
+
+  # Test: Minimal fixture data (no delays)
+  class TestData < Taski::Task
+    def run
+      puts "  [TestData] Loading test fixtures..."
+
+      @users = [
+        {id: 1, name: "Test User", department: "Test Dept"}
+      ]
+
+      @sales = [
+        {user_id: 1, amount: 100, date: "2024-01"}
+      ]
+
+      @activities = [
+        {user_id: 1, action: :commit, count: 10}
+      ]
+
+      puts "  [TestData] Loaded minimal test data"
+    end
+  end
+end
+
+# Section: Report format selection
+class ReportFormatSection < Taski::Section
+  interfaces :format_report
+
+  def impl
+    (ENV["REPORT_FORMAT"] == "json") ? JsonFormat : TextFormat
+  end
+
+  class TextFormat < Taski::Task
+    def run
+      @format_report = ->(report) {
+        report.map do |dept, stats|
+          "#{dept}: #{stats[:user_count]} users, $#{stats[:total_sales]} sales"
+        end.join("\n")
+      }
+    end
+  end
+
+  class JsonFormat < Taski::Task
+    def run
+      require "json"
+      @format_report = ->(report) { JSON.pretty_generate(report) }
+    end
+  end
+end
+
+# Transform: Enrich users with sales data
+class EnrichWithSales < Taski::Task
+  exports :users_with_sales
+
+  def run
+    users = DataSourceSection.users
+    sales = DataSourceSection.sales
+
+    sales_by_user = sales.group_by { |s| s[:user_id] }
+      .transform_values { |records| records.sum { |r| r[:amount] } }
+
+    @users_with_sales = users.map do |user|
+      user.merge(total_sales: sales_by_user[user[:id]] || 0)
+    end
+
+    puts "  [EnrichWithSales] Enriched #{@users_with_sales.size} users"
+  end
+end
+
+# Transform: Enrich users with activity data
+class EnrichWithActivities < Taski::Task
+  exports :users_with_activities
+
+  def run
+    users = DataSourceSection.users
+    activities = DataSourceSection.activities
+
+    activities_by_user = activities.group_by { |a| a[:user_id] }
+      .transform_values do |records|
+      records.to_h { |r| [r[:action], r[:count]] }
+    end
+
+    @users_with_activities = users.map do |user|
+      user.merge(activities: activities_by_user[user[:id]] || {})
+    end
+
+    puts "  [EnrichWithActivities] Enriched #{@users_with_activities.size} users"
+  end
+end
+
+# Aggregate: Combine enrichments into profiles
+class BuildProfiles < Taski::Task
+  exports :profiles
+
+  def run
+    users_sales = EnrichWithSales.users_with_sales
+    users_activities = EnrichWithActivities.users_with_activities
+
+    activities_map = users_activities.to_h { |u| [u[:id], u[:activities]] }
+
+    @profiles = users_sales.map do |user|
+      user.merge(activities: activities_map[user[:id]] || {})
+    end
+
+    puts "  [BuildProfiles] Built #{@profiles.size} profiles"
+  end
+end
+
+# Output: Generate department report
+class GenerateReport < Taski::Task
+  exports :report, :formatted_output
+
+  def run
+    profiles = BuildProfiles.profiles
+    formatter = ReportFormatSection.format_report
+
+    by_department = profiles.group_by { |p| p[:department] }
+
+    @report = by_department.transform_values do |dept_users|
+      {
+        user_count: dept_users.size,
+        total_sales: dept_users.sum { |u| u[:total_sales] },
+        total_commits: dept_users.sum { |u| u[:activities][:commit] || 0 },
+        total_reviews: dept_users.sum { |u| u[:activities][:review] || 0 }
+      }
+    end
+
+    @formatted_output = formatter.call(@report)
+    puts "  [GenerateReport] Generated report for #{@report.size} departments"
+  end
+end
+
+# Demo execution
+puts "Taski Data Pipeline Demo"
+puts "=" * 50
+
+puts "\n1. Dependency Tree"
+puts "-" * 50
+puts GenerateReport.tree
+
+puts "\n2. Production Data (default)"
+puts "-" * 50
+ENV["USE_TEST_DATA"] = "false"
+ENV["REPORT_FORMAT"] = "text"
+
+start_time = Time.now
+GenerateReport.run
+elapsed = Time.now - start_time
+
+puts "\nReport (text format):"
+puts GenerateReport.formatted_output
+puts "\nCompleted in #{elapsed.round(3)}s"
+
+puts "\n" + "=" * 50
+puts "\n3. Test Data with JSON Format"
+puts "-" * 50
+ENV["USE_TEST_DATA"] = "true"
+ENV["REPORT_FORMAT"] = "json"
+
+# Reset all tasks for fresh execution
+[DataSourceSection, ReportFormatSection, EnrichWithSales,
+  EnrichWithActivities, BuildProfiles, GenerateReport].each(&:reset!)
+
+start_time = Time.now
+GenerateReport.run
+elapsed = Time.now - start_time
+
+puts "\nReport (JSON format):"
+puts GenerateReport.formatted_output
+puts "\nCompleted in #{elapsed.round(3)}s"
+
+puts "\n" + "=" * 50
+puts "Pipeline demonstration complete!"
+puts "\nKey concepts demonstrated:"
+puts "  - DataSourceSection: Switch between production/test data"
+puts "  - ReportFormatSection: Switch output format (text/JSON)"
+puts "  - Parallel execution of independent transforms"
+puts "\nTry with progress display:"
+puts "  TASKI_FORCE_PROGRESS=1 ruby examples/data_pipeline_demo.rb"

data/examples/parallel_progress_demo.rb

@@ -0,0 +1,72 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/taski"
+
+# Demo tasks that simulate parallel execution with progress display
+# Run with: TASKI_FORCE_PROGRESS=1 ruby examples/parallel_progress_demo.rb
+
+class DownloadLayer1 < Taski::Task
+  exports :layer1_data
+
+  def run
+    sleep(2.3) # Simulate download
+    @layer1_data = "Layer 1 data (base image)"
+  end
+end
+
+class DownloadLayer2 < Taski::Task
+  exports :layer2_data
+
+  def run
+    sleep(5.5) # Simulate slower download
+    @layer2_data = "Layer 2 data (dependencies)"
+  end
+end
+
+class DownloadLayer3 < Taski::Task
+  exports :layer3_data
+
+  def run
+    sleep(0.2) # Simulate fast download
+    @layer3_data = "Layer 3 data (application)"
+  end
+end
+
+class ExtractLayers < Taski::Task
+  exports :extracted_data
+
+  def run
+    # This task depends on all download tasks (via static analysis)
+    layer1 = DownloadLayer1.layer1_data
+    layer2 = DownloadLayer2.layer2_data
+    layer3 = DownloadLayer3.layer3_data
+
+    sleep(0.3) # Simulate extraction
+    @extracted_data = "Extracted: #{layer1}, #{layer2}, #{layer3}"
+  end
+end
+
+class VerifyImage < Taski::Task
+  exports :verification_result
+
+  def run
+    # Depends on ExtractLayers
+    data = ExtractLayers.extracted_data
+
+    sleep(0.2) # Simulate verification
+    @verification_result = "Verified: #{data}"
+  end
+end
+
+# Start progress display
+Taski.progress_display&.start
+
+# Execute the final task (all dependencies will be resolved automatically)
+result = VerifyImage.verification_result
+
+# Stop progress display
+Taski.progress_display&.stop
+
+puts "\n\nFinal result:"
+puts result

data/examples/quick_start.rb

@@ -19,7 +19,7 @@ puts "=" * 30
 class DatabaseSetup < Taski::Task
   exports :connection_string
 
-  def build
+  def run
     @connection_string = "postgresql://localhost/myapp"
     puts "Database configured"
   end
@@ -28,14 +28,14 @@ end
 class APIServer < Taski::Task
   exports :port
 
-  def build
-    # Automatic dependency: DatabaseSetup will be built first
+  def run
+    # Automatic dependency: DatabaseSetup will be executed first
     puts "Starting API with #{DatabaseSetup.connection_string}"
     @port = 3000
   end
 end
 
 # Execute - dependencies are resolved automatically
-APIServer.build
+APIServer.run
 
 puts "\n✅ Result: APIServer running on port #{APIServer.port}"