@onlineapps/cookbook-core 1.0.0

package/src/referenceValidator.js

@@ -0,0 +1,317 @@
+'use strict';
+
+/**
+ * Reference validation utilities for cookbook schemas.
+ * Validates that depends_on references exist and variable paths are valid.
+ */
+
+/**
+ * Extract all step IDs from a cookbook recursively
+ * @param {Array} steps - Array of steps
+ * @param {Set} ids - Set to collect IDs
+ * @returns {Set} Set of all step IDs
+ */
+function collectAllStepIds(steps, ids = new Set()) {
+  if (!Array.isArray(steps)) return ids;
+
+  steps.forEach(step => {
+    if (step && typeof step === 'object' && step.id) {
+      ids.add(step.id);
+
+      // Recursively collect from nested structures
+      switch (step.type) {
+        case 'foreach':
+          if (step.body) collectAllStepIds(step.body, ids);
+          break;
+
+        case 'fork_join':
+          if (step.branches) collectAllStepIds(step.branches, ids);
+          break;
+
+        case 'switch':
+          if (step.cases && typeof step.cases === 'object') {
+            Object.values(step.cases).forEach(caseStep => {
+              if (caseStep) collectAllStepIds([caseStep], ids);
+            });
+          }
+          if (step.default) collectAllStepIds([step.default], ids);
+          break;
+
+        case 'sub_workflow':
+          if (step.steps) collectAllStepIds(step.steps, ids);
+          break;
+      }
+    }
+  });
+
+  return ids;
+}
+
+/**
+ * Validate that all depends_on references point to existing step IDs
+ * @param {Object} cookbook - The cookbook to validate
+ * @throws {Error} If invalid references are found
+ */
+function validateDependsOnReferences(cookbook) {
+  if (!cookbook || !cookbook.steps) return;
+
+  // Collect all valid step IDs
+  const validIds = collectAllStepIds(cookbook.steps);
+
+  // Check all depends_on references
+  const checkDependsOn = (steps, path = 'steps') => {
+    if (!Array.isArray(steps)) return;
+
+    steps.forEach((step, index) => {
+      const stepPath = `${path}[${index}]`;
+
+      if (step.depends_on && Array.isArray(step.depends_on)) {
+        step.depends_on.forEach((depId, depIndex) => {
+          if (!validIds.has(depId)) {
+            throw new Error(
+              `Invalid depends_on reference at ${stepPath}.depends_on[${depIndex}]: ` +
+              `Step ID '${depId}' does not exist`
+            );
+          }
+        });
+      }
+
+      // Check nested steps
+      switch (step.type) {
+        case 'foreach':
+          if (step.body) checkDependsOn(step.body, `${stepPath}.body`);
+          break;
+
+        case 'fork_join':
+          if (step.branches) checkDependsOn(step.branches, `${stepPath}.branches`);
+          break;
+
+        case 'switch':
+          if (step.cases && typeof step.cases === 'object') {
+            Object.entries(step.cases).forEach(([caseKey, caseStep]) => {
+              checkDependsOn([caseStep], `${stepPath}.cases['${caseKey}']`);
+            });
+          }
+          if (step.default) checkDependsOn([step.default], `${stepPath}.default`);
+          break;
+
+        case 'sub_workflow':
+          if (step.steps) checkDependsOn(step.steps, `${stepPath}.steps`);
+          break;
+      }
+    });
+  };
+
+  checkDependsOn(cookbook.steps);
+}
+
+/**
+ * Validate variable references in cookbook
+ * @param {Object} cookbook - The cookbook to validate
+ * @throws {Error} If invalid variable references are found
+ */
+function validateVariableReferences(cookbook) {
+  if (!cookbook || !cookbook.steps) return;
+
+  // Collect valid variable paths
+  const validPaths = new Set([
+    '$api_input',
+    '$global_error',
+    '$_loop_item',
+    '$_loop_index',
+    '$_parent',
+    '$_context'
+  ]);
+
+  // Add step output paths
+  const stepIds = collectAllStepIds(cookbook.steps);
+  stepIds.forEach(id => {
+    validPaths.add(`$steps.${id}`);
+    validPaths.add(`$.${id}`);
+  });
+
+  // Check variable references in strings
+  const checkVariableRef = (value, path) => {
+    if (typeof value === 'string') {
+      // Find all variable references ($ followed by word characters or dots)
+      const matches = value.match(/\$[\w\.]+/g);
+      if (matches) {
+        matches.forEach(match => {
+          // Extract base path (before any property access)
+          const basePath = match.split('.')[0];
+
+          // Check if it's a step reference
+          if (match.startsWith('$steps.')) {
+            const stepId = match.split('.')[1];
+            if (!stepIds.has(stepId)) {
+              throw new Error(
+                `Invalid variable reference at ${path}: ` +
+                `Step '${stepId}' does not exist in '${match}'`
+              );
+            }
+          }
+        });
+      }
+    } else if (typeof value === 'object' && value !== null) {
+      // Recursively check object properties
+      Object.entries(value).forEach(([key, val]) => {
+        checkVariableRef(val, `${path}.${key}`);
+      });
+    }
+  };
+
+  // Check all string values in steps
+  const checkStep = (step, path) => {
+    if (!step || typeof step !== 'object') return;
+
+    // Check common string fields
+    ['condition', 'expression', 'iterator', 'errorOutput'].forEach(field => {
+      if (step[field]) {
+        checkVariableRef(step[field], `${path}.${field}`);
+      }
+    });
+
+    // Check input/output mappings
+    ['input', 'output'].forEach(field => {
+      if (step[field]) {
+        checkVariableRef(step[field], `${path}.${field}`);
+      }
+    });
+
+    // Check nested steps
+    switch (step.type) {
+      case 'foreach':
+        if (step.body) {
+          step.body.forEach((s, i) => checkStep(s, `${path}.body[${i}]`));
+        }
+        break;
+
+      case 'fork_join':
+        if (step.branches) {
+          step.branches.forEach((s, i) => checkStep(s, `${path}.branches[${i}]`));
+        }
+        break;
+
+      case 'switch':
+        if (step.cases) {
+          Object.entries(step.cases).forEach(([k, s]) => {
+            checkStep(s, `${path}.cases['${k}']`);
+          });
+        }
+        if (step.default) {
+          checkStep(step.default, `${path}.default`);
+        }
+        break;
+
+      case 'sub_workflow':
+        if (step.steps) {
+          step.steps.forEach((s, i) => checkStep(s, `${path}.steps[${i}]`));
+        }
+        break;
+    }
+  };
+
+  cookbook.steps.forEach((step, index) => {
+    checkStep(step, `steps[${index}]`);
+  });
+}
+
+/**
+ * Validate error handler references
+ * @param {Object} cookbook - The cookbook to validate
+ * @throws {Error} If invalid error handler references are found
+ */
+function validateErrorHandlerReferences(cookbook) {
+  if (!cookbook || !cookbook.steps) return;
+
+  const validIds = collectAllStepIds(cookbook.steps);
+
+  const checkErrorHandler = (handler, path) => {
+    if (!handler || typeof handler !== 'object') return;
+
+    // Check fallbackStep reference
+    if (handler.fallbackStep && !validIds.has(handler.fallbackStep)) {
+      throw new Error(
+        `Invalid error handler reference at ${path}.fallbackStep: ` +
+        `Step ID '${handler.fallbackStep}' does not exist`
+      );
+    }
+
+    // Check compensationStep reference
+    if (handler.compensationStep && !validIds.has(handler.compensationStep)) {
+      throw new Error(
+        `Invalid error handler reference at ${path}.compensationStep: ` +
+        `Step ID '${handler.compensationStep}' does not exist`
+      );
+    }
+  };
+
+  // Check global error handler
+  if (cookbook.global_error_handler) {
+    checkErrorHandler(cookbook.global_error_handler, 'global_error_handler');
+  }
+
+  // Check step error handlers
+  const checkStep = (step, path) => {
+    if (!step || typeof step !== 'object') return;
+
+    if (step.on_error) {
+      checkErrorHandler(step.on_error, `${path}.on_error`);
+    }
+
+    // Check nested steps
+    switch (step.type) {
+      case 'foreach':
+        if (step.body) {
+          step.body.forEach((s, i) => checkStep(s, `${path}.body[${i}]`));
+        }
+        break;
+
+      case 'fork_join':
+        if (step.branches) {
+          step.branches.forEach((s, i) => checkStep(s, `${path}.branches[${i}]`));
+        }
+        break;
+
+      case 'switch':
+        if (step.cases) {
+          Object.entries(step.cases).forEach(([k, s]) => {
+            checkStep(s, `${path}.cases['${k}']`);
+          });
+        }
+        if (step.default) {
+          checkStep(step.default, `${path}.default`);
+        }
+        break;
+
+      case 'sub_workflow':
+        if (step.steps) {
+          step.steps.forEach((s, i) => checkStep(s, `${path}.steps[${i}]`));
+        }
+        break;
+    }
+  };
+
+  cookbook.steps.forEach((step, index) => {
+    checkStep(step, `steps[${index}]`);
+  });
+}
+
+/**
+ * Validate all references in a cookbook
+ * @param {Object} cookbook - The cookbook to validate
+ * @throws {Error} If any invalid references are found
+ */
+function validateAllReferences(cookbook) {
+  validateDependsOnReferences(cookbook);
+  validateVariableReferences(cookbook);
+  validateErrorHandlerReferences(cookbook);
+}
+
+module.exports = {
+  collectAllStepIds,
+  validateDependsOnReferences,
+  validateVariableReferences,
+  validateErrorHandlerReferences,
+  validateAllReferences
+};

