ukiryu 0.1.6 → 0.2.0

data/lib/ukiryu/errors.rb

@@ -17,9 +17,9 @@ module Ukiryu
     class UnknownShellError < Error
       def suggestions
         [
-          "Supported shells: bash, zsh, fish, sh, dash, tcsh, powershell, cmd",
-          "Platform groups: :unix (all Unix shells), :windows, :powershell",
-          "Set explicitly: Ukiryu.configure { |c| c.default_shell = :bash }"
+          'Supported shells: bash, zsh, fish, sh, dash, tcsh, powershell, cmd',
+          'Platform groups: :unix (all Unix shells), :windows, :powershell',
+          'Set explicitly: Ukiryu.configure { |c| c.default_shell = :bash }'
         ]
       end
     end
@@ -28,9 +28,9 @@ module Ukiryu
     class UnsupportedPlatformError < Error
       def suggestions
         [
-          "Ukiryu supports: macOS, Linux, Windows",
+          'Ukiryu supports: macOS, Linux, Windows',
           "Current platform: #{RUBY_PLATFORM}",
-          "Check if running on a supported operating system"
+          'Check if running on a supported operating system'
         ]
       end
     end
@@ -39,9 +39,9 @@ module Ukiryu
     class ValidationError < Error
       def suggestions
         [
-          "Check the parameter type against the tool definition",
-          "Verify value is within allowed range",
-          "Ensure value is in the allowed values list"
+          'Check the parameter type against the tool definition',
+          'Verify value is within allowed range',
+          'Ensure value is in the allowed values list'
         ]
       end
     end
@@ -50,9 +50,9 @@ module Ukiryu
     class ProfileNotFoundError < Error
       def suggestions
         [
-          "Check tool definition has profile for your platform",
-          "Verify tool definition has profile for your shell",
-          "Try specifying platform/shell explicitly"
+          'Check tool definition has profile for your platform',
+          'Verify tool definition has profile for your shell',
+          'Try specifying platform/shell explicitly'
         ]
       end
     end
@@ -60,9 +60,9 @@ module Ukiryu
     class ProfileLoadError < Error
       def suggestions
         [
-          "Verify YAML syntax is correct",
-          "Check profile structure matches schema",
-          "Review error message for specific issue"
+          'Verify YAML syntax is correct',
+          'Check profile structure matches schema',
+          'Review error message for specific issue'
         ]
       end
     end
@@ -73,9 +73,9 @@ module Ukiryu
     class DefinitionNotFoundError < DefinitionError
       def suggestions
         [
-          "Verify file path is correct",
-          "Check file has .yaml extension",
-          "Use absolute path if relative path fails"
+          'Verify file path is correct',
+          'Check file has .yaml extension',
+          'Use absolute path if relative path fails'
         ]
       end
     end
@@ -83,9 +83,9 @@ module Ukiryu
     class DefinitionLoadError < DefinitionError
       def suggestions
         [
-          "Validate YAML syntax",
-          "Check file is readable",
-          "Verify file encoding is UTF-8"
+          'Validate YAML syntax',
+          'Check file is readable',
+          'Verify file encoding is UTF-8'
         ]
       end
     end
@@ -94,8 +94,8 @@ module Ukiryu
       def suggestions
         [
           "Run 'ukiryu validate' for detailed errors",
-          "Compare with schema definition",
-          "Check tool definition examples"
+          'Compare with schema definition',
+          'Check tool definition examples'
         ]
       end
     end
@@ -107,9 +107,9 @@ module Ukiryu
     class ToolNotFoundError < Error
       def suggestions
         [
-          "Check tool name spelling",
-          "Verify register path is correct",
-          "List available tools: Ukiryu::Register.tool_names"
+          'Check tool name spelling',
+          'Verify register path is correct',
+          'List available tools: Ukiryu::Register.tool_names'
         ]
       end
     end
