fontisan 0.4.34 → 0.4.35

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c278ba38670bfc65e41805d14d6bc175ae451f0e5400e4b25036bf3ae6a84f6
-  data.tar.gz: 59ec85b42b6879f589c13429e8e490a41eb32257530207647203c010ee461182
+  metadata.gz: c534e6da296ea563119e164f40835bf5e794d0c7d37d4fdcd2c0e31008925410
+  data.tar.gz: be05402a2e893896e744432950d1f1e8951a59004f76ca9aacd2a9353f8d54cd
 SHA512:
-  metadata.gz: 17b9aeaeeb0589379b2ff65413aabb3db15c4d0dd323bd4891e4863a9dca2fdb7190fd795ebcd62fa16d6d570e7f7bb50c740b9947c0b42a5e673380e0164cd2
-  data.tar.gz: c9b35dd44d43fc634b1bf07aa84d2bd99527e4695636424cbf46aca757615b09d6dc27f3512e701ab8676d1111f51f980dd97d0d0fd82c47f4177592f9b94c95
+  metadata.gz: 2e77ac651176f1d4b42d24ac60d41d3b371ac548438bc373b9d5f1ce44b36f187050ce9e5e5b5385cfc83732e2e40d946cfb9d3ae2ac83ad9c82a20a8cc7fc5b
+  data.tar.gz: 903c46cd5ab5631f3ae6723bdee6f6df007c0351291e1a60856da0328ddcadbedc9a21ba68717d5db5d77031bd3b5bf69a003d08e33a8654302ae72eb122c7a4

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-07-11 04:55:54 UTC using RuboCop version 1.86.1.
+# on 2026-07-11 07:11:58 UTC using RuboCop version 1.86.1.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -32,20 +32,13 @@ Layout/IndentationWidth:
     - 'lib/fontisan/commands/audit_command.rb'
     - 'lib/fontisan/ufo/compile/glyf_loca.rb'
 
-# Offense count: 1969
+# Offense count: 2030
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
 Layout/LineLength:
   Enabled: false
 
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowInHeredoc.
-Layout/TrailingWhitespace:
-  Exclude:
-    - 'lib/fontisan/commands/audit_command.rb'
-
 # Offense count: 2
 Lint/CopDirectiveSyntax:
   Exclude:
@@ -118,7 +111,7 @@ Lint/UselessConstantScoping:
     - 'lib/fontisan/conversion_options.rb'
     - 'lib/fontisan/type1/charstrings.rb'
 
-# Offense count: 752
+# Offense count: 762
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Enabled: false
@@ -141,12 +134,12 @@ Metrics/CollectionLiteralLength:
     - 'lib/fontisan/type1/agl.rb'
     - 'lib/fontisan/type1/encodings.rb'
 
-# Offense count: 375
+# Offense count: 379
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Enabled: false
 
-# Offense count: 1019
+# Offense count: 1034
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 135
@@ -157,7 +150,7 @@ Metrics/ParameterLists:
   Max: 39
   MaxOptionalParameters: 4
 
-# Offense count: 289
+# Offense count: 291
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Enabled: false
@@ -228,7 +221,7 @@ RSpec/AnyInstance:
 RSpec/ContextWording:
   Enabled: false
 
-# Offense count: 40
+# Offense count: 41
 # Configuration parameters: IgnoredMetadata.
 RSpec/DescribeClass:
   Enabled: false
@@ -244,7 +237,7 @@ RSpec/DescribeMethod:
     - 'spec/fontisan/type1/seac_expander_spec.rb'
     - 'spec/fontisan/type1_real_fonts_spec.rb'
 
-# Offense count: 1726
+# Offense count: 1727
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 66
@@ -322,7 +315,7 @@ RSpec/MultipleDescribes:
     - 'spec/fontisan/utils/thread_pool_spec.rb'
     - 'spec/fontisan/variation/cache_spec.rb'
 
-# Offense count: 2149
+# Offense count: 2151
 RSpec/MultipleExpectations:
   Max: 19
 

data/TODO.improvements/README.md

@@ -11,7 +11,7 @@ Each file is `NN-short-name.md` where `NN` is the priority order.
 - [x] ~~[15 — CFF/CFF2 subsetter strategy](15-cff-cff2-subsetter-strategy.md)~~ ✓ Done — CFF via UFO round-trip, CFF2 via standalone INDEX filter with VStore preservation
 
 ### P1 — High-value features
