fontist 2.1.1 → 2.1.3

data/docs/package.json

@@ -7,11 +7,11 @@
   },
   "type": "module",
   "devDependencies": {
-    "@types/node": "latest",
-    "prettier": "^3.2.4",
-    "typescript": "latest",
-    "vitepress": "^1.0.0-rc.44",
-    "vue": "^3.4.15",
-    "vue-tsc": "^1.8.27"
+    "@types/node": "^25.0.0",
+    "prettier": "^3.8.1",
+    "typescript": "^5.9.3",
+    "vitepress": "^1.6.4",
+    "vue": "^3.5.29",
+    "vue-tsc": "^3.2.5"
   }
 }

data/fontist.gemspec

@@ -36,8 +36,10 @@ Gem::Specification.new do |spec|
   spec.add_dependency "git", "> 1.0"
   spec.add_dependency "json", "~> 2.0"
   spec.add_dependency "lutaml-model", "~> 0.7"
+  spec.add_dependency "lutaml-xsd", "~> 1.0"
   spec.add_dependency "marcel", "~> 1.0"
   spec.add_dependency "nokogiri", "~> 1.0"
+  spec.add_dependency "octokit", "~> 4.0"
   spec.add_dependency "paint", "~> 2.3"
   spec.add_dependency "parallel", "~> 1.24"
   spec.add_dependency "plist", "~> 3.0"

data/lib/fontist/cache/store.rb

@@ -42,6 +42,16 @@ module Fontist
         end
       end
 
+      def cleanup_temp_files
+        # Clean up orphaned .tmp files from interrupted writes
+        # This can happen if the process crashes between File.write and File.rename
+        Dir.glob(File.join(@cache_dir, "*.tmp")).each do |tmp|
+          File.delete(tmp)
+        rescue StandardError
+          nil
+        end
+      end
+
       private
 
       attr_reader :cache_dir
@@ -68,11 +78,30 @@ module Fontist
       def read_entry(key)
         return nil unless File.exist?(cache_path(key))
 
-        Marshal.load(File.read(cache_path(key)))
+        begin
+          Marshal.load(File.read(cache_path(key)))
+        rescue ArgumentError, TypeError => e
+          # Cache file is corrupted - delete it and return nil
+          # This can happen on Windows when file is read while being written,
+          # or when cache files from previous runs are corrupted
+          File.delete(cache_path(key)) rescue nil
+          nil
+        end
       end
 
       def write_entry(key, entry)
-        File.write(cache_path(key), Marshal.dump(entry))
+        # Use temp file + atomic rename to prevent race conditions
+        # This ensures readers never see partial writes, even on Windows
+        temp_path = cache_path(key) + ".tmp"
+
+        File.write(temp_path, Marshal.dump(entry))
+        # Atomic rename (overwrites target atomically)
+        # File.rename is atomic on all platforms for same filesystem
+        File.rename(temp_path, cache_path(key))
+      rescue => e
+        # Clean up temp file if rename fails
+        File.delete(temp_path) rescue nil
+        raise e
       end
 
       # Cache entry with TTL support

data/lib/fontist/font_file.rb

@@ -42,11 +42,11 @@ module Fontist
 
         # For collections, we need different handling
         if is_collection
-          # Load and validate the first font in the collection for indexability
+          # Load the first font in the collection
           font = Fontisan::FontLoader.load(path, font_index: 0,
                                                  mode: :metadata, lazy: true)
 
-          # Validate the font using indexability profile
+          # Validate the font using indexability profile (log issues but don't reject)
           validator = load_indexability_validator
           validation_report = validator.validate(font)
 
@@ -54,10 +54,9 @@ module Fontist
             error_messages = validation_report.errors.map do |e|
               "#{e.category}: #{e.message}"
             end.join("; ")
-            # rubocop:disable Layout/LineLength
-            raise Errors::FontFileError,
-                  "Font from collection failed indexability validation: #{error_messages}"
-            # rubocop:enable Layout/LineLength
+            Fontist.ui.debug(
+              "Font validation issues for #{File.basename(path)}: #{error_messages}",
+            )
           end
 
         else
@@ -82,11 +81,14 @@ module Fontist
         validation_report = validator.validate(font)
 
         unless validation_report.valid?
+          # Log validation issues but don't reject outright
+          # We'll check if we can still extract metadata
           error_messages = validation_report.errors.map do |e|
             "#{e.category}: #{e.message}"
           end.join("; ")
