taski 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d04adfab160e07e101e7d6364796d5607a896010396950ee5d479824bb4c422e
-  data.tar.gz: aeb0ea3476853608c0ef77e80e907c79db7ea62c1aaead8a22d8232d7e4c13aa
+  metadata.gz: 8b66b9afd145af8c5a07839b1886212336ffbdcb935897a278afae10315162e8
+  data.tar.gz: 7f43e874932671c2a41adc776514022e7d44d9ec0018935e2bd2e7e4d4537543
 SHA512:
-  metadata.gz: b3201ee69bc45ae1e58569bf1a98647ff7e38adabf0d04334805fdbac816468d420b1d460113970e1fc9394e6f9e6ca2fe4c700e0c390b9032366a01690c7762
-  data.tar.gz: 81a9796f7234f8f66216b61b7ea676b40614bb8258b8a6d6a0244e5d016319ea1492f7817324e1669a6ede1eeaf3f0ad4d8b71fd210168022838f66047348bff
+  metadata.gz: 8175467340490afdd0e9f1d4ba5c2e3db257e7d4c62850f88a138676056ea140753e2c38042803dd46c6c071731245314c2b597af83eb8c237be28d20e998e60
+  data.tar.gz: d1695488ca402cdb18800bd4b8623c64ed3c681a5dd6039c651c117c99793045fa59cca85f82cde0fde311b0ada0d81b8a66ba4d8cbb9b576ebe00fe71e760cf

data/README.md

@@ -1,68 +1,333 @@
 # Taski
 
-**Taski** is a Ruby-based task runner designed for small, composable processing steps.
-In Taski, you define tasks as Ruby classes that expose named values through `define`. Dependencies between tasks are established automatically when one task references the result of another—no need for explicit dependency declarations.
+> **🚧 Development Status:** Taski is currently under active development and the API may change. Not yet recommended for production use.
 
-Tasks are executed in a topologically sorted order, ensuring that tasks are built only after their inputs are available. Reverse execution is also supported, making it easy to clean up intermediate files or revert changes after a build.
+**Taski** is a powerful Ruby framework for building task dependency graphs with automatic resolution and execution. It provides two complementary APIs for different use cases: static dependencies through exports and dynamic dependencies through define.
 
-> **🚧 Development Status:** Taski is currently under active development and the API may change.
+## 🎯 Key Features
 
-> **⚠️ Limitation:** Circular dependencies are **not** supported at this time.
+- **Automatic Dependency Resolution**: Dependencies are detected automatically through static analysis and runtime evaluation
+- **Two Complementary APIs**: Choose the right approach for your use case
+  - **Exports API**: For simple, static dependencies
+  - **Define API**: For complex, dynamic dependencies based on runtime conditions
+- **Thread-Safe Execution**: Safe for concurrent access with Monitor-based synchronization
+- **Circular Dependency Detection**: Prevents infinite loops with clear error messages
+- **Memory Leak Prevention**: Built-in reset mechanisms for long-running applications
+- **Topological Execution**: Tasks execute in correct dependency order automatically
+- **Reverse Cleanup**: Clean operations run in reverse dependency order
 
-> **ℹ️ Note:** Taski does **not** infer dependencies from file contents or behavior. Instead, dependencies are implicitly established via references between task definitions.
+## 🚀 Quick Start
 
