fontisan 0.1.0 → 0.2.0

data/lib/fontisan/optimizers/pattern_analyzer.rb

@@ -0,0 +1,308 @@
+# frozen_string_literal: true
+
+require "stringio"
+require_relative "stack_tracker"
+
+module Fontisan
+  module Optimizers
+    # Analyzes CharString patterns across glyphs to identify repeated sequences
+    # suitable for subroutinization. Implements suffix tree-based pattern matching
+    # for efficient detection of repeated byte sequences.
+    #
+    # Can optionally use stack-aware detection to ensure patterns are stack-neutral,
+    # making them safe for subroutinization without causing stack underflow/overflow.
+    #
+    # @example Basic usage
+    #   analyzer = PatternAnalyzer.new(min_length: 10)
+    #   charstrings = { 0 => "\x01\x02...", 1 => "\x01\x02..." }
+    #   patterns = analyzer.analyze(charstrings)
+    #
+    # @example Stack-aware analysis
+    #   analyzer = PatternAnalyzer.new(min_length: 10, stack_aware: true)
+    #   patterns = analyzer.analyze(charstrings)
+    #
+    # @see docs/SUBROUTINE_ARCHITECTURE.md
+    class PatternAnalyzer
+      # Pattern data structure representing a repeated CharString sequence
+      Pattern = Struct.new(
+        :bytes,        # String: pattern byte sequence
+        :length,       # Integer: byte length
+        :glyphs,       # Array<Integer>: glyph IDs containing pattern
+        :frequency,    # Integer: number of occurrences
+        :savings,      # Integer: total byte savings
+        :positions, # Hash<Integer, Array<Integer>>: glyph_id => [positions]
+        :stack_neutral, # Boolean: whether pattern is stack-neutral
+      ) do
+        # Calculate overhead for calling this pattern as a subroutine
+        # @return [Integer] byte overhead (callsubr + number + return)
+        def call_overhead
+          1 + number_size(frequency) + 1 # callsubr + number + return
+        end
+
+        # Calculate CFF integer encoding size
+        # @param n [Integer] number to encode
+        # @return [Integer] byte size of encoded number
+        def number_size(num)
+          return 1 if num >= -107 && num <= 107
+          return 2 if num >= -1131 && num <= 1131
+          return 3 if num >= -32768 && num <= 32767
+
+          5
+        end
+      end
+
+      # Initialize pattern analyzer
+      # @param min_length [Integer] minimum pattern length in bytes
+      # @param stack_aware [Boolean] whether to enforce stack-neutral patterns
+      def initialize(min_length: 10, stack_aware: false)
+        @min_length = min_length
+        @stack_aware = stack_aware
+        @patterns = {}
+        @stack_trackers = {} # Cache StackTracker instances per glyph
+      end
+
+      # Analyze CharStrings to find repeated patterns
+      #
+      # @param charstrings [Hash<Integer, String>] glyph_id => charstring_bytes
+      # @return [Array<Pattern>] patterns sorted by savings (descending)
+      def analyze(charstrings)
+        raise ArgumentError, "No CharStrings provided" if charstrings.empty?
+
+        # Build stack trackers if stack-aware mode enabled
+        build_stack_trackers(charstrings) if @stack_aware
+
+        # Extract all byte sequences and build pattern candidates
+        extract_patterns(charstrings)
+
+        # Calculate savings for each pattern
+        calculate_savings
+
+        # Filter patterns by minimum length and positive savings
+        filter_patterns
+
+        # Sort by savings (descending) and return
+        @patterns.values.sort_by { |p| -p.savings }
+      end
+
+      private
+
+      # Find operator boundaries in CharString
+      # Returns positions where operators end, which are valid pattern boundaries
+      # @param charstring [String] CharString bytes
+      # @return [Array<Integer>] byte positions of boundaries
+      def find_operator_boundaries(charstring)
+        io = StringIO.new(charstring)
+        boundaries = [0] # Start is always a boundary
+
+        until io.eof?
+          byte = io.getbyte
+
+          if byte <= 31 && byte != 28
+            # Operator byte (28 is a number encoding prefix)
+            if byte == 12
+              # Two-byte operator
+              io.getbyte
+            end
+            # Mark position after operator as boundary
+            boundaries << io.pos
+          else
+            # Number - skip it
+            io.pos -= 1
+            skip_number(io)
+          end
+        end
+
+        boundaries
+      end
+
+      # Skip over a number without decoding
+      # Handles all CFF integer encoding formats
+      # @param io [StringIO] input stream
+      def skip_number(io)
+        byte = io.getbyte
+        return if byte.nil?
+
+        case byte
+        when 28
+          # 3-byte signed integer
+          io.read(2)
+        when 32..246
+          # Single byte integer - already consumed
+        when 247..254
+          # 2-byte integer
+          io.getbyte
+        when 255
+          # 5-byte integer
+          io.read(4)
+        end
+      end
+
+      # Build stack trackers for all CharStrings (if stack-aware)
+      def build_stack_trackers(charstrings)
+        charstrings.each do |glyph_id, charstring|
+          tracker = StackTracker.new(charstring)
+          tracker.track
+          @stack_trackers[glyph_id] = tracker
+        end
+      end
+
+      # Extract patterns from all CharStrings
+      # Uses operator boundaries to ensure patterns are syntactically valid
+      # OPTIMIZED: Samples glyphs and uses discrete lengths to avoid O(n³) complexity
+      def extract_patterns(charstrings)
+        pattern_occurrences = Hash.new { |h, k| h[k] = [] }
+
+        # OPTIMIZATION 1: Sample glyphs if there are too many
+        # For large fonts (1000+ glyphs), sample 30% of glyphs
+        sample_size = if charstrings.length > 1000
+                        (charstrings.length * 0.3).to_i
+                      else
+                        charstrings.length
+                      end
+
+        sampled_glyphs = charstrings.keys.sample(sample_size)
+
+        # NEW: Pre-compute boundaries for sampled glyphs
+        # Check if boundaries are useful (more than just start position)
+        glyph_boundaries = {}
+        use_boundaries = false
+        sampled_glyphs.each do |glyph_id|
+          boundaries = find_operator_boundaries(charstrings[glyph_id])
+          glyph_boundaries[glyph_id] = boundaries
+          # If any glyph has meaningful boundaries (more than just [0]), use boundary mode
+          use_boundaries = true if boundaries.length > 2
+        end
+
+        # OPTIMIZATION 2: Use discrete pattern lengths instead of continuous range
+        # This reduces iterations from 40 to ~5
+        pattern_lengths = [@min_length, @min_length + 5, @min_length + 10,
+                           @min_length + 15, @min_length + 20]
+
+        # For each sampled glyph, extract patterns
+        sampled_glyphs.each do |glyph_id|
+          charstring = charstrings[glyph_id]
+          next if charstring.length < @min_length
+
+          if use_boundaries
+            # Use boundary-based extraction for valid CFF CharStrings
+            boundaries = glyph_boundaries[glyph_id]
+
+            # Try each boundary as a potential start position
+            boundaries.each do |start_pos|
+              # Find boundaries that could be end positions
+              pattern_lengths.each do |target_length|
+                # Find next boundary that gives us approximately target_length
+                end_pos = boundaries.find { |b| b >= start_pos + target_length }
+                next unless end_pos
+
+                actual_length = end_pos - start_pos
+                next if actual_length < @min_length
+                next if actual_length > @min_length + 25 # Max pattern size
+
+                # Check if pattern is stack-neutral (if stack-aware mode)
+                if @stack_aware
+                  tracker = @stack_trackers[glyph_id]
+                  next unless tracker
+                  next unless tracker.stack_neutral?(start_pos, end_pos)
+                end
+
+                pattern_bytes = charstring[start_pos, actual_length]
+
+                # Record occurrence: pattern => [[glyph_id, position], ...]
+                pattern_occurrences[pattern_bytes] << [glyph_id, start_pos]
+              end
+            end
+          else
+            # Fall back to sliding window for non-CFF data (e.g., test data)
+            pattern_lengths.each do |length|
+              break if length > charstring.length
+
+              (0..charstring.length - length).each do |start_pos|
+                # Check if pattern is stack-neutral (if stack-aware mode)
+                if @stack_aware
+                  tracker = @stack_trackers[glyph_id]
+                  next unless tracker
+                  next unless tracker.stack_neutral?(start_pos, start_pos + length)
+                end
+
+                pattern_bytes = charstring[start_pos, length]
+
+                # Record occurrence: pattern => [[glyph_id, position], ...]
+                pattern_occurrences[pattern_bytes] << [glyph_id, start_pos]
+              end
+            end
+          end
+        end
+
+        # Convert occurrences to Pattern objects
+        pattern_occurrences.each do |bytes, occurrences|
+          # Only keep patterns that appear in at least 2 glyphs or 2+ times
+          next if occurrences.length < 2
+
+          # Group by glyph_id
+          by_glyph = occurrences.group_by(&:first)
+
+          # Only keep if appears in multiple glyphs
+          next if by_glyph.keys.length < 2
+
+          # Build positions hash
+          positions = {}
+          by_glyph.each do |glyph_id, glyph_occurrences|
+            positions[glyph_id] = glyph_occurrences.map(&:last)
+          end
+
+          @patterns[bytes] = Pattern.new(
+            bytes,
+            bytes.length,
+            by_glyph.keys,
+            occurrences.length,
+            0, # Will be calculated later
+            positions,
+            @stack_aware, # Mark if validated as stack-neutral
+          )
+        end
+      end
+
+      # Calculate byte savings for each pattern
+      def calculate_savings
+        @patterns.each_value do |pattern|
+          # Savings = (pattern_length - overhead) * (frequency - 1)
+          # -1 because we keep one occurrence in a subroutine
+          overhead = pattern.call_overhead
+          savings_per_use = pattern.length - overhead
+
+          # Total savings across all uses (minus the subroutine definition)
+          pattern.savings = if savings_per_use.positive?
+                              savings_per_use * (pattern.frequency - 1)
+                            else
+                              0
+                            end
+        end
+      end
+
+      # Filter patterns by criteria
+      def filter_patterns
+        @patterns.select! do |_bytes, pattern|
+          # Must meet minimum length
+          next false if pattern.length < @min_length
+
+          # Must have positive savings
+          next false if pattern.savings <= 0
+
+          # Must appear in at least 2 glyphs
+          next false if pattern.glyphs.length < 2
+
+          true
+        end
+      end
+
+      # Find maximal patterns (not contained in larger patterns)
+      # TODO: Implement in optimization phase
+      def find_maximal_patterns
+        # For now, keep all patterns
+        # Future: remove patterns that are substrings of larger patterns
+        # with same or higher frequency
+      end
+    end
+  end
+end

