aspera-cli 4.14.0 → 4.16.0

data/lib/aspera/cli/formatter.rb

@@ -1,95 +1,193 @@
 # frozen_string_literal: true
 
+# cspell:ignore jsonpp
 require 'aspera/secret_hider'
+require 'aspera/environment'
+require 'aspera/log'
+require 'aspera/assert'
 require 'terminal-table'
 require 'yaml'
 require 'pp'
 
 module Aspera
   module Cli
+    CONF_OVERVIEW_KEYS = %w[preset parameter value].freeze
+    # This class is used to transform a complex structure into a simple hash
+    class Flattener
+      def initialize
+        @result = nil
+      end
+
+      # General method
+      def flatten(something)
+        assert_type(something, Hash)
+        @result = {}
+        flatten_any(something, '')
+        return @result
+      end
+
+      # Special method for configuration overview
+      def config_over(something)
+        @result = []
+        something.each do |config, preset|
+          preset.each do |parameter, value|
+            @result.push(CONF_OVERVIEW_KEYS.zip([config, parameter, value]).to_h)
+          end
+        end
+        return @result
+      end
+
+      private
+
+      # Recursive function to flatten any type
+      # @param something [Object] to be flattened
+      # @param name [String] name of englobing key
+      def flatten_any(something, name)
+        if something.is_a?(Hash)
+          flattened_hash(something, name)
+        elsif something.is_a?(Array)
+          flatten_array(something, name)
+        elsif something.is_a?(String) && something.empty?
+          @result[name] = Formatter.special('empty string')
+        elsif something.nil?
+          @result[name] = Formatter.special('null')
+        # elsif something.eql?(true) || something.eql?(false)
+        #  @result[name] = something
+        else
+          @result[name] = something
+        end
+      end
+
+      # Recursive function to flatten an array
+      # @param array [Array] to be flattened
+      # @param name [String] name of englobing key
+      def flatten_array(array, name)
+        if array.empty?
+          @result[name] = Formatter.special('empty list')
+        elsif array.all?(String)
+          @result[name] = array.join("\n")
+        elsif array.all?{|i| i.is_a?(Hash) && i.keys.eql?(%w[name])}
+          @result[name] = array.map(&:values).join(', ')
+        elsif array.all?{|i| i.is_a?(Hash) && i.keys.sort.eql?(%w[name value])}
+          flattened_hash(array.each_with_object({}){|i, h|h[i['name']] = i['value']}, name)
+        else
+          array.each_with_index { |item, index| flatten_any(item, "#{name}.#{index}")}
+        end
+        nil
+      end
+
+      # Recursive function to flatten a Hash
+      # @param hash [Hash] to be flattened
+      # @param name [String] name of englobing key
+      def flattened_hash(hash, name)
+        prefix = name.empty? ? '' : "#{name}."
+        hash.each do |k, v|
+          flatten_any(v, "#{prefix}#{k}")
+        end
+      end
+    end # class
+
     # Take care of output
     class Formatter
-      FIELDS_ALL = 'ALL'
-      FIELDS_DEFAULT = 'DEF'
+      FIELDS_LESS = '-'
       CSV_RECORD_SEPARATOR = "\n"
       CSV_FIELD_SEPARATOR = ','
       # supported output formats
       DISPLAY_FORMATS = %i[text nagios ruby json jsonpp yaml table csv].freeze
       # user output levels
       DISPLAY_LEVELS = %i[info data error].freeze
-      CONF_OVERVIEW_KEYS = %w[config parameter value].freeze
-      KEY_VALUE = %w[key value].freeze
+      RESULT_PARAMS = %i[type data total fields name].freeze
 
-      private_constant :FIELDS_ALL, :FIELDS_DEFAULT, :DISPLAY_FORMATS, :DISPLAY_LEVELS, :CSV_RECORD_SEPARATOR, :CSV_FIELD_SEPARATOR,
-        :CONF_OVERVIEW_KEYS, :KEY_VALUE
+      private_constant :DISPLAY_FORMATS, :DISPLAY_LEVELS, :CSV_RECORD_SEPARATOR, :CSV_FIELD_SEPARATOR
+      # prefix to display error messages in user messages (terminal)
+      ERROR_FLASH = 'ERROR:'.bg_red.gray.blink.freeze
+      WARNING_FLASH = 'WARNING:'.bg_brown.black.blink.freeze
+      HINT_FLASH = 'HINT:'.bg_green.gray.blink.freeze
 
       class << self
