taski 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c018d3aa27087ea7f87e11e01833ffe9c2e6118cc59af29f7f718b7706d108f
-  data.tar.gz: c18eb90fcfab955b8576b6329ee5df932fcdb8cfed9079c8705656c9e8b90de9
+  metadata.gz: 80c881415617aa09fb7ae24441c38c677af816c20f356cc06ea82bba50639820
+  data.tar.gz: cc0c6e07e3f53c312844dc237ebebe344a0201bb772f1c6c20ee8c6476b9db30
 SHA512:
-  metadata.gz: ea18fc4b07667fd17f2a37356c6a92c54daeadd4f7ad986d5e6131a4a717baf985548845789a17f8b5f5508de70354359a7413b957510d080b041c2f9cde6067
-  data.tar.gz: '08d4ce07b0bcde870805a2d5b0daf38d6a3cb850bc0e4da8b197c71b906d9f854fc8c97963362bd7b404b1709ded3d2d53975314bc31b19aab3967bdba903a19'
+  metadata.gz: 5e40462d8b2b359c17f28f16ec03524ee649324eb4e21eaf365fd147ccedad6bb3d683ece9021975683b1b121c93ad1da2bdaa0fed82ec37797090fadc79129c
+  data.tar.gz: 441c9553cded529843af032347f4590f9b6a289bd00f3a8ccbbe996b6be43d2154bc6e2fc4f84a94c1f18c35eb4cfcf5408ff07f6b8878b4f50e41c32a407756

data/README.md

@@ -105,7 +105,7 @@ For environment-specific implementations with clean interfaces:
 class DatabaseSection < Taski::Section
   interface :host, :port
 
-  def impl  # No 'self' needed!
+  def impl
     ENV['RAILS_ENV'] == 'production' ? Production : Development
   end
 
@@ -122,8 +122,6 @@ class DatabaseSection < Taski::Section
       @port = 5432
     end
   end
-
-  apply_auto_exports  # DRY - auto-adds exports to nested tasks
 end
 
 # Usage is simple - Section works like any Task

data/examples/section_configuration.rb

@@ -58,9 +58,6 @@ class DatabaseSection < Taski::Section
       @pool_size = 5
     end
   end
-
-  # Apply auto-exports after all nested Task classes are defined
-  apply_auto_exports
 end
 
 # Example 2: API Configuration Section
@@ -98,9 +95,6 @@ class ApiSection < Taski::Section
       @retry_count = 1
     end
   end
-
-  # Apply auto-exports after all nested Task classes are defined
-  apply_auto_exports
 end
 
 # Example 3: Task that depends on multiple sections

data/lib/taski/dependency_analyzer.rb

@@ -165,10 +165,11 @@ module Taski
           begin
             resolved_class = nil
 
-            # 1. Try absolute reference first (existing logic)
+            # Try absolute reference first for performance and clarity
             if Object.const_defined?(const_name)
               resolved_class = Object.const_get(const_name)
-            # 2. Try relative reference within namespace context
+            # Fall back to relative reference for nested module support
+            # This enables tasks defined inside modules to reference siblings
             elsif @context_class
               resolved_class = resolve_relative_constant(const_name)
             end

data/lib/taski/progress/display_manager.rb

@@ -63,7 +63,8 @@ module Taski
 
         lines_count = 0
 
-        # Only display current task with spinner (no past completed tasks during execution)
+        # Show only current task to maintain clean, focused UI
+        # Displaying all past completed tasks creates visual clutter and reduces readability
         @terminal.puts @formatter.format_current_task(spinner_char, task_name)
         lines_count += 1
 
@@ -85,7 +86,8 @@ module Taski
         @output_capture.stop
         clear_current_display
 
-        # Include captured output if requested (typically for test environments)
+        # Test environments need output for verification, production prefers concise display
+        # Conditional inclusion balances debugging needs with user experience
         if @include_captured_output && captured_output.any?
           captured_output.each do |line|
             @terminal.puts line.chomp

data/lib/taski/progress/spinner_animation.rb

@@ -28,12 +28,15 @@ module Taski
             sleep FRAME_DELAY
           end
         rescue
