0xray 4.0.13 → 4.0.14

package/dist/enforcement/core/rule-hierarchy.js

@@ -0,0 +1,258 @@
+/**
+ * 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
+ *
+ * @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']
+ * ```
+ */
+/**
+ * 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 class RuleHierarchy {
+    /** Map of rule IDs to their dependencies */
+    dependencies = new Map();
+    /** Map of rule IDs to rules that depend on them */
+    dependents = new Map();
+    /**
+     * 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, dependsOn) {
+        // Add forward dependency relationship
+        if (!this.dependencies.has(ruleId)) {
+            this.dependencies.set(ruleId, new Set());
+        }
+        dependsOn.forEach(dep => this.dependencies.get(ruleId).add(dep));
+        // Track reverse relationship (dependents)
+        dependsOn.forEach(dep => {
+            if (!this.dependents.has(dep)) {
+                this.dependents.set(dep, new Set());
+            }
+            this.dependents.get(dep).add(ruleId);
+        });
+    }
+    /**
+     * 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) {
+        const deps = this.dependencies.get(ruleId);
+        return deps ? Array.from(deps) : [];
+    }
+    /**
+     * 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) {
+        const deps = this.dependents.get(ruleId);
+        return deps ? Array.from(deps) : [];
+    }
+    /**
+     * 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) {
+        if (ruleIds.length === 0)
+            return [];
+        // Build in-degree map for rules in the set
+        const inDegree = new Map();
+        const adjacencyList = new Map();
+        // Initialize
+        ruleIds.forEach(id => {
+            inDegree.set(id, 0);
+            adjacencyList.set(id, new Set());
+        });
+        // Calculate in-degrees and adjacency list
+        ruleIds.forEach(id => {
+            const deps = this.getDependencies(id);
+            deps.forEach(dep => {
+                // Only count dependencies that are in the rule set
+                if (ruleIds.includes(dep)) {
+                    inDegree.set(id, (inDegree.get(id) || 0) + 1);
+                    adjacencyList.get(dep).add(id);
+                }
+            });
+        });
+        // Kahn's algorithm
+        const result = [];
+        const queue = [];
+        // Start with nodes that have no dependencies
+        inDegree.forEach((degree, id) => {
+            if (degree === 0)
+                queue.push(id);
+        });
+        while (queue.length > 0) {
+            const current = queue.shift();
+            result.push(current);
+            const dependents = adjacencyList.get(current) || new Set();
+            dependents.forEach(dependent => {
+                const newDegree = (inDegree.get(dependent) || 0) - 1;
+                inDegree.set(dependent, newDegree);
+                if (newDegree === 0) {
+                    queue.push(dependent);
+                }
+            });
+        }
+        // If not all rules were processed, there's a circular dependency
+        if (result.length !== ruleIds.length) {
+            // Return rules in original order if topological sort fails
+            // This ensures we still execute rules even with cycles
+            return [...ruleIds];
+        }
+        return result;
+    }
+    /**
+     * 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() {
+        return this.findCircularDependencies().length > 0;
+    }
+    /**
+     * 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() {
+        const cycles = [];
+        const visited = new Set();
+        const recursionStack = new Set();
+        const dfs = (node, path) => {
+            if (recursionStack.has(node)) {
+                // Found a cycle
+                const cycleStart = path.indexOf(node);
+                if (cycleStart !== -1) {
+                    const cycle = path.slice(cycleStart);
+                    cycles.push(cycle);
+                }
+                return;
+            }
+            if (visited.has(node)) {
+                return;
+            }
+            visited.add(node);
+            recursionStack.add(node);
+            path.push(node);
+            const deps = this.getDependencies(node);
+            deps.forEach(dep => {
+                dfs(dep, [...path]);
+            });
+            recursionStack.delete(node);
+        };
+        // Check all nodes
+        this.dependencies.forEach((_, ruleId) => {
+            if (!visited.has(ruleId)) {
+                dfs(ruleId, []);
+            }
+        });
+        return cycles;
+    }
+    /**
+     * 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, executedRules) {
+        const deps = this.getDependencies(ruleId);
+        return deps.every(dep => executedRules.has(dep));
+    }
+    /**
+     * Clear all dependency relationships.
+     * Useful for testing or reinitializing.
+     */
+    clear() {
+        this.dependencies.clear();
+        this.dependents.clear();
+    }
+    /**
+     * Get all rules that have dependencies registered.
+     *
+     * @returns Array of rule IDs with dependencies
+     */
+    getAllRules() {
+        const rules = new Set();
+        this.dependencies.forEach((_, ruleId) => rules.add(ruleId));
+        this.dependents.forEach((_, ruleId) => rules.add(ruleId));
+        return Array.from(rules);
+    }
+}

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/rule-registry.js

@@ -0,0 +1,239 @@
+/**
+ * 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" })
+ * });
+ * ```
+ */
+/**
+ * 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 class RuleRegistry {
+    /** Internal storage for rules */
+    rules = new Map();
+    /**
+     * 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) {
+        if (this.rules.has(rule.id)) {
+            // Idempotent: update existing rule instead of throwing on duplicate.
+            // This handles async loaders that may re-register rules when the
+            // enforcer is constructed multiple times (e.g. singleton + tests).
+            this.rules.set(rule.id, rule);
+            return;
+        }
+        this.rules.set(rule.id, rule);
+    }
+    /**
+     * 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() {
+        return Array.from(this.rules.values());
+    }
+    /**
+     * 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) {
+        return this.rules.get(ruleId);
+    }
+    /**
+     * 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) {
+        const rule = this.rules.get(ruleId);
+        if (rule) {
+            rule.enabled = true;
+            return true;
+        }
+        return false;
+    }
+    /**
+     * 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) {
+        const rule = this.rules.get(ruleId);
+        if (rule) {
+            rule.enabled = false;
+            return true;
+        }
+        return false;
+    }
+    /**
+     * 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) {
+        const rule = this.rules.get(ruleId);
+        return rule?.enabled ?? false;
+    }
+    /**
+     * 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() {
+        return this.rules.size;
+    }
+    /**
+     * 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() {
+        const totalRules = this.rules.size;
+        const rulesValues = Array.from(this.rules.values());
+        const enabledRules = rulesValues.filter((rule) => rule.enabled).length;
+        const disabledRules = totalRules - enabledRules;
+        // Count rules by category
+        const ruleCategories = {};
+        rulesValues.forEach((rule) => {
+            ruleCategories[rule.category] = (ruleCategories[rule.category] || 0) + 1;
+        });
+        return { totalRules, enabledRules, disabledRules, ruleCategories };
+    }
+    /**
+     * 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) {
+        return this.rules.has(ruleId);
+    }
+    /**
+     * 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) {
+        return this.rules.delete(ruleId);
+    }
+    /**
+     * Clear all rules from the registry.
+     *
+     * @example
+     * ```typescript
+     * registry.clearRules();
+     * console.log(`Registry cleared. Count: ${registry.getRuleCount()}`);
+     * ```
+     */
+    clearRules() {
+        this.rules.clear();
+    }
+}