cabriolet 0.1.2 → 0.2.1

data/lib/cabriolet/lit/piece_builder.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative "directory_builder"
+
+module Cabriolet
+  module LIT
+    # Builds piece data for LIT files
+    class PieceBuilder
+      # Build piece 0 data (file size information)
+      #
+      # @param file_data [Array<Hash>] File data array
+      # @return [String] Binary piece 0 data
+      def self.build_piece0(file_data)
+        # Calculate total content size
+        content_size = file_data.sum { |f| f[:uncompressed_size] }
+
+        data = [Binary::LITStructures::Tags::SIZE_PIECE].pack("V")
+        data += [content_size].pack("V")
+        data += [0, 0].pack("VV") # High bits, reserved
+        data
+      end
+
+      # Build piece 1 data (directory IFCM structure)
+      #
+      # @param directory [Hash] Directory structure from DirectoryBuilder
+      # @return [String] Binary piece 1 data
+      def self.build_piece1(directory)
+        builder = DirectoryBuilder.new(chunk_size: directory[:chunk_size])
+
+        # Build IFCM header
+        ifcm = Binary::LITStructures::IFCMHeader.new
+        ifcm.tag = Binary::LITStructures::Tags::IFCM
+        ifcm.version = 1
+        ifcm.chunk_size = directory[:chunk_size]
+        ifcm.param = 0x100000
+        ifcm.reserved1 = 0xFFFFFFFF
+        ifcm.reserved2 = 0xFFFFFFFF
+        ifcm.num_chunks = directory[:num_chunks]
+        ifcm.reserved3 = 0
+
+        data = ifcm.to_binary_s
+
+        # Build AOLL chunk with directory entries
+        directory[:entries].each do |entry|
+          builder.add_entry(
+            name: entry[:name],
+            section: entry[:section],
+            offset: entry[:offset],
+            size: entry[:size],
+          )
+        end
+
+        aoll_chunk = builder.build_aoll_chunk
+        data += aoll_chunk
+
+        # Pad to fill piece (8KB standard)
+        target_size = 8192
+        if data.bytesize < target_size
+          data += "\x00" * (target_size - data.bytesize)
+        end
+
+        data
+      end
+
+      # Build piece 2 data (index information)
+      #
+      # @return [String] Binary piece 2 data
+      def self.build_piece2
+        # Minimal index data for foundation
+        "\x00" * 512
+      end
+    end
+  end
+end

