feat: provide variables used in feel expressions

Author: Buckwich

lib/base/VariableResolver.js

@@ -1,4 +1,5 @@
 import { getBusinessObject, is } from 'bpmn-js/lib/util/ModelUtil';
+import { has } from 'min-dash';
 import CachedValue from './util/CachedValue';
 import { mergeList } from './util/listUtil';
 import { getParents } from './util/elementsUtil';
@@ -15,8 +16,9 @@ import { getParents } from './util/elementsUtil';
 
 /**
  * @typedef {AdditionalVariable} ProcessVariable
- * @property {Array<ModdleElement>} origin
- * @property {ModdleElement} scope
+ * @property {Array<ModdleElement>} [origin]
+ * @property {Array<ModdleElement>} [usedBy]
+ * @property {ModdleElement} [scope]
  * @property {Array<Object>} provider
  */
 
@@ -159,12 +161,26 @@ export class BaseVariableResolver {
       variables.forEach(variable => {
         const existingVariable = mergedVariables.find(v =>
           v.name === variable.name && v.scope === variable.scope
+          && (v.scope || !v.usedBy) && (variable.scope || !variable.usedBy)
         );
 
         if (existingVariable) {
           merge('origin', existingVariable, variable);
           merge('provider', existingVariable, variable);
           mergeEntries(existingVariable, variable);
+
+          // Preserve usedBy from either side during merge
+          if (variable.usedBy) {
+            if (!existingVariable.usedBy) {
+              existingVariable.usedBy = [ ...variable.usedBy ];
+            } else {
+              variable.usedBy.forEach(target => {
+                if (!existingVariable.usedBy.includes(target)) {
+                  existingVariable.usedBy.push(target);
+                }
+              });
+            }
+          }
         } else {
           mergedVariables.push(variable);
         }
@@ -247,40 +263,86 @@ export class BaseVariableResolver {
   }
 
   /**
-   * Returns all variables in the scope of the given element.
+   * Returns variables for the given element.
+   *
+   * Default behavior returns written variables in scope (same as previous
+   * `getVariablesForElement` behavior).
+   *
+   * If one of `read` / `written` is set explicitly, only the requested types
+   * are returned.
    *
    * @async
    * @param {ModdleElement} element
-   * @returns {Array<ProcessVariable>} variables
+   * @param {Object} [options]
+   * @param {boolean} [options.read]
+   * @param {boolean} [options.written]
+   * @param {boolean} [options.local=true] Include local read variables
+   * @returns {Promise<Array<ProcessVariable>>} variables
    */
-  async getVariablesForElement(element) {
+  async getVariablesForElement(element, options = {}) {
     const bo = getBusinessObject(element);
 
+    const {
+      read,
+      written,
+      local
+    } = normalizeGetVariablesForElementOptions(options);
+
+    const writtenVariables = written
+      ? await this._getWrittenVariablesForElement(bo)
+      : [];
+
+    const readVariables = read
+      ? await this._getReadVariablesForElement(bo, { local })
+      : [];
+
+    return [ ...writtenVariables, ...readVariables ];
+  }
+
+  async _getWrittenVariablesForElement(bo) {
     const root = getRootElement(bo);
     const allVariables = await this.getProcessVariables(root);
 
-    // (1) get variables for given scope
-    var scopeVariables = allVariables.filter(function(variable) {
-      return variable.scope.id === bo.id;
-    });
+    const parentIds = new Set(getParents(bo).map(parent => parent.id));
+    const scopeVariables = [];
+    const parentsScopeVariables = [];
+    const leakedVariables = [];
 
-    // (2) get variables for parent scopes
-    var parents = getParents(bo);
+    // Categorize in one pass to avoid repeated full-array scans.
+    for (const variable of allVariables) {
+      const scope = variable.scope;
 
-    var parentsScopeVariables = allVariables.filter(function(variable) {
-      return parents.find(function(parent) {
-        return parent.id === variable.scope.id;
-      });
-    });
+      if (!scope) {
+        continue;
+      }
+
+      if (scope.id === bo.id) {
+        scopeVariables.push(variable);
+        continue;
+      }
+
+      if (parentIds.has(scope.id)) {
+        parentsScopeVariables.push(variable);
+        continue;
+      }
+
+      // Include descendant-scoped variables that are used outside their own
+      // scope but still within the current scope (cross-scope leak).
+      if (isElementInScope(scope, bo) && isUsedInScope(variable, bo) && isUsedOutsideOwnScope(variable)) {
+        leakedVariables.push(variable);
+      }
+    }
 
-    const reversedVariables = [ ...scopeVariables, ...parentsScopeVariables ].reverse();
+    const reversedVariables = [ ...leakedVariables, ...scopeVariables, ...parentsScopeVariables ].reverse();
 
     const seenNames = new Set();
 
-    return reversedVariables.filter(variable => {
+    const deduplicatedVariables = reversedVariables.filter(variable => {
+
+      const provider = variable.provider || [];
 
       // if external variable, keep
-      if (variable.provider.find(extractor => extractor !== this._baseExtractor)) {
+      if (provider.some(extractor => extractor !== this._baseExtractor)) {
         return true;
       }
 
@@ -293,6 +355,37 @@ export class BaseVariableResolver {
 
       return false;
     });
+
+    return deduplicatedVariables.map(variable => {
+      if (!variable.usedBy || !Array.isArray(variable.usedBy)) {
+        return variable;
+      }
+
+      const usedBy = filterUsedByForElement(variable, bo);
+
+      if (usedBy.length === variable.usedBy.length) {
+        return variable;
+      }
+
+      return {
+        ...variable,
+        usedBy: usedBy.length ? usedBy : undefined
+      };
+    });
+  }
+
+  async _getReadVariablesForElement(element, options = {}) {
+    const root = getRootElement(element);
+    const allVariablesByRoot = await this.parsedVariables.get();
+    const allVariables = allVariablesByRoot[root.id] || [];
+
+    if (!options.local) {
+      return allVariables.filter(variable => isConsumedByElement(variable, element));
+    }
+
+    return allVariables.filter(variable => {
+      return isConsumedByElement(variable, element) || isLocalReadByElement(variable, element);
+    });
   }
 
   _getScope(element, containerElement, variableName, checkYourself) {
@@ -396,4 +489,117 @@ function cloneVariable(variable) {
   }
 
   return newVariable;
-}
+}
+
+function isUsedInScope(variable, scopeElement) {
+  if (!variable.usedBy || !Array.isArray(variable.usedBy)) {
+    return false;
+  }
+
+  return variable.usedBy.some(usedBy => isElementInScope(usedBy, scopeElement));
+}
+
+function isElementInScope(element, scopeElement) {
+  if (!element || !element.id || !scopeElement || !scopeElement.id) {
+    return false;
+  }
+
+  if (element.id === scopeElement.id) {
+    return true;
+  }
+
+  return getParents(element).some(parent => parent.id === scopeElement.id);
+}
+
+function isUsedOutsideOwnScope(variable) {
+  if (!variable.scope || !Array.isArray(variable.usedBy)) {
+    return false;
+  }
+
+  return variable.usedBy.some(usedBy => {
+    return usedBy && usedBy.id && !isElementInScope(usedBy, variable.scope);
+  });
+}
+
+function filterUsedByForElement(variable, element) {
+  const names = variable.usedBy.filter(usage => typeof usage === 'string');
+  const elements = variable.usedBy.filter(usage => usage && usage.id);
+
+  if (!variable.scope) {
+    return [ ...names, ...elements.filter(usage => isElementInScope(usage, element)) ];
+  }
+
+  // Querying the variable's own scope: show local consumers.
+  if (element.id === variable.scope.id) {
+    return [
+      ...names,
+      ...elements.filter(usage => isElementInScope(usage, variable.scope))
+    ];
+  }
+
+  // Querying an ancestor scope: show consumers outside the variable's own scope.
+  if (isElementInScope(variable.scope, element)) {
+    return [
+      ...names,
+      ...elements.filter(usage =>
+        isElementInScope(usage, element)
+        && !isElementInScope(usage, variable.scope)
+      )
+    ];
+  }
+
+  // Querying a child scope: show consumers in that child scope only.
+  if (isElementInScope(element, variable.scope)) {
+    return [
+      ...names,
+      ...elements.filter(usage => isElementInScope(usage, element))
+    ];
+  }
+
+  return names;
+}
+
+function normalizeGetVariablesForElementOptions(options = {}) {
+  if (!has(options, 'read') && !has(options, 'written')) {
+    return {
+      read: false,
+      written: true,
+      local: options.local !== false
+    };
+  }
+
+  return {
+    read: !!options.read,
+    written: !!options.written,
+    local: options.local !== false
+  };
+}
+
+
+function isConsumedByElement(variable, element) {
+  return !variable.scope && hasElementUsage(variable, element);
+}
+
+function isLocalReadByElement(variable, element) {
+  if (!variable.scope || !Array.isArray(variable.usedBy)) {
+    return false;
+  }
+
+  if (hasElementUsage(variable, element)) {
+    return true;
+  }
+
+  if (variable.scope.id !== element.id) {
+    return false;
+  }
+
+  return variable.usedBy.some(usage => typeof usage === 'string');
+}
+
+function hasElementUsage(variable, element) {
+  if (!Array.isArray(variable.usedBy)) {
+    return false;
+  }
+
+  return variable.usedBy.some(usage => usage && usage.id === element.id);
+}