From 225c1adf60f2afa2239240bd4aec06b8b2a9e932 Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Thu, 21 Nov 2024 12:43:22 +0000
Subject: [PATCH] Add deprecated JavaScript files to package build

Because they're not imported by `all.mjs` deprecated JavaScript files were not included in the package (in which they need to remain until the next breaking release).

This adds a module to store the list of deprecated JavaScript files and helper functions that are then used:
- in the Gulp configuration, to add a new task building each deprecated file individually
- in the Rollup configuration, to prevent the bundled output of the deprecated files as all we want is for them to be in the package as a module

Co-authored-by: Patrick Cartlidge <patrick.cartlidge@digital.cabinet-office.gov.uk>
Co-authored-by: Brett Kyle <brett.kyle@digital.cabinet-office.gov.uk>
---
 docs/contributing/managing-change.md          | 25 +++++++++++
 .../govuk-frontend/rollup.publish.config.mjs  | 30 ++++++++-----
 .../src/govuk/govuk-frontend-component.mjs    |  5 +++
 .../tasks/config/deprecated-scripts.mjs       | 45 +++++++++++++++++++
 packages/govuk-frontend/tasks/scripts.mjs     | 19 ++++++++
 5 files changed, 112 insertions(+), 12 deletions(-)
 create mode 100644 packages/govuk-frontend/tasks/config/deprecated-scripts.mjs

