fontisan 0.4.33 → 0.4.35

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

@@ -31,6 +31,29 @@ module Fontisan
     desc "stitch", "Stitch glyphs from multiple source fonts into one output"
     subcommand "stitch", StitcherCli
 
+    desc "audit FONT_FILE", "Produce a structured audit report (identity, style, coverage, layout)"
+    option :output, type: :string,
+                    desc: "Output file path. For collections, use a directory path."
+    option :no_codepoints, type: :boolean, default: false,
+                           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])
+    rescue Errno::ENOENT
+      warn "File not found: #{font_file}" unless options[:quiet]
+      exit 1
+    end
+
     desc "info PATH", "Display font information"
     option :brief, type: :boolean, default: false,
                    desc: "Brief mode - only essential info (5x faster, uses metadata loading)",
@@ -732,6 +755,61 @@ module Fontisan
       puts output unless options[:quiet]
     end
 
+    # Write the audit result to stdout or a file. For a single report,
+    # the output path (if given) is the file path. For a collection,
+    # the output path is a directory; each face is written as
+    # `{font_index:02d}-{postscript_name}.yaml`.
+    def write_audit_result(result, output_path)
+      if result.is_a?(Array)
+        write_audit_collection(result, output_path)
+      else
+        write_audit_single(result, output_path)
+      end
+    end
+
+    def write_audit_single(report, output_path)
+      content = serialize_audit(report)
+      if output_path
+        FileUtils.mkpath(File.dirname(output_path)) unless File.dirname(output_path) == "."
+        File.write(output_path, content)
+      else
+        puts content unless options[:quiet]
+      end
+    end
+
+    def write_audit_collection(reports, output_path)
+      if output_path
+        FileUtils.mkpath(output_path)
+        reports.each do |report|
+          name = audit_face_filename(report)
+          File.write(File.join(output_path, name), serialize_audit(report))
+        end
+        say("Wrote #{reports.size} reports to #{output_path}") unless options[:quiet]
+      else
+        puts serialize_audit(reports) unless options[:quiet]
+      end
+    end
+
+    def serialize_audit(report)
+      options[:format] == "json" ? report.to_json : report.to_yaml
+    end
+
+    def audit_face_filename(report)
+      safe_name = report.postscript_name&.gsub(%r{[^A-Za-z0-9._-]}, "_") || "font"
+      suffix = options[:format] == "json" ? "json" : "yaml"
+      idx = report.font_index || 0
+      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

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+require "digest"
+require "time"
+
+module Fontisan
+  module Commands
+    # Produces a structured {Models::AuditReport} for a single font or
+    # an array of reports for every face in a collection.
+    #
+    # The audit report is MECE with ucode: fontisan owns the font-identity
+    # axis (name table, style metadata, OpenType layout); ucode owns the
+    # Unicode-coverage axis (UCD parsing, block/script aggregation). The
+    # audit command emits the raw codepoint list so a consumer can run
+    # ucode separately without re-reading the font.
+    #
+    # Delegates data extraction to existing sub-commands and table readers
+    # — no table re-parsing happens here. This keeps the audit command a
+    # thin orchestration layer (DRY, single source of truth).
+    #
+    # @example Single font
+    #   cmd = AuditCommand.new("Inter.ttf", include_codepoints: true)
+    #   cmd.run  # => Models::AuditReport
+    #
+    # @example Collection
+    #   cmd = AuditCommand.new("Inter.ttc")
+    #   cmd.run  # => Array<Models::AuditReport>
+    class AuditCommand < BaseCommand
+      # @return [Models::AuditReport, Array<Models::AuditReport>]
+      def run
+        if FontLoader.collection?(@font_path)
+          audit_collection
+        else
+          audit_single_font(font_index: nil, num_fonts: 1)
+        end
+      end
+
+      private
+
+      # ------------------------------------------------------------------
+      # Collection dispatch
+      # ------------------------------------------------------------------
+
+      def audit_collection
+        collection = FontLoader.load_collection(@font_path)
+        num = collection.num_fonts
+        Array.new(num) do |idx|
+          face = load_face(idx)
+          build_report(face, font_index: idx, num_fonts: num)
+        end
+      end
+
+      def audit_single_font(font_index:, num_fonts:)
+        build_report(font, font_index: font_index, num_fonts: num_fonts)
+      end
+
+      # Reload a single face from a collection by index, with full tables
+      # so the audit is complete.
+      def load_face(idx)
+        FontLoader.load(@font_path, font_index: idx, mode: LoadingModes::FULL)
+      end
+
+      # ------------------------------------------------------------------
+      # Report assembly
+      # ------------------------------------------------------------------
+
+      # @param face [SfntFont] loaded font
+      # @param font_index [Integer, nil]
+      # @param num_fonts [Integer]
+      # @return [Models::AuditReport]
+      def build_report(face, font_index:, num_fonts:)
+        Models::AuditReport.new.tap do |r|
+          populate_provenance(r, font_index:, num_fonts:)
+          populate_identity(r, face)
+          populate_style(r, face)
+          populate_coverage(r, face)
+          populate_layout(r, face)
+          populate_validation(r, face) if validate?
+        end
+      end
+
+      # ------------------------------------------------------------------
+      # Provenance
+      # ------------------------------------------------------------------
+
+      def populate_provenance(report, font_index:, num_fonts:)
+        report.generated_at = Time.now.utc.iso8601
+        report.fontisan_version = VERSION
+        report.source_file = File.basename(@font_path)
+        report.source_sha256 = Digest::SHA256.file(@font_path).hexdigest
+        report.source_format = detect_source_format
+        report.font_index = font_index
+        report.num_fonts_in_source = num_fonts
+      end
+
+      def detect_source_format
+        fmt = FontLoader.detect_format(@font_path)
+        fmt ? fmt.to_s : "unknown"
+      end
+
+      # ------------------------------------------------------------------
+      # Identity (name table)
+      # ------------------------------------------------------------------
+
+      def populate_identity(report, face)
+        return unless face.has_table?(Constants::NAME_TAG)
+
+        name_table = face.table(Constants::NAME_TAG)
+        report.family_name = name_table.english_name(Tables::Name::FAMILY)
+        report.subfamily_name = name_table.english_name(Tables::Name::SUBFAMILY)
+        report.full_name = name_table.english_name(Tables::Name::FULL_NAME)
+        report.postscript_name =
+          name_table.english_name(Tables::Name::POSTSCRIPT_NAME)
+        report.version = name_table.english_name(Tables::Name::VERSION)
+
+        return unless face.has_table?(Constants::HEAD_TAG)
+
+        report.font_revision = face.table(Constants::HEAD_TAG).font_revision
+      end
+
+      # ------------------------------------------------------------------
+      # Style (OS/2, head, fvar)
+      # ------------------------------------------------------------------
+
+      def populate_style(report, face)
+        report.is_variable = false
+        report.italic = false
+        report.bold = false
+        populate_os2_style(report, face) if face.has_table?(Constants::OS2_TAG)
+        populate_head_style(report, face) if face.has_table?(Constants::HEAD_TAG)
+        populate_fvar_style(report, face) if face.has_table?(Constants::FVAR_TAG)
+      end
+
+      def populate_os2_style(report, face)
+        os2 = face.table(Constants::OS2_TAG)
+        report.weight_class = os2.us_weight_class
+        report.width_class = os2.us_width_class
+        report.italic = os2.fs_selection && (os2.fs_selection & 0x01).positive?
+        report.bold = os2.fs_selection && (os2.fs_selection & 0x20).positive?
+        report.panose = format_panose(os2.panose)
+      end
+
+      def populate_head_style(report, face)
+        head = face.table(Constants::HEAD_TAG)
+        mac_style = head.mac_style || 0
+        # head macStyle overrides OS/2 fsSelection only when OS/2 didn't set it
+        report.italic = true if (mac_style & 0x02).positive?
+        report.bold = true if (mac_style & 0x01).positive?
+      end
+
+      def populate_fvar_style(report, face)
+        report.is_variable = true
+        fvar = face.table(Constants::FVAR_TAG)
+        report.axes = fvar.axes.map do |axis|
+          Models::AuditAxis.new(
+            tag: axis.axis_tag,
+            min_value: axis.min_value,
+            default_value: axis.default_value,
+            max_value: axis.max_value,
+            name_id: axis.axis_name_id,
+          )
+        end
+      end
+
+      def format_panose(panose)
+        return nil unless panose
+
+        panose.to_a.join(" ")
+      end
+
+      # ------------------------------------------------------------------
+      # Coverage (cmap + glyph count)
+      # ------------------------------------------------------------------
+
+      def populate_coverage(report, face)
+        if face.has_table?(Constants::CMAP_TAG)
+          cmap = face.table(Constants::CMAP_TAG)
+          mappings = cmap.unicode_mappings || {}
+          report.total_codepoints = mappings.size
+          report.cmap_subtables = cmap.subtable_formats
+          report.codepoints = codepoint_list(mappings.keys) if include_codepoints?
+        end
+
+        report.total_glyphs = total_glyphs(face)
+      end
+
+      def codepoint_list(codepoints)
+        codepoints.sort.map { |cp| format_codepoint(cp) }
+      end
+
+      def format_codepoint(cp)
+        format("U+%04X", cp)
+      end
+
+      def total_glyphs(face)
+        return 0 unless face.has_table?(Constants::MAXP_TAG)
+
+        face.table(Constants::MAXP_TAG)&.num_glyphs || 0
+      rescue StandardError
+        0
+      end
+
+      def include_codepoints?
+        @options.fetch(:include_codepoints, true)
+      end
+
+      # ------------------------------------------------------------------
+      # OpenType layout (GSUB/GPOS)
+      # ------------------------------------------------------------------
+
+      def populate_layout(report, face)
+        report.opentype_scripts = collect_scripts(face)
+        report.features = collect_features(face)
+      end
+
+      def collect_scripts(face)
+        scripts = Set.new
+        %w[GSUB GPOS].each do |tag|
+          next unless face.has_table?(tag)
+
+          table = face.table(tag)
+          scripts.merge(table.scripts) if table
+        end
+        scripts.sort
+      end
+
+      def collect_features(face)
+        features = Set.new
+        %w[GSUB GPOS].each do |tag|
+          next unless face.has_table?(tag)
+
+          table = face.table(tag)
+          features.merge(collect_features_from_table(table)) if table
+        end
+        features.sort
+      end
+
+      def collect_features_from_table(layout_table)
+        scripts = begin
+                    layout_table.scripts
+        rescue StandardError
+                    []
+        end
+        scripts.flat_map { |script| features_for_script(layout_table, script) }
+      rescue StandardError
+        []
+      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
+end

data/lib/fontisan/commands.rb

@@ -5,6 +5,7 @@
 module Fontisan
   module Commands
     autoload :BaseCommand, "fontisan/commands/base_command"
+    autoload :AuditCommand, "fontisan/commands/audit_command"
     autoload :ConvertCommand, "fontisan/commands/convert_command"
     autoload :DumpTableCommand, "fontisan/commands/dump_table_command"
     autoload :ExportCommand, "fontisan/commands/export_command"