releasehx 0.1.0

data/lib/releasehx/rhyml/change.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module ReleaseHx
+  module RHYML
+    # Represents a single Change within a Release, such as a bug fix, feature, or enhancement.
+    #
+    # The Change class encapsulates all metadata associated with an individual modification,
+    #  including its classification (type), descriptive content (summary, notes),
+    #  organizational data (tags, parts), and contributor information.
+    # Changes are always associated with a parent Release object.
+    class Change
+      attr_accessor :release, :version
+      attr_reader :vrsn, :chid, :tick, :hash, :type, :parts, :summ, :head, :note, :tags, :lead, :auths, :links
+
+      # Initializes a new Change object from attribute hash and parent Release.
+      #
+      # Processes the provided attributes to populate Change properties, handling
+      #  multiple possible field names (e.g., 'summ', 'summary', 'title') and
+      #  normalizing complex attributes like authors and links.
+      #
+      # @param attrs [Hash] A hash of attributes for the Change.
+      # @param release [Release] The required parent Release object.
+      # @raise [ArgumentError] If attrs is not a Hash or if both 'part' and 'parts' are provided.
+      def initialize attrs = {}, release:
+        raise ArgumentError, 'attrs must be a Hash' unless attrs.is_a? Hash
+
+        @release = release
+        @vrsn    = @release.code
+        @chid    = attrs['chid']
+        @tick    = attrs_value(attrs, %w[tick ticketid])
+        @hash    = attrs['hash']
+        @type    = attrs['type']
+        @summ    = attrs_value(attrs, %w[summ summary title])
+        @head    = attrs['head']
+        @note    = attrs['note']
+        @tags    = attrs['tags'] || []
+        @lead    = attrs_value(attrs, %w[lead contributor auth])
+        @auths   = normalize_auths(attrs['auths'])
+        @links   = normalize_links(attrs['links'])
+
+        # Handle 'part' vs 'parts'; mutually exclusive attributes
+        part  = attrs['part']
+        parts = attrs['parts']
+        raise ArgumentError, "Change cannot have both 'part' and 'parts'" if part && parts
+
+        @parts = if parts
+                   Array(parts).map(&:to_s)
+                 elsif part
+                   [part.to_s]
+                 else
+                   []
+                 end
+
+        ReleaseHx.logger.debug "Initialized Change: #{@tick} – #{@summ}"
+      end
+
+      # Produces a comprehensive hash representation of the Change.
+      #
+      # Includes all public attributes plus computed boolean properties
+      # for common Change classifications (highlight, breaking, etc.).
+      #
+      # @return [Hash] A hash containing all public attributes of the Change.
+      def to_h
+        {
+          'vrsn' => vrsn,
+          'chid' => chid,
+          'tick' => tick,
+          'hash' => hash,
+          'type' => type,
+          'parts' => parts,
+          'summ' => summ,
+          'head' => head,
+          'note' => note,
+          'tags' => tags,
+          'lead' => lead,
+          'auths' => auths,
+          'links' => links,
+          'deprecation' => deprecation?,
+          'removal' => removal?,
+          'highlight' => highlight?,
+          'breaking' => breaking?,
+          'experimental' => experimental?
+        }
+      end
+
+      # @return [Boolean] True if the Change is tagged as a highlight.
+      def highlight? = tags.include?('highlight')
+      # @return [Boolean] True if the Change is a breaking change.
+      def breaking?     = tags.include?('breaking')
+      # @return [Boolean] True if the Change is experimental.
+      def experimental? = tags.include?('experimental')
+      # @return [Boolean] True if the Change includes a deprecation.
+      def deprecation?  = tags.include?('deprecation')
+      # @return [Boolean] True if the Change includes a removal.
+      def removal?      = tags.include?('removal')
+
+      # Checks if a given tag is associated with the Change.
+      #
+      # Performs flexible tag matching, checking for the tag as provided,
+      #  as a string, and as a symbol to handle different input types.
+      #
+      # @param tag_name [String, Symbol] The name of the tag to check.
+      # @return [Boolean] True if the tag exists in any form.
+      def tag? tag_name
+        tags.include?(tag_name) || tags.include?(tag_name.to_s) || tags.include?(tag_name.to_sym)
+      end
+
+      private
+
+      # Retrieves the first available attribute value from a prioritized list of keys.
+      #
+      # Used for handling multiple possible field names in source data
+      # (example: 'tick' or 'ticketid', 'summ' or 'summary' or 'title').
+      #
+      # @param attrs [Hash] The attributes hash to search.
+      # @param keys [Array<String>] Ordered list of keys to try.
+      # @return [Object, nil] The first found value or nil if none exist.
+      def attrs_value attrs, keys
+        keys.find { |key| return attrs[key] if attrs.key?(key) }
+        nil
+      end
+
+      # Normalizes the 'auths' attribute to ensure consistent structure.
+      #
+      # Converts various input formats (strings, hashes, arrays) into a
+      # standardized array of hashes with 'user' and optional 'memo' keys.
+      #
+      # @param val [String, Hash, Array, nil] The authors data to normalize.
+      # @return [Array<Hash>] Normalized array of author hashes.
+      def normalize_auths val
+        return [] if val.nil?
+
+        Array(val).map do |a|
+          if a.is_a?(String)
+            { 'user' => a }
+          elsif a.is_a?(Hash)
+            {
+              'user' => a['user'] || a[:user],
+              'memo' => a['memo'] || a[:memo]
+            }.compact
+          else
+            { 'user' => a.to_s }
+          end
+        end
+      end
+
+      # Normalizes the 'links' attribute to ensure consistent structure.
+      #
+      # Ensures all links have standardized 'text', 'xref', and 'href' keys,
+      #  converting symbol keys to string keys and filtering out nil values.
+      #
+      # @param val [Array<Hash>, nil] The links data to normalize.
+      # @return [Array<Hash>] Normalized array of link hashes.
+      def normalize_links val
+        return [] if val.nil?
+
+        val.map do |l|
+          {
+            'text' => l['text'] || l[:text],
+            'xref' => l['xref'] || l[:xref],
+            'href' => l['href'] || l[:href]
+          }.compact
+        end
+      end
+    end
+  end
+end

