cabriolet 0.1.2 → 0.2.0

data/lib/cabriolet/hlp/compressor.rb

@@ -1,271 +1,61 @@
 # frozen_string_literal: true
 
+require_relative "quickhelp/compressor"
+require_relative "winhelp/compressor"
+
 module Cabriolet
   module HLP
-    # Compressor creates HLP (Windows Help) compressed archives
-    #
-    # HLP files contain an internal file system where files can be compressed
-    # using LZSS MODE_MSHELP compression. The compressor builds the archive
-    # structure and compresses files as needed.
+    # Main compressor for HLP files
     #
-    # NOTE: This implementation is based on the knowledge that HLP files use
-    # LZSS compression with MODE_MSHELP, but cannot be fully validated due to
-    # lack of test fixtures and incomplete libmspack implementation.
+    # Creates HLP files in either QuickHelp or Windows Help format.
+    # By default, uses QuickHelp format for compatibility.
     class Compressor
       attr_reader :io_system
 
-      # Default buffer size for I/O operations
-      DEFAULT_BUFFER_SIZE = 2048
-
-      # Initialize a new HLP compressor
+      # Initialize compressor
       #
-      # @param io_system [System::IOSystem, nil] Custom I/O system or nil for
-      #   default
+      # @param io_system [System::IOSystem, nil] Custom I/O system or nil for default
       def initialize(io_system = nil)
         @io_system = io_system || System::IOSystem.new
-        @files = []
+        @quickhelp = QuickHelp::Compressor.new(@io_system)
       end
 
-      # Add a file to the HLP archive
+      # Add a file to the archive
       #
       # @param source_path [String] Path to source file
-      # @param hlp_path [String] Path within HLP archive
-      # @param compress [Boolean] Whether to compress the file
+      # @param hlp_path [String] Path within archive
+      # @param compress [Boolean] Whether to compress
       # @return [void]
       def add_file(source_path, hlp_path, compress: true)
-        @files << {
-          source: source_path,
-          hlp_path: hlp_path,
-          compress: compress,
-        }
+        @quickhelp.add_file(source_path, hlp_path, compress: compress)
       end
 
-      # Add data from memory to the HLP archive
+      # Add data from memory
       #
       # @param data [String] Data to add
-      # @param hlp_path [String] Path within HLP archive
-      # @param compress [Boolean] Whether to compress the data
+      # @param hlp_path [String] Path within archive
+      # @param compress [Boolean] Whether to compress
       # @return [void]
       def add_data(data, hlp_path, compress: true)
-        @files << {
-          data: data,
-          hlp_path: hlp_path,
-          compress: compress,
-        }
+        @quickhelp.add_data(data, hlp_path, compress: compress)
       end
 
-      # Generate HLP archive
+      # Generate HLP archive (QuickHelp format by default)
       #
-      # @param output_file [String] Path to output HLP file
-      # @param options [Hash] Compression options
-      # @option options [Integer] :version HLP format version (default: 1)
-      # @return [Integer] Bytes written to output file
-      # @raise [Errors::CompressionError] if compression fails
+      # @param output_file [String] Output file path
+      # @param options [Hash] Format options
+      # @return [Integer] Bytes written
       def generate(output_file, **options)
