taski 0.2.0 → 0.2.2

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,7 +1,19 @@
 #!/usr/bin/env ruby
-# Quick Start example from README
+# frozen_string_literal: true
 
-require_relative '../lib/taski'
+# 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
@@ -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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'prism'
+require "prism"
 
 module Taski
   module DependencyAnalyzer
@@ -19,13 +19,19 @@ module Taski
           result = Prism.parse_file(file_path)
 
           unless result.success?
-            warn "Taski: Parse errors in #{file_path}: #{result.errors.map(&:message).join(', ')}"
+            Taski.logger.error("Parse errors in source file",
+              file: file_path,
+              errors: result.errors.map(&:message),
+              method: "#{klass}##{method_name}")
             return []
           end
 
           # Handle warnings if present
           if result.warnings.any?
-            warn "Taski: Parse warnings in #{file_path}: #{result.warnings.map(&:message).join(', ')}"
+            Taski.logger.warn("Parse warnings in source file",
+              file: file_path,
+              warnings: result.warnings.map(&:message),
+              method: "#{klass}##{method_name}")
           end
 
           dependencies = []
@@ -39,10 +45,17 @@ module Taski
 
           dependencies.uniq
         rescue IOError, SystemCallError => e
-          warn "Taski: Failed to read file #{file_path}: #{e.message}"
+          Taski.logger.error("Failed to read source file",
+            file: file_path,
+            error: e.message,
+            method: "#{klass}##{method_name}")
           []
         rescue => e
-          warn "Taski: Failed to analyze method #{klass}##{method_name}: #{e.message}"
+          Taski.logger.error("Failed to analyze method dependencies",
+            class: klass.name,
+            method: method_name,
+            error: e.message,
+            error_class: e.class.name)
           []
         end
       end
@@ -151,12 +164,9 @@ module Taski
             else
               child_name
             end
-          else
-            nil
           end
         end
       end
-
     end
   end
 end

data/lib/taski/exceptions.rb

@@ -2,13 +2,13 @@
 
 module Taski
   # Custom exceptions for Taski framework
-  
+
   # Raised when circular dependencies are detected between tasks
   class CircularDependencyError < StandardError; end
-  
+
   # Raised when task analysis fails (e.g., constant resolution errors)
   class TaskAnalysisError < StandardError; end
-  
+
   # Raised when task building fails during execution
   class TaskBuildError < StandardError; end
-end
+end

