taski 0.2.0 → 0.2.2

data/lib/taski/task/instance_management.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'monitor'
+require "monitor"
 
 module Taski
   class Task
@@ -8,9 +8,19 @@ module Taski
       # === Lifecycle Management ===
 
       # Build this task and all its dependencies
-      def build
-        resolve_dependencies.reverse.each do |task_class|
-          task_class.ensure_instance_built
+      # @param args [Hash] Optional arguments for parametrized builds
+      # @return [Task] Returns task instance (singleton or temporary)
+      def build(**args)
+        if args.empty?
+          # Traditional build: singleton instance with caching
+          resolve_dependencies.reverse_each do |task_class|
+            task_class.ensure_instance_built
+          end
+          # Return the singleton instance for consistency
+          instance_variable_get(:@__task_instance)
+        else
+          # Parametrized build: temporary instance without caching
+          build_with_args(args)
         end
       end
 
@@ -41,6 +51,32 @@ module Taski
         reset!
       end
 
+      # === Parametrized Build Support ===
+
+      # Build temporary instance with arguments
+      # @param args [Hash] Build arguments
+      # @return [Task] Temporary task instance
+      def build_with_args(args)
+        # Resolve dependencies first (same as normal build)
+        resolve_dependencies.reverse_each do |task_class|
+          task_class.ensure_instance_built
+        end
+
+        # Create temporary instance with arguments
+        temp_instance = new
+        temp_instance.instance_variable_set(:@build_args, args)
+
+        # Build with logging using common utility
+        Utils::TaskBuildHelpers.with_build_logging(name.to_s,
+          dependencies: @dependencies || [],
+          args: args) do
+          temp_instance.build
+          temp_instance
+        end
+      end
+
+      private :build_with_args
+
       # === Instance Management ===
 
       # Ensure task instance is built (public because called from build)
@@ -56,7 +92,9 @@ module Taski
           # Prevent infinite recursion using thread-local storage
           thread_key = build_thread_key
           if Thread.current[thread_key]
-            raise CircularDependencyError, "Circular dependency detected: #{self.name} is already being built"
+            # Build dependency path for better error message
+            cycle_path = build_current_dependency_path
+            raise CircularDependencyError, build_runtime_circular_dependency_message(cycle_path)
           end
 
           Thread.current[thread_key] = true
@@ -84,21 +122,17 @@ module Taski
       # Generate thread key for recursion detection
       # @return [String] Thread key for this task
       def build_thread_key
-        "#{self.name}#{THREAD_KEY_SUFFIX}"
+        "#{name}#{THREAD_KEY_SUFFIX}"
       end
 
       # Build and configure task instance
       # @return [Task] Built task instance
       def build_instance
-        instance = self.new
-        begin
+        instance = new
+        Utils::TaskBuildHelpers.with_build_logging(name.to_s,
+          dependencies: @dependencies || []) do
           instance.build
           instance
-        rescue => e
-          # Log the error but don't let it crash the entire system
-          warn "Taski: Failed to build #{self.name}: #{e.message}"
-          warn "Taski: #{e.backtrace.first}" if e.backtrace
-          raise TaskBuildError, "Failed to build task #{self.name}: #{e.message}"
         end
       end
 
@@ -123,13 +157,34 @@ module Taski
         end
       end
 
-      # Extract class from dependency hash
-      # @param dep [Hash] Dependency information
-      # @return [Class] The dependency class
-      def extract_class(dep)
-        klass = dep[:klass]
-        klass.is_a?(Reference) ? klass.deref : klass
+      private
+
+      # Build current dependency path from thread-local storage
+      # @return [Array<Class>] Array of classes in the current build path
+      def build_current_dependency_path
+        path = []
+        Thread.current.keys.each do |key|
+          if key.to_s.end_with?(THREAD_KEY_SUFFIX) && Thread.current[key]
+            class_name = key.to_s.sub(THREAD_KEY_SUFFIX, "")
+            begin
+              path << Object.const_get(class_name)
+            rescue NameError
+              # Skip if class not found
+            end
+          end
+        end
+        path << self
+      end
+
+      # Build runtime circular dependency error message
+      # @param cycle_path [Array<Class>] The circular dependency path
+      # @return [String] Formatted error message
+      def build_runtime_circular_dependency_message(cycle_path)
+        Utils::CircularDependencyHelpers.build_error_message(cycle_path, "runtime")
       end
