taski 0.1.1 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d04adfab160e07e101e7d6364796d5607a896010396950ee5d479824bb4c422e
-  data.tar.gz: aeb0ea3476853608c0ef77e80e907c79db7ea62c1aaead8a22d8232d7e4c13aa
+  metadata.gz: 4e44ea93464ceaf8994d761cec75cf4d32df7cdb8f90d25b4cfcae5be7f8a586
+  data.tar.gz: 8a1b5fae85bbffb28756f2e13b3f98c2cb8023c76346b5da722ac55e87ef3cc5
 SHA512:
-  metadata.gz: b3201ee69bc45ae1e58569bf1a98647ff7e38adabf0d04334805fdbac816468d420b1d460113970e1fc9394e6f9e6ca2fe4c700e0c390b9032366a01690c7762
-  data.tar.gz: 81a9796f7234f8f66216b61b7ea676b40614bb8258b8a6d6a0244e5d016319ea1492f7817324e1669a6ede1eeaf3f0ad4d8b71fd210168022838f66047348bff
+  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,68 +1,225 @@
 # Taski
 
-**Taski** is a Ruby-based task runner designed for small, composable processing steps.
-In Taski, you define tasks as Ruby classes that expose named values through `define`. Dependencies between tasks are established automatically when one task references the result of another—no need for explicit dependency declarations.
+[![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)
 
-Tasks are executed in a topologically sorted order, ensuring that tasks are built only after their inputs are available. Reverse execution is also supported, making it easy to clean up intermediate files or revert changes after a build.
+> **🚧 Development Status:** Taski is currently under active development. Not yet recommended for production use.
 
-> **🚧 Development Status:** Taski is currently under active development and the API may change.
+**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**.
 
-> **⚠️ Limitation:** Circular dependencies are **not** supported at this time.
+> **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.
 
-> **ℹ️ Note:** Taski does **not** infer dependencies from file contents or behavior. Instead, dependencies are implicitly established via references between task definitions.
+## 🚀 Quick Start
 
-### Features
+```ruby
+require 'taski'
 
-- Define tasks using Ruby classes
-- Implicit dependencies via reference to other task outputs
-- Topological execution order
-- Reverse execution for cleanup
-- Built entirely in Ruby
+# Static dependency using Exports API
+class DatabaseSetup < Taski::Task
+  exports :connection_string
 
-### Example
+  def build
+    @connection_string = "postgresql://localhost/myapp"
+    puts "Database configured"
+  end
+end
+
+class APIServer < Taski::Task
+  def build
+    puts "Starting API with #{DatabaseSetup.connection_string}"
+  end
+end
+
+APIServer.build
+# => Database configured
+# => Starting API with postgresql://localhost/myapp
+```
+
+## 📚 API Guide
+
+### Exports API - Static Dependencies
+
+For simple, predictable dependencies:
 
 ```ruby
-class TaskA < Taski::Task
-  define :task_a_result, -> { "Task A" }
+class ConfigLoader < Taski::Task
+  exports :app_name, :version
 
   def build
-    puts 'Processing...'
+    @app_name = "MyApp"
+    @version = "1.0.0"
+    puts "Config loaded: #{@app_name} v#{@version}"
   end
 end
 
-class TaskB < Taski::Task
-  define :simple_task, -> { "Task result is #{TaskA.task_a_result}" }
+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
+```
+
+### 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 simple_task
+    puts "Using database: #{database_service}"
+    puts "Environment: #{ENV['RAILS_ENV'] || 'development'}"
   end
 end
 
-TaskB.build
-# => Processing...
-# => Task result is Task A
+EnvironmentConfig.build
+# => Using database: localhost:5432
+# => Environment: development
+
+ENV['RAILS_ENV'] = 'production'
+EnvironmentConfig.reset!
+EnvironmentConfig.build
+# => Using database: production-db.example.com
+# => Environment: production
 ```
 
-## Installation
+### When to Use Each API
 
-Install the gem and add to the application's Gemfile by executing:
+- **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.
 
-```bash
-bundle add taski
+| 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 |
+
+## ✨ 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
+
+### 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
+```
+
+### 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
+
+WebServer.build
+# => Database connected
+# => Web server started with db-connection
+
+WebServer.clean
+# => Web server stopped
+# => Database disconnected
+```
+
+### 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
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+## 📦 Installation
+
+```ruby
+gem 'taski'
+```
 
 ```bash
-gem install taski
+bundle install
 ```
 
-## Development
+## 🧪 Testing
+
+```bash
+bundle exec rake test
+```
 
-After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+## 🏛️ Architecture
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+- **Task Base**: Core framework
+- **Exports API**: Static dependency resolution
+- **Define API**: Dynamic dependency resolution
+- **Instance Management**: Thread-safe lifecycle
+- **Dependency Resolver**: Topological sorting
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/taski.
+Bug reports and pull requests welcome at https://github.com/ahogappa/taski.
+
+## License
+
+MIT License
+
+---
+
+**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

@@ -0,0 +1,107 @@
+#!/usr/bin/env ruby
+# Complex example from README showing both APIs
+
+require_relative "../lib/taski"
+
+# Mock classes for the example
+class ProductionDB < Taski::Task
+  exports :connection_string
+  def build
+    @connection_string = "postgres://prod-server/app"
+  end
+end
+
+class TestDB < Taski::Task
+  exports :connection_string
+  def build
+    @connection_string = "postgres://test-server/app_test"
+  end
+end
+
+module FeatureFlag
+  def self.enabled?(flag)
+    ENV["FEATURE_#{flag.to_s.upcase}"] == "true"
+  end
+end
+
+class RedisService < Taski::Task
+  exports :configuration
+  def build
+    @configuration = "redis://localhost:6379"
+  end
+end
+
+# 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
+    end
+  }
+
+  def build
+    # Environment configuration is handled by define blocks
+  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
+  end
+end
+
+# 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}"
+  end
+
+  def clean
+    puts "Shutting down #{AppConfig.app_name}..."
+  end
+end
+
+# Test different environments
+puts "=== Complex Example ==="
+
+puts "\n1. Development Environment (default):"
+ENV.delete("RAILS_ENV")
+ENV.delete("FEATURE_REDIS_CACHE")
+Application.build
+Application.reset!
+
+puts "\n2. Test Environment:"
+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"
+# Reset Environment to re-evaluate define blocks
+Environment.reset!
+Application.build
+
+puts "\n4. Cleanup:"
+Application.clean

