@redpanda-data/docs-extensions-and-macros 4.12.6 → 4.13.0

package/bin/mcp-tools/generated-docs-review.js

@@ -0,0 +1,887 @@
+/**
+ * MCP Tools - Documentation Review
+ *
+ * OPTIMIZATION: This tool uses programmatic checks instead of LLM for most validations.
+ * - Caches style guide content
+ * - Programmatic checks for: missing descriptions, invalid xrefs, DRY violations
+ * - Only style/tone review requires LLM processing
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { findRepoRoot, formatDate } = require('./utils');
+const cache = require('./cache');
+
+/**
+ * Sanitize version string to prevent path traversal
+ * @param {string} version - Version string to sanitize
+ * @returns {string} Sanitized version string
+ * @throws {Error} If version contains invalid characters
+ */
+function sanitizeVersion(version) {
+  if (!version || typeof version !== 'string') {
+    throw new Error('Version must be a non-empty string');
+  }
+
+  // Reject path separators
+  if (version.includes('/') || version.includes('\\')) {
+    throw new Error('Version cannot contain path separators (/ or \\)');
+  }
+
+  // Reject path traversal sequences
+  if (version.includes('..')) {
+    throw new Error('Version cannot contain path traversal sequences (..)');
+  }
+
+  // Reject null bytes
+  if (version.includes('\0')) {
+    throw new Error('Version cannot contain null bytes');
+  }
+
+  // Whitelist: only allow alphanumeric, dots, dashes, and underscores
+  const sanitized = version.replace(/[^a-zA-Z0-9._-]/g, '_');
+
+  // Ensure the sanitized version is not empty and not too long
+  if (sanitized.length === 0) {
+    throw new Error('Version contains only invalid characters');
+  }
+
+  if (sanitized.length > 100) {
+    throw new Error('Version string is too long (max 100 characters)');
+  }
+
+  return sanitized;
+}
+
+/**
+ * Build style review instructions for LLM-based review
+ * @param {string} docType - Type of documentation being reviewed
+ * @returns {string} Review instructions
+ */
+function buildStyleReviewInstructions(docType) {
+  const baseInstructions = `
+# Style Guide Review Instructions
+
+You are reviewing autogenerated ${docType} documentation for Redpanda.
+
+## Your Task
+
+Review the content sample below against the style guide and identify:
+
+1. **Terminology issues**
+   - Incorrect capitalization (e.g., "RedPanda" should be "Redpanda")
+   - Deprecated terms (e.g., "whitelist/blacklist" should be "allowlist/denylist")
+   - Incorrect technical terms
+
+2. **Voice and tone issues**
+   - Passive voice (should be active)
+   - Wrong tense (should be present tense)
+   - Wrong person (should be second person "you")
+
+3. **Formatting issues**
+   - Heading capitalization (should be sentence case, not title case)
+   - Overuse of bold
+   - Use of em dashes (should use parentheses or colons instead)
+
+4. **Structural issues**
+   - Incorrect heading hierarchy
+   - Missing descriptions or context
+   - Unclear explanations
+
+## Output Format
+
+For each issue found, provide:
+- Line number or section reference
+- Issue type (terminology/voice/formatting/structure)
+- Specific problem
+- Suggested fix
+
+If no issues are found in a category, state "No issues found."
+`;
+
+  return baseInstructions;
+}
+
+/**
+ * Generate an AsciiDoc report from review results
+ * @param {Object} results - Review results
+ * @param {string} outputPath - Path to save the report
+ * @returns {string} Generated report content
+ */
+function generateReviewReport(results, outputPath) {
+  const { doc_type, version, quality_score, issues, suggestions, files_analyzed } = results;
+
+  const errorIssues = issues.filter(i => i.severity === 'error');
+  const warningIssues = issues.filter(i => i.severity === 'warning');
+  const infoIssues = issues.filter(i => i.severity === 'info');
+
+  let report = `= Documentation Review Report\n\n`;
+  report += `[cols="1,3"]\n`;
+  report += `|===\n`;
+  report += `| Type | ${doc_type}\n`;
+  report += `| Version | ${version || 'N/A'}\n`;
+  report += `| Date | ${formatDate()}\n`;
+  report += `| Files Analyzed | ${files_analyzed}\n`;
+  report += `|===\n\n`;
+
+  report += `== Quality Score: ${quality_score}/100\n\n`;
+
+  // Score interpretation
+  if (quality_score >= 90) {
+    report += `[NOTE]\n====\n*Excellent* - Documentation quality is very high.\n====\n\n`;
+  } else if (quality_score >= 75) {
+    report += `[WARNING]\n====\n*Good* - Documentation quality is acceptable but has room for improvement.\n====\n\n`;
+  } else if (quality_score >= 50) {
+    report += `[WARNING]\n====\n*Fair* - Documentation needs improvement in several areas.\n====\n\n`;
+  } else {
+    report += `[CAUTION]\n====\n*Poor* - Documentation requires significant improvements.\n====\n\n`;
+  }
+
+  // Scoring breakdown with detailed calculation
+  report += `=== Scoring Breakdown\n\n`;
+  report += `*How the score is calculated:*\n\n`;
+
+  let runningScore = 100;
+  report += `. Starting score: *${runningScore}*\n`;
+
+  if (errorIssues.length > 0) {
+    const errorDeduction = errorIssues.reduce((sum, issue) => {
+      if (issue.issue.includes('enterprise license') || issue.issue.includes('cloud-specific')) return sum + 5;
+      if (issue.issue.includes('invalid xref')) return sum + 3;
+      return sum + 3;
+    }, 0);
+    runningScore -= errorDeduction;
+    report += `. Errors: ${errorIssues.length} issues × 3-5 points = -*${errorDeduction}* (now ${runningScore})\n`;
+  }
+
+  const missingDescCount = warningIssues.filter(i => i.issue === 'Missing description').length;
+  const shortDescCount = infoIssues.filter(i => i.issue.includes('Very short description')).length;
+  const exampleCount = infoIssues.filter(i => i.issue.includes('would benefit from an example')).length;
+  const otherWarningCount = warningIssues.length - missingDescCount;
+
+  if (missingDescCount > 0) {
+    const deduction = Math.min(20, missingDescCount * 2);
+    runningScore -= deduction;
+    report += `. Missing descriptions: ${missingDescCount} issues × 2 points = -*${deduction}* (capped at 20, now ${runningScore})\n`;
+  }
+
+  if (shortDescCount > 0) {
+    const deduction = Math.min(10, shortDescCount);
+    runningScore -= deduction;
+    report += `. Short descriptions: ${shortDescCount} issues × 1 point = -*${deduction}* (capped at 10, now ${runningScore})\n`;
+  }
+
+  if (exampleCount > 0) {
+    const deduction = Math.min(5, Math.floor(exampleCount / 5));
+    runningScore -= deduction;
+    report += `. Missing examples: ${exampleCount} complex properties = -*${deduction}* (1 point per 5 properties, capped at 5, now ${runningScore})\n`;
+  }
+
+  if (otherWarningCount > 0) {
+    const deduction = Math.min(otherWarningCount * 2, 10);
+    runningScore -= deduction;
+    report += `. Other warnings: ${otherWarningCount} issues × 1-2 points = -*${deduction}* (now ${runningScore})\n`;
+  }
+
+  report += `\n*Final Score: ${quality_score}/100*\n\n`;
+
+  // Summary
+  report += `== Summary\n\n`;
+  report += `* *Total Issues:* ${issues.length}\n`;
+  report += `** Errors: ${errorIssues.length}\n`;
+  report += `** Warnings: ${warningIssues.length}\n`;
+  report += `** Info: ${infoIssues.length}\n\n`;
+
+  // General suggestions
+  if (suggestions.length > 0) {
+    report += `=== Key Findings\n\n`;
+    suggestions.forEach(s => {
+      report += `* ${s}\n`;
+    });
+    report += `\n`;
+  }
+
+  // Errors (highest priority)
+  if (errorIssues.length > 0) {
+    report += `== Errors (high priority)\n\n`;
+    report += `These issues violate documentation standards and should be fixed immediately.\n\n`;
+
+    errorIssues.forEach((issue, idx) => {
+      report += `=== ${idx + 1}. ${issue.property || issue.path || 'General'}\n\n`;
+      report += `*Issue:* ${issue.issue}\n\n`;
+      if (issue.suggestion) {
+        report += `*Fix:* ${issue.suggestion}\n\n`;
+      }
+      report += `*File:* \`${issue.file}\`\n\n`;
+
+      // Add specific instructions based on issue type
+      if (issue.issue.includes('enterprise license')) {
+        report += `*Action:*\n\n`;
+        report += `. Open \`docs-data/property-overrides.json\`\n`;
+        report += `. Find property \`${issue.property}\`\n`;
+        report += `. Remove the \`include::reference:partial$enterprise-licensed-property.adoc[]\` from the description\n`;
+        report += `. Regenerate docs\n\n`;
+      } else if (issue.issue.includes('cloud-specific conditional')) {
+        report += `*Action:*\n\n`;
+        report += `. Open \`docs-data/property-overrides.json\`\n`;
+        report += `. Find property \`${issue.property}\`\n`;
+        report += `. Remove the \`ifdef::env-cloud\` blocks from the description\n`;
+        report += `. Cloud-specific info will appear in metadata automatically\n`;
+        report += `. Regenerate docs\n\n`;
+      } else if (issue.issue.includes('invalid xref')) {
+        report += `*Action:*\n\n`;
+        report += `. Open \`docs-data/property-overrides.json\`\n`;
+        report += `. Find property \`${issue.property}\`\n`;
+        report += `. Update xref links to use full Antora resource IDs\n`;
+        report += `. Example: \`xref:reference:properties/cluster-properties.adoc[Link]\`\n`;
+        report += `. Regenerate docs\n\n`;
+      } else if (issue.issue.includes('Invalid $ref')) {
+        report += `*Action:*\n\n`;
+        report += `. Open \`docs-data/overrides.json\`\n`;
+        report += `. Find the reference at \`${issue.path}\`\n`;
+        report += `. Either add the missing definition or fix the reference\n`;
+        report += `. Regenerate docs\n\n`;
+      }
+    });
+  }
+
+  // Warnings
+  if (warningIssues.length > 0) {
+    report += `== Warnings\n\n`;
+    report += `These issues should be addressed to improve documentation quality.\n\n`;
+
+    // Group warnings by issue type
+    const warningsByType = {};
+    warningIssues.forEach(issue => {
+      const issueType = issue.issue.split(':')[0] || issue.issue;
+      if (!warningsByType[issueType]) {
+        warningsByType[issueType] = [];
+      }
+      warningsByType[issueType].push(issue);
+    });
+
+    Object.entries(warningsByType).forEach(([type, typeIssues]) => {
+      report += `=== ${type} (${typeIssues.length})\n\n`;
+
+      if (type === 'Missing description') {
+        report += `*Fix:* Add descriptions to these properties in \`docs-data/property-overrides.json\`\n\n`;
+        report += `*Properties needing descriptions:*\n\n`;
+        typeIssues.forEach(issue => {
+          report += `* \`${issue.property}\`\n`;
+        });
+        report += `\n`;
+      } else {
+        typeIssues.forEach(issue => {
+          report += `* *${issue.property || issue.path}*: ${issue.issue}\n`;
+        });
+        report += `\n`;
+      }
+    });
+  }
+
+  // Info items
+  if (infoIssues.length > 0) {
+    report += `== Info\n\n`;
+    report += `These are suggestions for enhancement.\n\n`;
+
+    // Group by issue type
+    const infoByType = {};
+    infoIssues.forEach(issue => {
+      const issueType = issue.issue.split('(')[0].trim();
+      if (!infoByType[issueType]) {
+        infoByType[issueType] = [];
+      }
+      infoByType[issueType].push(issue);
+    });
+
+    Object.entries(infoByType).forEach(([type, typeIssues]) => {
+      report += `=== ${type}\n\n`;
+      typeIssues.forEach(issue => {
+        report += `* *${issue.property || issue.path}*: ${issue.issue}\n`;
+      });
+      report += `\n`;
+    });
+  }
+
+  // Next steps
+  report += `== Next Steps\n\n`;
+  if (errorIssues.length > 0) {
+    report += `. *Fix errors first* - Address the ${errorIssues.length} error(s) above\n`;
+  }
+  if (warningIssues.length > 0) {
+    report += `${errorIssues.length > 0 ? '. ' : '. '}*Review warnings* - Prioritize the ${warningIssues.length} warning(s)\n`;
+  }
+  const step = errorIssues.length > 0 && warningIssues.length > 0 ? 3 : errorIssues.length > 0 || warningIssues.length > 0 ? 2 : 1;
+  report += `${step > 1 ? '. ' : '. '}*Regenerate documentation* - After making changes, regenerate the docs\n`;
+  report += `. *Review again* - Run the review tool again to verify fixes\n\n`;
+
+  // Write report
+  fs.writeFileSync(outputPath, report, 'utf8');
+
+  return report;
+}
+
+/**
+ * Review generated documentation for quality issues
+ * @param {Object} args - Arguments
+ * @param {string} args.doc_type - Type of docs to review (properties, metrics, rpk, rpcn_connectors)
+ * @param {string} args.version - Version of the docs to review (for properties, metrics, rpk)
+ * @param {boolean} [args.generate_report] - Whether to generate a markdown report file
+ * @param {string} [args.properties_dir] - Custom path to properties directory (default: modules/reference)
+ * @param {string} [args.metrics_file] - Custom path to metrics file (default: modules/reference/pages/public-metrics-reference.adoc)
+ * @param {string} [args.rpk_dir] - Custom path to RPK docs directory (default: autogenerated/{version}/rpk)
+ * @param {string} [args.overrides_file] - Custom path to overrides.json for RPCN connectors (default: docs-data/overrides.json)
+ * @returns {Object} Review results with issues and suggestions
+ */
+function reviewGeneratedDocs(args) {
+  const repoRoot = findRepoRoot();
+  const { doc_type, version, generate_report } = args;
+
+  // Load style guide from cache or file (cache for 1 hour)
+  const styleGuidePath = path.join(repoRoot.root, 'mcp', 'team-standards', 'style-guide.md');
+  let styleGuide = null;
+
+  const cacheKey = 'style-guide-content';
+  styleGuide = cache.get(cacheKey);
+
+  if (!styleGuide && fs.existsSync(styleGuidePath)) {
+    try {
+      styleGuide = fs.readFileSync(styleGuidePath, 'utf8');
+      cache.set(cacheKey, styleGuide, 60 * 60 * 1000); // Cache for 1 hour
+    } catch (err) {
+      console.error(`Warning: Could not load style guide: ${err.message}`);
+    }
+  }
+
+  if (!doc_type) {
+    return {
+      success: false,
+      error: 'doc_type is required',
+      suggestion: 'Provide one of: properties, metrics, rpk, rpcn_connectors'
+    };
+  }
+
+  const issues = [];
+  const suggestions = [];
+  let filesAnalyzed = 0;
+  let qualityScore = 100;
+  let contentSample = ''; // For storing content samples for LLM review
+  let contentFilePath = null; // Path to full content file for deep review if needed
+  let contentTotalLines = 0; // Total lines in the content file
+
+  try {
+    switch (doc_type) {
+      case 'properties': {
+        if (!version) {
+          return {
+            success: false,
+            error: 'version is required for property docs review'
+          };
+        }
+
+        // Sanitize version to prevent path traversal
+        let sanitizedVersion;
+        try {
+          sanitizedVersion = sanitizeVersion(version);
+        } catch (err) {
+          return {
+            success: false,
+            error: `Invalid version: ${err.message}`
+          };
+        }
+
+        // Normalize version
+        let normalizedVersion = sanitizedVersion;
+        if (!normalizedVersion.startsWith('v') && normalizedVersion !== 'latest') {
+          normalizedVersion = `v${normalizedVersion}`;
+        }
+
+        // Check for generated JSON file (use custom path or default)
+        const propertiesBaseDir = args.properties_dir || path.join('modules', 'reference');
+        const jsonPath = path.join(repoRoot.root, propertiesBaseDir, 'attachments', `redpanda-properties-${normalizedVersion}.json`);
+        if (!fs.existsSync(jsonPath)) {
+          return {
+            success: false,
+            error: `Properties JSON not found at ${jsonPath}`,
+            suggestion: 'Generate property docs first using generate_property_docs tool'
+          };
+        }
+
+        filesAnalyzed++;
+
+        // Read and parse the properties JSON
+        const propertiesData = JSON.parse(fs.readFileSync(jsonPath, 'utf8'));
+        const allProperties = Object.values(propertiesData.properties || {});
+
+        // Properties that typically benefit from examples
+        const shouldHaveExample = (prop) => {
+          const name = prop.name.toLowerCase();
+          // Properties with specific formats, complex values, or commonly misconfigured
+          return name.includes('pattern') ||
+                 name.includes('regex') ||
+                 name.includes('format') ||
+                 name.includes('template') ||
+                 name.includes('config') ||
+                 name.includes('override') ||
+                 name.includes('mapping') ||
+                 name.includes('filter') ||
+                 name.includes('selector') ||
+                 (prop.type && prop.type.includes('array')) ||
+                 (prop.type && prop.type.includes('object'));
+        };
+
+        // Check for missing or short descriptions
+        let missingDescriptions = 0;
+        let shortDescriptions = 0;
+        let emptyDefaults = 0;
+        let missingExamples = 0;
+
+        allProperties.forEach(prop => {
+          if (!prop.description || prop.description.trim() === '') {
+            missingDescriptions++;
+            if (!prop.is_deprecated) {
+              issues.push({
+                severity: 'warning',
+                file: jsonPath,
+                property: prop.name,
+                issue: 'Missing description'
+              });
+            }
+          } else if (prop.description.length < 20 && !prop.is_deprecated) {
+            shortDescriptions++;
+            issues.push({
+              severity: 'info',
+              file: jsonPath,
+              property: prop.name,
+              issue: `Very short description (${prop.description.length} chars): "${prop.description}"`
+            });
+          }
+
+          if ((!prop.default || (typeof prop.default === 'string' && prop.default.trim() === '')) && !prop.is_deprecated && prop.config_scope !== 'broker') {
+            emptyDefaults++;
+          }
+
+          // Track properties that should have examples
+          if (shouldHaveExample(prop) && !prop.is_deprecated) {
+            missingExamples++;
+          }
+        });
+
+        // Check ALL properties for missing examples
+        const propertiesNeedingExamples = [];
+        const overridesPath = path.join(repoRoot.root, 'docs-data', 'property-overrides.json');
+        const overrides = fs.existsSync(overridesPath) ? JSON.parse(fs.readFileSync(overridesPath, 'utf8')) : { properties: {} };
+
+        allProperties.forEach(prop => {
+          if (shouldHaveExample(prop) && !prop.is_deprecated) {
+            const override = overrides.properties && overrides.properties[prop.name];
+            if (!override || !override.example) {
+              propertiesNeedingExamples.push(prop.name);
+            }
+          }
+        });
+
+        // Read property overrides to check for quality issues
+        if (fs.existsSync(overridesPath)) {
+          filesAnalyzed++;
+
+          if (overrides.properties) {
+            Object.entries(overrides.properties).forEach(([propName, override]) => {
+              let propData = allProperties.find(p => p.name === propName);
+
+              // Check for enterprise license includes (should not be in descriptions)
+              if (override.description && override.description.includes('include::reference:partial$enterprise-licensed-property.adoc')) {
+                issues.push({
+                  severity: 'error',
+                  file: overridesPath,
+                  property: propName,
+                  issue: 'Description contains enterprise license include (should be in metadata only)',
+                  suggestion: 'Remove the include statement from the description'
+                });
+                qualityScore -= 5;
+              }
+
+              // Check for cloud-specific conditional blocks
+              if (override.description && (override.description.includes('ifdef::env-cloud') || override.description.includes('ifndef::env-cloud'))) {
+                issues.push({
+                  severity: 'error',
+                  file: overridesPath,
+                  property: propName,
+                  issue: 'Description contains cloud-specific conditional blocks',
+                  suggestion: 'Remove cloud conditionals - this info belongs in metadata'
+                });
+                qualityScore -= 5;
+              }
+
+              // Check for deprecated properties with descriptions (should not have overrides)
+              if (!propData) propData = allProperties.find(p => p.name === propName);
+              if (propData && propData.is_deprecated && override.description) {
+                issues.push({
+                  severity: 'warning',
+                  file: overridesPath,
+                  property: propName,
+                  issue: 'Override exists for deprecated property',
+                  suggestion: 'Remove override for deprecated properties'
+                });
+                qualityScore -= 2;
+              }
+
+              // Check for invalid xref links (not using full Antora resource IDs)
+              if (override.description) {
+                const invalidXrefPattern = /xref:\.\/|xref:(?![\w-]+:)/g;
+                const invalidXrefs = override.description.match(invalidXrefPattern);
+                if (invalidXrefs) {
+                  issues.push({
+                    severity: 'error',
+                    file: overridesPath,
+                    property: propName,
+                    issue: 'Description contains invalid xref links (not using full Antora resource IDs)',
+                    suggestion: 'Use full resource IDs like xref:reference:path/to/doc.adoc[Link]'
+                  });
+                  qualityScore -= 3;
+                }
+              }
+
+              // Check for duplicate links in related_topics
+              if (override.related_topics && Array.isArray(override.related_topics)) {
+                const uniqueLinks = new Set(override.related_topics);
+                if (uniqueLinks.size < override.related_topics.length) {
+                  issues.push({
+                    severity: 'warning',
+                    file: overridesPath,
+                    property: propName,
+                    issue: 'Duplicate links in related_topics',
+                    suggestion: 'Remove duplicate links'
+                  });
+                  qualityScore -= 1;
+                }
+              }
+            });
+          }
+        }
+
+        // Add summary suggestions
+        if (missingDescriptions > 0) {
+          suggestions.push(`${missingDescriptions} properties have missing descriptions`);
+          qualityScore -= Math.min(20, missingDescriptions * 2);
+        }
+        if (shortDescriptions > 0) {
+          suggestions.push(`${shortDescriptions} properties have very short descriptions (< 20 chars)`);
+          qualityScore -= Math.min(10, shortDescriptions);
+        }
+        if (emptyDefaults > 0) {
+          suggestions.push(`${emptyDefaults} non-deprecated properties have no default value listed`);
+        }
+        if (propertiesNeedingExamples.length > 0) {
+          suggestions.push(`${propertiesNeedingExamples.length} complex properties would benefit from examples`);
+          // Add info-level issues for properties that should have examples
+          propertiesNeedingExamples.forEach(propName => {
+            issues.push({
+              severity: 'info',
+              file: overridesPath,
+              property: propName,
+              issue: 'Complex property would benefit from an example',
+              suggestion: 'Add an example array to the property override showing typical usage'
+            });
+          });
+          qualityScore -= Math.min(5, Math.floor(propertiesNeedingExamples.length / 5));
+        }
+
+        // Sample generated property docs for style review (hybrid approach)
+        const clusterPropsPath = path.join(repoRoot.root, propertiesBaseDir, 'partials', 'properties', 'cluster-properties.adoc');
+        if (fs.existsSync(clusterPropsPath)) {
+          const fullContent = fs.readFileSync(clusterPropsPath, 'utf8');
+          const lines = fullContent.split('\n');
+          // Sample first 300 lines to catch systematic issues
+          // (enough to see multiple properties and their patterns)
+          contentSample = lines.slice(0, 300).join('\n');
+          // Store file path for full review if needed
+          contentFilePath = clusterPropsPath;
+          contentTotalLines = lines.length;
+        }
+
+        break;
+      }
+
+      case 'rpcn_connectors': {
+        // Read overrides.json (use custom path or default)
+        const overridesPath = args.overrides_file ?
+          path.join(repoRoot.root, args.overrides_file) :
+          path.join(repoRoot.root, 'docs-data', 'overrides.json');
+
+        if (!fs.existsSync(overridesPath)) {
+          return {
+            success: false,
+            error: `overrides.json not found at ${overridesPath}`,
+            suggestion: 'Generate RPCN connector docs first using generate_rpcn_connector_docs tool, or specify custom path with overrides_file parameter'
+          };
+        }
+
+        filesAnalyzed++;
+        const overrides = JSON.parse(fs.readFileSync(overridesPath, 'utf8'));
+
+        // Validate $ref references
+        const definitions = overrides.definitions || {};
+        const allRefs = new Set();
+        const invalidRefs = [];
+
+        const findRefs = (obj, path = '') => {
+          if (typeof obj !== 'object' || obj === null) return;
+
+          if (obj.$ref) {
+            allRefs.add(obj.$ref);
+            // Check if ref is valid
+            const refPath = obj.$ref.replace('#/definitions/', '');
+            if (!definitions[refPath]) {
+              invalidRefs.push({
+                ref: obj.$ref,
+                path
+              });
+            }
+          }
+
+          for (const [key, value] of Object.entries(obj)) {
+            if (key !== '$ref') {
+              findRefs(value, path ? `${path}.${key}` : key);
+            }
+          }
+        };
+
+        ['inputs', 'outputs', 'processors', 'caches'].forEach(section => {
+          if (overrides[section]) {
+            findRefs(overrides[section], section);
+          }
+        });
+
+        invalidRefs.forEach(({ ref, path }) => {
+          issues.push({
+            severity: 'error',
+            file: overridesPath,
+            path,
+            issue: `Invalid $ref: ${ref}`,
+            suggestion: 'Ensure the reference exists in the definitions section'
+          });
+          qualityScore -= 5;
+        });
+
+        // Check for duplicate descriptions (DRY violations)
+        const descriptions = new Map();
+        const checkDuplicates = (obj, path = '') => {
+          if (typeof obj !== 'object' || obj === null) return;
+
+          if (obj.description && !obj.$ref && typeof obj.description === 'string' && obj.description.length > 30) {
+            const key = obj.description.trim().toLowerCase();
+            if (descriptions.has(key)) {
+              descriptions.get(key).push(path);
+            } else {
+              descriptions.set(key, [path]);
+            }
+          }
+
+          for (const [key, value] of Object.entries(obj)) {
+            checkDuplicates(value, path ? `${path}.${key}` : key);
+          }
+        };
+
+        ['inputs', 'outputs', 'processors', 'caches'].forEach(section => {
+          if (overrides[section]) {
+            checkDuplicates(overrides[section], section);
+          }
+        });
+
+        const duplicates = Array.from(descriptions.entries()).filter(([_, paths]) => paths.length > 1);
+        duplicates.forEach(([desc, paths]) => {
+          suggestions.push(`Duplicate description found at: ${paths.join(', ')}. Consider creating a definition and using $ref`);
+          qualityScore -= 3;
+        });
+
+        if (invalidRefs.length === 0 && duplicates.length === 0) {
+          suggestions.push('All $ref references are valid and DRY principles are maintained');
+        }
+
+        // Sample connector descriptions for style review
+        // Collect sample descriptions from inputs/outputs
+        const sampleDescriptions = [];
+        ['inputs', 'outputs'].forEach(section => {
+          if (overrides[section]) {
+            Object.entries(overrides[section]).slice(0, 5).forEach(([name, config]) => {
+              if (config.description) {
+                sampleDescriptions.push(`\n== ${name} (${section})\n\n${config.description}`);
+              }
+            });
+          }
+        });
+
+        if (sampleDescriptions.length > 0) {
+          contentSample = `= RPCN Connector Descriptions Sample\n${sampleDescriptions.join('\n\n')}`;
+        }
+
+        break;
+      }
+
+      case 'metrics':
+      case 'rpk': {
+        // For metrics and RPK, check files exist and sample content for style review
+        if (!version) {
+          return {
+            success: false,
+            error: 'version is required for metrics/rpk docs review'
+          };
+        }
+
+        // Sanitize version to prevent path traversal
+        let sanitizedVersion;
+        try {
+          sanitizedVersion = sanitizeVersion(version);
+        } catch (err) {
+          return {
+            success: false,
+            error: `Invalid version: ${err.message}`
+          };
+        }
+
+        let filePath;
+
+        if (doc_type === 'metrics') {
+          // Use custom path or default
+          filePath = args.metrics_file ?
+            path.join(repoRoot.root, args.metrics_file) :
+            path.join(repoRoot.root, 'modules', 'reference', 'pages', 'public-metrics-reference.adoc');
+
+          if (!fs.existsSync(filePath)) {
+            return {
+              success: false,
+              error: `Generated docs not found at ${filePath}`,
+              suggestion: 'Generate metrics docs first using generate_metrics_docs tool, or specify custom path with metrics_file parameter'
+            };
+          }
+
+          // Read first 300 lines as sample for style review (hybrid approach)
+          const fullContent = fs.readFileSync(filePath, 'utf8');
+          const lines = fullContent.split('\n');
+          contentSample = lines.slice(0, 300).join('\n');
+          contentFilePath = filePath;
+          contentTotalLines = lines.length;
+
+        } else {
+          // RPK files are version-specific
+          const normalizedVersion = sanitizedVersion.startsWith('v') ? sanitizedVersion : `v${sanitizedVersion}`;
+          // Use custom path or default
+          const rpkDir = args.rpk_dir ?
+            path.join(repoRoot.root, args.rpk_dir) :
+            path.join(repoRoot.root, 'autogenerated', normalizedVersion, 'rpk');
+
+          if (!fs.existsSync(rpkDir)) {
+            return {
+              success: false,
+              error: `RPK docs directory not found at ${rpkDir}`,
+              suggestion: 'Generate RPK docs first using generate_rpk_docs tool, or specify custom path with rpk_dir parameter'
+            };
+          }
+          filePath = rpkDir;
+
+          // Sample 3 command files for review (hybrid approach)
+          const rpkFiles = fs.readdirSync(rpkDir).filter(f => f.endsWith('.adoc'));
+          if (rpkFiles.length > 0) {
+            const samplesToRead = Math.min(3, rpkFiles.length);
+            const samples = [];
+            for (let i = 0; i < samplesToRead; i++) {
+              const sampleFile = path.join(rpkDir, rpkFiles[i]);
+              const content = fs.readFileSync(sampleFile, 'utf8');
+              samples.push(`\n// File: ${rpkFiles[i]}\n${content}`);
+            }
+            contentSample = samples.join('\n\n---\n\n');
+            contentFilePath = rpkDir;
+            contentTotalLines = rpkFiles.length; // Total number of command files
+          }
+        }
+
+        filesAnalyzed++;
+        suggestions.push(`${doc_type} documentation generated successfully`);
+
+        break;
+      }
+
+      default:
+        return {
+          success: false,
+          error: `Unknown doc_type: ${doc_type}`,
+          suggestion: 'Use one of: properties, metrics, rpk, rpcn_connectors'
+        };
+    }
+
+    // Ensure quality score doesn't go below 0
+    qualityScore = Math.max(0, qualityScore);
+
+    const results = {
+      success: true,
+      doc_type,
+      version: version || 'N/A',
+      files_analyzed: filesAnalyzed,
+      issues,
+      quality_score: qualityScore,
+      suggestions,
+      summary: `Reviewed ${doc_type} documentation. Quality score: ${qualityScore}/100. Found ${issues.length} issues.`,
+      style_guide_loaded: styleGuide !== null,
+      style_guide: styleGuide,
+      // Hybrid review approach: sample for quick check, full content path if deeper review needed
+      content_sample: contentSample || null,
+      content_file_path: contentFilePath,
+      content_total_lines: contentTotalLines || null,
+      content_sample_info: contentSample ?
+        (doc_type === 'rpk' ?
+          `Sample includes ${Math.min(3, contentTotalLines)} of ${contentTotalLines} command files` :
+          `Sample includes first 300 of ${contentTotalLines} lines`) : null,
+      // Instructions for LLM-based review
+      review_instructions: styleGuide && contentSample ? buildStyleReviewInstructions(doc_type) : null,
+      additional_review_needed: styleGuide && contentSample ?
+        'IMPORTANT: HYBRID REVIEW APPROACH\n\n' +
+        '1. First, review the content sample below against the style guide:\n' +
+        '   - Terminology compliance (correct capitalization, approved terms)\n' +
+        '   - Voice and tone (active voice, present tense, second person)\n' +
+        '   - Formatting (heading capitalization, bold usage, em dashes)\n' +
+        '   - Clarity and readability\n\n' +
+        '2. If you find style issues in the sample:\n' +
+        '   - Report the issues found in the sample\n' +
+        '   - Use the Read tool on content_file_path to review more content\n' +
+        '   - Look for patterns that indicate systematic problems\n\n' +
+        '3. If no issues found in sample, the docs are likely good throughout.' :
+        styleGuide ?
+        'IMPORTANT: The programmatic review above checks for technical quality issues (missing descriptions, invalid xrefs, etc.). You should ALSO review the generated content against the style guide below for terminology, tone, and formatting compliance.' :
+        'Note: Style guide not available for additional review.'
+    };
+
+    // Generate AsciiDoc report if requested
+    if (generate_report) {
+      // Sanitize version for filename if provided
+      let safeVersion = '';
+      if (version) {
+        try {
+          safeVersion = `-${sanitizeVersion(version)}`;
+        } catch (err) {
+          // If version sanitization fails, skip it in filename
+          safeVersion = '';
+        }
+      }
+      const reportFilename = `review-${doc_type}${safeVersion}-${formatDate()}.adoc`;
+      const reportPath = path.join(repoRoot.root, reportFilename);
+      generateReviewReport(results, reportPath);
+      results.report_path = reportPath;
+      results.report_generated = true;
+    }
+
+    return results;
+
+  } catch (err) {
+    return {
+      success: false,
+      error: err.message,
+      suggestion: 'Check that the documentation has been generated and files exist'
+    };
+  }
+}
+
+module.exports = {
+  generateReviewReport,
+  reviewGeneratedDocs
+};