@rigour-labs/core 4.3.6 → 5.0.0

package/dist/gates/style-drift.js

@@ -0,0 +1,305 @@
+/**
+ * Style Drift Detection Gate
+ *
+ * Detects when AI-generated code gradually drifts away from the project's
+ * established coding conventions. AI models tend to use their own "default"
+ * style which may differ from the project norm.
+ *
+ * What it checks:
+ * 1. Naming conventions — camelCase vs snake_case vs PascalCase consistency
+ * 2. Error handling patterns — try-catch vs .catch() vs Result type consistency
+ * 3. Import style — named vs default vs wildcard import consistency
+ * 4. Quote style — single vs double quote consistency
+ *
+ * How it works:
+ * 1. First scan: sample source files → compute a style fingerprint → store baseline
+ * 2. Subsequent scans: compare new/changed files against baseline
+ * 3. If a file deviates >25% on any dimension → flag as style drift
+ *
+ * The baseline is stored in .rigour/style-baseline.json and evolves with
+ * human-approved changes (not AI drift).
+ *
+ * @since v5.0.0
+ */
+import { Gate } from './base.js';
+import { FileScanner } from '../utils/scanner.js';
+import { Logger } from '../utils/logger.js';
+import fs from 'fs-extra';
+import path from 'path';
+export class StyleDriftGate extends Gate {
+    config;
+    constructor(config = {}) {
+        super('style-drift', 'Style Drift Detection');
+        this.config = {
+            enabled: config.enabled ?? true,
+            deviation_threshold: config.deviation_threshold ?? 0.25,
+            sample_size: config.sample_size ?? 100,
+            baseline_path: config.baseline_path ?? '.rigour/style-baseline.json',
+        };
+    }
+    get provenance() { return 'ai-drift'; }
+    async run(context) {
+        if (!this.config.enabled)
+            return [];
+        const failures = [];
+        const baselinePath = path.join(context.cwd, this.config.baseline_path);
+        // Find source files
+        const files = await FileScanner.findFiles({
+            cwd: context.cwd,
+            patterns: context.patterns || ['**/*.{ts,tsx,js,jsx,py}'],
+            ignore: [...(context.ignore || []), '**/node_modules/**', '**/dist/**', '**/*.test.*', '**/*.spec.*', '**/*.d.ts'],
+        });
+        if (files.length === 0)
+            return [];
+        // Load or create baseline
+        let baseline = null;
+        if (await fs.pathExists(baselinePath)) {
+            try {
+                baseline = await fs.readJson(baselinePath);
+            }
+            catch {
+                Logger.debug('Failed to load style baseline, will create new one');
+            }
+        }
+        if (!baseline) {
+            // First scan: create baseline from sampled files
+            const sampled = files.slice(0, this.config.sample_size);
+            baseline = await this.computeFingerprint(context, sampled);
+            baseline.createdAt = new Date().toISOString();
+            // Ensure directory exists and save baseline
+            await fs.ensureDir(path.dirname(baselinePath));
+            await fs.writeJson(baselinePath, baseline, { spaces: 2 });
+            Logger.info(`Style Drift: Created baseline from ${sampled.length} files → ${baselinePath}`);
+            return []; // No failures on first scan
+        }
+        // Subsequent scan: compare each file against baseline
+        const contents = await FileScanner.readFiles(context.cwd, files, context.fileCache);
+        for (const [file, content] of contents) {
+            const ext = path.extname(file);
+            if (!['.ts', '.tsx', '.js', '.jsx', '.py'].includes(ext))
+                continue;
+            const fileFingerprint = this.analyzeFile(content, ext);
+            const deviations = this.compareToBaseline(fileFingerprint, baseline);
+            for (const deviation of deviations) {
+                if (deviation.score > this.config.deviation_threshold) {
+                    failures.push(this.createFailure(`Style drift in ${file}: ${deviation.dimension} deviates ${(deviation.score * 100).toFixed(0)}% from project baseline (${deviation.detail}).`, [file], `This file's ${deviation.dimension} doesn't match the project's established convention. ${deviation.suggestion}`, 'Style Drift', undefined, undefined, 'low'));
+                }
+            }
+        }
+        if (failures.length > 0) {
+            Logger.info(`Style Drift: Found ${failures.length} convention deviations`);
+        }
+        return failures;
+    }
+    // ─── Fingerprint Computation ─────────────────────────────────────
+    async computeFingerprint(context, files) {
+        const fingerprint = {
+            naming: {
+                functions: { camelCase: 0, snake_case: 0, PascalCase: 0, SCREAMING_SNAKE: 0 },
+                variables: { camelCase: 0, snake_case: 0, PascalCase: 0, SCREAMING_SNAKE: 0 },
+            },
+            errorHandling: { tryCatch: 0, promiseCatch: 0, resultType: 0 },
+            importStyle: { named: 0, default: 0, wildcard: 0, sideEffect: 0 },
+            quoteStyle: { single: 0, double: 0, backtick: 0 },
+            totalFilesAnalyzed: 0,
+            createdAt: '',
+        };
+        const contents = await FileScanner.readFiles(context.cwd, files, context.fileCache);
+        for (const [file, content] of contents) {
+            const ext = path.extname(file);
+            const fileAnalysis = this.analyzeFile(content, ext);
+            this.mergeIntoFingerprint(fingerprint, fileAnalysis);
+            fingerprint.totalFilesAnalyzed++;
+        }
+        return fingerprint;
+    }
+    analyzeFile(content, ext) {
+        const fp = {
+            naming: {
+                functions: { camelCase: 0, snake_case: 0, PascalCase: 0, SCREAMING_SNAKE: 0 },
+                variables: { camelCase: 0, snake_case: 0, PascalCase: 0, SCREAMING_SNAKE: 0 },
+            },
+            errorHandling: { tryCatch: 0, promiseCatch: 0, resultType: 0 },
+            importStyle: { named: 0, default: 0, wildcard: 0, sideEffect: 0 },
+            quoteStyle: { single: 0, double: 0, backtick: 0 },
+            totalFilesAnalyzed: 1,
+            createdAt: '',
+        };
+        const lines = content.split('\n');
+        for (const line of lines) {
+            // ── Naming conventions ──
+            // Function declarations
+            const fnMatch = line.match(/(?:function|async\s+function)\s+(\w+)/);
+            if (fnMatch)
+                this.classifyCasing(fnMatch[1], fp.naming.functions);
+            // Method definitions
+            const methodMatch = line.match(/^\s+(?:async\s+)?(\w+)\s*\([^)]*\)\s*[{:]/);
+            if (methodMatch && !['if', 'for', 'while', 'switch', 'catch', 'constructor'].includes(methodMatch[1])) {
+                this.classifyCasing(methodMatch[1], fp.naming.functions);
+            }
+            // Arrow function assignments
+            const arrowMatch = line.match(/(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s+)?(?:\([^)]*\)|(\w+))\s*=>/);
+            if (arrowMatch)
+                this.classifyCasing(arrowMatch[1], fp.naming.functions);
+            // Variable declarations (non-function)
+            const varMatch = line.match(/(?:const|let|var)\s+(\w+)\s*=/);
+            if (varMatch && !arrowMatch)
+                this.classifyCasing(varMatch[1], fp.naming.variables);
+            // Python function/variable
+            if (ext === '.py') {
+                const pyFn = line.match(/def\s+(\w+)/);
+                if (pyFn)
+                    this.classifyCasing(pyFn[1], fp.naming.functions);
+                const pyVar = line.match(/^(\w+)\s*=/);
+                if (pyVar && !pyFn)
+                    this.classifyCasing(pyVar[1], fp.naming.variables);
+            }
+            // ── Error handling ──
+            if (/\btry\s*\{/.test(line) || /\btry\s*:/.test(line))
+                fp.errorHandling.tryCatch++;
+            if (/\.catch\s*\(/.test(line))
+                fp.errorHandling.promiseCatch++;
+            if (/Result<|Result\[|Err\(|Ok\(|Either</.test(line))
+                fp.errorHandling.resultType++;
+            // ── Import style ──
+            if (/^import\s+\{/.test(line.trim()))
+                fp.importStyle.named++;
+            else if (/^import\s+\*\s+as/.test(line.trim()))
+                fp.importStyle.wildcard++;
+            else if (/^import\s+['"]/.test(line.trim()))
+                fp.importStyle.sideEffect++;
+            else if (/^import\s+\w/.test(line.trim()))
+                fp.importStyle.default++;
+            // ── Quote style ──
+            // Count quotes in non-import lines (imports are already counted above)
+            if (!line.trim().startsWith('import')) {
+                const singles = (line.match(/'/g) || []).length;
+                const doubles = (line.match(/"/g) || []).length;
+                const backticks = (line.match(/`/g) || []).length;
+                fp.quoteStyle.single += singles;
+                fp.quoteStyle.double += doubles;
+                fp.quoteStyle.backtick += backticks;
+            }
+        }
+        return fp;
+    }
+    classifyCasing(name, dist) {
+        if (name.startsWith('_') || name.length <= 1)
+            return; // Skip private/single char
+        if (/^[A-Z][A-Z0-9_]+$/.test(name)) {
+            dist.SCREAMING_SNAKE++;
+        }
+        else if (/^[A-Z]/.test(name)) {
+            dist.PascalCase++;
+        }
+        else if (name.includes('_')) {
+            dist.snake_case++;
+        }
+        else {
+            dist.camelCase++;
+        }
+    }
+    mergeIntoFingerprint(target, source) {
+        // Naming
+        for (const key of Object.keys(target.naming.functions)) {
+            target.naming.functions[key] += source.naming.functions[key];
+            target.naming.variables[key] += source.naming.variables[key];
+        }
+        // Error handling
+        target.errorHandling.tryCatch += source.errorHandling.tryCatch;
+        target.errorHandling.promiseCatch += source.errorHandling.promiseCatch;
+        target.errorHandling.resultType += source.errorHandling.resultType;
+        // Import style
+        target.importStyle.named += source.importStyle.named;
+        target.importStyle.default += source.importStyle.default;
+        target.importStyle.wildcard += source.importStyle.wildcard;
+        target.importStyle.sideEffect += source.importStyle.sideEffect;
+        // Quote style
+        target.quoteStyle.single += source.quoteStyle.single;
+        target.quoteStyle.double += source.quoteStyle.double;
+        target.quoteStyle.backtick += source.quoteStyle.backtick;
+    }
+    // ─── Baseline Comparison ─────────────────────────────────────────
+    compareToBaseline(file, baseline) {
+        const deviations = [];
+        // Compare function naming
+        const fnDev = this.distributionDeviation(this.toRecord(file.naming.functions), this.toRecord(baseline.naming.functions));
+        if (fnDev.score > 0) {
+            deviations.push({
+                dimension: 'function naming',
+                score: fnDev.score,
+                detail: `file uses ${fnDev.filePredominant}, project uses ${fnDev.baselinePredominant}`,
+                suggestion: `Use ${fnDev.baselinePredominant} for function names to match project conventions.`,
+            });
+        }
+        // Compare variable naming
+        const varDev = this.distributionDeviation(this.toRecord(file.naming.variables), this.toRecord(baseline.naming.variables));
+        if (varDev.score > 0) {
+            deviations.push({
+                dimension: 'variable naming',
+                score: varDev.score,
+                detail: `file uses ${varDev.filePredominant}, project uses ${varDev.baselinePredominant}`,
+                suggestion: `Use ${varDev.baselinePredominant} for variable names to match project conventions.`,
+            });
+        }
+        // Compare error handling
+        const errDev = this.distributionDeviation(file.errorHandling, baseline.errorHandling);
+        if (errDev.score > 0 && this.hasSignificantData(file.errorHandling)) {
+            deviations.push({
+                dimension: 'error handling',
+                score: errDev.score,
+                detail: `file uses ${errDev.filePredominant}, project uses ${errDev.baselinePredominant}`,
+                suggestion: `Use ${errDev.baselinePredominant} error handling pattern to match project conventions.`,
+            });
+        }
+        // Compare import style
+        const impDev = this.distributionDeviation(file.importStyle, baseline.importStyle);
+        if (impDev.score > 0 && this.hasSignificantData(file.importStyle)) {
+            deviations.push({
+                dimension: 'import style',
+                score: impDev.score,
+                detail: `file uses ${impDev.filePredominant}, project uses ${impDev.baselinePredominant}`,
+                suggestion: `Use ${impDev.baselinePredominant} imports to match project conventions.`,
+            });
+        }
+        return deviations;
+    }
+    /**
+     * Compare two distributions and return a deviation score (0-1).
+     * 0 = perfect match, 1 = completely different predominant style.
+     *
+     * Method: find the predominant category in each distribution.
+     * If they differ, score = how far the file is from the baseline's predominant category.
+     */
+    distributionDeviation(file, baseline) {
+        const fileTotal = Object.values(file).reduce((a, b) => a + b, 0);
+        const baselineTotal = Object.values(baseline).reduce((a, b) => a + b, 0);
+        if (fileTotal < 3 || baselineTotal < 5) {
+            return { score: 0, filePredominant: 'N/A', baselinePredominant: 'N/A' };
+        }
+        // Find predominant category
+        const filePredominant = Object.entries(file).sort((a, b) => b[1] - a[1])[0][0];
+        const baselinePredominant = Object.entries(baseline).sort((a, b) => b[1] - a[1])[0][0];
+        if (filePredominant === baselinePredominant) {
+            return { score: 0, filePredominant, baselinePredominant };
+        }
+        // Calculate how much the file uses the baseline's predominant style
+        const fileUseOfBaseline = (file[baselinePredominant] || 0) / fileTotal;
+        const baselineUseOfBaseline = (baseline[baselinePredominant] || 0) / baselineTotal;
+        // Score = how far the file deviates from baseline's predominant ratio
+        const deviation = Math.max(0, baselineUseOfBaseline - fileUseOfBaseline);
+        return { score: deviation, filePredominant, baselinePredominant };
+    }
+    hasSignificantData(obj) {
+        return Object.values(obj).reduce((a, b) => a + b, 0) >= 3;
+    }
+    /** Convert a typed distribution to a generic Record for comparison */
+    toRecord(dist) {
+        return {
+            camelCase: dist.camelCase,
+            snake_case: dist.snake_case,
+            PascalCase: dist.PascalCase,
+            SCREAMING_SNAKE: dist.SCREAMING_SNAKE,
+        };
+    }
+}

package/dist/index.d.ts

@@ -23,3 +23,7 @@ export { openDatabase, isSQLiteAvailable, compactDatabase, getDatabaseSize, rese
 export type { RigourDB, CompactResult } from './storage/index.js';
 export { checkLocalPatterns, persistAndReinforce, getProjectStats } from './storage/index.js';
 export type { ProjectStats } from './storage/index.js';
+export { generateTemporalDriftReport, formatDriftSummary } from './services/temporal-drift.js';
+export type { TemporalDriftReport, ProvenanceStream, MonthlyBucket, WeeklyBucket, DriftDirection } from './services/temporal-drift.js';
+export { getProvenanceTrends, getQualityTrend } from './services/adaptive-thresholds.js';
+export type { ProvenanceTrends, ProvenanceRunData } from './services/adaptive-thresholds.js';

package/dist/index.js

@@ -23,6 +23,10 @@ export { extractFacts, factsToPromptString } from './deep/fact-extractor.js';
 export { openDatabase, isSQLiteAvailable, compactDatabase, getDatabaseSize, resetDatabase, insertScan, insertFindings, getRecentScans, getScoreTrendFromDB, getTopIssues, reinforcePattern, getStrongPatterns } from './storage/index.js';
 // Local Project Memory (hybrid intelligence — SQLite-backed per-project learning)
 export { checkLocalPatterns, persistAndReinforce, getProjectStats } from './storage/index.js';
+// Temporal Drift Engine (v5 — cross-session trend analysis + per-provenance EWMA)
+export { generateTemporalDriftReport, formatDriftSummary } from './services/temporal-drift.js';
+// Adaptive Thresholds (v5 — Z-score + per-provenance trends)
+export { getProvenanceTrends, getQualityTrend } from './services/adaptive-thresholds.js';
 // Pattern Index is intentionally NOT exported here to prevent
 // native dependency issues (sharp/transformers) from leaking into
 // non-AI parts of the system.

package/dist/services/adaptive-thresholds.d.ts

@@ -1,16 +1,19 @@
 /**
- * Adaptive Thresholds Service
+ * Adaptive Thresholds Service (v2)
  *
  * Dynamically adjusts quality gate thresholds based on:
  * - Project maturity (age, commit count, file count)
- * - Historical failure rates
+ * - Historical failure rates with Z-score anomaly detection
  * - Complexity tier (hobby/startup/enterprise)
- * - Recent trends (improving/degrading)
+ * - Per-provenance trend analysis (ai-drift, structural, security separate)
  *
- * This enables Rigour to be "strict but fair" - new projects get
- * more lenient thresholds while mature codebases are held to higher standards.
+ * v2 upgrades:
+ * - Z-score replaces naive delta comparison for trend detection
+ * - Per-provenance failure tracking (AI drift vs structural vs security)
+ * - Statistical anomaly detection normalizes across project sizes
  *
- * @since v2.14.0
+ * @since v2.14.0 (original)
+ * @since v5.0.0 (Z-score + provenance-aware trends)
  */
 export type ComplexityTier = 'hobby' | 'startup' | 'enterprise';
 export type QualityTrend = 'improving' | 'stable' | 'degrading';
@@ -36,21 +39,62 @@ export interface ThresholdAdjustments {
     securityBlockLevel: 'critical' | 'high' | 'medium' | 'low';
     leniencyFactor: number;
     reasoning: string[];
+    /** Per-provenance trend breakdown (new in v5) */
+    provenanceTrends?: ProvenanceTrends;
+}
+export interface ProvenanceRunData {
+    aiDriftFailures: number;
+    structuralFailures: number;
+    securityFailures: number;
+}
+export interface ProvenanceTrends {
+    aiDrift: QualityTrend;
+    structural: QualityTrend;
+    security: QualityTrend;
+    aiDriftZScore: number;
+    structuralZScore: number;
+    securityZScore: number;
 }
 /**
- * Record a gate run for historical tracking
+ * Record a gate run for historical tracking.
+ * v5: accepts optional per-provenance breakdown.
  */
-export declare function recordGateRun(cwd: string, passedGates: number, failedGates: number, totalFailures: number): void;
+export declare function recordGateRun(cwd: string, passedGates: number, failedGates: number, totalFailures: number, provenance?: ProvenanceRunData): void;
 /**
- * Get quality trend from historical data
+ * Get quality trend using Z-score analysis (v5).
+ *
+ * How it works:
+ * 1. Take the last N runs (baseline window, default 20)
+ * 2. Compute mean and std of failure counts
+ * 3. Take the most recent window (last 5 runs)
+ * 4. Compute the average failure count in the recent window
+ * 5. Z-score = (recent_avg - baseline_mean) / baseline_std
+ *
+ * Z > 2.0 → statistically abnormal spike → DEGRADING
+ * Z < -2.0 → statistically abnormal drop → IMPROVING
+ *
+ * Why better than delta: A project with 100 failures/run and a spike to 108
+ * is stable (Z ≈ 0.5). A project with 2 failures/run and a spike to 8
+ * is degrading (Z ≈ 3.0). Z-score normalizes for project size.
  */
 export declare function getQualityTrend(cwd: string): QualityTrend;
+/**
+ * Get per-provenance trend analysis (v5).
+ *
+ * Runs separate Z-score analysis for each provenance category.
+ * This is the core differentiator: Rigour can tell you
+ * "your AI is getting worse" separately from "your code quality is dropping."
+ *
+ * Falls back gracefully for legacy history data without provenance.
+ */
+export declare function getProvenanceTrends(cwd: string): ProvenanceTrends;
 /**
  * Detect project complexity tier based on metrics
  */
 export declare function detectComplexityTier(metrics: ProjectMetrics): ComplexityTier;
 /**
- * Calculate adaptive thresholds based on project state
+ * Calculate adaptive thresholds based on project state.
+ * v5: Uses Z-score trending and per-provenance analysis.
  */
 export declare function calculateAdaptiveThresholds(cwd: string, metrics: ProjectMetrics, config?: AdaptiveConfig): ThresholdAdjustments;
 /**