0xray 2.0.0

package/dist/enforcement/index.js

@@ -0,0 +1,41 @@
+/**
+ * Rule Enforcement Module
+ *
+ * This module provides rule enforcement capabilities for the 0xRay framework.
+ * It validates code against development rules and codex compliance requirements.
+ *
+ * @module enforcement
+ * @version 1.0.0
+ *
+ * @example
+ * ```typescript
+ * import { RuleEnforcer, RuleDefinition, ValidationReport } from './enforcement/index.js';
+ *
+ * const enforcer = new RuleEnforcer();
+ * const report = await enforcer.validateOperation('write', context);
+ * ```
+ */
+// Core enforcer
+export { RuleEnforcer } from "./rule-enforcer.js";
+// Core components (Phase 5 refactoring)
+export { RuleRegistry, RuleHierarchy, RuleExecutor, ViolationFixer, } from "./core/index.js";
+// All types
+export { isRuleValidationResult, } from "./types.js";
+// Validators (Phase 3 refactoring)
+export { 
+// Base class
+BaseValidator, 
+// Registry
+ValidatorRegistry, globalValidatorRegistry, 
+// Code quality validators
+NoDuplicateCodeValidator, ContextAnalysisIntegrationValidator, MemoryOptimizationValidator, DocumentationRequiredValidator, NoOverEngineeringValidator, CleanDebugLogsValidator, ConsoleLogUsageValidator, } from "./validators/index.js";
+// Loaders (Phase 4 refactoring)
+export { 
+// Base loader
+BaseLoader, 
+// Concrete loaders
+CodexLoader, AgentTriageLoader, ProcessorLoader, AgentsMdValidationLoader, 
+// Orchestrator
+LoaderOrchestrator, } from "./loaders/index.js";
+// Enforcer tools (if any exports exist)
+export * as enforcerTools from "./enforcer-tools.js";

package/dist/enforcement/loaders/agent-triage-loader.js

