openvox-strings 5.0.0

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

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require 'openvox-strings/yard/handlers/ruby/base'
+
+# Base class for all Puppet resource type handlers.
+class OpenvoxStrings::Yard::Handlers::Ruby::TypeBase < OpenvoxStrings::Yard::Handlers::Ruby::Base
+  protected
+
+  def get_type_yard_object(name)
+    # Have to guess the path - if we create the object to get the true path from the code,
+    # it also shows up in the .at call - self registering?
+    guess_path = "puppet_types::#{name}"
+    object = YARD::Registry.at(guess_path)
+
+    return object unless object.nil?
+
+    # Didn't find, create instead
+    object = OpenvoxStrings::Yard::CodeObjects::Type.new(name)
+    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 OpenvoxStrings::Yard::Util.scrub_string(docstring)
+      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 #{kind} near #{child.file}:#{child.line}." and return nil unless docstring
+
+        return OpenvoxStrings::Yard::Util.scrub_string(docstring)
+      end
+    end
+    log.warn "Missing a description for #{kind} at #{node.file}:#{node.line}."
+    nil
+  end
+
+  def create_parameter(name, node)
+    parameter = OpenvoxStrings::Yard::CodeObjects::Type::Parameter.new(name, find_docstring(node, "Puppet resource parameter '#{name}'"))
+    set_values(node, parameter)
+    parameter
+  end
+
+  def create_property(name, node)
+    property = OpenvoxStrings::Yard::CodeObjects::Type::Property.new(name, find_docstring(node, "Puppet resource property '#{name}'"))
+    set_values(node, property)
+    property
+  end
+
+  def create_check(name, node)
+    check = OpenvoxStrings::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
+
+    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
+      parameters = child.parameters(false)
+
+      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|
+          object.add(node_as_string(p) || p.source)
+        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
+      elsif method_name == 'defaultvalues' && object.name == 'ensure'
+        object.add('present')
+        object.add('absent')
+        object.default = 'present'
+      end
+    end
+
+    parameters = node.parameters(false)
+
+    if parameters.count >= 2
+      kvps = parameters[1].select { |kvp| kvp.count == 2 }
+      required_features_kvp = kvps.find { |kvp| node_as_string(kvp[0]) == 'required_features' }
+      object.required_features = node_as_string(required_features_kvp[1]) unless required_features_kvp.nil?
+    end
+
+    return unless object.is_a? OpenvoxStrings::Yard::CodeObjects::Type::Parameter
+    # Process the options for parameter base types
+    return unless parameters.count >= 2
+
+    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'
+        # rubocop:disable Performance/InefficientHashSearch
+        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'
+        # rubocop:enable Performance/InefficientHashSearch
+      end
+      break
+    end
+  end
+
+  def set_default_namevar(object)
+    return unless object.properties || object.parameters
+
+    default = nil
+    object.properties&.each do |property|
+      return nil if property.isnamevar
+
+      default = property if property.name == 'name'
+    end
+    object.parameters&.each do |parameter|
+      return nil if parameter.isnamevar
+
+      default ||= parameter if parameter.name == 'name'
+    end
+    default.isnamevar = true if default
+  end
+end

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'openvox-strings/yard/handlers/helpers'
+require 'openvox-strings/yard/handlers/ruby/type_base'
+require 'openvox-strings/yard/code_objects'
+require 'openvox-strings/yard/util'
+
+# Implements the handler for Puppet resource type newparam/newproperty/ensurable calls written in Ruby.
+class OpenvoxStrings::Yard::Handlers::Ruby::TypeExtrasHandler < OpenvoxStrings::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.'
+
+  namespace_only
+  handles method_call(:newparam)
+  handles method_call(:newproperty)
+  handles method_call(:ensurable)
+
+  process do
+    # Our entry point is a type newproperty/newparam compound statement like this:
+    #  "Puppet::Type.type(:file).newparam(:content) do"
+    # We want to
+    #  Verify the structure
+    #  Capture the three parameters (e.g. type: 'file', newproperty or newparam?, name: 'source')
+    #  Proceed with collecting data
+    #  Either decorate an existing type object or store for future type object parsing
+
+    # Only accept calls to Puppet::Type.type(<type>).newparam/.newproperty
+    # e.g. "Puppet::Type.type(:file).newparam(:content) do" would yield:
+    #   module_name:  "Puppet::Type"
+    #   method1_name: "type"
+    #   typename:     "file"
+    #   method2_name: "newparam"
+    #   propertyname: "content"
+
+    return unless (statement.count > 1) && (statement[0].children.count > 2)
+
+    module_name = statement[0].children[0].source
+    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')
+    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)
+
+    # node - what should it be here?
+    node = statement # ?? not sure... test...
+
+    if method2_name == 'newproperty'
+      typeobject.add_property(create_property(propertyname, node))
+    elsif method2_name == 'newparam'
+      typeobject.add_parameter(create_parameter(propertyname, node))
+    end
+
+    # Set the default namevar
+    set_default_namevar(typeobject)
+  end
+end

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

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'openvox-strings/yard/handlers/helpers'
+require 'openvox-strings/yard/handlers/ruby/type_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::TypeHandler < OpenvoxStrings::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.'
+
+  namespace_only
+  handles method_call(:newtype)
+
+  process do
+    # Only accept calls to Puppet::Type
+    return unless statement.count > 1
+
+    module_name = statement[0].source
+    return unless ['Puppet::Type', 'Type'].include?(module_name)
+
+    object = get_type_yard_object(get_name(statement, 'Puppet::Type.newtype'))
+
+    docstring = find_docstring(statement, "Puppet resource type '#{object.name}'")
+    register_docstring(object, docstring, nil) if docstring
+
+    # Populate the parameters/properties/features to the type
+    populate_type_data(object)
+
+    # Set the default namevar
+    set_default_namevar(object)
+
+    # 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 populate_type_data(object)
+    # 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
+
+      method_name = node.method_name.source
+      parameters = node.parameters(false)
+
+      case method_name
+      when '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))
+      when '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))
+      when '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))
+      when 'feature'
+        # Add a feature to the object
+        next unless parameters.count >= 2
+
+        name = node_as_string(parameters[0])
+        next unless name
+
+        docstring = node_as_string(parameters[1])
+        next unless docstring
+
+        object.add_feature(OpenvoxStrings::Yard::CodeObjects::Type::Feature.new(name, docstring))
+      when 'ensurable'
+        if node.block
+          property = create_property('ensure', node)
+          property.docstring = DEFAULT_ENSURABLE_DOCSTRING if property.docstring.empty?
+        else
+          property = OpenvoxStrings::Yard::CodeObjects::Type::Property.new('ensure', DEFAULT_ENSURABLE_DOCSTRING)
+          property.add('present')
+          property.add('absent')
+          property.default = 'present'
+        end
+        object.add_property property
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# The module for custom YARD handlers.
+module OpenvoxStrings::Yard::Handlers
+  # The module for custom Ruby YARD handlers.
+  module Ruby
+    require 'openvox-strings/yard/handlers/ruby/data_type_handler'
+    require 'openvox-strings/yard/handlers/ruby/type_handler'
+    require 'openvox-strings/yard/handlers/ruby/type_extras_handler'
+    require 'openvox-strings/yard/handlers/ruby/rsapi_handler'
+    require 'openvox-strings/yard/handlers/ruby/provider_handler'
+    require 'openvox-strings/yard/handlers/ruby/function_handler'
+  end
+
+  # The module for custom JSON YARD handlers.
+  module JSON
+    require 'openvox-strings/yard/handlers/json/task_handler'
+  end
+
+  # The module for custom Puppet YARD handlers.
+  module Puppet
+    require 'openvox-strings/yard/handlers/puppet/class_handler'
+    require 'openvox-strings/yard/handlers/puppet/data_type_alias_handler'
+    require 'openvox-strings/yard/handlers/puppet/defined_type_handler'
+    require 'openvox-strings/yard/handlers/puppet/function_handler'
+    require 'openvox-strings/yard/handlers/puppet/plan_handler'
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'openvox-strings/yard/parsers/json/task_statement'
+
+# Implementas a JSON parser.
+class OpenvoxStrings::Yard::Parsers::JSON::Parser < YARD::Parser::Base
+  attr_reader :file, :source
+
+  # Initializes the parser.
+  # @param [String] source The source being parsed.
+  # @param [String] filename The file name of the file being parsed.
+  # @return [void]
+  def initialize(source, filename) # rubocop:disable Lint/MissingSuper
+    @file = filename
+    @source = source
+    @statements = []
+  end
+
+  def enumerator
+    @statements
+  end
+
+  # Parses the source
+  # @return [void]
+  def parse
+    begin
+      json = JSON.parse(source)
+      # 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(OpenvoxStrings::Yard::Parsers::JSON::TaskStatement.new(json, @source, @file)) unless json.empty?
+    rescue StandardError
+      log.error "Failed to parse #{@file}: "
+      @statements = []
+    end
+    @statements.freeze
+    self
+  end
+end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module OpenvoxStrings::Yard::Parsers::JSON
+  # Represents the Puppet Task statement.
+  class TaskStatement
+    attr_reader :line, :comments_range, :json, :file, :source, :docstring
+
+    def initialize(json, source, file)
+      @file = file
+      @source = source
+      @json = json
+      @line = 0
+      @comments_range = nil
+      @docstring = YARD::Docstring.new(@json['description'])
+    end
+
+    def parameters
+      json['parameters'] || {}
+    end
+
+    def comments_hash_flag
+      false
+    end
+
+    def show
+      ''
+    end
+
+    def comments
+      docstring.all
+    end
+
+    def name
+      File.basename(@file).gsub('.json', '') || ''
+    end
+  end
+end

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

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require 'puppet'
+require 'puppet/pops'
+require 'openvox-strings/yard/parsers/puppet/statement'
+
+# Implements the Puppet language parser.
+class OpenvoxStrings::Yard::Parsers::Puppet::Parser < YARD::Parser::Base
+  attr_reader :file, :source
+
+  # Initializes the parser.
+  # @param [String] source The source being parsed.
+  # @param [String] filename The file name of the file being parsed.
+  # @return [void]
+  def initialize(source, filename) # rubocop:disable Lint/MissingSuper
+    @source = source
+    @file = filename
+    @visitor = ::Puppet::Pops::Visitor.new(self, 'transform')
+  end
+
+  # Parses the source.
+  # @return [void]
+  def parse
+    begin
+      Puppet[:tasks] = true if Puppet.settings.include?(:tasks)
+      @statements ||= (@visitor.visit(::Puppet::Pops::Parser::Parser.new.parse_string(source)) || []).compact
+    rescue ::Puppet::ParseError => e
+      log.error "Failed to parse #{@file}: #{e.message}"
+      @statements = []
+    end
+    @statements.freeze
+    self
+  end
+
+  # Gets an enumerator for the statements that were parsed.
+  # @return Returns an enumerator for the statements that were parsed.
+  def enumerator
+    @statements
+  end
+
+  private
+
+  # TODO: Fix the rubocop violations in this file between the following rubocop:disable/enable lines
+  # rubocop:disable Naming/MethodName
+  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)
+    @visitor.visit(o.current)
+  end
+
+  def transform_HostClassDefinition(o)
+    statement = OpenvoxStrings::Yard::Parsers::Puppet::ClassStatement.new(o, @file)
+    statement.extract_docstring(@lines)
+    statement
+  end
+
+  def transform_ResourceTypeDefinition(o)
+    statement = OpenvoxStrings::Yard::Parsers::Puppet::DefinedTypeStatement.new(o, @file)
+    statement.extract_docstring(@lines)
+    statement
+  end
+
+  def transform_FunctionDefinition(o)
+    statement = OpenvoxStrings::Yard::Parsers::Puppet::FunctionStatement.new(o, @file)
+    statement.extract_docstring(@lines)
+    statement
+  end
+
+  def transform_PlanDefinition(o)
+    statement = OpenvoxStrings::Yard::Parsers::Puppet::PlanStatement.new(o, @file)
+    statement.extract_docstring(@lines)
+    statement
+  end
+
+  def transform_TypeAlias(o)
+    statement = OpenvoxStrings::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
+  # rubocop:enable Naming/MethodName
+end

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

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require 'puppet'
+require 'puppet/pops'
+
+module OpenvoxStrings::Yard::Parsers::Puppet
+  # Represents the base Puppet language statement.
+  class Statement
+    # The pattern for parsing docstring comments.
+    COMMENT_REGEX = /^\s*#+\s?/
+
+    attr_reader :source, :file, :line, :docstring, :comments_range
+
+    # Initializes the Puppet language statement.
+    # @param object The Puppet parser model object for the statement.
+    # @param [String] file The file name of the file containing the statement.
+    def initialize(object, file)
+      @file = file
+
+      @source = OpenvoxStrings::Yard::Util.ast_to_text(object)
+      @line = object.line
+      @comments_range = nil
+    end
+
+    # Extracts the docstring for the statement given the source lines.
+    # @param [Array<String>] lines The source lines for the file containing the statement.
+    # @return [void]
+    def extract_docstring(lines)
+      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)
+      @docstring = YARD::Docstring.new(comment.reverse.join("\n"))
+    end
+
+    # Shows the first line context for the statement.
+    # @return [String] Returns the first line context for the statement.
+    def show
+      "\t#{@line}: #{first_line}"
+    end
+
+    # Gets the full comments of the statement.
+    # @return [String] Returns the full comments of the statement.
+    def comments
+      @docstring.all
+    end
+
+    # Determines if the comments have hash flag.
+    # @return [Boolean] Returns true if the comments have a hash flag or false if not.
+    def comments_hash_flag
+      false
+    end
+
+    private
+
+    def first_line
+      @source.split(/\r?\n/).first.strip
+    end
+  end
+
+  # Implements a parameterized statement (a statement that takes parameters).
+  class ParameterizedStatement < Statement
+    # Implements a parameter for a parameterized statement.
+    class Parameter
+      attr_reader :name, :type, :value
+
+      # Initializes the parameter.
+      # @param [Puppet::Pops::Model::Parameter] parameter The parameter model object.
+      def initialize(parameter)
+        @name = parameter.name
+        # Take the exact text for the type expression
+        @type = OpenvoxStrings::Yard::Util.ast_to_text(parameter.type_expr) if parameter.type_expr
+        # Take the exact text for the default value expression
+        return unless parameter.value
+
+        @value = OpenvoxStrings::Yard::Util.ast_to_text(parameter.value)
+      end
+    end
+
+    attr_reader :parameters
+
+    # Initializes the parameterized statement.
+    # @param object The Puppet parser model object that has parameters.
+    # @param [String] file The file containing the statement.
+    def initialize(object, file)
+      super
+      @parameters = object.parameters.map { |parameter| Parameter.new(parameter) }
+    end
+  end
+
+  # Implements the Puppet class statement.
+  class ClassStatement < ParameterizedStatement
+    attr_reader :name, :parent_class
+
+    # Initializes the Puppet class statement.
+    # @param [Puppet::Pops::Model::HostClassDefinition] object The model object for the class statement.
+    # @param [String] file The file containing the statement.
+    def initialize(object, file)
+      super
+      @name = object.name
+      @parent_class = object.parent_class
+    end
+  end
+
+  # Implements the Puppet defined type statement.
+  class DefinedTypeStatement < ParameterizedStatement
+    attr_reader :name
+
+    # Initializes the Puppet defined type statement.
+    # @param [Puppet::Pops::Model::ResourceTypeDefinition] object The model object for the defined type statement.
+    # @param [String] file The file containing the statement.
+    def initialize(object, file)
+      super
+      @name = object.name
+    end
+  end
+
+  # Implements the Puppet function statement.
+  class FunctionStatement < ParameterizedStatement
+    attr_reader :name, :type
+
+    # Initializes the Puppet function statement.
+    # @param [Puppet::Pops::Model::FunctionDefinition] object The model object for the function statement.
+    # @param [String] file The file containing the statement.
+    def initialize(object, file)
+      super
+      @name = object.name
+      return unless object.respond_to? :return_type
+
+      type = object.return_type
+      return unless type
+
+      @type = OpenvoxStrings::Yard::Util.ast_to_text(type).gsub('>> ', '')
+    end
+  end
+
+  # Implements the Puppet plan statement.
+  class PlanStatement < ParameterizedStatement
+    attr_reader :name
+
+    # Initializes the Puppet plan statement.
+    # @param [Puppet::Pops::Model::PlanDefinition] object The model object for the plan statement.
+    # @param [String] file The file containing the statement.
+    def initialize(object, file)
+      super
+      @name = object.name
+    end
+  end
+
+  # Implements the Puppet data type alias statement.
+  class DataTypeAliasStatement < Statement
+    attr_reader :name, :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
+
+      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 = +"#{OpenvoxStrings::Yard::Util.ast_to_text(type_expr.left_expr)}[" # alias_of should be mutable so we add a + to the string.
+        @alias_of << type_expr.keys.map { |key| OpenvoxStrings::Yard::Util.ast_to_text(key) }.join(', ')
+        @alias_of << ']'
+      else
+        @alias_of = OpenvoxStrings::Yard::Util.ast_to_text(type_expr)
+      end
+      @name = object.name
+    end
+  end
+end