releasehx 0.1.0

data/lib/releasehx/transforms/adf_to_markdown.rb

@@ -0,0 +1,307 @@
+# frozen_string_literal: true
+
+module ReleaseHx
+  module Transforms
+    # Converts Atlassian Document Format (ADF) to Markdown.
+    # Focused on extracting "Release Note" sections from Jira issue descriptions
+    # and converting them to clean Markdown for use in release documentation.
+    module AdfToMarkdown
+      # Checks if an object is an ADF document
+      #
+      # @param obj [Object] The object to check
+      # @return [Boolean] true if obj is an ADF document
+      def self.adf? obj
+        return false unless obj.is_a?(Hash)
+        return false unless obj['type'] == 'doc'
+        return false unless obj['version'] == 1
+
+        obj.key?('content') && obj['content'].is_a?(Array)
+      end
+
+      # Extracts a specific section from an ADF document by heading text
+      #
+      # @param adf_doc [Hash] The ADF document
+      # @param heading [String] The heading text to search for (case-insensitive)
+      # @return [Hash] A new ADF document containing only the extracted section
+      def self.extract_section adf_doc, heading: 'Release Note'
+        return adf_doc unless adf?(adf_doc)
+
+        content = adf_doc['content'] || []
+        heading_normalized = heading.strip.downcase
+
+        # Find the heading index
+        heading_idx = content.find_index do |node|
+          node['type'] == 'heading' &&
+            extract_text_from_node(node).strip.downcase == heading_normalized
+        end
+
+        return { 'type' => 'doc', 'version' => 1, 'content' => [] } unless heading_idx
+
+        # Extract nodes after the heading until next same-level or higher heading
+        heading_level = content[heading_idx].dig('attrs', 'level') || 1
+        section_content = []
+
+        ((heading_idx + 1)...content.length).each do |i|
+          node = content[i]
+
+          # Stop if we hit another heading at same or higher level
+          if node['type'] == 'heading'
+            node_level = node.dig('attrs', 'level') || 1
+            break if node_level <= heading_level
+          end
+
+          section_content << node
+        end
+
+        { 'type' => 'doc', 'version' => 1, 'content' => section_content }
+      end
+
+      # Converts an ADF document (or fragment) to Markdown
+      #
+      # @param adf_doc [Hash] The ADF document to convert
+      # @param options [Hash] Conversion options
+      # @option options [Array<String>] :exclude_nodes Node types to exclude
+      # @return [String] The Markdown representation
+      def self.convert adf_doc, options = {}
+        return '' unless adf?(adf_doc)
+
+        excluded = options[:exclude_nodes] || default_excluded_nodes
+        content = adf_doc['content'] || []
+
+        converted = content.map { |node| convert_node(node, excluded) }
+        converted.join.strip
+      end
+
+      # Default nodes to exclude (headings, media, mentions, etc.)
+      def self.default_excluded_nodes
+        %w[heading media mediaGroup mediaSingle mediaInline mention emoji status inlineCard blockCard date]
+      end
+
+      # Converts a single ADF node to Markdown
+      #
+      # @param node [Hash] The ADF node
+      # @param excluded [Array<String>] Node types to exclude
+      # @param depth [Integer] Current nesting depth for lists
+      # @return [String] The Markdown representation
+      def self.convert_node node, excluded = [], depth = 0
+        return '' unless node.is_a?(Hash)
+        return '' if excluded.include?(node['type'])
+
+        case node['type']
+        when 'doc'
+          content = node['content'] || []
+          content.map { |n| convert_node(n, excluded, depth) }.join
+        when 'paragraph'
+          "#{convert_paragraph(node, excluded)}\n\n"
+        when 'bulletList'
+          convert_list(node, excluded, depth, unordered: true)
+        when 'orderedList'
+          convert_list(node, excluded, depth, unordered: false)
+        when 'listItem'
+          convert_list_item(node, excluded, depth)
+        when 'codeBlock'
+          convert_code_block(node)
+        when 'blockquote'
+          convert_blockquote(node, excluded)
+        when 'panel'
+          convert_panel(node, excluded)
+        when 'rule'
+          "\n---\n\n"
+        when 'table'
+          convert_table(node, excluded)
+        when 'tableRow'
+          convert_table_row(node, excluded)
+        when 'tableHeader', 'tableCell'
+          convert_table_cell(node, excluded)
+        when 'text'
+          apply_marks(node)
+        when 'hardBreak'
+          "  \n"
+        when 'taskList'
+          convert_task_list(node, excluded, depth)
+        when 'taskItem'
+          convert_task_item(node, excluded, depth)
+        else
+          # For unknown nodes, try to extract text content
+          ReleaseHx.logger.debug "Skipping unsupported ADF node type: #{node['type']}"
+          extract_text_from_node(node)
+        end
+      end
+
+      # Converts a paragraph node
+      def self.convert_paragraph node, excluded
+        content = node['content'] || []
+        content.map { |n| convert_node(n, excluded) }.join
+      end
+
+      # Converts a list (bullet or ordered)
+      def self.convert_list node, excluded, depth, unordered: true
+        content = node['content'] || []
+        items = content.map { |item| convert_node(item, excluded, depth + 1) }
+        "#{items.join}\n"
+      end
+
+      # Converts a list item
+      def self.convert_list_item node, excluded, depth
+        content = node['content'] || []
+        indent = '  ' * (depth - 1)
+        marker = '- '
+
+        # Separate paragraph content from nested lists
+        paragraphs = []
+        nested_lists = []
+
+        content.each do |n|
+          if n['type'] == 'paragraph'
+            paragraphs << convert_paragraph(n, excluded).strip
+          elsif %w[bulletList orderedList].include?(n['type'])
+            nested_lists << convert_node(n, excluded, depth)
+          else
+            paragraphs << convert_node(n, excluded, depth).strip
+          end
+        end
+
+        # Build the list item line
+        result = "#{indent}#{marker}#{paragraphs.join(' ')}\n"
+
+        # Add nested lists on new lines with proper indentation
+        nested_lists.each do |nested|
+          result += nested
+        end
+
+        result
+      end
+
+      # Converts a code block
+      def self.convert_code_block node
+        lang = node.dig('attrs', 'language') || ''
+        content = node['content'] || []
+        code = content.map { |n| n['type'] == 'text' ? n['text'] : '' }.join
+
+        "```#{lang}\n#{code}\n```\n\n"
+      end
+
+      # Converts a blockquote
+      def self.convert_blockquote node, excluded
+        content = node['content'] || []
+        lines = content.map { |n| convert_node(n, excluded).strip }.join("\n")
+        quoted = lines.split("\n").map { |line| "> #{line}" }.join("\n")
+        "#{quoted}\n\n"
+      end
+
+      # Converts a panel to a blockquote with admonition label
+      def self.convert_panel node, excluded
+        panel_type = node.dig('attrs', 'panelType') || 'info'
+        label = panel_type_to_label(panel_type)
+
+        content = node['content'] || []
+        text = content.map { |n| convert_node(n, excluded).strip }.join("\n")
+
+        "> **#{label}:** #{text}\n\n"
+      end
+
+      # Maps panel types to admonition labels
+      def self.panel_type_to_label panel_type
+        {
+          'info' => 'NOTE',
+          'note' => 'NOTE',
+          'warning' => 'WARNING',
+          'error' => 'CAUTION',
+          'success' => 'TIP'
+        }[panel_type] || 'NOTE'
+      end
+
+      # Converts a table (basic GFM table support)
+      def self.convert_table node, excluded
+        content = node['content'] || []
+        return '' if content.empty?
+
+        # Check if first row contains headers
+        first_row = content[0]
+        has_header = first_row && first_row['content']&.any? { |cell| cell['type'] == 'tableHeader' }
+
+        rows = content.map { |row| convert_node(row, excluded) }
+
+        if has_header
+          header = rows[0]
+          # Create separator row
+          col_count = first_row['content']&.length || 0
+          separator = "|#{' --- |' * col_count}\n"
+          table_body = rows[1..].join
+
+          "#{header}#{separator}#{table_body}\n"
+        else
+          "#{rows.join}\n"
+        end
+      end
+
+      # Converts a table row
+      def self.convert_table_row node, excluded
+        content = node['content'] || []
+        cells = content.map { |cell| convert_node(cell, excluded) }
+        "| #{cells.join(' | ')} |\n"
+      end
+
+      # Converts a table cell
+      def self.convert_table_cell node, excluded
+        content = node['content'] || []
+        content.map { |n| convert_node(n, excluded).strip }.join(' ')
+      end
+
+      # Converts a task list
+      def self.convert_task_list node, excluded, depth
+        content = node['content'] || []
+        content.map { |item| convert_node(item, excluded, depth + 1) }.join
+      end
+
+      # Converts a task item
+      def self.convert_task_item node, excluded, depth
+        state = node.dig('attrs', 'state')
+        marker = state == 'DONE' ? '[x]' : '[ ]'
+        indent = '  ' * (depth - 1)
+
+        content = node['content'] || []
+        text = content.map { |n| convert_node(n, excluded, depth).strip }.join(' ')
+
+        "#{indent}- #{marker} #{text}\n"
+      end
+
+      # Apply marks (bold, italic, code, link) to text
+      def self.apply_marks node
+        text = node['text'] || ''
+        marks = node['marks'] || []
+
+        marks.each do |mark|
+          case mark['type']
+          when 'strong'
+            text = "**#{text}**"
+          when 'em'
+            text = "_#{text}_"
+          when 'code'
+            text = "`#{text}`"
+          when 'link'
+            href = mark.dig('attrs', 'href') || ''
+            text = "[#{text}](#{href})"
+          when 'strike'
+            text = "~~#{text}~~"
+          when 'underline'
+            # Markdown doesn't have native underline; use HTML
+            text = "<u>#{text}</u>"
+          end
+        end
+
+        text
+      end
+
+      # Extract plain text from any node (recursive)
+      def self.extract_text_from_node node
+        return '' unless node.is_a?(Hash)
+
+        return node['text'] || '' if node['type'] == 'text'
+
+        content = node['content'] || []
+        content.map { |n| extract_text_from_node(n) }.join
+      end
+    end
+  end
+end

