fontisan 0.2.13 → 0.2.16

data/docs/guide/validation/helpers.md

@@ -0,0 +1,188 @@
+---
+title: Validation Helpers
+---
+
+# Validation Helpers
+
+Fontisan includes 56 validation helpers organized into categories.
+
+## Table Validation
+
+### required_tables
+
+Checks for required OpenType tables.
+
+```ruby
+# Required: name, head, maxp, hhea, post
+# Optional but common: cmap, hmtx, loca, glyf/cff
+```
+
+### table_checksums
+
+Validates table checksums.
+
+### table_lengths
+
+Verifies table lengths match headers.
+
+## Name Table Validation
+
+### name_version
+
+Validates version string format.
+
+### family_name
+
+Checks family name presence and format.
+
+### postscript_name
+
+Validates PostScript name compliance.
+
+### name_completeness
+
+Verifies all required name records.
+
+### name_encoding
+
+Validates name record encoding.
+
+## Head Table Validation
+
+### head_magic
+
+Validates magic number (0x5F0F3CF5).
+
+### head_version
+
+Checks head table version.
+
+### head_units_per_em
+
+Validates UPM value (typically 1000 or 2048).
+
+### head_timestamps
+
+Checks created/modified timestamps.
+
+## Metrics Validation
+
+### hhea_metrics
+
+Validates horizontal header metrics.
+
+### vhea_metrics
+
+Validates vertical header metrics.
+
+### os2_metrics
+
+Validates OS/2 table metrics.
+
+### line_gap
+
+Checks line gap values.
+
+## Glyph Validation
+
+### glyph_count
+
+Verifies glyph count consistency.
+
+### glyph_bounds
+
+Validates glyph bounding boxes.
+
+### composite_glyphs
+
+Checks composite glyph structure.
+
+### glyph_names
+
+Validates glyph naming.
+
+## CMAP Validation
+
+### cmap_presence
+
+Checks cmap table presence.
+
+### cmap_format
+
+Validates cmap format.
+
+### cmap_coverage
+
+Checks Unicode coverage.
+
+### cmap_duplicates
+
+Detects duplicate mappings.
+
+## Layout Table Validation
+
+### gsub_validity
+
+Validates GSUB table structure.
+
+### gpos_validity
+
+Validates GPOS table structure.
+
+### feature_list
+
+Checks feature list validity.
+
+### script_list
+
+Validates script list.
+
+## Advanced Validation
+
+### hint_validity
+
+Validates TrueType hints.
+
+### cff_validity
+
+Validates CFF table structure.
+
+### glyf_loca_consistency
+
+Checks glyf/loca consistency.
+
+### maxp_accuracy
+
+Verifies maxp values accuracy.
+
+## Using Helpers Programmatically
+
+```ruby
+require 'fontisan'
+
+font = Fontisan::FontLoader.load('font.ttf')
+validator = Fontisan::Validators::FontValidator.new(font)
+
+# Run specific helper
+result = validator.check_required_tables
+puts result.valid?  # => true or false
+
+# Get all helper results
+results = validator.run_all_helpers
+results.each do |check_id, result|
+  puts "#{check_id}: #{result.status}"
+end
+```
+
+## Helper Categories
+
+| Category | Helpers | Focus |
+|----------|---------|-------|
+| Table | 12 | Table structure |
+| Name | 8 | Name records |
+| Head | 6 | Header validation |
+| Metrics | 10 | Font metrics |
+| Glyph | 8 | Glyph data |
+| CMAP | 6 | Character mapping |
+| Layout | 6 | GSUB/GPOS |
+| Advanced | 10 | Complex checks |

data/docs/guide/validation/index.md

@@ -0,0 +1,132 @@
+---
+title: Validation Overview
+---
+
+# Validation Overview
+
+Fontisan provides a comprehensive validation framework for ensuring font quality, structural integrity, and compliance with OpenType specifications.
+
+## Validation Profiles
+
+Fontisan includes predefined validation profiles:
+
+| Profile | Checks | Speed | Use Case |
+|---------|--------|-------|----------|
+| `indexability` | 8 | Fast | Font discovery and indexing |
+| `usability` | 26 | Medium | Font installation compatibility |
+| `production` | 37 | Full | Comprehensive quality (default) |
+| `web` | 18 | Medium | Web embedding readiness |
+| `spec_compliance` | Full | Slow | OpenType specification compliance |
+
+### List Profiles
+
+```bash
+fontisan validate --list
+
+# Available validation profiles:
+#   indexability         - Fast validation for font discovery
+#   usability            - Basic usability for installation
+#   production           - Comprehensive quality checks
+#   web                  - Web embedding and optimization
+#   spec_compliance      - Full OpenType spec compliance
+```
+
+## CLI Usage
+
+### Basic Validation
+
+```bash
+# Validate with default profile (production)
+fontisan validate font.ttf
+
+# Font: font.ttf
+# Status: VALID
+#
+# Summary:
+#   Checks performed: 37
+#   Passed: 37
+#   Failed: 0
+```
+
+### With Specific Profile
+
+```bash
+# Validate for web use
+fontisan validate font.ttf -t web
+
+# Validate for indexing
+fontisan validate font.ttf -t indexability
+```
+
+### Output Formats
+
+```bash
+# Table format
+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
+```
+
+### With Summary
+
+```bash
+fontisan validate font.ttf -t web -S
+
+# Failed checks:
+#   web_font_tables      - Missing required GSUB table
+```
+
+## Ruby API
+
+### Basic Validation
+
+```ruby
+require 'fontisan'
+
+# Validate with default profile
+report = Fontisan.validate('font.ttf')
+puts report.valid?  # => true or false
+
+# Validate with specific profile
+report = Fontisan.validate('font.ttf', profile: :web)
+
+if report.valid?
+  puts "Font is valid!"
+else
+  puts "Font has #{report.summary.errors} errors"
+end
+```
+
+### Query Results
+
+```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 statistics
+failed_ids = report.failed_check_ids
+pass_rate = report.pass_rate
+
+# Export results
+yaml_output = report.to_yaml
+json_output = report.to_json
+summary = report.to_summary  # "2 errors, 3 warnings, 0 info"
+```
+
+## Next Steps
+
+- [Validation Profiles](/guide/validation/profiles) — Detailed profile documentation
+- [Validation Helpers](/guide/validation/helpers) — Individual validation checks
+- [Custom Validators](/guide/validation/custom) — Create custom validation rules

