documcp

Instructions

Implementation Reference

• src/tools/validate-content.ts:1661-1698 (schema)

  Tool definition with input schema for parameters: contentPath (required), analysisId, validationType, includeCodeValidation, confidence.

  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:1751-1820 (handler)

  Primary handler function that executes the tool. Instantiates ContentAccuracyValidator, calls validateContent with timeout protection, handles errors, 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:120-237 (handler)

  Core validation orchestration method in ContentAccuracyValidator class. Performs accuracy, completeness, compliance (including Diataxis), and code validation; calculates confidence metrics; generates recommendations.

  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:580-594 (helper)

  Diataxis-specific compliance validation: checks markdown files against Diataxis section rules (tutorials, how-to, reference, explanation).

  private async validateDiataxisCompliance(
    contentPath: string,
    result: ValidationResult,
  ): Promise<void> {
    const files = await this.getMarkdownFiles(contentPath);
  
    for (const file of files) {
      const content = await fs.readFile(file, "utf-8");
      const section = this.identifyDiataxisSection(file);
  
      if (section) {
        await this.checkSectionCompliance(file, content, section, result);
      }
    }
  }

• src/tools/validate-content.ts:1661-1698 (registration)

  Export of the Tool object which serves as the registration point for the MCP tool.

  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"],
    },
  };