openvox-strings 5.0.0

data/lib/openvox-strings/yard/code_objects/function.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'openvox-strings/yard/code_objects/group'
+
+# Implements the group for Puppet functions.
+class OpenvoxStrings::Yard::CodeObjects::Functions < OpenvoxStrings::Yard::CodeObjects::Group
+  # Gets the singleton instance of the group.
+  # @param [Symbol] type The function type to get the group for.
+  # @return Returns the singleton instance of the group.
+  def self.instance(type)
+    super(:"puppet_functions_#{type}")
+  end
+
+  # Gets the display name of the group.
+  # @param [Boolean] prefix whether to show a prefix. Ignored for Puppet group namespaces.
+  # @return [String] Returns the display name of the group.
+  def name(_prefix = false)
+    'Puppet Functions'
+  end
+end
+
+# Implements the Puppet function code object.
+class OpenvoxStrings::Yard::CodeObjects::Function < OpenvoxStrings::Yard::CodeObjects::Base
+  # Identifier for 3.x Ruby API functions
+  RUBY_3X = :ruby3x
+  # Identifier for 4.x Ruby API functions
+  RUBY_4X = :ruby4x
+  # Identifier for Puppet language functions
+  PUPPET = :puppet
+
+  attr_accessor :parameters
+
+  # Initializes a Puppet function code object.
+  # @param [String] name The name of the function.
+  # @param [Symbol] function_type The type of function (e.g. :ruby3x, :ruby4x, :puppet)
+  # @return [void]
+  def initialize(name, function_type)
+    super(OpenvoxStrings::Yard::CodeObjects::Functions.instance(function_type), name)
+    @parameters = []
+    @function_type = function_type
+  end
+
+  # Gets the type of the code object.
+  # @return Returns the type of the code object.
+  def type
+    :puppet_function
+  end
+
+  # Gets the function type display string.
+  # @return Returns the function type display string.
+  def function_type
+    case @function_type
+    when RUBY_3X
+      'Ruby 3.x API'
+    when RUBY_4X
+      'Ruby 4.x API'
+    else
+      'Puppet Language'
+    end
+  end
+
+  # Gets the Puppet signature of the function (single overload only).
+  # @return [String] Returns the Puppet signature of the function.
+  def signature
+    return '' if has_tag? :overload
+
+    tags = self.tags(:param)
+    args = @parameters.map do |parameter|
+      name, default = parameter
+      tag = tags.find { |t| t.name == name } if tags
+      type = tag&.types ? "#{tag.type} " : 'Any '
+      prefix = name[0].to_s if name.start_with?('*', '&')
+      name = name[1..] if prefix
+      default = " = #{default}" if default
+      "#{type}#{prefix}$#{name}#{default}"
+    end.join(', ')
+    "#{@name}(#{args})"
+  end
+
+  # Converts the code object to a hash representation.
+  # @return [Hash] Returns a hash representation of the code object.
+  def to_hash
+    hash = {}
+
+    hash[:name] = name
+    hash[:file] = file
+    hash[:line] = line
+    hash[:type] = @function_type.to_s
+    hash[:signatures] = []
+
+    if has_tag? :overload
+      # loop over overloads and append onto the signatures array
+      tags(:overload).each do |o|
+        hash[:signatures] << { signature: o.signature, docstring: OpenvoxStrings::Yard::Util.docstring_to_hash(o.docstring, %i[param option enum return example]) }
+      end
+    else
+      hash[:signatures] << { signature: signature, docstring: OpenvoxStrings::Yard::Util.docstring_to_hash(docstring, %i[param option enum return example]) }
+    end
+
+    hash[:docstring] = OpenvoxStrings::Yard::Util.docstring_to_hash(docstring)
+    defaults = Hash[*parameters.reject { |p| p[1].nil? }.flatten]
+    hash[:defaults] = defaults unless defaults.nil? || defaults.empty?
+    hash[:source] = source unless source.nil? || source.empty?
+    hash
+  end
+end