diff --git a/docs/contributing/managing-change.md b/docs/contributing/managing-change.md
index da640ffb08..7c6eb31c2b 100644
--- a/docs/contributing/managing-change.md
+++ b/docs/contributing/managing-change.md
@@ -122,6 +122,31 @@ If possible, update the mixin or function to maintain the existing functionality
 }
 ```
 
+### Deprecating a JavaScript file being removed
+
+Removing a JavaScript file may happen because the module is no longer needed, or has been moved to another place in the project.
+
+Awaiting for the next breaking, the file needs to remain included in the built package, marked as deprecated.
+
+1. To ensure the file remains in the package, add its path within `src/govuk` to the list of paths in `packages/tasks/config/deprecated-scripts.mjs`. For example:
+
+```mjs
+export const deprecatedFilesPaths = [
+  'govuk-frontend-component.mjs'
+]
+```
+
+This will build the file individually when creating the package, as it is no longer being discovered automatically by Rollup when building `all.mjs`.
+
+2. To mark the file as deprecated, add the following JSDoc comment at the top of the file:
+
+```js
+/**
+ * @deprecated - Optionally describe where the file has been moved to or why it's been removed
+ * @module
+ */
+```
+
 ## Renaming things
 
 When renaming things, keep the old name available as an alias and mark it as deprecated, following the steps above to [make sure we remember to remove the deprecated feature](#make-sure-we-remember-to-remove-the-deprecated-feature).
diff --git a/packages/govuk-frontend/rollup.publish.config.mjs b/packages/govuk-frontend/rollup.publish.config.mjs
index 1e7be8ddf4..5b706f51ca 100644
--- a/packages/govuk-frontend/rollup.publish.config.mjs
+++ b/packages/govuk-frontend/rollup.publish.config.mjs
@@ -3,6 +3,8 @@ import { babel } from '@rollup/plugin-babel'
 import replace from '@rollup/plugin-replace'
 import { defineConfig } from 'rollup'
 
+import { isDeprecated } from './tasks/config/deprecated-scripts.mjs'
+
 /**
  * Rollup config for npm publish
  */
@@ -28,26 +30,30 @@ export default defineConfig(({ i: input }) => ({
      * ECMAScript (ES) module bundles for browser <script type="module">
      * or using `import` for modern browsers and Node.js scripts
      */
-    {
-      format: 'es',
+    isDeprecated(input)
+      ? null
+      : {
+          format: 'es',
 
-      // Bundled modules
-      preserveModules: false
-    },
+          // Bundled modules
+          preserveModules: false
+        },
 
     /**
      * Universal Module Definition (UMD) bundle for browser <script>
      * `window` globals and compatibility with CommonJS and AMD `require()`
      */
-    {
-      format: 'umd',
+    isDeprecated(input)
+      ? null
+      : {
+          format: 'umd',
 
-      // Bundled modules
-      preserveModules: false,
+          // Bundled modules
+          preserveModules: false,
 
-      // Export via `window.GOVUKFrontend.${exportName}`
-      name: 'GOVUKFrontend'
-    }
+          // Export via `window.GOVUKFrontend.${exportName}`
+          name: 'GOVUKFrontend'
+        }
   ],
 
   /**
diff --git a/packages/govuk-frontend/src/govuk/govuk-frontend-component.mjs b/packages/govuk-frontend/src/govuk/govuk-frontend-component.mjs
index 0abfd6c6f5..99050aa320 100644
--- a/packages/govuk-frontend/src/govuk/govuk-frontend-component.mjs
+++ b/packages/govuk-frontend/src/govuk/govuk-frontend-component.mjs
@@ -1 +1,6 @@
+/**
+ * @deprecated - The file has been renamed `component.mjs`
+ * @module
+ */
+
 export { Component as GOVUKFrontendComponent } from './component.mjs'
diff --git a/packages/govuk-frontend/tasks/config/deprecated-scripts.mjs b/packages/govuk-frontend/tasks/config/deprecated-scripts.mjs
new file mode 100644
index 0000000000..1cd5637c68
--- /dev/null
+++ b/packages/govuk-frontend/tasks/config/deprecated-scripts.mjs
@@ -0,0 +1,45 @@
+/**
+ * Logistics for handling files that get renamed and are no longer part of modules imported by `all.mjs`
+ * but need to remain in the published package to support deprecations before they get removed
+ */
+import { join } from 'node:path'
+
+/**
+ * Paths to the deprecated files within `src/govuk`
+ * (excluding the `src/govuk` part)
+ */
+export const deprecatedFilesPaths = ['govuk-frontend-component.mjs']
+
+/**
+ * Checks if given Rollup input is a deprecated file
+ *
+ * This helps us decide whether to create bundled version of that input,
+ * which we don't want for deprecated files (we just want to include them in the package)
+ *
+ * @param {string} rollupInput - The path to the input Rollup is compiling
+ * @returns {boolean} - Whether the path corresponds to a deprecated file
+ */
+export function isDeprecated(rollupInput) {
+  return deprecatedFilesPaths.some((deprecatedFilePath) =>
+    rollupInput.endsWith(join('govuk', deprecatedFilePath))
+  )
+}
+
+/**
+ * Creates a glob matching the list of paths
+ *
+ * @param {string[]} paths - The list of paths to create a glob for
+ * @returns {string} - A glob matching the deprecated files
+ */
+export function createGlobFromPaths(paths) {
+  // Curly brace syntax in glob only works
+  // when there's more than one pattern to match
+  // so we need to distinguish between the two.
+  if (paths.length > 1) {
+    const joinedGlobs = paths.join(',')
+
+    return `{${joinedGlobs}}`
+  }
+
+  return paths[0]
+}
diff --git a/packages/govuk-frontend/tasks/scripts.mjs b/packages/govuk-frontend/tasks/scripts.mjs
index 1f59a7aae9..e3a3f3af57 100644
--- a/packages/govuk-frontend/tasks/scripts.mjs
+++ b/packages/govuk-frontend/tasks/scripts.mjs
@@ -4,6 +4,11 @@ import { pkg } from '@govuk-frontend/config'
 import { configs, scripts, task } from '@govuk-frontend/tasks'
 import gulp from 'gulp'
 
+import {
+  createGlobFromPaths,
+  deprecatedFilesPaths
+} from './config/deprecated-scripts.mjs'
+
 /**
  * JavaScripts task (for watch)
  *
@@ -24,6 +29,20 @@ export const compile = (options) =>
       })
     ),
 
+    /**
+     * Compile deprecated files no longer imported by `all.mjs`
+     * but that need to be kept in the package
+     */
+    task.name("compile:js 'deprecations'", () =>
+      scripts.compile(createGlobFromPaths(deprecatedFilesPaths), {
+        ...options,
+
+        srcPath: join(options.srcPath, 'govuk'),
+        destPath: join(options.destPath, 'govuk'),
+        configPath: join(options.basePath, 'rollup.publish.config.mjs')
+      })
+    ),
+
     /**
      * Compile GOV.UK Frontend JavaScript for main entry point only
      */