yaml_exporter 0.1.0 → 0.2.0

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.0'
+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,48 @@ 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/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.0
 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,34 @@ 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/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 +123,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 +130,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

data/lib/yaml_serializable/yaml_exporter.rb

@@ -1,196 +0,0 @@
-require 'yaml'
-require 'json-schema'
-
-module YamlSerializable
-  class YamlExporter
-    def self.export(object, structure)
-      new(object, structure).export
-    end
-
-    def self.import(object, yaml_string, structure)
-      new(object, structure).import(yaml_string)
-    end
-
-    def self.generate_schema(klass, structure)
-      new(klass.new, structure).generate_schema
-    end
-
-    def initialize(object, structure)
-      @object = object
-      @structure = structure
-    end
-
-    def export
-      yaml = YAML.dump(build_hash(@structure, @object))
-      validate(yaml)
-      yaml
-    end
-
-    def import(yaml_string)
-      data = YAML.safe_load(yaml_string)
-      validate(yaml_string)
-      update_object(data)
-      @object
-    end
-
-    def generate_schema
-      {
-        type: 'object',
-        properties: generate_properties(@structure, @object.class),
-        required: required_attributes(@structure, @object.class)
-      }
-    end
-
-    private
-
-    def build_hash(structure, object)
-      result = {}
-
-      structure[:attributes].each do |attr|
-        value = object.send(attr)
-        result[attr.to_s] = value unless value.nil?
-      end
-
-      structure[:associations].each do |name, config|
-        if config[:type] == :has_many
-          associated_objects = object.send(name).unscope(:order).order(:id)
-          if associated_objects.any?
-            result[name.to_s] = associated_objects.map { |item| build_hash(config[:structure], item) }
-          end
-        elsif config[:type] == :has_one
-          associated_object = object.send(name)
-          result[name.to_s] = build_hash(config[:structure], associated_object) if associated_object
-        end
-      end
-
-      result.compact
-    end
-
-    def validate(yaml)
-      schema = generate_schema
-      data = YAML.safe_load(yaml)
-      JSON::Validator.validate!(schema, data)
-    rescue JSON::Schema::ValidationError => e
-      raise "Invalid YAML structure: #{e.message}"
-    end
-
-    def update_object(data)
-      @object.transaction do
-        update_attributes(@object, data, @structure[:attributes])
-        @structure[:associations].each do |name, config|
-          if config[:type] == :has_many
-            update_collection(@object, data[name.to_s], name, config[:structure])
-          elsif config[:type] == :has_one && data[name.to_s]
-            update_nested(@object, data[name.to_s], name, config[:structure])
-          end
-        end
-        @object.save!
-      end
-    end
-
-    def update_attributes(object, data, attributes)
-      attributes.each do |attr|
-        if data.key?(attr.to_s)
-          object.send("#{attr}=", data[attr.to_s])
-        else
-          object.send("#{attr}=", nil)
-        end
-      end
-    end
-
-    def update_collection(parent, items_data, association_name, config)
-      existing_items = parent.send(association_name).unscope(:order).order(:id).to_a
-      new_items = []
-
-      items_data&.each_with_index do |item_data, index|
-        item = existing_items[index] || parent.send(association_name).build
-        update_attributes(item, item_data, config[:attributes])
-        config[:associations]&.each do |sub_name, sub_config|
-          if sub_config[:type] == :has_many
-            update_collection(item, item_data[sub_name.to_s], sub_name, sub_config[:structure])
-          elsif sub_config[:type] == :has_one && item_data[sub_name.to_s]
-            update_nested(item, item_data[sub_name.to_s], sub_name, sub_config[:structure])
-          end
-        end
-        new_items << item
-      end
-
-      # Entferne Items, die nicht mehr im YAML vorhanden sind
-      (existing_items - new_items).each(&:mark_for_destruction)
-
-      parent.send("#{association_name}=", new_items)
-    end
-
-    def update_nested(parent, nested_data, association_name, config)
-      nested_object = parent.send(association_name) || parent.send("build_#{association_name}")
-      update_attributes(nested_object, nested_data, config[:attributes])
-      config[:associations]&.each do |sub_name, sub_config|
-        if sub_config[:type] == :has_many
-          update_collection(nested_object, nested_data[sub_name.to_s], sub_name, sub_config[:structure])
-        elsif sub_config[:type] == :has_one && nested_data[sub_name.to_s]
-          update_nested(nested_object, nested_data[sub_name.to_s], sub_name, sub_config[:structure])
-        end
-      end
-    end
-
-    def generate_properties(structure, klass)
-      properties = {}
-
-      structure[:attributes].each do |attr|
-        column = klass.columns_hash[attr.to_s]
-        properties[attr.to_s] = { type: infer_type(column) }
-      end
-
-      structure[:associations].each do |name, config|
-        if config[:type] == :has_many
-          properties[name.to_s] = {
-            type: 'array',
-            items: {
-              type: 'object',
-              properties: generate_properties(config[:structure], association_class(klass, name)),
-              required: required_attributes(config[:structure], association_class(klass, name))
-            }
-          }
-        elsif config[:type] == :has_one
-          properties[name.to_s] = {
-            type: 'object',
-            properties: generate_properties(config[:structure], association_class(klass, name)),
-            required: required_attributes(config[:structure], association_class(klass, name))
-          }
-        end
-      end
-
-      properties
-    end
-
-    def infer_type(column)
-      case column.type
-      when :string, :text
-        'string'
-      when :integer, :bigint
-        'integer'
-      when :float, :decimal
-        'number'
-      when :boolean
-        'boolean'
-      when :date, :datetime, :time
-        'string'
-      when :json, :jsonb
-        'object'
-      else
-        'string'
-      end
-    end
-
-    def association_class(klass, association_name)
-      klass.reflect_on_association(association_name).klass
-    end
-
-    def required_attributes(structure, klass)
-      structure[:attributes].select do |attr|
-        column = klass.columns_hash[attr.to_s]
-        column && !column.null
-      end
-    end
-  end
-end