@fluentcommerce/ai-skills 0.13.0 → 0.15.0

package/tools/workflow-explainer.mjs

@@ -0,0 +1,1021 @@
+#!/usr/bin/env node
+// fluent-ai-skills/tools/workflow-explainer.mjs
+// Workflow Explainer — Local workflow analysis, custom rule source extraction, Mermaid visualization
+// Zero npm dependencies — uses only Node.js built-ins
+//
+// Usage:
+//   node tools/workflow-explainer.mjs --workflow <path-to-json> [--workspace <path>] [--profile <NAME>] [--output <path>] [--html]
+//
+// Examples:
+//   node tools/workflow-explainer.mjs --workflow accounts/SAGIRISH/workflows/Module\ Test/ORDER-MULTI.json --profile SAGIRISH
+//   node tools/workflow-explainer.mjs --workflow ORDER-MULTI.json --workspace /path/to/fluent-ai-workspace --profile SAGIRISH --output report.md
+//   node tools/workflow-explainer.mjs --workflow ORDER-MULTI.json --profile SAGIRISH --html --output report.html
+
+import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { join, basename, dirname, resolve, extname, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// ─── CLI Argument Parsing ────────────────────────────────────────────────────
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const opts = { workflow: null, workspace: null, profile: null, output: null, html: false };
+  for (let i = 0; i < args.length; i++) {
+    switch (args[i]) {
+      case '--workflow': case '-w': opts.workflow = args[++i]; break;
+      case '--workspace': opts.workspace = args[++i]; break;
+      case '--profile': case '-p': opts.profile = args[++i]; break;
+      case '--output': case '-o': opts.output = args[++i]; break;
+      case '--html': opts.html = true; break;
+      case '--help': case '-h': printHelp(); process.exit(0);
+      default:
+        if (!args[i].startsWith('-') && !opts.workflow) opts.workflow = args[i];
+        else if (!args[i].startsWith('-')) { console.error(`Unknown argument: ${args[i]}`); process.exit(1); }
+        else { console.error(`Unknown option: ${args[i]}`); process.exit(1); }
+    }
+  }
+  if (!opts.workflow) { console.error('Error: --workflow <path> is required\n'); printHelp(); process.exit(1); }
+  if (!opts.workspace) opts.workspace = process.cwd();
+  if (!opts.profile) opts.profile = process.env.FLUENT_PROFILE || null;
+  return opts;
+}
+
+function printHelp() {
+  console.log(`
+Workflow Explainer — Fluent Commerce Workflow Analysis & Visualization
+
+Usage:
+  node tools/workflow-explainer.mjs --workflow <path> [options]
+
+Options:
+  --workflow, -w <path>   Path to workflow JSON file (required)
+  --workspace <path>      Workspace root (default: cwd)
+  --profile, -p <NAME>    Account profile name (default: FLUENT_PROFILE env)
+  --output, -o <path>     Output file path (default: stdout)
+  --html                  Generate self-contained HTML with rendered Mermaid diagrams
+  --help, -h              Show this help
+
+Examples:
+  node tools/workflow-explainer.mjs -w ORDER-MULTI.json -p SAGIRISH
+  node tools/workflow-explainer.mjs -w ORDER-MULTI.json -p SAGIRISH --html -o report.html
+`);
+}
+
+// ─── Workflow Parser ─────────────────────────────────────────────────────────
+
+function parseWorkflow(filePath) {
+  const raw = readFileSync(filePath, 'utf-8');
+  const wf = JSON.parse(raw);
+
+  const entityTypes = new Set();
+  const statusesByEntity = {};    // entityType -> [{name, category}]
+  const rulesetsByEntity = {};    // entityType -> [ruleset]
+  const allRules = new Map();     // "MODULE.RuleName" -> {name, propsVariants: [{rulesetName, props}]}
+  const userActions = [];         // [{rulesetName, entityType, subtype, actions}]
+  const eventChains = [];         // [{from, to, trigger}]
+
+  // Parse statuses
+  for (const s of (wf.statuses || [])) {
+    const et = s.entityType || wf.entityType;
+    entityTypes.add(et);
+    if (!statusesByEntity[et]) statusesByEntity[et] = [];
+    if (!statusesByEntity[et].find(x => x.name === s.name)) {
+      statusesByEntity[et].push({ name: s.name, category: s.category || '' });
+    }
+  }
+
+  // Parse rulesets
+  for (const rs of (wf.rulesets || [])) {
+    const et = rs.type || wf.entityType;
+    entityTypes.add(et);
+    if (!rulesetsByEntity[et]) rulesetsByEntity[et] = [];
+    rulesetsByEntity[et].push(rs);
+
+    // Collect rules
+    for (const rule of (rs.rules || [])) {
+      if (!allRules.has(rule.name)) {
+        allRules.set(rule.name, { name: rule.name, propsVariants: [] });
+      }
+      allRules.get(rule.name).propsVariants.push({
+        rulesetName: rs.name,
+        entityType: et,
+        props: rule.props || null,
+      });
+    }
+
+    // Collect user actions
+    if (rs.userActions && rs.userActions.length > 0) {
+      userActions.push({
+        rulesetName: rs.name,
+        entityType: et,
+        subtype: rs.subtype || null,
+        actions: rs.userActions,
+      });
+    }
+
+    // Build event chain edges from rules that have eventName/noMatchEventName props
+    for (const rule of (rs.rules || [])) {
+      if (rule.props) {
+        if (rule.props.eventName) {
+          eventChains.push({ from: rs.name, to: rule.props.eventName, rule: rule.name, entityType: et });
+        }
+        if (rule.props.noMatchEventName) {
+          eventChains.push({ from: rs.name, to: rule.props.noMatchEventName, rule: rule.name, entityType: et, isNoMatch: true });
+        }
+      }
+    }
+  }
+
+  return {
+    name: wf.name,
+    version: wf.version,
+    entityType: wf.entityType,
+    entitySubtype: wf.entitySubtype,
+    description: wf.description,
+    versionComment: wf.versionComment,
+    retailerId: wf.retailerId,
+    entityTypes: [...entityTypes],
+    statusesByEntity,
+    rulesetsByEntity,
+    allRules,
+    userActions,
+    eventChains,
+    rulesetCount: (wf.rulesets || []).length,
+    statusCount: (wf.statuses || []).length,
+  };
+}
+
+// ─── Custom Rule Source Finder ───────────────────────────────────────────────
+
+function findJavaFiles(dir, results = []) {
+  if (!existsSync(dir)) return results;
+  try {
+    for (const entry of readdirSync(dir)) {
+      const full = join(dir, entry);
+      try {
+        const st = statSync(full);
+        if (st.isDirectory()) findJavaFiles(full, results);
+        else if (entry.endsWith('.java') && !entry.endsWith('Test.java')) results.push(full);
+      } catch { /* skip unreadable */ }
+    }
+  } catch { /* skip unreadable */ }
+  return results;
+}
+
+function extractClassName(filePath) {
+  return basename(filePath, '.java');
+}
+
+function parseJavaSource(filePath) {
+  const src = readFileSync(filePath, 'utf-8');
+  const className = extractClassName(filePath);
+
+  // Extract @RuleInfo
+  const ruleInfoMatch = src.match(/@RuleInfo\s*\(\s*([\s\S]*?)\)/);
+  let ruleInfoName = null;
+  let ruleInfoDesc = null;
+  if (ruleInfoMatch) {
+    const nameM = ruleInfoMatch[1].match(/name\s*=\s*"([^"]+)"/);
+    const descM = ruleInfoMatch[1].match(/description\s*=\s*"([^"]+)"/);
+    if (nameM) ruleInfoName = nameM[1];
+    if (descM) ruleInfoDesc = descM[1];
+  }
+
+  // Extract @ParamString annotations (multiple)
+  const paramStrings = [];
+  const paramRegex = /@ParamString\s*\(\s*([\s\S]*?)\)/g;
+  let pm;
+  while ((pm = paramRegex.exec(src)) !== null) {
+    const nameM = pm[1].match(/name\s*=\s*"([^"]+)"/);
+    const descM = pm[1].match(/description\s*=\s*"([^"]+)"/);
+    if (nameM) paramStrings.push({ name: nameM[1], description: descM ? descM[1] : '' });
+  }
+
+  // Extract @EventAttribute annotations
+  const eventAttributes = [];
+  const eaRegex = /@EventAttribute\s*\(\s*([\s\S]*?)\)/g;
+  let ea;
+  while ((ea = eaRegex.exec(src)) !== null) {
+    const nameM = ea[1].match(/name\s*=\s*"([^"]+)"/);
+    const descM = ea[1].match(/description\s*=\s*"([^"]+)"/);
+    if (nameM) eventAttributes.push({ name: nameM[1], description: descM ? descM[1] : '' });
+  }
+
+  // Extract class-level Javadoc
+  const javadocMatch = src.match(/\/\*\*\s*([\s\S]*?)\s*\*\/\s*(?:@RuleInfo|@ParamString|@Slf4j|public\s+class)/);
+  let javadoc = null;
+  if (javadocMatch) {
+    javadoc = javadocMatch[1]
+      .split('\n')
+      .map(l => l.replace(/^\s*\*\s?/, '').trim())
+      .filter(l => l && !l.startsWith('@'))
+      .join(' ')
+      .trim();
+  }
+
+  // Extract extends class
+  const extendsMatch = src.match(/class\s+\w+\s+extends\s+(\w+)/);
+  const extendsClass = extendsMatch ? extendsMatch[1] : null;
+
+  // Count lines
+  const lineCount = src.split('\n').length;
+
+  // Detect key patterns
+  const patterns = [];
+  if (src.includes('postWebhook')) patterns.push('WEBHOOK');
+  if (src.includes('SendEvent') || src.includes('sendEvent') || src.includes('action().sendEvent')) patterns.push('SENDS_EVENT');
+  if (src.includes('SetState') || src.includes('setState') || src.includes('setStatus')) patterns.push('STATUS_CHANGE');
+  if (src.includes('DynamicUtils.mutate')) patterns.push('MUTATION');
+  if (src.includes('DynamicUtils.query')) patterns.push('QUERY');
+  if (src.includes('DynamicUtils.create')) patterns.push('CREATE_ENTITY');
+  if (src.includes('SettingUtils.getSetting')) patterns.push('READS_SETTING');
+  if (src.includes('getJsonPath')) patterns.push('JSON_PATH');
+  if (src.includes('queryList')) patterns.push('LIST_QUERY');
+
+  return {
+    className,
+    filePath,
+    ruleInfoName,
+    ruleInfoDesc,
+    paramStrings,
+    eventAttributes,
+    javadoc,
+    extendsClass,
+    lineCount,
+    patterns,
+  };
+}
+
+function buildRuleSourceIndex(workspacePath, profile) {
+  const index = new Map(); // className -> { source: ParsedJava, isCustom: boolean, modulePath: string }
+
+  if (!profile || !workspacePath) return index;
+
+  const backendDir = join(workspacePath, 'accounts', profile, 'SOURCE', 'backend');
+  if (!existsSync(backendDir)) return index;
+
+  // Scan custom source (exclude .decompiled)
+  for (const entry of readdirSync(backendDir)) {
+    if (entry === '.decompiled') continue;
+    const moduleDir = join(backendDir, entry);
+    if (!statSync(moduleDir).isDirectory()) continue;
+    const javaFiles = findJavaFiles(moduleDir);
+    for (const f of javaFiles) {
+      const parsed = parseJavaSource(f);
+      index.set(parsed.className, {
+        source: parsed,
+        isCustom: true,
+        modulePath: entry,
+      });
+    }
+  }
+
+  // Scan decompiled OOTB source
+  const decompiledDir = join(backendDir, '.decompiled');
+  if (existsSync(decompiledDir)) {
+    for (const entry of readdirSync(decompiledDir)) {
+      const pluginDir = join(decompiledDir, entry);
+      if (!statSync(pluginDir).isDirectory()) continue;
+      const javaFiles = findJavaFiles(pluginDir);
+      for (const f of javaFiles) {
+        const parsed = parseJavaSource(f);
+        // Don't overwrite custom source with decompiled
+        if (!index.has(parsed.className)) {
+          index.set(parsed.className, {
+            source: parsed,
+            isCustom: false,
+            modulePath: `.decompiled/${entry}`,
+          });
+        }
+      }
+    }
+  }
+
+  return index;
+}
+
+function resolveRuleSource(ruleName, sourceIndex) {
+  // Rule name format: "NAMESPACE.module.ClassName" or "NAMESPACE.ClassName"
+  const parts = ruleName.split('.');
+  const className = parts[parts.length - 1];
+  return sourceIndex.get(className) || null;
+}
+
+// ─── Status Flow Graph Builder ───────────────────────────────────────────────
+
+function buildStatusFlows(wfData) {
+  // For each entity type, trace status transitions from rulesets
+  const flows = {}; // entityType -> [{from, to, via, rules}]
+
+  for (const [entityType, rulesets] of Object.entries(wfData.rulesetsByEntity)) {
+    flows[entityType] = [];
+    const edges = new Map(); // "from->to" -> {from, to, via: [rulesetName], rules: [ruleName]}
+
+    for (const rs of rulesets) {
+      const triggerStatuses = (rs.triggers || []).map(t => t.status);
+
+      // Find status changes in rules (SetState, UpdateStatusHistory)
+      for (const rule of (rs.rules || [])) {
+        let toStatus = null;
+        if (rule.props) {
+          if (rule.props.status && (rule.name.includes('SetState') || rule.name.includes('setState'))) {
+            toStatus = rule.props.status;
+          }
+          if (rule.props.toStatus && rule.name.includes('UpdateStatusHistory')) {
+            toStatus = rule.props.toStatus;
+          }
+        }
+
+        if (toStatus) {
+          for (const fromStatus of triggerStatuses) {
+            const key = `${fromStatus}->${toStatus}`;
+            if (!edges.has(key)) {
+              edges.set(key, { from: fromStatus, to: toStatus, via: [], rules: [] });
+            }
+            const edge = edges.get(key);
+            if (!edge.via.includes(rs.name)) edge.via.push(rs.name);
+            if (!edge.rules.includes(rule.name)) edge.rules.push(rule.name);
+          }
+        }
+      }
+    }
+
+    flows[entityType] = [...edges.values()];
+  }
+
+  return flows;
+}
+
+// ─── Mermaid Diagram Generator ───────────────────────────────────────────────
+
+function generateStatusFlowMermaid(entityType, statusFlow, statuses) {
+  const lines = ['stateDiagram-v2'];
+  lines.push(`  direction TB`);
+
+  // Add state definitions with categories
+  const statusNames = new Set();
+  for (const edge of statusFlow) {
+    statusNames.add(edge.from);
+    statusNames.add(edge.to);
+  }
+
+  // Color by category
+  const categoryColors = {
+    BOOKING: '#4A90D9',
+    FULFILMENT: '#E8A838',
+    DELIVERY: '#7B68EE',
+    DONE: '#5CB85C',
+    EXCEPTION: '#D9534F',
+    GENERATION: '#9B59B6',
+  };
+
+  for (const s of (statuses || [])) {
+    if (statusNames.has(s.name) && s.category && categoryColors[s.category]) {
+      lines.push(`  state "${s.name}" as ${sanitizeMermaidId(s.name)}`);
+    }
+  }
+
+  // Transitions
+  for (const edge of statusFlow) {
+    const label = edge.via.join(', ');
+    const from = sanitizeMermaidId(edge.from);
+    const to = sanitizeMermaidId(edge.to);
+    lines.push(`  ${from} --> ${to} : ${label}`);
+  }
+
+  // Start state
+  if (statusFlow.length > 0) {
+    const hasCreated = statusNames.has('CREATED');
+    if (hasCreated) {
+      lines.push(`  [*] --> ${sanitizeMermaidId('CREATED')}`);
+    }
+  }
+
+  // Terminal states
+  const terminalStatuses = ['COMPLETE', 'COMPLETED', 'CANCELLED', 'FAILED'];
+  for (const ts of terminalStatuses) {
+    if (statusNames.has(ts)) {
+      lines.push(`  ${sanitizeMermaidId(ts)} --> [*]`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+function sanitizeMermaidId(name) {
+  return name.replace(/[^a-zA-Z0-9_]/g, '_');
+}
+
+function generateEventChainMermaid(wfData) {
+  const lines = ['flowchart TD'];
+
+  // Group by entity type for subgraph
+  const byEntity = {};
+  for (const chain of wfData.eventChains) {
+    const et = chain.entityType;
+    if (!byEntity[et]) byEntity[et] = [];
+    byEntity[et].push(chain);
+  }
+
+  for (const [et, chains] of Object.entries(byEntity)) {
+    lines.push(`  subgraph ${et}`);
+    for (const c of chains) {
+      const from = sanitizeMermaidId(`${et}_${c.from}`);
+      const to = sanitizeMermaidId(`${et}_${c.to}`);
+      const style = c.isNoMatch ? '-.->' : '-->';
+      const label = c.isNoMatch ? 'no-match' : '';
+      lines.push(`    ${from}["${c.from}"] ${style}|${label}| ${to}["${c.to}"]`);
+    }
+    lines.push(`  end`);
+  }
+
+  // Cross-entity event chains (e.g., ORDER -> FULFILMENT_CHOICE)
+  // Detect rules that send events to other entity types
+  for (const [et, rulesets] of Object.entries(wfData.rulesetsByEntity)) {
+    for (const rs of rulesets) {
+      for (const rule of (rs.rules || [])) {
+        if (rule.name.includes('SendEventForAllFulfilment') && rule.props?.eventName) {
+          const targetET = rule.name.includes('Choice') ? 'FULFILMENT_CHOICE' : 'FULFILMENT';
+          if (wfData.rulesetsByEntity[targetET]) {
+            const from = sanitizeMermaidId(`${et}_${rs.name}`);
+            const to = sanitizeMermaidId(`${targetET}_${rule.props.eventName}`);
+            lines.push(`  ${from} -.->|"fan-out"| ${to}`);
+          }
+        }
+      }
+    }
+  }
+
+  return lines.join('\n');
+}
+
+// ─── Report Generator ────────────────────────────────────────────────────────
+
+function generateMarkdownReport(wfData, sourceIndex, statusFlows, opts) {
+  const lines = [];
+  const hr = '---';
+
+  // Header
+  lines.push(`# Workflow Explainer: ${wfData.name}`);
+  lines.push('');
+  lines.push(`> Auto-generated by \`workflow-explainer.mjs\` on ${new Date().toISOString().split('T')[0]}`);
+  lines.push('');
+
+  // Summary table
+  lines.push('## Summary');
+  lines.push('');
+  lines.push('| Property | Value |');
+  lines.push('|----------|-------|');
+  lines.push(`| **Workflow** | \`${wfData.name}\` |`);
+  lines.push(`| **Version** | ${wfData.version} |`);
+  lines.push(`| **Root Entity** | ${wfData.entityType} |`);
+  lines.push(`| **Subtype** | ${wfData.entitySubtype} |`);
+  lines.push(`| **Retailer ID** | ${wfData.retailerId} |`);
+  lines.push(`| **Entity Types** | ${wfData.entityTypes.join(', ')} |`);
+  lines.push(`| **Total Rulesets** | ${wfData.rulesetCount} |`);
+  lines.push(`| **Total Statuses** | ${wfData.statusCount} |`);
+  lines.push(`| **Unique Rules** | ${wfData.allRules.size} |`);
+  lines.push(`| **User Actions** | ${wfData.userActions.reduce((n, ua) => n + ua.actions.length, 0)} |`);
+  lines.push('');
+  if (wfData.description) {
+    lines.push(`**Description:** ${wfData.description}`);
+    lines.push('');
+  }
+  if (wfData.versionComment) {
+    lines.push(`**Version Comment:** ${wfData.versionComment}`);
+    lines.push('');
+  }
+
+  // Rule classification
+  let customCount = 0;
+  let ootbCount = 0;
+  let unknownCount = 0;
+  for (const [ruleName] of wfData.allRules) {
+    const resolved = resolveRuleSource(ruleName, sourceIndex);
+    if (resolved) {
+      if (resolved.isCustom) customCount++;
+      else ootbCount++;
+    } else {
+      unknownCount++;
+    }
+  }
+  lines.push('### Rule Classification');
+  lines.push('');
+  lines.push(`| Type | Count |`);
+  lines.push(`|------|-------|`);
+  lines.push(`| Custom (source found) | ${customCount} |`);
+  lines.push(`| OOTB (decompiled) | ${ootbCount} |`);
+  lines.push(`| Unresolved (no source) | ${unknownCount} |`);
+  lines.push('');
+
+  lines.push(hr);
+  lines.push('');
+
+  // ─── Per-Entity Sections ───────────────────────────────────────────
+  for (const entityType of wfData.entityTypes) {
+    lines.push(`## Entity: ${entityType}`);
+    lines.push('');
+
+    // Statuses
+    const statuses = wfData.statusesByEntity[entityType] || [];
+    if (statuses.length > 0) {
+      lines.push('### Statuses');
+      lines.push('');
+      lines.push('| Status | Category |');
+      lines.push('|--------|----------|');
+      for (const s of statuses) {
+        lines.push(`| ${s.name} | ${s.category} |`);
+      }
+      lines.push('');
+    }
+
+    // Status Flow Diagram
+    const flow = statusFlows[entityType] || [];
+    if (flow.length > 0) {
+      lines.push('### Status Flow');
+      lines.push('');
+      lines.push('```mermaid');
+      lines.push(generateStatusFlowMermaid(entityType, flow, statuses));
+      lines.push('```');
+      lines.push('');
+
+      // Also show transitions as a table
+      lines.push('#### Transitions');
+      lines.push('');
+      lines.push('| From | To | Via Ruleset(s) |');
+      lines.push('|------|----|----------------|');
+      for (const edge of flow) {
+        lines.push(`| ${edge.from} | ${edge.to} | ${edge.via.join(', ')} |`);
+      }
+      lines.push('');
+    }
+
+    // Rulesets
+    const rulesets = wfData.rulesetsByEntity[entityType] || [];
+    if (rulesets.length > 0) {
+      lines.push(`### Rulesets (${rulesets.length})`);
+      lines.push('');
+
+      for (const rs of rulesets) {
+        lines.push(`#### \`${rs.name}\``);
+        lines.push('');
+        if (rs.description) {
+          lines.push(`> ${rs.description}`);
+          lines.push('');
+        }
+
+        // Triggers
+        const triggers = (rs.triggers || []).map(t => t.status).join(', ');
+        lines.push(`**Triggers:** ${triggers || 'none'}`);
+        lines.push('');
+
+        // Rules
+        if (rs.rules && rs.rules.length > 0) {
+          lines.push('**Rules (execution order):**');
+          lines.push('');
+          for (let i = 0; i < rs.rules.length; i++) {
+            const rule = rs.rules[i];
+            const resolved = resolveRuleSource(rule.name, sourceIndex);
+            const badge = resolved ? (resolved.isCustom ? ' `CUSTOM`' : ' `OOTB`') : '';
+            lines.push(`${i + 1}. **\`${rule.name}\`**${badge}`);
+
+            // Show props
+            if (rule.props && Object.keys(rule.props).length > 0) {
+              for (const [k, v] of Object.entries(rule.props)) {
+                const val = typeof v === 'object' ? JSON.stringify(v) : v;
+                lines.push(`   - \`${k}\`: \`${val}\``);
+              }
+            }
+
+            // Show source summary if available
+            if (resolved && resolved.source) {
+              const src = resolved.source;
+              if (src.ruleInfoDesc) {
+                lines.push(`   - *${src.ruleInfoDesc}*`);
+              }
+              if (src.patterns.length > 0) {
+                lines.push(`   - Patterns: ${src.patterns.join(', ')}`);
+              }
+            }
+          }
+          lines.push('');
+        }
+
+        // User Actions
+        if (rs.userActions && rs.userActions.length > 0) {
+          lines.push('**User Actions:**');
+          lines.push('');
+          for (const ua of rs.userActions) {
+            const label = ua.label || ua.name || '(unnamed)';
+            lines.push(`- **${label}** → event: \`${ua.eventName || '(none)'}\``);
+            if (ua.attributes && ua.attributes.length > 0) {
+              for (const attr of ua.attributes) {
+                lines.push(`  - \`${attr.name}\` (${attr.type}): ${attr.label || ''}`);
+              }
+            }
+          }
+          lines.push('');
+        }
+      }
+    }
+
+    lines.push(hr);
+    lines.push('');
+  }
+
+  // ─── Event Chain Diagram ───────────────────────────────────────────
+  if (wfData.eventChains.length > 0) {
+    lines.push('## Event Chain Map');
+    lines.push('');
+    lines.push('```mermaid');
+    lines.push(generateEventChainMermaid(wfData));
+    lines.push('```');
+    lines.push('');
+
+    lines.push('### Event Chain Details');
+    lines.push('');
+    lines.push('| Source Ruleset | Target Ruleset | Rule | Entity | Type |');
+    lines.push('|----------------|----------------|------|--------|------|');
+    for (const c of wfData.eventChains) {
+      const type = c.isNoMatch ? 'no-match' : 'match';
+      lines.push(`| ${c.from} | ${c.to} | ${c.rule.split('.').pop()} | ${c.entityType} | ${type} |`);
+    }
+    lines.push('');
+    lines.push(hr);
+    lines.push('');
+  }
+
+  // ─── Custom Rules Inventory ────────────────────────────────────────
+  lines.push('## Custom Rules Inventory');
+  lines.push('');
+
+  const customRules = [];
+  const ootbRules = [];
+  const unresolvedRules = [];
+
+  for (const [ruleName, ruleData] of wfData.allRules) {
+    const resolved = resolveRuleSource(ruleName, sourceIndex);
+    if (resolved) {
+      if (resolved.isCustom) customRules.push({ ruleName, ruleData, resolved });
+      else ootbRules.push({ ruleName, ruleData, resolved });
+    } else {
+      unresolvedRules.push({ ruleName, ruleData });
+    }
+  }
+
+  if (customRules.length > 0) {
+    lines.push(`### Custom Rules (${customRules.length})`);
+    lines.push('');
+
+    for (const { ruleName, ruleData, resolved } of customRules) {
+      const src = resolved.source;
+      lines.push(`#### \`${ruleName}\``);
+      lines.push('');
+      lines.push(`| Property | Value |`);
+      lines.push(`|----------|-------|`);
+      lines.push(`| **Module** | \`${resolved.modulePath}\` |`);
+      lines.push(`| **Class** | \`${src.className}\` |`);
+      lines.push(`| **Extends** | \`${src.extendsClass || 'N/A'}\` |`);
+      lines.push(`| **Lines** | ${src.lineCount} |`);
+      if (src.ruleInfoDesc) lines.push(`| **Description** | ${src.ruleInfoDesc} |`);
+      lines.push(`| **Used in** | ${ruleData.propsVariants.map(p => p.rulesetName).join(', ')} |`);
+      lines.push('');
+
+      // Javadoc summary
+      if (src.javadoc) {
+        const truncated = src.javadoc.length > 300 ? src.javadoc.slice(0, 300) + '...' : src.javadoc;
+        lines.push(`**Purpose:** ${truncated}`);
+        lines.push('');
+      }
+
+      // Params
+      if (src.paramStrings.length > 0) {
+        lines.push('**@ParamString props:**');
+        lines.push('');
+        lines.push('| Prop | Description |');
+        lines.push('|------|-------------|');
+        for (const p of src.paramStrings) {
+          lines.push(`| \`${p.name}\` | ${p.description} |`);
+        }
+        lines.push('');
+      }
+
+      // Event Attributes
+      if (src.eventAttributes.length > 0) {
+        lines.push('**@EventAttribute inputs:**');
+        lines.push('');
+        lines.push('| Attribute | Description |');
+        lines.push('|-----------|-------------|');
+        for (const a of src.eventAttributes) {
+          lines.push(`| \`${a.name}\` | ${a.description} |`);
+        }
+        lines.push('');
+      }
+
+      // Behavioral patterns
+      if (src.patterns.length > 0) {
+        lines.push(`**Behavioral patterns:** ${src.patterns.join(', ')}`);
+        lines.push('');
+      }
+
+      // Props variants across rulesets
+      if (ruleData.propsVariants.length > 1) {
+        lines.push('**Configuration variants:**');
+        lines.push('');
+        lines.push('| Ruleset | Entity | Key Props |');
+        lines.push('|---------|--------|-----------|');
+        for (const v of ruleData.propsVariants) {
+          const keyProps = v.props ? Object.entries(v.props).map(([k, val]) => `${k}=${typeof val === 'object' ? JSON.stringify(val) : val}`).join(', ') : '(none)';
+          lines.push(`| ${v.rulesetName} | ${v.entityType} | ${keyProps} |`);
+        }
+        lines.push('');
+      }
+    }
+  }
+
+  if (ootbRules.length > 0) {
+    lines.push(`### OOTB Rules (${ootbRules.length})`);
+    lines.push('');
+    lines.push('| Rule | Class | Used In |');
+    lines.push('|------|-------|---------|');
+    for (const { ruleName, ruleData, resolved } of ootbRules) {
+      const usedIn = ruleData.propsVariants.map(p => p.rulesetName).join(', ');
+      lines.push(`| \`${ruleName}\` | ${resolved.source.className} | ${usedIn} |`);
+    }
+    lines.push('');
+  }
+
+  if (unresolvedRules.length > 0) {
+    lines.push(`### Unresolved Rules (${unresolvedRules.length})`);
+    lines.push('');
+    lines.push('| Rule | Used In | Inferred Behavior |');
+    lines.push('|------|---------|-------------------|');
+    for (const { ruleName, ruleData } of unresolvedRules) {
+      const usedIn = ruleData.propsVariants.map(p => p.rulesetName).join(', ');
+      const inferred = inferBehavior(ruleName, ruleData);
+      lines.push(`| \`${ruleName}\` | ${usedIn} | ${inferred} |`);
+    }
+    lines.push('');
+  }
+
+  lines.push(hr);
+  lines.push('');
+
+  // ─── User Actions Summary ─────────────────────────────────────────
+  if (wfData.userActions.length > 0) {
+    lines.push('## User Actions');
+    lines.push('');
+    lines.push('| Ruleset | Entity | Subtype | Action | Event |');
+    lines.push('|---------|--------|---------|--------|-------|');
+    for (const ua of wfData.userActions) {
+      for (const action of ua.actions) {
+        lines.push(`| ${ua.rulesetName} | ${ua.entityType} | ${ua.subtype || '-'} | ${action.label || action.name || '-'} | \`${action.eventName || '-'}\` |`);
+      }
+    }
+    lines.push('');
+    lines.push(hr);
+    lines.push('');
+  }
+
+  // ─── Integration Points ────────────────────────────────────────────
+  lines.push('## Integration Points');
+  lines.push('');
+
+  // Webhooks
+  const webhooks = [];
+  for (const [ruleName, ruleData] of wfData.allRules) {
+    if (ruleName.toLowerCase().includes('webhook') || ruleName.toLowerCase().includes('Webhook')) {
+      for (const v of ruleData.propsVariants) {
+        if (v.props?.setting) {
+          webhooks.push({ ruleset: v.rulesetName, setting: v.props.setting, entity: v.entityType });
+        }
+      }
+    }
+  }
+  if (webhooks.length > 0) {
+    lines.push('### Webhooks');
+    lines.push('');
+    lines.push('| Ruleset | Setting | Entity |');
+    lines.push('|---------|---------|--------|');
+    for (const wh of webhooks) {
+      lines.push(`| ${wh.ruleset} | \`${wh.setting}\` | ${wh.entity} |`);
+    }
+    lines.push('');
+  }
+
+  // Scheduled/timeout events
+  const timeouts = [];
+  for (const [, rulesets] of Object.entries(wfData.rulesetsByEntity)) {
+    for (const rs of rulesets) {
+      if (rs.name.toLowerCase().includes('timeout') || rs.name.toLowerCase().includes('expired') ||
+          rs.name.toLowerCase().includes('schedule') || rs.name.toLowerCase().includes('grace')) {
+        timeouts.push({ name: rs.name, description: rs.description || '' });
+      }
+    }
+  }
+  if (timeouts.length > 0) {
+    lines.push('### Scheduled/Timeout Events');
+    lines.push('');
+    for (const t of timeouts) {
+      lines.push(`- **${t.name}**: ${t.description.slice(0, 120)}${t.description.length > 120 ? '...' : ''}`);
+    }
+    lines.push('');
+  }
+
+  // External inbound events (events that are triggered externally)
+  const inboundPatterns = ['Confirm', 'Reject', 'Notify', 'Cancel', 'Approve', 'Complete'];
+  const inboundEvents = [];
+  for (const [et, rulesets] of Object.entries(wfData.rulesetsByEntity)) {
+    for (const rs of rulesets) {
+      if (inboundPatterns.some(p => rs.name.startsWith(p)) && rs.description?.toLowerCase().includes('inbound')) {
+        inboundEvents.push({ name: rs.name, entity: et, description: rs.description || '' });
+      }
+    }
+  }
+  if (inboundEvents.length > 0) {
+    lines.push('### Inbound Events (External Integration)');
+    lines.push('');
+    lines.push('| Event | Entity | Purpose |');
+    lines.push('|-------|--------|---------|');
+    for (const ie of inboundEvents) {
+      const purpose = ie.description.slice(0, 100) + (ie.description.length > 100 ? '...' : '');
+      lines.push(`| \`${ie.name}\` | ${ie.entity} | ${purpose} |`);
+    }
+    lines.push('');
+  }
+
+  lines.push(hr);
+  lines.push('');
+  lines.push(`*Generated from \`${basename(opts.workflow)}\` v${wfData.version}*`);
+
+  return lines.join('\n');
+}
+
+function inferBehavior(ruleName, ruleData) {
+  const name = ruleName.toLowerCase();
+  const parts = ruleName.split('.');
+  const className = parts[parts.length - 1];
+
+  if (name.includes('setstate') || name.includes('setState')) return 'Sets entity status';
+  if (name.includes('sendevent')) {
+    const events = ruleData.propsVariants.filter(p => p.props?.eventName).map(p => p.props.eventName);
+    return events.length > 0 ? `Sends event: ${events.join(', ')}` : 'Sends inline event';
+  }
+  if (name.includes('webhook')) return 'Posts webhook to external system';
+  if (name.includes('upsert') && name.includes('attribute')) return 'Upserts entity attribute';
+  if (name.includes('create') && name.includes('fulfilment')) return 'Creates fulfilment entity';
+  if (name.includes('updatestatus')) return 'Updates status history attribute';
+  if (name.includes('verify') || name.includes('check')) return 'Conditional gate/check';
+  if (name.includes('cancel')) return 'Cancellation logic';
+  return `Inferred from name: ${className}`;
+}
+
+// ─── HTML Report Generator ───────────────────────────────────────────────────
+
+function wrapInHtml(markdownContent, title) {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>${escapeHtml(title)}</title>
+<script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"><\/script>
+<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"><\/script>
+<style>
+  :root {
+    --fc-primary: #1a1a2e;
+    --fc-accent: #e94560;
+    --fc-bg: #f8f9fa;
+    --fc-card: #ffffff;
+    --fc-border: #e0e0e0;
+    --fc-text: #2d2d2d;
+    --fc-muted: #6c757d;
+  }
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+    background: var(--fc-bg);
+    color: var(--fc-text);
+    line-height: 1.6;
+    padding: 2rem;
+    max-width: 1200px;
+    margin: 0 auto;
+  }
+  h1 { color: var(--fc-primary); border-bottom: 3px solid var(--fc-accent); padding-bottom: 0.5rem; margin-bottom: 1.5rem; }
+  h2 { color: var(--fc-primary); margin-top: 2rem; margin-bottom: 1rem; border-bottom: 1px solid var(--fc-border); padding-bottom: 0.3rem; }
+  h3 { color: var(--fc-primary); margin-top: 1.5rem; margin-bottom: 0.5rem; }
+  h4 { margin-top: 1.2rem; margin-bottom: 0.4rem; color: var(--fc-accent); }
+  table { border-collapse: collapse; width: 100%; margin: 0.5rem 0 1rem; }
+  th, td { border: 1px solid var(--fc-border); padding: 0.5rem 0.75rem; text-align: left; }
+  th { background: var(--fc-primary); color: white; font-weight: 600; }
+  tr:nth-child(even) { background: #f1f3f5; }
+  code { background: #e9ecef; padding: 0.15rem 0.4rem; border-radius: 3px; font-size: 0.9em; }
+  pre { background: #2d2d2d; color: #f8f8f2; padding: 1rem; border-radius: 6px; overflow-x: auto; margin: 1rem 0; }
+  pre code { background: none; color: inherit; padding: 0; }
+  blockquote { border-left: 4px solid var(--fc-accent); padding: 0.5rem 1rem; margin: 0.5rem 0; background: #fff3f5; }
+  hr { border: none; border-top: 1px solid var(--fc-border); margin: 1.5rem 0; }
+  ul, ol { padding-left: 1.5rem; margin: 0.5rem 0; }
+  li { margin: 0.2rem 0; }
+  .mermaid { background: white; padding: 1rem; border-radius: 6px; border: 1px solid var(--fc-border); margin: 1rem 0; text-align: center; }
+  em { color: var(--fc-muted); }
+  strong { color: var(--fc-primary); }
+  a { color: var(--fc-accent); text-decoration: none; }
+  a:hover { text-decoration: underline; }
+</style>
+</head>
+<body>
+<div id="content"></div>
+<script>
+  mermaid.initialize({ startOnLoad: false, theme: 'default', securityLevel: 'loose' });
+  const md = ${JSON.stringify(markdownContent)};
+  const renderer = new marked.Renderer();
+  renderer.code = function(codeObj) {
+    const text = typeof codeObj === 'object' ? codeObj.text : codeObj;
+    const lang = typeof codeObj === 'object' ? codeObj.lang : arguments[1];
+    if (lang === 'mermaid') {
+      return '<div class="mermaid">' + text + '</div>';
+    }
+    return '<pre><code>' + (typeof text === 'string' ? text.replace(/</g, '&lt;').replace(/>/g, '&gt;') : text) + '</code></pre>';
+  };
+  document.getElementById('content').innerHTML = marked.parse(md, { renderer });
+  mermaid.run();
+</script>
+</body>
+</html>`;
+}
+
+function escapeHtml(str) {
+  return str.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+// ─── Main ────────────────────────────────────────────────────────────────────
+
+function main() {
+  const opts = parseArgs();
+
+  // Resolve workflow path
+  let workflowPath = opts.workflow;
+  if (!existsSync(workflowPath)) {
+    workflowPath = resolve(opts.workspace, workflowPath);
+  }
+  if (!existsSync(workflowPath)) {
+    console.error(`Error: Workflow file not found: ${opts.workflow}`);
+    console.error(`  Tried: ${opts.workflow}`);
+    console.error(`  Tried: ${workflowPath}`);
+    process.exit(1);
+  }
+
+  console.error(`[workflow-explainer] Parsing: ${workflowPath}`);
+
+  // Parse workflow
+  const wfData = parseWorkflow(workflowPath);
+  console.error(`[workflow-explainer] Workflow: ${wfData.name} v${wfData.version}`);
+  console.error(`[workflow-explainer] Entities: ${wfData.entityTypes.join(', ')}`);
+  console.error(`[workflow-explainer] Rulesets: ${wfData.rulesetCount}, Statuses: ${wfData.statusCount}, Rules: ${wfData.allRules.size}`);
+
+  // Build source index
+  console.error(`[workflow-explainer] Scanning source code...`);
+  const sourceIndex = buildRuleSourceIndex(opts.workspace, opts.profile);
+  console.error(`[workflow-explainer] Source index: ${sourceIndex.size} classes (${[...sourceIndex.values()].filter(v => v.isCustom).length} custom, ${[...sourceIndex.values()].filter(v => !v.isCustom).length} OOTB)`);
+
+  // Match rules to source
+  let matched = 0;
+  for (const [ruleName] of wfData.allRules) {
+    if (resolveRuleSource(ruleName, sourceIndex)) matched++;
+  }
+  console.error(`[workflow-explainer] Rule resolution: ${matched}/${wfData.allRules.size} rules matched to source`);
+
+  // Build status flows
+  const statusFlows = buildStatusFlows(wfData);
+  for (const [et, flows] of Object.entries(statusFlows)) {
+    console.error(`[workflow-explainer] ${et}: ${flows.length} status transitions`);
+  }
+
+  // Generate report
+  const markdown = generateMarkdownReport(wfData, sourceIndex, statusFlows, opts);
+
+  // Output
+  if (opts.html) {
+    const html = wrapInHtml(markdown, `Workflow: ${wfData.name}`);
+    if (opts.output) {
+      writeFileSync(opts.output, html, 'utf-8');
+      console.error(`[workflow-explainer] HTML report written to: ${opts.output}`);
+    } else {
+      process.stdout.write(html);
+    }
+  } else {
+    if (opts.output) {
+      writeFileSync(opts.output, markdown, 'utf-8');
+      console.error(`[workflow-explainer] Markdown report written to: ${opts.output}`);
+    } else {
+      process.stdout.write(markdown);
+    }
+  }
+
+  console.error(`[workflow-explainer] Done.`);
+}
+
+main();