@redpanda-data/docs-extensions-and-macros 4.7.4 → 4.8.1

package/tools/property-extractor/helpers/formatPropertyValue.js

@@ -0,0 +1,128 @@
+const handlebars = require('handlebars');
+
+/**
+ * Helper function to format a value (used in object/array formatting)
+ */
+function formatValue(val) {
+  if (typeof val === 'string') {
+    return `"${val}"`;
+  } else if (typeof val === 'boolean') {
+    return val ? 'true' : 'false';
+  } else if (val === null || val === undefined) {
+    return 'null';
+  } else if (Array.isArray(val)) {
+    return "[" + val.map(v => formatValue(v)).join(", ") + "]";
+  } else if (typeof val === 'object' && val !== null) {
+    return JSON.stringify(val);
+  } else {
+    return String(val);
+  }
+}
+
+/**
+ * Process C++ internal representations and convert them to user-friendly formats
+ * This matches the Python process_defaults function logic
+ */
+function processDefaults(inputString, suffix) {
+  if (typeof inputString !== 'string') {
+    return inputString;
+  }
+
+  // Test for ip:port in vector: std::vector<net::unresolved_address>({{...}})
+  const vectorMatch = inputString.match(/std::vector<net::unresolved_address>\(\{\{("([\d.]+)",\s*(\d+))\}\}\)/);
+  if (vectorMatch) {
+    const ip = vectorMatch[2];
+    const port = vectorMatch[3];
+    return [`${ip}:${port}`];
+  }
+
+  // Test for ip:port in single-string: net::unresolved_address("127.0.0.1", 9092)
+  const brokerMatch = inputString.match(/net::unresolved_address\("([\d.]+)",\s*(\d+)\)/);
+  if (brokerMatch) {
+    const ip = brokerMatch[1];
+    const port = brokerMatch[2];
+    return `${ip}:${port}`;
+  }
+
+  // Handle std::nullopt
+  if (inputString.includes('std::nullopt')) {
+    return inputString.replace(/std::nullopt/g, 'null');
+  }
+
+  // Handle time units and other patterns would go here...
+  // For now, return the original string
+  return inputString;
+}
+
+/**
+ * Formats a property value for display, matching Python legacy format exactly
+ * @param {*} value - The value to format
+ * @param {string} type - The property type
+ * @returns {handlebars.SafeString} Formatted value
+ */
+module.exports = function formatPropertyValue(value, type) {
+  if (value === null || value === undefined || value === '') {
+    return new handlebars.SafeString('null');
+  }
+
+  if (typeof value === 'boolean') {
+    return new handlebars.SafeString(value ? 'true' : 'false');
+  }
+
+  if (typeof value === 'object' && !Array.isArray(value)) {
+    // Format object defaults with Python-style syntax: {key: "value", key2: value2}
+    const pairs = [];
+    for (const [k, v] of Object.entries(value)) {
+      // Process each value for C++ representations
+      let processedValue = v;
+      if (typeof v === 'string') {
+        processedValue = processDefaults(v, null);
+      }
+      pairs.push(`${k}: ${formatValue(processedValue)}`);
+    }
+    return new handlebars.SafeString(`{${pairs.join(', ')}}`);
+  }
+
+  if (Array.isArray(value)) {
+    // Handle array defaults to match Python format
+    if (value.length === 0) {
+      return new handlebars.SafeString('[]');
+    } else {
+      // Format each array element
+      const formattedElements = [];
+      for (const item of value) {
+        if (typeof item === 'object' && item !== null) {
+          // Format object within array
+          const pairs = [];
+          for (const [k, v] of Object.entries(item)) {
+            // Process each value for C++ representations
+            let processedValue = v;
+            if (typeof v === 'string') {
+              processedValue = processDefaults(v, null);
+            }
+            pairs.push(`${k}: ${formatValue(processedValue)}`);
+          }
+          formattedElements.push(`{${pairs.join(', ')}}`);
+        } else {
+          formattedElements.push(String(item));
+        }
+      }
+      return new handlebars.SafeString(`[${formattedElements.join(', ')}]`);
+    }
+  }
+
+  // For other types, handle strings vs non-strings differently
+  let result;
+  if (typeof value === 'string') {
+    // Keep strings as-is (preserve original characters and casing)
+    result = value;
+  } else {
+    // Convert non-string values to String without altering case/quotes
+    result = String(value);
+  }
+  
+  // Apply C++ processing
+  result = processDefaults(result, null);
+  
+  return new handlebars.SafeString(result);
+};

