@redpanda-data/docs-extensions-and-macros 5.0.2 → 5.0.4

package/extensions/version-fetcher/set-latest-version.js

@@ -135,12 +135,97 @@ module.exports.register = function ({ config }) {
         }
       });
 
+      // Find latest available Redpanda properties JSON in content catalog
+      // This ensures we use a version that actually exists, even if latest-redpanda-tag
+      // points to a newer release that doesn't have docs/attachments yet
+      // Component name is 'streaming' (or 'ROOT' for backwards compatibility)
+      const propertiesFiles = contentCatalog.findBy({
+        family: 'attachment'
+      }).filter(f => {
+        if (!f?.src?.stem || !f?.src?.component) return false;
+        const isStreamingComponent = f.src.component === 'streaming' || f.src.component === 'ROOT';
+        const isReferenceModule = f.src.module === 'reference';
+        const isPropertiesFile = f.src.stem.startsWith('redpanda-properties-');
+        return isStreamingComponent && isReferenceModule && isPropertiesFile;
+      });
+
+      let availablePropertiesTag = null;
+      if (propertiesFiles.length > 0) {
+        const versions = propertiesFiles
+          .map(f => f.src.stem.replace('redpanda-properties-', ''))
+          // Only accept stable versions (no prerelease suffix like -backup, -rc1, etc.)
+          .filter(v => {
+            const normalized = v.replace(/^v/, '');
+            return semver.valid(normalized) && semver.prerelease(normalized) === null;
+          });
+
+        if (versions.length > 0) {
+          availablePropertiesTag = versions.sort((a, b) =>
+            semver.rcompare(a.replace(/^v/, ''), b.replace(/^v/, ''))
+          )[0];
+
+          // Set on all component versions
+          components.forEach(component => {
+            component.versions.forEach(({ asciidoc }) => {
+              asciidoc.attributes['available-properties-tag'] = availablePropertiesTag;
+            });
+          });
+
+          logger.debug(`Found ${propertiesFiles.length} properties JSON files, latest available: ${availablePropertiesTag}`);
+        }
+      } else {
+        logger.debug('No properties JSON files found in content catalog');
+      }
+
+      // Find latest available Connect JSON in content catalog
+      // Component name is 'connect' (or 'redpanda-connect' for backwards compatibility)
+      const connectFiles = contentCatalog.findBy({
+        family: 'attachment'
+      }).filter(f => {
+        if (!f?.src?.stem || !f?.src?.component) return false;
+        const isConnectComponent = f.src.component === 'connect' || f.src.component === 'redpanda-connect';
+        const isComponentsModule = f.src.module === 'components';
+        const isConnectFile = f.src.stem.startsWith('connect-');
+        return isConnectComponent && isComponentsModule && isConnectFile;
+      });
+
+      let availableConnectVersion = null;
+      if (connectFiles.length > 0) {
+        const versions = connectFiles
+          .map(f => f.src.stem.replace('connect-', ''))
+          // Only accept stable versions (no prerelease suffix)
+          .filter(v => semver.valid(v) && semver.prerelease(v) === null);
+
+        if (versions.length > 0) {
+          availableConnectVersion = versions.sort((a, b) =>
+            semver.rcompare(a, b)
+          )[0];
+
+          // Set on all component versions
+          components.forEach(component => {
+            component.versions.forEach(({ asciidoc }) => {
+              asciidoc.attributes['available-connect-version'] = availableConnectVersion;
+            });
+          });
+
+          logger.debug(`Found ${connectFiles.length} connect JSON files, latest available: ${availableConnectVersion}`);
+        }
+      } else {
+        logger.debug('No connect JSON files found in content catalog');
+      }
+
       logger.info('Updated Redpanda documentation versions successfully:');
       logger.info(`- Redpanda: ${latestVersions.redpanda.latestRedpandaRelease.version}${latestVersions.redpanda.latestRcRelease ? ', beta: ' + latestVersions.redpanda.latestRcRelease.version : ''}`);
       logger.info(`- Connect: ${latestVersions.connect}`);
       logger.info(`- Console: ${latestVersions.console.latestStableRelease}${latestVersions.console.latestBetaRelease ? ', beta: ' + latestVersions.console.latestBetaRelease : ''}`);
       logger.info(`- Operator: ${latestVersions.operator?.latestStableRelease || 'unknown'}${latestVersions.operator?.latestBetaRelease ? ', beta: ' + latestVersions.operator.latestBetaRelease : ''}`);
       logger.info(`- Helm chart: ${latestVersions.helmChart?.latestStableRelease || 'unknown'}${latestVersions.helmChart?.latestBetaRelease ? ', beta: ' + latestVersions.helmChart.latestBetaRelease : ''}`);
