@f-o-t/rules-engine 2.0.2 → 3.0.0

package/biome.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true,
+    "defaultBranch": "main"
+  },
+  "files": {
+    "ignoreUnknown": false,
+    "ignore": [
+      "node_modules",
+      "dist",
+      "*.config.ts"
+    ]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "tab",
+    "indentWidth": 2,
+    "lineWidth": 80
+  },
+  "organizeImports": {
+    "enabled": true
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double",
+      "semicolons": "always",
+      "trailingCommas": "all"
+    }
+  }
+}

package/docs/MIGRATION-v3.md

@@ -0,0 +1,118 @@
+# Migration Guide: v2.x → v3.0
+
+## Breaking Changes
+
+### Engine requires evaluator configuration
+
+**What changed:**
+The engine now requires explicit evaluator configuration to enable custom operators.
+
+**Before (v2.x):**
+```typescript
+import { createEngine } from "@f-o-t/rules-engine";
+
+const engine = createEngine({
+  consequences: MyConsequences,
+});
+```
+
+**After (v3.x):**
+```typescript
+import { createEngine, createEvaluator } from "@f-o-t/rules-engine";
+
+// Option 1: Built-in operators only
+const engine = createEngine({
+  consequences: MyConsequences,
+  evaluator: createEvaluator(),
+});
+
+// Option 2: With custom operators
+import { moneyOperators } from "@f-o-t/money/operators";
+
+const engine = createEngine({
+  consequences: MyConsequences,
+  evaluator: createEvaluator({ operators: moneyOperators }),
+});
+
+// Option 3: Convenience (engine creates evaluator)
+const engine = createEngine({
+  consequences: MyConsequences,
+  operators: moneyOperators,
+});
+```
+
+### Internal API changes
+
+If you were using `evaluateRule` or `evaluateRules` directly (not through the engine), these now require an evaluator parameter:
+
+**Before:**
+```typescript
+import { evaluateRule } from "@f-o-t/rules-engine";
+
+const result = evaluateRule(rule, context);
+```
+
+**After:**
+```typescript
+import { evaluateRule, createEvaluator } from "@f-o-t/rules-engine";
+
+const evaluator = createEvaluator();
+const result = evaluateRule(rule, context, evaluator);
+```
+
+## New Features
+
+### Custom operators in rules
+
+You can now use custom operators from any library:
+
+```typescript
+import { createEngine, createEvaluator } from "@f-o-t/rules-engine";
+import { moneyOperators } from "@f-o-t/money/operators";
+
+const engine = createEngine({
+  operators: moneyOperators,
+});
+
+engine.addRule({
+  name: "high-value-transaction",
+  conditions: {
+    id: "g1",
+    operator: "AND",
+    conditions: [
+      {
+        id: "c1",
+        type: "custom",
+        field: "transactionAmount",
+        operator: "money_gt",
+        value: { amount: "1000.00", currency: "BRL" },
+      },
+    ],
+  },
+  consequences: [
+    { type: "require_approval", payload: { level: "manager" } },
+  ],
+});
+```
+
+### Compose multiple operator sets
+
+```typescript
+import { moneyOperators } from "@f-o-t/money/operators";
+import { dateOperators } from "./my-date-operators";
+
+const engine = createEngine({
+  operators: {
+    ...moneyOperators,
+    ...dateOperators,
+  },
+});
+```
+
+## Why this change?
+
+This breaking change enables:
+1. **Custom operators** - Use domain-specific operators like `money_gt`, `money_between`
+2. **Type safety** - Better TypeScript support for custom operator types
+3. **Extensibility** - Easier to add new operator types
+4. **Consistency** - Aligns with condition-evaluator's plugin architecture

package/fot.config.ts

@@ -0,0 +1,5 @@
+import { defineFotConfig } from '@f-o-t/config';
+
+export default defineFotConfig({
+  external: ['zod', '@f-o-t/condition-evaluator'],
+});

package/package.json

