Skip JSDoc, SassDoc, Rollup stats during dev, add ESLint

.github/workflows/actions/build/action.yml

@@ -25,6 +25,5 @@ runs:
       if: steps.build-cache.outputs.cache-hit != 'true'
       shell: bash
 
-      # Build all workspaces but skip `postbuild` scripts
-      # since we run these in other workflow steps instead
-      run: npm run build --workspaces --if-present --ignore-scripts
+      # Build all workspaces
+      run: npm run build --workspaces --if-present

.github/workflows/tests.yml

@@ -96,7 +96,7 @@ jobs:
 
           - description: TypeScript compiler
             name: lint-types
-            run: npm run lint:types -- --incremental
+            run: npm run lint:types -- --incremental --pretty
             cache: '**/*.tsbuildinfo'
 
     steps:
@@ -218,11 +218,11 @@ jobs:
         task:
           - description: Verify package build
             name: test-build-package
-            run: npm run build:package -- --ignore-scripts
+            run: npm run build:package
 
           - description: Verify distribution build
             name: test-build-release
-            run: npm run build:release -- --ignore-scripts
+            run: npm run build:release
 
     steps:
       - name: Checkout

docs/contributing/tasks.md

@@ -25,6 +25,10 @@ npm scripts are defined in `package.json`. These trigger a number of Gulp tasks.
 - run tasks from `npm run build:package`
 - run tasks from `npm run build:app`
 
+**`npm run clean` will do the following:**
+
+- clean the `./dist` folder from all workspaces
+
 **`npm run build:app` will trigger `npm run build --workspace @govuk-frontend/review` that will:**
 
 - clean the `./packages/govuk-frontend-review/dist` folder

docs/examples/webpack/package.json

