0xray 3.4.2 → 3.4.4

package/dist/enforcement/core/rule-registry.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Rule Registry - Storage and management for validation rules
+ *
+ * This class separates rule storage concerns from rule execution.
+ * It provides a centralized registry for adding, retrieving, and
+ * managing rule definitions with lifecycle operations.
+ *
+ * @module enforcement/core
+ *
+ * @example
+ * ```typescript
+ * const registry = new RuleRegistry();
+ * registry.addRule({
+ *   id: "no-console",
+ *   name: "No Console Logs",
+ *   description: "Prevents console.log usage",
+ *   category: "code-quality",
+ *   severity: "warning",
+ *   enabled: true,
+ *   validator: async (ctx) => ({ passed: true, message: "OK" })
+ * });
+ * ```
+ */
+import { RuleDefinition, IRuleRegistry } from "../types.js";
+/**
+ * RuleRegistry provides storage and lifecycle management for validation rules.
+ *
+ * This class implements the IRuleRegistry interface and encapsulates
+ * all rule storage logic, keeping the RuleEnforcer focused on execution.
+ *
+ * Key responsibilities:
+ * - Rule storage and retrieval
+ * - Enable/disable rule state management
+ * - Rule statistics and metadata
+ * - Rule lifecycle operations (add, remove, clear)
+ */
+export declare class RuleRegistry implements IRuleRegistry {
+    /** Internal storage for rules */
+    private rules;
+    /**
+     * Add a rule to the registry.
+     *
+     * @param rule - The rule definition to add
+     * @throws Error if a rule with the same ID already exists
+     *
+     * @example
+     * ```typescript
+     * registry.addRule({
+     *   id: "no-console",
+     *   name: "No Console Logs",
+     *   description: "Prevents console.log usage",
+     *   category: "code-quality",
+     *   severity: "warning",
+     *   enabled: true,
+     *   validator: async (ctx) => ({ passed: true, message: "OK" })
+     * });
+     * ```
+     */
+    addRule(rule: RuleDefinition): void;
+    /**
+     * Get all loaded rules as an array.
+     *
+     * @returns Array of all rule definitions
+     *
+     * @example
+     * ```typescript
+     * const allRules = registry.getRules();
+     * console.log(`Loaded ${allRules.length} rules`);
+     * ```
+     */
+    getRules(): RuleDefinition[];
+    /**
+     * Get a specific rule by its ID.
+     *
+     * @param ruleId - The unique identifier of the rule
+     * @returns The rule definition or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const rule = registry.getRule("no-console");
+     * if (rule) {
+     *   console.log(rule.name);
+     * }
+     * ```
+     */
+    getRule(ruleId: string): RuleDefinition | undefined;
+    /**
+     * Enable a rule by its ID.
+     *
+     * @param ruleId - The unique identifier of the rule to enable
+     * @returns true if the rule was found and enabled, false if not found
+     *
+     * @example
+     * ```typescript
+     * if (registry.enableRule("no-console")) {
+     *   console.log("Rule enabled successfully");
+     * }
+     * ```
+     */
+    enableRule(ruleId: string): boolean;
+    /**
+     * Disable a rule by its ID.
+     *
+     * @param ruleId - The unique identifier of the rule to disable
+     * @returns true if the rule was found and disabled, false if not found
+     *
+     * @example
+     * ```typescript
+     * if (registry.disableRule("no-console")) {
+     *   console.log("Rule disabled successfully");
+     * }
+     * ```
+     */
+    disableRule(ruleId: string): boolean;
+    /**
+     * Check if a rule is enabled.
+     *
+     * @param ruleId - The unique identifier of the rule
+     * @returns true if the rule exists and is enabled, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (registry.isRuleEnabled("no-console")) {
+     *   // Rule is active
+     * }
+     * ```
+     */
+    isRuleEnabled(ruleId: string): boolean;
+    /**
+     * Get the total count of rules in the registry.
+     *
+     * @returns The number of rules stored
+     *
+     * @example
+     * ```typescript
+     * console.log(`Registry contains ${registry.getRuleCount()} rules`);
+     * ```
+     */
+    getRuleCount(): number;
+    /**
+     * Get comprehensive statistics about rules in the registry.
+     *
+     * @returns Statistics including total, enabled, disabled counts and category breakdown
+     *
+     * @example
+     * ```typescript
+     * const stats = registry.getRuleStats();
+     * console.log(`Enabled: ${stats.enabledRules}/${stats.totalRules}`);
+     * console.log("By category:", stats.ruleCategories);
+     * ```
+     */
+    getRuleStats(): {
+        totalRules: number;
+        enabledRules: number;
+        disabledRules: number;
+        ruleCategories: Record<string, number>;
+    };
+    /**
+     * Check if a rule exists in the registry.
+     *
+     * @param ruleId - The unique identifier of the rule
+     * @returns true if the rule exists, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (registry.hasRule("no-console")) {
+     *   // Rule exists
+     * }
+     * ```
+     */
+    hasRule(ruleId: string): boolean;
+    /**
+     * Remove a rule from the registry.
+     *
+     * @param ruleId - The unique identifier of the rule to remove
+     * @returns true if the rule was found and removed, false if not found
+     *
+     * @example
+     * ```typescript
+     * if (registry.removeRule("no-console")) {
+     *   console.log("Rule removed successfully");
+     * }
+     * ```
+     */
+    removeRule(ruleId: string): boolean;
+    /**
+     * Clear all rules from the registry.
+     *
+     * @example
+     * ```typescript
+     * registry.clearRules();
+     * console.log(`Registry cleared. Count: ${registry.getRuleCount()}`);
+     * ```
+     */
+    clearRules(): void;
+}