@@ -1,69 +1,33 @@
 {
-   "bugs": {
-      "url": "https://github.com/F-O-T/montte-nx/issues"
-   },
-   "description": "Type-safe, functional rules orchestration engine for TypeScript",
-   "dependencies": {
-      "@f-o-t/condition-evaluator": "2.0.0",
-      "zod": "4.3.4"
-   },
-   "devDependencies": {
-      "@biomejs/biome": "2.3.10",
-      "@types/bun": "1.3.5",
-      "bumpp": "10.3.2",
-      "bunup": "0.16.11",
-      "typescript": "5.9.3"
-   },
-   "exports": {
-      ".": {
-         "bun": "./src/index.ts",
-         "import": {
-            "default": "./dist/index.js",
-            "types": "./dist/index.d.ts"
-         },
-         "require": {
-            "default": "./dist/index.cjs",
-            "types": "./dist/index.d.cts"
-         },
-         "types": "./src/index.ts"
-      },
-      "./package.json": "./package.json"
-   },
-   "main": "./dist/index.cjs",
-   "files": [
-      "dist"
-   ],
-   "homepage": "https://github.com/F-O-T/montte-nx/blob/master/libraries/rules-engine",
-   "license": "MIT",
-   "module": "./dist/index.js",
-   "name": "@f-o-t/rules-engine",
-   "peerDependencies": {
-      "typescript": ">=4.5.0"
-   },
-   "peerDependenciesMeta": {
-      "typescript": {
-         "optional": true
-      }
-   },
-   "private": false,
-   "publishConfig": {
-      "access": "public"
-   },
-   "repository": {
-      "type": "git",
-      "url": "https://github.com/F-O-T/montte-nx.git"
-   },
-   "scripts": {
-      "build": "bunup",
-      "check": "biome check --write .",
-      "dev": "bunup --watch",
-      "release": "bumpp --commit --push --tag",
-      "test": "bun test",
-      "test:coverage": "bun test --coverage",
-      "test:watch": "bun test --watch",
-      "typecheck": "tsc"
-   },
-   "type": "module",
-   "types": "./dist/index.d.ts",
-   "version": "2.0.2"
+  "name": "@f-o-t/rules-engine",
+  "version": "3.0.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "bun x --bun fot build",
+    "test": "bun x --bun fot test",
+    "lint": "bun x --bun fot lint",
+    "format": "bun x --bun fot format",
+    "typecheck": "bun x --bun fot typecheck"
+  },
+  "dependencies": {
+    "@f-o-t/condition-evaluator": "^2.0.2",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@f-o-t/cli": "^1.0.0",
+    "@f-o-t/config": "^1.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/F-O-T/libraries.git",
+    "directory": "libraries/rules-engine"
+  }
 }

package/src/analyzer/analysis.ts