-### Features
+```ruby
+require 'taski'
+
+# Simple static dependency using Exports API
+class DatabaseSetup < Taski::Task
+  exports :connection_string
+
+  def build
+    @connection_string = "postgresql://localhost/myapp"
+    puts "Database configured"
+  end
+end
+
+class APIServer < Taski::Task
+  exports :port
+
+  def build
+    # Automatic dependency: DatabaseSetup will be built first
+    puts "Starting API with #{DatabaseSetup.connection_string}"
+    @port = 3000
+  end
+end
+
+# Execute - dependencies are resolved automatically
+APIServer.build
+# => Database configured
+# => Starting API with postgresql://localhost/myapp
+```
+
+## 📚 API Guide
+
+### Exports API - Static Dependencies
+
+Use the **Exports API** when you have simple, predictable dependencies:
+
+```ruby
+class ConfigLoader < Taski::Task
+  exports :app_name, :version
+
+  def build
+    @app_name = "MyApp"
+    @version = "1.0.0"
+  end
+end
+
+class Deployment < Taski::Task
+  exports :deploy_url
+
+  def build
+    # Static dependency - always uses ConfigLoader
+    @deploy_url = "https://#{ConfigLoader.app_name}.example.com"
+  end
+end
+```
+
+### Define API - Dynamic Dependencies
+
+Use the **Define API** when dependencies change based on runtime conditions:
+
+```ruby
+class EnvironmentConfig < Taski::Task
+  define :database_service, -> {
+    # Dynamic dependency based on environment
+    case ENV['RAILS_ENV']
+    when 'production'
+      ProductionDatabase.setup
+    when 'staging'
+      StagingDatabase.setup
+    else
+      DevelopmentDatabase.setup
+    end
+  }
+
+  define :cache_strategy, -> {
+    # Dynamic dependency based on feature flags
+    if FeatureFlag.enabled?(:redis_cache)
+      RedisCache.configure
+    else
+      MemoryCache.configure
+    end
+  }
+
+  def build
+    puts "Using #{database_service}"
+    puts "Cache: #{cache_strategy}"
+  end
+end
+```
+
+> **⚠️ Note:** The `define` API uses dynamic method definition, which may generate Ruby warnings about method redefinition. This is expected behavior due to the dependency resolution mechanism and does not affect functionality.
 
-- Define tasks using Ruby classes
-- Implicit dependencies via reference to other task outputs
-- Topological execution order
-- Reverse execution for cleanup
-- Built entirely in Ruby
+### When to Use Each API
 
-### Example
+| Use Case | Recommended API | Example |
+|----------|----------------|---------|
+| Simple value exports | Exports API | Configuration values, file paths |
+| Environment-specific logic | Define API | Different services per environment |
+| Feature flag dependencies | Define API | Optional components based on flags |
+| Conditional processing | Define API | Different algorithms based on input |
+| Static file dependencies | Exports API | Build artifacts, compiled assets |
+
+## 🔧 Advanced Features
+
+### Thread Safety
+
+Taski is thread-safe and handles concurrent access gracefully:
 
 ```ruby
-class TaskA < Taski::Task
-  define :task_a_result, -> { "Task A" }
+# Multiple threads can safely access the same task
+threads = 5.times.map do
+  Thread.new { MyTask.some_value }
+end
+
+# All threads get the same instance - built only once
+results = threads.map(&:value)
+```
+
+### Error Handling
+
+Comprehensive error handling with custom exception types:
+
+```ruby
+begin
+  TaskWithCircularDep.build
+rescue Taski::CircularDependencyError => e
+  puts "Circular dependency detected: #{e.message}"
+rescue Taski::TaskBuildError => e
+  puts "Build failed: #{e.message}"
+end
+```
+
+### Lifecycle Management
 
+Full control over task lifecycle:
+
+```ruby
+class ProcessingTask < Taski::Task
   def build
-    puts 'Processing...'
+    # Setup and processing logic
+    puts "Processing data..."
+  end
+
+  def clean
+    # Cleanup logic (runs in reverse dependency order)
+    puts "Cleaning up temporary files..."
   end
 end
 
-class TaskB < Taski::Task
-  define :simple_task, -> { "Task result is #{TaskA.task_a_result}" }
+# Build dependencies in correct order
+ProcessingTask.build
+
+# Clean in reverse order
+ProcessingTask.clean
+```
+
+## 🏗️ Complex Example
+
+Here's a realistic example showing both APIs working together:
+
+```ruby
+# Environment configuration using Define API
+class Environment < Taski::Task
+  define :database_url, -> {
+    case ENV['RAILS_ENV']
+    when 'production'
+      ProductionDB.connection_string
+    when 'test'
+      TestDB.connection_string
+    else
+      "sqlite3://development.db"
+    end
+  }
+
+  define :redis_config, -> {
+    if FeatureFlag.enabled?(:redis_cache)
+      RedisService.configuration
+    else
+      nil
+    end
+  }
+end
+
+# Static configuration using Exports API
+class AppConfig < Taski::Task
+  exports :app_name, :version, :port
 
   def build
-    puts simple_task
+    @app_name = "MyWebApp"
+    @version = "2.1.0"
+    @port = ENV.fetch('PORT', 3000).to_i
   end
 end
 
-TaskB.build
-# => Processing...
-# => Task result is Task A
+# Application startup combining both APIs
+class Application < Taski::Task
+  def build
+    puts "Starting #{AppConfig.app_name} v#{AppConfig.version}"
+    puts "Database: #{Environment.database_url}"
+    puts "Redis: #{Environment.redis_config || 'disabled'}"
+    puts "Port: #{AppConfig.port}"
+
+    # Start the application...
+  end
+
+  def clean
+    puts "Shutting down #{AppConfig.app_name}..."
+    # Cleanup logic...
+  end
+end
+
+# Everything runs in the correct order automatically
+Application.build
 ```
 
