releasehx 0.1.0

data/lib/schemagraphy/templating.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'tilt'
+require_relative '../sourcerer/templating'
+
+# frozen_string_literal: true
+
+module SchemaGraphy
+  # A module for handling templated fields within a data structure based on a schema or definition.
+  # It provides methods for pre-compiling and rendering fields using various template engines.
+  module Templating
+    extend Sourcerer::Templating
+
+    # Renders a field if it is a template.
+    #
+    # @param field [Object] The field to render.
+    # @param context [Hash] The context to use for rendering.
+    # @return [Object] The rendered field, or the original field if it's not a template.
+    def self.resolve_field field, context = {}
+      render_field_if_template(field, context)
+    end
+
+    # Recursively pre-compiles templated fields in a data structure based on a schema.
+    #
+    # @param data [Hash] The data to process.
+    # @param schema [Hash] The schema defining which fields are templated.
+    # @param base_path [String] The base path for the current data level.
+    # @param scope [Hash] The scope to use for compilation.
+    def self.precompile_from_schema! data, schema, base_path = '', scope: {}
+      return unless data.is_a?(Hash)
+
+      data.each do |key, value|
+        path = [base_path, key].reject(&:empty?).join('.')
+
+        precompile_from_schema!(value, schema, path, scope: scope) if value.is_a?(Hash)
+
+        next unless SchemaGraphy::SchemaUtils.templated_field?(schema, path)
+
+        compile_templated_fields!(
+          data: data,
+          schema: schema,
+          fields: [{ key: key, path: path }],
+          scope: scope)
+      end
+    end
+
+    # An alias for the `Sourcerer::Templating::TemplatedField` class.
+    TemplatedField = Sourcerer::Templating::TemplatedField
+
+    # Compiles templated fields in the data.
+    #
+    # @param data [Hash] The data containing the fields to compile.
+    # @param schema [Hash] The schema definition.
+    # @param fields [Array<Hash>] An array of fields to compile, each with a `:key` and `:path`.
+    # @param scope [Hash] The scope to use for compilation.
+    def self.compile_templated_fields! data:, schema:, fields:, scope: {}
+      fields.each do |entry|
+        key  = entry[:key]
+        path = entry[:path]
+        val  = data[key]
+
+        next unless val.is_a?(String) || (val.is_a?(Hash) && val['__tag__'] && val['value'])
+
+        raw     = val.is_a?(Hash) ? val['value'] : val
+        tagged  = val.is_a?(Hash)
+        config  = SchemaGraphy::SchemaUtils.templating_config_for(schema, path)
+        engine  = tagged ? val['__tag__'] : (config['default'] || 'liquid')
+
+        compiled = Sourcerer::Templating::Engines.compile(raw, engine)
+
+        data[key] = if config['delay']
+                      Sourcerer::Templating::TemplatedField.new(raw, compiled, engine, tagged, inferred: !tagged)
+                    else
+                      Sourcerer::Templating::Engines.render(compiled, engine, scope)
+                    end
+      end
+    end
+
+    # Recursively renders all pre-compiled templated fields in a data structure.
+    #
+    # @param data [Hash, Array] The data structure to process.
+    # @param context [Hash] The context to use for rendering.
+    def self.render_all_templated_fields! data, context = {}
+      return unless data.is_a?(Hash)
+
+      data.each do |key, value|
+        case value
+        when TemplatedField
+          data[key] = value.render(context)
+        when Hash
+          render_all_templated_fields!(value, context)
+        when Array
+          value.each_with_index do |item, idx|
+            if item.is_a?(TemplatedField)
+              value[idx] = item.render(context)
+            elsif item.is_a?(Hash)
+              render_all_templated_fields!(item, context)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/schemagraphy.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative 'schemagraphy/loader'
+require_relative 'schemagraphy/tag_utils'
+require_relative 'schemagraphy/schema_utils'
+require_relative 'schemagraphy/templating'
+require_relative 'schemagraphy/regexp_utils'
+require_relative 'schemagraphy/cfgyml/doc_builder'
+require_relative 'schemagraphy/data_query/json_pointer'
+require_relative 'schemagraphy/cfgyml/path_reference'
+
+# SchemaGraphy is a component for working with schema-driven data structures and extending YAML with robust typing and dynamic directives.
+# It provides utilities for loading, validating, and transforming data based on
+# a schema definition, with a focus on templating and safe expression evaluation.
+# This module is under early development and will be spun off as its own gem after ReleaseHx is generally available.
+module SchemaGraphy
+end

data/lib/sourcerer/builder.rb

