fontisan 0.2.16 → 0.2.22

data/lib/fontisan/models/audit/audit_block.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Fontisan
+  module Models
+    module Audit
+      # One Unicode block coverage row on an AuditReport.
+      class AuditBlock < Lutaml::Model::Serializable
+        attribute :name, :string
+        attribute :first_cp, :integer
+        attribute :last_cp, :integer
+        attribute :range, :string
+        attribute :total, :integer
+        attribute :covered, :integer
+        attribute :fill_ratio, :float
+        attribute :complete, Lutaml::Model::Type::Boolean
+
+        key_value do
+          map "name",       to: :name
+          map "first_cp",   to: :first_cp
+          map "last_cp",    to: :last_cp
+          map "range",      to: :range
+          map "total",      to: :total
+          map "covered",    to: :covered
+          map "fill_ratio", to: :fill_ratio
+          map "complete",   to: :complete
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/models/audit/audit_diff.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Fontisan
+  module Models
+    module Audit
+      # Structural diff between two AuditReports.
+      #
+      # `left_source`/`right_source` are the original source_file paths
+      # (or report paths) so a consumer reading the diff alone can locate
+      # the inputs.
+      #
+      # `field_changes` lists scalar fields whose values changed.
+      # `codepoints` is the cmap delta (CodepointSetDiff).
+      # The remaining fields are array set-diffs over the report's
+      # structural inventory: OpenType features, scripts, UCD blocks, and
+      # CLDR languages. Each is split into `added_*` (in right, not left)
+      # and `removed_*` (in left, not right).
+      class AuditDiff < Lutaml::Model::Serializable
+        attribute :left_source,      :string
+        attribute :right_source,     :string
+        attribute :field_changes,    FieldChange, collection: true
+        attribute :codepoints,       CodepointSetDiff
+        attribute :added_features,   :string, collection: true
+        attribute :removed_features, :string, collection: true
+        attribute :added_scripts,    :string, collection: true
+        attribute :removed_scripts,  :string, collection: true
+        attribute :added_blocks,     :string, collection: true
+        attribute :removed_blocks,   :string, collection: true
+        attribute :added_languages,  :string, collection: true
+        attribute :removed_languages, :string, collection: true
+
+        key_value do
+          map "left_source",       to: :left_source
+          map "right_source",      to: :right_source
+          map "field_changes",     to: :field_changes
+          map "codepoints",        to: :codepoints
+          map "added_features",    to: :added_features
+          map "removed_features",  to: :removed_features
+          map "added_scripts",     to: :added_scripts
+          map "removed_scripts",   to: :removed_scripts
+          map "added_blocks",      to: :added_blocks
+          map "removed_blocks",    to: :removed_blocks
+          map "added_languages",   to: :added_languages
+          map "removed_languages", to: :removed_languages
+        end
+
+        # True when nothing differs. Useful for the text formatter.
+        #
+        # @return [Boolean]
+        def empty?
+          collection_empty?(field_changes) &&
+            added_codepoints.zero? && removed_codepoints.zero? &&
+            collection_empty?(added_features) && collection_empty?(removed_features) &&
+            collection_empty?(added_scripts) && collection_empty?(removed_scripts) &&
+            collection_empty?(added_blocks) && collection_empty?(removed_blocks) &&
+            collection_empty?(added_languages) && collection_empty?(removed_languages)
+        end
+
+        def added_codepoints
+          codepoints&.added_count || 0
+        end
+
+        def removed_codepoints
+          codepoints&.removed_count || 0
+        end
+
+        private
+
+        def collection_empty?(value)
+          value.nil? || value.empty?
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/models/audit/audit_report.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Fontisan
+  module Models
+    module Audit
+      # Complete font audit report for a single face.
+      #
+      # Self-describing: one face per file. Carries source provenance
+      # (`source_file`, `source_sha256`, `font_index`, `num_fonts_in_source`)
+      # so a consumer reading a single face report knows whether the
+      # source was a standalone font or a collection face, and can locate
+      # siblings via the source hash.
+      #
+      # Constructed by Commands::AuditCommand. The model is passive —
+      # no font-parsing logic lives here.
+      class AuditReport < Lutaml::Model::Serializable
+        # Provenance
+        attribute :generated_at, :string
+        attribute :fontisan_version, :string
+        attribute :source_file, :string
+        attribute :source_sha256, :string
+        attribute :source_format, :string
+
+        # Source layout
+        attribute :font_index, :integer
+        attribute :num_fonts_in_source, :integer
+
+        # Identity (name table)
+        attribute :family_name, :string
+        attribute :subfamily_name, :string
+        attribute :full_name, :string
+        attribute :postscript_name, :string
+        attribute :version, :string
+        attribute :font_revision, :float
+
+        # Style (OS/2 + head)
+        attribute :weight_class, :integer
+        attribute :width_class, :integer
+        attribute :italic, Lutaml::Model::Type::Boolean
+        attribute :bold, Lutaml::Model::Type::Boolean
+        attribute :panose, :string
+
+        # Coverage
+        attribute :total_codepoints, :integer
+        attribute :total_glyphs, :integer
+        attribute :cmap_subtables, :integer, collection: true
+        attribute :codepoint_ranges, CodepointRange, collection: true
+        attribute :codepoints, :string, collection: true
+
+        # Aggregations (require UCD)
+        attribute :ucd_version, :string
+        attribute :blocks, AuditBlock, collection: true
+        attribute :unicode_scripts, :string, collection: true
+
+        # Per-language coverage (requires CLDR; opt-in via
+        # `--with-language-coverage`)
+        attribute :cldr_version, :string
+        attribute :language_coverage, Models::Cldr::LanguageCoverage, collection: true
+
+        # Licensing + embedding permissions (nil for Type 1)
+        attribute :licensing, Licensing
+
+        # Layout-critical metrics from head/hhea/OS/2/post (nil for Type 1)
+        attribute :metrics, Metrics
+
+        # Hinting summary from fpgm/prep/cvt/gasp/CFF charstrings (nil for Type 1)
+        attribute :hinting, Hinting
+
+        # Color-font capability summary from COLR/CPAL/SVG/CBDT/CBLC/sbix
+        # (nil for Type 1)
+        attribute :color_capabilities, ColorCapabilities
+
+        # Variable-font detail from fvar + variation side-tables
+        # (nil for non-variable faces and Type 1)
+        attribute :variation, VariationDetail
+
+        # OpenType layout summary from GSUB + GPOS
+        # (nil for Type 1)
+        attribute :opentype_layout, OpenTypeLayout
+
+        # Set when UCD download failed or any non-fatal issue was encountered.
+        attribute :warning, :string
+
+        key_value do
+          # Provenance
+          map "generated_at",       to: :generated_at
+          map "fontisan_version",   to: :fontisan_version
+          map "source_file",        to: :source_file
+          map "source_sha256",      to: :source_sha256
+          map "source_format",      to: :source_format
+
+          # Source layout
+          map "font_index",          to: :font_index
+          map "num_fonts_in_source", to: :num_fonts_in_source
+
+          # Identity
+          map "family_name",     to: :family_name
+          map "subfamily_name",  to: :subfamily_name
+          map "full_name",       to: :full_name
+          map "postscript_name", to: :postscript_name
+          map "version",         to: :version
+          map "font_revision",   to: :font_revision
+
+          # Style
+          map "weight_class", to: :weight_class
+          map "width_class",  to: :width_class
+          map "italic",       to: :italic
+          map "bold",         to: :bold
+          map "panose",       to: :panose
+
+          # Coverage
+          map "total_codepoints", to: :total_codepoints
+          map "total_glyphs",     to: :total_glyphs
+          map "cmap_subtables",   to: :cmap_subtables
+          map "codepoint_ranges", to: :codepoint_ranges
+          map "codepoints",       to: :codepoints
+
+          # Aggregations
+          map "ucd_version",       to: :ucd_version
+          map "blocks",            to: :blocks
+          map "unicode_scripts",   to: :unicode_scripts
+
+          # CLDR per-language coverage
+          map "cldr_version",      to: :cldr_version
+          map "language_coverage", to: :language_coverage
+
+          # Licensing
+          map "licensing", to: :licensing
+
+          # Metrics
+          map "metrics", to: :metrics
+
+          # Hinting
+          map "hinting", to: :hinting
+
+          # Color capabilities
+          map "color_capabilities", to: :color_capabilities
+
+          # Variation detail
+          map "variation", to: :variation
+
+          # OpenType layout
+          map "opentype_layout", to: :opentype_layout
+
+          # Warning
+          map "warning", to: :warning
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/models/audit/codepoint_range.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Fontisan
+  module Models
+    module Audit
+      # A contiguous run of covered codepoints.
+      #
+      # `first_cp`/`last_cp` are inclusive integer endpoints. A single-codepoint
+      # "range" has first_cp == last_cp and renders as `U+XXXX` (no dash).
+      #
+      # Produced by {Audit::CodepointRangeCoalescer} from the cmap coverage.
+      # The range view replaces the previous flat per-codepoint list as the
+      # default report shape — a 60k-codepoint CJK font produces tens of
+      # ranges rather than 60k strings.
+      class CodepointRange < Lutaml::Model::Serializable
+        attribute :first_cp, :integer
+        attribute :last_cp,  :integer
+
+        key_value do
+          map "first_cp", to: :first_cp
+          map "last_cp",  to: :last_cp
+        end
+
+        # Human-readable form: `U+XXXX` for single codepoints,
+        # `U+XXXX-U+XXXX` for true ranges.
+        #
+        # @return [String]
+        def to_s
+          if first_cp == last_cp
+            format("U+%04<cp>X", cp: first_cp)
+          else
+            format("U+%04<first>X-U+%04<last>X", first: first_cp, last: last_cp)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/models/audit/codepoint_set_diff.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Fontisan
+  module Models
+    module Audit
+      # Diff between two cmap codepoint sets.
+      #
+      # `added`/`removed` are compact range lists (CodepointRange) so a
+      # large delta (e.g. CJK extension added) renders as a handful of
+      # ranges rather than thousands of codepoints.
+      #
+      # `unchanged_count` is the intersection size — useful as a sanity
+      # check that the two reports share enough coverage to be meaningfully
+      # comparable.
+      class CodepointSetDiff < Lutaml::Model::Serializable
+        attribute :added,            CodepointRange, collection: true
+        attribute :removed,          CodepointRange, collection: true
+        attribute :added_count,      :integer
+        attribute :removed_count,    :integer
+        attribute :unchanged_count,  :integer
+
+        key_value do
+          map "added",           to: :added
+          map "removed",         to: :removed
+          map "added_count",     to: :added_count
+          map "removed_count",   to: :removed_count
+          map "unchanged_count", to: :unchanged_count
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Fontisan
+  module Models
+    module Audit
+      # Color-font capability summary for one face.
+      #
+      # Answers: is this a color font, and if so, which format(s)?
+      # Modern color font formats are mutually exclusive in design but a
+      # single face can carry more than one (e.g. NotoColorEmoji ships
+      # COLR + CBDT + SVG so legacy and modern stacks all render).
+      #
+      # `color_formats` is derived at extraction time so consumers read a
+      # flat string list instead of re-deriving from the boolean lattice.
+      # Empty array ⇒ no color support.
+      class ColorCapabilities < Lutaml::Model::Serializable
+        # COLR (vector color glyphs).
+        attribute :has_colr, Lutaml::Model::Type::Boolean
+        attribute :colr_version,            :integer # 0 or 1
+        attribute :colr_base_glyph_count,   :integer
+        attribute :colr_layer_count,        :integer
+
+        # CPAL (color palette).
+        attribute :has_cpal, Lutaml::Model::Type::Boolean
+        attribute :cpal_palette_count, :integer
+        attribute :cpal_color_count,   :integer
+
+        # SVG-in-OpenType.
+        attribute :has_svg, Lutaml::Model::Type::Boolean
+        attribute :svg_document_count, :integer
+
+        # CBDT/CBLC (color bitmaps — paired tables).
+        attribute :has_cbdt, Lutaml::Model::Type::Boolean
+        attribute :has_cblc, Lutaml::Model::Type::Boolean
+        # Strike count comes from the paired CBLC locator table.
+        attribute :cbdt_strike_count, :integer
+
+        # sbix (Apple color bitmaps).
+        attribute :has_sbix, Lutaml::Model::Type::Boolean
+        attribute :sbix_strike_count, :integer
+
+        # Derived: ordered list of active color format tags. One of
+        # "colr_v0", "colr_v1", "cpal", "svg", "cbdt", "sbix".
+        attribute :color_formats, :string, collection: true
+
+        key_value do
+          map "has_colr",                to: :has_colr
+          map "colr_version",            to: :colr_version
+          map "colr_base_glyph_count",   to: :colr_base_glyph_count
+          map "colr_layer_count",        to: :colr_layer_count
+          map "has_cpal",                to: :has_cpal
+          map "cpal_palette_count",      to: :cpal_palette_count
+          map "cpal_color_count",        to: :cpal_color_count
+          map "has_svg",                 to: :has_svg
+          map "svg_document_count",      to: :svg_document_count
+          map "has_cbdt",                to: :has_cbdt
+          map "has_cblc",                to: :has_cblc
+          map "cbdt_strike_count",       to: :cbdt_strike_count
+          map "has_sbix",                to: :has_sbix
+          map "sbix_strike_count",       to: :sbix_strike_count
+          map "color_formats",           to: :color_formats
+        end
+
+        # Canonical format tags, kept in spec order.
+        FORMAT_COLR_V0 = "colr_v0"
+        FORMAT_COLR_V1 = "colr_v1"
+        FORMAT_CPAL    = "cpal"
+        FORMAT_SVG     = "svg"
+        FORMAT_CBDT    = "cbdt"
+        FORMAT_SBIX    = "sbix"
+
+        # Derive the canonical color_formats list from individual flags.
+        # COLR v1 takes precedence over v0 — a v1 table can serve both.
+        #
+        # @return [Array<String>]
+        def self.derive_formats(has_colr:, colr_version:, has_cpal:,
+                                has_svg:, has_cbdt:, has_sbix:)
+          [].tap do |arr|
+            if has_colr
+              arr << (colr_version == 1 ? FORMAT_COLR_V1 : FORMAT_COLR_V0)
+            end
+            arr << FORMAT_CPAL if has_cpal
+            arr << FORMAT_SVG  if has_svg
+            arr << FORMAT_CBDT if has_cbdt
+            arr << FORMAT_SBIX if has_sbix
+          end
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/models/audit/duplicate_group.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Fontisan
+  module Models
+    module Audit
+      # Group of files that share an identical `source_sha256`.
+      #
+      # Detecting duplicate byte-identical files (regardless of filename)
+      # is the cheapest form of library hygiene: same bytes = same font.
+      class DuplicateGroup < Lutaml::Model::Serializable
+        attribute :source_sha256, :string
+        attribute :files, :string, collection: true
+
+        key_value do
+          map "source_sha256", to: :source_sha256
+          map "files", to: :files
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/models/audit/embedding_type.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Fontisan
+  module Models
+    module Audit
+      # Decoded OS/2 fsType bitfield → canonical embedding-permission string.
+      #
+      # Per OpenType spec, fsType is a bitfield. Only one of bits 0-3 should
+      # be set (the basic permission level); bits 4-7 are modifiers that
+      # only apply when INSTALLABLE (bit 3) is set.
+      #
+      # The decoder normalizes to one of seven canonical strings so
+      # downstream consumers don't need to know the bit layout.
+      class EmbeddingType < Lutaml::Model::Serializable
+        # Bit masks (OpenType fsType bitfield).
+        RESTRICTED_LICENSE_NO_EMBEDDING = 0x0001
+        PREVIEW_AND_PRINT               = 0x0002
+        EDITABLE_EMBEDDING              = 0x0004
+        INSTALLABLE_EMBEDDING           = 0x0008
+        NO_SUBSETTING                   = 0x0100
+        BITMAP_EMBEDDING_ONLY           = 0x0200
+
+        attribute :value, :string
+
+        # Decoded canonical string for the given fsType bitfield.
+        #
+        # @param fs_type [Integer, nil] raw OS/2 fsType value
+        # @return [String, nil] canonical permission name, or nil when
+        #   fs_type is nil
+        def self.decode(fs_type)
+          return nil if fs_type.nil?
+
+          if fs_type & RESTRICTED_LICENSE_NO_EMBEDDING != 0
+            "restricted_license"
+          elsif fs_type & PREVIEW_AND_PRINT != 0
+            "preview_print"
+          elsif fs_type & EDITABLE_EMBEDDING != 0
+            "editable"
+          elsif fs_type & INSTALLABLE_EMBEDDING != 0
+            installable_subcategory(fs_type)
+          elsif fs_type.zero?
+            "installable"
+          else
+            "unknown"
+          end
+        end
+
+        # Construct from a decoded canonical string.
+        #
+        # @param fs_type [Integer, nil]
+        def self.from_fs_type(fs_type)
+          new(value: decode(fs_type))
+        end
+
+        def to_s
+          value
+        end
+
+        def self.installable_subcategory(fs_type)
+          if fs_type & NO_SUBSETTING != 0 && fs_type & BITMAP_EMBEDDING_ONLY != 0
+            "installable_no_subsetting_bitmap_only"
+          elsif fs_type & NO_SUBSETTING != 0
+            "installable_no_subsetting"
+          elsif fs_type & BITMAP_EMBEDDING_ONLY != 0
+            "installable_bitmap_only"
+          else
+            "installable"
+          end
+        end
+        private_class_method :installable_subcategory
+      end
+    end
+  end
+end

