fontisan 0.4.35 → 0.4.37

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Audit
+    module Checks
+      # Validates the 'kern' table if present. The kern table is
+      # deprecated by the OpenType spec — GPOS is the replacement.
+      # Many legacy fonts still ship kern; this check warns about
+      # deprecation and validates basic structure.
+      #
+      # @see https://learn.microsoft.com/en-us/typography/opentype/spec/kern
+      class KernCheck < Check
+        def self.call(font)
+          return [] unless font.has_table?("kern")
+
+          issues = [deprecation_warning]
+          issues.concat(validate_gpos_presence(font))
+          issues
+        end
+
+        def self.code
+          :ot_kern
+        end
+
+        def self.deprecation_warning
+          issue(severity: :warning,
+                message: "kern table is present but deprecated by the " \
+                         "OpenType spec — use GPOS instead. Some modern " \
+                         "renderers (HarfBuzz, Core Text) ignore kern",
+                location: "tables.kern")
+        end
+        private_class_method :deprecation_warning
+
+        def self.validate_gpos_presence(font)
+          return [] if font.has_table?("GPOS")
+
+          [issue(severity: :warning,
+                 message: "kern table present but no GPOS table — " \
+                          "kerning data should be migrated to a GPOS " \
+                          "'kern' feature for full renderer support",
+                 location: "tables.GPOS")]
+        end
+        private_class_method :validate_gpos_presence
+      end
+    end
+  end
+end

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Audit
+    module Checks
+      # Validates the 'maxp' table per the OpenType spec.
+      #
+      # @see https://learn.microsoft.com/en-us/typography/opentype/spec/maxp
+      class MaxpCheck < Check
+        MAX_GLYPHS = 0xFFFF
+        MAX_STACK_ELEMENTS = 1000
+
+        def self.call(font)
+          return [] unless font.has_table?("maxp")
+
+          maxp = font.table("maxp")
+          issues = []
+          issues.concat(validate_version(maxp, font))
+          issues.concat(validate_num_glyphs(maxp))
+          issues.concat(validate_hint_capacity(maxp))
+          issues
+        end
+
+        def self.code
+          :ot_maxp
+        end
+
+        def self.validate_version(maxp, font)
+          version_raw = maxp.version_raw
+          is_truetype = font.has_table?("glyf")
+          tt_version = 0x00010000 # 1.0 as Fixed 16.16
+          cff_version = 0x00005000 # 0.5 as Fixed 16.16
+          if is_truetype && version_raw != tt_version
+            [issue(severity: :error,
+                   message: "maxp.version is 0x#{version_raw.to_s(16)} but must " \
+                            "be 1.0 (0x#{tt_version.to_s(16)}) for TrueType fonts",
+                   location: "maxp.version")]
+          elsif !is_truetype && version_raw != cff_version
+            [issue(severity: :warning,
+                   message: "maxp.version is 0x#{version_raw.to_s(16)} but " \
+                            "should be 0.5 (0x#{cff_version.to_s(16)}) for " \
+                            "CFF-based fonts",
+                   location: "maxp.version")]
+          else
+            []
+          end
+        end
+        private_class_method :validate_version
+
+        def self.validate_num_glyphs(maxp)
+          n = maxp.num_glyphs.to_i
+          return [] if n.between?(1, MAX_GLYPHS)
+
+          [issue(severity: :error,
+                 message: "maxp.numGlyphs is #{n} but must be between 1 and " \
+                          "#{MAX_GLYPHS}",
+                 location: "maxp.num_glyphs")]
+        end
+        private_class_method :validate_num_glyphs
+
+        def self.validate_hint_capacity(maxp)
+          return [] unless maxp.version_1_0?
+
+          issues = []
+          zones = maxp.max_zones.to_i
+          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
+          stack = maxp.max_stack_elements.to_i
+          if stack > MAX_STACK_ELEMENTS
+            issues << issue(severity: :warning,
+                            message: "maxp.maxStackElements is #{stack} — " \
+                                     "excessively large values waste interpreter memory",
+                            location: "maxp.max_stack_elements")
+          end
+          issues
+        end
+        private_class_method :validate_hint_capacity
+      end
+    end
+  end
+end

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Audit
+    module Checks
+      # Validates the 'name' table per the OpenType spec.
+      #
+      # Covers: required nameIDs, PostScript name character validity,
+      # version string format. Glyph-name rules are in GlyphNameCheck.
+      #
+      # @see https://learn.microsoft.com/en-us/typography/opentype/spec/name
+      class NameTableCheck < Check
+        REQUIRED_NAME_IDS = {
+          1 => "Family",
+          2 => "Subfamily",
+          4 => "Full",
+          6 => "PostScript",
+        }.freeze
+        PS_NAME_PATTERN = /\A[A-Za-z][A-Za-z0-9._-]*\z/
+
+        def self.call(font)
+          return [] unless font.has_table?("name")
+
+          name = font.table("name")
+          issues = []
+          issues.concat(validate_required_ids(name))
+          issues.concat(validate_ps_name(name))
+          issues.concat(validate_version_string(name))
+          issues
+        end
+
+        def self.code
+          :ot_name
+        end
+
+        def self.validate_required_ids(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_required_ids
+
+        def self.validate_ps_name(name)
+          ps = name.english_name(6).to_s
+          return [] if ps.empty? || ps.match?(PS_NAME_PATTERN)
+
+          [issue(severity: :warning,
+                 message: "PostScript name '#{ps}' contains characters outside " \
+                          "the OT spec grammar (must start with a letter, then " \
+                          "A–Z a–z 0–9 . - _)",
+                 location: "name.nameID.6")]
+        end
+        private_class_method :validate_ps_name
+
+        def self.validate_version_string(name)
+          ver = name.english_name(5).to_s
+          return [] if ver.empty?
+
+          unless ver.match?(/\AVersion\s/i)
+            return [issue(severity: :info,
+                          message: "name ID 5 (version) is '#{ver}' but should " \
+                                   "start with 'Version ' per OT spec convention",
+                          location: "name.nameID.5")]
+          end
+
+          []
+        end
+        private_class_method :validate_version_string
+      end
+    end
+  end
+end

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

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Audit
+    module Checks
+      # Foundational cross-table OpenType spec conformance checks.
+      # Per-table rules live in their own check modules
+      # ({HeadCheck}, {HheaCheck}, {Os2Check}, {NameTableCheck},
+      # {PostCheck}, {KernCheck}) to keep each concern MECE.
+      #
+      # This check owns the rules that span multiple tables:
+      #
+      #   - Required tables for each sfnt flavor (TTF vs CFF vs variable)
+      #   - head.indexToLocFormat consistency with loca table byte size
+      #   - hhea.numberOfHMetrics must be ≤ maxp.numGlyphs
+      #
+      # @see https://learn.microsoft.com/en-us/typography/opentype/spec/otff
+      class OpenTypeConformanceCheck < Check
+        # @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_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
+
+        # ---------- 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

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

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Audit
+    module Checks
+      # Validates the 'OS/2' table per the OpenType spec.
+      #
+      # @see https://learn.microsoft.com/en-us/typography/opentype/spec/os2
+      class Os2Check < Check
+        FS_SELECTION_RESERVED = 0xFC00
+
+        def self.call(font)
+          return [] unless font.has_table?("OS/2")
+
+          os2 = font.table("OS/2")
+          issues = []
+          issues.concat(validate_weight_class(os2))
+          issues.concat(validate_width_class(os2))
+          issues.concat(validate_fs_selection(os2))
+          issues.concat(validate_typo_metrics(os2))
+          issues.concat(validate_win_metrics(os2))
+          issues.concat(validate_panose(os2))
+          issues
+        end
+
+        def self.code
+          :ot_os2
+        end
+
+        def self.validate_weight_class(os2)
+          w = os2.us_weight_class.to_i
+          return [] if w.between?(1, 1000)
+
+          [issue(severity: :error,
+                 message: "OS/2.usWeightClass is #{w} but must be between " \
+                          "1 and 1000",
+                 location: "os2.us_weight_class")]
+        end
+        private_class_method :validate_weight_class
+
+        def self.validate_width_class(os2)
+          w = os2.us_width_class.to_i
+          return [] if w.between?(1, 9)
+
+          [issue(severity: :error,
+                 message: "OS/2.usWidthClass is #{w} but must be between 1 " \
+                          "and 9",
+                 location: "os2.us_width_class")]
+        end
+        private_class_method :validate_width_class
+
+        def self.validate_fs_selection(os2)
+          fs = os2.fs_selection.to_i
+          return [] if (fs & FS_SELECTION_RESERVED).zero?
+
+          [issue(severity: :warning,
+                 message: "OS/2.fsSelection uses reserved bits " \
+                          "(0x#{fs.to_s(16)}, bits 10-15 must be 0)",
+                 location: "os2.fs_selection")]
+        end
+        private_class_method :validate_fs_selection
+
+        def self.validate_typo_metrics(os2)
+          issues = []
+          asc = os2.s_typo_ascender.to_i
+          desc = os2.s_typo_descender.to_i
+          if asc <= 0
+            issues << issue(severity: :warning,
+                            message: "OS/2.sTypoAscender is #{asc} but should " \
+                                     "be positive",
+                            location: "os2.s_typo_ascender")
+          end
+          if desc.positive?
+            issues << issue(severity: :warning,
+                            message: "OS/2.sTypoDescender is #{desc} but should " \
+                                     "be ≤ 0",
+                            location: "os2.s_typo_descender")
+          end
+          issues
+        end
+        private_class_method :validate_typo_metrics
+
+        def self.validate_win_metrics(os2)
+          issues = []
+          if os2.us_win_ascent.to_i <= 0
+            issues << issue(severity: :warning,
+                            message: "OS/2.usWinAscent is #{os2.us_win_ascent} " \
+                                     "but should be positive",
+                            location: "os2.us_win_ascent")
+          end
+          if os2.us_win_descent.to_i <= 0
+            issues << issue(severity: :warning,
+                            message: "OS/2.usWinDescent is #{os2.us_win_descent} " \
+                                     "but should be positive",
+                            location: "os2.us_win_descent")
+          end
+          issues
+        end
+        private_class_method :validate_win_metrics
+
+        def self.validate_panose(os2)
+          panose = os2.panose
+          return [] unless panose
+
+          all_zero = panose.to_a.all?(&:zero?)
+          return [] unless all_zero
+
+          [issue(severity: :info,
+                 message: "OS/2.panose is all zeros — PANOSE classification " \
+                          "helps font matching in some applications",
+                 location: "os2.panose")]
+        end
+        private_class_method :validate_panose
+      end
+    end
+  end
+end

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

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Audit
+    module Checks
+      # Validates the 'post' table per the OpenType spec.
+      #
+      # @see https://learn.microsoft.com/en-us/typography/opentype/spec/post
+      class PostCheck < Check
+        VALID_VERSIONS = [1.0, 2.0, 2.5, 3.0, 4.0].freeze
+
+        def self.call(font)
+          return [] unless font.has_table?("post")
+
+          post = font.table("post")
+          head = font.has_table?("head") ? font.table("head") : nil
+          issues = []
+          issues.concat(validate_version(post))
+          issues.concat(validate_italic_angle(post, head))
+          issues.concat(validate_is_fixed_pitch(post))
+          issues
+        end
+
+        def self.code
+          :ot_post
+        end
+
+        def self.validate_version(post)
+          version = post.version.to_f
+          return [] if VALID_VERSIONS.include?(version)
+
+          [issue(severity: :error,
+                 message: "post.version is #{version} but must be one of " \
+                          "#{VALID_VERSIONS.join(', ')}",
+                 location: "post.version")]
+        end
+        private_class_method :validate_version
+
+        def self.validate_italic_angle(post, head)
+          angle = post.italic_angle.to_f
+          issues = []
+          if head&.mac_style
+            is_italic = (head.mac_style.to_i & 0x02).positive?
+            if is_italic && angle >= 0
+              issues << issue(severity: :warning,
+                              message: "post.italicAngle is #{angle} but " \
+                                       "head.macStyle indicates italic " \
+                                       "(angle should be negative)",
+                              location: "post.italic_angle")
+            elsif !is_italic && angle != 0
+              issues << issue(severity: :info,
+                              message: "post.italicAngle is #{angle} but " \
+                                       "head.macStyle does not indicate italic " \
+                                       "(angle should be 0)",
+                              location: "post.italic_angle")
+            end
+          end
+          issues
+        end
+        private_class_method :validate_italic_angle
+
+        def self.validate_is_fixed_pitch(post)
+          val = post.is_fixed_pitch.to_i
+          return [] if [0, 1].include?(val)
+
+          [issue(severity: :warning,
+                 message: "post.isFixedPitch is #{val} but must be 0 " \
+                          "(proportional) or 1 (monospace)",
+                 location: "post.is_fixed_pitch")]
+        end
+        private_class_method :validate_is_fixed_pitch
+      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