fontisan 0.2.1 → 0.2.2

data/lib/fontisan/hints/hint_converter.rb

@@ -82,11 +82,11 @@ module Fontisan
         when :postscript
           # Convert font-level TT → PS
           if hint_set.font_program || hint_set.control_value_program ||
-             hint_set.control_values&.any?
+              hint_set.control_values&.any?
             ps_dict = convert_tt_programs_to_ps_dict(
               hint_set.font_program,
               hint_set.control_value_program,
-              hint_set.control_values
+              hint_set.control_values,
             )
             result.private_dict_hints = ps_dict.to_json
           end
@@ -102,7 +102,7 @@ module Fontisan
           # Convert font-level PS → TT
           if hint_set.private_dict_hints && hint_set.private_dict_hints != "{}"
             tt_programs = convert_ps_dict_to_tt_programs(
-              JSON.parse(hint_set.private_dict_hints)
+              JSON.parse(hint_set.private_dict_hints),
             )
             result.font_program = tt_programs[:fpgm]
             result.control_value_program = tt_programs[:prep]
@@ -137,7 +137,7 @@ module Fontisan
         Models::Hint.new(
           type: hint.type,
           data: ps_data,
-          source_format: :postscript
+          source_format: :postscript,
         )
       rescue StandardError => e
         warn "Failed to convert hint to PostScript: #{e.message}"
@@ -158,7 +158,7 @@ module Fontisan
         Models::Hint.new(
           type: hint.type,
           data: { instructions: tt_instructions },
-          source_format: :truetype
+          source_format: :truetype,
         )
       rescue StandardError => e
         warn "Failed to convert hint to TrueType: #{e.message}"
@@ -230,7 +230,8 @@ module Fontisan
       # Convert TrueType font programs to PostScript Private dict
       #
       # Analyzes TrueType fpgm, prep, and cvt to extract semantic intent
-      # and generate corresponding PostScript hint parameters.
+      # and generate corresponding PostScript hint parameters using the
+      # TrueTypeInstructionAnalyzer.
       #
       # @param fpgm [String] Font program bytecode
       # @param prep [String] Control value program bytecode
@@ -239,8 +240,8 @@ module Fontisan
       def convert_tt_programs_to_ps_dict(fpgm, prep, cvt)
         hints = {}
 
-        # Extract stem widths from cvt if present
-        # CVT values typically contain standard widths
+        # Extract stem widths from CVT if present
+        # CVT values typically contain standard widths at the beginning
         if cvt && !cvt.empty?
           # First CVT value often represents standard horizontal stem
           hints[:std_hw] = cvt[0].abs if cvt.length > 0
@@ -248,14 +249,36 @@ module Fontisan
           hints[:std_vw] = cvt[1].abs if cvt.length > 1
         end
 
-        # Analyze control value program for alignment zones
-        # TrueType doesn't have exact Blue zones, so we use defaults
+        # Use the instruction analyzer to extract additional hint parameters
+        analyzer = TrueTypeInstructionAnalyzer.new
+
+        # Analyze prep program if present
+        prep_hints = if prep && !prep.empty?
+                       analyzer.analyze_prep(prep, cvt)
+                     else
+                       {}
+                     end
+
+        # Analyze fpgm program complexity
+        fpgm_hints = if fpgm && !fpgm.empty?
+                       analyzer.analyze_fpgm(fpgm)
+                     else
+                       {}
+                     end
+
+        # Extract blue zones from CVT if present
+        blue_zones = if cvt && !cvt.empty?
+                       analyzer.extract_blue_zones_from_cvt(cvt)
+                     else
+                       {}
+                     end
+
+        # Merge all extracted hints (prep_hints and fpgm_hints override stem widths if present)
+        hints.merge!(prep_hints).merge!(fpgm_hints).merge!(blue_zones)
+
+        # Provide default blue_values if none were detected
         # These are standard values that work for most Latin fonts
-        hints[:blue_values] = [-20, 0, 706, 726]
-
-        # Optional: Add other_blues for descenders if we detect them
-        # This would require analyzing prep program, which is complex
-        # For now, use conservative defaults
+        hints[:blue_values] ||= [-20, 0, 706, 726]
 
         hints
       rescue StandardError => e
@@ -266,44 +289,17 @@ module Fontisan
       # Convert PostScript Private dict to TrueType font programs
       #
       # Generates TrueType control values and programs from PostScript
