ukiryu 0.1.1 → 0.1.3

data/lib/ukiryu/definition/validation_result.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module Ukiryu
+  module Definition
+    # Result of a definition validation
+    #
+    # This class represents the result of validating a tool definition
+    # against a JSON Schema or other validation rules.
+    class ValidationResult
+      attr_reader :errors, :warnings, :schema_path
+
+      def initialize(valid:, errors: [], warnings: [], schema_path: nil)
+        @valid = valid
+        @errors = errors
+        @warnings = warnings
+        @schema_path = schema_path
+      end
+
+      # Check if validation passed
+      #
+      # @return [Boolean] true if validation passed
+      def valid?
+        @valid
+      end
+
+      # Check if validation failed
+      #
+      # @return [Boolean] true if validation failed
+      def invalid?
+        !@valid
+      end
+
+      # Check if there are any errors
+      #
+      # @return [Boolean] true if there are errors
+      def has_errors?
+        !@errors.empty?
+      end
+
+      # Check if there are any warnings
+      #
+      # @return [Boolean] true if there are warnings
+      def has_warnings?
+        !@warnings.empty?
+      end
+
+      # Get total issue count
+      #
+      # @return [Integer] total number of issues (errors + warnings)
+      def issue_count
+        @errors.length + @warnings.length
+      end
+
+      # Get error count
+      #
+      # @return [Integer] number of errors
+      def error_count
+        @errors.length
+      end
+
+      # Get warning count
+      #
+      # @return [Integer] number of warnings
+      def warning_count
+        @warnings.length
+      end
+
+      # Create a successful validation result
+      #
+      # @return [ValidationResult] a successful result
+      def self.success
+        new(valid: true)
+      end
+
+      # Create a failed validation result
+      #
+      # @param errors [Array<String>] validation errors
+      # @param warnings [Array<String>] validation warnings
+      # @return [ValidationResult] a failed result
+      def self.failure(errors, warnings = [])
+        new(valid: false, errors: errors, warnings: warnings)
+      end
+
+      # Create a result with warnings
+      #
+      # @param warnings [Array<String>] validation warnings
+      # @return [ValidationResult] a result with warnings
+      def self.with_warnings(warnings)
+        new(valid: true, warnings: warnings)
+      end
+
+      # Convert to hash
+      #
+      # @return [Hash] hash representation
+      def to_h
+        {
+          valid: @valid,
+          errors: @errors,
+          warnings: @warnings,
+          schema_path: @schema_path,
+          error_count: error_count,
+          warning_count: warning_count
+        }
+      end
+
+      # Convert to JSON
+      #
+      # @return [String] JSON representation
+      def to_json(*args)
+        require 'json'
+        to_h.to_json(*args)
+      end
+
+      # Human-readable summary
+      #
+      # @return [String] summary text
+      def summary
+        if valid?
+          if has_warnings?
+            "Valid with #{warning_count} warning(s)"
+          else
+            'Valid'
+          end
+        else
+          msg = "Invalid (#{error_count} error(s)"
+          msg += ", #{warning_count} warning(s)" if has_warnings?
+          "#{msg})"
+        end
+      end
+
+      # Detailed message string
+      #
+      # @return [String] detailed message
+      def to_s
+        output = []
+        output << "Validation: #{summary}"
+
+        if has_errors?
+          output << ''
+          output << 'Errors:'
+          @errors.each_with_index do |error, i|
+            output << "  #{i + 1}. #{error}"
+          end
+        end
+
+        if has_warnings?
+          output << ''
+          output << 'Warnings:'
+          @warnings.each_with_index do |warning, i|
+            output << "  #{i + 1}. #{warning}"
+          end
+        end
+
+        output.join("\n")
+      end
+    end
+  end
+end