data/docs/guide/validation/profiles.md

@@ -0,0 +1,156 @@
+---
+title: Validation Profiles
+---
+
+# Validation Profiles
+
+Fontisan includes 5 validation profiles for different use cases.
+
+## indexability
+
+Fast font discovery and indexing.
+
+| Property | Value |
+|----------|-------|
+| Checks | 8 |
+| Focus | Metadata-only |
+| Speed | ~5x faster than production |
+
+**Use Cases:**
+- Font indexing systems
+- Quick format verification
+- Batch font discovery
+
+```bash
+fontisan validate font.ttf -t indexability
+```
+
+**Checks Performed:**
+- Font format validity
+- Basic table presence
+- Name table readability
+- Magic number validation
+
+## usability
+
+Font installation compatibility.
+
+| Property | Value |
+|----------|-------|
+| Checks | 26 |
+| Focus | macOS Font Book compatibility |
+| Speed | Medium |
+
+**Use Cases:**
+- Font installation verification
+- Desktop font deployment
+- User-facing font distribution
+
+```bash
+fontisan validate font.ttf -t usability
+```
+
+**Checks Include:**
+- All indexability checks
+- Installation requirements
+- Name table completeness
+- Metrics validity
+
+## production
+
+Comprehensive production quality (default).
+
+| Property | Value |
+|----------|-------|
+| Checks | 37 |
+| Focus | OpenType spec compliance |
+| Speed | Full |
+
+**Use Cases:**
+- Font production pipeline
+- Quality assurance
+- Font release validation
+
+```bash
+fontisan validate font.ttf -t production
+# or
+fontisan validate font.ttf
+```
+
+**Checks Include:**
+- All usability checks
+- OpenType specification compliance
+- Cross-platform compatibility
+- Advanced table validation
+
+## web
+
+Web embedding readiness.
+
+| Property | Value |
+|----------|-------|
+| Checks | 18 |
+| Focus | Web deployment |
+| Speed | Medium |
+
+**Use Cases:**
+- Web font preparation
+- CDN deployment
+- Web performance optimization
+
+```bash
+fontisan validate font.ttf -t web
+```
+
+**Checks Include:**
+- Required web tables
+- Subset compatibility
+- WOFF/WOFF2 readiness
+- Performance optimization
+
+## spec_compliance
+
+Full OpenType specification compliance.
+
+| Property | Value |
+|----------|-------|
+| Checks | Full |
+| Focus | Detailed analysis |
+| Speed | Slow |
+
+**Use Cases:**
+- Font specification audit
+- Certification processes
+- Technical documentation
+
+```bash
+fontisan validate font.ttf -t spec_compliance
+```
+
+**Checks Include:**
+- All production checks
+- Detailed specification analysis
+- Edge case validation
+- Comprehensive reporting
+
+## Profile Comparison
+
+| Feature | indexability | usability | production | web | spec |
+|---------|-------------|-----------|------------|-----|------|
+| Basic validation | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Installation checks | - | ✓ | ✓ | - | ✓ |
+| Spec compliance | - | - | ✓ | - | ✓ |
+| Web optimization | - | - | - | ✓ | - |
+| Detailed analysis | - | - | - | - | ✓ |
+| Speed | Fast | Medium | Full | Medium | Slow |
+
+## Choosing a Profile
+
+| Task | Recommended Profile |
+|------|---------------------|
+| Indexing fonts | `indexability` |
+| Installing fonts | `usability` |
+| Releasing fonts | `production` |
+| Web deployment | `web` |
+| Specification audit | `spec_compliance` |
+| General use | `production` (default) |

data/docs/guide/validation.md

@@ -0,0 +1,47 @@
+# Font Validation
+
+Fontisan provides tools to validate font files for correctness and compliance.
+
+## Basic Validation
+
+```ruby
+require 'fontisan'
+
+# Validate a font file
+result = Fontisan.validate('font.ttf')
+
+if result.valid?
+  puts "Font is valid!"
+else
+  puts "Validation errors:"
+  result.errors.each do |error|
+    puts "  - #{error}"
+  end
+end
+```
+
+## Validation Options
+
+```ruby
+# Strict validation (includes optional checks)
+result = Fontisan.validate('font.ttf', strict: true)
+
+# Validate specific aspects
+result = Fontisan.validate('font.ttf', checks: [:tables, :glyphs, :names])
+```
+
+## Collection Validation
+
+For TrueType/OpenType Collections:
+
+```ruby
+# Validate a TTC file
+result = Fontisan.validate_collection('fonts.ttc')
+
+# Validate a specific font within the collection
+result = Fontisan.validate_collection('fonts.ttc', index: 0)
+```
+
+## Related
+
+- [Font Conversion](/guide/conversion) - Convert between formats