fontisan 0.2.6 → 0.2.8

data/README.adoc

@@ -184,7 +184,7 @@ Family:                   Noto Serif CJK JP ExtraLight
 ====
 [source,shell]
 ----
-$ fontisan info spec/fixtures/fonts/MonaSans/mona-sans-2.0.8/googlefonts/variable/MonaSans[wdth,wght].ttf --brief
+$ fontisan info spec/fixtures/fonts/MonaSans/variable/MonaSans[wdth,wght].ttf --brief
 
 Font type:                TrueType (Variable)
 Family:                   Mona Sans ExtraLight
@@ -1034,26 +1034,19 @@ structures, usability, instructions, and glyphs.
 
 === Predefined profiles
 
-Fontisan includes several predefined validation profiles for common use cases:
+Fontisan includes validation profiles for different use cases:
 
-`indexability`:: Fast validation for font discovery and indexing (< 50ms). Uses
-BasicValidator with 8 essential checks. Loading mode: metadata.
+`indexability`:: Fast font discovery and indexing (~5x faster, 8 checks, metadata-only)
 
-`usability`:: Basic usability for font installation. Uses FontBookValidator with
-26 checks including macOS Font Book compatibility. Loading mode: full.
+`usability`:: Font installation compatibility (26 checks, macOS Font Book focused)
 
-`production`:: Comprehensive quality checks for production fonts (default
-profile). Uses OpenTypeValidator with 36 checks for OpenType spec compliance.
-Loading mode: full.
+`production`:: Comprehensive production quality (36 checks, OpenType spec compliance - default)
 
-`web`:: Web font embedding and optimization validation. Uses WebFontValidator
-with 18 checks for web deployment. Loading mode: full.
+`web`:: Web font embedding readiness (18 checks for web deployment)
 
-`spec_compliance`:: Full OpenType specification compliance with detailed checks.
-Uses OpenTypeValidator with info-level severity for comprehensive analysis.
-Loading mode: full.
+`spec_compliance`:: Full OpenType specification compliance (detailed analysis mode)
 
-`default`:: Alias for the production profile.
+`default`:: Alias for the production profile
 
 
 === Command-line usage
@@ -1154,6 +1147,80 @@ production, web, spec_compliance, default)
 
 -e, --exclude CHECKS:: Exclude specific checks (comma-separated list)
 
+=== Collection validation
+
+The `validate` command automatically detects and validates font collections (TTC, OTC, dfont).
+When validating a collection, fontisan validates all fonts in the collection and displays
+per-font results with an overall summary.
+
+.Validation profiles with collections
+[example]
+====
+All validation profiles work with font collections. The selected profile determines:
+
+* **Which tables are loaded** - metadata vs full mode
+* **Which checks are performed** - number and type of validations
+* **Performance characteristics** - indexability is ~5x faster than production
+
+For large collections (CJK fonts with 30+ fonts), use the `indexability` profile for fast
+validation when scanning for font discovery, or `production` for comprehensive quality
+checks.
+
+[source,shell]
+----
+# Quick validation for indexing (metadata mode, 8 checks, ~5x faster)
+$ fontisan validate /path/to/font.ttc -t indexability
+
+# Comprehensive validation (full mode, 37 checks)
+$ fontisan validate /path/to/font.ttc -t production
+
+# Web font readiness validation
+$ fontisan validate /path/to/font.ttc -t web
+----
+
+The collection validation output includes:
+
+* *Collection header* - Path, type, and number of fonts
+* *Summary* - Total errors, warnings, and info across all fonts
+* *Per-font sections* - Individual validation results for each font with:
+** Font index and name
+** Font path in `collection.ttc:index` format
+** Individual font status (VALID/INVALID/VALID_WITH_WARNINGS)
+** Font-specific errors and warnings
+** Exit codes* - For collections, uses the "worst" status across all fonts:
+** 0 = All fonts valid
+** 2 = Any font has fatal errors
+** 3 = Any font has errors (and no fatal)
+** 4 = Any font has warnings (and no errors)
+** 5 = Any font has info issues (and no errors or warnings)
+====
+
+.Validate a font collection
+[example]
+====
+[source,shell]
+----
+$ fontisan validate /path/to/font.ttc
+Collection: /path/to/font.ttc
+Type: TTC
+Fonts: 4
+
+Summary:
+  Total Errors: 14
+  Total Warnings: 8
+  Total Info: 0
+
+=== Font 0: Lucida Grande ===
+Font: /path/to/font.ttc:0
+Status: INVALID
+...
+
+=== Font 1: Lucida Grande Bold ===
+Font: /path/to/font.ttc:1
+Status: INVALID
+...
+----
+====
 
 === Ruby API usage
 
