From dfe47a5fe0e95f4196a600fdfd4fc7142e5f11e9 Mon Sep 17 00:00:00 2001
From: Colin Rotherham <work@colinr.com>
Date: Sat, 17 Sep 2022 22:19:53 +0100
Subject: [PATCH 1/9] Ensure `git clone` uses LF line endings

Improves compatibility on Windows/Linux/Mac for linting tools
---
 .gitattributes | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.gitattributes b/.gitattributes
index 0494519389..a7630ea5eb 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -1,2 +1,3 @@
+* text=auto eol=lf
 *.min.js diff=minjs
 *.min.css diff=mincss

From 30dd18404e950b9cca1bfff9a63781598d19343b Mon Sep 17 00:00:00 2001
From: Colin Rotherham <work@colinr.com>
Date: Thu, 22 Sep 2022 12:39:35 +0100
Subject: [PATCH 2/9] Review documentation for gulp tasks

Also includes `configPaths` consistency and JSDoc descriptions
---
 docs/contributing/coding-standards/css.md |  4 +-
 docs/contributing/tasks.md                | 91 +++++++++++------------
 gulpfile.js                               | 70 ++++++++++-------
 tasks/clean.js                            | 16 ++--
 tasks/gulp/watch.js                       | 28 +++++--
 tasks/nodemon.js                          | 15 ++--
 tasks/sassdoc.js                          |  6 +-
 7 files changed, 127 insertions(+), 103 deletions(-)

diff --git a/docs/contributing/coding-standards/css.md b/docs/contributing/coding-standards/css.md
index fa05d894db..67fa6926b5 100644
--- a/docs/contributing/coding-standards/css.md
+++ b/docs/contributing/coding-standards/css.md
@@ -118,7 +118,7 @@ See [testing and linting](/docs/releasing/testing-and-linting.md) for more infor
 
 ## Running the lint task
 
