Merge pull request #3372 from alphagov/build-tasks-gulpfile

Build tasks: Create tasks per target without `--destination`

docs/contributing/tasks.md

@@ -34,7 +34,7 @@ npm scripts are defined in `package.json`. These trigger a number of Gulp tasks.
 **`npm run build:app` will do the following:**
 
 - clean the `./public` folder
-- output files into `./public`, or another location via the `--destination` flag
+- output files into `./public`
 - copy fonts and images
 - run sub tasks from `gulp styles` without StyleLint code quality checks
 - run sub tasks from `gulp scripts` without ESLint code quality checks
@@ -44,7 +44,7 @@ npm scripts are defined in `package.json`. These trigger a number of Gulp tasks.
 **`npm run build:package` will do the following:**
 
 - clean the `./package` folder
-- output files into `./package`, or another location via the `--destination` flag
+- output files into `./package`
 - copy Sass files, applying Autoprefixer via PostCSS
 - copy Nunjucks component template/macro files, including JSON configs
 - copy GOV.UK Prototype Kit config files
@@ -55,7 +55,7 @@ npm scripts are defined in `package.json`. These trigger a number of Gulp tasks.
 **`npm run build:dist` will do the following:**
 
 - clean the `./dist` folder
-- output files into `./dist`, or another location via the `--destination` flag
+- 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
@@ -76,15 +76,15 @@ This task will:
 This task will:
 
 - check Sass code quality via Stylelint (`npm run lint:scss`)
-- compile Sass to CSS into `./public`, or another location via the `--destination` flag
+- compile Sass to CSS into `./public`
 - compile Sass documentation into `./sassdoc`
 
 **`gulp scripts`**
 
 This task will:
 
 - check JavaScript code quality via ESLint (`npm run lint:js`) (using JavaScript Standard Style)
-- compile JavaScript ESM to CommonJS into `./public`, or another location via the `--destination` flag
+- compile JavaScript ESM to CommonJS into `./public`
 - compile JavaScript documentation into `./jsdoc`
 
 ## Express app only

gulpfile.mjs

@@ -1,21 +1,32 @@
+import { join } from 'path'
+
 import gulp from 'gulp'
 import taskListing from 'gulp-task-listing'
 
-import { updateAssetsVersion } from './tasks/asset-version.mjs'
+import { paths, pkg } from './config/index.js'
 import { clean } from './tasks/clean.mjs'
+import { compileConfig } from './tasks/compile-configs.mjs'
 import { compileJavaScripts } from './tasks/compile-javascripts.mjs'
 import { compileStylesheets } from './tasks/compile-stylesheets.mjs'
+import { version } from './tasks/file.mjs'
 import { copyAssets, copyFiles } from './tasks/gulp/copy-to-destination.mjs'
 import { watch } from './tasks/gulp/watch.mjs'
-import { updatePrototypeKitConfig } from './tasks/prototype-kit-config.mjs'
 import { npmScriptTask } from './tasks/run.mjs'
 
 /**
  * Umbrella scripts tasks (for watch)
  * Runs JavaScript code quality checks, documentation, compilation
  */
 gulp.task('scripts', gulp.series(
-  compileJavaScripts,
+  compileJavaScripts('all.mjs', {
+    srcPath: join(paths.src, 'govuk'),
+    destPath: join(paths.public, 'javascripts'),
+
+    filePath (file) {
+      return join(file.dir, `${file.name}.min.js`)
+    }
+  }),
+
   npmScriptTask('build:jsdoc')
 ))
 
