bpmnlint 11.0.0 → 11.2.0

package/bin/bpmnlint.js

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
+
+const { readFile } = require('node:fs/promises');
+const { writeFileSync, existsSync } = require('node:fs');
+const { resolve: resolvePath } = require('node:path');
+
 const mri = require('mri');
-const fs = require('fs');
-const path = require('path');
 const colors = require('ansi-colors');
 
 colors.enabled = require('color-support').hasBasic;
@@ -14,11 +17,9 @@ const {
   magenta
 } = colors;
 
-const { promisify } = require('util');
-
 const tinyGlob = require('tiny-glob');
-const readFile = promisify(fs.readFile);
 
+// @ts-expect-error 'missing <bpmn-moddle> types'
 const BpmnModdle = require('bpmn-moddle');
 
 const Linter = require('../lib/linter');
@@ -30,6 +31,11 @@ const pluralize = require('pluralize');
 
 const { pathStringify } = require('@bpmn-io/moddle-utils');
 
+/**
+ * @typedef { import('../lib/types').ModdleElement } ModdleElement
+ * @typedef { Error & { element: ModdleElement } } BPMNImportWarning
+ */
+
 const CONFIG_NAME = '.bpmnlintrc';
 
 const DEFAULT_CONFIG_CONTENTS = `{
@@ -76,7 +82,7 @@ function glob(files) {
  *
  * @param {string} diagramXML
  *
- * @return { { rootElement: any; warnings: Error[], error?: Error } } parseResult
+ * @return { Promise<{ moddleElement: any; warnings: Error[], error?: Error }> } parseResult
  */
 async function parseDiagram(diagramXML) {
 
@@ -93,10 +99,14 @@ async function parseDiagram(diagramXML) {
   } catch (error) {
 
     const {
+
+      // @ts-expect-error
       warnings = []
     } = error;
 
     return {
+
+      // @ts-expect-error
       error,
       warnings
     };
@@ -215,7 +225,7 @@ function printReports(filePath, results) {
 
   if (problemCount) {
     console.log();
-    console.log(underline(path.resolve(filePath)));
+    console.log(underline(resolvePath(filePath)));
     console.log(table.toString());
   }
 
@@ -230,9 +240,9 @@ async function lintDiagram(diagramPath, config) {
   let diagramXML;
 
   try {
-    diagramXML = await readFile(path.resolve(diagramPath), 'utf-8');
+    diagramXML = await readFile(resolvePath(diagramPath), 'utf-8');
   } catch (error) {
-    return errorAndExit(`Error: Failed to read ${diagramPath}\n\n%s`, error.message);
+    throw errorAndExit(`Error: Failed to read ${diagramPath}\n\n%s`, /** @type { Error } */ (error).message);
   }
 
 
@@ -259,7 +269,7 @@ async function lintDiagram(diagramPath, config) {
       const {
         element,
         message
-      } = warning;
+      } = /** @type { BPMNImportWarning } */ (warning);
 
       const id = element && element.id;
 
@@ -286,7 +296,7 @@ async function lintDiagram(diagramPath, config) {
 
     return printReports(diagramPath, allResults);
   } catch (e) {
-    return errorAndExit(e);
+    throw errorAndExit(e);
   }
 }
 
@@ -306,17 +316,10 @@ async function lint(files, config, maxWarnings) {
 
   const problemCount = errorCount + warningCount;
 
-  let color;
+  if (problemCount) {
 
-  if (warningCount) {
-    color = boldYellow;
-  }
+    const color = warningCount ? boldYellow : boldRed;
 
-  if (errorCount) {
-    color = boldRed;
-  }
-
-  if (problemCount) {
     console.log();
     console.log(color(
       `✖ ${problemCount} ${pluralize('problem', problemCount)} (${errorCount} ${pluralize('error', errorCount)}, ${warningCount} ${pluralize('warning', warningCount)})`
@@ -357,17 +360,17 @@ async function run() {
   }
 
   if (init) {
-    if (fs.existsSync(CONFIG_NAME)) {
-      return errorAndExit('Not overriding existing .bpmnlintrc');
+    if (existsSync(CONFIG_NAME)) {
+      throw errorAndExit('Not overriding existing .bpmnlintrc');
     }
 
-    fs.writeFileSync(CONFIG_NAME, DEFAULT_CONFIG_CONTENTS, 'utf8');
+    writeFileSync(CONFIG_NAME, DEFAULT_CONFIG_CONTENTS, 'utf8');
 
-    return infoAndExit(`Created ${magenta(CONFIG_NAME)} file`);
+    throw infoAndExit(`Created ${magenta(CONFIG_NAME)} file`);
   }
 
   if (files.length === 0) {
-    return errorAndExit('Error: bpmn file path missing');
+    throw errorAndExit('Error: bpmn file path missing');
   }
 
   const configPath = configOverridePath || CONFIG_NAME;
@@ -388,13 +391,13 @@ async function run() {
 Learn more about configuring bpmnlint: https://github.com/bpmn-io/bpmnlint#configuration`
     );
 
