Add verification for doc change

.lintstagedrc.json

@@ -1,6 +1,6 @@
 {
    "src/docs/**": [
-      "yarn build:docs"
+      "yarn docs:build"
    ],
    "*.{js,json,html,md}": [
       "yarn lint:fix"

package.json

@@ -26,8 +26,9 @@
     "build:dev": "webpack --mode development --progress --color",
     "build:prod": "webpack --mode production --progress --color",
     "build": "concurrently \"yarn build:dev\" \"yarn build:prod\"",
-    "build:docs": "ts-node-esm src/docs.mts",
-    "postbuild": "documentation build src/mermaidAPI.ts src/config.ts src/defaultConfig.ts --shallow -f md --markdown-toc false > src/docs/Setup.md; yarn build:docs",
+    "docs:build": "ts-node-esm src/docs.mts",
+    "docs:verify": "ts-node-esm src/docs.mts --verify",
+    "postbuild": "documentation build src/mermaidAPI.ts src/config.ts src/defaultConfig.ts --shallow -f md --markdown-toc false > src/docs/Setup.md; yarn docs:build",
     "build:watch": "yarn build:dev --watch",
     "release": "yarn build",
     "lint": "eslint --cache ./ --ext .js,.json,.html,.md",

src/docs.mts

@@ -7,6 +7,7 @@ import { globby } from 'globby';
 import { join, dirname } from 'path';
 import { exec } from 'child_process';
 
+const verify = process.argv.includes('--verify');
 let fileChanged = false;
 // Possible Improvement: combine with lint-staged to only copy files that have changed
 const prepareOutFile = (file: string): string => {
@@ -17,20 +18,16 @@ const prepareOutFile = (file: string): string => {
 
 const verifyAndCopy = (file: string, content?: string) => {
   const outFile = prepareOutFile(file);
-  const existing = existsSync(outFile) ? readFileSync(outFile) : Buffer.from('#NEW FILE#');
-  if (content !== undefined) {
-    if (!existing.equals(Buffer.from(content))) {
-      console.log(`Updating ${outFile}`);
-      writeFileSync(outFile, content);
-      fileChanged = true;
-    }
-  } else {
-    const newFile = readFileSync(file);
-    if (!existing.equals(newFile)) {
-      console.log(`Copying ${file} to ${outFile}`);
-      writeFileSync(outFile, newFile);
-      fileChanged = true;
-    }
+  const existingBuffer = existsSync(outFile) ? readFileSync(outFile) : Buffer.from('#NEW FILE#');
+  const newBuffer = content ? Buffer.from(content) : readFileSync(file);
+  if (existingBuffer.equals(newBuffer)) {
+    // Files are same, skip.
+    return;
+  }
+  console.log(`File changed: ${outFile}`);
+  fileChanged = true;
+  if (!verify) {
+    writeFileSync(outFile, newBuffer);
   }
 };
 
@@ -61,6 +58,12 @@ const transform = (file: string) => {
     verifyAndCopy(file);
   });
   if (fileChanged) {
+    if (verify) {
+      console.log(
+        "Changes detected in files in `docs`. Please run `yarn docs:build` after making changes to 'src/docs' to update the `docs` folder."
+      );
+      process.exit(1);
+    }
     console.log('Committing changes to the docs folder');
     exec('git add docs');
   }