acts_as_dag 1.2.6 → 2.0.0

data/lib/acts_as_dag/deprecated.rb

@@ -0,0 +1,121 @@
+module ActsAsDAG
+  module Deprecated
+
+    module ClassMethods
+      # Reorganizes the entire class of records based on their name, first resetting the hierarchy, then reoganizing
+      # Can pass a list of categories and only those will be reorganized
+      def reorganize(categories_to_reorganize = self.all)
+        puts "This method is deprecated and will be removed in a future version"
+
+        return if categories_to_reorganize.empty?
+
+        reset_hierarchy(categories_to_reorganize)
+
+        word_count_groups = categories_to_reorganize.group_by{|category| ActsAsDAG::Deprecated::HelperMethods.word_count(category)}.sort
+        roots_categories = word_count_groups.first[1].dup.sort_by(&:name)  # We will build up a list of plinko targets, we start with the group of categories with the shortest word count
+
+        # Now plinko the next shortest word group into those targets
+        # If we can't plinko one, then it gets added as a root
+        word_count_groups[1..-1].each do |word_count, categories|
+          categories_with_no_parents = []
+
+          # Try drop each category into each root
+          categories.sort_by(&:name).each do |category|
+            ActiveRecord::Base.benchmark "Analyze #{category.name}" do
+              suitable_parent = false
+              roots_categories.each do |root|
+                suitable_parent = true if ActsAsDAG::Deprecated::HelperMethods.plinko(root, category)
+              end
+              unless suitable_parent
+                ActiveRecord::Base.logger.info { "Plinko couldn't find a suitable parent for #{category.name}" }
+                categories_with_no_parents << category
+              end
+            end
+          end
+
+          # Add all categories from this group without suitable parents to the roots
+          if categories_with_no_parents.present?
+            ActiveRecord::Base.logger.info { "Adding #{categories_with_no_parents.collect(&:name).join(', ')} to roots" }
+            roots_categories.concat categories_with_no_parents
+          end
+        end
+      end
+    end
+
+    module InstanceMethods
+    end
+
+    module HelperMethods
+      # Searches the subtree for the best parent for the other
+      # i.e. it lets you drop the category in at the top and it drops down the list until it finds its final resting place
+      def self.plinko(current, other)
+        # ActiveRecord::Base.logger.info { "Plinkoing '#{other.name}' into '#{current.name}'..." }
+        if should_descend_from?(current, other)
+          # Find the subtree of the current category that +other+ should descend from
+          subtree_other_should_descend_from = current.subtree.select{|record| should_descend_from?(record, other) }
+          # Of those, find the categories with the most number of matching words and make +other+ their child
+          # We find all suitable candidates to provide support for categories whose names are permutations of each other
+          # e.g. 'goat wool fibre' should be a child of 'goat wool' and 'wool goat' if both are present under 'goat'
+          new_parents_group = subtree_other_should_descend_from.group_by{|category| matching_word_count(other, category)}.sort.reverse.first
+          if new_parents_group.present?
+            for new_parent in new_parents_group[1]
+              ActiveRecord::Base.logger.info { "  '#{other.name}' landed under '#{new_parent.name}'" }
+              other.add_parent(new_parent)
+
+              # We've just affected the associations in ways we can not possibly imagine, so let's clear the association cache
+              current.clear_association_cache
+            end
+            return true
+          end
+        end
+      end
+
+      # Convenience method for plinkoing multiple categories
+      # Plinko's multiple categories from shortest to longest in order to prevent the need for reorganization
+      def self.plinko_multiple(current, others)
+        groups = others.group_by{|category| word_count(category)}.sort
+        groups.each do |word_count, categories|
+          categories.each do |category|
+            unless plinko(current, category)
+            end
+          end
+        end
+      end
+
+      # Returns the portion of this category's name that is not present in any of it's parents
+      def self.unique_name_portion(current)
+        unique_portion = current.name.split
+        for parent in current.parents
+          for word in parent.name.split
+            unique_portion.delete(word)
+          end
+        end
+
+        return unique_portion.empty? ? nil : unique_portion.join(' ')
+      end
+
+      # Checks if other should descend from +current+ based on name matching
+      # Returns true if other contains all the words from +current+, but has words that are not contained in +current+
+      def self.should_descend_from?(current, other)
+        return false if current == other
+
+        other_words = other.name.split
+        current_words = current.name.split
+
+        # (other contains all the words from current and more) && (current contains no words that are not also in other)
+        return (other_words - (current_words & other_words)).count > 0 && (current_words - other_words).count == 0
+      end
+
+      def self.word_count(current)
+        current.name.split.count
+      end
+
+      def self.matching_word_count(current, other)
+        other_words = other.name.split
+        self_words = current.name.split
+        return (other_words & self_words).count
+      end
+
+    end
+  end
+end

data/spec/acts_as_dag_spec.rb

@@ -1,314 +1,838 @@
 require 'spec_helper'
 
 describe 'acts_as_dag' do
+  before do
+    klass.destroy_all # Because we're using sqlite3 and it doesn't support transactional specs (afaik)
+  end
+
   shared_examples_for "DAG Model" do