data/lib/fontisan/optimizers/stack_tracker.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+module Fontisan
+  module Optimizers
+    # Tracks operand stack depth during CharString execution without full
+    # interpretation. Used to identify stack-neutral patterns suitable for
+    # subroutinization.
+    #
+    # A stack-neutral pattern is one where the stack depth is the same before
+    # and after the pattern executes. This ensures that replacing the pattern
+    # with a subroutine call won't cause stack underflow/overflow.
+    #
+    # @example Basic usage
+    #   tracker = StackTracker.new(charstring_bytes)
+    #   stack_map = tracker.track
+    #   start_depth = stack_map[start_pos]
+    #   end_depth = stack_map[end_pos]
+    #   is_neutral = (start_depth == end_depth)
+    #
+    # @see docs/SUBROUTINE_ARCHITECTURE.md
+    class StackTracker
+      # Type 2 CharString operator stack effects
+      # Maps operator => [operands_consumed, operands_produced]
+      OPERATOR_STACK_EFFECTS = {
+        # Path construction operators
+        hstem: [2, 0],           # y dy hstem
+        vstem: [2, 0],           # x dx vstem
+        vmoveto: [1, 0],         # dy vmoveto
+        rlineto: [-1, 0],        # {dxa dya}+ (variable, pairs)
+        hlineto: [-1, 0],        # dx1 {dya dxb}* (variable, alternating)
+        vlineto: [-1, 0],        # dy1 {dxb dya}* (variable, alternating)
+        rrcurveto: [-1, 0],      # {dxa dya dxb dyb dxc dyc}+ (variable, 6-tuples)
+        callsubr: [1, 0],        # subr# callsubr (note: subr may affect stack)
+        return: [0, 0],          # return
+        endchar: [0, 0],         # endchar
+        hstemhm: [2, 0],         # y dy hstemhm
+        hintmask: [0, 0],        # hintmask
+        cntrmask: [0, 0],        # cntrmask
+        rmoveto: [2, 0],         # dx dy rmoveto
+        hmoveto: [1, 0],         # dx hmoveto
+        vstemhm: [2, 0],         # x dx vstemhm
+        rcurveline: [-1, 0],     # {dxa dya dxb dyb dxc dyc}+ dxd dyd (variable)
+        rlinecurve: [-1, 0],     # {dxa dya}+ dxb dyb dxc dyc dxd dyd (variable)
+        vvcurveto: [-1, 0],      # dx1? {dya dxb dyb dyc}+ (variable)
+        hhcurveto: [-1, 0],      # dy1? {dxa dxb dyb dxc}+ (variable)
+        shortint: [0, 1],        # (16-bit number)
+        callgsubr: [1, 0],       # subr# callgsubr
+        vhcurveto: [-1, 0],      # dy1 dx2 dy2 dx3 {dxa dxb dyb dyc dyd dxe dye dxf}* (variable)
+        hvcurveto: [-1, 0],      # dx1 dx2 dy2 dy3 {dya dxb dyb dxc dxd dxe dye dyf}* (variable)
+
+        # Arithmetic operators (12 prefix)
+        and: [2, 1],             # num1 num2 and
+        or: [2, 1],              # num1 num2 or
+        not: [1, 1],             # num1 not
+        abs: [1, 1],             # num abs
+        add: [2, 1],             # num1 num2 add
+        sub: [2, 1],             # num1 num2 sub
+        div: [2, 1],             # num1 num2 div
+        neg: [1, 1],             # num neg
+        eq: [2, 1],              # num1 num2 eq
+        drop: [1, 0],            # any drop
+        put: [2, 0],             # val i put
+        get: [1, 1],             # i get
+        ifelse: [4, 1],          # v1 v2 s1 s2 ifelse
+        random: [0, 1],          # random
+        mul: [2, 1],             # num1 num2 mul
+        sqrt: [1, 1],            # num sqrt
+        dup: [1, 2],             # any dup
+        exch: [2, 2],            # any1 any2 exch
+        index: [1, 1],           # i index (actually [i+1, i+1])
+        roll: [2, 0],            # N J roll (rotates top N elements)
+
+        # Flex operators (12 prefix)
+        hflex: [7, 0],           # dx1 dx2 dy2 dx3 dx4 dx5 dx6 hflex
+        flex: [13, 0],           # dx1 dy1 dx2 dy2 dx3 dy3 dx4 dy4 dx5 dy5 dx6 dy6 fd flex
+        hflex1: [9, 0],          # dx1 dy1 dx2 dy2 dx3 dx4 dx5 dy5 dx6 hflex1
+        flex1: [11, 0],          # dx1 dy1 dx2 dy2 dx3 dy3 dx4 dy4 dx5 dy5 d6 flex1
+      }.freeze
+
+      # Type 2 CharString operator codes
+      OPERATORS = {
+        1 => :hstem,
+        3 => :vstem,
+        4 => :vmoveto,
+        5 => :rlineto,
+        6 => :hlineto,
+        7 => :vlineto,
+        8 => :rrcurveto,
+        10 => :callsubr,
+        11 => :return,
+        14 => :endchar,
+        18 => :hstemhm,
+        19 => :hintmask,
+        20 => :cntrmask,
+        21 => :rmoveto,
+        22 => :hmoveto,
+        23 => :vstemhm,
+        24 => :rcurveline,
+        25 => :rlinecurve,
+        26 => :vvcurveto,
+        27 => :hhcurveto,
+        28 => :shortint,
+        29 => :callgsubr,
+        30 => :vhcurveto,
+        31 => :hvcurveto,
+        [12, 3] => :and,
+        [12, 4] => :or,
+        [12, 5] => :not,
+        [12, 9] => :abs,
+        [12, 10] => :add,
+        [12, 11] => :sub,
+        [12, 12] => :div,
+        [12, 14] => :neg,
+        [12, 15] => :eq,
+        [12, 18] => :drop,
+        [12, 20] => :put,
+        [12, 21] => :get,
+        [12, 22] => :ifelse,
+        [12, 23] => :random,
+        [12, 24] => :mul,
+        [12, 26] => :sqrt,
+        [12, 27] => :dup,
+        [12, 28] => :exch,
+        [12, 29] => :index,
+        [12, 30] => :roll,
+        [12, 34] => :hflex,
+        [12, 35] => :flex,
+        [12, 36] => :hflex1,
+        [12, 37] => :flex1,
+      }.freeze
+
+      # Initialize stack tracker
+      # @param charstring [String] CharString bytes to track
+      def initialize(charstring)
+        @charstring = charstring
+        @stack_depth_map = {}
+      end
+
+      # Track stack depth at each byte position
+      # @return [Hash<Integer, Integer>] position => stack_depth
+      def track
+        io = StringIO.new(@charstring)
+        depth = 0
+
+        # Record initial depth
+        @stack_depth_map[0] = depth
+
+        while !io.eof?
+          byte = io.getbyte
+
+          if byte <= 31 && byte != 28
+            # Operator
+            operator = read_operator(io, byte)
+            depth = apply_operator_effect(operator, depth)
+          else
+            # Number - pushes one value
+            io.pos -= 1
+            skip_number(io)
+            depth += 1
+          end
+
+          # Record depth after processing this element
+          @stack_depth_map[io.pos] = depth
+        end
+
+        @stack_depth_map
+      end
+
+      # Check if a pattern is stack-neutral
+      # @param start_pos [Integer] pattern start position
+      # @param end_pos [Integer] pattern end position (exclusive)
+      # @return [Boolean] true if stack depth is same at start and end
+      def stack_neutral?(start_pos, end_pos)
+        return false unless @stack_depth_map.key?(start_pos)
+        return false unless @stack_depth_map.key?(end_pos)
+
+        @stack_depth_map[start_pos] == @stack_depth_map[end_pos]
+      end
+
+      # Get stack depth at a position
+      # @param position [Integer] byte position
+      # @return [Integer, nil] stack depth or nil if not tracked
+      def depth_at(position)
+        @stack_depth_map[position]
+      end
+
+      private
+
+      # Read operator from CharString
+      def read_operator(io, first_byte)
+        if first_byte == 12
+          second_byte = io.getbyte
+          return :unknown if second_byte.nil?
+
+          operator_key = [first_byte, second_byte]
+          OPERATORS[operator_key] || :unknown
+        else
+          OPERATORS[first_byte] || :unknown
+        end
+      end
+
+      # Skip over a number without reading its value
+      def skip_number(io)
+        byte = io.getbyte
+        return if byte.nil?
+
+        case byte
+        when 28
+          # 3-byte signed integer
+          io.read(2)
+        when 32..246
+          # Single byte integer
+        when 247..254
+          # 2-byte integer
+          io.getbyte
+        when 255
+          # 5-byte integer
+          io.read(4)
+        end
+      end
+
+      # Apply operator's stack effect
+      def apply_operator_effect(operator, current_depth)
+        effect = OPERATOR_STACK_EFFECTS[operator]
+        return current_depth if effect.nil? # Unknown operator
+
+        consumed, produced = effect
+
+        if consumed == -1
+          # Variable consumption - these operators consume all available operands
+          # For path operators like rlineto, rrcurveto, etc., they consume pairs/tuples
+          # The stack depth after execution is just what they produce (usually 0)
+          new_depth = produced
+        else
+          new_depth = current_depth - consumed + produced
+          # Ensure depth doesn't go negative
+          new_depth = [new_depth, 0].max
+        end
+
+        new_depth
+      end
+    end
+  end
+end

