Workspace utilities API and internals cleanup

.vscode/launch.json

@@ -16,6 +16,19 @@
       "sourceMaps": true,
       "outputCapture": "std",
       "console": "integratedTerminal"
+    },
+    {
+      // If there's an issue with running a beachball command, it's very likely due to using the
+      // local version of workspace-tools if it has breaking changes...
+      "type": "node",
+      "request": "launch",
+      "name": "Debug beachball",
+      "runtimeExecutable": "npm",
+      "cwd": "${workspaceFolder}",
+      "runtimeArgs": ["run-script", "checkchange"],
+      "sourceMaps": true,
+      "outputCapture": "std",
+      "console": "integratedTerminal"
     }
   ]
 }

change/change-4de15c98-ca4c-479e-b502-2ef3e4caf154.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "type": "minor",
+      "comment": "BREAKING: Various breaking changes to workspace package utilities. See readme for details.",
+      "packageName": "workspace-tools",
+      "email": "elcraig@microsoft.com",
+      "dependentChangeType": "patch"
+    }
+  ]
+}

package.json

@@ -45,5 +45,13 @@
     "ts-jest": "^29.1.0",
     "typedoc": "^0.25.2",
     "typescript": "~5.2.2"
+  },
+  "resolutions": {
+    "**/beachball/workspace-tools": "0.40.2"
+  },
+  "rationale": {
+    "resolutions": {
+      "**/beachball/workspace-tools": "Explicitly install an older version to avoid issues with local breaking changes"
+    }
   }
 }

packages/workspace-tools/README.md

@@ -20,8 +20,46 @@ Override the `maxBuffer` value for git processes, for example if the repo is ver
 
 ### PREFERRED_WORKSPACE_MANAGER
 
-Sometimes if multiple workspace/monorepo manager files are checked in, it's necessary to hint which manager is used: `npm`, `yarn`, `pnpm`, `rush`, or `lerna`.
+Sometimes if multiple workspace/monorepo manager files are checked in, it's necessary to hint which manager is used: `npm`, `yarn`, `pnpm`, `rush`, or `lerna`. Some APIs also accept a `manager` parameter, which is now the preferred method when available.
 
 ### VERBOSE
 
 Log additional output from certain functions.
