mongoid-ancestry 0.1.0

data/Gemfile

@@ -0,0 +1,3 @@
+source :rubygems
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,75 @@
+PATH
+  remote: .
+  specs:
+    mongoid-ancestry (0.0.0)
+      bson_ext (~> 1.3)
+      mongoid (~> 2.0)
+      mongoid-ancestry
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activemodel (3.0.6)
+      activesupport (= 3.0.6)
+      builder (~> 2.1.2)
+      i18n (~> 0.5.0)
+    activesupport (3.0.6)
+    bson (1.3.0)
+    bson_ext (1.3.0)
+    builder (2.1.2)
+    chalofa_ruby-progressbar (0.0.9.1)
+    configuration (1.2.0)
+    diff-lcs (1.1.2)
+    ffi (1.0.7)
+      rake (>= 0.8.7)
+    fuubar (0.0.4)
+      chalofa_ruby-progressbar (~> 0.0.9)
+      rspec (~> 2.0)
+      rspec-instafail (~> 0.1.4)
+    guard (0.3.0)
+      open_gem (~> 1.4.2)
+      thor (~> 0.14.6)
+    guard-rspec (0.2.0)
+      guard (>= 0.2.2)
+    i18n (0.5.0)
+    launchy (0.3.7)
+      configuration (>= 0.0.5)
+      rake (>= 0.8.1)
+    libnotify (0.3.0)
+      ffi (>= 0.6.2)
+    mongo (1.3.0)
+      bson (>= 1.3.0)
+    mongoid (2.0.1)
+      activemodel (~> 3.0)
+      mongo (~> 1.3)
+      tzinfo (~> 0.3.22)
+      will_paginate (~> 3.0.pre)
+    open_gem (1.4.2)
+      launchy (~> 0.3.5)
+    rake (0.8.7)
+    rb-inotify (0.8.4)
+      ffi (>= 0.5.0)
+    rspec (2.5.0)
+      rspec-core (~> 2.5.0)
+      rspec-expectations (~> 2.5.0)
+      rspec-mocks (~> 2.5.0)
+    rspec-core (2.5.1)
+    rspec-expectations (2.5.0)
+      diff-lcs (~> 1.1.2)
+    rspec-instafail (0.1.7)
+    rspec-mocks (2.5.0)
+    thor (0.14.6)
+    tzinfo (0.3.26)
+    will_paginate (3.0.pre2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.0)
+  fuubar (~> 0.0.4)
+  guard-rspec (~> 0.2)
+  libnotify (~> 0.3)
+  mongoid-ancestry!
+  rb-inotify (~> 0.8)
+  rspec (~> 2.5)

data/Guardfile

