qnce-engine 0.1.0 → 1.2.1

package/dist/engine/condition.d.ts

@@ -0,0 +1,69 @@
+import { QNCEState } from './core';
+/**
+ * Error thrown when condition evaluation fails
+ */
+export declare class ConditionEvaluationError extends Error {
+    readonly expression?: string | undefined;
+    readonly cause?: Error | undefined;
+    constructor(message: string, expression?: string | undefined, cause?: Error | undefined);
+}
+/**
+ * Context object passed to condition evaluators
+ */
+export interface ConditionContext {
+    /** Current engine state */
+    state: QNCEState;
+    /** Current timestamp for time-based conditions */
+    timestamp: number;
+    /** Additional custom context data */
+    customData?: Record<string, unknown>;
+}
+/**
+ * Custom evaluator function signature
+ */
+export type CustomEvaluatorFunction = (expression: string, context: ConditionContext) => boolean;
+/**
+ * Condition evaluator service for parsing and executing conditional expressions
+ */
+export declare class ConditionEvaluator {
+    private customEvaluator?;
+    private functionCache;
+    private maxCacheSize;
+    /**
+     * Set a custom evaluator function for handling complex conditions
+     */
+    setCustomEvaluator(evaluator: CustomEvaluatorFunction): void;
+    /**
+     * Clear the custom evaluator
+     */
+    clearCustomEvaluator(): void;
+    /**
+     * Evaluate a condition expression against the provided context
+     */
+    evaluate(expression: string, context: ConditionContext): boolean;
+    /**
+     * Built-in expression evaluator with support for common patterns
+     */
+    private evaluateBuiltIn;
+    /**
+     * Sanitize expression to prevent code injection
+     */
+    private sanitizeExpression;
+    /**
+     * Create a safe evaluation context from the condition context
+     */
+    private createEvaluationContext;
+    /**
+     * Validate that an expression is syntactically correct without evaluating it
+     */
+    validateExpression(expression: string): {
+        valid: boolean;
+        error?: string;
+    };
+    /**
+     * Get list of flag names referenced in an expression
+     */
+    getReferencedFlags(expression: string): string[];
+}
+export declare const conditionEvaluator: ConditionEvaluator;
+//# sourceMappingURL=condition.d.ts.map

package/dist/engine/condition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"condition.d.ts","sourceRoot":"","sources":["../../src/engine/condition.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAEnC;;GAEG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;aACJ,UAAU,CAAC,EAAE,MAAM;aAAkB,KAAK,CAAC,EAAE,KAAK;gBAAnF,OAAO,EAAE,MAAM,EAAkB,UAAU,CAAC,EAAE,MAAM,YAAA,EAAkB,KAAK,CAAC,EAAE,KAAK,YAAA;CAIhG;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,2BAA2B;IAC3B,KAAK,EAAE,SAAS,CAAC;IACjB,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC;AAkBjG;;GAEG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,eAAe,CAAC,CAA0B;IAGlD,OAAO,CAAC,aAAa,CAAoC;IACzD,OAAO,CAAC,YAAY,CAAe;IAEnC;;OAEG;IACH,kBAAkB,CAAC,SAAS,EAAE,uBAAuB,GAAG,IAAI;IAI5D;;OAEG;IACH,oBAAoB,IAAI,IAAI;IAI5B;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO;IAkBhE;;OAEG;IACH,OAAO,CAAC,eAAe;IA+DvB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA8B1B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAa/B;;OAEG;IACH,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE;IAmB1E;;OAEG;IACH,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE;CAWjD;AAGD,eAAO,MAAM,kBAAkB,oBAA2B,CAAC"}

package/dist/engine/condition.js

