fontisan 0.2.17 → 0.2.22

data/lib/fontisan/audit/codepoint_range_coalescer.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Audit
+    # Coalesces a flat codepoint list into contiguous {Models::Audit::CodepointRange}s.
+    #
+    # Single static call site, deterministic output. Used by the Coverage
+    # extractor to produce the compact range view that is the default
+    # AuditReport shape.
+    module CodepointRangeCoalescer
+      module_function
+
+      # @param codepoints [Enumerable<Integer>] any enumeration of integers
+      # @return [Array<Models::Audit::CodepointRange>] contiguous, sorted
+      def call(codepoints)
+        return [] if codepoints.nil? || codepoints.empty?
+
+        sorted = codepoints.sort.uniq
+        ranges = []
+        range_start = sorted[0]
+        prev = sorted[0]
+
+        sorted[1..].each do |cp|
+          next if cp == prev # defensive: .uniq already handles this
+
+          if cp == prev + 1
+            prev = cp
+          else
+            ranges << Models::Audit::CodepointRange.new(first_cp: range_start,
+                                                        last_cp: prev)
+            range_start = cp
+            prev = cp
+          end
+        end
+        ranges << Models::Audit::CodepointRange.new(first_cp: range_start,
+                                                    last_cp: prev)
+        ranges
+      end
+    end
+  end
+end

data/lib/fontisan/audit/context.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Audit
+    # Value object carrying everything an extractor needs to do its job.
+    #
+    # Extractors never reach back into AuditCommand state — they read
+    # exclusively from the Context. Shared derived data (codepoints,
+    # UCD indices, source format) is memoized here so multiple
+    # extractors don't recompute it.
+    class Context
+      attr_reader :font, :font_path, :font_index, :num_fonts_in_source,
+                  :options
+
+      def initialize(font:, font_path:, font_index:, num_fonts_in_source:,
+                     options:)
+        @font = font
+        @font_path = font_path
+        @font_index = font_index
+        @num_fonts_in_source = num_fonts_in_source
+        @options = options
+      end
+
+      def codepoints
+        @codepoints ||= extract_codepoints
+      end
+
+      def ucd
+        @ucd ||= resolve_ucd
+      end
+
+      def cldr
+        return nil unless @options[:with_language_coverage]
+
+        @cldr ||= resolve_cldr
+      end
+
+      def source_format
+        @source_format ||= FontLoader.detect_format(@font_path)&.to_s
+      end
+
+      def all_codepoints?
+        @options[:all_codepoints] == true
+      end
+
+      private
+
+      def extract_codepoints
+        return [] unless @font.has_table?(Constants::CMAP_TAG)
+
+        @font.table(Constants::CMAP_TAG).unicode_mappings.keys
+      end
+
+      def resolve_ucd
+        version = Ucd::VersionResolver.resolve(@options[:ucd_version])
+
+        with_local_indices(version) do |blocks_path, scripts_path|
+          {
+            version: version,
+            blocks_index: Ucd::Index.load(blocks_path),
+            scripts_index: Ucd::Index.load(scripts_path),
+            warning: nil,
+          }
+        end
+      rescue Ucd::UnknownVersionError => e
+        { version: nil, blocks_index: nil, scripts_index: nil,
+          warning: "UCD version rejected: #{e.message}" }
+      rescue StandardError => e
+        version_ref = @ucd&.fetch(:version, nil)
+        {
+          version: version_ref,
+          blocks_index: nil,
+          scripts_index: nil,
+          warning: "UCD unavailable for version #{version_ref}: #{e.message}",
+        }
+      end
+
+      def with_local_indices(version)
+        unless Ucd::CacheManager.cached?(version)
+          Ucd::Downloader.download(version)
+        end
+        unless Ucd::CacheManager.blocks_index_path(version).exist?
+          Ucd::IndexBuilder.build(version)
+        end
+        yield Ucd::CacheManager.blocks_index_path(version),
+          Ucd::CacheManager.scripts_index_path(version)
+      end
+
+      def resolve_cldr
+        version = Cldr::VersionResolver.resolve(@options[:cldr_version])
+
+        with_local_languages_index(version) do |index_path|
+          {
+            version: version,
+            index: Cldr::Index.load(index_path),
+            warning: nil,
+          }
+        end
+      rescue Cldr::UnknownVersionError => e
+        { version: nil, index: nil,
+          warning: "CLDR version rejected: #{e.message}" }
+      rescue StandardError => e
+        version_ref = @cldr&.fetch(:version, nil)
+        {
+          version: version_ref,
+          index: nil,
+          warning: "CLDR unavailable for version #{version_ref}: #{e.message}",
+        }
+      end
+
+      def with_local_languages_index(version)
+        unless Cldr::CacheManager.cached?(version)
+          Cldr::Downloader.download(version)
+        end
+        unless Cldr::CacheManager.languages_index_path(version).exist?
+          Cldr::IndexBuilder.build(version)
+        end
+        yield Cldr::CacheManager.languages_index_path(version)
+      end
+    end
+  end
+end

