form0-core 0.3.0 → 0.4.0

package/src/engine/calculation.js

@@ -16,13 +16,14 @@ export function evaluateCalculatedFields(
   contextResolver = null,
   warningSystem = null,
   runtimeDiagnostics = null,
-  calculationPlan = null
+  calculationPlan = null,
+  diagnostics = null
 ) {
   const resolver = contextResolver || new ContextResolver(schema);
   const warnings = warningSystem || new WarningSystem();
   const plan = calculationPlan || buildCalculationDependencyPlan(schema, resolver);
 
-  emitDependencyPlanWarnings(plan, warnings, runtimeDiagnostics);
+  emitDependencyPlanWarnings(plan, warnings, runtimeDiagnostics, diagnostics);
 
   if (plan.totalCalculatedFieldCount === 0) {
     return;
@@ -47,7 +48,8 @@ export function evaluateCalculatedFields(
       securityConfig,
       resolver,
       warnings,
-      runtimeDiagnostics
+      runtimeDiagnostics,
+      diagnostics
     );
     return;
   }
@@ -73,7 +75,8 @@ export function evaluateCalculatedFields(
         securityConfig,
         resolver,
         warnings,
-        runtimeDiagnostics
+        runtimeDiagnostics,
+        diagnostics
       );
     }
   });
@@ -103,7 +106,8 @@ function buildScopedContext(
   executionContext,
   contextResolver,
   warningSystem,
-  expressionCode
+  expressionCode,
+  diagnostics
 ) {
   const ctx = { ...helpers };
 
@@ -139,12 +143,14 @@ function buildScopedContext(
       fieldName,
       'restricted'
     );
-    warningSystem.emitWarning(warning);
+    if (diagnostics) diagnostics.emitWarning(warning);
+    else warningSystem.emitWarning(warning);
   });
 
   notFoundAccessedFields.forEach((fieldName) => {
     const warning = contextResolver.generateAccessWarning(executionContext, fieldName, 'not_found');
-    warningSystem.emitWarning(warning);
+    if (diagnostics) diagnostics.emitWarning(warning);
+    else warningSystem.emitWarning(warning);
   });
 
   return ctx;
@@ -181,10 +187,12 @@ function pushRuntimeDiagnostic(
   });
 }
 
