documcp

Instructions

Implementation Reference

• src/tools/validate-content.ts:1568-1605 (registration)

  Tool definition and registration for validate_diataxis_content (referred to as validate_content in other tools)
  export const validateDiataxisContent: Tool = { name: "validate_diataxis_content", description: "Validate the accuracy, completeness, and compliance of generated Diataxis documentation", inputSchema: { type: "object", properties: { contentPath: { type: "string", description: "Path to the documentation directory to validate", }, analysisId: { type: "string", description: "Optional repository analysis ID for context-aware validation", }, validationType: { type: "string", enum: ["accuracy", "completeness", "compliance", "all"], default: "all", description: "Type of validation to perform", }, includeCodeValidation: { type: "boolean", default: true, description: "Whether to validate code examples for correctness", }, confidence: { type: "string", enum: ["strict", "moderate", "permissive"], default: "moderate", description: "Validation confidence level - stricter levels catch more issues", }, }, required: ["contentPath"], }, };
• src/tools/validate-content.ts:1572-1604 (schema)

  Input schema defining parameters for content validation: contentPath (required), analysisId, validationType, includeCodeValidation, confidence
  inputSchema: { type: "object", properties: { contentPath: { type: "string", description: "Path to the documentation directory to validate", }, analysisId: { type: "string", description: "Optional repository analysis ID for context-aware validation", }, validationType: { type: "string", enum: ["accuracy", "completeness", "compliance", "all"], default: "all", description: "Type of validation to perform", }, includeCodeValidation: { type: "boolean", default: true, description: "Whether to validate code examples for correctness", }, confidence: { type: "string", enum: ["strict", "moderate", "permissive"], default: "moderate", description: "Validation confidence level - stricter levels catch more issues", }, }, required: ["contentPath"], },
