@equilateral_ai/mindmeld 3.0.0

package/src/core/PatternValidator.js

@@ -0,0 +1,355 @@
+/**
+ * PatternValidator - Validates discovered patterns against enforced standards
+ *
+ * Phase 3 of Rapport Standards Integration
+ * Checks discovered patterns for violations of organization standards
+ * Generates actionable guidance with team evidence
+ *
+ * @module PatternValidator
+ */
+
+const { executeQuery } = require('../handlers/helpers/dbOperations');
+
+class PatternValidator {
+  constructor() {
+    this.severityLevels = {
+      enforced: 'critical',
+      validated: 'warning',
+      provisional: 'info'
+    };
+  }
+
+  /**
+   * Validate a discovered pattern against enforced standards
+   *
+   * @param {Object} discoveredPattern - Pattern to validate
+   * @param {string} discoveredPattern.element - Pattern element (e.g., "Lambda DB Connection")
+   * @param {string} discoveredPattern.rule - Pattern rule (e.g., "Use connection pools")
+   * @param {string} discoveredPattern.project_id - Project where pattern was discovered
+   * @param {string} discoveredPattern.context - Additional context for validation
+   * @returns {Promise<Object>} Validation result with violations if any
+   */
+  async validatePattern(discoveredPattern) {
+    const { element, rule, project_id, context = {} } = discoveredPattern;
+
+    // Check against enforced standards
+    const violations = await this.checkViolations(element, rule, context);
+
+    if (violations.length > 0) {
+      return {
+        valid: false,
+        violations: await Promise.all(
+          violations.map(async (v) => ({
+            standard: v.pattern_id,
+            element: v.element,
+            rule: v.rule,
+            severity: this.getSeverity(v.maturity),
+            guidance: this.generateGuidance(v, discoveredPattern),
+            examples: v.examples || [],
+            teamEvidence: await this.getTeamEvidence(v.element, project_id),
+            costImpact: v.cost_impact || null,
+            antiPattern: v.anti_patterns || null
+          }))
+        )
+      };
+    }
+
+    return { valid: true };
+  }
+
+  /**
+   * Check for violations against standards
+   *
+   * @param {string} element - Pattern element to check
+   * @param {string} rule - Pattern rule to check
+   * @param {Object} context - Additional context for validation
+   * @returns {Promise<Array>} Array of violated standards
+   */
+  async checkViolations(element, rule, context = {}) {
+    // Query for conflicting standards
+    const query = `
+      SELECT
+        pattern_id,
+        element,
+        rule,
+        maturity,
+        anti_patterns,
+        examples,
+        cost_impact,
+        category
+      FROM rapport.standards_patterns
+      WHERE element ILIKE $1
+        AND maturity IN ('enforced', 'validated')
+        AND rule != $2
+      ORDER BY
+        CASE maturity
+          WHEN 'enforced' THEN 1
+          WHEN 'validated' THEN 2
+          ELSE 3
+        END
+    `;
+
+    try {
+      const result = await executeQuery(query, [`%${element}%`, rule]);
+
+      // Additional context-based filtering
+      const violations = result.rows.filter(standard =>
+        this.matchesContext(standard, context)
+      );
+
+      return violations;
+    } catch (error) {
+      console.error('Error checking violations:', error);
+      throw new Error(`Failed to check violations: ${error.message}`);
+    }
+  }
+
+  /**
+   * Check if standard matches the provided context
+   *
+   * @param {Object} standard - Standard to check
+   * @param {Object} context - Context to match against
+   * @returns {boolean} True if standard applies to this context
+   */
+  matchesContext(standard, context) {
+    // If no applicable_files filter, standard applies everywhere
+    if (!standard.applicable_files || standard.applicable_files.length === 0) {
+      return true;
+    }
+
+    // If context has file information, check if it matches
+    if (context.currentFile) {
+      return standard.applicable_files.some(pattern => {
+        // Simple glob-like matching
+        const regex = new RegExp(
+          pattern.replace(/\*/g, '.*').replace(/\?/g, '.')
+        );
+        return regex.test(context.currentFile);
+      });
+    }
+
+    // Default to applying the standard
+    return true;
+  }
+
+  /**
+   * Get severity level based on maturity
+   *
+   * @param {string} maturity - Standard maturity level
+   * @returns {string} Severity level
+   */
+  getSeverity(maturity) {
+    return this.severityLevels[maturity] || 'info';
+  }
+
+  /**
+   * Generate actionable guidance for a violation
+   *
+   * @param {Object} violation - Violated standard
+   * @param {Object} discoveredPattern - Pattern that violated the standard
+   * @returns {Object} Guidance object with problem, fix, and rationale
+   */
+  generateGuidance(violation, discoveredPattern) {
+    const guidance = {
+      problem: `Pattern violates ${violation.element} standard`,
+      standard: violation.pattern_id,
+      violatedRule: discoveredPattern.rule,
+      correctRule: violation.rule,
+      fix: null,
+      why: null,
+      category: violation.category
+    };
+
+    // Extract fix from examples if available
+    if (violation.examples && violation.examples.length > 0) {
+      const firstExample = violation.examples[0];
+      guidance.fix = typeof firstExample === 'string'
+        ? firstExample
+        : firstExample.code || firstExample.description;
+    }
+
+    // Extract rationale from cost impact or anti-patterns
+    if (violation.cost_impact) {
+      if (typeof violation.cost_impact === 'string') {
+        guidance.why = violation.cost_impact;
+      } else if (violation.cost_impact.description) {
+        guidance.why = violation.cost_impact.description;
+      } else if (violation.cost_impact.monthly_cost) {
+        guidance.why = `Cost impact: ${violation.cost_impact.monthly_cost}`;
+      }
+    } else if (violation.anti_patterns) {
+      const antiPattern = Array.isArray(violation.anti_patterns)
+        ? violation.anti_patterns[0]
+        : violation.anti_patterns;
+
+      if (typeof antiPattern === 'string') {
+        guidance.why = antiPattern;
+      } else if (antiPattern.reason) {
+        guidance.why = antiPattern.reason;
+      }
+    }
+
+    // Default rationale if none found
+    if (!guidance.why) {
+      guidance.why = 'Proven pattern from team experience and organization standards';
+    }
+
+    return guidance;
+  }
+
+  /**
+   * Get team evidence that reinforces this standard
+   *
+   * @param {string} element - Pattern element
+   * @param {string} project_id - Project ID for team context
+   * @returns {Promise<Array>} Array of team evidence records
+   */
+  async getTeamEvidence(element, project_id) {
+    const query = `
+      SELECT
+        pu.email_address,
+        p.project_id,
+        COUNT(*) as usage_count,
+        SUM(CASE WHEN pu.success THEN 1 ELSE 0 END) as success_count,
+        ROUND(
+          AVG(CASE WHEN pu.success THEN 1.0 ELSE 0.0 END)::numeric,
+          2
+        ) as success_correlation,
+        MAX(pu.used_at) as last_used
+      FROM rapport.pattern_usage pu
+      JOIN rapport.patterns p ON pu.pattern_id = p.pattern_id
+      WHERE p.intent ILIKE $1
+        AND (p.project_id = $2 OR $2 IS NULL)
+      GROUP BY pu.email_address, p.project_id
+      HAVING COUNT(*) > 0
+      ORDER BY success_correlation DESC, usage_count DESC
+      LIMIT 5
+    `;
+
+    try {
+      const result = await executeQuery(query, [`%${element}%`, project_id]);
+      return result.rows.map(row => ({
+        user: row.email_address,
+        project: row.project_id,
+        usageCount: parseInt(row.usage_count),
+        successCount: parseInt(row.success_count),
+        successRate: parseFloat(row.success_correlation),
+        lastUsed: row.last_used
+      }));
+    } catch (error) {
+      console.error('Error fetching team evidence:', error);
+      return [];
+    }
+  }
+
+  /**
+   * Validate multiple patterns in bulk
+   *
+   * @param {Array<Object>} patterns - Array of patterns to validate
+   * @returns {Promise<Object>} Validation summary with all violations
+   */
+  async validatePatterns(patterns) {
+    const results = await Promise.all(
+      patterns.map(pattern => this.validatePattern(pattern))
+    );
+
+    const violations = results
+      .filter(result => !result.valid)
+      .flatMap(result => result.violations);
+
+    return {
+      totalPatterns: patterns.length,
+      validPatterns: results.filter(r => r.valid).length,
+      invalidPatterns: results.filter(r => !r.valid).length,
+      criticalViolations: violations.filter(v => v.severity === 'critical').length,
+      warningViolations: violations.filter(v => v.severity === 'warning').length,
+      violations: violations
+    };
+  }
+
+  /**
+   * Get all anti-patterns for a specific category
+   *
+   * @param {string} category - Category to get anti-patterns for
+   * @returns {Promise<Array>} Array of anti-patterns with details
+   */
+  async getAntiPatterns(category) {
+    const query = `
+      SELECT
+        pattern_id,
+        element,
+        rule,
+        anti_patterns,
+        cost_impact,
+        examples
+      FROM rapport.standards_patterns
+      WHERE category = $1
+        AND maturity = 'enforced'
+        AND anti_patterns IS NOT NULL
+      ORDER BY pattern_id
+    `;
+
+    try {
+      const result = await executeQuery(query, [category]);
+      return result.rows.map(row => ({
+        patternId: row.pattern_id,
+        element: row.element,
+        correctRule: row.rule,
+        antiPatterns: row.anti_patterns,
+        costImpact: row.cost_impact,
+        examples: row.examples
+      }));
+    } catch (error) {
+      console.error('Error fetching anti-patterns:', error);
+      throw new Error(`Failed to fetch anti-patterns: ${error.message}`);
+    }
+  }
+
+  /**
+   * Format validation result for display
+   *
+   * @param {Object} validationResult - Result from validatePattern
+   * @returns {string} Formatted text output
+   */
+  formatValidationResult(validationResult) {
+    if (validationResult.valid) {
+      return '✓ Pattern is compliant with standards';
+    }
+
+    const lines = ['✗ Pattern violates organization standards:\n'];
+
+    validationResult.violations.forEach((violation, index) => {
+      const severityIcon = {
+        critical: '🚨',
+        warning: '⚠️',
+        info: 'ℹ️'
+      }[violation.severity] || '•';
+
+      lines.push(`${severityIcon} Violation ${index + 1}: ${violation.guidance.problem}`);
+      lines.push(`   Standard: ${violation.standard}`);
+      lines.push(`   Severity: ${violation.severity.toUpperCase()}`);
+      lines.push(`   Your pattern: "${violation.guidance.violatedRule}"`);
+      lines.push(`   Standard rule: "${violation.guidance.correctRule}"`);
+
+      if (violation.guidance.why) {
+        lines.push(`   Why: ${violation.guidance.why}`);
+      }
+
+      if (violation.guidance.fix) {
+        lines.push(`   Fix: ${violation.guidance.fix}`);
+      }
+
+      if (violation.teamEvidence && violation.teamEvidence.length > 0) {
+        lines.push(`   Team evidence: ${violation.teamEvidence.length} team members have used this pattern`);
+        const topEvidence = violation.teamEvidence[0];
+        lines.push(`   - ${topEvidence.user}: ${topEvidence.successRate * 100}% success rate (${topEvidence.usageCount} uses)`);
+      }
+
+      lines.push('');
+    });
+
+    return lines.join('\n');
+  }
+}
+
+module.exports = { PatternValidator };

