yaml_exporter 0.1.0 → 0.2.0

data/lib/yaml_exporter/nodes/many_find_by.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module YamlExporter
+  module Nodes
+    # `many :assoc, find_by: :column do ... end` — identity is the find_by
+    # column value. Existing rows are matched by key; duplicates in the
+    # incoming YAML raise DuplicateKeyError.
+    class ManyFindBy < ManyBase
+      def find_or_build_child(parent, entry, _index, existing:)
+        key = entry[@find_by.to_s]
+        match = existing.find { |c| c.public_send(@find_by) == key }
+        return match if match
+
+        build_child(parent).tap do |child|
+          child.public_send("#{@find_by}=", key)
+        end
+      end
+
+      def default_export_order(records)
+        records.sort_by { |r| r.public_send(@find_by).to_s }
+      end
+
+      def extra_entry_keys
+        [@find_by.to_s]
+      end
+
+      # `extra_entry_schema` is inherited from ManyBase — entry_class here is
+      # the target class, which is exactly where @find_by lives, so the
+      # default TypeInference lookup produces the right type.
+
+      # Re-emit the find_by column first in each entry so round-trips stay
+      # stable (and readers see the discriminator up top).
+      def export(parent, exporter:)
+        records = sort_for_export(Array(parent.public_send(@name)))
+        list = records.map do |child|
+          hash = { @find_by.to_s => child.public_send(@find_by) }
+          hash.merge!(exporter.build_hash(child, @sub_structure))
+          hash
+        end
+        [@name.to_s, list]
+      end
+
+      private
+
+      # Guarantees duplicates-in-YAML fail loudly instead of silently
+      # overwriting each other by index.
+      def reject_duplicates!(entries, path)
+        seen = {}
+        entries.each_with_index do |entry, index|
+          key = entry[@find_by.to_s]
+          if seen.key?(key)
+            raise DuplicateKeyError,
+                  "#{list_path(path)}: duplicate #{@find_by} #{key.inspect} " \
+                  "(entries at index #{seen[key]} and #{index})"
+          end
+          seen[key] = index
+        end
+      end
+
+      public
+
+      # Wrap the shared import to insert duplicate detection up front.
+      def import(parent, data, path:, importer:)
+        entries = data.key?(@name.to_s) ? data[@name.to_s] : nil
+        reject_duplicates!(entries, path) if entries.is_a?(Array)
+        super
+      end
+    end
+  end
+end

data/lib/yaml_exporter/nodes/many_positional.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module YamlExporter
+  module Nodes
+    # `many :assoc do ... end` — identity is positional (array index). The
+    # documented footgun: reordering the YAML list rewrites existing rows
+    # in place by index instead of swapping ids.
+    class ManyPositional < ManyBase
+      def find_or_build_child(parent, _entry, index, existing:)
+        existing[index] || build_child(parent)
+      end
+    end
+  end
+end

data/lib/yaml_exporter/nodes/many_reference.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module YamlExporter
+  module Nodes
+    # `many :assoc, find_by: :column` — standalone reference list (HABTM or
+    # has_many). No block, no entry attributes: each YAML string resolves to
+    # an existing target record via `find_by`. Target records are never
+    # created or mutated; only the association is updated.
+    #
+    # Phase: :post_save (join rows / FK need parent.id).
+    class ManyReference
+      attr_reader :name, :owner_class, :find_by
+
+      def initialize(name:, owner_class:, find_by:)
+        @name = name.to_sym
+        @owner_class = owner_class
+        @find_by = find_by.to_sym
+        reflection = owner_class.reflect_on_association(@name)
+        unless reflection
+          raise ArgumentError,
+                "`many #{name.inspect}`: #{owner_class} has no association `#{name}`"
+        end
+      end
+
+      def phase
+        :post_save
+      end
+
+      def yaml_keys
+        [@name.to_s]
+      end
+
+      def target_class
+        @target_class ||= @owner_class.reflect_on_association(@name).klass
+      end
+
+      def import(record, data, path:, importer:)
+        raw = data.key?(@name.to_s) ? data[@name.to_s] : nil
+        values = Array(raw)
+
+        unless values.all? { |v| v.is_a?(String) || v.is_a?(Symbol) || v.is_a?(Numeric) }
+          raise UnknownAttributeError,
+                "#{describe_path(path)}: expected a list of #{@find_by} values, got #{raw.inspect}"
+        end
+
+        targets = values.map do |value|
+          target_class.find_by(@find_by => value) ||
+            (raise ActiveRecord::RecordNotFound,
+                   "no #{target_class} with #{@find_by}=#{value.inspect}")
+        end
+
+        record.public_send("#{@name}=", targets)
+      end
+
+      def export(record, exporter:)
+        targets = Array(record.public_send(@name))
+        keys = targets.map { |t| t.public_send(@find_by) }.sort
+        [@name.to_s, keys]
+      end
+
+      def schema_fragment
+        item_type = TypeInference.schema_type_for(target_class, @find_by)
+        { @name => { type: 'array', items: { type: item_type } } }
+      end
+
+      private
+
+      def describe_path(path)
+        path.empty? ? @name.to_s : "#{path}.#{@name}"
+      end
+    end
+  end
+end

