ukiryu 0.1.0 → 0.1.1

data/lib/ukiryu/models/execution_report.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+require 'socket'
+require 'etc'
+
+module Ukiryu
+  module Models
+    # Metrics for a single stage of execution
+    class StageMetrics < Lutaml::Model::Serializable
+      attribute :name, :string, default: ''
+      attribute :duration, :float, default: 0.0
+      attribute :formatted_duration, :string, default: ''
+      attribute :memory_before, :integer, default: 0
+      attribute :memory_after, :integer, default: 0
+      attribute :memory_delta, :integer, default: 0
+      attribute :success, :boolean, default: true
+      attribute :error, :string, default: ''
+
+      yaml do
+        map_element 'name', to: :name
+        map_element 'duration', to: :duration
+        map_element 'formatted_duration', to: :formatted_duration
+        map_element 'memory_before', to: :memory_before
+        map_element 'memory_after', to: :memory_after
+        map_element 'memory_delta', to: :memory_delta
+        map_element 'success', to: :success
+        map_element 'error', to: :error
+      end
+
+      # Record the end of a stage
+      def finish!(success: true, error: nil)
+        @duration = Time.now - @start_time if @start_time
+        @formatted_duration = format_duration(@duration)
+        @success = success
+        @error = error if error
+
+        # Record memory after
+        @memory_after = get_memory_usage
+        @memory_delta = @memory_after - @memory_before
+      end
+
+      # Start recording this stage
+      def start!
+        @start_time = Time.now
+        @memory_before = get_memory_usage
+        self
+      end
+
+      private
+
+      def get_memory_usage
+        # Get RSS memory usage in KB
+        `ps -o rss= -p #{Process.pid}`.to_i
+      rescue StandardError
+        0
+      end
+
+      def format_duration(seconds)
+        return '0ms' if seconds.nil? || seconds.zero?
+        return "#{(seconds * 1000).round(2)}ms" if seconds < 1
+
+        "#{seconds.round(2)}s"
+      end
+    end
+
+    # Run environment information
+    class RunEnvironment < Lutaml::Model::Serializable
+      attribute :hostname, :string, default: ''
+      attribute :platform, :string, default: ''
+      attribute :os_version, :string, default: ''
+      attribute :shell, :string, default: ''
+      attribute :shell_override, :boolean, default: false
+      attribute :shell_version, :string, default: ''
+      attribute :ruby_version, :string, default: ''
+      attribute :ukiryu_version, :string, default: ''
+      attribute :cpu_count, :integer, default: 0
+      attribute :total_memory, :integer, default: 0
+      attribute :working_directory, :string, default: ''
+
+      yaml do
+        map_element 'hostname', to: :hostname
+        map_element 'platform', to: :platform
+        map_element 'os_version', to: :os_version
+        map_element 'shell', to: :shell
+        map_element 'shell_override', to: :shell_override
+        map_element 'shell_version', to: :shell_version
+        map_element 'ruby_version', to: :ruby_version
+        map_element 'ukiryu_version', to: :ukiryu_version
+        map_element 'cpu_count', to: :cpu_count
+        map_element 'total_memory', to: :total_memory
+        map_element 'working_directory', to: :working_directory
+      end
+
+      # Collect all environment information
+      #
+      # @return [RunEnvironment] the environment info
+      def self.collect
+        require_relative '../runtime'
+        require_relative '../config'
+        require_relative '../shell'
+
+        runtime = Runtime.instance
+        begin
+          Shell.detect
+        rescue Ukiryu::UnknownShellError
+          'unknown'
+        end
+
+        # Determine if shell was overridden
+        shell_override = !Config.shell.nil?
+        actual_shell = runtime.shell.to_s
+
+        new(
+          hostname: Socket.gethostname,
+          platform: RUBY_PLATFORM,
+          os_version: os_version_string,
+          shell: actual_shell,
+          shell_override: shell_override,
+          shell_version: detect_shell_version_for(actual_shell),
+          ruby_version: RUBY_VERSION,
+          ukiryu_version: Ukiryu::VERSION,
+          cpu_count: Etc.nprocessors,
+          total_memory: detect_total_memory,
+          working_directory: Dir.pwd
+        )
+      end
+
+      # Detect shell version for a specific shell
+      #
+      # @param shell_name [String] the shell name
+      # @return [String] the shell version string
+      def self.detect_shell_version_for(shell_name)
+        return '' if shell_name == 'unknown' || shell_name.empty?
+
+        shell_path = ENV['SHELL']
+        return '' unless shell_path
+
+        `#{shell_path} --version 2>&1`.strip
+      rescue StandardError
+        ''
+      end
+
+      # Get OS version string
+      #
+      # @return [String] the OS version
+      def self.os_version_string
+        # Try to get OS version from RbConfig
+        RbConfig::CONFIG['host_os'] || RbConfig::CONFIG['target_os'] || RUBY_PLATFORM
+      end
+
+      # Detect total system memory
+      #
+      # @return [Integer] total memory in GB
+      def self.detect_total_memory
+        # Get total system memory in GB
+        if RUBY_PLATFORM =~ /darwin/i
+          # macOS
+          `sysctl hw.memsize`.to_i / (1024**3)
+        elsif RUBY_PLATFORM =~ /linux/i
+          # Linux
+          `grep MemTotal /proc/meminfo`.split[1].to_i / 1024
+        else
+          0
+        end
+      rescue StandardError
+        0
+      end
+
+      private_class_method :detect_shell_version_for, :detect_total_memory, :os_version_string
+    end
+
+    # Execution report containing metrics and timing information
+    #
+    # Provides detailed metrics about the execution process including:
+    # - Stage timings (tool resolution, command building, execution)
+    # - Memory usage
+    # - Run environment information
+    class ExecutionReport < Lutaml::Model::Serializable
+      attribute :tool_resolution, StageMetrics
+      attribute :command_building, StageMetrics
+      attribute :execution, StageMetrics
+      attribute :response_building, StageMetrics
+      attribute :total_duration, :float, default: 0.0
+      attribute :formatted_total_duration, :string, default: ''
+      attribute :run_environment, RunEnvironment
+      attribute :timestamp, :string, default: ''
+
+      yaml do
+        map_element 'tool_resolution', to: :tool_resolution
+        map_element 'command_building', to: :command_building
+        map_element 'execution', to: :execution
+        map_element 'response_building', to: :response_building
+        map_element 'total_duration', to: :total_duration
+        map_element 'formatted_total_duration', to: :formatted_total_duration
+        map_element 'run_environment', to: :run_environment
+        map_element 'timestamp', to: :timestamp
+      end
+
+      json do
+        map 'tool_resolution', to: :tool_resolution
+        map 'command_building', to: :command_building
+        map 'execution', to: :execution
+        map 'response_building', to: :response_building
+        map 'total_duration', to: :total_duration
+        map 'formatted_total_duration', to: :formatted_total_duration
+        map 'run_environment', to: :run_environment
+        map 'timestamp', to: :timestamp
+      end
+
+      # Calculate total duration from all stages
+      def calculate_total
+        stages = [tool_resolution, command_building, execution, response_building]
+        total = stages.compact.map(&:duration).sum
+        @total_duration = total
+        @formatted_total_duration = format_duration(total)
+      end
+
+      # Get all stages in order
+      #
+      # @return [Array<StageMetrics>] all stages
+      def all_stages
+        [tool_resolution, command_building, execution, response_building].compact
+      end
+
+      private
+
+      def format_duration(seconds)
+        return '0ms' if seconds.zero?
+        return "#{(seconds * 1000).round(2)}ms" if seconds < 1
+
+        "#{seconds.round(2)}s"
+      end
+    end
+  end
+end

