taski 0.1.0 → 0.2.0

data/lib/taski/dependency_analyzer.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require 'prism'
+
+module Taski
+  module DependencyAnalyzer
+    class << self
+      def analyze_method(klass, method_name)
+        return [] unless klass.instance_methods(false).include?(method_name)
+
+        method = klass.instance_method(method_name)
+        source_location = method.source_location
+        return [] unless source_location
+
+        file_path, line_number = source_location
+        return [] unless File.exist?(file_path)
+
+        begin
+          result = Prism.parse_file(file_path)
+
+          unless result.success?
+            warn "Taski: Parse errors in #{file_path}: #{result.errors.map(&:message).join(', ')}"
+            return []
+          end
+
+          # Handle warnings if present
+          if result.warnings.any?
+            warn "Taski: Parse warnings in #{file_path}: #{result.warnings.map(&:message).join(', ')}"
+          end
+
+          dependencies = []
+          method_node = find_method_node(result.value, method_name, line_number)
+
+          if method_node
+            visitor = TaskDependencyVisitor.new
+            visitor.visit(method_node)
+            dependencies = visitor.dependencies
+          end
+
+          dependencies.uniq
+        rescue IOError, SystemCallError => e
+          warn "Taski: Failed to read file #{file_path}: #{e.message}"
+          []
+        rescue => e
+          warn "Taski: Failed to analyze method #{klass}##{method_name}: #{e.message}"
+          []
+        end
+      end
+
+      private
+
+      def find_method_node(node, method_name, target_line)
+        return nil unless node
+
+        case node
+        when Prism::DefNode
+          if node.name == method_name && node.location.start_line <= target_line && node.location.end_line >= target_line
+            return node
+          end
+        when Prism::ClassNode, Prism::ModuleNode
+          if node.respond_to?(:body)
+            return find_method_node(node.body, method_name, target_line)
+          end
+        when Prism::StatementsNode
+          node.body.each do |child|
+            result = find_method_node(child, method_name, target_line)
+            return result if result
+          end
+        end
+
+        # Recursively search child nodes
+        if node.respond_to?(:child_nodes)
+          node.child_nodes.each do |child|
+            result = find_method_node(child, method_name, target_line)
+            return result if result
+          end
+        end
+
+        nil
+      end
+
+      # Task dependency visitor using Prism's visitor pattern
+      class TaskDependencyVisitor < Prism::Visitor
+        attr_reader :dependencies
+
+        def initialize
+          @dependencies = []
+          @constant_cache = {}
+        end
+
+        def visit_constant_read_node(node)
+          check_task_constant(node.name.to_s)
+          super
+        end
+
+        def visit_constant_path_node(node)
+          const_path = extract_constant_path(node)
+          check_task_constant(const_path) if const_path
+          super
+        end
+
+        def visit_call_node(node)
+          # Check for method calls on constants (e.g., TaskA.result)
+          case node.receiver
+          when Prism::ConstantReadNode
+            check_task_constant(node.receiver.name.to_s)
+          when Prism::ConstantPathNode
+            const_path = extract_constant_path(node.receiver)
+            check_task_constant(const_path) if const_path
+          end
+          super
+        end
+
+        private
+
+        def check_task_constant(const_name)
+          return unless const_name
+
+          # Use caching to avoid repeated constant resolution
+          cached_result = @constant_cache[const_name]
+          return cached_result if cached_result == false # Cached negative result
+          return @dependencies << cached_result if cached_result # Cached positive result
+
+          begin
+            if Object.const_defined?(const_name)
+              klass = Object.const_get(const_name)
+              if klass.is_a?(Class) && klass < Taski::Task
+                @constant_cache[const_name] = klass
+                @dependencies << klass
+              else
+                @constant_cache[const_name] = false
+              end
+            else
+              @constant_cache[const_name] = false
+            end
+          rescue NameError, ArgumentError
+            @constant_cache[const_name] = false
+          end
+        end
+
+        def extract_constant_path(node)
+          case node
+          when Prism::ConstantReadNode
+            node.name.to_s
+          when Prism::ConstantPathNode
+            parent_path = extract_constant_path(node.parent) if node.parent
+            child_name = node.name.to_s
+
+            if parent_path && child_name
+              "#{parent_path}::#{child_name}"
+            else
+              child_name
+            end
+          else
+            nil
+          end
+        end
+      end
+
+    end
+  end
+end

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.0"
+  VERSION = "0.2.0"
 end