taski 0.2.3 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da68d3dc067cdf14dd29a438cbf88cc7b00769000682417dc3395eb63f1a1659
-  data.tar.gz: a5ec661eeea77a73f77b07cbc09dfc4aef88fce2e856bac0366a5e32782356cc
+  metadata.gz: 80c881415617aa09fb7ae24441c38c677af816c20f356cc06ea82bba50639820
+  data.tar.gz: cc0c6e07e3f53c312844dc237ebebe344a0201bb772f1c6c20ee8c6476b9db30
 SHA512:
-  metadata.gz: 68b3c5ddaf63a71067fea5f3c6fdc47c80e6a020f0e7bd417f8cc03e8f595aa4a3f0b16826bf3d8a65935959ee7a243074c51db4bb766c296d25c73817fe90a8
-  data.tar.gz: ed2a3f80b1a5987c9a2ce8d410c6594c4edd35483a1be9507de0565582facba12e238f2862ae5964af27180431c21b3b80d00887aab8525ee89af2bfb91a507a
+  metadata.gz: 5e40462d8b2b359c17f28f16ec03524ee649324eb4e21eaf365fd147ccedad6bb3d683ece9021975683b1b121c93ad1da2bdaa0fed82ec37797090fadc79129c
+  data.tar.gz: 441c9553cded529843af032347f4590f9b6a289bd00f3a8ccbbe996b6be43d2154bc6e2fc4f84a94c1f18c35eb4cfcf5408ff07f6b8878b4f50e41c32a407756

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,59 @@ 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
+    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
+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
 
@@ -157,6 +197,11 @@ puts WebServer.tree
 # => └── Config
 # =>     ├── Database
 # =>     └── Cache
+
+# Sections also appear in dependency trees
+puts AppServer.tree
+# => AppServer
+# => └── DatabaseSection
 ```
 
 ### Progress Display
@@ -309,8 +354,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
 

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,206 @@
+#!/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
+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
+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

data/lib/taski/dependency_analyzer.rb

@@ -15,52 +15,79 @@ module Taski
         file_path, line_number = source_location
         return [] unless File.exist?(file_path)
 
-        begin
-          result = Prism.parse_file(file_path)
-
-          unless result.success?
-            Taski.logger.error("Parse errors in source file",
-              file: file_path,
-              errors: result.errors.map(&:message),
-              method: "#{klass}##{method_name}")
-            return []
-          end
+        parse_source_file(file_path, line_number, klass, method_name)
+      end
 
-          # Handle warnings if present
-          if result.warnings.any?
-            Taski.logger.warn("Parse warnings in source file",
-              file: file_path,
-              warnings: result.warnings.map(&:message),
-              method: "#{klass}##{method_name}")
-          end
+      private
 
-          dependencies = []
-          method_node = find_method_node(result.value, method_name, line_number)
+      # Parse source file and extract dependencies with proper error handling
+      # @param file_path [String] Path to source file
+      # @param line_number [Integer] Line number of method definition
+      # @param klass [Class] Class containing the method
+      # @param method_name [Symbol] Method name being analyzed
+      # @return [Array<Class>] Array of dependency classes
+      def parse_source_file(file_path, line_number, klass, method_name)
+        result = Prism.parse_file(file_path)
+        handle_parse_errors(result, file_path, klass, method_name)
+        extract_dependencies_from_node(result.value, line_number, klass, method_name)
+      rescue IOError, SystemCallError => e
+        Taski.logger.error("Failed to read source file",
+          file: file_path,
+          error: e.message,
+          method: "#{klass}##{method_name}")
+        []
+      rescue => e
+        Taski.logger.error("Failed to analyze method dependencies",
+          class: klass.name,
+          method: method_name,
+          error: e.message,
+          error_class: e.class.name)
+        []
+      end
 
-          if method_node
-            visitor = TaskDependencyVisitor.new(klass)
-            visitor.visit(method_node)
-            dependencies = visitor.dependencies
-          end
+      # Handle parse errors and warnings from Prism parsing
+      # @param result [Prism::ParseResult] Parse result from Prism
+      # @param file_path [String] Path to source file
+      # @param klass [Class] Class containing the method
+      # @param method_name [Symbol] Method name being analyzed
+      # @return [Array] Empty array if errors found
+      # @raise [RuntimeError] If parse fails
+      def handle_parse_errors(result, file_path, klass, method_name)
+        unless result.success?
+          Taski.logger.error("Parse errors in source file",
+            file: file_path,
+            errors: result.errors.map(&:message),
+            method: "#{klass}##{method_name}")
+          return []
+        end
 
-          dependencies.uniq
-        rescue IOError, SystemCallError => e
-          Taski.logger.error("Failed to read source file",
+        # Handle warnings if present
+        if result.warnings.any?
+          Taski.logger.warn("Parse warnings in source file",
             file: file_path,
-            error: e.message,
+            warnings: result.warnings.map(&:message),
             method: "#{klass}##{method_name}")
-          []
-        rescue => e
-          Taski.logger.error("Failed to analyze method dependencies",
-            class: klass.name,
-            method: method_name,
-            error: e.message,
-            error_class: e.class.name)
-          []
         end
       end
 
-      private
+      # Extract dependencies from parsed AST node
+      # @param root_node [Prism::Node] Root AST node
+      # @param line_number [Integer] Line number of method definition
+      # @param klass [Class] Class containing the method
+      # @param method_name [Symbol] Method name being analyzed
+      # @return [Array<Class>] Array of unique dependency classes
+      def extract_dependencies_from_node(root_node, line_number, klass, method_name)
+        dependencies = []
+        method_node = find_method_node(root_node, method_name, line_number)
+
+        if method_node
+          visitor = TaskDependencyVisitor.new(klass)
+          visitor.visit(method_node)
+          dependencies = visitor.dependencies
+        end
+
+        dependencies.uniq
+      end
 
       def find_method_node(node, method_name, target_line)
         return nil unless node
@@ -138,15 +165,16 @@ module Taski
           begin
             resolved_class = nil
 
-            # 1. Try absolute reference first (existing logic)
+            # Try absolute reference first for performance and clarity
             if Object.const_defined?(const_name)
               resolved_class = Object.const_get(const_name)
-            # 2. Try relative reference within namespace context
+            # Fall back to relative reference for nested module support
+            # This enables tasks defined inside modules to reference siblings
             elsif @context_class
               resolved_class = resolve_relative_constant(const_name)
             end
 
-            if resolved_class&.is_a?(Class) && resolved_class < Taski::Task
+            if resolved_class&.is_a?(Class) && (resolved_class < Taski::Task || resolved_class < Taski::Section)
               @constant_cache[const_name] = resolved_class
               @dependencies << resolved_class
             else

data/lib/taski/exceptions.rb

@@ -11,4 +11,7 @@ module Taski
 
   # Raised when task building fails during execution
   class TaskBuildError < StandardError; end
+
+  # Raised when section implementation method is missing
+  class SectionImplementationError < StandardError; end
 end