specweave 0.18.1 → 0.20.0

package/plugins/specweave-kafka/lib/documentation/diagram-generator.ts

@@ -0,0 +1,195 @@
+/**
+ * Diagram Generator
+ *
+ * Generates Mermaid data flow diagrams for Kafka ecosystems
+ *
+ * @module diagram-generator
+ */
+
+/**
+ * Data Flow Diagram Generator
+ *
+ * Creates Mermaid diagrams showing producer → topic → consumer flows
+ */
+export class DiagramGenerator {
+  /**
+   * Generate data flow diagram
+   */
+  static generateDataFlow(options: {
+    producers: { name: string; topics: string[] }[];
+    topics: string[];
+    consumers: { name: string; topics: string[] }[];
+  }): string {
+    const lines: string[] = [];
+
+    lines.push('```mermaid');
+    lines.push('graph LR');
+
+    // Producers
+    for (const producer of options.producers) {
+      const producerId = producer.name.replace(/[^a-zA-Z0-9]/g, '_');
+      lines.push(`    ${producerId}[${producer.name}]:::producer`);
+
+      for (const topic of producer.topics) {
+        const topicId = topic.replace(/[^a-zA-Z0-9]/g, '_');
+        lines.push(`    ${producerId} -->|produce| T_${topicId}`);
+      }
+    }
+
+    // Topics
+    for (const topic of options.topics) {
+      const topicId = topic.replace(/[^a-zA-Z0-9]/g, '_');
+      lines.push(`    T_${topicId}[(${topic})]:::topic`);
+    }
+
+    // Consumers
+    for (const consumer of options.consumers) {
+      const consumerId = consumer.name.replace(/[^a-zA-Z0-9]/g, '_');
+      lines.push(`    ${consumerId}[${consumer.name}]:::consumer`);
+
+      for (const topic of consumer.topics) {
+        const topicId = topic.replace(/[^a-zA-Z0-9]/g, '_');
+        lines.push(`    T_${topicId} -->|consume| ${consumerId}`);
+      }
+    }
+
+    // Styles
+    lines.push('');
+    lines.push('    classDef producer fill:#90EE90,stroke:#228B22,stroke-width:2px');
+    lines.push('    classDef topic fill:#87CEEB,stroke:#4682B4,stroke-width:2px');
+    lines.push('    classDef consumer fill:#FFB6C1,stroke:#FF69B4,stroke-width:2px');
+
+    lines.push('```');
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Generate architecture diagram
+   */
+  static generateArchitecture(options: {
+    brokers: number;
+    zookeeper?: boolean;
+    schemaRegistry?: boolean;
+    connectCluster?: boolean;
+    ksqlDB?: boolean;
+  }): string {
+    const lines: string[] = [];
+
+    lines.push('```mermaid');
+    lines.push('graph TB');
+    lines.push('    subgraph Kafka Cluster');
+
+    // Brokers
+    for (let i = 1; i <= options.brokers; i++) {
+      lines.push(`        B${i}[Broker ${i}]`);
+    }
+
+    lines.push('    end');
+
+    // ZooKeeper (legacy)
+    if (options.zookeeper) {
+      lines.push('    subgraph ZooKeeper Ensemble');
+      lines.push('        ZK1[ZooKeeper 1]');
+      lines.push('        ZK2[ZooKeeper 2]');
+      lines.push('        ZK3[ZooKeeper 3]');
+      lines.push('    end');
+
+      for (let i = 1; i <= options.brokers; i++) {
+        lines.push(`    B${i} --> ZK1`);
+      }
+    }
+
+    // Schema Registry
+    if (options.schemaRegistry) {
+      lines.push('    SR[Schema Registry]:::schemaRegistry');
+      lines.push('    SR --> B1');
+    }
+
+    // Kafka Connect
+    if (options.connectCluster) {
+      lines.push('    subgraph Kafka Connect Cluster');
+      lines.push('        C1[Connect Worker 1]');
+      lines.push('        C2[Connect Worker 2]');
+      lines.push('    end');
+      lines.push('    C1 --> B1');
+      lines.push('    C2 --> B1');
+    }
+
+    // ksqlDB
+    if (options.ksqlDB) {
+      lines.push('    KSQL[ksqlDB Server]:::ksqlDB');
+      lines.push('    KSQL --> B1');
+    }
+
+    // Styles
+    lines.push('');
+    lines.push('    classDef schemaRegistry fill:#FFA500,stroke:#FF8C00,stroke-width:2px');
+    lines.push('    classDef ksqlDB fill:#9370DB,stroke:#8B008B,stroke-width:2px');
+
+    lines.push('```');
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Generate multi-DC replication diagram
+   */
+  static generateMultiDCReplication(options: {
+    dataCenters: string[];
+    topology: 'active-passive' | 'active-active';
+  }): string {
+    const lines: string[] = [];
+
+    lines.push('```mermaid');
+    lines.push('graph LR');
+
+    if (options.topology === 'active-passive') {
+      lines.push(`    DC1[${options.dataCenters[0]}<br/>Primary]:::primary`);
+      lines.push(`    DC2[${options.dataCenters[1]}<br/>Standby]:::standby`);
+      lines.push('    DC1 -->|MirrorMaker 2| DC2');
+      lines.push('    Producers[Producers] --> DC1');
+      lines.push('    Consumers[Consumers] --> DC1');
+    } else {
+      lines.push(`    DC1[${options.dataCenters[0]}<br/>Active]:::active`);
+      lines.push(`    DC2[${options.dataCenters[1]}<br/>Active]:::active`);
+      lines.push('    DC1 <-->|Bidirectional<br/>Replication| DC2');
+      lines.push('    Producers1[Producers] --> DC1');
+      lines.push('    Producers2[Producers] --> DC2');
+      lines.push('    Consumers1[Consumers] --> DC1');
+      lines.push('    Consumers2[Consumers] --> DC2');
+    }
+
+    // Styles
+    lines.push('');
+    lines.push('    classDef primary fill:#90EE90,stroke:#228B22,stroke-width:3px');
+    lines.push('    classDef standby fill:#D3D3D3,stroke:#808080,stroke-width:2px');
+    lines.push('    classDef active fill:#87CEEB,stroke:#4682B4,stroke-width:3px');
+
+    lines.push('```');
+
+    return lines.join('\n');
+  }
+}
+
+/**
+ * Example Usage: Data Flow Diagram
+ *
+ * ```typescript
+ * const diagram = DiagramGenerator.generateDataFlow({
+ *   producers: [
+ *     { name: 'Order Service', topics: ['orders', 'order-events'] },
+ *     { name: 'Payment Service', topics: ['payments'] },
+ *   ],
+ *   topics: ['orders', 'order-events', 'payments'],
+ *   consumers: [
+ *     { name: 'Analytics Service', topics: ['orders', 'payments'] },
+ *     { name: 'Notification Service', topics: ['order-events'] },
+ *   ],
+ * });
+ *
+ * console.log(diagram);
+ * ```
+ */
+
+export default DiagramGenerator;

package/plugins/specweave-kafka/lib/documentation/exporter.js

@@ -0,0 +1,210 @@
+import * as fs from "fs";
+import * as path from "path";
+var ExportFormat = /* @__PURE__ */ ((ExportFormat2) => {
+  ExportFormat2["MARKDOWN"] = "markdown";
+  ExportFormat2["HTML"] = "html";
+  ExportFormat2["PDF"] = "pdf";
+  ExportFormat2["JSON"] = "json";
+  return ExportFormat2;
+})(ExportFormat || {});
+class DocumentationExporter {
+  /**
+   * Export documentation
+   */
+  static async export(content, options) {
+    if (!fs.existsSync(options.outputDir)) {
+      fs.mkdirSync(options.outputDir, { recursive: true });
+    }
+    const timestamp = options.includeTimestamp ? `-${(/* @__PURE__ */ new Date()).toISOString().replace(/:/g, "-").split(".")[0]}` : "";
+    const extension = this.getExtension(options.format);
+    const fileName = `${options.fileName}${timestamp}.${extension}`;
+    const filePath = path.join(options.outputDir, fileName);
+    switch (options.format) {
+      case "markdown" /* MARKDOWN */:
+        return this.exportMarkdown(content, filePath);
+      case "html" /* HTML */:
+        return this.exportHTML(content, filePath, options.customCSS);
+      case "pdf" /* PDF */:
+        return this.exportPDF(content, filePath, options.customCSS);
+      case "json" /* JSON */:
+        return this.exportJSON(content, filePath);
+      default:
+        throw new Error(`Unsupported export format: ${options.format}`);
+    }
+  }
+  /**
+   * Get file extension for format
+   */
+  static getExtension(format) {
+    switch (format) {
+      case "markdown" /* MARKDOWN */:
+        return "md";
+      case "html" /* HTML */:
+        return "html";
+      case "pdf" /* PDF */:
+        return "pdf";
+      case "json" /* JSON */:
+        return "json";
+      default:
+        return "txt";
+    }
+  }
+  /**
+   * Export as Markdown
+   */
+  static exportMarkdown(content, filePath) {
+    fs.writeFileSync(filePath, content, "utf-8");
+    return filePath;
+  }
+  /**
+   * Export as HTML
+   */
+  static exportHTML(content, filePath, customCSS) {
+    const htmlContent = this.markdownToHTML(content);
+    const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Kafka Documentation</title>
+    <style>
+        ${customCSS || this.getDefaultCSS()}
+    </style>
+</head>
+<body>
+    <div class="container">
+        ${htmlContent}
+    </div>
+</body>
+</html>`;
+    fs.writeFileSync(filePath, html, "utf-8");
+    return filePath;
+  }
+  /**
+   * Export as PDF
+   */
+  static exportPDF(content, filePath, customCSS) {
+    const htmlPath = filePath.replace(".pdf", ".html");
+    this.exportHTML(content, htmlPath, customCSS);
+    console.warn(
+      `PDF export requires additional setup (puppeteer, wkhtmltopdf, etc.). HTML file exported to: ${htmlPath}. Use a tool like puppeteer to convert to PDF.`
+    );
+    return htmlPath;
+  }
+  /**
+   * Export as JSON
+   */
+  static exportJSON(content, filePath) {
+    fs.writeFileSync(filePath, content, "utf-8");
+    return filePath;
+  }
+  /**
+   * Convert Markdown to HTML (simplified)
+   */
+  static markdownToHTML(markdown) {
+    let html = markdown;
+    html = html.replace(/^### (.*$)/gim, "<h3>$1</h3>");
+    html = html.replace(/^## (.*$)/gim, "<h2>$1</h2>");
+    html = html.replace(/^# (.*$)/gim, "<h1>$1</h1>");
+    html = html.replace(/\*\*(.*?)\*\*/g, "<strong>$1</strong>");
+    const tableRegex = /\|(.+)\|\n\|(.+)\|\n((?:\|.+\|\n?)+)/gm;
+    html = html.replace(tableRegex, (match) => {
+      const lines = match.trim().split("\n");
+      const headers = lines[0].split("|").filter((c) => c.trim()).map((h) => `<th>${h.trim()}</th>`).join("");
+      const rows = lines.slice(2).map((line) => {
+        const cells = line.split("|").filter((c) => c.trim()).map((c) => `<td>${c.trim()}</td>`).join("");
+        return `<tr>${cells}</tr>`;
+      }).join("");
+      return `<table><thead><tr>${headers}</tr></thead><tbody>${rows}</tbody></table>`;
+    });
+    html = html.replace(/```(.*?)\n([\s\S]*?)```/g, "<pre><code>$2</code></pre>");
+    html = html.replace(/\n\n/g, "</p><p>");
+    html = `<p>${html}</p>`;
+    return html;
+  }
+  /**
+   * Get default CSS for HTML export
+   */
+  static getDefaultCSS() {
+    return `
+      body {
+        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, sans-serif;
+        line-height: 1.6;
+        color: #333;
+        background: #f5f5f5;
+      }
+      .container {
+        max-width: 1000px;
+        margin: 40px auto;
+        padding: 40px;
+        background: white;
+        box-shadow: 0 2px 8px rgba(0,0,0,0.1);
+      }
+      h1 {
+        border-bottom: 3px solid #2196F3;
+        padding-bottom: 10px;
+        color: #1976D2;
+      }
+      h2 {
+        border-bottom: 2px solid #64B5F6;
+        padding-bottom: 8px;
+        color: #1976D2;
+        margin-top: 30px;
+      }
+      h3 {
+        color: #424242;
+        margin-top: 20px;
+      }
+      table {
+        width: 100%;
+        border-collapse: collapse;
+        margin: 20px 0;
+      }
+      th, td {
+        border: 1px solid #ddd;
+        padding: 12px;
+        text-align: left;
+      }
+      th {
+        background-color: #2196F3;
+        color: white;
+        font-weight: bold;
+      }
+      tr:nth-child(even) {
+        background-color: #f9f9f9;
+      }
+      pre {
+        background: #2e3440;
+        color: #d8dee9;
+        padding: 16px;
+        border-radius: 4px;
+        overflow-x: auto;
+      }
+      code {
+        font-family: 'Monaco', 'Courier New', monospace;
+        font-size: 14px;
+      }
+    `;
+  }
+  /**
+   * Batch export to multiple formats
+   */
+  static async exportMultiple(content, baseOptions) {
+    const formats = ["markdown" /* MARKDOWN */, "html" /* HTML */, "json" /* JSON */];
+    const results = [];
+    for (const format of formats) {
+      const filePath = await this.export(content, {
+        ...baseOptions,
+        format
+      });
+      results.push(filePath);
+    }
+    return results;
+  }
+}
+var exporter_default = DocumentationExporter;
+export {
+  DocumentationExporter,
+  ExportFormat,
+  exporter_default as default
+};