cabriolet 0.1.0

data/lib/cabriolet/chm/decompressor.rb

@@ -0,0 +1,436 @@
+# frozen_string_literal: true
+
+require_relative "parser"
+require_relative "../decompressors/lzx"
+require_relative "../system/file_handle"
+require_relative "../system/memory_handle"
+
+module Cabriolet
+  module CHM
+    # Decompressor for CHM (Compiled HTML Help) files
+    class Decompressor
+      LZX_FRAME_SIZE = 32_768
+
+      attr_reader :io_system, :chm
+
+      def initialize(io_system = nil)
+        @io_system = io_system || System::IOSystem.new
+        @chm = nil
+        @input_handle = nil
+        @lzx_state = nil
+        @lzx_offset = 0
+        @lzx_length = 0
+      end
+
+      # Open a CHM file
+      # @param filename [String] Path to CHM file
+      # @param entire [Boolean] If true, parse all file entries
+      # @return [Models::CHMHeader] CHM header
+      def open(filename, entire: true)
+        @input_handle = @io_system.open(filename, Constants::MODE_READ)
+        @chm = Parser.new(@input_handle).parse(entire: entire)
+        @chm.filename = filename
+        @chm
+      rescue StandardError => e
+        @input_handle&.close
+        @input_handle = nil
+        raise e
+      end
+
+      # Open a CHM file quickly (without parsing file entries)
+      # @param filename [String] Path to CHM file
+      # @return [Models::CHMHeader] CHM header
+      def fast_open(filename)
+        open(filename, entire: false)
+      end
+
+      # Close the CHM file
+      def close
+        cleanup_lzx
+        @input_handle&.close
+        @input_handle = nil
+        @chm = nil
+      end
+
+      # Extract a file from the CHM archive
+      # @param file [Models::CHMFile] File to extract
+      # @param output_path [String] Output path for extracted file
+      # @return [void]
+      def extract(file, output_path)
+        raise ArgumentError, "File is nil" if file.nil?
+        raise ArgumentError, "File section is nil" if file.section.nil?
+
+        # Handle empty files
+        if file.empty?
+          @io_system.open(output_path, Constants::MODE_WRITE).close
+          return
+        end
+
+        case file.section.id
+        when 0
+          extract_uncompressed(file, output_path)
+        when 1
+          extract_compressed(file, output_path)
+        else
+          raise Errors::FormatError, "Invalid section ID: #{file.section.id}"
+        end
+      end
+
+      # Find a file by name using fast_find
+      # @param filename [String] Name of the file to find
+      # @return [Models::CHMFile, nil] The file if found, nil otherwise
+      def fast_find(filename)
+        raise ArgumentError, "CHM not opened" unless @chm
+
+        # Use fast index search if available
+        if @chm.index_root < @chm.num_chunks
+          fast_search_pmgi(filename)
+        else
+          # Linear search through PMGL chunks
+          fast_search_pmgl(filename)
+        end
+      end
+
+      private
+
+      # Extract uncompressed file (section 0)
+      def extract_uncompressed(file, output_path)
+        output_handle = @io_system.open(output_path, Constants::MODE_WRITE)
+
+        # Seek to file data
+        offset = @chm.sec0.offset + file.offset
+        @input_handle.seek(offset, Constants::SEEK_START)
+
+        # Copy data in chunks
+        remaining = file.length
+        buffer_size = 4096
+
+        while remaining.positive?
+          chunk_size = [buffer_size, remaining].min
+          data = @input_handle.read(chunk_size)
+          if data.nil? || data.length < chunk_size
+            raise Errors::ReadError,
+                  "Unexpected end of file"
+          end
+
+          output_handle.write(data)
+          remaining -= chunk_size
+        end
+
+        output_handle.close
+      end
+
+      # Extract compressed file (section 1, MSCompressed/LZX)
+      def extract_compressed(file, output_path)
+        # Initialize LZX decompressor if needed
+        init_lzx(file) unless lzx_ready?(file)
+
+        # Seek to correct position in input
+        @input_handle.seek(@lzx_input_offset, Constants::SEEK_START)
+
+        # Skip to file offset if needed
+        skip_amount = file.offset - @lzx_offset
+        if skip_amount.positive?
+          # Decompress and discard to a dummy memory handle
+          dummy_output = System::MemoryHandle.new("", Constants::MODE_WRITE)
+          saved_output = @lzx_state.instance_variable_get(:@output)
+          @lzx_state.instance_variable_set(:@output, dummy_output)
+          @lzx_state.decompress(skip_amount)
+          @lzx_state.instance_variable_set(:@output, saved_output)
+          @lzx_offset += skip_amount
+        end
+
+        # Decompress to memory buffer
+        memory_output = System::MemoryHandle.new("", Constants::MODE_WRITE)
+        @lzx_state.instance_variable_set(:@output, memory_output)
+        @lzx_state.decompress(file.length)
+        @lzx_offset += file.length
+
+        # Save input position for next extraction
+        @lzx_input_offset = @input_handle.tell
+
+        # Write buffer to file
+        output_handle = @io_system.open(output_path, Constants::MODE_WRITE)
+        output_handle.write(memory_output.buffer)
+        output_handle.close
+      end
+
+      # Check if LZX state is ready for this file
+      def lzx_ready?(file)
+        return false unless @lzx_state
+        return false if file.offset < @lzx_offset
+
+        true
+      end
+
+      # Initialize LZX decompressor for section 1
+      def init_lzx(file)
+        cleanup_lzx
+
+        sec = @chm.sec1
+
+        # Find required system files
+        content = sec.content || find_system_file(Parser::CONTENT_NAME)
+        control = sec.control || find_system_file(Parser::CONTROL_NAME)
+
+        unless content
+          raise Errors::FormatError,
+                "MSCompressed Content file not found"
+        end
+        raise Errors::FormatError, "ControlData file not found" unless control
+
+        # Read control data
+        control_data = read_system_file(control)
+        unless control_data.length == 28
+          raise Errors::FormatError,
+                "ControlData wrong size"
+        end
+
+        window_size, reset_interval = parse_control_data(control_data)
+
+        # Calculate window bits
+        window_bits = case window_size
+                      when 0x008000 then 15
+                      when 0x010000 then 16
+                      when 0x020000 then 17
+                      when 0x040000 then 18
+                      when 0x080000 then 19
+                      when 0x100000 then 20
+                      when 0x200000 then 21
+                      else
+                        raise Errors::FormatError,
+                              "Invalid window size: #{window_size}"
+                      end
+
+        # Validate reset interval
+        if reset_interval.zero? || (reset_interval % LZX_FRAME_SIZE) != 0
+          raise Errors::FormatError, "Invalid reset interval: #{reset_interval}"
+        end
+
+        # Find reset table entry for this file
+        entry = file.offset / reset_interval
+        entry *= reset_interval / LZX_FRAME_SIZE
+
+        length, offset = read_reset_table(sec, entry, reset_interval)
+
+        # Calculate input offset
+        @lzx_input_offset = @chm.sec0.offset + content.offset + offset
+
+        # Set start offset and length
+        @lzx_offset = entry * LZX_FRAME_SIZE
+        @lzx_length = length
+
+        # Seek to input position
+        @input_handle.seek(@lzx_input_offset, Constants::SEEK_START)
+
+        # Create output handle (will be set per extraction)
+        output_handle = System::MemoryHandle.new("")
+
+        # Initialize LZX decompressor
+        @lzx_state = Decompressors::LZX.new(
+          @io_system,
+          @input_handle,
+          output_handle,
+          4096,
+          window_bits: window_bits,
+          reset_interval: reset_interval / LZX_FRAME_SIZE,
+          output_length: length - @lzx_offset,
+        )
+      end
+
+      # Parse control data to get window size and reset interval
+      def parse_control_data(data)
+        signature = data[4, 4]
+        unless signature == "LZXC"
+          raise Errors::SignatureError,
+                "Invalid LZXC signature"
+        end
+
+        version = data[8, 4].unpack1("V")
+        reset_interval = data[12, 4].unpack1("V")
+        window_size = data[16, 4].unpack1("V")
+
+        # Adjust for version 2
+        if version == 2
+          reset_interval *= LZX_FRAME_SIZE
+          window_size *= LZX_FRAME_SIZE
+        elsif version != 1
+          raise Errors::FormatError, "Unknown ControlData version: #{version}"
+        end
+
+        [window_size, reset_interval]
+      end
+
+      # Read reset table entry
+      def read_reset_table(sec, entry, reset_interval)
+        rtable = sec.rtable || find_system_file(Parser::RTABLE_NAME)
+
+        if rtable
+          # Read from reset table
+          read_reset_table_entry(rtable, entry, reset_interval)
+        else
+          # Fall back to SpanInfo
+          spaninfo = sec.spaninfo || find_system_file(Parser::SPANINFO_NAME)
+          unless spaninfo
+            raise Errors::FormatError,
+                  "Neither ResetTable nor SpanInfo found"
+          end
+
+          length = read_spaninfo(spaninfo)
+          [length, 0]
+        end
+      end
+
+      # Read an entry from the reset table
+      def read_reset_table_entry(rtable, entry, reset_interval)
+        data = read_system_file(rtable)
+        raise Errors::FormatError, "ResetTable too short" if data.length < 40
+
+        # Check frame length
+        frame_len = data[32, 8].unpack1("Q<")
+        unless frame_len == LZX_FRAME_SIZE
+          raise Errors::FormatError,
+                "Invalid frame length"
+        end
+
+        # Get uncompressed length
+        uncomp_len = data[16, 8].unpack1("Q<")
+
+        # Get entry info
+        num_entries = data[4, 4].unpack1("V")
+        entry_size = data[8, 4].unpack1("V")
+        table_offset = data[12, 4].unpack1("V")
+
+        if entry < num_entries && table_offset + (entry * entry_size) + entry_size <= data.length
+          pos = table_offset + (entry * entry_size)
+          offset = case entry_size
+                   when 4 then data[pos, 4].unpack1("V")
+                   when 8 then data[pos, 8].unpack1("Q<")
+                   else
+                     raise Errors::FormatError,
+                           "Invalid entry size: #{entry_size}"
+                   end
+
+          # Pad length to next reset interval
+          length = uncomp_len + reset_interval - 1
+          length &= -reset_interval
+
+          [length, offset]
+        else
+          # Invalid entry, fall back
+          [uncomp_len, 0]
+        end
+      end
+
+      # Read SpanInfo to get uncompressed length
+      def read_spaninfo(spaninfo)
+        data = read_system_file(spaninfo)
+        raise Errors::FormatError, "SpanInfo wrong size" unless data.length == 8
+
+        length = data.unpack1("Q<")
+        unless length.positive?
+          raise Errors::FormatError,
+                "Invalid SpanInfo length"
+        end
+
+        length
+      end
+
+      # Find a system file by name
+      def find_system_file(name)
+        file = @chm.sysfiles
+        while file
+          return file if file.filename == name
+
+          file = file.next_file
+        end
+        nil
+      end
+
+      # Read a system file's contents
+      def read_system_file(file)
+        unless file.section.id.zero?
+          raise Errors::FormatError,
+                "System file must be in section 0"
+        end
+
+        offset = @chm.sec0.offset + file.offset
+        @input_handle.seek(offset, Constants::SEEK_START)
+        @input_handle.read(file.length)
+      end
+
+      # Fast search using PMGI index
+      def fast_search_pmgi(filename)
+        # TODO: Implement PMGI-based binary search
+        # For now, fall back to PMGL linear search
+        fast_search_pmgl(filename)
+      end
+
+      # Fast search using PMGL chunks
+      def fast_search_pmgl(filename)
+        original_pos = @input_handle.tell
+
+        (@chm.first_pmgl..@chm.last_pmgl).each do |chunk_num|
+          offset = @chm.dir_offset + (chunk_num * @chm.chunk_size)
+          @input_handle.seek(offset, Constants::SEEK_START)
+          chunk = @input_handle.read(@chm.chunk_size)
+
+          next unless chunk && chunk.length == @chm.chunk_size
+          next unless chunk[0, 4] == "PMGL"
+
+          file = search_chunk(chunk, filename)
+          if file
+            @input_handle.seek(original_pos, Constants::SEEK_START)
+            return file
+          end
+        end
+
+        @input_handle.seek(original_pos, Constants::SEEK_START)
+        nil
+      end
+
+      # Search a chunk for a filename
+      def search_chunk(chunk, filename)
+        num_entries = chunk[-2, 2].unpack1("v")
+        pos = 20
+        chunk_end = chunk.length - 2
+
+        num_entries.times do
+          break if pos >= chunk_end
+
+          begin
+            name_len, pos = Binary::ENCINTReader.read_from_string(chunk, pos)
+            break if pos + name_len > chunk_end
+
+            name = chunk[pos, name_len].force_encoding("UTF-8")
+            pos += name_len
+
+            section, pos = Binary::ENCINTReader.read_from_string(chunk, pos)
+            offset, pos = Binary::ENCINTReader.read_from_string(chunk, pos)
+            length, pos = Binary::ENCINTReader.read_from_string(chunk, pos)
+
+            if name == filename
+              file = Models::CHMFile.new
+              file.filename = name
+              file.section = (section.zero? ? @chm.sec0 : @chm.sec1)
+              file.offset = offset
+              file.length = length
+              return file
+            end
+          rescue Errors::FormatError
+            break
+          end
+        end
+
+        nil
+      end
+
+      # Clean up LZX state
+      def cleanup_lzx
+        @lzx_state = nil
+        @lzx_offset = 0
+        @lzx_length = 0
+      end
+    end
+  end
+end

