documcp

Instructions

Implementation Reference

• src/tools/validate-content.ts:1751-1820 (handler)

  Main execution handler for the validate_content tool. Creates ContentAccuracyValidator instance and orchestrates the validation process with timeout protection and progress reporting.

  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:1661-1698 (schema)

  Tool schema definition and registration export. Defines input parameters for content validation. Referenced as 'validate_content' in other tools' prompts.

  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:96-237 (helper)

  Core ContentAccuracyValidator class with validateContent method implementing the validation logic: accuracy checks, completeness analysis, Diataxis compliance, code example validation, confidence scoring, and recommendations.

  class ContentAccuracyValidator {
    private projectContext: any;
    private tempDir: string;
    private executionSimulator: ExecutionSimulator | null = null;
    private useExecutionSimulation: boolean;
  
    constructor(useExecutionSimulation: boolean = true) {
      this.tempDir = path.join(currentDir, ".tmp");
      this.useExecutionSimulation = useExecutionSimulation;
  
      // Initialize execution simulator if enabled
      if (useExecutionSimulation) {
        this.executionSimulator = createExecutionSimulator({
          maxDepth: 5,
          maxSteps: 50,
          timeoutMs: 15000,
          detectNullRefs: true,
          detectTypeMismatches: true,
          detectUnreachableCode: true,
          confidenceThreshold: 0.6,
        });
      }
    }
  
    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/generate-technical-writer-prompts.ts:421-1698 (helper)

  References to "validate_content" tool in relatedTools arrays and nextSteps, confirming usage as validate_content tool name in workflows.

            "validate_content",
            "setup_structure",
          ],
        });
      }
    }
  
    // Style improvement prompts based on health scores
    if (
      promptTypes.includes("style_improvement") &&
      documentationContext.readmeHealth &&
      documentationContext.readmeHealth < 80
    ) {
      prompts.push({
        id: "style-improvement-prompt",
        title: "Documentation Style Enhancement",
        category: "style_improvement",
        audience,
        priority: "medium",
        prompt: `Improve the writing style and clarity of existing documentation. Focus on ${audience} readability, consistent tone, and professional presentation.`,
        context: `Current README health score: ${documentationContext.readmeHealth}/100`,
        expectedOutput:
          "Refined documentation with improved clarity, consistency, and professional tone",
        integrationHints: [
          "Use evaluate_readme_health metrics for focus areas",
          "Apply readme_best_practices guidelines",
          "Validate improvements with content validation",
        ],
        relatedTools: [
          "evaluate_readme_health",
          "readme_best_practices",
          "validate_content",
        ],
      });
    }
  
    // Advanced integration prompts for comprehensive level
    if (integrationLevel === "comprehensive" || integrationLevel === "advanced") {
      prompts.push({
        id: "deployment-docs-prompt",
        title: "Deployment Documentation",
        category: "deployment_optimization",
        audience,
        priority: "medium",
        prompt: `Create deployment documentation that integrates with the recommended static site generator and deployment workflow. Include environment setup, build process, and troubleshooting.`,
        context: `Project has CI: ${projectContext.hasCI}, Package manager: ${projectContext.packageManager}`,
        expectedOutput:
          "Complete deployment guide with step-by-step instructions and troubleshooting",
        integrationHints: [
          "Use recommend_ssg output for deployment strategy",
          "Reference deploy_pages workflow",
          "Include verify_deployment checklist",
        ],
        relatedTools: [
          "recommend_ssg",
          "deploy_pages",
          "verify_deployment",
          "test_local_deployment",
        ],
      });
    }
  
    return prompts;
  }
  
  /**
   * Generate integration recommendations based on cross-tool insights
   */
  function generateIntegrationRecommendations(
    projectContext: ProjectContext,
    documentationContext: DocumentationContext,
    _prompts: TechnicalWriterPrompt[],
  ): string[] {
    const recommendations: string[] = [];
  
    recommendations.push(
      "Run analyze_repository first to establish comprehensive project context",
    );
  
    if (!documentationContext.readmeExists) {
      recommendations.push(
        "Use generate_readme_template to create initial README structure",
      );
    }
  
    if (documentationContext.documentationGaps.length > 0) {
      recommendations.push(
        "Execute detect_documentation_gaps to identify all missing content areas",
      );
    }
  
    if (projectContext.hasTests) {
      recommendations.push(
        "Include testing documentation using repository analysis insights",
      );
    }
  
    if (projectContext.hasCI) {
      recommendations.push(
        "Document CI/CD workflow using deployment tool integration",
      );
    }
  
    recommendations.push(
      "Validate all generated content using validate_content tool",
    );
    recommendations.push(
      "Check documentation links with check_documentation_links after content creation",
    );
  
    return recommendations;
  }
  
  /**
   * Generate next steps based on prompts and integration level
   */
  function generateNextSteps(
    prompts: TechnicalWriterPrompt[],
    integrationLevel: string,
  ): NextStep[] {
    const steps: NextStep[] = [];
  
    steps.push({
      action:
        "Execute high-priority prompts first to address critical documentation gaps",
      toolRequired: "generate_technical_writer_prompts",
      priority: "high",
    });
  
    steps.push({
      action: "Use generated prompts with AI writing tools for content creation",
      toolRequired: "optimize_readme",
      priority: "high",
    });
  
    steps.push({
      action: "Validate generated content using DocuMCP validation tools",
      toolRequired: "validate_content",
      priority: "medium",
    });
  
    if (integrationLevel === "comprehensive" || integrationLevel === "advanced") {
      steps.push({
        action: "Run full documentation workflow using integrated tool chain",
        toolRequired: "analyze_repository",
        priority: "medium",
      });
  
      steps.push({
        action: "Test documentation with target audience using deployment tools",
        toolRequired: "test_local_deployment",
        priority: "low",
      });
    }
  
    steps.push({
      action:
        "Iterate on content based on validation feedback and best practices analysis",
      toolRequired: "readme_best_practices",
      priority: "low",
    });
  
    return steps;
  }
  
  /**
   * Helper functions
   */
  async function fileExists(path: string): Promise<boolean> {
    try {
      await fs.access(path);
      return true;
    } catch {
      return false;
    }
  }
  
  async function hasTestFiles(projectPath: string): Promise<boolean> {
    try {
      const files = await fs.readdir(projectPath, { recursive: true });
      return files.some(
        (file) =>
          typeof file === "string" &&
          (file.includes("test") ||
            file.includes("spec") ||
            file.endsWith(".test.js") ||
            file.endsWith(".spec.js")),
      );
    } catch {
      return false;
    }
  }
  
  async function hasCIConfig(projectPath: string): Promise<boolean> {
    const ciFiles = [
      ".github/workflows",
      ".gitlab-ci.yml",
      "circle.yml",
      ".travis.yml",
    ];
  
    for (const ciFile of ciFiles) {
      if (await fileExists(join(projectPath, ciFile))) {
        return true;
      }
    }
  
    return false;
  }
  
  function categorizePrompts(
    prompts: TechnicalWriterPrompt[],
  ): Record<string, number> {
    const categories: Record<string, number> = {};
  
    for (const prompt of prompts) {
      categories[prompt.category] = (categories[prompt.category] || 0) + 1;
    }
  
    return categories;
  }
  
  function calculateConfidenceScore(
    projectContext: ProjectContext,
    documentationContext: DocumentationContext,
  ): number {
    let score = 50; // Base score
  
    // Increase confidence based on available context
    if (projectContext.projectType !== "unknown") score += 20;
    if (projectContext.languages.length > 0) score += 15;
    if (projectContext.frameworks.length > 0) score += 10;
    if (documentationContext.readmeExists) score += 5;
  
    return Math.min(score, 100);
  }