panko_serializer 0.8.4 → 1.0.0

data/lib/panko/code_gen/descriptor_builder.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require_relative "../code_gen"
+require_relative "filter_adapter"
+
+module Panko
+  module CodeGen
+    # Builds a serializer class's Descriptor from its DSL declarations. Nested Descriptors are
+    # built when the association is declared, so +build+ never recurses.
+    module DescriptorBuilder
+      module_function
+
+      def build(serializer_class)
+        Descriptor.new(
+          name: descriptor_name(serializer_class),
+          model: nil,
+          attributes: serializer_class._cg_attributes.dup,
+          method_attributes: serializer_class._cg_method_attributes.dup,
+          associations: serializer_class._cg_associations.dup,
+          parent_class: serializer_class
+        )
+      end
+
+      # "::" is replaced because the name becomes a constant inside an anonymous namespace, where
+      # a qualified name would reopen the real outer module.
+      def descriptor_name(serializer_class)
+        name = serializer_class.name || "PankoSerializer#{serializer_class.object_id}"
+        name.gsub("::", "__")
+      end
+
+      # The engine defines one Generated Class per Descriptor object, named after +name+.
+      # Equal Descriptors become one object, so two associations using one child serializer share
+      # a class and the child's method fields stay monomorphic on +self+. Different Descriptors
+      # with one name (a self-reference snapshot, a static filter, another Model) get a suffix.
+      # +shared+ is keyed before the final name is set, so equal subtrees give equal keys.
+      def uniquify_names(descriptor, seen = Hash.new(0), shared = {})
+        associations = descriptor.associations.map do |association|
+          association.with(
+            descriptor: uniquify_names(association.descriptor, seen, shared),
+            variants: association.variants.map { |variant| uniquify_names(variant, seen, shared) }
+          )
+        end
+        rebuilt = descriptor.with(associations: associations)
+        shared[rebuilt] ||= begin
+          seen[descriptor.name] += 1
+          count = seen[descriptor.name]
+          rebuilt.with(name: (count == 1) ? descriptor.name : "#{descriptor.name}_#{count}")
+        end
+      end
+
+      # Bakes a static association filter (+has_many :x, only: [...]+) into the cached Descriptor.
+      def narrow(descriptor, only, except)
+        return descriptor if blank?(only) && blank?(except)
+        narrow_by(descriptor, FilterAdapter.to_engine_filters(only, except))
+      end
+
+      # A child with no specializable class is left unchanged. Several declared classes
+      # become +Association#variants+, which share a name, so callers run {uniquify_names}.
+      # +seen+ keeps each (Descriptor, Model) result, so a child shared by several associations
+      # stays one object. A pair still in progress is a cycle and comes back unspecialized.
+      def specialize(descriptor, model, seen = {})
+        key = [descriptor.__id__, model]
+        return seen[key] || descriptor if seen.key?(key)
+        seen[key] = nil
+        associations = descriptor.associations.map do |association|
+          child_models = child_models(model, association)
+          case child_models.size
+          when 0 then association
+          when 1 then association.with(descriptor: specialize(association.descriptor, child_models.first, seen))
+          else
+            association.with(variants: child_models.map { |child_model| specialize(association.descriptor, child_model, seen) })
+          end
+        end
+        seen[key] = descriptor.with(model: model, associations: associations)
+      end
+
+      def child_models(model, association)
+        return [] unless association.descriptor.model.nil?
+        reflection = model.reflect_on_association(association.source) if model.respond_to?(:reflect_on_association)
+        return Array(reflected_child_model(reflection)) if reflection
+        declared_models(association.descriptor.parent_class).select do |klass|
+          specializable?(klass) && serves?(klass, association.descriptor)
+        end
+      end
+      private_class_method :child_models
+
+      # A declared model missing one of the sources would stop the whole parent from compiling,
+      # so it is left out and its records get the unspecialized child.
+      def serves?(klass, descriptor)
+        ActiveRecord::DefineAttributeMethods.ensure!(klass)
+        sources = descriptor.attributes.map(&:source) + descriptor.associations.map(&:source)
+        sources.all? do |source|
+          ActiveRecord::AccessClassifier.classify(klass, source)
+          true
+        rescue UnknownSourceError
+          false
+        end
+      end
+      private_class_method :serves?
+
+      def declared_models(serializer_class)
+        serializer_class.respond_to?(:_cg_models) ? Array(serializer_class._cg_models) : []
+      end
+      private_class_method :declared_models
+
+      def reflected_child_model(reflection)
+        return nil if reflection.polymorphic?
+        klass = begin
+          reflection.klass
+        rescue
+          # An undefined +class_name:+ or a badly declared association raises here; such a child
+          # is just not specializable.
+          nil
+        end
+        specializable?(klass) ? klass : nil
+      end
+      private_class_method :reflected_child_model
+
+      def specializable?(klass)
+        return false if klass.nil? || !resolvable_name?(klass)
+        klass.respond_to?(:columns_hash) && klass.respond_to?(:attribute_methods_generated?)
+      end
+      private_class_method :specializable?
+
+      # The specialized code checks +record.instance_of?(::<Name>)+, so the name must resolve
+      # to this same class object, or the check raises +NameError+ or never matches.
+      def self.resolvable_name?(klass)
+        name = klass.name
+        return false if name.nil?
+        Object.const_defined?(name) && Object.const_get(name).equal?(klass)
+      rescue NameError
+        false
+      end
+
+      def narrow_by(descriptor, engine)
+        only_set = engine[:only]&.to_set
+        except_set = engine[:except]&.to_set
+        descriptor.with(
+          attributes: descriptor.attributes.reject { |a| drop?(a.name, only_set, except_set) },
+          method_attributes: descriptor.method_attributes.reject { |m| drop?(m.name, only_set, except_set) },
+          associations: descriptor.associations.reject { |as| drop?(as.source, only_set, except_set) }.map do |as|
+            sub = engine[as.source]
+            (sub.is_a?(Hash) && !sub.empty?) ? as.with(descriptor: narrow_by(as.descriptor, sub)) : as
+          end
+        )
+      end
+      private_class_method :narrow_by
+
+      def drop?(name, only_set, except_set)
+        if only_set
+          !only_set.include?(name)
+        elsif except_set
+          except_set.include?(name)
+        else
+          false
+        end
+      end
+      private_class_method :drop?
+
+      def blank?(filter)
+        filter.nil? || (filter.respond_to?(:empty?) && filter.empty?)
+      end
+      private_class_method :blank?
+    end
+  end
+end

