taski 0.8.3 → 0.9.0

data/lib/taski/execution/registry.rb

@@ -24,16 +24,14 @@ module Taski
       # @param task_class [Class] The task class
       # @param wrapper [TaskWrapper] The wrapper instance to register
       def register(task_class, wrapper)
-        @tasks[task_class] = wrapper
+        @monitor.synchronize { @tasks[task_class] = wrapper }
       end
 
+      # Check if a task wrapper has been registered (created during run phase).
       # @param task_class [Class] The task class
-      # @return [Object] The task instance
-      # @raise [RuntimeError] If the task is not registered
-      def get_task(task_class)
-        @tasks.fetch(task_class) do
-          raise "Task #{task_class} not registered"
-        end
+      # @return [Boolean] true if a wrapper exists for this task
+      def registered?(task_class)
+        @monitor.synchronize { @tasks.key?(task_class) }
       end
 
       # @param thread [Thread] The thread to register
@@ -77,19 +75,17 @@ module Taski
         end
       end
 
-      # @param task_class [Class] The task class to run
-      # @param exported_methods [Array<Symbol>] Methods to call to trigger execution
-      # @return [Object] The result of the task execution
-      def run(task_class, exported_methods)
-        exported_methods.each do |method|
-          task_class.public_send(method)
+      # Create or retrieve a TaskWrapper for the given task class.
+      # Encapsulates the standard wrapper creation pattern used by Executor and WorkerPool.
+      # @param task_class [Class] The task class
+      # @param execution_facade [ExecutionFacade] The execution facade
+      # @return [TaskWrapper] The wrapper instance
+      def create_wrapper(task_class, execution_facade:)
+        get_or_create(task_class) do
+          task_instance = task_class.allocate
+          task_instance.send(:initialize)
+          TaskWrapper.new(task_instance, registry: self, execution_facade: execution_facade)
         end
-
-        wait_all
-
-        # @type var wrapper: Taski::Execution::TaskWrapper
-        wrapper = get_task(task_class)
-        wrapper.result
       end
     end
   end

data/lib/taski/execution/scheduler.rb

@@ -3,13 +3,19 @@
 module Taski
   module Execution
     # Scheduler manages task dependency state and determines execution order.
-    # It tracks which tasks are pending, enqueued, or completed, and provides
-    # methods to determine which tasks are ready to execute.
+    # Both run and clean phases use the same unified state set:
+    # :pending, :running, :completed, :failed, :skipped.
+    #
+    # == State Transitions
+    #
+    # Run phase:   pending → running → completed | failed
+    #              pending → skipped (when a dependency fails)
+    # Clean phase: pending → running → completed
     #
     # == Responsibilities
     #
-    # - Build dependency graph from root task via static analysis
-    # - Track task states: pending, enqueued, completed
+    # - Load pre-built dependency graph from Executor
+    # - Track task states: pending, running, completed
     # - Determine which tasks are ready to execute (all dependencies completed)
     # - Provide next_ready_tasks for the Executor's event loop
     # - Build reverse dependency graph for clean operations
@@ -19,19 +25,19 @@ module Taski
     # == API
     #
     # Run operations:
-    # - {#build_dependency_graph} - Initialize dependency graph from root task
+    # - {#load_graph} - Load pre-built dependency graph
     # - {#next_ready_tasks} - Get tasks ready for execution
-    # - {#mark_enqueued} - Mark task as sent to worker pool
+    # - {#mark_running} - Mark task as sent to worker pool
     # - {#mark_completed} - Mark task as finished
-    # - {#completed?} - Check if task is completed
+    # - {#finished?} - Check if task is completed
     # - {#running_tasks?} - Check if any tasks are currently executing
     #
     # Clean operations:
     # - {#build_reverse_dependency_graph} - Build reverse graph for clean order
     # - {#next_ready_clean_tasks} - Get tasks ready for clean (reverse order)
-    # - {#mark_clean_enqueued} - Mark task as sent for clean
+    # - {#mark_clean_running} - Mark task as sent for clean
     # - {#mark_clean_completed} - Mark task as clean finished
-    # - {#clean_completed?} - Check if task clean is completed
+    # - {#clean_finished?} - Check if task clean is completed
     # - {#running_clean_tasks?} - Check if any clean tasks are currently executing
     #
     # == Thread Safety
