lazy_graph 0.1.0

data/lib/lazy_graph/hash_utils.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module LazyGraph
+  module HashUtils
+    module_function
+
+    def deep_dup!(hash)
+      case hash
+      when Hash
+        hash = hash.dup
+        hash.each do |key, value|
+          hash[key] = deep_dup!(value)
+        end
+      when Array
+        hash.map { |value| deep_dup!(value) }
+      end
+      hash
+    end
+
+    def deep_merge(hash, other_hash, path = :'')
+      hash.merge(other_hash.transform_keys(&:to_sym)) do |key, this_val, other_val|
+        if this_val.is_a?(Hash) && other_val.is_a?(Hash) && other_val != this_val
+          deep_merge(this_val, other_val, :"#{path}.#{key}")
+        elsif this_val.is_a?(Array) && other_val.is_a?(Array) && other_val != this_val
+          this_val.concat(other_val).uniq
+        else
+          if this_val != other_val && !(this_val.is_a?(Proc) && other_val.is_a?(Proc))
+            LazyGraph.logger.warn("Warning: Conflicting values at #{path}.#{key}. #{this_val}  != #{other_val} ")
+          end
+          other_val
+        end
+      end
+    end
+
+    def strip_invalid(obj, parent_list = {}.compare_by_identity)
+      return { '^ref': :circular } if (circular_dependency = parent_list[obj])
+
+      parent_list[obj] = true
+      case obj
+      when Hash
+        obj.each_with_object({}) do |(key, value), obj|
+          next if value.is_a?(MissingValue)
+
+          obj[key] = strip_invalid(value, parent_list)
+        end
+      when Struct
+        obj.members.each_with_object({}) do |key, res|
+          next if obj[key].is_a?(MissingValue)
+          next if obj.invisible.include?(key)
+
+          res[key] = strip_invalid(obj[key], parent_list)
+        end
+      when Array
+        obj.map! { |value| strip_invalid(value, parent_list) }
+      else
+        obj
+      end
+    ensure
+      parent_list.delete(obj) unless circular_dependency
+    end
+
+    def deep_symbolize!(obj)
+      case obj
+      when Hash
+        hash = 0
+        obj.to_a.each do |key, value|
+          hash ^= deep_symbolize!(value)
+          unless key.is_a?(Symbol)
+            key.to_s.to_sym
+            obj[key.to_s.to_sym] = obj.delete(key)
+          end
+          hash ^= key.object_id
+        end
+        obj.compare_by_identity
+        hash
+      when Array
+        hash = 0
+        obj.each { |item| hash ^= deep_symbolize!(item) }
+        hash
+      when String, Numeric, TrueClass, FalseClass, NilClass
+        obj.hash
+      else
+        0
+      end
+    end
+  end
+end

data/lib/lazy_graph/lazy-graph.json

