@redpanda-data/docs-extensions-and-macros 4.13.1 → 4.13.3

package/tools/add-commercial-names.js

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const glob = require('glob');
+
+// Commercial name mappings based on connector patterns
+const commercialNameMappings = {
+  // AWS services
+  'aws_s3': 'Amazon S3, AWS S3, S3, Simple Storage Service',
+  'aws_kinesis': 'Amazon Kinesis, AWS Kinesis, Kinesis',
+  'aws_sqs': 'Amazon SQS, AWS SQS, SQS, Simple Queue Service',
+  'aws_sns': 'Amazon SNS, AWS SNS, SNS, Simple Notification Service',
+  'aws_dynamodb': 'Amazon DynamoDB, AWS DynamoDB, DynamoDB',
+  'aws_kinesis_firehose': 'Amazon Kinesis Firehose, AWS Kinesis Firehose, Kinesis Firehose',
+  'aws_lambda': 'Amazon Lambda, AWS Lambda, Lambda',
+  'aws_cloudwatch': 'Amazon CloudWatch, AWS CloudWatch, CloudWatch',
+
+  // Message queues
+  'amqp_0_9': 'RabbitMQ, AMQP',
+  'amqp_1': 'RabbitMQ, AMQP, Apache Qpid',
+  'kafka': 'Apache Kafka, Kafka',
+  'kafka_franz': 'Apache Kafka, Kafka',
+  'nats': 'NATS, NATS.io',
+  'nats_jetstream': 'NATS JetStream, NATS',
+  'nats_stream': 'NATS Streaming, NATS',
+  'pulsar': 'Apache Pulsar, Pulsar',
+  'redis_pubsub': 'Redis Pub/Sub, Redis',
+  'redis_streams': 'Redis Streams, Redis',
+  'redis_list': 'Redis Lists, Redis',
+
+  // Databases - general patterns
+  'mongodb': 'MongoDB, Mongo',
+  'cassandra': 'Apache Cassandra, Cassandra',
+  'elasticsearch': 'Elasticsearch, Elastic',
+  'influxdb': 'InfluxDB, Influx',
+  'redis_hash': 'Redis, Redis Hash',
+
+  // HTTP/API
+  'http_client': 'HTTP, REST API, REST',
+  'http_server': 'HTTP, REST API, REST, Gateway',
+  'webhook': 'Webhook, HTTP',
+
+  // File formats
+  'unarchive': 'ZIP, TAR, GZIP, Archive, JSON, CSV',
+  'archive': 'ZIP, TAR, GZIP, Archive',
+  'lines': 'Text Files, Plain Text, Log Files',
+  'csv': 'CSV, Comma-Separated Values',
+
+  // Cloud providers (generic patterns will catch aws_*, gcp_*, azure_*)
+  'gcp_pubsub': 'Google Cloud Pub/Sub, GCP Pub/Sub, Google Pub/Sub',
+  'gcp_bigquery': 'Google BigQuery, GCP BigQuery, BigQuery',
+  'gcp_cloud_storage': 'Google Cloud Storage, GCS, GCP Cloud Storage',
+  'azure_blob_storage': 'Azure Blob Storage, Microsoft Azure Storage',
+  'azure_queue_storage': 'Azure Queue Storage, Microsoft Azure Queue',
+  'azure_table_storage': 'Azure Table Storage, Microsoft Azure Table',
+};
+
+// Pattern-based commercial names (for connectors not in explicit mapping)
+function getCommercialNamesFromPattern(connectorName) {
+  const names = [];
+
+  // AWS pattern
+  if (connectorName.startsWith('aws_')) {
+    names.push('Amazon');
+    names.push('AWS');
+    const serviceName = connectorName.replace('aws_', '').replace(/_/g, ' ');
+    names.push(serviceName.split(' ').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' '));
+  }
+
+  // GCP pattern
+  if (connectorName.startsWith('gcp_')) {
+    names.push('Google Cloud');
+    names.push('GCP');
+  }
+
+  // Azure pattern
+  if (connectorName.startsWith('azure_')) {
+    names.push('Microsoft Azure');
+    names.push('Azure');
+  }
+
+  // SQL databases
+  if (connectorName.startsWith('sql_')) {
+    names.push('SQL');
+    names.push('PostgreSQL');
+    names.push('MySQL');
+    names.push('Microsoft SQL Server');
+    names.push('ClickHouse');
+    names.push('Trino');
+  }
+
+  return names;
+}
+
+function getCommercialNames(connectorName) {
+  // Check explicit mapping first
+  if (commercialNameMappings[connectorName]) {
+    return commercialNameMappings[connectorName];
+  }
+
+  // Try pattern matching
+  const patternNames = getCommercialNamesFromPattern(connectorName);
+  if (patternNames.length > 0) {
+    return patternNames.join(', ');
+  }
+
+  return null;
+}
+
+function addCommercialNamesToFile(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  let lines = content.split('\n');
+
+  // Extract connector name from file path
+  const connectorName = path.basename(filePath, '.adoc');
+
+  // Remove existing page-commercial-names if present (we'll re-add in correct location)
+  lines = lines.filter(line => !line.includes(':page-commercial-names:'));
+
+  // Get commercial names
+  const commercialNames = getCommercialNames(connectorName);
+  if (!commercialNames) {
+    return { status: 'skip', reason: 'no commercial names found' };
+  }
+
+  // Find the position to insert (after single-source tag if present, otherwise after title)
+  let insertIndex = -1;
+  let titleIndex = -1;
+
+  // First find the title
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].startsWith('= ')) {
+      titleIndex = i;
+      break;
+    }
+  }
+
+  if (titleIndex === -1) {
+    return { status: 'error', reason: 'could not find title' };
+  }
+
+  // Look for single-source tag after the title (with or without space after //)
+  let foundSingleSource = false;
+  for (let i = titleIndex + 1; i < Math.min(titleIndex + 10, lines.length); i++) {
+    if (lines[i].includes('tag::single-source[]')) {
+      insertIndex = i + 1;
+      foundSingleSource = true;
+      break;
+    }
+  }
+
+  // If no single-source tag, insert after title
+  if (!foundSingleSource) {
+    insertIndex = titleIndex + 1;
+    // Skip any existing page attributes
+    while (insertIndex < lines.length && lines[insertIndex].startsWith(':')) {
+      insertIndex++;
+    }
+  }
+
+  if (insertIndex === -1) {
+    return { status: 'error', reason: 'could not find title' };
+  }
+
+  // Insert the attribute
+  lines.splice(insertIndex, 0, `:page-commercial-names: ${commercialNames}`);
+
+  // Write back
+  fs.writeFileSync(filePath, lines.join('\n'), 'utf8');
+
+  return { status: 'added', commercialNames };
+}
+
+// Main execution
+const basePath = process.argv[2] || '/Users/jakecahill/Documents/rp-connect-docs';
+const pattern = `${basePath}/modules/components/pages/{inputs,outputs,processors}/*.adoc`;
+
+console.log(`Finding connector files in: ${pattern}`);
+const files = glob.sync(pattern).filter(f => !f.endsWith('about.adoc'));
+
+console.log(`Found ${files.length} connector files\n`);
+
+let added = 0;
+let skipped = 0;
+let errors = 0;
+
+files.forEach(file => {
+  const connectorName = path.basename(file, '.adoc');
+  const result = addCommercialNamesToFile(file);
+
+  if (result.status === 'added') {
+    console.log(`✅ ${connectorName}: ${result.commercialNames}`);
+    added++;
+  } else if (result.status === 'skip') {
+    skipped++;
+  } else if (result.status === 'error') {
+    console.error(`❌ ${connectorName}: ${result.reason}`);
+    errors++;
+  }
+});
+
+console.log(`\n📊 Summary:`);
+console.log(`  ✅ Added: ${added}`);
+console.log(`  ⏭️  Skipped: ${skipped}`);
+console.log(`  ❌ Errors: ${errors}`);
+console.log(`  📝 Total: ${files.length}`);