@@ -40,59 +46,56 @@ module Taski
     # so no synchronization is needed. The Executor serializes all
     # access to the Scheduler through its event loop.
     class Scheduler
-      # Task execution states
+      # Unified task execution states (used by both run and clean phases)
       STATE_PENDING = :pending
-      STATE_ENQUEUED = :enqueued
+      STATE_RUNNING = :running
       STATE_COMPLETED = :completed
-
-      # Clean execution states (independent from run states)
-      CLEAN_STATE_PENDING = :clean_pending
-      CLEAN_STATE_ENQUEUED = :clean_enqueued
-      CLEAN_STATE_COMPLETED = :clean_completed
+      STATE_FAILED = :failed
+      STATE_SKIPPED = :skipped
 
       ##
       # Initializes internal data structures used to track normal and clean task execution.
-      #
-      # Sets up:
-      # - @dependencies: map from task class to its dependency task classes.
-      # - @task_states: map from task class to its normal execution state.
-      # - @completed_tasks: set of task classes that have completed normal execution.
-      # - @reverse_dependencies: map from task class to dependent task classes (used for clean ordering).
-      # - @clean_task_states: map from task class to its clean execution state.
-      # - @clean_completed_tasks: set of task classes that have completed clean execution.
       def initialize
         # Run execution state
         @dependencies = {}
         @task_states = {}
-        @completed_tasks = Set.new
+        @finished_tasks = Set.new
+        @run_reverse_deps = {}
 
-        # Clean execution state (independent tracking)
+        # Clean execution state (independent tracking, same state values)
         @reverse_dependencies = {}
         @clean_task_states = {}
-        @clean_completed_tasks = Set.new
+        @clean_finished_tasks = Set.new
       end
 
-      # Build dependency graph by traversing from root task.
-      # Populates internal state with all tasks and their dependencies.
+      # Load dependency graph from a pre-built DependencyGraph.
+      # Populates internal state with all tasks and their dependencies via BFS from root.
       #
+      # @param dependency_graph [StaticAnalysis::DependencyGraph] Pre-built graph
       # @param root_task_class [Class] The root task class to start from
-      def build_dependency_graph(root_task_class)
+      def load_graph(dependency_graph, root_task_class)
         # @type var queue: Array[singleton(Taski::Task)]
         queue = [root_task_class]
 
         while (task_class = queue.shift)
           next if @task_states.key?(task_class)
 
-          deps = task_class.cached_dependencies
+          deps = dependency_graph.dependencies_for(task_class)
           @dependencies[task_class] = deps.dup
           @task_states[task_class] = STATE_PENDING
+          @run_reverse_deps[task_class] ||= Set.new
 
-          deps.each { |dep| queue << dep }
+          deps.each do |dep|
+            @run_reverse_deps[dep] ||= Set.new
+            @run_reverse_deps[dep].add(task_class)
+            log_dependency_resolved(task_class, dep)
+            queue << dep
+          end
         end
       end
 
       # Get all tasks that are ready to execute.
-      # A task is ready when all its dependencies are completed.
+      # A task is ready when it is pending and all its dependencies are completed.
       #
       # @return [Array<Class>] Array of task classes ready for execution
       def next_ready_tasks
@@ -105,11 +108,12 @@ module Taski
         ready
       end
 
-      # Mark a task as enqueued for execution.
+      # Mark a task as running (sent to worker pool).
+      # Prevents the task from being selected again by next_ready_tasks.
       #
       # @param task_class [Class] The task class to mark
-      def mark_enqueued(task_class)
-        @task_states[task_class] = STATE_ENQUEUED
+      def mark_running(task_class)
+        @task_states[task_class] = STATE_RUNNING
       end
 
       # Mark a task as completed.
@@ -117,65 +121,101 @@ module Taski
       # @param task_class [Class] The task class to mark
       def mark_completed(task_class)
         @task_states[task_class] = STATE_COMPLETED
-        @completed_tasks.add(task_class)
+        @finished_tasks.add(task_class)
+      end
+
+      # Mark a task as failed.
+      # Failed tasks are added to the finished set so dependents can proceed
+      # (they will be skipped by the Executor's skip_pending_dependents).
+      #
+      # @param task_class [Class] The task class to mark
+      def mark_failed(task_class)
+        @task_states[task_class] = STATE_FAILED
+        @finished_tasks.add(task_class)
       end
 
