@defra/forms-engine-plugin 5.0.0-alpha.20 → 5.0.0-alpha.22

package/src/server/plugins/engine/models/FormModel.ts

@@ -1,5 +1,6 @@
 import {
   ComponentType,
+  ConditionEvaluationOutcome,
   ConditionsModel,
   ControllerPath,
   ControllerType,
@@ -8,6 +9,7 @@ import {
   formDefinitionSchema,
   formDefinitionV2Schema,
   generateConditionAlias,
+  getErrorMessage,
   hasComponents,
   hasComponentsEvenIfNoNext,
   hasRepeater,
@@ -54,7 +56,10 @@ import { extractBaseTranslations } from '../i18n/extractBaseTranslations.js'
 import { createFormI18nInstance } from '../i18n/index.js'
 import { getAvailableLanguages } from '../i18n/languages.js'
 import { type Translator } from '../i18n/types.js'
-import { type ExecutableCondition } from './types.js'
+import {
+  type ConditionEvaluation,
+  type ExecutableCondition
+} from './types.js'
 import { type PageController } from '../pageControllers/PageController.js'
 import {
   createPage,
@@ -304,21 +309,35 @@ export class FormModel {
       throw new ConditionBuildError(displayName, { cause })
     }
 
-    const fn = (evaluationState: FormState) => {
+    const evaluate = (evaluationState: FormState): ConditionEvaluation => {
       const ctx = this.toConditionContext(evaluationState, this.conditions)
+
       try {
-        return expr.evaluate(ctx) as boolean
-      } catch {
-        return false
+        return {
+          outcome: (expr.evaluate(ctx) as boolean)
+            ? ConditionEvaluationOutcome.True
+            : ConditionEvaluationOutcome.False
+        }
+      } catch (err) {
+        return {
+          outcome: ConditionEvaluationOutcome.Error,
+          error: getErrorMessage(err)
+        }
       }
     }
 
+    // A failed evaluation continues to route as `false`. `evaluate` exists so
+    // that the two can be told apart when recording outcomes for submission.
+    const fn = (evaluationState: FormState) =>
+      evaluate(evaluationState).outcome === ConditionEvaluationOutcome.True
+
     return {
       name,
       displayName,
       value,
       expr,
-      fn
+      fn,
+      evaluate
     }
   }
 

package/src/server/plugins/engine/models/types.ts

@@ -1,4 +1,5 @@
 import {
+  type ConditionEvaluationOutcome,
   type ConditionWrapper,
   type FormComponentsDef,
   type Section
@@ -16,9 +17,39 @@ import {
   type FormSubmissionError
 } from '../types.js'
 
+/**
+ * The result of evaluating a condition, keeping a failed evaluation distinct
+ * from one that legitimately returned `false`.
+ * @see {@link ExecutableCondition.evaluate}
+ */
+export interface ConditionEvaluation {
+  outcome: ConditionEvaluationOutcome
+  error?: string
+}
+
+/**
+ * A form condition paired with the parsed expression and callbacks needed to
+ * run it against a form submission state
+ * Created by `FormModel.makeCondition`
+ */
 export type ExecutableCondition = ConditionWrapper & {
+  /**
+   * Parsed expression for the condition's {@link ConditionWrapper.value},
+   * evaluated against a context built from the submission state
+   */
   expr: Expression
+
+  /**
+   * Evaluates the condition, used for page routing and component visibility
+   * A failed evaluation is reported as `false`
+   */
   fn: (evaluationState: FormState) => boolean
+
+  /**
+   * As `fn`, but reports whether evaluation failed rather than defaulting a
+   * failure to `false`. Used to record condition outcomes on submission.
+   */
+  evaluate: (evaluationState: FormState) => ConditionEvaluation
 }
 
 /**

package/src/server/plugins/engine/options.js

@@ -26,7 +26,8 @@ const pluginRegistrationOptionsSchema = Joi.object({
   saveAndExit: Joi.function().optional(),
   ordnanceSurveyApiKey: Joi.string().optional(),
   ordnanceSurveyApiSecret: Joi.string().optional(),
-  getLanguage: Joi.function().optional()
+  getLanguage: Joi.function().optional(),
+  generateReferenceNumber: Joi.function().optional()
 })
 
 /**

package/src/server/plugins/engine/outputFormatters/adapter/v1.ts

@@ -1,4 +1,5 @@
 import {
+  Engine,
   type FormMetadata,
   type SubmitResponsePayload
 } from '@defra/forms-model'
@@ -11,6 +12,7 @@ import {
 import { type FormModel } from '../../models/FormModel.js'
 import { type DetailItem } from '../../models/types.js'
 import { categoriseData } from '../machine/v2.js'
+import { buildConditionEvaluations } from '../../pageControllers/helpers/submission.js'
 import { FormAdapterSubmissionSchemaVersion } from '../../types/enums.js'
 import {
   type FormAdapterSubmissionMessageData,
@@ -73,7 +75,19 @@ export function format(
   const payload: FormAdapterSubmissionMessagePayload = {
     meta,
     data,
-    result
+    result,
+
+    // Recorded here because only the engine holds the walked evaluation state
+    // the conditions were judged against; forms-notify-listener receives the
+    // flat submitted answers and resolves the outputs that qualify from these
+    // outcomes alone. Condition ids are only stable in V2, so a V1 definition
+    // has nothing to report - the property is still emitted, because its
+    // absence is what marks a message as predating this and sends the listener
+    // down its legacy path.
+    conditionEvaluations:
+      model.engine === Engine.V2
+        ? buildConditionEvaluations(model, context)
+        : []
   }
 
   return JSON.stringify(payload)

package/src/server/plugins/engine/pageControllers/helpers/submission.ts

@@ -1,13 +1,27 @@
-import { type SubmitPayload } from '@defra/forms-model'
+import {
+  isConditionWrapperV2,
+  type ConditionDataV2,
+  type ConditionRefDataV2,
+  type ConditionWrapperV2,
+  type SubmitConditionEvaluation,
+  type SubmitConditionReference,
+  type SubmitPayload
+} from '@defra/forms-model'
 
 import { GeospatialField } from '../../components/GeospatialField.js'
 import { PaymentField } from '../../components/PaymentField.js'
 import { getAnswer } from '../../components/helpers/components.js'
 import { type Translator } from '../../i18n/types.js'
+import { type FormModel } from '../../models/FormModel.js'
 import {
   type DetailItem,
   type DetailItemField
 } from '../../models/types.js'
+import {
+  type FormContext,
+  type FormState,
+  type FormStateValue
+} from '../../types.js'
 import {
   formatCurrency,
   formatPaymentDate
@@ -141,3 +155,125 @@ export function buildRepeaterRecords(
       )
     }))
 }
+
+/**
+ * Records the outcome of every condition in the form definition, evaluated
+ * against the answers as they stand at the point of submission.
+ *
+ * Evaluated here rather than by the consumer because only the engine holds
+ * the context to evaluate against: `evaluationState` is built by walking the
+ * form from its start page along the path taken, applying page conditions as
+ * it goes. A consumer receives the flat submitted answers, not that walked
+ * state, and reproducing the walk in a second codebase would leave two
+ * implementations of the same logic free to diverge.
+ *
+ * Each record carries the components the condition depends on and whether each
+ * was answered. An unanswered question still yields a boolean - negative
+ * operators such as "is not" return `true` against the seeded `null` - so the
+ * outcome alone cannot be read as evidence that the user gave that answer.
+ *
+ * V2 definitions only. `conditionId` is the V2 condition id, and the
+ * references are resolved from the component ids V2 conditions carry - V1
+ * conditions reference components by name, and V1 components need not have
+ * an id at all.
+ */
+export function buildConditionEvaluations(
+  model: FormModel,
+  context: FormContext
+): SubmitConditionEvaluation[] {
+  const { evaluationState } = context
+
+  return model.def.conditions
+    .filter(isConditionWrapperV2)
+    .flatMap((conditionDef) => {
+      const condition = model.conditions[conditionDef.id]
+
+      if (!condition) {
+        return []
+      }
+
+      const { outcome } = condition.evaluate(evaluationState)
+
+      const references = collectReferences(model, conditionDef, evaluationState)
+
+      return {
+        conditionId: conditionDef.id,
+        outcome,
+        references: [...references.values()]
+      }
+    })
+}
+
+/**
+ * Whether a component held an answer at the point a condition was evaluated.
+ *
+ * The engine seeds every component in `evaluationState` with `null` before the
+ * page walk begins, so an unanswered question is present but empty rather than
+ * absent.
+ * @see {@link FormModel.initialiseContext}
+ */
+export function isAnswered(value: FormStateValue | undefined) {
+  if (value === undefined || value === null) {
+    return false
+  }
+
+  if (Array.isArray(value)) {
+    return value.length > 0
+  }
+
+  return value !== ''
+}
+
+function isConditionDataV2(
+  item: ConditionDataV2 | ConditionRefDataV2
+): item is ConditionDataV2 {
+  return 'componentId' in item
+}
+
+/**
+ * Recursive function that collects every component a condition depends on, following nested condition
+ * references. Results are keyed by component id so a component referenced more
+ * than once is reported once.
+ */
+function collectReferences(
+  model: FormModel,
+  conditionDef: ConditionWrapperV2,
+  evaluationState: FormState,
+  references: Map<string, SubmitConditionReference> = new Map<
+    string,
+    SubmitConditionReference
+  >(),
+  visited: Set<string> = new Set<string>()
+) {
+  if (visited.has(conditionDef.id)) {
+    return references
+  }
+
+  visited.add(conditionDef.id)
+
+  for (const item of conditionDef.items) {
+    if (isConditionDataV2(item)) {
+      const component = model.getComponentById(item.componentId)
+
+      // A condition referencing a component that no longer exists cannot be
+      // resolved to a name, so there is nothing meaningful to report for it
+      if (component) {
+        references.set(item.componentId, {
+          componentId: item.componentId,
+          componentName: component.name,
+          answered: isAnswered(evaluationState[component.name])
+        })
+      }
+
+      continue
+    }
+
+    const referenced = model.getConditionById(item.conditionId)
+
+    if (referenced) {
+      collectReferences(model, referenced, evaluationState, references, visited)
+    }
+  }
+
+  return references
+}

package/src/server/plugins/engine/plugin.ts

@@ -8,6 +8,7 @@ import {
 
 import { type FormModel } from './models/index.js'
 import { validatePluginOptions } from './options.js'
+import { generateUniqueReference } from './referenceNumbers.js'
 import { getRoutes as getFileUploadStatusRoutes } from './routes/file-upload.js'
 import { makeLoadFormPreHandler } from './routes/index.js'
 import { getRoutes as getPaymentRoutes } from './routes/payment.js'
@@ -37,6 +38,7 @@ export const plugin = {
       cache,
       saveAndExit,
       getLanguage,
+      generateReferenceNumber,
       nunjucks: nunjucksOptions,
       viewContext,
       preparePageEventRequestOptions,
@@ -80,6 +82,10 @@ export const plugin = {
     server.expose('cacheService', cacheService)
     server.expose('saveAndExit', saveAndExit)
     server.expose('getLanguage', getLanguage)
+    server.expose(
+      'generateReferenceNumber',
+      generateReferenceNumber ?? generateUniqueReference
+    )
     server.expose('baseUrl', baseUrl)
     server.expose('services', services)
 

package/src/server/plugins/engine/referenceNumbers.ts

@@ -6,6 +6,8 @@ import {
   englishRecommendedTransformers
 } from 'obscenity'
 
+export const DEFAULT_REFERENCE_NUMBER = 'XXX-XXX-XXX'
+
 /**
  * To prevent confusion to users reading the reference number, ambiguous letters and numbers are removed.
  * @param strCodes - array of binary input values

package/src/server/plugins/engine/routes/index.ts

@@ -20,6 +20,7 @@ import {
   findPage,
   getCacheService,
   getPage,
+  getPluginOptions,
   getStartPath,
   proceed
 } from '../helpers.js'
@@ -28,7 +29,7 @@ import {
   checkSaveAndExitRepeater,
   copyNotYetValidatedState
 } from '../pageControllers/helpers/state.js'
-import { generateUniqueReference } from '../referenceNumbers.js'
+import { DEFAULT_REFERENCE_NUMBER } from '../referenceNumbers.js'
 import * as defaultServices from '../services/index.js'
 import {
   type AnyFormRequest,
@@ -54,7 +55,7 @@ export async function redirectOrMakeHandler(
     context: FormContext
   ) => ResponseObject | Promise<ResponseObject>
 ) {
-  const { app, params } = request
+  const { app, params, query } = request
   const { model } = app
 
   if (!model) {
@@ -74,7 +75,12 @@ export async function redirectOrMakeHandler(
       )
     }
 
-    const referenceNumber = generateUniqueReference(prefix)
+    const isForce = 'force' in query
+    const { generateReferenceNumber } = getPluginOptions(request.server)
+    const referenceNumber = isForce
+      ? DEFAULT_REFERENCE_NUMBER
+      : await generateReferenceNumber(prefix)
+
     state = await page.mergeState(request, state, {
       $$__referenceNumber: referenceNumber
     })

package/src/server/plugins/engine/types/enums.ts

@@ -10,6 +10,7 @@ export enum FileStatus {
   pending = 'pending'
 }
 
-export enum FormAdapterSubmissionSchemaVersion {
-  V1 = 1
-}
+// Changed from an enum to enforce numeric values
+export const FormAdapterSubmissionSchemaVersion = {
+  V1: 1
+} as const satisfies Record<string, number>

package/src/server/plugins/engine/types/schema.ts

@@ -1,5 +1,6 @@
 import {
   FormStatus,
+  formSubmitConditionEvaluationSchema,
   formVersionMetadataSchema,
   idSchema,
   notificationEmailAddressSchema,
@@ -18,9 +19,9 @@ import {
 
 export const formAdapterSubmissionMessageMetaSchema =
   Joi.object<FormAdapterSubmissionMessageMeta>().keys({
-    schemaVersion: Joi.string().valid(
-      ...Object.values(FormAdapterSubmissionSchemaVersion)
-    ),
+    schemaVersion: Joi.number()
+      .valid(...Object.values(FormAdapterSubmissionSchemaVersion))
+      .required(),
     timestamp: Joi.date().required(),
     referenceNumber: Joi.string().required(),
     formName: titleSchema,
@@ -80,5 +81,16 @@ export const formAdapterSubmissionMessagePayloadSchema =
   Joi.object<FormAdapterSubmissionMessagePayload>().keys({
     meta: formAdapterSubmissionMessageMetaSchema.required(),
     data: formAdapterSubmissionMessageDataSchema.required(),
-    result: formAdapterSubmissionMessageResultSchema.required()
+    result: formAdapterSubmissionMessageResultSchema.required(),
+    // Optional so that messages published before this existed - which may
+    // still be in flight or sitting on a dead-letter queue - continue to
+    // validate. Consumers treat its absence as "resolve the recipients from
+    // the form definition yourself"
+    // This should be required at a later point in time.
+    conditionEvaluations: Joi.array()
+      .items(formSubmitConditionEvaluationSchema)
+      .optional()
+      .description(
+        'Outcome of every condition in the form definition, evaluated against the final answers at submission'
+      )
   })

package/src/server/plugins/engine/types.ts

@@ -6,6 +6,7 @@ import {
   type List,
   type Page,
   type PaymentFieldComponent,
+  type SubmitConditionEvaluation,
   type UkAddressFieldComponent
 } from '@defra/forms-model'
 import {
@@ -483,6 +484,10 @@ export type SaveAndExitHandler = (
 
 export type GetLanguageHandler = (query?: RequestQuery, yar?: Yar) => string
 
+export type GenerateReferenceNumberHandler = (
+  prefix?: string
+) => Promise<string>
+
 export interface ExternalArgs {
   component: ComponentDef
   controller: QuestionPageController
@@ -523,13 +528,14 @@ export interface PluginOptions {
   preparePageEventRequestOptions?: PreparePageEventRequestOptions
   onRequest?: OnRequestCallback
   getLanguage?: GetLanguageHandler
+  generateReferenceNumber?: GenerateReferenceNumberHandler
   baseUrl: string // base URL of the application, protocol and hostname e.g. "https://myapp.com"
   ordnanceSurveyApiKey?: string
   ordnanceSurveyApiSecret?: string
 }
 
 export interface FormAdapterSubmissionMessageMeta {
-  schemaVersion: FormAdapterSubmissionSchemaVersion
+  schemaVersion: (typeof FormAdapterSubmissionSchemaVersion)[keyof typeof FormAdapterSubmissionSchemaVersion]
   timestamp: Date
   referenceNumber: string
   formName: string
@@ -607,6 +613,18 @@ export interface FormAdapterSubmissionMessagePayload {
   meta: FormAdapterSubmissionMessageMeta
   data: FormAdapterSubmissionMessageData
   result: FormAdapterSubmissionMessageResult
+
+  /**
+   * The outcome of every condition in the form definition, evaluated against
+   * the final answers at the point of submission.
+   *
+   * Always emitted, empty when there is nothing to report - a V1-engine form
+   * has no stable condition ids to record against. Optional only for
+   * backwards compatibility: a message published before this existed carries
+   * no evaluations at all, and consumers fall back to resolving the recipients
+   * from the form definition themselves.
+   */
+  conditionEvaluations?: SubmitConditionEvaluation[]
 }
 
 export interface FormAdapterSubmissionMessage extends FormAdapterSubmissionMessagePayload {

package/src/typings/hapi/index.d.ts

@@ -11,6 +11,7 @@ import { type FormModel } from '../../server/plugins/engine/models/index.js'
 import {
   type AnyFormRequest,
   type FormSubmissionError,
+  type GenerateReferenceNumberHandler,
   type PluginOptions
 } from '../../server/plugins/engine/types.ts'
 import { type CacheService } from '../../server/services/index.js'
@@ -41,6 +42,7 @@ declare module '@hapi/hapi' {
       getLanguage?: PluginOptions['getLanguage']
       baseUrl: string
       services: PluginOptions['services']
+      generateReferenceNumber: GenerateReferenceNumberHandler
     }
   }