taski 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28f2e52366511da4606df64a169c804712fcf4398b55a7b7d6430a1367cc183d
-  data.tar.gz: 97cc63c767ceaf7dda2fbb4345876c47d1fb1bf7e0395c8a2a0369bc8585e817
+  metadata.gz: 0c018d3aa27087ea7f87e11e01833ffe9c2e6118cc59af29f7f718b7706d108f
+  data.tar.gz: c18eb90fcfab955b8576b6329ee5df932fcdb8cfed9079c8705656c9e8b90de9
 SHA512:
-  metadata.gz: 4558c7e5ab3ae48301da573a0d2dffa935ecf2bdf7f04ccce1b92add5ea45b3aea1b562dcce0c6356d28b7eacd58fcdca030a9a2748fbafdda9d9046b5a09213
-  data.tar.gz: f440abca3014be0bffdd34cb8440f197b55403fc938660a8eb311e1bb6c64127bf9d033335d7e52f71cefec534ae4b6e41e2b83164d76b893d3a3c8f692bc221
+  metadata.gz: ea18fc4b07667fd17f2a37356c6a92c54daeadd4f7ad986d5e6131a4a717baf985548845789a17f8b5f5508de70354359a7413b957510d080b041c2f9cde6067
+  data.tar.gz: '08d4ce07b0bcde870805a2d5b0daf38d6a3cb850bc0e4da8b197c71b906d9f854fc8c97963362bd7b404b1709ded3d2d53975314bc31b19aab3967bdba903a19'

data/README.md

@@ -6,7 +6,7 @@
 
 > **🚧 Development Status:** Taski is currently under active development. Not yet recommended for production use.
 
-**Taski** is a Ruby framework for building task dependency graphs with automatic resolution and execution. It provides two APIs: static dependencies through **Exports** and dynamic dependencies through **Define**.
+**Taski** is a Ruby framework for building task dependency graphs with automatic resolution and execution. It provides three APIs: static dependencies through **Exports**, dynamic dependencies through **Define**, and abstraction layers through **Section**.
 
 > **Name Origin**: "Taski" comes from the Japanese word "襷" (tasuki), a sash used in relay races. Just like how runners pass the sash to the next teammate, tasks in Taski pass dependencies to one another in a continuous chain.
 