-      # Check if a task is completed.
+      # Check if a task is in pending state.
       #
       # @param task_class [Class] The task class to check
-      # @return [Boolean] true if the task is completed
-      def completed?(task_class)
-        @completed_tasks.include?(task_class)
+      # @return [Boolean] true if the task is pending
+      def pending?(task_class)
+        @task_states[task_class] == STATE_PENDING
       end
 
-      # Check if there are any running (enqueued) tasks.
+      # Check if a task is finished (completed or failed).
       #
-      ##
-      # Indicates whether any tasks are currently enqueued for execution.
-      # @return [Boolean] `true` if any task is enqueued, `false` otherwise.
+      # @param task_class [Class] The task class to check
+      # @return [Boolean] true if the task is finished
+      def finished?(task_class)
+        @finished_tasks.include?(task_class)
+      end
+
+      # Check if there are any running tasks.
+      #
+      # @return [Boolean] true if any task is running, false otherwise.
       def running_tasks?
-        @task_states.values.any? { |state| state == STATE_ENQUEUED }
+        @task_states.values.any? { |state| state == STATE_RUNNING }
       end
 
-      # ========================================
-      # Runtime Dependency Merging
-      # ========================================
+      # Get the total number of tasks in the dependency graph.
+      #
+      # @return [Integer] The number of tasks
+      def task_count
+        @task_states.size
+      end
+
+      # Get task classes that were never executed (remained in STATE_PENDING).
+      # These are tasks discovered by the static dependency graph
+      # (via load_graph) but not reached at runtime — e.g.,
+      # skipped due to conditional logic inside Task#run or because the
+      # root task completed before all statically-discovered tasks were needed.
+      #
+      # @return [Array<Class>] Array of task classes still pending
+      def never_started_task_classes
+        @task_states.select { |_, state| state == STATE_PENDING }.keys
+      end
+
+      # Mark a task as skipped (never executed). Only transitions from pending.
+      #
+      # @param task_class [Class] The task class to mark as skipped
+      # @return [Boolean] true if the state was changed
+      def mark_skipped(task_class)
+        return false unless @task_states[task_class] == STATE_PENDING
+        @task_states[task_class] = STATE_SKIPPED
+        true
+      end
 
-      # Merge runtime dependencies into the dependency graph.
-      # Used to incorporate dynamically selected dependencies (e.g., Section implementations)
-      # that were determined during the run phase.
+      # Get the count of tasks in STATE_SKIPPED.
       #
-      # This method also updates reverse dependencies if they exist (for clean operations).
-      # This method is idempotent - calling it multiple times with the same data is safe.
+      # @return [Integer] Number of explicitly skipped tasks
+      def skipped_count
+        @task_states.count { |_, state| state == STATE_SKIPPED }
+      end
+
+      # Find all pending tasks that transitively depend on the given task.
+      # Traverses the reverse dependency graph (run phase) using BFS.
+      # Only returns tasks in STATE_PENDING; running/completed tasks are
+      # traversed through but not included in results.
       #
-      # @param runtime_deps [Hash{Class => Set<Class>}] Runtime dependencies from ExecutionContext
-      def merge_runtime_dependencies(runtime_deps)
-        runtime_deps.each do |from_class, to_classes|
-          # Ensure the from_class exists in the graph
-          @dependencies[from_class] ||= Set.new
-          @task_states[from_class] ||= STATE_PENDING
-
-          to_classes.each do |to_class|
-            # Add the dependency relationship
-            @dependencies[from_class].add(to_class)
-
-            # Add the to_class to the graph if not present
-            unless @dependencies.key?(to_class)
-              @dependencies[to_class] = to_class.cached_dependencies
-              @task_states[to_class] = STATE_PENDING
-            end
-
-            # Update reverse dependencies if they exist (for clean operations)
-            # If A depends on B (from_class→to_class), then B→[A] in reverse graph
-            if @reverse_dependencies.any?
-              @reverse_dependencies[to_class] ||= Set.new
-              @reverse_dependencies[to_class].add(from_class)
-
-              # Ensure to_class has clean state initialized
-              @clean_task_states[to_class] ||= CLEAN_STATE_PENDING
-            end
+      # @param task_class [Class] The task to find dependents of
+      # @return [Array<Class>] Pending transitive dependents
+      def pending_dependents_of(task_class)
+        result = []
+        queue = [task_class]
+        visited = Set.new([task_class])
+
+        while (tc = queue.shift)
+          dependents = @run_reverse_deps[tc] || Set.new
+          dependents.each do |dep|
+            next if visited.include?(dep)
+            visited.add(dep)
+
+            result << dep if @task_states[dep] == STATE_PENDING
+            queue << dep
           end
         end
