fontisan 0.2.17 → 0.2.22

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

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

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Fontisan
+  module Models
+    module Audit
+      # Hinting summary for one face.
+      #
+      # Answers the practical questions a designer or QA engineer asks:
+      # "Is this font hinted at all? What flavour? How much hinting, by
+      # byte / instruction count?" Unhinted fonts render poorly at small
+      # sizes; heavily hinted fonts can be 20%+ bytecode by file size.
+      #
+      # TrueType hinting surfaces as the fpgm/prep/cvt programs plus the
+      # gasp per-ppem policy. CFF/CFF2 hinting surfaces as stem hints
+      # encoded inside each CharString. This model carries both, plus a
+      # derived `is_unhinted` flag and `hinting_format` classification so
+      # downstream tooling does not need to re-derive either.
+      #
+      # All counts are nil-safe: a face with no hinting at all produces
+      # `Hinting.new` with every field falsy/nil rather than raising.
+      class Hinting < Lutaml::Model::Serializable
+        # TrueType bytecode programs.
+        attribute :has_fpgm, Lutaml::Model::Type::Boolean
+        attribute :fpgm_instruction_count, :integer
+        attribute :has_prep, Lutaml::Model::Type::Boolean
+        attribute :prep_instruction_count, :integer
+
+        # TrueType Control Value Table (hinting metrics).
+        attribute :has_cvt, Lutaml::Model::Type::Boolean
+        attribute :cvt_entry_count, :integer
+
+        # CVT variation table for variable TrueType fonts. Carried for
+        # context only — never included in cvt_entry_count.
+        attribute :has_cvar, Lutaml::Model::Type::Boolean
+
+        # gasp policy ranges, ordered by ascending max_ppem.
+        attribute :gasp_ranges, GaspRange, collection: true
+
+        # CFF/CFF2 hinting. cff_has_private_dict is true for every CFF
+        # face (Private DICT is mandatory); cff_hint_count sums stem
+        # declarations across all CharStrings, nil when unparsable.
+        attribute :cff_has_private_dict, Lutaml::Model::Type::Boolean
+        attribute :cff_hint_count, :integer
+
+        # Derived at extraction time so consumers read flat fields.
+        attribute :is_unhinted, Lutaml::Model::Type::Boolean
+        attribute :hinting_format, :string
+
+        key_value do
+          map "has_fpgm",               to: :has_fpgm
+          map "fpgm_instruction_count", to: :fpgm_instruction_count
+          map "has_prep",               to: :has_prep
+          map "prep_instruction_count", to: :prep_instruction_count
+          map "has_cvt",                to: :has_cvt
+          map "cvt_entry_count",        to: :cvt_entry_count
+          map "has_cvar",               to: :has_cvar
+          map "gasp_ranges",            to: :gasp_ranges
+          map "cff_has_private_dict",   to: :cff_has_private_dict
+          map "cff_hint_count",         to: :cff_hint_count
+          map "is_unhinted",            to: :is_unhinted
+          map "hinting_format",         to: :hinting_format
+        end
+
+        FORMAT_TRUETYPE = "truetype"
+        FORMAT_CFF      = "cff"
+        FORMAT_MIXED    = "mixed"
+        FORMAT_NONE     = "none"
+
+        # Derive {is_unhinted} and {hinting_format} from individual flags.
+        # Called by the extractor before construction so the values land
+        # in serialized output without recomputation at read time.
+        #
+        # gasp is a TrueType-specific table, so it counts toward the
+        # TrueType hinting bucket even when no fpgm/prep/cvt is present.
+        #
+        # @return [Hash] keys :is_unhinted, :hinting_format
+        def self.derive_flags(has_tt:, has_cff:, has_gasp:)
+          tt_hints = has_tt || has_gasp
+          any = tt_hints || has_cff
+          format =
+            if tt_hints && has_cff then FORMAT_MIXED
+            elsif tt_hints then FORMAT_TRUETYPE
+            elsif has_cff then FORMAT_CFF
+            else FORMAT_NONE
+            end
+          { is_unhinted: !any, hinting_format: format }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Fontisan
+  module Models
+    module Audit
+      # Aggregate view over a directory (tree) of audited fonts.
+      #
+      # Built by {Audit::LibraryAuditor}. Combines a flat list of
+      # per-face {AuditReport}s with derived cross-face rollups:
+      # script coverage matrix, duplicate detection (by source_sha256),
+      # and license distribution. Lets a librarian inventory a font
+      # collection in one pass.
+      class LibrarySummary < Lutaml::Model::Serializable
+        attribute :root_path, :string
+        attribute :total_files, :integer
+        attribute :total_faces, :integer
+        attribute :scanned_extensions, :string, collection: true
+        attribute :aggregate_metrics, :hash
+        attribute :script_coverage, ScriptCoverageRow, collection: true
+        attribute :duplicate_groups, DuplicateGroup, collection: true
+        attribute :license_distribution, :hash
+        attribute :per_face_reports, AuditReport, collection: true
+
+        key_value do
+          map "root_path", to: :root_path
+          map "total_files", to: :total_files
+          map "total_faces", to: :total_faces
+          map "scanned_extensions", to: :scanned_extensions
+          map "aggregate_metrics", to: :aggregate_metrics
+          map "script_coverage", to: :script_coverage
+          map "duplicate_groups", to: :duplicate_groups
+          map "license_distribution", to: :license_distribution
+          map "per_face_reports", to: :per_face_reports
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Fontisan
+  module Models
+    module Audit
+      # Licensing + embedding + vendor provenance fields for a face.
+      #
+      # Combines the human-readable legal/identity fields from the name
+      # table with the machine-readable embedding permissions from OS/2.
+      # Type 1 fonts have no OS/2 — callers must tolerate a nil
+      # embedding_type / fs_selection_flags / vendor_id.
+      class Licensing < Lutaml::Model::Serializable
+        # Name-table fields (English name IDs)
+        attribute :copyright,          :string
+        attribute :trademark,          :string
+        attribute :manufacturer,       :string
+        attribute :designer,           :string
+        attribute :description,        :string
+        attribute :vendor_url,         :string
+        attribute :designer_url,       :string
+        attribute :license_description, :string
+        attribute :license_url, :string
+
+        # OS/2 fields
+        attribute :vendor_id,           :string
+        attribute :embedding_type,      :string
+        attribute :fs_selection_flags,  :string, collection: true
+
+        key_value do
+          map "copyright",           to: :copyright
+          map "trademark",           to: :trademark
+          map "manufacturer",        to: :manufacturer
+          map "designer",            to: :designer
+          map "description",         to: :description
+          map "vendor_url",          to: :vendor_url
+          map "designer_url",        to: :designer_url
+          map "license_description", to: :license_description
+          map "license_url",         to: :license_url
+          map "vendor_id",           to: :vendor_id
+          map "embedding_type",      to: :embedding_type
+          map "fs_selection_flags",  to: :fs_selection_flags
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Fontisan
+  module Models
+    module Audit
+      # Layout-critical metrics for a face, consolidated from head, hhea,
+      # OS/2, and post tables. Designers and engineers can read all
+      # spacing-relevant numbers in one place instead of cross-referencing
+      # raw table dumps.
+      #
+      # All fields are nil-safe — Type 1 fonts and stripped WOFF builds
+      # may not carry every table. Derived booleans (e.g. metrics_consistent?)
+      # tolerate nil inputs and return false rather than raising.
+      class Metrics < Lutaml::Model::Serializable
+        # head
+        attribute :units_per_em, :integer
+        attribute :bbox_x_min,   :integer
+        attribute :bbox_y_min,   :integer
+        attribute :bbox_x_max,   :integer
+        attribute :bbox_y_max,   :integer
+
+        # hhea (horizontal)
+        attribute :hhea_ascent,  :integer
+        attribute :hhea_descent, :integer
+        attribute :hhea_line_gap, :integer
+
+        # OS/2 typo
+        attribute :typo_ascender, :integer
+        attribute :typo_descender, :integer
+        attribute :typo_line_gap, :integer
+
+        # OS/2 win
+        attribute :win_ascent,  :integer
+        attribute :win_descent, :integer
+
+        # OS/2 v2+ (optional)
+        attribute :x_height,   :integer
+        attribute :cap_height, :integer
+
+        # OS/2 subscript/superscript
+        attribute :subscript_x_size,    :integer
+        attribute :subscript_y_size,    :integer
+        attribute :subscript_x_offset,  :integer
+        attribute :subscript_y_offset,  :integer
+        attribute :superscript_x_size,    :integer
+        attribute :superscript_y_size,    :integer
+        attribute :superscript_x_offset,  :integer
+        attribute :superscript_y_offset,  :integer
+
+        # OS/2 strikeout
+        attribute :strikeout_size,     :integer
+        attribute :strikeout_position, :integer
+
+        # post underline
+        attribute :underline_position,  :float
+        attribute :underline_thickness, :float
+
+        key_value do
+          map "units_per_em",     to: :units_per_em
+          map "bbox_x_min",       to: :bbox_x_min
+          map "bbox_y_min",       to: :bbox_y_min
+          map "bbox_x_max",       to: :bbox_x_max
+          map "bbox_y_max",       to: :bbox_y_max
+
+          map "hhea_ascent",   to: :hhea_ascent
+          map "hhea_descent",  to: :hhea_descent
+          map "hhea_line_gap", to: :hhea_line_gap
+
+          map "typo_ascender",  to: :typo_ascender
+          map "typo_descender", to: :typo_descender
+          map "typo_line_gap",  to: :typo_line_gap
+
+          map "win_ascent",  to: :win_ascent
+          map "win_descent", to: :win_descent
+
+          map "x_height",   to: :x_height
+          map "cap_height", to: :cap_height
+
+          map "subscript_x_size",   to: :subscript_x_size
+          map "subscript_y_size",   to: :subscript_y_size
+          map "subscript_x_offset", to: :subscript_x_offset
+          map "subscript_y_offset", to: :subscript_y_offset
+          map "superscript_x_size",   to: :superscript_x_size
+          map "superscript_y_size",   to: :superscript_y_size
+          map "superscript_x_offset", to: :superscript_x_offset
+          map "superscript_y_offset", to: :superscript_y_offset
+
+          map "strikeout_size",     to: :strikeout_size
+          map "strikeout_position", to: :strikeout_position
+
+          map "underline_position",  to: :underline_position
+          map "underline_thickness", to: :underline_thickness
+        end
+
+        # True when hhea ascent/descent match OS/2 typo ascent/descent.
+        # Mismatch is a common font bug that causes inconsistent line
+        # height across platforms.
+        #
+        # @return [Boolean]
+        def metrics_consistent?
+          return false if hhea_ascent.nil? || typo_ascender.nil?
+          return false if hhea_descent.nil? || typo_descender.nil?
+
+          hhea_ascent == typo_ascender && hhea_descent == typo_descender
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Fontisan
+  module Models
+    module Audit
+      # One fvar named instance (e.g. "Bold", "SemiCondensed").
+      #
+      # `coordinates` is serialized as a compact "tag=value,tag=value" string
+      # (e.g. "wght=700,wdth=100") for human readability. The AuditReport is
+      # primarily a human-facing artifact; downstream tooling that needs
+      # structured coordinates can re-derive them from fvar.
+      class NamedInstance < Lutaml::Model::Serializable
+        attribute :subfamily_name,  :string
+        attribute :postscript_name, :string
+        attribute :coordinates,     :string
+
+        key_value do
+          map "subfamily_name",  to: :subfamily_name
+          map "postscript_name", to: :postscript_name
+          map "coordinates",     to: :coordinates
+        end
+
+        # Build the coordinates string from a parallel array of axis tags
+        # and fvar coordinate values. Returns nil if either side is empty.
+        #
+        # @param axis_tags [Array<String>] ordered axis tags (e.g. ["wght", "wdth"])
+        # @param values [Array<Numeric>] ordered coordinate values
+        # @return [String, nil]
+        def self.format_coordinates(axis_tags, values)
+          return nil if axis_tags.nil? || values.nil?
+          return nil if axis_tags.empty? || values.empty?
+
+          pairs = axis_tags.zip(values).map { |tag, val| "#{tag}=#{val}" }
+          pairs.join(",")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Fontisan
+  module Models
+    module Audit
+      # Structured OpenType layout summary for one face.
+      #
+      # Replaces the previous flat `opentype_scripts` + `features` pair
+      # on AuditReport for MECE cleanliness. Carries:
+      #
+      # - `scripts`: union of GSUB + GPOS script tags (sorted, unique).
+      # - `features`: union of GSUB + GPOS feature tags across every
+      #   script (sorted, unique).
+      # - `by_script`: per-script breakdown preserving the
+      #   "feature X is for script Y" relationship that the flat arrays
+      #   discarded.
+      # - `has_gsub` / `has_gpos`: presence flags so consumers can tell
+      #   "font has no layout" from "font has GSUB but no GPOS".
+      #
+      # nil for Type 1 fonts (no SFNT table structure).
+      class OpenTypeLayout < Lutaml::Model::Serializable
+        attribute :scripts,   :string,         collection: true
+        attribute :features,  :string,         collection: true
+        attribute :by_script, ScriptFeatures,  collection: true
+        attribute :has_gsub,  Lutaml::Model::Type::Boolean
+        attribute :has_gpos,  Lutaml::Model::Type::Boolean
+
+        key_value do
+          map "scripts",   to: :scripts
+          map "features",  to: :features
+          map "by_script", to: :by_script
+          map "has_gsub",  to: :has_gsub
+          map "has_gpos",  to: :has_gpos
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Fontisan
+  module Models
+    module Audit
+      # One row in a LibrarySummary's script-coverage matrix.
+      #
+      # Lists every face (by postscript_name) whose cmap covers at least
+      # one codepoint assigned to a Unicode script. Lets a librarian
+      # answer "which fonts cover Cyrillic?" without re-auditing.
+      class ScriptCoverageRow < Lutaml::Model::Serializable
+        attribute :script, :string
+        attribute :face_count, :integer
+        attribute :faces, :string, collection: true
+
+        key_value do
+          map "script", to: :script
+          map "face_count", to: :face_count
+          map "faces", to: :faces
+        end
+      end
+    end
+  end
+end