puppet-strings 2.4.0 → 2.8.0

data/lib/puppet-strings/yard/handlers/ruby/function_handler.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/yard/handlers/helpers'
 require 'puppet-strings/yard/handlers/ruby/base'
 require 'puppet-strings/yard/code_objects'
@@ -29,6 +31,7 @@ class PuppetStrings::Yard::Handlers::Ruby::FunctionHandler < PuppetStrings::Yard
     # newline, YARD ignores the namespace and uses `newfunction` as the source of the
     # first statement.
     return unless statement.count > 1
+
     module_name = statement[0].source
     return unless module_name == 'Puppet::Functions' || module_name == 'Puppet::Parser::Functions' || module_name == 'newfunction'
 
@@ -219,8 +222,7 @@ class PuppetStrings::Yard::Handlers::Ruby::FunctionHandler < PuppetStrings::Yard
 
     # Populate the required parameters
     params = parameters.unnamed_required_params
-    if params
-      params.each do |parameter|
+    params&.each do |parameter|
         add_param_tag(
           overload_tag,
           param_tags,
@@ -229,12 +231,10 @@ class PuppetStrings::Yard::Handlers::Ruby::FunctionHandler < PuppetStrings::Yard
           parameter.line
         )
       end
-    end
 
     # Populate the optional parameters
     params = parameters.unnamed_optional_params
-    if params
-      params.each do |parameter|
+    params&.each do |parameter|
         add_param_tag(
           overload_tag,
           param_tags,
@@ -246,7 +246,6 @@ class PuppetStrings::Yard::Handlers::Ruby::FunctionHandler < PuppetStrings::Yard
           true
         )
       end
-    end
 
     # Populate the splat parameter
     param = parameters.splat_param
@@ -301,7 +300,7 @@ class PuppetStrings::Yard::Handlers::Ruby::FunctionHandler < PuppetStrings::Yard
       name = '&' + name
     end
 
-    type ||= tag && tag.types ? tag.type : 'Any'
+    type ||= tag&.types ? tag.type : 'Any'
     type = optional ? "Optional[#{type}]" : type
 
     object.parameters << [name, to_puppet_literal(default)]
@@ -328,6 +327,7 @@ class PuppetStrings::Yard::Handlers::Ruby::FunctionHandler < PuppetStrings::Yard
     # Validate that tags have matching parameters
     overload.tags(:param).each do |tag|
       next if overload.parameters.find { |p| tag.name == p[0] }
+
       log.warn "The @param tag for parameter '#{tag.name}' has no matching parameter at #{file}:#{line}."
     end
   end
@@ -338,9 +338,11 @@ class PuppetStrings::Yard::Handlers::Ruby::FunctionHandler < PuppetStrings::Yard
       parameters[1].each do |kvp|
         next unless kvp.count == 2
         next unless node_as_string(kvp[0]) == 'doc'
+
         docstring = node_as_string(kvp[1])
 
         log.error "Failed to parse docstring for 3.x Puppet function '#{name}' near #{statement.file}:#{statement.line}." and return nil unless docstring
+
         return PuppetStrings::Yard::Util.scrub_string(docstring)
       end
     end

data/lib/puppet-strings/yard/handlers/ruby/provider_handler.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/yard/handlers/helpers'
 require 'puppet-strings/yard/handlers/ruby/base'
 require 'puppet-strings/yard/code_objects'
@@ -20,6 +22,7 @@ class PuppetStrings::Yard::Handlers::Ruby::ProviderHandler < PuppetStrings::Yard
     # Extract the type name
     type_call_parameters = type_call.parameters(false)
     return unless type_call_parameters.count >= 1
+
     type_name = node_as_string(type_call_parameters.first)
     raise YARD::Parser::UndocumentableError, "Could not determine the resource type name for the provider defined at #{statement.file}:#{statement.line}." unless type_name
 
@@ -47,8 +50,10 @@ class PuppetStrings::Yard::Handlers::Ruby::ProviderHandler < PuppetStrings::Yard
       if child.type == :assign
         ivar = child.jump(:ivar)
         next unless ivar != child && ivar.source == '@doc'
+
         docstring = node_as_string(child[1])
         log.error "Failed to parse docstring for Puppet provider '#{object.name}' (resource type '#{object.type_name}') near #{child.file}:#{child.line}." and return nil unless docstring
