fontisan 0.2.16 → 0.2.22

data/lib/fontisan/ucd/aggregator.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Ucd
+    # Produces audit-ready aggregations from a codepoint list + UCD indices.
+    #
+    # Pure: no I/O, no side effects. Caller passes the codepoints and the
+    # blocks/scripts indices; Aggregator returns the aggregated summaries.
+    module Aggregator
+      module_function
+
+      # Aggregate codepoints per Unicode block.
+      #
+      # Returns one hash per overlapping block, sorted by first_cp:
+      #
+      #   { name:, first_cp:, last_cp:, total:, covered:, fill_ratio:, complete: }
+      #
+      # @param codepoints [Array<Integer>] sorted not required
+      # @param blocks_index [Index]
+      # @return [Array<Hash>]
+      def aggregate_blocks(codepoints, blocks_index)
+        sorted = codepoints.sort
+        return [] if sorted.empty?
+
+        coverage = Hash.new { |h, k| h[k] = 0 }
+        coverage.compare_by_identity
+        first_cp = sorted.first
+        last_cp = sorted.last
+
+        overlapping = blocks_index.each_overlapping(first_cp, last_cp).to_a
+        overlapping.each do |entry|
+          coverage[entry] = count_in_range(sorted, [entry.first_cp, entry.last_cp])
+        end
+
+        overlapping.map do |entry|
+          covered = coverage[entry]
+          total = entry.size
+          {
+            name: entry.name,
+            first_cp: entry.first_cp,
+            last_cp: entry.last_cp,
+            total: total,
+            covered: covered,
+            fill_ratio: covered.fdiv(total).round(4),
+            complete: covered == total,
+          }
+        end
+      end
+
+      # Aggregate unique script names from codepoints.
+      #
+      # @param codepoints [Array<Integer>]
+      # @param scripts_index [Index]
+      # @return [Array<String>] sorted unique script names
+      def aggregate_scripts(codepoints, scripts_index)
+        scripts = codepoints.filter_map { |cp| scripts_index.lookup(cp) }
+        scripts.uniq.sort
+      end
+
+      # Count codepoints in `sorted` that fall within [first, last].
+      # `sorted` must be sorted ascending.
+      def count_in_range(sorted, range)
+        first, last = range
+        left = sorted.bsearch_index { |cp| cp >= first } || sorted.size
+        return 0 if left == sorted.size
+
+        right = sorted.bsearch_index { |cp| cp > last } || sorted.size
+        right - left
+      end
+      private_class_method :count_in_range
+    end
+  end
+end

