julewire-core 1.0.0

data/lib/julewire/core/records/public_projection.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Records
+      class PublicProjection
+        include Enumerable
+
+        INTERNAL_KEYS = Fields::Bags.hidden_output_sections
+        INTERNAL_EXECUTION_KEYS = %i[
+          ancestors
+          ancestors_truncated
+          depth
+          parent
+          root
+        ].freeze
+
+        class << self
+          def public_execution(value)
+            return value unless INTERNAL_EXECUTION_KEYS.any? { value.key?(it) }
+
+            value.except(*INTERNAL_EXECUTION_KEYS)
+          end
+        end
+
+        def initialize(record)
+          Record.validate_normalized!(record)
+          @record = record
+        end
+
+        def each
+          return enum_for(:each) unless block_given?
+
+          @record.each do |key, value|
+            next if INTERNAL_KEYS.include?(key)
+
+            yield key, output_value(key, value)
+          end
+        end
+
+        private
+
+        def output_value(key, value)
+          return self.class.public_execution(value) if key == :execution && value.is_a?(Hash)
+
+          value
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/records/raw_input.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Records
+      module RawInput
+        # Reads user-supplied emit hashes before draft normalization.
+        SEVERITY_KEYS = [:severity, "severity"].freeze
+        SEVERITY_KEY = SEVERITY_KEYS.fetch(0)
+        SEVERITY_STRING_KEY = SEVERITY_KEYS.fetch(1)
+        private_constant :SEVERITY_KEYS, :SEVERITY_KEY, :SEVERITY_STRING_KEY
+
+        class << self
+          def explicit_severity?(input)
+            hash_input?(input) && (input.key?(SEVERITY_KEY) || input.key?(SEVERITY_STRING_KEY))
+          end
+
+          def severity_key?(key)
+            SEVERITY_KEYS.include?(key)
+          end
+
+          def without_severity_keys(input)
+            input.except(*SEVERITY_KEYS)
+          end
+
+          def value(input, key, default: nil)
+            return default unless hash_input?(input)
+            return input[key] if input.key?(key)
+            return input[key.to_s] if input.key?(key.to_s)
+
+            default
+          end
+
+          def hash_input?(input)
+            input.is_a?(Hash) || LazyEmitInput.input?(input)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/records/record.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Julewire
+  module Core
+    module Records
+      # @api extension
+      class Record
+        include Enumerable
+        include Deconstruct
+
+        KINDS = {
+          "point" => :point,
+          "summary" => :summary
+        }.freeze
+        HASH_SECTIONS = Fields::Bags.record_hash_sections
+        REQUIRED_KEYS = Fields::Bags.required_record_keys
+
+        class << self
+          def from_normalized_hash(record, lineage: nil)
+            if record.is_a?(Hash)
+              lineage ||= Execution::Lineage.from_execution_hash(record[:execution])
+              record = record.merge(execution: Execution::Lineage.clean_lazy_relationship_hash(record[:execution]))
+            end
+            validate_normalized_hash!(record)
+            new(snapshot_hash(record), lineage: lineage)
+          end
+
+          def from_owned_hash(record, lineage: nil, trust_frozen: false)
+            if record.is_a?(Hash)
+              lineage ||= Execution::Lineage.from_execution_hash(record.fetch(:execution))
+              execution = Execution::Lineage.clean_lazy_relationship_hash(record.fetch(:execution))
+              record = record.frozen? ? record.merge(execution: execution) : replace_execution(record, execution)
+            end
+            validate_normalized_hash!(record)
+            new(Serialization::DeepFreeze.call(record, trust_frozen: trust_frozen), lineage: lineage)
+          end
+
+          def validate_normalized!(record)
+            return record if record.is_a?(self)
+
+            raise TypeError, "expected Julewire::Record"
+          end
+
+          def validate_normalized_hash!(record)
+            validate_hash!(record)
+            record
+          end
+
+          private
+
+          def replace_execution(record, execution)
+            record[:execution] = execution
+            record
+          end
+
+          def validate_hash!(record)
+            raise TypeError, "record must be a normalized Hash" unless record.is_a?(Hash)
+
+            validate_symbol_keys!(record)
+
+            validate_required_keys!(record)
+            validate_known_keys!(record)
+
+            validate_kind!(record.fetch(:kind))
+            validate_severity!(record.fetch(:severity))
+            validate_hash_sections!(record)
+            validate_error!(record.fetch(:error))
+          end
+
+          def validate_symbol_keys!(record)
+            record.each_key do |key|
+              raise TypeError, "record must not use string keys" if key.is_a?(String)
+            end
+          end
+
+          def validate_required_keys!(record)
+            missing = nil
+            REQUIRED_KEYS.each do |key|
+              next if record.key?(key)
+
+              (missing ||= []) << key
+            end
+            raise TypeError, "record must be complete (missing: #{missing.join(", ")})" if missing
+          end
+
+          def validate_known_keys!(record)
+            unknown = nil
+            record.each_key do |key|
+              next if REQUIRED_KEYS.include?(key)
+
+              (unknown ||= []) << key
+            end
+            return unless unknown
+
+            raise TypeError, "record has unknown top-level keys: #{unknown.join(", ")}"
+          end
+
+          def validate_kind!(value)
+            return if KINDS.value?(value)
+
+            raise TypeError, "record kind must be :point or :summary"
+          end
+
+          def validate_severity!(value)
+            return if Severity::VALUES.include?(value)
+
+            raise TypeError, "record severity must be one of: #{Severity::VALUES.join(", ")}"
+          end
+
+          def validate_hash_sections!(record)
+            HASH_SECTIONS.each do |section|
+              next if record.fetch(section).is_a?(Hash)
+
+              raise TypeError, "record #{section} must be a Hash"
+            end
+          end
+
+          def validate_error!(value)
+            return if value.nil? || value.is_a?(Hash)
+
+            raise TypeError, "record error must be nil or a Hash"
+          end
+
+          def snapshot_hash(record)
+            Serialization::ValueCopy.call(
+              record,
+              freeze_values: true
+            )
+          end
+        end
+
+        attr_reader :lineage
+
+        def initialize(data, lineage: nil)
+          @data = data
+          @lineage = (lineage || Execution::Lineage.from_execution_hash(fetch(:execution))).freeze
+          freeze
+        end
+
+        def [](key) = @data[key]
+
+        def fetch(...) = @data.fetch(...)
+
+        def dig(...) = @data.dig(...)
+
+        def key?(key) = @data.key?(key)
+
+        def each(&) = @data.each(&)
+
+        def to_h = Fields::FieldSet.deep_dup(@data)
+
+        # @api internal
+        def serializable_data = @data
+
+        REQUIRED_KEYS.each do |key|
+          define_method(key) { @data[key] }
+        end
+
+        def ==(other)
+          other.instance_of?(Record) && @data == other.serializable_data
+        end
+
+        def eql?(other)
+          other.instance_of?(Record) && @data.eql?(other.serializable_data)
+        end
+
+        def hash = @data.hash
+
+        def inspect = "#<#{self.class} #{@data}>"
+      end
+    end
+  end
+end

data/lib/julewire/core/records/severity.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+
+module Julewire
+  module Core
+    module Records
+      module Severity
+        VALUES = %i[debug info warn error fatal unknown].freeze
+        STRING_VALUES = VALUES.to_h { [it.name, it] }.freeze
+        RANKS = VALUES.each_with_index.to_h.freeze
+        LOGGER_INTEGER_VALUES = VALUES.each_with_index.to_h.invert.freeze
+
+        class << self
+          def normalize(value)
+            return value if RANKS.key?(value)
+
+            severity = severity_symbol(value)
+            return severity if RANKS.key?(severity)
+
+            raise ArgumentError, "unsupported severity: #{value.inspect}"
+          end
+
+          def severity_symbol(value)
+            case value
+            when Symbol
+              value.downcase
+            when String
+              STRING_VALUES[value.downcase]
+            when Integer
+              LOGGER_INTEGER_VALUES[value]
+            end
+          end
+
+          def rank(value)
+            rank = RANKS[value]
+            return rank unless rank.nil?
+
+            RANKS.fetch(normalize(value))
+          end
+        end
+      end
+    end
+  end
+end