documcp

Instructions

Implementation Reference

• src/tools/detect-gaps.ts:65-225 (handler)

  Primary handler function for the detect_documentation_gaps tool. Orchestrates analysis from multiple sources (analyzeRepository, CodeScanner, validateDiataxisContent) to detect gaps in documentation structure, content coverage, API endpoints, classes, functions, and framework-specific docs.
  export async function detectDocumentationGaps( args: unknown, ): Promise<{ content: any[] }> { const startTime = Date.now(); const { repositoryPath, documentationPath, analysisId: existingAnalysisId, depth, } = inputSchema.parse(args); try { // Step 1: Get or perform repository analysis let analysisId = existingAnalysisId; let repositoryAnalysis: any; if (!analysisId) { const analysisResult = await analyzeRepository({ path: repositoryPath, depth, }); if (analysisResult.content && analysisResult.content[0]) { // The analyze_repository tool returns the analysis data directly as JSON text repositoryAnalysis = JSON.parse(analysisResult.content[0].text); // Check if the analysis was successful if (repositoryAnalysis.success === false) { throw new Error("Repository analysis failed"); } analysisId = repositoryAnalysis.id; // Use the 'id' field from the analysis } else { throw new Error("Repository analysis failed - no content returned"); } } else { // Try to retrieve existing analysis (simplified for this implementation) // In a full implementation, this would retrieve from persistent storage } // Step 2: Perform deep code analysis const codeScanner = new CodeScanner(repositoryPath); const codeAnalysis = await codeScanner.analyzeRepository(); // Step 3: Analyze existing documentation structure const documentationAnalysis = await analyzeExistingDocumentation( documentationPath || path.join(repositoryPath, "docs"), ); // Step 4: Perform content validation if documentation exists let validationResult: any = null; if (documentationAnalysis.exists && documentationPath) { try { const validation = await handleValidateDiataxisContent({ contentPath: documentationPath, analysisId: analysisId, validationType: "all", includeCodeValidation: true, confidence: "moderate", }); if ( validation && (validation as any).content && (validation as any).content[0] ) { const validationData = JSON.parse( (validation as any).content[0].text, ); if (validationData.success) { validationResult = validationData.data; } } } catch (error) { // Validation errors are non-fatal - continue without validation data console.warn( "Content validation failed, continuing without validation data:", error, ); } } // Step 5: Identify gaps based on project and code analysis const gaps = identifyDocumentationGaps( repositoryAnalysis, documentationAnalysis, validationResult, codeAnalysis, ); // Step 6: Generate recommendations const recommendations = generateRecommendations( gaps, repositoryAnalysis, codeAnalysis, ); // Step 7: Calculate coverage scores const contentCoverage = calculateContentCoverage( documentationAnalysis, gaps, ); const gapAnalysis: GapAnalysisResult = { repositoryPath, documentationPath, analysisId: analysisId || "unknown", overallScore: calculateOverallScore(gaps, contentCoverage), gaps, strengths: identifyStrengths(documentationAnalysis, validationResult), recommendations, missingStructure: identifyMissingStructure(documentationAnalysis), contentCoverage, }; const response: MCPToolResponse<typeof gapAnalysis> = { success: true, data: gapAnalysis, metadata: { toolVersion: "1.0.0", executionTime: Date.now() - startTime, timestamp: new Date().toISOString(), }, recommendations: [ { type: gapAnalysis.overallScore < 60 ? "critical" : gapAnalysis.overallScore < 80 ? "warning" : "info", title: "Documentation Gap Analysis Complete", description: `Found ${gaps.length} gaps. Overall documentation score: ${gapAnalysis.overallScore}%`, }, ], nextSteps: recommendations.immediate.map((rec) => ({ action: rec, toolRequired: getRecommendedTool(rec), description: rec, priority: "high" as const, })), }; return formatMCPResponse(response); } catch (error) { const errorResponse: MCPToolResponse = { success: false, error: { code: "GAP_DETECTION_FAILED", message: `Failed to detect documentation gaps: ${error}`, resolution: "Ensure repository and documentation paths are accessible", }, metadata: { toolVersion: "1.0.0", executionTime: Date.now() - startTime, timestamp: new Date().toISOString(), }, }; return formatMCPResponse(errorResponse); } }
• src/tools/detect-gaps.ts:9-23 (schema)

  Zod input schema defining parameters for the tool: repositoryPath (required), documentationPath (optional), analysisId (optional), depth (enum with default).
  const inputSchema = z.object({ repositoryPath: z.string().describe("Path to the repository to analyze"), documentationPath: z .string() .optional() .describe("Path to existing documentation (if any)"), analysisId: z .string() .optional() .describe("Optional existing analysis ID to reuse"), depth: z .enum(["quick", "standard", "comprehensive"]) .optional() .default("standard"), });
• src/tools/detect-gaps.ts:281-529 (helper)

  Key helper function that implements the gap detection logic based on code analysis, documentation structure, and validation results. Identifies missing sections, undocumented code elements, and framework-specific gaps.
  function identifyDocumentationGaps( repoAnalysis: any, docsAnalysis: any, validationResult: any, codeAnalysis: CodeAnalysisResult, ): DocumentationGap[] { const gaps: DocumentationGap[] = []; // Check for missing Diataxis structure if (!docsAnalysis.exists) { gaps.push({ category: "general", gapType: "missing_section", description: "No documentation directory found", priority: "critical", recommendation: "Create documentation structure using setup_structure tool", estimatedEffort: "moderate", }); return gaps; // If no docs exist, return early } const diataxisCategories = [ "tutorials", "how-to", "reference", "explanation", ]; for (const category of diataxisCategories) { if (!docsAnalysis.structure[category]?.exists) { gaps.push({ category: category as any, gapType: "missing_section", description: `Missing ${category} documentation section`, priority: category === "tutorials" || category === "reference" ? "high" : "medium", recommendation: `Create ${category} directory and add relevant content`, estimatedEffort: "moderate", }); } else if (docsAnalysis.structure[category].files.length === 0) { gaps.push({ category: category as any, gapType: "incomplete_content", description: `${category} section exists but has no content`, priority: "high", recommendation: `Add content to ${category} section using populate_diataxis_content tool`, estimatedEffort: "substantial", }); } } // Code-based gaps using actual code analysis // Check for API documentation gaps based on actual endpoints found if ( codeAnalysis.apiEndpoints.length > 0 && !hasApiDocumentation(docsAnalysis) ) { gaps.push({ category: "reference", gapType: "missing_section", description: `Found ${codeAnalysis.apiEndpoints.length} API endpoints but no API documentation`, priority: "critical", recommendation: "Create API reference documentation for discovered endpoints", estimatedEffort: "substantial", relatedFiles: [ ...new Set(codeAnalysis.apiEndpoints.map((ep) => ep.filePath)), ], }); } // Check for undocumented API endpoints const undocumentedEndpoints = codeAnalysis.apiEndpoints.filter( (ep) => !ep.hasDocumentation, ); if (undocumentedEndpoints.length > 0) { gaps.push({ category: "reference", gapType: "missing_examples", description: `${undocumentedEndpoints.length} API endpoints lack inline documentation`, priority: "high", recommendation: "Add JSDoc comments to API endpoint handlers", estimatedEffort: "moderate", relatedFiles: [ ...new Set(undocumentedEndpoints.map((ep) => ep.filePath)), ], }); } // Check for class/interface documentation const undocumentedClasses = codeAnalysis.classes.filter( (cls) => cls.exported && !cls.hasJSDoc, ); if (undocumentedClasses.length > 0) { gaps.push({ category: "reference", gapType: "incomplete_content", description: `${undocumentedClasses.length} exported classes lack documentation`, priority: "medium", recommendation: "Add JSDoc comments to exported classes and create API reference", estimatedEffort: "moderate", relatedFiles: [ ...new Set(undocumentedClasses.map((cls) => cls.filePath)), ], }); } // Check for interface documentation const undocumentedInterfaces = codeAnalysis.interfaces.filter( (iface) => iface.exported && !iface.hasJSDoc, ); if (undocumentedInterfaces.length > 0) { gaps.push({ category: "reference", gapType: "incomplete_content", description: `${undocumentedInterfaces.length} exported interfaces lack documentation`, priority: "medium", recommendation: "Add JSDoc comments to exported interfaces and create type documentation", estimatedEffort: "moderate", relatedFiles: [ ...new Set(undocumentedInterfaces.map((iface) => iface.filePath)), ], }); } // Check for function documentation const undocumentedFunctions = codeAnalysis.functions.filter( (func) => func.exported && !func.hasJSDoc, ); if (undocumentedFunctions.length > 0) { gaps.push({ category: "reference", gapType: "incomplete_content", description: `${undocumentedFunctions.length} exported functions lack documentation`, priority: "medium", recommendation: "Add JSDoc comments to exported functions and create API reference", estimatedEffort: "substantial", relatedFiles: [ ...new Set(undocumentedFunctions.map((func) => func.filePath)), ], }); } // Framework-specific documentation gaps if ( codeAnalysis.frameworks.includes("React") && !hasFrameworkDocumentation(docsAnalysis, "react") ) { gaps.push({ category: "how-to", gapType: "missing_section", description: "React framework detected but no React-specific documentation found", priority: "medium", recommendation: "Create React component usage and development guides", estimatedEffort: "moderate", }); } if ( codeAnalysis.frameworks.includes("Express") && !hasFrameworkDocumentation(docsAnalysis, "express") ) { gaps.push({ category: "how-to", gapType: "missing_section", description: "Express framework detected but no Express-specific documentation found", priority: "medium", recommendation: "Create Express server setup and API development guides", estimatedEffort: "moderate", }); } // Test documentation gaps if (codeAnalysis.hasTests && !hasTestingDocumentation(docsAnalysis)) { gaps.push({ category: "how-to", gapType: "missing_section", description: "Test files found but no testing documentation", priority: "medium", recommendation: "Create testing setup and contribution guides", estimatedEffort: "moderate", relatedFiles: codeAnalysis.testFiles, }); } // Technology-specific gaps based on repository analysis (fallback) if (repoAnalysis) { // Check for setup/installation guides if (repoAnalysis.packageManager && !hasInstallationGuide(docsAnalysis)) { gaps.push({ category: "tutorials", gapType: "missing_section", description: "Package manager detected but no installation guide found", priority: "high", recommendation: "Create installation and setup tutorial", estimatedEffort: "moderate", }); } // Check for Docker documentation if (repoAnalysis.hasDocker && !hasDockerDocumentation(docsAnalysis)) { gaps.push({ category: "how-to", gapType: "missing_section", description: "Docker configuration found but no Docker documentation", priority: "medium", recommendation: "Add Docker deployment and development guides", estimatedEffort: "moderate", }); } // Check for CI/CD documentation if (repoAnalysis.hasCICD && !hasCICDDocumentation(docsAnalysis)) { gaps.push({ category: "explanation", gapType: "missing_section", description: "CI/CD configuration found but no related documentation", priority: "medium", recommendation: "Document CI/CD processes and deployment workflows", estimatedEffort: "moderate", }); } } // Add validation-based gaps if (validationResult?.validationResults) { for (const result of validationResult.validationResults) { if (result.status === "fail") { gaps.push({ category: "general", gapType: "poor_structure", description: result.message, priority: "medium", recommendation: result.recommendation || "Fix validation issue", estimatedEffort: "minimal", }); } } } return gaps; }