object-diagram-js-differ 1.0.0

package/.eslintignore

@@ -0,0 +1 @@
+dist

package/.eslintrc

@@ -0,0 +1,3 @@
+{
+  "extends": "plugin:bpmn-io/recommended"
+}

package/.github/workflows/CI.yml

@@ -0,0 +1,32 @@
+name: CI
+on: [ push, pull_request ]
+jobs:
+  Build:
+
+    strategy:
+      matrix:
+        os: [ ubuntu-latest ]
+        node-version: [ 20 ]
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+    - name: Use Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ matrix.node-version }}
+    - name: Cache Node.js modules
+      uses: actions/cache@v3
+      with:
+        # npm cache files are stored in `~/.npm` on Linux/macOS
+        path: ~/.npm
+        key: ${{ runner.OS }}-node-${{ hashFiles('**/package-lock.json') }}
+        restore-keys: |
+          ${{ runner.OS }}-node-
+          ${{ runner.OS }}-
+    - name: Install dependencies
+      run: npm ci
+    - name: Build
+      run: npm run all

package/README.md

@@ -0,0 +1,5 @@
+Diffing for object diagrams adapted from bpmn-js-differ.
+
+## License
+
+MIT

package/lib/change-handler.js

@@ -0,0 +1,87 @@
+/* eslint no-cond-assign: 0 */
+
+function is(element, type) {
+  return element.$instanceOf(type);
+}
+
+function isAny(element, types) {
+  return types.some(function(t) {
+    return is(element, t);
+  });
+}
+
+function isTracked(element) {
+
+  const track = isAny(element, [
+    'od:OdBoard',
+    'od:Object',
+    'od:Link',
+  ]);
+
+  if (track) {
+    return {
+      element: element,
+      property: ''
+    };
+  }
+}
+
+export default function ChangeHandler() {
+  this._layoutChanged = {};
+  this._changed = {};
+  this._removed = {};
+  this._added = {};
+}
+
+
+ChangeHandler.prototype.removed = function(model, property, element, idx) {
+
+  let tracked;
+
+  if (tracked = isTracked(element)) {
+    if (!this._removed[tracked.element.id]) {
+      this._removed[tracked.element.id] = element;
+    }
+  } else
+
+    if (tracked = isTracked(model)) {
+      this.changed(tracked.element, tracked.property + property + '[' + idx + ']', null, element);
+    }
+};
+
+ChangeHandler.prototype.changed = function(model, property, newValue, oldValue) {
+
+  let tracked;
+
+  if (tracked = isTracked(model)) {
+    let changed = this._changed[tracked.element.id];
+
+    if (!changed) {
+      changed = this._changed[tracked.element.id] = { model: model, attrs: { } };
+    }
+
+    if (oldValue !== undefined || newValue !== undefined) {
+      changed.attrs[property] = { oldValue: oldValue, newValue: newValue };
+    }
+  }
+};
+
+ChangeHandler.prototype.added = function(model, property, element, idx) {
+
+  let tracked;
+
+  if (tracked = isTracked(element)) {
+    if (!this._added[tracked.element.id]) {
+      this._added[tracked.element.id] = element;
+    }
+  } else
+
+    if (tracked = isTracked(model)) {
+      this.changed(tracked.element, tracked.property + property + '[' + idx + ']', element, null);
+    }
+};
+
+ChangeHandler.prototype.moved = function(model, property, oldIndex, newIndex) {
+
+  // noop
+};

package/lib/diff.js

@@ -0,0 +1,5 @@
+import Differ from './differ.js';
+
+export default function diff(a, b, handler) {
+  return new Differ().diff(a, b, handler);
+}

package/lib/differ.js