+      if (availablePropertiesTag) {
+        logger.info(`- Available properties JSON: ${availablePropertiesTag}`);
+      }
+      if (availableConnectVersion) {
+        logger.info(`- Available Connect JSON: ${availableConnectVersion}`);
+      }
     } catch (error) {
       logger.error(`Error updating versions: ${error}`);
     }
@@ -174,4 +259,50 @@ module.exports.register = function ({ config }) {
       }
     });
   }
+};
+
+// Export helper functions for testing
+module.exports.filterPropertiesFiles = function(files) {
+  return files.filter(f => {
+    if (!f?.src?.stem || !f?.src?.component) return false;
+    const isStreamingComponent = f.src.component === 'streaming' || f.src.component === 'ROOT';
+    const isReferenceModule = f.src.module === 'reference';
+    const isPropertiesFile = f.src.stem.startsWith('redpanda-properties-');
+    return isStreamingComponent && isReferenceModule && isPropertiesFile;
+  });
+};
+
+module.exports.filterConnectFiles = function(files) {
+  return files.filter(f => {
+    if (!f?.src?.stem || !f?.src?.component) return false;
+    const isConnectComponent = f.src.component === 'connect' || f.src.component === 'redpanda-connect';
+    const isComponentsModule = f.src.module === 'components';
+    const isConnectFile = f.src.stem.startsWith('connect-');
+    return isConnectComponent && isComponentsModule && isConnectFile;
+  });
+};
+
+module.exports.extractLatestPropertiesVersion = function(files, semver) {
+  const versions = files
+    .map(f => f.src.stem.replace('redpanda-properties-', ''))
+    .filter(v => {
+      const normalized = v.replace(/^v/, '');
+      return semver.valid(normalized) && semver.prerelease(normalized) === null;
+    });
+
+  if (versions.length === 0) return null;
+
+  return versions.sort((a, b) =>
+    semver.rcompare(a.replace(/^v/, ''), b.replace(/^v/, ''))
+  )[0];
+};
+
+module.exports.extractLatestConnectVersion = function(files, semver) {
+  const versions = files
+    .map(f => f.src.stem.replace('connect-', ''))
+    .filter(v => semver.valid(v) && semver.prerelease(v) === null);
+
+  if (versions.length === 0) return null;
+
+  return versions.sort((a, b) => semver.rcompare(a, b))[0];
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "5.0.2",
+  "version": "5.0.4",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",

package/tools/property-extractor/constant_resolver.py

@@ -22,7 +22,8 @@ class ConstantResolver:
         Args:
             source_path: Path to the Redpanda src/v directory
         """
-        self.source_path = source_path
+        # Ensure source_path is a Path object
+        self.source_path = Path(source_path) if not isinstance(source_path, Path) else source_path
         self._constant_cache: Dict[str, str] = {}
 
     def resolve_constant(self, constant_name: str) -> Optional[str]:
@@ -371,6 +372,173 @@ class ConstantResolver:
 
         return result
 
+    def _parse_size_literal(self, value: str) -> Optional[int]:
+        """
+        Parse C++ size literals like 256_MiB, 20_GiB to integers.
+
+        Args:
+            value: The size literal string (e.g., "256_MiB", "20_GiB", "1024", "1'024_KiB", "1048576ULL")
+
+        Returns:
+            The integer value in bytes, or None if parsing fails
+        """
+        if not value:
+            return None
+
+        value = value.strip()
+
+        # Remove C++ digit separators (apostrophes) - e.g., 1'024 -> 1024
+        value = value.replace("'", "")
+
+        # Binary suffixes (powers of 1024)
+        binary_suffixes = {
+            '_GiB': 1024**3,
+            '_MiB': 1024**2,
+            '_KiB': 1024,
+        }
+
+        # Decimal suffixes (powers of 1000)
+        decimal_suffixes = {
+            '_GB': 1000**3,
+            '_MB': 1000**2,
+            '_KB': 1000,
+        }
+
+        all_suffixes = {**binary_suffixes, **decimal_suffixes}
+
+        for suffix, multiplier in all_suffixes.items():
+            if value.endswith(suffix):
+                try:
+                    num = int(value[:-len(suffix)])
+                    return num * multiplier
+                except ValueError:
+                    return None
+
+        # Try parsing as plain integer
+        # First strip C++ integer suffixes (U, L, UL, LL, ULL, etc.)
+        normalized = re.sub(r'[uUlLzZ]+$', '', value)
+        try:
+            return int(normalized)
+        except ValueError:
+            return None
+
+    def resolve_numeric_constant(self, constant_name: str) -> Optional[dict]:
+        """
+        Resolve a C++ numeric constant to its actual value.
+
+        Handles patterns like:
+        - constexpr size_t DEFAULT_TOPIC_MEMORY_PER_PARTITION = 256_MiB;
+        - inline constexpr uint64_t identifier = 12345;
+        - constexpr auto identifier = 20_GiB;
+
+        Args:
+            constant_name: The constant name (e.g., "DEFAULT_TOPIC_MEMORY_PER_PARTITION")
+
+        Returns:
+            Dict with 'raw' (int) and 'friendly' (str) values, or None if not found
+        """
+        # Check cache first
+        cache_key = f"numeric:{constant_name}"
+        if cache_key in self._constant_cache:
+            return self._constant_cache[cache_key]
+
+        # Strip namespace qualifier if present
+        if '::' in constant_name:
+            namespace, identifier = constant_name.rsplit('::', 1)
+        else:
+            namespace = None
+            identifier = constant_name
+
+        # Search patterns for numeric constants
+        numeric_patterns = [
+            # constexpr size_t/uint64_t/int64_t identifier = VALUE;
+            rf'(?:inline\s+)?constexpr\s+(?:size_t|uint64_t|int64_t|int|unsigned(?:\s+int)?|long(?:\s+long)?)\s+{re.escape(identifier)}\s*=\s*([^;]+);',
+            # constexpr auto identifier = VALUE;
+            rf'(?:inline\s+)?constexpr\s+auto\s+{re.escape(identifier)}\s*=\s*([^;]+);',
+            # constexpr type identifier{VALUE};
+            rf'(?:inline\s+)?constexpr\s+(?:size_t|uint64_t|int64_t|int|unsigned(?:\s+int)?)\s+{re.escape(identifier)}\s*\{{\s*([^}}]+)\s*\}}',
+            # static constexpr variants
+            rf'static\s+(?:inline\s+)?constexpr\s+(?:size_t|uint64_t|int64_t|int|unsigned(?:\s+int)?)\s+{re.escape(identifier)}\s*=\s*([^;]+);',
+        ]
+
+        # Determine search directories based on namespace
+        if namespace == 'config':
+            search_dirs = ['config']
+        elif namespace == 'model':
+            search_dirs = ['model']
+        elif namespace == 'kafka':
+            search_dirs = ['kafka']
+        else:
+            # Search common locations
+            search_dirs = ['config', 'model', 'kafka', 'cluster']
+
+        for dir_name in search_dirs:
+            search_path = self.source_path / dir_name
+            if not search_path.exists():
+                continue
+
+            # Search both .h and .cc files
+            for file_path in list(search_path.rglob('*.h')) + list(search_path.rglob('*.cc')):
+                try:
+                    with open(file_path, 'r', encoding='utf-8', errors='ignore') as f:
+                        content = f.read()
+
+                    for pattern in numeric_patterns:
+                        match = re.search(pattern, content)
+                        if match:
+                            raw_value = match.group(1).strip()
+                            logger.debug(f"Found numeric constant {constant_name} = {raw_value} in {file_path}")
+
+                            # Try to parse the value
+                            parsed = self._parse_size_literal(raw_value)
+                            if parsed is not None:
+                                result = self._format_numeric_result(parsed)
+                                self._constant_cache[cache_key] = result
+                                logger.info(f"Resolved numeric constant {constant_name} = {result}")
+                                return result
+                            else:
+                                # Couldn't parse, return raw string
+                                logger.debug(f"Could not parse numeric value: {raw_value}")
+
+                except Exception as e:
+                    logger.debug(f"Error reading {file_path}: {e}")
+                    continue
+
+        logger.debug(f"Could not resolve numeric constant: {constant_name}")
+        return None
+
+    def _format_numeric_result(self, value: int) -> dict:
+        """
+        Format a numeric value with both raw and human-friendly representations.
+
+        Args:
+            value: The raw numeric value in bytes
+
+        Returns:
+            Dict with 'raw' (int) and 'friendly' (str like "256 MiB (268435456)")
+        """
+        # Define units in descending order
+        units = [
+            ('GiB', 1024**3),
+            ('MiB', 1024**2),
+            ('KiB', 1024),
+        ]
+
+        for unit_name, divisor in units:
+            if value >= divisor and value % divisor == 0:
+                friendly_num = value // divisor
+                friendly_str = f"{friendly_num} {unit_name} ({value})"
+                return {
+                    'raw': value,
+                    'friendly': friendly_str
+                }
+
+        # No unit applies, just return the raw number
+        return {
+            'raw': value,
+            'friendly': str(value)
+        }
+
 
 def resolve_property_default(default_value: str, resolver: ConstantResolver) -> str:
     """

package/tools/property-extractor/property_extractor.py

@@ -723,7 +723,7 @@ def transform_files_with_properties(files_with_properties):
         NumericBoundsTransformer(type_transformer),
         DurationBoundsTransformer(type_transformer),
         SimpleDefaultValuesTransformer(),
-        FriendlyDefaultTransformer(),
+        FriendlyDefaultTransformer(constant_resolver),
         ExperimentalTransformer(),
         AliasTransformer(),
     ]

