yaml_exporter 0.1.0 → 0.2.1

data/lib/yaml_exporter/nodes/one_reference_of.rb

@@ -0,0 +1,85 @@
+# 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
+      include OfResolution
+
+      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
+
+        validate_of_reflection!("one #{name.inspect}")
+      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
+
+        related = of_class.find_by(@find_by => value)
+        unless related
+          raise ActiveRecord::RecordNotFound,
+                "no #{of_class} with #{@find_by}=#{value.inspect}"
+        end
+
+        target = find_target_via(related)
+        unless target
+          raise ActiveRecord::RecordNotFound,
+                "no #{target_class} linked to #{of_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?
+
+        [@name.to_s, of_value_for(target)]
+      end
+
+      def schema_fragment
+        { @name => { type: TypeInference.schema_type_for(of_class, @find_by) } }
+      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

data/lib/yaml_exporter/type_inference.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module YamlExporter
+  # Maps an ActiveRecord column type to a JSON-schema primitive.
+  #
+  # Single source of truth used by every node that emits a `type:` entry
+  # in the generated schema (Nodes::Attribute, Nodes::OneReference,
+  # Nodes::ManyReference, and the extra_entry_keys path in Nodes::ManyBase).
+  #
+  # Unknown or un-resolvable columns fall back to 'string' so the schema
+  # always validates as JSON-schema-ish.
+  module TypeInference
+    # AR column type -> JSON-schema primitive. Date/time stay 'string' on
+    # purpose: YAML round-trips them as ISO-8601 strings by default, and we
+    # don't (yet) emit a `format:` facet.
+    COLUMN_TYPE_TO_JSON_SCHEMA = {
+      string:    'string',
+      text:      'string',
+      uuid:      'string',
+      binary:    'string',
+      integer:   'integer',
+      bigint:    'integer',
+      float:     'number',
+      decimal:   'number',
+      boolean:   'boolean',
+      date:      'string',
+      datetime:  'string',
+      time:      'string',
+      timestamp: 'string',
+      json:      'object',
+      jsonb:     'object'
+    }.freeze
+
+    FALLBACK = 'string'
+
+    # Returns the JSON-schema type string for `column_name` on `klass`.
+    # `klass` may be nil (e.g. declaration-time lookup on an anonymous
+    # class whose table doesn't exist yet) — we quietly fall back.
+    def self.schema_type_for(klass, column_name)
+      return FALLBACK unless klass.respond_to?(:columns_hash)
+
+      column = klass.columns_hash[column_name.to_s]
+      return FALLBACK unless column
+
+      COLUMN_TYPE_TO_JSON_SCHEMA[column.type] || FALLBACK
+    rescue ActiveRecord::ActiveRecordError
+      FALLBACK
+    end
+
+    # True when `column_name` on `klass` is a `text` column (as opposed to a
+    # `string`/varchar). Drives whether string values export as YAML literal
+    # block scalars. Unknown/unresolvable columns are treated as non-text.
+    def self.text_column?(klass, column_name)
+      return false unless klass.respond_to?(:columns_hash)
+
+      column = klass.columns_hash[column_name.to_s]
+      return false unless column
+
+      column.type == :text
+    rescue ActiveRecord::ActiveRecordError
+      false
+    end
+  end
+end

data/lib/yaml_exporter/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module YamlExporter
+  VERSION = '0.2.1'
+end

data/lib/yaml_exporter.rb

@@ -1,9 +1,28 @@
 # frozen_string_literal: true
 
-require_relative 'yaml_serializable/structure_builder'
-require_relative 'yaml_serializable/yaml_exporter'
+require 'active_record'
+require 'active_support/core_ext/class/attribute'
 
+require_relative 'yaml_exporter/version'
+
+# Top-level entrypoint: defines the `include YamlExporter` hook and the
+# public API methods (`yaml_structure`, `yaml_schema`, `yaml_import`,
+# `yaml_export`). Parsing, import, export and schema generation live in
+# dedicated classes under `lib/yaml_exporter/`.
 module YamlExporter
