@rigour-labs/core 2.21.2 → 3.0.0

package/src/gates/checkpoint.ts

@@ -1,311 +0,0 @@
-/**
- * Checkpoint Supervision Gate
- * 
- * Monitors agent quality during extended execution for frontier models
- * like GPT-5.3-Codex "coworking mode" that run autonomously for long periods.
- * 
- * Features:
- * - Time-based checkpoint triggers
- * - Quality score tracking
- * - Drift detection (quality degradation over time)
- * - Auto-save on failure
- * 
- * @since v2.14.0
- */
-
-import { Gate, GateContext } from './base.js';
-import { Failure } from '../types/index.js';
-import { Logger } from '../utils/logger.js';
-import * as fs from 'fs';
-import * as path from 'path';
-
-export interface CheckpointEntry {
-    checkpointId: string;
-    timestamp: Date;
-    progressPct: number;
-    filesChanged: string[];
-    summary: string;
-    qualityScore: number;
-    warnings: string[];
-}
-
-export interface CheckpointSession {
-    sessionId: string;
-    startedAt: Date;
-    lastCheckpoint?: Date;
-    checkpoints: CheckpointEntry[];
-    status: 'active' | 'completed' | 'aborted';
-}
-
-export interface CheckpointConfig {
-    enabled?: boolean;
-    interval_minutes?: number;
-    quality_threshold?: number;
-    drift_detection?: boolean;
-    auto_save_on_failure?: boolean;
-}
-
-// In-memory checkpoint store (persisted to .rigour/checkpoint-session.json)
-let currentCheckpointSession: CheckpointSession | null = null;
-
-/**
- * Generate unique checkpoint ID
- */
-function generateCheckpointId(): string {
-    return `cp-${Date.now()}-${Math.random().toString(36).substr(2, 6)}`;
-}
-
-/**
- * Get or create checkpoint session
- */
-export function getOrCreateCheckpointSession(cwd: string): CheckpointSession {
-    if (!currentCheckpointSession) {
-        loadCheckpointSession(cwd);
-    }
-    if (!currentCheckpointSession) {
-        currentCheckpointSession = {
-            sessionId: `chk-session-${Date.now()}`,
-            startedAt: new Date(),
-            checkpoints: [],
-            status: 'active',
-        };
-        persistCheckpointSession(cwd);
-    }
-    return currentCheckpointSession;
-}
-
-/**
- * Record a checkpoint with quality evaluation
- */
-export function recordCheckpoint(
-    cwd: string,
-    progressPct: number,
-    filesChanged: string[],
-    summary: string,
-    qualityScore: number
-): { continue: boolean; warnings: string[]; checkpoint: CheckpointEntry } {
-    const session = getOrCreateCheckpointSession(cwd);
-    const warnings: string[] = [];
-
-    // Default threshold
-    const qualityThreshold = 80;
-
-    // Check if quality is below threshold
-    const shouldContinue = qualityScore >= qualityThreshold;
-    if (!shouldContinue) {
-        warnings.push(`Quality score ${qualityScore}% is below threshold ${qualityThreshold}%`);
-    }
-
-    // Detect drift (quality degradation over recent checkpoints)
-    if (session.checkpoints.length >= 2) {
-        const recentScores = session.checkpoints.slice(-3).map(cp => cp.qualityScore);
-        const avgRecent = recentScores.reduce((a, b) => a + b, 0) / recentScores.length;
-
-        if (qualityScore < avgRecent - 10) {
-            warnings.push(`Drift detected: quality dropped from avg ${avgRecent.toFixed(0)}% to ${qualityScore}%`);
-        }
-    }
-
-    const checkpoint: CheckpointEntry = {
-        checkpointId: generateCheckpointId(),
-        timestamp: new Date(),
-        progressPct,
-        filesChanged,
-        summary,
-        qualityScore,
-        warnings,
-    };
-
-    session.checkpoints.push(checkpoint);
-    session.lastCheckpoint = new Date();
-    persistCheckpointSession(cwd);
-
-    return { continue: shouldContinue, warnings, checkpoint };
-}
-
-/**
- * Get current checkpoint session
- */
-export function getCheckpointSession(cwd: string): CheckpointSession | null {
-    if (!currentCheckpointSession) {
-        loadCheckpointSession(cwd);
-    }
-    return currentCheckpointSession;
-}
-
-/**
- * Complete checkpoint session
- */
-export function completeCheckpointSession(cwd: string): void {
-    if (currentCheckpointSession) {
-        currentCheckpointSession.status = 'completed';
-        persistCheckpointSession(cwd);
-    }
-}
-
-/**
- * Abort checkpoint session (quality too low)
- */
-export function abortCheckpointSession(cwd: string, reason: string): void {
-    if (currentCheckpointSession) {
-        currentCheckpointSession.status = 'aborted';
-        // Add final checkpoint with abort reason
-        currentCheckpointSession.checkpoints.push({
-            checkpointId: generateCheckpointId(),
-            timestamp: new Date(),
-            progressPct: currentCheckpointSession.checkpoints.length > 0
-                ? currentCheckpointSession.checkpoints[currentCheckpointSession.checkpoints.length - 1].progressPct
-                : 0,
-            filesChanged: [],
-            summary: `Session aborted: ${reason}`,
-            qualityScore: 0,
-            warnings: [reason],
-        });
-        persistCheckpointSession(cwd);
-    }
-}
-
-/**
- * Clear checkpoint session
- */
-export function clearCheckpointSession(cwd: string): void {
-    currentCheckpointSession = null;
-    const sessionPath = path.join(cwd, '.rigour', 'checkpoint-session.json');
-    if (fs.existsSync(sessionPath)) {
-        fs.unlinkSync(sessionPath);
-    }
-}
-
-function persistCheckpointSession(cwd: string): void {
-    const rigourDir = path.join(cwd, '.rigour');
-    if (!fs.existsSync(rigourDir)) {
-        fs.mkdirSync(rigourDir, { recursive: true });
-    }
-    const sessionPath = path.join(rigourDir, 'checkpoint-session.json');
-    fs.writeFileSync(sessionPath, JSON.stringify(currentCheckpointSession, null, 2));
-}
-
-function loadCheckpointSession(cwd: string): void {
-    const sessionPath = path.join(cwd, '.rigour', 'checkpoint-session.json');
-    if (fs.existsSync(sessionPath)) {
-        try {
-            const data = JSON.parse(fs.readFileSync(sessionPath, 'utf-8'));
-            currentCheckpointSession = {
-                ...data,
-                startedAt: new Date(data.startedAt),
-                lastCheckpoint: data.lastCheckpoint ? new Date(data.lastCheckpoint) : undefined,
-                checkpoints: data.checkpoints.map((cp: any) => ({
-                    ...cp,
-                    timestamp: new Date(cp.timestamp),
-                })),
-            };
-        } catch (err) {
-            Logger.warn('Failed to load checkpoint session, starting fresh');
-            currentCheckpointSession = null;
-        }
-    }
-}
-
-/**
- * Calculate time since last checkpoint
- */
-function timeSinceLastCheckpoint(session: CheckpointSession): number {
-    const lastTime = session.lastCheckpoint || session.startedAt;
-    return (Date.now() - lastTime.getTime()) / 1000 / 60; // minutes
-}
-
-/**
- * Detect quality drift pattern
- */
-function detectDrift(checkpoints: CheckpointEntry[]): { hasDrift: boolean; trend: 'improving' | 'stable' | 'degrading' } {
-    if (checkpoints.length < 3) {
-        return { hasDrift: false, trend: 'stable' };
-    }
-
-    const recent = checkpoints.slice(-5);
-    const scores = recent.map(cp => cp.qualityScore);
-
-    // Calculate trend using simple linear regression
-    const n = scores.length;
-    const sumX = (n * (n - 1)) / 2;
-    const sumY = scores.reduce((a, b) => a + b, 0);
-    const sumXY = scores.reduce((sum, y, x) => sum + x * y, 0);
-    const sumX2 = (n * (n - 1) * (2 * n - 1)) / 6;
-
-    const slope = (n * sumXY - sumX * sumY) / (n * sumX2 - sumX * sumX);
-
-    if (slope < -2) {
-        return { hasDrift: true, trend: 'degrading' };
-    } else if (slope > 2) {
-        return { hasDrift: false, trend: 'improving' };
-    }
-    return { hasDrift: false, trend: 'stable' };
-}
-
-export class CheckpointGate extends Gate {
-    private config: CheckpointConfig;
-
-    constructor(config: CheckpointConfig = {}) {
-        super('checkpoint', 'Checkpoint Supervision');
-        this.config = {
-            enabled: config.enabled ?? false,
-            interval_minutes: config.interval_minutes ?? 15,
-            quality_threshold: config.quality_threshold ?? 80,
-            drift_detection: config.drift_detection ?? true,
-            auto_save_on_failure: config.auto_save_on_failure ?? true,
-        };
-    }
-
-    async run(context: GateContext): Promise<Failure[]> {
-        if (!this.config.enabled) {
-            return [];
-        }
-
-        const failures: Failure[] = [];
-        const session = getCheckpointSession(context.cwd);
-
-        if (!session || session.checkpoints.length === 0) {
-            // No checkpoints yet, skip
-            return [];
-        }
-
-        Logger.info(`Checkpoint Gate: ${session.checkpoints.length} checkpoints in session`);
-
-        // Check 1: Time since last checkpoint
-        const minutesSinceLast = timeSinceLastCheckpoint(session);
-        if (minutesSinceLast > (this.config.interval_minutes ?? 15) * 2) {
-            failures.push(this.createFailure(
-                `No checkpoint in ${minutesSinceLast.toFixed(0)} minutes (expected every ${this.config.interval_minutes} min)`,
-                undefined,
-                'Ensure agent is reporting checkpoints via rigour_checkpoint MCP tool',
-                'Missing Checkpoint'
-            ));
-        }
-
-        // Check 2: Quality threshold
-        const lastCheckpoint = session.checkpoints[session.checkpoints.length - 1];
-        if (lastCheckpoint.qualityScore < (this.config.quality_threshold ?? 80)) {
-            failures.push(this.createFailure(
-                `Quality score ${lastCheckpoint.qualityScore}% is below threshold ${this.config.quality_threshold}%`,
-                lastCheckpoint.filesChanged,
-                'Review recent changes and address quality issues before continuing',
-                'Quality Below Threshold'
-            ));
-        }
-
-        // Check 3: Drift detection
-        if (this.config.drift_detection) {
-            const { hasDrift, trend } = detectDrift(session.checkpoints);
-            if (hasDrift && trend === 'degrading') {
-                failures.push(this.createFailure(
-                    `Quality drift detected: scores are degrading over time`,
-                    undefined,
-                    'Agent performance is declining. Consider pausing and reviewing recent work.',
-                    'Quality Drift Detected'
-                ));
-            }
-        }
-
-        return failures;
-    }
-}