@@ -0,0 +1,102 @@
+import {
+  forEach,
+  reduce,
+  isArray
+} from 'min-dash';
+
+import {
+  DiffPatcher
+} from 'jsondiffpatch';
+
+import ChangeHandler from './change-handler.js';
+
+
+export default function Differ() { }
+
+
+Differ.prototype.createDiff = function(a, b) {
+
+  // create a configured instance, match objects by name
+  const diffpatcher = new DiffPatcher({
+    objectHash: function(obj) {
+      return obj.id || JSON.stringify(obj);
+    },
+    propertyFilter: function(name, context) {
+      return name !== '$instanceOf';
+    }
+  });
+
+  return diffpatcher.diff(a, b);
+};
+
+
+Differ.prototype.diff = function(a, b, handler) {
+
+  handler = handler || new ChangeHandler();
+
+  function walk(diff, model) {
+
+    forEach(diff, function(d, key) {
+
+      if (d._t !== 'a' && isArray(d)) {
+
+        // take into account that collection properties are lazily
+        // initialized; this means that adding to an empty collection
+        // looks like setting an undefined variable to []
+        //
+        // ensure we detect this case and change it to an array diff
+        if (isArray(d[0])) {
+
+          d = reduce(d[0], function(newDelta, element, idx) {
+            const prefix = d.length === 3 ? '_' : '';
+
+            newDelta[prefix + idx] = [ element ];
+
+            return newDelta;
+          }, { _t: 'a' });
+        }
+
+      }
+
+
+      // is array
+      if (d._t === 'a') {
+
+        forEach(d, function(val, idx) {
+
+          if (idx === '_t') {
+            return;
+          }
+
+          const removed = /^_/.test(idx),
+                added = !removed && isArray(val),
+                moved = removed && val[0] === '';
+
+          idx = parseInt(removed ? idx.slice(1) : idx, 10);
+
+          if (added || (removed && !moved)) {
+            handler[removed ? 'removed' : 'added'](model, key, val[0], idx);
+          } else
+            if (moved) {
+              handler.moved(model, key, val[1], val[2]);
+            } else {
+              walk(val, model[key][idx]);
+            }
+        });
+      } else {
+        if (isArray(d)) {
+          handler.changed(model, key, d[0], d[1]);
+        } else {
+          handler.changed(model, key);
+          walk(d, model[key]);
+        }
+      }
+    });
+  }
+
+  const diff = this.createDiff(a, b);
+
+  walk(diff, b, handler);
+
+  return handler;
+};

package/lib/index.js

@@ -0,0 +1,7 @@
+export {
+  default as Differ
+} from './differ.js';
+
+export {
+  default as diff
+} from './diff.js';

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "object-diagram-js-differ",
+  "version": "1.0.0",
+  "description": "A semantic diffing utility for object diagram files",
+  "scripts": {
+    "all": "run-s lint test",
+    "lint": "eslint .",
+    "lintFix": "eslint . --fix",
+    "test": "jasmine"
+  },
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/timKraeuter/object-diagram-js-differ"
+  },
+  "keywords": [
+    "object diagram",
+    "diff"
+  ],
+  "author": {
+    "name": "Tim Kräuter",
+    "url": "https://timkraeuter.com/"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "object-diagram-moddle": "^1.0.1",
+    "eslint": "^8.54.0",
+    "eslint-plugin-bpmn-io": "^1.0.0",
+    "npm-run-all": "^4.1.5",
+    "chai": "^4.3.10",
+    "jasmine": "^5.1.0"
+  },
+  "dependencies": {
+    "jsondiffpatch": "^0.5.0",
+    "min-dash": "^3.0.0"
+  }
+}

package/spec/.eslintrc

@@ -0,0 +1,6 @@
+{
+  "env": {
+    "jasmine": true
+  },
+  "extends": "plugin:bpmn-io/recommended"
+}

package/spec/DifferSpec.js

@@ -0,0 +1,88 @@
+import {
+  expect
+} from 'chai';
+
+import {
+  readFileSync
+} from 'fs';
+
+import ODModdle from 'object-diagram-moddle';
+
+import { Differ } from '../lib/index.js';
+
+describe('diff', function() {
+
+  it('should discover add', async function() {
+
+    // given
+    const aDiagram = readFileSync('spec/fixtures/base.xml', 'utf-8');
+    const bDiagram = readFileSync('spec/fixtures/add.xml', 'utf-8');
+
+    // when
+    const results = await getDiff(aDiagram, bDiagram);
+
+    // then
+    expect(results._added).to.have.keys(
+      [ 'Object_2840', 'Link_Object_2669_to_Object_2840_type_components' ]);
+    expect(results._removed).to.eql({});
+    expect(results._layoutChanged).to.eql({});
+    expect(results._changed).to.eql({});
+
+  });
+
+  it('should discover remove', async function() {
+
+    // given
+    const aDiagram = readFileSync('spec/fixtures/base.xml', 'utf-8');
+    const bDiagram = readFileSync('spec/fixtures/remove.xml', 'utf-8');
+
+    // when
+    const results = await getDiff(aDiagram, bDiagram);
+
+    // then
+    expect(results._added).to.eql({});
+    expect(results._removed).to.have.keys(
+      [ 'Object_2839', 'Link_Object_2669_to_Object_2839_type_components' ]);
+    expect(results._layoutChanged).to.eql({});
+    expect(results._changed).to.eql({});
+
+  });
+
+  it('should discover change', async function() {
+
+    // given
+    const aDiagram = readFileSync('spec/fixtures/base.xml', 'utf-8');
+    const bDiagram = readFileSync('spec/fixtures/change.xml', 'utf-8');
+
+    // when
+    const results = await getDiff(aDiagram, bDiagram);
+
+    // then
+    expect(results._added).to.eql({});
+    expect(results._removed).to.eql({});
+    expect(results._layoutChanged).to.eql({});
+    expect(results._changed).to.have.keys([ 'Object_2839' ]);
+
+    expect(results._changed['Object_2839'].attrs).to.deep.eq({
+      name: { oldValue: '2:Component', newValue: '2:QuantifiedComponent' },
+      attributeValues: { oldValue: 'quantity=77', newValue: 'quantity=1' }
+
+    });
+  });
+});
+
+// helpers //////////////////
+
+async function importDiagram(diagram) {
+  const moddle = new ODModdle();
+  const defs = await moddle.fromXML(diagram);
+  return defs.rootElement;
+}
+
+async function getDiff(a, b) {
+  const aDefs = await importDiagram(a);
+  const bDefs = await importDiagram(b);
+
+  return new Differ().diff(aDefs, bDefs);
+}
+

