bpmnlint 11.1.0 → 11.3.0

package/lib/types.d.ts

@@ -1,5 +1,81 @@
 export type ModdleElement = any;
 
-export type EnterFn = (element: ModdleElement) => boolean | null;
+export interface Reporter {
 
-export type LeaveFn = (element: ModdleElement) => void;
+  report(id: string, message: string): void;
+
+  report(id: string, message: string, path: string[]): void;
+
+  report(id: string, message: string, context: {
+    path?: string[],
+    [key: string]: any
+  }) : void;
+}
+
+export interface Resolver {
+
+  resolveRule(pkg: string, ruleName: string): Promise<RuleFactory> | RuleFactory,
+
+  resolveConfig(pkg: string, configName: string): Promise<Config> | Config;
+}
+
+export type EnterFn = (element: ModdleElement, reporter: Reporter) => boolean | void;
+
+export type LeaveFn = (element: ModdleElement, reporter: Reporter) => void;
+
+export type CheckDefinition = EnterFn | {
+  enter: EnterFn
+} | {
+  leave: LeaveFn
+} | {
+  enter: EnterFn,
+  leave: LeaveFn
+};
+
+export type RuleDefinition = {
+  meta?: {
+    documentation?: {
+      url?: string
+    }
+  },
+  check: CheckDefinition
+};
+
+export type RuleFactory = (ruleOptions?: any) => RuleDefinition;
+
+export type ReportingCategoryMap = {
+  0: 'off',
+  1: 'warn',
+  2: 'error',
+  3: 'info'
+};
+
+export type ReportingCategoryIndex = keyof ReportingCategoryMap;
+export type ReportingCategory = ReportingCategoryMap[ReportingCategoryIndex];
+
+export type RuleErrorCategory = 'rule-error';
+
+export type RuleConfig =
+  ReportingCategoryIndex |
+  ReportingCategory |
+  [ ReportingCategoryIndex, config?: any ] |
+  [ ReportingCategory, config?: any ];
+
+export type RuleConfigs = Record<string, RuleConfig>;
+
+export type Config = {
+  extends?: string | string[],
+  rules?: RuleConfigs
+};
+
+export type TransformRuleFn = (
+  rule: RuleDefinition,
+  options: { pkg: string, ruleName: string }
+) => RuleDefinition;
+
+export type Report = {
+  id?: string,
+  path?: string[],
+  message: string,
+  [key: string]: any
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bpmnlint",
   "description": "Validate your BPMN diagrams based on configurable lint rules",
-  "version": "11.1.0",
+  "version": "11.3.0",
   "main": "lib/index.js",
   "keywords": [
     "bpmnlint",
@@ -27,8 +27,9 @@
   },
   "license": "MIT",
   "scripts": {
-    "all": "run-s lint test-coverage",
+    "all": "run-s lint lint:types test-coverage",
     "lint": "eslint .",
+    "lint:types": "tsc",
     "dev": "npm test -- --watch",
     "test": "mocha --exclude 'test/integration/*/**' 'test/**/*.*js'",
     "test-coverage": "nyc --reporter=lcov --reporter=html npm test",
@@ -44,22 +45,24 @@
     "bpmnlint-utils": "^1.1.1",
     "cli-table": "^0.3.11",
     "color-support": "^1.1.3",
-    "min-dash": "^4.2.2",
+    "min-dash": "^4.2.3",
     "mri": "^1.2.0",
     "pluralize": "^7.0.0",
     "tiny-glob": "^0.2.9"
   },
   "devDependencies": {
     "@bpmn-io/bpmnlint-generate-docs-images": "^0.4.0",
+    "@types/mocha": "^10.0.10",
     "chai": "^4.5.0",
     "eslint": "^9.17.0",
-    "eslint-plugin-bpmn-io": "^2.0.2",
+    "eslint-plugin-bpmn-io": "^2.2.0",
     "execa": "^9.5.2",
     "install-local": "^3.0.1",
     "mocha": "^11.0.1",
     "npm-run-all": "^4.1.5",
     "nyc": "^17.1.0",
-    "strip-indent": "^3.0.0"
+    "strip-indent": "^3.0.0",
+    "typescript": "^5.7.3"
   },
   "files": [
     "bin",

package/rules/ad-hoc-sub-process.js

@@ -3,11 +3,18 @@ const {
   isAny
 } = require('bpmnlint-utils');
 
+const {
+  annotateRule
+} = require('./helper');
+
+
 /**
  * A rule that ensures that an Ad Hoc Sub Process is valid according to the BPMN spec:
  *
  * - No start or end events
  * - Every intermediate event has an outgoing sequence flow
+ *
+ * @type { import('../lib/types.js').RuleFactory }
  */
 module.exports = function() {
 
@@ -38,8 +45,8 @@ module.exports = function() {
     });
   }
 
-  return {
+  return annotateRule('ad-hoc-sub-process', {
     check
-  };
+  });
 
 };