data/lib/yaml_exporter/nodes/many_through.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module YamlExporter
+  module Nodes
+    # `many :assoc, through: :join, find_by: :column do ... end`.
+    #
+    # With a block, its attributes (and any positioned_by column) attach to
+    # the JOIN row, not the target record. find_by resolves the target
+    # globally.
+    #
+    # With NO block at all the association is a bare reference list: each
+    # entry is just the target's find_by value (a string), exactly like
+    # ManyReference, but routed through a join model. The join rows are still
+    # created/destroyed by the DSL, and positioned_by: — when given — derives
+    # the join's position column from the YAML order. An *empty* block is NOT
+    # the reference flavor: passing a block (empty or not) opts into the
+    # hash-shaped entries, same as the other `many` flavors.
+    class ManyThrough < ManyBase
+      attr_reader :through
+
+      def initialize(name:, owner_class:, through:, find_by:, positioned_by: nil, &block)
+        # Whether a block was passed (even an empty one) decides the YAML
+        # shape: block → hash entries, no block → bare reference list.
+        @reference_list = block.nil?
+        block ||= proc {}
+
+        @through = through.to_sym
+        join_reflection = owner_class.reflect_on_association(@through)
+        unless join_reflection
+          raise ArgumentError,
+                "`many #{name.inspect}`: #{owner_class} has no join association `#{through}`"
+        end
+
+        super(name: name, owner_class: owner_class, find_by: find_by,
+              positioned_by: positioned_by, &block)
+      end
+
+      # No block was passed → the YAML is a flat list of find_by values
+      # rather than a list of hashes. Mirrors ManyReference, but join rows
+      # (and their positioned_by column) are still managed by the DSL.
+      def reference_list?
+        @reference_list
+      end
+
+      def join_class
+        @join_class ||= @owner_class.reflect_on_association(@through).klass
+      end
+
+      # Block attributes live on the join row.
+      def entry_class
+        join_class
+      end
+
+      # Existing "children" for destroy-missing bookkeeping are the join
+      # rows, not the targets: removing a reviewer must drop the join row,
+      # never the Reviewer itself. Order follows the through association's
+      # default scope (matching is by source-association object, not index,
+      # so order doesn't affect correctness here).
+      def current_entries(parent)
+        parent.association(@through).reset
+        parent.public_send(@through).to_a
+      end
+
+      def find_or_build_child(parent, entry, _index, existing:)
+        key = entry[@find_by.to_s]
+        target = target_class.find_by(@find_by => key)
+        unless target
+          raise ActiveRecord::RecordNotFound,
+                "no #{target_class} with #{@find_by}=#{key.inspect}"
+        end
+
+        # Match existing join rows by comparing the source association
+        # object (AR `==` compares primary keys internally, so this works
+        # for surrogate ids and composite PKs alike — no `target.id` needed).
+        assoc = source_association_name
+        match = existing.find { |join| join.public_send(assoc) == target }
+        return match if match
+
+        # `parent.<through>.build` sets the through-side FK for us (respects
+        # `association_primary_key`); then we assign the target via its own
+        # association setter rather than poking `*_id` columns.
+        parent.public_send(@through).build.tap do |join|
+          join.public_send("#{assoc}=", target)
+        end
+      end
+
+      def default_export_order(records)
+        records.sort_by do |join|
+          target = join.public_send(source_association_name)
+          target.public_send(@find_by).to_s
+        end
+      end
+
+      # The collection the Exporter should walk is the join rows, since
+      # block attributes belong to those.
+      def export(parent, exporter:)
+        records = sort_for_export(Array(parent.public_send(@through)))
+        if reference_list?
+          keys = records.map { |join| join.public_send(source_association_name).public_send(@find_by) }
+          return [@name.to_s, keys]
+        end
+
+        list = records.map do |join|
+          target = join.public_send(source_association_name)
+          hash = { @find_by.to_s => target.public_send(@find_by) }
+          hash.merge!(exporter.build_hash(join, @sub_structure))
+          hash
+        end
+        [@name.to_s, list]
+      end
+
+      # Bare reference-list import: entries are find_by values, not hashes.
+      # The block-driven flow in ManyBase#import only applies when there are
+      # block attributes to write onto the join row.
+      def import(parent, data, path:, importer:)
+        return super unless reference_list?
+
+        raw = data.key?(@name.to_s) ? data[@name.to_s] : nil
+        values = raw.nil? ? [] : raw
+
+        unless values.is_a?(Array)
+          raise UnknownAttributeError,
+                "#{list_path(path)}: expected a list, got #{values.class}"
+        end
+        unless values.all? { |v| v.is_a?(String) || v.is_a?(Symbol) || v.is_a?(Numeric) }
+          raise UnknownAttributeError,
+                "#{list_path(path)}: expected a list of #{@find_by} values, got #{raw.inspect}"
+        end
+
+        parent.association(@through).reset
+        existing = current_entries(parent)
+        kept = Set.new.compare_by_identity
+
+        values.each_with_index do |value, index|
+          join = find_or_build_child(parent, { @find_by.to_s => value }, index, existing: existing)
+          # positioned_by is DSL-owned: derived from the 1-based array index,
+          # mirroring ManyBase#import.
+          join.public_send("#{@positioned_by}=", index + 1) if @positioned_by
+          join.save!
+          kept << join
+        end
+
+        destroy_missing(existing, kept)
+      end
+
+      def extra_entry_keys
+        [@find_by.to_s]
+      end
+
+      # find_by is a column on the *target* (e.g. Reviewer.slug), not on the
+      # join row — so resolve the type against target_class.
+      def extra_entry_schema
+        { @find_by => { type: TypeInference.schema_type_for(target_class, @find_by) } }
+      end
+
+      # A bare reference list is a flat array of find_by values; the
+      # block-driven object-array schema from ManyBase doesn't apply.
+      def schema_fragment
+        return super unless reference_list?
+
+        item_type = TypeInference.schema_type_for(target_class, @find_by)
+        { @name => { type: 'array', items: { type: item_type } } }
+      end
+
+      private
+
+      def source_reflection
+        @source_reflection ||= @owner_class.reflect_on_association(@name).source_reflection
+      end
+
+      def source_association_name
+        source_reflection.name
+      end
+    end
+  end
+end

