taski 0.3.1 → 0.4.0

data/.gem_rbs_collection/simplecov/0.22/.rbs_meta.yaml

@@ -0,0 +1,9 @@
+---
+name: simplecov
+version: '0.22'
+source:
+  type: git
+  name: ruby/gem_rbs_collection
+  revision: 3a33fa6f8e486f880c80ca401f2be1c1f621cf11
+  remote: https://github.com/ruby/gem_rbs_collection.git
+  repo_dir: gems

data/.gem_rbs_collection/simplecov/0.22/simplecov.rbs

@@ -0,0 +1,54 @@
+module SimpleCov
+  extend Configuration
+
+  VERSION: String
+
+  def self.collate: (Array[String] result_filenames) -> void
+
+  def self.start: (?(String | Symbol | nil) profile) ?{ [self: Configuration] -> void } -> void
+
+  module Configuration
+    type filter = String
+                | Regexp
+                | Filter[untyped]
+                | ^(SourceFile source_file) -> boolish
+                | Array[filter]
+
+    type criterion = :line | :branch
+
+    def add_filter: (filter filter_argument) -> void
+                  | { (SourceFile source_file) -> boolish } -> void
+
+    def add_group: (String group_name, filter filter_argument) -> untyped
+                 | (String group_name) { (SourceFile source_file) -> boolish } -> void
+
+    def command_name: (String name) -> void
+
+    def enable_coverage: (criterion criterion) -> void
+
+    def enable_coverage_for_eval: () -> void
+
+    def filters: () -> Array[Filter[untyped]]
+
+    def primary_coverage: (criterion criterion) -> void
+
+    def root: (?String? root) -> String?
+  end
+
+  class SourceFile
+    attr_reader filename: String?
+
+    def lines: () -> Array[Line]
+
+    class Line
+    end
+  end
+
+  class Filter[T]
+    attr_reader filter_argument: T
+
+    def initialize: (T filter_argument) -> void
+
+    def matches?: (SourceFile source_file) -> boolish
+  end
+end

data/README.md

@@ -6,331 +6,220 @@
 
 > **🚧 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.
 
+## Why Taski?
+
+Build complex workflows by defining tasks and their dependencies - Taski automatically resolves execution order and executes them in parallel.
+
+- **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
+# Define tasks with dependencies
 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"
+    puts "Cache configured"
+  end
+end
+
 class APIServer < Taski::Task
-  def build
+  def run
+    # Dependencies execute automatically and in parallel
     puts "Starting API with #{DatabaseSetup.connection_string}"
+    puts "Using cache at #{CacheSetup.cache_url}"
   end
 end
 
-APIServer.build
+# Run any task - dependencies resolve and execute in parallel
+APIServer.run
 # => Database configured
+# => Cache configured
 # => Starting API with postgresql://localhost/myapp
+# => Using cache at redis://localhost:6379
 ```
 
-## 📚 API Guide
-
-### Exports API - Static Dependencies
+## Core Concepts
 
-For simple, predictable dependencies:
+Taski provides two complementary APIs:
 
+### 1. Exports API - Value Sharing Between Tasks
 ```ruby
-class ConfigLoader < Taski::Task
-  exports :app_name, :version
+class Config < Taski::Task
+  exports :app_name, :port
 
-  def build
+  def run
     @app_name = "MyApp"
-    @version = "1.0.0"
-    puts "Config loaded: #{@app_name} v#{@version}"
+    @port = 3000
   end
 end
 
-class Deployment < Taski::Task
-  def build
-    @deploy_url = "https://#{ConfigLoader.app_name}.example.com"
-    puts "Deploying to #{@deploy_url}"
+class Server < Taski::Task
+  def run
+    # Automatically depends on Config task
+    puts "Starting #{Config.app_name} on port #{Config.port}"
   end
 end