data/lib/cabriolet/chm/parser.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require_relative "../binary/chm_structures"
+require_relative "../models/chm_header"
+require_relative "../models/chm_file"
+require_relative "../errors"
+
+module Cabriolet
+  module CHM
+    # Parser for CHM (Compiled HTML Help) files
+    class Parser
+      # Expected GUID values in CHM headers
+      GUID1 = [0x10, 0xFD, 0x01, 0x7C, 0xAA, 0x7B, 0xD0, 0x11,
+               0x9E, 0x0C, 0x00, 0xA0, 0xC9, 0x22, 0xE6, 0xEC].pack("C*")
+      GUID2 = [0x11, 0xFD, 0x01, 0x7C, 0xAA, 0x7B, 0xD0, 0x11,
+               0x9E, 0x0C, 0x00, 0xA0, 0xC9, 0x22, 0xE6, 0xEC].pack("C*")
+
+      # System file names
+      CONTENT_NAME = "::DataSpace/Storage/MSCompressed/Content"
+      CONTROL_NAME = "::DataSpace/Storage/MSCompressed/ControlData"
+      SPANINFO_NAME = "::DataSpace/Storage/MSCompressed/SpanInfo"
+      RTABLE_NAME = "::DataSpace/Storage/MSCompressed/Transform/" \
+                    "{7FC28940-9D31-11D0-9B27-00A0C91E9C7C}/InstanceData/ResetTable"
+
+      attr_reader :io, :chm
+
+      def initialize(io)
+        @io = io
+        @chm = Models::CHMHeader.new
+      end
+
+      # Parse the CHM file
+      # @param entire [Boolean] If true, parse all file entries. If false, only headers.
+      # @return [Models::CHMHeader]
+      def parse(entire: true)
+        read_itsf_header
+        read_header_sections
+        read_directory_header
+
+        read_file_entries if entire
+
+        @chm
+      end
+
+      private
+
+      # Read the ITSF header (main file header)
+      def read_itsf_header
+        @io.seek(0, Constants::SEEK_START)
+        header = Binary::CHMITSFHeader.read(@io)
+
+        # Check signature
+        unless header.signature == "ITSF"
+          raise SignatureError,
+                "Invalid ITSF signature"
+        end
+
+        # Check GUIDs
+        unless header.guid1 == GUID1 && header.guid2 == GUID2
+          raise SignatureError,
+                "Invalid CHM GUIDs"
+        end
+
+        @chm.version = header.version
+        @chm.timestamp = header.timestamp
+        @chm.language = header.language_id
+      end
+
+      # Read header sections table and header section 0
+      def read_header_sections
+        section_table = Binary::CHMHeaderSectionTable.read(@io)
+
+        offset_hs0 = section_table.offset_hs0
+        @chm.dir_offset = section_table.offset_hs1
+        @chm.sec0.offset = section_table.offset_cs0
+
+        # Seek to header section 0
+        @io.seek(offset_hs0, Constants::SEEK_START)
+        hs0 = Binary::CHMHeaderSection0.read(@io)
+        @chm.length = hs0.file_len
+      end
+
+      # Read header section 1 (directory header)
+      def read_directory_header
+        @io.seek(@chm.dir_offset, Constants::SEEK_START)
+        hs1 = Binary::CHMHeaderSection1.read(@io)
+
+        # Check signature
+        unless hs1.signature == "ITSP"
+          raise SignatureError,
+                "Invalid ITSP signature"
+        end
+
+        @chm.dir_offset = @io.tell
+        @chm.chunk_size = hs1.chunk_size
+        @chm.density = hs1.density
+        @chm.depth = hs1.depth
+        @chm.index_root = hs1.index_root
+        @chm.num_chunks = hs1.num_chunks
+        @chm.first_pmgl = hs1.first_pmgl
+        @chm.last_pmgl = hs1.last_pmgl
+
+        # For CHM versions < 3, calculate section 0 offset
+        @chm.sec0.offset = @chm.dir_offset + (@chm.chunk_size * @chm.num_chunks) if @chm.version < 3
+
+        validate_chunk_parameters
+      end
+
+      # Validate chunk parameters
+      def validate_chunk_parameters
+        # Check if content offset is valid
+        if @chm.sec0.offset > @chm.length
+          raise FormatError,
+                "Content section offset beyond file length"
+        end
+
+        # Chunk size must be large enough
+        raise FormatError, "Chunk size too small" if @chm.chunk_size < 20
+
+        # Must have chunks
+        raise FormatError, "No chunks in CHM file" if @chm.num_chunks.zero?
+
+        # Sanity limits
+        if @chm.num_chunks > 100_000
+          raise FormatError,
+                "Too many chunks (> 100,000)"
+        end
+
+        if @chm.chunk_size > 8192
+          raise FormatError,
+                "Chunk size too large (> 8192)"
+        end
+
+        # Validate chunk indices
+        if @chm.first_pmgl > @chm.last_pmgl
+          raise FormatError,
+                "First PMGL > Last PMGL"
+        end
+
+        return unless @chm.index_root != 0xFFFFFFFF && @chm.index_root >= @chm.num_chunks
+
+        raise FormatError, "Index root out of range"
+      end
+
+      # Read all file entries from PMGL chunks
+      def read_file_entries
+        # Seek to first PMGL chunk
+        if @chm.first_pmgl != 0
+          pmgl_offset = @chm.first_pmgl * @chm.chunk_size
+          @io.seek(@chm.dir_offset + pmgl_offset, Constants::SEEK_START)
+        end
+
+        num_chunks = @chm.last_pmgl - @chm.first_pmgl + 1
+        last_file = nil
+
+        num_chunks.times do
+          chunk = @io.read(@chm.chunk_size)
+          next unless chunk && chunk.length == @chm.chunk_size
+
+          # Check if this is a PMGL chunk
+          next unless chunk[0, 4] == "PMGL"
+
+          files = parse_pmgl_chunk(chunk)
+          files.each do |file|
+            if file.system_file?
+              # Add to system files list
+              file.next_file = @chm.sysfiles
+              @chm.sysfiles = file
+              identify_system_file(file)
+            else
+              # Add to regular files list
+              if last_file
+                last_file.next_file = file
+              else
+                @chm.files = file
+              end
+              last_file = file
+            end
+          end
+        end
+      end
+
+      # Parse a PMGL chunk to extract file entries
+      # @param chunk [String] The chunk data
+      # @return [Array<Models::CHMFile>] The files found in this chunk
+      def parse_pmgl_chunk(chunk)
+        files = []
+
+        # Read number of entries (last 2 bytes)
+        num_entries = chunk[-2, 2].unpack1("v")
+
+        # Start reading entries after PMGL header
+        pos = 20 # PMGL header is 20 bytes
+        chunk_end = chunk.length - 2
+
+        num_entries.times do
+          break if pos >= chunk_end
+
+          begin
+            # Read name length
+            name_len, pos = Binary::ENCINTReader.read_from_string(chunk, pos)
+            break if pos + name_len > chunk_end
+
+            # Read name
+            name = chunk[pos, name_len]
+            pos += name_len
+
+            # Read section, offset, length
+            section, pos = Binary::ENCINTReader.read_from_string(chunk, pos)
+            offset, pos = Binary::ENCINTReader.read_from_string(chunk, pos)
+            length, pos = Binary::ENCINTReader.read_from_string(chunk, pos)
+
+            # Skip blank or single-char names
+            next if name_len < 2 || name[0].nil? || name[1].nil?
+
+            # Skip directory entries (end with '/')
+            next if offset.zero? && length.zero? && name[-1] == "/"
+
+            # Validate section number
+            next if section > 1
+
+            # Create file entry
+            file = Models::CHMFile.new
+            file.filename = name.force_encoding("UTF-8")
+            file.section = (section.zero? ? @chm.sec0 : @chm.sec1)
+            file.offset = offset
+            file.length = length
+
+            files << file
+          rescue Cabriolet::FormatError
+            # Skip malformed entries
+            break
+          end
+        end
+
+        files
+      end
+
+      # Identify and link system files
+      def identify_system_file(file)
+        case file.filename
+        when CONTENT_NAME
+          @chm.sec1.content = file
+        when CONTROL_NAME
+          @chm.sec1.control = file
+        when SPANINFO_NAME
+          @chm.sec1.spaninfo = file
+        when RTABLE_NAME
+          @chm.sec1.rtable = file
+        end
+      end
+    end
+  end
+end