-        # special for Aspera on Cloud display node
-        # {"param" => [{"name"=>"foo","value"=>"bar"}]} will be expanded to {"param.foo" : "bar"}
-        def flatten_name_value_list(hash)
-          hash.keys.each do |k| # rubocop:disable Style/HashEachMethods
-            v = hash[k]
-            next unless v.is_a?(Array) && v.map(&:class).uniq.eql?([Hash]) && v.map(&:keys).flatten.sort.uniq.eql?(%w[name value])
-            v.each do |pair|
-              hash["#{k}.#{pair['name']}"] = pair['value']
+        # Highlight special values
+        def special(what, use_colors: $stdout.isatty)
+          result = "<#{what}>"
+          if use_colors
+            result = if %w[null empty].any?{|s|what.include?(s)}
+              result.dim
+            else
+              result.reverse_color
             end
-            hash.delete(k)
           end
+          return result
         end
 
-        def flatten_config_overview(hash_array_conf)
-          r = []
-          hash_array_conf.each do |config, preset|
-            preset.each do |parameter, value|
-              r.push(CONF_OVERVIEW_KEYS.zip([config, parameter, SecretHider.deep_remove_secret(value).to_s]).to_h)
-            end
-          end
-          return r
+        def all_but(list)
+          list = [list] unless list.is_a?(Array)
+          return list.map{|i|"#{FIELDS_LESS}#{i}"}.unshift(ExtendedValue::ALL)
         end
 
-        def simple_hash?(h)
-          !(h.values.any?{|v|[Hash, Array].any?{|c|v.is_a?(c)}})
+        def tick(yes)
+          result =
+            if Environment.use_unicode?
+              if yes
+                "\u2713"
+              else
+                "\u2717"
+              end
+            elsif yes
+              'Y'
+            else
+              ' '
+            end
+          return result.green if yes
+          return result.red
         end
 
-        # recursive function to modify a hash
-        # @param source [Hash] to be modified
-        # @param expand_last [TrueClass,FalseClass] true if last level is not
-        # @param result [Hash] new hash flattened
-        # @param prefix [String] true if last level is not
-        def flattened_object(source, result: {}, prefix: '', expand_last: false)
-          Log.log.debug{"(#{expand_last})[#{simple_hash?(source)}] -#{source.values}- \n-#{source}-"}
-          source.each do |k, v|
-            if v.is_a?(Hash) && !(expand_last && simple_hash?(v))
-              flattened_object(v, result: result, prefix: prefix + k.to_s + '.', expand_last: expand_last)
-            else
-              result[prefix + k.to_s] = v
+        def auto_type(data)
+          result = {type: :other_struct, data: data}
+          result[:type] = :single_object if result[:data].is_a?(Hash)
+          if result[:data].is_a?(Array)
+            if result[:data].all?(Hash)
+              result[:type] = :object_list
             end
           end
           return result
         end
+      end # self
+
+      # initialize the formatter
+      def initialize
+        @options = {}
       end
 
-      attr_accessor :option_flat_hash, :option_transpose_single, :option_format, :option_display, :option_fields, :option_table_style,
-        :option_select, :option_show_secrets
+      def option_handler(option_symbol, operation, value=nil)
+        assert_values(operation, %i[set get])
+        case operation
+        when :set
+          @options[option_symbol] = value
+          if option_symbol.eql?(:output)
+            $stdout = if value.eql?('-')
+              STDOUT # rubocop:disable Style/GlobalStdStream
+            else
+              File.open(value, 'w')
+            end
+          end
+        when :get then return @options[option_symbol]
+        else error_unreachable_line
+        end
+        nil
+      end
 