data/lib/cabriolet/lit/structure_builder.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+require_relative "guid_generator"
+require_relative "content_type_detector"
+require_relative "directory_builder"
+
+module Cabriolet
+  module LIT
+    # Builds complete LIT structure from file data
+    class StructureBuilder
+      attr_reader :io_system, :version, :language_id, :creator_id
+
+      # Initialize structure builder
+      #
+      # @param io_system [System::IOSystem] I/O system for file operations
+      # @param version [Integer] LIT format version
+      # @param language_id [Integer] Language ID
+      # @param creator_id [Integer] Creator ID
+      def initialize(io_system:, version: 1, language_id: 0x409, creator_id: 0)
+        @io_system = io_system
+        @version = version
+        @language_id = language_id
+        @creator_id = creator_id
+      end
+
+      # Build complete LIT structure from file data
+      #
+      # @param file_data [Array<Hash>] File data array from prepare_files
+      # @return [Hash] Complete LIT structure
+      def build(file_data)
+        structure = {}
+
+        # Generate GUIDs
+        structure[:header_guid] = GuidGenerator.generate
+        structure[:piece3_guid] = Binary::LITStructures::GUIDs::PIECE3
+        structure[:piece4_guid] = Binary::LITStructures::GUIDs::PIECE4
+
+        # Build directory
+        structure[:directory] = build_directory(file_data)
+
+        # Build sections
+        structure[:sections] = build_sections
+
+        # Build manifest
+        structure[:manifest] = build_manifest(file_data)
+
+        # Build secondary header metadata
+        structure[:secondary_header] = build_secondary_header_metadata
+
+        # Calculate piece offsets and sizes
+        structure[:pieces] = calculate_pieces(structure)
+
+        # Update secondary header with content offset
+        update_secondary_header_content_offset(structure)
+
+        # Store metadata
+        structure[:version] = @version
+        structure[:file_data] = file_data
+
+        structure
+      end
+
+      private
+
+      # Build directory structure from file data
+      #
+      # @param file_data [Array<Hash>] File data array
+      # @return [Hash] Directory structure
+      def build_directory(file_data)
+        builder = DirectoryBuilder.new
+
+        # Add entries for all files
+        section = 0
+        offset = 0
+
+        file_data.each do |file_info|
+          builder.add_entry(
+            name: file_info[:lit_path],
+            section: section,
+            offset: offset,
+            size: file_info[:uncompressed_size],
+          )
+          offset += file_info[:uncompressed_size]
+        end
+
+        # Calculate NameList size
+        namelist_size = calculate_namelist_size
+
+        # Calculate manifest size
+        manifest_size = calculate_manifest_size(file_data)
+
+        # Add special entries for LIT structure
+        builder.add_entry(
+          name: Binary::LITStructures::Paths::NAMELIST,
+          section: 0,
+          offset: offset,
+          size: namelist_size,
+        )
+        offset += namelist_size
+
+        builder.add_entry(
+          name: Binary::LITStructures::Paths::MANIFEST,
+          section: 0,
+          offset: offset,
+          size: manifest_size,
+        )
+
+        builder.build
+      end
+
+      # Build sections array
+      #
+      # @return [Array<Hash>] Sections array
+      def build_sections
+        # For simple implementation: single uncompressed section
+        [
+          {
+            name: "Uncompressed",
+            transforms: [],
+            compressed: false,
+            encrypted: false,
+          },
+        ]
+      end
+
+      # Build manifest from file data
+      #
+      # @param file_data [Array<Hash>] File data array
+      # @return [Hash] Manifest structure
+      def build_manifest(file_data)
+        mappings = []
+
+        file_data.each_with_index do |file_info, index|
+          mappings << {
+            offset: index,
+            internal_name: file_info[:lit_path],
+            original_name: file_info[:lit_path],
+            content_type: ContentTypeDetector.content_type(file_info[:lit_path]),
+            group: ContentTypeDetector.file_group(file_info[:lit_path]),
+          }
+        end
+
+        { mappings: mappings }
+      end
+
+      # Build secondary header metadata
+      #
+      # @return [Hash] Secondary header metadata
+      def build_secondary_header_metadata
+        # Calculate actual secondary header length
+        temp_header = Binary::LITStructures::SecondaryHeader.new
+        sec_hdr_length = temp_header.to_binary_s.bytesize
+
+        {
+          length: sec_hdr_length,
+          entry_chunklen: 0x2000, # 8KB chunks for entry directory
+          count_chunklen: 0x200,      # 512B chunks for count directory
+          entry_unknown: 0x100000,
+          count_unknown: 0x20000,
+          entry_depth: 1,             # No AOLI index layer
+          entry_entries: 0,           # Will be set when directory built
+          count_entries: 0,           # Will be set when directory built
+          content_offset: 0,          # Will be calculated after pieces
+          timestamp: Time.now.to_i,
+          language_id: @language_id,
+          creator_id: @creator_id,
+        }
+      end
+
+      # Calculate piece offsets and sizes
+      #
+      # @param structure [Hash] Partial structure (needs secondary_header)
+      # @return [Array<Hash>] Pieces array
+      def calculate_pieces(structure)
+        pieces = []
+
+        # Calculate starting offset (after headers and pieces)
+        sec_hdr_length = structure[:secondary_header][:length]
+        current_offset = 40 + 80 + sec_hdr_length
+
+        # Piece 0: File size information (16 bytes)
+        pieces << { offset: current_offset, size: 16 }
+        current_offset += 16
+
+        # Piece 1: Directory (IFCM structure)
+        # Build DirectoryBuilder to calculate size
+        dir_builder = DirectoryBuilder.new(chunk_size: structure[:directory][:chunk_size])
+        structure[:directory][:entries].each do |entry|
+          dir_builder.add_entry(
+            name: entry[:name],
+            section: entry[:section],
+            offset: entry[:offset],
+            size: entry[:size],
+          )
+        end
+        piece1_size = dir_builder.calculate_size
+        pieces << { offset: current_offset, size: piece1_size }
+        current_offset += piece1_size
+
+        # Piece 2: Index information (typically empty or minimal)
+        piece2_size = 512
+        pieces << { offset: current_offset, size: piece2_size }
+        current_offset += piece2_size
+
+        # Piece 3: Standard GUID (16 bytes)
+        pieces << { offset: current_offset, size: 16 }
+        current_offset += 16
+
+        # Piece 4: Standard GUID (16 bytes)
+        pieces << { offset: current_offset, size: 16 }
+
+        pieces
+      end
+
+      # Update secondary header with final content offset
+      #
+      # @param structure [Hash] Structure to update
+      def update_secondary_header_content_offset(structure)
+        pieces = structure[:pieces]
+        last_piece = pieces.last
+        content_offset = last_piece[:offset] + last_piece[:size]
+
+        structure[:secondary_header][:content_offset] = content_offset
+      end
+
+      # Calculate NameList size (estimate)
+      #
+      # @return [Integer] Estimated size
+      def calculate_namelist_size
+        # Simple estimate: ~100 bytes for minimal NameList
+        100
+      end
+
+      # Calculate manifest size (estimate)
+      #
+      # @param file_data [Array<Hash>] File data array
+      # @return [Integer] Estimated size
+      def calculate_manifest_size(file_data)
+        # Rough estimate: directory header + entries
+        size = 10 # Directory header
+
+        file_data.each do |file_info|
+          # Per entry: offset (4) + 3 length bytes + names + content type + terminator
+          size += 4 + 3
+          size += (file_info[:lit_path].bytesize * 2) + 20 + 1
+        end
+
+        size
+      end
+    end
+  end
+end

