taski 0.4.2 → 0.7.0

data/sig/taski.rbs

@@ -2,7 +2,9 @@ module Taski
   VERSION: String
 
   self.@global_registry: Execution::Registry?
-  self.@progress_display: Execution::ParallelProgressDisplay?
+  self.@progress_display: Execution::TreeProgressDisplay?
+  self.@args: Args?
+  self.@args_monitor: Monitor
 
   # Type alias for Task class (singleton type with class methods)
   # This represents a Class that inherits from Taski::Task
@@ -11,9 +13,13 @@ module Taski
   # Module-level methods
   def self.global_registry: () -> Execution::Registry
   def self.reset_global_registry!: () -> void
-  def self.progress_display: () -> Execution::ParallelProgressDisplay?
-  def self.progress_enabled?: () -> bool
+  def self.progress_display: () -> Execution::TreeProgressDisplay?
+  def self.progress_disabled?: () -> bool
   def self.reset_progress_display!: () -> void
+  def self.args: () -> Args?
+  def self.start_args: (options: Hash[Symbol, untyped], root_task: Class) -> void
+  def self.reset_args!: () -> void
+  def self.args_worker_count: () -> Integer?
 
   # Custom exceptions
   class TaskAbortException < StandardError
@@ -27,55 +33,101 @@ module Taski
     def initialize: (Array[Array[Class]] cyclic_tasks) -> void
   end
 
-  # Context class for execution context management
-  class Context
-    self.@monitor: Monitor
-    self.@working_directory: String?
-    self.@started_at: Time?
-    self.@root_task: Class?
-
-    def self.working_directory: () -> String
-    def self.started_at: () -> Time
-    def self.root_task: () -> Class?
-    def self.set_root_task: (Class task) -> void
-    def self.reset!: () -> void
+  # Represents a single task failure with its context
+  class TaskFailure
+    @task_class: Class
+    @error: Exception
+
+    attr_reader task_class: Class
+    attr_reader error: Exception
+
+    def initialize: (task_class: Class, error: Exception) -> void
+  end
+
+  # Mixin for exception classes to enable transparent rescue matching with AggregateError
+  module AggregateAware
+    def ===: (untyped other) -> bool
+  end
+
+  # Base class for task-specific error wrappers
+  class TaskError < StandardError
+    extend AggregateAware
+
+    @cause: Exception
+    @task_class: Class
+
+    attr_reader cause: Exception
+    attr_reader task_class: Class
+
+    def initialize: (Exception cause, task_class: Class) -> void
+  end
+
+  # Raised when multiple tasks fail during parallel execution
+  class AggregateError < StandardError
+    @errors: Array[TaskFailure]
+
+    attr_reader errors: Array[TaskFailure]
+
+    def initialize: (Array[TaskFailure] errors) -> void
+    def cause: () -> Exception?
+    def includes?: (Class exception_class) -> bool
+
+    private
+
+    def build_message: () -> String
+  end
+
+  # Args class for execution arguments management
+  class Args
+    @options: Hash[Symbol | String, untyped]
+    @root_task: Class
+    @started_at: Time
+    @working_directory: String
+
+    attr_reader started_at: Time
+    attr_reader working_directory: String
+    attr_reader root_task: Class
+
+    def initialize: (options: Hash[Symbol | String, untyped], root_task: Class) -> void
+    def []: (Symbol | String key) -> untyped
+    def fetch: (Symbol | String key, ?untyped default) ?{ () -> untyped } -> untyped
+    def key?: (Symbol | String key) -> bool
   end
 
   # Main Task class
   class Task
     self.@exported_methods: Array[Symbol]
     self.@dependencies_cache: Set[task_class]?
-    self.@coordinator: Execution::Coordinator?
     self.@circular_dependency_checked: bool
 
     # Class methods
+    def self.inherited: (Class subclass) -> void
     def self.exports: (*Symbol names) -> void
     def self.exported_methods: () -> Array[Symbol]
     def self.new: () -> Execution::TaskWrapper
     def self.cached_dependencies: () -> Set[task_class]
     def self.clear_dependency_cache: () -> void