package/dist/enforcement/core/violation-fixer.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Violation Fixer - Handle violation fixes via agent delegation
+ *
+ * This class maps rule violations to appropriate agents/skills and attempts
+ * automatic fixes. It serves as the central governance point for all
+ * violation remediation in the 0xRay framework.
+ *
+ * Phase 5 refactoring: Extracted from RuleEnforcer.
+ *
+ * @module enforcement/core
+ *
+ * @example
+ * ```typescript
+ * const fixer = new ViolationFixer();
+ *
+ * // Register a custom fix strategy
+ * fixer.registerFixStrategy('my-rule', {
+ *   agent: 'refactorer',
+ *   skill: 'code-review',
+ *   tool: 'analyze_code_quality',
+ *   priority: 1
+ * });
+ *
+ * // Fix violations
+ * const fixes = await fixer.fixViolations(violations, context);
+ * ```
+ */
+import { IViolationFixer, Violation, ViolationFix, FixStrategy, RuleValidationContext } from '../types.js';
+/**
+ * ViolationFixer handles violation fixes by delegating to appropriate agents/skills.
+ *
+ * Key responsibilities:
+ * - Map violations to agents/skills
+ * - Attempt automatic fixes via MCP skill invocation
+ * - Track fix success/failure
+ * - Handle fix strategies
+ *
+ * This is the central governance point for all codex compliance actions.
+ */
+export declare class ViolationFixer implements IViolationFixer {
+    /** Map of rule IDs to their fix strategies */
+    private fixStrategies;
+    /** Default tool mapping for skills */
+    private toolMappings;
+    constructor();
+    /**
+     * Attempt to fix violations by delegating to appropriate agents/skills.
+     *
+     * For each violation:
+     * - Finds the appropriate agent/skill mapping
+     * - Invokes the skill via MCP
+     * - Tracks the result
+     *
+     * @param violations - Array of violations to fix
+     * @param context - Validation context with code and operation info
+     * @returns Array of fix attempts with results
+     *
+     * @example
+     * ```typescript
+     * const violations = [{ rule: 'no-duplicate-code', message: 'Duplicate detected' }];
+     * const fixes = await fixer.fixViolations(violations, context);
+     * console.log(fixes[0].success); // true if fix succeeded
+     * ```
+     */
+    fixViolations(violations: Violation[], context: RuleValidationContext): Promise<ViolationFix[]>;
+    /**
+     * Register a custom fix strategy for a rule.
+     *
+     * @param ruleId - The rule ID to register the strategy for
+     * @param strategy - The fix strategy configuration
+     *
+     * @example
+     * ```typescript
+     * fixer.registerFixStrategy('custom-rule', {
+     *   agent: 'refactorer',
+     *   skill: 'code-review',
+     *   tool: 'analyze_code_quality',
+     *   priority: 1
+     * });
+     * ```
+     */
+    registerFixStrategy(ruleId: string, strategy: FixStrategy): void;
+    /**
+     * Get the fix strategy for a rule.
+     *
+     * @param ruleId - The rule ID to get the strategy for
+     * @returns The fix strategy or undefined if not found
+     */
+    getFixStrategy(ruleId: string): FixStrategy | undefined;
+    /**
+     * Get the appropriate tool name for a skill.
+     * Uses internal tool mappings or defaults to analyze_code_quality.
+     *
+     * @param skill - The skill name
+     * @returns The tool name to use
+     */
+    private getToolForSkill;
+    /**
+     * Initialize default fix strategies for all known rules.
+     * This maps rule IDs to their corresponding agents/skills.
+     *
+     * Central governance mapping for all codex compliance actions.
+     */
+    private initializeFixStrategies;
+}