-          raise Errors::FontFileError,
-                "Font file failed indexability validation: #{error_messages}"
+          Fontist.ui.debug(
+            "Font validation issues for #{File.basename(path)}: #{error_messages}",
+          )
         end
 
         font
@@ -180,17 +182,66 @@ module Fontist
         return {} unless name_table
 
         # Extract all needed name strings using Fontisan's API
+        # Fall back to non-English names if English names are not available
         {
-          full_name: name_table.english_name(Fontisan::Tables::Name::FULL_NAME),
-          family_name: name_table.english_name(Fontisan::Tables::Name::FAMILY),
-          subfamily_name: name_table.english_name(Fontisan::Tables::Name::SUBFAMILY),
-          preferred_family: name_table.english_name(Fontisan::Tables::Name::PREFERRED_FAMILY),
-          preferred_subfamily: name_table.english_name(Fontisan::Tables::Name::PREFERRED_SUBFAMILY),
-          postscript_name: name_table.english_name(Fontisan::Tables::Name::POSTSCRIPT_NAME),
+          full_name: name_table.english_name(Fontisan::Tables::Name::FULL_NAME) ||
+            extract_any_name(name_table, Fontisan::Tables::Name::FULL_NAME),
+          family_name: name_table.english_name(Fontisan::Tables::Name::FAMILY) ||
+            extract_any_name(name_table, Fontisan::Tables::Name::FAMILY),
+          subfamily_name: name_table.english_name(Fontisan::Tables::Name::SUBFAMILY) ||
+            extract_any_name(name_table, Fontisan::Tables::Name::SUBFAMILY),
+          preferred_family: name_table.english_name(Fontisan::Tables::Name::PREFERRED_FAMILY) ||
+            extract_any_name(name_table, Fontisan::Tables::Name::PREFERRED_FAMILY),
+          preferred_subfamily: name_table.english_name(Fontisan::Tables::Name::PREFERRED_SUBFAMILY) ||
+            extract_any_name(name_table, Fontisan::Tables::Name::PREFERRED_SUBFAMILY),
+          postscript_name: name_table.english_name(Fontisan::Tables::Name::POSTSCRIPT_NAME) ||
+            extract_any_name(name_table, Fontisan::Tables::Name::POSTSCRIPT_NAME),
         }
       end
       # rubocop:enable Metrics/MethodLength
 
+      # Extract any available name for a given name ID by manually decoding the name record
+      def extract_any_name(name_table, name_id)
+        # Find any name record with the matching name_id
+        records = name_table.name_records.select { |r| r.name_id == name_id }
+        return nil if records.empty?
+
+        # Manually decode each record
+        records.each do |record|
+          decoded = decode_name_record_manually(name_table, record)
+          return decoded unless decoded.nil? || decoded.empty?
+        end
+
+        nil
+      end
+
+      # Manually decode a name record since the fontisan method is private
+      def decode_name_record_manually(name_table, record)
+        # Get raw string storage
+        storage_bytes = name_table.string_storage.to_s.b
+
+        # Extract this record's string
+        offset = record.string_offset
+        length = record.string_length
+
+        return nil if offset + length > storage_bytes.bytesize
+        return nil if length.zero?
+
+        string_data = storage_bytes.byteslice(offset, length)
+
+        # Decode based on platform (same logic as fontisan)
+        case record.platform_id
+        when 0, 3 # PLATFORM_UNICODE, PLATFORM_WINDOWS
+          string_data.dup.force_encoding("UTF-16BE")
+            .encode("UTF-8", invalid: :replace, undef: :replace)
+        when 1 # PLATFORM_MACINTOSH
+          string_data.dup.force_encoding("ASCII-8BIT")
+            .encode("UTF-8", invalid: :replace, undef: :replace)
+        else
+          string_data.dup.force_encoding("UTF-8")
+        end
+      end
+
       def raise_font_file_error(exception)
         raise Errors::FontFileError,
               "Font file could not be parsed: #{exception.inspect}."

data/lib/fontist/indexes/index_mixin.rb

@@ -1,5 +1,39 @@
 module Fontist
   module Indexes
