fontisan 0.1.0 → 0.2.0

data/lib/fontisan/commands/unpack_command.rb

@@ -0,0 +1,338 @@
+# frozen_string_literal: true
+
+require_relative "base_command"
+require_relative "../font_loader"
+require_relative "../font_writer"
+require "fileutils"
+
+module Fontisan
+  module Commands
+    # Command for unpacking fonts from TTC/OTC collections
+    #
+    # This command extracts individual font files from a TTC (TrueType Collection)
+    # or OTC (OpenType Collection) file. It can extract all fonts or a specific
+    # font by index, optionally converting to different formats during extraction.
+    #
+    # @example Extract all fonts
+    #   command = UnpackCommand.new(
+    #     'family.ttc',
+    #     output_dir: 'fonts/',
+    #     format: :ttf
+    #   )
+    #   result = command.run
+    #   puts "Extracted #{result[:fonts_extracted]} fonts"
+    #
+    # @example Extract specific font
+    #   command = UnpackCommand.new(
+    #     'family.ttc',
+    #     output_dir: 'fonts/',
+    #     font_index: 2
+    #   )
+    #   result = command.run
+    class UnpackCommand
+      # Initialize unpack command
+      #
+      # @param collection_path [String] Path to TTC/OTC file
+      # @param options [Hash] Command options
+      # @option options [String] :output_dir Output directory (required)
+      # @option options [Integer] :font_index Extract specific font index (optional)
+      # @option options [Symbol, String] :format Output format (ttf, otf, woff, woff2)
+      # @option options [String] :prefix Filename prefix for extracted fonts
+      # @option options [Boolean] :verbose Enable verbose output (default: false)
+      # @raise [ArgumentError] if collection_path or output_dir is invalid
+      def initialize(collection_path, options = {})
+        @collection_path = collection_path
+        @options = options
+        @output_dir = options[:output_dir]
+        @font_index = options[:font_index]
+        @format = parse_format(options[:format])
+        @prefix = options[:prefix]
+        @verbose = options.fetch(:verbose, false)
+
+        validate_options!
+      end
+
+      # Execute the unpack command
+      #
+      # Extracts fonts from the collection and writes them as individual files.
+      #
+      # @return [Hash] Result information with:
+      #   - :collection [String] - Input collection path
+      #   - :output_dir [String] - Output directory
+      #   - :num_fonts [Integer] - Total fonts in collection
+      #   - :fonts_extracted [Integer] - Number of fonts extracted
+      #   - :extracted_files [Array<String>] - Paths to extracted files
+      # @raise [Fontisan::Error] if unpacking fails
+      def run
+        puts "Loading collection from #{File.basename(@collection_path)}..." if @verbose
+
+        # Load collection
+        collection = load_collection
+
+        # Create output directory
+        FileUtils.mkdir_p(@output_dir) unless Dir.exist?(@output_dir)
+
+        # Determine which fonts to extract
+        indices_to_extract = determine_indices(collection)
+
+        puts "Extracting #{indices_to_extract.size} font(s)..." if @verbose
+
+        # Extract fonts
+        extracted_files = extract_fonts(collection, indices_to_extract)
+
+        # Display results
+        if @verbose
+          display_results(collection, extracted_files)
+        end
+
+        {
+          collection: @collection_path,
+          output_dir: @output_dir,
+          num_fonts: collection.font_count,
+          fonts_extracted: extracted_files.size,
+          extracted_files: extracted_files,
+        }
+      rescue Fontisan::Error => e
+        raise Fontisan::Error, "Collection unpacking failed: #{e.message}"
+      rescue ArgumentError
+        # Let ArgumentError propagate for validation errors
+        raise
+      rescue StandardError => e
+        raise Fontisan::Error, "Unexpected error during unpacking: #{e.message}"
+      end
+
+      private
+
+      # Validate command options
+      #
+      # @raise [ArgumentError] if options are invalid
+      def validate_options!
+        # Must have output directory
+        unless @output_dir
+          raise ArgumentError, "Output directory is required (--output-dir)"
+        end
+
+        # Check collection file exists
+        unless File.exist?(@collection_path)
+          raise ArgumentError, "Collection file not found: #{@collection_path}"
+        end
+
+        # Validate font index if provided
+        if @font_index&.negative?
+          raise ArgumentError, "Font index must be >= 0, got #{@font_index}"
+        end
+      end
+
+      # Load collection file
+      #
+      # @return [TrueTypeCollection, OpenTypeCollection] Loaded collection
+      # @raise [Fontisan::Error] if loading fails
+      def load_collection
+        # Try to detect format from extension
+        ext = File.extname(@collection_path).downcase
+
+        File.open(@collection_path, "rb") do |io|
+          # Read tag to determine type
+          tag = io.read(4)
+          io.rewind
+
+          unless tag == "ttcf"
+            raise Fontisan::Error,
+                  "Not a valid TTC/OTC file (invalid signature)"
+          end
+
+          # Load as TTC or OTC based on extension hint
+          # Both use same structure, main difference is expected font types
+          if ext == ".otc"
+            require_relative "../open_type_collection"
+            OpenTypeCollection.read(io)
+          else
+            require_relative "../true_type_collection"
+            TrueTypeCollection.read(io)
+          end
+        end
+      rescue Errno::ENOENT
+        raise Fontisan::Error, "Collection file not found: #{@collection_path}"
+      rescue BinData::ValidityError => e
+        raise Fontisan::Error, "Invalid collection file: #{e.message}"
+      end
+
+      # Determine which font indices to extract
+      #
+      # @param collection [TrueTypeCollection, OpenTypeCollection] Collection
+      # @return [Array<Integer>] Array of font indices
+      # @raise [ArgumentError] if font_index is out of range
+      def determine_indices(collection)
+        if @font_index
+          # Extract specific font
+          if @font_index >= collection.font_count
+            raise ArgumentError,
+                  "Font index #{@font_index} out of range (collection has #{collection.font_count} fonts)"
+          end
+          [@font_index]
+        else
+          # Extract all fonts
+          (0...collection.font_count).to_a
+        end
+      end
+
+      # Extract fonts from collection
+      #
+      # @param collection [TrueTypeCollection, OpenTypeCollection] Collection
+      # @param indices [Array<Integer>] Indices to extract
+      # @return [Array<String>] Paths to extracted files
+      def extract_fonts(collection, indices)
+        extracted_files = []
+
+        File.open(@collection_path, "rb") do |io|
+          fonts = collection.extract_fonts(io)
+
+          indices.each do |index|
+            font = fonts[index]
+            filename = generate_filename(font, index)
+            output_path = File.join(@output_dir, filename)
+
+            puts "  [#{index + 1}/#{indices.size}] Extracting to #{filename}..." if @verbose
+
+            # Write font
+            write_font(font, output_path)
+
+            extracted_files << output_path
+          end
+        end
+
+        extracted_files
+      end
+
+      # Generate output filename for extracted font
+      #
+      # @param font [TrueTypeFont, OpenTypeFont] Font object
+      # @param index [Integer] Font index
+      # @return [String] Filename
+      def generate_filename(font, index)
+        # Try to get font name from name table
+        base_name = nil
+        if font.respond_to?(:table) && font.table("name")
+          name_table = font.table("name")
+          # Try to get PostScript name, then family name
+          base_name = name_table.english_name(Tables::Name::POSTSCRIPT_NAME) ||
+            name_table.english_name(Tables::Name::FAMILY)
+        end
+
+        # Fallback to prefix or generic name
+        base_name ||= @prefix || "font"
+        base_name = "#{base_name}_#{index}" unless @font_index
+
+        # Clean filename
+        base_name = base_name.gsub(/[^a-zA-Z0-9_-]/, "_")
+
+        # Add extension based on format
+        ext = format_extension
+        "#{base_name}#{ext}"
+      end
+
+      # Write font to file
+      #
+      # @param font [TrueTypeFont, OpenTypeFont] Font object
+      # @param output_path [String] Output file path
+      # @return [void]
+      def write_font(font, output_path)
+        if @format
+          # Convert to specified format
+          convert_and_write(font, output_path)
+        else
+          # Write in native format
+          font.to_file(output_path)
+        end
+      end
+
+      # Convert font and write to file
+      #
+      # @param font [TrueTypeFont, OpenTypeFont] Font object
+      # @param output_path [String] Output file path
+      # @return [void]
+      def convert_and_write(font, output_path)
+        require_relative "../converters/format_converter"
+
+        converter = Converters::FormatConverter.new
+        converter.convert(font, @format, output_path: output_path)
+      rescue StandardError => e
+        raise Fontisan::Error, "Format conversion failed: #{e.message}"
+      end
+
+      # Parse format option
+      #
+      # @param format [Symbol, String, nil] Format option
+      # @return [Symbol, nil] Parsed format
+      def parse_format(format)
+        return nil unless format
+
+        return format if format.is_a?(Symbol)
+
+        case format.to_s.downcase
+        when "ttf"
+          :ttf
+        when "otf"
+          :otf
+        when "woff"
+          :woff
+        when "woff2"
+          :woff2
+        end
+      end
+
+      # Get file extension for format
+      #
+      # @return [String] File extension with dot
+      def format_extension
+        case @format
+        when :ttf
+          ".ttf"
+        when :otf
+          ".otf"
+        when :woff
+          ".woff"
+        when :woff2
+          ".woff2"
+        else
+          # Detect from collection type
+          ext = File.extname(@collection_path).downcase
+          ext == ".otc" ? ".otf" : ".ttf"
+        end
+      end
+
+      # Display extraction results
+      #
+      # @param collection [TrueTypeCollection, OpenTypeCollection] Collection
+      # @param extracted_files [Array<String>] Extracted file paths
+      # @return [void]
+      def display_results(collection, extracted_files)
+        puts "\n=== Extraction Complete ==="
+        puts "Collection: #{File.basename(@collection_path)}"
+        puts "Total fonts: #{collection.font_count}"
+        puts "Extracted: #{extracted_files.size}"
+        puts "Output directory: #{@output_dir}"
+        puts "\nExtracted files:"
+        extracted_files.each do |path|
+          size = File.size(path)
+          puts "  - #{File.basename(path)} (#{format_bytes(size)})"
+        end
+        puts ""
+      end
+
+      # Format bytes for display
+      #
+      # @param bytes [Integer] Byte count
+      # @return [String] Formatted string
+      def format_bytes(bytes)
+        if bytes < 1024
+          "#{bytes} B"
+        elsif bytes < 1024 * 1024
+          "#{(bytes / 1024.0).round(2)} KB"
+        else
+          "#{(bytes / (1024.0 * 1024)).round(2)} MB"
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/commands/validate_command.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require_relative "base_command"
+require_relative "../validation/validator"
+require_relative "../font_loader"
+
+module Fontisan
+  module Commands
+    # ValidateCommand provides CLI interface for font validation
+    #
+    # This command validates fonts against quality checks, structural integrity,
+    # and OpenType specification compliance. It supports different validation
+    # levels and output formats.
+    #
+    # @example Validating a font
+    #   command = ValidateCommand.new(
+    #     input: "font.ttf",
+    #     level: :standard,
+    #     format: :text
+    #   )
+    #   exit_code = command.run
+    class ValidateCommand < BaseCommand
+      # Initialize validate command
+      #
+      # @param input [String] Path to font file
+      # @param level [Symbol] Validation level (:strict, :standard, :lenient)
+      # @param format [Symbol] Output format (:text, :yaml, :json)
+      # @param verbose [Boolean] Show all issues (default: true)
+      # @param quiet [Boolean] Only return exit code, no output (default: false)
+      def initialize(input:, level: :standard, format: :text, verbose: true,
+quiet: false)
+        super()
+        @input = input
+        @level = level.to_sym
+        @format = format.to_sym
+        @verbose = verbose
+        @quiet = quiet
+      end
+
+      # Run the validation command
+      #
+      # @return [Integer] Exit code (0 = valid, 1 = errors, 2 = warnings only)
+      def run
+        validate_params!
+
+        # Load font
+        font = load_font
+        return 1 unless font
+
+        # Create validator
+        validator = Validation::Validator.new(level: @level)
+
+        # Run validation
+        report = validator.validate(font, @input)
+
+        # Output results unless quiet mode
+        output_report(report) unless @quiet
+
+        # Return appropriate exit code
+        determine_exit_code(report)
+      rescue StandardError => e
+        puts "Error: #{e.message}" unless @quiet
+        puts e.backtrace.join("\n") if @verbose && !@quiet
+        1
+      end
+
+      private
+
+      # Validate command parameters
+      #
+      # @raise [ArgumentError] if parameters are invalid
+      # @return [void]
+      def validate_params!
+        if @input.nil? || @input.empty?
+          raise ArgumentError,
+                "Input file is required"
+        end
+        unless File.exist?(@input)
+          raise ArgumentError,
+                "Input file does not exist: #{@input}"
+        end
+
+        valid_levels = %i[strict standard lenient]
+        unless valid_levels.include?(@level)
+          raise ArgumentError,
+                "Invalid level: #{@level}. Must be one of: #{valid_levels.join(', ')}"
+        end
+
+        valid_formats = %i[text yaml json]
+        unless valid_formats.include?(@format)
+          raise ArgumentError,
+                "Invalid format: #{@format}. Must be one of: #{valid_formats.join(', ')}"
+        end
+      end
+
+      # Load the font file
+      #
+      # @return [TrueTypeFont, OpenTypeFont, nil] The loaded font or nil on error
+      def load_font
+        FontLoader.load(@input)
+      rescue StandardError => e
+        puts "Error loading font: #{e.message}" unless @quiet
+        nil
+      end
+
+      # Output validation report in requested format
+      #
+      # @param report [Models::ValidationReport] The validation report
+      # @return [void]
+      def output_report(report)
+        case @format
+        when :text
+          output_text(report)
+        when :yaml
+          output_yaml(report)
+        when :json
+          output_json(report)
+        end
+      end
+
+      # Output report in text format
+      #
+      # @param report [Models::ValidationReport] The validation report
+      # @return [void]
+      def output_text(report)
+        if @verbose
+          puts report.text_summary
+        else
+          # Compact output: just status and error/warning counts
+          status = report.valid ? "VALID" : "INVALID"
+          puts "#{status}: #{report.summary.errors} errors, #{report.summary.warnings} warnings"
+
+          # Show errors only in non-verbose mode
+          report.errors.each do |error|
+            puts "  [ERROR] #{error.message}"
+          end
+        end
+      end
+
+      # Output report in YAML format
+      #
+      # @param report [Models::ValidationReport] The validation report
+      # @return [void]
+      def output_yaml(report)
+        require "yaml"
+        puts report.to_yaml
+      end
+
+      # Output report in JSON format
+      #
+      # @param report [Models::ValidationReport] The validation report
+      # @return [void]
+      def output_json(report)
+        require "json"
+        puts report.to_json
+      end
+
+      # Determine exit code based on validation results
+      #
+      # Exit codes:
+      # - 0: Valid (no errors, or only warnings in lenient mode)
+      # - 1: Has errors
+      # - 2: Has warnings only (no errors)
+      #
+      # @param report [Models::ValidationReport] The validation report
+      # @return [Integer] Exit code
+      def determine_exit_code(report)
+        if report.has_errors?
+          1
+        elsif report.has_warnings?
+          2
+        else
+          0
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/commands/variable_command.rb

