fontisan 0.4.33 → 0.4.35

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

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+module Fontisan
+  module Audit
+    module Checks
+      # Validates cmap subtable invariants per the OpenType spec:
+      #
+      #   - At least one Unicode-encoded subtable is present
+      #   - Format 4: segCountX2 must equal segCount × 2
+      #   - Format 4: the last segment must have endCode 0xFFFF
+      #   - Format 4: reservedPad must be 0
+      #   - Format 12: groups must be sorted and non-overlapping
+      #   - Format 12: each group startCharCode ≤ endCharCode
+      #   - Subtable offsets must be within the cmap table bounds
+      #
+      # Catches the most common real-world cmap bugs that renderers and
+      # text shapers reject silently.
+      #
+      # @see https://learn.microsoft.com/en-us/typography/opentype/spec/cmap
+      class CmapCheck < Check
+        # @param font [SfntFont]
+        # @return [Array<Models::ValidationReport::Issue>]
+        def self.call(font)
+          return [] unless font.has_table?("cmap")
+
+          raw = font.table_data["cmap"]
+          return [] unless raw
+
+          issues = []
+          issues.concat(validate_header(raw))
+          return issues unless issues.empty?
+
+          records = read_encoding_records(raw)
+          issues.concat(validate_unicode_presence(records))
+          issues.concat(validate_subtables(raw, records))
+          issues
+        end
+
+        def self.code
+          :cmap
+        end
+
+        # ---------- header ----------
+
+        def self.validate_header(raw)
+          issues = []
+          version, num_tables = raw.unpack("nn")
+          if version != 0
+            issues << issue(severity: :error,
+                            message: "cmap version is #{version} but must be 0",
+                            location: "cmap.version")
+          end
+          if num_tables.zero?
+            issues << issue(severity: :error,
+                            message: "cmap has no encoding records",
+                            location: "cmap.numTables")
+          end
+          issues
+        end
+        private_class_method :validate_header
+
+        # ---------- encoding records ----------
+
+        def self.read_encoding_records(raw)
+          num_tables = raw.unpack1("x2n")
+          offset = 4
+          Array.new(num_tables) do |i|
+            break if offset + 8 > raw.bytesize
+
+            platform_id, encoding_id, subtable_offset = raw[offset, 8].unpack("nnN")
+            offset += 8
+            {
+              index: i,
+              platform_id: platform_id,
+              encoding_id: encoding_id,
+              subtable_offset: subtable_offset,
+            }
+          end
+        end
+        private_class_method :read_encoding_records
+
+        def self.validate_unicode_presence(records)
+          has_unicode = records.any? do |r|
+            unicode_platform?(r[:platform_id], r[:encoding_id])
+          end
+          return [] if has_unicode
+
+          [issue(severity: :warning,
+                 message: "cmap has no Unicode-encoded subtable " \
+                          "(expected platform 0 or 3 with encoding 1 or 10)",
+                 location: "cmap.encoding_records")]
+        end
+        private_class_method :validate_unicode_presence
+
+        def self.unicode_platform?(platform_id, encoding_id)
+          platform_id.zero? ||
+            (platform_id == 3 && [1, 10].include?(encoding_id))
+        end
+        private_class_method :unicode_platform?
+
+        # ---------- per-subtable validation ----------
+
+        def self.validate_subtables(raw, records)
+          records.flat_map { |r| validate_one_subtable(raw, r) }
+        end
+        private_class_method :validate_subtables
+
+        def self.validate_one_subtable(raw, record)
+          off = record[:subtable_offset]
+          if off + 2 > raw.bytesize
+            return [issue(severity: :error,
+                          message: "cmap subtable at record #{record[:index]} " \
+                                   "has offset #{off} beyond the table end",
+                          location: "cmap.encoding_records.#{record[:index]}")]
+          end
+
+          format = raw[off, 2].unpack1("n")
+          case format
+          when 0 then validate_format0(raw, off, record)
+          when 4 then validate_format4(raw, off, record)
+          when 6 then validate_format6(raw, off, record)
+          when 12 then validate_format12(raw, off, record)
+          when 14 then [] # format 14 (Unicode Variation Sequences) — skip for now
+          else
+            [issue(severity: :warning,
+                   message: "cmap subtable at record #{record[:index]} uses " \
+                            "unknown format #{format}",
+                   location: "cmap.encoding_records.#{record[:index]}")]
+          end
+        end
+        private_class_method :validate_one_subtable
+
+        # Format 4 validation: segCountX2 consistency, sentinel, reservedPad.
+        def self.validate_format4(raw, off, record)
+          issues = []
+          return issues unless off + 14 <= raw.bytesize
+
+          _format, _, _lang, seg_count_x2, _search, _sel, _shift,
+            = raw[off, 16].unpack("nnnnnnnn")
+          seg_count = seg_count_x2 / 2
+
+          if seg_count_x2.odd? || seg_count_x2 != seg_count * 2
+            issues << issue(severity: :error,
+                            message: "cmap format 4 (record #{record[:index]}): " \
+                                     "segCountX2=#{seg_count_x2} is inconsistent " \
+                                     "with segCount=#{seg_count}",
+                            location: "cmap.encoding_records.#{record[:index]}")
+          end
+
+          # Read the last endCode (the sentinel segment)
+          end_codes_start = off + 14
+          if seg_count.positive? && end_codes_start + (seg_count * 2) <= raw.bytesize
+            last_end = raw[end_codes_start + ((seg_count - 1) * 2), 2].unpack1("n")
+            if last_end != 0xFFFF
+              issues << issue(severity: :warning,
+                              message: "cmap format 4 (record #{record[:index]}): " \
+                                       "last segment endCode is 0x#{last_end.to_s(16)} " \
+                                       "but should be 0xFFFF (sentinel)",
+                              location: "cmap.encoding_records.#{record[:index]}")
+            end
+          end
+
+          # reservedPad check
+          reserved_pad_off = end_codes_start + (seg_count * 2)
+          if reserved_pad_off + 2 <= raw.bytesize
+            reserved_pad = raw[reserved_pad_off, 2].unpack1("n")
+            unless reserved_pad.zero?
+              issues << issue(severity: :error,
+                              message: "cmap format 4 (record #{record[:index]}): " \
+                                       "reservedPad is #{reserved_pad} but must be 0",
+                              location: "cmap.encoding_records.#{record[:index]}")
+            end
+          end
+
+          issues
+        end
+        private_class_method :validate_format4
+
+        # Format 12 validation: groups sorted, non-overlapping, ordered.
+        def self.validate_format12(raw, off, record)
+          issues = []
+          return issues unless off + 16 <= raw.bytesize
+
+          _format, _reserved, _length, _lang, num_groups = raw[off, 16].unpack("nnNnN")
+          groups_start = off + 16
+          return issues if num_groups.zero?
+          return issues unless groups_start + (num_groups * 12) <= raw.bytesize
+
+          prev_end = nil
+          num_groups.times do |g|
+            entry_off = groups_start + (g * 12)
+            start_cp, end_cp, _gid = raw[entry_off, 12].unpack("NNN")
+
+            if start_cp > end_cp
+              issues << issue(severity: :error,
+                              message: "cmap format 12 (record #{record[:index]}): " \
+                                       "group #{g} has startCharCode 0x#{start_cp.to_s(16)} " \
+                                       "> endCharCode 0x#{end_cp.to_s(16)}",
+                              location: "cmap.encoding_records.#{record[:index]}")
+            end
+
+            if prev_end && start_cp <= prev_end
+              issues << issue(severity: :error,
+                              message: "cmap format 12 (record #{record[:index]}): " \
+                                       "group #{g} overlaps or is out of order " \
+                                       "(startCharCode 0x#{start_cp.to_s(16)} ≤ " \
+                                       "previous endCharCode 0x#{prev_end.to_s(16)})",
+                              location: "cmap.encoding_records.#{record[:index]}")
+            end
+            prev_end = end_cp
+          end
+          issues
+        end
+        private_class_method :validate_format12
+
+        def self.validate_format0(raw, off, record)
+          # Format 0: 262 bytes (header 6 + 256-byte glyphIdArray)
+          if off + 262 > raw.bytesize
+            [issue(severity: :error,
+                   message: "cmap format 0 (record #{record[:index]}): " \
+                            "subtable is truncated (need 262 bytes)",
+                   location: "cmap.encoding_records.#{record[:index]}")]
+          else
+            []
+          end
+        end
+        private_class_method :validate_format0
+
+        def self.validate_format6(raw, off, record)
+          return [] unless off + 10 <= raw.bytesize
+
+          _fmt, _len, _lang, first, count = raw[off, 10].unpack("nnnnn")
+          needed = off + 10 + (count * 2)
+          if needed > raw.bytesize
+            [issue(severity: :error,
+                   message: "cmap format 6 (record #{record[:index]}): " \
+                            "subtable truncated (first=#{first}, count=#{count})",
+                   location: "cmap.encoding_records.#{record[:index]}")]
+          else
+            []
+          end
+        end
+        private_class_method :validate_format6
+      end
+    end
+  end
+end

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

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Audit
+    module Checks
+      # Validates TrueType/OpenType Collection (TTC/OTC) structural
+      # integrity: TTC header, per-face SFNT offsets, shared-table
+      # deduplication. TTC is undertooled — CJK and Apple workflows
+      # ship fonts as collections and no widely-available validator
+      # covers the collection-specific invariants.
+      #
+      # Checks:
+      #
+      #   - TTC tag must be 'ttcf'
+      #   - header.majorVersion must be 1 or 2
+      #   - numFonts must be positive and match the offset array length
+      #   - every face offset must be > 0 and within the file
+      #   - face offsets must not overlap the TTC header
+      #   - (v2 only) DSIG tag/length must be null or point inside the file
+      #
+      # @see https://learn.microsoft.com/en-us/typography/opentype/spec/otff#ttc-header
+      class CollectionIntegrityCheck < Check
+        TTC_TAG = "ttcf"
+        VALID_MAJOR_VERSIONS = [1, 2].freeze
+
+        # @param font [BaseCollection, SfntFont] a collection or single font
+        # @return [Array<Models::ValidationReport::Issue>]
+        def self.call(font)
+          return [] unless collection?(font)
+
+          issues = []
+          issues.concat(validate_header(font))
+          issues.concat(validate_face_offsets(font))
+          issues
+        end
+
+        def self.code
+          :collection_integrity
+        end
+
+        def self.collection?(font)
+          font.is_a?(BaseCollection)
+        end
+        private_class_method :collection?
+
+        def self.validate_header(collection)
+          issues = []
+          tag = collection.tag.to_s
+
+          if tag != TTC_TAG
+            issues << issue(severity: :error,
+                            message: "Collection tag is '#{tag}' but must be '#{TTC_TAG}'",
+                            location: "ttc_header.tag")
+          end
+
+          version = collection.major_version.to_i
+          unless VALID_MAJOR_VERSIONS.include?(version)
+            issues << issue(severity: :error,
+                            message: "Collection major version is #{version} " \
+                                     "but must be one of #{VALID_MAJOR_VERSIONS.join(', ')}",
+                            location: "ttc_header.majorVersion")
+          end
+
+          num_fonts = collection.num_fonts.to_i
+          if num_fonts <= 0
+            issues << issue(severity: :error,
+                            message: "Collection numFonts is #{num_fonts} " \
+                                     "but must be positive",
+                            location: "ttc_header.numFonts")
+          end
+
+          if collection.font_offsets.length != num_fonts
+            issues << issue(severity: :error,
+                            message: "Collection has #{num_fonts} fonts but " \
+                                     "#{collection.font_offsets.length} offsets " \
+                                     "(should match)",
+                            location: "ttc_header.font_offsets")
+          end
+
+          issues
+        end
+        private_class_method :validate_header
+
+        def self.validate_face_offsets(collection)
+          header_end = 12 + (collection.num_fonts.to_i * 4) +
+            (collection.major_version.to_i == 2 ? 8 : 0)
+          collection.font_offsets.each_with_index.with_object([]) do |(off, idx), issues|
+            off_val = off.to_i
+            if off_val < header_end
+              issues << issue(severity: :error,
+                              message: "Face #{idx} SFNT offset #{off_val} " \
+                                       "overlaps the TTC header " \
+                                       "(header ends at #{header_end})",
+                              location: "ttc_header.font_offsets.#{idx}")
+            end
+          end
+        end
+        private_class_method :validate_face_offsets
+      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/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