data/lib/fontisan/ucd/cache_manager.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Fontisan
+  module Ucd
+    # Manages the on-disk UCD cache layout.
+    #
+    # Cache root resolution honors `XDG_CONFIG_HOME` per the XDG Base
+    # Directory Specification. Falls back to `~/.config` on Unix and
+    # `~/.config` (literal) elsewhere — consistent with other Fontisan
+    # config paths.
+    #
+    # Layout:
+    #
+    #   <root>/
+    #     <version>/
+    #       ucdxml/
+    #         ucd.all.flat.xml
+    #       index/
+    #         blocks.yml
+    #         scripts.yml
+    #
+    # No network access — all methods are pure filesystem operations.
+    module CacheManager
+      UCDXML_FILENAME = "ucd.all.flat.xml"
+      private_constant :UCDXML_FILENAME
+
+      BLOCKS_INDEX_FILENAME = "blocks.yml"
+      SCRIPTS_INDEX_FILENAME = "scripts.yml"
+      private_constant :BLOCKS_INDEX_FILENAME, :SCRIPTS_INDEX_FILENAME
+
+      class << self
+        # Root path of the UCD cache.
+        # @return [Pathname]
+        def root
+          base = xdg_config_home || File.join(Dir.home, ".config")
+          Pathname.new(base).join("fontisan", "unicode")
+        end
+
+        # Per-version directory.
+        # @param version [String] e.g. "17.0.0"
+        # @return [Pathname]
+        def version_dir(version)
+          root.join(version)
+        end
+
+        # Path to the unpacked UCDXML flat file for a version.
+        # @param version [String]
+        # @return [Pathname]
+        def ucdxml_path(version)
+          version_dir(version).join("ucdxml", UCDXML_FILENAME)
+        end
+
+        # Directory holding the derived RLE indices for a version.
+        # @param version [String]
+        # @return [Pathname]
+        def index_dir(version)
+          version_dir(version).join("index")
+        end
+
+        def blocks_index_path(version)
+          index_dir(version).join(BLOCKS_INDEX_FILENAME)
+        end
+
+        def scripts_index_path(version)
+          index_dir(version).join(SCRIPTS_INDEX_FILENAME)
+        end
+
+        # True if the UCDXML file is present for this version.
+        # @param version [String]
+        # @return [Boolean]
+        def cached?(version)
+          ucdxml_path(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 ucdxml/index subdirs.
+        # Idempotent.
+        # @param version [String]
+        def ensure_version_dir!(version)
+          ucdxml_path(version).dirname.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/ucd/config.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Fontisan
+  module Ucd
+    # Single source of truth for UCD version selection.
+    #
+    # Wraps `lib/fontisan/config/ucd.yml`. Loads the YAML once at first
+    # access and memoizes. All other Ucd::* classes resolve versions,
+    # URLs, and known-version validation through this module.
+    module Config
+      CONFIG_PATH = File.expand_path("../config/ucd.yml", __dir__)
+      private_constant :CONFIG_PATH
+
+      class << self
+        # The version Fontisan uses by default for auto-download and
+        # `fontisan ucd download` (no args). String like "17.0.0".
+        def default_version
+          data[:default_version]
+        end
+
+        # Array of 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 UCDXML artifacts.
+        def base_url
+          data[:base_url]
+        end
+
+        # Listing URL for `--latest` probing.
+        def listing_url
+          data[:listing_url]
+        end
+
+        # Full URL to the UCDXML flat zip for a given version.
+        # @param version [String] e.g. "17.0.0"
+        # @return [String]
+        def ucdxml_url_for(version)
+          "#{base_url}/#{version}/ucdxml/ucd.all.flat.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/ucd/download_error.rb

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

data/lib/fontisan/ucd/downloader.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "tempfile"
+require "zip"
+
+module Fontisan
+  module Ucd
+    # Fetches UCDXML zips from unicode.org and unpacks them into the cache.
+    #
+    # Single entry point: `Downloader.download(version, force:)`.
+    # Idempotent unless `force: true`. Returns the path to the unpacked
+    # `ucd.all.flat.xml`.
+    module Downloader
+      UCDXML_ZIP_ENTRY = "ucd.all.flat.xml"
+      private_constant :UCDXML_ZIP_ENTRY
+
+      class << self
+        # Download and unpack UCDXML for `version`.
+        #
+        # @param version [String] e.g. "17.0.0"
+        # @param force [Boolean] if false and cache already has the file,
+        #   return the existing path without re-fetching.
+        # @return [Pathname] path to the unpacked ucd.all.flat.xml
+        # @raise [DownloadError] on HTTP failure or zip extraction failure
+        def download(version, force: false)
+          target = CacheManager.ucdxml_path(version)
+          return target if target.exist? && !force
+
+          CacheManager.ensure_version_dir!(version)
+          zip_data = fetch_zip(version)
+          extract_xml(zip_data, target)
+          target
+        end
+
+        private
+
+        def fetch_zip(version)
+          uri = URI(Config.ucdxml_url_for(version))
+          response = Net::HTTP.get_response(uri)
+          unless response.is_a?(Net::HTTPSuccess)
+            raise DownloadError,
+                  "GET #{uri} returned HTTP #{response.code}: #{response.message}"
+          end
+
+          body = response.body
+          if body.nil? || body.empty?
+            raise DownloadError, "GET #{uri} returned an empty body"
+          end
+
+          body
+        rescue StandardError => e
+          raise e if e.is_a?(DownloadError)
+
+          raise DownloadError, "Failed to fetch #{uri}: #{e.message}"
+        end
+
+        def extract_xml(zip_data, target)
+          Tempfile.create(["fontisan-ucd", ".zip"]) do |tmp|
+            tmp.binmode
+            tmp.write(zip_data)
+            tmp.flush
+            tmp.rewind
+
+            write_xml_entry(tmp.path, target)
+          end
+        end
+
+        def write_xml_entry(zip_path, target)
+          Zip::File.open(zip_path) do |zip|
+            entry = zip.find_entry(UCDXML_ZIP_ENTRY) ||
+              zip.glob("#{UCDXML_ZIP_ENTRY}*", include_directories: false).first
+            unless entry
+              raise DownloadError,
+                    "UCDXML zip did not contain #{UCDXML_ZIP_ENTRY.inspect}"
+            end
+
+            # Atomic-ish: write to .part then rename.
+            partial = target.sub_ext(".xml.part")
+            zip.extract(entry, partial.to_s) { true } # overwrite
+            File.rename(partial.to_s, target.to_s)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/ucd/error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Ucd
+    # Base error class for all UCD-related failures.
+    class Error < StandardError; end
+  end
+end

data/lib/fontisan/ucd/index.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "yaml"
+
+module Fontisan
+  module Ucd
+    # Sorted, run-length-encoded lookup table over Unicode codepoints.
+    #
+    # One Index answers "what <thing> does codepoint N belong to?" for one
+    # property (block, or script). Lookup is O(log N) via bsearch.
+    class Index
+      include Enumerable
+
+      # @param entries [Array<RangeEntry>] sorted, disjoint
+      def initialize(entries)
+        @entries = entries.sort
+      end
+
+      # @return [Array<RangeEntry>]
+      attr_reader :entries
+
+      def each(&)
+        @entries.each(&)
+      end
+
+      def size
+        @entries.size
+      end
+
+      # @param codepoint [Integer] Unicode codepoint
+      # @return [String, nil] the name of the range covering `codepoint`, or nil
+      def lookup(codepoint)
+        idx = bsearch_index(codepoint)
+        idx && @entries[idx].name
+      end
+
+      # Enumerate every range whose [first_cp, last_cp] overlaps the
+      # inclusive query range.
+      # @param first [Integer]
+      # @param last [Integer]
+      # @return [Enumerator<RangeEntry>]
+      def each_overlapping(first, last, &)
+        return enum_for(:each_overlapping, first, last) unless block_given?
+
+        start_idx = bsearch_first_overlap(first)
+        return if start_idx.nil?
+
+        @entries[start_idx..].each do |entry|
+          break if entry.first_cp > last
+
+          yield entry if entry.last_cp >= first
+        end
+      end
+
+      # Serialize to a YAML file.
+      # @param path [String, Pathname]
+      # @return [void]
+      def save(path)
+        File.open(path, "w") do |file|
+          YAML.dump(@entries.map(&:to_h), file)
+        end
+      end
+
+      # Load from a YAML file previously written by #save.
+      # @param path [String, Pathname] (required)
+      # @return [Index]
+      def self.load(path)
+        hashes = YAML.load_file(path)
+        new(hashes.map { |h| RangeEntry.from_h(h) })
+      end
+
+      # Build an Index from raw [first_cp, last_cp, name] triples.
+      # @param triples [Array<Array(Integer, Integer, String)>]
+      # @return [Index]
+      def self.from_triples(triples)
+        new(triples.map { |first, last, name| RangeEntry.new(first, last, name) })
+      end
+
+      private
+
+      # Binary search for the entry whose range contains `codepoint`.
+      # Returns the index in @entries, or nil.
+      def bsearch_index(codepoint)
+        @entries.bsearch_index do |entry|
+          if codepoint < entry.first_cp
+            -1
+          elsif codepoint > entry.last_cp
+            1
+          else
+            0
+          end
+        end
+      end
+
+      # Find the first entry whose last_cp >= `first`. Returns nil if no
+      # entry overlaps anything >= `first`.
+      def bsearch_first_overlap(first)
+        @entries.bsearch_index { |entry| entry.last_cp >= first }
+      end
+    end
+  end
+end

data/lib/fontisan/ucd/index_builder.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Ucd
+    # Turns a parsed Models::Ucd::Ucd instance into two compact
+    # run-length-encoded indices (blocks + scripts), and persists them to
+    # the cache for future Index loads.
+    #
+    # Index layout on disk (YAML):
+    #
+    #   <root>/<version>/index/
+    #     blocks.yml
+    #     scripts.yml
+    #
+    # Each file is an array of `{ first_cp:, last_cp:, name: }` hashes,
+    # sorted by first_cp, disjoint.
+    module IndexBuilder
+      class << self
+        # Build + persist both indices for a cached version.
+        # @param version [String]
+        # @return [Array(Index, Index)] blocks_index, scripts_index
+        def build(version)
+          ucd = load_ucd(version)
+          blocks, scripts = build_from_ucd(ucd)
+          CacheManager.index_dir(version).mkpath
+          blocks.save(CacheManager.blocks_index_path(version))
+          scripts.save(CacheManager.scripts_index_path(version))
+          [blocks, scripts]
+        end
+
+        # Pure: build both indices from an in-memory Ucd model.
+        # @param ucd [Models::Ucd::Ucd]
+        # @return [Array(Index, Index)]
+        def build_from_ucd(ucd)
+          blocks_runs = collect_runs(ucd, :block)
+          scripts_runs = collect_runs(ucd, :script)
+          [Index.new(to_entries(blocks_runs)), Index.new(to_entries(scripts_runs))]
+        end
+
+        private
+
+        def load_ucd(version)
+          path = CacheManager.ucdxml_path(version)
+          xml = File.read(path)
+          Models::Ucd::Ucd.from_xml(xml)
+        end
+
+        # Walk all UcdChar entries, group by the given property
+        # (:block or :script), and accumulate codepoint ranges per name.
+        # Returns Hash<String, Array<[Integer, Integer]>>.
+        def collect_runs(ucd, property)
+          runs_by_name = Hash.new { |h, k| h[k] = [] }
+
+          ucd.chars.each do |char|
+            name = char.public_send(property)
+            next if name.nil? || name.empty?
+
+            ranges_for_char(char).each do |first, last|
+              runs_by_name[name] << [first, last]
+            end
+          end
+
+          runs_by_name.each_value { |runs| coalesce!(runs) }
+          runs_by_name
+        end
+
+        # Returns Array<[Integer, Integer]> — the codepoint range(s) this
+        # char covers.
+        def ranges_for_char(char)
+          if char.range?
+            [[char.first_cp.to_i(16), char.last_cp.to_i(16)]]
+          elsif char.cp
+            cp_int = char.cp.to_i(16)
+            [[cp_int, cp_int]]
+          else
+            []
+          end
+        end
+
+        # Sort + merge adjacent/overlapping ranges in place.
+        # Input: Array<[Integer, Integer]>, mutated.
+        def coalesce!(runs)
+          return if runs.empty?
+
+          runs.sort!
+          merged = [runs.first]
+          runs[1..].each do |first, last|
+            prev = merged.last
+            if first <= prev[1] + 1
+              prev[1] = [prev[1], last].max
+            else
+              merged << [first, last]
+            end
+          end
+          runs.replace(merged)
+        end
+
+        # Flatten {name => [[first,last],...]} into Array<RangeEntry>.
+        def to_entries(runs_by_name)
+          runs_by_name.flat_map do |name, runs|
+            runs.map { |first, last| RangeEntry.new(first, last, name) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/ucd/range_entry.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Ucd
+    # Value object representing one row in a run-length-encoded UCD index.
+    #
+    # Sorted by `first_cp`. Entries within a single Index are disjoint
+    # (no overlapping ranges).
+    class RangeEntry
+      include Comparable
+
+      attr_reader :first_cp, :last_cp, :name
+
+      def initialize(first_cp, last_cp, name)
+        @first_cp = first_cp
+        @last_cp = last_cp
+        @name = name
+      end
+
+      def covers?(codepoint)
+        codepoint >= @first_cp && codepoint <= @last_cp
+      end
+
+      def size
+        @last_cp - @first_cp + 1
+      end
+
+      def <=>(other)
+        [@first_cp, @last_cp] <=> [other.first_cp, other.last_cp]
+      end
+
+      def ==(other)
+        other.is_a?(RangeEntry) &&
+          @first_cp == other.first_cp &&
+          @last_cp == other.last_cp &&
+          @name == other.name
+      end
+      alias eql? ==
+
+      def hash
+        [@first_cp, @last_cp, @name].hash
+      end
+
+      # Compact YAML-friendly form.
+      def to_h
+        { first_cp: @first_cp, last_cp: @last_cp, name: @name }
+      end
+
+      def self.from_h(hash)
+        new(hash[:first_cp] || hash["first_cp"],
+            hash[:last_cp] || hash["last_cp"],
+            hash[:name] || hash["name"])
+      end
+    end
+  end
+end

data/lib/fontisan/ucd/unknown_version_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Ucd
+    # Raised by Ucd::VersionResolver when a user-supplied version string
+    # is not in Ucd::Config.known_versions.
+    class UnknownVersionError < Ucd::Error; end
+  end
+end