@rigour-labs/core 2.9.4 → 2.10.0

package/dist/pattern-index/indexer.test.js

@@ -0,0 +1,188 @@
+/**
+ * Pattern Indexer Tests
+ *
+ * Comprehensive tests for the pattern indexer.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+import { PatternIndexer, savePatternIndex, loadPatternIndex } from './indexer.js';
+describe('PatternIndexer', () => {
+    let testDir;
+    beforeEach(async () => {
+        // Create a temporary test directory
+        testDir = await fs.mkdtemp(path.join(os.tmpdir(), 'rigour-test-'));
+        await fs.mkdir(path.join(testDir, 'src'), { recursive: true });
+    });
+    afterEach(async () => {
+        // Clean up
+        await fs.rm(testDir, { recursive: true, force: true });
+    });
+    describe('buildIndex', () => {
+        it('should index function declarations', async () => {
+            await fs.writeFile(path.join(testDir, 'src', 'utils.ts'), `
+/**
+ * Format a date to a readable string.
+ */
+export function formatDate(date: Date): string {
+    return date.toISOString();
+}
+                `);
+            const indexer = new PatternIndexer(testDir);
+            const index = await indexer.buildIndex();
+            expect(index.patterns).toHaveLength(1);
+            expect(index.patterns[0].name).toBe('formatDate');
+            expect(index.patterns[0].type).toBe('function');
+            expect(index.patterns[0].exported).toBe(true);
+            expect(index.patterns[0].signature).toContain('date: Date');
+            expect(index.patterns[0].description).toContain('Format a date');
+        });
+        it('should index arrow functions', async () => {
+            await fs.writeFile(path.join(testDir, 'src', 'helpers.ts'), `
+export const slugify = (text: string): string => {
+    return text.toLowerCase().replace(/\\s+/g, '-');
+};
+                `);
+            const indexer = new PatternIndexer(testDir);
+            const index = await indexer.buildIndex();
+            expect(index.patterns).toHaveLength(1);
+            expect(index.patterns[0].name).toBe('slugify');
+            expect(index.patterns[0].type).toBe('function');
+        });
+        it('should detect React hooks', async () => {
+            await fs.writeFile(path.join(testDir, 'src', 'hooks.ts'), `
+export const useAuth = () => {
+    return { user: null, login: () => {} };
+};
+                `);
+            const indexer = new PatternIndexer(testDir);
+            const index = await indexer.buildIndex();
+            expect(index.patterns).toHaveLength(1);
+            expect(index.patterns[0].name).toBe('useAuth');
+            expect(index.patterns[0].type).toBe('hook');
+        });
+        it('should index classes', async () => {
+            await fs.writeFile(path.join(testDir, 'src', 'services.ts'), `
+export class UserService {
+    getUser(id: string) {
+        return { id };
+    }
+}
+                `);
+            const indexer = new PatternIndexer(testDir);
+            const index = await indexer.buildIndex();
+            expect(index.patterns.some(p => p.name === 'UserService')).toBe(true);
+            expect(index.patterns.find(p => p.name === 'UserService')?.type).toBe('class');
+        });
+        it('should detect error classes', async () => {
+            await fs.writeFile(path.join(testDir, 'src', 'errors.ts'), `
+export class ValidationError extends Error {
+    constructor(message: string) {
+        super(message);
+    }
+}
+                `);
+            const indexer = new PatternIndexer(testDir);
+            const index = await indexer.buildIndex();
+            expect(index.patterns[0].type).toBe('error');
+        });
+        it('should index interfaces', async () => {
+            await fs.writeFile(path.join(testDir, 'src', 'types.ts'), `
+export interface User {
+    id: string;
+    name: string;
+    email: string;
+}
+                `);
+            const indexer = new PatternIndexer(testDir);
+            const index = await indexer.buildIndex();
+            expect(index.patterns).toHaveLength(1);
+            expect(index.patterns[0].name).toBe('User');
+            expect(index.patterns[0].type).toBe('interface');
+        });
+        it('should index type aliases', async () => {
+            await fs.writeFile(path.join(testDir, 'src', 'types.ts'), `
+export type UserId = string;
+                `);
+            const indexer = new PatternIndexer(testDir);
+            const index = await indexer.buildIndex();
+            expect(index.patterns).toHaveLength(1);
+            expect(index.patterns[0].type).toBe('type');
+        });
+        it('should index enums', async () => {
+            await fs.writeFile(path.join(testDir, 'src', 'constants.ts'), `
+export enum Status {
+    Active = 'active',
+    Inactive = 'inactive'
+}
+                `);
+            const indexer = new PatternIndexer(testDir);
+            const index = await indexer.buildIndex();
+            expect(index.patterns).toHaveLength(1);
+            expect(index.patterns[0].name).toBe('Status');
+            expect(index.patterns[0].type).toBe('enum');
+        });
+        it('should index constants (all caps)', async () => {
+            await fs.writeFile(path.join(testDir, 'src', 'config.ts'), `
+export const API_URL = 'https://api.example.com';
+export const MAX_RETRIES = 3;
+                `);
+            const indexer = new PatternIndexer(testDir);
+            const index = await indexer.buildIndex();
+            const constants = index.patterns.filter(p => p.type === 'constant');
+            expect(constants.length).toBeGreaterThanOrEqual(1);
+            expect(constants.some(c => c.name === 'API_URL')).toBe(true);
+        });
+        it('should track index statistics', async () => {
+            await fs.writeFile(path.join(testDir, 'src', 'utils.ts'), `
+export function foo() {}
+export function bar() {}
+export interface Baz {}
+                `);
+            const indexer = new PatternIndexer(testDir);
+            const index = await indexer.buildIndex();
+            expect(index.stats.totalPatterns).toBe(3);
+            expect(index.stats.totalFiles).toBe(1);
+            expect(index.stats.indexDurationMs).toBeGreaterThan(0);
+        });
+        it('should exclude test files by default', async () => {
+            await fs.writeFile(path.join(testDir, 'src', 'utils.ts'), 'export function main() {}');
+            await fs.writeFile(path.join(testDir, 'src', 'utils.test.ts'), 'export function testMain() {}');
+            const indexer = new PatternIndexer(testDir);
+            const index = await indexer.buildIndex();
+            expect(index.patterns.every(p => !p.file.includes('.test.'))).toBe(true);
+        });
+    });
+    describe('updateIndex (incremental)', () => {
+        it('should only reindex changed files', async () => {
+            // Initial index
+            await fs.writeFile(path.join(testDir, 'src', 'a.ts'), 'export function funcA() {}');
+            await fs.writeFile(path.join(testDir, 'src', 'b.ts'), 'export function funcB() {}');
+            const indexer = new PatternIndexer(testDir);
+            const initialIndex = await indexer.buildIndex();
+            expect(initialIndex.patterns).toHaveLength(2);
+            // Modify only one file
+            await fs.writeFile(path.join(testDir, 'src', 'a.ts'), 'export function funcA() {} export function funcA2() {}');
+            const updatedIndex = await indexer.updateIndex(initialIndex);
+            expect(updatedIndex.patterns).toHaveLength(3);
+        });
+    });
+    describe('savePatternIndex / loadPatternIndex', () => {
+        it('should save and load index correctly', async () => {
+            await fs.writeFile(path.join(testDir, 'src', 'utils.ts'), 'export function myFunc() {}');
+            const indexer = new PatternIndexer(testDir);
+            const index = await indexer.buildIndex();
+            const indexPath = path.join(testDir, '.rigour', 'patterns.json');
+            await savePatternIndex(index, indexPath);
+            const loaded = await loadPatternIndex(indexPath);
+            expect(loaded).not.toBeNull();
+            expect(loaded.patterns).toHaveLength(index.patterns.length);
+            expect(loaded.version).toBe(index.version);
+        });
+        it('should return null for non-existent index', async () => {
+            const loaded = await loadPatternIndex('/non/existent/path.json');
+            expect(loaded).toBeNull();
+        });
+    });
+});

package/dist/pattern-index/matcher.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Pattern Matcher
+ *
+ * Matches queries against the pattern index using multiple strategies:
+ * 1. Exact name match
+ * 2. Fuzzy name match (Levenshtein)
+ * 3. Signature match
+ * 4. Keyword/semantic match
+ */
+import type { PatternIndex, PatternMatchResult, PatternOverride } from './types.js';
+/**
+ * Configuration for pattern matching.
+ */
+export interface MatcherConfig {
+    /** Minimum confidence threshold to include a match (0-100) */
+    minConfidence: number;
+    /** Maximum number of matches to return */
+    maxMatches: number;
+    /** Whether to use fuzzy matching */
+    useFuzzy: boolean;
+    /** Whether to use signature matching */
+    useSignature: boolean;
+    /** Whether to use keyword/semantic matching */
+    useKeywords: boolean;
+    /** Action when matches are found */
+    defaultAction: 'BLOCK' | 'WARN' | 'ALLOW';
+    /** Whether to use semantic embeddings for matching */
+    useEmbeddings: boolean;
+}
+/**
+ * Pattern Matcher class.
+ * Finds similar patterns in the index.
+ */
+export declare class PatternMatcher {
+    private index;
+    private config;
+    private overrides;
+    private nameMap;
+    constructor(index: PatternIndex, config?: Partial<MatcherConfig>, overrides?: PatternOverride[]);
+    /**
+     * Find patterns similar to a query.
+     */
+    match(query: {
+        name?: string;
+        signature?: string;
+        keywords?: string[];
+        type?: string;
+        intent?: string;
+    }): Promise<PatternMatchResult>;
+    /**
+     * Check for exact name match.
+     */
+    private exactNameMatch;
+    /**
+     * Check for fuzzy name match using Levenshtein distance.
+     */
+    private fuzzyNameMatch;
+    /**
+     * Check for signature match.
+     */
+    private signatureMatch;
+    /**
+     * Check for keyword/semantic match.
+     */
+    private keywordMatch;
+    /**
+     * Check if an override exists for a pattern.
+     */
+    private hasOverride;
+    /**
+     * Generate a suggestion message.
+     */
+    private generateSuggestion;
+    /**
+     * Calculate Levenshtein distance between two strings.
+     */
+    private levenshteinDistance;
+    /**
+     * Extract words from a camelCase/PascalCase name.
+     */
+    private extractWords;
+    /**
+     * Calculate word overlap ratio.
+     */
+    private calculateWordOverlap;
+    /**
+     * Normalize a signature for comparison.
+     */
+    private normalizeSignature;
+    /**
+     * Extract parameters from a signature.
+     */
+    private extractParameters;
+    /**
+     * Compare parameter types between two signatures.
+     */
+    private compareParameterTypes;
+    /**
+     * Extract type from a parameter declaration.
+     */
+    private extractType;
+}
+/**
+ * Quick helper to check for pattern duplicates.
+ */
+export declare function checkPatternDuplicate(index: PatternIndex, name: string, options?: Partial<MatcherConfig>): Promise<PatternMatchResult>;

package/dist/pattern-index/matcher.js

@@ -0,0 +1,376 @@
+/**
+ * Pattern Matcher
+ *
+ * Matches queries against the pattern index using multiple strategies:
+ * 1. Exact name match
+ * 2. Fuzzy name match (Levenshtein)
+ * 3. Signature match
+ * 4. Keyword/semantic match
+ */
+import { generateEmbedding, cosineSimilarity } from './embeddings.js';
+/** Default matcher configuration */
+const DEFAULT_MATCHER_CONFIG = {
+    minConfidence: 60,
+    maxMatches: 5,
+    useFuzzy: true,
+    useSignature: true,
+    useKeywords: true,
+    defaultAction: 'WARN',
+    useEmbeddings: true
+};
+/**
+ * Pattern Matcher class.
+ * Finds similar patterns in the index.
+ */
+export class PatternMatcher {
+    index;
+    config;
+    overrides;
+    nameMap;
+    constructor(index, config = {}, overrides = []) {
+        this.index = index;
+        this.config = { ...DEFAULT_MATCHER_CONFIG, ...config };
+        this.overrides = overrides;
+        // Build name map for O(1) lookups
+        this.nameMap = new Map();
+        for (const pattern of index.patterns) {
+            const normalized = pattern.name.toLowerCase();
+            const existing = this.nameMap.get(normalized) || [];
+            existing.push(pattern);
+            this.nameMap.set(normalized, existing);
+        }
+    }
+    /**
+     * Find patterns similar to a query.
+     */
+    async match(query) {
+        const matches = [];
+        // Pre-calculate query embedding if semantic search is enabled
+        let queryEmbedding = null;
+        if (this.config.useEmbeddings && (query.intent || query.name)) {
+            queryEmbedding = await generateEmbedding(`${query.name || ''} ${query.intent || ''}`);
+        }
+        // Check for override first
+        if (query.name && this.hasOverride(query.name)) {
+            return {
+                query: query.name || '',
+                matches: [],
+                suggestion: 'Human override granted for this pattern.',
+                canOverride: false,
+                status: 'OVERRIDE_ALLOWED',
+                action: 'ALLOW'
+            };
+        }
+        // Strategy 1: Fast Exact name match (O(1))
+        if (query.name) {
+            const exactPatterns = this.nameMap.get(query.name.toLowerCase()) || [];
+            for (const pattern of exactPatterns) {
+                const match = this.exactNameMatch(query.name, pattern);
+                if (match) {
+                    matches.push(match);
+                }
+            }
+            // If we found exact matches, we might still want to find others, 
+            // but we can skip checking these specific patterns again in the main loop.
+        }
+        for (const pattern of this.index.patterns) {
+            // Skip if we already matched this pattern via exact match
+            if (query.name && pattern.name.toLowerCase() === query.name.toLowerCase()) {
+                continue;
+            }
+            let currentBest = null;
+            let maxConfidence = -1;
+            // Strategy 2: Fuzzy name match
+            if (query.name && this.config.useFuzzy) {
+                const match = this.fuzzyNameMatch(query.name, pattern);
+                if (match && match.confidence > maxConfidence) {
+                    currentBest = match;
+                    maxConfidence = match.confidence;
+                }
+            }
+            // Strategy 3: Signature match
+            if (query.signature && this.config.useSignature) {
+                const match = this.signatureMatch(query.signature, pattern);
+                if (match && match.confidence > maxConfidence) {
+                    currentBest = match;
+                    maxConfidence = match.confidence;
+                }
+            }
+            // Strategy 4: Keyword match
+            if (query.keywords && query.keywords.length > 0 && this.config.useKeywords) {
+                const match = this.keywordMatch(query.keywords, pattern);
+                if (match && match.confidence > maxConfidence) {
+                    currentBest = match;
+                    maxConfidence = match.confidence;
+                }
+            }
+            // Strategy 5: Semantic embedding match
+            if (queryEmbedding && pattern.embedding && this.config.useEmbeddings) {
+                const similarity = cosineSimilarity(queryEmbedding, pattern.embedding);
+                const confidence = Math.round(similarity * 100);
+                if (confidence > maxConfidence) {
+                    currentBest = {
+                        pattern,
+                        matchType: 'semantic',
+                        confidence,
+                        reason: `Semantic match (${confidence}%): similar intent to "${pattern.name}"`
+                    };
+                    maxConfidence = confidence;
+                }
+            }
+            if (currentBest && maxConfidence >= this.config.minConfidence) {
+                matches.push(currentBest);
+            }
+        }
+        // Sort by confidence and limit
+        matches.sort((a, b) => b.confidence - a.confidence);
+        const topMatches = matches.slice(0, this.config.maxMatches);
+        // Determine status and action
+        const hasExact = topMatches.some(m => m.matchType === 'exact');
+        const hasHighConfidence = topMatches.some(m => m.confidence >= 90);
+        let status = 'NO_MATCH';
+        let action = 'ALLOW';
+        let suggestion = '';
+        if (topMatches.length > 0) {
+            status = 'FOUND_SIMILAR';
+            action = hasExact || hasHighConfidence ? 'BLOCK' : this.config.defaultAction;
+            const best = topMatches[0];
+            suggestion = this.generateSuggestion(best);
+        }
+        return {
+            query: query.name || query.signature || query.keywords?.join(' ') || '',
+            matches: topMatches,
+            suggestion,
+            canOverride: true,
+            status,
+            action
+        };
+    }
+    /**
+     * Check for exact name match.
+     */
+    exactNameMatch(queryName, pattern) {
+        const normalizedQuery = queryName.toLowerCase();
+        const normalizedPattern = pattern.name.toLowerCase();
+        if (normalizedQuery === normalizedPattern) {
+            return {
+                pattern,
+                matchType: 'exact',
+                confidence: 100,
+                reason: `Exact match: "${pattern.name}" already exists in ${pattern.file}`
+            };
+        }
+        return null;
+    }
+    /**
+     * Check for fuzzy name match using Levenshtein distance.
+     */
+    fuzzyNameMatch(queryName, pattern) {
+        const distance = this.levenshteinDistance(queryName.toLowerCase(), pattern.name.toLowerCase());
+        const maxLength = Math.max(queryName.length, pattern.name.length);
+        const similarity = 1 - (distance / maxLength);
+        const confidence = Math.round(similarity * 100);
+        // Also check word overlap
+        const queryWords = this.extractWords(queryName);
+        const patternWords = this.extractWords(pattern.name);
+        const wordOverlap = this.calculateWordOverlap(queryWords, patternWords);
+        // Combine word overlap with character similarity
+        const combinedConfidence = Math.round((confidence + wordOverlap * 100) / 2);
+        if (combinedConfidence >= 60) {
+            return {
+                pattern,
+                matchType: 'fuzzy',
+                confidence: combinedConfidence,
+                reason: `Similar name: "${pattern.name}" in ${pattern.file} (${combinedConfidence}% similar)`
+            };
+        }
+        return null;
+    }
+    /**
+     * Check for signature match.
+     */
+    signatureMatch(querySignature, pattern) {
+        if (!pattern.signature)
+            return null;
+        // Normalize signatures for comparison
+        const normalizedQuery = this.normalizeSignature(querySignature);
+        const normalizedPattern = this.normalizeSignature(pattern.signature);
+        if (normalizedQuery === normalizedPattern) {
+            return {
+                pattern,
+                matchType: 'signature',
+                confidence: 85,
+                reason: `Matching signature: ${pattern.name}${pattern.signature} in ${pattern.file}`
+            };
+        }
+        // Check parameter count and types
+        const queryParams = this.extractParameters(querySignature);
+        const patternParams = this.extractParameters(pattern.signature);
+        if (queryParams.length === patternParams.length && queryParams.length > 0) {
+            const typeMatch = this.compareParameterTypes(queryParams, patternParams);
+            if (typeMatch >= 0.7) {
+                const confidence = Math.round(60 + typeMatch * 20);
+                return {
+                    pattern,
+                    matchType: 'signature',
+                    confidence,
+                    reason: `Similar signature (${confidence}% match): ${pattern.name} in ${pattern.file}`
+                };
+            }
+        }
+        return null;
+    }
+    /**
+     * Check for keyword/semantic match.
+     */
+    keywordMatch(queryKeywords, pattern) {
+        if (!pattern.keywords || pattern.keywords.length === 0)
+            return null;
+        const normalizedQuery = queryKeywords.map(k => k.toLowerCase());
+        const normalizedPattern = pattern.keywords.map(k => k.toLowerCase());
+        const matches = normalizedQuery.filter(k => normalizedPattern.includes(k));
+        const overlap = matches.length / Math.max(normalizedQuery.length, normalizedPattern.length);
+        if (overlap >= 0.5) {
+            const confidence = Math.round(50 + overlap * 40);
+            return {
+                pattern,
+                matchType: 'semantic',
+                confidence,
+                reason: `Semantic match (keywords: ${matches.join(', ')}): ${pattern.name} in ${pattern.file}`
+            };
+        }
+        return null;
+    }
+    /**
+     * Check if an override exists for a pattern.
+     */
+    hasOverride(name) {
+        const now = new Date();
+        return this.overrides.some(override => {
+            // Check expiration
+            if (override.expiresAt && new Date(override.expiresAt) < now) {
+                return false;
+            }
+            // Check pattern match (supports globs)
+            if (override.pattern.includes('*')) {
+                const regex = new RegExp('^' + override.pattern.replace(/\*/g, '.*') + '$');
+                return regex.test(name);
+            }
+            return override.pattern === name;
+        });
+    }
+    /**
+     * Generate a suggestion message.
+     */
+    generateSuggestion(match) {
+        const { pattern } = match;
+        if (pattern.exported) {
+            return `Import "${pattern.name}" from "${pattern.file}" instead of creating a new one.`;
+        }
+        return `A similar pattern "${pattern.name}" exists in "${pattern.file}". Consider reusing it or extracting it to a shared location.`;
+    }
+    /**
+     * Calculate Levenshtein distance between two strings.
+     */
+    levenshteinDistance(a, b) {
+        const matrix = [];
+        for (let i = 0; i <= b.length; i++) {
+            matrix[i] = [i];
+        }
+        for (let j = 0; j <= a.length; j++) {
+            matrix[0][j] = j;
+        }
+        for (let i = 1; i <= b.length; i++) {
+            for (let j = 1; j <= a.length; j++) {
+                if (b.charAt(i - 1) === a.charAt(j - 1)) {
+                    matrix[i][j] = matrix[i - 1][j - 1];
+                }
+                else {
+                    matrix[i][j] = Math.min(matrix[i - 1][j - 1] + 1, // substitution
+                    matrix[i][j - 1] + 1, // insertion
+                    matrix[i - 1][j] + 1 // deletion
+                    );
+                }
+            }
+        }
+        return matrix[b.length][a.length];
+    }
+    /**
+     * Extract words from a camelCase/PascalCase name.
+     */
+    extractWords(name) {
+        return name
+            .replace(/([a-z])([A-Z])/g, '$1 $2')
+            .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+            .toLowerCase()
+            .split(/[\s_-]+/)
+            .filter(w => w.length > 1);
+    }
+    /**
+     * Calculate word overlap ratio.
+     */
+    calculateWordOverlap(words1, words2) {
+        const set1 = new Set(words1);
+        const set2 = new Set(words2);
+        let matches = 0;
+        for (const word of set1) {
+            if (set2.has(word)) {
+                matches++;
+            }
+        }
+        return matches / Math.max(set1.size, set2.size);
+    }
+    /**
+     * Normalize a signature for comparison.
+     */
+    normalizeSignature(sig) {
+        return sig
+            .replace(/\s+/g, '') // Remove whitespace
+            .replace(/:\s*\w+/g, '') // Remove type annotations
+            .replace(/\?/g, '') // Remove optional markers
+            .toLowerCase();
+    }
+    /**
+     * Extract parameters from a signature.
+     */
+    extractParameters(sig) {
+        const match = sig.match(/\(([^)]*)\)/);
+        if (!match)
+            return [];
+        return match[1]
+            .split(',')
+            .map(p => p.trim())
+            .filter(p => p.length > 0);
+    }
+    /**
+     * Compare parameter types between two signatures.
+     */
+    compareParameterTypes(params1, params2) {
+        let matches = 0;
+        for (let i = 0; i < params1.length; i++) {
+            const type1 = this.extractType(params1[i]);
+            const type2 = this.extractType(params2[i]);
+            if (type1 === type2) {
+                matches++;
+            }
+            else if (type1 && type2 && (type1.includes(type2) || type2.includes(type1))) {
+                matches += 0.5;
+            }
+        }
+        return matches / params1.length;
+    }
+    /**
+     * Extract type from a parameter declaration.
+     */
+    extractType(param) {
+        const match = param.match(/:\s*(\w+)/);
+        return match ? match[1].toLowerCase() : null;
+    }
+}
+/**
+ * Quick helper to check for pattern duplicates.
+ */
+export async function checkPatternDuplicate(index, name, options = {}) {
+    const matcher = new PatternMatcher(index, options);
+    return matcher.match({ name });
+}

package/dist/pattern-index/matcher.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Pattern Matcher Tests
+ *
+ * Comprehensive tests for the pattern matcher.
+ */
+export {};