data/lib/cabriolet/models/hlp_file.rb

@@ -2,44 +2,145 @@
 
 module Cabriolet
   module Models
-    # HLP internal file model
+    # QuickHelp topic model
     #
-    # Represents a file within an HLP archive. HLP files contain an internal
-    # file system where each file can be compressed using LZSS MODE_MSHELP.
-    class HLPFile
-      attr_accessor :filename, :offset, :length, :compressed_length,
-                    :compressed, :data
-
-      # Initialize HLP file
-      #
-      # @param filename [String] File name within the HLP archive
-      # @param offset [Integer] Offset in the HLP archive
-      # @param length [Integer] Uncompressed file length
-      # @param compressed_length [Integer] Compressed file length
-      # @param compressed [Boolean] Whether the file is compressed
-      def initialize(filename: nil, offset: 0, length: 0,
-                     compressed_length: 0, compressed: true)
-        @filename = filename
+    # Represents a single topic in a QuickHelp help database.
+    # Each topic contains formatted text lines with styles and hyperlinks.
+    class HLPTopic
+      attr_accessor :index, :offset, :size, :lines, :source_data, :metadata
+
+      # Initialize a QuickHelp topic
+      #
+      # @param index [Integer] Topic index in the database
+      # @param offset [Integer] Offset of topic data in file
+      # @param size [Integer] Size of compressed topic data
+      def initialize(index: 0, offset: 0, size: 0)
+        @index = index
         @offset = offset
