Split out linting gulp tasks

Linting tasks no longer run before assets are built

docs/contributing/tasks.md

@@ -1,31 +1,31 @@
-# 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`
+- compiles component Nunjucks files to `public`
 - copies icons to `public`
-- compile sass files, add vendor prefixes and copy 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 test` will do the following:**
 - compile components to HTML
-- run JS tests
-- run CSS lint checker
+- run JavaScript tests
+- run Sass lint checker
 - run accessibility tests on HTML files
 - run tests on the review application
 
 **`npm run heroku` runs on Heroku build/PR and it:**
 - compiles components' HTML
-- compiles CSS & JS
+- compiles Sass & JavaScript
 - starts up Express
 
 **`npm run build:assets` will do the following:**
@@ -34,19 +34,19 @@ 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
-- compile component nunjucks to HTML
+- 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
+- copy CSS files, add vendor prefixes and replace path to be node_modules consumption compliant
 - 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
+- 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)
+- runs `npm run test:build:dist` (which will test the output is correct)
 
 ## Gulp tasks
 
@@ -57,11 +57,6 @@ 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:
@@ -70,18 +65,21 @@ This task will:
 **`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
+ - Sass code quality checks via Stylelint (`gulp scss:lint`)
+ - Sass compilation (`gulp scss:compile`) to a destination folder that can be specified via a --destination flag
+ - Sass documentation compilation (`gulp sassdoc:compile`)
 
 **`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:
+ - JavaScript code quality checks via ESLint (`gulp js:lint`) (using JavaScript Standard Style)
+ - concatenate and uglify JavaScript (`gulp js:compile`) to a destination folder that can be specified via a --destination flag
 
-**`gulp compile:components`**
+**`gulp compile`**
 
-  This task will:
-  - compile all `src/govuk/components/componentName/componentName.njk` files to HTML files
+This task will:
+- run sub tasks from `gulp styles` without ESLint code quality checks
+- run sub tasks from `gulp scripts` without StyleLint code quality checks
 
 ## Express app only
 

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,78 +16,95 @@ 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'
+  gulp.parallel(
+    'scss:compile',
+    buildSassdocs
+  )
 ))
 
-// 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)
-// --------------------------------------
-gulp.task('copy-assets', gulp.series(
-  'styles',
-  'scripts'
+/**
+ * Compile task for local & heroku
+ * Runs JavaScript and Sass compilation
+ */
+gulp.task('compile', gulp.series(
+  'js:compile',
+  'scss:compile',
+  buildSassdocs
 ))
 
-// 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 task on start
+ */
 gulp.task('dev', gulp.series(
   cleanPublic,
-  'copy-assets',
-  buildSassdocs,
+  'compile',
   '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',
+  'copy:files',
   'js:compile',
   'js:copy-esm'
 ))
 
+/**
+ * Build dist task
+ * Prepare dist folder for release
+ */
 gulp.task('build:dist', gulp.series(
   cleanDist,
-  'copy-assets',
-  'copy:assets',
+  'copy:files',
+  'js:compile',
   updateDistAssetsVersion
 ))
 
-gulp.task('sassdoc', buildSassdocs)
+/**
+ * Compiles Sass documentation
+ */
+gulp.task('sassdoc:compile', buildSassdocs)
 
-// Default task -------------------------
-// Lists out available tasks.
-// --------------------------------------
+/**
+ * Default task
+ * Lists out available tasks
+ */
 gulp.task('default', taskListing)

package.json

@@ -14,10 +14,10 @@
     "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:assets": "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 lint && npm run build:assets",
     "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*\"",

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}**/*`
   ])
 }
 

tasks/gulp/copy-to-destination.js

@@ -12,7 +12,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(
     gulp.src([
       `${configPaths.src}**/*`,

tasks/gulp/watch.js

@@ -1,11 +1,18 @@
 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
+ * When a file is changed, re-runs the build task
+ */
+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'))
+  ])
+})

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'
   })

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',