data/lib/yaml_exporter/nodes/one_owned.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module YamlExporter
+  module Nodes
+    # `one :assoc do ... end` — owned has_one child. The current record owns
+    # the child row; missing/null in YAML means "destroy the child".
+    #
+    # Phase: :post_save (the child carries `parent_id`, so parent must be
+    # persisted first).
+    class OneOwned
+      attr_reader :name, :owner_class, :sub_structure
+
+      def initialize(name:, owner_class:, &block)
+        raise ArgumentError, "`one #{name.inspect}`: block required" unless block
+
+        @name = name.to_sym
+        @owner_class = owner_class
+        reflection = owner_class.reflect_on_association(@name)
+        unless reflection
+          raise ArgumentError,
+                "`one #{name.inspect}`: #{owner_class} has no association `#{name}`"
+        end
+
+        @sub_structure = Builder.new(-> { target_class }, &block).build
+      end
+
+      def phase
+        :post_save
+      end
+
+      def yaml_keys
+        [@name.to_s]
+      end
+
+      def target_class
+        @target_class ||= @owner_class.reflect_on_association(@name).klass
+      end
+
+      def import(record, data, path:, importer:)
+        child_data = data.key?(@name.to_s) ? data[@name.to_s] : nil
+
+        if child_data.nil?
+          destroy_existing(record)
+          return
+        end
+
+        child = find_or_build_child(record)
+        importer.apply(child, @sub_structure, child_data, path: child_path(path))
+        cache_target(record, child)
+      end
+
+      def export(record, exporter:)
+        child = record.public_send(@name)
+        return [@name.to_s, nil] if child.nil?
+
+        [@name.to_s, exporter.build_hash(child, @sub_structure)]
+      end
+
+      def schema_fragment
+        { @name => Schema.generate(@sub_structure) }
+      end
+
+      private
+
+      def find_or_build_child(parent)
+        # Don't trust the in-memory association cache — we may have been
+        # re-imported into a parent whose assoc target is stale.
+        parent.association(@name).reset
+        existing = parent.public_send(@name)
+        return existing if existing
+
+        # `build_<assoc>` sets the FK via AR's reflection, which consults
+        # `association_primary_key` — PK-agnostic (works for composite /
+        # custom primary keys and polymorphic `*_type` columns).
+        parent.public_send("build_#{@name}")
+      end
+
+      def destroy_existing(parent)
+        parent.association(@name).reset
+        existing = parent.public_send(@name)
+        existing&.destroy!
+        cache_target(parent, nil)
+      end
+
+      def cache_target(parent, target)
+        assoc = parent.association(@name)
+        assoc.target = target
+        assoc.loaded!
+      end
+
+      def child_path(parent_path)
+        parent_path.empty? ? @name.to_s : "#{parent_path}.#{@name}"
+      end
+    end
+  end
+end

