taski 0.2.3 → 0.3.1

data/lib/taski/task/base.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../exceptions"
+require_relative "../utils/tree_display_helper"
 
 module Taski
   # Base Task class that provides the foundation for task framework
@@ -19,7 +20,7 @@ module Taski
       def method_added(method_name)
         super
         return unless ANALYZED_METHODS.include?(method_name)
-        # Only call if the method is available (loaded by dependency_resolver)
+        # Avoid calling before dependency_resolver module is loaded
         analyze_dependencies_at_definition if respond_to?(:analyze_dependencies_at_definition, true)
       end
 
@@ -28,7 +29,8 @@ module Taski
       # @return [Reference] A reference object
       def ref(klass)
         reference = Reference.new(klass)
-        # If we're in a define context, throw for dependency tracking
+        # Use throw/catch mechanism for dependency collection during define API analysis
+        # This allows catching unresolved references without unwinding the entire call stack
         if Thread.current[TASKI_ANALYZING_DEFINE_KEY]
           reference.tap { |ref| throw :unresolved, ref }
         else
@@ -46,38 +48,15 @@ module Taski
       # @param prefix [String] Current indentation prefix
       # @param visited [Set] Set of visited classes to prevent infinite loops
       # @return [String] Formatted dependency tree
-      def tree(prefix = "", visited = Set.new)
-        return "#{prefix}#{name} (circular)\n" if visited.include?(self)
-
-        visited = visited.dup
-        visited << self
-
-        result = "#{prefix}#{name}\n"
-
-        dependencies = (@dependencies || []).uniq { |dep| extract_class(dep) }
-        dependencies.each_with_index do |dep, index|
-          dep_class = extract_class(dep)
-          is_last = index == dependencies.length - 1
-
-          connector = is_last ? "└── " : "├── "
-          child_prefix = prefix + (is_last ? "    " : "│   ")
-
-          # For the dependency itself, we want to use the connector
-          # For its children, we want to use the child_prefix
-          dep_tree = dep_class.tree(child_prefix, visited)
-          # Replace the first line (which has child_prefix) with the proper connector
-          dep_lines = dep_tree.lines
-          if dep_lines.any?
-            # Replace the first line prefix with connector
-            first_line = dep_lines[0]
-            fixed_first_line = first_line.sub(/^#{Regexp.escape(child_prefix)}/, prefix + connector)
-            result += fixed_first_line
-            # Add the rest of the lines as-is
-            result += dep_lines[1..].join if dep_lines.length > 1
-          else
-            result += "#{prefix}#{connector}#{dep_class.name}\n"
-          end
-        end
+      def tree(prefix = "", visited = Set.new, color: TreeColors.enabled?)
+        should_return_early, early_result, new_visited = handle_circular_dependency_check(visited, self, prefix)
+        return early_result if should_return_early
+
+        task_name = color ? TreeColors.task(name) : name
+        result = "#{prefix}#{task_name}\n"
+
+        dependencies = @dependencies || []
+        result += render_dependencies_tree(dependencies, prefix, new_visited, color)
 
         result
       end
@@ -85,6 +64,7 @@ module Taski
       private
 
       include Utils::DependencyUtils
+      include Utils::TreeDisplayHelper
       private :extract_class
     end
 
@@ -105,7 +85,7 @@ module Taski
     # Clean method with default empty implementation
     # Subclasses can override this method to implement cleanup logic
     def clean
-      # Default implementation does nothing
+      # Default implementation does nothing - allows optional cleanup in subclasses
     end
   end
 end

data/lib/taski/task/define_api.rb

@@ -16,7 +16,8 @@ module Taski
         @dependencies ||= []
         @definitions ||= {}
 
-        # Ensure ref method is defined first time define is called
+        # Enable forward declarations by creating ref method on first define usage
+        # This allows tasks to reference other tasks before they're defined
         create_ref_method_if_needed
 
         # Create method that tracks dependencies on first call
@@ -61,7 +62,7 @@ module Taski
           def self.#{name}
             __resolve__[__callee__] ||= false
             if __resolve__[__callee__]
-              # already resolved
+              # already resolved - prevents infinite recursion
             else
               __resolve__[__callee__] = true
               throw :unresolved, [self, __callee__]
@@ -93,7 +94,8 @@ module Taski
         # Reset resolution state
         classes.each do |task_class|
           klass = task_class[:klass]
-          # Only reset Task classes, not Reference objects
+          # Reference objects are stateless but Task classes store analysis state
+          # Selective reset prevents errors while ensuring clean state for next analysis
           if klass.respond_to?(:instance_variable_set) && !klass.is_a?(Taski::Reference)
             klass.instance_variable_set(:@__resolve__, {})
           end

data/lib/taski/task/dependency_resolver.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../dependency_analyzer"
+require_relative "../utils/dependency_resolver_helper"
 
 module Taski
   class Task
@@ -12,75 +13,13 @@ module Taski
       # @param resolved [Array] Array of resolved tasks
       # @return [self] Returns self for method chaining
       def resolve(queue, resolved)
-        @dependencies ||= []
-
-        @dependencies.each do |task|
-          task_class = extract_class(task)
-
-          # Reorder in resolved list for correct priority
-          resolved.delete(task_class) if resolved.include?(task_class)
-          queue << task_class
-        end
-
-        # Create getter methods for defined values
-        create_defined_methods
-
-        self
+        resolve_common(queue, resolved, custom_hook: -> { create_defined_methods })
       end
 
       # Resolve all dependencies in topological order with circular dependency detection
       # @return [Array<Class>] Array of tasks in dependency order
       def resolve_dependencies
-        queue = [self]
-        resolved = []
-        visited = Set.new
-        resolving = Set.new  # Track currently resolving tasks
-        path_map = {self => []}  # Track paths to each task
-
-        while queue.any?
-          task_class = queue.shift
-          next if visited.include?(task_class)
-
-          # Check for circular dependency
-          if resolving.include?(task_class)
-            # Build error message with path information
-            cycle_path = build_cycle_path(task_class, path_map)
-            raise CircularDependencyError, build_circular_dependency_message(cycle_path)
-          end
-
-          resolving << task_class
-          visited << task_class
-
-          # Store current path for dependencies
-          current_path = path_map[task_class] || []
-
-          # Let task resolve its dependencies
-          task_class.resolve(queue, resolved)
-
-          # Track paths for each dependency
-          task_class.instance_variable_get(:@dependencies)&.each do |dep|
-            dep_class = extract_class(dep)
-            path_map[dep_class] = current_path + [task_class] unless path_map.key?(dep_class)
-          end
-
-          resolving.delete(task_class)
-          resolved << task_class unless resolved.include?(task_class)
-        end
-
-        resolved
-      end
-
-      private
-
-      # Build the cycle path from path tracking information
-      def build_cycle_path(task_class, path_map)
-        path = path_map[task_class] || []
-        path + [task_class]
-      end
-
-      # Build detailed error message for circular dependencies
-      def build_circular_dependency_message(cycle_path)
-        Utils::CircularDependencyHelpers.build_error_message(cycle_path, "dependency")
+        resolve_dependencies_common
       end
 
       public
@@ -127,6 +66,7 @@ module Taski
       private
 
       include Utils::DependencyUtils
+      include Utils::DependencyResolverHelper
       private :extract_class
     end
   end

data/lib/taski/task/exports_api.rb

@@ -15,12 +15,10 @@ module Taski
         names.each do |name|
           next if respond_to?(name)
 
-          # Define class method to access exported value
           define_singleton_method(name) do
             ensure_instance_built.send(name)
           end
 
-          # Define instance method getter
           define_method(name) do
             instance_variable_get("@#{name}")
           end

data/lib/taski/task/instance_management.rb

@@ -12,14 +12,12 @@ module Taski
       # @return [Task] Returns task instance (singleton or temporary)
       def build(**args)
         if args.empty?
-          # Traditional build: singleton instance with caching
           resolve_dependencies.reverse_each do |task_class|
             task_class.ensure_instance_built
           end
           # Return the singleton instance for consistency
           instance_variable_get(:@__task_instance)
         else
-          # Parametrized build: temporary instance without caching
           build_with_args(args)
         end
       end
@@ -45,7 +43,7 @@ module Taski
         self
       end
 
-      # Refresh task state (currently just resets)
+      # Refresh task state
       # @return [self] Returns self for method chaining
       def refresh
         reset!
@@ -82,28 +80,15 @@ module Taski
       # Ensure task instance is built (public because called from build)
       # @return [Task] The built task instance
       def ensure_instance_built
-        # Use double-checked locking pattern for thread safety
+        # Double-checked locking prevents lock contention in multi-threaded builds
+        # First check avoids expensive synchronization when instance already exists
         return @__task_instance if @__task_instance
 
         build_monitor.synchronize do
-          # Check again after acquiring lock
           return @__task_instance if @__task_instance
 
-          # Prevent infinite recursion using thread-local storage
-          thread_key = build_thread_key
-          if Thread.current[thread_key]
-            # Build dependency path for better error message
-            cycle_path = build_current_dependency_path
-            raise CircularDependencyError, build_runtime_circular_dependency_message(cycle_path)
-          end
-
-          Thread.current[thread_key] = true
-          begin
-            build_dependencies
-            @__task_instance = build_instance
-          ensure
-            Thread.current[thread_key] = false
-          end
+          check_circular_dependency
+          create_and_build_instance
         end
 
         @__task_instance
@@ -111,6 +96,32 @@ module Taski
 
       private
 
+      # === Instance Management Helper Methods ===
+
+      # Check for circular dependencies and raise error if detected
+      # @raise [CircularDependencyError] If circular dependency is detected
+      def check_circular_dependency
+        thread_key = build_thread_key
+        if Thread.current[thread_key]
+          # Build dependency path for better error message
+          cycle_path = build_current_dependency_path
+          raise CircularDependencyError, build_runtime_circular_dependency_message(cycle_path)
+        end
+      end
+
+      # Create and build instance with proper thread-local state management
+      # @return [void] Sets @__task_instance
+      def create_and_build_instance
+        thread_key = build_thread_key
+        Thread.current[thread_key] = true
+        begin
+          build_dependencies
+          @__task_instance = build_instance
+        ensure
+          Thread.current[thread_key] = false
+        end
+      end
+
       # === Core Helper Methods ===
 
       # Get or create build monitor for thread safety

data/lib/taski/tree_colors.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Taski
+  # Color utilities for tree display
+  # Provides ANSI color codes for enhanced tree visualization
+  class TreeColors
+    # ANSI color codes
+    COLORS = {
+      red: "\e[31m",
+      green: "\e[32m",
+      yellow: "\e[33m",
+      blue: "\e[34m",
+      magenta: "\e[35m",
+      cyan: "\e[36m",
+      gray: "\e[90m",
+      reset: "\e[0m",
+      bold: "\e[1m"
+    }.freeze
+
+    class << self
+      # Check if colors should be enabled
+      # @return [Boolean] true if colors should be used
+      def enabled?
+        return @enabled unless @enabled.nil?
+        @enabled = tty? && !no_color?
+      end
+
+      # Enable or disable colors
+      # @param value [Boolean] whether to enable colors
+      attr_writer :enabled
+
+      # Colorize text for Section names (blue)
+      # @param text [String] text to colorize
+      # @return [String] colorized text
+      def section(text)
+        colorize(text, :blue, bold: true)
+      end
+
+      # Colorize text for Task names (green)
+      # @param text [String] text to colorize
+      # @return [String] colorized text
+      def task(text)
+        colorize(text, :green)
+      end
+
+      # Colorize text for implementation candidates (yellow)
+      # @param text [String] text to colorize
+      # @return [String] colorized text
+      def implementations(text)
+        colorize(text, :yellow)
+      end
+
+      # Colorize tree connectors (gray)
+      # @param text [String] text to colorize
+      # @return [String] colorized text
+      def connector(text)
+        colorize(text, :gray)
+      end
+
+      private
+
+      # Apply color to text
+      # @param text [String] text to colorize
+      # @param color [Symbol] color name
+      # @param bold [Boolean] whether to make text bold
+      # @return [String] colorized text
+      def colorize(text, color, bold: false)
+        return text unless enabled?
+
+        result = ""
+        result += COLORS[:bold] if bold
+        result += COLORS[color]
+        result += text
+        result += COLORS[:reset]
+        result
+      end
+
+      # Check if output is a TTY
+      # @return [Boolean] true if stdout is a TTY
+      def tty?
+        $stdout.tty?
+      end
+
+      # Check if NO_COLOR environment variable is set
+      # @return [Boolean] true if colors should be disabled
+      def no_color?
+        ENV.key?("NO_COLOR")
+      end
+    end
+  end
+end

data/lib/taski/utils/dependency_resolver_helper.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Taski
+  module Utils
+    # Helper module for dependency resolution functionality
+    # Provides common logic for resolving dependencies and detecting circular dependencies
+    module DependencyResolverHelper
+      private
+
+      # Resolve all dependencies in topological order with circular dependency detection
+      # @return [Array<Class>] Array of tasks in dependency order
+      def resolve_dependencies_common
+        queue = [self]
+        resolved = []
+        visited = Set.new
+        resolving = Set.new
+        path_map = {self => []}
+
+        while queue.any?
+          task_class = queue.shift
+          next if visited.include?(task_class)
+
+          if resolving.include?(task_class)
+            cycle_path = build_cycle_path(task_class, path_map)
+            raise CircularDependencyError, build_circular_dependency_message(cycle_path)
+          end
+
+          resolving << task_class
+          visited << task_class
+
+          current_path = path_map[task_class] || []
+          task_class.resolve(queue, resolved)
+
+          task_class.instance_variable_get(:@dependencies)&.each do |dep|
+            dep_class = extract_class(dep)
+            path_map[dep_class] = current_path + [task_class] unless path_map.key?(dep_class)
+          end
+
+          resolving.delete(task_class)
+          resolved << task_class unless resolved.include?(task_class)
+        end
+
+        resolved
+      end
+
+      # Resolve method for dependency graph (called by resolve_dependencies)
+      # @param queue [Array] Queue of tasks to process
+      # @param resolved [Array] Array of resolved tasks
+      # @param options [Hash] Optional parameters for customization
+      # @return [self] Returns self for method chaining
+      def resolve_common(queue, resolved, options = {})
+        @dependencies ||= []
+
+        @dependencies.each do |task|
+          task_class = extract_class(task)
+
+          # Reorder in resolved list for correct priority
+          resolved.delete(task_class) if resolved.include?(task_class)
+          queue << task_class
+        end
+
+        # Call custom hook if provided
+        options[:custom_hook]&.call
+
+        self
+      end
+
+      # Build the cycle path from path tracking information
+      # @param task_class [Class] Current task class
+      # @param path_map [Hash] Map of paths to each task
+      # @return [Array] Cycle path array
+      def build_cycle_path(task_class, path_map)
+        path = path_map[task_class] || []
+        path + [task_class]
+      end
+
+      # Build detailed error message for circular dependencies
+      # @param cycle_path [Array] Array representing the circular dependency path
+      # @return [String] Formatted error message
+      def build_circular_dependency_message(cycle_path)
+        Utils::CircularDependencyHelpers.build_error_message(cycle_path, "dependency")
+      end
+    end
+  end
+end

data/lib/taski/utils/tree_display_helper.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Taski
+  module Utils
+    # Helper module for tree display functionality
+    # Provides common logic for displaying dependency trees
+    module TreeDisplayHelper
+      private
+
+      # Render dependencies as tree structure
+      # @param dependencies [Array] Array of dependency objects
+      # @param prefix [String] Current indentation prefix
+      # @param visited [Set] Set of visited classes
+      # @param color [Boolean] Whether to use color output
+      # @return [String] Formatted dependency tree string
+      def render_dependencies_tree(dependencies, prefix, visited, color)
+        result = ""
+
+        dependencies = dependencies.uniq { |dep| extract_class(dep) }
+        dependencies.each_with_index do |dep, index|
+          dep_class = extract_class(dep)
+          is_last = index == dependencies.length - 1
+
+          connector_text = is_last ? "└── " : "├── "
+          connector = color ? TreeColors.connector(connector_text) : connector_text
+          child_prefix_text = is_last ? "    " : "│   "
+          child_prefix = prefix + (color ? TreeColors.connector(child_prefix_text) : child_prefix_text)
+
+          dep_tree = if dep_class.respond_to?(:tree)
+            dep_class.tree(child_prefix, visited, color: color)
+          else
+            "#{child_prefix}#{dep_class.name}\n"
+          end
+
+          dep_lines = dep_tree.lines
+          if dep_lines.any?
+            # Replace the first line prefix with connector
+            first_line = dep_lines[0]
+            fixed_first_line = first_line.sub(/^#{Regexp.escape(child_prefix)}/, prefix + connector)
+            result += fixed_first_line
+            # Add the rest of the lines as-is
+            result += dep_lines[1..].join if dep_lines.length > 1
+          else
+            dep_name = color ? TreeColors.task(dep_class.name) : dep_class.name
+            result += "#{prefix}#{connector}#{dep_name}\n"
+          end
+        end
+
+        result
+      end
+
+      # Check for circular dependencies and handle visited set
+      # @param visited [Set] Set of visited classes
+      # @param current_class [Class] Current class being processed
+      # @param prefix [String] Current indentation prefix
+      # @return [Array] Returns [should_return_early, result_string, new_visited_set]
+      def handle_circular_dependency_check(visited, current_class, prefix)
+        if visited.include?(current_class)
+          return [true, "#{prefix}#{current_class.name} (circular)\n", visited]
+        end
+
+        new_visited = visited.dup
+        new_visited << current_class
+        [false, nil, new_visited]
+      end
+    end
+  end
+end

data/lib/taski/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Taski
-  VERSION = "0.2.3"
+  VERSION = "0.3.1"
 end

data/lib/taski.rb

@@ -10,6 +10,7 @@ require_relative "taski/progress_display"
 require_relative "taski/reference"
 require_relative "taski/dependency_analyzer"
 require_relative "taski/utils"
+require_relative "taski/tree_colors"
 
 # Load Task class components
 require_relative "taski/task/base"
@@ -18,24 +19,27 @@ require_relative "taski/task/define_api"
 require_relative "taski/task/instance_management"
 require_relative "taski/task/dependency_resolver"
 
+# Load Section class
+require_relative "taski/section"
+
 module Taski
   # Main module for the Taski task framework
   #
   # Taski provides a framework for defining and managing task dependencies
-  # with two complementary APIs:
+  # with three complementary APIs:
   # 1. Exports API - Export instance variables as class methods (static dependencies)
   # 2. Define API - Define lazy-evaluated values with dynamic dependency resolution
+  # 3. Section API - Abstraction layers with runtime implementation selection
   #
-  # Use Define API when:
-  # - Dependencies change based on runtime conditions
-  # - Environment-specific configurations
-  # - Feature flags determine which classes to use
-  # - Complex conditional logic determines dependencies
+  # API Selection Guide:
+  # - Use Exports API for simple static dependencies
+  # - Use Define API for conditional dependencies analyzed at class definition time
+  # - Use Section API for environment-specific implementations with static analysis
   #
   # Features:
   # - Automatic dependency resolution (static and dynamic)
   # - Static analysis of method dependencies
-  # - Runtime dependency resolution for conditional logic
+  # - Runtime implementation selection with Section API
   # - Thread-safe task building
   # - Circular dependency detection
   # - Memory leak prevention

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: taski
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.3.1
 platform: ruby
 authors:
 - ahogappa
@@ -43,19 +43,36 @@ files:
 - examples/advanced_patterns.rb
 - examples/progress_demo.rb
 - examples/quick_start.rb
+- examples/section_configuration.rb
 - examples/tree_demo.rb
 - lib/taski.rb
 - lib/taski/dependency_analyzer.rb
 - lib/taski/exceptions.rb
 - lib/taski/logger.rb
+- lib/taski/logging/formatter_factory.rb
+- lib/taski/logging/formatter_interface.rb
+- lib/taski/logging/json_formatter.rb
+- lib/taski/logging/simple_formatter.rb
+- lib/taski/logging/structured_formatter.rb
+- lib/taski/progress/display_colors.rb
+- lib/taski/progress/display_manager.rb
+- lib/taski/progress/output_capture.rb
+- lib/taski/progress/spinner_animation.rb
+- lib/taski/progress/task_formatter.rb
+- lib/taski/progress/task_status.rb
+- lib/taski/progress/terminal_controller.rb
 - lib/taski/progress_display.rb
 - lib/taski/reference.rb
+- lib/taski/section.rb
 - lib/taski/task/base.rb
 - lib/taski/task/define_api.rb
 - lib/taski/task/dependency_resolver.rb
 - lib/taski/task/exports_api.rb
 - lib/taski/task/instance_management.rb
+- lib/taski/tree_colors.rb
 - lib/taski/utils.rb
+- lib/taski/utils/dependency_resolver_helper.rb
+- lib/taski/utils/tree_display_helper.rb
 - lib/taski/version.rb
 - sig/taski.rbs
 homepage: https://github.com/ahogappa/taski