taski 0.2.1 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e44ea93464ceaf8994d761cec75cf4d32df7cdb8f90d25b4cfcae5be7f8a586
-  data.tar.gz: 8a1b5fae85bbffb28756f2e13b3f98c2cb8023c76346b5da722ac55e87ef3cc5
+  metadata.gz: da68d3dc067cdf14dd29a438cbf88cc7b00769000682417dc3395eb63f1a1659
+  data.tar.gz: a5ec661eeea77a73f77b07cbc09dfc4aef88fce2e856bac0366a5e32782356cc
 SHA512:
-  metadata.gz: '037285b1bc19edd6d674f6748674fa8443c0cb40d5199de86bdfa3696c1597308d69ff5236a7114c43cf666a27e62f5c4111c5a36301736c4fdac98cdd65b4c4'
-  data.tar.gz: afa967d630b56f9de1f4974879533572d06c42d574dce6bea69da9635ce69e06251af555168ff0b3475e95d5a1d6d07e8951e6052f0f6e04291d07b15d23239b
+  metadata.gz: 68b3c5ddaf63a71067fea5f3c6fdc47c80e6a020f0e7bd417f8cc03e8f595aa4a3f0b16826bf3d8a65935959ee7a243074c51db4bb766c296d25c73817fe90a8
+  data.tar.gz: ed2a3f80b1a5987c9a2ce8d410c6594c4edd35483a1be9507de0565582facba12e238f2862ae5964af27180431c21b3b80d00887aab8525ee89af2bfb91a507a

data/README.md

@@ -99,7 +99,7 @@ EnvironmentConfig.build
 
 ### When to Use Each API
 
-- **Define API**: Best for dynamic runtime dependencies. Cannot contain side effects in definition blocks.
+- **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.
 
 | Use Case | API | Example |
@@ -109,6 +109,8 @@ EnvironmentConfig.build
 | Side effects | Exports | Database connections, I/O |
 | Conditional processing | Define | Algorithm selection |
 
+**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.
+
 ## ✨ Key Features
 
 - **Automatic Dependency Resolution**: Dependencies detected through static analysis
@@ -116,6 +118,81 @@ 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
+```
+
+### 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
 
@@ -172,6 +249,29 @@ WebServer.clean
 # => Database disconnected
 ```
 
+### Clean Method Idempotency
+
+**Important**: The `clean` method must be idempotent - safe to call multiple times without errors.
+
+```ruby
+class FileTask < Taski::Task
+  exports :output_file
+
+  def build
+    @output_file = '/tmp/data.csv'
+    File.write(@output_file, process_data)
+  end
+
+  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
+end
+```
+
 ### Error Handling
 
 ```ruby
@@ -182,7 +282,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
@@ -222,4 +322,4 @@ MIT License
 
 ---
 
-**Taski** - Build dependency graphs with elegant Ruby code. 🚀
+**Taski** - Build dependency graphs with elegant Ruby code. 🚀

data/examples/README.md

@@ -0,0 +1,57 @@
+# Taski Examples
+
+Learn Taski through practical examples, from basic concepts to advanced patterns.
+
+## Getting Started
+
+Start with these examples in order:
+
+### 1. **[quick_start.rb](quick_start.rb)** - Your First Taski Program
+- Basic task definition with Exports API
+- Automatic dependency resolution
+- Simple task execution
+
+```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
+
+```bash
+# Interactive mode with rich spinner
+ruby examples/progress_demo.rb
+
+# Clean output mode (no spinner)
+ruby examples/progress_demo.rb > build.log 2>&1
+cat build.log
+```
+
+### 3. **[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
+
+```bash
+ruby examples/advanced_patterns.rb
+```
+
+## Key Concepts Demonstrated
+
+- **Exports API**: Static dependencies with `exports :property`
+- **Define API**: Dynamic dependencies with `define :property, -> { ... }`
+- **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
+
+## 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/`

data/examples/{complex_example.rb → advanced_patterns.rb}

@@ -1,8 +1,22 @@
 #!/usr/bin/env ruby
