@modernpoacher/deps 2.2.18 → 2.2.20

package/src/common/git/index.mjs

@@ -1,4 +1,13 @@
-import debug from 'debug'
+/**
+ *  @typedef {import('node:child_process').ExecException} ExecException
+ */
+
+/**
+ *  @callback HandleComplete
+ *  @param {ExecException | null} e
+ *  @param {string} v
+ *  @returns {void}
+ */
 
 import stripAnsi from 'strip-ansi'
 
@@ -10,6 +19,8 @@ import {
   exec
 } from 'node:child_process'
 
+import debug from '#deps/src/common/debug'
+
 import {
   BIN,
   VERSION,
@@ -28,7 +39,7 @@ const ADD = 'package.json package-lock.json'
 
 export const MESSAGE = PLATFORM === 'win32'
   ? 'Updated `package.json` &/ `package-lock.json`'
-  : 'Updated \\`package.json\\` &/ \\`package-lock.json\\`' /* eslint-disable-line no-useless-escape */
+  : 'Updated \\`package.json\\` &/ \\`package-lock.json\\`'
 
 export const AUTHOR = 'Modern Poacher Limited <modernpoacher@modernpoacher.com>'
 
@@ -40,25 +51,19 @@ echo "\${BASH_REMATCH[0]}"
 
 const GIT_PULL = `
 source "${BIN}/common.sh"
-
 source_home "${BIN}"
-
 git pull
 `
 
 const GIT_PUSH = `
 source "${BIN}/common.sh"
-
 source_home "${BIN}"
-
 git push
 `
 
 const GIT_PUSH_TAGS = `
 source "${BIN}/common.sh"
-
 source_home "${BIN}"
-
 git push --tags
 `
 
@@ -66,41 +71,82 @@ const log = debug('@modernpoacher/deps')
 
 log(`\`common/git\` (${VERSION} - ${PLATFORM}) is awake`)
 
-const trim = (v) => v.split(String.fromCharCode(10)).map((v) => v.trimEnd()).join(String.fromCharCode(10)).trim()
+const LF = String.fromCharCode(10)
+
+/**
+ *  @param {string} v
+ *  @returns {string}
+ */
+const trimEnd = (v) => v.trimEnd()
+
+/**
+ *  @param {string} v
+ *  @returns {string}
+ */
+const trim = (v) => v.split(LF).map(trimEnd).join(LF).trim()
 
+/**
+ *  @param {string} v
+ *  @returns {boolean}
+ */
 function filter (v) {
   return Boolean(stripAnsi(v).trim())
 }
 
+/**
+ *  @param {string} directory
+ *  @returns {(s: string) => boolean}
+ */
 function getIsDirectory (directory) {
   return function isDirectory (s) {
     return directory === s
   }
 }
 
-function isFatal (s) {
-  return s.toLowerCase().startsWith('fatal: not a git repository')
+/**
+ *  @param {string} v
+ *  @returns {boolean}
+ */
+function isFatal (v) {
+  return v.toLowerCase().startsWith('fatal: not a git repository')
 }
 
+/**
+ *  @param {string} key
+ *  @returns {(value: string) => void}
+ */
 export function use (key) {
   const log = debug(`@modernpoacher/deps:${key}`)
 
+  /**
+   *  @param {string} v
+   *  @returns {void}
+   */
   function write (v) {
     log(v.trimEnd())
   }
 
   return function use (value) {
-    value.split(String.fromCharCode(10))
+    value.split(LF)
       .filter(filter)
       .forEach(write)
   }
 }
 
+/**
+ *  @param {string} key
+ *  @param {string} directory
+ *  @returns {(value: string) => void}
+ */
 export function out (key, directory) {
   const log = debug(`@modernpoacher/deps:${key}`)
 
   const isDirectory = getIsDirectory(directory)
 
+  /**
+   *  @param {string} v
+   *  @returns {boolean}
+   */
   function filterOut (v) {
     const s = v.trim()
 
@@ -109,22 +155,35 @@ export function out (key, directory) {
     )
   }
 
+  /**
+   *  @param {string} v
+   *  @returns {void}
+   */
   function write (v) {
     if (v.trim()) log(v.trimEnd())
   }
 
   return function out (value) {
-    value.split(String.fromCharCode(10))
+    value.split(LF)
       .filter(filter).filter(filterOut)
       .forEach(write)
   }
 }
 
+/**
+ *  @param {string} key
+ *  @param {string} directory
+ *  @returns {(value: string) => void}
+ */
 export function err (key, directory) {
   const log = debug(`@modernpoacher/deps:${key}`)
 
   const isDirectory = getIsDirectory(directory)
 
+  /**
+   *  @param {string} v
+   *  @returns {boolean}
+   */
   function filterErr (v) {
     const s = v.trim()
 
@@ -133,12 +192,16 @@ export function err (key, directory) {
     )
   }
 
+  /**
+   *  @param {string} v
+   *  @returns {void}
+   */
   function write (v) {
     if (v.trim()) log(v.trimEnd())
   }
 
   return function err (value) {
-    value.split(String.fromCharCode(10))
+    value.split(LF)
       .filter(filter).filter(filterErr)
       .forEach(write)
   }
@@ -146,30 +209,27 @@ export function err (key, directory) {
 
 /**
  *  @function getErrorCode
- *
+ *  @description
  *  Get an error code from an error
- *
- *  @param {Error}
+ *  @param {{code?: number, message?: string}} e
  *  @returns {number}
  */
 const getErrorCode = ({ code = 0 } = {}) => code
 
 /**
  *  @function getErrorMessage
- *
+ *  @description
  *  Get an error message from an error
- *
- *  @param {Error}
+ *  @param {{code?: number, message?: string}} e
  *  @returns {string}
  */
 const getErrorMessage = ({ message = '' } = {}) => message
 
 /**
  *  @function isCommandError
- *
+ *  @description
  *  Determine whether an error is a safe non-zero exit from a Git command
- *
- *  @param {Error}
+ *  @param {{code?: number, message?: string}} e
  *  @returns {boolean}
  */
 function isCommandError (e) {
@@ -183,9 +243,8 @@ function isCommandError (e) {
 
 /**
  *  @function catGitRefsRemotesOriginHead
- *
+ *  @description
  *  Get the default branch from `.git/refs/remotes/origin/HEAD`
- *
  *  @param {string} d - A directory configured for Git
  *  @returns {Promise<string>}
  */
@@ -198,27 +257,32 @@ export function catGitRefsRemotesOriginHead (d = DIRECTORY) {
     new Promise((resolve, reject) => {
       const commands = CAT_GIT_REFS_REMOTES_ORIGIN_HEAD.trim()
       const options = getOptions(directory)
+      /**
+       *  @type {HandleComplete}
+       */
+      function handleComplete (e, v) {
+        if (!e) {
+          resolve(trim(v))
+        } else {
+          reject(e)
+        }
+      }
 
       const {
         stdout,
         stderr
-      } = exec(commands, options, (e, v = '') => {
-        (!e)
-          ? resolve(trim(v))
-          : reject(e)
-      })
-
-      stdout.on('data', out('cat-git-refs-remotes-origin-head', directory))
-      stderr.on('data', err('cat-git-refs-remotes-origin-head', directory))
+      } = exec(commands, options, handleComplete)
+
+      if (stdout) stdout.on('data', out('cat-git-refs-remotes-origin-head', directory))
+      if (stderr) stderr.on('data', err('cat-git-refs-remotes-origin-head', directory))
     })
   )
 }
 
 /**
  *  @function awkGitRemoteShowOriginHead
- *
+ *  @description
  *  Get the remote default branch
- *
  *  @param {string} d - A directory configured for Git
  *  @returns {Promise<string>}
  */
@@ -231,27 +295,32 @@ export function awkGitRemoteShowOriginHead (d = DIRECTORY) {
     new Promise((resolve, reject) => {
       const commands = 'git remote show origin | awk \'/HEAD branch/ {print $NF}\''
       const options = getOptions(directory)
+      /**
+       *  @type {HandleComplete}
+       */
+      function handleComplete (e = null, v = '') {
+        if (!e) {
+          resolve(trim(v))
+        } else {
+          reject(e)
+        }
+      }
 
       const {
         stdout,
         stderr
-      } = exec(commands, options, (e, v = '') => {
-        (!e)
-          ? resolve(trim(v))
-          : reject(e)
-      })
-
-      stdout.on('data', out('git-remote-show-origin-head', directory))
-      stderr.on('data', err('git-remote-show-origin-head', directory))
+      } = exec(commands, options, handleComplete)
+
+      if (stdout) stdout.on('data', out('git-remote-show-origin-head', directory))
+      if (stderr) stderr.on('data', err('git-remote-show-origin-head', directory))
     })
   )
 }
 
 /**
  *  @function gitRevParseShowTopLevel
- *
+ *  @description
  *  Determine whether a directory is configured for Git
- *
  *  @param {string} d - A directory
  *  @returns {Promise<string>}
  */
@@ -264,27 +333,32 @@ export function gitRevParseShowTopLevel (d = DIRECTORY) {
     new Promise((resolve, reject) => {
       const commands = 'git rev-parse --show-toplevel'
       const options = getOptions(directory)
+      /**
+       *  @type {HandleComplete}
+       */
+      function handleComplete (e, v) {
+        if (!e) {
+          resolve(trim(v))
+        } else {
+          reject(e)
+        }
+      }
 
       const {
         stdout,
         stderr
-      } = exec(commands, options, (e, v = '') => {
-        (!e)
-          ? resolve(trim(v))
-          : reject(e)
-      })
-
-      stdout.on('data', out('git-rev-parse-show-toplevel', directory))
-      stderr.on('data', err('git-rev-parse-show-toplevel', directory))
+      } = exec(commands, options, handleComplete)
+
+      if (stdout) stdout.on('data', out('git-rev-parse-show-toplevel', directory))
+      if (stderr) stderr.on('data', err('git-rev-parse-show-toplevel', directory))
     })
   )
 }
 
 /**
  *  @function gitRevParseAbbrevRefHead
- *
+ *  @description
  *  Determine which branch is HEAD
- *
  *  @param {string} d - A directory
  *  @returns {Promise<string>}
  */