-    return errorAndExit(message);
+    throw errorAndExit(message);
   }
 
   try {
     config = JSON.parse(configString);
-  } catch (err) {
-    return errorAndExit('Error: Could not parse %s\n\n%s', configPath, err.message);
+  } catch (error) {
+    throw errorAndExit('Error: Could not parse %s\n\n%s', configPath, /** @type { Error } */ (error).message);
   }
 
   const actualFiles = await glob(files);

package/config/all.js

@@ -1,4 +1,5 @@
 const allRules = [
+  'ad-hoc-sub-process',
   'conditional-flows',
   'end-event-required',
   'event-sub-process-typed-start-event',

package/config/recommended.js

@@ -1,5 +1,6 @@
 module.exports = {
   rules: {
+    'ad-hoc-sub-process': 'error',
     'conditional-flows': 'error',
     'end-event-required': 'error',
     'event-sub-process-typed-start-event': 'error',

package/lib/linter.js

@@ -1,5 +1,54 @@
 const testRule = require('./test-rule');
 
+
+/**
+ * @typedef { import('./types.js').ModdleElement } ModdleElement
+ *
+ * @typedef { import('./types.js').ReportingCategory } ReportingCategory
+ * @typedef { import('./types.js').ReportingCategoryMap } ReportingCategoryMap
+ * @typedef { import('./types.js').RuleErrorCategory } RuleErrorCategory
+ *
+ * @typedef { import('./types.js').Resolver } Resolver
+ * @typedef { import('./types.js').Config } Config
+ *
+ * @typedef { import('./types.js').RuleFactory } RuleFactory
+ *
+ * @typedef { import('./types.js').RuleDefinition } RuleDefinition
+ * @typedef { import('./types.js').RuleConfigs } RuleConfigs
+ * @typedef { import('./types.js').RuleConfig } RuleConfig
+ *
+ * @typedef { {
+ *   name: string,
+ *   rule: RuleDefinition,
+ *   config: any,
+ *   category: ReportingCategory
+ * } } ResolvedRuleDefinition
+ *
+ * @typedef { import('./types.js').Report } Report
+ * @typedef { Report & Pick<RuleDefinition, 'meta'> & {
+ *   category: ReportingCategory | RuleErrorCategory
+ * } } AnnotatedReport
+ *
+ * @typedef { import('./types.js').TransformRuleFn } TransformRuleFn
+ *
+ * @typedef { Record<string, AnnotatedReport[]> } LintResults
+ */
+
+
+/**
+ * Transform a rule after it is loaded.
+ *
+ * @param { RuleDefinition } rule
+ * @param { { pkg: string, ruleName: string } } options
+ */
+const noopTransformRule = (rule, options) => {
+  return rule;
+};
+
+
+/**
+ * @typeof { ReportingCategoryMap }
+ */
 const categoryMap = {
   0: 'off',
   1: 'warn',
@@ -7,15 +56,25 @@ const categoryMap = {
   3: 'info'
 };
 
+/**
+ * @type { RuleErrorCategory }
+ */
 const ruleErrorCategory = 'rule-error';
 
-
-function Linter(options = {}) {
+/**
+ * @param { {
+ *   config?: Config,
+ *   resolver: Resolver,
+ *   transformRule?: TransformRuleFn
+ * } } options
+ */
+function Linter(options) {
 
   const {
-    config,
-    resolver
-  } = options;
+    config = {},
+    resolver,
+    transformRule = noopTransformRule
+  } = options || {};
 
   if (typeof resolver === 'undefined') {
     throw new Error('must provide <options.resolver>');
@@ -24,7 +83,16 @@ function Linter(options = {}) {
   this.config = config;
   this.resolver = resolver;
 
+  this.transformRule = transformRule;
+
+  /**
+   * @type { Record<string, RuleDefinition> }
+   */
   this.cachedRules = {};
+
+  /**
+   * @type { Record<string, Config> }
+   */
   this.cachedConfigs = {};
 }
 
@@ -34,14 +102,11 @@ module.exports = Linter;
 /**
  * Applies a rule on the moddleRoot and adds reports to the finalReport
  *
- * @param {ModdleElement} moddleRoot
+ * @param { ModdleElement } moddleRoot
  *
- * @param {Object} ruleDefinition.name
- * @param {Object} ruleDefinition.config
- * @param {Object} ruleDefinition.category
- * @param {Rule} ruleDefinition.rule
+ * @param { ResolvedRuleDefinition } ruleDefinition
  *
- * @return {Array<ValidationErrors>} rule reports
+ * @return { AnnotatedReport[] } reports
  */
 Linter.prototype.applyRule = function applyRule(moddleRoot, ruleDefinition) {
 
@@ -63,6 +128,7 @@ Linter.prototype.applyRule = function applyRule(moddleRoot, ruleDefinition) {
     return reports.map(function(report) {
       return {
         ...report,
+        meta: rule.meta,
         category
       };
     });
@@ -71,7 +137,7 @@ Linter.prototype.applyRule = function applyRule(moddleRoot, ruleDefinition) {
 
     return [
       {
-        message: e.message,
+        message: /** @type { Error } */ (e).message,
         category: ruleErrorCategory
       }
     ];
@@ -80,6 +146,12 @@ Linter.prototype.applyRule = function applyRule(moddleRoot, ruleDefinition) {
 };
 
 
+/**
+ * @param { string } name
+ * @param  { RuleConfig } config
+ *
+ * @return { Promise<RuleDefinition> }
+ */
 Linter.prototype.resolveRule = function(name, config) {
 
   const {
@@ -101,12 +173,17 @@ Linter.prototype.resolveRule = function(name, config) {
       throw new Error(`unknown rule <${name}>`);
     }
 
-    const rule = this.cachedRules[id] = ruleFactory(config);
+    const rule = this.cachedRules[id] = this.transformRule(ruleFactory(config), { pkg, ruleName });
 
     return rule;
   });
 };
 
+/**
+ * @param {string} name
+ *
+ * @return {Promise<Config>}
+ */
 Linter.prototype.resolveConfig = function(name) {
 
   const {
@@ -137,9 +214,9 @@ Linter.prototype.resolveConfig = function(name) {
 /**
  * Take a linter config and return list of resolved rules.
  *
- * @param {Object} config
+ * @param { Config } config
  *
- * @return {Array<RuleDefinition>}
+ * @return { Promise<ResolvedRuleDefinition[]> }
  */
 Linter.prototype.resolveRules = function(config) {
 
@@ -182,7 +259,11 @@ Linter.prototype.resolveRules = function(config) {
   });
 };
 
-
+/**
+ * @param { Config } config
+ *
+ * @return { Promise<RuleConfigs> }
+ */
 Linter.prototype.resolveConfiguredRules = function(config) {
 
   let parents = config.extends;
@@ -220,10 +301,10 @@ Linter.prototype.resolveConfiguredRules = function(config) {
 /**
  * Lint the given model root, using the specified linter config.
  *
- * @param {ModdleElement} moddleRoot
- * @param {Object} [config] the bpmnlint configuration to use
+ * @param { ModdleElement } moddleRoot
+ * @param { Config } [config] the bpmnlint configuration to use
  *
- * @return {Object} lint results, keyed by category names
+ * @return { Promise<LintResults> } lint results, keyed by rule names
  */
 Linter.prototype.lint = function(moddleRoot, config) {
 
@@ -232,6 +313,9 @@ Linter.prototype.lint = function(moddleRoot, config) {
   // load rules
   return this.resolveRules(config).then((ruleDefinitions) => {
 
+    /**
+     * @type { LintResults }
+     */
     const allReports = {};
 
     ruleDefinitions.forEach((ruleDefinition) => {
@@ -251,7 +335,11 @@ Linter.prototype.lint = function(moddleRoot, config) {
   });
 };
 
-
+/**
+ * @param { import('./types.js').RuleConfig } value
+ *
+ * @return { { config: any, category: ReportingCategory } }
+ */
 Linter.prototype.parseRuleValue = function(value) {
 
   let category;

package/lib/resolver/node-resolver.js

@@ -1,14 +1,23 @@
-const Module = require('module');
-const path = require('path');
+const Module = require('node:module');
+const path = require('node:path');
+const { cwd } = require('node:process');
 
 const { isString } = require('min-dash');
 
+/**
+ * @typedef { import('../types.js').RuleFactory } RuleFactory
+ * @typedef { import('../types.js').Config } Config
+ */
+
+
 /**
  * A resolver that locates rules and configurations
  * using node module resolution.
+ *
+ * @param { { require?: NodeRequire, requireLocal?: NodeRequire } } [options]
  */
 function NodeResolver(options) {
-  this.require = options && options.require || createScopedRequire(process.cwd());
+  this.require = options && options.require || createScopedRequire(cwd());
 
   this.requireLocal = options && options.requireLocal || require;
 
@@ -22,6 +31,12 @@ function NodeResolver(options) {
 module.exports = NodeResolver;
 
 
+/**
+ * @param { string } pkg
+ * @param { string } ruleName
+ *
+ * @return { RuleFactory }
+ */
 NodeResolver.prototype.resolveRule = function(pkg, ruleName) {
 
   const originalPkg = pkg;
@@ -72,6 +87,12 @@ NodeResolver.prototype.resolveRule = function(pkg, ruleName) {
   throw new Error('cannot resolve rule <' + ruleName + '> from <' + originalPkg + '>');
 };
 
+/**
+ * @param { string } pkg
+ * @param { string } configName
+ *
+ * @return { Config }
+ */
 NodeResolver.prototype.resolveConfig = function(pkg, configName) {
 
   const originalPkg = pkg;
@@ -116,19 +137,9 @@ NodeResolver.prototype.normalizePkg = function(pkg) {
 
 // helpers ////////////////////
 
+/**
+ * @param {string} cwd
+ */
 function createScopedRequire(cwd) {
-
-  // shim createRequireFromPath for Node < 10.12
-  // shim createRequireFromPath for Node < 12.2.0
-  const createRequireFromPath = Module.createRequire || Module.createRequireFromPath || (filename => {
-    const mod = new Module(filename, null);
-
-    mod.filename = filename;
-    mod.paths = Module._nodeModulePaths(path.dirname(filename));
-    mod._compile('module.exports = require;', filename);
-
-    return mod.exports;
-  });
-
-  return createRequireFromPath(path.join(cwd, '__placeholder__.js'));
+  return Module.createRequire(path.join(cwd, '__placeholder__.js'));
 }

package/lib/resolver/static-resolver.js

@@ -1,16 +1,38 @@
+/**
+ * @typedef { import('../types.js').RuleFactory } RuleFactory
+ * @typedef { import('../types.js').Config } Config
+ */
+
+
+/**
+ * A resolver that resolves rules and packages from a static cache.
+ *
+ * @param { any } cache
+ */
 function StaticResolver(cache) {
   this.cache = cache;
 }
 
 module.exports = StaticResolver;
 
-
+/**
+ * @param { string } pkg
+ * @param { string } ruleName
+ *
+ * @return { RuleFactory }
+ */
 StaticResolver.prototype.resolveRule = function(pkg, ruleName) {
-  return this.resolve('rule', pkg, ruleName);
+  return /** @type { RuleFactory } */ (this.resolve('rule', pkg, ruleName));
 };
 
+/**
+ * @param { string } pkg
+ * @param { string } configName
+ *
+ * @return { Config }
+ */
 StaticResolver.prototype.resolveConfig = function(pkg, configName) {
-  return this.resolve('config', pkg, configName);
+  return /** @type { Config } */ (this.resolve('config', pkg, configName));
 };
 
 StaticResolver.prototype.resolve = function(type, pkg, name) {

package/lib/test-rule.js

@@ -2,33 +2,54 @@ const traverse = require('./traverse');
 
 const {
   isArray,
-  isObject
+  isObject,
+  isFunction
 } = require('min-dash');
 
 
+/**
+ * @typedef { import('./types.js').EnterFn } EnterFn
+ * @typedef { import('./types.js').ModdleElement } ModdleElement
+ * @typedef { import('./types.js').RuleDefinition } RuleDefinition
+ * @typedef { import('./types.js').Report } Report
+ */
+
+
 class Reporter {
+
+  /**
+   * @param { {
+   *   moddleRoot: ModdleElement,
+   *   rule: RuleDefinition
+   * } } options
+   */
   constructor({ moddleRoot, rule }) {
     this.rule = rule;
     this.moddleRoot = moddleRoot;
+
+    /**
+     * @type { Report[] }
+     */
     this.messages = [];
+
     this.report = this.report.bind(this);
   }
 
   /**
-   * @param {string} id
-   * @param {string} message
-   * @param {string[]|Object} path
+   * @param { string } id
+   * @param { string } message
+   * @param { string[] | { path?: string[], [key: string]: any } } [path]
    *
    * @example
    *
-   * Reporter.report('foo', 'Foo error', [ 'foo', 'bar', 'baz' ]);
-   *
-   * @example
+   * ```javascript
+   * reporter.report('foo', 'Foo error', [ 'foo', 'bar', 'baz' ]);
    *
-   * Reporter.report('foo', 'Foo error', {
-   *  path: [ 'foo', 'bar', 'baz' ],
-   *  foo: 'foo'
+   * reporter.report('foo', 'Foo error', {
+   *   path: [ 'foo', 'bar', 'baz' ],
+   *   foo: 'foo'
    * });
+   * ```
    */
   report(id, message, path) {
     let report = {
@@ -54,21 +75,32 @@ class Reporter {
   }
 }
 
+/**
+ * @param { {
+ *   moddleRoot: ModdleElement,
+ *   rule: RuleDefinition,
+ *   config: any
+ * } } options
+ *
+ * @return { Report[] } lint reports
+ */
 module.exports = function testRule({ moddleRoot, rule }) {
   const reporter = new Reporter({ rule, moddleRoot });
 
-  const check = rule.check;
+  const check = rule.check || {};
 
-  const enter = check && check.enter || check;
-  const leave = check && check.leave;
+  const leave = 'leave' in check ? check.leave : undefined;
+  const enter = 'enter' in check ? check.enter : (
+    isFunction(check) ? check : undefined
+  );
 
   if (!enter && !leave) {
     throw new Error('no check implemented');
   }
 
   traverse(moddleRoot, {
-    enter: enter ? (node) => enter(node, reporter) : null,
-    leave: leave ? (node) => leave(node, reporter) : null
+    enter: enter ? (node) => enter(node, reporter) : undefined,
+    leave: leave ? (node) => leave(node, reporter) : undefined
   });
 
   return reporter.messages;

package/lib/testers/helper.js

@@ -1,6 +1,7 @@
+// @ts-expect-error 'missing <bpmn-moddle> types'
 const BpmnModdle = require('bpmn-moddle');
 
-const readFileSync = require('fs').readFileSync;
+const { readFileSync } = require('node:fs');
 
 
 /**

package/lib/testers/rule-tester.js

@@ -5,8 +5,13 @@ const assert = require('assert');
 const Linter = require('../linter');
 
 function createResolver(rule) {
+
   return {
-    resolveRule: () => Promise.resolve(rule)
+    resolveRule: () => Promise.resolve(rule),
+
+    resolveConfig: () => {
+      throw new Error('not implemented');
+    }
   };
 }
 
@@ -57,7 +62,7 @@ function verify(ruleName, rule, testCases) {
 
       testCases.invalid.forEach(({ config = {}, it: _it, moddleElement, name, report }, idx) => (
 
-        (_it || it)(getTitle(idx, name), function() {
+        (_it || it)(getTitle(idx, name), async function() {
 
           if (!Array.isArray(report)) {
             report = [
@@ -65,9 +70,14 @@ function verify(ruleName, rule, testCases) {
             ];
           }
 
+          const {
+            meta
+          } = await linter.resolveRule(name, config);
+
           const expectedResults = report.map(report => {
             return {
               ...report,
+              meta,
               category: 'error'
             };
           });

package/lib/traverse.js

@@ -1,19 +1,22 @@
 /**
- * @typedef { import('./types.js').EnterFn } EnterFn
- * @typedef { import('./types.js').LeaveFn } LeaveFn
+ * @typedef { import('./types.js').ModdleElement } ModdleElement
+ *
+ * @typedef { (element: ModdleElement) => boolean | void } EnterFn
+ * @typedef { (element: ModdleElement) => void } LeaveFn
  */
 
+
 /**
  * Traverse a moddle tree, depth first from top to bottom
  * and call the passed visitor fn.
  *
- * @param {ModdleElement} element
- * @param {{ enter?: EnterFn; leave?: LeaveFn }} options
+ * @param { ModdleElement } element
+ * @param { { enter?: EnterFn; leave?: LeaveFn } } options
  */
 module.exports = function traverse(element, options) {
 
-  const enter = options.enter || null;
-  const leave = options.leave || null;
+  const enter = options.enter;
+  const leave = options.leave;
 
   const enterSubTree = enter && enter(element);