lazy_graph 0.1.0

data/lib/lazy_graph/builder/dsl.rb

@@ -0,0 +1,315 @@
+# frozen_string_literal: true
+
+module LazyGraph
+  class Builder
+    # This module defines the DSL for building Lazy Graph JSON schemas.
+    # Supported helpers
+    # * object :name, **opts, &blk
+    # * object_conditional :name, **opts, &blk
+    #   ⌙ matches &blk
+    # * array :name, **opts, &blk
+    #   ⌙ items &blk
+    # * <primitive> :name, **opts, &blk
+    # * date :name, **opts, &blk
+    # * decimal :name, **opts, &blk
+    # * timestamp :name, **opts, &blk
+    # * time :name, **opts, &blk
+    #
+    module DSL
+      def additional_properties(value)
+        schema[:additionalProperties] = value
+        self
+      end
+
+      def required(*keys)
+        (schema[:required] ||= []).concat(keys.map(&:to_s)).uniq!
+        self
+      end
+
+      def default(value)
+        schema[:default] = \
+          if value.is_a?(Hash)
+            HashUtils.deep_merge(schema.fetch(:default, {}), value)
+          elsif value.is_a?(Array)
+            schema.fetch(:default, []).concat(value).uniq!
+          else
+            value
+          end
+        self
+      end
+
+      def set_pattern_property(pattern, value)
+        pattern = pattern.to_s
+        properties = schema[:patternProperties] ||= {}
+        properties[pattern] = \
+          if properties.key?(pattern) && %i[object array].include?(properties[pattern][:type])
+            HashUtils.deep_merge(properties[pattern], value, key)
+          else
+            value
+          end
+        self
+      end
+
+      def set_property(key, value)
+        key = key.to_sym
+        properties = schema[:properties] ||= {}
+        properties[key] = \
+          if properties.key?(key) && %i[object array].include?(properties[key][:type])
+            HashUtils.deep_merge(properties[key], value, key)
+          else
+            value
+          end
+        self
+      end
+
+      def object_conditional(
+        name = nil, required: false, pattern_property: false, rule: nil,
+        default: nil, description: nil, **opts, &blk
+      )
+        new_object = {
+          type: :object,
+          properties: {},
+          additionalProperties: false,
+          **(!default.nil? ? { default: default } : {}),
+          **(description ? { description: description } : {}),
+          **opts
+        }
+        @prev_match_cases = @match_cases
+        @match_cases = []
+
+        yields(new_object, &blk)
+
+        object_names = @match_cases.map do |match_case|
+          rule = rule_from_when(match_case[:when_clause])
+          set_property(match_case[:name], { type: :object, rule: rule, **match_case[:schema] })
+          match_case[:name]
+        end
+
+        new_object[:rule] = rule_from_first_of(object_names)
+        @match_cases = @prev_match_cases
+        required(name) if required && default.nil? && rule.nil?
+        pattern_property ? set_pattern_property(name, new_object) : set_property(name, new_object)
+      end
+
+      def matches(name, invisible: true, **when_clause, &blk)
+        @match_cases << { name: name, when_clause: when_clause, schema: { invisible: invisible } }
+        yields(@match_cases.last[:schema], &blk)
+      end
+
+      def object(
+        name = nil, required: false, pattern_property: false, rule: nil,
+        default: nil, description: nil, **opts, &blk
+      )
+        rule ||= rule_from_when(opts.delete(:when)) if opts[:when]
+        rule ||= rule_from_first_of(opts.delete(:first_of)) if opts[:first_of]
+        new_object = {
+          type: :object,
+          properties: {},
+          additionalProperties: false,
+
+          **(!default.nil? ? { default: default } : {}),
+          **(description ? { description: description } : {}),
+          **(rule ? { rule: rule } : {}),
+          **opts
+        }
+        yields(new_object, &blk)
+        required(name) if required && default.nil? && rule.nil?
+        pattern_property ? set_pattern_property(name, new_object) : set_property(name, new_object)
+      end
+
+      def primitive(
+        name = nil, type, required: false, pattern_property: false,
+        default: nil, description: nil, enum: nil,
+        rule: nil, **additional_options, &blk
+      )
+        new_primitive = {
+          type: type,
+          **(enum ? { enum: enum } : {}),
+          **(!default.nil? ? { default: default } : {}),
+          **(description ? { description: description } : {}),
+          **(rule ? { rule: rule } : {}),
+          **additional_options
+        }
+        yields(new_primitive, &blk)
+        required(name) if required && default.nil? && rule.nil?
+        pattern_property ? set_pattern_property(name, new_primitive) : set_property(name, new_primitive)
+      end
+
+      def decimal(name = nil, required: false, pattern_property: false, default: nil, description: nil, rule: nil,
+                  **opts, &blk)
+        # Define the decimal schema supporting multiple formats
+        new_decimal = {
+          anyOf: [
+            {
+              type: :string,
+              # Matches valid decimals with optional exponentials
+              pattern: '^-?(\\d+\\.\\d+|\\d+|\\d+e[+-]?\\d+|\\d+\\.\\d+e[+-]?\\d+)$'
+
+            },
+            # Allows both float and int
+            {
+              type: :number #
+            },
+            {
+              type: :integer
+            }
+          ],
+          type: :decimal,
+          **(!default.nil? ? { default: default } : {}),
+          **(description ? { description: description } : {}),
+          **(rule ? { rule: rule } : {}),
+          **opts
+        }
+        yields(new_decimal, &blk)
+        required(name) if required && default.nil? && rule.nil?
+        pattern_property ? set_pattern_property(name, new_decimal) : set_property(name, new_decimal)
+      end
+
+      def timestamp(name = nil, required: false, pattern_property: false, default: nil, description: nil, rule: nil,
+                    **opts, &blk)
+        new_timestamp = {
+          anyOf: [
+            {
+              type: :string,
+              # Matches ISO 8601 timestamp without timezone
+              pattern: '^\d{4}-\d{2}-\d{2}(T\d{2}(:\d{2}(:\d{2}(\.\d{1,3})?)?)?(Z|[+-]\d{2}(:\d{2})?)?)?$'
+            },
+            {
+              type: :number # Allows numeric epoch timestamps
+            },
+            {
+              type: :integer # Allows both float and int
+            }
+          ],
+          type: :timestamp, # Custom extended type
+          **(!default.nil? ? { default: default } : {}),
+          **(description ? { description: description } : {}),
+          **(rule ? { rule: rule } : {}),
+          **opts
+        }
+        yields(new_timestamp, &blk)
+        required(name) if required && default.nil? && rule.nil?
+        pattern_property ? set_pattern_property(name, new_timestamp) : set_property(name, new_timestamp)
+      end
+
+      def time(name = nil, required: false, pattern_property: false, default: nil, description: nil, rule: nil,
+               **opts, &blk)
+        new_time = {
+          type: :time, # Custom extended type
+          # Matches HH:mm[:ss[.SSS]]
+          pattern: '^\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,3})?)?$',
+          **(!default.nil? ? { default: default } : {}),
+          **(description ? { description: description } : {}),
+          **(rule ? { rule: rule } : {}),
+          **opts
+        }
+        yields(new_time, &blk)
+        required(name) if required && default.nil? && rule.nil?
+        pattern_property ? set_pattern_property(name, new_time) : set_property(name, new_time)
+      end
+
+      def date(name = nil, required: false, pattern_property: false, default: nil, description: nil, rule: nil,
+               **opts, &blk)
+        new_date = {
+          anyOf: [
+            {
+              type: :string,
+              # Matches ISO 8601 date format
+              pattern: '^\\d{4}-\\d{2}-\\d{2}$'
+            }
+          ],
+          type: :date, # Custom extended type
+          **(!default.nil? ? { default: default } : {}),
+          **(description ? { description: description } : {}),
+          **(rule ? { rule: rule } : {}),
+          **opts
+        }
+        yields(new_date, &blk)
+        required(name) if required && default.nil? && rule.nil?
+        pattern_property ? set_pattern_property(name, new_date) : set_property(name, new_date)
+      end
+
+      %i[boolean string const integer number null].each do |type|
+        define_method(type) do |
+          name = nil, required: false, pattern_property: false,
+          default: nil, description: nil, enum: nil, rule: nil, **additional_options, &blk|
+          primitive(
+            name, type, required: required, pattern_property: pattern_property, enum: enum,
+                        default: default, rule: rule, description: description,
+                        **additional_options, &blk
+          )
+        end
+      end
+
+      def dependencies(dependencies)
+        schema[:dependencies] = HashUtils.deep_merge(schema[:dependencies] || {}, dependencies)
+      end
+
+      def one_of(one_of)
+        schema[:oneOf] = (schema[:one_of] || []).concat(one_of).uniq
+      end
+
+      def any_of(any_of)
+        schema[:anyOf] = (schema[:any_of] || []).concat(any_of).uniq
+      end
+
+      def array(name = nil, required: false, pattern_property: false, default: nil, description: nil, rule: nil,
+                type: :object, **opts, &blk)
+        new_array = {
+          type: :array,
+          **(!default.nil? ? { default: default } : {}),
+          **(description ? { description: description } : {}),
+          **(rule ? { rule: rule } : {}),
+          **opts,
+          items: {
+            type: type,
+            properties: {},
+            additionalProperties: false
+          }
+        }
+        yields(new_array, &blk)
+        required(name) if required && default.nil? && rule.nil?
+        pattern_property ? set_pattern_property(name, new_array) : set_property(name, new_array)
+      end
+
+      def items(&blk)
+        yields(schema[:items], &blk)
+      end
+
+      def yields(other)
+        return unless block_given?
+
+        prev_schema = schema
+        self.schema = other
+        yield
+        self.schema = prev_schema
+      end
+
+      def rule_from_when(when_clause)
+        inputs = when_clause.keys
+        conditions = when_clause
+        rule = "{#{when_clause.keys.map { |k| "#{k}: #{k}}" }.join(', ')}"
+        {
+          inputs: inputs,
+          conditions: conditions,
+          rule: rule
+        }
+      end
+
+      def rule_from_first_of(prop_list)
+        {
+          inputs: prop_list,
+          rule: "itself.get_first_of(:#{prop_list.join(', :')})"
+        }
+      end
+
+      def depends_on(*dependencies)
+        @resolved_dependencies ||= Hash.new do |h, k|
+          send(k) # Load dependency once
+          h[k] = true
+        end
+        dependencies.each(&@resolved_dependencies.method(:[]))
+      end
+    end
+  end
+end