data/lib/releasehx/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative '../sourcerer'
+
+module ReleaseHx
+  VERSION = ReleaseHx::ATTRIBUTES[:globals]['this_prod_vrsn']
+end

data/lib/releasehx.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'thor'
+require 'logger'
+require 'liquid'
+require 'yaml'
+require_relative 'sourcerer'
+require_relative 'schemagraphy'
+begin
+  require_relative 'releasehx/generated'
+rescue LoadError
+  raise LoadError, 'ReleaseHx prebuild artifacts missing. Run `bundle exec rake prebuild`.'
+end
+require_relative 'releasehx/helpers'
+require_relative 'releasehx/configuration'
+require_relative 'releasehx/rhyml'
+require_relative 'releasehx/version'
+require_relative 'releasehx/sgyml/helpers'
+require_relative 'releasehx/ops/template_ops'
+require_relative 'releasehx/ops/check_ops'
+require_relative 'releasehx/ops/draft_ops'
+require_relative 'releasehx/ops/write_ops'
+require_relative 'releasehx/ops/enrich_ops'
+require_relative 'releasehx/rest/yaml_client'
+require_relative 'releasehx/transforms/adf_to_markdown'
+
+# The ReleaseHx module provides a CLI and a library for generating release
+# histories and changelogs from various sources like Jira, GitHub, and YAML files.
+module ReleaseHx
+  def self.attrs
+    if ENV['RELEASEHX_DEV_RELOAD'] == 'true'
+      # Development-only reload from source document
+      require 'asciidoctor' # explicitly required here for dev-only reload
+      Sourcerer.load_attributes(File.expand_path('../README.adoc', __dir__))
+    else
+      # Always use pre-generated attributes at runtime
+      ReleaseHx::ATTRIBUTES[:globals]
+    end
+  end
+
+  DUMP = Logger::DEBUG - 1 # Custom log level, lower than DEBUG
+
+  class << self
+    # Provides a singleton logger instance for the application.
+    #
+    # @return [Logger] The application-wide logger instance.
+    def logger
+      return @logger if @logger
+
+      $stdout.sync = true
+      log = Logger.new($stdout)
+      log.level = Logger::INFO
+      log.formatter = proc do |severity, _datetime, _progname, msg|
+        sev = severity == DUMP ? 'DUMP' : severity
+        "#{sev}: #{msg}\n"
+      end
+
+      log.singleton_class.class_eval do
+        define_method(:dump) do |msg|
+          add(DUMP, msg)
+        end
+      end
+
+      @logger = log
+    end
+  end
+
+  class Error < StandardError; end
+end