data/lib/ukiryu/models/exit_codes.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+
+module Ukiryu
+  module Models
+    # Exit code definitions for tool commands
+    #
+    # Provides machine-readable error semantics for exit codes.
+    #
+    # @example
+    #   exit_codes = ExitCodes.new(
+    #     standard: { '0' => 'success', '1' => 'general_error' },
+    #     custom: { '3' => 'merge_conflict', '4' => 'permission_denied' }
+    #   )
+    class ExitCodes < Lutaml::Model::Serializable
+      attribute :standard, :hash, default: {}
+      attribute :custom, :hash, default: {}
+
+      yaml do
+        map_element 'standard', to: :standard
+        map_element 'custom', to: :custom
+      end
+
+      # Get the meaning of an exit code
+      #
+      # @param code [Integer] the exit code
+      # @return [String, nil] the meaning or nil if not defined
+      def meaning(code)
+        code_str = code.to_s
+
+        # Check custom codes first (more specific)
+        @custom&.dig(code_str) || @standard&.dig(code_str)
+      end
+
+      # Check if an exit code is defined
+      #
+      # @param code [Integer] the exit code
+      # @return [Boolean] true if defined
+      def defined?(code)
+        !meaning(code).nil?
+      end
+
+      # Check if an exit code indicates success
+      #
+      # @param code [Integer] the exit code
+      # @return [Boolean] true if success (0 or defined as success)
+      def success?(code)
+        code.zero? || meaning(code) == 'success'
+      end
+
+      # Get all defined exit codes
+      #
+      # @return [Hash] all codes merged (standard + custom)
+      def all_codes
+        @standard.to_h.merge(@custom.to_h)
+      end
+
+      # Get standard exit codes
+      #
+      # @return [Hash] standard codes
+      def standard_codes
+        @standard.to_h
+      end
+
+      # Get custom exit codes
+      #
+      # @return [Hash] custom codes
+      def custom_codes
+        @custom.to_h
+      end
+    end
+  end
+end

