taski 0.2.0 → 0.2.1

data/lib/taski/logger.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+module Taski
+  # Enhanced logging functionality for Taski framework
+  # Provides structured logging with multiple levels and context information
+  class Logger
+    # Log levels in order of severity
+    LEVELS = {debug: 0, info: 1, warn: 2, error: 3}.freeze
+
+    # @param level [Symbol] Minimum log level to output (:debug, :info, :warn, :error)
+    # @param output [IO] Output destination (default: $stdout)
+    # @param format [Symbol] Log format (:simple, :structured, :json)
+    def initialize(level: :info, output: $stdout, format: :structured)
+      @level = level
+      @output = output
+      @format = format
+      @start_time = Time.now
+    end
+
+    # Log debug message with optional context
+    # @param message [String] Log message
+    # @param context [Hash] Additional context information
+    def debug(message, **context)
+      log(:debug, message, context)
+    end
+
+    # Log info message with optional context
+    # @param message [String] Log message
+    # @param context [Hash] Additional context information
+    def info(message, **context)
+      log(:info, message, context)
+    end
+
+    # Log warning message with optional context
+    # @param message [String] Log message
+    # @param context [Hash] Additional context information
+    def warn(message, **context)
+      log(:warn, message, context)
+    end
+
+    # Log error message with optional context
+    # @param message [String] Log message
+    # @param context [Hash] Additional context information
+    def error(message, **context)
+      log(:error, message, context)
+    end
+
+    # Log task build start event
+    # @param task_name [String] Name of the task being built
+    # @param dependencies [Array] List of task dependencies
+    def task_build_start(task_name, dependencies: [])
+      info("Task build started",
+        task: task_name,
+        dependencies: dependencies.size,
+        dependency_names: dependencies.map { |dep| dep.is_a?(Hash) ? dep[:klass].inspect : dep.inspect })
+    end
+
+    # Log task build completion event
+    # @param task_name [String] Name of the task that was built
+    # @param duration [Float] Build duration in seconds
+    def task_build_complete(task_name, duration: nil)
+      context = {task: task_name}
+      context[:duration_ms] = (duration * 1000).round(2) if duration
+      info("Task build completed", **context)
+    end
+
+    # Log task build failure event
+    # @param task_name [String] Name of the task that failed
+    # @param error [Exception] The error that occurred
+    # @param duration [Float] Duration before failure in seconds
+    def task_build_failed(task_name, error:, duration: nil)
+      context = {
+        task: task_name,
+        error_class: error.class.name,
+        error_message: error.message
+      }
+      context[:duration_ms] = (duration * 1000).round(2) if duration
+      context[:backtrace] = error.backtrace&.first(3) if error.backtrace
+      error("Task build failed", **context)
+    end
+
+    # Log dependency resolution event
+    # @param task_name [String] Name of the task resolving dependencies
+    # @param resolved_count [Integer] Number of dependencies resolved
+    def dependency_resolved(task_name, resolved_count:)
+      debug("Dependencies resolved",
+        task: task_name,
+        resolved_dependencies: resolved_count)
+    end
+
+    # Log circular dependency detection
+    # @param cycle_path [Array] The circular dependency path
+    def circular_dependency_detected(cycle_path)
+      error("Circular dependency detected",
+        cycle: cycle_path.map { |klass| klass.name || klass.inspect },
+        cycle_length: cycle_path.size)
+    end
+
+    private
+
+    # Core logging method
+    # @param level [Symbol] Log level
+    # @param message [String] Log message
+    # @param context [Hash] Additional context
+    def log(level, message, context)
+      return unless should_log?(level)
+
+      case @format
+      when :simple
+        log_simple(level, message, context)
+      when :structured
+        log_structured(level, message, context)
+      when :json
+        log_json(level, message, context)
+      end
+    end
+
+    # Check if message should be logged based on current level
+    # @param level [Symbol] Message level to check
+    # @return [Boolean] True if message should be logged
+    def should_log?(level)
+      LEVELS[@level] <= LEVELS[level]
+    end
+
+    # Simple log format: [LEVEL] message
+    def log_simple(level, message, context)
+      @output.puts "[#{level.upcase}] #{message}"
+    end
+
+    # Structured log format with timestamp and context
+    def log_structured(level, message, context)
+      timestamp = Time.now.strftime("%Y-%m-%d %H:%M:%S.%3N")
+      elapsed = ((Time.now - @start_time) * 1000).round(1)
+
+      line = "[#{timestamp}] [#{elapsed}ms] #{level.to_s.upcase.ljust(5)} Taski: #{message}"
+
+      unless context.empty?
+        context_parts = context.map do |key, value|
+          "#{key}=#{format_value(value)}"
+        end
+        line += " (#{context_parts.join(", ")})"
+      end
+
+      @output.puts line
+    end
+
+    # JSON log format for structured logging systems
+    def log_json(level, message, context)
+      require "json"
+
+      log_entry = {
+        timestamp: Time.now.iso8601(3),
+        level: level.to_s,
+        logger: "taski",
+        message: message,
+        elapsed_ms: ((Time.now - @start_time) * 1000).round(1)
+      }.merge(context)
+
+      @output.puts JSON.generate(log_entry)
+    end
+
+    # Format values for structured logging
+    def format_value(value)
+      case value
+      when String
+        (value.length > 50) ? "#{value[0..47]}..." : value
+      when Array
+        (value.size > 5) ? "[#{value[0..4].join(", ")}, ...]" : value.inspect
+      when Hash
+        (value.size > 3) ? "{#{value.keys[0..2].join(", ")}, ...}" : value.inspect
+      else
+        value.inspect
+      end
+    end
+  end
+
+  class << self
+    # Get the current logger instance
+    # @return [Logger] Current logger instance
+    def logger
+      @logger ||= Logger.new
+    end
+
+    # Configure the logger with new settings
+    # @param level [Symbol] Log level (:debug, :info, :warn, :error)
+    # @param output [IO] Output destination
+    # @param format [Symbol] Log format (:simple, :structured, :json)
+    def configure_logger(level: :info, output: $stdout, format: :structured)
+      @logger = Logger.new(level: level, output: output, format: format)
+    end
+
+    # Set logger to quiet mode (only errors)
+    def quiet!
+      @logger = Logger.new(level: :error, output: @logger&.instance_variable_get(:@output) || $stdout)
+    end
+
+    # Set logger to verbose mode (all messages)
+    def verbose!
+      @logger = Logger.new(level: :debug, output: @logger&.instance_variable_get(:@output) || $stdout)
+    end
+  end
+end