-    def self.run: () -> untyped
-    def self.clean: () -> void
+    def self.run: (?args: Hash[Symbol, untyped], ?workers: Integer?) -> untyped
+    def self.clean: (?args: Hash[Symbol, untyped], ?workers: Integer?) -> void
+    def self.run_and_clean: (?args: Hash[Symbol, untyped], ?workers: Integer?) -> untyped
     def self.registry: () -> Execution::Registry
-    def self.coordinator: () -> Execution::Coordinator
     def self.reset!: () -> void
     def self.tree: () -> String
 
     # Instance methods
     def run: () -> void
     def clean: () -> void
+    def system: (*untyped args, **untyped opts) -> bool?
     def reset!: () -> void
 
     private
 
     # Private class methods
-    def self.build_tree: (task_class task_class, String prefix, Set[task_class] visited) -> String
-    def self.format_dependency_branch: (task_class dep, String prefix, bool is_last, Set[task_class] visited) -> String
-    def self.tree_connector_chars: (bool is_last) -> [String, String]
     def self.cached_wrapper: () -> Execution::TaskWrapper
     def self.define_instance_reader: (Symbol method_name) -> void
     def self.define_class_accessor: (Symbol method_name) -> void
     def self.validate_no_circular_dependencies!: () -> void
+    def self.validate_workers!: (untyped workers) -> void
   end
 
   # Section class for abstraction layers (inherits from Task)
@@ -119,43 +171,191 @@ module Taski
 
       def initialize: () -> void
       def get_or_create: (Class task_class) { () -> TaskWrapper } -> TaskWrapper
-      def get_task: (Class task_class) -> TaskWrapper
+      def get_task: (Class task_class) -> TaskWrapper?
+      def register: (Class task_class, TaskWrapper wrapper) -> void
       def register_thread: (Thread thread) -> void
       def wait_all: () -> void
       def reset!: () -> void
       def request_abort!: () -> void
       def abort_requested?: () -> bool
       def run: (Class task_class, Array[Symbol] exported_methods) -> untyped
+      def failed_wrappers: () -> Array[TaskWrapper]
+      def failed_clean_wrappers: () -> Array[TaskWrapper]
     end
 