@@ -117,9 +117,9 @@ module Ukiryu
     class ExecutableNotFoundError < Error
       def suggestions
         [
-          "Install the tool (e.g., brew install imagemagick)",
-          "Add executable to PATH",
-          "Configure search_paths in tool definition"
+          'Install the tool (e.g., brew install imagemagick)',
+          'Add executable to PATH',
+          'Configure search_paths in tool definition'
         ]
       end
     end
@@ -128,9 +128,9 @@ module Ukiryu
     class ExecutionError < Error
       def suggestions
         [
-          "Check e.result.exit_status for exit code",
-          "Check e.result.stderr for error message",
-          "Verify parameters are correct"
+          'Check e.result.exit_status for exit code',
+          'Check e.result.stderr for error message',
+          'Verify parameters are correct'
         ]
       end
     end
@@ -145,9 +145,9 @@ module Ukiryu
 
       def suggestions
         [
-          "Increase timeout parameter",
-          "Check UKIRYU_TIMEOUT environment variable",
-          "Verify tool is not hanging"
+          'Increase timeout parameter',
+          'Check UKIRYU_TIMEOUT environment variable',
+          'Verify tool is not hanging'
         ]
       end
     end
@@ -156,9 +156,9 @@ module Ukiryu
     class VersionDetectionError < Error
       def suggestions
         [
-          "Verify tool is installed correctly",
-          "Check version_detection command in tool definition",
-          "Test version command manually: tool --version"
+          'Verify tool is installed correctly',
+          'Check version_detection command in tool definition',
+          'Test version command manually: tool --version'
         ]
       end
     end

data/lib/ukiryu/executable_locator.rb

@@ -50,23 +50,17 @@ module Ukiryu
 
         # Try primary name first
         result = DiscoveryStrategy.discover(tool_name, context)
-        if result && (ENV['UKIRYU_DEBUG_EXECUTABLE'] || (platform == :windows && ENV['CI']))
-          warn "[UKIRYU DEBUG ExecutableLocator] Found #{tool_name}: #{result[:path]}"
-        end
+        warn "[UKIRYU DEBUG ExecutableLocator] Found #{tool_name}: #{result[:path]}" if result && (ENV['UKIRYU_DEBUG_EXECUTABLE'] || (platform == :windows && ENV['CI']))
         return result if result
 
         # Try aliases
         aliases.each do |alias_name|
           result = DiscoveryStrategy.discover(alias_name, context)
-          if result && (ENV['UKIRYU_DEBUG_EXECUTABLE'] || (platform == :windows && ENV['CI']))
-            warn "[UKIRYU DEBUG ExecutableLocator] Found alias #{alias_name}: #{result[:path]}"
-          end
+          warn "[UKIRYU DEBUG ExecutableLocator] Found alias #{alias_name}: #{result[:path]}" if result && (ENV['UKIRYU_DEBUG_EXECUTABLE'] || (platform == :windows && ENV['CI']))
           return result if result
         end
 
-        if ENV['UKIRYU_DEBUG_EXECUTABLE'] || (platform == :windows && ENV['CI'])
-          warn "[UKIRYU DEBUG ExecutableLocator] NO EXECUTABLE FOUND for #{tool_name} or aliases #{aliases}"
-        end
+        warn "[UKIRYU DEBUG ExecutableLocator] NO EXECUTABLE FOUND for #{tool_name} or aliases #{aliases}" if ENV['UKIRYU_DEBUG_EXECUTABLE'] || (platform == :windows && ENV['CI'])
 
         nil
       end
@@ -151,9 +145,7 @@ module Ukiryu
         # @param context [DiscoveryContext] discovery environment
         # @return [Hash, nil] discovery result or nil
         def discover(command, context)
-          if ENV['UKIRYU_DEBUG_EXECUTABLE'] || (context.platform == :windows && ENV['CI'])
-            warn "[UKIRYU DEBUG AliasDiscovery] Checking for alias: #{command.inspect} with shell #{context.shell_class}"
-          end
+          warn "[UKIRYU DEBUG AliasDiscovery] Checking for alias: #{command.inspect} with shell #{context.shell_class}" if ENV['UKIRYU_DEBUG_EXECUTABLE'] || (context.platform == :windows && ENV['CI'])
 
           alias_info = context.shell_class.detect_alias(command)
           warn "[UKIRYU DEBUG AliasDiscovery] Alias info: #{alias_info.inspect}" if ENV['UKIRYU_DEBUG_EXECUTABLE'] || (context.platform == :windows && ENV['CI'])
