openvox-strings 6.1.0 → 7.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e110d114b1600a477064071570a4999be41d69c8a9dc239686507dafe2cb8087
-  data.tar.gz: 0a3c79360b241f4693d5cd3850a83b4363efb0f30c1b14fc2b0ed0bb8519ae3e
+  metadata.gz: 8a4305998c36c2f258decc43a46de8b89ebbd52492e9f4dd003909af5b657abe
+  data.tar.gz: 741e317d5ee54b75e63ebef4abe8795d1752046cd733dbae1b3abe436499fd1e
 SHA512:
-  metadata.gz: 2fb4c34bb55826086049bf9ec865d5f31bcbe832135598f3fcdc843a12527e0697d5e51cda0d95a1ea7e53312babc92cea788d070e44d61597c41763ccd3cd09
-  data.tar.gz: 73c68a76542d8ef8b0362f1ac868a563656eef01ce0cc7d012a3f8bae6648c05672577ce03f21fa7a2a9b026bde0480ba739ffd73deeb96201962f544dcf1dcd
+  metadata.gz: bda5adbbf34a9f57bdc095bb28968a65e0c62bbbfefbfdd213db22015a387b246ab94f71ae3661dc8bea734f0bd0355b5b1f724c75317a7aff649eee626d8ea5
+  data.tar.gz: 3361070dfc9cf61198cfc8162a40bbe83c0f0a1b72be9bedbd962a85eb18846a2a88bcffaf0e4da6fc83c1dbdb35bf3d54ab2b80f12d115b60a16caeb497b1be

