dexkit 0.9.0 → 0.10.0

data/lib/dex/query.rb

@@ -3,6 +3,7 @@
 require "active_model"
 
 require_relative "query/backend"
+require_relative "query/export"
 require_relative "query/filtering"
 require_relative "query/sorting"
 
@@ -17,7 +18,11 @@ module Dex
     extend ActiveModel::Naming
     include ActiveModel::Conversion
 
+    extend Registry
+
     class << self
+      include ContextDSL
+
       def scope(&block)
         raise ArgumentError, "scope requires a block." unless block
 
@@ -31,6 +36,14 @@ module Dex
       end
 
       def new(scope: nil, sort: nil, **kwargs)
+        mappings = context_mappings
+        unless mappings.empty?
+          ambient = Dex.context
+          mappings.each do |prop_name, context_key|
+            next if kwargs.key?(prop_name)
+            kwargs[prop_name] = ambient[context_key] if ambient.key?(context_key)
+          end
+        end
         instance = super(**kwargs)
         instance.instance_variable_set(:@_injected_scope, scope)
         sort_str = sort&.to_s
@@ -96,6 +109,30 @@ module Dex
         subclass.instance_variable_set(:@_sort_default, _sort_default) if _sort_default
       end
 
+      # Export
+
+      def to_h
+        Export.build_hash(self)
+      end
+
+      def to_json_schema
+        Export.build_json_schema(self)
+      end
+
+      def export(format: :hash)
+        unless %i[hash json_schema].include?(format)
+          raise ArgumentError, "unknown format: #{format.inspect}. Known: :hash, :json_schema"
+        end
+
+        sorted = registry.sort_by(&:name)
+        sorted.map do |klass|
+          case format
+          when :hash then klass.to_h
+          when :json_schema then klass.to_json_schema
+          end
+        end
+      end
+
       def from_params(params, scope: nil, **overrides)
         pk = model_name.param_key
         nested = _extract_nested_params(params, pk)
@@ -139,6 +176,10 @@ module Dex
 
       private
 
+      def _context_prop_declared?(name)
+        respond_to?(:literal_properties) && literal_properties.any? { |p| p.name == name }
+      end
+
       def _extract_nested_params(params, pk)
         hash = if params.respond_to?(:to_unsafe_h)
           params.to_unsafe_h

data/lib/dex/test_log.rb

@@ -2,7 +2,18 @@
 
 module Dex
   module TestLog
-    Entry = Data.define(:type, :name, :operation_class, :params, :result, :duration, :caller_location)
+    Entry = Data.define(
+      :type,
+      :name,
+      :operation_class,
+      :params,
+      :result,
+      :duration,
+      :caller_location,
+      :execution_id,
+      :trace_id,
+      :trace
+    )
 
     @_entries = []
     @_mutex = Mutex.new
@@ -42,14 +53,61 @@ module Dex
         return "No operations called." if entries.empty?
 
         lines = ["Operations called (#{entries.size}):"]
-        entries.each_with_index do |entry, i|
+        nodes = entries.each_with_index.map { |entry, index| { entry: entry, index: index } }
+        by_id = nodes.to_h { |node| [node[:entry].execution_id, node] }
+        children = Hash.new { |hash, key| hash[key] = [] }
+        roots = []
+
+        nodes.each do |node|
+          parent_id = _parent_operation_id(node[:entry])
+          if parent_id && by_id[parent_id]
+            children[parent_id] << node
+          else
+            roots << node
+          end
+        end
+
+        counter = 0
+        render = lambda do |node, depth|
+          counter += 1
+          entry = node[:entry]
           status = entry.result.ok? ? "OK" : "ERR(#{entry.result.code})"
           duration_ms = entry.duration ? format("%.1fms", entry.duration * 1000) : "n/a"
-          lines << "  #{i + 1}. #{entry.name} [#{status}] #{duration_ms}"
-          lines << "     params: #{entry.params.inspect}" unless entry.params.nil? || entry.params.empty?
+          indent = "   " * depth
+          id = entry.execution_id ? " (#{_display_id(entry.execution_id)})" : ""
+
+          lines << "  #{indent}#{counter}. #{entry.name}#{id} [#{status}] #{duration_ms}"
+          lines << "  #{indent}   params: #{entry.params.inspect}" unless entry.params.nil? || entry.params.empty?
+
+          children.fetch(entry.execution_id, []).sort_by { |child| child[:index] }.each do |child|
+            render.call(child, depth + 1)
+          end
         end
