@equilateral_ai/mindmeld 3.5.3 → 4.0.1

package/src/core/CrossReferenceEngine.js

@@ -1,624 +0,0 @@
-/**
- * CrossReferenceEngine - Compare uploaded vs discovered standards
- *
- * Analyzes overlap, conflicts, and new discoveries between standards
- * that were explicitly uploaded by a team and those discovered through
- * codebase analysis or pattern detection.
- *
- * Returns:
- *   confirmed     - Both uploaded and discovered agree on the same rule
- *   conflicts     - Uploaded says one thing, discovered shows the opposite
- *   newDiscoveries - Found in discovered but not present in uploaded
- *
- * Each result item includes a confidence score (0.0 - 1.0)
- *
- * @module CrossReferenceEngine
- */
-
-/**
- * Action types considered opposite to each other
- */
-const OPPOSING_ACTIONS = {
-  'ALWAYS': 'NEVER',
-  'NEVER': 'ALWAYS',
-  'USE': 'AVOID',
-  'AVOID': 'USE',
-  'PREFER': 'AVOID'
-};
-
-/**
- * Action types considered aligned with each other
- */
-const ALIGNED_ACTIONS = {
-  'ALWAYS': ['ALWAYS', 'USE', 'PREFER'],
-  'NEVER': ['NEVER', 'AVOID'],
-  'USE': ['USE', 'ALWAYS', 'PREFER'],
-  'PREFER': ['PREFER', 'USE', 'ALWAYS'],
-  'AVOID': ['AVOID', 'NEVER']
-};
-
-class CrossReferenceEngine {
-  constructor(options = {}) {
-    this.similarityThreshold = options.similarityThreshold || 0.4;
-    this.highConfidenceThreshold = options.highConfidenceThreshold || 0.8;
-  }
-
-  /**
-   * Cross-reference uploaded standards against discovered standards
-   *
-   * @param {Array<Object>} uploaded - Standards explicitly uploaded by the team
-   *   Each item: { id, category, rules: [{ action, rule }], anti_patterns, tags }
-   * @param {Array<Object>} discovered - Standards discovered from codebase analysis
-   *   Each item: { id, category, rules: [{ action, rule }], anti_patterns, tags }
-   * @returns {Object} Cross-reference results
-   *   { confirmed: [...], conflicts: [...], newDiscoveries: [...] }
-   */
-  crossReference(uploaded, discovered) {
-    if (!Array.isArray(uploaded) || !Array.isArray(discovered)) {
-      throw new Error('Both uploaded and discovered must be arrays');
-    }
-
-    const confirmed = [];
-    const conflicts = [];
-    const newDiscoveries = [];
-
-    // Flatten all rules from uploaded standards for comparison
-    const uploadedRules = this.flattenRules(uploaded);
-    const discoveredRules = this.flattenRules(discovered);
-
-    // Track which discovered rules have been matched
-    const matchedDiscoveredIndices = new Set();
-
-    // Compare each discovered rule against all uploaded rules
-    for (let dIdx = 0; dIdx < discoveredRules.length; dIdx++) {
-      const discoveredRule = discoveredRules[dIdx];
-      let bestMatch = null;
-      let bestSimilarity = 0;
-
-      for (let uIdx = 0; uIdx < uploadedRules.length; uIdx++) {
-        const uploadedRule = uploadedRules[uIdx];
-
-        const similarity = this.computeRuleSimilarity(uploadedRule, discoveredRule);
-
-        if (similarity > bestSimilarity && similarity >= this.similarityThreshold) {
-          bestSimilarity = similarity;
-          bestMatch = { uploadedRule, uploadedIndex: uIdx, similarity };
-        }
-      }
-
-      if (bestMatch) {
-        matchedDiscoveredIndices.add(dIdx);
-
-        const isAligned = this.areActionsAligned(
-          bestMatch.uploadedRule.action,
-          discoveredRule.action
-        );
-
-        const isConflicting = this.areActionsConflicting(
-          bestMatch.uploadedRule.action,
-          discoveredRule.action
-        );
-
-        if (isAligned) {
-          confirmed.push({
-            uploaded: {
-              standardId: bestMatch.uploadedRule.standardId,
-              action: bestMatch.uploadedRule.action,
-              rule: bestMatch.uploadedRule.rule,
-              category: bestMatch.uploadedRule.category
-            },
-            discovered: {
-              standardId: discoveredRule.standardId,
-              action: discoveredRule.action,
-              rule: discoveredRule.rule,
-              category: discoveredRule.category
-            },
-            confidence: this.computeConfirmationConfidence(bestMatch.similarity, bestMatch.uploadedRule, discoveredRule),
-            matchType: 'confirmed',
-            similarity: bestMatch.similarity
-          });
-        } else if (isConflicting) {
-          conflicts.push({
-            uploaded: {
-              standardId: bestMatch.uploadedRule.standardId,
-              action: bestMatch.uploadedRule.action,
-              rule: bestMatch.uploadedRule.rule,
-              category: bestMatch.uploadedRule.category
-            },
-            discovered: {
-              standardId: discoveredRule.standardId,
-              action: discoveredRule.action,
-              rule: discoveredRule.rule,
-              category: discoveredRule.category
-            },
-            confidence: this.computeConflictConfidence(bestMatch.similarity, bestMatch.uploadedRule, discoveredRule),
-            matchType: 'conflict',
-            similarity: bestMatch.similarity,
-            reason: this.describeConflict(bestMatch.uploadedRule, discoveredRule)
-          });
-        } else {
-          // Ambiguous match - related but not clearly aligned or conflicting
-          // Treat as confirmed with lower confidence
-          confirmed.push({
-            uploaded: {
-              standardId: bestMatch.uploadedRule.standardId,
-              action: bestMatch.uploadedRule.action,
-              rule: bestMatch.uploadedRule.rule,
-              category: bestMatch.uploadedRule.category
-            },
-            discovered: {
-              standardId: discoveredRule.standardId,
-              action: discoveredRule.action,
-              rule: discoveredRule.rule,
-              category: discoveredRule.category
-            },
-            confidence: bestMatch.similarity * 0.5,
-            matchType: 'partial',
-            similarity: bestMatch.similarity
-          });
-        }
-      } else {
-        // No match found - this is a new discovery
-        matchedDiscoveredIndices.add(dIdx);
-        newDiscoveries.push({
-          discovered: {
-            standardId: discoveredRule.standardId,
-            action: discoveredRule.action,
-            rule: discoveredRule.rule,
-            category: discoveredRule.category
-          },
-          confidence: this.computeDiscoveryConfidence(discoveredRule),
-          matchType: 'new_discovery'
-        });
-      }
-    }
-
-    // Also check anti-patterns cross-references
-    const antiPatternResults = this.crossReferenceAntiPatterns(uploaded, discovered);
-    confirmed.push(...antiPatternResults.confirmed);
-    conflicts.push(...antiPatternResults.conflicts);
-
-    // Sort each result set by confidence descending
-    confirmed.sort((a, b) => b.confidence - a.confidence);
-    conflicts.sort((a, b) => b.confidence - a.confidence);
-    newDiscoveries.sort((a, b) => b.confidence - a.confidence);
-
-    return {
-      confirmed,
-      conflicts,
-      newDiscoveries,
-      summary: {
-        totalUploaded: uploadedRules.length,
-        totalDiscovered: discoveredRules.length,
-        confirmedCount: confirmed.length,
-        conflictCount: conflicts.length,
-        newDiscoveryCount: newDiscoveries.length,
-        overallAlignment: this.computeOverallAlignment(confirmed, conflicts, newDiscoveries)
-      }
-    };
-  }
-
-  /**
-   * Flatten standards objects into individual rule records for comparison
-   *
-   * @param {Array<Object>} standards - Array of standards objects
-   * @returns {Array<Object>} Flattened rule records
-   */
-  flattenRules(standards) {
-    const flattened = [];
-
-    for (const standard of standards) {
-      const rules = Array.isArray(standard.rules) ? standard.rules : [];
-
-      for (const rule of rules) {
-        flattened.push({
-          standardId: standard.id || 'unknown',
-          category: standard.category || 'general',
-          action: rule.action || 'USE',
-          rule: rule.rule || '',
-          tags: standard.tags || [],
-          priority: standard.priority || 30
-        });
-      }
-    }
-
-    return flattened;
-  }
-
-  /**
-   * Compute similarity between two rules using text and semantic analysis
-   *
-   * @param {Object} ruleA - First rule
-   * @param {Object} ruleB - Second rule
-   * @returns {number} Similarity score (0.0 - 1.0)
-   */
-  computeRuleSimilarity(ruleA, ruleB) {
-    const textA = ruleA.rule.toLowerCase();
-    const textB = ruleB.rule.toLowerCase();
-
-    // Exact match
-    if (textA === textB) return 1.0;
-
-    // Token-based similarity (Jaccard)
-    const tokensA = this.tokenize(textA);
-    const tokensB = this.tokenize(textB);
-    const jaccardScore = this.jaccardSimilarity(tokensA, tokensB);
-
-    // Category match bonus
-    const categoryBonus = ruleA.category === ruleB.category ? 0.1 : 0;
-
-    // Tag overlap bonus
-    const tagOverlap = this.computeTagOverlap(ruleA.tags, ruleB.tags);
-    const tagBonus = tagOverlap * 0.05;
-
-    // Substring containment bonus
-    let containmentBonus = 0;
-    if (textA.includes(textB) || textB.includes(textA)) {
-      containmentBonus = 0.2;
-    }
-
-    // Key term match (technical terms carry more weight)
-    const keyTermScore = this.computeKeyTermOverlap(tokensA, tokensB);
-
-    // Weighted combination
-    const score = Math.min(1.0,
-      (jaccardScore * 0.4) +
-      (keyTermScore * 0.3) +
-      containmentBonus +
-      categoryBonus +
-      tagBonus
-    );
-
-    return Math.round(score * 100) / 100;
-  }
-
-  /**
-   * Tokenize text into meaningful words
-   *
-   * @param {string} text - Text to tokenize
-   * @returns {Set<string>} Set of tokens
-   */
-  tokenize(text) {
-    const stopWords = new Set([
-      'the', 'a', 'an', 'is', 'are', 'was', 'were', 'be', 'been',
-      'to', 'of', 'in', 'for', 'on', 'with', 'at', 'by', 'from',
-      'and', 'or', 'but', 'not', 'no', 'do', 'does', 'did',
-      'this', 'that', 'it', 'its', 'all', 'any', 'each', 'some',
-      'should', 'must', 'shall', 'will', 'can', 'may',
-      'use', 'using', 'used'
-    ]);
-
-    const words = text
-      .replace(/[^a-z0-9\s-]/g, ' ')
-      .split(/\s+/)
-      .filter(w => w.length > 1 && !stopWords.has(w));
-
-    return new Set(words);
-  }
-
-  /**
-   * Compute Jaccard similarity between two token sets
-   *
-   * @param {Set<string>} setA - First token set
-   * @param {Set<string>} setB - Second token set
-   * @returns {number} Jaccard similarity (0.0 - 1.0)
-   */
-  jaccardSimilarity(setA, setB) {
-    if (setA.size === 0 && setB.size === 0) return 0;
-
-    let intersection = 0;
-    for (const token of setA) {
-      if (setB.has(token)) intersection++;
-    }
-
-    const union = setA.size + setB.size - intersection;
-    return union > 0 ? intersection / union : 0;
-  }
-
-  /**
-   * Compute overlap of technical key terms between token sets
-   *
-   * @param {Set<string>} tokensA - First token set
-   * @param {Set<string>} tokensB - Second token set
-   * @returns {number} Key term overlap score (0.0 - 1.0)
-   */
-  computeKeyTermOverlap(tokensA, tokensB) {
-    // Technical terms carry more semantic weight
-    const technicalTerms = new Set([
-      'async', 'await', 'promise', 'callback', 'error', 'exception',
-      'variable', 'function', 'class', 'interface', 'type', 'const', 'let', 'var',
-      'import', 'export', 'module', 'require', 'dependency',
-      'database', 'query', 'sql', 'connection', 'pool', 'transaction',
-      'api', 'rest', 'graphql', 'endpoint', 'handler', 'middleware',
-      'lambda', 'serverless', 'aws', 'cloud', 'deploy',
-      'react', 'component', 'state', 'hook', 'render', 'props',
-      'test', 'mock', 'assert', 'coverage', 'jest',
-      'security', 'auth', 'token', 'encryption', 'validation',
-      'log', 'console', 'debug', 'monitor', 'trace',
-      'cache', 'performance', 'optimization', 'memory',
-      'unused', 'deprecated', 'legacy'
-    ]);
-
-    const keyTermsA = new Set([...tokensA].filter(t => technicalTerms.has(t)));
-    const keyTermsB = new Set([...tokensB].filter(t => technicalTerms.has(t)));
-
-    if (keyTermsA.size === 0 && keyTermsB.size === 0) return 0;
-
-    return this.jaccardSimilarity(keyTermsA, keyTermsB);
-  }
-
-  /**
-   * Compute tag overlap between two tag arrays
-   *
-   * @param {Array<string>} tagsA - First tag set
-   * @param {Array<string>} tagsB - Second tag set
-   * @returns {number} Tag overlap ratio (0.0 - 1.0)
-   */
-  computeTagOverlap(tagsA, tagsB) {
-    if (!tagsA || !tagsB || tagsA.length === 0 || tagsB.length === 0) return 0;
-
-    const setA = new Set(tagsA.map(t => t.toLowerCase()));
-    const setB = new Set(tagsB.map(t => t.toLowerCase()));
-
-    return this.jaccardSimilarity(setA, setB);
-  }
-
-  /**
-   * Check if two actions are aligned (same direction)
-   *
-   * @param {string} actionA - First action
-   * @param {string} actionB - Second action
-   * @returns {boolean} True if actions are aligned
-   */
-  areActionsAligned(actionA, actionB) {
-    const aligned = ALIGNED_ACTIONS[actionA];
-    return aligned ? aligned.includes(actionB) : actionA === actionB;
-  }
-
-  /**
-   * Check if two actions are conflicting (opposite direction)
-   *
-   * @param {string} actionA - First action
-   * @param {string} actionB - Second action
-   * @returns {boolean} True if actions conflict
-   */
-  areActionsConflicting(actionA, actionB) {
-    return OPPOSING_ACTIONS[actionA] === actionB;
-  }
-
-  /**
-   * Compute confidence score for a confirmed match
-   *
-   * @param {number} similarity - Text similarity score
-   * @param {Object} uploadedRule - Uploaded rule
-   * @param {Object} discoveredRule - Discovered rule
-   * @returns {number} Confidence score (0.0 - 1.0)
-   */
-  computeConfirmationConfidence(similarity, uploadedRule, discoveredRule) {
-    let confidence = similarity;
-
-    // Exact action match increases confidence
-    if (uploadedRule.action === discoveredRule.action) {
-      confidence = Math.min(1.0, confidence + 0.15);
-    }
-
-    // Same category increases confidence
-    if (uploadedRule.category === discoveredRule.category) {
-      confidence = Math.min(1.0, confidence + 0.1);
-    }
-
-    // Higher priority rules get slightly higher confidence
-    if (uploadedRule.priority <= 20 || discoveredRule.priority <= 20) {
-      confidence = Math.min(1.0, confidence + 0.05);
-    }
-
-    return Math.round(confidence * 100) / 100;
-  }
-
-  /**
-   * Compute confidence score for a conflict
-   *
-   * @param {number} similarity - Text similarity score
-   * @param {Object} uploadedRule - Uploaded rule
-   * @param {Object} discoveredRule - Discovered rule
-   * @returns {number} Confidence score (0.0 - 1.0)
-   */
-  computeConflictConfidence(similarity, uploadedRule, discoveredRule) {
-    let confidence = similarity;
-
-    // Direct opposition (ALWAYS vs NEVER) is high confidence conflict
-    if (OPPOSING_ACTIONS[uploadedRule.action] === discoveredRule.action) {
-      confidence = Math.min(1.0, confidence + 0.2);
-    }
-
-    // Same category makes the conflict more significant
-    if (uploadedRule.category === discoveredRule.category) {
-      confidence = Math.min(1.0, confidence + 0.1);
-    }
-
-    return Math.round(confidence * 100) / 100;
-  }
-
-  /**
-   * Compute confidence score for a new discovery
-   *
-   * @param {Object} discoveredRule - Discovered rule
-   * @returns {number} Confidence score (0.0 - 1.0)
-   */
-  computeDiscoveryConfidence(discoveredRule) {
-    let confidence = 0.5; // Base confidence for any discovery
-
-    // Stronger action types indicate higher confidence
-    if (discoveredRule.action === 'ALWAYS' || discoveredRule.action === 'NEVER') {
-      confidence += 0.2;
-    } else if (discoveredRule.action === 'USE' || discoveredRule.action === 'AVOID') {
-      confidence += 0.1;
-    }
-
-    // Higher priority discovered rules are more confident
-    if (discoveredRule.priority === 10) {
-      confidence += 0.1;
-    } else if (discoveredRule.priority === 20) {
-      confidence += 0.05;
-    }
-
-    // Longer, more descriptive rules indicate more specificity
-    if (discoveredRule.rule.length > 50) {
-      confidence += 0.1;
-    }
-
-    return Math.min(1.0, Math.round(confidence * 100) / 100);
-  }
-
-  /**
-   * Generate a human-readable description of a conflict
-   *
-   * @param {Object} uploadedRule - Uploaded rule
-   * @param {Object} discoveredRule - Discovered rule
-   * @returns {string} Conflict description
-   */
-  describeConflict(uploadedRule, discoveredRule) {
-    return `Uploaded standard says "${uploadedRule.action}: ${uploadedRule.rule}" ` +
-      `but discovered pattern shows "${discoveredRule.action}: ${discoveredRule.rule}"`;
-  }
-
-  /**
-   * Cross-reference anti-patterns between uploaded and discovered standards
-   *
-   * @param {Array<Object>} uploaded - Uploaded standards
-   * @param {Array<Object>} discovered - Discovered standards
-   * @returns {Object} Anti-pattern cross-reference results
-   */
-  crossReferenceAntiPatterns(uploaded, discovered) {
-    const confirmed = [];
-    const conflicts = [];
-
-    const uploadedAntiPatterns = this.flattenAntiPatterns(uploaded);
-    const discoveredAntiPatterns = this.flattenAntiPatterns(discovered);
-
-    for (const discoveredAp of discoveredAntiPatterns) {
-      for (const uploadedAp of uploadedAntiPatterns) {
-        const similarity = this.computeTextSimilarity(
-          uploadedAp.text,
-          discoveredAp.text
-        );
-
-        if (similarity >= this.similarityThreshold) {
-          confirmed.push({
-            uploaded: {
-              standardId: uploadedAp.standardId,
-              action: 'AVOID',
-              rule: uploadedAp.text,
-              category: uploadedAp.category
-            },
-            discovered: {
-              standardId: discoveredAp.standardId,
-              action: 'AVOID',
-              rule: discoveredAp.text,
-              category: discoveredAp.category
-            },
-            confidence: Math.round(similarity * 100) / 100,
-            matchType: 'anti_pattern_confirmed',
-            similarity
-          });
-        }
-      }
-    }
-
-    // Check if any uploaded anti-patterns are found as positive rules in discovered
-    const discoveredRules = this.flattenRules(discovered);
-    for (const uploadedAp of uploadedAntiPatterns) {
-      for (const discoveredRule of discoveredRules) {
-        if (discoveredRule.action === 'ALWAYS' || discoveredRule.action === 'USE' || discoveredRule.action === 'PREFER') {
-          const similarity = this.computeTextSimilarity(
-            uploadedAp.text,
-            discoveredRule.rule
-          );
-
-          if (similarity >= this.similarityThreshold) {
-            conflicts.push({
-              uploaded: {
-                standardId: uploadedAp.standardId,
-                action: 'AVOID',
-                rule: uploadedAp.text,
-                category: uploadedAp.category
-              },
-              discovered: {
-                standardId: discoveredRule.standardId,
-                action: discoveredRule.action,
-                rule: discoveredRule.rule,
-                category: discoveredRule.category
-              },
-              confidence: Math.round(similarity * 100) / 100,
-              matchType: 'anti_pattern_conflict',
-              similarity,
-              reason: `Uploaded standard lists "${uploadedAp.text}" as an anti-pattern, ` +
-                `but discovered pattern promotes "${discoveredRule.action}: ${discoveredRule.rule}"`
-            });
-          }
-        }
-      }
-    }
-
-    return { confirmed, conflicts };
-  }
-
-  /**
-   * Flatten anti-patterns from standards objects
-   *
-   * @param {Array<Object>} standards - Standards objects
-   * @returns {Array<Object>} Flattened anti-pattern records
-   */
-  flattenAntiPatterns(standards) {
-    const flattened = [];
-
-    for (const standard of standards) {
-      const antiPatterns = Array.isArray(standard.anti_patterns) ? standard.anti_patterns : [];
-
-      for (const ap of antiPatterns) {
-        const text = typeof ap === 'string' ? ap : (ap.description || ap.text || '');
-        if (text) {
-          flattened.push({
-            standardId: standard.id || 'unknown',
-            category: standard.category || 'general',
-            text
-          });
-        }
-      }
-    }
-
-    return flattened;
-  }
-
-  /**
-   * Compute text similarity between two strings
-   *
-   * @param {string} textA - First text
-   * @param {string} textB - Second text
-   * @returns {number} Similarity score (0.0 - 1.0)
-   */
-  computeTextSimilarity(textA, textB) {
-    const tokensA = this.tokenize(textA.toLowerCase());
-    const tokensB = this.tokenize(textB.toLowerCase());
-    return this.jaccardSimilarity(tokensA, tokensB);
-  }
-
-  /**
-   * Compute overall alignment score
-   *
-   * @param {Array} confirmed - Confirmed matches
-   * @param {Array} conflicts - Conflicts found
-   * @param {Array} newDiscoveries - New discoveries
-   * @returns {number} Overall alignment (0.0 - 1.0)
-   */
-  computeOverallAlignment(confirmed, conflicts, newDiscoveries) {
-    const total = confirmed.length + conflicts.length + newDiscoveries.length;
-    if (total === 0) return 1.0;
-
-    // Confirmed matches contribute positively, conflicts negatively
-    const alignmentScore = (confirmed.length - conflicts.length * 0.5) / total;
-    return Math.max(0, Math.min(1.0, Math.round(alignmentScore * 100) / 100));
-  }
-}
-
-module.exports = { CrossReferenceEngine };