form0-core 0.1.7 → 0.1.9

package/src/engine/form-engine.js

@@ -3,7 +3,7 @@ import { evaluateVisibility } from './conditions.js';
 import { evaluateRequirement } from './conditions.js';
 import { evaluateReadOnly } from './conditions.js';
 import { validateFields } from './field-validation.js';
-import { builtins, eventBuiltins } from '../builtins/registry.js';
+import { calculationBuiltins, eventBuiltins } from '../builtins/registry.js';
 import { validateSchema } from '../schema/schema-validator.js';
 import { flattenFields } from '../utilities/field-helpers.js';
 import { DEFAULT_SECURITY_CONFIG } from '../security/config.js';
@@ -12,6 +12,7 @@ import { FIELD_SPECS } from '../schema/field-specs.js';
 import { ContextResolver } from './context-resolver.js';
 import { WarningSystem } from './warning-system.js';
 import { expandBuildingPlanSchema } from '../schema/building-plan-expander.js';
+import { buildCalculationDependencyPlan } from '../utilities/calculation-dependencies.js';
 
 export function createFormEngine({
   schema,
@@ -90,16 +91,17 @@ export function createFormEngine({
   const required = {};
   const read_only = {};
 
-  const allHelpers = { ...builtins, ...helpers };
+  const allHelpers = { ...calculationBuiltins, ...helpers };
 
   // Initialize context resolution system
   const contextResolver = new ContextResolver(form);
+  const calculationPlan = buildCalculationDependencyPlan(form, contextResolver);
   const sharedWarningSystem = warningSystem || new WarningSystem();
 
   // Initialize event system with context resolution
   const eventManager = new EventManager(form, contextResolver, sharedWarningSystem);
   eventManager.securityConfig = security; // Pass security config
-  const eventHelpers = { ...builtins, ...eventBuiltins, ...helpers };
+  const eventHelpers = { ...eventBuiltins, ...helpers };
 
   // Initialize event code if present
   if (form.events && form.events.code) {
@@ -128,7 +130,8 @@ export function createFormEngine({
       security,
       contextResolver,
       sharedWarningSystem,
-      runtimeDiagnostics
+      runtimeDiagnostics,
+      calculationPlan
     );
     evaluateRequirement(form, values, required);
     evaluateVisibility(form, values, visible);

package/src/index.js

@@ -38,6 +38,11 @@ export {
   createCalculationPreviewSession,
   simulateCalculationExpression,
 } from './utilities/calculation-editor.js';
+export {
+  getFormEventBuiltinCatalog,
+  getFormEventReferenceCatalog,
+  analyzeFormEventCode,
+} from './utilities/form-event-editor.js';
 export {
   getFormAIMetadata,
   getFormAIContext,

package/src/security/validation.js

@@ -1,16 +1,15 @@
-import { builtins, eventBuiltins } from '../builtins/registry.js';
+import { calculationBuiltins, eventBuiltins } from '../builtins/registry.js';
 import { DEFAULT_SECURITY_CONFIG, SAFE_SECURITY_CONFIG, SECURITY_MODES } from './config.js';
 
 // Helper function to validate builtin function names in expressions
 function validateBuiltinNames(expr, includeEventBuiltins = false) {
   // Always use fresh builtin sets (no caching) to support dynamic builtin registration
-  const validBuiltinsSet = new Set(Object.keys(builtins));
+  const validCalculationBuiltinsSet = new Set(Object.keys(calculationBuiltins));
   const validEventBuiltinsSet = new Set(Object.keys(eventBuiltins));
 
-  // Combine regular and event builtins if in event context
   const allowedBuiltins = includeEventBuiltins
-    ? new Set([...validBuiltinsSet, ...validEventBuiltinsSet])
-    : validBuiltinsSet;
+    ? validEventBuiltinsSet
+    : validCalculationBuiltinsSet;
 
   // Extract function calls from the expression
   // This regex matches function calls like FUNCTIONNAME( allowing for whitespace
@@ -46,8 +45,8 @@ function validateBuiltinNames(expr, includeEventBuiltins = false) {
     }
 
     // Check for potential typos by finding similar builtin names
-    const validBuiltins = [...allowedBuiltins]; // Convert back to array for filtering
-    const similarBuiltins = validBuiltins.filter((builtin) => {
+    const validBuiltinNames = [...allowedBuiltins];
+    const similarBuiltins = validBuiltinNames.filter((builtin) => {
       // Simple similarity check - same length or very close
       const lengthDiff = Math.abs(builtin.length - functionName.length);
       return lengthDiff <= 2 && builtin.startsWith(functionName.substring(0, 3));

package/src/utilities/calculation-dependencies.js

@@ -0,0 +1,311 @@
+import { ContextResolver } from '../engine/context-resolver.js';
+import { flattenFields } from './field-helpers.js';
+
+function sortFieldNames(fieldNames, orderByFieldName) {
+  return [...fieldNames].sort(
+    (left, right) => orderByFieldName.get(left) - orderByFieldName.get(right)
+  );
+}
+
+function buildStronglyConnectedComponents(nodesByDataName, orderByFieldName) {
+  const indices = new Map();
+  const lowLinks = new Map();
+  const stack = [];
+  const onStack = new Set();
+  const components = [];
+  let currentIndex = 0;
+
+  function strongConnect(fieldName) {
+    indices.set(fieldName, currentIndex);
+    lowLinks.set(fieldName, currentIndex);
+    currentIndex += 1;
+    stack.push(fieldName);
+    onStack.add(fieldName);
+
+    const node = nodesByDataName.get(fieldName);
+    if (node) {
+      for (const dependency of node.dependencies) {
+        if (!indices.has(dependency)) {
+          strongConnect(dependency);
+          lowLinks.set(fieldName, Math.min(lowLinks.get(fieldName), lowLinks.get(dependency)));
+        } else if (onStack.has(dependency)) {
+          lowLinks.set(fieldName, Math.min(lowLinks.get(fieldName), indices.get(dependency)));
+        }
+      }
+    }
+
+    if (lowLinks.get(fieldName) !== indices.get(fieldName)) {
+      return;
+    }
+
+    const componentFieldNames = [];
+    while (stack.length > 0) {
+      const stackFieldName = stack.pop();
+      onStack.delete(stackFieldName);
+      componentFieldNames.push(stackFieldName);
+      if (stackFieldName === fieldName) {
+        break;
+      }
+    }
+
+    components.push(sortFieldNames(componentFieldNames, orderByFieldName));
+  }
+
+  const sortedFieldNames = sortFieldNames(nodesByDataName.keys(), orderByFieldName);
+  sortedFieldNames.forEach((fieldName) => {
+    if (!indices.has(fieldName)) {
+      strongConnect(fieldName);
+    }
+  });
+
+  return components;
+}
+
+function topologicallyOrderComponents(componentIds, componentEdges) {
+  const inDegree = new Map(componentIds.map((componentId) => [componentId, 0]));
+
+  componentEdges.forEach((targets) => {
+    targets.forEach((targetId) => {
+      inDegree.set(targetId, (inDegree.get(targetId) || 0) + 1);
+    });
+  });
+
+  const queue = componentIds.filter((componentId) => (inDegree.get(componentId) || 0) === 0);
+  const ordered = [];
+
+  while (queue.length > 0) {
+    const componentId = queue.shift();
+    ordered.push(componentId);
+
+    for (const targetId of componentEdges.get(componentId) || []) {
+      const nextDegree = (inDegree.get(targetId) || 0) - 1;
+      inDegree.set(targetId, nextDegree);
+      if (nextDegree === 0) {
+        queue.push(targetId);
+      }
+    }
+  }
+
+  if (ordered.length === componentIds.length) {
+    return ordered;
+  }
+
+  return [...componentIds];
+}
+
+export function normalizeCalculationFormSchema(schema) {
+  if (schema && Array.isArray(schema.elements)) {
+    return schema;
+  }
+
+  if (schema && schema.form && Array.isArray(schema.form.elements)) {
+    return schema.form;
+  }
+
+  throw new Error('Expected a form schema or a root schema containing form.elements');
+}
+
+export function hasDynamicCalculationDependencies(code) {
+  return /\bEVAL\s*\(/.test(typeof code === 'string' ? code : '');
+}
+
+export function removeEvalContents(code) {
+  const source = typeof code === 'string' ? code : '';
+  let result = '';
+  let i = 0;
+
+  while (i < source.length) {
+    const evalMatch = source.substring(i).match(/^EVAL\s*\(/);
+    if (evalMatch) {
+      result += 'EVAL()';
+      i += evalMatch[0].length;
+
+      let parenCount = 1;
+      let inSingleQuote = false;
+      let inDoubleQuote = false;
+      let inBacktick = false;
+
+      while (i < source.length && parenCount > 0) {
+        const char = source[i];
+
+        if (char === "'" && !inDoubleQuote && !inBacktick) {
+          inSingleQuote = !inSingleQuote;
+        } else if (char === '"' && !inSingleQuote && !inBacktick) {
+          inDoubleQuote = !inDoubleQuote;
+        } else if (char === '`' && !inSingleQuote && !inDoubleQuote) {
+          inBacktick = !inBacktick;
+        }
+
+        if (!inSingleQuote && !inDoubleQuote && !inBacktick) {
+          if (char === '(') {
+            parenCount += 1;
+          } else if (char === ')') {
+            parenCount -= 1;
+          }
+        }
+
+        i += 1;
+      }
+    } else {
+      result += source[i];
+      i += 1;
+    }
+  }
+
+  return result;
+}
+
+export function extractStaticFieldReferenceMatches(code) {
+  const cleanedCode = removeEvalContents(code);
+  const fieldRegex = /\$([a-zA-Z_][a-zA-Z0-9_]*)/g;
+  const matches = [];
+  let match;
+
+  while ((match = fieldRegex.exec(cleanedCode)) !== null) {
+    matches.push({
+      fieldName: match[1],
+      reference: `$${match[1]}`,
+      index: match.index,
+      length: match[0].length,
+    });
+  }
+
+  return matches;
+}
+
+export function extractStaticFieldReferences(code) {
+  return new Set(extractStaticFieldReferenceMatches(code).map((match) => match.fieldName));
+}
+
+export function buildCalculationExecutionContext(form, fieldDataName, resolver) {
+  return {
+    type: 'calculation',
+    fieldName: fieldDataName,
+    parentPath: resolver.getFieldInfo(fieldDataName)?.parentPath || [],
+  };
+}
+
+export function buildCalculationDependencyPlan(schema, contextResolver = null) {
+  const form = normalizeCalculationFormSchema(schema);
+  const resolver = contextResolver || new ContextResolver(form);
+  const fields = flattenFields(form.elements).filter((field) => field && typeof field === 'object');
+  const fieldsByDataName = new Map(
+    fields
+      .filter((field) => typeof field.data_name === 'string' && field.data_name.length > 0)
+      .map((field) => [field.data_name, field])
+  );
+
+  const orderByFieldName = new Map();
+  fields.forEach((field, index) => {
+    if (typeof field?.data_name === 'string') {
+      orderByFieldName.set(field.data_name, index);
+    }
+  });
+
+  const nodesByDataName = new Map();
+  fields.forEach((field) => {
+    if (field.type !== 'CalculatedField' || typeof field.data_name !== 'string') {
+      return;
+    }
+
+    const fieldName = field.data_name;
+    const executionContext = buildCalculationExecutionContext(form, fieldName, resolver);
+    const directReferences = extractStaticFieldReferences(field.calculate || '');
+    const dependencies = new Set();
+
+    directReferences.forEach((referenceFieldName) => {
+      const accessInfo = resolver.resolveFieldAccessInfo(executionContext, referenceFieldName);
+      if (accessInfo.level !== 'accessible') {
+        return;
+      }
+
+      const dependencyField = fieldsByDataName.get(referenceFieldName);
+      if (dependencyField?.type === 'CalculatedField') {
+        dependencies.add(referenceFieldName);
+      }
+    });
+
+    nodesByDataName.set(fieldName, {
+      field,
+      fieldName,
+      dependencies,
+      directReferences,
+      hasDynamicDependencies: hasDynamicCalculationDependencies(field.calculate || ''),
+    });
+  });
+
+  const componentFieldGroups = buildStronglyConnectedComponents(nodesByDataName, orderByFieldName);
+  const componentIdByFieldName = new Map();
+  const componentsById = new Map();
+
+  componentFieldGroups.forEach((fieldNames, componentIndex) => {
+    const componentId = `component_${componentIndex}`;
+    fieldNames.forEach((fieldName) => {
+      componentIdByFieldName.set(fieldName, componentId);
+    });
+    componentsById.set(componentId, {
+      id: componentId,
+      fieldNames,
+      hasDynamicDependencies: false,
+      isCyclic: false,
+    });
+  });
+
+  nodesByDataName.forEach((node) => {
+    node.componentId = componentIdByFieldName.get(node.fieldName);
+  });
+
+  componentsById.forEach((component) => {
+    component.hasDynamicDependencies = component.fieldNames.some(
+      (fieldName) => nodesByDataName.get(fieldName)?.hasDynamicDependencies
+    );
+    component.isCyclic =
+      component.fieldNames.length > 1 ||
+      component.fieldNames.some((fieldName) =>
+        nodesByDataName.get(fieldName)?.dependencies.has(fieldName)
+      );
+  });
+
+  const componentEdges = new Map(
+    Array.from(componentsById.keys(), (componentId) => [componentId, new Set()])
+  );
+
+  nodesByDataName.forEach((node) => {
+    const targetComponentId = node.componentId;
+    node.dependencies.forEach((dependencyFieldName) => {
+      const dependencyComponentId = componentIdByFieldName.get(dependencyFieldName);
+      if (!dependencyComponentId || dependencyComponentId === targetComponentId) {
+        return;
+      }
+      componentEdges.get(dependencyComponentId).add(targetComponentId);
+    });
+  });
+
+  const orderedComponentIds = topologicallyOrderComponents(
+    Array.from(componentsById.keys()),
+    componentEdges
+  );
+  const orderedFieldNames = orderedComponentIds.flatMap(
+    (componentId) => componentsById.get(componentId)?.fieldNames || []
+  );
+  const dynamicFieldNames = orderedFieldNames.filter(
+    (fieldName) => nodesByDataName.get(fieldName)?.hasDynamicDependencies
+  );
+  const cyclicComponentIds = orderedComponentIds.filter(
+    (componentId) => componentsById.get(componentId)?.isCyclic
+  );
+
+  return {
+    form,
+    fieldsByDataName,
+    nodesByDataName,
+    componentsById,
+    componentIdByFieldName,
+    orderedComponentIds,
+    orderedFieldNames,
+    hasDynamicDependencies: dynamicFieldNames.length > 0,
+    dynamicFieldNames,
+    cyclicComponentIds,
+    totalCalculatedFieldCount: orderedFieldNames.length,
+  };
+}

package/src/utilities/calculation-editor.js

@@ -8,6 +8,13 @@ import { createFormEngine } from '../engine/form-engine.js';
 import { WarningSystem } from '../engine/warning-system.js';
 import { DEFAULT_SECURITY_CONFIG } from '../security/config.js';
 import { validateExpression } from '../security/validation.js';
+import {
+  buildCalculationDependencyPlan,
+  buildCalculationExecutionContext,
+  extractStaticFieldReferenceMatches,
+  hasDynamicCalculationDependencies,
+  normalizeCalculationFormSchema,
+} from './calculation-dependencies.js';
 import {
   isMultilineCalculationExpression,
   normalizeInlineCalculationExpression,
@@ -53,67 +60,10 @@ const CALCULATION_BUILTIN_METADATA_BY_NAME = new Map(
   CALCULATION_BUILTIN_CATALOG.map((definition) => [definition.name, definition])
 );
 
-function normalizeFormSchema(schema) {
-  if (schema && Array.isArray(schema.elements)) {
-    return schema;
-  }
-
-  if (schema && schema.form && Array.isArray(schema.form.elements)) {
-    return schema.form;
-  }
-
-  throw new Error('Expected a form schema or a root schema containing form.elements');
-}
-
 function isBuiltinCallMatchAllowed(functionName) {
   return COMMON_GLOBAL_FUNCTIONS.has(functionName);
 }
 
-function removeEvalContents(code) {
-  let result = '';
-  let i = 0;
-
-  while (i < code.length) {
-    const evalMatch = code.substring(i).match(/^EVAL\s*\(/);
-    if (evalMatch) {
-      result += 'EVAL()';
-      i += evalMatch[0].length;
-
-      let parenCount = 1;
-      let inSingleQuote = false;
-      let inDoubleQuote = false;
-      let inBacktick = false;
-
-      while (i < code.length && parenCount > 0) {
-        const char = code[i];
-
-        if (char === "'" && !inDoubleQuote && !inBacktick) {
-          inSingleQuote = !inSingleQuote;
-        } else if (char === '"' && !inSingleQuote && !inBacktick) {
-          inDoubleQuote = !inDoubleQuote;
-        } else if (char === '`' && !inSingleQuote && !inDoubleQuote) {
-          inBacktick = !inBacktick;
-        }
-
-        if (!inSingleQuote && !inDoubleQuote && !inBacktick) {
-          if (char === '(') {
-            parenCount++;
-          } else if (char === ')') {
-            parenCount--;
-          }
-        }
-
-        i++;
-      }
-    } else {
-      result += code[i];
-      i++;
-    }
-  }
-
-  return result;
-}
-
 function extractFunctionCalls(code) {
   const functionCallPattern = /\b([A-Z_][A-Z0-9_]*)\s*\(/g;
   const matches = [];
@@ -130,32 +80,6 @@ function extractFunctionCalls(code) {
   return matches;
 }
 
-function extractFieldReferenceMatches(code) {
-  const cleanedCode = removeEvalContents(code);
-  const fieldRegex = /\$([a-zA-Z_][a-zA-Z0-9_]*)/g;
-  const matches = [];
-  let match;
-
-  while ((match = fieldRegex.exec(cleanedCode)) !== null) {
-    matches.push({
-      fieldName: match[1],
-      reference: `$${match[1]}`,
-      index: match.index,
-      length: match[0].length,
-    });
-  }
-
-  return matches;
-}
-
-function buildExecutionContext(form, fieldDataName, resolver) {
-  return {
-    type: 'calculation',
-    fieldName: fieldDataName,
-    parentPath: resolver.getFieldInfo(fieldDataName)?.parentPath || [],
-  };
-}
-
 function cloneCatalogDefinition(definition) {
   return {
     ...definition,
@@ -254,7 +178,7 @@ function cloneSimulationSchema(schema) {
   }
 
   return {
-    form: deepClone(normalizeFormSchema(schema)),
+    form: deepClone(normalizeCalculationFormSchema(schema)),
   };
 }
 
@@ -383,9 +307,9 @@ export function getCalculationReferenceCatalog({
   fieldDataName,
   includeRestricted = false,
 }) {
-  const form = normalizeFormSchema(schema);
+  const form = normalizeCalculationFormSchema(schema);
   const resolver = new ContextResolver(form);
-  const executionContext = buildExecutionContext(form, fieldDataName, resolver);
+  const executionContext = buildCalculationExecutionContext(form, fieldDataName, resolver);
 
   return flattenFields(form.elements)
     .filter((field) => field && typeof field === 'object')
@@ -431,9 +355,14 @@ export function analyzeCalculationExpression({
   const setResultCalls = [];
 
   const normalizedExpression = typeof expression === 'string' ? expression : '';
-  const form = normalizeFormSchema(schema);
+  const baseForm = normalizeCalculationFormSchema(schema);
+  const form = deepClone(baseForm);
+  const targetField = findFieldByDataName(form.elements, fieldDataName);
+  if (targetField && targetField.type === 'CalculatedField') {
+    targetField.calculate = normalizedExpression;
+  }
   const resolver = new ContextResolver(form);
-  const executionContext = buildExecutionContext(form, fieldDataName, resolver);
+  const executionContext = buildCalculationExecutionContext(form, fieldDataName, resolver);
 
   if (normalizedExpression.trim().length === 0) {
     addIssue(
@@ -590,7 +519,7 @@ export function analyzeCalculationExpression({
     );
   }
 
-  for (const reference of extractFieldReferenceMatches(normalizedExpression)) {
+  for (const reference of extractStaticFieldReferenceMatches(normalizedExpression)) {
     if (!referencedFieldNames.has(reference.fieldName)) {
       referencedFieldNames.add(reference.fieldName);
       referencedFields.push(reference.fieldName);
@@ -633,6 +562,39 @@ export function analyzeCalculationExpression({
     }
   }
 
+  if (hasDynamicCalculationDependencies(normalizedExpression)) {
+    addIssue(
+      issues,
+      issueKeys,
+      createIssue({
+        code: 'dynamic_calculation_dependency',
+        severity: 'warning',
+        message:
+          'This expression uses dynamic field access through EVAL(). Runtime evaluation will fall back to bounded stabilization.',
+      })
+    );
+  }
+
+  if (targetField?.type === 'CalculatedField') {
+    const dependencyPlan = buildCalculationDependencyPlan(form, resolver);
+    const targetNode = dependencyPlan.nodesByDataName.get(fieldDataName);
+    const targetComponent = targetNode?.componentId
+      ? dependencyPlan.componentsById.get(targetNode.componentId)
+      : null;
+
+    if (targetComponent?.isCyclic) {
+      addIssue(
+        issues,
+        issueKeys,
+        createIssue({
+          code: 'calculated_field_cycle',
+          severity: 'error',
+          message: `CalculatedField dependency cycle detected: ${targetComponent.fieldNames.join(' -> ')}.`,
+        })
+      );
+    }
+  }
+
   return {
     valid: !issues.some((issue) => issue.severity === 'error'),
     issues,
@@ -673,23 +635,20 @@ export function createCalculationPreviewSession({
   security = DEFAULT_SECURITY_CONFIG,
 }) {
   const simulationSchema = cloneSimulationSchema(schema);
-  const form = normalizeFormSchema(simulationSchema);
+  const form = normalizeCalculationFormSchema(simulationSchema);
   const targetField = findFieldByDataName(form.elements, fieldDataName);
 
   if (!targetField) {
     return {
       run: () =>
-        createSimulationErrorResult(
-          `Field '${fieldDataName}' does not exist in the form schema.`
-        ),
+        createSimulationErrorResult(`Field '${fieldDataName}' does not exist in the form schema.`),
       dispose: () => {},
     };
   }
 
   if (targetField.type !== 'CalculatedField') {
     return {
-      run: () =>
-        createSimulationErrorResult(`Field '${fieldDataName}' is not a CalculatedField.`),
+      run: () => createSimulationErrorResult(`Field '${fieldDataName}' is not a CalculatedField.`),
       dispose: () => {},
     };
   }
@@ -739,9 +698,13 @@ export function createCalculationPreviewSession({
 
         const simulatedResult = engineState.values[fieldDataName];
         const runtimeError =
-          runtimeDiagnostics.find((diagnostic) => diagnostic.fieldName === fieldDataName)
+          runtimeDiagnostics.find(
+            (diagnostic) =>
+              diagnostic.fieldName === fieldDataName &&
+              (diagnostic.severity || 'error') !== 'warning'
+          )?.message ||
+          runtimeDiagnostics.find((diagnostic) => (diagnostic.severity || 'error') !== 'warning')
             ?.message ||
-          runtimeDiagnostics[0]?.message ||
           null;
 
         return {