package/tools/bundle-openapi.js

@@ -551,7 +551,7 @@ function postProcessBundle(filePath, options, quiet = false) {
 }
 
 /**
- * Bundle OpenAPI fragments for the specified API surface(s) from a repository tag and write the resulting bundled YAML files to disk.
+ * Bundle OpenAPI fragments for the specified API surfaces from a repository tag and write the resulting bundled YAML files to disk.
  *
  * @param {Object} options - Configuration options.
  * @param {string} options.tag - Git tag to checkout (for example, 'v25.1.1').

package/tools/generate-cli-docs.js

@@ -274,7 +274,10 @@ IMPORTANT: This documentation is auto-generated. Do not edit manually. Run \`npm
     'get-console-version',
     'link-readme',
     'fetch',
-    'setup-mcp'
+    'setup-mcp',
+    'validate-mcp',
+    'preview-prompt',
+    'mcp-version'
   ];
 
   topLevelCommands.forEach(cmd => {
@@ -300,7 +303,8 @@ IMPORTANT: This documentation is auto-generated. Do not edit manually. Run \`npm
     'helm-spec',
     'cloud-regions',
     'crd-spec',
-    'bundle-openapi'
+    'bundle-openapi',
+    'update-connect-version'
   ];
 
   generateSubcommands.forEach(subcmd => {

package/tools/get-console-version.js

@@ -50,6 +50,11 @@ module.exports = async function getConsoleVersion({ beta = false, fromAntora = f
     ? (data.latestBetaRelease || data.latestStableRelease)
     : data.latestStableRelease;
 
+  if (!version) {
+    console.error('Could not determine Console version');
+    process.exit(1);
+  }
+
   console.log(`CONSOLE_VERSION=${version}`);
   console.log(`CONSOLE_DOCKER_REPO=${CONSOLE_DOCKER_REPO}`);
 };

package/tools/get-redpanda-version.js

@@ -46,6 +46,11 @@ module.exports = async function getRedpandaVersion({ beta = false, fromAntora =
   const rc = data.latestRcRelease;
   const version = useBeta && rc ? rc.version : stableVersion;
 
+  if (!version) {
+    console.error('Could not determine Redpanda version');
+    process.exit(1);
+  }
+
   // Determine the Docker repository
   const dockerRepo = (useBeta && rc) ? 'redpanda-unstable' : 'redpanda';
 

package/tools/property-extractor/compare-properties.js

@@ -296,7 +296,7 @@ function generateConsoleReport(report, oldVersion, newVersion) {
   }
 
   if (report.emptyDescriptions.length > 0) {
-    console.log(`\n⚠️  Properties with empty descriptions (${report.emptyDescriptions.length}):`);
+    console.log(`\nWarning: Properties with empty descriptions (${report.emptyDescriptions.length}):`);
     report.emptyDescriptions.forEach(prop => {
       console.log(`   • ${prop.name} (${prop.type})`);
     });
@@ -362,7 +362,7 @@ function generateJsonReport(report, oldVersion, newVersion, outputPath) {
  */
 function comparePropertyFiles(oldFilePath, newFilePath, oldVersion, newVersion, outputDir, filename = 'property-changes.json') {
   try {
-    console.log(`📊 Comparing property files:`);
+    console.log(`Comparing property files:`);
     console.log(`   Old: ${oldFilePath}`);
     console.log(`   New: ${newFilePath}`);
     
@@ -383,7 +383,7 @@ function comparePropertyFiles(oldFilePath, newFilePath, oldVersion, newVersion,
     
     return report;
   } catch (error) {
-    console.error(`❌ Error comparing properties: ${error.message}`);
+    console.error(`Error: Error comparing properties: ${error.message}`);
     process.exit(1);
   }
 }

package/tools/property-extractor/generate-handlebars-docs.js

@@ -25,7 +25,7 @@ const helpers = require('./helpers');
 // Register helpers
 Object.entries(helpers).forEach(([name, fn]) => {
   if (typeof fn !== 'function') {
-    console.error(`❌ Helper "${name}" is not a function`);
+    console.error(`Error: Helper "${name}" is not a function`);
     process.exit(1);
   }
   handlebars.registerHelper(name, fn);
@@ -96,9 +96,9 @@ function registerPartials() {
     }
     handlebars.registerPartial('deprecated-property', fs.readFileSync(deprecatedPropertyTemplatePath, 'utf8'));
 
-    console.log('✅ Registered all partials');
+    console.log('Done: Registered all partials');
   } catch (error) {
-    console.error('❌ Failed to register Handlebars templates:');
+    console.error('Error: Failed to register Handlebars templates:');
     console.error(`   ${error.message}`);
     throw error;
   }
@@ -140,7 +140,7 @@ function generatePropertyPartials(properties, partialsDir, onRender) {
 
     // Skip if we've already processed this key
     if (processedKeys.has(key)) {
-      console.warn(`⚠️ Duplicate key detected: ${key}`);
+      console.warn(`Warning: Duplicate key detected: ${key}`);
       return;
     }
     processedKeys.add(key);
@@ -164,7 +164,7 @@ function generatePropertyPartials(properties, partialsDir, onRender) {
         propertyGroups['object-storage'].push(prop);
         break;
       default:
-        console.warn(`⚠️ Unknown config_scope: ${prop.config_scope} for ${prop.name}`);
+        console.warn(`Warning: Unknown config_scope: ${prop.config_scope} for ${prop.name}`);
         break;
     }
   });
@@ -185,11 +185,11 @@ function generatePropertyPartials(properties, partialsDir, onRender) {
     const content = pieces.join('\n');
     const filename = `${type}-properties.adoc`;
     fs.writeFileSync(path.join(propertiesPartialsDir, filename), AUTOGEN_NOTICE + content, 'utf8');
-    console.log(`✅ Generated ${filename} (${props.length} properties)`);
+    console.log(`Done: Generated ${filename} (${props.length} properties)`);
     totalCount += props.length;
   });
 
