[rush-lib] Add async APIs for disk-touching methods in PackageJsonEditor, CommonVersionsConfiguration, and VersionPolicy (microsoft#5724)

* Refactor PackageJsonEditor.

* fixup! Refactor PackageJsonEditor.

* fixup! Refactor PackageJsonEditor.

* Add changelog entry for PackageJsonEditor async API refactor.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Update a downstream project to use the async APIs.

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: iclanton

common/changes/@microsoft/rush/rework-PackageJsonEditor_2026-03-24-00-00.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "Add async variants of disk-touching APIs in `PackageJsonEditor` (`loadAsync`, `saveIfModifiedAsync`), `CommonVersionsConfiguration` (`loadFromFileAsync`, `saveAsync`), and `VersionPolicy` (`setDependenciesBeforePublishAsync`, `setDependenciesBeforeCommitAsync`); deprecate corresponding sync methods.",
+      "type": "minor",
+      "packageName": "@microsoft/rush"
+    }
+  ],
+  "packageName": "@microsoft/rush",
+  "email": "iclanton@users.noreply.github.com"
+}

common/reviews/api/rush-lib.api.md

@@ -137,9 +137,13 @@ export class CommonVersionsConfiguration {
     getAllPreferredVersions(): Map<string, string>;
     getPreferredVersionsHash(): string;
     readonly implicitlyPreferredVersions: boolean | undefined;
+    // @deprecated (undocumented)
     static loadFromFile(jsonFilePath: string, rushConfiguration?: RushConfiguration): CommonVersionsConfiguration;
+    static loadFromFileAsync(jsonFilePath: string, rushConfiguration?: RushConfiguration): Promise<CommonVersionsConfiguration>;
     readonly preferredVersions: Map<string, string>;
+    // @deprecated (undocumented)
     save(): boolean;
+    saveAsync(): Promise<boolean>;
 }
 
 export { CredentialCache }
@@ -1097,15 +1101,19 @@ export class PackageJsonEditor {
     readonly filePath: string;
     // (undocumented)
     static fromObject(object: IPackageJson, filename: string): PackageJsonEditor;
-    // (undocumented)
+    // @deprecated (undocumented)
     static load(filePath: string): PackageJsonEditor;
     // (undocumented)
+    static loadAsync(filePath: string): Promise<PackageJsonEditor>;
+    // (undocumented)
     get name(): string;
     // (undocumented)
     removeDependency(packageName: string, dependencyType: DependencyType): void;
     get resolutionsList(): ReadonlyArray<PackageJsonDependency>;
-    // (undocumented)
+    // @deprecated (undocumented)
     saveIfModified(): boolean;
+    // (undocumented)
+    saveIfModifiedAsync(): Promise<boolean>;
     saveToObject(): IPackageJson;
     // (undocumented)
     tryGetDependency(packageName: string): PackageJsonDependency | undefined;
@@ -1648,8 +1656,12 @@ export abstract class VersionPolicy {
     // @internal
     static load(versionPolicyJson: IVersionPolicyJson): VersionPolicy | undefined;
     get policyName(): string;
+    // @deprecated (undocumented)
     setDependenciesBeforeCommit(packageName: string, configuration: RushConfiguration): void;
+    setDependenciesBeforeCommitAsync(packageName: string, configuration: RushConfiguration): Promise<void>;
+    // @deprecated (undocumented)
     setDependenciesBeforePublish(packageName: string, configuration: RushConfiguration): void;
+    setDependenciesBeforePublishAsync(packageName: string, configuration: RushConfiguration): Promise<void>;
     abstract validate(versionString: string, packageName: string): void;
 }
 

libraries/rush-lib/src/api/CommonVersionsConfiguration.ts

@@ -186,17 +186,42 @@ export class CommonVersionsConfiguration {
   }
 
   /**
-   * Loads the common-versions.json data from the specified file path.
-   * If the file has not been created yet, then an empty object is returned.
+   * @deprecated Use {@link CommonVersionsConfiguration.loadFromFileAsync} method instead.
    */
   public static loadFromFile(
     jsonFilePath: string,
     rushConfiguration?: RushConfiguration
   ): CommonVersionsConfiguration {
     let commonVersionsJson: ICommonVersionsJson | undefined = undefined;
-
-    if (FileSystem.exists(jsonFilePath)) {
+    try {
       commonVersionsJson = JsonFile.loadAndValidate(jsonFilePath, CommonVersionsConfiguration._jsonSchema);
+    } catch (error) {
+      if (!FileSystem.isNotExistError(error)) {
+        throw error;
+      }
+    }
+
+    return new CommonVersionsConfiguration(commonVersionsJson, jsonFilePath, rushConfiguration);
+  }
+
+  /**
+   * Loads the common-versions.json data from the specified file path.
+   * If the file has not been created yet, then an empty object is returned.
+   */
+  public static async loadFromFileAsync(
+    jsonFilePath: string,
+    rushConfiguration?: RushConfiguration
+  ): Promise<CommonVersionsConfiguration> {
+    let commonVersionsJson: ICommonVersionsJson | undefined = undefined;
+    try {
+      commonVersionsJson = await JsonFile.loadAndValidateAsync(
+        jsonFilePath,
+        CommonVersionsConfiguration._jsonSchema
+      );
+    } catch (error) {
+      if (!FileSystem.isNotExistError(error)) {
+        throw error;
+      }
     }
 
     return new CommonVersionsConfiguration(commonVersionsJson, jsonFilePath, rushConfiguration);
@@ -242,7 +267,7 @@ export class CommonVersionsConfiguration {
   }
 
   /**
-   * Writes the "common-versions.json" file to disk, using the filename that was passed to loadFromFile().
+   * @deprecated Use {@link CommonVersionsConfiguration.saveAsync} method instead.
    */
   public save(): boolean {
     if (this._modified) {
@@ -257,6 +282,22 @@ export class CommonVersionsConfiguration {
     return false;
   }
 
+  /**
+   * Writes the "common-versions.json" file to disk, using the filename that was passed to loadFromFile().
+   */
+  public async saveAsync(): Promise<boolean> {
+    if (this._modified) {
+      await JsonFile.saveAsync(this._serialize(), this.filePath, {
+        updateExistingFile: true,
+        ignoreUndefinedValues: true
+      });
+      this._modified = false;
+      return true;
+    }
+
+    return false;
+  }
+
   /**
    * Returns preferredVersions.
    */