Changes Provider and Direct Comparison functionality (#245)

This PR aims to enhance changed elements react for:

_Frontend Enhancements:_
1. Provide consumers a way to inject their own changes and skip using
the changed elements service altogether
2. Provide colorization overrides for any special customization logic
3. Provide a callback when changed instances are selected in the UI

_Backend Enhancements:_
1. Initial ChangesRpcInterface and ChangesRpcImpl which aim to allow
using the Partial EC Change Unifier in a simplified way
2. The Rpc interface allows the app to provide relationships that they
care about and marks any related changed ec instance with what
relationships were affected that may drive the element for changes

_Test App Changes:_
1. The ChangesRpcInterface is used to supply changes to provide an
example of usage for an app that may want specific relationships to be
highlighted
2. Showcases how they could colorize changed instances based on the
relationships that have changes

The Rpc is being implemented temporarily as part of the
test-app-backend, but we will aim to move it to a separate package
(potentially
[imodel-sync](https://github.com/iTwin/itwinjs-internal/tree/master/packages/clients/sync))
to be consumable by other applications.

---------

Co-authored-by: Caleb German <Caleb.German@Bentley.com>

Author: diegopinate

.changeset/wise-readers-jog.md

@@ -0,0 +1,15 @@
+---
+"@itwin/changed-elements-react": minor
+---
+
+_Frontend Enhancements:_
+
+1. Provide consumers a way to inject their own changes and skip using the changed elements service altogether
+2. Provide colorization overrides for any special customization logic
+3. Provide a callback when changed instances are selected in the UI
+
+_Backend Enhancements:_
+1. Initial ChangesRpcInterface and ChangesRpcImpl which aim to allow using the Partial EC Change Unifier in a simplified way
+2. The Rpc interface allows the app to provide relationships that they care about and marks any related changed ec instance with what relationships were affected that may drive the element for changes
+
+See VersionCompare initialization options (`changesProvider`, `colorOverrideProvider` and `onInstancesSelected`) for more information.

.eslintrc.json

@@ -2,6 +2,7 @@
   "root": true,
   "extends": [
     "eslint:recommended",
+    "prettier",
     "plugin:@typescript-eslint/recommended-type-checked"
   ],
   "parser": "@typescript-eslint/parser",
@@ -16,6 +17,7 @@
     "no-alert": "warn",
     "no-empty": [ "warn", { "allowEmptyCatch": true } ],
     "no-eval": "error",
+    "no-console": "off",
     "@typescript-eslint/comma-dangle": [
       "warn",
       {

.github/workflows/CI.yaml

@@ -15,16 +15,16 @@ jobs:
       with:
         fetch-depth: 0  # Fetch all history for all branches and tags
 
-    - name: Install pnpm
+    - name: Install pnpm@10.12.4
       uses: pnpm/action-setup@v2
       with:
-        version: 8
+        version: 10.12.4
         run_install: false
 
-    - name: Use Node.js 20
+    - name: Use Node.js 20.16.0
       uses: actions/setup-node@v3
       with:
-        node-version: 20
+        node-version: 20.16.0
         cache: "pnpm"
 
     - name: Install dependencies

.github/workflows/dependabot-push.yml

@@ -26,7 +26,7 @@ jobs:
 
       # Install pnpm
       - name: Install pnpm
-        run: npm install -g pnpm
+        run: npm install -g pnpm@10.12.4
 
       # Install dependencies
       - name: Install dependencies

.github/workflows/release-workflow.yml

@@ -22,7 +22,7 @@ jobs:
     - name: Install pnpm
       uses: pnpm/action-setup@v2
       with:
-        version: 8
+        version: 10.12.4
         run_install: false
 
     - name: Use Node.js 20

.prettierrc

@@ -0,0 +1,7 @@
+{
+  "singleQuote": false,
+  "trailingComma": "all",
+  "printWidth": 150,
+  "tabWidth": 2,
+  "useTabs": false
+}

experiment.md

@@ -0,0 +1,32 @@
+## Changed Elements React Experiment - Direct Comparison Workflow
+
+### HYPOTHESIS:
+If we use changeset group processing without processing the changed elements, then the result of the direct processing will be produced faster and will resemble GitHub's diff functionality by displaying a flat list of changes.
+
+### REASON FOR EXPERIMENT
+Changed elements undergo extensive processing to ensure a presentation-based summary of changes in an iModel. We aim to understand how a feature like Version Comparison would operate using raw changeset group results instead of presentation ruleset-based property path traversal. We expect faster loading times for Direct Comparison due to reduced processing, while still providing valuable output to the user.
+
+### EXPERIMENT
+We conducted multiple experiments to confirm our hypothesis. The steps were:
+
+1. Run the Version Compare V2 workflow (Post/Get/Display) for an iModel with an unprocessed job range. Record the time until the user can interact with the job-related information on the UI.
+2. Run the experimental Direct Comparison on the same unprocessed job version. Record the time until the user can interact with the job-related information on the UI.
+
+#### Results Table
+We tested across three different iModels of varying sizes in the DEV region to draw better conclusions.
+
+| Itwin | IModel | Number Of Changeset Processed (V2 / Direct Comparison) | V2 Processing Time till interaction in UI (ms) | V2 Number of Changed Elements Found | Direct Comparison Processing Time till interaction in UI (ms) | Direct Comparison Number of Changed Elements Found | % diff between V2 and Direct Processing |
+| -- | -- | -- | -- | -- | -- | -- | -- |
+| 1036c64d-7fbe-47fd-b03c-4ed7ad7fc829 | c87854bc-1197-4ed9-8d3d-ad9cb5fd1347 | 12 | 22133 | 5342 | 6536 | 28039 | 108.807% |
+| 1036c64d-7fbe-47fd-b03c-4ed7ad7fc829 | e657e0d6-fad1-4971-9c22-459bd400534b | 524 | 185067 | 109474 | 71375 | 314907 | 88.6688% |
+| 1036c64d-7fbe-47fd-b03c-4ed7ad7fc829 | b8571aeb-dc0b-405f-bf6b-42401af40dd1 | 23 | 109007 | 128803 | 26017 | 22348 | 122.926% |
+
+### RESULTS SUMMARY
+The most salient findings of our testing:
+
+1. On iModels with a vast amount of data to process, Direct Comparison is on average 106.8 % faster than V2 Comparison.
+2. The UI has more elements to process with the Direct Comparison workflow than with the V2 workflow.
+3. The larger the IModel/changeset range. The v2 processing is faster due to multiple agents used for processing.
+
+### CONCLUSION
+This experiment proved that the Direct Comparison workflow is viable and may be preferable in some situations for larger iModels due to its processing speed. Direct Comparison may be an efficacious solution to long waiting times if the user does not require the full information provided by property traversal.

package.json

@@ -8,15 +8,15 @@
     "test:components": "npm test --prefix packages/changed-elements-react",
     "cover": "run-p --silent cover:*",
     "cover:components": "npm run test:cover --prefix packages/changed-elements-react",
-    "lint": "eslint '**/*.{ts,tsx}'",
+    "lint": "eslint ./packages/**/src/**/*.{ts,tsx}",
     "typecheck": "run-p --silent typecheck:*",
     "typecheck:components": "npm run typecheck --prefix packages/changed-elements-react",
     "typecheck:backend": "npm run typecheck --prefix packages/test-app-backend",
     "typecheck:frontend": "npm run typecheck --prefix packages/test-app-frontend",
     "check": "changeset status"
   },
   "engines": {
-    "pnpm": ">=8",
+    "pnpm": ">=10",
     "npm": "<0",
     "node": ">=20"
   },
@@ -43,6 +43,16 @@
       "axios@<1.8.2": ">=1.8.2",
       "dompurify@<3.2.4": ">=3.2.4",
       "esbuild@<=0.24.2": ">=0.25.0"
-    }
+    },
+    "onlyBuiltDependencies": [
+      "@bentley/imodeljs-native",
+      "@parcel/watcher",
+      "@swc/core",
+      "esbuild",
+      "protobufjs"
+    ]
+  },
+  "devDependencies": {
+    "eslint-config-prettier": "^10.1.5"
   }
 }

