fontisan 0.2.17 → 0.2.22

data/lib/fontisan/audit/extractors.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Autoload hub for the Fontisan::Audit::Extractors namespace.
+#
+# Each extractor is a small MECE class with a single `#extract(context)`
+# method returning a hash of AuditReport fields. The Audit::Registry
+# declares the ordered list.
+
+module Fontisan
+  module Audit
+    module Extractors
+      autoload :Base, "fontisan/audit/extractors/base"
+      autoload :Provenance, "fontisan/audit/extractors/provenance"
+      autoload :Identity, "fontisan/audit/extractors/identity"
+      autoload :Style, "fontisan/audit/extractors/style"
+      autoload :Licensing, "fontisan/audit/extractors/licensing"
+      autoload :Metrics, "fontisan/audit/extractors/metrics"
+      autoload :Hinting, "fontisan/audit/extractors/hinting"
+      autoload :ColorCapabilities, "fontisan/audit/extractors/color_capabilities"
+      autoload :VariationDetail, "fontisan/audit/extractors/variation_detail"
+      autoload :OpenTypeLayout, "fontisan/audit/extractors/opentype_layout"
+      autoload :Coverage, "fontisan/audit/extractors/coverage"
+      autoload :Aggregations, "fontisan/audit/extractors/aggregations"
+      autoload :LanguageCoverage, "fontisan/audit/extractors/language_coverage"
+    end
+  end
+end

data/lib/fontisan/audit/library_aggregator.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Audit
+    # Pure cross-face aggregation over a list of AuditReports.
+    #
+    # No I/O, no font parsing — operates only on already-built reports.
+    # Easy to spec with synthetic reports and trivially testable. The
+    # orchestrator ({LibraryAuditor}) handles file discovery and per-face
+    # auditing; this class owns the rollups that span faces.
+    #
+    # Aggregates:
+    #   - aggregate_metrics: sum of total_codepoints and total_glyphs.
+    #   - script_coverage:   one ScriptCoverageRow per Unicode script,
+    #                         listing faces that cover it.
+    #   - duplicate_groups:  files bucketed by source_sha256 (size > 1).
+    #   - license_distribution: face counts keyed by license_url.
+    class LibraryAggregator
+      # @param reports [Array<Models::Audit::AuditReport>]
+      # @return [Hash{Symbol => Object}] keys: :aggregate_metrics,
+      #   :script_coverage, :duplicate_groups, :license_distribution
+      def aggregate(reports)
+        {
+          aggregate_metrics: aggregate_metrics(reports),
+          script_coverage: build_script_coverage(reports),
+          duplicate_groups: find_duplicates(reports),
+          license_distribution: license_distribution(reports),
+        }
+      end
+
+      private
+
+      def aggregate_metrics(reports)
+        {
+          total_codepoints: reports.sum(&:total_codepoints),
+          total_glyphs: reports.sum(&:total_glyphs),
+        }
+      end
+
+      def build_script_coverage(reports)
+        by_script = Hash.new { |h, k| h[k] = [] }
+        reports.each do |report|
+          face = report.postscript_name || report.source_file
+          scripts_for(report).each { |script| by_script[script] << face }
+        end
+        by_script.map do |script, faces|
+          Models::Audit::ScriptCoverageRow.new(
+            script: script,
+            face_count: faces.size,
+            faces: faces.uniq.sort,
+          )
+        end.sort_by { |row| [-row.face_count, row.script] }
+      end
+
+      def find_duplicates(reports)
+        reports.group_by(&:source_sha256)
+          .select { |_sha, group| group.size > 1 }
+          .map do |sha, group|
+            Models::Audit::DuplicateGroup.new(
+              source_sha256: sha,
+              files: group.map(&:source_file).sort,
+            )
+          end
+          .sort_by(&:source_sha256)
+      end
+
+      def license_distribution(reports)
+        reports.each_with_object({}) do |report, counts|
+          url = license_url_for(report)
+          counts[url] = counts.fetch(url, 0) + 1
+        end
+      end
+
+      def scripts_for(report)
+        Array(report.unicode_scripts)
+      end
+
+      def license_url_for(report)
+        report.licensing&.license_url || "(none)"
+      end
+    end
+  end
+end

