0xray 2.0.0 → 2.1.0

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

@@ -0,0 +1,146 @@
+/**
+ * Rule Hierarchy - Manage rule dependencies and execution order
+ *
+ * This class manages rule dependencies and calculates execution order.
+ * It uses topological sorting to ensure dependencies are validated before dependents.
+ *
+ * Phase 5 refactoring: Extracted from RuleEnforcer.
+ *
+ * @module enforcement/core
+ * @version 1.0.0
+ *
+ * @example
+ * ```typescript
+ * const hierarchy = new RuleHierarchy();
+ * hierarchy.addDependency('tests-required', ['no-duplicate-code']);
+ * hierarchy.addDependency('memory-optimization', ['context-analysis-integration']);
+ *
+ * const order = hierarchy.getExecutionOrder(['tests-required', 'memory-optimization']);
+ * // Result: ['no-duplicate-code', 'tests-required', 'context-analysis-integration', 'memory-optimization']
+ * ```
+ */
+import { IRuleHierarchy } from '../types.js';
+/**
+ * RuleHierarchy manages rule dependency relationships and execution ordering.
+ *
+ * Key responsibilities:
+ * - Track rule dependencies (A depends on B)
+ * - Calculate execution order via topological sort
+ * - Detect circular dependencies
+ * - Check dependency satisfaction
+ */
+export declare class RuleHierarchy implements IRuleHierarchy {
+    /** Map of rule IDs to their dependencies */
+    private dependencies;
+    /** Map of rule IDs to rules that depend on them */
+    private dependents;
+    /**
+     * Add a dependency relationship.
+     * The rule will be executed after all its dependencies.
+     *
+     * @param ruleId - The rule that depends on others
+     * @param dependsOn - Array of rule IDs that must be executed first
+     *
+     * @example
+     * ```typescript
+     * hierarchy.addDependency('tests-required', ['no-duplicate-code']);
+     * // tests-required will be validated after no-duplicate-code
+     * ```
+     */
+    addDependency(ruleId: string, dependsOn: string[]): void;
+    /**
+     * Get all dependencies for a rule.
+     *
+     * @param ruleId - The rule to get dependencies for
+     * @returns Array of rule IDs that the rule depends on
+     *
+     * @example
+     * ```typescript
+     * const deps = hierarchy.getDependencies('tests-required');
+     * console.log(deps); // ['no-duplicate-code']
+     * ```
+     */
+    getDependencies(ruleId: string): string[];
+    /**
+     * Get all rules that depend on the given rule.
+     *
+     * @param ruleId - The rule to get dependents for
+     * @returns Array of rule IDs that depend on this rule
+     *
+     * @example
+     * ```typescript
+     * const dependents = hierarchy.getDependents('no-duplicate-code');
+     * console.log(dependents); // ['tests-required']
+     * ```
+     */
+    getDependents(ruleId: string): string[];
+    /**
+     * Get the execution order for a set of rules using topological sort.
+     * Rules are returned in order such that dependencies come before dependents.
+     *
+     * Uses Kahn's algorithm for topological sorting.
+     *
+     * @param ruleIds - Array of rule IDs to order
+     * @returns Sorted array of rule IDs in dependency order
+     *
+     * @example
+     * ```typescript
+     * const order = hierarchy.getExecutionOrder(['tests-required', 'no-duplicate-code']);
+     * // Result: ['no-duplicate-code', 'tests-required']
+     * ```
+     */
+    getExecutionOrder(ruleIds: string[]): string[];
+    /**
+     * Check if any circular dependencies exist in the hierarchy.
+     *
+     * @returns true if circular dependencies exist, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (hierarchy.hasCircularDependencies()) {
+     *   console.error('Circular dependencies detected!');
+     * }
+     * ```
+     */
+    hasCircularDependencies(): boolean;
+    /**
+     * Find all circular dependency cycles.
+     * Uses DFS to detect cycles in the dependency graph.
+     *
+     * @returns Array of cycles, where each cycle is an array of rule IDs
+     *
+     * @example
+     * ```typescript
+     * const cycles = hierarchy.findCircularDependencies();
+     * // cycles might be [['rule-a', 'rule-b', 'rule-c']]
+     * ```
+     */
+    findCircularDependencies(): string[][];
+    /**
+     * Check if all dependencies for a rule have been executed.
+     *
+     * @param ruleId - The rule to check
+     * @param executedRules - Set of rule IDs that have already been executed
+     * @returns true if all dependencies are satisfied, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const executed = new Set(['no-duplicate-code']);
+     * if (hierarchy.isDependencySatisfied('tests-required', executed)) {
+     *   // Safe to execute tests-required
+     * }
+     * ```
+     */
+    isDependencySatisfied(ruleId: string, executedRules: Set<string>): boolean;
+    /**
+     * Clear all dependency relationships.
+     * Useful for testing or reinitializing.
+     */
+    clear(): void;
+    /**
+     * Get all rules that have dependencies registered.
+     *
+     * @returns Array of rule IDs with dependencies
+     */
+    getAllRules(): string[];
+}

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

@@ -0,0 +1,197 @@
+/**
+ * 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
+ * @version 1.0.0
+ *
+ * @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,106 @@
+/**
+ * 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
+ * @version 1.0.0
+ *
+ * @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/enforcer-tools.js

@@ -5,7 +5,7 @@
 import { ruleEnforcer, } from "./rule-enforcer.js";
 import { frameworkLogger } from "../core/framework-logger.js";
 import { AgentDelegator } from "../delegation/agent-delegator.js";
-import { StringRayStateManager } from "../state/state-manager.js";
+import { XrayStateManager } from "../state/state-manager.js";
 import { strRayConfigLoader } from "../core/config-loader.js";
 import * as fs from "fs";
 import * as path from "path";
@@ -325,7 +325,7 @@ async function executeReleaseWorkflow(operation, context, jobId, routing) {
 async function delegateToAgent(agentName, operation, context, jobId) {
     try {
         // Create a minimal state manager and config loader for the delegator
-        const stateManager = new StringRayStateManager();
+        const stateManager = new XrayStateManager();
         // Create the delegator
         const delegator = new AgentDelegator(stateManager, strRayConfigLoader);
         // Build task description for the delegated agent

package/dist/enforcement/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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);
+ * ```
+ */
+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,99 @@
+/**
+ * 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 { 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;
+}