package/tools/property-extractor/transformers.py

@@ -1570,9 +1570,12 @@ class FriendlyDefaultTransformer:
     NUMERIC_LIMITS_PATTERN = r"std::numeric_limits<[^>]+>::max\(\)"
     LEGACY_DEFAULT_PATTERN = r"legacy_default<[^>]+>\(([^,]+)"
     BRACED_LIST_PATTERN = r"^\{(.*)\}$"
+    # Pattern for identifiers that look like C++ constants (ALL_CAPS with underscores)
+    CONSTANT_IDENTIFIER_PATTERN = r'^[A-Z][A-Z0-9_]*$'
 
-    def __init__(self):
+    def __init__(self, constant_resolver=None):
         self._resolver = None
+        self._constant_resolver = constant_resolver
 
     def accepts(self, info, file_pair):
         return bool(info.get("params") and len(info["params"]) > 2)
@@ -1592,6 +1595,40 @@ class FriendlyDefaultTransformer:
                 return identifier
         return identifier
 
+    def _resolve_numeric_constant(self, identifier):
+        """
+        Try to resolve a C++ numeric constant using the ConstantResolver.
+
+        Args:
+            identifier: The constant name (e.g., "DEFAULT_TOPIC_MEMORY_PER_PARTITION")
+
+        Returns:
+            The friendly formatted value (e.g., "256 MiB (268435456)"), or None if not resolved
+        """
+        if not self._constant_resolver:
+            return None
+
+        try:
+            result = self._constant_resolver.resolve_numeric_constant(identifier)
+            if result:
+                return result.get('friendly')
+        except Exception as e:
+            logger.debug(f"Error resolving numeric constant {identifier}: {e}")
+
+        return None
+
+    def _looks_like_constant(self, identifier):
+        """
+        Check if an identifier looks like a C++ constant (ALL_CAPS_WITH_UNDERSCORES).
+
+        Args:
+            identifier: The identifier to check
+
+        Returns:
+            True if it looks like a constant, False otherwise
+        """
+        return bool(re.match(self.CONSTANT_IDENTIFIER_PATTERN, identifier))
+
     def _parse_initializer_list(self, text):
         """Handle braced lists like {"a", "b"}."""
         inner = re.sub(self.BRACED_LIST_PATTERN, r"\1", text.strip()).strip()
