0xray 4.0.13 → 4.0.14

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

@@ -0,0 +1,251 @@
+/**
+ * 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
+ */
+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.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 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
+ */
+import * as fs from "fs";
+import { IRuleLoader, RuleDefinition } from "../types.js";
+/**
+ * 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 declare abstract class BaseLoader implements IRuleLoader {
+    /** Unique name identifier for this loader */
+    abstract readonly name: string;
+    /**
+     * Load rules from the source.
+     * Must be implemented by concrete loader classes.
+     * @returns Promise resolving to array of rule definitions
+     */
+    abstract load(): Promise<RuleDefinition[]>;
+    /**
+     * Check if this loader's source is available.
+     * Must be implemented by concrete loader classes.
+     * @returns Promise resolving to true if source exists and is accessible
+     */
+    abstract isAvailable(): Promise<boolean>;
+    /**
+     * 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
+     */
+    protected loadJsonFile<T = unknown>(filePath: string): Promise<T>;
+    /**
+     * Check if a file exists.
+     * @param filePath - Path to check
+     * @returns Promise resolving to true if file exists
+     */
+    protected fileExists(filePath: string): Promise<boolean>;
+    /**
+     * Read file content as string.
+     * @param filePath - Path to the file
+     * @returns Promise resolving to file content
+     * @throws Error if file cannot be read
+     */
+    protected readFile(filePath: string): Promise<string>;
+    /**
+     * Resolve a path relative to the current working directory.
+     * @param relativePath - Path relative to process.cwd()
+     * @returns Absolute path
+     */
+    protected resolvePath(relativePath: string): string;
+    /**
+     * Get file stats.
+     * @param filePath - Path to the file
+     * @returns Promise resolving to file stats
+     * @throws Error if file cannot be accessed
+     */
+    protected getFileStats(filePath: string): Promise<fs.Stats>;
+}

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

@@ -0,0 +1,85 @@
+/**
+ * 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
+ */
+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);
+    }
+}

package/dist/enforcement/loaders/codex-loader.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Codex Rule Loader
+ *
+ * Loads codex terms from the resolved codex path and converts them
+ * to RuleDefinition objects for the rule enforcement system.
+ *
+ * Phase 4 refactoring: Extracted from RuleEnforcer.loadCodexRules()
+ *
+ * @module loaders/codex-loader
+ */
+import { BaseLoader } from "./base-loader.js";
+import { RuleDefinition } from "../types.js";
+/**
+ * Loader for codex terms from codex.json.
+ * Converts codex terms to RuleDefinition objects.
+ *
+ * @example
+ * ```typescript
+ * const loader = new CodexLoader();
+ * if (await loader.isAvailable()) {
+ *   const rules = await loader.load();
+ *   console.log(`Loaded ${rules.length} codex rules`);
+ * }
+ * ```
+ */
+export declare class CodexLoader extends BaseLoader {
+    readonly name = "codex";
+    /**
+     * Path to the codex.json file.
+      * Uses the standard config-paths resolver which checks .xray/, etc.
+     */
+    private get codexPath();
+    /**
+     * Check if codex.json exists.
+     * @returns Promise resolving to true if codex.json is available
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Load codex terms and convert to RuleDefinition objects.
+     * @returns Promise resolving to array of rule definitions
+     */
+    load(): Promise<RuleDefinition[]>;
+    /**
+     * Type guard to check if an object is a valid CodexTerm.
+     * @param term - Object to validate
+     * @returns True if the object is a valid CodexTerm
+     */
+    private isValidCodexTerm;
+    /**
+     * Convert a codex term to a RuleDefinition.
+     * @param key - Term key (number as string)
+     * @param term - Codex term data
+     * @returns RuleDefinition object
+     */
+    private convertTermToRule;
+    /**
+     * Map codex category to RuleCategory.
+     * @param category - Codex category string
+     * @returns Mapped RuleCategory
+     */
+    private mapCodexCategory;
+    /**
+     * Map codex severity to RuleSeverity.
+     * @param enforcementLevel - Codex enforcement level
+     * @param zeroTolerance - Whether term has zero tolerance
+     * @returns Mapped RuleSeverity
+     */
+    private mapCodexSeverity;
+    /**
+     * Create a validator function for a codex term.
+     * Now actually validates code against the term requirements.
+     * @param term - Codex term data
+     * @returns Validator function that performs real validation
+     */
+    private createCodexValidator;
+}