package/dist/enforcement/enforcer-tools.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Enforcer Tools - Integration layer between enforcer agent and rule enforcement system
+ * Provides tools for codex compliance, rule validation, and contextual analysis enforcement
+ */
+import { RuleValidationContext, ValidationReport } from "./rule-enforcer.js";
+export interface RoutingRecommendation {
+    suggestedAgent: string;
+    suggestedSkill: string;
+    confidence: number;
+    matchedKeyword?: string;
+}
+export declare function getTaskRoutingRecommendation(taskDescription: string): RoutingRecommendation;
+/**
+ * Pre-process and validate that the routing is appropriate for the operation
+ * This is the integration point between TaskSkillRouter and RuleEnforcer
+ */
+export declare function preProcessAndRoute(operation: string, context: RuleValidationContext): Promise<{
+    enhancedContext: RuleValidationContext;
+    routing: RoutingRecommendation;
+}>;
+export interface EnforcementResult {
+    operation: string;
+    passed: boolean;
+    blocked: boolean;
+    errors: string[];
+    warnings: string[];
+    fixes: Array<{
+        type: "auto" | "manual";
+        description: string;
+        action?: () => Promise<void>;
+    }>;
+    report: ValidationReport;
+}
+/**
+ * Rule Validation Tool - Validates operations against rule hierarchy
+ * Now with intelligent task routing via TaskSkillRouter
+ * Automatically delegates to best agent when confidence is high
+ */
+export declare function ruleValidation(operation: string, context: RuleValidationContext): Promise<EnforcementResult>;
+/**
+ * Context Analysis Validation Tool - Validates contextual analysis integration
+ */
+export declare function contextAnalysisValidation(files: string[], operation: string): Promise<EnforcementResult>;
+/**
+ * Codex Enforcement Tool - Comprehensive codex compliance validation
+ */
+export declare function codexEnforcement(operation: string, files: string[], newCode?: string): Promise<EnforcementResult>;
+/**
+ * Quality Gate Check Tool - Final validation before commit/execution
+ */
+export declare function qualityGateCheck(operation: string, context: {
+    files: string[];
+    newCode?: string;
+    tests?: string[];
+    dependencies?: string[];
+}): Promise<EnforcementResult>;
+/**
+ * Get comprehensive enforcement status
+ */
+export declare function getEnforcementStatus(): Promise<{
+    rules: number;
+    validations: number;
+    violations: number;
+    fixes: number;
+    success: boolean;
+}>;
+/**
+ * Run comprehensive pre-commit validation
+ */
+export declare function runPreCommitValidation(files: string[], operation?: string): Promise<EnforcementResult>;
+export declare const enforcerTools: {
+    ruleValidation: typeof ruleValidation;
+    contextAnalysisValidation: typeof contextAnalysisValidation;
+    codexEnforcement: typeof codexEnforcement;
+    qualityGateCheck: typeof qualityGateCheck;
+    getEnforcementStatus: typeof getEnforcementStatus;
+    runPreCommitValidation: typeof runPreCommitValidation;
+};

package/dist/enforcement/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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
+ *
+ * @example
+ * ```typescript
+ * import { RuleEnforcer, RuleDefinition, ValidationReport } from './enforcement/index.js';
+ *
+ * const enforcer = new RuleEnforcer();
+ * const report = await enforcer.validateOperation('write', context);
+ * ```
+ */
+export { RuleEnforcer } from "./rule-enforcer.js";
+export { RuleRegistry, RuleHierarchy, RuleExecutor, ViolationFixer, } from "./core/index.js";
+export { RuleDefinition, RuleValidationContext, RuleValidationResult, ValidationReport, Violation, ViolationFix, RuleFix, RuleCategory, RuleSeverity, RuleFixType, IRuleRegistry, IValidator, IValidatorRegistry, IRuleHierarchy, IRuleExecutor, IViolationFixer, ExecutionOptions, BatchExecutionOptions, FixStrategy, isRuleValidationResult, } from "./types.js";
+export { BaseValidator, ValidatorRegistry, globalValidatorRegistry, NoDuplicateCodeValidator, ContextAnalysisIntegrationValidator, MemoryOptimizationValidator, DocumentationRequiredValidator, NoOverEngineeringValidator, CleanDebugLogsValidator, ConsoleLogUsageValidator, } from "./validators/index.js";
+export { BaseLoader, CodexLoader, AgentTriageLoader, ProcessorLoader, AgentsMdValidationLoader, LoaderOrchestrator, type LoaderOrchestratorOptions, type LoaderOrchestratorResult, } from "./loaders/index.js";
+export * as enforcerTools from "./enforcer-tools.js";