@@ -1241,7 +1308,7 @@ validator = Fontisan::Validators::OpenTypeValidator.new
 report = validator.validate(font)
 
 # Check individual results
-name_check = report.result_of(:name_version)
+name_check = report.result_of(:name_validation)
 puts name_check.passed?
 puts name_check.severity
 ----
@@ -1308,7 +1375,7 @@ font = Fontisan::FontLoader.load('font.ttf')
 validator = MyFontValidator.new
 report = validator.validate(font)
 
-# Check results
+# Check validation results
 puts report.valid?                           # => true/false
 puts report.status                           # => "valid", "valid_with_warnings", "invalid"
 puts report.summary.errors                   # => number of errors
@@ -1576,6 +1643,14 @@ dfont (Apple suitcase)::: Apple proprietary format storing complete Mac font
 suitcase resources in the data fork. Supports any SFNT fonts (TTF, OTF, or
 mixed). Mac OS X specific. File extension: `.dfont`
 
+Fontist returns the appropriate collection type based on the font data:
+
+* Examines font data within collection to determine type (TTC vs OTC)
+* TTC contains fonts with TrueType outlines (glyf table)
+* OTC contains fonts with CFF outlines (CFF table)
+* If ANY font in the collection has CFF outlines, use OpenTypeCollection
+* Only use TrueTypeCollection if ALL fonts have TrueType outlines
+
 
 === Collection compatibility
 
@@ -2076,6 +2151,41 @@ Fontisan can:
 * Importing and generation PNG block ruler layers
 
 
+== Testing
+
+=== General
+
+Fontisan has a comprehensive test suite covering all font operations, formats,
+and features.
+
+=== Running tests
+
+[source,shell]
+----
+# Run full test suite
+bundle exec rspec
+
+# Run with documentation format
+bundle exec rspec --format documentation
+
+# Run specific file
+bundle exec rspec spec/fontisan/tables/maxp_spec.rb
+----
+
+=== Test fixtures
+
+All required font fixtures are automatically downloaded before tests run. The
+test suite uses a centralized fixture configuration system that ensures all
+necessary fonts are available.
+
+[source,shell]
+----
+# Manual fixture management (if needed)
+bundle exec rake fixtures:download  # Download all test fonts
+bundle exec rake fixtures:clean     # Remove downloaded fonts
+----
+
+
 == Copyright and license
 
 Copyright https://www.ribose.com[Ribose].

data/Rakefile

@@ -8,6 +8,7 @@ require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
 
+# rubocop:disable Metrics/BlockLength
 namespace :fixtures do
   # Load centralized fixture configuration
   require_relative "spec/support/fixture_fonts"
@@ -99,8 +100,13 @@ namespace :fixtures do
     end
   end
 
+  # Compute download task prerequisites (marker files for non-skipped fonts)
+  download_prerequisites = fonts.values.reject do |config|
+    config[:skip_download]
+  end.map { |config| config[:marker] }
+
   desc "Download all test fixture fonts"
-  task download: fonts.values.reject { |config| config[:skip_download] }.map { |config| config[:marker] }
+  task download: download_prerequisites
 
   desc "Clean downloaded fixtures"
   task :clean do
@@ -112,17 +118,16 @@ namespace :fixtures do
           FileUtils.rm_f(config[:marker])
           puts "[fixtures:clean] Removed #{config[:marker]}"
         end
