Workspace utilities API and internals cleanup

[ecraig12345]

Overview

Massive cleanup and coherence improvements to the APIs related to monorepo workspaces/packages...

In addition to the naming changes detailed below, the structure of per-manager utilities has been greatly simplified and deduped:

• workspaces/implementations/<manager>.ts ONLY includes the internals that vary by manager: getting the workspace patterns or paths, and getting the catalogs if applicable. These internals throw on error.
• The common logic for determining the manager and catching errors moves to wrapWorkspaceUtility, which is called by each main function (e.g. getWorkspaceInfos)
• Most APIs now return | undefined and return undefined rather than empty arrays (or in some cases empty objects) if there was an error or nothing was found. APIs following that pattern will log rather than throwing on error.
• Rather than exporting manager-specific utilities like getYarnWorkspaces, several functions now have an optional manager param
• Try to ensure doc comments include relevant info about caching and error handling

Details and API changes

• getWorkspaces/getWorkspaceAsync has been renamed to getWorkspaceInfos/getWorkspaceInfosAsync, and the deprecated WorkspaceInfo type has been removed (use WorkspaceInfos).
• getWorkspaceRoot has been renamed to getWorkspaceManagerRoot. (getWorkspaceManagerAndRoot is now exported too, if you also want to know the manager.)
• Several functions now return string[] | undefined instead of returning an empty array on error:
  • getAllPackageJsonFiles/getAllPackageJsonFilesAsync
  • getWorkspacePackagePaths/getWorkspacePackagePathsAsync
  • getWorkspaceInfos/getWorkspaceInfosAsync
• Several functions now have a manager param to force using a specific manager. Manager-specific get___WorkspaceRoot and get___Workspaces have been removed.
  • getWorkspaceManagerRoot
  • findProjectRoot (falls back to the git root and throws if neither is found)
  • getWorkspacePackagePaths/getWorkspacePackagePathsAsync
  • getWorkspacePatterns (new)
  • getWorkspaceInfos/getWorkspaceInfosAsync
  • getCatalogs
• listOfWorkspacePackageNames is removed since it's trivially replaced by workspaces.map(w => w.name).
• Some related files have been moved or renamed internally, so deep imports may be broken. Please check the current top-level API to see if the utility you were deep-importing is now exported.