form0-core 0.6.0 → 0.7.0

package/src/engine/submission-validation.js

@@ -0,0 +1,125 @@
+/**
+ * @typedef {Object} SubmissionFinding
+ * @property {'required'|'error'|'custom'} kind
+ * @property {string} message
+ * @property {Object[]} instancePath Complete row ancestry; [] for root.
+ * @property {string} [fieldName] Absent for scope-level custom findings.
+ * @property {string} [fieldKey]
+ *
+ * @typedef {Object} SubmissionValidationSummary
+ * @property {boolean} hasErrors
+ * @property {SubmissionFinding[]} requiredFieldErrors
+ * @property {SubmissionFinding[]} generalErrors
+ * @property {SubmissionFinding[]} scopeIssues
+ * @property {SubmissionFinding[]} orderedIssues
+ */
+
+import { prepareRecordContext, visitRecordScopes } from './record-context.js';
+
+const hasText = (value) => typeof value === 'string' && value.trim().length > 0;
+const hasChoice = (entries) =>
+  Array.isArray(entries) &&
+  entries.some(
+    (entry) => entry && ((entry.value != null && entry.value !== '') || hasText(entry.label))
+  );
+const hasOther = (entries) =>
+  Array.isArray(entries) &&
+  entries.some((entry) =>
+    typeof entry === 'string'
+      ? hasText(entry)
+      : entry && (hasText(entry.label) || (entry.value != null && entry.value !== ''))
+  );
+
+/** Type-aware input emptiness shared with submission participation; zero/false are values. */
+export function isFieldValueEmpty(field, value) {
+  if (!field || value == null) return true;
+  switch (field.type) {
+    case 'TextField':
+    case 'CalculatedField':
+    case 'DateField':
+    case 'TimeField':
+    case 'TitleField':
+    case 'StatusField':
+      return typeof value === 'string' && !value.trim();
+    case 'NumericField':
+      return typeof value === 'number' ? false : typeof value === 'string' ? !value.trim() : true;
+    case 'SingleChoiceField':
+    case 'BooleanField':
+      return !hasChoice(value.choice) && !hasOther(value.other);
+    case 'MultiChoiceField':
+      return !hasChoice(value.choices) && !hasOther(value.other);
+    case 'PhotoField':
+    case 'VideoField':
+      return !Array.isArray(value) || value.length === 0;
+    case 'SignatureField':
+      return typeof value === 'string'
+        ? !value.trim()
+        : !(hasText(value?.data) || hasText(value?.url));
+    default:
+      return Array.isArray(value)
+        ? value.length === 0
+        : typeof value === 'object'
+          ? Object.keys(value).length === 0
+          : false;
+  }
+}
+
+export function validateScope(scope) {
+  const findings = [];
+  if (!scope.participating) return findings;
+  const { record, template, instancePath } = scope;
+  for (const field of template.fields) {
+    if (['Section', 'BuildingPlanSection', 'RepeatableSection', 'LabelField'].includes(field.type))
+      continue;
+    if (
+      record.visible?.[field.data_name] === false ||
+      !(template.chains.get(field.data_name) || []).every(
+        (name) => record.visible?.[name] !== false
+      )
+    )
+      continue;
+    const message = record.errors?.[field.data_name];
+    const required = record.required?.[field.data_name] ?? field.required;
+    const base = {
+      fieldName: field.data_name,
+      fieldKey: field.key || field.data_name,
+      instancePath,
+    };
+    if (message) findings.push({ ...base, kind: 'error', message });
+    else if (required && isFieldValueEmpty(field, record.values?.[field.data_name]))
+      findings.push({ ...base, kind: 'required', message: 'This field is required' });
+  }
+  return findings;
+}
+
+export function validateSubmissionWithContext(snapshot, context, customIssues = []) {
+  const orderedIssues = [];
+  const issuesByScope = new Map();
+  for (const custom of customIssues) {
+    const key = JSON.stringify(custom.instancePath || []);
+    if (!issuesByScope.has(key)) issuesByScope.set(key, []);
+    issuesByScope.get(key).push(custom);
+  }
+  visitRecordScopes(snapshot, context, (scope) => {
+    orderedIssues.push(...validateScope(scope));
+    if (scope.participating)
+      for (const custom of issuesByScope.get(JSON.stringify(scope.instancePath)) || [])
+        orderedIssues.push({ ...custom, instancePath: scope.instancePath, kind: 'custom' });
+  });
+  return {
+    hasErrors: orderedIssues.length > 0,
+    requiredFieldErrors: orderedIssues.filter((issue) => issue.kind === 'required'),
+    generalErrors: orderedIssues.filter((issue) => issue.kind === 'error'),
+    scopeIssues: orderedIssues.filter((issue) => issue.kind === 'custom'),
+    orderedIssues,
+  };
+}
+
+/**
+ * Validate an already evaluated runtime record tree; never evaluates or mutates intrinsic errors.
+ * @param {{schema: Object, snapshot: Object, validationIssues?: Object[]}} options
+ * @returns {SubmissionValidationSummary} Ordered field and scope findings; no freshness assertion.
+ */
+export function validateSubmission({ schema, snapshot, validationIssues = [] }) {
+  return validateSubmissionWithContext(snapshot, prepareRecordContext(schema), validationIssues);
+}