package/spec/fixtures/add.xml

@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<od:definitions xmlns:od="http://tk/schema/od" xmlns:odDi="http://tk/schema/odDi" xmlns:dc="http://www.omg.org/spec/DD/20100524/DC">
+  <od:odBoard id="Board_debug">
+    <od:link name="components" id="Link_Object_2669_to_Object_2839_type_components" type="components" sourceRef="Object_2669" targetRef="Object_2839" />
+    <od:object name="folding_wall_table:Product" id="Object_2669" attributeValues="cost=5&#10;name=&#34;Folding wall table&#34;">
+      <od:links>Link_Object_2669_to_Object_2839_type_components</od:links>
+      <od:links>Link_Object_2669_to_Object_2840_type_components</od:links>
+    </od:object>
+    <od:object name="2:QuantifiedComponent" id="Object_2839" attributeValues="quantity=1" />
+    <od:object name="3:QuantifiedComponent" id="Object_2840" attributeValues="quantity=26" />
+    <od:link name="components" id="Link_Object_2669_to_Object_2840_type_components" type="components" sourceRef="Object_2669" targetRef="Object_2840" />
+  </od:odBoard>
+  <odDi:odRootBoard id="RootBoard_debug">
+    <odDi:odPlane id="Plane_debug" boardElement="Board_debug">
+      <odDi:link id="Link_Object_2669_to_Object_2840_type_components_di" boardElement="Link_Object_2669_to_Object_2840_type_components">
+        <odDi:waypoint x="521.9" y="198.60000000000002" />
+        <odDi:waypoint x="521.9" y="233.60000000000002" />
+        <odDi:waypoint x="435.5" y="233.60000000000002" />
+        <odDi:waypoint x="435.5" y="296.6" />
+        <odDi:odLabel>
+          <dc:Bounds x="450" y="240" width="82" height="18" />
+        </odDi:odLabel>
+      </odDi:link>
+      <odDi:link id="Link_Object_2669_to_Object_2839_type_components_di" boardElement="Link_Object_2669_to_Object_2839_type_components">
+        <odDi:waypoint x="477.7" y="198.60000000000002" />
+        <odDi:waypoint x="477.7" y="223.60000000000002" />
+        <odDi:waypoint x="218.5" y="223.60000000000002" />
+        <odDi:waypoint x="218.5" y="296.6" />
+        <odDi:odLabel>
+          <dc:Bounds x="307" y="199" width="82" height="18" />
+        </odDi:odLabel>
+      </odDi:link>
+      <odDi:odShape id="Object_2669_di" boardElement="Object_2669">
+        <dc:Bounds x="434" y="120" width="221" height="78" />
+      </odDi:odShape>
+      <odDi:odShape id="Object_2839_di" boardElement="Object_2839">
+        <dc:Bounds x="120" y="297" width="197" height="59" />
+      </odDi:odShape>
+      <odDi:odShape id="Object_2840_di" boardElement="Object_2840">
+        <dc:Bounds x="337" y="297" width="197" height="59" />
+      </odDi:odShape>
+    </odDi:odPlane>
+  </odDi:odRootBoard>
+</od:definitions>

package/spec/fixtures/base.xml

