build: add an npm release command that builds and validates

CONTRIBUTING.md

@@ -20,3 +20,15 @@ docs: trim local setup to the essentials
 ## Build outputs
 
 `imagediff.js` and `imagediff.min.js` are generated by `npm run build` and committed for releases. Rebuild and commit them only when preparing a release; ordinary PRs change `js/imagediff.js` and leave the built files alone. `npm test` runs against the source, including the CLI, so nothing needs rebuilding to test a change.
+
+## Releasing
+
+In the release PR, run:
+
+```sh
+npm run release
+```
+
+It builds `imagediff.js` and `imagediff.min.js` and runs `npm test` against each, through `require` in Node and in a page. Commit the built files once it passes. It doesn't bump the version, tag or publish.
+
+After merging, `npm publish` checks the committed built files again before publishing: it refuses if they differ from what's committed or if the specs fail against them. It doesn't rebuild, so what's published is what's committed.

README.md

@@ -92,6 +92,8 @@ npm test
 * `npm run test:node` runs the specs, including a smoke test of the `imagediff` CLI, in Node.js against [node-canvas](https://github.com/Automattic/node-canvas) (the optional `canvas` dependency, which `npm ci` installs from prebuilt binaries on common platforms).
 * `npm run test:browser` runs the specs in headless Chromium with Playwright.
 * `npm run test:serve` serves the specs at http://localhost:8085/spec/ to watch them run in a browser.
+* `IMAGEDIFF_LIBRARY=imagediff.min.js npm test` runs the same specs against a built file (a path from the repository root) instead of the source: through `require` in Node and as a `<script>` global in Chromium. `npm run test:built` does this for `imagediff.js` and then `imagediff.min.js`.
+* `npm run release` builds the release files and then runs `npm run test:built`, leaving them ready to commit. `npm publish` runs `npm run test:built` first (without rebuilding) and refuses to publish if it fails or if the built files differ from what's committed. See [CONTRIBUTING.md](CONTRIBUTING.md#releasing).
 * `npm run build` (or `make imagediff`) writes `imagediff.js` (license header + `js/imagediff.js`) and `imagediff.min.js`, minified with [terser](https://terser.org/) to ES5 output. Run it only when preparing a release; see [CONTRIBUTING.md](CONTRIBUTING.md#build-outputs).
 
 ### Dev container

package.json

@@ -9,8 +9,11 @@
   "homepage": "http://HumbleSoftware.github.com/js-imagediff/",
   "scripts": {
     "build": "node make/build.js",
+    "prepublishOnly": "git diff --exit-code --stat HEAD -- imagediff.js imagediff.min.js && npm run test:built",
+    "release": "npm run build && npm run test:built",
     "test": "npm run test:node && npm run test:browser",
     "test:browser": "playwright test --config=spec/playwright.config.js",
+    "test:built": "IMAGEDIFF_LIBRARY=imagediff.js npm test && IMAGEDIFF_LIBRARY=imagediff.min.js npm test",
     "test:node": "jasmine --config=./spec/jasmine.json",
     "test:serve": "node spec/server.js"
   },

spec/ImageDiffSpec.js

@@ -1,6 +1,10 @@
 var isNode    = typeof module !== 'undefined';
 var Canvas    = isNode && require('canvas');
-var imagediff = imagediff || require('../js/imagediff.js');
+// IMAGEDIFF_LIBRARY (a path from the repository root) tests a built file
+// instead of the source, e.g. IMAGEDIFF_LIBRARY=imagediff.min.js npm test.
+var imagediff = imagediff || require(
+  require('path').join(__dirname, '..', process.env.IMAGEDIFF_LIBRARY || 'js/imagediff.js')
+);
 
 describe('ImageUtils', function() {
 

spec/LoadSpec.js

@@ -1,12 +1,13 @@
-// Loads the library source in a fresh Node process, the way bundlers and
-// installs without the optional `canvas` dependency see it.
+// Loads the library source (or the build in IMAGEDIFF_LIBRARY) in a fresh
+// Node process, the way bundlers and installs without the optional `canvas`
+// dependency see it.
 var
   childProcess = require('child_process'),
   path = require('path');
 
 describe('loading imagediff', function () {
 
-  var LIBRARY = path.join(__dirname, '..', 'js', 'imagediff.js');
+  var LIBRARY = path.join(__dirname, '..', process.env.IMAGEDIFF_LIBRARY || 'js/imagediff.js');
 
   // Runs `body` in a child process with `canvas` unresolvable and calls back
   // with the JSON it prints.

spec/browser/jasmine.spec.js

@@ -1,12 +1,15 @@
 // Runs the Jasmine specs in spec/index.html and reports each failed spec.
+// IMAGEDIFF_LIBRARY (a path from the repository root) loads a built file
+// instead of the source.
 var test = require('@playwright/test').test;
 var expect = require('@playwright/test').expect;
 
 test('jasmine specs pass in the browser', async function ({ page }) {
   var errors = [];
   page.on('pageerror', function (error) { errors.push(error.message); });
 
-  await page.goto('/spec/');
+  var library = process.env.IMAGEDIFF_LIBRARY;
+  await page.goto('/spec/' + (library ? '?lib=' + encodeURIComponent(library) : ''));
   await page.waitForFunction(function () {
     return window.specResults && window.specResults.done;
   });

spec/index.html

@@ -23,7 +23,11 @@
       jasmineDone: function (result) { window.specResults.done = result; }
     });
   </script>
-  <script src="js/imagediff.js"></script>
+  <script>
+    // ?lib= loads a built file instead of the source (see IMAGEDIFF_LIBRARY).
+    var lib = /[?&]lib=([^&]*)/.exec(window.location.search);
+    document.write('<script src="' + (lib ? decodeURIComponent(lib[1]) : 'js/imagediff.js') + '"><\/script>');
+  </script>
   <script src="spec/ImageDiffSpec.js"></script>
 </head>
 <body>