fix: Improve accuracy of JSDoc type annotations

commands/publish/lib/get-tagged-packages.js

@@ -8,17 +8,18 @@ module.exports.getTaggedPackages = getTaggedPackages;
 
 /**
  * Retrieve a list of graph nodes for packages that were tagged in a non-independent release.
- * @param {PackageGraph} packageGraph
+ * @param {import("@lerna/package-graph").PackageGraph} packageGraph
  * @param {string} rootPath
- * @param {CommandExecOpts} opts
+ * @param {{ cwd: string }} execOpts
+ * @returns {Promise<import("@lerna/package-graph").PackageGraphNode[]>}
  */
-function getTaggedPackages(packageGraph, rootPath, opts) {
+function getTaggedPackages(packageGraph, rootPath, execOpts) {
   log.silly("getTaggedPackages");
 
   // @see https://stackoverflow.com/a/424142/5707
   // FIXME: --root is only necessary for tests :P
   return childProcess
-    .exec("git", ["diff-tree", "--name-only", "--no-commit-id", "--root", "-r", "-c", "HEAD"], opts)
+    .exec("git", ["diff-tree", "--name-only", "--no-commit-id", "--root", "-r", "-c", "HEAD"], execOpts)
     .then(({ stdout }) => {
       const manifests = stdout.split("\n").filter((fp) => path.basename(fp) === "package.json");
       const locations = new Set(manifests.map((fp) => path.join(rootPath, path.dirname(fp))));

commands/publish/lib/get-unpublished-packages.js

@@ -8,9 +8,9 @@ module.exports.getUnpublishedPackages = getUnpublishedPackages;
 
 /**
  * Retrieve a list of graph nodes for packages that need to be published.
- * @param {PackageGraph} packageGraph
- * @param {OptionsSnapshot} opts
- * @returns {PackageGraphNode[]}
+ * @param {import("@lerna/package-graph").PackageGraph} packageGraph
+ * @param {import("./fetch-config").FetchConfig} opts
+ * @returns {Promise<import("@lerna/package-graph").PackageGraphNode[]>}
  */
 function getUnpublishedPackages(packageGraph, opts) {
   log.silly("getUnpublishedPackages");

core/filter-options/lib/get-filtered-packages.js

@@ -22,10 +22,10 @@ module.exports.getFilteredPackages = getFilteredPackages;
 
 /**
  * Retrieve a list of Package instances filtered by various options.
- * @param {PackageGraph} packageGraph
- * @param {CommandExecOpts} execOpts
+ * @param {import("@lerna/package-graph").PackageGraph} packageGraph
+ * @param {{ cwd: string }} execOpts
  * @param {Partial<FilterOptions>} opts
- * @returns {Promise<Package>}
+ * @returns {Promise<import("@lerna/package").Package[]>}
  */
 function getFilteredPackages(packageGraph, execOpts, opts) {
   const options = { log, ...opts };
@@ -61,7 +61,7 @@ function getFilteredPackages(packageGraph, execOpts, opts) {
       options.log.notice("filter", "including merged tags");
     }
 
-    chain = chain.then((filteredPackages) =>
+    chain = chain.then((/** @type {ReturnType<typeof filterPackages>} */ filteredPackages) =>
       Promise.resolve(collectUpdates(filteredPackages, packageGraph, execOpts, opts)).then((updates) => {
         const updated = new Set(updates.map(({ pkg }) => pkg.name));
 

utils/collect-updates/lib/collect-dependents.js

@@ -2,21 +2,19 @@
 
 module.exports.collectDependents = collectDependents;
 
-/** @typedef {import("@lerna/package-graph/lib/package-graph-node").PackageGraphNode} PackageGraphNode */
-
 /**
  * @callback LocalDependentVisitor
- * @param {PackageGraphNode} dependentNode
+ * @param {import("@lerna/package-graph").PackageGraphNode} dependentNode
  * @param {string} dependentName
- * @param {Map<string, PackageGraphNode>} siblingDependents
+ * @param {Map<string, import("@lerna/package-graph").PackageGraphNode>} siblingDependents
  */
 
 /**
  * Build a set of nodes that are dependents of the input set.
- * @param {Set<PackageGraphNode>} nodes
+ * @param {Set<import("@lerna/package-graph").PackageGraphNode>} nodes
  */
 function collectDependents(nodes) {
-  /** @type {Set<PackageGraphNode>} */
+  /** @type {typeof nodes} */
   const collected = new Set();
 
   nodes.forEach((currentNode) => {

utils/collect-updates/lib/collect-packages.js

@@ -4,22 +4,20 @@ const { collectDependents } = require("./collect-dependents");
 
 module.exports.collectPackages = collectPackages;
 
-/** @typedef {import("@lerna/package-graph/lib/package-graph-node").PackageGraphNode} PackageGraphNode */
-
 /**
- * @typedef {object} CollectorOptions
- * @property {(node: PackageGraphNode, name: string) => boolean} [isCandidate] By default, all nodes passed in are candidates
+ * @typedef {object} PackageCollectorOptions
+ * @property {(node: import("@lerna/package-graph").PackageGraphNode, name: string) => boolean} [isCandidate] By default, all nodes passed in are candidates
  * @property {(name: string) => void} [onInclude]
  * @property {boolean} [excludeDependents]
  */
 
 /**
  * Build a list of graph nodes, possibly including dependents, using predicate if available.
- * @param {Map<string, PackageGraphNode>} packages
- * @param {CollectorOptions} options
+ * @param {Map<string, import("@lerna/package-graph").PackageGraphNode>} packages
+ * @param {PackageCollectorOptions} options
  */
 function collectPackages(packages, { isCandidate = () => true, onInclude, excludeDependents } = {}) {
-  /** @type {Set<PackageGraphNode>} */
+  /** @type {Set<import("@lerna/package-graph").PackageGraphNode>} */
   const candidates = new Set();
 
   packages.forEach((node, name) => {
@@ -33,7 +31,7 @@ function collectPackages(packages, { isCandidate = () => true, onInclude, exclud
   }
 
   // The result should always be in the same order as the input
-  /** @type {PackageGraphNode[]} */
+  /** @type {import("@lerna/package-graph").PackageGraphNode[]} */
   const updates = [];
 
   packages.forEach((node, name) => {

utils/collect-updates/lib/make-diff-predicate.js

@@ -8,8 +8,6 @@ const slash = require("slash");
 
 module.exports.makeDiffPredicate = makeDiffPredicate;
 
-/** @typedef {import("@lerna/package-graph/lib/package-graph-node").PackageGraphNode} PackageGraphNode */
-
 /**
  * @param {string} committish
  * @param {{ cwd: string }} execOpts
@@ -30,7 +28,9 @@ function makeDiffPredicate(committish, execOpts, ignorePatterns = []) {
     log.info("ignoring diff in paths matching", ignorePatterns);
   }
 
-  return function hasDiffSinceThatIsntIgnored(/** @type {PackageGraphNode} */ node) {
+  return function hasDiffSinceThatIsntIgnored(
+    /** @type {import("@lerna/package-graph").PackageGraphNode} */ node
+  ) {
     const diff = diffSinceIn(committish, node.location, execOpts);
 
     if (diff === "") {

utils/filter-packages/filter-packages.js

@@ -9,15 +9,14 @@ const { ValidationError } = require("@lerna/validation-error");
 module.exports.filterPackages = filterPackages;
 
 /**
- * Filters a given set of packages and returns all packages that match the scope glob
- * and do not match the ignore glob
+ * Filters a list of packages, returning all packages that match the `include` glob[s]
+ * and do not match the `exclude` glob[s].
  *
- * @param {!Array.<Package>} packagesToFilter The packages to filter
- * @param {Array.<String>} include A list of globs to match the package name against
- * @param {Array.<String>} exclude A list of globs to filter the package name against
- * @param {Boolean} showPrivate When false, filter out private packages
- * @param {Boolean} continueIfNoMatch When true, do not throw if no package is matched
- * @return {Array.<Package>} The packages with a name matching the glob
+ * @param {import("@lerna/package").Package[]} packagesToFilter The packages to filter
+ * @param {string[]} [include] A list of globs to match the package name against
+ * @param {string[]} [exclude] A list of globs to filter the package name against
+ * @param {boolean} [showPrivate] When false, filter out private packages
+ * @param {boolean} [continueIfNoMatch] When true, do not throw if no package is matched
  * @throws when a given glob would produce an empty list of packages and `continueIfNoMatch` is not set.
  */
 function filterPackages(packagesToFilter, include = [], exclude = [], showPrivate, continueIfNoMatch) {
@@ -58,6 +57,9 @@ function filterPackages(packagesToFilter, include = [], exclude = [], showPrivat
   return Array.from(filtered);
 }
 
+/**
+ * @param {string[]|string|undefined} thing
+ */
 function arrify(thing) {
   if (!thing) {
     return [];
@@ -70,6 +72,9 @@ function arrify(thing) {
   return thing;
 }
 
+/**
+ * @param {string[]} patterns
+ */
 function negate(patterns) {
   return arrify(patterns).map((pattern) => `!${pattern}`);
 }

utils/listable/lib/listable-format.js

@@ -8,7 +8,7 @@ const { QueryGraph } = require("@lerna/query-graph");
 module.exports.listableFormat = listableFormat;
 
 /**
- *
+ * Format a list of packages according to specified options.
  * @param {import("@lerna/package").Package[]} pkgList
  * @param {import("./listable-options").ListableOptions} options
  */

utils/query-graph/query-graph.js

@@ -42,7 +42,6 @@ class QueryGraph {
   /**
    * @param {import("@lerna/package").Package[]} packages An array of Packages to build the graph out of
    * @param {QueryGraphConfig} [options]
-   * @constructor
    */
   constructor(packages, { graphType = "allDependencies", rejectCycles } = {}) {
     // Create dependency graph
@@ -79,10 +78,16 @@ class QueryGraph {
     return this._getNextCycle();
   }
 
+  /**
+   * @param {string} name
+   */
   markAsTaken(name) {
     this.graph.delete(name);
   }
 
+  /**
+   * @param {import("@lerna/package-graph").PackageGraphNode} candidateNode
+   */
   markAsDone(candidateNode) {
     this.graph.remove(candidateNode);
 

utils/run-topologically/run-topologically.js

@@ -12,10 +12,11 @@ module.exports.runTopologically = runTopologically;
 /**
  * Run callback in maximally-saturated topological order.
  *
+ * @template T
  * @param {import("@lerna/package").Package[]} packages List of `Package` instances
- * @param {(pkg: import("@lerna/package").Package) => Promise<unknown>} runner Callback to map each `Package` with
+ * @param {(pkg: import("@lerna/package").Package) => Promise<T>} runner Callback to map each `Package` with
  * @param {TopologicalConfig} [options]
- * @returns {Promise<unknown[]>} when all executions complete
+ * @returns {Promise<T[]>} when all executions complete
  */
 function runTopologically(packages, runner, { concurrency, graphType, rejectCycles } = {}) {
   const queue = new PQueue({ concurrency });