@@ -1,16 +1,24 @@
 # frozen_string_literal: true
 
+require_relative "base_command"
+require_relative "../variation/inspector"
+
 module Fontisan
   module Commands
     # Command to extract variable font information.
     #
     # This command extracts variation axes and named instances from variable
-    # fonts using the fvar (Font Variations) table.
+    # fonts using the fvar (Font Variations) table. It also provides
+    # detailed inspection capabilities through the Inspector class.
     #
     # @example Extract variable font information
     #   command = VariableCommand.new("path/to/variable-font.ttf")
     #   info = command.run
     #   puts info.axes.first.tag
+    #
+    # @example Inspect variable font structure
+    #   command = VariableCommand.new("path/to/variable-font.ttf")
+    #   command.inspect(format: "json")
     class VariableCommand < BaseCommand
       # Extract variable font information from the fvar table.
       #
@@ -56,6 +64,27 @@ module Fontisan
 
         result
       end
+
+      # Inspect variable font structure
+      #
+      # Provides detailed analysis of variable font structure including
+      # axes, instances, regions, and statistics.
+      #
+      # @param options [Hash] Inspection options
+      # @option options [String] :format Output format ("json" or "yaml")
+      # @return [String] Formatted inspection output
+      def inspect(options = {})
+        inspector = Variation::Inspector.new(font)
+
+        format = options[:format] || "json"
+
+        case format.downcase
+        when "yaml"
+          inspector.export_yaml
+        else
+          inspector.export_json
+        end
+      end
     end
   end
 end

