taski 0.1.1 → 0.2.0

data/lib/taski/exceptions.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Taski
+  # Custom exceptions for Taski framework
+  
+  # Raised when circular dependencies are detected between tasks
+  class CircularDependencyError < StandardError; end
+  
+  # Raised when task analysis fails (e.g., constant resolution errors)
+  class TaskAnalysisError < StandardError; end
+  
+  # Raised when task building fails during execution
+  class TaskBuildError < StandardError; 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,125 @@
+# frozen_string_literal: true
+
+require 'set'
+
+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 ||= {}
+
+        # 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 method that tracks dependencies for define API
+      # @param name [Symbol] Method name to create
+      def create_tracking_method(name)
+        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)
+        # 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,105 @@
+# frozen_string_literal: true
+
+require 'set'
+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
+
+        # 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
+
+        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
+
+        while queue.any?
+          task_class = queue.shift
+          next if visited.include?(task_class)
+
+          # Check for circular dependency
+          if resolving.include?(task_class)
+            raise CircularDependencyError, "Circular dependency detected involving #{task_class.name}"
+          end
+
+          resolving << task_class
+          visited << task_class
+          task_class.resolve(queue, resolved)
+          resolving.delete(task_class)
+          resolved << task_class unless resolved.include?(task_class)
+        end
+
+        resolved
+      end
+
+      # === 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

data/lib/taski/task/instance_management.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require 'monitor'
+
+module Taski
+  class Task
+    class << self
+      # === Lifecycle Management ===
+
+      # Build this task and all its dependencies
+      def build
+        resolve_dependencies.reverse.each do |task_class|
+          task_class.ensure_instance_built
+        end
+      end
+
+      # Clean this task and all its dependencies in reverse order
+      def clean
+        resolve_dependencies.each do |task_class|
+          # Get existing instance or create new one for cleaning
+          instance = task_class.instance_variable_get(:@__task_instance) || task_class.new
+          instance.clean
+        end
+      end
+
+      # Reset task instance and cached data to prevent memory leaks
+      # @return [self] Returns self for method chaining
+      def reset!
+        build_monitor.synchronize do
+          @__task_instance = nil
+          @__defined_values = nil
+          @__defined_for_resolve = nil
+          clear_thread_local_state
+        end
+        self
+      end
+
+      # Refresh task state (currently just resets)
+      # @return [self] Returns self for method chaining
+      def refresh
+        reset!
+      end
+
+      # === Instance Management ===
+
+      # Ensure task instance is built (public because called from build)
+      # @return [Task] The built task instance
+      def ensure_instance_built
+        # Use double-checked locking pattern for thread safety
+        return @__task_instance if @__task_instance
+
+        build_monitor.synchronize do
+          # Check again after acquiring lock
+          return @__task_instance if @__task_instance
+
+          # 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"
+          end
+
+          Thread.current[thread_key] = true
+          begin
+            build_dependencies
+            @__task_instance = build_instance
+          ensure
+            Thread.current[thread_key] = false
+          end
+        end
+
+        @__task_instance
+      end
+
+      private
+
+      # === Core Helper Methods ===
+
+      # Get or create build monitor for thread safety
+      # @return [Monitor] Thread-safe monitor object
+      def build_monitor
+        @__build_monitor ||= Monitor.new
+      end
+
+      # Generate thread key for recursion detection
+      # @return [String] Thread key for this task
+      def build_thread_key
+        "#{self.name}#{THREAD_KEY_SUFFIX}"
+      end
+
+      # Build and configure task instance
+      # @return [Task] Built task instance
+      def build_instance
+        instance = self.new
+        begin
+          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
+
+      # Clear thread-local state for this task
+      def clear_thread_local_state
+        Thread.current.keys.each do |key|
+          Thread.current[key] = nil if key.to_s.include?(build_thread_key)
+        end
+      end
+
+      # === Dependency Management ===
+
+      # Build all dependencies of this task
+      def build_dependencies
+        resolve_dependencies
+
+        (@dependencies || []).each do |dep|
+          dep_class = extract_class(dep)
+          next if dep_class == self
+
+          dep_class.ensure_instance_built if dep_class.respond_to?(:ensure_instance_built)
+        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
+      end
+    end
+  end
+end