-  console.log(`✅ Done. ${totalCount} total properties.`);
+  console.log(`Done: Done. ${totalCount} total properties.`);
   return totalCount;
 }
 
@@ -223,7 +223,7 @@ function generateDeprecatedDocs(properties, outputDir) {
 
   fs.mkdirSync(path.dirname(outputPath), { recursive: true });
   fs.writeFileSync(outputPath, AUTOGEN_NOTICE + template(data), 'utf8');
-  console.log(`✅ Generated ${outputPath}`);
+  console.log(`Done: Generated ${outputPath}`);
   return deprecatedProperties.length;
 }
 
@@ -253,7 +253,7 @@ function generateTopicPropertyMappings(properties, partialsDir) {
   fs.mkdirSync(propertiesPartialsDir, { recursive: true });
   const mappingsOut = path.join(propertiesPartialsDir, 'topic-property-mappings.adoc');
   fs.writeFileSync(mappingsOut, AUTOGEN_NOTICE + rendered, 'utf8');
-  console.log(`✅ Generated ${mappingsOut}`);
+  console.log(`Done: Generated ${mappingsOut}`);
   return topicProperties.length;
 }
 
@@ -324,7 +324,7 @@ function generateAllDocs(inputFile, outputDir) {
     try {
       generateTopicPropertyMappings(properties, process.env.OUTPUT_PARTIALS_DIR);
     } catch (err) {
-      console.error(`❌ Failed to generate topic-property-mappings.adoc: ${err.message}`);
+      console.error(`Error: Failed to generate topic-property-mappings.adoc: ${err.message}`);
     }
   } else {
     console.log('📄 Skipping partial generation (set GENERATE_PARTIALS=1 and OUTPUT_PARTIALS_DIR to enable)');
@@ -338,7 +338,7 @@ function generateAllDocs(inputFile, outputDir) {
     ? ((partialsCount / totalProperties) * 100).toFixed(2)
     : '0.00';
 
-  console.log('\n📊 Summary:');
+  console.log('\nSummary:');
   console.log(`   Total properties found:      ${totalProperties}`);
   console.log(`   Property partials generated: ${partialsCount} (${pctRendered}% of total)`);
   console.log(`   Not documented:              ${notRendered}`);
@@ -374,15 +374,15 @@ if (require.main === module) {
 
   const [inputFile, outputDir] = args;
   if (!fs.existsSync(inputFile)) {
-    console.error(`❌ Input file not found: ${inputFile}`);
+    console.error(`Error: Input file not found: ${inputFile}`);
     process.exit(1);
   }
 
   try {
     generateAllDocs(inputFile, outputDir);
-    console.log('✅ Documentation generation completed successfully');
+    console.log('Done: Documentation generation completed successfully');
   } catch (err) {
-    console.error(`❌ Error: ${err.message}`);
+    console.error(`Error: ${err.message}`);
     process.exit(1);
   }
 }

package/tools/property-extractor/generate-pr-summary.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+/**
+ * Standalone CLI tool to generate PR summaries from property diff JSON files
+ *
+ * Usage:
+ *   node generate-pr-summary.js <diff-json-file>
+ *
+ * Example:
+ *   node generate-pr-summary.js ../../docs-data/redpanda-property-changes-v25.3.1-to-v25.3.3.json
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { printPRSummary } = require('./pr-summary-formatter');
+
+// CLI usage
+if (require.main === module) {
+  const args = process.argv.slice(2);
+
+  if (args.length < 1) {
+    console.error('Usage: node generate-pr-summary.js <diff-json-file>');
+    console.error('');
+    console.error('Example:');
+    console.error('  node generate-pr-summary.js redpanda-property-changes-v25.3.1-to-v25.3.3.json');
+    console.error('');
+    console.error('This tool reads a property diff JSON file (generated by compare-properties.js)');
+    console.error('and outputs a GitHub PR-ready markdown summary.');
+    process.exit(1);
+  }
+
+  const diffFilePath = path.resolve(args[0]);
+
+  if (!fs.existsSync(diffFilePath)) {
+    console.error(`Error: File not found: ${diffFilePath}`);
+    process.exit(1);
+  }
+
+  try {
+    const diffData = JSON.parse(fs.readFileSync(diffFilePath, 'utf8'));
+    printPRSummary(diffData);
+  } catch (error) {
+    console.error(`Error: Error reading diff file: ${error.message}`);
+    process.exit(1);
+  }
+}