@rigour-labs/core 2.9.4 → 2.11.0

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

@@ -0,0 +1,221 @@
+/**
+ * Pattern Index - Types
+ *
+ * Core type definitions for the Pattern Index system.
+ * Rigour's Pattern Index prevents AI from reinventing existing code.
+ */
+/**
+ * All supported pattern types that can be indexed.
+ * Organized by category for clarity.
+ */
+export type PatternType = 'function' | 'class' | 'method' | 'component' | 'hook' | 'decorator' | 'middleware' | 'type' | 'interface' | 'schema' | 'model' | 'enum' | 'constant' | 'config' | 'env' | 'route' | 'handler' | 'resolver' | 'rpc' | 'store' | 'reducer' | 'action' | 'selector' | 'error' | 'exception' | 'mock' | 'fixture' | 'factory' | 'command' | 'task' | 'event' | 'protocol';
+/**
+ * A single indexed pattern entry.
+ */
+export interface PatternEntry {
+    /** Unique identifier (hash of file + name) */
+    id: string;
+    /** The type of pattern */
+    type: PatternType;
+    /** Name of the pattern (e.g., "formatDate") */
+    name: string;
+    /** Relative path to the file */
+    file: string;
+    /** Line number where the pattern is defined */
+    line: number;
+    /** End line number */
+    endLine: number;
+    /** Function/method signature if applicable */
+    signature: string;
+    /** Description from JSDoc/docstring */
+    description: string;
+    /** Extracted semantic keywords for matching */
+    keywords: string[];
+    /** Content hash for change detection */
+    hash: string;
+    /** Is this pattern exported? */
+    exported: boolean;
+    /** How many files import this pattern */
+    usageCount: number;
+    /** User-defined category/grouping */
+    category?: string;
+    embedding?: number[];
+    /** Last indexed timestamp */
+    indexedAt: string;
+}
+/**
+ * The complete pattern index structure.
+ */
+export interface PatternIndex {
+    /** Index format version */
+    version: string;
+    /** When the index was last updated */
+    lastUpdated: string;
+    /** Root directory that was indexed */
+    rootDir: string;
+    /** All indexed patterns */
+    patterns: PatternEntry[];
+    /** Index statistics */
+    stats: PatternIndexStats;
+    /** Files that were indexed */
+    files: IndexedFile[];
+}
+/**
+ * Statistics about the pattern index.
+ */
+export interface PatternIndexStats {
+    totalPatterns: number;
+    totalFiles: number;
+    byType: Record<PatternType, number>;
+    indexDurationMs: number;
+}
+/**
+ * Information about an indexed file.
+ */
+export interface IndexedFile {
+    path: string;
+    hash: string;
+    patternCount: number;
+    indexedAt: string;
+}
+/**
+ * Configuration for the pattern indexer.
+ */
+export interface PatternIndexConfig {
+    /** Directories to index (defaults to src/) */
+    include: string[];
+    /** Directories to exclude */
+    exclude: string[];
+    /** File extensions to index */
+    extensions: string[];
+    /** Whether to index test files */
+    indexTests: boolean;
+    /** Whether to index node_modules */
+    indexNodeModules: boolean;
+    /** Minimum pattern name length to index */
+    minNameLength: number;
+    /** Custom categories for patterns */
+    categories: Record<string, string[]>;
+    /** Whether to generate semantic embeddings for patterns */
+    useEmbeddings?: boolean;
+}
+/**
+ * Result from matching against the pattern index.
+ */
+export interface PatternMatchResult {
+    /** The query that was matched */
+    query: string;
+    /** All matches found */
+    matches: PatternMatch[];
+    /** Suggestion for what to do */
+    suggestion: string;
+    /** Whether human override is available */
+    canOverride: boolean;
+    /** Overall status */
+    status: 'FOUND_SIMILAR' | 'NO_MATCH' | 'OVERRIDE_ALLOWED';
+    /** Recommended action */
+    action: 'BLOCK' | 'WARN' | 'ALLOW';
+}
+/**
+ * A single pattern match.
+ */
+export interface PatternMatch {
+    /** The matched pattern */
+    pattern: PatternEntry;
+    /** How the match was determined */
+    matchType: 'exact' | 'fuzzy' | 'signature' | 'semantic';
+    /** Confidence score 0-100 */
+    confidence: number;
+    /** Human-readable reason for the match */
+    reason: string;
+}
+/**
+ * Human override entry.
+ */
+export interface PatternOverride {
+    /** Pattern name or glob */
+    pattern: string;
+    /** Why the override was granted */
+    reason: string;
+    /** When the override expires */
+    expiresAt?: string;
+    /** Who approved the override */
+    approvedBy?: string;
+    /** When the override was created */
+    createdAt: string;
+}
+/**
+ * Staleness detection result.
+ */
+export interface StalenessResult {
+    /** Overall status */
+    status: 'FRESH' | 'STALE' | 'DEPRECATED';
+    /** All staleness issues found */
+    issues: StalenessIssue[];
+    /** Project context (versions) */
+    projectContext: Record<string, string>;
+}
+/**
+ * A single staleness issue.
+ */
+export interface StalenessIssue {
+    /** Line number */
+    line: number;
+    /** The stale pattern */
+    pattern: string;
+    /** Severity */
+    severity: 'error' | 'warning' | 'info';
+    /** Why it's stale */
+    reason: string;
+    /** What to use instead */
+    replacement: string;
+    /** Link to documentation */
+    docs?: string;
+}
+/**
+ * Security/CVE entry for a package.
+ */
+export interface SecurityEntry {
+    /** CVE Identifier (e.g., CVE-2021-1234) */
+    cveId: string;
+    /** Package name */
+    packageName: string;
+    /** Vulnerable version range (semver) */
+    vulnerableRange: string;
+    /** Severity level */
+    severity: 'critical' | 'high' | 'moderate' | 'low';
+    /** Brief description of the vulnerability */
+    title: string;
+    /** Link to advisory */
+    url: string;
+    /** The version of the package in the current project */
+    currentVersion?: string;
+}
+/**
+ * Result from security check.
+ */
+export interface SecurityResult {
+    /** Overall security status */
+    status: 'SECURE' | 'VULNERABLE';
+    /** All CVEs/vulnerabilities found */
+    vulnerabilities: SecurityEntry[];
+}
+/**
+ * Deprecation entry in the deprecation database.
+ */
+export interface DeprecationEntry {
+    /** Pattern to match (can be regex) */
+    pattern: string;
+    /** Library this belongs to */
+    library?: string;
+    /** Version when deprecated */
+    deprecatedIn: string;
+    /** Suggested replacement */
+    replacement: string;
+    /** Severity level */
+    severity: 'error' | 'warning' | 'info';
+    /** Additional context */
+    reason?: string;
+    /** Documentation link */
+    docs?: string;
+}

