dexkit 0.9.0 → 0.10.0

data/lib/dex/form/export.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Dex
+  class Form
+    module Export
+      module_function
+
+      TYPE_MAP = {
+        string: { type: "string" },
+        integer: { type: "integer" },
+        float: { type: "number" },
+        decimal: { type: "number" },
+        boolean: { type: "boolean" },
+        date: { type: "string", format: "date" },
+        datetime: { type: "string", format: "date-time" },
+        time: { type: "string", format: "time" }
+      }.freeze
+
+      def build_hash(source)
+        h = _serialize_form_definition(source)
+        h[:name] = source.name if source.name
+        desc = source.description
+        h[:description] = desc if desc
+        h
+      end
+
+      def build_json_schema(source) # rubocop:disable Metrics/MethodLength
+        properties = {}
+        required = []
+
+        source._field_registry.each do |name, field_def|
+          schema = _field_to_schema(field_def)
+          properties[name.to_s] = schema
+          required << name.to_s if field_def.required
+        end
+
+        _add_nested_properties(source, properties, required)
+
+        result = { "$schema": "https://json-schema.org/draft/2020-12/schema", type: "object" }
+        result[:title] = source.name if source.name
+        desc = source.description
+        result[:description] = desc if desc
+        result[:properties] = properties unless properties.empty?
+        result[:required] = required unless required.empty?
+        result[:additionalProperties] = false
+        result
+      end
+
+      def _serialize_fields(source)
+        source._field_registry.each_with_object({}) do |(name, field_def), hash|
+          entry = { type: field_def.type, required: field_def.required }
+          entry[:desc] = field_def.desc if field_def.desc
+          entry[:default] = field_def.default if field_def.default?
+          hash[name] = entry
+        end
+      end
+
+      def _serialize_form_definition(source)
+        h = { fields: _serialize_fields(source) }
+        nested = _serialize_nested(source)
+        h[:nested] = nested unless nested.empty?
+        h
+      end
+
+      def _serialize_nested(source)
+        nested = {}
+        source._nested_ones.each do |name, klass|
+          nested[name] = { type: :one }.merge(_serialize_form_definition(klass))
+        end
+        source._nested_manys.each do |name, klass|
+          nested[name] = { type: :many }.merge(_serialize_form_definition(klass))
+        end
+        nested
+      end
+
+      def _field_to_schema(field_def)
+        schema = TYPE_MAP[field_def.type]&.dup || {}
+        schema[:description] = field_def.desc if field_def.desc
+        schema[:default] = _coerce_default(field_def) if field_def.default?
+        schema
+      end
+
+      def _coerce_default(field_def)
+        val = field_def.default
+        case field_def.type
+        when :integer then val.is_a?(Integer) ? val : val.to_i
+        when :float, :decimal then val.is_a?(Float) ? val : val.to_f
+        when :boolean then !!val
+        when :string, :date, :datetime, :time then val.to_s
+        else val
+        end
+      end
+
+      def _nested_json_schema(klass)
+        properties = {}
+        required = []
+
+        klass._field_registry.each do |name, field_def|
+          schema = _field_to_schema(field_def)
+          properties[name.to_s] = schema
+          required << name.to_s if field_def.required
+        end
+
+        _add_nested_properties(klass, properties, required)
+
+        result = { type: "object" }
+        result[:properties] = properties unless properties.empty?
+        result[:required] = required unless required.empty?
+        result[:additionalProperties] = false
+        result
+      end
+
+      def _add_nested_properties(source, properties, required)
+        source._nested_ones.each do |name, klass|
+          properties[name.to_s] = _nested_json_schema(klass)
+          required << name.to_s
+        end
+
+        source._nested_manys.each do |name, klass|
+          properties[name.to_s] = { type: "array", items: _nested_json_schema(klass) }
+        end
+      end
+
+      private_class_method :_serialize_fields, :_serialize_form_definition, :_serialize_nested, :_field_to_schema,
+        :_coerce_default, :_nested_json_schema, :_add_nested_properties
+    end
+  end
+end

data/lib/dex/form/nesting.rb

@@ -70,6 +70,8 @@ module Dex
 
         def _build_nested_class(name, class_name, &block)
           klass = Class.new(Dex::Form, &block)
+          klass.instance_variable_set(:@_dex_nested_form, true)
+          Dex::Form.deregister(klass)
           const_name = class_name || name.to_s.singularize.camelize
           const_set(const_name, klass)
           klass

