feat(sam): improved TypeScript support

## Problem
TypeScript debugger has a race condition that breaks debugging much of the time. Hard-coded tsconfig also is used which breaks anything more than a very basic typescript lambda.

## Solution
Updated toolkit to generate tsconfig that attempts to match project tsconfig as close as possible, code is compiled into a ts build directory, sam deploys from there on an updated handler path (pointing to build dir). This eliminates the debugger race condition, and much more closely resembles a standard project build eliminating all of our errors. It also matches jetbrains approach here: https://github.com/aws/aws-toolkit-jetbrains/blob/c35ffdbd545c104c2cc5e23bb4dbf02bdc08953a/jetbrains-ultimate/src/software/aws/toolkits/jetbrains/services/lambda/nodejs/NodeJsLambdaBuilder.kt

Code updated:
    src/shared/sam/activation.ts: allow typescript code to be recognized
    src/shared/sam/debugger/awsSamDebugger.ts: code template generation after individual runtime configs are made so ts can update handler path
    src/shared/sam/debugger/typescriptSamDebug.ts: updated build directory process matching jetbrains (most of the updates)
    src/shared/sam/localLambdaRunner.ts: split getting template path and creating the template to facilitate awsSamDebugger.ts changes
    src/test/shared/sam/debugger/samDebugConfigProvider.test.ts: update ts tests

Tested with unit tests, and with several typescript projects including large and small lambdas. New code lines are covered with code coverage.

Author: sseidel16

.changes/next-release/Feature-46a93a97-f979-4c7a-9a8d-f241a30987b6.json

@@ -0,0 +1,4 @@
+{
+	"type": "Feature",
+	"description": "SAM: run/debug now works for a larger variety of TypeScript projects"
+}

src/shared/sam/activation.ts

@@ -187,6 +187,7 @@ async function activateCodeLensProviders(
         supportedLanguages[javaLensProvider.javaLanguage] = javaCodeLensProvider
         supportedLanguages[csLensProvider.csharpLanguage] = csCodeLensProvider
         supportedLanguages[goLensProvider.goLanguage] = goCodeLensProvider
+        supportedLanguages[jsLensProvider.typescriptLanguage] = tsCodeLensProvider
     }
 
     disposables.push(

src/shared/sam/debugger/awsSamDebugger.ts

@@ -49,7 +49,7 @@ import {
     AwsSamDebugConfigurationValidator,
     DefaultAwsSamDebugConfigurationValidator,
 } from './awsSamDebugConfigurationValidator'
-import { makeInputTemplate, makeJsonFiles } from '../localLambdaRunner'
+import { getInputTemplatePath, makeInputTemplate, makeJsonFiles } from '../localLambdaRunner'
 import { SamLocalInvokeCommand } from '../cli/samCliLocalInvoke'
 import { getCredentialsFromStore } from '../../../credentials/credentialsStore'
 import { fromString } from '../../../credentials/providers/credentials'
@@ -464,7 +464,7 @@ export class SamDebugConfigProvider implements vscode.DebugConfigurationProvider
             codeConfig.invokeTarget.projectRoot = pathutil.normalize(
                 resolve(folder.uri.fsPath, config.invokeTarget.projectRoot)
             )
-            templateInvoke.templatePath = await makeInputTemplate(codeConfig)
+            templateInvoke.templatePath = getInputTemplatePath(codeConfig)
         }
 
         const isZip = CloudFormation.isZipLambdaResource(templateResource?.Properties)
@@ -598,6 +598,9 @@ export class SamDebugConfigProvider implements vscode.DebugConfigurationProvider
             envFile: '', // Populated by makeConfig().
             apiPort: apiPort,
             debugPort: debugPort,
+            invokeTarget: {
+                ...config.invokeTarget,
+            },
             lambda: {
                 ...config.lambda,
                 memoryMb: lambdaMemory,
@@ -652,6 +655,13 @@ export class SamDebugConfigProvider implements vscode.DebugConfigurationProvider
                 throw new ToolkitError(message, { code: 'UnsupportedRuntime' })
             }
         }
+
+        // generate template for target=code
+        if (launchConfig.invokeTarget.target === 'code') {
+            const codeConfig = launchConfig as SamLaunchRequestArgs & { invokeTarget: { target: 'code' } }
+            await makeInputTemplate(codeConfig)
+        }
+
         await makeJsonFiles(launchConfig)
 
         // Set the type, then vscode will pass the config to SamDebugSession.attachRequest().

src/shared/sam/debugger/typescriptSamDebug.ts

@@ -3,6 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { existsSync, PathLike, readFileSync } from 'fs'
 import { writeFileSync } from 'fs-extra'
 import * as path from 'path'
 import * as vscode from 'vscode'