-      else
+      elsif File.exist?(config[:target_dir])
         # For archives, delete the entire target directory
-        if File.exist?(config[:target_dir])
-          puts "[fixtures:clean] Removing #{config[:target_dir]}..."
-          FileUtils.rm_rf(config[:target_dir])
-          puts "[fixtures:clean] Removed #{config[:target_dir]}"
-        end
+        puts "[fixtures:clean] Removing #{config[:target_dir]}..."
+        FileUtils.rm_rf(config[:target_dir])
+        puts "[fixtures:clean] Removed #{config[:target_dir]}"
       end
     end
   end
 end
+# rubocop:enable Metrics/BlockLength
 
 # RSpec task depends on fixtures
 RSpec::Core::RakeTask.new(spec: "fixtures:download")

data/benchmark/variation_quick_bench.rb

@@ -18,7 +18,7 @@ puts "Font: #{FONT_PATH}"
 puts
 
 # Test coordinates
-coords = Array.new(4) { |i| { "wght" => 300 + i * 200 } }
+coords = Array.new(4) { |i| { "wght" => 300 + (i * 200) } }
 puts "Generating #{coords.size} instances"
 puts
 

data/lib/fontisan/base_collection.rb

@@ -2,6 +2,7 @@
 
 require "bindata"
 require_relative "constants"
+require_relative "collection/shared_logic"
 
 module Fontisan
   # Abstract base class for font collections (TTC/OTC)
@@ -29,6 +30,8 @@ module Fontisan
   #     end
   #   end
   class BaseCollection < BinData::Record
+    include Collection::SharedLogic
+
     endian :big
 
     string :tag, length: 4, assert: "ttcf"
@@ -251,8 +254,6 @@ module Fontisan
     # @param io [IO] Open file handle
     # @return [TableSharingInfo] Sharing statistics
     def calculate_table_sharing(io)
-      require_relative "models/table_sharing_info"
-
       font_class = self.class.font_class
 
       # Extract all fonts
@@ -260,37 +261,8 @@ module Fontisan
         font_class.from_collection(io, offset)
       end
 
-      # Build table hash map (checksum -> size)
-      table_map = {}
-      total_table_size = 0
-
-      fonts.each do |font|
-        font.tables.each do |entry|
-          key = entry.checksum
-          size = entry.table_length
-          table_map[key] ||= size
-          total_table_size += size
-        end
-      end
-
-      # Count unique vs shared
-      unique_tables = table_map.size
-      total_tables = fonts.sum { |f| f.tables.length }
-      shared_tables = total_tables - unique_tables
-
-      # Calculate space saved
-      unique_size = table_map.values.sum
-      space_saved = total_table_size - unique_size
-
-      # Calculate sharing percentage
-      sharing_pct = total_tables.positive? ? (shared_tables.to_f / total_tables * 100).round(2) : 0.0
-
-      Models::TableSharingInfo.new(
-        shared_tables: shared_tables,
-        unique_tables: unique_tables,
-        sharing_percentage: sharing_pct,
-        space_saved_bytes: space_saved,
-      )
+      # Use shared logic for calculation
+      calculate_table_sharing_for_fonts(fonts)
     end
   end
 end

data/lib/fontisan/cli.rb

@@ -367,18 +367,27 @@ module Fontisan
       handle_error(e)
     end
 
-    desc "validate FONT_FILE", "Validate font file"
+    desc "validate [FONT_FILE]", "Validate font file"
     long_desc <<-DESC
       Validate font file against quality checks and standards.
 
-      Test lists (-t/--test-list):
-        indexability     - Fast indexing validation
+      Supports individual fonts (TTF/OTF) and font collections (TTC/OTC/dfont).
+      For collections, validates each font and provides a summary report.
+
+      Profiles (-p/--profile):
+        indexability     - Fast indexing validation (metadata only, 8 checks)
         usability        - Installation compatibility
         production       - Comprehensive quality (default)
         web              - Web font readiness
         spec_compliance  - OpenType spec compliance
         default          - Production profile (alias)
 
