From 758ff37dae89ce44c5ccdd7aa9f777be057343b9 Mon Sep 17 00:00:00 2001
From: Ed Moore <eddiemoore@users.noreply.github.com>
Date: Mon, 17 May 2021 22:26:16 +1000
Subject: [PATCH] cleanup with docs (#91)

Co-authored-by: Joe Becher <71270647+drazisil-codecov@users.noreply.github.com>
---
 src/helpers/files.js | 61 +++++++++++++++++++++++++++++++++++++-------
 src/helpers/web.js   | 17 ++++++++++++
 src/index.js         | 13 ++++++++++
 3 files changed, 82 insertions(+), 9 deletions(-)

diff --git a/src/helpers/files.js b/src/helpers/files.js
index 8576d5b99..1e7c3f6d3 100644
--- a/src/helpers/files.js
+++ b/src/helpers/files.js
@@ -1,8 +1,14 @@
+// @ts-check
 const childProcess = require('child_process')
 const fs = require('fs')
 const path = require('path')
 const glob = require('glob')
 
+/**
+ *
+ * @param {string} projectRoot
+ * @returns Promise<string>
+ */
 async function getFileListing (projectRoot) {
   return getAllFiles(projectRoot, projectRoot).join('')
 }
@@ -144,20 +150,29 @@ function coverageFilePatterns () {
   ]
 }
 
+/**
+ *
+ * @param {string} projectRoot
+ * @param {string[]} coverageFilePatterns
+ * @returns string[]
+ */
 function getCoverageFiles (projectRoot, coverageFilePatterns) {
-  let files = []
-  for (let index = 0; index < coverageFilePatterns.length; index++) {
-    const pattern = coverageFilePatterns[index]
-    const newFiles = glob.sync(`**/${pattern}`, {
+  const files = coverageFilePatterns.flatMap(pattern => {
+    return glob.sync(`**/${pattern}`, {
       cwd: projectRoot,
       ignore: globBlacklist()
     })
-
-    files = files.concat(newFiles)
-  }
+  })
   return files
 }
 
+/**
+ *
+ * @param {string} projectRoot
+ * @param {string} file
+ * @param {string[]} manualBlacklist
+ * @returns boolean
+ */
 function isBlacklisted (projectRoot, file, manualBlacklist) {
   const blacklist = manualBlacklist
   return blacklist.includes(file)
@@ -179,6 +194,11 @@ function fetchGitRoot () {
   }
 }
 
+/**
+ *
+ * @param {string} projectRoot
+ * @returns string[]
+ */
 function parseGitIgnore (projectRoot) {
   const gitIgnorePath = path.join(projectRoot, '.gitignore')
   let lines
@@ -197,9 +217,15 @@ function parseGitIgnore (projectRoot) {
   return filteredLines
 }
 
-function getAllFiles (projectRoot, dirPath, arrayOfFiles) {
+/**
+ *
+ * @param {string} projectRoot Root of the project
+ * @param {string} dirPath Directory to search in
+ * @param {string[]} arrayOfFiles
+ * @returns {string[]}
+ */
+function getAllFiles (projectRoot, dirPath, arrayOfFiles = []) {
   const files = fs.readdirSync(dirPath)
-  arrayOfFiles = arrayOfFiles || []
 
   files.forEach(function (file) {
     if (
@@ -223,6 +249,11 @@ function getAllFiles (projectRoot, dirPath, arrayOfFiles) {
   return arrayOfFiles
 }
 
+/**
+ *
+ * @param {string} filePath
+ * @returns string[]
+ */
 function readAllLines (filePath) {
   const fileContents = fs.readFileSync(filePath)
 
@@ -230,6 +261,12 @@ function readAllLines (filePath) {
   return lines
 }
 
+/**
+ *
+ * @param {string} projectRoot
+ * @param {string} filePath
+ * @returns string
+ */
 function readCoverageFile (projectRoot, filePath) {
   try {
     return fs.readFileSync(getFilePath(projectRoot, filePath))
@@ -254,6 +291,12 @@ function endEnvironmentMarker () {
   return '<<<<<< ENV\n'
 }
 
+/**
+ *
+ * @param {string} projectRoot
+ * @param {string} filePath
+ * @returns string
+ */
 function getFilePath (projectRoot, filePath) {
   if (filePath.startsWith('./') ||
       filePath.startsWith('/') ||
diff --git a/src/helpers/web.js b/src/helpers/web.js
index a872e7f2d..5d8f16507 100644
--- a/src/helpers/web.js
+++ b/src/helpers/web.js
@@ -1,6 +1,13 @@
 const superagent = require('superagent')
 const validateHelpers = require('./validate')
 
+/**
+ *
+ * @param {Object} inputs
+ * @param {NodeJS.ProcessEnv} inputs.envs
+ * @param {Object} serviceParams
+ * @returns Object
+ */
 function populateBuildParams (inputs, serviceParams) {
   const { args, envs } = inputs
   serviceParams.name = args.name || envs.CODECOV_NAME || ''
@@ -68,12 +75,22 @@ async function uploadToCodecov (uploadURL, token, query, uploadFile, version) {
   }
 }
 
+/**
+ *
+ * @param {string} str
+ * @returns string
+ */
 function camelToSnake (str) {
   return str && str.match(/[A-Z]{2,}(?=[A-Z][a-z]+[0-9]*|\b)|[A-Z]?[a-z]+[0-9]*|[A-Z]|[0-9]+/g)
     .map(s => s.toLowerCase())
     .join('_')
 }
 
+/**
+ *
+ * @param {Object} queryParams
+ * @returns string
+ */
 function generateQuery (queryParams) {
   const query = Object
     .entries(queryParams)
diff --git a/src/index.js b/src/index.js
index 49a6628d2..1851d5e0c 100644
--- a/src/index.js
+++ b/src/index.js
@@ -1,3 +1,4 @@
+// @ts-check
 const zlib = require('zlib')
 const { version } = require('../package.json')
 const fileHelpers = require('./helpers/files')
@@ -5,6 +6,13 @@ const validateHelpers = require('./helpers/validate')
 const webHelpers = require('./helpers/web')
 const providers = require('./ci_providers')
 
+/**
+ *
+ * @param {string} uploadHost
+ * @param {string} token
+ * @param {string} query
+ * @param {string} uploadFile
+ */
 function dryRun (uploadHost, token, query, uploadFile) {
   console.log('==> Dumping upload file (no upload)')
   console.log(
@@ -192,6 +200,11 @@ async function main (args) {
   }
 }
 
+/**
+ *
+ * @param {string} version
+ * @returns string
+ */
 function generateHeader (version) {
   return `
      _____          _