@redpanda-data/docs-extensions-and-macros 4.12.2 → 4.12.4

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

@@ -104,7 +104,12 @@ module.exports = function renderConnectFields(children, prefix = '') {
       }
       // Complex object/array
       else if (typeof child.default === 'object') {
-        const defYaml = yaml.stringify(child.default).trim();
+        const defYaml = yaml.stringify(child.default, {
+          defaultStringType: 'PLAIN',
+          defaultKeyType: 'PLAIN',
+          lineWidth: 0,
+          simpleKeys: false
+        }).trim();
         block += `*Default*:\n[source,yaml]\n----\n${defYaml}\n----\n\n`;
       }
       // Primitive
@@ -138,61 +143,77 @@ module.exports = function renderConnectFields(children, prefix = '') {
     if (child.examples && child.examples.length) {
       block += `[source,yaml]\n----\n# Examples:\n`;
       if (child.kind === 'array') {
-        child.examples.forEach(example => {
+        child.examples.forEach((example, exampleIndex) => {
           if (Array.isArray(example)) {
             // Check if array contains any objects
             const hasObjects = example.some(item => typeof item === 'object' && item !== null);
 
+            // Always use block style for arrays
             if (hasObjects) {
-              // Use block style for arrays of objects
+              // Arrays of objects
               block += renderYamlList(child.name, [example]);
             } else {
-              // Use flow style for arrays of primitives: fieldName: [item1, item2, ...]
-              const items = example.map(item => {
+              // Arrays of primitives - use block style
+              block += `${child.name}:\n`;
+              example.forEach(item => {
+                let value;
                 if (typeof item === 'string') {
                   // Check if already quoted (starts and ends with quotes)
                   const alreadyQuoted = item.startsWith('"') && item.endsWith('"');
 
                   if (alreadyQuoted) {
                     // Already quoted, return as-is
-                    return item;
+                    value = item;
+                  } else {
+                    // Check if quoting is needed
+                    const needsQuoting = item === '' ||
+                                         item === '*' ||
+                                         /^(true|false|null|yes|no|on|off)$/i.test(item) ||
+                                         /^[-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?$/.test(item) ||
+                                         /[:\[\]\{\},&>|%@`"]/.test(item) ||
+                                         /\s/.test(item); // any whitespace
+
+                    if (needsQuoting) {
+                      // Escape backslashes first, then double quotes
+                      const escaped = item.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+                      value = `"${escaped}"`;
+                    } else {
+                      value = item;
+                    }
                   }
-
-                  // Check if quoting is needed
-                  const needsQuoting = item === '' ||
-                                       item === '*' ||
-                                       /^(true|false|null|yes|no|on|off)$/i.test(item) ||
-                                       /^[-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?$/.test(item) ||
-                                       /[:\[\]\{\},&>|%@`"]/.test(item) ||
-                                       /\s/.test(item); // any whitespace
-
-                  if (needsQuoting) {
-                    // Escape backslashes first, then double quotes
-                    const escaped = item.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
-                    return `"${escaped}"`;
+                } else {
+                  // For primitives (numbers, booleans, etc.), convert to string
+                  const strValue = String(item);
+                  // Check if the stringified value needs quoting
+                  if (/[:\[\]\{\},&>|%@`"]/.test(strValue) || /\s/.test(strValue)) {
+                    const escaped = strValue.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+                    value = `"${escaped}"`;
+                  } else {
+                    value = strValue;
                   }
-                  return item;
-                }
-                // For primitives (numbers, booleans, etc.), convert to string
-                const strValue = String(item);
-                // Check if the stringified value needs quoting
-                if (/[:\[\]\{\},&>|%@`"]/.test(strValue) || /\s/.test(strValue)) {
-                  const escaped = strValue.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
-                  return `"${escaped}"`;
                 }
-                return strValue;
+                block += `  - ${value}\n`;
               });
-              block += `${child.name}: [${items.join(', ')}]\n`;
             }
           } else {
             // Fallback for non-array examples (shouldn't happen for array fields)
             block += `${child.name}: ${example}\n`;
           }
+
+          // Add separator between examples, but not after the last one
+          if (exampleIndex < child.examples.length - 1) {
+            block += `\n# ---\n\n`;
+          }
         });
       } else {
-        child.examples.forEach(example => {
+        child.examples.forEach((example, exampleIndex) => {
           if (typeof example === 'object') {
-            const snippet = yaml.stringify(example).trim();
+            const snippet = yaml.stringify(example, {
+              defaultStringType: 'PLAIN',
+              defaultKeyType: 'PLAIN',
+              lineWidth: 0,
+              simpleKeys: false
+            }).trim();
             block += `${child.name}:\n`;
             block += snippet.split('\n').map(line => '  ' + line).join('\n') + '\n';
           } else if (typeof example === 'string' && example.includes('\n')) {
@@ -202,6 +223,11 @@ module.exports = function renderConnectFields(children, prefix = '') {
             // Primitive values
             block += `${child.name}: ${example}\n`;
           }
+
+          // Add separator between examples, but not after the last one
+          if (exampleIndex < child.examples.length - 1) {
+            block += `\n# ---\n\n`;
+          }
         });
       }
       block += `----\n\n`;

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

@@ -31,7 +31,7 @@ module.exports = function renderLeafField(field, indentLevel) {
 
   // If a default is provided, use it:
   if (field.default !== undefined) {
-    // Empty array inline
+    // Empty array - use block style
     if (Array.isArray(field.default) && field.default.length === 0) {
       return `${indent}${name}: []`;
     }
@@ -45,10 +45,16 @@ module.exports = function renderLeafField(field, indentLevel) {
       return `${indent}${name}: {}`;
     }
 
-    // Complex object/array: dump as YAML block
+    // Complex object/array: dump as YAML block style
     if (typeof field.default === 'object') {
       try {
-        const rawYaml = yaml.stringify(field.default).trim();
+        // Force block style for all arrays and nested structures
+        const rawYaml = yaml.stringify(field.default, {
+          defaultStringType: 'PLAIN',
+          defaultKeyType: 'PLAIN',
+          lineWidth: 0,  // Disable line wrapping to prevent flow style
+          simpleKeys: false
+        }).trim();
         const indentedYaml = rawYaml
           .split('\n')
           .map(line => ' '.repeat(indentLevel + 2) + line)
@@ -79,6 +85,7 @@ module.exports = function renderLeafField(field, indentLevel) {
   }
 
   // No default → choose representation
+  // Note: Empty arrays still use [] for brevity when showing placeholder with comment
   if (field.kind === 'array') {
     return `${indent}${name}: [] ${comment}`;
   } else {

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

@@ -24,8 +24,13 @@ module.exports = function renderYamlList(name, exampleGroups) {
         }
         out += `  - ${value}\n`;
       } else {
-        // Objects/arrays: stringify with indentation
-        const snippet = yaml.stringify(item).trim();
+        // Objects/arrays: stringify with indentation using block style
+        const snippet = yaml.stringify(item, {
+          defaultStringType: 'PLAIN',
+          defaultKeyType: 'PLAIN',
+          lineWidth: 0,
+          simpleKeys: false
+        }).trim();
         const lines = snippet.split('\n');
         out += lines
           .map((line, idx) => (idx === 0 ? `  - ${line}` : `    ${line}`))

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

@@ -1,11 +1,16 @@
 const yaml = require('yaml');
-	
+
 /**
- * Converts an object to a YAML string.
+ * Converts an object to a YAML string using block style for arrays.
  *
  * @param {Object} obj - The object to convert.
  * @returns {string} The YAML representation of the object, trimmed.
  */
 module.exports = function toYaml(obj) {
-  return yaml.stringify(obj).trim();
+  return yaml.stringify(obj, {
+    defaultStringType: 'PLAIN',
+    defaultKeyType: 'PLAIN',
+    lineWidth: 0,  // Disable line wrapping to prevent flow style
+    simpleKeys: false
+  }).trim();
 }

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

@@ -101,6 +101,9 @@ function generateConnectorDiffJson(oldIndex, newIndex, opts = {}) {
 
   // Newly deprecated fields (exist in both versions but became deprecated)
   const deprecatedFields = [];
+  // Changed default values
+  const changedDefaults = [];
+
   Object.keys(newMap).forEach(cKey => {
     if (!(cKey in oldMap)) return;
     const oldFieldsArr = oldMap[cKey].fields || [];
@@ -137,6 +140,26 @@ function generateConnectorDiffJson(oldIndex, newIndex, opts = {}) {
           description: newFieldObj && newFieldObj.description
         });
       }
+
+      // Check for changed default values
+      if (oldFieldObj && newFieldObj) {
+        const oldDefault = oldFieldObj.default;
+        const newDefault = newFieldObj.default;
+
+        // Compare defaults using JSON stringification to handle objects/arrays
+        const oldDefaultStr = JSON.stringify(oldDefault);
+        const newDefaultStr = JSON.stringify(newDefault);
+
+        if (oldDefaultStr !== newDefaultStr) {
+          changedDefaults.push({
+            component: cKey,
+            field: fName,
+            oldDefault: oldDefault,
+            newDefault: newDefault,
+            description: newFieldObj && newFieldObj.description
+          });
+        }
+      }
     });
   });
 
@@ -152,7 +175,8 @@ function generateConnectorDiffJson(oldIndex, newIndex, opts = {}) {
       newFields: newFields.length,
       removedFields: removedFields.length,
       deprecatedComponents: deprecatedComponents.length,
-      deprecatedFields: deprecatedFields.length
+      deprecatedFields: deprecatedFields.length,
+      changedDefaults: changedDefaults.length
     },
     details: {
       newComponents,
@@ -160,7 +184,8 @@ function generateConnectorDiffJson(oldIndex, newIndex, opts = {}) {
       newFields,
       removedFields,
       deprecatedComponents,
-      deprecatedFields
+      deprecatedFields,
+      changedDefaults
     }
   };
 }
@@ -281,6 +306,9 @@ function printDeltaReport(oldIndex, newIndex) {
 
   // Newly deprecated fields
   const deprecatedFieldsList = [];
+  // Changed default values
+  const changedDefaultsList = [];
+
   Object.keys(newMap).forEach(cKey => {
     if (!(cKey in oldMap)) return;
     const oldFieldsArr = oldMap[cKey].fields || [];
@@ -306,6 +334,25 @@ function printDeltaReport(oldIndex, newIndex) {
       if (!oldDeprecated && newDeprecated) {
         deprecatedFieldsList.push({ component: cKey, field: fName });
       }
+
+      // Check for changed default values
+      if (oldFieldObj && newFieldObj) {
+        const oldDefault = oldFieldObj.default;
+        const newDefault = newFieldObj.default;
+
+        // Compare defaults using JSON stringification to handle objects/arrays
+        const oldDefaultStr = JSON.stringify(oldDefault);
+        const newDefaultStr = JSON.stringify(newDefault);
+
+        if (oldDefaultStr !== newDefaultStr) {
+          changedDefaultsList.push({
+            component: cKey,
+            field: fName,
+            oldDefault: oldDefault,
+            newDefault: newDefault
+          });
+        }
+      }
     });
   });
 
@@ -365,6 +412,21 @@ function printDeltaReport(oldIndex, newIndex) {
   } else {
     console.log('➤ No newly deprecated fields.\n');
   }
+
+  if (changedDefaultsList.length) {
+    console.log('➤ Changed default values:');
+    changedDefaultsList.forEach(entry => {
+      const { component, field, oldDefault, newDefault } = entry;
+      const oldStr = JSON.stringify(oldDefault);
+      const newStr = JSON.stringify(newDefault);
+      console.log(`   • ${component} → ${field}`);
+      console.log(`     Old: ${oldStr}`);
+      console.log(`     New: ${newStr}`);
+    });
+    console.log('');
+  } else {
+    console.log('➤ No changed default values.\n');
+  }
 }
 
 module.exports = {