+  # Base class for every library-specific error. Inherits from
+  # ActiveRecord::ActiveRecordError so existing `rescue ActiveRecord::ActiveRecordError`
+  # blocks (and the import transaction wrapper) catch it naturally.
+  class Error < ActiveRecord::ActiveRecordError; end
+
+  # Raised when a YAML document carries a key (top-level or inside an entry)
+  # that the corresponding `yaml_structure` scope does not declare.
+  class UnknownAttributeError < Error; end
+
+  # Raised when a `find_by`-identified list contains two entries with the same
+  # key value — e.g. two `slug: chapter-1` entries under one `book_parts:`.
+  class DuplicateKeyError < Error; end
+
   def self.included(base)
     base.extend(ClassMethods)
   end
@@ -11,22 +30,49 @@ module YamlExporter
   module ClassMethods
     def yaml_structure(&block)
       class_attribute :yaml_structure_definition, instance_writer: false
-      self.yaml_structure_definition = YamlSerializable::StructureBuilder.new(&block).build
+      self.yaml_structure_definition = YamlExporter::Builder.new(self, &block).build
       include InstanceMethods
     end
 
     def yaml_schema
-      YamlSerializable::YamlExporter.generate_schema(self, yaml_structure_definition)
+      YamlExporter::Schema.generate(yaml_structure_definition)
     end
   end
 
   module InstanceMethods
-    def yaml_export
-      YamlSerializable::YamlExporter.export(self, self.class.yaml_structure_definition)
+    def yaml_import(yaml_string)
+      YamlExporter::Importer.new(self, self.class.yaml_structure_definition).import(yaml_string)
     end
 
-    def yaml_import(yaml_string)
-      YamlSerializable::YamlExporter.import(self, yaml_string, self.class.yaml_structure_definition)
+    # `omit_nil:` (default true) drops keys whose value is empty — a nil
+    # attribute, a missing `one` reference, an absent owned `one`, or an empty
+    # `many` list. Round-trip safe: import treats a missing key, an explicit
+    # `null`, and an empty list identically. Pass `omit_nil: false` to keep
+    # explicit `null`s in the file (e.g. so optional fields stay discoverable).
+    def yaml_export(omit_nil: true)
+      YamlExporter::Exporter.new(
+        self, self.class.yaml_structure_definition, omit_nil: omit_nil
+      ).to_yaml
     end
   end
 end
+
+require 'set'
+require 'yaml'
+
+require_relative 'yaml_exporter/structure'
+require_relative 'yaml_exporter/type_inference'
+require_relative 'yaml_exporter/nodes/attribute'
+require_relative 'yaml_exporter/nodes/of_resolution'
+require_relative 'yaml_exporter/nodes/one_owned'
+require_relative 'yaml_exporter/nodes/one_reference'
+require_relative 'yaml_exporter/nodes/one_reference_of'
+require_relative 'yaml_exporter/nodes/many_base'
+require_relative 'yaml_exporter/nodes/many_positional'
+require_relative 'yaml_exporter/nodes/many_find_by'
+require_relative 'yaml_exporter/nodes/many_reference'
+require_relative 'yaml_exporter/nodes/many_through'
+require_relative 'yaml_exporter/builder'
+require_relative 'yaml_exporter/importer'
+require_relative 'yaml_exporter/exporter'
+require_relative 'yaml_exporter/schema'

data/script/demo_quiz.rb

