fontisan 0.2.3 → 0.2.5

data/README.adoc

@@ -424,6 +424,11 @@ tables:
   length: 17870
   offset: 542992
   checksum: 701383168
+- tag: OS/2
+  length: 96
+  offset: 392
+  checksum: 1193824355
+...
 ----
 ====
 
@@ -505,7 +510,7 @@ Syntax:
 $ fontisan unicode FONT_FILE [--format FORMAT]
 ----
 
-Where,
+Where:
 
 `FONT_FILE`:: Path to the font file (OTF, TTF, or TTC)
 `FORMAT`:: Output format: `text` (default), `json`, or `yaml`
@@ -734,10 +739,8 @@ Dry-run mode: Preview of instance generation
 Coordinates:
   wght: 700.0
 
-Output would be written to: variable-instance.ttf
-Output
-
- format: same as input
+Output file: variable-instance.ttf
+Format: same as input
 
 Use without --dry-run to actually generate the instance.
 ----
@@ -1020,6 +1023,492 @@ Uses base64 encoding for binary data instead of hexadecimal, useful for
 JSON-based workflows.
 ====
 
+== Font validation
+
+=== General
+
+Fontisan provides validation functionality to ensure font quality, structural
+integrity, and compliance with various standards.
+
+The validation framework allows developers to create custom validators using a
+declarative DSL. Validators can perform checks on font tables, fields,
+structures, usability, instructions, and glyphs.
+
+=== Predefined profiles
+
+Fontisan includes several predefined validation profiles for common use cases:
+
+`indexability`:: Fast validation for font discovery and indexing (< 50ms). Uses
+BasicValidator with 8 essential checks. Loading mode: metadata.
+
+`usability`:: Basic usability for font installation. Uses FontBookValidator with
+26 checks including macOS Font Book compatibility. Loading mode: full.
+
+`production`:: Comprehensive quality checks for production fonts (default
+profile). Uses OpenTypeValidator with 36 checks for OpenType spec compliance.
+Loading mode: full.
+
+`web`:: Web font embedding and optimization validation. Uses WebFontValidator
+with 18 checks for web deployment. Loading mode: full.
+
+`spec_compliance`:: Full OpenType specification compliance with detailed checks.
+Uses OpenTypeValidator with info-level severity for comprehensive analysis.
+Loading mode: full.
+
+`default`:: Alias for the production profile.
+
+
+=== Command-line usage
+
+==== Validate a font file against a predefined profile
+
+.Validate with default profile
+[example]
+====
+[source,shell]
+----
+$ fontisan validate font.ttf
+----
+====
+
+.Validate for web use
+[example]
+====
+[source,shell]
+----
+$ fontisan validate font.ttf -t web
+----
+====
+
+.List available profiles
+[example]
+====
+[source,shell]
+----
+$ fontisan validate --list
+Available validation profiles:
+  indexability         - Fast validation for font discovery and indexing
+  usability            - Basic usability for installation
+  production           - Comprehensive quality checks
+  web                  - Web embedding and optimization
+  spec_compliance      - Full OpenType spec compliance
+  default              - Default validation profile (alias for production)
+----
+====
+
+.Full report to file
+[example]
+====
+[source,shell]
+----
+$ fontisan validate font.ttf -t production -r -o report.txt
+----
+====
+
+.Summary with return value
+[example]
+====
+[source,shell]
+----
+$ fontisan validate font.ttf -S -R
+0 errors, 2 warnings, 0 info
+$ echo $?
+4  # Exit code 4 indicates warnings found
+----
+====
+
+.Table format output
+[example]
+====
+[source,shell]
+----
+$ fontisan validate font.ttf -T
+CHECK_ID | STATUS | SEVERITY | TABLE
+------------------------------------------------------------
+required_tables | PASS | error | N/A
+name_version | PASS | error | name
+family_name | PASS | error | name
+...
+----
+====
+
+==== CLI options
+
+-t, --test-list PROFILE:: Select validation profile (indexability, usability,
+production, web, spec_compliance, default)
+
+-l, --list:: List available validation profiles
+
+-o, --output FILE:: Write report to file instead of stdout
+
+-r, --full-report:: Generate full detailed report
+
+-R, --return-value-results:: Use return value to indicate results (0=none,
+1=error, 2=fatal, 3=major, 4=minor, 5=info)
+
+-S, --summary-report:: Generate brief summary report
+
+-T, --table-report:: Generate tabular format report
+
+-v, --verbose:: Enable verbose output
+
+-w, --suppress-warnings:: Suppress warning output
+
+-e, --exclude CHECKS:: Exclude specific checks (comma-separated list)
+
+
+=== Ruby API usage
+
+==== Architecture
+
+The validation framework in Ruby consists of:
+
+DSL base class:: `Fontisan::Validators::Validator` provides a declarative syntax
+for defining validation checks
+
+Table validation helpers::
+56 helper methods across 8 core OpenType tables (name, head, maxp, hhea, glyf,
+cmap, post, OS/2) that perform specific validation checks
+
+ValidationReport::
+Structured reports with individual check results, severity levels, and
+comprehensive issue tracking
+
+==== Using predefined profiles
+
+.Validate with Ruby API
+[example]
+====
+[source,ruby]
+----
+require 'fontisan'
+
+# Validate with default profile (production)
+report = Fontisan.validate('font.ttf')
+puts report.valid?  # => true or false
+
+# Validate with specific profile
+report = Fontisan.validate('font.ttf', profile: :web)
+puts "Errors: #{report.summary.errors}"
+puts "Warnings: #{report.summary.warnings}"
+
+# Check validation status
+if report.valid?
+  puts "Font is valid for web use!"
+else
+  puts "Font has #{report.summary.errors} errors"
+end
+----
+====
+
+.Query validation results
+[example]
+====
+[source,ruby]
+----
+report = Fontisan.validate('font.ttf', profile: :production)
+
+# Get issues by severity
+fatal_issues = report.fatal_errors
+error_issues = report.errors_only
+warning_issues = report.warnings_only
+info_issues = report.info_only
+
+# Get issues by category
+table_issues = report.issues_by_category('table_validation')
+
+# Get check results
+failed_ids = report.failed_check_ids
+pass_rate = report.pass_rate
+
+# Export to different formats
+yaml_output = report.to_yaml
+json_output = report.to_json
+summary = report.to_summary  # "2 errors, 3 warnings, 0 info"
+----
+====
+
+.Use validators directly
+[example]
+====
+[source,ruby]
+----
+require 'fontisan'
+
+# Load font
+font = Fontisan::FontLoader.load('font.ttf')
+
+# Use specific validator
+validator = Fontisan::Validators::OpenTypeValidator.new
+report = validator.validate(font)
+
+# Check individual results
+name_check = report.result_of(:name_version)
+puts name_check.passed?
+puts name_check.severity
+----
+====
+
+==== Using custom validators
+
+===== General
+
+Custom validators inherit from `Fontisan::Validators::Validator` and define
+validation logic using the DSL.
+
+The DSL provides 6 check methods for different validation types:
+
+* `check_table` - Validate table-level properties
+* `check_field` - Validate specific field values
+* `check_structure` - Validate font structure and relationships
+* `check_usability` - Validate usability and best practices
+* `check_instructions` - Validate TrueType instructions/hinting
+* `check_glyphs` - Validate individual glyphs
+
+Each check receives a unique ID, severity level (:info, :warning, :error,
+:fatal), and a validation block.
+
+.Creating a custom validator
+[example]
+====
+[source,ruby]
+----
+require 'fontisan/validators/validator'
+
+# Define a custom validator
+class MyFontValidator < Fontisan::Validators::Validator
+  private
+
+  def define_checks
+    # Check name table
+    check_table :name_version, 'name', severity: :error do |table|
+      table.valid_version?
+    end
+
+    check_table :family_name, 'name', severity: :error do |table|
+      table.family_name_present?
+    end
+
+    # Check head table
+    check_table :head_magic, 'head', severity: :error do |table|
+      table.valid_magic?
+    end
+
+    check_table :units_per_em, 'head', severity: :error do |table|
+      table.valid_units_per_em?
+    end
+
+    # Check structure
+    check_structure :required_tables, severity: :error do |font|
+      %w[name head maxp hhea].all? { |tag| !font.table(tag).nil? }
+    end
+  end
+end
+
+# Use the validator
+font = Fontisan::FontLoader.load('font.ttf')
+validator = MyFontValidator.new
+report = validator.validate(font)
+
+# Check results
+puts report.valid?                           # => true/false
+puts report.status                           # => "valid", "valid_with_warnings", "invalid"
+puts report.summary.errors                   # => number of errors
+puts report.summary.warnings                 # => number of warnings
+
+# Query specific checks
+result = report.result_of(:name_version)
+puts result.passed?                          # => true/false
+puts result.severity                         # => "error"
+puts result.messages                         # => array of messages
+
+# Get all failed checks
+report.failed_checks.each do |check|
+  puts "#{check.check_id}: #{check.messages.join(', ')}"
+end
+
+# Serialize report
+puts report.to_yaml
+puts report.to_json
+----
+====
+
+
+.Using table validation helpers
+[example]
+====
+The validation framework integrates with 56 built-in validation helpers across
+core OpenType tables. These helpers perform specific validation checks and
+return boolean values.
+
+[source,ruby]
+----
+class ComprehensiveValidator < Fontisan::Validators::Validator
+  private
+
+  def define_checks
+    # Name table validation helpers
+    check_table :name_validation, 'name' do |table|
+      table.valid_version? &&
+        table.valid_encoding_heuristics? &&
+        table.family_name_present? &&
+        table.postscript_name_valid?
+    end
+
+    # Head table validation helpers
+    check_table :head_validation, 'head' do |table|
+      table.valid_magic? &&
+        table.valid_version? &&
+        table.valid_units_per_em? &&
+        table.valid_bounding_box? &&
+        table.valid_index_to_loc_format? &&
+        table.valid_glyph_data_format?
+    end
+
+    # Maxp table validation helpers
+    check_table :maxp_validation, 'maxp' do |table|
+      table.valid_version? &&
+        table.valid_num_glyphs? &&
+        table.valid_max_zones? &&
+        table.has_truetype_metrics? &&
+        table.reasonable_metrics?
+    end
+  end
+end
+----
+====
+
+.Handling validation results
+[example]
+====
+[source,ruby]
+----
+validator = MyFontValidator.new
+report = validator.validate(font)
+
+# Overall validation status
+if report.valid?
+  puts "Font is valid!"
+else
+  puts "Font has issues:"
+
+  # Show errors
+  report.errors.each do |error|
+    puts "  [ERROR] #{error.category}: #{error.message}"
+    puts "          Location: #{error.location}" if error.location
+  end
+
+  # Show warnings
+  report.warnings.each do |warning|
+    puts "  [WARN] #{warning.category}: #{warning.message}"
+  end
+end
+
+# Check specific validation results
+if report.result_of(:name_version)&.passed?
+  puts "Name table version is valid"
+else
+  puts "Name table version check failed"
+end
+
+# Get summary statistics
+puts "\nValidation Summary:"
+puts "  Total checks: #{report.check_results.count}"
+puts "  Passed: #{report.passed_checks.count}"
+puts "  Failed: #{report.failed_checks.count}"
+puts "  Errors: #{report.summary.errors}"
+puts "  Warnings: #{report.summary.warnings}"
+puts "  Info: #{report.summary.info}"
+----
+====
+
+==== Validation helpers
+
+===== General
+
+The validation framework provides 56 helper methods across 8 core OpenType
+tables. Each helper returns a boolean indicating whether the validation passed.
+
+Name table:
+
+* `valid_version?` - Check if version is 0 or 1
+* `valid_encoding_heuristics?` - Check platform/encoding combinations
+* `has_valid_platform_combos?` - Check for required platform combinations
+* `family_name_present?` - Check if family name exists and is non-empty
+* `postscript_name_present?` - Check if PostScript name exists and is non-empty
+* `postscript_name_valid?` - Check if PostScript name matches required pattern
+
+Head table:
+
+* `valid_magic?` - Check magic number (0x5F0F3CF5)
+* `valid_version?` - Check version is 1.0
+* `valid_units_per_em?` - Check units per em is valid (16-16384)
+* `valid_bounding_box?` - Check bounding box coordinates
+* `valid_index_to_loc_format?` - Check format is 0 or 1
+* `valid_glyph_data_format?` - Check format is 0
+
+Maxp Table:
+
+* `valid_version?` - Check version is 0.5 or 1.0
+* `valid_num_glyphs?` - Check num glyphs >= 1
+* `valid_max_zones?` - Check maxZones is 1 or 2
+* `has_truetype_metrics?` - Check TrueType metrics are present
+* `reasonable_metrics?` - Check metrics are within reasonable bounds
+
+Hhea Table:
+
+* `valid_version?` - Check version is 1.0
+* `valid_metric_data_format?` - Check format is 0
+* `valid_number_of_h_metrics?` - Check count >= 1
+* `valid_ascent_descent?` - Check signs are correct
+* `valid_line_gap?` - Check line gap >= 0
+* `valid_advance_width_max?` - Check max width > 0
+* `valid_caret_slope?` - Check caret slope values
+* `valid_x_max_extent?` - Check extent > 0
+
+Glyf Table:
+
+* `has_empty_glyphs?` - Check for empty glyphs
+* `has_clipped_glyphs?` - Check for clipped glyphs
+* `has_instructions?` - Check for TrueType instructions
+* `contours_valid?` - Check contour counts
+* `glyphs_accessible?` - Check glyph accessibility
+
+Cmap Table:
+
+* `valid_version?` - Check version is 0
+* `has_valid_subtables?` - Check subtable validity
+* `has_unicode_mapping?` - Check for Unicode support
+* `has_valid_bmp_coverage?` - Check BMP coverage
+* `has_valid_format4?` - Check format 4 subtable
+* `glyph_indices_valid?` - Check glyph index validity
+* `supports_platform?` - Check platform support
+
+Post Table:
+
+* `valid_version?` - Check version (1.0, 2.0, 2.5, 3.0, 4.0)
+* `valid_italic_angle?` - Check italic angle range
+* `valid_underline_position?` - Check underline metrics
+* `valid_underline_thickness?` - Check underline thickness
+* `valid_is_fixed_pitch?` - Check fixed pitch flag
+* `has_glyph_names?` - Check for glyph names
+
+OS/2 Table:
+
+* `valid_version?` - Check version (0-5)
+* `valid_weight_class?` - Check weight class (100-900)
+* `valid_width_class?` - Check width class (1-9)
+* `valid_vendor_id?` - Check vendor ID format
+* `valid_typo_metrics?` - Check typographic metrics
+* `valid_win_metrics?` - Check Windows metrics
+* `valid_unicode_ranges?` - Check Unicode range bits
+* `has_valid_panose?` - Check PANOSE classification
+* `valid_selection_flags?` - Check style selection flags
+* `valid_first_char_index?` - Check first character index
+* `valid_last_char_index?` - Check last character index
+* `valid_typo_ascender?` - Check typographic ascender
+* `valid_typo_descender?` - Check typographic descender
+
 
 == Version information
 
