fontisan 0.4.34 → 0.4.36

data/lib/fontisan/audit/checks/format_round_trip_check.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+
+module Fontisan
+  module Audit
+    module Checks
+      # Reports fidelity discrepancies when converting between TTF and
+      # OTF outline formats. A high-fidelity conversion preserves:
+      #
+      #   - Glyph count (maxp.numGlyphs)
+      #   - Codepoint coverage (cmap Unicode mappings)
+      #   - Font identity (name table family + PostScript name)
+      #
+      # Any mismatch signals a bug in the outline converter or a data
+      # loss path. This check is the pure-Ruby replacement for `ttx`
+      # diff comparisons.
+      #
+      # Only converts in one direction (TTF→OTF for TrueType sources,
+      # OTF→TTF for CFF sources) — full round-trip would double the
+      # conversion surface without adding signal.
+      #
+      # @see Converters::OutlineConverter
+      class FormatRoundTripCheck < Check
+        # @param font [SfntFont]
+        # @return [Array<Models::ValidationReport::Issue>]
+        def self.call(font)
+          target = round_trip_target(font)
+          return [] unless target
+
+          converted_path = convert_to_temp(font, target)
+          return [] unless converted_path
+
+          converted = FontLoader.load(converted_path)
+          compare_fonts(font, converted, target)
+        rescue StandardError => e
+          [issue(severity: :warning,
+                 message: "Round-trip conversion to #{target.upcase} failed: " \
+                          "#{e.class}: #{e.message}",
+                 location: "round_trip.#{target}")]
+        ensure
+          cleanup_temp(converted_path) if converted_path
+        end
+
+        def self.code
+          :format_round_trip
+        end
+
+        # Decide the conversion target based on the source outline type.
+        # @return [Symbol, nil] :otf, :ttf, or nil if not convertible
+        def self.round_trip_target(font)
+          return :otf if font.has_table?("glyf")
+          return :ttf if font.has_table?("CFF ") || font.has_table?("CFF2")
+
+          nil
+        end
+        private_class_method :round_trip_target
+
+        def self.convert_to_temp(font, target)
+          converter = Converters::FormatConverter.new
+          tables = converter.convert(font, target)
+          return nil unless tables && !tables.empty?
+
+          dir = Dir.mktmpdir("fontisan-roundtrip-")
+          path = File.join(dir, "converted.#{target}")
+          sfnt = target == :otf ? 0x4F54544F : 0x00010000
+          FontWriter.write_to_file(
+            tables.transform_values { |t| t.is_a?(String) ? t : t.to_binary_s },
+            path,
+            sfnt_version: sfnt,
+          )
+          File.exist?(path) ? path : nil
+        rescue StandardError
+          nil
+        end
+        private_class_method :convert_to_temp
+
+        def self.compare_fonts(source, converted, target)
+          issues = []
+          issues.concat(compare_glyph_count(source, converted, target))
+          issues.concat(compare_codepoints(source, converted, target))
+          issues
+        end
+        private_class_method :compare_fonts
+
+        def self.compare_glyph_count(source, converted, target)
+          src_count = glyph_count(source)
+          dst_count = glyph_count(converted)
+          return [] if src_count == dst_count
+
+          [issue(severity: :warning,
+                 message: "Round-trip to #{target.upcase}: glyph count changed " \
+                          "from #{src_count} to #{dst_count}",
+                 location: "round_trip.#{target}.glyph_count")]
+        end
+        private_class_method :compare_glyph_count
+
+        def self.compare_codepoints(source, converted, target)
+          src_cps = codepoint_set(source)
+          dst_cps = codepoint_set(converted)
+          missing = src_cps - dst_cps
+          extra = dst_cps - src_cps
+          issues = []
+          unless missing.empty?
+            issues << issue(severity: :warning,
+                            message: "Round-trip to #{target.upcase}: #{missing.size} " \
+                                     "codepoints lost (first: " \
+                                     "#{missing.first(5).map { |c| format('U+%04X', c) }.join(', ')})",
+                            location: "round_trip.#{target}.codepoints.missing")
+          end
+          unless extra.empty?
+            issues << issue(severity: :info,
+                            message: "Round-trip to #{target.upcase}: #{extra.size} " \
+                                     "codepoints gained (first: " \
+                                     "#{extra.first(5).map { |c| format('U+%04X', c) }.join(', ')})",
+                            location: "round_trip.#{target}.codepoints.extra")
+          end
+          issues
+        end
+        private_class_method :compare_codepoints
+
+        def self.glyph_count(font)
+          return 0 unless font.has_table?("maxp")
+
+          font.table("maxp").num_glyphs.to_i
+        rescue StandardError
+          0
+        end
+        private_class_method :glyph_count
+
+        def self.codepoint_set(font)
+          return Set.new unless font.has_table?("cmap")
+
+          Set.new(font.table("cmap").unicode_mappings&.keys || [])
+        rescue StandardError
+          Set.new
+        end
+        private_class_method :codepoint_set
+
+        def self.cleanup_temp(path)
+          dir = File.dirname(path)
+          FileUtils.rm_rf(dir) if Dir.exist?(dir)
+        rescue StandardError
+          nil
+        end
+        private_class_method :cleanup_temp
+      end
+    end
+  end
+end

