@bernierllc/nevar-evaluator 0.0.1 → 0.1.0

package/README.md

@@ -1,45 +1,82 @@
 # @bernierllc/nevar-evaluator
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+Evaluates condition trees against a flat context using an operator registry for the Nevar rules engine.
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+## Installation
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+```bash
+npm install @bernierllc/nevar-evaluator
+```
 
-## Purpose
+## Usage
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@bernierllc/nevar-evaluator`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+```typescript
+import { evaluate, resolveField } from '@bernierllc/nevar-evaluator';
+import type { OperatorLookup } from '@bernierllc/nevar-evaluator';
+import type { ConditionGroup } from '@bernierllc/nevar-types';
 
-## What is OIDC Trusted Publishing?
+// Any object implementing OperatorLookup (e.g. OperatorRegistry from nevar-operator-registry)
+const operators: OperatorLookup = {
+  has: (name) => name === 'gte',
+  evaluate: (name, field, target) => (field as number) >= (target as number),
+};
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+const tree: ConditionGroup = {
+  operator: 'AND',
+  conditions: [
+    { field: 'user.age', op: 'gte', value: 18 },
+  ],
+};
 
-## Setup Instructions
+const result = evaluate(tree, { user: { age: 21 } }, operators);
+// result.matched === true
+// result.trace === [{ field: 'user.age', op: 'gte', expected: 18, actual: 21, matched: true }]
 
