camunda-cli 0.3.1 → 0.4.0

package/README.md

@@ -72,21 +72,29 @@ camunda lint ./order-process.bpmn     # no engine and no login needed
 camunda lint order-process            # or the deployed version
 ```
 
-Every rule exists because that failure was reproduced against a real engine first:
+Every rule exists because that failure was reproduced against a real engine first.
+
+**Errors** are reserved for defects that are provable from the model alone, because `deploy`
+refuses to push a model that has one:
 
 | Rule | What it catches |
 |---|---|
-| `uncovered-value` | `> N` and `< N` branches that leave `== N` with nowhere to go (`ENGINE-02004`) |
-| `no-default-flow` | Every branch conditional, no default: any instance where they all fail stops dead |
-| `variable-name-mismatch` | A condition reads `foo` while the form writes `foo_2`, so the expression throws |
-| `unwritten-variable` | A direct `${x}` read where nothing sets `x`; throws instead of yielding null |
-| `initiator-expression` | `${initiator}`, which exists only when started through AlurKerja's API |
-| `no-op-service-task` | A service task with no implementation behind it |
-| `addon-without-config` | An integration call with no config bound |
-| `unreachable`, `dead-end`, `dangling-flow` | Structural mistakes |
-
-`deploy` runs the same checks and refuses to push a model with blocking issues, unless you
-pass `--skip-lint`.
+| `uncovered-value` | `> N` and `< N` branches leaving `== N` with nowhere to go (`ENGINE-02004`) |
+| `default-flow-with-condition` | A default flow that also carries a condition, which the engine rejects outright (`ENGINE-09005`) |
+| `variable-name-mismatch` | A form writing one variable nothing reads, feeding a condition reading one nothing writes |
+| `dangling-flow`, `dangling-boundary`, `no-start-event` | References to elements that do not exist |
+
+**Warnings** are risks that need a human to judge, since the model cannot prove them either
+way: `no-default-flow`, `unwritten-variable`, `initiator-expression`, `no-op-service-task`,
+`addon-without-config`, `unreachable`, `dead-end`, `ambiguous-branch`.
+
+Run over 190 production models, the checks raised zero errors and did not block a single
+deploy, while still flagging both defects in a model built to contain them. That balance is
+deliberate: a static check an agent cannot trust is worse than none, because acting on a
+confident wrong answer breaks a process that was working.
+
+`deploy` runs the same checks and refuses to push a model with an error, unless you pass
+`--skip-lint`.
 
 **Work out why an instance is stuck.** `diagnose` gathers what is scattered across several
 endpoints and unpacks it:

package/bin/camunda.js

@@ -24,7 +24,7 @@ program
       'Start with "camunda inspect <key>" to read a deployed model, and\n' +
       '"camunda diagnose <instanceId>" when an instance misbehaves.'
   )
-  .version('0.3.1')
+  .version('0.4.0')
   .option('--json', 'print the raw API payload instead of a formatted view')
   .option('--no-color', 'never emit colour, even on a terminal')
   .showHelpAfterError()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "camunda-cli",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Command-line client for self-hosted Camunda 7: inspect and lint deployed BPMN models, and diagnose why an instance is stuck",
   "license": "MIT",
   "type": "module",

package/src/lint.js

@@ -24,22 +24,104 @@ function levenshtein(a, b) {
   return d[m][n];
 }
 
+// Deliberately narrow. An earlier version also treated a shared prefix as evidence, which
+// made every model using a naming convention look broken: in a process where a form writes
+// gr_number, gr_date and gr_amount, reading an unrelated gr_recorded was reported as a typo
+// of gr_number. A near-identical spelling is the only similarity worth mentioning, and even
+// that is offered as a candidate rather than a conclusion.
 function similarNames(target, candidates) {
-  const prefix = target.includes('_') ? target.slice(0, target.indexOf('_') + 1) : null;
   return candidates.filter((c) => {
     if (c === target) return false;
-    if (prefix && c.startsWith(prefix)) return true;
-    return levenshtein(c.toLowerCase(), target.toLowerCase()) <= 3;
+    const a = c.toLowerCase().replace(/[_-]/g, '');
+    const b = target.toLowerCase().replace(/[_-]/g, '');
+    if (a === b) return true;
+    if (Math.min(a.length, b.length) < 4) return false;
+    return levenshtein(a, b) <= 2;
   });
 }
 
-// Reads `${x > 300}` style comparisons so a gateway's branches can be checked for gaps.
+// Evidence that a form and the expression reading it were never lined up, independent of
+// how the two names are spelled: an element whose form writes exactly one variable that
+// nothing anywhere reads, immediately followed by a flow reading a variable nothing writes.
+// Both halves are dead on their own, and they sit either side of the same element.
+// Field types whose name is a mount point rather than a variable. An embedded micro
+// frontend writes whatever it likes and the model has no way to declare that, so a form
+// containing one tells you nothing about which variables the element sets. Reasoning about
+// unwritten variables around these produced a confident, wrong error on a process that had
+// been running correctly for months.
+const OPAQUE_FIELD_TYPES = new Set([
+  'EXTERNAL_MICRO_FRONTEND_FORM',
+  'HTML_CUSTOM_FORM',
+  'VARIABLE_RENDERER',
+  'EXPRESSION_INPUT',
+]);
+
+function findStrandedFormField(model, node, byId, outgoing, readEverywhere, written) {
+  if (node.formFields.some((f) => OPAQUE_FIELD_TYPES.has(f.type))) return null;
+  const writable = node.formFields.filter((f) => !f.disabled && f.name);
+  if (writable.length !== 1) return null;
+  const field = writable[0].name;
+  if (readEverywhere.has(field)) return null;
+
+  // The conditions that act on a user task's input usually sit on the flows out of the
+  // gateway after it rather than on the task's own flow, so pass through gateways. Nothing
+  // else is followed: once a real activity intervenes, the value could have come from there.
+  const seen = new Set([node.id]);
+  const frontier = [node.id];
+  for (let depth = 0; depth < 3 && frontier.length; depth++) {
+    const next = [];
+    for (const id of frontier) {
+      for (const flow of outgoing.get(id) ?? []) {
+        if (flow.condition) {
+          const { direct } = readVariables(flow.condition);
+          const orphan = direct.find((v) => !written.has(v) && v !== 'initiator');
+          if (orphan) return { field, orphan, flow };
+        }
+        const target = byId.get(flow.target);
+        if (target && GATEWAYS.has(target.type) && !seen.has(target.id)) {
+          seen.add(target.id);
+          next.push(target.id);
+        }
+      }
+    }
+    frontier.length = 0;
+    frontier.push(...next);
+  }
+  return null;
+}
+
+// Reads `${x > 300}` and `${x == 'draft'}` style comparisons so a gateway's branches can be
+// checked for gaps. Values stay as written: a numeric gap is only meaningful between numbers.
 function parseComparison(expression) {
   const m = String(expression || '').match(
-    /\$\{\s*([A-Za-z_$][\w$]*)\s*(==|!=|>=|<=|>|<)\s*(-?\d+(?:\.\d+)?)\s*\}/
+    /^\s*\$\{\s*([A-Za-z_$][\w$]*)\s*(==|!=|>=|<=|>|<)\s*('[^']*'|"[^"]*"|-?\d+(?:\.\d+)?|true|false)\s*\}\s*$/
   );
   if (!m) return null;
-  return { variable: m[1], op: m[2], value: Number(m[3]) };
+  const raw = m[3];
+  const numeric = /^-?\d/.test(raw);
+  return {
+    variable: m[1],
+    op: m[2],
+    value: numeric ? Number(raw) : raw.replace(/^['"]|['"]$/g, ''),
+    numeric,
+  };
+}
+
+// Two branches that between them cover every value need no default flow. Recognising the
+// common complementary pairs keeps the check off models that are already exhaustive, which
+// would otherwise be a third of them.
+const COMPLEMENTARY = [
+  ['==', '!='],
+  ['>', '<='],
+  ['<', '>='],
+];
+
+function coversEverything(comparisons) {
+  if (comparisons.length !== 2) return false;
+  const [a, b] = comparisons;
+  if (a.variable !== b.variable) return false;
+  if (a.numeric !== b.numeric || String(a.value) !== String(b.value)) return false;
+  return COMPLEMENTARY.some(([x, y]) => (a.op === x && b.op === y) || (a.op === y && b.op === x));
 }
 
 export function lintProcess(model, { engineVariables = [] } = {}) {
@@ -71,6 +153,17 @@ export function lintProcess(model, { engineVariables = [] } = {}) {
   const starts = model.nodes.filter((n) => START_TYPES.has(n.type) && !n.scope);
   if (starts.length === 0) add('error', 'no-start-event', model.id, 'The process has no start event, so nothing can ever begin it.');
 
+  // A boundary event has no incoming sequence flow: it fires because the activity it is
+  // attached to is running. So whatever hangs off a boundary event is reachable exactly
+  // when its host activity is, and walking sequence flows alone would report every error
+  // and timeout handler in the model as unreachable.
+  const boundaryByHost = new Map();
+  for (const n of model.nodes) {
+    if (!n.attachedTo) continue;
+    if (!boundaryByHost.has(n.attachedTo)) boundaryByHost.set(n.attachedTo, []);
+    boundaryByHost.get(n.attachedTo).push(n.id);
+  }
+
   const reachable = new Set();
   const queue = starts.map((s) => s.id);
   while (queue.length) {
@@ -78,6 +171,7 @@ export function lintProcess(model, { engineVariables = [] } = {}) {
     if (reachable.has(id)) continue;
     reachable.add(id);
     for (const f of outgoing.get(id) || []) queue.push(f.target);
+    for (const b of boundaryByHost.get(id) || []) queue.push(b);
   }
   for (const n of model.nodes) {
     if (n.scope || n.attachedTo || START_TYPES.has(n.type)) continue;
@@ -102,36 +196,36 @@ export function lintProcess(model, { engineVariables = [] } = {}) {
     const unconditional = outs.filter((f) => !f.condition && f.id !== n.defaultFlow);
 
     if (conditional.length === outs.length && !n.defaultFlow) {
-      add(
-        'error',
-        'no-default-flow',
-        n.id,
-        `Every outgoing flow of "${n.name || n.id}" has a condition and there is no default flow. ` +
-          `If they all evaluate false at runtime the engine raises ENGINE-02004 and the instance stops. ` +
-          `Mark one flow as the default and remove its condition: a default flow carrying a condition is ` +
-          `rejected at deploy time with ENGINE-09005.`
-      );
+      const comparisons = conditional.map((f) => parseComparison(f.condition)).filter(Boolean);
+      const exhaustive = comparisons.length === conditional.length && coversEverything(comparisons);
 
-      // Numeric gap: a > N and a < N leave a == N with nowhere to go.
-      const comparisons = conditional.map((f) => ({ flow: f, cmp: parseComparison(f.condition) })).filter((c) => c.cmp);
-      const byVar = new Map();
-      for (const c of comparisons) {
-        if (!byVar.has(c.cmp.variable)) byVar.set(c.cmp.variable, []);
-        byVar.get(c.cmp.variable).push(c.cmp);
-      }
-      for (const [variable, cmps] of byVar) {
-        if (cmps.length !== conditional.length) continue;
-        const gt = cmps.find((c) => c.op === '>');
-        const lt = cmps.find((c) => c.op === '<');
-        if (gt && lt && gt.value === lt.value && !cmps.some((c) => ['==', '>=', '<='].includes(c.op))) {
-          add(
-            'error',
-            'uncovered-value',
-            n.id,
-            `"${n.name || n.id}" branches on ${variable} > ${gt.value} and ${variable} < ${lt.value}, ` +
-              `so ${variable} == ${gt.value} matches neither branch and the instance will fail there.`
-          );
-        }
+      // A provable gap: `> N` and `< N` between them never match `== N`. This one is
+      // certain, so it is an error even though the general case below is not.
+      const gt = comparisons.find((c) => c.op === '>' && c.numeric);
+      const lt = comparisons.find((c) => c.op === '<' && c.numeric);
+      const sameVar = gt && lt && gt.variable === lt.variable && gt.value === lt.value;
+
+      if (sameVar && comparisons.length === conditional.length) {
+        add(
+          'error',
+          'uncovered-value',
+          n.id,
+          `"${n.name || n.id}" branches on ${gt.variable} > ${gt.value} and ${lt.variable} < ${lt.value}, ` +
+            `so ${gt.variable} == ${gt.value} matches neither branch. The engine raises ENGINE-02004 and the ` +
+            `instance stops there.`
+        );
+      } else if (!exhaustive) {
+        // Not provably broken: the conditions may well cover every case in a way that
+        // cannot be read off the expressions. Worth flagging, not worth blocking a deploy.
+        add(
+          'warning',
+          'no-default-flow',
+          n.id,
+          `Every outgoing flow of "${n.name || n.id}" has a condition and there is no default flow. If a case ever ` +
+            `arises where they all evaluate false, the engine raises ENGINE-02004 and the instance stops. Marking ` +
+            `one flow as the default removes that risk; a default flow must not carry a condition itself, or the ` +
+            `model is rejected at deploy time with ENGINE-09005.`
+        );
       }
     }
 
@@ -174,7 +268,33 @@ export function lintProcess(model, { engineVariables = [] } = {}) {
   const knownNames = new Set([...written.keys(), ...engineVariables]);
   const formFieldNames = [...written.keys()];
 
-  for (const { where, expression, kind } of collectExpressions(model)) {
+  const hasOpaqueForms = model.nodes.some((n) => n.formFields.some((f) => OPAQUE_FIELD_TYPES.has(f.type)));
+  const expressions = collectExpressions(model);
+  const readEverywhere = new Set();
+  for (const e of expressions) {
+    const { direct, safe } = readVariables(e.expression);
+    for (const v of [...direct, ...safe]) readEverywhere.add(v);
+  }
+
+  // Structural mismatch first: a form field nothing reads sitting directly upstream of a
+  // condition reading something nothing writes. This holds whatever the two are called,
+  // so it is the only case reported as an error.
+  for (const n of model.nodes) {
+    if (n.formFields.length === 0) continue;
+    const stranded = findStrandedFormField(model, n, byId, outgoing, readEverywhere, written);
+    if (!stranded) continue;
+    add(
+      'error',
+      'variable-name-mismatch',
+      n.id,
+      `The form on "${n.name || n.id}" writes only "${stranded.field}", which nothing in this process reads, ` +
+        `while the flow leaving it ("${stranded.flow.name || stranded.flow.id}") reads "${stranded.orphan}", which ` +
+        `nothing writes. Completing this element therefore cannot satisfy the condition, and evaluating it throws ` +
+        `"Cannot resolve identifier '${stranded.orphan}'". One of the two names needs to change.`
+    );
+  }
+
+  for (const { where, expression, kind } of expressions) {
     const { direct } = readVariables(expression);
     for (const v of direct) {
       if (knownNames.has(v)) continue;
@@ -192,24 +312,16 @@ export function lintProcess(model, { engineVariables = [] } = {}) {
       }
 
       const near = similarNames(v, formFieldNames);
-      if (near.length > 0) {
-        add(
-          'error',
-          'variable-name-mismatch',
-          where,
-          `Reads "${v}", which nothing in this process writes, while a form here writes ${near.map((s) => `"${s}"`).join(', ')}. ` +
-            `These names look related, so this is most likely a typo: the expression throws ` +
-            `"Cannot resolve identifier '${v}'" the moment it is evaluated.`
-        );
-      } else {
-        add(
-          'warning',
-          'unwritten-variable',
-          where,
-          `Reads "${v}" directly and nothing in this process writes it. If it is not supplied at start time the ` +
-            `expression throws rather than treating it as null. Use \${execution.getVariable('${v}')} if absent is a valid state.`
-        );
-      }
+      add(
+        'warning',
+        'unwritten-variable',
+        where,
+        `Reads "${v}" directly and nothing in this process writes it. That is fine if it always arrives with the ` +
+          `start payload; otherwise the expression throws "Cannot resolve identifier '${v}'" rather than treating ` +
+          `it as null, and \${execution.getVariable('${v}')} would yield null instead.` +
+          (near.length > 0 ? ` A form here writes ${near.map((s) => `"${s}"`).join(', ')}, which is spelled almost the same.` : '') +
+          (hasOpaqueForms ? ` This process embeds an external form, which can set variables the model does not declare, so "${v}" may well be one of those.` : '')
+      );
     }
   }