data/lib/fontisan/audit/checks/glyph_name_check.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Audit
+    module Checks
+      # Validates glyph names against the OpenType spec rules:
+      #
+      #   - Length ≤ 63 characters
+      #   - Allowed characters: printable ASCII excluding special chars
+      #     (per OT spec: A–Z a–z 0–9, period, hyphen, underscore)
+      #   - Must not start with a digit
+      #   - Must not be a reserved name (.notdef is the only exception at GID 0)
+      #   - Duplicate names across the font (warning)
+      #   - Empty names (warning — some tools tolerate them but spec discourages)
+      #
+      # @see https://learn.microsoft.com/en-us/typography/opentype/spec/post
+      class GlyphNameCheck < Check
+        MAX_NAME_LENGTH = 63
+        # OT spec post table glyph name charset: A–Z a–z 0–9 . - _
+        # (leading dot is allowed for .notdef, .null, .nonmarkingreturn, etc.)
+        ALLOWED_NAME_PATTERN = /\A[A-Za-z0-9._-]+\z/
+
+        # @param font [SfntFont]
+        # @return [Array<Models::ValidationReport::Issue>]
+        def self.call(font)
+          names = extract_glyph_names(font)
+          return [] if names.empty?
+
+          issues = []
+          names.each_with_index do |name, gid|
+            issues.concat(check_name(name, gid))
+          end
+          issues.concat(check_duplicates(names))
+          issues
+        end
+
+        def self.code
+          :glyph_names
+        end
+
+        def self.extract_glyph_names(font)
+          return [] unless font.has_table?("post")
+
+          post = font.table("post")
+          return [] unless post
+
+          post.glyph_names || []
+        end
+        private_class_method :extract_glyph_names
+
+        def self.check_name(name, gid)
+          issues = []
+          if name.nil? || name.empty?
+            issues << issue(severity: :warning,
+                            message: "Glyph at GID #{gid} has an empty name",
+                            location: "glyph.#{gid}.name")
+            return issues
+          end
+
+          if name.length > MAX_NAME_LENGTH
+            issues << issue(severity: :error,
+                            message: "Glyph name '#{name[0, 20]}…' (GID #{gid}) " \
+                                     "exceeds #{MAX_NAME_LENGTH} characters " \
+                                     "(#{name.length})",
+                            location: "glyph.#{gid}.name")
+          end
+
+          unless name.match?(ALLOWED_NAME_PATTERN)
+            issues << issue(severity: :warning,
+                            message: "Glyph name '#{name}' (GID #{gid}) contains " \
+                                     "characters outside the OT spec grammar " \
+                                     "(A–Z a–z 0–9 . - _)",
+                            location: "glyph.#{gid}.name")
+          end
+
+          if name.match?(/\A\d/)
+            issues << issue(severity: :warning,
+                            message: "Glyph name '#{name}' (GID #{gid}) starts " \
+                                     "with a digit — not portable",
+                            location: "glyph.#{gid}.name")
+          end
+          issues
+        end
+        private_class_method :check_name
+
+        def self.check_duplicates(names)
+          seen = {}
+          names.each_with_index do |name, gid|
+            next unless name && !name.empty?
+
+            (seen[name] ||= []) << gid
+          end
+          seen.each_with_object([]) do |(name, gids), issues|
+            next unless gids.size > 1
+
+            issues << issue(severity: :warning,
+                            message: "Glyph name '#{name}' is shared by " \
+                                     "#{gids.size} glyphs (GIDs: #{gids.first(5).join(', ')}" \
+                                     "#{'…' if gids.size > 5})",
+                            location: "glyph_names.#{name}")
+          end
+        end
+        private_class_method :check_duplicates
+      end
+    end
+  end
+end

