omnizip 0.3.1

data/lib/omnizip/models/filter_config.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+#
+# Copyright (C) 2025 Ribose Inc.
+#
+# This file is part of Omnizip.
+#
+# Omnizip is a pure Ruby port of 7-Zip compression algorithms.
+# Based on the 7-Zip LZMA SDK by Igor Pavlov.
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2.1 of the License, or (at your option) any later version.
+#
+# See the COPYING file for the complete text of the license.
+#
+
+require_relative "../filter_registry"
+
+module Omnizip
+  module Models
+    # Configuration model for a filter in a compression pipeline.
+    #
+    # This class replaces hash-based filter configuration with a proper
+    # model class. It provides format-aware ID resolution and validation.
+    #
+    # @example Create a BCJ filter configuration
+    #   config = FilterConfig.new(name: :bcj_x86, architecture: :x86)
+    #   config.id_for_format(:xz)         # => 0x04
+    #   config.id_for_format(:seven_zip)  # => 0x03030103
+    #
+    # @example Create a Delta filter configuration
+    #   config = FilterConfig.new(name: :delta)
+    #   config.delta?  # => true
+    class FilterConfig
+      # @return [Symbol] Filter name (:bcj_x86, :delta, etc.)
+      attr_reader :name_sym
+
+      # @return [String] Binary properties data for filter configuration
+      attr_accessor :properties
+
+      # @return [Symbol] Target architecture for BCJ filters
+      attr_accessor :architecture
+
+      # Initialize filter configuration.
+      #
+      # @param attributes [Hash] Initialization attributes
+      # @option attributes [Symbol] :name Filter name
+      # @option attributes [Symbol] :name_sym Filter name (alternative key)
+      # @option attributes [String] :properties Binary properties data
+      # @option attributes [Symbol] :architecture Target architecture
+      def initialize(attributes = {})
+        @name_sym = attributes[:name] || attributes[:name_sym]
+        @properties = attributes[:properties] || "".b
+        @architecture = attributes[:architecture]
+      end
+
+      # Set filter name.
+      #
+      # @param value [Symbol] Filter name
+      # @return [void]
+      def name=(value)
+        @name_sym = value
+      end
+
+      # Get filter name as symbol.
+      #
+      # @return [Symbol] Filter name
+      def name_sym
+        @name_sym
+      end
+
+      # Get filter instance from registry.
+      #
+      # Returns a new instance of the filter. Handles both old-style
+      # registration (direct class) and new-style registration (hash with :class).
+      #
+      # @return [Object] Filter instance from FilterRegistry
+      # @raise [KeyError] If filter not found in registry
+      def filter_instance
+        filter = Omnizip::FilterRegistry.get(@name_sym)
+
+        # Handle both hash-style and direct class registration
+        if filter.is_a?(Hash)
+          # New-style registration - check if architecture is needed
+          klass = filter[:class]
+          if architecture_required?(klass)
+            klass.new(architecture: @architecture) if @architecture
+          else
+            klass.new
+          end
+        elsif filter.is_a?(Class)
+          # Old-style registration - try with architecture if available
+          if @architecture && requires_initialize_kwargs?(filter)
+            filter.new(architecture: @architecture)
+          else
+            filter.new
+          end
+        else
+          # Already an instance
+          filter
+        end
+      end
+
+      # Get filter ID for specific format.
+      #
+      # Delegates to filter instance's id_for_format method if available.
+      # For older filters without id_for_format, returns a default value.
+      #
+      # @param format [Symbol] Format identifier (:seven_zip, :xz)
+      # @return [Integer] Format-specific filter ID
+      # @raise [NotImplementedError] If filter doesn't support id_for_format
+      def id_for_format(format)
+        filter = filter_instance
+        if filter.respond_to?(:id_for_format)
+          filter.id_for_format(format)
+        else
+          raise NotImplementedError,
+                "Filter #{@name_sym} doesn't support format-aware IDs. " \
+                "Use the newer BCJ filter instead."
+        end
+      end
+
+      # Check if this is a BCJ filter.
+      #
+      # @return [Boolean] True if BCJ filter variant
+      def bcj?
+        @name_sym.to_s.start_with?("bcj_")
+      end
+
+      # Check if this is a Delta filter.
+      #
+      # @return [Boolean] True if Delta filter
+      def delta?
+        @name_sym == :delta
+      end
+
+      # Validate configuration.
+      #
+      # @return [Boolean] True if valid
+      # @raise [ArgumentError] If filter name is nil or not registered
+      def validate!
+        raise ArgumentError, "Filter name is required" if @name_sym.nil?
+
+        unless Omnizip::FilterRegistry.registered?(@name_sym)
+          raise ArgumentError, "Filter not registered: #{@name_sym}"
+        end
+
+        true
+      end
+
+      # Convert to hash for backward compatibility.
+      #
+      # @return [Hash] Hash representation with :name, :properties, :architecture
+      def to_h
+        {
+          name: @name_sym,
+          properties: @properties,
+          architecture: @architecture,
+        }
+      end
+
+      private
+
+      # Check if filter class requires architecture argument.
+      #
+      # @param klass [Class] Filter class to check
+      # @return [Boolean] True if architecture is required
+      def architecture_required?(klass)
+        klass.name.include?("BCJ") && !klass.name.include?("BcjX86")
+      end
+
+      # Check if filter class requires keyword arguments for initialize.
+      #
+      # @param klass [Class] Filter class to check
+      # @return [Boolean] True if kwargs are required
+      def requires_initialize_kwargs?(klass)
+        klass.name.include?("BCJ") && !klass.name.include?("BcjX86")
+      end
+    end
+  end
+end

