fontisan 0.2.17 → 0.2.23

data/lib/fontisan/converters/format_converter.rb

@@ -1,12 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "conversion_strategy"
-require_relative "table_copier"
-require_relative "outline_converter"
-require_relative "woff_writer"
-require_relative "woff2_encoder"
-require_relative "svg_generator"
-require_relative "type1_converter"
 require "yaml"
 
 module Fontisan
@@ -17,18 +10,14 @@ module Fontisan
     # primary entry point for all format conversion operations. It:
     # - Selects appropriate conversion strategy based on source/target formats
     # - Validates conversions against the conversion matrix
+    # - Validates user-supplied options against the selected strategy's schema
     # - Delegates actual conversion to strategy implementations
     # - Provides clean error messages for unsupported conversions
     #
     # The converter uses a strategy pattern with pluggable strategies for
-    # different conversion types:
-    # - OutlineConverter: TTF ↔ OTF conversions
-    # - TableCopier: Same-format operations
-    # - Woff2Encoder: TTF/OTF → WOFF2 compression
-    # - SvgGenerator: TTF/OTF → SVG font generation
-    #
-    # Supported conversions are defined in the conversion matrix configuration
-    # file, making it easy to extend without modifying code.
+    # different conversion types. Each strategy declares its own options via
+    # the `ConversionStrategy.option` DSL; the converter enforces the
+    # format ↔ option mapping at runtime.
     #
     # @example Converting TTF to OTF
     #   converter = Fontisan::Converters::FormatConverter.new
@@ -41,6 +30,81 @@ module Fontisan
     #   tables = converter.convert(font, :ttf)  # TTF to TTF
     #   FontWriter.write_to_file(tables, 'copy.ttf')
     class FormatConverter
+      # Registry of all strategy classes. Single source of truth for option
+      # discovery and strategy lookup. Add a new format by appending its
+      # strategy class here.
+      STRATEGY_CLASSES = [
+        TableCopier,
+        OutlineConverter,
+        Type1Converter,
+        WoffWriter,
+        Woff2Encoder,
+        SvgGenerator,
+      ].freeze
+
+      class << self
+        # All option names declared by any strategy. Used by ConversionOptions
+        # to keep its generating-options list in sync without duplicating the
+        # schema.
+        #
+        # @return [Array<Symbol>]
+        def all_strategy_option_names
+          STRATEGY_CLASSES.flat_map { |k| k.supported_options.map(&:name) }.uniq
+        end
+
+        # Look up the strategy class that handles a given conversion.
+        #
+        # @param source_format [Symbol]
+        # @param target_format [Symbol]
+        # @return [Class, nil]
+        def strategy_class_for(source_format, target_format)
+          STRATEGY_CLASSES.find do |klass|
+            klass.new.supports?(source_format, target_format)
+          rescue NotImplementedError
+            false
+          end
+        end
+
+        # Strategies whose supported_conversions include the given target.
+        #
+        # @param target_format [Symbol]
+        # @return [Array[Class]]
+        def strategies_for_target(target_format)
+          STRATEGY_CLASSES.select do |klass|
+            klass.new.supported_conversions.any? { |(_, t)| t == target_format }
+          rescue NotImplementedError
+            false
+          end
+        end
+
+        # Cross-format option check, independent of source format. Used by
+        # OutputWriter (which doesn't know the source format at write time)
+        # to catch e.g. `--brotli-quality` passed with `--to woff`.
+        #
+        # @param target_format [Symbol]
+        # @param options [Hash]
+        # @return [void]
+        # @raise [ArgumentError] if a user-supplied option is declared only by
+        #   strategies that don't handle this target
+        def validate_options_for_target!(target_format, options)
+          handlers = strategies_for_target(target_format)
+          handler_names = handlers.flat_map do |k|
+            k.supported_options.map(&:name)
+          end.to_set
+          non_handler_names = (STRATEGY_CLASSES - handlers)
+            .flat_map { |k| k.supported_options.map(&:name) }
+
+          conflicts = options.keys.select do |k|
+            non_handler_names.include?(k.to_sym)
+          end
+          return if conflicts.empty?
+
+          accepted = handler_names.empty? ? "(none)" : handler_names.join(", ")
+          raise ArgumentError,
+                "Option(s) #{conflicts.map(&:inspect).join(', ')} do not apply " \
+                "to --to #{target_format}. Accepted for #{target_format}: #{accepted}"
+        end
+      end
       # @return [Hash] Conversion matrix loaded from config
       attr_reader :conversion_matrix
 