data/lib/taski/reference.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
-require_relative 'exceptions'
+require_relative "exceptions"
 
 module Taski
   # Reference class for task references
-  # 
+  #
   # Used to create lazy references to task classes by name,
   # which is useful for dependency tracking and metaprogramming.
   class Reference
@@ -37,4 +37,4 @@ module Taski
       "&#{@klass}"
     end
   end
-end
+end

data/lib/taski/task/base.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
-require_relative '../exceptions'
+require_relative "../exceptions"
 
 module Taski
   # Base Task class that provides the foundation for task framework
   # This module contains the core constants and basic structure
   class Task
     # Constants for thread-local keys and method tracking
-    THREAD_KEY_SUFFIX = '_building'
+    THREAD_KEY_SUFFIX = "_building"
     TASKI_ANALYZING_DEFINE_KEY = :taski_analyzing_define
     ANALYZED_METHODS = [:build, :clean].freeze
 
@@ -57,4 +57,4 @@ module Taski
       # Default implementation does nothing
     end
   end
-end
+end

data/lib/taski/task/define_api.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'set'
-
 module Taski
   class Task
     class << self
@@ -18,6 +16,9 @@ module Taski
         @dependencies ||= []
         @definitions ||= {}
 
+        # Ensure ref method is defined first time define is called
+        create_ref_method_if_needed
+
         # Create method that tracks dependencies on first call
         create_tracking_method(name)
 
