chore: add jsdoc types

lib/checkpoint.js

@@ -1,7 +1,15 @@
-const chalk = require('chalk')
+/** @type {import('chalk').default} */
+const chalk = /** @type {any} */(require('chalk'))
 const figures = require('figures')
 const util = require('util')
 
+/**
+ * @param {RuntimeConfig} argv
+ * @param {string} msg
+ * @param {string[]} args
+ * @param {string} [figure]
+ * @returns {void}
+ */
 module.exports = function (argv, msg, args, figure) {
   const defaultFigure = argv.dryRun ? chalk.yellow(figures.tick) : chalk.green(figures.tick)
   if (!argv.silent) {

lib/configuration.js

@@ -8,7 +8,9 @@ const CONFIGURATION_FILES = [
   '.versionrc.json',
   '.versionrc.js'
 ]
-
+/**
+ * @returns {import('conventional-changelog-config-spec').Config}
+ */
 module.exports.getConfiguration = function () {
   let config = {}
   const configPath = findUp.sync(CONFIGURATION_FILES)

lib/detect-package-manager.js

@@ -9,6 +9,8 @@ const { resolve } = require('path')
 
 /**
  * Check if a path exists
+ * @param {string} p
+ * @returns {Promise<boolean>}
  */
 async function pathExists (p) {
   try {
@@ -18,7 +20,10 @@ async function pathExists (p) {
     return false
   }
 }
-
+/**
+ * @param {string} cwd
+ * @returns {Promise<string | null>}
+ */
 function getTypeofLockFile (cwd = '.') {
   return Promise.all([
     pathExists(resolve(cwd, 'yarn.lock')),
@@ -39,6 +44,10 @@ function getTypeofLockFile (cwd = '.') {
   })
 }
 
+/**
+ * @param {string} [cwd]
+ * @returns {Promise<string>}
+ */
 const detectPMByLockFile = async (cwd) => {
   const type = await getTypeofLockFile(cwd)
   if (type) {

lib/format-commit-message.js

@@ -1,3 +1,8 @@
+/**
+ * @param {string} rawMsg
+ * @param {string} newVersion
+ * @returns {string}
+ */
 module.exports = function (rawMsg, newVersion) {
   const message = String(rawMsg)
   return message.replace(/{{currentTag}}/g, newVersion)

lib/latest-semver-tag.js

@@ -1,6 +1,10 @@
 const gitSemverTags = require('git-semver-tags')
 const semver = require('semver')
 
+/**
+ * @param {string} [tagPrefix]
+ * @returns {Promise<string>}
+ */
 module.exports = function (tagPrefix = undefined) {
   return new Promise((resolve, reject) => {
     gitSemverTags({ tagPrefix }, function (err, tags) {

lib/lifecycles/bump.js

@@ -1,19 +1,27 @@
 'use strict'
 
-const chalk = require('chalk')
+/** @type {import('chalk').default} */
+const chalk = /** @type {any} */(require('chalk'))
 const checkpoint = require('../checkpoint')
 const conventionalRecommendedBump = require('conventional-recommended-bump')
 const figures = require('figures')
 const fs = require('fs')
-const DotGitignore = require('dotgitignore')
+/** @type {import('dotgitignore').default} */
+const DotGitignore = /** @type {any} */(require('dotgitignore'))
 const path = require('path')
 const presetLoader = require('../preset-loader')
 const runLifecycleScript = require('../run-lifecycle-script')
 const semver = require('semver')
 const writeFile = require('../write-file')
 const { resolveUpdaterObjectFromArgument } = require('../updaters')
+/** @type {Object<string, boolean>} */
 let configsToUpdate = {}
 
+/**
+ * @typedef {import('semver').ReleaseType} ReleaseType
+ */
+
+/** @type {(args: RuntimeConfig, version: string) => Promise<string>} */
 async function Bump (args, version) {
   // reset the cache of updated config files each
   // time we perform the version bump step.
@@ -22,42 +30,71 @@ async function Bump (args, version) {
   if (args.skip.bump) return version
   let newVersion = version
   await runLifecycleScript(args, 'prerelease')
+  /** @type {ReleaseType | void | undefined} */
   const stdout = await runLifecycleScript(args, 'prebump')
   if (stdout && stdout.trim().length) args.releaseAs = stdout.trim()
   const release = await bumpVersion(args.releaseAs, version, args)
   if (!args.firstRelease) {
-    const releaseType = getReleaseType(args.prerelease, release.releaseType, version)
-    const releaseTypeAsVersion = releaseType === 'pre' + release.releaseType ? semver.valid(release.releaseType + '-' + args.prerelease + '.0') : semver.valid(releaseType)
-
-    newVersion = releaseTypeAsVersion || semver.inc(version, releaseType, args.prerelease)
+    const releaseType = getReleaseType(
+      args.prerelease,
+      release.releaseType,
+      version
+    )
+    const releaseTypeAsVersion =
+      releaseType === 'pre' + release.releaseType
+        ? semver.valid(release.releaseType + '-' + args.prerelease + '.0')
+        : semver.valid(releaseType)
+
+    newVersion =
+      releaseTypeAsVersion || semver.inc(version, releaseType, args.prerelease)
     updateConfigs(args, newVersion)
   } else {
-    checkpoint(args, 'skip version bump on first release', [], chalk.red(figures.cross))
+    checkpoint(
+      args,
+      'skip version bump on first release',
+      [],
+      chalk.red(figures.cross)
+    )
   }
   await runLifecycleScript(args, 'postbump')
   return newVersion
 }
 
+/**
+ * @returns {Object<string, boolean>}
+ */
 Bump.getUpdatedConfigs = function () {
   return configsToUpdate
 }
 
+/**
+ *
+ * @param {string} prerelease
+ * @param {"major" | "minor" | "patch"} expectedReleaseType
+ * @param {string} currentVersion
+ * @returns {ReleaseType}
+ */
 function getReleaseType (prerelease, expectedReleaseType, currentVersion) {
   if (isString(prerelease)) {
     if (isInPrerelease(currentVersion)) {
-      if (shouldContinuePrerelease(currentVersion, expectedReleaseType) ||
-        getTypePriority(getCurrentActiveType(currentVersion)) > getTypePriority(expectedReleaseType)
+      if (
+        shouldContinuePrerelease(currentVersion, expectedReleaseType) ||
+        getTypePriority(getCurrentActiveType(currentVersion)) >
+          getTypePriority(expectedReleaseType)
       ) {
         return 'prerelease'
       }
     }
 
-    return 'pre' + expectedReleaseType
+    return /** @type {ReleaseType} */('pre' + expectedReleaseType)
   } else {
     return expectedReleaseType
   }
 }
 
+/**
+ * @type {(val: unknown) => val is string}
+ */
 function isString (val) {
   return typeof val === 'string'
 }
@@ -67,14 +104,15 @@ function isString (val) {
  * and if it current in-pre-release type is same as expect type,
  * it should continue the pre-release with the same type
  *
- * @param version
- * @param expectType
+ * @param {string} version
+ * @param {string} expectType
  * @return {boolean}
  */
 function shouldContinuePrerelease (version, expectType) {
   return getCurrentActiveType(version) === expectType
 }
 
+/** @type {(version: string) => boolean} */
 function isInPrerelease (version) {
   return Array.isArray(semver.prerelease(version))
 }
@@ -83,9 +121,8 @@ const TypeList = ['major', 'minor', 'patch'].reverse()
 
 /**
  * extract the in-pre-release type in target version
- *
- * @param version
- * @return {string}
+ * @param {string} version
+ * @return {string | void}
  */
 function getCurrentActiveType (version) {
   const typelist = TypeList
@@ -100,13 +137,13 @@ function getCurrentActiveType (version) {
  * calculate the priority of release type,
  * major - 2, minor - 1, patch - 0
  *
- * @param type
+ * @param {string} type
  * @return {number}
  */
 function getTypePriority (type) {
   return TypeList.indexOf(type)
 }
-
+/** @type {(releaseAs: ReleaseType, currentVersion: string, args: RuntimeConfig) => Promise<{releaseType: ReleaseType}>} */
 function bumpVersion (releaseAs, currentVersion, args) {
   return new Promise((resolve, reject) => {
     if (releaseAs) {
@@ -118,16 +155,21 @@ function bumpVersion (releaseAs, currentVersion, args) {
       if (typeof presetOptions === 'object') {
         if (semver.lt(currentVersion, '1.0.0')) presetOptions.preMajor = true
       }
-      conventionalRecommendedBump({
-        debug: args.verbose && console.info.bind(console, 'conventional-recommended-bump'),
-        preset: presetOptions,
-        path: args.path,
-        tagPrefix: args.tagPrefix,
-        lernaPackage: args.lernaPackage
-      }, function (err, release) {
-        if (err) return reject(err)
-        else return resolve(release)
-      })
+      conventionalRecommendedBump(
+        {
+          debug:
+            args.verbose &&
+            console.info.bind(console, 'conventional-recommended-bump'),
+          preset: presetOptions,
+          path: args.path,
+          tagPrefix: args.tagPrefix,
+          lernaPackage: args.lernaPackage
+        },
+        function (err, release) {
+          if (err) return reject(err)
+          else return resolve(release)
+        }
+      )
     }
   })
 }
@@ -159,11 +201,7 @@ function updateConfigs (args, newVersion) {
         'bumping version in ' + updater.filename + ' from %s to %s',
         [updater.updater.readVersion(contents), realNewVersion]
       )
-      writeFile(
-        args,
-        configPath,
-        newContents
-      )
+      writeFile(args, configPath, newContents)
       // flag any config files that we modify the version # for
       // as having been updated.
       configsToUpdate[updater.filename] = true

lib/lifecycles/changelog.js

@@ -1,4 +1,5 @@
-const chalk = require('chalk')
+/** @type {import('chalk').default} */
+const chalk = /** @type {any} */(require('chalk'))
 const checkpoint = require('../checkpoint')
 const conventionalChangelog = require('conventional-changelog')
 const fs = require('fs')
@@ -7,6 +8,11 @@ const runLifecycleScript = require('../run-lifecycle-script')
 const writeFile = require('../write-file')
 const START_OF_LAST_RELEASE_PATTERN = /(^#+ \[?[0-9]+\.[0-9]+\.[0-9]+|<a name=)/m
 
+/**
+ * @param {RuntimeConfig} args
+ * @param {string} newVersion
+ * @returns {Promise<void>}
+ */
 async function Changelog (args, newVersion) {
   if (args.skip.changelog) return
   await runLifecycleScript(args, 'prechangelog')
@@ -18,6 +24,11 @@ Changelog.START_OF_LAST_RELEASE_PATTERN = START_OF_LAST_RELEASE_PATTERN
 
 module.exports = Changelog
 
+/**
+ * @param {RuntimeConfig} args
+ * @param {string} newVersion
+ * @returns {Promise<void>}
+ */
 function outputChangelog (args, newVersion) {
   return new Promise((resolve, reject) => {
     createIfMissing(args)
@@ -53,7 +64,10 @@ function outputChangelog (args, newVersion) {
     })
   })
 }
-
+/**
+ * @param {RuntimeConfig} args
+ * @returns {void}
+ */
 function createIfMissing (args) {
   try {
     fs.accessSync(args.infile, fs.F_OK)

lib/lifecycles/commit.js

@@ -5,6 +5,11 @@ const path = require('path')
 const runExecFile = require('../run-execFile')
 const runLifecycleScript = require('../run-lifecycle-script')
 
+/**
+ * @param {RuntimeConfig} args
+ * @param {string} newVersion
+ * @returns {Promise<void>}
+ */
 module.exports = async function (args, newVersion) {
   if (args.skip.commit) return
   const message = await runLifecycleScript(args, 'precommit')
@@ -13,11 +18,19 @@ module.exports = async function (args, newVersion) {
   await runLifecycleScript(args, 'postcommit')
 }
 
+/**
+ *
+ * @param {RuntimeConfig} args
+ * @param {string} newVersion
+ * @returns {Promise<void>}
+ */
 async function execCommit (args, newVersion) {
   let msg = 'committing %s'
+  /** @type {string[]} */
   let paths = []
   const verify = args.verify === false || args.n ? ['--no-verify'] : []
   const sign = args.sign ? ['-S'] : []
+  /** @type {string[]} */
   const toAdd = []
 
   // only start with a pre-populated paths list when CHANGELOG processing is not skipped

lib/lifecycles/tag.js

@@ -1,25 +1,41 @@
 const bump = require('../lifecycles/bump')
-const chalk = require('chalk')
+/** @type {import('chalk').default} */
+const chalk = /** @type {any} */(require('chalk'))
 const checkpoint = require('../checkpoint')
 const figures = require('figures')
 const formatCommitMessage = require('../format-commit-message')
 const runExecFile = require('../run-execFile')
 const runLifecycleScript = require('../run-lifecycle-script')
 const { detectPMByLockFile } = require('../detect-package-manager')
 
+/**
+ * @param {RuntimeConfig} args
+ * @param {boolean} pkgPrivate
+ * @param {string} newVersion
+ * @returns {Promise<void>}
+ */
 module.exports = async function (newVersion, pkgPrivate, args) {
   if (args.skip.tag) return
   await runLifecycleScript(args, 'pretag')
   await execTag(newVersion, pkgPrivate, args)
   await runLifecycleScript(args, 'posttag')
 }
 
+/**
+ * @returns {Promise<string>}
+ */
 async function detectPublishHint () {
   const npmClientName = await detectPMByLockFile()
   const publishCommand = 'publish'
   return `${npmClientName} ${publishCommand}`
 }
 
+/**
+ * @param {string} newVersion
+ * @param {boolean} pkgPrivate
+ * @param {RuntimeConfig} args
+ * @returns {Promise<void>}
+ */
 async function execTag (newVersion, pkgPrivate, args) {
   const tagOption = []
   if (args.sign) {