feat(toolkit-lib): add a return type for toolkit.diff() (#368)

`toolkit.diff()` now returns a `TemplateDiff` for each stack it diffs.

Closes aws/aws-cdk#33182

---
By submitting this pull request, I confirm that my contribution is made
under the terms of the Apache-2.0 license

Author: kaizencc

Diff for: packages/@aws-cdk/tmp-toolkit-helpers/src/api/diff/diff-formatter.ts

@@ -120,13 +120,6 @@ export interface TemplateInfo {
    */
   readonly changeSet?: any;
 
-  /**
-   * The name of the stack
-   *
-   * @default undefined
-   */
-  readonly stackName?: string;
-
   /**
    * Whether or not there are any imported resources
    *
@@ -151,21 +144,31 @@ export class DiffFormatter {
   private readonly ioHelper: IoHelper;
   private readonly oldTemplate: any;
   private readonly newTemplate: cxapi.CloudFormationStackArtifact;
-  private readonly stackName?: string;
+  private readonly stackName: string;
   private readonly changeSet?: any;
   private readonly nestedStacks: { [nestedStackLogicalId: string]: NestedStackTemplates } | undefined;
   private readonly isImport: boolean;
 
+  /**
+   * Stores the TemplateDiffs that get calculated in this DiffFormatter,
+   * indexed by the stack name.
+   */
+  private _diffs: { [name: string]: TemplateDiff } = {};
+
   constructor(props: DiffFormatterProps) {
     this.ioHelper = props.ioHelper;
     this.oldTemplate = props.templateInfo.oldTemplate;
     this.newTemplate = props.templateInfo.newTemplate;
-    this.stackName = props.templateInfo.stackName;
+    this.stackName = props.templateInfo.newTemplate.stackName;
     this.changeSet = props.templateInfo.changeSet;
     this.nestedStacks = props.templateInfo.nestedStacks;
     this.isImport = props.templateInfo.isImport ?? false;
   }
 
+  public get diffs() {
+    return this._diffs;
+  }
+
   /**
    * Format the stack diff
    */
@@ -184,11 +187,12 @@ export class DiffFormatter {
 
   private formatStackDiffHelper(
     oldTemplate: any,
-    stackName: string | undefined,
+    stackName: string,
     nestedStackTemplates: { [nestedStackLogicalId: string]: NestedStackTemplates } | undefined,
     options: ReusableStackDiffOptions,
   ) {
     let diff = fullDiff(oldTemplate, this.newTemplate.template, this.changeSet, this.isImport);
+    this._diffs[stackName] = diff;
 
     // The stack diff is formatted via `Formatter`, which takes in a stream
     // and sends its output directly to that stream. To faciliate use of the
@@ -277,6 +281,7 @@ export class DiffFormatter {
     const ioDefaultHelper = new IoDefaultMessages(this.ioHelper);
 
     const diff = fullDiff(this.oldTemplate, this.newTemplate.template, this.changeSet);
+    this._diffs[this.stackName] = diff;
 
     if (diffRequiresApproval(diff, options.requireApproval)) {
       // The security diff is formatted via `Formatter`, which takes in a stream

Diff for: packages/@aws-cdk/toolkit-lib/lib/actions/diff/private/helpers.ts

@@ -91,7 +91,6 @@ async function cfnDiff(
     templateInfos.push({
       oldTemplate: currentTemplate,
       newTemplate: stack,
-      stackName: stack.stackName,
       isImport: !!resourcesToImport,
       nestedStacks,
       changeSet,
@@ -167,3 +166,25 @@ export function determinePermissionType(
     return PermissionChangeType.NONE;
   }
 }
+
+/**
+ * Appends all properties from obj2 to obj1.
+ * obj2 values take priority in the case of collisions.
+ *
+ * @param obj1 The object to modify
+ * @param obj2 The object to consume
+ *
+ * @returns obj1 with all properties from obj2
+ */
+export function appendObject<T>(
+  obj1: { [name: string]: T },
+  obj2: { [name: string]: T },
+): { [name: string]: T } {
+  // Directly modify obj1 by adding all properties from obj2
+  for (const key in obj2) {
+    obj1[key] = obj2[key];
+  }
+
+  // Return the modified obj1
+  return obj1;
+}

Diff for: packages/@aws-cdk/toolkit-lib/lib/toolkit/toolkit.ts

@@ -1,4 +1,5 @@
 import * as path from 'node:path';
+import type { TemplateDiff } from '@aws-cdk/cloudformation-diff';
 import * as cxapi from '@aws-cdk/cx-api';
 import * as chalk from 'chalk';
 import * as chokidar from 'chokidar';
@@ -23,7 +24,7 @@ import {
 } from '../actions/deploy/private';
 import { type DestroyOptions } from '../actions/destroy';
 import type { DiffOptions } from '../actions/diff';
-import { determinePermissionType, makeTemplateInfos as prepareDiff } from '../actions/diff/private';
+import { appendObject, determinePermissionType, makeTemplateInfos as prepareDiff } from '../actions/diff/private';
 import { type ListOptions } from '../actions/list';
 import type { RefactorOptions } from '../actions/refactor';
 import { type RollbackOptions } from '../actions/rollback';
@@ -300,7 +301,7 @@ export class Toolkit extends CloudAssemblySourceBuilder {
   /**
    * Diff Action
    */
-  public async diff(cx: ICloudAssemblySource, options: DiffOptions): Promise<void> {
+  public async diff(cx: ICloudAssemblySource, options: DiffOptions): Promise<{ [name: string]: TemplateDiff}> {
     const ioHelper = asIoHelper(this.ioHost, 'diff');
     const selectStacks = options.stacks ?? ALL_STACKS;
     const synthSpan = await ioHelper.span(SPAN.SYNTH_ASSEMBLY).begin({ stacks: selectStacks });
@@ -319,7 +320,7 @@ export class Toolkit extends CloudAssemblySourceBuilder {
     let formattedStackDiff = '';
 
     const templateInfos = await prepareDiff(ioHelper, stacks, deployments, await this.sdkProvider('diff'), options);
-
+    const templateDiffs: { [name: string]: TemplateDiff } = {};
     for (const templateInfo of templateInfos) {
       const formatter = new DiffFormatter({
         ioHelper,
@@ -340,14 +341,15 @@ export class Toolkit extends CloudAssemblySourceBuilder {
         formattedStackDiff = diff.formattedDiff;
         diffs = diff.numStacksWithChanges;
       }
+      appendObject(templateDiffs, formatter.diffs);
     }
 
     await diffSpan.end(`✨ Number of stacks with differences: ${diffs}`, {
       formattedSecurityDiff,
       formattedStackDiff,
     });
 
-    return;
+    return templateDiffs;
   }
 
   /**

Diff for: packages/@aws-cdk/toolkit-lib/test/_fixtures/two-different-stacks/index.ts

@@ -0,0 +1,13 @@
+import * as s3 from 'aws-cdk-lib/aws-s3';
+import * as sqs from 'aws-cdk-lib/aws-sqs';
+import * as core from 'aws-cdk-lib/core';
+
+export default async () => {
+  const app = new core.App({ autoSynth: false });
+  const stack1 = new core.Stack(app, 'Stack1');
+  new s3.Bucket(stack1, 'MyBucket');
+  const stack2 = new core.Stack(app, 'Stack2');
+  new sqs.Queue(stack2, 'MyQueue');
+
+  return app.synth();
+};