@@ -25,16 +26,25 @@ module Taski
         dependencies = analyze_define_dependencies(block)
 
         @dependencies += dependencies
-        @definitions[name] = { block:, options:, classes: dependencies }
+        @definitions[name] = {block:, options:, classes: dependencies}
       end
 
       private
 
       # === Define API Implementation ===
 
+      # Create ref method if needed to avoid redefinition warnings
+      def create_ref_method_if_needed
+        return if method_defined_for_define?(:ref)
+
+        define_singleton_method(:ref) { |klass| Object.const_get(klass) }
+        mark_method_as_defined(:ref)
+      end
+
       # Create method that tracks dependencies for define API
       # @param name [Symbol] Method name to create
       def create_tracking_method(name)
+        # Only create tracking method during dependency analysis
         class_eval(<<-RUBY, __FILE__, __LINE__ + 1)
           def self.#{name}
             __resolve__[__callee__] ||= false
@@ -65,7 +75,7 @@ module Taski
 
           break if klass.nil?
 
-          classes << { klass:, task: }
+          classes << {klass:, task:}
         end
 
         # Reset resolution state
@@ -90,6 +100,9 @@ module Taski
       # @param name [Symbol] Method name
       # @param definition [Hash] Method definition information
       def create_defined_method(name, definition)
+        # Remove tracking method first to avoid redefinition warnings
+        singleton_class.undef_method(name) if singleton_class.method_defined?(name)
+
         # Class method with lazy evaluation
         define_singleton_method(name) do
           @__defined_values ||= {}
@@ -101,7 +114,7 @@ module Taski
           @__defined_values ||= {}
           @__defined_values[name] ||= self.class.send(name)
         end
-        
+
         # Mark as defined for this resolution
         mark_method_as_defined(name)
       end
@@ -122,4 +135,4 @@ module Taski
       end
     end
   end
-end
+end

data/lib/taski/task/dependency_resolver.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
-require 'set'
-require_relative '../dependency_analyzer'
+require_relative "../dependency_analyzer"
 
 module Taski
   class Task
@@ -23,12 +22,6 @@ module Taski
           queue << task_class
         end
 
-        # Override ref method after resolution for define API compatibility
-        # Note: This may cause "method redefined" warnings, which is expected behavior
-        if (@definitions && !@definitions.empty?) && !method_defined_for_define?(:ref)
-          define_singleton_method(:ref) { |klass| Object.const_get(klass) }
-        end
-
         # Create getter methods for defined values
         create_defined_methods
 
@@ -42,6 +35,7 @@ module Taski
         resolved = []
         visited = Set.new
         resolving = Set.new  # Track currently resolving tasks
+        path_map = {self => []}  # Track paths to each task
 
         while queue.any?
           task_class = queue.shift
@@ -49,12 +43,26 @@ module Taski
 
           # Check for circular dependency
           if resolving.include?(task_class)
-            raise CircularDependencyError, "Circular dependency detected involving #{task_class.name}"
+            # Build error message with path information
+            cycle_path = build_cycle_path(task_class, path_map)
+            raise CircularDependencyError, build_circular_dependency_message(cycle_path)
           end
 
           resolving << task_class
           visited << task_class
+
+          # Store current path for dependencies
+          current_path = path_map[task_class] || []
+
+          # Let task resolve its dependencies
           task_class.resolve(queue, resolved)
+
+          # Track paths for each dependency
+          task_class.instance_variable_get(:@dependencies)&.each do |dep|
+            dep_class = extract_class(dep)
+            path_map[dep_class] = current_path + [task_class] unless path_map.key?(dep_class)
+          end
+
           resolving.delete(task_class)
           resolved << task_class unless resolved.include?(task_class)
         end