@@ -0,0 +1,148 @@
+{
+  "$schema": "http://json-schema.org/draft-06/schema#",
+  "$id": "http://json-schema.org/draft-06/schema#",
+  "title": "Core schema meta-schema",
+  "definitions": {
+    "schemaArray": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#" }
+    },
+    "nonNegativeInteger": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "nonNegativeIntegerDefault0": {
+      "allOf": [
+        { "$ref": "#/definitions/nonNegativeInteger" },
+        { "default": 0 }
+      ]
+    },
+    "simpleTypes": {
+      "enum": [
+        "array",
+        "boolean",
+        "integer",
+        "null",
+        "number",
+        "object",
+        "string",
+        "decimal",
+        "timestamp",
+        "date",
+        "time"
+      ]
+    },
+    "stringArray": {
+      "type": "array",
+      "items": { "type": "string" },
+      "uniqueItems": true,
+      "default": []
+    }
+  },
+  "type": ["object", "boolean"],
+  "properties": {
+    "$id": {
+      "type": "string",
+      "format": "uri-reference"
+    },
+    "$schema": {
+      "type": "string",
+      "format": "uri"
+    },
+    "$ref": {
+      "type": "string",
+      "format": "uri-reference"
+    },
+    "title": {
+      "type": "string"
+    },
+    "description": {
+      "type": "string"
+    },
+    "default": {},
+    "multipleOf": {
+      "type": "number",
+      "exclusiveMinimum": 0
+    },
+    "maximum": {
+      "type": "number"
+    },
+    "exclusiveMaximum": {
+      "type": "number"
+    },
+    "minimum": {
+      "type": "number"
+    },
+    "exclusiveMinimum": {
+      "type": "number"
+    },
+    "maxLength": { "$ref": "#/definitions/nonNegativeInteger" },
+    "minLength": { "$ref": "#/definitions/nonNegativeIntegerDefault0" },
+    "pattern": {
+      "type": "string",
+      "format": "regex"
+    },
+    "additionalItems": { "$ref": "#" },
+    "items": {
+      "anyOf": [{ "$ref": "#" }, { "$ref": "#/definitions/schemaArray" }],
+      "default": {}
+    },
+    "maxItems": { "$ref": "#/definitions/nonNegativeInteger" },
+    "minItems": { "$ref": "#/definitions/nonNegativeIntegerDefault0" },
+    "uniqueItems": {
+      "type": "boolean",
+      "default": false
+    },
+    "contains": { "$ref": "#" },
+    "maxProperties": { "$ref": "#/definitions/nonNegativeInteger" },
+    "minProperties": { "$ref": "#/definitions/nonNegativeIntegerDefault0" },
+    "required": { "$ref": "#/definitions/stringArray" },
+    "additionalProperties": { "$ref": "#" },
+    "definitions": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#" },
+      "default": {}
+    },
+    "properties": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#" },
+      "default": {}
+    },
+    "patternProperties": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#" },
+      "default": {}
+    },
+    "dependencies": {
+      "type": "object",
+      "additionalProperties": {
+        "anyOf": [{ "$ref": "#" }, { "$ref": "#/definitions/stringArray" }]
+      }
+    },
+    "propertyNames": { "$ref": "#" },
+    "const": {},
+    "enum": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true
+    },
+    "type": {
+      "anyOf": [
+        { "$ref": "#/definitions/simpleTypes" },
+        {
+          "type": "array",
+          "items": { "$ref": "#/definitions/simpleTypes" },
+          "minItems": 1,
+          "uniqueItems": true
+        }
+      ]
+    },
+    "format": { "type": "string" },
+    "allOf": { "$ref": "#/definitions/schemaArray" },
+    "anyOf": { "$ref": "#/definitions/schemaArray" },
+    "oneOf": { "$ref": "#/definitions/schemaArray" },
+    "not": { "$ref": "#" }
+  },
+  "default": {}
+}

