taski 0.5.0 → 0.7.1

data/lib/taski/test_helper.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require_relative "test_helper/errors"
+require_relative "test_helper/mock_wrapper"
+require_relative "test_helper/mock_registry"
+
+module Taski
+  # Test helper module for mocking Taski task dependencies in unit tests.
+  # Include this module in your test class to access mocking functionality.
+  #
+  # @example Minitest usage
+  #   class BuildReportTest < Minitest::Test
+  #     include Taski::TestHelper
+  #
+  #     def test_builds_report
+  #       mock_task(FetchData, users: [1, 2, 3])
+  #       assert_equal 3, BuildReport.user_count
+  #     end
+  #   end
+  module TestHelper
+    # Module prepended to Task's singleton class to intercept define_class_accessor.
+    # @api private
+    module TaskExtension
+      def define_class_accessor(method)
+        singleton_class.undef_method(method) if singleton_class.method_defined?(method)
+
+        define_singleton_method(method) do
+          # Check for mock first
+          mock = MockRegistry.mock_for(self)
+          return mock.get_exported_value(method) if mock
+
+          # No mock - call original implementation via registry lookup
+          registry = Taski.current_registry
+          if registry
+            wrapper = registry.get_or_create(self) do
+              task_instance = allocate
+              task_instance.__send__(:initialize)
+              Execution::TaskWrapper.new(
+                task_instance,
+                registry: registry,
+                execution_context: Execution::ExecutionContext.current
+              )
+            end
+            wrapper.get_exported_value(method)
+          else
+            Taski.with_args(options: {}, root_task: self) do
+              validate_no_circular_dependencies!
+              fresh_wrapper.get_exported_value(method)
+            end
+          end
+        end
+      end
+    end
+
+    # Module prepended to Scheduler to skip dependencies of mocked tasks.
+    # @api private
+    module SchedulerExtension
+      def build_dependency_graph(root_task_class)
+        queue = [root_task_class]
+
+        while (task_class = queue.shift)
+          next if @task_states.key?(task_class)
+
+          # Mocked tasks have no dependencies (isolates indirect dependencies)
+          mock = MockRegistry.mock_for(task_class)
+          deps = mock ? Set.new : task_class.cached_dependencies
+          @dependencies[task_class] = deps.dup
+          @task_states[task_class] = Taski::Execution::Scheduler::STATE_PENDING
+
+          deps.each { |dep| queue << dep }
+        end
+      end
+    end
+
+    # Module prepended to Executor to skip execution of mocked tasks.
+    # @api private
+    module ExecutorExtension
+      def execute_task(task_class, wrapper)
+        return if @registry.abort_requested?
+
+        # Skip execution if task is mocked
+        if MockRegistry.mock_for(task_class)
+          wrapper.mark_completed(nil)
+          @completion_queue.push({task_class: task_class, wrapper: wrapper})
+          return
+        end
+
+        super
+      end
+    end
+
+    class << self
+      # Checks if any mocks are currently registered.
+      # @return [Boolean] true if mocks exist
+      def mocks_active?
+        MockRegistry.mocks_active?
+      end
+
+      # Retrieves the mock wrapper for a task class.
+      # @param task_class [Class] The task class to look up
+      # @return [MockWrapper, nil] The mock wrapper or nil if not mocked
+      def mock_for(task_class)
+        MockRegistry.mock_for(task_class)
+      end
+
+      # Clears all registered mocks.
+      # Called automatically by test framework integrations.
+      def reset_mocks!
+        MockRegistry.reset!
+      end
+    end
+
+    # Registers a mock for a task class with specified return values.
+    # @param task_class [Class] A Taski::Task or Taski::Section subclass
+    # @param values [Hash{Symbol => Object}] Method names mapped to return values
+    # @return [MockWrapper] The created mock wrapper
+    # @raise [InvalidTaskError] If task_class is not a Taski::Task/Section subclass
+    # @raise [InvalidMethodError] If any method name is not an exported method
+    #
+    # @example
+    #   mock_task(FetchData, result: { users: [1, 2, 3] })
+    #   mock_task(Config, timeout: 30, retries: 3)
+    def mock_task(task_class, **values)
+      validate_task_class!(task_class)
+      validate_exported_methods!(task_class, values.keys)
+
+      mock_wrapper = MockWrapper.new(task_class, values)
+      MockRegistry.register(task_class, mock_wrapper)
+      mock_wrapper
+    end
+
+    # Asserts that a mocked task's method was accessed during the test.
+    # @param task_class [Class] The mocked task class
+    # @param method_name [Symbol] The exported method name
+    # @return [true] If assertion passes
+    # @raise [ArgumentError] If task_class was not mocked
+    # @raise [Minitest::Assertion, RSpec::Expectations::ExpectationNotMetError]
+    #   If method was not accessed
+    def assert_task_accessed(task_class, method_name)
+      mock = fetch_mock!(task_class)
+
+      unless mock.accessed?(method_name)
+        raise assertion_error("Expected #{task_class}.#{method_name} to be accessed, but it was not")
+      end
+
+      true
+    end
+
+    # Asserts that a mocked task's method was NOT accessed during the test.
+    # @param task_class [Class] The mocked task class
+    # @param method_name [Symbol] The exported method name
+    # @return [true] If assertion passes
+    # @raise [ArgumentError] If task_class was not mocked
+    # @raise [Minitest::Assertion, RSpec::Expectations::ExpectationNotMetError]
+    #   If method was accessed
+    def refute_task_accessed(task_class, method_name)
+      mock = fetch_mock!(task_class)
+
+      if mock.accessed?(method_name)
+        count = mock.access_count(method_name)
+        raise assertion_error(
+          "Expected #{task_class}.#{method_name} not to be accessed, but it was accessed #{count} time(s)"
+        )
+      end
+
+      true
+    end
+
+    private
+
+    def fetch_mock!(task_class)
+      mock = MockRegistry.mock_for(task_class)
+      return mock if mock
+
+      raise ArgumentError, "Task #{task_class} was not mocked. Call mock_task first."
+    end
+
+    def validate_task_class!(task_class)
+      valid = task_class.is_a?(Class) &&
+        (task_class < Taski::Task || task_class == Taski::Task)
+      return if valid
+
+      raise InvalidTaskError,
+        "Cannot mock #{task_class}: not a Taski::Task or Taski::Section subclass"
+    end
+
+    def validate_exported_methods!(task_class, method_names)
+      exported = task_class.exported_methods
+      method_names.each do |method_name|
+        unless exported.include?(method_name)
+          raise InvalidMethodError,
+            "Cannot mock :#{method_name} on #{task_class}: not an exported method. Exported: #{exported.inspect}"
+        end
+      end
+    end
+
+    def assertion_error(message)
+      # Use the appropriate assertion error class based on the test framework
+      # Use fully qualified names to avoid namespace conflicts
+      if defined?(::Minitest::Assertion)
+        ::Minitest::Assertion.new(message)
+      elsif defined?(::RSpec::Expectations::ExpectationNotMetError)
+        ::RSpec::Expectations::ExpectationNotMetError.new(message)
+      else
+        RuntimeError.new(message)
+      end
+    end
+  end
+end
+
+# Prepend extensions when test helper is loaded
+Taski::Task.singleton_class.prepend(Taski::TestHelper::TaskExtension)
+Taski::Execution::Scheduler.prepend(Taski::TestHelper::SchedulerExtension)
+Taski::Execution::Executor.prepend(Taski::TestHelper::ExecutorExtension)

