puppet 6.0.10-universal-darwin → 6.1.0-universal-darwin

data/lib/puppet/pal/plan_signature.rb

@@ -0,0 +1,71 @@
+module Puppet
+module Pal
+  # A PlanSignature is returned from `plan_signature`. Its purpose is to answer questions about the plans's parameters
+  # and if it can be called with a hash of named parameters.
+  #
+  # @api public
+  #
+  class PlanSignature
+    def initialize(plan_function)
+      @plan_func = plan_function
+    end
+
+    # Returns true or false depending on if the given PlanSignature is callable with a set of named arguments or not
+    # In addition to returning the boolean outcome, if a block is given, it is called with a string of formatted
+    # error messages that describes the difference between what was given and what is expected. The error message may
+    # have multiple lines of text, and each line is indented one space.
+    #
+    # @example Checking if signature is acceptable
+    #
+    #   signature = pal.plan_signature('myplan')
+    #   signature.callable_with?({x => 10}) { |errors| raise ArgumentError("Ooops: given arguments does not match\n#{errors}") }
+    #
+    # @api public
+    #
+    def callable_with?(args_hash)
+      dispatcher = @plan_func.class.dispatcher.dispatchers[0]
+
+      param_scope = {}
+      # Assign all non-nil values, even those that represent non-existent parameters.
+      args_hash.each { |k, v| param_scope[k] = v unless v.nil? }
+      dispatcher.parameters.each do |p|
+        name = p.name
+        arg = args_hash[name]
+        if arg.nil?
+          # Arg either wasn't given, or it was undef
+          if p.value.nil?
+            # No default. Assign nil if the args_hash included it
+            param_scope[name] = nil if args_hash.include?(name)
+          else
+            # parameter does not have a default value, it will be assigned its default when being called
+            # we assume that the default value is of the correct type and therefore simply skip
+            # checking this
+            # param_scope[name] = param_scope.evaluate(name, p.value, closure_scope, @evaluator)
+          end
+        end
+      end
+
+      errors = Puppet::Pops::Types::TypeMismatchDescriber.singleton.describe_struct_signature(dispatcher.params_struct, param_scope).flatten
+      return true if errors.empty?
+      if block_given?
+        yield errors.map {|e| e.format }.join("\n")
+      end
+      false
+    end
+
+    # Returns a PStructType describing the parameters as a puppet Struct data type
+    # Note that a `to_s` on the returned structure will result in a human readable Struct datatype as a
+    # description of what a plan expects.
+    #
+    # @return [Puppet::Pops::Types::PStructType] a struct data type describing the parameters and their types
+    #
+    # @api public
+    #
+    def params_type
+      dispatcher = @plan_func.class.dispatcher.dispatchers[0]
+      dispatcher.params_struct
+    end
+  end
+
+end
+end

data/lib/puppet/pal/script_compiler.rb