-    before(:each) do
-      @klass.destroy_all # Because we're using sqlite3 and it doesn't support transactional specs (afaik)
+    let (:grandpa) { klass.create(:name => 'grandpa') }
+    let (:dad) { klass.create(:name => 'dad') }
+    let (:mom) { klass.create(:name => 'mom') }
+    let (:suzy) { klass.create(:name => 'suzy') }
+    let (:billy) { klass.create(:name => 'billy') }
+
+    describe '#children' do
+      it "returns an ActiveRecord::Relation" do
+        expect(mom.children).to be_an(ActiveRecord::Relation)
+      end
+
+      it "includes all children of the receiver" do
+        mom.add_child(suzy, billy)
+        expect(mom.children).to include(suzy,billy)
+      end
+
+      it "doesn't include any records that are not children of the receiver" do
+        grandpa.add_child(mom)
+        expect(mom.children).not_to include(grandpa)
+      end
+
+      it "returns records in the order they were added to the graph" do
+        grandpa.add_child(mom, dad)
+        expect(grandpa.children).to eq([mom, dad])
+      end
     end
 
-    describe "and" do
-      before(:each) do
-        @grandpa = @klass.create(:name => 'grandpa')
-        @dad = @klass.create(:name => 'dad')
-        @mom = @klass.create(:name => 'mom')
-        @child = @klass.create(:name => 'child')
+    describe '#parents' do
+      it "returns an ActiveRecord::Relation" do
+        expect(mom.parents).to be_an(ActiveRecord::Relation)
       end
 
-      it "should be descendant of itself immediately after saving" do
-        @grandpa.descendants.should == [@grandpa]
+      it "includes all parents of the receiver" do
+        suzy.add_parent(mom, dad)
+        expect(suzy.parents).to include(mom, dad)
       end
 
-      it "should be ancestor of itself immediately after saving" do
-        @grandpa.ancestors.should == [@grandpa]
+      it "doesn't include any records that are not parents of the receiver" do
+        dad.add_parent(grandpa)
+        suzy.add_parent(mom, dad)
+        expect(suzy.parents).not_to include(grandpa)
       end
 
-      it "should be able to add a child" do
-        @grandpa.add_child(@dad)
+      it "returns records in the order they were added to the graph" do
+        suzy.add_parent(mom, dad)
+        expect(suzy.parents).to eq([mom, dad])
+      end
+    end
 
-        @grandpa.children.should == [@dad]
+    describe '#descendants' do
+      it "returns an ActiveRecord::Relation" do
+        expect(mom.descendants).to be_an(ActiveRecord::Relation)
       end
 
-      it "should be able to add a parent" do
-        @child.add_parent(@dad)
+      it "doesn't include self" do
+        expect(mom.descendants).not_to include(mom)
+      end
 
-        @child.parents.should == [@dad]
+      it "includes all descendants of the receiver" do
+        grandpa.add_child(mom, dad)
+        mom.add_child(suzy)
+        dad.add_child(billy)
+        expect(grandpa.descendants).to include(mom, dad, suzy, billy)
       end
 
-      it "should be able to add multiple parents" do
-        @child.add_parent(@dad)
-        @child.add_parent(@mom)
+      it "doesn't include any ancestors of the receiver" do
+        grandpa.add_child(mom)
+        mom.add_child(suzy)
+        expect(mom.descendants).not_to include(grandpa)
+      end
 
-        @child.parents.sort_by(&:id).should == [@dad, @mom].sort_by(&:id)
+      it "returns records in ascending order of distance, and ascending order added to graph" do
+        grandpa.add_child(mom, dad)
+        mom.add_child(suzy)
+        dad.add_child(billy)
+        expect(grandpa.descendants).to eq([mom, dad, suzy, billy])
       end
 
-      it "should be able to add multiple children" do
-        @grandpa.add_child(@dad)
-        @grandpa.add_child(@mom)
+      it "returns no duplicates when there are multiple paths to the same descendant" do
+        grandpa.add_child(mom, dad)
+        billy.add_parent(mom, dad)
+
+        expect(grandpa.descendants).to eq(grandpa.descendants.uniq)
+      end
+    end
+
+    describe '#subtree' do
+      it "returns an ActiveRecord::Relation" do
+        expect(mom.subtree).to be_an(ActiveRecord::Relation)
+      end
+
+      it "includes self" do
+        expect(mom.subtree).to include(mom)
+      end
+
+      it "includes all descendants of the receiver" do
+        grandpa.add_child(mom)
+        mom.add_child(billy)
+        expect(grandpa.subtree).to include(mom, billy)
+      end
+
+      it "doesn't include any ancestors of the receiver" do
+        grandpa.add_child(mom)
+        mom.add_child(billy)
+        expect(mom.subtree).not_to include(grandpa)
+      end
+
+      it "returns records in ascending order of distance, and ascending order added to graph" do
+        grandpa.add_child(mom)
+        grandpa.add_child(dad)
+        mom.add_child(billy)
+        expect(grandpa.subtree).to eq([grandpa, mom, dad, billy])
+      end
+
+      it "returns no duplicates when there are multiple paths to the same descendant" do
+        grandpa.add_child(mom, dad)
+        billy.add_parent(mom, dad)
+
+        expect(grandpa.subtree).to eq(grandpa.subtree.uniq)
+      end
+    end
 
-        @grandpa.children.sort_by(&:id).should == [@dad, @mom].sort_by(&:id)
+    describe '#ancestors' do
+      it "returns an ActiveRecord::Relation" do
+        expect(mom.ancestors).to be_an(ActiveRecord::Relation)
       end
 
-      it "should be able to add ancestors (top down)" do
-        @grandpa.add_child(@dad)
-        @dad.add_child(@child)
+      it "doesn't include self" do
+        expect(mom.ancestors).not_to include(mom)
+      end
 