@@ -0,0 +1,78 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Runnable demo sharing the same schema and models as the test suite.
+# From the repository root:
+#
+#   ruby script/demo_quiz.rb
+#
+# One-time: gem install sqlite3 && bundle install
+
+require 'bundler/setup'
+require 'active_record'
+require 'json'
+require 'pathname'
+
+root = Pathname.new(__dir__).join('..').expand_path
+$LOAD_PATH.unshift root.join('lib').to_s
+require 'yaml_exporter'
+
+ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: ':memory:')
+ActiveRecord::Base.logger = nil
+
+load root.join('test/support/schema.rb')
+load root.join('test/support/models.rb')
+
+quiz = Quiz.create!(title: 'Ruby Basics', quiz_type: 'multiple_choice')
+
+q1 = quiz.questions.create!(
+  text: 'What is Ruby?',
+  question_type: 'single_choice',
+  feedback: 'Ruby is a dynamic, open-source programming language.'
+)
+q1.answers.create!(text: 'A programming language', is_correct: true, impact: 10)
+q1.answers.create!(text: 'A gemstone', is_correct: false, impact: 0)
+q1.answers.create!(text: 'A color', is_correct: false, impact: 0)
+
+q2 = quiz.questions.create!(
+  text: 'Which keyword defines a method in Ruby?',
+  question_type: 'single_choice',
+  feedback: "Use 'def' to define methods."
+)
+q2.answers.create!(text: 'def', is_correct: true, impact: 10)
+q2.answers.create!(text: 'func', is_correct: false, impact: 0)
+q2.answers.create!(text: 'fn', is_correct: false, impact: 0)
+
+puts '=' * 60
+puts '1) YAML Export'
+puts '=' * 60
+yaml_output = quiz.yaml_export
+puts yaml_output
+
+puts '=' * 60
+puts '2) JSON Schema'
+puts '=' * 60
+schema = Quiz.yaml_schema
+puts JSON.pretty_generate(schema)
+
+puts "\n" + '=' * 60
+puts '3) YAML Import (round-trip into a new Quiz)'
+puts '=' * 60
+
+imported_quiz = Quiz.create!(title: 'placeholder', quiz_type: 'placeholder')
+imported_quiz.yaml_import(yaml_output)
+
+puts "Title:          #{imported_quiz.title}"
+puts "Type:           #{imported_quiz.quiz_type}"
+puts "Questions:      #{imported_quiz.questions.count}"
+imported_quiz.questions.each do |q|
+  puts "  Q: #{q.text}"
+  q.answers.each do |a|
+    marker = a.is_correct ? '✓' : '✗'
+    puts "    #{marker} #{a.text} (impact: #{a.impact || 'n/a'})"
+  end
+end
+
+puts "\n" + '=' * 60
+puts 'Done — all features working!'
+puts '=' * 60

data/yaml_exporter.gemspec

@@ -1,24 +1,21 @@
-require_relative "lib/yaml_serializable/version"
+require_relative "lib/yaml_exporter/version"
 
 Gem::Specification.new do |spec|
   spec.name        = "yaml_exporter"
-  spec.version     = YamlSerializable::VERSION
+  spec.version     = YamlExporter::VERSION
   spec.authors     = ["Anatoly Zelenin"]
   spec.email       = ["anatoly@zelenin.de"]
 
-  spec.summary     = "YAML serialization for ActiveRecord models with JSON schema support"
-  spec.description = "A Ruby gem for YAML serialization and deserialization of ActiveRecord models with JSON schema generation."
+  spec.summary     = "YAML import/export for ActiveRecord models with a small declarative DSL"
+  spec.description = "A Ruby gem that declaratively maps ActiveRecord models to YAML documents (and back) via a compact `attributes` / `one` / `many` DSL."
   spec.homepage    = "https://github.com/itadventurer/yaml_exporter"
   spec.license     = "MIT"
 
-  spec.required_ruby_version = Gem::Requirement.new(">= 2.5.0")
+  spec.required_ruby_version = Gem::Requirement.new(">= 3.2")
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/itadventurer/yaml_exporter"
-  #spec.metadata["changelog_uri"] = "https://github.com/itadventurer/yaml_exporter/blob/master/CHANGELOG.md"
 
