fontisan 0.1.0 → 0.2.0

data/lib/fontisan/collection/offset_calculator.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Collection
+    # OffsetCalculator calculates file offsets for TTC/OTC structure
+    #
+    # Single responsibility: Calculate all file offsets for the collection structure
+    # including TTC header, offset table, font directories, and table data.
+    # Handles 4-byte alignment requirements.
+    #
+    # TTC/OTC Structure:
+    # - TTC Header (12 bytes)
+    # - Offset Table (4 bytes per font)
+    # - Font 0 Table Directory
+    # - Font 1 Table Directory
+    # - ...
+    # - Shared Tables
+    # - Unique Tables
+    #
+    # @example Calculate offsets
+    #   calculator = OffsetCalculator.new(sharing_map, fonts)
+    #   offsets = calculator.calculate
+    #   header_offset = offsets[:header_offset]
+    #   font_directory_offsets = offsets[:font_directory_offsets]
+    class OffsetCalculator
+      # Alignment requirement for tables (4 bytes)
+      TABLE_ALIGNMENT = 4
+
+      # TTC header size (12 bytes)
+      TTC_HEADER_SIZE = 12
+
+      # Size of each font offset entry (4 bytes)
+      FONT_OFFSET_SIZE = 4
+
+      # Size of font directory header (12 bytes: sfnt_version, num_tables, searchRange, entrySelector, rangeShift)
+      FONT_DIRECTORY_HEADER_SIZE = 12
+
+      # Size of each table directory entry (16 bytes: tag, checksum, offset, length)
+      TABLE_DIRECTORY_ENTRY_SIZE = 16
+
+      # Initialize calculator
+      #
+      # @param sharing_map [Hash] Sharing map from TableDeduplicator
+      # @param fonts [Array<TrueTypeFont, OpenTypeFont>] Source fonts
+      # @raise [ArgumentError] if parameters are invalid
+      def initialize(sharing_map, fonts)
+        raise ArgumentError, "sharing_map cannot be nil" if sharing_map.nil?
+
+        if fonts.nil? || fonts.empty?
+          raise ArgumentError,
+                "fonts cannot be nil or empty"
+        end
+
+        @sharing_map = sharing_map
+        @fonts = fonts
+        @offsets = {}
+      end
+
+      # Calculate all offsets for the collection
+      #
+      # @return [Hash] Complete offset map with:
+      #   - :header_offset [Integer] - TTC header offset (always 0)
+      #   - :offset_table_offset [Integer] - Offset table offset (always 12)
+      #   - :font_directory_offsets [Array<Integer>] - Offset to each font's directory
+      #   - :table_offsets [Hash] - Map of canonical_id to file offset
+      #   - :font_table_directories [Hash] - Per-font table directory info
+      def calculate
+        @offsets = {
+          header_offset: 0,
+          offset_table_offset: TTC_HEADER_SIZE,
+          font_directory_offsets: [],
+          table_offsets: {},
+          font_table_directories: {},
+        }
+
+        # Calculate offset after TTC header and offset table
+        current_offset = TTC_HEADER_SIZE + (@fonts.size * FONT_OFFSET_SIZE)
+
+        # Calculate offsets for each font's table directory
+        calculate_font_directory_offsets(current_offset)
+
+        # Calculate offsets for table data
+        calculate_table_data_offsets
+
+        @offsets
+      end
+
+      # Get offset for specific font's directory
+      #
+      # @param font_index [Integer] Font index
+      # @return [Integer, nil] Offset or nil if not calculated
+      def font_directory_offset(font_index)
+        calculate unless @offsets.key?(:font_directory_offsets) && @offsets[:font_directory_offsets].any?
+        @offsets[:font_directory_offsets][font_index]
+      end
+
+      # Get offset for specific table
+      #
+      # @param canonical_id [String] Canonical table ID
+      # @return [Integer, nil] Offset or nil if not found
+      def table_offset(canonical_id)
+        calculate unless @offsets.key?(:table_offsets) && @offsets[:table_offsets].any?
+        @offsets[:table_offsets][canonical_id]
+      end
+
+      private
+
+      # Calculate offsets for each font's table directory
+      #
+      # Each font directory contains:
+      # - Font directory header (12 bytes)
+      # - Table directory entries (16 bytes each)
+      #
+      # @param start_offset [Integer] Starting offset
+      # @return [void]
+      def calculate_font_directory_offsets(start_offset)
+        current_offset = start_offset
+
+        @fonts.each_with_index do |font, font_index|
+          # Store this font's directory offset
+          @offsets[:font_directory_offsets] << current_offset
+
+          # Calculate size of this font's directory
+          num_tables = font.table_names.size
+          directory_size = FONT_DIRECTORY_HEADER_SIZE + (num_tables * TABLE_DIRECTORY_ENTRY_SIZE)
+
+          # Store directory info
+          @offsets[:font_table_directories][font_index] = {
+            offset: current_offset,
+            size: directory_size,
+            num_tables: num_tables,
+            table_tags: font.table_names,
+          }
+
+          # Move to next font's directory (with alignment)
+          current_offset = align_offset(current_offset + directory_size)
+        end
+
+        # Store offset where table data begins
+        @table_data_start_offset = current_offset
+      end
+
+      # Calculate offsets for all table data
+      #
+      # Processes tables in two groups:
+      # 1. Shared tables (stored once)
+      # 2. Unique tables (stored per font)
+      #
+      # @return [void]
+      def calculate_table_data_offsets
+        current_offset = @table_data_start_offset
+
+        # Collect all unique canonical tables
+        canonical_tables = {}
+        @sharing_map.each_value do |tables|
+          tables.each do |tag, info|
+            canonical_id = info[:canonical_id]
+            next if canonical_tables[canonical_id] # Already processed
+
+            canonical_tables[canonical_id] = {
+              tag: tag,
+              size: info[:size],
+              shared: info[:shared],
+            }
+          end
+        end
+
+        # First, assign offsets to shared tables
+        # Shared tables are stored once and referenced by multiple fonts
+        canonical_tables.each do |canonical_id, info|
+          next unless info[:shared]
+
+          @offsets[:table_offsets][canonical_id] = current_offset
+          current_offset = align_offset(current_offset + info[:size])
+        end
+
+        # Then, assign offsets to unique tables
+        # Each font gets its own copy of unique tables
+        canonical_tables.each do |canonical_id, info|
+          next if info[:shared]
+
+          @offsets[:table_offsets][canonical_id] = current_offset
+          current_offset = align_offset(current_offset + info[:size])
+        end
+      end
+
+      # Align offset to TABLE_ALIGNMENT boundary
+      #
+      # @param offset [Integer] Unaligned offset
+      # @return [Integer] Aligned offset
+      def align_offset(offset)
+        remainder = offset % TABLE_ALIGNMENT
+        return offset if remainder.zero?
+
+        offset + (TABLE_ALIGNMENT - remainder)
+      end
+
+      # Calculate search range parameters for font directory header
+      #
+      # These values are used in the font directory header for binary search:
+      # - searchRange: (max power of 2 <= numTables) * 16
+      # - entrySelector: log2(max power of 2 <= numTables)
+      # - rangeShift: numTables * 16 - searchRange
+      #
+      # @param num_tables [Integer] Number of tables
+      # @return [Hash] Search parameters
+      def calculate_search_params(num_tables)
+        max_power = 0
+        n = num_tables
+        while n > 1
+          n >>= 1
+          max_power += 1
+        end
+
+        search_range = (1 << max_power) * 16
+        entry_selector = max_power
+        range_shift = (num_tables * 16) - search_range
+
+        {
+          search_range: search_range,
+          entry_selector: entry_selector,
+          range_shift: range_shift,
+        }
+      end
+    end
+  end
+end