data/lib/taski/logger.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+module Taski
+  # Enhanced logging functionality for Taski framework
+  # Provides structured logging with multiple levels and context information
+  class Logger
+    # Log levels in order of severity
+    LEVELS = {debug: 0, info: 1, warn: 2, error: 3}.freeze
+
+    # @param level [Symbol] Minimum log level to output (:debug, :info, :warn, :error)
+    # @param output [IO] Output destination (default: $stdout)
+    # @param format [Symbol] Log format (:simple, :structured, :json)
+    def initialize(level: :info, output: $stdout, format: :structured)
+      @level = level
+      @output = output
+      @format = format
+      @start_time = Time.now
+    end
+
+    # Log debug message with optional context
+    # @param message [String] Log message
+    # @param context [Hash] Additional context information
+    def debug(message, **context)
+      log(:debug, message, context)
+    end
+
+    # Log info message with optional context
+    # @param message [String] Log message
+    # @param context [Hash] Additional context information
+    def info(message, **context)
+      log(:info, message, context)
+    end
+
+    # Log warning message with optional context
+    # @param message [String] Log message
+    # @param context [Hash] Additional context information
+    def warn(message, **context)
+      log(:warn, message, context)
+    end
+
+    # Log error message with optional context
+    # @param message [String] Log message
+    # @param context [Hash] Additional context information
+    def error(message, **context)
+      log(:error, message, context)
+    end
+
+    # Log task build start event
+    # @param task_name [String] Name of the task being built
+    # @param dependencies [Array] List of task dependencies
+    # @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 }
+      }
+      context[:args] = args if args && !args.empty?
+
+      info("Task build started", **context)
+    end
+
+    # Log task build completion event
+    # @param task_name [String] Name of the task that was built
+    # @param duration [Float] Build duration in seconds
+    def task_build_complete(task_name, duration: nil)
+      context = {task: task_name}
+      context[:duration_ms] = (duration * 1000).round(2) if duration
+      info("Task build completed", **context)
+    end
+
+    # Log task build failure event
+    # @param task_name [String] Name of the task that failed
+    # @param error [Exception] The error that occurred
+    # @param duration [Float] Duration before failure in seconds
+    def task_build_failed(task_name, error:, duration: nil)
+      context = {
+        task: task_name,
+        error_class: error.class.name,
+        error_message: error.message
+      }
+      context[:duration_ms] = (duration * 1000).round(2) if duration
+      context[:backtrace] = error.backtrace&.first(3) if error.backtrace
+      error("Task build failed", **context)
+    end
+
+    # Log dependency resolution event
+    # @param task_name [String] Name of the task resolving dependencies
+    # @param resolved_count [Integer] Number of dependencies resolved
+    def dependency_resolved(task_name, resolved_count:)
+      debug("Dependencies resolved",
+        task: task_name,
+        resolved_dependencies: resolved_count)
+    end
+
+    # Log circular dependency detection
+    # @param cycle_path [Array] The circular dependency path
+    def circular_dependency_detected(cycle_path)
+      error("Circular dependency detected",
+        cycle: cycle_path.map { |klass| klass.name || klass.inspect },
+        cycle_length: cycle_path.size)
+    end
+
+    private
+
+    # Core logging method
+    # @param level [Symbol] Log level
+    # @param message [String] Log message
+    # @param context [Hash] Additional context
+    def log(level, message, context)
+      return unless should_log?(level)
+
+      case @format
+      when :simple
+        log_simple(level, message, context)
+      when :structured
+        log_structured(level, message, context)
+      when :json
+        log_json(level, message, context)
+      end
+    end
+
+    # Check if message should be logged based on current level
+    # @param level [Symbol] Message level to check
+    # @return [Boolean] True if message should be logged
+    def should_log?(level)
+      LEVELS[@level] <= LEVELS[level]
+    end
+
+    # Simple log format: [LEVEL] message
+    def log_simple(level, message, context)
+      @output.puts "[#{level.upcase}] #{message}"
+    end
+
+    # Structured log format with timestamp and context
+    def log_structured(level, message, context)
+      timestamp = Time.now.strftime("%Y-%m-%d %H:%M:%S.%3N")
+      elapsed = ((Time.now - @start_time) * 1000).round(1)
+
+      line = "[#{timestamp}] [#{elapsed}ms] #{level.to_s.upcase.ljust(5)} Taski: #{message}"
+
+      unless context.empty?
+        context_parts = context.map do |key, value|
+          "#{key}=#{format_value(value)}"
+        end
+        line += " (#{context_parts.join(", ")})"
+      end
+
+      @output.puts line
+    end
+
+    # JSON log format for structured logging systems
+    def log_json(level, message, context)
+      require "json"
+
+      log_entry = {
+        timestamp: Time.now.iso8601(3),
+        level: level.to_s,
+        logger: "taski",
+        message: message,
+        elapsed_ms: ((Time.now - @start_time) * 1000).round(1)
+      }.merge(context)
+
+      @output.puts JSON.generate(log_entry)
+    end
+
+    # Format values for structured logging
+    def format_value(value)
+      case value
+      when String
+        (value.length > 50) ? "#{value[0..47]}..." : value
+      when Array
+        (value.size > 5) ? "[#{value[0..4].join(", ")}, ...]" : value.inspect
+      when Hash
+        (value.size > 3) ? "{#{value.keys[0..2].join(", ")}, ...}" : value.inspect
+      else
+        value.inspect
+      end
+    end
+  end
+
+  class << self
+    # Get the current logger instance
+    # @return [Logger] Current logger instance
+    def logger
+      @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
+    # @param format [Symbol] Log format (:simple, :structured, :json)
+    def configure_logger(level: :info, output: $stdout, format: :structured)
+      @logger = Logger.new(level: level, output: output, format: format)
+    end
+
+    # Set logger to quiet mode (only errors)
+    def quiet!
+      @logger = Logger.new(level: :error, output: @logger&.instance_variable_get(:@output) || $stdout)
+    end
+
+    # Set logger to verbose mode (all messages)
+    def verbose!
+      @logger = Logger.new(level: :debug, output: @logger&.instance_variable_get(:@output) || $stdout)
+    end
+  end
+end