@@ -52,15 +116,7 @@ module Fontisan
       # @param conversion_matrix_path [String, nil] Path to conversion matrix
       #   config. If nil, uses default.
       def initialize(conversion_matrix_path: nil)
-        @strategies = [
-          TableCopier.new,
-          OutlineConverter.new,
-          Type1Converter.new,
-          WoffWriter.new,
-          Woff2Encoder.new,
-          SvgGenerator.new,
-        ]
-
+        @strategies = self.class::STRATEGY_CLASSES.map(&:new)
         load_conversion_matrix(conversion_matrix_path)
       end
 
@@ -105,8 +161,20 @@ module Fontisan
         end
 
         strategy = select_strategy(source_format, target_format)
-        tables = strategy.convert(font,
-                                  options.merge(target_format: target_format))
+
+        # Enforce format ↔ option mapping at the orchestrator level so each
+        # strategy only sees options it declared. Cross-format misuse
+        # (e.g., `--zlib-level` on a WOFF2 conversion) raises here with a
+        # clear message; the strategy itself never has to defensively
+        # ignore unknown keys.
+        validate_strategy_options!(strategy, source_format, target_format,
+                                   options)
+        sliced = slice_strategy_options(options, strategy)
+
+        tables = strategy.convert(
+          font,
+          sliced.merge(target_format: target_format),
+        )
 
         # Preserve variation data if requested and font is variable
         if options.fetch(:preserve_variation, true) && variable_font?(font)
@@ -178,8 +246,6 @@ module Fontisan
       # @option options [Integer] :instance_index Named instance index
       # @return [Hash] Hash with :svg_xml key
       def convert_variable_to_svg(font, options = {})
-        require_relative "../variation/variable_svg_generator"
-
         coordinates = options[:instance_coordinates] || {}
         generator = Variation::VariableSvgGenerator.new(font, coordinates)
 
@@ -214,7 +280,6 @@ module Fontisan
 options)
         # Case 1: Compatible formats (same outline format) - just copy tables
         if compatible_variation_formats?(source_format, target_format)
-          require_relative "../variation/variation_preserver"
           Variation::VariationPreserver.preserve(font, tables, options)
 
         # Case 2: Different outline formats - convert variation data
@@ -278,9 +343,6 @@ options)
       # @return [Hash<String, String>] Tables with converted variation
       def convert_variation_data(font, tables, source_format, target_format,
 _options)
-        require_relative "../variation/variation_preserver"
-        require_relative "../variation/converter"
-
         # For now, just preserve common tables and warn about conversion
         warn "WARNING: Full variation conversion (#{source_format} → " \
              "#{target_format}) not yet implemented. " \
@@ -420,6 +482,55 @@ _options)
                 "Cannot detect font format: missing both CFF and glyf tables"
         end
       end
+
+      # Cross-format option check. Any user-supplied key that belongs to
+      # another strategy (i.e., is valid for some other format) raises
+      # immediately — this is what makes `--zlib-level --to woff2` fail
+      # predictably.
+      #
+      # @param strategy [Object] Selected strategy instance
+      # @param source_format [Symbol]
+      # @param target_format [Symbol]
+      # @param options [Hash]
+      # @return [void]
+      # @raise [ArgumentError] if a user option is declared by another strategy
+      # @raise [ArgumentError] if a user option fails type/range validation
+      def validate_strategy_options!(strategy, source_format, target_format,
+                                     options)
+        this_class = strategy.class
+        other_classes = self.class::STRATEGY_CLASSES.reject do |k|
+          k == this_class
+        end
+        other_names = other_classes.flat_map do |k|
+          k.supported_options.map(&:name)
+        end
+
+        conflicts = options.keys.select do |k|
+          other_names.include?(k.to_sym)
+        end
+
+        if conflicts.any?
+          accepted = this_class.supported_options.map(&:name)
+          accepted_list = accepted.empty? ? "(none)" : accepted.join(", ")
+          raise ArgumentError,
+                "Option(s) #{conflicts.map(&:inspect).join(', ')} do not apply " \
+                "to #{source_format}→#{target_format} " \
+                "(#{this_class.name.demodulize}). " \
+                "Accepted: #{accepted_list}"
+        end
+
+        this_class.validate_options!(slice_strategy_options(options, strategy))
+      end
+
+      # Slice an options hash to only the keys declared by the given strategy.
+      #
+      # @param options [Hash]
+      # @param strategy [Object]
+      # @return [Hash]
+      def slice_strategy_options(options, strategy)
+        names = strategy.class.supported_options.to_set(&:name)
+        options.select { |k, _| names.include?(k.to_sym) }
+      end
     end
   end
 end