data/lib/taski/version.rb

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

data/lib/taski.rb

@@ -5,12 +5,15 @@ require_relative "taski/static_analysis/analyzer"
 require_relative "taski/static_analysis/visitor"
 require_relative "taski/static_analysis/dependency_graph"
 require_relative "taski/execution/registry"
+require_relative "taski/execution/execution_context"
 require_relative "taski/execution/task_wrapper"
+require_relative "taski/execution/scheduler"
+require_relative "taski/execution/worker_pool"
 require_relative "taski/execution/executor"
 require_relative "taski/execution/tree_progress_display"
-require_relative "taski/context"
-require_relative "taski/task"
-require_relative "taski/section"
+require_relative "taski/execution/simple_progress_display"
+require_relative "taski/execution/plain_progress_display"
+require_relative "taski/args"
 
 module Taski
   class TaskAbortException < StandardError
@@ -28,52 +31,237 @@ module Taski
     end
   end
 
-  @context_monitor = Monitor.new
+  # Represents a single task failure with its context
+  class TaskFailure
+    attr_reader :task_class, :error, :output_lines
 
-  # Get the current execution context
-  # @return [Context, nil] The current context or nil if no task is running
-  def self.context
-    @context_monitor.synchronize { @context }
+    # @param task_class [Class] The task class that failed
+    # @param error [Exception] The exception that was raised
+    # @param output_lines [Array<String>] Recent output lines from the failed task
+    def initialize(task_class:, error:, output_lines: [])
+      @task_class = task_class
+      @error = error
+      @output_lines = output_lines
+    end
   end
 