data/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v7.0.0](https://github.com/voxpupuli/openvox-strings/tree/v7.0.0) (2026-02-19)
+
+[Full Changelog](https://github.com/voxpupuli/openvox-strings/compare/v6.1.0...v7.0.0)
+
+**Breaking changes:**
+
+- Add Hiera defaults support for module documentation [\#27](https://github.com/voxpupuli/openvox-strings/pull/27) ([slauger](https://github.com/slauger))
+
 ## [v6.1.0](https://github.com/voxpupuli/openvox-strings/tree/v6.1.0) (2026-02-19)
 
 [Full Changelog](https://github.com/voxpupuli/openvox-strings/compare/v6.0.0...v6.1.0)

data/lib/openvox-strings/hiera.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module OpenvoxStrings
+  # Parser for Hiera configuration and data
+  class Hiera
+    attr_reader :hiera_config, :common_data
+
+    # Initializes a Hiera parser for a given module path
+    # @param [String] module_path The path to the Puppet module root directory
+    def initialize(module_path)
+      @module_path = module_path
+      @hiera_config = load_hiera_config
+      @common_data = load_common_data
+    end
+
+    # Checks if Hiera is configured for this module
+    # @return [Boolean] true if hiera.yaml exists and is valid
+    def hiera_enabled?
+      !@hiera_config.nil?
+    end
+
+    # Gets the default value for a parameter from Hiera data
+    # @param [String] class_name The fully qualified class name (e.g., 'github_actions_runner')
+    # @param [String] param_name The parameter name
+    # @return [String, nil] The default value as a string, or nil if not found
+    def lookup_default(class_name, param_name)
+      return nil unless hiera_enabled?
+      return nil if @common_data.nil?
+
+      # Try to lookup with class prefix: modulename::parametername
+      key = "#{class_name}::#{param_name}"
+      return nil unless @common_data.key?(key)
+
+      value = @common_data[key]
+
+      # Convert value to Puppet-compatible string representation
+      value_to_puppet_string(value)
+    end
+
+    private
+
+    # Loads and parses hiera.yaml from the module root
+    # @return [Hash, nil] The parsed hiera configuration, or nil if not found/invalid
+    def load_hiera_config
+      hiera_file = File.join(@module_path, 'hiera.yaml')
+      load_yaml_data(hiera_file)
+    end
+
+    # Finds the path to the first static hierarchy layer (without interpolations)
+    # @return [String, nil] The full path to the data file, or nil if not found
+    def find_first_static_layer_path
+      return nil unless hiera_enabled?
+
+      # Get datadir from hiera config (defaults to 'data')
+      datadir = @hiera_config.dig('defaults', 'datadir') || 'data'
+
+      # Find first hierarchy entry without interpolations
+      hierarchy = @hiera_config['hierarchy']
+      return nil unless hierarchy
+
+      first_static = hierarchy.find do |entry|
+        path_or_paths = entry['path'] || entry['paths']
+        next false unless path_or_paths
+
+        # Check if path(s) contain interpolations like %{...}
+        case path_or_paths
+        when String
+          !path_or_paths.include?('%{')
+        when Array
+          path_or_paths.none? { |p| p.include?('%{') }
+        else
+          false
+        end
+      end
+
+      return nil unless first_static
+
+      # Get the path from the hierarchy entry
+      data_file_path = first_static['path'] || first_static['paths']&.first
+      return nil unless data_file_path
+
+      # Build and return full path
+      File.join(@module_path, datadir, data_file_path)
+    end
+
+    # Loads and parses a YAML data file
+    # @param [String] file_path The full path to the YAML file to load
+    # @return [Hash, nil] The parsed YAML data, or nil if not found/invalid
+    def load_yaml_data(file_path)
+      return nil unless File.exist?(file_path)
+
+      begin
+        YAML.load_file(file_path)
+      rescue StandardError => e
+        YARD::Logger.instance.warn "Failed to parse #{File.basename(file_path)}: #{e.message}"
+        nil
+      end
+    end
+
+    # Loads and parses the first static hierarchy layer (without interpolations)
+    # @return [Hash, nil] The parsed data, or nil if not found/invalid
+    def load_common_data
+      data_file = find_first_static_layer_path
+      return nil unless data_file
+
+      load_yaml_data(data_file)
+    end
+
+    # Converts a Ruby value to a Puppet-compatible string representation
+    # @param [Object] value The value to convert
+    # @return [String] The Puppet-compatible string representation
+    def value_to_puppet_string(value)
+      case value
+      when String
+        # Empty strings from YAML nil (~) should be undef
+        return 'undef' if value.empty?
+
+        # Strings should be quoted
+        "'#{value}'"
+      when Integer, Float, TrueClass, FalseClass
+        # Numbers and booleans are unquoted/lowercase
+        value.to_s
+      when NilClass, :undef
+        # Puppet undef
+        'undef'
+      when Hash
+        # Convert hash to Puppet hash syntax (no spaces to match code defaults format)
+        return '{}' if value.empty?
+
+        pairs = value.map { |k, v| "'#{k}' => #{value_to_puppet_string(v)}" }
+        "{ #{pairs.join(', ')} }"
+      when Array
+        # Convert array to Puppet array syntax (no spaces to match code defaults format)
+        return '[]' if value.empty?
+
+        elements = value.map { |v| value_to_puppet_string(v) }
+        "[#{elements.join(', ')}]"
+      else
+        # Fallback: convert to string and quote
+        "'#{value}'"
+      end
+    end
+  end
+end

data/lib/openvox-strings/markdown/base.rb

@@ -4,6 +4,7 @@ require 'openvox-strings'
 require 'openvox-strings/json'
 require 'openvox-strings/yard'
 require 'openvox-strings/markdown/helpers'
+require 'openvox-strings/hiera'
 
 # Implements classes that make elements in a YARD::Registry hash easily accessible for template.
 module OpenvoxStrings::Markdown
@@ -86,6 +87,7 @@ module OpenvoxStrings::Markdown
       @type = component_type
       @registry = registry
       @tags = registry[:docstring][:tags] || []
+      @hiera = initialize_hiera
     end
 
     # generate 1:1 tag methods
@@ -174,7 +176,13 @@ module OpenvoxStrings::Markdown
 
     # @return [Hash] any defaults found for the component
     def defaults
-      @registry[:defaults] unless @registry[:defaults].nil?
+      # Start with code defaults from the Puppet class
+      code_defaults = @registry[:defaults] || {}
+
+      # Try to merge with Hiera defaults if available
+      merged_defaults = merge_hiera_defaults(code_defaults)
+
+      merged_defaults.empty? ? nil : merged_defaults
     end
 
     # @return [Hash] information needed for the table of contents
@@ -216,6 +224,59 @@ module OpenvoxStrings::Markdown
 
     private
 
+    # Initializes Hiera integration for this component
+    # @return [OpenvoxStrings::Hiera, nil] Hiera instance or nil if not available
+    def initialize_hiera
+      return nil unless @registry[:file]
+
+      # Find the module root directory from the file path
+      # Puppet modules have manifests/, lib/, data/ etc. at the root
+      module_path = find_module_root(@registry[:file])
+      return nil unless module_path
+
+      OpenvoxStrings::Hiera.new(module_path)
+    rescue StandardError => e
+      YARD::Logger.instance.debug "Failed to initialize Hiera: #{e.message}"
+      nil
+    end
+
+    # Finds the module root directory from a file path
+    # @param [String] file_path The path to a file in the module
+    # @return [String, nil] The module root path or nil if not found
+    def find_module_root(file_path)
+      names = %w[metadata.json manifests hiera.yaml]
+      Pathname.new(file_path).expand_path.parent.ascend do |current_path|
+        names.each do |name|
+          return current_path if (current_path / name).exist?
+        end
+      end
+    end
+
+    # Merges code defaults with Hiera defaults
+    # @param [Hash] code_defaults The defaults from the Puppet code
+    # @return [Hash] Merged defaults with code defaults taking precedence
+    def merge_hiera_defaults(code_defaults)
+      return code_defaults unless @hiera&.hiera_enabled?
+
+      # Start with Hiera defaults
+      merged = {}
+
+      # Get all parameters from the docstring
+      param_tags = @tags.select { |tag| tag[:tag_name] == 'param' }
+
+      param_tags.each do |param_tag|
+        param_name = param_tag[:name]
+        next unless param_name
+
+        # Try to get default from Hiera
+        hiera_default = @hiera.lookup_default(name, param_name)
+        merged[param_name] = hiera_default if hiera_default
+      end
+
+      # Code defaults override Hiera defaults
+      merged.merge(code_defaults)
+    end
+
     def select_tags(name)
       tags = @tags.select { |tag| tag[:tag_name] == name }
       tags.empty? ? nil : tags

data/lib/openvox-strings/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OpenvoxStrings
-  VERSION = '6.1.0'
+  VERSION = '7.0.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openvox-strings
 version: !ruby/object:Gem::Version
-  version: 6.1.0
+  version: 7.0.0
 platform: ruby
 authors:
 - Puppet Inc.
@@ -105,6 +105,7 @@ files:
 - README.md
 - lib/openvox-strings.rb
 - lib/openvox-strings/describe.rb
+- lib/openvox-strings/hiera.rb
 - lib/openvox-strings/json.rb
 - lib/openvox-strings/markdown.rb
 - lib/openvox-strings/markdown/base.rb