package/dist/pattern-index/types.js

@@ -0,0 +1,7 @@
+/**
+ * Pattern Index - Types
+ *
+ * Core type definitions for the Pattern Index system.
+ * Rigour's Pattern Index prevents AI from reinventing existing code.
+ */
+export {};

package/package.json

@@ -1,9 +1,19 @@
 {
   "name": "@rigour-labs/core",
-  "version": "2.9.4",
+  "version": "2.11.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./pattern-index": {
+      "types": "./dist/pattern-index/index.d.ts",
+      "import": "./dist/pattern-index/index.js"
+    }
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/rigour-labs/rigour"
@@ -24,6 +34,9 @@
     "yaml": "^2.3.4",
     "zod": "^3.22.4"
   },
+  "optionalDependencies": {
+    "@xenova/transformers": "^2.17.2"
+  },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",
     "@types/micromatch": "^4.0.10",

package/src/index.ts

@@ -7,3 +7,7 @@ export * from './types/fix-packet.js';
 export { Gate, GateContext } from './gates/base.js';
 export { RetryLoopBreakerGate } from './gates/retry-loop-breaker.js';
 export * from './utils/logger.js';
+// Pattern Index is intentionally NOT exported here to prevent
+// native dependency issues (sharp/transformers) from leaking into 
+// non-AI parts of the system. 
+// Import from @rigour-labs/core/pattern-index instead.

package/src/pattern-index/embeddings.ts