data/lib/ukiryu/definition/version_resolver.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module Ukiryu
+  module Definition
+    # Resolve semantic version constraints
+    #
+    # This class handles semantic versioning constraints like:
+    # - "1.0" - exact version
+    # - ">= 1.0" - minimum version (inclusive)
+    # - "~> 1.2" - pessimistic version constraint
+    class VersionResolver
+      # Version constraint structure
+      class Constraint
+        attr_reader :operator, :version, :raw
+
+        def initialize(operator, version, raw = nil)
+          @operator = operator
+          @version = version
+          @raw = raw || "#{operator} #{version}"
+        end
+
+        # Exact version constraint
+        def self.exact(version)
+          new(:==, version, version)
+        end
+
+        # Minimum version constraint (inclusive)
+        def self.min(version)
+          new(:>=, version)
+        end
+
+        # Maximum version constraint (inclusive)
+        def self.max(version)
+          new(:<=, version)
+        end
+
+        # Pessimistic version constraint
+        def self.pessimistic(version)
+          new('~>'.to_sym, version)
+        end
+
+        # Range constraint
+        def self.range(min_version, max_version)
+          # This is represented as two constraints internally
+          [new(:>=, min_version), new(:<, max_version)]
+        end
+
+        def to_s
+          @raw
+        end
+      end
+
+      # Parse a version constraint string
+      #
+      # @param constraint_string [String] the constraint string
+      # @return [Array<Constraint>] array of constraints
+      def self.parse_constraint(constraint_string)
+        return [Constraint.exact(constraint_string)] unless constraint_string.match?(/[<>=~]/)
+
+        constraints = []
+
+        # Split by comma for compound constraints
+        constraint_string.split(',').map(&:strip).each do |part|
+          case part
+          when /\A~>(?:\s*(.+))?/ # Updated regex for ~> operator
+            # Pessimistic version constraint
+            version = ::Regexp.last_match(1) || ''
+            constraints << Constraint.pessimistic(version.strip)
+          when /\A>=\s*(.+)/
+            # Minimum version (inclusive)
+            constraints << Constraint.min(::Regexp.last_match(1))
+          when /\A>\s*(.+)/
+            # Minimum version (exclusive)
+            constraints << Constraint.new(:>, ::Regexp.last_match(1))
+          when /\A<=\s*(.+)/
+            # Maximum version (inclusive)
+            constraints << Constraint.max(::Regexp.last_match(1))
+          when /\A<\s*(.+)/
+            # Maximum version (exclusive)
+            constraints << Constraint.new(:<, ::Regexp.last_match(1))
+          when /\A==\s*(.+)/
+            # Exact version
+            constraints << Constraint.exact(::Regexp.last_match(1))
+          else
+            # Assume exact version
+            constraints << Constraint.exact(part.strip)
+          end
+        end
+
+        constraints
+      end
+
+      # Check if a version satisfies a constraint
+      #
+      # @param version [String] the version to check
+      # @param constraint [String, Array<Constraint>] the constraint(s)
+      # @return [Boolean] true if version satisfies constraint
+      def self.satisfies?(version, constraint)
+        constraints = constraint.is_a?(Array) ? constraint : parse_constraint(constraint)
+
+        v_parts = parse_version(version)
+
+        constraints.all? do |c|
+          case c.operator
+          when :==
+            v_parts == parse_version(c.version)
+          when :>=
+            compare_versions(v_parts, parse_version(c.version)) >= 0
+          when :>
+            compare_versions(v_parts, parse_version(c.version)).positive?
+          when :<=
+            compare_versions(v_parts, parse_version(c.version)) <= 0
+          when :<
+            compare_versions(v_parts, parse_version(c.version)).negative?
+          when '~>'.to_sym
+            # Pessimistic version constraint: >= x.y.z, < x.(y+1).0
+            base = parse_version(c.version)
+            upper = base[0...-1] + [base[-1] + 1, 0]
+            compare_versions(v_parts, base) >= 0 && compare_versions(v_parts, upper).negative?
+          else
+            false
+          end
+        end
+      end
+
+      # Resolve the best matching version from available versions
+      #
+      # @param constraint [String] the version constraint
+      # @param available_versions [Array<String>] available versions
+      # @return [String, nil] best matching version, or nil if none match
+      def self.resolve(constraint, available_versions)
+        return nil if available_versions.nil? || available_versions.empty?
+
+        # Parse constraint
+        constraints = parse_constraint(constraint)
+
+        # Filter versions that satisfy the constraint
+        matching = available_versions.select { |v| satisfies?(v, constraints) }
+
+        # Return highest matching version
+        matching.max_by { |v| parse_version(v) }
+      end
+
+      # Compare two version strings
+      #
+      # @param v1 [String, Array] first version or parts
+      # @param v2 [String, Array] second version or parts
+      # @return [Integer] comparison result (-1, 0, 1)
+      def self.compare_versions(v1, v2)
+        parts1 = v1.is_a?(Array) ? v1 : parse_version(v1)
+        parts2 = v2.is_a?(Array) ? v2 : parse_version(v2)
+
+        max_length = [parts1.length, parts2.length].max
+        max_length.times do |i|
+          p1 = parts1[i] || 0
+          p2 = parts2[i] || 0
+          comparison = p1 <=> p2
+          return comparison unless comparison.zero?
+        end
+
+        0
+      end
+
+      # Parse a version string into components
+      #
+      # @param version_string [String] the version string
+      # @return [Array<Integer>] version components
+      def self.parse_version(version_string)
+        version_string.to_s.split('.').map(&:to_i)
+      end
+
+      # Get the latest version from a list
+      #
+      # @param versions [Array<String>] list of versions
+      # @return [String, nil] the latest version
+      def self.latest(versions)
+        return nil if versions.nil? || versions.empty?
+
+        versions.max_by { |v| parse_version(v) }
+      end
+
+      # Get the compatible version range for a pessimistic constraint
+      #
+      # @param version [String] the base version
+      # @return [Array<String>] [min_version, max_version]
+      def self.pessimistic_range(version)
+        parts = parse_version(version)
+        min = version
+        max = "#{parts[0...-1].join('.')}.#{parts[-1] + 1}"
+        [min, max]
+      end
+    end
+  end
+end