@@ -297,27 +371,32 @@ export function gitRevParseAbbrevRefHead (d = DIRECTORY) {
     new Promise((resolve, reject) => {
       const commands = 'git rev-parse --abbrev-ref HEAD'
       const options = getOptions(directory)
+      /**
+       *  @type {HandleComplete}
+       */
+      function handleComplete (e, v) {
+        if (!e) {
+          resolve(trim(v))
+        } else {
+          reject(e)
+        }
+      }
 
       const {
         stdout,
         stderr
-      } = exec(commands, options, (e, v = '') => {
-        (!e)
-          ? resolve(trim(v))
-          : reject(e)
-      })
-
-      stdout.on('data', out('git-rev-parse-abbrev-ref-head', directory))
-      stderr.on('data', err('git-rev-parse-abbrev-ref-head', directory))
+      } = exec(commands, options, handleComplete)
+
+      if (stdout) stdout.on('data', out('git-rev-parse-abbrev-ref-head', directory))
+      if (stderr) stderr.on('data', err('git-rev-parse-abbrev-ref-head', directory))
     })
   )
 }
 
 /**
  *  @function gitCheckout
- *
+ *  @description
  *  Switch to the default value if none is supplied
- *
  *  @param {string} d - A directory configured for Git
  *  @param {string} branch - The Git branch
  *  @returns {Promise<string>}
@@ -332,30 +411,34 @@ export function gitCheckout (d = DIRECTORY, branch = BRANCH) {
       const commands = `git checkout ${branch}`
       const options = getOptions(directory)
 
+      /**
+       *  @type {HandleComplete}
+       */
+      function handleComplete (e, v) {
+        if (!e || isCommandError(e)) {
+          resolve(v)
+        } else {
+          reject(e)
+        }
+      }
+
       const {
         stdout,
         stderr
-      } = exec(commands, options, (e, v) => {
-        (!e)
-          ? resolve(v)
-          : isCommandError(e)
-            ? resolve(v)
-            : reject(e)
-      })
+      } = exec(commands, options, handleComplete)
 
       const log = use('git-checkout')
 