+
         register_docstring(object, PuppetStrings::Yard::Util.scrub_string(docstring), nil)
         return nil
       elsif child.is_a?(YARD::Parser::Ruby::MethodCallNode)
@@ -60,6 +65,7 @@ class PuppetStrings::Yard::Handlers::Ruby::ProviderHandler < PuppetStrings::Yard
 
         docstring = node_as_string(child.parameters[0])
         log.error "Failed to parse docstring for Puppet provider '#{object.name}' (resource type '#{object.type_name}') near #{child.file}:#{child.line}." and return nil unless docstring
+
         register_docstring(object, PuppetStrings::Yard::Util.scrub_string(docstring), nil)
         return nil
       end
@@ -71,6 +77,7 @@ class PuppetStrings::Yard::Handlers::Ruby::ProviderHandler < PuppetStrings::Yard
     # Traverse the block looking for confines/defaults/commands
     block = statement.block
     return unless block && block.count >= 2
+
     block[1].children.each do |node|
       next unless node.is_a?(YARD::Parser::Ruby::MethodCallNode) && node.method_name
 
@@ -80,8 +87,10 @@ class PuppetStrings::Yard::Handlers::Ruby::ProviderHandler < PuppetStrings::Yard
       if method_name == 'confine'
         # Add a confine to the object
         next unless parameters.count >= 1
+
         parameters[0].each do |kvp|
           next unless kvp.count == 2
+
           object.add_confine(node_as_string(kvp[0]) || kvp[0].source, node_as_string(kvp[1]) || kvp[1].source)
         end
       elsif method_name == 'has_feature' || method_name == 'has_features'
@@ -92,9 +101,11 @@ class PuppetStrings::Yard::Handlers::Ruby::ProviderHandler < PuppetStrings::Yard
       elsif method_name == 'defaultfor'
         # Add a default to the object
         next unless parameters.count >= 1
+
         # Some defaultfor statements contain multiple constraints.
         parameters.each do |kvps|
           next unless kvps.count >= 1
+
           defaultfor = []
           kvps.each do |kvp|
             defaultfor << [node_as_string(kvp[0]) || kvp[0].source, node_as_string(kvp[1]) || kvp[1].source]
@@ -104,8 +115,10 @@ class PuppetStrings::Yard::Handlers::Ruby::ProviderHandler < PuppetStrings::Yard
       elsif method_name == 'commands'
         # Add the commands to the object
         next unless parameters.count >= 1
+
         parameters[0].each do |kvp|
           next unless kvp.count == 2
+
           object.add_command(node_as_string(kvp[0]) || kvp[0].source, node_as_string(kvp[1]) || kvp[1].source)
         end
       end

data/lib/puppet-strings/yard/handlers/ruby/rsapi_handler.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/yard/handlers/helpers'
 require 'puppet-strings/yard/handlers/ruby/base'
 require 'puppet-strings/yard/code_objects'
@@ -6,7 +8,7 @@ require 'puppet-strings/yard/util'
 # Implements the handler for Puppet resource types written in Ruby.
 class PuppetStrings::Yard::Handlers::Ruby::RsapiHandler < PuppetStrings::Yard::Handlers::Ruby::Base
   # The default docstring when ensurable is used without given a docstring.
-  DEFAULT_ENSURABLE_DOCSTRING = 'The basic property that the resource should be in.'.freeze
+  DEFAULT_ENSURABLE_DOCSTRING = 'The basic property that the resource should be in.'
 
   namespace_only
   handles method_call(:register_type)
@@ -14,6 +16,7 @@ class PuppetStrings::Yard::Handlers::Ruby::RsapiHandler < PuppetStrings::Yard::H
   process do
     # Only accept calls to Puppet::ResourceApi
     return unless statement.count > 1
+
     module_name = statement[0].source
     return unless ['Puppet::ResourceApi'].include? module_name
 

data/lib/puppet-strings/yard/handlers/ruby/type_base.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/yard/handlers/ruby/base'
 
 class PuppetStrings::Yard::Handlers::Ruby::TypeBase < PuppetStrings::Yard::Handlers::Ruby::Base
@@ -22,8 +24,10 @@ class PuppetStrings::Yard::Handlers::Ruby::TypeBase < PuppetStrings::Yard::Handl
       if child.type == :assign
         ivar = child.jump(:ivar)
         next unless ivar != child && ivar.source == '@doc'
