releasehx 0.1.0

data/lib/schemagraphy/loader.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'psych'
+require_relative 'attribute_resolver'
+
+module SchemaGraphy
+  # The Loader class provides methods for loading YAML files while preserving
+  # custom tags and resolving attribute references.
+  class Loader
+    # Load a YAML file and resolve AsciiDoc attribute references like `\{attribute_name}`.
+    #
+    # @param path [String] The path to the YAML file.
+    # @param attrs [Hash] The AsciiDoc attributes to use for resolution.
+    # @return [Hash] The loaded YAML data with attributes resolved.
+    def self.load_yaml_with_attributes path, attrs = {}
+      raw_data = load_yaml_with_tags(path)
+      AttributeResolver.resolve_attributes!(raw_data, attrs)
+      raw_data
+    end
+
+    # Load a YAML file, preserving any custom tags (e.g., `!foo`).
+    # Custom tags are attached to the data structure.
+    #
+    # @param path [String] The path to the YAML file.
+    # @return [Hash] The loaded YAML data with custom tags attached.
+    def self.load_yaml_with_tags path
+      return {} if File.empty?(path)
+
+      data = Psych.load_file(path, aliases: true, permitted_classes: [Date, Time])
+      ast  = Psych.parse_file(path)
+      attach_tags(ast.root, data)
+      data
+    end
+
+    # Recursively attach YAML tags to the loaded data structure for template processing.
+    #
+    # @param node [Psych::Nodes::Node] The current AST node.
+    # @param data [Object] The data corresponding to the current node.
+    # @api private
+    def self.attach_tags node, data
+      return unless node.is_a?(Psych::Nodes::Mapping)
+
+      node.children.each_slice(2) do |key_node, val_node|
+        key = key_node.value
+
+        if val_node.respond_to?(:tag) && val_node.tag && data[key].is_a?(String)
+          normalized_tag = val_node.tag.sub(/^!+/, '').sub(/^.*:/, '')
+          data[key] = {
+            'value' => data[key],
+            '__tag__' => normalized_tag
+          }
+        elsif data[key].is_a?(Hash)
+          attach_tags(val_node, data[key])
+        end
+      end
+    end
+  end
+end