-# Complex example from README showing both APIs
+# frozen_string_literal: true
+
+# Taski Advanced Patterns
+#
+# This example demonstrates advanced Taski patterns:
+# - Mixed usage of Exports API and Define API
+# - Environment-specific dependency resolution
+# - Feature flag integration with dynamic dependencies
+# - Task reset and rebuild scenarios
+# - Conditional dependency evaluation
+#
+# Run: ruby examples/advanced_patterns.rb
 
 require_relative "../lib/taski"
 
+puts "⚡ Advanced Taski Patterns"
+puts "=" * 40
+
 # Mock classes for the example
 class ProductionDB < Taski::Task
   exports :connection_string
@@ -81,8 +95,6 @@ class Application < Taski::Task
 end
 
 # Test different environments
-puts "=== Complex Example ==="
-
 puts "\n1. Development Environment (default):"
 ENV.delete("RAILS_ENV")
 ENV.delete("FEATURE_REDIS_CACHE")

data/examples/progress_demo.rb

@@ -0,0 +1,166 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Taski Progress Display Demo
+#
+# This comprehensive example demonstrates all progress display features:
+# 1. Basic spinner animation with success/failure indicators
+# 2. Output capture with 5-line tail display
+# 3. Real-world build scenario with external command simulation
+# 4. TTY detection for clean file output
+#
+# Run: ruby examples/progress_demo.rb
+# Try: ruby examples/progress_demo.rb > build.log 2>&1 && cat build.log
+
+require_relative "../lib/taski"
+
+puts "🎯 Taski Progress Display Demo"
+puts "=" * 50
+
+# SECTION 1: Basic Spinner Animation
+puts "\n📍 SECTION 1: Basic Spinner & Success/Failure Indicators"
+puts "-" * 50
+
+class ConfigTask < Taski::Task
+  exports :database_url, :cache_url
+
+  def build
+    sleep 0.8
+    @database_url = "postgres://localhost/myapp"
+    @cache_url = "redis://localhost:6379"
+  end
+end
+
+class DatabaseTask < Taski::Task
+  exports :connection
+
+  def build
+    sleep 1.2
+    @connection = "Connected to #{ConfigTask.database_url}"
+  end
+end
+
+class ApplicationTask < Taski::Task
+  exports :status
+
+  def build
+    sleep 1.0
+    db = DatabaseTask.connection
+    @status = "App ready! #{db}"
+  end
+end
+
+ApplicationTask.build
+puts "🎉 Application Status: #{ApplicationTask.status}"
+
+# SECTION 2: Output Capture Demo
+puts "\n📍 SECTION 2: Output Capture with 5-Line Tail"
+puts "-" * 50
+
+class VerboseTask < Taski::Task
+  exports :result
+
+  def build
+    puts "Starting task initialization..."
+    sleep 0.3
+
+    puts "Loading configuration files..."
+    puts "Connecting to database..."
+    puts "Connection established: localhost:5432"
+    sleep 0.3
+
+    puts "Running initial checks..."
+    puts "Checking schema version..."
+    puts "Schema is up to date"
+    puts "Performing data validation..."
+    puts "Validating user records..."
+    puts "Validating product records..."
+    puts "All validations passed"
+    sleep 0.4
+
+    puts "Task completed successfully!"
+    @result = "All operations completed"
+  end
+end
+
+VerboseTask.build
+puts "📊 Verbose Task Result: #{VerboseTask.result}"
+
+# SECTION 3: Production Build Scenario
+puts "\n📍 SECTION 3: Production Build Scenario"
+puts "-" * 50
+
+class CompileTask < Taski::Task
+  exports :result
+
+  def build
+    puts "Starting compilation process..."
+    sleep 0.8
+
+    puts "Checking source files..."
+    puts "Found: main.c, utils.c, config.h"
+    sleep 0.6
+
+    puts "Running gcc compilation..."
+    puts "gcc -Wall -O2 -c main.c"
+    puts "gcc -Wall -O2 -c utils.c"
+    puts "main.c: In function 'main':"
+    puts "main.c:42: warning: unused variable 'temp'"
+    puts "utils.c: In function 'parse_config':"
+    puts "utils.c:15: warning: implicit declaration of function 'strcpy'"
+    sleep 0.8
+
+    puts "Linking objects..."
+    puts "gcc -o myapp main.o utils.o"
+    puts "Compilation successful!"
+
+    @result = "myapp binary created"
+  end
+end
+
+class TestTask < Taski::Task
+  exports :test_result
+
+  def build
+    puts "Running test suite..."
+    sleep 0.2
+
+    (1..8).each do |i|
+      puts "Test #{i}/8: #{["PASS", "PASS", "FAIL", "PASS", "PASS", "PASS", "PASS", "PASS"][i - 1]}"
+      sleep 0.4
+    end
+
+    puts "Test summary: 7/8 passed, 1 failed"
+    @test_result = "Tests completed with 1 failure"
+  end
+end
+
+CompileTask.build
+puts "📦 Compilation: #{CompileTask.result}"
+
+TestTask.build
+puts "🧪 Test Result: #{TestTask.test_result}"
+
+# SECTION 4: Error Handling Demo
+puts "\n📍 SECTION 4: Error Handling Demo"
+puts "-" * 50
+
+class FailingTask < Taski::Task
+  def build
+    puts "Attempting network connection..."
+    sleep 1.0  # Watch it spin before failing
+    puts "Connection timeout after 30 seconds"
+    puts "Retrying connection..."
+    sleep 0.5
+    raise StandardError, "Network connection failed!"
+  end
+end
+
+begin
+  FailingTask.build
+rescue Taski::TaskBuildError => e
+  puts "🛡️  Error handled gracefully: #{e.message}"
+end
+
+puts "\n✨ Demo Complete!"
+puts "Note: Rich spinner display only appears in terminals, not when output is redirected."

