openvox-strings 5.0.0

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

@@ -0,0 +1,386 @@
+# frozen_string_literal: true
+
+require 'openvox-strings/yard/handlers/helpers'
+require 'openvox-strings/yard/handlers/ruby/base'
+require 'openvox-strings/yard/code_objects'
+require 'openvox-strings/yard/util'
+
+# Implements the handler for Puppet functions written in Ruby.
+class OpenvoxStrings::Yard::Handlers::Ruby::FunctionHandler < OpenvoxStrings::Yard::Handlers::Ruby::Base
+  # Represents the list of Puppet 4.x function API methods to support.
+  DISPATCH_METHOD_NAMES = %w[
+    param
+    required_param
+    optional_param
+    repeated_param
+    optional_repeated_param
+    required_repeated_param
+    block_param
+    required_block_param
+    optional_block_param
+    return_type
+  ].freeze
+
+  namespace_only
+  handles method_call(:create_function)
+  handles method_call(:newfunction)
+
+  process do
+    # Only accept calls to Puppet::Functions (4.x) or Puppet::Parser::Functions (3.x)
+    # When `newfunction` is separated from the Puppet::Parser::Functions module name by a
+    # 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 ['Puppet::Functions', 'Puppet::Parser::Functions', 'newfunction'].include?(module_name)
+
+    # Create and register the function object
+    is_3x = ['Puppet::Parser::Functions', 'newfunction'].include?(module_name)
+    object = OpenvoxStrings::Yard::CodeObjects::Function.new(
+      get_name(statement, 'Puppet::Functions.create_function'),
+      is_3x ? OpenvoxStrings::Yard::CodeObjects::Function::RUBY_3X : OpenvoxStrings::Yard::CodeObjects::Function::RUBY_4X
+    )
+    object.source = statement
+    register object
+
+    # For 3x, parse the doc parameter for the docstring
+    # This must be done after the `register` call above because `register` always uses the statement's docstring
+    if is_3x
+      docstring = get_3x_docstring(object.name)
+      register_docstring(object, docstring, nil) if docstring
+
+      # Default any typeless param tag to 'Any'
+      object.tags(:param).each do |tag|
+        tag.types = ['Any'] unless tag.types && !tag.types.empty?
+      end
+
+      # Populate the parameters and the return tag
+      object.parameters = object.tags(:param).map { |p| [p.name, nil] }
+      add_return_tag(object, statement.file, statement.line)
+    else
+      # For 4x, auto generate tags based on dispatch docstrings
+      add_tags(object)
+    end
+
+    # Mark the function as public if it doesn't already have an api tag
+    object.add_tag YARD::Tags::Tag.new(:api, 'public') unless object.has_tag? :api
+
+    # Warn if a summary longer than 140 characters was provided
+    OpenvoxStrings::Yard::Handlers::Helpers.validate_summary_tag(object) if object.has_tag? :summary
+  end
+
+  private
+
+  def add_tags(object)
+    log.warn "Missing documentation for Puppet function '#{object.name}' at #{statement.file}:#{statement.line}." if object.docstring.empty? && object.tags.empty?
+
+    unless object.tags(:param).empty?
+      log.warn "The docstring for Puppet 4.x function '#{object.name}' " \
+               "contains @param tags near #{object.file}:#{object.line}: parameter " \
+               'documentation should be made on the dispatch call.'
+    end
+
+    unless object.tags(:return).empty?
+      log.warn "The docstring for Puppet 4.x function '#{object.name}' " \
+               "contains @return tags near #{object.file}:#{object.line}: return " \
+               'value documentation should be made on the dispatch call.'
+    end
+
+    unless object.tags(:overload).empty?
+      log.warn "The docstring for Puppet 4.x function '#{object.name}' " \
+               "contains @overload tags near #{object.file}:#{object.line}: overload " \
+               'tags are automatically generated from the dispatch calls.'
+    end
+
+    # Delete any existing param/return/overload tags
+    object.docstring.delete_tags(:param)
+    object.docstring.delete_tags(:return)
+    object.docstring.delete_tags(:overload)
+
+    block = statement.block
+    return unless block && block.count >= 2
+
+    # Get the unqualified name of the Puppet function
+    unqualified_name = object.name.to_s.split('::').last
+
+    # Walk the block statements looking for dispatch calls and methods with the same name as the Puppet function
+    default = nil
+    block[1].children.each do |node|
+      if node.is_a?(YARD::Parser::Ruby::MethodCallNode)
+        add_overload_tag(object, node)
+      elsif node.is_a?(YARD::Parser::Ruby::MethodDefinitionNode)
+        default = node if node.method_name && node.method_name.source == unqualified_name
+      end
+    end
+
+    # Create an overload for the default method if there is one
+    overloads = object.tags(:overload)
+    if overloads.empty? && default
+      add_method_overload(object, default)
+      overloads = object.tags(:overload)
+    end
+
+    # If there's only one overload, move the tags to the object itself
+    return unless overloads.length == 1
+
+    overload = overloads.first
+    object.parameters = overload.parameters
+    object.add_tag(*overload.tags)
+    object.docstring.delete_tags(:overload)
+  end
+
+  def add_overload_tag(object, node)
+    # Look for a call to a dispatch method with a block
+    return unless node.is_a?(YARD::Parser::Ruby::MethodCallNode) &&
+                  node.method_name &&
+                  node.method_name.source == 'dispatch' &&
+                  node.parameters(false).count == 1 &&
+                  node.block &&
+                  node.block.count >= 2
+
+    overload_tag = OpenvoxStrings::Yard::Tags::OverloadTag.new(object.name, node.docstring || '')
+    param_tags = overload_tag.tags(:param)
+
+    block = nil
+    node.block[1].children.each do |child|
+      next unless child.is_a?(YARD::Parser::Ruby::MethodCallNode) && child.method_name
+
+      method_name = child.method_name.source
+      next unless DISPATCH_METHOD_NAMES.include?(method_name)
+
+      if method_name == 'return_type'
+        # Add a return tag if missing
+        overload_tag.add_tag YARD::Tags::Tag.new(:return, '', 'Any') if overload_tag.tag(:return).nil?
+
+        overload_tag.tag(:return).types = [node_as_string(child.parameters[0])]
+        next
+      end
+
+      # Check for block
+      if method_name.include?('block')
+        if block
+          log.warn "A duplicate block parameter was found for Puppet function '#{object.name}' at #{child.file}:#{child.line}."
+          next
+        end
+
+        # Store the block; needs to be appended last
+        block = child
+        next
+      end
+
+      # Ensure two parameters to parameter definition
+      parameters = child.parameters(false)
+      unless parameters.count == 2
+        log.warn "Expected 2 arguments to '#{method_name}' call at #{child.file}:#{child.line}: parameter information may not be correct."
+        next
+      end
+
+      add_param_tag(
+        overload_tag,
+        param_tags,
+        node_as_string(parameters[1]),
+        child.file,
+        child.line,
+        node_as_string(parameters[0]),
+        nil, # TODO: determine default from corresponding Ruby method signature?
+        method_name.include?('optional'),
+        method_name.include?('repeated')
+      )
+    end
+
+    # Handle the block parameter after others so it appears last in the list
+    if block
+      parameters = block.parameters(false)
+      if parameters.empty?
+        name = 'block'
+        type = 'Callable'
+      elsif parameters.count == 1
+        name = node_as_string(parameters[0])
+        type = 'Callable'
+      elsif parameters.count == 2
+        type = node_as_string(parameters[0])
+        name = node_as_string(parameters[1])
+      else
+        log.warn "Unexpected number of arguments to block definition at #{block.file}:#{block.line}."
+      end
+
+      if name && type
+        add_param_tag(
+          overload_tag,
+          param_tags,
+          name,
+          block.file,
+          block.line,
+          type,
+          nil, # TODO: determine default from corresponding Ruby method signature?
+          block.method_name.source.include?('optional'),
+          false, # Not repeated
+          true # Is block
+        )
+      end
+    end
+
+    # Add a return tag if missing
+    add_return_tag(overload_tag, node.file, node.line)
+
+    # Validate that tags have parameters
+    validate_overload(overload_tag, node.file, node.line)
+
+    object.add_tag overload_tag
+  end
+
+  def add_method_overload(object, node)
+    overload_tag = OpenvoxStrings::Yard::Tags::OverloadTag.new(object.name, node.docstring || '')
+    param_tags = overload_tag.tags(:param)
+
+    parameters = node.parameters
+
+    # Populate the required parameters
+    params = parameters.unnamed_required_params
+    params&.each do |parameter|
+      add_param_tag(
+        overload_tag,
+        param_tags,
+        parameter.source,
+        parameter.file,
+        parameter.line
+      )
+    end
+
+    # Populate the optional parameters
+    params = parameters.unnamed_optional_params
+    params&.each do |parameter|
+      add_param_tag(
+        overload_tag,
+        param_tags,
+        parameter[0].source,
+        parameter.file,
+        parameter.line,
+        nil,
+        parameter[1].source,
+        true
+      )
+    end
+
+    # Populate the splat parameter
+    param = parameters.splat_param
+    if param
+      add_param_tag(
+        overload_tag,
+        param_tags,
+        param.source,
+        param.file,
+        param.line,
+        nil,
+        nil,
+        false,
+        true
+      )
+    end
+
+    # Populate the block parameter
+    param = parameters.block_param
+    if param
+      add_param_tag(
+        overload_tag,
+        param_tags,
+        param.source,
+        param.file,
+        param.line,
+        nil,
+        nil,
+        false,
+        false,
+        true
+      )
+    end
+
+    # Add a return tag if missing
+    add_return_tag(overload_tag, node.file, node.line)
+
+    # Validate that tags have parameters
+    validate_overload(overload_tag, node.file, node.line)
+
+    object.add_tag overload_tag
+  end
+
+  def add_param_tag(object, tags, name, file, line, type = nil, default = nil, optional = false, repeated = false, block = false)
+    tag = tags.find { |t| t.name == name } if tags
+    log.warn "Missing @param tag for parameter '#{name}' near #{file}:#{line}." unless tag || object.docstring.all.empty?
+
+    if type && tag && tag.types && !tag.types.empty?
+      log.warn "The @param tag for parameter '#{name}' should not contain a " \
+               "type specification near #{file}:#{line}: ignoring in favor of " \
+               'dispatch type information.'
+    end
+
+    if repeated
+      name = "*#{name}"
+    elsif block
+      name = "&#{name}"
+    end
+
+    type ||= tag&.types ? tag.type : 'Any'
+    type = "Optional[#{type}]" if optional
+
+    object.parameters << [name, to_puppet_literal(default)]
+
+    if tag
+      tag.name = name
+      tag.types = [type]
+    else
+      object.add_tag YARD::Tags::Tag.new(:param, '', type, name)
+    end
+  end
+
+  def add_return_tag(object, file, line)
+    tag = object.tag(:return)
+    if tag
+      tag.types = ['Any'] unless tag.types
+      return
+    end
+    log.warn "Missing @return tag near #{file}:#{line}."
+    object.add_tag YARD::Tags::Tag.new(:return, '', 'Any')
+  end
+
+  def validate_overload(overload, file, line)
+    # 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
+
+  def get_3x_docstring(name)
+    parameters = statement.parameters(false)
+    if parameters.count >= 2
+      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 OpenvoxStrings::Yard::Util.scrub_string(docstring)
+      end
+    end
+
+    # Log a warning for missing docstring
+    log.warn "Missing documentation for Puppet function '#{name}' at #{statement.file}:#{statement.line}."
+    nil
+  end
+
+  def to_puppet_literal(literal)
+    case literal
+    when 'nil'
+      'undef'
+    when ':default'
+      'default'
+    else
+      literal
+    end
+  end
+end

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

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require 'openvox-strings/yard/handlers/helpers'
+require 'openvox-strings/yard/handlers/ruby/base'
+require 'openvox-strings/yard/code_objects'
+require 'openvox-strings/yard/util'
+
+# Implements the handler for Puppet providers written in Ruby.
+class OpenvoxStrings::Yard::Handlers::Ruby::ProviderHandler < OpenvoxStrings::Yard::Handlers::Ruby::Base
+  namespace_only
+  handles method_call(:provide)
+
+  process do
+    return unless statement.count >= 2
+
+    # Check that provide is being called on Puppet::Type.type(<name>)
+    type_call = statement[0]
+    return unless type_call.is_a?(YARD::Parser::Ruby::MethodCallNode) && type_call.count >= 3
+    return unless type_call[0].source == 'Puppet::Type'
+    return unless type_call[2].source == 'type'
+
+    # 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
+
+    # Register the object
+    object = OpenvoxStrings::Yard::CodeObjects::Provider.new(type_name, get_name(statement, "'provide'"))
+    register object
+
+    # Extract the docstring
+    register_provider_docstring object
+
+    # Populate the provider data
+    populate_provider_data object
+
+    # Mark the provider as public if it doesn't already have an api tag
+    object.add_tag YARD::Tags::Tag.new(:api, 'public') unless object.has_tag? :api
+
+    # Warn if a summary longer than 140 characters was provided
+    OpenvoxStrings::Yard::Handlers::Helpers.validate_summary_tag(object) if object.has_tag? :summary
+  end
+
+  private
+
+  def register_provider_docstring(object)
+    # Walk the tree searching for assignments or calls to desc/doc=
+    statement.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 Puppet provider '#{object.name}' (resource type '#{object.type_name}') near #{child.file}:#{child.line}." and return nil unless docstring
+
+        register_docstring(object, OpenvoxStrings::Yard::Util.scrub_string(docstring), nil)
+        return nil
+      elsif child.is_a?(YARD::Parser::Ruby::MethodCallNode)
+        # Look for a call to a dispatch method with a block
+        next unless
+          child.method_name &&
+          ['desc', 'doc='].include?(child.method_name.source) &&
+          child.parameters(false).count == 1
+
+        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, OpenvoxStrings::Yard::Util.scrub_string(docstring), nil)
+        return nil
+      end
+    end
+    log.warn "Missing a description for Puppet provider '#{object.name}' (resource type '#{object.type_name}') at #{statement.file}:#{statement.line}."
+  end
+
+  def populate_provider_data(object)
+    # 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
+
+      method_name = node.method_name.source
+      parameters = node.parameters(false)
+
+      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 %w[has_feature has_features].include?(method_name)
+        # Add the features to the object
+        parameters.each do |parameter|
+          object.add_feature(node_as_string(parameter) || parameter.source)
+        end
+      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.map do |kvp|
+            [node_as_string(kvp[0]) || kvp[0].source, node_as_string(kvp[1]) || kvp[1].source]
+          end
+          object.add_default(defaultfor)
+        end
+      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
+    end
+  end
+end

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

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require 'openvox-strings/yard/handlers/helpers'
+require 'openvox-strings/yard/handlers/ruby/base'
+require 'openvox-strings/yard/code_objects'
+require 'openvox-strings/yard/util'
+
+# Implements the handler for Puppet resource types written in Ruby.
+class OpenvoxStrings::Yard::Handlers::Ruby::RsapiHandler < OpenvoxStrings::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.'
+
+  namespace_only
+  handles method_call(:register_type)
+
+  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
+
+    schema = extract_schema
+
+    # puts "Schema: #{schema.inspect}"
+
+    object = OpenvoxStrings::Yard::CodeObjects::Type.new(schema['name'])
+    register object
+
+    docstring = schema['docs']
+    if docstring
+      register_docstring(object, OpenvoxStrings::Yard::Util.scrub_string(docstring.to_s), nil)
+    else
+      log.warn "Missing a description for Puppet resource type '#{object.name}' at #{statement.file}:#{statement.line}."
+    end
+
+    # Populate the parameters/properties/features to the type
+    populate_type_data(object, schema)
+
+    # Mark the type as public if it doesn't already have an api tag
+    object.add_tag YARD::Tags::Tag.new(:api, 'public') unless object.has_tag? :api
+
+    # Warn if a summary longer than 140 characters was provided
+    OpenvoxStrings::Yard::Handlers::Helpers.validate_summary_tag(object) if object.has_tag? :summary
+  end
+
+  private
+
+  def raise_parse_error(msg, location = statement)
+    raise YARD::Parser::UndocumentableError, "#{msg} at #{location.file}:#{location.line}."
+  end
+
+  # check that the params of the register_type call are key/value pairs.
+  def kv_arg_list?(params)
+    params.type == :list &&
+      params.children.count.positive? &&
+      params.children.first.type == :list &&
+      params.children.first.children.count.positive? &&
+      statement.parameters.children.first.children.first.type == :assoc
+  end
+
+  def extract_schema
+    raise_parse_error('Expected list of key/value pairs as argument') unless kv_arg_list?(statement.parameters)
+    hash_from_node(statement.parameters.children.first)
+  end
+
+  def value_from_node(node)
+    return nil unless node
+
+    # puts "value from #{node.inspect}"
+
+    case node.type
+    when :int
+      node.source.to_i
+    when :hash
+      hash_from_node(node)
+    when :array
+      array_from_node(node)
+    when :var_ref
+      var_ref_from_node(node)
+    when :symbol, :symbol_literal, :label, :dyna_symbol, :string_literal, :regexp_literal
+      node_as_string(node)
+    else
+      raise_parse_error("unexpected construct #{node.type}")
+    end
+  end
+
+  def array_from_node(node)
+    return nil unless node
+
+    node.children.map do |assoc|
+      value_from_node(assoc.children[0])
+    end
+  end
+
+  def hash_from_node(node)
+    return nil unless node
+
+    # puts "hash from #{node.inspect}"
+
+    kv_pairs = node.children.map do |assoc|
+      [value_from_node(assoc.children[0]), value_from_node(assoc.children[1])]
+    end
+    kv_pairs.to_h
+  end
+
+  def var_ref_from_node(node)
+    return nil unless node
+
+    # puts "var_ref from #{node.inspect}"
+
+    if node.children.first.type == :kw
+      case node.children.first.source
+      when 'false'
+        return false
+      when 'true'
+        return true
+      when 'nil'
+        return nil
+      else
+        raise_parse_error("unexpected keyword '#{node.children.first.source}'")
+      end
+    end
+    raise_parse_error('unexpected variable')
+  end
+
+  def populate_type_data(object, schema)
+    return if schema['attributes'].nil?
+
+    schema['attributes'].each do |name, definition|
+      # puts "Processing #{name}: #{definition.inspect}"
+      if %w[parameter namevar].include? definition['behaviour']
+        object.add_parameter(create_parameter(name, definition))
+      else
+        object.add_property(create_property(name, definition))
+      end
+    end
+  end
+
+  def create_parameter(name, definition)
+    parameter = OpenvoxStrings::Yard::CodeObjects::Type::Parameter.new(name, definition['desc'])
+    set_values(definition, parameter)
+    parameter
+  end
+
+  def create_property(name, definition)
+    property = OpenvoxStrings::Yard::CodeObjects::Type::Property.new(name, definition['desc'])
+    set_values(definition, property)
+    property
+  end
+
+  def set_values(definition, object)
+    object.data_type = definition['type'] if definition.key? 'type'
+    object.default = definition['default'] if definition.key? 'default'
+    object.isnamevar = definition.key?('behaviour') && definition['behaviour'] == 'namevar'
+  end
+end