-        @grandpa.children.should == [@dad]
-        @grandpa.descendants.sort_by(&:id).should == [@grandpa, @dad, @child].sort_by(&:id)
-        @dad.descendants.should == [@dad, @child]
-        @dad.children.should == [@child]
+      it "includes all ancestors of the receiver" do
+        grandpa.add_child(mom)
+        mom.add_child(billy)
+        expect(billy.ancestors).to include(grandpa, mom)
       end
 
-      it "should be able to add ancestors (bottom up)" do
-        @dad.add_child(@child)
-        @grandpa.add_child(@dad)
+      it "doesn't include any descendants of the receiver" do
+        grandpa.add_child(mom)
+        mom.add_child(billy)
+        expect(mom.ancestors).not_to include(billy)
+      end
 
-        @grandpa.children.should == [@dad]
-        @grandpa.descendants.sort_by(&:id).should == [@grandpa, @dad, @child].sort_by(&:id)
-        @dad.descendants.should == [@dad,@child]
-        @dad.children.should == [@child]
+      it "returns records in descending order of distance, and ascending order added to graph" do
+        grandpa.add_child(mom)
+        mom.add_child(billy)
+        dad.add_child(billy)
+        expect(billy.ancestors).to eq([grandpa, mom, dad])
       end
 
-      it "should return ancestors in order of greatest distance to least" do
-        @dad.add_child(@child)
-        @grandpa.add_child(@dad)
+      it "returns no duplicates when there are multiple paths to the same ancestor" do
+        grandpa.add_child(mom, dad)
+        billy.add_parent(mom, dad)
 
-        @child.ancestors.should == [@grandpa, @dad, @child]
+        expect(billy.ancestors).to eq(billy.ancestors.uniq)
       end
+    end
 
-      it "should return descendants in order of of least distance to greatest" do
-        @dad.add_child(@child)
-        @grandpa.add_child(@dad)
+    describe '#path' do
+      it "returns an ActiveRecord::Relation" do
+        expect(mom.path).to be_an(ActiveRecord::Relation)
+      end
 
-        @grandpa.descendants.should == [@grandpa, @dad, @child]
+      it "includes self" do
+        expect(mom.path).to include(mom)
       end
 
-      it "should be able to test descent" do
-        @dad.add_child(@child)
-        @grandpa.add_child(@dad)
+      it "includes all ancestors of the receiver" do
+        grandpa.add_child(mom)
+        mom.add_child(billy)
+        dad.add_child(billy)
+        expect(billy.path).to include(grandpa, mom, dad)
+      end
 
-        @grandpa.ancestor_of?(@child).should be_truthy
-        @child.descendant_of?(@grandpa).should be_truthy
-        @child.ancestor_of?(@grandpa).should be_falsy
-        @grandpa.descendant_of?(@child).should be_falsy
+      it "doesn't include any descendants of the receiver" do
+        grandpa.add_child(mom)
+        mom.add_child(billy)
+        expect(mom.path).not_to include(billy)
       end
 
-      it "should be a root node immediately after saving" do
-        @grandpa.parents.should be_empty
-        @grandpa.root?.should be_truthy
+      it "returns records in descending order of distance, and ascending order added to graph" do
+        grandpa.add_child(mom)
+        mom.add_child(billy)
+        dad.add_child(billy)
+        expect(billy.path).to eq([grandpa, mom, dad, billy])
       end
 
-      it "should be a child if it has a parent" do
-        @grandpa.add_child(@dad)
-        @grandpa.add_child(@mom)
-        @klass.children.order(:id).should == [@dad, @mom]
+      it "returns no duplicates when there are multiple paths to the same ancestor" do
+        grandpa.add_child(mom, dad)
+        billy.add_parent(mom, dad)
+
+        expect(billy.path).to eq(billy.path.uniq)
       end
     end
 
-    context "when a record hierarchy exists" do
-      before(:each) do
-        @grandma = @klass.create(:name => 'grandma')
-        @mom = @klass.create(:name => 'mom')
-        @brother = @klass.create(:name => 'brother')
+    describe '#add_child' do
+      it "makes the record a child of the receiver" do
+        mom.add_child(billy)
+        expect(billy.child_of?(mom)).to be_truthy
+      end
 
-        @grandma.add_child(@mom)
-        @mom.add_child(@brother)
+      it "makes the record a descendant of the receiver" do
+        mom.add_child(billy)
+        expect(billy.descendant_of?(mom)).to be_truthy
       end
 
-      it "destroying a record should delete the associated hierarchy-tracking records " do
-        @mom.destroy
-        @mom.descendant_links.should be_empty
-        @mom.ancestor_links.should be_empty
-        @mom.parent_links.should be_empty
-        @mom.child_links.should be_empty
+      it "makes the record an descendant of any of the receiver's ancestors" do
+        grandpa.add_child(mom)
+        mom.add_child(billy)
+        expect(billy.descendant_of?(grandpa)).to be_truthy
       end
 
-      it "make_root should make the record a root, but maintain it's children" do
-        @mom.make_root
+      it "can be called multiple times to add additional children" do
+        mom.add_child(suzy)
+        mom.add_child(billy)
+        expect(mom.children).to include(suzy, billy)
+      end
 
-        @mom.should be_root
-        @mom.parents.should be_empty
-        @mom.children.should be_present
+      it "accepts multiple arguments, adding each as a child" do
+        mom.add_child(suzy, billy)
+        expect(mom.children).to include(suzy, billy)
       end
 
