@rigour-labs/core 1.0.0

package/dist/types/index.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReportSchema = exports.FailureSchema = exports.StatusSchema = exports.ConfigSchema = exports.CommandsSchema = exports.GatesSchema = void 0;
+const zod_1 = require("zod");
+exports.GatesSchema = zod_1.z.object({
+    max_file_lines: zod_1.z.number().optional().default(500),
+    forbid_todos: zod_1.z.boolean().optional().default(true),
+    forbid_fixme: zod_1.z.boolean().optional().default(true),
+    forbid_paths: zod_1.z.array(zod_1.z.string()).optional().default([]),
+    required_files: zod_1.z.array(zod_1.z.string()).optional().default([
+        'docs/SPEC.md',
+        'docs/ARCH.md',
+        'docs/DECISIONS.md',
+        'docs/TASKS.md',
+    ]),
+});
+exports.CommandsSchema = zod_1.z.object({
+    format: zod_1.z.string().optional(),
+    lint: zod_1.z.string().optional(),
+    typecheck: zod_1.z.string().optional(),
+    test: zod_1.z.string().optional(),
+});
+exports.ConfigSchema = zod_1.z.object({
+    version: zod_1.z.number().default(1),
+    commands: exports.CommandsSchema.optional().default({}),
+    gates: exports.GatesSchema.optional().default({}),
+    output: zod_1.z.object({
+        report_path: zod_1.z.string().default('rigour-report.json'),
+    }).optional().default({}),
+});
+exports.StatusSchema = zod_1.z.enum(['PASS', 'FAIL', 'SKIP', 'ERROR']);
+exports.FailureSchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    title: zod_1.z.string(),
+    details: zod_1.z.string(),
+    files: zod_1.z.array(zod_1.z.string()).optional(),
+    hint: zod_1.z.string().optional(),
+});
+exports.ReportSchema = zod_1.z.object({
+    status: exports.StatusSchema,
+    summary: zod_1.z.record(exports.StatusSchema),
+    failures: zod_1.z.array(exports.FailureSchema),
+    stats: zod_1.z.object({
+        duration_ms: zod_1.z.number(),
+    }),
+});

package/dist/utils/logger.d.ts

@@ -0,0 +1,14 @@
+export declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3
+}
+export declare class Logger {
+    private static level;
+    static setLevel(level: LogLevel): void;
+    static info(message: string): void;
+    static warn(message: string): void;
+    static error(message: string, error?: any): void;
+    static debug(message: string): void;
+}

package/dist/utils/logger.js

@@ -0,0 +1,44 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Logger = exports.LogLevel = void 0;
+const chalk_1 = __importDefault(require("chalk"));
+var LogLevel;
+(function (LogLevel) {
+    LogLevel[LogLevel["DEBUG"] = 0] = "DEBUG";
+    LogLevel[LogLevel["INFO"] = 1] = "INFO";
+    LogLevel[LogLevel["WARN"] = 2] = "WARN";
+    LogLevel[LogLevel["ERROR"] = 3] = "ERROR";
+})(LogLevel || (exports.LogLevel = LogLevel = {}));
+class Logger {
+    static level = LogLevel.INFO;
+    static setLevel(level) {
+        this.level = level;
+    }
+    static info(message) {
+        if (this.level <= LogLevel.INFO) {
+            console.log(chalk_1.default.blue('info: ') + message);
+        }
+    }
+    static warn(message) {
+        if (this.level <= LogLevel.WARN) {
+            console.log(chalk_1.default.yellow('warn: ') + message);
+        }
+    }
+    static error(message, error) {
+        if (this.level <= LogLevel.ERROR) {
+            console.error(chalk_1.default.red('error: ') + message);
+            if (error) {
+                console.error(error);
+            }
+        }
+    }
+    static debug(message) {
+        if (this.level <= LogLevel.DEBUG) {
+            console.log(chalk_1.default.dim('debug: ') + message);
+        }
+    }
+}
+exports.Logger = Logger;

package/dist/utils/scanner.d.ts

@@ -0,0 +1,11 @@
+export interface ScannerOptions {
+    cwd: string;
+    patterns?: string[];
+    ignore?: string[];
+}
+export declare class FileScanner {
+    private static DEFAULT_PATTERNS;
+    private static DEFAULT_IGNORE;
+    static findFiles(options: ScannerOptions): Promise<string[]>;
+    static readFiles(cwd: string, files: string[]): Promise<Map<string, string>>;
+}

package/dist/utils/scanner.js

