fontisan 0.1.0 → 0.2.1

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,317 @@
+# 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
+      # Tables that can be shared in variable font collections if identical
+      VARIATION_SHAREABLE_TABLES = %w[fvar avar STAT HVAR VVAR MVAR].freeze
+
+      # Tables that must remain font-specific in variable fonts
+      VARIATION_FONT_SPECIFIC_TABLES = %w[gvar CFF2].freeze
+
+      # 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
+
+        # Handle variable font table deduplication
+        deduplicate_variation_tables if has_variable_fonts?
+
+        # 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
+
+      # Check if any font is a variable font
+      #
+      # @return [Boolean] true if any font has fvar table
+      def has_variable_fonts?
+        @fonts.any? { |font| font.has_table?("fvar") }
+      end
+
+      # Deduplicate variable font tables
+      #
+      # Handles special logic for variable font tables:
+      # - Share tables that are identical across fonts (fvar, avar, etc.)
+      # - Keep font-specific tables separate (gvar, CFF2)
+      #
+      # @return [void]
+      def deduplicate_variation_tables
+        # Share tables that are identical across fonts
+        VARIATION_SHAREABLE_TABLES.each do |tag|
+          share_if_identical(tag)
+        end
+
+        # Never share font-specific variation tables
+        VARIATION_FONT_SPECIFIC_TABLES.each do |tag|
+          keep_separate(tag)
+        end
+      end
+
+      # Share table if identical across all fonts that have it
+      #
+      # @param tag [String] Table tag
+      # @return [void]
+      def share_if_identical(tag)
+        # Get all instances of this table
+        tables = @fonts.map { |f| f.table_data[tag] }.compact
+        return if tables.empty?
+
+        # Check if all instances are identical
+        nil if tables.uniq.length > 1
+
+        # All instances are identical, mark as shareable
+        # The normal deduplication logic will handle this
+      end
+
+      # Ensure table stays separate for each font
+      #
+      # @param tag [String] Table tag
+      # @return [void]
+      def keep_separate(tag)
+        # Mark each font's instance as non-shareable
+        @fonts.each_with_index do |font, _font_index|
+          next unless font.has_table?(tag)
+
+          # Find this font's canonical table for this tag
+          table_data = font.table_data[tag]
+          checksum = calculate_checksum(table_data)
+
+          # Ensure canonical table exists
+          @canonical_tables[tag] ||= {}
+          canonical_id = @checksum_to_canonical.dig(tag, checksum)
+
+          next unless canonical_id && @canonical_tables[tag][canonical_id]
+
+          # Mark as non-shareable
+          @canonical_tables[tag][canonical_id][:shared] = false
+          @canonical_tables[tag][canonical_id][:font_specific] = true
+        end
+      end
+
+      # 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