@@ -0,0 +1,120 @@
+# lib/sourcerer/builder.rb
+# frozen_string_literal: true
+
+require 'asciidoctor'
+require 'fileutils'
+require_relative '../sourcerer'
+
+module Sourcerer
+  # A build-time code generator that creates assets such as new data, documentation, and even Ruby files from
+  # data extracted from AsciiDoc files, such as attributes and tagged regions.
+  module Builder
+    # Generates a Ruby file at build-time to be used during the build process.
+    #
+    # @param generated [Hash] A hash with `:path` and `:module` for the generated file.
+    # @param attributes [Array<Hash>] A list of attribute sources to build.
+    # @param snippets [Array<Hash>] A list of snippets to build.
+    # @param regions [Array<Hash>] A list of tagged regions to build.
+    # @param templates [Array<Hash>] A list of templates to build (currently unused).
+    # @param render [Array<Hash>] A list of render entries (currently unused).
+    # rubocop:disable Lint/UnusedMethodArgument
+    def self.generate_prebuild generated: {}, attributes: [], snippets: [], regions: [], templates: [], render: []
+      # rubocop:enable Lint/UnusedMethodArgument
+      # NOTE: templates/render parameters are accepted from config but handled separately by Sourcerer.render_outputs
+      attr_result     = build_attributes(attributes)
+      snippet_lookup  = build_outputs(snippets, type: :snippet)
+      region_lookup   = build_outputs(regions, type: :region)
+
+      File.write(generated[:path].to_s, <<~RUBY)
+        # frozen_string_literal: true
+        # Auto-generated by Sourcerer::Builder
+
+        module #{generated[:module]}
+          ATTRIBUTES = #{attr_result.inspect}
+
+          SNIPPET_LOOKUP = #{snippet_lookup.inspect}
+
+          REGION_LOOKUP = #{region_lookup.inspect}
+
+          def self.read_built_snippet name
+            fname = SNIPPET_LOOKUP[name.to_s] || name.to_s
+            path = File.expand_path("../../../build/snippets/\#{fname}", __FILE__)
+            raise "Snippet not found: \#{name}" unless File.exist?(path)
+            File.read(path)
+          end
+        end
+      RUBY
+    end
+
+    # @api private
+    # Builds a hash of attributes from the given sources.
+    # @param attributes [Array<Hash>] The attribute sources.
+    # @return [Hash] The built attributes.
+    def self.build_attributes attributes
+      attributes.each_with_object({}) do |entry, acc|
+        source = entry[:source]
+        name   = entry[:name] || File.basename(source, '.adoc').to_sym
+        acc[name.to_sym] = Sourcerer.load_attributes(source)
+      end
+    end
+
+    # @api private
+    # Builds output files from snippets or regions and returns a lookup hash.
+    # @param entries [Array<Hash>] The entries to build.
+    # @param type [Symbol] The type of output (`:snippet` or `:region`).
+    # @return [Hash] A lookup hash mapping names to output filenames.
+    def self.build_outputs entries, type:
+      lookup   = {}
+      names    = []
+      outnames = []
+
+      entries.each do |entry|
+        source = entry[:source] or raise ArgumentError, "#{type} entry is missing :source"
+        tag    = entry[:tag]
+        tags   = entry[:tags]
+
+        raise ArgumentError, 'use only one of :tag or :tags' if tag && tags
+        raise ArgumentError, "#{type} must include a :tag or :tags" unless tag || tags
+
+        name    = entry[:name] || tag || File.basename(source, '.adoc')
+        outname = entry[:out]  || default_output_name(name, type)
+
+        raise ArgumentError, "name value must be unique; #{name} already used"   if names.include? name
+        raise ArgumentError, "out value must be unique; #{outname} already used" if outnames.include? outname
+
+        names    << name
+        outnames << outname
+
+        tags = [tag] if tag
+
+        text =
+          case type
+          when :snippet then Sourcerer.load_include(source, tags: tags)
+          when :region  then Sourcerer.extract_tagged_content(source, tags: tags)
+          else raise ArgumentError, "Unsupported type: #{type}"
+          end
+
+        lookup[name.to_s] = outname
+
+        outpath = File.join("build/#{type}s", outname)
+        FileUtils.mkdir_p File.dirname(outpath)
+        File.write(outpath, text)
+      end
+
+      lookup
+    end
+
+    # @api private
+    # Determines the default output filename for a given name and type.
+    # @param name [String] The name of the output.
+    # @param type [Symbol] The type of output.
+    # @return [String] The default filename.
+    def self.default_output_name name, type
+      case type
+      when :snippet then "#{name}.txt"
+      when :region  then "#{name}.adoc"
+      else raise ArgumentError, "Unknown type: #{type}"
+      end
+    end
+  end
+end

