@fairfox/polly 0.4.1 → 0.5.0

package/dist/vendor/visualize/src/cli.js

@@ -1314,16 +1314,250 @@ class IntegrationAnalyzer {
 }
 
 // vendor/analysis/src/extract/handlers.ts
-import { Project as Project4, SyntaxKind as SyntaxKind2, Node as Node4 } from "ts-morph";
+import { Project as Project4, SyntaxKind as SyntaxKind3, Node as Node5 } from "ts-morph";
 
+// vendor/analysis/src/extract/relationships.ts
+import { Node as Node4 } from "ts-morph";
+
+class RelationshipExtractor {
+  extractFromHandler(handlerNode, sourceFile, handlerName) {
+    const relationships = [];
+    const visited = new Set;
+    this.extractFromNode(handlerNode, sourceFile, handlerName, relationships, visited);
+    return this.deduplicateRelationships(relationships);
+  }
+  extractFromNode(node, sourceFile, handlerName, relationships, visited) {
+    node.forEachDescendant((descendant) => {
+      if (Node4.isCallExpression(descendant)) {
+        const expr = descendant.getExpression();
+        if (Node4.isIdentifier(expr)) {
+          const functionName = expr.getText();
+          const functionDecl = sourceFile.getFunction(functionName);
+          if (functionDecl && !visited.has(functionName)) {
+            visited.add(functionName);
+            const body = functionDecl.getBody();
+            if (body) {
+              this.extractFromNode(body, sourceFile, handlerName, relationships, visited);
+            }
+            return;
+          }
+        }
+        if (Node4.isPropertyAccessExpression(expr)) {
+          const rel2 = this.extractFromPropertyAccess(expr, handlerName);
+          if (rel2) {
+            relationships.push(rel2);
+            return;
+          }
+        }
+        const rel = this.extractFromFunctionCall(descendant, handlerName, sourceFile);
+        if (rel) {
+          relationships.push(rel);
+        }
+      }
+      if (Node4.isAwaitExpression(descendant)) {
+        const rel = this.extractFromDatabaseCall(descendant, handlerName);
+        if (rel) {
+          relationships.push(rel);
+        }
+      }
+      if (Node4.isCallExpression(descendant) && descendant.getExpression().getText() === "fetch") {
+        const rel = this.extractFromFetchCall(descendant, handlerName);
+        if (rel) {
+          relationships.push(rel);
+        }
+      }
+    });
+  }
+  extractFromFunctionCall(callExpr, handlerName, sourceFile) {
+    const expr = callExpr.getExpression();
+    const exprText = expr.getText();
+    const skipList = [
+      "console.",
+      "JSON.",
+      "Math.",
+      "Object.",
+      "Array.",
+      "String.",
+      "Number.",
+      "Date.",
+      "Promise.",
+      "setTimeout",
+      "setInterval",
+      "clearTimeout",
+      "clearInterval"
+    ];
+    if (skipList.some((skip) => exprText.startsWith(skip))) {
+      return null;
+    }
+    let functionName = exprText;
+    let targetComponent = null;
+    if (Node4.isPropertyAccessExpression(expr)) {
+      const objectExpr = expr.getExpression();
+      const objectName = objectExpr.getText();
+      const methodName = expr.getName();
+      targetComponent = this.inferComponentFromCall(objectName, methodName);
+      if (!targetComponent) {
+        return null;
+      }
+      functionName = methodName;
+    } else {
+      targetComponent = this.resolveComponentFromImport(exprText, sourceFile);
+      if (!targetComponent) {
+        return null;
+      }
+    }
+    return {
+      from: this.toComponentId(handlerName),
+      to: targetComponent,
+      description: `Calls ${functionName}()`,
+      technology: "Function Call",
+      confidence: "high",
+      evidence: [`Function call: ${exprText}`]
+    };
+  }
+  extractFromPropertyAccess(propAccess, handlerName) {
+    if (!Node4.isPropertyAccessExpression(propAccess)) {
+      return null;
+    }
+    const fullChain = propAccess.getText();
+    const objectExpr = propAccess.getExpression();
+    const objectName = objectExpr.getText();
+    const methodName = propAccess.getName();
+    const targetComponent = this.inferComponentFromCall(objectName, methodName);
+    if (!targetComponent) {
+      return null;
+    }
+    return {
+      from: this.toComponentId(handlerName),
+      to: targetComponent,
+      description: `Calls ${methodName}()`,
+      technology: "Function Call",
+      confidence: "high",
+      evidence: [`Property access: ${fullChain}`]
+    };
+  }
+  extractFromDatabaseCall(awaitExpr, handlerName) {
+    if (!Node4.isAwaitExpression(awaitExpr)) {
+      return null;
+    }
+    const innerExpr = awaitExpr.getExpression();
+    if (!Node4.isCallExpression(innerExpr)) {
+      return null;
+    }
+    const callExpr = innerExpr.getExpression().getText();
+    if (callExpr.includes("db.query") || callExpr.includes("db.execute") || callExpr.includes("db.select") || callExpr.includes("db.insert") || callExpr.includes("db.update") || callExpr.includes("db.delete")) {
+      const operation = this.inferDatabaseOperation(callExpr);
+      return {
+        from: this.toComponentId(handlerName),
+        to: "database",
+        description: operation,
+        technology: "SQL",
+        confidence: "high",
+        evidence: [`Database call: ${callExpr}`]
+      };
+    }
+    return null;
+  }
+  extractFromFetchCall(callExpr, handlerName) {
+    const args = callExpr.getArguments();
+    if (args.length === 0) {
+      return null;
+    }
+    const urlArg = args[0].getText();
+    let apiName = "external_api";
+    if (urlArg.includes("openai")) {
+      apiName = "openai_api";
+    } else if (urlArg.includes("anthropic")) {
+      apiName = "anthropic_api";
+    }
+    return {
+      from: this.toComponentId(handlerName),
+      to: apiName,
+      description: "Calls external API",
+      technology: "HTTP/REST",
+      confidence: "high",
+      evidence: [`fetch() call to: ${urlArg}`]
+    };
+  }
+  inferComponentFromCall(objectName, methodName) {
+    const mappings = {
+      db: "db_client",
+      database: "database",
+      repos: "repositories",
+      repository: "repositories",
+      cache: "cache",
+      storage: "storage",
+      ai: "ai_service",
+      auth: "auth_service",
+      authservice: "auth_service",
+      user: "user_service",
+      userservice: "user_service",
+      logger: "logger",
+      queue: "queue_service"
+    };
+    const normalized = objectName.toLowerCase();
+    return mappings[normalized] || null;
+  }
+  resolveComponentFromImport(functionName, sourceFile) {
+    for (const importDecl of sourceFile.getImportDeclarations()) {
+      const namedImports = importDecl.getNamedImports();
+      for (const namedImport of namedImports) {
+        if (namedImport.getName() === functionName) {
+          const modulePath = importDecl.getModuleSpecifierValue();
+          if (modulePath.includes("/db/") || modulePath.includes("/database/")) {
+            return "db_client";
+          }
+          if (modulePath.includes("/repos") || modulePath.includes("/repositories")) {
+            return "repositories";
+          }
+          if (modulePath.includes("/service") || modulePath.includes("/services")) {
+            const match = modulePath.match(/\/([^/]+)\.ts$/);
+            if (match) {
+              return this.toComponentId(match[1]);
+            }
+          }
+        }
+      }
+    }
+    return null;
+  }
+  inferDatabaseOperation(callExpr) {
+    if (callExpr.includes("query") || callExpr.includes("select")) {
+      return "Reads from database";
+    }
+    if (callExpr.includes("execute") || callExpr.includes("insert") || callExpr.includes("update") || callExpr.includes("delete")) {
+      return "Writes to database";
+    }
+    return "Accesses database";
+  }
+  toComponentId(name) {
+    return name.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_|_$/g, "");
+  }
+  deduplicateRelationships(relationships) {
+    const seen = new Set;
+    const unique = [];
+    for (const rel of relationships) {
+      const key = `${rel.from}->${rel.to}`;
+      if (!seen.has(key)) {
+        seen.add(key);
+        unique.push(rel);
+      }
+    }
+    return unique;
+  }
+}
+
+// vendor/analysis/src/extract/handlers.ts
 class HandlerExtractor {
   project;
   typeGuardCache;
+  relationshipExtractor;
   constructor(tsConfigPath) {
     this.project = new Project4({
       tsConfigFilePath: tsConfigPath
     });
     this.typeGuardCache = new WeakMap;
+    this.relationshipExtractor = new RelationshipExtractor;
   }
   extractHandlers() {
     const handlers = [];
@@ -1357,9 +1591,9 @@ class HandlerExtractor {
     const filePath = sourceFile.getFilePath();
     const context = this.inferContext(filePath);
     sourceFile.forEachDescendant((node) => {
-      if (Node4.isCallExpression(node)) {
+      if (Node5.isCallExpression(node)) {
         const expression = node.getExpression();
-        if (Node4.isPropertyAccessExpression(expression)) {
+        if (Node5.isPropertyAccessExpression(expression)) {
           const methodName = expression.getName();
           if (methodName === "on" || methodName === "addEventListener") {
             const handler = this.extractHandler(node, context, filePath);
@@ -1369,17 +1603,17 @@ class HandlerExtractor {
           }
         }
       }
-      if (Node4.isSwitchStatement(node)) {
+      if (Node5.isSwitchStatement(node)) {
         const switchHandlers = this.extractSwitchCaseHandlers(node, context, filePath);
         handlers.push(...switchHandlers);
       }
-      if (Node4.isVariableDeclaration(node)) {
+      if (Node5.isVariableDeclaration(node)) {
         const mapHandlers = this.extractHandlerMapPattern(node, context, filePath);
         handlers.push(...mapHandlers);
       }
-      if (Node4.isIfStatement(node)) {
+      if (Node5.isIfStatement(node)) {
         const parent = node.getParent();
-        const isElseIf = parent && Node4.isIfStatement(parent);
+        const isElseIf = parent && Node5.isIfStatement(parent);
         if (!isElseIf) {
           const typeGuardHandlers = this.extractTypeGuardHandlers(node, context, filePath);
           handlers.push(...typeGuardHandlers);
@@ -1395,9 +1629,9 @@ class HandlerExtractor {
     }
     const messageTypeArg = args[0];
     let messageType = null;
-    if (Node4.isStringLiteral(messageTypeArg)) {
+    if (Node5.isStringLiteral(messageTypeArg)) {
       messageType = messageTypeArg.getLiteralValue();
-    } else if (Node4.isTemplateExpression(messageTypeArg)) {
+    } else if (Node5.isTemplateExpression(messageTypeArg)) {
       messageType = messageTypeArg.getText().replace(/[`'"]/g, "");
     }
     if (!messageType) {
@@ -1407,11 +1641,20 @@ class HandlerExtractor {
     const assignments = [];
     const preconditions = [];
     const postconditions = [];
-    if (Node4.isArrowFunction(handlerArg) || Node4.isFunctionExpression(handlerArg)) {
+    if (Node5.isArrowFunction(handlerArg) || Node5.isFunctionExpression(handlerArg)) {
       this.extractAssignments(handlerArg, assignments);
       this.extractVerificationConditions(handlerArg, preconditions, postconditions);
     }
     const line = callExpr.getStartLineNumber();
+    const sourceFile = callExpr.getSourceFile();
+    const handlerName = `${messageType}_handler`;
+    let relationships = undefined;
+    if (Node5.isArrowFunction(handlerArg) || Node5.isFunctionExpression(handlerArg)) {
+      const detectedRelationships = this.relationshipExtractor.extractFromHandler(handlerArg, sourceFile, handlerName);
+      if (detectedRelationships.length > 0) {
+        relationships = detectedRelationships;
+      }
+    }
     return {
       messageType,
       node: context,
@@ -1421,17 +1664,18 @@ class HandlerExtractor {
       location: {
         file: filePath,
         line
-      }
+      },
+      relationships
     };
   }
   extractAssignments(funcNode, assignments) {
     funcNode.forEachDescendant((node) => {
-      if (Node4.isBinaryExpression(node)) {
+      if (Node5.isBinaryExpression(node)) {
         const operator = node.getOperatorToken().getText();
         if (operator === "=") {
           const left = node.getLeft();
           const right = node.getRight();
-          if (Node4.isPropertyAccessExpression(left)) {
+          if (Node5.isPropertyAccessExpression(left)) {
             const fieldPath = this.getPropertyPath(left);
             if (fieldPath.startsWith("state.")) {
               const field = fieldPath.substring(6);
@@ -1450,13 +1694,13 @@ class HandlerExtractor {
   }
   extractVerificationConditions(funcNode, preconditions, postconditions) {
     const body = funcNode.getBody();
-    const statements = Node4.isBlock(body) ? body.getStatements() : [body];
+    const statements = Node5.isBlock(body) ? body.getStatements() : [body];
     statements.forEach((statement, index) => {
-      if (Node4.isExpressionStatement(statement)) {
+      if (Node5.isExpressionStatement(statement)) {
         const expr = statement.getExpression();
-        if (Node4.isCallExpression(expr)) {
+        if (Node5.isCallExpression(expr)) {
           const callee = expr.getExpression();
-          if (Node4.isIdentifier(callee)) {
+          if (Node5.isIdentifier(callee)) {
             const functionName = callee.getText();
             if (functionName === "requires") {
               const condition = this.extractCondition(expr);
@@ -1482,7 +1726,7 @@ class HandlerExtractor {
     const conditionArg = args[0];
     const expression = conditionArg.getText();
     let message;
-    if (args.length >= 2 && Node4.isStringLiteral(args[1])) {
+    if (args.length >= 2 && Node5.isStringLiteral(args[1])) {
       message = args[1].getLiteralValue();
     }
     const line = callExpr.getStartLineNumber();
@@ -1499,29 +1743,29 @@ class HandlerExtractor {
   getPropertyPath(node) {
     const parts = [];
     let current = node;
-    while (Node4.isPropertyAccessExpression(current)) {
+    while (Node5.isPropertyAccessExpression(current)) {
       parts.unshift(current.getName());
       current = current.getExpression();
     }
-    if (Node4.isIdentifier(current)) {
+    if (Node5.isIdentifier(current)) {
       parts.unshift(current.getText());
     }
     return parts.join(".");
   }
   extractValue(node) {
-    if (Node4.isStringLiteral(node)) {
+    if (Node5.isStringLiteral(node)) {
       return node.getLiteralValue();
     }
-    if (Node4.isNumericLiteral(node)) {
+    if (Node5.isNumericLiteral(node)) {
       return node.getLiteralValue();
     }
-    if (node.getKind() === SyntaxKind2.TrueKeyword) {
+    if (node.getKind() === SyntaxKind3.TrueKeyword) {
       return true;
     }
-    if (node.getKind() === SyntaxKind2.FalseKeyword) {
+    if (node.getKind() === SyntaxKind3.FalseKeyword) {
       return false;
     }
-    if (node.getKind() === SyntaxKind2.NullKeyword) {
+    if (node.getKind() === SyntaxKind3.NullKeyword) {
       return null;
     }
     return;
@@ -1536,10 +1780,10 @@ class HandlerExtractor {
       }
       const caseClauses = switchNode.getClauses();
       for (const clause of caseClauses) {
-        if (Node4.isCaseClause(clause)) {
+        if (Node5.isCaseClause(clause)) {
           const caseExpr = clause.getExpression();
           let messageType = null;
-          if (Node4.isStringLiteral(caseExpr)) {
+          if (Node5.isStringLiteral(caseExpr)) {
             messageType = caseExpr.getLiteralValue();
           }
           if (messageType) {
@@ -1562,7 +1806,7 @@ class HandlerExtractor {
     const handlers = [];
     try {
       const initializer = varDecl.getInitializer();
-      if (!initializer || !Node4.isObjectLiteralExpression(initializer)) {
+      if (!initializer || !Node5.isObjectLiteralExpression(initializer)) {
         return handlers;
       }
       const varName = varDecl.getName().toLowerCase();
@@ -1571,12 +1815,12 @@ class HandlerExtractor {
       }
       const properties = initializer.getProperties();
       for (const prop of properties) {
-        if (Node4.isPropertyAssignment(prop)) {
+        if (Node5.isPropertyAssignment(prop)) {
           const nameNode = prop.getNameNode();
           let messageType = null;
-          if (Node4.isStringLiteral(nameNode)) {
+          if (Node5.isStringLiteral(nameNode)) {
             messageType = nameNode.getLiteralValue();
-          } else if (Node4.isIdentifier(nameNode)) {
+          } else if (Node5.isIdentifier(nameNode)) {
             messageType = nameNode.getText();
           }
           if (messageType) {
@@ -1623,7 +1867,7 @@ class HandlerExtractor {
           }
         }
         const elseStatement = currentIf.getElseStatement();
-        if (elseStatement && Node4.isIfStatement(elseStatement)) {
+        if (elseStatement && Node5.isIfStatement(elseStatement)) {
           currentIf = elseStatement;
         } else {
           break;
@@ -1639,12 +1883,12 @@ class HandlerExtractor {
   extractHandlerFromIfClause(ifNode, typeGuards, context, filePath) {
     try {
       const condition = ifNode.getExpression();
-      if (!Node4.isCallExpression(condition)) {
+      if (!Node5.isCallExpression(condition)) {
         return null;
       }
       const funcExpr = condition.getExpression();
       let funcName;
-      if (Node4.isIdentifier(funcExpr)) {
+      if (Node5.isIdentifier(funcExpr)) {
         funcName = funcExpr.getText();
       }
       if (process.env.POLLY_DEBUG && funcName) {
@@ -1656,7 +1900,7 @@ class HandlerExtractor {
         if (process.env.POLLY_DEBUG) {
           console.log(`[DEBUG] Found in local type guards: ${funcName} → ${messageType}`);
         }
-      } else if (Node4.isIdentifier(funcExpr)) {
+      } else if (Node5.isIdentifier(funcExpr)) {
         if (process.env.POLLY_DEBUG) {
           console.log(`[DEBUG] Not found locally, trying import resolution for: ${funcName}`);
         }
@@ -1669,13 +1913,24 @@ class HandlerExtractor {
         return null;
       }
       const line = ifNode.getStartLineNumber();
+      const sourceFile = ifNode.getSourceFile();
+      const handlerName = `${messageType}_handler`;
+      let relationships = undefined;
+      const thenStatement = ifNode.getThenStatement();
+      if (thenStatement) {
+        const detectedRelationships = this.relationshipExtractor.extractFromHandler(thenStatement, sourceFile, handlerName);
+        if (detectedRelationships.length > 0) {
+          relationships = detectedRelationships;
+        }
+      }
       return {
         messageType,
         node: context,
         assignments: [],
         preconditions: [],
         postconditions: [],
-        location: { file: filePath, line }
+        location: { file: filePath, line },
+        relationships
       };
     } catch (error) {
       return null;
@@ -1684,20 +1939,20 @@ class HandlerExtractor {
   findTypePredicateFunctions(sourceFile) {
     const typeGuards = new Map;
     sourceFile.forEachDescendant((node) => {
-      if (Node4.isFunctionDeclaration(node) || Node4.isFunctionExpression(node) || Node4.isArrowFunction(node)) {
+      if (Node5.isFunctionDeclaration(node) || Node5.isFunctionExpression(node) || Node5.isArrowFunction(node)) {
         const returnTypeNode = node.getReturnTypeNode();
-        if (returnTypeNode && Node4.isTypePredicate(returnTypeNode)) {
+        if (returnTypeNode && Node5.isTypePredicate(returnTypeNode)) {
           let functionName;
-          if (Node4.isFunctionDeclaration(node)) {
+          if (Node5.isFunctionDeclaration(node)) {
             functionName = node.getName();
-          } else if (Node4.isFunctionExpression(node)) {
+          } else if (Node5.isFunctionExpression(node)) {
             const parent = node.getParent();
-            if (Node4.isVariableDeclaration(parent)) {
+            if (Node5.isVariableDeclaration(parent)) {
               functionName = parent.getName();
             }
-          } else if (Node4.isArrowFunction(node)) {
+          } else if (Node5.isArrowFunction(node)) {
             const parent = node.getParent();
-            if (Node4.isVariableDeclaration(parent)) {
+            if (Node5.isVariableDeclaration(parent)) {
               functionName = parent.getName();
             }
           }
@@ -1738,15 +1993,15 @@ class HandlerExtractor {
         return null;
       }
       for (const def of definitions) {
-        if (Node4.isFunctionDeclaration(def) || Node4.isFunctionExpression(def) || Node4.isArrowFunction(def)) {
+        if (Node5.isFunctionDeclaration(def) || Node5.isFunctionExpression(def) || Node5.isArrowFunction(def)) {
           const returnTypeNode = def.getReturnTypeNode();
           if (process.env.POLLY_DEBUG) {
             const returnType = def.getReturnType().getText();
             console.log(`[DEBUG] Function ${funcName} return type (resolved): ${returnType}`);
             console.log(`[DEBUG] Has return type node: ${!!returnTypeNode}`);
-            console.log(`[DEBUG] Is type predicate node: ${returnTypeNode && Node4.isTypePredicate(returnTypeNode)}`);
+            console.log(`[DEBUG] Is type predicate node: ${returnTypeNode && Node5.isTypePredicate(returnTypeNode)}`);
           }
-          if (returnTypeNode && Node4.isTypePredicate(returnTypeNode)) {
+          if (returnTypeNode && Node5.isTypePredicate(returnTypeNode)) {
             const typeNode = returnTypeNode.getTypeNode();
             if (typeNode) {
               const typeName = typeNode.getText();
@@ -2288,10 +2543,33 @@ class StructurizrDSLGenerator {
     if (this.options.groups && this.options.groups.length > 0) {
       parts.push(...this.generateGroupedComponents(componentDefs, this.options.groups));
     } else {
-      for (const comp of componentDefs) {
-        parts.push(this.generateComponentDefinition(comp, "        "));
+      const autoGroups = this.generateAutomaticGroups(componentDefs);
+      if (autoGroups.length > 0) {
+        parts.push(...this.generateGroupedComponents(componentDefs, autoGroups));
+      } else {
+        for (const comp of componentDefs) {
+          parts.push(this.generateComponentDefinition(comp, "        "));
+        }
       }
     }
+    const serviceComponents = new Set;
+    for (const handler of contextInfo.handlers) {
+      if (handler.relationships) {
+        for (const rel of handler.relationships) {
+          const targetId = this.toId(rel.to);
+          const isHandler = componentDefs.some((c) => c.id === targetId);
+          if (!isHandler) {
+            serviceComponents.add(rel.to);
+          }
+        }
+      }
+    }
+    for (const serviceId of serviceComponents) {
+      const serviceName = serviceId.split("_").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+      parts.push(`        ${this.toId(serviceId)} = component "${serviceName}" "Business logic service" {`);
+      parts.push(`          tags "Service" "Auto-detected"`);
+      parts.push(`        }`);
+    }
     if (contextInfo.components) {
       for (const comp of contextInfo.components) {
         parts.push(`        ${this.toId(comp.name)} = component "${comp.name}" "${this.escape(comp.description || "UI component")}" {`);
@@ -2444,6 +2722,21 @@ class StructurizrDSLGenerator {
         parts.push(`        }`);
       }
     }
+    for (const handler of contextInfo.handlers) {
+      if (handler.relationships && handler.relationships.length > 0) {
+        for (const rel of handler.relationships) {
+          const fromId = this.toId(rel.from);
+          const toId = this.toId(rel.to);
+          const description = this.escape(rel.description);
+          parts.push(`        ${fromId} -> ${toId} "${description}" {`);
+          if (rel.technology) {
+            parts.push(`          technology "${this.escape(rel.technology)}"`);
+          }
+          parts.push(`          tags "Auto-detected"`);
+          parts.push(`        }`);
+        }
+      }
+    }
     const stateHandlers = [];
     const queryHandlers = [];
     for (const [messageType, handlers] of handlersByType) {
@@ -2568,6 +2861,10 @@ class StructurizrDSLGenerator {
         parts.push(this.generateUserDynamicDiagram(diagram));
       }
     }
+    const autoDiagrams = this.generateAutomaticDynamicDiagrams();
+    if (autoDiagrams.length > 0) {
+      parts.push(...autoDiagrams);
+    }
     const flowsByDomain = new Map;
     for (const flow of this.analysis.messageFlows) {
       const messageType = flow.messageType.toLowerCase();
@@ -2596,6 +2893,111 @@ class StructurizrDSLGenerator {
 
 `);
   }
+  generateAutomaticDynamicDiagrams() {
+    const diagrams = [];
+    const processedHandlers = new Set;
+    const handlersWithRelationships = [];
+    for (const [contextType, contextInfo] of Object.entries(this.analysis.contexts)) {
+      for (const handler of contextInfo.handlers) {
+        if (handler.relationships && handler.relationships.length > 0) {
+          handlersWithRelationships.push({
+            handler,
+            contextType,
+            contextName: this.toId(contextType)
+          });
+        }
+      }
+    }
+    const handlerGroups = new Map;
+    for (const hwc of handlersWithRelationships) {
+      const messageType = hwc.handler.messageType.toLowerCase();
+      let category = "general";
+      if (messageType.includes("auth") || messageType.includes("login") || messageType.includes("logout") || messageType.includes("verify") || messageType.includes("register")) {
+        category = "authentication";
+      } else if (messageType.includes("user")) {
+        category = "user";
+      } else if (messageType.includes("todo")) {
+        category = "todo";
+      } else if (messageType.includes("query") || messageType.includes("get") || messageType.includes("fetch") || messageType.includes("list")) {
+        category = "query";
+      } else if (messageType.includes("command") || messageType.includes("create") || messageType.includes("update") || messageType.includes("delete") || messageType.includes("add") || messageType.includes("remove")) {
+        category = "command";
+      }
+      if (!handlerGroups.has(category)) {
+        handlerGroups.set(category, []);
+      }
+      handlerGroups.get(category).push(hwc);
+    }
+    let diagramCount = 0;
+    const maxDiagrams = 5;
+    const totalHandlers = handlersWithRelationships.length;
+    const categoriesWithHandlers = handlerGroups.size;
+    if (totalHandlers <= 5 && categoriesWithHandlers <= 3) {
+      const allHandlers = Array.from(handlerGroups.values()).flat();
+      const diagram = this.generateHandlerFlowDiagram("general", allHandlers);
+      if (diagram) {
+        diagrams.push(diagram);
+      }
+    } else {
+      for (const [category, handlers] of handlerGroups) {
+        if (diagramCount >= maxDiagrams)
+          break;
+        if (handlers.length === 0)
+          continue;
+        const diagram = this.generateHandlerFlowDiagram(category, handlers);
+        if (diagram) {
+          diagrams.push(diagram);
+          diagramCount++;
+        }
+      }
+    }
+    return diagrams;
+  }
+  generateHandlerFlowDiagram(category, handlers) {
+    const parts = [];
+    const title = this.getCategoryTitle(category);
+    const description = this.getCategoryDescription(category);
+    const scope = handlers[0]?.contextName ? `extension.${handlers[0].contextName}` : "extension";
+    parts.push(`    dynamic ${scope} "${title}" "${description}" {`);
+    let stepCount = 0;
+    for (const { handler, contextName } of handlers) {
+      const handlerComponentId = this.toId(`${handler.messageType}_handler`);
+      for (const rel of handler.relationships) {
+        const toComponent = this.toId(rel.to);
+        parts.push(`      ${handlerComponentId} -> ${toComponent} "${rel.description}"`);
+        stepCount++;
+      }
+    }
+    if (stepCount === 0) {
+      return null;
+    }
+    parts.push("      autoLayout lr");
+    parts.push("    }");
+    return parts.join(`
+`);
+  }
+  getCategoryTitle(category) {
+    const titles = {
+      authentication: "Authentication Flow",
+      user: "User Management Flow",
+      todo: "Todo Management Flow",
+      query: "Query Processing Flow",
+      command: "Command Processing Flow",
+      general: "Message Processing Flow"
+    };
+    return titles[category] || `${this.capitalize(category)} Flow`;
+  }
+  getCategoryDescription(category) {
+    const descriptions = {
+      authentication: "Shows authentication request processing and service interactions",
+      user: "Shows user management operations and service dependencies",
+      todo: "Shows todo item operations and service dependencies",
+      query: "Shows read operations flow through query handlers and services",
+      command: "Shows write operations flow through command handlers and services",
+      general: "Shows message processing flow through handlers and services"
+    };
+    return descriptions[category] || "Shows message flow through system components";
+  }
   generateUserDynamicDiagram(diagram) {
     const parts = [];
     parts.push(`    dynamic ${diagram.scope || "extension"} "${this.escape(diagram.title)}" "${this.escape(diagram.description || "")}" {`);
@@ -2892,6 +3294,105 @@ class StructurizrDSLGenerator {
     return parts.join(`
 `);
   }
+  generateAutomaticGroups(componentDefs) {
+    const groups = [];
+    const assigned = new Set;
+    const authHandlers = componentDefs.filter((comp) => {
+      const type = comp.messageType.toLowerCase();
+      return type.includes("login") || type.includes("logout") || type.includes("auth") || type.includes("verify") || type.includes("register") || type.includes("signup");
+    });
+    if (authHandlers.length > 0) {
+      groups.push({
+        name: "Authentication",
+        components: authHandlers.map((c) => c.id)
+      });
+      authHandlers.forEach((h) => assigned.add(h.id));
+    }
+    const subscriptionHandlers = componentDefs.filter((comp) => {
+      const type = comp.messageType.toLowerCase();
+      return type.includes("subscribe") || type.includes("unsubscribe");
+    });
+    if (subscriptionHandlers.length > 0) {
+      groups.push({
+        name: "Subscriptions",
+        components: subscriptionHandlers.map((c) => c.id)
+      });
+      subscriptionHandlers.forEach((h) => assigned.add(h.id));
+    }
+    const entityGroups = new Map;
+    for (const comp of componentDefs) {
+      if (assigned.has(comp.id))
+        continue;
+      const type = comp.messageType.toLowerCase();
+      if (type === "connection" || type === "message" || type === "close" || type === "error") {
+        continue;
+      }
+      let entity = null;
+      const underscoreMatch = type.match(/^([a-z]+)_(add|create|update|delete|remove|get|fetch|load|list|query)/);
+      if (underscoreMatch) {
+        entity = underscoreMatch[1];
+      }
+      if (!entity) {
+        const camelMatch = type.match(/(add|create|update|delete|remove|get|fetch|load|list|query)([a-z]+)/i);
+        if (camelMatch) {
+          entity = camelMatch[2].toLowerCase();
+        }
+      }
+      if (!entity && type.match(/^[a-z]+$/)) {
+        entity = type;
+      }
+      if (entity) {
+        if (!entityGroups.has(entity)) {
+          entityGroups.set(entity, []);
+        }
+        entityGroups.get(entity).push(comp.id);
+        assigned.add(comp.id);
+      }
+    }
+    for (const [entity, componentIds] of entityGroups) {
+      if (componentIds.length >= 2) {
+        const entityName = entity.charAt(0).toUpperCase() + entity.slice(1);
+        groups.push({
+          name: `${entityName} Management`,
+          components: componentIds
+        });
+      } else {
+        componentIds.forEach((id) => assigned.delete(id));
+      }
+    }
+    const queryHandlers = componentDefs.filter((comp) => {
+      if (assigned.has(comp.id))
+        return false;
+      const type = comp.messageType.toLowerCase();
+      return type.includes("query") || type.includes("get") || type.includes("fetch") || type.includes("load") || type.includes("list") || type.includes("read");
+    });
+    const commandHandlers = componentDefs.filter((comp) => {
+      if (assigned.has(comp.id))
+        return false;
+      const type = comp.messageType.toLowerCase();
+      return type.includes("command") || type.includes("add") || type.includes("create") || type.includes("update") || type.includes("delete") || type.includes("remove") || type.includes("set") || type.includes("clear");
+    });
+    if (queryHandlers.length >= 2) {
+      groups.push({
+        name: "Query Handlers",
+        components: queryHandlers.map((c) => c.id)
+      });
+      queryHandlers.forEach((h) => assigned.add(h.id));
+    }
+    if (commandHandlers.length >= 2) {
+      groups.push({
+        name: "Command Handlers",
+        components: commandHandlers.map((c) => c.id)
+      });
+      commandHandlers.forEach((h) => assigned.add(h.id));
+    }
+    const groupedCount = assigned.size;
+    const totalCount = componentDefs.length;
+    if (groupedCount >= totalCount * 0.5 || groups.length >= 2) {
+      return groups;
+    }
+    return [];
+  }
   generateGroupedComponents(componentDefs, groups) {
     const parts = [];
     const assignedComponents = new Set;
@@ -3399,4 +3900,4 @@ Stack trace:`, COLORS.gray));
   process.exit(1);
 });
 
-//# debugId=85D3947587AAAF0E64756E2164756E21
+//# debugId=59C09397E2AB6BFF64756E2164756E21