data/lib/fontisan/converters/glyf_table_builder.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "../tables/glyf/glyph_builder"
-
 module Fontisan
   module Converters
     # Builds glyf and loca tables from glyph outlines

data/lib/fontisan/converters/outline_converter.rb

@@ -1,24 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "../conversion_options"
-require_relative "conversion_strategy"
-require_relative "../outline_extractor"
-require_relative "../models/outline"
-require_relative "../tables/cff/charstring_builder"
-require_relative "outline_extraction"
-require_relative "cff_table_builder"
-require_relative "glyf_table_builder"
-require_relative "outline_optimizer"
-require_relative "../hints/truetype_hint_extractor"
-require_relative "../hints/postscript_hint_extractor"
-require_relative "../hints/hint_converter"
-require_relative "../hints/truetype_hint_applier"
-require_relative "../hints/postscript_hint_applier"
-require_relative "../tables/cff2"
-require_relative "../variation/data_extractor"
-require_relative "../variation/instance_generator"
-require_relative "../variation/converter"
-
 module Fontisan
   module Converters
     # Strategy for converting between TTF and OTF outline formats

data/lib/fontisan/converters/outline_extraction.rb

@@ -1,10 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "../outline_extractor"
-require_relative "../tables/cff/charstring_builder"
-require_relative "../tables/glyf/glyph_builder"
-require_relative "../tables/glyf/compound_glyph_resolver"
-
 module Fontisan
   module Converters
     # Extracts all glyph outlines from a font for conversion purposes

data/lib/fontisan/converters/outline_optimizer.rb

@@ -1,10 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "../optimizers/pattern_analyzer"
-require_relative "../optimizers/subroutine_optimizer"
-require_relative "../optimizers/subroutine_builder"
-require_relative "../optimizers/charstring_rewriter"
-
 module Fontisan
   module Converters
     # Optimizes CFF CharStrings using subroutine extraction

data/lib/fontisan/converters/svg_generator.rb

@@ -1,9 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "conversion_strategy"
-require_relative "../outline_extractor"
-require_relative "../svg/font_generator"
-
 module Fontisan
   module Converters
     # SVG font generator conversion strategy

data/lib/fontisan/converters/table_copier.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "conversion_strategy"
-
 module Fontisan
   module Converters
     # Strategy for same-format font operations (copy/optimize)

data/lib/fontisan/converters/type1_converter.rb

@@ -1,14 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "../conversion_options"
-require_relative "../type1/charstring_converter"
-require_relative "../type1/cff_to_type1_converter"
-require_relative "../type1/font_dictionary"
-require_relative "../type1/charstrings"
-require_relative "../type1/seac_expander"
-require_relative "../type1_font"
-require_relative "cff_table_builder"
-
 module Fontisan
   module Converters
     # Converter for Adobe Type 1 fonts to/from SFNT formats.
@@ -1054,8 +1045,6 @@ module Fontisan
       # @param font [Type1Font] Source Type 1 font
       # @return [String] cmap table binary data
       def build_cmap_table(font)
-        require_relative "../type1/agl"
-
         data = (+"").b
 
         # Get encoding from Type1Font

data/lib/fontisan/converters/woff2_encoder.rb

@@ -1,11 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "conversion_strategy"
-require_relative "../woff2/header"
-require_relative "../woff2/directory"
-require_relative "../woff2/table_transformer"
-require_relative "../utilities/brotli_wrapper"
-require_relative "../utilities/checksum_calculator"
 # Validation temporarily disabled - will be reimplemented with new DSL framework in Week 3+
 # require_relative "../validation/woff2_validator"
 require "yaml"
