puppet-strings 2.2.0 → 2.6.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,9 +300,7 @@ class PuppetStrings::Yard::Handlers::Ruby::FunctionHandler < PuppetStrings::Yard
       name = '&' + name
     end
 
-    unless type
-      type = tag && tag.types ? tag.type : 'Any'
-    end
+    type ||= tag&.types ? tag.type : 'Any'
     type = optional ? "Optional[#{type}]" : type
 
     object.parameters << [name, to_puppet_literal(default)]
@@ -330,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
@@ -340,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,8 +16,9 @@ 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
+    return unless ['Puppet::ResourceApi'].include? module_name
 
     schema = extract_schema
 
@@ -92,7 +95,7 @@ class PuppetStrings::Yard::Handlers::Ruby::RsapiHandler < PuppetStrings::Yard::H
     # puts "hash from #{node.inspect}"
 
     kv_pairs = node.children.collect do |assoc|
-      [ value_from_node(assoc.children[0]), value_from_node(assoc.children[1]) ]
+      [value_from_node(assoc.children[0]), value_from_node(assoc.children[1])]
     end
     Hash[kv_pairs]
   end

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
@@ -15,15 +17,17 @@ class PuppetStrings::Yard::Handlers::Ruby::TypeBase < PuppetStrings::Yard::Handl
     register object
     object
   end
-    
+
   def find_docstring(node, kind)
     # Walk the tree searching for assignments or calls to desc/doc=
     node.traverse do |child|
       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,11 +111,12 @@ 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'
-            object.add('false') unless object.values.include? 'false'
-            object.add('yes') unless object.values.include? 'yes'
-            object.add('no') unless object.values.include? 'no'
+            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
+            object.add('yes') unless object.values.include? 'yes' # rubocop:disable Performance/InefficientHashSearch Not supported on Ruby 2.1
+            object.add('no') unless object.values.include? 'no' # rubocop:disable Performance/InefficientHashSearch Not supported on Ruby 2.1
           end
           break
         end
@@ -111,20 +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,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 type newparam/newproperty 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)
@@ -31,9 +33,10 @@ 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'
 
     typename = get_name(statement[0], 'Puppet::Type.type')
     method2_name = caller_method

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
@@ -25,7 +27,7 @@ class PuppetStrings::Yard::Parsers::JSON::Parser < YARD::Parser::Base
       # TODO: this should compare json to a Task metadata json-schema or perform some other hueristics
       # to determine what type of statement it represents
       @statements.push(PuppetStrings::Yard::Parsers::JSON::TaskStatement.new(json, @source, @file)) unless json.empty?
-    rescue
+    rescue  # rubocop:disable Style/RescueStandardError  Just catch everything
       log.error "Failed to parse #{@file}: "
       @statements = []
     end

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'
@@ -26,8 +28,8 @@ class PuppetStrings::Yard::Parsers::Puppet::Parser < YARD::Parser::Base
         return
       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
@@ -41,6 +43,7 @@ class PuppetStrings::Yard::Parsers::Puppet::Parser < YARD::Parser::Base
   end
 
   private
+
   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
@@ -75,6 +78,12 @@ class PuppetStrings::Yard::Parsers::Puppet::Parser < YARD::Parser::Base
     statement
   end
 
+  def transform_TypeAlias(o)
+    statement = PuppetStrings::Yard::Parsers::Puppet::DataTypeAliasStatement.new(o, @file)
+    statement.extract_docstring(@lines)
+    statement
+  end
+
   def transform_Object(o)
     # Ignore anything else (will be compacted out of the resulting array)
   end

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet'
 require 'puppet/pops'
 
@@ -32,11 +34,13 @@ module PuppetStrings::Yard::Parsers::Puppet
       comment = []
       (0..@line-2).reverse_each do |index|
         break unless index <= lines.count
+
         line = lines[index].strip
         count = line.size
         line.gsub!(COMMENT_REGEX, '')
         # Break out if nothing was removed (wasn't a comment line)
         break unless line.size < count
+
         comment << line
       end
       @comments_range = (@line - comment.size - 1..@line - 1)
@@ -165,4 +169,29 @@ module PuppetStrings::Yard::Parsers::Puppet
     end
   end
 
+  # Implements the Puppet data type alias statement.
+  class DataTypeAliasStatement < Statement
+    attr_reader :name
+    attr_reader :alias_of
+
+    # Initializes the Puppet data type alias statement.
+    # @param [Puppet::Pops::Model::TypeAlias] object The model object for the type statement.
+    # @param [String] file The file containing the statement.
+    def initialize(object, file)
+      super(object, file)
+
+      type_expr = object.type_expr
+      case type_expr
+      when Puppet::Pops::Model::AccessExpression
+        # TODO: I don't like rebuilding the source from the AST, but AccessExpressions don't expose the original source
+        @alias_of = ::Puppet::Pops::Adapters::SourcePosAdapter.adapt(type_expr.left_expr).extract_text + '['
+        @alias_of << type_expr.keys.map { |key| ::Puppet::Pops::Adapters::SourcePosAdapter.adapt(key).extract_text }.join(', ')
+        @alias_of << ']'
+      else
+        adapter = ::Puppet::Pops::Adapters::SourcePosAdapter.adapt(type_expr)
+        @alias_of = adapter.extract_text
+      end
+      @name = object.name
+    end
+  end
 end