data/lib/dex/form.rb

@@ -3,6 +3,7 @@
 require "active_model"
 
 require_relative "form/nesting"
+require_relative "form/context"
 
 module Dex
   class Form
@@ -15,8 +16,17 @@ module Dex
     end
 
     include Nesting
+    include Context
     include Match
 
+    extend Registry
+
+    FIELD_DEFAULT_UNSET = Object.new.freeze
+
+    FieldDef = Data.define(:name, :type, :desc, :required, :default) do
+      def default? = !default.equal?(Dex::Form::FIELD_DEFAULT_UNSET)
+    end
+
     class ValidationError < StandardError
       attr_reader :form
 
@@ -27,6 +37,37 @@ module Dex
     end
 
     class << self
+      def _field_registry
+        @_field_registry ||= {}
+      end
+
+      def _required_fields
+        _field_registry.each_with_object([]) do |(name, f), list|
+          list << name if f.required
+        end
+      end
+
+      def field(name, type, desc: nil, default: FIELD_DEFAULT_UNSET, **options)
+        raise ArgumentError, "field name must be a Symbol, got #{name.inspect}" unless name.is_a?(Symbol)
+        raise ArgumentError, "field type must be a Symbol, got #{type.inspect}" unless type.is_a?(Symbol)
+        raise ArgumentError, "desc must be a String, got #{desc.inspect}" if desc && !desc.is_a?(String)
+
+        am_options = options.dup
+        am_options[:default] = default unless default.equal?(FIELD_DEFAULT_UNSET)
+        attribute name, type, **am_options
+        _field_registry[name] = FieldDef.new(name: name, type: type, desc: desc, required: true, default: default)
+      end
+
+      def field?(name, type, desc: nil, default: FIELD_DEFAULT_UNSET, **options)
+        raise ArgumentError, "field name must be a Symbol, got #{name.inspect}" unless name.is_a?(Symbol)
+        raise ArgumentError, "field type must be a Symbol, got #{type.inspect}" unless type.is_a?(Symbol)
+        raise ArgumentError, "desc must be a String, got #{desc.inspect}" if desc && !desc.is_a?(String)
+
+        actual_default = default.equal?(FIELD_DEFAULT_UNSET) ? nil : default
+        attribute name, type, default: actual_default, **options
+        _field_registry[name] = FieldDef.new(name: name, type: type, desc: desc, required: false, default: default)
+      end
+
       def model(klass = nil)
         if klass
           raise ArgumentError, "model must be a Class, got #{klass.inspect}" unless klass.is_a?(Class)
@@ -42,9 +83,38 @@ module Dex
 
       def inherited(subclass)
         super
+        subclass.instance_variable_set(:@_field_registry, _field_registry.dup)
         subclass.instance_variable_set(:@_nested_ones, _nested_ones.dup)
         subclass.instance_variable_set(:@_nested_manys, _nested_manys.dup)
       end
+
+      def _dex_nested_form?
+        !!instance_variable_get(:@_dex_nested_form)
+      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.reject { |klass| klass._dex_nested_form? }.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
     end
 
     silence_redefinition_of_method :model_name
@@ -66,6 +136,18 @@ module Dex
       # setters are assignable; everything else is silently dropped.
       attributes = attributes.to_unsafe_h if attributes.respond_to?(:to_unsafe_h)
       attrs = (attributes || {}).transform_keys(&:to_s)
+
+      # Context injection — fill ambient values for unmapped keys
+      mappings = self.class.context_mappings
+      unless mappings.empty?
+        ambient = Dex.context
+        mappings.each do |attr_name, context_key|
+          str_name = attr_name.to_s
+          next if attrs.key?(str_name)
+          attrs[str_name] = ambient[context_key] if ambient.key?(context_key)
+        end
+      end
+
       record = attrs.delete("record")
       @record = record if record.nil? || record.respond_to?(:persisted?)
       provided_keys = attrs.keys
@@ -95,9 +177,10 @@ module Dex
     end
 
     def valid?(context = nil)
-      super_result = super
-      nested_result = _validate_nested(context)
-      super_result && nested_result
+      super
+      _fix_boolean_presence_errors
+      nested_valid = _validate_nested(context)
+      errors.empty? && nested_valid
     end
 
     def to_h
@@ -111,8 +194,40 @@ module Dex
 
     alias_method :to_hash, :to_h
 
+    validate :_validate_required_fields
+
     private
 
