@rigour-labs/core 1.0.0 → 1.2.1

package/src/gates/ast.ts

@@ -0,0 +1,150 @@
+import ts from 'typescript';
+import fs from 'fs-extra';
+import path from 'path';
+import { globby } from 'globby';
+import { Gate, GateContext } from './base.js';
+import { Failure, Gates } from '../types/index.js';
+import micromatch from 'micromatch';
+
+export class ASTGate extends Gate {
+    constructor(private config: Gates) {
+        super('ast-analysis', 'AST Structural Analysis');
+    }
+
+    async run(context: GateContext): Promise<Failure[]> {
+        const failures: Failure[] = [];
+        const files = await globby(['**/*.{ts,js,tsx,jsx}'], {
+            cwd: context.cwd,
+            ignore: ['node_modules/**', 'dist/**', 'build/**', '**/*.test.*', '**/*.spec.*'],
+        });
+
+        for (const file of files) {
+            const fullPath = path.join(context.cwd, file);
+            const content = await fs.readFile(fullPath, 'utf-8');
+            const sourceFile = ts.createSourceFile(file, content, ts.ScriptTarget.Latest, true);
+
+            this.analyzeSourceFile(sourceFile, file, failures);
+        }
+
+        return failures;
+    }
+
+    private analyzeSourceFile(sourceFile: ts.SourceFile, relativePath: string, failures: Failure[]) {
+        const astConfig = this.config.ast || {};
+        const maxComplexity = astConfig.complexity || 10;
+        const maxMethods = astConfig.max_methods || 10;
+        const maxParams = astConfig.max_params || 5;
+
+        const visit = (node: ts.Node) => {
+            // 1. Complexity & Params for functions
+            if (ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node) || ts.isArrowFunction(node)) {
+                const name = this.getNodeName(node);
+
+                // Parameter count
+                if (node.parameters.length > maxParams) {
+                    failures.push(this.createFailure(
+                        `Function '${name}' has ${node.parameters.length} parameters (max: ${maxParams})`,
+                        [relativePath],
+                        `Reduce number of parameters or use an options object.`
+                    ));
+                    // Update: Failures in Runner will be mapped to FixPacket
+                    (failures[failures.length - 1] as any).metrics = { count: node.parameters.length, max: maxParams };
+                }
+
+                // Cyclomatic Complexity (Simplified: nodes that cause branching)
+                let complexity = 1;
+                const countComplexity = (n: ts.Node) => {
+                    if (ts.isIfStatement(n) || ts.isCaseClause(n) || ts.isDefaultClause(n) ||
+                        ts.isForStatement(n) || ts.isForInStatement(n) || ts.isForOfStatement(n) ||
+                        ts.isWhileStatement(n) || ts.isDoStatement(n) || ts.isConditionalExpression(n)) {
+                        complexity++;
+                    }
+                    if (ts.isBinaryExpression(n)) {
+                        if (n.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken ||
+                            n.operatorToken.kind === ts.SyntaxKind.BarBarToken) {
+                            complexity++;
+                        }
+                    }
+                    ts.forEachChild(n, countComplexity);
+                };
+                ts.forEachChild(node, countComplexity);
+
+                if (complexity > maxComplexity) {
+                    failures.push(this.createFailure(
+                        `Function '${name}' has cyclomatic complexity of ${complexity} (max: ${maxComplexity})`,
+                        [relativePath],
+                        `Refactor '${name}' into smaller, more focused functions.`
+                    ));
+                    (failures[failures.length - 1] as any).metrics = { complexity, max: maxComplexity };
+                }
+            }
+
+            // 2. Class metrics
+            if (ts.isClassDeclaration(node)) {
+                const name = node.name?.text || 'Anonymous Class';
+                const methods = node.members.filter(ts.isMethodDeclaration);
+
+                if (methods.length > maxMethods) {
+                    failures.push(this.createFailure(
+                        `Class '${name}' has ${methods.length} methods (max: ${maxMethods})`,
+                        [relativePath],
+                        `Class '${name}' is becoming a 'God Object'. Split it into smaller services.`
+                    ));
+                    (failures[failures.length - 1] as any).metrics = { methodCount: methods.length, max: maxMethods };
+                }
+            }
+
+            // 3. Import check for Layer Boundaries
+            if (ts.isImportDeclaration(node)) {
+                const importPath = (node.moduleSpecifier as ts.StringLiteral).text;
+                this.checkBoundary(importPath, relativePath, failures);
+            }
+
+            ts.forEachChild(node, visit);
+        };
+
+        ts.forEachChild(sourceFile, visit);
+    }
+
+    private checkBoundary(importPath: string, relativePath: string, failures: Failure[]) {
+        const boundaries = (this.config as any).architecture?.boundaries || [];
+        if (boundaries.length === 0) return;
+
+        for (const rule of boundaries) {
+            const isFromMatch = micromatch.isMatch(relativePath, rule.from);
+            if (isFromMatch) {
+                // Approximate resolution (simplified for now)
+                // Real implementation would need to handle alias and absolute path resolution
+                const resolved = importPath.startsWith('.')
+                    ? path.join(path.dirname(relativePath), importPath)
+                    : importPath;
+
+                const isToMatch = micromatch.isMatch(resolved, rule.to);
+
+                if (rule.mode === 'deny' && isToMatch) {
+                    failures.push(this.createFailure(
+                        `Architectural Violation: '${relativePath}' is forbidden from importing '${importPath}' (denied by boundary rule).`,
+                        [relativePath],
+                        `Remove this import to maintain architectural layering.`
+                    ));
+                } else if (rule.mode === 'allow' && !isToMatch && importPath.startsWith('.')) {
+                    // Complexity: Allow rules are trickier to implement strictly without full resolution
+                }
+            }
+        }
+    }
+
+    private getNodeName(node: ts.Node): string {
+        if (ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node)) {
+            return node.name?.getText() || 'anonymous';
+        }
+        if (ts.isArrowFunction(node)) {
+            const parent = node.parent;
+            if (ts.isVariableDeclaration(parent)) {
+                return parent.name.getText();
+            }
+            return 'anonymous arrow';
+        }
+        return 'unknown';
+    }
+}