@@ -50,31 +44,45 @@ module Fontisan
       # @return [Hash] Configuration settings
       attr_reader :config
 
-      # Initialize encoder with configuration
+      # Initialize encoder with configuration.
+      #
+      # The encoder is stateless per call; all conversion knobs come through
+      # the per-convert options hash. The config file supplies default values
+      # only for fields not expressed via the DSL.
       #
       # @param config_path [String, nil] Path to config file
       def initialize(config_path: nil)
         @config = load_configuration(config_path)
       end
 
-      # Convert font to WOFF2 format
+      option :brotli_quality, type: :integer, range: 0..11, default: 11,
+                              cli: "--brotli-quality=N",
+                              desc: "Brotli quality (0=fastest, 11=smallest)"
+      option :transform_tables, type: :boolean, default: false,
+                                cli: "--[no-]transform-tables",
+                                desc: "apply glyf/loca and hmtx transformations"
+
+      # Convert font to WOFF2 format.
       #
-      # Returns a hash with :woff2_binary key containing complete WOFF2 file.
-      # This is different from other converters that return table data.
+      # Returns a hash with `:woff2_binary` containing the complete WOFF2 file.
       #
       # @param font [TrueTypeFont, OpenTypeFont] Source font
-      # @param options [Hash] Conversion options
-      # @option options [Integer] :quality Brotli quality (0-11)
-      # @option options [Boolean] :transform_tables Apply table transformations
-      # @option options [Boolean] :validate Run validation after encoding
-      # @option options [Symbol] :validation_level Validation level (:strict, :standard, :lenient)
-      # @return [Hash] Hash with :woff2_binary and optional :validation_report keys
-      # @raise [Error] If encoding fails
+      # @param options [Hash{Symbol => Object}] Per-call options:
+      #   - `:brotli_quality` (0–11, default from config or 11)
+      #   - `:transform_tables` (bool, default false)
+      #   - `:quality` — legacy alias for `:brotli_quality` (backward compat)
+      # @return [Hash{Symbol => String}] `{ woff2_binary: <bytes> }`
+      # @raise [ArgumentError] if any option fails validation
+      # @raise [Fontisan::Error] if encoding fails
       def convert(font, options = {})
         validate(font, :woff2)
 
-        # Get Brotli quality from options or config
-        quality = options[:quality] || config["brotli"]["quality"]
+        resolved = normalize_legacy_quality(options)
+        self.class.validate_options!(strategy_options(resolved))
+
+        quality = resolved.fetch(:brotli_quality) do
+          config["brotli"]["quality"]
+        end
 
         # Detect font flavor
         flavor = detect_flavor(font)
@@ -84,7 +92,7 @@ module Fontisan
 
         # Transform tables (if enabled)
         transformer = Woff2::TableTransformer.new(font)
-        transform_enabled = options.fetch(:transform_tables, false)
+        transform_enabled = resolved.fetch(:transform_tables, false)
 
         # Build table directory entries
         entries = build_table_entries(table_data, transformer,
@@ -201,6 +209,27 @@ module Fontisan
       # Extend Woff2Font with in-memory loading
       Woff2Font.singleton_class.prepend(Woff2FontMemoryLoader)
 
+      # Normalize legacy `:quality` option to `:brotli_quality`.
+      # Internal callers and older specs use `:quality`; the public DSL uses
+      # `:brotli_quality`. Returns a new hash; does not mutate the input.
+      #
+      # @param options [Hash]
+      # @return [Hash]
+      def normalize_legacy_quality(options)
+        return options unless options.key?(:quality) && !options.key?(:brotli_quality)
+
+        options.merge(brotli_quality: options[:quality])
+      end
+
+      # Slice options to those declared by this strategy.
+      #
+      # @param options [Hash]
+      # @return [Hash]
+      def strategy_options(options)
+        names = self.class.supported_options.to_set(&:name)
+        options.select { |k, _| names.include?(k.to_sym) }
+      end
+
       # Load configuration from YAML file
       #
       # @param path [String, nil] Path to config file