package/tools/property-extractor/helpers/formatUnits.js

@@ -0,0 +1,26 @@
+/**
+ * Formats units for display based on property name suffix
+ * @param {string} name - Property name that might contain unit suffixes
+ * @returns {string} Formatted unit description
+ */
+module.exports = function formatUnits(name) {
+  const suffixToUnit = {
+    'ms': 'milliseconds',
+    'sec': 'seconds',
+    'seconds': 'seconds',
+    'bytes': 'bytes',
+    'buf': 'bytes',
+    'partitions': 'number of partitions per topic',
+    'percent': 'percent',
+    'bps': 'bytes per second',
+    'fraction': 'fraction'
+  };
+
+  if (!name) return '';
+
+  // Extract the last part after splitting on underscores (like Python implementation)
+  const parts = name.split('_');
+  const suffix = parts[parts.length - 1];
+  
+  return suffixToUnit[suffix] || '';
+};

package/tools/property-extractor/helpers/index.js

@@ -0,0 +1,13 @@
+'use strict';
+
+module.exports = {
+  join: require('./join.js'),
+  eq: require('./eq.js'),
+  ne: require('./ne.js'),
+  and: require('./and.js'),
+  or: require('./or.js'),
+  not: require('./not.js'),
+  formatPropertyValue: require('./formatPropertyValue.js'),
+  renderPropertyExample: require('./renderPropertyExample.js'),
+  formatUnits: require('./formatUnits.js'),
+};

package/tools/property-extractor/helpers/join.js

@@ -0,0 +1,18 @@
+/**
+ * Handlebars helper to join an array with a separator
+ * @param {Array} array - The array to join
+ * @param {string} separator - The separator to use
+ * @returns {string} The joined string
+ */
+module.exports = function join(array, separator) {
+  if (!Array.isArray(array)) {
+    return '';
+  }
+  
+  // Detect and ignore Handlebars options object
+  if (separator && typeof separator === 'object' && (separator.hash !== undefined || separator.data !== undefined)) {
+    separator = undefined;
+  }
+  
+  return array.join(separator || ', ');
+};

package/tools/property-extractor/helpers/ne.js

@@ -0,0 +1,9 @@
+/**
+ * Handlebars helper for inequality comparison
+ * @param {*} a - First value
+ * @param {*} b - Second value
+ * @returns {boolean} True if values are not equal
+ */
+module.exports = function ne(a, b) {
+  return a !== b;
+};

package/tools/property-extractor/helpers/not.js

@@ -0,0 +1,8 @@
+/**
+ * Handlebars helper for logical NOT
+ * @param {*} value - Value to negate
+ * @returns {boolean} True if value is falsy
+ */
+module.exports = function not(value) {
+  return !value;
+};

package/tools/property-extractor/helpers/or.js

@@ -0,0 +1,10 @@
+/**
+ * Handlebars helper for logical OR
+ * @param {...*} args - Values to check
+ * @returns {boolean} True if any value is truthy
+ */
+module.exports = function or(...args) {
+  // Remove the last argument which is the Handlebars options object
+  const values = args.slice(0, -1);
+  return values.some(val => !!val);
+};

package/tools/property-extractor/helpers/renderPropertyExample.js

