[DOP-4033]: Add comments

config/default.json

@@ -33,7 +33,6 @@
   "featureFlagUpdatePages": "false",
   "featureFlagSearchUI": "false",
   "gatsbyUseChatbot": "false",
-  "gatsbyHideUnifiedFooterLocale": "true",
   "parallel": {
     "enabled": true,
     "stg": {

src/commands/src/helpers/execution-helper.ts → src/commands/src/helpers/dependency-helpers.ts

@@ -34,10 +34,13 @@ async function createEnvProdFile(repoDir: string, projectName: string, baseUrl:
 }
 
 export async function getCliBuildDependencies(repoName: string, projectName: string, baseUrl: string) {
+  // before we get build dependencies, we need to clone
+  // the repo
   await cloneRepo(repoName);
 
   const repoDir = getRepoDir(repoName);
 
+  // doing these in parallel
   const commandPromises = [
     getCommitHash(repoDir),
     getCommitBranch(repoDir),
@@ -46,12 +49,13 @@ export async function getCliBuildDependencies(repoName: string, projectName: str
     createEnvProdFile(repoDir, projectName, baseUrl),
   ];
 
-  const deps = await Promise.all(commandPromises);
+  const dependencies = await Promise.all(commandPromises);
+
   return {
-    commitHash: deps[0] as string,
-    commitBranch: deps[1] as string,
-    patchId: deps[2] as string | undefined,
-    hasRedirects: deps[3] as boolean,
+    commitHash: dependencies[0] as string,
+    commitBranch: dependencies[1] as string,
+    patchId: dependencies[2] as string | undefined,
+    hasRedirects: dependencies[3] as boolean,
     bundlePath: `${repoDir}/bundle.zip`,
     repoDir,
   };

src/commands/src/helpers/index.ts

@@ -111,6 +111,20 @@ export async function executeAndPipeCommands(
     });
   });
 }
+
+/**
+ * A promisified way to execute CLI commands. This approach uses spawn instead of exec, which
+ * is a safer way of executing CLI commands. Also, spawn allows us to stream output in real-time.
+ * @param {string} command: The CLI command we want to execute
+ * @param {string[] | undefined} args: Arguments we want to provide to the command
+ * @param {SpawnOptions | undefined} options: Options to configure the spawn process
+ * @param {fs.WriteStream | undefined} writeStream: A writable stream object to pipe output to.
+ * For example, we can mimic ls >> directory.txt by creating a WriteStream object to write to
+ * directory.txt, and then provide the WriteStream so that we can pipe the output from the ls
+ * command to the WriteStream.
+ * @returns {Promise<CliCommandResponse>} An object containing the CLI output from stdout and stderr.
+ * stdout is the outputText property, and stderr is the errorText property.
+ */
 export async function executeCliCommand({
   command,
   args = [],

src/commands/src/shared/next-gen-deploy.ts

@@ -9,14 +9,12 @@ interface NextGenDeployParams {
 }
 
 export async function nextGenDeploy({ bucket, mutPrefix, gitBranch, hasConfigRedirects, url }: NextGenDeployParams) {
-  // const hasConfigRedirects = await existsAsync(path.join(process.cwd(), 'config/redirects'));
-
   if (hasConfigRedirects && (gitBranch === 'main' || gitBranch === 'master')) {
-    // mut-redirects config/redirects -o public/.htaccess
+    // equivalent to: mut-redirects config/redirects -o public/.htaccess
     await executeCliCommand({ command: 'mut-redirects', args: ['config/redirects', '-o', 'public/.htaccess'] });
   }
 
-  // yes | mut-publish public ${BUCKET} --prefix="${MUT_PREFIX}" --deploy --deployed-url-prefix=${URL} --json --all-subdirectories ${ARGS};
+  // equivalent to: yes | mut-publish public ${BUCKET} --prefix="${MUT_PREFIX}" --deploy --deployed-url-prefix=${URL} --json --all-subdirectories ${ARGS};
   const { outputText } = await executeAndPipeCommands(
     { command: 'yes' },
     {

src/entrypoints/localApp.ts

@@ -1,6 +1,6 @@
 import { nextGenParse } from '../commands/src/shared/next-gen-parse';
 import { nextGenHtml } from '../commands/src/shared/next-gen-html';
-import { getCliBuildDependencies } from '../commands/src/helpers/execution-helper';
+import { getCliBuildDependencies } from '../commands/src/helpers/dependency-helpers';
 import { nextGenStage } from '../commands/src/shared/next-gen-stage';
 import { oasPageBuild } from '../commands/src/shared/oas-page-build';
 import { persistenceModule } from '../commands/src/shared/persistence-module';
@@ -20,8 +20,6 @@ async function localApp() {
     baseUrl
   );
 
-  console.log('Hello');
-
   console.log('Begin snooty build...');
   const snootyBuildRes = await nextGenParse({ repoDir, commitHash, patchId });