-      # hint parameters.
+      # hint parameters using the TrueTypeInstructionGenerator.
       #
       # @param ps_dict [Hash] PostScript Private dict parameters
       # @return [Hash] TrueType programs ({ fpgm:, prep:, cvt: })
       def convert_ps_dict_to_tt_programs(ps_dict)
-        # Handle both string and symbol keys from JSON
-        ps_dict = ps_dict.transform_keys(&:to_sym) if ps_dict.keys.first.is_a?(String)
-
-        # Generate control values from PS parameters
-        cvt = []
-
-        # Add standard stem widths as CVT values
-        cvt << ps_dict[:std_hw] if ps_dict[:std_hw]
-        cvt << ps_dict[:std_vw] if ps_dict[:std_vw]
-
-        # Add stem snap values if present
-        if ps_dict[:stem_snap_h]&.is_a?(Array)
-          cvt.concat(ps_dict[:stem_snap_h])
-        end
-        if ps_dict[:stem_snap_v]&.is_a?(Array)
-          cvt.concat(ps_dict[:stem_snap_v])
-        end
-
-        # Remove duplicates and sort
-        cvt = cvt.uniq.sort
-
-        # Generate basic prep program (empty for converted fonts)
-        # A real implementation would generate instructions to set up CVT
-        prep = ""
-
-        # fpgm typically empty for converted fonts
-        # Functions would need to be synthesized from scratch
-        fpgm = ""
-
-        { fpgm: fpgm, prep: prep, cvt: cvt }
+        # Use the instruction generator to create real TrueType programs
+        generator = TrueTypeInstructionGenerator.new
+        generator.generate(ps_dict)
       rescue StandardError => e
         warn "Error converting PS dict to TT programs: #{e.message}"
-        { fpgm: "", prep: "", cvt: [] }
+        { fpgm: "".b, prep: "".b, cvt: [] }
       end
     end
   end

data/lib/fontisan/hints/hint_validator.rb