@@ -0,0 +1,71 @@
+module Puppet
+module Pal
+
+  class ScriptCompiler < Compiler
+    # Returns the signature of the given plan name
+    # @param plan_name [String] the name of the plan to get the signature of
+    # @return [Puppet::Pal::PlanSignature, nil] returns a PlanSignature, or nil if plan is not found
+    #
+    def plan_signature(plan_name)
+      loader = internal_compiler.loaders.private_environment_loader
+      if func = loader.load(:plan, plan_name)
+        return PlanSignature.new(func)
+      end
+      # Could not find plan
+      nil
+    end
+
+    # Returns an array of TypedName objects for all plans, optionally filtered by a regular expression.
+    # The returned array has more information than just the leaf name - the typical thing is to just get
+    # the name as showing the following example.
+    #
+    # Errors that occur during plan discovery will either be logged as warnings or collected by the optional
+    # `error_collector` array. When provided, it will receive {Puppet::DataTypes::Error} instances describing
+    # each error in detail and no warnings will be logged.
+    #
+    # @example getting the names of all plans
+    #   compiler.list_plans.map {|tn| tn.name }
+    #
+    # @param filter_regex [Regexp] an optional regexp that filters based on name (matching names are included in the result)
+    # @param error_collector [Array<Puppet::DataTypes::Error>] an optional array that will receive errors during load
+    # @return [Array<Puppet::Pops::Loader::TypedName>] an array of typed names
+    #
+    def list_plans(filter_regex = nil, error_collector = nil)
+      list_loadable_kind(:plan, filter_regex, error_collector)
+    end
+
+    # Returns the signature callable of the given task (the arguments it accepts, and the data type it returns)
+    # @param task_name [String] the name of the task to get the signature of
+    # @return [Puppet::Pal::TaskSignature, nil] returns a TaskSignature, or nil if task is not found
+    #
+    def task_signature(task_name)
+      loader = internal_compiler.loaders.private_environment_loader
+      if task = loader.load(:task, task_name)
+        return TaskSignature.new(task)
+      end
+      # Could not find task
+      nil
+    end
+
+    # Returns an array of TypedName objects for all tasks, optionally filtered by a regular expression.
+    # The returned array has more information than just the leaf name - the typical thing is to just get
+    # the name as showing the following example.
+    #
+    # @example getting the names of all tasks
+    #   compiler.list_tasks.map {|tn| tn.name }
+    #
+    # Errors that occur during task discovery will either be logged as warnings or collected by the optional
+    # `error_collector` array. When provided, it will receive {Puppet::DataTypes::Error} instances describing
+    # each error in detail and no warnings will be logged.
+    #
+    # @param filter_regex [Regexp] an optional regexp that filters based on name (matching names are included in the result)
+    # @param error_collector [Array<Puppet::DataTypes::Error>] an optional array that will receive errors during load
+    # @return [Array<Puppet::Pops::Loader::TypedName>] an array of typed names
+    #
+    def list_tasks(filter_regex = nil, error_collector = nil)
+      list_loadable_kind(:task, filter_regex, error_collector)
+    end
+  end
+
+end
+end

data/lib/puppet/pal/task_signature.rb

@@ -0,0 +1,58 @@
+module Puppet
+module Pal
+  # A TaskSignature is returned from `task_signature`. Its purpose is to answer questions about the task's parameters
+  # and if it can be run/called with a hash of named parameters.
+  #
+  class TaskSignature
+    def initialize(task)
+      @task = task
+    end
+
+    # Returns whether or not the given arguments are acceptable when running the task.
+    # In addition to returning the boolean outcome, if a block is given, it is called with a string of formatted
+    # error messages that describes the difference between what was given and what is expected. The error message may
+    # have multiple lines of text, and each line is indented one space.
+    #
+    # @param args_hash [Hash] a hash mapping parameter names to argument values
+    # @yieldparam [String] a formatted error message if a type mismatch occurs that explains the mismatch
+    # @return [Boolean] if the given arguments are acceptable when running the task
+    #
+    def runnable_with?(args_hash)
+      params = @task.parameters
+      params_type = if params.nil?
+        T_GENERIC_TASK_HASH
+      else
+        Puppet::Pops::Types::TypeFactory.struct(params)
+      end
+      return true if params_type.instance?(args_hash)
+
+      if block_given?
+        tm = Puppet::Pops::Types::TypeMismatchDescriber.singleton
+        error = if params.nil?
+          tm.describe_mismatch('', params_type, Puppet::Pops::Types::TypeCalculator.infer_set(args_hash))
+        else
+          tm.describe_struct_signature(params_type, args_hash).flatten.map {|e| e.format }.join("\n")
+        end
+        yield "Task #{@task.name}:\n#{error}"
+      end
+      false
+    end
+
+    # Returns the Task instance as a hash
+    #
+    # @return [Hash{String=>Object}] the hash representation of the task
+    def task_hash
+      @task._pcore_init_hash
+    end
+
+    # Returns the Task instance which can be further explored. It contains all meta-data defined for
+    # the task such as the description, parameters, output, etc.
+    #
+    # @return [Puppet::Pops::Types::PuppetObject] An instance of a dynamically created Task class
+    def task
+      @task
+    end
+  end
+
+end
+end

data/lib/puppet/parser/functions/generate.rb