@@ -1599,6 +2088,31 @@ converter.supported_targets(:ttf)
 # => [:ttf, :otf, :woff2, :svg]
 ----
 
+=== Convert into WOFF2
+
+==== Validation
+
+WOFF2 encoding can be validated automatically to ensure spec compliance:
+
+.Validation example
+[example]
+====
+[source,ruby]
+----
+encoder = Fontisan::Converters::Woff2Encoder.new
+result = encoder.convert(font, {
+  transform_tables: true,
+  validate: true,
+  validation_level: :strict  # :strict, :standard, or :lenient
+})
+
+report = result[:validation_report]
+puts "Valid: #{report.valid}"
+puts "Compression: #{report.info_issues.first.message}"
+----
+====
+
+
 
 === Validation
 

data/Rakefile

@@ -87,6 +87,9 @@ namespace :fixtures do
 
   # Create file tasks for each font
   fonts.each do |name, config|
+    # Skip fonts that should not be downloaded (already committed)
+    next if config[:skip_download]
+
     file config[:marker] do
       if config[:single_file]
         download_single_file(name, config[:url], config[:marker])
@@ -97,16 +100,26 @@ namespace :fixtures do
   end
 
   desc "Download all test fixture fonts"
-  task download: fonts.values.map { |config| config[:marker] }
+  task download: fonts.values.reject { |config| config[:skip_download] }.map { |config| config[:marker] }
 
   desc "Clean downloaded fixtures"
   task :clean do
