From fa5a0652ba428a3c25d6cd1e87263f043e0e0cd8 Mon Sep 17 00:00:00 2001
From: Mohamed ElAsmar <melasmar@amazon.com>
Date: Mon, 25 Nov 2024 14:54:31 -0800
Subject: [PATCH] add some comments

---
 .../lambda-integration-test-updater/README.md |  5 ++-
 .../lib/runtime-updater.ts                    | 44 +++++++++++++++++++
 2 files changed, 47 insertions(+), 2 deletions(-)

diff --git a/tools/@aws-cdk/lambda-integration-test-updater/README.md b/tools/@aws-cdk/lambda-integration-test-updater/README.md
index 5426815dfcd8c..fc74e2b8457af 100644
--- a/tools/@aws-cdk/lambda-integration-test-updater/README.md
+++ b/tools/@aws-cdk/lambda-integration-test-updater/README.md
@@ -6,5 +6,6 @@ This tool updates integration test cases for AWS Lambda runtimes in the AWS CDK
 - Updating integration test files with all runtime information
 - Supporting NodeJS, Python, and Go runtime families
 
-The purpose of this tool is to make sure that we have integration test cases that cover new runtimes, and to so we 
-can detect if there is an issue in the build image to contact SAM team to fix it before releasing the new runtime.
\ No newline at end of file
+The purpose of this tool is to make sure that we have integration test cases that cover new runtimes, and so we 
+can detect if there is an issue in the build image, and to make sure we do not release a new Runtime before its build 
+image got released.
\ No newline at end of file
diff --git a/tools/@aws-cdk/lambda-integration-test-updater/lib/runtime-updater.ts b/tools/@aws-cdk/lambda-integration-test-updater/lib/runtime-updater.ts
index 6e04cb5bf6161..ea72f4bad6342 100644
--- a/tools/@aws-cdk/lambda-integration-test-updater/lib/runtime-updater.ts
+++ b/tools/@aws-cdk/lambda-integration-test-updater/lib/runtime-updater.ts
@@ -1,11 +1,25 @@
 import {Node, Project, SourceFile, ts} from 'ts-morph';
 import SyntaxKind = ts.SyntaxKind;
 
+/**
+ * RuntimeIntegrationTestUpdater is responsible for updating Lambda runtime integration tests
+ * by analyzing and extracting runtime information from the AWS CDK Lambda runtime source file
+ * and updating corresponding integration test files.
+ *
+ * The class identifies non-deprecated runtimes for each runtime family and updates integration
+ * test files to ensure they include all current supported runtimes.
+ */
 export class RuntimeIntegrationTestUpdater {
   private readonly project: Project;
   private readonly runtimesPerFamily: {[key: string]: string[]};
   private readonly integTestConfigs: {[key:string]: string};
 
+  /**
+   * Creates a new instance of RuntimeIntegrationTestUpdater.
+   *
+   * @param integTestFiles - An object mapping runtime families to their integration test file paths
+   * @param runtimeSourceFilePath - Path to the Lambda runtime source file (defaults to aws-lambda/lib/runtime.ts)
+   */
   constructor(integTestFiles: {[key:string]: string} , runtimeSourceFilePath = __dirname + '../../../../../packages/aws-cdk-lib/aws-lambda/lib/runtime.ts') {
     this.integTestConfigs = integTestFiles;
     this.project = new Project();
@@ -13,6 +27,13 @@ export class RuntimeIntegrationTestUpdater {
     this.runtimesPerFamily = this.getRuntimes(runtimeSourceFile);
   }
 
+  /**
+   * Executes the update process for all configured integration test files.
+   * For each runtime family, this method:
+   * 1. Loads the corresponding integration test file
+   * 2. Updates the runtimes list in the test file
+   * 3. Saves the changes back to disk
+   */
   public async execute(): Promise<void> {
     for (const [runtimeFamily, integTestFile] of Object.entries(this.integTestConfigs)) {
       const integSourceFile = this.project.addSourceFileAtPath(integTestFile);
@@ -21,6 +42,18 @@ export class RuntimeIntegrationTestUpdater {
     }
   }
 
+  /**
+   * Analyzes the runtime source file to extract non-deprecated runtimes for each runtime family.
+   *
+   * This method:
+   * 1. Looks for Runtime class instantiations
+   * 2. Extracts the runtime family and name
+   * 3. Checks if the runtime is deprecated (via JSDoc tags)
+   * 4. Groups non-deprecated runtimes by family
+   *
+   * @param sourceFile - The parsed Runtime.ts source file
+   * @returns An object mapping runtime families to arrays of runtime names
+   */
   private getRuntimes(sourceFile: SourceFile): {[key: string]: string[]} {
     const deprecatedRuntimesPerFamily: {[key: string]: string[]} = {};
 
@@ -56,12 +89,23 @@ export class RuntimeIntegrationTestUpdater {
     return deprecatedRuntimesPerFamily;
   }
 
+  /**
+   * Updates the runtimes list in a given integration test file.
+   *
+   * This method processes the source file to locate and update variable declarations
+   * that contain lists of runtimes for integration testing.
+   *
+   * @param sourceFile - The integration test source file to update
+   * @param runtimes - Array of runtime names to include in the test
+   */
   private async updateRuntimesList(sourceFile: SourceFile, runtimes: string[]): Promise<void> {
     sourceFile.getDescendantsOfKind(SyntaxKind.VariableDeclaration).forEach(varDecl => {
       if (varDecl.getName() === 'runtimes') {
         const initializer = varDecl.getInitializer();
         if (initializer && Node.isArrayLiteralExpression(initializer)) {
           runtimes = runtimes.map(runtime => `Runtime.${runtime}`);
+
+          // Format runtimes array into groups of 6 per line to keep lines under max length and to follow linter rules
           const formattedDeprecatedRuntimes = [];
           for (let i = 0; i < runtimes.length; i += 6) {
             formattedDeprecatedRuntimes.push(`  ${runtimes.slice(i, i + 6).join(', ')}`);