fontisan 0.2.7 → 0.2.9

data/docs/DOCUMENTATION_SUMMARY.md

@@ -0,0 +1,141 @@
+# Fontisan Documentation Summary
+
+This document provides an overview of all Fontisan documentation files and their purpose.
+
+## Main Documentation
+
+### README.adoc
+Primary user guide and reference documentation for Fontisan.
+
+## Feature Guides
+
+### Font Hinting
+- **File**: `docs/FONT_HINTING.adoc`
+- **Purpose**: Documentation for font hinting features in Fontisan
+- **Topics**: TrueType and PostScript hinting, hint extraction and application
+
+### Variable Font Operations
+- **File**: `docs/VARIABLE_FONT_OPERATIONS.adoc`
+- **Purpose**: Guide for working with variable fonts
+- **Topics**: Instance generation, axis manipulation, variation preservation
+
+### TTC Migration Guide
+- **File**: `docs/EXTRACT_TTC_MIGRATION.md`
+- **Purpose**: Migration guide for users of the `extract-ttc` gem
+- **Topics**: Moving from extract-ttc to Fontisan pack/unpack commands
+
+### Web Font Formats
+- **File**: `docs/WOFF_WOFF2_FORMATS.adoc`
+- **Purpose**: Documentation for WOFF and WOFF2 web font formats
+- **Topics**: Conversion to/from WOFF/WOFF2, web optimization
+
+### Color Fonts
+- **File**: `docs/COLOR_FONTS.adoc`
+- **Purpose**: Guide for color font formats
+- **Topics**: COLR/CPAL, SVG-in-OpenType, sbix color fonts
+
+### Validation
+- **File**: `docs/VALIDATION.adoc`
+- **Purpose**: Font validation framework documentation
+- **Topics**: Validation profiles, quality checks, OpenType spec compliance
+
+### Apple Legacy Fonts
+- **File**: `docs/APPLE_LEGACY_FONTS.adoc`
+- **Purpose**: Documentation for Apple legacy font formats
+- **Topics**: dfont format, Mac suitcase fonts
+
+### Collection Validation
+- **File**: `docs/COLLECTION_VALIDATION.adoc`
+- **Purpose**: Guide for validating font collections (TTC/OTC/dfont)
+- **Topics**: Collection-specific validation, profile selection
+
+## CLI Commands Reference
+
+Fontisan provides the following CLI commands:
+
+| Command | Purpose |
+|---------|---------|
+| `info` | Display font information |
+| `ls` | List contents (fonts in collection or font summary) |
+| `tables` | List OpenType tables |
+| `glyphs` | List glyph names |
+| `unicode` | List Unicode to glyph mappings |
+| `variable` | Display variable font information |
+| `optical-size` | Display optical size information |
+| `scripts` | List supported scripts from GSUB/GPOS tables |
+| `features` | List GSUB/GPOS features |
+| `subset` | Subset a font to specific glyphs |
+| `convert` | Convert font to different format |
+| `instance` | Generate static font instance from variable font |
+| `pack` | Pack multiple fonts into TTC/OTC collection |
+| `unpack` | Unpack fonts from TTC/OTC collection |
+| `validate` | Validate font file |
+| `export` | Export font to TTX/YAML/JSON format |
+| `dump-table` | Dump raw table data to stdout |
+| `version` | Display version information |
+
+## Ruby API Reference
+
+### Fontisan Module Methods
+
+#### `Fontisan.info(path, brief: false, font_index: 0)`
+Get font information. Supports both full and brief modes.
+
+- **Parameters**:
+  - `path` (String): Path to font file
+  - `brief` (Boolean): Use brief mode for fast identification (default: false)
+  - `font_index` (Integer): Index for TTC/OTC files (default: 0)
+- **Returns**: `Models::FontInfo`, `Models::CollectionInfo`, or `Models::CollectionBriefInfo`
+- **Example**:
+  ```ruby
+  info = Fontisan.info("font.ttf", brief: true)
+  puts info.family_name
+  ```
+
+#### `Fontisan.validate(path, profile: :default, options: {})`
+Validate a font file using specified profile.
+
+- **Parameters**:
+  - `path` (String): Path to font file
+  - `profile` (Symbol/String): Validation profile (default: :default)
+  - `options` (Hash): Additional validation options
+- **Available Profiles**:
+  - `:indexability` - Fast validation for font discovery
+  - `:usability` - Basic usability for installation
+  - `:production` - Comprehensive quality checks (default)
+  - `:web` - Web embedding and optimization
+  - `:spec_compliance` - Full OpenType spec compliance
+  - `:default` - Alias for production profile
+- **Returns**: `Models::ValidationReport`
+- **Example**:
+  ```ruby
+  report = Fontisan.validate("font.ttf", profile: :web)
+  puts "Errors: #{report.summary.errors}"
+  ```
+
+### Fontisan::FontLoader
+
+Module for loading fonts in different modes.
+
+- **Methods**:
+  - `load(path, mode: :full)` - Load a font file
+- **Loading Modes**:
+  - `:full` - Load all tables
+  - `:metadata` - Load only metadata tables (name, head, hhea, maxp, OS/2, post)
+  - `:tables` - Load specific tables only
+  - `:structure` - Load structure tables only
+
+## Verification
+
+Documentation examples are verified by `spec/documentation_examples_spec.rb`.
+
+This spec ensures that:
+1. All CLI commands referenced in documentation exist
+2. All Ruby API methods are available
+3. All documentation files are present
+4. Command examples reference valid commands
+
+Run verification with:
+```bash
+bundle exec rspec spec/documentation_examples_spec.rb -v
+```

