fontisan 0.4.35 → 0.4.37

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c534e6da296ea563119e164f40835bf5e794d0c7d37d4fdcd2c0e31008925410
-  data.tar.gz: be05402a2e893896e744432950d1f1e8951a59004f76ca9aacd2a9353f8d54cd
+  metadata.gz: 615c64e2005d769c01c4b7a5cd153630b42f5230c55a0242f892aaec65618320
+  data.tar.gz: deca6b51aba40a45b2150290fe5ef0bd94b935f4fd09c54da54e65bf8cde3194
 SHA512:
-  metadata.gz: 2e77ac651176f1d4b42d24ac60d41d3b371ac548438bc373b9d5f1ce44b36f187050ce9e5e5b5385cfc83732e2e40d946cfb9d3ae2ac83ad9c82a20a8cc7fc5b
-  data.tar.gz: 903c46cd5ab5631f3ae6723bdee6f6df007c0351291e1a60856da0328ddcadbedc9a21ba68717d5db5d77031bd3b5bf69a003d08e33a8654302ae72eb122c7a4
+  metadata.gz: dc66734c722fd5fc959d80c95f41b701ecb7679926e85d6bbf09f9aab84c5ea96eb94f558ee241f40b88c999f21a811d9d45a306f35ec7b5cc61b188c053851e
+  data.tar.gz: 6ceebcf686badd81a1d934f8f2d03b607f29522bef598e85cd363c33d16a94f9df6d3fd048ebce38dfce103e5dc55efb7df6cbd55016220e564e4ca833490dd8

data/.rubocop.yml

@@ -116,7 +116,19 @@ Style/BitwisePredicate:
   Enabled: false
 
 # Allow short math-conventional parameter names in font geometry code.
-# Point#x / Point#y are domain-standard coordinate names; renaming to
-# x_coord/y_coord adds noise without aiding readers.
+# Font geometry / binary parsing uses single-letter variables by domain
+# convention: affine matrix (a,b,c,d,e,f), loop indices (i,j,k,m,n),
+# coordinates (x,y,z), deltas (dx,dy). Renaming to 3+ chars adds noise
+# without aiding readers familiar with the math.
 Naming/MethodParameterName:
-  AllowedNames: ["x", "y", "cp", "gid", "n"]
+  AllowedNames: ["a", "b", "c", "d", "e", "f", "i", "j", "k", "m", "n",
+                 "p", "r", "s", "t", "u", "v", "w", "x", "y", "z",
+                 "cp", "gid", "dx", "dy", "fd", "io", "id"]
+
+# Allow spec-format identifiers that match OpenType spec terminology:
+# cmap format4, format6, format12, format14 are the official names.
+# Renaming to format_4 diverges from the spec and makes docs harder
+# to cross-reference.
+Naming/VariableNumber:
+  AllowedIdentifiers: ["format0", "format4", "format6", "format12", "format14",
+                        "version1", "version2", "table1", "table2"]

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-07-11 07:11:58 UTC using RuboCop version 1.86.1.
+# on 2026-07-11 08:52:22 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,7 +32,7 @@ Layout/IndentationWidth:
     - 'lib/fontisan/commands/audit_command.rb'
     - 'lib/fontisan/ufo/compile/glyf_loca.rb'
 
-# Offense count: 2030
+# Offense count: 2053
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
@@ -111,7 +111,7 @@ Lint/UselessConstantScoping:
     - 'lib/fontisan/conversion_options.rb'
     - 'lib/fontisan/type1/charstrings.rb'
 
-# Offense count: 762
+# Offense count: 766
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Enabled: false
@@ -134,12 +134,12 @@ Metrics/CollectionLiteralLength:
     - 'lib/fontisan/type1/agl.rb'
     - 'lib/fontisan/type1/encodings.rb'
 
-# Offense count: 379
+# Offense count: 383
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Enabled: false
 
-# Offense count: 1034
+# Offense count: 1045
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 135
@@ -150,16 +150,28 @@ Metrics/ParameterLists:
   Max: 39
   MaxOptionalParameters: 4
 
-# Offense count: 291
+# Offense count: 294
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Enabled: false
 
-# Offense count: 209
+# Offense count: 34
 # Configuration parameters: MinNameLength, AllowNamesEndingInNumbers, AllowedNames, ForbiddenNames.
 # AllowedNames: as, at, by, cc, db, id, if, in, io, ip, of, on, os, pp, to
 Naming/MethodParameterName:
-  Enabled: false
+  Exclude:
+    - 'lib/fontisan.rb'
+    - 'lib/fontisan/conversion_options.rb'
+    - 'lib/fontisan/optimizers/subroutine_optimizer.rb'
+    - 'lib/fontisan/svg_to_glyf/geometry/affine_transform.rb'
+    - 'lib/fontisan/svg_to_glyf/geometry/transform_parser.rb'
+    - 'lib/fontisan/type1/ttf_to_type1_converter.rb'
+    - 'lib/fontisan/ufo/compile/filters/cubic_to_quadratic.rb'
+    - 'lib/fontisan/ufo/convert.rb'
+    - 'lib/fontisan/variation/optimizer.rb'
+    - 'lib/fontisan/woff2/glyf_loca_reconstruct.rb'
+    - 'lib/fontisan/woff2/glyf_loca_transform.rb'
+    - 'spec/fontisan/subset/table_strategy/cff2_spec.rb'
 
 # Offense count: 13
 # Configuration parameters: Mode, AllowedMethods, AllowedPatterns, AllowBangMethods, WaywardPredicates.
@@ -221,7 +233,7 @@ RSpec/AnyInstance:
 RSpec/ContextWording:
   Enabled: false
 
-# Offense count: 41
+# Offense count: 42
 # Configuration parameters: IgnoredMetadata.
 RSpec/DescribeClass:
   Enabled: false
@@ -237,7 +249,7 @@ RSpec/DescribeMethod:
     - 'spec/fontisan/type1/seac_expander_spec.rb'
     - 'spec/fontisan/type1_real_fonts_spec.rb'
 
-# Offense count: 1727
+# Offense count: 1729
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 66
@@ -315,7 +327,7 @@ RSpec/MultipleDescribes:
     - 'spec/fontisan/utils/thread_pool_spec.rb'
     - 'spec/fontisan/variation/cache_spec.rb'
 
-# Offense count: 2151
+# Offense count: 2153
 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, 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] ~~[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, glyph names, cmap, OTS, collection integrity; Phase 3 axes: variable-font, hinting, WOFF2, format-round-trip; Phase 3 axis 14 (full OT conformance): cross-table conformance + per-table checks for head, hhea, maxp, OS/2, name, post, kern; CLI `fontisan audit --validate` with profiles: default (17 checks), structural, ots, layout, variable, hinting, web, spec, per_table)
 - [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_registry.rb

@@ -16,12 +16,24 @@ module Fontisan
     # @example Run a specific profile
     #   CheckRegistry.for(:ots)      # => [OtsCompatibilityCheck]
     class CheckRegistry
+      # Per-table OT conformance checks (axis 14 — full OT spec coverage).
+      OT_TABLE_CHECKS = %i[ot_head ot_hhea ot_maxp ot_os2 ot_name ot_post
+                           ot_kern].freeze
+
       PROFILES = {
         default: %i[table_directory glyph_names cmap ots_compatibility
-                    collection_integrity],
-        structural: %i[table_directory collection_integrity],
+                    collection_integrity variable_font hinting woff2_validation
+                    format_round_trip opentype_conformance
+                    ot_head ot_hhea ot_maxp ot_os2 ot_name ot_post ot_kern],
+        structural: %i[table_directory collection_integrity opentype_conformance],
         ots: %i[ots_compatibility],
         layout: %i[glyph_names cmap],
+        variable: %i[variable_font],
+        hinting: %i[hinting],
+        web: %i[ots_compatibility woff2_validation],
+        spec: %i[opentype_conformance ot_head ot_hhea ot_maxp ot_os2
+                 ot_name ot_post ot_kern],
+        per_table: OT_TABLE_CHECKS,
       }.freeze
 
       # @param profile [Symbol]
@@ -40,6 +52,18 @@ module Fontisan
         when :cmap then Checks::CmapCheck
         when :ots_compatibility then Checks::OtsCompatibilityCheck
         when :collection_integrity then Checks::CollectionIntegrityCheck