data/lib/panko/code_gen/dump.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Panko::CodeGen
+  class Dump
+    def initialize(descriptor, output:, config:, path:,
+      validator: Validators::Validator.new, generator: Generator.new)
+      @descriptor = descriptor
+      @output = output
+      @config = config
+      @path = path
+      @validator = validator
+      @generator = generator
+    end
+
+    def dump
+      validate_path!
+      @validator.validate(@descriptor, output: @output, config: @config)
+      if @descriptor.associations.empty?
+        write_flat
+      else
+        write_fan_out
+      end
+      @path
+    end
+
+    private
+
+    def validate_path!
+      unless @path.is_a?(String)
+        raise ArgumentError,
+          "path: must be a String, got #{@path.class} (#{@path.inspect})"
+      end
+      raise ArgumentError, "path: must not be empty" if @path.empty?
+    end
+
+    def write_flat
+      source = @generator.emit(@descriptor, output: @output, config: @config)
+      File.write(@path, source)
+    end
+
+    # Inner file paths are derived, never taken from the caller: +require_relative+
+    # lines name derived basenames. When the root is in a cycle, its peers
+    # +require_relative+ it by its derived name, so +path:+ must use that basename.
+    def write_fan_out
+      directory = File.dirname(@path)
+      Generators::Fanout.emit_files(@descriptor, output: @output, config: @config).each do |file|
+        target = file[:descriptor].equal?(@descriptor) ? @path : File.join(directory, file[:basename])
+        File.write(target, file[:source])
+      end
+    end
+  end
+end

data/lib/panko/code_gen/errors.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Panko::CodeGen
+  # Errors raised by user code (method bodies, record reads) are not wrapped in it.
+  class Error < StandardError; end
+
+  # Raised while building a Descriptor or one of its parts with a wrong type or shape,
+  # and by Config for an invalid +hash_*_key_type+.
+  class DescriptorError < Error; end
+
+  class CompileError < Error; end
+
+  class NameCollisionError < CompileError; end
+
+  # Specialized path only: the source is neither a column nor a method on the model.
+  # On the generic path a missing method raises Ruby's own +NoMethodError+ at run time.
+  class UnknownSourceError < CompileError; end
+
+  # A method body or +if:+ callable whose arity is outside 0..3, variadic included.
+  class ArityError < CompileError; end
+end