data/lib/fontisan/config/collection_settings.yml

@@ -0,0 +1,56 @@
+# Collection Creation Settings
+# Configuration for TTC/OTC (TrueType/OpenType Collection) creation
+
+# Table sharing strategy determines how aggressive the deduplication is
+# Options:
+#   - conservative: Only share tables with exact checksum match (safest)
+#   - aggressive: Consider sharing even with minor differences (not implemented yet)
+table_sharing_strategy: conservative
+
+# Alignment requirement for tables in bytes
+# Must be 4 for TrueType/OpenType compliance
+alignment: 4
+
+# Optimize table order for better performance
+# When true, tables are ordered according to recommended order
+optimize_table_order: true
+
+# Verify checksums after writing
+# When true, verifies all checksums match expected values
+verify_checksums: true
+
+# Priority tables for sharing
+# These tables are commonly identical across font families
+# and should be prioritized for sharing to maximize space savings
+priority_tables:
+  - head  # Font header
+  - hhea  # Horizontal header
+  - maxp  # Maximum profile
+  - OS/2  # OS/2 and Windows metrics
+  - name  # Naming table
+  - post  # PostScript information
+  - cvt   # Control value table
+  - fpgm  # Font program
+  - prep  # Control value program
+
+# Tables that should typically not be shared
+# These tables often differ between fonts in a family
+unique_tables:
+  - cmap  # Character to glyph mapping (can vary)
+  - glyf  # Glyph data (usually unique per font)
+  - loca  # Index to location (tied to glyf)
+  - hmtx  # Horizontal metrics (varies by font)
+  - GSUB  # Glyph substitution (may vary)
+  - GPOS  # Glyph positioning (may vary)
+
+# Minimum space savings threshold (in bytes)
+# If potential savings are below this, a warning is issued
+min_savings_threshold: 1024
+
+# Maximum collection size (in bytes)
+# Collections larger than this will trigger a warning
+# Set to 0 to disable
+max_collection_size: 104857600  # 100 MB
+
+# Enable verbose logging during collection creation
+verbose: false