-        @length = length
-        @compressed_length = compressed_length
-        @compressed = compressed
-        @data = nil
+        @size = size
+        @lines = []
+        @source_data = nil
+        @metadata = {}
+      end
+
+      # Check if topic has any content
+      #
+      # @return [Boolean] true if topic has lines
+      def empty?
+        @lines.empty?
+      end
+
+      # Get plain text content (without formatting)
+      #
+      # @return [String] plain text of all lines
+      def plain_text
+        @lines.map(&:text).join("\n")
+      end
+
+      # Add a line to the topic
+      #
+      # @param line [HLPLine] line to add
+      # @return [void]
+      def add_line(line)
+        @lines << line
+      end
+    end
+
+    # QuickHelp topic line model
+    #
+    # Represents a single line within a topic, including text, styles, and links.
+    class HLPLine
+      attr_accessor :text, :attributes
+
+      # Initialize a topic line
+      #
+      # @param text [String] plain text content
+      def initialize(text = "")
+        @text = text
+        @attributes = Array.new(text.length) { TextAttribute.new }
+      end
+
+      # Get line length in characters
+      #
+      # @return [Integer] character count
+      def length
+        @text.length
       end
 
-      # Check if file is compressed
+      # Apply style to a range of characters
       #
-      # @return [Boolean] true if file is compressed
-      def compressed?
-        @compressed
+      # @param start_index [Integer] start position (0-based)
+      # @param end_index [Integer] end position (0-based, inclusive)
+      # @param style [Integer] style flags
+      # @return [void]
+      def apply_style(start_index, end_index, style)
+        (start_index..end_index).each do |i|
+          @attributes[i].style = style if i < @attributes.length
+        end
       end
 
-      # Get the size to read from archive
+      # Apply link to a range of characters
       #
-      # @return [Integer] Size to read (compressed or uncompressed)
-      def read_size
-        compressed? ? @compressed_length : @length
+      # @param start_index [Integer] start position (1-based, as per format)
+      # @param end_index [Integer] end position (1-based, inclusive)
+      # @param link [String] link target (context string or topic index)
+      # @return [void]
+      def apply_link(start_index, end_index, link)
+        # Convert from 1-based to 0-based indexing
+        start_idx = start_index - 1
+        end_idx = end_index - 1
+
+        (start_idx..end_idx).each do |i|
+          @attributes[i].link = link if i >= 0 && i < @attributes.length
+        end
+      end
+    end
+
+    # Text attribute model
+    #
+    # Represents style and link information for a single character.
+    class TextAttribute
+      attr_accessor :style, :link
+
+      # Initialize text attribute
+      #
+      # @param style [Integer] style flags (bold, italic, underline)
+      # @param link [String, nil] link target if any
+      def initialize(style = 0, link = nil)
+        @style = style
+        @link = link
+      end
+
+      # Check if character is bold
+      #
+      # @return [Boolean] true if bold
+      def bold?
+        @style.anybits?(Binary::HLPStructures::TextStyle::BOLD)
+      end
+
+      # Check if character is italic
+      #
+      # @return [Boolean] true if italic
+      def italic?
+        @style.anybits?(Binary::HLPStructures::TextStyle::ITALIC)
+      end
+
+      # Check if character is underlined
+      #
+      # @return [Boolean] true if underlined
+      def underline?
+        @style.anybits?(Binary::HLPStructures::TextStyle::UNDERLINE)
+      end
+
+      # Check if character has a link
+      #
+      # @return [Boolean] true if linked
+      def linked?
+        !@link.nil?
       end
     end
+
+    # Backward compatibility alias
+    HLPFile = HLPTopic
   end
 end

data/lib/cabriolet/models/hlp_header.rb

@@ -2,35 +2,123 @@
 
 module Cabriolet
   module Models
-    # HLP file header model
+    # QuickHelp database header model
     #
-    # 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. Testing relies on round-trip
-    # compression/decompression and comparison with libmspack tools if
-    # available.
+    # Represents the metadata of a QuickHelp help database (.HLP file).
+    # HLP files contain topics, context strings, and optional compression
+    # (keyword dictionary and Huffman coding).
     class HLPHeader
-      attr_accessor :magic, :version, :filename, :length, :files
+      attr_accessor :magic, :version, :attributes, :control_character,
+                    :topic_count, :context_count, :display_width, :predefined_ctx_count, :database_name, :topic_index_offset, :context_strings_offset, :context_map_offset, :keywords_offset, :huffman_tree_offset, :topic_text_offset, :database_size, :filename, :keywords, :huffman_tree
 