-function emitDependencyPlanWarnings(plan, warningSystem, runtimeDiagnostics) {
+function emitDependencyPlanWarnings(plan, warningSystem, runtimeDiagnostics, diagnostics) {
+  const emit = (warning, fieldNames) =>
+    diagnostics ? diagnostics.emitWarning(warning, fieldNames) : warningSystem.emitWarning(warning);
   plan.dynamicFieldNames.forEach((fieldName) => {
     const message = `CalculatedField '${fieldName}' uses dynamic field access. Runtime evaluation falls back to bounded stabilization.`;
-    warningSystem.emitWarning({
+    emit({
       type: 'calculation_dependency',
       reason: 'dynamic_dependencies',
       message,
@@ -215,22 +223,25 @@ function emitDependencyPlanWarnings(plan, warningSystem, runtimeDiagnostics) {
 
     const fieldNames = component.fieldNames;
     const message = `CalculatedField dependency cycle detected: ${fieldNames.join(' -> ')}. Runtime evaluation is disabled for the involved fields until the cycle is removed.`;
-    warningSystem.emitWarning({
-      type: 'calculation_dependency',
-      reason: 'cyclic_dependencies',
-      severity: 'error',
-      message,
-      suggestion:
-        'Remove the cycle or break it with a source field so calculated values can be evaluated deterministically.',
-      executionContext: {
-        type: 'calculation',
-        fieldName: fieldNames[0] || null,
-      },
-      fieldContext: {
-        fieldNames: [...fieldNames],
-        cyclic: true,
+    emit(
+      {
+        type: 'calculation_dependency',
+        reason: 'cyclic_dependencies',
+        severity: 'error',
+        message,
+        suggestion:
+          'Remove the cycle or break it with a source field so calculated values can be evaluated deterministically.',
+        executionContext: {
+          type: 'calculation',
+          fieldName: fieldNames[0] || null,
+        },
+        fieldContext: {
+          fieldNames: [...fieldNames],
+          cyclic: true,
+        },
       },
-    });
+      fieldNames
+    );
 
     fieldNames.forEach((fieldName) => {
       pushRuntimeDiagnostic(
@@ -252,7 +263,8 @@ function evaluateCalculatedField(
   securityConfig,
   resolver,
   warnings,
-  runtimeDiagnostics
+  runtimeDiagnostics,
+  diagnostics
 ) {
   if (!field?.data_name || !field.calculate) {
     return { changed: false, hasError: false };
@@ -266,11 +278,20 @@ function evaluateCalculatedField(
       executionContext,
       resolver,
       warnings,
-      field.calculate
+      field.calculate,
+      diagnostics
     );
     const previousValue = values[field.data_name];
     const nextValue = runExpression(field.calculate, context, securityConfig, false, schema, {
-      suppressConsoleWarning: Array.isArray(runtimeDiagnostics),
+      requireResult: true,
+      fieldName: field.data_name,
+      suppressConsoleWarning:
+        diagnostics?.consoleOverride !== undefined || Array.isArray(runtimeDiagnostics),
+      onDiagnostic: (diagnostic) => diagnostics?.record(field.data_name, diagnostic),
+      evalReporting: {
+        suppressConsole: diagnostics?.consoleOverride !== undefined,
+        onDiagnostic: (diagnostic) => diagnostics?.record(field.data_name, diagnostic),
+      },
       onError: (error) => {
         pushRuntimeDiagnostic(
           runtimeDiagnostics,
@@ -288,13 +309,21 @@ function evaluateCalculatedField(
       hasError: false,
     };
   } catch (error) {
+    diagnostics?.record(field.data_name, {
+      code: 'runtime_exception',
+      phase: 'runtime',
+      message:
+        error instanceof Error && error.message
+          ? error.message
+          : 'Unknown calculation runtime error.',
+    });
     pushRuntimeDiagnostic(
       runtimeDiagnostics,
       field.data_name,
       error instanceof Error && error.message ? error.message : 'Unknown calculation runtime error.'
     );
 
-    if (!Array.isArray(runtimeDiagnostics)) {
+    if (diagnostics?.consoleOverride === undefined && !Array.isArray(runtimeDiagnostics)) {
       console.warn(`Calculation failed for ${field.data_name}:`, error?.message);
     }
 
@@ -311,7 +340,8 @@ function evaluateFieldSequenceUntilStable(
   securityConfig,
   resolver,
   warnings,
-  runtimeDiagnostics
+  runtimeDiagnostics,
+  diagnostics
 ) {
   const maxPasses = Math.max(2, fieldNames.length);
   let stillChangingFieldNames = [];
@@ -333,7 +363,8 @@ function evaluateFieldSequenceUntilStable(
         securityConfig,
         resolver,
         warnings,
-        runtimeDiagnostics
+        runtimeDiagnostics,
+        diagnostics
       );
 
       if (result.changed) {
@@ -347,7 +378,7 @@ function evaluateFieldSequenceUntilStable(
   }
 
   const message = `Calculated fields did not stabilize within ${maxPasses} evaluation passes: ${stillChangingFieldNames.join(', ')}.`;
-  warnings.emitWarning({
+  const warning = {
     type: 'calculation_dependency',
     reason: 'non_converging_runtime',
     message,
@@ -361,7 +392,9 @@ function evaluateFieldSequenceUntilStable(
       fieldNames: [...stillChangingFieldNames],
       maxPasses,
     },
-  });
+  };
+  if (diagnostics) diagnostics.emitWarning(warning, stillChangingFieldNames);
+  else warnings.emitWarning(warning);
 
   stillChangingFieldNames.forEach((fieldName) => {
     pushRuntimeDiagnostic(

package/src/engine/conditions.js

@@ -1,8 +1,28 @@
 import { flattenFields } from '../utilities/field-helpers.js';
 
+const valuesEqual = (a, b) => {
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) {
+      return false;
+    }
+
+    const unmatched = [...b];
+    return a.every((value) => {
+      const matchIndex = unmatched.findIndex((candidate) => candidate === value);
+      if (matchIndex === -1) {
+        return false;
+      }
+      unmatched.splice(matchIndex, 1);
+      return true;
+    });
+  }
+
+  return a === b;
+};
+
 const OPERATORS = {
-  equal_to: (a, b) => a === b,
-  not_equal_to: (a, b) => a !== b,
+  equal_to: valuesEqual,
+  not_equal_to: (a, b) => !valuesEqual(a, b),
   greater_than: (a, b) => a > b,
   less_than: (a, b) => a < b,
   greater_or_equal_than: (a, b) => a >= b,
@@ -15,6 +35,52 @@ const OPERATORS = {
     !(a === null || a === undefined || a === '' || (Array.isArray(a) && a.length === 0)),
 };
 
+const hasValue = (entry, property) =>
+  entry &&
+  typeof entry === 'object' &&
+  Object.prototype.hasOwnProperty.call(entry, property) &&
+  entry[property] !== null &&
+  entry[property] !== undefined &&
+  entry[property] !== '';
+
+const getOtherValue = (entry) => {
+  if (hasValue(entry, 'value')) {
+    return entry.value;
+  }
+  if (hasValue(entry, 'label')) {
+    return entry.label;
+  }
+  return null;
+};
+
+function normalizeConditionValue(field, value) {
+  if (!field || !value || typeof value !== 'object' || Array.isArray(value)) {
+    return value;
+  }
+
+  if (field.type === 'SingleChoiceField' || field.type === 'BooleanField') {
+    const selectedChoice = Array.isArray(value.choice) ? value.choice[0] : null;
+    if (hasValue(selectedChoice, 'value')) {
+      return selectedChoice.value;
+    }
+
+    const otherEntry = Array.isArray(value.other) ? value.other[0] : null;
+    return getOtherValue(otherEntry);
+  }
+
+  if (field.type === 'MultiChoiceField') {
+    const selectedValues = Array.isArray(value.choices)
+      ? value.choices.filter((choice) => hasValue(choice, 'value')).map((choice) => choice.value)
+      : [];
+    const otherValues = Array.isArray(value.other)
+      ? value.other.map(getOtherValue).filter((otherValue) => otherValue !== null)
+      : [];
+    return [...selectedValues, ...otherValues];
+  }
+
+  return value;
+}
+
 export function evaluateConditions(conditions, values, allFields) {
   if (Array.isArray(conditions)) {
     return conditions.every((c) => evaluateConditions(c, values, allFields));
@@ -31,7 +97,7 @@ export function evaluateConditions(conditions, values, allFields) {
   // Map field_id (key) to data_name for value lookup
   const field = allFields ? allFields[conditions.field_id] : undefined;
   const dataName = field ? field.data_name : undefined;
-  const val = dataName ? values[dataName] : undefined;
+  const val = normalizeConditionValue(field, dataName ? values[dataName] : undefined);
   // Debug log: show what is being checked
   //console.log('[evaluateConditions] field_id:', conditions.field_id, 'data_name:', dataName, 'value in values:', val, 'expected:', conditions.value, 'operator:', conditions.operator);
   const fn = OPERATORS[conditions.operator];

package/src/engine/evaluator.js

@@ -1,6 +1,6 @@
-import { __consumeResult, __resetResult } from '../builtins/registry.js';
-import { __setEvalContext, __clearEvalContext } from '../builtins/control/eval.js';
-import { __setDataNamesContext, __clearDataNamesContext } from '../builtins/schema/datanames.js';
+import { __beginResultScope, __consumeResult } from '../builtins/registry.js';
+import { __setEvalContext } from '../builtins/control/eval.js';
+import { __setDataNamesContext } from '../builtins/schema/datanames.js';
 import { validateExpression, createSecureContext, withTimeout } from '../security/validation.js';
 import { DEFAULT_SECURITY_CONFIG } from '../security/config.js';
 import {
@@ -8,6 +8,24 @@ import {
   normalizeInlineCalculationExpression,
 } from '../utilities/calculation-expression-utils.js';
 
+const MISSING_RESULT_MESSAGE =
+  'Multiline calculation produced no value because it neither calls SETRESULT() nor returns a value.';
+
+function reportMissingResult(options) {
+  options.onDiagnostic?.({
+    code: 'missing_result',
+    severity: 'warning',
+    phase: 'runtime',
+    message: MISSING_RESULT_MESSAGE,
+    suggestion:
+      'Wrap the final value in SETRESULT(), use an explicit return statement, or write the calculation on a single line.',
+  });
+  if (!options.suppressConsoleWarning) {
+    const field = options.fieldName ? ` (${options.fieldName})` : '';
+    console.warn(`[form0] missing_result${field}: ${MISSING_RESULT_MESSAGE}`);
+  }
+}
+
 export function runExpression(
   expr,
   context = {},
@@ -16,13 +34,18 @@ export function runExpression(
   schema = null,
   options = {}
 ) {
-  // SETRESULT uses synchronous evaluation-scoped state. Clear it at both boundaries so a
-  // previously failed expression can never influence this evaluation.
-  __resetResult();
+  const restoreResultScope = __beginResultScope();
+  let phase = 'runtime';
   try {
+    const sourceExpression = options.sourceExpression ?? expr;
     // Validate expression based on security mode
-    const validation = validateExpression(expr, securityConfig, includeEventBuiltins);
+    const validation = validateExpression(sourceExpression, securityConfig, includeEventBuiltins);
     if (!validation.valid) {
+      options.onDiagnostic?.({
+        code: 'expression_validation_failed',
+        phase: 'validation',
+        message: validation.reason,
+      });
       if (!options.suppressConsoleWarning) {
         console.warn('[form0] Expression validation failed:', validation.reason);
       }
@@ -37,37 +60,40 @@ export function runExpression(
     // Execute expression
     const executeExpression = () => {
       // Set context for EVAL() before execution
-      __setEvalContext(secureContext);
-      if (schema) {
-        __setDataNamesContext(schema);
-      }
+      const restoreEvalContext = __setEvalContext(secureContext, options.evalReporting);
+      const restoreDataNamesContext = schema ? __setDataNamesContext(schema) : null;
 
       try {
         // Handle both expressions and multi-line code (Windows-safe)
-        const isMultiLine = isMultilineCalculationExpression(expr);
+        const isMultiLine =
+          options.evaluateAsExpression !== true &&
+          isMultilineCalculationExpression(sourceExpression);
 
         if (isMultiLine) {
           // Execute as code block (recompile each time for now)
+          phase = 'syntax';
           const fn = new Function(...keys, expr);
+          phase = 'runtime';
           const result = fn(...values);
           // Check for consumed result from SETRESULT() calls in multiline code
           const consumed = __consumeResult();
+          if (options.requireResult && !consumed.called && result === undefined) {
+            reportMissingResult(options);
+          }
           return consumed.called ? consumed.value : result;
         } else {
           // Execute as expression (existing behavior)
           const inlineExpression = normalizeInlineCalculationExpression(expr);
+          phase = 'syntax';
           const fn = new Function(...keys, `return (${inlineExpression});`);
+          phase = 'runtime';
           const result = fn(...values);
           const consumed = __consumeResult();
           return consumed.called ? consumed.value : result;
         }
       } finally {
-        __resetResult();
-        // Always clear EVAL context after execution
-        __clearEvalContext();
-        if (schema) {
-          __clearDataNamesContext();
-        }
+        restoreDataNamesContext?.();
+        restoreEvalContext();
       }
     };
 
@@ -80,6 +106,16 @@ export function runExpression(
 
     return executeExpression();
   } catch (e) {
+    options.onDiagnostic?.({
+      code:
+        phase === 'syntax'
+          ? e instanceof SyntaxError
+            ? 'invalid_syntax'
+            : 'compilation_error'
+          : 'runtime_exception',
+      phase,
+      message: e instanceof Error && e.message ? e.message : 'Unknown calculation runtime error.',
+    });
     if (typeof options.onError === 'function') {
       options.onError(e);
     }
@@ -87,5 +123,7 @@ export function runExpression(
       console.warn('[form0] Expression evaluation failed:', e.message);
     }
     return null;
+  } finally {
+    restoreResultScope();
   }
 }

package/src/engine/event-operation-scope.js

@@ -0,0 +1,61 @@
+import {
+  __invokeBoundEventBuiltin,
+  __runWithEventOperationScope,
+} from '../builtins/event/event-operations-collector.js';
+
+const EVENT_OPERATION_BUILTINS = ['ALERT', 'SETVALUE', 'ON', 'OFF'];
+
+/**
+ * Create an operation scope owned by one synchronous event execution.
+ * @param {Function} onLateOperation - Receives only the discarded operation name
+ * @returns {Object} Private scope
+ */
+export function createEventOperationScope(onLateOperation) {
+  let open = true;
+  let operations = [];
+
+  return {
+    collect(operation) {
+      if (open) {
+        operations.push(operation);
+        return;
+      }
+
+      onLateOperation(operation?.operation || operation?.type || 'unknown');
+    },
+    close() {
+      if (!open) return [];
+      open = false;
+      const collected = operations;
+      operations = [];
+      return collected;
+    },
+  };
+}
+
+/**
+ * Bind canonical event operation builtins to their originating scope.
+ * Intentional helper overrides are left untouched.
+ */
+export function bindEventBuiltins(context, canonicalBuiltins, scope) {
+  const boundContext = { ...context };
+
+  for (const name of EVENT_OPERATION_BUILTINS) {
+    const builtin = canonicalBuiltins[name];
+    if (context[name] === builtin) {
+      boundContext[name] = (...args) => __invokeBoundEventBuiltin(scope, builtin, args);
+    }
+  }
+
+  return boundContext;
+}
+
+/** Run synchronous work while raw canonical builtins target this scope. */
+export function runInEventOperationScope(scope, work) {
+  return __runWithEventOperationScope(scope, work);
+}
+
+/** Close a scope and return its operations in creation order. */
+export function closeEventOperationScope(scope) {
+  return scope.close();
+}

package/src/engine/event-source.js

@@ -0,0 +1,164 @@
+import { parse } from 'acorn';
+
+/** Retains authored callback source without depending on engine-specific toString output. */
+export function createEventSourceRegistry() {
+  const sources = new WeakMap();
+
+  function prepare(code, context) {
+    let tree;
+    try {
+      // Event scripts are Function bodies, rather than modules or global scripts.
+      tree = parse(code, { ecmaVersion: 'latest', sourceType: 'commonjs' });
+    } catch {
+      // Let the existing evaluator validate and report invalid/unsupported source.
+      return { code, context };
+    }
+
+    const identifiers = new Set();
+    function collectIdentifiers(node) {
+      if (!node || typeof node !== 'object') return;
+      if (node.type === 'Identifier') identifiers.add(node.name);
+      for (const value of Object.values(node)) {
+        if (Array.isArray(value)) value.forEach(collectIdentifiers);
+        else if (value && typeof value === 'object') collectIdentifiers(value);
+      }
+    }
+    collectIdentifiers(tree);
+    let captureName = '__form0CaptureEventSource';
+    while (identifiers.has(captureName) || Object.hasOwn(context, captureName)) captureName += '_';
+    const edits = [];
+    const propertyNames = new Map();
+
+    function inferredName(node, parent) {
+      if (node.id) return '';
+      if (parent?.type === 'VariableDeclarator' && parent.id.type === 'Identifier')
+        return parent.id.name;
+      if (
+        parent?.type === 'AssignmentExpression' &&
+        ['=', '||=', '&&=', '??='].includes(parent.operator) &&
+        parent.left.type === 'Identifier'
+      )
+        return parent.left.name;
+      if (parent?.type === 'AssignmentPattern' && parent.left.type === 'Identifier')
+        return parent.left.name;
+      if (parent?.type === 'Property' && parent.computed) {
+        // Preserve ToPropertyKey's single coercion and the inferred function name.
+        const key = parent.key;
+        edits.push({ position: key.start, rank: 0, text: `${captureName}.key(` });
+        edits.push({ position: key.end, rank: 2, text: `,${node.start})` });
+        return { computed: node.start };
+      }
+      if (
+        (parent?.type === 'Property' || parent?.type === 'PropertyDefinition') &&
+        (!parent.computed || parent.key.type === 'Literal')
+      ) {
+        if (parent.key.type === 'PrivateIdentifier') return `#${parent.key.name}`;
+        return parent.key.type === 'Identifier' ? parent.key.name : String(parent.key.value);
+      }
+      return '';
+    }
+
+    function visit(node, parent) {
+      if (!node || typeof node !== 'object') return;
+      if (node.type === 'Program' || node.type === 'BlockStatement') {
+        const declarations = node.body.filter(
+          (statement) => statement.type === 'FunctionDeclaration'
+        );
+        if (declarations.length) {
+          let position = node.type === 'Program' ? node.start : node.start + 1;
+          for (const statement of node.body) {
+            if (
+              statement.type !== 'ExpressionStatement' ||
+              statement.expression.type !== 'Literal' ||
+              typeof statement.expression.value !== 'string'
+            )
+              break;
+            position = statement.end;
+          }
+          const text = declarations
+            .map(
+              (declaration) =>
+                `${captureName}(${declaration.id.name},${JSON.stringify(code.slice(declaration.start, declaration.end))});`
+            )
+            .join('');
+          edits.push({ position, rank: 1, text: `;${text}` });
+        }
+      }
+      if (
+        (node.type === 'FunctionExpression' || node.type === 'ArrowFunctionExpression') &&
+        !(parent?.type === 'Property' && (parent.method || parent.kind !== 'init')) &&
+        parent?.type !== 'MethodDefinition' &&
+        // Dynamic class keys need class-specific name metadata; keep their legacy path.
+        !(parent?.type === 'PropertyDefinition' && parent.computed && parent.key.type !== 'Literal')
+      ) {
+        const source = code.slice(node.start, node.end);
+        const name = inferredName(node, parent);
+        const nameExpression =
+          typeof name === 'object'
+            ? `${captureName}.nameFor(${name.computed})`
+            : JSON.stringify(name);
+        edits.push({ position: node.start, rank: 0, text: `${captureName}(` });
+        edits.push({
+          position: node.end,
+          rank: 2,
+          text: `,${JSON.stringify(source)},${nameExpression})`,
+        });
+      }
+      for (const [key, value] of Object.entries(node)) {
+        if (key === 'start' || key === 'end') continue;
+        if (Array.isArray(value)) value.forEach((child) => visit(child, node));
+        else if (value && typeof value === 'object') visit(value, node);
+      }
+    }
+    visit(tree, null);
+
+    let prepared = code;
+    // At shared boundaries apply openers first, then hoisted captures, then closers.
+    for (const { position, text } of edits.sort(
+      (a, b) => b.position - a.position || a.rank - b.rank
+    )) {
+      prepared = prepared.slice(0, position) + text + prepared.slice(position);
+    }
+
+    const capture = (callback, source, name) => {
+      sources.set(callback, source);
+      if (name && !callback.name)
+        Object.defineProperty(callback, 'name', { value: name, configurable: true });
+      return callback;
+    };
+    capture.key = (value, id) => {
+      const key = Reflect.ownKeys({ [value]: null })[0];
+      propertyNames.set(
+        id,
+        typeof key === 'symbol'
+          ? key.description === undefined
+            ? ''
+            : `[${key.description}]`
+          : key
+      );
+      return key;
+    };
+    capture.nameFor = (id) => propertyNames.get(id);
+
+    return {
+      code: prepared,
+      context: {
+        ...context,
+        [captureName]: capture,
+      },
+    };
+  }
+
+  function getSource(callback) {
+    if (sources.has(callback)) return sources.get(callback);
+    const source = callback.toString();
+    if (/^function\b[^]*\{\s*\[\s*(?:native\s+code|bytecode)\s*\]\s*\}\s*$/.test(source.trim())) {
+      throw new Error(
+        'Event callback source is unavailable on this JavaScript engine. Define the callback in form.events.code.'
+      );
+    }
+    return source;
+  }
+
+  return { prepare, getSource };
+}