+    def _validate_required_fields
+      explicit = self.class.validators
+        .select { |v| v.is_a?(ActiveModel::Validations::PresenceValidator) }
+        .reject { |v| v.options.key?(:on) || v.options.key?(:if) || v.options.key?(:unless) }
+        .flat_map(&:attributes).map(&:to_sym).to_set
+
+      self.class._required_fields.each do |name|
+        next if explicit.include?(name)
+        field_def = self.class._field_registry[name]
+        value = public_send(name)
+        blank = (field_def.type == :boolean) ? value.nil? : value.blank?
+        errors.add(name, :blank) if blank
+      end
+    end
+
+    def _fix_boolean_presence_errors
+      explicit = self.class.validators
+        .select { |v| v.is_a?(ActiveModel::Validations::PresenceValidator) }
+        .reject { |v| v.options.key?(:on) || v.options.key?(:if) || v.options.key?(:unless) }
+        .flat_map(&:attributes).map(&:to_sym)
+
+      explicit.each do |name|
+        field_def = self.class._field_registry[name]
+        next unless field_def&.type == :boolean
+        next if public_send(name).nil?
+
+        errors.delete(name, :blank)
+      end
+    end
+
     def _extract_nested_attributes(attrs)
       nested_keys = self.class._nested_ones.keys.map(&:to_s) +
         self.class._nested_manys.keys.map(&:to_s)
@@ -140,3 +255,4 @@ module Dex
 end
 
 require_relative "form/uniqueness_validator"
+require_relative "form/export"

data/lib/dex/id.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Dex
+  module Id
+    ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
+    TIMESTAMP_WIDTH = 8
+    RANDOM_WIDTH = 12
+
+    module_function
+
+    def generate(prefix)
+      "#{prefix}#{base58_encode(current_milliseconds, TIMESTAMP_WIDTH)}#{random_suffix(RANDOM_WIDTH)}"
+    end
+
+    def base58_encode(number, width = nil)
+      encoded = +""
+      value = number.to_i
+
+      loop do
+        value, remainder = value.divmod(ALPHABET.length)
+        encoded.prepend(ALPHABET[remainder])
+        break unless value.positive?
+      end
+
+      width ? encoded.rjust(width, ALPHABET[0]) : encoded
+    end
+
+    def random_suffix(width)
+      Array.new(width) { ALPHABET[SecureRandom.random_number(ALPHABET.length)] }.join
+    end
+
+    def current_milliseconds
+      Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)
+    end
+  end
+end

data/lib/dex/operation/async_proxy.rb

@@ -21,21 +21,31 @@ module Dex
 
       def enqueue_direct_job
         job = apply_options(Operation::DirectJob)
-        payload = { class_name: operation_class_name, params: serialized_params }
+        payload = {
+          class_name: operation_class_name,
+          params: serialized_params,
+          trace: Dex::Trace.dump
+        }
         apply_once_payload!(payload)
         job.perform_later(**payload)
       end
 
       def enqueue_record_job
         @operation.send(:_record_validate_backend!, async: true)
+        execution_id = Dex::Id.generate("op_")
         record = Dex.record_backend.create_record(
+          id: execution_id,
           name: operation_class_name,
           params: serialized_params,
           status: "pending"
         )
         begin
           job = apply_options(Operation::RecordJob)
-          payload = { class_name: operation_class_name, record_id: record.id.to_s }
+          payload = {
+            class_name: operation_class_name,
+            record_id: record.id.to_s,
+            trace: Dex::Trace.dump
+          }
           apply_once_payload!(payload)
           job.perform_later(**payload)
         rescue => e

data/lib/dex/operation/jobs.rb