package/src/gates/dependency.ts

@@ -0,0 +1,44 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { Failure, Config } from '../types/index.js';
+import { Gate, GateContext } from './base.js';
+
+export class DependencyGate extends Gate {
+    constructor(private config: Config) {
+        super('dependency-guardian', 'Dependency Guardian');
+    }
+
+    async run(context: GateContext): Promise<Failure[]> {
+        const failures: Failure[] = [];
+        const forbidden = this.config.gates.dependencies?.forbid || [];
+
+        if (forbidden.length === 0) return [];
+
+        const { cwd } = context;
+
+        // 1. Scan Node.js (package.json)
+        const pkgPath = path.join(cwd, 'package.json');
+        if (await fs.pathExists(pkgPath)) {
+            try {
+                const pkg = await fs.readJson(pkgPath);
+                const allDeps = {
+                    ...(pkg.dependencies || {}),
+                    ...(pkg.devDependencies || {}),
+                    ...(pkg.peerDependencies || {}),
+                };
+
+                for (const dep of forbidden) {
+                    if (allDeps[dep]) {
+                        failures.push(this.createFailure(
+                            `The package '${dep}' is forbidden by project standards.`,
+                            ['package.json'],
+                            `Remove '${dep}' from package.json and use approved alternatives.`
+                        ));
+                    }
+                }
+            } catch (e) { }
+        }
+
+        return failures;
+    }
+}

package/src/gates/runner.ts

@@ -3,6 +3,9 @@ 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 { ASTGate } from './ast.js';
+import { SafetyGate } from './safety.js';
+import { DependencyGate } from './dependency.js';
 import { execa } from 'execa';
 import { Logger } from '../utils/logger.js';
 