package/src/gates/content.ts

@@ -1,50 +0,0 @@
-import { Gate, GateContext } from './base.js';
-import { Failure } from '../types/index.js';
-import { FileScanner } from '../utils/scanner.js';
-
-export interface ContentGateConfig {
-    forbidTodos: boolean;
-    forbidFixme: boolean;
-}
-
-export class ContentGate extends Gate {
-    constructor(private config: ContentGateConfig) {
-        super('content-check', 'Forbidden Content');
-    }
-
-    async run(context: GateContext): Promise<Failure[]> {
-        const patterns: RegExp[] = [];
-        if (this.config.forbidTodos) patterns.push(/TODO/i);
-        if (this.config.forbidFixme) patterns.push(/FIXME/i);
-
-        if (patterns.length === 0) return [];
-
-        const files = await FileScanner.findFiles({
-            cwd: context.cwd,
-            ignore: context.ignore,
-            patterns: context.patterns
-        });
-        const contents = await FileScanner.readFiles(context.cwd, files);
-
-        const failures: Failure[] = [];
-        for (const [file, content] of contents) {
-            const lines = content.split('\n');
-            lines.forEach((line, index) => {
-                for (const pattern of patterns) {
-                    if (pattern.test(line)) {
-                        failures.push(this.createFailure(
-                            `Forbidden placeholder '${pattern.source}' found`,
-                            [file],
-                            'Remove forbidden comments. address the root cause or create a tracked issue.',
-                            undefined,
-                            index + 1,
-                            index + 1
-                        ));
-                    }
-                }
-            });
-        }
-
-        return failures;
-    }
-}