@@ -0,0 +1,195 @@
+"use strict";
+// QNCE Condition Evaluator - Sprint 3.4
+// Parses and evaluates conditional expressions for choice visibility
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.conditionEvaluator = exports.ConditionEvaluator = exports.ConditionEvaluationError = void 0;
+/**
+ * Error thrown when condition evaluation fails
+ */
+class ConditionEvaluationError extends Error {
+    expression;
+    cause;
+    constructor(message, expression, cause) {
+        super(message);
+        this.expression = expression;
+        this.cause = cause;
+        this.name = 'ConditionEvaluationError';
+    }
+}
+exports.ConditionEvaluationError = ConditionEvaluationError;
+/**
+ * Built-in expression operators
+ */
+const OPERATORS = {
+    '>=': (a, b) => a >= b,
+    '<=': (a, b) => a <= b,
+    '>': (a, b) => a > b,
+    '<': (a, b) => a < b,
+    '==': (a, b) => a == b,
+    '===': (a, b) => a === b,
+    '!=': (a, b) => a != b,
+    '!==': (a, b) => a !== b,
+    '&&': (a, b) => a && b,
+    '||': (a, b) => a || b,
+};
+/**
+ * Condition evaluator service for parsing and executing conditional expressions
+ */
+class ConditionEvaluator {
+    customEvaluator;
+    // Cache compiled functions for better performance
+    functionCache = new Map();
+    maxCacheSize = 100;
+    /**
+     * Set a custom evaluator function for handling complex conditions
+     */
+    setCustomEvaluator(evaluator) {
+        this.customEvaluator = evaluator;
+    }
+    /**
+     * Clear the custom evaluator
+     */
+    clearCustomEvaluator() {
+        this.customEvaluator = undefined;
+    }
+    /**
+     * Evaluate a condition expression against the provided context
+     */
+    evaluate(expression, context) {
+        try {
+            // If custom evaluator is set, use it first
+            if (this.customEvaluator) {
+                return this.customEvaluator(expression, context);
+            }
+            // Use built-in evaluator
+            return this.evaluateBuiltIn(expression, context);
+        }
+        catch (error) {
+            throw new ConditionEvaluationError(`Failed to evaluate condition: ${expression}`, expression, error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+    /**
+     * Built-in expression evaluator with support for common patterns
+     */
+    evaluateBuiltIn(expression, context) {
+        // Handle empty expressions
+        if (!expression || expression.trim() === '') {
+            throw new ConditionEvaluationError('Empty or whitespace-only condition expression', expression);
+        }
+        // Sanitize and prepare expression
+        const sanitizedExpression = this.sanitizeExpression(expression);
+        // Handle simple cases first
+        if (sanitizedExpression === 'true')
+            return true;
+        if (sanitizedExpression === 'false')
+            return false;
+        // Create safe evaluation context
+        const evalContext = this.createEvaluationContext(context);
+        // Check function cache for performance
+        let func = this.functionCache.get(sanitizedExpression);
+        if (!func) {
+            try {
+                // Use Function constructor for safe evaluation (better than eval)
+                func = new Function('flags', 'state', 'timestamp', 'customData', `
+          "use strict";
+          return ${sanitizedExpression};
+        `);
+                // Cache the function for future use
+                if (this.functionCache.size >= this.maxCacheSize) {
+                    // Remove oldest entry when cache is full
+                    const firstKey = this.functionCache.keys().next().value;
+                    if (firstKey) {
+                        this.functionCache.delete(firstKey);
+                    }
+                }
+                this.functionCache.set(sanitizedExpression, func);
+            }
+            catch (error) {
+                throw new ConditionEvaluationError(`Invalid expression syntax: ${expression}`, expression, error instanceof Error ? error : new Error(String(error)));
+            }
+        }
+        try {
+            return !!func(evalContext.flags, evalContext.state, evalContext.timestamp, evalContext.customData);
+        }
+        catch (error) {
+            throw new ConditionEvaluationError(`Runtime error evaluating: ${expression}`, expression, error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+    /**
+     * Sanitize expression to prevent code injection
+     */
+    sanitizeExpression(expression) {
+        // Remove potentially dangerous patterns
+        const dangerous = [
+            /\beval\b/g,
+            /\bFunction\b/g,
+            /\bconstructor\b/g,
+            /\bprototype\b/g,
+            /\b__proto__\b/g,
+            /\bimport\b/g,
+            /\brequire\b/g,
+            /\bprocess\b/g,
+            /\bglobal\b/g,
+            /\bwindow\b/g,
+            /\bdocument\b/g,
+        ];
+        let sanitized = expression.trim();
+        for (const pattern of dangerous) {
+            if (pattern.test(sanitized)) {
+                throw new ConditionEvaluationError(`Potentially unsafe expression detected: ${expression}`, expression);
+            }
+        }
+        return sanitized;
+    }
+    /**
+     * Create a safe evaluation context from the condition context
+     */
+    createEvaluationContext(context) {
+        return {
+            flags: { ...context.state.flags },
+            state: {
+                currentNodeId: context.state.currentNodeId,
+                flags: { ...context.state.flags },
+                history: [...context.state.history],
+            },
+            timestamp: context.timestamp,
+            customData: context.customData ? { ...context.customData } : {},
+        };
+    }
+    /**
+     * Validate that an expression is syntactically correct without evaluating it
+     */
+    validateExpression(expression) {
+        try {
+            this.sanitizeExpression(expression);
+            // Try to create the function without executing it
+            new Function('flags', 'state', 'timestamp', 'customData', `
+        "use strict";
+        return ${expression};
+      `);
+            return { valid: true };
+        }
+        catch (error) {
+            return {
+                valid: false,
+                error: error instanceof Error ? error.message : String(error)
+            };
+        }
+    }
+    /**
+     * Get list of flag names referenced in an expression
+     */
+    getReferencedFlags(expression) {
+        const flagPattern = /flags\.([a-zA-Z_$][a-zA-Z0-9_$]*)/g;
+        const matches = [];
+        let match;
+        while ((match = flagPattern.exec(expression)) !== null) {
+            matches.push(match[1]);
+        }
+        return Array.from(new Set(matches)); // Remove duplicates
+    }
+}
+exports.ConditionEvaluator = ConditionEvaluator;
+// Create a global instance for the engine to use
+exports.conditionEvaluator = new ConditionEvaluator();
+//# sourceMappingURL=condition.js.map

package/dist/engine/condition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"condition.js","sourceRoot":"","sources":["../../src/engine/condition.ts"],"names":[],"mappings":"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"}