@@ -97,19 +97,61 @@ EnvironmentConfig.build
 # => Environment: production
 ```
 
+### Section API - Abstraction Layers
+
+For environment-specific implementations with clean interfaces:
+
+```ruby
+class DatabaseSection < Taski::Section
+  interface :host, :port
+
+  def impl  # No 'self' needed!
+    ENV['RAILS_ENV'] == 'production' ? Production : Development
+  end
+
+  class Production < Taski::Task
+    def build
+      @host = "prod-db.example.com"
+      @port = 5432
+    end
+  end
+
+  class Development < Taski::Task
+    def build
+      @host = "localhost"
+      @port = 5432
+    end
+  end
+
+  apply_auto_exports  # DRY - auto-adds exports to nested tasks
+end
+
+# Usage is simple - Section works like any Task
+class App < Taski::Task
+  def build
+    puts "DB: #{DatabaseSection.host}:#{DatabaseSection.port}"
+  end
+end
+
+App.build  # => DB: localhost:5432
+```
+
 ### When to Use Each API
 
 - **Define API**: Best for dynamic runtime dependencies. Cannot contain side effects in definition blocks. Dependencies are analyzed at class definition time, not runtime.
 - **Exports API**: Ideal for static dependencies. Supports side effects in build methods.
+- **Section API**: Perfect for abstraction layers where you need different implementations based on runtime conditions while maintaining static analysis capabilities.
 
 | Use Case | API | Example |
 |----------|-----|---------|
 | Configuration values | Exports | File paths, settings |
-| Environment-specific logic | Define | Different services per env |
+| Environment-specific logic | Define/Section | Different services per env |
 | Side effects | Exports | Database connections, I/O |
 | Conditional processing | Define | Algorithm selection |
+| Implementation abstraction | Section | Database/API adapters |
+| Multi-environment configs | Section | Dev/Test/Prod settings |
 
-**Note**: Define API analyzes dependencies when the class is defined. Conditional dependencies like `ENV['USE_NEW'] ? TaskA : TaskB` will only include the task selected at class definition time, not runtime.
+**Note**: Define API analyzes dependencies when the class is defined. Conditional dependencies like `ENV['USE_NEW'] ? TaskA : TaskB` will only include the task selected at class definition time, not runtime. Use Section API when you need true runtime selection.
 
 ## ✨ Key Features
 
@@ -118,6 +160,86 @@ EnvironmentConfig.build
 - **Circular Dependency Detection**: Clear error messages with detailed paths
 - **Granular Execution**: Build individual tasks or complete graphs
 - **Memory Management**: Built-in reset mechanisms
+- **Progress Display**: Visual feedback with spinners and output capture
+- **Dependency Tree Visualization**: Visual representation of task relationships
+
+### Dependency Tree Visualization
+
+Visualize task dependencies with the `tree` method:
+
+```ruby
+class Database < Taski::Task
+  exports :connection
+  def build; @connection = "db-conn"; end
+end
+
+class Cache < Taski::Task
+  exports :redis_url
+  def build; @redis_url = "redis://localhost"; end
+end
+
+class Config < Taski::Task
+  exports :settings
+  def build
+    @settings = {
+      database: Database.connection,
+      cache: Cache.redis_url
+    }
+  end
+end
+
+class WebServer < Taski::Task
+  def build
+    puts "Starting with #{Config.settings}"
+  end
+end
+
+puts WebServer.tree
+# => WebServer
+# => └── Config
+# =>     ├── Database
+# =>     └── Cache
+
+# Sections also appear in dependency trees
+puts AppServer.tree
+# => AppServer
+# => └── DatabaseSection
+```
+
+### Progress Display
+
+Taski provides visual feedback during task execution with animated spinners and real-time output capture:
+
+```ruby
+class LongRunningTask < Taski::Task
+  def build
+    puts "Starting process..."
+    sleep(1.0)
+    puts "Processing data..."
+    puts "Almost done..."
+    sleep(0.5)
+    puts "Completed!"
+  end
+end
+
+LongRunningTask.build
+# During execution shows:
+# ⠧ LongRunningTask
+#   Starting process...
+#   Processing data...
+#   Almost done...
+#   Completed!
+#
+# After completion shows:
+# ✅ LongRunningTask (1500ms)
+```
+
+**Progress Display Features:**
+- **Spinner Animation**: Dots-style spinner during task execution
+- **Output Capture**: Real-time display of task output (last 5 lines)
+- **Status Indicators**: ✅ for success, ❌ for failure
+- **Execution Time**: Shows task duration after completion
+- **TTY Detection**: Clean output when redirected to files
 
 ### Granular Task Execution
 
@@ -190,7 +312,7 @@ class FileTask < Taski::Task
   def clean
     # ❌ Bad: Raises error if file doesn't exist
     # File.delete(@output_file)
-    
+
     # ✅ Good: Check before delete
     File.delete(@output_file) if File.exist?(@output_file)
   end
@@ -207,7 +329,7 @@ rescue Taski::CircularDependencyError => e
 end
 # => Circular dependency: Circular dependency detected!
 # => Cycle: TaskA → TaskB → TaskA
-# => 
+# =>
 # => The dependency chain is:
 # =>   1. TaskA is trying to build → TaskB
 # =>   2. TaskB is trying to build → TaskA
@@ -234,8 +356,9 @@ bundle exec rake test
 - **Task Base**: Core framework
 - **Exports API**: Static dependency resolution
 - **Define API**: Dynamic dependency resolution
+- **Section API**: Abstraction layer with runtime implementation selection
 - **Instance Management**: Thread-safe lifecycle
-- **Dependency Resolver**: Topological sorting
+- **Dependency Resolver**: Topological sorting with Section support
 
 ## Contributing
 
@@ -247,4 +370,4 @@ MIT License
 
 ---
 
-**Taski** - Build dependency graphs with elegant Ruby code. 🚀
+**Taski** - Build dependency graphs with elegant Ruby code. 🚀

data/examples/README.md

@@ -30,7 +30,17 @@ ruby examples/progress_demo.rb > build.log 2>&1
 cat build.log
 ```
 
