Merge pull request #3562 from alphagov/gulp-package-prep

Prepare Gulp tasks + helpers for directory changes

.github/workflows/screenshots.yml

@@ -44,7 +44,7 @@ jobs:
         run: npm start --workspace app &
 
       - name: Send screenshots to Percy
-        run: npx percy exec --parallel -- npm run test:screenshots
+        run: npx percy exec --parallel -- npm run test:screenshots --workspace app
 
       - name: Finalise Percy build
         run: npx percy build:finalize

.github/workflows/tests.yml

@@ -159,8 +159,8 @@ jobs:
             run: npm run build:package
 
           - description: Verify distribution build
-            name: test-build-dist
-            run: npm run build:dist
+            name: test-build-release
+            run: npm run build:release
 
           - description: JavaScript behaviour tests
             name: test-behaviour

app/gulpfile.mjs

@@ -1,16 +1,24 @@
+import { browser } from 'govuk-frontend-tasks'
 import gulp from 'gulp'
 
 import * as build from './tasks/build/index.mjs'
+import { options } from './tasks/build/options.mjs'
 import { scripts, styles } from './tasks/index.mjs'
 
 /**
  * Build target tasks
  */
-gulp.task('build', build.dist)
-gulp.task('dev', build.dev)
+gulp.task('build', build.dist(options))
+gulp.task('dev', build.dev(options))
 
 /**
  * Utility tasks
  */
-gulp.task('scripts', scripts)
-gulp.task('styles', styles)
+gulp.task('scripts', scripts(options))
+gulp.task('styles', styles(options))
+
+/**
+ * Screenshots task
+ * Sends screenshots to Percy for visual regression testing
+ */
+gulp.task('screenshots', browser.screenshots)

app/package.json