data/lib/ukiryu/definition.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative 'definition/source'
+require_relative 'definition/sources/file'
+require_relative 'definition/sources/string'
+
+# Export classes for convenience
+Ukiryu::Definition::FileSource = Ukiryu::Definition::Sources::FileSource
+Ukiryu::Definition::StringSource = Ukiryu::Definition::Sources::StringSource
+
+require_relative 'definition/loader'
+require_relative 'definition/metadata'
+require_relative 'definition/discovery'
+require_relative 'definition/version_resolver'
+require_relative 'definition/definition_cache'
+require_relative 'definition/definition_composer'
+
+# Phase 5: Ecosystem - Validation, linting, documentation
+require_relative 'definition/validation_result'
+require_relative 'definition/definition_validator'
+require_relative 'definition/lint_issue'
+require_relative 'definition/definition_linter'
+require_relative 'definition/documentation_generator'
+
+module Ukiryu
+  # Definition loading module
+  #
+  # Provides functionality for loading tool definitions from various sources:
+  # - Files on the filesystem
+  # - YAML strings
+  # - XDG-compliant system paths
+  # - Tool-bundled locations
+  # - Central register (existing)
+  #
+  # @see Ukiryu::Tool::load
+  # @see Ukiryu::Tool::load_from_string
+  # @see Ukiryu::Definition::Discovery
+  module Definition
+  end
+end

data/lib/ukiryu/errors.rb

@@ -18,6 +18,12 @@ module Ukiryu
   class ProfileLoadError < Error; end
 
   # Definition loading errors
+  class DefinitionError < Error; end
+  class DefinitionNotFoundError < DefinitionError; end
+  class DefinitionLoadError < DefinitionError; end
+  class DefinitionValidationError < DefinitionError; end
+
+  # Definition loading errors (legacy, use DefinitionError instead)
   class LoadError < Error; end
 
   # Tool errors

data/lib/ukiryu/execution_context.rb

@@ -32,13 +32,13 @@ module Ukiryu
   #   context = Ukiryu::ExecutionContext.current
   #   context.platform  # => :macos
   #   context.shell     # => :bash
-  #   context.registry  # => '/path/to/registry'
+  #   context.register  # => '/path/to/register'
   #
   # @example Using ExecutionContext in tests
   #   context = Ukiryu::ExecutionContext.new(
   #     platform: :linux,
   #     shell: :zsh,
-  #     registry_path: '/test/registry'
+  #     register_path: '/test/register'
   #   )
   #   context.platform  # => :linux
   #   context.shell     # => :zsh