-      it "should return a list of ancestors and descendants" do
-        @mom.relatives.should == (@mom.ancestors + @mom.descendants).uniq
+      it "accepts an array of records, adding each as a child" do
+        mom.add_child([suzy, billy])
+        expect(mom.children).to include(suzy, billy)
       end
     end
 
-    describe "reorganization" do
-      before(:each) do
-        @totem = @klass.create(:name => "totem")
-        @totem_pole = @klass.create(:name => "totem pole")
-        @big_totem_pole = @klass.create(:name => "big totem pole")
-        @big_model_totem_pole = @klass.create(:name => "big model totem pole")
-        @big_red_model_totem_pole = @klass.create(:name => "big red model totem pole")
+    describe '#add_parent' do
+      it "makes the record a parent of the receiver" do
+        suzy.add_parent(dad)
+        expect(dad.parent_of?(suzy)).to be_truthy
       end
 
-      it "should reinitialize links and descendants after resetting the hierarchy" do
-        @klass.reset_hierarchy
-        @big_totem_pole.parents.should == []
-        @big_totem_pole.children.should == []
-        @big_totem_pole.ancestors.should == [@big_totem_pole]
-        @big_totem_pole.descendants.should == [@big_totem_pole]
+      it "makes the record a ancestor of the receiver" do
+        suzy.add_parent(dad)
+        expect(dad.ancestor_of?(suzy)).to be_truthy
       end
 
-      it "should be able to determine whether one category is an ancestor of the other by inspecting the name" do
-        ActsAsDAG::HelperMethods.should_descend_from?(@totem_pole, @big_totem_pole).should be_truthy
-        ActsAsDAG::HelperMethods.should_descend_from?(@big_totem_pole, @totem_pole).should be_falsy
+      it "makes the record an ancestor of any of the receiver's ancestors" do
+        dad.add_parent(grandpa)
+        suzy.add_parent(dad)
+        expect(grandpa.ancestor_of?(suzy)).to be_truthy
       end
 
-      it "should be able to determine the number of matching words in two categories names" do
-        ActsAsDAG::HelperMethods.matching_word_count(@totem_pole, @big_totem_pole).should == 2
+      it "can be called multiple times to add additional parents" do
+        suzy.add_parent(mom)
+        suzy.add_parent(dad)
+        expect(suzy.parents).to include(mom, dad)
       end
 
-      it "should arrange the categories correctly when not passed any arguments" do
-        @klass.reorganize
+      it "accepts multiple arguments, adding each as a parent" do
+        suzy.add_parent(mom, dad)
+        expect(suzy.parents).to include(mom, dad)
+      end
 
-        @totem.children.should == [@totem_pole]
-        @totem_pole.children.should == [@big_totem_pole]
-        @big_totem_pole.children.should == [@big_model_totem_pole]
-        @big_model_totem_pole.children.should == [@big_red_model_totem_pole]
+      it "accepts an array of records, adding each as a parent" do
+        suzy.add_parent([mom, dad])
+        expect(suzy.parents).to include(mom, dad)
       end
+    end
 
-      it "should arrange the categories correctly when passed a set of nodes to reorganize" do
-        @klass.reorganize [@totem, @totem_pole, @big_totem_pole, @big_model_totem_pole, @big_red_model_totem_pole]
+    describe '#ancestor_of?' do
+      it "returns true if the record is a ancestor of the receiver" do
+        grandpa.add_child(mom)
+        mom.add_child(billy)
+        expect(grandpa.ancestor_of?(billy)).to be_truthy
+      end
 
-        @totem.reload.children.should == [@totem_pole]
-        @totem_pole.reload.children.should == [@big_totem_pole]
-        @big_totem_pole.reload.children.should == [@big_model_totem_pole]
-        @big_model_totem_pole.reload.children.should == [@big_red_model_totem_pole]
+      it "returns false if the record is not an ancestor of the receiver" do
+        grandpa.add_child(dad)
+        mom.add_child(billy)
+        expect(grandpa.ancestor_of?(billy)).to be_falsey
       end
+    end
 
-      it "should arrange the categories correctly when inserting a category into an existing chain" do
-        @totem.add_child(@big_totem_pole)
+    describe '#descendant_of?' do
+      it "returns true if the record is a descendant of the receiver" do
+        grandpa.add_child(mom)
+        mom.add_child(billy)
+        expect(billy.descendant_of?(grandpa)).to be_truthy
+      end
 
-        @klass.reorganize
+      it "returns false if the record is not an descendant of the receiver" do
+        grandpa.add_child(dad)
+        mom.add_child(billy)
+        expect(billy.descendant_of?(grandpa)).to be_falsey
+      end
+    end
 
-        @totem.children.should == [@totem_pole]
-        @totem_pole.children.should == [@big_totem_pole]
-        @big_totem_pole.children.should == [@big_model_totem_pole]
-        @big_model_totem_pole.reload.children.should == [@big_red_model_totem_pole]
+    describe '#child_of?' do
+      it "returns true if the record is a child of the receiver" do
+        mom.add_child(billy)
+        expect(billy.child_of?(mom)).to be_truthy
       end
 
-      it "should still work when there are categories that are permutations of each other" do
-        @big_totem_pole_model = @klass.create(:name => "big totem pole model")
+      it "returns false if the record is not an child of the receiver" do
+        mom.add_child(suzy)
+        expect(billy.child_of?(mom)).to be_falsey
+      end
+    end
 