packages/changed-elements-react/public/locales/en/VersionCompare.json

@@ -46,6 +46,7 @@
     "searchResults": "Search Results",
     "removed": "Removed",
     "modified": "Modified",
+    "driven": "Driven by another change",
     "loading": "Loading...",
     "versions": "Versions",
     "version": "Version",
@@ -153,8 +154,10 @@
     "hiddenProperty": "Hidden Properties",
     "placement": "Placement",
     "indirect": "Indirect",
+    "driven": "Driven",
     "modifiedIndirectly": "Children modified",
     "modelHasChanges": "Model has changed elements",
+    "modelHasDrivenChanges": "Model was changed indirectly",
     "childrenModified": "Child elements were modified",
     "childrenChanges": "Children changes",
     "childrenAdded": "Children were added",

packages/changed-elements-react/src/NamedVersionSelector/useComparisonJobs.ts

@@ -87,7 +87,6 @@ export function useComparisonJobs(args: UseComparisonJobsArgs): UseComparisonJob
         job,
         watchJob: async function* (pollingIntervalMs: number, signal?: AbortSignal) {
           signal?.throwIfAborted();
-
           while (job.status === "Queued" || job.status === "Started") {
             await new Promise((resolve) => setTimeout(resolve, pollingIntervalMs));
             const comparisonJob = await getComparisonJob({