lorax 0.1.0

data/lib/lorax/fast_matcher.rb

@@ -0,0 +1,108 @@
+module Lorax
+  class FastMatcher
+    attr_accessor :match_set
+
+    def initialize(doc1, doc2, dependency_injection={})
+      @document1 = doc1
+      @document2 = doc2
+      @match_set = dependency_injection[:matcher_match_set] || MatchSet.new(doc1, doc2, dependency_injection)
+    end
+
+    def match
+      match_node @document1.root
+    end
+
+    private
+
+    def match_node(node1)
+      return if match_set.match(node1)
+      signature1 = match_set.signature1.signature(node1) # assumes node1 is in signature1
+      candidates = match_set.signature2.nodes(signature1) || []
+      candidates.reject! { |node| match_set.match(node) }
+
+      if candidates.empty?
+        node1.children.each do |child|
+          match_node(child)
+        end
+        match = match_set.match(node1)
+        propagate_to_children(match.pair.first, match.pair.last) if match
+      else
+        match_candidate(node1, candidates)
+      end
+      propagate_to_parent(node1) unless match_set.match(node1)
+      match_set
+    end
+
+    def match_candidate(node1, candidates)
+      ancestral_matches = candidates.collect do |node2|
+        ancestral_match(node1, node2, depth(node2, match_set.signature2))
+      end
+      longest_trail = ancestral_matches.max { |a, b| a.length <=> b.length }
+      longest_trail.each do |ancestral_match|
+        match_set.add ancestral_match
+      end
+    end
+
+    def ancestral_match(node1, node2, max_depth)
+      matches = [Match.new(node1, node2, :perfect => true)]
+      curr1, curr2 = node1.parent, node2.parent
+      1.upto(max_depth) do
+        break unless curr1.name == curr2.name && ! curr1.is_a?(Nokogiri::XML::Document)
+        matches << Match.new(curr1, curr2)
+        curr1, curr2 = curr1.parent, curr2.parent
+      end
+      matches
+    end
+
+    def propagate_to_parent(node1)
+      node1.children.sort_by { |child| match_set.signature1.weight(child) }.reverse.each do |child|
+        next unless match = match_set.match(child)
+        match_parent = match.pair.last.parent
+        if match_parent.name == node1.name
+          match_set.add Match.new(node1, match_parent)
+          return
+        end
+      end
+    end
+
+    def propagate_to_children(node1, node2)
+      # TODO: OMG! MY EYES ARE BLEEDING! REFACTOR ME AND OPTIMIZE ME!
+      children_set1 = collect_children_by_name(node1.children)
+      children_set2 = collect_children_by_name(node2.children)
+
+      children_set1.each do |name1, children1|
+        children_set2.each do |name2, children2|
+          next unless name1 == name2
+          if children1.length == 1 && children2.length == 1
+            match_set.add Match.new(children1.first, children2.first)
+            propagate_to_children children1.first, children2.first
+          else
+            children1.each do |child1|
+              children2.each do |child2|
+                if node1.children.index(child1) == node2.children.index(child2)
+                  match_set.add Match.new(child1, child2)
+                  propagate_to_children child1, child2
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+
+    def depth(node, sig)
+      depth = 1 + Math.log(sig.size) * sig.weight(node) / sig.weight
+      # puts "lorax: debug: #{__FILE__}:#{__LINE__}: depth #{depth} = 1 + #{Math.log(sig.size)} * #{sig.weight(node)} / #{sig.weight}"
+      depth.to_i
+    end
+
+    def collect_children_by_name(node_set)
+      collection = {}
+      node_set.each do |child|
+        next if match_set.match(child)
+        (collection[child.name] ||= []) << child
+      end
+      collection
+    end
+  end
+end

data/lib/lorax/match.rb

@@ -0,0 +1,22 @@
+module Lorax
+  class Match
+    attr_accessor :pair
+
+    def initialize(node1, node2, options={})
+      @pair    = [node1, node2]
+      @perfect = options[:perfect] ? true : false
+    end
+
+    def perfect?
+      @perfect
+    end
+
+    def other(node)
+      case node
+      when pair.first then pair.last
+      when pair.last then pair.first
+      else nil
+      end
+    end
+  end
+end

data/lib/lorax/match_set.rb