package/dist/enforcement/loaders/agent-triage-loader.d.ts

@@ -0,0 +1,98 @@
+/**
+ * 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
+ */
+import { BaseLoader } from "./base-loader.js";
+import { RuleDefinition } from "../types.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 declare class AgentTriageLoader extends BaseLoader {
+    readonly name = "agent-triage";
+    /**
+     * Path to the AGENTS.md file.
+     */
+    private get agentsPath();
+    /**
+     * Check if AGENTS.md exists.
+     * @returns Promise resolving to true if AGENTS.md is available
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Load agent triage rules from AGENTS.md.
+     * @returns Promise resolving to array of rule definitions
+     */
+    load(): Promise<RuleDefinition[]>;
+    /**
+     * Extract the triage section from AGENTS.md content.
+     * @param content - Full content of AGENTS.md
+     * @returns Triage section content or null if not found
+     */
+    private extractTriageSection;
+    /**
+     * Extract additional rules from AGENTS.md content.
+     * @param content - Full content of AGENTS.md
+     * @returns Array of additional rule definitions
+     */
+    private extractAdditionalRules;
+    /**
+     * Create the triage commit status reporting rule.
+     * @returns RuleDefinition for triage commit status
+     */
+    private createTriageCommitStatusRule;
+    /**
+     * Create a reflection guideline rule.
+     * @returns RuleDefinition for reflection guidelines
+     */
+    private createReflectionGuidelineRule;
+    /**
+     * Create a complexity routing rule.
+     * @returns RuleDefinition for complexity routing
+     */
+    private createComplexityRoutingRule;
+    /**
+     * Create an agent invocation rule.
+     * @returns RuleDefinition for agent invocation
+     */
+    private createAgentInvocationRule;
+    /**
+     * Validate triage reporting requirements.
+     * @param context - Validation context
+     * @returns Validation result
+     */
+    private validateTriageReporting;
+    /**
+     * Validate reflection guidelines.
+     * @param context - Validation context
+     * @returns Validation result
+     */
+    private validateReflectionGuidelines;
+    /**
+     * Validate complexity routing.
+     * @param context - Validation context
+     * @returns Validation result
+     */
+    private validateComplexityRouting;
+    /**
+     * Validate agent invocation syntax.
+     * @param context - Validation context
+     * @returns Validation result
+     */
+    private validateAgentInvocation;
+}

package/dist/enforcement/loaders/agents-md-validation-loader.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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 { BaseLoader } from "./base-loader.js";
+import { RuleDefinition } from "../types.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 declare class AgentsMdValidationLoader extends BaseLoader {
+    readonly name = "agents-md-validation";
+    /**
+     * Path to the AGENTS.md file.
+     */
+    private get agentsPath();
+    /**
+     * Check if AGENTS.md exists.
+     * @returns Promise resolving to true if AGENTS.md is available
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Load AGENTS.md validation rules.
+     * @returns Promise resolving to array of rule definitions
+     */
+    load(): Promise<RuleDefinition[]>;
+    /**
+     * Create AGENTS.md existence rule.
+     * @returns RuleDefinition for AGENTS.md existence
+     */
+    private createAgentsMdExistsRule;
+    /**
+     * Create AGENTS.md currency rule.
+     * @returns RuleDefinition for AGENTS.md currency
+     */
+    private createAgentsMdCurrentRule;
+    /**
+     * Create AGENTS.md structure rule.
+     * @returns RuleDefinition for AGENTS.md structure
+     */
+    private createAgentsMdStructureRule;
+    /**
+     * Validate that AGENTS.md exists.
+     * @param context - Validation context
+     * @returns Validation result
+     */
+    private validateAgentsMdExists;
+    /**
+     * Validate that AGENTS.md is current (updated within 30 days).
+     * @param context - Validation context
+     * @returns Validation result
+     */
+    private validateAgentsMdCurrent;
+    /**
+     * Validate AGENTS.md structure.
+     * @param context - Validation context
+     * @returns Validation result
+     */
+    private validateAgentsMdStructure;
+}

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>;
+}