@@ -0,0 +1,284 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Hints
+    # Validates hint data for correctness and compatibility
+    #
+    # This validator ensures that hints are well-formed and compatible with
+    # their target format. It performs multiple levels of validation:
+    # - TrueType instruction bytecode validation
+    # - PostScript hint parameter validation
+    # - Stack neutrality verification
+    # - Hint-outline compatibility checking
+    #
+    # @example Validate TrueType instructions
+    #   validator = HintValidator.new
+    #   result = validator.validate_truetype_instructions(prep_bytes)
+    #   if result[:valid]
+    #     puts "Valid TrueType instructions"
+    #   else
+    #     puts "Errors: #{result[:errors]}"
+    #   end
+    #
+    # @example Validate PostScript hints
+    #   validator = HintValidator.new
+    #   result = validator.validate_postscript_hints(ps_dict)
+    #   puts result[:warnings] if result[:warnings].any?
+    class HintValidator
+      # Maximum allowed values for PostScript hint parameters
+      MAX_BLUE_VALUES = 14      # 7 pairs
+      MAX_OTHER_BLUES = 10      # 5 pairs
+      MAX_STEM_SNAP = 12        # Maximum stem snap entries
+
+      # Validate TrueType instruction bytecode
+      #
+      # Checks for:
+      # - Valid instruction opcodes
+      # - Correct parameter counts
+      # - Stack neutrality
+      #
+      # @param instructions [String] Binary instruction bytes
+      # @return [Hash] Validation result with :valid, :errors, :warnings keys
+      def validate_truetype_instructions(instructions)
+        return { valid: true, errors: [], warnings: [] } if instructions.nil? || instructions.empty?
+
+        errors = []
+        warnings = []
+
+        begin
+          bytes = instructions.bytes
+          stack_depth = 0
+          index = 0
+
+          while index < bytes.length
+            opcode = bytes[index]
+            index += 1
+
+            case opcode
+            when 0x40 # NPUSHB
+              count = bytes[index]
+              index += 1
+              if index + count > bytes.length
+                errors << "NPUSHB: Not enough bytes (need #{count}, have #{bytes.length - index})"
+                break
+              end
+              stack_depth += count
+              index += count
+
+            when 0x41 # NPUSHW
+              count = bytes[index]
+              index += 1
+              if index + (count * 2) > bytes.length
+                errors << "NPUSHW: Not enough bytes (need #{count * 2}, have #{bytes.length - index})"
+                break
+              end
+              stack_depth += count
+              index += count * 2
+
+            when 0xB0..0xB7 # PUSHB[0-7]
+              count = opcode - 0xB0 + 1
+              if index + count > bytes.length
+                errors << "PUSHB[#{count - 1}]: Not enough bytes"
+                break
+              end
+              stack_depth += count
+              index += count
+
+            when 0xB8..0xBF # PUSHW[0-7]
+              count = opcode - 0xB8 + 1
+              if index + (count * 2) > bytes.length
+                errors << "PUSHW[#{count - 1}]: Not enough bytes"
+                break
+              end
+              stack_depth += count
+              index += count * 2
+
+            when 0x1D, 0x1E, 0x1F # SCVTCI, SSWCI, SSW
+              if stack_depth < 1
+                errors << "#{opcode_name(opcode)}: Stack underflow"
+              end
+              stack_depth -= 1
+
+            when 0x44, 0x70 # WCVTP, WCVTF
+              if stack_depth < 2
+                errors << "#{opcode_name(opcode)}: Stack underflow (need 2 values)"
+              end
+              stack_depth -= 2
+
+            else
+              warnings << "Unknown opcode: 0x#{opcode.to_s(16).upcase} at offset #{index - 1}"
+            end
+          end
+
+          # Check stack neutrality
+          if stack_depth != 0
+            warnings << "Stack not neutral: #{stack_depth} value(s) remaining"
+          end
+
+        rescue StandardError => e
+          errors << "Exception during validation: #{e.message}"
+        end
+
+        {
+          valid: errors.empty?,
+          errors: errors,
+          warnings: warnings,
+        }
+      end
+
+      # Validate PostScript hint parameters
+      #
+      # Checks for:
+      # - Valid parameter ranges
+      # - Proper pair counts for blue zones
+      # - Sensible stem width values
+      #
+      # @param hints [Hash] PostScript hint parameters
+      # @return [Hash] Validation result with :valid, :errors, :warnings keys
+      def validate_postscript_hints(hints)
+        errors = []
+        warnings = []
+
+        # Validate blue_values
+        if hints[:blue_values]
+          blue_values = hints[:blue_values]
+          if blue_values.length > MAX_BLUE_VALUES
+            errors << "blue_values exceeds maximum (#{MAX_BLUE_VALUES}): #{blue_values.length}"
+          end
+          if blue_values.length.odd?
+            errors << "blue_values must be pairs (even count): #{blue_values.length}"
+          end
+        end
+
+        # Validate other_blues
+        if hints[:other_blues]
+          other_blues = hints[:other_blues]
+          if other_blues.length > MAX_OTHER_BLUES
+            errors << "other_blues exceeds maximum (#{MAX_OTHER_BLUES}): #{other_blues.length}"
+          end
+          if other_blues.length.odd?
+            errors << "other_blues must be pairs (even count): #{other_blues.length}"
+          end
+        end
+
+        # Validate stem widths
+        [:std_hw, :std_vw].each do |key|
+          if hints[key] && hints[key] <= 0
+            errors << "#{key} must be positive: #{hints[key]}"
+          end
+        end
+
+        # Validate stem snaps
+        [:stem_snap_h, :stem_snap_v].each do |key|
+          if hints[key]
+            if hints[key].length > MAX_STEM_SNAP
+              errors << "#{key} exceeds maximum (#{MAX_STEM_SNAP}): #{hints[key].length}"
+            end
+            if hints[key].any? { |v| v <= 0 }
+              warnings << "#{key} contains non-positive values"
+            end
+          end
+        end
+
+        # Validate blue_scale
+        if hints[:blue_scale]
+          if hints[:blue_scale] <= 0
+            errors << "blue_scale must be positive: #{hints[:blue_scale]}"
+          end
+          if hints[:blue_scale] > 1.0
+            warnings << "blue_scale unusually large (>1.0): #{hints[:blue_scale]}"
+          end
+        end
+
+        # Validate language_group
+        if hints[:language_group]
+          unless [0, 1].include?(hints[:language_group])
+            errors << "language_group must be 0 (Latin) or 1 (CJK): #{hints[:language_group]}"
+          end
+        end
+
+        {
+          valid: errors.empty?,
+          errors: errors,
+          warnings: warnings,
+        }
+      end
+
+      # Validate stack neutrality of instruction sequence
+      #
+      # Ensures the instruction sequence leaves the stack in the same state
+      # as it started (net stack change of zero).
+      #
+      # @param instructions [String] Binary instruction bytes
+      # @return [Hash] Result with :neutral, :stack_depth, :errors keys
+      def validate_stack_neutrality(instructions)
+        return { neutral: true, stack_depth: 0, errors: [] } if instructions.nil? || instructions.empty?
+
+        errors = []
+        stack_depth = 0
+        bytes = instructions.bytes
+        index = 0
+
+        begin
+          while index < bytes.length
+            opcode = bytes[index]
+            index += 1
+
+            case opcode
+            when 0x40 # NPUSHB
+              count = bytes[index]
+              index += 1 + count
+              stack_depth += count
+
+            when 0x41 # NPUSHW
+              count = bytes[index]
+              index += 1 + (count * 2)
+              stack_depth += count
+
+            when 0xB0..0xB7 # PUSHB[0-7]
+              count = opcode - 0xB0 + 1
+              index += count
+              stack_depth += count
+
+            when 0xB8..0xBF # PUSHW[0-7]
+              count = opcode - 0xB8 + 1
+              index += count * 2
+              stack_depth += count
+
+            when 0x1D, 0x1E, 0x1F # SCVTCI, SSWCI, SSW
+              stack_depth -= 1
+
+            when 0x44, 0x70 # WCVTP, WCVTF
+              stack_depth -= 2
+            end
+          end
+        rescue StandardError => e
+          errors << "Error analyzing stack: #{e.message}"
+        end
+
+        {
+          neutral: stack_depth == 0,
+          stack_depth: stack_depth,
+          errors: errors,
+        }
+      end
+
+      private
+
+      # Get human-readable name for opcode
+      #
+      # @param opcode [Integer] Instruction opcode
+      # @return [String] Opcode name
+      def opcode_name(opcode)
+        case opcode
+        when 0x1D then "SCVTCI"
+        when 0x1E then "SSWCI"
+        when 0x1F then "SSW"
+        when 0x44 then "WCVTP"
+        when 0x70 then "WCVTF"
+        else "0x#{opcode.to_s(16).upcase}"
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/hints/postscript_hint_applier.rb

