taski 0.7.0 → 0.8.0

data/lib/taski/test_helper/mock_registry.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Taski
+  module TestHelper
+    # Global registry that stores mock definitions for tests.
+    # Uses a Mutex for thread-safety when accessed from worker threads.
+    # Mocks should be reset in test setup/teardown to ensure test isolation.
+    module MockRegistry
+      @mutex = Mutex.new
+      @mocks = {}
+
+      class << self
+        # Registers a mock for a task class.
+        # If a mock already exists for this class, it is replaced.
+        # @param task_class [Class] The task class to mock
+        # @param mock_wrapper [MockWrapper] The mock wrapper instance
+        def register(task_class, mock_wrapper)
+          @mutex.synchronize do
+            @mocks[task_class] = mock_wrapper
+          end
+        end
+
+        # Retrieves the mock wrapper for a task class, if one exists.
+        # @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)
+          @mutex.synchronize do
+            @mocks[task_class]
+          end
+        end
+
+        # Checks if any mocks are registered.
+        # Used for optimization to skip mock lookup in hot paths.
+        # @return [Boolean] true if mocks exist
+        def mocks_active?
+          @mutex.synchronize do
+            !@mocks.empty?
+          end
+        end
+
+        # Clears all registered mocks and resets args/env.
+        # Should be called in test setup/teardown.
+        def reset!
+          @mutex.synchronize do
+            @mocks = {}
+          end
+          Taski.reset_args!
+          Taski.reset_env!
+        end
+      end
+    end
+  end
+end

data/lib/taski/test_helper/mock_wrapper.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Taski
+  module TestHelper
+    # Wraps a mocked task and returns pre-configured values without executing the task.
+    # Tracks which methods were accessed for verification in tests.
+    class MockWrapper
+      attr_reader :task_class, :mock_values
+
+      # @param task_class [Class] The task class being mocked
+      # @param mock_values [Hash{Symbol => Object}] Method names mapped to their return values
+      def initialize(task_class, mock_values)
+        @task_class = task_class
+        @mock_values = mock_values
+        @access_counts = Hash.new(0)
+      end
+
+      # Returns the mocked value for a method and records the access.
+      # @param method_name [Symbol] The exported method name
+      # @return [Object] The pre-configured mock value
+      # @raise [KeyError] If method_name was not configured in the mock
+      def get_exported_value(method_name)
+        unless @mock_values.key?(method_name)
+          raise KeyError, "No mock value for method :#{method_name} on #{@task_class}"
+        end
+
+        @access_counts[method_name] += 1
+        @mock_values[method_name]
+      end
+
+      # Checks if a method was accessed at least once.
+      # @param method_name [Symbol] The method name to check
+      # @return [Boolean] true if accessed at least once
+      def accessed?(method_name)
+        @access_counts[method_name] > 0
+      end
+
+      # Returns the number of times a method was accessed.
+      # @param method_name [Symbol] The method name to check
+      # @return [Integer] Number of accesses (0 if never accessed)
+      def access_count(method_name)
+        @access_counts[method_name]
+      end
+    end
+  end
+end

data/lib/taski/test_helper/rspec.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "../test_helper"
+
+module Taski
+  module TestHelper
+    # RSpec integration module.
+    # Include this in your RSpec examples for automatic mock cleanup.
+    #
+    # @example In spec_helper.rb
+    #   require 'taski/test_helper/rspec'
+    #
+    #   RSpec.configure do |config|
+    #     config.include Taski::TestHelper::RSpec
+    #   end
+    #
+    # @example In individual specs
+    #   RSpec.describe MyTask do
+    #     include Taski::TestHelper::RSpec
+    #
+    #     it "processes data" do
+    #       mock_task(FetchData, result: "mocked")
+    #       # ... test code ...
+    #     end
+    #   end
+    module RSpec
+      def self.included(base)
+        base.include(Taski::TestHelper)
+
+        # Add before/after hooks when included in RSpec
+        if base.respond_to?(:before) && base.respond_to?(:after)
+          base.before(:each) { Taski::TestHelper.reset_mocks! }
+          base.after(:each) { Taski::TestHelper.reset_mocks! }
+        end
+      end
+    end
+  end
+end

data/lib/taski/test_helper.rb

@@ -0,0 +1,246 @@
+# 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.send(:with_env, root_task: self) do
+              Taski.send(:with_args, options: {}) do
+                validate_no_circular_dependencies!
+                fresh_wrapper.get_exported_value(method)
+              end
+            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
+
+    # Sets mock args for the duration of the test.
+    # This allows testing code that depends on Taski.args without running full task execution.
+    # Args are automatically cleared when MockRegistry.reset! is called (in test teardown).
+    # @param options [Hash] User-defined options to include in args
+    # @return [Taski::Args] The created args instance
+    #
+    # @example
+    #   mock_args(env: "test", debug: true)
+    #   assert_equal "test", Taski.args[:env]
+    def mock_args(**options)
+      Taski.reset_args!
+      Taski.send(:start_args, options: options)
+      Taski.args
+    end
+
+    # Sets mock env for the duration of the test.
+    # This allows testing code that depends on Taski.env without running full task execution.
+    # Env is automatically cleared when MockRegistry.reset! is called (in test teardown).
+    # @param root_task [Class] The root task class (defaults to nil for testing)
+    # @return [Taski::Env] The created env instance
+    #
+    # @example
+    #   mock_env(root_task: MyTask)
+    #   assert_equal MyTask, Taski.env.root_task
+    def mock_env(root_task: nil)
+      Taski.reset_env!
+      Taski.send(:start_env, root_task: root_task)
+      Taski.env
+    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.7.0"
+  VERSION = "0.8.0"
 end

