puppet-strings 1.2.1 → 2.0.0

data/lib/puppet-strings/yard/code_objects/task.rb

@@ -0,0 +1,70 @@
+require 'puppet-strings/yard/code_objects/group'
+
+# Implements the group for Puppet tasks.
+class PuppetStrings::Yard::CodeObjects::Tasks < PuppetStrings::Yard::CodeObjects::Group
+  # Gets the singleton instance of the group.
+  # @return Returns the singleton instance of the group.
+  def self.instance
+    super(:puppet_tasks)
+  end
+
+  # Gets the display name of the group.
+  # @param [Boolean] prefix whether to show a prefix.
+  # @return [String] Returns the display name of the group.
+  def name(prefix = false)
+    'Puppet Tasks'
+  end
+end
+
+# Implements the Puppet task code object.
+class PuppetStrings::Yard::CodeObjects::Task < PuppetStrings::Yard::CodeObjects::Base
+  attr_reader :statement
+
+  # Initializes a JSON task code object.
+  # @param statement TaskStatement object
+  # @return [void]
+  def initialize(statement)
+    @name = statement.name
+    @statement = statement
+    super(PuppetStrings::Yard::CodeObjects::Tasks.instance, name)
+  end
+
+  # Gets the type of the code object.
+  # @return Returns the type of the code object.
+  def type
+    :puppet_task
+  end
+
+  # Gets the source of the code object.
+  # @return Returns the source of the code object.
+  def source
+    @statement.source
+  end
+
+  def parameters
+    parameters = []
+    statement.json['parameters'].each do |name,props|
+      parameters.push({ name: name.to_s,
+                        tag_name: 'param',
+                        text: props['description'] || "",
+                        types: [props['type']] || "" })
+    end
+    parameters
+  end
+
+  # Converts the code object to a hash representation.
+  # @return [Hash] Returns a hash representation of the code object.
+  def to_hash
+    { name: name.to_s,
+      file: statement.file,
+      line: statement.line,
+      docstring: {
+        text: statement.docstring,
+        tags: parameters
+      },
+      source: statement.source,
+      supports_noop: statement.json['supports_noop'] || false,
+      input_method: statement.json['input_method']
+    }
+  end
+end

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

@@ -8,10 +8,16 @@ module PuppetStrings::Yard::Handlers
     require 'puppet-strings/yard/handlers/ruby/function_handler'
   end
 
+  # The module for custom JSON YARD handlers.
+  module JSON
+    require 'puppet-strings/yard/handlers/json/task_handler'
+  end
+
   # The module for custom Puppet YARD handlers.
   module Puppet
     require 'puppet-strings/yard/handlers/puppet/class_handler'
     require 'puppet-strings/yard/handlers/puppet/defined_type_handler'
     require 'puppet-strings/yard/handlers/puppet/function_handler'
+    require 'puppet-strings/yard/handlers/puppet/plan_handler'
   end
 end

data/lib/puppet-strings/yard/handlers/json/base.rb

@@ -0,0 +1,5 @@
+class PuppetStrings::Yard::Handlers::JSON::Base < YARD::Handlers::Base
+  def self.handles?(statement)
+    handlers.any? {|handler| statement.is_a?(handler)}
+  end
+end

data/lib/puppet-strings/yard/handlers/json/task_handler.rb

@@ -0,0 +1,31 @@
+require 'puppet-strings/yard/handlers/json/base'
+require 'puppet-strings/yard/parsers'
+require 'puppet-strings/yard/parsers/json/parser'
+
+class PuppetStrings::Yard::Handlers::JSON::TaskHandler < PuppetStrings::Yard::Handlers::JSON::Base
+  handles PuppetStrings::Yard::Parsers::JSON::TaskStatement
+  namespace_only
+
+  process do
+    object = PuppetStrings::Yard::CodeObjects::Task.new(statement)
+    register object
+
+    @kind = "Puppet Task #{object.name}."
+    @statement = statement
+
+    validate_description
+    validate_params
+  end
+
+  def validate_description
+    log.warn "Missing a description for #{@kind}." if @statement.docstring.empty?
+  end
+
+  def validate_params
+    unless @statement.parameters.empty?
+      @statement.parameters.each do |param, val|
+        log.warn "Missing description for param '#{param}' in #{@kind}" if val['description'].nil?
+      end
+    end
+  end
+end

