Docs: add '..auto generated..' to .html documentation files

src/docs.mts

@@ -1,24 +1,35 @@
 /**
- * @overview Process and potentially transform documentation source files into files suitable for publishing.
- *   Copy files from the source directory (/src/docs) to the directory used for the final, published documentation (/docs).
- *   The list of files changed (transformed) and copied to /docs are logged to the console.
- *   If a file in /src/docs has the same contents in /docs, nothing is done (it is not copied to /docs).
+ * @file Transform documentation source files into files suitable for publishing and optionally copy the transformed files from the source directory
+ *   to the directory used for the final, published documentation directory. The list of files transformed and copied to final documentation directory
+ *   are logged to the console. If a file in the source directory has the same contents in the final directory, nothing is done (the final directory
+ *   is up-to-date).
+ * @example
+ *   docs
+ *   Run with no option flags
  *
- * @example docs
- * @example docs --verify
- *   If the --verify option is used, no files will be copied to /docs, but the list of files to be changed is still shown on the console.
- *   A message to the console will show that this command should be run without the --verify flag so that the 'docs' folder is be updated.
- *   Note that the command will return an exit code (1), which will show that it failed.
- * @example docs --git
- *   If the --git option is used, the command `git add docs` will be run
+ * @example
+ *   docs --verify
+ *   If the --verify option is used, it only _verifies_ that the final directory has been updated with the transformed files in the source directory.
+ *   No files will be copied to the final documentation directory, but the list of files to be changed is shown on the console.
+ *   If the final documentation directory does not have the transformed files from source directory
+ *   - a message to the console will show that this command should be run without the --verify flag so that the final directory is updated, and
+ *   - it will return a fail exit code (1)
  *
+ * @example
+ *   docs --git
+ *   If the --git option is used, the command `git add docs` will be run after all transformations (and/or verifications) have completed successfully
+ *   If not files were transformed, the git command is not run.
+ *
+ * @todo Ensure that the documentation source and final paths are correct by using process.cwd() to get their absolute paths. Ensures that the
+ *   location of those 2 directories is not dependent on where this file resides.
+ *
+ * @todo Write a test file for this. (Will need to be able to deal .mts file. Jest has trouble with it.)
  */
 
 import { remark } from 'remark';
 import type { Code, Root } from 'mdast';
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
 import { JSDOM } from 'jsdom';
-
 // @ts-ignore
 import flatmap from 'unist-util-flatmap';
 import { globby } from 'globby';
@@ -27,70 +38,92 @@ import { exec } from 'child_process';
 // @ts-ignore
 import prettier from 'prettier';
 
-const SOURCE_DOCS_DIR = 'src/docs/';
-const FINAL_DOCS_DIR = 'docs/';
-const AUTOGENERATED_TEXT =
-  '# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.';
+const SOURCE_DOCS_DIR = 'src/docs';
+const FINAL_DOCS_DIR = 'docs';
+
+const AUTOGENERATED_TEXT = `# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in ${SOURCE_DOCS_DIR}.`;
+
+const LOGMSG_TRANSFORMED = 'transformed';
+const LOGMSG_TO_BE_TRANSFORMED = 'to be transformed';
+const LOGMSG_COPIED = ` ...and copied to ${FINAL_DOCS_DIR}`;
+
+const WARN_DOCSDIR_DOESNT_MATCH = `Changed files were transformed in ${SOURCE_DOCS_DIR} but do not match the files in ${FINAL_DOCS_DIR}. Please run yarn docs:build after making changes to ${SOURCE_DOCS_DIR} to update the ${FINAL_DOCS_DIR} directory with the transformed files.`;
 
-const verifyOnly = process.argv.includes('--verify');
-const git = process.argv.includes('--git');
+const verifyOnly: boolean = process.argv.includes('--verify');
+const git: boolean = process.argv.includes('--git');
 
-let filesWereChanged = false;
+let filesWereTransformed = false;
 
 /**
- * Given a source file name and path, return the documentation destination full path and file name
- * Create the destination path if it does not already exist.
- * Possible Improvement: combine with lint-staged to only copy files that have changed
+ * Given a source file name and path, return the documentation destination full path and file name Create the destination path if it does not already exist.
  *
- * @param file {string} name of the file (including full path)
- * @returns {string} name of the file with the path changed from src/docs to docs
+ * @param {string} file - Name of the file (including full path)
+ * @returns {string} Name of the file with the path changed from the source directory to final documentation directory
+ * @todo Possible Improvement: combine with lint-staged to only copy files that have changed
  */