@@ -1778,10 +1815,26 @@ class FriendlyDefaultTransformer:
             property["default"] = COMPUTED_CONSTANTS[d]
             return property
 
+        # ------------------------------------------------------------------
+        # ALL_CAPS numeric constants (DEFAULT_TOPIC_MEMORY_PER_PARTITION, etc.)
+        # Try to resolve via ConstantResolver before falling back
+        # ------------------------------------------------------------------
+        if self._looks_like_constant(d):
+            resolved = self._resolve_numeric_constant(d)
+            if resolved:
+                property["default"] = resolved
+                return property
+            # If not resolved, fall through to normalized string fallback
+
         # ------------------------------------------------------------------
         # Constant-like or symbolic identifiers (model::..., net::..., etc.)
         # ------------------------------------------------------------------
         if "::" in d and not d.startswith("std::"):
+            # Try numeric resolution first for namespace-qualified constants
+            resolved = self._resolve_numeric_constant(d)
+            if resolved:
+                property["default"] = resolved
+                return property
             # Try to resolve to string enum if possible
             resolved = self._resolve_identifier(d)
             property["default"] = resolved or d

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

@@ -31,19 +31,24 @@ module.exports = function buildConfigYaml(type, connectorName, children, include
     lines.push(`  label: ""`);
   }
 
