@camunda/linting 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to [@camunda/linting](https://github.com/camunda/linting) are documented here. We use [semantic versioning](http://semver.org/) for releases.
+
+## Unreleased
+
+___Note:__ Yet to be released changes appear here._
+
+## 0.1.0
+
+* `FEAT`: initial release bundling [bpmnlint](https://github.com/bpmn-io/bpmnlint) and [bpmnlint-plugin-camunda-compat](https://github.com/camunda/bpmnlint-plugin-camunda-compat/) and Camunda specific functionality ([#1](https://github.com/camunda/linting/pull/1))

package/README.md

@@ -0,0 +1,27 @@
+# @camunda/linting
+
+The BPMN linter used by the Camunda Desktop and Web Modeler. Batteries included. 🔋
+
+# Features
+
+* bundles [bpmnlint](https://github.com/bpmn-io/bpmnlint) and [bpmnlint-plugin-camunda-compat](https://github.com/camunda/bpmnlint-plugin-camunda-compat/)
+* configures linter based on `modeler:executionPlatform` and `modeler:executionPlatformVersion`
+* adjusts error messages to be shown in desktop and web modeler
+
+# Usage
+
+```javascript
+import { Linter } from '@camunda/linting';
+
+...
+
+// lint by passing definitions
+const reports = await Linter.lint(definitions);
+
+// or passing XML
+const reports = await Linter.lint(xml);
+```
+
+# License
+
+MIT

package/index.js

@@ -0,0 +1 @@
+export { Linter } from './lib/Linter';

package/lib/Linter.js

@@ -0,0 +1,116 @@
+import BpmnModdle from 'bpmn-moddle/dist/index';
+
+import { Linter as BpmnLinter } from 'bpmnlint';
+
+import StaticResolver from 'bpmnlint/lib/resolver/static-resolver';
+
+import { configs } from 'bpmnlint-plugin-camunda-compat';
+
+import { isString } from 'min-dash';
+
+import modelerModdle from 'modeler-moddle/resources/modeler.json';
+import zeebeModdle from 'zeebe-bpmn-moddle/resources/zeebe.json';
+
+import { adjustErrorMessages } from './utils/error-messages';
+
+const moddle = new BpmnModdle({
+  modeler: modelerModdle,
+  zeebe: zeebeModdle
+});
+
+export class Linter {
+  static async lint(contents) {
+    let rootElement;
+
+    if (isString(contents)) {
+      ({ rootElement } = await moddle.fromXML(contents));
+    } else {
+      rootElement = contents;
+    }
+
+    const executionPlatform = rootElement.get('modeler:executionPlatform'),
+          executionPlatformVersion = rootElement.get('modeler:executionPlatformVersion');
+
+    if (!executionPlatform || !executionPlatformVersion) {
+      return [];
+    }
+
+    const configName = getConfigName(executionPlatform, executionPlatformVersion);
+
+    const config = configs[ configName ];
+
+    if (!config) {
+      return [];
+    }
+
+    const rules = await importRules(config);
+
+    const linter = new BpmnLinter({
+      config: prefixRules(config),
+      resolver: new StaticResolver(rules)
+    });
+
+    let reports = await linter.lint(rootElement);
+
+    reports = adjustErrorMessages(reports, getExecutionPlatformLabel(executionPlatform, toSemverMinor(executionPlatformVersion)));
+
+    return Object.values(reports).reduce((reports, report) => {
+      return [ ...reports, ...report ];
+    }, []);
+  }
+}
+
+function getConfigName(executionPlatform, executionPlatformVersion) {
+  return [
+    ...executionPlatform.split(' ').map(toLowerCase),
+    ...toSemverMinor(executionPlatformVersion).split('.')
+  ].join('-');
+}
+
+function prefixRules({ rules }) {
+  return {
+    rules: Object.entries(rules).reduce((rules, [ key, value ]) => {
+      return {
+        ...rules,
+        [ `bpmnlint-plugin-camunda-compat/${ key }` ]: value
+      };
+    }, {})
+  };
+}
+
+async function importRules({ rules }) {
+  let importedRules = {};
+
+  for (let key of Object.keys(rules)) {
+    const importedRule = require(`bpmnlint-plugin-camunda-compat/rules/${ key }`);
+
+    importedRules = {
+      ...importedRules,
+      [ `rule:bpmnlint-plugin-camunda-compat/${ key }` ]: importedRule
+    };
+  }
+
+  return importedRules;
+}
+
+const executionPlatformLabels = {
+  'Camunda Cloud': {
+    '1.0': 'Camunda 8 (Zeebe 1.0)',
+    '1.1': 'Camunda 8 (Zeebe 1.1)',
+    '1.2': 'Camunda 8 (Zeebe 1.2)',
+    '1.3': 'Camunda 8 (Zeebe 1.3)',
+    '8.0': 'Camunda 8'
+  }
+};
+
+function getExecutionPlatformLabel(executionPlatform, executionPlatformVersion) {
+  return executionPlatformLabels[ executionPlatform ] && executionPlatformLabels[ executionPlatform ][ executionPlatformVersion ];
+}
+
+function toLowerCase(string) {
+  return string.toLowerCase();
+}
+
+function toSemverMinor(executionPlatformVersion) {
+  return executionPlatformVersion.split('.').slice(0, 2).join('.');
+}

package/lib/utils/error-messages.js

@@ -0,0 +1,247 @@
+import { ERROR_TYPES } from 'bpmnlint-plugin-camunda-compat/rules/utils/element';
+
+import { is } from 'bpmnlint-utils';
+
+import { isArray } from 'min-dash';
+
+import { getTypeString } from './types';
+
+export function adjustErrorMessage(report, executionPlatformLabel) {
+  const {
+    error,
+    message
+  } = report;
+
+  if (!error) {
+    return report;
+  }
+
+  const { type } = error;
+
+  if (type === ERROR_TYPES.ELEMENT_TYPE_NOT_ALLOWED) {
+    return getElementTypeNotAllowedErrorMessage(report, executionPlatformLabel);
+  }
+
+  if (type === ERROR_TYPES.EXTENSION_ELEMENT_NOT_ALLOWED) {
+    return getExtensionElementNotAllowedErrorMessage(report, executionPlatformLabel);
+  }
+
+  if (type === ERROR_TYPES.EXTENSION_ELEMENT_REQUIRED) {
+    return getExtensionElementRequiredErrorMessage(report);
+  }
+
+  if (type === ERROR_TYPES.PROPERTY_DEPENDEND_REQUIRED) {
+    return getPropertyDependendRequiredErrorMessage(report);
+  }
+
+  if (type === ERROR_TYPES.PROPERTY_REQUIRED) {
+    return getPropertyRequiredErrorMessage(report, executionPlatformLabel);
+  }
+
+  if (type === ERROR_TYPES.PROPERTY_TYPE_NOT_ALLOWED) {
+    return getPropertyTypeNotAllowedErrorMessage(report, executionPlatformLabel);
+  }
+
+  return message;
+}
+
+export function adjustErrorMessages(reports, executionPlatformLabel) {
+  Object.values(reports).forEach(reportsForRule => {
+    reportsForRule.forEach(report => {
+      report.message = adjustErrorMessage(report, executionPlatformLabel);
+    });
+  });
+
+  return reports;
+}
+
+function getIndefiniteArticle(type) {
+  if ([
+    'Error',
+    'Escalation',
+    'Event',
+    'Intermediate',
+    'Undefined'
+  ].includes(type.split(' ')[ 0 ])) {
+    return 'An';
+  }
+
+  return 'A';
+}
+
+function getElementTypeNotAllowedErrorMessage(report, executionPlatformLabel) {
+  const { error } = report;
+
+  const { node } = error;
+
+  const typeString = getTypeString(node);
+
+  return `${ getIndefiniteArticle(typeString) } <${ typeString }> is not supported by ${ executionPlatformLabel }`;
+}
+
+function getExtensionElementNotAllowedErrorMessage(report, executionPlatformLabel) {
+  const {
+    error,
+    message
+  } = report;
+
+  const {
+    node,
+    extensionElement
+  } = error;
+
+  if (is(node, 'bpmn:BusinessRuleTask') && is(extensionElement, 'zeebe:CalledDecision')) {
+    return `A <Business Rule Task> with <Implementation: DMN decision> is not supported by ${ executionPlatformLabel }`;
+  }
+
+  return message;
+}
+
+function getExtensionElementRequiredErrorMessage(report) {
+  const {
+    error,
+    message
+  } = report;
+
+  const {
+    node,
+    parentNode,
+    requiredExtensionElement
+  } = error;
+
+  const typeString = getTypeString(parentNode || node);
+
+  if (requiredExtensionElement === 'zeebe:CalledElement') {
+    return `${ getIndefiniteArticle(typeString) } <${ typeString }> must have a defined <Called element>`;
+  }
+
+  if (requiredExtensionElement === 'zeebe:LoopCharacteristics') {
+    return `${ getIndefiniteArticle(typeString) } <${ typeString }> with <Multi-instance marker> must have a defined <Input collection>`;
+  }
+
+  if (requiredExtensionElement === 'zeebe:Subscription') {
+    return `${ getIndefiniteArticle(typeString) } <${ typeString }> with <Message Reference> must have a defined <Subscription correlation key>`;
+  }
+
+  if (requiredExtensionElement === 'zeebe:TaskDefinition') {
+    return `${ getIndefiniteArticle(typeString) } <${ typeString }> must have a <Task definition type>`;
+  }
+
+  if (isArray(requiredExtensionElement) && requiredExtensionElement.includes('zeebe:CalledDecision')) {
+    return `${ getIndefiniteArticle(typeString) } <${ typeString }> must have a defined <Implementation>`;
+  }
+
+  return message;
+}
+
+function getPropertyDependendRequiredErrorMessage(report) {
+  const {
+    error,
+    message
+  } = report;
+
+  const {
+    node,
+    parentNode,
+    property,
+    dependendRequiredProperty
+  } = error;
+
+  const typeString = getTypeString(parentNode || node);
+
+  if (is(node, 'zeebe:LoopCharacteristics') && property === 'outputCollection' && dependendRequiredProperty === 'outputElement') {
+    return `${ getIndefiniteArticle(typeString) } <${ typeString }> with <Multi-instance marker> and defined <Output collection> must have a defined <Output element>`;
+  }
+
+  if (is(node, 'zeebe:LoopCharacteristics') && property === 'outputElement' && dependendRequiredProperty === 'outputCollection') {
+    return `${ getIndefiniteArticle(typeString) } <${ typeString }> with <Multi-instance marker> and defined <Output element> must have a defined <Output collection>`;
+  }
+
+  return message;
+}
+
+function getPropertyRequiredErrorMessage(report, executionPlatformLabel) {
+  const {
+    error,
+    message
+  } = report;
+
+  const {
+    node,
+    parentNode,
+    requiredProperty
+  } = error;
+
+  const typeString = getTypeString(parentNode || node);
+
+  if (parentNode && is(parentNode, 'bpmn:BusinessRuleTask') && is(node, 'zeebe:CalledDecision') && requiredProperty === 'decisionId') {
+    return 'A <Business Rule Task> with <Implementation: DMN decision> must have a defined <Called decision ID>';
+  }
+
+  if (parentNode && is(parentNode, 'bpmn:BusinessRuleTask') && is(node, 'zeebe:CalledDecision') && requiredProperty === 'resultVariable') {
+    return 'A <Business Rule Task> with <Implementation: DMN decision> must have a defined <Result variable>';
+  }
+
+  if (parentNode && is(parentNode, 'bpmn:BusinessRuleTask') && is(node, 'zeebe:TaskDefinition') && requiredProperty === 'type') {
+    return 'A <Business Rule Task> with <Implementation: Job worker> must have a defined <Task definition type>';
+  }
+
+  if (is(node, 'zeebe:CalledElement') && requiredProperty === 'processId') {
+    return `${ getIndefiniteArticle(typeString) } <${ typeString }> must have a defined <Called element>`;
+  }
+
+  if (is(node, 'bpmn:Error') && requiredProperty === 'errorCode') {
+    return `${ getIndefiniteArticle(typeString) } <${ typeString }> with <Error Reference> must have a defined <Error code>`;
+  }
+
+  if (is(node, 'bpmn:Event') && requiredProperty === 'eventDefinitions') {
+    return `${ getIndefiniteArticle(typeString) } <${ typeString }> is not supported by ${ executionPlatformLabel }`;
+  }
+
+  if (is(node, 'zeebe:LoopCharacteristics') && requiredProperty === 'inputCollection') {
+    return `${ getIndefiniteArticle(typeString) } <${ typeString }> with <Multi-instance marker> must have a defined <Input collection>`;
+  }
+
+  if (is(node, 'bpmn:Message') && requiredProperty === 'name') {
+    return `${ getIndefiniteArticle(typeString) } <${ typeString }> with <Message Reference> must have a defined <Name>`;
+  }
+
+  if (is(node, 'zeebe:Subscription') && requiredProperty === 'correlationKey') {
+    return `${ getIndefiniteArticle(typeString) } <${ typeString }> with <Message Reference> must have a defined <Subscription correlation key>`;
+  }
+
+  if (is(node, 'zeebe:TaskDefinition') && requiredProperty === 'type') {
+    return `${ getIndefiniteArticle(typeString) } <${ typeString }> with <Implementation: Job worker> must have a defined <Task definition type>`;
+  }
+
+  if (requiredProperty === 'errorRef') {
+    return `${ getIndefiniteArticle(typeString) } <${ typeString }> must have a defined <Error Reference>`;
+  }
+
+  if (requiredProperty === 'messageRef') {
+    return `${ getIndefiniteArticle(typeString) } <${ typeString }> must have a defined <Message Reference>`;
+  }
+
+  return message;
+}
+
+function getPropertyTypeNotAllowedErrorMessage(report, executionPlatformLabel) {
+  const {
+    error,
+    message
+  } = report;
+
+  const {
+    node,
+    parentNode,
+    property
+  } = error;
+
+  const typeString = getTypeString(parentNode || node);
+
+  if (is(node, 'bpmn:Event') && property === 'eventDefinitions') {
+    return `${ getIndefiniteArticle(typeString) } <${ typeString }> is not supported by ${ executionPlatformLabel }`;
+  }
+
+  return message;
+}

package/lib/utils/types.js

@@ -0,0 +1,47 @@
+function getEventDefinition(node) {
+  const eventDefinitions = node.get('eventDefinitions');
+
+  return eventDefinitions && eventDefinitions[ 0 ];
+}
+
+function getEventDefinitionPrefix(eventDefinition) {
+  const localType = getLocalType(eventDefinition);
+
+  return localType.replace('EventDefinition', '');
+}
+
+function getLocalType(node) {
+  const { $descriptor } = node;
+
+  const { localName } = $descriptor.ns;
+
+  return localName;
+}
+
+function formatTypeString(string) {
+  return string.replace(/([a-z])([A-Z])/g, '$1 $2').trim();
+}
+
+export function getTypeString(node) {
+  let type = getLocalType(node);
+
+  const eventDefinition = getEventDefinition(node);
+
+  if (eventDefinition) {
+    type = `${ getEventDefinitionPrefix(eventDefinition) }${ type }`;
+  } else if ([
+    'BoundaryEvent',
+    'EndEvent',
+    'IntermediateCatchEvent',
+    'IntermediateThrowEvent',
+    'StartEvent'
+  ].includes(type)) {
+    type = `Undefined ${ type }`;
+  }
+
+  if (type === 'Task') {
+    type = 'Undefined Task';
+  }
+
+  return formatTypeString(type);
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@camunda/linting",
+  "version": "0.1.0",
+  "description": "Linting for Camunda Platform",
+  "main": "index.js",
+  "scripts": {
+    "all": "npm run lint && npm test",
+    "lint": "eslint .",
+    "test": "mocha -r esm --reporter=spec --recursive test/spec",
+    "test:watch": "npm run test -- --watch"
+  },
+  "keywords": [
+    "bpmnlint",
+    "camunda"
+  ],
+  "author": {
+    "name": "Philipp Fromme",
+    "url": "https://github.com/philippfromme"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "bpmnlint": "^7.8.0",
+    "bpmnlint-plugin-camunda-compat": "^0.7.0",
+    "bpmnlint-utils": "^1.0.2"
+  },
+  "devDependencies": {
+    "bpmn-moddle": "^7.1.2",
+    "chai": "^4.3.6",
+    "eslint": "^4.11.0",
+    "eslint-plugin-bpmn-io": "^0.4.1",
+    "esm": "^3.2.25",
+    "min-dash": "^3.8.1",
+    "mocha": "^4.0.1",
+    "modeler-moddle": "^0.2.0",
+    "zeebe-bpmn-moddle": "^0.12.1"
+  },
+  "files": [
+    "lib"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}