data/lib/yaml_exporter/nodes/one_reference.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module YamlExporter
+  module Nodes
+    # `one :assoc, find_by: :column` — belongs_to reference. The FK column
+    # lives on the current record; the target is externally managed.
+    #
+    # Phase: :pre_save (sets the FK column on `record` before `record.save!`).
+    class OneReference
+      attr_reader :name, :owner_class, :find_by
+
+      def initialize(name:, owner_class:, find_by:)
+        @name = name.to_sym
+        @owner_class = owner_class
+        @find_by = find_by.to_sym
+        reflection = owner_class.reflect_on_association(@name)
+        unless reflection
+          raise ArgumentError,
+                "`one #{name.inspect}`: #{owner_class} has no association `#{name}`"
+        end
+      end
+
+      def phase
+        :pre_save
+      end
+
+      def yaml_keys
+        [@name.to_s]
+      end
+
+      def target_class
+        @target_class ||= @owner_class.reflect_on_association(@name).klass
+      end
+
+      # Assign via the association setter (not the raw FK column) so that:
+      #   - Rails uses the target's `association_primary_key`, not a hardcoded
+      #     :id (composite/custom primary keys keep working).
+      #   - The in-memory association cache on `record` is updated, so a
+      #     subsequent `record.publisher` returns the freshly-assigned target
+      #     instead of a stale one.
+      #   - Polymorphic `*_type` columns would be set too, if we ever grow
+      #     that feature.
+      def import(record, data, path:, importer:)
+        value = data.key?(@name.to_s) ? data[@name.to_s] : nil
+
+        if value.nil?
+          record.public_send("#{@name}=", nil)
+          return
+        end
+
+        target = target_class.find_by(@find_by => value)
+        unless target
+          raise ActiveRecord::RecordNotFound,
+                "no #{target_class} with #{@find_by}=#{value.inspect}"
+        end
+
+        record.public_send("#{@name}=", target)
+      end
+
+      def export(record, exporter:)
+        target = record.public_send(@name)
+        return [@name.to_s, nil] if target.nil?
+
+        [@name.to_s, target.public_send(@find_by)]
+      end
+
+      def schema_fragment
+        { @name => { type: TypeInference.schema_type_for(target_class, @find_by) } }
+      end
+    end
+  end
+end