data/lib/omnizip/models/match_result.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Omnizip
+  module Models
+    # Represents the result of pattern matching against archive entries
+    #
+    # Contains matched entries with metadata about the matching process.
+    class MatchResult
+      include Enumerable
+
+      attr_reader :matches, :total_scanned, :pattern
+
+      # Initialize a new match result
+      #
+      # @param pattern [Object] The pattern that was matched
+      # @param matches [Array] Array of matched entries
+      # @param total_scanned [Integer] Total entries scanned
+      def initialize(pattern, matches: [], total_scanned: 0)
+        @pattern = pattern
+        @matches = Array(matches)
+        @total_scanned = total_scanned
+      end
+
+      # Add a matched entry
+      #
+      # @param entry [Object] Entry that matched
+      # @return [self]
+      def add_match(entry)
+        @matches << entry
+        self
+      end
+
+      # Increment the scan counter
+      #
+      # @param count [Integer] Number to increment by
+      # @return [self]
+      def increment_scanned(count = 1)
+        @total_scanned += count
+        self
+      end
+
+      # Get the number of matches
+      #
+      # @return [Integer]
+      def count
+        @matches.size
+      end
+
+      # Check if any matches were found
+      #
+      # @return [Boolean]
+      def any?
+        !@matches.empty?
+      end
+
+      # Check if no matches were found
+      #
+      # @return [Boolean]
+      def none?
+        @matches.empty?
+      end
+
+      # Get match rate (matches/scanned)
+      #
+      # @return [Float] Match rate between 0.0 and 1.0
+      def match_rate
+        return 0.0 if @total_scanned.zero?
+
+        count.to_f / @total_scanned
+      end
+
+      # Get match percentage
+      #
+      # @return [Float] Match percentage between 0.0 and 100.0
+      def match_percentage
+        match_rate * 100.0
+      end
+
+      # Iterate over matches
+      #
+      # @yield [entry] Each matched entry
+      # @return [Enumerator, self]
+      def each(&block)
+        return matches.to_enum unless block
+
+        matches.each(&block)
+        self
+      end
+
+      # Get first match
+      #
+      # @return [Object, nil]
+      def first
+        @matches.first
+      end
+
+      # Get last match
+      #
+      # @return [Object, nil]
+      def last
+        @matches.last
+      end
+
+      # Convert to array
+      #
+      # @return [Array]
+      def to_a
+        @matches.dup
+      end
+
+      # Get summary hash
+      #
+      # @return [Hash]
+      def to_h
+        {
+          pattern: @pattern.to_s,
+          matches: count,
+          scanned: @total_scanned,
+          match_rate: match_rate,
+        }
+      end
+    end
+  end
+end

data/lib/omnizip/models/optimization_suggestion.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Omnizip
+  module Models
+    # Represents a performance optimization suggestion based on profiling data
+    class OptimizationSuggestion
+      SEVERITY_LEVELS = %i[low medium high critical].freeze
+      CATEGORIES = %i[
+        memory cpu hotpath algorithm io gc allocation concurrency
+      ].freeze
+
+      attr_reader :title, :description, :severity, :category, :impact_estimate,
+                  :implementation_effort, :related_operations, :code_locations,
+                  :metrics
+
+      def initialize(
+        title:,
+        description:,
+        severity:,
+        category:,
+        impact_estimate: nil,
+        implementation_effort: nil,
+        related_operations: [],
+        code_locations: [],
+        metrics: {}
+      )
+        validate_severity!(severity)
+        validate_category!(category)
+
+        @title = title
+        @description = description
+        @severity = severity
+        @category = category
+        @impact_estimate = impact_estimate
+        @implementation_effort = implementation_effort
+        @related_operations = related_operations
+        @code_locations = code_locations
+        @metrics = metrics
+      end
+
+      def critical?
+        severity == :critical
+      end
+
+      def high_priority?
+        severity == :high || critical?
+      end
+
+      def priority_score
+        severity_weight = SEVERITY_LEVELS.index(severity) + 1
+        impact_weight = impact_estimate || 1.0
+        effort_weight = implementation_effort ? (1.0 / implementation_effort) : 1.0
+
+        severity_weight * impact_weight * effort_weight
+      end
+
+      def to_h
+        {
+          title: title,
+          description: description,
+          severity: severity,
+          category: category,
+          impact_estimate: impact_estimate,
+          implementation_effort: implementation_effort,
+          priority_score: priority_score,
+          related_operations: related_operations,
+          code_locations: code_locations,
+          metrics: metrics,
+        }
+      end
+
+      private
+
+      def validate_severity!(severity)
+        return if SEVERITY_LEVELS.include?(severity)
+
+        raise ArgumentError,
+              "Invalid severity: #{severity}. " \
+              "Must be one of: #{SEVERITY_LEVELS.join(', ')}"
+      end
+
+      def validate_category!(category)
+        return if CATEGORIES.include?(category)
+
+        raise ArgumentError,
+              "Invalid category: #{category}. " \
+              "Must be one of: #{CATEGORIES.join(', ')}"
+      end
+    end
+  end
+end