@@ -85,7 +85,7 @@ module Ukiryu
         new(
           platform: runtime.platform,
           shell: runtime.shell,
-          registry_path: Registry.default_registry_path,
+          register_path: Register.default_register_path,
           timeout: Config.timeout,
           debug: Config.debug,
           metrics: Config.metrics
@@ -110,10 +110,10 @@ module Ukiryu
     # @return [Symbol] the shell
     attr_reader :shell
 
-    # Registry path for tool profiles
+    # Register path for tool profiles
     #
-    # @return [String, nil] the registry path
-    attr_reader :registry_path
+    # @return [String, nil] the register path
+    attr_reader :register_path
 
     # Execution timeout in seconds
     #
@@ -139,21 +139,21 @@ module Ukiryu
     #
     # @param platform [Symbol] the platform (:macos, :linux, :windows)
     # @param shell [Symbol] the shell (:bash, :zsh, :fish, :powershell, :cmd)
-    # @param registry_path [String, nil] the registry path
+    # @param register_path [String, nil] the register path
     # @param timeout [Integer, nil] execution timeout in seconds
     # @param debug [Boolean] debug mode flag
     # @param metrics [Boolean] metrics collection flag
     # @param options [Hash] additional options
     def initialize(platform: nil,
                    shell: nil,
-                   registry_path: nil,
+                   register_path: nil,
                    timeout: nil,
                    debug: false,
                    metrics: false,
                    options: {})
       @platform = platform
       @shell = shell
-      @registry_path = registry_path
+      @register_path = register_path
       @timeout = timeout
       @debug = debug
       @metrics = metrics
@@ -226,7 +226,7 @@ module Ukiryu
       self.class.new(
         platform: changes.fetch(:platform, @platform),
         shell: changes.fetch(:shell, @shell),
-        registry_path: changes.fetch(:registry_path, @registry_path),
+        register_path: changes.fetch(:register_path, @register_path),
         timeout: changes.fetch(:timeout, @timeout),
         debug: changes.fetch(:debug, @debug),
         metrics: changes.fetch(:metrics, @metrics),
@@ -238,7 +238,7 @@ module Ukiryu
     #
     # @return [String] the context as a string
     def to_s
-      "ExecutionContext(platform=#{@platform}, shell=#{@shell}, registry=#{@registry_path})"
+      "ExecutionContext(platform=#{@platform}, shell=#{@shell}, register=#{@register_path})"
     end
 
     # Inspect

data/lib/ukiryu/executor.rb

@@ -269,6 +269,12 @@ module Ukiryu
 
         # Add shell-specific headless environment
         headless = shell_instance.headless_environment
+
+        # For headless mode, explicitly remove DISPLAY
+        # If user_env explicitly didn't set DISPLAY, respect that (caller wants it removed)
+        # Otherwise, check if headless environment specifies DISPLAY
+        env.delete('DISPLAY') unless headless.key?('DISPLAY')
+
         env.merge!(headless)
 
         env

data/lib/ukiryu/extractors/extractor.rb

@@ -48,11 +48,12 @@ module Ukiryu
       def extract
         method = @options[:method] || :auto
 
-        if method == :auto
+        case method
+        when :auto
           extract_auto
-        elsif method == :native
+        when :native
           extract_with_native
-        elsif method == :help
+        when :help
           extract_with_help
         else
           {
@@ -105,7 +106,7 @@ module Ukiryu
         else
           {
             success: false,
-            error: "Native extraction failed",
+            error: 'Native extraction failed',
             method: :native,
             yaml: nil
           }
@@ -139,7 +140,7 @@ module Ukiryu
         else
           {
             success: false,
-            error: "Help parsing failed",
+            error: 'Help parsing failed',
             method: :help,
             yaml: nil
           }

data/lib/ukiryu/extractors/help_parser.rb

@@ -75,7 +75,7 @@ module Ukiryu
       #
       # @param help_text [String] the help output
       # @return [String] the tool name
-      def extract_name(help_text)
+      def extract_name(_help_text)
         # Use the tool name passed to the extractor
         @tool_name.to_s
       end
@@ -88,9 +88,7 @@ module Ukiryu
         if version_result[:exit_status].zero?
           version_text = version_result[:stdout]
           # Try to extract version number
-          if version_text =~ /(\d+\.\d+(?:\.\d+)?)/
-            return Regexp.last_match(1)
-          end
+          return Regexp.last_match(1) if version_text =~ /(\d+\.\d+(?:\.\d+)?)/
         end
         nil
       end
@@ -124,17 +122,13 @@ module Ukiryu
               'description' => line.strip
             }
 
-            if short_opt
-              option['cli'] = short_opt
-            else
-              option['cli'] = "--#{long_opt}"
-            end
+            option['cli'] = (short_opt || "--#{long_opt}")
 
-            if param
-              option['type'] = infer_type(param)
-            else
-              option['type'] = 'boolean'
-            end
+            option['type'] = if param
+                               infer_type(param)
+                             else
+                               'boolean'
+                             end
 
             options << option
           elsif line =~ /^\s*\[--([a-z-]+)(?:[=\s]+([A-Z_]+))?\]/i
@@ -147,11 +141,11 @@ module Ukiryu
               'description' => line.strip
             }
 
-            if param
-              option['type'] = infer_type(param)
-            else
-              option['type'] = 'boolean'
-            end
+            option['type'] = if param
+                               infer_type(param)
+                             else
+                               'boolean'
+                             end
 
             options << option
           end

data/lib/ukiryu/logger.rb

@@ -172,7 +172,9 @@ module Ukiryu
       if @paint_available
         paint = Paint.method(:[])
         @output.puts ''
-        @output.puts "#{paint['  ✓', :green]} #{paint[selected_tool, :cyan, :bright]}#{paint[' implements: ', :white]}#{paint[identifier, :yellow]}"
+        @output.puts "#{paint['  ✓',
+                              :green]} #{paint[selected_tool, :cyan,
+                                               :bright]}#{paint[' implements: ', :white]}#{paint[identifier, :yellow]}"
       else
         @output.puts ''
         @output.puts "  ✓ #{selected_tool} implements: #{identifier}"

