taski 0.3.1 → 0.4.1

data/lib/taski/progress_display.rb

@@ -1,57 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "progress/terminal_controller"
-require_relative "progress/spinner_animation"
-require_relative "progress/output_capture"
-require_relative "progress/display_manager"
-
-module Taski
-  # Backward compatibility aliases
-  TerminalController = Progress::TerminalController
-  SpinnerAnimation = Progress::SpinnerAnimation
-  OutputCapture = Progress::OutputCapture
-  TaskStatus = Progress::TaskStatus
-
-  # Main progress display controller - refactored for better separation of concerns
-  class ProgressDisplay
-    def initialize(output: $stdout, enable: true, include_captured_output: nil)
-      @output = output
-      @terminal = Progress::TerminalController.new(output)
-      @spinner = Progress::SpinnerAnimation.new
-      @output_capture = Progress::OutputCapture.new(output)
-
-      include_captured_output = include_captured_output.nil? ? (output != $stdout) : include_captured_output
-      @display_manager = Progress::DisplayManager.new(@terminal, @spinner, @output_capture, include_captured_output: include_captured_output)
-
-      @enabled = ENV["TASKI_PROGRESS_DISABLE"] != "1" && enable
-    end
-
-    def start_task(task_name, dependencies: [])
-      return unless @enabled
-
-      @display_manager.start_task_display(task_name)
-    end
-
-    def complete_task(task_name, duration:)
-      return unless @enabled
-
-      @display_manager.complete_task_display(task_name, duration: duration)
-    end
-
-    def fail_task(task_name, error:, duration:)
-      return unless @enabled
-
-      @display_manager.fail_task_display(task_name, error: error, duration: duration)
-    end
-
-    def clear
-      return unless @enabled
-
-      @display_manager.clear_all_displays
-    end
-
-    def enabled?
-      @enabled
-    end
-  end
-end

data/lib/taski/reference.rb

@@ -1,40 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "exceptions"
-
-module Taski
-  # Reference class for task references
-  #
-  # Used to create lazy references to task classes by name,
-  # which is useful for dependency tracking and metaprogramming.
-  class Reference
-    # @param klass [String] The name of the class to reference
-    def initialize(klass)
-      @klass = klass
-    end
-
-    # Dereference to get the actual class object
-    # @return [Class] The referenced class
-    # @raise [TaskAnalysisError] If the constant cannot be resolved
-    def deref
-      Object.const_get(@klass)
-    rescue NameError => e
-      raise TaskAnalysisError, "Cannot resolve constant '#{@klass}': #{e.message}"
-    end
-
-    # Compare reference with another object
-    # @param other [Object] Object to compare with
-    # @return [Boolean] True if the referenced class equals the other object
-    def ==(other)
-      Object.const_get(@klass) == other
-    rescue NameError
-      false
-    end
-
-    # String representation of the reference
-    # @return [String] Reference representation
-    def inspect
-      "&#{@klass}"
-    end
-  end
-end

data/lib/taski/task/base.rb

@@ -1,91 +0,0 @@
-# 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
-  # This module contains the core constants and basic structure
-  class Task
-    # Constants for thread-local keys and method tracking
-    THREAD_KEY_SUFFIX = "_building"
-    TASKI_ANALYZING_DEFINE_KEY = :taski_analyzing_define
-    ANALYZED_METHODS = [:build, :clean].freeze
-
-    class << self
-      # === Hook Methods ===
-
-      # Hook called when build/clean methods are defined
-      # This triggers static analysis of dependencies
-      def method_added(method_name)
-        super
-        return unless ANALYZED_METHODS.include?(method_name)
-        # Avoid calling before dependency_resolver module is loaded
-        analyze_dependencies_at_definition if respond_to?(:analyze_dependencies_at_definition, true)
-      end
-
-      # Create a reference to a task class (can be used anywhere)
-      # @param klass [String] The class name to reference
-      # @return [Reference] A reference object
-      def ref(klass)
-        reference = Reference.new(klass)
-        # 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
-          reference
-        end
-      end
-
-      # Get or create resolution state for define API
-      # @return [Hash] Resolution state hash
-      def __resolve__
-        @__resolve__ ||= {}
-      end
-
-      # Display dependency tree for this task
-      # @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, 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
-
-      private
-
-      include Utils::DependencyUtils
-      include Utils::TreeDisplayHelper
-      private :extract_class
-    end
-
-    # === Instance Methods ===
-
-    # Build method that must be implemented by subclasses
-    # @raise [NotImplementedError] If not implemented by subclass
-    def build
-      raise NotImplementedError, "You must implement the build method in your task class"
-    end
-
-    # Access build arguments passed to parametrized builds
-    # @return [Hash] Build arguments or empty hash if none provided
-    def build_args
-      @build_args || {}
-    end
-
-    # Clean method with default empty implementation
-    # Subclasses can override this method to implement cleanup logic
-    def clean
-      # Default implementation does nothing - allows optional cleanup in subclasses
-    end
-  end
-end