data/lib/schemagraphy/attribute_resolver.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module SchemaGraphy
+  # The AttributeResolver module provides methods for resolving AsciiDoc attribute references
+  # within a schema hash. It is used to substitute placeholders like `\{attribute_name}`
+  # with actual values.
+  module AttributeResolver
+    # Recursively walk a schema Hash and resolve `\{attribute_name}` references
+    # in 'dflt' values.
+    #
+    # @param schema [Hash] The schema or definition hash to process.
+    # @param attrs [Hash] The key-value pairs from AsciiDoc attributes to use for resolution.
+    # @return [Hash] The schema with resolved attributes.
+    def self.resolve_attributes! schema, attrs
+      case schema
+      when Hash
+        schema.transform_values! do |value|
+          if value.is_a?(Hash)
+            if value.key?('dflt') && value['dflt'].is_a?(String)
+              value['dflt'] = resolve_attribute_reference(value['dflt'], attrs)
+            end
+            resolve_attributes!(value, attrs)
+          else
+            value
+          end
+        end
+      end
+      schema
+    end
+
+    # Replace `\{attribute_name}` patterns with corresponding values from the attrs hash.
+    #
+    # @param value [String] The string to process.
+    # @param attrs [Hash] The attributes to use for resolution.
+    # @return [String] The processed string with attribute references replaced.
+    def self.resolve_attribute_reference value, attrs
+      # Handle \{attribute_name} references
+      if value.match?(/\{[^}]+\}/)
+        value.gsub(/\{([^}]+)\}/) do |match|
+          attr_name = ::Regexp.last_match(1)
+          attrs[attr_name] || match # Keep original if no matching attribute
+        end
+      else
+        value
+      end
+    end
+  end
+end