data/lib/fontisan/audit/library_auditor.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Fontisan
+  module Audit
+    # Orchestrates a library-wide audit pass.
+    #
+    # Owns the file-system side: discovers font files under a root path
+    # (recursively or not), audits each via {Commands::AuditCommand},
+    # and assembles a {Models::Audit::LibrarySummary} combining the
+    # per-face reports with cross-face rollups from {LibraryAggregator}.
+    #
+    # Aggregation logic lives in the pure {LibraryAggregator}; this
+    # class stays focused on discovery + per-face auditing + summary
+    # assembly. Errors auditing a single file are logged and skipped so
+    # a corrupt file doesn't abort the whole pass.
+    class LibraryAuditor
+      FONT_EXTENSIONS = %w[.ttf .otf .ttc .otc .dfont .woff .woff2
+                           .pfb .pfa .svg].freeze
+
+      # @param root_path [String, Pathname] directory containing fonts
+      # @param recursive [Boolean] walk into subdirectories
+      # @param options [Hash] forwarded to AuditCommand (minus library-only keys)
+      def initialize(root_path, recursive:, options:)
+        @root_path = Pathname.new(root_path)
+        @recursive = recursive
+        @options = options
+        @aggregator = LibraryAggregator.new
+        @skipped = []
+      end
+
+      # @return [Models::Audit::LibrarySummary]
+      def audit
+        paths = discover_font_paths
+        reports = paths.flat_map { |p| audit_one(p) }
+        rolled_up = aggregates(reports)
+
+        Models::Audit::LibrarySummary.new(
+          root_path: @root_path.to_s,
+          total_files: paths.size,
+          total_faces: reports.size,
+          scanned_extensions: scanned_extensions(paths),
+          aggregate_metrics: rolled_up[:aggregate_metrics].merge(
+            total_size_bytes: paths.sum { |p| File.size(p) },
+          ),
+          script_coverage: rolled_up[:script_coverage],
+          duplicate_groups: rolled_up[:duplicate_groups],
+          license_distribution: rolled_up[:license_distribution],
+          per_face_reports: reports,
+        )
+      end
+
+      # @return [Array<String>] source files that could not be audited
+      attr_reader :skipped
+
+      private
+
+      def discover_font_paths
+        method = @recursive ? :find : :children
+        @root_path.public_send(method).select do |entry|
+          next false unless entry.file?
+          next false if entry.symlink?
+
+          FONT_EXTENSIONS.include?(entry.extname.downcase)
+        end.map(&:to_s).sort
+      end
+
+      def audit_one(path)
+        Array(Commands::AuditCommand.new(path, audit_options).run)
+      rescue StandardError => e
+        @skipped << "#{path}: #{e.message}"
+        []
+      end
+
+      # Drop library-only options before forwarding to AuditCommand.
+      def audit_options
+        @options.except(:recursive, :summary, :output)
+      end
+
+      def scanned_extensions(paths)
+        paths.map { |p| File.extname(p).downcase }.uniq.sort
+      end
+
+      def aggregates(reports)
+        @aggregator.aggregate(reports)
+      end
+    end
+  end
+end