data/lib/taski/task/define_api.rb

@@ -1,156 +0,0 @@
-# frozen_string_literal: true
-
-module Taski
-  class Task
-    class << self
-      # === Define API ===
-      # Define lazy-evaluated values with dynamic dependency resolution
-
-      # Define a lazy-evaluated value using a block
-      # Use this API when dependencies change based on runtime conditions,
-      # environment-specific configurations, feature flags, or complex conditional logic
-      # @param name [Symbol] Name of the value
-      # @param block [Proc] Block that computes the value and determines dependencies at runtime
-      # @param options [Hash] Additional options
-      def define(name, block, **options)
-        @dependencies ||= []
-        @definitions ||= {}
-
-        # 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
-        create_tracking_method(name)
-
-        # Analyze dependencies by executing the block
-        dependencies = analyze_define_dependencies(block)
-
-        @dependencies += dependencies
-        @definitions[name] = {block:, options:, classes: dependencies}
-      end
-
-      private
-
-      # === Define API Implementation ===
-
-      # Create ref method if needed to avoid redefinition warnings
-      def create_ref_method_if_needed
-        return if method_defined_for_define?(:ref)
-
-        define_singleton_method(:ref) do |klass_name|
-          # During dependency analysis, track as dependency but defer resolution
-          if Thread.current[TASKI_ANALYZING_DEFINE_KEY]
-            # Create Reference object for deferred resolution
-            reference = Taski::Reference.new(klass_name)
-
-            # Track as dependency by throwing unresolved
-            throw :unresolved, [reference, :deref]
-          else
-            # At runtime, resolve to actual class
-            Object.const_get(klass_name)
-          end
-        end
-        mark_method_as_defined(:ref)
-      end
-
-      # Create method that tracks dependencies for define API
-      # @param name [Symbol] Method name to create
-      def create_tracking_method(name)
-        # Only create tracking method during dependency analysis
-        class_eval(<<-RUBY, __FILE__, __LINE__ + 1)
-          def self.#{name}
-            __resolve__[__callee__] ||= false
-            if __resolve__[__callee__]
-              # already resolved - prevents infinite recursion
-            else
-              __resolve__[__callee__] = true
-              throw :unresolved, [self, __callee__]
-            end
-          end
-        RUBY
-      end
-
-      # Analyze dependencies in define block
-      # @param block [Proc] Block to analyze
-      # @return [Array<Hash>] Array of dependency information
-      def analyze_define_dependencies(block)
-        classes = []
-
-        # Set flag to indicate we're analyzing define dependencies
-        Thread.current[TASKI_ANALYZING_DEFINE_KEY] = true
-
-        loop do
-          klass, task = catch(:unresolved) do
-            block.call
-            nil
-          end
-
-          break if klass.nil?
-
-          classes << {klass:, task:}
-        end
-
-        # Reset resolution state
-        classes.each do |task_class|
-          klass = task_class[:klass]
-          # 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
-        end
-
-        classes
-      ensure
-        Thread.current[TASKI_ANALYZING_DEFINE_KEY] = false
-      end
-
-      # Create methods for values defined with define API
-      def create_defined_methods
-        @definitions ||= {}
-        @definitions.each do |name, definition|
-          create_defined_method(name, definition) unless method_defined_for_define?(name)
-        end
-      end
-
-      # Create a single defined method (both class and instance)
-      # @param name [Symbol] Method name
-      # @param definition [Hash] Method definition information
-      def create_defined_method(name, definition)
-        # Remove tracking method first to avoid redefinition warnings
-        singleton_class.undef_method(name) if singleton_class.method_defined?(name)
-
-        # Class method with lazy evaluation
-        define_singleton_method(name) do
-          @__defined_values ||= {}
-          @__defined_values[name] ||= definition[:block].call
-        end
-
-        # Instance method that delegates to class method
-        define_method(name) do
-          @__defined_values ||= {}
-          @__defined_values[name] ||= self.class.send(name)
-        end
-
-        # Mark as defined for this resolution
-        mark_method_as_defined(name)
-      end
-
-      # Mark method as defined for this resolution cycle
-      # @param method_name [Symbol] Method name to mark
-      def mark_method_as_defined(method_name)
-        @__defined_for_resolve ||= Set.new
-        @__defined_for_resolve << method_name
-      end
-
-      # Check if method was already defined for define API
-      # @param method_name [Symbol] Method name to check
-      # @return [Boolean] True if already defined
-      def method_defined_for_define?(method_name)
-        @__defined_for_resolve ||= Set.new
-        @__defined_for_resolve.include?(method_name)
-      end
-    end
-  end
-end

