cabriolet 0.1.0

data/exe/cabriolet

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/cabriolet"
+
+Cabriolet::CLI.start(ARGV)

data/lib/cabriolet/auto.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require_relative "format_detector"
+
+module Cabriolet
+  # Auto-detection and extraction module
+  module Auto
+    class << self
+      # Open and parse an archive with automatic format detection
+      #
+      # @param path [String] Path to the archive file
+      # @param options [Hash] Options to pass to the parser
+      # @return [Object] Parsed archive object
+      # @raise [UnsupportedFormatError] if format cannot be detected or is unsupported
+      #
+      # @example
+      #   archive = Cabriolet::Auto.open('unknown.archive')
+      #   archive.files.each { |f| puts f.name }
+      def open(path, **options)
+        format = FormatDetector.detect(path)
+        unless format
+          raise UnsupportedFormatError,
+                "Unable to detect format for: #{path}"
+        end
+
+        parser_class = FormatDetector.format_to_parser(format)
+        unless parser_class
+          raise UnsupportedFormatError,
+                "No parser available for format: #{format}"
+        end
+
+        parser_class.new(**options).parse(path)
+      end
+
+      # Detect format and extract all files automatically
+      #
+      # @param archive_path [String] Path to the archive
+      # @param output_dir [String] Directory to extract to
+      # @param options [Hash] Extraction options
+      # @option options [Boolean] :preserve_paths (true) Preserve directory structure
+      # @option options [Boolean] :overwrite (false) Overwrite existing files
+      # @option options [Boolean] :parallel (false) Use parallel extraction
+      # @option options [Integer] :workers (4) Number of parallel workers
+      # @return [Hash] Extraction statistics
+      #
+      # @example
+      #   Cabriolet::Auto.extract('archive.cab', 'output/')
+      #   Cabriolet::Auto.extract('file.chm', 'docs/', parallel: true, workers: 8)
+      def extract(archive_path, output_dir, **options)
+        archive = open(archive_path)
+
+        extractor = if options[:parallel]
+                      ParallelExtractor.new(archive, output_dir, **options)
+                    else
+                      SimpleExtractor.new(archive, output_dir, **options)
+                    end
+
+        extractor.extract_all
+      end
+
+      # Detect format only without parsing
+      #
+      # @param path [String] Path to the file
+      # @return [Symbol, nil] Detected format symbol or nil
+      #
+      # @example
+      #   format = Cabriolet::Auto.detect_format('file.cab')
+      #   # => :cab
+      def detect_format(path)
+        FormatDetector.detect(path)
+      end
+
+      # Get information about an archive without full extraction
+      #
+      # @param path [String] Path to the archive
+      # @return [Hash] Archive information
+      #
+      # @example
+      #   info = Cabriolet::Auto.info('archive.cab')
+      #   # => { format: :cab, file_count: 145, total_size: 52428800, ... }
+      def info(path)
+        archive = open(path)
+        format = detect_format(path)
+
+        {
+          format: format,
+          path: path,
+          file_count: archive.files.count,
+          total_size: archive.files.sum { |f| f.size || 0 },
+          compressed_size: File.size(path),
+          compression_ratio: calculate_compression_ratio(archive, path),
+          files: archive.files.map { |f| file_info(f) },
+        }
+      end
+
+      private
+
+      def calculate_compression_ratio(archive, path)
+        total_uncompressed = archive.files.sum { |f| f.size || 0 }
+        compressed = File.size(path)
+
+        return 0 if total_uncompressed.zero?
+
+        ((compressed.to_f / total_uncompressed) * 100).round(2)
+      end
+
+      def file_info(file)
+        {
+          name: file.name,
+          size: file.size,
+          compressed_size: file.respond_to?(:compressed_size) ? file.compressed_size : nil,
+          attributes: file.respond_to?(:attributes) ? file.attributes : nil,
+          date: file.respond_to?(:date) ? file.date : nil,
+          time: file.respond_to?(:time) ? file.time : nil,
+        }
+      end
+    end
+
+    # Simple sequential extractor
+    class SimpleExtractor
+      def initialize(archive, output_dir, **options)
+        @archive = archive
+        @output_dir = output_dir
+        @options = options
+        @preserve_paths = options.fetch(:preserve_paths, true)
+        @overwrite = options.fetch(:overwrite, false)
+        @stats = { extracted: 0, skipped: 0, failed: 0, bytes: 0 }
+      end
+
+      def extract_all
+        FileUtils.mkdir_p(@output_dir)
+
+        @archive.files.each do |file|
+          extract_file(file)
+        end
+
+        @stats
+      end
+
+      private
+
+      def extract_file(file)
+        output_path = build_output_path(file.name)
+
+        if File.exist?(output_path) && !@overwrite
+          @stats[:skipped] += 1
+          return
+        end
+
+        FileUtils.mkdir_p(File.dirname(output_path))
+        File.write(output_path, file.data, mode: "wb")
+
+        @stats[:extracted] += 1
+        @stats[:bytes] += file.data.bytesize
+      rescue StandardError => e
+        @stats[:failed] += 1
+        warn "Failed to extract #{file.name}: #{e.message}"
+      end
+
+      def build_output_path(filename)
+        if @preserve_paths
+          # Keep directory structure
+          clean_name = filename.gsub("\\", "/")
+          File.join(@output_dir, clean_name)
+        else
+          # Flatten to output directory
+          base_name = File.basename(filename.gsub("\\", "/"))
+          File.join(@output_dir, base_name)
+        end
+      end
+    end
+  end
+end