+
         docstring = node_as_string(child[1])
         log.error "Failed to parse docstring for #{kind} near #{child.file}:#{child.line}." and return nil unless docstring
+
         return PuppetStrings::Yard::Util.scrub_string(docstring)
       elsif child.is_a?(YARD::Parser::Ruby::MethodCallNode)
         # Look for a call to a dispatch method with a block
@@ -33,6 +37,7 @@ class PuppetStrings::Yard::Handlers::Ruby::TypeBase < PuppetStrings::Yard::Handl
 
         docstring = node_as_string(child.parameters[0])
         log.error "Failed to parse docstring for #{kind} near #{child.file}:#{child.line}." and return nil unless docstring
+
         return PuppetStrings::Yard::Util.scrub_string(docstring)
       end
     end
@@ -52,6 +57,12 @@ class PuppetStrings::Yard::Handlers::Ruby::TypeBase < PuppetStrings::Yard::Handl
     property
   end
 
+  def create_check(name, node)
+    check = PuppetStrings::Yard::CodeObjects::Type::Check.new(name, find_docstring(node, "Puppet resource check '#{name}'"))
+    set_values(node, check)
+    check
+  end
+
   def set_values(node, object)
     return unless node.block && node.block.count >= 2
 
@@ -63,6 +74,7 @@ class PuppetStrings::Yard::Handlers::Ruby::TypeBase < PuppetStrings::Yard::Handl
 
       if method_name == 'newvalue'
         next unless parameters.count >= 1
+
         object.add(node_as_string(parameters[0]) || parameters[0].source)
       elsif method_name == 'newvalues'
         parameters.each do |p|
@@ -70,9 +82,11 @@ class PuppetStrings::Yard::Handlers::Ruby::TypeBase < PuppetStrings::Yard::Handl
         end
       elsif method_name == 'aliasvalue'
         next unless parameters.count >= 2
+
         object.alias(node_as_string(parameters[0]) || parameters[0].source, node_as_string(parameters[1]) || parameters[1].source)
       elsif method_name == 'defaultto'
         next unless parameters.count >= 1
+
         object.default = node_as_string(parameters[0]) || parameters[0].source
       elsif method_name == 'isnamevar'
         object.isnamevar = true
@@ -97,6 +111,7 @@ class PuppetStrings::Yard::Handlers::Ruby::TypeBase < PuppetStrings::Yard::Handl
         parameters[1].each do |kvp|
           next unless kvp.count == 2
           next unless node_as_string(kvp[0]) == 'parent'
+
           if kvp[1].source == 'Puppet::Parameter::Boolean'
             object.add('true') unless object.values.include? 'true' # rubocop:disable Performance/InefficientHashSearch Not supported on Ruby 2.1
             object.add('false') unless object.values.include? 'false' # rubocop:disable Performance/InefficientHashSearch Not supported on Ruby 2.1
@@ -111,19 +126,18 @@ class PuppetStrings::Yard::Handlers::Ruby::TypeBase < PuppetStrings::Yard::Handl
 
   def set_default_namevar(object)
     return unless object.properties || object.parameters
+
     default = nil
-    if object.properties
-      object.properties.each do |property|
+    object.properties&.each do |property|
         return nil if property.isnamevar
+
         default = property if property.name == 'name'
       end
-    end
-    if object.parameters
-      object.parameters.each do |parameter|
+    object.parameters&.each do |parameter|
         return nil if parameter.isnamevar
+
         default ||= parameter if parameter.name == 'name'
       end
-    end
     default.isnamevar = true if default
   end
 end

data/lib/puppet-strings/yard/handlers/ruby/type_extras_handler.rb

@@ -1,16 +1,19 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/yard/handlers/helpers'
 require 'puppet-strings/yard/handlers/ruby/type_base'
 require 'puppet-strings/yard/code_objects'
 require 'puppet-strings/yard/util'
 
-# Implements the handler for Puppet resource type newparam/newproperty calls written in Ruby.
+# Implements the handler for Puppet resource type newparam/newproperty/ensurable calls written in Ruby.
 class PuppetStrings::Yard::Handlers::Ruby::TypeExtrasHandler < PuppetStrings::Yard::Handlers::Ruby::TypeBase
   # The default docstring when ensurable is used without given a docstring.