package/src/index.js

@@ -86,3 +86,6 @@ export {
   applyFormMutationBatch,
 } from './authoring/form-authoring.js';
 export { INVALID } from './builtins/event/control/invalid.js';
+
+export { createRecordEvaluator } from './engine/record-evaluator.js';
+export { validateSubmission, isFieldValueEmpty } from './engine/submission-validation.js';

package/src/schema/schema-validator.js

@@ -85,6 +85,11 @@ export function validateSchemaWithContext(form, contextResolver) {
   const duplicateDataNames = new Set();
   const duplicateKeys = new Set();
   const errors = [];
+  if (
+    form.repeatable_recalculation !== undefined &&
+    !['automatic', 'confirm'].includes(form.repeatable_recalculation)
+  )
+    errors.push('form.repeatable_recalculation must be automatic or confirm');
 
   const formAIValidation = validateFormAIMetadata(form);
   if (!formAIValidation.isValid) {

package/src/utilities/calculation-dependencies.js

@@ -1,3 +1,4 @@
+import { analyzeRepeatableCollections } from './repeatable-collections.js';
 import { ContextResolver } from '../engine/context-resolver.js';
 import { flattenFields } from './field-helpers.js';
 
@@ -378,7 +379,7 @@ export function removeEvalContents(code) {
 }
 
 export function extractStaticFieldReferenceMatches(code) {
-  const cleanedCode = removeEvalContents(code);
+  const cleanedCode = removeEvalContents(analyzeRepeatableCollections(code).scalarSource);
   const fieldRegex = /\$([a-zA-Z_][a-zA-Z0-9_]*)/g;
   const matches = [];
   let match;

package/src/utilities/calculation-editor.js

@@ -1,3 +1,5 @@
+import { analyzeRepeatableCollections } from './repeatable-collections.js';
+import { createRecordEvaluator } from '../engine/record-evaluator.js';
 import { parse } from 'acorn';
 import { BUILTIN_CONTEXTS } from '../builtins/builtin-metadata.js';
 import {
@@ -363,6 +365,7 @@ function createSimulationErrorResult(runtimeError, warnings = []) {
  * @property {string | null} description
  * @property {string | null} displayStyle
  * @property {string[]} parentPath
+ * @property {boolean} [collectionOnly] Section references are valid only in collection calls.
  * @property {{
  *   level: 'accessible' | 'restricted',
  *   code: 'main_form' | 'same_repeatable_section' | 'ancestor_repeatable_context' | 'different_repeatable_section',
@@ -396,18 +399,20 @@ export function getCalculationBuiltinCatalog() {
  * @param {Object} options.schema
  * @param {string} options.fieldDataName
  * @param {boolean} [options.includeRestricted=false]
+ * @param {boolean} [options.includeCollections=false] Include collection-only section references.
  * @returns {CalculationReferenceDefinition[]}
  */
 export function getCalculationReferenceCatalog({
   schema,
   fieldDataName,
   includeRestricted = false,
+  includeCollections = false,
 }) {
   const form = normalizeCalculationFormSchema(schema);
   const resolver = new ContextResolver(form);
   const executionContext = buildCalculationExecutionContext(form, fieldDataName, resolver);
 
-  return flattenFields(form.elements)
+  const scalarReferences = flattenFields(form.elements)
     .filter((field) => field && typeof field === 'object')
     .filter((field) => field.data_name && field.data_name !== fieldDataName)
     .filter(
@@ -419,6 +424,33 @@ export function getCalculationReferenceCatalog({
     .map((field) => toCalculationReferenceDefinition(field, resolver, executionContext))
     .filter((reference) => reference !== null)
     .filter((reference) => includeRestricted || reference.access.level === 'accessible');
+  if (!includeCollections) return scalarReferences;
+  const collections = [...resolver.repeatableSectionTree.values()]
+    .map((info) => {
+      const accessible =
+        ContextResolver.isPrefix(executionContext.parentPath, info.parentPath) ||
+        ContextResolver.isPrefix(info.parentPath, executionContext.parentPath);
+      return {
+        key: info.preferredKey,
+        reference: `$${info.field.data_name}`,
+        dataName: info.field.data_name,
+        label: info.field.label,
+        type: 'RepeatableSection',
+        description: info.field.description,
+        displayStyle: null,
+        parentPath: [...info.parentPath],
+        collectionOnly: true,
+        access: {
+          level: accessible ? 'accessible' : 'restricted',
+          code: accessible ? 'same_repeatable_section' : 'different_repeatable_section',
+          message: accessible ? null : 'Collection is outside the record ancestry.',
+          suggestion:
+            'Use this reference only as the first argument of REPEATABLEVALUES or REPEATABLESUM.',
+        },
+      };
+    })
+    .filter((reference) => includeRestricted || reference.access.level === 'accessible');
+  return [...scalarReferences, ...collections];
 }
 
 /**
@@ -434,6 +466,7 @@ export function getCalculationReferenceCatalog({
  *   issues: CalculationExpressionIssue[],
  *   usedBuiltins: string[],
  *   referencedFields: string[],
+ *   collectionReferences: Array<{builtinName: string, sectionDataName: string, targetDataName: string, startIndex: number, endIndex: number}>,
  * }}
  */
 export function analyzeCalculationExpression({
@@ -651,6 +684,13 @@ export function analyzeCalculationExpression({
     );
   }
 
+  const collectionAnalysis = analyzeRepeatableCollections(
+    normalizedExpression,
+    resolver,
+    fieldDataName
+  );
+  for (const issue of collectionAnalysis.issues)
+    addIssue(issues, issueKeys, createIssue({ ...issue, severity: 'error' }));
   for (const reference of extractStaticFieldReferenceMatches(normalizedExpression)) {
     if (!referencedFieldNames.has(reference.fieldName)) {
       referencedFieldNames.add(reference.fieldName);
@@ -732,6 +772,13 @@ export function analyzeCalculationExpression({
     issues,
     usedBuiltins,
     referencedFields,
+    collectionReferences: collectionAnalysis.calls.map((call) => ({
+      builtinName: call.name,
+      sectionDataName: call.section,
+      targetDataName: call.target,
+      startIndex: call.index,
+      endIndex: call.index + call.length,
+    })),
   };
 }
 
@@ -757,6 +804,7 @@ export function analyzeCalculationExpression({
  *       fieldContext: Object | null,
  *     }>,
  *   },
+ *   runRecord: (options: {snapshot: Object, instancePath?: Object[], expression?: string}) => Promise<{result: unknown, runtimeError: string|null, warnings: Object[], evaluation?: Object}>,
  *   dispose: () => void,
  * }}
  */
@@ -774,6 +822,10 @@ export function createCalculationPreviewSession({
     return {
       run: () =>
         createSimulationErrorResult(`Field '${fieldDataName}' does not exist in the form schema.`),
+      runRecord: async () =>
+        createSimulationErrorResult(
+          `Field '${fieldDataName}' does not exist or is not a CalculatedField.`
+        ),
       dispose: () => {},
     };
   }
@@ -781,6 +833,10 @@ export function createCalculationPreviewSession({
   if (targetField.type !== 'CalculatedField') {
     return {
       run: () => createSimulationErrorResult(`Field '${fieldDataName}' is not a CalculatedField.`),
+      runRecord: async () =>
+        createSimulationErrorResult(
+          `Field '${fieldDataName}' does not exist or is not a CalculatedField.`
+        ),
       dispose: () => {},
     };
   }
@@ -852,6 +908,43 @@ export function createCalculationPreviewSession({
         );
       }
     },
+    runRecord: async ({ snapshot, instancePath = [], expression: nextExpression, ...options }) => {
+      if (disposed)
+        return createSimulationErrorResult('Calculation preview session has been disposed.');
+      if (typeof nextExpression === 'string') targetField.calculate = nextExpression;
+      const evaluator = createRecordEvaluator({
+        schema: simulationSchema,
+        security,
+        warningSystem,
+        diagnostics: { console: false },
+      });
+      const evaluation = await evaluator.evaluate(snapshot, { ...options, mode: 'refresh' });
+      if (evaluation.status !== 'evaluated')
+        return {
+          ...createSimulationErrorResult(evaluation.issues[0]?.message || 'Record preview failed.'),
+          evaluation,
+        };
+      let record = evaluation.snapshot;
+      for (const segment of instancePath)
+        record = record?.repeatable?.[segment.repeatableKey]?.[segment.index];
+      if (!record?.values || !Object.hasOwn(record.values, fieldDataName))
+        return {
+          ...createSimulationErrorResult(
+            'Preview instancePath must identify the record owning the calculated field.'
+          ),
+          evaluation,
+        };
+      const runtimeError =
+        evaluation.diagnostics.find(
+          (item) => item.fieldName === fieldDataName && item.severity === 'error'
+        )?.message || null;
+      return {
+        result: record?.values?.[fieldDataName] ?? null,
+        runtimeError,
+        warnings: sanitizeCollectedWarnings(warningSystem.getCollectedWarnings()),
+        evaluation,
+      };
+    },
     dispose: () => {
       disposed = true;
       warningSystem.clearCollectedWarnings();

package/src/utilities/record-data.js

@@ -0,0 +1,23 @@
+/** Clone portable record data without copying immutable binary media into JS memory. */
+export function copyRecordData(value, seen = new Map()) {
+  if (typeof value === 'function' || typeof value === 'symbol')
+    throw new Error('Record data must not contain functions or symbols.');
+  if (value === null || typeof value !== 'object') return value;
+  if (seen.has(value)) throw new Error('Record data must not contain cyclic references.');
+  if (value instanceof Date) return new Date(value.getTime());
+  if (typeof Blob === 'function' && value instanceof Blob) return value;
+  if (!Array.isArray(value) && ![Object.prototype, null].includes(Object.getPrototypeOf(value)))
+    throw new Error('Record data must use plain objects, arrays, dates or native media handles.');
+  const result = Array.isArray(value) ? [] : {};
+  seen.set(value, result);
+  for (const key of Object.keys(value)) {
+    Object.defineProperty(result, key, {
+      value: copyRecordData(value[key], seen),
+      enumerable: true,
+      writable: true,
+      configurable: true,
+    });
+  }
+  seen.delete(value);
+  return result;
+}

package/src/utilities/repeatable-collections.js

@@ -0,0 +1,170 @@
+import { parse } from 'acorn';
+import { ContextResolver } from '../engine/context-resolver.js';
+
+export const COLLECTION_NAMES = new Set(['REPEATABLEVALUES', 'REPEATABLESUM']);
+const VALUE_TYPES = new Set([
+  'TextField',
+  'NumericField',
+  'SingleChoiceField',
+  'MultiChoiceField',
+  'BooleanField',
+  'DateField',
+  'TimeField',
+  'CalculatedField',
+  'FormLinkField',
+]);
+
+/** Parse schema references without interpreting collection sources as scalar values. */
+export function analyzeRepeatableCollections(source, resolver = null, owner = null) {
+  const calls = [];
+  const issues = [];
+  if (!/\bREPEATABLE(?:VALUES|SUM)\b/.test(source || ''))
+    return { calls, issues, expression: source, scalarSource: source };
+  let tree;
+  try {
+    tree = parse(source, { ecmaVersion: 'latest', sourceType: 'commonjs' });
+  } catch {
+    return { calls, issues, expression: source, scalarSource: source };
+  }
+  const edits = [];
+  function visit(node, parent) {
+    if (!node || typeof node !== 'object') return;
+    if (
+      node.type === 'CallExpression' &&
+      node.callee?.name === 'EVAL' &&
+      node.arguments.some(
+        (argument) =>
+          argument.type === 'Literal' &&
+          typeof argument.value === 'string' &&
+          /\bREPEATABLE(?:VALUES|SUM)\s*\(/.test(argument.value)
+      )
+    )
+      issues.push({
+        code: 'dynamic_collection_unsupported',
+        message: 'Repeatable collection calls inside EVAL are unsupported; use direct calls.',
+        index: node.start,
+        length: node.end - node.start,
+      });
+    if (node.type === 'Identifier' && COLLECTION_NAMES.has(node.name)) {
+      if (parent?.type !== 'CallExpression' || parent.callee !== node) {
+        issues.push({
+          code: 'collection_alias_unsupported',
+          message: 'Repeatable collection builtins require direct calls.',
+          index: node.start,
+          length: node.end - node.start,
+        });
+      } else {
+        const [section, target] = parent.arguments;
+        const valid =
+          parent.arguments.length === 2 &&
+          section?.type === 'Identifier' &&
+          /^\$[a-zA-Z_][a-zA-Z0-9_]*$/.test(section.name) &&
+          target?.type === 'Literal' &&
+          typeof target.value === 'string';
+        if (!valid) {
+          issues.push({
+            code: 'invalid_collection_arguments',
+            message: `${node.name} requires a direct $repeatable_data_name and a literal target data_name.`,
+            index: parent.start,
+            length: parent.end - parent.start,
+          });
+        } else {
+          const call = {
+            name: node.name,
+            section: section.name.slice(1),
+            target: target.value,
+            index: section.start,
+            length: section.end - section.start,
+          };
+          calls.push(call);
+          edits.push({
+            start: section.start,
+            end: section.end,
+            value: JSON.stringify(call.section),
+          });
+          if (resolver) {
+            const info = resolver.repeatableSectionTree.get(call.section);
+            const fieldInfo = resolver.fieldOwnership.get(call.target);
+            const ownerPath = resolver.getFieldInfo(owner)?.parentPath || [];
+            let message = null;
+            if (!info) message = `Unknown RepeatableSection '${call.section}'.`;
+            else if (
+              !fieldInfo ||
+              !ContextResolver.pathsEqual(fieldInfo.parentPath, info.currentPath)
+            )
+              message = `Collection target '${call.target}' must belong to '${call.section}' rows.`;
+            else if (!VALUE_TYPES.has(fieldInfo.field.type))
+              message = `Collection target type ${fieldInfo.field.type} is unsupported.`;
+            else if (
+              call.name === 'REPEATABLESUM' &&
+              !['NumericField', 'CalculatedField'].includes(fieldInfo.field.type)
+            )
+              message = 'REPEATABLESUM requires a NumericField or CalculatedField target.';
+            else if (
+              !ContextResolver.isPrefix(ownerPath, info.parentPath) &&
+              !ContextResolver.isPrefix(info.parentPath, ownerPath)
+            )
+              message = `Collection source '${call.section}' is outside the calculation's record ancestry.`;
+            if (message)
+              issues.push({
+                code: 'invalid_collection_reference',
+                message,
+                index: parent.start,
+                length: parent.end - parent.start,
+              });
+          }
+        }
+      }
+    }
+    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 expression = source;
+  let scalarSource = source;
+  for (const edit of edits.sort((a, b) => b.start - a.start)) {
+    expression = expression.slice(0, edit.start) + edit.value + expression.slice(edit.end);
+    scalarSource =
+      scalarSource.slice(0, edit.start) +
+      ' '.repeat(edit.end - edit.start) +
+      scalarSource.slice(edit.end);
+  }
+  return { calls, issues, expression, scalarSource };
+}
+
+export function projectCollectionValue(field, value) {
+  if (value == null) return ['MultiChoiceField', 'FormLinkField'].includes(field.type) ? [] : null;
+  const fail = () => {
+    throw new Error(`Malformed collection value for '${field.data_name}'.`);
+  };
+  if (['SingleChoiceField', 'MultiChoiceField', 'BooleanField'].includes(field.type)) {
+    if (typeof value !== 'object' || Array.isArray(value)) return fail();
+    const multiple = field.type === 'MultiChoiceField';
+    const selections = value[multiple ? 'choices' : 'choice'];
+    const others = value.other ?? (field.type === 'BooleanField' ? [] : undefined);
+    if (!Array.isArray(selections) || !Array.isArray(others)) return fail();
+    if ((field.type === 'BooleanField' || !field.allow_other) && others.length) return fail();
+    const allowed = new Set(field.choices.map((choice) => choice.value));
+    const projected = selections.map((entry) => {
+      if (!entry || !allowed.has(entry.value)) return fail();
+      return entry.value;
+    });
+    for (const entry of others) {
+      if (!entry || typeof entry.label !== 'string' || !entry.label.trim()) return fail();
+      projected.push(entry.label);
+    }
+    if (!multiple && projected.length > 1) return fail();
+    return multiple ? projected : (projected[0] ?? null);
+  }
+  if (field.type === 'FormLinkField') {
+    if (!Array.isArray(value) || (!field.allow_multiple_records && value.length > 1)) return fail();
+    return value.map((entry) => {
+      if (!entry || typeof entry.record_id !== 'string' || !entry.record_id.trim()) return fail();
+      return { record_id: entry.record_id };
+    });
+  }
+  return value;
+}

package/src/utilities/schema-revision.js

@@ -0,0 +1,30 @@
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (!value || typeof value !== 'object') return value;
+  return Object.fromEntries(
+    Object.keys(value)
+      .sort()
+      .map((key) => [key, stableValue(value[key])])
+  );
+}
+
+function fnv1a64(input) {
+  let hash = 0xcbf29ce484222325n;
+  for (let index = 0; index < input.length; index += 1) {
+    hash ^= BigInt(input.charCodeAt(index));
+    hash = BigInt.asUintN(64, hash * 0x100000001b3n);
+  }
+  return hash.toString(16).padStart(16, '0');
+}
+
+/** Return a deterministic schema revision without importing authoring/editor modules. */
+export function getFormSchemaRevision(schema) {
+  const root =
+    schema?.form && Array.isArray(schema.form.elements)
+      ? schema
+      : schema && Array.isArray(schema.elements)
+        ? { form: schema }
+        : null;
+  if (!root) throw new Error('Expected a root schema containing form.elements or a form schema');
+  return `form0-${fnv1a64(JSON.stringify(stableValue(root)))}`;
+}