From a7d73d842cb5bfcc8492d9778dac5527dc740f4c Mon Sep 17 00:00:00 2001 From: tstephen-nhs <231503406+tstephen-nhs@users.noreply.github.com> Date: Fri, 10 Apr 2026 13:23:15 +0000 Subject: [PATCH 1/7] docs: suggestions after cdk work --- .../instructions/languages/cdk.instructions.md | 17 +++++++++++++++++ .../languages/typescript.instructions.md | 2 ++ 2 files changed, 19 insertions(+) diff --git a/.github/instructions/languages/cdk.instructions.md b/.github/instructions/languages/cdk.instructions.md index b441a02..7924c2b 100644 --- a/.github/instructions/languages/cdk.instructions.md +++ b/.github/instructions/languages/cdk.instructions.md @@ -88,11 +88,28 @@ export class CptsApiAppStack extends Stack { - Prefer VPC endpoints for private connectivity - Minimize resource creation in test environments +## Unit Testing + +- Write unit tests for CDK stacks and constructs using synthesis-based assertions. +- Prefer in-process tests that instantiate CDK `App` and `Stack` objects directly and assert on synthesized templates. +- Keep assertions light-touch and stable, such as resource counts and a small number of important properties. +- Use smoke tests for `bin/` entrypoints only to verify the app can be synthesized from its CLI wiring and environment configuration. +- Avoid mocking AWS resources or writing tests that attempt to exercise live AWS behaviour. +- CDK constructs suitable for reuse should be placed in `eps-cdk-utils` repo. +- Smaller CDK constructs may be included here and should have tests associated. +- Do not test AWS implementation details owned by the CDK library. Test the resources and properties your code is responsible for declaring. + +### Recommended Test Styles + +- Smoke tests for `bin/` files: execute the entrypoint and assert that synthesis completes without throwing. +- In-process synth tests for stacks and constructs: instantiate the stack directly and assert resource counts or key CloudFormation properties with `Template.fromStack(...)`. + ## Validation and Verification - Build: `make cdk-synth` - Lint: `npm run lint --workspace packages/cdk` +- Test: `npm test --workspace packages/cdk` ## Maintenance diff --git a/.github/instructions/languages/typescript.instructions.md b/.github/instructions/languages/typescript.instructions.md index 4c15f42..beddb89 100644 --- a/.github/instructions/languages/typescript.instructions.md +++ b/.github/instructions/languages/typescript.instructions.md @@ -23,6 +23,7 @@ This document provides instructions for generating, reviewing, and maintaining T - Use destructuring for objects and arrays to improve readability. - Avoid magic numbers and hardcoded values; use named constants. - Keep functions pure and side-effect free when possible. +- Do not use the `void` operator to silence unused-value warnings; prefer code that makes usage explicit. ## Code Standards @@ -92,6 +93,7 @@ This document provides instructions for generating, reviewing, and maintaining T ### Type Safety - Prefer interfaces and types. You MUST NOT use `any`. +- Prefer `Array` over `T[]` for array type annotations. - Use type guards and assertions when necessary. - Example: From e040551236d18c9899bd0a4053de90d82bf1227f Mon Sep 17 00:00:00 2001 From: tstephen-nhs <231503406+tstephen-nhs@users.noreply.github.com> Date: Mon, 13 Apr 2026 12:23:17 +0100 Subject: [PATCH 2/7] docs: suggestions after cdk work --- .github/instructions/languages/cdk.instructions.md | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/instructions/languages/cdk.instructions.md b/.github/instructions/languages/cdk.instructions.md index 7924c2b..13bbd76 100644 --- a/.github/instructions/languages/cdk.instructions.md +++ b/.github/instructions/languages/cdk.instructions.md @@ -93,7 +93,6 @@ export class CptsApiAppStack extends Stack { - Write unit tests for CDK stacks and constructs using synthesis-based assertions. - Prefer in-process tests that instantiate CDK `App` and `Stack` objects directly and assert on synthesized templates. - Keep assertions light-touch and stable, such as resource counts and a small number of important properties. -- Use smoke tests for `bin/` entrypoints only to verify the app can be synthesized from its CLI wiring and environment configuration. - Avoid mocking AWS resources or writing tests that attempt to exercise live AWS behaviour. - CDK constructs suitable for reuse should be placed in `eps-cdk-utils` repo. - Smaller CDK constructs may be included here and should have tests associated. From e23fbe9b15d3587f6486489c5482ad4138a82325 Mon Sep 17 00:00:00 2001 From: tstephen-nhs <231503406+tstephen-nhs@users.noreply.github.com> Date: Mon, 13 Apr 2026 12:25:08 +0100 Subject: [PATCH 3/7] docs: tweak --- .github/instructions/languages/cdk.instructions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/instructions/languages/cdk.instructions.md b/.github/instructions/languages/cdk.instructions.md index 13bbd76..3590eb8 100644 --- a/.github/instructions/languages/cdk.instructions.md +++ b/.github/instructions/languages/cdk.instructions.md @@ -94,8 +94,8 @@ export class CptsApiAppStack extends Stack { - Prefer in-process tests that instantiate CDK `App` and `Stack` objects directly and assert on synthesized templates. - Keep assertions light-touch and stable, such as resource counts and a small number of important properties. - Avoid mocking AWS resources or writing tests that attempt to exercise live AWS behaviour. -- CDK constructs suitable for reuse should be placed in `eps-cdk-utils` repo. -- Smaller CDK constructs may be included here and should have tests associated. +- CDK constructs suitable for reuse should be placed in `eps-cdk-utils` repo. +- Smaller CDK constructs may be included here and should have associated tests. - Do not test AWS implementation details owned by the CDK library. Test the resources and properties your code is responsible for declaring. ### Recommended Test Styles From 4c4a9348224387f7d32d3af3a2fd22481539c089 Mon Sep 17 00:00:00 2001 From: tstephen-nhs <231503406+tstephen-nhs@users.noreply.github.com> Date: Tue, 21 Apr 2026 15:23:33 +0000 Subject: [PATCH 4/7] docs: guidance on state machine cdk --- .github/instructions/languages/cdk.instructions.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/instructions/languages/cdk.instructions.md b/.github/instructions/languages/cdk.instructions.md index 3590eb8..884683f 100644 --- a/.github/instructions/languages/cdk.instructions.md +++ b/.github/instructions/languages/cdk.instructions.md @@ -23,6 +23,7 @@ This file provides instructions for generating, reviewing, and maintaining AWS C - Suppress warnings with `nagSuppressions.ts` only when justified and documented - Use `bin/` for entrypoint apps, `constructs/` for reusable components, and `stacks/` for stack definitions - Prefer `props` interfaces for construct configuration +- For Step Functions definitions, prefer a chain-centric style where states are defined inline within `Chain.start(...).next(...)` so the execution flow reads top-to-bottom in one place. Avoid mixing a chain with many separately declared state `const`s instead embedding calls to helper functions in the chain. ## Code Standards From 3ca98696dcfcefe019de0e624162e12a2a65d96c Mon Sep 17 00:00:00 2001 From: tstephen-nhs <231503406+tstephen-nhs@users.noreply.github.com> Date: Tue, 21 Apr 2026 15:24:47 +0000 Subject: [PATCH 5/7] fix: review comment --- .github/instructions/languages/cdk.instructions.md | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/instructions/languages/cdk.instructions.md b/.github/instructions/languages/cdk.instructions.md index 884683f..ab7f324 100644 --- a/.github/instructions/languages/cdk.instructions.md +++ b/.github/instructions/languages/cdk.instructions.md @@ -96,7 +96,6 @@ export class CptsApiAppStack extends Stack { - Keep assertions light-touch and stable, such as resource counts and a small number of important properties. - Avoid mocking AWS resources or writing tests that attempt to exercise live AWS behaviour. - CDK constructs suitable for reuse should be placed in `eps-cdk-utils` repo. -- Smaller CDK constructs may be included here and should have associated tests. - Do not test AWS implementation details owned by the CDK library. Test the resources and properties your code is responsible for declaring. ### Recommended Test Styles From 854ca742a8cfeca2da11dcd75be182957f885f0d Mon Sep 17 00:00:00 2001 From: tstephen-nhs <231503406+tstephen-nhs@users.noreply.github.com> Date: Thu, 23 Apr 2026 14:39:28 +0100 Subject: [PATCH 6/7] docs: step function formatting, Props typing hints --- .github/instructions/languages/cdk.instructions.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/instructions/languages/cdk.instructions.md b/.github/instructions/languages/cdk.instructions.md index ab7f324..9b18d75 100644 --- a/.github/instructions/languages/cdk.instructions.md +++ b/.github/instructions/languages/cdk.instructions.md @@ -23,7 +23,9 @@ This file provides instructions for generating, reviewing, and maintaining AWS C - Suppress warnings with `nagSuppressions.ts` only when justified and documented - Use `bin/` for entrypoint apps, `constructs/` for reusable components, and `stacks/` for stack definitions - Prefer `props` interfaces for construct configuration -- For Step Functions definitions, prefer a chain-centric style where states are defined inline within `Chain.start(...).next(...)` so the execution flow reads top-to-bottom in one place. Avoid mixing a chain with many separately declared state `const`s instead embedding calls to helper functions in the chain. +- For Step Functions definitions, prefer a chain-centric style where states are defined inline within `Chain.start(...).next(...)` so the execution flow reads top-to-bottom in one place. Avoid mixing a chain with many separately declared state `const`s; instead embed calls to helper functions directly in the chain when needed. +- For Step Functions chain formatting, place `.start`, `.next`, `.when`, and `.otherwise` on their own lines, and give helper calls such as `.jsonata(...)` the same line-break weight so nested flow blocks are visually aligned and easy to scan. +- For construct props that group resources (for example lambda functions or state machines), prefer explicit named object shapes (e.g. `{status: TypescriptLambdaFunction}`) over generic index signatures or broad maps so consumers are strongly typed to only the supported resources. ## Code Standards From 0a23d95e06b295519d0ac763991c8f34299d0c0a Mon Sep 17 00:00:00 2001 From: tstephen-nhs <231503406+tstephen-nhs@users.noreply.github.com> Date: Thu, 23 Apr 2026 16:43:26 +0100 Subject: [PATCH 7/7] docs: more detail on shaping the Props interfaces --- .../languages/cdk.instructions.md | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/.github/instructions/languages/cdk.instructions.md b/.github/instructions/languages/cdk.instructions.md index 9b18d75..c1921b7 100644 --- a/.github/instructions/languages/cdk.instructions.md +++ b/.github/instructions/languages/cdk.instructions.md @@ -26,6 +26,37 @@ This file provides instructions for generating, reviewing, and maintaining AWS C - For Step Functions definitions, prefer a chain-centric style where states are defined inline within `Chain.start(...).next(...)` so the execution flow reads top-to-bottom in one place. Avoid mixing a chain with many separately declared state `const`s; instead embed calls to helper functions directly in the chain when needed. - For Step Functions chain formatting, place `.start`, `.next`, `.when`, and `.otherwise` on their own lines, and give helper calls such as `.jsonata(...)` the same line-break weight so nested flow blocks are visually aligned and easy to scan. - For construct props that group resources (for example lambda functions or state machines), prefer explicit named object shapes (e.g. `{status: TypescriptLambdaFunction}`) over generic index signatures or broad maps so consumers are strongly typed to only the supported resources. +- For construct props that consume grouped resources, prefer inline explicit object shapes in the props contract (for example `functions: { status: TypescriptLambdaFunction }`) over `Pick<...>` or generic map types. + +### Good Example - Inline Explicit Shape + +```typescript +interface ApisProps { + readonly functions: { + readonly status: TypescriptLambdaFunction + } + readonly stateMachines: { + readonly getMyPrescriptions: ExpressStateMachine + } +} +``` + +### Bad Example - Hidden Contract via Pick + +```typescript +interface ApisProps { + readonly functions: Pick +} +``` + +### Bad Example - Generic Map + +```typescript +interface ApisProps { + functions: {[key: string]: TypescriptLambdaFunction} + stateMachines: {[key: string]: ExpressStateMachine} +} +``` ## Code Standards @@ -36,6 +67,7 @@ This file provides instructions for generating, reviewing, and maintaining AWS C - Variables: camelCase - Stacks: Suffix with `Stack` (e.g., `CptsApiAppStack`) - Entry points: Suffix with `App` (e.g., `CptsApiApp.ts`) +- CDK app entry points must follow `[Sandbox]App` naming (e.g., `PsuApiApp`, `PsuApiSandboxApp`) ### File Organization