puppet-strings 0.4.0 → 0.99.0

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

@@ -0,0 +1,194 @@
+require 'puppet-strings/yard/handlers/ruby/base'
+require 'puppet-strings/yard/code_objects'
+require 'puppet/util'
+
+# Implements the handler for Puppet resource types written in Ruby.
+class PuppetStrings::Yard::Handlers::Ruby::TypeHandler < 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
+
+  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 module_name == 'Puppet::Type' || module_name == 'Type'
+
+    object = PuppetStrings::Yard::CodeObjects::Type.new(get_name)
+    register object
+
+    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
+  end
+
+  private
+  def get_name
+    parameters = statement.parameters(false)
+    raise YARD::Parser::UndocumentableError, "Expected at least one parameter to Puppet::Type.newtype at #{statement.file}:#{statement.line}." if parameters.empty?
+    name = node_as_string(parameters.first)
+    raise YARD::Parser::UndocumentableError, "Expected a symbol or string literal for first parameter but found '#{parameters.first.type}' at #{statement.file}:#{statement.line}." unless name
+    name
+  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 Puppet::Util::Docs.scrub(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 &&
+                    (child.method_name.source == 'desc' || child.method_name.source == 'doc=') &&
+                    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 Puppet::Util::Docs.scrub(docstring)
+      end
+    end
+    log.warn "Missing a description for #{kind} at #{node.file}:#{node.line}."
+    nil
+  end
+
+  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)
+
+      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 == '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(PuppetStrings::Yard::CodeObjects::Type::Feature.new(name, docstring))
+      elsif method_name == 'ensurable'
+        if node.block
+          property = create_property('ensure', node)
+          property.docstring = DEFAULT_ENSURABLE_DOCSTRING if property.docstring.empty?
+        else
+          property = PuppetStrings::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
+
+  def create_parameter(name, node)
+    parameter = PuppetStrings::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 = PuppetStrings::Yard::CodeObjects::Type::Property.new(name, find_docstring(node, "Puppet resource property '#{name}'"))
+    set_values(node, property)
+    property
+  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
+    if object.is_a? PuppetStrings::Yard::CodeObjects::Type::Parameter
+      # Process the options for parameter base types
+      parameters = node.parameters(false)
+      if 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'
+            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'
+          end
+          break
+        end
+      end
+    end
+  end
+
+  def set_default_namevar(object)
+    return unless object.properties || object.parameters
+    default = nil
+    if object.properties
+      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|
+        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/parsers.rb

@@ -0,0 +1,7 @@
+# The module for custom YARD parsers.
+module PuppetStrings::Yard::Parsers
+  # The module for custom YARD parsers for the Puppet language.
+  module Puppet
+    require 'puppet-strings/yard/parsers/puppet/parser'
+  end
+end

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

@@ -0,0 +1,70 @@
+require 'puppet'
+require 'puppet/pops'
+require 'puppet-strings/yard/parsers/puppet/statement'
+
+# Implements the Puppet language parser.
+class PuppetStrings::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)
+    @source = source
+    @file = filename
+    @visitor = ::Puppet::Pops::Visitor.new(self, 'transform')
+  end
+
+  # Parses the source.
+  # @return [void]
+  def parse
+    begin
+      @statements ||= (@visitor.visit(::Puppet::Pops::Parser::Parser.new.parse_string(source)) || []).compact
+    rescue ::Puppet::ParseError => ex
+      log.error "Failed to parse #{@file}: #{ex.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
+  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 = PuppetStrings::Yard::Parsers::Puppet::ClassStatement.new(o, @file)
+    statement.extract_docstring(@lines)
+    statement
+  end
+
+  def transform_ResourceTypeDefinition(o)
+    statement = PuppetStrings::Yard::Parsers::Puppet::DefinedTypeStatement.new(o, @file)
+    statement.extract_docstring(@lines)
+    statement
+  end
+
+  def transform_FunctionDefinition(o)
+    statement = PuppetStrings::Yard::Parsers::Puppet::FunctionStatement.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
+end

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

@@ -0,0 +1,146 @@
+require 'puppet'
+require 'puppet/pops'
+
+module PuppetStrings::Yard::Parsers::Puppet
+  # Represents the base Puppet language statement.
+  class Statement
+    # The pattern for parsing docstring comments.
+    COMMENT_REGEX = /^\s*#+\s?/
+
+    attr_reader :source
+    attr_reader :file
+    attr_reader :line
+    attr_reader :docstring
+    attr_reader :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
+
+      adapter = ::Puppet::Pops::Adapters::SourcePosAdapter.adapt(object)
+      @source = adapter.extract_text
+      @line = adapter.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
+      attr_reader :type
+      attr_reader :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
+        if parameter.type_expr
+          adapter = ::Puppet::Pops::Adapters::SourcePosAdapter.adapt(parameter.type_expr)
+          @type = adapter.extract_text
+        end
+        # Take the exact text for the default value expression
+        if parameter.value
+          adapter = ::Puppet::Pops::Adapters::SourcePosAdapter.adapt(parameter.value)
+          @value = adapter.extract_text
+        end
+      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(object, file)
+      @parameters = object.parameters.map { |parameter| Parameter.new(parameter) }
+    end
+  end
+
+  # Implements the Puppet class statement.
+  class ClassStatement < ParameterizedStatement
+    attr_reader :name
+    attr_reader :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(object, file)
+      @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(object, file)
+      @name = object.name
+    end
+  end
+
+  # Implements the Puppet function statement.
+  class FunctionStatement < ParameterizedStatement
+    attr_reader :name
+
+    # 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(object, file)
+      @name = object.name
+    end
+  end
+end

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

