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 diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index a1675742a6..4b03b872ac 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -34,9 +34,12 @@ jobs: if: steps.npm-cache.outputs.cache-hit != 'true' run: npm ci + - name: Lint + run: npm run lint + - name: Build run: | - npm run build:assets + npm run build:compile npm run build:package npm run build:dist 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..296ab92f5a 100644 --- a/docs/contributing/tasks.md +++ b/docs/contributing/tasks.md @@ -1,52 +1,49 @@ -# 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 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 **`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:compile` +- start up Express -**`npm run build:assets` will do the following:** -- compiles CSS & JS -- compiles Sass documentation +**`npm run build:compile` will do the following:** +- output files into `./public`, or another location via the `--destination` flag +- compile JavaScript and Sass, including Sass documentation (`gulp compile`) **`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 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) + ## Gulp tasks @@ -57,32 +54,31 @@ 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 (`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: - - 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 (`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 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 +- compile Sass documentation into `./sassdoc` ## 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..82f9d26cbc 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -1,92 +1,100 @@ -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 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 { 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 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', + npmScriptTask('lint:js', ['--silent']), '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', + npmScriptTask('lint:scss', ['--silent']), '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) -// -------------------------------------- -gulp.task('copy-assets', gulp.series( - 'styles', - 'scripts' +/** + * Compile task for local & heroku + * Runs JavaScript and Sass compilation, including Sass documentation + */ +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 tasks 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' )) +/** + * Build dist task + * Prepare dist folder for release + */ gulp.task('build:dist', gulp.series( cleanDist, - 'copy-assets', + 'compile', 'copy:assets', updateDistAssetsVersion )) -gulp.task('sassdoc', buildSassdocs) - -// Default task ------------------------- -// Lists out available tasks. -// -------------------------------------- +/** + * Default task + * Lists out available tasks + */ gulp.task('default', taskListing) 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*\"", 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 d5f537df22..c09390dc22 100644 --- a/tasks/clean.js +++ b/tasks/clean.js @@ -1,28 +1,32 @@ -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}**/*` ]) } +cleanDist.displayName = 'clean:dist' +cleanPackage.displayName = 'clean:package' +cleanPublic.displayName = 'clean:public' + module.exports = { cleanDist, cleanPackage, 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 diff --git a/tasks/gulp/lint.js b/tasks/gulp/lint.js deleted file mode 100644 index 15b422ac61..0000000000 --- a/tasks/gulp/lint.js +++ /dev/null @@ -1,41 +0,0 @@ -const gulp = require('gulp') -const { spawn } = require('child_process') - -/** - * JavaScript code quality checks via ESLint - */ -gulp.task('js:lint', () => { - return runTask('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} 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) - }) -} 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..7a489daf29 100644 --- a/tasks/nodemon.js +++ b/tasks/nodemon.js @@ -1,18 +1,23 @@ 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' }) } -module.exports = runNodemon +runNodemon.displayName = 'nodemon' + +module.exports = { + runNodemon +} 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} 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} 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 +} diff --git a/tasks/sassdoc.js b/tasks/sassdoc.js index 50f7a908f7..8ecee7ebe7 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', @@ -31,4 +31,8 @@ function buildSassdocs () { }) } -module.exports = buildSassdocs +buildSassdocs.displayName = 'sassdoc:compile' + +module.exports = { + buildSassdocs +}