data/lib/schemagraphy/cfgyml/definition.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative '../loader'
+require_relative '../schema_utils'
+
+module SchemaGraphy
+  # A module for handling CFGYML, a schema-driven configuration system.
+  module CFGYML
+    # Represents a configuration definition loaded from a schema file.
+    # It provides methods for accessing defaults and rendering documentation.
+    class Definition
+      # @return [Hash] The loaded schema hash.
+      attr_reader :schema
+
+      # @return [Hash] The attributes used for resolving placeholders in the schema.
+      attr_reader :attributes
+
+      # @param schema_path [String] The path to the schema YAML file.
+      # @param attrs [Hash] A hash of attributes for placeholder resolution.
+      def initialize schema_path, attrs = {}
+        @schema = Loader.load_yaml_with_attributes(schema_path, attrs)
+        @attributes = attrs
+      end
+
+      # Extract default values from the loaded schema.
+      # @return [Hash] A hash of default values.
+      def defaults
+        SchemaUtils.crawl_defaults(@schema)
+      end
+
+      # Get the search paths for templates.
+      # @return [Array<String>] An array of template paths.
+      def template_paths
+        @template_paths ||= [
+          File.join(File.dirname(__FILE__), '..', 'templates', 'cfgyml'),
+          *additional_template_paths
+        ]
+      end
+
+      # Render a configuration reference or sample in the specified format.
+      #
+      # @param format [Symbol] The output format (`:adoc` or `:yaml`).
+      # @return [String] The rendered output.
+      # @raise [ArgumentError] if the format is unsupported.
+      def render_reference format = :adoc
+        template = case format
+                   when :adoc
+                     'config-reference.adoc.liquid'
+                   when :yaml
+                     'sample-config.yaml.liquid'
+                   else
+                     raise ArgumentError, "Unsupported format: #{format}"
+                   end
+
+        render_template(template)
+      end
+
+      private
+
+      # Render a template using the Liquid engine.
+      def render_template template_name
+        template_path = find_template(template_name)
+        raise "Template not found: #{template_name}" unless template_path
+
+        require 'liquid'
+        template_content = File.read(template_path)
+        template = Liquid::Template.parse(template_content)
+
+        template.render(
+          'config_def' => @schema,
+          'attrs' => @attributes)
+      end
+
+      # Find a template file in the configured template paths.
+      def find_template name
+        template_paths.each do |path|
+          file = File.join(path, name)
+          return file if File.exist?(file)
+        end
+        nil
+      end
+
+      # Provides an extension point for subclasses to add more template paths.
+      def additional_template_paths
+        # Can be overridden by subclasses
+        []
+      end
+    end
+  end
+end