data/lib/ukiryu/models/flag_definition.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+
+module Ukiryu
+  module Models
+    # Flag definition for a command
+    #
+    # Represents a boolean flag (present or absent)
+    #
+    # @example
+    #   flag = FlagDefinition.new(
+    #     name: 'verbose',
+    #     cli: '-v',
+    #     default: false,
+    #     description: 'Enable verbose output'
+    #   )
+    class FlagDefinition < Lutaml::Model::Serializable
+      attribute :name, :string
+      attribute :cli, :string
+      attribute :default, :boolean, default: false
+      attribute :description, :string
+      attribute :platforms, :string, collection: true, default: []
+
+      yaml do
+        map_element 'name', to: :name
+        map_element 'cli', to: :cli
+        map_element 'default', to: :default
+        map_element 'description', to: :description
+        map_element 'platforms', to: :platforms
+      end
+
+      # Get the effective default value
+      #
+      # @return [Boolean] the default value
+      def default_value
+        default || false
+      end
+
+      # Check if flag applies to a platform
+      #
+      # @param platform [Symbol] the platform
+      # @return [Boolean] true if applies
+      def applies_to?(platform)
+        return true if platforms.nil? || platforms.empty?
+
+        cached_platforms_sym.include?(platform.to_sym)
+      end
+
+      # Get name as symbol (cached for performance)
+      #
+      # @return [Symbol] the name as symbol
+      def name_sym
+        @name_sym ||= name.to_sym
+      end
+
+      private
+
+      # Get platforms as cached symbol array
+      #
+      # @api private
+      def cached_platforms_sym
+        @cached_platforms_sym ||= platforms&.map(&:to_sym) || []
+      end
+    end
+  end
+end

