npm - specweave - Versions diffs - 0.18.0 → 0.20.0 - Mend

specweave 0.18.0 → 0.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (428) hide show

package/plugins/specweave-kafka/lib/documentation/exporter.ts ADDED Viewed

@@ -0,0 +1,338 @@
+/**
+ * Documentation Exporter
+ *
+ * Exports generated documentation to multiple formats (Markdown, HTML, PDF)
+ *
+ * @module exporter
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * Export Format
+ */
+export enum ExportFormat {
+  MARKDOWN = 'markdown',
+  HTML = 'html',
+  PDF = 'pdf',
+  JSON = 'json',
+}
+/**
+ * Export Options
+ */
+export interface ExportOptions {
+  /** Output directory */
+  outputDir: string;
+  /** File name (without extension) */
+  fileName: string;
+  /** Export format */
+  format: ExportFormat;
+  /** Include timestamp in filename */
+  includeTimestamp?: boolean;
+  /** Custom CSS for HTML/PDF (optional) */
+  customCSS?: string;
+}
+/**
+ * Documentation Exporter
+ *
+ * Handles exporting documentation to various formats
+ */
+export class DocumentationExporter {
+  /**
+   * Export documentation
+   */
+  static async export(content: string, options: ExportOptions): Promise<string> {
+    // Ensure output directory exists
+    if (!fs.existsSync(options.outputDir)) {
+      fs.mkdirSync(options.outputDir, { recursive: true });
+    }
+    // Build filename
+    const timestamp = options.includeTimestamp
+      ? `-${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 ExportFormat.MARKDOWN:
+        return this.exportMarkdown(content, filePath);
+      case ExportFormat.HTML:
+        return this.exportHTML(content, filePath, options.customCSS);
+      case ExportFormat.PDF:
+        return this.exportPDF(content, filePath, options.customCSS);
+      case ExportFormat.JSON:
+        return this.exportJSON(content, filePath);
+      default:
+        throw new Error(`Unsupported export format: ${options.format}`);
+    }
+  }
+  /**
+   * Get file extension for format
+   */
+  private static getExtension(format: ExportFormat): string {
+    switch (format) {
+      case ExportFormat.MARKDOWN:
+        return 'md';
+      case ExportFormat.HTML:
+        return 'html';
+      case ExportFormat.PDF:
+        return 'pdf';
+      case ExportFormat.JSON:
+        return 'json';
+      default:
+        return 'txt';
+    }
+  }
+  /**
+   * Export as Markdown
+   */
+  private static exportMarkdown(content: string, filePath: string): string {
+    fs.writeFileSync(filePath, content, 'utf-8');
+    return filePath;
+  }
+  /**
+   * Export as HTML
+   */
+  private static exportHTML(content: string, filePath: string, customCSS?: string): string {
+    // Convert Markdown to HTML (would use marked or similar in real implementation)
+    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
+   */
+  private static exportPDF(content: string, filePath: string, customCSS?: string): string {
+    // In real implementation, would use puppeteer or similar
+    // For now, just export as HTML and note that PDF generation requires additional setup
+    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
+   */
+  private static exportJSON(content: string, filePath: string): string {
+    // Assume content is already JSON string
+    fs.writeFileSync(filePath, content, 'utf-8');
+    return filePath;
+  }
+  /**
+   * Convert Markdown to HTML (simplified)
+   */
+  private static markdownToHTML(markdown: string): string {
+    // Simple Markdown to HTML conversion
+    // In production, use marked, markdown-it, or similar
+    let html = markdown;
+    // Headers
+    html = html.replace(/^### (.*$)/gim, '<h3>$1</h3>');
+    html = html.replace(/^## (.*$)/gim, '<h2>$1</h2>');
+    html = html.replace(/^# (.*$)/gim, '<h1>$1</h1>');
+    // Bold
+    html = html.replace(/\*\*(.*?)\*\*/g, '<strong>$1</strong>');
+    // Tables (basic)
+    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>`;
+    });
+    // Code blocks
+    html = html.replace(/```(.*?)\n([\s\S]*?)```/g, '<pre><code>$2</code></pre>');
+    // Paragraphs
+    html = html.replace(/\n\n/g, '</p><p>');
+    html = `<p>${html}</p>`;
+    return html;
+  }
+  /**
+   * Get default CSS for HTML export
+   */
+  private static getDefaultCSS(): string {
+    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: string,
+    baseOptions: Omit<ExportOptions, 'format'>
+  ): Promise<string[]> {
+    const formats = [ExportFormat.MARKDOWN, ExportFormat.HTML, ExportFormat.JSON];
+    const results: string[] = [];
+    for (const format of formats) {
+      const filePath = await this.export(content, {
+        ...baseOptions,
+        format,
+      });
+      results.push(filePath);
+    }
+    return results;
+  }
+}
+/**
+ * Example Usage: Export Topology Documentation
+ *
+ * ```typescript
+ * import { TopologyGenerator } from './topology-generator';
+ * import { DocumentationExporter, ExportFormat } from './exporter';
+ *
+ * // Generate topology markdown
+ * const topology = await TopologyGenerator.generate(admin);
+ * const markdown = TopologyGenerator.formatAsMarkdown(topology);
+ *
+ * // Export as HTML
+ * const htmlPath = await DocumentationExporter.export(markdown, {
+ *   outputDir: './docs/output',
+ *   fileName: 'kafka-topology',
+ *   format: ExportFormat.HTML,
+ *   includeTimestamp: true,
+ * });
+ *
+ * console.log(`Documentation exported to: ${htmlPath}`);
+ * ```
+ */
+/**
+ * Example Usage: Batch Export
+ *
+ * ```typescript
+ * // Export to all formats
+ * const paths = await DocumentationExporter.exportMultiple(markdown, {
+ *   outputDir: './docs/output',
+ *   fileName: 'kafka-topology',
+ *   includeTimestamp: false,
+ * });
+ *
+ * console.log('Exported files:', paths);
+ * // Output: ['./docs/output/kafka-topology.md', './docs/output/kafka-topology.html', './docs/output/kafka-topology.json']
+ * ```
+ */
+export default DocumentationExporter;