data/examples/{readme_example.rb → quick_start.rb}

@@ -1,8 +1,20 @@
 #!/usr/bin/env ruby
-# Quick Start example from README
+# frozen_string_literal: true
+
+# Taski Quick Start Guide
+#
+# This example demonstrates the fundamentals of Taski:
+# - Task definition with the Exports API
+# - Automatic dependency resolution
+# - Simple task execution
+#
+# Run: ruby examples/quick_start.rb
 
 require_relative "../lib/taski"
 
+puts "🚀 Taski Quick Start"
+puts "=" * 30
+
 # Simple static dependency using Exports API
 class DatabaseSetup < Taski::Task
   exports :connection_string
@@ -24,7 +36,6 @@ class APIServer < Taski::Task
 end
 
 # Execute - dependencies are resolved automatically
-puts "=== Quick Start Example ==="
 APIServer.build
 
-puts "\nResult: APIServer running on port #{APIServer.port}"
+puts "\n✅ Result: APIServer running on port #{APIServer.port}"

data/examples/tree_demo.rb

@@ -0,0 +1,80 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Tree Display Demo
+#
+# This example demonstrates the tree display functionality that shows
+# task dependency relationships in a visual tree format.
+#
+# Run: ruby examples/tree_demo.rb
+
+require_relative "../lib/taski"
+
+puts "🌲 Taski Tree Display Demo"
+puts "=" * 40
+
+# Create a dependency chain for demonstration
+class Database < Taski::Task
+  exports :connection_string
+
+  def build
+    @connection_string = "postgres://localhost/myapp"
+  end
+end
+
+class Cache < Taski::Task
+  exports :redis_url
+
+  def build
+    @redis_url = "redis://localhost:6379"
+  end
+end
+
+class Config < Taski::Task
+  exports :settings
+
+  def build
+    @settings = {
+      database: Database.connection_string,
+      cache: Cache.redis_url,
+      port: 3000
+    }
+  end
+end
+
+class Logger < Taski::Task
+  exports :log_level
+
+  def build
+    @log_level = "info"
+  end
+end
+
+class WebServer < Taski::Task
+  exports :server_instance
+
+  def build
+    @server_instance = "WebServer configured with #{Config.settings[:database]} and #{Logger.log_level}"
+  end
+end
+
+class Application < Taski::Task
+  def build
+    puts "Starting application..."
+    puts "Web server: #{WebServer.server_instance}"
+    puts "Config: #{Config.settings}"
+  end
+end
+
+puts "\n📊 Application Dependency Tree:"
+puts Application.tree
+
+puts "\n🔍 Individual Component Trees:"
+puts "\nWebServer dependencies:"
+puts WebServer.tree
+
+puts "\nConfig dependencies:"
+puts Config.tree
+
+puts "\n▶️  Building Application (to verify dependencies work):"
+Application.build