+        when :variable_font then Checks::VariableFontCheck
+        when :hinting then Checks::HintingCheck
+        when :woff2_validation then Checks::Woff2ValidationCheck
+        when :format_round_trip then Checks::FormatRoundTripCheck
+        when :opentype_conformance then Checks::OpenTypeConformanceCheck
+        when :ot_head then Checks::HeadCheck
+        when :ot_hhea then Checks::HheaCheck
+        when :ot_maxp then Checks::MaxpCheck
+        when :ot_os2 then Checks::Os2Check
+        when :ot_name then Checks::NameTableCheck
+        when :ot_post then Checks::PostCheck
+        when :ot_kern then Checks::KernCheck
         end
       end
     end

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

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

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

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Audit
+    module Checks
+      # Validates the 'head' table per the OpenType spec.
+      #
+      # @see https://learn.microsoft.com/en-us/typography/opentype/spec/head
+      class HeadCheck < Check
+        HEAD_MAGIC = 0x5F0F3CF5
+        MIN_UPM = 16
+        MAX_UPM = 16_384
+        MAC_STYLE_DEFINED_BITS = 0x00FF
+        MAC_STYLE_RESERVED_BITS = 0xFF00
+
+        def self.call(font)
+          return [] unless font.has_table?("head")
+
+          head = font.table("head")
+          issues = []
+          issues.concat(validate_magic(head))
+          issues.concat(validate_upm(head))
+          issues.concat(validate_loc_format(head))
+          issues.concat(validate_dates(head))
+          issues.concat(validate_mac_style(head))
+          issues
+        end
+
+        def self.code
+          :ot_head
+        end
+
+        def self.validate_magic(head)
+          return [] if head.magic_number == HEAD_MAGIC
+
+          [issue(severity: :error,
+                 message: "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
+        private_class_method :validate_magic
+
+        def self.validate_upm(head)
+          upm = head.units_per_em.to_i
+          return [] if upm.between?(MIN_UPM, MAX_UPM)
+
+          [issue(severity: :error,
+                 message: "head.unitsPerEm is #{upm} but must be between " \
+                          "#{MIN_UPM} and #{MAX_UPM}",
+                 location: "head.units_per_em")]
+        end
+        private_class_method :validate_upm
+
+        def self.validate_loc_format(head)
+          fmt = head.index_to_loc_format.to_i
+          return [] if [0, 1].include?(fmt)
+
+          [issue(severity: :error,
+                 message: "head.indexToLocFormat is #{fmt} but must be 0 " \
+                          "(short) or 1 (long)",
+                 location: "head.index_to_loc_format")]
+        end
+        private_class_method :validate_loc_format
+
+        def self.validate_dates(head)
+          issues = []
+          if head.created_raw.to_i.zero?
+            issues << issue(severity: :info,
+                            message: "head.created is 0 — creation date not set",
+                            location: "head.created")
+          end
+          if head.modified_raw.to_i.zero?
+            issues << issue(severity: :info,
+                            message: "head.modified is 0 — modification date not set",
+                            location: "head.modified")
+          end
+          issues
+        end
+        private_class_method :validate_dates
+
+        def self.validate_mac_style(head)
+          style = head.mac_style.to_i
+          issues = []
+          unless (style & MAC_STYLE_RESERVED_BITS).zero?
+            issues << issue(severity: :warning,
+                            message: "head.macStyle uses reserved bits " \
+                                     "(0x#{style.to_s(16)}, bits 8-15 must be 0)",
+                            location: "head.mac_style")
+          end
+          issues
+        end
+        private_class_method :validate_mac_style
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Audit
+    module Checks
+      # Validates the 'hhea' table per the OpenType spec.
+      #
+      # @see https://learn.microsoft.com/en-us/typography/opentype/spec/hhea
+      class HheaCheck < Check
+        def self.call(font)
+          return [] unless font.has_table?("hhea")
+
+          hhea = font.table("hhea")
+          issues = []
+          issues.concat(validate_ascent(hhea))
+          issues.concat(validate_descent(hhea))
+          issues.concat(validate_line_gap(hhea))
+          issues.concat(validate_advance_width_max(hhea))
+          issues
+        end
+
+        def self.code
+          :ot_hhea
+        end
+
+        def self.validate_ascent(hhea)
+          return [] if hhea.ascent.to_i.positive?
+
+          [issue(severity: :warning,
+                 message: "hhea.ascent is #{hhea.ascent} but should be positive " \
+                          "(ascender typically rises above the baseline)",
+                 location: "hhea.ascent")]
+        end
+        private_class_method :validate_ascent
+
+        def self.validate_descent(hhea)
+          return [] if hhea.descent.to_i <= 0
+
+          [issue(severity: :warning,
+                 message: "hhea.descent is #{hhea.descent} but should be ≤ 0 " \
+                          "(descender typically falls below the baseline)",
+                 location: "hhea.descent")]
+        end
+        private_class_method :validate_descent
+
+        def self.validate_line_gap(hhea)
+          return [] if hhea.line_gap.to_i >= 0
+
+          [issue(severity: :info,
+                 message: "hhea.lineGap is #{hhea.line_gap} — negative line " \
+                          "gap is unusual but not spec-prohibited",
+                 location: "hhea.line_gap")]
+        end
+        private_class_method :validate_line_gap
+
+        def self.validate_advance_width_max(hhea)
+          return [] unless hhea.advance_width_max.to_i <= 0
+
+          [issue(severity: :warning,
+                 message: "hhea.advanceWidthMax is #{hhea.advance_width_max} " \
+                          "but should be positive (the widest glyph advance)",
+                 location: "hhea.advance_width_max")]
+        end
+        private_class_method :validate_advance_width_max
+      end
+    end
+  end
+end

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

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