-  DEFAULT_ENSURABLE_DOCSTRING = 'The basic property that the resource should be in.'.freeze
+  DEFAULT_ENSURABLE_DOCSTRING = 'The basic property that the resource should be in.'
 
   namespace_only
   handles method_call(:newparam)
   handles method_call(:newproperty)
+  handles method_call(:ensurable)
 
   process do
 
@@ -31,13 +34,20 @@ class PuppetStrings::Yard::Handlers::Ruby::TypeExtrasHandler < PuppetStrings::Ya
     #   propertyname: "content"
 
     return unless (statement.count > 1) && (statement[0].children.count > 2)
+
     module_name = statement[0].children[0].source
-    method1_name = statement[0].children[1].source
-    return unless (module_name == 'Puppet::Type' || module_name == 'Type') && method1_name == 'type'
+    method1_name = statement[0].children.drop(1).find{ |c| c.type == :ident }.source
+    return unless ['Type', 'Puppet::Type'].include?(module_name) && method1_name == 'type'
 
+    # ensurable is syntatic sugar for newproperty
     typename = get_name(statement[0], 'Puppet::Type.type')
-    method2_name = caller_method
-    propertyname = get_name(statement, "Puppet::Type.type().#{method2_name}")
+    if caller_method == 'ensurable'
+      method2_name = 'newproperty'
+      propertyname = 'ensure'
+    else
+      method2_name = caller_method
+      propertyname = get_name(statement, "Puppet::Type.type().#{method2_name}")
+    end
 
     typeobject = get_type_yard_object(typename)
 

data/lib/puppet-strings/yard/handlers/ruby/type_handler.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/yard/handlers/helpers'
 require 'puppet-strings/yard/handlers/ruby/type_base'
 require 'puppet-strings/yard/code_objects'
@@ -6,7 +8,7 @@ require 'puppet-strings/yard/util'
 # Implements the handler for Puppet resource types written in Ruby.
 class PuppetStrings::Yard::Handlers::Ruby::TypeHandler < PuppetStrings::Yard::Handlers::Ruby::TypeBase
   # The default docstring when ensurable is used without given a docstring.
-  DEFAULT_ENSURABLE_DOCSTRING = 'The basic property that the resource should be in.'.freeze
+  DEFAULT_ENSURABLE_DOCSTRING = 'The basic property that the resource should be in.'
 
   namespace_only
   handles method_call(:newtype)
@@ -14,6 +16,7 @@ class PuppetStrings::Yard::Handlers::Ruby::TypeHandler < PuppetStrings::Yard::Ha
   process do
     # Only accept calls to Puppet::Type
     return unless statement.count > 1
+
     module_name = statement[0].source
     return unless module_name == 'Puppet::Type' || module_name == 'Type'
 
@@ -40,6 +43,7 @@ class PuppetStrings::Yard::Handlers::Ruby::TypeHandler < PuppetStrings::Yard::Ha
     # Traverse the block looking for properties/parameters/features
     block = statement.block
     return unless block && block.count >= 2
+
     block[1].children.each do |node|
       next unless node.is_a?(YARD::Parser::Ruby::MethodCallNode) &&
                   node.method_name
@@ -50,18 +54,31 @@ class PuppetStrings::Yard::Handlers::Ruby::TypeHandler < PuppetStrings::Yard::Ha
       if method_name == 'newproperty'
         # Add a property to the object
         next unless parameters.count >= 1
+
         name = node_as_string(parameters[0])
         next unless name
+
         object.add_property(create_property(name, node))
       elsif method_name == 'newparam'
         # Add a parameter to the object
         next unless parameters.count >= 1
+
         name = node_as_string(parameters[0])
         next unless name
+
         object.add_parameter(create_parameter(name, node))
+      elsif method_name == 'newcheck'
+        # Add a check to the object
+        next unless parameters.count >= 1
+
+        name = node_as_string(parameters[0])
+        next unless name
+
+        object.add_check(create_check(name, node))
       elsif method_name == 'feature'
         # Add a feature to the object
         next unless parameters.count >= 2
+
         name = node_as_string(parameters[0])
         next unless name
 

data/lib/puppet-strings/yard/parsers.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # The module for custom YARD parsers.
 module PuppetStrings::Yard::Parsers
   # The module for custom YARD parsers for JSON.

