feat(rules): attach documentation URLs

Previously we injected them via camunda/linting, now we can use the new meta infrastructure provided by bpmnlint itself. Related to bpmn-io/bpmnlint#165
camunda · Feb 18, 2025 · 974999f · 974999f
1 parent 3c936f0
commit 974999f
Show file tree

Hide file tree

Showing 9 changed files with 68 additions and 14 deletions.
diff --git a/rules/camunda-cloud/called-element.js b/rules/camunda-cloud/called-element.js
@@ -6,6 +6,8 @@ const {
   hasProperties
 } = require('../utils/element');
 
+const { annotateRule } = require('../helper');
+
 const { reportErrors } = require('../utils/reporter');
 
 const { skipInNonExecutableProcess } = require('../utils/rule');
@@ -37,7 +39,7 @@ module.exports = skipInNonExecutableProcess(function() {
     }
   }
 
-  return {
+  return annotateRule('called-element', {
     check
-  };
+  });
 });
diff --git a/rules/camunda-cloud/element-type/index.js b/rules/camunda-cloud/element-type/index.js
@@ -14,6 +14,8 @@ const { reportErrors } = require('../../utils/reporter');
 
 const { skipInNonExecutableProcess } = require('../../utils/rule');
 
+const { annotateRule } = require('../../helper');
+
 module.exports = skipInNonExecutableProcess(function({ version }) {
   function check(node, reporter) {
     if (!isAny(node, [ 'bpmn:FlowElement', 'bpmn:FlowElementsContainer' ])) {
@@ -128,7 +130,7 @@ module.exports = skipInNonExecutableProcess(function({ version }) {
     }
   }
 
-  return {
+  return annotateRule('element-type', {
     check
-  };
+  });
 });
diff --git a/rules/camunda-cloud/error-reference.js b/rules/camunda-cloud/error-reference.js
@@ -13,6 +13,7 @@ const { reportErrors } = require('../utils/reporter');
 const { skipInNonExecutableProcess } = require('../utils/rule');
 
 const { greaterOrEqual } = require('../utils/version');
+const { annotateRule } = require('../helper');
 
 const noErrorRefAllowedVersion = '8.2';
 
@@ -62,9 +63,9 @@ module.exports = skipInNonExecutableProcess(function({ version }) {
     }
   }
 
-  return {
+  return annotateRule('error-reference', {
     check
-  };
+  });
 });
 
 function isNoErrorRefAllowed(node, version) {

diff --git a/rules/camunda-cloud/escalation-reference.js b/rules/camunda-cloud/escalation-reference.js
@@ -11,6 +11,7 @@ const {
 const { reportErrors } = require('../utils/reporter');
 
 const { skipInNonExecutableProcess } = require('../utils/rule');
+const { annotateRule } = require('../helper');
 
 module.exports = skipInNonExecutableProcess(function() {
   function check(node, reporter) {
@@ -57,9 +58,9 @@ module.exports = skipInNonExecutableProcess(function() {
     }
   }
 
-  return {
+  return annotateRule('escalation-reference', {
     check
-  };
+  });
 });
 
 function isNoEscalationRefAllowed(node) {

diff --git a/rules/camunda-cloud/feel.js b/rules/camunda-cloud/feel.js
@@ -14,6 +14,7 @@ const { reportErrors } = require('../utils/reporter');
 const { ERROR_TYPES } = require('../utils/error-types');
 
 const { skipInNonExecutableProcess } = require('../utils/rule');
+const { annotateRule } = require('../helper');
 
 module.exports = skipInNonExecutableProcess(function() {
   function check(node, reporter) {
@@ -64,9 +65,9 @@ module.exports = skipInNonExecutableProcess(function() {
     }
   }
 
-  return {
+  return annotateRule('feel', {
     check
-  };
+  });
 });
 
 const isFeelProperty = ([ propertyName, value ]) => {

diff --git a/rules/camunda-cloud/message-reference.js b/rules/camunda-cloud/message-reference.js
@@ -11,6 +11,7 @@ const {
 const { reportErrors } = require('../utils/reporter');
 
 const { skipInNonExecutableProcess } = require('../utils/rule');
+const { annotateRule } = require('../helper');
 
 module.exports = skipInNonExecutableProcess(function() {
   function check(node, reporter) {
@@ -55,7 +56,7 @@ module.exports = skipInNonExecutableProcess(function() {
     }
   }
 
-  return {
+  return annotateRule('message-reference', {
     check
-  };
+  });
 });
diff --git a/rules/camunda-cloud/zeebe-user-task.js b/rules/camunda-cloud/zeebe-user-task.js
@@ -20,6 +20,11 @@ module.exports = skipInNonExecutableProcess(function() {
   }
 
   return {
+    meta: {
+      documentation: {
+        url: 'https://docs.camunda.io/docs/next/apis-tools/migration-manuals/migrate-to-zeebe-user-tasks'
+      }
+    },
     check
   };
 });
diff --git a/rules/camunda-platform/history-time-to-live.js b/rules/camunda-platform/history-time-to-live.js
@@ -1,5 +1,7 @@
 const { is } = require('bpmnlint-utils');
 
+const { annotateRule } = require('../helper');
+
 const { skipInNonExecutableProcess } = require('../utils/rule');
 
 module.exports = skipInNonExecutableProcess(function() {
@@ -14,7 +16,7 @@ module.exports = skipInNonExecutableProcess(function() {
     }
   }
 
-  return {
+  return annotateRule('history-time-to-live', {
     check
-  };
+  });
 });
diff --git a/rules/helper.js b/rules/helper.js
@@ -0,0 +1,39 @@
+const modelingGuidanceBaseUrl = 'https://docs.camunda.io/docs/next/components/modeler/reference/modeling-guidance/rules';
+
+/**
+ * @typedef { any } RuleDefinition
+ */
+
+/**
+ * Annotate a rule with core information, such as the documentation url.
+ *
+ * @param { string } ruleName
+ * @param { RuleDefinition } options
+ *
+ * @return { RuleDefinition }
+ */
+function annotateRule(ruleName, options) {
+
+  const {
+    meta: {
+      documentation = {},
+      ...restMeta
+    } = {},
+    ...restOptions
+  } = options;
+
+  const documentationUrl = `${modelingGuidanceBaseUrl}/${ruleName}.md`;
+
+  return {
+    meta: {
+      documentation: {
+        url: documentationUrl,
+        ...documentation
+      },
+      ...restMeta
+    },
+    ...restOptions
+  };
+}
+
+module.exports.annotateRule = annotateRule;