taski 0.3.1 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 80c881415617aa09fb7ae24441c38c677af816c20f356cc06ea82bba50639820
-  data.tar.gz: cc0c6e07e3f53c312844dc237ebebe344a0201bb772f1c6c20ee8c6476b9db30
+  metadata.gz: 46cb1222487f928c10241827374311ed65541773bd1cd6d40d8fd2e6ea8af64e
+  data.tar.gz: c16aad068cef227130a8051fd71c8847845212dc3f990ae706b2d1b10104a9d6
 SHA512:
-  metadata.gz: 5e40462d8b2b359c17f28f16ec03524ee649324eb4e21eaf365fd147ccedad6bb3d683ece9021975683b1b121c93ad1da2bdaa0fed82ec37797090fadc79129c
-  data.tar.gz: 441c9553cded529843af032347f4590f9b6a289bd00f3a8ccbbe996b6be43d2154bc6e2fc4f84a94c1f18c35eb4cfcf5408ff07f6b8878b4f50e41c32a407756
+  metadata.gz: a37a616b526c7c67811286e2c50dd5319c9ce98779f4edf495f6337c214c9f0915b46694f4b8edfd5a8a6b7f66ce9fb9d946ffd36cf0be2f2a4991452875a765
+  data.tar.gz: ff577241138a18dcf8018c4c0c68ea8137301e33bfa6b31d58e564862eeb8f520a9120c755aa0c6acf61b5c1f18b71bb728dd785627ee278c3c6eee08d31dc30

data/README.md