data/lib/lazy_graph/missing_value.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module LazyGraph
+  # Represents a value that is missing or undefined, allowing for graceful handling
+  # of method calls and JSON serialization even when the value is not present.
+  class MissingValue
+    attr_reader :details
+
+    def initialize(details) = @details = details
+    def to_s = "MISSING[#{@details}]"
+
+    def inspect = to_s
+    def coerce(other) = [self, other]
+    def as_json = nil
+    def respond_to_missing?(_method_name, _include_private = false) = true
+
+    def method_missing(method, *args, &block)
+      return super if method == :to_ary
+      return self if self == BLANK
+
+      MissingValue.new(:"#{details}##{method}#{args.any? ? :"(#{args.inspect[1...-1]})" : :''}")
+    end
+
+    BLANK = new('')
+  end
+end

data/lib/lazy_graph/node/array_node.rb

@@ -0,0 +1,67 @@
+module LazyGraph
+  class ArrayNode < Node
+    # An Array supports the following types of path resolutions.
+    # 1. Forward property (assuming child items are objects): arr.property
+    # 2. Absolute Index: arr[0], arr[1], arr[2], ...
+    # 3. Range: arr[0..2], arr[1...3]
+    # 4. All:arr [*]
+    # 5. Set of indexes: arr[0, 2, 4]
+    #
+    # Parts between square brackets are represented as path groups.
+    def resolve(
+      path,
+      stack_memory,
+      should_recycle = stack_memory,
+      **
+    )
+      input = stack_memory.frame
+      @visited[input.object_id ^ (path.object_id << 8)] ||= begin
+        if (path_segment = path.segment).is_a?(PathParser::PathGroup)
+          unless path_segment.options.all?(&:index?)
+            return input.length.times.map do |index|
+              item = children.fetch_item(input, index, stack_memory)
+              children.resolve(path, stack_memory.push(item, index))
+            end
+          end
+
+          return resolve(path_segment.options.first.merge(path.next), stack_memory, nil) if path_segment.options.one?
+
+          return path_segment.options.map { |part| resolve(part.merge(path.next), stack_memory, nil) }
+        end
+
+        segment = path_segment&.part
+        case segment
+        when nil
+          input.length.times do |index|
+            item = children.fetch_item(input, index, stack_memory)
+            children.resolve(path, stack_memory.push(item, index))
+          end
+          input
+        when DIGIT_REGEXP
+          item = @children.fetch_item(input, segment.to_s.to_i, stack_memory)
+          children.resolve(path.next, stack_memory.push(item, segment))
+        when :*
+          input.length.times.map do |index|
+            item = children.fetch_item(input, index, stack_memory)
+            @children.resolve(path.next, stack_memory.push(item, index))
+          end
+        else
+          if @children.is_object && @children.children[:properties].keys.include?(segment) || input&.first&.key?(segment)
+            input.length.times.map do |index|
+              item = children.fetch_item(input, index, stack_memory)
+              @children.resolve(path, stack_memory.push(item, index))
+            end
+          else
+            MissingValue()
+          end
+        end
+      end
+    ensure
+      should_recycle&.recycle!
+    end
+
+    def cast(value)
+      value.dup
+    end
+  end
+end

data/lib/lazy_graph/node/derived_rules.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require 'prism'
+require 'securerandom'
+
+module LazyGraph
+  class Node
+    module DerivedRules
+      PLACEHOLDER_VAR_REGEX = /\$\{[^}]+\}/
+      # Derived input rules can be provided in a wide variety of formats,
+      # this function handles them all.
+      #
+      # 1. A simple string or symbol: 'a.b.c'. The value at the nodes is simply set to the resolved value
+      #
+      # 2. Alternatively, you must split the inputs and the rule.
+      #  derived[:inputs]
+      #  a. Inputs as strings or symbols, e.g. inputs: ['position', 'velocity'].
+      #   These paths are resolved and made available within the rule by the same name
+      #  b. Inputs as a map of key-value pairs, e.g. inputs: { position: 'a.b.c', velocity: 'd.e.f' },
+      #   These are resolved and made available within the rule by the mapped name
+      #
+      # 3. derived[:calc]
+      #  The rule can be a simple string of Ruby code OR (this way we can encode entire lazy graphs as pure JSON)
+      #  A ruby block.
+      def build_derived_inputs(derived, helpers)
+        @resolvers = {}.compare_by_identity
+        @path_cache = {}.compare_by_identity
+
+        derived = interpret_derived_proc(derived) if derived.is_a?(Proc)
+        derived = { inputs: derived.to_s } if derived.is_a?(String) || derived.is_a?(Symbol)
+        derived[:inputs] = parse_derived_inputs(derived)
+        @copy_input = true if !derived[:calc] && derived[:inputs].size == 1
+        extract_derived_src(derived) if @debug
+
+        @inputs_optional = derived[:calc].is_a?(Proc)
+        derived[:calc] = parse_rule_string(derived) if derived[:calc].is_a?(String) || derived[:calc].is_a?(Symbol)
+
+        @node_context = create_derived_input_context(derived, helpers)
+        @inputs = map_derived_inputs_to_paths(derived[:inputs])
+        @conditions = derived[:conditions]
+        @derived = true
+      end
+
+      def interpret_derived_proc(derived)
+        src, requireds, optionals, keywords, = DerivedRules.extract_expr_from_source_location(derived.source_location)
+        src = src.body&.slice || ''
+        @src = src.lines.map(&:strip)
+        inputs, conditions = parse_args_with_conditions(requireds, optionals, keywords)
+
+        {
+          inputs: inputs,
+          mtime: File.mtime(derived.source_location.first),
+          conditions: conditions,
+          calc: instance_eval(
+            "->(#{inputs.keys.map { |k| "#{k}=self.#{k}" }.join(', ')}){ #{src}}",
+            # rubocop:disable:next-line
+            derived.source_location.first,
+            # rubocop:enable
+            derived.source_location.last.succ
+          )
+        }
+      end
+
+      def parse_args_with_conditions(requireds, optionals_with_conditions, keywords_with_conditions)
+        keywords = requireds.map { |r| [r, r] }.to_h
+        conditions = {}
+        keywords_with_conditions.map do |k, v|
+          path, condition = v.split('=')
+          keywords[k] = path
+          conditions[k] = eval(condition) if condition
+        end
+        optionals_with_conditions.each do |optional_with_conditions|
+          keywords[optional_with_conditions.name] = optional_with_conditions.name
+          conditions[optional_with_conditions.name] = eval(optional_with_conditions.value.slice)
+        end
+        [keywords, conditions.any? ? conditions : nil]
+      end
+
+      def self.extract_expr_from_source_location(source_location)
+        @derived_proc_cache ||= {}
+        mtime = File.mtime(source_location.first).to_i
+
+        if @derived_proc_cache[source_location]&.last.to_i.< mtime
+          @derived_proc_cache[source_location] = begin
+            source_lines = IO.readlines(source_location.first)
+            proc_line = source_location.last - 1
+            first_line = source_lines[proc_line]
+            until first_line =~ /(?:lambda|proc|->)/ || proc_line.zero?
+              proc_line -= 1
+              first_line = source_lines[proc_line]
+            end
+            lines = source_lines[proc_line..]
+            lines[0] = lines[0][/(?:lambda|proc|->).*/]
+            src_str = ''.dup
+            intermediate = nil
+            lines.each do |line|
+              token_count = 0
+              line.split(/(?=\s|;|\)|\})/).each do |token|
+                src_str << token
+                token_count += 1
+                intermediate = Prism.parse(src_str)
+                next unless intermediate.success? && token_count > 1
+
+                break
+              end
+              break if intermediate.success?
+            end
+
+            raise 'Source Extraction Failed' unless intermediate.success?
+
+            src = intermediate.value.statements.body.first.yield_self do |s|
+              s.type == :call_node ? s.block : s
+            end
+            requireds = (src.parameters&.parameters&.requireds || []).map(&:name)
+            optionals = src.parameters&.parameters&.optionals || []
+            keywords =  (src.parameters&.parameters&.keywords || []).map do |kw|
+              [kw.name, kw.value.slice.gsub(/^_\./, '$.')]
+            end.to_h
+            [src, requireds, optionals, keywords, mtime]
+          end
+        end
+
+        @derived_proc_cache[source_location]
+      rescue StandardError => e
+        LazyGraph.logger.error(e.message)
+        LazyGraph.logger.error(e.backtrace)
+        raise "Failed to extract expression from source location: #{source_location}. Ensure the file exists and the line number is correct. Extraction from a REPL is not supported"
+      end
+
+      def parse_derived_inputs(derived)
+        inputs = derived[:inputs]
+        case inputs
+        when Symbol, String
+          if inputs =~ PLACEHOLDER_VAR_REGEX && !derived[:calc]
+            input_hash = {}
+            derived[:calc] = inputs.gsub(PLACEHOLDER_VAR_REGEX) do |match|
+              input_hash[match[2...-1]] ||= "a#{::SecureRandom.hex(8)}"
+            end
+            input_hash.invert
+          else
+            { inputs.to_str.gsub(/[^(?:[A-Za-z][A-Za-z0-9_])]/, '__') => inputs.to_str.freeze }
+          end
+        when Array
+          inputs.map { |v| { v.to_s.gsub(/[^(?:[A-Za-z][A-Za-z0-9_])]/, '__') => v } }.reduce({}, :merge)
+        when Hash
+          inputs
+        else
+          {}
+        end.transform_values { |v| PathParser.parse(v) }
+      end
+
+      def extract_derived_src(derived)
+        return @src = derived[:calc].to_s.lines unless derived[:calc].is_a?(Proc)
+
+        @src ||= begin
+          extract_expr_from_source_location(derived[:calc].source_location).body.slice.lines.map(&:strip)
+        rescue StandardError
+          ["Failed to extract source from proc #{derived}"]
+        end
+      end
+
+      def parse_rule_string(derived)
+        instance_eval("->{ #{derived[:calc]} }", __FILE__, __LINE__)
+      rescue SyntaxError
+        missing_value = MissingValue { "Syntax error in #{derived[:src]}" }
+        -> { missing_value }
+      end
+
+      def create_derived_input_context(derived, helpers)
+        return if @copy_input
+
+        Struct.new(*(derived[:inputs].keys.map(&:to_sym) + %i[itself stack_ptr])) do
+          def missing?(value) = value.is_a?(LazyGraph::MissingValue) || value.nil?
+          helpers&.each { |h| include h }
+          define_method(:process!, &derived[:calc])
+          def method_missing(name, *args, &block)
+            stack_ptr.send(name, *args, &block)
+          end
+
+          def respond_to_missing?(name, include_private = false)
+            stack_ptr.respond_to?(name, include_private)
+          end
+        end.new
+      end
+
+      def map_derived_inputs_to_paths(inputs)
+        inputs.values.map.with_index do |path, idx|
+          segment_indexes = path.parts.map.with_index do |segment, i|
+            segment.is_a?(PathParser::PathGroup) && segment.options.length == 1 ? i : nil
+          end.compact
+          [path, idx, segment_indexes.any? ? segment_indexes : nil]
+        end
+      end
+    end
+  end
+end