data/lib/ukiryu/models/option_definition.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+
+module Ukiryu
+  module Models
+    # Option definition for a command
+    #
+    # Represents a named option (flag with value)
+    #
+    # @example
+    #   opt = OptionDefinition.new(
+    #     name: 'quality',
+    #     cli: '-q',
+    #     type: 'integer',
+    #     format: 'single_dash_space',
+    #     description: 'JPEG quality'
+    #   )
+    class OptionDefinition < Lutaml::Model::Serializable
+      attribute :name, :string
+      attribute :cli, :string
+      attribute :type, :string, default: 'string'
+      attribute :format, :string, default: 'single_dash_space'
+      attribute :separator, :string
+      attribute :default, :string
+      # Array for numeric range [min, max]
+      attribute :range, :integer, collection: true
+      # Valid values for symbols
+      attribute :values, :string, collection: true
+      # Type of array elements
+      attribute :of, :string
+      attribute :description, :string
+      attribute :platforms, :string, collection: true, default: []
+
+      yaml do
+        map_element 'name', to: :name
+        map_element 'cli', to: :cli
+        map_element 'type', to: :type
+        map_element 'format', to: :format
+        map_element 'separator', to: :separator
+        map_element 'default', to: :default
+        map_element 'range', to: :range
+        map_element 'values', to: :values
+        map_element 'of', to: :of
+        map_element 'description', to: :description
+        map_element 'platforms', to: :platforms
+      end
+
+      # Check if option applies to a platform
+      #
+      # @param platform [Symbol] the platform
+      # @return [Boolean] true if applies
+      def applies_to?(platform)
+        return true if platforms.nil? || platforms.empty?
+
+        cached_platforms_sym.include?(platform.to_sym)
+      end
+
+      # Check if type is boolean
+      #
+      # @return [Boolean] true if boolean type
+      def boolean?
+        type == 'boolean'
+      end
+
+      # Get format as symbol (cached for performance)
+      #
+      # @return [Symbol] the format
+      def format_sym
+        @format_sym ||= format&.to_sym || :single_dash_space
+      end
+
+      # Hash-like access for Type validation compatibility
+      #
+      # @param key [Symbol, String] the attribute key
+      # @return [Object] the attribute value
+      def [](key)
+        key_sym = key.to_sym
+        # Return nil for unknown keys (like Type validation options)
+        return nil unless respond_to?(key_sym, true)
+
+        send(key_sym)
+      end
+
+      # Get name as symbol (cached for performance)
+      #
+      # @return [Symbol] the name as symbol
+      def name_sym
+        @name_sym ||= name.to_sym
+      end
+
+      private
+
+      # Get platforms as cached symbol array
+      #
+      # @api private
+      def cached_platforms_sym
+        @cached_platforms_sym ||= platforms&.map(&:to_sym) || []
+      end
+    end
+  end
+end

data/lib/ukiryu/models/output_info.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+
+module Ukiryu
+  module Models
+    # Command output information
+    #
+    # Contains the standard output and error output from command execution.
+    class OutputInfo < Lutaml::Model::Serializable
+      attribute :stdout, :string, default: ''
+      attribute :stderr, :string, default: ''
+
+      yaml do
+        map_element 'stdout', to: :stdout
+        map_element 'stderr', to: :stderr
+      end
+
+      json do
+        map 'stdout', to: :stdout
+        map 'stderr', to: :stderr
+      end
+    end
+  end
+end