+
+## Breaking changes
+
+For details of changes in all versions, see the [changelog](https://github.com/microsoft/workspace-tools/blob/main/packages/workspace-tools/CHANGELOG.md). This only lists the most significant breaking API changes.
+
+### 0.41.0
+
+The following APIs have been renamed for clarity, removed entirely, or consolidated:
+
+| Old (removed)                 | New                                    |
+| ----------------------------- | -------------------------------------- |
+| `getWorkspaces`               | `getWorkspaceInfos`                    |
+| `getWorkspacesAsync`          | `getWorkspaceInfosAsync`               |
+| `WorkspaceInfo`               | `WorkspaceInfos`                       |
+| `getWorkspaceRoot`            | `getWorkspaceManagerRoot`              |
+| `listOfWorkspacePackageNames` | `workspaces.map(w => w.name)`          |
+| `getPnpmWorkspaceRoot`        | `getWorkspaceManagerRoot(cwd, 'pnpm')` |
+| `getRushWorkspaceRoot`        | `getWorkspaceManagerRoot(cwd, 'rush')` |
+| `getYarnWorkspaceRoot`        | `getWorkspaceManagerRoot(cwd, 'yarn')` |
+| `getPnpmWorkspaces`           | `getWorkspaceInfos(cwd, 'pnpm')`       |
+| `getRushWorkspaces`           | `getWorkspaceInfos(cwd, 'rush')`       |
+| `getYarnWorkspaces`           | `getWorkspaceInfos(cwd, 'yarn')`       |
+
+Other changes:
+
+- Several functions now return `string[] | undefined` instead of returning an empty array on error:
+  - `getAllPackageJsonFiles`, `getAllPackageJsonFilesAsync`
+  - `getWorkspacePackagePaths`, `getWorkspacePackagePathsAsync`
+  - `getWorkspaceInfos`, `getWorkspaceInfosAsync`
+- `getWorkspaceManagerAndRoot` is now exported if you want to know the manager as well as the root
+- Several functions now have a `manager` param to force using a specific manager:
+  - `getWorkspaceManagerRoot`
+  - `findProjectRoot` (falls back to the git root and throws if neither is found)
+  - `getWorkspacePackagePaths`, `getWorkspacePackagePathsAsync`
+  - `getWorkspacePatterns` (new)
+  - `getWorkspaceInfos`, `getWorkspaceInfosAsync`
+  - `getCatalogs`
+- 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, and file an issue if not.

packages/workspace-tools/etc/workspace-tools.api.md

@@ -90,16 +90,16 @@ export function findGitRoot(cwd: string): string;
 export function findPackageRoot(cwd: string): string | undefined;
 
 // @public
-export function findProjectRoot(cwd: string): string;
+export function findProjectRoot(cwd: string, manager?: WorkspaceManager): string;
 
 // @public
 export function findWorkspacePath(workspaces: WorkspaceInfos, packageName: string): string | undefined;
 
 // @public
-export function getAllPackageJsonFiles(cwd: string): string[];
+export function getAllPackageJsonFiles(cwd: string): string[] | undefined;
 
 // @public
-export function getAllPackageJsonFilesAsync(cwd: string): Promise<string[]>;
+export function getAllPackageJsonFilesAsync(cwd: string): Promise<string[] | undefined>;
 
 // Warning: (ae-forgotten-export) The symbol "GitBranchOptions" needs to be exported by the entry point index.d.ts
 //
@@ -118,7 +118,7 @@ export function getBranchName(options: GitCommonOptions): string;
 export function getBranchName(cwd: string): string;
 
 // @public
-export function getCatalogs(cwd: string): Catalogs | undefined;
+export function getCatalogs(cwd: string, managerOverride?: WorkspaceManager): Catalogs | undefined;
 
 // @public
 export function getCatalogVersion(params: {
@@ -243,10 +243,10 @@ export function getPackageInfo(cwd: string): PackageInfo | undefined;
 export function getPackageInfoAsync(cwd: string): Promise<PackageInfo | undefined>;
 
 // @public
-export function getPackageInfos(cwd: string): PackageInfos;
+export function getPackageInfos(cwd: string, managerOverride?: WorkspaceManager): PackageInfos;
 
 // @public
-export function getPackageInfosAsync(cwd: string): Promise<PackageInfos>;
+export function getPackageInfosAsync(cwd: string, managerOverride?: WorkspaceManager): Promise<PackageInfos>;
 
 // Warning: (ae-forgotten-export) The symbol "GetPackagesByFilesOptions" needs to be exported by the entry point index.d.ts
 //
@@ -267,12 +267,6 @@ interface GetPackagesByFilesOptions {
 // @public @deprecated
 export function getParentBranch(cwd: string): string | null;
 
-// @public @deprecated (undocumented)
-export function getPnpmWorkspaceRoot(cwd: string): string;
-
-// @public
-export function getPnpmWorkspaces(cwd: string): WorkspaceInfos;
-
 // @public
 export function getRecentCommitMessages(options: GitBranchOptions): string[];
 
@@ -285,12 +279,6 @@ export function getRemoteBranch(options: GitBranchOptions): string | null;
 // @public @deprecated (undocumented)
 export function getRemoteBranch(branch: string, cwd: string): string | null;
 
-// @public @deprecated (undocumented)
-export function getRushWorkspaceRoot(cwd: string): string;
-
-// @public
-export function getRushWorkspaces(cwd: string): WorkspaceInfos;
-
 // @public
 export function getScopedPackages(search: string[], packages: {
     [pkg: string]: unknown;
@@ -341,36 +329,32 @@ export function getUserEmail(options: GitCommonOptions): string | null;
 export function getUserEmail(cwd: string): string | null;
 
 // @public
-export function getWorkspaceInfos(cwd: string): WorkspaceInfos;
+export function getWorkspaceInfos(cwd: string, managerOverride?: WorkspaceManager): WorkspaceInfos | undefined;
 
 // @public
-export function getWorkspaceInfosAsync(cwd: string): Promise<WorkspaceInfos>;
+export function getWorkspaceInfosAsync(cwd: string, managerOverride?: WorkspaceManager): Promise<WorkspaceInfos | undefined>;
 
-// Warning: (ae-forgotten-export) The symbol "WorkspaceManager" needs to be exported by the entry point index.d.ts
+// Warning: (ae-forgotten-export) The symbol "WorkspaceManagerAndRoot" needs to be exported by the entry point index.d.ts
 //
 // @public
-export function getWorkspaceManagerRoot(cwd: string, preferredManager?: WorkspaceManager): string | undefined;
-
-// @public
-export function getWorkspacePackagePaths(cwd: string): string[];
+export function getWorkspaceManagerAndRoot(cwd: string, cache?: Map<string, WorkspaceManagerAndRoot | undefined>, managerOverride?: WorkspaceManager): WorkspaceManagerAndRoot | undefined;
 
 // @public
-export function getWorkspacePackagePathsAsync(cwd: string): Promise<string[]>;
+export function getWorkspaceManagerRoot(cwd: string, managerOverride?: WorkspaceManager): string | undefined;
 
-// @public @deprecated
-export function getWorkspaceRoot(cwd: string, preferredManager?: WorkspaceManager): string | undefined;
-
-// @public @deprecated (undocumented)
-export const getWorkspaces: typeof getWorkspaceInfos;
+// @public (undocumented)
+export function getWorkspaceManagerRoot(cwd: string, managerOverride: WorkspaceManager | undefined, options?: {
+    throwOnError: true;
+}): string;
 
-// @public @deprecated (undocumented)
-export const getWorkspacesAsync: typeof getWorkspaceInfosAsync;
+// @public
+export function getWorkspacePackagePaths(cwd: string, managerOverride?: WorkspaceManager): string[] | undefined;
 
-// @public @deprecated (undocumented)
-export function getYarnWorkspaceRoot(cwd: string): string;
+// @public
+export function getWorkspacePackagePathsAsync(cwd: string, managerOverride?: WorkspaceManager): Promise<string[] | undefined>;
 
 // @public
-export function getYarnWorkspaces(cwd: string): WorkspaceInfos;
+export function getWorkspacePatterns(cwd: string, managerOverride?: WorkspaceManager): string[] | undefined;
 
 // @public
 export function git(args: string[], options?: GitOptions): GitProcessOutput;
@@ -462,9 +446,6 @@ export function listAllTrackedFiles(options: {
 // @public @deprecated (undocumented)
 export function listAllTrackedFiles(patterns: string[], cwd: string): string[];
 
-// @public @deprecated (undocumented)
-export function listOfWorkspacePackageNames(workspaces: WorkspaceInfos): string[];
-
 // @public (undocumented)
 export type LockDependency = {
     version: string;
@@ -697,14 +678,17 @@ export function stageAndCommit(options: GitStageOptions & GitCommitOptions): voi
 // @public @deprecated (undocumented)
 export function stageAndCommit(patterns: string[], message: string, cwd: string, commitOptions?: string[]): void;
 
-// @public @deprecated (undocumented)
-export type WorkspaceInfo = WorkspaceInfos;
-
 // @public
 export type WorkspaceInfos = WorkspacePackageInfo[];
 
 // @public (undocumented)
-type WorkspaceManager = "yarn" | "pnpm" | "rush" | "npm" | "lerna";
+export type WorkspaceManager = "yarn" | "pnpm" | "rush" | "npm" | "lerna";
+
+// @public (undocumented)
+interface WorkspaceManagerAndRoot {
+    manager: WorkspaceManager;
+    root: string;
+}
 
 // @public
 export interface WorkspacePackageInfo {

packages/workspace-tools/src/__tests__/workspaces/getCatalogs.test.ts

@@ -1,12 +1,12 @@
+import { cleanupFixtures, setupFixture } from "@ws-tools/scripts/jest/setupFixture";
 import fs from "fs";
 import path from "path";
-import { cleanupFixtures, setupFixture } from "@ws-tools/scripts/jest/setupFixture";
-import type { Catalogs } from "../../types/Catalogs";
-import type { WorkspaceManager } from "../../workspaces/WorkspaceManager";
-import { getWorkspaceManagerAndRoot } from "../../workspaces/implementations";
 import { getPackageInfo } from "../../getPackageInfo";
-import { getCatalogs } from "../../workspaces/getCatalogs";
+import type { Catalogs } from "../../types/Catalogs";
+import type { WorkspaceManager } from "../../types/WorkspaceManager";
 import { catalogsToYaml } from "../../workspaces/catalogsToYaml";
+import { getCatalogs } from "../../workspaces/getCatalogs";
+import { getWorkspaceManagerAndRoot } from "../../workspaces/implementations";
 
 // Samples from https://yarnpkg.com/features/catalogs
 const defaultCatalogs: Required<Pick<Catalogs, "default">> = {

packages/workspace-tools/src/__tests__/workspaces/getWorkspaceManagerAndRoot.test.ts

@@ -0,0 +1,48 @@
+import { cleanupFixtures, setupFixture } from "@ws-tools/scripts/jest/setupFixture";
+import { getWorkspaceManagerAndRoot } from "../../workspaces/implementations/getWorkspaceManagerAndRoot";
+
+describe("getWorkspaceManagerAndRoot", () => {
+  afterAll(() => {
+    cleanupFixtures();
+  });
+
+  it("handles yarn monorepo", () => {
+    const repoRoot = setupFixture("monorepo");
+    expect(getWorkspaceManagerAndRoot(repoRoot)).toEqual({
+      root: repoRoot,
+      manager: "yarn",
+    });
+  });
+
+  it("handles pnpm monorepo", () => {
+    const repoRoot = setupFixture("monorepo-pnpm");
+    expect(getWorkspaceManagerAndRoot(repoRoot)).toEqual({
+      root: repoRoot,
+      manager: "pnpm",
+    });
+  });
+
+  it("handles rush monorepo", () => {
+    const repoRoot = setupFixture("monorepo-rush-pnpm");
+    expect(getWorkspaceManagerAndRoot(repoRoot)).toEqual({
+      root: repoRoot,
+      manager: "rush",
+    });
+  });
+
+  it("handles npm monorepo", () => {
+    const repoRoot = setupFixture("monorepo-npm");
+    expect(getWorkspaceManagerAndRoot(repoRoot)).toEqual({
+      root: repoRoot,
+      manager: "npm",
+    });
+  });
+
+  it("handles lerna monorepo", () => {
+    const repoRoot = setupFixture("monorepo-lerna-npm");
+    expect(getWorkspaceManagerAndRoot(repoRoot)).toEqual({
+      root: repoRoot,
+      manager: "lerna",
+    });
+  });
+});