package/src/core/README.md

@@ -0,0 +1,160 @@
+# Rapport Core Components
+
+This directory contains the core components of the Rapport Standards Integration system.
+
+## Components
+
+### RelevanceDetector.js (Phase 2) ✅
+
+**Purpose**: Identifies which standards apply to current work
+
+**Key Features**:
+- Fast project characteristic detection (< 100ms)
+- Intelligent category mapping
+- Relevance scoring algorithm (0-100)
+- Returns top 10 most relevant standards
+- Database integration with Phase 1 schema
+
+**Usage**:
+```javascript
+const { RelevanceDetector } = require('./src/core/RelevanceDetector');
+
+const detector = new RelevanceDetector({
+    workingDirectory: process.cwd()
+});
+
+const result = await detector.detectRelevantStandards({
+    projectId: 'prj_example',
+    currentFile: 'src/handlers/userCreate.js'
+});
+
+console.log(`Found ${result.standards.length} relevant standards`);
+// Execution time: ~250ms
+```
+
+**Documentation**: `/Users/jamesford/Source/rapport/docs/PHASE_2_RELEVANCE_DETECTION.md`
+
+**Test Suite**: `/Users/jamesford/Source/rapport/scripts/test-relevance-detection.js`
+
+---
+
+### TeamLoadBearingDetector.js (Existing)
+
+**Purpose**: Detects load-bearing context elements from team sessions
+
+**Key Features**:
+- Team-wide correlation analysis
+- User-specific pattern tracking
+- Confidence scoring
+- Statistical significance testing
+
+---
+
+## Phase Implementation Status
+
+| Phase | Status | Component | Documentation |
+|-------|--------|-----------|---------------|
+| Phase 1 | Pending | StandardsIngestion.js | - |
+| Phase 2 | ✅ Complete | RelevanceDetector.js | PHASE_2_RELEVANCE_DETECTION.md |
+| Phase 3 | Pending | PatternValidator.js | - |
+| Phase 4 | Pending | CurationEngine.js | - |
+| Phase 5 | Pending | Hooks (session-start, pre-compact) | - |
+| Phase 6 | Pending | RapportOrchestrator.js | - |
+
+---
+
+## Testing
+
+```bash
+# Test RelevanceDetector
+node scripts/test-relevance-detection.js
+
+# Quick validation
+node -e "
+const { RelevanceDetector } = require('./src/core/RelevanceDetector');
+const detector = new RelevanceDetector();
+console.log('✓ RelevanceDetector ready');
+"
+```
+
+---
+
+## Integration
+
+### With Claude Code (Phase 5)
+
+```javascript
+// rapport/hooks/session-start.js
+const { RelevanceDetector } = require('@mindmeld/rapport/relevance');
+
+async function injectContext() {
+    const detector = new RelevanceDetector({
+        workingDirectory: process.cwd()
+    });
+
+    const result = await detector.detectRelevantStandards({
+        projectId: getCurrentProjectId(),
+        currentFile: getCurrentFile()
+    });
+
+    return detector.formatForInjection(result.standards);
+}
+```
+
+### With Pattern Validation (Phase 3)
+
+```javascript
+// rapport/src/core/PatternValidator.js
+const { RelevanceDetector } = require('./RelevanceDetector');
+
+async function validatePattern(pattern) {
+    const detector = new RelevanceDetector();
+    const relevant = await detector.detectRelevantStandards(context);
+
+    // Validate against only relevant standards
+    return checkAgainstStandards(pattern, relevant.standards);
+}
+```
+
+---
+
+## Database Requirements
+
+All core components require PostgreSQL database with Rapport schema.
+
+**Connection**: Uses `src/handlers/helpers/dbOperations.js`
+
+**Schema**: See `database/schema.sql`
+
+**Environment Variables**:
+- `DB_HOST`
+- `DB_PORT`
+- `DB_NAME`
+- `DB_USER`
+- `DB_PASSWORD`
+
+---
+
+## Performance Targets
+
+| Component | Target | Actual |
+|-----------|--------|--------|
+| RelevanceDetector | < 500ms | ~250ms ✓ |
+| TeamLoadBearingDetector | < 1s | ~800ms ✓ |
+
+---
+
+## Contributing
+
+When adding new core components:
+
+1. Follow existing patterns (constructor with options)
+2. Use `executeQuery` from dbOperations.js
+3. Include comprehensive JSDoc comments
+4. Create test script in `scripts/`
+5. Document in `docs/PHASE_X_*.md`
+6. Update this README
+
+---
+
+**Last Updated**: 2025-12-20