-        version = options.fetch(:version, 1)
-
-        output_handle = @io_system.open(output_file, Constants::MODE_WRITE)
-
-        begin
-          # Compress all files and collect metadata
-          compressed_files = compress_all_files
-
-          # Calculate directory size first
-          directory_size = calculate_directory_size(compressed_files)
-
-          # Calculate offsets
-          header_size = 18 # Header structure size
-          directory_offset = header_size
-          data_offset = header_size + directory_size
-
-          # Assign file offsets
-          current_offset = data_offset
-          compressed_files.each do |file_info|
-            file_info[:offset] = current_offset
-            current_offset += file_info[:compressed_data].bytesize
-          end
-
-          # Write header
-          header_bytes = write_header(
-            output_handle,
-            version,
-            compressed_files.size,
-            directory_offset,
-          )
-
-          # Write directory
-          directory_bytes = write_directory(output_handle, compressed_files)
-
-          # Write file data
-          data_bytes = write_file_data(output_handle, compressed_files)
-
-          header_bytes + directory_bytes + data_bytes
-        ensure
-          @io_system.close(output_handle) if output_handle
-        end
-      end
-
-      private
-
-      # Compress all files and collect metadata
-      #
-      # @return [Array<Hash>] Array of file information hashes
-      def compress_all_files
-        @files.map do |file_spec|
-          compress_file_spec(file_spec)
-        end
-      end
-
-      # Compress a single file specification
-      #
-      # @param file_spec [Hash] File specification
-      # @return [Hash] File information with compressed data
-      def compress_file_spec(file_spec)
-        # Get source data
-        data = file_spec[:data] || read_file_data(file_spec[:source])
-
-        # Compress if requested
-        compressed_data = if file_spec[:compress]
-                            compress_data_lzss(data)
-                          else
-                            data
-                          end
-
-        {
-          hlp_path: file_spec[:hlp_path],
-          uncompressed_size: data.bytesize,
-          compressed_data: compressed_data,
-          compressed: file_spec[:compress],
-        }
-      end
-
-      # Read file data from disk
-      #
-      # @param filename [String] Path to file
-      # @return [String] File contents
-      def read_file_data(filename)
-        handle = @io_system.open(filename, Constants::MODE_READ)
-        begin
-          data = +""
-          loop do
-            chunk = @io_system.read(handle, DEFAULT_BUFFER_SIZE)
-            break if chunk.empty?
-
-            data << chunk
-          end
-          data
-        ensure
-          @io_system.close(handle)
-        end
-      end
-
-      # Compress data using LZSS MODE_MSHELP
-      #
-      # @param data [String] Data to compress
-      # @return [String] Compressed data
-      def compress_data_lzss(data)
-        input_handle = System::MemoryHandle.new(data)
-        output_handle = System::MemoryHandle.new("", Constants::MODE_WRITE)
-
-        compressor = Compressors::LZSS.new(
-          @io_system,
-          input_handle,
-          output_handle,
-          DEFAULT_BUFFER_SIZE,
-          Compressors::LZSS::MODE_MSHELP,
-        )
-
-        compressor.compress
-        output_handle.data
-      end
-
-      # Calculate directory size
-      #
-      # @param compressed_files [Array<Hash>] Compressed file information
-      # @return [Integer] Directory size in bytes
-      def calculate_directory_size(compressed_files)
-        size = 0
-        compressed_files.each do |file_info|
-          # 4 bytes for filename length
-          # N bytes for filename
-          # 4 + 4 + 4 + 1 = 13 bytes for file metadata
-          size += 4 + file_info[:hlp_path].bytesize + 13
-        end
-        size
-      end
-
-      # Write HLP header
-      #
-      # @param output_handle [System::FileHandle] Output file handle
-      # @param version [Integer] Format version
-      # @param file_count [Integer] Number of files
-      # @param directory_offset [Integer] Offset to directory
-      # @return [Integer] Number of bytes written
-      def write_header(output_handle, version, file_count, directory_offset)
-        header = Binary::HLPStructures::Header.new
-        header.signature = Binary::HLPStructures::SIGNATURE
-        header.version = version
-        header.file_count = file_count
-        header.directory_offset = directory_offset
-
-        header_data = header.to_binary_s
-        written = @io_system.write(output_handle, header_data)
-
-        unless written == header_data.bytesize
-          raise Errors::CompressionError,
-                "Failed to write HLP header"
-        end
-
-        written
-      end
-
-      # Write file directory
-      #
-      # @param output_handle [System::FileHandle] Output file handle
-      # @param compressed_files [Array<Hash>] Compressed file information
-      # @return [Integer] Number of bytes written
-      def write_directory(output_handle, compressed_files)
-        bytes_written = 0
-
-        compressed_files.each do |file_info|
-          # Write filename length
-          filename = file_info[:hlp_path].b
-          length_data = [filename.bytesize].pack("V")
-          bytes_written += @io_system.write(output_handle, length_data)
-
-          # Write filename
-          bytes_written += @io_system.write(output_handle, filename)
-
-          # Write file metadata
-          metadata = [
-            file_info[:offset],
-            file_info[:uncompressed_size],
-            file_info[:compressed_data].bytesize,
-            file_info[:compressed] ? 1 : 0,
-          ].pack("V3C")
-          bytes_written += @io_system.write(output_handle, metadata)
-        end
-
-        bytes_written
+        @quickhelp.generate(output_file, **options)
       end
 