data/lib/fontisan/models/audit/field_change.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Fontisan
+  module Models
+    module Audit
+      # One scalar field that differs between two AuditReports.
+      #
+      # `field` is the dotted attribute name (e.g. "weight_class").
+      # `left`/`right` are stringified values: nil → "", String → itself,
+      # anything else → its YAML form. Comparing the YAML form of nested
+      # models is intentionally avoided here — those diffs surface as
+      # structural add/remove lists on AuditDiff itself.
+      class FieldChange < Lutaml::Model::Serializable
+        attribute :field, :string
+        attribute :left,  :string
+        attribute :right, :string
+
+        key_value do
+          map "field", to: :field
+          map "left",  to: :left
+          map "right", to: :right
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/models/audit/fs_selection_flags.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Fontisan
+  module Models
+    module Audit
+      # Decoded OS/2 fsSelection bitfield → sorted array of flag names.
+      #
+      # Per OpenType spec, fsSelection is a bitfield with these bits:
+      #
+      #   bit 0 (0x001): italic
+      #   bit 1 (0x002): underscore
+      #   bit 2 (0x004): negative
+      #   bit 3 (0x008): outlined
+      #   bit 4 (0x010): strikeout
+      #   bit 5 (0x020): bold
+      #   bit 6 (0x040): regular
+      #   bit 7 (0x080): use_typo_metrics
+      #   bit 8 (0x100): wws
+      #   bit 9 (0x200): oblique
+      #
+      # Returns names in spec order (bit ascending).
+      class FsSelectionFlags < Lutaml::Model::Serializable
+        FLAGS = {
+          0x001 => "italic",
+          0x002 => "underscore",
+          0x004 => "negative",
+          0x008 => "outlined",
+          0x010 => "strikeout",
+          0x020 => "bold",
+          0x040 => "regular",
+          0x080 => "use_typo_metrics",
+          0x100 => "wws",
+          0x200 => "oblique",
+        }.freeze
+
+        attribute :flags, :string, collection: true
+
+        # Decoded array of flag names in spec order (bit ascending).
+        #
+        # @param fs_selection [Integer, nil] raw OS/2 fsSelection value
+        # @return [Array<String>, nil]
+        def self.decode(fs_selection)
+          return nil if fs_selection.nil?
+
+          FLAGS.each_with_object([]) do |(mask, name), acc|
+            acc << name if fs_selection & mask != 0
+          end
+        end
+
+        # Construct from a raw fsSelection value.
+        #
+        # @param fs_selection [Integer, nil]
+        def self.from_fs_selection(fs_selection)
+          new(flags: decode(fs_selection))
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/models/audit/gasp_range.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Fontisan
+  module Models
+    module Audit
+      # One entry from the TrueType `gasp` (Grid-fitting And Scan-conversion
+      # Procedure) table.
+      #
+      # Each entry describes the hinting/smoothing policy that applies up to
+      # the given `max_ppem` (pixels-per-em). The OpenType spec defines four
+      # single-bit flags; the high 12 bits of the raw rangeFlags uint16 are
+      # reserved.
+      #
+      # Construct via {.from_flags} from the raw uint16 pair; never hand-build
+      # the bit decoding at call sites.
+      class GaspRange < Lutaml::Model::Serializable
+        # OpenType gasp rangeFlags bit masks.
+        GRIDFIT             = 0x0001
+        DO_GRAY             = 0x0002
+        SYMMETRIC_GRIDFIT   = 0x0004
+        SYMMETRIC_SMOOTHING = 0x0008
+
+        attribute :max_ppem,            :integer
+        attribute :gridfit,             Lutaml::Model::Type::Boolean
+        attribute :do_gray,             Lutaml::Model::Type::Boolean
+        attribute :symmetric_gridfit,   Lutaml::Model::Type::Boolean
+        attribute :symmetric_smoothing, Lutaml::Model::Type::Boolean
+
+        key_value do
+          map "max_ppem",            to: :max_ppem
+          map "gridfit",             to: :gridfit
+          map "do_gray",             to: :do_gray
+          map "symmetric_gridfit",   to: :symmetric_gridfit
+          map "symmetric_smoothing", to: :symmetric_smoothing
+        end
+
+        # Build a GaspRange from the raw uint16 pair stored in the gasp table.
+        #
+        # @param max_ppem [Integer] rangeMaxPPEM (exclusive upper bound)
+        # @param flags [Integer] raw rangeFlags bitfield
+        # @return [GaspRange]
+        def self.from_flags(max_ppem, flags)
+          new(
+            max_ppem: max_ppem,
+            gridfit: (flags & GRIDFIT).positive?,
+            do_gray: (flags & DO_GRAY).positive?,
+            symmetric_gridfit: (flags & SYMMETRIC_GRIDFIT).positive?,
+            symmetric_smoothing: (flags & SYMMETRIC_SMOOTHING).positive?,
+          )
+        end
+
+        # Derived: both gridfit and do_gray are set. Mac historically treated
+        # this combination as "do everything". Not serialized — compute on
+        # demand.
+        def gridfit_and_smoothing?
+          gridfit && do_gray
+        end
+      end
+    end
+  end
+end