mcp-adr-analysis-server 2.1.22 → 2.1.28

package/dist/src/tools/analyze-gaps-tool.js

@@ -0,0 +1,727 @@
+/**
+ * Analyze Gaps Tool
+ * Scans local codebase and compares with ADRs to detect bi-directional gaps.
+ *
+ * Workflow:
+ * 1. Fetch ADRs (local or from aggregator)
+ * 2. Scan local files for:
+ *    - File references in ADRs that don't exist
+ *    - Technologies in package.json without ADR coverage
+ *    - Architectural patterns (WebSocket, Redis, auth, etc.)
+ * 3. Report gaps to ADR Aggregator
+ */
+import { promises as fs, existsSync } from 'fs';
+import path from 'path';
+import { McpAdrError } from '../types/index.js';
+import { getAdrAggregatorClient, } from '../utils/adr-aggregator-client.js';
+import { loadConfig } from '../utils/config.js';
+import { isGitRepository } from '../utils/git-remote-detector.js';
+// ============================================================================
+// Technology Detection Patterns
+// ============================================================================
+/**
+ * Technology patterns to detect in package.json dependencies
+ */
+const TECHNOLOGY_PATTERNS = {
+    redis: {
+        keywords: ['redis', 'ioredis', '@redis/client'],
+        suggestedAdrTitle: 'Caching Strategy with Redis',
+    },
+    postgresql: {
+        keywords: ['pg', 'postgres', 'postgresql', '@prisma/client', 'typeorm', 'knex'],
+        suggestedAdrTitle: 'Database Strategy with PostgreSQL',
+    },
+    mongodb: {
+        keywords: ['mongodb', 'mongoose', 'monk'],
+        suggestedAdrTitle: 'Database Strategy with MongoDB',
+    },
+    elasticsearch: {
+        keywords: ['elasticsearch', '@elastic/elasticsearch', 'opensearch'],
+        suggestedAdrTitle: 'Search Infrastructure with Elasticsearch',
+    },
+    rabbitmq: {
+        keywords: ['amqplib', 'amqp-connection-manager', 'rabbitmq'],
+        suggestedAdrTitle: 'Message Queue Strategy with RabbitMQ',
+    },
+    kafka: {
+        keywords: ['kafkajs', 'kafka-node', 'node-rdkafka'],
+        suggestedAdrTitle: 'Event Streaming with Kafka',
+    },
+    graphql: {
+        keywords: ['graphql', 'apollo-server', '@apollo/server', 'type-graphql', 'nexus'],
+        suggestedAdrTitle: 'API Strategy with GraphQL',
+    },
+    websocket: {
+        keywords: ['ws', 'socket.io', 'socket.io-client', '@socket.io/redis-adapter'],
+        suggestedAdrTitle: 'Real-time Communication with WebSockets',
+    },
+    grpc: {
+        keywords: ['grpc', '@grpc/grpc-js', '@grpc/proto-loader'],
+        suggestedAdrTitle: 'Service Communication with gRPC',
+    },
+    kubernetes: {
+        keywords: ['@kubernetes/client-node', 'kubernetes-client'],
+        suggestedAdrTitle: 'Container Orchestration with Kubernetes',
+    },
+    docker: {
+        keywords: ['dockerode', 'docker-compose'],
+        suggestedAdrTitle: 'Containerization Strategy with Docker',
+    },
+    aws: {
+        keywords: ['aws-sdk', '@aws-sdk/', 'aws-amplify'],
+        suggestedAdrTitle: 'Cloud Infrastructure with AWS',
+    },
+    gcp: {
+        keywords: ['@google-cloud/', 'firebase', 'firebase-admin', 'firebase-functions'],
+        suggestedAdrTitle: 'Cloud Infrastructure with Google Cloud',
+    },
+    azure: {
+        keywords: ['@azure/', 'azure-storage'],
+        suggestedAdrTitle: 'Cloud Infrastructure with Azure',
+    },
+    auth: {
+        keywords: ['passport', 'jsonwebtoken', 'bcrypt', 'oauth', '@auth0/', 'next-auth', 'clerk'],
+        suggestedAdrTitle: 'Authentication and Authorization Strategy',
+    },
+    testing: {
+        keywords: ['jest', 'mocha', 'vitest', 'cypress', 'playwright', '@testing-library/'],
+        suggestedAdrTitle: 'Testing Strategy and Framework Selection',
+    },
+    monitoring: {
+        keywords: ['prom-client', 'newrelic', '@sentry/', 'datadog', '@opentelemetry/'],
+        suggestedAdrTitle: 'Observability and Monitoring Strategy',
+    },
+    react: {
+        keywords: ['react', 'react-dom', 'next', '@remix-run/'],
+        suggestedAdrTitle: 'Frontend Framework Selection - React',
+    },
+    vue: {
+        keywords: ['vue', 'nuxt', '@vue/'],
+        suggestedAdrTitle: 'Frontend Framework Selection - Vue',
+    },
+    angular: {
+        keywords: ['@angular/core', '@angular/cli'],
+        suggestedAdrTitle: 'Frontend Framework Selection - Angular',
+    },
+};
+/**
+ * Architectural patterns to detect in source code
+ */
+const ARCHITECTURAL_PATTERNS = {
+    microservices: {
+        filePatterns: [/docker-compose\.ya?ml$/i, /k8s\/.*\.ya?ml$/i, /\.?helm\//i],
+        codePatterns: [/service-discovery/i, /circuit-?breaker/i, /api-gateway/i],
+        suggestedAdrTitle: 'Microservices Architecture',
+    },
+    eventSourcing: {
+        filePatterns: [/events?\//i, /event-store/i],
+        codePatterns: [/event-?sourcing/i, /event-?store/i, /aggregate-?root/i],
+        suggestedAdrTitle: 'Event Sourcing Pattern',
+    },
+    cqrs: {
+        filePatterns: [/commands?\//i, /queries?\//i],
+        codePatterns: [/command-?handler/i, /query-?handler/i, /cqrs/i],
+        suggestedAdrTitle: 'CQRS Pattern Implementation',
+    },
+    domainDrivenDesign: {
+        filePatterns: [/domain\//i, /aggregates?\//i, /entities?\//i, /value-?objects?\//i],
+        codePatterns: [/bounded-?context/i, /aggregate/i, /domain-?event/i],
+        suggestedAdrTitle: 'Domain-Driven Design Adoption',
+    },
+    cleanArchitecture: {
+        filePatterns: [
+            /use-?cases?\//i,
+            /adapters?\//i,
+            /infrastructure\//i,
+            /presentation\//i,
+            /core\//i,
+        ],
+        codePatterns: [/use-?case/i, /presenter/i, /repository-?interface/i],
+        suggestedAdrTitle: 'Clean Architecture Implementation',
+    },
+    serverless: {
+        filePatterns: [/serverless\.ya?ml$/i, /netlify\.toml$/i, /vercel\.json$/i],
+        codePatterns: [/lambda-?handler/i, /cloud-?function/i],
+        suggestedAdrTitle: 'Serverless Architecture',
+    },
+};
+// ============================================================================
+// Helper Functions
+// ============================================================================
+/**
+ * Discover ADR files in the project
+ */
+async function discoverLocalAdrs(projectPath, adrDirectory) {
+    const adrPath = path.resolve(projectPath, adrDirectory);
+    const adrFiles = [];
+    try {
+        const files = await fs.readdir(adrPath);
+        for (const file of files) {
+            if (file.endsWith('.md')) {
+                adrFiles.push(path.join(adrPath, file));
+            }
+        }
+    }
+    catch {
+        // Directory doesn't exist or not readable
+    }
+    return adrFiles;
+}
+/**
+ * Normalize a file path and verify if it exists
+ *
+ * Handles various path formats:
+ * - ./src/file.ts → src/file.ts (strips leading ./)
+ * - ../shared/types.ts → ../shared/types.ts (preserves parent refs)
+ * - src/file.ts → src/file.ts (no change needed)
+ *
+ * @param referencedPath - The path as found in the ADR
+ * @param basePath - The base path to resolve relative paths against (usually repo root)
+ * @returns Object with exists flag and normalized path
+ */
+function normalizeAndVerifyPath(referencedPath, basePath) {
+    // Normalize the path:
+    // - Strip leading ./ (current directory)
+    // - Preserve ../ (parent directory references)
+    // - Handle multiple leading ./
+    const normalized = referencedPath
+        .replace(/^(\.\/)+/, '') // Remove one or more leading ./
+        .trim();
+    // If path is empty after normalization, it's invalid
+    if (!normalized) {
+        return {
+            exists: false,
+            normalizedPath: referencedPath,
+            resolvedPath: '',
+        };
+    }
+    // Resolve the full path relative to basePath
+    const fullPath = path.resolve(basePath, normalized);
+    // Check if file exists
+    const exists = existsSync(fullPath);
+    return {
+        exists,
+        normalizedPath: normalized,
+        resolvedPath: fullPath,
+    };
+}
+/**
+ * Simple path normalization (for use in extraction)
+ * Strips leading ./ prefix only
+ */
+function normalizeFilePath(ref) {
+    return ref.replace(/^(\.\/)+/, '').trim();
+}
+/**
+ * Extract file references from ADR content
+ * Looks for patterns like:
+ * - `src/file.ts` or `./src/file.ts`
+ * - [link](./path/to/file.ts)
+ * - References to: src/auth/oauth.ts
+ *
+ * Note: All paths are normalized by stripping leading ./ prefix
+ */
+function extractFileReferences(content) {
+    const references = new Set();
+    // Match backtick code references: `src/file.ts` or `./src/file.ts`
+    const backtickPattern = /`([^`]+\.[a-zA-Z]{2,4})`/g;
+    let match;
+    while ((match = backtickPattern.exec(content)) !== null) {
+        const ref = match[1];
+        if (ref && !ref.includes(' ') && !ref.startsWith('http')) {
+            references.add(normalizeFilePath(ref));
+        }
+    }
+    // Match markdown links: [text](./path/file.ts)
+    const linkPattern = /\[([^\]]*)\]\(([^)]+\.[a-zA-Z]{2,4})\)/g;
+    while ((match = linkPattern.exec(content)) !== null) {
+        const ref = match[2];
+        if (ref && !ref.startsWith('http')) {
+            references.add(normalizeFilePath(ref));
+        }
+    }
+    // Match explicit file paths in common patterns (with or without ./ prefix)
+    const pathPattern = /(?:\.\/)?(?:src|lib|app|packages?)\/[\w\-/.]+\.[a-zA-Z]{2,4}(?=[\s,;:\])]|$)/g;
+    while ((match = pathPattern.exec(content)) !== null) {
+        references.add(normalizeFilePath(match[0]));
+    }
+    return Array.from(references);
+}
+/**
+ * Read and parse package.json
+ */
+async function readPackageJson(projectPath) {
+    try {
+        const packageJsonPath = path.join(projectPath, 'package.json');
+        const content = await fs.readFile(packageJsonPath, 'utf-8');
+        const pkg = JSON.parse(content);
+        return {
+            dependencies: pkg.dependencies || {},
+            devDependencies: pkg.devDependencies || {},
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Detect technologies from package.json
+ */
+function detectTechnologies(dependencies, devDependencies) {
+    const allDeps = { ...dependencies, ...devDependencies };
+    const detected = [];
+    for (const [techName, config] of Object.entries(TECHNOLOGY_PATTERNS)) {
+        const matchingPackages = [];
+        for (const dep of Object.keys(allDeps)) {
+            for (const keyword of config.keywords) {
+                if (dep.toLowerCase().includes(keyword.toLowerCase())) {
+                    matchingPackages.push(dep);
+                    break;
+                }
+            }
+        }
+        if (matchingPackages.length > 0) {
+            detected.push({
+                name: techName,
+                packages: matchingPackages,
+                suggestedAdrTitle: config.suggestedAdrTitle,
+            });
+        }
+    }
+    return detected;
+}
+/**
+ * Scan directory recursively for files
+ */
+async function scanDirectory(dirPath, includePatterns, excludePatterns, maxDepth = 5, currentDepth = 0) {
+    if (currentDepth >= maxDepth)
+        return [];
+    const files = [];
+    try {
+        const entries = await fs.readdir(dirPath, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dirPath, entry.name);
+            const relativePath = fullPath;
+            // Skip excluded patterns
+            if (excludePatterns.some(pattern => pattern.test(relativePath))) {
+                continue;
+            }
+            if (entry.isDirectory()) {
+                // Skip common non-source directories
+                if (['node_modules', '.git', 'dist', 'build', 'coverage', '.next'].includes(entry.name)) {
+                    continue;
+                }
+                const subFiles = await scanDirectory(fullPath, includePatterns, excludePatterns, maxDepth, currentDepth + 1);
+                files.push(...subFiles);
+            }
+            else if (entry.isFile()) {
+                if (includePatterns.length === 0 ||
+                    includePatterns.some(pattern => pattern.test(entry.name))) {
+                    files.push(fullPath);
+                }
+            }
+        }
+    }
+    catch {
+        // Directory not accessible
+    }
+    return files;
+}
+/**
+ * Check if ADR content mentions a technology
+ */
+function adrMentionsTechnology(adrContent, techName, keywords) {
+    const lowerContent = adrContent.toLowerCase();
+    if (lowerContent.includes(techName.toLowerCase())) {
+        return true;
+    }
+    for (const keyword of keywords) {
+        if (lowerContent.includes(keyword.toLowerCase())) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Detect architectural patterns in the codebase
+ */
+async function detectArchitecturalPatterns(projectPath, scannedFiles) {
+    const detected = [];
+    for (const [patternName, config] of Object.entries(ARCHITECTURAL_PATTERNS)) {
+        const evidence = [];
+        // Check file patterns
+        for (const file of scannedFiles) {
+            const relativePath = path.relative(projectPath, file);
+            for (const pattern of config.filePatterns) {
+                if (pattern.test(relativePath)) {
+                    evidence.push(`File: ${relativePath}`);
+                    break;
+                }
+            }
+        }
+        // For now, just use file-based detection
+        // Code pattern detection could be added by reading file contents
+        if (evidence.length > 0) {
+            detected.push({
+                name: patternName,
+                evidence,
+                suggestedAdrTitle: config.suggestedAdrTitle,
+            });
+        }
+    }
+    return detected;
+}
+/**
+ * Ensure client is configured
+ */
+function ensureConfigured(client) {
+    if (!client.isConfigured()) {
+        throw new McpAdrError('ADR Aggregator API key not configured. Set ADR_AGGREGATOR_API_KEY environment variable.', 'NOT_CONFIGURED');
+    }
+}
+/**
+ * Ensure git repository
+ */
+function ensureGitRepo(projectPath) {
+    if (!isGitRepository(projectPath)) {
+        throw new McpAdrError('Not a git repository. ADR Aggregator requires a git repository to auto-detect the repository name.', 'NOT_GIT_REPO');
+    }
+}
+// ============================================================================
+// Main Tool Implementation
+// ============================================================================
+/**
+ * Analyze gaps between ADRs and codebase
+ *
+ * Detects:
+ * 1. ADR-to-code gaps: File references in ADRs that don't exist
+ * 2. Code-to-ADR gaps: Technologies/patterns in code without ADR coverage
+ */
+export async function analyzeGaps(args, context) {
+    const { reportToAggregator = true, scanDirectories, includePatterns, excludePatterns } = args;
+    const config = loadConfig();
+    const resolvedProjectPath = args.projectPath || config.projectPath;
+    const client = getAdrAggregatorClient();
+    // Validate git repository if reporting to aggregator
+    if (reportToAggregator) {
+        ensureConfigured(client);
+        ensureGitRepo(resolvedProjectPath);
+    }
+    try {
+        context?.info('Starting gap analysis...');
+        context?.report_progress(5, 100);
+        const gaps = [];
+        let filesScanned = 0;
+        const technologiesDetected = [];
+        const patternsDetected = [];
+        // Step 1: Discover and analyze local ADRs
+        context?.info('Discovering ADRs...');
+        context?.report_progress(10, 100);
+        const adrFiles = await discoverLocalAdrs(resolvedProjectPath, config.adrDirectory);
+        const adrContents = [];
+        for (const adrFile of adrFiles) {
+            try {
+                const content = await fs.readFile(adrFile, 'utf-8');
+                adrContents.push({
+                    path: path.relative(resolvedProjectPath, adrFile),
+                    content,
+                });
+            }
+            catch {
+                // Skip unreadable files
+            }
+        }
+        context?.info(`Found ${adrContents.length} ADRs`);
+        context?.report_progress(20, 100);
+        // Step 2: Check file references in ADRs (ADR-to-code gaps)
+        context?.info('Checking file references in ADRs...');
+        context?.report_progress(30, 100);
+        for (const adr of adrContents) {
+            const fileRefs = extractFileReferences(adr.content);
+            for (const ref of fileRefs) {
+                // Normalize path and verify if file exists
+                const { exists, normalizedPath } = normalizeAndVerifyPath(ref, resolvedProjectPath);
+                // Only report as a gap if file truly doesn't exist
+                if (!exists) {
+                    gaps.push({
+                        gap_type: 'adr_to_code',
+                        severity: 'error',
+                        title: `Missing referenced file: ${normalizedPath}`,
+                        adr_path: adr.path,
+                        referenced_file: normalizedPath,
+                        verified: true, // File existence was verified by MCP server
+                        description: `ADR references file "${normalizedPath}" which does not exist in the codebase`,
+                    });
+                }
+            }
+        }
+        context?.report_progress(40, 100);
+        // Step 3: Scan codebase for technologies
+        context?.info('Scanning package.json for technologies...');
+        context?.report_progress(50, 100);
+        const packageJson = await readPackageJson(resolvedProjectPath);
+        if (packageJson) {
+            const technologies = detectTechnologies(packageJson.dependencies, packageJson.devDependencies);
+            for (const tech of technologies) {
+                technologiesDetected.push(tech.name);
+                // Check if any ADR mentions this technology
+                const hasAdrCoverage = adrContents.some(adr => adrMentionsTechnology(adr.content, tech.name, TECHNOLOGY_PATTERNS[tech.name]?.keywords || []));
+                if (!hasAdrCoverage) {
+                    // Determine severity based on technology importance
+                    let severity = 'warning';
+                    if (['auth', 'postgresql', 'mongodb', 'aws', 'gcp', 'azure'].includes(tech.name)) {
+                        severity = 'error'; // Critical infrastructure decisions
+                    }
+                    gaps.push({
+                        gap_type: 'code_to_adr',
+                        severity,
+                        title: `Undocumented technology: ${tech.name}`,
+                        detected_pattern: `${tech.packages.join(', ')} usage`,
+                        code_files: ['package.json', ...tech.packages.map(p => `node_modules/${p}`)],
+                        suggested_adr_title: tech.suggestedAdrTitle,
+                        description: `Technology "${tech.name}" is used (packages: ${tech.packages.join(', ')}) but has no ADR documenting the decision`,
+                    });
+                }
+            }
+        }
+        context?.report_progress(60, 100);
+        // Step 4: Scan for architectural patterns
+        context?.info('Detecting architectural patterns...');
+        context?.report_progress(70, 100);
+        const dirsToScan = scanDirectories || ['src', 'lib', 'app', 'packages'];
+        const includeRegex = includePatterns?.map(p => new RegExp(p)) || [];
+        const excludeRegex = excludePatterns?.map(p => new RegExp(p)) || [/node_modules/, /\.git/];
+        const scannedFiles = [];
+        for (const dir of dirsToScan) {
+            const dirPath = path.join(resolvedProjectPath, dir);
+            try {
+                await fs.access(dirPath);
+                const files = await scanDirectory(dirPath, includeRegex, excludeRegex);
+                scannedFiles.push(...files);
+            }
+            catch {
+                // Directory doesn't exist
+            }
+        }
+        filesScanned = scannedFiles.length;
+        const architecturalPatterns = await detectArchitecturalPatterns(resolvedProjectPath, scannedFiles);
+        for (const pattern of architecturalPatterns) {
+            patternsDetected.push(pattern.name);
+            // Check if any ADR mentions this pattern
+            const hasAdrCoverage = adrContents.some(adr => adr.content.toLowerCase().includes(pattern.name.toLowerCase()) ||
+                adr.content.toLowerCase().includes(pattern.suggestedAdrTitle.toLowerCase()));
+            if (!hasAdrCoverage) {
+                gaps.push({
+                    gap_type: 'code_to_adr',
+                    severity: 'warning',
+                    title: `Undocumented pattern: ${pattern.name}`,
+                    detected_pattern: `${pattern.name} pattern detected`,
+                    code_files: pattern.evidence.map(e => e.replace('File: ', '')),
+                    suggested_adr_title: pattern.suggestedAdrTitle,
+                    description: `Architectural pattern "${pattern.name}" detected but has no ADR documenting the decision`,
+                });
+            }
+        }
+        context?.report_progress(80, 100);
+        // Step 5: Report to ADR Aggregator if enabled
+        let gapsInserted;
+        let totalOpenGaps;
+        let repositoryName;
+        if (reportToAggregator && gaps.length > 0) {
+            context?.info('Reporting gaps to ADR Aggregator...');
+            context?.report_progress(90, 100);
+            try {
+                repositoryName = client.getRepositoryName(resolvedProjectPath);
+                const request = {
+                    repository_name: repositoryName,
+                    analyzed_at: new Date().toISOString(),
+                    gaps,
+                    analysis_summary: {
+                        files_scanned: filesScanned,
+                        adrs_checked: adrContents.length,
+                        technologies_detected: technologiesDetected,
+                        patterns_detected: patternsDetected,
+                    },
+                };
+                const response = await client.reportCodeGaps(request);
+                gapsInserted = response.summary.gaps_inserted;
+                totalOpenGaps = response.summary.total_open_gaps;
+                context?.info(`Reported gaps: ${gapsInserted} new, ${response.summary.gaps_updated} updated, ${totalOpenGaps} total open`);
+            }
+            catch (error) {
+                // Log but don't fail if aggregator reporting fails
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                context?.info(`Warning: Failed to report to aggregator: ${errorMessage}`);
+            }
+        }
+        context?.report_progress(100, 100);
+        // Build analysis summary
+        const summary = {
+            files_scanned: filesScanned,
+            adrs_checked: adrContents.length,
+            technologies_detected: technologiesDetected,
+            patterns_detected: patternsDetected,
+        };
+        // Format response
+        const adrToCodeGaps = gaps.filter(g => g.gap_type === 'adr_to_code');
+        const codeToAdrGaps = gaps.filter(g => g.gap_type === 'code_to_adr');
+        const errorGaps = gaps.filter(g => g.severity === 'error');
+        const warningGaps = gaps.filter(g => g.severity === 'warning');
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `# Gap Analysis Report
+
+## Summary
+- **Files Scanned:** ${summary.files_scanned}
+- **ADRs Checked:** ${summary.adrs_checked}
+- **Total Gaps Found:** ${gaps.length}
+  - Errors: ${errorGaps.length}
+  - Warnings: ${warningGaps.length}
+- **Technologies Detected:** ${summary.technologies_detected.join(', ') || 'None'}
+- **Patterns Detected:** ${summary.patterns_detected?.join(', ') || 'None'}
+${repositoryName ? `- **Repository:** ${repositoryName}` : ''}
+${gapsInserted !== undefined ? `- **Gaps Reported:** ${gapsInserted} new, ${totalOpenGaps} total open` : ''}
+
+---
+
+## ADR-to-Code Gaps (${adrToCodeGaps.length})
+${adrToCodeGaps.length > 0
+                        ? adrToCodeGaps
+                            .map(g => `
+### ${g.severity === 'error' ? '❌' : '⚠️'} ${g.title}
+- **ADR:** ${g.adr_path}
+- **Referenced File:** ${g.referenced_file}
+- **Description:** ${g.description}
+`)
+                            .join('\n')
+                        : '*No ADR-to-code gaps found*'}
+
+---
+
+## Code-to-ADR Gaps (${codeToAdrGaps.length})
+${codeToAdrGaps.length > 0
+                        ? codeToAdrGaps
+                            .map(g => `
+### ${g.severity === 'error' ? '❌' : '⚠️'} ${g.title}
+- **Pattern Type:** ${g.detected_pattern}
+- **Code Files:** ${g.code_files?.join(', ')}
+- **Suggested ADR Title:** "${g.suggested_adr_title}"
+- **Description:** ${g.description}
+`)
+                            .join('\n')
+                        : '*No code-to-ADR gaps found*'}
+
+---
+
+## Recommendations
+
+${gaps.length === 0
+                        ? '✅ **Great job!** Your ADRs are well-aligned with your codebase.'
+                        : `
+Based on the analysis, consider the following actions:
+
+${errorGaps.length > 0 ? '### High Priority (Errors)\n' + errorGaps.map(g => `- ${g.gap_type === 'adr_to_code' ? `Fix or remove reference to \`${g.referenced_file}\` in ${g.adr_path}` : `Create ADR: "${g.suggested_adr_title}"`}`).join('\n') : ''}
+
+${warningGaps.length > 0 ? '### Medium Priority (Warnings)\n' + warningGaps.map(g => `- ${g.gap_type === 'adr_to_code' ? `Fix or remove reference to \`${g.referenced_file}\` in ${g.adr_path}` : `Consider creating ADR: "${g.suggested_adr_title}"`}`).join('\n') : ''}
+`}
+
+---
+
+*Analysis performed at ${new Date().toISOString()}*
+${reportToAggregator ? `\nView in dashboard: ${client.getBaseUrl()}/mcp-dashboard` : ''}
+`,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof McpAdrError ? error.message : String(error);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `# Gap Analysis Failed
+
+**Error:** ${errorMessage}
+
+Please check:
+1. PROJECT_PATH is set correctly
+2. The project directory exists and is readable
+3. ADR_AGGREGATOR_API_KEY is set if reporting to aggregator`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}
+/**
+ * Get current gaps from ADR Aggregator
+ */
+export async function getGaps(args, context) {
+    const client = getAdrAggregatorClient();
+    ensureConfigured(client);
+    const config = loadConfig();
+    const resolvedProjectPath = args.projectPath || config.projectPath;
+    ensureGitRepo(resolvedProjectPath);
+    try {
+        const repositoryName = client.getRepositoryName(resolvedProjectPath);
+        context?.info(`Fetching gaps for ${repositoryName}...`);
+        context?.report_progress(30, 100);
+        const response = await client.getCodeGaps({
+            repository_name: repositoryName,
+            ...(args.includeDismissed !== undefined && { include_dismissed: args.includeDismissed }),
+            ...(args.includeResolved !== undefined && { include_resolved: args.includeResolved }),
+        });
+        context?.report_progress(100, 100);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `# Current Gaps for ${response.repository}
+
+## Summary
+- **Total Gaps:** ${response.summary.total}
+- **By Type:** ADR→Code: ${response.summary.by_type.adr_to_code || 0}, Code→ADR: ${response.summary.by_type.code_to_adr || 0}
+- **By Severity:** Errors: ${response.summary.by_severity.error || 0}, Warnings: ${response.summary.by_severity.warning || 0}, Info: ${response.summary.by_severity.info || 0}
+- **By Status:** Open: ${response.summary.by_status['open'] || 0}, Dismissed: ${response.summary.by_status['dismissed'] || 0}, Resolved: ${response.summary.by_status['resolved'] || 0}
+
+## Gaps
+${response.gaps.length > 0
+                        ? response.gaps
+                            .map(g => `
+### ${g.severity === 'error' ? '❌' : g.severity === 'warning' ? '⚠️' : 'ℹ️'} ${g.title}
+- **ID:** ${g.id}
+- **Type:** ${g.gap_type}
+- **Status:** ${g.status}
+- **First Detected:** ${g.first_detected}
+- **Last Seen:** ${g.last_seen}
+${g.adr_path ? `- **ADR:** ${g.adr_path}` : ''}
+${g.referenced_file ? `- **Referenced File:** ${g.referenced_file}` : ''}
+${g.code_files ? `- **Code Files:** ${g.code_files.join(', ')}` : ''}
+${g.suggested_adr_title ? `- **Suggested ADR:** "${g.suggested_adr_title}"` : ''}
+`)
+                            .join('\n')
+                        : '*No gaps found*'}
+`,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof McpAdrError ? error.message : String(error);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `# Failed to Get Gaps
+
+**Error:** ${errorMessage}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}
+//# sourceMappingURL=analyze-gaps-tool.js.map