+
+        result
       end
 
       # ========================================
@@ -186,28 +226,18 @@ module Taski
       # Clean operations run in reverse order: if A depends on B, then B must
       # be cleaned after A (so A→[B] in reverse graph means B depends on A's clean).
       #
-      # Also initializes clean states for all tasks to CLEAN_STATE_PENDING.
-      #
-      ##
-      # Builds the reverse dependency graph and initializes per-task clean execution state starting from the given root task.
-      #
-      # Ensures the forward dependency graph is present, clears prior clean-state data, initializes each discovered task with
-      # an empty reverse-dependency set and `CLEAN_STATE_PENDING`, and populates reverse mappings so a task's clean run
-      # depends on the clean completion of tasks that depend on it.
-      # @param [Class] root_task_class The root task class from which to discover tasks and their dependencies.
-      def build_reverse_dependency_graph(root_task_class)
-        # First, ensure we have the forward dependency graph
-        build_dependency_graph(root_task_class) if @dependencies.empty?
-
+      # Requires load_graph to have been called first to populate @dependencies.
+      # Also initializes clean states for all tasks to STATE_PENDING.
+      def build_reverse_dependency_graph
         # Clear previous clean state
         @reverse_dependencies.clear
         @clean_task_states.clear
-        @clean_completed_tasks.clear
+        @clean_finished_tasks.clear
 
         # Initialize all tasks with empty reverse dependency sets
         @dependencies.each_key do |task_class|
           @reverse_dependencies[task_class] = Set.new
-          @clean_task_states[task_class] = CLEAN_STATE_PENDING
+          @clean_task_states[task_class] = STATE_PENDING
         end
 
         # Build reverse mappings: if A depends on B, then B→[A] in reverse graph
@@ -220,88 +250,79 @@ module Taski
       end
 
       # Get all tasks that are ready to clean.
-      # A task is ready to clean when all its reverse dependencies (dependents)
-      # have completed their clean operation.
+      # A task is ready to clean when it is pending and all its reverse
+      # dependencies (dependents) have completed their clean operation.
       #
-      ##
-      # Lists task classes that are ready for clean execution.
-      # A task is considered ready when its clean state is `CLEAN_STATE_PENDING` and all of its reverse dependencies have completed their clean execution.
       # @return [Array<Class>] Array of task classes ready for clean execution.
       def next_ready_clean_tasks
         ready = []
         @clean_task_states.each_key do |task_class|
-          next unless @clean_task_states[task_class] == CLEAN_STATE_PENDING
+          next unless @clean_task_states[task_class] == STATE_PENDING
           next unless ready_to_clean?(task_class)
           ready << task_class
         end
         ready
       end
 
-      # Mark a task as enqueued for clean execution.
+      # Mark a task as running for clean execution.
       #
-      ##
-      # Marks the given task class as enqueued for clean execution.
-      # @param [Class] task_class The task class to mark as enqueued for clean execution.
-      def mark_clean_enqueued(task_class)
-        @clean_task_states[task_class] = CLEAN_STATE_ENQUEUED
+      # @param task_class [Class] The task class to mark as running for clean.
+      def mark_clean_running(task_class)
+        @clean_task_states[task_class] = STATE_RUNNING
       end
 
       # Mark a task as clean completed.
       #
-      ##
-      # Marks the clean execution of the given task class as completed and records it.
-      # @param [Class] task_class - The task class to mark as clean completed.
+      # @param task_class [Class] The task class to mark as clean completed.
       def mark_clean_completed(task_class)
