puppet-retrospec 0.12.2 → 1.0.0

data/vendor/gems/puppet-4.5.2/lib/puppet/pops/utils.rb

@@ -0,0 +1,143 @@
+# Provides utility methods
+module Puppet::Pops
+module Utils
+  # Can the given o be converted to numeric? (or is numeric already)
+  # Accepts a leading '::'
+  # Returns a boolean if the value is numeric
+  # If testing if value can be converted it is more efficient to call {#to_n} or {#to_n_with_radix} directly
+  # and check if value is nil.
+  def self.is_numeric?(o)
+    case o
+    when Numeric
+      true
+    else
+      !!Patterns::NUMERIC.match(relativize_name(o.to_s))
+    end
+  end
+
+  # Convert a match from Patterns::NUMERIC to floating point value if
+  # possible
+  def self.match_to_fp(match)
+    if match[5].to_s.length > 0
+      # Use default radix (default is decimal == 10) for floats
+      # Do not convert a value that is 0 raised to 10^somevalue to float - the value is always 0
+      # i.e. 0000.0e1, 0e1, 0.0000e1
+      if Integer(match[4]) == 0 && match[5] =~ /\A\.?0*[eE].*\z/
+        nil
+      else
+        fp_value = Float(match[2])
+        if fp_value != Float::INFINITY
+          match[1] == '-' ? -fp_value : fp_value
+        else
+          nil
+        end
+      end
+    end
+  end
+
+  # To Numeric with radix, or nil if not a number.
+  # If the value is already Numeric it is returned verbatim with a radix of 10.
+  # @param o [String, Number] a string containing a number in octal, hex, integer (decimal) or floating point form
+  #   with optional sign +/-
+  # @return [Array<Number, Integer>, nil] array with converted number and radix, or nil if not possible to convert
+  # @api public
+  #
+  def self.to_n_with_radix o
+    begin
+      case o
+      when String
+        match = Patterns::NUMERIC.match(relativize_name(o))
+        if !match
+          nil
+        elsif match[5].to_s.length > 0
+          fp_value = match_to_fp(match)
+          fp_value.nil? ? nil : [fp_value, 10]
+        else
+          # Set radix (default is decimal == 10)
+          radix = 10
+          if match[3].to_s.length > 0
+            radix = 16
+          elsif match[4].to_s.length > 1 && match[4][0,1] == '0'
+            radix = 8
+          end
+          # Ruby 1.8.7 does not have a second argument to Kernel method that creates an
+          # integer from a string, it relies on the prefix 0x, 0X, 0 (and unsupported in puppet binary 'b')
+          # We have the correct string here, match[2] is safe to parse without passing on radix
+          match[1] == '-' ? [-Integer(match[2]), radix] : [Integer(match[2]), radix]
+        end
+      when Numeric
+        # Impossible to calculate radix, assume decimal
+        [o, 10]
+      else
+        nil
+      end
+    rescue ArgumentError
+      nil
+    end
+  end
+
+  # To Numeric (or already numeric)
+  # Returns nil if value is not numeric, else an Integer or Float. A String may have an optional sign.
+  #
+  # A leading '::' is accepted (and ignored)
+  #
+  def self.to_n o
+    begin
+      case o
+      when String
+        match = Patterns::NUMERIC.match(relativize_name(o))
+        if !match
+          nil
+        elsif match[5].to_s.length > 0
+          match_to_fp(match)
+        else
+          match[1] == '-' ? -Integer(match[2]) : Integer(match[2])
+        end
+      when Numeric
+        o
+      else
+        nil
+      end
+    rescue ArgumentError
+      nil
+    end
+  end
+
+  # is the name absolute (i.e. starts with ::)
+  def self.is_absolute? name
+    name.start_with? "::"
+  end
+
+  def self.name_to_segments name
+    name.split("::")
+  end
+
+  def self.relativize_name name
+    is_absolute?(name) ? name[2..-1] : name
+  end
+
+  # Finds an existing adapter for o or for one of its containers, or nil, if none of the containers
+  # was adapted with the given adapter.
+  # This method can only be used with objects that respond to `:eContainer`.
+  # with true.
+  #
+  # @see #find_closest_positioned
+  #
+  def self.find_adapter(o, adapter)
+    return nil if o.nil? || (o.is_a?(Array) && o.empty?)
+    a = adapter.get(o)
+    return a if a
+    return find_adapter(o.eContainer, adapter)
+  end
+
+  # Finds the closest positioned Model::Positioned object, or object decorated with
+  # a SourcePosAdapter, and returns
+  # a SourcePosAdapter for the first found, or nil if not found.
+  #
+  def self.find_closest_positioned(o)
+    return nil if o.nil? || o.is_a?(Model::Program) || (o.is_a?(Array) && o.empty?)
+    return find_adapter(o, Adapters::SourcePosAdapter) unless o.is_a?(Model::Positioned)
+    o.offset.nil? ? find_closest_positioned(o.eContainer) : Adapters::SourcePosAdapter.adapt(o)
+  end
+end
+end

