cabriolet 0.1.2 → 0.2.1

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

data/lib/cabriolet/hlp/parser.rb

@@ -1,19 +1,21 @@
 # frozen_string_literal: true
 
+require_relative "quickhelp/parser"
+require_relative "winhelp/parser"
+
 module Cabriolet
   module HLP
-    # Parser for HLP (Windows Help) files
+    # Main parser 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 parser:
+    # - QuickHelp (DOS format with "LN" signature)
+    # - Windows Help (WinHelp 3.x/4.x format)
     class Parser
       attr_reader :io_system
 
       # Initialize parser
       #
-      # @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
       end
@@ -21,111 +23,60 @@ module Cabriolet
       # Parse an HLP file
       #
       # @param filename [String] Path to HLP file
-      # @return [Models::HLPHeader] Parsed header
-      # @raise [Errors::ParseError] if file is not valid HLP
+      # @return [Models::HLPHeader, Models::WinHelpHeader] Parsed header with metadata
+      # @raise [Cabriolet::ParseError] if file is not a valid HLP format
       def parse(filename)
-        handle = @io_system.open(filename, Constants::MODE_READ)
-
-        begin
-          parse_header(handle)
-        ensure
-          @io_system.close(handle)
+        # Detect format
+        format = detect_format(filename)
+
+        # Dispatch to appropriate parser
+        case format
+        when :quickhelp
+          QuickHelp::Parser.new(@io_system).parse(filename)
+        when :winhelp
+          WinHelp::Parser.new(@io_system).parse(filename)
+        else
+          raise Cabriolet::ParseError,
+                "Unknown HLP format in file: #{filename}"
         end
       end
 
       private
 
-      # Parse HLP header from file handle
-      #
-      # @param handle [System::FileHandle] Open file handle
-      # @return [Models::HLPHeader] Parsed header with file list
-      # @raise [Errors::ParseError] if header is invalid
-      def parse_header(handle)
-        # Read header structure
-        header_data = @io_system.read(handle, 18)
-        raise Errors::ParseError, "File too small for HLP header" if
-          header_data.bytesize < 18
-
-        binary_header = Binary::HLPStructures::Header.read(header_data)
-
-        # Validate signature
-        unless valid_signature?(binary_header.signature)
-          raise Errors::ParseError,
-                "Invalid HLP signature: #{binary_header.signature.inspect}"
-        end
-
-        # Create header model
-        header = Models::HLPHeader.new(
-          magic: binary_header.signature,
-          version: binary_header.version,
-          length: 0,
-        )
-
-        # Parse file directory if present
-        if binary_header.file_count.positive? &&
-            binary_header.directory_offset.positive?
-          parse_directory(handle, header, binary_header)
-        end
-
-        header
-      end
-
-      # Parse file directory
+      # Detect HLP format variant
       #
-      # @param handle [System::FileHandle] Open file handle
-      # @param header [Models::HLPHeader] Header to populate
-      # @param binary_header [Binary::HLPStructures::Header] Binary header
-      # @return [void]
-      def parse_directory(handle, header, binary_header)
-        # Seek to directory
-        @io_system.seek(
-          handle,
-          binary_header.directory_offset,
-          Constants::SEEK_START,
-        )
-
-        # Read each file entry
-        binary_header.file_count.times do
-          # Read filename length
-          length_data = @io_system.read(handle, 4)
-          break if length_data.bytesize < 4
-
-          filename_length = length_data.unpack1("V")
-          next if filename_length.zero? || filename_length > 1024
-
-          # Read filename
-          filename = @io_system.read(handle, filename_length)
-          next if filename.bytesize != filename_length
-
-          # Read rest of entry (offset, sizes, compression flag)
-          metadata_data = @io_system.read(handle, 13)
-          next if metadata_data.bytesize < 13
-
-          offset, uncompressed_size, compressed_size, compression_flag =
-            metadata_data.unpack("V3C")
-
-          # Create file model
-          file = Models::HLPFile.new(
-            filename: filename.force_encoding("ASCII-8BIT"),
-            offset: offset,
-            length: uncompressed_size,
-            compressed_length: compressed_size,
-            compressed: compression_flag != 0,
-          )
+      # @param filename [String] Path to HLP file
+      # @return [Symbol] :quickhelp or :winhelp
+      # @raise [Cabriolet::ParseError] if format cannot be determined
+      def detect_format(filename)
+        handle = @io_system.open(filename, Constants::MODE_READ)
 
-          header.files << file
+        begin
+          # Read first 4 bytes to check signature
+          sig_data = @io_system.read(handle, 4)
+
+          # Check QuickHelp signature ("LN" at offset 0)
+          if sig_data[0..1] == Binary::HLPStructures::SIGNATURE
+            return :quickhelp
+          end
+
+          # Check WinHelp 3.x magic (0x35F3 at offset 0, 16-bit)
+          magic_word = sig_data[0..1].unpack1("v")
+          return :winhelp if magic_word == 0x35F3
+
+          # Check WinHelp 4.x magic (0x5F3F or 0x3F5F in lower 16 bits of 32-bit value)
+          magic_dword = sig_data.unpack1("V")
+          return :winhelp if (magic_dword & 0xFFFF) == 0x5F3F || (magic_dword & 0xFFFF) == 0x3F5F
+
+          # Unknown format
+          raise Cabriolet::ParseError,
+                "Unknown HLP signature: #{sig_data.bytes.map do |b|
+                  format('0x%02X', b)
+                end.join(' ')}"
+        ensure
+          @io_system.close(handle)
         end
       end