-        @klass.reorganize [@totem, @totem_pole, @big_totem_pole, @big_model_totem_pole, @big_red_model_totem_pole, @big_totem_pole_model]
+    describe '#parent_of?' do
+      it "returns true if the record is a parent of the receiver" do
+        mom.add_child(billy)
+        expect(mom.parent_of?(billy)).to be_truthy
+      end
 
-        @totem.children.should == [@totem_pole]
-        @totem_pole.children.should == [@big_totem_pole]
-        (@big_totem_pole.children - [@big_model_totem_pole, @big_totem_pole_model]).should == []
-        @big_model_totem_pole.reload.children.should == [@big_red_model_totem_pole]
-        @big_totem_pole_model.reload.children.should == [@big_red_model_totem_pole]
+      it "returns false if the record is not an parent of the receiver" do
+        mom.add_child(billy)
+        expect(mom.parent_of?(suzy)).to be_falsey
       end
+    end
 
-      describe "when there is a single long inheritance chain" do
-        before(:each) do
-          @totem.add_child(@totem_pole)
-          @totem_pole.add_child(@big_totem_pole)
-          @big_totem_pole.add_child(@big_model_totem_pole)
-          @big_model_totem_pole.add_child(@big_red_model_totem_pole)
-        end
+    describe '#root?' do
+      it "returns true if the record has no parents" do
+        mom.add_child(suzy)
+        expect(mom.root?).to be_truthy
+      end
 
-        describe "and we are reorganizing the middle of the chain" do
-          # Totem
-          #   |
-          # Totem Pole
-          #  *|*       \
-          #  *|*      Big Totem Pole
-          #  *|*       /
-          # Big Model Totem Pole
-          #   |
-          # Big Red Model Totem Pole
-          #
-          before(:each) do
-            @totem_pole.add_child(@big_model_totem_pole)
-          end
-
-          it "should return multiple instances of descendants before breaking the old link" do
-            @totem.descendants.sort_by(&:id).should == [@totem, @totem_pole, @big_totem_pole, @big_model_totem_pole, @big_model_totem_pole, @big_red_model_totem_pole, @big_red_model_totem_pole].sort_by(&:id)
-          end
-
-          it "should return the correct inheritance chain after breaking the old link" do
-            @totem_pole.remove_child(@big_model_totem_pole)
-
-            @totem_pole.children.sort_by(&:id).should == [@big_totem_pole].sort_by(&:id)
-            @totem.descendants.sort_by(&:id).should == [@totem, @totem_pole, @big_totem_pole, @big_model_totem_pole, @big_red_model_totem_pole].sort_by(&:id)
-          end
-
-          it "should return the correct inheritance chain after breaking the old link when there is are two ancestor root nodes" do
-            pole = @klass.create(:name => "pole")
-            @totem_pole.add_parent(pole)
-            @totem_pole.remove_child(@big_model_totem_pole)
-
-            pole.descendants.sort_by(&:id).should == [pole, @totem_pole, @big_totem_pole, @big_model_totem_pole, @big_red_model_totem_pole].sort_by(&:id)
-            @totem_pole.children.sort_by(&:id).should == [@big_totem_pole].sort_by(&:id)
-            @totem.descendants.sort_by(&:id).should == [@totem, @totem_pole, @big_totem_pole, @big_model_totem_pole, @big_red_model_totem_pole].sort_by(&:id)
-          end
-        end
+      it "returns false if the record has parents" do
+        mom.add_parent(grandpa)
+        expect(mom.root?).to be_falsey
       end
     end
 
-    describe "and two paths of the same length exist to the same node" do
-      before(:each) do
-        @grandpa = @klass.create(:name => 'grandpa')
-        @dad = @klass.create(:name => 'dad')
-        @mom = @klass.create(:name => 'mom')
-        @child = @klass.create(:name => 'child')
+    describe '#leaf?' do
+      it "returns true if the record has no children" do
+        mom.add_parent(grandpa)
+        expect(mom.leaf?).to be_truthy
+      end
 
-        # nevermind the incest
-        @grandpa.add_child(@dad)
-        @dad.add_child(@child)
-        @child.add_parent(@mom)
-        @mom.add_parent(@grandpa)
+      it "returns false if the record has children" do
+        mom.add_child(suzy)
+        expect(mom.leaf?).to be_falsey
       end
+    end
 
-      it "descendants should not return multiple instances of a child" do
-        @grandpa.descendants.sort_by(&:id).should == [@grandpa, @dad, @mom, @child].sort_by(&:id)
+    describe '#make_root' do
+      it "makes the receiver a root node" do
+        mom.add_parent(grandpa)
+        mom.make_root
+        expect(mom.root?).to be_truthy
       end
 
-      describe "and a link between parent and ancestor is removed" do
-        before(:each) do
-          # the incest is undone!
-          @dad.remove_parent(@grandpa)
-        end
+      it "removes the receiver from the children of its parents" do
+        suzy.add_parent(mom, dad)
+        suzy.make_root
+        expect(mom.children).not_to include(suzy)
+        expect(dad.children).not_to include(suzy)
+      end
 