@@ -62,6 +70,31 @@ module Taski
         resolved
       end
 
+      private
+
+      # Build the cycle path from path tracking information
+      def build_cycle_path(task_class, path_map)
+        path = path_map[task_class] || []
+        path + [task_class]
+      end
+
+      # Build detailed error message for circular dependencies
+      def build_circular_dependency_message(cycle_path)
+        path_names = cycle_path.map { |klass| klass.name || klass.to_s }
+
+        message = "Circular dependency detected!\n"
+        message += "Cycle: #{path_names.join(" → ")}\n\n"
+        message += "Detailed dependency chain:\n"
+
+        cycle_path.each_cons(2).with_index do |(from, to), index|
+          message += "  #{index + 1}. #{from.name} depends on → #{to.name}\n"
+        end
+
+        message
+      end
+
+      public
+
       # === Static Analysis ===
 
       # Analyze dependencies when methods are defined
@@ -91,7 +124,7 @@ module Taski
       # @param dep_class [Class] Dependency class to add
       def add_dependency(dep_class)
         @dependencies ||= []
-        @dependencies << { klass: dep_class }
+        @dependencies << {klass: dep_class}
       end
 
       # Check if dependency already exists
@@ -102,4 +135,4 @@ module Taski
       end
     end
   end
-end
+end

data/lib/taski/task/exports_api.rb

@@ -28,4 +28,4 @@ module Taski
       end
     end
   end
-end
+end

data/lib/taski/task/instance_management.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'monitor'
+require "monitor"
 
 module Taski
   class Task
@@ -9,7 +9,7 @@ module Taski
 
       # Build this task and all its dependencies
       def build
-        resolve_dependencies.reverse.each do |task_class|
+        resolve_dependencies.reverse_each do |task_class|
           task_class.ensure_instance_built
         end
       end
@@ -56,7 +56,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 +86,25 @@ 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
+        instance = new
+        build_start_time = Time.now
         begin
+          Taski.logger.task_build_start(name.to_s, dependencies: @dependencies || [])
           instance.build
+          duration = Time.now - build_start_time
+          Taski.logger.task_build_complete(name.to_s, duration: duration)
           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}"
+          duration = Time.now - build_start_time
+          # Log the error with full context
+          Taski.logger.task_build_failed(name.to_s, error: e, duration: duration)
+          raise TaskBuildError, "Failed to build task #{name}: #{e.message}"
         end
       end
 
@@ -123,6 +129,41 @@ module Taski
         end
       end
 
+      # 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)
+        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 dependency chain is:\n"
+
+        cycle_path.each_cons(2).with_index do |(from, to), index|
+          message += "  #{index + 1}. #{from.name} is trying to build → #{to.name}\n"
+        end
+
+        message += "\nThis creates an infinite loop that cannot be resolved."
+        message
+      end
+
       # Extract class from dependency hash
       # @param dep [Hash] Dependency information
       # @return [Class] The dependency class
@@ -132,4 +173,4 @@ module Taski
       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.1"
 end

data/lib/taski.rb

@@ -1,11 +1,11 @@
 # 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/reference"
 require_relative "taski/dependency_analyzer"
 
@@ -18,7 +18,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 +26,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 +37,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.1
 platform: ruby
 authors:
 - ahogappa
 bindir: exe
 cert_chain: []
-date: 2025-06-15 00:00:00.000000000 Z
+date: 2025-06-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: prism
@@ -35,15 +35,16 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".standard.yml"
 - LICENSE
 - README.md
 - Rakefile
-- Steepfile
 - examples/complex_example.rb
 - examples/readme_example.rb
 - lib/taski.rb
 - lib/taski/dependency_analyzer.rb
 - lib/taski/exceptions.rb
+- lib/taski/logger.rb
 - lib/taski/reference.rb
 - lib/taski/task/base.rb
 - lib/taski/task/define_api.rb
@@ -65,7 +66,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:
   - - ">="