data/lib/sourcerer/jekyll/bootstrapper.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'jekyll'
+require 'jekyll-asciidoc'
+
+module Sourcerer
+  module Jekyll
+    # This module provides methods for programmatically setting up a Jekyll site
+    # environment, which is useful for loading plugins or creating a mock site for rendering.
+    module Bootstrapper
+      # Loads Jekyll plugins from specified directories.
+      #
+      # @param plugin_dirs [Array<String>] A list of directories to search for plugins.
+      # @return [Jekyll::Site] The initialized Jekyll site object.
+      def self.load_plugins plugin_dirs: []
+        config = ::Jekyll.configuration(
+          {
+            'source'      => Dir.pwd,
+            'destination' => File.join(Dir.pwd, '_site'),
+            'quiet'       => true,
+            'skip_config_files' => true,
+            'plugins_dir' => plugin_dirs.map { |d| File.expand_path(d) },
+            'disable_disk_cache' => true
+          })
+
+        site = ::Jekyll::Site.new(config)
+        site.plugin_manager.conscientious_require
+
+        ::Jekyll::Hooks.trigger :site, :after_init, site
+
+        site
+      end
+
+      # Creates an ephemeral Jekyll site instance for rendering purposes.
+      # This is useful for leveraging Jekyll's templating outside of a full site build.
+      #
+      # @param includes_load_paths [Array<String>] Paths to load includes from.
+      # @param plugin_dirs [Array<String>] Paths to load plugins from.
+      # @return [Jekyll::Site] The initialized fake Jekyll site object.
+      # rubocop:disable Lint/UnusedMethodArgument
+      def self.fake_site includes_load_paths: [], plugin_dirs: []
+        # NOTE: plugin_dirs parameter is accepted but not yet implemented; reserved for future plugin loading
+        ::Jekyll.logger.log_level = :error if ::Jekyll.logger.respond_to?(:log_level=)
+
+        config = ::Jekyll.configuration(
+          'source'              => Dir.pwd,
+          'includes_dir'        => includes_load_paths.first,
+          'includes_load_paths' => includes_load_paths,
+          'destination'         => File.join(Dir.pwd, '_site'),
+          'quiet'               => true,
+          'skip_config_files'   => true,
+          'disable_disk_cache'  => true)
+
+        site = ::Jekyll::Site.new(config)
+
+        include_paths = site.includes_load_paths || []
+        site.inclusions ||= {}
+
+        include_paths.each do |dir|
+          Dir[File.join(dir, '**/*')].each do |file|
+            next unless File.file?(file)
+
+            relative_path = file.sub("#{dir}/", '')
+            site.inclusions[relative_path] = File.read(file)
+          end
+        end
+
+        site.instance_variable_set(:@liquid_renderer, ::Jekyll::LiquidRenderer.new(site))
+
+        plugin_manager = ::Jekyll::PluginManager.new(site)
+        plugin_manager.conscientious_require
+
+        site
+      end
+      # rubocop:enable Lint/UnusedMethodArgument
+    end
+  end
+end

data/lib/sourcerer/jekyll/liquid/file_system.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'liquid'
+
+module Sourcerer
+  module Jekyll
+    module Liquid
+      # A custom Liquid file system that extends `Liquid::LocalFileSystem` to support
+      # multiple root paths for template lookups. This allows templates to be
+      # resolved from a prioritized list of directories.
+      class FileSystem < ::Liquid::LocalFileSystem
+        # Initializes the file system with one or more root paths.
+        #
+        # @param roots_or_root [String, Array<String>] A single root path or an array of root paths.
+        # rubocop:disable Lint/MissingSuper
+        # Intentional: Custom implementation that doesn't need parent's initialization
+        def initialize roots_or_root
+          if roots_or_root.is_a?(Array)
+            @roots = roots_or_root.map { |root| File.expand_path(root) }
+            @multi_root = true
+          else
+            @root = File.expand_path(roots_or_root)
+            @multi_root = false
+          end
+        end
+        # rubocop:enable Lint/MissingSuper
+
+        # Finds the full path of a template, searching through multiple roots if configured.
+        #
+        # @param template_path [String] The path to the template.
+        # @return [String] The full, validated path to the template.
+        # @raise [Liquid::FileSystemError] if the template is not found.
+        def full_path template_path
+          if @multi_root
+            @roots.each do |root|
+              full = File.expand_path(File.join(root, template_path))
+              return full if File.exist?(full) && full.start_with?(root)
+            end
+            raise ::Liquid::FileSystemError, "Template not found: '#{template_path}' in paths: #{@roots}"
+          else
+            full = File.expand_path(File.join(@root, template_path))
+            validate_path(full)
+          end
+        end
+
+        # Reads the content of a template file.
+        #
+        # @param template_path [String] The path to the template.
+        # @return [String] The content of the template file.
+        def read_template_file template_path
+          path = full_path(template_path)
+          File.read(path)
+        end
+
+        private
+
+        # Validates that the resolved path is within the allowed root(s).
+        def validate_path path
+          if @multi_root
+            # Check if path starts with any of the allowed roots
+            unless @roots.any? { |root| path.start_with?(root) }
+              raise ::Liquid::FileSystemError, "Illegal template path '#{path}'"
+            end
+
+          else
+            raise ::Liquid::FileSystemError, "Illegal template path '#{path}'" unless path.start_with?(@root)
+
+          end
+          path
+        end
+      end
+    end
+  end
+end