-To properly configure OIDC trusted publishing for this package:
+// Resolve a dot-path field from a nested object
+const value = resolveField({ user: { name: 'Alice' } }, 'user.name');
+// 'Alice'
+```
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+## API
 
-## DO NOT USE THIS PACKAGE
+### `evaluate(tree, context, operators)`
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+Recursively evaluates a condition tree (AND / OR / NOT groups) against a context object. Returns a boolean match result and a trace of every condition evaluated.
 
-## More Information
+**Parameters:**
+- `tree: ConditionGroup` - The root condition group to evaluate
+- `context: Record<string, unknown>` - Key-value context to evaluate against
+- `operators: OperatorLookup` - Operator lookup for resolving and evaluating operators
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+**Returns:** `EvaluationResult` with `matched: boolean` and `trace: EvaluationTrace[]`
 
----
+**Throws:** `NevarEvaluationError` if an unknown operator is encountered.
 
-**Maintained for OIDC setup purposes only**
+### `resolveField(context, fieldPath)`
+
+Resolves a dot-notation field path against a context object. Returns `undefined` if any segment is missing.
+
+**Parameters:**
+- `context: Record<string, unknown>` - The context object
+- `fieldPath: string` - Dot-notation path (e.g. `"user.name"`)
+
+**Returns:** `unknown` - The resolved value or `undefined`
+
+### `OperatorLookup` (type)
+
+Interface for looking up and evaluating operators. Decouples the evaluator from a specific operator registry implementation.
+
+- `evaluate(name: string, fieldValue: unknown, targetValue: unknown): boolean`
+- `has(name: string): boolean`
+
+## Integration Documentation
+
+### Logger Integration
+This package does not integrate with `@bernierllc/logger`. As a core package, logger integration is optional and not included by default. Consumers should handle logging at the service layer.
+
+### NeverHub Integration
+This package does not integrate with `@bernierllc/neverhub-adapter`. As a core package, NeverHub integration is not applicable. NeverHub registration should be handled by service-layer packages that compose this package.
+
+## License
+
+Copyright (c) 2025 Bernier LLC. All rights reserved.

package/dist/evaluator.d.ts

@@ -0,0 +1,41 @@
+import { ConditionGroup, EvaluationResult } from '@bernierllc/nevar-types';
+/**
+ * Interface for looking up and evaluating operators.
+ * Decouples the evaluator from a specific operator registry implementation.
+ */
+export interface OperatorLookup {
+    evaluate(name: string, fieldValue: unknown, targetValue: unknown): boolean;
+    has(name: string): boolean;
+}
+/**
+ * Resolves a dot-path field reference against a flat context object.
+ * Returns undefined if any segment is missing.
+ *
+ * @example
+ * resolveField({ user: { name: 'Alice' } }, 'user.name') // 'Alice'
+ * resolveField({ a: 1 }, 'b.c') // undefined
+ */
+export declare function resolveField(context: Record<string, unknown>, fieldPath: string): unknown;
+/**
+ * Evaluates a condition tree against a flat context using an operator registry.
+ * Returns a boolean match result and a trace of every condition evaluated.
+ *
+ * @param tree - The root condition group to evaluate.
+ * @param context - A flat (or nested) key-value context to evaluate against.
+ * @param operators - An operator lookup for resolving and evaluating operators.
+ * @returns An EvaluationResult with matched status and evaluation trace.
+ *
+ * @throws NevarEvaluationError if an unknown operator is encountered.
+ *
+ * @example
+ * ```typescript
+ * const result = evaluate(
+ *   { operator: 'AND', conditions: [{ field: 'age', op: 'gte', value: 18 }] },
+ *   { age: 21 },
+ *   operatorRegistry,
+ * );
+ * // result.matched === true
+ * // result.trace === [{ field: 'age', op: 'gte', expected: 18, actual: 21, matched: true }]
+ * ```
+ */
+export declare function evaluate(tree: ConditionGroup, context: Record<string, unknown>, operators: OperatorLookup): EvaluationResult;

package/dist/evaluator.js

@@ -0,0 +1,131 @@
+"use strict";
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveField = resolveField;
+exports.evaluate = evaluate;
+const nevar_types_1 = require("@bernierllc/nevar-types");
+/**
+ * Resolves a dot-path field reference against a flat context object.
+ * Returns undefined if any segment is missing.
+ *
+ * @example
+ * resolveField({ user: { name: 'Alice' } }, 'user.name') // 'Alice'
+ * resolveField({ a: 1 }, 'b.c') // undefined
+ */
+function resolveField(context, fieldPath) {
+    const segments = fieldPath.split('.');
+    let current = context;
+    for (const segment of segments) {
+        if (current === null || current === undefined || typeof current !== 'object') {
+            return undefined;
+        }
+        current = current[segment];
+    }
+    return current;
+}
+/**
+ * Evaluates a single leaf condition against the context.
+ * Returns the trace entry and whether it matched.
+ */
+function evaluateCondition(condition, context, operators) {
+    if (!operators.has(condition.op)) {
+        throw new nevar_types_1.NevarEvaluationError(`Unknown operator: "${condition.op}"`, {
+            code: 'UNKNOWN_OPERATOR',
+            context: { operator: condition.op, field: condition.field },
+        });
+    }
+    const actual = resolveField(context, condition.field);
+    // Missing field in context evaluates to false
+    if (actual === undefined) {
+        return {
+            matched: false,
+            trace: {
+                field: condition.field,
+                op: condition.op,
+                expected: condition.value,
+                actual: undefined,
+                matched: false,
+            },
+        };
+    }
+    const matched = operators.evaluate(condition.op, actual, condition.value);
+    return {
+        matched,
+        trace: {
+            field: condition.field,
+            op: condition.op,
+            expected: condition.value,
+            actual,
+            matched,
+        },
+    };
+}
+/**
+ * Recursively evaluates a condition group (AND / OR / NOT) against the context.
+ * Returns the aggregate match result and all trace entries.
+ */
+function evaluateGroup(group, context, operators) {
+    const trace = [];
+    // Empty conditions → vacuous truth
+    if (group.conditions.length === 0) {
+        return { matched: true, trace };
+    }
+    const childResults = [];
+    for (const child of group.conditions) {
+        if ((0, nevar_types_1.isConditionGroup)(child)) {
+            const result = evaluateGroup(child, context, operators);
+            trace.push(...result.trace);
+            childResults.push(result.matched);
+        }
+        else if ((0, nevar_types_1.isCondition)(child)) {
+            const result = evaluateCondition(child, context, operators);
+            trace.push(result.trace);
+            childResults.push(result.matched);
+        }
+    }
+    let matched;
+    switch (group.operator) {
+        case 'AND':
+            matched = childResults.every(Boolean);
+            break;
+        case 'OR':
+            matched = childResults.some(Boolean);
+            break;
+        case 'NOT':
+            // NOT evaluates children as AND, then negates
+            matched = !childResults.every(Boolean);
+            break;
+    }
+    return { matched, trace };
+}
+/**
+ * Evaluates a condition tree against a flat context using an operator registry.
+ * Returns a boolean match result and a trace of every condition evaluated.
+ *
+ * @param tree - The root condition group to evaluate.
+ * @param context - A flat (or nested) key-value context to evaluate against.
+ * @param operators - An operator lookup for resolving and evaluating operators.
+ * @returns An EvaluationResult with matched status and evaluation trace.
+ *
+ * @throws NevarEvaluationError if an unknown operator is encountered.
+ *
+ * @example
+ * ```typescript
+ * const result = evaluate(
+ *   { operator: 'AND', conditions: [{ field: 'age', op: 'gte', value: 18 }] },
+ *   { age: 21 },
+ *   operatorRegistry,
+ * );
+ * // result.matched === true
+ * // result.trace === [{ field: 'age', op: 'gte', expected: 18, actual: 21, matched: true }]
+ * ```
+ */
+function evaluate(tree, context, operators) {
+    return evaluateGroup(tree, context, operators);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { evaluate, resolveField } from './evaluator';
+export type { OperatorLookup } from './evaluator';

package/dist/index.js

@@ -0,0 +1,13 @@
+"use strict";
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveField = exports.evaluate = void 0;
+var evaluator_1 = require("./evaluator");
+Object.defineProperty(exports, "evaluate", { enumerable: true, get: function () { return evaluator_1.evaluate; } });
+Object.defineProperty(exports, "resolveField", { enumerable: true, get: function () { return evaluator_1.resolveField; } });

package/package.json

@@ -1,10 +1,56 @@
 {
   "name": "@bernierllc/nevar-evaluator",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @bernierllc/nevar-evaluator",
+  "version": "0.1.0",
+  "description": "Evaluates condition trees against a flat context using an operator registry for the Nevar rules engine",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE"
+  ],
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
-}
+    "nevar",
+    "rules-engine",
+    "evaluator",
+    "condition-tree",
+    "evaluation"
+  ],
+  "author": "Bernier LLC",
+  "license": "SEE LICENSE IN LICENSE",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bernierllc/tools.git",
+    "directory": "packages/core/nevar-evaluator"
+  },
+  "dependencies": {
+    "@bernierllc/nevar-types": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "eslint": "^8.0.0",
+    "jest": "^29.5.0",
+    "rimraf": "^5.0.0",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prebuild": "npm run clean",
+    "clean": "rimraf dist",
+    "test": "jest",
+    "test:run": "jest",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint src __tests__ --ext .ts"
+  }
+}