-### 3. **[advanced_patterns.rb](advanced_patterns.rb)** - Complex Dependency Patterns
+### 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
+
+```bash
+ruby examples/section_configuration.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
@@ -44,6 +54,8 @@ ruby examples/advanced_patterns.rb
 
 - **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

data/examples/section_configuration.rb

@@ -0,0 +1,212 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Section Configuration Example
+# This example demonstrates how to use Taski::Section for dynamic implementation
+# selection and dependency resolution with configuration management.
+#
+# Key Features Demonstrated:
+# 1. DRY Principle: No need to duplicate 'exports' declarations in nested Task classes
+#    - interface declaration automatically adds exports to nested Task classes
+# 2. Consistent API: impl must return Task classes - .build is called automatically
+# 3. Dynamic Implementation Selection: Different implementations based on environment
+# 4. Dependency Resolution: Sections are properly detected in dependency analysis
+# 5. Tree Visualization: Sections appear in dependency trees
+
+require_relative "../lib/taski"
+
+# Example 1: Database Configuration Section
+# This section provides database configuration with different implementations
+# for development and production environments
+class DatabaseSection < Taski::Section
+  # Define the interface that implementations must provide
+  interface :host, :port, :username, :password, :database_name, :pool_size
+
+  # Select implementation based on environment
+  # Note: Must return a Task class - .build is automatically called
+  # No 'self' needed - just define as instance method!
+  def impl
+    if ENV["RAILS_ENV"] == "production"
+      Production
+    else
+      Development
+    end
+  end
+
+  # Production implementation with secure settings
+  # Note: exports are automatically inherited from interface declaration
+  class Production < Taski::Task
+    def build
+      @host = "prod-db.example.com"
+      @port = 5432
+      @username = "app_user"
+      @password = ENV["DB_PASSWORD"] || "secure_password"
+      @database_name = "myapp_production"
+      @pool_size = 25
+    end
+  end
+
+  # Development implementation with local settings
+  # Note: exports are automatically inherited from interface declaration
+  class Development < Taski::Task
+    def build
+      @host = "localhost"
+      @port = 5432
+      @username = "dev_user"
+      @password = "dev_password"
+      @database_name = "myapp_development"
+      @pool_size = 5
+    end
+  end
+
+  # Apply auto-exports after all nested Task classes are defined
+  apply_auto_exports
+end
+
+# Example 2: API Configuration Section
+# This section provides API endpoints and credentials
+class ApiSection < Taski::Section
+  interface :base_url, :api_key, :timeout, :retry_count
+
+  # No 'self' needed - just define as instance method!
+  def impl
+    # Select based on feature flag
+    # Note: Must return a Task class - .build is automatically called
+    if ENV["USE_STAGING_API"] == "true"
+      Staging
+    else
+      Production
+    end
+  end
+
+  # Note: exports are automatically inherited from interface declaration - DRY principle!
+  class Production < Taski::Task
+    def build
+      @base_url = "https://api.example.com/v1"
+      @api_key = ENV["PROD_API_KEY"] || "prod-key-123"
+      @timeout = 30
+      @retry_count = 3
+    end
+  end
+
+  # Note: exports are automatically inherited from interface declaration - DRY principle!
+  class Staging < Taski::Task
+    def build
+      @base_url = "https://staging-api.example.com/v1"
+      @api_key = ENV["STAGING_API_KEY"] || "staging-key-456"
+      @timeout = 60
+      @retry_count = 1
+    end
+  end
+
+  # Apply auto-exports after all nested Task classes are defined
+  apply_auto_exports
+end
+
+# Example 3: Task that depends on multiple sections
+class ApplicationSetup < Taski::Task
+  exports :config_summary
+
+  def build
+    puts "Setting up application with configuration:"
+    puts "Database: #{DatabaseSection.host}:#{DatabaseSection.port}/#{DatabaseSection.database_name}"
+    puts "API: #{ApiSection.base_url}"
+    puts "Pool size: #{DatabaseSection.pool_size}"
+    puts "API timeout: #{ApiSection.timeout}s"
+
+    @config_summary = {
+      database: {
+        host: DatabaseSection.host,
+        port: DatabaseSection.port,
+        database: DatabaseSection.database_name,
+        pool_size: DatabaseSection.pool_size
+      },
+      api: {
+        base_url: ApiSection.base_url,
+        timeout: ApiSection.timeout,
+        retry_count: ApiSection.retry_count
+      }
+    }
+  end
+end
+
+# Example 4: Complex dependency chain with sections
+class DatabaseConnection < Taski::Task
+  exports :connection
+
+  def build
+    puts "Connecting to database..."
+    # Use section configuration to create connection
+    connection_string = "postgresql://#{DatabaseSection.username}:#{DatabaseSection.password}@#{DatabaseSection.host}:#{DatabaseSection.port}/#{DatabaseSection.database_name}"
+    @connection = "Connected to: #{connection_string} (pool: #{DatabaseSection.pool_size})"
+    puts @connection
+  end
+end
+
+class ApiClient < Taski::Task
+  exports :client
+
+  def build
+    puts "Initializing API client..."
+    @client = "API Client: #{ApiSection.base_url} (timeout: #{ApiSection.timeout}s, retries: #{ApiSection.retry_count})"
+    puts @client
+  end
+end
+
+class Application < Taski::Task
+  def build
+    puts "\n=== Starting Application ==="
+
+    # Dependencies are automatically resolved
+    # DatabaseConnection and ApiClient will be built first
+    # which triggers building of their respective sections
+
+    puts "\nDatabase ready: #{DatabaseConnection.connection}"
+    puts "API ready: #{ApiClient.client}"
+
+    puts "\nApplication configuration summary:"
+    puts ApplicationSetup.config_summary.inspect
+
+    puts "\n=== Application Started Successfully ==="
+  end
+end
+
+# Demo script
+if __FILE__ == $0
+  puts "Taski Section Configuration Example"
+  puts "=" * 50
+
+  puts "\n1. Development Environment (default)"
+  ENV["RAILS_ENV"] = "development"
+  ENV["USE_STAGING_API"] = "false"
+
+  # Reset all tasks to ensure fresh build
+  [DatabaseSection, ApiSection, ApplicationSetup, DatabaseConnection, ApiClient, Application].each(&:reset!)
+
+  Application.build
+
+  puts "\n" + "=" * 50
+  puts "\n2. Production Environment with Staging API"
+  ENV["RAILS_ENV"] = "production"
+  ENV["USE_STAGING_API"] = "true"
+
+  # Reset all tasks to see different configuration
+  [DatabaseSection, ApiSection, ApplicationSetup, DatabaseConnection, ApiClient, Application].each(&:reset!)
+
+  Application.build
+
+  puts "\n" + "=" * 50
+  puts "\n3. Dependency Tree Visualization"
+  puts "\nApplication dependency tree:"
+  puts Application.tree
+
+  puts "\nDatabaseConnection dependency tree:"
+  puts DatabaseConnection.tree
+
+  puts "\nApiClient dependency tree:"
+  puts ApiClient.tree
+
+  puts "\n" + "=" * 50
+  puts "\nSection dependency resolution successfully demonstrated!"
+  puts "Notice how sections appear in the dependency trees and logs."
+end

data/examples/tree_demo.rb

@@ -76,5 +76,130 @@ puts WebServer.tree
 puts "\nConfig dependencies:"
 puts Config.tree
 
+puts "\n🔧 Section-based Architecture (Dynamic Implementation Selection):"
+
+# Create database section with multiple implementation options
+class DatabaseSection < Taski::Section
+  interface :connection_string, :pool_size
+
+  def self.impl
+    if ENV["DATABASE"] == "postgres"
+      PostgresImplementation
+    elsif ENV["DATABASE"] == "mysql"
+      MysqlImplementation
+    else
+      SQLiteImplementation
+    end
+  end
+
+  class PostgresImplementation < Taski::Task
+    exports :connection_string, :pool_size
+
+    def build
+      Logger.log_level
+      @connection_string = "postgresql://localhost/production_app"
+      @pool_size = 20
+    end
+  end
+
+  class MysqlImplementation < Taski::Task
+    exports :connection_string, :pool_size
+
+    def build
+      Logger.log_level
+      @connection_string = "mysql://localhost/production_app"
+      @pool_size = 15
+    end
+  end
+
+  class SQLiteImplementation < Taski::Task
+    exports :connection_string, :pool_size
+
+    def build
+      @connection_string = "sqlite:///tmp/development.db"
+      @pool_size = 1
+    end
+  end
+end
+
+# Cache section with Redis/Memory options
+class CacheSection < Taski::Section
+  interface :cache_url
+
+  def self.impl
+    if ENV["CACHE"] == "redis"
+      RedisCache
+    else
+      MemoryCache
+    end
+  end
+
+  class RedisCache < Taski::Task
+    exports :cache_url
+    def build
+      DatabaseSection.connection_string
+      @cache_url = "redis://localhost:6379"
+    end
+  end
+
+  class MemoryCache < Taski::Task
+    exports :cache_url
+    def build
+      @cache_url = "memory://local"
+    end
+  end
+end
+
+puts "\n📋 Section Trees (Show Available Implementations):"
+puts "\nDatabaseSection.tree:"
+puts DatabaseSection.tree
+
+puts "\nCacheSection.tree:"
+puts CacheSection.tree
+
+puts "\n🔍 Individual Implementation Trees (Show Actual Dependencies):"
+puts "\nDatabaseSection::PostgresImplementation.tree:"
+puts DatabaseSection::PostgresImplementation.tree
+
+puts "\nDatabaseSection::SQLiteImplementation.tree:"
+puts DatabaseSection::SQLiteImplementation.tree
+
+puts "\nCacheSection::RedisCache.tree:"
+puts CacheSection::RedisCache.tree
+
+puts "\n🔄 Section vs Implementation Comparison:"
+puts "Section shows POSSIBLE implementations:"
+puts DatabaseSection.tree
+puts "\nBut implementation shows ACTUAL dependencies:"
+puts DatabaseSection::PostgresImplementation.tree
+
+puts "\n💡 Workflow:"
+puts "1. Use DatabaseSection.tree to see what implementations are available"
+puts "2. Use DatabaseSection::PostgresImplementation.tree to see specific dependencies"
+puts "3. Runtime selects implementation based on ENV variables"
+
+puts "\n🎨 Colored Tree Display (if TTY supports colors):"
+
+# Enable colors for demonstration
+Taski::TreeColors.enabled = true
+
+puts "\nDatabaseSection.tree (with colors):"
+puts DatabaseSection.tree(color: true)
+
+puts "\nCacheSection.tree (with colors):"
+puts CacheSection.tree(color: true)
+
+puts "\nDatabaseSection::PostgresImplementation.tree (with colors):"
+puts DatabaseSection::PostgresImplementation.tree(color: true)
+
+puts "\n🎯 Color Legend:"
+puts "#{Taski::TreeColors.section("Blue")} = Section names (dynamic selection layer)"
+puts "#{Taski::TreeColors.task("Green")} = Task names (concrete implementations)"
+puts "#{Taski::TreeColors.implementations("Yellow")} = Implementation candidates"
+puts "#{Taski::TreeColors.connector("Gray")} = Tree connectors"
+
+# Reset colors to auto-detection
+Taski::TreeColors.enabled = nil
+
 puts "\n▶️  Building Application (to verify dependencies work):"
 Application.build