data/lib/taski/task/dependency_resolver.rb

@@ -1,73 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../dependency_analyzer"
-require_relative "../utils/dependency_resolver_helper"
-
-module Taski
-  class Task
-    class << self
-      # === Dependency Resolution ===
-
-      # Resolve method for dependency graph (called by resolve_dependencies)
-      # @param queue [Array] Queue of tasks to process
-      # @param resolved [Array] Array of resolved tasks
-      # @return [self] Returns self for method chaining
-      def resolve(queue, resolved)
-        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
-        resolve_dependencies_common
-      end
-
-      public
-
-      # === Static Analysis ===
-
-      # Analyze dependencies when methods are defined
-      def analyze_dependencies_at_definition
-        dependencies = gather_static_dependencies
-        add_unique_dependencies(dependencies)
-      end
-
-      # Gather dependencies from build and clean methods
-      # @return [Array<Class>] Array of dependency classes
-      def gather_static_dependencies
-        build_deps = DependencyAnalyzer.analyze_method(self, :build)
-        clean_deps = DependencyAnalyzer.analyze_method(self, :clean)
-        (build_deps + clean_deps).uniq
-      end
-
-      # Add dependencies that don't already exist
-      # @param dep_classes [Array<Class>] Array of dependency classes
-      def add_unique_dependencies(dep_classes)
-        dep_classes.each do |dep_class|
-          next if dep_class == self || dependency_exists?(dep_class)
-          add_dependency(dep_class)
-        end
-      end
-
-      # Add a single dependency
-      # @param dep_class [Class] Dependency class to add
-      def add_dependency(dep_class)
-        @dependencies ||= []
-        @dependencies << {klass: dep_class}
-      end
-
-      # Check if dependency already exists
-      # @param dep_class [Class] Dependency class to check
-      # @return [Boolean] True if dependency exists
-      def dependency_exists?(dep_class)
-        (@dependencies || []).any? { |d| d[:klass] == dep_class }
-      end
-
-      private
-
-      include Utils::DependencyUtils
-      include Utils::DependencyResolverHelper
-      private :extract_class
-    end
-  end
-end

data/lib/taski/task/exports_api.rb

@@ -1,29 +0,0 @@
-# frozen_string_literal: true
-
-module Taski
-  class Task
-    class << self
-      # === Exports API ===
-      # Export instance variables as class methods for static dependencies
-
-      # Export instance variables as both class and instance methods
-      # @param names [Array<Symbol>] Names of instance variables to export
-      def exports(*names)
-        @exports ||= []
-        @exports += names
-
-        names.each do |name|
-          next if respond_to?(name)
-
-          define_singleton_method(name) do
-            ensure_instance_built.send(name)
-          end
-
-          define_method(name) do
-            instance_variable_get("@#{name}")
-          end
-        end
-      end
-    end
-  end
-end

data/lib/taski/task/instance_management.rb