-  # Specify which files should be added to the gem when it is released.
-  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
     `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
   end
@@ -27,5 +24,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "activerecord", ">= 5.2"
   spec.add_dependency "activesupport", ">= 5.2"
 
+  spec.add_development_dependency "minitest", "~> 5.0"
   spec.add_development_dependency "rake", "~> 13.0"
-end
+  spec.add_development_dependency "sqlite3", ">= 1.4"
+end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: yaml_exporter
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Anatoly Zelenin
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-08-29 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -38,6 +37,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '5.2'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -52,8 +65,22 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
-description: A Ruby gem for YAML serialization and deserialization of ActiveRecord
-  models with JSON schema generation.
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.4'
+description: A Ruby gem that declaratively maps ActiveRecord models to YAML documents
+  (and back) via a compact `attributes` / `one` / `many` DSL.
 email:
 - anatoly@zelenin.de
 executables: []
@@ -61,14 +88,35 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".github/workflows/gem-push.yml"
+- ".github/workflows/test.yml"
 - ".gitignore"
+- AGENTS.md
+- CHANGELOG.md
 - Gemfile
+- Gemfile.lock
 - LICENSE
 - README.md
+- RELEASING.md
+- Rakefile
 - lib/yaml_exporter.rb
-- lib/yaml_serializable/structure_builder.rb
-- lib/yaml_serializable/version.rb
-- lib/yaml_serializable/yaml_exporter.rb
+- lib/yaml_exporter/builder.rb
+- lib/yaml_exporter/exporter.rb
+- lib/yaml_exporter/importer.rb
+- lib/yaml_exporter/nodes/attribute.rb
+- lib/yaml_exporter/nodes/many_base.rb
+- lib/yaml_exporter/nodes/many_find_by.rb
+- lib/yaml_exporter/nodes/many_positional.rb
+- lib/yaml_exporter/nodes/many_reference.rb
+- lib/yaml_exporter/nodes/many_through.rb
+- lib/yaml_exporter/nodes/of_resolution.rb
+- lib/yaml_exporter/nodes/one_owned.rb
+- lib/yaml_exporter/nodes/one_reference.rb
+- lib/yaml_exporter/nodes/one_reference_of.rb
+- lib/yaml_exporter/schema.rb
+- lib/yaml_exporter/structure.rb
+- lib/yaml_exporter/type_inference.rb
+- lib/yaml_exporter/version.rb
+- script/demo_quiz.rb
 - yaml_exporter.gemspec
 homepage: https://github.com/itadventurer/yaml_exporter
 licenses:
@@ -76,7 +124,6 @@ licenses:
 metadata:
   homepage_uri: https://github.com/itadventurer/yaml_exporter
   source_code_uri: https://github.com/itadventurer/yaml_exporter
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -84,15 +131,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.5.0
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
-signing_key: 
+rubygems_version: 3.6.9
 specification_version: 4
-summary: YAML serialization for ActiveRecord models with JSON schema support
+summary: YAML import/export for ActiveRecord models with a small declarative DSL
 test_files: []

data/lib/yaml_serializable/structure_builder.rb

@@ -1,30 +0,0 @@
-# frozen_string_literal: true
-
-module YamlSerializable
-  class StructureBuilder
-    def initialize(&block)
-      @structure = { attributes: [], associations: {} }
-      instance_eval(&block)
-    end
-
-    def yaml_attribute(*attrs)
-      @structure[:attributes].concat(attrs)
-    end
-
-    def yaml_has_one(name, &block)
-      @structure[:associations][name] = { type: :has_one, structure: self.class.new(&block).build }
-    end
-
-    def yaml_has_many(name, &block)
-      @structure[:associations][name] = { type: :has_many, structure: self.class.new(&block).build }
-    end
-
-    def yaml_condition(&block)
-      @structure[:condition] = block
-    end
-
-    def build
-      @structure
-    end
-  end
-end

data/lib/yaml_serializable/version.rb

@@ -1,3 +0,0 @@
-module YamlSerializable
-  VERSION = "0.1.0"
-end