@onlineapps/cookbook-core 1.0.0

package/src/parser/cookbookValidator.js

@@ -0,0 +1,569 @@
+/**
+ * @fileoverview
+ * Comprehensive validator for Workflow Cookbook JSON objects.
+ *
+ * Validates:
+ *  - Top-level structure against JSON Schema (strict: no additional properties)
+ *  - Recursive validation of each Step object, ensuring all required fields are present and no extraneous fields
+ *  - Unique `id` across all steps (including nested steps in foreach, fork_join, switch, sub_workflow)
+ *  - For TaskStep and DispatchStep: `input` and `output` objects each have at least one mapping, all values are non-empty strings
+ *  - For Retry configurations: `maxAttempts` ≥ 1, `delayMs` ≥ 0
+ *  - For ForeachStep: `iterator` is a non-empty string, `body` is a non-empty array of valid Steps, optional `output` maps have non-empty string values
+ *  - For ForkJoinStep: `branches` is a non-empty array of Steps, `join.strategy` must be "merge", `join.output` has at least one mapping with non-empty string values
+ *  - For SwitchStep: `expression` is non-empty string, `cases` has ≥1 key each mapping to a valid Step, optional `default` is a valid Step
+ *  - For SubWorkflowStep: `input` maps have non-empty string values, `steps` is a non-empty array of valid Steps
+ *  - For WaitStep: `durationMs` is integer ≥ 0
+ *  - For DispatchStep: `method` must be "webhook", `target` must be a valid URI, `input` has ≥1 mappings with non-empty string values, optional `retry` as per Retry schema
+ *  - Ensures no unexpected properties exist on any step object (additionalProperties = false)
+ *
+ * Throws:
+ *  - Error with descriptive message upon first validation failure encountered.
+ *
+ * Usage:
+ *   const { validateCookbook } = require('./cookbookValidator');
+ *   validateCookbook(parsedObject);
+ */
+
+const Ajv = require('ajv');
+const addFormats = require('ajv-formats');
+const path = require('path');
+const fs = require('fs');
+
+// Load schemas dynamically
+const loadSchemaFile = (filename) => {
+  const schemaPath = path.join(__dirname, '../../schemas', filename);
+  if (fs.existsSync(schemaPath)) {
+    return JSON.parse(fs.readFileSync(schemaPath, 'utf-8'));
+  }
+  // Fallback to default schema
+  return JSON.parse(fs.readFileSync(path.join(__dirname, '../../schemas/cookbook.schema.json'), 'utf-8'));
+};
+
+const cookbookSchema = loadSchemaFile('cookbook.schema.json');
+const strictSchema = loadSchemaFile('cookbook.strict.schema.json');
+const relaxedSchema = loadSchemaFile('cookbook.relaxed.schema.json');
+
+// Initialize AJV instance for JSON Schema validation
+// Note: strict: false is needed because our schema uses "condition" as a property name,
+// which would be interpreted as an AJV keyword in strict mode
+const ajv = new Ajv({ allErrors: true, strict: false, allowUnionTypes: true });
+addFormats(ajv);
+
+// Compile schemas for different modes
+const validators = {
+  default: ajv.compile(cookbookSchema),
+  strict: ajv.compile(strictSchema),
+  relaxed: ajv.compile(relaxedSchema)
+};
+
+/**
+ * Custom Error class to represent validation errors in the cookbook.
+ */
+class CookbookValidationError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'CookbookValidationError';
+  }
+}
+
+/**
+ * Validate that a given string is non-empty.
+ * @param {any} val - Value to check.
+ * @param {string} context - Description for error messages.
+ */
+function assertNonEmptyString(val, context) {
+  if (typeof val !== 'string' || val.trim() === '') {
+    throw new CookbookValidationError(`${context} must be a non-empty string.`);
+  }
+}
+
+/**
+ * Validate that a given object has at least one key, and every value is a non-empty string.
+ * @param {object} obj - Object to validate.
+ * @param {string} context - Description for error messages.
+ * @param {boolean} allowEmpty - Whether to allow empty object
+ */
+function assertNonEmptyStringMap(obj, context, allowEmpty = false) {
+  if (typeof obj !== 'object' || obj === null) {
+    throw new CookbookValidationError(`${context} must be an object.`);
+  }
+  const keys = Object.keys(obj);
+  if (!allowEmpty && keys.length < 1) {
+    throw new CookbookValidationError(`${context} must have at least one property.`);
+  }
+  keys.forEach((k) => {
+    const v = obj[k];
+    if (typeof v !== 'string' || v.trim() === '') {
+      throw new CookbookValidationError(`${context}['${k}'] must be a non-empty string.`);
+    }
+  });
+}
+
+/**
+ * Validate Retry configuration: object with integer maxAttempts ≥1 and integer delayMs ≥0, no extra properties.
+ * @param {object} retry - Retry object to validate.
+ * @param {string} context - Description for error messages.
+ */
+function validateRetryConfig(retry, context) {
+  if (typeof retry !== 'object' || retry === null || Array.isArray(retry)) {
+    throw new CookbookValidationError(`${context} must be an object.`);
+  }
+  const allowedProps = ['maxAttempts', 'delayMs'];
+  Object.keys(retry).forEach((prop) => {
+    if (!allowedProps.includes(prop)) {
+      throw new CookbookValidationError(`${context} has unexpected property '${prop}'.`);
+    }
+  });
+  if (!Number.isInteger(retry.maxAttempts) || retry.maxAttempts < 1) {
+    throw new CookbookValidationError(`${context}.maxAttempts must be an integer ≥ 1.`);
+  }
+  if (!Number.isInteger(retry.delayMs) || retry.delayMs < 0) {
+    throw new CookbookValidationError(`${context}.delayMs must be an integer ≥ 0.`);
+  }
+}
+
+/**
+ * Validate a URI string using simple regex for scheme://... . Does not cover every edge case but ensures a scheme and host.
+ * @param {string} uri - URI string to validate.
+ * @param {string} context - Context for error messages.
+ */
+function assertValidUri(uri, context) {
+  // Basic URI regex: scheme://... , e.g. http://example.com or https://api.service/path
+  const uriRegex = /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\/\S+$/;
+  if (!uriRegex.test(uri)) {
+    throw new CookbookValidationError(`${context} ('${uri}') is not a valid URI.`);
+  }
+}
+
+/**
+ * Collects all step IDs from a nested structure of steps. Throws if duplicate IDs found.
+ * @param {Array} steps - Array of Step objects (may contain nested steps).
+ * @param {Set<string>} seenIds - Set to accumulate seen IDs.
+ * @param {string} path - Recursion path for error context.
+ */
+function collectAndValidateUniqueIds(steps, seenIds, path) {
+  if (!Array.isArray(steps)) {
+    throw new CookbookValidationError(`${path} must be an array of steps.`);
+  }
+  steps.forEach((step, index) => {
+    const context = `${path}[${index}]`;
+    if (typeof step !== 'object' || step === null) {
+      throw new CookbookValidationError(`${context} must be an object.`);
+    }
+    // id must exist and be a string
+    if (!('id' in step)) {
+      throw new CookbookValidationError(`${context} is missing required property 'id'.`);
+    }
+    assertNonEmptyString(step.id, `${context}.id`);
+    if (seenIds.has(step.id)) {
+      throw new CookbookValidationError(`Duplicate step ID '${step.id}' found at ${context}.`);
+    }
+    seenIds.add(step.id);
+
+    // Recurse into nested steps according to type
+    const stepType = step.type || 'task';
+    switch (stepType) {
+      case 'foreach':
+        if (!Array.isArray(step.body)) {
+          throw new CookbookValidationError(`${context} of type 'foreach' must have 'body' as an array.`);
+        }
+        collectAndValidateUniqueIds(step.body, seenIds, `${context}.body`);
+        break;
+      case 'fork_join':
+        if (!Array.isArray(step.branches)) {
+          throw new CookbookValidationError(`${context} of type 'fork_join' must have 'branches' as an array.`);
+        }
+        collectAndValidateUniqueIds(step.branches, seenIds, `${context}.branches`);
+        break;
+      case 'switch':
+        // cases: object mapping keys to Step
+        if (typeof step.cases === 'object' && step.cases !== null) {
+          Object.entries(step.cases).forEach(([caseKey, caseStep]) => {
+            collectAndValidateUniqueIds([caseStep], seenIds, `${context}.cases['${caseKey}']`);
+          });
+        }
+        if ('default' in step && step.default) {
+          collectAndValidateUniqueIds([step.default], seenIds, `${context}.default`);
+        }
+        break;
+      case 'sub_workflow':
+        if (!Array.isArray(step.steps)) {
+          throw new CookbookValidationError(`${context} of type 'sub_workflow' must have 'steps' as an array.`);
+        }
+        collectAndValidateUniqueIds(step.steps, seenIds, `${context}.steps`);
+        break;
+      // task, wait, dispatch have no nested steps for id collection
+      case 'task':
+      case 'wait':
+      case 'dispatch':
+        // no nested step arrays
+        break;
+      default:
+        throw new CookbookValidationError(`${context}.type '${stepType}' is not recognized.`);
+    }
+  });
+}
+
+/**
+ * Validate a single Step object deeply according to its `type`.
+ * @param {object} step - The Step object to validate.
+ * @param {string} context - String prefix describing location in the cookbook for error context.
+ * @param {string} mode - Validation mode (strict, relaxed, default)
+ */
+function validateStep(step, context, mode = 'default') {
+  if (typeof step !== 'object' || step === null) {
+    throw new CookbookValidationError(`${context} must be an object.`);
+  }
+
+  // Validate required properties: id is required, type is optional (defaults to 'task')
+  if (!('id' in step)) {
+    throw new CookbookValidationError(`${context} is missing required property 'id'.`);
+  }
+  assertNonEmptyString(step.id, `${context}.id`);
+
+  // Type is optional, defaults to 'task' for simple service calls
+  const stepType = step.type || 'task';
+  if (step.type) {
+    assertNonEmptyString(step.type, `${context}.type`);
+  }
+
+  // Ensure no additional properties beyond { id, type, and those allowed per type }
+  const commonAllowed = new Set(['id', 'type']);
+  let allowedProps = new Set(commonAllowed);
+
+  switch (stepType) {
+    case 'task': {
+      // Required: service (input/output now optional)
+      const req = mode === 'strict' ? ['service'] : ['service'];
+      req.forEach((prop) => {
+        if (!(prop in step)) {
+          throw new CookbookValidationError(`${context} of type 'task' is missing required property '${prop}'.`);
+        }
+      });
+      // Validate service
+      assertNonEmptyString(step.service, `${context}.service`);
+
+      // Validate input and output maps - now optional in updated schema
+      if ('input' in step) {
+        assertNonEmptyStringMap(step.input, `${context}.input`, true);
+      }
+      if ('output' in step) {
+        assertNonEmptyStringMap(step.output, `${context}.output`, true);
+      }
+
+      // Optional properties
+      if ('name' in step) {
+        assertNonEmptyString(step.name, `${context}.name`);
+      }
+      if ('action' in step) {
+        const validActions = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'];
+        if (!validActions.includes(step.action)) {
+          throw new CookbookValidationError(`${context}.action must be one of: ${validActions.join(', ')}`);
+        }
+      }
+      if ('endpoint' in step) {
+        assertNonEmptyString(step.endpoint, `${context}.endpoint`);
+      }
+      if ('depends_on' in step) {
+        if (!Array.isArray(step.depends_on)) {
+          throw new CookbookValidationError(`${context}.depends_on must be an array.`);
+        }
+        step.depends_on.forEach((dep, idx) => {
+          assertNonEmptyString(dep, `${context}.depends_on[${idx}]`);
+        });
+      }
+      if ('retry' in step) {
+        validateRetryConfig(step.retry, `${context}.retry`);
+      }
+      if ('timeoutMs' in step) {
+        if (!Number.isInteger(step.timeoutMs) || step.timeoutMs < 1) {
+          throw new CookbookValidationError(`${context}.timeoutMs must be an integer ≥ 1.`);
+        }
+      }
+
+      allowedProps = new Set([...commonAllowed, 'name', 'service', 'action', 'endpoint', 'input', 'output', 'depends_on', 'retry', 'timeoutMs']);
+      break;
+    }
+    case 'foreach': {
+      // Required: iterator, body
+      const req = ['iterator', 'body'];
+      req.forEach((prop) => {
+        if (!(prop in step)) {
+          throw new CookbookValidationError(`${context} of type 'foreach' is missing required property '${prop}'.`);
+        }
+      });
+      assertNonEmptyString(step.iterator, `${context}.iterator`);
+
+      if (!Array.isArray(step.body) || step.body.length < 1) {
+        throw new CookbookValidationError(`${context}.body must be a non-empty array of Step objects.`);
+      }
+      // Recursively validate each nested step in body
+      step.body.forEach((childStep, idx) => {
+        validateStep(childStep, `${context}.body[${idx}]`, mode);
+      });
+
+      // Optional properties
+      if ('name' in step) {
+        assertNonEmptyString(step.name, `${context}.name`);
+      }
+      if ('output' in step) {
+        assertNonEmptyStringMap(step.output, `${context}.output`);
+      }
+
+      allowedProps = new Set([...commonAllowed, 'name', 'iterator', 'body', 'output']);
+      break;
+    }
+    case 'fork_join': {
+      // Required: branches, join
+      const req = ['branches', 'join'];
+      req.forEach((prop) => {
+        if (!(prop in step)) {
+          throw new CookbookValidationError(`${context} of type 'fork_join' is missing required property '${prop}'.`);
+        }
+      });
+      if (!Array.isArray(step.branches) || step.branches.length < 1) {
+        throw new CookbookValidationError(`${context}.branches must be a non-empty array of Step objects.`);
+      }
+      // Recursively validate each branch
+      step.branches.forEach((branchStep, idx) => {
+        validateStep(branchStep, `${context}.branches[${idx}]`, mode);
+      });
+
+      const join = step.join;
+      if (typeof join !== 'object' || join === null) {
+        throw new CookbookValidationError(`${context}.join must be an object.`);
+      }
+      // Validate join.strategy
+      const validStrategies = ['merge', 'first', 'last', 'all', 'custom'];
+      if (!validStrategies.includes(join.strategy)) {
+        throw new CookbookValidationError(`${context}.join.strategy must be one of: ${validStrategies.join(', ')}`);
+      }
+      // Validate join.output if present (now optional)
+      if ('output' in join) {
+        assertNonEmptyStringMap(join.output, `${context}.join.output`, true);
+      }
+
+      // Ensure no additional props on join
+      const joinAllowed = new Set(['strategy', 'output']);
+      Object.keys(join).forEach((prop) => {
+        if (!joinAllowed.has(prop)) {
+          throw new CookbookValidationError(`${context}.join has unexpected property '${prop}'.`);
+        }
+      });
+
+      // Optional properties
+      if ('name' in step) {
+        assertNonEmptyString(step.name, `${context}.name`);
+      }
+
+      allowedProps = new Set([...commonAllowed, 'name', 'branches', 'join']);
+      break;
+    }
+    case 'switch': {
+      // Required: expression, cases, and default in strict mode
+      const req = mode === 'strict' ? ['expression', 'cases', 'default'] : ['expression', 'cases'];
+      req.forEach((prop) => {
+        if (!(prop in step)) {
+          throw new CookbookValidationError(`${context} of type 'switch' is missing required property '${prop}'.`);
+        }
+      });
+      assertNonEmptyString(step.expression, `${context}.expression`);
+
+      if (typeof step.cases !== 'object' || step.cases === null) {
+        throw new CookbookValidationError(`${context}.cases must be an object with ≥1 key.`);
+      }
+      const caseKeys = Object.keys(step.cases);
+      if (caseKeys.length < 1) {
+        throw new CookbookValidationError(`${context}.cases must have at least one case.`);
+      }
+      // Validate each case's Step
+      caseKeys.forEach((caseKey) => {
+        const caseStep = step.cases[caseKey];
+        validateStep(caseStep, `${context}.cases['${caseKey}']`, mode);
+      });
+
+      // Optional properties
+      if ('name' in step) {
+        assertNonEmptyString(step.name, `${context}.name`);
+      }
+      if ('depends_on' in step) {
+        if (!Array.isArray(step.depends_on)) {
+          throw new CookbookValidationError(`${context}.depends_on must be an array.`);
+        }
+        step.depends_on.forEach((dep, idx) => {
+          assertNonEmptyString(dep, `${context}.depends_on[${idx}]`);
+        });
+      }
+      if ('default' in step) {
+        validateStep(step.default, `${context}.default`, mode);
+      } else if (mode === 'strict') {
+        throw new CookbookValidationError(`${context} of type 'switch' in strict mode must have a 'default' case.`);
+      }
+
+      allowedProps = new Set([...commonAllowed, 'name', 'expression', 'cases', 'default', 'depends_on']);
+      break;
+    }
+    case 'sub_workflow': {
+      // Required: steps (input now optional)
+      const req = ['steps'];
+      req.forEach((prop) => {
+        if (!(prop in step)) {
+          throw new CookbookValidationError(`${context} of type 'sub_workflow' is missing required property '${prop}'.`);
+        }
+      });
+      // Validate input map if present
+      if ('input' in step) {
+        assertNonEmptyStringMap(step.input, `${context}.input`, true);
+      }
+
+      // Validate nested steps
+      if (!Array.isArray(step.steps) || step.steps.length < 1) {
+        throw new CookbookValidationError(`${context}.steps must be a non-empty array of Step objects.`);
+      }
+      step.steps.forEach((childStep, idx) => {
+        validateStep(childStep, `${context}.steps[${idx}]`, mode);
+      });
+
+      // Optional properties
+      if ('name' in step) {
+        assertNonEmptyString(step.name, `${context}.name`);
+      }
+
+      allowedProps = new Set([...commonAllowed, 'name', 'input', 'steps']);
+      break;
+    }
+    case 'wait': {
+      // Required: durationMs
+      if (!('durationMs' in step)) {
+        throw new CookbookValidationError(`${context} of type 'wait' is missing required property 'durationMs'.`);
+      }
+      if (!Number.isInteger(step.durationMs) || step.durationMs < 0) {
+        throw new CookbookValidationError(`${context}.durationMs must be an integer ≥ 0.`);
+      }
+      // Optional properties
+      if ('name' in step) {
+        assertNonEmptyString(step.name, `${context}.name`);
+      }
+      allowedProps = new Set([...commonAllowed, 'name', 'durationMs']);
+      break;
+    }
+    case 'dispatch': {
+      // Required: method, target (input now optional)
+      const req = ['method', 'target'];
+      req.forEach((prop) => {
+        if (!(prop in step)) {
+          throw new CookbookValidationError(`${context} of type 'dispatch' is missing required property '${prop}'.`);
+        }
+      });
+      // method must be valid
+      const validMethods = ['webhook', 'http', 'grpc', 'kafka', 'sqs', 'custom'];
+      if (!validMethods.includes(step.method)) {
+        throw new CookbookValidationError(`${context}.method must be one of: ${validMethods.join(', ')}`);
+      }
+      // target must be valid URI
+      assertValidUri(step.target, `${context}.target`);
+      // input map if present
+      if ('input' in step) {
+        assertNonEmptyStringMap(step.input, `${context}.input`, true);
+      }
+      // Optional: retry
+      if ('retry' in step) {
+        validateRetryConfig(step.retry, `${context}.retry`);
+      }
+      // Optional properties
+      if ('name' in step) {
+        assertNonEmptyString(step.name, `${context}.name`);
+      }
+
+      allowedProps = new Set([...commonAllowed, 'name', 'method', 'target', 'input', 'retry']);
+      break;
+    }
+    default:
+      throw new CookbookValidationError(`${context}.type '${stepType}' is not a supported step type.`);
+  }
+
+  // Finally, ensure no additional unexpected properties on this step object
+  Object.keys(step).forEach((prop) => {
+    if (!allowedProps.has(prop)) {
+      throw new CookbookValidationError(`${context} has unexpected property '${prop}'.`);
+    }
+  });
+}
+
+/**
+ * Main entrypoint: Validate an entire workbook JSON object.
+ * Throws CookbookValidationError on first error encountered.
+ * @param {object} cookbook - Parsed JSON object for the cookbook.
+ * @param {object} options - Validation options
+ * @param {string} options.mode - Validation mode: 'strict', 'relaxed', or 'default'
+ * @param {string} options.schemaVersion - Schema version to use (for migration)
+ * @param {boolean} options.warnOnly - If true, log warnings instead of throwing
+ */
+function validateCookbook(cookbook, options = {}) {
+  const mode = options.mode || 'default';
+  const warnOnly = options.warnOnly || false;
+  // Top-level type must be object
+  if (typeof cookbook !== 'object' || cookbook === null || Array.isArray(cookbook)) {
+    throw new CookbookValidationError(`Cookbook must be a JSON object.`);
+  }
+
+  // Select validator based on mode
+  const validateSchema = validators[mode] || validators.default;
+
+  // Validate against JSON Schema (structure, required top-level props, basic types)
+  const valid = validateSchema(cookbook);
+  if (!valid) {
+    // Collect all errors for better debugging
+    const errors = validateSchema.errors.map(err => {
+      return `${err.instancePath || 'cookbook'} ${err.message}`;
+    });
+    const message = `Schema validation errors (${mode} mode):\n${errors.join('\n')}`;
+
+    if (warnOnly) {
+      console.warn(`WARNING: ${message}`);
+    } else {
+      throw new CookbookValidationError(message);
+    }
+  }
+
+  // Collect and validate unique IDs across all nested steps
+  const seenIds = new Set();
+  collectAndValidateUniqueIds(cookbook.steps, seenIds, 'steps');
+
+  // Validate each top-level Step deeply (skip in relaxed mode)
+  if (mode !== 'relaxed') {
+    cookbook.steps.forEach((step, idx) => {
+      try {
+        validateStep(step, `steps[${idx}]`, mode);
+      } catch (err) {
+        if (warnOnly) {
+          console.warn(`WARNING: ${err.message}`);
+        } else {
+          throw err;
+        }
+      }
+    });
+  }
+
+  // Validate references if not in relaxed mode
+  if (mode !== 'relaxed' && options.validateReferences !== false) {
+    try {
+      const { validateAllReferences } = require('../referenceValidator');
+      validateAllReferences(cookbook);
+    } catch (err) {
+      if (warnOnly) {
+        console.warn(`WARNING: Reference validation error: ${err.message}`);
+      } else {
+        throw new CookbookValidationError(`Reference validation error: ${err.message}`);
+      }
+    }
+  }
+
+  // If we reach this point, the cookbook is valid
+}
+
+module.exports = {
+  validateCookbook,
+  validateStep,
+  CookbookValidationError,
+};

package/src/parser.js

@@ -0,0 +1,7 @@
+'use strict';
+
+/**
+ * Re-export parser functions from the parser module
+ */
+
+module.exports = require('./parser/cookbookParser');