data/lib/yaml_exporter/nodes/one_reference_of.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module YamlExporter
+  module Nodes
+    # `one :assoc, find_by: :col, of: :nested_assoc`
+    #
+    # Identifies the target record indirectly: the YAML value is looked up on
+    # a related model (`of:`) rather than on the target itself.
+    #
+    # Example: Book `belongs_to :responsible_editor` (CorporateUser), and
+    # CorporateUser `belongs_to :user` (User with a slug). Declaring
+    #   `one :responsible_editor, find_by: :slug, of: :user`
+    # stores the User's slug in the YAML and resolves the CorporateUser on
+    # import by reversing the FK.
+    #
+    # Only 1:[0,1] `of:` associations are permitted (belongs_to or has_one).
+    # Phase: :pre_save (sets the FK before record.save!).
+    class OneReferenceOf
+      attr_reader :name, :owner_class, :find_by, :of
+
+      def initialize(name:, owner_class:, find_by:, of:)
+        @name = name.to_sym
+        @owner_class = owner_class
+        @find_by = find_by.to_sym
+        @of = of.to_sym
+
+        reflection = owner_class.reflect_on_association(@name)
+        unless reflection
+          raise ArgumentError,
+                "`one #{name.inspect}`: #{owner_class} has no association `#{name}`"
+        end
+
+        of_ref = target_class.reflect_on_association(@of)
+        unless of_ref
+          raise ArgumentError,
+                "`one #{name.inspect}, of: #{of.inspect}`: #{target_class} has no association `#{of}`"
+        end
+
+        unless singular_association?(of_ref)
+          raise ArgumentError,
+                "`one #{name.inspect}, of: #{of.inspect}`: `of:` must be a 1:[0,1] association " \
+                "(belongs_to or has_one); got #{of_ref.macro}"
+        end
+      end
+
+      def phase
+        :pre_save
+      end
+
+      def yaml_keys
+        [@name.to_s]
+      end
+
+      def target_class
+        @target_class ||= @owner_class.reflect_on_association(@name).klass
+      end
+
+      def import(record, data, path:, importer:)
+        value = data.key?(@name.to_s) ? data[@name.to_s] : nil
+
+        if value.nil?
+          record.public_send("#{@name}=", nil)
+          return
+        end
+
+        through = through_class.find_by(@find_by => value)
+        unless through
+          raise ActiveRecord::RecordNotFound,
+                "no #{through_class} with #{@find_by}=#{value.inspect}"
+        end
+
+        target = find_target_via(through)
+        unless target
+          raise ActiveRecord::RecordNotFound,
+                "no #{target_class} linked to #{through_class} #{@find_by}=#{value.inspect} via `#{@of}`"
+        end
+
+        record.public_send("#{@name}=", target)
+      end
+
+      def export(record, exporter:)
+        target = record.public_send(@name)
+        return [@name.to_s, nil] if target.nil?
+
+        through = target.public_send(@of)
+        return [@name.to_s, nil] if through.nil?
+
+        [@name.to_s, through.public_send(@find_by)]
+      end
+
+      def schema_fragment
+        { @name => { type: TypeInference.schema_type_for(through_class, @find_by) } }
+      end
+
+      private
+
+      def of_reflection
+        @of_reflection ||= target_class.reflect_on_association(@of)
+      end
+
+      def through_class
+        @through_class ||= of_reflection.klass
+      end
+
+      # Navigate from a resolved `through` record back to the target.
+      #
+      # belongs_to (:user on CorporateUser): FK is on the target.
+      #   target_class.find_by(user_id: through.id)
+      #
+      # has_one (:profile on CorporateUser): FK is on the through record.
+      #   target_class.find_by(id: through.corporate_user_id)
+      def find_target_via(through)
+        if of_reflection.is_a?(ActiveRecord::Reflection::BelongsToReflection)
+          pk_val = through.public_send(of_reflection.association_primary_key)
+          target_class.find_by(of_reflection.foreign_key => pk_val)
+        else # has_one
+          fk_val = through.public_send(of_reflection.foreign_key)
+          target_class.find_by(of_reflection.association_primary_key => fk_val)
+        end
+      end
+
+      def singular_association?(reflection)
+        reflection.is_a?(ActiveRecord::Reflection::BelongsToReflection) ||
+          reflection.is_a?(ActiveRecord::Reflection::HasOneReflection)
+      end
+    end
+  end
+end

data/lib/yaml_exporter/schema.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module YamlExporter
+  # Builds a JSON-schema-ish hash describing a structure. Keys are symbols
+  # so callers can use `schema[:properties][:title]` ergonomically.
+  class Schema
+    def self.generate(structure)
+      new(structure).generate
+    end
+
+    def initialize(structure)
+      @structure = structure
+    end
+
+    def generate
+      {
+        type: 'object',
+        properties: @structure.nodes.each_with_object({}) do |node, acc|
+          acc.merge!(node.schema_fragment)
+        end
+      }
+    end
+  end
+end

data/lib/yaml_exporter/structure.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module YamlExporter
+  # Immutable representation of a `yaml_structure do ... end` block.
+  #
+  # * `klass` — the ActiveRecord class this structure is attached to.
+  #   Resolved lazily: the constructor accepts either a class or a callable,
+  #   and defers to first access. This matters for inner structures whose
+  #   class might be resolved via a reflection that isn't safe to compute
+  #   at declaration time (anonymous parent classes, etc.).
+  # * `nodes` — ordered list of node objects. Order matches declaration and
+  #   drives export key order.
+  class Structure
+    attr_reader :nodes
+
+    def initialize(klass:, nodes:)
+      @klass_resolver = klass.respond_to?(:call) ? klass : -> { klass }
+      @nodes = nodes
+    end
+
+    def klass
+      @klass ||= @klass_resolver.call
+    end
+  end
+end