-## Installation
+## 📦 Installation
 
-Install the gem and add to the application's Gemfile by executing:
+> **⚠️ Warning:** Taski is currently in development. API changes may occur. Use at your own risk in production environments.
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'taski'
+```
+
+And then execute:
 
 ```bash
-bundle add taski
+bundle install
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+Or install it yourself as:
 
 ```bash
 gem install taski
 ```
 
-## Development
+For development and testing purposes, you can also install directly from the repository:
+
+```ruby
+# In your Gemfile
+gem 'taski', git: 'https://github.com/[USERNAME]/taski.git'
+```
+
+## 🧪 Testing
+
+Taski includes comprehensive test coverage. Run the test suite:
+
+```bash
+bundle exec rake test
+```
+
+> **ℹ️ Note:** Test output may include warnings about method redefinition from the `define` API. These warnings are expected and can be safely ignored.
+
+
+## 🏛️ Architecture
+
+Taski is built with a modular architecture:
+
+- **Task Base**: Core framework and constants
+- **Exports API**: Static dependency resolution
+- **Define API**: Dynamic dependency resolution
+- **Instance Management**: Thread-safe lifecycle management
+- **Dependency Resolver**: Topological sorting and analysis
+- **Static Analyzer**: AST-based dependency detection
+
+## 🚧 Development Status
 
-After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+**Taski is currently in active development and should be considered experimental.** While the core functionality is working and well-tested, the API may undergo changes as we refine the framework based on feedback and real-world usage.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+### Current Development Phase
+
+- ✅ **Core Framework**: Dependency resolution, both APIs, thread safety
+- ✅ **Testing**: Comprehensive test suite with 38+ tests
+- ✅ **Type Safety**: RBS definitions and Steep integration
+- 🚧 **API Stability**: Some breaking changes may occur
+- 🚧 **Performance**: Optimizations for large dependency graphs
+- 🚧 **Documentation**: Examples and best practices
+
+### Known Limitations
+
+- **API Changes**: Breaking changes may occur in minor version updates
+- **Production Readiness**: Not yet recommended for production environments
+- **Static Analysis**: Works best with straightforward Ruby code patterns
+- **Metaprogramming**: Complex metaprogramming may require manual dependency specification
+- **Performance**: Not yet optimized for very large dependency graphs (1000+ tasks)
+- **Method Redefinition Warnings**: Using `define` API may generate Ruby warnings about method redefinition (this is expected behavior)
+
+### Future Development
+
+The future direction of Taski will be determined based on community feedback, real-world usage, and identified needs. Development priorities may include areas such as performance optimization, enhanced static analysis, and improved documentation, but specific roadmap items have not yet been finalized.
+
+### Contributing to Development
+
+We welcome contributions during this development phase! Areas where help is especially appreciated:
+
+- **Real-world Testing**: Try Taski in your projects and report issues
+- **Performance Testing**: Test with large dependency graphs
+- **API Feedback**: Suggest improvements to the developer experience
+- **Documentation**: Help improve examples and guides
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/taski.
+Bug reports and pull requests are welcome on GitHub at https://github.com/ahogappa/taski.
+
+## License
+
+The gem is available as open source under the [MIT License](LICENSE).
+
+---
+
+**Taski** - Build complex dependency graphs with simple, elegant Ruby code. 🚀
+
+> **Experimental Software**: Please use responsibly and provide feedback to help us reach v1.0!