+
+        roots.sort_by { |node| node[:index] }.each { |node| render.call(node, 0) }
         lines.join("\n")
       end
+
+      private
+
+      def _frame_type(frame)
+        return unless frame
+
+        (frame[:type] || frame["type"])&.to_sym
+      end
+
+      def _display_id(id)
+        prefix, suffix = id.to_s.split("_", 2)
+        return id.to_s unless suffix
+
+        "#{prefix}_#{suffix[0, 7]}"
+      end
+
+      def _parent_operation_id(entry)
+        frames = Array(entry.trace)[0...-1]
+        parent = frames.reverse.find { |frame| _frame_type(frame) == :operation }
+        parent && (parent[:id] || parent["id"])
+      end
     end
   end
 end

data/lib/dex/trace.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+module Dex
+  module Trace
+    FIBER_KEY = :_dex_trace
+    FRAME_TYPES = %i[actor operation handler].freeze
+
+    class << self
+      def start(actor: nil, trace_id: nil)
+        previous = _dump_state
+        _set_state(trace_id: (trace_id || Dex::Id.generate("tr_")).to_s, frames: [], event_context: nil)
+        _state[:frames] << _normalize_actor(actor) if actor
+        yield
+      ensure
+        _restore_state(previous)
+      end
+
+      def ensure_started!(trace_id: nil)
+        return false if active?
+
+        _state[:trace_id] = (trace_id || Dex::Id.generate("tr_")).to_s
+        true
+      end
+
+      def active?
+        !trace_id.nil?
+      end
+
+      def with_frame(frame)
+        auto_started = ensure_started!
+        pushed = false
+        push(frame)
+        pushed = true
+        yield
+      ensure
+        pop if pushed
+        stop! if auto_started
+      end
+
+      def with_event_context(event)
+        auto_started = ensure_started!(trace_id: event.trace_id)
+        previous = _state[:event_context]
+        _state[:event_context] = _build_event_context(event)
+        yield
+      ensure
+        _state[:event_context] = previous
+        stop! if auto_started
+      end
+
+      def restore_event_context(event_id:, trace_id:, event_class: nil, event_ancestry: [])
+        previous = _dump_state
+        effective_trace_id = trace_id&.to_s || _state[:trace_id]
+        _set_state(
+          trace_id: effective_trace_id,
+          frames: _normalize_frames(_state[:frames]),
+          event_context: {
+            id: event_id&.to_s,
+            trace_id: effective_trace_id,
+            event_class: event_class,
+            event_ancestry: Array(event_ancestry).compact.map(&:to_s)
+          }
+        )
+        yield
+      ensure
+        _restore_state(previous)
+      end
+
+      def push(frame)
+        _state[:frames] << _normalize_frame(frame)
+      end
+
+      def pop
+        _state[:frames].pop
+      end
+
+      def current
+        _deep_copy(_state[:frames])
+      end
+
+      def trace_id
+        _state[:trace_id]
+      end
+
+      def current_id
+        _state[:frames].last&.dig(:id)
+      end
+
+      def actor
+        frame = _state[:frames].find { |entry| entry[:type] == :actor }
+        frame ? _deep_copy(frame) : nil
+      end
+
+      def current_event_id
+        current_event_context&.dig(:id)
+      end
+
+      def current_event_context
+        context = _state[:event_context]
+        return _deep_copy(context) if context
+
+        handler = _state[:frames].reverse.find { |frame| frame[:type] == :handler && frame[:event_id] }
+        return nil unless handler
+
+        {
+          id: handler[:event_id],
+          trace_id: trace_id,
+          event_class: handler[:event_class],
+          event_ancestry: _deep_copy(Array(handler[:event_ancestry]))
+        }
+      end
+
+      def dump
+        return nil unless active?
+
+        data = {
+          trace_id: trace_id,
+          frames: current
+        }
+        data[:event_context] = _deep_copy(_state[:event_context]) if _state[:event_context]
+        data
+      end
+
+      def restore(data)
+        return yield unless data
+
+        previous = _dump_state
+        _set_state(
+          trace_id: _fetch(data, :trace_id)&.to_s,
+          frames: _normalize_frames(_fetch(data, :frames)),
+          event_context: _normalize_event_context(_fetch(data, :event_context))
+        )
+        yield
+      ensure
+        _restore_state(previous)
+      end
+
+      def to_s
+        current.filter_map { |frame| _format_frame(frame) }.join(" > ")
+      end
+
+      def clear!
+        Fiber[FIBER_KEY] = nil
+      end
+      alias_method :stop!, :clear!
+
+      private
+
+      def _state
+        Fiber[FIBER_KEY] ||= { trace_id: nil, frames: [], event_context: nil }
+      end
+
+      def _set_state(trace_id:, frames:, event_context:)
+        Fiber[FIBER_KEY] = {
+          trace_id: trace_id,
+          frames: frames,
+          event_context: event_context
+        }
+      end
+
+      def _dump_state
+        state = _state
+        return nil unless state[:trace_id] || !state[:frames].empty? || state[:event_context]
+
+        {
+          trace_id: state[:trace_id],
+          frames: _deep_copy(state[:frames]),
+          event_context: _deep_copy(state[:event_context])
+        }
+      end
+
+      def _restore_state(state)
+        if state
+          _set_state(
+            trace_id: state[:trace_id],
+            frames: _normalize_frames(state[:frames]),
+            event_context: _normalize_event_context(state[:event_context])
+          )
+        else
+          clear!
+        end
+      end
+
+      def _normalize_frames(frames)
+        Array(frames).map { |frame| _normalize_frame(frame) }
+      end
+
+      def _normalize_actor(actor)
+        raise ArgumentError, "actor must be a Hash" unless actor.is_a?(Hash)
+
+        normalized = _symbolize(actor)
+        actor_type = normalized[:type]
+        raise ArgumentError, "actor must include :type" if actor_type.nil? || actor_type.to_s.strip.empty?
+
+        frame = { type: :actor, actor_type: actor_type.to_s }
+        frame[:id] = normalized[:id].to_s if normalized.key?(:id) && !normalized[:id].nil?
+
+        normalized.each do |key, value|
+          next if %i[type id].include?(key)
+
+          frame[key] = _deep_copy(value)
+        end
+
+        frame
+      end
+
+      def _normalize_frame(frame)
+        raise ArgumentError, "trace frame must be a Hash" unless frame.is_a?(Hash)
+
+        normalized = _symbolize(frame)
+        type = normalized[:type]&.to_sym
+        raise ArgumentError, "trace frame type is required" unless type
+        raise ArgumentError, "unknown trace frame type: #{type.inspect}" unless FRAME_TYPES.include?(type)
+
+        normalized[:type] = type
+        normalized[:id] = normalized[:id].to_s if normalized.key?(:id) && !normalized[:id].nil?
+        normalized[:actor_type] = normalized[:actor_type].to_s if normalized.key?(:actor_type) && !normalized[:actor_type].nil?
+        normalized[:event_id] = normalized[:event_id].to_s if normalized.key?(:event_id) && !normalized[:event_id].nil?
+        normalized[:event_ancestry] = Array(normalized[:event_ancestry]).compact.map(&:to_s) if normalized.key?(:event_ancestry)
+        normalized
+      end
+
+      def _normalize_event_context(context)
+        return nil unless context
+
+        {
+          id: _fetch(context, :id)&.to_s,
+          trace_id: _fetch(context, :trace_id)&.to_s,
+          event_class: _fetch(context, :event_class),
+          event_ancestry: Array(_fetch(context, :event_ancestry)).compact.map(&:to_s)
+        }
+      end
+
+      def _build_event_context(event)
+        {
+          id: event.id.to_s,
+          trace_id: event.trace_id.to_s,
+          event_class: event.class.name,
+          event_ancestry: Array(event.metadata.event_ancestry).compact.map(&:to_s)
+        }
+      end
+
+      def _symbolize(hash)
+        hash.each_with_object({}) do |(key, value), result|
+          result[key.respond_to?(:to_sym) ? key.to_sym : key] = _deep_copy(value)
+        end
+      end
+
+      def _deep_copy(value)
+        case value
+        when Hash
+          value.each_with_object({}) { |(key, nested), result| result[key] = _deep_copy(nested) }
+        when Array
+          value.map { |nested| _deep_copy(nested) }
+        else
+          value
+        end
+      end
+
+      def _fetch(hash, key)
+        hash[key] || hash[key.to_s]
+      end
+
+      def _format_frame(frame)
+        case frame[:type]
+        when :actor
+          return nil unless frame[:actor_type]
+
+          frame[:id] ? "#{frame[:actor_type]}:#{frame[:id]}" : frame[:actor_type]
+        when :operation
+          name = frame[:class] || "Operation"
+          id = _display_id(frame[:id])
+          id ? "#{name}(#{id})" : name
+        when :handler
+          event_class = frame[:event_class] || "Event"
+          handler_name = frame[:class] || "Handler"
+          id = _display_id(frame[:id])
+          id ? "[#{event_class}] #{handler_name}(#{id})" : "[#{event_class}] #{handler_name}"
+        end
+      end
+
+      def _display_id(id)
+        return nil unless id
+
+        prefix, suffix = id.split("_", 2)
+        return id[0, 10] unless suffix
+
+        "#{prefix}_#{suffix[0, 7]}"
+      end
+    end
+  end
+end

