fix(CodeTransform): show link to docs after errors (#4477)

* fix(CodeTransform): show link to docs after errors

* nit: comment changes

---------

Co-authored-by: David Hasani <[email protected]>

Author: dhasani23

.changes/next-release/Feature-29b29159-d661-4ffe-ae03-2f5473dd6dec.json

@@ -0,0 +1,4 @@
+{
+	"type": "Feature",
+	"description": "Amazon Q CodeTransform: show link to documentation after errors"
+}

packages/toolkit/src/codewhisperer/commands/startTransformByQ.ts

@@ -174,7 +174,7 @@ async function setMaven() {
     } else {
         transformByQState.setMavenName('mvn')
     }
-    getLogger().info(`CodeTransform: using Maven ${transformByQState.getMavenName()}`)
+    getLogger().info(`CodeTransformation: using Maven ${transformByQState.getMavenName()}`)
 }
 
 async function validateJavaHome() {
@@ -218,11 +218,11 @@ async function validateJavaHome() {
             ignoreFocusOut: true,
         })
         if (!javaHome || !javaHome.trim()) {
-            throw new ToolkitError('No JAVA_HOME provided', { code: 'NoJavaHomePath' })
+            throw new ToolkitError('No JDK path provided', { code: 'NoJavaHomePath' })
         }
         transformByQState.setJavaHome(javaHome.trim())
         getLogger().info(
-            `CodeTransform: using JAVA_HOME = ${transformByQState.getJavaHome()} since source JDK does not match Maven JDK`
+            `CodeTransformation: using JAVA_HOME = ${transformByQState.getJavaHome()} since source JDK does not match Maven JDK`
         )
     }
 }