-const prepareOutFile = (file: string): string => {
-  const outFile = join(FINAL_DOCS_DIR, file.replace(SOURCE_DOCS_DIR, ''));
-  mkdirSync(dirname(outFile), { recursive: true });
-  return outFile;
+const changeToFinalDocDir = (file: string): string => {
+  const newDir = file.replace(SOURCE_DOCS_DIR, FINAL_DOCS_DIR);
+  mkdirSync(dirname(newDir), { recursive: true });
+  return newDir;
 };
 
 /**
- * Verify that a file was changed and (potentially) write the new contents out to the file. Log a message to the console
- * If the file was not changed, do nothing. (No message is logged to the console.)
+ * Log messages to the console showing if the transformed file copied to the final documentation directory or still needs to be copied.
  *
- * @param file {string} name of the file that will be verified
- * @param content {string} new contents for the file
+ * @param {string} filename Name of the file that was transformed
+ * @param {boolean} wasCopied Whether or not the file was copied
  */
-const verifyAndCopy = (file: string, content?: string) => {
-  const outFile = prepareOutFile(file);
-  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;
+const logWasOrShouldBeTransformed = (filename: string, wasCopied: boolean) => {
+  let changeMsg: string;
+  let logMsg: string;
+  changeMsg = wasCopied ? LOGMSG_TRANSFORMED : LOGMSG_TO_BE_TRANSFORMED;
+  logMsg = `  File ${changeMsg}: ${filename}`;
+  if (wasCopied) {
+    logMsg += LOGMSG_COPIED;
   }
-  let changeMsg = 'changed';
-  if (verifyOnly) {
-    changeMsg = 'to be changed';
+  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} filename 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 = (
+  filename: string,
+  doCopy: boolean = false,
+  transformedContent?: string
+) => {
+  const fileInFinalDocDir = changeToFinalDocDir(filename);
+  const existingBuffer = existsSync(fileInFinalDocDir)
+    ? readFileSync(fileInFinalDocDir)
+    : Buffer.from('#NEW FILE#');
+  const newBuffer = transformedContent ? Buffer.from(transformedContent) : readFileSync(filename);
+  if (existingBuffer.equals(newBuffer)) {
+    return; // Files are same, skip.
   }
-  let logMsg = `  File ${changeMsg}: ${outFile}`;
 
-  filesWereChanged = true;
-  if (!verifyOnly) {
-    writeFileSync(outFile, newBuffer);
-    logMsg += ' ...and copied to /docs';
+  filesWereTransformed = true;
+  if (doCopy) {
+    writeFileSync(fileInFinalDocDir, newBuffer);
   }
-  console.log(logMsg);
+  logWasOrShouldBeTransformed(fileInFinalDocDir, doCopy);
 };
 
-const readSyncedUTF8file = (file: string): string => {
-  return readFileSync(file, 'utf8');
+const readSyncedUTF8file = (filename: string): string => {
+  return readFileSync(filename, '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
- *   3. use prettier to format the file
- *   Verify that the file has been changed and write out the changes
+ *
+ * 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
+ * 3. Use prettier to format the file Verify that the file has been changed and write out the changes
  *
  * @param file {string} name of the file that will be verified
  */
@@ -110,8 +143,9 @@ 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,
+    !verifyOnly,
     prettier.format(transformed, {
       parser: 'markdown',
       useTabs: false,
@@ -124,9 +158,9 @@ const transformMarkdown = (file: string) => {
 };
 
 /**
- * Transform a 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
+ * 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
  *
  * @param filename {string} name of the HTML file to transform
  */
@@ -135,7 +169,7 @@ const transformHtml = (filename: string) => {
    * Insert the '...auto generated...' comment into an HTML file after the <html> element
    *
    * @param fileName {string} file name that should have the comment inserted
-   * @returns {string} the contents of the file with the comment inserted
+   * @returns {string} The contents of the file with the comment inserted
    */
   const insertAutoGeneratedComment = (fileName: string): string => {
     const fileContents = readSyncedUTF8file(fileName);
@@ -146,35 +180,42 @@ const transformHtml = (filename: string) => {
     const rootElement = htmlDoc.documentElement;
     rootElement.prepend(autoGeneratedComment);
     return jsdom.serialize();
-  }
+  };
 
   const transformedHTML = insertAutoGeneratedComment(filename);
-  verifyAndCopy(filename, transformedHTML);
+  copyTransformedContents(filename, !verifyOnly, transformedHTML);
 };
 
+/** Main method (entry point) */
 (async () => {
+  const sourceDirGlob = join('.', SOURCE_DOCS_DIR, '**');
+  const includeFilesStartingWithDot = true;
+
   console.log('Transforming markdown files...');
-  const mdFiles = await globby(['./src/docs/**/*.md'], { dot: true });
+  const mdFiles = await globby([join(sourceDirGlob, '*.md')], { dot: includeFilesStartingWithDot });
   mdFiles.forEach(transformMarkdown);
 
   console.log('Transforming html files...');
-  const htmlFiles = await globby(['./src/docs/**/*.html'], { dot: true });
+  const htmlFiles = await globby([join(sourceDirGlob, '*.html')], {
+    dot: includeFilesStartingWithDot,
+  });
   htmlFiles.forEach(transformHtml);
 
   console.log('Transforming all other files...');
-  const otherFiles = await globby(['src/docs/**', '!**/*.md', '!**/*.html'], { dot: true });
-  otherFiles.forEach((file) => {
-    verifyAndCopy(file);
+  const otherFiles = await globby([sourceDirGlob, '!**/*.md', '!**/*.html'], {
+    dot: includeFilesStartingWithDot,
   });
-  if (filesWereChanged) {
+  otherFiles.forEach((file: string) => {
+    copyTransformedContents(file, !verifyOnly); // no transformation
+  });
+
+  if (filesWereTransformed) {
     if (verifyOnly) {
-      console.log(
-        "Changes detected in files in `src/docs`. Please run `yarn docs:build` after making changes to 'src/docs' to update the `docs` folder."
-      );
+      console.log(WARN_DOCSDIR_DOESNT_MATCH);
       process.exit(1);
     }
     if (git) {
-      console.log('Adding changes in docs folder to git');
+      console.log('Adding changes in ${FINAL_DOCS_DIR} folder to git');
       exec('git add docs');
     }
   }