+    # IndexMixin provides common functionality for font index classes.
+    #
+    # == Performance Optimization (Tech Debt)
+    #
+    # This module uses a temporary Hash-based lookup cache during index building
+    # to avoid O(n²) performance when adding many entries. This is a workaround
+    # for Lutaml::Model::Collection's Array-based storage.
+    #
+    # === The Problem
+    #
+    # Lutaml::Model::Collection stores entries as an Array, which provides O(n)
+    # lookup when searching for existing keys. When building an index with
+    # thousands of entries, this creates O(n²) behavior:
+    #
+    # - 8867 font styles × average 2670 comparisons = ~23.6 million comparisons
+    # - Index building: ~26 seconds with Array lookup
+    #
+    # === The Workaround
+    #
+    # During `build` and `build_with_formulas`, we maintain a temporary
+    # `@index_build_cache` Hash that provides O(1) lookups. After building,
+    # the cache is cleared.
+    #
+    # - Index building with Hash lookup: ~0.08 seconds
+    # - Speedup: 325× faster
+    #
+    # === The Proper Fix
+    #
+    # This tech debt should be resolved by enhancing Lutaml::Model::Collection
+    # to support efficient key-based lookups. See the reproduction script at:
+    # `dev/lutaml_model_collection_lookup_benchmark.rb`
+    #
+    # Related issue: https://github.com/lutaml/lutaml-model/issues/XXX
+    #
     module IndexMixin
       def self.included(base)
         base.extend(ClassMethods)
@@ -35,13 +69,17 @@ module Fontist
         def reset_cache
           # Delete the index file to force rebuild on next access
           # This is important for tests to ensure clean state
-          File.delete(path) if File.exist?(path)
+          FileUtils.rm_f(path)
         end
       end
 
+      # Build index by loading all formulas from disk.
+      # Uses Hash-based cache for O(1) lookups during building.
       def build
-        Formula.all.each do |formula|
-          add_formula(formula)
+        with_index_build_cache do
+          Formula.all.each do |formula|
+            add_formula(formula)
+          end
         end
 
         to_file
@@ -49,9 +87,16 @@ module Fontist
         self
       end
 
+      # Build index from pre-loaded formulas.
+      # Uses Hash-based cache for O(1) lookups during building.
+      #
+      # This is the preferred method when formulas are already loaded,
+      # as it avoids re-loading from disk.
       def build_with_formulas(formulas)
-        formulas.each do |formula|
-          add_formula(formula)
+        with_index_build_cache do
+          formulas.each do |formula|
+            add_formula(formula)
+          end
         end
 
         to_file
@@ -73,26 +118,20 @@ module Fontist
 
       def index_key_for_style(_style)
         raise NotImplementedError,
-              "index_key_for_style(style) must be implemented in including class"
+              "index_key_for_style(style) must be implemented"
       end
 
+      # Add a font style to the index with O(1) or O(n) lookup.
+      #
+      # Uses `@index_build_cache` Hash for O(1) lookup during building,
+      # falling back to O(n) Array lookup for incremental updates.
       def add_index_formula(style, formula_path)
-        key = index_key_for_style(style)
-        raise if key.nil? || key.empty?
-
-        key = normalize_key(key)
-        formula_path = Array(formula_path)
-        paths = formula_path.map { |p| relative_formula_path(p) }
+        key = prepare_index_key(style)
+        paths = prepare_formula_paths(formula_path)
 
-        if index_formula(key)
-          index_formula(key).formula_path.concat(paths).uniq!
-          return
-        end
+        return if merge_existing_entry?(key, paths)
 
-        entries << FormulaKeyToPath.new(
-          key: key,
-          formula_path: paths,
-        )
+        create_and_add_entry(key, paths)
       end
 
       def load_formulas(key)
@@ -114,6 +153,56 @@ module Fontist
 
       private
 
+      # Yields with a Hash-based lookup cache for O(1) key lookups.
+      #
+      # This is a performance optimization to avoid O(n²) behavior
+      # when building indexes with thousands of entries.
+      #
+      # @yield [void] Block to execute with cache enabled
+      # @return [void]
+      def with_index_build_cache
+        @index_build_cache = {}
+        yield
+      ensure
+        @index_build_cache = nil
+      end
+
+      def prepare_index_key(style)
+        key = index_key_for_style(style)
+        raise if key.nil? || key.empty?
+
+        normalize_key(key)
+      end
+
+      def prepare_formula_paths(formula_path)
+        Array(formula_path).map { |p| relative_formula_path(p) }
+      end
+
+      # Attempt to merge paths into existing entry.
+      # Returns true if merged, false if no existing entry found.
+      def merge_existing_entry?(key, paths)
+        existing = find_existing_entry(key)
+        return false unless existing
+
+        existing.formula_path.concat(paths).uniq!
+        true
+      end
+
+      # Find existing entry using cache (O(1)) or array scan (O(n))
+      def find_existing_entry(key)
+        if @index_build_cache
+          @index_build_cache[key]
+        else
+          index_formula(key)
+        end
+      end
+
+      def create_and_add_entry(key, paths)
+        entry = FormulaKeyToPath.new(key: key, formula_path: paths)
+        entries << entry
+        @index_build_cache[key] = entry if @index_build_cache
+      end
+
       def index_formula(key)
         Array(entries).detect { |f| normalize_key(f.key) == normalize_key(key) }
       end