+
+      include Utils::DependencyUtils
+      private :extract_class
     end
   end
-end
+end

data/lib/taski/utils.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Taski
+  # Common utility functions for the Taski framework
+  module Utils
+    # Handle circular dependency error message generation
+    module CircularDependencyHelpers
+      # Build detailed error message for circular dependencies
+      # @param cycle_path [Array<Class>] The circular dependency path
+      # @param context [String] Context of the error (dependency, runtime)
+      # @return [String] Formatted error message
+      def self.build_error_message(cycle_path, context = "dependency")
+        path_names = cycle_path.map { |klass| klass.name || klass.to_s }
+
+        message = "Circular dependency detected!\n"
+        message += "Cycle: #{path_names.join(" → ")}\n\n"
+        message += "The #{context} chain is:\n"
+
+        cycle_path.each_cons(2).with_index do |(from, to), index|
+          action = (context == "dependency") ? "depends on" : "is trying to build"
+          message += "  #{index + 1}. #{from.name} #{action} → #{to.name}\n"
+        end
+
+        message += "\nThis creates an infinite loop that cannot be resolved." if context == "dependency"
+        message
+      end
+    end
+
+    # Common dependency utility functions
+    module DependencyUtils
+      # Extract class from dependency hash
+      # @param dep [Hash] Dependency information
+      # @return [Class] The dependency class
+      def extract_class(dep)
+        klass = dep[:klass]
+        klass.is_a?(Reference) ? klass.deref : klass
+      end
+    end
+
+    # Common task build utility functions
+    module TaskBuildHelpers
+      # Format arguments hash for display in error messages
+      # @param args [Hash] Arguments hash
+      # @return [String] Formatted arguments string
+      def self.format_args(args)
+        return "" if args.nil? || args.empty?
+
+        formatted_pairs = args.map do |key, value|
+          "#{key}: #{value.inspect}"
+        end
+        "{#{formatted_pairs.join(", ")}}"
+      end
+
+      # Execute block with comprehensive build logging and progress display
+      # @param task_name [String] Name of the task being built
+      # @param dependencies [Array] List of dependencies
+      # @param args [Hash] Build arguments for parametrized builds
+      # @yield Block to execute with logging
+      # @return [Object] Result of the block execution
+      def self.with_build_logging(task_name, dependencies: [], args: nil)
+        build_start_time = Time.now
+
+        begin
+          # Traditional logging first (before any stdout redirection)
+          Taski.logger.task_build_start(task_name, dependencies: dependencies, args: args)
+
+          # Show progress display if enabled (this may redirect stdout)
+          Taski.progress_display&.start_task(task_name, dependencies: dependencies)
+
+          result = yield
+          duration = Time.now - build_start_time
+
+          # Complete progress display first (this restores stdout)
+          Taski.progress_display&.complete_task(task_name, duration: duration)
+
+          # Then do logging (on restored stdout)
+          begin
+            Taski.logger.task_build_complete(task_name, duration: duration)
+          rescue IOError
+            # If logger fails due to closed stream, write to STDERR instead
+            warn "[#{Time.now.strftime("%Y-%m-%d %H:%M:%S.%3N")}] INFO  Taski: Task build completed (task=#{task_name}, duration_ms=#{(duration * 1000).round(2)})"
+          end
+
+          result
+        rescue => e
+          duration = Time.now - build_start_time
+
+          # Complete progress display first (with error)
+          Taski.progress_display&.fail_task(task_name, error: e, duration: duration)
+
+          # Then do error logging (on restored stdout)
+          begin
+            Taski.logger.task_build_failed(task_name, error: e, duration: duration)
+          rescue IOError
+            # If logger fails due to closed stream, write to STDERR instead
+            warn "[#{Time.now.strftime("%Y-%m-%d %H:%M:%S.%3N")}] ERROR Taski: Task build failed (task=#{task_name}, error=#{e.message}, duration_ms=#{(duration * 1000).round(2)})"
+          end
+
+          error_message = "Failed to build task #{task_name}"
+          error_message += " with args #{format_args(args)}" if args && !args.empty?
+          error_message += ": #{e.message}"
+          raise TaskBuildError, error_message
+        end
+      end
+    end
+  end
+end