-    # Coordinator class for dependency management
-    class Coordinator
+    # ExecutionContext manages execution state and notifies observers about execution events
+    class ExecutionContext
+      THREAD_LOCAL_KEY: Symbol
+
+      @monitor: Monitor
+      @observers: Array[untyped]
+      @execution_trigger: (^(Class, Registry) -> void)?
+      @clean_trigger: (^(Class, Registry) -> void)?
+      @output_capture: TaskOutputRouter?
+      @original_stdout: IO?
+      @runtime_dependencies: Hash[Class, Set[Class]]
+
+      def self.current: () -> ExecutionContext?
+      def self.current=: (ExecutionContext? context) -> void
+
+      def initialize: () -> void
+      def output_capture_active?: () -> bool
+      def setup_output_capture: (IO output_io) -> void
+      def teardown_output_capture: () -> void
+      def output_capture: () -> TaskOutputRouter?
+      def execution_trigger=: ((^(Class, Registry) -> void)? trigger) -> void
+      def clean_trigger=: ((^(Class, Registry) -> void)? trigger) -> void
+      def trigger_execution: (Class task_class, registry: Registry) -> void
+      def trigger_clean: (Class task_class, registry: Registry) -> untyped
+      def register_runtime_dependency: (Class from_class, Class to_class) -> void
+      def runtime_dependencies: () -> Hash[Class, Set[Class]]
+      def add_observer: (untyped observer) -> void
+      def remove_observer: (untyped observer) -> void
+      def observers: () -> Array[untyped]
+      def notify_task_registered: (Class task_class) -> void
+      def notify_task_started: (Class task_class) -> void
+      def notify_task_completed: (Class task_class, ?duration: Float?, ?error: Exception?) -> void
+      def notify_section_impl_selected: (Class section_class, Class impl_class) -> void
+      def notify_set_root_task: (Class task_class) -> void
+      def notify_set_output_capture: (TaskOutputRouter output_capture) -> void
+      def notify_start: () -> void
+      def notify_stop: () -> void
+      def notify_clean_started: (Class task_class) -> void
+      def notify_clean_completed: (Class task_class, ?duration: Float?, ?error: Exception?) -> void
+
+      private
+
+      def dispatch: (Symbol method_name, *untyped args, **untyped kwargs) -> void
+    end
+
+    # TaskOutputRouter for routing task output
+    class TaskOutputRouter
+      def initialize: (IO original_io) -> void
+      def current_write_io: () -> IO?
+      def start_capture: (Class task_class) -> void
+      def stop_capture: () -> void
+    end
+
+    # Scheduler manages task dependency state and determines execution order
+    class Scheduler
+      STATE_PENDING: Symbol
+      STATE_ENQUEUED: Symbol
+      STATE_COMPLETED: Symbol
+      CLEAN_STATE_PENDING: Symbol
+      CLEAN_STATE_ENQUEUED: Symbol
+      CLEAN_STATE_COMPLETED: Symbol
+
+      @dependencies: Hash[Class, Set[Class]]
+      @task_states: Hash[Class, Symbol]
+      @completed_tasks: Set[Class]
+      @reverse_dependencies: Hash[Class, Set[Class]]
+      @clean_task_states: Hash[Class, Symbol]
+      @clean_completed_tasks: Set[Class]
+
+      def initialize: () -> void
+      def build_dependency_graph: (Class root_task_class) -> void
+      def next_ready_tasks: () -> Array[Class]
+      def mark_enqueued: (Class task_class) -> void
+      def mark_completed: (Class task_class) -> void
+      def completed?: (Class task_class) -> bool
+      def running_tasks?: () -> bool
+      def merge_runtime_dependencies: (Hash[Class, Set[Class]] runtime_deps) -> void
+      def build_reverse_dependency_graph: (Class root_task_class) -> void
+      def next_ready_clean_tasks: () -> Array[Class]
+      def mark_clean_enqueued: (Class task_class) -> void
+      def mark_clean_completed: (Class task_class) -> void
+      def clean_completed?: (Class task_class) -> bool
+      def running_clean_tasks?: () -> bool
+
+      private
+
+      def ready_to_execute?: (Class task_class) -> bool
+      def ready_to_clean?: (Class task_class) -> bool
+    end
+
+    # WorkerPool manages a pool of worker threads that execute tasks
+    class WorkerPool
+      attr_reader execution_queue: Thread::Queue
+
+      @worker_count: Integer
       @registry: Registry
-      @analyzer: singleton(StaticAnalysis::Analyzer)
+      @on_execute: ^(Class, TaskWrapper) -> void
+      @execution_queue: Thread::Queue
+      @workers: Array[Thread]
 
-      def initialize: (registry: Registry, analyzer: singleton(StaticAnalysis::Analyzer)) -> void
-      def start_dependencies: (task_class task_class) -> void
-      def start_clean_dependencies: (task_class task_class) -> void
-      def get_dependencies: (task_class task_class) -> Set[task_class]
+      def initialize: (registry: Registry, ?worker_count: Integer?) { (Class, TaskWrapper) -> void } -> void
+      def start: () -> void
+      def enqueue: (Class task_class, TaskWrapper wrapper) -> void
+      def shutdown: () -> void
+      def enqueue_shutdown_signals: () -> void
 
       private
 