-        it "should still return the correct ancestors" do
-          @child.ancestors.sort_by(&:id).should == [@grandpa, @dad, @mom, @child].sort_by(&:id)
-          @mom.ancestors.sort_by(&:id).should == [@grandpa, @mom].sort_by(&:id)
-          @dad.ancestors.sort_by(&:id).should == [@dad].sort_by(&:id)
+      it "doesn't modify the relationship between the receiver and its descendants" do
+        mom.add_parent(grandpa)
+        mom.add_child(suzy, billy)
+        mom.make_root
+        expect(mom.children).to eq([suzy, billy])
+      end
+    end
+
+    describe '#lineage' do
+      it "returns an ActiveRecord::Relation" do
+        expect(mom.children).to be_an(ActiveRecord::Relation)
+      end
+
+      it "doesn't include the receiver" do
+        expect(mom.lineage).not_to include(mom)
+      end
+
+      it "includes all ancestors and descendants of the receiver" do
+        mom.add_child(suzy, billy)
+        mom.add_parent(grandpa)
+        expect(mom.lineage).to include(grandpa, suzy, billy)
+      end
+
+      it "return ancestors and descendants of the receiver in the order they would be if called separately" do
+        mom.add_child(suzy, billy)
+        mom.add_parent(grandpa)
+        expect(mom.lineage).to eq([grandpa, suzy, billy])
+      end
+    end
+
+    describe '::children' do
+      it "returns an ActiveRecord::Relation" do
+        expect(klass.children).to be_an(ActiveRecord::Relation)
+      end
+
+      it "returns records that have at least 1 parent" do
+        mom.add_parent(grandpa)
+        mom.add_child(suzy)
+        expect(klass.children).to include(mom, suzy)
+      end
+
+      it "doesn't returns records without parents" do
+        mom.add_parent(grandpa)
+        mom.add_child(suzy)
+        expect(klass.children).not_to include(grandpa)
+      end
+
+      it "does not return duplicate records, regardless of the number of parents" do
+        suzy.add_parent(mom, dad)
+        expect(klass.children).to eq([suzy])
+      end
+    end
+
+    describe '::parent_records' do
+      it "returns an ActiveRecord::Relation" do
+        expect(klass.parent_records).to be_an(ActiveRecord::Relation)
+      end
+
+      it "returns records that have at least 1 child" do
+        mom.add_parent(grandpa)
+        mom.add_child(suzy)
+        expect(klass.parent_records).to include(grandpa, mom)
+      end
+
+      it "doesn't returns records without children" do
+        mom.add_parent(grandpa)
+        mom.add_child(suzy)
+        expect(klass.parent_records).not_to include(suzy)
+      end
+
+      it "does not return duplicate records, regardless of the number of children" do
+        mom.add_child(suzy, billy)
+        expect(klass.parent_records).to eq([mom])
+      end
+    end
+
+    describe '#ancestors_of' do
+      it "returns an ActiveRecord::Relation" do
+        expect(klass.ancestors_of(suzy)).to be_an(ActiveRecord::Relation)
+      end
+
+      it "doesn't include the given record" do
+        expect(klass.ancestors_of(suzy)).not_to include(suzy)
+      end
+
+      it "returns records that are ancestors of the given record" do
+        suzy.add_parent(mom, dad)
+        expect(klass.ancestors_of(suzy)).to include(mom, dad)
+      end
+
+      it "doesn't return records that are not ancestors of the given record" do
+        suzy.add_parent(mom)
+        expect(klass.ancestors_of(suzy)).not_to include(dad)
+      end
+
+      it "returns records that are ancestors of the given record id" do
+        suzy.add_parent(mom, dad)
+        expect(klass.ancestors_of(suzy.id)).to include(mom, dad)
+      end
+    end
+
+    describe '#descendants_of' do
+      it "returns an ActiveRecord::Relation" do
+        expect(klass.descendants_of(grandpa)).to be_an(ActiveRecord::Relation)
+      end
+
+      it "doesn't include the given record" do
+        expect(klass.descendants_of(grandpa)).not_to include(grandpa)
+      end
+
+      it "returns records that are descendants of the given record" do
+        grandpa.add_child(mom, dad)
+        expect(klass.descendants_of(grandpa)).to include(mom, dad)
+      end
+
+      it "doesn't return records that are not descendants of the given record" do
+        grandpa.add_child(mom)
+        expect(klass.descendants_of(grandpa)).not_to include(dad)
+      end
+
+      it "returns records that are descendants of the given record id" do
+        grandpa.add_child(mom, dad)
+        expect(klass.descendants_of(grandpa.id)).to include(mom, dad)
+      end
+    end
+
+    describe '#path_of' do
+      it "returns an ActiveRecord::Relation" do
+        expect(klass.path_of(suzy)).to be_an(ActiveRecord::Relation)
+      end
+
+      it "returns records that are path-members of the given record" do
+        suzy.add_parent(mom, dad)
+        expect(klass.path_of(suzy)).to include(mom, dad, suzy)
+      end
+
+      it "doesn't return records that are not path-members of the given record" do
+        suzy.add_parent(mom)
+        expect(klass.path_of(suzy)).not_to include(dad)
+      end
+
+      it "returns records that are path-members of the given record id" do
+        suzy.add_parent(mom, dad)
+        expect(klass.path_of(suzy.id)).to include(mom, dad, suzy)
+      end
+    end
+
+    describe '#subtree_of' do
+      it "returns an ActiveRecord::Relation" do
+        expect(klass.subtree_of(grandpa)).to be_an(ActiveRecord::Relation)
+      end
+
+      it "returns records that are subtree-members of the given record" do
+        grandpa.add_child(mom, dad)
+        expect(klass.subtree_of(grandpa)).to include(grandpa, mom, dad)
+      end
+
+      it "doesn't return records that are not subtree-members of the given record" do
+        grandpa.add_child(mom)
+        expect(klass.subtree_of(grandpa)).not_to include(dad)
+      end
+
+      it "returns records that are subtree-members of the given record id" do
+        grandpa.add_child(mom, dad)
+        expect(klass.subtree_of(grandpa.id)).to include(grandpa, mom, dad)
+      end
+    end
+
+    describe '#destroy' do
+      it "destroys associated hierarchy-tracking records" do
+        mom.add_parent(grandpa)
+        mom.add_child(suzy)
+
+        mom.destroy
+
+        expect(mom.ancestor_links).to contain_exactly
+        expect(mom.path_links).to contain_exactly
+        expect(mom.parent_links).to contain_exactly
+        expect(mom.child_links).to contain_exactly
+      end
+    end
+
+    describe '#parents=' do
+      before { suzy.parents = [mom, dad] }
+
+      it "sets the receiver's parents to the given array" do
+        expect(suzy.parents).to eq([mom, dad])
+      end
+
+      it "updates the ancestors of the receiver" do
+        expect(suzy.ancestors).to eq([mom, dad])
+      end
+
+      it "unsets the receiver's parents when given an empty array" do
+        suzy.parents = []
+        expect(suzy.parents).to contain_exactly
+      end
+
+      it "updates the ancestors of the receivers when given an empty array" do
+        suzy.parents = []
+        expect(suzy.ancestors).to contain_exactly
+      end
+    end
+
+    describe '#children=' do
+      before { grandpa.children = [mom, dad] }
+
+      it "sets the receiver's children to the given array" do
+        expect(grandpa.children).to eq([mom, dad])
+      end
+
+      it "updates the descendants of the receiver" do
+        expect(grandpa.descendants).to eq([mom, dad])
+      end
+
+      it "unsets the receiver's children when given an empty array" do
+        grandpa.children = []
+        expect(grandpa.children).to contain_exactly
+      end
+
+      it "updates the descendants of the receivers when given an empty array" do
+        grandpa.children = []
+        expect(grandpa.descendants).to contain_exactly
+      end
+    end
+
+    describe '#parent_ids=' do
+      before { suzy.parent_ids = [mom.id, dad.id] }
+
+      it "sets the receiver's parents to the given array" do
+        expect(suzy.parents).to eq([mom, dad])
+      end
+
+      it "updates the ancestors of the receiver" do
+        expect(suzy.ancestors).to eq([mom, dad])
+      end
+
+      it "unsets the receiver's parents when given an empty array" do
+        suzy.parents = []
+        expect(suzy.parents).to contain_exactly
+      end
+
+      it "updates the ancestors of the receivers when given an empty array" do
+        suzy.parents = []
+        expect(suzy.ancestors).to contain_exactly
+      end
+    end
+
+    describe '#child_ids=' do
+      before { grandpa.child_ids = [mom.id, dad.id] }
+
+      it "sets the receiver's children to the given array" do
+        expect(grandpa.children).to eq([mom, dad])
+      end
+
+      it "updates the descendants of the receiver" do
+        expect(grandpa.descendants).to eq([mom, dad])
+      end
+
+      it "unsets the receiver's children when given an empty array" do
+        grandpa.children = []
+        expect(grandpa.children).to contain_exactly
+      end
+
+      it "updates the descendants of the receivers when given an empty array" do
+        grandpa.children = []
+        expect(grandpa.descendants).to contain_exactly
+      end
+    end
+
+    describe '#create' do
+      it "sets the receiver's children to the given array" do
+        record = klass.create!(:children => [mom, dad])
+        expect(record.children).to contain_exactly(mom, dad)
+      end
+
+      it "updates the descendants of the receiver" do
+        record = klass.create!(:children => [mom, dad])
+        record.reload
+        expect(record.descendants).to contain_exactly(mom, dad)
+      end
+
+      it "sets the receiver's parents to the given array" do
+        record = klass.create!(:parents => [mom, dad])
+        expect(record.parents).to contain_exactly(mom, dad)
+      end
+
+      it "updates the ancestors of the receiver" do
+        record = klass.create!(:parents => [mom, dad])
+        record.reload
+        expect(record.ancestors).to contain_exactly(mom, dad)
+      end
+    end
+
+    describe '::reset_hierarchy' do
+      it "reinitialize links and descendants after resetting the hierarchy" do
+        mom.add_parent(grandpa)
+        mom.add_child(suzy)
+
+        klass.reset_hierarchy
+        expect(mom.parents).to contain_exactly()
+        expect(mom.children).to contain_exactly()
+        expect(mom.path).to contain_exactly(mom)
+        expect(mom.subtree).to contain_exactly(mom)
+      end
+    end
+
+    describe '#ancestor_links' do
+      it "doesn't include a link to the receiver" do
+        expect(mom.ancestor_links).to contain_exactly
+      end
+    end
+
+    describe '#path_links' do
+      it "includes a link to the receiver" do
+        expect(mom.path_links.first.descendant).to eq(mom)
+      end
+    end
+
+    describe '#descendant_links' do
+      it "doesn't include a link to the receiver" do
+        expect(mom.descendant_links).to contain_exactly
+      end
+    end
+
+    describe '#subtree_links' do
+      it "includes a link to the receiver" do
+        expect(mom.subtree_links.first.descendant).to eq(mom)
+      end
+    end
+
+    describe '::roots' do
+      it "returns all root nodes" do
+        mom; dad
+        expect(klass.roots).to include(mom, dad)
+      end
+
+      it "doesn't return non-root nodes" do
+        mom.add_child(suzy)
+        expect(klass.roots).not_to include(suzy)
+      end
+
+      it "doesn't mark returned records as readonly" do
+        mom; dad
+        expect(klass.roots.none?(&:readonly?)).to be_truthy
+      end
+    end
+
+    describe '::leafs' do
+      it "returns all leaf nodes" do
+        mom.add_child(suzy)
+        expect(klass.leafs).to include(suzy)
+      end
+
+      it "doesn't return non-leaf nodes" do
+        mom.add_child(suzy)
+        expect(klass.leafs).not_to include(mom)
+      end
+
+      it "doesn't mark returned records as readonly" do
+        mom.add_child(suzy)
+        expect(klass.leafs.none?(&:readonly?)).to be_truthy
+      end
+    end
+
+    describe '::children' do
+      it "returns all child nodes" do
+        mom.add_child(suzy)
+        expect(klass.children).to contain_exactly(suzy)
+      end
+
+      it "doesn't return non-child nodes" do
+        mom; dad
+        expect(klass.children).not_to include(mom, dad)
+      end
+
+      it "doesn't mark returned records as readonly" do
+        mom.add_child(suzy)
+        expect(klass.children.none?(&:readonly?)).to be_truthy
+      end
+    end
+
+    describe '::parent_records' do
+      it "returns all parent nodes" do
+        mom.add_child(suzy)
+        expect(klass.parent_records).to contain_exactly(mom)
+      end
+
+      it "doesn't return non-parent nodes" do
+        mom; dad
+        expect(klass.parent_records).not_to include(mom, dad)
+      end
+
+      it "doesn't mark returned records as readonly" do
+        mom.add_child(suzy)
+        expect(klass.parent_records.none?(&:readonly?)).to be_truthy
+      end
+    end
+
+    context "When two paths of the same length exist to the same node and a link between parent and ancestor is removed" do
+      before do
+        grandpa.add_child(mom, dad)
+        suzy.add_parent(mom, dad)
+      end
+
+      describe '#remove_parent' do
+        it "updates the ancestor links correctly" do
+          dad.remove_parent(grandpa)
+          expect(suzy.ancestors).to contain_exactly(grandpa, dad, mom)
+          expect(mom.ancestors).to contain_exactly(grandpa)
+          expect(dad.ancestors).to contain_exactly()
         end
 