@@ -147,14 +147,12 @@ module Fontisan
           # Prepare per-glyph hint data if present
           per_glyph_hints = if has_per_glyph_hints
                               extract_per_glyph_hints(hint_set)
-                            else
-                              nil
                             end
 
           new_cff_data = Tables::Cff::TableBuilder.rebuild(
             cff_table,
             private_dict_hints: hint_params,
-            per_glyph_hints: per_glyph_hints
+            per_glyph_hints: per_glyph_hints,
           )
 
           tables["CFF "] = new_cff_data

data/lib/fontisan/hints/postscript_hint_extractor.rb

@@ -91,12 +91,12 @@ module Fontisan
           if operator?(byte)
             # Process operator
             operator = if byte == 12
-                        # Two-byte operator
-                        i += 1
-                        (12 << 8) | bytes[i]
-                      else
-                        byte
-                      end
+                         # Two-byte operator
+                         i += 1
+                         (12 << 8) | bytes[i]
+                       else
+                         byte
+                       end
 
             hint = process_operator(operator, stack)
             hints << hint if hint
@@ -165,7 +165,7 @@ module Fontisan
           # 5-byte signed integer
           if index + 4 < bytes.length
             num = (bytes[index + 1] << 24) | (bytes[index + 2] << 16) |
-                  (bytes[index + 3] << 8) | bytes[index + 4]
+              (bytes[index + 3] << 8) | bytes[index + 4]
             num = num - 4294967296 if num > 2147483647
             [num, 5]
           else
@@ -204,7 +204,7 @@ module Fontisan
           Models::Hint.new(
             type: :hint_replacement,
             data: { mask: stack.dup },
-            source_format: :postscript
+            source_format: :postscript,
           )
 
         when CNTRMASK
@@ -212,11 +212,9 @@ module Fontisan
           Models::Hint.new(
             type: :counter,
             data: { zones: stack.dup },
-            source_format: :postscript
+            source_format: :postscript,
           )
 
-        else
-          nil
         end
       end
 
@@ -238,9 +236,9 @@ module Fontisan
           data: {
             position: position,
             width: width,
-            orientation: orientation
+            orientation: orientation,
           },
-          source_format: :postscript
+          source_format: :postscript,
         )
       end
 
@@ -258,7 +256,7 @@ module Fontisan
           pos_idx = i * 2
           stems << {
             position: stack[pos_idx],
-            width: stack[pos_idx + 1]
+            width: stack[pos_idx + 1],
           }
         end
 
@@ -266,9 +264,9 @@ module Fontisan
           type: :stem3,
           data: {
             stems: stems,
-            orientation: orientation
+            orientation: orientation,
           },
-          source_format: :postscript
+          source_format: :postscript,
         )
       end
 
