@rigour-labs/core 2.0.0 → 2.1.0

package/dist/types/index.d.ts

@@ -77,6 +77,38 @@ export declare const GatesSchema: z.ZodObject<{
         max_files_changed_per_cycle?: number | undefined;
         protected_paths?: string[] | undefined;
     }>>>;
+    context: z.ZodDefault<z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        sensitivity: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        mining_depth: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        ignored_patterns: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        sensitivity: number;
+        mining_depth: number;
+        ignored_patterns: string[];
+    }, {
+        enabled?: boolean | undefined;
+        sensitivity?: number | undefined;
+        mining_depth?: number | undefined;
+        ignored_patterns?: string[] | undefined;
+    }>>>;
+    environment: z.ZodDefault<z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        enforce_contracts: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        tools: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>;
+        required_env: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        enforce_contracts: boolean;
+        tools: Record<string, string>;
+        required_env: string[];
+    }, {
+        enabled?: boolean | undefined;
+        enforce_contracts?: boolean | undefined;
+        tools?: Record<string, string> | undefined;
+        required_env?: string[] | undefined;
+    }>>>;
 }, "strip", z.ZodTypeAny, {
     max_file_lines: number;
     forbid_todos: boolean;
@@ -107,6 +139,18 @@ export declare const GatesSchema: z.ZodObject<{
         max_files_changed_per_cycle: number;
         protected_paths: string[];
     };
+    context: {
+        enabled: boolean;
+        sensitivity: number;
+        mining_depth: number;
+        ignored_patterns: string[];
+    };
+    environment: {
+        enabled: boolean;
+        enforce_contracts: boolean;
+        tools: Record<string, string>;
+        required_env: string[];
+    };
 }, {
     max_file_lines?: number | undefined;
     forbid_todos?: boolean | undefined;
@@ -137,6 +181,18 @@ export declare const GatesSchema: z.ZodObject<{
         max_files_changed_per_cycle?: number | undefined;
         protected_paths?: string[] | undefined;
     } | undefined;
+    context?: {
+        enabled?: boolean | undefined;
+        sensitivity?: number | undefined;
+        mining_depth?: number | undefined;
+        ignored_patterns?: string[] | undefined;
+    } | undefined;
+    environment?: {
+        enabled?: boolean | undefined;
+        enforce_contracts?: boolean | undefined;
+        tools?: Record<string, string> | undefined;
+        required_env?: string[] | undefined;
+    } | undefined;
 }>;
 export declare const CommandsSchema: z.ZodObject<{
     format: z.ZodOptional<z.ZodString>;
@@ -252,6 +308,38 @@ export declare const ConfigSchema: z.ZodObject<{
             max_files_changed_per_cycle?: number | undefined;
             protected_paths?: string[] | undefined;
         }>>>;
+        context: z.ZodDefault<z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+            sensitivity: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+            mining_depth: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+            ignored_patterns: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+        }, "strip", z.ZodTypeAny, {
+            enabled: boolean;
+            sensitivity: number;
+            mining_depth: number;
+            ignored_patterns: string[];
+        }, {
+            enabled?: boolean | undefined;
+            sensitivity?: number | undefined;
+            mining_depth?: number | undefined;
+            ignored_patterns?: string[] | undefined;
+        }>>>;
+        environment: z.ZodDefault<z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+            enforce_contracts: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+            tools: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>;
+            required_env: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+        }, "strip", z.ZodTypeAny, {
+            enabled: boolean;
+            enforce_contracts: boolean;
+            tools: Record<string, string>;
+            required_env: string[];
+        }, {
+            enabled?: boolean | undefined;
+            enforce_contracts?: boolean | undefined;
+            tools?: Record<string, string> | undefined;
+            required_env?: string[] | undefined;
+        }>>>;
     }, "strip", z.ZodTypeAny, {
         max_file_lines: number;
         forbid_todos: boolean;
@@ -282,6 +370,18 @@ export declare const ConfigSchema: z.ZodObject<{
             max_files_changed_per_cycle: number;
             protected_paths: string[];
         };
+        context: {
+            enabled: boolean;
+            sensitivity: number;
+            mining_depth: number;
+            ignored_patterns: string[];
+        };
+        environment: {
+            enabled: boolean;
+            enforce_contracts: boolean;
+            tools: Record<string, string>;
+            required_env: string[];
+        };
     }, {
         max_file_lines?: number | undefined;
         forbid_todos?: boolean | undefined;
@@ -312,6 +412,18 @@ export declare const ConfigSchema: z.ZodObject<{
             max_files_changed_per_cycle?: number | undefined;
             protected_paths?: string[] | undefined;
         } | undefined;
+        context?: {
+            enabled?: boolean | undefined;
+            sensitivity?: number | undefined;
+            mining_depth?: number | undefined;
+            ignored_patterns?: string[] | undefined;
+        } | undefined;
+        environment?: {
+            enabled?: boolean | undefined;
+            enforce_contracts?: boolean | undefined;
+            tools?: Record<string, string> | undefined;
+            required_env?: string[] | undefined;
+        } | undefined;
     }>>>;
     output: z.ZodDefault<z.ZodOptional<z.ZodObject<{
         report_path: z.ZodDefault<z.ZodString>;
@@ -321,7 +433,9 @@ export declare const ConfigSchema: z.ZodObject<{
         report_path?: string | undefined;
     }>>>;
     planned: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+    ignore: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
 }, "strip", z.ZodTypeAny, {
+    ignore: string[];
     version: number;
     commands: {
         format?: string | undefined;
@@ -359,6 +473,18 @@ export declare const ConfigSchema: z.ZodObject<{
             max_files_changed_per_cycle: number;
             protected_paths: string[];
         };
+        context: {
+            enabled: boolean;
+            sensitivity: number;
+            mining_depth: number;
+            ignored_patterns: string[];
+        };
+        environment: {
+            enabled: boolean;
+            enforce_contracts: boolean;
+            tools: Record<string, string>;
+            required_env: string[];
+        };
     };
     output: {
         report_path: string;
@@ -367,6 +493,7 @@ export declare const ConfigSchema: z.ZodObject<{
     preset?: string | undefined;
     paradigm?: string | undefined;
 }, {
+    ignore?: string[] | undefined;
     version?: number | undefined;
     preset?: string | undefined;
     paradigm?: string | undefined;
@@ -406,6 +533,18 @@ export declare const ConfigSchema: z.ZodObject<{
             max_files_changed_per_cycle?: number | undefined;
             protected_paths?: string[] | undefined;
         } | undefined;
+        context?: {
+            enabled?: boolean | undefined;
+            sensitivity?: number | undefined;
+            mining_depth?: number | undefined;
+            ignored_patterns?: string[] | undefined;
+        } | undefined;
+        environment?: {
+            enabled?: boolean | undefined;
+            enforce_contracts?: boolean | undefined;
+            tools?: Record<string, string> | undefined;
+            required_env?: string[] | undefined;
+        } | undefined;
     } | undefined;
     output?: {
         report_path?: string | undefined;
@@ -415,6 +554,9 @@ export declare const ConfigSchema: z.ZodObject<{
 export type Gates = z.infer<typeof GatesSchema>;
 export type Commands = z.infer<typeof CommandsSchema>;
 export type Config = z.infer<typeof ConfigSchema>;
+export type RawGates = z.input<typeof GatesSchema>;
+export type RawCommands = z.input<typeof CommandsSchema>;
+export type RawConfig = z.input<typeof ConfigSchema>;
 export declare const StatusSchema: z.ZodEnum<["PASS", "FAIL", "SKIP", "ERROR"]>;
 export type Status = z.infer<typeof StatusSchema>;
 export declare const FailureSchema: z.ZodObject<{
@@ -470,6 +612,10 @@ export declare const ReportSchema: z.ZodObject<{
         score?: number | undefined;
     }>;
 }, "strip", z.ZodTypeAny, {
+    stats: {
+        duration_ms: number;
+        score?: number | undefined;
+    };
     status: "PASS" | "FAIL" | "SKIP" | "ERROR";
     summary: Record<string, "PASS" | "FAIL" | "SKIP" | "ERROR">;
     failures: {
@@ -479,11 +625,11 @@ export declare const ReportSchema: z.ZodObject<{
         files?: string[] | undefined;
         hint?: string | undefined;
     }[];
+}, {
     stats: {
         duration_ms: number;
         score?: number | undefined;
     };
-}, {
     status: "PASS" | "FAIL" | "SKIP" | "ERROR";
     summary: Record<string, "PASS" | "FAIL" | "SKIP" | "ERROR">;
     failures: {
@@ -493,9 +639,5 @@ export declare const ReportSchema: z.ZodObject<{
         files?: string[] | undefined;
         hint?: string | undefined;
     }[];
-    stats: {
-        duration_ms: number;
-        score?: number | undefined;
-    };
 }>;
 export type Report = z.infer<typeof ReportSchema>;

package/dist/types/index.js

@@ -34,6 +34,18 @@ export const GatesSchema = z.object({
         max_files_changed_per_cycle: z.number().optional().default(10),
         protected_paths: z.array(z.string()).optional().default(['.github/**', 'docs/**', 'rigour.yml']),
     }).optional().default({}),
+    context: z.object({
+        enabled: z.boolean().optional().default(true),
+        sensitivity: z.number().min(0).max(1).optional().default(0.8), // 0.8 correlation threshold
+        mining_depth: z.number().optional().default(100), // Number of files to sample
+        ignored_patterns: z.array(z.string()).optional().default([]),
+    }).optional().default({}),
+    environment: z.object({
+        enabled: z.boolean().optional().default(true),
+        enforce_contracts: z.boolean().optional().default(true), // Auto-discovery of versions from truth sources
+        tools: z.record(z.string()).optional().default({}), // Explicit overrides
+        required_env: z.array(z.string()).optional().default([]),
+    }).optional().default({}),
 });
 export const CommandsSchema = z.object({
     format: z.string().optional(),
@@ -51,6 +63,7 @@ export const ConfigSchema = z.object({
         report_path: z.string().default('rigour-report.json'),
     }).optional().default({}),
     planned: z.array(z.string()).optional().default([]),
+    ignore: z.array(z.string()).optional().default([]),
 });
 export const StatusSchema = z.enum(['PASS', 'FAIL', 'SKIP', 'ERROR']);
 export const FailureSchema = z.object({

package/dist/utils/scanner.js

@@ -12,15 +12,19 @@ export class FileScanner {
         'rigour-report.json'
     ];
     static async findFiles(options) {
-        return globby(options.patterns || this.DEFAULT_PATTERNS, {
-            cwd: options.cwd,
-            ignore: options.ignore || this.DEFAULT_IGNORE,
+        const patterns = (options.patterns || this.DEFAULT_PATTERNS).map(p => p.replace(/\\/g, '/'));
+        const ignore = (options.ignore || this.DEFAULT_IGNORE).map(p => p.replace(/\\/g, '/'));
+        const normalizedCwd = options.cwd.replace(/\\/g, '/');
+        return globby(patterns, {
+            cwd: normalizedCwd,
+            ignore: ignore,
         });
     }
     static async readFiles(cwd, files) {
         const contents = new Map();
         for (const file of files) {
-            const filePath = path.join(cwd, file);
+            const normalizedFile = file.replace(/\//g, path.sep);
+            const filePath = path.isAbsolute(normalizedFile) ? normalizedFile : path.join(cwd, normalizedFile);
             contents.set(file, await fs.readFile(filePath, 'utf-8'));
         }
         return contents;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rigour-labs/core",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -18,6 +18,7 @@
     "fs-extra": "^11.3.3",
     "globby": "^14.1.0",
     "micromatch": "^4.0.8",
+    "semver": "^7.7.3",
     "typescript": "^5.9.3",
     "web-tree-sitter": "^0.26.3",
     "yaml": "^2.3.4",
@@ -26,7 +27,8 @@
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",
     "@types/micromatch": "^4.0.10",
-    "@types/node": "^25.0.3"
+    "@types/node": "^25.0.3",
+    "@types/semver": "^7.7.1"
   },
   "scripts": {
     "build": "tsc",

package/src/context.test.ts

@@ -0,0 +1,73 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { GateRunner } from '../src/gates/runner.js';
+import fs from 'fs-extra';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TEST_CWD = path.join(__dirname, '../temp-test-context');
+
+describe('Context Awareness Engine', () => {
+    beforeAll(async () => {
+        await fs.ensureDir(TEST_CWD);
+    });
+
+    afterAll(async () => {
+        await fs.remove(TEST_CWD);
+    });
+
+    it('should detect context drift for redundant env suffixes (Golden Example)', async () => {
+        // Setup: Define standard GCP_PROJECT_ID
+        await fs.writeFile(path.join(TEST_CWD, '.env.example'), 'GCP_PROJECT_ID=my-project\n');
+
+        // Setup: Use drifted GCP_PROJECT_ID_PRODUCTION
+        await fs.writeFile(path.join(TEST_CWD, 'feature.js'), `
+            const id = process.env.GCP_PROJECT_ID_PRODUCTION;
+            console.log(id);
+        `);
+
+        const config = {
+            version: 1,
+            commands: {},
+            gates: {
+                context: {
+                    enabled: true,
+                    sensitivity: 0.8,
+                    mining_depth: 10,
+                },
+            },
+            output: { report_path: 'rigour-report.json' }
+        };
+
+        const runner = new GateRunner(config as any);
+        const report = await runner.run(TEST_CWD);
+
+        const driftFailures = report.failures.filter(f => f.id === 'context-drift');
+        expect(driftFailures.length).toBeGreaterThan(0);
+        expect(driftFailures[0].details).toContain('GCP_PROJECT_ID_PRODUCTION');
+        expect(driftFailures[0].hint).toContain('GCP_PROJECT_ID');
+    });
+
+    it('should not flag valid environment variables', async () => {
+        await fs.writeFile(path.join(TEST_CWD, 'valid.js'), `
+            const id = process.env.GCP_PROJECT_ID;
+        `);
+
+        const config = {
+            version: 1,
+            commands: {},
+            gates: {
+                context: { enabled: true },
+            },
+            output: { report_path: 'rigour-report.json' }
+        };
+
+        const runner = new GateRunner(config as any);
+        const report = await runner.run(TEST_CWD);
+
+        const driftFailures = report.failures.filter(f => f.id === 'context-drift');
+        // Filter out failures from other files if they still exist in TEST_CWD
+        const specificFailures = driftFailures.filter(f => f.files?.includes('valid.js'));
+        expect(specificFailures.length).toBe(0);
+    });
+});

package/src/environment.test.ts

@@ -0,0 +1,115 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { GateRunner } from './gates/runner.js';
+import { Config, RawConfig, ConfigSchema } from './types/index.js';
+import fs from 'fs-extra';
+import path from 'path';
+
+describe('Environment Alignment Gate', () => {
+    const testDir = path.join(process.cwd(), 'temp-test-env');
+
+    beforeEach(async () => {
+        await fs.ensureDir(testDir);
+    });
+
+    afterEach(async () => {
+        await fs.remove(testDir);
+    });
+
+    it('should detect tool version mismatch (Explicit)', async () => {
+        const rawConfig: RawConfig = {
+            version: 1,
+            gates: {
+                environment: {
+                    enabled: true,
+                    enforce_contracts: false,
+                    tools: {
+                        node: ">=99.0.0" // Guaranteed to fail
+                    }
+                }
+            }
+        };
+
+        const config = ConfigSchema.parse(rawConfig);
+        const runner = new GateRunner(config);
+        const report = await runner.run(testDir);
+
+        expect(report.status).toBe('FAIL');
+        const envFailure = report.failures.find(f => f.id === 'environment-alignment');
+        expect(envFailure).toBeDefined();
+        expect(envFailure?.details).toContain('node');
+        expect(envFailure?.details).toContain('version mismatch');
+    });
+
+    it('should detect missing environment variables', async () => {
+        const rawConfig: RawConfig = {
+            version: 1,
+            gates: {
+                environment: {
+                    enabled: true,
+                    required_env: ["RIGOUR_TEST_VAR_MISSING"]
+                }
+            }
+        };
+
+        const config = ConfigSchema.parse(rawConfig);
+        const runner = new GateRunner(config);
+        const report = await runner.run(testDir);
+
+        expect(report.status).toBe('FAIL');
+        expect(report.failures[0].details).toContain('RIGOUR_TEST_VAR_MISSING');
+    });
+
+    it('should discover contracts from pyproject.toml', async () => {
+        // Create mock pyproject.toml with a version that will surely fail
+        await fs.writeFile(path.join(testDir, 'pyproject.toml'), `
+[tool.ruff]
+ruff = ">=99.14.0"
+`);
+
+        const rawConfig: RawConfig = {
+            version: 1,
+            gates: {
+                environment: {
+                    enabled: true,
+                    enforce_contracts: true,
+                    tools: {} // Should discover ruff from file
+                }
+            }
+        };
+
+        const config = ConfigSchema.parse(rawConfig);
+        const runner = new GateRunner(config);
+        const report = await runner.run(testDir);
+
+        // This might pass or fail depending on the local ruff version, 
+        // but we want to check if the gate attempted to check ruff.
+        // If ruff is missing, it will fail with "is missing".
+        const ruffFailure = report.failures.find(f => f.details.includes('ruff'));
+        expect(ruffFailure).toBeDefined();
+    });
+
+    it('should prioritize environment gate and run it first', async () => {
+        const rawConfig: RawConfig = {
+            version: 1,
+            gates: {
+                max_file_lines: 1,
+                environment: {
+                    enabled: true,
+                    required_env: ["MANDATORY_SECRET_MISSING"]
+                }
+            }
+        };
+
+        const config = ConfigSchema.parse(rawConfig);
+
+        // Create a file that would fail max_file_lines
+        await fs.writeFile(path.join(testDir, 'large.js'), 'line1\nline2\nline3');
+
+        const runner = new GateRunner(config);
+        const report = await runner.run(testDir);
+
+        // In a real priority system, we might want to stop after environment failure.
+        // Currently GateRunner runs all, but environment-alignment has been unshifted.
+        expect(Object.keys(report.summary)[0]).toBe('environment-alignment');
+    });
+});

package/src/gates/ast.ts

@@ -21,10 +21,14 @@ export class ASTGate extends Gate {
     async run(context: GateContext): Promise<Failure[]> {
         const failures: Failure[] = [];
 
+        const patterns = (context.patterns || ['**/*.{ts,js,tsx,jsx,py,go,rs,cs,java,rb,c,cpp,php,swift,kt}']).map(p => p.replace(/\\/g, '/'));
+        const ignore = (context.ignore || ['node_modules/**', 'dist/**', 'build/**', '**/*.test.*', '**/*.spec.*', '**/__pycache__/**']).map(p => p.replace(/\\/g, '/'));
+        const normalizedCwd = context.cwd.replace(/\\/g, '/');
+
         // Find all supported files
-        const files = await globby(['**/*.{ts,js,tsx,jsx,py,go,rs,cs,java,rb,c,cpp,php,swift,kt}'], {
-            cwd: context.cwd,
-            ignore: ['node_modules/**', 'dist/**', 'build/**', '**/*.test.*', '**/*.spec.*', '**/__pycache__/**'],
+        const files = await globby(patterns, {
+            cwd: normalizedCwd,
+            ignore: ignore,
         });
 
         for (const file of files) {

package/src/gates/base.ts

@@ -1,7 +1,11 @@
+import { GoldenRecord } from '../services/context-engine.js';
 import { Failure } from '../types/index.js';
 
 export interface GateContext {
     cwd: string;
+    record?: GoldenRecord;
+    ignore?: string[];
+    patterns?: string[];
 }
 
 export abstract class Gate {

package/src/gates/content.ts

@@ -19,7 +19,11 @@ export class ContentGate extends Gate {
 
         if (patterns.length === 0) return [];
 
-        const files = await FileScanner.findFiles({ cwd: context.cwd });
+        const files = await FileScanner.findFiles({
+            cwd: context.cwd,
+            ignore: context.ignore,
+            patterns: context.patterns
+        });
         const contents = await FileScanner.readFiles(context.cwd, files);
 
         const violations: string[] = [];

package/src/gates/context.ts

@@ -0,0 +1,55 @@
+import { Gate, GateContext } from './base.js';
+import { Failure, Gates } from '../types/index.js';
+import { FileScanner } from '../utils/scanner.js';
+import fs from 'fs-extra';
+import path from 'path';
+
+export class ContextGate extends Gate {
+    constructor(private config: Gates) {
+        super('context-drift', 'Context Awareness & Drift Detection');
+    }
+
+    async run(context: GateContext): Promise<Failure[]> {
+        const failures: Failure[] = [];
+        const record = context.record;
+        if (!record || !this.config.context?.enabled) return [];
+
+        const files = await FileScanner.findFiles({ cwd: context.cwd });
+        const envAnchors = record.anchors.filter(a => a.type === 'env' && a.confidence >= 1);
+
+        for (const file of files) {
+            try {
+                const content = await fs.readFile(path.join(context.cwd, file), 'utf-8');
+
+                // 1. Detect Redundant Suffixes (The Golden Example)
+                this.checkEnvDrift(content, file, envAnchors, failures);
+
+            } catch (e) { }
+        }
+
+        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.`
+                    ));
+                }
+            }
+        }
+    }
+}