@defra/forms-engine-plugin 0.0.1

package/.browserslistrc

@@ -0,0 +1,16 @@
+[javascripts]
+supports es6-module
+
+[stylesheets]
+> 0.1% in GB and not dead
+last 6 Chrome versions
+last 6 Firefox versions
+last 6 Edge versions
+last 2 Samsung versions
+Firefox ESR
+Safari >= 11
+iOS >= 11
+ie 11
+
+[node]
+node 22

package/.editorconfig

@@ -0,0 +1,9 @@
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 2
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true

package/.eslintrc.cjs

@@ -0,0 +1,266 @@
+/**
+ * ESLint config
+ * @type {import('eslint').ESLint.ConfigData}
+ */
+module.exports = {
+  ignorePatterns: ['.public', '.server', 'coverage'],
+  overrides: [
+    {
+      extends: [
+        'standard',
+        'eslint:recommended',
+        'plugin:import/recommended',
+        'plugin:import/typescript',
+        'plugin:jsdoc/recommended',
+        'plugin:n/recommended',
+        'plugin:promise/recommended',
+        'plugin:@typescript-eslint/strict-type-checked',
+        'plugin:@typescript-eslint/stylistic-type-checked',
+        'prettier'
+      ],
+      files: ['**/*.{cjs,js,mjs,ts}'],
+      parser: '@typescript-eslint/parser',
+      parserOptions: {
+        ecmaVersion: 'latest',
+        projectService: true,
+        tsconfigRootDir: __dirname
+      },
+      plugins: ['@typescript-eslint', 'import', 'jsdoc', 'n', 'promise'],
+      rules: {
+        'no-console': 'error',
+        'no-irregular-whitespace': [
+          'error',
+          {
+            skipTemplates: true
+          }
+        ],
+
+        // Check type imports are identified
+        '@typescript-eslint/consistent-type-imports': [
+          'error',
+          {
+            fixStyle: 'inline-type-imports'
+          }
+        ],
+
+        // Allow void return shorthand in arrow functions
+        '@typescript-eslint/no-confusing-void-expression': [
+          'error',
+          {
+            ignoreArrowShorthand: true
+          }
+        ],
+
+        // Only show warnings for missing types
+        '@typescript-eslint/no-unsafe-argument': 'warn',
+        '@typescript-eslint/no-unsafe-assignment': 'warn',
+        '@typescript-eslint/no-unsafe-call': 'warn',
+        '@typescript-eslint/no-unsafe-member-access': 'warn',
+        '@typescript-eslint/no-unsafe-return': 'warn',
+
+        // Check type support for template string implicit `.toString()`
+        '@typescript-eslint/restrict-template-expressions': [
+          'error',
+          {
+            allowBoolean: true,
+            allowNumber: true
+          }
+        ],
+
+        // Skip warnings for `this` in static methods
+        '@typescript-eslint/unbound-method': [
+          'warn',
+          {
+            ignoreStatic: true
+          }
+        ],
+
+        // Skip rules handled by TypeScript compiler
+        'import/default': 'off',
+        'import/extensions': 'off',
+        'import/named': 'off',
+        'import/namespace': 'off',
+        'import/no-named-as-default': 'off',
+        'import/no-named-as-default-member': 'off',
+        'import/no-unresolved': 'off',
+
+        // Check type imports are annotated inline
+        'import/consistent-type-specifier-style': ['error', 'prefer-inline'],
+
+        // Check import or require statements are A-Z ordered
+        'import/order': [
+          'error',
+          {
+            alphabetize: { order: 'asc' },
+            named: {
+              enabled: true,
+              types: 'types-last'
+            },
+            'newlines-between': 'always'
+          }
+        ],
+
+        // Check relative import paths use aliases
+        'no-restricted-imports': [
+          'error',
+          {
+            patterns: [
+              {
+                group: ['./', '../'],
+                message: "Please use '~/*' import alias instead."
+              }
+            ]
+          }
+        ],
+
+        // Check for valid formatting
+        'jsdoc/check-line-alignment': [
+          'warn',
+          'never',
+          {
+            tags: ['param', 'property', 'typedef', 'returns']
+          }
+        ],
+
+        // Require hyphens before param description
+        // Aligns with TSDoc style: https://tsdoc.org/pages/tags/param/
+        'jsdoc/require-hyphen-before-param-description': [
+          'warn',
+          'always',
+          {
+            tags: {
+              param: 'always',
+              property: 'always',
+              returns: 'never'
+            }
+          }
+        ],
+
+        // JSDoc blocks are optional but must be valid
+        'jsdoc/require-jsdoc': [
+          'error',
+          {
+            enableFixer: false,
+            require: {
+              FunctionDeclaration: false
+            }
+          }
+        ],
+
+        // JSDoc @param is optional
+        'jsdoc/require-param-description': 'off',
+        'jsdoc/require-param-type': 'off',
+        'jsdoc/require-param': 'off',
+
+        // JSDoc @returns is optional
+        'jsdoc/require-returns-description': 'off',
+        'jsdoc/require-returns-type': 'off',
+        'jsdoc/require-returns': 'off',
+
+        // Skip rules handled by TypeScript compiler
+        'n/no-extraneous-require': 'off',
+        'n/no-extraneous-import': 'off',
+        'n/no-missing-require': 'off',
+        'n/no-missing-import': 'off',
+
+        // Prefer rules that are type aware
+        'no-unused-vars': 'off',
+        'no-use-before-define': 'off',
+        '@typescript-eslint/no-unused-vars': [
+          'error',
+          { argsIgnorePattern: '^_' }
+        ],
+        '@typescript-eslint/no-use-before-define': ['error', 'nofunc']
+      },
+      settings: {
+        'import/parsers': {
+          '@typescript-eslint/parser': ['.cjs', '.js', '.mjs', '.ts']
+        },
+        'import/resolver': {
+          node: true,
+          typescript: true
+        }
+      }
+    },
+    {
+      extends: ['plugin:jsdoc/recommended-typescript-flavor'],
+      files: ['**/*.{cjs,js,mjs}'],
+      plugins: ['jsdoc'],
+      rules: {
+        // Promise.prototype.catch() errors cannot be typed in JavaScript
+        '@typescript-eslint/use-unknown-in-catch-callback-variable': 'off',
+
+        // JSDoc blocks are optional but must be valid
+        'jsdoc/require-jsdoc': [
+          'error',
+          {
+            enableFixer: false,
+            require: {
+              FunctionDeclaration: false
+            }
+          }
+        ],
+
+        // JSDoc @param types are mandatory for JavaScript
+        'jsdoc/require-param-description': 'off',
+        'jsdoc/require-param-type': 'error',
+        'jsdoc/require-param': 'off',
+
+        // JSDoc @returns is optional
+        'jsdoc/require-returns-description': 'off',
+        'jsdoc/require-returns-type': 'off',
+        'jsdoc/require-returns': 'off'
+      }
+    },
+    {
+      files: ['**/*.cjs'],
+      rules: {
+        '@typescript-eslint/no-var-requires': 'off'
+      }
+    },
+    {
+      files: ['**/*.{js,mjs}'],
+      parserOptions: {
+        sourceType: 'module'
+      }
+    },
+    {
+      env: {
+        browser: true,
+        node: false
+      },
+      files: ['src/client/**/*.js'],
+      rules: {
+        // Turn off warnings for unavailable types
+        // https://github.com/alphagov/govuk-frontend/issues/2835
+        '@typescript-eslint/no-unsafe-argument': 'off',
+        '@typescript-eslint/no-unsafe-assignment': 'off',
+        '@typescript-eslint/no-unsafe-call': 'off',
+        '@typescript-eslint/no-unsafe-member-access': 'off',
+        '@typescript-eslint/no-unsafe-return': 'off',
+
+        // Allow floating promises for lazy loading
+        '@typescript-eslint/no-floating-promises': 'off',
+        'promise/always-return': 'off'
+      }
+    },
+    {
+      env: {
+        'jest/globals': true
+      },
+      extends: ['plugin:jest/recommended', 'plugin:jest/style'],
+      files: ['**/*.test.{cjs,js,mjs,ts}'],
+      plugins: ['jest'],
+      rules: {
+        // Turn off warnings for jest.Expect 'any' types
+        '@typescript-eslint/no-unsafe-assignment': 'off',
+        '@typescript-eslint/no-unsafe-argument': 'off',
+
+        // Allow Jest to assert on mocked unbound methods
+        '@typescript-eslint/unbound-method': 'off',
+        'jest/unbound-method': 'error'
+      }
+    }
+  ],
+  root: true
+}