data/lib/fontist/manifest.rb

@@ -79,13 +79,13 @@ location: nil)
     end
 
     def validate_platform_compatibility!
-      formula = Fontist::Formula.find(name)
-      return if formula.nil?
-      return if formula.compatible_with_platform?
+      formula = Fontist::Formula.find_many(name)
+      return if formula.empty?
+      return if formula.any?(&:compatible_with_platform?)
 
       raise Fontist::Errors::PlatformMismatchError.new(
         name,
-        formula.platforms,
+        formula.map(&:platforms).flatten.uniq,
         Fontist::Utils::System.user_os,
       )
     end

data/lib/fontist/system_index.rb

@@ -682,7 +682,10 @@ spinner_index = nil)
 
     def parse_font(font_file, path)
       # Skip fonts with incomplete metadata
-      return nil unless font_file.full_name && font_file.family
+      unless font_file.full_name && font_file.family
+        warn_incomplete_metadata(path)
+        return nil
+      end
 
       # Get file metadata for caching
       file_size = begin
@@ -708,6 +711,32 @@ spinner_index = nil)
       )
     end
 
+    def filter_valid_fonts(fonts)
+      fonts.select do |font|
+        missing_keys = ALLOWED_KEYS.reject { |key| font.send(key) }
+
+        next true if missing_keys.empty?
+
+        warn_font_metadata_incomplete(font, missing_keys)
+      end
+    end
+
+    def warn_font_metadata_incomplete(font, missing_keys)
+      Fontist.ui.error(<<~MSG.chomp)
+        Skipping font with incomplete metadata: #{font.path}
+        Missing attributes: #{missing_keys.join(', ')}.
+        This font will not be indexed, but Fontist will continue to work.
+      MSG
+    end
+
+    def warn_incomplete_metadata(path)
+      Fontist.ui.error(<<~MSG.chomp)
+        Skipping font with incomplete metadata: #{path}
+        Missing attributes: full_name, family_name.
+        This font will not be indexed, but Fontist will continue to work.
+      MSG
+    end
+
     def raise_font_index_corrupted(font, missing_keys)
       raise(Errors::FontIndexCorrupted, <<~MSG.chomp)
         Font index is corrupted.

data/lib/fontist/utils/cache.rb

@@ -1,5 +1,6 @@
 require "lutaml/model"
 require "marcel"
+require_relative "locking"
 
 module Fontist
   module Utils

data/lib/fontist/utils/downloader.rb

@@ -1,4 +1,6 @@
 require_relative "cache"
+require_relative "github_url"
+require_relative "github_client"
 
 module Fontist
   module Utils
@@ -59,16 +61,30 @@ module Fontist
       end
 
       def download_file
-        tries = tries ? tries + 1 : 1
+        @tries ||= 0
+        @tries += 1
         print_download_start if @verbose
         do_download_file
       rescue Down::Error => e
-        retry if tries < 3
+        if @tries < max_retries
+          sleep(backoff_time(@tries))
+          retry
+        end
 
         raise Fontist::Errors::InvalidResourceError,
               "Invalid URL: #{@file}. Error: #{e.inspect}."
       end
 
+      def max_retries
+        @max_retries ||= 3
+      end
+
+      def backoff_time(attempt)
+        # Exponential backoff: 2^attempt seconds, max 30 seconds
+        # 1st retry: 2s, 2nd: 4s, 3rd: 8s
+        [2**attempt, 30].min
+      end
+
       def print_download_start
         Fontist.ui.say("Downloading from: #{Paint[url, :cyan]}")
         if @verbose
@@ -115,8 +131,10 @@ module Fontist
       # rubocop:enable Metrics/MethodLength
 
       def url