data/lib/omnizip/models/parallel_options.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Omnizip
+  module Models
+    # Model for parallel processing configuration
+    #
+    # Stores settings for parallel compression and extraction operations
+    # including thread count, queue size, and load balancing strategy.
+    #
+    # @example Create parallel options
+    #   options = Omnizip::Models::ParallelOptions.new
+    #   options.threads = 8
+    #   options.queue_size = 100
+    #   options.strategy = :dynamic
+    #
+    # @example Use with parallel compression
+    #   Omnizip::Parallel.compress_directory('files/', 'backup.zip', options)
+    class ParallelOptions
+      # @return [Integer] Number of worker threads (default: auto-detect)
+      attr_accessor :threads
+
+      # @return [Integer] Maximum size of job queue (default: 1000)
+      attr_accessor :queue_size
+
+      # @return [Integer] Chunk size for chunked operations in bytes
+      attr_accessor :chunk_size
+
+      # @return [Symbol] Load balancing strategy (:dynamic or :static)
+      attr_accessor :strategy
+
+      # @return [Boolean] Enable verbose progress output
+      attr_accessor :verbose
+
+      # @return [Integer] Batch size for work queue polling
+      attr_accessor :batch_size
+
+      # Initialize parallel options with default values
+      def initialize
+        @threads = detect_cpu_count
+        @queue_size = 1000
+        @chunk_size = 64 * 1024 * 1024 # 64MB default
+        @strategy = :dynamic
+        @verbose = false
+        @batch_size = 10
+      end
+
+      # Validate options
+      #
+      # @raise [ArgumentError] if options are invalid
+      # @return [Boolean] true if valid
+      def validate!
+        raise ArgumentError, "threads must be > 0" if threads <= 0
+        raise ArgumentError, "queue_size must be > 0" if queue_size <= 0
+        raise ArgumentError, "chunk_size must be > 0" if chunk_size <= 0
+        raise ArgumentError, "strategy must be :dynamic or :static" unless %i[
+          dynamic static
+        ].include?(strategy)
+        raise ArgumentError, "batch_size must be > 0" if batch_size <= 0
+
+        true
+      end
+
+      # Create a copy of options
+      #
+      # @return [ParallelOptions] new instance with same values
+      def dup
+        copy = self.class.new
+        copy.threads = threads
+        copy.queue_size = queue_size
+        copy.chunk_size = chunk_size
+        copy.strategy = strategy
+        copy.verbose = verbose
+        copy.batch_size = batch_size
+        copy
+      end
+
+      # Convert to hash
+      #
+      # @return [Hash] options as hash
+      def to_h
+        {
+          threads: threads,
+          queue_size: queue_size,
+          chunk_size: chunk_size,
+          strategy: strategy,
+          verbose: verbose,
+          batch_size: batch_size,
+        }
+      end
+
+      private
+
+      # Detect number of available CPU cores
+      #
+      # @return [Integer] number of CPUs
+      def detect_cpu_count
+        require "etc"
+        Etc.nprocessors
+      rescue StandardError
+        4 # fallback to 4 threads
+      end
+    end
+  end
+end