-      # adds options but does not parse
-      def initialize(opt_mgr)
-        @option_format = :table
-        @option_display = :info
-        @option_fields = FIELDS_DEFAULT
-        @option_select = nil
-        @option_table_style = ':.:'
-        @option_flat_hash = true
-        @option_transpose_single = true
-        @option_show_secrets = false
-        opt_mgr.declare(:format, 'Output format', values: DISPLAY_FORMATS, handler: {o: self, m: :option_format})
-        opt_mgr.declare(:display, 'Output only some information', values: DISPLAY_LEVELS, handler: {o: self, m: :option_display})
-        opt_mgr.declare(:fields, "Comma separated list of fields, or #{FIELDS_ALL}, or #{FIELDS_DEFAULT}", handler: {o: self, m: :option_fields})
-        opt_mgr.declare(:select, 'Select only some items in lists: column, value', types: Hash, handler: {o: self, m: :option_select})
-        opt_mgr.declare(:table_style, 'Table display style', handler: {o: self, m: :option_table_style})
-        opt_mgr.declare(:flat_hash, 'Display deep values as additional keys', values: :bool, handler: {o: self, m: :option_flat_hash})
-        opt_mgr.declare(:transpose_single, 'Single object fields output vertically', values: :bool, handler: {o: self, m: :option_transpose_single})
-        opt_mgr.declare(:show_secrets, 'Show secrets on command output', values: :bool, handler: {o: self, m: :option_show_secrets})
+      def declare_options(options)
+        options.declare(:format, 'Output format', values: DISPLAY_FORMATS, handler: {o: self, m: :option_handler}, default: :table)
+        options.declare(:output, 'Destination for results', types: String, handler: {o: self, m: :option_handler})
+        options.declare(:display, 'Output only some information', values: DISPLAY_LEVELS, handler: {o: self, m: :option_handler}, default: :info)
+        options.declare(
+          :fields, "Comma separated list of: fields, or #{ExtendedValue::ALL}, or #{ExtendedValue::DEF}", handler: {o: self, m: :option_handler},
+          types: [String, Array, Regexp, Proc],
+          default: ExtendedValue::DEF)
+        options.declare(:select, 'Select only some items in lists: column, value', types: [Hash, Proc], handler: {o: self, m: :option_handler})
+        options.declare(:table_style, 'Table display style', handler: {o: self, m: :option_handler}, default: ':.:')
+        options.declare(:flat_hash, 'Display deep values as additional keys', values: :bool, handler: {o: self, m: :option_handler}, default: true)
+        options.declare(:transpose_single, 'Single object fields output vertically', values: :bool, handler: {o: self, m: :option_handler}, default: true)
+        options.declare(:show_secrets, 'Show secrets on command output', values: :bool, handler: {o: self, m: :option_handler}, default: false)
       end
 
       # main output method
@@ -98,10 +196,10 @@ module Aspera
       # error: always displayed on stderr
       def display_message(message_level, message)
         case message_level
-        when :data then $stdout.puts(message) unless @option_display.eql?(:error)
-        when :info then $stdout.puts(message) if @option_display.eql?(:info)
+        when :data then $stdout.puts(message) unless @options[:display].eql?(:error)
+        when :info then $stdout.puts(message) if @options[:display].eql?(:info)
         when :error then $stderr.puts(message)
-        else raise "wrong message_level:#{message_level}"
+        else error_unexpected_value(message_level)
         end
       end
 
@@ -110,155 +208,159 @@ module Aspera
       end
 
       def display_item_count(number, total)
+        number = number.to_i
+        total = total.to_i
+        return if total.eql?(0) && number.eql?(0)
         count_msg = "Items: #{number}/#{total}"
-        count_msg = count_msg.bg_red unless number.to_i.eql?(total.to_i)
+        count_msg = count_msg.bg_red unless number.eql?(total)
         display_status(count_msg)
       end
 
-      def result_default_fields(results, table_rows_hash_val)
-        unless results[:fields].nil?
-          raise "internal error: [fields] must be Array, not #{results[:fields].class}" unless results[:fields].is_a?(Array)
-          if results[:fields].first.eql?(:all_but) && !table_rows_hash_val.empty?
-            filter = results[:fields][1..-1]
-            return table_rows_hash_val.first.keys.reject{|i|filter.include?(i)}
+      def all_fields(data)
+        data.each_with_object({}){|v, m|v.each_key{|c|m[c] = true}}.keys
+      end
+
+      # this method computes the list of fields to display
+      # data: array of hash
+      # default: list of fields to display by default (may contain special values)
+      def compute_fields(data, default)
+        Log.log.debug{"compute_fields: data:#{data.class} default:#{default.class} #{default}"}
+        request =
+          case @options[:fields]
+          when NilClass then [ExtendedValue::DEF]
+          when String then @options[:fields].split(',')
+          when Array then @options[:fields]
+          when Regexp then return all_fields(data).select{|i|i.match(@options[:fields])}
+          when Proc then return all_fields(data).select{|i|@options[:fields].call(i)}
+          else error_unexpected_value(@options[:fields])
+          end
+        result = []
+        until request.empty?
+          item = request.shift
+          removal = false
+          if item[0].eql?(FIELDS_LESS)
+            removal = true
+            item = item[1..-1]
+          end
+          case item
+          when ExtendedValue::ALL
+            # get the list of all column names used in all lines, not just first one, as all lines may have different columns
+            request.unshift(*all_fields(data))
+          when ExtendedValue::DEF
+            default = all_fields(data).select{|i|default.call(i)} if default.is_a?(Proc)
+            default = all_fields(data) if default.nil?
+            request.unshift(*default)
+          else
+            if removal
+              result = result.reject{|i|i.eql?(item)}
+            else
+              result.push(item)
+            end
           end
