cabriolet 0.1.2 → 0.2.1

data/lib/cabriolet/hlp/winhelp/zeck_lz77.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+module Cabriolet
+  module HLP
+    module WinHelp
+      # Zeck LZ77 decompressor for Windows Help files
+      #
+      # Implements the Zeck LZ77 compression algorithm used in WinHelp files.
+      # This is a variant of LZ77 with specific encoding:
+      # - 4KB sliding window (4096 bytes)
+      # - Minimum match: 3 bytes
+      # - Maximum match: 271 bytes
+      # - Flag-based token control (8 tokens per flag byte)
+      #
+      # Encoding:
+      # - Flag byte: 8 bits controlling next 8 tokens
+      #   - Bit = 0: Literal byte follows
+      #   - Bit = 1: Match follows (2-3 bytes)
+      # - Match format:
+      #   - Byte 1: OOOO LLLL (O=offset high 4 bits, L=length 0-15)
+      #   - Byte 2: OOOO OOOO (O=offset low 8 bits)
+      #   - Byte 3 (if L=15): Extra length byte (0-252, add 19)
+      #
+      # Match decoding:
+      # - Offset: 12 bits (0-4095)
+      # - Length 3-18: 4 bits (0-15, add 3)
+      # - Length 19-271: Extra byte (0-252, add 19)
+      class ZeckLZ77
+        # Window size for LZ77 compression
+        WINDOW_SIZE = 4096
+
+        # Minimum match length
+        MIN_MATCH = 3
+
+        # Maximum match length without extra byte
+        MAX_SHORT_MATCH = 18
+
+        # Maximum match length with extra byte
+        MAX_LONG_MATCH = 271
+
+        # Initialize decompressor
+        def initialize
+          @window = String.new(capacity: WINDOW_SIZE)
+        end
+
+        # Compress data using Zeck LZ77
+        #
+        # @param input [String] Uncompressed data
+        # @return [String] Compressed data
+        def compress(input)
+          output = +""
+          pos = 0
+          @window.clear
+
+          while pos < input.bytesize
+            # Collect up to 8 tokens for this flag byte
+            tokens = []
+            flag = 0
+
+            8.times do |bit|
+              break if pos >= input.bytesize
+
+              # Try to find a match
+              match = find_best_match(input, pos)
+
+              if match && match[:length] >= MIN_MATCH
+                # Encode match
+                tokens << encode_match(match)
+                flag |= (1 << bit) # Set flag bit for match
+
+                # Add matched bytes to window
+                match[:length].times do
+                  add_to_window(input.getbyte(pos))
+                  pos += 1
+                end
+              else
+                # Encode literal
+                byte = input.getbyte(pos)
+                tokens << [byte].pack("C")
+                add_to_window(byte)
+                pos += 1
+              end
+            end
+
+            # Write flag byte followed by tokens
+            output << [flag].pack("C")
+            tokens.each { |token| output << token }
+          end
+
+          output
+        end
+
+        # Find best match in sliding window
+        #
+        # @param input [String] Input data
+        # @param pos [Integer] Current position
+        # @return [Hash, nil] Match info or nil
+        def find_best_match(input, pos)
+          return nil if @window.empty?
+
+          best_match = nil
+          best_length = 0
+
+          # Search window for matches
+          window_size = @window.bytesize
+          max_offset = [window_size, WINDOW_SIZE].min
+
+          # Start from most recent bytes (end of window)
+          (1..max_offset).each do |offset|
+            window_pos = window_size - offset
+            match_length = 0
+
+            # Count matching bytes
+            while match_length < MAX_LONG_MATCH &&
+                (pos + match_length) < input.bytesize &&
+                (window_pos + match_length) < window_size
+
+              if @window.getbyte(window_pos + match_length) == input.getbyte(pos + match_length)
+                match_length += 1
+              else
+                break
+              end
+            end
+
+            # Update best match if this is better
+            if match_length >= MIN_MATCH && match_length > best_length
+              best_length = match_length
+              best_match = {
+                offset: offset,
+                length: match_length,
+              }
+            end
+          end
+
+          best_match
+        end
+
+        # Encode a match into bytes
+        #
+        # @param match [Hash] Match with :offset and :length
+        # @return [String] Encoded match (2-3 bytes)
+        def encode_match(match)
+          offset = match[:offset]
+          length = match[:length]
+
+          # Calculate encoded length
+          encoded_length = length - MIN_MATCH
+
+          if length <= MAX_SHORT_MATCH
+            # Short match: 2 bytes
+            # Byte 1: OOOO LLLL (high offset 4 bits, length 0-15)
+            # Byte 2: OOOO OOOO (low offset 8 bits)
+            byte1 = ((offset >> 4) & 0xF0) | (encoded_length & 0x0F)
+            byte2 = offset & 0xFF
+            [byte1, byte2].pack("CC")
+          else
+            # Long match: 3 bytes (length > 18, needs extra byte)
+            # Byte 1: OOOO 1111 (high offset, length = 15)
+            # Byte 2: OOOO OOOO (low offset)
+            # Byte 3: Extra length (length - 19)
+            byte1 = ((offset >> 4) & 0xF0) | 0x0F
+            byte2 = offset & 0xFF
+            byte3 = length - 19
+            [byte1, byte2, byte3].pack("CCC")
+          end
+        end
+
+        # Decompress Zeck LZ77 compressed data
+        #
+        # @param input [String] Compressed data
+        # @param output_size [Integer] Expected decompressed size
+        # @return [String] Decompressed data
+        # @raise [Cabriolet::DecompressionError] if decompression fails
+        def decompress(input, output_size)
+          output = String.new(capacity: output_size)
+          input_pos = 0
+          @window.clear
+
+          while output.bytesize < output_size && input_pos < input.bytesize
+            # Read flag byte
+            flags = input.getbyte(input_pos)
+            input_pos += 1
+            break if input_pos > input.bytesize
+
+            # Process 8 tokens controlled by flag byte
+            8.times do |bit|
+              break if output.bytesize >= output_size
+
+              if flags.nobits?(1 << bit)
+                # Bit = 0: Literal byte
+                byte = input.getbyte(input_pos)
+                return output if byte.nil? # End of input
+
+                input_pos += 1
+                output << byte.chr
+                add_to_window(byte)
+              else
+                # Bit = 1: Match (2-3 bytes)
+                break if input_pos + 1 >= input.bytesize
+
+                # Read match bytes
+                byte1 = input.getbyte(input_pos)
+                byte2 = input.getbyte(input_pos + 1)
+                input_pos += 2
+
+                # Decode offset and length
+                # byte1: OOOO LLLL (high offset and length)
+                # byte2: OOOO OOOO (low offset)
+                offset = ((byte1 & 0xF0) << 4) | byte2
+                length = (byte1 & 0x0F) + MIN_MATCH
+
+                # If length is max short match, check for extra length byte
+                if length == (15 + MIN_MATCH) && input_pos < input.bytesize
+                  extra = input.getbyte(input_pos)
+                  input_pos += 1
+                  length = extra + 19 # Length 19-271
+                end
+
+                # Copy from window
+                copy_match(output, offset, length)
+              end
+            end
+          end
+
+          output
+        end
+
+        private
+
+        # Add byte to sliding window
+        #
+        # @param byte [Integer] Byte to add
+        def add_to_window(byte)
+          @window << byte.chr
+          @window = @window[-WINDOW_SIZE..] if @window.bytesize > WINDOW_SIZE
+        end
+
+        # Copy match from window
+        #
+        # @param output [String] Output buffer
+        # @param offset [Integer] Offset in window (0-4095)
+        # @param length [Integer] Match length (3-271)
+        def copy_match(output, offset, length)
+          # Calculate position in window
+          window_pos = @window.bytesize - offset
+
+          if window_pos.negative?
+            raise Cabriolet::DecompressionError,
+                  "Invalid offset: #{offset}"
+          end
+
+          # Copy bytes from window
+          length.times do
+            if window_pos < @window.bytesize
+              byte = @window.getbyte(window_pos)
+              output << byte.chr
+              add_to_window(byte)
+              window_pos += 1
+            else
+              # Match extends beyond current window, copy from output
+              # This handles overlapping matches
+              byte = output.getbyte(output.bytesize - offset)
+              output << byte.chr
+              add_to_window(byte)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cabriolet/huffman/encoder.rb