package/.github/dependabot.yml

@@ -0,0 +1,85 @@
+version: 2
+
+updates:
+  # Update npm packages
+  - package-ecosystem: npm
+    directory: /
+    open-pull-requests-limit: 10
+
+    # Group into shared PRs
+    groups:
+      build:
+        patterns:
+          - '*-loader'
+          - '*-webpack-plugin'
+          - '@babel/*'
+          - 'autoprefixer'
+          - 'babel-*'
+          - 'core-js'
+          - 'cssnano'
+          - 'cssnano-*'
+          - 'postcss'
+          - 'postcss-*'
+          - 'sass-embedded'
+          - 'tsc-alias'
+          - 'typescript'
+          - 'webpack'
+          - 'webpack-*'
+
+        # Exclude packages in other groups
+        exclude-patterns:
+          - 'postcss-scss'
+
+      lint:
+        patterns:
+          - '@typescript-eslint/*'
+          - 'editorconfig-checker'
+          - 'eslint'
+          - 'eslint-*'
+          - 'husky'
+          - 'lint-staged'
+          - 'postcss-scss'
+          - 'prettier'
+          - 'stylelint'
+          - 'stylelint-*'
+
+      logging:
+        patterns:
+          - '*-pino'
+          - '*-pino-format'
+          - 'pino'
+          - 'pino-*'
+
+      tools:
+        patterns:
+          - 'concurrently'
+          - 'global-jsdom'
+          - 'jest'
+          - 'jsdom'
+          - 'tsx'
+
+      types:
+        patterns:
+          - '@types/*'
+
+    # Schedule run every Monday, local time
+    schedule:
+      interval: weekly
+      time: '10:30'
+      timezone: 'Europe/London'
+
+    versioning-strategy: increase
+
+    allow:
+      # Include direct package.json updates
+      - dependency-type: direct
+
+  # Update GitHub Actions
+  - package-ecosystem: github-actions
+    directory: /
+
+    # Schedule run every Monday, local time
+    schedule:
+      interval: weekly
+      time: '10:30'
+      timezone: 'Europe/London'

