form0-core 0.1.3 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "form0-core",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
   },

package/src/engine/context-resolver.js

@@ -66,25 +66,54 @@ export class ContextResolver {
   }
 
   /**
-   * Determine if a field is accessible from the current execution context
+   * Resolve field access with structured metadata for editor integrations.
    * @param {Object} executionContext - Current execution context
    * @param {string} fieldName - Field data_name being accessed
-   * @returns {string} 'accessible', 'restricted', or 'not_found'
+   * @param {Object | null} [providedFieldInfo]
+   * @returns {{
+   *   level: 'accessible' | 'restricted' | 'not_found',
+   *   code: 'main_form' | 'same_repeatable_section' | 'ancestor_repeatable_context' | 'different_repeatable_section' | null,
+   *   message: string | null,
+   *   suggestion: string | null,
+   *   fieldInfo: Object | null,
+   * }}
    */
-  resolveFieldAccess(executionContext, fieldName) {
-    const fieldInfo = this.fieldOwnership.get(fieldName);
+  resolveFieldAccessInfo(executionContext, fieldName, providedFieldInfo = null) {
+    const fieldInfo = providedFieldInfo || this.fieldOwnership.get(fieldName) || null;
 
     if (!fieldInfo) {
-      return 'not_found';
+      return {
+        level: 'not_found',
+        code: null,
+        message: `Field '${fieldName}' does not exist in the form schema`,
+        suggestion: `Check that field '${fieldName}' exists in the form schema`,
+        fieldInfo: null,
+      };
     }
 
     // Main form fields (no parent RepeatableSection) are always accessible
     if (fieldInfo.parentPath.length === 0) {
-      return 'accessible';
+      return this.buildAccessInfo(
+        'accessible',
+        'main_form',
+        fieldName,
+        fieldInfo,
+        executionContext
+      );
     }
 
     // RepeatableSection field access depends on execution context
-    return this.checkRepeatableSectionAccess(executionContext, fieldInfo);
+    return this.checkRepeatableSectionAccessInfo(executionContext, fieldName, fieldInfo);
+  }
+
+  /**
+   * Determine if a field is accessible from the current execution context
+   * @param {Object} executionContext - Current execution context
+   * @param {string} fieldName - Field data_name being accessed
+   * @returns {string} 'accessible', 'restricted', or 'not_found'
+   */
+  resolveFieldAccess(executionContext, fieldName) {
+    return this.resolveFieldAccessInfo(executionContext, fieldName).level;
   }
 
   /**
@@ -94,22 +123,49 @@ export class ContextResolver {
    * @returns {string} 'accessible' or 'restricted'
    */
   checkRepeatableSectionAccess(executionContext, fieldInfo) {
+    return this.checkRepeatableSectionAccessInfo(
+      executionContext,
+      fieldInfo.field?.data_name || fieldInfo.preferredKey,
+      fieldInfo
+    ).level;
+  }
+
+  /**
+   * Check RepeatableSection field access and return structured access metadata.
+   * @param {Object} executionContext - Current execution context
+   * @param {string} fieldName - Field data_name being accessed
+   * @param {Object} fieldInfo - Field ownership information
+   * @returns {{
+   *   level: 'accessible' | 'restricted' | 'not_found',
+   *   code: 'main_form' | 'same_repeatable_section' | 'ancestor_repeatable_context' | 'different_repeatable_section' | null,
+   *   message: string | null,
+   *   suggestion: string | null,
+   *   fieldInfo: Object | null,
+   * }}
+   */
+  checkRepeatableSectionAccessInfo(executionContext, fieldName, fieldInfo) {
     const { type: contextType, eventType, fieldName: contextFieldName } = executionContext;
 
     if (contextType === 'calculation') {
       // CalculatedField can only access fields in same RepeatableSection context
       const calculationFieldInfo = this.fieldOwnership.get(contextFieldName);
       if (!calculationFieldInfo) {
-        return 'restricted'; // Unknown calculation field
+        return this.buildAccessInfo(
+          'restricted',
+          'different_repeatable_section',
+          fieldName,
+          fieldInfo,
+          executionContext
+        );
       }
 
-      // Check if both fields have the same RepeatableSection ancestry
-      return this.haveSameRepeatableSectionContext(
+      return this.resolveRepeatableSectionRelationship(
         calculationFieldInfo.parentPath,
-        fieldInfo.parentPath
-      )
-        ? 'accessible'
-        : 'restricted';
+        fieldInfo.parentPath,
+        fieldName,
+        fieldInfo,
+        executionContext
+      );
     }
 
     if (contextType === 'event') {
@@ -118,38 +174,75 @@ export class ContextResolver {
       switch (eventInfo.scope) {
         case 'main':
           // Record events can't access RepeatableSection fields
-          return 'restricted';
+          return this.buildAccessInfo(
+            'restricted',
+            'different_repeatable_section',
+            fieldName,
+            fieldInfo,
+            executionContext
+          );
 
         case 'contextual':
           // Field events can access fields in same RepeatableSection context
           if (!contextFieldName) {
-            return 'restricted'; // No field context
+            return this.buildAccessInfo(
+              'restricted',
+              'different_repeatable_section',
+              fieldName,
+              fieldInfo,
+              executionContext
+            );
           }
 
           const triggerFieldInfo = this.fieldOwnership.get(contextFieldName);
           if (!triggerFieldInfo) {
-            return 'restricted'; // Unknown trigger field
+            return this.buildAccessInfo(
+              'restricted',
+              'different_repeatable_section',
+              fieldName,
+              fieldInfo,
+              executionContext
+            );
           }
 
-          return this.haveSameRepeatableSectionContext(
+          return this.resolveRepeatableSectionRelationship(
             triggerFieldInfo.parentPath,
-            fieldInfo.parentPath
-          )
-            ? 'accessible'
-            : 'restricted';
+            fieldInfo.parentPath,
+            fieldName,
+            fieldInfo,
+            executionContext
+          );
 
         case 'repeatable':
           // RepeatableSection events - future implementation
           // For now, assume accessible (will be refined when implemented)
-          return 'accessible';
+          return this.buildAccessInfo(
+            'accessible',
+            'same_repeatable_section',
+            fieldName,
+            fieldInfo,
+            executionContext
+          );
 
         default:
-          return 'restricted';
+          return this.buildAccessInfo(
+            'restricted',
+            'different_repeatable_section',
+            fieldName,
+            fieldInfo,
+            executionContext
+          );
       }
     }
 
     // Unknown context type
-    return 'restricted';
+    return this.buildAccessInfo(
+      'restricted',
+      'different_repeatable_section',
+      fieldName,
+      fieldInfo,
+      executionContext
+    );
   }
 
   /**
@@ -159,25 +252,118 @@ export class ContextResolver {
    * @returns {boolean} True if they share the same RepeatableSection context
    */
   haveSameRepeatableSectionContext(parentPath1, parentPath2) {
-    const contextPath = parentPath1;
-    const targetPath = parentPath2;
+    return (
+      this.resolveRepeatableSectionAccessCode(parentPath1, parentPath2) !==
+      'different_repeatable_section'
+    );
+  }
 
-    // Main form calculations can only access other main form fields
-    if (contextPath.length === 0) {
-      return targetPath.length === 0;
+  resolveRepeatableSectionRelationship(
+    contextPath,
+    targetPath,
+    fieldName,
+    fieldInfo,
+    executionContext
+  ) {
+    const code = this.resolveRepeatableSectionAccessCode(contextPath, targetPath);
+    const level = code === 'different_repeatable_section' ? 'restricted' : 'accessible';
+
+    return this.buildAccessInfo(level, code, fieldName, fieldInfo, executionContext);
+  }
+
+  resolveRepeatableSectionAccessCode(contextPath, targetPath) {
+    if (targetPath.length === 0) {
+      return 'main_form';
     }
 
-    // Child context can access its own fields
     if (ContextResolver.pathsEqual(contextPath, targetPath)) {
-      return true;
+      return contextPath.length === 0 ? 'main_form' : 'same_repeatable_section';
     }
 
-    // Child context can access ancestors (including main form)
-    if (targetPath.length < contextPath.length && ContextResolver.isPrefix(targetPath, contextPath)) {
-      return true;
+    if (
+      targetPath.length < contextPath.length &&
+      ContextResolver.isPrefix(targetPath, contextPath)
+    ) {
+      return targetPath.length === 0 ? 'main_form' : 'ancestor_repeatable_context';
+    }
+
+    return 'different_repeatable_section';
+  }
+
+  buildAccessInfo(level, code, fieldName, fieldInfo, executionContext) {
+    if (level === 'accessible') {
+      return {
+        level,
+        code,
+        message: null,
+        suggestion: null,
+        fieldInfo,
+      };
+    }
+
+    return {
+      level,
+      code,
+      message: `Field '${fieldName}' is not accessible from current context`,
+      suggestion: this.buildRestrictedAccessSuggestion(
+        executionContext,
+        fieldName,
+        fieldInfo,
+        code
+      ),
+      fieldInfo,
+    };
+  }
+
+  buildRestrictedAccessSuggestion(executionContext, fieldName, fieldInfo, code) {
+    const { type: contextType, eventType } = executionContext;
+
+    if (contextType === 'calculation') {
+      if (code === 'different_repeatable_section') {
+        return `CalculatedField can only access fields in the same RepeatableSection or ancestor contexts. Field '${fieldName}' is in RepeatableSection: ${this.formatRepeatableSectionPath(fieldInfo.parentPath)}`;
+      }
     }
 
-    return false;
+    if (contextType === 'event') {
+      const eventInfo = getEventInfo(eventType);
+
+      if (eventInfo.scope === 'main') {
+        return `Record-level events (like '${eventType}') can only access main form fields, not RepeatableSection fields`;
+      }
+
+      if (eventInfo.scope === 'contextual') {
+        return `Field events can only access fields in the same RepeatableSection or ancestor contexts as the triggering field`;
+      }
+    }
+
+    return 'Check the field access rules for your current context';
+  }
+
+  formatRepeatableSectionPath(parentPath) {
+    if (!Array.isArray(parentPath) || parentPath.length === 0) {
+      return 'main form';
+    }
+
+    return parentPath
+      .map((_, index) => this.formatRepeatableSectionSegment(parentPath.slice(0, index + 1)))
+      .join(' -> ');
+  }
+
+  formatRepeatableSectionSegment(currentPath) {
+    for (const treeInfo of this.repeatableSectionTree.values()) {
+      if (!ContextResolver.pathsEqual(treeInfo.currentPath, currentPath)) {
+        continue;
+      }
+
+      const dataName = treeInfo.field?.data_name || treeInfo.preferredKey;
+      if (dataName === treeInfo.preferredKey) {
+        return dataName;
+      }
+
+      return `${dataName} (${treeInfo.preferredKey})`;
+    }
+
+    return currentPath[currentPath.length - 1];
   }
 
   static isPrefix(prefix, fullPath) {
@@ -221,19 +407,26 @@ export class ContextResolver {
    * @returns {Object} Warning object with structured information
    */
   generateAccessWarning(executionContext, fieldName, reason) {
-    const fieldInfo = this.fieldOwnership.get(fieldName);
-    const suggestion = this.generateAccessSuggestion(executionContext, fieldName, fieldInfo);
+    const accessInfo =
+      reason === 'not_found'
+        ? this.resolveFieldAccessInfo(executionContext, fieldName)
+        : this.resolveFieldAccessInfo(executionContext, fieldName);
+    const fieldInfo = accessInfo.fieldInfo;
 
     return {
       type: 'FIELD_ACCESS_WARNING',
       fieldName,
       executionContext,
       reason,
+      accessCode: accessInfo.code,
       message:
-        reason === 'not_found'
+        accessInfo.message ||
+        (reason === 'not_found'
           ? `Field '${fieldName}' does not exist in the form schema`
-          : `Field '${fieldName}' is not accessible from current context`,
-      suggestion,
+          : `Field '${fieldName}' is not accessible from current context`),
+      suggestion:
+        accessInfo.suggestion ||
+        this.generateAccessSuggestion(executionContext, fieldName, fieldInfo),
       fieldContext: fieldInfo
         ? {
             parentPath: fieldInfo.parentPath,
@@ -252,28 +445,26 @@ export class ContextResolver {
    * @returns {string} Helpful suggestion message
    */
   generateAccessSuggestion(executionContext, fieldName, fieldInfo) {
-    if (!fieldInfo) {
-      return `Check that field '${fieldName}' exists in the form schema`;
+    const accessInfo = this.resolveFieldAccessInfo(executionContext, fieldName, fieldInfo);
+
+    if (accessInfo.suggestion) {
+      return accessInfo.suggestion;
     }
 
-    const { type: contextType, eventType, fieldName: contextFieldName } = executionContext;
+    if (accessInfo.level === 'not_found') {
+      return `Check that field '${fieldName}' exists in the form schema`;
+    }
 
-    if (contextType === 'calculation') {
-      if (fieldInfo.parentPath.length === 0) {
-        return 'Main form fields are always accessible from calculations';
-      } else {
-        return `CalculatedField can only access fields in the same RepeatableSection. Field '${fieldName}' is in RepeatableSection: ${fieldInfo.parentPath.join(' -> ')}`;
-      }
+    if (accessInfo.code === 'main_form') {
+      return 'Main form fields are always accessible from calculations';
     }
 
-    if (contextType === 'event') {
-      const eventInfo = getEventInfo(eventType);
+    if (accessInfo.code === 'same_repeatable_section') {
+      return 'Fields in the same RepeatableSection are accessible from this context';
+    }
 
-      if (eventInfo.scope === 'main') {
-        return `Record-level events (like '${eventType}') can only access main form fields, not RepeatableSection fields`;
-      } else if (eventInfo.scope === 'contextual') {
-        return `Field events can only access fields in the same RepeatableSection context as the triggering field`;
-      }
+    if (accessInfo.code === 'ancestor_repeatable_context') {
+      return 'Fields in ancestor RepeatableSection contexts are accessible from this context';
     }
 
     return 'Check the field access rules for your current context';

package/src/engine/evaluator.js

@@ -3,6 +3,10 @@ import { __setEvalContext, __clearEvalContext } from '../builtins/control/eval.j
 import { __setDataNamesContext, __clearDataNamesContext } from '../builtins/schema/datanames.js';
 import { validateExpression, createSecureContext, withTimeout } from '../security/validation.js';
 import { DEFAULT_SECURITY_CONFIG } from '../security/config.js';
+import {
+  isMultilineCalculationExpression,
+  normalizeInlineCalculationExpression,
+} from '../utilities/calculation-expression-utils.js';
 
 export function runExpression(
   expr,
@@ -34,8 +38,7 @@ export function runExpression(
 
       try {
         // Handle both expressions and multi-line code (Windows-safe)
-        const isMultiLine =
-          expr.includes('\r\n') || expr.includes('\n') || expr.includes('function');
+        const isMultiLine = isMultilineCalculationExpression(expr);
 
         if (isMultiLine) {
           // Execute as code block (recompile each time for now)
@@ -46,7 +49,8 @@ export function runExpression(
           return consumed.called ? consumed.value : result;
         } else {
           // Execute as expression (existing behavior)
-          const fn = new Function(...keys, `return (${expr});`);
+          const inlineExpression = normalizeInlineCalculationExpression(expr);
+          const fn = new Function(...keys, `return (${inlineExpression});`);
           const result = fn(...values);
           const consumed = __consumeResult();
           return consumed.called ? consumed.value : result;

package/src/utilities/calculation-editor.js

@@ -6,6 +6,10 @@ import {
 import { ContextResolver } from '../engine/context-resolver.js';
 import { DEFAULT_SECURITY_CONFIG } from '../security/config.js';
 import { validateExpression } from '../security/validation.js';
+import {
+  isMultilineCalculationExpression,
+  normalizeInlineCalculationExpression,
+} from './calculation-expression-utils.js';
 import { flattenFields } from './field-helpers.js';
 
 const COMMON_GLOBAL_FUNCTIONS = new Set([
@@ -157,6 +161,40 @@ function cloneCatalogDefinition(definition) {
   };
 }
 
+function toCalculationReferenceAccess(accessInfo) {
+  return {
+    level: accessInfo.level,
+    code: accessInfo.code,
+    message: accessInfo.message,
+    suggestion: accessInfo.suggestion,
+  };
+}
+
+function toCalculationReferenceDefinition(field, resolver, executionContext) {
+  const accessInfo = resolver.resolveFieldAccessInfo(executionContext, field.data_name);
+
+  if (accessInfo.level === 'not_found') {
+    return null;
+  }
+
+  return {
+    key: typeof field.key === 'string' ? field.key : field.data_name,
+    reference: `$${field.data_name}`,
+    dataName: field.data_name,
+    label: typeof field.label === 'string' ? field.label : field.data_name,
+    type: typeof field.type === 'string' ? field.type : 'UnknownField',
+    description: typeof field.description === 'string' ? field.description : null,
+    displayStyle:
+      field.display && typeof field.display === 'object' && typeof field.display.style === 'string'
+        ? field.display.style
+        : typeof field.display === 'string'
+          ? field.display
+          : null,
+    parentPath: resolver.getFieldInfo(field.data_name)?.parentPath || [],
+    access: toCalculationReferenceAccess(accessInfo),
+  };
+}
+
 function createIssue({ code, severity, message, symbol = null, index = null, length = null }) {
   return {
     code,
@@ -178,15 +216,15 @@ function addIssue(issues, issueKeys, issue) {
 }
 
 function validateSyntax(expression) {
-  const isMultiLine =
-    expression.includes('\r\n') || expression.includes('\n') || expression.includes('function');
+  const isMultiLine = isMultilineCalculationExpression(expression);
 
   if (isMultiLine) {
     new Function(expression);
     return;
   }
 
-  new Function(`return (${expression});`);
+  const inlineExpression = normalizeInlineCalculationExpression(expression);
+  new Function(`return (${inlineExpression});`);
 }
 
 function createSchemaFilteredSecurityConfig(securityConfig) {
@@ -220,6 +258,12 @@ function createSchemaFilteredSecurityConfig(securityConfig) {
  * @property {string | null} description
  * @property {string | null} displayStyle
  * @property {string[]} parentPath
+ * @property {{
+ *   level: 'accessible' | 'restricted',
+ *   code: 'main_form' | 'same_repeatable_section' | 'ancestor_repeatable_context' | 'different_repeatable_section',
+ *   message: string | null,
+ *   suggestion: string | null,
+ * }} access
  *
  * @typedef {Object} CalculationExpressionIssue
  * @property {string} code
@@ -246,9 +290,14 @@ export function getCalculationBuiltinCatalog() {
  * @param {Object} options
  * @param {Object} options.schema
  * @param {string} options.fieldDataName
+ * @param {boolean} [options.includeRestricted=false]
  * @returns {CalculationReferenceDefinition[]}
  */
-export function getCalculationReferenceCatalog({ schema, fieldDataName }) {
+export function getCalculationReferenceCatalog({
+  schema,
+  fieldDataName,
+  includeRestricted = false,
+}) {
   const form = normalizeFormSchema(schema);
   const resolver = new ContextResolver(form);
   const executionContext = buildExecutionContext(form, fieldDataName, resolver);
@@ -262,26 +311,9 @@ export function getCalculationReferenceCatalog({ schema, fieldDataName }) {
         field.type !== 'RepeatableSection' &&
         field.type !== 'BuildingPlanSection'
     )
-    .filter(
-      (field) => resolver.resolveFieldAccess(executionContext, field.data_name) === 'accessible'
-    )
-    .map((field) => ({
-      key: typeof field.key === 'string' ? field.key : field.data_name,
-      reference: `$${field.data_name}`,
-      dataName: field.data_name,
-      label: typeof field.label === 'string' ? field.label : field.data_name,
-      type: typeof field.type === 'string' ? field.type : 'UnknownField',
-      description: typeof field.description === 'string' ? field.description : null,
-      displayStyle:
-        field.display &&
-        typeof field.display === 'object' &&
-        typeof field.display.style === 'string'
-          ? field.display.style
-          : typeof field.display === 'string'
-            ? field.display
-            : null,
-      parentPath: resolver.getFieldInfo(field.data_name)?.parentPath || [],
-    }));
+    .map((field) => toCalculationReferenceDefinition(field, resolver, executionContext))
+    .filter((reference) => reference !== null)
+    .filter((reference) => includeRestricted || reference.access.level === 'accessible');
 }
 
 /**
@@ -311,6 +343,7 @@ export function analyzeCalculationExpression({
   const usedBuiltinNames = new Set();
   const referencedFields = [];
   const referencedFieldNames = new Set();
+  const setResultCalls = [];
 
   const normalizedExpression = typeof expression === 'string' ? expression : '';
   const form = normalizeFormSchema(schema);
@@ -407,6 +440,10 @@ export function analyzeCalculationExpression({
         usedBuiltins.push(call.name);
       }
 
+      if (call.name === 'SETRESULT') {
+        setResultCalls.push(call);
+      }
+
       if (builtinMetadata.status === 'unavailable') {
         addIssue(
           issues,
@@ -452,31 +489,50 @@ export function analyzeCalculationExpression({
     );
   }
 
+  if (setResultCalls.length > 1) {
+    const duplicateSetResultCall = setResultCalls[1];
+    addIssue(
+      issues,
+      issueKeys,
+      createIssue({
+        code: 'multiple_setresult_calls',
+        severity: 'error',
+        message: 'SETRESULT() can only be used once in a CalculatedField expression.',
+        symbol: duplicateSetResultCall.name,
+        index: duplicateSetResultCall.index,
+        length: duplicateSetResultCall.length,
+      })
+    );
+  }
+
   for (const reference of extractFieldReferenceMatches(normalizedExpression)) {
     if (!referencedFieldNames.has(reference.fieldName)) {
       referencedFieldNames.add(reference.fieldName);
       referencedFields.push(reference.fieldName);
     }
 
-    const accessLevel = resolver.resolveFieldAccess(executionContext, reference.fieldName);
-    if (accessLevel === 'restricted') {
+    const accessInfo = resolver.resolveFieldAccessInfo(executionContext, reference.fieldName);
+    if (accessInfo.level === 'restricted') {
       addIssue(
         issues,
         issueKeys,
         createIssue({
           code: 'restricted_field_reference',
           severity: 'error',
-          message: resolver.generateAccessSuggestion(
-            executionContext,
-            reference.fieldName,
-            resolver.getFieldInfo(reference.fieldName)
-          ),
+          message:
+            accessInfo.suggestion ||
+            accessInfo.message ||
+            resolver.generateAccessSuggestion(
+              executionContext,
+              reference.fieldName,
+              resolver.getFieldInfo(reference.fieldName)
+            ),
           symbol: reference.reference,
           index: reference.index,
           length: reference.length,
         })
       );
-    } else if (accessLevel === 'not_found') {
+    } else if (accessInfo.level === 'not_found') {
       addIssue(
         issues,
         issueKeys,

package/src/utilities/calculation-expression-utils.js

@@ -0,0 +1,15 @@
+export function isMultilineCalculationExpression(expression) {
+  const normalizedExpression = typeof expression === 'string' ? expression : '';
+
+  return (
+    normalizedExpression.includes('\r\n') ||
+    normalizedExpression.includes('\n') ||
+    normalizedExpression.includes('function')
+  );
+}
+
+export function normalizeInlineCalculationExpression(expression) {
+  const normalizedExpression = typeof expression === 'string' ? expression : '';
+
+  return normalizedExpression.replace(/;+\s*$/u, '');
+}