data/lib/panko/code_gen/filter.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "filters/none"
+require_relative "filters/indexed"
+
+module Panko::CodeGen
+  module Filter
+    # Validates every level here, once per call, so the generated per-record
+    # bodies need no validation branches.
+    def self.wrap(filters, field_index = nil)
+      return None if filters.nil? || filters.empty?
+      validate_no_only_except_co_supply!(filters)
+      raise ArgumentError, "Filter.wrap: a non-empty filters Hash requires a field_index (the Generated Class's FIELD_INDEX)" if field_index.nil?
+      Indexed.build(filters, field_index)
+    end
+
+    def self.validate_no_only_except_co_supply!(hash)
+      if hash.key?(:only) && hash.key?(:except)
+        raise ArgumentError,
+          "filters: cannot supply both :only and :except at the same level " \
+          "(got only: #{hash[:only].inspect}, except: #{hash[:except].inspect})"
+      end
+      hash.each_value do |value|
+        validate_no_only_except_co_supply!(value) if value.is_a?(Hash)
+      end
+    end
+    private_class_method :validate_no_only_except_co_supply!
+  end
+end

data/lib/panko/code_gen/filter_adapter.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "../code_gen"
+
+module Panko
+  module CodeGen
+    # Translates Panko's +only:+/+except:+ filters into the engine's runtime Filter shape.
+    module FilterAdapter
+      module_function
+
+      def to_engine_filters(only, except)
+        only_attrs, only_assocs = split(only)
+        except_attrs, except_assocs = split(except)
+
+        result = {}
+        merge_level!(result, only_attrs, except_attrs)
+
+        (only_assocs.keys | except_assocs.keys).each do |source|
+          result[source] = to_engine_filters(only_assocs[source], except_assocs[source])
+        end
+
+        result
+      end
+
+      def split(filter)
+        case filter
+        when nil then [[], {}]
+        when ::Array then [filter, {}]
+        when ::Hash then [Array(filter[:instance]), filter.except(:instance)]
+        else raise ArgumentError, "filters must be an Array or Hash, got #{filter.class}"
+        end
+      end
+
+      # Filter.wrap raises when one level has both :only and :except, so both fold into :only.
+      def merge_level!(result, only_attrs, except_attrs)
+        if !only_attrs.empty?
+          result[:only] = only_attrs - except_attrs
+        elsif !except_attrs.empty?
+          result[:except] = except_attrs
+        end
+      end
+    end
+  end
+end

data/lib/panko/code_gen/filters/indexed.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Panko::CodeGen
+  module Filter
+    module Indexed
+      module_function
+
+      def build(hash, field_index)
+        n = field_index.size
+        only = hash[:only]
+        except = hash[:except]
+        only_set = only&.to_set
+        except_set = except&.to_set
+
+        arr = ::Array.new(n)
+        field_index.each do |name, i|
+          arr[i] = drop?(name, only_set, except_set)
+        end
+        Array.new(hash, arr)
+      end
+
+      def drop?(name, only_set, except_set)
+        if only_set
+          !only_set.include?(name)
+        elsif except_set
+          except_set.include?(name)
+        else
+          false
+        end
+      end
+
+      class Array
+        def initialize(hash, drops_array)
+          @hash = hash
+          @drops_array = drops_array
+          @children_cache = {}
+        end
+
+        def drops?(index)
+          @drops_array[index]
+        end
+
+        # Each cached entry keeps the +field_index+ it was built for (checked with
+        # +equal?+): two Associations may share a Source but nest different classes.
+        def child(source, field_index)
+          cached = @children_cache[source]
+          return cached[1] if cached && cached[0].equal?(field_index)
+          resolved = Indexed.resolve_child(@hash, source, field_index)
+          @children_cache[source] = [field_index, resolved]
+          resolved
+        end
+      end
+
+      # +Filter.wrap+ already validated every nested level, so no re-check here.
+      def resolve_child(hash, source, field_index)
+        sub = hash[source]
+        return None unless sub.is_a?(Hash) && !sub.empty?
+        build(sub, field_index)
+      end
+    end
+  end
+end

data/lib/panko/code_gen/filters/none.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Panko::CodeGen
+  module Filter
+    # Takes the same arguments as +Indexed::Array+ so generated code calls
+    # one shape whether or not filters were given.
+    module None
+      def self.drops?(_index)
+        false
+      end
+
+      def self.child(_source, _field_index)
+        self
+      end
+
+      freeze
+    end
+  end
+end

data/lib/panko/code_gen/generator.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Panko::CodeGen
+  class Generator
+    OUTPUT_MODES = %i[json hash].freeze
+
+    # Sinks are stateless, so one frozen instance per mode serves every emit.
+    SINKS = {
+      json: Generators::JsonSink.new.freeze,
+      hash: Generators::HashSink.new.freeze
+    }.freeze
+
+    def self.sink_for(output)
+      SINKS.fetch(output) do
+        raise ArgumentError, "unknown output mode #{output.inspect}; must be one of #{OUTPUT_MODES.inspect}"
+      end
+    end
+
+    def emit(descriptor, output:, config:)
+      Generators::ClassEmitter.new(self.class.sink_for(output)).emit(descriptor, config)
+    end
+  end
+end