-- [x] ~~[03 — `fontisan audit` command (identity+style+features lens)](03-fontisan-audit-command.md)~~ ✓ Done (Phase 1: identity, style, coverage, OpenType layout, provenance; CLI `fontisan audit` with YAML/JSON output)
+- [x] ~~[03 — `fontisan audit` command (identity+style+features lens)](03-fontisan-audit-command.md)~~ ✓ Done (Phase 1: identity, style, coverage, layout, provenance; Phase 2 axes: table directory validation, glyph name validation, cmap validation, OTS compatibility predictor, collection integrity; CLI `fontisan audit --validate` with profiles: default, structural, ots, layout)
 - [x] ~~[04 — UFO composite glyph encoding](04-ufo-composite-glyph-encoding.md)~~ ✓ Done
 - [x] ~~[05 — OTF compiler real CFF charstrings](05-otf-compiler-real-cff.md)~~ ✓ Already working (discovered in PR #117 — Cff.build produces real Type 2 charstrings; stale TODO marker removed)
 

data/lib/fontisan/audit/check.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Fontisan
+  module Audit
+    # Abstract base for all audit checks. A check is a stateless
+    # function that examines a loaded font and returns an Array of
+    # {Models::ValidationReport::Issue} records. An empty array means
+    # the font passed the check.
+    #
+    # Subclasses MUST override {.call} and {.code}.
+    #
+    # Checks are intentionally stateless + side-effect free so they
+    # can be composed, run in parallel, and tested in isolation.
+    class Check
+      # Run the check against +font+.
+      #
+      # @param font [SfntFont, BaseCollection]
+      # @return [Array<Models::ValidationReport::Issue>]
+      def self.call(font)
+        raise NotImplementedError,
+              "#{name} must override .call(font) -> Array<Issue>"
+      end
+
+      # Unique short identifier for this check (e.g. :table_checksum).
+      # Used as the issue +category+ for programmatic filtering.
+      #
+      # @return [Symbol]
+      def self.code
+        raise NotImplementedError,
+              "#{name} must override .code -> Symbol"
+      end
+
+      # Build an issue. Centralizes the category so callers don't repeat it.
+      # @return [Models::ValidationReport::Issue]
+      def self.issue(severity:, message:, location: nil)
+        Models::ValidationReport::Issue.new(
+          severity: severity.to_s,
+          category: code.to_s,
+          message: message,
+          location: location,
+        )
+      end
+    end
+  end
+end

data/lib/fontisan/audit/check_registry.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Audit
+    # Central registry of audit checks. A profile is a named subset of
+    # checks (e.g. +:ots+, +:structural+). The +:default+ profile runs
+    # every registered check.
+    #
+    # Profiles let callers opt into specific validation axes without
+    # running everything — e.g. +fontisan audit font.ttf --validate ots+
+    # runs only the OTS compatibility check.
+    #
+    # @example Run all checks
+    #   CheckRegistry.for(:default)  # => [TableDirectoryCheck, ...]
+    #
+    # @example Run a specific profile
+    #   CheckRegistry.for(:ots)      # => [OtsCompatibilityCheck]
+    class CheckRegistry
+      PROFILES = {
+        default: %i[table_directory glyph_names cmap ots_compatibility
+                    collection_integrity],
+        structural: %i[table_directory collection_integrity],
+        ots: %i[ots_compatibility],
+        layout: %i[glyph_names cmap],
+      }.freeze
+
+      # @param profile [Symbol]
+      # @return [Array<Class>] check classes for the profile
+      def self.for(profile)
+        codes = PROFILES[profile] || PROFILES[:default]
+        codes.filter_map { |code| check_for(code) }
+      end
+
+      # @param code [Symbol]
+      # @return [Class, nil] the check class
+      def self.check_for(code)
+        case code
+        when :table_directory then Checks::TableDirectoryCheck
+        when :glyph_names then Checks::GlyphNameCheck
+        when :cmap then Checks::CmapCheck
+        when :ots_compatibility then Checks::OtsCompatibilityCheck
+        when :collection_integrity then Checks::CollectionIntegrityCheck
+        end
+      end
+    end
+  end
+end

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

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.rb

@@ -0,0 +1,22 @@
+# 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"
+    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

data/lib/fontisan/cli.rb

@@ -38,10 +38,14 @@ module Fontisan
                            desc: "Omit the codepoint list from the report"
     option :font_index, type: :numeric, default: nil,
                         desc: "Audit only the given face of a collection"
+    option :validate, type: :string, default: nil,
+                      desc: "Run validation checks. Use 'true' for all, or a " \
+                            "profile name: default, structural, ots, layout"
     # Produce a structured font audit report (YAML or JSON).
     def audit(font_file)
       cmd_options = options.dup
       cmd_options[:include_codepoints] = !options[:no_codepoints]
+      cmd_options[:validate] = parse_validate_option(options[:validate])
       command = Commands::AuditCommand.new(font_file, cmd_options)
       result = command.run
       write_audit_result(result, options[:output])
@@ -797,6 +801,15 @@ module Fontisan
       format("%<idx>02d-%<name>s.%<suffix>s", idx: idx, name: safe_name, suffix: suffix)
     end
 
+    # The --validate option is either nil (no validation), "true" (run all
+    # checks), or a profile name (e.g. "ots", "structural").
+    def parse_validate_option(raw)
+      return nil if raw.nil? || raw.empty?
+      return true if raw == "true"
+
+      raw.to_sym
+    end
+
     def serialize_report(report, format)
       format == :json ? report.to_json : report.to_yaml
     end

data/lib/fontisan/commands/audit_command.rb

@@ -75,6 +75,7 @@ module Fontisan
           populate_style(r, face)
           populate_coverage(r, face)
           populate_layout(r, face)
+          populate_validation(r, face) if validate?
         end
       end
 
@@ -246,11 +247,44 @@ module Fontisan
       end
 
       def features_for_script(layout_table, script)
-        
           layout_table.features(script_tag: script)
       rescue StandardError
           []
-        
+      end
+
+      # ------------------------------------------------------------------
+      # Validation (audit checks)
+      # ------------------------------------------------------------------
+
+      def populate_validation(report, face)
+        report.validation_issues = run_validation_checks(face)
+      end
+
+      def run_validation_checks(face)
+        checks = Audit::CheckRegistry.for(validation_profile)
+        checks.flat_map { |check| safe_run_check(check, face) }
+      end
+
+      def safe_run_check(check, face)
+        check.call(face)
+      rescue StandardError => e
+        [Models::ValidationReport::Issue.new(
+          severity: "fatal",
+          category: check.code.to_s,
+          message: "Check #{check.code} failed to execute: #{e.class}: #{e.message}",
+          location: nil,
+        )]
+      end
+
+      def validate?
+        @options.fetch(:validate, false)
+      end
+
+      def validation_profile
+        profile = @options[:validate]
+        return :default if profile == true
+
+        profile&.to_sym || :default
       end
     end
   end

data/lib/fontisan/models/audit_report.rb

@@ -73,6 +73,9 @@ module Fontisan
       attribute :opentype_scripts, :string, collection: true
       attribute :features, :string, collection: true
 
+      # Validation (populated only with --validate)
+      attribute :validation_issues, Models::ValidationReport::Issue, collection: true
+
       json do
         map "generated_at", to: :generated_at
         map "fontisan_version", to: :fontisan_version
@@ -104,6 +107,7 @@ module Fontisan
 
         map "opentype_scripts", to: :opentype_scripts
         map "features", to: :features
+        map "validation_issues", to: :validation_issues
       end
 
       yaml do
@@ -137,6 +141,7 @@ module Fontisan
 
         map "opentype_scripts", to: :opentype_scripts
         map "features", to: :features
+        map "validation_issues", to: :validation_issues
       end
     end
   end

data/lib/fontisan/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Fontisan
-  VERSION = "0.4.34"
+  VERSION = "0.4.35"
 end

data/lib/fontisan.rb

@@ -77,6 +77,7 @@ module Fontisan
 
   # Namespace hubs (each hub declares its own child autoloads)
   autoload :Binary, "fontisan/binary"
+  autoload :Audit, "fontisan/audit"
   autoload :Collection, "fontisan/collection"
   autoload :Commands, "fontisan/commands"
   autoload :Converters, "fontisan/converters"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fontisan
 version: !ruby/object:Gem::Version
-  version: 0.4.34
+  version: 0.4.35
 platform: ruby
 authors:
 - Ribose Inc.
@@ -293,6 +293,15 @@ files:
 - exe/fontisan
 - fontisan.gemspec
 - lib/fontisan.rb
+- lib/fontisan/audit.rb
+- lib/fontisan/audit/check.rb
+- lib/fontisan/audit/check_registry.rb
+- lib/fontisan/audit/checks.rb
+- lib/fontisan/audit/checks/cmap_check.rb
+- lib/fontisan/audit/checks/collection_integrity_check.rb
+- lib/fontisan/audit/checks/glyph_name_check.rb
+- lib/fontisan/audit/checks/ots_compatibility_check.rb
+- lib/fontisan/audit/checks/table_directory_check.rb
 - lib/fontisan/base_collection.rb
 - lib/fontisan/binary.rb
 - lib/fontisan/binary/base_record.rb