@@ -4,368 +4,198 @@
 [![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)
 
-> **🚧 Development Status:** Taski is currently under active development. Not yet recommended for production use.
-
-**Taski** is a Ruby framework for building task dependency graphs with automatic resolution and execution. It provides three APIs: static dependencies through **Exports**, dynamic dependencies through **Define**, and abstraction layers through **Section**.
+**Taski** is a Ruby framework for building task dependency graphs with automatic resolution and parallel execution.
 
 > **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
+## Features
+
+- **Automatic Dependency Resolution**: Dependencies detected via static analysis
+- **Parallel Execution**: Independent tasks run concurrently for maximum performance
+- **Two Simple APIs**: Exports (value sharing) and Section (runtime selection)
+- **Real-time Progress**: Visual feedback with parallel task progress display
+- **Thread-Safe**: Built on Monitor-based synchronization for reliable concurrent execution
+
+## Quick Start
 
 ```ruby
 require 'taski'
 
-# Static dependency using Exports API
 class DatabaseSetup < Taski::Task
   exports :connection_string
 
-  def build
+  def run
     @connection_string = "postgresql://localhost/myapp"
-    puts "Database configured"
+  end
+end
+
+class CacheSetup < Taski::Task
+  exports :cache_url
+
+  def run
+    @cache_url = "redis://localhost:6379"
   end
 end
 
 class APIServer < Taski::Task
-  def build
-    puts "Starting API with #{DatabaseSetup.connection_string}"
+  def run
+    # Dependencies execute automatically and in parallel
+    puts "DB: #{DatabaseSetup.connection_string}"
+    puts "Cache: #{CacheSetup.cache_url}"
   end
 end
 
-APIServer.build
-# => Database configured
-# => Starting API with postgresql://localhost/myapp
+APIServer.run
 ```
 
-## 📚 API Guide
-
-### Exports API - Static Dependencies
-
-For simple, predictable dependencies:
+## Installation
 
 ```ruby
-class ConfigLoader < Taski::Task
-  exports :app_name, :version
-
-  def build
-    @app_name = "MyApp"
-    @version = "1.0.0"
-    puts "Config loaded: #{@app_name} v#{@version}"
-  end
-end
-
-class Deployment < Taski::Task
-  def build
-    @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
+gem 'taski'
 ```
 
-### Define API - Dynamic Dependencies
+## Core Concepts
+
+### Exports - Value Sharing Between Tasks
 
-For dependencies that change based on runtime conditions:
+Share computed values between tasks:
 
 ```ruby
-class EnvironmentConfig < Taski::Task
-  define :database_service, -> {
-    case ENV['RAILS_ENV']
-    when 'production'
-      "production-db.example.com"
-    else
-      "localhost:5432"
-    end
-  }
+class Config < Taski::Task
+  exports :app_name, :port
 
-  def build
-    puts "Using database: #{database_service}"
-    puts "Environment: #{ENV['RAILS_ENV'] || 'development'}"
+  def run
+    @app_name = "MyApp"
+    @port = 3000
   end
 end
 
-EnvironmentConfig.build
-# => Using database: localhost:5432
-# => Environment: development
-
-ENV['RAILS_ENV'] = 'production'
-EnvironmentConfig.reset!
-EnvironmentConfig.build
-# => Using database: production-db.example.com
-# => Environment: production
+class Server < Taski::Task
+  def run
+    puts "Starting #{Config.app_name} on port #{Config.port}"
+  end
+end
 ```
 
-### Section API - Abstraction Layers
+### Section - Runtime Implementation Selection
 
-For environment-specific implementations with clean interfaces:
+Switch implementations based on environment:
 
 ```ruby
 class DatabaseSection < Taski::Section
-  interface :host, :port
-
-  def impl
-    ENV['RAILS_ENV'] == 'production' ? Production : Development
-  end
+  interfaces :host, :port
 
   class Production < Taski::Task
-    def build
-      @host = "prod-db.example.com"
+    def run
+      @host = "prod.example.com"
       @port = 5432
     end
   end
 
   class Development < Taski::Task
-    def build
+    def run
       @host = "localhost"
       @port = 5432
     end
   end
+
+  def impl
+    ENV['RAILS_ENV'] == 'production' ? Production : Development
+  end
 end
 
-# Usage is simple - Section works like any Task
 class App < Taski::Task
-  def build
-    puts "DB: #{DatabaseSection.host}:#{DatabaseSection.port}"
+  def run
+    puts "Connecting to #{DatabaseSection.host}:#{DatabaseSection.port}"
   end
 end
-
-App.build  # => DB: localhost:5432
 ```
 
-### When to Use Each API
-
-- **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.
-- **Section API**: Perfect for abstraction layers where you need different implementations based on runtime conditions while maintaining static analysis capabilities.
-
-| Use Case | API | Example |
-|----------|-----|---------|
-| Configuration values | Exports | File paths, settings |
-| Environment-specific logic | Define/Section | Different services per env |
-| Side effects | Exports | Database connections, I/O |
-| Conditional processing | Define | Algorithm selection |
-| Implementation abstraction | Section | Database/API adapters |
-| Multi-environment configs | Section | Dev/Test/Prod settings |
+> **Note**: Nested implementation classes automatically inherit Section's `interfaces` as `exports`.
 
-**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. Use Section API when you need true runtime selection.
+## Advanced Usage
 
-## ✨ Key Features
+### Context - Runtime Information and Options
 
-- **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
-- **Progress Display**: Visual feedback with spinners and output capture
-- **Dependency Tree Visualization**: Visual representation of task relationships
-
-### Dependency Tree Visualization
-
-Visualize task dependencies with the `tree` method:
+Pass custom options and access execution context from any task:
 
 ```ruby
-class Database < Taski::Task
-  exports :connection
-  def build; @connection = "db-conn"; end
-end
+class DeployTask < Taski::Task
+  def run
+    # User-defined options
+    env = Taski.context[:env]
+    debug = Taski.context.fetch(:debug, false)
 
-class Cache < Taski::Task
-  exports :redis_url
-  def build; @redis_url = "redis://localhost"; end
-end
-
-class Config < Taski::Task
-  exports :settings
-  def build
-    @settings = {
-      database: Database.connection,
-      cache: Cache.redis_url
-    }
+    # Runtime information
+    puts "Working directory: #{Taski.context.working_directory}"
+    puts "Started at: #{Taski.context.started_at}"
+    puts "Root task: #{Taski.context.root_task}"
+    puts "Deploying to: #{env}"
   end
 end
 
-class WebServer < Taski::Task
-  def build
-    puts "Starting with #{Config.settings}"
-  end
-end
-
-puts WebServer.tree
-# => WebServer
-# => └── Config
-# =>     ├── Database
-# =>     └── Cache
-
-# Sections also appear in dependency trees
-puts AppServer.tree
-# => AppServer
-# => └── DatabaseSection
+# Pass options when running
+DeployTask.run(context: { env: "production", debug: true })
 ```
 
-### Progress Display
+Context API:
+- `Taski.context[:key]` - Get option value (nil if not set)
+- `Taski.context.fetch(:key, default)` - Get with default value
+- `Taski.context.key?(:key)` - Check if option exists
+- `Taski.context.working_directory` - Execution directory
+- `Taski.context.started_at` - Execution start time
+- `Taski.context.root_task` - First task class called
 
-Taski provides visual feedback during task execution with animated spinners and real-time output capture:
+### Re-execution
 
 ```ruby
-class LongRunningTask < Taski::Task
-  def build
-    puts "Starting process..."
-    sleep(1.0)
-    puts "Processing data..."
-    puts "Almost done..."
-    sleep(0.5)
-    puts "Completed!"
-  end
-end
-
-LongRunningTask.build
-# During execution shows:
-# ⠧ LongRunningTask
-#   Starting process...
-#   Processing data...
-#   Almost done...
-#   Completed!
-#
-# After completion shows:
-# ✅ LongRunningTask (1500ms)
-```
+# Cached execution (default)
+RandomTask.value  # => 42
+RandomTask.value  # => 42 (cached)
 
-**Progress Display Features:**
-- **Spinner Animation**: Dots-style spinner during task execution
-- **Output Capture**: Real-time display of task output (last 5 lines)
-- **Status Indicators**: ✅ for success, ❌ for failure
-- **Execution Time**: Shows task duration after completion
-- **TTY Detection**: Clean output when redirected to files
+# Fresh execution
+RandomTask.new.run  # => 123 (new instance)
 
-### Granular Task Execution
-
-Execute any task individually - Taski builds only required dependencies:
-
-```ruby
-# 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
+# Reset all caches
+RandomTask.reset!
 ```
 
-### Lifecycle Management
-
-Tasks can define both build and clean methods. Clean operations run in reverse dependency order:
-
-```ruby
-class DatabaseSetup < Taski::Task
-  exports :connection
-
-  def build
-    @connection = "db-connection"
-    puts "Database connected"
-  end
-
-  def clean
-    puts "Database disconnected"
-  end
-end
-
-class WebServer < Taski::Task
-  def build
-    puts "Web server started with #{DatabaseSetup.connection}"
-  end
-
-  def clean
-    puts "Web server stopped"
-  end
-end
+### Progress Display
 
-WebServer.build
-# => Database connected
-# => Web server started with db-connection
+Enable real-time progress visualization:
 
-WebServer.clean
-# => Web server stopped
-# => Database disconnected
+```bash
+TASKI_FORCE_PROGRESS=1 ruby your_script.rb
 ```
 
-### Clean Method Idempotency
-
-**Important**: The `clean` method must be idempotent - safe to call multiple times without errors.
-
-```ruby
-class FileTask < Taski::Task
-  exports :output_file
-
-  def build
-    @output_file = '/tmp/data.csv'
-    File.write(@output_file, process_data)
-  end
-
-  def clean
-    # ❌ 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
 ```
-
-### Error Handling
-
-```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
+⠋ DatabaseSetup (running)
+⠙ CacheSetup (running)
+✅ DatabaseSetup (123.4ms)
+✅ CacheSetup (98.2ms)
 ```
 
-## 📦 Installation
+### Tree Visualization
 
 ```ruby
-gem 'taski'
-```
-
-```bash
-bundle install
+puts WebServer.tree
+# => WebServer
+# => └── Config
+# =>     ├── Database
+# =>     └── Cache
 ```
 
-## 🧪 Testing
+## Development
 
 ```bash
-bundle exec rake test
+rake test      # Run all tests
+rake standard  # Check code style
 ```
 
-## 🏛️ Architecture
-
-- **Task Base**: Core framework
-- **Exports API**: Static dependency resolution
-- **Define API**: Dynamic dependency resolution
-- **Section API**: Abstraction layer with runtime implementation selection
-- **Instance Management**: Thread-safe lifecycle
-- **Dependency Resolver**: Topological sorting with Section support
-
-## Contributing
+## Support
 
 Bug reports and pull requests welcome at https://github.com/ahogappa/taski.
 
 ## License
 
 MIT License
-
----
-
-**Taski** - Build dependency graphs with elegant Ruby code. 🚀

data/Steepfile

@@ -0,0 +1,19 @@
+# Steepfile for Taski gem
+
+target :lib do
+  signature "sig"
+
+  check "lib"
+
+  # Ignore test and temporary files
+  ignore "test"
+  ignore "tmp"
+  ignore "examples"
+
+  # Standard library dependencies
+  library "monitor"
+  library "tsort"
+
+  # Use gems from rbs_collection
+  collection_config "rbs_collection.yaml"
+end