@rigour-labs/core 2.22.0 → 3.0.1

package/src/gates/inconsistent-error-handling.ts

@@ -1,254 +0,0 @@
-/**
- * Inconsistent Error Handling Gate
- *
- * Detects when the same error type is handled differently across the codebase.
- * This is an AI-specific failure mode — each agent session writes error handling
- * from scratch, leading to 4 different patterns for the same error type.
- *
- * Detection strategy:
- * 1. Extract all try-catch blocks and error handling patterns
- * 2. Cluster by caught error type (e.g. "Error", "TypeError", custom errors)
- * 3. Compare handling strategies within each cluster
- * 4. Flag types with >2 distinct handling patterns across files
- *
- * Examples of inconsistency:
- * - File A: catch(e) { console.log(e) }
- * - File B: catch(e) { throw new AppError(e) }
- * - File C: catch(e) { return null }
- * - File D: catch(e) { [empty] }
- *
- * @since v2.16.0
- */
-
-import { Gate, GateContext } from './base.js';
-import { Failure } from '../types/index.js';
-import { FileScanner } from '../utils/scanner.js';
-import { Logger } from '../utils/logger.js';
-import fs from 'fs-extra';
-import path from 'path';
-
-interface ErrorHandler {
-    file: string;
-    line: number;
-    errorType: string;       // What's caught: 'Error', 'TypeError', 'any', etc.
-    strategy: string;        // Classified handling strategy
-    rawPattern: string;      // First line of catch body for display
-}
-
-export interface InconsistentErrorHandlingConfig {
-    enabled?: boolean;
-    max_strategies_per_type?: number;  // Flag if more than N strategies, default 2
-    min_occurrences?: number;          // Minimum catch blocks to analyze, default 3
-    ignore_empty_catches?: boolean;    // Whether to count empty catches as a strategy
-}
-
-export class InconsistentErrorHandlingGate extends Gate {
-    private config: Required<InconsistentErrorHandlingConfig>;
-
-    constructor(config: InconsistentErrorHandlingConfig = {}) {
-        super('inconsistent-error-handling', 'Inconsistent Error Handling Detection');
-        this.config = {
-            enabled: config.enabled ?? true,
-            max_strategies_per_type: config.max_strategies_per_type ?? 2,
-            min_occurrences: config.min_occurrences ?? 3,
-            ignore_empty_catches: config.ignore_empty_catches ?? false,
-        };
-    }
-
-    async run(context: GateContext): Promise<Failure[]> {
-        if (!this.config.enabled) return [];
-
-        const failures: Failure[] = [];
-        const handlers: ErrorHandler[] = [];
-
-        const files = await FileScanner.findFiles({
-            cwd: context.cwd,
-            patterns: ['**/*.{ts,js,tsx,jsx}'],
-            ignore: [...(context.ignore || []), '**/node_modules/**', '**/dist/**', '**/*.test.*', '**/*.spec.*'],
-        });
-
-        Logger.info(`Inconsistent Error Handling: Scanning ${files.length} files`);
-
-        for (const file of files) {
-            try {
-                const content = await fs.readFile(path.join(context.cwd, file), 'utf-8');
-                this.extractErrorHandlers(content, file, handlers);
-            } catch (e) { }
-        }
-
-        // Group by error type
-        const byType = new Map<string, ErrorHandler[]>();
-        for (const handler of handlers) {
-            const existing = byType.get(handler.errorType) || [];
-            existing.push(handler);
-            byType.set(handler.errorType, existing);
-        }
-
-        // Analyze each error type for inconsistent handling
-        for (const [errorType, typeHandlers] of byType) {
-            if (typeHandlers.length < this.config.min_occurrences) continue;
-
-            // Count unique strategies
-            const strategies = new Map<string, ErrorHandler[]>();
-            for (const handler of typeHandlers) {
-                const existing = strategies.get(handler.strategy) || [];
-                existing.push(handler);
-                strategies.set(handler.strategy, existing);
-            }
-
-            // Filter out empty catches if configured
-            const activeStrategies = this.config.ignore_empty_catches
-                ? new Map([...strategies].filter(([k]) => k !== 'swallow'))
-                : strategies;
-
-            if (activeStrategies.size > this.config.max_strategies_per_type) {
-                // Only flag if handlers span multiple files
-                const uniqueFiles = new Set(typeHandlers.map(h => h.file));
-                if (uniqueFiles.size < 2) continue;
-
-                const strategyBreakdown = [...activeStrategies.entries()]
-                    .map(([strategy, handlers]) => {
-                        const files = [...new Set(handlers.map(h => h.file))].slice(0, 3);
-                        return `  • ${strategy} (${handlers.length}x): ${files.join(', ')}`;
-                    })
-                    .join('\n');
-
-                failures.push(this.createFailure(
-                    `Inconsistent error handling for '${errorType}': ${activeStrategies.size} different strategies found across ${uniqueFiles.size} files:\n${strategyBreakdown}`,
-                    [...uniqueFiles].slice(0, 5),
-                    `Standardize error handling for '${errorType}'. Create a shared error handler or establish a project convention. AI agents often write error handling from scratch each session, leading to divergent patterns.`,
-                    'Inconsistent Error Handling',
-                    typeHandlers[0].line,
-                    undefined,
-                    'high'
-                ));
-            }
-        }
-
-        return failures;
-    }
-
-    private extractErrorHandlers(content: string, file: string, handlers: ErrorHandler[]): void {
-        const lines = content.split('\n');
-
-        for (let i = 0; i < lines.length; i++) {
-            // Match catch clauses: catch (e), catch (error: Error), catch (e: TypeError)
-            const catchMatch = lines[i].match(/\bcatch\s*\(\s*(\w+)(?:\s*:\s*(\w+))?\s*\)/);
-            if (!catchMatch) continue;
-
-            const varName = catchMatch[1];
-            const explicitType = catchMatch[2] || 'any';
-
-            // Extract catch body (up to next closing brace at same level)
-            const body = this.extractCatchBody(lines, i);
-            if (!body) continue;
-
-            const strategy = this.classifyStrategy(body, varName);
-            const rawPattern = body.split('\n')[0]?.trim() || '';
-
-            handlers.push({
-                file,
-                line: i + 1,
-                errorType: explicitType,
-                strategy,
-                rawPattern,
-            });
-        }
-
-        // Also detect .catch() promise patterns
-        for (let i = 0; i < lines.length; i++) {
-            const catchMatch = lines[i].match(/\.catch\s*\(\s*(?:async\s+)?(?:\(\s*)?(\w+)/);
-            if (!catchMatch) continue;
-
-            const varName = catchMatch[1];
-
-            // Extract the callback body
-            const body = this.extractCatchCallbackBody(lines, i);
-            if (!body) continue;
-
-            const strategy = this.classifyStrategy(body, varName);
-
-            handlers.push({
-                file,
-                line: i + 1,
-                errorType: 'Promise',
-                strategy,
-                rawPattern: body.split('\n')[0]?.trim() || '',
-            });
-        }
-    }
-
-    private classifyStrategy(body: string, varName: string): string {
-        const trimmed = body.trim();
-
-        // Empty catch (swallow)
-        if (!trimmed || trimmed === '{}' || trimmed === '') {
-            return 'swallow';
-        }
-
-        // Re-throw
-        if (/\bthrow\b/.test(trimmed)) {
-            if (/\bthrow\s+new\b/.test(trimmed)) return 'wrap-and-throw';
-            if (new RegExp(`\\bthrow\\s+${varName}\\b`).test(trimmed)) return 'rethrow';
-            return 'throw-new';
-        }
-
-        // Return patterns
-        if (/\breturn\s+null\b/.test(trimmed)) return 'return-null';
-        if (/\breturn\s+undefined\b/.test(trimmed) || /\breturn\s*;/.test(trimmed)) return 'return-undefined';
-        if (/\breturn\s+\[\s*\]/.test(trimmed)) return 'return-empty-array';
-        if (/\breturn\s+\{\s*\}/.test(trimmed)) return 'return-empty-object';
-        if (/\breturn\s+false\b/.test(trimmed)) return 'return-false';
-        if (/\breturn\s+/.test(trimmed)) return 'return-value';
-
-        // Logging patterns
-        if (/console\.(error|warn)\b/.test(trimmed)) return 'log-error';
-        if (/console\.log\b/.test(trimmed)) return 'log-info';
-        if (/\blogger\b/i.test(trimmed) || /\blog\b/i.test(trimmed)) return 'log-custom';
-
-        // Process.exit
-        if (/process\.exit\b/.test(trimmed)) return 'exit';
-
-        // Response patterns (Express/HTTP)
-        if (/\bres\s*\.\s*status\b/.test(trimmed) || /\bres\s*\.\s*json\b/.test(trimmed)) return 'http-response';
-
-        // Notification patterns
-        if (/\bnotif|toast|alert|modal\b/i.test(trimmed)) return 'user-notification';
-
-        return 'other';
-    }
-
-    private extractCatchBody(lines: string[], catchLine: number): string | null {
-        let braceDepth = 0;
-        let started = false;
-        const body: string[] = [];
-
-        for (let i = catchLine; i < lines.length; i++) {
-            for (const ch of lines[i]) {
-                if (ch === '{') { braceDepth++; started = true; }
-                if (ch === '}') braceDepth--;
-            }
-            if (started && i > catchLine) body.push(lines[i]);
-            if (started && braceDepth === 0) break;
-        }
-
-        return body.length > 0 ? body.join('\n') : null;
-    }
-
-    private extractCatchCallbackBody(lines: string[], startLine: number): string | null {
-        let depth = 0;
-        let started = false;
-        const body: string[] = [];
-
-        for (let i = startLine; i < Math.min(startLine + 20, lines.length); i++) {
-            for (const ch of lines[i]) {
-                if (ch === '{' || ch === '(') { depth++; started = true; }
-                if (ch === '}' || ch === ')') depth--;
-            }
-            if (started && i > startLine) body.push(lines[i]);
-            if (started && depth <= 0) break;
-        }
-
-        return body.length > 0 ? body.join('\n') : null;
-    }
-}

package/src/gates/retry-loop-breaker.ts

@@ -1,151 +0,0 @@
-import { Gate, GateContext } from './base.js';
-import { Failure, Gates } from '../types/index.js';
-import fs from 'fs-extra';
-import path from 'path';
-
-interface FailureRecord {
-    category: string;
-    count: number;
-    lastError: string;
-    lastTimestamp: string;
-}
-
-interface RigourState {
-    failureHistory: Record<string, FailureRecord>;
-}
-
-const ERROR_PATTERNS: [RegExp, string][] = [
-    [/ERR_REQUIRE_ESM|Cannot find module|MODULE_NOT_FOUND/i, 'module_resolution'],
-    [/FUNCTION_INVOCATION_FAILED|Build Failed|deploy.*fail/i, 'deployment'],
-    [/TypeError|SyntaxError|ReferenceError|compilation.*error/i, 'runtime_error'],
-    [/Connection refused|ECONNREFUSED|timeout|ETIMEDOUT/i, 'network'],
-    [/Permission denied|EACCES|EPERM/i, 'permissions'],
-    [/ENOMEM|heap out of memory|OOM/i, 'resources'],
-];
-
-/**
- * Retry Loop Breaker Gate
- * 
- * Detects when an agent is stuck in a retry loop and forces them to consult
- * official documentation before continuing. This gate is universal and works
- * with any type of failure, not just specific tools or languages.
- */
-export class RetryLoopBreakerGate extends Gate {
-    constructor(private options: Gates['retry_loop_breaker']) {
-        super('retry_loop_breaker', 'Retry Loop Breaker');
-    }
-
-    async run(context: GateContext): Promise<Failure[]> {
-        const state = await this.loadState(context.cwd);
-        const failures: Failure[] = [];
-
-        for (const [category, record] of Object.entries(state.failureHistory)) {
-            if (record.count >= (this.options?.max_retries ?? 3)) {
-                const docUrl = this.options?.doc_sources?.[category] || this.getDefaultDocUrl(category);
-                failures.push(this.createFailure(
-                    `Operation '${category}' has failed ${record.count} times consecutively. Last error: ${record.lastError}`,
-                    undefined,
-                    `STOP RETRYING. You are in a loop. Consult the official documentation: ${docUrl}. Extract the canonical solution pattern and apply it.`,
-                    `Retry Loop Detected: ${category}`
-                ));
-            }
-        }
-
-        return failures;
-    }
-
-    /**
-     * Classify an error message into a category based on patterns.
-     */
-    static classifyError(errorMessage: string): string {
-        for (const [pattern, category] of ERROR_PATTERNS) {
-            if (pattern.test(errorMessage)) {
-                return category;
-            }
-        }
-        return 'general';
-    }
-
-    /**
-     * Record a failure for retry loop detection.
-     * Call this when an operation fails.
-     */
-    static async recordFailure(cwd: string, errorMessage: string, category?: string): Promise<void> {
-        const resolvedCategory = category || this.classifyError(errorMessage);
-        const state = await this.loadStateStatic(cwd);
-
-        const existing = state.failureHistory[resolvedCategory] || {
-            category: resolvedCategory,
-            count: 0,
-            lastError: '',
-            lastTimestamp: ''
-        };
-        existing.count += 1;
-        existing.lastError = errorMessage.slice(0, 500); // Truncate for storage
-        existing.lastTimestamp = new Date().toISOString();
-        state.failureHistory[resolvedCategory] = existing;
-
-        await this.saveStateStatic(cwd, state);
-    }
-
-    /**
-     * Clear failure history for a specific category after successful resolution.
-     */
-    static async clearFailure(cwd: string, category: string): Promise<void> {
-        const state = await this.loadStateStatic(cwd);
-        delete state.failureHistory[category];
-        await this.saveStateStatic(cwd, state);
-    }
-
-    /**
-     * Clear all failure history.
-     */
-    static async clearAllFailures(cwd: string): Promise<void> {
-        const state = await this.loadStateStatic(cwd);
-        state.failureHistory = {};
-        await this.saveStateStatic(cwd, state);
-    }
-
-    /**
-     * Get the current failure state for inspection.
-     */
-    static async getState(cwd: string): Promise<RigourState> {
-        return this.loadStateStatic(cwd);
-    }
-
-    private getDefaultDocUrl(category: string): string {
-        const defaults: Record<string, string> = {
-            module_resolution: 'https://nodejs.org/api/esm.html',
-            deployment: 'Check the deployment platform\'s official documentation',
-            runtime_error: 'Check the language\'s official documentation',
-            network: 'Check network configuration and firewall rules',
-            permissions: 'Check file/directory permissions and ownership',
-            resources: 'Check system resource limits and memory allocation',
-            general: 'Consult the relevant official documentation',
-        };
-        return defaults[category] || defaults.general;
-    }
-
-    private async loadState(cwd: string): Promise<RigourState> {
-        return RetryLoopBreakerGate.loadStateStatic(cwd);
-    }
-
-    private static async loadStateStatic(cwd: string): Promise<RigourState> {
-        const statePath = path.join(cwd, '.rigour', 'state.json');
-        if (await fs.pathExists(statePath)) {
-            try {
-                const data = await fs.readJson(statePath);
-                return { failureHistory: data.failureHistory || {}, ...data };
-            } catch {
-                return { failureHistory: {} };
-            }
-        }
-        return { failureHistory: {} };
-    }
-
-    private static async saveStateStatic(cwd: string, state: RigourState): Promise<void> {
-        const statePath = path.join(cwd, '.rigour', 'state.json');
-        await fs.ensureDir(path.dirname(statePath));
-        await fs.writeJson(statePath, state, { spaces: 2 });
-    }
-}

package/src/gates/runner.ts

@@ -1,188 +0,0 @@
-import { Gate } from './base.js';
-import { Failure, Config, Report, Status, Severity, SEVERITY_WEIGHTS } from '../types/index.js';
-import { FileGate } from './file.js';
-import { ContentGate } from './content.js';
-import { StructureGate } from './structure.js';
-import { ASTGate } from './ast.js';
-import { FileGuardGate } from './safety.js';
-import { DependencyGate } from './dependency.js';
-import { CoverageGate } from './coverage.js';
-import { ContextGate } from './context.js';
-import { ContextEngine } from '../services/context-engine.js';
-import { EnvironmentGate } from './environment.js';
-import { RetryLoopBreakerGate } from './retry-loop-breaker.js';
-import { AgentTeamGate } from './agent-team.js';
-import { CheckpointGate } from './checkpoint.js';
-import { SecurityPatternsGate } from './security-patterns.js';
-import { DuplicationDriftGate } from './duplication-drift.js';
-import { HallucinatedImportsGate } from './hallucinated-imports.js';
-import { InconsistentErrorHandlingGate } from './inconsistent-error-handling.js';
-import { ContextWindowArtifactsGate } from './context-window-artifacts.js';
-import { execa } from 'execa';
-import { Logger } from '../utils/logger.js';
-
-export class GateRunner {
-    private gates: Gate[] = [];
-
-    constructor(private config: Config) {
-        this.initializeGates();
-    }
-
-    private initializeGates() {
-        // Retry Loop Breaker Gate - HIGHEST PRIORITY (runs first)
-        if (this.config.gates.retry_loop_breaker?.enabled !== false) {
-            this.gates.push(new RetryLoopBreakerGate(this.config.gates.retry_loop_breaker));
-        }
-
-        if (this.config.gates.max_file_lines) {
-            this.gates.push(new FileGate({ maxLines: this.config.gates.max_file_lines }));
-        }
-        this.gates.push(
-            new ContentGate({
-                forbidTodos: !!this.config.gates.forbid_todos,
-                forbidFixme: !!this.config.gates.forbid_fixme,
-            })
-        );
-        if (this.config.gates.required_files) {
-            this.gates.push(new StructureGate({ requiredFiles: this.config.gates.required_files }));
-        }
-        this.gates.push(new ASTGate(this.config.gates));
-        this.gates.push(new DependencyGate(this.config));
-        this.gates.push(new FileGuardGate(this.config.gates));
-        this.gates.push(new CoverageGate(this.config.gates));
-
-        if (this.config.gates.context?.enabled) {
-            this.gates.push(new ContextGate(this.config.gates));
-        }
-
-        // Agent Team Governance Gate (for Opus 4.6 / GPT-5.3 multi-agent workflows)
-        if (this.config.gates.agent_team?.enabled) {
-            this.gates.push(new AgentTeamGate(this.config.gates.agent_team));
-        }
-
-        // Checkpoint Supervision Gate (for long-running GPT-5.3 coworking mode)
-        if (this.config.gates.checkpoint?.enabled) {
-            this.gates.push(new CheckpointGate(this.config.gates.checkpoint));
-        }
-
-        // Security Patterns Gate (code-level vulnerability detection) — enabled by default since v2.15
-        if (this.config.gates.security?.enabled !== false) {
-            this.gates.push(new SecurityPatternsGate(this.config.gates.security));
-        }
-
-        // v2.16+ AI-Native Drift Detection Gates (enabled by default)
-        if (this.config.gates.duplication_drift?.enabled !== false) {
-            this.gates.push(new DuplicationDriftGate(this.config.gates.duplication_drift));
-        }
-
-        if (this.config.gates.hallucinated_imports?.enabled !== false) {
-            this.gates.push(new HallucinatedImportsGate(this.config.gates.hallucinated_imports));
-        }
-
-        if (this.config.gates.inconsistent_error_handling?.enabled !== false) {
-            this.gates.push(new InconsistentErrorHandlingGate(this.config.gates.inconsistent_error_handling));
-        }
-
-        if (this.config.gates.context_window_artifacts?.enabled !== false) {
-            this.gates.push(new ContextWindowArtifactsGate(this.config.gates.context_window_artifacts));
-        }
-
-        // Environment Alignment Gate (Should be prioritized)
-        if (this.config.gates.environment?.enabled) {
-            this.gates.unshift(new EnvironmentGate(this.config.gates));
-        }
-    }
-
-    /**
-     * Allows adding custom gates dynamically (SOLID - Open/Closed Principle)
-     */
-    addGate(gate: Gate) {
-        this.gates.push(gate);
-    }
-
-    async run(cwd: string, patterns?: string[]): Promise<Report> {
-        const start = Date.now();
-        const failures: Failure[] = [];
-        const summary: Record<string, Status> = {};
-
-        const ignore = this.config.ignore;
-
-        // 0. Run Context Discovery
-        let record;
-        if (this.config.gates.context?.enabled) {
-            const engine = new ContextEngine(this.config);
-            record = await engine.discover(cwd);
-        }
-
-        // 1. Run internal gates
-        for (const gate of this.gates) {
-            try {
-                const gateFailures = await gate.run({ cwd, record, ignore, patterns });
-                if (gateFailures.length > 0) {
-                    failures.push(...gateFailures);
-                    summary[gate.id] = 'FAIL';
-                } else {
-                    summary[gate.id] = 'PASS';
-                }
-            } catch (error: any) {
-                Logger.error(`Gate ${gate.id} failed with error: ${error.message}`);
-                summary[gate.id] = 'ERROR';
-                failures.push({
-                    id: gate.id,
-                    title: `Gate Error: ${gate.title}`,
-                    details: error.message,
-                    hint: 'There was an internal error running this gate. Check the logs.',
-                });
-            }
-        }
-
-        // 2. Run command gates (lint, test, etc.)
-        const commands = this.config.commands;
-        if (commands) {
-            for (const [key, cmd] of Object.entries(commands)) {
-                if (!cmd) {
-                    summary[key] = 'SKIP';
-                    continue;
-                }
-
-                try {
-                    Logger.info(`Running command gate: ${key} (${cmd})`);
-                    await execa(cmd, { shell: true, cwd });
-                    summary[key] = 'PASS';
-                } catch (error: any) {
-                    summary[key] = 'FAIL';
-                    failures.push({
-                        id: key,
-                        title: `${key.toUpperCase()} Check Failed`,
-                        details: error.stderr || error.stdout || error.message,
-                        hint: `Fix the issues reported by \`${cmd}\`. Use rigorous standards (SOLID, DRY) in your resolution.`,
-                    });
-                }
-            }
-        }
-
-        const status: Status = failures.length > 0 ? 'FAIL' : 'PASS';
-
-        // Severity-weighted scoring: each failure deducts based on its severity
-        // critical=20, high=10, medium=5, low=2, info=0
-        const severityBreakdown: Record<string, number> = {};
-        let totalDeduction = 0;
-        for (const f of failures) {
-            const sev = (f.severity || 'medium') as Severity;
-            severityBreakdown[sev] = (severityBreakdown[sev] || 0) + 1;
-            totalDeduction += SEVERITY_WEIGHTS[sev] ?? 5;
-        }
-        const score = Math.max(0, 100 - totalDeduction);
-
-        return {
-            status,
-            summary,
-            failures,
-            stats: {
-                duration_ms: Date.now() - start,
-                score,
-                severity_breakdown: severityBreakdown,
-            },
-        };
-    }
-}

package/src/gates/safety.ts

@@ -1,56 +0,0 @@
-import { Gate, GateContext } from './base.js';
-import { Failure, Gates } from '../types/index.js';
-import { execa } from 'execa';
-
-export class FileGuardGate extends Gate {
-    constructor(private config: Gates) {
-        super('file-guard', 'File Guard — Protected Paths');
-    }
-
-    async run(context: GateContext): Promise<Failure[]> {
-        const failures: Failure[] = [];
-        const safety = this.config.safety || {};
-        const protectedPaths = safety.protected_paths || [];
-
-        if (protectedPaths.length === 0) return [];
-
-        try {
-            // Check for modified files in protected paths using git
-            // File Guard - if an agent touched protected files, we fail.
-            const { stdout } = await execa('git', ['status', '--porcelain'], { cwd: context.cwd });
-            const modifiedFiles = stdout.split('\n')
-                .filter(line => {
-                    const status = line.slice(0, 2);
-                    // M: Modified, A: Added (staged), D: Deleted, R: Renamed
-                    // We ignore ?? (Untracked) to allow rigour init and new doc creation
-                    return /M|A|D|R/.test(status);
-                })
-                .map(line => line.slice(3).trim());
-
-            for (const file of modifiedFiles) {
-                if (this.isProtected(file, protectedPaths)) {
-                    const message = `Protected file '${file}' was modified.`;
-                    failures.push(this.createFailure(
-                        message,
-                        [file],
-                        `Agents are forbidden from modifying files in ${protectedPaths.join(', ')}.`,
-                        message
-                    ));
-                }
-            }
-        } catch (error) {
-            // If not a git repo, skip safety for now
-        }
-
-        return failures;
-    }
-
-    private isProtected(file: string, patterns: string[]): boolean {
-        return patterns.some(p => {
-            const cleanP = p.replace('/**', '').replace('/*', '');
-            if (file === cleanP) return true;
-            if (cleanP.endsWith('/')) return file.startsWith(cleanP);
-            return file.startsWith(cleanP + '/');
-        });
-    }
-}