data/lib/puppet-strings/yard/parsers/json/parser.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/yard/parsers/json/task_statement'
 
 class PuppetStrings::Yard::Parsers::JSON::Parser < YARD::Parser::Base

data/lib/puppet-strings/yard/parsers/json/task_statement.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module PuppetStrings::Yard::Parsers::JSON
   # Represents the Puppet Task statement.
   class TaskStatement

data/lib/puppet-strings/yard/parsers/puppet/parser.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet'
 require 'puppet/pops'
 require 'puppet-strings/yard/parsers/puppet/statement'
@@ -20,14 +22,16 @@ class PuppetStrings::Yard::Parsers::Puppet::Parser < YARD::Parser::Base
   # @return [void]
   def parse
     begin
-      Puppet[:tasks] = true if Puppet.settings.include?(:tasks)
-      if Puppet::Util::Package.versioncmp(Puppet.version, "5.0.0") < 0 && @file.to_s.match(/^plans\//)
-        log.warn "Skipping #{@file}: Puppet Plans require Puppet 5 or greater."
-        return
+      if @file.to_s.match(/^plans|\/plans\//)
+        if Puppet::Util::Package.versioncmp(Puppet.version, "5.0.0") < 0
+          log.warn "Skipping #{@file}: Puppet Plans require Puppet 5 or greater."
+          return
+        end
+        Puppet[:tasks] = true if Puppet.settings.include?(:tasks)
       end
       @statements ||= (@visitor.visit(::Puppet::Pops::Parser::Parser.new.parse_string(source)) || []).compact
-    rescue ::Puppet::ParseError => ex
-      log.error "Failed to parse #{@file}: #{ex.message}"
+    rescue ::Puppet::ParseError => e
+      log.error "Failed to parse #{@file}: #{e.message}"
       @statements = []
     end
     @statements.freeze
@@ -42,47 +46,47 @@ class PuppetStrings::Yard::Parsers::Puppet::Parser < YARD::Parser::Base
 
   private
 
-  def transform_Program(o) # rubocop:disable Naming/UncommunicativeMethodParamName
+  def transform_Program(o)
     # Cache the lines of the source text; we'll use this to locate comments
     @lines = o.source_text.lines.to_a
     o.definitions.map { |d| @visitor.visit(d) }
   end
 
-  def transform_Factory(o) # rubocop:disable Naming/UncommunicativeMethodParamName
+  def transform_Factory(o)
     @visitor.visit(o.current)
   end
 
-  def transform_HostClassDefinition(o) # rubocop:disable Naming/UncommunicativeMethodParamName
+  def transform_HostClassDefinition(o)
     statement = PuppetStrings::Yard::Parsers::Puppet::ClassStatement.new(o, @file)
     statement.extract_docstring(@lines)
     statement
   end
 
-  def transform_ResourceTypeDefinition(o) # rubocop:disable Naming/UncommunicativeMethodParamName
+  def transform_ResourceTypeDefinition(o)
     statement = PuppetStrings::Yard::Parsers::Puppet::DefinedTypeStatement.new(o, @file)
     statement.extract_docstring(@lines)
     statement
   end
 
-  def transform_FunctionDefinition(o) # rubocop:disable Naming/UncommunicativeMethodParamName
+  def transform_FunctionDefinition(o)
     statement = PuppetStrings::Yard::Parsers::Puppet::FunctionStatement.new(o, @file)
     statement.extract_docstring(@lines)
     statement
   end
 
-  def transform_PlanDefinition(o) # rubocop:disable Naming/UncommunicativeMethodParamName
+  def transform_PlanDefinition(o)
     statement = PuppetStrings::Yard::Parsers::Puppet::PlanStatement.new(o, @file)
     statement.extract_docstring(@lines)
     statement
   end
 
-  def transform_TypeAlias(o) # rubocop:disable Naming/UncommunicativeMethodParamName
+  def transform_TypeAlias(o)
     statement = PuppetStrings::Yard::Parsers::Puppet::DataTypeAliasStatement.new(o, @file)
     statement.extract_docstring(@lines)
     statement
   end
 
-  def transform_Object(o) # rubocop:disable Naming/UncommunicativeMethodParamName
+  def transform_Object(o)
     # Ignore anything else (will be compacted out of the resulting array)
   end
 end