fontisan 0.2.17 → 0.2.22

data/lib/fontisan/converters/conversion_strategy.rb

@@ -2,45 +2,171 @@
 
 module Fontisan
   module Converters
-    # Interface module for font format conversion strategies
+    # Interface module and declarative options DSL for conversion strategies
     #
     # [`ConversionStrategy`](lib/fontisan/converters/conversion_strategy.rb)
-    # defines the contract that all conversion strategy classes must implement.
-    # This follows the Strategy pattern to enable polymorphic handling of
-    # different conversion types (TTF→OTF, OTF→TTF, same-format copying).
+    # defines the contract that all conversion strategy classes must implement,
+    # plus a declarative DSL for declaring the options each strategy accepts.
     #
-    # Each strategy must implement:
-    # - convert(font, options) - Perform the actual conversion
-    # - supported_conversions - Return array of [source, target] format pairs
-    # - validate(font, target_format) - Validate conversion is possible
+    # ## Why a declarative options DSL
     #
-    # Strategies are selected by [`FormatConverter`](lib/fontisan/converters/format_converter.rb)
-    # based on source and target formats.
+    # Each format has its own spec-mandated knobs (WOFF: zlib level,
+    # WOFF2: Brotli quality, etc.). Letting each strategy declare its own
+    # options keeps the schema with the code that consumes it (encapsulation),
+    # and makes adding a new format a pure additive change (OCP): write a new
+    # strategy class, declare its options, done — no edits to central option
+    # lists, the CLI option parser, or ConversionOptions.
     #
-    # @example Implementing a strategy
-    #   class MyStrategy
-    #     include Fontisan::Converters::ConversionStrategy
+    # The strategy is also the sole validator of its own options. The
+    # runtime check at `FormatConverter#convert` calls
+    # `strategy.class.validate_options!` to enforce the format ↔ option
+    # mapping (e.g., rejecting `--zlib-level` on a WOFF2 conversion). This
+    # is the MECE guarantee: every option belongs to exactly one strategy,
+    # and a strategy rejects anything it did not declare.
     #
-    #     def convert(font, options = {})
-    #       # Perform conversion
-    #       tables = {...}
-    #       tables
-    #     end
+    # @example Declaring options
+    #   class WoffWriter
+    #     include ConversionStrategy
     #
-    #     def supported_conversions
-    #       [[:ttf, :otf], [:otf, :ttf]]
-    #     end
+    #     option :zlib_level, type: :integer, range: 0..9, default: 6,
+    #            cli: "--zlib-level", desc: "zlib compression level"
+    #     option :uncompressed, type: :boolean, default: false,
+    #            cli: "--uncompressed", desc: "store tables uncompressed"
     #
-    #     def validate(font, target_format)
-    #       # Validate font can be converted
-    #       raise Error unless valid
+    #     def convert(font, options = {})
+    #       self.class.validate_options!(options)
+    #       # ...
     #     end
     #   end
     module ConversionStrategy