@@ -0,0 +1,35 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileScanner = void 0;
+const globby_1 = require("globby");
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+class FileScanner {
+    static DEFAULT_PATTERNS = ['**/*.{ts,js,py,css,html,md}'];
+    static DEFAULT_IGNORE = [
+        '**/node_modules/**',
+        '**/dist/**',
+        '**/package-lock.json',
+        '**/pnpm-lock.yaml',
+        '**/.git/**',
+        'rigour-report.json'
+    ];
+    static async findFiles(options) {
+        return (0, globby_1.globby)(options.patterns || this.DEFAULT_PATTERNS, {
+            cwd: options.cwd,
+            ignore: options.ignore || this.DEFAULT_IGNORE,
+        });
+    }
+    static async readFiles(cwd, files) {
+        const contents = new Map();
+        for (const file of files) {
+            const filePath = path_1.default.join(cwd, file);
+            contents.set(file, await fs_extra_1.default.readFile(filePath, 'utf-8'));
+        }
+        return contents;
+    }
+}
+exports.FileScanner = FileScanner;

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@rigour-labs/core",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/erashu212/rigour"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "execa": "^8.0.1",
+    "fs-extra": "^11.3.3",
+    "globby": "^14.1.0",
+    "yaml": "^2.3.4",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^25.0.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run"
+  }
+}

package/src/discovery.ts

@@ -0,0 +1,30 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { Config } from './types/index.js';
+import { TEMPLATES, UNIVERSAL_CONFIG } from './templates/index.js';
+
+export class DiscoveryService {
+    async discover(cwd: string): Promise<Config> {
+        const config = { ...UNIVERSAL_CONFIG };
+
+        for (const template of TEMPLATES) {
+            const match = await this.hasAnyMarker(cwd, template.markers);
+            if (match) {
+                // Merge template config
+                config.commands = { ...config.commands, ...template.config.commands };
+                config.gates = { ...config.gates, ...template.config.gates };
+            }
+        }
+
+        return config;
+    }
+
+    private async hasAnyMarker(cwd: string, markers: string[]): Promise<boolean> {
+        for (const marker of markers) {
+            if (await fs.pathExists(path.join(cwd, marker))) {
+                return true;
+            }
+        }
+        return false;
+    }
+}

package/src/gates/base.ts

@@ -0,0 +1,21 @@
+import { Failure } from '../types/index.js';
+
+export interface GateContext {
+    cwd: string;
+}
+
+export abstract class Gate {
+    constructor(public readonly id: string, public readonly title: string) { }
+
+    abstract run(context: GateContext): Promise<Failure[]>;
+
+    protected createFailure(details: string, files?: string[], hint?: string): Failure {
+        return {
+            id: this.id,
+            title: this.title,
+            details,
+            files,
+            hint,
+        };
+    }
+}

package/src/gates/content.ts

@@ -0,0 +1,47 @@
+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 = [];
+        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 });
+        const contents = await FileScanner.readFiles(context.cwd, files);
+
+        const violations: string[] = [];
+        for (const [file, content] of contents) {
+            for (const pattern of patterns) {
+                if (pattern.test(content)) {
+                    violations.push(file);
+                    break;
+                }
+            }
+        }
+
+        if (violations.length > 0) {
+            return [
+                this.createFailure(
+                    'Forbidden placeholders found in the following files:',
+                    violations,
+                    'Remove all TODO and FIXME comments. Use the "Done is Done" mentality—address the root cause or create a tracked issue.'
+                ),
+            ];
+        }
+
+        return [];
+    }
+}

package/src/gates/file.ts

@@ -0,0 +1,38 @@
+import { Gate, GateContext } from './base.js';
+import { Failure } from '../types/index.js';
+import { FileScanner } from '../utils/scanner.js';
+
+export interface FileGateConfig {
+    maxLines: number;
+}
+
+export class FileGate extends Gate {
+    constructor(private config: FileGateConfig) {
+        super('file-size', 'File Size Limit');
+    }
+
+    async run(context: GateContext): Promise<Failure[]> {
+        const files = await FileScanner.findFiles({ cwd: context.cwd });
+        const contents = await FileScanner.readFiles(context.cwd, files);
+
+        const violations: string[] = [];
+        for (const [file, content] of contents) {
+            const lines = content.split('\n').length;
+            if (lines > this.config.maxLines) {
+                violations.push(`${file} (${lines} lines)`);
+            }
+        }
+
+        if (violations.length > 0) {
+            return [
+                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).'
+                ),
+            ];
+        }
+
+        return [];
+    }
+}

package/src/gates/runner.ts

