fontisan 0.4.34 → 0.4.36

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

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Audit
+    module Checks
+      # Predicts whether Chrome/Android OTS (OpenType Sanitizer) would
+      # reject the font. OTS has strict requirements beyond the base
+      # OpenType spec — fonts that pass the spec can still be rejected
+      # by browsers.
+      #
+      # Ports the most commonly-hit ots-sanitize rules:
+      #
+      #   - head magicNumber must be 0x5F0F3CF5
+      #   - head unitsPerEm must be 16–16384
+      #   - name table must have PostScript + Family names
+      #   - post table version must be 1.0, 2.0, 2.5, 3.0, or 4.0
+      #   - numGlyphs must be ≤ 65534 (uint16 minus sentinel)
+      #   - glyf/CFF (depending on sfnt flavor) must be present
+      #   - cmap must have at least one Unicode subtable
+      #   - OS/2 usWeightClass must be 1–1000
+      #   - OS/2 usWidthClass must be 1–9
+      #   - Total file size must be under the OTS limit (~30MB)
+      #
+      # @see https://github.com/khaledhosny/ots/tree/master
+      class OtsCompatibilityCheck < Check
+        MAX_GLYPHS = 0xFFFD # 65534 — OTS rejects fonts with more
+        MAX_FILE_SIZE = 30 * 1024 * 1024 # 30MB — OTS soft limit
+        VALID_POST_VERSIONS = [1.0, 2.0, 2.5, 3.0, 4.0].freeze
+        HEAD_MAGIC = 0x5F0F3CF5
+        MIN_UPM = 16
+        MAX_UPM = 16_384
+
+        # @param font [SfntFont]
+        # @return [Array<Models::ValidationReport::Issue>]
+        def self.call(font)
+          issues = []
+          issues.concat(check_head(font))
+          issues.concat(check_post(font))
+          issues.concat(check_maxp(font))
+          issues.concat(check_name(font))
+          issues.concat(check_cmap(font))
+          issues.concat(check_os2(font))
+          issues.concat(check_outlines(font))
+          issues
+        end
+
+        def self.code
+          :ots_compatibility
+        end
+
+        # ---------- head ----------
+
+        def self.check_head(font)
+          issues = []
+          return [missing_table_issue("head", :error)] unless font.has_table?("head")
+
+          head = font.table("head")
+          if head.magic_number != HEAD_MAGIC
+            issues << issue(severity: :error,
+                            message: "OTS: head.magicNumber is 0x#{head.magic_number.to_i.to_s(16)} " \
+                                     "but must be 0x#{HEAD_MAGIC.to_s(16)}",
+                            location: "head.magic_number")
+          end
+          upm = head.units_per_em.to_i
+          if upm < MIN_UPM || upm > MAX_UPM
+            issues << issue(severity: :error,
+                            message: "OTS: head.unitsPerEm is #{upm} but must " \
+                                     "be between #{MIN_UPM} and #{MAX_UPM}",
+                            location: "head.units_per_em")
+          end
+          issues
+        end
+        private_class_method :check_head
+
+        # ---------- post ----------
+
+        def self.check_post(font)
+          return [missing_table_issue("post", :error)] unless font.has_table?("post")
+
+          post = font.table("post")
+          version = post.version.to_f
+          return [] if VALID_POST_VERSIONS.include?(version)
+
+          [issue(severity: :error,
+                 message: "OTS: post.version is #{version} but must be one of " \
+                          "#{VALID_POST_VERSIONS.join(', ')}",
+                 location: "post.version")]
+        end
+        private_class_method :check_post
+
+        # ---------- maxp ----------
+
+        def self.check_maxp(font)
+          return [missing_table_issue("maxp", :error)] unless font.has_table?("maxp")
+
+          num_glyphs = font.table("maxp").num_glyphs.to_i
+          return [] if num_glyphs <= MAX_GLYPHS
+
+          [issue(severity: :error,
+                 message: "OTS: maxp.numGlyphs is #{num_glyphs} but OTS " \
+                          "rejects fonts with more than #{MAX_GLYPHS} glyphs",
+                 location: "maxp.num_glyphs")]
+        end
+        private_class_method :check_maxp
+
+        # ---------- name ----------
+
+        def self.check_name(font)
+          return [missing_table_issue("name", :error)] unless font.has_table?("name")
+
+          name = font.table("name")
+          issues = []
+          if name.english_name(Tables::Name::FAMILY).to_s.empty?
+            issues << issue(severity: :error,
+                            message: "OTS: name table has no English Family name (nameID 1)",
+                            location: "name.nameID.1")
+          end
+          if name.english_name(Tables::Name::POSTSCRIPT_NAME).to_s.empty?
+            issues << issue(severity: :error,
+                            message: "OTS: name table has no English PostScript name " \
+                                     "(nameID 6)",
+                            location: "name.nameID.6")
+          end
+          issues
+        end
+        private_class_method :check_name
+
+        # ---------- cmap ----------
+
+        def self.check_cmap(font)
+          return [missing_table_issue("cmap", :error)] unless font.has_table?("cmap")
+
+          cmap = font.table("cmap")
+          mappings = cmap.unicode_mappings || {}
+          return [] if mappings.any?
+
+          [issue(severity: :error,
+                 message: "OTS: cmap has no Unicode subtable or no codepoint mappings",
+                 location: "cmap.unicode_mappings")]
+        end
+        private_class_method :check_cmap
+
+        # ---------- OS/2 ----------
+
+        def self.check_os2(font)
+          return [missing_table_issue("OS/2", :error)] unless font.has_table?("OS/2")
+
+          os2 = font.table("OS/2")
+          issues = []
+          weight = os2.us_weight_class.to_i
+          unless weight.between?(1, 1000)
+            issues << issue(severity: :error,
+                            message: "OTS: OS/2.usWeightClass is #{weight} " \
+                                     "but must be between 1 and 1000",
+                            location: "os2.us_weight_class")
+          end
+          width = os2.us_width_class.to_i
+          unless width.between?(1, 9)
+            issues << issue(severity: :error,
+                            message: "OTS: OS/2.usWidthClass is #{width} " \
+                                     "but must be between 1 and 9",
+                            location: "os2.us_width_class")
+          end
+          issues
+        end
+        private_class_method :check_os2
+
+        # ---------- outline presence ----------
+
+        def self.check_outlines(font)
+          has_glyf = font.has_table?("glyf")
+          has_cff = font.has_table?("CFF ") || font.has_table?("CFF2")
+          return [] if has_glyf || has_cff
+
+          [issue(severity: :error,
+                 message: "OTS: font has neither 'glyf' nor 'CFF '/'CFF2' — " \
+                          "no outline data",
+                 location: "outline_tables")]
+        end
+        private_class_method :check_outlines
+
+        def self.missing_table_issue(tag, severity)
+          issue(severity: severity,
+                message: "OTS: required table '#{tag}' is missing",
+                location: "tables.#{tag}")
+        end
+        private_class_method :missing_table_issue
+      end
+    end
+  end
+end

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

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Audit
+    module Checks
+      # Validates the SFNT table directory: checksums, 4-byte alignment,
+      # offset arithmetic, search-range/entry-selector/range-shift
+      # consistency.
+      #
+      # These checks are the foundation of all font validation — a
+      # corrupt table directory makes every downstream parse
+      # unreliable. Replaces the table-directory portion of MS Font
+      # Validator + ots-sanitize.
+      #
+      # @see https://learn.microsoft.com/en-us/typography/opentype/spec/otff#table-directory
+      class TableDirectoryCheck < Check
+        # @param font [SfntFont]
+        # @return [Array<Models::ValidationReport::Issue>]
+        def self.call(font)
+          issues = []
+          issues.concat(validate_search_fields(font))
+          issues.concat(validate_alignment(font))
+          issues.concat(validate_checksums(font))
+          issues.concat(validate_offsets(font))
+          issues
+        end
+
+        def self.code
+          :table_directory
+        end
+
+        # ---------- search range / entry selector / range shift ----------
+
+        def self.validate_search_fields(font)
+          num_tables = font.header.num_tables
+          expected_range = largest_power_of_two_le(num_tables) * 16
+          expected_selector = Math.log2(expected_range / 16).to_i
+          expected_shift = (num_tables * 16) - expected_range
+
+          issues = []
+          if font.header.search_range != expected_range
+            issues << issue(severity: :warning,
+                            message: "searchRange is #{font.header.search_range} " \
+                                     "but should be #{expected_range} " \
+                                     "(numTables=#{num_tables})",
+                            location: "header.searchRange")
+          end
+          if font.header.entry_selector != expected_selector
+            issues << issue(severity: :warning,
+                            message: "entrySelector is #{font.header.entry_selector} " \
+                                     "but should be #{expected_selector}",
+                            location: "header.entrySelector")
+          end
+          if font.header.range_shift != expected_shift
+            issues << issue(severity: :warning,
+                            message: "rangeShift is #{font.header.range_shift} " \
+                                     "but should be #{expected_shift}",
+                            location: "header.rangeShift")
+          end
+          issues
+        end
+
+        def self.largest_power_of_two_le(n)
+          return 0 if n <= 0
+
+          power = 1
+          power *= 2 while power * 2 <= n
+          power
+        end
+        private_class_method :largest_power_of_two_le
+
+        # ---------- 4-byte alignment ----------
+
+        def self.validate_alignment(font)
+          font.tables.each_with_object([]) do |entry, issues|
+            next if (entry.offset % 4).zero?
+
+            issues << issue(severity: :warning,
+                            message: "Table '#{readable_tag(entry.tag)}' at offset " \
+                                     "#{entry.offset} is not 4-byte aligned",
+                            location: "tables.#{readable_tag(entry.tag)}.offset")
+          end
+        end
+
+        # ---------- checksums ----------
+
+        # The 'head' table checksum has a special rule: its checkSumAdjustment
+        # field (offset 8) is set to make the whole-table checksum match the
+        # directory entry. We skip the head table's own checksum verification
+        # and instead verify the adjustment is present.
+        def self.validate_checksums(font)
+          font.tables.each_with_object([]) do |entry, issues|
+            tag = readable_tag(entry.tag)
+            raw = font.table_data[tag]
+            next unless raw
+
+            next if tag == "head" # checkSumAdjustment complicates this
+
+            actual = checksum(raw)
+            next if actual == entry.checksum
+
+            issues << issue(severity: :error,
+                            message: "Table '#{tag}' checksum mismatch: " \
+                                     "directory=0x#{entry.checksum.to_s(16).upcase} " \
+                                     "computed=0x#{actual.to_s(16).upcase}",
+                            location: "tables.#{tag}.checksum")
+          end
+        end
+
+        # OpenType table checksum: sum of uint32 words, padded to 4 bytes
+        # with zeros if the table length isn't a multiple of 4.
+        def self.checksum(data)
+          remainder = data.bytesize % 4
+          padded_bytes = remainder.zero? ? data : data + "\x00".b * (4 - remainder)
+          padded_bytes.unpack("N*").sum & 0xFFFFFFFF
+        rescue StandardError
+          0
+        end
+        private_class_method :checksum
+
+        # ---------- offset arithmetic ----------
+
+        def self.validate_offsets(font)
+          dir_end = 12 + (font.header.num_tables * 16)
+          font.tables.each_with_object([]) do |entry, issues|
+            tag = readable_tag(entry.tag)
+
+            if entry.offset < dir_end
+              issues << issue(severity: :error,
+                              message: "Table '#{tag}' offset #{entry.offset} " \
+                                       "overlaps the table directory " \
+                                       "(directory ends at #{dir_end})",
+                              location: "tables.#{tag}.offset")
+            end
+
+            raw = font.table_data[tag]
+            if raw && raw.bytesize != entry.table_length
+              issues << issue(severity: :error,
+                              message: "Table '#{tag}' length mismatch: " \
+                                       "directory says #{entry.table_length} " \
+                                       "but actual data is #{raw.bytesize} bytes",
+                              location: "tables.#{tag}.table_length")
+            end
+          end
+        end
+
+        # BinData returns ASCII-8BIT tag strings; normalize for display.
+        def self.readable_tag(tag)
+          tag.dup.force_encoding("UTF-8")
+        rescue StandardError
+          tag.to_s
+        end
+        private_class_method :readable_tag
+      end
+    end
+  end
+end

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

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Audit
+    module Checks
+      # Validates variable-font readiness: fvar axis invariants, named
+      # instances within ranges, companion-table presence (gvar for
+      # TrueType outlines, HVAR for horizontal metrics, STAT for OS
+      # style matching). Ports the most commonly-hit fontbakery GF-VF
+      # check subset.
+      #
+      # Only runs when the font HAS an fvar table — static fonts are
+      # skipped (returns empty issues array).
+      #
+      # @see https://learn.microsoft.com/en-us/typography/opentype/spec/fvar
+      class VariableFontCheck < Check
+        # @param font [SfntFont]
+        # @return [Array<Models::ValidationReport::Issue>]
+        def self.call(font)
+          return [] unless font.has_table?("fvar")
+
+          issues = []
+          issues.concat(validate_axes(font))
+          issues.concat(validate_instances(font))
+          issues.concat(validate_companion_tables(font))
+          issues
+        end
+
+        def self.code
+          :variable_font
+        end
+
+        # ---------- fvar axes ----------
+
+        def self.validate_axes(font)
+          fvar = font.table("fvar")
+          axes = fvar.axes
+          issues = []
+
+          issues.concat(check_axis_uniqueness(axes))
+          axes.each_with_index { |axis, idx| issues.concat(check_one_axis(axis, idx)) }
+          issues
+        end
+        private_class_method :validate_axes
+
+        def self.check_axis_uniqueness(axes)
+          tags = axes.map(&:axis_tag)
+          duplicates = tags.tally.filter_map { |t, c| t if c > 1 }
+          duplicates.map do |tag|
+            issue(severity: :error,
+                  message: "Duplicate fvar axis tag '#{tag}' — axis tags " \
+                           "must be unique within a font",
+                  location: "fvar.axes.#{tag}")
+          end
+        end
+        private_class_method :check_axis_uniqueness
+
+        def self.check_one_axis(axis, idx)
+          issues = []
+          min_v = axis.min_value.to_f
+          default_v = axis.default_value.to_f
+          max_v = axis.max_value.to_f
+
+          unless min_v <= default_v && default_v <= max_v
+            issues << issue(severity: :error,
+                            message: "fvar axis '#{axis.axis_tag}' (#{idx}) has " \
+                                     "invalid range: min=#{min_v} " \
+                                     "default=#{default_v} max=#{max_v} " \
+                                     "(must be min ≤ default ≤ max)",
+                            location: "fvar.axes.#{idx}")
+          end
+
+          if axis.axis_name_id.to_i.zero?
+            issues << issue(severity: :warning,
+                            message: "fvar axis '#{axis.axis_tag}' (#{idx}) has " \
+                                     "no name ID — users cannot identify the axis",
+                            location: "fvar.axes.#{idx}.axis_name_id")
+          end
+
+          issues
+        end
+        private_class_method :check_one_axis
+
+        # ---------- fvar named instances ----------
+
+        def self.validate_instances(font)
+          fvar = font.table("fvar")
+          instances = fvar.instances || []
+          axes = fvar.axes
+
+          instances.each_with_index.with_object([]) do |(inst, idx), issues|
+            issues.concat(check_instance_ranges(inst, idx, axes))
+          end
+        end
+        private_class_method :validate_instances
+
+        def self.check_instance_ranges(inst, idx, axes)
+          issues = []
+          coords = inst[:coordinates] || inst["coordinates"] || []
+          coords.each_with_index do |coord, axis_idx|
+            next unless axes[axis_idx]
+
+            axis = axes[axis_idx]
+            min_v = axis.min_value.to_f
+            max_v = axis.max_value.to_f
+            next if coord.to_f.between?(min_v, max_v)
+
+            issues << issue(severity: :warning,
+                            message: "fvar instance #{idx} has coordinate " \
+                                     "#{coord} for axis '#{axis.axis_tag}' " \
+                                     "outside its range [#{min_v}, #{max_v}]",
+                            location: "fvar.instances.#{idx}.#{axis.axis_tag}")
+          end
+          issues
+        end
+        private_class_method :check_instance_ranges
+
+        # ---------- companion tables ----------
+
+        def self.validate_companion_tables(font)
+          issues = []
+          is_truetype = font.has_table?("glyf")
+          if is_truetype && !font.has_table?("gvar")
+            issues << issue(severity: :warning,
+                            message: "Variable TrueType font has no 'gvar' table — " \
+                                     "glyph outlines won't vary across the design space",
+                            location: "tables.gvar")
+          end
+
+          unless font.has_table?("HVAR")
+            issues << issue(severity: :warning,
+                            message: "Variable font has no 'HVAR' table — " \
+                                     "advance widths won't vary; renderers must " \
+                                     "fall back to per-glyph hmtx lookups",
+                            location: "tables.HVAR")
+          end
+
+          unless font.has_table?("STAT")
+            issues << issue(severity: :info,
+                            message: "Variable font has no 'STAT' table — " \
+                                     "OS style-matching won't work; Windows and " \
+                                     "modern font pickers rely on STAT",
+                            location: "tables.STAT")
+          end
+          issues
+        end
+        private_class_method :validate_companion_tables
+      end
+    end
+  end
+end

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

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Audit
+    module Checks
+      # Validates WOFF2 (Web Open Font Format 2) wrapper structure per
+      # the W3C WOFF2 spec. Only runs when the font IS a Woff2Font —
+      # plain TTF/OTF inputs are skipped.
+      #
+      # Checks:
+      #
+      #   - Signature must be 0x774F4632 ('wOF2')
+      #   - Flavor must be a valid SFNT version
+      #   - reserved field must be 0
+      #   - major_version should be 1
+      #   - total_compressed_size must be positive
+      #   - If metadata block is present, lengths must be consistent
+      #   - num_tables must match the table directory count
+      #
+      # @see https://www.w3.org/TR/WOFF2/
+      class Woff2ValidationCheck < Check
+        WOFF2_SIGNATURE = 0x774F4632
+        VALID_FLAVORS = [
+          0x00010000, # TrueType
+          0x74727565, # 'true' (Apple TrueType)
+          0x4F54544F, # 'OTTO' (OpenType CFF)
+          0x74746366, # 'ttcf' (collection)
+        ].freeze
+
+        # @param font [Woff2Font, SfntFont]
+        # @return [Array<Models::ValidationReport::Issue>]
+        def self.call(font)
+          return [] unless woff2?(font)
+
+          header = font.header
+          issues = []
+          issues.concat(validate_signature(header))
+          issues.concat(validate_flavor(header))
+          issues.concat(validate_reserved(header))
+          issues.concat(validate_version(header))
+          issues.concat(validate_sizes(header))
+          issues.concat(validate_metadata(header))
+          issues
+        end
+
+        def self.code
+          :woff2_validation
+        end
+
+        def self.woff2?(font)
+          font.is_a?(Woff2Font)
+        end
+        private_class_method :woff2?
+
+        def self.validate_signature(header)
+          return [] if header.signature == WOFF2_SIGNATURE
+
+          [issue(severity: :error,
+                 message: "WOFF2 signature is 0x#{header.signature.to_s(16)} " \
+                          "but must be 0x#{WOFF2_SIGNATURE.to_s(16)} ('wOF2')",
+                 location: "woff2_header.signature")]
+        end
+        private_class_method :validate_signature
+
+        def self.validate_flavor(header)
+          return [] if VALID_FLAVORS.include?(header.flavor)
+
+          [issue(severity: :error,
+                 message: "WOFF2 flavor is 0x#{header.flavor.to_s(16)} " \
+                          "but must be a valid SFNT version " \
+                          "(0x00010000, 0x74727565, 0x4F54544F, or 0x74746366)",
+                 location: "woff2_header.flavor")]
+        end
+        private_class_method :validate_flavor
+
+        def self.validate_reserved(header)
+          return [] if header.reserved.zero?
+
+          [issue(severity: :warning,
+                 message: "WOFF2 reserved field is #{header.reserved} " \
+                          "but must be 0 per the spec",
+                 location: "woff2_header.reserved")]
+        end
+        private_class_method :validate_reserved
+
+        def self.validate_version(header)
+          issues = []
+          if header.major_version != 1
+            issues << issue(severity: :warning,
+                            message: "WOFF2 major version is #{header.major_version} " \
+                                     "but the spec recommends 1",
+                            location: "woff2_header.major_version")
+          end
+          issues
+        end
+        private_class_method :validate_version
+
+        def self.validate_sizes(header)
+          issues = []
+          if header.total_compressed_size.to_i <= 0
+            issues << issue(severity: :error,
+                            message: "WOFF2 total_compressed_size is " \
+                                     "#{header.total_compressed_size} but must be positive",
+                            location: "woff2_header.total_compressed_size")
+          end
+          if header.total_sfnt_size.to_i <= 0
+            issues << issue(severity: :error,
+                            message: "WOFF2 total_sfnt_size is " \
+                                     "#{header.total_sfnt_size} but must be positive",
+                            location: "woff2_header.total_sfnt_size")
+          end
+          issues
+        end
+        private_class_method :validate_sizes
+
+        def self.validate_metadata(header)
+          return [] unless header.meta_offset.to_i.positive?
+
+          issues = []
+          if header.meta_length.to_i <= 0
+            issues << issue(severity: :error,
+                            message: "WOFF2 metadata offset is set but " \
+                                     "meta_length is #{header.meta_length} " \
+                                     "(must be positive)",
+                            location: "woff2_header.meta_length")
+          end
+          if header.meta_orig_length.to_i <= 0
+            issues << issue(severity: :error,
+                            message: "WOFF2 metadata offset is set but " \
+                                     "meta_orig_length is #{header.meta_orig_length} " \
+                                     "(must be positive)",
+                            location: "woff2_header.meta_orig_length")
+          end
+          issues
+        end
+        private_class_method :validate_metadata
+      end
+    end
+  end
+end