@@ -0,0 +1,84 @@
+/**
+ * Semantic Embedding Service
+ * 
+ * Uses Transformers.js for local vector embeddings.
+ */
+
+/**
+ * Singleton for the embedding pipeline to avoid re-loading the model.
+ */
+let embeddingPipeline: any = null;
+
+/**
+ * Get or initialize the embedding pipeline.
+ */
+async function getPipeline() {
+    // Definitive bypass for tests to avoid native 'sharp' dependency issues
+    if (process.env.VITEST) {
+        return async (text: string) => {
+            const vector = new Array(384).fill(0);
+            for (let i = 0; i < Math.min(text.length, 384); i++) {
+                vector[i] = text.charCodeAt(i) / 255;
+            }
+            return { data: new Float32Array(vector) };
+        };
+    }
+
+    if (!embeddingPipeline) {
+        try {
+            // Dynamic import to isolate native dependency issues (like sharp)
+            const { pipeline } = await import('@xenova/transformers');
+
+            // Using a compact but high-quality model for local embeddings
+            embeddingPipeline = await pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2');
+        } catch (error) {
+            console.error('Failed to initialize embedding pipeline:', error);
+            throw error;
+        }
+    }
+    return embeddingPipeline;
+}
+
+/**
+ * Generate an embedding for a piece of text.
+ */
+export async function generateEmbedding(text: string): Promise<number[]> {
+    try {
+        const extractor = await getPipeline();
+        const output = await extractor(text, { pooling: 'mean', normalize: true });
+        return Array.from(output.data);
+    } catch (error) {
+        console.warn('Semantic reasoning disabled: Embedding generation failed.', error);
+        return [];
+    }
+}
+
+/**
+ * Calculate cosine similarity between two vectors.
+ */
+export function cosineSimilarity(v1: number[], v2: number[]): number {
+    if (!v1 || !v2 || v1.length !== v2.length || v1.length === 0) return 0;
+
+    let dotProduct = 0;
+    let norm1 = 0;
+    let norm2 = 0;
+
+    for (let i = 0; i < v1.length; i++) {
+        dotProduct += v1[i] * v2[i];
+        norm1 += v1[i] * v1[i];
+        norm2 += v2[i] * v2[i];
+    }
+
+    const denominator = Math.sqrt(norm1) * Math.sqrt(norm2);
+    return denominator === 0 ? 0 : dotProduct / denominator;
+}
+
+/**
+ * Perform semantic search against a list of embeddings.
+ */
+export function semanticSearch(queryVector: number[], entries: { embedding?: number[] }[]): number[] {
+    return entries.map(entry => {
+        if (!entry.embedding) return 0;
+        return cosineSimilarity(queryVector, entry.embedding);
+    });
+}

package/src/pattern-index/index.ts

@@ -0,0 +1,59 @@
+/**
+ * Pattern Index - Main Export
+ * 
+ * This is the public API for the Pattern Index system.
+ */
+
+// Types
+export type {
+    PatternType,
+    PatternEntry,
+    PatternIndex,
+    PatternIndexConfig,
+    PatternIndexStats,
+    IndexedFile,
+    PatternMatchResult,
+    PatternMatch,
+    PatternOverride,
+    StalenessResult,
+    StalenessIssue,
+    DeprecationEntry
+} from './types.js';
+
+// Indexer
+export {
+    PatternIndexer,
+    savePatternIndex,
+    loadPatternIndex,
+    getDefaultIndexPath
+} from './indexer.js';
+
+// Matcher
+export {
+    PatternMatcher,
+    checkPatternDuplicate,
+    type MatcherConfig
+} from './matcher.js';
+
+// Staleness Detection
+export {
+    StalenessDetector,
+    checkCodeStaleness
+} from './staleness.js';
+
+// Security Detection
+export {
+    SecurityDetector
+} from './security.js';
+
+// Override Management
+export {
+    OverrideManager,
+    loadConfigOverrides
+} from './overrides.js';
+// Embeddings
+export {
+    generateEmbedding,
+    semanticSearch,
+    cosineSimilarity
+} from './embeddings.js';

package/src/pattern-index/indexer.test.ts

@@ -0,0 +1,276 @@
+/**
+ * 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: string;
+
+    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();
+        });
+    });
+});