package/.github/workflows/check-pull-request.yml

@@ -0,0 +1,209 @@
+name: Check Pull Request
+
+on:
+  pull_request:
+
+  push:
+    branches:
+      - main
+      - 'releases/**'
+
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-24.04
+
+    strategy:
+      fail-fast: false
+
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        id: npm-install-cache
+        with:
+          enableCrossOsArchive: true
+          key: npm-install-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
+          path: node_modules
+
+      - name: Cache build
+        uses: actions/cache@v4
+        with:
+          enableCrossOsArchive: true
+          key: npm-build-${{ runner.os }}-${{ github.sha }}
+          path: |
+            .public
+            .server
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+
+      - name: Install dependencies
+        if: steps.npm-install-cache.outputs.cache-hit != 'true'
+        run: npm ci
+
+      - name: Run build
+        run: npm run build
+
+  lint:
+    name: ${{ matrix.task.description }}
+    runs-on: ubuntu-24.04
+    needs: [build]
+
+    env:
+      # Authorise GitHub API requests for EditorConfig checker binary
+      # https://www.npmjs.com/package/editorconfig-checker
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+    strategy:
+      fail-fast: false
+
+      matrix:
+        task:
+          - description: Prettier
+            name: lint-prettier
+            run: npm run format:check
+            cache: .cache/prettier
+
+          - description: EditorConfig
+            name: lint-editorconfig
+            run: npm run lint:editorconfig
+
+          - description: ESLint
+            name: lint-js
+            run: npm run lint:js
+            cache: .cache/eslint
+
+          - description: Stylelint
+            run: npm run lint:scss
+            cache: .cache/stylelint
+
+          - description: TypeScript compiler
+            name: lint-types
+            run: npm run lint:types -- --incremental --pretty
+            cache: '**/*.tsbuildinfo'
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Restore dependencies
+        uses: actions/cache/restore@v4
+        with:
+          enableCrossOsArchive: true
+          fail-on-cache-miss: true
+          key: npm-install-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
+          path: node_modules
+
+      - name: Cache task
+        if: ${{ matrix.task.cache }}
+        uses: actions/cache@v4
+        with:
+          enableCrossOsArchive: true
+          key: ${{ matrix.task.name }}-${{ runner.os }}
+          path: ${{ matrix.task.cache }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+
+      - name: Run lint task
+        run: ${{ matrix.task.run }}
+
+  tasks:
+    name: ${{ matrix.task.description }}
+    runs-on: ubuntu-24.04
+    needs: [build]
+
+    strategy:
+      fail-fast: false
+
+      matrix:
+        task:
+          - description: Unit tests
+            name: test-unit
+            run: npm run test
+            cache: coverage
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Restore dependencies
+        uses: actions/cache/restore@v4
+        with:
+          enableCrossOsArchive: true
+          fail-on-cache-miss: true
+          key: npm-install-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
+          path: node_modules
+
+      - name: Restore build
+        uses: actions/cache/restore@v4
+        with:
+          enableCrossOsArchive: true
+          fail-on-cache-miss: true
+          key: npm-build-${{ runner.os }}-${{ github.sha }}
+          path: |
+            .public
+            .server
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+
+      - name: Cache task
+        if: ${{ matrix.task.cache }}
+        uses: actions/cache@v4
+        with:
+          enableCrossOsArchive: true
+          key: ${{ matrix.task.name }}-${{ runner.os }}-${{ github.sha }}
+          path: ${{ matrix.task.cache }}
+
+      - name: Run task
+        run: ${{ matrix.task.run }}
+
+      - name: Save test coverage
+        if: ${{ always() }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.task.description }} coverage
+          path: coverage
+          if-no-files-found: ignore
+
+  analysis:
+    name: Analysis
+    if: ${{ always() }}
+    runs-on: ubuntu-24.04
+    needs: [build, tasks]
+
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Restore unit test coverage
+        uses: actions/cache/restore@v4
+        with:
+          enableCrossOsArchive: true
+          fail-on-cache-miss: true
+          key: test-unit-${{ runner.os }}-${{ github.sha }}
+          path: coverage
+
+      - name: SonarCloud Scan
+        uses: SonarSource/sonarqube-scan-action@v4.2.1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