data/lib/cabriolet/binary/bitstream.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Cabriolet
+  module Binary
+    # Bitstream provides bit-level I/O operations for reading compressed data
+    class Bitstream
+      attr_reader :io_system, :handle, :buffer_size
+
+      # Initialize a new bitstream
+      #
+      # @param io_system [System::IOSystem] I/O system for reading data
+      # @param handle [System::FileHandle, System::MemoryHandle] Handle to read from
+      # @param buffer_size [Integer] Size of the input buffer
+      def initialize(io_system, handle,
+buffer_size = Cabriolet.default_buffer_size)
+        @io_system = io_system
+        @handle = handle
+        @buffer_size = buffer_size
+        @buffer = ""
+        @buffer_pos = 0
+        @bit_buffer = 0
+        @bits_left = 0
+      end
+
+      # Read specified number of bits from the stream
+      #
+      # @param num_bits [Integer] Number of bits to read (1-32)
+      # @return [Integer] Bits read as an integer
+      # @raise [DecompressionError] if unable to read required bits
+      def read_bits(num_bits)
+        if num_bits < 1 || num_bits > 32
+          raise ArgumentError,
+                "Can only read 1-32 bits at a time"
+        end
+
+        # Ensure we have enough bits in the buffer
+        while @bits_left < num_bits
+          byte = read_byte
+          return 0 if byte.nil? # EOF
+
+          @bit_buffer |= (byte << @bits_left)
+          @bits_left += 8
+        end
+
+        # Extract the requested bits
+        result = @bit_buffer & ((1 << num_bits) - 1)
+        @bit_buffer >>= num_bits
+        @bits_left -= num_bits
+
+        result
+      end
+
+      # Read a single byte from the input
+      #
+      # @return [Integer, nil] Byte value or nil at EOF
+      def read_byte
+        if @buffer_pos >= @buffer.bytesize
+          @buffer = @io_system.read(@handle, @buffer_size)
+          @buffer_pos = 0
+          return nil if @buffer.empty?
+        end
+
+        byte = @buffer.getbyte(@buffer_pos)
+        @buffer_pos += 1
+        byte
+      end
+
+      # Align to the next byte boundary
+      #
+      # @return [void]
+      def byte_align
+        discard_bits = @bits_left % 8
+        @bit_buffer >>= discard_bits
+        @bits_left -= discard_bits
+      end
+
+      # Peek at bits without consuming them
+      #
+      # @param num_bits [Integer] Number of bits to peek at
+      # @return [Integer] Bits as an integer
+      def peek_bits(num_bits)
+        if num_bits < 1 || num_bits > 32
+          raise ArgumentError,
+                "Can only peek 1-32 bits at a time"
+        end
+
+        # Ensure we have enough bits
+        while @bits_left < num_bits
+          byte = read_byte
+          return 0 if byte.nil?
+
+          @bit_buffer |= (byte << @bits_left)
+          @bits_left += 8
+        end
+
+        @bit_buffer & ((1 << num_bits) - 1)
+      end
+
+      # Skip specified number of bits
+      #
+      # @param num_bits [Integer] Number of bits to skip
+      # @return [void]
+      def skip_bits(num_bits)
+        read_bits(num_bits)
+        nil
+      end
+
+      # Read bits in big-endian (MSB first) order
+      #
+      # @param num_bits [Integer] Number of bits to read
+      # @return [Integer] Bits as an integer
+      def read_bits_be(num_bits)
+        result = 0
+        num_bits.times do
+          result = (result << 1) | read_bits(1)
+        end
+        result
+      end
+
+      # Read a 16-bit little-endian value
+      #
+      # @return [Integer] 16-bit value
+      def read_uint16_le
+        read_bits(16)
+      end
+
+      # Read a 32-bit little-endian value
+      #
+      # @return [Integer] 32-bit value
+      def read_uint32_le
+        low = read_bits(16)
+        high = read_bits(16)
+        (high << 16) | low
+      end
+
+      # Reset the bitstream state
+      #
+      # @return [void]
+      def reset
+        @buffer = ""
+        @buffer_pos = 0
+        @bit_buffer = 0
+        @bits_left = 0
+        @io_system.seek(@handle, 0, Constants::SEEK_START)
+      end
+    end
+  end
+end

