feat: diff shows moved resources (#708)

When a resource is moved from one location to another, the `diff`
command will show two entries: an addition and a removal. This PR
augments those entries to show where they moved to and from,
respectively:

<img width="1440" height="709" alt="Drawing 2025-07-15 14 35 02
excalidraw"
src="https://github.com/user-attachments/assets/005c27a0-b433-4203-a3ee-7bfa893d3f47"
/>


This information is not shown by default. To enable it, the user has to
pass `--include-moves` to the CLI, and `includeMoves: true` to the
toolkit.

Closes #362

Depends on #679.

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

---------

Signed-off-by: github-actions <[email protected]>
Co-authored-by: github-actions <[email protected]>

Author: otaviomacedo

packages/@aws-cdk/cloudformation-diff/lib/diff/types.ts

@@ -547,6 +547,12 @@ export interface Resource {
   [key: string]: any;
 }
 
+export interface Move {
+  readonly direction: 'from' | 'to';
+  readonly stackName: string;
+  readonly resourceLogicalId: string;
+}
+
 /**
  * Change to a single resource between two CloudFormation templates
  *
@@ -568,6 +574,8 @@ export class ResourceDifference implements IDifference<Resource> {
    */
   public isImport?: boolean;
 
+  public move?: Move;
+
   /** Property-level changes on the resource */
   private readonly propertyDiffs: { [key: string]: PropertyDifference<any> };
 

packages/@aws-cdk/cloudformation-diff/lib/format.ts

@@ -1,6 +1,6 @@
 import { format } from 'util';
 import * as chalk from 'chalk';
-import type { DifferenceCollection, TemplateDiff } from './diff/types';
+import type { DifferenceCollection, Move, TemplateDiff } from './diff/types';
 import { deepEqual } from './diff/util';
 import type { Difference, ResourceDifference } from './diff-template';
 import { isPropertyDifference, ResourceImpact } from './diff-template';
@@ -166,8 +166,15 @@ export class Formatter {
 
     const resourceType = diff.isRemoval ? diff.oldResourceType : diff.newResourceType;
 
-    // eslint-disable-next-line @stylistic/max-len
-    this.print(`${this.formatResourcePrefix(diff)} ${this.formatValue(resourceType, chalk.cyan)} ${this.formatLogicalId(logicalId)} ${this.formatImpact(diff.changeImpact)}`.trimEnd());
+    const message = [
+      this.formatResourcePrefix(diff),
+      this.formatValue(resourceType, chalk.cyan),
+      this.formatLogicalId(logicalId),
+      this.formatImpact(diff.changeImpact),
+      this.formatMove(diff.move),
+    ].filter(Boolean).join(' ');
+
+    this.print(message);
 
     if (diff.isUpdate) {
       const differenceCount = diff.differenceCount;
@@ -239,6 +246,10 @@ export class Formatter {
     }
   }
 
+  private formatMove(move?: Move): string {
+    return !move ? '' : chalk.yellow('(OR', chalk.italic(chalk.bold('move')), `${move.direction} ${move.stackName}.${move.resourceLogicalId} via refactoring)`);
+  }
+
   /**
    * Renders a tree of differences under a particular name.
    * @param name    - the name of the root of the tree.

packages/@aws-cdk/toolkit-lib/lib/actions/diff/index.ts

@@ -129,4 +129,12 @@ export interface DiffOptions {
    * @default 3
    */
   readonly contextLines?: number;
+
+  /**
+   * Whether to include resource moves in the diff. These are the same moves that are detected
+   * by the `refactor` command.
+   *
+   * @default false
+   */
+  readonly includeMoves?: boolean;
 }

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

@@ -13,6 +13,7 @@ import type { ResourcesToImport } from '../../../api/resource-import';
 import { removeNonImportResources, ResourceMigrator } from '../../../api/resource-import';
 import { ToolkitError } from '../../../toolkit/toolkit-error';
 import { deserializeStructure, formatErrorMessage } from '../../../util';
+import { mappingsByEnvironment } from '../../refactor/index';
 
 export function prepareDiff(
   ioHelper: IoHelper,
@@ -67,6 +68,10 @@ async function cfnDiff(
   const templateInfos = [];
   const methodOptions = (options.method?.options ?? {}) as ChangeSetDiffOptions;
 
+  const allMappings = options.includeMoves
+    ? await mappingsByEnvironment(stacks.stackArtifacts, sdkProvider, true)
+    : [];
+
   // Compare N stacks against deployed templates
   for (const stack of stacks.stackArtifacts) {
     const templateWithNestedStacks = await deployments.readCurrentTemplateWithNestedStacks(
@@ -93,12 +98,17 @@ async function cfnDiff(
       methodOptions.importExistingResources,
     ) : undefined;
 
+    const mappings = allMappings.find(m =>
+      m.environment.region === stack.environment.region && m.environment.account === stack.environment.account,
+    )?.mappings ?? {};
+
     templateInfos.push({
       oldTemplate: currentTemplate,
       newTemplate: stack,
       isImport: !!resourcesToImport,
       nestedStacks,
       changeSet,
+      mappings,
     });
   }
 

packages/@aws-cdk/toolkit-lib/lib/actions/refactor/index.ts

@@ -1,6 +1,8 @@
+import type * as cxapi from '@aws-cdk/cx-api';
 import type { StackSelector } from '../../api';
+import type { SdkProvider } from '../../api/aws-auth/sdk-provider';
 import type { ExcludeList } from '../../api/refactoring';
-import { InMemoryExcludeList, NeverExclude } from '../../api/refactoring';
+import { groupStacks, InMemoryExcludeList, NeverExclude, RefactoringContext } from '../../api/refactoring';
 import { ToolkitError } from '../../toolkit/toolkit-error';
 
 type MappingType = 'auto' | 'explicit';
@@ -142,3 +144,28 @@ export function parseMappingGroups(s: string) {
     }
   }
 }
+
+export interface EnvironmentSpecificMappings {
+  readonly environment: cxapi.Environment;
+  readonly mappings: Record<string, string>;
+}
+
+export async function mappingsByEnvironment(
+  stackArtifacts: cxapi.CloudFormationStackArtifact[],
+  sdkProvider: SdkProvider,
+  ignoreModifications?: boolean,
+): Promise<EnvironmentSpecificMappings[]> {
+  const groups = await groupStacks(sdkProvider, stackArtifacts, []);
+  return groups.map((group) => {
+    const context = new RefactoringContext({
+      ...group,
+      ignoreModifications,
+    });
+    return {
+      environment: context.environment,
+      mappings: Object.fromEntries(
+        context.mappings.map((m) => [m.source.toLocationString(), m.destination.toLocationString()]),
+      ),
+    };
+  });
+}

packages/@aws-cdk/toolkit-lib/lib/api/diff/diff-formatter.ts

@@ -5,6 +5,7 @@ import {
   formatSecurityChanges,
   fullDiff,
   mangleLikeCloudFormation,
+  type ResourceDifference,
   type TemplateDiff,
 } from '@aws-cdk/cloudformation-diff';
 import type * as cxapi from '@aws-cdk/cx-api';
@@ -122,6 +123,14 @@ export interface TemplateInfo {
   readonly nestedStacks?: {
     [nestedStackLogicalId: string]: NestedStackTemplates;
   };
+
+  /**
+   * Mappings of old locations to new locations. If these are provided,
+   * for all resources that were moved, their corresponding addition
+   * and removal lines will be augmented with the location they were
+   * moved fom and to, respectively.
+   */
+  readonly mappings?: Record<string, string>;
 }
 
 /**
@@ -134,6 +143,7 @@ export class DiffFormatter {
   private readonly changeSet?: any;
   private readonly nestedStacks: { [nestedStackLogicalId: string]: NestedStackTemplates } | undefined;
   private readonly isImport: boolean;
+  private readonly mappings: Record<string, string>;
 
   /**
    * Stores the TemplateDiffs that get calculated in this DiffFormatter,
@@ -148,6 +158,7 @@ export class DiffFormatter {
     this.changeSet = props.templateInfo.changeSet;
     this.nestedStacks = props.templateInfo.nestedStacks;
     this.isImport = props.templateInfo.isImport ?? false;
+    this.mappings = props.templateInfo.mappings ?? {};
   }
 
   public get diffs() {
@@ -159,16 +170,38 @@ export class DiffFormatter {
    * If it creates the diff, it stores the result in a map for
    * easier retrieval later.
    */
-  private diff(stackName?: string, oldTemplate?: any) {
+  private diff(stackName?: string, oldTemplate?: any, mappings: Record<string, string> = {}) {
     const realStackName = stackName ?? this.stackName;
 
     if (!this._diffs[realStackName]) {
-      this._diffs[realStackName] = fullDiff(
+      const templateDiff = fullDiff(
         oldTemplate ?? this.oldTemplate,
         this.newTemplate.template,
         this.changeSet,
         this.isImport,
       );
+
+      const setMove = (change: ResourceDifference, direction: 'from' | 'to', location?: string)=> {
+        if (location != null) {
+          const [sourceStackName, sourceLogicalId] = location.split('.');
+          change.move = {
+            direction,
+            stackName: sourceStackName,
+            resourceLogicalId: sourceLogicalId,
+          };
+        }
+      };
+
+      templateDiff.resources.forEachDifference((id, change) => {
+        const location = `${realStackName}.${id}`;
+        if (change.isAddition && Object.values(mappings).includes(location)) {
+          setMove(change, 'from', Object.keys(mappings).find(k => mappings[k] === location));
+        } else if (change.isRemoval && Object.keys(mappings).includes(location)) {
+          setMove(change, 'to', mappings[location]);
+        }
+      });
+
+      this._diffs[realStackName] = templateDiff;
     }
     return this._diffs[realStackName];
   }
@@ -199,6 +232,7 @@ export class DiffFormatter {
       this.stackName,
       this.nestedStacks,
       options,
+      this.mappings,
     );
   }
 
@@ -207,8 +241,9 @@ export class DiffFormatter {
     stackName: string,
     nestedStackTemplates: { [nestedStackLogicalId: string]: NestedStackTemplates } | undefined,
     options: ReusableStackDiffOptions,
+    mappings: Record<string, string> = {},
   ) {
-    let diff = this.diff(stackName, oldTemplate);
+    let diff = this.diff(stackName, oldTemplate, mappings);
 
     // The stack diff is formatted via `Formatter`, which takes in a stream
     // and sends its output directly to that stream. To facilitate use of the
@@ -279,6 +314,7 @@ export class DiffFormatter {
         nestedStack.physicalName ?? nestedStackLogicalId,
         nestedStack.nestedStackTemplates,
         options,
+        this.mappings,
       );
       numStacksWithChanges += nextDiff.numStacksWithChanges;
       formattedDiff += nextDiff.formattedDiff;

packages/@aws-cdk/toolkit-lib/lib/api/refactoring/cloudformation.ts

@@ -31,16 +31,19 @@ export class ResourceLocation {
   }
 
   public toPath(): string {
-    const stack = this.stack;
-    const resource = stack.template.Resources?.[this.logicalResourceId];
+    const resource = this.stack.template.Resources?.[this.logicalResourceId];
     const result = resource?.Metadata?.['aws:cdk:path'];
 
     if (result != null) {
       return result;
     }
 
     // If the path is not available, we can use stack name and logical ID
-    return `${stack.stackName}.${this.logicalResourceId}`;
+    return this.toLocationString();
+  }
+
+  public toLocationString() {
+    return `${this.stack.stackName}.${this.logicalResourceId}`;
   }
 
   public getType(): string {

packages/@aws-cdk/toolkit-lib/lib/api/refactoring/context.ts

@@ -13,11 +13,12 @@ import { equalSets } from '../../util/sets';
  */
 type ResourceMove = [ResourceLocation[], ResourceLocation[]];
 
-export interface RefactorManagerOptions {
+export interface RefactoringContextOptions {
   environment: Environment;
   localStacks: CloudFormationStack[];
   deployedStacks: CloudFormationStack[];
   overrides?: ResourceMapping[];
+  ignoreModifications?: boolean;
 }
 
 /**
@@ -28,9 +29,9 @@ export class RefactoringContext {
   private readonly ambiguousMoves: ResourceMove[] = [];
   public readonly environment: Environment;
 
-  constructor(props: RefactorManagerOptions) {
+  constructor(props: RefactoringContextOptions) {
     this.environment = props.environment;
-    const moves = resourceMoves(props.deployedStacks, props.localStacks, 'direct');
+    const moves = resourceMoves(props.deployedStacks, props.localStacks, 'direct', props.ignoreModifications);
     const additionalOverrides = structuralOverrides(props.deployedStacks, props.localStacks);
     const overrides = (props.overrides ?? []).concat(additionalOverrides);
     const [nonAmbiguousMoves, ambiguousMoves] = partitionByAmbiguity(overrides, moves);
@@ -70,20 +71,28 @@ export class RefactoringContext {
  *
  */
 function structuralOverrides(deployedStacks: CloudFormationStack[], localStacks: CloudFormationStack[]): ResourceMapping[] {
-  const moves = resourceMoves(deployedStacks, localStacks, 'opposite');
+  const moves = resourceMoves(deployedStacks, localStacks, 'opposite', true);
   const [nonAmbiguousMoves] = partitionByAmbiguity([], moves);
   return resourceMappings(nonAmbiguousMoves);
 }
 
-function resourceMoves(before: CloudFormationStack[], after: CloudFormationStack[], direction: GraphDirection): ResourceMove[] {
+function resourceMoves(
+  before: CloudFormationStack[],
+  after: CloudFormationStack[],
+  direction: GraphDirection = 'direct',
+  ignoreModifications: boolean = false): ResourceMove[] {
   const digestsBefore = resourceDigests(before, direction);
   const digestsAfter = resourceDigests(after, direction);
 
-  const stackNames = (stacks: CloudFormationStack[]) => stacks.map((s) => s.stackName).sort().join(', ');
-  if (!isomorphic(digestsBefore, digestsAfter)) {
+  const stackNames = (stacks: CloudFormationStack[]) =>
+    stacks
+      .map((s) => s.stackName)
+      .sort()
+      .join(', ');
+  if (!(ignoreModifications || isomorphic(digestsBefore, digestsAfter))) {
     const message = [
       'A refactor operation cannot add, remove or update resources. Only resource moves and renames are allowed. ',
-      'Run \'cdk diff\' to compare the local templates to the deployed stacks.\n',
+      "Run 'cdk diff' to compare the local templates to the deployed stacks.\n",
       `Deployed stacks: ${stackNames(before)}`,
       `Local stacks: ${stackNames(after)}`,
     ];

packages/@aws-cdk/toolkit-lib/lib/api/refactoring/index.ts

@@ -17,6 +17,7 @@ import type { MappingGroup } from '../../actions';
 import { ToolkitError } from '../../toolkit/toolkit-error';
 
 export * from './exclude';
+export * from './context';
 
 interface StackGroup {
   environment: cxapi.Environment;