-    fonts.values.map { |config| config[:target_dir] }.each do |path|
-      next unless File.exist?(path)
-
-      puts "[fixtures:clean] Removing #{path}..."
-      FileUtils.rm_rf(path)
-      puts "[fixtures:clean] Removed #{path}"
+    fonts.values.reject { |config| config[:skip_download] }.each do |config|
+      if config[:single_file]
+        # For single files, just delete the marker file itself
+        if File.exist?(config[:marker])
+          puts "[fixtures:clean] Removing #{config[:marker]}..."
+          FileUtils.rm_f(config[:marker])
+          puts "[fixtures:clean] Removed #{config[:marker]}"
+        end
+      else
+        # 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
+      end
     end
   end
 end

data/lib/fontisan/cli.rb

@@ -350,13 +350,62 @@ module Fontisan
       handle_error(e)
     end
 
-    desc "validate FONT_FILE", "Validate font file structure and checksums"
-    option :verbose, type: :boolean, default: false,
-                     desc: "Show detailed validation information"
+    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
+        usability        - Installation compatibility
+        production       - Comprehensive quality (default)
+        web              - Web font readiness
+        spec_compliance  - OpenType spec compliance
+        default          - Production profile (alias)
+
+      Return values (with -R/--return-value-results):
+        0  No results
+        1  Execution errors
+        2  Fatal errors found
+        3  Major errors found
+        4  Minor errors found
+        5  Spec violations found
+    DESC
+
+    option :exclude, aliases: "-e", type: :array, desc: "Tests to exclude"
+    option :list, aliases: "-l", type: :boolean, desc: "List available tests"
+    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 :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"
+
     def validate(font_file)
