releasehx 0.1.2 → 0.2.0

data/lib/schemagraphy/safe_expression.rb

@@ -1,189 +0,0 @@
-# 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

@@ -1,124 +0,0 @@
-# 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

@@ -1,32 +0,0 @@
-# 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

data/lib/schemagraphy/templating.rb

@@ -1,104 +0,0 @@
-# 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

@@ -1,17 +0,0 @@
-# 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

@@ -1,120 +0,0 @@
-# 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

@@ -1,78 +0,0 @@
-# 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