@@ -18,6 +19,11 @@ import { DefaultSamLocalInvokeCommand, waitForDebuggerMessages } from '../cli/sa
 import { runLambdaFunction, waitForPort } from '../localLambdaRunner'
 import { SamLaunchRequestArgs } from './awsSamDebugger'
 
+const tsConfigFile = 'aws-toolkit-tsconfig.json'
+
+// use project tsconfig.json as initial base - if unable to parse existing config
+const tsConfigInitialBaseFile = 'tsconfig.json'
+
 /**
  * Launches and attaches debugger to a SAM Node project.
  */
@@ -29,8 +35,7 @@ export async function invokeTypescriptLambda(
     // eslint-disable-next-line @typescript-eslint/unbound-method
     config.onWillAttachDebugger = waitForPort
 
-    const onAfterBuild = () => compileTypeScript(config)
-    const c = (await runLambdaFunction(ctx, config, onAfterBuild)) as NodejsDebugConfiguration
+    const c = (await runLambdaFunction(ctx, config, async () => {})) as NodejsDebugConfiguration
     return c
 }
 
@@ -68,6 +73,9 @@ export async function makeTypescriptConfig(config: SamLaunchRequestArgs): Promis
     let remoteRoot: string | undefined
     config.codeRoot = pathutil.normalize(config.codeRoot)
 