-      # Write file data
+      # Create a Windows Help format HLP file
       #
-      # @param output_handle [System::FileHandle] Output file handle
-      # @param compressed_files [Array<Hash>] Compressed file information
-      # @return [Integer] Number of bytes written
-      def write_file_data(output_handle, compressed_files)
-        bytes_written = 0
-
-        compressed_files.each do |file_info|
-          written = @io_system.write(
-            output_handle,
-            file_info[:compressed_data],
-          )
-          bytes_written += written
-        end
-
-        bytes_written
+      # @param output_file [String] Output file path
+      # @param options [Hash] Format options
+      # @return [WinHelp::Compressor] Compressor for building WinHelp file
+      def self.create_winhelp(io_system = nil)
+        WinHelp::Compressor.new(io_system)
       end
     end
   end

data/lib/cabriolet/hlp/decompressor.rb

@@ -1,197 +1,157 @@
 # frozen_string_literal: true
 
+require_relative "quickhelp/decompressor"
+require_relative "winhelp/decompressor"
+
 module Cabriolet
   module HLP
-    # Decompressor is the main interface for HLP file operations
-    #
-    # HLP files use LZSS compression with MODE_MSHELP and contain an internal
-    # file system. Files are decompressed using the Decompressors::LZSS class.
+    # Main decompressor for HLP files
     #
-    # NOTE: This implementation is based on the knowledge that HLP files use
-    # LZSS compression with MODE_MSHELP, but cannot be fully validated due to
-    # lack of test fixtures and incomplete libmspack implementation.
+    # Detects the HLP format variant and delegates to the appropriate decompressor:
+    # - QuickHelp (DOS format)
+    # - Windows Help (WinHelp 3.x/4.x format)
     class Decompressor
       attr_reader :io_system, :parser
-      attr_accessor :buffer_size
 
-      # Input buffer size for decompression
-      DEFAULT_BUFFER_SIZE = 2048
-
-      # Initialize a new HLP decompressor
+      # Initialize decompressor
       #
-      # @param io_system [System::IOSystem, nil] Custom I/O system or nil for
-      #   default
+      # @param io_system [System::IOSystem, nil] Custom I/O system or nil for default
       def initialize(io_system = nil)
         @io_system = io_system || System::IOSystem.new
         @parser = Parser.new(@io_system)
-        @buffer_size = DEFAULT_BUFFER_SIZE
+        @delegate = nil
+        @current_format = nil
       end
 
-      # Open and parse an HLP file
+      # Open and parse HLP file
       #
-      # @param filename [String] Path to the HLP file
-      # @return [Models::HLPHeader] Parsed header with file list
-      # @raise [Errors::ParseError] if the file is not a valid HLP
+      # @param filename [String] Path to HLP file
+      # @return [Models::HLPHeader, Models::WinHelpHeader] Parsed header
       def open(filename)
-        header = @parser.parse(filename)
-        header.filename = filename
-        header
+        @current_format = detect_format(filename)
+
+        case @current_format
+        when :quickhelp
+          @delegate = QuickHelp::Decompressor.new(@io_system)
+          @delegate.open(filename)
+        when :winhelp
+          @delegate = WinHelp::Decompressor.new(filename, @io_system)
+          @delegate.parse
+        else
+          raise Cabriolet::ParseError, "Unknown HLP format"
+        end
       end
 
-      # Close an HLP file (no-op for compatibility)
+      # Close HLP file
       #
-      # @param _header [Models::HLPHeader] Header to close
-      # @return [void]
-      def close(_header)
-        # No resources to free in the header itself
-        # File handles are managed separately during extraction
+      # @param header [Models::HLPHeader, Models::WinHelpHeader] Header to close
+      # @return [nil]
+      def close(header)
+        @delegate&.close(header) if @delegate.respond_to?(:close)
         nil
       end
 
-      # Extract a file from HLP archive
+      # Extract a file
       #