@@ -1,15 +1,16 @@
 # Runs an external command and returns the results
 Puppet::Parser::Functions::newfunction(:generate, :arity => -2, :type => :rvalue,
     :doc => "Calls an external command on the Puppet master and returns
-    the results of the command.  Any arguments are passed to the external command as
-    arguments.  If the generator does not exit with return code of 0,
+    the results of the command. Any arguments are passed to the external command as
+    arguments. If the generator does not exit with return code of 0,
     the generator is considered to have failed and a parse error is
-    thrown.  Generators can only have file separators, alphanumerics, dashes,
-    and periods in them.  This function will attempt to protect you from
+    thrown. Generators can only have file separators, alphanumerics, dashes,
+    and periods in them. This function will attempt to protect you from
     malicious generator calls (e.g., those with '..' in them), but it can
-    never be entirely safe.  No subshell is used to execute
+    never be entirely safe. No subshell is used to execute
     generators, so all shell metacharacters are passed directly to
-    the generator.") do |args|
+    the generator, and all metacharacters are returned by the function.
+    Consider cleaning white space from any string generated.") do |args|
 
       #TRANSLATORS "fully qualified" refers to a fully qualified file system path
       raise Puppet::ParseError, _("Generators must be fully qualified") unless Puppet::Util.absolute_path?(args[0])

data/lib/puppet/plugins/configuration.rb

@@ -10,6 +10,8 @@ module Puppet::Plugins
     require 'puppet/plugins/syntax_checkers'
     require 'puppet/syntax_checkers/base64'
     require 'puppet/syntax_checkers/json'
+    require 'puppet/syntax_checkers/pp'
+    require 'puppet/syntax_checkers/epp'
 
     def self.load_plugins
       # Register extensions
@@ -17,7 +19,9 @@ module Puppet::Plugins
       {
         SyntaxCheckers::SYNTAX_CHECKERS_KEY => {
           'json' => Puppet::SyntaxCheckers::Json.new,
-          'base64' => Puppet::SyntaxCheckers::Base64.new
+          'base64' => Puppet::SyntaxCheckers::Base64.new,
+          'pp' => Puppet::SyntaxCheckers::PP.new,
+          'epp' => Puppet::SyntaxCheckers::EPP.new
         }
       }
     end

data/lib/puppet/pops/evaluator/evaluator_impl.rb

@@ -1028,8 +1028,12 @@ class EvaluatorImpl
 
   # Evaluates Puppet DSL Heredoc
   def eval_HeredocExpression o, scope
+    expr = o.text_expr.expr # Always a SublocatedExpression with an expression
     result = evaluate(o.text_expr, scope)
-    assert_external_syntax(scope, result, o.syntax, o.text_expr)
+    unless expr.is_a?(Model::LiteralString)
+      # When expr is a LiteralString, validation has already validated this
+      assert_external_syntax(scope, result, o.syntax, o.text_expr)
+    end
     result
   end
 

data/lib/puppet/pops/evaluator/external_syntax_support.rb

@@ -3,11 +3,11 @@
 #
 require 'puppet/plugins/syntax_checkers'
 module Puppet::Pops::Evaluator::ExternalSyntaxSupport
-  def assert_external_syntax(scope, result, syntax, reference_expr)
+  def assert_external_syntax(_, result, syntax, reference_expr)
     # ignore 'unspecified syntax'
     return if syntax.nil? || syntax == ''
 
-    checker = checker_for_syntax(scope, syntax)
+    checker = checker_for_syntax(nil, syntax)
     # ignore syntax with no matching checker
     return unless checker
 
@@ -26,7 +26,7 @@ module Puppet::Pops::Evaluator::ExternalSyntaxSupport
   # Finds the most significant checker for the given syntax (most significant is to the right).
   # Returns nil if there is no registered checker.
   #
-  def checker_for_syntax(scope, syntax)
+  def checker_for_syntax(_, syntax)
     checkers_hash = Puppet.lookup(:plugins)[Puppet::Plugins::SyntaxCheckers::SYNTAX_CHECKERS_KEY]
     checkers_hash[lookup_keys_for_syntax(syntax).find {|x| checkers_hash[x] }]
   end

data/lib/puppet/pops/issues.rb

@@ -760,10 +760,6 @@ module Issues
     _("An escape char for @() may only appear once. Got '%{escapes}'") % { escapes: escapes.join(', ') }
   end
 
-  HEREDOC_DIRTY_MARGIN = hard_issue :HEREDOC_DIRTY_MARGIN, :heredoc_line do
-    _("Heredoc with text in the margin is not allowed (line %{heredoc_line} in this heredoc)") % { heredoc_line: heredoc_line }
-  end
-
   ILLEGAL_BOM = hard_issue :ILLEGAL_BOM, :format_name, :bytes do
     _("Illegal %{format} Byte Order mark at beginning of input: %{bom} - remove these from the puppet source") % { format: format_name, bom: bytes }
   end

data/lib/puppet/pops/loader/ruby_legacy_function_instantiator.rb

@@ -1,10 +1,7 @@
 # The RubyLegacyFunctionInstantiator instantiates a Puppet::Functions::Function given the ruby source
 # that calls Puppet::Functions.create_function.
 #
-require 'ripper'
 class Puppet::Pops::Loader::RubyLegacyFunctionInstantiator
-  UNKNOWN = '<unknown>'.freeze
-
   # Produces an instance of the Function class with the given typed_name, or fails with an error if the
   # given ruby source does not produce this instance when evaluated.
   #
@@ -16,15 +13,9 @@ class Puppet::Pops::Loader::RubyLegacyFunctionInstantiator
   # @return [Puppet::Pops::Functions.Function] - an instantiated function with global scope closure associated with the given loader
   #
   def self.create(loader, typed_name, source_ref, ruby_code_string)
-    # When func3x turned on, assert content by parsing, when turned off continue with (legacy) undefined behavior
-    if Puppet[:func3x_check]
-      assertion_result = []
-      assert_code(ruby_code_string, assertion_result)
-      unless ruby_code_string.is_a?(String) && assertion_result.include?(:found_newfunction)
-        raise ArgumentError, _("The code loaded from %{source_ref} does not seem to be a Puppet 3x API function - no 'newfunction' call.") % { source_ref: source_ref }
-      end
+    unless ruby_code_string.is_a?(String) && ruby_code_string =~ /Puppet\:\:Parser\:\:Functions.*newfunction/m
+      raise ArgumentError, _("The code loaded from %{source_ref} does not seem to be a Puppet 3x API function - no 'newfunction' call.") % { source_ref: source_ref }
     end
-
     # make the private loader available in a binding to allow it to be passed on
     loader_for_function = loader.private_loader
     here = get_binding(loader_for_function)
@@ -35,14 +26,14 @@ class Puppet::Pops::Loader::RubyLegacyFunctionInstantiator
     environment = Puppet.lookup(:current_environment)
     func_info = Puppet::Parser::Functions.environment_module(environment).get_function_info(typed_name.name.to_sym)
     if func_info.nil?
-      # This will do the 3x loading and define the "function_<name>" and "real_function_<name>" methods
+      # This will to do the 3x loading and define the "function_<name>" and "real_function_<name>" methods
       # in the anonymous module used to hold function definitions.
       #
       func_info = eval(ruby_code_string, here, source_ref, 1)
 
       # Validate what was loaded
       unless func_info.is_a?(Hash)
-        # TRANSLATORS - the word 'newfunction' should not be translated as it is a method name.
+        # TRANSLATORS - the word 'newfunction' shoud not be translated as it is a method name.
         raise ArgumentError, _("Illegal legacy function definition! The code loaded from %{source_ref} did not return the result of calling 'newfunction'. Got '%{klass}'") % { source_ref: source_ref, klass: func_info.class }
       end
       unless func_info[:name] == "function_#{typed_name.name()}"
@@ -69,51 +60,4 @@ class Puppet::Pops::Loader::RubyLegacyFunctionInstantiator
     binding
   end
   private_class_method :get_binding
-
-  def self.assert_code(code_string, result)
-    ripped = Ripper.sexp(code_string)
-    return if ripped.nil?  # Let the next real parse crash and tell where and what is wrong
-    ripped.each {|x| walk(x, result) }
-  end
-  private_class_method :assert_code
-
-  def self.walk(x, result)
-    return unless x.is_a?(Array)
-    first = x[0]
-    case first
-    when :fcall, :call
-      # Ripper returns a :fcall for a function call in a module (want to know there is a call to newfunction()).
-      # And it returns :call for a qualified named call
-      identity_part = find_identity(x)
-      result << :found_newfunction if identity_part.is_a?(Array) && identity_part[1] == 'newfunction'
-    when :def, :defs
-      # There should not be any calls to def in a 3x function
-      mname, mline = extract_name_line(find_identity(x))
-      raise SecurityError, _("Illegal method definition of method '%{method_name}' on line %{line}' in legacy function. See %{url} for more information") % { 
-        method_name: mname,
-        line: mline,
-        url: "https://puppet.com/docs/puppet/latest/functions_refactor_legacy.html"
-      }
-    end
-    x.each {|v| walk(v, result) }
-  end
-  private_class_method :walk
-
-  def self.find_identity(rast)
-    rast.find{|x| x.is_a?(Array) && x[0] == :@ident }
-  end
-  private_class_method :find_identity
-
-  # Extracts the method name and line number from the Ripper Rast for an id entry.
-  # The expected input (a result from Ripper :@ident entry) is an array with:
-  # [0] == :def (or :defs for self.def)
-  # [1] == method name
-  # [2] == [ <filename>, <linenumber> ]
-  #
-  # Returns an Array; a tuple with method name and line number or "<unknown>" if either is missing, or format is not the expected
-  #
-  def self.extract_name_line(x)
-    (x.is_a?(Array) ? [ x[1], x[2].is_a?(Array) ? x[2][1] : nil] : [nil, nil]).map {|v| v.nil? ? UNKNOWN : v }
-  end
-  private_class_method :extract_name_line
 end

data/lib/puppet/pops/model/factory.rb

@@ -28,7 +28,6 @@ class Factory
   BUILD_VISITOR = Visitor.new(self, 'build')
   INFER_VISITOR = Visitor.new(self, 'infer')
   INTERPOLATION_VISITOR = Visitor.new(self, 'interpolate')
-  MAPOFFSET_VISITOR = Visitor.new(self, 'map_offset')
 
   def self.infer(o)
     if o.instance_of?(Factory)
@@ -90,29 +89,6 @@ class Factory
     end
   end
 
-  def map_offset(model, locator)
-    MAPOFFSET_VISITOR.visit_this_1(self, model, locator)
-  end
-
-  def map_offset_Object(o, locator)
-    o
-  end
-
-  def map_offset_Factory(o, locator)
-    map_offset(o.model, locator)
-  end
-
-  def map_offset_Positioned(o, locator)
-    # Transpose the local offset, length to global "coordinates"
-    global_offset, global_length = locator.to_global(o.offset, o.length)
-
-    # mutate
-    o.instance_variable_set(:'@offset', global_offset)
-    o.instance_variable_set(:'@length', global_length)
-    # Change locator since the positions were transposed to the global coordinates
-    o.instance_variable_set(:'@locator', locator.locator) if locator.is_a? Puppet::Pops::Parser::Locator::SubLocator
-  end
-
   # Polymorphic interpolate
   def interpolate()
     INTERPOLATION_VISITOR.visit_this_class(self, @model_class, EMPTY_ARRAY)
@@ -457,7 +433,8 @@ class Factory
     @init_hash[KEY_LOCATOR] = locator
     @init_hash['leading_line_count'] = locator.leading_line_count
     @init_hash['leading_line_offset'] = locator.leading_line_offset
-    @init_hash['line_offsets'] = locator.line_index # index of lines in sublocated
+    # Index is held in sublocator's parent locator - needed to be able to reconstruct
+    @init_hash['line_offsets'] = locator.locator.line_index
   end
 
   def build_SelectorEntry(o, matching, value)
@@ -752,6 +729,8 @@ class Factory
 
   def self.STRING(*args);                new(ConcatenatedString, args);                  end
 
+  def self.SUBLOCATE(token, expr)        new(SubLocatedExpression, token, expr);         end
+
   def self.LIST(entries);                new(LiteralList, entries);                      end
 
   def self.PARAM(name, expr=nil);        new(Parameter, name, expr);                     end
@@ -786,19 +765,6 @@ class Factory
     o.instance_of?(Factory) && o.model_class <= QualifiedReference ? self : new(QualifiedReference, o)
   end
 
-  def self.SUBLOCATE(token, expr_factory)
-    # expr is a Factory wrapped LiteralString, or ConcatenatedString
-    # The token is SUBLOCATED token which has a SubLocator as the token's locator
-    # Use the SubLocator to recalculate the offsets and lengths.
-    model = expr_factory.model
-    locator = token.locator
-    expr_factory.map_offset(model, locator)
-    model._pcore_all_contents([]) { |element| expr_factory.map_offset(element, locator) }
-
-    # Returned the factory wrapping the now offset/length transformed expression(s)
-    expr_factory
-  end
-
   def self.TEXT(expr)
     new(TextExpression, infer(expr).interpolate)
   end