@halleyassist/rule-templater 0.0.15 → 0.0.17

package/dist/rule-templater.browser.js

@@ -3918,17 +3918,20 @@ class RuleTemplate {
     /**
      * Validate variable types against the AST
      * @param {Object} variables - Object mapping variable names to {type} objects
-     * @returns {Object} Object with validation results: {valid: boolean, errors: []}
+     * @param {Object} [functionBlob] - Optional HalleyFunctionBlob used for non-fatal function warnings
+     * @returns {Object} Object with validation results: {valid: boolean, errors: [], warnings: []}
      */
-    validate(variables) {
+    validate(variables, functionBlob) {
         if (!variables || typeof variables !== 'object') {
             return {
                 valid: false,
-                errors: ['Variables must be provided as an object']
+                errors: ['Variables must be provided as an object'],
+                warnings: []
             };
         }
 
         const errors = [];
+        const warnings = [];
         const extractedVars = this.extractVariables();
         
         for (const varInfo of extractedVars) {
@@ -3961,13 +3964,50 @@ class RuleTemplate {
                 }
             }
         }
+
+        if (functionBlob && typeof functionBlob.validate === 'function') {
+            for (const functionCall of this._extractFunctionCalls()) {
+                warnings.push(...functionBlob.validate(functionCall.name, functionCall.arguments));
+            }
+        }
         
         return {
             valid: errors.length === 0,
-            errors
+            errors,
+            warnings
         };
     }
 
+    _extractFunctionCalls() {
+        const functionCalls = [];
+
+        const traverse = (node) => {
+            if (!node) return;
+
+            if (node.type === 'fcall') {
+                const functionName = node.children?.find(c => c.type === 'fname')?.text?.trim();
+                const argumentsNode = node.children?.find(c => c.type === 'arguments');
+                if (functionName) {
+                    functionCalls.push({
+                        name: functionName,
+                        arguments: argumentsNode?.children
+                            ?.filter(c => c.type === 'argument')
+                            .map(c => c.text) || []
+                    });
+                }
+            }
+
+            if (node.children) {
+                for (const child of node.children) {
+                    traverse(child);
+                }
+            }
+        };
+
+        traverse(this.ast);
+        return functionCalls;
+    }
+
     /**
      * Prepare the template by replacing variables with their values
      * Rebuilds from AST by iterating through children
@@ -4311,6 +4351,7 @@ module.exports = TemplateFilters;
 },{}],19:[function(require,module,exports){
 const { Parser } = require('ebnf');
 const TemplateGrammar = require('./RuleTemplate.ebnf');
+const TemplateFilters = require('./TemplateFilters');
 const RuleParser = require('@halleyassist/rule-parser');
 const RuleParserRules = RuleParser.ParserRules;
 
@@ -4357,7 +4398,17 @@ class VariableValidate {
             };
         }
 
-        return VariableValidate.validateValue(variableData.type, variableData.value);
+        let normalizedVarData;
+        try {
+            normalizedVarData = VariableValidate._normalizeVarData(variableData);
+        } catch (error) {
+            return {
+                valid: false,
+                error: error.message
+            };
+        }
+
+        return VariableValidate.validateValue(normalizedVarData.type, normalizedVarData.value);
     }
 
     static validateValue(type, value) {
@@ -4424,6 +4475,49 @@ class VariableValidate {
         return ParserCache;
     }
 
+    static _normalizeVarData(variableData) {
+        const normalizedVarData = VariableValidate._cloneVarData(variableData);
+
+        if (!Object.prototype.hasOwnProperty.call(normalizedVarData, 'value')) {
+            throw new Error('Variable data must include a value property');
+        }
+
+        if (!Object.prototype.hasOwnProperty.call(normalizedVarData, 'filters')) {
+            return normalizedVarData;
+        }
+
+        if (!Array.isArray(normalizedVarData.filters)) {
+            throw new Error('Variable data filters must be an array');
+        }
+
+        for (const filterName of normalizedVarData.filters) {
+            if (!TemplateFilters[filterName]) {
+                throw new Error(`Unknown filter '${filterName}'`);
+            }
+
+            TemplateFilters[filterName](normalizedVarData);
+        }
+
+        return normalizedVarData;
+    }
+
+    static _cloneVarData(variableData) {
+        const cloned = Object.assign({}, variableData);
+        if (Array.isArray(cloned.filters)) {
+            cloned.filters = cloned.filters.slice();
+        }
+
+        if (cloned.value && typeof cloned.value === 'object') {
+            if (Array.isArray(cloned.value)) {
+                cloned.value = cloned.value.slice();
+            } else {
+                cloned.value = Object.assign({}, cloned.value);
+            }
+        }
+
+        return cloned;
+    }
+
     static _serializeString(value) {
         if (typeof value !== 'string') {
             return null;
@@ -4654,5 +4748,5 @@ VariableValidate.validators = Object.freeze({
 });
 
 module.exports = VariableValidate;
-},{"./RuleTemplate.ebnf":15,"@halleyassist/rule-parser":2,"ebnf":13}]},{},[14])(14)
+},{"./RuleTemplate.ebnf":15,"./TemplateFilters":18,"@halleyassist/rule-parser":2,"ebnf":13}]},{},[14])(14)
 });

package/index.d.ts

@@ -15,6 +15,7 @@ export interface VariableValue {
         to: string;
         ago?: [number, string];
     } | Record<string, any> | string[] | number[] | boolean[] | Record<string, any>[];
+    filters?: string[];
     type?: 'string' | 'number' | 'boolean' | 'object' | 'time period' | 'time period ago' | 'time value' | 'number time' | 'string array' | 'number array' | 'boolean array' | 'object array';
 }
 
@@ -25,6 +26,7 @@ export interface Variables {
 export interface ValidationResult {
     valid: boolean;
     errors: string[];
+    warnings: string[];
 }
 
 export interface VariableValidationResult {
@@ -59,6 +61,17 @@ export interface TemplateFiltersType {
     [key: string]: FilterFunction;
 }
 
+export interface HalleyFunctionDefinition {
+    name: string;
+    arguments: string[];
+}
+
+export interface HalleyFunctionBlobData {
+    _schema?: number;
+    version?: string;
+    functions?: HalleyFunctionDefinition[];
+}
+
 export class RuleTemplate {
     ruleTemplateText: string;
     ast: ASTNode;
@@ -89,7 +102,7 @@ export class RuleTemplate {
      * @param variables Object mapping variable names to {value, type} objects
      * @returns Object with validation results: {valid, errors}
      */
-    validate(variables: Variables): ValidationResult;
+    validate(variables: Variables, functionBlob?: HalleyFunctionBlob): ValidationResult;
 
     /**
      * Prepare the template by replacing variables with their values
@@ -124,6 +137,18 @@ export class GeneralTemplate {
     prepare(variables: Variables): string;
 }
 
+export class HalleyFunctionBlob {
+    _schema?: number;
+    version?: string;
+    functions: HalleyFunctionDefinition[];
+
+    constructor(jsonData: HalleyFunctionBlobData);
+
+    static fromURL(url: string): Promise<HalleyFunctionBlob>;
+
+    validate(functionName: string, variables?: any[]): string[];
+}
+
 export class VariableTemplate {
     templateText: string;
     ast: ASTNode;

package/index.js

@@ -1,5 +1,6 @@
 const RuleTemplate = require('./src/RuleTemplate');
 const GeneralTemplate = require('./src/GeneralTemplate');
+const HalleyFunctionBlob = require('./src/HalleyFunctionBlob');
 const VariableTemplate = require('./src/VariableTemplate');
 const VariableValidate = require('./src/VariableValidate');
 
@@ -9,4 +10,5 @@ module.exports.VariableTypes = RuleTemplate.VariableTypes;
 module.exports.TemplateFilters = RuleTemplate.TemplateFilters;
 module.exports.VariableValidate = VariableValidate;
 module.exports.GeneralTemplate = GeneralTemplate;
+module.exports.HalleyFunctionBlob = HalleyFunctionBlob;
 module.exports.VariableTemplate = VariableTemplate;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@halleyassist/rule-templater",
-  "version": "0.0.15",
+  "version": "0.0.17",
   "description": "The grammar for HalleyAssist rules",
   "main": "src/RuleTemplate.production.js",
   "browser": "./dist/rule-templater.browser.js",

package/src/HalleyFunctionBlob.js

@@ -0,0 +1,126 @@
+class HalleyFunctionBlob {
+    constructor(jsonData) {
+        const blobData = jsonData && typeof jsonData === 'object' ? jsonData : {};
+
+        this._schema = blobData._schema;
+        this.version = blobData.version;
+        this.functions = [];
+        this.functionMap = new Map();
+
+        const functions = Array.isArray(blobData.functions) ? blobData.functions : [];
+        for (const definition of functions) {
+            if (!definition || typeof definition.name !== 'string') {
+                continue;
+            }
+
+            const normalizedDefinition = {
+                name: definition.name,
+                arguments: Array.isArray(definition.arguments) ? definition.arguments.slice() : []
+            };
+
+            this.functions.push(normalizedDefinition);
+            this.functionMap.set(normalizedDefinition.name, normalizedDefinition);
+        }
+    }
+
+    static async fromURL(url) {
+        if (typeof url !== 'string' || !url.trim()) {
+            throw new Error('A function blob URL must be provided');
+        }
+
+        if (typeof globalThis.fetch !== 'function') {
+            throw new Error('Fetch API is not available');
+        }
+
+        const response = await globalThis.fetch(url);
+        if (!response || !response.ok) {
+            throw new Error(`Failed to fetch function blob from '${url}'`);
+        }
+
+        return new HalleyFunctionBlob(await response.json());
+    }
+
+    validate(functionName, variables = []) {
+        const warnings = [];
+        const functionDefinition = this.functionMap.get(functionName);
+
+        if (!functionDefinition) {
+            return [`function '${functionName}' does not exist`];
+        }
+
+        const providedVariables = Array.isArray(variables) ? variables : [];
+        const providedCount = providedVariables.length;
+        const parameterRange = this._getParameterRange(functionDefinition.arguments);
+
+        for (let idx = 0; idx < functionDefinition.arguments.length; idx++) {
+            const argumentName = functionDefinition.arguments[idx];
+            if (argumentName === '...') {
+                break;
+            }
+
+            if (providedCount > idx || argumentName.endsWith('?')) {
+                continue;
+            }
+
+            warnings.push(
+                `parameter ${idx + 1} of ${functionName} '${argumentName}' is missing, function expects ${parameterRange}`
+            );
+        }
+
+        if (this._hasTooManyArguments(functionDefinition.arguments, providedCount)) {
+            warnings.push(
+                `${functionName} received ${providedCount} parameters, function expects ${parameterRange}`
+            );
+        }
+
+        return warnings;
+    }
+
+    _hasTooManyArguments(argumentList, providedCount) {
+        const { max } = this._getArgumentBounds(argumentList);
+        return max !== Infinity && providedCount > max;
+    }
+
+    _getParameterRange(argumentList) {
+        const { min, max } = this._getArgumentBounds(argumentList);
+
+        if (max === Infinity) {
+            if (min === 0) {
+                return 'any number of parameters';
+            }
+
+            return `at least ${min} ${min === 1 ? 'parameter' : 'parameters'}`;
+        }
+
+        if (min === max) {
+            return `${min} ${min === 1 ? 'parameter' : 'parameters'}`;
+        }
+
+        return `${min} to ${max} parameters`;
+    }
+
+    _getArgumentBounds(argumentList) {
+        let min = 0;
+        let max = 0;
+        let variadic = false;
+
+        for (const argumentName of argumentList) {
+            if (argumentName === '...') {
+                variadic = true;
+                continue;
+            }
+
+            max++;
+            if (!argumentName.endsWith('?')) {
+                min++;
+            }
+        }
+
+        return {
+            min,
+            max: variadic ? Infinity : max
+        };
+    }
+}
+
+module.exports = HalleyFunctionBlob;

package/src/RuleTemplate.js

@@ -215,17 +215,20 @@ class RuleTemplate {
     /**
      * Validate variable types against the AST
      * @param {Object} variables - Object mapping variable names to {type} objects
-     * @returns {Object} Object with validation results: {valid: boolean, errors: []}
+     * @param {Object} [functionBlob] - Optional HalleyFunctionBlob used for non-fatal function warnings
+     * @returns {Object} Object with validation results: {valid: boolean, errors: [], warnings: []}
      */
-    validate(variables) {
+    validate(variables, functionBlob) {
         if (!variables || typeof variables !== 'object') {
             return {
                 valid: false,
-                errors: ['Variables must be provided as an object']
+                errors: ['Variables must be provided as an object'],
+                warnings: []
             };
         }
 
         const errors = [];
+        const warnings = [];
         const extractedVars = this.extractVariables();
         
         for (const varInfo of extractedVars) {
@@ -258,13 +261,50 @@ class RuleTemplate {
                 }
             }
         }
+
+        if (functionBlob && typeof functionBlob.validate === 'function') {
+            for (const functionCall of this._extractFunctionCalls()) {
+                warnings.push(...functionBlob.validate(functionCall.name, functionCall.arguments));
+            }
+        }
         
         return {
             valid: errors.length === 0,
-            errors
+            errors,
+            warnings
         };
     }
 
+    _extractFunctionCalls() {
+        const functionCalls = [];
+
+        const traverse = (node) => {
+            if (!node) return;
+
+            if (node.type === 'fcall') {
+                const functionName = node.children?.find(c => c.type === 'fname')?.text?.trim();
+                const argumentsNode = node.children?.find(c => c.type === 'arguments');
+                if (functionName) {
+                    functionCalls.push({
+                        name: functionName,
+                        arguments: argumentsNode?.children
+                            ?.filter(c => c.type === 'argument')
+                            .map(c => c.text) || []
+                    });
+                }
+            }
+
+            if (node.children) {
+                for (const child of node.children) {
+                    traverse(child);
+                }
+            }
+        };
+
+        traverse(this.ast);
+        return functionCalls;
+    }
+
     /**
      * Prepare the template by replacing variables with their values
      * Rebuilds from AST by iterating through children

package/src/RuleTemplate.production.js

@@ -215,17 +215,20 @@ class RuleTemplate {
     /**
      * Validate variable types against the AST
      * @param {Object} variables - Object mapping variable names to {type} objects
-     * @returns {Object} Object with validation results: {valid: boolean, errors: []}
+     * @param {Object} [functionBlob] - Optional HalleyFunctionBlob used for non-fatal function warnings
+     * @returns {Object} Object with validation results: {valid: boolean, errors: [], warnings: []}
      */
-    validate(variables) {
+    validate(variables, functionBlob) {
         if (!variables || typeof variables !== 'object') {
             return {
                 valid: false,
-                errors: ['Variables must be provided as an object']
+                errors: ['Variables must be provided as an object'],
+                warnings: []
             };
         }
 
         const errors = [];
+        const warnings = [];
         const extractedVars = this.extractVariables();
         
         for (const varInfo of extractedVars) {
@@ -258,13 +261,50 @@ class RuleTemplate {
                 }
             }
         }
+
+        if (functionBlob && typeof functionBlob.validate === 'function') {
+            for (const functionCall of this._extractFunctionCalls()) {
+                warnings.push(...functionBlob.validate(functionCall.name, functionCall.arguments));
+            }
+        }
         
         return {
             valid: errors.length === 0,
-            errors
+            errors,
+            warnings
         };
     }
 
+    _extractFunctionCalls() {
+        const functionCalls = [];
+
+        const traverse = (node) => {
+            if (!node) return;
+
+            if (node.type === 'fcall') {
+                const functionName = node.children?.find(c => c.type === 'fname')?.text?.trim();
+                const argumentsNode = node.children?.find(c => c.type === 'arguments');
+                if (functionName) {
+                    functionCalls.push({
+                        name: functionName,
+                        arguments: argumentsNode?.children
+                            ?.filter(c => c.type === 'argument')
+                            .map(c => c.text) || []
+                    });
+                }
+            }
+
+            if (node.children) {
+                for (const child of node.children) {
+                    traverse(child);
+                }
+            }
+        };
+
+        traverse(this.ast);
+        return functionCalls;
+    }
+
     /**
      * Prepare the template by replacing variables with their values
      * Rebuilds from AST by iterating through children

package/src/VariableValidate.js

@@ -1,5 +1,6 @@
 const { Parser } = require('ebnf');
 const TemplateGrammar = require('./RuleTemplate.ebnf');
+const TemplateFilters = require('./TemplateFilters');
 const RuleParser = require('@halleyassist/rule-parser');
 const RuleParserRules = RuleParser.ParserRules;
 
@@ -46,7 +47,17 @@ class VariableValidate {
             };
         }
 
-        return VariableValidate.validateValue(variableData.type, variableData.value);
+        let normalizedVarData;
+        try {
+            normalizedVarData = VariableValidate._normalizeVarData(variableData);
+        } catch (error) {
+            return {
+                valid: false,
+                error: error.message
+            };
+        }
+
+        return VariableValidate.validateValue(normalizedVarData.type, normalizedVarData.value);
     }
 
     static validateValue(type, value) {
@@ -113,6 +124,49 @@ class VariableValidate {
         return ParserCache;
     }
 
+    static _normalizeVarData(variableData) {
+        const normalizedVarData = VariableValidate._cloneVarData(variableData);
+
+        if (!Object.prototype.hasOwnProperty.call(normalizedVarData, 'value')) {
+            throw new Error('Variable data must include a value property');
+        }
+
+        if (!Object.prototype.hasOwnProperty.call(normalizedVarData, 'filters')) {
+            return normalizedVarData;
+        }
+
+        if (!Array.isArray(normalizedVarData.filters)) {
+            throw new Error('Variable data filters must be an array');
+        }
+
+        for (const filterName of normalizedVarData.filters) {
+            if (!TemplateFilters[filterName]) {
+                throw new Error(`Unknown filter '${filterName}'`);
+            }
+
+            TemplateFilters[filterName](normalizedVarData);
+        }
+
+        return normalizedVarData;
+    }
+
+    static _cloneVarData(variableData) {
+        const cloned = Object.assign({}, variableData);
+        if (Array.isArray(cloned.filters)) {
+            cloned.filters = cloned.filters.slice();
+        }
+
+        if (cloned.value && typeof cloned.value === 'object') {
+            if (Array.isArray(cloned.value)) {
+                cloned.value = cloned.value.slice();
+            } else {
+                cloned.value = Object.assign({}, cloned.value);
+            }
+        }
+
+        return cloned;
+    }
+
     static _serializeString(value) {
         if (typeof value !== 'string') {
             return null;