package/src/gates/context.ts

@@ -1,267 +0,0 @@
-import { Gate, GateContext } from './base.js';
-import { Failure, Gates } 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';
-
-/**
- * Extended Context Configuration (v2.14+)
- * For 1M token frontier models like Opus 4.6
- */
-export interface ExtendedContextConfig {
-    enabled?: boolean;
-    sensitivity?: number;
-    mining_depth?: number;
-    cross_file_patterns?: boolean;  // NEW: Enable cross-file pattern analysis
-    naming_consistency?: boolean;   // NEW: Check naming convention drift
-    import_relationships?: boolean; // NEW: Validate import patterns
-    max_cross_file_depth?: number;  // NEW: How many related files to analyze
-}
-
-export class ContextGate extends Gate {
-    private extendedConfig: ExtendedContextConfig;
-
-    constructor(private config: Gates) {
-        super('context-drift', 'Context Awareness & Drift Detection');
-        this.extendedConfig = {
-            enabled: config.context?.enabled ?? false,
-            sensitivity: config.context?.sensitivity ?? 0.8,
-            mining_depth: config.context?.mining_depth ?? 100,
-            cross_file_patterns: true,  // Default ON for frontier model support
-            naming_consistency: true,
-            import_relationships: true,
-            max_cross_file_depth: 50,
-        };
-    }
-
-    async run(context: GateContext): Promise<Failure[]> {
-        const failures: Failure[] = [];
-        const record = context.record;
-        if (!record || !this.extendedConfig.enabled) return [];
-
-        const files = await FileScanner.findFiles({ cwd: context.cwd });
-        const envAnchors = record.anchors.filter(a => a.type === 'env' && a.confidence >= 1);
-
-        // Collect all patterns across files for cross-file analysis
-        const namingPatterns: Map<string, { casing: string; file: string; count: number }[]> = new Map();
-        const importPatterns: Map<string, string[]> = new Map();
-
-        for (const file of files) {
-            try {
-                const content = await fs.readFile(path.join(context.cwd, file), 'utf-8');
-
-                // 1. Original: Detect Redundant Suffixes (The Golden Example)
-                this.checkEnvDrift(content, file, envAnchors, failures);
-
-                // 2. NEW: Cross-file pattern collection
-                if (this.extendedConfig.cross_file_patterns) {
-                    this.collectNamingPatterns(content, file, namingPatterns);
-                    this.collectImportPatterns(content, file, importPatterns);
-                }
-
-            } catch (e) { }
-        }
-
-        // 3. NEW: Analyze naming consistency across files
-        if (this.extendedConfig.naming_consistency) {
-            this.analyzeNamingConsistency(namingPatterns, failures);
-        }
-
-        // 4. NEW: Analyze import relationship patterns
-        if (this.extendedConfig.import_relationships) {
-            this.analyzeImportPatterns(importPatterns, failures);
-        }
-
-        return failures;
-    }
-
-    private checkEnvDrift(content: string, file: string, anchors: any[], failures: Failure[]) {
-        // Find all environment variable accesses in the content
-        const matches = content.matchAll(/process\.env(?:\.([A-Z0-9_]+)|\[['"]([A-Z0-9_]+)['"]\])/g);
-
-        for (const match of matches) {
-            const accessedVar = match[1] || match[2];
-
-            for (const anchor of anchors) {
-                // If the accessed variable contains the anchor but is not equal to it, 
-                // it's a potential "invented" redundancy (e.g. CORE_URL vs CORE_URL_PROD)
-                if (accessedVar !== anchor.id && accessedVar.includes(anchor.id)) {
-                    const deviation = accessedVar.replace(anchor.id, '').replace(/^_|_$/, '');
-
-                    failures.push(this.createFailure(
-                        `Context Drift: Redundant variation '${accessedVar}' detected in ${file}.`,
-                        [file],
-                        `The project already uses '${anchor.id}' as a standard anchor. Avoid inventing variations like '${deviation}'. Reuse the existing anchor or align with established project patterns.`
-                    ));
-                }
-            }
-        }
-    }
-
-    /**
-     * Collect naming patterns (function names, class names, variable names)
-     */
-    private collectNamingPatterns(
-        content: string,
-        file: string,
-        patterns: Map<string, { casing: string; file: string; count: number }[]>
-    ) {
-        // Named function declarations: function fetchData() { ... }
-        const namedFuncMatches = content.matchAll(/function\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\(/g);
-        for (const match of namedFuncMatches) {
-            const casing = this.detectCasing(match[1]);
-            this.addPattern(patterns, 'function', { casing, file, count: 1 });
-        }
-
-        // Arrow function expressions: (export) const fetchData = (async) (...) => { ... }
-        const arrowFuncMatches = content.matchAll(/(?:export\s+)?(?:const|let|var)\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*=\s*(?:async\s+)?(?:\([^)]*\)|[a-zA-Z_$][a-zA-Z0-9_$]*)\s*=>/g);
-        for (const match of arrowFuncMatches) {
-            const casing = this.detectCasing(match[1]);
-            this.addPattern(patterns, 'function', { casing, file, count: 1 });
-        }
-
-        // Function expressions: (export) const fetchData = (async) function(...) { ... }
-        const funcExprMatches = content.matchAll(/(?:export\s+)?(?:const|let|var)\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*=\s*(?:async\s+)?function\s*\(/g);
-        for (const match of funcExprMatches) {
-            const casing = this.detectCasing(match[1]);
-            this.addPattern(patterns, 'function', { casing, file, count: 1 });
-        }
-
-        // Class declarations
-        const classMatches = content.matchAll(/class\s+([A-Za-z_$][A-Za-z0-9_$]*)/g);
-        for (const match of classMatches) {
-            const casing = this.detectCasing(match[1]);
-            this.addPattern(patterns, 'class', { casing, file, count: 1 });
-        }
-
-        // Interface declarations (TypeScript)
-        const interfaceMatches = content.matchAll(/interface\s+([A-Za-z_$][A-Za-z0-9_$]*)/g);
-        for (const match of interfaceMatches) {
-            const casing = this.detectCasing(match[1]);
-            this.addPattern(patterns, 'interface', { casing, file, count: 1 });
-        }
-    }
-
-    /**
-     * Collect import patterns
-     */
-    private collectImportPatterns(content: string, file: string, patterns: Map<string, string[]>) {
-        // ES6 imports
-        const importMatches = content.matchAll(/import\s+(?:{[^}]+}|\*\s+as\s+\w+|\w+)\s+from\s+['"]([^'"]+)['"]/g);
-        for (const match of importMatches) {
-            const importPath = match[1];
-            if (!patterns.has(file)) {
-                patterns.set(file, []);
-            }
-            patterns.get(file)!.push(importPath);
-        }
-    }
-
-    /**
-     * Analyze naming consistency across files
-     */
-    private analyzeNamingConsistency(
-        patterns: Map<string, { casing: string; file: string; count: number }[]>,
-        failures: Failure[]
-    ) {
-        for (const [type, entries] of patterns) {
-            const casingCounts = new Map<string, number>();
-            for (const entry of entries) {
-                casingCounts.set(entry.casing, (casingCounts.get(entry.casing) || 0) + entry.count);
-            }
-
-            // Find dominant casing
-            let dominant = '';
-            let maxCount = 0;
-            for (const [casing, count] of casingCounts) {
-                if (count > maxCount) {
-                    dominant = casing;
-                    maxCount = count;
-                }
-            }
-
-            // Report violations (non-dominant casing with significant usage)
-            const total = entries.reduce((sum, e) => sum + e.count, 0);
-            const threshold = total * (1 - (this.extendedConfig.sensitivity ?? 0.8));
-
-            for (const [casing, count] of casingCounts) {
-                if (casing !== dominant && count > threshold) {
-                    const violatingFiles = entries.filter(e => e.casing === casing).map(e => e.file);
-                    const uniqueFiles = [...new Set(violatingFiles)].slice(0, 5);
-
-                    failures.push(this.createFailure(
-                        `Cross-file naming inconsistency: ${type} names use ${casing} in ${count} places (dominant is ${dominant})`,
-                        uniqueFiles,
-                        `Standardize ${type} naming to ${dominant}. Found ${casing} in: ${uniqueFiles.join(', ')}`,
-                        'Naming Convention Drift'
-                    ));
-                }
-            }
-        }
-    }
-
-    /**
-     * Analyze import patterns for consistency
-     */
-    private analyzeImportPatterns(patterns: Map<string, string[]>, failures: Failure[]) {
-        // Check for mixed import styles (relative vs absolute)
-        const relativeCount = new Map<string, number>();
-        const absoluteCount = new Map<string, number>();
-
-        for (const [file, imports] of patterns) {
-            for (const imp of imports) {
-                if (imp.startsWith('.') || imp.startsWith('..')) {
-                    relativeCount.set(file, (relativeCount.get(file) || 0) + 1);
-                } else if (!imp.startsWith('@') && !imp.includes('/')) {
-                    // Skip external packages
-                } else {
-                    absoluteCount.set(file, (absoluteCount.get(file) || 0) + 1);
-                }
-            }
-        }
-
-        // Detect files with both relative AND absolute local imports
-        const mixedFiles: string[] = [];
-        for (const file of patterns.keys()) {
-            const hasRelative = (relativeCount.get(file) || 0) > 0;
-            const hasAbsolute = (absoluteCount.get(file) || 0) > 0;
-            if (hasRelative && hasAbsolute) {
-                mixedFiles.push(file);
-            }
-        }
-
-        if (mixedFiles.length > 3) {
-            failures.push(this.createFailure(
-                `Cross-file import inconsistency: ${mixedFiles.length} files mix relative and absolute imports`,
-                mixedFiles.slice(0, 5),
-                'Standardize import style across the codebase. Use either relative (./foo) or path aliases (@/foo) consistently.',
-                'Import Pattern Drift'
-            ));
-        }
-    }
-
-    /**
-     * Detect casing convention of an identifier
-     */
-    private detectCasing(name: string): string {
-        if (/^[A-Z][a-z]/.test(name) && /[a-z][A-Z]/.test(name)) return 'PascalCase';
-        if (/^[a-z]/.test(name) && /[a-z][A-Z]/.test(name)) return 'camelCase';
-        if (/^[a-z][a-zA-Z0-9]*$/.test(name)) return 'camelCase';  // single-word lowercase (e.g. fetch, use, get)
-        if (/^[a-z]+(_[a-z]+)+$/.test(name)) return 'snake_case';
-        if (/^[A-Z]+(_[A-Z]+)*$/.test(name)) return 'SCREAMING_SNAKE';
-        if (/^[A-Z][a-zA-Z]*$/.test(name)) return 'PascalCase';
-        return 'unknown';
-    }
-
-    private addPattern(
-        patterns: Map<string, { casing: string; file: string; count: number }[]>,
-        type: string,
-        entry: { casing: string; file: string; count: number }
-    ) {
-        if (!patterns.has(type)) {
-            patterns.set(type, []);
-        }
-        patterns.get(type)!.push(entry);
-    }
-}