bpmnlint-plugin-camunda-compat 2.58.2 → 2.59.0

package/README.md

@@ -79,7 +79,8 @@ npx bpmnlint my-diagram.bpmn
 ## Resources
 
 * [Issues](https://github.com/camunda/bpmnlint-plugin-camunda-compat/issues)
-
+* [Architecture documentation](./docs/ARCHITECTURE.md)
+* [Rule authoring guide](./docs/RULE_AUTHORING.md)
 
 ## Related
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bpmnlint-plugin-camunda-compat",
-  "version": "2.58.2",
+  "version": "2.59.0",
   "description": "A bpmnlint plug-in for Camunda compatibility",
   "main": "index.js",
   "scripts": {

package/rules/camunda-cloud/agent-fromai-contract.js

@@ -1,5 +1,7 @@
 const { is } = require('bpmnlint-utils');
 
+const { getPath, pathConcat } = require('@bpmn-io/moddle-utils');
+
 const { findExtensionElement, findAncestorAdHocSubProcess, isAgenticAdHocSubProcess } = require('../utils/element');
 const { CORRECT_NAME, NAME_ALIASES, findFunctionInvocations, getPositionalArgs } = require('./utils/feel');
 const { reportErrors } = require('../utils/reporter');
@@ -156,12 +158,11 @@ module.exports = skipInNonExecutableProcess(function(config = {}) {
       return;
     }
 
-    // Properties-panel entry for this input parameter, so clicking the report
-    // opens the right mapping (id convention: {elementId}-input-{index}-source).
-    const inputIndex = (node.$parent.get('inputParameters') || []).indexOf(node);
-    const propertiesPanel = {
-      entryIds: [ `${ task.get('id') }-input-${ inputIndex }-source` ]
-    };
+    // Moddle path to this input parameter's source, so a single downstream
+    // resolver maps it to the entry the modeler actually renders — the standard
+    // input mapping, or a template's custom entry. The rule stays agnostic to
+    // the id scheme.
+    const path = pathConcat(getPath(node, task), 'source');
 
     const ahsp = findAncestorAdHocSubProcess(task);
 
@@ -169,7 +170,7 @@ module.exports = skipInNonExecutableProcess(function(config = {}) {
       reportErrors(task, reporter, invocations.map(() => ({
         message: 'fromAi() should only be used inside an agentic sub-process.',
         data: { type: ERROR_TYPES.AGENT_FEEL_WRONG_CONTEXT },
-        propertiesPanel,
+        path,
       })));
       return;
     }
@@ -179,7 +180,7 @@ module.exports = skipInNonExecutableProcess(function(config = {}) {
       reportErrors(task, reporter, invocations.map(() => ({
         message: `The "${ahspLabel}" sub-process is not marked as agentic, so fromAi() has no effect.`,
         data: { type: ERROR_TYPES.AGENT_FEEL_WRONG_CONTEXT },
-        propertiesPanel,
+        path,
       })));
       return;
     }
@@ -194,7 +195,7 @@ module.exports = skipInNonExecutableProcess(function(config = {}) {
       reportErrors(task, reporter, invocations.map(() => ({
         message: 'fromAi() is ignored here: only the tool\'s entry element defines AI inputs. Define it there and read the toolCall variable directly.',
         data: { type: ERROR_TYPES.AGENT_FEEL_NON_ENTRY_ELEMENT },
-        propertiesPanel,
+        path,
       })));
       return;
     }
@@ -237,7 +238,7 @@ module.exports = skipInNonExecutableProcess(function(config = {}) {
     }
 
     if (errors.length) {
-      reportErrors(task, reporter, errors.map(error => ({ ...error, propertiesPanel })));
+      reportErrors(task, reporter, errors.map(error => ({ ...error, path })));
     }
   }
 
@@ -273,7 +274,7 @@ module.exports = skipInNonExecutableProcess(function(config = {}) {
       return;
     }
 
-    const keyCounts = {};
+    const keyOccurrences = {};
 
     for (const input of ioMapping.get('inputParameters') || []) {
       const source = input.get('source');
@@ -286,18 +287,18 @@ module.exports = skipInNonExecutableProcess(function(config = {}) {
         const args = getPositionalArgs(inv.node, expr);
         const key = args[ 0 ];
         if (key && key.type === 'PathExpression' && key.text.startsWith('toolCall.')) {
-          keyCounts[ key.text ] = (keyCounts[ key.text ] || 0) + 1;
+          (keyOccurrences[ key.text ] = keyOccurrences[ key.text ] || []).push(input);
         }
       }
     }
 
-    const duplicates = Object.keys(keyCounts).filter(key => keyCounts[ key ] > 1);
+    const duplicates = Object.keys(keyOccurrences).filter(key => keyOccurrences[ key ].length > 1);
 
     if (duplicates.length) {
       reportErrors(task, reporter, duplicates.map(key => ({
         message: `fromAi() key ${ key } is declared more than once in this tool. Declare it once and reference it directly elsewhere.`,
         data: { type: ERROR_TYPES.AGENT_FEEL_KEY_DUPLICATE },
-        propertiesPanel: { entryIds: [ 'inputs' ] },
+        paths: keyOccurrences[ key ].map(input => pathConcat(getPath(input, task), 'source')),
       })));
     }
   }
@@ -330,15 +331,12 @@ module.exports = skipInNonExecutableProcess(function(config = {}) {
       return;
     }
 
-    const outputIndex = (node.$parent.get('outputParameters') || []).indexOf(node);
-    const propertiesPanel = {
-      entryIds: [ `${ task.get('id') }-output-${ outputIndex }-source` ]
-    };
+    const path = pathConcat(getPath(node, task), 'source');
 
     reportErrors(task, reporter, invocations.map(() => ({
       message: 'fromAi() defines a tool input and has no effect in an output mapping. Define it in an input mapping on the tool\'s entry element.',
       data: { type: ERROR_TYPES.AGENT_FEEL_WRONG_CONTEXT },
-      propertiesPanel,
+      path,
     })));
   }
 
@@ -368,7 +366,7 @@ module.exports = skipInNonExecutableProcess(function(config = {}) {
     reportErrors(node, reporter, invocations.map(() => ({
       message: 'fromAi() defines a tool input and cannot be used in a sequence flow condition. Define it in an input mapping on the tool\'s entry element.',
       data: { type: ERROR_TYPES.AGENT_FEEL_WRONG_CONTEXT },
-      propertiesPanel: { entryIds: [ 'conditionExpression' ] },
+      path: getPath(condition, node),
     })));
   }
 });

package/rules/camunda-cloud/agent-tool-documentation.js

@@ -29,7 +29,7 @@ module.exports = skipInNonExecutableProcess(function(config = {}) {
         {
           message: 'Tool documentation is missing.',
           data: { type: ERROR_TYPES.AGENT_TOOL_DOCUMENTATION_MISSING },
-          propertiesPanel: { entryIds: [ 'documentation' ] },
+          path: [ 'documentation' ],
         },
       ]);
     }

package/rules/camunda-cloud/agent-tool-output-key.js

@@ -1,5 +1,7 @@
 const { is } = require('bpmnlint-utils');
 
+const { getPath, pathConcat } = require('@bpmn-io/moddle-utils');
+
 const { isAgenticToolElement } = require('../utils/element');
 const { reportErrors, getName } = require('../utils/reporter');
 const { ERROR_TYPES } = require('../utils/error-types');
@@ -38,7 +40,7 @@ module.exports = skipInNonExecutableProcess(function(config = {}) {
       reportErrors(node, reporter, {
         message: 'Tool returns nothing to the agent. Set a "toolCallResult" (at minimum, note the task completed).',
         data: { type: ERROR_TYPES.AGENT_TOOL_RESULT_MISSING },
-        propertiesPanel: { entryIds: [ 'outputs' ] },
+        path: getOutputsPath(node),
       });
       return;
     }
@@ -51,7 +53,7 @@ module.exports = skipInNonExecutableProcess(function(config = {}) {
         reportErrors(casingMismatch.element, reporter, {
           message: `Wrong casing "${getCasingMismatchText(casingMismatch)}": use toolCallResult (case-sensitive).`,
           data: { type: ERROR_TYPES.AGENT_TOOL_OUTPUT_KEY_CASING_INVALID },
-          propertiesPanel: { entryIds: [ 'outputs' ] },
+          path: getChannelPath(casingMismatch),
         });
         return;
       }
@@ -63,7 +65,7 @@ module.exports = skipInNonExecutableProcess(function(config = {}) {
       reportErrors(misdirected.element, reporter, {
         message: '"toolCallResult" output is not mapped.',
         data: { type: ERROR_TYPES.AGENT_TOOL_OUTPUT_KEY_INVALID },
-        propertiesPanel: { entryIds: [ 'outputs' ] },
+        path: getChannelPath(misdirected),
       });
       return;
     }
@@ -96,7 +98,7 @@ module.exports = skipInNonExecutableProcess(function(config = {}) {
         reportErrors(overwriter.element, reporter, {
           message: `This overwrites the "toolCallResult" value set on "${overwrittenLabel}".`,
           data: { type: ERROR_TYPES.AGENT_TOOL_OUTPUT_KEY_OVERWRITE },
-          propertiesPanel: { entryIds: [ 'outputs' ] },
+          path: getChannelPath(overwriter),
         });
       }
     }
@@ -120,8 +122,9 @@ module.exports = skipInNonExecutableProcess(function(config = {}) {
  *
  * @param {ModdleElement} entry
  *
- * @returns {Object} { channels, linear } — channels as { kind, value, element }
- * (element being whichever element in the flow actually wrote this channel),
+ * @returns {Object} { channels, linear } — channels as { kind, value, element,
+ * node, property } (element being whichever element in the flow actually wrote
+ * this channel; node/property the moddle leaf that carries the offending value),
  * and linear being true when the flow is a single non-branching chain
  */
 function collectResultChannels(entry) {
@@ -191,14 +194,14 @@ function collectElementChannels(element, channels) {
   for (const value of extensionElements.get('values')) {
     if (is(value, 'zeebe:IoMapping')) {
       for (const output of value.get('outputParameters') || []) {
-        channels.push({ kind: 'output', value: output.get('target') || '', source: output.get('source'), element });
+        channels.push({ kind: 'output', value: output.get('target') || '', source: output.get('source'), element, node: output, property: 'target' });
       }
     }
 
     if (is(value, 'zeebe:Script') || is(value, 'zeebe:CalledDecision')) {
       const resultVariable = value.get('resultVariable');
       if (resultVariable) {
-        channels.push({ kind: 'resultVariable', value: resultVariable, element });
+        channels.push({ kind: 'resultVariable', value: resultVariable, element, node: value, property: 'resultVariable' });
       }
     }
 
@@ -212,16 +215,45 @@ function collectElementChannels(element, channels) {
       for (const header of value.get('values') || []) {
         const key = header.get('key');
         if (key === 'resultVariable') {
-          channels.push({ kind: 'resultVariable', value: header.get('value') || '', element });
+          channels.push({ kind: 'resultVariable', value: header.get('value') || '', element, node: header, property: 'value' });
         }
         if (key === 'resultExpression') {
-          channels.push({ kind: 'resultExpression', value: header.get('value') || '', element });
+          channels.push({ kind: 'resultExpression', value: header.get('value') || '', element, node: header, property: 'value' });
         }
       }
     }
   }
 }
 
+// The moddle leaf path to the write that actually carries the offending value
+// (an output target, a script/decision resultVariable, a connector header
+// value), relative to the element the finding is reported on. The panel
+// resolves this render-agnostically to the concrete field — a standard output
+// entry, or the matching element-template field when the tool is template
+// bound. Degrades to null (element selection) if the node is detached.
+function getChannelPath(channel) {
+  return pathConcat(getPath(channel.node, channel.element), channel.property);
+}
+
+// Best-effort location for a "tool returns nothing" finding: the tool's output
+// mapping collection, which the panel resolves outward to the outputs group.
+// When the tool has no output mapping at all there is nothing to point at, so
+// the finding degrades to element selection (null path) rather than fabricate a
+// target.
+function getOutputsPath(element) {
+  const extensionElements = element.get('extensionElements');
+  if (!extensionElements) {
+    return null;
+  }
+
+  const ioMapping = (extensionElements.get('values') || []).find(value => is(value, 'zeebe:IoMapping'));
+  if (!ioMapping) {
+    return null;
+  }
+
+  return pathConcat(getPath(ioMapping, element), 'outputParameters');
+}
+
 function isToolCallResultChannel({ kind, value }) {
   if (kind === 'resultExpression') {
     return /\btoolCallResult\b/.test(value);

package/rules/camunda-cloud/before-all-execution-listener.js

@@ -1,6 +1,6 @@
 const { is } = require('bpmnlint-utils');
 
-const { getPath } = require('@bpmn-io/moddle-utils');
+const { getPath, pathConcat } = require('@bpmn-io/moddle-utils');
 
 const {
   ERROR_TYPES,
@@ -33,7 +33,7 @@ module.exports = skipInNonExecutableProcess(function() {
       return [
         {
           message: 'Property <eventType> of <zeebe:ExecutionListener> with value <beforeAll> only allowed on multi-instance elements',
-          path: [ ...getPath(listener, node), 'eventType' ],
+          path: pathConcat(getPath(listener, node), 'eventType'),
           data: {
             type: ERROR_TYPES.PROPERTY_VALUE_NOT_ALLOWED,
             node: listener,

package/rules/camunda-cloud/connector-properties/config.js

@@ -1,4 +1,4 @@
-const { getPath } = require('@bpmn-io/moddle-utils');
+const { getPath, pathConcat } = require('@bpmn-io/moddle-utils');
 
 const { findExtensionElement } = require('../../utils/element');
 
@@ -75,7 +75,7 @@ function getInboundConnectorError(node, propertyName, allowedVersion) {
 
   return {
     message: `Connector property <name> with value <${ propertyName }> only allowed by Camunda ${ allowedVersion } or newer.`,
-    path: path ? [ ...path, 'name' ] : [ 'name' ],
+    path: pathConcat(path || [], 'name'),
     data: {
       type: ERROR_TYPES.CONNECTORS_PROPERTY_VALUE_NOT_ALLOWED,
       node: property,

package/rules/camunda-cloud/error-reference.js

@@ -5,6 +5,7 @@ const {
 
 const {
   getEventDefinition,
+  getReferencePath,
   hasProperties
 } = require('../utils/element');
 
@@ -52,11 +53,19 @@ module.exports = skipInNonExecutableProcess(function({ version }) {
       return;
     }
 
+    const nodePath = getReferencePath({
+      element: node,
+      referenceHolder: eventDefinition,
+      referenceProperty: 'errorRef',
+      referencedRoot: errorRef,
+      node: errorRef
+    });
+
     errors = hasProperties(errorRef, {
       errorCode: {
         required: true
       }
-    }, node);
+    }, node, nodePath);
 
     if (errors.length) {
       reportErrors(node, reporter, errors);

package/rules/camunda-cloud/escalation-reference.js

@@ -5,6 +5,7 @@ const {
 
 const {
   getEventDefinition,
+  getReferencePath,
   hasProperties
 } = require('../utils/element');
 
@@ -47,11 +48,19 @@ module.exports = skipInNonExecutableProcess(function() {
       return;
     }
 
+    const nodePath = getReferencePath({
+      element: node,
+      referenceHolder: eventDefinition,
+      referenceProperty: 'escalationRef',
+      referencedRoot: escalationRef,
+      node: escalationRef
+    });
+
     errors = hasProperties(escalationRef, {
       escalationCode: {
         required: true
       }
-    }, node);
+    }, node, nodePath);
 
     if (errors.length) {
       reportErrors(node, reporter, errors);

package/rules/camunda-cloud/feel-compatibility.js

@@ -1,6 +1,6 @@
 const { is } = require('bpmnlint-utils');
 
-const { getPath } = require('@bpmn-io/moddle-utils');
+const { getPath, pathConcat } = require('@bpmn-io/moddle-utils');
 const { camundaBuiltins, camundaReservedNameBuiltins } = require('@camunda/feel-builtins');
 
 const { FeelAnalyzer } = require('@bpmn-io/feel-analyzer');
@@ -77,9 +77,7 @@ module.exports = skipInNonExecutableProcess(function(config = {}) {
 
         errors.push({
           message: `FEEL function <${ builtin.name }> requires Camunda ${ builtin.engines.camunda }`,
-          path: path
-            ? [ ...path, propertyName ]
-            : [ propertyName ],
+          path: pathConcat(path || [], propertyName),
           data: {
             type: ERROR_TYPES.FEEL_EXPRESSION_UNSUPPORTED_FUNCTION,
             node,

package/rules/camunda-cloud/feel.js

@@ -1,6 +1,6 @@
 const { is } = require('bpmnlint-utils');
 
-const { getPath } = require('@bpmn-io/moddle-utils');
+const { getPath, pathConcat } = require('@bpmn-io/moddle-utils');
 
 const { FeelAnalyzer } = require('@bpmn-io/feel-analyzer');
 
@@ -52,9 +52,7 @@ module.exports = skipInNonExecutableProcess(function() {
 
         errors.push({
           message: `Property <${ propertyName }> is not a valid FEEL expression`,
-          path: path
-            ? [ ...path, propertyName ]
-            : [ propertyName ],
+          path: pathConcat(path || [], propertyName),
           data: {
             type: ERROR_TYPES.FEEL_EXPRESSION_INVALID,
             node,

package/rules/camunda-cloud/link-event.js

@@ -1,4 +1,4 @@
-const { getPath } = require('@bpmn-io/moddle-utils');
+const { getPath, pathConcat } = require('@bpmn-io/moddle-utils');
 
 const {
   is,
@@ -72,9 +72,7 @@ module.exports = skipInNonExecutableProcess(function() {
 
             reportErrors(linkCatchEvent, reporter, {
               message: `Property of type <bpmn:LinkEventDefinition> has property <name> with duplicate value of <${ name }>`,
-              path: path
-                ? [ ...path, 'name' ]
-                : [ 'name' ],
+              path: pathConcat(path || [], 'name'),
               data: {
                 type: ERROR_TYPES.ELEMENT_PROPERTY_VALUE_DUPLICATED,
                 node: linkEventDefinition,

package/rules/camunda-cloud/message-reference.js

@@ -5,6 +5,7 @@ const {
 
 const {
   getEventDefinition,
+  getReferencePath,
   hasProperties
 } = require('../utils/element');
 
@@ -45,11 +46,19 @@ module.exports = skipInNonExecutableProcess(function() {
 
     const messageRef = eventDefinitionOrReceiveTask.get('messageRef');
 
+    const nodePath = getReferencePath({
+      element: node,
+      referenceHolder: eventDefinitionOrReceiveTask,
+      referenceProperty: 'messageRef',
+      referencedRoot: messageRef,
+      node: messageRef
+    });
+
     errors = hasProperties(messageRef, {
       name: {
         required: true
       }
-    }, node);
+    }, node, nodePath);
 
     if (errors && errors.length) {
       reportErrors(node, reporter, errors);

package/rules/camunda-cloud/no-before-all-execution-listener.js

@@ -1,4 +1,4 @@
-const { getPath } = require('@bpmn-io/moddle-utils');
+const { getPath, pathConcat } = require('@bpmn-io/moddle-utils');
 
 const {
   findExtensionElement
@@ -30,7 +30,7 @@ module.exports = skipInNonExecutableProcess(function() {
       return [
         {
           message: `Property <eventType> of <zeebe:ExecutionListener> with value <beforeAll> only allowed by Camunda ${ ALLOWED_VERSION } or newer`,
-          path: [ ...getPath(listener, node), 'eventType' ],
+          path: pathConcat(getPath(listener, node), 'eventType'),
           data: {
             type: ERROR_TYPES.PROPERTY_VALUE_NOT_ALLOWED,
             node: listener,

package/rules/camunda-cloud/no-expression.js

@@ -2,7 +2,7 @@ const {
   is
 } = require('bpmnlint-utils');
 
-const { getPath } = require('@bpmn-io/moddle-utils');
+const { getPath, pathConcat } = require('@bpmn-io/moddle-utils');
 
 const {
   ERROR_TYPES,
@@ -103,9 +103,7 @@ function noExpression(node, propertyName, parentNode, allowedVersion) {
 
   return {
     message,
-    path: path
-      ? [ ...path, propertyName ]
-      : [ propertyName ],
+    path: pathConcat(path || [], propertyName),
     data
   };
 }

package/rules/camunda-cloud/no-task-schedule.js

@@ -1,3 +1,5 @@
+const { getPath, pathConcat } = require('@bpmn-io/moddle-utils');
+
 const { hasNoExtensionElement } = require('../utils/element');
 
 const { reportErrors } = require('../utils/reporter');
@@ -9,6 +11,29 @@ module.exports = skipInNonExecutableProcess(function() {
     const errors = hasNoExtensionElement(node, 'zeebe:TaskSchedule', node, '8.2');
 
     if (errors && errors.length) {
+
+      // add one leaf path per offending schedule field that is set, so consumers
+      // resolve entry ids render-agnostically
+      errors.forEach(error => {
+        const { extensionElement: taskSchedule } = error.data;
+
+        const path = getPath(taskSchedule, node);
+
+        const paths = [];
+
+        if (path && taskSchedule.get('dueDate')) {
+          paths.push(pathConcat(path, 'dueDate'));
+        }
+
+        if (path && taskSchedule.get('followUpDate')) {
+          paths.push(pathConcat(path, 'followUpDate'));
+        }
+
+        if (paths.length) {
+          error.paths = paths;
+        }
+      });
+
       reportErrors(node, reporter, errors);
     }
   }

package/rules/camunda-cloud/no-zeebe-properties.js

@@ -1,3 +1,5 @@
+const { getPath, pathConcat } = require('@bpmn-io/moddle-utils');
+
 const { hasNoExtensionElement } = require('../utils/element');
 
 const { reportErrors } = require('../utils/reporter');
@@ -9,6 +11,22 @@ module.exports = skipInNonExecutableProcess(function() {
     const errors = hasNoExtensionElement(node, 'zeebe:Properties', node, '8.1');
 
     if (errors && errors.length) {
+
+      // add one leaf path per offending property `name` field, so consumers
+      // resolve entry ids render-agnostically
+      errors.forEach(error => {
+        const { extensionElement } = error.data;
+
+        const paths = extensionElement.get('properties')
+          .map(property => getPath(property, node))
+          .filter(path => path)
+          .map(path => pathConcat(path, 'name'));
+
+        if (paths.length) {
+          error.paths = paths;
+        }
+      });
+
       reportErrors(node, reporter, errors);
     }
   }

package/rules/camunda-cloud/secrets.js

@@ -2,7 +2,7 @@ const { isString } = require('min-dash');
 
 const { is } = require('bpmnlint-utils');
 
-const { getPath } = require('@bpmn-io/moddle-utils');
+const { getPath, pathConcat } = require('@bpmn-io/moddle-utils');
 
 const {
   findExtensionElement,
@@ -99,9 +99,7 @@ function getReport(propertyName, node, parentNode) {
 
   return {
     message: `Property <${ propertyName }> uses deprecated secret expression format`,
-    path: path
-      ? [ ...getPath(node, parentNode), propertyName ]
-      : [ propertyName ],
+    path: pathConcat(path || [], propertyName),
     data: {
       type: ERROR_TYPES.SECRET_EXPRESSION_FORMAT_DEPRECATED,
       node,

package/rules/camunda-cloud/signal-reference.js

@@ -5,6 +5,7 @@ const {
 
 const {
   getEventDefinition,
+  getReferencePath,
   hasProperties
 } = require('../utils/element');
 
@@ -48,11 +49,19 @@ module.exports = skipInNonExecutableProcess(function() {
       return;
     }
 
+    const nodePath = getReferencePath({
+      element: node,
+      referenceHolder: eventDefinition,
+      referenceProperty: 'signalRef',
+      referencedRoot: signalRef,
+      node: signalRef
+    });
+
     errors = hasProperties(signalRef, {
       name: {
         required: true
       }
-    }, node);
+    }, node, nodePath);
 
     if (errors.length) {
       reportErrors(node, reporter, errors);

package/rules/camunda-cloud/subscription.js

@@ -6,6 +6,7 @@ const {
 const {
   findExtensionElement,
   getEventDefinition,
+  getReferencePath,
   hasExtensionElement,
   hasProperties
 } = require('../utils/element');
@@ -49,11 +50,19 @@ module.exports = skipInNonExecutableProcess(function() {
 
     const subscription = findExtensionElement(messageRef, 'zeebe:Subscription');
 
+    const nodePath = getReferencePath({
+      element: node,
+      referenceHolder: eventDefinitionOrReceiveTask,
+      referenceProperty: 'messageRef',
+      referencedRoot: messageRef,
+      node: subscription
+    });
+
     errors = hasProperties(subscription, {
       correlationKey: {
         required: true
       }
-    }, node);
+    }, node, nodePath);
 
     if (errors && errors.length) {
       reportErrors(node, reporter, errors);

package/rules/utils/element.js

@@ -16,7 +16,7 @@ const {
   isAny
 } = require('bpmnlint-utils');
 
-const { getPath } = require('@bpmn-io/moddle-utils');
+const { getPath, pathConcat } = require('@bpmn-io/moddle-utils');
 
 const { ERROR_TYPES } = require('./error-types');
 
@@ -24,6 +24,59 @@ const { greaterOrEqual } = require('./version');
 
 module.exports.ERROR_TYPES = ERROR_TYPES;
 
+/**
+ * Build the `{ paths }` fragment for a multi-field finding: one leaf moddle path
+ * per offending node, rooted at `parentNode`. Nodes whose path can't be resolved
+ * are dropped; the fragment is empty when none resolve, so the `paths` key is
+ * only present when it carries usable locations.
+ *
+ * @param {Array<Object>} nodes
+ * @param {string} propertyName leaf property appended to each node's path
+ * @param {Object} [parentNode]
+ *
+ * @returns {{ paths?: Array<Array<string|number>> }}
+ */
+function leafPaths(nodes, propertyName, parentNode = null) {
+  const paths = nodes
+    .map(node => getPath(node, parentNode))
+    .filter(path => isArray(path))
+    .map(path => pathConcat(path, propertyName));
+
+  return paths.length ? { paths } : {};
+}
+
+/**
+ * Build a moddle path that locates `node` relative to `element` by following a
+ * single reference edge.
+ *
+ * `getPath` (from @bpmn-io/moddle-utils) only walks containment (`$parent`), so
+ * it roots any referenced node at `bpmn:Definitions` — a path that cannot be
+ * resolved starting from `element`. This helper instead stitches together
+ *
+ *   getPath(referenceHolder, element) + referenceProperty + getPath(node, referencedRoot)
+ *
+ * yielding a path that resolves locally from `element`, because moddle
+ * `get(referenceProperty)` transparently follows the reference.
+ *
+ * @param {Object} options
+ * @param {Object} options.element root element the path is relative to
+ * @param {Object} options.referenceHolder node holding the reference (contained in `element`)
+ * @param {string} options.referenceProperty name of the reference property
+ * @param {Object} options.referencedRoot referenced root element
+ * @param {Object} options.node checked node (contained in `referencedRoot`)
+ *
+ * @returns {Array<string|number>|null} null when a segment can't be resolved
+ */
+function getReferencePath({ element, referenceHolder, referenceProperty, referencedRoot, node }) {
+  return pathConcat(
+    getPath(referenceHolder, element),
+    referenceProperty,
+    getPath(node, referencedRoot)
+  );
+}
+
+module.exports.getReferencePath = getReferencePath;
+
 function getEventDefinition(node) {
   const eventDefinitions = node.get('eventDefinitions');
 
@@ -121,6 +174,10 @@ module.exports.hasDuplicatedPropertyValues = function(node, propertiesName, prop
       return {
         message: `Properties of type <${ duplicateProperties[ 0 ].$type }> have property <${ propertyName }> with duplicate value of <${ duplicate }>`,
         path: null,
+
+        // one leaf path per offending field, so consumers resolve entry ids
+        // render-agnostically (template field vs. standard field)
+        ...leafPaths(duplicateProperties, propertyName, parentNode),
         data: {
           type: ERROR_TYPES.PROPERTY_VALUE_DUPLICATED,
           node,
@@ -169,6 +226,11 @@ module.exports.hasDuplicatedPropertiesValues = function(node, containerPropertyN
       return {
         message: `Properties of type <${ duplicate.$type }> have properties with duplicate values (${ duplicatesSummary })`,
         path: null,
+
+        // one leaf path per offending location; `type` is the field that
+        // represents the duplicated element in the properties panel, so
+        // consumers resolve its entry id render-agnostically
+        ...leafPaths(duplicateProperties, 'type', parentNode),
         data: {
           type: ERROR_TYPES.PROPERTY_VALUES_DUPLICATED,
           node,
@@ -184,13 +246,13 @@ module.exports.hasDuplicatedPropertiesValues = function(node, containerPropertyN
   return [];
 };
 
-module.exports.hasProperties = function(node, properties, parentNode = null) {
+module.exports.hasProperties = function(node, properties, parentNode = null, nodePath) {
   return Object.entries(properties).reduce((results, property) => {
     const [ propertyName, propertyChecks ] = property;
 
     const { allowedVersion = null } = propertyChecks;
 
-    const path = getPath(node, parentNode);
+    const path = nodePath === undefined ? getPath(node, parentNode) : nodePath;
 
     const propertyValue = node.get(propertyName);
 
@@ -201,9 +263,7 @@ module.exports.hasProperties = function(node, properties, parentNode = null) {
           message: allowedVersion
             ? `Element of type <${ node.$type }> without property <${ propertyName }> only allowed by Camunda ${ allowedVersion } or newer`
             : `Element of type <${ node.$type }> must have property <${ propertyName }>`,
-          path: path
-            ? [ ...path, propertyName ]
-            : [ propertyName ],
+          path: pathConcat(path || [], propertyName),
           data: addAllowedVersion({
             type: ERROR_TYPES.PROPERTY_REQUIRED,
             node,
@@ -222,9 +282,7 @@ module.exports.hasProperties = function(node, properties, parentNode = null) {
           ...results,
           {
             message: `Element of type <${ node.$type }> must have property <${ propertyName }> if it has property <${ propertyChecks.dependentRequired }>`,
-            path: path
-              ? [ ...path, propertyName ]
-              : [ propertyName ],
+            path: pathConcat(path || [], propertyName),
             data: {
               type: ERROR_TYPES.PROPERTY_DEPENDENT_REQUIRED,
               node,
@@ -252,9 +310,7 @@ module.exports.hasProperties = function(node, properties, parentNode = null) {
           message: allowedVersion
             ? `Property <${ propertyName }> of type <${ propertyValue.$type }> only allowed by Camunda ${ allowedVersion } or newer`
             : `Property <${ propertyName }> of type <${ propertyValue.$type }> not allowed`,
-          path: path
-            ? [ ...path, propertyName ]
-            : [ propertyName ],
+          path: pathConcat(path || [], propertyName),
           data: addAllowedVersion({
             type: ERROR_TYPES.PROPERTY_TYPE_NOT_ALLOWED,
             node,
@@ -271,9 +327,7 @@ module.exports.hasProperties = function(node, properties, parentNode = null) {
         ...results,
         {
           message: `Property <${ propertyName }> must have value of <${ propertyChecks.value }>`,
-          path: path
-            ? [ ...path, propertyName ]
-            : [ propertyName ],
+          path: pathConcat(path || [], propertyName),
           data: {
             type: ERROR_TYPES.PROPERTY_VALUE_REQUIRED,
             node,
@@ -292,9 +346,7 @@ module.exports.hasProperties = function(node, properties, parentNode = null) {
           message: allowedVersion
             ? `Property <${ propertyName }> only allowed by Camunda ${ allowedVersion } or newer`
             : `Property <${ propertyName }> not allowed`,
-          path: path
-            ? [ ...path, propertyName ]
-            : [ propertyName ],
+          path: pathConcat(path || [], propertyName),
           data: addAllowedVersion({
             type: ERROR_TYPES.PROPERTY_NOT_ALLOWED,
             node,
@@ -312,9 +364,7 @@ module.exports.hasProperties = function(node, properties, parentNode = null) {
           message: allowedVersion
             ? `Property value of <${ truncate(propertyValue) }> only allowed by Camunda ${ allowedVersion } or newer`
             : `Property value of <${ truncate(propertyValue) }> not allowed`,
-          path: path
-            ? [ ...path, propertyName ]
-            : [ propertyName ],
+          path: pathConcat(path || [], propertyName),
           data: addAllowedVersion({
             type: ERROR_TYPES.PROPERTY_VALUE_NOT_ALLOWED,
             node,
@@ -432,9 +482,7 @@ module.exports.hasExpression = function(node, propertyName, check, parentNode =
       return [
         {
           message: `Property <${ propertyName }> must have expression value`,
-          path: path
-            ? [ ...path, propertyName ]
-            : null,
+          path: pathConcat(path, propertyName),
           data: {
             type: ERROR_TYPES.EXPRESSION_REQUIRED,
             node: is(expression, 'bpmn:Expression') ? expression : node,
@@ -462,9 +510,7 @@ module.exports.hasExpression = function(node, propertyName, check, parentNode =
         message: allowedVersion
           ? `Expression value of <${ propertyValue }> only allowed by Camunda ${ allowedVersion }`
           : `Expression value of <${ propertyValue }> not allowed`,
-        path: path
-          ? [ ...path, propertyName ]
-          : null,
+        path: pathConcat(path, propertyName),
         data: addAllowedVersion({
           type: ERROR_TYPES.EXPRESSION_VALUE_NOT_ALLOWED,
           node: is(expression, 'bpmn:Expression') ? expression : node,