package/plugins/specweave-kafka/lib/documentation/schema-catalog-generator.js ADDED Viewed

@@ -0,0 +1,60 @@
+class SchemaCatalogGenerator {
+  /**
+   * Generate schema catalog from Schema Registry
+   */
+  static async generate(schemaRegistryUrl) {
+    const subjects = [];
+    return {
+      totalSubjects: subjects.length,
+      subjects,
+      generatedAt: /* @__PURE__ */ new Date()
+    };
+  }
+  /**
+   * Format catalog as Markdown
+   */
+  static formatAsMarkdown(catalog) {
+    const lines = [];
+    lines.push("# Schema Registry Catalog");
+    lines.push("");
+    lines.push(`**Total Subjects**: ${catalog.totalSubjects}`);
+    lines.push(`**Generated**: ${catalog.generatedAt.toISOString()}`);
+    lines.push("");
+    for (const subject of catalog.subjects) {
+      lines.push(`## ${subject.subject}`);
+      lines.push("");
+      lines.push(`**Latest Version**: ${subject.latestVersion}`);
+      lines.push(`**Compatibility Mode**: ${subject.compatibility}`);
+      lines.push("");
+      lines.push("### Versions");
+      lines.push("");
+      lines.push("| Version | Schema ID | Type |");
+      lines.push("|---------|-----------|------|");
+      for (const version of subject.versions) {
+        lines.push(`| ${version.version} | ${version.id} | ${version.schemaType} |`);
+      }
+      lines.push("");
+      const latestVersion = subject.versions[subject.versions.length - 1];
+      if (latestVersion) {
+        lines.push("### Latest Schema");
+        lines.push("");
+        lines.push("```json");
+        lines.push(latestVersion.schema);
+        lines.push("```");
+        lines.push("");
+      }
+    }
+    return lines.join("\n");
+  }
+  /**
+   * Format catalog as JSON
+   */
+  static formatAsJSON(catalog) {
+    return JSON.stringify(catalog, null, 2);
+  }
+}
+var schema_catalog_generator_default = SchemaCatalogGenerator;
+export {
+  SchemaCatalogGenerator,
+  schema_catalog_generator_default as default
+};

package/plugins/specweave-kafka/lib/documentation/schema-catalog-generator.ts ADDED Viewed

