feat: check ancestry when setting recommended version

Author: hcooreman-salesforce

messages/package.md

@@ -49,3 +49,15 @@ Can't retrieve package metadata. The org you specified doesn't have the required
 # recommendedVersionIdApiPriorTo66Error
 
 To enable Recommended Version, use API version 66.0 or higher.
+
+# skipAncestorCheckRequiresRecommendedVersionIdError
+
+Skip ancestor check requires a Recommended Version ID.
+
+# noPackageVersionsForGivenPackage2FoundError
+
+No package versions were found for the given Package 2 ID (0Ho). At least one released package version must exist.
+
+# recommendedVersionNotAncestorOfPriorVersionError
+
+The new recommended version is not an ancestor of the previous recommended version. To bypass this check, use the --skip-ancestor-check CLI flag.

src/interfaces/packagingInterfacesAndType.ts

@@ -63,6 +63,7 @@ export type PackageUpdateOptions = {
   PackageErrorUsername?: string;
   AppAnalyticsEnabled?: boolean;
   RecommendedVersionId?: string;
+  SkipAncestorCheck?: boolean;
 };
 
 export type PackageIdType =

src/package/package.ts

@@ -15,6 +15,7 @@
  */
 import type { Schema } from '@jsforce/jsforce-node';
 import { Connection, Messages, SfError, SfProject } from '@salesforce/core';
+import { DirectedGraph } from 'graphology';
 import {
   ConvertPackageOptions,
   PackageCreateOptions,
@@ -48,6 +49,9 @@ const packagePrefixes = {
 Messages.importMessagesDirectory(__dirname);
 const messages = Messages.loadMessages('@salesforce/packaging', 'package');
 
+const packageVersionQuery = 'SELECT SubscriberPackageVersionId, AncestorId, RecommendedVersionId FROM Package2Version';
+const package2Query = 'SELECT RecommendedVersionId FROM Package2';
+
 export const Package2Fields = [
   'Id',
   'IsDeleted',
@@ -325,6 +329,14 @@ export class Package {
         throw messages.createError('recommendedVersionIdApiPriorTo66Error');
       }
 
+      if (opts.SkipAncestorCheck !== undefined && opts.RecommendedVersionId === undefined) {
+        throw messages.createError('skipAncestorCheckRequiresRecommendedVersionIdError');
+      }
+
+      if (opts.SkipAncestorCheck === undefined && opts.RecommendedVersionId !== undefined) {
+        await this.checkRecommendedVersionAncestors(opts);
+      }
+
       const result = await this.options.connection.tooling.update('Package2', opts);
       if (!result.success) {
         throw new SfError(result.errors.join(', '));
@@ -354,4 +366,67 @@ export class Package {
     }
     return this.packageData;
   }
+
+  /**
+   *
+   * @param options
+   */
+  private async checkRecommendedVersionAncestors(opts: PackageUpdateOptions): Promise<void> {
+    if (opts.RecommendedVersionId === undefined) {
+      return;
+    }
+
+    const queryP2 = `${package2Query} WHERE Id = '${this.packageId}'`;
+    const priorRecommendedVersionId = (await this.options.connection.tooling.query<PackagingSObjects.Package2>(queryP2))
+      .records[0].RecommendedVersionId;
+
+    if (priorRecommendedVersionId === undefined || opts.RecommendedVersionId === priorRecommendedVersionId) {
+      return;
+    }
+
+    const queryP2V = `${packageVersionQuery} WHERE Package2Id = '${this.packageId}'`;
+    const result = await this.options.connection.tooling.query<PackageVersionListResult>(queryP2V);
+
+    if (result.totalSize === 0) {
+      throw messages.createError('noPackageVersionsForGivenPackage2FoundError');
+    } else if (result.totalSize === 1) {
+      return;
+    }
+
+    const graph = new DirectedGraph();
+    const stack: string[] = [opts.RecommendedVersionId];
+    const visited: Set<string> = new Set([opts.RecommendedVersionId]);
+
+    result.records.forEach((record) => {
+      graph.addNode(record.SubscriberPackageVersionId);
+
+      if (record.AncestorId) {
+        graph.addNode(record.AncestorId);
+        graph.addEdge(record.SubscriberPackageVersionId, record.AncestorId);
+      }
+    });
+
+    if (
+      graph.outDegree(opts.RecommendedVersionId) > 0 &&
+      result.records.some((record) => record.SubscriberPackageVersionId === priorRecommendedVersionId)
+    ) {
+      while (stack.length > 0) {
+        const node = stack.pop()!;
+
+        for (const neighbor of graph.neighbors(node)) {
+          if (neighbor === priorRecommendedVersionId) {
+            return;
+          }
+
+          if (!visited.has(neighbor)) {
+            visited.add(neighbor);
+            stack.push(neighbor);
+          }
+        }
+      }
+      throw messages.createError('recommendedVersionNotAncestorOfPriorVersionError');
+    } else if (graph.outDegree(opts.RecommendedVersionId) === 0) {
+      return;
+    }
+  }
 }

test/package/package.test.ts

@@ -192,13 +192,26 @@ describe('Package', () => {
 
       let objProvided = '';
       let optsProvided: PackageUpdateOptions = { Id: '' };
+      let queryProvided = '';
       const conn = {
         tooling: {
           update: (obj: string, opts: PackageUpdateOptions) => {
             objProvided = obj;
             optsProvided = opts;
             return { success: true };
           },
+          query: (query: string) => {
+            queryProvided = query;
+            return {
+              records: [
+                {
+                  Id: pkgId,
+                  RecommendedVersionId: '04tasdsadfasdf',
+                },
+              ],
+              totalSize: 1,
+            };
+          },
         },
         getApiVersion: () => '66.0',
       } as unknown as Connection;
@@ -212,6 +225,7 @@ describe('Package', () => {
       expect(objProvided).to.equal('Package2');
       expect(optsProvided.Id).to.equal(pkgId);
       expect(optsProvided.RecommendedVersionId).to.equal('04tasdsadfasdf');
+      expect(queryProvided).to.equal(`SELECT RecommendedVersionId FROM Package2 WHERE Id = '${pkgId}'`);
     });
 
     it('should error if RecommendedVersionId is defined for api version < 66.0', async () => {