fontisan 0.2.17 → 0.2.22

data/lib/fontisan/audit/extractors/hinting.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+module Fontisan
+  module Audit
+    module Extractors
+      # Hinting summary: TrueType bytecode counts + gasp policy + CFF stem
+      # count, with derived `is_unhinted` and `hinting_format` fields.
+      #
+      # Returned fields:
+      #   hinting: Models::Audit::Hinting instance, or nil for Type 1
+      #
+      # The fpgm/prep/cvt/gasp tables have no BinData classes yet — they
+      # are read as raw bytes from `font.table_data`. Bytecode is one byte
+      # per instruction; cvt is an array of FWord (int16), so the entry
+      # count is bytesize / 2.
+      class Hinting < Base
+        # Raw CFF2 / CFF2 charstring operator bytes that declare stem hints.
+        HSTEM    = 1
+        VSTEM    = 3
+        HSTEMHM  = 18
+        VSTEMHM  = 23
+        HINTMASK = 19
+        CNTRMASK = 20
+
+        def extract(context)
+          font = context.font
+          return { hinting: nil } unless sfnt?(font)
+
+          { hinting: Models::Audit::Hinting.new(**gather(font)) }
+        end
+
+        protected
+
+        def sfnt?(font)
+          font.is_a?(SfntFont)
+        end
+
+        private
+
+        def gather(font)
+          tt = truetype_fields(font)
+          cff = cff_fields(font)
+          gasp = parse_gasp(font)
+
+          derived = Models::Audit::Hinting.derive_flags(
+            has_tt: tt[:has_fpgm] || tt[:has_prep] || tt[:has_cvt],
+            has_cff: cff[:cff_has_private_dict],
+            has_gasp: !gasp.empty?,
+          )
+
+          tt.merge(cff).merge(gasp_ranges: gasp).merge(derived)
+        end
+
+        def truetype_fields(font)
+          {
+            has_fpgm: font.has_table?(Constants::FPGM_TAG),
+            fpgm_instruction_count: byte_count(font, Constants::FPGM_TAG),
+            has_prep: font.has_table?(Constants::PREP_TAG),
+            prep_instruction_count: byte_count(font, Constants::PREP_TAG),
+            has_cvt: font.has_table?(Constants::CVT_TAG),
+            cvt_entry_count: cvt_entry_count(font),
+            has_cvar: font.has_table?(Constants::CVAR_TAG),
+          }
+        end
+
+        def cff_fields(font)
+          has_cff1 = font.has_table?(Constants::CFF_TAG)
+          has_cff2 = font.has_table?(Constants::CFF2_TAG)
+          has_private = has_cff1 || has_cff2
+
+          {
+            cff_has_private_dict: has_private,
+            cff_hint_count: has_cff1 ? count_cff_stems(font) : nil,
+          }
+        end
+
+        def byte_count(font, tag)
+          return nil unless font.has_table?(tag)
+
+          font.table_data[tag]&.bytesize
+        end
+
+        def cvt_entry_count(font)
+          return nil unless font.has_table?(Constants::CVT_TAG)
+
+          bytes = font.table_data[Constants::CVT_TAG]
+          return nil unless bytes
+
+          bytes.bytesize / 2
+        end
+
+        # Parse the gasp table from raw bytes. Format: uint16 version,
+        # uint16 numRanges, then numRanges × (uint16 rangeMaxPPEM,
+        # uint16 rangeFlags). Returns [] if gasp is absent or truncated.
+        def parse_gasp(font)
+          return [] unless font.has_table?(Constants::GASP_TAG)
+
+          data = font.table_data[Constants::GASP_TAG]
+          return [] unless data && data.bytesize >= 4
+
+          _version, num_ranges = data.unpack("nn")
+          ranges = []
+          offset = 4
+          num_ranges.times do
+            break if offset + 4 > data.bytesize
+
+            max_ppem, flags = data[offset, 4].unpack("nn")
+            ranges << Models::Audit::GaspRange.from_flags(max_ppem, flags)
+            offset += 4
+          end
+          ranges
+        end
+
+        def count_cff_stems(font)
+          return nil unless font.has_table?(Constants::CFF_TAG)
+
+          cff = font.table(Constants::CFF_TAG)
+          return nil unless cff
+
+          index = cff.charstrings_index(0)
+          return nil unless index
+
+          total = 0
+          index.count.times do |glyph_index|
+            data = index[glyph_index]
+            next unless data
+
+            total += count_stems_in_charstring(data)
+          end
+          total
+        rescue CorruptedTableError
+          nil
+        end
+
+        # Lightweight Type-2 CharString scanner that counts stem hints
+        # without instantiating a full CharString (which needs a Private
+        # DICT, global/local subrs, etc.). Operates purely on bytes.
+        def count_stems_in_charstring(data)
+          io = StringIO.new(data)
+          stack = 0
+          stems = 0
+
+          until io.eof?
+            byte = io.getbyte
+            next if byte.nil?
+
+            stack, stems = process_byte(io, byte, stack, stems)
+          end
+
+          stems
+        end
+
+        def process_byte(io, byte, stack, stems)
+          if operator_byte?(byte)
+            apply_operator(io, byte, stack, stems)
+          else
+            [consume_operand(io, byte, stack), stems]
+          end
+        end
+
+        def operator_byte?(byte)
+          byte <= 31 && byte != 28
+        end
+
+        def apply_operator(io, byte, stack, stems)
+          case byte
+          when 12
+            io.getbyte
+            [0, stems]
+          when HSTEM, VSTEM, HSTEMHM, VSTEMHM
+            [0, stems + stack / 2]
+          when HINTMASK, CNTRMASK
+            new_stems = stems + stack / 2
+            io.read((new_stems + 7) / 8)
+            [0, new_stems]
+          else
+            [0, stems]
+          end
+        end
+
+        def consume_operand(io, byte, stack)
+          case byte
+          when 28
+            io.read(2)
+          when 255
+            io.read(4)
+          when 247..254
+            io.getbyte
+          end
+          stack + 1
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/audit/extractors/identity.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Audit
+    module Extractors
+      # Identity fields: the human-readable names a font uses to describe
+      # itself, drawn from the `name` table (SFNT) or font dictionary
+      # (Type 1).
+      #
+      # Returned fields:
+      #   family_name, subfamily_name, full_name, postscript_name,
+      #   version, font_revision
+      class Identity < Base
+        def extract(context)
+          if context.font.is_a?(Type1Font)
+            type1_identity(context.font)
+          else
+            sfnt_identity(context.font)
+          end
+        end
+
+        private
+
+        def sfnt_identity(font)
+          name_table = font.table(Constants::NAME_TAG) if font.has_table?(Constants::NAME_TAG)
+          head_table = font.table(Constants::HEAD_TAG) if font.has_table?(Constants::HEAD_TAG)
+
+          {
+            family_name: name_table&.english_name(Tables::Name::FAMILY),
+            subfamily_name: name_table&.english_name(Tables::Name::SUBFAMILY),
+            full_name: name_table&.english_name(Tables::Name::FULL_NAME),
+            postscript_name: name_table&.english_name(Tables::Name::POSTSCRIPT_NAME),
+            version: name_table&.english_name(Tables::Name::VERSION),
+            font_revision: head_table&.font_revision,
+          }
+        end
+
+        def type1_identity(font)
+          font_info = font.font_dictionary&.font_info
+          {
+            family_name: font_info&.family_name,
+            subfamily_name: nil,
+            full_name: font_info&.full_name,
+            postscript_name: font.font_name,
+            version: font_info&.version,
+            font_revision: nil,
+          }
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/audit/extractors/language_coverage.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Audit
+    module Extractors
+      # Per-language CLDR coverage for one face.
+      #
+      # Returned fields:
+      #   language_coverage, cldr_version
+      #
+      # Opt-in only — `--with-language-coverage`. When off, Context#cldr
+      # returns nil and this extractor emits an empty array + nil version.
+      # MECE: this extractor is CLDR-driven; UCD block/script coverage
+      # lives in {Extractors::Aggregations}.
+      class LanguageCoverage < Base
+        def extract(context)
+          cldr = context.cldr
+          return empty(nil) if cldr.nil?
+
+          return empty(cldr[:version]) if cldr[:index].nil?
+
+          {
+            language_coverage: Cldr::Aggregator.aggregate(context.codepoints,
+                                                          cldr[:index]),
+            cldr_version: cldr[:version],
+          }
+        end
+
+        private
+
+        def empty(version)
+          { language_coverage: [], cldr_version: version }
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/audit/extractors/licensing.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Audit
+    module Extractors
+      # Licensing + embedding permissions + vendor provenance.
+      #
+      # Returned fields:
+      #   licensing: Models::Audit::Licensing instance, or nil for Type 1
+      #
+      # Type 1 fonts have no OS/2 table; their licensing is nil. WOFF/
+      # WOFF2 carry the same OS/2 + name tables as TTF/OTF and need no
+      # special handling.
+      class Licensing < Base
+        # nameID → AuditReport field name, per OpenType name table spec.
+        NAME_IDS = {
+          copyright: 0,
+          trademark: 7,
+          manufacturer: 8,
+          designer: 9,
+          description: 10,
+          vendor_url: 11,
+          designer_url: 12,
+          license_description: 13,
+          license_url: 14,
+        }.freeze
+        private_constant :NAME_IDS
+
+        def extract(context)
+          font = context.font
+          return { licensing: nil } unless sfnt?(font)
+
+          os2 = os2_for(font)
+          name = name_table_for(font)
+
+          {
+            licensing: Models::Audit::Licensing.new(
+              **name_fields(name),
+              vendor_id: sanitized_vendor_id(os2),
+              embedding_type: Models::Audit::EmbeddingType.decode(os2&.fs_type&.to_i),
+              fs_selection_flags: Models::Audit::FsSelectionFlags.decode(os2&.fs_selection&.to_i),
+            ),
+          }
+        end
+
+        private
+
+        def sfnt?(font)
+          font.is_a?(SfntFont)
+        end
+
+        def os2_for(font)
+          return nil unless font.has_table?(Constants::OS2_TAG)
+
+          font.table(Constants::OS2_TAG)
+        end
+
+        def name_table_for(font)
+          return nil unless font.has_table?(Constants::NAME_TAG)
+
+          font.table(Constants::NAME_TAG)
+        end
+
+        def name_fields(name)
+          return {} unless name
+
+          NAME_IDS.transform_values { |id| name.english_name(id) }
+        end
+
+        def sanitized_vendor_id(os2)
+          raw = os2&.ach_vend_id
+          return nil if raw.nil?
+
+          raw.gsub(/[\x00\s]+$/, "")
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/audit/extractors/metrics.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Audit
+    module Extractors
+      # Layout-critical metrics consolidated from head, hhea, OS/2, post.
+      #
+      # Returned fields:
+      #   metrics: Models::Audit::Metrics instance, or nil for Type 1
+      #
+      # All table reads are nil-safe; tables may be absent in stripped
+      # WOFF builds or legacy formats.
+      class Metrics < Base
+        def extract(context)
+          font = context.font
+          return { metrics: nil } unless sfnt?(font)
+
+          { metrics: Models::Audit::Metrics.new(**gather(font)) }
+        end
+
+        private
+
+        def sfnt?(font)
+          font.is_a?(SfntFont)
+        end
+
+        def gather(font)
+          {}.tap do |h|
+            h.merge!(head_fields(font))
+            h.merge!(hhea_fields(font))
+            h.merge!(os2_fields(font))
+            h.merge!(post_fields(font))
+          end
+        end
+
+        def head_fields(font)
+          head = table(font, Constants::HEAD_TAG)
+          return {} unless head
+
+          {
+            units_per_em: head.units_per_em&.to_i,
+            bbox_x_min: head.x_min&.to_i,
+            bbox_y_min: head.y_min&.to_i,
+            bbox_x_max: head.x_max&.to_i,
+            bbox_y_max: head.y_max&.to_i,
+          }
+        end
+
+        def hhea_fields(font)
+          hhea = table(font, Constants::HHEA_TAG)
+          return {} unless hhea
+
+          {
+            hhea_ascent: hhea.ascent&.to_i,
+            hhea_descent: hhea.descent&.to_i,
+            hhea_line_gap: hhea.line_gap&.to_i,
+          }
+        end
+
+        def os2_fields(font)
+          os2 = table(font, Constants::OS2_TAG)
+          return {} unless os2
+
+          {
+            typo_ascender: os2.s_typo_ascender&.to_i,
+            typo_descender: os2.s_typo_descender&.to_i,
+            typo_line_gap: os2.s_typo_line_gap&.to_i,
+            win_ascent: os2.us_win_ascent&.to_i,
+            win_descent: os2.us_win_descent&.to_i,
+            x_height: os2.sx_height&.to_i,
+            cap_height: os2.s_cap_height&.to_i,
+            subscript_x_size: os2.y_subscript_x_size&.to_i,
+            subscript_y_size: os2.y_subscript_y_size&.to_i,
+            subscript_x_offset: os2.y_subscript_x_offset&.to_i,
+            subscript_y_offset: os2.y_subscript_y_offset&.to_i,
+            superscript_x_size: os2.y_superscript_x_size&.to_i,
+            superscript_y_size: os2.y_superscript_y_size&.to_i,
+            superscript_x_offset: os2.y_superscript_x_offset&.to_i,
+            superscript_y_offset: os2.y_superscript_y_offset&.to_i,
+            strikeout_size: os2.y_strikeout_size&.to_i,
+            strikeout_position: os2.y_strikeout_position&.to_i,
+          }
+        end
+
+        def post_fields(font)
+          post = table(font, Constants::POST_TAG)
+          return {} unless post
+
+          {
+            underline_position: post.underline_position&.to_f,
+            underline_thickness: post.underline_thickness&.to_f,
+          }
+        end
+
+        def table(font, tag)
+          return nil unless font.has_table?(tag)
+
+          font.table(tag)
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/audit/extractors/opentype_layout.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Audit
+    module Extractors
+      # OpenType layout summary: union of GSUB + GPOS scripts and features,
+      # plus a per-script breakdown preserving which feature belongs to
+      # which script under which table.
+      #
+      # Returned fields:
+      #   opentype_layout: Models::Audit::OpenTypeLayout, or nil for
+      #                    Type 1
+      #
+      # Owned here (MECE split from Aggregations, which is UCD-only).
+      class OpenTypeLayout < Base
+        def extract(context)
+          font = context.font
+          return { opentype_layout: nil } unless sfnt?(font)
+
+          gsub_scripts = scripts_in(font, Constants::GSUB_TAG)
+          gpos_scripts = scripts_in(font, Constants::GPOS_TAG)
+          all_scripts = (gsub_scripts + gpos_scripts).uniq.sort
+
+          by_script = all_scripts.map do |tag|
+            Models::Audit::ScriptFeatures.new(
+              script: tag,
+              gsub_features: features_for(font, Constants::GSUB_TAG, tag),
+              gpos_features: features_for(font, Constants::GPOS_TAG, tag),
+            )
+          end
+
+          { opentype_layout: Models::Audit::OpenTypeLayout.new(
+            scripts: all_scripts,
+            features: aggregate_features(by_script),
+            by_script: by_script,
+            has_gsub: font.has_table?(Constants::GSUB_TAG),
+            has_gpos: font.has_table?(Constants::GPOS_TAG),
+          ) }
+        end
+
+        protected
+
+        def sfnt?(font)
+          font.is_a?(SfntFont)
+        end
+
+        private
+
+        def scripts_in(font, tag)
+          return [] unless font.has_table?(tag)
+
+          font.table(tag).scripts
+        end
+
+        def features_for(font, tag, script)
+          return [] unless font.has_table?(tag)
+
+          font.table(tag).features(script_tag: script).sort
+        end
+
+        def aggregate_features(by_script)
+          gsub = by_script.flat_map(&:gsub_features)
+          gpos = by_script.flat_map(&:gpos_features)
+          (gsub + gpos).uniq.sort
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/audit/extractors/provenance.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "digest"
+require "time"
+
+module Fontisan
+  module Audit
+    module Extractors
+      # Provenance fields: who generated this report, when, from what.
+      #
+      # Returned fields:
+      #   generated_at, fontisan_version, source_file, source_sha256,
+      #   source_format, font_index, num_fonts_in_source
+      class Provenance < Base
+        def extract(context)
+          {
+            generated_at: Time.now.utc.iso8601,
+            fontisan_version: Fontisan::VERSION,
+            source_file: File.expand_path(context.font_path),
+            source_sha256: Digest::SHA256.file(context.font_path).hexdigest,
+            source_format: context.source_format,
+            font_index: context.font_index,
+            num_fonts_in_source: context.num_fonts_in_source,
+          }
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/audit/extractors/style.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Audit
+    module Extractors
+      # Style fields: weight, width, italic/bold flags, Panose family
+      # classification.
+      #
+      # Returned fields:
+      #   weight_class, width_class, italic, bold, panose
+      #
+      # Variable-font axis inventory lives in {Extractors::VariationDetail}
+      # (MECE: this extractor is the OS/2 + head specialist, that one owns
+      # everything fvar-derived).
+      #
+      # Delegates to {Audit::StyleExtractor} — the existing specialist
+      # class that owns the OS/2 + head interpretation rules.
+      class Style < Base
+        def extract(context)
+          style = StyleExtractor.new(context.font)
+          {
+            weight_class: style.weight_class,
+            width_class: style.width_class,
+            italic: style.italic,
+            bold: style.bold,
+            panose: style.panose,
+          }
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/audit/extractors/variation_detail.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Audit
+    module Extractors
+      # Variable-font detail: fvar axes + named instances + presence flags
+      # for every variation side-table (avar, cvar, HVAR, VVAR, MVAR, gvar).
+      #
+      # Returned fields:
+      #   variation: Models::Audit::VariationDetail, or nil for non-variable
+      #              faces and Type 1 fonts
+      #
+      # A face is considered variable iff the fvar table is present. CFF2
+      # outlines without fvar are not "variable" by this definition (they
+      # may carry variation data but no user-facing axes).
+      class VariationDetail < Base
+        def extract(context)
+          font = context.font
+          return { variation: nil } unless variable?(font)
+
+          fvar = font.table(Constants::FVAR_TAG)
+          return { variation: nil } unless fvar
+
+          name_table = font.has_table?(Constants::NAME_TAG) ? font.table(Constants::NAME_TAG) : nil
+          axis_tags = axis_tags_from(fvar)
+
+          { variation: Models::Audit::VariationDetail.new(
+            axes: build_axes(name_table, fvar),
+            named_instances: build_instances(name_table, fvar, axis_tags),
+            has_avar: font.has_table?(Constants::AVAR_TAG),
+            has_cvar: font.has_table?(Constants::CVAR_TAG),
+            has_hvar: font.has_table?(Constants::HVAR_TAG),
+            has_vvar: font.has_table?(Constants::VVAR_TAG),
+            has_mvar: font.has_table?(Constants::MVAR_TAG),
+            has_gvar: font.has_table?(Constants::GVAR_TAG),
+          ) }
+        end
+
+        protected
+
+        def variable?(font)
+          font.is_a?(SfntFont) && font.has_table?(Constants::FVAR_TAG)
+        end
+
+        private
+
+        def build_axes(name_table, fvar)
+          return [] unless fvar.axes
+
+          fvar.axes.map do |axis|
+            Models::Audit::AuditAxis.new(
+              tag: axis.axis_tag,
+              min_value: axis.min_value,
+              default_value: axis.default_value,
+              max_value: axis.max_value,
+              name: english_name(name_table, axis.axis_name_id),
+            )
+          end
+        end
+
+        def build_instances(name_table, fvar, axis_tags)
+          instances = fvar.instances
+          return [] unless instances
+
+          instances.map do |instance|
+            build_instance(name_table, instance, axis_tags)
+          end
+        end
+
+        def build_instance(name_table, instance, axis_tags)
+          subfamily_name = english_name(name_table, instance[:name_id])
+          ps_name_id = instance[:postscript_name_id]
+          ps_name = ps_name_id ? english_name(name_table, ps_name_id) : nil
+          coords = Models::Audit::NamedInstance.format_coordinates(
+            axis_tags, instance[:coordinates]
+          )
+
+          Models::Audit::NamedInstance.new(
+            subfamily_name: subfamily_name,
+            postscript_name: ps_name,
+            coordinates: coords,
+          )
+        end
+
+        def english_name(name_table, name_id)
+          return nil unless name_table && name_id
+
+          name_table.english_name(name_id)
+        end
+
+        def axis_tags_from(fvar)
+          return [] unless fvar.axes
+
+          fvar.axes.map(&:axis_tag)
+        end
+      end
+    end
+  end
+end