data/lib/sourcerer/jekyll/liquid/filters.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require 'kramdown-asciidoc'
+require 'base64'
+require 'cgi'
+
+module Sourcerer
+  module Jekyll
+    module Liquid
+      # This module provides a set of custom filters for use in Liquid templates.
+      module Filters
+        # Renders a Liquid template string with a given scope.
+        # @param input [String, Object] The Liquid template string or a pre-parsed template object.
+        # @param vars [Hash] A hash of variables to use as the scope.
+        # @return [String] The rendered output.
+        def render input, vars = nil
+          scope = if vars.is_a?(Hash)
+                    vars.transform_keys(&:to_s)
+                  else
+                    {}
+                  end
+
+          template =
+            if input.respond_to?(:render) && input.respond_to?(:templated?) && input.templated?
+              input
+            else
+              ::Liquid::Template.parse(input.to_s)
+            end
+
+          template.render(scope)
+        end
+
+        # Converts a string into a slug.
+        # @param input [String] The string to convert.
+        # @param format [String] The desired format (`kebab`, `snake`, `camel`, `pascal`).
+        # @return [String] The sluggerized string.
+        def sluggerize input, format = 'kebab'
+          return input unless input.is_a? String
+
+          case format
+          when 'kebab' then input.downcase.gsub(/[\s\-_]/, '-')
+          when 'snake' then input.downcase.gsub(/[\s\-_]/, '_')
+          when 'camel' then input.downcase.gsub(/[\s\-_]/, '_').camelize(:lower)
+          when 'pascal' then input.downcase.gsub(/[\s\-_]/, '_').camelize(:upper)
+          else input
+          end
+        end
+
+        # Replaces double newlines with a newline and a plus sign.
+        # @param input [String] The input string.
+        # @return [String] The processed string.
+        def plusify input
+          input.gsub(/\n\n+/, "\n+\n")
+        end
+
+        # Converts a Markdown string to AsciiDoc.
+        # @param input [String] The Markdown string.
+        # @param wrap [String] The wrapping option for the converter.
+        # @return [String] The converted AsciiDoc string.
+        def md_to_adoc input, wrap = 'ventilate'
+          options = {}
+          options[:wrap] = wrap.to_sym if wrap
+          Kramdoc.convert(input, options)
+        end
+
+        # Indents a string by a given number of spaces.
+        # @param input [String] The string to indent.
+        # @param spaces [Integer] The number of spaces for indentation.
+        # @param line1 [Boolean] Whether to indent the first line.
+        # @return [String] The indented string.
+        def indent input, spaces = 2, line1: false
+          indent = ' ' * spaces
+          lines = input.split("\n")
+          indented = if line1
+                       lines.map { |line| indent + line }
+                     else
+                       lines.map.with_index { |line, i| i.zero? ? line : indent + line }
+                     end
+          indented.join("\n")
+        end
+
+        # Checks the type of a value in the context of SG-YML.
+        # @param input [Object] The value to check.
+        # @return [String] A string representing the type.
+        def sgyml_type_check input
+          if input.nil?
+            'Null:nil'
+          elsif input.is_a? Array
+            # if all items in Array are (integer, float, string, boolean)
+            if input.all? do |item|
+              item.is_a?(Integer) || item.is_a?(Float) || item.is_a?(String) ||
+              item.is_a?(TrueClass) || item.is_a?(FalseClass)
+            end
+              'Compound:ArrayList'
+            elsif input.all? { |item| item.is_a?(Hash) && (item.keys.length >= 2) }
+              'Compound:ArrayTable'
+            else
+              'Compound:Array'
+            end
+          elsif input.is_a? Hash
+            if input.values.all? { |value| value.is_a?(Hash) && (value.keys.length >= 2) }
+              'Compound:MapTable'
+            else
+              'Compound:Map'
+            end
+          elsif input.is_a? String
+            'Scalar:String'
+          elsif input.is_a? Integer
+            'Scalar:Number'
+          elsif input.is_a? Time
+            'Scalar:DateTime'
+          elsif input.is_a? Float
+            'Scalar:Float'
+          elsif input.is_a?(TrueClass) || input.is_a?(FalseClass)
+            'Scalar:Boolean'
+          else
+            'unknown:unknown'
+          end
+        end
+
+        # Returns the Ruby class name of a value.
+        # @param input [Object] The value.
+        # @return [String] The class name.
+        def ruby_class input
+          input.class.name
+        end
+
+        # Removes markup from a string.
+        # @param input [String] The string to demarkupify.
+        # @return [String] The demarkupified string.
+        def demarkupify input
+          return input unless input.is_a? String
+
+          input = input.gsub(/`"|"`/, '"')
+          input = input.gsub(/'`|`'/, "'")
+          input = input.gsub(/[*_`]/, '')
+          # change curly quotes to striaght quotes
+          input = input.gsub(/[“”]/, '"')
+          input.gsub(/[‘’]/, "'")
+        end
+
+        # Dumps a value to YAML format.
+        # @param input [Object] The value to dump.
+        # @return [String] The YAML representation.
+        def inspect_yaml input
+          require 'yaml'
+          YAML.dump(input)
+        end
+
+        # Base64 encodes a string.
+        # @param input [String] The string to encode.
+        # @return [String] The Base64-encoded string.
+        def base64 input
+          return input unless input.is_a? String
+
+          Base64.strict_encode64(input)
+        end
+
+        # Decodes a Base64-encoded string.
+        # @param input [String] The string to decode.
+        # @return [String] The decoded string.
+        def base64_decode input
+          return input unless input.is_a? String
+
+          Base64.strict_decode64(input)
+        rescue ArgumentError
+          # Return original input if decoding fails
+          input
+        end
+
+        # URL-encodes a string.
+        # @param input [String] The string to encode.
+        # @return [String] The URL-encoded string.
+        def url_encode input
+          return input unless input.is_a? String
+
+          CGI.escape(input)
+        end
+
+        # Decodes a URL-encoded string.
+        # @param input [String] The string to decode.
+        # @return [String] The decoded string.
+        def url_decode input
+          return input unless input.is_a? String
+
+          CGI.unescape(input)
+        rescue ArgumentError
+          # Return original input if decoding fails
+          input
+        end
+
+        # HTML-escapes a string.
+        # @param input [String] The string to escape.
+        # @return [String] The HTML-escaped string.
+        def html_escape input
+          return input unless input.is_a? String
+
+          CGI.escapeHTML(input)
+        end
+
+        # Unescapes an HTML-escaped string.
+        # @param input [String] The string to unescape.
+        # @return [String] The unescaped string.
+        def html_unescape input
+          return input unless input.is_a? String
+
+          CGI.unescapeHTML(input)
+        end
+      end
+    end
+  end
+end
+
+# Register the filters automatically
+Liquid::Template.register_filter(Sourcerer::Jekyll::Liquid::Filters)

data/lib/sourcerer/jekyll/liquid/tags.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Sourcerer
+  module Jekyll
+    # This module contains custom Liquid tags for the Sourcerer templating environment.
+    module Tags
+      # A Liquid tag for embedding and rendering a file within a template.
+      # It searches for the file in the configured include paths.
+      class EmbedTag < ::Liquid::Tag
+        # @param tag_name [String] The name of the tag ('embed').
+        # @param markup [String] The name of the partial to embed.
+        # @param tokens [Array<String>] The list of tokens.
+        def initialize tag_name, markup, tokens
+          super
+          @partial_name = markup.strip
+        end
+
+        # Renders the embedded file.
+        #
+        # @param context [Liquid::Context] The Liquid context.
+        # @return [String] The rendered content of the embedded file.
+        # @raise [IOError] if the embed file is not found.
+        def render context
+          includes_paths = context.registers[:includes_load_paths] || []
+
+          found_path = includes_paths.find do |base|
+            candidate = File.expand_path(@partial_name, base)
+            File.exist?(candidate)
+          end
+
+          raise "Embed file not found: #{@partial_name}" unless found_path
+
+          full_path = File.expand_path(@partial_name, found_path)
+          source = File.read(full_path)
+
+          partial = ::Liquid::Template.parse(source)
+          partial.render!(context)
+        end
+      end
+    end
+  end
+end
+
+Liquid::Template.register_tag('embed', Sourcerer::Jekyll::Tags::EmbedTag)