taski 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b66b9afd145af8c5a07839b1886212336ffbdcb935897a278afae10315162e8
-  data.tar.gz: 7f43e874932671c2a41adc776514022e7d44d9ec0018935e2bd2e7e4d4537543
+  metadata.gz: 28f2e52366511da4606df64a169c804712fcf4398b55a7b7d6430a1367cc183d
+  data.tar.gz: 97cc63c767ceaf7dda2fbb4345876c47d1fb1bf7e0395c8a2a0369bc8585e817
 SHA512:
-  metadata.gz: 8175467340490afdd0e9f1d4ba5c2e3db257e7d4c62850f88a138676056ea140753e2c38042803dd46c6c071731245314c2b597af83eb8c237be28d20e998e60
-  data.tar.gz: d1695488ca402cdb18800bd4b8623c64ed3c681a5dd6039c651c117c99793045fa59cca85f82cde0fde311b0ada0d81b8a66ba4d8cbb9b576ebe00fe71e760cf
+  metadata.gz: 4558c7e5ab3ae48301da573a0d2dffa935ecf2bdf7f04ccce1b92add5ea45b3aea1b562dcce0c6356d28b7eacd58fcdca030a9a2748fbafdda9d9046b5a09213
+  data.tar.gz: f440abca3014be0bffdd34cb8440f197b55403fc938660a8eb311e1bb6c64127bf9d033335d7e52f71cefec534ae4b6e41e2b83164d76b893d3a3c8f692bc221

data/.standard.yml

@@ -0,0 +1,9 @@
+ruby_version: 3.2
+
+ignore:
+  - 'pkg/**/*'
+  - 'vendor/**/*'
+  - 'bin/**/*'
+
+# Allow eval for dynamic method creation in define API
+parallel: true

data/README.md

@@ -1,27 +1,21 @@
 # Taski
 
