schemagraphy 0.1.0

data/lib/schemagraphy/cfgyml/templates/sample-property.yaml.liquid

@@ -0,0 +1,82 @@
+{%- assign key = include.property[0] %}
+{%- assign val = include.property[1] %}
+{%- assign dflt = val.dflt %}
+{%- assign tier = include.tier | plus: 0 %}
+{%- assign nulled = include.nulled %}
+{%- assign indent = '' %}
+{%- if tier > 1 %}
+{%- for i in (2..tier) %}{% assign indent = indent | append: '  ' %}{% endfor %}
+{%- endif %}
+{%- if nulled %}
+  {%- assign pfx = '# ' %}
+{%- else %}
+  {%- assign pfx = '' %}
+{%- endif %}
+{%- assign cmmt = val.cmmt | default: val.desc | default: '' | strip | split: "
+" | first %}
+{%- if cmmt and cmmt != "" %}
+  {%- assign cmmt = cmmt | demarkupify | truncatewords: 20 | prepend: '# ' %}
+{%- endif %}
+{%- assign dflt_kind = dflt  | sgyml_type | split: ":" | first %}
+{%- assign dflt_class = dflt | sgyml_type | split: ":" | last %}
+{%- assign disp = nil %}
+{%- if dflt contains "
+" or val.type == "Multiline" %}
+  {%- assign disp = "multiline" %}
+{%- elsif val.type == "String" %}
+  {%- if dflt.size > 40 %}
+    {%- assign disp = "multiline" %}
+  {%- elsif dflt contains ":" or dflt contains "{" %}
+    {%- assign disp = "quoted" %}
+  {%- else %}
+    {%- assign disp = "unquoted" %}
+  {% endif %}
+{%- elsif val.templating or val.type == "Template" or val.type == "Liquid" or val.type == "RegExp" %}
+  {%- assign disp = "multiline" %}
+{%- elsif val.type == "Array" or val.type == "ArrayList" or dflt_class == "ArrayList" %}
+  {%- if dflt.size < 4 and (val.type == "ArrayList" or dflt_class == "ArrayList") %}
+    {%- assign disp = "sequence-flow" %}
+  {%- else %}
+    {%- assign disp = "sequence-block" %}
+  {%- endif %}
+{%- elsif val.properties or val.type == "Map" %}
+  {%- assign disp = "mapping-block" %}
+{%- elsif !val.type %}
+  {%- assign disp = "unquoted" %}
+{%- elsif val.type == "String" and dflt == "" %}
+    {%- assign disp = "blank-string" %}
+{%- else %}
+  {%- assign disp = "unquoted" %}
+{%- endif %}
+{%- case disp %}
+{%- when "multiline" %}
+{{ pfx }}{{ indent }}{{ key }}: | {{ cmmt }}
+{%-   assign ml_indent = indent | append: '  ' %}
+{%-   if nulled %}
+{%-     assign dflt_lines = dflt | split: "
+" -%}
+{%-     for line in dflt_lines %}
+{{ ml_indent }}# {{ line }}
+{%-     endfor %}
+{%-   else %}
+{%-     assign ml_indent_size = indent.size | plus: 2 %}
+{{ dflt | indent: ml_indent_size, true }}
+{%-   endif %}
+{%- when "mapping-block" %}
+{{ pfx }}{{ indent }}{{ key }}: {{ cmmt }}
+{%- when "sequence-block" %}
+{{ pfx }}{{ indent }}{{ key }}: {{ cmmt }}
+{%-   for item in dflt %}
+{{ pfx }}{{ indent }}  - {{ item }}
+{%-   endfor %}
+{%- when "sequence-flow" %}
+{{ pfx }}{{ indent }}{{ key }}: [{{ dflt | join: ', ' }}] {{ cmmt }}
+{%- when "blank-string" %}
+{{ pfx }}{{ indent }}{{ key }}: "" {{ cmmt }}
+{%- when "quoted" %}
+{{ pfx }}{{ indent }}{{ key }}: "{{ dflt }}" {{ cmmt }}
+{%- when "unquoted" %}
+{{ pfx }}{{ indent }}{{ key }}: {{ dflt }} {{ cmmt }}
+{%- else %}
+{{ pfx }}{{ indent }}# UNIDENTIFIED
+{%- endcase %}

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 # rubocop:disable Lint/ShadowedException
+        raise KeyError, "JSON Pointer not found: #{pointer}"
+      end
+
+      def unescape token
+        token.gsub('~1', '/').gsub('~0', '~')
+      end
+    end
+  end
+end

data/lib/schemagraphy/liquid/filters.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'liquid'
+
+module SchemaGraphy
+  # Liquid filter wrappers for SchemaGraphy domain operations.
+  #
+  # These filters are registered globally when SchemaGraphy is loaded and are
+  # available in any Liquid rendering environment that has required this gem.
+  # Following the DocOps Lab convention, each gem in the ecosystem registers
+  # its own domain-specific filters here rather than delegating to AsciiSourcerer.
+  module Filters
+    # Classifies a value by its SGYML type.
+    # @return [String] A "Kind:Class" type string (e.g. "Scalar:String", "Compound:ArrayList").
+    # @see SchemaGraphy::SGYML.classify
+    def sgyml_type input
+      SchemaGraphy::SGYML.classify(input)
+    end
+  end
+end
+
+Liquid::Template.register_filter(SchemaGraphy::Filters)

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,235 @@
+# 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(/^["']|["']$/, '')
+
+      # Manual parsing for /pattern/flags format (common in YAML configs)
+      if clean_input =~ %r{^/(.+)/([a-z]*)$}
+        pattern_str = Regexp.last_match(1)
+        flags_str = Regexp.last_match(2)
+        options = flags_to_options(flags_str)
+
+        begin
+          regexp_obj = Regexp.new(pattern_str, options)
+
+          return {
+            pattern: pattern_str,
+            flags: flags_str,
+            regexp: regexp_obj,
+            options: options
+          }
+        rescue RegexpError => e
+          raise RegexpError, "Invalid regex pattern '#{input}': #{e.message}"
+        end
+      end
+
+      # Heuristic to detect if it's a Regexp literal
+      is_literal = 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.to_h do |name|
+          [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