Fix order of arguments to .equals and comparator (#467)

* Ensure the left & right arguments to equals() always correspond to old and new values respectively

* Add test

* Add release notes

Author: ExplodingCabbage

release-notes.md

@@ -8,7 +8,8 @@
 - [#439](https://github.com/kpdecker/jsdiff/pull/439) Prefer diffs that order deletions before insertions. When faced with a choice between two diffs with an equal total edit distance, the Myers diff algorithm generally prefers one that does deletions before insertions rather than insertions before deletions. For instance, when diffing `abcd` against `acbd`, it will prefer a diff that says to delete the `b` and then insert a new `b` after the `c`, over a diff that says to insert a `c` before the `b` and then delete the existing `c`. JsDiff deviated from the published Myers algorithm in a way that led to it having the opposite preference in many cases, including that example. This is now fixed, meaning diffs output by JsDiff will more accurately reflect what the published Myers diff algorithm would output.
 - [#455](https://github.com/kpdecker/jsdiff/pull/455) The `added` and `removed` properties of change objects are now guaranteed to be set to a boolean value. (Previously, they would be set to `undefined` or omitted entirely instead of setting them to false.)
 - [#464](https://github.com/kpdecker/jsdiff/pull/464) Specifying `{maxEditLength: 0}` now sets a max edit length of 0 instead of no maximum.
-- [#460][https://github.com/kpdecker/jsdiff/pull/460] Added `oneChangePerToken` option.
+- [#460](https://github.com/kpdecker/jsdiff/pull/460) Added `oneChangePerToken` option.
+- [#467](https://github.com/kpdecker/jsdiff/pull/467) When passing a `comparator(left, right)` to `diffArrays`, values from the old array will now consistently be passed as the first argument (`left`) and values from the new array as the second argument (`right`). Previously this was almost (but not quite) always the other way round.
 
 ## Development
 

src/diff/base.js

@@ -166,7 +166,7 @@ Diff.prototype = {
         newPos = oldPos - diagonalPath,
 
         commonCount = 0;
-    while (newPos + 1 < newLen && oldPos + 1 < oldLen && this.equals(newString[newPos + 1], oldString[oldPos + 1])) {
+    while (newPos + 1 < newLen && oldPos + 1 < oldLen && this.equals(oldString[oldPos + 1], newString[newPos + 1])) {
       newPos++;
       oldPos++;
       commonCount++;
@@ -259,10 +259,15 @@ function buildValues(diff, lastComponent, newString, oldString, useLongestToken)
   // For this case we merge the terminal into the prior string and drop the change.
   // This is only available for string mode.
   let finalComponent = components[componentLen - 1];
-  if (componentLen > 1
-      && typeof finalComponent.value === 'string'
-      && (finalComponent.added || finalComponent.removed)
-      && diff.equals('', finalComponent.value)) {
+  if (
+    componentLen > 1
+    && typeof finalComponent.value === 'string'
+    && (
+      (finalComponent.added && diff.equals('', finalComponent.value))
+      ||
+      (finalComponent.removed && diff.equals(finalComponent.value, ''))
+    )
+  ) {
     components[componentLen - 2].value += finalComponent.value;
     components.pop();
   }

test/diff/array.js

@@ -75,5 +75,18 @@ describe('diff/array', function() {
           {count: 1, value: [d], removed: false, added: true}
       ]);
     });
+    it('Should pass old/new tokens as the left/right comparator args respectively', function() {
+      diffArrays(
+        ['a', 'b', 'c'],
+        ['x', 'y', 'z'],
+        {
+          comparator: function(left, right) {
+            expect(left).to.be.oneOf(['a', 'b', 'c']);
+            expect(right).to.be.oneOf(['x', 'y', 'z']);
+            return left === right;
+          }
+        }
+      );
+    });
   });
 });