@@ -0,0 +1,222 @@
+/**
+ * Agent Triage Rule Loader
+ *
+ * Loads agent triage rules from AGENTS.md file.
+ * Extracts triage guidelines and converts them to RuleDefinition objects.
+ *
+ * Phase 4 refactoring: Extracted from RuleEnforcer.loadAgentTriageRules()
+ *
+ * @module loaders/agent-triage-loader
+ * @version 1.0.0
+ */
+import { frameworkLogger } from "../../core/framework-logger.js";
+import { BaseLoader } from "./base-loader.js";
+/**
+ * Loader for agent triage rules from AGENTS.md.
+ * Parses the markdown file to extract triage guidelines.
+ *
+ * @example
+ * ```typescript
+ * const loader = new AgentTriageLoader();
+ * if (await loader.isAvailable()) {
+ *   const rules = await loader.load();
+ *   console.log(`Loaded ${rules.length} triage rules`);
+ * }
+ * ```
+ */
+export class AgentTriageLoader extends BaseLoader {
+    name = "agent-triage";
+    /**
+     * Path to the AGENTS.md file.
+     */
+    get agentsPath() {
+        return this.resolvePath("AGENTS.md");
+    }
+    /**
+     * Check if AGENTS.md exists.
+     * @returns Promise resolving to true if AGENTS.md is available
+     */
+    async isAvailable() {
+        return this.fileExists(this.agentsPath);
+    }
+    /**
+     * Load agent triage rules from AGENTS.md.
+     * @returns Promise resolving to array of rule definitions
+     */
+    async load() {
+        const rules = [];
+        try {
+            const content = await this.readFile(this.agentsPath);
+            // Extract triage guidelines from AGENTS.md
+            const triageSection = this.extractTriageSection(content);
+            if (triageSection) {
+                // Create triage commit status reporting rule
+                rules.push(this.createTriageCommitStatusRule());
+                // Create additional triage rules based on AGENTS.md content
+                const additionalRules = this.extractAdditionalRules(content);
+                rules.push(...additionalRules);
+                await frameworkLogger.log("agent-triage-loader", "loaded-triage-rules", "success", {
+                    message: `Loaded ${rules.length} agent triage rules`,
+                    ruleCount: rules.length,
+                });
+            }
+        }
+        catch (error) {
+            await frameworkLogger.log("agent-triage-loader", "failed-to-load-triage", "error", {
+                message: `Failed to load agent triage rules: ${error instanceof Error ? error.message : String(error)}`,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+        return rules;
+    }
+    /**
+     * Extract the triage section from AGENTS.md content.
+     * @param content - Full content of AGENTS.md
+     * @returns Triage section content or null if not found
+     */
+    extractTriageSection(content) {
+        // Look for triage-related sections
+        const triagePatterns = [
+            /### Triage Summary Guidelines([\s\S]*?)(?=###|$)/,
+            /### Agent Triage([\s\S]*?)(?=###|$)/,
+            /### Triage([\s\S]*?)(?=###|$)/,
+            /## Triage([\s\S]*?)(?=##|$)/,
+        ];
+        for (const pattern of triagePatterns) {
+            const match = content.match(pattern);
+            if (match && match[1]) {
+                return match[1].trim();
+            }
+        }
+        return null;
+    }
+    /**
+     * Extract additional rules from AGENTS.md content.
+     * @param content - Full content of AGENTS.md
+     * @returns Array of additional rule definitions
+     */
+    extractAdditionalRules(content) {
+        const rules = [];
+        // Check for reflection guidelines
+        if (content.includes("reflection") || content.includes("Reflection")) {
+            rules.push(this.createReflectionGuidelineRule());
+        }
+        // Check for complexity routing
+        if (content.includes("complexity") ||
+            content.includes("routing") ||
+            content.includes("Complexity")) {
+            rules.push(this.createComplexityRoutingRule());
+        }
+        // Check for agent invocation patterns
+        if (content.includes("@") || content.includes("invoke")) {
+            rules.push(this.createAgentInvocationRule());
+        }
+        return rules;
+    }
+    /**
+     * Create the triage commit status reporting rule.
+     * @returns RuleDefinition for triage commit status
+     */
+    createTriageCommitStatusRule() {
+        return {
+            id: "agent-triage-commit-status",
+            name: "Triage Commit Status Reporting",
+            description: "When providing triage summaries after build error resolution or major changes, ALWAYS explicitly state the commit status (successful/failed) to avoid confusion",
+            category: "reporting",
+            severity: "info",
+            enabled: true,
+            validator: this.validateTriageReporting.bind(this),
+        };
+    }
+    /**
+     * Create a reflection guideline rule.
+     * @returns RuleDefinition for reflection guidelines
+     */
+    createReflectionGuidelineRule() {
+        return {
+            id: "agent-triage-reflection-guidelines",
+            name: "Triage Reflection Guidelines",
+            description: "Complex investigations and multi-session work should be documented in deep reflections",
+            category: "reporting",
+            severity: "info",
+            enabled: true,
+            validator: this.validateReflectionGuidelines.bind(this),
+        };
+    }
+    /**
+     * Create a complexity routing rule.
+     * @returns RuleDefinition for complexity routing
+     */
+    createComplexityRoutingRule() {
+        return {
+            id: "agent-triage-complexity-routing",
+            name: "Complexity-Based Agent Routing",
+            description: "Tasks should be routed to appropriate agents based on complexity level",
+            category: "architecture",
+            severity: "info",
+            enabled: true,
+            validator: this.validateComplexityRouting.bind(this),
+        };
+    }
+    /**
+     * Create an agent invocation rule.
+     * @returns RuleDefinition for agent invocation
+     */
+    createAgentInvocationRule() {
+        return {
+            id: "agent-triage-invocation-syntax",
+            name: "Agent Invocation Syntax",
+            description: "Use @agent-name syntax in prompts or code comments to invoke agents",
+            category: "code-quality",
+            severity: "info",
+            enabled: true,
+            validator: this.validateAgentInvocation.bind(this),
+        };
+    }
+    /**
+     * Validate triage reporting requirements.
+     * @param context - Validation context
+     * @returns Validation result
+     */
+    async validateTriageReporting(context) {
+        // This rule validates that triage summaries include commit status
+        // Would be checked during reporting operations
+        return {
+            passed: true,
+            message: "Triage reporting guidelines enforced",
+        };
+    }
+    /**
+     * Validate reflection guidelines.
+     * @param context - Validation context
+     * @returns Validation result
+     */
+    async validateReflectionGuidelines(context) {
+        return {
+            passed: true,
+            message: "Reflection guidelines available",
+        };
+    }
+    /**
+     * Validate complexity routing.
+     * @param context - Validation context
+     * @returns Validation result
+     */
+    async validateComplexityRouting(context) {
+        return {
+            passed: true,
+            message: "Complexity routing guidelines available",
+        };
+    }
+    /**
+     * Validate agent invocation syntax.
+     * @param context - Validation context
+     * @returns Validation result
+     */
+    async validateAgentInvocation(context) {
+        return {
+            passed: true,
+            message: "Agent invocation syntax guidelines available",
+        };
+    }
+}

package/dist/enforcement/loaders/agents-md-validation-loader.js

@@ -0,0 +1,252 @@
+/**
+ * AGENTS.md Validation Rule Loader
+ *
+ * Loads validation rules for AGENTS.md file existence and currency.
+ * Ensures that AGENTS.md exists and is properly maintained.
+ *
+ * Phase 4 refactoring: Extracted from RuleEnforcer.loadAgentsMdValidationRule()
+ *
+ * @module loaders/agents-md-validation-loader
+ * @version 1.0.0
+ */
+import { frameworkLogger } from "../../core/framework-logger.js";
+import { BaseLoader } from "./base-loader.js";
+/**
+ * Loader for AGENTS.md validation rules.
+ * Creates rules that validate AGENTS.md existence and currency.
+ *
+ * @example
+ * ```typescript
+ * const loader = new AgentsMdValidationLoader();
+ * if (await loader.isAvailable()) {
+ *   const rules = await loader.load();
+ *   console.log(`Loaded ${rules.length} AGENTS.md validation rules`);
+ * }
+ * ```
+ */
+export class AgentsMdValidationLoader extends BaseLoader {
+    name = "agents-md-validation";
+    /**
+     * Path to the AGENTS.md file.
+     */
+    get agentsPath() {
+        return this.resolvePath("AGENTS.md");
+    }
+    /**
+     * Check if AGENTS.md exists.
+     * @returns Promise resolving to true if AGENTS.md is available
+     */
+    async isAvailable() {
+        return this.fileExists(this.agentsPath);
+    }
+    /**
+     * Load AGENTS.md validation rules.
+     * @returns Promise resolving to array of rule definitions
+     */
+    async load() {
+        const rules = [];
+        try {
+            // Rule: AGENTS.md must exist
+            rules.push(this.createAgentsMdExistsRule());
+            // Rule: AGENTS.md must be current
+            rules.push(this.createAgentsMdCurrentRule());
+            // Rule: AGENTS.md must have valid structure
+            rules.push(this.createAgentsMdStructureRule());
+            await frameworkLogger.log("agents-md-validation-loader", "loaded-agents-md-rules", "success", {
+                message: `Loaded ${rules.length} AGENTS.md validation rules`,
+                ruleCount: rules.length,
+            });
+        }
+        catch (error) {
+            await frameworkLogger.log("agents-md-validation-loader", "failed-to-load-agents-md-rules", "error", {
+                message: `Failed to load AGENTS.md validation rules: ${error instanceof Error ? error.message : String(error)}`,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+        return rules;
+    }
+    /**
+     * Create AGENTS.md existence rule.
+     * @returns RuleDefinition for AGENTS.md existence
+     */
+    createAgentsMdExistsRule() {
+        return {
+            id: "agents-md-exists",
+            name: "AGENTS.md Must Exist",
+            description: "AGENTS.md is required for agent triage rules, codex compliance, and session management. Projects must maintain an up-to-date AGENTS.md file.",
+            category: "architecture",
+            severity: "blocking",
+            enabled: true,
+            validator: this.validateAgentsMdExists.bind(this),
+        };
+    }
+    /**
+     * Create AGENTS.md currency rule.
+     * @returns RuleDefinition for AGENTS.md currency
+     */
+    createAgentsMdCurrentRule() {
+        return {
+            id: "agents-md-current",
+            name: "AGENTS.md Must Be Current",
+            description: "AGENTS.md should be reviewed and updated regularly (within 30 days) to ensure agent capabilities and rules are accurate.",
+            category: "reporting",
+            severity: "warning",
+            enabled: true,
+            validator: this.validateAgentsMdCurrent.bind(this),
+        };
+    }
+    /**
+     * Create AGENTS.md structure rule.
+     * @returns RuleDefinition for AGENTS.md structure
+     */
+    createAgentsMdStructureRule() {
+        return {
+            id: "agents-md-structure",
+            name: "AGENTS.md Must Have Valid Structure",
+            description: "AGENTS.md must contain required sections including agent list, triage guidelines, and reflection paths.",
+            category: "architecture",
+            severity: "warning",
+            enabled: true,
+            validator: this.validateAgentsMdStructure.bind(this),
+        };
+    }
+    /**
+     * Validate that AGENTS.md exists.
+     * @param context - Validation context
+     * @returns Validation result
+     */
+    async validateAgentsMdExists(context) {
+        try {
+            const exists = await this.fileExists(this.agentsPath);
+            if (!exists) {
+                const fixes = [
+                    {
+                        type: "run-command",
+                        description: "Auto-generate AGENTS.md from template",
+                        command: "node scripts/node/enforce-agents-md.js --generate",
+                    },
+                ];
+                return {
+                    passed: false,
+                    message: "AGENTS.md not found in project root",
+                    suggestions: [
+                        "Create AGENTS.md using template from docs/AGENTS_TEMPLATE.md",
+                        "Run: node scripts/node/enforce-agents-md.js --generate",
+                        "See AGENTS.md for agent triage rules and codex compliance",
+                    ],
+                    fixes,
+                };
+            }
+            return {
+                passed: true,
+                message: "AGENTS.md exists",
+            };
+        }
+        catch (error) {
+            return {
+                passed: false,
+                message: `Error checking AGENTS.md: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    /**
+     * Validate that AGENTS.md is current (updated within 30 days).
+     * @param context - Validation context
+     * @returns Validation result
+     */
+    async validateAgentsMdCurrent(context) {
+        try {
+            const exists = await this.fileExists(this.agentsPath);
+            if (!exists) {
+                return {
+                    passed: true,
+                    message: "AGENTS.md check skipped (file does not exist)",
+                };
+            }
+            const content = await this.readFile(this.agentsPath);
+            const dateMatch = content.match(/\*\*Updated\*\*:\s*(\d{4}-\d{2}-\d{2})/);
+            if (!dateMatch || !dateMatch[1]) {
+                return {
+                    passed: false,
+                    severity: "warning",
+                    message: "AGENTS.md missing date stamp",
+                    suggestions: ["Add '**Updated**: YYYY-MM-DD' to AGENTS.md header"],
+                };
+            }
+            const updateDate = new Date(dateMatch[1]);
+            const daysSinceUpdate = Math.floor((Date.now() - updateDate.getTime()) / (1000 * 60 * 60 * 24));
+            if (daysSinceUpdate > 30) {
+                return {
+                    passed: false,
+                    message: `AGENTS.md is ${daysSinceUpdate} days old (recommended: review every 30 days)`,
+                    suggestions: [
+                        "Review and update AGENTS.md to reflect current agent capabilities",
+                        "Update the date stamp to today's date",
+                    ],
+                };
+            }
+            return {
+                passed: true,
+                message: `AGENTS.md is current (${daysSinceUpdate} days old)`,
+            };
+        }
+        catch (error) {
+            return {
+                passed: false,
+                message: `Error checking AGENTS.md date: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    /**
+     * Validate AGENTS.md structure.
+     * @param context - Validation context
+     * @returns Validation result
+     */
+    async validateAgentsMdStructure(context) {
+        try {
+            const exists = await this.fileExists(this.agentsPath);
+            if (!exists) {
+                return {
+                    passed: true,
+                    message: "AGENTS.md structure check skipped (file does not exist)",
+                };
+            }
+            const content = await this.readFile(this.agentsPath);
+            const missingSections = [];
+            // Check for required sections
+            if (!content.includes("# 0xRay Agents")) {
+                missingSections.push("Main title (0xRay Agents)");
+            }
+            if (!content.includes("Available Agents")) {
+                missingSections.push("Available Agents section");
+            }
+            if (!content.includes("Triage") && !content.includes("triage")) {
+                missingSections.push("Triage guidelines section");
+            }
+            if (!content.includes("reflection") &&
+                !content.includes("Reflection")) {
+                missingSections.push("Reflection guidelines section");
+            }
+            if (missingSections.length > 0) {
+                return {
+                    passed: false,
+                    message: `AGENTS.md missing required sections: ${missingSections.join(", ")}`,
+                    suggestions: [
+                        "Add missing sections to AGENTS.md",
+                        "Reference docs/AGENTS_TEMPLATE.md for structure",
+                    ],
+                };
+            }
+            return {
+                passed: true,
+                message: "AGENTS.md has valid structure",
+            };
+        }
+        catch (error) {
+            return {
+                passed: false,
+                message: `Error checking AGENTS.md structure: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+}

package/dist/enforcement/loaders/base-loader.js

@@ -0,0 +1,86 @@
+/**
+ * Base Rule Loader
+ *
+ * Abstract base class for all rule loaders. Provides common functionality
+ * for loading rules from various sources such as files, APIs, or databases.
+ *
+ * Phase 4 refactoring: Extracted from RuleEnforcer to separate loading logic
+ * from rule execution.
+ *
+ * @module loaders/base-loader
+ * @version 1.0.0
+ */
+import * as fs from "fs";
+import * as path from "path";
+/**
+ * Abstract base class implementing IRuleLoader interface.
+ * Provides common file loading utilities and error handling.
+ *
+ * @example
+ * ```typescript
+ * class MyLoader extends BaseLoader {
+ *   readonly name = 'my-loader';
+ *
+ *   async load(): Promise<RuleDefinition[]> {
+ *     const data = await this.loadJsonFile('rules.json');
+ *     return this.transformToRules(data);
+ *   }
+ *
+ *   async isAvailable(): Promise<boolean> {
+ *     return this.fileExists('rules.json');
+ *   }
+ * }
+ * ```
+ */
+export class BaseLoader {
+    /**
+     * Load and parse a JSON file.
+     * @param filePath - Path to the JSON file
+     * @returns Promise resolving to parsed JSON data
+     * @throws Error if file cannot be read or parsed
+     */
+    async loadJsonFile(filePath) {
+        const content = await fs.promises.readFile(filePath, "utf8");
+        return JSON.parse(content);
+    }
+    /**
+     * Check if a file exists.
+     * @param filePath - Path to check
+     * @returns Promise resolving to true if file exists
+     */
+    async fileExists(filePath) {
+        try {
+            await fs.promises.access(filePath, fs.constants.F_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Read file content as string.
+     * @param filePath - Path to the file
+     * @returns Promise resolving to file content
+     * @throws Error if file cannot be read
+     */
+    async readFile(filePath) {
+        return fs.promises.readFile(filePath, "utf8");
+    }
+    /**
+     * Resolve a path relative to the current working directory.
+     * @param relativePath - Path relative to process.cwd()
+     * @returns Absolute path
+     */
+    resolvePath(relativePath) {
+        return path.join(process.cwd(), relativePath);
+    }
+    /**
+     * Get file stats.
+     * @param filePath - Path to the file
+     * @returns Promise resolving to file stats
+     * @throws Error if file cannot be accessed
+     */
+    async getFileStats(filePath) {
+        return fs.promises.stat(filePath);
+    }
+}