data/lib/taski/version.rb

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

data/lib/taski.rb

@@ -1,13 +1,15 @@
 # frozen_string_literal: true
 
-require 'set'
-require 'monitor'
+require "monitor"
 
 # Load core components
 require_relative "taski/version"
 require_relative "taski/exceptions"
+require_relative "taski/logger"
+require_relative "taski/progress_display"
 require_relative "taski/reference"
 require_relative "taski/dependency_analyzer"
+require_relative "taski/utils"
 
 # Load Task class components
 require_relative "taski/task/base"
@@ -18,7 +20,7 @@ require_relative "taski/task/dependency_resolver"
 
 module Taski
   # Main module for the Taski task framework
-  # 
+  #
   # Taski provides a framework for defining and managing task dependencies
   # with two complementary APIs:
   # 1. Exports API - Export instance variables as class methods (static dependencies)
@@ -26,7 +28,7 @@ module Taski
   #
   # Use Define API when:
   # - Dependencies change based on runtime conditions
-  # - Environment-specific configurations  
+  # - Environment-specific configurations
   # - Feature flags determine which classes to use
   # - Complex conditional logic determines dependencies
   #
@@ -37,4 +39,4 @@ module Taski
   # - Thread-safe task building
   # - Circular dependency detection
   # - Memory leak prevention
-end
+end

data/sig/taski.rbs

@@ -33,15 +33,19 @@ module Taski
 
     # Public API methods
     def self.exports: (*Symbol names) -> void
-    def self.define: (Symbol name, Proc block, **untyped options) -> void
+    def self.define: (Symbol name) { () -> untyped } -> void
     def self.build: () -> void
     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 klass) -> Reference
+    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
+
     # Instance methods
     def build: () -> void
     def clean: () -> void
@@ -53,10 +57,43 @@ module Taski
     # 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
+
+    # 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 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
   end
 
   # Dependency analyzer module
   module DependencyAnalyzer
     def self.analyze_method: (Class klass, Symbol method_name) -> Array[Class]
+
+    # Task dependency visitor for AST analysis
+    class TaskDependencyVisitor < Prism::Visitor
+      @dependencies: Array[Class]
+
+      def initialize: () -> void
+      def dependencies: () -> Array[Class]
+      def visit_call_node: (Prism::CallNode node) -> void
+
+      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?
+    end
+
+    private
+
+    def self.parse_method_code: (Class klass, Symbol method_name) -> Prism::ParseResult?
+    def self.extract_dependencies_from_ast: (Prism::Node ast) -> Array[Class]
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: taski
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
 - ahogappa
 bindir: exe
 cert_chain: []
-date: 2025-06-15 00:00:00.000000000 Z
+date: 2025-06-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: prism
@@ -35,21 +35,27 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".standard.yml"
 - LICENSE
 - README.md
 - Rakefile
-- Steepfile
-- examples/complex_example.rb
-- examples/readme_example.rb
+- examples/README.md
+- examples/advanced_patterns.rb
+- examples/progress_demo.rb
+- examples/quick_start.rb
+- examples/tree_demo.rb
 - lib/taski.rb
 - lib/taski/dependency_analyzer.rb
 - lib/taski/exceptions.rb
+- lib/taski/logger.rb
+- lib/taski/progress_display.rb
 - lib/taski/reference.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/utils.rb
 - lib/taski/version.rb
 - sig/taski.rbs
 homepage: https://github.com/ahogappa/taski
@@ -65,7 +71,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/Steepfile

@@ -1,20 +0,0 @@
-# Steepfile
-
-D = Steep::Diagnostic
-
-target :lib do
-  signature "sig"
-
-  check "lib"
-
-  library "monitor", "prism"
-
-  # Configure diagnostics with lenient settings for metaprogramming-heavy code
-  configure_code_diagnostics do |hash|
-    hash[D::Ruby::UnannotatedEmptyCollection] = :information
-    hash[D::Ruby::UnknownInstanceVariable] = :information
-    hash[D::Ruby::FallbackAny] = :information
-    hash[D::Ruby::NoMethod] = :warning
-    hash[D::Ruby::UndeclaredMethodDefinition] = :information
-  end
-end