clone_kit 0.4.1 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA256:
-  metadata.gz: 44c1a6651a51d141af62a548478d3434d1ade17975090d3cd0a3c574c774fa0a
-  data.tar.gz: 8ac5a6548b0612eca38f70cc915c65f6fcbb3f74fd52e4ce1fe69fc244fe0de7
+SHA1:
+  metadata.gz: c6c302894250fb88b745cb86ae6d329c24c8f601
+  data.tar.gz: 691b3d3bbcff0db46980266e8818a644da0f8626
 SHA512:
-  metadata.gz: 3b0869c41f2031c89c9703d10a32f18e53bde40781d17ee90316706419e3826164bd475888a4906365c4f13feb5815a32b95b6f207adaa7a85d7e85526c9c04d
-  data.tar.gz: d534b0614f37999c26607c3e4a3b5c6e015e69442d609a7c6af690e7904237cdccf1a30eb4875ce8dd8db441ae24daa14b1048a340158010ac5fb69419823a2b
+  metadata.gz: 6442ecee0507caa2d84382a296272f955340aac5e16837183e0c9f4adf8513b535afbf5384a87fe905bcc1c0c467973fce81f5ac5ae207c185805d696a91e5ee
+  data.tar.gz: b38a06f98cf9b42a0005a7cc6b5a0cbd3d0ec7113b2d207e2508acfa9cb64786b2b148abfdb4392b1325090179402f22d59621be1e213e7b58d6ae19012c2049

data/.circleci/config.yml

@@ -0,0 +1,49 @@
+version: 2
+
+jobs:
+  build:
+    docker:
+      - image: kapost/ruby:2.3.1-node-6.11.5
+        environment:
+          DATABASE_URL: "postgres://circleci@localhost/clone_kit_test"
+      - image: circleci/postgres:9.6-alpine
+        environment:
+          POSTGRES_USER: circleci
+          POSTGRES_DB: clone_kit_test
+      - image: kapost/mongo:3.2
+
+    working_directory: ~/clone_kit
+
+    steps:
+      - checkout
+      - run:
+          name: Install deps
+          command: |
+            apt-get update
+            apt-get -y install netcat
+      - restore_cache:
+          keys:
+            - bundle-v1-{{ arch }}-{{ .Branch }}-{{ checksum "clone_kit.gemspec" }}
+            - bundle-v1-{{ arch }}-{{ .Branch }}
+            - bundle-v1-{{ arch }}
+      - run:
+          name: Bundle Install
+          command: |
+            bundle check --path=vendor/bundle || bundle install --path=vendor/bundle --jobs=4 --retry=3
+      - save_cache:
+          key: bundle-v1-{{ arch }}-{{ .Branch }}-{{ checksum "clone_kit.gemspec" }}
+          paths:
+            - vendor/bundle
+      - run:
+          name: Wait for mongo
+          command: ./.circleci/wait_for_mongo.sh
+      - run:
+          name: Run Specs
+          command: |
+            bundle exec rspec --profile 10 \
+                              --format RspecJunitFormatter \
+                              --out test_results/rspec.xml \
+                              --format progress \
+                              $(circleci tests glob "spec/**/*_spec.rb" | circleci tests split --split-by=timings)
+      - store_test_results:
+          path: test_results

data/.circleci/wait_for_mongo.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+
+until nc -z localhost 27017
+do
+    sleep 1
+done

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
+and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+
+## [0.4.2](https://github.com/kapost/clone_kit/compare/v0.4.1...v0.4.2) - 2018-11-14
+### Added
+- CHANGELOG
+- Validation errors on embedded models when cloning

data/README.md

@@ -26,31 +26,118 @@ You can specify the dependency order of cloning, the scope of the operation, and
 
 ```ruby
 CloneKit::Specification.new(BlogPost) do |spec|
-spec.dependencies = %w(Account BlogType)                     # Helps derive the cloning order
-  spec.emitter = TenantEmitter.new(BlogPost)                 # The scope of the operation for this collection
-  spec.cloner = CloneKit::Cloners::MongoidRulesetCloner.new( # The cloning behavior
-    BlogPost,
-    rules: [
-      ReTenantRule.new,
-      CloneKit::Rules::Remap.new("BlogPost", "Account" => "account_id", "BlogType" => "blog_type_id")
-    ]
-  )
+  spec.dependencies = %w(Account BlogType)                     # Helps derive the cloning order
+    spec.emitter = TenantEmitter.new(BlogPost)                 # The scope of the operation for this collection
+    spec.cloner = CloneKit::Cloners::MongoidRulesetCloner.new( # The cloning behavior
+      BlogPost,
+      rules: [
+        ReTenantRule.new,
+        CloneKit::Rules::Remap.new("BlogPost", "Account" => "account_id", "BlogType" => "blog_type_id")
+      ]
+    )
+    spec.after_operation do |operation|
+      ...
+    end
 end
 ```
 
 ## Writing an Emitter
 