data/lib/lazy_graph/builder.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+# Subclass LazyGraph::Builder to create new builder classes
+# which can be used to easily build a rule-set to be used as a LazyGraph.
+#
+require_relative 'builder/dsl'
+
+module LazyGraph
+  class Builder
+    include DSL
+    # This class is responsible for piece-wise building of rules,
+    # as a combined schema definition.
+    attr_accessor :schema
+
+    def initialize(schema: { type: 'object', properties: {} }) = @schema = schema
+    def build!(debug: false, validate: false) = @schema.to_lazy_graph(debug: debug, validate: validate, helpers: self.class.helper_modules)
+    def context(value, debug: false, validate: false) = build!(debug: debug, validate: validate).context(value)
+    def eval!(context, *value, debug: false, validate: false) = context(context, validate: validate, debug: debug).query(*value)
+
+    def self.rules_module(name, schema = { type: 'object', properties: {} }, &blk)
+      rules_modules[:properties][name.to_sym] = { type: :object, properties: schema }
+      module_body_func_name = :"_#{name}"
+      define_method(module_body_func_name, &blk)
+      define_method(name) do |**args, &inner_blk|
+        send(module_body_func_name, **args, &inner_blk)
+        self
+      end
+    end
+
+    class << self
+      attr_reader :helper_modules
+    end
+
+    def self.register_helper_module(mod)
+      (@helper_modules ||= []) << mod
+    end
+
+    def self.clear_rules_modules!
+      @rules_modules = nil
+    end
+
+    def self.clear_helper_modules!
+      @helper_modules = nil
+    end
+
+    def self.rules_modules
+      @rules_modules ||= {
+        type: :object,
+        properties: {},
+        additionalProperties: false
+      }
+    end
+
+    def self.usage
+      {
+        modules_options: rules_modules[:properties].map do |k, v|
+          {
+            name: k.to_s,
+            properties: v[:properties],
+            required: v[:required]
+          }
+        end,
+        context_sample_schema: rules_modules[:properties].keys.reduce(new) do |acc, (k, _v)|
+          acc.send(k, **{})
+        end.schema
+      }
+    end
+
+    def self.eval!(modules:, context:, query:, debug: false, validate: false)
+      context_result = (@eval_cache ||= {})[[modules, context, query, debug, validate].hash] ||= begin
+        invalid_modules = modules.reject { |k, _v| rules_modules[:properties].key?(k.to_sym) }
+        return format_error_response('Invalid Modules', invalid_modules.keys.join(',')) unless invalid_modules.empty?
+
+        error = validate_modules(modules)
+
+        return format_error_response('Invalid Module Option', error) unless error.empty?
+
+        builder = build_modules(modules)
+        return builder if builder.is_a?(Hash)
+
+        evaluate_context(builder, context, debug: debug, validate: validate)
+      end
+
+      @eval_cache.delete(@eval_cache.keys.first) if @eval_cache.size > 1000
+
+      return context_result if context_result.is_a?(Hash) && context_result[:type] == :error
+
+      {
+        type: :success,
+        result: context_result.query(*(query || ''))
+      }
+
+    rescue SystemStackError => e
+      LazyGraph.logger.error(e.message)
+      LazyGraph.logger.error(e.backtrace)
+      {
+        type: :error,
+        message: 'Recursive Query Detected',
+        detail: "Problem query path: #{query}"
+      }
+    end
+
+    private_class_method def self.method_missing(method_name, *args, &block) = new.send(method_name, *args, &block)
+    private_class_method def self.respond_to_missing?(_, _ = false) = true
+
+    private_class_method def self.validate_modules(input_options)
+      JSON::Validator.validate!(rules_modules, input_options)
+      ''
+    rescue StandardError => e
+      e.message
+    end
+
+    private_class_method def self.format_error_response(message, detail)
+      {
+        type: :error,
+        message: message,
+        **(detail.to_s =~ /Schema: / ? { location: detail[/^Schema: #(.*)$/, 1] } : {}),
+        detail: detail.to_s
+      }
+    end
+
+    private_class_method def self.build_modules(input_options)
+      input_options.reduce(new.additional_properties(false)) do |acc, (k, v)|
+        acc.send(k, **v.to_h.transform_keys(&:to_sym))
+      end
+    rescue ArgumentError => e
+      format_error_response('Invalid Module Argument', e.message)
+      LazyGraph.logger.error(e.backtrace)
+    end
+
+    private_class_method def self.evaluate_context(builder, context, debug: false, validate: false)
+      builder.context(context, debug: debug, validate: validate)
+    rescue ArgumentError => e
+      format_error_response('Invalid Context Input', e.message)
+      LazyGraph.logger.error(e.backtrace)
+    end
+  end
+end

data/lib/lazy_graph/builder_group.rb

@@ -0,0 +1,57 @@
+module LazyGraph
+  class BuilderGroup
+    # A builder group is simply a named colleciton of builders (each a subclass of LazyGraph::Builder)
+    # That can be reloaded in bulk, and exposed via a simple HTTP server interface.
+    def self.bootstrap!(reload_paths: [], listen: ENV['RACK_ENV'] == 'development')
+      reload_paths = Array(reload_paths)
+      Module.new do
+        define_singleton_method(:included) do |base|
+          def base.each_builder(const = self, &blk)
+            return to_enum(__method__, const) unless blk
+
+            if const.is_a?(Class) && const < LazyGraph::Builder
+              blk[const]
+            elsif const.is_a?(Module)
+              const.constants.each do |c|
+                each_builder(const.const_get(c), &blk)
+              end
+            end
+          end
+
+          def base.server
+            LazyGraph::Server.new(
+              routes: each_builder.map do |builder|
+                [
+                  builder.to_s.downcase.gsub('::', '/').gsub(/^#{name.downcase}/, ''),
+                  builder
+                ]
+              end.to_h
+            )
+          end
+
+          base.define_singleton_method(:reload_lazy_graphs!) do
+            each_builder do |builder|
+              builder.clear_rules_modules!
+              builder.clear_helper_modules!
+            end
+
+            reload_paths.flat_map { |p| Dir[p] }.each do |file|
+              load file
+            rescue StandardError => e
+              LazyGraph.logger.error("Failed to load #{file}: #{e.message}")
+            end
+          end
+
+          base.reload_lazy_graphs!
+
+          return unless listen
+
+          require 'listen'
+          Listen.to(*reload_paths.map { |p| p.gsub(%r{(?:/\*\*)*/\*\.rb}, '') }) do
+            base.reload_lazy_graphs!
+          end.start
+        end
+      end
+    end
+  end
+end

data/lib/lazy_graph/context.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module LazyGraph
+  # Context class is responsible for managing ruleset and input data,
+  # allowing querying and dynamic method calls to access input fields.
+  class Context
+    attr_accessor :ruleset, :input
+
+    def initialize(graph, input)
+      HashUtils.deep_symbolize!(input)
+      graph.validate!(input) if [true, 'input'].include?(graph.validate)
+      @graph = graph
+      @input = input
+    end
+
+    def query(paths)
+      paths.is_a?(Array) ? paths.map { |path| resolve(input, path) } : resolve(input, paths)
+    end
+
+    def resolve(input, path)
+      @input = @graph.root_node.fetch_item({ input: input }, :input, nil)
+      query = PathParser.parse(path, true)
+      stack = StackPointer.new(nil, @input, 0, :'$', nil)
+      stack.root = stack
+
+      result = @graph.root_node.resolve(query, stack)
+      @graph.root_node.clear_visits!
+      if @graph.debug?
+        debug_trace = stack.frame[:DEBUG]
+        stack.frame[:DEBUG] = nil
+      end
+      {
+        output: HashUtils.strip_invalid(result),
+        debug_trace: HashUtils.strip_invalid(debug_trace)
+      }
+    rescue LazyGraph::AbortError => e
+      {
+        output: { err: e.message, status: :abort }
+      }
+    rescue StandardError => e
+      LazyGraph.logger.error(e.message)
+      LazyGraph.logger.error(e.backtrace)
+      {
+        output: { err: e.message, backtrace: e.backtrace }
+      }
+    end
+
+    def pretty_print(q)
+      # Start the custom pretty print
+      q.group(1, '<LazyGraph::Context ', '>') do
+        q.group do
+          q.text 'graph='
+          q.pp(@graph)
+        end
+      end
+    end
+
+    alias [] query
+  end
+end

data/lib/lazy_graph/graph.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'json-schema'
+
+module LazyGraph
+  # Represents a lazy graph structure based on JSON schema
+  VALIDATION_CACHE = {}
+  METASCHEMA = JSON.load_file(File.join(__dir__, 'lazy-graph.json'))
+
+  class Graph
+    attr_reader :json_schema, :root_node, :validate
+
+    def context(input) = Context.new(self, input)
+    def debug? = @debug
+
+    def initialize(json_schema, debug: false, validate: true, helpers: nil)
+      @json_schema = HashUtils.deep_dup!(json_schema).merge(type: :object)
+
+      @debug = debug
+      @validate = validate
+      @helpers = helpers
+
+      signature = HashUtils.deep_symbolize!(@json_schema)
+      if [true, 'schema'].include?(validate)
+        VALIDATION_CACHE[signature] ||= validate!(@json_schema, METASCHEMA)
+        true
+      end
+
+      if @json_schema[:type].to_sym != :object || @json_schema[:properties].nil?
+        raise ArgumentError, 'Root schema must be a non-empty object'
+      end
+
+      @root_node = build_node(@json_schema)
+    end
+
+    def build_node(schema, path = :'$', name = :root, parent = nil)
+      schema[:type] = schema[:type].to_sym
+      case schema[:type]
+      when :object then ObjectNode
+      when :array then ArrayNode
+      else Node
+      end.new(name, path, schema, parent, debug: @debug, helpers: @helpers).tap do |node|
+        node.children = build_children(node, schema, path)
+      end
+    end
+
+    def build_children(node, schema, path)
+      case node.type
+      when :object then build_object_children(schema, path, node)
+      when :array then build_node(schema.fetch(:items, {}), :"#{path}[]", :items, node)
+      end
+    end
+
+    def build_object_children(schema, path, parent)
+      {
+        properties: schema.fetch(:properties, {}).map do |key, value|
+          [key, build_node(value, "#{path}.#{key}", key, parent)]
+        end.to_h,
+        pattern_properties: schema.fetch(:patternProperties, {}).map do |key, value|
+          [Regexp.new(key.to_s), build_node(value, :"#{path}.#{key}", :'<property>', parent)]
+        end.to_h
+      }
+    end
+
+    def validate!(input, schema = @json_schema)
+      JSON::Validator.validate!(schema, input)
+    end
+  end
+
+  Hash.define_method(:to_lazy_graph, ->(**opts) { LazyGraph::Graph.new(self, **opts) })
+  Hash.define_method(:to_graph_ctx, ->(input, **opts) { to_lazy_graph(**opts).context(input) })
+  Hash.define_method(:eval_graph, ->(input, *query, **opts) { to_graph_ctx(input, **opts)[*query] })
+end