+  // Count how many fields will be rendered to determine if we need {}
+  const fieldsToRender = children.filter(field => {
+    if (field.is_deprecated) return false;
+    if (!includeAdvanced && field.is_advanced) return false;
+    return true;
+  });
+
   // Two‐space indent for connectorName heading
-  lines.push(`  ${connectorName}:`);
+  // If no fields will be rendered, use {} for valid YAML
+  if (fieldsToRender.length === 0) {
+    lines.push(`  ${connectorName}: {}`);
+  } else {
+    lines.push(`  ${connectorName}:`);
+  }
 
   // Four‐space indent for children
   const baseIndent = 4;
-  children.forEach(field => {
-    if (field.is_deprecated) {
-      return; // skip deprecated fields
-    }
-    if (!includeAdvanced && field.is_advanced) {
-      return; // skip advanced fields in "common" mode
-    }
-
+  fieldsToRender.forEach(field => {
     // Check if this is an array-of-objects (e.g., client_certs[])
     // These should render as empty arrays, not expanded object structures
     if (field.kind === 'array' && field.type === 'object' && Array.isArray(field.children)) {

package/tools/redpanda-connect/rpcn-connector-docs-handler.js

@@ -8,7 +8,8 @@ const { getAntoraValue, setAntoraValue } = require('../../cli-utils/antora-utils
 const fetchFromGithub = require('../fetch-from-github.js')
 const { generateRpcnConnectorDocs } = require('./generate-rpcn-connector-docs.js')
 const { getRpkConnectVersion, printDeltaReport } = require('./report-delta')
-const { discoverIntermediateReleases } = require('./github-release-utils')
+const { discoverIntermediateReleases, findCloudVersionForDate } = require('./github-release-utils')
+const { analyzeAllBinaries } = require('./connector-binary-analyzer.js')
 const parseCSVConnectors = require('./parse-csv-connectors.js')
 const semver = require('semver')
 
@@ -600,15 +601,17 @@ function logCollapsed (label, filesArray, maxToShow = 10) {
 async function loadConnectorDataForVersion(version, dataDir, options = {}) {
   const dataFile = path.join(dataDir, `connect-${version}.json`);
 
-  // If file exists, load it (with platform metadata intact)
-  if (fs.existsSync(dataFile)) {
+  // If forceFresh is set, always fetch even if file exists
+  // This ensures we have accurate connector lists for diff comparison
+  if (!options.forceFresh && fs.existsSync(dataFile)) {
     console.log(`✓ Using existing data file: connect-${version}.json`);
     const data = JSON.parse(fs.readFileSync(dataFile, 'utf8'));
     return data;
   }
 
-  // If not, fetch it
-  console.log(`📥 Data file not found for ${version}, attempting to fetch...`);
+  // Fetch fresh data
+  const reason = options.forceFresh ? 'force refresh requested' : 'file not found';
+  console.log(`📥 Fetching data for ${version} (${reason})...`);
 
   try {
     // Try installing that specific version and fetching data
@@ -866,38 +869,62 @@ async function handleRpcnConnectorDocs (options) {
             console.log('─'.repeat(80) + '\n')
 
             try {
-              // Load data for both versions
-              console.log(`Loading connector data for ${fromVer}...`)
-              const oldData = await loadConnectorDataForVersion(fromVer, dataDir)
+              // Load data for both versions - FORCE FRESH to avoid stale/incomplete data
+              // This ensures we have accurate connector lists for both versions
+              console.log(`Loading connector data for ${fromVer} (fresh fetch)...`)
+              const oldData = await loadConnectorDataForVersion(fromVer, dataDir, { forceFresh: true })
 
-              console.log(`Loading connector data for ${toVer}...`)
-              const newData = await loadConnectorDataForVersion(toVer, dataDir)
+              console.log(`Loading connector data for ${toVer} (fresh fetch)...`)
+              const newData = await loadConnectorDataForVersion(toVer, dataDir, { forceFresh: true })
 
-              // Determine the appropriate cloud version for this release date
-              const releaseInfo = intermediateReleases.find(r => r.version === toVer)
+              const analysisOptions = {
+                skipCloud: false,
+                skipCgo: false,
+                cgoVersion: options.cgoVersion || null
+              }
+
+              // Determine cloud version for OLD release date
+              const oldReleaseInfo = intermediateReleases.find(r => r.version === fromVer)
+              let cloudVersionForOldRelease = options.cloudVersion || null
+
+              if (!options.cloudVersion && oldReleaseInfo && oldReleaseInfo.date) {
+                cloudVersionForOldRelease = await findCloudVersionForDate(oldReleaseInfo.date, { useCache: true })
+                if (cloudVersionForOldRelease) {
+                  console.log(`   Using cloud version ${cloudVersionForOldRelease} for old release ${fromVer}`)
+                } else {
+                  cloudVersionForOldRelease = fromVer
+                }
+              }
+
+              // Determine cloud version for NEW release date
+              const newReleaseInfo = intermediateReleases.find(r => r.version === toVer)
               let cloudVersionForRelease = options.cloudVersion || null
 
-              if (!options.cloudVersion && releaseInfo && releaseInfo.date) {
-                const { findCloudVersionForDate } = require('./github-release-utils')
-                cloudVersionForRelease = await findCloudVersionForDate(releaseInfo.date, { useCache: true })
+              if (!options.cloudVersion && newReleaseInfo && newReleaseInfo.date) {
+                cloudVersionForRelease = await findCloudVersionForDate(newReleaseInfo.date, { useCache: true })
                 if (cloudVersionForRelease) {
-                  console.log(`   Using cloud version ${cloudVersionForRelease} (current at ${new Date(releaseInfo.date).toLocaleDateString()})`)
+                  console.log(`   Using cloud version ${cloudVersionForRelease} for new release ${toVer}`)
                 } else {
-                  console.log(`   No cloud version found for release date, using OSS version ${toVer}`)
                   cloudVersionForRelease = toVer
                 }
               }
 
-              // Run binary analysis for the new version
-              console.log(`\nAnalyzing binaries for version ${toVer}...`)
-              const { analyzeAllBinaries } = require('./connector-binary-analyzer.js')
+              // Run binary analysis for BOTH versions to ensure symmetric comparison
+              console.log(`\nAnalyzing binaries for OLD version ${fromVer}...`)
+              const oldAnalysis = await analyzeAllBinaries(
+                fromVer,
+                cloudVersionForOldRelease,
+                dataDir,
+                analysisOptions
+              )
 
-              const analysisOptions = {
-                skipCloud: false,
-                skipCgo: false,
-                cgoVersion: options.cgoVersion || null
+              console.log(`Done: Binary analysis for ${fromVer}:`)
+              console.log(`   - OSS version: ${oldAnalysis.ossVersion}`)
+              if (oldAnalysis.cgoOnly && oldAnalysis.cgoOnly.length > 0) {
+                console.log(`   - CGO-only connectors: ${oldAnalysis.cgoOnly.length}`)
               }
 
+              console.log(`\nAnalyzing binaries for NEW version ${toVer}...`)
               const intermediateAnalysis = await analyzeAllBinaries(
                 toVer,
                 cloudVersionForRelease,
@@ -905,40 +932,46 @@ async function handleRpcnConnectorDocs (options) {
                 analysisOptions
               )
 
-              console.log('✓ Binary analysis complete:')
-              console.log(`   • OSS version: ${intermediateAnalysis.ossVersion}`)
+              console.log(`Done: Binary analysis for ${toVer}:`)
+              console.log(`   - OSS version: ${intermediateAnalysis.ossVersion}`)
               if (intermediateAnalysis.cloudVersion) {
-                console.log(`   • Cloud version: ${intermediateAnalysis.cloudVersion}`)
+                console.log(`   - Cloud version: ${intermediateAnalysis.cloudVersion}`)
               }
               if (intermediateAnalysis.comparison) {
-                console.log(`   • Connectors in cloud: ${intermediateAnalysis.comparison.inCloud.length}`)
-                console.log(`   • Self-hosted only: ${intermediateAnalysis.comparison.notInCloud.length}`)
+                console.log(`   - Connectors in cloud: ${intermediateAnalysis.comparison.inCloud.length}`)
+                console.log(`   - Self-hosted only: ${intermediateAnalysis.comparison.notInCloud.length}`)
                 if (intermediateAnalysis.comparison.cloudOnly) {
-                  console.log(`   • Cloud-only: ${intermediateAnalysis.comparison.cloudOnly.length}`)
+                  console.log(`   - Cloud-only: ${intermediateAnalysis.comparison.cloudOnly.length}`)
                 }
               }
+              if (intermediateAnalysis.cgoOnly && intermediateAnalysis.cgoOnly.length > 0) {
+                console.log(`   - CGO-only connectors: ${intermediateAnalysis.cgoOnly.length}`)
+              }
 
-              // Augment newData with binary analysis results before generating diff
-              // This ensures CGO-only and cloud-only connectors are included and metadata is accurate
-              const { augmentedData: augmentedNewData, addedCgoCount, addedCloudOnlyCount } =
+              // Augment BOTH oldData and newData with their respective binary analysis
+              // This ensures symmetric comparison - both have CGO/cloud connectors and metadata
+              const { augmentedData: augmentedOldData, addedCgoCount: oldCgoCount, addedCloudOnlyCount: oldCloudOnlyCount } =
+                augmentConnectorData(oldData, oldAnalysis)
+
+              const { augmentedData: augmentedNewData, addedCgoCount: newCgoCount, addedCloudOnlyCount: newCloudOnlyCount } =
                 augmentConnectorData(newData, intermediateAnalysis)
 
-              if (addedCgoCount > 0 || addedCloudOnlyCount > 0) {
-                console.log(`   • Augmented newData: +${addedCgoCount} CGO-only, +${addedCloudOnlyCount} cloud-only`)
-              }
+              console.log(`   - Augmented oldData: +${oldCgoCount} CGO-only, +${oldCloudOnlyCount} cloud-only`)
+              console.log(`   - Augmented newData: +${newCgoCount} CGO-only, +${newCloudOnlyCount} cloud-only`)
 
-              // Generate diff
-              console.log(`\nGenerating diff: ${fromVer} → ${toVer}...`)
+              // Generate diff with BOTH augmented (symmetric comparison)
+              console.log(`\nGenerating diff: ${fromVer} -> ${toVer}...`)
               const { generateConnectorDiffJson } = require('./report-delta.js')
 
               const diffData = generateConnectorDiffJson(
-                oldData,
+                augmentedOldData,
                 augmentedNewData,
                 {
                   oldVersion: fromVer,
                   newVersion: toVer,
                   timestamp,
-                  binaryAnalysis: intermediateAnalysis
+                  binaryAnalysis: intermediateAnalysis,
+                  oldBinaryAnalysis: oldAnalysis
                 }
               )
 
@@ -1136,7 +1169,6 @@ async function handleRpcnConnectorDocs (options) {
 
   try {
     console.log('\nAnalyzing connector binaries...')
-    const { analyzeAllBinaries } = require('./connector-binary-analyzer.js')
 
     if (fs.existsSync(cleanOssDataPath)) {
       if (fs.existsSync(expectedPath)) {