taski 0.1.1 → 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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+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
+    # @param klass [String] The name of the class to reference
+    def initialize(klass)
+      @klass = klass
+    end
+
+    # Dereference to get the actual class object
+    # @return [Class] The referenced class
+    # @raise [TaskAnalysisError] If the constant cannot be resolved
+    def deref
+      Object.const_get(@klass)
+    rescue NameError => e
+      raise TaskAnalysisError, "Cannot resolve constant '#{@klass}': #{e.message}"
+    end
+
+    # Compare reference with another object
+    # @param other [Object] Object to compare with
+    # @return [Boolean] True if the referenced class equals the other object
+    def ==(other)
+      Object.const_get(@klass) == other
+    rescue NameError
+      false
+    end
+
+    # String representation of the reference
+    # @return [String] Reference representation
+    def inspect
+      "&#{@klass}"
+    end
+  end
+end

data/lib/taski/task/base.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+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"
+    TASKI_ANALYZING_DEFINE_KEY = :taski_analyzing_define
+    ANALYZED_METHODS = [:build, :clean].freeze
+
+    class << self
+      # === Hook Methods ===
+
+      # Hook called when build/clean methods are defined
+      # This triggers static analysis of dependencies
+      def method_added(method_name)
+        super
+        return unless ANALYZED_METHODS.include?(method_name)
+        # Only call if the method is available (loaded by dependency_resolver)
+        analyze_dependencies_at_definition if respond_to?(:analyze_dependencies_at_definition, true)
+      end
+
+      # Create a reference to a task class (can be used anywhere)
+      # @param klass [String] The class name to reference
+      # @return [Reference] A reference object
+      def ref(klass)
+        reference = Reference.new(klass)
+        # If we're in a define context, throw for dependency tracking
+        if Thread.current[TASKI_ANALYZING_DEFINE_KEY]
+          reference.tap { |ref| throw :unresolved, ref }
+        else
+          reference
+        end
+      end
+
+      # Get or create resolution state for define API
+      # @return [Hash] Resolution state hash
+      def __resolve__
+        @__resolve__ ||= {}
+      end
+    end
+
+    # === Instance Methods ===
+
+    # Build method that must be implemented by subclasses
+    # @raise [NotImplementedError] If not implemented by subclass
+    def build
+      raise NotImplementedError, "You must implement the build method in your task class"
+    end
+
+    # Clean method with default empty implementation
+    # Subclasses can override this method to implement cleanup logic
+    def clean
+      # Default implementation does nothing
+    end
+  end
+end

data/lib/taski/task/define_api.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Taski
+  class Task
+    class << self
+      # === Define API ===
+      # Define lazy-evaluated values with dynamic dependency resolution
+
+      # Define a lazy-evaluated value using a block
+      # Use this API when dependencies change based on runtime conditions,
+      # environment-specific configurations, feature flags, or complex conditional logic
+      # @param name [Symbol] Name of the value
+      # @param block [Proc] Block that computes the value and determines dependencies at runtime
+      # @param options [Hash] Additional options
+      def define(name, block, **options)
+        @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)
+
+        # Analyze dependencies by executing the block
+        dependencies = analyze_define_dependencies(block)
+
+        @dependencies += 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
+            if __resolve__[__callee__]
+              # already resolved
+            else
+              __resolve__[__callee__] = true
+              throw :unresolved, [self, __callee__]
+            end
+          end
+        RUBY
+      end
+
+      # Analyze dependencies in define block
+      # @param block [Proc] Block to analyze
+      # @return [Array<Hash>] Array of dependency information
+      def analyze_define_dependencies(block)
+        classes = []
+
+        # Set flag to indicate we're analyzing define dependencies
+        Thread.current[TASKI_ANALYZING_DEFINE_KEY] = true
+
+        loop do
+          klass, task = catch(:unresolved) do
+            block.call
+            nil
+          end
+
+          break if klass.nil?
+
+          classes << {klass:, task:}
+        end
+
+        # Reset resolution state
+        classes.each do |task_class|
+          task_class[:klass].instance_variable_set(:@__resolve__, {})
+        end
+
+        classes
+      ensure
+        Thread.current[TASKI_ANALYZING_DEFINE_KEY] = false
+      end
+
+      # Create methods for values defined with define API
+      def create_defined_methods
+        @definitions ||= {}
+        @definitions.each do |name, definition|
+          create_defined_method(name, definition) unless method_defined_for_define?(name)
+        end
+      end
+
+      # Create a single defined method (both class and instance)
+      # @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 ||= {}
+          @__defined_values[name] ||= definition[:block].call
+        end
+
+        # Instance method that delegates to class method
+        define_method(name) do
+          @__defined_values ||= {}
+          @__defined_values[name] ||= self.class.send(name)
+        end
+
+        # Mark as defined for this resolution
+        mark_method_as_defined(name)
+      end
+
+      # Mark method as defined for this resolution cycle
+      # @param method_name [Symbol] Method name to mark
+      def mark_method_as_defined(method_name)
+        @__defined_for_resolve ||= Set.new
+        @__defined_for_resolve << method_name
+      end
+
+      # Check if method was already defined for define API
+      # @param method_name [Symbol] Method name to check
+      # @return [Boolean] True if already defined
+      def method_defined_for_define?(method_name)
+        @__defined_for_resolve ||= Set.new
+        @__defined_for_resolve.include?(method_name)
+      end
+    end
+  end
+end