data/lib/puppet-strings/yard/handlers/puppet/base.rb

@@ -17,7 +17,7 @@ class PuppetStrings::Yard::Handlers::Puppet::Base < YARD::Handlers::Base
     tags = object.tags(:param)
     tags.each do |tag|
       next if statement.parameters.find { |p| tag.name == p.name }
-      log.warn "The @param tag for parameter '#{tag.name}' has no matching parameter at #{statement.file}:#{statement.line}."
+      log.warn "The @param tag for parameter '#{tag.name}' has no matching parameter at #{statement.file}:#{statement.line}." unless tag.name == 'name' || tag.name == 'title'
     end
 
     # Assign the types for the parameter

data/lib/puppet-strings/yard/handlers/puppet/class_handler.rb

@@ -13,7 +13,7 @@ class PuppetStrings::Yard::Handlers::Puppet::ClassHandler < PuppetStrings::Yard:
     register object
 
     # Log a warning if missing documentation
-    log.warn "Missing documentation for Puppet class '#{object.name}' at #{statement.file}:#{statement.line}." if object.docstring.empty?
+    log.warn "Missing documentation for Puppet class '#{object.name}' at #{statement.file}:#{statement.line}." if object.docstring.empty? && object.tags.empty?
 
     # Set the parameter types
     set_parameter_types(object)

data/lib/puppet-strings/yard/handlers/puppet/defined_type_handler.rb

@@ -13,7 +13,7 @@ class PuppetStrings::Yard::Handlers::Puppet::DefinedTypeHandler < PuppetStrings:
     register object
 
     # Log a warning if missing documentation
-    log.warn "Missing documentation for Puppet defined type '#{object.name}' at #{statement.file}:#{statement.line}." if object.docstring.empty?
+    log.warn "Missing documentation for Puppet defined type '#{object.name}' at #{statement.file}:#{statement.line}." if object.docstring.empty? && object.tags.empty?
 
     # Set the parameter types
     set_parameter_types(object)

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

@@ -15,7 +15,7 @@ class PuppetStrings::Yard::Handlers::Puppet::FunctionHandler < PuppetStrings::Ya
     register object
 
     # Log a warning if missing documentation
-    log.warn "Missing documentation for Puppet function '#{object.name}' at #{statement.file}:#{statement.line}." if object.docstring.empty?
+    log.warn "Missing documentation for Puppet function '#{object.name}' at #{statement.file}:#{statement.line}." if object.docstring.empty? && object.tags.empty?
 
     # Set the parameter tag types
     set_parameter_types(object)

data/lib/puppet-strings/yard/handlers/puppet/plan_handler.rb

@@ -0,0 +1,27 @@
+require 'puppet-strings/yard/handlers/helpers'
+require 'puppet-strings/yard/handlers/puppet/base'
+require 'puppet-strings/yard/parsers'
+require 'puppet-strings/yard/code_objects'
+
+# Implements the handler for Puppet classes.
+class PuppetStrings::Yard::Handlers::Puppet::PlanHandler < PuppetStrings::Yard::Handlers::Puppet::Base
+  handles PuppetStrings::Yard::Parsers::Puppet::PlanStatement
+
+  process do
+    # Register the object
+    object = PuppetStrings::Yard::CodeObjects::Plan.new(statement)
+    register object
+
+    # Log a warning if missing documentation
+    log.warn "Missing documentation for Puppet plan '#{object.name}' at #{statement.file}:#{statement.line}." if object.docstring.empty? && object.tags.empty?
+
+    # Set the parameter types
+    set_parameter_types(object)
+
+    # Mark the class 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
+    PuppetStrings::Yard::Handlers::Helpers.validate_summary_tag(object) if object.has_tag? :summary
+  end
+end

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

