taski 0.4.0 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17f3cd1627f0b49f60b2173fcfef71ce6bbc60b6280d1d3b35cf9edb5e89ea9c
-  data.tar.gz: 25e99fdf4d4fbdc48be47a65764efd0884a71355db16c7d674b796f178bdf900
+  metadata.gz: 537249ee49e056c8841cc1c4d4061eccf7be201b3690a197af8d5a5b65939173
+  data.tar.gz: f012517341ea31b2e36f4a87e51ab199cb24d70d7ba10519653a2d290c78dcaf
 SHA512:
-  metadata.gz: 19697472cbdff99b1a4a5315be18d274637c1806b225550d3a4acb541771a618a6fd1e14156599335174e12f3dd27d7f714bd0e7c87e0c76d525ca0a3375e361
-  data.tar.gz: 20bff2f125897ca23dab9a1d78831c14e45fca5f40f2fed29bb6c1114a7d040569b2e46994614049963dcca0cb3831d8cee91ebc3dc7892a7def59e1a965198a
+  metadata.gz: e15871fa35cf862eae794b823ab760adcd1ca1156cb23b0d27d705e8c5fb0ddfa3f2dd17859f7d238a6f0e9dbf558bedf5148330ffbf239a7291f3c99b037e07
+  data.tar.gz: d1ca33867403c337c2d1638acae3a2fd47ca77a707e7df2b6076d8c22c8d289ceae73ba6e4f1f30d413c784c30f999d60648a270c3b49a398e3144d85fd63837

data/README.md