-      command = Commands::ValidateCommand.new(font_file,
-                                              verbose: options[:verbose])
-      exit command.run
+      if options[:list]
+        list_available_tests
+        return
+      end
+
+      cmd = Commands::ValidateCommand.new(
+        input: font_file,
+        profile: options[:test_list],
+        exclude: options[:exclude] || [],
+        output: options[:output],
+        format: options[:format].to_sym,
+        full_report: options[:full_report],
+        summary_report: options[:summary_report],
+        table_report: options[:table_report],
+        verbose: options[:verbose],
+        suppress_warnings: options[:suppress_warnings],
+        return_value_results: options[:return_value_results]
+      )
+
+      exit cmd.run
+    rescue => e
+      error "Validation failed: #{e.message}"
+      exit 1
     end
 
     desc "export FONT_FILE", "Export font to TTX/YAML/JSON format"
@@ -555,5 +604,17 @@ module Fontisan
       warn message unless options[:quiet]
       exit 1
     end
+
+    # List available validation tests/profiles
+    #
+    # @return [void]
+    def list_available_tests
+      require_relative "validators/profile_loader"
+      profiles = Validators::ProfileLoader.all_profiles
+      puts "Available validation profiles:"
+      profiles.each do |profile_name, config|
+        puts "  #{profile_name.to_s.ljust(20)} - #{config[:description]}"
+      end
+    end
   end
 end