@@ -77,7 +77,7 @@ class PuppetStrings::Yard::Handlers::Ruby::FunctionHandler < PuppetStrings::Yard
   end
 
   def add_tags(object)
-    log.warn "Missing documentation for Puppet function '#{object.name}' at #{statement.file}:#{statement.line}." if object.docstring.empty?
+    log.warn "Missing documentation for Puppet function '#{object.name}' at #{statement.file}:#{statement.line}." if object.docstring.empty? && object.tags.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." unless object.tags(:param).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." unless object.tags(:return).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." unless object.tags(:overload).empty?
@@ -139,6 +139,9 @@ class PuppetStrings::Yard::Handlers::Ruby::FunctionHandler < PuppetStrings::Yard
       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

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

@@ -24,7 +24,7 @@ class PuppetStrings::Yard::Handlers::Ruby::RsapiHandler < PuppetStrings::Yard::H
     object = PuppetStrings::Yard::CodeObjects::Type.new(schema['name'])
     register object
 
-    docstring = schema['desc'] || ""
+    docstring = schema['docs']
     if docstring
       register_docstring(object, PuppetStrings::Yard::Util.scrub_string(docstring.to_s), nil)
     else
@@ -44,7 +44,7 @@ class PuppetStrings::Yard::Handlers::Ruby::RsapiHandler < PuppetStrings::Yard::H
   private
 
   def raise_parse_error(msg, location = statement)
-    raise YARD::Parser::UndocumentableError, "#{msg} at #{location.file}:#{location.line}." if parameters.empty?
+    raise YARD::Parser::UndocumentableError, "#{msg} at #{location.file}:#{location.line}."
   end
 
   # check that the params of the register_type call are key/value pairs.
@@ -67,6 +67,8 @@ class PuppetStrings::Yard::Handlers::Ruby::RsapiHandler < PuppetStrings::Yard::H
       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
@@ -76,6 +78,14 @@ class PuppetStrings::Yard::Handlers::Ruby::RsapiHandler < PuppetStrings::Yard::H
     end
   end
 
+  def array_from_node(node)
+    return nil unless node
+
+    arr = node.children.collect do |assoc|
+      value_from_node(assoc.children[0])
+    end
+  end
+
   def hash_from_node(node)
     return nil unless node
 

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

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

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

@@ -0,0 +1,33 @@
+require 'puppet-strings/yard/parsers/json/task_statement'
+
+class PuppetStrings::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)
+    @file = filename
+    @source = source
+    @statements = []
+  end
+
+  def enumerator
+    @statements
+  end
+
+  # Parses the source
+  # @return [void]
+  def parse
+    begin
+      json = JSON.parse(source)
+      @statements.push(PuppetStrings::Yard::Parsers::JSON::TaskStatement.new(json, @source, @file))
+    rescue
+      log.error "Failed to parse #{@file}: "
+      @statements = []
+    end
+    @statements.freeze
+    self
+  end
+end

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

@@ -0,0 +1,35 @@
+module PuppetStrings::Yard::Parsers::JSON
+  # Represents the Puppet Task statement.
+  class TaskStatement
+    attr_reader :line, :comments, :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/puppet-strings/yard/parsers/puppet/parser.rb

@@ -20,6 +20,11 @@ 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
+      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}"
@@ -64,6 +69,12 @@ class PuppetStrings::Yard::Parsers::Puppet::Parser < YARD::Parser::Base
     statement
   end
 
+  def transform_PlanDefinition(o)
+    statement = PuppetStrings::Yard::Parsers::Puppet::PlanStatement.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

@@ -151,4 +151,18 @@ module PuppetStrings::Yard::Parsers::Puppet
       end
     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(object, file)
+      @name = object.name
+    end
+  end
+
 end

data/lib/puppet-strings/yard/templates/default/fulldoc/html/full_list_puppet_plan.erb