data/lib/fontisan/audit/checks/hinting_check.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Audit
+    module Checks
+      # Audits font hinting configuration. Hinting quality directly
+      # affects small-size screen rendering (Windows, Android, embedded
+      # systems).
+      #
+      # TrueType (glyf outlines):
+      #   - fpgm (font program) presence recommended for hinted fonts
+      #   - prep (control value program) presence recommended
+      #   - cvt (control value table) presence recommended
+      #   - maxp.maxStackElements and maxp.maxZones must be positive
+      #     if any hinting instructions exist
+      #   - gasp table recommended for controlling grid-fitting per ppem
+      #
+      # CFF (PostScript outlines):
+      #   - Private DICT should have BlueValues or StdHW/StdVW for hinting
+      #   - Subroutine usage (Local/Global subrs) recommended for size
+      #
+      # @see https://learn.microsoft.com/en-us/typography/opentype/spec/ttinst#hinting-instructions
+      class HintingCheck < Check
+        # @param font [SfntFont]
+        # @return [Array<Models::ValidationReport::Issue>]
+        def self.call(font)
+          if font.has_table?("glyf")
+            validate_truetype_hinting(font)
+          elsif font.has_table?("CFF ") || font.has_table?("CFF2")
+            validate_cff_hinting(font)
+          else
+            []
+          end
+        end
+
+        def self.code
+          :hinting
+        end
+
+        # ---------- TrueType hinting ----------
+
+        def self.validate_truetype_hinting(font)
+          issues = []
+          has_fpgm = font.has_table?("fpgm")
+          has_prep = font.has_table?("prep")
+          has_cvt = font.has_table?("cvt")
+          has_glyf_data = table_has_data?(font, "glyf")
+
+          if has_fpgm && has_glyf_data
+            issues.concat(validate_maxp_hint_capacity(font))
+          end
+
+          issues << no_program_warning("prep") if !has_prep && has_fpgm
+          issues << no_program_warning("cvt") if !has_cvt && has_fpgm
+
+          unless font.has_table?("gasp")
+            issues << issue(severity: :info,
+                            message: "TrueType font has no 'gasp' table — " \
+                                     "grid-fitting behavior per ppem is " \
+                                     "implementation-defined",
+                            location: "tables.gasp")
+          end
+
+          issues
+        end
+        private_class_method :validate_truetype_hinting
+
+        def self.validate_maxp_hint_capacity(font)
+          issues = []
+          maxp = font.table("maxp")
+          return issues unless maxp.version_1_0?
+
+          stack = maxp.max_stack_elements.to_i
+          zones = maxp.max_zones.to_i
+          if has_fpgm_instructions?(font) && stack.zero?
+            issues << issue(severity: :warning,
+                            message: "maxp.maxStackElements is 0 but the font " \
+                                     "has hinting instructions — rendering " \
+                                     "may fail",
+                            location: "maxp.max_stack_elements")
+          end
+          unless zones.between?(1, 2)
+            issues << issue(severity: :warning,
+                            message: "maxp.maxZones is #{zones} but must be 1 or 2 " \
+                                     "per the OpenType spec",
+                            location: "maxp.max_zones")
+          end
+          issues
+        end
+        private_class_method :validate_maxp_hint_capacity
+
+        def self.has_fpgm_instructions?(font)
+          table_has_data?(font, "fpgm")
+        end
+        private_class_method :has_fpgm_instructions?
+
+        def self.no_program_warning(table)
+          issue(severity: :info,
+                message: "Font has 'fpgm' but no '#{table}' table — " \
+                         "#{table == 'cvt' ? 'control values' : 'pre-program'} " \
+                         "are recommended for consistent hinting",
+                location: "tables.#{table}")
+        end
+        private_class_method :no_program_warning
+
+        # ---------- CFF hinting ----------
+
+        def self.validate_cff_hinting(font)
+          issues = []
+          tag = font.has_table?("CFF2") ? "CFF2" : "CFF "
+          cff = font.table(tag)
+          return issues unless cff
+
+          priv = begin
+            cff.private_dict(0)
+          rescue StandardError
+            nil
+          end
+          return issues unless priv
+
+          has_blues = priv_values?(priv, :blue_values) || priv_values?(priv, :other_blues)
+          has_stems = priv_value?(priv, :std_hw) || priv_value?(priv, :std_vw)
+
+          if !has_blues && !has_stems
+            issues << issue(severity: :info,
+                            message: "CFF Private DICT has no BlueValues or " \
+                                     "StdHW/StdVW — alignment zones and stem " \
+                                     "widths are the primary hinting mechanism " \
+                                     "for CFF outlines",
+                            location: "cff.private_dict")
+          end
+
+          issues
+        end
+        private_class_method :validate_cff_hinting
+
+        def self.priv_values?(priv, key)
+          val = priv[key] || priv[key.to_s]
+          val.is_a?(Array) ? val.any? : false
+        rescue StandardError
+          false
+        end
+        private_class_method :priv_values?
+
+        def self.priv_value?(priv, key)
+          val = priv[key] || priv[key.to_s]
+          val && !val.zero?
+        rescue StandardError
+          false
+        end
+        private_class_method :priv_value?
+
+        # ---------- helpers ----------
+
+        def self.table_has_data?(font, tag)
+          raw = font.table_data[tag]
+          raw && !raw.empty?
+        end
+        private_class_method :table_has_data?
+      end
+    end
+  end
+end

