@divmain/jdm-asm 0.2.0

package/src/compiler/compile-time-validation.ts

@@ -0,0 +1,507 @@
+/**
+ * Compile-time validation for decision models.
+ *
+ * This module provides functions to perform static analysis of JDM structure
+ * and references at compile time. These checks detect missing references,
+ * undeclared identifiers, and unassigned outputs before code generation.
+ *
+ * These functions operate on ASTs and CompilationContext - they do NOT
+ * execute at runtime. For runtime data validation, see runtime-validation-codegen.ts.
+ */
+
+import type { ExpressionAST, Identifier } from './ast-types';
+import { CompilationError, ErrorCode, ErrorCollector, type SourceLocation } from './errors';
+import type { CompilationContext } from './types';
+
+/**
+ * Collect all identifier references from an expression AST.
+ *
+ * This function walks the AST and collects all variable/field references
+ * that need to be resolved from the context. It handles:
+ * - Simple identifiers: `age`, `name`
+ * - Member access: `customer.age`, `order.items[0].price`
+ *
+ * @param ast - The expression AST to analyze
+ * @returns Set of all identifier names referenced in the expression
+ */
+export function collectIdentifiers(ast: ExpressionAST): Set<string> {
+  const identifiers = new Set<string>();
+  collectIdentifiersRecursive(ast, identifiers);
+  return identifiers;
+}
+
+/**
+ * Recursively collect identifiers from an AST node.
+ */
+function collectIdentifiersRecursive(ast: ExpressionAST, identifiers: Set<string>): void {
+  switch (ast.type) {
+    case 'Identifier': {
+      const ident = ast as Identifier;
+      identifiers.add(ident.name);
+      break;
+    }
+
+    case 'MemberAccess':
+      // For member access like `customer.age`, we need to track the base object `customer`
+      collectIdentifiersRecursive((ast as any).object, identifiers);
+      // The property name is a literal, not an identifier
+      break;
+
+    case 'IndexAccess':
+      // For index access like `items[0]`, we need the base object
+      collectIdentifiersRecursive((ast as any).object, identifiers);
+      // The index is an expression that may contain identifiers
+      collectIdentifiersRecursive((ast as any).index, identifiers);
+      break;
+
+    case 'BinaryOp':
+      collectIdentifiersRecursive((ast as any).left, identifiers);
+      collectIdentifiersRecursive((ast as any).right, identifiers);
+      break;
+
+    case 'UnaryOp':
+      collectIdentifiersRecursive((ast as any).operand, identifiers);
+      break;
+
+    case 'TernaryOp':
+      collectIdentifiersRecursive((ast as any).condition, identifiers);
+      collectIdentifiersRecursive((ast as any).consequent, identifiers);
+      collectIdentifiersRecursive((ast as any).alternate, identifiers);
+      break;
+
+    case 'FunctionCall':
+      collectIdentifiersRecursive((ast as any).callee, identifiers);
+      for (const arg of (ast as any).args) {
+        collectIdentifiersRecursive(arg, identifiers);
+      }
+      break;
+
+    case 'ArrayLiteral':
+      for (const element of (ast as any).elements) {
+        collectIdentifiersRecursive(element, identifiers);
+      }
+      break;
+
+    case 'ObjectLiteral':
+      for (const [_key, value] of Object.entries((ast as any).properties)) {
+        collectIdentifiersRecursive(value as ExpressionAST, identifiers);
+      }
+      break;
+
+    case 'TemplateLiteral':
+      for (const part of (ast as any).parts) {
+        if (typeof part === 'object') {
+          // It's an expression
+          collectIdentifiersRecursive(part as ExpressionAST, identifiers);
+        }
+        // String literals are ignored
+      }
+      break;
+
+    case 'Interval':
+      collectIdentifiersRecursive((ast as any).start, identifiers);
+      collectIdentifiersRecursive((ast as any).end, identifiers);
+      break;
+
+    // Literals don't reference identifiers
+    case 'NumberLiteral':
+    case 'StringLiteral':
+    case 'BooleanLiteral':
+    case 'NullLiteral':
+    case 'DollarRef':
+    case 'HashRef':
+      // No identifiers to collect
+      break;
+
+    default:
+      throw new Error(`Unknown AST node type: ${(ast as any).type}`);
+  }
+}
+
+/**
+ * Validate that all referenced identifiers exist in the input schema.
+ *
+ * This function checks that all input references in expressions are declared
+ * in the input schema. It builds a set of expected input fields from the
+ * flattened layout and compares it against the identifiers used in expressions.
+ *
+ * @param referencedIdentifiers - Set of identifiers used in expressions
+ * @param context - The compilation context containing the input schema
+ * @param location - Source location for error reporting
+ * @throws CompilationError if any referenced input is not declared
+ */
+export function validateInputReferences(
+  referencedIdentifiers: Set<string>,
+  context: CompilationContext,
+  location?: SourceLocation,
+): void {
+  // Build a set of all expected input fields from the flattened layout
+  const expectedInputs = new Set<string>();
+
+  // Add all top-level fields (e.g., "age", "name", "customer")
+  for (const field of context.inputLayout.fields) {
+    const parts = field.path.split('.');
+    expectedInputs.add(parts[0]); // Add the top-level field name
+
+    // Also add the full path for cases like "customer.age"
+    expectedInputs.add(field.path);
+  }
+
+  // Check each referenced identifier
+  const missingInputs: string[] = [];
+
+  for (const identifier of referencedIdentifiers) {
+    // $ is the unary context variable in decision table cells, # is the iteration variable
+    // in higher-order functions (map, filter, etc.). Both are implicit and don't need schema
+    // declaration.
+    if (identifier === '$' || identifier === '#') {
+      continue;
+    }
+
+    // Check if this identifier is declared
+    let found = false;
+    // Check exact match first
+    if (expectedInputs.has(identifier)) {
+      found = true;
+    } else {
+      // Check if it's a prefix match (e.g., "customer" matches "customer.age")
+      for (const expected of expectedInputs) {
+        if (expected.startsWith(identifier + '.')) {
+          found = true;
+          break;
+        }
+      }
+    }
+
+    if (!found) {
+      missingInputs.push(identifier);
+    }
+  }
+
+  // If we found missing inputs, throw an error
+  if (missingInputs.length > 0) {
+    const missingList = missingInputs
+      .sort()
+      .map((id) => `"${id}"`)
+      .join(', ');
+    const message =
+      missingInputs.length === 1
+        ? `Input reference "${missingInputs[0]}" is not declared in the input schema`
+        : `Input references are not declared in the input schema: ${missingList}`;
+
+    throw new CompilationError(
+      message,
+      ErrorCode.UNKNOWN_FIELD,
+      {
+        ...location,
+        field: 'inputs',
+      },
+      { missingInputs: missingInputs as any },
+    );
+  }
+}
+
+/**
+ * Collect all output assignments from a decision.
+ *
+ * This function walks through all nodes in the decision and collects
+ * the output paths that are assigned by expression nodes and decision table nodes.
+ *
+ * @param context - The compilation context
+ * @returns Set of all output paths assigned by the decision
+ */
+export function collectOutputAssignments(
+  context: CompilationContext,
+  errorCollector?: ErrorCollector,
+): Set<string> {
+  const assignedOutputs = new Set<string>();
+
+  for (const node of context.jdm.nodes) {
+    const nodeType = node.type;
+
+    try {
+      if (nodeType === 'expressionNode') {
+        // Collect output assignments from expression nodes
+        const expressions = node.content.expressions as Array<{ key: string; value: string }>;
+        for (const expr of expressions) {
+          assignedOutputs.add(expr.key);
+        }
+      } else if (nodeType === 'decisionTableNode') {
+        // Collect output fields from decision table nodes
+        const content = node.content as any;
+        if (content.outputs) {
+          for (const output of content.outputs) {
+            if (output.field) {
+              assignedOutputs.add(output.field);
+            }
+          }
+        }
+      }
+      // Switch nodes and sub-decision nodes delegate to other nodes which will be processed
+      // separately, so their outputs will be collected from those target nodes.
+    } catch (error) {
+      // Collect errors for batch reporting rather than swallowing them silently
+      if (errorCollector) {
+        const err =
+          error instanceof CompilationError
+            ? error
+            : new CompilationError(
+                `Failed to collect output assignments from node "${node.name || node.id}": ${error instanceof Error ? error.message : String(error)}`,
+                ErrorCode.PARSE_ERROR,
+                { nodeId: node.id, nodeName: node.name },
+              );
+        errorCollector.add(err);
+      }
+    }
+  }
+
+  return assignedOutputs;
+}
+
+/**
+ * Validate that all expected outputs from the schema are assigned.
+ *
+ * This function checks that all output fields defined in the output schema
+ * are actually assigned by the decision logic. It builds a set of expected
+ * output fields from the flattened layout and compares it against the
+ * outputs that are assigned by expression nodes and decision table nodes.
+ *
+ * @param assignedOutputs - Set of output paths assigned by the decision
+ * @param context - The compilation context containing the output schema
+ * @param location - Source location for error reporting
+ * @throws CompilationError if any expected output is not assigned
+ */
+export function validateOutputReferences(
+  assignedOutputs: Set<string>,
+  context: CompilationContext,
+  location?: SourceLocation,
+): void {
+  // Build a set of all expected output fields from the flattened layout
+  const expectedOutputs = new Set<string>();
+
+  // Add all output fields from the layout
+  for (const field of context.outputLayout.fields) {
+    expectedOutputs.add(field.path);
+  }
+
+  // Check each expected output
+  const missingOutputs: string[] = [];
+
+  for (const output of expectedOutputs) {
+    // Prefix matching handles nested object assignment - if schema expects "customer" but decision
+    // assigns "customer.name" and "customer.age", those partial assignments satisfy the requirement
+    let found = false;
+
+    // Check exact match
+    if (assignedOutputs.has(output)) {
+      found = true;
+    } else {
+      // Check if any assigned output is a nested field of the expected output
+      // e.g., if "customer" is expected and "customer.name" is assigned
+      for (const assigned of assignedOutputs) {
+        if (assigned.startsWith(output + '.')) {
+          found = true;
+          break;
+        }
+      }
+    }
+
+    if (!found) {
+      missingOutputs.push(output);
+    }
+  }
+
+  // If we found missing outputs, throw an error
+  if (missingOutputs.length > 0) {
+    const missingList = missingOutputs
+      .sort()
+      .map((field) => `"${field}"`)
+      .join(', ');
+    const message =
+      missingOutputs.length === 1
+        ? `Output field "${missingOutputs[0]}" is declared in the output schema but not assigned by the decision`
+        : `Output fields are declared in the output schema but not assigned by the decision: ${missingList}`;
+
+    throw new CompilationError(
+      message,
+      ErrorCode.UNKNOWN_FIELD,
+      {
+        ...location,
+        field: 'outputs',
+      },
+      { missingOutputs: missingOutputs as any },
+    );
+  }
+}
+
+/**
+ * Validate output assignments for all nodes in a decision.
+ *
+ * This is a convenience function that validates that all expected outputs
+ * from the output schema are actually assigned by the decision logic.
+ *
+ * @param context - The compilation context
+ * @throws CompilationError if any expected output is not assigned or if errors occur during collection
+ */
+export function validateAllOutputReferences(context: CompilationContext): void {
+  const errorCollector = new ErrorCollector();
+
+  // Collect all output assignments, gathering any errors
+  const assignedOutputs = collectOutputAssignments(context, errorCollector);
+
+  // Validate that all expected outputs are assigned
+  try {
+    validateOutputReferences(assignedOutputs, context);
+  } catch (error) {
+    if (error instanceof CompilationError) {
+      errorCollector.add(error);
+    } else {
+      throw error;
+    }
+  }
+
+  // Throw all collected errors (parse errors + validation errors)
+  errorCollector.throwIfErrors();
+}
+
+/**
+ * Validate input references for all expression nodes in a decision.
+ *
+ * This is a convenience function that validates all expressions in the decision
+ * at once, collecting all errors before throwing.
+ *
+ * @param context - The compilation context
+ * @throws CompilationError if any expression references an undeclared input or contains parse errors
+ */
+export function validateAllInputReferences(context: CompilationContext): void {
+  const errorCollector = new ErrorCollector();
+  const inputLayout = context.inputLayout;
+  const expectedInputs = new Set<string>();
+
+  // Build set of expected inputs
+  for (const field of inputLayout.fields) {
+    const parts = field.path.split('.');
+    expectedInputs.add(parts[0]);
+    expectedInputs.add(field.path);
+  }
+
+  // Collect all references and validate them
+  const allIdentifiers = new Set<string>();
+
+  // Helper to create a parse error with location context
+  const createParseError = (
+    nodeId: string,
+    nodeName: string | undefined,
+    expression: string,
+    error: unknown,
+  ): CompilationError => {
+    if (error instanceof CompilationError) {
+      // Preserve original error but add node context if missing
+      if (!error.location?.nodeId) {
+        return new CompilationError(error.message, error.code, { nodeId, nodeName }, error.context);
+      }
+      return error;
+    }
+    return new CompilationError(
+      `Failed to parse expression "${expression}": ${error instanceof Error ? error.message : String(error)}`,
+      ErrorCode.PARSE_ERROR,
+      { nodeId, nodeName },
+    );
+  };
+
+  // Process all nodes that contain expressions
+  for (const node of context.jdm.nodes) {
+    const nodeType = node.type;
+
+    try {
+      if (nodeType === 'expressionNode') {
+        // Collect identifiers from all expressions in the node
+        const expressions = node.content.expressions as Array<{ key: string; value: string }>;
+        for (const expr of expressions) {
+          try {
+            const ast = context.parseExpression(expr.value);
+            const identifiers = collectIdentifiers(ast);
+            for (const id of identifiers) {
+              allIdentifiers.add(id);
+            }
+          } catch (error) {
+            errorCollector.add(createParseError(node.id, node.name, expr.value, error));
+          }
+        }
+      } else if (nodeType === 'decisionTableNode') {
+        // Collect identifiers from decision table conditions
+        const content = node.content as any;
+        if (content.rules) {
+          for (const rule of content.rules) {
+            if (rule.input) {
+              for (const [_key, value] of Object.entries(rule.input as Record<string, string>)) {
+                if (
+                  value &&
+                  typeof value === 'string' &&
+                  !['true', 'false', 'null'].includes(value.toLowerCase())
+                ) {
+                  try {
+                    const ast = context.parseExpression(value);
+                    const identifiers = collectIdentifiers(ast);
+                    for (const id of identifiers) {
+                      allIdentifiers.add(id);
+                    }
+                  } catch (error) {
+                    // Collect parse errors for batch reporting
+                    errorCollector.add(createParseError(node.id, node.name, value, error));
+                  }
+                }
+              }
+            }
+          }
+        }
+      } else if (nodeType === 'switchNode') {
+        // Collect identifiers from switch conditions
+        const content = node.content as any;
+        if (content.cases) {
+          for (const switchCase of content.cases) {
+            if (switchCase.condition && switchCase.condition.expression) {
+              try {
+                const ast = context.parseExpression(switchCase.condition.expression);
+                const identifiers = collectIdentifiers(ast);
+                for (const id of identifiers) {
+                  allIdentifiers.add(id);
+                }
+              } catch (error) {
+                // Collect parse errors for batch reporting
+                errorCollector.add(
+                  createParseError(node.id, node.name, switchCase.condition.expression, error),
+                );
+              }
+            }
+          }
+        }
+      }
+    } catch (error) {
+      // Collect errors from node processing for batch reporting
+      const err =
+        error instanceof CompilationError
+          ? error
+          : new CompilationError(
+              `Failed to process node "${node.name || node.id}": ${error instanceof Error ? error.message : String(error)}`,
+              ErrorCode.PARSE_ERROR,
+              { nodeId: node.id, nodeName: node.name },
+            );
+      errorCollector.add(err);
+    }
+  }
+
+  // Validate all collected identifiers
+  try {
+    validateInputReferences(allIdentifiers, context);
+  } catch (error) {
+    if (error instanceof CompilationError) {
+      errorCollector.add(error);
+    } else {
+      throw error;
+    }
+  }
+
+  // Throw all collected errors (parse errors + validation errors)
+  errorCollector.throwIfErrors();
+}