@@ -4,7 +4,9 @@
   "description": "Boilerplate example for govuk-frontend using webpack",
   "scripts": {
     "dev": "webpack serve --progress --mode development",
-    "build": "webpack --progress --mode production"
+    "prebuild": "npm run clean",
+    "build": "webpack --progress --mode production",
+    "clean": "del-cli dist"
   },
   "dependencies": {
     "govuk-frontend": "*"

jest.config.mjs

@@ -48,7 +48,7 @@ const config = {
 
     // Transform some `*.js` to compatible CommonJS
     ...Object.fromEntries(
-      ['del', 'slash'].map((packagePath) => [
+      ['slash'].map((packagePath) => [
         replacePathSepForRegex(`${packageResolveToPath(packagePath)}$`),
         [
           'babel-jest',
@@ -63,7 +63,7 @@ const config = {
   // Enable Babel transforms for ESM-only node_modules
   // See: https://jestjs.io/docs/ecmascript-modules
   transformIgnorePatterns: [
-    `<rootDir>/node_modules/(?!${['del', 'slash'].join('|')}/)`
+    `<rootDir>/node_modules/(?!${['slash'].join('|')}/)`
   ]
 }
 

package.json

@@ -20,7 +20,7 @@
     "build-release": "./bin/build-release.sh",
     "publish-release": "./bin/publish-release.sh",
     "publish-preview": "./bin/publish-preview.sh",
-    "predev": "npm run build",
+    "predev": "npm run build -- --ignore-scripts",
     "dev": "concurrently \"npm run dev --workspace @govuk-frontend/review\" \"npm run dev --workspace govuk-frontend\" --kill-others --names \"app,pkg\" --prefix-colors \"red.dim,blue.dim\"",
     "build": "npm run build --workspace govuk-frontend --workspace @govuk-frontend/review",
     "build:app": "cross-env-shell NODE_ENV=production npm run build --workspace @govuk-frontend/review",
@@ -29,7 +29,8 @@
     "build:types": "npm run build:types --workspaces --if-present",
     "postbuild:package": "jest --color --selectProjects \"Build tasks\" --testMatch \"**/build/package.unit.test.mjs\"",
     "postbuild:release": "jest --color --selectProjects \"Build tasks\" --testMatch \"**/build/release.unit.test.mjs\"",
-    "heroku-postbuild": "npm run build -- --ignore-scripts",
+    "clean": "npm run clean --workspaces --if-present",
+    "heroku-postbuild": "npm run build",
     "postheroku-postbuild": "NPM_CONFIG_PRODUCTION=true npm ci --ignore-scripts --omit=optional --workspace @govuk-frontend/review",
     "pretest": "npm run build",
     "test": "jest --color --ignoreProjects \"Build tasks\" --maxWorkers=50%",
@@ -56,6 +57,7 @@
     "@typescript-eslint/parser": "^6.7.0",
     "concurrently": "^8.2.1",
     "cross-env": "^7.0.3",
+    "del-cli": "^5.1.0",
     "editorconfig-checker": "^5.1.1",
     "eslint": "^8.49.0",
     "eslint-config-prettier": "^9.0.0",

packages/govuk-frontend-review/gulpfile.mjs

@@ -3,7 +3,7 @@ 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'
+import { styles } from './tasks/index.mjs'
 
 /**
  * Build target tasks
@@ -14,7 +14,6 @@ gulp.task('dev', build.dev(options))
 /**
  * Utility tasks
  */
-gulp.task('scripts', scripts(options))
 gulp.task('styles', styles(options))
 
 /**

packages/govuk-frontend-review/nodemon.json

@@ -1,6 +1,7 @@
 {
   "watch": [
     "./src",
+    "./dist/**/index.html",
     "../govuk-frontend/dist/govuk/**/*.json",
     "../../shared/config",
     "../../shared/lib",

packages/govuk-frontend-review/package.json

@@ -10,11 +10,13 @@
   "license": "MIT",
   "scripts": {
     "dev": "gulp dev --color",
+    "prebuild": "npm run clean",
     "build": "gulp build --color",
     "build:sassdoc": "sassdoc --config sassdoc.config.yaml ../govuk-frontend/src/govuk",
     "build:types": "tsc --build tsconfig.build.json",
     "build:jsdoc": "typedoc",
-    "postbuild": "npm run build:types",
+    "postbuild": "npm run build:jsdoc && npm run build:sassdoc",
+    "clean": "del-cli dist",
     "proxy": "browser-sync start --config browsersync.config.js",
     "serve": "nodemon",
     "start": "node src/start.mjs",

packages/govuk-frontend-review/src/app.mjs

@@ -1,11 +1,13 @@
+import { join } from 'path'
+
 import { paths } from '@govuk-frontend/config'
 import {
   getComponentsFixtures,
   getComponentNames,
   getComponentNamesFiltered,
   renderComponent
 } from '@govuk-frontend/lib/components'
-import { filterPath } from '@govuk-frontend/lib/files'
+import { filterPath, hasPath } from '@govuk-frontend/lib/files'
 import { getStats, modulePaths } from '@govuk-frontend/stats'
 import express from 'express'
 
@@ -48,7 +50,12 @@ export default async () => {
   // Feature flags
   const flags = /** @type {FeatureFlags} */ ({
     isDeployedToHeroku: !!process.env.HEROKU_APP,
-    isDevelopment: !['test', 'production'].includes(process.env.NODE_ENV)
+    isDevelopment: !['test', 'production'].includes(process.env.NODE_ENV),
+
+    // Check for JSDoc, SassDoc and Rollup stats
+    hasDocsScripts: await hasPath(join(paths.app, 'dist/docs/jsdoc')),
+    hasDocsStyles: await hasPath(join(paths.app, 'dist/docs/sassdoc')),
+    hasStats: await hasPath(join(paths.stats, 'dist'))
   })
 
   // Set up Express.js
@@ -213,4 +220,7 @@ export default async () => {
  * @typedef {object} FeatureFlags
  * @property {boolean} isDeployedToHeroku - Review app using `HEROKU_APP`
  * @property {boolean} isDevelopment - Review app not using `NODE_ENV` production or test
+ * @property {boolean} hasDocsStyles - Stylesheets documentation (SassDoc) is available
+ * @property {boolean} hasDocsScripts - JavaScripts documentation (JSDoc) is available
+ * @property {boolean} hasStats - Rollup stats are available
  */

packages/govuk-frontend-review/src/views/index.njk

@@ -61,6 +61,7 @@
 
   </div>
 
+  {% if flags.hasDocsStyles or flags.hasDocsScripts %}
   <div class="govuk-grid-row">
 
     <div class="govuk-grid-column-two-thirds-from-desktop">
@@ -69,6 +70,7 @@
 
       <div class="govuk-grid-row">
 
+        {% if flags.hasDocsStyles %}
         <div class="govuk-grid-column-one-half">
           <h3 class="govuk-heading-m govuk-!-margin-bottom-2">Sass API reference</h3>
           <ul class="govuk-list">
@@ -78,18 +80,23 @@
             <li><a href="https://frontend.design-system.service.gov.uk/sass-api-reference/" class="govuk-link">Latest release</a></li>
           </ul>
         </div>
+        {% endif %}
 
+        {% if flags.hasDocsScripts %}
         <div class="govuk-grid-column-one-half">
           <h3 class="govuk-heading-m govuk-!-margin-bottom-2">JavaScript API reference</h3>
           <ul class="govuk-list">
             <li><a href="/docs/javascript" class="govuk-link">Local version</a></li>
           </ul>
         </div>
+        {% endif %}
 
       </div>
     </div>
   </div>
+  {% endif %}
 
+  {% if flags.hasStats %}
   <div class="govuk-grid-row">
     <div class="govuk-grid-column-two-thirds-from-desktop">
       <hr class="govuk-section-break govuk-section-break--xl govuk-section-break--visible">
@@ -138,4 +145,5 @@
       }) }}
     </div>
   </div>
+  {% endif %}
 {% endblock %}

packages/govuk-frontend-review/tasks/build/dist.mjs

@@ -1,7 +1,7 @@
-import { files, task } from '@govuk-frontend/tasks'
+import { npm } from '@govuk-frontend/tasks'
 import gulp from 'gulp'
 
-import { scripts, styles } from '../index.mjs'
+import { styles } from '../index.mjs'
 
 /**
  * Build review app task
@@ -10,8 +10,4 @@ import { scripts, styles } from '../index.mjs'
  * @type {import('@govuk-frontend/tasks').TaskFunction}
  */
 export default (options) =>
-  gulp.series(
-    task.name('clean', () => files.clean('*', options)),
-
-    gulp.parallel(scripts(options), styles(options))
-  )
+  gulp.series(npm.script('clean', [], options), styles(options))

packages/govuk-frontend-review/tasks/index.mjs

@@ -1,6 +1,5 @@
 /**
  * Build tasks
  */
-export { compile as scripts } from './scripts.mjs'
 export { compile as styles } from './styles.mjs'
 export { watch } from './watch.mjs'

packages/govuk-frontend-review/tasks/styles.mjs

@@ -1,11 +1,10 @@
 import { join } from 'path'
 
-import { npm, styles, task } from '@govuk-frontend/tasks'
+import { styles, task } from '@govuk-frontend/tasks'
 import gulp from 'gulp'
 
 /**
  * Stylesheets task (for watch)
- * Compilation, documentation
  *
  * @type {import('@govuk-frontend/tasks').TaskFunction}
  */
@@ -24,8 +23,5 @@ export const compile = (options) =>
           return join(dir, `${name}.min.css`)
         }
       })
-    ),
-
-    // Build SassDoc for /docs/sass
-    npm.script('build:sassdoc', [], options)
+    )
   )

packages/govuk-frontend-review/tasks/watch.mjs

@@ -5,7 +5,7 @@ import { npm, task } from '@govuk-frontend/tasks'
 import gulp from 'gulp'
 import slash from 'slash'
 
-import { scripts, styles } from './index.mjs'
+import { styles } from './index.mjs'
 
 /**
  * Watch task
@@ -22,7 +22,9 @@ export const watch = (options) =>
      */
     task.name('lint:scss watch', () =>
       gulp.watch(
-        [`${slash(paths.app)}/src/**/*.scss`],
+        [join(options.srcPath, '**/*.scss')],
+
+        // Run Stylelint checks
         npm.script('lint:scss:cli', [
           slash(join(options.workspace, '**/*.scss'))
         ])
@@ -35,24 +37,30 @@ export const watch = (options) =>
     task.name('compile:scss watch', () =>
       gulp.watch(
         [
-          `${slash(paths.app)}/sassdoc.config.yaml`,
-          `${slash(paths.app)}/src/**/*.scss`,
-          `${slash(paths.package)}/dist/govuk/all.scss`
+          join(options.srcPath, '**/*.scss'),
+          join(paths.package, 'dist/govuk/all.scss')
         ],
+
+        // Run Sass compile
         styles(options)
       )
     ),
 
     /**
-     * JavaScripts build watcher
+     * JavaScripts lint watcher
      */
-    task.name('compile:js watch', () =>
+    task.name('lint:js watch', () =>
       gulp.watch(
-        [
-          `${slash(paths.app)}/typedoc.config.js`,
-          `${slash(paths.package)}/dist/govuk/**/*.mjs`
-        ],
-        scripts(options)
+        [join(options.srcPath, '**/*.{cjs,js,mjs}')],
+        gulp.parallel(
+          // Run TypeScript compiler
+          npm.script('build:types', ['--incremental', '--pretty'], options),
+
+          // Run ESLint checks
+          npm.script('lint:js:cli', [
+            slash(join(options.workspace, '**/*.{cjs,js,mjs}'))
+          ])
+        )
       )
     )
   )