documcp

Instructions

Implementation Reference

• src/tools/validate-documentation-freshness.ts:163-358 (handler)

  The core handler function that performs documentation freshness validation. It processes markdown files in the docs path, initializes missing freshness metadata, optionally updates existing metadata, integrates with git for commit tracking, generates a formatted report, and stores the validation event in the knowledge graph.

  export async function validateDocumentationFreshness(
    input: ValidateDocumentationFreshnessInput,
  ): Promise<MCPToolResponse> {
    const startTime = Date.now();
  
    try {
      const {
        docsPath,
        projectPath,
        initializeMissing,
        updateExisting,
        updateFrequency,
        validateAgainstGit,
      } = input;
  
      // Get current git commit if requested
      let currentCommit: string | undefined;
      if (validateAgainstGit) {
        try {
          const git = simpleGit(projectPath);
          const isRepo = await git.checkIsRepo();
  
          if (isRepo) {
            const log = await git.log({ maxCount: 1 });
            currentCommit = log.latest?.hash;
          }
        } catch (error) {
          // Git not available, continue without it
        }
      }
  
      // Find all markdown files
      const markdownFiles = await findMarkdownFiles(docsPath);
      const results: FileValidationResult[] = [];
  
      for (const filePath of markdownFiles) {
        const relativePath = path.relative(docsPath, filePath);
  
        try {
          const frontmatter = await parseDocFrontmatter(filePath);
          const hasMetadata = !!frontmatter.documcp?.last_updated;
  
          if (!hasMetadata && initializeMissing) {
            // Initialize metadata
            await initializeFreshnessMetadata(filePath, {
              updateFrequency,
              autoUpdated: false,
            });
  
            // If git is available, set validated_against_commit
            if (currentCommit) {
              await updateDocFrontmatter(filePath, {
                validated_against_commit: currentCommit,
              });
            }
  
            const updatedFrontmatter = await parseDocFrontmatter(filePath);
            results.push({
              filePath,
              relativePath,
              action: "initialized",
              metadata: updatedFrontmatter.documcp,
            });
          } else if (hasMetadata && updateExisting) {
            // Update existing metadata
            const updateData: Partial<DocFreshnessMetadata> = {
              last_validated: new Date().toISOString(),
            };
  
            if (currentCommit) {
              updateData.validated_against_commit = currentCommit;
            }
  
            await updateDocFrontmatter(filePath, updateData);
  
            const updatedFrontmatter = await parseDocFrontmatter(filePath);
            results.push({
              filePath,
              relativePath,
              action: "updated",
              metadata: updatedFrontmatter.documcp,
            });
          } else {
            results.push({
              filePath,
              relativePath,
              action: "skipped",
              metadata: frontmatter.documcp,
            });
          }
        } catch (error) {
          results.push({
            filePath,
            relativePath,
            action: "error",
            error: error instanceof Error ? error.message : "Unknown error",
          });
        }
      }
  
      // Generate report
      const report: ValidationReport = {
        validatedAt: new Date().toISOString(),
        docsPath,
        projectPath,
        totalFiles: markdownFiles.length,
        initialized: results.filter((r) => r.action === "initialized").length,
        updated: results.filter((r) => r.action === "updated").length,
        skipped: results.filter((r) => r.action === "skipped").length,
        errors: results.filter((r) => r.action === "error").length,
        currentCommit,
        files: results,
      };
  
      const formattedReport = formatValidationReport(report);
  
      // Store validation event in knowledge graph
      let eventId: string | undefined;
      if (report.initialized > 0 || report.updated > 0) {
        try {
          // Scan current state to get freshness metrics
          const scanReport = await scanDocumentationFreshness(docsPath, {
            warning: STALENESS_PRESETS.monthly,
            stale: {
              value: STALENESS_PRESETS.monthly.value * 2,
              unit: STALENESS_PRESETS.monthly.unit,
            },
            critical: {
              value: STALENESS_PRESETS.monthly.value * 3,
              unit: STALENESS_PRESETS.monthly.unit,
            },
          });
  
          // Determine event type
          const eventType = report.initialized > 0 ? "initialization" : "update";
  
          // Store in KG
          eventId = await storeFreshnessEvent(
            projectPath,
            docsPath,
            scanReport,
            eventType,
          );
  
          // Update event with validation details
          await updateFreshnessEvent(eventId, {
            filesInitialized: report.initialized,
            filesUpdated: report.updated,
            eventType,
          });
        } catch (error) {
          // KG storage failed, but continue with the response
          console.warn(
            "Failed to store validation event in knowledge graph:",
            error,
          );
        }
      }
  
      const response: MCPToolResponse = {
        success: true,
        data: {
          summary: `Validated ${report.totalFiles} files: ${report.initialized} initialized, ${report.updated} updated`,
          report,
          formattedReport,
          kgEventId: eventId,
        },
        metadata: {
          toolVersion: "1.0.0",
          executionTime: Date.now() - startTime,
          timestamp: new Date().toISOString(),
        },
        recommendations: [],
      };
  
      return response;
    } catch (error) {
      return {
        success: false,
        error: {
          code: "FRESHNESS_VALIDATION_FAILED",
          message:
            error instanceof Error
              ? error.message
              : "Unknown error validating documentation freshness",
          resolution:
            "Check that the documentation and project paths exist and are readable",
        },
        metadata: {
          toolVersion: "1.0.0",
          executionTime: Date.now() - startTime,
          timestamp: new Date().toISOString(),
        },
      };
    }
  }