@@ -0,0 +1,10 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard 'rspec', :version => 2, :cli => "--format Fuubar" do
+  watch(%r{^spec/.+_spec\.rb})
+  watch(%r{^lib/mongoid/ancestry/(.+)\.rb})     { |m| "spec/mongoid/ancestry/#{m[1]}_spec.rb" }
+  watch('lib/mongoid/ancestry.rb')      { "spec" }
+  watch(%r{^spec/support/(.+)\.rb})     { "spec" }
+  watch('spec/spec_helper.rb')          { "spec" }
+end

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Stefan Kroes
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,225 @@
+Mongoid-ancestry
+================
+
+Mongoid-ancestry is a gem/plugin that allows the records of a Ruby on Rails Mongoid model to be organised as a tree structure (or hierarchy). It uses a single, intuitively formatted database column, using a variation on the materialised path pattern. It exposes all the standard tree structure relations (ancestors, parent, root, children, siblings, descendants) and all of them can be fetched in a single query. Additional features are STI support, scopes, depth caching, depth constraints, easy migration from older plugins/gems, integrity checking, integrity restoration, arrangement of (sub)tree into hashes and different strategies for dealing with orphaned records.
+
+Installation
+------------
+
+## It's Rails 3 only.
+
+To apply Mongoid-ancestry to any Mongoid model, follow these simple steps:
+
+1. Install
+Add to Gemfile: `gem 'ancestry'`
+Install required gems: `bundle install`
+
+2. Add ancestry to your model
+Add to app/models/[model].rb:
+
+     include Mongoid::Ancestry
+     has_ancestry
+
+Your model is now a tree!
+
+= Organising records into a tree
+By default MongoDB provide records with an unique id which can't be use to order their. Therefore, Mongoid-Ancestry
+adds to the all records of your's model an autoincremented unique id(by default `uid` attribute). You can use the parent
+attribute to organise your records into a tree. For these purposes you should use `uid` attribute. You have already had
+the `uid` of the record and you want to use it as a parent and don't want to fetch it, you can use parent_id. Like any
+virtual model attributes, parent and parent_id can be set using parent= and parent_id= on a record or by including them
+in the hash passed to new, create, create!, update_attributes and update_attributes!. For example:
+
+    TreeNode.create :name => 'Stinky', :parent => TreeNode.create(:name => 'Squeeky')
+
+or
+
+    TreeNode.create :name => 'Stinky', :parent_id => TreeNode.create(:name => 'Squeeky').uid
+
+### Note: It doesn't work with `.create!` at the moment(mongoid bug? needs more investigation). But it absolutely will be fixed.
+
+
+You can also create children through the children relation on a node:
+
+    node.children.create :name => 'Stinky'
+
+## Navigating your tree
+
+To navigate an Ancestry model, use the following methods on any instance / record:
+
+    parent           Returns the parent of the record, nil for a root node
+    parent_id        Returns the id of the parent of the record, nil for a root node
+    root             Returns the root of the tree the record is in, self for a root node
+    root_id          Returns the id of the root of the tree the record is in
+    is_root?         Returns true if the record is a root node, false otherwise
+    ancestor_ids     Returns a list of ancestor ids, starting with the root id and ending with the parent id
+    ancestors        Scopes the model on ancestors of the record
+    path_ids         Returns a list the path ids, starting with the root id and ending with the node's own id
+    path             Scopes model on path records of the record
+    children         Scopes the model on children of the record
+    child_ids        Returns a list of child ids
+    has_children?    Returns true if the record has any children, false otherwise
+    is_childless?    Returns true is the record has no childen, false otherwise
+    siblings         Scopes the model on siblings of the record, the record itself is included
+    sibling_ids      Returns a list of sibling ids
+    has_siblings?    Returns true if the record's parent has more than one child
+    is_only_child?   Returns true if the record is the only child of its parent
+    descendants      Scopes the model on direct and indirect children of the record
+    descendant_ids   Returns a list of a descendant ids
+    subtree          Scopes the model on descendants and itself
+    subtree_ids      Returns a list of all ids in the record's subtree
+    depth            Return the depth of the node, root nodes are at depth 0
+
+## Options for has_ancestry
+
+The has_ancestry methods supports the following options:
+
+    :ancestry_field        Pass in a symbol to store ancestry in a different field
+    :uid_field             Pass in a symbol to store unique id in a different field
+    :orphan_strategy       Instruct Ancestry what to do with children of a node that is destroyed:
+                           :destroy   All children are destroyed as well (default)
+                           :rootify   The children of the destroyed node become root nodes
+                           :restrict  An Error is raised if any children exist
+    :cache_depth           Cache the depth of each node in the 'ancestry_depth' field (default: false)
+                           If you turn depth_caching on for an existing model:
+                           - Build cache: TreeNode.rebuild_depth_cache!
+    :depth_cache_field     Pass in a symbol to store depth cache in a different field
+
+## (Named) Scopes
+
+Where possible, the navigation methods return scopes instead of records, this means additional ordering, conditions, limits, etc. can be applied and that the result can be either retrieved, counted or checked for existence. For example:
+
+    node.children.where(:name => 'Mary')
+    node.subtree.order_by([:name, :desc]).limit(10).each do; ...; end
+    node.descendants.count
+
+For convenience, a couple of named scopes are included at the class level:
+
+    roots                   Root nodes
+    ancestors_of(node)      Ancestors of node, node can be either a record or an id
+    children_of(node)       Children of node, node can be either a record or an id
+    descendants_of(node)    Descendants of node, node can be either a record or an id
+    subtree_of(node)        Subtree of node, node can be either a record or an id
+    siblings_of(node)       Siblings of node, node can be either a record or an id
+
+Thanks to some convenient rails magic, it is even possible to create nodes through the children and siblings scopes:
+
+    node.children.create
+    node.siblings.create
+    TestNode.children_of(node_id).build
+    TestNode.siblings_of(node_id).create
+
+## Selecting nodes by depth
+
+When depth caching is enabled (see has_ancestry options), five more named scopes can be used to select nodes on their depth:
+
+    before_depth(depth)     Return nodes that are less deep than depth (node.depth < depth)
+    to_depth(depth)         Return nodes up to a certain depth (node.depth <= depth)
+    at_depth(depth)         Return nodes that are at depth (node.depth == depth)
+    from_depth(depth)       Return nodes starting from a certain depth (node.depth >= depth)
+    after_depth(depth)      Return nodes that are deeper than depth (node.depth > depth)
+
+The depth scopes are also available through calls to descendants, descendant_ids, subtree, subtree_ids, path and ancestors. In this case, depth values are interpreted relatively. Some examples:
+
+    node.subtree(:to_depth => 2)      Subtree of node, to a depth of node.depth + 2 (self, children and grandchildren)
+    node.subtree.to_depth(5)          Subtree of node to an absolute depth of 5
+    node.descendants(:at_depth => 2)  Descendant of node, at depth node.depth + 2 (grandchildren)
+    node.descendants.at_depth(10)     Descendants of node at an absolute depth of 10
+    node.ancestors.to_depth(3)        The oldest 4 ancestors of node (its root and 3 more)
+    node.path(:from_depth => -2)      The node's grandparent, parent and the node itself
+
+    node.ancestors(:from_depth => -6, :to_depth => -4)
+    node.path.from_depth(3).to_depth(4)
+    node.descendants(:from_depth => 2, :to_depth => 4)
+    node.subtree.from_depth(10).to_depth(12)
+
+Please note that depth constraints cannot be passed to ancestor_ids and path_ids. The reason for this is that both these relations can be fetched directly from the ancestry column without performing a database query. It would require an entirely different method of applying the depth constraints which isn't worth the effort of implementing. You can use ancestors(depth_options).map(&:id) or ancestor_ids.slice(min_depth..max_depth) instead.
+
+## STI support
+
+Ancestry works fine with STI. Just create a STI inheritance hierarchy and build an Ancestry tree from the different classes/models. All Ancestry relations that where described above will return nodes of any model type. If you do only want nodes of a specific subclass you'll have to add a condition on type for that.
+
+## Arrangement
+
+Ancestry can arrange an entire subtree into nested hashes for easy navigation after retrieval from the database.  TreeNode.arrange could for example return:
+
+    { #<TreeNode id: 100018, name: "Stinky", ancestry: nil>
+      => { #<TreeNode id: 100019, name: "Crunchy", ancestry: "100018">
+        => { #<TreeNode id: 100020, name: "Squeeky", ancestry: "100018/100019">
+          => {}
+        }
+      }
+    }
+
+The arrange method also works on a scoped class, for example:
+
+    TreeNode.where(:name => 'Crunchy').first.subtree.arrange
+
+The arrange method takes Mongoid find options. If you want your hashes to be ordered, you should pass the order to the arrange method instead of to the scope. This only works for Ruby 1.9 and later since before that hashes weren't ordered. For example:
+
+    TreeNode.where(:name => 'Crunchy').subtree.arrange(:order => [:name, :asc])
+
+## Migrating from plugin that uses parent_id column
+
+With Mongoid-ancestry its easy to migrate from any of these plugins, to do so, use the build_ancestry_from_parent_ids! method on your model. These steps provide a more detailed explanation:
+
+1. Remove old tree plugin or gem and add in Mongoid-ancestry
+See 'Installation' for more info on installing and configuring gem
+Add to app/models/[model].rb:
+
+     include Mongoid::Ancestry
+     has_ancestry
+
+Create indexes
+
+2. Change your code
+Most tree calls will probably work fine with ancestry
+Others must be changed or proxied
+Check if all your data is intact and all tests pass
+
+3. Drop parent_id field
+
+## Integrity checking and restoration
+
+I don't see any way Mongoid-ancestry tree integrity could get compromised without explicitly setting cyclic parents or invalid ancestry and circumventing validation with update_attribute, if you do, please let me know.
+
+Mongoid-ancestry includes some methods for detecting integrity problems and restoring integrity just to be sure. To check integrity use: [Model].check_ancestry_integrity!. An Mongoid::Ancestry::Error will be raised if there are any problems. You can also specify :report => :list to return an array of exceptions or :report => :echo to echo any error messages. To restore integrity use: [Model].restore_ancestry_integrity!.
+
+For example, from IRB:
+
+    >> stinky = TreeNode.create :name => 'Stinky'
+    $  #<TreeNode id: 1, name: "Stinky", ancestry: nil>
+    >> squeeky = TreeNode.create :name => 'Squeeky', :parent => stinky
+    $  #<TreeNode id: 2, name: "Squeeky", ancestry: "1">
+    >> stinky.update_attribute :parent, squeeky
+    $  true
+    >> TreeNode.all
+    $  [#<TreeNode id: 1, name: "Stinky", ancestry: "1/2">, #<TreeNode id: 2, name: "Squeeky", ancestry: "1/2/1">]
+    >> TreeNode.check_ancestry_integrity!
+    !! Ancestry::AncestryIntegrityException: Conflicting parent id in node 1: 2 for node 1, expecting nil
+    >> TreeNode.restore_ancestry_integrity!
+    $  [#<TreeNode id: 1, name: "Stinky", ancestry: 2>, #<TreeNode id: 2, name: "Squeeky", ancestry: nil>]
+
+Additionally, if you think something is wrong with your depth cache:
+
+    >> TreeNode.rebuild_depth_cache!
+
+## Tests
+
+The Mongoid-ancestry gem comes with rspec and guard(for automatically specs running) suite consisting of about 40 specs. It takes about 10 seconds to run. To run it yourself check out the repository from GitHub, run `bundle install`, run `guard` and press `Ctrl+\` or just `rake spec`.
+
+## Internals
+
+As can be seen in the previous section, Mongoid-ancestry stores a path from the root to the parent for every node. This is a variation on the materialised path database pattern. It allows to fetch any relation (siblings, descendants, etc.) in a single query without the complicated algorithms and incomprehensibility associated with left and right values. Additionally, any inserts, deletes and updates only affect nodes within the affected node's own subtree.
+
+The materialised path pattern requires Mongoid-ancestry to use a 'regexp' condition in order to fetch descendants. This should not be particularly slow however since the the condition never starts with a wildcard which allows the DBMS to use the column index. If you have any data on performance with a large number of records, please drop me line.
+
+## Contact and copyright
+
+It's a fork of [original ancestry](https://github.com/stefankroes/ancestry) gem but adopted to work with Mongoid.
+
+All thanks should goes to Stefan Kroes for his great work.
+
+Bug report? Faulty/incomplete documentation? Feature request? Please post an issue on 'http://github.com/skyeagle/mongoid-ancestry/issues'.
+
+Copyright (c) 2009 Stefan Kroes, released under the MIT license

data/Rakefile

@@ -0,0 +1,42 @@
+require 'rubygems'
+
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "mongoid-ancestry"
+  gem.homepage = "http://github.com/skyeagle/mongoid-ancestry"
+  gem.license = "MIT"
+  gem.summary = %Q{'Ancestry allows the records of a Mongoid model to be organised in a tree structure, using a single, intuitively formatted database field. It exposes all the standard tree structure relations (ancestors, parent, root, children, siblings, descendants) and all of them can be fetched in a single query. Additional features are named_scopes, integrity checking, integrity restoration, arrangement of (sub)tree into hashes and different strategies for dealing with orphaned records.'}
+  gem.description = %Q{Organise Mongoid model into a tree structure}
+  gem.email = "eagle.anton@gmail.com"
+  gem.authors = ["Stefan Kroes", "Anton Orel"]
+  gem.add_runtime_dependency('mongoid', '~> 2.0')
+  gem.add_runtime_dependency('bson_ext', '~> 1.3')
+  gem.add_development_dependency 'rspec', '~> 2.5'
+  gem.add_development_dependency 'bundler', '~> 1.0'
+  gem.add_development_dependency 'guard-rspec', '~> 0.2'
+  gem.add_development_dependency 'libnotify', '~> 0.3'
+  gem.add_development_dependency 'rb-inotify', '~> 0.8'
+  gem.add_development_dependency 'fuubar', '~> 0.0.4'
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "mongoid-ancestry #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/init.rb

@@ -0,0 +1 @@
+require 'ancestry'

data/install.rb

@@ -0,0 +1 @@
+puts "Thank you for installing Ancestry. You can visit http://github.com/stefankroes/ancestry to read the documentation."

data/lib/mongoid/ancestry/class_methods.rb

@@ -0,0 +1,233 @@
+module Mongoid
+  module Ancestry
+    module ClassMethods
+      def has_ancestry(opts = {})
+        defaults = {
+          :uid_field         => :uid,
+          :ancestry_field    => :ancestry,
+          :cache_depth       => false,
+          :depth_cache_field => :ancestry_depth,
+          :orphan_strategy   => :destroy
+        }
+
+        valid_opts = [:uid_field, :ancestry_field, :cache_depth, :depth_cache_field, :orphan_strategy]
+        unless opts.is_a?(Hash) &&  opts.keys.all? {|opt| valid_opts.include?(opt) }
+          raise Error.new("Invalid options for has_ancestry. Only hash is allowed.\n Defaults: #{defaults.inspect}")
+        end
+
+        opts.symbolize_keys!
+
+        opts.reverse_merge!(defaults)
+
+        cattr_accessor :uid_field
+        self.uid_field = opts[:uid_field]
+
+        # Create unique id field accessor and set to option or default
+        self.field uid_field, :type => Integer
+        self.index uid_field, :unique => true
+
+        # Create ancestry field accessor and set to option or default
+        cattr_accessor :ancestry_field
+        self.ancestry_field = opts[:ancestry_field]
+
+        self.field ancestry_field, :type => String
+        self.index ancestry_field
+
+        # Create orphan strategy accessor and set to option or default (writer comes from DynamicClassMethods)
+        cattr_reader :orphan_strategy
+        self.orphan_strategy = opts[:orphan_strategy]
+
+        # Validate format of ancestry column value
+        primary_key_format = opts[:primary_key_format] || /[0-9]+/
+        validates_format_of ancestry_field, :with => /\A#{primary_key_format.source}(\/#{primary_key_format.source})*\Z/, :allow_nil => true
+
+        # Validate that the ancestor ids don't include own id
+        validate :ancestry_exclude_self
+
+        # Create ancestry column accessor and set to option or default
+        if opts[:cache_depth]
+          # Create accessor for column name and set to option or default
+          self.cattr_accessor :depth_cache_field
+          self.depth_cache_field = opts[:depth_cache_field]
+
+          # Cache depth in depth cache column before save
+          before_validation :cache_depth
+
+          # Validate depth column
+          validates_numericality_of depth_cache_field, :greater_than_or_equal_to => 0, :only_integer => true, :allow_nil => false
+        end
+
+        # Create named scopes for depth
+        {:before_depth => 'lt', :to_depth => 'lte', :at_depth => nil, :from_depth => 'gte', :after_depth => 'gt'}.each do |scope_name, operator|
+          scope scope_name, lambda { |depth|
+            raise Error.new("Named scope '#{scope_name}' is only available when depth caching is enabled.") unless opts[:cache_depth]
+            where( (operator ? depth_cache_field.send(operator.to_sym) : depth_cache_field) => depth)
+          }
+        end
+
+        scope :roots, where(ancestry_field => nil)
+        scope :ancestors_of, lambda { |object| where(to_node(object).ancestor_conditions) }
+        scope :children_of, lambda { |object| where(to_node(object).child_conditions) }
+        scope :descendants_of, lambda { |object| any_of(to_node(object).descendant_conditions) }
+        scope :subtree_of, lambda { |object| any_of(to_node(object).subtree_conditions) }
+        scope :siblings_of, lambda { |object| where(to_node(object).sibling_conditions) }
+        scope :ordered_by_ancestry, asc(:"#{self.base_class.ancestry_field}")
+        scope :ordered_by_ancestry_and, lambda {|by| ordered_by_ancestry.order_by([by]) }
+
+        before_create :set_uid
+
+        # Update descendants with new ancestry before save
+        before_save :update_descendants_with_new_ancestry
+
+        # Apply orphan strategy before destroy
+        before_destroy :apply_orphan_strategy
+      end
+
+      def find_by_uid!(uid)
+        where(self.base_class.uid_field => uid).first || raise(Mongoid::Errors::DocumentNotFound.new(self, uid))
+      end
+
+      # Fetch tree node if necessary
+      def to_node object
+        object.is_a?(self.base_class) ? object : find(object)
+      end
+
+      # Scope on relative depth options
+      def scope_depth depth_options, depth
+        depth_options.inject(self.base_class) do |scope, option|
+          scope_name, relative_depth = option
+          if [:before_depth, :to_depth, :at_depth, :from_depth, :after_depth].include? scope_name
+            scope.send scope_name, depth + relative_depth
+          else
+            raise Error.new("Unknown depth option: #{scope_name}.")
+          end
+        end
+      end
+
+      # Orphan strategy writer
+      def orphan_strategy= orphan_strategy
+        # Check value of orphan strategy, only rootify, restrict or destroy is allowed
+        if [:rootify, :restrict, :destroy].include? orphan_strategy
+          class_variable_set :@@orphan_strategy, orphan_strategy
+        else
+          raise Error.new("Invalid orphan strategy, valid ones are :rootify, :restrict and :destroy.")
+        end
+      end
+
+      # Arrangement
+      def arrange options = {}
+        scope =
+          if options[:order].nil?
+            self.base_class.ordered_by_ancestry
+          else
+            self.base_class.ordered_by_ancestry_and options.delete(:order)
+          end
+        # Get all nodes ordered by ancestry and start sorting them into an empty hash
+        scope.all(options).inject(ActiveSupport::OrderedHash.new) do |arranged_nodes, node|
+          # Find the insertion point for that node by going through its ancestors
+          node.ancestor_ids.inject(arranged_nodes) do |insertion_point, ancestor_id|
+            insertion_point.each do |parent, children|
+              # Change the insertion point to children if node is a descendant of this parent
+              insertion_point = children if ancestor_id == parent.read_attribute(self.base_class.uid_field)
+            end; insertion_point
+          end[node] = ActiveSupport::OrderedHash.new; arranged_nodes
+        end
+      end
+
+      # Integrity checking
+      def check_ancestry_integrity! options = {}
+        parents = {}
+        exceptions = [] if options[:report] == :list
+        # For each node ...
+        self.base_class.all.each do |node|
+          begin
+            # ... check validity of ancestry column
+            if !node.valid? and !node.errors[node.class.ancestry_field].blank?
+              raise IntegrityError.new "Invalid format for ancestry column of node #{node.read_attribute node.uid_field}: #{node.read_attribute node.ancestry_field}."
+            end
+            # ... check that all ancestors exist
+            node.ancestor_ids.each do |ancestor_id|
+              unless where(:uid => ancestor_id).first
+                raise IntegrityError.new "Reference to non-existent node in node #{node.read_attribute node.uid_field}: #{ancestor_id}."
+              end
+            end
+            # ... check that all node parents are consistent with values observed earlier
+            node.path_ids.zip([nil] + node.path_ids).each do |node_id, parent_id|
+              parents[node_id] = parent_id unless parents.has_key? node_id
+              unless parents[node_id] == parent_id
+                raise IntegrityError.new "Conflicting parent id found in node #{node.read_attribute node.uid_field}: #{parent_id || 'nil'} for node #{node_id} while expecting #{parents[node_id] || 'nil'}"
+              end
+            end
+          rescue IntegrityError => integrity_exception
+            case options[:report]
+            when :list then exceptions << integrity_exception
+            when :echo then puts integrity_exception
+            else raise integrity_exception
+            end
+          end
+        end
+        exceptions if options[:report] == :list
+      end
+
+      # Integrity restoration
+      def restore_ancestry_integrity!
+        parents = {}
+        # For each node ...
+        self.base_class.all.each do |node|
+          # ... set its ancestry to nil if invalid
+          if node.errors[node.class.ancestry_field].blank?
+            node.without_ancestry_callbacks do
+              node.update_attribute node.ancestry_field, nil
+            end
+          end
+          # ... save parent of this node in parents array if it exists
+          parents[node.read_attribute(node.uid_field)] = node.parent_id if exists? node.parent_id
+
+          # Reset parent id in array to nil if it introduces a cycle
+          parent = parents[node.read_attribute(node.uid_field)]
+          until parent.nil? || parent == node.read_attribute(node.uid_field)
+            parent = parents[parent]
+          end
+          parents[node.read_attribute(node.uid_field)] = nil if parent == node.read_attribute(node.uid_field)
+        end
+        # For each node ...
+        self.base_class.all.each do |node|
+          # ... rebuild ancestry from parents array
+          ancestry, parent = nil, parents[node.read_attribute(node.uid_field)]
+          until parent.nil?
+            ancestry, parent = if ancestry.nil? then parent else "#{parent}/#{ancestry}" end, parents[parent]
+          end
+          node.without_ancestry_callbacks do
+            node.update_attribute node.ancestry_field, ancestry
+          end
+        end
+      end
+
+      # Build ancestry from parent id's for migration purposes
+      def build_ancestry_from_parent_ids! parent_id = nil, ancestry = nil
+        self.base_class.where(:parent_id => parent_id).all.each do |node|
+          node.without_ancestry_callbacks do
+            retries = 3
+            begin
+              node.set_uid
+              node.send(:"#{ancestry_field}=", ancestry)
+              node.save!
+            rescue Mongo::OperationFailure => e
+              (retries -= 1) > 0 && e.to_s =~ %r{duplicate key error.+\$#{self.base_class.uid_field}} ? retry : raise(e)
+            end
+          end
+          build_ancestry_from_parent_ids! node.id,
+            if ancestry.nil? then "#{node.read_attribute(self.base_class.uid_field)}" else "#{ancestry}/#{node.read_attribute(self.base_class.uid_field)}" end
+        end
+      end
+
+      # Rebuild depth cache if it got corrupted or if depth caching was just turned on
+      def rebuild_depth_cache!
+        raise Error.new("Cannot rebuild depth cache for model without depth caching.") unless respond_to? :depth_cache_field
+        self.base_class.all.each do |node|
+          node.update_attribute depth_cache_field, node.depth
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/ancestry/exceptions.rb

@@ -0,0 +1,6 @@
+module Mongoid
+  module Ancestry
+    class Error < RuntimeError; end
+    class IntegrityError < RuntimeError; end
+  end
+end