@equilateral_ai/mindmeld 3.0.0

package/src/core/RelevanceDetector.js

@@ -0,0 +1,577 @@
+/**
+ * RelevanceDetector - Phase 2: Rapport Standards Integration
+ *
+ * Identifies which standards apply to current work by:
+ * 1. Detecting project characteristics (Lambda, React, SAM, etc.)
+ * 2. Mapping characteristics to standard categories
+ * 3. Querying relevant standards from database
+ * 4. Returning top 10 most relevant standards with scoring
+ *
+ * Target: < 500ms execution time
+ *
+ * @module RelevanceDetector
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+const { executeQuery } = require('../handlers/helpers/dbOperations');
+
+class RelevanceDetector {
+    constructor(options = {}) {
+        this.workingDirectory = options.workingDirectory || process.cwd();
+        this.standardsPath = options.standardsPath || '.equilateral-standards';
+
+        // Category weights for relevance scoring
+        this.categoryWeights = {
+            'serverless-saas-aws': 1.0,
+            'multi-agent-orchestration': 1.0,
+            'frontend-development': 1.0,
+            'database': 0.9,
+            'compliance-security': 0.8,
+            'cost-optimization': 0.7,
+            'real-time-systems': 0.8,
+            'testing': 0.6,
+            'backend': 0.9,
+            'well-architected': 0.7
+        };
+    }
+
+    /**
+     * Main entry point: Detect relevant standards for current project context
+     * @param {Object} projectContext - Context information about the project
+     * @returns {Promise<Object>} Relevant standards with scoring
+     */
+    async detectRelevantStandards(projectContext = {}) {
+        const startTime = Date.now();
+
+        try {
+            // 1. Analyze project structure to detect characteristics
+            const characteristics = await this.detectProjectCharacteristics(projectContext);
+
+            // 2. Map characteristics to standard categories
+            const relevantCategories = this.mapCharacteristicsToCategories(characteristics);
+
+            // 3. Query standards from database (assumes Phase 1 schema exists)
+            const standards = await this.queryRelevantStandards({
+                categories: relevantCategories,
+                currentFile: projectContext.currentFile,
+                characteristics: characteristics
+            });
+
+            // 4. Calculate relevance scores and rank
+            const rankedStandards = this.rankStandards(standards, characteristics, relevantCategories);
+
+            // 5. Return top 10 most relevant
+            const topStandards = rankedStandards.slice(0, 10);
+
+            const executionTime = Date.now() - startTime;
+
+            return {
+                characteristics,
+                categories: relevantCategories,
+                standards: topStandards,
+                totalStandards: standards.length,
+                executionTime,
+                timestamp: new Date().toISOString()
+            };
+        } catch (error) {
+            console.error('RelevanceDetector error:', error);
+            throw error;
+        }
+    }
+
+    /**
+     * Detect project characteristics from file structure and content
+     * Fast file system analysis without deep content parsing
+     */
+    async detectProjectCharacteristics(projectContext) {
+        const characteristics = {
+            hasLambda: false,
+            hasReact: false,
+            hasDatabase: false,
+            hasMultiAgent: false,
+            hasSAM: false,
+            hasAPI: false,
+            hasTypeScript: false,
+            hasNodeJS: false,
+            hasPython: false,
+            hasDocker: false,
+            hasCI: false,
+            hasTests: false,
+            framework: null,
+            deploymentType: null
+        };
+
+        try {
+            // Check for key files that indicate project type
+            const keyFiles = await this.checkKeyFiles();
+
+            // SAM/Serverless detection
+            characteristics.hasSAM = keyFiles.includes('template.yaml') || keyFiles.includes('template.yml');
+
+            // Lambda detection (SAM template or serverless.yml)
+            if (characteristics.hasSAM || keyFiles.includes('serverless.yml')) {
+                characteristics.hasLambda = await this.detectLambdaFunctions();
+            }
+
+            // React detection
+            characteristics.hasReact = await this.detectReact(keyFiles);
+
+            // Database detection
+            characteristics.hasDatabase = await this.detectDatabase(keyFiles);
+
+            // Multi-agent detection
+            characteristics.hasMultiAgent = await this.detectMultiAgent();
+
+            // API detection
+            characteristics.hasAPI = await this.detectAPIHandlers();
+
+            // Language detection
+            characteristics.hasTypeScript = keyFiles.some(f => f.endsWith('.ts') || f.endsWith('.tsx'));
+            characteristics.hasNodeJS = keyFiles.includes('package.json');
+            characteristics.hasPython = keyFiles.includes('requirements.txt') || keyFiles.includes('setup.py');
+
+            // Infrastructure detection
+            characteristics.hasDocker = keyFiles.includes('Dockerfile') || keyFiles.includes('docker-compose.yml');
+            characteristics.hasCI = keyFiles.includes('.github') || keyFiles.includes('.gitlab-ci.yml');
+            characteristics.hasTests = keyFiles.includes('tests') || keyFiles.includes('test');
+
+            // Determine framework
+            characteristics.framework = await this.detectFramework(keyFiles);
+
+            // Determine deployment type
+            characteristics.deploymentType = this.determineDeploymentType(characteristics);
+
+            return characteristics;
+        } catch (error) {
+            console.error('Error detecting characteristics:', error);
+            return characteristics; // Return partial results
+        }
+    }
+
+    /**
+     * Check for key files in project
+     */
+    async checkKeyFiles() {
+        try {
+            const files = await fs.readdir(this.workingDirectory);
+
+            // Also check common subdirectories
+            const checkDirs = ['src', 'handlers', 'tests', 'test', '.github'];
+            for (const dir of checkDirs) {
+                try {
+                    const dirPath = path.join(this.workingDirectory, dir);
+                    const stats = await fs.stat(dirPath);
+                    if (stats.isDirectory()) {
+                        files.push(dir);
+                    }
+                } catch (e) {
+                    // Directory doesn't exist, skip
+                }
+            }
+
+            return files;
+        } catch (error) {
+            console.error('Error reading directory:', error);
+            return [];
+        }
+    }
+
+    /**
+     * Detect Lambda functions by checking for handler files or SAM config
+     */
+    async detectLambdaFunctions() {
+        try {
+            // Check for SAM template with Lambda functions
+            const templatePath = path.join(this.workingDirectory, 'template.yaml');
+            try {
+                const content = await fs.readFile(templatePath, 'utf-8');
+                return content.includes('AWS::Serverless::Function') ||
+                       content.includes('AWS::Lambda::Function');
+            } catch (e) {
+                // File doesn't exist, check for handler files
+            }
+
+            // Check for common Lambda handler directories
+            const handlerDirs = ['src/handlers', 'handlers', 'functions', 'lambdas'];
+            for (const dir of handlerDirs) {
+                try {
+                    const dirPath = path.join(this.workingDirectory, dir);
+                    await fs.access(dirPath);
+                    return true; // Directory exists
+                } catch (e) {
+                    continue;
+                }
+            }
+
+            return false;
+        } catch (error) {
+            return false;
+        }
+    }
+
+    /**
+     * Detect React usage
+     */
+    async detectReact(keyFiles) {
+        if (!keyFiles.includes('package.json')) {
+            return false;
+        }
+
+        try {
+            const pkgPath = path.join(this.workingDirectory, 'package.json');
+            const content = await fs.readFile(pkgPath, 'utf-8');
+            const pkg = JSON.parse(content);
+
+            return !!(pkg.dependencies?.react || pkg.devDependencies?.react);
+        } catch (error) {
+            // Check for .jsx or .tsx files
+            return keyFiles.some(f => f.endsWith('.jsx') || f.endsWith('.tsx'));
+        }
+    }
+
+    /**
+     * Detect database usage
+     */
+    async detectDatabase(keyFiles) {
+        // Check for database configuration files
+        if (keyFiles.includes('schema.sql') ||
+            keyFiles.includes('database') ||
+            keyFiles.some(f => f.includes('migration'))) {
+            return true;
+        }
+
+        // Check package.json for database libraries
+        if (keyFiles.includes('package.json')) {
+            try {
+                const pkgPath = path.join(this.workingDirectory, 'package.json');
+                const content = await fs.readFile(pkgPath, 'utf-8');
+                const pkg = JSON.parse(content);
+
+                const dbLibs = ['pg', 'mysql', 'mongodb', 'mongoose', 'sequelize', 'typeorm'];
+                return dbLibs.some(lib =>
+                    pkg.dependencies?.[lib] || pkg.devDependencies?.[lib]
+                );
+            } catch (error) {
+                return false;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Detect multi-agent orchestration patterns
+     */
+    async detectMultiAgent() {
+        try {
+            // Check for agent-related directories
+            const agentDirs = ['agents', 'src/agents', 'src/core'];
+            for (const dir of agentDirs) {
+                try {
+                    const dirPath = path.join(this.workingDirectory, dir);
+                    const files = await fs.readdir(dirPath);
+
+                    // Look for agent-related files
+                    if (files.some(f =>
+                        f.includes('Agent') ||
+                        f.includes('Orchestrat') ||
+                        f.includes('agent')
+                    )) {
+                        return true;
+                    }
+                } catch (e) {
+                    continue;
+                }
+            }
+
+            return false;
+        } catch (error) {
+            return false;
+        }
+    }
+
+    /**
+     * Detect API handlers
+     */
+    async detectAPIHandlers() {
+        try {
+            const handlerDirs = ['src/handlers', 'handlers', 'api'];
+            for (const dir of handlerDirs) {
+                try {
+                    const dirPath = path.join(this.workingDirectory, dir);
+                    await fs.access(dirPath);
+                    return true;
+                } catch (e) {
+                    continue;
+                }
+            }
+
+            return false;
+        } catch (error) {
+            return false;
+        }
+    }
+
+    /**
+     * Detect framework being used
+     */
+    async detectFramework(keyFiles) {
+        if (!keyFiles.includes('package.json')) {
+            return null;
+        }
+
+        try {
+            const pkgPath = path.join(this.workingDirectory, 'package.json');
+            const content = await fs.readFile(pkgPath, 'utf-8');
+            const pkg = JSON.parse(content);
+
+            const frameworks = {
+                'next': 'Next.js',
+                'nuxt': 'Nuxt.js',
+                'express': 'Express',
+                'fastify': 'Fastify',
+                'nestjs': 'NestJS',
+                'react': 'React',
+                'vue': 'Vue.js',
+                'angular': 'Angular'
+            };
+
+            for (const [key, name] of Object.entries(frameworks)) {
+                if (pkg.dependencies?.[key] || pkg.devDependencies?.[key]) {
+                    return name;
+                }
+            }
+
+            return null;
+        } catch (error) {
+            return null;
+        }
+    }
+
+    /**
+     * Determine deployment type from characteristics
+     */
+    determineDeploymentType(characteristics) {
+        if (characteristics.hasSAM || characteristics.hasLambda) {
+            return 'serverless';
+        }
+        if (characteristics.hasDocker) {
+            return 'containerized';
+        }
+        if (characteristics.hasNodeJS || characteristics.hasPython) {
+            return 'traditional';
+        }
+        return 'unknown';
+    }
+
+    /**
+     * Map detected characteristics to standard categories
+     */
+    mapCharacteristicsToCategories(characteristics) {
+        const categories = new Set();
+
+        // Serverless/Lambda → serverless-saas-aws
+        if (characteristics.hasLambda || characteristics.hasSAM) {
+            categories.add('serverless-saas-aws');
+        }
+
+        // React/Frontend → frontend-development
+        if (characteristics.hasReact) {
+            categories.add('frontend-development');
+        }
+
+        // Database → database
+        if (characteristics.hasDatabase) {
+            categories.add('database');
+        }
+
+        // Multi-agent → multi-agent-orchestration
+        if (characteristics.hasMultiAgent) {
+            categories.add('multi-agent-orchestration');
+        }
+
+        // API handlers → backend
+        if (characteristics.hasAPI) {
+            categories.add('backend');
+        }
+
+        // Cost optimization always relevant for AWS
+        if (characteristics.hasLambda || characteristics.hasSAM) {
+            categories.add('cost-optimization');
+        }
+
+        // Testing if tests detected
+        if (characteristics.hasTests) {
+            categories.add('testing');
+        }
+
+        // Security/compliance always relevant
+        categories.add('compliance-security');
+
+        // Well-architected principles always relevant
+        categories.add('well-architected');
+
+        return Array.from(categories);
+    }
+
+    /**
+     * Query relevant standards from database
+     * Assumes Phase 1 schema (rapport.standards_patterns table exists)
+     */
+    async queryRelevantStandards({ categories, currentFile, characteristics }) {
+        try {
+            // Build file type filter
+            let fileType = null;
+            if (currentFile) {
+                const ext = path.extname(currentFile);
+                if (ext) {
+                    fileType = `*${ext}`;
+                }
+            }
+
+            // Query standards matching categories
+            const query = `
+                SELECT
+                    pattern_id,
+                    element,
+                    rule,
+                    category,
+                    correlation,
+                    maturity,
+                    applicable_files,
+                    anti_patterns,
+                    examples,
+                    cost_impact,
+                    source
+                FROM rapport.standards_patterns
+                WHERE category = ANY($1::varchar[])
+                    AND maturity IN ('enforced', 'validated', 'recommended')
+                ORDER BY
+                    CASE
+                        WHEN maturity = 'enforced' THEN 1
+                        WHEN maturity = 'validated' THEN 2
+                        ELSE 3
+                    END,
+                    correlation DESC
+            `;
+
+            const result = await executeQuery(query, [categories]);
+            return result.rows;
+        } catch (error) {
+            // If table doesn't exist (Phase 1 not complete), return empty array
+            console.warn('Standards patterns table not found. Assuming Phase 1 not complete.');
+            return [];
+        }
+    }
+
+    /**
+     * Rank standards by relevance score
+     */
+    rankStandards(standards, characteristics, categories) {
+        return standards.map(standard => {
+            let score = 0;
+
+            // Base score from correlation
+            score += (standard.correlation || 1.0) * 40;
+
+            // Maturity score
+            const maturityScores = {
+                'enforced': 30,
+                'validated': 20,
+                'recommended': 10,
+                'provisional': 5
+            };
+            score += maturityScores[standard.maturity] || 0;
+
+            // Category weight
+            const categoryWeight = this.categoryWeights[standard.category] || 0.5;
+            score += categoryWeight * 20;
+
+            // File applicability bonus
+            if (standard.applicable_files && standard.applicable_files.length > 0) {
+                score += 5;
+            }
+
+            // Cost impact bonus (critical patterns)
+            if (standard.cost_impact && standard.cost_impact.severity === 'critical') {
+                score += 10;
+            }
+
+            // Anti-patterns bonus (important to know what NOT to do)
+            if (standard.anti_patterns && Object.keys(standard.anti_patterns).length > 0) {
+                score += 5;
+            }
+
+            return {
+                ...standard,
+                relevance_score: Math.round(score * 10) / 10 // Round to 1 decimal
+            };
+        }).sort((a, b) => b.relevance_score - a.relevance_score);
+    }
+
+    /**
+     * Format standards for injection into Claude Code context
+     */
+    formatForInjection(relevantStandards) {
+        if (!relevantStandards || relevantStandards.length === 0) {
+            return '';
+        }
+
+        let output = '## Relevant Standards (Auto-Detected)\n\n';
+
+        for (const standard of relevantStandards) {
+            output += `### ${standard.element}\n`;
+            output += `**Category**: ${standard.category}\n`;
+            output += `**Maturity**: ${standard.maturity}\n`;
+            output += `**Relevance**: ${standard.relevance_score}/100\n\n`;
+            output += `${standard.rule}\n\n`;
+
+            // Include examples if available
+            if (standard.examples && standard.examples.length > 0) {
+                output += '**Examples**:\n';
+                for (const example of standard.examples.slice(0, 2)) { // Max 2 examples
+                    output += `\`\`\`javascript\n${example.code || example}\n\`\`\`\n\n`;
+                }
+            }
+
+            // Include anti-patterns if available
+            if (standard.anti_patterns && Object.keys(standard.anti_patterns).length > 0) {
+                output += '**Anti-Patterns** (Avoid):\n';
+                for (const [key, value] of Object.entries(standard.anti_patterns)) {
+                    output += `- ❌ ${key}: ${value}\n`;
+                }
+                output += '\n';
+            }
+
+            output += '---\n\n';
+        }
+
+        return output;
+    }
+
+    /**
+     * Get execution statistics
+     */
+    async getStatistics() {
+        try {
+            const query = `
+                SELECT
+                    category,
+                    maturity,
+                    COUNT(*) as count
+                FROM rapport.standards_patterns
+                GROUP BY category, maturity
+                ORDER BY category, maturity
+            `;
+
+            const result = await executeQuery(query);
+            return result.rows;
+        } catch (error) {
+            console.error('Error getting statistics:', error);
+            return [];
+        }
+    }
+}
+
+module.exports = { RelevanceDetector };