-You can run the linter in gulp by running `gulp scss:lint`, or use linting in [Sublime Text](https://github.com/SublimeLinter/SublimeLinter-stylelint), [Atom](https://atom.io/packages/linter-stylelint) or [other editors that support stylelint](https://stylelint.io/user-guide/integrations/editor).
+You can run the linter in Gulp by running `npm run lint:scss`, or use linting in [Sublime Text](https://github.com/SublimeLinter/SublimeLinter-stylelint), [Atom](https://atom.io/packages/linter-stylelint) or [other editors that support stylelint](https://stylelint.io/user-guide/integrations/editor).
 
 See also [testing and linting](/docs/releasing/testing-and-linting.md).
 
@@ -338,7 +338,7 @@ Good:
 }
 ```
 
-### `@if` statements should be written without surrounding brackets 
+### `@if` statements should be written without surrounding brackets
 
 Bad:
 ```
diff --git a/docs/contributing/tasks.md b/docs/contributing/tasks.md
index 8ecf3d2938..df80d6b4fc 100644
--- a/docs/contributing/tasks.md
+++ b/docs/contributing/tasks.md
@@ -1,52 +1,51 @@
-# NPM and Gulp tasks
+# npm and Gulp tasks
 
-This document describes the NPM scripts that run the application, and the gulp tasks they trigger to build files, update the package, copy assets and watch for changes.
+This document describes the npm scripts that run the application, and the Gulp tasks they trigger to build files, update the package, copy assets and watch for changes.
 
 To run the application without any tasks being triggered, see [Express app only](#express-app-only).
 
-## NPM script aliases
+## npm script aliases
 
-NPM scripts are defined in `package.json`. These trigger a number of gulp tasks.
+npm scripts are defined in `package.json`. These trigger a number of Gulp tasks.
 
-**`npm run start` will trigger `gulp dev` that:**
-- cleans the `public` folder
-- compiles component nunjucks files to `public`
-- copies icons to `public`
-- compile sass files, add vendor prefixes and copy to `public`
-- starts up the Express server and app
-- starts up `gulp watch` task to watch for changes
+**`npm run start` will trigger `gulp dev` that will:**
+- clean the `./public` folder
+- compile Sass and JavaScript (`gulp copy-assets`)
+- compile Sass documentation into `./sassdoc` (`gulp sassdoc`)
+- compile again when `.scss` and `.mjs` files change (`gulp watch`)
+- start up Express, restarting when `.js`, `.mjs`, and `.json` files change
 
 **`npm run test` will do the following:**
-- compile components to HTML
-- run JS tests
-- run CSS lint checker
-- run accessibility tests on HTML files
-- run tests on the review application
+- run Nunjucks macros tests
+- run JavaScript tests on the review application
+- run accessibility and HTML validation tests
 
-**`npm run heroku` runs on Heroku build/PR and it:**
-- compiles components' HTML
-- compiles CSS & JS
-- starts up Express
+**`npm run heroku` runs on Heroku build/PR and it will:**
+- run `npm run build:assets`
+- start up Express
 
 **`npm run build:assets` will do the following:**
-- compiles CSS & JS
-- compiles Sass documentation
+- output files into `./public`, or another location via the `--destination` flag
+- compile Sass and JavaScript (`gulp copy-assets`)
+- compile Sass documentation into `./sassdoc` (`gulp sassdoc`)
 
 **`npm run build:package` will do the following:**
-- clean the `package` folder
-- compile component nunjucks to HTML
-- copy template, macro and component.njk files for each component
-- copy Sass files, add vendor prefixes and replace path to be node_modules consumption compliant
+- output files into `./package`, or another location via the `--destination` flag
+- clean the `./package` folder
+- copy Sass files, applying Autoprefixer via PostCSS
+- copy Nunjucks component template/macro files, including JSON configs
+- copy JavaScript ESM source files
+- compile JavaScript ESM to CommonJS (`gulp js:compile`)
 - runs `npm run test:build:package` (which will test the output is correct)
 
 **`npm run build:dist` will do the following:**
-- clean the `dist` folder
-- copy JS
-- copy icons
-- copy SASS and add vendor prefixes
-- compile component nujucks files to HTML
-- take version from 'all/package.json' and append it to compiled & minified JS and CSS files
-- runs `npm run test:dist:package` (which will test the output is correct)
+- output files into `./dist`, or another location via the `--destination` flag
+- clean the `./dist` folder
+- compile Sass and JavaScript (`gulp copy-assets`)
+- copy fonts and images (`gulp copy:assets`)
+- append version number from `package/package.json` to compiled JavaScript and CSS files
+- runs `npm run test:build:dist` (which will test the output is correct)
+
 
 ## Gulp tasks
 
@@ -57,32 +56,30 @@ Gulp tasks are defined in `gulpfile.js` and .`/tasks/gulp/` folder.
 This task will:
 - list out all available tasks
 
-**`gulp test`**
-
-This task will:
-- Run scss:lint
-
 **`gulp watch`**
 
 This task will:
-- watch for changes in .mjs, .scss and .njk files and run below tasks.
+- run `gulp styles` when `.scss` files change
+- run `gulp scripts` when `.mjs` files change
 
 **`gulp styles`**
 
 This task will:
- - run scss lint task (`gulp scss:lint`)
- - sass compilation (`gulp scss:compile`) to a destination folder that can be specified via a --destination flag
+ - check Sass code quality via Stylelint (`gulp scss:lint`)
+ - compile Sass to CSS (`gulp scss:compile`) into `./public`, or another location via the `--destination` flag
 
 **`gulp scripts`**
 
- This task will:
- - concatenate and uglify javascript (`gulp js:compile`) to a destination folder that can be specified via a --destination flag
+This task will:
+ - check JavaScript code quality via ESLint (`gulp js:lint`) (using JavaScript Standard Style)
+ - compile JavaScript ESM to CommonJS (`gulp js:compile`) into `./public`, or another location via the `--destination` flag
 
-**`gulp compile:components`**
+**`gulp copy-assets`**
 
-  This task will:
-  - compile all `src/govuk/components/componentName/componentName.njk` files to HTML files
+This task will:
+- run `gulp styles`
+- run `gulp scripts`
 
 ## Express app only
 
-To simply run the Express app without gulp tasks being triggered, simply run `node app/start.js`.
+To start the Express app without Gulp tasks being triggered, run `node app/start.js`.
diff --git a/gulpfile.js b/gulpfile.js
index d2781f9367..b170d8159c 100644
--- a/gulpfile.js
+++ b/gulpfile.js
@@ -1,6 +1,6 @@
-const paths = require('./config/paths.js')
 const gulp = require('gulp')
 const taskListing = require('gulp-task-listing')
+const configPaths = require('./config/paths.js')
 const taskArguments = require('./tasks/task-arguments')
 
 // Gulp sub-tasks
@@ -16,51 +16,56 @@ const runNodemon = require('./tasks/nodemon.js')
 const updateDistAssetsVersion = require('./tasks/asset-version.js')
 const { cleanDist, cleanPackage, cleanPublic } = require('./tasks/clean.js')
 
-// Umbrella scripts tasks for preview ---
-// Runs js lint and compilation
-// --------------------------------------
+/**
+ * Umbrella scripts tasks (for watch)
+ * Runs JavaScript code quality checks and compilation
+ */
 gulp.task('scripts', gulp.series(
   'js:lint',
   'js:compile'
 ))
 
-// Umbrella styles tasks for preview ----
-// Runs scss lint and compilation
-// --------------------------------------
+/**
+ * Umbrella styles tasks (for watch)
+ * Runs Sass code quality checks and compilation
+ */
 gulp.task('styles', gulp.series(
   'scss:lint',
   'scss:compile'
 ))
 
-// Copy assets task ----------------------
-// Copies assets to taskArguments.destination (public)
-// --------------------------------------
+/**
+ * Copy assets task
+ * Copies assets to taskArguments.destination (public)
+ */
 gulp.task('copy:assets', () => {
-  return gulp.src(paths.src + 'assets/**/*')
+  return gulp.src(configPaths.src + 'assets/**/*')
     .pipe(gulp.dest(taskArguments.destination + '/assets/'))
 })
 
-// Copy assets task for local & heroku --
-// Copies files to
-// taskArguments.destination (public)
-// --------------------------------------
+/**
+ * Copy assets task for local & heroku
+ * Runs JavaScript and Sass compilation
+ */
 gulp.task('copy-assets', gulp.series(
   'styles',
   'scripts'
 ))
 
-// Serve task ---------------------------
-// Restarts node app when there is changed
-// affecting js, css or njk files
-// --------------------------------------
+/**
+ * Serve task
+ * Restarts Node.js app when there are changes
+ * affecting .js, .mjs and .json files
+ */
 gulp.task('serve', gulp.parallel(
   'watch',
   runNodemon
 ))
 
-// Dev task -----------------------------
-// Runs a sequence of task on start
-// --------------------------------------
+/**
+ * Dev task
+ * Runs a sequence of tasks on start
+ */
 gulp.task('dev', gulp.series(
   cleanPublic,
   'copy-assets',
@@ -68,15 +73,20 @@ gulp.task('dev', gulp.series(
   'serve'
 ))
 
-// Build package task -----------------
-// Prepare package folder for publishing
-// -------------------------------------
+/**
+ * Build package task
+ * Prepare package folder for publishing
+ */
 gulp.task('build:package', gulp.series(
   cleanPackage,
   'copy-files',
   'js:compile'
 ))
 
+/**
+ * Build dist task
+ * Prepare dist folder for release
+ */
 gulp.task('build:dist', gulp.series(
   cleanDist,
   'copy-assets',
@@ -84,9 +94,13 @@ gulp.task('build:dist', gulp.series(
   updateDistAssetsVersion
 ))
 
+/**
+ * Compiles Sass documentation
+ */
 gulp.task('sassdoc', buildSassdocs)
 
-// Default task -------------------------
-// Lists out available tasks.
-// --------------------------------------
+/**
+ * Default task
+ * Lists out available tasks
+ */
 gulp.task('default', taskListing)
diff --git a/tasks/clean.js b/tasks/clean.js
index d5f537df22..c7a4c73c25 100644
--- a/tasks/clean.js
+++ b/tasks/clean.js
@@ -1,25 +1,25 @@
-const paths = require('../config/paths.js')
 const del = require('del')
+const configPaths = require('../config/paths.js')
 
 function cleanDist () {
   return del([
-    `${paths.dist}**/*`
+    `${configPaths.dist}**/*`
   ])
 }
 
 function cleanPackage () {
   return del([
-    `${paths.package}**`,
-    `!${paths.package}`,
-    `!${paths.package}package.json`,
-    `!${paths.package}govuk-prototype-kit.config.json`,
-    `!${paths.package}README.md`
+    `${configPaths.package}**`,
+    `!${configPaths.package}`,
+    `!${configPaths.package}package.json`,
+    `!${configPaths.package}govuk-prototype-kit.config.json`,
+    `!${configPaths.package}README.md`
   ])
 }
 
 function cleanPublic () {
   return del([
-    `${paths.public}**/*`
+    `${configPaths.public}**/*`
   ])
 }
 
diff --git a/tasks/gulp/watch.js b/tasks/gulp/watch.js
index 41860f2b23..a4f0218b95 100644
--- a/tasks/gulp/watch.js
+++ b/tasks/gulp/watch.js
@@ -1,11 +1,23 @@
 const gulp = require('gulp')
 const configPaths = require('../../config/paths.js')
-const buildSassdocs = require('../sassdoc.js')
 
-// Watch task ----------------------------
-// When a file is changed, re-run the build task.
-// ---------------------------------------
-gulp.task('watch', () => Promise.all([
-  gulp.watch([configPaths.src + '**/**/*.scss', configPaths.app + 'assets/scss/**/*.scss', configPaths.fullPageExamples + '**/*.scss'], gulp.parallel('styles', buildSassdocs)),
-  gulp.watch([configPaths.src + '**/**/*.mjs'], gulp.series('scripts'))
-]))
+/**
+ * Watch task
+ * During development, this task will:
+ * - run `gulp styles` when `.scss` files change
+ * - run `gulp scripts` when `.mjs` files change
+ */
+gulp.task('watch', () => {
+  return Promise.all([
+    gulp.watch([
+      `${configPaths.src}**/**/*.scss`,
+      `${configPaths.app}assets/scss/**/*.scss`,
+      `${configPaths.fullPageExamples}**/*.scss`,
+      `!${configPaths.src}vendor/*`
+    ], gulp.series('styles')),
+
+    gulp.watch([
+      `${configPaths.src}**/**/*.mjs`
+    ], gulp.series('scripts'))
+  ])
+})
diff --git a/tasks/nodemon.js b/tasks/nodemon.js
index 7ef3ac8f33..01e337849c 100644
--- a/tasks/nodemon.js
+++ b/tasks/nodemon.js
@@ -1,15 +1,16 @@
 const nodemon = require('nodemon')
-const paths = require('../config/paths.js')
+const configPaths = require('../config/paths.js')
 
-// Nodemon task --------------------------
-// Restarts node app for changes affecting
-// js and json files
-// ---------------------------------------
+/**
+ * Nodemon task
+ * Restarts Node.js app when there are changes
+ * affecting .js, .mjs and .json files
+ */
 function runNodemon () {
   return nodemon({
     watch: [
-      paths.app,
-      paths.src
+      configPaths.app,
+      configPaths.src
     ],
     script: 'app/start.js'
   })
diff --git a/tasks/sassdoc.js b/tasks/sassdoc.js
index 50f7a908f7..10c3201972 100644
--- a/tasks/sassdoc.js
+++ b/tasks/sassdoc.js
@@ -1,9 +1,9 @@
 const sassdoc = require('sassdoc')
-const paths = require('../config/paths.js')
+const configPaths = require('../config/paths.js')
 
 function buildSassdocs () {
-  return sassdoc([paths.src + '**/**/*.scss', `!${paths.src}/vendor/*`], {
-    dest: paths.sassdoc,
+  return sassdoc([configPaths.src + '**/**/*.scss', `!${configPaths.src}/vendor/*`], {
+    dest: configPaths.sassdoc,
     groups: {
       'components/button': 'Components / Button',
       'helpers/accessibility': 'Helpers / Accessibility',

From d20718043e5b775032ec76b219fad12828833e7c Mon Sep 17 00:00:00 2001
From: Colin Rotherham <work@colinr.com>
Date: Tue, 27 Sep 2022 09:37:21 +0100
Subject: [PATCH 3/9] Add npm task wrapper for gulp

---
 tasks/gulp/lint.js | 35 +++------------------------------
 tasks/run.js       | 48 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 51 insertions(+), 32 deletions(-)
 create mode 100644 tasks/run.js

diff --git a/tasks/gulp/lint.js b/tasks/gulp/lint.js
index 15b422ac61..548cbac623 100644
--- a/tasks/gulp/lint.js
+++ b/tasks/gulp/lint.js
@@ -1,41 +1,12 @@
 const gulp = require('gulp')
-const { spawn } = require('child_process')
+const { npmScriptTask } = require('../run.js')
 
 /**
  * JavaScript code quality checks via ESLint
  */
-gulp.task('js:lint', () => {
-  return runTask('lint:js', ['--silent'])
-})
+gulp.task('js:lint', npmScriptTask('lint:js', ['--silent']))
 
 /**
  * Sass code quality checks via Stylelint
  */
-gulp.task('scss:lint', () => {
-  return runTask('lint:scss', ['--silent'])
-})
-
-/**
- * Spawns Node.js child process for npm task
- * rather than using Gulp
- *
- * @param {string} name - npm script name
- * @param {string[]} [args] - npm script arguments
- * @returns {Promise<number>} Exit code
- */
-async function runTask (name, args = []) {
-  const command = process.platform === 'win32' ? 'npm.cmd' : 'npm'
-
-  return new Promise((resolve, reject) => {
-    const task = spawn(command, ['run', name, ...args])
-
-    task.stdout.on('data', (data) => console.log(data.toString()))
-    task.stderr.on('data', (data) => console.error(data.toString()))
-
-    // Reject on actual task errors to exit `gulp watch`
-    task.on('error', reject)
-
-    // Resolve all exit codes to continue `gulp watch`
-    task.on('close', resolve)
-  })
-}
+gulp.task('scss:lint', npmScriptTask('lint:scss', ['--silent']))
diff --git a/tasks/run.js b/tasks/run.js
new file mode 100644
index 0000000000..1d2a974c01
--- /dev/null
+++ b/tasks/run.js
@@ -0,0 +1,48 @@
+const { spawn } = require('child_process')
+
+/**
+ * Spawns Node.js child process for npm script
+ * rather than using Gulp
+ *
+ * @param {string} name - npm script name
+ * @param {string[]} [args] - npm script arguments
+ * @returns {Promise<number>} Exit code
+ */
+async function npmScript (name, args = []) {
+  const command = process.platform === 'win32' ? 'npm.cmd' : 'npm'
+
+  return new Promise((resolve, reject) => {
+    const script = spawn(command, ['run', name, ...args])
+
+    script.stdout.on('data', (data) => console.log(data.toString()))
+    script.stderr.on('data', (data) => console.error(data.toString()))
+
+    // Reject on actual script errors to exit `gulp watch`
+    script.on('error', reject)
+
+    // Resolve all exit codes to continue `gulp watch`
+    script.on('close', resolve)
+  })
+}
+
+/**
+ * Creates a Gulp task for npmScript()
+ *
+ * @param {string} name - npm script name
+ * @param {string[]} [args] - npm script arguments
+ * @returns {() => Promise<number>} Exit code
+ */
+const npmScriptTask = (name, args = []) => {
+  const task = () => npmScript(name, args)
+
+  // Add task alias
+  // https://gulpjs.com/docs/en/api/task#task-metadata
+  task.displayName = `npm run ${name} ${args.join(' ')}`.trim()
+
+  return task
+}
+
+module.exports = {
+  npmScript,
+  npmScriptTask
+}

From e6fd81759c0b499d06f52b36ff83c4374c637f84 Mon Sep 17 00:00:00 2001
From: Colin Rotherham <work@colinr.com>
Date: Tue, 27 Sep 2022 09:38:12 +0100
Subject: [PATCH 4/9] Use npm wrapper to replace gulp lint tasks

---
 docs/contributing/tasks.md |  4 ++--
 gulpfile.js                |  9 ++++-----
 tasks/gulp/lint.js         | 12 ------------
 3 files changed, 6 insertions(+), 19 deletions(-)
 delete mode 100644 tasks/gulp/lint.js

diff --git a/docs/contributing/tasks.md b/docs/contributing/tasks.md
index df80d6b4fc..886c26d799 100644
--- a/docs/contributing/tasks.md
+++ b/docs/contributing/tasks.md
@@ -65,13 +65,13 @@ This task will:
 **`gulp styles`**
 
 This task will:
- - check Sass code quality via Stylelint (`gulp scss:lint`)
+ - check Sass code quality via Stylelint (`npm run lint:scss`)
  - compile Sass to CSS (`gulp scss:compile`) into `./public`, or another location via the `--destination` flag
 
 **`gulp scripts`**
 
 This task will:
- - check JavaScript code quality via ESLint (`gulp js:lint`) (using JavaScript Standard Style)
+ - check JavaScript code quality via ESLint (`npm run lint:js`) (using JavaScript Standard Style)
  - compile JavaScript ESM to CommonJS (`gulp js:compile`) into `./public`, or another location via the `--destination` flag
 
 **`gulp copy-assets`**
diff --git a/gulpfile.js b/gulpfile.js
index b170d8159c..074124d4ce 100644
--- a/gulpfile.js
+++ b/gulpfile.js
@@ -5,23 +5,22 @@ const taskArguments = require('./tasks/task-arguments')
 
 // Gulp sub-tasks
 require('./tasks/gulp/compile-assets.js')
-require('./tasks/gulp/lint.js')
-require('./tasks/gulp/watch.js')
-// new tasks
 require('./tasks/gulp/copy-to-destination.js')
+require('./tasks/gulp/watch.js')
 
 // Node tasks
 const buildSassdocs = require('./tasks/sassdoc.js')
 const runNodemon = require('./tasks/nodemon.js')
 const updateDistAssetsVersion = require('./tasks/asset-version.js')
 const { cleanDist, cleanPackage, cleanPublic } = require('./tasks/clean.js')
+const { npmScriptTask } = require('./tasks/run.js')
 
 /**
  * Umbrella scripts tasks (for watch)
  * Runs JavaScript code quality checks and compilation
  */
 gulp.task('scripts', gulp.series(
-  'js:lint',
+  npmScriptTask('lint:js', ['--silent']),
   'js:compile'
 ))
 
@@ -30,7 +29,7 @@ gulp.task('scripts', gulp.series(
  * Runs Sass code quality checks and compilation
  */
 gulp.task('styles', gulp.series(
-  'scss:lint',
+  npmScriptTask('lint:scss', ['--silent']),
   'scss:compile'
 ))
 
diff --git a/tasks/gulp/lint.js b/tasks/gulp/lint.js
deleted file mode 100644
index 548cbac623..0000000000
--- a/tasks/gulp/lint.js
+++ /dev/null
@@ -1,12 +0,0 @@
-const gulp = require('gulp')
-const { npmScriptTask } = require('../run.js')
-
-/**
- * JavaScript code quality checks via ESLint
- */
-gulp.task('js:lint', npmScriptTask('lint:js', ['--silent']))
-
-/**
- * Sass code quality checks via Stylelint
- */
-gulp.task('scss:lint', npmScriptTask('lint:scss', ['--silent']))

From 8e919002a06bf534153f997c830be4d5fe1819d2 Mon Sep 17 00:00:00 2001
From: Colin Rotherham <work@colinr.com>
Date: Thu, 22 Sep 2022 12:45:48 +0100
Subject: [PATCH 5/9] Rename `gulp copy-assets` to `gulp compile`

Also moves sassdoc into `gulp compile` sub tasks
---
 .github/workflows/tests.yml |  2 +-
 docs/contributing/tasks.md  | 15 +++++++--------
 gulpfile.js                 | 19 +++++++------------
 package.json                |  6 +++---
 4 files changed, 18 insertions(+), 24 deletions(-)

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index a1675742a6..9dd248624d 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -36,7 +36,7 @@ jobs:
 
       - name: Build
         run: |
-          npm run build:assets
+          npm run build:compile
           npm run build:package
           npm run build:dist
 
diff --git a/docs/contributing/tasks.md b/docs/contributing/tasks.md
index 886c26d799..af329577bf 100644
--- a/docs/contributing/tasks.md
+++ b/docs/contributing/tasks.md
@@ -10,8 +10,7 @@ npm scripts are defined in `package.json`. These trigger a number of Gulp tasks.
 
 **`npm run start` will trigger `gulp dev` that will:**
 - clean the `./public` folder
-- compile Sass and JavaScript (`gulp copy-assets`)
-- compile Sass documentation into `./sassdoc` (`gulp sassdoc`)
+- compile JavaScript and Sass, including Sass documentation (`gulp compile`)
 - compile again when `.scss` and `.mjs` files change (`gulp watch`)
 - start up Express, restarting when `.js`, `.mjs`, and `.json` files change
 
@@ -21,13 +20,12 @@ npm scripts are defined in `package.json`. These trigger a number of Gulp tasks.
 - run accessibility and HTML validation tests
 
 **`npm run heroku` runs on Heroku build/PR and it will:**
-- run `npm run build:assets`
+- run `npm run build:compile`
 - start up Express
 
-**`npm run build:assets` will do the following:**
+**`npm run build:compile` will do the following:**
 - output files into `./public`, or another location via the `--destination` flag
-- compile Sass and JavaScript (`gulp copy-assets`)
-- compile Sass documentation into `./sassdoc` (`gulp sassdoc`)
+- compile JavaScript and Sass, including Sass documentation (`gulp compile`)
 
 **`npm run build:package` will do the following:**
 - output files into `./package`, or another location via the `--destination` flag
@@ -41,7 +39,7 @@ npm scripts are defined in `package.json`. These trigger a number of Gulp tasks.
 **`npm run build:dist` will do the following:**
 - output files into `./dist`, or another location via the `--destination` flag
 - clean the `./dist` folder
-- compile Sass and JavaScript (`gulp copy-assets`)
+- compile JavaScript and Sass, including Sass documentation (`gulp compile`)
 - copy fonts and images (`gulp copy:assets`)
 - append version number from `package/package.json` to compiled JavaScript and CSS files
 - runs `npm run test:build:dist` (which will test the output is correct)
@@ -74,11 +72,12 @@ This task will:
  - check JavaScript code quality via ESLint (`npm run lint:js`) (using JavaScript Standard Style)
  - compile JavaScript ESM to CommonJS (`gulp js:compile`) into `./public`, or another location via the `--destination` flag
 
-**`gulp copy-assets`**
+**`gulp compile`**
 
 This task will:
 - run `gulp styles`
 - run `gulp scripts`
+- compile Sass documentation into `./sassdoc`
 
 ## Express app only
 
diff --git a/gulpfile.js b/gulpfile.js
index 074124d4ce..3f5df56069 100644
--- a/gulpfile.js
+++ b/gulpfile.js
@@ -43,12 +43,13 @@ gulp.task('copy:assets', () => {
 })
 
 /**
- * Copy assets task for local & heroku
- * Runs JavaScript and Sass compilation
+ * Compile task for local & heroku
+ * Runs JavaScript and Sass compilation, including Sass documentation
  */
-gulp.task('copy-assets', gulp.series(
+gulp.task('compile', gulp.series(
   'styles',
-  'scripts'
+  'scripts',
+  buildSassdocs
 ))
 
 /**
@@ -67,8 +68,7 @@ gulp.task('serve', gulp.parallel(
  */
 gulp.task('dev', gulp.series(
   cleanPublic,
-  'copy-assets',
-  buildSassdocs,
+  'compile',
   'serve'
 ))
 
@@ -88,16 +88,11 @@ gulp.task('build:package', gulp.series(
  */
 gulp.task('build:dist', gulp.series(
   cleanDist,
-  'copy-assets',
+  'compile',
   'copy:assets',
   updateDistAssetsVersion
 ))
 
-/**
- * Compiles Sass documentation
- */
-gulp.task('sassdoc', buildSassdocs)
-
 /**
  * Default task
  * Lists out available tasks
diff --git a/package.json b/package.json
index 0c90085f9a..cf5913300d 100644
--- a/package.json
+++ b/package.json
@@ -10,14 +10,14 @@
   "scripts": {
     "postinstall": "npm ls --depth=0",
     "start": "gulp dev",
-    "heroku": "npm run build:assets && node app/start.js",
+    "heroku": "npm run build:compile && node app/start.js",
     "build-release": "./bin/build-release.sh",
     "publish-release": "./bin/publish-release.sh",
     "pre-release": "./bin/pre-release.sh",
-    "build:assets": "gulp copy-assets && gulp sassdoc",
+    "build:compile": "gulp compile",
     "build:package": "gulp build:package --destination 'package' && npm run test:build:package",
     "build:dist": "gulp build:dist --destination 'dist' && npm run test:build:dist",
-    "pretest": "npm run build:assets",
+    "pretest": "npm run build:compile",
     "test": "jest --color --ignoreProjects \"Gulp tasks\" --maxWorkers=50%",
     "test:build:package": "npx jest --selectProjects \"Gulp tasks\" --testMatch \"**/*build-package*\"",
     "test:build:dist": "npx jest --selectProjects \"Gulp tasks\" --testMatch \"**/*build-dist*\"",

From e4f4b1be381cb4dcf760ecb1ee7b02af06753da4 Mon Sep 17 00:00:00 2001
From: Colin Rotherham <work@colinr.com>
Date: Mon, 26 Sep 2022 14:29:04 +0100
Subject: [PATCH 6/9] Rename `gulp copy-files` to `gulp copy:files`

---
 tasks/gulp/copy-to-destination.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tasks/gulp/copy-to-destination.js b/tasks/gulp/copy-to-destination.js
index 2a81fcf6da..d971280a09 100644
--- a/tasks/gulp/copy-to-destination.js
+++ b/tasks/gulp/copy-to-destination.js
@@ -13,7 +13,7 @@ const rename = require('gulp-rename')
 const configPaths = require('../../config/paths.js')
 const taskArguments = require('../task-arguments')
 
-gulp.task('copy-files', () => {
+gulp.task('copy:files', () => {
   return merge(
     /**
      * Copy files to destination with './govuk-esm' suffix

From 83f910646fd29f251a5a4c74483896236ffea628 Mon Sep 17 00:00:00 2001
From: Colin Rotherham <work@colinr.com>
Date: Mon, 26 Sep 2022 14:29:08 +0100
Subject: [PATCH 7/9] Rename `gulp copy-files` to `gulp copy:files`

---
 gulpfile.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/gulpfile.js b/gulpfile.js
index 3f5df56069..84bcacc320 100644
--- a/gulpfile.js
+++ b/gulpfile.js
@@ -78,7 +78,7 @@ gulp.task('dev', gulp.series(
  */
 gulp.task('build:package', gulp.series(
   cleanPackage,
-  'copy-files',
+  'copy:files',
   'js:compile'
 ))
 

From 4c11f65570ccc438a73d44de22016bd89f79e394 Mon Sep 17 00:00:00 2001
From: Colin Rotherham <work@colinr.com>
Date: Mon, 26 Sep 2022 14:30:11 +0100
Subject: [PATCH 8/9] Separate out CSS/JS lint tasks from build and test

Linting tasks no longer run before assets are built or tested
---
 .github/workflows/tests.yml | 3 +++
 docs/contributing/tasks.md  | 4 ++--
 gulpfile.js                 | 4 ++--
 3 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 9dd248624d..4b03b872ac 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -34,6 +34,9 @@ jobs:
         if: steps.npm-cache.outputs.cache-hit != 'true'
         run: npm ci
 
+      - name: Lint
+        run: npm run lint
+
       - name: Build
         run: |
           npm run build:compile
diff --git a/docs/contributing/tasks.md b/docs/contributing/tasks.md
index af329577bf..296ab92f5a 100644
--- a/docs/contributing/tasks.md
+++ b/docs/contributing/tasks.md
@@ -75,8 +75,8 @@ This task will:
 **`gulp compile`**
 
 This task will:
-- run `gulp styles`
-- run `gulp scripts`
+- run sub tasks from `gulp styles` without ESLint code quality checks
+- run sub tasks from `gulp scripts` without StyleLint code quality checks
 - compile Sass documentation into `./sassdoc`
 
 ## Express app only
diff --git a/gulpfile.js b/gulpfile.js
index 84bcacc320..55d26013d7 100644
--- a/gulpfile.js
+++ b/gulpfile.js
@@ -47,8 +47,8 @@ gulp.task('copy:assets', () => {
  * Runs JavaScript and Sass compilation, including Sass documentation
  */
 gulp.task('compile', gulp.series(
-  'styles',
-  'scripts',
+  'js:compile',
+  'scss:compile',
   buildSassdocs
 ))
 

From 10d45814dfa6ef487ee08f0ccb77abac20b4f52a Mon Sep 17 00:00:00 2001
From: Colin Rotherham <work@colinr.com>
Date: Thu, 22 Sep 2022 12:20:53 +0100
Subject: [PATCH 9/9] Add display names to task functions

See https://gulpjs.com/docs/en/api/task#task-metadata
---
 gulpfile.js            | 6 +++---
 tasks/asset-version.js | 6 +++++-
 tasks/clean.js         | 4 ++++
 tasks/nodemon.js       | 6 +++++-
 tasks/sassdoc.js       | 6 +++++-
 5 files changed, 22 insertions(+), 6 deletions(-)

diff --git a/gulpfile.js b/gulpfile.js
index 55d26013d7..82f9d26cbc 100644
--- a/gulpfile.js
+++ b/gulpfile.js
@@ -9,9 +9,9 @@ require('./tasks/gulp/copy-to-destination.js')
 require('./tasks/gulp/watch.js')
 
 // Node tasks
-const buildSassdocs = require('./tasks/sassdoc.js')
-const runNodemon = require('./tasks/nodemon.js')
-const updateDistAssetsVersion = require('./tasks/asset-version.js')
+const { buildSassdocs } = require('./tasks/sassdoc.js')
+const { runNodemon } = require('./tasks/nodemon.js')
+const { updateDistAssetsVersion } = require('./tasks/asset-version.js')
 const { cleanDist, cleanPackage, cleanPublic } = require('./tasks/clean.js')
 const { npmScriptTask } = require('./tasks/run.js')
 
diff --git a/tasks/asset-version.js b/tasks/asset-version.js
index 8eb97f1242..7b5966ce26 100644
--- a/tasks/asset-version.js
+++ b/tasks/asset-version.js
@@ -32,4 +32,8 @@ async function updateDistAssetsVersion () {
   return Promise.all(assetTasks)
 }
 
-module.exports = updateDistAssetsVersion
+updateDistAssetsVersion.displayName = 'update-dist-assets-version'
+
+module.exports = {
+  updateDistAssetsVersion
+}
diff --git a/tasks/clean.js b/tasks/clean.js
index c7a4c73c25..c09390dc22 100644
--- a/tasks/clean.js
+++ b/tasks/clean.js
@@ -23,6 +23,10 @@ function cleanPublic () {
   ])
 }
 
+cleanDist.displayName = 'clean:dist'
+cleanPackage.displayName = 'clean:package'
+cleanPublic.displayName = 'clean:public'
+
 module.exports = {
   cleanDist,
   cleanPackage,
diff --git a/tasks/nodemon.js b/tasks/nodemon.js
index 01e337849c..7a489daf29 100644
--- a/tasks/nodemon.js
+++ b/tasks/nodemon.js
@@ -16,4 +16,8 @@ function runNodemon () {
   })
 }
 
-module.exports = runNodemon
+runNodemon.displayName = 'nodemon'
+
+module.exports = {
+  runNodemon
+}
diff --git a/tasks/sassdoc.js b/tasks/sassdoc.js
index 10c3201972..8ecee7ebe7 100644
--- a/tasks/sassdoc.js
+++ b/tasks/sassdoc.js
@@ -31,4 +31,8 @@ function buildSassdocs () {
   })
 }
 
-module.exports = buildSassdocs
+buildSassdocs.displayName = 'sassdoc:compile'
+
+module.exports = {
+  buildSassdocs
+}