data/lib/cabriolet/binary/bitstream_writer.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Cabriolet
+  module Binary
+    # BitstreamWriter provides bit-level I/O operations for writing compressed data
+    class BitstreamWriter
+      attr_reader :io_system, :handle, :buffer_size
+
+      # Initialize a new bitstream writer
+      #
+      # @param io_system [System::IOSystem] I/O system for writing data
+      # @param handle [System::FileHandle, System::MemoryHandle] Handle to write to
+      # @param buffer_size [Integer] Size of the output buffer
+      # @param msb_first [Boolean] Whether to write bits MSB-first (for Quantum)
+      def initialize(io_system, handle,
+buffer_size = Cabriolet.default_buffer_size, msb_first: false)
+        @io_system = io_system
+        @handle = handle
+        @buffer_size = buffer_size
+        @msb_first = msb_first
+        @bit_buffer = 0
+        @bits_in_buffer = 0
+      end
+
+      # Write specified number of bits to the stream
+      #
+      # @param value [Integer] Value to write
+      # @param num_bits [Integer] Number of bits to write (1-32)
+      # @return [void]
+      # @raise [ArgumentError] if num_bits is out of range
+      def write_bits(value, num_bits)
+        if num_bits < 1 || num_bits > 32
+          raise ArgumentError,
+                "Can only write 1-32 bits at a time"
+        end
+
+        # Add bits to buffer (LSB first, like DEFLATE)
+        @bit_buffer |= ((value & ((1 << num_bits) - 1)) << @bits_in_buffer)
+        @bits_in_buffer += num_bits
+
+        # Flush complete bytes
+        while @bits_in_buffer >= 8
+          byte = @bit_buffer & 0xFF
+          write_byte(byte)
+          @bit_buffer >>= 8
+          @bits_in_buffer -= 8
+        end
+      end
+
+      # Align to the next byte boundary by padding with zeros
+      #
+      # @return [void]
+      def byte_align
+        return if @bits_in_buffer.zero?
+
+        # Pad with zeros to complete the current byte
+        padding_bits = 8 - (@bits_in_buffer % 8)
+        write_bits(0, padding_bits) if padding_bits < 8
+      end
+
+      # Flush any remaining bits in the buffer
+      #
+      # @return [void]
+      def flush
+        return if @bits_in_buffer.zero?
+
+        # Write any remaining bits (padded with zeros)
+        byte = @bit_buffer & 0xFF
+        write_byte(byte)
+        @bit_buffer = 0
+        @bits_in_buffer = 0
+      end
+
+      # Write a single byte to the output
+      #
+      # @param byte [Integer] Byte value to write
+      # @return [void]
+      def write_byte(byte)
+        data = [byte].pack("C")
+        @io_system.write(@handle, data)
+      end
+
+      # Write a raw byte directly (for signatures, etc.)
+      # This ensures the bit buffer is flushed first
+      #
+      # @param byte [Integer] Byte value to write
+      # @return [void]
+      def write_raw_byte(byte)
+        flush if @bits_in_buffer.positive?
+        write_byte(byte)
+      end
+
+      # Write multiple bytes to the output
+      #
+      # @param bytes [String, Array<Integer>] Bytes to write
+      # @return [void]
+      def write_bytes(bytes)
+        data = bytes.is_a?(String) ? bytes : bytes.pack("C*")
+        @io_system.write(@handle, data)
+      end
+
+      # Write bits in big-endian (MSB first) order
+      #
+      # @param value [Integer] Value to write
+      # @param num_bits [Integer] Number of bits to write
+      # @return [void]
+      def write_bits_be(value, num_bits)
+        num_bits.times do |i|
+          bit = (value >> (num_bits - 1 - i)) & 1
+          write_bits(bit, 1)
+        end
+      end
+
+      # Write a 16-bit little-endian value
+      #
+      # @param value [Integer] 16-bit value
+      # @return [void]
+      def write_uint16_le(value)
+        write_bits(value & 0xFFFF, 16)
+      end
+
+      # Write a 32-bit little-endian value
+      #
+      # @param value [Integer] 32-bit value
+      # @return [void]
+      def write_uint32_le(value)
+        write_bits(value & 0xFFFF, 16)
+        write_bits((value >> 16) & 0xFFFF, 16)
+      end
+
+      # Write bits MSB-first (for Quantum compression)
+      # Accumulates bits and writes 16-bit words MSB-first
+      #
+      # @param value [Integer] Value to write
+      # @param num_bits [Integer] Number of bits to write
+      # @return [void]
+      def write_bits_msb(value, num_bits)
+        if num_bits < 1 || num_bits > 32
+          raise ArgumentError,
+                "Can only write 1-32 bits at a time"
+        end
+
+        # Add bits to buffer (MSB first)
+        @bit_buffer = (@bit_buffer << num_bits) | (value & ((1 << num_bits) - 1))
+        @bits_in_buffer += num_bits
+
+        # Flush complete 16-bit words MSB-first
+        while @bits_in_buffer >= 16
+          @bits_in_buffer -= 16
+          word = (@bit_buffer >> @bits_in_buffer) & 0xFFFF
+          # Write MSB first
+          write_byte((word >> 8) & 0xFF)
+          write_byte(word & 0xFF)
+        end
+      end
+
+      # Flush MSB buffer (write remaining bits padded to 16-bit boundary)
+      #
+      # @return [void]
+      def flush_msb
+        return if @bits_in_buffer.zero?
+
+        # Pad to 16-bit boundary
+        padding = (16 - @bits_in_buffer) % 16
+        @bit_buffer <<= padding if padding.positive?
+        @bits_in_buffer += padding
+
+        # Write final 16-bit word
+        if @bits_in_buffer == 16
+          word = @bit_buffer & 0xFFFF
+          write_byte((word >> 8) & 0xFF)
+          write_byte(word & 0xFF)
+        end
+
+        @bit_buffer = 0
+        @bits_in_buffer = 0
+      end
+    end
+  end
+end

