@rigour-labs/core 2.21.1 → 2.22.0

package/src/gates/context-window-artifacts.ts

@@ -0,0 +1,277 @@
+/**
+ * Context Window Artifacts Gate
+ *
+ * Detects quality degradation patterns within a single file that emerge
+ * when AI loses context mid-generation. The telltale sign: clean,
+ * well-structured code at the top of a file that gradually degrades
+ * toward the bottom.
+ *
+ * Detection signals:
+ * 1. Comment density drops sharply (top half vs bottom half)
+ * 2. Function complexity increases toward end of file
+ * 3. Variable naming quality degrades (shorter names, more single-letter vars)
+ * 4. Error handling becomes sparser toward the bottom
+ * 5. Code style inconsistencies emerge (indentation, spacing)
+ *
+ * @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 FileQualityMetrics {
+    file: string;
+    totalLines: number;
+    topHalf: HalfMetrics;
+    bottomHalf: HalfMetrics;
+    degradationScore: number;  // 0-1, higher = more degradation
+    signals: string[];
+}
+
+interface HalfMetrics {
+    commentDensity: number;         // comments per code line
+    avgFunctionLength: number;      // average lines per function
+    singleCharVarCount: number;     // number of single-char variables
+    errorHandlingDensity: number;   // try/catch per function
+    emptyBlockCount: number;        // empty {} blocks
+    todoCount: number;              // TODO/FIXME/HACK comments
+    avgIdentifierLength: number;    // average variable/function name length
+}
+
+export interface ContextWindowArtifactsConfig {
+    enabled?: boolean;
+    min_file_lines?: number;           // Only analyze files with 100+ lines
+    degradation_threshold?: number;    // 0-1, flag if degradation > this, default 0.4
+    signals_required?: number;         // How many signals needed to flag, default 2
+}
+
+export class ContextWindowArtifactsGate extends Gate {
+    private config: Required<ContextWindowArtifactsConfig>;
+
+    constructor(config: ContextWindowArtifactsConfig = {}) {
+        super('context-window-artifacts', 'Context Window Artifact Detection');
+        this.config = {
+            enabled: config.enabled ?? true,
+            min_file_lines: config.min_file_lines ?? 100,
+            degradation_threshold: config.degradation_threshold ?? 0.4,
+            signals_required: config.signals_required ?? 2,
+        };
+    }
+
+    async run(context: GateContext): Promise<Failure[]> {
+        if (!this.config.enabled) return [];
+
+        const failures: Failure[] = [];
+
+        const files = await FileScanner.findFiles({
+            cwd: context.cwd,
+            patterns: ['**/*.{ts,js,tsx,jsx,py}'],
+            ignore: [...(context.ignore || []), '**/node_modules/**', '**/dist/**', '**/*.test.*', '**/*.spec.*', '**/*.min.*'],
+        });
+
+        Logger.info(`Context Window Artifacts: Scanning ${files.length} files`);
+
+        for (const file of files) {
+            try {
+                const content = await fs.readFile(path.join(context.cwd, file), 'utf-8');
+                const lines = content.split('\n');
+
+                if (lines.length < this.config.min_file_lines) continue;
+
+                const metrics = this.analyzeFile(content, file);
+                if (metrics && metrics.signals.length >= this.config.signals_required &&
+                    metrics.degradationScore >= this.config.degradation_threshold) {
+
+                    const signalList = metrics.signals.map(s => `  • ${s}`).join('\n');
+                    const midpoint = Math.floor(metrics.totalLines / 2);
+
+                    failures.push(this.createFailure(
+                        `Context window artifact detected in ${file} (${metrics.totalLines} lines, degradation: ${(metrics.degradationScore * 100).toFixed(0)}%):\n${signalList}`,
+                        [file],
+                        `This file shows quality degradation from top to bottom, a pattern typical of AI context window exhaustion. Consider refactoring the bottom half or splitting the file. The quality drop begins around line ${midpoint}.`,
+                        'Context Window Artifacts',
+                        midpoint,
+                        undefined,
+                        'high'
+                    ));
+                }
+            } catch (e) { }
+        }
+
+        return failures;
+    }
+
+    private analyzeFile(content: string, file: string): FileQualityMetrics | null {
+        const lines = content.split('\n');
+        const midpoint = Math.floor(lines.length / 2);
+
+        const topContent = lines.slice(0, midpoint).join('\n');
+        const bottomContent = lines.slice(midpoint).join('\n');
+
+        const topMetrics = this.measureHalf(topContent);
+        const bottomMetrics = this.measureHalf(bottomContent);
+
+        const signals: string[] = [];
+        let degradationScore = 0;
+
+        // Signal 1: Comment density drops
+        if (topMetrics.commentDensity > 0) {
+            const commentRatio = bottomMetrics.commentDensity / topMetrics.commentDensity;
+            if (commentRatio < 0.5) {
+                signals.push(`Comment density drops ${((1 - commentRatio) * 100).toFixed(0)}% in bottom half`);
+                degradationScore += 0.25;
+            }
+        }
+
+        // Signal 2: Function length increases
+        if (topMetrics.avgFunctionLength > 0 && bottomMetrics.avgFunctionLength > 0) {
+            const lengthRatio = bottomMetrics.avgFunctionLength / topMetrics.avgFunctionLength;
+            if (lengthRatio > 1.5) {
+                signals.push(`Average function length ${lengthRatio.toFixed(1)}x longer in bottom half`);
+                degradationScore += 0.2;
+            }
+        }
+
+        // Signal 3: Variable naming quality degrades
+        if (bottomMetrics.singleCharVarCount > topMetrics.singleCharVarCount * 2 &&
+            bottomMetrics.singleCharVarCount >= 3) {
+            signals.push(`${bottomMetrics.singleCharVarCount} single-char variables in bottom half vs ${topMetrics.singleCharVarCount} in top`);
+            degradationScore += 0.2;
+        }
+
+        // Signal 3b: Average identifier length shrinks
+        if (topMetrics.avgIdentifierLength > 0 && bottomMetrics.avgIdentifierLength > 0) {
+            const nameRatio = bottomMetrics.avgIdentifierLength / topMetrics.avgIdentifierLength;
+            if (nameRatio < 0.7) {
+                signals.push(`Identifier names ${((1 - nameRatio) * 100).toFixed(0)}% shorter in bottom half`);
+                degradationScore += 0.15;
+            }
+        }
+
+        // Signal 4: Error handling becomes sparser
+        if (topMetrics.errorHandlingDensity > 0) {
+            const errorRatio = bottomMetrics.errorHandlingDensity / topMetrics.errorHandlingDensity;
+            if (errorRatio < 0.3) {
+                signals.push(`Error handling ${((1 - errorRatio) * 100).toFixed(0)}% less frequent in bottom half`);
+                degradationScore += 0.2;
+            }
+        }
+
+        // Signal 5: Empty blocks increase
+        if (bottomMetrics.emptyBlockCount > topMetrics.emptyBlockCount + 2) {
+            signals.push(`${bottomMetrics.emptyBlockCount} empty blocks in bottom half vs ${topMetrics.emptyBlockCount} in top`);
+            degradationScore += 0.15;
+        }
+
+        // Signal 6: TODO/FIXME/HACK density increases at bottom
+        if (bottomMetrics.todoCount > topMetrics.todoCount + 1) {
+            signals.push(`${bottomMetrics.todoCount} TODO/FIXME/HACK in bottom half vs ${topMetrics.todoCount} in top`);
+            degradationScore += 0.1;
+        }
+
+        // Cap at 1.0
+        degradationScore = Math.min(1.0, degradationScore);
+
+        return {
+            file,
+            totalLines: lines.length,
+            topHalf: topMetrics,
+            bottomHalf: bottomMetrics,
+            degradationScore,
+            signals,
+        };
+    }
+
+    private measureHalf(content: string): HalfMetrics {
+        const lines = content.split('\n');
+        const codeLines = lines.filter(l => l.trim() && !l.trim().startsWith('//') && !l.trim().startsWith('#') && !l.trim().startsWith('*'));
+        const commentLines = lines.filter(l => {
+            const trimmed = l.trim();
+            return trimmed.startsWith('//') || trimmed.startsWith('#') || trimmed.startsWith('*') || trimmed.startsWith('/*');
+        });
+
+        // Comment density
+        const commentDensity = codeLines.length > 0 ? commentLines.length / codeLines.length : 0;
+
+        // Function lengths
+        const funcLengths = this.measureFunctionLengths(content);
+        const avgFunctionLength = funcLengths.length > 0
+            ? funcLengths.reduce((a, b) => a + b, 0) / funcLengths.length
+            : 0;
+
+        // Single-char variables (excluding common loop vars i, j, k in for loops)
+        const singleCharMatches = content.match(/\b(?:const|let|var)\s+([a-z])\b/g) || [];
+        const singleCharVarCount = singleCharMatches.length;
+
+        // Error handling density
+        const tryCount = (content.match(/\btry\s*\{/g) || []).length;
+        const funcCount = Math.max(1, funcLengths.length);
+        const errorHandlingDensity = tryCount / funcCount;
+
+        // Empty blocks
+        const emptyBlockCount = (content.match(/\{\s*\}/g) || []).length;
+
+        // TODO/FIXME/HACK count
+        const todoCount = (content.match(/\b(TODO|FIXME|HACK|XXX)\b/gi) || []).length;
+
+        // Average identifier length
+        const identifiers = content.match(/\b(?:const|let|var|function)\s+([a-zA-Z_$][a-zA-Z0-9_$]*)/g) || [];
+        const identNames = identifiers.map(m => {
+            const parts = m.split(/\s+/);
+            return parts[parts.length - 1];
+        });
+        const avgIdentifierLength = identNames.length > 0
+            ? identNames.reduce((sum, n) => sum + n.length, 0) / identNames.length
+            : 0;
+
+        return {
+            commentDensity,
+            avgFunctionLength,
+            singleCharVarCount,
+            errorHandlingDensity,
+            emptyBlockCount,
+            todoCount,
+            avgIdentifierLength,
+        };
+    }
+
+    private measureFunctionLengths(content: string): number[] {
+        const lines = content.split('\n');
+        const lengths: number[] = [];
+
+        const funcStarts = [
+            /^(?:export\s+)?(?:async\s+)?function\s+\w+/,
+            /^(?:export\s+)?(?:const|let|var)\s+\w+\s*=\s*(?:async\s+)?(?:\([^)]*\)|\w+)\s*=>/,
+            /^\s+(?:async\s+)?\w+\s*\([^)]*\)\s*\{/,
+        ];
+
+        for (let i = 0; i < lines.length; i++) {
+            for (const pattern of funcStarts) {
+                if (pattern.test(lines[i])) {
+                    // Count function body length
+                    let braceDepth = 0;
+                    let started = false;
+                    let bodyLines = 0;
+
+                    for (let j = i; j < lines.length; j++) {
+                        for (const ch of lines[j]) {
+                            if (ch === '{') { braceDepth++; started = true; }
+                            if (ch === '}') braceDepth--;
+                        }
+                        if (started) bodyLines++;
+                        if (started && braceDepth === 0) break;
+                    }
+
+                    if (bodyLines > 0) lengths.push(bodyLines);
+                    break;
+                }
+            }
+        }
+
+        return lengths;
+    }
+}