@@ -162,9 +154,7 @@ module Ukiryu
           alias_target = alias_info[:target]
           path = PathScanner.find(command) || PathScanner.find(alias_target)
 
-          if ENV['UKIRYU_DEBUG_EXECUTABLE'] || (context.platform == :windows && ENV['CI'])
-            warn "[UKIRYU DEBUG AliasDiscovery] Alias target: #{alias_target.inspect}, path: #{path.inspect}"
-          end
+          warn "[UKIRYU DEBUG AliasDiscovery] Alias target: #{alias_target.inspect}, path: #{path.inspect}" if ENV['UKIRYU_DEBUG_EXECUTABLE'] || (context.platform == :windows && ENV['CI'])
 
           DiscoveryResult.build(path, :alias, context, alias_info[:definition]) if path
         end
@@ -325,12 +315,21 @@ module Ukiryu
 
     # Handle platform-specific path extensions (.exe, .bat, etc.)
     #
+    # On Windows, prioritizes .exe over .com for better PowerShell compatibility.
+    # The .com extension is legacy and can cause issues with PowerShell's call
+    # operator when used with I/O redirection (hangs with Open3.capture3).
+    #
     # @api private
     class PathExtensions
       include Enumerable
 
+      # Extensions to prioritize on Windows for PowerShell compatibility
+      # .com files can hang PowerShell when used with I/O redirection
+      PREFERRED_WINDOWS_EXTENSIONS = %w[.exe .EXE].freeze
+
       def initialize
-        @extensions = ENV['PATHEXT'] ? ENV['PATHEXT'].split(';') : ['']
+        raw_extensions = ENV['PATHEXT'] ? ENV['PATHEXT'].split(';') : ['']
+        @extensions = prioritize_extensions(raw_extensions)
       end
 
       # Iterate over extensions
@@ -339,6 +338,31 @@ module Ukiryu
       def each(&block)
         @extensions.each(&block)
       end
+
+      private
+
+      # Prioritize .exe extensions on Windows for better PowerShell compatibility
+      #
+      # @param extensions [Array<String>] original PATHEXT extensions
+      # @return [Array<String>] reordered extensions with .exe first
+      def prioritize_extensions(extensions)
+        return extensions unless Platform.windows?
+
+        # Separate preferred extensions from others
+        preferred = []
+        others = []
+
+        extensions.each do |ext|
+          if PREFERRED_WINDOWS_EXTENSIONS.include?(ext)
+            preferred << ext
+          else
+            others << ext
+          end
+        end
+
+        # Return preferred first, then others in original order
+        preferred + others
+      end
     end
   end
 end

data/lib/ukiryu/extractors/base_extractor.rb

@@ -59,7 +59,8 @@ module Ukiryu
         args = command[1..]
 
         # Execute through Executor (uses Environment system internally)
