feat/DF-717: Shows reference number on confirmation page if enabled

package.json

@@ -70,7 +70,7 @@
   },
   "license": "SEE LICENSE IN LICENSE",
   "dependencies": {
-    "@defra/forms-model": "^3.0.597",
+    "@defra/forms-model": "^3.0.603",
     "@defra/hapi-tracing": "^1.29.0",
     "@elastic/ecs-pino-format": "^1.5.0",
     "@hapi/boom": "^10.0.1",
@@ -108,6 +108,7 @@
     "lodash": "^4.17.21",
     "marked": "^15.0.12",
     "nunjucks": "^3.2.4",
+    "obscenity": "^0.4.5",
     "outdent": "^0.8.0",
     "pino": "^9.14.0",
     "pino-pretty": "^13.1.2",

src/server/plugins/engine/pageControllers/StatusPageController.ts

@@ -12,10 +12,12 @@ import {
 export class StatusPageController extends QuestionPageController {
   declare pageDef: PageStatus
   allowSaveAndExit = false
+  showReferenceNumber = false
 
   constructor(model: FormModel, pageDef: PageStatus) {
     super(model, pageDef)
     this.viewName = 'confirmation'
+    this.showReferenceNumber = model.def.options?.showReferenceNumber ?? false
   }
 
   getRelevantPath() {
@@ -54,7 +56,9 @@ export class StatusPageController extends QuestionPageController {
       return h.view(viewName, {
         ...viewModel,
         submissionGuidance,
-        formName
+        formName,
+        showReferenceNumber: this.showReferenceNumber,
+        referenceNumber: context.referenceNumber
       })
     }
   }

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

@@ -1,4 +1,7 @@
-import { generateUniqueReference } from '~/src/server/plugins/engine/referenceNumbers.js'
+import {
+  convertToDecAlpha,
+  generateUniqueReference
+} from '~/src/server/plugins/engine/referenceNumbers.js'
 
 describe('generateUniqueReference', () => {
   it('should generate a reference number with 3 segments when no prefix is provided', () => {
@@ -30,4 +33,42 @@ describe('generateUniqueReference', () => {
     const referenceNumber2 = generateUniqueReference()
     expect(referenceNumber1).not.toBe(referenceNumber2)
   })
+
+  describe('convertToDecAlpha', () => {
+    it('should generate correct characters in string', () => {
+      const allValuesHexPairs = Array.from(Array(256).keys())
+      expect(convertToDecAlpha(allValuesHexPairs)).toBe(
+        'AAAAAAAAA' +
+          'BBBBBBBBB' +
+          'CCCCCCCC' +
+          'DDDDDDDDD' +
+          'EEEEEEEE' +
+          'FFFFFFFFF' +
+          'HHHHHHHH' +
+          'JJJJJJJJJ' +
+          'KKKKKKKK' +
+          'LLLLLLLLL' +
+          'MMMMMMMM' +
+          'NNNNNNNNN' +
+          'PPPPPPPP' +
+          'RRRRRRRRR' +
+          'SSSSSSSS' +
+          'TTTTTTTTT' +
+          'UUUUUUUUU' +
+          'VVVVVVVV' +
+          'WWWWWWWWW' +
+          'XXXXXXXX' +
+          'YYYYYYYYY' +
+          'ZZZZZZZZ' +
+          '222222222' +
+          '33333333' +
+          '444444444' +
+          '55555555' +
+          '666666666' +
+          '77777777' +
+          '888888888' +
+          '99999999'
+      )
+    })
+  })
 })

src/server/plugins/engine/referenceNumbers.ts

@@ -1,18 +1,56 @@
 import { randomBytes } from 'node:crypto'
 
+import {
+  RegExpMatcher,
+  englishDataset,
+  englishRecommendedTransformers
+} from 'obscenity'
+
+/**
+ * To prevent confusion to users reading the reference number, ambiguous letters and numbers are removed.
+ * @param strCodes - array of binary input values
+ */
+export function convertToDecAlpha(strCodes: number[]) {
+  const validChars = 'ABCDEFHJKLMNPRSTUVWXYZ23456789'
+  const strLen = validChars.length
+  const outArray = [] as string[]
+
+  strCodes.forEach((code) => {
+    const pos = (code / 256) * strLen
+    outArray.push(validChars.charAt(pos))
+  })
+
+  return outArray.join('')
+}
+
 /**
  * Generates a reference number in the format of `XXX-XXX-XXX`, or `PREFIX-XXX-XXX` if a prefix is provided.
  * Provides no guarantee on uniqueness.
+ * To prevent confusion to users reading the reference number, ambiguous letters and numbers are removed
+ * (see https://gunkies.org/wiki/DEC_alphabet )
  */
 export function generateUniqueReference(prefix?: string) {
   const segmentLength = 3
   const segmentCount = prefix ? 2 : 3
   prefix = prefix ? `${prefix}-` : ''
 
-  const segments = Array.from(
-    { length: segmentCount },
-    () => randomBytes(segmentLength).toString('hex').slice(0, segmentLength) // 0-9a-f, might be good enough?
-  )
+  const profanityMatcher = new RegExpMatcher({
+    ...englishDataset.build(),
+    ...englishRecommendedTransformers
+  })
+
+  let referenceNumber
+
+  do {
+    const segments = Array.from({ length: segmentCount }, () =>
+      convertToDecAlpha([...randomBytes(segmentLength)]).slice(
+        0,
+        segmentLength * 2
+      )
+    )
+
+    referenceNumber = `${prefix}${segments.join('-')}`.toUpperCase()
+  } while (profanityMatcher.hasMatch(referenceNumber.replaceAll('-', '')))
 
-  return `${prefix}${segments.join('-')}`.toUpperCase()
+  return referenceNumber
 }

src/server/plugins/engine/views/confirmation.html

@@ -8,7 +8,8 @@
   <div class="govuk-grid-row">
     <div class="govuk-grid-column-two-thirds">
       {{ govukPanel({
-        titleText: pageTitle
+        titleText: pageTitle,
+        html: "Your reference number<br><strong>" + referenceNumber + "</strong>" if showReferenceNumber
       }) }}
       <h2 class="govuk-heading-m">What happens next</h2>
       <div class="app-prose-scope">