@@ -24,7 +35,15 @@ gulp.task('scripts', gulp.series(
  * Runs Sass code quality checks, documentation, compilation
  */
 gulp.task('styles', gulp.series(
-  compileStylesheets,
+  compileStylesheets('**/[!_]*.scss', {
+    srcPath: join(paths.app, 'src/stylesheets'),
+    destPath: join(paths.public, 'stylesheets'),
+
+    filePath (file) {
+      return join(file.dir, `${file.name}.min.css`)
+    }
+  }),
+
   npmScriptTask('build:sassdoc')
 ))
 
@@ -33,8 +52,16 @@ gulp.task('styles', gulp.series(
  * Prepare public folder for review app
  */
 gulp.task('build:app', gulp.series(
-  clean,
-  copyAssets,
+  clean('**/*', {
+    destPath: paths.public
+  }),
+
+  // Copy GOV.UK Frontend static assets
+  copyAssets('**/*', {
+    srcPath: join(paths.src, 'govuk/assets'),
+    destPath: join(paths.public, 'assets')
+  }),
+
   'scripts',
   'styles'
 ))
@@ -44,23 +71,106 @@ gulp.task('build:app', gulp.series(
  * Prepare package folder for publishing
  */
 gulp.task('build:package', gulp.series(
-  clean,
-  copyFiles,
-  compileJavaScripts,
-  compileStylesheets,
-  updatePrototypeKitConfig
+  clean('**/*', {
+    destPath: paths.package,
+    ignore: [
+      '**/package.json',
+      '**/README.md'
+    ]
+  }),
+
+  // Copy GOV.UK Frontend files
+  copyFiles({
+    srcPath: paths.src,
+    destPath: paths.package
+  }),
+
+  // Copy GOV.UK Frontend JavaScript (ES modules)
+  copyAssets('**/!(*.test).mjs', {
+    srcPath: join(paths.src, 'govuk'),
+    destPath: join(paths.package, 'govuk-esm')
+  }),
+
+  // Compile GOV.UK Frontend JavaScript (AMD modules)
+  compileJavaScripts('**/!(*.test).mjs', {
+    srcPath: join(paths.src, 'govuk'),
+    destPath: join(paths.package, 'govuk'),
+
+    filePath (file) {
+      return join(file.dir, `${file.name}.js`)
+    }
+  }),
+
+  // Apply CSS prefixes to GOV.UK Frontend Sass
+  compileStylesheets('**/*.scss', {
+    srcPath: join(paths.src, 'govuk'),
+    destPath: join(paths.package, 'govuk'),
+
+    filePath (file) {
+      return join(file.dir, `${file.name}.scss`)
+    }
+  }),
+
+  // Apply CSS prefixes to GOV.UK Prototype Kit Sass
+  compileStylesheets('init.scss', {
+    srcPath: join(paths.src, 'govuk-prototype-kit'),
+    destPath: join(paths.package, 'govuk-prototype-kit'),
+
+    filePath (file) {
+      return join(file.dir, `${file.name}.scss`)
+    }
+  }),
+
+  // Compile GOV.UK Prototype Kit config
+  compileConfig('govuk-prototype-kit.config.mjs', {
+    srcPath: join(paths.src, 'govuk-prototype-kit'),
+    destPath: paths.package,
+
+    filePath (file) {
+      return join(file.dir, `${file.name}.json`)
+    }
+  })
 ))
 
 /**
  * Build dist task
  * Prepare dist folder for release
  */
 gulp.task('build:dist', gulp.series(
-  clean,
-  copyAssets,
-  compileJavaScripts,
-  compileStylesheets,
-  updateAssetsVersion
+  clean('**/*', {
+    destPath: paths.dist
+  }),
+
+  // Copy GOV.UK Frontend static assets
+  copyAssets('*/**', {
+    srcPath: join(paths.src, 'govuk/assets'),
+    destPath: join(paths.dist, 'assets')
+  }),
+
+  // Compile GOV.UK Frontend JavaScript
+  compileJavaScripts('all.mjs', {
+    srcPath: join(paths.src, 'govuk'),
+    destPath: paths.dist,
+
+    filePath (file) {
+      return join(file.dir, `${file.name.replace(/^all/, pkg.name)}-${pkg.version}.min.js`)
+    }
+  }),
+
+  // Compile GOV.UK Frontend Sass
+  compileStylesheets('**/[!_]*.scss', {
+    srcPath: join(paths.src, 'govuk'),
+    destPath: paths.dist,
+
+    filePath (file) {
+      return join(file.dir, `${file.name.replace(/^all/, pkg.name)}-${pkg.version}.min.css`)
+    }
+  }),
+
+  // Update GOV.UK Frontend version
+  version('VERSION.txt', {
+    destPath: paths.dist
+  })
 ))
 
 /**

lib/file-helper.js

@@ -20,7 +20,6 @@ const getListing = async (directoryPath, pattern = '**/*', options = {}) => {
   const listing = await glob(pattern, {
     absolute: true,
     cwd: directoryPath,
-    matchBase: true,
     nodir: true,
     realpath: true,
     ...options

package.json

@@ -22,9 +22,9 @@
     "pre-release": "./bin/pre-release.sh",
     "build:sassdoc": "sassdoc --config sassdoc.config.yaml ./src/govuk",
     "build:jsdoc": "jsdoc --configure jsdoc.config.js ./src/govuk",
-    "build:app": "gulp build:app --destination \"public\"",
-    "build:package": "gulp build:package --destination \"package\"",
-    "build:dist": "gulp build:dist --destination \"dist\"",
+    "build:app": "gulp build:app",
+    "build:package": "gulp build:package",
+    "build:dist": "gulp build:dist",
     "build:types": "tsc --build",
     "postbuild:package": "jest --color --selectProjects \"Gulp tasks\" --testMatch \"**/*build-package*\"",
     "postbuild:dist": "jest --color --selectProjects \"Gulp tasks\" --testMatch \"**/*build-dist*\"",

tasks/clean.mjs

@@ -3,34 +3,21 @@ import { basename, join } from 'path'
 import { deleteAsync } from 'del'
 import slash from 'slash'
 
-import { destination } from './task-arguments.mjs'
-
-const cleanPath = slash(destination)
-
 /**
- * List path globs to clean for a given destination
+ * Delete path globs for a given destination
  *
- * @param {string} cleanPath - Destination path to clean
- * @returns {string[]} Path globs to clean
+ * @param {string} pattern - Pattern to remove
+ * @param {AssetEntry[1]} options - Asset options
+ * @returns {() => Promise<string[]>} Prepared compile task
  */
-export function paths (cleanPath) {
-  const param = [slash(join(cleanPath, '**/*'))]
-
-  // Preserve package files
-  if (basename(cleanPath) === 'package') {
-    param.push(
-      `!${cleanPath}/`,
-      `!${cleanPath}/package.json`,
-      `!${cleanPath}/govuk-prototype-kit.config.json`,
-      `!${cleanPath}/README.md`
-    )
-  }
+export function clean (pattern, { destPath, ignore }) {
+  const task = () => deleteAsync(slash(join(destPath, pattern)), { ignore })
 
-  return param
-}
+  task.displayName = `clean:${basename(destPath)}`
 
-export function clean () {
-  return deleteAsync(paths(cleanPath))
+  return task
 }
 
-clean.displayName = `clean:${basename(cleanPath)}`
+/**
+ * @typedef {import('./compile-assets.mjs').AssetEntry} AssetEntry
+ */

tasks/compile-assets.mjs

@@ -38,8 +38,18 @@ export async function writeAsset (filePath, result) {
  * Asset options
  *
  * @typedef {object} AssetOptions
- * @property {string} srcPath - Input directory
- * @property {string} destPath - Output directory
+ * @property {string} [srcPath] - Input directory
+ * @property {string} [destPath] - Output directory
+ * @property {AssetFormatter} [filePath] - File path formatter
+ * @property {string[]} [ignore] - File path patterns to ignore
+ */
+
+/**
+ * Asset path formatter
+ *
+ * @callback AssetFormatter
+ * @param {import('path').ParsedPath} file - Parsed file path
+ * @returns {string} Formatted file path
  */
 
 /**