data/lib/fontisan/audit/registry.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Audit
+    # Ordered list of extractor classes run for every audit face.
+    #
+    # Order matters only for human-readable output (text formatter).
+    # All extractors are independent; their outputs are merged into
+    # one big hash before constructing the AuditReport.
+    #
+    # Add new extractors here. AuditCommand never enumerates them
+    # directly (OCP: adding a concern = one line here + one file).
+    module Registry
+      # Full audit: every concern.
+      ORDERED_EXTRACTORS = [
+        Extractors::Provenance,
+        Extractors::Identity,
+        Extractors::Style,
+        Extractors::Licensing,
+        Extractors::Metrics,
+        Extractors::Hinting,
+        Extractors::ColorCapabilities,
+        Extractors::VariationDetail,
+        Extractors::OpenTypeLayout,
+        Extractors::Coverage,
+        Extractors::Aggregations,
+        Extractors::LanguageCoverage,
+      ].freeze
+
+      # Brief audit: only the cheap, name-table-only extractors. Skips
+      # metrics/hinting/color/variation/layout (extra table loads) and
+      # aggregations/language coverage (need UCD/CLDR indices). Used by
+      # `fontisan audit --brief` for a fast inventory pass.
+      BRIEF_EXTRACTORS = [
+        Extractors::Provenance,
+        Extractors::Identity,
+        Extractors::Style,
+        Extractors::Licensing,
+        Extractors::Coverage,
+      ].freeze
+
+      # Iterate the extractors appropriate for the given mode.
+      #
+      # @param mode [Symbol] :full (default) or :brief
+      # @yieldparam extractor_class [Class]
+      def self.each(mode: :full, &)
+        extractors_for(mode).each(&)
+      end
+
+      # @param mode [Symbol] :full or :brief
+      # @return [Array<Class>] the extractor list for the given mode
+      def self.extractors_for(mode)
+        case mode
+        when :brief then BRIEF_EXTRACTORS
+        else ORDERED_EXTRACTORS
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/audit/style_extractor.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Audit
+    # Extracts style descriptors from a loaded font's OS/2 and head tables.
+    # One extractor per font; cheap to construct.
+    #
+    # All fields return nil when the underlying table is absent or the
+    # value is unset (e.g., Type 1 fonts have no OS/2). Callers must
+    # tolerate nils.
+    #
+    # Scope: OS/2 + head only. fvar-derived fields (axes, named instances,
+    # variable presence) live on {Extractors::VariationDetail} — this is
+    # the MECE split between static style metadata and variation metadata.
+    #
+    # Duck typing: uses only `font.has_table?(tag)` and `font.table(tag)`.
+    # No class-specific branching — any object that honors the SFNT
+    # contract works (TrueTypeFont, OpenTypeFont, WoffFont, Woff2Font,
+    # and individual faces from collections).
+    class StyleExtractor
+      FS_SELECTION_ITALIC_BIT = 0
+      MAC_STYLE_BOLD_BIT      = 0
+      private_constant :FS_SELECTION_ITALIC_BIT, :MAC_STYLE_BOLD_BIT
+
+      # @param font [Object] an SFNT-compatible font object
+      def initialize(font)
+        @font = font
+      end
+
+      def weight_class
+        os2&.us_weight_class&.to_i
+      end
+
+      def width_class
+        os2&.us_width_class&.to_i
+      end
+
+      # OS/2.fsSelection bit 0 (ITALIC).
+      def italic
+        return nil unless os2
+
+        (os2.fs_selection.to_i & (1 << FS_SELECTION_ITALIC_BIT)).nonzero?
+      end
+
+      # head.macStyle bit 0 (BOLD). Per OpenType convention, bold is read
+      # from head, not OS/2.
+      def bold
+        return nil unless head
+
+        (head.mac_style.to_i & (1 << MAC_STYLE_BOLD_BIT)).nonzero?
+      end
+
+      # OS/2.panose as a space-joined 10-digit string, e.g. "2 0 5 3 0 0 0 0 0 0".
+      # Returns nil if there is no OS/2 table.
+      def panose
+        bytes = os2&.panose
+        return nil if bytes.nil?
+
+        bytes = bytes.to_a
+        return nil if bytes.empty?
+
+        bytes.join(" ")
+      end
+
+      private
+
+      def os2
+        return @os2 if defined?(@os2)
+
+        @os2 = @font.has_table?("OS/2") ? @font.table("OS/2") : nil
+      end
+
+      def head
+        return @head if defined?(@head)
+
+        @head = @font.has_table?("head") ? @font.table("head") : nil
+      end
+    end
+  end
+end

data/lib/fontisan/audit.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Autoload hub for the Fontisan::Audit namespace.
+#
+# AuditCommand (under Commands::AuditCommand) builds a Context and
+# runs every extractor in Audit::Registry, merging their outputs
+# into a single AuditReport.
+
+module Fontisan
+  module Audit
+    autoload :Context, "fontisan/audit/context"
+    autoload :CodepointRangeCoalescer, "fontisan/audit/codepoint_range_coalescer"
+    autoload :Differ, "fontisan/audit/differ"
+    autoload :LibraryAggregator, "fontisan/audit/library_aggregator"
+    autoload :LibraryAuditor, "fontisan/audit/library_auditor"
+    autoload :Registry, "fontisan/audit/registry"
+    autoload :Extractors, "fontisan/audit/extractors"
+    autoload :StyleExtractor, "fontisan/audit/style_extractor"
+  end
+end