@@ -0,0 +1,130 @@
+/**
+ * Schema Catalog Generator
+ *
+ * Generates Schema Registry catalog documentation
+ *
+ * @module schema-catalog-generator
+ */
+/**
+ * Schema Version
+ */
+export interface SchemaVersion {
+  /** Schema ID */
+  id: number;
+  /** Version number */
+  version: number;
+  /** Schema definition (Avro/Protobuf/JSON) */
+  schema: string;
+  /** Schema type */
+  schemaType: 'AVRO' | 'PROTOBUF' | 'JSON';
+}
+/**
+ * Subject Metadata
+ */
+export interface SubjectMetadata {
+  /** Subject name */
+  subject: string;
+  /** Latest version */
+  latestVersion: number;
+  /** Compatibility mode */
+  compatibility: 'BACKWARD' | 'FORWARD' | 'FULL' | 'NONE';
+  /** All versions */
+  versions: SchemaVersion[];
+}
+/**
+ * Schema Catalog
+ */
+export interface SchemaCatalog {
+  /** Total subjects */
+  totalSubjects: number;
+  /** Subjects */
+  subjects: SubjectMetadata[];
+  /** Generated timestamp */
+  generatedAt: Date;
+}
+/**
+ * Schema Catalog Generator
+ *
+ * Generates documentation for Schema Registry
+ */
+export class SchemaCatalogGenerator {
+  /**
+   * Generate schema catalog from Schema Registry
+   */
+  static async generate(schemaRegistryUrl: string): Promise<SchemaCatalog> {
+    // In real implementation, would use @kafkajs/confluent-schema-registry
+    // For now, return mock data structure
+    const subjects: SubjectMetadata[] = [];
+    // Would fetch from Schema Registry REST API:
+    // GET /subjects
+    // GET /subjects/{subject}/versions
+    // GET /subjects/{subject}/versions/{version}
+    // GET /config/{subject}
+    return {
+      totalSubjects: subjects.length,
+      subjects,
+      generatedAt: new Date(),
+    };
+  }
+  /**
+   * Format catalog as Markdown
+   */
+  static formatAsMarkdown(catalog: SchemaCatalog): string {
+    const lines: string[] = [];
+    lines.push('# Schema Registry Catalog');
+    lines.push('');
+    lines.push(`**Total Subjects**: ${catalog.totalSubjects}`);
+    lines.push(`**Generated**: ${catalog.generatedAt.toISOString()}`);
+    lines.push('');
+    for (const subject of catalog.subjects) {
+      lines.push(`## ${subject.subject}`);
+      lines.push('');
+      lines.push(`**Latest Version**: ${subject.latestVersion}`);
+      lines.push(`**Compatibility Mode**: ${subject.compatibility}`);
+      lines.push('');
+      lines.push('### Versions');
+      lines.push('');
+      lines.push('| Version | Schema ID | Type |');
+      lines.push('|---------|-----------|------|');
+      for (const version of subject.versions) {
+        lines.push(`| ${version.version} | ${version.id} | ${version.schemaType} |`);
+      }
+      lines.push('');
+      // Latest schema definition
+      const latestVersion = subject.versions[subject.versions.length - 1];
+      if (latestVersion) {
+        lines.push('### Latest Schema');
+        lines.push('');
+        lines.push('```json');
+        lines.push(latestVersion.schema);
+        lines.push('```');
+        lines.push('');
+      }
+    }
+    return lines.join('\n');
+  }
+  /**
+   * Format catalog as JSON
+   */
+  static formatAsJSON(catalog: SchemaCatalog): string {
+    return JSON.stringify(catalog, null, 2);
+  }
+}
+export default SchemaCatalogGenerator;

package/plugins/specweave-kafka/lib/documentation/topology-generator.js ADDED Viewed