package/rules/conditional-flows.js

@@ -1,7 +1,14 @@
+const {
+  annotateRule
+} = require('./helper');
+
+
 /**
  * A rule that checks that sequence flows outgoing from a
  * conditional forking gateway or activity are
  * either default flows _or_ have a condition attached
+ *
+ * @type { import('../lib/types.js').RuleFactory }
  */
 module.exports = function() {
 
@@ -25,9 +32,9 @@ module.exports = function() {
     });
   }
 
-  return {
+  return annotateRule('conditional-flows', {
     check
-  };
+  });
 
 };
 

package/rules/end-event-required.js

@@ -3,9 +3,15 @@ const {
   isAny
 } = require('bpmnlint-utils');
 
+const {
+  annotateRule
+} = require('./helper');
+
 
 /**
  * A rule that checks the presence of an end event per scope.
+ *
+ * @type { import('../lib/types.js').RuleFactory }
  */
 module.exports = function() {
 
@@ -33,5 +39,7 @@ module.exports = function() {
     }
   }
 
-  return { check };
+  return annotateRule('end-event-required', {
+    check
+  });
 };

package/rules/event-sub-process-typed-start-event.js

@@ -2,9 +2,16 @@ const {
   is
 } = require('bpmnlint-utils');
 
+const {
+  annotateRule
+} = require('./helper');
+
+
 /**
  * A rule that checks that start events inside an event sub-process
  * are typed.
+ *
+ * @type { import('../lib/types.js').RuleFactory }
  */
 module.exports = function() {
 
@@ -30,8 +37,8 @@ module.exports = function() {
     });
   }
 
-  return {
+  return annotateRule('event-sub-process-typed-start-event', {
     check
-  };
+  });
 
 };

package/rules/fake-join.js

@@ -2,12 +2,19 @@ const {
   isAny
 } = require('bpmnlint-utils');
 
+const {
+  annotateRule
+} = require('./helper');
+
+
 /**
  * A rule that checks that no fake join is modeled by attempting
  * to give a task or event join semantics.
  *
  * Users should model a parallel joining gateway
  * to achieve the desired behavior.
+ *
+ * @type { import('../lib/types.js').RuleFactory }
  */
 module.exports = function() {
 
@@ -27,8 +34,8 @@ module.exports = function() {
     }
   }
 
-  return {
+  return annotateRule('fake-join', {
     check
-  };
+  });
 
 };

package/rules/global.js

@@ -3,6 +3,10 @@ const {
   isAny
 } = require('bpmnlint-utils');
 
