documcp

Instructions

Implementation Reference

• src/tools/sync-code-to-docs.ts:82-286 (handler)

  Main handler function that executes the sync_code_to_docs tool logic: parses input, detects drift between code and docs, applies changes based on mode, computes stats, and returns structured results.

  export async function handleSyncCodeToDocs(
    args: unknown,
    context?: any,
  ): Promise<{ content: any[] }> {
    const startTime = Date.now();
  
    try {
      const { projectPath, docsPath, mode, autoApplyThreshold, createSnapshot } =
        inputSchema.parse(args);
  
      await context?.info?.(
        `🔄 Starting code-to-documentation synchronization (mode: ${mode})...`,
      );
  
      // Initialize drift detector
      const detector = new DriftDetector(projectPath);
      await detector.initialize();
  
      // Create baseline snapshot if requested
      if (createSnapshot || mode !== "detect") {
        await context?.info?.("📸 Creating code snapshot...");
        await detector.createSnapshot(projectPath, docsPath);
      }
  
      // Load previous snapshot for comparison
      await context?.info?.("🔍 Detecting documentation drift...");
      const previousSnapshot = await detector.loadLatestSnapshot();
  
      if (!previousSnapshot) {
        await context?.info?.(
          "ℹ️ No previous snapshot found. Creating baseline...",
        );
        const baselineSnapshot = await detector.createSnapshot(
          projectPath,
          docsPath,
        );
  
        const result: SyncResult = {
          mode,
          driftDetections: [],
          appliedChanges: [],
          pendingChanges: [],
          stats: {
            filesAnalyzed: baselineSnapshot.files.size,
            driftsDetected: 0,
            changesApplied: 0,
            changesPending: 0,
            breakingChanges: 0,
            estimatedUpdateTime: "0 minutes",
          },
          snapshotId: baselineSnapshot.timestamp,
        };
  
        const response: MCPToolResponse<typeof result> = {
          success: true,
          data: result,
          metadata: {
            toolVersion: "3.0.0",
            executionTime: Date.now() - startTime,
            timestamp: new Date().toISOString(),
          },
          recommendations: [
            {
              type: "info",
              title: "Baseline Created",
              description:
                "Baseline snapshot created. Run sync again after code changes to detect drift.",
            },
          ],
        };
  
        return formatMCPResponse(response, { fullResponse: true });
      }
  
      // Create current snapshot and detect drift
      const currentSnapshot = await detector.createSnapshot(
        projectPath,
        docsPath,
      );
      const driftResults = await detector.detectDrift(
        previousSnapshot,
        currentSnapshot,
      );
  
      await context?.info?.(
        `📊 Found ${driftResults.length} file(s) with documentation drift`,
      );
  
      // Process based on mode
      const appliedChanges: AppliedChange[] = [];
      const pendingChanges: PendingSuggestion[] = [];
  
      for (const driftResult of driftResults) {
        if (driftResult.hasDrift) {
          for (const suggestion of driftResult.suggestions) {
            if (mode === "apply" || mode === "auto") {
              // Apply changes based on confidence
              const shouldApply =
                mode === "auto" ||
                (suggestion.autoApplicable &&
                  suggestion.confidence >= autoApplyThreshold);
  
              if (shouldApply) {
                try {
                  await applyDocumentationChange(
                    suggestion,
                    context,
                    projectPath,
                  );
                  appliedChanges.push({
                    docFile: suggestion.docFile,
                    section: suggestion.section,
                    changeType: "updated",
                    confidence: suggestion.confidence,
                    details: suggestion.reasoning,
                  });
                } catch (error: any) {
                  await context?.warn?.(
                    `Failed to apply change to ${suggestion.docFile}: ${error.message}`,
                  );
                  pendingChanges.push({
                    docFile: suggestion.docFile,
                    section: suggestion.section,
                    reason: `Auto-apply failed: ${error.message}`,
                    suggestion,
                    requiresReview: true,
                  });
                }
              } else {
                pendingChanges.push({
                  docFile: suggestion.docFile,
                  section: suggestion.section,
                  reason: "Requires manual review",
                  suggestion,
                  requiresReview: true,
                });
              }
            } else {
              // Preview/detect mode - just collect suggestions
              pendingChanges.push({
                docFile: suggestion.docFile,
                section: suggestion.section,
                reason: "Detected drift",
                suggestion,
                requiresReview: !suggestion.autoApplicable,
              });
            }
          }
        }
      }
  
      // Calculate stats
      const stats = calculateSyncStats(
        driftResults,
        appliedChanges,
        pendingChanges,
      );
  
      // Store sync results in knowledge graph
      await storeSyncResults(projectPath, driftResults, appliedChanges, context);
  
      const result: SyncResult = {
        mode,
        driftDetections: driftResults,
        appliedChanges,
        pendingChanges,
        stats,
        snapshotId: currentSnapshot.timestamp,
      };
  
      const response: MCPToolResponse<typeof result> = {
        success: true,
        data: result,
        metadata: {
          toolVersion: "3.0.0",
          executionTime: Date.now() - startTime,
          timestamp: new Date().toISOString(),
        },
        recommendations: generateRecommendations(result),
        nextSteps: generateNextSteps(result),
      };
  
      await context?.info?.(
        `✅ Synchronization complete: ${appliedChanges.length} applied, ${pendingChanges.length} pending`,
      );
  
      return formatMCPResponse(response, { fullResponse: true });
    } catch (error: any) {
      const errorResponse: MCPToolResponse = {
        success: false,
        error: {
          code: "SYNC_FAILED",
          message: `Documentation synchronization failed: ${error.message}`,
          resolution: "Check project and documentation paths are correct",
        },
        metadata: {
          toolVersion: "3.0.0",
          executionTime: Date.now() - startTime,
          timestamp: new Date().toISOString(),
        },
      };
  
      return formatMCPResponse(errorResponse, { fullResponse: true });
    }
  }