@@ -9,10 +9,12 @@
   },
   "license": "MIT",
   "scripts": {
-    "build": "gulp build",
-    "dev": "gulp dev",
+    "predev": "npm run build",
+    "dev": "gulp dev --color",
+    "build": "gulp build --color",
     "serve": "nodemon",
-    "start": "node src/start.mjs"
+    "start": "node src/start.mjs",
+    "test:screenshots": "gulp screenshots --color"
   },
   "dependencies": {
     "chokidar": "^3.5.3",

app/tasks/build/dev.mjs

@@ -1,17 +1,15 @@
-import { paths } from 'govuk-frontend-config'
 import { npm } from 'govuk-frontend-tasks'
 import gulp from 'gulp'
 
 import { watch } from '../index.mjs'
 
-import dist from './dist.mjs'
-
 /**
  * Dev task
  * Runs a sequence of tasks on start
+ *
+ * @type {import('govuk-frontend-tasks').TaskFunction}
  */
-export default gulp.series(
-  dist,
-  watch,
-  npm.script('serve', paths.app)
+export default (options) => gulp.parallel(
+  npm.script('serve', options),
+  watch(options)
 )

app/tasks/build/dist.mjs

@@ -1,6 +1,3 @@
-import { join } from 'path'
-
-import { paths } from 'govuk-frontend-config'
 import { files, task } from 'govuk-frontend-tasks'
 import gulp from 'gulp'
 
@@ -9,16 +6,16 @@ import { scripts, styles } from '../index.mjs'
 /**
  * Build review app task
  * Prepare dist folder for review app
+ *
+ * @type {import('govuk-frontend-tasks').TaskFunction}
  */
-export default gulp.series(
+export default (options) => gulp.series(
   task.name('clean', () =>
-    files.clean('**/*', {
-      destPath: join(paths.app, 'dist')
-    })
+    files.clean('*', options)
   ),
 
   gulp.parallel(
-    scripts,
-    styles
+    scripts(options),
+    styles(options)
   )
 )

app/tasks/build/options.mjs

@@ -0,0 +1,14 @@
+import { join } from 'path'
+
+import { paths } from 'govuk-frontend-config'
+
+/**
+ * Default build paths
+ *
+ * @type {import('govuk-frontend-tasks').TaskOptions}
+ */
+export const options = {
+  basePath: paths.app,
+  srcPath: join(paths.app, 'src'),
+  destPath: join(paths.app, 'dist')
+}

app/tasks/scripts.mjs

@@ -7,12 +7,16 @@ import gulp from 'gulp'
 /**
  * JavaScripts task (for watch)
  * Compilation, documentation
+ *
+ * @type {import('govuk-frontend-tasks').TaskFunction}
  */
-export const compile = gulp.series(
+export const compile = (options) => gulp.series(
   task.name('compile:js', () =>
     scripts.compile('all.mjs', {
+      // TODO: Review app should use `options.srcPath` to
+      // import scripts from its own `javascripts` directory
       srcPath: join(paths.src, 'govuk'),
-      destPath: join(paths.app, 'dist/javascripts'),
+      destPath: join(options.destPath, 'javascripts'),
 
       filePath (file) {
         return join(file.dir, `${file.name}.min.js`)

app/tasks/styles.mjs

@@ -1,18 +1,19 @@
 import { join } from 'path'
 
-import { paths } from 'govuk-frontend-config'
 import { npm, styles, task } from 'govuk-frontend-tasks'
 import gulp from 'gulp'
 
 /**
  * Stylesheets task (for watch)
  * Compilation, documentation
+ *
+ * @type {import('govuk-frontend-tasks').TaskFunction}
  */
-export const compile = gulp.series(
+export const compile = (options) => gulp.series(
   task.name('compile:scss', () =>
     styles.compile('**/[!_]*.scss', {
-      srcPath: join(paths.app, 'src/stylesheets'),
-      destPath: join(paths.app, 'dist/stylesheets'),
+      srcPath: join(options.srcPath, 'stylesheets'),
+      destPath: join(options.destPath, 'stylesheets'),
 
       filePath (file) {
         return join(file.dir, `${file.name}.min.css`)

app/tasks/watch.mjs

@@ -1,5 +1,5 @@
 import { paths } from 'govuk-frontend-config'
-import { npm } from 'govuk-frontend-tasks'
+import { npm, task } from 'govuk-frontend-tasks'
 import gulp from 'gulp'
 import slash from 'slash'
 
@@ -11,26 +11,34 @@ import { scripts, styles } from './index.mjs'
  * - lint and run `gulp styles` when `.scss` files change
  * - lint and run `gulp scripts` when `.mjs` files change
  *
- * @returns {Promise<import('fs').FSWatcher[]>} Array from file system watcher objects
+ * @type {import('govuk-frontend-tasks').TaskFunction}
  */
-export function watch () {
-  return Promise.all([
+export const watch = (options) => gulp.parallel(
+  /**
+   * Stylesheets lint + build watcher
+   */
+  task.name('compile:scss watch', () =>
     gulp.watch([
       `${slash(paths.root)}/sassdoc.config.yaml`,
       `${slash(paths.app)}/src/**/*.scss`,
       `${slash(paths.src)}/govuk/**/*.scss`,
       `!${slash(paths.src)}/govuk/vendor/*`
     ], gulp.parallel(
       npm.script('lint:scss'),
-      styles
-    )),
+      styles(options)
+    ))
+  ),
 
+  /**
+   * JavaScripts lint + build watcher
+   */
+  task.name('compile:js watch', () =>
     gulp.watch([
       `${slash(paths.root)}/typedoc.config.js`,
       `${slash(paths.src)}/govuk/**/*.mjs`
     ], gulp.parallel(
       npm.script('lint:js'),
-      scripts
+      scripts(options)
     ))
-  ])
-}
+  )
+)

bin/build-release.sh

@@ -28,7 +28,7 @@ fi
 
 npm run test
 npm run build:package
-npm run build:dist
+npm run build:release
 
 ALL_PACKAGE_VERSION=$(node -p "require('./package/package.json').version")
 TAG="v$ALL_PACKAGE_VERSION"

docs/contributing/application-architecture.md

@@ -23,7 +23,7 @@
 
 - `shared/`
 
-  Shared packages used by tests, build tools and the [review app](../../app).
+  Shared packages used by tests, build tools and the [review app](/app).
 
   - `config/`
 
@@ -43,4 +43,4 @@
 
 - `src/`
 
-  Source files. See README.md in the src directory for details.
+  Source files. See [README.md](/src/govuk/README.md) in the src directory for details.

docs/contributing/coding-standards/css.md

@@ -112,7 +112,7 @@ This makes it easier to keep track of different contexts.
 # Linting
 
 To ensure code quality and consistency in our Sass files we check that certain
-style rules are followed. These rules are based on [stylelint-config-gds](https://github.com/alphagov/stylelint-config-gds/blob/main/scss.js), but we also add our own custom rules with a project [config file](../../../stylelint.config.js).
+style rules are followed. These rules are based on [stylelint-config-gds](https://github.com/alphagov/stylelint-config-gds/blob/main/scss.js), but we also add our own custom rules with a project [config file](/stylelint.config.js).
 
 See [testing and linting](/docs/releasing/testing-and-linting.md) for more information.
 
@@ -548,4 +548,4 @@ The SassDoc comments are used to generate the [Sass API reference in the GOV.UK
 
 For SassDoc comments, use 3 slashes (`///`) at the start of the line.
 
-See [colour.scss](../../../src/govuk/helpers/_colour.scss) for an example of SassDoc syntax.
+See [`_colour.scss`](/src/govuk/helpers/_colour.scss) for an example of SassDoc syntax.

docs/contributing/managing-change.md

@@ -176,6 +176,6 @@ Keep the old name in the selector list, and mark it as deprecated.
 
 In the above examples we've used `@include _warning(...)` instead of the native sass `@warn` at-rule. We use this instead of `@warn` because it gives users the option to suppress deprecation warnings by interacting with the `$govuk-suppressed-warnings` map.
 
-You can read more about how `$govuk-suppressed-warnings` and `_warning` work by reading their respective sassdocs in `/src/govuk/settings/warnings.scss`.
+You can read more about how `$govuk-suppressed-warnings` and `_warning` work by reading their respective sassdocs in [`src/govuk/settings/_warnings.scss`](/src/govuk/settings/_warnings.scss).
 
 We make this option available for users because they can not always action deprecation warnings or upgrade their codebase beyond a specific version of GOV.UK Frontend. For example, a legacy codebase that does not have the resource to upgrade to the latest breaking change where a deprecated feature will be removed. This feature allows those users to continue to operate their codebase without having to repeatedly see non-actionable deprecation warnings in their testing.

docs/contributing/tasks.md

@@ -42,26 +42,26 @@ npm scripts are defined in `package.json`. These trigger a number of Gulp tasks.
 - compile JavaScript to Universal Module Definition (UMD)
 - runs `npm run postbuild:package` (which will test the output is correct)
 
-**`npm run build:dist` will do the following:**
+**`npm run build:release` will do the following:**
 
 - clean the `./dist` folder
 - output files into `./dist`
 - copy fonts and images
 - compile JavaScript and Sass
 - append version number from `package/package.json` to compiled JavaScript and CSS files
-- runs `npm run postbuild:dist` (which will test the output is correct)
+- runs `npm run postbuild:release` (which will test the output is correct)
 
 ## Gulp tasks
 
-Project Gulp tasks are defined in [`gulpfile.mjs`](../../gulpfile.mjs) and the [`tasks/`](../../shared/tasks) folder.
+Project Gulp tasks are defined in [`gulpfile.mjs`](/gulpfile.mjs) and the [`tasks/`](/shared/tasks) folder.
 
 **`gulp --tasks`**
 
 This task will:
 
 - list out all available tasks
 
-Review app Gulp tasks are defined in [`app/gulpfile.mjs`](../../app/gulpfile.mjs) and the [`app/tasks/`](../../app/tasks) folder.
+Review app Gulp tasks are defined in [`app/gulpfile.mjs`](/app/gulpfile.mjs) and the [`app/tasks/`](/app/tasks) folder.
 
 Gulp tasks from npm workspaces (such as the review app) can be run as shown:
 

docs/contributing/testing.md

@@ -116,7 +116,7 @@ Where `<COMPONENT>` is the name of the component you changed or added to.
 
 Update or add tests in the `.test.js` file that matches the name of the `.scss` file you created or updated. Create the `.test.js` file if it does not exist.
 
-For example, if you updated a mixin in `src/govuk/helpers/_colour.scss`, update or add tests in `src/govuk/helpers/_colour.test.js`.
+For example, if you updated a mixin in [`src/govuk/helpers/_colour.scss`](/src/govuk/helpers/_colour.scss), update or add tests in [`src/govuk/helpers/colour.test.js`](/src/govuk/helpers/colour.test.js).
 
 ## 7. Update the snapshot tests
 

docs/releasing/publishing-a-pre-release.md

@@ -13,7 +13,7 @@ Use pre-releases when you:
 
 ## What happens when you pre-release GOV.UK Frontend
 
-When you pre-release GOV.UK Frontend, this creates a GitHub branch. This branch contains the GOV.UK Frontend `/package` directory with your trial changes.
+When you pre-release GOV.UK Frontend, this creates a GitHub branch. This branch contains the GOV.UK Frontend [`/package`](/package) directory with your trial changes.
 
 Projects can point to this branch in their package.json, instead of to the published [GOV.UK Frontend npm package](https://www.npmjs.com/package/govuk-frontend). No changes are published to the GOV.UK Frontend npm package as part of this process.
 

docs/releasing/publishing-from-a-support-branch.md

@@ -55,7 +55,7 @@ Read the docs for [what to do before publishing a release](/docs/releasing/befor
 
 4. Run `npm ci` to make sure you have the exact dependencies installed.
 
-5. Update the [`CHANGELOG.md`](../../CHANGELOG.md) by:
+5. Update the [`CHANGELOG.md`](/CHANGELOG.md) by:
 
    - changing the 'Unreleased' heading to the new version number and its release type. For example, '3.14.1 (Fix release)'
    - adding a new 'Unreleased' heading above the new version number and release type, so users will know where to add PRs to the changelog
@@ -67,13 +67,13 @@ Read the docs for [what to do before publishing a release](/docs/releasing/befor
    npm version <NEW VERSION NUMBER> --no-git-tag-version --workspace package
    ```
 
-   This step will update the `package.json` and project `package-lock.json` files.
+   This step will update the [`package.json`](/package.json) and project [`package-lock.json`](/package-lock.json) files.
 
    Do not commit the changes.
 
 7. Run `npm run build-release` to:
 
-   - build GOV.UK Frontend into the `/package` and `/dist` directories
+   - build GOV.UK Frontend into the [`/package`](/package) and [`/dist`](/dist) directories
    - commit the changes
    - push a branch to GitHub
 

docs/releasing/publishing.md

@@ -14,7 +14,7 @@ Developers should pair on releases. When remote working, it can be useful to be
 
 4. Create and check out a new branch (`release-[version-number]`). See the [versioning documentation](/docs/contributing/versioning.md) for more information.
 
-5. Update the [`CHANGELOG.md`](../../CHANGELOG.md) by:
+5. Update the [`CHANGELOG.md`](/CHANGELOG.md) by:
 
    - changing the 'Unreleased' heading to the new version number and release type. For example, '3.11.0 (Feature release)'
    - adding a new 'Unreleased' heading above the new version number and release type, so users will know where to add PRs to the changelog
@@ -26,7 +26,7 @@ Developers should pair on releases. When remote working, it can be useful to be
    npm version <NEW VERSION NUMBER> --no-git-tag-version --workspace package
    ```
 
-   This step will update the `package.json` and project `package-lock.json` files.
+   This step will update the [`package.json`](/package.json) and project [`package-lock.json`](/package-lock.json) files.
 
    Do not commit the changes.
 
@@ -36,11 +36,11 @@ Developers should pair on releases. When remote working, it can be useful to be
    npx update-browserslist-db@latest
    ```
 
-   This step will update the project `package-lock.json` file if updates are found.
+   This step will update the project [`package-lock.json`](/package-lock.json) file if updates are found.
 
 8. Run `npm run build-release` to:
 
-   - build GOV.UK Frontend into the `/package` and `/dist` directories
+   - build GOV.UK Frontend into the [`/package`](/package) and [`/dist`](/dist) directories
    - commit the changes
    - push a branch to GitHub