data/docs/FONT_HINTING.adoc

@@ -541,9 +541,12 @@ The hint system has comprehensive test coverage:
 * **Total Tests**: 306 (100% passing)
 * **Generator Tests**: 45
 * **Validator Tests**: 48
+* **Applier Tests**: 87 (PostScript: 63, TrueType: 24)
+* **Extractor Tests**: 23 (PostScript: 11, TrueType: 12)
+* **Converter Tests**: 29
 * **Round-Trip Tests**: 16
+* **Integration Tests**: 28 (Conversion: 11, Application: 17)
 * **Analyzer Tests**: 30
-* **Integration Tests**: 167
 
 Test files:
 
@@ -552,7 +555,12 @@ Test files:
 * link:../spec/fontisan/hints/hint_validator_spec.rb[hint_validator_spec.rb]
 * link:../spec/fontisan/hints/hint_round_trip_spec.rb[hint_round_trip_spec.rb]
 * link:../spec/fontisan/hints/hint_converter_spec.rb[hint_converter_spec.rb]
+* link:../spec/fontisan/hints/postscript_hint_applier_spec.rb[postscript_hint_applier_spec.rb]
+* link:../spec/fontisan/hints/postscript_hint_extractor_spec.rb[postscript_hint_extractor_spec.rb]
+* link:../spec/fontisan/hints/truetype_hint_applier_spec.rb[truetype_hint_applier_spec.rb]
+* link:../spec/fontisan/hints/truetype_hint_extractor_spec.rb[truetype_hint_extractor_spec.rb]
 * link:../spec/fontisan/hints/hint_conversion_integration_spec.rb[hint_conversion_integration_spec.rb]
+* link:../spec/fontisan/hints/hint_application_integration_spec.rb[hint_application_integration_spec.rb]
 
 == References
 

data/docs/VALIDATION.adoc

