minor cleanup, clarify var names, add @todos

src/docs.mts

@@ -20,13 +20,18 @@
  *   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 with globby. 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';
@@ -35,36 +40,35 @@ import { exec } from 'child_process';
 // @ts-ignore
 import prettier from 'prettier';
 
-const SOURCE_DOCS_DIR = 'src/docs/';
+const SOURCE_DOCS_DIR = 'src/docs';
-const FINAL_DOCS_DIR = '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 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 LOGMSG_COPIED = ` ...and copied to ${FINAL_DOCS_DIR}`;
 
-const WARN_DOCSDIR_DOESNT_MATCH =
+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.`;
-  "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 verifyOnly: boolean = process.argv.includes('--verify');
-const git = process.argv.includes('--git');
+const git: boolean = process.argv.includes('--git');
 
 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
+ * Create the destination path if it does not already exist.
- * lint-staged to only copy files that have changed
  *
  * @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 changeToFinalDocDir = (file: string): string => {
-  const outFile = join(FINAL_DOCS_DIR, file.replace(SOURCE_DOCS_DIR, ''));
+  const newDir = file.replace(SOURCE_DOCS_DIR, FINAL_DOCS_DIR);
-  mkdirSync(dirname(outFile), { recursive: true });
+  mkdirSync(dirname(newDir), { recursive: true });
-  return outFile;
+  return newDir;
 };
 
 /**
@@ -100,8 +104,10 @@ const copyTransformedContents = (
   transformedContent?: string,
   doCopy: boolean = false
 ) => {
-  const outFile = prepareOutFile(file);
+  const fileInFinalDocDir = changeToFinalDocDir(file);
-  const existingBuffer = existsSync(outFile) ? readFileSync(outFile) : Buffer.from('#NEW FILE#');
+  const existingBuffer = existsSync(fileInFinalDocDir)
+    ? readFileSync(fileInFinalDocDir)
+    : Buffer.from('#NEW FILE#');
   const newBuffer = transformedContent ? Buffer.from(transformedContent) : readFileSync(file);
   if (existingBuffer.equals(newBuffer)) {
     return; // Files are same, skip.
@@ -109,7 +115,7 @@ const copyTransformedContents = (
 
   filesWereTransformed = true;
   if (doCopy) {
-    writeFileSync(outFile, newBuffer);
+    writeFileSync(fileInFinalDocDir, newBuffer);
   }
   logWasOrShouldBeTransformed(fileInFinalDocDir, doCopy);
 };
@@ -185,7 +191,7 @@ const transformHtml = (filename: string) => {
   };
 
   const transformedHTML = insertAutoGeneratedComment(filename);
-  copyTransformedContents(filename, transformedHTML);
+  copyTransformedContents(filename, transformedHTML, !verifyOnly);
 };
 
 /** Main method (entry point) */