feat: Add change watcher for real-time documentation drift monitoring

[tosin2013]

Overview

Implement a change watching system that monitors code changes and proactively triggers documentation drift detection. This enables real-time awareness of when documentation may become stale.

Background

This enhancement supports ADR-009: Documentation Synchronization Agent from the DocuMCP Orchestrator project. The change watcher enables proactive drift detection rather than relying solely on manual checks.

Requirements

Core Functionality

• Monitor git hooks for code changes
• Support webhook integration for CI/CD pipelines
• File system watching for development environments
• Debounced change detection to avoid excessive processing

Trigger Events

• Post-commit hooks
• Pull request events
• Branch merge events
• Manual trigger API

Change Analysis

• Identify which functions/classes changed
• Map changes to affected documentation sections
• Calculate change impact scores
• Queue drift detection jobs

Configuration Options

interface ChangeWatcherConfig {
  watchPaths: string[];
  excludePatterns: string[];
  debounceMs: number;
  triggerOnCommit: boolean;
  triggerOnPR: boolean;
  webhookEndpoint?: string;
}

Acceptance Criteria

• Git hook integration works with standard git workflows
• Webhook endpoint accepts GitHub/GitLab events
• Changes are correctly mapped to documentation sections
• Debouncing prevents duplicate processing
• Configuration is flexible for different project setups

Dependencies

• Requires: Existing drift detection in drift-detector.ts
• Optional: Issue feat: Add LLM integration layer for semantic code analysis #71 (LLM Integration Layer) for semantic change analysis

Implementation Notes

• Consider using chokidar for file system watching
• Git hooks should be installable via CLI command
• Webhook should validate request signatures

Related

• ADR-009: Documentation Synchronization Agent
• src/utils/drift-detector.ts - existing drift detection

[tosin2013]

Implementation Complete ✅

The change watcher feature has been fully implemented in commit 362fbca. All requirements from this issue have been addressed:

Core Functionality

• ✅ Git hooks monitoring via installGitHook() method
• ✅ Webhook integration for CI/CD (GitHub/GitLab support with signature validation)
• ✅ File system watching using chokidar
• ✅ Debounced change detection with configurable timing

Trigger Events

• ✅ Post-commit hooks
• ✅ Pull request events
• ✅ Branch merge events
• ✅ Manual trigger API

Change Analysis

• ✅ Identifies changed functions/classes (changedSymbols)
• ✅ Maps changes to affected documentation (affectedDocs)
• ✅ Calculates impact scores via drift detector priority scoring
• ✅ Queues drift detection jobs with debouncing

Configuration

All configuration options from the spec are implemented:

• watchPaths, excludePatterns, debounceMs
• triggerOnCommit, triggerOnPR
• webhookEndpoint, webhookSecret, port

Files Added

• src/utils/change-watcher.ts - Core ChangeWatcher class
• src/tools/change-watcher.ts - MCP tool handler
• tests/change-watcher.test.ts - Unit tests
• docs/how-to/change-watcher.md - User documentation

Usage

// Start watching
change_watcher({ action: "start", projectPath: "/repo", docsPath: "/repo/docs" })

// Manual trigger
change_watcher({ action: "trigger", reason: "manual check" })

// Install git hook
change_watcher({ action: "install_hook" })