package/.github/workflows/pr-notifier.yml

@@ -0,0 +1,98 @@
+name: Post PR to Slack
+
+on:
+  pull_request:
+    types:
+      - opened
+      - converted_to_draft
+      - ready_for_review
+      - reopened
+      - closed
+
+  pull_request_review:
+    types:
+      - submitted
+
+env:
+  CONFIG: |
+    {
+      "opened": {
+        "icon": "${{ github.event.pull_request.draft && '📝' || '🆕' }}",
+        "status": "${{ github.event.pull_request.draft && 'opened as draft' || 'opened' }}"
+      },
+      "converted_to_draft": {
+        "icon": "📝",
+        "status": "converted to draft"
+      },
+      "ready_for_review": {
+        "icon": "👀",
+        "status": "ready for review"
+      },
+      "reopened": {
+        "icon": "🔄",
+        "status": "reopened"
+      },
+      "submitted": {
+        "icon": "${{ github.event.review.state == 'approved' && '✅' || '💬' }}",
+        "status": "${{ github.event.review.state == 'approved' && 'code review approved' || 'code review comments' }}"
+      },
+      "closed": {
+        "icon": "${{ github.event.pull_request.merged && '🚀' || '🗑️' }}",
+        "status": "${{ github.event.pull_request.merged && 'merged' || 'closed' }}"
+      }
+    }
+
+jobs:
+  notify:
+    name: Slack notify
+    runs-on: ubuntu-24.04
+    if: ${{ !contains(github.event.pull_request.head.ref || github.head_ref || github.ref, 'dependabot/') }}
+
+    steps:
+      - name: Build Slack JSON
+        uses: actions/github-script@v7
+        id: payload
+        if: github.event.action != 'submitted' || github.event.review.state == 'approved'
+
+        env:
+          ACTION_ICON: ${{ fromJSON(env.CONFIG)[github.event.action].icon }}
+          ACTION_STATUS: ${{ fromJSON(env.CONFIG)[github.event.action].status }}
+
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const title = ${{ toJson(github.event.pull_request.title) }}
+            const username = ${{ toJson(github.event.pull_request.user.login) }}
+            const profileUrl = ${{ toJson(github.event.pull_request.user.html_url) }}
+
+            const { pull_request } = context.payload
+            const { owner, repo } = context.repo
+
+            // Format as Slack mrkdwn
+            const titleFormatted = `<${pull_request.html_url}|*${title}* #${pull_request.number}>`
+            const profileFormatted = `<${profileUrl}|@${username}>`
+
+            // Payload output is JSON encoded
+            return {
+              channel: '${{ vars.SLACK_CHANNEL_ID }}',
+              blocks: [
+                {
+                  type: 'section',
+                  text: {
+                    type: 'mrkdwn',
+                    text: `${owner}/*${repo}*: ${titleFormatted} by ${profileFormatted} ${{ env.ACTION_ICON }} ${{ env.ACTION_STATUS }}`
+                  }
+                }
+              ],
+              unfurl_links: false,
+              unfurl_media: false
+            }
+
+      - name: Post to Slack
+        uses: slackapi/slack-github-action@v2.0.0
+        if: github.event.action != 'submitted' || github.event.review.state == 'approved'
+
+        with:
+          method: chat.postMessage
+          token: ${{ secrets.SLACK_BOT_TOKEN }}
+          payload: ${{ steps.payload.outputs.result }}