simplfy method to copy transformation to /docs; extract logging

Extract the logging so that it if later we want to turn it on/off with a --verbose flag

src/docs.mts

@@ -68,40 +68,59 @@ const prepareOutFile = (file: string): string => {
 };
 
 /**
- * Verify that a file was changed and (potentially) write the new contents out to the file. Log a message to the console
+ * Log messages to the console showing if the transformed file copied to the final documentation
- * If the file was not changed, do nothing. (No message is logged to the console.)
+ * directory or still needs to be copied.
  *
- * @param file {string} name of the file that will be verified
+ * @param {string} filename Name of the file that was transformed
- * @param content {string} new contents for the file
+ * @param {boolean} wasCopied Whether or not the file was copied
  */
-const verifyAndCopy = (file: string, content?: string) => {
+const logWasOrShouldBeTransformed = (filename: string, wasCopied: boolean) => {
-  const outFile = prepareOutFile(file);
+  let changeMsg: string;
-  const existingBuffer = existsSync(outFile) ? readFileSync(outFile) : Buffer.from('#NEW FILE#');
+  let logMsg: string;
-  const newBuffer = content ? Buffer.from(content) : readFileSync(file);
+  changeMsg = wasCopied ? LOGMSG_TRANSFORMED : LOGMSG_TO_BE_TRANSFORMED;
-  if (existingBuffer.equals(newBuffer)) {
+  logMsg = `  File ${changeMsg}: ${filename}`;
-    // Files are same, skip.
+  if (wasCopied) {
-    return;
+    logMsg += LOGMSG_COPIED;
-  }
-  let changeMsg = 'changed';
-  if (verifyOnly) {
-    changeMsg = 'to be changed';
-  }
-  let logMsg = `  File ${changeMsg}: ${outFile}`;
-
-  filesWereChanged = true;
-  if (!verifyOnly) {
-    writeFileSync(outFile, newBuffer);
-    logMsg += ' ...and copied to /docs';
   }
   console.log(logMsg);
 };
 
+/**
+ * If the file contents were transformed, set the _filesWereTransformed_ flag to true and copy the
+ * transformed contents to the final documentation directory if the doCopy flag is true. Log
+ * messages to the console.
+ *
+ * @param {string} file Name of the file that will be verified
+ * @param {string} [transformedContent] New contents for the file
+ * @param {boolean} [doCopy=false] Whether we should copy that transformedContents to the final
+ *   documentation directory. Default is `false`
+ */
+const copyTransformedContents = (
+  file: string,
+  transformedContent?: string,
+  doCopy: boolean = false
+) => {
+  const outFile = prepareOutFile(file);
+  const existingBuffer = existsSync(outFile) ? readFileSync(outFile) : Buffer.from('#NEW FILE#');
+  const newBuffer = transformedContent ? Buffer.from(transformedContent) : readFileSync(file);
+  if (existingBuffer.equals(newBuffer)) {
+    return; // Files are same, skip.
+  }
+
+  filesWereTransformed = true;
+  if (doCopy) {
+    writeFileSync(outFile, newBuffer);
+  }
+  logWasOrShouldBeTransformed(outFile, doCopy);
+};
+
 const readSyncedUTF8file = (file: string): string => {
   return readFileSync(file, 'utf8');
 };
 
 /**
  * Transform a markdown file and write the transformed file to the directory for published documentation
+ *
  * 1. Add a `mermaid-example` block before every `mermaid` or `mmd` block On the docsify site (one
  *    place where the documentation is published), this will show the code used for the mermaid diagram
  * 2. Add the text that says the file is automatically generated
@@ -125,7 +144,7 @@ const transformMarkdown = (file: string) => {
   // Add the AUTOGENERATED_TEXT to the start of the file
   const transformed = `${AUTOGENERATED_TEXT}\n${remark.stringify(out)}`;
 
-  verifyAndCopy(
+  copyTransformedContents(
     file,
     prettier.format(transformed, {
       parser: 'markdown',
@@ -140,6 +159,7 @@ const transformMarkdown = (file: string) => {
 
 /**
  * Transform an HTML file and write the transformed file to the directory for published documentation
+ *
  * - Add the text that says the file is automatically generated Verify that the file has been changed
  *   and write out the changes
  *
@@ -161,10 +181,10 @@ const transformHtml = (filename: string) => {
     const rootElement = htmlDoc.documentElement;
     rootElement.prepend(autoGeneratedComment);
     return jsdom.serialize();
-  }
+  };
 
   const transformedHTML = insertAutoGeneratedComment(filename);
-  verifyAndCopy(filename, transformedHTML);
+  copyTransformedContents(filename, transformedHTML);
 };
 
 /** Main method (entry point) */
@@ -187,9 +207,10 @@ const transformHtml = (filename: string) => {
     dot: includeFilesStartingWithDot,
   });
   otherFiles.forEach((file) => {
-    verifyAndCopy(file);
+    copyTransformedContents(file);
   });
-  if (filesWereChanged) {
+
+  if (filesWereTransformed) {
     if (verifyOnly) {
       console.log(WARN_DOCSDIR_DOESNT_MATCH);
       process.exit(1);