data/lib/panko/code_gen/generators/banner.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Panko::CodeGen
+  module Generators
+    module Banner
+      def self.emit(builder, descriptor, output:, config:)
+        suffix = Compiler::OUTPUT_SUFFIXES.fetch(output)
+        snake = descriptor.name.gsub(/(?<=.)([A-Z])/, '_\1').downcase
+        builder.line "#"
+        builder.line "# Generated by #{GENERATOR_NAME}"
+        builder.line "# Descriptor: #{descriptor.name}"
+        builder.line "# Mode: :#{output}"
+        builder.line "# Config: #{render_config(config)}"
+        builder.line "#"
+        builder.line "# To use:"
+        builder.line %(#   require_relative "#{snake}_#{output}.generated")
+        builder.line "#   #{descriptor.name}_#{suffix}.new(descriptor: descriptor).serialize_one(record)"
+        builder.blank
+      end
+
+      def self.render_config(config)
+        config.to_h.map { |k, v| "#{k}=#{v.inspect}" }.join(", ")
+      end
+      private_class_method :render_config
+    end
+  end
+end

data/lib/panko/code_gen/generators/class_emitter.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Panko::CodeGen
+  module Generators
+    class ClassEmitter
+      def initialize(sink)
+        @sink = sink
+      end
+
+      def emit(descriptor, config)
+        builder = CodeBuilder.new
+        builder.line "# frozen_string_literal: true"
+        builder.blank
+        Banner.emit(builder, descriptor, output: @sink.output, config: config)
+        cyclic_ids = CycleMembership.cyclic_descriptor_ids(descriptor)
+        DescriptorWalk.in_emit_order(descriptor).each_with_index do |desc, i|
+          builder.blank if i > 0
+          emit_class(desc, config, builder, cyclic_ids)
+        end
+        builder.to_s + "\n"
+      end
+
+      # Public so {Generators::Fanout} can write one class per file.
+      def emit_class(descriptor, config, builder, cyclic_ids)
+        field_index = FieldIndex.build(descriptor)
+        builder.line class_line(descriptor)
+        builder.indent do
+          builder.line "#{GeneratedNames.field_index_const} = #{FieldIndex.to_hash_literal(field_index)}.freeze"
+          @sink.emit_class_constants(descriptor, config, builder)
+          builder.blank
+          emit_initialize(descriptor, builder, cyclic_ids)
+          builder.blank
+          @sink.emit_serialize_one(config, builder)
+          builder.blank
+          @sink.emit_serialize_many(config, builder)
+          builder.blank
+          if @sink.output == :json
+            @sink.emit_serialize_to(config, builder)
+            builder.blank
+          end
+          Release.emit(descriptor, builder, cyclic_ids)
+          builder.blank
+          if descriptor.model.nil?
+            RecordAccess::Generic.emit(descriptor, config, field_index, builder, @sink)
+          else
+            RecordAccess::Specialized.emit(descriptor, config, field_index, builder, @sink)
+          end
+          if config.supports_root_key
+            builder.blank
+            emit_validate_root_key(builder)
+          end
+        end
+        builder.line "end"
+      end
+
+      private
+
+      # An anonymous parent class has no name to write into the source, so
+      # it is fetched from the +ANON_PARENTS+ constant instead.
+      def class_line(descriptor)
+        class_name = GeneratedNames.class_name(descriptor, @sink.suffix)
+        if descriptor.parent_class.name
+          "class #{class_name} < #{descriptor.parent_class.name}"
+        else
+          "class #{class_name} < ANON_PARENTS.fetch(#{descriptor.name.inspect})"
+        end
+      end
+
+      # A Descriptor in a recursion cycle registers +self+ in +_construct_cache+
+      # before building its children, so the cycle reuses this instance.
+      def emit_initialize(descriptor, builder, cyclic_ids)
+        cyclic_self = cyclic_ids[descriptor.__id__]
+        signature = cyclic_self ? "def initialize(descriptor:, _construct_cache: {})" : "def initialize(descriptor:)"
+        builder.line signature
+        builder.indent do
+          builder.line "_construct_cache[descriptor.__id__] = self" if cyclic_self
+          descriptor.method_attributes.each_with_index do |method_attribute, index|
+            next if method_attribute.body.is_a?(Symbol)
+            ivar = GeneratedNames.callable_ivar(method_attribute)
+            builder.line "#{ivar} = descriptor.method_attributes[#{index}].body"
+          end
+          descriptor.associations.each_with_index do |assoc, i|
+            if assoc.if
+              builder.line "#{GeneratedNames.if_guard_ivar(assoc)} = descriptor.associations[#{i}].if"
+            end
+            builder.line emit_serializer_assignment(descriptor, assoc, i, cyclic_ids)
+            assoc.variants.each_with_index do |variant, v|
+              builder.line "#{GeneratedNames.variant_serializer_ivar(assoc, v)} = " \
+                "#{GeneratedNames.class_name(variant, @sink.suffix)}.new(descriptor: descriptor.associations[#{i}].variants[#{v}])"
+            end
+          end
+        end
+        builder.line "end"
+      end
+
+      # The cache is passed only when both ends are cyclic: a child outside
+      # the cycle has a constructor without the +_construct_cache:+ kwarg.
+      def emit_serializer_assignment(descriptor, assoc, i, cyclic_ids)
+        ivar = GeneratedNames.serializer_ivar(assoc)
+        if assoc.descriptor.equal?(descriptor)
+          "#{ivar} = self"
+        elsif cyclic_ids[descriptor.__id__] && cyclic_ids[assoc.descriptor.__id__]
+          "#{ivar} = (_construct_cache[descriptor.associations[#{i}].descriptor.__id__] ||= " \
+            "#{GeneratedNames.class_name(assoc.descriptor, @sink.suffix)}.new(descriptor: descriptor.associations[#{i}].descriptor, _construct_cache: _construct_cache))"
+        else
+          "#{ivar} = #{GeneratedNames.class_name(assoc.descriptor, @sink.suffix)}.new(descriptor: descriptor.associations[#{i}].descriptor)"
+        end
+      end
+
+      def emit_validate_root_key(builder)
+        builder.line "private def validate_root_key!(root_key)"
+        builder.indent do
+          builder.line "return if root_key.nil? || (root_key.is_a?(String) && !root_key.empty?)"
+          builder.line %(raise ArgumentError, "root_key: must be a non-empty String, got \#{root_key.inspect}")
+        end
+        builder.line "end"
+      end
+    end
+  end
+end

data/lib/panko/code_gen/generators/cycle_membership.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Panko::CodeGen
+  module Generators
+    # Only cycles of two or more need +_construct_cache:+; a self-loop uses +@<name>_serializer = self+.
+    # Tarjan's SCC: a DFS that skips finished nodes misses Y in A -> X -> A plus A -> Y -> X -> A.
+    module CycleMembership
+      module_function
+
+      def cyclic_descriptor_ids(root)
+        cyclic = {}
+        index = {}
+        lowlink = {}
+        on_stack = {}
+        scc_stack = []
+        next_index = [0]
+        strongconnect(root, cyclic, index, lowlink, on_stack, scc_stack, next_index)
+        cyclic
+      end
+
+      # +next_index+ is a one-element Array so recursive calls share the counter.
+      def strongconnect(v, cyclic, index, lowlink, on_stack, scc_stack, next_index)
+        vid = v.__id__
+        index[vid] = next_index[0]
+        lowlink[vid] = next_index[0]
+        next_index[0] += 1
+        scc_stack.push(v)
+        on_stack[vid] = true
+
+        v.associations.flat_map(&:descriptors).each do |w|
+          next if w.equal?(v)
+          wid = w.__id__
+          if !index.key?(wid)
+            strongconnect(w, cyclic, index, lowlink, on_stack, scc_stack, next_index)
+            lowlink[vid] = lowlink[wid] if lowlink[wid] < lowlink[vid]
+          elsif on_stack[wid]
+            lowlink[vid] = index[wid] if index[wid] < lowlink[vid]
+          end
+        end
+
+        return unless lowlink[vid] == index[vid]
+        scc = []
+        loop do
+          w = scc_stack.pop
+          on_stack.delete(w.__id__)
+          scc << w
+          break if w.equal?(v)
+        end
+        scc.each { |w| cyclic[w.__id__] = true } if scc.size > 1
+      end
+    end
+  end
+end

data/lib/panko/code_gen/generators/descriptor_walk.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Panko::CodeGen
+  module Generators
+    module DescriptorWalk
+      module_function
+
+      def in_emit_order(root)
+        order = []
+        visit(root, order, {})
+        order
+      end
+
+      def visit(descriptor, order, seen)
+        return if seen[descriptor.__id__]
+        seen[descriptor.__id__] = true
+        descriptor.associations.each { |assoc| assoc.descriptors.each { |child| visit(child, order, seen) } }
+        order << descriptor
+      end
+    end
+  end
+end