-      stdout.on('data', log)
-      stderr.on('data', log)
+      if (stdout) stdout.on('data', log)
+      if (stderr) stderr.on('data', log)
     })
   )
 }
 
 /**
  *  @function gitPull
- *
+ *  @description
  *  Pull changes from the Git remote
- *
  *  @param {string} d - A directory configured for Git
  *  @returns {Promise<string>}
  */
@@ -368,31 +451,34 @@ export function gitPull (d = DIRECTORY) {
     new Promise((resolve, reject) => {
       const commands = GIT_PULL.trim()
       const options = getOptions(directory)
+      /**
+       *  @type {HandleComplete}
+       */
+      function handleComplete (e, v) {
+        if (!e || isCommandError(e)) {
+          resolve(v)
+        } else {
+          reject(e)
+        }
+      }
 
       const {
         stdout,
         stderr
-      } = exec(commands, options, (e, v) => {
-        (!e)
-          ? resolve(v)
-          : isCommandError(e)
-            ? resolve(v)
-            : reject(e)
-      })
+      } = exec(commands, options, handleComplete)
 
       const log = use('git-pull')
 
-      stdout.on('data', log)
-      stderr.on('data', log)
+      if (stdout) stdout.on('data', log)
+      if (stderr) stderr.on('data', log)
     })
   )
 }
 
 /**
  *  @function gitPush
- *
+ *  @description
  *  Push changes to the Git remote
- *
  *  @param {string} d - A directory configured for Git
  *  @returns {Promise<string>}
  */