data/lib/taski/dependency_analyzer.rb

@@ -38,7 +38,7 @@ module Taski
           method_node = find_method_node(result.value, method_name, line_number)
 
           if method_node
-            visitor = TaskDependencyVisitor.new
+            visitor = TaskDependencyVisitor.new(klass)
             visitor.visit(method_node)
             dependencies = visitor.dependencies
           end
@@ -96,9 +96,10 @@ module Taski
       class TaskDependencyVisitor < Prism::Visitor
         attr_reader :dependencies
 
-        def initialize
+        def initialize(context_class = nil)
           @dependencies = []
           @constant_cache = {}
+          @context_class = context_class
         end
 
         def visit_constant_read_node(node)
@@ -135,14 +136,19 @@ module Taski
           return @dependencies << cached_result if cached_result # Cached positive result
 
           begin
+            resolved_class = nil
+
+            # 1. Try absolute reference first (existing logic)
             if Object.const_defined?(const_name)
-              klass = Object.const_get(const_name)
-              if klass.is_a?(Class) && klass < Taski::Task
-                @constant_cache[const_name] = klass
-                @dependencies << klass
-              else
-                @constant_cache[const_name] = false
-              end
+              resolved_class = Object.const_get(const_name)
+            # 2. Try relative reference within namespace context
+            elsif @context_class
+              resolved_class = resolve_relative_constant(const_name)
+            end
+
+            if resolved_class&.is_a?(Class) && resolved_class < Taski::Task
+              @constant_cache[const_name] = resolved_class
+              @dependencies << resolved_class
             else
               @constant_cache[const_name] = false
             end
@@ -151,6 +157,32 @@ module Taski
           end
         end
 
+        def resolve_relative_constant(const_name)
+          return nil unless @context_class
+
+          # Get the namespace from the context class
+          namespace = get_namespace_from_class(@context_class)
+          return nil unless namespace
+
+          # Try to resolve the constant within the namespace
+          full_const_name = "#{namespace}::#{const_name}"
+          Object.const_get(full_const_name) if Object.const_defined?(full_const_name)
+        rescue NameError, ArgumentError
+          nil
+        end
+
+        def get_namespace_from_class(klass)
+          # Extract namespace from class name (e.g., "A::AB" -> "A")
+          class_name = klass.name
+          return nil unless class_name&.include?("::")
+
+          # Split by "::" and take all but the last part
+          parts = class_name.split("::")
+          return nil if parts.length <= 1  # No namespace
+
+          parts[0..-2].join("::")
+        end
+
         def extract_constant_path(node)
           case node
           when Prism::ConstantReadNode

data/lib/taski/logger.rb

@@ -48,11 +48,16 @@ module Taski
     # Log task build start event
     # @param task_name [String] Name of the task being built
     # @param dependencies [Array] List of task dependencies
-    def task_build_start(task_name, dependencies: [])
-      info("Task build started",
+    # @param args [Hash] Build arguments for parametrized builds
+    def task_build_start(task_name, dependencies: [], args: nil)
+      context = {
         task: task_name,
         dependencies: dependencies.size,
-        dependency_names: dependencies.map { |dep| dep.is_a?(Hash) ? dep[:klass].inspect : dep.inspect })
+        dependency_names: dependencies.map { |dep| dep.is_a?(Hash) ? dep[:klass].inspect : dep.inspect }
+      }
+      context[:args] = args if args && !args.empty?
+
+      info("Task build started", **context)
     end
 
     # Log task build completion event
@@ -181,6 +186,12 @@ module Taski
       @logger ||= Logger.new
     end
 
+    # Get the current progress display instance (always enabled)
+    # @return [ProgressDisplay] Current progress display instance
+    def progress_display
+      @progress_display ||= ProgressDisplay.new(force_enable: ENV["TASKI_FORCE_PROGRESS"] == "1")
+    end
+
     # Configure the logger with new settings
     # @param level [Symbol] Log level (:debug, :info, :warn, :error)
     # @param output [IO] Output destination