ukiryu 0.1.1 → 0.1.3

data/lib/ukiryu/definition/loader.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require_relative 'source'
+require_relative 'sources/file'
+require_relative 'sources/string'
+require_relative '../register'
+require_relative '../models/tool_definition'
+
+module Ukiryu
+  module Definition
+    # Loader for tool definitions from various sources
+    #
+    # The loader orchestrates loading tool definitions from different
+    # sources (files, strings, bundled locations, register) and provides
+    # a unified interface for definition loading.
+    class Loader
+      class << self
+        # Load a tool definition from a source
+        #
+        # @param source [Source] the definition source
+        # @param options [Hash] loading options
+        # @option options [Symbol] :validation validation mode (:strict, :lenient, :none)
+        # @return [Models::ToolDefinition] the loaded tool definition
+        # @raise [DefinitionLoadError] if loading fails
+        def load_from_source(source, options = {})
+          # Check cache first
+          cache_key = source.cache_key
+          return profile_cache[cache_key] if profile_cache.key?(cache_key)
+
+          # Load YAML content from source
+          yaml_content = source.load
+
+          # Parse using lutaml-model
+          profile = parse_yaml(yaml_content, source)
+
+          # Validate if requested
+          validation_mode = options[:validation] || :strict
+          validate_profile(profile, validation_mode) if validation_mode != :none
+
+          # Cache the profile
+          profile_cache[cache_key] = profile
+
+          profile
+        end
+
+        # Load a tool definition from a file path
+        #
+        # @param path [String] path to the definition file
+        # @param options [Hash] loading options
+        # @return [Models::ToolDefinition] the loaded tool definition
+        def load_from_file(path, options = {})
+          source = Sources::FileSource.new(path)
+          load_from_source(source, options)
+        end
+
+        # Load a tool definition from a YAML string
+        #
+        # @param yaml_string [String] the YAML content
+        # @param options [Hash] loading options
+        # @return [Models::ToolDefinition] the loaded tool definition
+        def load_from_string(yaml_string, options = {})
+          source = Sources::StringSource.new(yaml_string)
+          load_from_source(source, options)
+        end
+
+        # Get the profile cache
+        #
+        # @return [Hash] the profile cache
+        def profile_cache
+          @profile_cache ||= {}
+        end
+
+        # Clear the profile cache
+        #
+        # @param source [Source, nil] clear specific source or all if nil
+        def clear_cache(source = nil)
+          if source
+            profile_cache.delete(source.cache_key)
+          else
+            profile_cache.clear
+          end
+        end
+
+        private
+
+        # Parse YAML content into a tool definition
+        #
+        # @param yaml_content [String] the YAML content
+        # @param source [Source] the source for error messages
+        # @return [Models::ToolDefinition] the parsed profile
+        # @raise [DefinitionLoadError] if parsing fails
+        def parse_yaml(yaml_content, source)
+          Models::ToolDefinition.from_yaml(yaml_content)
+        rescue Psych::SyntaxError => e
+          raise DefinitionLoadError,
+                "Invalid YAML in #{source}: #{e.message}"
+        rescue StandardError => e
+          raise DefinitionLoadError,
+                "Failed to parse definition from #{source}: #{e.message}"
+        end
+
+        # Validate a tool profile
+        #
+        # @param profile [Models::ToolDefinition] the profile to validate
+        # @param mode [Symbol] validation mode (:strict, :lenient)
+        # @raise [DefinitionValidationError] if validation fails in strict mode
+        def validate_profile(profile, mode)
+          errors = []
+
+          # Check required fields
+          errors << "Missing 'name' field" unless profile.name
+          errors << "Missing 'version' field" unless profile.version
+          errors << "Missing 'profiles' field or profiles is empty" unless profile.profiles&.any?
+
+          # Check ukiryu_schema format if present
+          errors << "Invalid ukiryu_schema format: #{profile.ukiryu_schema}" if profile.ukiryu_schema && !profile.ukiryu_schema.match?(/^\d+\.\d+$/)
+
+          # Check $self URI format if present
+          errors << "Invalid $self URI format: #{profile.self_uri}" if profile.self_uri && !valid_uri?(profile.self_uri) && (mode == :strict)
+
+          return if errors.empty?
+
+          message = "Profile validation failed:\n  - #{errors.join("\n  - ")}"
+          raise DefinitionValidationError, message if mode == :strict
+
+          warn "[Ukiryu] #{message}"
+        end
+
+        # Check if a string is a valid URI
+        #
+        # @param uri_string [String] the URI to check
+        # @return [Boolean] true if valid URI
+        def valid_uri?(uri_string)
+          uri_string =~ %r{^https?://} || uri_string =~ %r{^file://} ? true : false
+        end
+      end
+    end
+  end
+end

data/lib/ukiryu/definition/metadata.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require_relative '../models/tool_definition'
+
+module Ukiryu
+  module Definition
+    # Metadata about a discovered tool definition
+    #
+    # This class encapsulates information about a tool definition
+    # that was discovered in the filesystem.
+    class DefinitionMetadata
+      include Comparable
+
+      # The tool name
+      # @return [String] tool name
+      attr_reader :name
+
+      # The tool version
+      # @return [String] tool version
+      attr_reader :version
+
+      # The path to the definition file
+      # @return [String] absolute path to the YAML file
+      attr_reader :path
+
+      # The source type (user, system, bundled, register)
+      # @return [Symbol] source type
+      attr_reader :source_type
+
+      # Create a new definition metadata
+      #
+      # @param name [String] tool name
+      # @param version [String] tool version
+      # @param path [String] path to the definition file
+      # @param source_type [Symbol] source type
+      def initialize(name:, version:, path:, source_type:)
+        @name = name
+        @version = version
+        @path = File.expand_path(path)
+        @source_type = source_type
+      end
+
+      # Get the tool definition by loading the YAML
+      #
+      # @return [Models::ToolDefinition] the loaded tool definition
+      # @raise [DefinitionLoadError] if loading fails
+      def load_definition
+        Loader.load_from_file(@path)
+      end
+
+      # Check if the definition file exists
+      #
+      # @return [Boolean] true if file exists
+      def exists?
+        File.exist?(@path)
+      end
+
+      # Get the file modification time
+      #
+      # @return [Time, nil] file mtime, or nil if file doesn't exist
+      def mtime
+        File.mtime(@path) if exists?
+      end
+
+      # Get a string representation
+      #
+      # @return [String] string representation
+      def to_s
+        "#{@name}/#{@version} (#{@source_type}) - #{@path}"
+      end
+
+      # Detailed inspection string
+      #
+      # @return [String] inspection string
+      def inspect
+        "#<#{self.class.name} name=#{@name.inspect} version=#{@version.inspect} path=#{@path.inspect} source_type=#{@source_type.inspect}>"
+      end
+
+      # Compare two metadata objects
+      #
+      # @param other [DefinitionMetadata] the other metadata
+      # @return [Boolean] true if equal
+      def ==(other)
+        return false unless other.is_a?(DefinitionMetadata)
+
+        @name == other.name &&
+          @version == other.version &&
+          @path == other.path &&
+          @source_type == other.source_type
+      end
+
+      # Hash code for hash keys
+      #
+      # @return [Integer] hash code
+      def hash
+        [@name, @version, @path, @source_type].hash
+      end
+
+      # Source type priorities (lower = higher priority)
+      #
+      # @return [Integer] priority value
+      def priority
+        case @source_type
+        when :user then 1
+        when :bundled then 2
+        when :local_system then 3
+        when :system then 4
+        when :register then 5
+        else 999
+        end
+      end
+
+      # Compare priorities for sorting
+      #
+      # @param other [DefinitionMetadata] the other metadata
+      # @return [Integer] comparison result
+      def <=>(other)
+        return 0 unless other.is_a?(DefinitionMetadata)
+
+        # Compare by priority (lower number = higher priority)
+        priority_comparison = priority <=> other.priority
+        return priority_comparison unless priority_comparison.zero?
+
+        # Same priority, compare by version (descending - higher version first)
+        version_comparison = compare_versions(@version, other.version)
+        return version_comparison unless version_comparison.zero?
+
+        # Same version, compare by name
+        @name <=> other.name
+      end
+
+      private
+
+      # Compare version strings
+      #
+      # Returns result for descending order (higher version first)
+      #
+      # @param v1 [String] first version
+      # @param v2 [String] second version
+      # @return [Integer] comparison result (negated for descending)
+      def compare_versions(v1, v2)
+        # Simple version comparison - can be enhanced later
+        parts1 = v1.split('.').map(&:to_i)
+        parts2 = v2.split('.').map(&:to_i)
+
+        max_length = [parts1.length, parts2.length].max
+        max_length.times do |i|
+          p1 = parts1[i] || 0
+          p2 = parts2[i] || 0
+          comparison = p1 <=> p2
+          # Negate for descending order (higher version = lower value)
+          return -comparison unless comparison.zero?
+        end
+
+        0
+      end
+    end
+  end
+end

data/lib/ukiryu/definition/source.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Ukiryu
+  module Definition
+    # Abstract base class for definition sources
+    #
+    # A source represents a location from which a tool definition
+    # can be loaded. Each source type (file, string, bundled, register)
+    # implements this interface.
+    #
+    # @abstract Subclasses must implement {#load}, {#cache_key}, and {#source_type}
+    class Source
+      # Load the YAML definition content
+      #
+      # @abstract
+      # @return [String] the YAML content
+      # @raise [DefinitionLoadError] if the definition cannot be loaded
+      def load
+        raise NotImplementedError, "#{self.class} must implement #load"
+      end
+
+      # Get a unique cache key for this source
+      #
+      # The cache key must uniquely identify both the source location
+      # and its content to ensure proper cache invalidation.
+      #
+      # @abstract
+      # @return [String] a unique cache key
+      def cache_key
+        raise NotImplementedError, "#{self.class} must implement #cache_key"
+      end
+
+      # Get the source type identifier
+      #
+      # @abstract
+      # @return [Symbol] the source type (:file, :string, :bundled, :register)
+      def source_type
+        raise NotImplementedError, "#{self.class} must implement #source_type"
+      end
+
+      # Check if this source is equal to another
+      #
+      # Two sources are equal if they have the same cache key.
+      #
+      # @param other [Object] the object to compare
+      # @return [Boolean] true if sources are equal
+      def ==(other)
+        return false unless other.is_a?(Source)
+
+        cache_key == other.cache_key
+      end
+      alias eql? ==
+
+      # Generate hash code for hash storage
+      #
+      # @return [Integer] hash code based on cache key
+      def hash
+        cache_key.hash
+      end
+
+      # String representation
+      #
+      # @return [String] source description
+      def to_s
+        "#{source_type}:#{cache_key}"
+      end
+
+      # Inspect representation
+      #
+      # @return [String] detailed inspection string
+      def inspect
+        "#<#{self.class.name} source_type=#{source_type} cache_key=#{cache_key}>"
+      end
+
+      protected
+
+      # Calculate SHA256 hash of a string
+      #
+      # @param string [String] the string to hash
+      # @return [String] hexadecimal SHA256 hash
+      def sha256(string)
+        require 'digest'
+        Digest::SHA256.hexdigest(string)
+      end
+    end
+  end
+end

data/lib/ukiryu/definition/sources/file.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require_relative '../source'
+
+module Ukiryu
+  module Definition
+    module Sources
+      # Load tool definitions from a file
+      #
+      # This source reads YAML tool definitions from the filesystem.
+      # It tracks file metadata for cache invalidation.
+      class FileSource < Source
+        # The path to the definition file
+        # @return [String] absolute path to the file
+        attr_reader :path
+
+        # The file modification time
+        # @return [Time] file mtime
+        attr_reader :mtime
+
+        # Create a new file-based definition source
+        #
+        # @param path [String] path to the definition file
+        # @raise [DefinitionNotFoundError] if the file doesn't exist
+        # @raise [DefinitionLoadError] if the file is not readable
+        def initialize(path)
+          @path = expand_path(path)
+          @mtime = nil # Will be set on first load
+          @cached_content = nil
+
+          validate_file_exists!
+          validate_file_readable!
+        end
+
+        # Load the YAML definition content from the file
+        #
+        # @return [String] the YAML content
+        # @raise [DefinitionLoadError] if the file cannot be read
+        def load
+          current_mtime = get_mtime
+
+          # Check if file has changed since init
+          if @mtime && @mtime != current_mtime
+            raise DefinitionLoadError,
+                  "File #{@path} has been modified since it was loaded. " \
+                  "Original mtime: #{@mtime}, Current mtime: #{current_mtime}"
+          end
+
+          @mtime = current_mtime
+
+          # Read and cache content
+          @load ||= read_file
+        end
+
+        # Get the source type
+        #
+        # @return [Symbol] :file
+        def source_type
+          :file
+        end
+
+        # Get a unique cache key for this file source
+        #
+        # The cache key includes a hash of the path and the mtime,
+        # ensuring that file changes invalidate the cache.
+        #
+        # @return [String] unique cache key
+        def cache_key
+          "file:#{sha256(path)}:#{mtime || get_mtime}"
+        end
+
+        # Get the real path (resolves symlinks)
+        #
+        # @return [String] real path to the file
+        def real_path
+          @real_path ||= File.realpath(path)
+        rescue Errno::ENOENT
+          path
+        end
+
+        private
+
+        # Expand the path to an absolute path
+        #
+        # @param path [String] the path to expand
+        # @return [String] absolute path
+        def expand_path(path)
+          File.expand_path(path)
+        end
+
+        # Validate that the file exists
+        #
+        # @raise [DefinitionNotFoundError] if file doesn't exist
+        def validate_file_exists!
+          return if File.exist?(path)
+
+          raise DefinitionNotFoundError,
+                "Definition file not found: #{path}"
+        end
+
+        # Validate that the file is readable
+        #
+        # @raise [DefinitionLoadError] if file is not readable
+        def validate_file_readable!
+          return if File.readable?(path)
+
+          raise DefinitionLoadError,
+                "Definition file is not readable: #{path}"
+        end
+
+        # Get the file modification time
+        #
+        # @return [Time] file mtime
+        # @raise [DefinitionLoadError] if mtime cannot be determined
+        def get_mtime
+          File.mtime(path)
+        rescue Errno::ENOENT, Errno::EACCES => e
+          raise DefinitionLoadError,
+                "Cannot access file metadata for #{path}: #{e.message}"
+        end
+
+        # Read the file content
+        #
+        # @return [String] file content
+        # @raise [DefinitionLoadError] if file cannot be read
+        def read_file
+          File.read(path)
+        rescue Errno::EACCES => e
+          raise DefinitionLoadError,
+                "Permission denied reading file #{path}: #{e.message}"
+        rescue IOError, SystemCallError => e
+          raise DefinitionLoadError,
+                "Error reading file #{path}: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/ukiryu/definition/sources/string.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative '../source'
+
+module Ukiryu
+  module Definition
+    module Sources
+      # Load tool definitions from a YAML string
+      #
+      # This source handles YAML content provided directly as a string,
+      # useful for definitions obtained via command-line flags or
+      # programmatic generation.
+      class StringSource < Source
+        # The YAML content
+        # @return [String] the YAML string
+        attr_reader :content
+
+        # The SHA256 hash of the content
+        # @return [String] hexadecimal hash
+        attr_reader :content_hash
+
+        # Create a new string-based definition source
+        #
+        # @param content [String] the YAML content
+        # @raise [ArgumentError] if content is not a String
+        # @raise [DefinitionLoadError] if content is empty
+        def initialize(content)
+          @content = validate_content!(content)
+          @content_hash = sha256(@content)
+        end
+
+        # Load the YAML definition content
+        #
+        # @return [String] the YAML content
+        def load
+          @content
+        end
+
+        # Get the source type
+        #
+        # @return [Symbol] :string
+        def source_type
+          :string
+        end
+
+        # Get a unique cache key for this string source
+        #
+        # The cache key is based on the SHA256 hash of the content,
+        # ensuring identical strings produce identical cache keys.
+        #
+        # @return [String] unique cache key
+        def cache_key
+          "string:#{content_hash}"
+        end
+
+        # Get the size of the content in bytes
+        #
+        # @return [Integer] content size
+        def size
+          @content.bytesize
+        end
+
+        private
+
+        # Validate the content
+        #
+        # @param content [String] the content to validate
+        # @return [String] the validated content
+        # @raise [ArgumentError] if content is not a String
+        # @raise [DefinitionLoadError] if content is empty
+        def validate_content!(content)
+          unless content.is_a?(String)
+            raise ArgumentError,
+                  "Definition content must be a String, got #{content.class}"
+          end
+
+          if content.empty?
+            raise DefinitionLoadError,
+                  'Definition content cannot be empty'
+          end
+
+          # Strip leading/trailing whitespace but preserve internal formatting
+          content.strip
+        end
+      end
+    end
+  end
+end