data/lib/openvox-strings/yard/code_objects/group.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'openvox-strings/yard/code_objects/base'
+
+# Implements the base class for "groups".
+#
+# A group behaves like a YARD namespace object, but displays differently in the HTML output.
+class OpenvoxStrings::Yard::CodeObjects::Group < OpenvoxStrings::Yard::CodeObjects::Base
+  # Gets the singleton instance of the group.
+  # @param [Symbol] key The key to lookup the group for.
+  # @return Returns the singleton instance of the group.
+  def self.instance(key)
+    instance = P(:root, key)
+    return instance unless instance.is_a?(YARD::CodeObjects::Proxy)
+
+    instance = new(:root, key)
+    instance.visibility = :hidden
+    P(:root).children << instance
+    instance
+  end
+
+  # Gets the path to the group.
+  # @return [String] Returns the path to the group.
+  def path
+    @name.to_s
+  end
+
+  # Gets the type of the group.
+  # @return [Symbol] Returns the type of the group.
+  def type
+    @name
+  end
+end

data/lib/openvox-strings/yard/code_objects/plan.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'openvox-strings/yard/code_objects/group'
+
+# Implements the group for Puppet plans.
+class OpenvoxStrings::Yard::CodeObjects::Plans < OpenvoxStrings::Yard::CodeObjects::Group
+  # Gets the singleton instance of the group.
+  # @return Returns the singleton instance of the group.
+  def self.instance
+    super(:puppet_plans)
+  end
+
+  # Gets the display name of the group.
+  # @param [Boolean] prefix whether to show a prefix. Ignored for Puppet group namespaces.
+  # @return [String] Returns the display name of the group.
+  def name(_prefix = false)
+    'Puppet Plans'
+  end
+end
+
+# Implements the Puppet plan code object.
+class OpenvoxStrings::Yard::CodeObjects::Plan < OpenvoxStrings::Yard::CodeObjects::Base
+  attr_reader :statement, :parameters
+
+  # Initializes a Puppet plan code object.
+  # @param [OpenvoxStrings::Parsers::PlanStatement] statement The plan statement that was parsed.
+  # @return [void]
+  def initialize(statement)
+    @statement = statement
+    @parameters = statement.parameters.map { |p| [p.name, p.value] }
+    super(OpenvoxStrings::Yard::CodeObjects::Plans.instance, statement.name)
+  end
+
+  # Gets the type of the code object.
+  # @return Returns the type of the code object.
+  def type
+    :puppet_plan
+  end
+
+  # Gets the source of the code object.
+  # @return Returns the source of the code object.
+  def source
+    @statement.source
+  end
+
+  # Converts the code object to a hash representation.
+  # @return [Hash] Returns a hash representation of the code object.
+  def to_hash
+    hash = {}
+    hash[:name] = name
+    hash[:file] = file
+    hash[:line] = line
+    hash[:docstring] = OpenvoxStrings::Yard::Util.docstring_to_hash(docstring)
+    defaults = Hash[*parameters.reject { |p| p[1].nil? }.flatten]
+    hash[:defaults] = defaults unless defaults.nil? || defaults.empty?
+    hash[:source] = source unless source.nil? || source.empty?
+    hash
+  end
+end