data/lib/dex/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Dex
-  VERSION = "0.9.0"
+  VERSION = "0.10.0"
 end

data/lib/dexkit.rb

@@ -10,6 +10,7 @@ require_relative "dex/concern"
 require_relative "dex/ref_type"
 require_relative "dex/type_coercion"
 require_relative "dex/props_setup"
+require_relative "dex/context_dsl"
 require_relative "dex/context_setup"
 require_relative "dex/error"
 require_relative "dex/settings"
@@ -17,6 +18,8 @@ require_relative "dex/pipeline"
 require_relative "dex/executable"
 require_relative "dex/registry"
 require_relative "dex/type_serializer"
+require_relative "dex/id"
+require_relative "dex/trace"
 require_relative "dex/operation"
 require_relative "dex/event"
 require_relative "dex/tool"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dexkit
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Jacek Galanciak
@@ -168,6 +168,7 @@ files:
 - guides/llm/OPERATION.md
 - guides/llm/QUERY.md
 - lib/dex/concern.rb
+- lib/dex/context_dsl.rb
 - lib/dex/context_setup.rb
 - lib/dex/error.rb
 - lib/dex/event.rb
@@ -184,8 +185,11 @@ files:
 - lib/dex/event_test_helpers.rb
 - lib/dex/executable.rb
 - lib/dex/form.rb