@@ -26,6 +29,9 @@ export class GateRunner {
         if (this.config.gates.required_files) {
             this.gates.push(new StructureGate({ requiredFiles: this.config.gates.required_files }));
         }
+        this.gates.push(new ASTGate(this.config.gates));
+        this.gates.push(new DependencyGate(this.config));
+        this.gates.push(new SafetyGate(this.config.gates));
     }
 
     /**

package/src/gates/safety.ts

@@ -0,0 +1,49 @@
+import { Gate, GateContext } from './base.js';
+import { Failure, Gates } from '../types/index.js';
+import { execa } from 'execa';
+
+export class SafetyGate extends Gate {
+    constructor(private config: Gates) {
+        super('safety-rail', 'Safety & Protection Rails');
+    }
+
+    async run(context: GateContext): Promise<Failure[]> {
+        const failures: Failure[] = [];
+        const safety = this.config.safety || {};
+        const protectedPaths = safety.protected_paths || [];
+
+        if (protectedPaths.length === 0) return [];
+
+        try {
+            // Check for modified files in protected paths using git
+            // This is a "Safety Rail" - if an agent touched these, we fail.
+            const { stdout } = await execa('git', ['status', '--porcelain'], { cwd: context.cwd });
+            const modifiedFiles = stdout.split('\n')
+                .filter(line => line.trim().length > 0)
+                .map(line => line.slice(3));
+
+            for (const file of modifiedFiles) {
+                if (this.isProtected(file, protectedPaths)) {
+                    failures.push(this.createFailure(
+                        `Protected file '${file}' was modified.`,
+                        [file],
+                        `Agents are forbidden from modifying files in ${protectedPaths.join(', ')}.`
+                    ));
+                }
+            }
+        } catch (error) {
+            // If not a git repo, skip safety for now
+        }
+
+        return failures;
+    }
+
+    private isProtected(file: string, patterns: string[]): boolean {
+        return patterns.some(p => {
+            const cleanP = p.replace('/**', '').replace('/*', '');
+            if (file === cleanP) return true;
+            if (cleanP.endsWith('/')) return file.startsWith(cleanP);
+            return file.startsWith(cleanP + '/');
+        });
+    }
+}

package/src/index.ts

@@ -1,5 +1,8 @@
 export * from './types/index.js';
 export * from './gates/runner.js';
 export * from './discovery.js';
+export * from './services/fix-packet-service.js';
 export * from './templates/index.js';
+export * from './types/fix-packet.js';
+export { Gate, GateContext } from './gates/base.js';
 export * from './utils/logger.js';

package/src/services/fix-packet-service.ts

@@ -0,0 +1,42 @@
+import { Report, Failure, Config } from '../types/index.js';
+import { FixPacketV2, FixPacketV2Schema } from '../types/fix-packet.js';
+
+export class FixPacketService {
+    generate(report: Report, config: Config): FixPacketV2 {
+        const violations = report.failures.map(f => ({
+            id: f.id,
+            gate: f.id,
+            severity: this.inferSeverity(f),
+            title: f.title,
+            details: f.details,
+            files: f.files,
+            hint: f.hint,
+            instructions: f.hint ? [f.hint] : [], // Use hint as first instruction
+            metrics: (f as any).metrics,
+        }));
+
+        const packet: FixPacketV2 = {
+            version: 2,
+            goal: "Achieve PASS state by resolving all listed engineering violations.",
+            violations,
+            constraints: {
+                paradigm: config.paradigm,
+                protected_paths: config.gates.safety?.protected_paths,
+                do_not_touch: config.gates.safety?.protected_paths,
+                max_files_changed: config.gates.safety?.max_files_changed_per_cycle,
+                no_new_deps: true,
+            },
+        };
+
+        return FixPacketV2Schema.parse(packet);
+    }
+
+    private inferSeverity(f: Failure): "low" | "medium" | "high" | "critical" {
+        // High complexity or God objects are usually High severity
+        if (f.id === 'ast-analysis') return 'high';
+        // Unit test or Lint failures are Medium
+        if (f.id === 'test' || f.id === 'lint') return 'medium';
+        // Documentation or small file size issues are Low
+        return 'medium';
+    }
+}

package/src/templates/index.ts

@@ -1,60 +1,132 @@
-import { Config } from '../types/index.js';
+import { Config, Commands, Gates } from '../types/index.js';
 
 export interface Template {
     name: string;
     markers: string[];
-    config: Partial<Config>;
+    config: {
+        preset?: string;
+        paradigm?: string;
+        commands?: Partial<Commands>;
+        gates?: Partial<Gates>;
+        planned?: string[];
+    };
 }
 
 export const TEMPLATES: Template[] = [
     {
-        name: 'Node.js',
-        markers: ['package.json'],
+        name: 'ui',
+        markers: [
+            'package.json', // Check deps later
+            'next.config.js',
+            'vite.config.ts',
+            'tailwind.config.js',
+            'base.css',
+            'index.html',
+        ],
         config: {
-            commands: {
-                lint: 'npm run lint',
-                test: 'npm test',
+            preset: 'ui',
+            gates: {
+                max_file_lines: 300,
+                required_files: ['docs/SPEC.md', 'docs/ARCH.md', 'README.md'],
             },
+            planned: [
+                'Layer Boundary: Components cannot import from DB',
+                'Prop-Drilling Detection: Max depth 5',
+            ],
+        },
+    },
+    {
+        name: 'api',
+        markers: [
+            'go.mod',
+            'requirements.txt',
+            'pyproject.toml',
+            'package.json', // Check for backend frameworks later
+            'app.py',
+            'main.go',
+            'index.js',
+        ],
+        config: {
+            preset: 'api',
             gates: {
-                max_file_lines: 500,
-                forbid_todos: true,
-                forbid_fixme: true,
-                forbid_paths: [],
+                max_file_lines: 400,
                 required_files: ['docs/SPEC.md', 'docs/ARCH.md', 'README.md'],
             },
+            planned: [
+                'Service Layer Enforcement: Controllers -> Services only',
+                'Repo Pattern: Databases access isolated to repositories/',
+            ],
         },
     },
     {
-        name: 'Python',
-        markers: ['pyproject.toml', 'requirements.txt', 'setup.py'],
+        name: 'infra',
+        markers: [
+            'Dockerfile',
+            'docker-compose.yml',
+            'main.tf',
+            'k8s/',
+            'helm/',
+            'ansible/',
+        ],
         config: {
-            commands: {
-                lint: 'ruff check .',
-                test: 'pytest',
+            preset: 'infra',
+            gates: {
+                max_file_lines: 300,
+                required_files: ['docs/RUNBOOK.md', 'docs/ARCH.md', 'README.md'],
             },
+        },
+    },
+    {
+        name: 'data',
+        markers: [
+            'ipynb',
+            'spark',
+            'pandas',
+            'data/',
+            'dbt_project.yml',
+        ],
+        config: {
+            preset: 'data',
             gates: {
                 max_file_lines: 500,
-                forbid_todos: true,
-                forbid_fixme: true,
-                forbid_paths: [],
-                required_files: ['docs/SPEC.md', 'docs/ARCH.md', 'README.md'],
+                required_files: ['docs/DATA_DICTIONARY.md', 'docs/PIPELINE.md', 'README.md'],
             },
+            planned: [
+                'Stochastic Determinism: Seed setting enforcement',
+                'Data Leaks: Detecting PII in notebook outputs',
+            ],
         },
     },
+];
+
+export const PARADIGM_TEMPLATES: Template[] = [
     {
-        name: 'Frontend (React/Vite/Next)',
-        markers: ['next.config.js', 'vite.config.ts', 'tailwind.config.js'],
+        name: 'oop',
+        markers: [
+            'class ',
+            'interface ',
+            'implements ',
+            'extends ',
+        ],
         config: {
-            commands: {
-                lint: 'npm run lint',
-                test: 'npm test',
+            paradigm: 'oop',
+            gates: {
+                // Future: class-specific gates
             },
+        },
+    },
+    {
+        name: 'functional',
+        markers: [
+            '=>',
+            'export const',
+            'map(',
+            'filter(',
+        ],
+        config: {
+            paradigm: 'functional',
             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'],
+                // Future: function-specific gates
             },
         },
     },
@@ -69,8 +141,24 @@ export const UNIVERSAL_CONFIG: Config = {
         forbid_fixme: true,
         forbid_paths: [],
         required_files: ['docs/SPEC.md', 'docs/ARCH.md', 'docs/DECISIONS.md', 'docs/TASKS.md'],
+        ast: {
+            complexity: 10,
+            max_methods: 10,
+            max_params: 5,
+        },
+        dependencies: {
+            forbid: [],
+        },
+        architecture: {
+            boundaries: [],
+        },
+        safety: {
+            max_files_changed_per_cycle: 10,
+            protected_paths: ['.github/**', 'docs/**', 'rigour.yml'],
+        },
     },
     output: {
         report_path: 'rigour-report.json',
     },
+    planned: [],
 };

package/src/types/fix-packet.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+
+/**
+ * Fix Packet v2 Schema
+ * Designed for high-fidelity communication with AI agents during the refinement loop.
+ */
+export const FixPacketV2Schema = z.object({
+    version: z.literal(2),
+    goal: z.string().default('Achieve PASS state for all quality gates'),
+    violations: z.array(z.object({
+        id: z.string(),
+        gate: z.string(),
+        severity: z.enum(['low', 'medium', 'high', 'critical']).default('medium'),
+        category: z.string().optional(),
+        title: z.string(),
+        details: z.string(),
+        files: z.array(z.string()).optional(),
+        hint: z.string().optional(),
+        instructions: z.array(z.string()).optional(), // Step-by-step fix instructions
+        metrics: z.record(z.any()).optional(), // e.g., { complexity: 15, max: 10 }
+    })),
+    constraints: z.object({
+        protected_paths: z.array(z.string()).optional(),
+        do_not_touch: z.array(z.string()).optional(), // Alias for protected_paths
+        max_files_changed: z.number().optional(),
+        no_new_deps: z.boolean().optional().default(true),
+        allowed_dependencies: z.array(z.string()).optional(),
+        paradigm: z.string().optional(), // 'oop', 'functional'
+    }).optional().default({}),
+});
+
+export type FixPacketV2 = z.infer<typeof FixPacketV2Schema>;