data/examples/readme_example.rb

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+# Quick Start example from README
+
+require_relative "../lib/taski"
+
+# Simple static dependency using Exports API
+class DatabaseSetup < Taski::Task
+  exports :connection_string
+
+  def build
+    @connection_string = "postgresql://localhost/myapp"
+    puts "Database configured"
+  end
+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
+puts "=== Quick Start Example ==="
+APIServer.build
+
+puts "\nResult: APIServer running on port #{APIServer.port}"

data/lib/taski/dependency_analyzer.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Taski
+  module DependencyAnalyzer
+    class << self
+      def analyze_method(klass, method_name)
+        return [] unless klass.instance_methods(false).include?(method_name)
+
+        method = klass.instance_method(method_name)
+        source_location = method.source_location
+        return [] unless source_location
+
+        file_path, line_number = source_location
+        return [] unless File.exist?(file_path)
+
+        begin
+          result = Prism.parse_file(file_path)
+
+          unless result.success?
+            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?
+            Taski.logger.warn("Parse warnings in source file",
+              file: file_path,
+              warnings: result.warnings.map(&:message),
+              method: "#{klass}##{method_name}")
+          end
+
+          dependencies = []
+          method_node = find_method_node(result.value, method_name, line_number)
+
+          if method_node
+            visitor = TaskDependencyVisitor.new
+            visitor.visit(method_node)
+            dependencies = visitor.dependencies
+          end
+
+          dependencies.uniq
+        rescue IOError, SystemCallError => e
+          Taski.logger.error("Failed to read source file",
+            file: file_path,
+            error: e.message,
+            method: "#{klass}##{method_name}")
+          []
+        rescue => e
+          Taski.logger.error("Failed to analyze method dependencies",
+            class: klass.name,
+            method: method_name,
+            error: e.message,
+            error_class: e.class.name)
+          []
+        end
+      end
+
+      private
+
+      def find_method_node(node, method_name, target_line)
+        return nil unless node
+
+        case node
+        when Prism::DefNode
+          if node.name == method_name && node.location.start_line <= target_line && node.location.end_line >= target_line
+            return node
+          end
+        when Prism::ClassNode, Prism::ModuleNode
+          if node.respond_to?(:body)
+            return find_method_node(node.body, method_name, target_line)
+          end
+        when Prism::StatementsNode
+          node.body.each do |child|
+            result = find_method_node(child, method_name, target_line)
+            return result if result
+          end
+        end
+
+        # Recursively search child nodes
+        if node.respond_to?(:child_nodes)
+          node.child_nodes.each do |child|
+            result = find_method_node(child, method_name, target_line)
+            return result if result
+          end
+        end
+
+        nil
+      end
+
+      # Task dependency visitor using Prism's visitor pattern
+      class TaskDependencyVisitor < Prism::Visitor
+        attr_reader :dependencies
+
+        def initialize
+          @dependencies = []
+          @constant_cache = {}
+        end
+
+        def visit_constant_read_node(node)
+          check_task_constant(node.name.to_s)
+          super
+        end
+
+        def visit_constant_path_node(node)
+          const_path = extract_constant_path(node)
+          check_task_constant(const_path) if const_path
+          super
+        end
+
+        def visit_call_node(node)
+          # Check for method calls on constants (e.g., TaskA.result)
+          case node.receiver
+          when Prism::ConstantReadNode
+            check_task_constant(node.receiver.name.to_s)
+          when Prism::ConstantPathNode
+            const_path = extract_constant_path(node.receiver)
+            check_task_constant(const_path) if const_path
+          end
+          super
+        end
+
+        private
+
+        def check_task_constant(const_name)
+          return unless const_name
+
+          # Use caching to avoid repeated constant resolution
+          cached_result = @constant_cache[const_name]
+          return cached_result if cached_result == false # Cached negative result
+          return @dependencies << cached_result if cached_result # Cached positive result
+
+          begin
+            if Object.const_defined?(const_name)
+              klass = Object.const_get(const_name)
+              if klass.is_a?(Class) && klass < Taski::Task
+                @constant_cache[const_name] = klass
+                @dependencies << klass
+              else
+                @constant_cache[const_name] = false
+              end
+            else
+              @constant_cache[const_name] = false
+            end
+          rescue NameError, ArgumentError
+            @constant_cache[const_name] = false
+          end
+        end
+
+        def extract_constant_path(node)
+          case node
+          when Prism::ConstantReadNode
+            node.name.to_s
+          when Prism::ConstantPathNode
+            parent_path = extract_constant_path(node.parent) if node.parent
+            child_name = node.name.to_s
+
+            if parent_path && child_name
+              "#{parent_path}::#{child_name}"
+            else
+              child_name
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/taski/exceptions.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+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