+- lib/dex/form/context.rb
+- lib/dex/form/export.rb
 - lib/dex/form/nesting.rb
 - lib/dex/form/uniqueness_validator.rb
+- lib/dex/id.rb
 - lib/dex/match.rb
 - lib/dex/operation.rb
 - lib/dex/operation/async_proxy.rb
@@ -207,12 +211,14 @@ files:
 - lib/dex/operation/test_helpers/assertions.rb
 - lib/dex/operation/test_helpers/execution.rb
 - lib/dex/operation/test_helpers/stubbing.rb
+- lib/dex/operation/trace_wrapper.rb
 - lib/dex/operation/transaction_adapter.rb
 - lib/dex/operation/transaction_wrapper.rb
 - lib/dex/pipeline.rb
 - lib/dex/props_setup.rb
 - lib/dex/query.rb
 - lib/dex/query/backend.rb
+- lib/dex/query/export.rb
 - lib/dex/query/filtering.rb
 - lib/dex/query/sorting.rb
 - lib/dex/railtie.rb
@@ -222,6 +228,7 @@ files:
 - lib/dex/test_helpers.rb
 - lib/dex/test_log.rb
 - lib/dex/tool.rb
+- lib/dex/trace.rb
 - lib/dex/type_coercion.rb
 - lib/dex/type_serializer.rb
 - lib/dex/version.rb