taski 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b66b9afd145af8c5a07839b1886212336ffbdcb935897a278afae10315162e8
-  data.tar.gz: 7f43e874932671c2a41adc776514022e7d44d9ec0018935e2bd2e7e4d4537543
+  metadata.gz: 4e44ea93464ceaf8994d761cec75cf4d32df7cdb8f90d25b4cfcae5be7f8a586
+  data.tar.gz: 8a1b5fae85bbffb28756f2e13b3f98c2cb8023c76346b5da722ac55e87ef3cc5
 SHA512:
-  metadata.gz: 8175467340490afdd0e9f1d4ba5c2e3db257e7d4c62850f88a138676056ea140753e2c38042803dd46c6c071731245314c2b597af83eb8c237be28d20e998e60
-  data.tar.gz: d1695488ca402cdb18800bd4b8623c64ed3c681a5dd6039c651c117c99793045fa59cca85f82cde0fde311b0ada0d81b8a66ba4d8cbb9b576ebe00fe71e760cf
+  metadata.gz: '037285b1bc19edd6d674f6748674fa8443c0cb40d5199de86bdfa3696c1597308d69ff5236a7114c43cf666a27e62f5c4111c5a36301736c4fdac98cdd65b4c4'
+  data.tar.gz: afa967d630b56f9de1f4974879533572d06c42d574dce6bea69da9635ce69e06251af555168ff0b3475e95d5a1d6d07e8951e6052f0f6e04291d07b15d23239b

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,177 @@ 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
-    else
-      DevelopmentDatabase.setup
-    end
-  }
-
-  define :cache_strategy, -> {
-    # Dynamic dependency based on feature flags
-    if FeatureFlag.enabled?(:redis_cache)
-      RedisCache.configure
+      "production-db.example.com"
     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.
+- **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
+## ✨ Key Features
 
-Taski is thread-safe and handles concurrent access gracefully:
+- **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
 
-```ruby
-# Multiple threads can safely access the same task
-threads = 5.times.map do
-  Thread.new { MyTask.some_value }
-end
+### Granular Task Execution
 
-# All threads get the same instance - built only once
-results = threads.map(&:value)
-```
+Execute any task individually - Taski builds only required dependencies:
 
-### Error Handling
+```ruby
+# Build specific components
+ConfigLoader.build           # Builds only ConfigLoader
+# => Config loaded: MyApp v1.0.0
 
-Comprehensive error handling with custom exception types:
+EnvironmentConfig.build      # Builds EnvironmentConfig and its dependencies
+# => Using database: localhost:5432
+# => Environment: development
 
-```ruby
-begin
-  TaskWithCircularDep.build
-rescue Taski::CircularDependencyError => e
-  puts "Circular dependency detected: #{e.message}"
-rescue Taski::TaskBuildError => e
-  puts "Build failed: #{e.message}"
-end
+# 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..."
-  end
-end
-
-# 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
-    @app_name = "MyWebApp"
-    @version = "2.1.0"
-    @port = ENV.fetch('PORT', 3000).to_i
+    puts "Database disconnected"
   end
 end
 
-# Application startup combining both APIs
-class Application < Taski::Task
+class WebServer < 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...
+    puts "Web server started with #{DatabaseSetup.connection}"
   end
 
   def clean
-    puts "Shutting down #{AppConfig.app_name}..."
-    # Cleanup logic...
+    puts "Web server stopped"
   end
 end
 
-# Everything runs in the correct order automatically
-Application.build
+WebServer.build
+# => Database connected
+# => Web server started with db-connection
+
+WebServer.clean
+# => Web server stopped
+# => Database disconnected
 ```
 
-## 📦 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/complex_example.rb

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 # Complex example from README showing both APIs
 
-require_relative '../lib/taski'
+require_relative "../lib/taski"
 
 # Mock classes for the example
 class ProductionDB < Taski::Task
@@ -11,7 +11,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 +20,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 +34,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 +47,6 @@ class Environment < Taski::Task
   define :redis_config, -> {
     if FeatureFlag.enabled?(:redis_cache)
       RedisService.configuration
-    else
-      nil
     end
   }
 
@@ -57,14 +55,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 +71,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
 
@@ -86,24 +84,24 @@ end
 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

data/examples/readme_example.rb

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 # Quick Start example from README
 
-require_relative '../lib/taski'
+require_relative "../lib/taski"
 
 # Simple static dependency using Exports API
 class DatabaseSetup < Taski::Task
@@ -27,4 +27,4 @@ end
 puts "=== Quick Start Example ==="
 APIServer.build
 
-puts "\nResult: APIServer running on port #{APIServer.port}"
+puts "\nResult: APIServer running on port #{APIServer.port}"

data/lib/taski/dependency_analyzer.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'prism'
+require "prism"
 
 module Taski
   module DependencyAnalyzer
@@ -19,13 +19,19 @@ module Taski
           result = Prism.parse_file(file_path)
 
           unless result.success?
-            warn "Taski: Parse errors in #{file_path}: #{result.errors.map(&:message).join(', ')}"
+            Taski.logger.error("Parse errors in source file",
+              file: file_path,
+              errors: result.errors.map(&:message),
+              method: "#{klass}##{method_name}")
             return []
           end
 
           # Handle warnings if present
           if result.warnings.any?
-            warn "Taski: Parse warnings in #{file_path}: #{result.warnings.map(&:message).join(', ')}"
+            Taski.logger.warn("Parse warnings in source file",
+              file: file_path,
+              warnings: result.warnings.map(&:message),
+              method: "#{klass}##{method_name}")
           end
 
           dependencies = []
@@ -39,10 +45,17 @@ module Taski
 
           dependencies.uniq
         rescue IOError, SystemCallError => e
-          warn "Taski: Failed to read file #{file_path}: #{e.message}"
+          Taski.logger.error("Failed to read source file",
+            file: file_path,
+            error: e.message,
+            method: "#{klass}##{method_name}")
           []
         rescue => e
-          warn "Taski: Failed to analyze method #{klass}##{method_name}: #{e.message}"
+          Taski.logger.error("Failed to analyze method dependencies",
+            class: klass.name,
+            method: method_name,
+            error: e.message,
+            error_class: e.class.name)
           []
         end
       end
@@ -151,12 +164,9 @@ module Taski
             else
               child_name
             end
-          else
-            nil
           end
         end
       end
-
     end
   end
 end

data/lib/taski/exceptions.rb

@@ -2,13 +2,13 @@
 
 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
+end