@@ -4,15 +4,11 @@
 [![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 **parallel execution**.
+**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.
+## Features
 
 - **Automatic Dependency Resolution**: Dependencies detected via static analysis
 - **Parallel Execution**: Independent tasks run concurrently for maximum performance
@@ -20,18 +16,16 @@ Build complex workflows by defining tasks and their dependencies - Taski automat
 - **Real-time Progress**: Visual feedback with parallel task progress display
 - **Thread-Safe**: Built on Monitor-based synchronization for reliable concurrent execution
 
-## 🚀 Quick Start
+## Quick Start
 
 ```ruby
 require 'taski'
 
-# Define tasks with dependencies
 class DatabaseSetup < Taski::Task
   exports :connection_string
 
   def run
     @connection_string = "postgresql://localhost/myapp"
-    puts "Database configured"
   end
 end
 
@@ -40,31 +34,32 @@ class CacheSetup < Taski::Task
 
   def run
     @cache_url = "redis://localhost:6379"
-    puts "Cache configured"
   end
 end
 
 class APIServer < Taski::Task
   def run
     # Dependencies execute automatically and in parallel
-    puts "Starting API with #{DatabaseSetup.connection_string}"
-    puts "Using cache at #{CacheSetup.cache_url}"
+    puts "DB: #{DatabaseSetup.connection_string}"
+    puts "Cache: #{CacheSetup.cache_url}"
   end
 end
 
-# 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
+```
+
+## Installation
+
+```ruby
+gem 'taski'
 ```
 
 ## Core Concepts
 
-Taski provides two complementary APIs:
+### Exports - Value Sharing Between Tasks
+
+Share computed values between tasks:
 
-### 1. Exports API - Value Sharing Between Tasks
 ```ruby
 class Config < Taski::Task
   exports :app_name, :port
@@ -77,26 +72,27 @@ end
 
 class Server < Taski::Task
   def run
-    # Automatically depends on Config task
     puts "Starting #{Config.app_name} on port #{Config.port}"
   end
 end
 ```
 
-### 2. Section API - Runtime Implementation Selection
+### Section - Runtime Implementation Selection
+
+Switch implementations based on environment:
+
 ```ruby
 class DatabaseSection < Taski::Section
   interfaces :host, :port
 
-  # Nested classes automatically inherit interfaces - no exports needed
-  class ProductionDB < Taski::Task
+  class Production < Taski::Task
     def run
       @host = "prod.example.com"
       @port = 5432
     end
   end
 
-  class LocalDB < Taski::Task
+  class Development < Taski::Task
     def run
       @host = "localhost"
       @port = 5432
@@ -104,97 +100,67 @@ class DatabaseSection < Taski::Section
   end
 
   def impl
-    # Select implementation at runtime
-    ENV['RAILS_ENV'] == 'production' ? ProductionDB : LocalDB
+    ENV['RAILS_ENV'] == 'production' ? Production : Development
   end
 end
 
 class App < Taski::Task
   def run
-    # Access through Section - implementation selected at runtime
     puts "Connecting to #{DatabaseSection.host}:#{DatabaseSection.port}"
   end
 end
-
-App.run
-# In development (RAILS_ENV != 'production'):
-# => Connecting to localhost:5432
-
-# In production (RAILS_ENV == 'production'):
-# => Connecting to prod.example.com:5432
 ```
 
-**When to use each:**
-- **Exports**: Share computed values or side effects between tasks
-- **Section**: Switch implementations based on environment or conditions
+> **Note**: Nested implementation classes automatically inherit Section's `interfaces` as `exports`.
 
-> **Note**: When implementation classes are nested inside a Section, they automatically inherit the Section's `interfaces` as `exports`. External implementations must declare `exports` explicitly.
+## Advanced Usage
 
-### 3. Context - Runtime Information Access
+### Context - Runtime Information and Options
 
-Access execution context information from any task:
+Pass custom options and access execution context from any task:
 
 ```ruby
 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}"
+    # User-defined options
+    env = Taski.context[:env]
+    debug = Taski.context.fetch(:debug, false)
+
+    # 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
-```
-
-**Available context:**
-- `working_directory`: Directory where execution started
-- `started_at`: Time when execution began
-- `root_task`: The first task class that was called
 
-> **Note**: Context is not included in dependency analysis - it provides runtime information only.
-
-> **Important**: Tasks must be defined in source files, not dynamically with `Class.new`. Static analysis requires actual source files to detect dependencies.
+# Pass options when running
+DeployTask.run(context: { env: "production", debug: true })
+```
 
-### 4. Re-execution with `new`
+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
 
-By default, task results are cached. Use `new` to create a fresh instance for re-execution:
+### Re-execution
 
 ```ruby
-class RandomTask < Taski::Task
-  exports :value
-
-  def run
-    @value = rand(1000)
-  end
-end
-
-# Cached execution (same result)
+# Cached execution (default)
 RandomTask.value  # => 42
 RandomTask.value  # => 42 (cached)
 
-# Fresh execution with new
+# Fresh execution
 RandomTask.new.run  # => 123 (new instance)
-RandomTask.new.run  # => 456 (another new instance)
 
 # Reset all caches
 RandomTask.reset!
-RandomTask.value  # => 789 (fresh after reset)
 ```
 
-**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
-
-## Key Features
-
-- **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
-
-### Parallel Progress Display
+### Progress Display
 
 Enable real-time progress visualization:
 
@@ -202,14 +168,11 @@ Enable real-time progress visualization:
 TASKI_FORCE_PROGRESS=1 ruby your_script.rb
 ```
 
-Output example:
 ```
 ⠋ DatabaseSetup (running)
 ⠙ CacheSetup (running)
 ✅ DatabaseSetup (123.4ms)
 ✅ CacheSetup (98.2ms)
-⠸ WebServer (running)
-✅ WebServer (45.1ms)
 ```
 
 ### Tree Visualization
@@ -222,33 +185,13 @@ puts WebServer.tree
 # =>     └── Cache
 ```
 
-## 📦 Installation
-
-```ruby
-gem 'taski'
-```
-
-```bash
-bundle install
-```
-
-## 🧪 Testing
+## Development
 
 ```bash
 rake test      # Run all tests
 rake standard  # Check code style
 ```
 
-## 📚 Learn More
-
-- **[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
-
 ## Support
 
 Bug reports and pull requests welcome at https://github.com/ahogappa/taski.
@@ -256,7 +199,3 @@ Bug reports and pull requests welcome at https://github.com/ahogappa/taski.
 ## License
 
 MIT License
-
----
-
-**Taski** - Parallel task execution with automatic dependency resolution. 🚀

data/examples/README.md

@@ -34,18 +34,21 @@ ruby examples/section_demo.rb
 
 ---
 
-### 3. context_demo.rb - Runtime Context
+### 3. context_demo.rb - Runtime Context and Options
 
-Access execution context information from any task.
+Access execution context and pass custom options to tasks.
 
 ```bash
 ruby examples/context_demo.rb
 ```
 
 **Covers:**
-- `Taski::Context.working_directory`
-- `Taski::Context.started_at`
-- `Taski::Context.root_task`
+- User-defined options via `run(context: {...})`
+- `Taski.context[:key]` for option access
+- `Taski.context.fetch(:key, default)` for defaults
+- `Taski.context.working_directory`
+- `Taski.context.started_at`
+- `Taski.context.root_task`
 
 ---
 

data/examples/context_demo.rb

@@ -7,6 +7,7 @@
 # - working_directory: Where execution started
 # - started_at: When execution began
 # - root_task: The first task class that was called
+# - User-defined options: Custom values passed via run(context: {...})
 #
 # Run: ruby examples/context_demo.rb
 
@@ -21,13 +22,15 @@ class SetupTask < Taski::Task
 
   def run
     puts "Setup running..."
-    puts "  Working directory: #{Taski::Context.working_directory}"
-    puts "  Started at: #{Taski::Context.started_at}"
-    puts "  Root task: #{Taski::Context.root_task}"
+    puts "  Working directory: #{Taski.context.working_directory}"
+    puts "  Started at: #{Taski.context.started_at}"
+    puts "  Root task: #{Taski.context.root_task}"
+    puts "  Environment: #{Taski.context[:env]}"
 
     @setup_info = {
-      directory: Taski::Context.working_directory,
-      timestamp: Taski::Context.started_at
+      directory: Taski.context.working_directory,
+      timestamp: Taski.context.started_at,
+      env: Taski.context[:env]
     }
   end
 end
@@ -38,11 +41,12 @@ class FileProcessor < Taski::Task
 
   def run
     # Use context to determine output location
-    base_dir = Taski::Context.working_directory
-    @output_path = File.join(base_dir, "tmp", "output.txt")
+    base_dir = Taski.context.working_directory
+    env = Taski.context.fetch(:env, "development")
+    @output_path = File.join(base_dir, "tmp", env, "output.txt")
 
     puts "FileProcessor: Would write to #{@output_path}"
-    puts "  (relative to working directory)"
+    puts "  (relative to working directory, env: #{env})"
   end
 end
 
@@ -51,11 +55,12 @@ class TimingTask < Taski::Task
   exports :duration_info
 
   def run
-    start_time = Taski::Context.started_at
+    start_time = Taski.context.started_at
     current_time = Time.now
     elapsed = current_time - start_time
 
     puts "TimingTask: #{elapsed.round(3)}s since execution started"
+    puts "  Debug mode: #{Taski.context.fetch(:debug, false)}"
 
     @duration_info = {
       started: start_time,
@@ -71,7 +76,8 @@ class MainTask < Taski::Task
 
   def run
     puts "\nMainTask executing..."
-    puts "  Root task is: #{Taski::Context.root_task}"
+    puts "  Root task is: #{Taski.context.root_task}"
+    puts "  Environment: #{Taski.context[:env]}"
 
     # Access dependencies
     setup = SetupTask.setup_info
@@ -82,7 +88,7 @@ class MainTask < Taski::Task
       setup: setup,
       output_path: output,
       timing: timing,
-      root_task: Taski::Context.root_task.to_s
+      root_task: Taski.context.root_task.to_s
     }
 
     puts "\nExecution Summary:"
@@ -92,15 +98,15 @@ class MainTask < Taski::Task
   end
 end
 
-puts "\n1. Running MainTask (context will show MainTask as root)"
+puts "\n1. Running MainTask with context options"
 puts "-" * 40
-MainTask.run
+MainTask.run(context: {env: "production", debug: true})
 
 puts "\n" + "=" * 40
-puts "\n2. Running SetupTask directly (context will show SetupTask as root)"
+puts "\n2. Running SetupTask directly with different context"
 puts "-" * 40
 SetupTask.reset!
-SetupTask.run
+SetupTask.run(context: {env: "staging"})
 
 puts "\n" + "=" * 40
 puts "\n3. Dependency Tree"
@@ -109,4 +115,4 @@ puts MainTask.tree
 
 puts "\n" + "=" * 40
 puts "Context API demonstration complete!"
-puts "Note: Context provides runtime information without affecting dependency analysis."
+puts "Note: Context provides runtime information and user options without affecting dependency analysis."

data/lib/taski/context.rb

@@ -3,50 +3,48 @@
 require "monitor"
 
 module Taski
-  # Runtime context accessible from any task (not included in dependency analysis).
+  # Runtime context accessible from any task.
+  # Holds user-defined options and execution metadata.
+  # Context is immutable after creation - options cannot be modified during task execution.
   class Context
-    @monitor = Monitor.new
+    attr_reader :started_at, :working_directory, :root_task
 
-    class << self
-      # @return [String] The working directory path
-      def working_directory
-        @monitor.synchronize do
-          @working_directory ||= Dir.pwd
-        end
-      end
-
-      # @return [Time] The start time
-      def started_at
-        @monitor.synchronize do
-          @started_at ||= Time.now
-        end
-      end
+    # @param options [Hash] User-defined options (immutable after creation)
+    # @param root_task [Class] The root task class that initiated execution
+    def initialize(options:, root_task:)
+      @options = options.dup.freeze
+      @root_task = root_task
+      @started_at = Time.now
+      @working_directory = Dir.pwd
+    end
 
-      # @return [Class, nil] The root task class or nil if not set
-      def root_task
-        @monitor.synchronize do
-          @root_task
-        end
-      end
+    # Get a user-defined option value
+    # @param key [Symbol, String] The option key
+    # @return [Object, nil] The option value or nil if not set
+    def [](key)
+      @options[key]
+    end
 
-      # Called internally when a task is first invoked. Only the first call has effect.
-      # @param task_class [Class] The task class to set as root
-      def set_root_task(task_class)
-        @monitor.synchronize do
-          return if @root_task
-          @root_task = task_class
-          @started_at ||= Time.now
-          @working_directory ||= Dir.pwd
-        end
+    # Get a user-defined option value with a default
+    # @param key [Symbol, String] The option key
+    # @param default [Object] Default value if key is not present
+    # @yield Block to compute default value if key is not present
+    # @return [Object] The option value or default
+    def fetch(key, default = nil, &block)
+      if @options.key?(key)
+        @options[key]
+      elsif block
+        block.call
+      else
+        default
       end
+    end
 
-      def reset!
-        @monitor.synchronize do
-          @working_directory = nil
-          @started_at = nil
-          @root_task = nil
-        end
-      end
+    # Check if a user-defined option key exists
+    # @param key [Symbol, String] The option key
+    # @return [Boolean] true if the key exists
+    def key?(key)
+      @options.key?(key)
     end
   end
 end

data/lib/taski/section.rb

@@ -9,6 +9,13 @@ module Taski
       def interfaces(*interface_methods)
         exports(*interface_methods)
       end
+
+      # Section does not have static dependencies for execution.
+      # The impl method is called at runtime to determine the actual implementation.
+      # Static dependencies (impl candidates) are only used for tree display and circular detection.
+      def cached_dependencies
+        Set.new
+      end
     end
 
     def run

data/lib/taski/static_analysis/analyzer.rb

@@ -6,29 +6,50 @@ require_relative "visitor"
 module Taski
   module StaticAnalysis
     class Analyzer
+      # Analyzes a task class and returns its static dependencies.
+      # For Task: dependencies detected from run method (SomeTask.method calls)
+      # For Section: impl candidates detected from impl method (constants returned)
+      #
+      # Static dependencies are used for:
+      # - Tree display visualization
+      # - Circular dependency detection
+      # - Task execution (for Task only; Section resolves impl at runtime)
+      #
       # @param task_class [Class] The task class to analyze
-      # @return [Set<Class>] Set of task classes that are dependencies
+      # @return [Set<Class>] Set of task classes that are static dependencies
       def self.analyze(task_class)
-        source_location = extract_run_method_location(task_class)
+        target_method = target_method_for(task_class)
+        source_location = extract_method_location(task_class, target_method)
         return Set.new unless source_location
 
         file_path, _line_number = source_location
         parse_result = Prism.parse_file(file_path)
 
-        visitor = Visitor.new(task_class)
+        visitor = Visitor.new(task_class, target_method)
         visitor.visit(parse_result.value)
         visitor.dependencies
       end
 
       # @param task_class [Class] The task class
+      # @return [Symbol] The method name to analyze (:run for Task, :impl for Section)
+      def self.target_method_for(task_class)
+        if defined?(Taski::Section) && task_class < Taski::Section
+          :impl
+        else
+          :run
+        end
+      end
+
+      # @param task_class [Class] The task class
+      # @param method_name [Symbol] The method name to extract location for
       # @return [Array<String, Integer>, nil] File path and line number, or nil
-      def self.extract_run_method_location(task_class)
-        task_class.instance_method(:run).source_location
+      def self.extract_method_location(task_class, method_name)
+        task_class.instance_method(method_name).source_location
       rescue NameError
         nil
       end
 
-      private_class_method :extract_run_method_location
+      private_class_method :target_method_for, :extract_method_location
     end
   end
 end

data/lib/taski/static_analysis/visitor.rb

@@ -7,11 +7,14 @@ module Taski
     class Visitor < Prism::Visitor
       attr_reader :dependencies
 
-      def initialize(target_task_class)
+      # @param target_task_class [Class] The task class to analyze
+      # @param target_method [Symbol] The method name to analyze (:run or :impl)
+      def initialize(target_task_class, target_method = :run)
         super()
         @target_task_class = target_task_class
+        @target_method = target_method
         @dependencies = Set.new
-        @in_target_run_method = false
+        @in_target_method = false
         @current_namespace_path = []
       end
 
@@ -24,17 +27,29 @@ module Taski
       end
 
       def visit_def_node(node)
-        if node.name == :run && in_target_class?
-          @in_target_run_method = true
+        if node.name == @target_method && in_target_class?
+          @in_target_method = true
           super
-          @in_target_run_method = false
+          @in_target_method = false
         else
           super
         end
       end
 
       def visit_call_node(node)
-        detect_task_dependency(node) if @in_target_run_method
+        detect_task_dependency(node) if @in_target_method
+        super
+      end
+
+      def visit_constant_read_node(node)
+        # For Section.impl, detect constants as impl candidates (static dependencies)
+        detect_impl_candidate(node) if in_impl_method?
+        super
+      end
+
+      def visit_constant_path_node(node)
+        # For Section.impl, detect constants as impl candidates (static dependencies)
+        detect_impl_candidate(node) if in_impl_method?
         super
       end
 
@@ -55,6 +70,15 @@ module Taski
         node.slice
       end
 
+      def in_impl_method?
+        @in_target_method && @target_method == :impl
+      end
+
+      def detect_impl_candidate(node)
+        constant_name = node.slice
+        resolve_and_add_dependency(constant_name)
+      end
+
       def detect_task_dependency(node)
         return unless node.receiver