data/lib/fontisan/collection/table_analyzer.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require "digest/sha2"
+
+module Fontisan
+  module Collection
+    # TableAnalyzer analyzes tables across multiple fonts to identify sharing opportunities
+    #
+    # Single responsibility: Analyze tables across fonts to identify identical tables
+    # that can be shared in a font collection. Uses SHA256 checksums for reliable
+    # content comparison.
+    #
+    # @example Analyze tables across fonts
+    #   analyzer = TableAnalyzer.new([font1, font2, font3])
+    #   report = analyzer.analyze
+    #   puts "Potential savings: #{report[:space_savings]} bytes"
+    #   puts "Shared tables: #{report[:shared_tables].keys.join(', ')}"
+    class TableAnalyzer
+      # Analysis report structure
+      # @return [Hash] Analysis results
+      attr_reader :report
+
+      # Initialize analyzer with fonts
+      #
+      # @param fonts [Array<TrueTypeFont, OpenTypeFont>] Fonts to analyze
+      # @raise [ArgumentError] if fonts array is empty or contains invalid fonts
+      def initialize(fonts)
+        if fonts.nil? || fonts.empty?
+          raise ArgumentError,
+                "fonts cannot be nil or empty"
+        end
+        raise ArgumentError, "fonts must be an array" unless fonts.is_a?(Array)
+
+        @fonts = fonts
+        @report = nil
+      end
+
+      # Analyze tables across all fonts
+      #
+      # Identifies tables that are identical across fonts based on content checksum.
+      # Returns a comprehensive analysis report with sharing opportunities and
+      # potential space savings.
+      #
+      # @return [Hash] Analysis report with:
+      #   - :total_fonts [Integer] Number of fonts analyzed
+      #   - :table_checksums [Hash<String, Hash>] Map of tag to checksum to font indices
+      #   - :shared_tables [Hash<String, Array>] Map of tag to array of font indices sharing that table
+      #   - :unique_tables [Hash<String, Array>] Map of tag to array of font indices with unique versions
+      #   - :space_savings [Integer] Potential bytes saved by sharing
+      #   - :sharing_percentage [Float] Percentage of tables that can be shared
+      def analyze
+        @report = {
+          total_fonts: @fonts.size,
+          table_checksums: {},
+          shared_tables: {},
+          unique_tables: {},
+          space_savings: 0,
+          sharing_percentage: 0.0,
+        }
+
+        # Collect checksums for all tables across all fonts
+        collect_table_checksums
+
+        # Identify which tables are shared
+        identify_shared_tables
+
+        # Calculate space savings
+        calculate_space_savings
+
+        @report
+      end
+
+      # Get tables that can be shared
+      #
+      # @return [Hash<String, Array<Integer>>] Map of table tag to font indices
+      def shared_tables
+        analyze unless @report
+        @report[:shared_tables]
+      end
+
+      # Get potential space savings in bytes
+      #
+      # @return [Integer] Bytes that can be saved by sharing
+      def space_savings
+        analyze unless @report
+        @report[:space_savings]
+      end
+
+      # Get sharing percentage
+      #
+      # @return [Float] Percentage of tables that can be shared (0.0-100.0)
+      def sharing_percentage
+        analyze unless @report
+        @report[:sharing_percentage]
+      end
+
+      private
+
+      # Collect checksums for all tables in all fonts
+      #
+      # Builds a map of: tag -> checksum -> array of font indices
+      # This allows quick identification of which fonts share identical tables.
+      #
+      # @return [void]
+      def collect_table_checksums
+        @fonts.each_with_index do |font, font_index|
+          font.table_names.each do |tag|
+            # Get raw table data
+            table_data = font.table_data[tag]
+            next unless table_data
+
+            # Calculate checksum
+            checksum = calculate_checksum(table_data)
+
+            # Store in report
+            @report[:table_checksums][tag] ||= {}
+            @report[:table_checksums][tag][checksum] ||= []
+            @report[:table_checksums][tag][checksum] << font_index
+          end
+        end
+      end
+
+      # Identify which tables are shared across fonts
+      #
+      # A table is considered shared if 2 or more fonts have identical content
+      # (same checksum) for that table.
+      #
+      # @return [void]
+      def identify_shared_tables
+        @report[:table_checksums].each do |tag, checksums|
+          checksums.each do |checksum, font_indices|
+            if font_indices.size > 1
+              # This table is shared across multiple fonts
+              @report[:shared_tables][tag] ||= []
+              @report[:shared_tables][tag] << {
+                checksum: checksum,
+                font_indices: font_indices,
+                count: font_indices.size,
+              }
+            else
+              # This table is unique to one font
+              @report[:unique_tables][tag] ||= []
+              @report[:unique_tables][tag] << {
+                checksum: checksum,
+                font_index: font_indices.first,
+              }
+            end
+          end
+        end
+      end
+
+      # Calculate potential space savings from table sharing
+      #
+      # Space is saved when N fonts share a table - we only need to store it once
+      # instead of N times. Savings = (N-1) * table_size
+      #
+      # @return [void]
+      def calculate_space_savings
+        total_savings = 0
+        total_table_instances = 0
+        shared_table_instances = 0
+
+        @report[:shared_tables].each do |tag, sharing_groups|
+          sharing_groups.each do |group|
+            font_indices = group[:font_indices]
+            count = font_indices.size
+
+            # Get table size from first font in group
+            table_data = @fonts[font_indices.first].table_data[tag]
+            table_size = table_data.bytesize
+
+            # Savings = (count - 1) * table_size
+            # We only need to store the table once instead of count times
+            savings = (count - 1) * table_size
+            total_savings += savings
+
+            shared_table_instances += count
+          end
+        end
+
+        # Count total table instances
+        @fonts.each do |font|
+          total_table_instances += font.table_names.size
+        end
+
+        @report[:space_savings] = total_savings
+
+        # Calculate sharing percentage
+        if total_table_instances.positive?
+          @report[:sharing_percentage] =
+            (shared_table_instances.to_f / total_table_instances * 100).round(2)
+        end
+      end
+
+      # Calculate SHA256 checksum for table data
+      #
+      # @param data [String] Binary table data
+      # @return [String] Hexadecimal checksum
+      def calculate_checksum(data)
+        Digest::SHA256.hexdigest(data)
+      end
+    end
+  end
+end