-
-Deployment.build
-# => Config loaded: MyApp v1.0.0
-# => Deploying to https://MyApp.example.com
-```
-
-### Define API - Dynamic Dependencies
-
-For dependencies that change based on runtime conditions:
-
-```ruby
-class EnvironmentConfig < Taski::Task
-  define :database_service, -> {
-    case ENV['RAILS_ENV']
-    when 'production'
-      "production-db.example.com"
-    else
-      "localhost:5432"
-    end
-  }
-
-  def build
-    puts "Using database: #{database_service}"
-    puts "Environment: #{ENV['RAILS_ENV'] || 'development'}"
-  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
 ```
 
-### Section API - Abstraction Layers
-
-For environment-specific implementations with clean interfaces:
-
+### 2. Section API - Runtime Implementation Selection
 ```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"
+  # Nested classes automatically inherit interfaces - no exports needed
+  class ProductionDB < Taski::Task
+    def run
+      @host = "prod.example.com"
       @port = 5432
     end
   end
 
-  class Development < Taski::Task
-    def build
+  class LocalDB < Taski::Task
+    def run
       @host = "localhost"
       @port = 5432
     end
   end
-end
 
-# Usage is simple - Section works like any Task
-class App < Taski::Task
-  def build
-    puts "DB: #{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**: 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.
-
-## ✨ Key Features
-
-- **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:
-
-```ruby
-class Database < Taski::Task
-  exports :connection
-  def build; @connection = "db-conn"; end
-end
-
-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
-    }
+  def impl
+    # Select implementation at runtime
+    ENV['RAILS_ENV'] == 'production' ? ProductionDB : LocalDB
   end
 end
 
-class WebServer < Taski::Task
-  def build
-    puts "Starting with #{Config.settings}"
+class App < Taski::Task
+  def run
+    # Access through Section - implementation selected at runtime
+    puts "Connecting to #{DatabaseSection.host}:#{DatabaseSection.port}"
   end
 end
 
-puts WebServer.tree
-# => WebServer
-# => └── Config
-# =>     ├── Database
-# =>     └── Cache
+App.run
+# In development (RAILS_ENV != 'production'):
+# => Connecting to localhost:5432
 
-# Sections also appear in dependency trees
-puts AppServer.tree
-# => AppServer
-# => └── DatabaseSection
+# In production (RAILS_ENV == 'production'):
+# => Connecting to prod.example.com:5432
 ```
 
-### Progress Display
+**When to use each:**
+- **Exports**: Share computed values or side effects between tasks
+- **Section**: Switch implementations based on environment or conditions
+
+> **Note**: When implementation classes are nested inside a Section, they automatically inherit the Section's `interfaces` as `exports`. External implementations must declare `exports` explicitly.
+
+### 3. Context - Runtime Information Access
 
-Taski provides visual feedback during task execution with animated spinners and real-time output capture:
+Access execution context information from any task:
 
 ```ruby
-class LongRunningTask < Taski::Task
-  def build
-    puts "Starting process..."
-    sleep(1.0)
-    puts "Processing data..."
-    puts "Almost done..."
-    sleep(0.5)
-    puts "Completed!"
+class DeployTask < Taski::Task
+  def run
+    puts "Working directory: #{Taski::Context.working_directory}"
+    puts "Started at: #{Taski::Context.started_at}"
+    puts "Root task: #{Taski::Context.root_task}"
   end
 end
-
-LongRunningTask.build
-# During execution shows:
-# ⠧ LongRunningTask
-#   Starting process...
-#   Processing data...
-#   Almost done...
-#   Completed!
-#
-# After completion shows:
-# ✅ LongRunningTask (1500ms)
 ```
 
-**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
-
-### Granular Task Execution
+**Available context:**
+- `working_directory`: Directory where execution started
+- `started_at`: Time when execution began
+- `root_task`: The first task class that was called
 
-Execute any task individually - Taski builds only required dependencies:
+> **Note**: Context is not included in dependency analysis - it provides runtime information only.
 
-```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
+> **Important**: Tasks must be defined in source files, not dynamically with `Class.new`. Static analysis requires actual source files to detect dependencies.
 
-# Access values (triggers build if needed)
-puts ConfigLoader.version    # Builds ConfigLoader if not built
-# => 1.0.0
-```
+### 4. Re-execution with `new`
 