• src/tools/sync-code-to-docs.ts:560-598 (registration)

  MCP Tool registration defining the 'sync_code_to_docs' tool with name, description, and detailed input schema.

  export const syncCodeToDocs: Tool = {
    name: "sync_code_to_docs",
    description:
      "Automatically synchronize documentation with code changes using AST-based drift detection (Phase 3)",
    inputSchema: {
      type: "object",
      properties: {
        projectPath: {
          type: "string",
          description: "Path to the project root directory",
        },
        docsPath: {
          type: "string",
          description: "Path to the documentation directory",
        },
        mode: {
          type: "string",
          enum: ["detect", "preview", "apply", "auto"],
          default: "detect",
          description:
            "Sync mode: detect=analyze only, preview=show changes, apply=apply safe changes, auto=apply all",
        },
        autoApplyThreshold: {
          type: "number",
          minimum: 0,
          maximum: 1,
          default: 0.8,
          description:
            "Confidence threshold (0-1) for automatic application of changes",
        },
        createSnapshot: {
          type: "boolean",
          default: true,
          description: "Create a snapshot before making changes (recommended)",
        },
      },
      required: ["projectPath", "docsPath"],
    },
  };

• src/tools/sync-code-to-docs.ts:22-41 (schema)

  Zod input validation schema used within the handler to parse and validate tool arguments.

  const inputSchema = z.object({
    projectPath: z.string().describe("Path to the project root"),
    docsPath: z.string().describe("Path to the documentation directory"),
    mode: z
      .enum(["detect", "preview", "apply", "auto"])
      .default("detect")
      .describe(
        "Mode: detect=analyze only, preview=show changes, apply=apply safe changes, auto=apply all changes",
      ),
    autoApplyThreshold: z
      .number()
      .min(0)
      .max(1)
      .default(0.8)
      .describe("Confidence threshold for automatic application (0-1)"),
    createSnapshot: z
      .boolean()
      .default(true)
      .describe("Create a snapshot before making changes"),
  });

• src/tools/sync-code-to-docs.ts:291-359 (helper)

  Helper function to apply a specific documentation change: updates file content and metadata.

  async function applyDocumentationChange(
    suggestion: DriftSuggestion,
    context?: any,
    projectPath?: string,
  ): Promise<void> {
    const filePath = suggestion.docFile;
  
    // Read current file
    const content = await fs.readFile(filePath, "utf-8");
  
    // Find and replace the section
    const sectionPattern = new RegExp(
      `(#{1,6}\\s+${escapeRegex(suggestion.section)}[\\s\\S]*?)(?=#{1,6}\\s+|$)`,
      "g",
    );
  
    let newContent = content;
    const match = sectionPattern.exec(content);
  
    if (match) {
      // Replace existing section
      newContent = content.replace(sectionPattern, suggestion.suggestedContent);
      await context?.info?.(
        `✏️ Updated section '${suggestion.section}' in ${path.basename(
          filePath,
        )}`,
      );
    } else {
      // Append new section
      newContent = content + "\n\n" + suggestion.suggestedContent;
      await context?.info?.(
        `➕ Added section '${suggestion.section}' to ${path.basename(filePath)}`,
      );
    }
  
    // Write back to file
    await fs.writeFile(filePath, newContent, "utf-8");
  
    // Update freshness metadata
    try {
      let currentCommit: string | undefined;
      if (projectPath) {
        try {
          const git = simpleGit(projectPath);
          const isRepo = await git.checkIsRepo();
          if (isRepo) {
            const log = await git.log({ maxCount: 1 });
            currentCommit = log.latest?.hash;
          }
        } catch {
          // Git not available, continue without it
        }
      }
  
      await updateDocFrontmatter(filePath, {
        last_updated: new Date().toISOString(),
        last_validated: new Date().toISOString(),
        auto_updated: true,
        validated_against_commit: currentCommit,
      });
  
      await context?.info?.(
        `🏷️ Updated freshness metadata for ${path.basename(filePath)}`,
      );
    } catch (error) {
      // Non-critical error, just log it
      await context?.warn?.(`Failed to update freshness metadata: ${error}`);
    }
  }