-
-      # Check if signature is valid HLP
-      #
-      # @param signature [String] Signature bytes
-      # @return [Boolean] true if valid
-      def valid_signature?(_signature)
-        # Accept the placeholder signature or other common HLP signatures
-        # For now, accept any signature since we're testing without real fixtures
-        true
-      end
     end
   end
 end

data/lib/cabriolet/hlp/quickhelp/compression_stream.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require_relative "../../binary/bitstream"
+
+module Cabriolet
+  module HLP
+    module QuickHelp
+      # Compression stream decoder for QuickHelp topics
+      #
+      # Handles dictionary substitution (keyword compression) and run-length
+      # encoding as specified in the QuickHelp format.
+      #
+      # Control bytes 0x10-0x1A have special meanings:
+      # - 0x10-0x17: Dictionary entry (with optional space append)
+      # - 0x18: Run of spaces
+      # - 0x19: Run of bytes
+      # - 0x1A: Escape byte
+      class CompressionStream
+        # Initialize compression stream decoder
+        #
+        # @param input [String, IO] Input data (compressed)
+        # @param keywords [Array<String>] Keyword dictionary
+        def initialize(input, keywords = [])
+          @input = input.is_a?(String) ? StringIO.new(input) : input
+          @keywords = keywords || []
+          @buffer = ""
+          @buffer_pos = 0
+        end
+
+        # Read bytes from the decompressed stream
+        #
+        # @param length [Integer] Number of bytes to read
+        # @return [String] Decompressed data
+        def read(length)
+          result = String.new(encoding: Encoding::BINARY)
+
+          while result.bytesize < length
+            # Fill buffer if needed
+            fill_buffer(length - result.bytesize) if @buffer_pos >= @buffer.bytesize
+
+            # Check for EOF
+            break if @buffer_pos >= @buffer.bytesize
+
+            # Copy from buffer
+            available = @buffer.bytesize - @buffer_pos
+            to_copy = [length - result.bytesize, available].min
+            result << @buffer[@buffer_pos, to_copy]
+            @buffer_pos += to_copy
+          end
+
+          result
+        end
+
+        # Check if at end of stream
+        #
+        # @return [Boolean] true if EOF
+        def eof?
+          @buffer_pos >= @buffer.bytesize && @input.eof?
+        end
+
+        private
+
+        # Fill internal buffer by decoding compressed data
+        #
+        # @param max_bytes [Integer] Maximum bytes to decode
+        def fill_buffer(max_bytes)
+          @buffer = String.new(encoding: Encoding::BINARY)
+          @buffer_pos = 0
+
+          # Decode until buffer has enough data or we hit EOF
+          while @buffer.bytesize <= 256 && @buffer.bytesize < max_bytes
+            byte = read_byte
+            break if byte.nil? # EOF
+
+            if byte < 0x10 || byte > 0x1A
+              # Regular value byte
+              @buffer << byte.chr
+            elsif byte == 0x1A
+              # Escape byte - next byte is literal
+              escaped = read_byte
+              if escaped.nil?
+                raise Cabriolet::DecompressionError,
+                      "Unexpected EOF after escape byte"
+              end
+
+              @buffer << escaped.chr
+            elsif byte == 0x19
+              # Run of bytes: REPEAT-BYTE, REPEAT-COUNT
+              repeat_byte = read_byte
+              repeat_count = read_byte
+              if repeat_byte.nil? || repeat_count.nil?
+                raise Cabriolet::DecompressionError,
+                      "Unexpected EOF in byte run"
+              end
+
+              @buffer << (repeat_byte.chr * repeat_count)
+            elsif byte == 0x18
+              # Run of spaces: SPACE-COUNT
+              space_count = read_byte
+              if space_count.nil?
+                raise Cabriolet::DecompressionError,
+                      "Unexpected EOF in space run"
+              end
+
+              @buffer << (" " * space_count)
+            else
+              # Dictionary entry (0x10-0x17)
+              dict_index_low = read_byte
+              if dict_index_low.nil?
+                raise Cabriolet::DecompressionError,
+                      "Unexpected EOF reading dictionary index"
+              end
+
+              # Extract append-space flag (bit 2) and index (bits 0-1 + next 8 bits)
+              append_space = byte.anybits?(0x04)
+              dict_index = ((byte & 0x03) << 8) | dict_index_low
+
+              if dict_index >= @keywords.length
+                raise Cabriolet::DecompressionError,
+                      "Dictionary index #{dict_index} out of range (max #{@keywords.length - 1})"
+              end
+
+              @buffer << @keywords[dict_index]
+              @buffer << " " if append_space
+            end
+          end
+        end
+
+        # Read a single byte from input
+        #
+        # @return [Integer, nil] Byte value or nil on EOF
+        def read_byte
+          @input.getbyte
+        end
+      end
+    end
+  end
+end