@@ -0,0 +1,143 @@
+class TopologyGenerator {
+  /**
+   * Generate cluster topology documentation
+   */
+  static async generate(admin) {
+    const cluster = await admin.describeCluster();
+    const allTopics = await admin.listTopics();
+    const topicMetadata = await admin.fetchTopicMetadata({ topics: allTopics });
+    const topicConfigs = await admin.fetchTopicOffsets(allTopics.slice(0, 10));
+    const topics = [];
+    let totalPartitions = 0;
+    const underReplicatedPartitions = [];
+    for (const topicData of topicMetadata.topics) {
+      const partitionCount = topicData.partitions.length;
+      totalPartitions += partitionCount;
+      const replicationFactor = topicData.partitions.length > 0 ? topicData.partitions[0].replicas.length : 0;
+      topics.push({
+        name: topicData.name,
+        partitions: partitionCount,
+        replicationFactor,
+        configs: {},
+        // Would fetch from describeConfigs in real implementation
+        isInternal: topicData.name.startsWith("__") || topicData.name.startsWith("_")
+      });
+      for (const partition of topicData.partitions) {
+        if (partition.isr.length < partition.replicas.length) {
+          underReplicatedPartitions.push({
+            topic: topicData.name,
+            partition: partition.partitionId,
+            leader: partition.leader,
+            isr: partition.isr.map(Number),
+            replicas: partition.replicas.map(Number)
+          });
+        }
+      }
+    }
+    const topology = {
+      clusterId: cluster.clusterId,
+      controller: Number(cluster.controller),
+      brokers: cluster.brokers.map((broker) => ({
+        nodeId: broker.nodeId,
+        host: broker.host,
+        port: broker.port,
+        rack: broker.rack
+      })),
+      topics,
+      totalPartitions,
+      underReplicatedPartitions,
+      generatedAt: /* @__PURE__ */ new Date()
+    };
+    return topology;
+  }
+  /**
+   * Format topology as Markdown
+   */
+  static formatAsMarkdown(topology) {
+    const lines = [];
+    lines.push("# Kafka Cluster Topology");
+    lines.push("");
+    lines.push(`**Cluster ID**: ${topology.clusterId}`);
+    lines.push(`**Controller**: Broker ${topology.controller}`);
+    lines.push(`**Generated**: ${topology.generatedAt.toISOString()}`);
+    lines.push("");
+    lines.push("## Brokers");
+    lines.push("");
+    lines.push("| Broker ID | Host | Port | Rack |");
+    lines.push("|-----------|------|------|------|");
+    for (const broker of topology.brokers) {
+      lines.push(
+        `| ${broker.nodeId} | ${broker.host} | ${broker.port} | ${broker.rack || "N/A"} |`
+      );
+    }
+    lines.push("");
+    lines.push("## Topics");
+    lines.push("");
+    lines.push(`**Total Topics**: ${topology.topics.length}`);
+    lines.push(`**Total Partitions**: ${topology.totalPartitions}`);
+    lines.push("");
+    lines.push("### Topic List");
+    lines.push("");
+    lines.push("| Topic Name | Partitions | Replication Factor | Internal |");
+    lines.push("|------------|------------|-------------------|----------|");
+    const sortedTopics = [...topology.topics].sort((a, b) => a.name.localeCompare(b.name));
+    for (const topic of sortedTopics) {
+      lines.push(
+        `| ${topic.name} | ${topic.partitions} | ${topic.replicationFactor} | ${topic.isInternal ? "Yes" : "No"} |`
+      );
+    }
+    lines.push("");
+    if (topology.underReplicatedPartitions.length > 0) {
+      lines.push("## \u26A0\uFE0F  Under-Replicated Partitions");
+      lines.push("");
+      lines.push("| Topic | Partition | Leader | ISR | Replicas |");
+      lines.push("|-------|-----------|--------|-----|----------|");
+      for (const partition of topology.underReplicatedPartitions) {
+        lines.push(
+          `| ${partition.topic} | ${partition.partition} | ${partition.leader} | ${partition.isr.join(", ")} | ${partition.replicas.join(", ")} |`
+        );
+      }
+      lines.push("");
+    }
+    return lines.join("\n");
+  }
+  /**
+   * Format topology as JSON
+   */
+  static formatAsJSON(topology) {
+    return JSON.stringify(topology, null, 2);
+  }
+  /**
+   * Generate Mermaid diagram for cluster topology
+   */
+  static generateMermaidDiagram(topology) {
+    const lines = [];
+    lines.push("```mermaid");
+    lines.push("graph TB");
+    lines.push("    subgraph Kafka Cluster");
+    for (const broker of topology.brokers) {
+      const isController = broker.nodeId === topology.controller;
+      const shape = isController ? "[Broker " : "(Broker ";
+      const endShape = isController ? "]" : ")";
+      lines.push(
+        `        B${broker.nodeId}${shape}${broker.nodeId}<br/>${broker.host}:${broker.port}${endShape}`
+      );
+    }
+    const sampleTopics = topology.topics.filter((t) => !t.isInternal).slice(0, 10);
+    for (const topic of sampleTopics) {
+      const topicId = topic.name.replace(/[^a-zA-Z0-9]/g, "_");
+      lines.push(`        T_${topicId}[${topic.name}<br/>${topic.partitions} partitions]`);
+      for (const broker of topology.brokers.slice(0, 3)) {
+        lines.push(`        T_${topicId} --> B${broker.nodeId}`);
+      }
+    }
+    lines.push("    end");
+    lines.push("```");
+    return lines.join("\n");
+  }
+}
+var topology_generator_default = TopologyGenerator;
+export {
+  TopologyGenerator,
+  topology_generator_default as default
+};