-      # Convert font to target format
+      # Declarative description of a single strategy option.
+      # `allowed_values` is spelled out (not `values`) to avoid shadowing
+      # Struct#values.
+      Option = Struct.new(:name, :type, :default, :cli, :desc, :range,
+                          :allowed_values, keyword_init: true)
+
+      # Class methods mixed into including classes via `included`.
+      module ClassMethods
+        # Declare an option this strategy accepts.
+        #
+        # @param name [Symbol] Option name (the hash key used in `convert`)
+        # @param type [Symbol] One of :integer, :boolean, :string
+        # @param default [Object] Default value when the caller omits the option
+        # @param cli [String] CLI flag shape (for help text generation)
+        # @param desc [String] Human-readable description
+        # @param range [Range, nil] For :integer; valid range
+        # @param values [Array, nil] For :string; allowed values
+        # @return [void]
+        def option(name, type:, default:, cli:, desc:, range: nil, values: nil)
+          declared_options << Option.new(
+            name: name, type: type, default: default, cli: cli, desc: desc,
+            range: range, allowed_values: values
+          )
+        end
+
+        # All options declared by this class.
+        #
+        # @return [Array<Option>]
+        def declared_options
+          @declared_options ||= []
+        end
+
+        # Public accessor: the full list of options for this strategy.
+        alias supported_options declared_options
+
+        # Find the option schema for a given key (symbol or string).
+        #
+        # @param name [Symbol, String]
+        # @return [Option, nil]
+        def option_for(name)
+          supported_options.find { |o| o.name == name.to_sym }
+        end
+
+        # Default values for every declared option.
+        #
+        # @return [Hash{Symbol => Object}]
+        def default_options
+          supported_options.to_h { |o| [o.name, o.default] }
+        end
+
+        # Validate a user-provided options hash against this strategy's schema.
+        #
+        # Raises ArgumentError for any unknown key, wrong type, or
+        # out-of-range value. Called by FormatConverter after strategy
+        # selection, so cross-format misuse (e.g., `--zlib-level` on a
+        # WOFF2 conversion) is caught here.
+        #
+        # @param user_options [Hash{Symbol, String => Object}]
+        # @return [void]
+        # @raise [ArgumentError] if any key is unknown or any value is invalid
+        def validate_options!(user_options)
+          user_options.each_key do |key|
+            opt = option_for(key)
+            next if opt
+
+            names = supported_options.map(&:name)
+            list = names.empty? ? "(none)" : names.join(", ")
+            raise ArgumentError,
+                  "Unknown option #{key.inspect} for #{name}. " \
+                  "Supported: #{list}"
+          end
+
+          user_options.each do |key, value|
+            opt = option_for(key)
+            validate_option_value!(opt, value) unless value.nil?
+          end
+        end
+
+        private
+
+        # Type-check a single value against its declared schema.
+        #
+        # @param opt [Option]
+        # @param value [Object]
+        # @return [void]
+        # @raise [ArgumentError] if value fails type or range/values check
+        def validate_option_value!(opt, value)
+          case opt.type
+          when :integer
+            unless value.is_a?(Integer)
+              raise ArgumentError,
+                    "#{opt.name} must be an Integer, got #{value.inspect} " \
+                    "(#{value.class})"
+            end
+            return unless opt.range && !opt.range.cover?(value)
+
+            raise ArgumentError,
+                  "#{opt.name} must be in #{opt.range}, got #{value}"
+          when :boolean
+            return if [true, false].include?(value)
+
+            raise ArgumentError,
+                  "#{opt.name} must be true or false, got #{value.inspect}"
+          when :string
+            unless value.is_a?(String)
+              raise ArgumentError,
+                    "#{opt.name} must be a String, got #{value.class}"
+            end
+            return unless opt.allowed_values && !opt.allowed_values.include?(value)
+
+            raise ArgumentError,
+                  "#{opt.name} must be one of #{opt.allowed_values.join(', ')}, " \
+                  "got #{value.inspect}"
+          else
+            raise "Unknown option type #{opt.type.inspect} on #{opt.name}"
+          end
+        end
+      end
+
+      # Mix ClassMethods into any class that includes this module.
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # Convert font to target format.
       #
-      # This method must return a hash of table tags to binary data,
-      # which will be assembled into a complete font by FontWriter.
+      # Strategies must implement this. Subclasses should call
+      # `self.class.validate_options!(options)` first to enforce their schema.
       #
       # @param font [TrueTypeFont, OpenTypeFont] Source font
       # @param options [Hash] Conversion options
@@ -51,30 +177,19 @@ module Fontisan
               "#{self.class.name} must implement convert(font, options)"
       end
 
-      # Get list of supported conversions
-      #
-      # Returns an array of [source_format, target_format] pairs that
-      # this strategy can handle.
+      # Get list of supported conversions.
       #
-      # @return [Array<Array<Symbol>>] Supported conversion pairs
+      # @return [Array<Array<Symbol>>] Supported [source, target] pairs
       # @raise [NotImplementedError] If not implemented by strategy
-      #
-      # @example
-      #   strategy.supported_conversions
-      #   # => [[:ttf, :otf], [:otf, :ttf]]
       def supported_conversions
         raise NotImplementedError,
               "#{self.class.name} must implement supported_conversions"
       end
 
-      # Validate that conversion is possible
-      #
-      # Checks if the given font can be converted to the target format.
-      # Should raise an error with a clear message if conversion is not
-      # possible.
+      # Validate that conversion is possible.
       #
       # @param font [TrueTypeFont, OpenTypeFont] Font to validate
-      # @param target_format [Symbol] Target format (:ttf, :otf, etc.)
+      # @param target_format [Symbol] Target format
       # @return [Boolean] True if valid
       # @raise [Error] If conversion is not possible
       # @raise [NotImplementedError] If not implemented by strategy
@@ -83,11 +198,11 @@ module Fontisan
               "#{self.class.name} must implement validate(font, target_format)"
       end
 
-      # Check if strategy supports a conversion
+      # Check if strategy supports a given conversion.
       #
-      # @param source_format [Symbol] Source format
-      # @param target_format [Symbol] Target format
-      # @return [Boolean] True if supported
+      # @param source_format [Symbol]
+      # @param target_format [Symbol]
+      # @return [Boolean]
       def supports?(source_format, target_format)
         supported_conversions.include?([source_format, target_format])
       end

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