@@ -0,0 +1,101 @@
+import { Gate } from './base.js';
+import { Failure, Config, Report, Status } from '../types/index.js';
+import { FileGate } from './file.js';
+import { ContentGate } from './content.js';
+import { StructureGate } from './structure.js';
+import { execa } from 'execa';
+import { Logger } from '../utils/logger.js';
+
+export class GateRunner {
+    private gates: Gate[] = [];
+
+    constructor(private config: Config) {
+        this.initializeGates();
+    }
+
+    private initializeGates() {
+        if (this.config.gates.max_file_lines) {
+            this.gates.push(new FileGate({ maxLines: this.config.gates.max_file_lines }));
+        }
+        this.gates.push(
+            new ContentGate({
+                forbidTodos: !!this.config.gates.forbid_todos,
+                forbidFixme: !!this.config.gates.forbid_fixme,
+            })
+        );
+        if (this.config.gates.required_files) {
+            this.gates.push(new StructureGate({ requiredFiles: this.config.gates.required_files }));
+        }
+    }
+
+    /**
+     * Allows adding custom gates dynamically (SOLID - Open/Closed Principle)
+     */
+    addGate(gate: Gate) {
+        this.gates.push(gate);
+    }
+
+    async run(cwd: string): Promise<Report> {
+        const start = Date.now();
+        const failures: Failure[] = [];
+        const summary: Record<string, Status> = {};
+
+        // 1. Run internal gates
+        for (const gate of this.gates) {
+            try {
+                const gateFailures = await gate.run({ cwd });
+                if (gateFailures.length > 0) {
+                    failures.push(...gateFailures);
+                    summary[gate.id] = 'FAIL';
+                } else {
+                    summary[gate.id] = 'PASS';
+                }
+            } catch (error: any) {
+                Logger.error(`Gate ${gate.id} failed with error: ${error.message}`);
+                summary[gate.id] = 'ERROR';
+                failures.push({
+                    id: gate.id,
+                    title: `Gate Error: ${gate.title}`,
+                    details: error.message,
+                    hint: 'There was an internal error running this gate. Check the logs.',
+                });
+            }
+        }
+
+        // 2. Run command gates (lint, test, etc.)
+        const commands = this.config.commands;
+        if (commands) {
+            for (const [key, cmd] of Object.entries(commands)) {
+                if (!cmd) {
+                    summary[key] = 'SKIP';
+                    continue;
+                }
+
+                try {
+                    Logger.info(`Running command gate: ${key} (${cmd})`);
+                    await execa(cmd, { shell: true, cwd });
+                    summary[key] = 'PASS';
+                } catch (error: any) {
+                    summary[key] = 'FAIL';
+                    failures.push({
+                        id: key,
+                        title: `${key.toUpperCase()} Check Failed`,
+                        details: error.stderr || error.stdout || error.message,
+                        hint: `Fix the issues reported by \`${cmd}\`. Use rigorous standards (SOLID, DRY) in your resolution.`,
+                    });
+                }
+            }
+        }
+
+        const status: Status = failures.length > 0 ? 'FAIL' : 'PASS';
+
+        return {
+            status,
+            summary,
+            failures,
+            stats: {
+                duration_ms: Date.now() - start,
+            },
+        };
+    }
+}

package/src/gates/structure.ts