data/lib/fontisan/collection/table_deduplicator.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+require "digest/sha2"
+
+module Fontisan
+  module Collection
+    # TableDeduplicator deduplicates identical tables across fonts
+    #
+    # Single responsibility: Group identical tables and create a canonical mapping
+    # for shared table references. Ensures that each unique table content is stored
+    # only once in the collection.
+    #
+    # @example Deduplicate tables
+    #   deduplicator = TableDeduplicator.new([font1, font2, font3])
+    #   sharing_map = deduplicator.build_sharing_map
+    #   canonical_tables = deduplicator.canonical_tables
+    class TableDeduplicator
+      # Canonical tables (unique table data)
+      # @return [Hash<String, Hash>] Map of table tag to canonical versions
+      attr_reader :canonical_tables
+
+      # Sharing map (font -> table -> canonical reference)
+      # @return [Hash<Integer, Hash<String, Hash>>] Sharing map
+      attr_reader :sharing_map
+
+      # Initialize deduplicator with fonts
+      #
+      # @param fonts [Array<TrueTypeFont, OpenTypeFont>] Fonts to process
+      # @raise [ArgumentError] if fonts array is empty or invalid
+      def initialize(fonts)
+        if fonts.nil? || fonts.empty?
+          raise ArgumentError,
+                "fonts cannot be nil or empty"
+        end
+        raise ArgumentError, "fonts must be an array" unless fonts.is_a?(Array)
+
+        @fonts = fonts
+        @canonical_tables = {}
+        @sharing_map = {}
+        @checksum_to_canonical = {}
+      end
+
+      # Build sharing map for all fonts
+      #
+      # Creates a map structure that indicates which canonical table each font
+      # should reference for each table tag. This enables efficient table sharing
+      # in the final collection.
+      #
+      # @return [Hash<Integer, Hash<String, Hash>>] Sharing map with structure:
+      #   {
+      #     font_index => {
+      #       table_tag => {
+      #         canonical_id: unique_id,
+      #         checksum: sha256_checksum,
+      #         data: table_data,
+      #         shared: true/false,
+      #         shared_with: [font_indices]
+      #       }
+      #     }
+      #   }
+      def build_sharing_map
+        # First pass: collect all unique tables
+        collect_canonical_tables
+
+        # Second pass: build sharing map for each font
+        build_font_sharing_references
+
+        @sharing_map
+      end
+
+      # Get canonical table data for a specific table
+      #
+      # @param tag [String] Table tag
+      # @param canonical_id [String] Canonical table identifier
+      # @return [String, nil] Binary table data
+      def canonical_table_data(tag, canonical_id)
+        @canonical_tables.dig(tag, canonical_id, :data)
+      end
+
+      # Get all canonical tables for a specific tag
+      #
+      # @param tag [String] Table tag
+      # @return [Hash<String, Hash>, nil] Map of canonical_id to table info
+      def canonical_tables_for_tag(tag)
+        @canonical_tables[tag]
+      end
+
+      # Get sharing statistics
+      #
+      # @return [Hash] Statistics about table sharing
+      def statistics
+        total_tables = 0
+        shared_tables = 0
+        unique_tables = 0
+
+        @sharing_map.each_value do |tables|
+          tables.each_value do |info|
+            total_tables += 1
+            if info[:shared]
+              shared_tables += 1
+            else
+              unique_tables += 1
+            end
+          end
+        end
+
+        {
+          total_tables: total_tables,
+          shared_tables: shared_tables,
+          unique_tables: unique_tables,
+          sharing_percentage: total_tables.positive? ? (shared_tables.to_f / total_tables * 100).round(2) : 0.0,
+          canonical_count: @canonical_tables.values.sum(&:size),
+        }
+      end
+
+      private
+
+      # Collect all unique (canonical) tables across all fonts
+      #
+      # Identifies unique table content based on checksum and stores one
+      # canonical version of each unique table.
+      #
+      # @return [void]
+      def collect_canonical_tables
+        @fonts.each_with_index do |font, font_index|
+          font.table_names.each do |tag|
+            table_data = font.table_data[tag]
+            next unless table_data
+
+            # Calculate checksum
+            checksum = calculate_checksum(table_data)
+
+            # Check if we've seen this exact table content before
+            canonical_id = find_or_create_canonical(tag, checksum, table_data,
+                                                    font_index)
+
+            # Track which fonts use this canonical table
+            @canonical_tables[tag][canonical_id][:font_indices] << font_index
+          end
+        end
+
+        # Mark shared tables
+        mark_shared_tables
+      end
+
+      # Find existing canonical table or create new one
+      #
+      # @param tag [String] Table tag
+      # @param checksum [String] Table checksum
+      # @param data [String] Table data
+      # @param font_index [Integer] Font index
+      # @return [String] Canonical table ID
+      def find_or_create_canonical(tag, checksum, data, _font_index)
+        # Initialize tag entry if needed
+        @canonical_tables[tag] ||= {}
+        @checksum_to_canonical[tag] ||= {}
+
+        # Check if we already have this exact table content
+        if @checksum_to_canonical[tag][checksum]
+          # Reuse existing canonical table
+          @checksum_to_canonical[tag][checksum]
+        else
+          # Create new canonical table
+          canonical_id = generate_canonical_id(tag, checksum)
+          @checksum_to_canonical[tag][checksum] = canonical_id
+
+          @canonical_tables[tag][canonical_id] = {
+            checksum: checksum,
+            data: data,
+            size: data.bytesize,
+            font_indices: [],
+            shared: false,
+          }
+
+          canonical_id
+        end
+      end
+
+      # Generate unique canonical ID for a table
+      #
+      # @param tag [String] Table tag
+      # @param checksum [String] Table checksum
+      # @return [String] Canonical ID
+      def generate_canonical_id(tag, checksum)
+        # Use first 12 characters of checksum for brevity
+        "#{tag}_#{checksum[0...12]}"
+      end
+
+      # Mark tables that are shared across multiple fonts
+      #
+      # @return [void]
+      def mark_shared_tables
+        @canonical_tables.each_value do |canonical_versions|
+          canonical_versions.each_value do |info|
+            info[:shared] = info[:font_indices].size > 1
+            info[:shared_with] = info[:font_indices].dup if info[:shared]
+          end
+        end
+      end
+
+      # Build sharing references for each font
+      #
+      # Creates a map for each font indicating which canonical table it should
+      # reference for each tag.
+      #
+      # @return [void]
+      def build_font_sharing_references
+        @fonts.each_with_index do |font, font_index|
+          @sharing_map[font_index] = {}
+
+          font.table_names.each do |tag|
+            table_data = font.table_data[tag]
+            next unless table_data
+
+            checksum = calculate_checksum(table_data)
+            canonical_id = @checksum_to_canonical[tag][checksum]
+
+            # Reference canonical table
+            canonical_info = @canonical_tables[tag][canonical_id]
+            @sharing_map[font_index][tag] = {
+              canonical_id: canonical_id,
+              checksum: checksum,
+              data: canonical_info[:data],
+              size: canonical_info[:size],
+              shared: canonical_info[:shared],
+              shared_with: canonical_info[:shared_with] || [],
+            }
+          end
+        end
+      end
+
+      # Calculate SHA256 checksum for table data
+      #
+      # @param data [String] Binary table data
+      # @return [String] Hexadecimal checksum
+      def calculate_checksum(data)
+        Digest::SHA256.hexdigest(data)
+      end
+    end
+  end
+end