data/lib/taski.rb

@@ -11,7 +11,10 @@ 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/execution/simple_progress_display"
+require_relative "taski/execution/plain_progress_display"
 require_relative "taski/args"
+require_relative "taski/env"
 
 module Taski
   class TaskAbortException < StandardError
@@ -31,13 +34,15 @@ module Taski
 
   # Represents a single task failure with its context
   class TaskFailure
-    attr_reader :task_class, :error
+    attr_reader :task_class, :error, :output_lines
 
     # @param task_class [Class] The task class that failed
     # @param error [Exception] The exception that was raised
-    def initialize(task_class:, error:)
+    # @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
 
@@ -117,12 +122,24 @@ module Taski
 
     def build_message
       task_word = (errors.size == 1) ? "task" : "tasks"
-      "#{errors.size} #{task_word} failed:\n" +
-        errors.map { |f| "  - #{f.task_class.name}: #{f.error.message}" }.join("\n")
+      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
 
   @args_monitor = Monitor.new
+  @env_monitor = Monitor.new
 
   # Get the current runtime arguments
   # @return [Args, nil] The current args or nil if no task is running
@@ -130,12 +147,51 @@ module Taski
     @args_monitor.synchronize { @args }
   end
 
+  # Get the current execution environment
+  # @return [Env, nil] The current env or nil if no task is running
+  def self.env
+    @env_monitor.synchronize { @env }
+  end
+
+  # Start new execution environment (internal use only)
+  # @api private
+  # @return [Boolean] true if this call created the env, false if env already existed
+  def self.start_env(root_task:)
+    @env_monitor.synchronize do
+      return false if @env
+      @env = Env.new(root_task: root_task)
+      true
+    end
+  end
+
+  # Reset the execution environment (internal use only)
+  # @api private
+  def self.reset_env!
+    @env_monitor.synchronize { @env = nil }
+  end
+
+  # Execute a block with env lifecycle management.
+  # Creates env if it doesn't exist, and resets it only if this call created it.
+  # This prevents race conditions in concurrent execution.
+  #
+  # @param root_task [Class] The root task class
+  # @yield The block to execute with env available
+  # @return [Object] The result of the block
+  def self.with_env(root_task:)
+    created_env = start_env(root_task: root_task)
+    yield
+  ensure
+    reset_env! if created_env
+  end
+
   # Start new runtime arguments (internal use only)
   # @api private
-  def self.start_args(options:, root_task:)
+  # @return [Boolean] true if this call created the args, false if args already existed
+  def self.start_args(options:)
     @args_monitor.synchronize do
-      return if @args
-      @args = Args.new(options: options, root_task: root_task)
+      return false if @args
+      @args = Args.new(options: options)
+      true
     end
   end
 
@@ -145,21 +201,76 @@ module Taski
     @args_monitor.synchronize { @args = nil }
   end
 
+  # 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
+  # @yield The block to execute with args available
+  # @return [Object] The result of the block
+  def self.with_args(options:)
+    created_args = start_args(options: options)
+    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_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))

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: taski
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - ahogappa
@@ -61,19 +61,25 @@ files:
 - examples/clean_demo.rb
 - examples/data_pipeline_demo.rb
 - examples/group_demo.rb
+- examples/large_tree_demo.rb
 - examples/nested_section_demo.rb
 - examples/parallel_progress_demo.rb
 - examples/quick_start.rb
 - examples/reexecution_demo.rb
 - examples/section_demo.rb
+- examples/simple_progress_demo.rb
 - examples/system_call_demo.rb
 - examples/tree_progress_demo.rb
 - lib/taski.rb
 - lib/taski/args.rb
+- lib/taski/env.rb
+- lib/taski/execution/base_progress_display.rb
 - lib/taski/execution/execution_context.rb
 - lib/taski/execution/executor.rb
+- lib/taski/execution/plain_progress_display.rb
 - lib/taski/execution/registry.rb
 - lib/taski/execution/scheduler.rb
+- lib/taski/execution/simple_progress_display.rb
 - lib/taski/execution/task_output_pipe.rb
 - lib/taski/execution/task_output_router.rb
 - lib/taski/execution/task_wrapper.rb
@@ -84,6 +90,12 @@ files:
 - lib/taski/static_analysis/dependency_graph.rb
 - lib/taski/static_analysis/visitor.rb
 - lib/taski/task.rb
+- lib/taski/test_helper.rb
+- lib/taski/test_helper/errors.rb
+- lib/taski/test_helper/minitest.rb
+- lib/taski/test_helper/mock_registry.rb
+- lib/taski/test_helper/mock_wrapper.rb
+- lib/taski/test_helper/rspec.rb
 - lib/taski/version.rb
 - rbs_collection.lock.yaml
 - rbs_collection.yaml
@@ -108,7 +120,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.3
 specification_version: 4
 summary: A simple yet powerful Ruby task runner with static dependency resolution
   (in development).