data/lib/lazy_graph/node/node_properties.rb

@@ -0,0 +1,64 @@
+module LazyGraph
+  module NodeProperties
+    # Builds an Anonymous Struct with the given members
+    # Invisible members are ignored when the struct is serialized
+    def self.build(members:, invisible:)
+      Struct.new(*members, keyword_init: true) do
+        define_method(:initialize) do |kws|
+          members.each { |k| self[k] = kws[k] || MissingValue::BLANK }
+        end
+
+        define_method(:key?) do |x|
+          !self[x].equal?(MissingValue::BLANK)
+        rescue StandardError
+          nil
+        end
+
+        define_method(:[]=) do |key, val|
+          super(key, val)
+        end
+
+        define_method(:members) do
+          members
+        end
+
+        define_method(:invisible) do
+          invisible
+        end
+
+        define_method(:each_key, &members.method(:each))
+
+        def dup
+          self.class.new(members.map do |k|
+            [k, self[k].dup]
+          end.to_h)
+        end
+
+        def get_first_of(*props)
+          key = props.find do |prop|
+            !self[prop].is_a?(MissingValue)
+          end
+          key ? self[key] : MissingValue::BLANK
+        end
+
+        def pretty_print(q)
+          # Start the custom pretty print
+          q.group(1, '<Props ', '>') do
+            q.seplist(members.zip(values).reject do |m, v|
+              m == :DEBUG && (v.nil? || v.is_a?(MissingValue))
+            end) do |member, value|
+              q.group do
+                q.text "#{member}="
+                if value.respond_to?(:pretty_print)
+                  q.pp(value) # Delegate to the nested value's pretty_print
+                else
+                  q.text value.inspect
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end