-### Lifecycle Management
-
-Tasks can define both build and clean methods. Clean operations run in reverse dependency order:
+By default, task results are cached. Use `new` to create a fresh instance for re-execution:
 
 ```ruby
-class DatabaseSetup < Taski::Task
-  exports :connection
+class RandomTask < Taski::Task
+  exports :value
 
-  def build
-    @connection = "db-connection"
-    puts "Database connected"
-  end
-
-  def clean
-    puts "Database disconnected"
+  def run
+    @value = rand(1000)
   end
 end
 
-class WebServer < Taski::Task
-  def build
-    puts "Web server started with #{DatabaseSetup.connection}"
-  end
-
-  def clean
-    puts "Web server stopped"
-  end
-end
+# Cached execution (same result)
+RandomTask.value  # => 42
+RandomTask.value  # => 42 (cached)
 
-WebServer.build
-# => Database connected
-# => Web server started with db-connection
+# Fresh execution with new
+RandomTask.new.run  # => 123 (new instance)
+RandomTask.new.run  # => 456 (another new instance)
 
-WebServer.clean
-# => Web server stopped
-# => Database disconnected
+# Reset all caches
+RandomTask.reset!
+RandomTask.value  # => 789 (fresh after reset)
 ```
 
-### Clean Method Idempotency
+**When to use:**
+- `TaskClass.run` / `TaskClass.value`: Normal execution with caching (recommended for dependency graphs)
+- `TaskClass.new.run`: Re-execute only this task (dependencies still use cache)
+- `TaskClass.reset!`: Clear all caches and re-execute everything
 
-**Important**: The `clean` method must be idempotent - safe to call multiple times without errors.
+## Key Features
 
-```ruby
-class FileTask < Taski::Task
-  exports :output_file
+- **Parallel Execution**: Independent tasks run concurrently using threads
+- **Static Analysis**: Dependencies detected automatically via Prism AST parsing
+- **Thread-Safe**: Monitor-based synchronization ensures safe concurrent access
+- **Progress Display**: Real-time visual feedback with spinner animations and timing
+- **Tree Visualization**: See your dependency graph structure
+- **Graceful Abort**: Stop execution cleanly without starting new tasks (Ctrl+C)
+- **Runtime Context**: Access execution information from any task
 
-  def build
-    @output_file = '/tmp/data.csv'
-    File.write(@output_file, process_data)
-  end
+### Parallel Progress Display
 
-  def clean
-    # ❌ Bad: Raises error if file doesn't exist
-    # File.delete(@output_file)
+Enable real-time progress visualization:
 
-    # ✅ Good: Check before delete
-    File.delete(@output_file) if File.exist?(@output_file)
-  end
-end
+```bash
+TASKI_FORCE_PROGRESS=1 ruby your_script.rb
 ```
 
-### Error Handling
+Output example:
+```
+⠋ DatabaseSetup (running)
+⠙ CacheSetup (running)
+✅ DatabaseSetup (123.4ms)
+✅ CacheSetup (98.2ms)
+⠸ WebServer (running)
+✅ WebServer (45.1ms)
+```
+
+### Tree Visualization
 
 ```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
+puts WebServer.tree
+# => WebServer
+# => └── Config
+# =>     ├── Database
+# =>     └── Cache
 ```
 
 ## 📦 Installation
@@ -346,19 +235,21 @@ bundle install
 ## 🧪 Testing
 
 ```bash
-bundle exec rake test
+rake test      # Run all tests
+rake standard  # Check code style
 ```
 
-## 🏛️ Architecture
+## 📚 Learn More
 
-- **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
+- **[Examples](examples/)**: Practical examples from basic to advanced patterns
+- **[Tests](test/)**: Comprehensive test suite showing real-world usage
+- **[Source Code](lib/taski/)**: Clean, well-documented implementation
+  - `lib/taski/task.rb` - Core Task implementation with exports API
+  - `lib/taski/section.rb` - Section API for runtime selection
+  - `lib/taski/execution/` - Parallel execution engine
+  - `lib/taski/static_analysis/` - Prism-based dependency analyzer
 
-## Contributing
+## Support
 
 Bug reports and pull requests welcome at https://github.com/ahogappa/taski.
 
@@ -368,4 +259,4 @@ MIT License
 
 ---
 
-**Taski** - Build dependency graphs with elegant Ruby code. 🚀
+**Taski** - Parallel task execution with automatic dependency resolution. 🚀

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