@redpanda-data/docs-extensions-and-macros 4.11.1 → 4.12.1

package/tools/redpanda-connect/helpers/renderConnectFields.js

@@ -138,7 +138,39 @@ module.exports = function renderConnectFields(children, prefix = '') {
     if (child.examples && child.examples.length) {
       block += `[source,yaml]\n----\n# Examples:\n`;
       if (child.kind === 'array') {
-        block += renderYamlList(child.name, child.examples);
+        // Render arrays in flow style (with brackets) instead of block style
+        child.examples.forEach(example => {
+          if (Array.isArray(example)) {
+            // Format as flow style: fieldName: [item1, item2, ...]
+            const items = example.map(item => {
+              if (typeof item === 'string') {
+                // Check if quoting is needed
+                const needsQuoting = item === '*' ||
+                                     /[:\[\]\{\},&>|%@`"]/.test(item) ||
+                                     /^[\s]|[\s]$/.test(item); // leading/trailing whitespace
+
+                if (needsQuoting) {
+                  // Escape backslashes first, then double quotes
+                  const escaped = item.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+                  return `"${escaped}"`;
+                }
+                return item;
+              }
+              // For non-strings, convert to string
+              const strValue = String(item);
+              // Check if the stringified value needs quoting
+              if (/[:\[\]\{\},&>|%@`"]/.test(strValue) || /^[\s]|[\s]$/.test(strValue)) {
+                const escaped = strValue.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+                return `"${escaped}"`;
+              }
+              return strValue;
+            });
+            block += `${child.name}: [${items.join(', ')}]\n`;
+          } else {
+            // Fallback for non-array examples (shouldn't happen for array fields)
+            block += `${child.name}: ${example}\n`;
+          }
+        });
       } else {
         child.examples.forEach(example => {
           if (typeof example === 'object') {

package/tools/redpanda-connect/report-delta.js

@@ -1,3 +1,5 @@
+const { execSync } = require('child_process');
+
 /**
  * Generate a JSON diff report between two connector index objects.
  * @param {object} oldIndex - Previous version connector index
@@ -78,6 +80,66 @@ function generateConnectorDiffJson(oldIndex, newIndex, opts = {}) {
     });
   });
 
+  // Newly deprecated components (exist in both versions but became deprecated)
+  const deprecatedComponents = [];
+  Object.keys(newMap).forEach(cKey => {
+    if (!(cKey in oldMap)) return;
+    const oldStatus = (oldMap[cKey].raw.status || '').toLowerCase();
+    const newStatus = (newMap[cKey].raw.status || '').toLowerCase();
+    if (oldStatus !== 'deprecated' && newStatus === 'deprecated') {
+      const [type, name] = cKey.split(':');
+      const raw = newMap[cKey].raw;
+      deprecatedComponents.push({
+        name,
+        type,
+        status: raw.status || raw.type || '',
+        version: raw.version || raw.introducedInVersion || '',
+        description: raw.description || ''
+      });
+    }
+  });
+
+  // Newly deprecated fields (exist in both versions but became deprecated)
+  const deprecatedFields = [];
+  Object.keys(newMap).forEach(cKey => {
+    if (!(cKey in oldMap)) return;
+    const oldFieldsArr = oldMap[cKey].fields || [];
+    const newFieldsArr = newMap[cKey].fields || [];
+
+    // Check fields that exist in both versions
+    const commonFields = oldFieldsArr.filter(f => newFieldsArr.includes(f));
+    commonFields.forEach(fName => {
+      const [type, compName] = cKey.split(':');
+
+      // Get old field object
+      let oldFieldObj = null;
+      if (type === 'config') {
+        oldFieldObj = (oldMap[cKey].raw.children || []).find(f => f.name === fName);
+      } else {
+        oldFieldObj = (oldMap[cKey].raw.config?.children || []).find(f => f.name === fName);
+      }
+
+      // Get new field object
+      let newFieldObj = null;
+      if (type === 'config') {
+        newFieldObj = (newMap[cKey].raw.children || []).find(f => f.name === fName);
+      } else {
+        newFieldObj = (newMap[cKey].raw.config?.children || []).find(f => f.name === fName);
+      }
+
+      const oldDeprecated = oldFieldObj && (oldFieldObj.is_deprecated === true || oldFieldObj.deprecated === true || (oldFieldObj.status || '').toLowerCase() === 'deprecated');
+      const newDeprecated = newFieldObj && (newFieldObj.is_deprecated === true || newFieldObj.deprecated === true || (newFieldObj.status || '').toLowerCase() === 'deprecated');
+
+      if (!oldDeprecated && newDeprecated) {
+        deprecatedFields.push({
+          component: cKey,
+          field: fName,
+          description: newFieldObj && newFieldObj.description
+        });
+      }
+    });
+  });
+
   return {
     comparison: {
       oldVersion: opts.oldVersion || '',
@@ -88,23 +150,20 @@ function generateConnectorDiffJson(oldIndex, newIndex, opts = {}) {
       newComponents: newComponents.length,
       removedComponents: removedComponents.length,
       newFields: newFields.length,
-      removedFields: removedFields.length
+      removedFields: removedFields.length,
+      deprecatedComponents: deprecatedComponents.length,
+      deprecatedFields: deprecatedFields.length
     },
     details: {
       newComponents,
       removedComponents,
       newFields,
-      removedFields
+      removedFields,
+      deprecatedComponents,
+      deprecatedFields
     }
   };
 }
-// tools/redpanda-connect/report-delta.js
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const yaml = require('yaml');
-const { execSync } = require('child_process');
 
 function discoverComponentKeys(obj) {
   return Object.keys(obj).filter(key => Array.isArray(obj[key]));
@@ -209,6 +268,47 @@ function printDeltaReport(oldIndex, newIndex) {
     });
   });
 
+  // Newly deprecated components
+  const deprecatedComponentKeys = [];
+  Object.keys(newMap).forEach(cKey => {
+    if (!(cKey in oldMap)) return;
+    const oldStatus = (oldMap[cKey].raw.status || '').toLowerCase();
+    const newStatus = (newMap[cKey].raw.status || '').toLowerCase();
+    if (oldStatus !== 'deprecated' && newStatus === 'deprecated') {
+      deprecatedComponentKeys.push(cKey);
+    }
+  });
+
+  // Newly deprecated fields
+  const deprecatedFieldsList = [];
+  Object.keys(newMap).forEach(cKey => {
+    if (!(cKey in oldMap)) return;
+    const oldFieldsArr = oldMap[cKey].fields || [];
+    const newFieldsArr = newMap[cKey].fields || [];
+    const commonFields = oldFieldsArr.filter(f => newFieldsArr.includes(f));
+
+    commonFields.forEach(fName => {
+      const [type, compName] = cKey.split(':');
+      let oldFieldObj = null;
+      if (type === 'config') {
+        oldFieldObj = (oldMap[cKey].raw.children || []).find(f => f.name === fName);
+      } else {
+        oldFieldObj = (oldMap[cKey].raw.config?.children || []).find(f => f.name === fName);
+      }
+      let newFieldObj = null;
+      if (type === 'config') {
+        newFieldObj = (newMap[cKey].raw.children || []).find(f => f.name === fName);
+      } else {
+        newFieldObj = (newMap[cKey].raw.config?.children || []).find(f => f.name === fName);
+      }
+      const oldDeprecated = oldFieldObj && (oldFieldObj.is_deprecated === true || oldFieldObj.deprecated === true || (oldFieldObj.status || '').toLowerCase() === 'deprecated');
+      const newDeprecated = newFieldObj && (newFieldObj.is_deprecated === true || newFieldObj.deprecated === true || (newFieldObj.status || '').toLowerCase() === 'deprecated');
+      if (!oldDeprecated && newDeprecated) {
+        deprecatedFieldsList.push({ component: cKey, field: fName });
+      }
+    });
+  });
+
   console.log('\n📋 RPCN Connector Delta Report\n');
 
   if (newComponentKeys.length) {
@@ -242,6 +342,29 @@ function printDeltaReport(oldIndex, newIndex) {
   } else {
     console.log('➤ No newly added fields.\n');
   }
+
+  if (deprecatedComponentKeys.length) {
+    console.log('➤ Newly deprecated components:');
+    deprecatedComponentKeys.forEach(key => {
+      const [type, name] = key.split(':');
+      const raw = newMap[key].raw;
+      console.log(`   • ${type}/${name}`);
+    });
+    console.log('');
+  } else {
+    console.log('➤ No newly deprecated components.\n');
+  }
+
+  if (deprecatedFieldsList.length) {
+    console.log('➤ Newly deprecated fields:');
+    deprecatedFieldsList.forEach(entry => {
+      const { component, field } = entry;
+      console.log(`   • ${component} → ${field}`);
+    });
+    console.log('');
+  } else {
+    console.log('➤ No newly deprecated fields.\n');
+  }
 }
 
 module.exports = {

package/tools/property-extractor/definitions.json

@@ -1,245 +0,0 @@
-{
-    "client_group_quota": {
-        "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/config/client_group_byte_rate_quota.h#L29",
-        "type": "object",
-        "properties": {
-            "group_name": {
-                "type": "string"
-            },
-            "clients_prefix": {
-                "type": "string"
-            },
-            "quota": {
-                "type": "integer",
-                "minimum": -9223372036854775808,
-                "maximum": 9223372036854775807
-            }
-        }
-    },
-    "config::broker_authn_endpoint": {
-        "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/config/broker_authn_endpoint.h#L42",
-        "type": "object",
-        "properties": {
-            "name": {
-                "type": "string"
-            },
-            "address": {
-                "type": "string"
-            },
-            "port": {
-                "type": "integer",
-                "minimum": 0,
-                "maximum": 4294967295
-            }
-        }
-    },
-    "config::endpoint_tls_config": {
-        "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/config/endpoint_tls_config.h#L21",
-        "type": "object",
-        "properties": {
-            "name": {
-                "type": "string"
-            },
-            "config": {
-                "$ref": "#/definitions/config::tls_config"
-            }
-        }
-    },
-    "config::tls_config": {
-        "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/config/tls_config.h#L49",
-        "type": "object",
-        "properties": {
-            "enabled": {
-                "type": "boolean"
-            },
-            "require_client_auth": {
-                "type": "boolean"
-            },
-            "key_file": {
-                "type": "string"
-            },
-            "cert_file": {
-                "type": "string"
-            },
-            "truststore_file": {
-                "type": "string"
-            }
-        }
-    },
-    "tls_config": {
-        "$ref": "#/definitions/config::tls_config"
-    },
-    "config::rest_authn_endpoint": {
-        "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/config/rest_authn_endpoint.h#L42",
-        "type": "object",
-        "properties": {
-            "name": {
-                "type": "string"
-            },
-            "address": {
-                "type": "string"
-            },
-            "port": {
-                "type": "integer",
-                "minimum": 0,
-                "maximum": 4294967295
-            },
-            "authentication_method": {
-                "$ref": "#/definitions/config::rest_authn_method"
-            }
-        }
-    },
-    "config::rest_authn_method": {
-        "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/config/rest_authn_endpoint.h#L31",
-        "enum": [
-            "none",
-            "http_basic"
-        ]
-    },
-    "endpoint_tls_config": {
-        "$ref": "#/definitions/config::endpoint_tls_config"
-    },
-    "model::broker_endpoint": {
-        "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/model/metadata.h#L88",
-        "type": "object",
-        "properties": {
-            "name": {
-                "type": "string"
-            },
-            "address": {
-                "type": "string"
-            },
-            "port": {
-                "type": "integer",
-                "minimum": 0,
-                "maximum": 4294967295
-            }
-        }
-    },
-    "model::cleanup_policy_bitflags": {
-        "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/model/fundamental.h#L72",
-        "enum": [
-            "none",
-            "delete",
-            "compact"
-        ]
-    },
-    "model::cloud_credentials_source": {
-        "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/model/metadata.h#L454",
-        "enum": [
-            "config_file",
-            "aws_instance_metadata",
-            "sts",
-            "gcp_instance_metadata"
-        ]
-    },
-    "model::cloud_storage_backend": {
-        "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/model/metadata.h#L481",
-        "enum": [
-            "aws",
-            "google_s3_compat",
-            "azure",
-            "minio",
-            "unknown"
-        ]
-    },
-    "model::cloud_storage_chunk_eviction_strategy": {
-        "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/model/metadata.h#L524",
-        "enum": [
-            "eager",
-            "capped",
-            "predictive"
-        ]
-    },
-    "model::compression": {
-        "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/model/compression.h#L36",
-        "enum": [
-            "none",
-            "gzip",
-            "snappy",
-            "lz4",
-            "zstd",
-            "producer"
-        ]
-    },
-    "model::leader_balancer_mode": {
-        "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/model/metadata.h#L504",
-        "enum": [
-            "greedy_balanced_shards",
-            "random_hill_climbing"
-        ]
-    },
-    "model::node_id": {
-        "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/model/metadata.h#L36",
-        "type": "integer",
-        "minimum": -2147483648,
-        "maximum": 2147483647
-    },
-    "model::partition_autobalancing_mode": {
-        "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/model/metadata.h#L463",
-        "enum": [
-            "off",
-            "node_add",
-            "continuous"
-        ]
-    },
-    "model::rack_id": {
-        "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/model/metadata.h#L60",
-        "type": "string"
-    },
-    "model::timestamp_type": {
-        "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/model/timestamp.h#L30",
-        "enum": [
-            "create_time",
-            "append_time"
-        ]
-    },
-    "net::unresolved_address": {
-        "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/net/unresolved_address.h#L27",
-        "properties": {
-            "address": {
-                "type": "string"
-            },
-            "port": {
-                "type": "integer",
-                "minimum": 0,
-                "maximum": 4294967295
-            }
-        }
-    },
-    "pandaproxy::schema_registry::schema_id_validation_mode": {
-        "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/pandaproxy/schema_registry/schema_id_validation.h#L22",
-        "enum": [
-            "none",
-            "redpanda",
-            "compat"
-        ]
-    },
-    "retention_duration_property": {
-        "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/config/property.h#L878",
-        "type": "integer",
-        "minimum": -2147483648,
-        "maximum": 2147483647
-    },
-    "seed_server": {
-        "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/config/seed_server.h#L24",
-        "type": "object",
-        "properties": {
-            "host": {
-                "$ref": "#/definitions/net::unresolved_address"
-            }
-        }
-    },
-    "throughput_control_group": {
-        "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/config/throughput_control_group.h#L36",
-        "type": "object",
-        "properties": {
-            "name": {
-                "type": "string"
-            },
-            "client_id": {
-                "type": "string"
-            }
-        }
-    }
-}