-  # Start a new execution context (internal use only)
-  # @api private
-  def self.start_context(options:, root_task:)
-    @context_monitor.synchronize do
-      return if @context
-      @context = Context.new(options: options, root_task: root_task)
+  # Mixin for exception classes to enable transparent rescue matching with AggregateError.
+  # When extended by an exception class, `rescue ThatError` will also match
+  # an AggregateError that contains ThatError.
+  #
+  # @note TaskError and all TaskClass::Error classes already extend this module.
+  #
+  # @example
+  #   begin
+  #     MyTask.value  # raises AggregateError containing MyTask::Error
+  #   rescue MyTask::Error => e
+  #     puts "MyTask failed: #{e.message}"
+  #   end
+  module AggregateAware
+    def ===(other)
+      return super unless other.is_a?(Taski::AggregateError)
+
+      other.includes?(self)
+    end
+  end
+
+  # Base class for task-specific error wrappers.
+  # Each Task subclass automatically gets a ::Error class that inherits from this.
+  # This allows rescuing errors by task class: rescue MyTask::Error => e
+  #
+  # @example Rescuing task-specific errors
+  #   begin
+  #     MyTask.value
+  #   rescue MyTask::Error => e
+  #     puts "MyTask failed: #{e.message}"
+  #   end
+  class TaskError < StandardError
+    extend AggregateAware
+
+    # @return [Exception] The original error that occurred in the task
+    attr_reader :cause
+
+    # @return [Class] The task class where the error occurred
+    attr_reader :task_class
+
+    # @param cause [Exception] The original error
+    # @param task_class [Class] The task class where the error occurred
+    def initialize(cause, task_class:)
+      @cause = cause
+      @task_class = task_class
+      super(cause.message)
+      set_backtrace(cause.backtrace)
+    end
+  end
+
+  # Raised when multiple tasks fail during parallel execution
+  class AggregateError < StandardError
+    attr_reader :errors
+
+    # @param errors [Array<TaskFailure>] List of task failures
+    def initialize(errors)
+      @errors = errors
+      super(build_message)
+    end
+
+    # Returns the first error for compatibility with exception chaining
+    # @return [Exception, nil] The first error or nil if no errors
+    def cause
+      errors.first&.error
+    end
+
+    # Check if this aggregate contains an error of the given type
+    # @param exception_class [Class] The exception class to check for
+    # @return [Boolean] true if any contained error is of the given type
+    def includes?(exception_class)
+      errors.any? { |f| f.error.is_a?(exception_class) }
+    end
+
+    private
+
+    def build_message
+      task_word = (errors.size == 1) ? "task" : "tasks"
+      parts = ["#{errors.size} #{task_word} failed:"]
+
+      errors.each do |f|
+        parts << "  - #{f.task_class.name}: #{f.error.message}"
+
+        # Include captured output if available
+        if f.output_lines && !f.output_lines.empty?
+          parts << "    Output:"
+          f.output_lines.each { |line| parts << "      #{line}" }
+        end
+      end
+
+      parts.join("\n")
     end
   end
 