-          # Silently handle thread errors
+          # Prevent crashes during app shutdown or forced thread termination
+          # Progress display is auxiliary - errors shouldn't affect main processing
         end
       end
 
       def stop
         @running = false
+        # 0.2s timeout prevents hanging during rapid task execution
+        # UI responsiveness is more important than perfect cleanup
         @thread&.join(0.2)
         @thread = nil
       end

data/lib/taski/progress_display.rb

@@ -20,8 +20,6 @@ module Taski
       @spinner = Progress::SpinnerAnimation.new
       @output_capture = Progress::OutputCapture.new(output)
 
-      # Default to including captured output in test environments (when output != $stdout)
-      # This ensures test output is visible in the test output stream
       include_captured_output = include_captured_output.nil? ? (output != $stdout) : include_captured_output
       @display_manager = Progress::DisplayManager.new(@terminal, @spinner, @output_capture, include_captured_output: include_captured_output)
 

data/lib/taski/section.rb

@@ -117,7 +117,7 @@ module Taski
         colored_section_name = color ? TreeColors.section(section_name) : section_name
         result = "#{prefix}#{colored_section_name}\n"
 
-        # Add possible implementations (一般化 - detect from nested Task classes)
+        # Add possible implementations - detect from nested Task classes
         possible_implementations = find_possible_implementations
         if possible_implementations.any?
           impl_names = possible_implementations.map { |impl| extract_implementation_name(impl) }
@@ -174,6 +174,9 @@ module Taski
             end
           end
         end
+
+        # Automatically apply exports to existing nested Task classes
+        auto_apply_exports_to_existing_tasks
       end
 
       # Get the interface exports for this section
@@ -214,9 +217,10 @@ module Taski
         result
       end
 
-      # Apply auto-exports to all nested Task classes
-      # Call this method after defining nested Task classes to automatically add exports
-      def apply_auto_exports
+      private
+
+      # Automatically apply exports to existing nested Task classes when interface is defined
+      def auto_apply_exports_to_existing_tasks
         constants.each do |const_name|
           const_value = const_get(const_name)
           if const_value.is_a?(Class) && const_value < Taski::Task && !interface_exports.empty?

data/lib/taski/task/base.rb

@@ -20,7 +20,7 @@ module Taski
       def method_added(method_name)
         super
         return unless ANALYZED_METHODS.include?(method_name)
-        # Only call if the method is available (loaded by dependency_resolver)
+        # Avoid calling before dependency_resolver module is loaded
         analyze_dependencies_at_definition if respond_to?(:analyze_dependencies_at_definition, true)
       end
 
@@ -29,7 +29,8 @@ module Taski
       # @return [Reference] A reference object
       def ref(klass)
         reference = Reference.new(klass)
-        # If we're in a define context, throw for dependency tracking
+        # Use throw/catch mechanism for dependency collection during define API analysis
+        # This allows catching unresolved references without unwinding the entire call stack
         if Thread.current[TASKI_ANALYZING_DEFINE_KEY]
           reference.tap { |ref| throw :unresolved, ref }
         else
@@ -84,7 +85,7 @@ module Taski
     # Clean method with default empty implementation
     # Subclasses can override this method to implement cleanup logic
     def clean
-      # Default implementation does nothing
+      # Default implementation does nothing - allows optional cleanup in subclasses
     end
   end
 end

data/lib/taski/task/define_api.rb

@@ -16,7 +16,8 @@ module Taski
         @dependencies ||= []
         @definitions ||= {}
 
-        # Ensure ref method is defined first time define is called
+        # Enable forward declarations by creating ref method on first define usage
+        # This allows tasks to reference other tasks before they're defined
         create_ref_method_if_needed
 
         # Create method that tracks dependencies on first call
@@ -61,7 +62,7 @@ module Taski
           def self.#{name}
             __resolve__[__callee__] ||= false
             if __resolve__[__callee__]
-              # already resolved
+              # already resolved - prevents infinite recursion
             else
               __resolve__[__callee__] = true
               throw :unresolved, [self, __callee__]