-You have to write some emitters for your app. By default, CloneKit specifications utilize and empty emitter, making all clones no-operations.
+By default, CloneKit specifications utilize an empty emitter, making all clones no-ops. Emitters are expected to make db calls using logic defined in the emitter.
 
-TODO
+#### Emitter rules
+  - Emitters must respond to `#emit_all` and `#scope`.
+  - `emit_all` must return an object that responds to `#pluck`.
 
-## Writing a Cloner
+```ruby
+CloneKit::ActiveRecordSpecification.new(BlogPost) do |spec|
+  ...
+  spec.emitter = ActiveRecordEmitter.new(BlogPost)
+  ...
+end
+
+class ActiveRecordEmitter
+  def initialize(klass)
+    self.klass = klass
+  end
+
+  def scope(*)
+    klass.all # add any scope restrictions here
+  end
+
+  def emit_all # the method that will be used to pluck the record ids
+    scope
+  end
+
+  private
+
+  attr_accessor :klass
+end
+```
+
+## Custom Cloners
+
+Cloners are the classes that determine what model class is cloned and how. There are several built-in cloners that can be extended. See `lib/clone_kit/cloners` for a list.
+
+Custom cloners will need to define:
+
+1. The Mongoid or ActiveRecord model class, which will be used to make db calls
+2. Rules, which are executed in the defined order and determine how the ids are mapped from source to destination records. See more in next section.
+3. Merge fields, which allow two records to be merged into one provided all listed fields are equal.
 
-TODO
+Optionally, if you are merging records you will probably want to override the `compare` and `merge` methods with custom logic, though basic logic comes for free.
 
-## Extending the built-in Cloners
+```ruby
+CloneKit::ActiveRecordSpecification.new(self) do |spec|
+  ...
+  spec.cloner = BlogPostCloner.new
+  ...
+end
+
+class BlogPostCloner < ActiveRecordRulesetCloner
+  OMIT_ATTRIBUTES = [:created_at, :updated_at]
+
+  def initialize
+    super(
+      BlogPost,                                           # model class
+      rules: [                                            # rules
+        CloneKit::Rules::Except.new(*OMIT_ATTRIBUTES),
+        CloneKit::Rules::Remap.new(BlogPost)
+      ],
+      merge_fields: [])                                   # merge fields
+  end
+
+  def compare(first, second)
+    # returns a boolean to determine if two records are mergeable
+  end
+
+  def merge(records)
+    # returns a single record that is the merged result
+    # of all argument `records`,
+    # e.g. [{ a: 1, b: 1 }, { a: 2, b: 1}] => { a: 2, b: 1 }
+  end
+end
+
+```
+
+## Writing a Cloner rule
 
-TODO
+Rules respond to a single `#fix` method. `#fix` mutates a record's attributes, allowing the same `attributes` object to be passed down a pipeline of rules.
+
+```ruby
+# given the following rules
+rules: [
+  CloneKit::Rules::Except.new(:title),
+  CloneKit::Rules::Remap.new(BlogPost, "Author" => "author_id" )
+]
+
+# a blog post's attributes will be changed
+{ title: "Title", content: "Content", author_id: 5 }
+{ content: "Content", author_id: 5 } # CloneKit::Rules::Except
+{ content: "Content", author_id: 6 } # CloneKit::Rules::Remap
+```
+
+See `lib/clone_kit/rules` for examples with documentation.
 
 ## Installation
 
@@ -62,11 +149,15 @@ gem 'clone_kit'
 
 And then execute:
 
-    $ bundle
+```bash
+$ bundle
+```
 
 Or install it yourself as:
 
-    $ gem install clone_kit
+```bash
+$ gem install clone_kit
+```
 
 ## Development
 
@@ -76,4 +167,4 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/clone_kit.
+Bug reports and pull requests are welcome on GitHub at https://github.com/kapost/clone_kit.

data/clone_kit.gemspec

@@ -36,6 +36,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "pry-byebug"
   spec.add_development_dependency "rake", "~> 11.0"
   spec.add_development_dependency "rspec-collection_matchers"
+  spec.add_development_dependency "rspec_junit_formatter", "~> 0.3"
   spec.add_development_dependency "rspec-rails", "~> 3.4"
   spec.add_development_dependency "rubocop"
   spec.add_development_dependency "simplecov", "~> 0.12.0"

data/lib/clone_kit/cloners/mongoid_ruleset_cloner.rb

@@ -107,12 +107,42 @@ module CloneKit
         if model_that_we_wont_save.valid?
           model_klass.collection.insert(attributes)
         else