data/lib/taski/task/dependency_resolver.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require_relative "../dependency_analyzer"
+
+module Taski
+  class Task
+    class << self
+      # === Dependency Resolution ===
+
+      # Resolve method for dependency graph (called by resolve_dependencies)
+      # @param queue [Array] Queue of tasks to process
+      # @param resolved [Array] Array of resolved tasks
+      # @return [self] Returns self for method chaining
+      def resolve(queue, resolved)
+        @dependencies ||= []
+
+        @dependencies.each do |task|
+          task_class = extract_class(task)
+
+          # Reorder in resolved list for correct priority
+          resolved.delete(task_class) if resolved.include?(task_class)
+          queue << task_class
+        end
+
+        # Create getter methods for defined values
+        create_defined_methods
+
+        self
+      end
+
+      # Resolve all dependencies in topological order with circular dependency detection
+      # @return [Array<Class>] Array of tasks in dependency order
+      def resolve_dependencies
+        queue = [self]
+        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
+          next if visited.include?(task_class)
+
+          # Check for circular dependency
+          if resolving.include?(task_class)
+            # 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
+
+        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
+      def analyze_dependencies_at_definition
+        dependencies = gather_static_dependencies
+        add_unique_dependencies(dependencies)
+      end
+
+      # Gather dependencies from build and clean methods
+      # @return [Array<Class>] Array of dependency classes
+      def gather_static_dependencies
+        build_deps = DependencyAnalyzer.analyze_method(self, :build)
+        clean_deps = DependencyAnalyzer.analyze_method(self, :clean)
+        (build_deps + clean_deps).uniq
+      end
+
+      # Add dependencies that don't already exist
+      # @param dep_classes [Array<Class>] Array of dependency classes
+      def add_unique_dependencies(dep_classes)
+        dep_classes.each do |dep_class|
+          next if dep_class == self || dependency_exists?(dep_class)
+          add_dependency(dep_class)
+        end
+      end
+
+      # Add a single dependency
+      # @param dep_class [Class] Dependency class to add
+      def add_dependency(dep_class)
+        @dependencies ||= []
+        @dependencies << {klass: dep_class}
+      end
+
+      # Check if dependency already exists
+      # @param dep_class [Class] Dependency class to check
+      # @return [Boolean] True if dependency exists
+      def dependency_exists?(dep_class)
+        (@dependencies || []).any? { |d| d[:klass] == dep_class }
+      end
+    end
+  end
+end

data/lib/taski/task/exports_api.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Taski
+  class Task
+    class << self
+      # === Exports API ===
+      # Export instance variables as class methods for static dependencies
+
+      # Export instance variables as both class and instance methods
+      # @param names [Array<Symbol>] Names of instance variables to export
+      def exports(*names)
+        @exports ||= []
+        @exports += names
+
+        names.each do |name|
+          next if respond_to?(name)
+
+          # Define class method to access exported value
+          define_singleton_method(name) do
+            ensure_instance_built.send(name)
+          end
+
+          # Define instance method getter
+          define_method(name) do
+            instance_variable_get("@#{name}")
+          end
+        end
+      end
+    end
+  end
+end