data/Steepfile

@@ -0,0 +1,20 @@
+# 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

data/examples/complex_example.rb

@@ -0,0 +1,109 @@
+#!/usr/bin/env ruby
+# Complex example from README showing both APIs
+
+require_relative '../lib/taski'
+
+# Mock classes for the example
+class ProductionDB < Taski::Task
+  exports :connection_string
+  def build
+    @connection_string = "postgres://prod-server/app"
+  end
+end
+
+class TestDB < Taski::Task  
+  exports :connection_string
+  def build
+    @connection_string = "postgres://test-server/app_test"
+  end
+end
+
+module FeatureFlag
+  def self.enabled?(flag)
+    ENV["FEATURE_#{flag.to_s.upcase}"] == 'true'
+  end
+end
+
+class RedisService < Taski::Task
+  exports :configuration
+  def build
+    @configuration = "redis://localhost:6379"
+  end
+end
+
+# Environment configuration using Define API
+class Environment < Taski::Task
+  define :database_url, -> {
+    case ENV['RAILS_ENV']
+    when 'production'
+      ProductionDB.connection_string
+    when 'test'
+      TestDB.connection_string  
+    else
+      "sqlite3://development.db"
+    end
+  }
+
+  define :redis_config, -> {
+    if FeatureFlag.enabled?(:redis_cache)
+      RedisService.configuration
+    else
+      nil
+    end
+  }
+
+  def build
+    # Environment configuration is handled by define blocks
+  end
+end
+
+# Static configuration using Exports API  
+class AppConfig < Taski::Task
+  exports :app_name, :version, :port
+
+  def build
+    @app_name = "MyWebApp"
+    @version = "2.1.0"
+    @port = ENV.fetch('PORT', 3000).to_i
+  end
+end
+
+# Application startup combining both APIs
+class Application < Taski::Task
+  def build
+    puts "Starting #{AppConfig.app_name} v#{AppConfig.version}"
+    puts "Database: #{Environment.database_url}"
+    puts "Redis: #{Environment.redis_config || 'disabled'}"
+    puts "Port: #{AppConfig.port}"
+  end
+
+  def clean
+    puts "Shutting down #{AppConfig.app_name}..."
+  end
+end
+
+# Test different environments
+puts "=== Complex Example ==="
+
+puts "\n1. Development Environment (default):"
+ENV.delete('RAILS_ENV')
+ENV.delete('FEATURE_REDIS_CACHE')
+Application.build
+Application.reset!
+
+puts "\n2. Test Environment:"
+ENV['RAILS_ENV'] = 'test'
+# Reset Environment to re-evaluate define blocks
+Environment.reset!
+Application.build
+Application.reset!
+
+puts "\n3. Production with Redis:"
+ENV['RAILS_ENV'] = 'production'
+ENV['FEATURE_REDIS_CACHE'] = 'true'
+# Reset Environment to re-evaluate define blocks
+Environment.reset!
+Application.build
+
+puts "\n4. Cleanup:"
+Application.clean

data/examples/readme_example.rb

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+# Quick Start example from README
+
+require_relative '../lib/taski'
+
+# Simple static dependency using Exports API
+class DatabaseSetup < Taski::Task
+  exports :connection_string
+
+  def build
+    @connection_string = "postgresql://localhost/myapp"
+    puts "Database configured"
+  end
+end
+
+class APIServer < Taski::Task
+  exports :port
+
+  def build
+    # Automatic dependency: DatabaseSetup will be built first
+    puts "Starting API with #{DatabaseSetup.connection_string}"
+    @port = 3000
+  end
+end
+
+# Execute - dependencies are resolved automatically
+puts "=== Quick Start Example ==="
+APIServer.build
+
+puts "\nResult: APIServer running on port #{APIServer.port}"

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