Changes requests

src/cache-save.ts

@@ -1,6 +1,5 @@
 import * as core from '@actions/core';
 import * as cache from '@actions/cache';
-import fs from 'fs';
 import {State} from './constants';
 import {getCacheDirectoriesPaths, getPackageManagerInfo} from './cache-utils';
 
@@ -31,7 +30,7 @@ const cachePackages = async (packageManager: string) => {
     return;
   }
 
-  // TODO: core.getInput has a bug - it can return undefined despite its definition
+  // TODO: core.getInput has a bug - it can return undefined despite its definition (tests only?)
   //       export declare function getInput(name: string, options?: InputOptions): string;
   const cacheDependencyPath = core.getInput('cache-dependency-path') || '';
   const cachePaths = await getCacheDirectoriesPaths(

src/cache-utils.ts

@@ -112,6 +112,11 @@ export const getPackageManagerInfo = async (packageManager: string) => {
     return null;
   }
 };
+
+/**
+ * glob expanding memoized because it involves potentially very deep
+ * traversing through the directories tree
+ */
 export const expandedPatternsMemoized: Record<string, string[]> = {};
 /**
  * Wrapper around `glob.create(pattern).glob()` with the memoization
@@ -148,9 +153,9 @@ export const expandCacheDependencyPath = async (
 };
 
 /**
- * Converts dependency file to the directory it resides in and ensures the directory exists
- * @param cacheDependencyPath - file name
- * @return either directory containing file or null
+ * Converts dependency file path to the directory it resides in and ensures the directory exists
+ * @param cacheDependencyPath - a file name path
+ * @return either directory containing the file or null
  */
 const cacheDependencyPathToProjectDirectory = (
   cacheDependencyPath: string
@@ -175,7 +180,8 @@ const cacheDependencyPathToProjectDirectory = (
 /**
  * Expands (converts) the string input `cache-dependency-path` to list of directories that
  * may be project roots
- * @param cacheDependencyPath
+ * @param cacheDependencyPath - either a single string or multiline string with possible glob patterns
+ *                              expected to be the result of `core.getInput('cache-dependency-path')`
  * @return list of directories and possible
  */
 const cacheDependencyPathToProjectsDirectories = async (
@@ -191,18 +197,28 @@ const cacheDependencyPathToProjectsDirectories = async (
     )
     .filter(path => path !== null) as string[];
 
+  // if user explicitly pointed out some file, but it does not exist it is definitely
+  // not he wanted, thus we should throw an error not trying to workaround with unexpected
+  // result to the whole build
   if (existingDirectories.length === 0)
     throw Error(
       'No existing directories found containing `cache-dependency-path`="${cacheDependencyPath}"'
     );
 
-  // uniq
+  // uniq in order to do not traverse the same directories during the further processing
   return existingDirectories.filter(
     (cachePath, i, result) =>
       cachePath != null && result.indexOf(cachePath) === i
   );
 };
 
+/**
+ * Utility function to be used from within `map`
+ * Finds the cache directories configured for the project directory
+ * @param packageManagerInfo - an object having getCacheFolderPath method specific to given PM
+ * @param projectDirectory - the string pointing out to a project dir (i.e. directory with its own .yarnrc)
+ * @return list of directories to be cached according to the project configuration in the directory
+ */
 const projectDirectoryToCacheFolderPath = async (
   packageManagerInfo: PackageManagerInfo,
   projectDirectory: string
@@ -216,19 +232,13 @@ const projectDirectoryToCacheFolderPath = async (
   return cacheFolderPath;
 };
 
-const projectDirectoriesToCacheFoldersPaths = async (
-  packageManagerInfo: PackageManagerInfo,
-  projectDirectories: string[]
-): Promise<string[]> => {
-  const cacheFoldersPaths = await Promise.all(
-    projectDirectories.map(projectDirectory =>
-      projectDirectoryToCacheFolderPath(packageManagerInfo, projectDirectory)
-    )
-  );
-  return cacheFoldersPaths.filter(
-    (cachePath, i, result) => result.indexOf(cachePath) === i
-  );
-};
+/**
+ * Top-entry function to find the cache directories configured for the repo if cache-dependency-path is not empty
+ * @param packageManagerInfo - an object having getCacheFolderPath method specific to given PM
+ * @param cacheDependencyPath - either a single string or multiline string with possible glob patterns
+ *                              expected to be the result of `core.getInput('cache-dependency-path')`
+ * @return list of files on which the cache depends
+ */
 const cacheDependencyPathToCacheFoldersPaths = async (
   packageManagerInfo: PackageManagerInfo,
   cacheDependencyPath: string
@@ -236,12 +246,22 @@ const cacheDependencyPathToCacheFoldersPaths = async (
   const projectDirectories = await cacheDependencyPathToProjectsDirectories(
     cacheDependencyPath
   );
-  return projectDirectoriesToCacheFoldersPaths(
-    packageManagerInfo,
-    projectDirectories
+  const cacheFoldersPaths = await Promise.all(
+    projectDirectories.map(projectDirectory =>
+      projectDirectoryToCacheFolderPath(packageManagerInfo, projectDirectory)
+    )
+  );
+  // uniq in order to do not cache the same directories twice
+  return cacheFoldersPaths.filter(
+    (cachePath, i, result) => result.indexOf(cachePath) === i
   );
 };
 
+/**
+ * Top-entry function to find the cache directories configured for the repo if cache-dependency-path is empty
+ * @param packageManagerInfo - an object having getCacheFolderPath method specific to given PM
+ * @return list of files on which the cache depends
+ */
 const cacheFoldersPathsForRoot = async (
   packageManagerInfo: PackageManagerInfo
 ): Promise<string[]> => {
@@ -252,6 +272,14 @@ const cacheFoldersPathsForRoot = async (
   return [cacheFolderPath];
 };
 
+/**
+ * Main function to find the cache directories configured for the repo
+ * currently it handles only the case of PM=yarn && cacheDependencyPath is not empty
+ * @param packageManagerInfo - an object having getCacheFolderPath method specific to given PM
+ * @param cacheDependencyPath - either a single string or multiline string with possible glob patterns
+ *                              expected to be the result of `core.getInput('cache-dependency-path')`
+ * @return list of files on which the cache depends
+ */
 export const getCacheDirectoriesPaths = async (
   packageManagerInfo: PackageManagerInfo,
   cacheDependencyPath: string