taski 0.3.1 → 0.4.1

data/sig/taski.rbs

@@ -1,99 +1,306 @@
 module Taski
   VERSION: String
 
+  self.@global_registry: Execution::Registry?
+  self.@progress_display: Execution::ParallelProgressDisplay?
+
+  # Type alias for Task class (singleton type with class methods)
+  # This represents a Class that inherits from Taski::Task
+  type task_class = singleton(Task)
+
+  # 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.reset_progress_display!: () -> void
+
   # Custom exceptions
-  class CircularDependencyError < StandardError
+  class TaskAbortException < StandardError
   end
 
-  class TaskAnalysisError < StandardError
-  end
+  class CircularDependencyError < StandardError
+    @cyclic_tasks: Array[Array[Class]]
+
+    attr_reader cyclic_tasks: Array[Array[Class]]
 
-  class TaskBuildError < StandardError
+    def initialize: (Array[Array[Class]] cyclic_tasks) -> void
   end
 
-  # Reference class for task references
-  class Reference
-    @klass: String
+  # Context class for execution context management
+  class Context
+    self.@monitor: Monitor
+    self.@working_directory: String?
+    self.@started_at: Time?
+    self.@root_task: Class?
 
-    def initialize: (String klass) -> void
-    def deref: () -> Class
-    def ==: (untyped other) -> bool
-    def inspect: () -> String
+    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
   end
 
   # Main Task class
   class Task
-    # Constants
-    THREAD_KEY_SUFFIX: String
-    TASKI_ANALYZING_DEFINE_KEY: Symbol
-    ANALYZED_METHODS: Array[Symbol]
+    self.@exported_methods: Array[Symbol]
+    self.@dependencies_cache: Set[task_class]?
+    self.@coordinator: Execution::Coordinator?
+    self.@circular_dependency_checked: bool
 
-    # Hook methods
-    def self.method_added: (Symbol method_name) -> void
-
-    # Public API methods
+    # Class methods
     def self.exports: (*Symbol names) -> void
-    def self.define: (Symbol name) { () -> untyped } -> void
-    def self.build: () -> 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.reset!: () -> self
-    def self.refresh: () -> self
-    def self.resolve: (Array[untyped] queue, Array[untyped] resolved) -> self
-    def self.ref: (String | Class klass) -> (Reference | Class)
-    def self.ensure_instance_built: () -> Task
-
-    # Define API methods
-    def self.__resolve__: () -> Hash[Symbol, untyped]
-    def self.resolve_dependencies: () -> void
+    def self.registry: () -> Execution::Registry
+    def self.coordinator: () -> Execution::Coordinator
+    def self.reset!: () -> void
+    def self.tree: () -> String
 
     # Instance methods
-    def build: () -> void
+    def run: () -> void
     def clean: () -> void
+    def reset!: () -> void
 
-    # Allow dynamic method definitions
-    def method_missing: (Symbol name, *untyped args) ?{ (*untyped) -> untyped } -> untyped
-    def respond_to_missing?: (Symbol name, bool include_private) -> bool
+    private
 
-    # Allow dynamic class method definitions  
-    def self.method_missing: (Symbol name, *untyped args) ?{ (*untyped) -> untyped } -> untyped
-    def self.respond_to_missing?: (Symbol name, bool include_private) -> bool
+    # 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
+  end
 
-    private
+  # Section class for abstraction layers (inherits from Task)
+  class Section < Task
+    def self.interfaces: (*Symbol interface_methods) -> void
+
+    def run: () -> void
+    def impl: () -> task_class
 
-    # Private class methods for dependency resolution
-    def self.resolve_queue: (Array[Class] queue, Array[Class] resolved) -> Array[Class]
-    def self.detect_circular_dependencies: (Array[Class] queue, Array[Class] resolved) -> void
-    def self.build_instance: (Class task_class) -> void
+    private
 
-    # Private class methods for Define API
-    def self.create_defined_method: (Symbol name) { () -> untyped } -> void
-    def self.create_ref_method_if_needed: () -> void
-    def self.method_defined_for_define?: (Symbol method_name) -> bool
-    def self.mark_method_as_defined: (Symbol method_name) -> void
+    def apply_interface_to_implementation: (task_class implementation_class) -> void
   end
 