-  # Reset the execution context (internal use only)
+  @args_monitor = Monitor.new
+
+  # Get the current runtime arguments
+  # @return [Args, nil] The current args or nil if no task is running
+  def self.args
+    @args_monitor.synchronize { @args }
+  end
+
+  # Start new runtime arguments (internal use only)
   # @api private
-  def self.reset_context!
-    @context_monitor.synchronize { @context = nil }
+  # @return [Boolean] true if this call created the args, false if args already existed
+  def self.start_args(options:, root_task:)
+    @args_monitor.synchronize do
+      return false if @args
+      @args = Args.new(options: options, root_task: root_task)
+      true
+    end
   end
 
-  def self.global_registry
-    @global_registry ||= Execution::Registry.new
+  # Reset the runtime arguments (internal use only)
+  # @api private
+  def self.reset_args!
+    @args_monitor.synchronize { @args = nil }
   end
 
-  def self.reset_global_registry!
-    @global_registry = nil
+  # Execute a block with args lifecycle management.
+  # Creates args if they don't exist, and resets them only if this call created them.
+  # This prevents race conditions in concurrent execution.
+  #
+  # @param options [Hash] User-defined options
+  # @param root_task [Class] The root task class
+  # @yield The block to execute with args available
+  # @return [Object] The result of the block
+  def self.with_args(options:, root_task:)
+    created_args = start_args(options: options, root_task: root_task)
+    yield
+  ensure
+    reset_args! if created_args
   end
 
   # Progress display is enabled by default (tree-style).
   # Environment variables:
   # - TASKI_PROGRESS_DISABLE=1: Disable progress display entirely
-  # - TASKI_FORCE_PROGRESS=1: Force enable even without TTY (for testing)
+  # - TASKI_PROGRESS_MODE=simple|tree: Set display mode (default: tree)
   def self.progress_display
     return nil if progress_disabled?
-    @progress_display ||= Execution::TreeProgressDisplay.new
+    @progress_display ||= create_progress_display
   end
 
   def self.progress_disabled?
     ENV["TASKI_PROGRESS_DISABLE"] == "1"
   end
 
+  # Get the current progress mode (:tree or :simple)
+  # @return [Symbol] The current progress mode
+  def self.progress_mode
+    @progress_mode || progress_mode_from_env
+  end
+
+  # Set the progress mode (:tree or :simple)
+  # @param mode [Symbol] The mode to use (:tree or :simple)
+  def self.progress_mode=(mode)
+    @progress_mode = mode.to_sym
+    # Reset display so it will be recreated with new mode
+    @progress_display&.stop
+    @progress_display = nil
+  end
+
   def self.reset_progress_display!
     @progress_display&.stop
     @progress_display = nil
+    @progress_mode = nil
+  end
+
+  # @api private
+  def self.create_progress_display
+    case progress_mode
+    when :simple
+      Execution::SimpleProgressDisplay.new
+    when :plain
+      Execution::PlainProgressDisplay.new
+    else
+      Execution::TreeProgressDisplay.new
+    end
+  end
+
+  # @api private
+  def self.progress_mode_from_env
+    case ENV["TASKI_PROGRESS_MODE"]
+    when "simple"
+      :simple
+    when "plain"
+      :plain
+    else
+      :tree
+    end
+  end
+
+  # Get the worker count from the current args (set via Task.run(workers: n))
+  # @return [Integer, nil] The worker count or nil to use WorkerPool default
+  # @api private
+  def self.args_worker_count
+    args&.fetch(:_workers, nil)
+  end
+
+  # Get the current registry for this thread (used during dependency resolution)
+  # @return [Execution::Registry, nil] The current registry or nil
+  # @api private
+  def self.current_registry
+    Thread.current[:taski_current_registry]
+  end
+
+  # Set the current registry for this thread (internal use only)
+  # @api private
+  def self.set_current_registry(registry)
+    Thread.current[:taski_current_registry] = registry
+  end
+
+  # Clear the current registry for this thread (internal use only)
+  # @api private
+  def self.clear_current_registry
+    Thread.current[:taski_current_registry] = nil
   end
 end
+
+# Load Task and Section after Taski module is defined (they depend on TaskError)
+require_relative "taski/task"
+require_relative "taski/section"