-          return results[:fields]
         end
-        return ['empty'] if table_rows_hash_val.empty?
-        return table_rows_hash_val.first.keys
+        return result
       end
 
-      def result_all_fields(_results, table_rows_hash_val)
-        raise 'internal error: must be array' unless table_rows_hash_val.is_a?(Array)
-        # get the list of all column names used in all lines, not just first one, as all lines may have different columns
-        return table_rows_hash_val.each_with_object({}){|v, m|v.each_key{|c|m[c] = true}; }.keys
+      # this method displays a table
+      # object_array: array of hash
+      # fields: list of column names
+      def display_table(object_array, fields)
+        assert(!fields.nil?){'missing fields parameter'}
+        case @options[:select]
+        when Proc
+          object_array.select!{|i|@options[:select].call(i)}
+        when Hash
+          @options[:select].each{|k, v|object_array.select!{|i|i[k].eql?(v)}}
+        end
+        if object_array.empty?
+          # no  display for csv
+          display_message(:info, Formatter.special('empty')) if @options[:format].eql?(:table)
+          return
+        end
+        if object_array.length == 1 && fields.length == 1
+          display_message(:data, object_array.first[fields.first])
+          return
+        end
+        # Special case if only one row (it could be object_list or single_object)
+        if @options[:transpose_single] && object_array.length == 1
+          new_columns = %i[key value]
+          single = object_array.first
+          object_array = fields.map { |i| new_columns.zip([i, single[i]]).to_h }
+          fields = new_columns
+        end
+        Log.log.debug{Log.dump(:object_array, object_array)}
+        # convert data to string, and keep only display fields
+        final_table_rows = object_array.map { |r| fields.map { |c| r[c].to_s } }
+        # here : fields : list of column names
+        case @options[:format]
+        when :table
+          style = @options[:table_style].chars
+          # display the table !
+          display_message(:data, Terminal::Table.new(
+            headings:  fields,
+            rows:      final_table_rows,
+            border_x:  style[0],
+            border_y:  style[1],
+            border_i:  style[2]))
+        when :csv
+          display_message(:data, final_table_rows.map{|t| t.join(CSV_FIELD_SEPARATOR)}.join(CSV_RECORD_SEPARATOR))
+        end
       end
 
       # this method displays the results, especially the table format
       def display_results(results)
-        raise "INTERNAL ERROR, result must be Hash (got: #{results.class}: #{results})" unless results.is_a?(Hash)
-        raise 'INTERNAL ERROR, result must have type' unless results.key?(:type)
-        raise 'INTERNAL ERROR, result must have data' unless results.key?(:data) || %i[empty nothing].include?(results[:type])
-        res_data = results[:data]
-        # for config overview, it is name and value
-        is_config_overview = res_data.is_a?(Array) && !res_data.empty? && res_data.first.is_a?(Hash) && res_data.first.keys.sort.eql?(CONF_OVERVIEW_KEYS)
-        SecretHider.deep_remove_secret(res_data, is_name_value: is_config_overview) unless @option_show_secrets || @option_display.eql?(:data)
-        # comma separated list in string format
-        user_asked_fields_list_str = @option_fields
-        case @option_format
+        assert_type(results, Hash)
+        assert((results.keys - RESULT_PARAMS).empty?){"result unsupported key: #{results.keys - RESULT_PARAMS}"}
+        assert(results.key?(:type)){"result must have type (#{results})"}
+        assert(results.key?(:data) || %i[empty nothing].include?(results[:type])){'result must have data'}
+        Log.log.debug{"display_results: #{results[:data].class} #{results[:type]}"}
+        display_item_count(results[:data].length, results[:total]) if results.key?(:total)
+        SecretHider.deep_remove_secret(results[:data]) unless @options[:show_secrets] || @options[:display].eql?(:data)
+        case @options[:format]
         when :text