data/lib/fontisan/base_collection.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
 require "bindata"
-require_relative "constants"
-require_relative "collection/shared_logic"
 
 module Fontisan
   # Abstract base class for font collections (TTC/OTC)
@@ -118,6 +116,29 @@ module Fontisan
       num_fonts
     end
 
+    # Whether this object represents a font collection rather than a single
+    # font. Each font class is the authority on this question.
+    #
+    # @return [Boolean]
+    def collection? = true
+
+    # Variation profile. Collections are containers; per-font variation is
+    # not exposed at the collection level.
+    #
+    # @return [Symbol] :static
+    def variation_type = :static
+
+    # Outline representation. Collections may contain mixed-flavor fonts;
+    # per-font outline type requires loading an individual font.
+    #
+    # @return [Symbol] :unknown
+    def outline_type = :unknown
+
+    # Collections have no single SFNT table directory.
+    #
+    # @return [Array<String>] empty
+    def table_names = []
+
     # Validate format correctness
     #
     # @return [Boolean] true if the format is valid, false otherwise
@@ -156,10 +177,6 @@ module Fontisan
     #     list.fonts.each { |f| puts "#{f.index}: #{f.family_name}" }
     #   end
     def list_fonts(io)
-      require_relative "models/collection_list_info"
-      require_relative "models/collection_font_summary"
-      require_relative "tables/name"
-
       font_class = self.class.font_class
 
       fonts = font_offsets.map.with_index do |offset, index|
@@ -222,9 +239,6 @@ module Fontisan
     #     puts "Version: #{info.version_string}"
     #   end
     def collection_info(io, path)
-      require_relative "models/collection_info"
-      require_relative "models/table_sharing_info"
-
       # Calculate table sharing statistics
       table_sharing = calculate_table_sharing(io)
 

data/lib/fontisan/binary/structures.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "base_record"
-
 module Fontisan
   module Binary
     # OpenType Offset Table (Font Header)

data/lib/fontisan/binary.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Autoload hub for the Fontisan::Binary namespace.
+
+module Fontisan
+  module Binary
+    autoload :BaseRecord, "fontisan/binary/base_record"
+    autoload :OffsetTable, "fontisan/binary/structures"
+    autoload :TableDirectoryEntry, "fontisan/binary/structures"
+  end
+end

data/lib/fontisan/cldr/aggregator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Cldr
+    # Produces audit-ready per-language coverage from a codepoint list
+    # and a Cldr::Index of per-language exemplar sets.
+    #
+    # Pure: no I/O, no side effects.
+    module Aggregator
+      module_function
+
+      # @param codepoints [Enumerable<Integer>] font's codepoints
+      # @param languages_index [Cldr::Index]
+      # @return [Array<Models::Cldr::LanguageCoverage>] sorted by
+      #   descending coverage_ratio, then by language name
+      def aggregate(codepoints, languages_index)
+        font_set = Set.new(codepoints)
+
+        languages_index.entries.map do |lang, required_set|
+          covered = (font_set & required_set).size
+          total = required_set.size
+          Models::Cldr::LanguageCoverage.new(
+            language: lang,
+            covered: covered,
+            total: total,
+            coverage_ratio: total.zero? ? 0.0 : covered.fdiv(total).round(4),
+            fully_supported: total.positive? && covered == total,
+          )
+        end.sort_by { |lc| [lc.coverage_ratio * -1, lc.language] }
+      end
+    end
+  end
+end