-      # @param header [Models::HLPHeader] HLP header from open()
-      # @param hlp_file [Models::HLPFile] File to extract from archive
-      # @param output_path [String] Where to write the extracted file
-      # @return [Integer] Number of bytes written
-      # @raise [Errors::DecompressionError] if extraction fails
+      # @param header [Models::HLPHeader, Models::WinHelpHeader] Parsed header
+      # @param hlp_file [Models::HLPFile] File to extract
+      # @param output_path [String] Output file path
+      # @return [Integer] Bytes written
       def extract_file(header, hlp_file, output_path)
-        raise ArgumentError, "Header must not be nil" unless header
-        raise ArgumentError, "HLP file must not be nil" unless hlp_file
-        raise ArgumentError, "Output path must not be nil" unless output_path
-
-        input_handle = @io_system.open(header.filename, Constants::MODE_READ)
-        output_handle = @io_system.open(output_path, Constants::MODE_WRITE)
-
-        begin
-          # Seek to file data
-          @io_system.seek(input_handle, hlp_file.offset,
-                          Constants::SEEK_START)
-
-          bytes_written = if hlp_file.compressed?
-                            decompress_file(input_handle, output_handle,
-                                            hlp_file)
-                          else
-                            copy_file(input_handle, output_handle, hlp_file)
-                          end
-
-          # Verify size if expected
-          if bytes_written != hlp_file.length && Cabriolet.verbose
-            warn "[Cabriolet] WARNING: extracted #{bytes_written} bytes, " \
-                 "expected #{hlp_file.length} bytes"
-          end
-
-          bytes_written
-        ensure
-          @io_system.close(input_handle) if input_handle
-          @io_system.close(output_handle) if output_handle
+        raise ArgumentError, "Header must not be nil" if header.nil?
+        raise ArgumentError, "HLP file must not be nil" if hlp_file.nil?
+        raise ArgumentError, "Output path must not be nil" if output_path.nil?
+
+        case @current_format
+        when :quickhelp
+          @delegate.extract_file(header, hlp_file, output_path)
+        when :winhelp
+          # WinHelp uses different extraction model
+          raise NotImplementedError,
+                "WinHelp file extraction not yet implemented via this API"
         end
       end
 
-      # Extract a file to memory
+      # Extract file to memory
       #
-      # @param header [Models::HLPHeader] HLP header from open()
+      # @param header [Models::HLPHeader, Models::WinHelpHeader] Parsed header
       # @param hlp_file [Models::HLPFile] File to extract
-      # @return [String] Extracted data
-      # @raise [Errors::DecompressionError] if extraction fails
+      # @return [String] File contents
       def extract_file_to_memory(header, hlp_file)
-        raise ArgumentError, "Header must not be nil" unless header
-        raise ArgumentError, "HLP file must not be nil" unless hlp_file
-
-        input_handle = @io_system.open(header.filename, Constants::MODE_READ)
-        output_handle = System::MemoryHandle.new("", Constants::MODE_WRITE)
-
-        begin
-          # Seek to file data
-          @io_system.seek(input_handle, hlp_file.offset,
-                          Constants::SEEK_START)
-
-          if hlp_file.compressed?
-            decompress_file(input_handle, output_handle, hlp_file)
-          else
-            copy_file(input_handle, output_handle, hlp_file)
-          end
-
-          output_handle.data
-        ensure
-          @io_system.close(input_handle) if input_handle
+        raise ArgumentError, "Header must not be nil" if header.nil?
+        raise ArgumentError, "HLP file must not be nil" if hlp_file.nil?
+
+        case @current_format
+        when :quickhelp
+          @delegate.extract_file_to_memory(header, hlp_file)
+        when :winhelp
+          raise NotImplementedError,
+                "WinHelp memory extraction not yet implemented via this API"
         end
       end
 
-      # Extract all files from HLP archive
+      # Extract all files
       #
-      # @param header [Models::HLPHeader] HLP header from open()
-      # @param output_dir [String] Directory to extract files to
+      # @param header [Models::HLPHeader, Models::WinHelpHeader] Parsed header
+      # @param output_dir [String] Output directory
       # @return [Integer] Number of files extracted