+      Collection validation with profiles:
+        When validating TTC/OTC/dfont collections, the selected profile
+        determines which tables are loaded and which checks are performed
+        for each font in the collection. Use 'indexability' for quick
+        validation or 'production' for comprehensive quality checks.
+
       Return values (with -R/--return-value-results):
         0  No results
         1  Execution errors
@@ -389,25 +398,41 @@ module Fontisan
     DESC
 
     option :exclude, aliases: "-e", type: :array, desc: "Tests to exclude"
-    option :list, aliases: "-l", type: :boolean, desc: "List available tests"
+    option :list, aliases: "-l", type: :boolean, desc: "List available profiles"
     option :output, aliases: "-o", type: :string, desc: "Output file"
     option :full_report, aliases: "-r", type: :boolean, desc: "Full report"
-    option :return_value_results, aliases: "-R", type: :boolean, desc: "Use return value for results"
-    option :summary_report, aliases: "-S", type: :boolean, desc: "Summary report"
-    option :test_list, aliases: "-t", type: :string, default: "default", desc: "Tests to execute"
+    option :return_value_results, aliases: "-R", type: :boolean,
+                                  desc: "Use return value for results"
+    option :summary_report, aliases: "-S", type: :boolean,
+                            desc: "Summary report"
+    option :profile, aliases: "-p", type: :string, default: "default",
+                     desc: "Validation profile"
     option :table_report, aliases: "-T", type: :boolean, desc: "Tabular report"
     option :verbose, aliases: "-v", type: :boolean, desc: "Verbose output"
-    option :suppress_warnings, aliases: "-W", type: :boolean, desc: "Suppress warnings"
+    option :suppress_warnings, aliases: "-W", type: :boolean,
+                               desc: "Suppress warnings"
 
-    def validate(font_file)
+    def validate(*font_files)
       if options[:list]
         list_available_tests
         return
       end
 
+      # Validate argument count
+      if font_files.empty?
+        raise(Thor::Error, "FONT_FILE is required unless using --list")
+      elsif font_files.size > 1
+        raise(Thor::Error,
+              "Too many arguments. validate accepts only one font file.\n" \
+              "To validate multiple files, run validate separately for each.\n" \
+              "To validate all fonts in a collection, use: fontisan validate collection.ttc")
+      end
+
+      font_file = font_files.first
+
       cmd = Commands::ValidateCommand.new(
         input: font_file,
-        profile: options[:test_list],
+        profile: options[:profile],
         exclude: options[:exclude] || [],
         output: options[:output],
         format: options[:format].to_sym,
@@ -416,11 +441,18 @@ module Fontisan
         table_report: options[:table_report],
         verbose: options[:verbose],
         suppress_warnings: options[:suppress_warnings],
-        return_value_results: options[:return_value_results]
+        return_value_results: options[:return_value_results],
       )
 
       exit cmd.run
-    rescue => e
+    rescue Thor::Error => e
+      unless options[:quiet]
+        warn "ERROR: #{e.message}"
+        warn
+        help("validate")
+      end
+      exit 1
+    rescue StandardError => e
       error "Validation failed: #{e.message}"
       exit 1
     end
@@ -546,7 +578,7 @@ module Fontisan
         puts "  Format: #{result[:format].upcase}"
         puts "  Fonts: #{result[:num_fonts]}"
         puts "  Size: #{format_size(result[:output_size] || result[:total_size])}"
-        if result[:space_savings] && result[:space_savings].positive?
+        if result[:space_savings]&.positive?
           puts "  Space saved: #{format_size(result[:space_savings])}"
           puts "  Sharing: #{result[:statistics][:sharing_percentage]}%"
         end

data/lib/fontisan/collection/dfont_builder.rb

@@ -86,7 +86,8 @@ module Fontisan
         map_size = 28 + 2 + 8 + (sfnt_binaries.size * 12)
 
         # Step 4: Build resource map
-        resource_map = build_resource_map(sfnt_binaries, resource_data.bytesize, map_size)
+        resource_map = build_resource_map(sfnt_binaries,
+                                          resource_data.bytesize, map_size)
 
         # Step 5: Build header
         header = build_header(resource_data.bytesize, resource_map.bytesize)