• src/tools/validate-documentation-freshness.ts:29-54 (schema)

  Zod schema defining the input parameters for the validate_documentation_freshness tool, including paths, flags for initialization/updating, frequency preset, and git validation option.

  export const ValidateDocumentationFreshnessSchema = z.object({
    docsPath: z.string().describe("Path to documentation directory"),
    projectPath: z
      .string()
      .describe("Path to project root (for git integration)"),
    initializeMissing: z
      .boolean()
      .optional()
      .default(true)
      .describe("Initialize metadata for files without it"),
    updateExisting: z
      .boolean()
      .optional()
      .default(false)
      .describe("Update last_validated timestamp for all files"),
    updateFrequency: z
      .enum(["realtime", "active", "recent", "weekly", "monthly", "quarterly"])
      .optional()
      .default("monthly")
      .describe("Default update frequency for new metadata"),
    validateAgainstGit: z
      .boolean()
      .optional()
      .default(true)
      .describe("Validate against current git commit"),
  });

• src/tools/validate-documentation-freshness.ts:90-158 (helper)

  Helper function that formats the validation results into a readable Markdown report with summary, actions performed, and next steps.

  function formatValidationReport(report: ValidationReport): string {
    let output = "# Documentation Freshness Validation Report\n\n";
    output += `**Validated at**: ${new Date(
      report.validatedAt,
    ).toLocaleString()}\n`;
    output += `**Documentation path**: ${report.docsPath}\n`;
  
    if (report.currentCommit) {
      output += `**Current commit**: ${report.currentCommit.substring(0, 7)}\n`;
    }
  
    output += "\n## Summary\n\n";
    output += `- **Total files**: ${report.totalFiles}\n`;
    output += `- **Initialized**: ${report.initialized} files\n`;
    output += `- **Updated**: ${report.updated} files\n`;
    output += `- **Skipped**: ${report.skipped} files\n`;
  
    if (report.errors > 0) {
      output += `- **Errors**: ${report.errors} files\n`;
    }
  
    output += "\n## Actions Performed\n\n";
  
    // Group by action
    const grouped = {
      initialized: report.files.filter((f) => f.action === "initialized"),
      updated: report.files.filter((f) => f.action === "updated"),
      error: report.files.filter((f) => f.action === "error"),
    };
  
    if (grouped.initialized.length > 0) {
      output += `### ✨ Initialized (${grouped.initialized.length})\n\n`;
      for (const file of grouped.initialized) {
        output += `- ${file.relativePath}\n`;
      }
      output += "\n";
    }
  
    if (grouped.updated.length > 0) {
      output += `### 🔄 Updated (${grouped.updated.length})\n\n`;
      for (const file of grouped.updated) {
        output += `- ${file.relativePath}\n`;
      }
      output += "\n";
    }
  
    if (grouped.error.length > 0) {
      output += `### ❌ Errors (${grouped.error.length})\n\n`;
      for (const file of grouped.error) {
        output += `- ${file.relativePath}: ${file.error}\n`;
      }
      output += "\n";
    }
  
    // Recommendations
    output += "## Next Steps\n\n";
  
    if (report.initialized > 0) {
      output += `→ ${report.initialized} files now have freshness tracking enabled\n`;
    }
  
    if (report.updated > 0) {
      output += `→ ${report.updated} files have been marked as validated\n`;
    }
  
    output += `→ Run \`track_documentation_freshness\` to view current freshness status\n`;
  
    return output;
  }