0xray 3.4.1 → 3.4.3

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

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

package/dist/enforcement/loaders/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Rule Loaders Module
+ *
+ * This module provides rule loading capabilities for the 0xRay framework.
+ * Loaders encapsulate the logic for loading rules from various sources.
+ *
+ * Phase 4 refactoring: Extracted async rule loading from RuleEnforcer
+ *
+ * @module loaders
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   LoaderOrchestrator,
+ *   CodexLoader,
+ *   AgentTriageLoader,
+ *   IRuleLoader
+ * } from './enforcement/loaders/index.js';
+ *
+ * // Use the orchestrator to load all rules
+ * const orchestrator = new LoaderOrchestrator();
+ * const result = await orchestrator.loadAllRules();
+ *
+ * // Or use individual loaders
+ * const codexLoader = new CodexLoader();
+ * if (await codexLoader.isAvailable()) {
+ *   const codexRules = await codexLoader.load();
+ * }
+ * ```
+ */
+export { BaseLoader } from "./base-loader.js";
+export { CodexLoader } from "./codex-loader.js";
+export { AgentTriageLoader } from "./agent-triage-loader.js";
+export { ProcessorLoader } from "./processor-loader.js";
+export { AgentsMdValidationLoader } from "./agents-md-validation-loader.js";
+export { LoaderOrchestrator, type LoaderOrchestratorOptions, type LoaderOrchestratorResult, } from "./loader-orchestrator.js";

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

@@ -0,0 +1,96 @@
+/**
+ * Loader Orchestrator
+ *
+ * Coordinates multiple rule loaders to load rules from various sources.
+ * Manages loader execution, error handling, and rule aggregation.
+ *
+ * Phase 4 refactoring: Extracted loader orchestration from RuleEnforcer
+ *
+ * @module loaders/loader-orchestrator
+ */
+import { IRuleLoader, RuleDefinition } from "../types.js";
+/**
+ * Options for LoaderOrchestrator configuration.
+ */
+export interface LoaderOrchestratorOptions {
+    /** Whether to continue loading if one loader fails */
+    continueOnError?: boolean;
+    /** Whether to log loader activity */
+    enableLogging?: boolean;
+}
+/**
+ * Result from the orchestrator's load operation.
+ */
+export interface LoaderOrchestratorResult {
+    /** All loaded rules */
+    rules: RuleDefinition[];
+    /** Number of successful loaders */
+    successfulLoaders: number;
+    /** Number of failed loaders */
+    failedLoaders: number;
+    /** Loader-specific results */
+    loaderResults: Map<string, {
+        success: boolean;
+        ruleCount: number;
+        error?: string;
+    }>;
+}
+/**
+ * Orchestrates multiple rule loaders to load rules from various sources.
+ *
+ * @example
+ * ```typescript
+ * const orchestrator = new LoaderOrchestrator();
+ * const result = await orchestrator.loadAllRules();
+ * console.log(`Loaded ${result.rules.length} rules from ${result.successfulLoaders} loaders`);
+ * ```
+ */
+export declare class LoaderOrchestrator {
+    private loaders;
+    private options;
+    /**
+     * Create a new LoaderOrchestrator.
+     * @param options - Configuration options
+     */
+    constructor(options?: LoaderOrchestratorOptions);
+    /**
+     * Register the default set of loaders.
+     */
+    private registerDefaultLoaders;
+    /**
+     * Load all rules from all available loaders.
+     * @returns Promise resolving to orchestrator result
+     */
+    loadAllRules(): Promise<LoaderOrchestratorResult>;
+    /**
+     * Register a custom loader.
+     * @param loader - Loader to register
+     */
+    registerLoader(loader: IRuleLoader): void;
+    /**
+     * Get all registered loaders.
+     * @returns Array of registered loaders
+     */
+    getLoaders(): IRuleLoader[];
+    /**
+     * Get loader by name.
+     * @param name - Loader name
+     * @returns Loader instance or undefined
+     */
+    getLoader(name: string): IRuleLoader | undefined;
+    /**
+     * Remove a loader by name.
+     * @param name - Loader name
+     * @returns True if loader was removed
+     */
+    removeLoader(name: string): boolean;
+    /**
+     * Clear all registered loaders.
+     */
+    clearLoaders(): void;
+    /**
+     * Get count of registered loaders.
+     * @returns Number of loaders
+     */
+    getLoaderCount(): number;
+}