@@ -0,0 +1,30 @@
+module Lorax
+  class MatchSet
+    attr_accessor :signature1, :signature2
+
+    def initialize(doc1, doc2, dependency_injection={})
+      @document1  = doc1
+      @document2  = doc2
+      @signature1 = dependency_injection[:match_set_signature1] || Lorax::Signature.new(@document1.root)
+      @signature2 = dependency_injection[:match_set_signature2] || Lorax::Signature.new(@document2.root)
+      @matches    = {}
+    end
+
+    def match(node)
+      @matches[node]
+    end
+
+    def matches
+      puts "MIKE: #{__FILE__}:#{__LINE__} REMOVE ME THIS IS FOR DEBUGGING ONLY"
+      @matches.values.uniq.collect {|m| [m.pair.first.path, m.pair.last.path, m.perfect?]}.sort
+    end
+
+    def add(match)
+      match.pair.each { |node| @matches[node] = match }
+    end
+
+    def to_delta_set
+      DeltaSetGenerator.generate_delta_set(self)
+    end
+  end
+end

data/lib/lorax/signature.rb

@@ -0,0 +1,101 @@
+require 'digest/sha1'
+
+module Lorax
+  class Signature
+    SEP = "\0"
+
+    def initialize(node=nil)
+      @signatures = {} # node      => signature
+      @monograms  = {} # node      => monogram (signature not including children)
+      @nodes      = {} # signature => [node, ...]
+      @weights    = {} # node      => weight
+      @size       = 0
+      @node       = node
+      signature(node) if node
+    end
+
+    def root
+      @node
+    end
+
+    def nodes(sig=nil)
+      sig ? @nodes[sig] : @node
+    end
+
+    def size
+      @size
+    end
+
+    def signature(node=@node)
+      return @signatures[node] if @signatures.key?(node)
+      raise ArgumentError, "signature expects a Node, but received #{node.inspect}" unless node.is_a?(Nokogiri::XML::Node)
+
+      if node.text? || node.cdata? || node.comment?
+        monogram     = signature = hashify(node.content)
+      elsif node.type == Nokogiri::XML::Node::ENTITY_REF_NODE
+        monogram     = signature = hashify(node.to_html)
+      elsif node.element?
+        children_sig = hashify(node.children       .collect { |child| signature(child) })
+        attr_sig     = hashify(node.attributes.sort.collect { |k,v|   [k, v.value]     }.flatten)
+        monogram     = hashify(node.name, attr_sig)
+        signature    = hashify(node.name, attr_sig, children_sig)
+      else
+        raise ArgumentError, "signature expects an element, text, cdata or comment node, but received #{node.class}"
+      end
+
+      @size += 1
+      weight(node)
+
+      (@nodes[signature] ||= []) << node
+      @monograms[node]           =  monogram
+      @signatures[node]          =  signature
+    end
+
+    def weight(node=@node)
+      return @weights[node] if @weights.key?(node)
+      raise ArgumentError, "weight expects a Node, but received #{node.inspect}" unless node.is_a?(Nokogiri::XML::Node)
+
+      calculated_weight = \
+        if node.text? || node.cdata? || node.comment?
+          1 + Math.log(node.content.length)
+        elsif node.type == Nokogiri::XML::Node::ENTITY_REF_NODE
+          1
+        elsif node.element?
+          node.children.inject(1) { |sum, child| sum += weight(child) }
+        else
+          raise ArgumentError, "weight expects an element, text, cdata or comment node, but received #{node.class}"
+        end
+
+      @weights[node] = calculated_weight
+    end
+
+    def monogram(node=@node)
+      return @monograms[node] if @monograms.key?(node)
+      signature(node)
+      @monograms[node]
+    end
+
+    def set_signature(node, value) # :nodoc: for testing
+      (@nodes[value] ||= []) << node
+      @signatures[node]      =  value
+    end
+
+    def set_weight(node, value) # :nodoc: for testing
+      @weights[node] = value
+    end
+
+    private
+
+    def hashify(*args)
+      if args.length == 1
+        if args.first.is_a?(Array)
+          Digest::SHA1.hexdigest args.first.join(SEP)
+        else
+          Digest::SHA1.hexdigest args.first
+        end
+      else
+        Digest::SHA1.hexdigest args.join(SEP)
+      end
+    end
+  end
+end

data/spec/fast_matcher_spec.rb