data/lib/fontisan/audit/differ.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Audit
+    # Computes an {Models::Audit::AuditDiff} between two AuditReports.
+    #
+    # Pure: no I/O, no font parsing. Both reports must already be built
+    # (Commands::AuditCompareCommand handles loading reports from disk
+    # or auditing fresh fonts before invoking the differ).
+    #
+    # Comparison shape:
+    #   - Scalar fields: one FieldChange per differing field.
+    #   - Codepoint coverage: CodepointSetDiff built from the cmap range
+    #     lists (expanded to integer sets for set arithmetic, then
+    #     re-coalesced to ranges for output).
+    #   - Structural inventories (features, scripts, blocks, languages):
+    #     simple array set-diffs.
+    class Differ
+      # Scalar AuditReport fields compared field-by-field. Excludes
+      # generated_at / source_sha256 / source_file (per-report identity),
+      # codepoints / codepoint_ranges (handled via CodepointSetDiff),
+      # and nested models (surfaced via structural add/remove lists).
+      COMPARED_FIELDS = %i[
+        family_name subfamily_name full_name postscript_name version
+        font_revision weight_class width_class italic bold panose
+        total_codepoints total_glyphs ucd_version cldr_version
+      ].freeze
+
+      def initialize(left_report, right_report)
+        @left = left_report
+        @right = right_report
+      end
+
+      # @return [Models::Audit::AuditDiff]
+      def diff
+        Models::Audit::AuditDiff.new(
+          left_source: @left.source_file,
+          right_source: @right.source_file,
+          field_changes: field_changes,
+          codepoints: codepoint_diff,
+          added_features: set_diff(features(@right), features(@left)),
+          removed_features: set_diff(features(@left), features(@right)),
+          added_scripts: set_diff(scripts(@right), scripts(@left)),
+          removed_scripts: set_diff(scripts(@left), scripts(@right)),
+          added_blocks: set_diff(blocks(@right), blocks(@left)),
+          removed_blocks: set_diff(blocks(@left), blocks(@right)),
+          added_languages: set_diff(languages(@right), languages(@left)),
+          removed_languages: set_diff(languages(@left), languages(@right)),
+        )
+      end
+
+      private
+
+      def field_changes
+        COMPARED_FIELDS.filter_map do |field|
+          left_val = @left.public_send(field)
+          right_val = @right.public_send(field)
+          next if left_val == right_val
+
+          Models::Audit::FieldChange.new(
+            field: field.to_s,
+            left: serialize_value(left_val),
+            right: serialize_value(right_val),
+          )
+        end
+      end
+
+      def codepoint_diff
+        left_set = codepoints_from_ranges(@left)
+        right_set = codepoints_from_ranges(@right)
+        added = right_set - left_set
+        removed = left_set - right_set
+        unchanged = left_set & right_set
+
+        Models::Audit::CodepointSetDiff.new(
+          added: CodepointRangeCoalescer.call(added.to_a),
+          removed: CodepointRangeCoalescer.call(removed.to_a),
+          added_count: added.size,
+          removed_count: removed.size,
+          unchanged_count: unchanged.size,
+        )
+      end
+
+      # Expand a report's compact codepoint range list into a Set<Integer>.
+      # Works for both default reports (range list populated) and
+      # --all-codepoints reports (range list is also populated).
+      def codepoints_from_ranges(report)
+        ranges = report.codepoint_ranges || []
+        ranges.each_with_object(Set.new) do |range, set|
+          (range.first_cp..range.last_cp).each { |cp| set << cp }
+        end
+      end
+
+      def features(report)
+        report.opentype_layout&.features || []
+      end
+
+      def scripts(report)
+        report.opentype_layout&.scripts || []
+      end
+
+      def blocks(report)
+        (report.blocks || []).map(&:name)
+      end
+
+      def languages(report)
+        (report.language_coverage || []).map(&:language)
+      end
+
+      def set_diff(minuend, subtrahend)
+        (Array(minuend) - Array(subtrahend)).sort
+      end
+
+      def serialize_value(value)
+        case value
+        when nil then ""
+        when String, Integer, Float then value.to_s
+        when true, false then value.to_s
+        else value.to_yaml
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Audit
+    module Extractors
+      # Aggregation fields: UCD block/script coverage.
+      #
+      # Returned fields:
+      #   ucd_version, blocks, unicode_scripts
+      #
+      # OpenType script/feature inventory lives in {Extractors::OpenTypeLayout}
+      # (MECE: this extractor is UCD-driven, that one is SFNT-table-driven).
+      class Aggregations < Base
+        def extract(context)
+          ucd = context.ucd
+          ucd_aggregations(context.codepoints, ucd)
+        end
+
+        private
+
+        def ucd_aggregations(codepoints, ucd)
+          return empty_aggregation(ucd) if ucd[:blocks_index].nil?
+
+          blocks_hashes = Ucd::Aggregator.aggregate_blocks(codepoints,
+                                                           ucd[:blocks_index])
+          {
+            ucd_version: ucd[:version],
+            blocks: blocks_hashes.map { |h| build_audit_block(h) },
+            unicode_scripts: Ucd::Aggregator.aggregate_scripts(codepoints,
+                                                               ucd[:scripts_index]),
+          }
+        end
+
+        def empty_aggregation(ucd)
+          { ucd_version: ucd[:version], blocks: [], unicode_scripts: [] }
+        end
+
+        def build_audit_block(block_hash)
+          Models::Audit::AuditBlock.new(
+            name: block_hash[:name],
+            first_cp: block_hash[:first_cp],
+            last_cp: block_hash[:last_cp],
+            range: format("U+%<first>04X-U+%<last>04X",
+                          first: block_hash[:first_cp], last: block_hash[:last_cp]),
+            total: block_hash[:total],
+            covered: block_hash[:covered],
+            fill_ratio: block_hash[:fill_ratio],
+            complete: block_hash[:complete],
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Audit
+    module Extractors
+      # Abstract extractor interface. Subclasses implement `#extract`.
+      #
+      # An extractor reads from a Context and returns a hash of fields
+      # suitable for `Models::Audit::AuditReport.new(**fields)`.
+      # Returning an empty hash is valid (no-op).
+      class Base
+        def extract(context)
+          raise NotImplementedError,
+                "#{self.class} must implement #extract"
+        end
+
+        protected
+
+        # Convenience accessor used by most extractors.
+        def font(context)
+          context.font
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Audit
+    module Extractors
+      # Color-font capability summary: which color formats a face carries
+      # (COLR v0/v1, CPAL, SVG, CBDT/CBLC, sbix) plus lightweight counts
+      # from each table's header.
+      #
+      # Returned fields:
+      #   color_capabilities: Models::Audit::ColorCapabilities, or nil
+      #                       for Type 1
+      #
+      # Counts are best-effort — any table that fails to parse yields nil
+      # for its corresponding count fields rather than crashing the audit.
+      class ColorCapabilities < Base
+        def extract(context)
+          font = context.font
+          return { color_capabilities: nil } unless sfnt?(font)
+
+          { color_capabilities: Models::Audit::ColorCapabilities.new(**gather(font)) }
+        end
+
+        protected
+
+        def sfnt?(font)
+          font.is_a?(SfntFont)
+        end
+
+        private
+
+        def gather(font)
+          colr = colr_fields(font)
+          cpal = cpal_fields(font)
+          svg  = svg_fields(font)
+          cbdt = cbdt_fields(font)
+          sbix = sbix_fields(font)
+
+          formats = Models::Audit::ColorCapabilities.derive_formats(
+            has_colr: colr[:has_colr], colr_version: colr[:colr_version],
+            has_cpal: cpal[:has_cpal], has_svg: svg[:has_svg],
+            has_cbdt: cbdt[:has_cbdt], has_sbix: sbix[:has_sbix]
+          )
+
+          colr.merge(cpal).merge(svg).merge(cbdt).merge(sbix)
+            .merge(color_formats: formats)
+        end
+
+        def colr_fields(font)
+          return empty_colr unless font.has_table?(Constants::COLR_TAG)
+
+          colr = font.table(Constants::COLR_TAG)
+          return empty_colr unless colr
+
+          {
+            has_colr: true,
+            colr_version: colr.version&.to_i,
+            colr_base_glyph_count: colr.num_base_glyph_records&.to_i,
+            colr_layer_count: colr.num_layer_records&.to_i,
+          }
+        end
+
+        def empty_colr
+          { has_colr: false, colr_version: nil,
+            colr_base_glyph_count: nil, colr_layer_count: nil }
+        end
+
+        def cpal_fields(font)
+          return empty_cpal unless font.has_table?(Constants::CPAL_TAG)
+
+          cpal = font.table(Constants::CPAL_TAG)
+          return empty_cpal unless cpal
+
+          {
+            has_cpal: true,
+            cpal_palette_count: cpal.num_palettes&.to_i,
+            cpal_color_count: cpal.num_color_records&.to_i,
+          }
+        end
+
+        def empty_cpal
+          { has_cpal: false, cpal_palette_count: nil, cpal_color_count: nil }
+        end
+
+        def svg_fields(font)
+          return empty_svg unless font.has_table?(Constants::SVG_TAG)
+
+          svg = font.table(Constants::SVG_TAG)
+          return empty_svg unless svg
+
+          {
+            has_svg: true,
+            svg_document_count: svg.num_svg_documents&.to_i,
+          }
+        end
+
+        def empty_svg
+          { has_svg: false, svg_document_count: nil }
+        end
+
+        # CBDT/CBLC are paired tables: CBLC holds the strike index,
+        # CBDT holds the bitmap data. has_cbdt vs has_cblc disagreement
+        # is reported as-is — audit consumers can spot the inconsistency.
+        def cbdt_fields(font)
+          has_cbdt = font.has_table?(Constants::CBDT_TAG)
+          has_cblc = font.has_table?(Constants::CBLC_TAG)
+          strike_count = cblc_strike_count(font) if has_cblc
+
+          {
+            has_cbdt: has_cbdt,
+            has_cblc: has_cblc,
+            cbdt_strike_count: strike_count,
+          }
+        end
+
+        def cblc_strike_count(font)
+          cblc = font.table(Constants::CBLC_TAG)
+          return nil unless cblc
+
+          cblc.num_sizes&.to_i
+        end
+
+        def sbix_fields(font)
+          return empty_sbix unless font.has_table?(Constants::SBIX_TAG)
+
+          sbix = font.table(Constants::SBIX_TAG)
+          return empty_sbix unless sbix
+
+          {
+            has_sbix: true,
+            sbix_strike_count: sbix.num_strikes&.to_i,
+          }
+        end
+
+        def empty_sbix
+          { has_sbix: false, sbix_strike_count: nil }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Audit
+    module Extractors
+      # Coverage fields: how many codepoints and glyphs the font ships,
+      # the compact codepoint-range view (default), and the optional flat
+      # per-codepoint list (only when `--all-codepoints` is on).
+      #
+      # Returned fields:
+      #   total_codepoints, total_glyphs, cmap_subtables,
+      #   codepoint_ranges, codepoints
+      class Coverage < Base
+        def extract(context)
+          font = context.font
+          codepoints = context.codepoints
+          {
+            total_codepoints: codepoints.length,
+            total_glyphs: total_glyphs(font),
+            cmap_subtables: cmap_subtable_formats(font),
+            codepoint_ranges: CodepointRangeCoalescer.call(codepoints),
+            codepoints: codepoints_for_report(context, codepoints),
+          }
+        end
+
+        private
+
+        def total_glyphs(font)
+          return nil unless font.has_table?(Constants::MAXP_TAG)
+
+          font.table(Constants::MAXP_TAG).num_glyphs
+        end
+
+        def cmap_subtable_formats(font)
+          return [] unless font.has_table?(Constants::CMAP_TAG)
+
+          font.table(Constants::CMAP_TAG).subtable_formats
+        end
+
+        def codepoints_for_report(context, codepoints)
+          return [] unless context.all_codepoints?
+
+          codepoints.map { |cp| format("U+%<cp>04X", cp: cp) }
+        end
+      end
+    end
+  end
+end