@@ -93,7 +94,8 @@ module Taski
         # Reset resolution state
         classes.each do |task_class|
           klass = task_class[:klass]
-          # Only reset Task classes, not Reference objects
+          # Reference objects are stateless but Task classes store analysis state
+          # Selective reset prevents errors while ensuring clean state for next analysis
           if klass.respond_to?(:instance_variable_set) && !klass.is_a?(Taski::Reference)
             klass.instance_variable_set(:@__resolve__, {})
           end

data/lib/taski/task/exports_api.rb

@@ -15,12 +15,10 @@ module Taski
         names.each do |name|
           next if respond_to?(name)
 
-          # Define class method to access exported value
           define_singleton_method(name) do
             ensure_instance_built.send(name)
           end
 
-          # Define instance method getter
           define_method(name) do
             instance_variable_get("@#{name}")
           end

data/lib/taski/task/instance_management.rb

@@ -12,14 +12,12 @@ module Taski
       # @return [Task] Returns task instance (singleton or temporary)
       def build(**args)
         if args.empty?
-          # Traditional build: singleton instance with caching
           resolve_dependencies.reverse_each do |task_class|
             task_class.ensure_instance_built
           end
           # Return the singleton instance for consistency
           instance_variable_get(:@__task_instance)
         else
-          # Parametrized build: temporary instance without caching
           build_with_args(args)
         end
       end
@@ -45,7 +43,7 @@ module Taski
         self
       end
 
-      # Refresh task state (currently just resets)
+      # Refresh task state
       # @return [self] Returns self for method chaining
       def refresh
         reset!
@@ -82,11 +80,11 @@ module Taski
       # Ensure task instance is built (public because called from build)
       # @return [Task] The built task instance
       def ensure_instance_built
-        # Use double-checked locking pattern for thread safety
+        # Double-checked locking prevents lock contention in multi-threaded builds
+        # First check avoids expensive synchronization when instance already exists
         return @__task_instance if @__task_instance
 
         build_monitor.synchronize do
-          # Check again after acquiring lock
           return @__task_instance if @__task_instance
 
           check_circular_dependency

data/lib/taski/utils/tree_display_helper.rb

@@ -26,15 +26,12 @@ module Taski
           child_prefix_text = is_last ? "    " : "│   "
           child_prefix = prefix + (color ? TreeColors.connector(child_prefix_text) : child_prefix_text)
 
-          # For the dependency itself, we want to use the connector
-          # For its children, we want to use the child_prefix
           dep_tree = if dep_class.respond_to?(:tree)
             dep_class.tree(child_prefix, visited, color: color)
           else
             "#{child_prefix}#{dep_class.name}\n"
           end
 
-          # Replace the first line (which has child_prefix) with the proper connector
           dep_lines = dep_tree.lines
           if dep_lines.any?
             # Replace the first line prefix with connector

data/lib/taski/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Taski
-  VERSION = "0.3.0"
+  VERSION = "0.3.1"
 end

data/lib/taski.rb

@@ -26,20 +26,20 @@ module Taski
   # Main module for the Taski task framework
   #
   # Taski provides a framework for defining and managing task dependencies
-  # with two complementary APIs:
+  # with three complementary APIs:
   # 1. Exports API - Export instance variables as class methods (static dependencies)
   # 2. Define API - Define lazy-evaluated values with dynamic dependency resolution
+  # 3. Section API - Abstraction layers with runtime implementation selection
   #
-  # Use Define API when:
-  # - Dependencies change based on runtime conditions
-  # - Environment-specific configurations
-  # - Feature flags determine which classes to use
-  # - Complex conditional logic determines dependencies
+  # API Selection Guide:
+  # - Use Exports API for simple static dependencies
+  # - Use Define API for conditional dependencies analyzed at class definition time
+  # - Use Section API for environment-specific implementations with static analysis
   #
   # Features:
   # - Automatic dependency resolution (static and dynamic)
   # - Static analysis of method dependencies
-  # - Runtime dependency resolution for conditional logic
+  # - Runtime implementation selection with Section API
   # - Thread-safe task building
   # - Circular dependency detection
   # - Memory leak prevention

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: taski
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - ahogappa