@@ -9,29 +9,30 @@ module Dex
       case name
       when :DirectJob
         const_set(:DirectJob, Class.new(ActiveJob::Base) do
-          def perform(class_name:, params:, once_key: nil, once_bypass: false)
+          def perform(class_name:, params:, trace: nil, once_key: nil, once_bypass: false)
             klass = class_name.constantize
             op = klass.new(**klass.send(:_coerce_serialized_hash, params))
             op.once(once_key) if once_key
             op.once(nil) if once_bypass
-            op.call
+            Dex::Trace.restore(trace) { op.call }
           end
         end)
       when :RecordJob
         const_set(:RecordJob, Class.new(ActiveJob::Base) do
-          def perform(class_name:, record_id:, once_key: nil, once_bypass: false)
+          def perform(class_name:, record_id:, trace: nil, once_key: nil, once_bypass: false)
             klass = class_name.constantize
             record = Dex.record_backend.find_record(record_id)
             params = klass.send(:_coerce_serialized_hash, record.params || {})
 
             op = klass.new(**params)
             op.instance_variable_set(:@_dex_record_id, record_id)
+            op.instance_variable_set(:@_dex_execution_id, record_id)
             op.once(once_key) if once_key
             op.once(nil) if once_bypass
 
             update_status(record_id, status: "running")
             pipeline_started = true
-            op.call
+            Dex::Trace.restore(trace) { op.call }
           rescue => e
             # RecordWrapper handles failures during op.call via its own rescue.
             # This catches pre-pipeline failures (find_record, deserialization, etc.)

data/lib/dex/operation/once_wrapper.rb

@@ -180,6 +180,7 @@ module Dex
           once_key: key, once_key_expires_at: expires_at)
       else
         record = Dex.record_backend.create_record(
+          id: @_dex_execution_id,
           name: self.class.name,
           once_key: key,
           once_key_expires_at: expires_at,

data/lib/dex/operation/record_backend.rb

@@ -156,7 +156,8 @@ module Dex
         end
 
         def has_field?(field_name)
-          record_class.fields.key?(field_name.to_s)
+          field_name = field_name.to_s
+          record_class.fields.key?(field_name) || (field_name == "id" && record_class.fields.key?("_id"))
         end
       end
     end

data/lib/dex/operation/record_wrapper.rb

@@ -88,7 +88,7 @@ module Dex
       else
         _record_success_attrs(interceptor.result)
       end
-      Dex.record_backend.update_record(@_dex_record_id, attrs)
+      Dex.record_backend.update_record(@_dex_record_id, _record_base_attrs(include_id: false).merge(attrs))
     rescue => e
       _record_handle_error(e)
     end
@@ -108,7 +108,7 @@ module Dex
       attrs[:once_key] = nil if defined?(@_once_key) || self.class.settings_for(:once).fetch(:defined, false)
 
       if _record_has_pending_record?
-        Dex.record_backend.update_record(@_dex_record_id, attrs)
+        Dex.record_backend.update_record(@_dex_record_id, _record_base_attrs(include_id: false).merge(attrs))
       else
         Dex.record_backend.create_record(_record_base_attrs.merge(attrs))
       end
@@ -116,8 +116,18 @@ module Dex
       _record_handle_error(e)
     end
 
-    def _record_base_attrs
-      attrs = { name: self.class.name }
+    def _record_base_attrs(include_id: true)
+      trace_snapshot = Dex::Trace.current
+      actor_frame = Dex::Trace.actor
+
+      attrs = {
+        name: self.class.name,
+        trace_id: Dex::Trace.trace_id,
+        trace: trace_snapshot,
+        actor_type: actor_frame&.dig(:actor_type),
+        actor_id: actor_frame&.dig(:id)&.to_s
+      }
+      attrs[:id] = @_dex_execution_id if include_id && defined?(@_dex_execution_id) && @_dex_execution_id
       attrs[:params] = _record_params? ? _record_params : nil
       attrs
     end

data/lib/dex/operation/test_helpers/assertions.rb

@@ -199,6 +199,30 @@ module Dex
           "Expected no operations to be enqueued, but #{after_count - before_count} were"
       end
 
+      # --- Trace assertions ---
+
+      def assert_trace_includes(operation_class, msg: nil)
+        expected = operation_class.is_a?(Class) ? operation_class.name : operation_class.to_s
+        trace_classes = Dex::Trace.current.map { |frame| frame[:class] }.compact
+
+        assert_includes trace_classes, expected,
+          msg || "Expected trace to include #{expected.inspect}, got #{trace_classes.inspect}"
+      end
+
+      def assert_trace_actor(type:, id: :_not_given, msg: nil)
+        actor = Dex::Trace.actor
+        refute_nil actor, msg || "Expected a trace actor, but no actor is set"
+        assert_equal type.to_s, actor[:actor_type], msg || "Trace actor type mismatch"
+        assert_equal id.to_s, actor[:id], msg || "Trace actor id mismatch" unless id == :_not_given
+        actor
+      end
+
+      def assert_trace_depth(expected, msg: nil)
+        actual = Dex::Trace.current.size
+        assert_equal expected, actual,
+          msg || "Expected trace depth #{expected}, got #{actual}.\nTrace: #{Dex::Trace.current.inspect}"
+      end
+
       # --- Transaction assertions ---
 
       def assert_rolls_back(model_class, &block)

data/lib/dex/operation/test_helpers.rb

@@ -97,6 +97,12 @@ module Dex
           Dex::Operation::Ok.new(result)
         end
 
+        trace = Dex::Trace.current + [{
+          type: :operation,
+          id: @_dex_execution_id,
+          class: self.class.name || self.class.to_s
+        }]
+
         entry = Dex::TestLog::Entry.new(
           type: "Operation",
           name: self.class.name || self.class.to_s,
@@ -104,7 +110,10 @@ module Dex
           params: _test_safe_params,
           result: safe_result,
           duration: duration,
-          caller_location: caller_locations(4, 1)&.first
+          caller_location: caller_locations(4, 1)&.first,
+          execution_id: @_dex_execution_id,
+          trace_id: @_dex_trace_id,
+          trace: trace
         )
         Dex::TestLog.record(entry)
       end
@@ -120,6 +129,7 @@ module Dex
 
       def setup
         super
+        Dex::Trace.clear!
         Dex::TestLog.clear!
         Dex::Operation::TestWrapper.clear_all_stubs!
       end

data/lib/dex/operation/trace_wrapper.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Dex
+  module TraceWrapper
+    extend Dex::Concern
+
+    def _trace_wrap
+      @_dex_execution_id ||= Dex::Id.generate("op_")
+
+      Dex::Trace.with_frame(
+        type: :operation,
+        id: @_dex_execution_id,
+        class: self.class.name
+      ) do
+        @_dex_trace_id = Dex::Trace.trace_id
+        yield
+      end
+    end
+  end
+end

data/lib/dex/operation.rb

@@ -4,6 +4,7 @@
 require_relative "operation/result_wrapper"
 require_relative "operation/once_wrapper"
 require_relative "operation/record_wrapper"
+require_relative "operation/trace_wrapper"
 require_relative "operation/transaction_wrapper"
 require_relative "operation/lock_wrapper"
 require_relative "operation/async_wrapper"
@@ -139,6 +140,7 @@ module Dex
     include AsyncWrapper
     include SafeWrapper
 
+    use TraceWrapper, at: :outer
     use ResultWrapper
     use GuardWrapper
     use OnceWrapper

data/lib/dex/query/export.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Dex
+  class Query
+    module Export
+      module_function
+
+      def build_hash(source)
+        h = {}
+        h[:name] = source.name if source.name
+        desc = source.description
+        h[:description] = desc if desc
+        h[:props] = _serialize_props(source)
+        ctx = _serialize_context(source)
+        h[:context] = ctx unless ctx.empty?
+        h[:filters] = source.filters unless source.filters.empty?
+        h[:sorts] = source.sorts unless source.sorts.empty?
+        h
+      end
+
+      def build_json_schema(source) # rubocop:disable Metrics/MethodLength
+        descs = source.respond_to?(:prop_descriptions) ? source.prop_descriptions : {}
+        properties = {}
+        required = []
+
+        if source.respond_to?(:literal_properties)
+          source.literal_properties.each do |prop|
+            prop_desc = descs[prop.name]
+            schema = TypeSerializer.to_json_schema(prop.type, desc: prop_desc)
+            properties[prop.name.to_s] = schema
+            required << prop.name.to_s if prop.required?
+          end
+        end
+
+        result = { "$schema": "https://json-schema.org/draft/2020-12/schema" }
+        result[:title] = source.name if source.name
+        desc = source.description
+        result[:description] = desc if desc
+        result[:type] = "object"
+        result[:properties] = properties unless properties.empty?
+        result[:required] = required unless required.empty?
+        result[:additionalProperties] = false
+        result
+      end
+
+      def _serialize_props(source)
+        return {} unless source.respond_to?(:literal_properties)
+
+        descs = source.respond_to?(:prop_descriptions) ? source.prop_descriptions : {}
+        source.literal_properties.each_with_object({}) do |prop, hash|
+          entry = { type: TypeSerializer.to_string(prop.type), required: prop.required? }
+          entry[:desc] = descs[prop.name] if descs[prop.name]
+          hash[prop.name] = entry
+        end
+      end
+
+      def _serialize_context(source)
+        source.respond_to?(:context_mappings) ? source.context_mappings.presence || {} : {}
+      end
+
+      private_class_method :_serialize_props, :_serialize_context
+    end
+  end
+end