data/lib/taski/version.rb

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

data/lib/taski.rb

@@ -1,143 +1,40 @@
 # frozen_string_literal: true
 
-require_relative "taski/version"
-
-module Taski
-  class Reference
-    def initialize(klass)
-      @klass = klass
-    end
-
-    def deref
-      Object.const_get(@klass)
-    end
-
-    def inspect
-      "&#{@klass}"
-    end
-  end
-
-  class Task
-    class << self
-      def ref(klass)
-        ref = Reference.new(klass)
-        throw :unresolved, ref
-      end
-
-      def define(name, block, **options)
-        @dependencies ||= []
-        @definitions ||= {}
-
-        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
-
-        classes = []
-        loop do
-          klass, task = catch(:unresolved) do
-            block.call
-            nil
-          end
-
-          if klass.nil?
-            classes.each do |task_class|
-              task_class[:klass].class_eval(<<-RUBY, __FILE__, __LINE__ + 1)
-                __resolve__ = {}
-              RUBY
-            end
-
-            break
-          else
-            classes << { klass:, task: }
-          end
-        end
-
-        @dependencies += classes
-        @definitions[name] = { block:, options:, classes: }
-      end
-
-      def build
-        resolve_dependencies.reverse.each do |task_class|
-          task_class.new.build
-        end
-      end
+require 'set'
+require 'monitor'
 
-      def clean
-        resolve_dependencies.each do |task_class|
-          task_class.new.clean
-        end
-      end
-
-      def refresh
-        # TODO
-      end
-
-      def resolve(queue, resolved)
-        @dependencies.each do |task|
-          if task[:klass].is_a?(Reference)
-            task[:klass].deref
-          else
-            task[:klass]
-          end => task_class
-
-          # increase priority
-          if resolved.include?(task_class)
-            resolved.delete(task_class)
-          end
-          queue << task_class
-        end
-
-        # override
-        class_eval(<<-RUBY, __FILE__, __LINE__ + 1)
-          def self.ref(klass)
-            Object.const_get(klass)
-          end
-        RUBY
-
-        @definitions.each do |name, (_block, _options)|
-          # override
-          class_eval(<<-RUBY, __FILE__, __LINE__ + 1)
-            def self.#{name}
-              @__#{name} ||= @definitions[:#{name}][:block].call
-            end
-          RUBY
-
-          define_method(name) do
-            unless instance_variable_defined?("@__#{name}")
-              instance_variable_set("@__#{name}", self.class.send(name))
-            end
-            instance_variable_get("@__#{name}")
-          end
-        end
-
-        self
-      end
-
-      private
-
-      def __resolve__
-        @__resolve__ ||= {}
-      end
-
-      def resolve_dependencies
-        queue = [self]
-        resolved = []
+# Load core components
+require_relative "taski/version"
+require_relative "taski/exceptions"
+require_relative "taski/reference"
+require_relative "taski/dependency_analyzer"
 
-        while queue.any?
-          resolved << task_class = queue.shift
-          task_class.resolve(queue, resolved)
-        end
+# Load Task class components
+require_relative "taski/task/base"
+require_relative "taski/task/exports_api"
+require_relative "taski/task/define_api"
+require_relative "taski/task/instance_management"
+require_relative "taski/task/dependency_resolver"
 
-        resolved
-      end
-    end
-  end
-end
+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)
+  # 2. Define API - Define lazy-evaluated values with dynamic dependency resolution
+  #
+  # Use Define API when:
+  # - Dependencies change based on runtime conditions
+  # - Environment-specific configurations  
+  # - Feature flags determine which classes to use
+  # - Complex conditional logic determines dependencies
+  #
+  # Features:
+  # - Automatic dependency resolution (static and dynamic)
+  # - Static analysis of method dependencies
+  # - Runtime dependency resolution for conditional logic
+  # - Thread-safe task building
+  # - Circular dependency detection
+  # - Memory leak prevention
+end