-      def start_thread_with: () { () -> void } -> void
-      def start_dependency_execution: (task_class dep_class) -> void
-      def start_dependency_clean: (task_class dep_class) -> void
+      def default_worker_count: () -> Integer
+      def worker_loop: () -> void
+      def debug_log: (String message) -> void
+    end
+
+    # Executor class for parallel task execution (Producer-Consumer pattern)
+    class Executor
+      @registry: Registry
+      @completion_queue: Thread::Queue
+      @execution_context: ExecutionContext
+      @scheduler: Scheduler
+      @effective_worker_count: Integer?
+      @worker_pool: WorkerPool
+      @clean_worker_pool: WorkerPool?
+
+      def self.execute: (Class root_task_class, registry: Registry, ?execution_context: ExecutionContext?) -> void
+      def self.execute_clean: (Class root_task_class, registry: Registry, ?execution_context: ExecutionContext?) -> void
+      def initialize: (registry: Registry, ?worker_count: Integer?, ?execution_context: ExecutionContext?) -> void
+      def execute: (Class root_task_class) -> void
+      def execute_clean: (Class root_task_class) -> void
+
+      private
+
+      def enqueue_ready_tasks: () -> void
+      def enqueue_task: (Class task_class) -> void
+      def get_or_create_wrapper: (Class task_class) -> TaskWrapper
+      def execute_task: (Class task_class, TaskWrapper wrapper) -> void
+      def run_main_loop: (Class root_task_class) -> void
+      def handle_completion: (Hash[Symbol, untyped] event) -> void
+      def enqueue_ready_clean_tasks: () -> void
+      def enqueue_clean_task: (Class task_class) -> void
+      def execute_clean_task: (Class task_class, TaskWrapper wrapper) -> void
+      def run_clean_main_loop: (Class root_task_class) -> void
+      def handle_clean_completion: (Hash[Symbol, untyped] event) -> void
+      def all_tasks_cleaned?: () -> bool
+      def setup_progress_display: (Class root_task_class) -> void
+      def setup_output_capture_if_needed: () -> bool
+      def teardown_output_capture: () -> void
+      def start_progress_display: () -> void
+      def stop_progress_display: () -> void
+      def create_default_execution_context: () -> ExecutionContext
+      def debug_log: (String message) -> void
+      def raise_if_any_failures: () -> void
+      def flatten_failures: (Array[TaskWrapper] failed_wrappers) -> Array[TaskFailure]
+      def wrap_with_task_error: (Class task_class, Exception error) -> TaskError
+      def raise_if_any_clean_failures: () -> void
+      def flatten_clean_failures: (Array[TaskWrapper] failed_wrappers) -> Array[TaskFailure]
+      def error_identity: (Exception error) -> Integer
     end
 
     # TaskWrapper class for task execution
     class TaskWrapper
       attr_reader task: Task
       attr_reader result: untyped
+      attr_reader error: StandardError?
+      attr_reader clean_error: StandardError?
+      attr_reader timing: TaskTiming?
 
       @task: Task
       @registry: Registry
-      @coordinator: Coordinator
+      @execution_context: ExecutionContext?
       @result: untyped
       @clean_result: untyped
       @error: StandardError?
+      @clean_error: StandardError?
       @monitor: Monitor
       @condition: MonitorMixin::ConditionVariable
       @clean_condition: MonitorMixin::ConditionVariable
@@ -166,39 +366,45 @@ module Taski
       STATE_PENDING: Symbol
       STATE_RUNNING: Symbol
       STATE_COMPLETED: Symbol
-
-      def initialize: (Task task, registry: Registry, coordinator: Coordinator) -> void
+      STATE_FAILED: Symbol
+
+      def initialize: (Task task, registry: Registry, ?execution_context: ExecutionContext?) -> void
+      def state: () -> Symbol
+      def pending?: () -> bool
+      def completed?: () -> bool
+      def failed?: () -> bool
+      def clean_failed?: () -> bool
       def run: () -> untyped
-      def clean: () -> void
+      def clean: () -> untyped
+      def run_and_clean: () -> untyped
       def get_exported_value: (Symbol method_name) -> untyped