data/lib/fontisan/collection/shared_logic.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Collection
+    # Shared logic for font collection classes
+    #
+    # This module provides common functionality for all collection types
+    # (TTC, OTC, dfont) to maintain DRY principles.
+    module SharedLogic
+      # Calculate table sharing statistics
+      #
+      # Analyzes which tables are shared between fonts and calculates
+      # space savings from deduplication.
+      #
+      # @param fonts [Array<TrueTypeFont, OpenTypeFont>] Array of fonts
+      # @return [Models::TableSharingInfo] Sharing statistics
+      def calculate_table_sharing_for_fonts(fonts)
+        require_relative "../models/table_sharing_info"
+
+        # Build table hash map (checksum -> size)
+        table_map = {}
+        total_table_size = 0
+
+        fonts.each do |font|
+          font.tables.each do |entry|
+            key = entry.checksum
+            size = entry.table_length
+            table_map[key] ||= size
+            total_table_size += size
+          end
+        end
+
+        # Count unique vs shared
+        unique_tables = table_map.size
+        total_tables = fonts.sum { |f| f.tables.length }
+        shared_tables = total_tables - unique_tables
+
+        # Calculate space saved
+        unique_size = table_map.values.sum
+        space_saved = total_table_size - unique_size
+
+        # Calculate sharing percentage
+        sharing_pct = total_tables.positive? ? (shared_tables.to_f / total_tables * 100).round(2) : 0.0
+
+        Models::TableSharingInfo.new(
+          shared_tables: shared_tables,
+          unique_tables: unique_tables,
+          sharing_percentage: sharing_pct,
+          space_saved_bytes: space_saved,
+        )
+      end
+    end
+  end
+end

data/lib/fontisan/commands/convert_command.rb

@@ -73,7 +73,7 @@ module Fontisan
         @instance_index = opts[:instance_index]
         @preserve_variation = opts[:preserve_variation]
         @preserve_hints = opts.fetch(:preserve_hints, false)
-        @collection_target_format = opts.fetch(:target_format, 'preserve').to_s
+        @collection_target_format = opts.fetch(:target_format, "preserve").to_s
         @validate = !opts[:no_validate]
       end
 
@@ -196,7 +196,7 @@ module Fontisan
             output: @output_path,
             target_format: @collection_target_format,
             verbose: @options[:verbose],
-          }
+          },
         )
 
         # Display results
@@ -245,8 +245,6 @@ module Fontisan
             :otc
           when ".dfont"
             :dfont
-          else
-            nil
           end
         end
       end

data/lib/fontisan/commands/info_command.rb

@@ -311,7 +311,7 @@ module Fontisan
               start_glyph_id: strike_rec.start_glyph_index,
               end_glyph_id: strike_rec.end_glyph_index,
               bit_depth: strike_rec.bit_depth,
-              num_glyphs: strike_rec.glyph_range.size
+              num_glyphs: strike_rec.glyph_range.size,
             )
           end
           formats << "PNG" # CBDT typically contains PNG data
@@ -329,8 +329,8 @@ module Fontisan
               ppem: strike[:ppem],
               start_glyph_id: 0,
               end_glyph_id: strike[:num_glyphs] - 1,
-              bit_depth: 32,  # sbix is typically 32-bit
-              num_glyphs: strike[:num_glyphs]
+              bit_depth: 32, # sbix is typically 32-bit
+              num_glyphs: strike[:num_glyphs],
             )
           end
         end

data/lib/fontisan/commands/pack_command.rb

@@ -260,7 +260,8 @@ module Fontisan
       # @return [Symbol] Parsed format (:ttc, :otc, or :dfont)
       # @raise [ArgumentError] if format is invalid
       def parse_format(format)
-        return format if format.is_a?(Symbol) && %i[ttc otc dfont].include?(format)
+        return format if format.is_a?(Symbol) && %i[ttc otc
+                                                    dfont].include?(format)
 
         case format.to_s.downcase
         when "ttc"