data/lib/schemagraphy/cfgyml/doc_builder.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module SchemaGraphy
+  module CFGYML
+    # Builds documentation-friendly CFGYML references for machine consumption.
+    module DocBuilder
+      module_function
+
+      def call schema, options = {}
+        pretty = options.fetch(:pretty, true)
+        data = reference_hash(schema)
+        pretty ? JSON.pretty_generate(data) : JSON.generate(data)
+      end
+
+      def reference_hash schema
+        {
+          'format' => 'releasehx-config-reference',
+          'version' => 1,
+          'properties' => build_properties(schema['properties'], [])
+        }
+      end
+
+      def build_properties properties, path
+        return {} unless properties.is_a?(Hash)
+
+        properties.each_with_object({}) do |(key, definition), acc|
+          next unless definition.is_a?(Hash)
+
+          current_path = path + [key]
+          entry = build_entry(current_path, definition)
+          children = build_properties(definition['properties'], current_path)
+          entry['properties'] = children unless children.empty?
+          acc[key] = entry
+        end
+      end
+
+      def build_entry path, definition
+        entry = {
+          'path' => path.join('.'),
+          'desc' => definition['desc'],
+          'docs' => definition['docs'],
+          'type' => definition['type'],
+          'templating' => definition['templating'],
+          'default' => definition.key?('dflt') ? definition['dflt'] : nil
+        }
+        entry.compact
+      end
+    end
+  end
+end

data/lib/schemagraphy/cfgyml/path_reference.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module SchemaGraphy
+  module CFGYML
+    # Loads and queries a JSON config reference using JSON Pointer.
+    class PathReference
+      def initialize data
+        @data = data
+      end
+
+      def self.load path
+        new(JSON.parse(File.read(path)))
+      end
+
+      def get pointer
+        SchemaGraphy::DataQuery::JSONPointer.resolve(@data, pointer)
+      end
+    end
+
+    Reference = PathReference
+  end
+end

data/lib/schemagraphy/data_query/json_pointer.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module SchemaGraphy
+  module DataQuery
+    # Resolves JSON Pointer queries against a Hash or Array.
+    module JSONPointer
+      module_function
+
+      def resolve data, pointer
+        return data if pointer.nil? || pointer == ''
+        raise ArgumentError, "Invalid JSON Pointer: #{pointer}" unless pointer.start_with?('/')
+
+        tokens = pointer.split('/')[1..]
+        tokens.reduce(data) do |current, token|
+          key = unescape(token)
+          resolve_token(current, key, pointer)
+        end
+      end
+
+      def resolve_token current, key, pointer
+        case current
+        when Array
+          index = Integer(key, 10)
+          current.fetch(index)
+        when Hash
+          return current.fetch(key) if current.key?(key)
+          return current.fetch(key.to_sym) if current.key?(key.to_sym)
+
+          raise KeyError, "JSON Pointer not found: #{pointer}"
+        else
+          raise KeyError, "JSON Pointer not found: #{pointer}"
+        end
+      rescue ArgumentError, IndexError, KeyError
+        raise KeyError, "JSON Pointer not found: #{pointer}"
+      end
+
+      def unescape token
+        token.gsub('~1', '/').gsub('~0', '~')
+      end
+    end
+  end
+end