@@ -331,16 +331,17 @@ export async function pollTransformationStatusUntilPlanReady(jobId: string) {
     try {
         await pollTransformationJob(jobId, CodeWhispererConstants.validStatesForGettingPlan)
     } catch (error) {
-        const errorMessage = 'Failed to poll transformation job for plan availability, or job itself failed'
-        getLogger().error(errorMessage, error)
+        const errorMessage = 'Failed to get job status or job itself failed'
+        getLogger().error(`CodeTransformation: ${errorMessage}`, error)
+        transformByQState.setJobFailureErrorMessage(errorMessage)
         throw new ToolkitError(errorMessage, { cause: error as Error })
     }
     let plan = undefined
     try {
         plan = await getTransformationPlan(jobId)
     } catch (error) {
         const errorMessage = 'Failed to get transformation plan'
-        getLogger().error(errorMessage, error)
+        getLogger().error(`CodeTransformation: ${errorMessage}`, error)
         transformByQState.setJobFailureErrorMessage(errorMessage)
         throw new ToolkitError(errorMessage, { cause: error as Error })
     }
@@ -359,7 +360,7 @@ export async function pollTransformationStatusUntilComplete(jobId: string) {
         status = await pollTransformationJob(jobId, CodeWhispererConstants.validStatesForCheckingDownloadUrl)
     } catch (error) {
         const errorMessage = 'Failed to get transformation job status'
-        getLogger().error(errorMessage, error)
+        getLogger().error(`CodeTransformation: ${errorMessage}`, error)
         transformByQState.setJobFailureErrorMessage(errorMessage)
         throw new ToolkitError(errorMessage, { cause: error as Error })
     }
@@ -370,7 +371,7 @@ export async function pollTransformationStatusUntilComplete(jobId: string) {
 export async function finalizeTransformationJob(status: string) {
     if (!(status === 'COMPLETED' || status === 'PARTIALLY_COMPLETED')) {
         const errorMessage = 'Failed to complete transformation'
-        getLogger().error(errorMessage)
+        getLogger().error(`CodeTransformation: ${errorMessage}`)
         sessionPlanProgress['transformCode'] = StepProgress.Failed
         transformByQState.setJobFailureErrorMessage(errorMessage)
         throw new ToolkitError(errorMessage, { code: 'JobDidNotSucceed' })
@@ -395,15 +396,15 @@ export async function validateTransformationJob() {
     try {
         openProjects = await getOpenProjects()
     } catch (err) {
-        getLogger().error('Failed to get open projects: ', err)
+        getLogger().error(`CodeTransformation: Failed to get open projects: ${err}`)
         throw err
     }
 
     let validProjects = undefined
     try {
         validProjects = await validateOpenProjects(openProjects)
     } catch (err) {
-        getLogger().error('Selected project is not Java 8, not Java 11, or does not use Maven', err)
+        getLogger().error(`CodeTransformation: No open projects contain a .java file or a pom.xml file ${err}`)
         throw err
     }
 
@@ -517,8 +518,8 @@ export async function transformationJobErrorHandler(error: any) {
         codeTransformTelemetryState.setResultStatus('JobFailed')
         let displayedErrorMessage =
             transformByQState.getJobFailureErrorMessage() || CodeWhispererConstants.transformByQFailedMessage
-        if (transformByQState.getJobFailureReason() !== '') {
-            displayedErrorMessage += `: ${transformByQState.getJobFailureReason()}`
+        if (transformByQState.getJobFailureMetadata() !== '') {
+            displayedErrorMessage += `: ${transformByQState.getJobFailureMetadata()}`
         }
         void vscode.window.showErrorMessage(displayedErrorMessage)
     }
@@ -534,8 +535,7 @@ export async function transformationJobErrorHandler(error: any) {
     if (sessionPlanProgress['returnCode'] !== StepProgress.Succeeded) {
         sessionPlanProgress['returnCode'] = StepProgress.Failed
     }
-    // Log error to VSCode logs
-    getLogger().error('Amazon Q Code Transform', error)
+    getLogger().error(`CodeTransformation: ${error}`)
 }
 
 export async function cleanupTransformationJob(intervalId: NodeJS.Timeout | undefined) {
@@ -578,7 +578,7 @@ export async function confirmStopTransformByQ(
         stopTransformByQButton
     )
     if (resp === stopTransformByQButton && transformByQState.isRunning()) {
-        getLogger().verbose('User requested to stop transform by Q. Stopping transform by Q.')
+        getLogger().info('CodeTransformation: User requested to stop transformation. Stopping transformation.')
         transformByQState.setToCancelled()
         await vscode.commands.executeCommand('aws.amazonq.refresh')
         await vscode.commands.executeCommand('setContext', 'gumby.isStopButtonAvailable', false)

packages/toolkit/src/codewhisperer/models/constants.ts

@@ -274,18 +274,18 @@ export const newCustomizationMessage = 'You have access to new CodeWhisperer cus
 
 export const newCustomizationAvailableKey = 'CODEWHISPERER_NEW_CUSTOMIZATION_AVAILABLE'
 
-// Transform by Q
+// Amazon Q CodeTransformation
 
 export const selectProjectPrompt = 'Select the project you want to transform'
 
 export const unsupportedJavaVersionSelectedMessage =
-    'Thank you for trying our product. We currently only support Java 8 and 11. We appreciate you taking the time to use the product, and hope to expand support to more Java versions in the future. Please see: https://docs.aws.amazon.com/amazonq/latest/aws-builder-use-ug/code-transformation.html'
+    'Thank you for trying our product. We currently only support Java 8 and 11. We appreciate you taking the time to use the product, and hope to expand support to more Java versions in the future. Please see: https://docs.aws.amazon.com/amazonq/latest/aws-builder-use-ug/code-transformation.html#prerequisites'
 
 export const transformByQWindowTitle = 'Amazon Q Code Transformation'
 
-export const stopTransformByQMessage = 'Stop Transformation?'
+export const stopTransformByQMessage = 'Stop transformation?'
 
-export const stoppingTransformByQMessage = 'Stopping Transformation...'
+export const stoppingTransformByQMessage = 'Stopping transformation...'
 
 export const transformByQFailedMessage = 'Transformation failed'
 
@@ -296,10 +296,10 @@ export const transformByQCompletedMessage = 'Transformation completed'
 export const transformByQPartiallyCompletedMessage = 'Transformation partially completed'
 
 export const noPomXmlFoundMessage =
-    'None of your open Java projects are supported by Amazon Q Code Transformation. We were unable to find a pom.xml in any of your Java projects. We only support Java projects built on Maven at the moment. Please see: https://docs.aws.amazon.com/amazonq/latest/aws-builder-use-ug/code-transformation.html'
+    'None of your open Java projects are supported by Amazon Q Code Transformation. We were unable to find a pom.xml in any of your Java projects. We only support Java projects built on Maven at the moment. Please see: https://docs.aws.amazon.com/amazonq/latest/aws-builder-use-ug/code-transformation.html#prerequisites'
 
 export const noActiveIdCMessage =
-    'Amazon Q Code Transformation requires an active IAM Identity Center connection. Please see: https://docs.aws.amazon.com/amazonq/latest/aws-builder-use-ug/code-transformation.html'
+    'Amazon Q Code Transformation requires an active IAM Identity Center connection. Please see: https://docs.aws.amazon.com/amazonq/latest/aws-builder-use-ug/code-transformation.html#prerequisites'
 
 export const noOngoingJobMessage = 'No job is in-progress at the moment'
 
@@ -309,26 +309,31 @@ export const cancellationInProgressMessage = 'Cancellation is in-progress'
 
 export const errorStoppingJobMessage = 'Error stopping job'
 
-export const errorDownloadingDiffMessage = 'Amazon Q Code Transformation experienced an error when downloading the diff'
+export const errorDownloadingDiffMessage =
+    'Amazon Q Code Transformation experienced an error when downloading the diff. Please see: https://docs.aws.amazon.com/amazonq/latest/aws-builder-use-ug/troubleshooting-code-transformation.html#w24aac14c20c19c11'
+
+export const errorDeserializingDiffMessage =
+    'Amazon Q Code Transformation experienced an error during the deserialization of the downloaded result archive. Please see: https://docs.aws.amazon.com/amazonq/latest/aws-builder-use-ug/troubleshooting-code-transformation.html#w24aac14c20c19c11'
+
+export const buildLogsDocumentationMessage =
+    'Please also see https://docs.aws.amazon.com/amazonq/latest/aws-builder-use-ug/troubleshooting-code-transformation.html#w24aac14c20c19b7'
 
 export const viewProposedChangesMessage =
     'Transformation job completed. You can view the transformation summary along with the proposed changes and accept or reject them in the Proposed Changes panel.'
 
 export const changesAppliedMessage = 'Changes applied'
 
 export const noSupportedJavaProjectsFoundMessage =
-    'None of your open projects are supported by Amazon Q Code Transformation. We were unable to find a Java project. We only support Java projects built on Maven at the moment. Please see: https://docs.aws.amazon.com/amazonq/latest/aws-builder-use-ug/code-transformation.html'
+    'None of your open projects are supported by Amazon Q Code Transformation. We were unable to find a Java project. We only support Java projects built on Maven at the moment. Please see: https://docs.aws.amazon.com/amazonq/latest/aws-builder-use-ug/code-transformation.html#prerequisites'
 
 export const dependencyDisclaimer =
     'Please confirm you are ready to proceed with the transformation. Amazon Q Code Transformation will upload the application code and its dependency binaries from your machine to start the upgrade. If you have not yet compiled the application on your local machine, please do so once before starting the upgrade. Install Maven to ensure all module dependencies are picked for Transformation.'
 
 export const dependencyFolderName = 'transformation_dependencies_temp_'
 
-export const installErrorMessage =
-    'Failed to execute Maven install. Please see: https://docs.aws.amazon.com/amazonq/latest/aws-builder-use-ug/code-transformation.html'
+export const installErrorMessage = 'Failed to execute Maven install.'
 
-export const dependencyErrorMessage =
-    'Failed to execute Maven copy-dependencies. Please see: https://docs.aws.amazon.com/amazonq/latest/aws-builder-use-ug/code-transformation.html'
+export const dependencyErrorMessage = 'Failed to execute Maven copy-dependencies.'
 
 export const planIntroductionMessage =
     'We reviewed your Java JAVA_VERSION_HERE application and generated a transformation plan. Any code changes made to your application will be done in the sandbox so as to not interfere with your working repository. Once the transformation job is done, we will share the new code which you can review before acccepting the code changes. In the meantime, you can work on your codebase and invoke Q Chat to answer questions about your codebase.'
@@ -347,7 +352,7 @@ export const nonWindowsJava11HomeHelpMessage =
     'Try running "/usr/libexec/java_home -v 11" in a terminal to find this. It should look something like "/Library/Java/JavaVirtualMachines/jdk-11.jdk/Contents/Home"'
 
 export const projectSizeTooLargeMessage =
-    'Your project size exceeds the Amazon Q Code Transformation upload limit of 1GB. Please see: https://docs.aws.amazon.com/amazonq/latest/aws-builder-use-ug/code-transformation.html'
+    'Your project size exceeds the Amazon Q Code Transformation upload limit of 1GB. Please see: https://docs.aws.amazon.com/amazonq/latest/aws-builder-use-ug/code-transformation.html#prerequisites'
 
 export const JDK8VersionNumber = '52'
 

packages/toolkit/src/codewhisperer/models/model.ts

@@ -281,7 +281,7 @@ export class TransformByQState {
 
     private polledJobStatus: string = ''
 
-    private jobFailureReason: string = ''
+    private jobFailureMetadata: string = ''
 
     private payloadFilePath: string = ''
 
@@ -361,8 +361,8 @@ export class TransformByQState {
         return this.projectCopyFilePath
     }
 
-    public getJobFailureReason() {
-        return this.jobFailureReason
+    public getJobFailureMetadata() {
+        return this.jobFailureMetadata
     }
 
     public getPayloadFilePath() {
@@ -453,8 +453,8 @@ export class TransformByQState {
         this.projectCopyFilePath = filePath
     }
 
-    public setJobFailureReason(reason: string) {
-        this.jobFailureReason = reason
+    public setJobFailureMetadata(data: string) {
+        this.jobFailureMetadata = data
     }
 
     public setPayloadFilePath(payloadFilePath: string) {