@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<od:definitions xmlns:od="http://tk/schema/od" xmlns:odDi="http://tk/schema/odDi" xmlns:dc="http://www.omg.org/spec/DD/20100524/DC">
+  <od:odBoard id="Board_debug">
+    <od:link name="components" id="Link_Object_2669_to_Object_2839_type_components" type="components" sourceRef="Object_2669" targetRef="Object_2839" />
+    <od:object name="folding_wall_table:Product" id="Object_2669" attributeValues="cost=5&#10;name=&#34;Folding wall table&#34;">
+      <od:links>Link_Object_2669_to_Object_2839_type_components</od:links>
+    </od:object>
+    <od:object name="2:QuantifiedComponent" id="Object_2839" attributeValues="quantity=1" />
+  </od:odBoard>
+  <odDi:odRootBoard id="RootBoard_debug">
+    <odDi:odPlane id="Plane_debug" boardElement="Board_debug">
+      <odDi:link id="Link_Object_2669_to_Object_2839_type_components_di" boardElement="Link_Object_2669_to_Object_2839_type_components">
+        <odDi:waypoint x="477.7" y="198.60000000000002" />
+        <odDi:waypoint x="477.7" y="223.60000000000002" />
+        <odDi:waypoint x="218.5" y="223.60000000000002" />
+        <odDi:waypoint x="218.5" y="296.6" />
+        <odDi:odLabel>
+          <dc:Bounds x="307" y="199" width="82" height="18" />
+        </odDi:odLabel>
+      </odDi:link>
+      <odDi:odShape id="Object_2669_di" boardElement="Object_2669">
+        <dc:Bounds x="434" y="120" width="221" height="78" />
+      </odDi:odShape>
+      <odDi:odShape id="Object_2839_di" boardElement="Object_2839">
+        <dc:Bounds x="120" y="297" width="197" height="59" />
+      </odDi:odShape>
+    </odDi:odPlane>
+  </odDi:odRootBoard>
+</od:definitions>

package/spec/fixtures/change.xml

@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<od:definitions xmlns:od="http://tk/schema/od" xmlns:odDi="http://tk/schema/odDi" xmlns:dc="http://www.omg.org/spec/DD/20100524/DC">
+  <od:odBoard id="Board_debug">
+    <od:object name="folding_wall_table:Product" id="Object_2669" attributeValues="cost=5&#10;name=&#34;Folding wall table&#34;">
+      <od:links>Link_Object_2669_to_Object_2839_type_components</od:links>
+    </od:object>
+    <od:object name="2:Component" id="Object_2839" attributeValues="quantity=77" />
+    <od:link name="components" id="Link_Object_2669_to_Object_2839_type_components" type="components" sourceRef="Object_2669" targetRef="Object_2839" />
+  </od:odBoard>
+  <odDi:odRootBoard id="RootBoard_debug">
+    <odDi:odPlane id="Plane_debug" boardElement="Board_debug">
+      <odDi:link id="Link_Object_2669_to_Object_2839_type_components_di" boardElement="Link_Object_2669_to_Object_2839_type_components">
+        <odDi:waypoint x="477.7" y="198.60000000000002" />
+        <odDi:waypoint x="477.7" y="223.60000000000002" />
+        <odDi:waypoint x="218.5" y="223.60000000000002" />
+        <odDi:waypoint x="218.5" y="296.6" />
+        <odDi:odLabel>
+          <dc:Bounds x="307" y="199" width="82" height="18" />
+        </odDi:odLabel>
+      </odDi:link>
+      <odDi:odShape id="Object_2669_di" boardElement="Object_2669">
+        <dc:Bounds x="434" y="120" width="221" height="78" />
+      </odDi:odShape>
+      <odDi:odShape id="Object_2839_di" boardElement="Object_2839">
+        <dc:Bounds x="120" y="297" width="197" height="59" />
+      </odDi:odShape>
+    </odDi:odPlane>
+  </odDi:odRootBoard>
+</od:definitions>

package/spec/fixtures/remove.xml

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<od:definitions xmlns:od="http://tk/schema/od" xmlns:odDi="http://tk/schema/odDi" xmlns:dc="http://www.omg.org/spec/DD/20100524/DC">
+  <od:odBoard id="Board_debug">
+    <od:object name="folding_wall_table:Product" id="Object_2669" attributeValues="cost=5&#10;name=&#34;Folding wall table&#34;" />
+  </od:odBoard>
+  <odDi:odRootBoard id="RootBoard_debug">
+    <odDi:odPlane id="Plane_debug" boardElement="Board_debug">
+      <odDi:odShape id="Object_2669_di" boardElement="Object_2669">
+        <dc:Bounds x="434" y="120" width="221" height="78" />
+      </odDi:odShape>
+    </odDi:odPlane>
+  </odDi:odRootBoard>
+</od:definitions>

package/spec/support/jasmine.json

@@ -0,0 +1,13 @@
+{
+  "spec_dir": "spec",
+  "spec_files": [
+    "**/*[sS]pec.?(m)js"
+  ],
+  "helpers": [
+    "helpers/**/*.?(m)js"
+  ],
+  "env": {
+    "stopSpecOnExpectationFailure": false,
+    "random": true
+  }
+}