-        result = Ukiryu::Executor.execute(executable, args, env: environment, shell: shell_class, allow_failure: true, timeout: timeout)
+        result = Ukiryu::Executor.execute(executable, args, env: environment, shell: shell_class, allow_failure: true,
+                                                            timeout: timeout)
 
         {
           stdout: result.stdout,

data/lib/ukiryu/extractors/help_parser.rb

@@ -212,6 +212,9 @@ module Ukiryu
           /is not recognized as (?:a |the )?(?:name of a )?cmdlet/i,
           /cannot be found/i,
           /because it does not exist/i,
+          # Windows Start-Process error when executable not found
+          /The system cannot find the file specified/i,
+          /cannot find the file/i,
           # General
           /executable not found/i,
           /bad command or file name/i

data/lib/ukiryu/logger.rb

@@ -10,12 +10,17 @@ module Ukiryu
   # - Colored output via Paint gem (when available)
   # - Message classification (debug, info, warn, error)
   # - Structured output for tool resolution process
+  # - Class-level convenience methods for quick debug output
   #
   # @example Enable debug mode
   #   ENV['UKIRYU_DEBUG'] = '1'
   #   logger = Ukiryu::Logger.new
   #   logger.debug("Tool resolution started")
   #
+  # @example Class-level debug output (recommended)
+  #   Ukiryu::Logger.debug("Message", category: :executable)
+  #   Ukiryu::Logger.debug("Found executable", context: { path: '/usr/bin/tool' })
+  #
   # @example Standard logging
   #   logger = Ukiryu::Logger.new
   #   logger.info("Command completed successfully")
@@ -25,6 +30,52 @@ module Ukiryu
     # Log levels
     LEVELS = %i[debug info warn error].freeze
 
+    # Environment variable names for debug control
+    DEBUG_ENV_VAR = 'UKIRYU_DEBUG'
+    DEBUG_EXECUTABLE_ENV_VAR = 'UKIRYU_DEBUG_EXECUTABLE'
+
+    class << self
+      # Class-level debug output (quick access without instance)
+      #
+      # @param message [String] the debug message
+      # @param category [Symbol, nil] optional category (:executable for UKIRYU_DEBUG_EXECUTABLE)
+      # @param context [Hash] optional context data to include
+      def debug(message, category: nil, context: {})
+        return unless debug_enabled?(category)
+
+        prefix = "[UKIRYU DEBUG#{category ? " #{category.to_s.upcase}" : ''}]"
+        details = context.empty? ? '' : " (#{context.map { |k, v| "#{k}=#{v.inspect}" }.join(', ')})"
+        warn "#{prefix} #{message}#{details}"
+      end
+
+      # Check if debug mode is enabled for a given category
+      #
+      # @param category [Symbol, nil] the category to check
+      # @return [Boolean] true if debug is enabled
+      def debug_enabled?(category = nil)
+        case category
+        when :executable
+          ENV[DEBUG_EXECUTABLE_ENV_VAR] || (Platform.windows? && ENV['CI'])
+        else
+          ENV[DEBUG_ENV_VAR]
+        end
+      end
+
+      # Get the singleton instance
+      #
+      # @return [Logger] the logger instance
+      def instance
+        @instance ||= new
+      end
+
+      # Delegate instance methods to class level
+      %i[info warn error debug_resolution].each do |method|
+        define_method(method) do |*args, **kwargs|
+          instance.send(method, *args, **kwargs)
+        end
+      end
+    end
+
     attr_reader :level, :logger, :output, :paint_available
 
     # Initialize a new Logger

data/lib/ukiryu/models/implementation_index.rb

@@ -66,7 +66,8 @@ module Ukiryu
       # @return [ImplementationIndex] Loaded index
       def self.from_yaml(path)
         require 'psych'
-        data = Psych.safe_load_file(path, permitted_classes: [Symbol, String, Integer, Array, Hash, TrueClass, FalseClass])
+        data = Psych.safe_load_file(path,
+                                    permitted_classes: [Symbol, String, Integer, Array, Hash, TrueClass, FalseClass])
         from_hash(data)
       end
 

data/lib/ukiryu/models/implementation_version.rb

@@ -50,6 +50,17 @@ module Ukiryu
           platforms.include?(platform_str) && shells.include?(shell_str)
         end
 
+        # Debug output for profile selection
+        if ENV['UKIRYU_DEBUG_EXECUTABLE'] || (ENV['CI'] && defined?(Ukiryu::Platform) && Ukiryu::Platform.windows?)
+          warn "[UKIRYU DEBUG compatible_profile] platform=#{platform_str}, shell=#{shell_str}"
+          warn "[UKIRYU DEBUG compatible_profile] Found profile: #{profile ? (profile[:name] || profile['name']) : 'nil'}"
+          if profile
+            warn "[UKIRYU DEBUG compatible_profile] Profile inherits: #{profile[:inherits] || profile['inherits']}"
+            warn "[UKIRYU DEBUG compatible_profile] Profile commands nil?: #{profile[:commands].nil?}"
+            warn "[UKIRYU DEBUG compatible_profile] Profile commands empty?: #{(profile[:commands] || []).empty?}"
+          end
+        end
+
         return nil unless profile
 
         # Resolve profile inheritance at hash level
@@ -61,11 +72,16 @@ module Ukiryu
             prof_name.to_s == inherits.to_s
           end
 
+          if ENV['UKIRYU_DEBUG_EXECUTABLE'] || (ENV['CI'] && defined?(Ukiryu::Platform) && Ukiryu::Platform.windows?)
+            warn "[UKIRYU DEBUG compatible_profile] Looking for parent '#{inherits}': #{parent_profile ? 'found' : 'not found'}"
+          end
+
           if parent_profile && (profile[:commands].nil? || profile[:commands].empty?)
             # Copy parent's commands to child profile (without modifying original)
             parent_commands = parent_profile[:commands] || parent_profile['commands']
             # Return a new hash with inherited commands
             profile = profile.dup.merge(commands: parent_commands)
+            warn "[UKIRYU DEBUG compatible_profile] Inherited #{parent_commands&.size || 0} commands from parent" if ENV['UKIRYU_DEBUG_EXECUTABLE'] || (ENV['CI'] && defined?(Ukiryu::Platform) && Ukiryu::Platform.windows?)
           end
         end
 
@@ -86,7 +102,8 @@ module Ukiryu
       # @return [ImplementationVersion] Loaded version
       def self.from_yaml(path)
         require 'psych'
-        data = Psych.safe_load_file(path, permitted_classes: [Symbol, String, Integer, Array, Hash, TrueClass, FalseClass])
+        data = Psych.safe_load_file(path,
+                                    permitted_classes: [Symbol, String, Integer, Array, Hash, TrueClass, FalseClass])
         from_hash(data)
       end
 

data/lib/ukiryu/models/interface.rb

@@ -63,7 +63,8 @@ module Ukiryu
       # @return [Interface] Loaded interface
       def self.from_yaml(path)
         require 'psych'
-        data = Psych.safe_load_file(path, permitted_classes: [Symbol, String, Integer, Array, Hash, TrueClass, FalseClass])
+        data = Psych.safe_load_file(path,
+                                    permitted_classes: [Symbol, String, Integer, Array, Hash, TrueClass, FalseClass])
         from_hash(symbolize_keys(data))
       end
 

data/lib/ukiryu/models/run_environment.rb

@@ -5,7 +5,6 @@ require 'etc'
 
 module Ukiryu
   module Models
-
     # Run environment information
     class RunEnvironment < Lutaml::Model::Serializable
       attribute :hostname, :string, default: ''
@@ -107,6 +106,5 @@ module Ukiryu
 
       private_class_method :detect_shell_version_for, :detect_total_memory, :os_version_string
     end
-
   end
 end

data/lib/ukiryu/models/semantic_version.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Ukiryu
+  module Models
+    # Semantic version value object for proper version comparison.
+    #
+    # Handles version strings like "10.0", "9.5.1", "1.2.3" and provides
+    # proper semantic comparison (10.0 > 9.5, not alphabetical).
+    #
+    # This class ensures that version selection uses actual semantic meaning
+    # rather than string comparison, which would incorrectly sort "9.5" > "10.0".
+    #
+    # @example
+    #   v1 = Ukiryu::Models::SemanticVersion.new("10.0")
+    #   v2 = Ukiryu::Models::SemanticVersion.new("9.5")
+    #   v1 > v2  # => true (correct)
+    #   "10.0" > "9.5"  # => false (wrong - alphabetical)
+    #
+    class SemanticVersion
+      include Comparable
+
+      # Parse a version string into segments
+      #
+      # @param version_string [String, nil] the version string to parse
+      # @return [Array<Integer>] array of numeric segments
+      def self.parse(version_string)
+        return [0] if version_string.nil? || version_string.to_s.empty?
+
+        version_string.to_s
+                      .split('.')
+                      .map do |part|
+                        part.to_i
+        rescue StandardError
+          0
+        end
+      end
+
+      # Compare two version strings directly
+      #
+      # @param version_a [String] first version string
+      # @param version_b [String] second version string
+      # @return [Integer] -1, 0, or 1
+      def self.compare(version_a, version_b)
+        segments1 = parse(version_a)
+        segments2 = parse(version_b)
+
+        max_length = [segments1.length, segments2.length].max
+        padded1 = segments1 + [0] * (max_length - segments1.length)
+        padded2 = segments2 + [0] * (max_length - segments2.length)
+
+        padded1 <=> padded2
+      end
+
+      # @return [Array<Integer>] the numeric segments of this version
+      attr_reader :segments
+
+      # @return [String, nil] the original version string
+      attr_reader :original
+
+      # Create a new SemanticVersion from a version string
+      #
+      # @param version_string [String, Integer, SemanticVersion, nil] the version
+      def initialize(version_string)
+        @original = version_string.respond_to?(:to_s) ? version_string.to_s : nil
+        @segments = self.class.parse(@original)
+      end
+
+      # Compare this version with another
+      #
+      # @param other [SemanticVersion, String, Integer, nil] the other version
+      # @return [Integer, nil] -1, 0, 1, or nil if not comparable
+      def <=>(other)
+        return nil unless other
+
+        other_segments = case other
+                         when SemanticVersion
+                           other.segments
+                         when String, Integer
+                           self.class.parse(other)
+                         else
+                           return nil
+                         end
+
+        # Compare segment by segment
+        # [10, 0] <=> [9, 5] should return 1 (10.0 > 9.5)
+        max_length = [segments.length, other_segments.length].max
+
+        max_length.times do |i|
+          a = segments[i] || 0
+          b = other_segments[i] || 0
+
+          return a <=> b unless a == b
+        end
+
+        0 # All segments equal
+      end
+
+      # Check equality with another version
+      #
+      # @param other [Object] the other object
+      # @return [Boolean]
+      def ==(other)
+        return false unless other
+
+        (self <=> other).zero?
+      end
+
+      # Check if this version is greater than another
+      #
+      # @param other [SemanticVersion, String, Integer, nil] the other version
+      # @return [Boolean]
+      def >(other)
+        (self <=> other) == 1
+      end
+
+      # Check if this version is less than another
+      #
+      # @param other [SemanticVersion, String, Integer, nil] the other version
+      # @return [Boolean]
+      def <(other)
+        (self <=> other) == -1
+      end
+
+      # Check if this version is greater than or equal to another
+      #
+      # @param other [SemanticVersion, String, Integer, nil] the other version
+      # @return [Boolean]
+      def >=(other)
+        result = self <=> other
+        [1, 0].include?(result)
+      end
+
+      # Check if this version is less than or equal to another
+      #
+      # @param other [SemanticVersion, String, Integer, nil] the other version
+      # @return [Boolean]
+      def <=(other)
+        result = self <=> other
+        [-1, 0].include?(result)
+      end
+
+      # Return the version as a string
+      #
+      # @return [String] the version string
+      def to_s
+        segments.join('.')
+      end
+
+      # Return a human-readable representation
+      #
+      # @return [String]
+      def inspect
+        "#<Ukiryu::Models::SemanticVersion #{self}>"
+      end
+
+      # Hash for use as hash key
+      #
+      # @return [Integer]
+      def hash
+        segments.hash
+      end
+
+      # Equality for hash key usage
+      #
+      # @param other [Object]
+      # @return [Boolean]
+      def eql?(other)
+        return false unless other.is_a?(SemanticVersion)
+
+        segments == other.segments
+      end
+    end
+  end
+end

data/lib/ukiryu/models/stage_metrics.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-
 module Ukiryu
   module Models
     # Metrics for a single stage of execution