-      # @raise [Errors::DecompressionError] if extraction fails
       def extract_all(header, output_dir)
-        raise ArgumentError, "Header must not be nil" unless header
-        raise ArgumentError, "Output directory must not be nil" unless
-          output_dir
+        raise ArgumentError, "Header must not be nil" if header.nil?
 
-        # Create output directory if needed
-        FileUtils.mkdir_p(output_dir)
-
-        extracted = 0
-        header.files.each do |hlp_file|
-          output_path = ::File.join(output_dir, hlp_file.filename)
-
-          # Create subdirectories if needed
-          output_subdir = ::File.dirname(output_path)
-          FileUtils.mkdir_p(output_subdir)
+        if output_dir.nil?
+          raise ArgumentError,
+                "Output directory must not be nil"
+        end
 
-          extract_file(header, hlp_file, output_path)
-          extracted += 1
+        case @current_format
+        when :quickhelp
+          @delegate.extract_all(header, output_dir)
+        when :winhelp
+          @delegate.extract_all(output_dir)
         end
+      end
 
-        extracted
+      # Extract (alternate API taking filename directly)
+      #
+      # @param filename [String] Path to HLP file
+      # @param output_dir [String] Output directory
+      # @return [Integer] Number of files extracted
+      def self.extract(filename, output_dir, io_system = nil)
+        io_sys = io_system || System::IOSystem.new
+        decompressor = new(io_sys)
+        header = decompressor.open(filename)
+        decompressor.extract_all(header, output_dir)
       end
 
       private
 
-      # Decompress a file using LZSS MODE_MSHELP
+      # Detect HLP format
       #
-      # @param input_handle [System::FileHandle] Input file handle
-      # @param output_handle [System::FileHandle, System::MemoryHandle]
-      #   Output handle
-      # @param hlp_file [Models::HLPFile] File metadata
-      # @return [Integer] Number of bytes written
-      def decompress_file(input_handle, output_handle, hlp_file)
-        # Create LZSS decompressor with MODE_MSHELP
-        decompressor = Decompressors::LZSS.new(
-          @io_system,
-          input_handle,
-          output_handle,
-          @buffer_size,
-          Decompressors::LZSS::MODE_MSHELP,
-        )
-
-        # Decompress
-        decompressor.decompress(hlp_file.compressed_length)
-      end
+      # @param filename [String] Path to file
+      # @return [Symbol] :quickhelp or :winhelp
+      def detect_format(filename)
+        handle = @io_system.open(filename, Constants::MODE_READ)
 
-      # Copy uncompressed file data
-      #
-      # @param input_handle [System::FileHandle] Input file handle
-      # @param output_handle [System::FileHandle, System::MemoryHandle]
-      #   Output handle
-      # @param hlp_file [Models::HLPFile] File metadata
-      # @return [Integer] Number of bytes written
-      def copy_file(input_handle, output_handle, hlp_file)
-        bytes_written = 0
-        remaining = hlp_file.length
-
-        while remaining.positive?
-          chunk_size = [remaining, @buffer_size].min
-          data = @io_system.read(input_handle, chunk_size)
-          break if data.empty?
-
-          written = @io_system.write(output_handle, data)
-          bytes_written += written
-          remaining -= written
-        end
+        begin
+          sig_data = @io_system.read(handle, 4)
+
+          # Check QuickHelp signature ("LN" = 0x4C 0x4E)
+          return :quickhelp if sig_data[0..1] == Binary::HLPStructures::SIGNATURE
+
+          # Check WinHelp 3.x magic (little-endian 16-bit: 0x35F3)
+          magic_word = sig_data[0..1].unpack1("v")
+          return :winhelp if magic_word == 0x35F3
 
-        bytes_written
+          # Check WinHelp 4.x magic (little-endian 32-bit, low 16 bits: 0x5F3F)
+          magic_dword = sig_data.unpack1("V")
+          return :winhelp if (magic_dword & 0xFFFF) == 0x5F3F
+
+          raise Cabriolet::ParseError, "Unknown HLP format: #{sig_data.bytes.map do |b|
+            format('0x%02X', b)
+          end.join(' ')}"
+        ensure
+          @io_system.close(handle)
+        end
       end
     end
   end