data/lib/fontisan/optimizers/subroutine_builder.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Optimizers
+    # Builds CFF subroutines from analyzed patterns. Converts pattern byte
+    # sequences into valid CFF CharStrings with return operators, calculates
+    # bias values, and generates callsubr operators for pattern replacement.
+    #
+    # @example Basic usage
+    #   patterns = analyzer.analyze(charstrings)
+    #   builder = SubroutineBuilder.new(patterns, type: :local)
+    #   subroutines = builder.build
+    #   bias = builder.bias
+    #   call = builder.create_call(0)  # Call first subroutine
+    #
+    # @see docs/SUBROUTINE_ARCHITECTURE.md
+    class SubroutineBuilder
+      # CFF return operator
+      RETURN_OPERATOR = "\x0b"
+
+      # CFF callsubr operator
+      CALLSUBR_OPERATOR = "\x0a"
+
+      # Initialize subroutine builder
+      # @param patterns [Array<Pattern>] patterns to convert to subroutines
+      # @param type [Symbol] subroutine type (:local or :global)
+      def initialize(patterns, type: :local)
+        @patterns = patterns
+        @type = type
+        @subroutines = []
+      end
+
+      # Build subroutines from patterns
+      # Each subroutine consists of the pattern bytes followed by a return
+      # operator. The order matches the pattern array order.
+      #
+      # @return [Array<String>] subroutine CharStrings
+      def build
+        @subroutines = @patterns.map do |pattern|
+          build_subroutine_charstring(pattern)
+        end
+        @subroutines
+      end
+
+      # Calculate CFF bias for current subroutine count
+      # Bias values defined by CFF specification:
+      # - 107 for count < 1240
+      # - 1131 for count < 33900
+      # - 32768 for count >= 33900
+      #
+      # @return [Integer] bias value
+      def bias
+        calculate_bias(@subroutines.length)
+      end
+
+      # Create callsubr operator for a subroutine
+      # Encodes the biased subroutine ID as a CFF integer followed by the
+      # callsubr operator.
+      #
+      # @param subroutine_id [Integer] zero-based subroutine index
+      # @return [String] encoded callsubr operator
+      def create_call(subroutine_id)
+        biased_id = subroutine_id - bias
+        encode_integer(biased_id) + CALLSUBR_OPERATOR
+      end
+
+      private
+
+      # Build a subroutine CharString from a pattern
+      # @param pattern [Pattern] pattern to convert
+      # @return [String] subroutine CharString (pattern + return)
+      def build_subroutine_charstring(pattern)
+        pattern.bytes + RETURN_OPERATOR
+      end
+
+      # Calculate bias based on subroutine count
+      # @param count [Integer] number of subroutines
+      # @return [Integer] bias value
+      def calculate_bias(count)
+        return 107 if count < 1240
+        return 1131 if count < 33_900
+
+        32_768
+      end
+
+      # Encode an integer using CFF integer encoding
+      # CFF spec defines multiple encoding formats based on value range:
+      # - -107..107: single byte (32 + n)
+      # - 108..1131: two bytes (247 prefix)
+      # - -1131..-108: two bytes (251 prefix)
+      # - -32768..32767: three bytes (29 prefix)
+      # - Otherwise: five bytes (255 prefix)
+      #
+      # @param num [Integer] integer to encode
+      # @return [String] encoded bytes
+      def encode_integer(num)
+        # Range 1: -107 to 107 (single byte)
+        if num >= -107 && num <= 107
+          return [32 + num].pack("c")
+        end
+
+        # Range 2: 108 to 1131 (two bytes)
+        if num >= 108 && num <= 1131
+          b0 = 247 + ((num - 108) >> 8)
+          b1 = (num - 108) & 0xff
+          return [b0, b1].pack("c*")
+        end
+
+        # Range 3: -1131 to -108 (two bytes)
+        if num >= -1131 && num <= -108
+          b0 = 251 - ((num + 108) >> 8)
+          b1 = -(num + 108) & 0xff
+          return [b0, b1].pack("c*")
+        end
+
+        # Range 4: -32768 to 32767 (three bytes)
+        if num >= -32_768 && num <= 32_767
+          b0 = 29
+          b1 = (num >> 8) & 0xff
+          b2 = num & 0xff
+          return [b0, b1, b2].pack("c*")
+        end
+
+        # Range 5: Larger numbers (five bytes)
+        b0 = 255
+        b1 = (num >> 24) & 0xff
+        b2 = (num >> 16) & 0xff
+        b3 = (num >> 8) & 0xff
+        b4 = num & 0xff
+        [b0, b1, b2, b3, b4].pack("c*")
+      end
+    end
+  end
+end