-> **🚧 Development Status:** Taski is currently under active development and the API may change. Not yet recommended for production use.
+[![CI](https://github.com/ahogappa/taski/workflows/CI/badge.svg)](https://github.com/ahogappa/taski/actions/workflows/ci.yml)
+[![Codecov](https://codecov.io/gh/ahogappa/taski/branch/master/graph/badge.svg)](https://codecov.io/gh/ahogappa/taski)
+[![Gem Version](https://badge.fury.io/rb/taski.svg)](https://badge.fury.io/rb/taski)
 
-**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. Not yet recommended for production use.
 
-## 🎯 Key Features
+**Taski** is a Ruby framework for building task dependency graphs with automatic resolution and execution. It provides two APIs: static dependencies through **Exports** and dynamic dependencies through **Define**.
 
-- **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
+> **Name Origin**: "Taski" comes from the Japanese word "襷" (tasuki), a sash used in relay races. Just like how runners pass the sash to the next teammate, tasks in Taski pass dependencies to one another in a continuous chain.
 
 ## 🚀 Quick Start
 
 ```ruby
 require 'taski'
 
-# Simple static dependency using Exports API
+# Static dependency using Exports API
 class DatabaseSetup < Taski::Task
   exports :connection_string
 
@@ -32,16 +26,11 @@ class DatabaseSetup < Taski::Task
 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
@@ -51,7 +40,7 @@ APIServer.build
 
 ### Exports API - Static Dependencies
 
-Use the **Exports API** when you have simple, predictable dependencies:
+For simple, predictable dependencies:
 
 ```ruby
 class ConfigLoader < Taski::Task
@@ -60,274 +49,202 @@ class ConfigLoader < Taski::Task
   def build
     @app_name = "MyApp"
     @version = "1.0.0"
+    puts "Config loaded: #{@app_name} v#{@version}"
   end
 end
 
 class Deployment < Taski::Task
-  exports :deploy_url
-
   def build
-    # Static dependency - always uses ConfigLoader
     @deploy_url = "https://#{ConfigLoader.app_name}.example.com"
+    puts "Deploying to #{@deploy_url}"
   end
 end
+
+Deployment.build
+# => Config loaded: MyApp v1.0.0
+# => Deploying to https://MyApp.example.com
 ```
 
 ### Define API - Dynamic Dependencies
 
-Use the **Define API** when dependencies change based on runtime conditions:
+For dependencies that 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
+      "production-db.example.com"
     else
-      DevelopmentDatabase.setup
-    end
-  }
-
-  define :cache_strategy, -> {
-    # Dynamic dependency based on feature flags
-    if FeatureFlag.enabled?(:redis_cache)
-      RedisCache.configure
-    else
-      MemoryCache.configure
+      "localhost:5432"
     end
   }
 
   def build
-    puts "Using #{database_service}"
-    puts "Cache: #{cache_strategy}"
+    puts "Using database: #{database_service}"
+    puts "Environment: #{ENV['RAILS_ENV'] || 'development'}"
   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.
+EnvironmentConfig.build
+# => Using database: localhost:5432
+# => Environment: development
+
+ENV['RAILS_ENV'] = 'production'
+EnvironmentConfig.reset!
+EnvironmentConfig.build
+# => Using database: production-db.example.com
+# => Environment: production
+```
 
 ### 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 |
+- **Define API**: Best for dynamic runtime dependencies. Cannot contain side effects in definition blocks. Dependencies are analyzed at class definition time, not runtime.
+- **Exports API**: Ideal for static dependencies. Supports side effects in build methods.
 
-## 🔧 Advanced Features
+| Use Case | API | Example |
+|----------|-----|---------|
+| Configuration values | Exports | File paths, settings |
+| Environment-specific logic | Define | Different services per env |
+| Side effects | Exports | Database connections, I/O |
+| Conditional processing | Define | Algorithm selection |
 
-### Thread Safety
+**Note**: Define API analyzes dependencies when the class is defined. Conditional dependencies like `ENV['USE_NEW'] ? TaskA : TaskB` will only include the task selected at class definition time, not runtime.
 
-Taski is thread-safe and handles concurrent access gracefully:
+## ✨ Key Features
 
-```ruby
-# Multiple threads can safely access the same task
-threads = 5.times.map do
-  Thread.new { MyTask.some_value }
-end
+- **Automatic Dependency Resolution**: Dependencies detected through static analysis
+- **Thread-Safe**: Safe for concurrent access
+- **Circular Dependency Detection**: Clear error messages with detailed paths
+- **Granular Execution**: Build individual tasks or complete graphs
+- **Memory Management**: Built-in reset mechanisms
 
-# All threads get the same instance - built only once
-results = threads.map(&:value)
-```
+### Granular Task Execution
 
-### Error Handling
-
-Comprehensive error handling with custom exception types:
+Execute any task individually - Taski builds only required dependencies:
 
 ```ruby
-begin
-  TaskWithCircularDep.build
-rescue Taski::CircularDependencyError => e
-  puts "Circular dependency detected: #{e.message}"
-rescue Taski::TaskBuildError => e
-  puts "Build failed: #{e.message}"
-end
+# Build specific components
+ConfigLoader.build           # Builds only ConfigLoader
+# => Config loaded: MyApp v1.0.0
+
+EnvironmentConfig.build      # Builds EnvironmentConfig and its dependencies
+# => Using database: localhost:5432
+# => Environment: development
+
+# Access values (triggers build if needed)
+puts ConfigLoader.version    # Builds ConfigLoader if not built
+# => 1.0.0
 ```
 
 ### Lifecycle Management
 
-Full control over task lifecycle:
+Tasks can define both build and clean methods. Clean operations run in reverse dependency order:
 
 ```ruby
-class ProcessingTask < Taski::Task
+class DatabaseSetup < Taski::Task
+  exports :connection
+
   def build
-    # Setup and processing logic
-    puts "Processing data..."
+    @connection = "db-connection"
+    puts "Database connected"
   end
 
   def clean
-    # Cleanup logic (runs in reverse dependency order)
-    puts "Cleaning up temporary files..."
+    puts "Database disconnected"
   end
 end
 
-# Build dependencies in correct order
-ProcessingTask.build
-
-# Clean in reverse order
-ProcessingTask.clean
-```
+class WebServer < Taski::Task
+  def build
+    puts "Web server started with #{DatabaseSetup.connection}"
+  end
 
-## 🏗️ Complex Example
+  def clean
+    puts "Web server stopped"
+  end
+end
 
-Here's a realistic example showing both APIs working together:
+WebServer.build
+# => Database connected
+# => Web server started with db-connection
 
-```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
-  }
+WebServer.clean
+# => Web server stopped
+# => Database disconnected
+```
 
-  define :redis_config, -> {
-    if FeatureFlag.enabled?(:redis_cache)
-      RedisService.configuration
-    else
-      nil
-    end
-  }
-end
+### Clean Method Idempotency
 
-# Static configuration using Exports API
-class AppConfig < Taski::Task
-  exports :app_name, :version, :port
+**Important**: The `clean` method must be idempotent - safe to call multiple times without errors.
 
-  def build
-    @app_name = "MyWebApp"
-    @version = "2.1.0"
-    @port = ENV.fetch('PORT', 3000).to_i
-  end
-end
+```ruby
+class FileTask < Taski::Task
+  exports :output_file
 
-# 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...
+    @output_file = '/tmp/data.csv'
+    File.write(@output_file, process_data)
   end
 
   def clean
-    puts "Shutting down #{AppConfig.app_name}..."
-    # Cleanup logic...
+    # ❌ Bad: Raises error if file doesn't exist
+    # File.delete(@output_file)
+    
+    # ✅ Good: Check before delete
+    File.delete(@output_file) if File.exist?(@output_file)
   end
 end
-
-# Everything runs in the correct order automatically
-Application.build
 ```
 
-## 📦 Installation
+### Error Handling
 
-> **⚠️ Warning:** Taski is currently in development. API changes may occur. Use at your own risk in production environments.
+```ruby
+begin
+  TaskWithCircularDep.build
+rescue Taski::CircularDependencyError => e
+  puts "Circular dependency: #{e.message}"
+end
+# => Circular dependency: Circular dependency detected!
+# => Cycle: TaskA → TaskB → TaskA
+# => 
+# => The dependency chain is:
+# =>   1. TaskA is trying to build → TaskB
+# =>   2. TaskB is trying to build → TaskA
+```
 
-Add this line to your application's Gemfile:
+## 📦 Installation
 
 ```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
+- **Task Base**: Core framework
 - **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
+- **Instance Management**: Thread-safe lifecycle
+- **Dependency Resolver**: Topological sorting
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/ahogappa/taski.
+Bug reports and pull requests welcome at https://github.com/ahogappa/taski.
 
 ## License
 
-The gem is available as open source under the [MIT License](LICENSE).
+MIT 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!
+**Taski** - Build dependency graphs with elegant Ruby code. 🚀

data/Rakefile

@@ -10,4 +10,10 @@ Rake::TestTask.new(:test) do |t|
   t.verbose = true
 end
 
-task default: %i[test]
+begin
+  require "standard/rake"
+rescue LoadError
+  # Standard not available
+end
+
+task default: %i[test standard]

data/examples/README.md

@@ -0,0 +1,57 @@
+# Taski Examples
+
+Learn Taski through practical examples, from basic concepts to advanced patterns.
+
+## Getting Started
+
+Start with these examples in order:
+
+### 1. **[quick_start.rb](quick_start.rb)** - Your First Taski Program
+- Basic task definition with Exports API
+- Automatic dependency resolution
+- Simple task execution
+
+```bash
+ruby examples/quick_start.rb
+```
+
+### 2. **[progress_demo.rb](progress_demo.rb)** - Rich CLI Progress Display
+- Animated spinner with ANSI colors
+- Real-time output capture and 5-line tail
+- Production build scenarios
+- TTY detection for clean file output
+
+```bash
+# Interactive mode with rich spinner
+ruby examples/progress_demo.rb
+
+# Clean output mode (no spinner)
+ruby examples/progress_demo.rb > build.log 2>&1
+cat build.log
+```
+
+### 3. **[advanced_patterns.rb](advanced_patterns.rb)** - Complex Dependency Patterns
+- Mixed Exports API and Define API usage
+- Environment-specific dependencies
+- Feature flags and conditional logic
+- Task reset and rebuild scenarios
+
+```bash
+ruby examples/advanced_patterns.rb
+```
+
+## Key Concepts Demonstrated
+
+- **Exports API**: Static dependencies with `exports :property`
+- **Define API**: Dynamic dependencies with `define :property, -> { ... }`
+- **Progress Display**: Rich terminal output with spinners and colors
+- **Output Capture**: Tail-style display of task output
+- **Environment Configuration**: Different behavior based on runtime settings
+- **Error Handling**: Graceful failure with progress indicators
+
+## Next Steps
+
+After exploring these examples:
+- Read the main documentation
+- Examine the test files for more usage patterns
+- Check out the source code in `lib/taski/`

data/examples/{complex_example.rb → advanced_patterns.rb}

@@ -1,7 +1,21 @@
 #!/usr/bin/env ruby
-# Complex example from README showing both APIs
+# frozen_string_literal: true
 
-require_relative '../lib/taski'
+# Taski Advanced Patterns
+#
+# This example demonstrates advanced Taski patterns:
+# - Mixed usage of Exports API and Define API
+# - Environment-specific dependency resolution
+# - Feature flag integration with dynamic dependencies
+# - Task reset and rebuild scenarios
+# - Conditional dependency evaluation
+#
+# Run: ruby examples/advanced_patterns.rb
+
+require_relative "../lib/taski"
+
+puts "⚡ Advanced Taski Patterns"
+puts "=" * 40
 
 # Mock classes for the example
 class ProductionDB < Taski::Task
@@ -11,7 +25,7 @@ class ProductionDB < Taski::Task
   end
 end
 
-class TestDB < Taski::Task  
+class TestDB < Taski::Task
   exports :connection_string
   def build
     @connection_string = "postgres://test-server/app_test"
@@ -20,7 +34,7 @@ end
 
 module FeatureFlag
   def self.enabled?(flag)
-    ENV["FEATURE_#{flag.to_s.upcase}"] == 'true'
+    ENV["FEATURE_#{flag.to_s.upcase}"] == "true"
   end
 end
 
@@ -34,11 +48,11 @@ end
 # Environment configuration using Define API
 class Environment < Taski::Task
   define :database_url, -> {
-    case ENV['RAILS_ENV']
-    when 'production'
+    case ENV["RAILS_ENV"]
+    when "production"
       ProductionDB.connection_string
-    when 'test'
-      TestDB.connection_string  
+    when "test"
+      TestDB.connection_string
     else
       "sqlite3://development.db"
     end
@@ -47,8 +61,6 @@ class Environment < Taski::Task
   define :redis_config, -> {
     if FeatureFlag.enabled?(:redis_cache)
       RedisService.configuration
-    else
-      nil
     end
   }
 
@@ -57,14 +69,14 @@ class Environment < Taski::Task
   end
 end
 
-# Static configuration using Exports API  
+# 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
+    @port = ENV.fetch("PORT", 3000).to_i
   end
 end
 
@@ -73,7 +85,7 @@ 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 "Redis: #{Environment.redis_config || "disabled"}"
     puts "Port: #{AppConfig.port}"
   end
 
@@ -83,27 +95,25 @@ class Application < Taski::Task
 end
 
 # Test different environments
-puts "=== Complex Example ==="
-
 puts "\n1. Development Environment (default):"
-ENV.delete('RAILS_ENV')
-ENV.delete('FEATURE_REDIS_CACHE')
+ENV.delete("RAILS_ENV")
+ENV.delete("FEATURE_REDIS_CACHE")
 Application.build
 Application.reset!
 
 puts "\n2. Test Environment:"
-ENV['RAILS_ENV'] = 'test'
+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'
+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
+Application.clean