chore(ci): check that docs are up to date in ci

When we accidentally edit the auto-generated portions of the docs, this
will catch the error and cause CI to fail.

Later phase automated safety check that the early-stage human commenting
in the last commit also addresses.

Re: #3654
Re: #3630

PR-URL: #3655
Credit: @isaacs
Close: #3655
Reviewed-by: @nlf

.github/workflows/ci.yml

@@ -20,7 +20,24 @@ jobs:
         run: node . run posttest
         env:
           DEPLOY_VERSION: testing
-
+
+  check_docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Use Node.js 14.x
+        uses: actions/setup-node@v1
+        with:
+          node-version: 14.x
+      - name: Install dependencies
+        run: |
+          node . install --ignore-scripts --no-audit
+      - name: Rebuild the docs
+        run: make freshdocs
+      - name: Git should not be dirty
+        run: node scripts/git-dirty.js
+
+
   licenses:
     runs-on: ubuntu-latest
     steps:

Makefile

@@ -76,6 +76,12 @@ docs/content/using-npm/config.md: scripts/config-doc.js lib/utils/config/*.js
 docs/content/commands/npm-%.md: lib/%.js scripts/config-doc-command.js lib/utils/config/*.js
 	node scripts/config-doc-command.js $@ $<
 
+freshdocs:
+	touch lib/utils/config/definitions.js
+	touch scripts/config-doc-command.js
+	touch scripts/config-doc.js
+	make docs
+
 test: dev-deps
 	node bin/npm-cli.js test
 
@@ -109,4 +115,4 @@ publish: gitclean ls-ok link test smoke-tests docs prune
 release: gitclean ls-ok docs prune
 	@bash scripts/release.sh
 
-.PHONY: all latest install dev link docs clean uninstall test man docs-clean docsclean release ls-ok dev-deps prune
+.PHONY: all latest install dev link docs clean uninstall test man docs-clean docsclean release ls-ok dev-deps prune freshdocs

scripts/git-dirty.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+const { spawnSync } = require('child_process')
+const changes = spawnSync('git', ['status', '--porcelain', '-uno'])
+const stdout = changes.stdout.toString('utf8')
+const stderr = changes.stderr.toString('utf8')
+const { status, signal } = changes
+console.log(stdout)
+console.error(stderr)
+if (status || signal) {
+  console.error({ status, signal })
+  process.exitCode = status || 1
+}
+if (stdout.trim() !== '')
+  throw new Error('git dirty')
+else
+  console.log('git clean')