@@ -0,0 +1,254 @@
+= Font Validation Framework
+
+== General
+
+Fontisan provides a comprehensive validation framework for ensuring font quality,
+structural integrity, and compliance with OpenType specifications.
+
+The framework uses a declarative DSL for defining validation checks and supports
+multiple validation profiles for different use cases.
+
+== Validation profiles
+
+Fontisan includes predefined validation profiles:
+
+`indexability`:: Fast font discovery and indexing (8 checks, metadata-only, ~5x faster)
+
+`usability`:: Font installation compatibility (26 checks, macOS Font Book focused)
+
+`production`:: Comprehensive production quality (37 checks, OpenType spec compliance - default)
+
+`web`:: Web font embedding readiness (18 checks for web deployment)
+
+`spec_compliance`:: Full OpenType specification compliance (detailed analysis mode)
+
+[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)
+----
+
+== Command-line validation
+
+.Validate with default profile
+[example]
+====
+[source,shell]
+----
+$ fontisan validate font.ttf
+
+Font: font.ttf
+Status: VALID
+
+Summary:
+  Checks performed: 37
+  Passed: 37
+  Failed: 0
+
+Errors: 0
+Warnings: 0
+Info: 0
+----
+====
+
+.Validate for web use with summary
+[example]
+====
+[source,shell]
+----
+$ fontisan validate font.ttf -t web -S
+
+Font: font.ttf
+Status: VALID
+
+Summary:
+  Checks performed: 18
+  Passed: 17
+  Failed: 1
+
+Errors: 1
+Warnings: 0
+
+Failed checks:
+  web_font_tables      - Missing required GSUB table
+----
+====
+
+.Validation with 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
+----
+====
+====
+
+== Ruby API usage
+
+=== Using predefined profiles
+
+[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
+
+[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"
+----
+
+== Creating custom validators
+
+=== General
+
+Custom validators inherit from `Fontisan::Validators::Validator` and define
+validation logic using the DSL.
+
+The DSL provides 6 check methods:
+
+* `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
+
+.Creating a custom validator
+[example]
+====
+[source,ruby]
+----
+require 'fontisan/validators/validator'
+
+class MyFontValidator < Fontisan::Validators::Validator
+  private
+
+  def define_checks
+    # Check name table
+    check_table :name_validation, 'name', severity: :error do |table|
+      table.valid_version? &&
+        table.valid_encoding_heuristics? &&
+        table.family_name_present? &&
+        table.postscript_name_valid?
+    end
+
+    # Check head table
+    check_table :head_validation, 'head', severity: :error do |table|
+      table.valid_magic? &&
+        table.valid_version? &&
+        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)
+
+puts report.valid?                           # => true/false
+puts report.summary.errors                   # => number of errors
+puts report.summary.warnings                 # => number of warnings
+----
+====
+
+== Validation helpers
+
+The validation framework provides 56 helper methods across 8 core OpenType
+tables. Each helper returns a boolean indicating whether the validation passed.
+
+.Name table helpers:
+[example]
+====
+[source,ruby]
+----
+class MyValidator < Fontisan::Validators::Validator
+  private
+
+  def define_checks
+    check_table :name_validation, 'name', severity: :error do |table|
+      table.valid_version? &&
+        table.valid_encoding_heuristics? &&
+        table.family_name_present? &&
+        table.postscript_name_valid?
+    end
+  end
+end
+----
+====
+
+.Head table helpers:
+[example]
+====
+[source,ruby]
+----
+class MyValidator < Fontisan::Validators::Validator
+  private
+
+  def define_checks
+    check_table :head_validation, 'head', severity: :error 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
+  end
+end
+----
+====

data/docs/WOFF_WOFF2_FORMATS.adoc

@@ -0,0 +1,94 @@
+= WOFF and WOFF2 Font Format Support
+
+== General
+
+Fontisan provides comprehensive support for Web Open Font Format (WOFF) and WOFF2,
+including reading, writing, and conversion between these and other font formats.
+
+WOFF is a wrapper around SFNT fonts (TTF/OTF) using zlib compression, while WOFF2
+uses Brotli compression for better compression ratios and table transformations.
+
+=== Display WOFF/WOFF2 font information
+
+Show metadata specific to WOFF/WOFF2 fonts including version, compression details,
+and original font flavor.
+
+[source,shell]
+----
+$ fontisan info FONT.woff [--format FORMAT]
+----
+
+Where,
+
+`FONT.woff`:: Path to the WOFF or WOFF2 file
+`FORMAT`:: Output format: `text` (default), `json`, or `yaml`
+
+.Major version from WOFF/WOFF2 header
+[example]
+====
+[source,shell]
+----
+$ fontisan info /path/to/your/font.woff
+
+Font type:                WOFF (TrueType)
+Family:                   Example Font
+WOFF Major Version:       1
+WOFF Minor Version:       0
+WOFF Metadata:            0 entries
+WOFF Private Data:        0 bytes
+Original Font Flavor:     TrueType
+----
+====
+
+=== WOFF2 validation
+
+Fontisan validates WOFF2 fonts according to the specification, checking:
+
+* Required table presence and order
+* Table transformation flags (glyf, loca transformations)
+* Checksum validation for transformed tables
+* Compression format validation
+
+.Validation example
+[example]
+====
+[source,shell]
+----
+$ fontisan validate font.woff2 -t web
+
+CHECK_ID                     | STATUS | SEVERITY
+--------------------------------------------------------------
+woff2_required_tables        | PASS   | error
+woff2_table_transformations  | PASS   | error
+woff2_checksum_validation    | PASS   | error
+----
+====
+
+=== Convert fonts to WOFF/WOFF2
+
+Convert TTF/OTF fonts to web-optimized formats.
+
+[source,shell]
+----
+$ fontisan convert INPUT.ttf --to woff --output output.woff
+$ fontisan convert INPUT.ttf --to woff2 --output output.woff2
+----
+
+.Conversion with optimization
+[example]
+====
+[source,shell]
+----
+$ fontisan convert font.ttf --to woff2 --output font.woff2
+
+Converting font.ttf to WOFF2...
+  Input:  245.8 KB (TTF)
+  Output: 89.2 KB (WOFF2)
+  Ratio:  63.7% reduction
+
+Compression details:
+  Tables: 12
+  Brotli compression: Applied
+  Transformed tables: glyf, loca
+----
+====

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/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"