@@ -0,0 +1,42 @@
+const handlebars = require('handlebars');
+
+/**
+ * Renders an example for a property based on its format
+ * @param {Object} property - The property object containing example data
+ * @returns {handlebars.SafeString} Formatted example block
+ */
+module.exports = function renderPropertyExample(property) {
+  if (!property.example) {
+    return new handlebars.SafeString('');
+  }
+
+  let exampleContent = '';
+
+  // Handle different example formats
+  if (typeof property.example === 'string') {
+    // Check if it's already a complete AsciiDoc example
+    if (property.example.includes('.Example') || property.example.includes('[,yaml]')) {
+      exampleContent = property.example;
+    } else {
+      // Simple string example - wrap it
+      exampleContent = `.Example\n[,yaml]\n----\n${property.name}: ${property.example}\n----`;
+    }
+  } else if (Array.isArray(property.example)) {
+    // Multiline array example
+    exampleContent = property.example.join('\n');
+  } else if (typeof property.example === 'object' && property.example.title) {
+    // Structured example with title and content
+    exampleContent = `.${property.example.title}\n`;
+    if (property.example.description) {
+      exampleContent += `${property.example.description}\n\n`;
+    }
+    if (property.example.config) {
+      exampleContent += `[,yaml]\n----\n${JSON.stringify(property.example.config, null, 2)}\n----`;
+    }
+  } else {
+    // Fallback: JSON stringify the example
+    exampleContent = `.Example\n[,yaml]\n----\n${property.name}: ${JSON.stringify(property.example, null, 2)}\n----`;
+  }
+
+  return new handlebars.SafeString('\n' + exampleContent + '\n');
+};

package/tools/property-extractor/package-lock.json

@@ -0,0 +1,77 @@
+{
+  "name": "property-extractor",
+  "version": "1.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "dependencies": {
+        "handlebars": "^4.7.8"
+      }
+    },
+    "node_modules/handlebars": {
+      "version": "4.7.8",
+      "resolved": "https://registry.npmjs.org/handlebars/-/handlebars-4.7.8.tgz",
+      "integrity": "sha512-vafaFqs8MZkRrSX7sFVUdo3ap/eNiLnb4IakshzvP56X5Nr1iGKAIqdX6tMlm6HcNRIkr6AxO5jFEoJzzpT8aQ==",
+      "license": "MIT",
+      "dependencies": {
+        "minimist": "^1.2.5",
+        "neo-async": "^2.6.2",
+        "source-map": "^0.6.1",
+        "wordwrap": "^1.0.0"
+      },
+      "bin": {
+        "handlebars": "bin/handlebars"
+      },
+      "engines": {
+        "node": ">=0.4.7"
+      },
+      "optionalDependencies": {
+        "uglify-js": "^3.1.4"
+      }
+    },
+    "node_modules/minimist": {
+      "version": "1.2.8",
+      "resolved": "https://registry.npmjs.org/minimist/-/minimist-1.2.8.tgz",
+      "integrity": "sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/neo-async": {
+      "version": "2.6.2",
+      "resolved": "https://registry.npmjs.org/neo-async/-/neo-async-2.6.2.tgz",
+      "integrity": "sha512-Yd3UES5mWCSqR+qNT93S3UoYUkqAZ9lLg8a7g9rimsWmYGK8cVToA4/sF3RrshdyV3sAGMXVUmpMYOw+dLpOuw==",
+      "license": "MIT"
+    },
+    "node_modules/source-map": {
+      "version": "0.6.1",
+      "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.6.1.tgz",
+      "integrity": "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==",
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/uglify-js": {
+      "version": "3.19.3",
+      "resolved": "https://registry.npmjs.org/uglify-js/-/uglify-js-3.19.3.tgz",
+      "integrity": "sha512-v3Xu+yuwBXisp6QYTcH4UbH+xYJXqnq2m/LtQVWKWzYc1iehYnLixoQDN9FH6/j9/oybfd6W9Ghwkl8+UMKTKQ==",
+      "license": "BSD-2-Clause",
+      "optional": true,
+      "bin": {
+        "uglifyjs": "bin/uglifyjs"
+      },
+      "engines": {
+        "node": ">=0.8.0"
+      }
+    },
+    "node_modules/wordwrap": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/wordwrap/-/wordwrap-1.0.0.tgz",
+      "integrity": "sha512-gvVzJFlPycKc5dZN4yPkP8w7Dc37BtP1yczEneOb4uq34pXZcvrtRTmWV8W+Ume+XCxKgbjM+nevkyFPMybd4Q==",
+      "license": "MIT"
+    }
+  }
+}

package/tools/property-extractor/package.json

@@ -0,0 +1,6 @@
+{
+  "private": true,
+  "dependencies": {
+    "handlebars": "^4.7.8"
+  }
+}