@rigour-labs/core 4.3.4 → 4.3.5

package/dist/services/fix-packet-service.js

@@ -1,8 +1,9 @@
 import { FixPacketV2Schema } from '../types/fix-packet.js';
 export class FixPacketService {
     generate(report, config) {
-        // Sort violations: critical first, then high, medium, low, info
         const severityOrder = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
+        // Deduplicate failed gate IDs
+        const failedGates = [...new Set(report.failures.map(f => f.id))];
         const violations = report.failures
             .map(f => ({
             id: f.id,
@@ -12,19 +13,32 @@ export class FixPacketService {
             title: f.title,
             details: f.details,
             files: f.files,
+            locations: buildLocations(f),
             hint: f.hint,
-            instructions: f.hint ? [f.hint] : [],
+            instructions: buildInstructions(f),
             metrics: f.metrics,
         }))
             .sort((a, b) => (severityOrder[a.severity] ?? 2) - (severityOrder[b.severity] ?? 2));
+        // Build verification commands from config.commands
+        const verification = buildVerification(config);
+        // Build allowed scope from violation files (what the agent should touch)
+        const violationFiles = violations.flatMap(v => v.files || []);
+        const uniqueFiles = [...new Set(violationFiles.map(f => {
+                // Strip metadata like "(600 lines)" from file paths
+                const clean = f.replace(/\s*\(.*?\)\s*$/, '').trim();
+                return clean;
+            }))];
         const packet = {
-            version: 2,
+            version: 3,
             goal: "Achieve PASS state by resolving all listed engineering violations.",
+            failed_gates: failedGates,
             violations,
+            verification,
             constraints: {
                 paradigm: config.paradigm,
                 protected_paths: config.gates.safety?.protected_paths,
                 do_not_touch: config.gates.safety?.protected_paths,
+                allowed_scope: uniqueFiles.length > 0 ? uniqueFiles : undefined,
                 max_files_changed: config.gates.safety?.max_files_changed_per_cycle,
                 no_new_deps: true,
             },
@@ -32,3 +46,86 @@ export class FixPacketService {
         return FixPacketV2Schema.parse(packet);
     }
 }
+/**
+ * Build precise locations from failure's files + line numbers.
+ * If failure has both files[] and line/endLine, create a location per file.
+ * If only files[], locations are file-level (no line numbers).
+ */
+function buildLocations(f) {
+    if (!f.files || f.files.length === 0)
+        return undefined;
+    return f.files.map(file => {
+        const loc = {
+            file: file.replace(/\s*\(.*?\)\s*$/, '').trim(),
+        };
+        // If the failure has line numbers and there's only one file, attach them
+        if (f.files.length === 1) {
+            if (f.line)
+                loc.line = f.line;
+            if (f.endLine)
+                loc.endLine = f.endLine;
+        }
+        return loc;
+    });
+}
+/**
+ * Build step-by-step instructions from the hint and failure context.
+ */
+function buildInstructions(f) {
+    const steps = [];
+    if (f.hint)
+        steps.push(f.hint);
+    // Add gate-specific guidance
+    switch (f.id) {
+        case 'file-size':
+            steps.push('Break the file into smaller modules following Single Responsibility Principle');
+            break;
+        case 'hallucinated-imports':
+            steps.push('Remove or replace the non-existent import with a real package');
+            break;
+        case 'phantom-apis':
+            steps.push('Check the actual API surface of the module and use a real method');
+            break;
+        case 'forbid-todos':
+            steps.push('Resolve the TODO/FIXME comment or remove it if no longer relevant');
+            break;
+        case 'security-patterns':
+            steps.push('Apply the security fix described above. Do NOT suppress the warning.');
+            break;
+        case 'promise-safety':
+            steps.push('Add proper error handling (try/catch or .catch()) to async operations');
+            break;
+        case 'deprecated-apis':
+            steps.push('Replace deprecated API usage with the recommended modern alternative');
+            break;
+        case 'duplication-drift':
+            steps.push('Extract the duplicated logic into a shared utility or module');
+            break;
+        case 'inconsistent-error-handling':
+            steps.push('Align error handling strategy across the module');
+            break;
+    }
+    return steps.length > 0 ? steps : [];
+}
+/**
+ * Build verification block from config.commands.
+ * These are the commands the agent MUST run after fixing to prove the fix works.
+ */
+function buildVerification(config) {
+    const commands = [];
+    if (config.commands?.typecheck) {
+        commands.push({ cmd: config.commands.typecheck, purpose: 'Ensure no type errors after changes' });
+    }
+    if (config.commands?.lint) {
+        commands.push({ cmd: config.commands.lint, purpose: 'Ensure no lint violations' });
+    }
+    if (config.commands?.test) {
+        commands.push({ cmd: config.commands.test, purpose: 'Ensure all tests pass' });
+    }
+    if (config.commands?.format) {
+        commands.push({ cmd: config.commands.format, purpose: 'Ensure code formatting is correct' });
+    }
+    // Always end with rigour check
+    commands.push({ cmd: 'rigour_check', purpose: 'Re-run all quality gates to confirm PASS' });
+    return { commands, gate_command: 'rigour_check' };
+}

package/dist/types/fix-packet.d.ts

@@ -1,11 +1,91 @@
 import { z } from 'zod';
 /**
- * Fix Packet v2 Schema
- * Designed for high-fidelity communication with AI agents during the refinement loop.
+ * Fix Packet v3 Schema
+ *
+ * Designed for high-fidelity, machine-readable communication with AI agents.
+ * Every violation tells the agent exactly: who failed, which files, what rule,
+ * where in the file, and what must pass to verify the fix.
+ *
+ * v3 changes from v2:
+ *   - Violations now include `location` (file + line range) for precise targeting
+ *   - Top-level `verification` block: commands the agent MUST run after fixing
+ *   - `allowed_scope`: explicit list of file globs the agent IS allowed to edit
+ *   - `failed_gates`: summary list of gate IDs that failed (quick machine check)
  */
+declare const ViolationLocationSchema: z.ZodObject<{
+    file: z.ZodString;
+    line: z.ZodOptional<z.ZodNumber>;
+    endLine: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    file: string;
+    line?: number | undefined;
+    endLine?: number | undefined;
+}, {
+    file: string;
+    line?: number | undefined;
+    endLine?: number | undefined;
+}>;
+declare const ViolationSchema: z.ZodObject<{
+    id: z.ZodString;
+    gate: z.ZodString;
+    severity: z.ZodDefault<z.ZodEnum<["info", "low", "medium", "high", "critical"]>>;
+    category: z.ZodOptional<z.ZodString>;
+    title: z.ZodString;
+    details: z.ZodString;
+    files: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    locations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        file: z.ZodString;
+        line: z.ZodOptional<z.ZodNumber>;
+        endLine: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        file: string;
+        line?: number | undefined;
+        endLine?: number | undefined;
+    }, {
+        file: string;
+        line?: number | undefined;
+        endLine?: number | undefined;
+    }>, "many">>;
+    hint: z.ZodOptional<z.ZodString>;
+    instructions: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    metrics: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    title: string;
+    details: string;
+    severity: "critical" | "high" | "medium" | "low" | "info";
+    gate: string;
+    files?: string[] | undefined;
+    hint?: string | undefined;
+    category?: string | undefined;
+    locations?: {
+        file: string;
+        line?: number | undefined;
+        endLine?: number | undefined;
+    }[] | undefined;
+    instructions?: string[] | undefined;
+    metrics?: Record<string, any> | undefined;
+}, {
+    id: string;
+    title: string;
+    details: string;
+    gate: string;
+    severity?: "critical" | "high" | "medium" | "low" | "info" | undefined;
+    files?: string[] | undefined;
+    hint?: string | undefined;
+    category?: string | undefined;
+    locations?: {
+        file: string;
+        line?: number | undefined;
+        endLine?: number | undefined;
+    }[] | undefined;
+    instructions?: string[] | undefined;
+    metrics?: Record<string, any> | undefined;
+}>;
 export declare const FixPacketV2Schema: z.ZodObject<{
-    version: z.ZodLiteral<2>;
+    version: z.ZodLiteral<3>;
     goal: z.ZodDefault<z.ZodString>;
+    failed_gates: z.ZodArray<z.ZodString, "many">;
     violations: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         gate: z.ZodString;
@@ -14,6 +94,19 @@ export declare const FixPacketV2Schema: z.ZodObject<{
         title: z.ZodString;
         details: z.ZodString;
         files: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        locations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            file: z.ZodString;
+            line: z.ZodOptional<z.ZodNumber>;
+            endLine: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            file: string;
+            line?: number | undefined;
+            endLine?: number | undefined;
+        }, {
+            file: string;
+            line?: number | undefined;
+            endLine?: number | undefined;
+        }>, "many">>;
         hint: z.ZodOptional<z.ZodString>;
         instructions: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         metrics: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
@@ -26,6 +119,11 @@ export declare const FixPacketV2Schema: z.ZodObject<{
         files?: string[] | undefined;
         hint?: string | undefined;
         category?: string | undefined;
+        locations?: {
+            file: string;
+            line?: number | undefined;
+            endLine?: number | undefined;
+        }[] | undefined;
         instructions?: string[] | undefined;
         metrics?: Record<string, any> | undefined;
     }, {
@@ -37,12 +135,43 @@ export declare const FixPacketV2Schema: z.ZodObject<{
         files?: string[] | undefined;
         hint?: string | undefined;
         category?: string | undefined;
+        locations?: {
+            file: string;
+            line?: number | undefined;
+            endLine?: number | undefined;
+        }[] | undefined;
         instructions?: string[] | undefined;
         metrics?: Record<string, any> | undefined;
     }>, "many">;
+    verification: z.ZodOptional<z.ZodObject<{
+        commands: z.ZodArray<z.ZodObject<{
+            cmd: z.ZodString;
+            purpose: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            cmd: string;
+            purpose: string;
+        }, {
+            cmd: string;
+            purpose: string;
+        }>, "many">;
+        gate_command: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        commands: {
+            cmd: string;
+            purpose: string;
+        }[];
+        gate_command: string;
+    }, {
+        commands: {
+            cmd: string;
+            purpose: string;
+        }[];
+        gate_command?: string | undefined;
+    }>>;
     constraints: z.ZodDefault<z.ZodOptional<z.ZodObject<{
         protected_paths: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         do_not_touch: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        allowed_scope: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         max_files_changed: z.ZodOptional<z.ZodNumber>;
         no_new_deps: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
         allowed_dependencies: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
@@ -52,19 +181,22 @@ export declare const FixPacketV2Schema: z.ZodObject<{
         protected_paths?: string[] | undefined;
         paradigm?: string | undefined;
         do_not_touch?: string[] | undefined;
+        allowed_scope?: string[] | undefined;
         max_files_changed?: number | undefined;
         allowed_dependencies?: string[] | undefined;
     }, {
         protected_paths?: string[] | undefined;
         paradigm?: string | undefined;
         do_not_touch?: string[] | undefined;
+        allowed_scope?: string[] | undefined;
         max_files_changed?: number | undefined;
         no_new_deps?: boolean | undefined;
         allowed_dependencies?: string[] | undefined;
     }>>>;
 }, "strip", z.ZodTypeAny, {
-    version: 2;
+    version: 3;
     goal: string;
+    failed_gates: string[];
     violations: {
         id: string;
         title: string;
@@ -74,6 +206,11 @@ export declare const FixPacketV2Schema: z.ZodObject<{
         files?: string[] | undefined;
         hint?: string | undefined;
         category?: string | undefined;
+        locations?: {
+            file: string;
+            line?: number | undefined;
+            endLine?: number | undefined;
+        }[] | undefined;
         instructions?: string[] | undefined;
         metrics?: Record<string, any> | undefined;
     }[];
@@ -82,11 +219,20 @@ export declare const FixPacketV2Schema: z.ZodObject<{
         protected_paths?: string[] | undefined;
         paradigm?: string | undefined;
         do_not_touch?: string[] | undefined;
+        allowed_scope?: string[] | undefined;
         max_files_changed?: number | undefined;
         allowed_dependencies?: string[] | undefined;
     };
+    verification?: {
+        commands: {
+            cmd: string;
+            purpose: string;
+        }[];
+        gate_command: string;
+    } | undefined;
 }, {
-    version: 2;
+    version: 3;
+    failed_gates: string[];
     violations: {
         id: string;
         title: string;
@@ -96,17 +242,33 @@ export declare const FixPacketV2Schema: z.ZodObject<{
         files?: string[] | undefined;
         hint?: string | undefined;
         category?: string | undefined;
+        locations?: {
+            file: string;
+            line?: number | undefined;
+            endLine?: number | undefined;
+        }[] | undefined;
         instructions?: string[] | undefined;
         metrics?: Record<string, any> | undefined;
     }[];
     goal?: string | undefined;
+    verification?: {
+        commands: {
+            cmd: string;
+            purpose: string;
+        }[];
+        gate_command?: string | undefined;
+    } | undefined;
     constraints?: {
         protected_paths?: string[] | undefined;
         paradigm?: string | undefined;
         do_not_touch?: string[] | undefined;
+        allowed_scope?: string[] | undefined;
         max_files_changed?: number | undefined;
         no_new_deps?: boolean | undefined;
         allowed_dependencies?: string[] | undefined;
     } | undefined;
 }>;
 export type FixPacketV2 = z.infer<typeof FixPacketV2Schema>;
+export type Violation = z.infer<typeof ViolationSchema>;
+export type ViolationLocation = z.infer<typeof ViolationLocationSchema>;
+export {};

package/dist/types/fix-packet.js

@@ -1,29 +1,55 @@
 import { z } from 'zod';
 /**
- * Fix Packet v2 Schema
- * Designed for high-fidelity communication with AI agents during the refinement loop.
+ * Fix Packet v3 Schema
+ *
+ * Designed for high-fidelity, machine-readable communication with AI agents.
+ * Every violation tells the agent exactly: who failed, which files, what rule,
+ * where in the file, and what must pass to verify the fix.
+ *
+ * v3 changes from v2:
+ *   - Violations now include `location` (file + line range) for precise targeting
+ *   - Top-level `verification` block: commands the agent MUST run after fixing
+ *   - `allowed_scope`: explicit list of file globs the agent IS allowed to edit
+ *   - `failed_gates`: summary list of gate IDs that failed (quick machine check)
  */
+const ViolationLocationSchema = z.object({
+    file: z.string(),
+    line: z.number().optional(),
+    endLine: z.number().optional(),
+});
+const ViolationSchema = z.object({
+    id: z.string(), // Gate ID, e.g. "file-size"
+    gate: z.string(), // Same as id (kept for backwards compat)
+    severity: z.enum(['info', 'low', 'medium', 'high', 'critical']).default('medium'),
+    category: z.string().optional(), // Provenance: "traditional", "ai-drift", "security", etc.
+    title: z.string(),
+    details: z.string(),
+    files: z.array(z.string()).optional(),
+    locations: z.array(ViolationLocationSchema).optional(), // Precise file + line targets
+    hint: z.string().optional(),
+    instructions: z.array(z.string()).optional(),
+    metrics: z.record(z.any()).optional(), // e.g. { complexity: 15, threshold: 10 }
+});
+const VerificationSchema = z.object({
+    commands: z.array(z.object({
+        cmd: z.string(), // e.g. "npm run typecheck"
+        purpose: z.string(), // e.g. "Ensure no TypeScript errors"
+    })),
+    gate_command: z.string().default('rigour_check'), // The rigour tool to re-run
+});
 export const FixPacketV2Schema = z.object({
-    version: z.literal(2),
+    version: z.literal(3),
     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(['info', '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 }
-    })),
+    failed_gates: z.array(z.string()), // Quick list: ["file-size", "hallucinated-imports"]
+    violations: z.array(ViolationSchema),
+    verification: VerificationSchema.optional(),
     constraints: z.object({
         protected_paths: z.array(z.string()).optional(),
-        do_not_touch: z.array(z.string()).optional(), // Alias for protected_paths
+        do_not_touch: z.array(z.string()).optional(),
+        allowed_scope: z.array(z.string()).optional(), // Globs the agent IS allowed to edit
         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'
+        paradigm: z.string().optional(),
     }).optional().default({}),
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rigour-labs/core",
-  "version": "4.3.4",
+  "version": "4.3.5",
   "description": "Deterministic quality gate engine for AI-generated code. AST analysis, drift detection, and Fix Packet generation across TypeScript, JavaScript, Python, Go, Ruby, and C#.",
   "license": "MIT",
   "homepage": "https://rigour.run",
@@ -59,11 +59,11 @@
     "@xenova/transformers": "^2.17.2",
     "better-sqlite3": "^11.0.0",
     "openai": "^4.104.0",
-    "@rigour-labs/brain-darwin-arm64": "4.3.4",
-    "@rigour-labs/brain-darwin-x64": "4.3.4",
-    "@rigour-labs/brain-linux-x64": "4.3.4",
-    "@rigour-labs/brain-linux-arm64": "4.3.4",
-    "@rigour-labs/brain-win-x64": "4.3.4"
+    "@rigour-labs/brain-darwin-arm64": "4.3.5",
+    "@rigour-labs/brain-darwin-x64": "4.3.5",
+    "@rigour-labs/brain-win-x64": "4.3.5",
+    "@rigour-labs/brain-linux-x64": "4.3.5",
+    "@rigour-labs/brain-linux-arm64": "4.3.5"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.12",