data/lib/fontisan/cldr/cache_manager.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Fontisan
+  module Cldr
+    # Manages the on-disk CLDR cache layout.
+    #
+    # Cache root resolution honors `XDG_CONFIG_HOME` per the XDG Base
+    # Directory Specification. Falls back to `~/.config` on Unix.
+    #
+    # Layout:
+    #
+    #   <root>/
+    #     <version>/
+    #       json/                 # extracted CLDR JSON archive
+    #         cldr-json/
+    #           cldr-characters-full/
+    #             main/<lang>/characters.json
+    #       index/
+    #         languages.yml       # built index of per-language codepoint sets
+    #
+    # No network access — all methods are pure filesystem operations.
+    module CacheManager
+      LANGUAGES_INDEX_FILENAME = "languages.yml"
+      private_constant :LANGUAGES_INDEX_FILENAME
+
+      class << self
+        # Root path of the CLDR cache.
+        # @return [Pathname]
+        def root
+          base = xdg_config_home || File.join(Dir.home, ".config")
+          Pathname.new(base).join("fontisan", "cldr")
+        end
+
+        # Per-version directory.
+        # @param version [String] e.g. "46.0.0"
+        # @return [Pathname]
+        def version_dir(version)
+          root.join(version)
+        end
+
+        # Directory where the raw CLDR JSON archive is extracted.
+        # @param version [String]
+        # @return [Pathname]
+        def json_dir(version)
+          version_dir(version).join("json")
+        end
+
+        # Directory containing the per-language characters.json files
+        # inside the extracted archive.
+        # @param version [String]
+        # @return [Pathname]
+        def characters_main_dir(version)
+          json_dir(version).join("cldr-json", "cldr-characters-full", "main")
+        end
+
+        # Directory holding the derived language index for a version.
+        # @param version [String]
+        # @return [Pathname]
+        def index_dir(version)
+          version_dir(version).join("index")
+        end
+
+        def languages_index_path(version)
+          index_dir(version).join(LANGUAGES_INDEX_FILENAME)
+        end
+
+        # True if the extracted JSON archive is present for this version.
+        # @param version [String]
+        # @return [Boolean]
+        def cached?(version)
+          characters_main_dir(version).exist?
+        end
+
+        # All versions currently in the cache (sorted ascending).
+        # @return [Array<String>]
+        def cached_versions
+          return [] unless root.exist?
+
+          root.children.select(&:directory?).map { |p| p.basename.to_s }.sort
+        end
+
+        # Create the version directory and json/index subdirs.
+        # Idempotent.
+        # @param version [String]
+        def ensure_version_dir!(version)
+          json_dir(version).mkpath
+          index_dir(version).mkpath
+        end
+
+        # Remove a version from the cache. No-op if absent.
+        # @param version [String]
+        def remove_version(version)
+          dir = version_dir(version)
+          dir.rmtree if dir.exist?
+        end
+
+        private
+
+        def xdg_config_home
+          env = ENV["XDG_CONFIG_HOME"]
+          return nil if env.nil? || env.empty?
+
+          env
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/cldr/config.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Fontisan
+  module Cldr
+    # Single source of truth for CLDR version selection.
+    #
+    # Wraps `lib/fontisan/config/cldr.yml`. Loads the YAML once at first
+    # access and memoizes. All other Cldr::* classes resolve versions,
+    # URLs, and known-version validation through this module.
+    module Config
+      CONFIG_PATH = File.expand_path("../config/cldr.yml", __dir__)
+      private_constant :CONFIG_PATH
+
+      class << self
+        # The CLDR version Fontisan uses by default for auto-download and
+        # `fontisan cldr download` (no args). String like "46.0.0".
+        def default_version
+          data[:default_version]
+        end
+
+        # Array of CLDR version strings this Fontisan release recognizes.
+        # Used by VersionResolver to reject unknown versions early.
+        def known_versions
+          data[:known_versions]
+        end
+
+        # Base URL for fetching CLDR JSON artifacts.
+        def base_url
+          data[:base_url]
+        end
+
+        # Listing URL for `--latest` probing.
+        def listing_url
+          data[:listing_url]
+        end
+
+        # Full URL to the CLDR JSON full archive for a version.
+        # @param version [String] e.g. "46.0.0"
+        # @return [String]
+        def archive_url_for(version)
+          "#{base_url}/#{version}/cldr-#{version}-json-full.zip"
+        end
+
+        # True if the version appears in `known_versions`.
+        def known?(version)
+          known_versions.include?(version)
+        end
+
+        private
+
+        def data
+          @data ||= YAML.load_file(CONFIG_PATH).transform_keys(&:to_sym)
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/cldr/download_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Cldr
+    # Raised by Cldr::Downloader when the upstream HTTP fetch or the zip
+    # extraction fails. Caught by AuditCommand to degrade-with-warning.
+    class DownloadError < Cldr::Error; end
+  end
+end