@@ -0,0 +1,9 @@
+<% even = false  %>
+<% @items.each do |item| %>
+    <li id="object_<%=item.path%>" class="<%= even ? 'even' : 'odd' %>">
+      <div class="item">
+        <%= linkify item, h(item.name(true)) %>
+      </div>
+    </li>
+    <% even = !even %>
+<% end %>

data/lib/puppet-strings/yard/templates/default/fulldoc/html/full_list_puppet_task.erb

@@ -0,0 +1,9 @@
+<% even = false  %>
+<% @items.each do |item| %>
+    <li id="object_<%=item.path%>" class="<%= even ? 'even' : 'odd' %>">
+      <div class="item">
+        <%= linkify item, h(item.name(true)) %>
+      </div>
+    </li>
+    <% even = !even %>
+<% end %>

data/lib/puppet-strings/yard/templates/default/fulldoc/html/setup.rb

@@ -62,3 +62,21 @@ def generate_class_list
   @list_type = 'class'
   generate_list_contents
 end
+
+# Generates the searchable Puppet Task list.
+# @return [void]
+def generate_puppet_task_list
+  @items = Registry.all(:puppet_task).sort_by {|t| t.name.to_s }
+  @list_title = 'Puppet Task List'
+  @list_type = 'puppet_task'
+  generate_list_contents
+end
+
+# Generates the searchable Puppet Plan list.
+# @return [void]
+def generate_puppet_plan_list
+  @items = Registry.all(:puppet_plan).sort_by {|t| t.name.to_s }
+  @list_title = 'Puppet Plan List'
+  @list_type = 'puppet_plan'
+  generate_list_contents
+end

data/lib/puppet-strings/yard/templates/default/layout/html/setup.rb

@@ -4,7 +4,7 @@ def init
   case object
   when '_index.html'
     @page_title = options.title
-    sections :layout, [:index, [:listing, [:classes, :defined_types, :types, :providers, :functions, :files, :objects]]]
+    sections :layout, [:index, [:listing, [:classes, :defined_types, :types, :providers, :functions, :tasks, :plans, :files, :objects]]]
   else
     super
   end
@@ -46,11 +46,25 @@ def layout
     @nav_url = url_for_list('puppet_function')
     @page_title = "Puppet Function: #{object.name} (#{object.function_type})"
     @path = object.path
+  when PuppetStrings::Yard::CodeObjects::Task
+    @nav_url = url_for_list('puppet_task')
+    @page_title = "Puppet Task: #{object.name}"
+    @path = object.path
+  when PuppetStrings::Yard::CodeObjects::Plan
+    @nav_url = url_for_list('puppet_plan')
+    @page_title = "Puppet Plan: #{object.name}"
+    @path = object.path
   else
     @path = object.path
   end
 
-  erb(:layout)
+  final_layout = erb(:layout)
+
+  if @file && @file.name == 'README'
+    PuppetStrings::Yard::Util.github_to_yard_links(final_layout)
+  end
+
+  final_layout
 end
 
 # Creates the dynamic menu lists.
@@ -82,6 +96,16 @@ def create_menu_lists
       title: 'Puppet Functions',
       search_title: 'Puppet Functions'
     },
+    {
+      type: 'puppet_task',
+      title: 'Puppet Tasks',
+      search_totle: 'Puppet Tasks'
+    },
+    {
+      type: 'puppet_plan',
+      title: 'Puppet Plans',
+      search_totle: 'Puppet Plans'
+    },
     {
       type: 'class',
       title: 'Ruby Classes',
@@ -163,6 +187,22 @@ def functions
   erb(:objects)
 end
 
+# Renders the tasks section.
+# @return [String] Returns the rendered section.
+def tasks
+  @title = 'Puppet Task Listing A-Z'
+  @objects_by_letter = objects_by_letter(:puppet_task)
+  erb(:objects)
+end
+
+# Renders the plans section.
+# @return [String] Returns the rendered section.
+def plans
+  @title = 'Puppet Plan Listing A-Z'
+  @objects_by_letter = objects_by_letter(:puppet_plan)
+  erb(:objects)
+end
+
 # Renders the objects section.
 # @return [String] Returns the rendered section.
 def objects