@@ -0,0 +1,6 @@
+# The module for custom YARD tags.
+module PuppetStrings::Yard::Tags
+  require 'puppet-strings/yard/tags/parameter_directive'
+  require 'puppet-strings/yard/tags/property_directive'
+  require 'puppet-strings/yard/tags/overload_tag'
+end

data/lib/puppet-strings/yard/tags/overload_tag.rb

@@ -0,0 +1,109 @@
+# Implements an overload tag for Puppet functions
+#
+# This differs from Yard's overload tag in that the signatures are formatted according to Puppet language rules.
+class PuppetStrings::Yard::Tags::OverloadTag < YARD::Tags::Tag
+  attr_reader :parameters, :docstring
+
+  # Initializes the overload tag.
+  # @param [String, Symbol] name The name of the function being overloaded.
+  # @param [String] docstring The docstring for the overload.
+  # @return [void]
+  def initialize(name, docstring)
+    super(:overload, nil)
+    @name = name.to_s
+    @parameters = []
+    @docstring = YARD::Docstring.new(docstring)
+  end
+
+  # Gets the signature of the overload.
+  # @return [String] Returns the signature of the overload.
+  def signature
+    tags = self.tags(:param)
+    args = @parameters.map do |parameter|
+      name, default = parameter
+      tag = tags.find { |tag| tag.name == name } if tags
+      type = tag && tag.types ? "#{tag.type} " : 'Any '
+      prefix = "#{name[0]}" if name.start_with?('*', '&')
+      name = name[1..-1] if prefix
+      default = " = #{default}" if default
+      "#{type}#{prefix}$#{name}#{default}"
+    end.join(', ')
+    @name + '(' + args + ')'
+  end
+
+  # Adds a tag to the overload's docstring.
+  # @param [YARD::Tag] tag The tag to add to the overload's docstring.
+  # @return [void]
+  def add_tag(tag)
+    @docstring.add_tag(tag)
+  end
+
+  # Gets the first tag of the given name.
+  # @param [String, Symbol] name The name of the tag.
+  # @return [YARD::Tag] Returns the first tag if found or nil if not found.
+  def tag(name)
+    @docstring.tag(name)
+  end
+
+  # Gets all tags or tags of a given name.
+  # @param [String, Symbol] name The name of the tag to get or nil for all tags.
+  # @return [Array<Yard::Tag>] Returns an array of tags.
+  def tags(name = nil)
+    @docstring.tags(name)
+  end
+
+  # Determines if a tag with the given name is present.
+  # @param [String, Symbol] name The tag name.
+  # @return [Boolean] Returns true if there is at least one tag with the given name or false if not.
+  def has_tag?(name)
+    @docstring.has_tag?(name)
+  end
+
+  # Sets the object associated with this tag.
+  # @param [Object] value The object to associate with this tag.
+  # @return [void]
+  def object=(value)
+    super(value)
+    @docstring.object = value
+    @docstring.tags.each {|tag| tag.object = value }
+  end
+
+  # Responsible for forwarding method calls to the associated object.
+  # @param [Symbol] method_name The method being invoked.
+  # @param [Array] args The args passed to the method.
+  # @param block The block passed to the method.
+  # @return Returns what the method call on the object would return.
+  def method_missing(method_name, *args, &block)
+    return object.send(method_name, *args, &block) if object.respond_to? method_name
+    super
+  end
+
+  # Determines if the associated object responds to the give missing method name.
+  # @param [Symbol, String] method_name The name of the method to check.
+  # @param [Boolean] include_all True to include all methods in the check or false for only public methods.
+  # @return [Boolean] Returns true if the object responds to the method or false if not.
+  def respond_to_missing?(method_name, include_all = false)
+    object.respond_to?(method_name, include_all) || super
+  end
+
+  # Gets the type of the object associated with this tag.
+  # @return [Symbol] Returns the type of the object associated with this tag.
+  def type
+    object.type
+  end
+
+  # Converts the overload tag to a hash representation.
+  # @return [Hash] Returns a hash representation of the overload.
+  def to_hash
+    hash = {}
+    hash[:tag_name] = tag_name
+    hash[:text] = text if text
+    hash[:signature] = signature
+    hash[:docstring] = PuppetStrings::Json.docstring_to_hash(docstring) if !docstring.empty?
+    defaults = Hash[*parameters.select{ |p| !p[1].nil? }.flatten]
+    hash[:defaults] = defaults unless defaults.empty?
+    hash[:types] = types if types
+    hash[:name] = name if name
+    hash
+  end
+end