data/lib/ukiryu/models/platform_profile.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+require_relative 'command_definition'
+require_relative 'routing'
+require_relative 'exit_codes'
+
+module Ukiryu
+  module Models
+    # Platform-specific profile for a tool
+    #
+    # @example
+    #   profile = PlatformProfile.new(
+    #     name: 'default',
+    #     platforms: [:macos, :linux],
+    #     commands: [CommandDefinition.new(...)]
+    #   )
+    class PlatformProfile < Lutaml::Model::Serializable
+      attribute :name, :string
+      attribute :display_name, :string
+      attribute :platforms, :string, collection: true, default: []
+      attribute :shells, :string, collection: true, default: []
+      attribute :option_style, :string, default: 'single_dash_space'
+      attribute :commands, CommandDefinition, collection: true, initialize_empty: true
+      attribute :inherits, :string
+      attribute :routing_data, :hash, default: {}  # Raw routing from YAML
+      attribute :version_requirement, :string  # Semantic version requirement (e.g., ">= 2.30")
+      attribute :exit_codes, ExitCodes  # Exit code definitions for this profile
+
+      yaml do
+        map_element 'name', to: :name
+        map_element 'display_name', to: :display_name
+        map_element 'platforms', to: :platforms
+        map_element 'shells', to: :shells
+        map_element 'option_style', to: :option_style
+        map_element 'commands', to: :commands
+        map_element 'inherits', to: :inherits
+        map_element 'routing', to: :routing_data
+        map_element 'version_requirement', to: :version_requirement
+        map_element 'exit_codes', to: :exit_codes
+      end
+
+      # Get the routing table as a Routing model
+      #
+      # @return [Routing] the routing table
+      def routing
+        @routing ||= Routing.new(@routing_data || {})
+      end
+
+      # Check if this profile has routing defined
+      #
+      # @return [Boolean] true if routing table is non-empty
+      def routing?
+        !@routing_data.nil? && !@routing_data.empty?
+      end
+
+      # Check if profile supports a platform
+      #
+      # @param platform [Symbol] the platform
+      # @return [Boolean] true if supported
+      def supports_platform?(platform)
+        platform_list = cached_platforms_sym
+        platform_list.nil? || platform_list.empty? ||
+          platform_list.include?(platform.to_sym)
+      end
+
+      # Check if profile supports a shell
+      #
+      # @param shell [Symbol] the shell
+      # @return [Boolean] true if supported
+      def supports_shell?(shell)
+        shell_list = cached_shells_sym
+        shell_list.nil? || shell_list.empty? ||
+          shell_list.include?(shell.to_sym)
+      end
+
+      # Check if profile is compatible with platform and shell
+      #
+      # @param platform [Symbol] the platform
+      # @param shell [Symbol] the shell
+      # @return [Boolean] true if compatible
+      def compatible?(platform, shell)
+        supports_platform?(platform) && supports_shell?(shell)
+      end
+
+      # Get a command by name using indexed O(1) lookup
+      #
+      # @param name [String, Symbol] the command name
+      # @return [CommandDefinition, nil] the command
+      def command(name)
+        return nil unless commands
+
+        build_commands_index unless @commands_index_built
+        @commands_index[name.to_s]
+      end
+
+      # Get all command names
+      #
+      # @return [Array<String>] command names
+      def command_names
+        return [] unless commands
+
+        build_commands_index unless @commands_index_built
+        @commands_index.keys
+      end
+
+      # Check if universal (supports all)
+      #
+      # @return [Boolean] true if universal
+      def universal?
+        (platforms.nil? || platforms.empty?) &&
+          (shells.nil? || shells.empty?)
+      end
+
+      # Clear the commands index
+      #
+      # Call this if commands are modified after initial loading
+      # (e.g., during inheritance resolution)
+      #
+      # @api private
+      def clear_commands_index!
+        @commands_index = nil
+        @commands_index_built = false
+      end
+
+      private
+
+      # Get platforms as cached symbol array
+      #
+      # @api private
+      def cached_platforms_sym
+        @cached_platforms_sym ||= platforms&.map(&:to_sym)
+      end
+
+      # Get shells as cached symbol array
+      #
+      # @api private
+      def cached_shells_sym
+        @cached_shells_sym ||= shells&.map(&:to_sym)
+      end
+
+      # Build the commands index hash for O(1) lookup
+      #
+      # @api private
+      def build_commands_index
+        return unless commands
+
+        @commands_index = commands.to_h { |c| [c.name, c] }
+        @commands_index_built = true
+      end
+    end
+  end
+end