@@ -405,31 +491,34 @@ export function gitPush (d = DIRECTORY) {
     new Promise((resolve, reject) => {
       const commands = GIT_PUSH.trim()
       const options = getOptions(directory)
+      /**
+       *  @type {HandleComplete}
+       */
+      function handleComplete (e, v) {
+        if (!e || isCommandError(e)) {
+          resolve(v)
+        } else {
+          reject(e)
+        }
+      }
 
       const {
         stdout,
         stderr
-      } = exec(commands, options, (e, v) => {
-        (!e)
-          ? resolve(v)
-          : isCommandError(e)
-            ? resolve(v)
-            : reject(e)
-      })
+      } = exec(commands, options, handleComplete)
 
       const log = use('git-push')
 
-      stdout.on('data', log)
-      stderr.on('data', log)
+      if (stdout) stdout.on('data', log)
+      if (stderr) stderr.on('data', log)
     })
   )
 }
 
 /**
  *  @function gitPushTags
- *
+ *  @description
  *  Push tags changes to the Git remote
- *
  *  @param {string} d - A directory configured for Git
  *  @returns {Promise<string>}
  */
@@ -442,31 +531,34 @@ export function gitPushTags (d = DIRECTORY) {
     new Promise((resolve, reject) => {
       const commands = GIT_PUSH_TAGS.trim()
       const options = getOptions(directory)
+      /**
+       *  @type {HandleComplete}
+       */
+      function handleComplete (e, v) {
+        if (!e || isCommandError(e)) {
+          resolve(v)
+        } else {
+          reject(e)
+        }
+      }
 
       const {
         stdout,
         stderr
-      } = exec(commands, options, (e, v) => {
-        (!e)
-          ? resolve(v)
-          : isCommandError(e)
-            ? resolve(v)
-            : reject(e)
-      })
+      } = exec(commands, options, handleComplete)
 
       const log = use('git-push-tags')
 
-      stdout.on('data', log)
-      stderr.on('data', log)
+      if (stdout) stdout.on('data', log)
+      if (stderr) stderr.on('data', log)
     })
   )
 }
 
 /**
  *  @function gitAdd
- *
+ *  @description
  *  Add changes to Git with a default value if none is supplied
- *
  *  @param {string} d - A directory configured for Git
  *  @param {string} add - An add parameter
  *  @returns {Promise<string>}
@@ -480,34 +572,37 @@ export function gitAdd (d = DIRECTORY, add = ADD) {
     new Promise((resolve, reject) => {
       const commands = `git add ${add}`
       const options = getOptions(directory)
+      /**
+       *  @type {HandleComplete}
+       */
+      function handleComplete (e, v) {
+        if (!e || isCommandError(e)) {
+          resolve(v)
+        } else {
+          reject(e)
+        }
+      }
 
       const {
         stdout,
         stderr
-      } = exec(commands, options, (e, v) => {
-        (!e)
-          ? resolve(v)
-          : isCommandError(e)
-            ? resolve(v)
-            : reject(e)
-      })
+      } = exec(commands, options, handleComplete)
 
       const log = use('git-add')
 
-      stdout.on('data', log)
-      stderr.on('data', log)
+      if (stdout) stdout.on('data', log)
+      if (stderr) stderr.on('data', log)
     })
   )
 }
 
 /**
  *  @function gitCommit
- *
+ *  @description
  *  Commit changes to Git with a default value if none is supplied
- *
- *  @param {string} c - A directory configured for Git
+ *  @param {string} d - A directory configured for Git
  *  @param {string} message - A commit message
- *  @param {string} author - The commit author
+ *  @param {string | { name: string; email: string }} author - The commit author
  *  @returns {Promise<string>}
  */
 export function gitCommit (d = DIRECTORY, message = MESSAGE, author = AUTHOR) {
@@ -519,22 +614,26 @@ export function gitCommit (d = DIRECTORY, message = MESSAGE, author = AUTHOR) {
     new Promise((resolve, reject) => {
       const commands = `git commit -m "${message}" --author "${author}"`
       const options = getOptions(directory)
+      /**
+       *  @type {HandleComplete}
+       */
+      function handleComplete (e, v) {
+        if (!e || isCommandError(e)) {
+          resolve(v)
+        } else {
+          reject(e)
+        }
+      }
 
       const {
         stdout,
         stderr
-      } = exec(commands, options, (e, v) => {
-        (!e)
-          ? resolve(v)
-          : isCommandError(e)
-            ? resolve(v)
-            : reject(e)
-      })
+      } = exec(commands, options, handleComplete)
 
       const log = use('git-commit')
 
-      stdout.on('data', log)
-      stderr.on('data', log)
+      if (stdout) stdout.on('data', log)
+      if (stderr) stderr.on('data', log)
     })
   )
 }