-          display_message(:data, res_data.to_s)
+          display_message(:data, results[:data].to_s)
         when :nagios
-          Nagios.process(res_data)
+          Nagios.process(results[:data])
         when :ruby
-          display_message(:data, PP.pp(res_data, +''))
+          display_message(:data, PP.pp(results[:data], +''))
         when :json
-          display_message(:data, JSON.generate(res_data))
+          display_message(:data, JSON.generate(results[:data]))
         when :jsonpp
-          display_message(:data, JSON.pretty_generate(res_data))
+          display_message(:data, JSON.pretty_generate(results[:data]))
         when :yaml
-          display_message(:data, res_data.to_yaml)
+          display_message(:data, results[:data].to_yaml)
         when :table, :csv
-          if !@option_transpose_single && results[:type].eql?(:single_object)
-            results[:type] = :object_list
-            res_data = [res_data]
-          end
           case results[:type]
-          when :object_list # goes to table display
-            raise "internal error: unexpected type: #{res_data.class}, expecting Array" unless res_data.is_a?(Array)
+          when :config_over
+            display_table(Flattener.new.config_over(results[:data]), CONF_OVERVIEW_KEYS)
+          when :object_list, :single_object
+            obj_list = results[:data]
+            obj_list = [obj_list] if results[:type].eql?(:single_object)
+            assert_type(obj_list, Array)
+            assert(obj_list.all?(Hash)){"expecting Array of Hash: #{obj_list.inspect}"}
             # :object_list is an array of hash tables, where key=colum name
-            table_rows_hash_val = res_data
-            final_table_columns = nil
-            if @option_flat_hash
-              table_rows_hash_val.map!{|obj|self.class.flattened_object(obj, expand_last: results[:option_expand_last])}
-            end
-            final_table_columns =
-              case user_asked_fields_list_str
-              when FIELDS_DEFAULT then result_default_fields(results, table_rows_hash_val)
-              when FIELDS_ALL then     result_all_fields(results, table_rows_hash_val)
-              else
-                if user_asked_fields_list_str.start_with?('+')
-                  result_default_fields(results, table_rows_hash_val).push(*user_asked_fields_list_str.gsub(/^\+/, '').split(','))
-                elsif user_asked_fields_list_str.start_with?('-')
-                  result_default_fields(results, table_rows_hash_val).reject{|i| user_asked_fields_list_str.gsub(/^-/, '').split(',').include?(i)}
-                else
-                  user_asked_fields_list_str.split(',')
-                end
-              end
-          when :single_object # goes to table display
-            # :single_object is a simple hash table  (can be nested)
-            raise "internal error: expecting Hash: got #{res_data.class}: #{res_data}" unless res_data.is_a?(Hash)
-            final_table_columns = results[:columns] || KEY_VALUE
-            if @option_flat_hash
-              res_data = self.class.flattened_object(res_data, expand_last: results[:option_expand_last])
-              self.class.flatten_name_value_list(res_data)
-            end
-            asked_fields =
-              case user_asked_fields_list_str
-              when FIELDS_DEFAULT then results[:fields] || res_data.keys
-              when FIELDS_ALL then     res_data.keys
-              else user_asked_fields_list_str.split(',')
-              end
-            table_rows_hash_val = asked_fields.map { |i| { final_table_columns.first => i, final_table_columns.last => res_data[i] } }
-            # if only one row, and columns are key/value, then display the value only
-            if table_rows_hash_val.length == 1 && final_table_columns.eql?(KEY_VALUE)
-              display_message(:data, res_data.values.first)
-              return
-            end
-          when :value_list # goes to table display
+            obj_list = obj_list.map{|obj|Flattener.new.flatten(obj)} if @options[:flat_hash]
+            display_table(obj_list, compute_fields(obj_list, results[:fields]))
+          when :value_list
             # :value_list is a simple array of values, name of column provided in the :name
-            final_table_columns = [results[:name]]
-            table_rows_hash_val = res_data.map { |i| { results[:name] => i } }
+            display_table(results[:data].map { |i| { results[:name] => i } }, [results[:name]])
           when :empty # no table
-            display_message(:info, 'empty')
+            display_message(:info, Formatter.special('empty'))
             return
           when :nothing # no result expected
             Log.log.debug('no result expected')
-            return
           when :status # no table
             # :status displays a simple message