data/lib/ukiryu/models/command_definition.rb

@@ -23,10 +23,10 @@ module Ukiryu
       attribute :description, :string
       attribute :usage, :string
       attribute :subcommand, :string
-      attribute :execution_mode, :string
       attribute :belongs_to, :string  # Parent command this action belongs to
       attribute :cli_flag, :string    # CLI flag for this action (e.g., '-d' for delete)
       attribute :aliases, :string, collection: true, default: []
+      attribute :use_env_vars, :string, collection: true, default: []
 
       # Collections of model objects (lutaml-model handles serialization automatically)
       attribute :options, OptionDefinition, collection: true
@@ -34,7 +34,7 @@ module Ukiryu
       attribute :arguments, ArgumentDefinition, collection: true
       attribute :post_options, OptionDefinition, collection: true
       attribute :env_vars, EnvVarDefinition, collection: true
-      attribute :exit_codes, ExitCodes  # Exit code definitions for this command
+      attribute :exit_codes, ExitCodes # Exit code definitions for this command
 
       yaml do
         map_element 'name', to: :name
@@ -47,7 +47,7 @@ module Ukiryu
         map_element 'post_options', to: :post_options
         map_element 'env_vars', to: :env_vars
         map_element 'exit_codes', to: :exit_codes
-        map_element 'execution_mode', to: :execution_mode
+        map_element 'use_env_vars', to: :use_env_vars
         map_element 'belongs_to', to: :belongs_to
         map_element 'cli_flag', to: :cli_flag
         map_element 'aliases', to: :aliases

data/lib/ukiryu/models/command_info.rb

@@ -12,7 +12,7 @@ module Ukiryu
     class CommandInfo < Lutaml::Model::Serializable
       attribute :executable, :string
       attribute :executable_name, :string
-      attribute :tool_name, :string  # Name of the tool being executed
+      attribute :tool_name, :string # Name of the tool being executed
       attribute :arguments, Arguments
       attribute :full_command, :string
       attribute :shell, :string

data/lib/ukiryu/models/components.rb

@@ -8,7 +8,7 @@ require_relative 'exit_codes'
 
 module Ukiryu
   module Models
-    # Components registry for reusable definitions
+    # Components register for reusable definitions
     #
     # Enables sharing common option/argument/flag/exit_codes definitions
     # across commands through `$ref` references.
@@ -98,8 +98,6 @@ module Ukiryu
           argument(name)
         when 'exit_codes'
           @exit_codes
-        else
-          nil
         end
       end
     end