@@ -53,20 +53,23 @@ module Cabriolet
       #
       # @return [Hash] Hash with :literal and :distance code tables
       def self.build_fixed_codes
-        # Fixed literal/length code lengths
-        literal_lengths = Array.new(288, 0)
-        (0...144).each { |i| literal_lengths[i] = 8 }
-        (144...256).each { |i| literal_lengths[i] = 9 }
-        (256...280).each { |i| literal_lengths[i] = 7 }
-        (280...288).each { |i| literal_lengths[i] = 8 }
+        # Memoize fixed codes since they never change
+        @build_fixed_codes ||= begin
+          # Fixed literal/length code lengths
+          literal_lengths = Array.new(288, 0)
+          (0...144).each { |i| literal_lengths[i] = 8 }
+          (144...256).each { |i| literal_lengths[i] = 9 }
+          (256...280).each { |i| literal_lengths[i] = 7 }
+          (280...288).each { |i| literal_lengths[i] = 8 }
 
-        # Fixed distance code lengths (all 5 bits)
-        distance_lengths = Array.new(32, 5)
+          # Fixed distance code lengths (all 5 bits)
+          distance_lengths = Array.new(32, 5)
 
-        {
-          literal: build_codes(literal_lengths, 288),
-          distance: build_codes(distance_lengths, 32),
-        }
+          {
+            literal: build_codes(literal_lengths, 288),
+            distance: build_codes(distance_lengths, 32),
+          }
+        end
       end
 
       # Encode a symbol using Huffman codes and write to bitstream