+    // compile typescript code and convert lambda handler if necessary
+    await compileTypeScript(config)
+
     const isImageLambda = isImageLambdaConfig(config)
 
     if (isImageLambda && !config.noDebug) {
@@ -113,9 +121,9 @@ export async function makeTypescriptConfig(config: SamLaunchRequestArgs): Promis
  * Compiles non-template (target=code) debug configs, using a temporary default
  * tsconfig.json file.
  *
- * Assumes that `sam build` was already performed.
+ * Assumes that `sam build` was not already performed.
  */
-async function compileTypeScript(config: NodejsDebugConfiguration): Promise<void> {
+async function compileTypeScript(config: SamLaunchRequestArgs): Promise<void> {
     if (!config.baseBuildDir) {
         throw Error('invalid state: config.baseBuildDir was not set')
     }
@@ -134,46 +142,76 @@ async function compileTypeScript(config: NodejsDebugConfiguration): Promise<void
 
     // Require tsconfig.json or *.ts in the top-level of the source app, to
     // indicate a typescript Lambda. #2086
-    // Note: we don't use this tsconfig.json for compiling the target=code
-    // Lambda app below, instead we generate a minimal one.
+    // Note: we use this tsconfig.json as a base for compiling the target=code
+    // Lambda app below. If it does not exist, we generate a minimal one.
     const isTsApp = (await findTsOrTsConfig(config.codeRoot, false)) !== undefined
     if (!isTsApp) {
         return
     }
 
-    const buildOutputDir = path.join(config.baseBuildDir, 'output')
-    const buildDirTsFile = await findTsOrTsConfig(buildOutputDir, true)
-    if (!buildDirTsFile) {
-        // Should never happen: `sam build` should have copied the tsconfig.json from the source app dir.
-        throw new Error(`tsconfig.json or *.ts not found in: "${buildOutputDir}/*"`)
-    }
-    // XXX: `sam` may rename the CodeUri (and thus "output/<app>/" dir) if the
-    // original "<app>/" dir contains special chars, so get it this way. #2086
-    const buildDirApp = path.dirname(buildDirTsFile)
-    const buildDirTsConfig = path.join(buildDirApp, 'tsconfig.json')
+    const loadBaseConfig = (tsConfigPath: PathLike) => {
+        if (!existsSync(tsConfigPath)) {
+            return undefined
+        }
 
-    const tsc = await systemutil.SystemUtilities.findTypescriptCompiler()
-    if (!tsc) {
-        throw new Error('TypeScript compiler "tsc" not found in node_modules/ or the system.')
+        try {
+            const tsConfig = JSON.parse(readFileSync(tsConfigPath).toString())
+            getLogger('channel').info(`Using base TypeScript config: ${tsConfigPath}`)
+            return tsConfig
+        } catch (err) {
+            getLogger('channel').error(`Unable to use TypeScript base: ${tsConfigPath}`)
+        }
+
+        return undefined
     }
 
-    // Default config.
-    // Adapted from: https://github.com/aws/aws-toolkit-jetbrains/blob/911c54252d6a4271ee6cacf0ea1023506c4b504a/jetbrains-ultimate/src/software/aws/toolkits/jetbrains/services/lambda/nodejs/NodeJsLambdaBuilder.kt#L60
-    const defaultTsconfig = {
-        compilerOptions: {
+    const tsConfigPath = path.join(config.codeRoot, tsConfigFile)
+
+    const tsConfig =
+        loadBaseConfig(tsConfigPath) ?? loadBaseConfig(path.join(config.codeRoot, tsConfigInitialBaseFile)) ?? {}
+
+    if (tsConfig.compilerOptions === undefined) {
+        getLogger('channel').info('Creating TypeScript config')
+        tsConfig.compilerOptions = {
             target: 'es6',
             module: 'commonjs',
-            typeRoots: ['node_modules/@types'],
-            types: ['node'],
-            rootDir: '.',
             inlineSourceMap: true,
-        },
+        }
     }
+
+    const compilerOptions = tsConfig.compilerOptions
+
+    // determine build directory
+    const tsBuildDir = path.resolve(config.codeRoot, config.sam?.buildDir ?? compilerOptions.outDir ?? '.')
+    compilerOptions.outDir = tsBuildDir
+
+    // overwrite rootDir, sourceRoot
+    compilerOptions.rootDir = '.'
+    compilerOptions.sourceRoot = config.codeRoot
+
+    const typeRoots: string[] = Array.isArray(compilerOptions.typeRoots) ? compilerOptions.typeRoots : []
+    typeRoots.push('node_modules/@types')
+    compilerOptions.typeRoots = [...new Set(typeRoots)]
+
+    const types: string[] = Array.isArray(compilerOptions.types) ? compilerOptions.types : []
+    types.push('node')
+    compilerOptions.types = [...new Set(types)]
+
+    writeFileSync(tsConfigPath, JSON.stringify(tsConfig, undefined, 4))
+
+    // resolve ts lambda handler to point into build directory relative to codeRoot
+    const tsLambdaHandler = path.relative(config.codeRoot, path.join(tsBuildDir, config.invokeTarget.lambdaHandler))
+    config.invokeTarget.lambdaHandler = tsLambdaHandler
+    getLogger('channel').info(`Resolved compiled lambda handler to ${tsLambdaHandler}`)
+
+    const tsc = await systemutil.SystemUtilities.findTypescriptCompiler()
+    if (!tsc) {
+        throw new Error('TypeScript compiler "tsc" not found in node_modules/ or the system.')
+    }
+
     try {
-        // Overwrite the tsconfig.json copied by `sam build`.
-        writeFileSync(buildDirTsConfig, JSON.stringify(defaultTsconfig, undefined, 4))
         getLogger('channel').info(`Compiling TypeScript app with: "${tsc}"`)
-        await new ChildProcess(tsc, ['--project', buildDirApp]).run()
+        await new ChildProcess(tsc, ['--project', tsConfigPath]).run()
     } catch (error) {
         getLogger('channel').error(`TypeScript compile error: ${error}`)
         throw Error('Failed to compile TypeScript app')

src/shared/sam/localLambdaRunner.ts

@@ -76,11 +76,17 @@ function makeResourceName(config: SamLaunchRequestArgs): string {
 const samLocalPortCheckRetryIntervalMillis: number = 125
 const attachDebuggerRetryDelayMillis: number = 1000
 
+export function getInputTemplatePath(config: SamLaunchRequestArgs & { invokeTarget: { target: 'code' } }): string {
+    const inputTemplatePath: string = path.join(config.baseBuildDir!, 'app___vsctk___template.yaml')
+
+    return pathutil.normalize(inputTemplatePath)
+}
+
 export async function makeInputTemplate(
     config: SamLaunchRequestArgs & { invokeTarget: { target: 'code' } }
-): Promise<string> {
+): Promise<void> {
     let newTemplate: SamTemplateGenerator
-    const inputTemplatePath: string = path.join(config.baseBuildDir!, 'app___vsctk___template.yaml')
+    const inputTemplatePath: string = config.templatePath
     const resourceName = makeResourceName(config)
 
     // code type - generate ephemeral SAM template
@@ -90,7 +96,7 @@ export async function makeInputTemplate(
         .withRuntime(config.lambda!.runtime!)
         .withCodeUri(pathutil.normalize(config.invokeTarget.projectRoot))
 
-    if (config.lambda?.environmentVariables) {
+    if (config.lambda?.environmentVariables && Object.entries(config.lambda?.environmentVariables).length) {
         newTemplate = newTemplate.withEnvironment({
             Variables: config.lambda?.environmentVariables,
         })
@@ -108,8 +114,6 @@ export async function makeInputTemplate(
     }
 
     await newTemplate.generate(inputTemplatePath)
-
-    return pathutil.normalize(inputTemplatePath)
 }
 
 async function buildLambdaHandler(

src/test/shared/sam/debugger/samDebugConfigProvider.test.ts

@@ -718,7 +718,9 @@ describe('SamDebugConfigurationProvider', async function () {
                 debugPort: actual.debugPort,
                 documentUri: vscode.Uri.file(''), // TODO: remove or test.
                 handlerName: 'app.handler',
-                invokeTarget: { ...input.invokeTarget },
+                invokeTarget: {
+                    ...input.invokeTarget,
+                },
                 lambda: {
                     ...input.lambda,
                 },