data/lib/cabriolet/binary/chm_structures.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require "bindata"
+
+module Cabriolet
+  module Binary
+    # CHM ITSF Header (main file header)
+    class CHMITSFHeader < BinData::Record
+      endian :little
+
+      string :signature, length: 4 # 'ITSF'
+      uint32 :version
+      uint32 :header_len
+      uint32 :unknown1
+      uint32 :timestamp
+      uint32 :language_id
+      string :guid1, length: 16
+      string :guid2, length: 16
+    end
+
+    # CHM Header Section Table
+    class CHMHeaderSectionTable < BinData::Record
+      endian :little
+
+      uint64 :offset_hs0
+      uint64 :length_hs0
+      uint64 :offset_hs1
+      uint64 :length_hs1
+      uint64 :offset_cs0 # Only in version 3+
+    end
+
+    # CHM Header Section 0
+    class CHMHeaderSection0 < BinData::Record
+      endian :little
+
+      uint32 :unknown1
+      uint32 :unknown2
+      uint64 :file_len
+      uint32 :unknown3
+      uint32 :unknown4
+    end
+
+    # CHM Header Section 1 (Directory header)
+    class CHMHeaderSection1 < BinData::Record
+      endian :little
+
+      string :signature, length: 4 # 'ITSP'
+      uint32 :version
+      uint32 :header_len
+      uint32 :unknown1
+      uint32 :chunk_size
+      uint32 :density
+      uint32 :depth
+      int32  :index_root
+      uint32 :first_pmgl
+      uint32 :last_pmgl
+      uint32 :unknown2
+      uint32 :num_chunks
+      uint32 :language_id
+      string :guid, length: 16
+      uint32 :unknown3
+      uint32 :unknown4
+      uint32 :unknown5
+      uint32 :unknown6
+    end
+
+    # PMGL Chunk Header (directory listing chunk)
+    class PMGLChunkHeader < BinData::Record
+      endian :little
+
+      string :signature, length: 4 # 'PMGL'
+      uint32 :quickref_size
+      uint32 :unknown1
+      int32  :prev_chunk
+      int32  :next_chunk
+    end
+
+    # PMGI Chunk Header (directory index chunk)
+    class PMGIChunkHeader < BinData::Record
+      endian :little
+
+      string :signature, length: 4 # 'PMGI'
+      uint32 :quickref_size
+    end
+
+    # LZX Control Data
+    class LZXControlData < BinData::Record
+      endian :little
+
+      uint32 :len
+      string :signature, length: 4 # 'LZXC'
+      uint32 :version
+      uint32 :reset_interval
+      uint32 :window_size
+      uint32 :cache_size
+      uint32 :unknown1
+    end
+
+    # LZX Reset Table Header
+    class LZXResetTableHeader < BinData::Record
+      endian :little
+
+      uint32 :unknown1
+      uint32 :num_entries
+      uint32 :entry_size
+      uint32 :table_offset
+      uint64 :uncomp_len
+      uint64 :comp_len
+      uint64 :frame_len
+    end
+
+    # Helper class for reading ENCINT (variable-length integers)
+    class ENCINTReader
+      # Read an ENCINT from an IO stream
+      # Returns the integer value
+      def self.read(io)
+        result = 0
+        byte = 0x80
+        bytes_read = 0
+        max_bytes = 9 # 63 bits max
+
+        while byte.anybits?(0x80) && bytes_read < max_bytes
+          byte_data = io.read(1)
+          if byte_data.nil?
+            raise Cabriolet::FormatError,
+                  "Unexpected end of ENCINT"
+          end
+
+          byte = byte_data.unpack1("C")
+          result = (result << 7) | (byte & 0x7F)
+          bytes_read += 1
+        end
+
+        if bytes_read == max_bytes && byte.anybits?(0x80)
+          raise Cabriolet::FormatError,
+                "ENCINT too large"
+        end
+
+        result
+      end
+
+      # Read an ENCINT from a string at a given position
+      # Returns [value, new_position]
+      def self.read_from_string(str, pos)
+        result = 0
+        byte = 0x80
+        bytes_read = 0
+        max_bytes = 9
+
+        while byte.anybits?(0x80) && bytes_read < max_bytes
+          if pos >= str.length
+            raise Cabriolet::FormatError,
+                  "ENCINT beyond string"
+          end
+
+          byte = str.getbyte(pos)
+          pos += 1
+          result = (result << 7) | (byte & 0x7F)
+          bytes_read += 1
+        end
+
+        if bytes_read == max_bytes && byte.anybits?(0x80)
+          raise Cabriolet::FormatError,
+                "ENCINT too large"
+        end
+
+        [result, pos]
+      end
+    end
+
+    # Helper class for writing ENCINT (variable-length integers)
+    class ENCINTWriter
+      # Write an ENCINT to an IO stream
+      # @param io [IO] IO object to write to
+      # @param value [Integer] Value to encode
+      # @return [Integer] Number of bytes written
+      def self.write(io, value)
+        bytes = encode(value)
+        io.write(bytes)
+        bytes.bytesize
+      end
+
+      # Encode an integer as ENCINT bytes
+      # @param value [Integer] Value to encode (must be non-negative)
+      # @return [String] Encoded bytes
+      def self.encode(value)
+        if value.negative?
+          raise ArgumentError,
+                "ENCINT value must be non-negative"
+        end
+
+        # Special case: zero
+        return "\x00".b if value.zero?
+
+        bytes = []
+
+        # Encode 7 bits at a time
+        while value.positive?
+          byte = value & 0x7F
+          value >>= 7
+          bytes.unshift(byte)
+        end
+
+        # Set high bit on all but last byte
+        (0...(bytes.length - 1)).each do |i|
+          bytes[i] |= 0x80
+        end
+
+        bytes.pack("C*")
+      end
+    end
+  end
+end