cabriolet 0.1.0

data/lib/cabriolet/decompressors/quantum.rb

@@ -0,0 +1,456 @@
+# frozen_string_literal: true
+
+module Cabriolet
+  module Decompressors
+    # Quantum handles Quantum-compressed data using arithmetic coding
+    # Based on libmspack qtmd.c implementation
+    #
+    # The Quantum method was created by David Stafford, adapted by Microsoft
+    # Corporation.
+    class Quantum < Base
+      # Frame size (32KB per frame)
+      FRAME_SIZE = 32_768
+
+      # Match constants
+      MAX_MATCH = 1028
+
+      # Position slot tables (same as in qtmd.c)
+      POSITION_BASE = [
+        0, 1, 2, 3, 4, 6, 8, 12, 16, 24, 32, 48, 64, 96, 128, 192, 256, 384,
+        512, 768, 1024, 1536, 2048, 3072, 4096, 6144, 8192, 12_288, 16_384,
+        24_576, 32_768, 49_152, 65_536, 98_304, 131_072, 196_608, 262_144,
+        393_216, 524_288, 786_432, 1_048_576, 1_572_864
+      ].freeze
+
+      EXTRA_BITS = [
+        0, 0, 0, 0, 1, 1, 2, 2, 3, 3, 4, 4, 5, 5, 6, 6, 7, 7, 8, 8,
+        9, 9, 10, 10, 11, 11, 12, 12, 13, 13, 14, 14, 15, 15, 16, 16,
+        17, 17, 18, 18, 19, 19
+      ].freeze
+
+      LENGTH_BASE = [
+        0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 14, 18, 22, 26,
+        30, 38, 46, 54, 62, 78, 94, 110, 126, 158, 190, 222, 254
+      ].freeze
+
+      LENGTH_EXTRA = [
+        0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2,
+        3, 3, 3, 3, 4, 4, 4, 4, 5, 5, 5, 5, 0
+      ].freeze
+
+      attr_reader :window_bits, :window_size
+
+      # Represents a symbol in an arithmetic coding model
+      class ModelSymbol
+        attr_accessor :sym, :cumfreq
+
+        def initialize(sym, cumfreq)
+          @sym = sym
+          @cumfreq = cumfreq
+        end
+      end
+
+      # Represents an arithmetic coding model
+      class Model
+        attr_accessor :shiftsleft, :entries, :syms
+
+        def initialize(syms, entries)
+          @syms = syms
+          @entries = entries
+          @shiftsleft = 4
+        end
+      end
+
+      # Initialize Quantum decompressor
+      #
+      # @param io_system [System::IOSystem] I/O system for reading/writing
+      # @param input [System::FileHandle, System::MemoryHandle] Input handle
+      # @param output [System::FileHandle, System::MemoryHandle] Output handle
+      # @param buffer_size [Integer] Buffer size for I/O operations
+      # @param window_bits [Integer] Window size parameter (10-21)
+      def initialize(io_system, input, output, buffer_size, window_bits: 10)
+        super(io_system, input, output, buffer_size)
+
+        # Validate window_bits
+        unless (10..21).cover?(window_bits)
+          raise ArgumentError,
+                "Quantum window_bits must be 10-21, got #{window_bits}"
+        end
+
+        @window_bits = window_bits
+        @window_size = 1 << window_bits
+
+        # Initialize window
+        @window = "\0" * @window_size
+        @window_posn = 0
+        @frame_todo = FRAME_SIZE
+
+        # Arithmetic coding state
+        @h = 0xFFFF
+        @l = 0
+        @c = 0
+        @header_read = false
+
+        # Initialize bitstream for MSB-first reading
+        @bitstream = MSBBitstream.new(io_system, input, buffer_size)
+
+        # Initialize models
+        initialize_models
+      end
+
+      # Decompress Quantum data
+      #
+      # @param bytes [Integer] Number of bytes to decompress
+      # @return [Integer] Number of bytes decompressed
+      def decompress(bytes)
+        return 0 if bytes <= 0
+
+        output_data = String.new(capacity: bytes)
+        bytes_todo = bytes
+
+        while bytes_todo.positive?
+          # Read header if needed (initializes C register)
+          read_frame_header unless @header_read
+
+          # Calculate how much to decode this iteration
+          frame_end = @window_posn + [bytes_todo, @frame_todo,
+                                      @window_size - @window_posn].min
+
+          # Decode symbols
+          while @window_posn < frame_end
+            selector = decode_symbol(@model7)
+
+            if selector < 4
+              # Literal byte from one of 4 models
+              model = case selector
+                      when 0 then @model0
+                      when 1 then @model1
+                      when 2 then @model2
+                      else @model3
+                      end
+
+              sym = decode_symbol(model)
+              @window.setbyte(@window_posn, sym)
+              @window_posn += 1
+              @frame_todo -= 1
+            else
+              # Match
+              match_offset, match_length = decode_match(selector)
+
+              # Validate match doesn't exceed frame or window
+              if @window_posn + match_length > @window_size
+                raise DecompressionError,
+                      "Match exceeds window boundary"
+              end
+
+              @frame_todo -= match_length
+
+              # Copy match
+              copy_match(match_offset, match_length)
+            end
+          end
+
+          # Extract decoded bytes for output
+          output_amount = [@window_posn, bytes_todo].min
+          output_data << @window[0, output_amount]
+          bytes_todo -= output_amount
+
+          # Handle frame completion
+          if @frame_todo.zero?
+            # Re-align to byte boundary
+            @bitstream.byte_align
+
+            # Skip trailer bytes until 0xFF
+            loop do
+              byte = @bitstream.read_bits(8)
+              break if byte == 0xFF
+            end
+
+            @header_read = false
+            @frame_todo = FRAME_SIZE
+          end
+
+          # Handle window wrap
+          @window_posn = 0 if @window_posn == @window_size
+        end
+
+        # Write output
+        io_system.write(output, output_data)
+        bytes
+      end
+
+      private
+
+      # MSB-first bitstream for Quantum (reads 16-bit words MSB first)
+      class MSBBitstream
+        attr_reader :bits_left
+
+        def initialize(io_system, handle, buffer_size)
+          @io_system = io_system
+          @handle = handle
+          @buffer_size = buffer_size
+          @buffer = ""
+          @buffer_pos = 0
+          @bit_buffer = 0
+          @bits_left = 0
+        end
+
+        # Read bits MSB first (matching Quantum's READ_BITS macro)
+        def read_bits(num_bits)
+          while @bits_left < num_bits
+            # Read 16-bit word MSB first
+            b0 = read_byte
+            b1 = read_byte
+            word = (b0 << 8) | b1
+            @bit_buffer = (@bit_buffer << 16) | word
+            @bits_left += 16
+          end
+
+          # Extract bits from MSB side
+          @bits_left -= num_bits
+          (@bit_buffer >> @bits_left) & ((1 << num_bits) - 1)
+        end
+
+        def read_byte
+          if @buffer_pos >= @buffer.bytesize
+            @buffer = @io_system.read(@handle, @buffer_size)
+            @buffer_pos = 0
+            return 0 if @buffer.empty?
+          end
+
+          byte = @buffer.getbyte(@buffer_pos)
+          @buffer_pos += 1
+          byte
+        end
+
+        def byte_align
+          @bits_left -= (@bits_left % 8)
+        end
+      end
+
+      # Initialize all 7 arithmetic coding models
+      def initialize_models
+        # Models depend on window size
+        i = @window_bits * 2
+
+        # Four literal models (64 symbols each)
+        @m0sym = init_model_syms(0, 64)
+        @model0 = Model.new(@m0sym, 64)
+
+        @m1sym = init_model_syms(64, 64)
+        @model1 = Model.new(@m1sym, 64)
+
+        @m2sym = init_model_syms(128, 64)
+        @model2 = Model.new(@m2sym, 64)
+
+        @m3sym = init_model_syms(192, 64)
+        @model3 = Model.new(@m3sym, 64)
+
+        # Three match models (size depends on window)
+        @m4sym = init_model_syms(0, [i, 24].min)
+        @model4 = Model.new(@m4sym, [i, 24].min)
+
+        @m5sym = init_model_syms(0, [i, 36].min)
+        @model5 = Model.new(@m5sym, [i, 36].min)
+
+        @m6sym = init_model_syms(0, i)
+        @model6 = Model.new(@m6sym, i)
+
+        # Match length model
+        @m6lsym = init_model_syms(0, 27)
+        @model6len = Model.new(@m6lsym, 27)
+
+        # Selector model (7 symbols: 0-3 literals, 4-6 matches)
+        @m7sym = init_model_syms(0, 7)
+        @model7 = Model.new(@m7sym, 7)
+      end
+
+      # Initialize model symbol array
+      def init_model_syms(start, len)
+        Array.new(len + 1) do |i|
+          ModelSymbol.new(start + i, len - i)
+        end
+      end
+
+      # Read frame header (initialize C register)
+      def read_frame_header
+        @h = 0xFFFF
+        @l = 0
+        @c = @bitstream.read_bits(16)
+        @header_read = true
+      end
+
+      # Decode a symbol using arithmetic coding
+      # This implements the GET_SYMBOL macro from qtmd.c
+      def decode_symbol(model)
+        # Calculate range
+        range = ((@h - @l) & 0xFFFF) + 1
+        symf = ((((@c - @l + 1) * model.syms[0].cumfreq) - 1) / range) & 0xFFFF
+
+        # Find symbol
+        i = 1
+        while i < model.entries
+          break if model.syms[i].cumfreq <= symf
+
+          i += 1
+        end
+
+        sym = model.syms[i - 1].sym
+
+        # Update range
+        range = (@h - @l) + 1
+        symf = model.syms[0].cumfreq
+        @h = @l + ((model.syms[i - 1].cumfreq * range) / symf) - 1
+        @l += ((model.syms[i].cumfreq * range) / symf)
+
+        # Update model frequencies
+        j = i - 1
+        while j >= 0
+          model.syms[j].cumfreq += 8
+          j -= 1
+        end
+
+        # Check if model needs updating
+        update_model(model) if model.syms[0].cumfreq > 3800
+
+        # Normalize range
+        normalize_range
+
+        sym
+      end
+
+      # Normalize arithmetic coding range
+      def normalize_range
+        loop do
+          if (@l & 0x8000) != (@h & 0x8000)
+            # Underflow case
+            break unless @l.anybits?(0x4000) && @h.nobits?(0x4000)
+
+            @c ^= 0x4000
+            @l &= 0x3FFF
+            @h |= 0x4000
+
+          end
+
+          @l = (@l << 1) & 0xFFFF
+          @h = ((@h << 1) | 1) & 0xFFFF
+          bit = @bitstream.read_bits(1)
+          @c = ((@c << 1) | bit) & 0xFFFF
+        end
+      end
+
+      # Update model statistics (from qtmd_update_model)
+      def update_model(model)
+        model.shiftsleft -= 1
+
+        if model.shiftsleft.positive?
+          # Simple shift
+          (model.entries - 1).downto(0) do |i|
+            model.syms[i].cumfreq >>= 1
+            model.syms[i].cumfreq = model.syms[i + 1].cumfreq + 1 if model.syms[i].cumfreq <= model.syms[i + 1].cumfreq
+          end
+        else
+          # Full rebuild
+          model.shiftsleft = 50
+
+          # Convert cumfreq to frequencies
+          (0...model.entries).each do |i|
+            model.syms[i].cumfreq -= model.syms[i + 1].cumfreq
+            model.syms[i].cumfreq += 1
+            model.syms[i].cumfreq >>= 1
+          end
+
+          # Sort by frequency (selection sort for stability)
+          (0...(model.entries - 1)).each do |i|
+            ((i + 1)...model.entries).each do |j|
+              if model.syms[i].cumfreq < model.syms[j].cumfreq
+                model.syms[i], model.syms[j] = model.syms[j], model.syms[i]
+              end
+            end
+          end
+
+          # Convert back to cumulative frequencies
+          (model.entries - 1).downto(0) do |i|
+            model.syms[i].cumfreq += model.syms[i + 1].cumfreq
+          end
+        end
+      end
+
+      # Decode match offset and length
+      def decode_match(selector)
+        case selector
+        when 4
+          # Fixed length match (3 bytes)
+          sym = decode_symbol(@model4)
+          extra = @bitstream.read_bits(EXTRA_BITS[sym]) if EXTRA_BITS[sym].positive?
+          match_offset = POSITION_BASE[sym] + (extra || 0) + 1
+          match_length = 3
+        when 5
+          # Fixed length match (4 bytes)
+          sym = decode_symbol(@model5)
+          extra = @bitstream.read_bits(EXTRA_BITS[sym]) if EXTRA_BITS[sym].positive?
+          match_offset = POSITION_BASE[sym] + (extra || 0) + 1
+          match_length = 4
+        when 6
+          # Variable length match
+          sym = decode_symbol(@model6len)
+          extra = @bitstream.read_bits(LENGTH_EXTRA[sym]) if LENGTH_EXTRA[sym].positive?
+          match_length = LENGTH_BASE[sym] + (extra || 0) + 5
+
+          sym = decode_symbol(@model6)
+          extra = @bitstream.read_bits(EXTRA_BITS[sym]) if EXTRA_BITS[sym].positive?
+          match_offset = POSITION_BASE[sym] + (extra || 0) + 1
+        else
+          raise DecompressionError, "Invalid selector: #{selector}"
+        end
+
+        [match_offset, match_length]
+      end
+
+      # Copy match from window
+      def copy_match(offset, length)
+        if offset > @window_posn
+          # Match wraps around window
+          if offset > @window_size
+            raise DecompressionError,
+                  "Match offset beyond window"
+          end
+
+          # Copy from end of window
+          src_pos = @window_size - (offset - @window_posn)
+          copy_len = offset - @window_posn
+
+          if copy_len < length
+            # Copy from end, then from beginning
+            copy_len.times do
+              @window.setbyte(@window_posn, @window.getbyte(src_pos))
+              @window_posn += 1
+              src_pos += 1
+            end
+            src_pos = 0
+            (length - copy_len).times do
+              @window.setbyte(@window_posn, @window.getbyte(src_pos))
+              @window_posn += 1
+              src_pos += 1
+            end
+          else
+            # Copy entirely from end
+            length.times do
+              @window.setbyte(@window_posn, @window.getbyte(src_pos))
+              @window_posn += 1
+              src_pos += 1
+            end
+          end
+        else
+          # Normal copy
+          src_pos = @window_posn - offset
+          length.times do
+            @window.setbyte(@window_posn, @window.getbyte(src_pos))
+            @window_posn += 1
+            src_pos += 1
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cabriolet/errors.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Cabriolet
+  # Base error class for all Cabriolet errors
+  class Error < StandardError; end
+
+  # Raised when there's an I/O error
+  class IOError < Error; end
+
+  # Raised when parsing a CAB file fails
+  class ParseError < Error; end
+
+  # Raised during decompression
+  class DecompressionError < Error; end
+
+  # Raised during compression
+  class CompressionError < Error; end
+
+  # Raised when a checksum doesn't match
+  class ChecksumError < Error; end
+
+  # Raised when an unsupported format is encountered
+  class UnsupportedFormatError < Error; end
+
+  # Raised when invalid arguments are provided
+  class ArgumentError < ::ArgumentError; end
+
+  # Raised when file signature doesn't match expected format
+  class SignatureError < Error; end
+
+  # Raised when file format is invalid or corrupted
+  class FormatError < Error; end
+
+  # Raised when read operation fails
+  class ReadError < IOError; end
+
+  # Raised when seek operation fails
+  class SeekError < IOError; end
+end