data/lib/releasehx/rhyml/liquid.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module ReleaseHx
+  module RHYML
+    module RHYMLFilters
+      def pasterize input
+        return input unless input.is_a? String
+
+        RHYML.pasterize(input)
+      end
+    end
+  end
+end

data/lib/releasehx/rhyml/loaders.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ReleaseHx
+  module RHYML
+    class Loader
+      require 'yaml'
+      require 'json'
+
+      def self.load_file path
+        ext = File.extname(path)
+        case ext
+        when '.yml', '.yaml'
+          SchemaGraphy::Loader.load_yaml_with_tags(path)
+        when '.json'
+          JSON.parse(File.read(path))
+        else
+          raise "Unsupported format: #{ext}"
+        end
+      end
+    end
+
+    class MappingLoader < Loader
+    end
+
+    class ReleaseLoader < Loader
+      def self.load path
+        hash = load_file(path)
+        Release.new(
+          code: hash['code'],
+          date: hash['date'],
+          hash: hash['hash'],
+          memo: hash['memo'],
+          changes: hash['changes'] || hash['work'] || [])
+      end
+    end
+  end
+end

data/lib/releasehx/rhyml/mappings/github.yaml

@@ -0,0 +1,60 @@
+# GitHub Issues API to RHYML mapping configuration
+# Maps GitHub Issues API response to RHYML Change entries
+
+$config:
+  desc: "GitHub Issues API to RHYML mapping"
+  path_lang: jmespath
+  tplt_lang: liquid
+
+# GitHub Issues API returns an array of issues directly
+# But some payloads may have an {issues: [...]} wrapper
+changes_array_path: "issues || @"
+
+# Map each issue to RHYML Change properties
+tick:
+  path: "number"
+
+# hash:
+#   path: $nil # GitHub Issues API doesn't include git commit hashes
+
+summ:
+  path: "title"
+
+note:
+  path: "body"
+
+# Extract type from the native GitHub Issues type field (modern approach)
+type:
+  path: "issue_type.name"
+
+# Derive `parts` from labels using direct key matching or slug override
+parts:
+  path: "labels[].name"
+  ruby: |
+    labels = path.is_a?(Array) ? path : [path]
+    parts_defs = config['parts'] || {}
+    label_prefix = parts_defs['label_prefix'] || ''
+
+    label_to_part = parts_defs.each_with_object({}) do |(part_key, part_config), memo|
+      if part_config.is_a?(Hash)
+        slug = part_config['slug']
+        memo[part_key.to_s.downcase] = part_key
+        memo[slug.to_s.downcase] = part_key if slug
+      end
+    end
+
+    found_parts = labels.map do |label|
+      l = label.to_s.downcase
+      if !label_prefix.to_s.empty? && l.start_with?(label_prefix.to_s.downcase)
+        l = l.sub(/^#{Regexp.escape(label_prefix)}/i, '')
+      end
+      label_to_part[l]
+    end
+
+    found_parts.compact.uniq
+
+tags:
+  path: "labels[].name"
+
+lead:
+  path: "assignee.login"

data/lib/releasehx/rhyml/mappings/gitlab.yaml

@@ -0,0 +1,73 @@
+# GitLab Issues API to RHYML mapping configuration
+# Maps GitLab Issues API response to RHYML Change entries
+
+$config:
+  desc: "GitLab Issues API to RHYML mapping"
+  path_lang: jmespath
+  tplt_lang: liquid
+
+# GitLab Issues API returns an array of issues in "issues" key
+changes_array_path: "issues"
+
+# Map each issue to RHYML Change properties
+tick:
+  path: "iid"
+
+summ:
+  path: "title"
+
+note:
+  path: "description"
+
+# Derive `type` from labels using direct key matching or slug override
+type:
+  path: "labels"
+  ruby: |
+    labels = path.is_a?(Array) ? path : [path]
+    type_defs = config['types'] || {}
+
+    label_to_type = type_defs.each_with_object({}) do |(type_key, type_config), memo|
+      if type_config.is_a?(Hash)
+        slug = type_config['slug']
+        memo[type_key.to_s.downcase] = type_key
+        memo[slug.to_s.downcase] = type_key if slug
+      end
+    end
+
+    found_type = labels.find do |label|
+      label_to_type[label.to_s.downcase]
+    end
+
+    label_to_type[found_type.to_s.downcase] if found_type
+
+# Derive `parts` from labels using direct key matching or slug override
+parts:
+  path: "labels"
+  ruby: |
+    labels = path.is_a?(Array) ? path : [path]
+    parts_defs = config['parts'] || {}
+    label_prefix = parts_defs['label_prefix'] || ''
+
+    label_to_part = parts_defs.each_with_object({}) do |(part_key, part_config), memo|
+      if part_config.is_a?(Hash)
+        slug = part_config['slug']
+        memo[part_key.to_s.downcase] = part_key
+        memo[slug.to_s.downcase] = part_key if slug
+      end
+    end
+
+    found_parts = labels.map do |label|
+      l = label.to_s.downcase
+      if !label_prefix.to_s.empty? && l.start_with?(label_prefix.to_s.downcase)
+        l = l.sub(/^#{Regexp.escape(label_prefix)}/i, '')
+      end
+      label_to_part[l]
+    end
+
+    found_parts.compact.uniq
+
+tags:
+  path: "labels"
+
+lead:
+  path: "assignees[0].username"

data/lib/releasehx/rhyml/mappings/jira.yaml

@@ -0,0 +1,29 @@
+# Jira Issues API to RHYML mapping configuration
+$config:
+  desc: "Jira Issues API to RHYML mapping"
+  path_lang: jmespath
+  tplt_lang: liquid
+
+changes_array_path: "@"
+
+tick:
+  path: "key"
+
+summ:
+  path: "fields.summary"
+
+note:
+  path: "fields.description"
+
+type:
+  path: "fields.issuetype.name"
+  tplt: '{{ path | downcase }}'
+
+parts:
+  path: "fields.components[].name"
+
+tags:
+  path: "fields.labels"
+
+lead:
+  path: "fields.assignee.displayName"

data/lib/releasehx/rhyml/mappings/verb_past_tenses.yml

@@ -0,0 +1,98 @@
+# Verb past tense mappings for the pasterize feature
+# Maps present tense verbs to their past tense equivalents
+add: added
+adds: added
+address: addressed
+addresses: addressed
+change: changed
+changes: changed
+clarify: clarified
+clarifies: clarified
+clean: cleaned
+cleans: cleaned
+configure: configured
+configures: configured
+correct: corrected
+corrects: corrected
+create: created
+creates: created
+deprecate: deprecated
+deprecates: deprecated
+document: documented
+documents: documented
+downgrade: downgraded
+downgrades: downgraded
+enhance: enhanced
+enhances: enhanced
+enable: enabled
+enables: enabled
+evaluate: evaluated
+evaluates: evaluated
+expand: expanded
+expands: expanded
+fix: fixed
+fixes: fixed
+improve: improved
+improves: improved
+handle: handled
+handles: handled
+implement: implemented
+implements: implemented
+initialize: initialized
+initializes: initialized
+integrate: integrated
+integrates: integrated
+investigate: investigated
+investigates: investigated
+launch: launched
+launches: launched
+make: made
+makes: made
+merge: merged
+merges: merged
+migrate: migrated
+migrates: migrated
+optimize: optimized
+optimizes: optimized
+patch: patched
+patches: patched
+refactor: refactored
+refactors: refactored
+refine: refined
+refines: refined
+remove: removed
+removes: removed
+rename: renamed
+renames: renamed
+revert: reverted
+reverts: reverted
+review: reviewed
+reviews: reviewed
+resolve: resolved
+resolves: resolved
+restructure: restructured
+restructures: restructured
+rework: reworked
+reworks: reworked
+secure: secured
+secures: secured
+simplify: simplified
+simplifies: simplified
+speedup: "sped up"
+speedups: "sped up"
+standardize: standardized
+standardizes: standardized
+streamline: streamlined
+streamlines: streamlined
+support: supported
+supports: supported
+test: tested
+tests: tested
+tweak: tweaked
+tweaks: tweaked
+update: updated
+updates: updated
+upgrade: upgraded
+upgrades: upgraded
+verify: verified
+verifies: verified

data/lib/releasehx/rhyml/release.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module ReleaseHx
+  module RHYML
+    # Represents a single versioned release containing metadata and associated changes.
+    #
+    # The Release class serves as a container for release metadata (version code, date, etc.)
+    #  and manages a collection of Change objects that comprise the Release content.
+    class Release
+      attr_reader :code, :date, :hash, :memo, :changes
+
+      # Initializes a new Release object.
+      #
+      # @param code [String] The version code for the release (e.g., '1.2.0').
+      # @param date [Date, String] The release date.
+      # @param hash [String] The Git commit hash associated with the release.
+      # @param memo [String] A descriptive memo for the release.
+      # @param changes [Array<Change, Hash>] An array of Change objects or Hashes
+      #   to be converted into Change objects.
+      def initialize code:, date: nil, hash: nil, memo: nil, changes: []
+        @code    = code
+        @date    = date
+        @hash    = hash
+        @memo    = memo
+        @changes = Array(changes).map { |ch| init_change(ch) }.compact
+
+        ReleaseHx.logger.debug 'Release initialized with changes (post-compact):'
+        @changes.each_with_index do |ch, i|
+          ReleaseHx.logger.debug "  changes[#{i}]: #{ch.class}" unless ch.nil?
+        end
+        raise 'Unexpected nil in changes' if @changes.any?(&:nil?)
+      end
+
+      # Adds a Change object to the Release.
+      #
+      # @param change [Change] The Change object to add.
+      # @return [Array<Change>] The updated array of Changes.
+      def add_change change
+        attach_release(change)
+        @changes << change
+      end
+
+      # Returns the number of Changes in the Release.
+      #
+      # @return [Integer] The count of Changes.
+      def change_count
+        changes.size
+      end
+
+      # Retrieves a unique, sorted list of contributor logins for the Release.
+      #
+      # @return [Array<String>] An array of unique contributor names.
+      def contributors
+        changes.map(&:lead).compact.uniq
+      end
+
+      # Calculates a hash with the count of each tag used in the Release.
+      #
+      # @return [Hash{String => Integer}] A hash where keys are tag names and
+      #   values are their counts.
+      def tag_stats
+        changes.compact.flat_map { |c| c.tags || [] }.tally
+      end
+
+      # Converts the Release metadata to a hash representation.
+      #
+      # @note This method excludes the Changes array from the output.
+      # @return [Hash] A hash containing the Release's metadata fields.
+      def to_h
+        {
+          'code' => code,
+          'version' => code, # alias for backward compatibility
+          'date' => date,
+          'hash' => hash,
+          'memo' => memo,
+          'tag_stats' => tag_stats,
+          'contributors' => contributors
+        }.compact
+      end
+
+      private
+
+      # Initializes a Change object from various input types.
+      # Handles both existing Change objects and raw Hash data.
+      #
+      # @param change [Hash, Change] The item to process into a Change object.
+      # @return [Change, nil] A valid Change object or nil if input is invalid.
+      def init_change change
+        return nil unless change
+
+        if change.is_a?(Change)
+          change.release = self
+          change
+        elsif change.is_a?(Hash)
+          begin
+            obj = Change.new(change, release: self)
+            obj.release = self
+            obj
+          rescue StandardError => e
+            ReleaseHx.logger.warn "Skipping malformed change: #{e.message}"
+            nil
+          end
+        else
+          ReleaseHx.logger.warn "Unknown change type: #{ch.class}"
+          nil
+        end
+      end
+
+      # Associates a Change object with this Release by setting its release property.
+      #
+      # @param change [Change] The Change to associate with this release.
+      # @return [Change] The associated Change object.
+      def attach_release change
+        change.release = self
+        change
+      end
+    end
+
+    # Manages a collection of Release objects for historical tracking.
+    #
+    # @note This class is currently unused but maintained as part of the core
+    #   RHYML data model for future functionality like cross-release analytics.
+    class History
+      attr_reader :releases
+
+      # Initializes a new, empty History object.
+      def initialize
+        @releases = []
+      end
+
+      # Adds a Release to the history.
+      #
+      # @param release [Release] The Release to add.
+      # @return [Release] The Release that was added.
+      def add_release release
+        raise ArgumentError, 'Release must be a Release object' unless release.is_a? Release
+
+        @releases << release
+        ReleaseHx.logger.debug "Added Release: #{release.code} (#{release.date})"
+        release
+      end
+    end
+  end
+end

data/lib/releasehx/rhyml.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative 'rhyml/adapter'
+require_relative 'rhyml/change'
+require_relative 'rhyml/loaders'
+require_relative 'rhyml/release'
+require_relative 'rhyml/liquid'
+
+module ReleaseHx
+  # RHYML (Release History YAML) is the core data modeling language for ReleaseHx.
+  # This module provides the components for loading, validating, and transforming
+  # RHYML data.
+  module RHYML
+  end
+end

data/lib/releasehx/sgyml/helpers.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative '../../schemagraphy/templating'
+
+module ReleaseHx
+  module SgymlHelpers
+    # Precompiles a schema into a set of templates, using the provided data and schema.
+    def self.precompile_from_schema! data, schema, base_path = '', scope: {}
+      SchemaGraphy::Templating.precompile_from_schema!(data, schema, base_path, scope: scope)
+    end
+
+    # Renders all templated fields in a given Hash if they've previously been parsed
+    def self.render_stage_fields! data, stage
+      data.each do |key, value|
+        next unless value.is_a?(Sourcerer::Templating::TemplatedField)
+
+        tmpl_context = value.context
+        next unless tmpl_context.respond_to?(:stage)
+        next unless tmpl_context.stage.to_sym == stage.to_sym
+
+        data[key] = value.render
+      end
+    end
+
+    # Recursively converts all keys in a Hash or Array to strings,
+    #  safely handling non-stringifiable objects
+    def self.deep_stringify_safe obj
+      case obj
+      when Hash
+        obj.each_with_object({}) do |(k, v), h|
+          h[k.to_s] = deep_stringify_safe(v)
+        end
+      when Array
+        obj.map { |v| deep_stringify_safe(v) }
+      else
+        begin
+          obj.to_yaml
+          obj
+        rescue TypeError
+          obj.to_s
+        end
+      end
+    end
+  end
+end