@@ -293,19 +291,58 @@ module Fontisan
 
         # Extract hint-related parameters from Private DICT
         # These are the key hinting parameters in CFF
-        hints[:blue_values] = private_dict.blue_values if private_dict.respond_to?(:blue_values)
-        hints[:other_blues] = private_dict.other_blues if private_dict.respond_to?(:other_blues)
-        hints[:family_blues] = private_dict.family_blues if private_dict.respond_to?(:family_blues)
-        hints[:family_other_blues] = private_dict.family_other_blues if private_dict.respond_to?(:family_other_blues)
-        hints[:blue_scale] = private_dict.blue_scale if private_dict.respond_to?(:blue_scale)
-        hints[:blue_shift] = private_dict.blue_shift if private_dict.respond_to?(:blue_shift)
-        hints[:blue_fuzz] = private_dict.blue_fuzz if private_dict.respond_to?(:blue_fuzz)
-        hints[:std_hw] = private_dict.std_hw if private_dict.respond_to?(:std_hw)
-        hints[:std_vw] = private_dict.std_vw if private_dict.respond_to?(:std_vw)
-        hints[:stem_snap_h] = private_dict.stem_snap_h if private_dict.respond_to?(:stem_snap_h)
-        hints[:stem_snap_v] = private_dict.stem_snap_v if private_dict.respond_to?(:stem_snap_v)
-        hints[:force_bold] = private_dict.force_bold if private_dict.respond_to?(:force_bold)
-        hints[:language_group] = private_dict.language_group if private_dict.respond_to?(:language_group)
+        if private_dict.respond_to?(:blue_values)
+          hints[:blue_values] =
+            private_dict.blue_values
+        end
+        if private_dict.respond_to?(:other_blues)
+          hints[:other_blues] =
+            private_dict.other_blues
+        end
+        if private_dict.respond_to?(:family_blues)
+          hints[:family_blues] =
+            private_dict.family_blues
+        end
+        if private_dict.respond_to?(:family_other_blues)
+          hints[:family_other_blues] =
+            private_dict.family_other_blues
+        end
+        if private_dict.respond_to?(:blue_scale)
+          hints[:blue_scale] =
+            private_dict.blue_scale
+        end
+        if private_dict.respond_to?(:blue_shift)
+          hints[:blue_shift] =
+            private_dict.blue_shift
+        end
+        if private_dict.respond_to?(:blue_fuzz)
+          hints[:blue_fuzz] =
+            private_dict.blue_fuzz
+        end
+        if private_dict.respond_to?(:std_hw)
+          hints[:std_hw] =
+            private_dict.std_hw
+        end
+        if private_dict.respond_to?(:std_vw)
+          hints[:std_vw] =
+            private_dict.std_vw
+        end
+        if private_dict.respond_to?(:stem_snap_h)
+          hints[:stem_snap_h] =
+            private_dict.stem_snap_h
+        end
+        if private_dict.respond_to?(:stem_snap_v)
+          hints[:stem_snap_v] =
+            private_dict.stem_snap_v
+        end
+        if private_dict.respond_to?(:force_bold)
+          hints[:force_bold] =
+            private_dict.force_bold
+        end
+        if private_dict.respond_to?(:language_group)
+          hints[:language_group] =
+            private_dict.language_group
+        end
 
         hints.compact
       rescue StandardError => e
@@ -331,20 +368,18 @@ module Fontisan
         # Iterate through all glyphs
         glyph_count = cff_table.glyph_count(0)
         (0...glyph_count).each do |glyph_id|
-          begin
-            # Get CharString for this glyph
-            charstring = cff_table.charstring_for_glyph(glyph_id, 0)
-            next unless charstring
-
-            # Extract hints from CharString
-            hints = extract(charstring)
-            next if hints.empty?
-
-            # Store glyph hints
-            hint_set.add_glyph_hints(glyph_id, hints)
-          rescue StandardError => e
-            warn "Failed to extract hints for glyph #{glyph_id}: #{e.message}"
-          end
+          # Get CharString for this glyph
+          charstring = cff_table.charstring_for_glyph(glyph_id, 0)
+          next unless charstring
+
+          # Extract hints from CharString
+          hints = extract(charstring)
+          next if hints.empty?
+
+          # Store glyph hints
+          hint_set.add_glyph_hints(glyph_id, hints)
+        rescue StandardError => e
+          warn "Failed to extract hints for glyph #{glyph_id}: #{e.message}"
         end
       rescue StandardError => e
         warn "Failed to extract CharString hints: #{e.message}"