data/lib/cabriolet/huffman/tree.rb

@@ -13,9 +13,11 @@ module Cabriolet
       #
       # @param lengths [Array<Integer>] Code lengths for each symbol
       # @param num_symbols [Integer] Number of symbols
-      def initialize(lengths, num_symbols)
+      # @param bit_order [Symbol] Bit ordering (:lsb or :msb), defaults to :lsb
+      def initialize(lengths, num_symbols, bit_order: :lsb)
         @lengths = lengths
         @num_symbols = num_symbols
+        @bit_order = bit_order
         @table = nil
       end
 
@@ -39,6 +41,88 @@ module Cabriolet
         table_mask = 1 << table_bits
         bit_mask = table_mask >> 1
 
+        if @bit_order == :msb
+          build_table_msb(table_bits, pos, table_mask, bit_mask)
+        else
+          build_table_lsb(table_bits, pos, table_mask, bit_mask)
+        end
+      end
+
+      private
+
+      # Build table for MSB-first bit ordering
+      def build_table_msb(table_bits, pos, table_mask, bit_mask)
+        # Fill entries for codes short enough for direct mapping
+        (1..table_bits).each do |bit_num|
+          (0...num_symbols).each do |sym|
+            next unless lengths[sym] == bit_num
+
+            leaf = pos
+            return false if (pos += bit_mask) > table_mask
+
+            # Fill all possible lookups of this symbol
+            fill = bit_mask
+            while fill.positive?
+              @table[leaf] = sym
+              leaf += 1
+              fill -= 1
+            end
+          end
+          bit_mask >>= 1
+        end
+
+        # Exit with success if table is complete
+        return true if pos == table_mask
+
+        # Mark remaining entries as unused
+        (pos...(table_mask)).each do |sym|
+          @table[sym] = 0xFFFF
+        end
+
+        # next_symbol = base of allocation for long codes
+        next_symbol = [(table_mask >> 1), num_symbols].max
+
+        # Process longer codes (table_bits + 1 to MAX_BITS)
+        pos <<= 16
+        table_mask <<= 16
+        bit_mask = 1 << 15
+
+        ((table_bits + 1)..MAX_BITS).each do |bit_num|
+          (0...num_symbols).each do |sym|
+            next unless lengths[sym] == bit_num
+
+            return false if pos >= table_mask
+
+            # leaf = the first table_bits of the code
+            leaf = pos >> 16
+
+            # Build the tree path for this long code
+            (0...(bit_num - table_bits)).each do |fill_idx|
+              # If this path hasn't been taken yet, allocate two entries
+              if @table[leaf] == 0xFFFF
+                @table[next_symbol << 1] = 0xFFFF
+                @table[(next_symbol << 1) + 1] = 0xFFFF
+                @table[leaf] = next_symbol
+                next_symbol += 1
+              end
+
+              # Follow the path and select either left or right for next bit
+              leaf = @table[leaf] << 1
+              leaf += 1 if (pos >> (15 - fill_idx)).anybits?(1)
+            end
+
+            @table[leaf] = sym
+            pos += bit_mask
+          end
+          bit_mask >>= 1
+        end
+
+        # Full table?
+        pos == table_mask
+      end
+
+      # Build table for LSB-first bit ordering (original implementation)
+      def build_table_lsb(table_bits, pos, table_mask, bit_mask)
         # Fill entries for codes short enough for direct mapping (LSB ordering)
         (1..table_bits).each do |bit_num|
           (0...num_symbols).each do |sym|