package/src/schema.js

@@ -0,0 +1,46 @@
+'use strict';
+
+/**
+ * Schema access utilities
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * Load the cookbook JSON schema
+ * @param {string} mode - Schema mode: 'default', 'strict', 'relaxed'
+ * @returns {Object} The cookbook schema object
+ */
+function loadSchema(mode = 'default') {
+  let schemaFile;
+  switch (mode) {
+    case 'strict':
+      schemaFile = 'cookbook.strict.schema.json';
+      break;
+    case 'relaxed':
+      schemaFile = 'cookbook.relaxed.schema.json';
+      break;
+    default:
+      schemaFile = 'cookbook.schema.json';
+  }
+
+  const schemaPath = path.join(__dirname, '../schemas', schemaFile);
+
+  // Check if file exists
+  if (!fs.existsSync(schemaPath)) {
+    // Fall back to default schema
+    const defaultPath = path.join(__dirname, '../schemas/cookbook.schema.json');
+    return JSON.parse(fs.readFileSync(defaultPath, 'utf-8'));
+  }
+
+  return JSON.parse(fs.readFileSync(schemaPath, 'utf-8'));
+}
+
+// Pre-load the default schema
+const CookbookSchema = loadSchema();
+
+module.exports = {
+  CookbookSchema,
+  loadSchema
+};

package/src/validator.js

@@ -0,0 +1,17 @@
+'use strict';
+
+/**
+ * Re-export validator functions from the parser module
+ */
+
+const {
+  validateCookbook,
+  validateStep,
+  CookbookValidationError
+} = require('./parser/cookbookValidator');
+
+module.exports = {
+  validateCookbook,
+  validateStep,
+  CookbookValidationError
+};