-      def start_thread_with: () { () -> void } -> void
-      def execute_with_state_pattern: (state_getter: ^() -> Symbol, starter: ^() -> void, waiter: ^() -> void, ?pre_start_check: (^() -> void)?) -> void
-      def execute_task_if_needed: () -> void
-      def start_async_execution: () -> void
-      def execute_task: () -> void
-      def wait_for_dependencies: () -> void
-      def execute_clean_if_needed: () -> void
-      def start_async_clean: () -> void
-      def execute_clean: () -> void
-      def wait_for_clean_dependencies: () -> void
-      def mark_completed: () -> void
-      def mark_clean_completed: () -> void
-      def wait_for_completion: () -> untyped
+      def mark_running: () -> bool
+      def mark_completed: (untyped result) -> void
+      def mark_failed: (StandardError error) -> void
+      def mark_clean_running: () -> bool
+      def mark_clean_completed: (untyped result) -> void
+      def mark_clean_failed: (StandardError error) -> void
+      def wait_for_completion: () -> void
       def wait_for_clean_completion: () -> void
-      def debug_log: (String message) -> void
-      def log_start: () -> void
-      def log_completion: () -> void
-      def log_clean_start: () -> void
-      def log_clean_completion: () -> void
-      def register_with_progress_display: () -> void
-      def update_progress: (Symbol state, ?duration: Numeric?, ?error: Exception?) -> void
       def method_missing: (Symbol name, *untyped args) ?{ (*untyped) -> untyped } -> untyped
       def respond_to_missing?: (Symbol name, ?bool include_private) -> bool
+
+      private
+
+      def trigger_execution_and_wait: () -> void
+      def trigger_clean_and_wait: () -> void
+      def execute_clean: () -> void
+      def wait_for_clean_dependencies: () -> void
+      def check_abort!: () -> void
+      def update_progress: (Symbol state, ?duration: Numeric?, ?error: Exception?) -> void
+      def debug_log: (String message) -> void
     end
 
-    # ParallelProgressDisplay class for progress visualization
-    class ParallelProgressDisplay
+    # TreeProgressDisplay class for tree-based progress visualization
+    class TreeProgressDisplay
       SPINNER_FRAMES: Array[String]
+      COLORS: Hash[Symbol, String]
+      ICONS: Hash[Symbol, String]
 
       @output: IO
       @tasks: Hash[Class, TaskProgress]
@@ -206,6 +412,30 @@ module Taski
       @spinner_index: Integer
       @renderer_thread: Thread?
       @running: bool
+      @nest_level: Integer
+      @root_task_class: Class?
+      @tree_structure: Hash[Symbol, untyped]?
+      @section_impl_map: Hash[Class, Class]
+      @last_line_count: Integer
+
+      # Shared class methods
+      def self.section_class?: (Class klass) -> bool
+      def self.nested_class?: (Class child_class, Class parent_class) -> bool
+      def self.render_static_tree: (Class root_task_class) -> String
+
+      # Static tree renderer (internal class)
+      class StaticTreeRenderer
+        @task_index_map: Hash[Class, Integer]
+
+        def render: (Class root_task_class) -> String
+
+        private
+
+        def build_tree: (Class task_class, String prefix, bool is_impl, Set[Class] ancestors) -> String
+        def render_dependency_branch: (Class dep, String prefix, bool is_last, bool is_impl, Set[Class] ancestors) -> String
+        def get_task_number: (Class task_class) -> String
+        def colored_type_label: (Class klass) -> String
+      end
 
       class TaskProgress
         attr_accessor state: Symbol
@@ -213,28 +443,37 @@ module Taski
         attr_accessor end_time: Time?
         attr_accessor error: Exception?
         attr_accessor duration: Numeric?
+        attr_accessor is_impl_candidate: bool
 
         def initialize: () -> void
       end
 
       def initialize: (?output: IO) -> void
+      def set_root_task: (Class root_task_class) -> void
+      def register_section_impl: (Class section_class, Class impl_class) -> void
       def register_task: (Class task_class) -> void
       def task_registered?: (Class task_class) -> bool
       def update_task: (Class task_class, state: Symbol, ?duration: Numeric?, ?error: Exception?) -> void
       def task_state: (Class task_class) -> Symbol?
-      def render: () -> void
       def start: () -> void
       def stop: () -> void
 
       private
 