data/lib/cabriolet/kwaj/command_handler.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require_relative "../cli/base_command_handler"
+require_relative "decompressor"
+require_relative "compressor"
+
+module Cabriolet
+  module KWAJ
+    # Command handler for KWAJ compressed format
+    #
+    # This handler implements the unified command interface for KWAJ files,
+    # wrapping the existing KWAJ::Decompressor and KWAJ::Compressor classes.
+    #
+    class CommandHandler < Commands::BaseCommandHandler
+      # List KWAJ file information
+      #
+      # For KWAJ files, list displays detailed file information
+      # rather than a file listing (single file archive).
+      #
+      # @param file [String] Path to the KWAJ file
+      # @param options [Hash] Additional options (unused)
+      # @return [void]
+      def list(file, _options = {})
+        validate_file_exists(file)
+
+        decompressor = Decompressor.new
+        header = decompressor.open(file)
+
+        display_kwaj_info(header, file)
+
+        decompressor.close(header)
+      end
+
+      # Extract KWAJ compressed file
+      #
+      # Extracts/decompresses the KWAJ file to its original form.
+      # Auto-detects output filename if not specified.
+      #
+      # @param file [String] Path to the KWAJ file
+      # @param output_dir [String] Output directory (not typically used for KWAJ)
+      # @param options [Hash] Additional options
+      # @option options [String] :output Output file path
+      # @return [void]
+      def extract(file, output_dir = nil, options = {})
+        validate_file_exists(file)
+
+        output = options[:output]
+
+        # Auto-detect output name if not provided
+        if output.nil? && output_dir.nil?
+          output = auto_output_filename(file)
+        end
+
+        # If output_dir is specified, ensure it exists and construct output path
+        if output.nil? && output_dir
+          output_dir = ensure_output_dir(output_dir)
+          base_name = File.basename(file, ".*")
+          output = File.join(output_dir, base_name)
+        end
+
+        decompressor = Decompressor.new
+        header = decompressor.open(file)
+
+        puts "Extracting #{file} -> #{output}" if verbose?
+        bytes = decompressor.extract(header, file, output)
+        decompressor.close(header)
+
+        puts "Extracted #{file} to #{output} (#{bytes} bytes)"
+      end
+
+      # Create KWAJ compressed file
+      #
+      # Compresses a file using KWAJ compression.
+      #
+      # @param output [String] Output KWAJ file path
+      # @param files [Array<String>] Input file (single file for KWAJ)
+      # @param options [Hash] Additional options
+      # @option options [String] :compression Compression method (:none, :xor, :szdd, :mszip)
+      # @option options [Boolean] :include_length Include uncompressed length
+      # @option options [String] :filename Original filename to embed
+      # @option options [String] :extra_data Extra data to include
+      # @return [void]
+      # @raise [ArgumentError] if no file specified or multiple files
+      def create(output, files = [], options = {})
+        raise ArgumentError, "No file specified" if files.empty?
+
+        if files.size > 1
+          raise ArgumentError,
+                "KWAJ format supports only one file at a time"
+        end
+
+        file = files.first
+        unless File.exist?(file)
+          raise ArgumentError,
+                "File does not exist: #{file}"
+        end
+
+        compression = parse_compression_option(options[:compression])
+        compress_options = { compression: compression }
+
+        compress_options[:include_length] = true if options[:include_length]
+        compress_options[:filename] = options[:filename] if options[:filename]
+        if options[:extra_data]
+          compress_options[:extra_data] =
+            options[:extra_data]
+        end
+
+        # Auto-generate output name if not provided
+        if output.nil?
+          output = "#{file}.kwj"
+        end
+
+        compressor = Compressor.new
+
+        puts "Compressing #{file} -> #{output} (#{compression} compression)" if verbose?
+        bytes = compressor.compress(file, output, **compress_options)
+
+        puts "Compressed #{file} to #{output} (#{bytes} bytes, #{compression} compression)"
+      end
+
+      # Display detailed KWAJ file information
+      #
+      # @param file [String] Path to the KWAJ file
+      # @param options [Hash] Additional options (unused)
+      # @return [void]
+      def info(file, _options = {})
+        validate_file_exists(file)
+
+        decompressor = Decompressor.new
+        header = decompressor.open(file)
+
+        display_kwaj_info(header, file)
+
+        decompressor.close(header)
+      end
+
+      # Test KWAJ file integrity
+      #
+      # Verifies the KWAJ file structure.
+      #
+      # @param file [String] Path to the KWAJ file
+      # @param options [Hash] Additional options (unused)
+      # @return [void]
+      def test(file, _options = {})
+        validate_file_exists(file)
+
+        decompressor = Decompressor.new
+        header = decompressor.open(file)
+
+        puts "Testing #{file}..."
+        # TODO: Implement full integrity testing
+        puts "OK: KWAJ file structure is valid"
+        puts "Compression: #{header.compression_name}"
+        puts "Data offset: #{header.data_offset} bytes"
+        puts "Uncompressed size: #{header.length || 'unknown'} bytes"
+
+        decompressor.close(header)
+      end
+
+      private
+
+      # Display KWAJ file information
+      #
+      # @param header [Header] The KWAJ header object
+      # @param file [String] Original file path
+      # @return [void]
+      def display_kwaj_info(header, file)
+        puts "KWAJ File Information"
+        puts "=" * 50
+        puts "Filename: #{file}"
+        puts "Compression: #{header.compression_name}"
+        puts "Data offset: #{header.data_offset} bytes"
+        puts "Uncompressed size: #{header.length || 'unknown'} bytes"
+        puts "Original filename: #{header.filename}" if header.filename
+        if header.extra && !header.extra.empty?
+          puts "Extra data: #{header.extra_length} bytes"
+          puts "  #{header.extra}"
+        end
+      end
+
+      # Auto-detect output filename from KWAJ header
+      #
+      # @param file [String] Original file path
+      # @return [String] Detected output filename
+      def auto_output_filename(file)
+        decompressor = Decompressor.new
+        header = decompressor.open(file)
+        output = decompressor.auto_output_filename(file, header)
+        decompressor.close(header)
+        output
+      end
+
+      # Parse compression option to symbol
+      #
+      # @param compression_value [String, Symbol] The compression type
+      # @return [Symbol] The compression symbol
+      def parse_compression_option(compression_value)
+        return :szdd if compression_value.nil?
+
+        compression = compression_value.to_sym
+        valid_compressions = %i[none xor szdd mszip]
+
+        unless valid_compressions.include?(compression)
+          raise ArgumentError,
+                "Invalid compression: #{compression_value}. " \
+                "Valid options: #{valid_compressions.join(', ')}"
+        end
+
+        compression
+      end
+    end
+  end
+end

data/lib/cabriolet/kwaj/compressor.rb

@@ -22,8 +22,10 @@ module Cabriolet
       #
       # @param io_system [System::IOSystem, nil] Custom I/O system or nil for
       #   default
-      def initialize(io_system = nil)
+      # @param algorithm_factory [AlgorithmFactory, nil] Custom algorithm factory or nil for default
+      def initialize(io_system = nil, algorithm_factory = nil)
         @io_system = io_system || System::IOSystem.new
+        @algorithm_factory = algorithm_factory || Cabriolet.algorithm_factory
       end
 
       # Compress a file to KWAJ format
@@ -372,12 +374,14 @@ module Cabriolet
       # @param output_handle [System::FileHandle] Output handle
       # @return [Integer] Number of bytes written
       def compress_szdd(input_handle, output_handle)
-        compressor = Compressors::LZSS.new(
+        compressor = @algorithm_factory.create(
+          :lzss,
+          :compressor,
           @io_system,
           input_handle,
           output_handle,
           2048,
-          Compressors::LZSS::MODE_QBASIC,
+          mode: Compressors::LZSS::MODE_QBASIC,
         )
         compressor.compress
       end