@@ -1,201 +0,0 @@
-# frozen_string_literal: true
-
-require "monitor"
-
-module Taski
-  class Task
-    class << self
-      # === Lifecycle Management ===
-
-      # Build this task and all its dependencies
-      # @param args [Hash] Optional arguments for parametrized builds
-      # @return [Task] Returns task instance (singleton or temporary)
-      def build(**args)
-        if args.empty?
-          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
-          build_with_args(args)
-        end
-      end
-
-      # Clean this task and all its dependencies in reverse order
-      def clean
-        resolve_dependencies.each do |task_class|
-          # Get existing instance or create new one for cleaning
-          instance = task_class.instance_variable_get(:@__task_instance) || task_class.new
-          instance.clean
-        end
-      end
-
-      # Reset task instance and cached data to prevent memory leaks
-      # @return [self] Returns self for method chaining
-      def reset!
-        build_monitor.synchronize do
-          @__task_instance = nil
-          @__defined_values = nil
-          @__defined_for_resolve = nil
-          clear_thread_local_state
-        end
-        self
-      end
-
-      # Refresh task state
-      # @return [self] Returns self for method chaining
-      def refresh
-        reset!
-      end
-
-      # === Parametrized Build Support ===
-
-      # Build temporary instance with arguments
-      # @param args [Hash] Build arguments
-      # @return [Task] Temporary task instance
-      def build_with_args(args)
-        # Resolve dependencies first (same as normal build)
-        resolve_dependencies.reverse_each do |task_class|
-          task_class.ensure_instance_built
-        end
-
-        # Create temporary instance with arguments
-        temp_instance = new
-        temp_instance.instance_variable_set(:@build_args, args)
-
-        # Build with logging using common utility
-        Utils::TaskBuildHelpers.with_build_logging(name.to_s,
-          dependencies: @dependencies || [],
-          args: args) do
-          temp_instance.build
-          temp_instance
-        end
-      end
-
-      private :build_with_args
-
-      # === Instance Management ===
-
-      # Ensure task instance is built (public because called from build)
-      # @return [Task] The built task instance
-      def ensure_instance_built
-        # 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
-          return @__task_instance if @__task_instance
-
-          check_circular_dependency
-          create_and_build_instance
-        end
-
-        @__task_instance
-      end
-
-      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
-      # @return [Monitor] Thread-safe monitor object
-      def build_monitor
-        @__build_monitor ||= Monitor.new
-      end
-
-      # Generate thread key for recursion detection
-      # @return [String] Thread key for this task
-      def build_thread_key
-        "#{name}#{THREAD_KEY_SUFFIX}"
-      end
-
-      # Build and configure task instance
-      # @return [Task] Built task instance
-      def build_instance
-        instance = new
-        Utils::TaskBuildHelpers.with_build_logging(name.to_s,
-          dependencies: @dependencies || []) do
-          instance.build
-          instance
-        end
-      end
-
-      # Clear thread-local state for this task
-      def clear_thread_local_state
-        Thread.current.keys.each do |key|
-          Thread.current[key] = nil if key.to_s.include?(build_thread_key)
-        end
-      end
-
-      # === Dependency Management ===
-
-      # Build all dependencies of this task
-      def build_dependencies
-        resolve_dependencies
-
-        (@dependencies || []).each do |dep|
-          dep_class = extract_class(dep)
-          next if dep_class == self
-
-          dep_class.ensure_instance_built if dep_class.respond_to?(:ensure_instance_built)
-        end
-      end
-
-      private
-
-      # Build current dependency path from thread-local storage
-      # @return [Array<Class>] Array of classes in the current build path
-      def build_current_dependency_path
-        path = []
-        Thread.current.keys.each do |key|
-          if key.to_s.end_with?(THREAD_KEY_SUFFIX) && Thread.current[key]
-            class_name = key.to_s.sub(THREAD_KEY_SUFFIX, "")
-            begin
-              path << Object.const_get(class_name)
-            rescue NameError
-              # Skip if class not found
-            end
-          end
-        end
-        path << self
-      end
-
-      # Build runtime circular dependency error message
-      # @param cycle_path [Array<Class>] The circular dependency path
-      # @return [String] Formatted error message
-      def build_runtime_circular_dependency_message(cycle_path)
-        Utils::CircularDependencyHelpers.build_error_message(cycle_path, "runtime")
-      end
-
-      include Utils::DependencyUtils
-      private :extract_class
-    end
-  end
-end