data/lib/omnizip/models/performance_result.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Omnizip
+  module Models
+    # Represents the performance characteristics of a profiled operation
+    class PerformanceResult
+      attr_reader :operation_name, :total_time, :cpu_time, :wall_time,
+                  :memory_allocated, :memory_retained, :object_allocations,
+                  :gc_runs, :call_count, :timestamp
+
+      def initialize(
+        operation_name:,
+        total_time: nil,
+        cpu_time: nil,
+        wall_time: nil,
+        memory_allocated: nil,
+        memory_retained: nil,
+        object_allocations: nil,
+        gc_runs: nil,
+        call_count: nil,
+        timestamp: Time.now
+      )
+        @operation_name = operation_name
+        @total_time = total_time
+        @cpu_time = cpu_time
+        @wall_time = wall_time
+        @memory_allocated = memory_allocated
+        @memory_retained = memory_retained
+        @object_allocations = object_allocations
+        @gc_runs = gc_runs
+        @call_count = call_count
+        @timestamp = timestamp
+      end
+
+      def throughput_ops_per_second
+        return nil unless call_count && total_time&.positive?
+
+        call_count.to_f / total_time
+      end
+
+      def average_time_per_operation
+        return nil unless call_count && total_time && call_count.positive?
+
+        total_time / call_count.to_f
+      end
+
+      def memory_per_operation
+        return nil unless call_count && memory_allocated && call_count.positive?
+
+        memory_allocated / call_count.to_f
+      end
+
+      def gc_pressure
+        return nil unless gc_runs && total_time&.positive?
+
+        gc_runs.to_f / total_time
+      end
+
+      def to_h
+        {
+          operation_name: operation_name,
+          total_time: total_time,
+          cpu_time: cpu_time,
+          wall_time: wall_time,
+          memory_allocated: memory_allocated,
+          memory_retained: memory_retained,
+          object_allocations: object_allocations,
+          gc_runs: gc_runs,
+          call_count: call_count,
+          throughput_ops_per_second: throughput_ops_per_second,
+          average_time_per_operation: average_time_per_operation,
+          memory_per_operation: memory_per_operation,
+          gc_pressure: gc_pressure,
+          timestamp: timestamp.iso8601,
+        }
+      end
+    end
+  end
+end

data/lib/omnizip/models/profile_report.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Omnizip
+  module Models
+    # Represents an aggregated profiling report with hot path analysis
+    class ProfileReport
+      attr_reader :profile_name, :results, :hot_paths, :bottlenecks,
+                  :timestamp, :metadata
+
+      def initialize(
+        profile_name:,
+        results: [],
+        hot_paths: [],
+        bottlenecks: [],
+        timestamp: Time.now,
+        metadata: {}
+      )
+        @profile_name = profile_name
+        @results = results
+        @hot_paths = hot_paths
+        @bottlenecks = bottlenecks
+        @timestamp = timestamp
+        @metadata = metadata
+      end
+
+      def total_execution_time
+        results.filter_map(&:total_time).sum
+      end
+
+      def total_memory_allocated
+        results.filter_map(&:memory_allocated).sum
+      end
+
+      def total_gc_runs
+        results.filter_map(&:gc_runs).sum
+      end
+
+      def slowest_operations(limit: 5)
+        results.select(&:total_time)
+          .sort_by(&:total_time)
+          .reverse
+          .take(limit)
+      end
+
+      def memory_intensive_operations(limit: 5)
+        results.select(&:memory_allocated)
+          .sort_by(&:memory_allocated)
+          .reverse
+          .take(limit)
+      end
+
+      def add_result(result)
+        @results << result
+      end
+
+      def add_hot_path(hot_path)
+        @hot_paths << hot_path
+      end
+
+      def add_bottleneck(bottleneck)
+        @bottlenecks << bottleneck
+      end
+
+      def to_h
+        {
+          profile_name: profile_name,
+          timestamp: timestamp.iso8601,
+          summary: {
+            total_execution_time: total_execution_time,
+            total_memory_allocated: total_memory_allocated,
+            total_gc_runs: total_gc_runs,
+            operation_count: results.size,
+          },
+          results: results.map(&:to_h),
+          hot_paths: hot_paths,
+          bottlenecks: bottlenecks,
+          metadata: metadata,
+        }
+      end
+    end
+  end
+end

data/lib/omnizip/models/progress_options.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+#
+# Copyright (C) 2025 Ribose Inc.
+#
+
+module Omnizip
+  module Models
+    # Model representing progress tracking options.
+    #
+    # This class encapsulates configuration for progress tracking,
+    # including reporter type, update interval, and display preferences.
+    class ProgressOptions
+      attr_accessor :reporter, :update_interval, :show_rate,
+                    :show_eta, :show_files, :show_bytes
+
+      def initialize
+        @reporter = "auto"
+        @update_interval = 0.5
+        @show_rate = true
+        @show_eta = true
+        @show_files = true
+        @show_bytes = true
+      end
+
+      def to_h
+        {
+          reporter: @reporter,
+          update_interval: @update_interval,
+          show_rate: @show_rate,
+          show_eta: @show_eta,
+          show_files: @show_files,
+          show_bytes: @show_bytes,
+        }.compact
+      end
+    end
+  end
+end