• src/tools/validate-content.ts:1658-1727 (handler)

  Primary handler function for the validation tool. Instantiates ContentAccuracyValidator, handles timeout, progress reporting, and returns ValidationResult.
  export async function handleValidateDiataxisContent( args: any, context?: any, ): Promise<ValidationResult> { await context?.info?.("🔍 Starting Diataxis content validation..."); const validator = new ContentAccuracyValidator(); // Add timeout protection to prevent infinite hangs const timeoutMs = 120000; // 2 minutes let timeoutHandle: NodeJS.Timeout; const timeoutPromise = new Promise<ValidationResult>((_, reject) => { timeoutHandle = setTimeout(() => { reject( new Error( `Validation timed out after ${ timeoutMs / 1000 } seconds. This may be due to a large directory structure. Try validating a smaller subset or specific directory.`, ), ); }, timeoutMs); }); const validationPromise = validator.validateContent(args, context); try { const result = await Promise.race([validationPromise, timeoutPromise]); clearTimeout(timeoutHandle!); return result; } catch (error: any) { clearTimeout(timeoutHandle!); // Return a partial result with error information return { success: false, confidence: { overall: 0, breakdown: { technologyDetection: 0, frameworkVersionAccuracy: 0, codeExampleRelevance: 0, architecturalAssumptions: 0, businessContextAlignment: 0, }, riskFactors: [ { type: "high", category: "validation", description: "Validation process failed or timed out", impact: "Unable to complete content validation", mitigation: "Try validating a smaller directory or specific subset of files", }, ], }, issues: [], uncertainties: [], recommendations: [ "Validation failed or timed out", "Consider validating smaller directory subsets", "Check for very large files or deep directory structures", `Error: ${error.message}`, ], nextSteps: [ "Verify the content path is correct and accessible", "Try validating specific subdirectories instead of the entire project", "Check for circular symlinks or very deep directory structures", ], }; } }
• src/tools/validate-content.ts:100-217 (handler)

  Core validation logic implementing accuracy, completeness, compliance checks, code validation, confidence scoring, and recommendations generation.
  async validateContent( options: ValidationOptions, context?: any, ): Promise<ValidationResult> { if (context?.meta?.progressToken) { await context.meta.reportProgress?.({ progress: 0, total: 100 }); } const result: ValidationResult = { success: false, confidence: this.initializeConfidenceMetrics(), issues: [], uncertainties: [], recommendations: [], nextSteps: [], }; // Load project context if analysis ID provided if (options.analysisId) { await context?.info?.("📊 Loading project context..."); this.projectContext = await this.loadProjectContext(options.analysisId); } if (context?.meta?.progressToken) { await context.meta.reportProgress?.({ progress: 20, total: 100 }); } // Determine if we should analyze application code vs documentation await context?.info?.("🔎 Analyzing content type..."); const isApplicationValidation = await this.shouldAnalyzeApplicationCode( options.contentPath, ); if (context?.meta?.progressToken) { await context.meta.reportProgress?.({ progress: 40, total: 100 }); } // Perform different types of validation based on request if ( options.validationType === "all" || options.validationType === "accuracy" ) { await this.validateAccuracy(options.contentPath, result); } if ( options.validationType === "all" || options.validationType === "completeness" ) { await this.validateCompleteness(options.contentPath, result); } if ( options.validationType === "all" || options.validationType === "compliance" ) { if (isApplicationValidation) { await this.validateApplicationStructureCompliance( options.contentPath, result, ); } else { await this.validateDiataxisCompliance(options.contentPath, result); } } // Code validation if requested if (options.includeCodeValidation) { result.codeValidation = await this.validateCodeExamples( options.contentPath, ); // Set code example relevance confidence based on code validation results if (result.codeValidation) { const successRate = result.codeValidation.exampleResults.length > 0 ? result.codeValidation.exampleResults.filter( (e) => e.compilationSuccess, ).length / result.codeValidation.exampleResults.length : 1; result.confidence.breakdown.codeExampleRelevance = Math.round( successRate * 100, ); } } else { // If code validation is skipped, assume reasonable confidence result.confidence.breakdown.codeExampleRelevance = 75; } // Set framework version accuracy based on technology detection confidence result.confidence.breakdown.frameworkVersionAccuracy = Math.min( 90, result.confidence.breakdown.technologyDetection + 10, ); // Set architectural assumptions confidence based on file structure and content analysis const filesAnalyzed = await this.getMarkdownFiles(options.contentPath); const hasStructuredContent = filesAnalyzed.length > 3; // Basic heuristic result.confidence.breakdown.architecturalAssumptions = hasStructuredContent ? 80 : 60; // Calculate overall confidence and success this.calculateOverallMetrics(result); // Generate recommendations and next steps this.generateRecommendations(result, options); if (context?.meta?.progressToken) { await context.meta.reportProgress?.({ progress: 100, total: 100 }); } const status = result.success ? "PASSED" : "ISSUES FOUND"; await context?.info?.( `✅ Validation complete! Status: ${status} (${result.confidence.overall}% confidence, ${result.issues.length} issue(s))`, ); return result; }
• src/tools/validate-content.ts:1739-1867 (helper)

  Alternative general content validation function for links and basic code checks, potentially corresponding to simpler "validate_content" usage.
  export async function validateGeneralContent( args: any, ): Promise<GeneralValidationResult> { const { contentPath, validationType = "all", includeCodeValidation = true, followExternalLinks = false, } = args; const result: GeneralValidationResult = { success: true, linksChecked: 0, brokenLinks: [], codeBlocksValidated: 0, codeErrors: [], recommendations: [], summary: "", }; try { // Get all markdown files const validator = new ContentAccuracyValidator(); const files = await validator.getMarkdownFiles(contentPath); // Check links if requested if (validationType === "all" || validationType === "links") { for (const file of files) { const content = await fs.readFile(file, "utf-8"); const links = extractLinksFromMarkdown(content); for (const link of links) { result.linksChecked++; // Skip external links unless explicitly requested if (link.startsWith("http") && !followExternalLinks) continue; // Check internal links if (!link.startsWith("http")) { const fullPath = path.resolve(path.dirname(file), link); try { await fs.access(fullPath); } catch { result.brokenLinks.push(`${path.basename(file)}: ${link}`); result.success = false; } } } } } // Validate code blocks if requested if ( includeCodeValidation && (validationType === "all" || validationType === "code") ) { for (const file of files) { const content = await fs.readFile(file, "utf-8"); const codeBlocks = extractCodeBlocks(content); for (const block of codeBlocks) { result.codeBlocksValidated++; // Basic syntax validation if (block.language && block.code.trim()) { if (block.language === "javascript" || block.language === "js") { try { // Basic JS syntax check - look for common issues if ( block.code.includes("console.log") && !block.code.includes(";") ) { result.codeErrors.push( `${path.basename(file)}: Missing semicolon in JS code`, ); } } catch (error) { result.codeErrors.push( `${path.basename(file)}: JS syntax error - ${error}`, ); result.success = false; } } } } } } // Generate recommendations if (result.brokenLinks.length > 0) { result.recommendations.push( `Fix ${result.brokenLinks.length} broken internal links`, ); result.recommendations.push( "Run documentation build to catch additional link issues", ); } if (result.codeErrors.length > 0) { result.recommendations.push( `Review and fix ${result.codeErrors.length} code syntax issues`, ); } if (result.success) { result.recommendations.push( "Content validation passed - no critical issues found", ); } // Create summary result.summary = `Validated ${files.length} files, ${ result.linksChecked } links, ${result.codeBlocksValidated} code blocks. ${ result.success ? "PASSED" : `ISSUES FOUND: ${ result.brokenLinks.length + result.codeErrors.length }` }`; return result; } catch (error) { result.success = false; result.recommendations.push(`Validation failed: ${error}`); result.summary = `Validation error: ${error}`; return result; } }