+const {
+  annotateRule
+} = require('./helper');
+
 
 /**
  * A rule that verifies that global elements are properly used.
@@ -19,6 +23,8 @@ const {
  *   * element must have a name
  *   * element is referenced by at least one element
  *   * there exists only a single element per type with a given name
+ *
+ * @type { import('../lib/types.js').RuleFactory }
  */
 module.exports = function() {
 
@@ -48,9 +54,9 @@ module.exports = function() {
 
   }
 
-  return {
+  return annotateRule('global', {
     check
-  };
+  });
 
   // helpers /////////////////////////////
 

package/rules/helper.js

@@ -2,15 +2,26 @@ const {
   is
 } = require('bpmnlint-utils');
 
+/**
+ * @typedef { import('../lib/types.js').ModdleElement } ModdleElement
+ *
+ * @typedef { import('../lib/types.js').RuleFactory } RuleFactory
+ * @typedef { import('../lib/types.js').RuleDefinition } RuleDefinition
+ */
+
+
 /**
  * Create a checker that disallows the given element type.
  *
- * @param {String} type
+ * @param { string } type
  *
- * @return {Function} ruleImpl
+ * @return { RuleFactory } ruleFactory
  */
-function disallowNodeType(type) {
+function disallowNodeType(type, ruleName) {
 
+  /**
+   * @type { RuleFactory }
+   */
   return function() {
 
     function check(node, reporter) {
@@ -20,9 +31,9 @@ function disallowNodeType(type) {
       }
     }
 
-    return {
+    return annotateRule(ruleName, {
       check
-    };
+    });
 
   };
 
@@ -30,16 +41,15 @@ function disallowNodeType(type) {
 
 module.exports.disallowNodeType = disallowNodeType;
 
+
 /**
  * Find a parent for the given element
  *
- * @param {ModdleElement} node
+ * @param { ModdleElement } node
+ * @param { string } type
  *
- *  @param {String} type
- *
- * @return {ModdleElement} element
+ * @return { ModdleElement } element
  */
-
 function findParent(node, type) {
   if (!node) {
     return null;
@@ -58,4 +68,41 @@ function findParent(node, type) {
   return findParent(parent, type);
 }
 
-module.exports.findParent = findParent;
+module.exports.findParent = findParent;
+
+
+const documentationBaseUrl = 'https://github.com/bpmn-io/bpmnlint/blob/main/docs/rules';
+
+/**
+ * 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 = `${documentationBaseUrl}/${ruleName}.md`;
+
+  return {
+    meta: {
+      documentation: {
+        url: documentationUrl,
+        ...documentation
+      },
+      ...restMeta
+    },
+    ...restOptions
+  };
+}
+
+module.exports.annotateRule = annotateRule;

package/rules/label-required.js

@@ -3,9 +3,15 @@ const {
   isAny
 } = require('bpmnlint-utils');
 
+const {
+  annotateRule
+} = require('./helper');
+
 
 /**
  * A rule that checks the presence of a label.
+ *
+ * @type { import('../lib/types.js').RuleFactory }
  */
 module.exports = function() {
 
@@ -51,7 +57,9 @@ module.exports = function() {
     }
   }
 
-  return { check };
+  return annotateRule('label-required', {
+    check
+  });
 };
 
 

package/rules/link-event.js

@@ -6,6 +6,10 @@ const {
   is
 } = require('bpmnlint-utils');
 
+const {
+  annotateRule
+} = require('./helper');
+
 
 /**
  * A rule that verifies that link events are properly used.
@@ -18,6 +22,7 @@ const {
  *     with a given name, per scope
  *   * link events have a name
  *
+ * @type { import('../lib/types.js').RuleFactory }
  */
 module.exports = function() {
 
@@ -70,9 +75,9 @@ module.exports = function() {
 
   }
 
-  return {
+  return annotateRule('link-event', {
     check
-  };
+  });
 };
 
 

package/rules/no-bpmndi.js

@@ -6,9 +6,20 @@ const {
   flatten
 } = require('min-dash');
 
+const {
+  annotateRule
+} = require('./helper');
+
+/**
+ * @typedef { import('../lib/types.js').ModdleElement } ModdleElement
+ */
+
+
 /**
  * A rule that checks that there is no BPMNDI information missing for elements,
  * which require BPMNDI.
+ *
+ * @type { import('../lib/types.js').RuleFactory }
  */
 module.exports = function() {
 
@@ -35,9 +46,9 @@ module.exports = function() {
     });
   }
 
-  return {
+  return annotateRule('no-bpmndi', {
     check
-  };
+  });
 
 };
 
@@ -47,11 +58,12 @@ module.exports = function() {
 /**
  * Get all BPMN elements within a bpmn:Definitions node
  *
- * @param {array<ModdleElement>} rootElements - An array of Moddle rootElements
- * @return {array<Object>} A flat array with all BPMN elements, each represented with { id: elementId, $type: elementType }
+ * @param { ModdleElement[] } rootElements - An array of Moddle rootElements
  *
+ * @return { { id: string, $type: string }[] } A flat array with all BPMN elements, each represented with { id: elementId, $type: elementType }
  */
 function getAllBpmnElements(rootElements) {
+
   return flatten(rootElements.map((rootElement) => {
     const laneSet =
       rootElement.laneSets && rootElement.laneSets[0] || rootElement.childLaneSet;
@@ -66,7 +78,7 @@ function getAllBpmnElements(rootElements) {
     // * childLaneSets
     // * nested childLaneSets
     // * messageFlows
-    const elements = flatten([].concat(
+    const elements = flatten([
       rootElement.flowElements || [],
       (rootElement.flowElements && getAllBpmnElements(rootElement.flowElements.filter(hasFlowElements))) || [],
       rootElement.participants || [],
@@ -74,7 +86,7 @@ function getAllBpmnElements(rootElements) {
       laneSet && laneSet.lanes || [],
       laneSet && laneSet.lanes && getAllBpmnElements(laneSet.lanes.filter(hasChildLaneSet)) || [],
       rootElement.messageFlows || []
-    ));
+    ]);
 
     if (elements.length > 0) {
       return elements.map((element) => {
@@ -96,10 +108,10 @@ function getAllBpmnElements(rootElements) {
  * Get all BPMN elements within a bpmn:Definitions node
  *
  * @param {ModdleElement} definitionsNode - A moddleElement representing the
- * bpmn:Definitions element
- * @return {array<String>} A flat array with all BPMNDI element ids part of
- * this bpmn:Definitions node
+ *   bpmn:Definitions element
  *
+ * @return {string[]} ids of all BPMNDI element part of
+ *   this bpmn:Definitions node
  */
 function getAllDiBpmnReferences(definitionsNode) {
   return flatten(
@@ -115,16 +127,31 @@ function getAllDiBpmnReferences(definitionsNode) {
   );
 }
 
+/**
+ * @param { ModdleElement } element
+ *
+ * @return {boolean}
+ */
 function hasVisualRepresentation(element) {
   const noVisRepresentation = [ 'bpmn:DataObject' ];
 
   return noVisRepresentation.includes(element.$type) ? false : true;
 }
 
+/**
+ * @param { ModdleElement } element
+ *
+ * @return {boolean}
+ */
 function hasFlowElements(element) {
   return element.flowElements ? true : false;
 }
 
+/**
+ * @param { ModdleElement } element
+ *
+ * @return {boolean}
+ */
 function hasChildLaneSet(element) {
   return element.childLaneSet ? true : false;
 }

package/rules/no-complex-gateway.js

@@ -1,3 +1,3 @@
 const disallowNodeType = require('./helper').disallowNodeType;
 
-module.exports = disallowNodeType('bpmn:ComplexGateway');
+module.exports = disallowNodeType('bpmn:ComplexGateway', 'no-complex-gateway');

package/rules/no-disconnected.js

@@ -3,11 +3,16 @@ const {
   is
 } = require('bpmnlint-utils');
 
+const {
+  annotateRule
+} = require('./helper');
+
 
 /**
  * A rule that verifies that there exists no disconnected
- * flow elements, i.e. elements without incoming
- * _or_ outgoing sequence flows
+ * flow elements, i.e. elements without incoming or outgoing sequence flows.
+ *
+ * @type { import('../lib/types.js').RuleFactory }
  */
 module.exports = function() {
 
@@ -37,9 +42,9 @@ module.exports = function() {
     }
   }
 
-  return {
+  return annotateRule('no-disconnected', {
     check
-  };
+  });
 };
 
 

package/rules/no-duplicate-sequence-flows.js

@@ -2,10 +2,16 @@ const {
   is
 } = require('bpmnlint-utils');
 
+const {
+  annotateRule
+} = require('./helper');
+
+
 /**
  * A rule that verifies that there are no disconnected
- * flow elements, i.e. elements without incoming
- * _or_ outgoing sequence flows
+ * flow elements, i.e. elements without incoming or outgoing sequence flows.
+ *
+ * @type { import('../lib/types.js').RuleFactory }
  */
 module.exports = function() {
 
@@ -44,9 +50,9 @@ module.exports = function() {
     }
   }
 
-  return {
+  return annotateRule('no-duplicate-sequence-flows', {
     check
-  };
+  });
 
 };
 

package/rules/no-gateway-join-fork.js

@@ -2,10 +2,16 @@ const {
   is
 } = require('bpmnlint-utils');
 
+const {
+  annotateRule
+} = require('./helper');
+
 
 /**
  * A rule that checks, whether a gateway forks and joins
  * at the same time.
+ *
+ * @type { import('../lib/types.js').RuleFactory }
  */
 module.exports = function() {
 
@@ -23,8 +29,8 @@ module.exports = function() {
     }
   }
 
-  return {
+  return annotateRule('no-gateway-fork-join', {
     check
-  };
+  });
 
 };

package/rules/no-implicit-end.js

@@ -4,11 +4,15 @@ const {
 } = require('bpmnlint-utils');
 
 const {
-  findParent
+  findParent,
+  annotateRule
 } = require('./helper');
 
+
 /**
  * A rule that checks that an element is not an implicit end (token sink).
+ *
+ * @type { import('../lib/types.js').RuleFactory }
  */
 module.exports = function() {
 
@@ -85,5 +89,7 @@ module.exports = function() {
     }
   }
 
-  return { check };
+  return annotateRule('no-implicit-end', {
+    check
+  });
 };