-  # Dependency analyzer module
-  module DependencyAnalyzer
-    def self.analyze_method: (Class klass, Symbol method_name) -> Array[Class]
+  # Execution module
+  module Execution
+    # TaskTiming struct (Data.define)
+    class TaskTiming
+      attr_reader start_time: Time
+      attr_reader end_time: Time?
 
-    # Task dependency visitor for AST analysis
-    class TaskDependencyVisitor < Prism::Visitor
-      @dependencies: Array[Class]
+      # Data.define provides both positional and keyword argument constructors
+      def initialize: (Time start_time, Time? end_time) -> void
+                    | (start_time: Time, end_time: Time?) -> void
+
+      def self.new: (Time start_time, Time? end_time) -> TaskTiming
+                  | (start_time: Time, end_time: Time?) -> TaskTiming
+
+      def self.start_now: () -> TaskTiming
+      def duration_ms: () -> (Integer | Float)?
+      def with_end_now: () -> TaskTiming
+      def with: (?start_time: Time, ?end_time: Time?) -> TaskTiming
+    end
+
+    # Registry class for task instance management
+    class Registry
+      @tasks: Hash[Class, TaskWrapper]
+      @threads: Array[Thread]
+      @monitor: Monitor
+      @abort_requested: bool
 
       def initialize: () -> void
-      def dependencies: () -> Array[Class]
-      def visit_call_node: (Prism::CallNode node) -> void
+      def get_or_create: (Class task_class) { () -> TaskWrapper } -> TaskWrapper
+      def get_task: (Class task_class) -> TaskWrapper
+      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
+    end
+
+    # Coordinator class for dependency management
+    class Coordinator
+      @registry: Registry
+      @analyzer: singleton(StaticAnalysis::Analyzer)
+
+      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]
 
       private
 
-      def extract_class_from_constant: (String constant_name) -> Class?
-      def safe_constantize: (String name) -> Class?
-      def extract_class_from_ref_call: (Prism::CallNode node) -> Class?
+      def start_thread_with: () { () -> void } -> void
+      def start_dependency_execution: (task_class dep_class) -> void
+      def start_dependency_clean: (task_class dep_class) -> void
     end
 
-    private
+    # TaskWrapper class for task execution
+    class TaskWrapper
+      attr_reader task: Task
+      attr_reader result: untyped
+
+      @task: Task
+      @registry: Registry
+      @coordinator: Coordinator
+      @result: untyped
+      @clean_result: untyped
+      @error: StandardError?
+      @monitor: Monitor
+      @condition: MonitorMixin::ConditionVariable
+      @clean_condition: MonitorMixin::ConditionVariable
+      @state: Symbol
+      @clean_state: Symbol
+      @timing: TaskTiming?
+
+      STATE_PENDING: Symbol
+      STATE_RUNNING: Symbol
+      STATE_COMPLETED: Symbol
+
+      def initialize: (Task task, registry: Registry, coordinator: Coordinator) -> void
+      def run: () -> untyped
+      def clean: () -> void
+      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 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
+    end
+
+    # ParallelProgressDisplay class for progress visualization
+    class ParallelProgressDisplay
+      SPINNER_FRAMES: Array[String]
+
+      @output: IO
+      @tasks: Hash[Class, TaskProgress]
+      @monitor: Monitor
+      @spinner_index: Integer
+      @renderer_thread: Thread?
+      @running: bool
 
