bpmnlint 8.1.1 → 8.3.0

package/README.md

@@ -37,7 +37,7 @@ Validate your diagrams via the commandline:
 
 Our [documentation](https://github.com/bpmn-io/bpmnlint/tree/master/docs/rules#rules) lists all currenty implemented rules, the [`./rules` folder](https://github.com/bpmn-io/bpmnlint/tree/master/rules) contains each rules implementation.
 
-Do you miss a rule that should be included? [Propose a new rule](https://github.com/bpmn-io/bpmnlint/issues/new?template=NEW_RULE.md).
+Do you miss a rule that should be included? [Propose a new rule](https://github.com/bpmn-io/bpmnlint/issues/new?assignees=&labels=rules&template=NEW_RULE.md).
 
 
 ## Configuration
@@ -62,6 +62,66 @@ Add or customize rules using the `rules` block:
 ```
 
 
+## API
+
+Invoke the tool directly from [NodeJS](https://nodejs.org/en):
+
+```javascript
+import Linter from 'bpmnlint';
+import NodeResolver from 'bpmnlint/lib/resolver/node-resolver';
+
+import BpmnModdle from 'bpmn-moddle';
+
+const linter = new Linter({ 
+  config: {
+    extends: 'bpmnlint:recommended'
+  },
+  resolver: new NodeResolver()
+});
+
+const xmlStr = `
+  <?xml version="1.0" encoding="UTF-8"?>
+  <bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" 
+                     id="definitions" 
+                     targetNamespace="http://bpmn.io/schema/bpmn">
+    <bpmn:process id="process" />
+  </bpmn:definitions>
+`;
+
+const {
+  rootElement: definitions
+} = await moddle.fromXML(xmlStr);
+
+const reports = linter.lint(definitions);
+
+// {
+//    "end-event-required": [
+//      {
+//        "id": "process",
+//        "message": "Process is missing end event"
+//      }
+//    ],
+//    ...
+// }
+```
+
+
+## Writing a Plug-in
+
+Create your first plug-in using the [plugin creator](https://github.com/nikku/create-bpmnlint-plugin):
+
+```sh
+npm init bpmnlint-plugin {PLUGIN_NAME}
+```
+
+Checkout the [bpmnlint-plugin-example](https://github.com/bpmn-io/bpmnlint-plugin-example) for details on how to define, test, and consume custom lint rules. Use the [bpmnlint playground](https://github.com/bpmn-io/bpmnlint-playground) to implement new rules with quick visual feedback.
+
+
+## Bundling
+
+For browser usage include your [linting configuration](#configuration) using your favorite bundler plug-in ([Rollup](https://www.npmjs.com/package/rollup-plugin-bpmnlint), [Webpack](https://www.npmjs.com/package/bpmnlint-loader)).
+
+
 ## Visual Feedback
 
 Integrate the linter via [bpmn-js-bpmnlint](https://github.com/bpmn-io/bpmn-js-bpmnlint) into [bpmn-js](https://github.com/bpmn-io/bpmn-js) and get direct feedback during modeling.
@@ -69,13 +129,12 @@ Integrate the linter via [bpmn-js-bpmnlint](https://github.com/bpmn-io/bpmn-js-b
 To try out visual validation, checkout the [bpmnlint playground](https://github.com/bpmn-io/bpmnlint-playground).
 
 
-## Writing / Consuming Custom Rules
-
-Use the [bpmnlint playground](https://github.com/bpmn-io/bpmnlint-playground) to implement new rules with quick visual feedback.
-
-Create your first plug-in using the [plugin creator](https://github.com/nikku/create-bpmnlint-plugin).
+## Related
 
-Checkout the [bpmnlint-plugin-example](https://github.com/bpmn-io/bpmnlint-plugin-example) for details on how to define, test, and consume custom lint rules.
+* [bpmnlint-plugin-example](https://github.com/bpmn-io/bpmnlint-plugin-example) - an example plug-in
+* [bpmnlint-playground](https://github.com/bpmn-io/bpmnlint-playground) - a playground to implement new rules with quick visual feedback
+* [bpmnlint-generate-docs-images](https://github.com/bpmn-io/bpmnlint-generate-docs-images) - Generate images for your bpmnlint documentation
+* [bpmn-js-bpmnlint](https://github.com/bpmn-io/bpmn-js-bpmnlint) - integration into [bpmn-js](https://github.com/bpmn-io/bpmn-js)
 
 
 ## License

package/config/all.js

@@ -10,6 +10,8 @@ const allRules = [
   'no-duplicate-sequence-flows',
   'no-gateway-join-fork',
   'no-implicit-split',
+  'no-implicit-end',
+  'no-implicit-start',
   'no-inclusive-gateway',
   'single-blank-start-event',
   'single-event-definition',

package/config/recommended.js

@@ -11,6 +11,8 @@ module.exports = {
     'no-duplicate-sequence-flows': 'error',
     'no-gateway-join-fork': 'error',
     'no-implicit-split': 'error',
+    'no-implicit-end': 'error',
+    'no-implicit-start': 'error',
     'no-inclusive-gateway': 'error',
     'single-blank-start-event': 'error',
     'single-event-definition': 'error',

package/lib/linter.js

@@ -3,7 +3,8 @@ const testRule = require('./test-rule');
 const categoryMap = {
   0: 'off',
   1: 'warn',
-  2: 'error'
+  2: 'error',
+  3: 'info'
 };
 
 

package/lib/resolver/node-resolver.js

@@ -1,6 +1,8 @@
 const Module = require('module');
 const path = require('path');
 
+const { isString } = require('min-dash');
+
 /**
  * A resolver that locates rules and configurations
  * using node module resolution.
@@ -26,15 +28,48 @@ NodeResolver.prototype.resolveRule = function(pkg, ruleName) {
 
   pkg = this.normalizePkg(pkg);
 
+  let pkgInstance;
+
+  // (1) try resolving rule via $PKG.rules[$NAME]
+  try {
+    pkgInstance = this.require(pkg);
+  } catch (err) {
+
+    /* ignore */
+  }
+
+  if (pkgInstance) {
+    const rules = pkgInstance.rules || {};
+
+    if (ruleName in rules) {
+      const rule = rules[ruleName];
+
+      if (!isString(rule)) {
+        throw new Error('cannot resolve rule <' + ruleName + '> from <' + originalPkg + '>: illegal rule export (expected path reference)');
+      }
+
+      // local reference, resolved relative to pkg location
+      if (rule.startsWith('.')) {
+        const pkgDir = path.dirname(this.require.resolve(pkg));
+
+        return this.require(path.posix.normalize(`${ pkgDir }/${ rule }`));
+      }
+
+      // absolute reference
+      return this.require(rule);
+    }
+  }
+
+  // (2) try resolving rule via $PKG/rules/$NAME
   try {
     if (pkg === 'bpmnlint') {
       return this.requireLocal(`../../rules/${ruleName}`);
     } else {
       return this.require(`${pkg}/rules/${ruleName}`);
     }
-  } catch (err) {
-    throw new Error('Cannot resolve rule <' + ruleName + '> from <' + originalPkg + '>');
-  }
+  } catch (err) { /* ignore */ }
+
+  throw new Error('cannot resolve rule <' + ruleName + '> from <' + originalPkg + '>');
 };
 
 NodeResolver.prototype.resolveConfig = function(pkg, configName) {
@@ -43,16 +78,7 @@ NodeResolver.prototype.resolveConfig = function(pkg, configName) {
 
   pkg = this.normalizePkg(pkg);
 
-  // resolve config via $PKG/config/$NAME
-  try {
-    if (pkg === 'bpmnlint') {
-      return this.requireLocal(`../../config/${configName}`);
-    } else {
-      return this.require(`${pkg}/config/${configName}`);
-    }
-  } catch (err) { /* ignore */ }
-
-  // resolve config via $PKG.configs[$NAME]
+  // (1) try resolving config via $PKG.configs[$NAME]
   try {
     const instance = this.require(pkg);
 
@@ -66,8 +92,17 @@ NodeResolver.prototype.resolveConfig = function(pkg, configName) {
     /* ignore */
   }
 
+  // (2) try resolving config via $PKG/config/$NAME
+  try {
+    if (pkg === 'bpmnlint') {
+      return this.requireLocal(`../../config/${configName}`);
+    } else {
+      return this.require(`${pkg}/config/${configName}`);
+    }
+  } catch (err) { /* ignore */ }
+
   throw new Error(
-    'Cannot resolve config <' + configName + '> from <' + originalPkg + '>'
+    'cannot resolve config <' + configName + '> from <' + originalPkg + '>'
   );
 };
 

package/lib/support/compile-config.js

@@ -1,3 +1,7 @@
+const path = require('path').posix;
+
+const { isString } = require('min-dash');
+
 const Linter = require('../linter');
 
 const NodeResolver = require('../resolver/node-resolver');
@@ -53,7 +57,7 @@ Resolver.prototype.resolveRule = function(pkg, ruleName) {
   const rule = cache[pkg + '/' + ruleName];
 
   if (!rule) {
-    throw new Error('cannot resolve rule <' + pkg + '/' + ruleName + '>');
+    throw new Error('cannot resolve rule <' + pkg + '/' + ruleName + '>: not bundled');
   }
 
   return rule;
@@ -61,7 +65,7 @@ Resolver.prototype.resolveRule = function(pkg, ruleName) {
 
 Resolver.prototype.resolveConfig = function(pkg, configName) {
   throw new Error(
-    'cannot resolve config <' + configName + '> in <' + pkg +'>'
+    'cannot resolve config <' + configName + '> in <' + pkg +'>: not bundled'
   );
 };
 
@@ -93,12 +97,68 @@ export default bundle;
       pkg, ruleName
     } = linter.parseRuleName(key);
 
-    return `
-import rule_${idx} from '${resolver.normalizePkg(pkg)}/rules/${ruleName}';
-cache['${pkg}/${ruleName}'] = rule_${idx};`;
+    return createImportStatement(pkg, ruleName, idx, resolver);
   }).filter(e => e).join('\n');
 
-  return `${preambleCode}\n\n${importCode}`;
+  return `${preambleCode}${importCode}`;
 }
 
-module.exports = compileConfig;
+module.exports = compileConfig;
+
+function requirePkg(resolver, pkg) {
+  try {
+    return resolver.require(pkg);
+  } catch (err) {
+    return null;
+  }
+}
+
+function createImportStatement(pkg, ruleName, idx, resolver) {
+  const originalPkg = pkg;
+
+  pkg = resolver.normalizePkg(pkg);
+
+  const pkgExport = requirePkg(resolver, pkg);
+
+  // (1) try resolving rule via $PKG.rules[$NAME]
+  if (pkgExport && pkgExport.rules) {
+    const rules = pkgExport.rules;
+
+    if (ruleName in rules) {
+      const rule = rules[ruleName];
+
+      if (!isString(rule)) {
+        throw new Error(
+          `failed to bundle rule <${ruleName}> from <${ pkg }>: illegal rule export (expected path reference)`
+        );
+      }
+
+      const rulePath = computeRuleImport(resolver, pkg, rule);
+
+      return `
+import rule_${ idx } from '${rulePath}';
+
+cache['${ originalPkg }/${ ruleName }'] = rule_${ idx };`;
+
+    }
+  }
+
+  // (2) resolve rule via $PKG/rules/$NAME
+  return `
+import rule_${ idx } from '${ pkg }/rules/${ ruleName }';
+
+cache['${ originalPkg }/${ ruleName }'] = rule_${ idx };`;
+}
+
+function computeRuleImport(resolver, pkg, rule) {
+
+  // local reference, resolved relative to pkg location
+  if (rule.startsWith('.')) {
+    const pkgDir = path.dirname(resolver.require.resolve(pkg));
+
+    return path.posix.normalize(`${ pkgDir }/${ rule }`);
+  }
+
+  // absolute reference
+  return path.normalize(rule);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bpmnlint",
   "description": "Validate your BPMN diagrams based on configurable lint rules",
-  "version": "8.1.1",
+  "version": "8.3.0",
   "main": "lib/index.js",
   "keywords": [
     "bpmnlint",
@@ -30,8 +30,9 @@
     "all": "run-s lint test-coverage",
     "lint": "eslint .",
     "dev": "npm test -- --watch",
-    "test": "mocha -r esm --exclude 'test/integration/cli/**' 'test/**/*.js'",
-    "test-coverage": "nyc --reporter=lcov --reporter=html npm test"
+    "test": "mocha -r esm --exclude 'test/integration/*/**' 'test/**/*.js'",
+    "test-coverage": "nyc --reporter=lcov --reporter=html npm test",
+    "generate-docs-images": "npx @bpmn-io/bpmnlint-generate-docs-images ."
   },
   "bin": {
     "bpmnlint": "./bin/bpmnlint.js"
@@ -39,19 +40,20 @@
   "dependencies": {
     "@bpmn-io/moddle-utils": "^0.1.0",
     "ansi-colors": "^4.1.3",
-    "bpmn-moddle": "^7.1.3",
-    "bpmnlint-utils": "^1.0.2",
+    "bpmn-moddle": "^8.0.1",
+    "bpmnlint-utils": "^1.1.1",
     "cli-table": "^0.3.11",
     "color-support": "^1.1.3",
-    "min-dash": "^3.8.1",
+    "min-dash": "^4.1.1",
     "mri": "^1.2.0",
     "pluralize": "^7.0.0",
     "tiny-glob": "^0.2.9"
   },
   "devDependencies": {
+    "@bpmn-io/bpmnlint-generate-docs-images": "^0.3.2",
     "chai": "^4.3.4",
-    "eslint": "^8.23.1",
-    "eslint-plugin-bpmn-io": "^0.16.0",
+    "eslint": "^8.42.0",
+    "eslint-plugin-bpmn-io": "^1.0.0",
     "esm": "^3.2.25",
     "execa": "^5.1.1",
     "install-local": "^3.0.1",

package/rules/no-implicit-end.js

@@ -0,0 +1,30 @@
+const {
+  is,
+  isAny
+} = require('bpmnlint-utils');
+
+
+/**
+ * A rule that checks that an element is not an implicit end (token sink).
+ */
+module.exports = function() {
+
+  function isImplicitEnd(node) {
+    const outgoing = node.outgoing || [];
+
+    return !is(node, 'bpmn:EndEvent') && outgoing.length === 0;
+  }
+
+  function check(node, reporter) {
+
+    if (!isAny(node, [ 'bpmn:Event', 'bpmn:Activity', 'bpmn:Gateway' ])) {
+      return;
+    }
+
+    if (isImplicitEnd(node)) {
+      reporter.report(node.id, 'Element is an implicit end');
+    }
+  }
+
+  return { check };
+};

package/rules/no-implicit-start.js

@@ -0,0 +1,30 @@
+const {
+  is,
+  isAny
+} = require('bpmnlint-utils');
+
+
+/**
+ * A rule that checks that an element is not an implicit start (token spawn).
+ */
+module.exports = function() {
+
+  function isImplicitStart(node) {
+    const incoming = node.incoming || [];
+
+    return !is(node, 'bpmn:StartEvent') && incoming.length === 0;
+  }
+
+  function check(node, reporter) {
+
+    if (!isAny(node, [ 'bpmn:Event', 'bpmn:Activity', 'bpmn:Gateway' ])) {
+      return;
+    }
+
+    if (isImplicitStart(node)) {
+      reporter.report(node.id, 'Element is an implicit start');
+    }
+  }
+
+  return { check };
+};