package/src/gates/context.ts

@@ -92,7 +92,8 @@ export class ContextGate extends Gate {
                     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.`
+                        `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.`,
+                        undefined, undefined, undefined, 'high'
                     ));
                 }
             }
@@ -194,7 +195,8 @@ export class ContextGate extends Gate {
                         `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'
+                        'Naming Convention Drift',
+                        undefined, undefined, 'high'
                     ));
                 }
             }
@@ -236,7 +238,8 @@ export class ContextGate extends Gate {
                 `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'
+                'Import Pattern Drift',
+                undefined, undefined, 'high'
             ));
         }
     }

package/src/gates/duplication-drift.ts

@@ -0,0 +1,231 @@
+/**
+ * Duplication Drift Gate
+ *
+ * Detects when AI generates near-identical functions across files because
+ * it doesn't remember what it already wrote. This is an AI-specific failure
+ * mode — humans reuse via copy-paste (same file), AI re-invents (cross-file).
+ *
+ * Detection strategy:
+ * 1. Extract all function bodies (normalized: strip whitespace, comments)
+ * 2. Compare function signatures + body hashes across files
+ * 3. Flag functions with >80% similarity in different files
+ *
+ * @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 crypto from 'crypto';
+import path from 'path';
+
+interface FunctionSignature {
+    name: string;
+    file: string;
+    line: number;
+    paramCount: number;
+    bodyHash: string;
+    bodyLength: number;
+    normalized: string;
+}
+
+export interface DuplicationDriftConfig {
+    enabled?: boolean;
+    similarity_threshold?: number; // 0-1, default 0.8
+    min_body_lines?: number;       // Ignore trivial functions, default 5
+}
+
+export class DuplicationDriftGate extends Gate {
+    private config: Required<DuplicationDriftConfig>;
+
+    constructor(config: DuplicationDriftConfig = {}) {
+        super('duplication-drift', 'AI Duplication Drift Detection');
+        this.config = {
+            enabled: config.enabled ?? true,
+            similarity_threshold: config.similarity_threshold ?? 0.8,
+            min_body_lines: config.min_body_lines ?? 5,
+        };
+    }
+
+    async run(context: GateContext): Promise<Failure[]> {
+        if (!this.config.enabled) return [];
+
+        const failures: Failure[] = [];
+        const functions: FunctionSignature[] = [];
+
+        const files = await FileScanner.findFiles({
+            cwd: context.cwd,
+            patterns: ['**/*.{ts,js,tsx,jsx,py}'],
+            ignore: [...(context.ignore || []), '**/node_modules/**', '**/dist/**', '**/*.test.*', '**/*.spec.*'],
+        });
+
+        Logger.info(`Duplication Drift: Scanning ${files.length} files`);
+
+        for (const file of files) {
+            try {
+                const { readFile } = await import('fs-extra');
+                const content = await readFile(path.join(context.cwd, file), 'utf-8');
+                const ext = path.extname(file);
+
+                if (['.ts', '.js', '.tsx', '.jsx'].includes(ext)) {
+                    this.extractJSFunctions(content, file, functions);
+                } else if (ext === '.py') {
+                    this.extractPyFunctions(content, file, functions);
+                }
+            } catch (e) { }
+        }
+
+        // Compare all function pairs across different files
+        const duplicateGroups = this.findDuplicateGroups(functions);
+
+        for (const group of duplicateGroups) {
+            const files = group.map(f => f.file);
+            const locations = group.map(f => `${f.file}:${f.line} (${f.name})`).join(', ');
+
+            failures.push(this.createFailure(
+                `AI Duplication Drift: Function '${group[0].name}' has ${group.length} near-identical copies across files`,
+                [...new Set(files)],
+                `Found duplicate implementations at: ${locations}. Extract to a shared module and import.`,
+                'Duplication Drift',
+                group[0].line,
+                undefined,
+                'high'
+            ));
+        }
+
+        return failures;
+    }
+
+    private extractJSFunctions(content: string, file: string, functions: FunctionSignature[]) {
+        const lines = content.split('\n');
+
+        // Match function declarations, arrow functions, and method definitions
+        const patterns = [
+            // function name(...) {
+            /^(?:export\s+)?(?:async\s+)?function\s+(\w+)\s*\(([^)]*)\)/,
+            // const name = (...) => {
+            /^(?:export\s+)?(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s+)?(?:\([^)]*\)|(\w+))\s*=>/,
+            // name(...) { — class method
+            /^\s+(?:async\s+)?(\w+)\s*\(([^)]*)\)\s*\{/,
+        ];
+
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            for (const pattern of patterns) {
+                const match = line.match(pattern);
+                if (match) {
+                    const name = match[1];
+                    const params = match[2] || '';
+                    const body = this.extractFunctionBody(lines, i);
+
+                    if (body.length >= this.config.min_body_lines) {
+                        const normalized = this.normalizeBody(body.join('\n'));
+                        functions.push({
+                            name,
+                            file,
+                            line: i + 1,
+                            paramCount: params ? params.split(',').length : 0,
+                            bodyHash: this.hash(normalized),
+                            bodyLength: body.length,
+                            normalized,
+                        });
+                    }
+                    break;
+                }
+            }
+        }
+    }
+
+    private extractPyFunctions(content: string, file: string, functions: FunctionSignature[]) {
+        const lines = content.split('\n');
+
+        for (let i = 0; i < lines.length; i++) {
+            const match = lines[i].match(/^(?:\s*)(?:async\s+)?def\s+(\w+)\s*\(([^)]*)\)/);
+            if (match) {
+                const name = match[1];
+                const params = match[2] || '';
+                const indent = lines[i].match(/^(\s*)/)?.[1]?.length || 0;
+
+                // Extract body by indentation
+                const body: string[] = [];
+                for (let j = i + 1; j < lines.length; j++) {
+                    const lineIndent = lines[j].match(/^(\s*)/)?.[1]?.length || 0;
+                    if (lines[j].trim() === '' || lineIndent > indent) {
+                        body.push(lines[j]);
+                    } else {
+                        break;
+                    }
+                }
+
+                if (body.length >= this.config.min_body_lines) {
+                    const normalized = this.normalizeBody(body.join('\n'));
+                    functions.push({
+                        name,
+                        file,
+                        line: i + 1,
+                        paramCount: params ? params.split(',').length : 0,
+                        bodyHash: this.hash(normalized),
+                        bodyLength: body.length,
+                        normalized,
+                    });
+                }
+            }
+        }
+    }
+
+    private extractFunctionBody(lines: string[], startIndex: number): string[] {
+        let braceDepth = 0;
+        let started = false;
+        const body: string[] = [];
+
+        for (let i = startIndex; i < lines.length; i++) {
+            const line = lines[i];
+            for (const ch of line) {
+                if (ch === '{') { braceDepth++; started = true; }
+                if (ch === '}') braceDepth--;
+            }
+            if (started) body.push(line);
+            if (started && braceDepth === 0) break;
+        }
+
+        return body;
+    }
+
+    private normalizeBody(body: string): string {
+        return body
+            .replace(/\/\/.*/g, '')           // strip single-line comments
+            .replace(/\/\*[\s\S]*?\*\//g, '') // strip multi-line comments
+            .replace(/#.*/g, '')              // strip Python comments
+            .replace(/\s+/g, ' ')            // collapse whitespace
+            .replace(/['"`]/g, '"')          // normalize quotes
+            .trim();
+    }
+
+    private hash(text: string): string {
+        return crypto.createHash('md5').update(text).digest('hex');
+    }
+
+    private findDuplicateGroups(functions: FunctionSignature[]): FunctionSignature[][] {
+        const groups = new Map<string, FunctionSignature[]>();
+
+        // Group by body hash (exact duplicates across files)
+        for (const fn of functions) {
+            const existing = groups.get(fn.bodyHash) || [];
+            existing.push(fn);
+            groups.set(fn.bodyHash, existing);
+        }
+
+        // Filter: only groups with functions from DIFFERENT files, 2+ members
+        const duplicates: FunctionSignature[][] = [];
+        for (const group of groups.values()) {
+            if (group.length < 2) continue;
+            const uniqueFiles = new Set(group.map(f => f.file));
+            if (uniqueFiles.size >= 2) {
+                duplicates.push(group);
+            }
+        }
+
+        return duplicates;
+    }
+}

package/src/gates/file.ts

@@ -32,7 +32,11 @@ export class FileGate extends Gate {
                 this.createFailure(
                     `The following files exceed the maximum limit of ${this.config.maxLines} lines:`,
                     violations,
-                    'Break these files into smaller, more modular components to improve maintainability (SOLID - Single Responsibility Principle).'
+                    'Break these files into smaller, more modular components to improve maintainability (SOLID - Single Responsibility Principle).',
+                    undefined,
+                    undefined,
+                    undefined,
+                    'low'
                 ),
             ];
         }