Add rhsRoot defaulting logic for the "sunny day" scenario.

Author: tjprescott

CHANGELOG.md

@@ -1,6 +1,6 @@
 # @azure-tools/rest-api-diff
 
-## 0.2.0 (TBD)
+## 0.2.0 (2025-03-11)
 
 - Fixed issue where relative references would sometimes be resolved incorrectly. `--lhs-root`
   and `--rhs-root` are still needed when compiling TypeSpec. See README.md.

README.md

@@ -116,13 +116,15 @@ debugging purposes.
 
 ## Running against the REST API Specs Repo
 
-These steps assumed that `--lhs` points to a Swagger folder and `--rhs` points to a TypeSpec folder, both within the REST API specs repo. If this is not the case, your steps will differ.
+These steps assume that `--lhs` points to a Swagger folder and `--rhs` points to a TypeSpec folder, both within the REST API specs repo. If this is not the case, your steps will differ.
 
 1. Ensure you have updated the dependencies in your fork by running `npm install` in the REST API specs repo root. You may need to delete `package-lock.json` first. Copy the path to the `node_modules/@typespec/compiler` package.
 2. Set the `TYPESPEC_COMPILER_PATH` environment variable (ideally in .env) to the path you copied in step 1.
 3. Ensure that LHS and RHS point to the appropriate paths in the REST API specs repo.
 4. By convention, if you are comparing hand-written Swagger to TypeSpec, the Swagger should be LHS and the TypeSpec should be RHS. When compiling TypeSpec, you will
-   need to set RHS_ROOT. It will generally be the same path as LHS, but with the "stable" or "preview" segment replaced with "generated".
+   need to set RHS_ROOT. **If you are following the convention, the tool will automatically use the same folder as LHS for RHS_ROOT except changing the "stable" or "preview"
+   folder to "temp", which will subsequently be deleted after the tool completes.** This is so the relative paths get generated and resolve correctly without bulldozing
+   and existing files.
 5. If you are comparing to a multi-versioned TypeSpec, you should probably include the `TYPESPEC_VERSION_SELECTOR` environment variable to ensure you are generating the right version for comparison.
 
 ## Rules

pnpm-lock.yaml

@@ -181,7 +181,7 @@ export class DefinitionRegistry {
       const expVal = this.#expand(val);
       expanded.push(expVal);
     }
-    return expanded.toSorted();
+    return toSorted(expanded);
   }
 
   #expandDerivedClasses(base: any): any {

src/definitions.ts

@@ -21,7 +21,7 @@ export interface DiffClientConfig {
 }
 
 export class DiffClient {
-  private args: any;
+  public args: any;
   private rules: RuleSignature[];
   private lhsParser?: SwaggerParser;
   private rhsParser?: SwaggerParser;
@@ -38,6 +38,8 @@ export class DiffClient {
   public diffResults?: DiffResult;
   /** The output files generated by the diff operation. Available once buildOutput() called. */
   public resultFiles?: ResultFiles;
+  /** The temporary root folder for TypeSpec-generated Swagger. */
+  private tempRhsRoot?: string;
 
   /** Creates an instance of the DiffClient class asynchronously. */
   static async create(config: DiffClientConfig): Promise<DiffClient> {
@@ -47,9 +49,18 @@ export class DiffClient {
     const lhsRoot = client.args["lhs-root"]
       ? path.resolve(client.args["lhs-root"])
       : undefined;
-    const rhsRoot = client.args["rhs-root"]
+
+    let rhsRoot = client.args["rhs-root"]
       ? path.resolve(client.args["rhs-root"])
       : undefined;
+    if (!rhsRoot) {
+      const tempRhsRoot = client.checkDefaultRhsRoot(lhs, rhs);
+      if (tempRhsRoot) {
+        // since we are using the default rhsRoot, we should delete it when we are done.
+        client.tempRhsRoot = tempRhsRoot;
+        rhsRoot = tempRhsRoot;
+      }
+    }
     const lhsParser = await SwaggerParser.create(lhs, lhsRoot, client);
     const rhsParser = await SwaggerParser.create(rhs, rhsRoot, client);
     client.lhsParser = lhsParser;
@@ -66,6 +77,47 @@ export class DiffClient {
     this.args["rhs"] = rhs;
   }
 
+  /**
+   * If the rhsRoot is not provided, rhs points to TypeSpec and the lhs is a folder, use the lhs as the basis
+   * for the rhsRoot.
+   * @param lhs lhs paths
+   * @param rhs rhs paths
+   * @returns the inferred rhsRoot or undefined if it cannot be inferred
+   */
+  private checkDefaultRhsRoot(
+    lhs: string[],
+    rhs: string[]
+  ): string | undefined {
+    if (lhs.length === 1 && rhs.length === 1) {
+      const lhsStat = fs.statSync(lhs[0]);
+      const rhsStat = fs.statSync(rhs[0]);
+      if (lhsStat.isDirectory() && rhsStat.isDirectory()) {
+        // check if the lhs folder is swagger and rhs folder is typespec
+        const lhsFiles = fs.readdirSync(lhs[0]);
+        const lhsSwagger = !lhsFiles.some((x) => x.endsWith(".tsp"));
+        const rhsFiles = fs.readdirSync(rhs[0]);
+        const rhsTypespec = rhsFiles.some((x) => x.endsWith(".tsp"));
+        if (lhsSwagger && rhsTypespec) {
+          const lhsSegments = lhs[0].split(path.sep);
+          const rhsSegments = [];
+          for (const segment of lhsSegments) {
+            if (segment === "preview" || segment === "stable") {
+              rhsSegments.push("temp");
+            } else {
+              rhsSegments.push(segment);
+            }
+          }
+          const rhsRoot = rhsSegments.join(path.sep);
+          console.warn(
+            `WARN: No rhs-root provided. Using '${rhsRoot}' as the rhs-root.`
+          );
+          return rhsRoot;
+        }
+      }
+    }
+    return undefined;
+  }
+
   /**
    * Parses the documents, expanding them into canonical transformations.
    * Upon completion, the lhs and rhs documents will be available for diffing.
@@ -271,6 +323,12 @@ export class DiffClient {
       }
     }
 
+    // delete the tempRhsRoot if used
+    if (this.tempRhsRoot) {
+      console.warn(`WARN: Cleaning up temporary folder '${this.tempRhsRoot}'`);
+      fs.rmdirSync(this.tempRhsRoot, { recursive: true });
+    }
+
     // create inverse files that show only the stuff that has been pruned
     // for diagnostic purposes.
     fs.writeFileSync(