-        obj = Helpers.url_object(@file)
-        obj.respond_to?(:url) ? obj.url : obj
+        @url ||= begin
+          raw_url = extract_raw_url
+          github_aware_url(raw_url)
+        end
       end
 
       def headers
@@ -126,6 +144,22 @@ module Fontist
           obj.headers.to_h.map { |k, v| [k.to_s, v] }.to_h || # rubocop:disable Style/HashTransformKeys, Metrics/LineLength
           {}
       end
+
+      private
+
+      def extract_raw_url
+        obj = Helpers.url_object(@file)
+        obj.respond_to?(:url) ? obj.url : obj
+      end
+
+      def github_aware_url(raw_url)
+        parsed = GitHubUrl.parse(raw_url)
+        if parsed.matched?
+          GitHubClient.authenticated_download_url(parsed)
+        else
+          raw_url
+        end
+      end
     end
 
     class ProgressBar

data/lib/fontist/utils/github_client.rb

@@ -0,0 +1,43 @@
+require "octokit"
+
+module Fontist
+  module Utils
+    class GitHubClient
+      class << self
+        def authenticated_download_url(parsed_url)
+          return parsed_url.original_url unless parsed_url.matched?
+
+          client = create_client
+          release = fetch_release(client, parsed_url)
+
+          find_asset_url(release, parsed_url.asset) || parsed_url.original_url
+        rescue Octokit::Error => e
+          Fontist.ui.say("GitHub API error: #{e.message}. Falling back to direct download.")
+          parsed_url.original_url
+        end
+
+        private
+
+        def create_client
+          if github_token
+            Octokit::Client.new(access_token: github_token)
+          else
+            Octokit::Client.new
+          end
+        end
+
+        def github_token
+          ENV.fetch("GITHUB_TOKEN", nil)
+        end
+
+        def fetch_release(client, parsed_url)
+          client.release_for_tag("#{parsed_url.owner}/#{parsed_url.repo}", parsed_url.tag)
+        end
+
+        def find_asset_url(release, asset_name)
+          release.assets.find { |asset| asset.name == asset_name }&.browser_download_url
+        end
+      end
+    end
+  end
+end

data/lib/fontist/utils/github_url.rb

@@ -0,0 +1,51 @@
+module Fontist
+  module Utils
+    class GitHubUrl
+      GITHUB_RELEASE_PATTERN =
+        %r{^https?://github\.com/(?<owner>[^/]+)/(?<repo>[^/]+)/releases/download/(?<tag>[^/]+)/(?<asset>.+)$}
+
+      class << self
+        def match?(url)
+          parse(url).matched?
+        end
+
+        def parse(url)
+          url_string = url.to_s
+          match = url_string.match(GITHUB_RELEASE_PATTERN)
+
+          if match
+            ParsedUrl.new(
+              owner: match[:owner],
+              repo: match[:repo],
+              tag: match[:tag],
+              asset: match[:asset],
+              original_url: url_string
+            )
+          else
+            ParsedUrl.from_non_github_url(url_string)
+          end
+        end
+      end
+
+      class ParsedUrl
+        attr_reader :owner, :repo, :tag, :asset, :original_url
+
+        def initialize(owner:, repo:, tag:, asset:, original_url:)
+          @owner = owner
+          @repo = repo
+          @tag = tag
+          @asset = asset
+          @original_url = original_url
+        end
+
+        def self.from_non_github_url(original_url)
+          new(owner: nil, repo: nil, tag: nil, asset: nil, original_url: original_url)
+        end
+
+        def matched?
+          !owner.nil?
+        end
+      end
+    end
+  end
+end

data/lib/fontist/version.rb

@@ -1,3 +1,3 @@
 module Fontist
-  VERSION = "2.1.1".freeze
+  VERSION = "2.1.3".freeze
 end

data/lib/fontist.rb

@@ -188,9 +188,12 @@ module Fontist
   def self.formulas_repo_path_exists!
     return true if Dir.exist?(Fontist.formulas_repo_path.join("Formulas"))
 
-    raise Errors::MainRepoNotFoundError.new(
-      "Please fetch formulas with `fontist update`.",
-    )
+    # Auto-update formulas repo if it doesn't exist (lazy initialization).
+    # This ensures formulas are always discoverable without requiring
+    # explicit `fontist update`.
+    Formula.update_formulas_repo
+
+    true
   end
 end