data/lib/cabriolet/format_detector.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Cabriolet
+  # Detects archive format based on magic bytes and file structure
+  class FormatDetector
+    # Magic byte signatures for supported formats
+    MAGIC_SIGNATURES = {
+      "MSCF" => :cab,
+      "ITSF" => :chm,
+      "\x3F\x5F" => :hlp,       # ?_
+      "\x4C\x4E" => :hlp,       # LN (alternative HLP signature)
+      "KWAJ" => :kwaj,
+      "SZDD" => :szdd,
+      "\x88\xF0\x27\x00" => :szdd, # Alternative SZDD signature
+      "ITOLITLS" => :lit,
+      "\x00\x00\x00\x00" => :oab, # OAB has null header start
+    }.freeze
+
+    # File extension to format mapping (fallback)
+    EXTENSION_MAP = {
+      ".cab" => :cab,
+      ".chm" => :chm,
+      ".hlp" => :hlp,
+      ".kwj" => :kwaj,
+      ".kwaj" => :kwaj,
+      ".lit" => :lit,
+      ".oab" => :oab,
+      ".szdd" => :szdd,
+    }.freeze
+
+    class << self
+      # Detect format from file path
+      #
+      # @param path [String] Path to the archive file
+      # @return [Symbol, nil] Detected format or nil if unknown
+      def detect(path)
+        return nil unless File.exist?(path)
+
+        # Try magic byte detection first
+        format = detect_by_magic_bytes(path)
+        return format if format
+
+        # Fallback to extension-based detection
+        detect_by_extension(path)
+      end
+
+      # Detect format from IO stream
+      #
+      # @param io [IO] IO object to read from
+      # @return [Symbol, nil] Detected format or nil if unknown
+      def detect_from_io(io)
+        original_pos = io.pos
+
+        # Read first 16 bytes for magic byte checking
+        magic_bytes = io.read(16)
+        io.seek(original_pos) if original_pos
+
+        return nil unless magic_bytes && magic_bytes.size >= 4
+
+        detect_magic_bytes(magic_bytes)
+      end
+
+      # Detect format and return appropriate parser class
+      #
+      # @param path [String] Path to the archive file
+      # @return [Class, nil] Parser class or nil if unknown format
+      def parser_for(path)
+        format = detect(path)
+        format_to_parser(format) if format
+      end
+
+      # Convert format symbol to parser class
+      #
+      # @param format [Symbol] Format symbol
+      # @return [Class, nil] Parser class
+      def format_to_parser(format)
+        case format
+        when :cab
+          Cabriolet::CAB::Parser
+        when :chm
+          Cabriolet::CHM::Parser
+        when :hlp
+          Cabriolet::HLP::Parser
+        when :kwaj
+          Cabriolet::KWAJ::Parser
+        when :szdd
+          Cabriolet::SZDD::Parser
+        when :lit
+          # LIT parser to be implemented
+          nil
+        when :oab
+          # OAB parser to be implemented
+          nil
+        end
+      end
+
+      private
+
+      def detect_by_magic_bytes(path)
+        File.open(path, "rb") do |file|
+          magic_bytes = file.read(16)
+          detect_magic_bytes(magic_bytes)
+        end
+      rescue StandardError
+        nil
+      end
+
+      def detect_magic_bytes(bytes)
+        return nil unless bytes && bytes.size >= 4
+
+        # Check each known signature
+        MAGIC_SIGNATURES.each do |signature, format|
+          if bytes.start_with?(signature) && validate_format(bytes, format)
+            # Additional validation for specific formats
+            return format
+          end
+        end
+
+        nil
+      end
+
+      def detect_by_extension(path)
+        ext = File.extname(path).downcase
+        EXTENSION_MAP[ext]
+      end
+
+      def validate_format(bytes, format)
+        case format
+        when :cab
+          # Verify CAB header structure
+          bytes.size >= 36 && bytes[0..3] == "MSCF"
+        when :chm
+          # Verify CHM header
+          bytes.size >= 8 && bytes[0..3] == "ITSF"
+        when :hlp
+          # HLP files have either ?_ or LN signature
+          bytes.size >= 2 && ["\x3F\x5F", "\x4C\x4E"].include?(bytes[0..1])
+        when :kwaj
+          # Verify KWAJ header
+          bytes.size >= 4 && bytes[0..3] == "KWAJ"
+        when :szdd
+          # SZDD can have multiple signatures
+          bytes.size >= 4 && ["SZDD", "\x88\xF0\x27\x00"].include?(bytes[0..3])
+        when :lit
+          # Verify LIT header
+          bytes.size >= 8 && bytes[0..7] == "ITOLITLS"
+        when :oab
+          # OAB validation would need more specific checks
+          true
+        else
+          true
+        end
+      end
+    end
+  end
+end