-            display_message(:info, res_data)
-            return
+            display_message(:info, results[:data])
           when :text # no table
             # :status displays a simple message
-            display_message(:data, res_data)
-            return
+            display_message(:data, results[:data])
           when :other_struct # no table
             # :other_struct is any other type of structure
-            display_message(:data, PP.pp(res_data, +''))
-            return
+            display_message(:data, PP.pp(results[:data], +''))
           else
             raise "unknown data type: #{results[:type]}"
           end
-          # here we expect: table_rows_hash_val and final_table_columns
-          raise 'no field specified' if final_table_columns.nil?
-          if table_rows_hash_val.empty?
-            display_message(:info, 'empty'.gray) if @option_format.eql?(:table)
-            return
-          end
-          # convert to string with special function. here table_rows_hash_val is an array of hash
-          table_rows_hash_val = results[:textify].call(table_rows_hash_val) if results.key?(:textify)
-          unless @option_select.nil? || (@option_select.respond_to?(:empty?) && @option_select.empty?)
-            raise CliBadArgument, "expecting hash for select, have #{@option_select.class}: #{@option_select}" unless @option_select.is_a?(Hash)
-            @option_select.each{|k, v|table_rows_hash_val.select!{|i|i[k].eql?(v)}}
-          end
-          # convert data to string, and keep only display fields
-          final_table_rows = table_rows_hash_val.map { |r| final_table_columns.map { |c| r[c].to_s } }
-          # here : final_table_columns : list of column names
-          # here: final_table_rows : array of list of value
-          case @option_format
-          when :table
-            style = @option_table_style.chars
-            # display the table !
-            display_message(:data, Terminal::Table.new(
-              headings:  final_table_columns,
-              rows:      final_table_rows,
-              border_x:  style[0],
-              border_y:  style[1],
-              border_i:  style[2]))
-          when :csv
-            display_message(:data, final_table_rows.map{|t| t.join(CSV_FIELD_SEPARATOR)}.join(CSV_RECORD_SEPARATOR))
-          end
         end
       end
     end

data/lib/aspera/cli/hints.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'aspera/fasp/error'
+require 'aspera/rest'
+require 'aspera/log'
+require 'aspera/assert'
+require 'net/ssh'
+require 'openssl'
+
+module Aspera
+  module Cli
+    # Provide hints on errors
+    class Hints
+      # Well know issues that users may get
+      ERROR_HINTS = [
+        {
+          exception:   Fasp::Error,
+          match:       'Remote host is not who we expected',
+          remediation: [
+            'For this specific error, refer to:',
+            "#{SRC_URL}#error-remote-host-is-not-who-we-expected",
+            'Add this to arguments:',
+            %q{--ts=@json:'{"sshfp":null}'"}
+          ]
+        },
+        {
+          exception:   Aspera::RestCallError,
+          match:       /Signature has expired/,
+          remediation: [
+            'There is too much time difference between your computer and the server',
+            'Check your local time: is time synchronization enabled?'
+          ]
+        },
+        {
+          exception:   OpenSSL::SSL::SSLError,
+          match:       /(does not match the server certificate|certificate verify failed)/,
+          remediation: [
+            'You can ignore SSL errors with option:',
+            '--insecure=yes'
+          ]
+        },
+        {
+          exception:   OpenSSL::PKey::RSAError,
+          match:       /Neither PUB key nor PRIV key/,
+          remediation: [
+            'option: private_key expects a key PEM value, not path to file',
+            'if you provide a path: prefix with @file:',
+            'e.g. --private-key=@file:/path/to/key.pem'
+          ]
+        }
+      ]
+
+      private_constant :ERROR_HINTS
+
+      class << self
+        def hint_for(error, formatter)
+          ERROR_HINTS.each do |hint|
+            next unless error.is_a?(hint[:exception])
+            message = error.message
+            matches = hint[:match]
+            matches = [matches] unless matches.is_a?(Array)
+            matches.each do |m|
+              assert_values(m.class, [String, Regexp])
+              case m
+              when String
+                next unless message.eql?(m)
+              when Regexp
+                next unless message.match?(m)
+              else error_unexpected_value(m)
+              end
+              remediation = hint[:remediation]
+              remediation = [remediation] unless remediation.is_a?(Array)
+              remediation.each{|r|formatter.display_message(:error, "#{Formatter::HINT_FLASH} #{r}")}
+              break
+            end
+          end
+        end
+      end
+    end
+  end
+end