@@ -0,0 +1,36 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { Gate, GateContext } from './base.js';
+import { Failure } from '../types/index.js';
+
+export interface StructureGateConfig {
+    requiredFiles: string[];
+}
+
+export class StructureGate extends Gate {
+    constructor(private config: StructureGateConfig) {
+        super('structure-check', 'Project Structure');
+    }
+
+    async run(context: GateContext): Promise<Failure[]> {
+        const missing: string[] = [];
+        for (const file of this.config.requiredFiles) {
+            const filePath = path.join(context.cwd, file);
+            if (!(await fs.pathExists(filePath))) {
+                missing.push(file);
+            }
+        }
+
+        if (missing.length > 0) {
+            return [
+                this.createFailure(
+                    'The following required files are missing:',
+                    missing,
+                    'Create these files to maintain project documentation and consistency.'
+                ),
+            ];
+        }
+
+        return [];
+    }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './types/index.js';
+export * from './gates/runner.js';
+export * from './discovery.js';
+export * from './templates/index.js';
+export * from './utils/logger.js';

package/src/smoke.test.ts

@@ -0,0 +1,18 @@
+import { describe, it, expect } from 'vitest';
+import { GateRunner } from '../src/gates/runner.js';
+
+describe('GateRunner Smoke Test', () => {
+    it('should initialize with empty config', async () => {
+        const config = {
+            version: 1,
+            commands: {},
+            gates: {
+                max_file_lines: 500,
+                forbid_todos: true,
+                forbid_fixme: true,
+            },
+        };
+        const runner = new GateRunner(config as any);
+        expect(runner).toBeDefined();
+    });
+});

package/src/templates/index.ts

@@ -0,0 +1,76 @@
+import { Config } from '../types/index.js';
+
+export interface Template {
+    name: string;
+    markers: string[];
+    config: Partial<Config>;
+}
+
+export const TEMPLATES: Template[] = [
+    {
+        name: 'Node.js',
+        markers: ['package.json'],
+        config: {
+            commands: {
+                lint: 'npm run lint',
+                test: 'npm test',
+            },
+            gates: {
+                max_file_lines: 500,
+                forbid_todos: true,
+                forbid_fixme: true,
+                forbid_paths: [],
+                required_files: ['docs/SPEC.md', 'docs/ARCH.md', 'README.md'],
+            },
+        },
+    },
+    {
+        name: 'Python',
+        markers: ['pyproject.toml', 'requirements.txt', 'setup.py'],
+        config: {
+            commands: {
+                lint: 'ruff check .',
+                test: 'pytest',
+            },
+            gates: {
+                max_file_lines: 500,
+                forbid_todos: true,
+                forbid_fixme: true,
+                forbid_paths: [],
+                required_files: ['docs/SPEC.md', 'docs/ARCH.md', 'README.md'],
+            },
+        },
+    },
+    {
+        name: 'Frontend (React/Vite/Next)',
+        markers: ['next.config.js', 'vite.config.ts', 'tailwind.config.js'],
+        config: {
+            commands: {
+                lint: 'npm run lint',
+                test: 'npm test',
+            },
+            gates: {
+                max_file_lines: 300, // Frontend files often should be smaller
+                forbid_todos: true,
+                forbid_fixme: true,
+                forbid_paths: [],
+                required_files: ['docs/SPEC.md', 'docs/ARCH.md', 'README.md'],
+            },
+        },
+    },
+];
+
+export const UNIVERSAL_CONFIG: Config = {
+    version: 1,
+    commands: {},
+    gates: {
+        max_file_lines: 500,
+        forbid_todos: true,
+        forbid_fixme: true,
+        forbid_paths: [],
+        required_files: ['docs/SPEC.md', 'docs/ARCH.md', 'docs/DECISIONS.md', 'docs/TASKS.md'],
+    },
+    output: {
+        report_path: 'rigour-report.json',
+    },
+};

package/src/types/index.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+
+export const GatesSchema = z.object({
+    max_file_lines: z.number().optional().default(500),
+    forbid_todos: z.boolean().optional().default(true),
+    forbid_fixme: z.boolean().optional().default(true),
+    forbid_paths: z.array(z.string()).optional().default([]),
+    required_files: z.array(z.string()).optional().default([
+        'docs/SPEC.md',
+        'docs/ARCH.md',
+        'docs/DECISIONS.md',
+        'docs/TASKS.md',
+    ]),
+});
+
+export const CommandsSchema = z.object({
+    format: z.string().optional(),
+    lint: z.string().optional(),
+    typecheck: z.string().optional(),
+    test: z.string().optional(),
+});
+
+export const ConfigSchema = z.object({
+    version: z.number().default(1),
+    commands: CommandsSchema.optional().default({}),
+    gates: GatesSchema.optional().default({}),
+    output: z.object({
+        report_path: z.string().default('rigour-report.json'),
+    }).optional().default({}),
+});
+
+export type Gates = z.infer<typeof GatesSchema>;
+export type Commands = z.infer<typeof CommandsSchema>;
+export type Config = z.infer<typeof ConfigSchema>;
+
+export const StatusSchema = z.enum(['PASS', 'FAIL', 'SKIP', 'ERROR']);
+export type Status = z.infer<typeof StatusSchema>;
+
+export const FailureSchema = z.object({
+    id: z.string(),
+    title: z.string(),
+    details: z.string(),
+    files: z.array(z.string()).optional(),
+    hint: z.string().optional(),
+});
+export type Failure = z.infer<typeof FailureSchema>;
+
+export const ReportSchema = z.object({
+    status: StatusSchema,
+    summary: z.record(StatusSchema),
+    failures: z.array(FailureSchema),
+    stats: z.object({
+        duration_ms: z.number(),
+    }),
+});
+export type Report = z.infer<typeof ReportSchema>;

package/src/utils/logger.ts

@@ -0,0 +1,43 @@
+import chalk from 'chalk';
+
+export enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+}
+
+export class Logger {
+    private static level: LogLevel = LogLevel.INFO;
+
+    static setLevel(level: LogLevel) {
+        this.level = level;
+    }
+
+    static info(message: string) {
+        if (this.level <= LogLevel.INFO) {
+            console.log(chalk.blue('info: ') + message);
+        }
+    }
+
+    static warn(message: string) {
+        if (this.level <= LogLevel.WARN) {
+            console.log(chalk.yellow('warn: ') + message);
+        }
+    }
+
+    static error(message: string, error?: any) {
+        if (this.level <= LogLevel.ERROR) {
+            console.error(chalk.red('error: ') + message);
+            if (error) {
+                console.error(error);
+            }
+        }
+    }
+
+    static debug(message: string) {
+        if (this.level <= LogLevel.DEBUG) {
+            console.log(chalk.dim('debug: ') + message);
+        }
+    }
+}