data/lib/openvox-strings/yard/code_objects/provider.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require 'openvox-strings/yard/code_objects/group'
+
+# Implements the group for Puppet providers.
+class OpenvoxStrings::Yard::CodeObjects::Providers < OpenvoxStrings::Yard::CodeObjects::Group
+  # Gets the singleton instance of the group.
+  # @param [String] type The resource type name for the provider.
+  # @return Returns the singleton instance of the group.
+  def self.instance(type)
+    super(:"puppet_providers_#{type}")
+  end
+
+  # Gets the display name of the group.
+  # @param [Boolean] prefix whether to show a prefix. Ignored for Puppet group namespaces.
+  # @return [String] Returns the display name of the group.
+  def name(_prefix = false)
+    'Providers'
+  end
+end
+
+# Implements the Puppet provider code object.
+class OpenvoxStrings::Yard::CodeObjects::Provider < OpenvoxStrings::Yard::CodeObjects::Base
+  attr_reader :type_name, :confines, :features, :defaults, :commands
+
+  # Initializes a Puppet provider code object.
+  # @param [String] type_name The resource type name for the provider.
+  # @param [String] name The name of the provider.s
+  # @return [void]
+  def initialize(type_name, name)
+    @type_name = type_name
+    super(OpenvoxStrings::Yard::CodeObjects::Providers.instance(type_name), name)
+  end
+
+  # Gets the type of the code object.
+  # @return Returns the type of the code object.
+  def type
+    :puppet_provider
+  end
+
+  # Adds a confine to the provider.
+  # @param [String] key The confine's key.
+  # @param [String] value The confine's value.
+  # @return [void]
+  def add_confine(key, value)
+    return unless key && value
+
+    @confines ||= {}
+    @confines[key] = value
+  end
+
+  # Adds a feature to the provider.
+  # @param [String] feature The feature to add to the provider.
+  # @return [void]
+  def add_feature(feature)
+    return unless feature
+
+    @features ||= []
+    @features << feature
+  end
+
+  # Adds a default to the provider.
+  # @param [Array] constraints List of related key-pair values for the default.
+  # @return [void]
+  def add_default(constraints)
+    return unless constraints
+
+    @defaults ||= []
+    @defaults << constraints
+  end
+
+  # Adds a command to the provider.
+  # @param [String] key The command's key.
+  # @param [String] value The command's value.
+  # @return [void]
+  def add_command(key, value)
+    return unless key && value
+
+    @commands ||= {}
+    @commands[key] = value
+  end
+
+  # Converts the code object to a hash representation.
+  # @return [Hash] Returns a hash representation of the code object.
+  def to_hash
+    hash = {}
+    hash[:name] = name
+    hash[:type_name] = type_name
+    hash[:file] = file
+    hash[:line] = line
+    hash[:docstring] = OpenvoxStrings::Yard::Util.docstring_to_hash(docstring)
+    hash[:confines] = confines if confines && !confines.empty?
+    hash[:features] = features if features && !features.empty?
+    hash[:defaults] = defaults if defaults && !defaults.empty?
+    hash[:commands] = commands if commands && !commands.empty?
+    hash
+  end
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'openvox-strings/yard/code_objects/group'
+
+# Implements the group for Puppet tasks.
+class OpenvoxStrings::Yard::CodeObjects::Tasks < OpenvoxStrings::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. Ignored for Puppet group namespaces.
+  # @return [String] Returns the display name of the group.
+  def name(_prefix = false)
+    'Puppet Tasks'
+  end
+end
+
+# Implements the Puppet task code object.
+class OpenvoxStrings::Yard::CodeObjects::Task < OpenvoxStrings::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(OpenvoxStrings::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
+    statement.parameters.map do |name, props|
+      { name: name.to_s,
+        tag_name: 'param',
+        text: props['description'] || '',
+        types: [props['type']] || '' }
+    end
+  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/openvox-strings/yard/code_objects/type.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require 'openvox-strings/yard/code_objects/group'
+require 'openvox-strings/yard/util'
+
+# Implements the group for Puppet resource types.
+class OpenvoxStrings::Yard::CodeObjects::Types < OpenvoxStrings::Yard::CodeObjects::Group
+  # Gets the singleton instance of the group.
+  # @return Returns the singleton instance of the group.
+  def self.instance
+    super(:puppet_types)
+  end
+
+  # Gets the display name of the group.
+  # @param [Boolean] prefix whether to show a prefix. Ignored for Puppet group namespaces.
+  # @return [String] Returns the display name of the group.
+  def name(_prefix = false)
+    'Resource Types'
+  end
+end
+
+# Implements the Puppet resource type code object.
+class OpenvoxStrings::Yard::CodeObjects::Type < OpenvoxStrings::Yard::CodeObjects::Base
+  # Represents a resource type parameter.
+  class Parameter
+    attr_reader :name, :values, :aliases
+    attr_accessor :docstring, :isnamevar, :default, :data_type, :required_features
+
+    # Initializes a resource type parameter or property.
+    # @param [String] name The name of the parameter or property.
+    # @param [String] docstring The docstring for the parameter or property.s
+    def initialize(name, docstring = nil)
+      @name = name
+      @docstring = docstring || ''
+      @values = []
+      @data_type = []
+      @aliases = {}
+      @isnamevar = false
+      @default = nil
+    end
+
+    # Adds a value to the parameter or property.
+    # @param [String] value The value to add.
+    # @return [void]
+    def add(value)
+      @values << value
+    end
+
+    # Aliases a value to another value.
+    # @param [String] new The new (alias) value.
+    # @param [String] old The old (existing) value.
+    # @return [void]
+    def alias(new, old)
+      @values << new unless @values.include? new
+      @aliases[new] = old
+    end
+
+    # Converts the parameter to a hash representation.
+    # @return [Hash] Returns a hash representation of the parameter.
+    def to_hash
+      hash = {}
+      hash[:name] = name
+      hash[:description] = docstring unless docstring.empty?
+      hash[:values] = values unless values.empty?
+      hash[:data_type] = data_type unless data_type.empty?
+      hash[:aliases] = aliases unless aliases.empty?
+      hash[:isnamevar] = true if isnamevar
+      hash[:required_features] = required_features if required_features
+      hash[:default] = default if default
+      hash
+    end
+  end
+
+  # Represents a resource type property (same attributes as a parameter).
+  class Property < Parameter
+  end
+
+  class Check < Parameter
+  end
+
+  # Represents a resource type feature.
+  class Feature
+    attr_reader :name, :docstring
+
+    # Initializes a new feature.
+    # @param [String] name The name of the feature.
+    # @param [String] docstring The docstring of the feature.
+    def initialize(name, docstring)
+      @name = name
+      @docstring = OpenvoxStrings::Yard::Util.scrub_string(docstring).tr("\n", ' ')
+    end
+
+    # Converts the feature to a hash representation.
+    # @return [Hash] Returns a hash representation of the feature.
+    def to_hash
+      hash = {}
+      hash[:name] = name
+      hash[:description] = docstring unless docstring.empty?
+      hash
+    end
+  end
+
+  attr_reader :properties, :features, :checks
+
+  # Initializes a new resource type.
+  # @param [String] name The resource type name.
+  # @return [void]
+  def initialize(name)
+    super(OpenvoxStrings::Yard::CodeObjects::Types.instance, name)
+  end
+
+  # Gets the type of the code object.
+  # @return Returns the type of the code object.
+  def type
+    :puppet_type
+  end
+
+  # Adds a parameter to the resource type
+  # @param [OpenvoxStrings::Yard::CodeObjects::Type::Parameter] parameter The parameter to add.
+  # @return [void]
+  def add_parameter(parameter)
+    @parameters ||= []
+    @parameters << parameter
+  end
+
+  # Adds a property to the resource type
+  # @param [OpenvoxStrings::Yard::CodeObjects::Type::Property] property The property to add.
+  # @return [void]
+  def add_property(property)
+    @properties ||= []
+    @properties << property
+  end
+
+  # Adds a feature to the resource type.
+  # @param [OpenvoxStrings::Yard::CodeObjects::Type::Feature] feature The feature to add.
+  # @return [void]
+  def add_feature(feature)
+    @features ||= []
+    @features << feature
+  end
+
+  # Adds a check to the resource type.
+  # @param [OpenvoxStrings::Yard::CodeObjects::Type::Check] check The check to add.
+  # @return [void]
+  def add_check(check)
+    @checks ||= []
+    @checks << check
+  end
+
+  def parameters
+    @parameters ||= [] # guard against not filled parameters
+    # just return params if there are no providers
+    return @parameters if providers.empty?
+
+    # return existing params if we have already added provider
+    return @parameters if @parameters&.any? { |p| p.name == 'provider' }
+
+    provider_param = Parameter.new(
+      'provider',
+      "The specific backend to use for this `#{name}` resource. You will seldom need " \
+      'to specify this --- Puppet will usually discover the appropriate provider for your platform.'
+    )
+
+    @parameters ||= []
+    @parameters << provider_param
+  end
+
+  # Not sure if this is where this belongs or if providers should only be resolved at
+  # render-time. For now, this should re-resolve on every call.
+  # may be able to memoize this
+  def providers
+    providers = YARD::Registry.all(:"puppet_providers_#{name}")
+    return providers if providers.empty?
+
+    providers.first.children
+  end
+
+  # Converts the code object to a hash representation.
+  # @return [Hash] Returns a hash representation of the code object.
+  def to_hash
+    hash = {}
+
+    hash[:name] = name
+    hash[:file] = file
+    hash[:line] = line
+
+    hash[:docstring]  = OpenvoxStrings::Yard::Util.docstring_to_hash(docstring)
+    hash[:properties] = properties.sort_by(&:name).map(&:to_hash) if properties && !properties.empty?
+    hash[:parameters] = parameters.sort_by(&:name).map(&:to_hash) if parameters && !parameters.empty?
+    hash[:checks]     = checks.sort_by(&:name).map(&:to_hash) if checks && !checks.empty?
+    hash[:features]   = features.sort_by(&:name).map(&:to_hash) if features && !features.empty?
+    hash[:providers]  = providers.sort_by(&:name).map(&:to_hash) if providers && !providers.empty?
+
+    hash
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# The module for custom YARD code objects.
+module OpenvoxStrings::Yard::CodeObjects
+  require 'openvox-strings/yard/code_objects/class'
+  require 'openvox-strings/yard/code_objects/data_type'
+  require 'openvox-strings/yard/code_objects/data_type_alias'
+  require 'openvox-strings/yard/code_objects/defined_type'
+  require 'openvox-strings/yard/code_objects/type'
+  require 'openvox-strings/yard/code_objects/provider'
+  require 'openvox-strings/yard/code_objects/function'
+  require 'openvox-strings/yard/code_objects/task'
+  require 'openvox-strings/yard/code_objects/plan'
+end

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

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Implements a helper that logs a warning if a summary tag has more than 140 characters
+module OpenvoxStrings::Yard::Handlers::Helpers
+  def self.validate_summary_tag(object)
+    return unless object.has_tag?(:summary) && object.tag(:summary).text.length > 140
+
+    log.warn "The length of the summary for #{object.type} '#{object.name}' exceeds the recommended limit of 140 characters."
+  end
+end

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

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Implements the base class for all JSON handlers.
+class OpenvoxStrings::Yard::Handlers::JSON::Base < YARD::Handlers::Base
+  def self.handles?(statement)
+    handlers.any? { |handler| statement.is_a?(handler) }
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'openvox-strings/yard/handlers/json/base'
+require 'openvox-strings/yard/parsers'
+require 'openvox-strings/yard/parsers/json/parser'
+
+# Implements the handler for JSON task metadata.
+class OpenvoxStrings::Yard::Handlers::JSON::TaskHandler < OpenvoxStrings::Yard::Handlers::JSON::Base
+  handles OpenvoxStrings::Yard::Parsers::JSON::TaskStatement
+  namespace_only
+
+  process do
+    object = OpenvoxStrings::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
+    return if @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

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# Implements the base handler for Puppet language handlers.
+class OpenvoxStrings::Yard::Handlers::Puppet::Base < YARD::Handlers::Base
+  # Determine sif the handler handles the given statement.
+  # @param statement The statement that was parsed.
+  # @return [Boolean] Returns true if the statement is handled by this handler or false if not.
+  def self.handles?(statement)
+    handlers.any? { |handler| statement.is_a?(handler) }
+  end
+
+  protected
+
+  # Sets the parameter tag types for the given code object.
+  # This also performs some validation on the parameter tags.
+  # @param object The code object to set the parameter tag types for.
+  # @return [void]
+  def set_parameter_types(object)
+    # Ensure there is an actual parameter for each parameter tag
+    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}." unless %w[name title].include?(tag.name)
+    end
+
+    # Assign the types for the parameter
+    statement.parameters.each do |parameter|
+      tag = tags.find { |t| t.name == parameter.name }
+      unless tag
+        log.warn "Missing @param tag for parameter '#{parameter.name}' near #{statement.file}:#{statement.line}." unless object.docstring.empty?
+
+        # Add a tag with an empty docstring
+        object.add_tag YARD::Tags::Tag.new(:param, '', [parameter.type || 'Any'], parameter.name)
+        next
+      end
+
+      # Warn if the parameter type and tag types don't match
+      if parameter.type && tag.types && !tag.types.empty? && parameter.type != tag.types[0]
+        log.warn "The type of the @param tag for parameter '#{parameter.name}' " \
+                 "does not match the parameter type specification near #{statement.file}:#{statement.line}: " \
+                 'ignoring in favor of parameter type information.'
+      end
+
+      if parameter.type
+        tag.types = [parameter.type]
+      elsif !tag.types
+        tag.types = ['Any']
+      end
+    end
+  end
+end