data/vendor/gems/puppet-4.5.2/lib/puppet/pops/validation.rb

@@ -0,0 +1,462 @@
+module Puppet::Pops
+# A module with base functionality for validation of a model.
+#
+# * **Factory** - an abstract factory implementation that makes it easier to create a new validation factory.
+# * **SeverityProducer** - produces a severity (:error, :warning, :ignore) for a given Issue
+# * **DiagnosticProducer** - produces a Diagnostic which binds an Issue to an occurrence of that issue
+# * **Acceptor** - the receiver/sink/collector of computed diagnostics
+# * **DiagnosticFormatter** - produces human readable output for a Diagnostic
+#
+module Validation
+
+  # This class is an abstract base implementation of a _model validation factory_ that creates a validator instance
+  # and associates it with a fully configured DiagnosticProducer.
+  #
+  # A _validator_ is responsible for validating a model. There may be different versions of validation available
+  # for one and the same model; e.g. different semantics for different puppet versions, or different types of
+  # validation configuration depending on the context/type of validation that should be performed (static, vs. runtime, etc.).
+  #
+  # This class is abstract and must be subclassed. The subclass must implement the methods
+  # {#label_provider} and {#checker}. It is also expected that the sublcass will override
+  # the severity_producer and configure the issues that should be reported as errors (i.e. if they should be ignored, produce
+  # a warning, or a deprecation warning).
+  #
+  # @abstract Subclass must implement {#checker}, and {#label_provider}
+  # @api public
+  #
+  class Factory
+
+    # Produces a validator with the given acceptor as the recipient of produced diagnostics.
+    # The acceptor is where detected issues are received (and typically collected).
+    #
+    # @param acceptor [Acceptor] the acceptor is the receiver of all detected issues
+    # @return [#validate] a validator responding to `validate(model)`
+    #
+    # @api public
+    #
+    def validator(acceptor)
+      checker(diagnostic_producer(acceptor))
+    end
+
+    # Produces the diagnostics producer to use given an acceptor of issues.
+    #
+    # @param acceptor [Acceptor] the acceptor is the receiver of all detected issues
+    # @return [DiagnosticProducer] a detector of issues
+    #
+    # @api public
+    #
+    def diagnostic_producer(acceptor)
+      DiagnosticProducer.new(acceptor, severity_producer(), label_provider())
+    end
+
+    # Produces the SeverityProducer to use
+    # Subclasses should implement and add specific overrides
+    #
+    # @return [SeverityProducer] a severity producer producing error, warning or ignore per issue
+    #
+    # @api public
+    #
+    def severity_producer
+      SeverityProducer.new
+    end
+
+    # Produces the checker to use.
+    #
+    # @abstract
+    #
+    # @api public
+    #
+    def checker(diagnostic_producer)
+      raise NoMethodError, "checker"
+    end
+
+    # Produces the label provider to use.
+    #
+    # @abstract
+    #
+    # @api public
+    #
+    def label_provider
+      raise NoMethodError, "label_provider"
+    end
+  end
+
+  # Decides on the severity of a given issue.
+  # The produced severity is one of `:error`, `:warning`, or `:ignore`.
+  # By default, a severity of `:error` is produced for all issues. To configure the severity
+  # of an issue call `#severity=(issue, level)`.
+  #
+  # @return [Symbol] a symbol representing the severity `:error`, `:warning`, or `:ignore`
+  #
+  # @api public
+  #
+  class SeverityProducer
+    @@severity_hash = {:ignore => true, :warning => true, :error => true, :deprecation => true }
+
+    # Creates a new instance where all issues are diagnosed as :error unless overridden.
+    # @param [Symbol] specifies default severity if :error is not wanted as the default
+    # @api public
+    #
+    def initialize(default_severity = :error)
+      # If diagnose is not set, the default is returned by the block
+      @severities = Hash.new default_severity
+    end
+
+    # Returns the severity of the given issue.
+    # @return [Symbol] severity level :error, :warning, or :ignore
+    # @api public
+    #
+    def severity(issue)
+      assert_issue(issue)
+      @severities[issue]
+    end
+
+    # @see {#severity}
+    # @api public
+    #
+    def [] issue
+      severity issue
+    end
+
+    # Override a default severity with the given severity level.
+    #
+    # @param issue [Issues::Issue] the issue for which to set severity
+    # @param level [Symbol] the severity level (:error, :warning, or :ignore).
+    # @api public
+    #
+    def []=(issue, level)
+      raise Puppet::DevError.new("Attempt to set validation severity for something that is not an Issue. (Got #{issue.class})") unless issue.is_a? Issues::Issue
+      raise Puppet::DevError.new("Illegal severity level: #{level} for '#{issue.issue_code}'") unless @@severity_hash[level]
+      raise Puppet::DevError.new("Attempt to demote the hard issue '#{issue.issue_code}' to #{level}") unless issue.demotable? || level == :error
+      @severities[issue] = level
+    end
+
+    # Returns `true` if the issue should be reported or not.
+    # @return [Boolean] this implementation returns true for errors and warnings
+    #
+    # @api public
+    #
+    def should_report? issue
+      diagnose = @severities[issue]
+      diagnose == :error || diagnose == :warning || diagnose == :deprecation
+    end
+
+    # Checks if the given issue is valid.
+    # @api private
+    #
+    def assert_issue issue
+      raise Puppet::DevError.new("Attempt to get validation severity for something that is not an Issue. (Got #{issue.class})") unless issue.is_a? Issues::Issue
+    end
+
+    # Checks if the given severity level is valid.
+    # @api private
+    #
+    def assert_severity level
+      raise Puppet::DevError.new("Illegal severity level: #{option}") unless @@severity_hash[level]
+    end
+  end
+
+  # A producer of diagnostics.
+  # An producer of diagnostics is given each issue occurrence as they are found by a diagnostician/validator. It then produces
+  # a Diagnostic, which it passes on to a configured Acceptor.
+  #
+  # This class exists to aid a diagnostician/validator which will typically first check if a particular issue
+  # will be accepted at all (before checking for an occurrence of the issue; i.e. to perform check avoidance for expensive checks).
+  # A validator passes an instance of Issue, the semantic object (the "culprit"), a hash with arguments, and an optional
+  # exception. The semantic object is used to determine the location of the occurrence of the issue (file/line), and it
+  # sets keys in the given argument hash that may be used in the formatting of the issue message.
+  #
+  class DiagnosticProducer
+
+    # A producer of severity for a given issue
+    # @return [SeverityProducer]
+    #
+    attr_reader :severity_producer
+
+    # A producer of labels for objects involved in the issue
+    # @return [LabelProvider]
+    #
+    attr_reader :label_provider
+    # Initializes this producer.
+    #
+    # @param acceptor [Acceptor] a sink/collector of diagnostic results
+    # @param severity_producer [SeverityProducer] the severity producer to use to determine severity of a given issue
+    # @param label_provider [LabelProvider] a provider of model element type to human readable label
+    #
+    def initialize(acceptor, severity_producer, label_provider)
+      @acceptor           = acceptor
+      @severity_producer  = severity_producer
+      @label_provider     = label_provider
+    end
+
+    def accept(issue, semantic, arguments={}, except=nil)
+      return unless will_accept? issue
+
+      # Set label provider unless caller provided a special label provider
+      arguments[:label]    ||= @label_provider
+      arguments[:semantic] ||= semantic
+
+      # A detail message is always provided, but is blank by default.
+      # TODO: this support is questionable, it requires knowledge that :detail is special
+      arguments[:detail] ||= ''
+
+      if semantic.is_a?(Puppet::Parser::Resource)
+        source_pos = semantic
+        file = semantic.file
+      else
+        source_pos = Utils.find_closest_positioned(semantic)
+        file = source_pos ? source_pos.locator.file : nil
+      end
+
+      severity = @severity_producer.severity(issue)
+      @acceptor.accept(Diagnostic.new(severity, issue, file, source_pos, arguments, except))
+    end
+
+    def will_accept? issue
+      @severity_producer.should_report? issue
+    end
+  end
+
+  class Diagnostic
+    attr_reader :severity
+    attr_reader :issue
+    attr_reader :arguments
+    attr_reader :exception
+    attr_reader :file
+    attr_reader :source_pos
+    def initialize severity, issue, file, source_pos, arguments={}, exception=nil
+      @severity = severity
+      @issue = issue
+      @file = file
+      @source_pos = source_pos
+      @arguments = arguments
+      # TODO: Currently unused, the intention is to provide more information (stack backtrace, etc.) when
+      # debugging or similar - this to catch internal problems reported as higher level issues.
+      @exception = exception
+    end
+
+    # Two diagnostics are considered equal if the have the same issue, location and severity
+    # (arguments and exception are ignored)
+    #
+    def ==(o)
+      self.class            == o.class             &&
+        same_position?(o)                          &&
+        issue.issue_code    == o.issue.issue_code  &&
+        file                == o.file              &&
+        severity            == o.severity
+    end
+    alias eql? ==
+
+    # Position is equal if the diagnostic is not located or if referring to the same offset
+    def same_position?(o)
+      source_pos.nil? && o.source_pos.nil? || source_pos.offset == o.source_pos.offset
+    end
+    private :same_position?
+
+    def hash
+      @hash ||= [file, source_pos.offset, issue.issue_code, severity].hash
+    end
+  end
+
+  # Formats a diagnostic for output.
+  # Produces a diagnostic output typical for a compiler (suitable for interpretation by tools)
+  # The format is:
+  # `file:line:pos: Message`, where pos, line and file are included if available.
+  #
+  class DiagnosticFormatter
+    def format diagnostic
+      "#{loc(diagnostic)} #{format_severity(diagnostic)}#{format_message(diagnostic)}"
+    end
+
+    def format_message diagnostic
+      diagnostic.issue.format(diagnostic.arguments)
+    end
+
+    # This produces "Deprecation notice: " prefix if the diagnostic has :deprecation severity, otherwise "".
+    # The idea is that all other diagnostics are emitted with the methods Puppet.err (or an exception), and
+    # Puppet.warning.
+    # @note Note that it is not a good idea to use Puppet.deprecation_warning as it is for internal deprecation.
+    #
+    def format_severity diagnostic
+      diagnostic.severity == :deprecation ? "Deprecation notice: " : ""
+    end
+
+    def format_location diagnostic
+      file = diagnostic.file
+      file = (file.is_a?(String) && file.empty?) ? nil : file
+      line = pos = nil
+      if diagnostic.source_pos
+        line = diagnostic.source_pos.line
+        pos = diagnostic.source_pos.pos
+      end
+      if file && line && pos
+        "#{file}:#{line}:#{pos}:"
+      elsif file && line
+        "#{file}:#{line}:"
+      elsif file
+        "#{file}:"
+      else
+        ""
+      end
+    end
+  end
+
+  # Produces a diagnostic output in the "puppet style", where the location is appended with an "at ..." if the
+  # location is known.
+  #
+  class DiagnosticFormatterPuppetStyle < DiagnosticFormatter
+    def format diagnostic
+      if (location = format_location diagnostic) != ""
+        "#{format_severity(diagnostic)}#{format_message(diagnostic)}#{location}"
+      else
+        format_message(diagnostic)
+      end
+    end
+
+    # The somewhat (machine) unusable format in current use by puppet.
+    # have to be used here for backwards compatibility.
+    def format_location diagnostic
+      file = diagnostic.file
+      file = (file.is_a?(String) && file.empty?) ? nil : file
+      line = pos = nil
+      if diagnostic.source_pos
+        line = diagnostic.source_pos.line
+        pos = diagnostic.source_pos.pos
+      end
+
+      if file && line && pos
+        " at #{file}:#{line}:#{pos}"
+      elsif file && line
+        " at #{file}:#{line}"
+      elsif line && pos
+        " at line #{line}:#{pos}"
+      elsif line
+        " at line #{line}"
+      elsif file
+        " in #{file}"
+      else
+        ""
+      end
+    end
+  end
+
+  # An acceptor of diagnostics.
+  # An acceptor of diagnostics is given each issue as they are found by a diagnostician/validator. An
+  # acceptor can collect all found issues, or decide to collect a few and then report, or give up as the first issue
+  # if found.
+  # This default implementation collects all diagnostics in the order they are produced, and can then
+  # answer questions about what was diagnosed.
+  #
+  class Acceptor
+
+    # All diagnostic in the order they were issued
+    attr_reader :diagnostics
+
+    # The number of :warning severity issues + number of :deprecation severity issues
+    attr_reader :warning_count
+
+    # The number of :error severity issues
+    attr_reader :error_count
+    # Initializes this diagnostics acceptor.
+    # By default, the acceptor is configured with a default severity producer.
+    # @param severity_producer [SeverityProducer] the severity producer to use to determine severity of an issue
+    #
+    # TODO add semantic_label_provider
+    #
+    def initialize()
+      @diagnostics = []
+      @error_count = 0
+      @warning_count = 0
+    end
+
+    # Returns true when errors have been diagnosed.
+    def errors?
+      @error_count > 0
+    end
+
+    # Returns true when warnings have been diagnosed.
+    def warnings?
+      @warning_count > 0
+    end
+
+    # Returns true when errors and/or warnings have been diagnosed.
+    def errors_or_warnings?
+      errors? || warnings?
+    end
+
+    # Returns the diagnosed errors in the order thwy were reported.
+    def errors
+      @diagnostics.select {|d| d.severity == :error }
+    end
+
+    # Returns the diagnosed warnings in the order thwy were reported.
+    # (This includes :warning and :deprecation severity)
+    def warnings
+      @diagnostics.select {|d| d.severity == :warning || d.severity == :deprecation }
+    end
+
+    def errors_and_warnings
+      @diagnostics.select {|d| d.severity != :ignore }
+    end
+
+    # Returns the ignored diagnostics in the order thwy were reported (if reported at all)
+    def ignored
+      @diagnostics.select {|d| d.severity == :ignore }
+    end
+
+    # Add a diagnostic, or all diagnostics from another acceptor to the set of diagnostics
+    # @param diagnostic [Diagnostic, Acceptor] diagnostic(s) that should be accepted
+    def accept(diagnostic)
+      if diagnostic.is_a?(Acceptor)
+        diagnostic.diagnostics.each {|d| self.send(d.severity, d)}
+      else
+        self.send(diagnostic.severity, diagnostic)
+      end
+    end
+
+    # Prunes the contain diagnostics by removing those for which the given block returns true.
+    # The internal statistics is updated as a consequence of removing.
+    # @return [Array<Diagnostic, nil] the removed set of diagnostics or nil if nothing was removed
+    #
+    def prune(&block)
+      removed = []
+      @diagnostics.delete_if do |d|
+        if should_remove = yield(d)
+          removed << d
+        end
+        should_remove
+      end
+      removed.each do |d|
+        case d.severity
+        when :error
+          @error_count -= 1
+        when :warning
+          @warning_count -= 1
+        # there is not ignore_count
+        end
+      end
+      removed.empty? ? nil : removed
+    end
+
+    private
+
+    def ignore diagnostic
+      @diagnostics << diagnostic
+    end
+
+    def error diagnostic
+      @diagnostics << diagnostic
+      @error_count += 1
+    end
+
+    def warning diagnostic
+      @diagnostics << diagnostic
+      @warning_count += 1
+    end
+
+    def deprecation diagnostic
+      warning diagnostic
+    end
+  end
+end
+end