data/lib/fontisan/audit/checks.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Fontisan
+  module Audit
+    # Individual audit check implementations. Each is a standalone class
+    # under {Audit::Check} that implements `.call(font)` and `.code`.
+    #
+    # Adding a new check = one file + one autoload entry here. No edits
+    # to {CheckRegistry} or {AuditCommand} required (Open/Closed).
+    module Checks
+      autoload :TableDirectoryCheck, "fontisan/audit/checks/table_directory_check"
+      autoload :GlyphNameCheck, "fontisan/audit/checks/glyph_name_check"
+      autoload :CmapCheck, "fontisan/audit/checks/cmap_check"
+      autoload :OtsCompatibilityCheck,
+               "fontisan/audit/checks/ots_compatibility_check"
+      autoload :CollectionIntegrityCheck,
+               "fontisan/audit/checks/collection_integrity_check"
+      autoload :VariableFontCheck, "fontisan/audit/checks/variable_font_check"
+      autoload :HintingCheck, "fontisan/audit/checks/hinting_check"
+      autoload :Woff2ValidationCheck,
+               "fontisan/audit/checks/woff2_validation_check"
+      autoload :FormatRoundTripCheck,
+               "fontisan/audit/checks/format_round_trip_check"
+      autoload :OpenTypeConformanceCheck,
+               "fontisan/audit/checks/opentype_conformance_check"
+    end
+  end
+end

data/lib/fontisan/audit.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Fontisan
+  # Audit-layer validation axes. Each check is a standalone module that
+  # produces structured issues when run against a loaded font. Checks
+  # are MECE by design: one concern per check (checksums, glyph names,
+  # cmap subtables, OTS compatibility, collection integrity, etc.).
+  #
+  # Checks are independent of the existing `Validators::*` framework
+  # (which uses a DSL and produces boolean pass/fail per check). The
+  # audit checks produce detailed `Models::ValidationReport::Issue`
+  # records so the consumer knows exactly what failed and where.
+  #
+  # @see Models::ValidationReport::Issue
+  module Audit
+    autoload :Check, "fontisan/audit/check"
+    autoload :CheckRegistry, "fontisan/audit/check_registry"
+    autoload :Checks, "fontisan/audit/checks"
+  end
+end