@@ -0,0 +1,400 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe Lorax::FastMatcher do
+  describe ".new" do
+    context "normal usage" do
+      it "takes two arguments" do
+        proc { Lorax::FastMatcher.new(xml{root})            }.should     raise_error(ArgumentError)
+        proc { Lorax::FastMatcher.new(xml{root}, xml{root}) }.should_not raise_error(ArgumentError)
+      end
+
+      it "builds a MatchSet for the documents" do
+        doc1 = xml { root1 }
+        doc2 = xml { root2 }
+        mock.proxy(Lorax::MatchSet).new(doc1, doc2, anything)
+        Lorax::FastMatcher.new(doc1, doc2)
+      end
+    end
+
+    context "dependency injection" do
+      it "takes an optional third argument for dependency injection" do
+        proc { Lorax::FastMatcher.new(xml{root}, xml{root}, {:foo => :bar}) }.should_not raise_error(ArgumentError)
+      end
+
+      it "will use the value of ':matcher_match_set' for @match_set" do
+        matcher = Lorax::FastMatcher.new(xml{root}, xml{root}, {:matcher_match_set => :foo})
+        matcher.match_set.should == :foo
+      end
+    end
+  end
+
+  describe "basic node matching" do
+    context "simple matches" do
+      before do
+        @doc1 = xml { root1 {
+            a1
+            b1
+          } }
+        @doc2 = xml { root2 {
+            a1
+            b2
+          } }
+        @signature1 = Lorax::Signature.new(@doc1.root)
+        @signature1.set_signature(@doc1.at_css("root1"), "root1")
+        @signature1.set_signature(@doc1.at_css("a1"), "a1")
+        @signature1.set_signature(@doc1.at_css("b1"), "b1")
+        @signature2 = Lorax::Signature.new(@doc2.root)
+        @signature2.set_signature(@doc2.at_css("root2"), "root2")
+        @signature2.set_signature(@doc2.at_css("a1"), "a1")
+        @signature2.set_signature(@doc2.at_css("b2"), "b2")
+      end
+
+      it "matches identical nodes" do
+        match_set = Lorax::FastMatcher.new(@doc1, @doc2,
+          :match_set_signature1 => @signature1,
+          :match_set_signature2 => @signature2).match
+        assert_perfect_match_exists match_set, @doc1.at_css("a1"), @doc2.at_css("a1")
+      end
+
+      it "does not match different nodes" do
+        match_set = Lorax::FastMatcher.new(@doc1, @doc2,
+          :match_set_signature1 => @signature1,
+          :match_set_signature2 => @signature2).match
+        assert_no_match_exists match_set, @doc1.at_css("b1"), @doc2.at_css("b2")
+      end
+    end
+
+    context "sibling matches" do
+      it "matches all identical siblings" do
+        doc1 = xml { root {
+            a1_1 ; a1_3 ; a1_5
+          } }
+        doc2 = xml { root {
+            a2_1 ; a2_2 ; a2_3 ; a2_4 ; a2_5
+          } }
+        signature1 = Lorax::Signature.new(doc1.root)
+        signature1.set_signature(doc1.at_css("a1_1"), "a1")
+        signature1.set_signature(doc1.at_css("a1_3"), "a3")
+        signature1.set_signature(doc1.at_css("a1_5"), "a5")
+
+        signature2 = Lorax::Signature.new(doc2.root)
+        signature2.set_signature(doc2.at_css("a2_1"), "a1")
+        signature2.set_signature(doc2.at_css("a2_3"), "a3")
+        signature2.set_signature(doc2.at_css("a2_5"), "a5")
+
+        match_set = Lorax::FastMatcher.new(doc1, doc2,
+          :match_set_signature1 => signature1, :match_set_signature2 => signature2).match
+        assert_perfect_match_exists match_set, doc1.at_css("a1_1"), doc2.at_css("a2_1")
+        assert_perfect_match_exists match_set, doc1.at_css("a1_3"), doc2.at_css("a2_3")
+        assert_perfect_match_exists match_set, doc1.at_css("a1_5"), doc2.at_css("a2_5")
+      end
+    end
+
+    context "matching children of an unmatched node" do
+      it "matches those children" do
+        doc1 = xml { root {
+            a1 {
+              b1 ; b2
+            }
+          } }
+        doc2 = xml { root {
+            a2 {
+              b1 ; b2
+            }
+          } }
+        signature1 = Lorax::Signature.new(doc1.root)
+        signature1.set_signature(doc1.at_css("a1"), "a1")
+        signature1.set_signature(doc1.at_css("b1"), "b1")
+        signature1.set_signature(doc1.at_css("b2"), "b2")
+
+        signature2 = Lorax::Signature.new(doc2.root)
+        signature1.set_signature(doc2.at_css("a2"), "a2")
+        signature2.set_signature(doc2.at_css("b1"), "b1")
+        signature2.set_signature(doc2.at_css("b2"), "b2")
+
+        match_set = Lorax::FastMatcher.new(doc1, doc2,
+          :match_set_signature1 => signature1, :match_set_signature2 => signature2).match
+        assert_perfect_match_exists match_set, doc1.at_css("b1"), doc2.at_css("b1")
+        assert_perfect_match_exists match_set, doc1.at_css("b2"), doc2.at_css("b2")
+      end
+    end
+
+    context "nested matches" do
+      before do
+        @doc1 = xml { root1 { a1 { b1 } } }
+        @doc2 = xml { root2 { a1 { b1 } } }
+        @signature1 = Lorax::Signature.new(@doc1.root)
+        @signature1.set_signature(@doc1.at_css("a1"), "a1")
+        @signature1.set_signature(@doc1.at_css("b1"), "b1")
+        @signature2 = Lorax::Signature.new(@doc2.root)
+        @signature2.set_signature(@doc2.at_css("a1"), "a1")
+        @signature2.set_signature(@doc2.at_css("b1"), "b2")
+      end
+
+      it "matches the root nodes of the largest identical subtree" do
+        match_set = Lorax::FastMatcher.new(@doc1, @doc2,
+          :match_set_signature1 => @signature1, :match_set_signature2 => @signature2).match
+        assert_perfect_match_exists match_set, @doc1.at_css("a1"), @doc2.at_css("a1")
+      end
+
+      it "does not match children of identical match nodes" do
+        match_set = Lorax::FastMatcher.new(@doc1, @doc2,
+          :match_set_signature1 => @signature1, :match_set_signature2 => @signature2).match
+        assert_no_match_exists match_set, @doc1.at_css("b1"), @doc2.at_css("b1")
+      end
+    end
+  end
+
+  describe "forced parent matching" do
+    before do
+      stub.instance_of(Lorax::FastMatcher).propagate_to_parent # we're not testing propagation to parent
+    end
+
+    it "forces a match when parent names are the same but attributes are different" do
+      doc1 = xml { root { a1(:foo => "bar")   { b1 } } }
+      doc2 = xml { root { a1(:bazz => "quux") { b1 } } }
+      match_set = Lorax::FastMatcher.new(doc1, doc2).match
+      assert_perfect_match_exists match_set, doc1.at_css("b1"), doc2.at_css("b1")
+      assert_forced_match_exists  match_set, doc1.at_css("a1"), doc2.at_css("a1")
+    end
+
+    it "forces a match when parent names and attributes are the same but siblings are different" do
+      doc1 = xml { root { a1(:foo => "bar") { b1 ; b2 } } }
+      doc2 = xml { root { a1(:foo => "bar") { b1 ; b3 } } }
+      match_set = Lorax::FastMatcher.new(doc1, doc2).match
+      assert_perfect_match_exists match_set, doc1.at_css("b1"), doc2.at_css("b1")
+      assert_forced_match_exists  match_set, doc1.at_css("a1"), doc2.at_css("a1")
+    end
+
+    describe "subsequent forced child matching" do
+      it "force matches a uniquely-named sibling" do
+        doc1 = xml { root { a1 {
+              b2 "goodbye"
+              b1 "hello"
+              b3
+              b4
+            } } }
+        doc2 = xml { root { a1 {
+              b2 "good boy"
+              b1 "hello"
+              b3 "something"
+              b4 { c1 }
+            } } }
+        match_set = Lorax::FastMatcher.new(doc1, doc2).match
+        assert_perfect_match_exists match_set, doc1.at_css("b1"), doc2.at_css("b1")
+        assert_forced_match_exists  match_set, doc1.at_css("a1"), doc2.at_css("a1")
+        assert_forced_match_exists  match_set, doc1.at_css("b2"), doc2.at_css("b2")
+        assert_forced_match_exists  match_set, doc1.at_css("b3"), doc2.at_css("b3")
+        assert_forced_match_exists  match_set, doc1.at_css("b4"), doc2.at_css("b4")
+      end
+
+      it "force matches recursively" do
+        doc1 = xml { root { a1 ; a2 { b2 "hello" } } }
+        doc2 = xml { root { a1 ; a2 { b2 "goodbye" } } }
+        match_set = Lorax::FastMatcher.new(doc1, doc2).match
+        assert_perfect_match_exists match_set, doc1.at_css("a1"), doc2.at_css("a1")
+        assert_forced_match_exists  match_set, doc1.at_css("a2"), doc2.at_css("a2")
+        assert_forced_match_exists  match_set, doc1.at_css("b2"), doc2.at_css("b2")
+        assert_forced_match_exists  match_set, doc1.at_xpath("//b2/text()"), doc2.at_xpath("//b2/text()")
+      end
+
+      it "should match uniquely-named unmatched children" do
+        doc1 = xml { root {
+            a1 "hello"
+            a2 "goodbye"
+            a3 "natch"
+          } }
+        doc2 = xml { root {
+            a1 "hello"
+            a3 "not"
+          } }
+        match_set = Lorax::FastMatcher.new(doc1, doc2).match
+        assert_perfect_match_exists match_set, doc1.at_css("a1"), doc2.at_css("a1")
+        assert_forced_match_exists match_set,  doc1.at_css("a3"), doc2.at_css("a3")
+      end
+
+      it "should match same-named children in the same position, even if they are not uniquely named" do
+        doc1 = xml { root {
+            a1 {
+              text "hello"
+              b1 "foo"
+              text "goodbye"
+            }
+          } }
+        doc2 = xml { root {
+            a1 {
+              text "bonjour"
+              b1 "foo"
+              text "au revoir"
+            }
+          } }
+        match_set = Lorax::FastMatcher.new(doc1, doc2).match
+        assert_forced_match_exists match_set, doc1.at_xpath("/root/a1/text()[1]"), doc2.at_xpath("/root/a1/text()[1]")
+        assert_forced_match_exists match_set, doc1.at_xpath("/root/a1/text()[2]"), doc2.at_xpath("/root/a1/text()[2]")
+      end
+
+      it "large subtree matches force more parent matches than smaller subtree matches" do
+        small_doc1 = xml { root { a1 { b1 { c1 { d1 { e1 {
+                      f1
+                      f2
+                    } } } } } } }
+        small_doc2 = xml { root { a1 { b1 { c1 { d1 { e1 {
+                      f1
+                      f3
+                    } } } } } } }
+        large_doc1 = xml { root { a1 { b1 { c1 { d1 { e1 {
+                      f1
+                      f2
+                    } } } } } } }
+        large_doc2 = xml { root { a1 { b1 { c1 { d1 { e1 {
+                      f1
+                      f3
+                    } } } } } } }
+
+        small_signature1 = Lorax::Signature.new(small_doc1.root)
+        small_signature1.set_weight(small_doc1.at_css("f1"), 1)
+        small_signature2 = Lorax::Signature.new(small_doc2.root)
+        small_signature2.set_weight(small_doc2.at_css("f1"), 1)
+        large_signature1 = Lorax::Signature.new(large_doc1.root)
+        large_signature1.set_weight(large_doc1.at_css("f1"), 10)
+        large_signature2 = Lorax::Signature.new(large_doc2.root)
+        large_signature2.set_weight(large_doc2.at_css("f1"), 10)
+
+        small_match_set = Lorax::FastMatcher.new(small_doc1, small_doc2,
+          :match_set_signature1 => small_signature1, :match_set_signature2 => small_signature2).match
+        large_match_set = Lorax::FastMatcher.new(large_doc1, large_doc2,
+          :match_set_signature1 => large_signature1, :match_set_signature2 => large_signature2).match
+
+        assert_forced_match_exists small_match_set, small_doc1.at_css("e1"), small_doc2.at_css("e1")
+        assert_no_match_exists     small_match_set, small_doc1.at_css("d1"), small_doc2.at_css("d1")
+
+        assert_forced_match_exists large_match_set, large_doc1.at_css("e1"), large_doc2.at_css("e1")
+        assert_forced_match_exists large_match_set, large_doc1.at_css("d1"), large_doc2.at_css("d1")
+        assert_forced_match_exists large_match_set, large_doc1.at_css("c1"), large_doc2.at_css("c1")
+        assert_no_match_exists     large_match_set, large_doc1.at_css("b1"), large_doc2.at_css("b1")
+      end
+    end
+  end
+
+  describe "propagating matches to unmatched parents based on children's matches' parents" do
+    context "when there is only one child" do
+      it "should match parents all the way up the tree" do
+        doc1 = xml { root { a1 { b1 { c1 { d1 { e1 {
+                      f1 "hello"
+                      f2
+                    } } } } } } }
+        doc2 = xml { root { a1 { b1 { c1 { d1 { e1 {
+                      f1 "hello"
+                      f3
+                    } } } } } } }
+        match_set = Lorax::FastMatcher.new(doc1, doc2).match
+        assert_perfect_match_exists match_set, doc1.at_css("f1"), doc2.at_css("f1")
+        %w[e1 d1 c1 b1 a1 root].each do |node_name|
+          assert_forced_match_exists match_set, doc1.at_css(node_name), doc2.at_css(node_name)
+        end
+      end
+    end
+
+    context "there are many possible children" do
+      it "should match via children with largest weight" do
+        doc1 = xml { root {
+            a1 { b1 ; b2 }
+          } }
+        doc2 = xml { root {
+            a1 { b1 ; b3 }
+            a1 { b2 ; b4 }
+          } }
+        signature1 = Lorax::Signature.new(doc1.root)
+        signature2 = Lorax::Signature.new(doc2.root)
+        signature1.set_weight(doc1.at_css("b1"), 10)
+        signature1.set_weight(doc1.at_css("b2"), 100)
+        signature2.set_weight(doc2.at_css("b1"), 10)
+        signature2.set_weight(doc2.at_css("b2"), 100)
+
+        match_set = Lorax::MatchSet.new(doc1, doc2, :match_set_signature1 => signature1, :match_set_signature2 => signature2)
+        match_set.add Lorax::Match.new(doc1.at_css("b1"), doc2.at_css("b1"))
+        match_set.add Lorax::Match.new(doc1.at_css("b2"), doc2.at_css("b2"))
+
+        match_set = Lorax::FastMatcher.new(doc1, doc2, :matcher_match_set => match_set).match
+        assert_forced_match_exists match_set, doc1.at_css("a1"), doc2.at_xpath("//a1[2]")
+      end
+    end
+  end
+
+  describe "choosing the best among multiple possible matches" do
+    context "no match's parent is same-named" do
+      it "we don't care which node we match, just pick one" do
+        doc1 = xml { root {
+            a1 { b1 }
+          } }
+        doc2 = xml { root {
+            a2 { b1 }
+            a3 { b1 }
+          } }
+        signature1 = Lorax::Signature.new(doc1.root)
+        signature2 = Lorax::Signature.new(doc2.root)
+        signature1.set_signature(doc1.at_xpath("//b1"),    "b1")
+        signature2.set_signature(doc2.at_xpath("//a2/b1"), "b1")
+        signature2.set_signature(doc2.at_xpath("//a3/b1"), "b1")
+        match_set = Lorax::FastMatcher.new(doc1, doc2,
+          :match_set_signature1 => signature1, :match_set_signature2 => signature2).match
+        match_set.match(doc1.at_css("b1")).other(doc1.at_css("b1")).name.should == "b1"
+      end
+    end
+
+    context "one match's parent is same-named" do
+      it "matches the node with the same-named parent" do
+        doc1 = xml { root {
+            a2 { b1 ; b2 }
+          } }
+        doc2 = xml { root {
+            a1 { b1 }
+            a2 { b1 }
+            a3 { b1 }
+          } }
+        match_set = Lorax::FastMatcher.new(doc1, doc2).match
+        assert_forced_match_exists match_set, doc1.at_css("a2"), doc2.at_css("a2")
+      end
+    end
+
+    context "multiple identical nodes exist in both documents" do
+      it "should create one-to-one match relationships" do
+        doc1 = xml { root1 {
+            a1 ; a1 ; a1
+          } }
+        doc2 = xml { root2 {
+            a1 ; a1
+          } }
+        match_set = Lorax::FastMatcher.new(doc1, doc2).match
+        [doc1, doc2].each do |doc|
+          others = doc.css("a1").collect do |node|
+            m = match_set.match(node)
+            m ? m.pair.last : nil
+          end
+          others.uniq.length.should == others.length
+        end
+      end
+    end
+
+    context "multiple matches' parents are same-named" do
+      it "matches the node with the same-named grandparent" do
+        doc1 = xml { root {
+            wrap2 {
+              a1 { b1 { 10.times { c1 "hello there" } } ; b2 }
+            } } }
+        doc2 = xml { root {
+            wrap1 {
+              a1 { b1 { 10.times { c1 "hello there" } } }
+            }
+            wrap2 {
+              a1 { b1 { 10.times { c1 "hello there" } } }
+            }
+            wrap3 {
+              a1 { b1 { 10.times { c1 "hello there" } } }
+            } } }
+        match_set = Lorax::FastMatcher.new(doc1, doc2).match
+        assert_forced_match_exists match_set, doc1.at_css("wrap2"), doc2.at_css("wrap2")
+      end
+    end
+  end
+end