taski 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 260795a6ff4d622bd95b3bfb2668ba6123f17339650ea9371ea54d2210691d98
-  data.tar.gz: 60d7f97a6c736ed91e50bd2e8e9f48c163f76024e7407c0da96c9d77f4394514
+  metadata.gz: 8b66b9afd145af8c5a07839b1886212336ffbdcb935897a278afae10315162e8
+  data.tar.gz: 7f43e874932671c2a41adc776514022e7d44d9ec0018935e2bd2e7e4d4537543
 SHA512:
-  metadata.gz: 71ccbe4131ac8409636071355af2de6cfda0862e21fb012e70b2f2fe60cb3bbc7023d640f9d3dc889f6759e8885a5dba5a1c0d543a6aa05e9299aa9ff401df54
-  data.tar.gz: a0a291d6fdd8d9ec1a122dbca9d115aa5c36f8008e7812120b0356e218ea895f46b292eab4404404c611c1f1b69e6dc9e4247f18d2cfc7a079b7d1f0ec2716d6
+  metadata.gz: 8175467340490afdd0e9f1d4ba5c2e3db257e7d4c62850f88a138676056ea140753e2c38042803dd46c6c071731245314c2b597af83eb8c237be28d20e998e60
+  data.tar.gz: d1695488ca402cdb18800bd4b8623c64ed3c681a5dd6039c651c117c99793045fa59cca85f82cde0fde311b0ada0d81b8a66ba4d8cbb9b576ebe00fe71e760cf

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ahogappa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,65 +1,333 @@
 # Taski
 
-**Taski** is a Ruby-based task runner designed for small, composable processing steps.
-With Taski, you define tasks and the outputs they depend on. Taski then statically resolves task dependencies and determines the correct execution order.
+> **🚧 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 all dependencies are resolved before a task is run. Reverse execution is also supported, making it easy to clean up intermediate files after a build process.
+**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
 
-### Features
+## 🚀 Quick Start
 
-- Simple and declarative task definitions
-- Static dependency resolution
-- Topological execution order
-- Reverse execution for teardown or cleanup
-- Built entirely in Ruby
+```ruby
+require 'taski'
 
-## Installation
+# Simple static dependency using Exports API
+class DatabaseSetup < Taski::Task
+  exports :connection_string
 
-Install the gem and add to the application's Gemfile by executing:
+  def build
+    @connection_string = "postgresql://localhost/myapp"
+    puts "Database configured"
+  end
+end
 
-```bash
-bundle add taski
+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
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+## 📚 API Guide
 
-```bash
-gem install taski
+### 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
 ```
 
-## Usage
+### Define API - Dynamic Dependencies
+
+Use the **Define API** when dependencies change based on runtime conditions:
 
 ```ruby
-class TaskA < Taski::Task
-  definition :task_a, -> { "Task A" }
+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
-    task_a
+    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.
+
+### When to Use Each API
+
+| 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
+# 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
+```
 
-class TaskB < Taski::Task
-  definition :simple_task, -> { "Task result is #{TaskA.task_a}" }
+### Lifecycle Management
 
+Full control over task lifecycle:
+
+```ruby
+class ProcessingTask < Taski::Task
   def build
-    puts simple_task
+    # Setup and processing logic
+    puts "Processing data..."
+  end
+
+  def clean
+    # Cleanup logic (runs in reverse dependency order)
+    puts "Cleaning up temporary files..."
   end
 end
 
-TaskB.build
-# => Task result is Task A
+# Build dependencies in correct order
+ProcessingTask.build
+
+# Clean in reverse order
+ProcessingTask.clean
 ```
 
-## Development
+## 🏗️ Complex Example
 
-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.
+Here's a realistic example showing both APIs working together:
 
-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).
+```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
+    @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}"
+
+    # 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
+
+> **⚠️ 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 install
+```
+
+Or install it yourself as:
+
+```bash
+gem install taski
+```
+
+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
+
+**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.
+
+### 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}"