-        @clean_task_states[task_class] = CLEAN_STATE_COMPLETED
-        @clean_completed_tasks.add(task_class)
+        @clean_task_states[task_class] = STATE_COMPLETED
+        @clean_finished_tasks.add(task_class)
+      end
+
+      # Mark a task as clean failed.
+      # Adds to @clean_finished_tasks so dependents are not blocked.
+      #
+      # @param task_class [Class] The task class to mark as clean failed.
+      def mark_clean_failed(task_class)
+        @clean_task_states[task_class] = STATE_FAILED
+        @clean_finished_tasks.add(task_class)
       end
 
       # Check if a task's clean is completed.
       #
-      # @param task_class [Class] The task class to check
-      ##
-      # Checks whether a task class has completed its clean execution.
-      # @param [Class] task_class - The task class to check.
-      # @return [Boolean] `true` if the task's clean is completed, `false` otherwise.
-      def clean_completed?(task_class)
-        @clean_completed_tasks.include?(task_class)
+      # @param task_class [Class] The task class to check.
+      # @return [Boolean] true if the task's clean is completed, false otherwise.
+      def clean_finished?(task_class)
+        @clean_finished_tasks.include?(task_class)
       end
 
-      # Check if there are any running (enqueued) clean tasks.
+      # Check if there are any running clean tasks.
       #
-      ##
-      # Indicates whether any clean tasks are currently enqueued for execution.
-      # @return [Boolean] `true` if at least one clean task is enqueued, `false` otherwise.
+      # @return [Boolean] true if at least one clean task is running, false otherwise.
       def running_clean_tasks?
-        @clean_task_states.values.any? { |state| state == CLEAN_STATE_ENQUEUED }
+        @clean_task_states.values.any? { |state| state == STATE_RUNNING }
       end
 
       private
 
       # Check if a task is ready to execute (all dependencies completed).
-      #
-      # @param task_class [Class] The task class to check
-      ##
-      # Determines whether a task's dependencies have all completed.
-      # @param [Class] task_class - The task class to check.
-      # @return [Boolean] `true` if every dependency of `task_class` is in the set of completed tasks, `false` otherwise.
       def ready_to_execute?(task_class)
         task_deps = @dependencies[task_class] || Set.new
-        task_deps.subset?(@completed_tasks)
+        task_deps.subset?(@finished_tasks)
       end
 
       # Check if a task is ready to clean (all reverse dependencies completed).
-      # Reverse dependencies are tasks that depend on this task, which must
-      # be cleaned before this task can be cleaned.
-      #
-      # @param task_class [Class] The task class to check
-      ##
-      # Determines whether a task is ready for clean execution.
-      # @param [Class] task_class - The task class to check.
-      # @return [Boolean] `true` if all tasks that depend on `task_class` have completed their clean execution, `false` otherwise.
       def ready_to_clean?(task_class)
         reverse_deps = @reverse_dependencies[task_class] || Set.new
-        reverse_deps.subset?(@clean_completed_tasks)
+        reverse_deps.subset?(@clean_finished_tasks)
+      end
+
+      def log_dependency_resolved(from_task, to_task)
+        Taski::Logging.debug(
+          Taski::Logging::Events::DEPENDENCY_RESOLVED,
+          from_task: from_task.name,
+          to_task: to_task.name
+        )
       end
     end
   end

data/lib/taski/execution/task_observer.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Taski
+  module Execution
+    # Base class for observers of the execution lifecycle.
+    # Subclasses override only the events they care about.
+    #
+    # All events are defined as no-op methods. The +context+ accessor
+    # is auto-injected by ExecutionFacade#add_observer.
+    #
+    # == Event Methods
+    #
+    # - on_ready — facade is configured, observer can pull from context
+    # - on_start — execution is about to begin
+    # - on_stop — execution has finished
+    # - on_task_updated(task_class, previous_state:, current_state:, phase:, timestamp:)
+    # - on_group_started(task_class, group_name, phase:, timestamp:)
+    # - on_group_completed(task_class, group_name, phase:, timestamp:)
+    class TaskObserver
+      attr_accessor :context
+
+      def on_ready
+      end
+
+      def on_start
+      end
+
+      def on_stop
+      end
+
+      def on_task_updated(task_class, previous_state:, current_state:, phase:, timestamp:)
+      end
+
+      def on_group_started(task_class, group_name, phase:, timestamp:)
+      end
+
+      def on_group_completed(task_class, group_name, phase:, timestamp:)
+      end
+    end
+  end
+end