@fairfox/polly 0.1.1 → 0.1.2

package/vendor/visualize/src/codegen/structurizr.ts

@@ -0,0 +1,770 @@
+// Structurizr DSL generator
+
+import type { ArchitectureAnalysis } from "@fairfox/polly-analysis";
+
+export interface StructurizrDSLOptions {
+  /** Include dynamic diagrams for message flows */
+  includeDynamicDiagrams?: boolean;
+
+  /** Include component diagrams for contexts */
+  includeComponentDiagrams?: boolean;
+
+  /** Which contexts to generate component diagrams for */
+  componentDiagramContexts?: string[];
+
+  /** Custom theme URL */
+  theme?: string;
+
+  /** Custom styles */
+  styles?: Record<string, string>;
+}
+
+export class StructurizrDSLGenerator {
+  private analysis: ArchitectureAnalysis;
+  private options: StructurizrDSLOptions;
+
+  constructor(analysis: ArchitectureAnalysis, options: StructurizrDSLOptions = {}) {
+    this.analysis = analysis;
+    this.options = {
+      includeDynamicDiagrams: true,
+      includeComponentDiagrams: true,
+      componentDiagramContexts: ["background"],
+      theme: "https://static.structurizr.com/themes/default",
+      ...options,
+    };
+  }
+
+  /**
+   * Generate complete Structurizr DSL
+   */
+  generate(): string {
+    const parts: string[] = [];
+
+    parts.push(this.generateWorkspaceHeader());
+    parts.push(this.generateModel());
+    parts.push(this.generateViews());
+    parts.push(this.generateWorkspaceFooter());
+
+    return parts.join("\n\n");
+  }
+
+  /**
+   * Generate workspace header
+   */
+  private generateWorkspaceHeader(): string {
+    const { name, description } = this.analysis.system;
+
+    const parts = [`workspace "${this.escape(name)}" "${this.escape(description || "")}" {`];
+    parts.push("");
+    parts.push("  !identifiers hierarchical");
+
+    // Add ADRs if present
+    if (this.analysis.adrs && this.analysis.adrs.adrs.length > 0) {
+      parts.push("  !adrs " + this.analysis.adrs.directory);
+    }
+
+    return parts.join("\n");
+  }
+
+  /**
+   * Generate workspace footer
+   */
+  private generateWorkspaceFooter(): string {
+    return "}";
+  }
+
+  /**
+   * Generate model section
+   */
+  private generateModel(): string {
+    const parts: string[] = [];
+
+    parts.push("  model {");
+    parts.push(this.generatePeople());
+    parts.push(this.generateExternalSystems());
+    parts.push(this.generateMainSystem());
+    parts.push("  }");
+
+    return parts.join("\n\n");
+  }
+
+  /**
+   * Generate people/actors
+   */
+  private generatePeople(): string {
+    return `    user = person "User" "Extension user"`;
+  }
+
+  /**
+   * Generate external systems
+   */
+  private generateExternalSystems(): string {
+    const parts: string[] = [];
+
+    for (const integration of this.analysis.integrations) {
+      if (integration.type === "api" || integration.type === "websocket") {
+        const tech =
+          integration.technology || (integration.type === "websocket" ? "WebSocket" : "REST API");
+        let desc = integration.description || "";
+
+        // Generate better description from API calls if available
+        if (!desc && integration.calls && integration.calls.length > 0) {
+          const endpoints = integration.calls
+            .slice(0, 3)
+            .map((c) => c.endpoint)
+            .join(", ");
+          const methods = [...new Set(integration.calls.map((c) => c.method))].join(", ");
+          desc = `External API with endpoints: ${endpoints}. Methods: ${methods}`;
+        }
+
+        parts.push(
+          `    ${this.toId(integration.name)} = softwareSystem "${this.escape(integration.name)}" "${this.escape(desc)}" {`
+        );
+        parts.push(
+          `      tags "External System" "${integration.type === "websocket" ? "WebSocket" : "REST API"}"`
+        );
+        parts.push(`    }`);
+      }
+    }
+
+    return parts.join("\n");
+  }
+
+  /**
+   * Generate main system (the extension)
+   */
+  private generateMainSystem(): string {
+    const parts: string[] = [];
+
+    parts.push(`    extension = softwareSystem "${this.escape(this.analysis.system.name)}" {`);
+
+    // Generate containers (contexts)
+    for (const [contextType, contextInfo] of Object.entries(this.analysis.contexts)) {
+      parts.push(this.generateContainer(contextType, contextInfo));
+    }
+
+    // Generate relationships between containers
+    parts.push(this.generateContainerRelationships());
+
+    parts.push("    }");
+
+    return parts.join("\n\n");
+  }
+
+  /**
+   * Generate container (context)
+   */
+  private generateContainer(contextType: string, contextInfo: any): string {
+    const parts: string[] = [];
+
+    const technology = this.getContextTechnology(contextType);
+    const description = contextInfo.description || `${this.capitalize(contextType)} context`;
+
+    parts.push(
+      `      ${contextType} = container "${this.capitalize(contextType)}" "${this.escape(description)}" "${technology}" {`
+    );
+
+    // Generate components if enabled
+    if (
+      this.options.includeComponentDiagrams &&
+      this.options.componentDiagramContexts?.includes(contextType)
+    ) {
+      parts.push(this.generateComponents(contextType, contextInfo));
+      parts.push("");
+      parts.push(this.generateComponentRelationships(contextType, contextInfo));
+    }
+
+    parts.push("      }");
+
+    return parts.join("\n");
+  }
+
+  /**
+   * Generate components within a container
+   */
+  private generateComponents(contextType: string, contextInfo: any): string {
+    const parts: string[] = [];
+
+    // Generate components from handlers
+    const handlersByType = new Map<string, any[]>();
+    for (const handler of contextInfo.handlers) {
+      if (!handlersByType.has(handler.messageType)) {
+        handlersByType.set(handler.messageType, []);
+      }
+      handlersByType.get(handler.messageType)!.push(handler);
+    }
+
+    for (const [messageType, handlers] of handlersByType) {
+      const componentName = this.toComponentName(messageType);
+      const description = this.generateComponentDescription(messageType, handlers[0]);
+      const tags = this.getComponentTags(messageType, handlers[0]);
+
+      parts.push(
+        `        ${this.toId(componentName)} = component "${componentName}" "${description}" {`
+      );
+      if (tags.length > 0) {
+        parts.push(`          tags "${tags.join('" "')}"`);
+      }
+      parts.push(`        }`);
+    }
+
+    // Generate components from UI components
+    if (contextInfo.components) {
+      for (const comp of contextInfo.components) {
+        parts.push(
+          `        ${this.toId(comp.name)} = component "${comp.name}" "${this.escape(comp.description || "UI component")}" {`
+        );
+        parts.push(`          tags "UI Component"`);
+        parts.push(`        }`);
+      }
+    }
+
+    // Add Chrome API components if used
+    if (contextInfo.chromeAPIs && contextInfo.chromeAPIs.length > 0) {
+      for (const api of contextInfo.chromeAPIs) {
+        const apiId = this.toId(`chrome_${api}`);
+        parts.push(
+          `        ${apiId} = component "Chrome ${this.capitalize(api)} API" "Browser API for ${api}" {`
+        );
+        parts.push(`          tags "Chrome API" "External"`);
+        parts.push(`        }`);
+      }
+    }
+
+    return parts.join("\n");
+  }
+
+  /**
+   * Generate better component descriptions based on message type
+   */
+  private generateComponentDescription(messageType: string, handler: any): string {
+    const type = messageType.toLowerCase();
+
+    // Authentication related
+    if (type.includes("login")) {
+      return "Authenticates users and establishes sessions";
+    }
+    if (type.includes("logout")) {
+      return "Terminates user sessions and clears credentials";
+    }
+
+    // CRUD operations
+    if (type.includes("add") || type.includes("create")) {
+      const entity = type.replace(/_(add|create)/, "").replace(/_/g, " ");
+      return `Creates new ${entity} items and persists to storage`;
+    }
+    if (type.includes("remove") || type.includes("delete")) {
+      const entity = type.replace(/_(remove|delete)/, "").replace(/_/g, " ");
+      return `Removes ${entity} items from storage`;
+    }
+    if (type.includes("update") || type.includes("toggle")) {
+      const entity = type.replace(/_(update|toggle)/, "").replace(/_/g, " ");
+      return `Updates ${entity} item state and syncs with storage`;
+    }
+    if (type.includes("clear")) {
+      const entity = type.replace(/_clear.*/, "").replace(/_/g, " ");
+      return `Clears all ${entity} items matching criteria`;
+    }
+
+    // Query operations
+    if (type.includes("get") || type.includes("fetch") || type.includes("load")) {
+      const entity = type.replace(/_(get|fetch|load)/, "").replace(/_/g, " ");
+      return `Retrieves ${entity} data from storage`;
+    }
+
+    // Default
+    return `Processes ${messageType} messages and coordinates business logic`;
+  }
+
+  /**
+   * Determine appropriate tags for a component
+   */
+  private getComponentTags(messageType: string, handler: any): string[] {
+    const tags: string[] = ["Message Handler"];
+    const type = messageType.toLowerCase();
+
+    // Add functional tags
+    if (type.includes("login") || type.includes("logout") || type.includes("auth")) {
+      tags.push("Authentication");
+    } else if (
+      type.includes("add") ||
+      type.includes("create") ||
+      type.includes("update") ||
+      type.includes("delete") ||
+      type.includes("remove") ||
+      type.includes("toggle")
+    ) {
+      tags.push("CRUD");
+    } else if (type.includes("get") || type.includes("fetch") || type.includes("load")) {
+      tags.push("Query");
+    }
+
+    // Add domain tags
+    if (type.includes("user")) {
+      tags.push("User Management");
+    }
+    if (type.includes("todo")) {
+      tags.push("Todo Management");
+    }
+    if (type.includes("state")) {
+      tags.push("State Management");
+    }
+
+    return tags;
+  }
+
+  /**
+   * Generate relationships between components within a container
+   */
+  private generateComponentRelationships(contextType: string, contextInfo: any): string {
+    const parts: string[] = [];
+
+    // Build a map of handler components
+    const handlersByType = new Map<string, any[]>();
+    for (const handler of contextInfo.handlers) {
+      if (!handlersByType.has(handler.messageType)) {
+        handlersByType.set(handler.messageType, []);
+      }
+      handlersByType.get(handler.messageType)!.push(handler);
+    }
+
+    // Add relationships to Chrome APIs
+    if (contextInfo.chromeAPIs && contextInfo.chromeAPIs.length > 0) {
+      for (const api of contextInfo.chromeAPIs) {
+        const apiId = this.toId(`chrome_${api}`);
+
+        // Find handlers that use this API
+        for (const [messageType, handlers] of handlersByType) {
+          const componentId = this.toId(this.toComponentName(messageType));
+
+          // Infer relationship based on API
+          let description = `Uses ${api}`;
+          if (api === "storage") {
+            if (
+              messageType.toLowerCase().includes("get") ||
+              messageType.toLowerCase().includes("load")
+            ) {
+              description = "Reads from storage";
+            } else {
+              description = "Writes to storage";
+            }
+          } else if (api === "tabs") {
+            description = "Manages browser tabs";
+          } else if (api === "runtime") {
+            description = "Sends messages";
+          }
+
+          parts.push(`        ${componentId} -> ${apiId} "${description}"`);
+        }
+      }
+    }
+
+    // Add state management relationships (handlers that modify state)
+    const stateHandlers: string[] = [];
+    const queryHandlers: string[] = [];
+
+    for (const [messageType, handlers] of handlersByType) {
+      const type = messageType.toLowerCase();
+      const componentId = this.toId(this.toComponentName(messageType));
+
+      if (
+        type.includes("add") ||
+        type.includes("create") ||
+        type.includes("update") ||
+        type.includes("delete") ||
+        type.includes("remove") ||
+        type.includes("toggle") ||
+        type.includes("clear") ||
+        type.includes("login") ||
+        type.includes("logout")
+      ) {
+        stateHandlers.push(componentId);
+      } else if (type.includes("get") || type.includes("fetch") || type.includes("load")) {
+        queryHandlers.push(componentId);
+      }
+    }
+
+    // Create implicit state manager if we have state operations
+    if (stateHandlers.length > 0 && queryHandlers.length > 0) {
+      // Query handlers depend on state set by mutation handlers
+      for (const queryHandler of queryHandlers) {
+        for (const stateHandler of stateHandlers) {
+          if (queryHandler !== stateHandler) {
+            parts.push(`        ${stateHandler} -> ${queryHandler} "Updates state" {`);
+            parts.push(`          tags "Implicit"`);
+            parts.push(`        }`);
+          }
+        }
+      }
+    }
+
+    return parts.join("\n");
+  }
+
+  /**
+   * Generate relationships between containers
+   */
+  private generateContainerRelationships(): string {
+    const parts: string[] = [];
+
+    // Add user relationships
+    const uiContexts = ["popup", "options", "devtools"];
+    for (const contextType of Object.keys(this.analysis.contexts)) {
+      if (uiContexts.includes(contextType)) {
+        parts.push(`      user -> extension.${contextType} "Uses"`);
+      }
+    }
+
+    // Add message flow relationships
+    for (const flow of this.analysis.messageFlows) {
+      const tech = `Sends ${flow.messageType}`;
+      for (const to of flow.to) {
+        parts.push(`      extension.${flow.from} -> extension.${to} "${tech}"`);
+      }
+    }
+
+    // Add external API relationships
+    for (const integration of this.analysis.integrations) {
+      if (integration.type === "api" || integration.type === "websocket") {
+        // Find which contexts use this integration
+        for (const [contextType, contextInfo] of Object.entries(this.analysis.contexts)) {
+          const usesIntegration = contextInfo.externalAPIs.some((api: any) =>
+            integration.calls?.some((call) => call.endpoint === api.endpoint)
+          );
+
+          if (usesIntegration) {
+            const method = integration.type === "websocket" ? "Connects to" : "Calls";
+            parts.push(
+              `      extension.${contextType} -> ${this.toId(integration.name)} "${method}"`
+            );
+          }
+        }
+      }
+    }
+
+    return parts.join("\n");
+  }
+
+  /**
+   * Generate views section
+   */
+  private generateViews(): string {
+    const parts: string[] = [];
+
+    parts.push("  views {");
+    parts.push(this.generateSystemContextView());
+    parts.push(this.generateContainerView());
+
+    if (this.options.includeComponentDiagrams) {
+      for (const contextType of this.options.componentDiagramContexts || []) {
+        if (this.analysis.contexts[contextType]) {
+          parts.push(this.generateComponentView(contextType));
+        }
+      }
+    }
+
+    if (this.options.includeDynamicDiagrams) {
+      parts.push(this.generateDynamicViews());
+    }
+
+    parts.push(this.generateStyles());
+    parts.push("  }");
+
+    // Add documentation section if ADRs exist
+    if (this.analysis.adrs && this.analysis.adrs.adrs.length > 0) {
+      parts.push("");
+      parts.push(this.generateDocumentation());
+    }
+
+    return parts.join("\n\n");
+  }
+
+  /**
+   * Generate documentation section for ADRs
+   */
+  private generateDocumentation(): string {
+    if (!this.analysis.adrs || this.analysis.adrs.adrs.length === 0) {
+      return "";
+    }
+
+    const parts: string[] = [];
+    parts.push("  documentation {");
+
+    for (const adr of this.analysis.adrs.adrs) {
+      parts.push(`    decision "${adr.id}" {`);
+      parts.push(`      title "${this.escape(adr.title)}"`);
+      parts.push(`      status "${adr.status}"`);
+      parts.push(`      date "${adr.date}"`);
+      parts.push(`      content "${this.escape(adr.context)}"`);
+      parts.push("    }");
+    }
+
+    parts.push("  }");
+
+    return parts.join("\n");
+  }
+
+  /**
+   * Generate system context view
+   */
+  private generateSystemContextView(): string {
+    return `    systemContext extension "SystemContext" {
+      include *
+      autoLayout lr
+    }`;
+  }
+
+  /**
+   * Generate container view
+   */
+  private generateContainerView(): string {
+    return `    container extension "Containers" {
+      include *
+      autoLayout lr
+    }`;
+  }
+
+  /**
+   * Generate component view
+   */
+  private generateComponentView(contextType: string): string {
+    return `    component extension.${contextType} "Components_${this.capitalize(contextType)}" {
+      include *
+      autoLayout tb
+    }`;
+  }
+
+  /**
+   * Generate dynamic views for message flows
+   */
+  private generateDynamicViews(): string {
+    const parts: string[] = [];
+
+    // Group flows by domain/feature
+    const flowsByDomain = new Map<string, any[]>();
+
+    for (const flow of this.analysis.messageFlows) {
+      // Extract domain from message type (e.g., USER_LOGIN -> user, TODO_ADD -> todo)
+      const messageType = flow.messageType.toLowerCase();
+      let domain = "general";
+
+      if (
+        messageType.includes("user") ||
+        messageType.includes("login") ||
+        messageType.includes("logout") ||
+        messageType.includes("auth")
+      ) {
+        domain = "authentication";
+      } else if (messageType.includes("todo")) {
+        domain = "todo";
+      } else if (messageType.includes("state")) {
+        domain = "state";
+      }
+
+      if (!flowsByDomain.has(domain)) {
+        flowsByDomain.set(domain, []);
+      }
+      flowsByDomain.get(domain)!.push(flow);
+    }
+
+    // Generate a dynamic view for each domain
+    let count = 0;
+    for (const [domain, flows] of flowsByDomain) {
+      if (count >= 5) break; // Limit to avoid too many diagrams
+
+      const viewName = this.capitalize(domain) + " Flow";
+      parts.push(this.generateDynamicView(viewName, flows, domain));
+      count++;
+    }
+
+    return parts.join("\n\n");
+  }
+
+  /**
+   * Generate single dynamic view
+   */
+  private generateDynamicView(flowName: string, flows: any[], domain: string): string {
+    const parts: string[] = [];
+
+    // Create a user-centric description
+    const description = this.getDynamicViewDescription(domain);
+    parts.push(`    dynamic extension "${flowName}" "${description}" {`);
+
+    // Add user interaction if this is a UI flow
+    const uiContexts = ["popup", "options", "devtools"];
+    const hasUIFlow = flows.some((f) => uiContexts.includes(f.from));
+
+    if (hasUIFlow) {
+      // Start with user interaction
+      const firstFlow = flows.find((f) => uiContexts.includes(f.from));
+      if (firstFlow) {
+        const action = this.getUserAction(domain);
+        parts.push(`      user -> extension.${firstFlow.from} "${action}"`);
+      }
+    }
+
+    // Generate message flows
+    for (const flow of flows) {
+      const messageDesc = this.getMessageDescription(flow.messageType);
+
+      for (const to of flow.to) {
+        parts.push(`      extension.${flow.from} -> extension.${to} "${messageDesc}"`);
+      }
+    }
+
+    parts.push("      autoLayout lr");
+    parts.push("    }");
+
+    return parts.join("\n");
+  }
+
+  /**
+   * Get description for dynamic view based on domain
+   */
+  private getDynamicViewDescription(domain: string): string {
+    const descriptions: Record<string, string> = {
+      authentication: "User authentication and session management",
+      todo: "Todo item creation, updates, and retrieval",
+      state: "Application state synchronization",
+      general: "Message flow through the system",
+    };
+    return descriptions[domain] || descriptions.general;
+  }
+
+  /**
+   * Get user action description for domain
+   */
+  private getUserAction(domain: string): string {
+    const actions: Record<string, string> = {
+      authentication: "Initiates login",
+      todo: "Manages todo items",
+      state: "Requests state",
+      general: "Interacts",
+    };
+    return actions[domain] || actions.general;
+  }
+
+  /**
+   * Get message description based on type
+   */
+  private getMessageDescription(messageType: string): string {
+    const type = messageType.toLowerCase();
+
+    if (type.includes("login")) return "Authenticate user";
+    if (type.includes("logout")) return "End session";
+    if (type.includes("add") || type.includes("create")) return "Create item";
+    if (type.includes("remove") || type.includes("delete")) return "Delete item";
+    if (type.includes("update") || type.includes("toggle")) return "Update item";
+    if (type.includes("get") || type.includes("fetch")) return "Retrieve data";
+    if (type.includes("clear")) return "Clear items";
+
+    return messageType;
+  }
+
+  /**
+   * Generate styles
+   */
+  private generateStyles(): string {
+    const parts: string[] = [];
+
+    // Skip theme directive - causes issues with Structurizr CLI export
+    // The inline styles are sufficient for diagram generation
+    parts.push("    styles {");
+
+    // Default styles for containers (contexts)
+    const contextStyles: Record<string, string> = {
+      background: "#2E7D32",
+      content: "#F57C00",
+      popup: "#1976D2",
+      devtools: "#7B1FA2",
+      options: "#0288D1",
+      ...this.options.styles,
+    };
+
+    for (const [context, color] of Object.entries(contextStyles)) {
+      if (this.analysis.contexts[context]) {
+        parts.push(`      element "extension.${context}" {`);
+        parts.push(`        background ${color}`);
+        parts.push(`        color #ffffff`);
+        parts.push("      }");
+      }
+    }
+
+    parts.push("    }");
+
+    return parts.join("\n");
+  }
+
+  /**
+   * Get technology label for context
+   */
+  private getContextTechnology(contextType: string): string {
+    const technologies: Record<string, string> = {
+      background: "Service Worker / Background Script",
+      content: "Content Script",
+      popup: "Browser Action Popup",
+      devtools: "DevTools Panel",
+      options: "Options Page",
+      offscreen: "Offscreen Document",
+    };
+
+    return technologies[contextType] || "Extension Context";
+  }
+
+  /**
+   * Convert message type to component name
+   */
+  private toComponentName(messageType: string): string {
+    return (
+      messageType
+        .split("_")
+        .map((part) => this.capitalize(part.toLowerCase()))
+        .join(" ") + " Handler"
+    );
+  }
+
+  /**
+   * Convert name to identifier
+   */
+  private toId(name: string): string {
+    return name
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "_")
+      .replace(/^_|_$/g, "");
+  }
+
+  /**
+   * Convert flow name to view name
+   */
+  private toViewName(flowName: string): string {
+    return flowName
+      .split(/[_-]/)
+      .map((part) => this.capitalize(part))
+      .join(" ");
+  }
+
+  /**
+   * Capitalize first letter
+   */
+  private capitalize(str: string): string {
+    return str.charAt(0).toUpperCase() + str.slice(1);
+  }
+
+  /**
+   * Escape string for DSL
+   */
+  private escape(str: string): string {
+    return str.replace(/"/g, '\\"');
+  }
+}
+
+/**
+ * Generate Structurizr DSL from architecture analysis
+ */
+export function generateStructurizrDSL(
+  analysis: ArchitectureAnalysis,
+  options?: StructurizrDSLOptions
+): string {
+  const generator = new StructurizrDSLGenerator(analysis, options);
+  return generator.generate();
+}