-      def collect_task_lines: () -> Array[String]
+      def build_tree_structure: () -> void
+      def build_tree_node: (Class task_class, Set[Class] ancestors) -> Hash[Symbol, untyped]?
+      def register_tasks_from_tree: (Hash[Symbol, untyped] node) -> void
       def render_live: () -> void
       def render_final: () -> void
-      def format_task_line: (Class task_class, TaskProgress progress) -> String
-      def task_icon: (Symbol state) -> String
+      def build_tree_display: () -> Array[String]
+      def build_root_tree_lines: (Hash[Symbol, untyped] node, String prefix, Array[String] lines) -> void
+      def render_children: (Hash[Symbol, untyped] node, String prefix, Array[String] lines, Class parent_task_class, bool ancestor_selected) -> void
+      def format_tree_line: (Class task_class, TaskProgress? progress, bool is_impl, bool is_selected) -> String
+      def format_unknown_task: (Class task_class, ?bool is_selected) -> String
       def spinner_char: () -> String
-      def task_details: (TaskProgress progress) -> String
+      def type_label_for: (Class task_class, ?bool is_selected) -> String
+      def section_class?: (Class klass) -> bool
+      def nested_class?: (Class child_class, Class parent_class) -> bool
     end
   end
 
@@ -246,19 +485,21 @@ module Taski
 
       private
 
-      def self.extract_run_method_location: (Class task_class) -> [String, Integer]?
+      def self.target_method_for: (Class task_class) -> Symbol
+      def self.extract_method_location: (Class task_class, Symbol method_name) -> [String, Integer]?
     end
 
     # Visitor class for AST traversal
     class Visitor < Prism::Visitor
       @target_task_class: Class
+      @target_method: Symbol
       @dependencies: Set[task_class]
-      @in_target_run_method: bool
+      @in_target_method: bool
       @current_namespace_path: Array[String?]
 
       attr_reader dependencies: Set[task_class]
 
-      def initialize: (Class task_class) -> void
+      def initialize: (Class task_class, Symbol target_method) -> void
       def visit_class_node: (Prism::ClassNode node) -> untyped
       def visit_module_node: (Prism::ModuleNode node) -> untyped
       def visit_def_node: (Prism::DefNode node) -> untyped
@@ -268,8 +509,10 @@ module Taski
 
       def within_namespace: (String? name) { () -> void } -> void
       def in_target_class?: () -> bool
+      def in_impl_method?: () -> bool
       def extract_constant_name: (untyped node) -> String?
       def detect_task_dependency: (Prism::CallNode node) -> void
+      def detect_impl_candidate: (untyped node) -> void
       def extract_receiver_constant: (untyped receiver) -> String?
       def resolve_and_add_dependency: (String constant_name) -> void
       def resolve_constant: (String name) -> task_class?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: taski
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.7.0
 platform: ruby
 authors:
 - ahogappa
@@ -50,26 +50,35 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".standard.yml"
+- CHANGELOG.md
 - LICENSE
 - README.md
 - Rakefile
 - Steepfile
-- docs/advanced-features.md
-- docs/api-guide.md
-- docs/error-handling.md
+- docs/GUIDE.md
 - examples/README.md
-- examples/context_demo.rb
+- examples/args_demo.rb
+- examples/clean_demo.rb
 - examples/data_pipeline_demo.rb
+- examples/group_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/system_call_demo.rb
+- examples/tree_progress_demo.rb
 - lib/taski.rb
-- lib/taski/context.rb
-- lib/taski/execution/coordinator.rb
-- lib/taski/execution/parallel_progress_display.rb
+- lib/taski/args.rb
+- lib/taski/execution/execution_context.rb
+- lib/taski/execution/executor.rb
 - lib/taski/execution/registry.rb
+- lib/taski/execution/scheduler.rb
+- lib/taski/execution/task_output_pipe.rb
+- lib/taski/execution/task_output_router.rb
 - lib/taski/execution/task_wrapper.rb
+- lib/taski/execution/tree_progress_display.rb
+- lib/taski/execution/worker_pool.rb
 - lib/taski/section.rb
 - lib/taski/static_analysis/analyzer.rb
 - lib/taski/static_analysis/dependency_graph.rb