docs: add code documention for some functions called in the index module

Author: stpham

.gitignore

@@ -1 +1,2 @@
 /node_modules/
+.idea/

src/choose-blueprint-updates.js

@@ -5,6 +5,13 @@ const inquirer = require('inquirer');
 const loadSafeBlueprint = require('./load-safe-blueprint');
 const { defaultTo } = require('./constants');
 
+/**
+ * Format the string that is displayed when user is prompted for a blueprint
+ *
+ * @param {object} blueprint - Expected to contain `name` and `version` attributes
+ * @param {string} latestVersion - Latest version for the blueprint
+ * @returns {string}
+ */
 function formatBlueprintLine({
   blueprint,
   latestVersion
@@ -26,6 +33,17 @@ async function chooseBlueprint({
   return choicesByName[answer.blueprint];
 }
 
+/**
+ * Facilitate prompting the user for which bllueprint that want to update
+ *
+ * @param cwd
+ * @param emberCliUpdateJson
+ * @param reset
+ * @param compare
+ * @param codemods
+ * @param to
+ * @returns {Promise<{blueprint: (*|{}), areAllUpToDate, to: string}>}
+ */
 async function chooseBlueprintUpdates({
   cwd,
   emberCliUpdateJson,

src/get-base-blueprint.js

@@ -5,6 +5,16 @@ const downloadPackage = require('./download-package');
 const loadSafeBlueprint = require('./load-safe-blueprint');
 const isDefaultBlueprint = require('./is-default-blueprint');
 
+/**
+ * If the passed in `blueprint` is not the base blueprint, find it. A base blueprint is either
+ * an `addon`, `app`, or `glimmer` blueprint or has the `isBaseBlueprint` boolean set to true.
+ *
+ * @param cwd - Used in `parseBlueprintPackage` to read package.json and find a viable version and normalize url
+ * if it exists
+ * @param blueprints - Find the base blueprint in this array if the passed blueprint is not one
+ * @param blueprint - Figure out if this is a base blueprint
+ * @returns {Promise<*>}
+ */
 async function getBaseBlueprint({
   cwd,
   blueprints,

src/get-blueprint-file-path.js

@@ -9,6 +9,13 @@ async function getBlueprintFilePath(cwd) {
   return path.join(cwd, relative);
 }
 
+/**
+ * Use `config` as the parent directory of `ember-cli-update.json` unless a different config
+ * folder is set in the a `package.json` file at the root of the project directory
+ *
+ * @param {String} cwd - Current working directory path where a `package.json` file could exist
+ * @returns {Promise<string>}
+ */
 async function getBlueprintRelativeFilePath(cwd) {
   let configDir = 'config';
 

src/get-project-options.js

@@ -4,6 +4,14 @@ const path = require('path');
 const fs = require('fs-extra');
 const isDefaultBlueprint = require('./is-default-blueprint');
 
+/**
+ * Determine if project is a `addon`, `app`, or `glimmer` type
+ *
+ * @param {function} checkForDep - Function that will check if dependency exists in `devDependencies` or `dependencies`
+ * attribute of `package.json`
+ * @param {array} keywords - Array of strings of the `keywords` attribute from `package.json`
+ * @returns {string}
+ */
 function getProjectType(checkForDep, keywords) {
   let isAddon = keywords && keywords.indexOf('ember-addon') !== -1;
 
@@ -26,6 +34,15 @@ function getProjectType(checkForDep, keywords) {
   throw new Error('Ember CLI project type could not be determined');
 }
 
+/**
+ * Determine what kind of ember flavor this project is and if it uses yarn or npm
+ *
+ * @param keywords
+ * @param dependencies
+ * @param devDependencies
+ * @param blueprint
+ * @returns {Promise<[string]|string[]>} - Array of strings containing keywords
+ */
 module.exports = async function getProjectOptions({
   keywords,
   dependencies,

src/get-project-version.js

@@ -5,7 +5,16 @@ const _getProjectVersion = require('boilerplate-update/src/get-project-version')
 
 const glimmerVersionCutoff = '0.6.3';
 
+/**
+ * Fine the minimum version from `versions` array that matches the `packageVersion` range string
+ *
+ * @param {string} packageVersion - Can be a version range such as ^1.0.2 or an exact version
+ * @param {array<string>} versions - Array of version strings available for package
+ * @param {object} projectOptions - Glimmer projects are a special case
+ * @returns {string}
+ */
 module.exports = function getProjectVersion(packageVersion, versions, projectOptions) {
+  // _getProjectVersion gets the minimum version that satisfies the given packageVersion string
   let projectVersion = _getProjectVersion(packageVersion, versions);
 
   if (projectOptions.includes('glimmer') && semver.lt(projectVersion, glimmerVersionCutoff)) {

src/get-versions.js

@@ -2,6 +2,15 @@
 
 const npm = require('boilerplate-update/src/npm');
 
+/**
+ * Returns an array of strings i.e.
+ * [
+ *   "0.0.0",
+ *   "3.23.0-beta.2"
+ * ]
+ * @param packageName
+ * @returns {Promise<Array<string>>}
+ */
 module.exports = async function getVersions(packageName) {
   return await npm.json(`view ${packageName} versions`);
 };

src/index.js

@@ -23,6 +23,82 @@ const resolvePackage = require('./resolve-package');
 const { defaultTo } = require('./constants');
 const normalizeBlueprintArgs = require('./normalize-blueprint-args');
 
+/**
+ * Build an object of configurations based on contents of the package containing the blueprint specified
+ * by the user
+ */
+async function setupParamPassedBlueprint(
+  selectedPackageName,
+  selectedBlueprintName,
+  emberCliUpdateJson,
+  fromVersion,
+  cwd
+) {
+  let blueprintArgs = normalizeBlueprintArgs({
+    selectedPackageName,
+    blueprintName: selectedBlueprintName
+  });
+  let parsedPackage = await parseBlueprintPackage({
+    cwd,
+    packageName: blueprintArgs.packageName
+  });
+  let blueprint;
+  let packageUrl = parsedPackage.url;
+  let packageName = parsedPackage.name;
+
+  if (!packageName) {
+    let downloadedPackage = await downloadPackage(null, packageUrl, defaultTo);
+    packageName = downloadedPackage.name;
+  }
+
+  let blueprintName;
+  if (blueprintArgs.blueprintName !== blueprintArgs.packageName) {
+    blueprintName = blueprintArgs.blueprintName;
+  } else {
+    blueprintName = packageName;
+  }
+
+  let existingBlueprint = findBlueprint(emberCliUpdateJson, packageName, blueprintName);
+
+  if (existingBlueprint) {
+    blueprint = existingBlueprint;
+  } else {
+    blueprint = loadSafeBlueprint({
+      packageName,
+      name: blueprintName,
+      location: parsedPackage.location
+    });
+
+    if (isDefaultBlueprint(blueprint)) {
+      blueprint = await loadDefaultBlueprintFromDisk({
+        cwd,
+        version: fromVersion
+      });
+    }
+  }
+
+  if (fromVersion) {
+    blueprint.version = fromVersion;
+  }
+
+  if (!blueprint.version) {
+    throw new Error('A custom blueprint cannot detect --from. You must supply it.');
+  }
+
+  return blueprint;
+}
+
+/**
+ * If `version` attribute exists in the `blueprint` object and URL is empty, skip. Otherwise resolve the details of
+ * the blueprint
+ *
+ * @param {Object} blueprint - Expected to contain `name`, `options` array, `packageName`, `location`, and `version`
+ * attributes
+ * @param {String} url - Optional parameter that links to package
+ * @param {String} range - Version range i.e. 1.0.2
+ * @returns {Promise<void>}
+ * @private
+ */
 async function _resolvePackage(blueprint, url, range) {
   if (blueprint.version && !url) {
     return;
@@ -44,6 +120,16 @@ async function _resolvePackage(blueprint, url, range) {
   }
 }
 
+/**
+ *
+ * @param cwd
+ * @param packageName - User passed package name
+ * @param _blueprint - User passed blueprint name
+ * @param from
+ * @param to
+ * @param resolveConflicts
+ * @returns {Promise<{promise: Promise<*>, resolveConflictsProcess}|{promise: Promise<void>}>}
+ */
 module.exports = async function emberCliUpdate({
   cwd = process.cwd(),
   packageName,
@@ -65,54 +151,13 @@ module.exports = async function emberCliUpdate({
   let packageUrl;
 
   if (_blueprint) {
-    let blueprintArgs = normalizeBlueprintArgs({
+    blueprint = await setupParamPassedBlueprint(
       packageName,
-      blueprintName: _blueprint
-    });
-
-    let parsedPackage = await parseBlueprintPackage({
-      cwd,
-      packageName: blueprintArgs.packageName
-    });
-    packageUrl = parsedPackage.url;
-
-    packageName = parsedPackage.name;
-    if (!packageName) {
-      let downloadedPackage = await downloadPackage(null, packageUrl, defaultTo);
-      packageName = downloadedPackage.name;
-    }
-    let blueprintName;
-    if (blueprintArgs.blueprintName !== blueprintArgs.packageName) {
-      blueprintName = blueprintArgs.blueprintName;
-    } else {
-      blueprintName = packageName;
-    }
-
-    let existingBlueprint = findBlueprint(emberCliUpdateJson, packageName, blueprintName);
-    if (existingBlueprint) {
-      blueprint = existingBlueprint;
-    } else {
-      blueprint = loadSafeBlueprint({
-        packageName,
-        name: blueprintName,
-        location: parsedPackage.location
-      });
-
-      if (isDefaultBlueprint(blueprint)) {
-        blueprint = await loadDefaultBlueprintFromDisk({
-          cwd,
-          version: from
-        });
-      }
-    }
-
-    if (from) {
-      blueprint.version = from;
-    }
-
-    if (!blueprint.version) {
-      throw new Error('A custom blueprint cannot detect --from. You must supply it.');
-    }
+      _blueprint,
+      emberCliUpdateJson,
+      from,
+      cwd
+    );
   } else if (blueprints.length) {
     let {
       areAllUpToDate,
@@ -137,6 +182,7 @@ module.exports = async function emberCliUpdate({
     });
   }
 
+  // If blueprint is located on disk
   if (blueprint.location && !packageUrl) {
     let parsedPackage = await parseBlueprintPackage({
       cwd,
@@ -153,6 +199,9 @@ module.exports = async function emberCliUpdate({
     blueprint
   });
 
+  // If no base blueprint is found, set the selected one as the base blueprint.
+  // `glimmer`, `app`, and `addon` blueprints as well as ones whose `isBaseBlueprint` attribute is
+  // set to true will also have baseBlueprint undefined
   if (!baseBlueprint) {
     // for non-existing blueprints
     blueprint.isBaseBlueprint = true;

src/is-default-blueprint.js

@@ -7,6 +7,13 @@ const {
   glimmerPackageName
 } = require('./constants');
 
+/**
+ * A default blueprint either the `addon` or `app` blueprint provided by `ember-cli` or the `glimmer` one
+ *
+ * @param {string} packageName - Ensure this is one of the package names that contain the default blueprints
+ * @param {string} name - Check if this is the name of one of the default blueprint names
+ * @returns {boolean}
+ */
 function isDefaultBlueprint({ packageName, name }) {
   if (packageName === glimmerPackageName && name === glimmerPackageName) {
     return true;

src/load-default-blueprint-from-disk.js

@@ -8,6 +8,14 @@ const getProjectVersion = require('./get-project-version');
 const loadDefaultBlueprint = require('./load-default-blueprint');
 const utils = require('./utils');
 
+/**
+ * Generate the configuration for the "base blueprint" which is the blueprint that first created
+ * the ember project
+ *
+ * @param {string} cwd - Current working directory expected to be a node project path
+ * @param {string} version - Optional. if not pass will use the one specified in package json
+ * @returns {Promise<*|{}>}
+ */
 async function loadDefaultBlueprintFromDisk({
   cwd,
   version
@@ -32,9 +40,7 @@ async function loadDefaultBlueprintFromDisk({
     }
   }
 
-  let blueprint = loadDefaultBlueprint(projectOptions, version);
-
-  return blueprint;
+  return loadDefaultBlueprint(projectOptions, version);
 }
 
 module.exports = loadDefaultBlueprintFromDisk;