data/lib/schemagraphy/regexp_utils.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require 'to_regexp'
+
+module SchemaGraphy
+  # A utility module for robustly parsing and using regular expressions.
+  # It handles various formats, including literals and plain strings,
+  # and provides helpers for extracting captured content.
+  module RegexpUtils
+    module_function
+
+    # Parse a regex pattern string using the `to_regexp` gem for robust parsing.
+    # Handles `/pattern/flags`, `%r{pattern}flags`, and plain text formats.
+    #
+    # @example
+    #   parse_pattern("/^hello.*$/im")
+    #   # => { pattern: "^hello.*$", flags: "im", regexp: /^hello.*$/im, options: 6 }
+    #
+    # @example
+    #   parse_pattern("hello world")
+    #   # => { pattern: "hello world", flags: "", regexp: /hello world/, options: 0 }
+    #
+    # @example
+    #   parse_pattern("hello world", "i")
+    #   # => { pattern: "hello world", flags: "i", regexp: /hello world/i, options: 1 }
+    #
+    # @param input [String] The input string, e.g., "/pattern/flags" or "plain pattern".
+    # @param default_flags [String] Default flags to apply if none are specified (default: "").
+    # @return [Hash, nil] A hash with `:pattern`, `:flags`, `:regexp`, and `:options`, or `nil`.
+    def parse_pattern input, default_flags = ''
+      return nil if input.nil? || input.to_s.strip.empty?
+
+      input_str = input.to_s.strip
+
+      # Remove surrounding quotes that might come from YAML parsing
+      clean_input = input_str.gsub(/^["']|["']$/, '')
+
+      # Heuristic to detect if it's a Regexp literal
+      is_literal = (clean_input.start_with?('/') && clean_input.rindex('/').positive?) || clean_input.start_with?('%r{')
+
+      if is_literal
+        # Try to parse as regex literal using to_regexp
+        begin
+          regexp_obj = clean_input.to_regexp(detect: true)
+
+          # Extract pattern and flags from the compiled regexp
+          pattern_str = regexp_obj.source
+          flags_str = extract_flags_from_regexp(regexp_obj)
+
+          {
+            pattern: pattern_str,
+            flags: flags_str,
+            regexp: regexp_obj,
+            options: regexp_obj.options
+          }
+        rescue RegexpError => e
+          # Malformed literal is an error
+          raise RegexpError, "Invalid regex literal '#{input}': #{e.message}"
+        end
+      else
+        # Treat as plain pattern string with default flags
+        flags_str = default_flags.to_s
+        options = flags_to_options(flags_str)
+
+        begin
+          regexp_obj = Regexp.new(clean_input, options)
+
+          {
+            pattern: clean_input,
+            flags: flags_str,
+            regexp: regexp_obj,
+            options: options
+          }
+        rescue RegexpError => e
+          raise RegexpError, "Invalid regex pattern '#{input}': #{e.message}"
+        end
+      end
+    end
+
+    # @note Not yet implemented.
+    # Future enhancement to parse structured pattern definitions from a Hash.
+    # @param pattern_hash [Hash] A hash with 'pattern' and 'flags' keys.
+    # @raise [NotImplementedError] Always raises this error.
+    def parse_structured_pattern pattern_hash
+      # TODO: Implement structured pattern parsing
+      # pattern_hash should have 'pattern' and 'flags' keys
+      # flags can be string or array
+      raise NotImplementedError, 'Structured pattern parsing not yet implemented'
+    end
+
+    # @note Not yet implemented.
+    # Future enhancement to parse custom YAML tags for regular expressions.
+    # @param tagged_input [String] The input string with a YAML tag.
+    # @param tag_type [Symbol] The type of tag, e.g., `:literal` or `:pattern`.
+    # @raise [NotImplementedError] Always raises this error.
+    def parse_tagged_pattern tagged_input, tag_type
+      # TODO: Implement custom YAML tag parsing
+      # tag_type would be :literal or :pattern
+      raise NotImplementedError, 'Tagged pattern parsing not yet implemented'
+    end
+
+    # Convert a flags string (ex: "im") to a Regexp options integer.
+    #
+    # @param flags [String] String containing regex flags.
+    # @return [Integer] Regexp options integer.
+    def flags_to_options flags
+      options = 0
+      flags = flags.to_s
+
+      options |= Regexp::IGNORECASE if flags.include?('i')
+      options |= Regexp::MULTILINE if flags.include?('m')
+      options |= Regexp::EXTENDED if flags.include?('x')
+
+      # NOTE: 'g' (global) and 'o' (once) are not standard Ruby flags
+      # encoding flags ('n', 'e', 's', 'u') are handled by to_regexp
+
+      options
+    end
+
+    # Extract a flags string from a compiled Regexp object.
+    #
+    # @param regexp [Regexp] A compiled regexp object.
+    # @return [String] String representation of the flags (e.g., "im").
+    def extract_flags_from_regexp regexp
+      flags = ''
+      flags += 'i' if regexp.options.anybits?(Regexp::IGNORECASE)
+      flags += 'm' if regexp.options.anybits?(Regexp::MULTILINE)
+      flags += 'x' if regexp.options.anybits?(Regexp::EXTENDED)
+      flags
+    end
+
+    # Create a Regexp object from a pattern string and explicit flags.
+    #
+    # @param pattern [String] The regex pattern (without delimiters).
+    # @param flags [String] The flags string (ex: "im").
+    # @return [Regexp] The compiled Regexp object.
+    def create_regexp pattern, flags = ''
+      options = flags_to_options(flags)
+      Regexp.new(pattern, options)
+    end
+
+    # Extract content using named or positional capture groups.
+    #
+    # @param text [String] The text to match against.
+    # @param pattern_info [Hash] The hash result from `parse_pattern`.
+    # @param capture_name [String] The name of the capture group to extract (optional).
+    # @return [String, nil] The extracted text, or `nil` if no match is found.
+    def extract_capture text, pattern_info, capture_name = nil
+      return nil unless text && pattern_info
+
+      regexp = pattern_info[:regexp]
+      match = text.match(regexp)
+
+      return nil unless match
+
+      if capture_name && match.names.include?(capture_name.to_s)
+        # Extract named capture group
+        match[capture_name.to_s]
+      elsif match.captures.any?
+        # Extract first capture group
+        match[1]
+      else
+        # Return the entire match
+        match[0]
+      end
+    end
+
+    # Extract all named capture groups as a hash or positional captures as an array.
+    #
+    # @param text [String] The text to match against.
+    # @param pattern_info [Hash] The hash result from `parse_pattern`.
+    # @return [Hash, Array, nil] A hash of named captures, an array of positional captures, or `nil`.
+    def extract_all_captures text, pattern_info
+      return nil unless text && pattern_info
+
+      regexp = pattern_info[:regexp]
+      match = text.match(regexp)
+
+      return nil unless match
+
+      if match.names.any?
+        # Return hash of named captures
+        match.names.each_with_object({}) do |name, captures|
+          captures[name] = match[name]
+        end
+      else
+        # Return array of positional captures
+        match.captures
+      end
+    end
+
+    # A convenience method that combines parsing and a single extraction.
+    #
+    # @param text [String] The text to match against.
+    # @param pattern_input [String] The pattern string (with or without /flags/).
+    # @param capture_name [String] Name of the capture group to extract (optional).
+    # @param default_flags [String] Default flags if the pattern has no flags.
+    # @return [String, nil] The extracted text, or `nil` if no match is found.
+    def parse_and_extract text, pattern_input, capture_name = nil, default_flags = ''
+      pattern_info = parse_pattern(pattern_input, default_flags)
+      extract_capture(text, pattern_info, capture_name)
+    end
+
+    # A convenience method that combines parsing and extraction of all captures.
+    #
+    # @param text [String] The text to match against.
+    # @param pattern_input [String] The pattern string (with or without /flags/).
+    # @param default_flags [String] Default flags if the pattern has no flags.
+    # @return [Hash, Array, nil] All captured content, or `nil` if no match is found.
+    def parse_and_extract_all text, pattern_input, default_flags = ''
+      pattern_info = parse_pattern(pattern_input, default_flags)
+      extract_all_captures(text, pattern_info)
+    end
+  end
+end

data/lib/schemagraphy/safe_expression.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require 'prism'
+require 'timeout'
+
+module SchemaGraphy
+  # Provides a simple, deny-by-exception sandbox for mapping expressions.
+  # It validates code by walking the Abstract Syntax Tree (AST) and blocking
+  # known dangerous operations, rather than attempting to allowlist safe ones.
+  class AstGate
+    # A list of dangerous bareword methods that are blocked.
+    BLOCKED_BAREWORDS = %w[
+      eval instance_eval class_eval module_eval binding
+      require require_relative load autoload
+      system exec spawn fork backtick `
+      open ObjectSpace GC Thread Process at_exit
+    ].freeze
+
+    # A list of AST node types that are explicitly disallowed.
+    DISALLOWED_NODES = %i[
+      # Definitions and meta-programming
+      def_node class_node module_node define_node alias_node undef_node
+      # Globals and constants paths
+      global_variable_read_node constant_path_node
+      # Shell and backticks
+      x_string_node interpolated_x_string_node
+    ].freeze
+
+    # A list of constants that are considered dangerous and are blocked.
+    DANGEROUS_CONSTANTS = %w[
+      Kernel Object Module Class File FileUtils IO Dir Process Open3 PTY Thread
+      SystemSignal Signal Gem Net HTTP TCPSocket UDPSocket Socket ObjectSpace GC
+    ].freeze
+
+    # Validates the given code by parsing it and walking the AST.
+    #
+    # @param code [String] The Ruby code to validate.
+    # @param context_keys [Array<Symbol>] A list of keys available in the execution context.
+    # @raise [SyntaxError] if the code has syntax errors.
+    # @raise [SecurityError] if the code contains disallowed operations.
+    def self.validate! code, context_keys: []
+      result = Prism.parse(code)
+      raise SyntaxError, result.errors.map(&:message).join(', ') if result.errors.any?
+
+      walk(result.value, context_keys: context_keys)
+    end
+
+    # @api private
+    # Recursively walks the AST, checking for disallowed nodes and operations.
+    #
+    # @param node [Prism::Node] The current AST node.
+    # @param context_keys [Array<Symbol>] A list of keys available in the execution context.
+    # @raise [SecurityError] if a disallowed operation is found.
+    def self.walk node, context_keys: []
+      return unless node.is_a?(Prism::Node)
+
+      type = node.type
+      raise SecurityError, "node not allowed: #{type}" if DISALLOWED_NODES.include?(type)
+
+      case node
+      when Prism::CallNode
+        # Block dangerous barewords (system, eval, etc.)
+        if node.receiver.nil? && BLOCKED_BAREWORDS.include?(node.name.to_s)
+          raise SecurityError, "method not allowed: #{node.name}"
+        end
+        # Block dangerous constants and constant paths
+        if node.receiver.is_a?(Prism::ConstantReadNode) && DANGEROUS_CONSTANTS.include?(node.receiver.name.to_s)
+          raise SecurityError, "unsafe constant: #{node.receiver.name}"
+        end
+        raise SecurityError, 'unsafe constant path' if node.receiver.is_a?(Prism::ConstantPathNode)
+
+      when Prism::ConstantReadNode
+        # Allow only core Ruby constants defined in SafeTransform
+        const_name = node.name.to_s
+        unless SafeTransform::CORE_CONSTANTS.key?(const_name.to_sym)
+          raise SecurityError, "constant not allowed: #{const_name}"
+        end
+      when Prism::ConstantPathNode, Prism::GlobalVariableReadNode
+        raise SecurityError, 'constant paths and global variables are not allowed'
+      when Prism::DefNode, Prism::ClassNode, Prism::ModuleNode
+        raise SecurityError, 'method, class, and module definitions are not allowed'
+      when Prism::BackReferenceReadNode, Prism::XStringNode, Prism::InterpolatedXStringNode
+        raise SecurityError, 'shell commands and backticks are not allowed'
+      end
+
+      node.child_nodes.each { |child| walk(child, context_keys: context_keys) if child }
+    end
+  end
+
+  # Provides a sandboxed environment for executing Ruby code.
+  # Inherits from `BasicObject` for a minimal namespace and uses `instance_eval`
+  # to run code within its own context. All code is validated by {AstGate} before execution.
+  class SafeTransform < BasicObject
+    # A minimal set of core Ruby constants exposed to the sandboxed environment.
+    CORE_CONSTANTS = {
+      Array:      ::Array,
+      Hash:       ::Hash,
+      String:     ::String,
+      Integer:    ::Integer,
+      Float:      ::Float,
+      TrueClass:  ::TrueClass,
+      FalseClass: ::FalseClass,
+      NilClass:   ::NilClass,
+      Symbol:     ::Symbol,
+      Numeric:    ::Numeric,
+      Regexp:     ::Regexp
+    }.freeze
+
+    CORE_CONSTANTS.each do |name, ref|
+      const_set(name, ref) unless const_defined?(name, false)
+    end
+
+    # @param context [Hash] A hash of data to be made available in the sandbox.
+    def initialize context = {}
+      @context = context
+    end
+
+    # Executes the given code within the sandboxed environment.
+    #
+    # @param code [String] The Ruby code to execute.
+    # @return [Object] The result of the executed code.
+    # @raise [Timeout::Error] if the execution time exceeds the limit.
+    # @raise [SecurityError] if the code contains disallowed operations.
+    def transform code
+      ::Timeout.timeout(0.25) do
+        AstGate.validate!(code, context_keys: @context.keys)
+        instance_eval(code)
+      end
+    rescue ::Timeout::Error
+      ::Kernel.raise ::StandardError, 'transform timed out'
+    end
+
+    # Adds a key-value pair to the execution context.
+    #
+    # @param key [String, Symbol] The key to add.
+    # @param value [Object] The value to associate with the key.
+    def add_context key, value
+      @context[key.to_s] = value
+    end
+
+    # Safely traverses a nested object using a dot-separated path.
+    #
+    # @param obj [Object] The object to traverse.
+    # @param path [String] The dot-separated path (e.g., "a.b.c").
+    # @return [Object, nil] The value at the specified path, or `nil`.
+    def dig_path obj, path
+      keys = path.to_s.split('.')
+      keys.reduce(obj) { |memo, key| memo.respond_to?(:[]) ? memo[key] : nil }
+    end
+
+    def to_s
+      '#<SchemaGraphy::SafeTransform>'
+    end
+
+    private
+
+    # Handles access to variables in the context.
+    def method_missing(name, *args, &block)
+      key = name.to_s
+      if @context.key?(key) && args.empty? && block.nil?
+        @context[key]
+      else
+        ::Kernel.raise ::NoMethodError, "undefined method `#{name}` for #{self}"
+      end
+    end
+
+    def respond_to_missing? name, include_private = false
+      @context.key?(name.to_s) || super
+    end
+
+    # Disable methods that could be used to break out of the sandbox.
+
+    def instance_exec(*_args)
+      ::Kernel.raise ::NoMethodError, 'disabled'
+    end
+
+    def method(*_args)
+      ::Kernel.raise ::NoMethodError, 'disabled'
+    end
+
+    def singleton_class(*_args)
+      ::Kernel.raise ::NoMethodError, 'disabled'
+    end
+
+    def define_singleton_method(*_args)
+      ::Kernel.raise ::NoMethodError, 'disabled'
+    end
+  end
+end

data/lib/schemagraphy/schema_utils.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module SchemaGraphy
+  # A utility module for introspecting schema definitions.
+  # Provides methods for retrieving metadata, default values, and type information
+  # from a schema hash using a dot-separated path syntax.
+  module SchemaUtils
+    module_function
+
+    # Retrieve a nested property definition from a schema using a dot-separated path.
+    #
+    # @example Schema Structure
+    #   schema = {
+    #     "$schema": {
+    #       "properties": {
+    #         "property1": {
+    #           "properties": {
+    #             "subproperty1": {
+    #               "default": "value1",
+    #               "type": "String"
+    #             }
+    #           }
+    #         }
+    #       }
+    #     }
+    #   }
+    #   crawl_properties(schema, "property1.subproperty1")
+    #   # => { "default" => "value1", "type" => "String" }
+    #
+    # @param schema [Hash] The schema hash to crawl.
+    # @param path [String] The dot-separated path to the property.
+    # @return [Hash, nil] The property definition hash, or `nil` if not found.
+    def crawl_properties schema, path
+      path_components = path.split('.')
+      current = schema['$schema'] || schema
+
+      path_components.each do |component|
+        return nil unless current.is_a?(Hash)
+        return nil unless current['properties']&.key?(component)
+
+        current = current['properties'][component]
+      end
+
+      current
+    end
+
+    # Get the default value for a property from the schema.
+    #
+    # @param schema [Hash] The schema hash.
+    # @param path [String] The dot-separated path to the property.
+    # @return [Object, nil] The default value, or `nil` if not defined.
+    def default_for schema, path
+      property = crawl_properties(schema, path)
+      return nil unless property.is_a?(Hash)
+
+      property['default'] || property['dflt']
+    end
+
+    # Get the type for a property from the schema.
+    #
+    # @param schema [Hash] The schema hash.
+    # @param path [String] The dot-separated path to the property.
+    # @return [String, nil] The property type, or `nil` if not defined.
+    def type_for schema, path
+      property = crawl_properties(schema, path)
+      return nil unless property.is_a?(Hash)
+
+      property['type']
+    end
+
+    # Get the templating configuration for a property from the schema.
+    #
+    # @param schema [Hash] The schema hash.
+    # @param path [String] The dot-separated path to the property.
+    # @return [Hash] The templating configuration hash.
+    def templating_config_for schema, path
+      property = crawl_properties(schema, path)
+      return {} unless property.is_a?(Hash)
+
+      return property['templating'] if property['templating']
+
+      if property['type'].to_s.downcase == 'liquid'
+        { 'default' => 'liquid', 'delay' => true }
+      elsif property['type'].to_s.downcase == 'erb'
+        { 'default' => 'erb', 'delay' => true }
+      else
+        {}
+      end
+    end
+
+    # Check if a property is a templated field.
+    #
+    # @param schema [Hash] The schema hash.
+    # @param path [String] The dot-separated path to the property.
+    # @return [Boolean] `true` if the field has templating configured, `false` otherwise.
+    def templated_field? schema, path
+      property = crawl_properties(schema, path)
+      return false unless property.is_a?(Hash)
+
+      property.key?('templating') && property['templating'].is_a?(Hash)
+    end
+
+    # Crawl the schema to find the metadata for a given path.
+    #
+    # @param schema [Hash] The schema hash.
+    # @param path [String, nil] The dot-separated path.
+    # @return [Hash] The metadata hash.
+    def self.crawl_meta schema, path = nil
+      parts = path ? path.split('.') : []
+      node = schema['$schema'] || schema
+      meta = {}
+
+      parts.each do |part|
+        node = node['properties'][part] if node['properties']&.key?(part)
+        break unless node.is_a?(Hash)
+
+        # Only update meta if this level has it
+        meta = node if node['templating']
+      end
+
+      meta['$meta'] || meta['sgyml'] || meta['templating'] || {}
+    end
+  end
+end

data/lib/schemagraphy/tag_utils.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module SchemaGraphy
+  # A utility module for working with the custom tag data structure.
+  # The structure is a hash with 'value' and '__tag__' keys.
+  module TagUtils
+    # Extracts the original value from a tagged data structure.
+    #
+    # @param value [Object] The tagged value (a Hash) or any other value.
+    # @return [Object] The original value, or the value itself if not tagged.
+    def self.detag value
+      value.is_a?(Hash) && value.key?('value') ? value['value'] : value
+    end
+
+    # Retrieves the tag from a tagged data structure.
+    #
+    # @param value [Object] The tagged value (a Hash) or any other value.
+    # @return [String, nil] The tag string, or `nil` if not tagged.
+    def self.tag_of value
+      value.is_a?(Hash) ? value['__tag__'] : nil
+    end
+
+    # Checks if a value has a specific tag.
+    #
+    # @param value [Object] The tagged value to check.
+    # @param tag [String, Symbol] The tag to check for.
+    # @return [Boolean] `true` if the value has the specified tag, `false` otherwise.
+    def self.tag? value, tag
+      tag_of(value)&.to_s == tag.to_s
+    end
+  end
+end