package/src/types/index.ts

@@ -11,6 +11,26 @@ export const GatesSchema = z.object({
         'docs/DECISIONS.md',
         'docs/TASKS.md',
     ]),
+    ast: z.object({
+        complexity: z.number().optional().default(10),
+        max_methods: z.number().optional().default(10),
+        max_params: z.number().optional().default(5),
+    }).optional().default({}),
+    dependencies: z.object({
+        forbid: z.array(z.string()).optional().default([]),
+        trusted_registry: z.string().optional(),
+    }).optional().default({}),
+    architecture: z.object({
+        boundaries: z.array(z.object({
+            from: z.string(),
+            to: z.string(),
+            mode: z.enum(['allow', 'deny']).default('deny'),
+        })).optional().default([]),
+    }).optional().default({}),
+    safety: 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({}),
 });
 
 export const CommandsSchema = z.object({
@@ -22,11 +42,14 @@ export const CommandsSchema = z.object({
 
 export const ConfigSchema = z.object({
     version: z.number().default(1),
+    preset: z.string().optional(),
+    paradigm: z.string().optional(),
     commands: CommandsSchema.optional().default({}),
     gates: GatesSchema.optional().default({}),
     output: z.object({
         report_path: z.string().default('rigour-report.json'),
     }).optional().default({}),
+    planned: z.array(z.string()).optional().default([]),
 });
 
 export type Gates = z.infer<typeof GatesSchema>;