-          details = model_that_we_wont_save.errors.full_messages.to_sentence
-          id = attributes["_id"]
-          current_operation.error("#{model_klass} #{id} failed model validation and was not cloned: #{details}")
+          report_errors(attributes, model_that_we_wont_save)
         end
       end
 
+      def report_errors(attributes, model)
+        model_error = model.errors.full_messages.to_sentence
+        embedded_errors = collect_embedded_errors(model)
+        id = attributes["_id"]
+
+        current_operation.error("#{model_klass} #{id} failed model validation and was not cloned: #{model_error}")
+
+        embedded_errors.each do |e|
+          current_operation.error("[#{model_klass} #{id}]: #{e}")
+        end
+      end
+
+      def collect_embedded_errors(model)
+        embedded_documents(model).each_with_object([]) do |doc, accum|
+          next if doc.blank? || doc.valid?
+
+          klass = doc.class
+          id = doc._id.to_s
+          error = doc.errors.full_messages.to_sentence
+
+          accum << "Embedded #{klass} #{id} failed model validation: #{error}"
+        end
+      end
+
+      def embedded_documents(model)
+        model.associations
+             .select { |_key, assoc| assoc.embedded? }
+             .keys
+             .map { |field| model.send(field) }
+             .flatten
+      end
+
       def each_existing_record(ids)
         ids.each do |id|
           record = model_klass.collection.find(_id: id).one

data/lib/clone_kit/rules/allow_only_mongoid_fields.rb

@@ -2,8 +2,10 @@
 
 module CloneKit
   module Rules
-    # The purpose of this rule is to only include attributes that are presently defined on the model
-    # (and its embedded models)
+    #
+    # The purpose of this rule is to only include attributes that are
+    # presently defined on the model (and its embedded models)
+
     class AllowOnlyMongoidFields < CloneKit::Rule
       def initialize(model_klass)
         self.model_klass = model_klass

data/lib/clone_kit/rules/except.rb

@@ -2,20 +2,23 @@
 
 module CloneKit
   module Rules
+    #
+    # Removes attributes defined by an array of keys
+
     class Except < CloneKit::Rule
-      def initialize(*attributes)
-        self.except_attributes = attributes
+      def initialize(*excepted_attributes)
+        self.excepted_attributes = excepted_attributes
       end
 
       def fix(_old_id, attributes)
-        except_attributes.each do |key|
+        excepted_attributes.each do |key|
           attributes.delete(key)
         end
       end
 
       private
 
-      attr_accessor :except_attributes
+      attr_accessor :excepted_attributes
     end
   end
 end

data/lib/clone_kit/rules/remap.rb

@@ -2,6 +2,21 @@
 
 module CloneKit
   module Rules
+    #
+    # Utilizes the SharedIdMap stored in Redis to remap original
+    # ids to their new cloned values.
+    #
+    #   Given an original blog post being cloned:
+    #     { title: "Title", author_id: 5 }
+    #   And a blog post rule:
+    #     Remap.new(BlogPost, "Author" => "author_id")
+    #   And an author record that was cloned from => to:
+    #     { id: 5, name: "Pat" } => { id: 6, name: "Pat" }
+    #   The cloned blog post will show the remapped author id:
+    #     { title: "Title", author_id: 6 }
+    #
+    # When a remapped id is missing, an error is added to the operation.
+
     class Remap < CloneKit::Rule
       def initialize(model_name, remap_hash = {}, id_generator: nil)
         super(id_generator: id_generator)

data/lib/clone_kit/rules/safe_remap.rb

@@ -4,6 +4,10 @@ require "clone_kit/rules/remap"
 
 module CloneKit
   module Rules
+    #
+    # Operates like Remap, but returns a default value instead of `nil`.
+    # When the default is used, the event outlet receives a #warn message.
+
     class SafeRemap < Remap
       def initialize(model_name, remap_hash = {}, safe_value = nil, id_generator: nil)
         super(model_name, remap_hash, id_generator: id_generator)

data/lib/clone_kit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CloneKit
-  VERSION = "0.4.1"
+  VERSION = "0.4.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: clone_kit
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.4.2
 platform: ruby
 authors:
 - Brandon Croft
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-04-27 00:00:00.000000000 Z
+date: 2018-11-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -192,6 +192,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec_junit_formatter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
 - !ruby/object:Gem::Dependency
   name: rspec-rails
   requirement: !ruby/object:Gem::Requirement
@@ -241,11 +255,14 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".circleci/config.yml"
+- ".circleci/wait_for_mongo.sh"
 - ".gitignore"
 - ".rspec"
 - ".rubocop.kapost.yml"
 - ".rubocop.yml"
 - ".ruby-version"
+- CHANGELOG.md
 - Gemfile
 - README.md
 - Rakefile
@@ -297,7 +314,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.7.6
+rubygems_version: 2.5.2.2
 signing_key: 
 specification_version: 4
 summary: A toolkit to assist in complex cloning operations