data/lib/fontisan/audit/checks/opentype_conformance_check.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Audit
+    module Checks
+      # Foundational OpenType spec conformance checks. Covers the
+      # most commonly-violated "MUST" and "SHOULD" rules from the OT
+      # spec that other check domains don't already cover.
+      #
+      # This check is intentionally a growing foundation — new OT spec
+      # rules are added incrementally as real-world fonts surface them.
+      # Full OT conformance is a long-running effort that tracks the
+      # spec's evolution (axis 14 per TODO #03).
+      #
+      # Current checks:
+      #
+      #   - Required tables for each sfnt flavor (TTF vs CFF vs variable)
+      #   - head.indexToLocFormat consistency with loca table size
+      #   - name table must have at least family (1), subfamily (2),
+      #     full (4), PostScript (6) name IDs
+      #   - OS/2 fsSelection must not use reserved bits
+      #   - hhea.numberOfHMetrics must be ≤ maxp.numGlyphs
+      #   - post table version must be valid
+      #   - cmap must have at least one Unicode subtable (already
+      #     covered by CmapCheck — skipped here to avoid duplicate issues)
+      #
+      # @see https://learn.microsoft.com/en-us/typography/opentype/spec/otff
+      class OpenTypeConformanceCheck < Check
+        REQUIRED_NAME_IDS = {
+          1 => "Family",
+          2 => "Subfamily",
+          4 => "Full",
+          6 => "PostScript",
+        }.freeze
+
+        # @param font [SfntFont]
+        # @return [Array<Models::ValidationReport::Issue>]
+        def self.call(font)
+          issues = []
+          issues.concat(validate_required_tables(font))
+          issues.concat(validate_loca_format(font))
+          issues.concat(validate_name_coverage(font))
+          issues.concat(validate_os2_fsselection(font))
+          issues.concat(validate_hhea_metrics(font))
+          issues
+        end
+
+        def self.code
+          :opentype_conformance
+        end
+
+        # ---------- required tables ----------
+
+        def self.validate_required_tables(font)
+          required = required_tables_for_flavor(font)
+          missing = required.reject { |tag| font.has_table?(tag) }
+          missing.map do |tag|
+            issue(severity: :error,
+                  message: "Required table '#{tag}' is missing for this " \
+                           "sfnt flavor",
+                  location: "tables.#{tag}")
+          end
+        end
+        private_class_method :validate_required_tables
+
+        def self.required_tables_for_flavor(font)
+          base = %w[head hhea maxp hmtx name post cmap OS/2]
+          if font.has_table?("glyf")
+            base + %w[glyf loca]
+          elsif font.has_table?("CFF2")
+            base + ["CFF2"]
+          elsif font.has_table?("CFF ")
+            base + ["CFF "]
+          else
+            base
+          end
+        end
+        private_class_method :required_tables_for_flavor
+
+        # ---------- loca format ----------
+
+        def self.validate_loca_format(font)
+          return [] unless font.has_table?("head") && font.has_table?("loca")
+
+          head = font.table("head")
+          loca = font.table("loca")
+          return [] unless head && loca
+
+          format = head.index_to_loc_format
+          maxp = font.table("maxp")
+          num_glyphs = maxp&.num_glyphs.to_i
+          return [] if num_glyphs.zero?
+
+          expected_size = format.zero? ? (num_glyphs + 1) * 2 : (num_glyphs + 1) * 4
+          actual_size = loca.to_binary_s.bytesize
+          return [] if actual_size == expected_size
+
+          [issue(severity: :warning,
+                 message: "loca table size (#{actual_size} bytes) doesn't match " \
+                          "head.indexToLocFormat=#{format} + numGlyphs=#{num_glyphs} " \
+                          "(expected #{expected_size} bytes)",
+                 location: "head.index_to_loc_format")]
+        end
+        private_class_method :validate_loca_format
+
+        # ---------- name table coverage ----------
+
+        def self.validate_name_coverage(font)
+          return [] unless font.has_table?("name")
+
+          name = font.table("name")
+          REQUIRED_NAME_IDS.each_with_object([]) do |(id, label), issues|
+            val = name.english_name(id).to_s
+            next unless val.empty?
+
+            issues << issue(severity: :error,
+                            message: "Required name ID #{id} (#{label}) is " \
+                                     "missing from the name table",
+                            location: "name.nameID.#{id}")
+          end
+        end
+        private_class_method :validate_name_coverage
+
+        # ---------- OS/2 fsSelection reserved bits ----------
+
+        def self.validate_os2_fsselection(font)
+          return [] unless font.has_table?("OS/2")
+
+          os2 = font.table("OS/2")
+          fs = os2.fs_selection.to_i
+          reserved_mask = 0xFC00 # bits 10-15 are reserved
+          return [] if (fs & reserved_mask).zero?
+
+          [issue(severity: :warning,
+                 message: "OS/2 fsSelection uses reserved bits " \
+                          "(value 0x#{fs.to_s(16)}, bits 10-15 must be 0)",
+                 location: "os2.fs_selection")]
+        end
+        private_class_method :validate_os2_fsselection
+
+        # ---------- hhea.numberOfHMetrics ----------
+
+        def self.validate_hhea_metrics(font)
+          return [] unless font.has_table?("hhea") && font.has_table?("maxp")
+
+          num_metrics = font.table("hhea").number_of_h_metrics.to_i
+          num_glyphs = font.table("maxp").num_glyphs.to_i
+          return [] if num_metrics.positive? && num_metrics <= num_glyphs
+
+          [issue(severity: :error,
+                 message: "hhea.numberOfHMetrics (#{num_metrics}) must be " \
+                          "between 1 and maxp.numGlyphs (#{num_glyphs})",
+                 location: "hhea.number_of_h_metrics")]
+        end
+        private_class_method :validate_hhea_metrics
+      end
+    end
+  end
+end