-        it "should still return the correct descendants" do
-          @child.descendants.sort_by(&:id).should == [@child].sort_by(&:id)
-          @mom.descendants.sort_by(&:id).should == [@mom, @child].sort_by(&:id)
-          @dad.descendants.sort_by(&:id).should == [@dad, @child].sort_by(&:id)
-          @grandpa.descendants.sort_by(&:id).should == [@grandpa, @mom, @child].sort_by(&:id)
+        it "updates the descendant links correctly" do
+          dad.remove_parent(grandpa)
+          expect(suzy.descendants).to contain_exactly()
+          expect(mom.descendants).to contain_exactly(suzy)
+          expect(dad.descendants).to contain_exactly(suzy)
+          expect(grandpa.descendants).to contain_exactly(mom, suzy)
         end
       end
     end
+
+    # describe "Includes, Eager-Loads, and Preloads" do
+    #   before(:each) do
+    #     dad.add_parent(grandpa)
+    #     billy.add_parent(dad, mom)
+    #   end
+
+    #   it "should preload path in the correct order" do
+    #     records = klass.order("#{klass.table_name}.id asc").preload(:path)
+
+    #     records[0].path.should == [grandpa]                      # grandpa
+    #     records[1].path.should == [grandpa, dad]                # dad
+    #     records[2].path.should == [mom]                          # mom
+    #     records[3].path.should == [grandpa, dad, mom, billy]  # billy
+    #   end
+
+    #   it "should eager_load path in the correct order" do
+    #     records = klass.order("#{klass.table_name}.id asc").eager_load(:path)
+
+    #     records[0].path.should == [grandpa]                      # grandpa
+    #     records[1].path.should == [grandpa, dad]                # dad
+    #     records[2].path.should == [mom]                          # mom
+    #     records[3].path.should == [grandpa, dad, mom, billy]  # billy
+    #   end
+
+    #   it "should include path in the correct order" do
+    #     records = klass.order("#{klass.table_name}.id asc").includes(:path)
+
+    #     records[0].path.should == [grandpa]                      # grandpa
+    #     records[1].path.should == [grandpa, dad]                # dad
+    #     records[2].path.should == [mom]                          # mom
+    #     records[3].path.should == [grandpa, dad, mom, billy]  # billy
+    #   end
+    # end
   end
 
   describe "models with separate link tables" do
-    before(:each) do
-      @klass = SeparateLinkModel
-    end
+    let(:klass) { SeparateLinkModel }
 
     it_should_behave_like "DAG Model"
   end
 
   describe "models with unified link tables" do
-    before(:each) do
-      @klass = UnifiedLinkModel
-    end
+    let(:klass) { UnifiedLinkModel }
 
     it_should_behave_like "DAG Model"
 
     it "should create links that include the category type" do
-      record = @klass.create!
+      record = klass.create!
 
-      record.parent_links.first.category_type.should == @klass.name
-      record.descendant_links.first.category_type.should == @klass.name
+      expect(record.parent_links.first.category_type).to eq(klass.name)
+      expect(record.subtree_links.first.category_type).to eq(klass.name)
     end
   end
 end