@@ -0,0 +1,401 @@
+import {
+   type Condition,
+   type ConditionGroup,
+   isConditionGroup,
+} from "@f-o-t/condition-evaluator";
+import type {
+   ConsequenceDefinitions,
+   DefaultConsequences,
+} from "../types/consequence";
+import type { Rule } from "../types/rule";
+import {
+   calculateMaxDepth,
+   collectConditionFields,
+   countConditionGroups,
+   countConditions,
+} from "../utils/conditions";
+
+export type RuleComplexity = {
+   readonly ruleId: string;
+   readonly ruleName: string;
+   readonly totalConditions: number;
+   readonly maxDepth: number;
+   readonly groupCount: number;
+   readonly uniqueFields: number;
+   readonly uniqueOperators: number;
+   readonly consequenceCount: number;
+   readonly complexityScore: number;
+};
+
+export type RuleSetAnalysis = {
+   readonly ruleCount: number;
+   readonly enabledCount: number;
+   readonly disabledCount: number;
+   readonly totalConditions: number;
+   readonly totalConsequences: number;
+   readonly uniqueFields: ReadonlyArray<string>;
+   readonly uniqueOperators: ReadonlyArray<string>;
+   readonly uniqueConsequenceTypes: ReadonlyArray<string>;
+   readonly uniqueCategories: ReadonlyArray<string>;
+   readonly uniqueTags: ReadonlyArray<string>;
+   readonly priorityRange: { min: number; max: number };
+   readonly averageComplexity: number;
+   readonly complexityDistribution: {
+      readonly low: number;
+      readonly medium: number;
+      readonly high: number;
+   };
+   readonly ruleComplexities: ReadonlyArray<RuleComplexity>;
+};
+
+export type FieldUsage = {
+   readonly field: string;
+   readonly count: number;
+   readonly types: ReadonlyArray<string>;
+   readonly operators: ReadonlyArray<string>;
+   readonly rules: ReadonlyArray<{ id: string; name: string }>;
+};
+
+export type OperatorUsage = {
+   readonly operator: string;
+   readonly type: string;
+   readonly count: number;
+   readonly rules: ReadonlyArray<{ id: string; name: string }>;
+};
+
+export type ConsequenceUsage = {
+   readonly type: string;
+   readonly count: number;
+   readonly rules: ReadonlyArray<{ id: string; name: string }>;
+};
+
+const collectOperators = (
+   condition: Condition | ConditionGroup,
+): Set<string> => {
+   const operators = new Set<string>();
+
+   const traverse = (c: Condition | ConditionGroup) => {
+      if (isConditionGroup(c)) {
+         operators.add(c.operator);
+         for (const child of c.conditions) {
+            traverse(child as Condition | ConditionGroup);
+         }
+      } else {
+         operators.add(c.operator);
+      }
+   };
+
+   traverse(condition);
+   return operators;
+};
+
+const calculateComplexityScore = (
+   totalConditions: number,
+   maxDepth: number,
+   groupCount: number,
+   uniqueFields: number,
+): number => {
+   return (
+      totalConditions * 1 + maxDepth * 2 + groupCount * 1.5 + uniqueFields * 0.5
+   );
+};
+
+export const analyzeRuleComplexity = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   rule: Rule<TContext, TConsequences>,
+): RuleComplexity => {
+   const totalConditions = countConditions(rule.conditions);
+   const maxDepth = calculateMaxDepth(rule.conditions);
+   const groupCount = countConditionGroups(rule.conditions);
+   const uniqueFields = collectConditionFields(rule.conditions).size;
+   const uniqueOperators = collectOperators(rule.conditions).size;
+   const consequenceCount = rule.consequences.length;
+
+   const complexityScore = calculateComplexityScore(
+      totalConditions,
+      maxDepth,
+      groupCount,
+      uniqueFields,
+   );
+
+   return {
+      ruleId: rule.id,
+      ruleName: rule.name,
+      totalConditions,
+      maxDepth,
+      groupCount,
+      uniqueFields,
+      uniqueOperators,
+      consequenceCount,
+      complexityScore,
+   };
+};
+
+export const analyzeRuleSet = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   rules: ReadonlyArray<Rule<TContext, TConsequences>>,
+): RuleSetAnalysis => {
+   const complexities = rules.map(analyzeRuleComplexity);
+
+   const allFields = new Set<string>();
+   const allOperators = new Set<string>();
+   const allConsequenceTypes = new Set<string>();
+   const allCategories = new Set<string>();
+   const allTags = new Set<string>();
+
+   let totalConditions = 0;
+   let totalConsequences = 0;
+   let minPriority = Number.POSITIVE_INFINITY;
+   let maxPriority = Number.NEGATIVE_INFINITY;
+   let enabledCount = 0;
+
+   for (const rule of rules) {
+      totalConditions += countConditions(rule.conditions);
+      totalConsequences += rule.consequences.length;
+
+      if (rule.priority < minPriority) minPriority = rule.priority;
+      if (rule.priority > maxPriority) maxPriority = rule.priority;
+
+      if (rule.enabled) enabledCount++;
+
+      for (const field of collectConditionFields(rule.conditions)) {
+         allFields.add(field);
+      }
+
+      for (const operator of collectOperators(rule.conditions)) {
+         allOperators.add(operator);
+      }
+
+      for (const consequence of rule.consequences) {
+         allConsequenceTypes.add(consequence.type as string);
+      }
+
+      if (rule.category) allCategories.add(rule.category);
+      for (const tag of rule.tags) allTags.add(tag);
+   }
+
+   const averageComplexity =
+      complexities.length > 0
+         ? complexities.reduce((sum, c) => sum + c.complexityScore, 0) /
+           complexities.length
+         : 0;
+
+   const complexityDistribution = {
+      low: complexities.filter((c) => c.complexityScore < 5).length,
+      medium: complexities.filter(
+         (c) => c.complexityScore >= 5 && c.complexityScore < 15,
+      ).length,
+      high: complexities.filter((c) => c.complexityScore >= 15).length,
+   };
+
+   return {
+      ruleCount: rules.length,
+      enabledCount,
+      disabledCount: rules.length - enabledCount,
+      totalConditions,
+      totalConsequences,
+      uniqueFields: [...allFields].sort(),
+      uniqueOperators: [...allOperators].sort(),
+      uniqueConsequenceTypes: [...allConsequenceTypes].sort(),
+      uniqueCategories: [...allCategories].sort(),
+      uniqueTags: [...allTags].sort(),
+      priorityRange: {
+         min: minPriority === Number.POSITIVE_INFINITY ? 0 : minPriority,
+         max: maxPriority === Number.NEGATIVE_INFINITY ? 0 : maxPriority,
+      },
+      averageComplexity,
+      complexityDistribution,
+      ruleComplexities: complexities,
+   };
+};
+
+export const analyzeFieldUsage = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   rules: ReadonlyArray<Rule<TContext, TConsequences>>,
+): ReadonlyArray<FieldUsage> => {
+   const fieldMap = new Map<
+      string,
+      {
+         types: Set<string>;
+         operators: Set<string>;
+         rules: Array<{ id: string; name: string }>;
+      }
+   >();
+
+   for (const rule of rules) {
+      const traverse = (c: Condition | ConditionGroup) => {
+         if (isConditionGroup(c)) {
+            for (const child of c.conditions) {
+               traverse(child as Condition | ConditionGroup);
+            }
+         } else {
+            const existing = fieldMap.get(c.field) ?? {
+               types: new Set(),
+               operators: new Set(),
+               rules: [],
+            };
+            existing.types.add(c.type);
+            existing.operators.add(c.operator);
+            if (!existing.rules.some((r) => r.id === rule.id)) {
+               existing.rules.push({ id: rule.id, name: rule.name });
+            }
+            fieldMap.set(c.field, existing);
+         }
+      };
+
+      traverse(rule.conditions);
+   }
+
+   return [...fieldMap.entries()]
+      .map(([field, data]) => ({
+         field,
+         count: data.rules.length,
+         types: [...data.types].sort(),
+         operators: [...data.operators].sort(),
+         rules: data.rules,
+      }))
+      .sort((a, b) => b.count - a.count);
+};
+
+export const analyzeOperatorUsage = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   rules: ReadonlyArray<Rule<TContext, TConsequences>>,
+): ReadonlyArray<OperatorUsage> => {
+   const operatorMap = new Map<
+      string,
+      { type: string; rules: Array<{ id: string; name: string }> }
+   >();
+
+   for (const rule of rules) {
+      const traverse = (c: Condition | ConditionGroup) => {
+         if (isConditionGroup(c)) {
+            for (const child of c.conditions) {
+               traverse(child as Condition | ConditionGroup);
+            }
+         } else {
+            const key = `${c.type}:${c.operator}`;
+            const existing = operatorMap.get(key) ?? {
+               type: c.type,
+               rules: [] as Array<{ id: string; name: string }>,
+            };
+            if (!existing.rules.some((r) => r.id === rule.id)) {
+               existing.rules.push({ id: rule.id, name: rule.name });
+            }
+            operatorMap.set(key, existing);
+         }
+      };
+
+      traverse(rule.conditions);
+   }
+
+   return [...operatorMap.entries()]
+      .map(([key, data]) => {
+         const parts = key.split(":");
+         return {
+            operator: parts[1] ?? "",
+            type: data.type,
+            count: data.rules.length,
+            rules: data.rules,
+         };
+      })
+      .sort((a, b) => b.count - a.count);
+};
+
+export const analyzeConsequenceUsage = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   rules: ReadonlyArray<Rule<TContext, TConsequences>>,
+): ReadonlyArray<ConsequenceUsage> => {
+   const consequenceMap = new Map<
+      string,
+      Array<{ id: string; name: string }>
+   >();
+
+   for (const rule of rules) {
+      for (const consequence of rule.consequences) {
+         const type = consequence.type as string;
+         const existing = consequenceMap.get(type) ?? [];
+         if (!existing.some((r) => r.id === rule.id)) {
+            existing.push({ id: rule.id, name: rule.name });
+         }
+         consequenceMap.set(type, existing);
+      }
+   }
+
+   return [...consequenceMap.entries()]
+      .map(([type, rules]) => ({
+         type,
+         count: rules.length,
+         rules,
+      }))
+      .sort((a, b) => b.count - a.count);
+};
+
+export const findMostComplexRules = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   rules: ReadonlyArray<Rule<TContext, TConsequences>>,
+   limit = 10,
+): ReadonlyArray<RuleComplexity> => {
+   return rules
+      .map(analyzeRuleComplexity)
+      .sort((a, b) => b.complexityScore - a.complexityScore)
+      .slice(0, limit);
+};
+
+export const findLeastUsedFields = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   rules: ReadonlyArray<Rule<TContext, TConsequences>>,
+   limit = 10,
+): ReadonlyArray<FieldUsage> => {
+   return [...analyzeFieldUsage(rules)]
+      .sort((a, b) => a.count - b.count)
+      .slice(0, limit);
+};
+
+export const formatRuleSetAnalysis = (analysis: RuleSetAnalysis): string => {
+   const lines: string[] = [
+      "=== Rule Set Analysis ===",
+      "",
+      `Rules: ${analysis.ruleCount} (${analysis.enabledCount} enabled, ${analysis.disabledCount} disabled)`,
+      `Total Conditions: ${analysis.totalConditions}`,
+      `Total Consequences: ${analysis.totalConsequences}`,
+      "",
+      `Unique Fields: ${analysis.uniqueFields.length}`,
+      `  ${analysis.uniqueFields.join(", ") || "(none)"}`,
+      "",
+      `Unique Operators: ${analysis.uniqueOperators.length}`,
+      `  ${analysis.uniqueOperators.join(", ") || "(none)"}`,
+      "",
+      `Consequence Types: ${analysis.uniqueConsequenceTypes.length}`,
+      `  ${analysis.uniqueConsequenceTypes.join(", ") || "(none)"}`,
+      "",
+      `Categories: ${analysis.uniqueCategories.length}`,
+      `  ${analysis.uniqueCategories.join(", ") || "(none)"}`,
+      "",
+      `Tags: ${analysis.uniqueTags.length}`,
+      `  ${analysis.uniqueTags.join(", ") || "(none)"}`,
+      "",
+      `Priority Range: ${analysis.priorityRange.min} - ${analysis.priorityRange.max}`,
+      "",
+      `Average Complexity: ${analysis.averageComplexity.toFixed(2)}`,
+      `Complexity Distribution:`,
+      `  Low (< 5): ${analysis.complexityDistribution.low}`,
+      `  Medium (5-15): ${analysis.complexityDistribution.medium}`,
+      `  High (> 15): ${analysis.complexityDistribution.high}`,
+   ];
+
+   return lines.join("\n");
+};