-    def self.parse_method_code: (Class klass, Symbol method_name) -> Prism::ParseResult?
-    def self.extract_dependencies_from_ast: (Prism::Node ast) -> Array[Class]
+      class TaskProgress
+        attr_accessor state: Symbol
+        attr_accessor start_time: Time?
+        attr_accessor end_time: Time?
+        attr_accessor error: Exception?
+        attr_accessor duration: Numeric?
+
+        def initialize: () -> void
+      end
+
+      def initialize: (?output: IO) -> 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 render_live: () -> void
+      def render_final: () -> void
+      def format_task_line: (Class task_class, TaskProgress progress) -> String
+      def task_icon: (Symbol state) -> String
+      def spinner_char: () -> String
+      def task_details: (TaskProgress progress) -> String
+    end
+  end
+
+  # StaticAnalysis module
+  module StaticAnalysis
+    # Analyzer class for dependency analysis
+    class Analyzer
+      def self.analyze: (Class task_class) -> Set[task_class]
+
+      private
+
+      def self.extract_run_method_location: (Class task_class) -> [String, Integer]?
+    end
+
+    # Visitor class for AST traversal
+    class Visitor < Prism::Visitor
+      @target_task_class: Class
+      @dependencies: Set[task_class]
+      @in_target_run_method: bool
+      @current_namespace_path: Array[String?]
+
+      attr_reader dependencies: Set[task_class]
+
+      def initialize: (Class task_class) -> 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
+      def visit_call_node: (Prism::CallNode node) -> untyped
+
+      private
+
+      def within_namespace: (String? name) { () -> void } -> void
+      def in_target_class?: () -> bool
+      def extract_constant_name: (untyped node) -> String?
+      def detect_task_dependency: (Prism::CallNode 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?
+      def resolve_with_namespace_prefix: (String name) -> task_class?
+      def valid_dependency?: (task_class klass) -> bool
+      def is_parallel_task?: (task_class klass) -> boolish
+      def is_parallel_section?: (task_class klass) -> boolish
+    end
+
+    # DependencyGraph class for topological sorting and cycle detection
+    class DependencyGraph
+      include TSort[Class]
+
+      @graph: Hash[Class, Set[Class]]
+
+      def initialize: () -> void
+      def build_from: (Class root_task_class) -> self
+      def sorted: () -> Array[Class]
+      def cyclic?: () -> bool
+      def strongly_connected_components: () -> Array[Array[Class]]
+      def cyclic_components: () -> Array[Array[Class]]
+      def all_tasks: () -> Array[Class]
+      def dependencies_for: (Class task) -> Set[Class]
+
+      # TSort interface methods (required by TSort module)
+      def tsort_each_node: () { (Class) -> void } -> void
+      def tsort_each_child: (Class node) { (Class) -> void } -> void
+
+      private
+
+      def collect_dependencies: (Class task_class) -> void
+    end
   end
-end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: taski
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.1
 platform: ruby
 authors:
 - ahogappa
@@ -23,6 +23,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: tsort
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Taski is a Ruby-based task runner currently under development. It allows
   you to define small, composable tasks along with the outputs they depend on. Taski
   statically resolves dependencies and executes tasks in the correct topological order,
@@ -39,41 +53,31 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- Steepfile
+- docs/advanced-features.md
+- docs/api-guide.md
+- docs/error-handling.md
 - examples/README.md
-- examples/advanced_patterns.rb
-- examples/progress_demo.rb
+- examples/context_demo.rb
+- examples/data_pipeline_demo.rb
+- examples/parallel_progress_demo.rb
 - examples/quick_start.rb
-- examples/section_configuration.rb
-- examples/tree_demo.rb
+- examples/reexecution_demo.rb
+- examples/section_demo.rb
 - lib/taski.rb
-- lib/taski/dependency_analyzer.rb
-- lib/taski/exceptions.rb
-- lib/taski/logger.rb
-- lib/taski/logging/formatter_factory.rb
-- lib/taski/logging/formatter_interface.rb
-- lib/taski/logging/json_formatter.rb
-- lib/taski/logging/simple_formatter.rb
-- lib/taski/logging/structured_formatter.rb
-- lib/taski/progress/display_colors.rb
-- lib/taski/progress/display_manager.rb
-- lib/taski/progress/output_capture.rb
-- lib/taski/progress/spinner_animation.rb
-- lib/taski/progress/task_formatter.rb
-- lib/taski/progress/task_status.rb
-- lib/taski/progress/terminal_controller.rb
-- lib/taski/progress_display.rb
-- lib/taski/reference.rb
+- lib/taski/context.rb
+- lib/taski/execution/coordinator.rb
+- lib/taski/execution/parallel_progress_display.rb
+- lib/taski/execution/registry.rb
+- lib/taski/execution/task_wrapper.rb
 - lib/taski/section.rb
-- lib/taski/task/base.rb
-- lib/taski/task/define_api.rb
-- lib/taski/task/dependency_resolver.rb
-- lib/taski/task/exports_api.rb
-- lib/taski/task/instance_management.rb
-- lib/taski/tree_colors.rb
-- lib/taski/utils.rb
-- lib/taski/utils/dependency_resolver_helper.rb
-- lib/taski/utils/tree_display_helper.rb
+- lib/taski/static_analysis/analyzer.rb
+- lib/taski/static_analysis/dependency_graph.rb
+- lib/taski/static_analysis/visitor.rb
+- lib/taski/task.rb
 - lib/taski/version.rb
+- rbs_collection.lock.yaml
+- rbs_collection.yaml
 - sig/taski.rbs
 homepage: https://github.com/ahogappa/taski
 licenses: []
@@ -95,7 +99,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A simple yet powerful Ruby task runner with static dependency resolution
   (in development).

data/examples/advanced_patterns.rb

@@ -1,119 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-# Taski Advanced Patterns
-#
-# This example demonstrates advanced Taski patterns:
-# - Mixed usage of Exports API and Define API
-# - Environment-specific dependency resolution
-# - Feature flag integration with dynamic dependencies
-# - Task reset and rebuild scenarios
-# - Conditional dependency evaluation
-#
-# Run: ruby examples/advanced_patterns.rb
-
-require_relative "../lib/taski"
-
-puts "⚡ Advanced Taski Patterns"
-puts "=" * 40
-
-# Mock classes for the example
-class ProductionDB < Taski::Task
-  exports :connection_string
-  def build
-    @connection_string = "postgres://prod-server/app"
-  end
-end
-
-class TestDB < Taski::Task
-  exports :connection_string
-  def build
-    @connection_string = "postgres://test-server/app_test"
-  end
-end
-
-module FeatureFlag
-  def self.enabled?(flag)
-    ENV["FEATURE_#{flag.to_s.upcase}"] == "true"
-  end
-end
-
-class RedisService < Taski::Task
-  exports :configuration
-  def build
-    @configuration = "redis://localhost:6379"
-  end
-end
-
-# Environment configuration using Define API
-class Environment < Taski::Task
-  define :database_url, -> {
-    case ENV["RAILS_ENV"]
-    when "production"
-      ProductionDB.connection_string
-    when "test"
-      TestDB.connection_string
-    else
-      "sqlite3://development.db"
-    end
-  }
-
-  define :redis_config, -> {
-    if FeatureFlag.enabled?(:redis_cache)
-      RedisService.configuration
-    end
-  }
-
-  def build
-    # Environment configuration is handled by define blocks
-  end
-end
-
-# Static configuration using Exports API
-class AppConfig < Taski::Task
-  exports :app_name, :version, :port
-
-  def build
-    @app_name = "MyWebApp"
-    @version = "2.1.0"
-    @port = ENV.fetch("PORT", 3000).to_i
-  end
-end
-
-# Application startup combining both APIs
-class Application < Taski::Task
-  def build
-    puts "Starting #{AppConfig.app_name} v#{AppConfig.version}"
-    puts "Database: #{Environment.database_url}"
-    puts "Redis: #{Environment.redis_config || "disabled"}"
-    puts "Port: #{AppConfig.port}"
-  end
-
-  def clean
-    puts "Shutting down #{AppConfig.app_name}..."
-  end
-end
-
-# Test different environments
-puts "\n1. Development Environment (default):"
-ENV.delete("RAILS_ENV")
-ENV.delete("FEATURE_REDIS_CACHE")
-Application.build
-Application.reset!
-
-puts "\n2. Test Environment:"
-ENV["RAILS_ENV"] = "test"
-# Reset Environment to re-evaluate define blocks
-Environment.reset!
-Application.build
-Application.reset!
-
-puts "\n3. Production with Redis:"
-ENV["RAILS_ENV"] = "production"
-ENV["FEATURE_REDIS_CACHE"] = "true"
-# Reset Environment to re-evaluate define blocks
-Environment.reset!
-Application.build
-
-puts "\n4. Cleanup:"
-Application.clean