-      # Initialize HLP header
+      # Topics and context data
+      attr_accessor :topics, :contexts, :context_map
+
+      # Initialize QuickHelp database header
       #
-      # @param magic [String] Magic number (should be specific to HLP)
-      # @param version [Integer] Format version
-      # @param filename [String] Original filename
-      # @param length [Integer] Uncompressed file length
-      def initialize(magic: nil, version: nil, filename: nil, length: 0)
-        @magic = magic
+      # @param magic [String] Magic number (should be 0x4C 0x4E)
+      # @param version [Integer] Format version (should be 2)
+      # @param attributes [Integer] Attribute flags
+      # @param control_character [Integer] Control character (usually ':' or 0xFF)
+      # @param topic_count [Integer] Number of topics
+      # @param context_count [Integer] Number of context strings
+      # @param display_width [Integer] Display width in characters
+      # @param database_name [String] Database name for external links
+      def initialize(
+        magic: nil,
+        version: 2,
+        attributes: 0,
+        control_character: 0x3A,
+        topic_count: 0,
+        context_count: 0,
+        display_width: 80,
+        predefined_ctx_count: 0,
+        database_name: "",
+        topic_index_offset: 0,
+        context_strings_offset: 0,
+        context_map_offset: 0,
+        keywords_offset: 0,
+        huffman_tree_offset: 0,
+        topic_text_offset: 0,
+        database_size: 0,
+        filename: nil
+      )
+        @magic = magic || Binary::HLPStructures::SIGNATURE
         @version = version
+        @attributes = attributes
+        @control_character = control_character
+        @topic_count = topic_count
+        @context_count = context_count
+        @display_width = display_width
+        @predefined_ctx_count = predefined_ctx_count
+        @database_name = database_name
+        @topic_index_offset = topic_index_offset
+        @context_strings_offset = context_strings_offset
+        @context_map_offset = context_map_offset
+        @keywords_offset = keywords_offset
+        @huffman_tree_offset = huffman_tree_offset
+        @topic_text_offset = topic_text_offset
+        @database_size = database_size
         @filename = filename
-        @length = length
-        @files = []
+
+        # Collections
+        @topics = []
+        @contexts = []
+        @context_map = []
+        @keywords = []
+        @huffman_tree = nil
       end
 
       # Check if header is valid
       #
       # @return [Boolean] true if header appears valid
       def valid?
-        !@magic.nil? && !@version.nil?
+        @magic == Binary::HLPStructures::SIGNATURE &&
+          @version == 2 &&
+          @topic_count >= 0 &&
+          @context_count >= 0
+      end
+
+      # Check if case-sensitive context strings
+      #
+      # @return [Boolean] true if case-sensitive
+      def case_sensitive?
+        @attributes.anybits?(Binary::HLPStructures::Attributes::CASE_SENSITIVE)
+      end
+
+      # Check if database is locked (cannot be decoded by HELPMAKE)
+      #
+      # @return [Boolean] true if locked
+      def locked?
+        @attributes.anybits?(Binary::HLPStructures::Attributes::LOCKED)
+      end
+
+      # Check if keyword compression is used
+      #
+      # @return [Boolean] true if keywords present
+      def has_keywords?
+        @keywords_offset.positive? && !@keywords.empty?
+      end
+
+      # Check if Huffman compression is used
+      #
+      # @return [Boolean] true if Huffman tree present
+      def has_huffman?
+        @huffman_tree_offset.positive? && !@huffman_tree.nil?
+      end
+
+      # Get control character as string
+      #
+      # @return [String] control character
+      def control_char
+        @control_character.chr(Encoding::ASCII)
+      end
+
+      # Get database name without null padding
+      #
+      # @return [String] trimmed database name
+      def db_name
+        @database_name.split("\x00").first || ""
       end
     end
   end