Merge branch 'main' into aea-6055-reg-test-lambda-invoke

Author: tstephen-nhs

.github/instructions/languages/cdk.instructions.md

@@ -23,6 +23,40 @@ 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 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<FunctionResources, "status" | "capabilityStatement">
+}
+```
+
+### Bad Example - Generic Map
+
+```typescript
+interface ApisProps {
+  functions: {[key: string]: TypescriptLambdaFunction}
+  stateMachines: {[key: string]: ExpressStateMachine}
+}
+```
 
 ## Code Standards
 
@@ -33,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 `<app acronym><Api|Ui>[Sandbox]App` naming (e.g., `PsuApiApp`, `PsuApiSandboxApp`)
 
 ### File Organization
 
@@ -88,11 +123,26 @@ 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.
+- 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.
+- 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
 

.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<T>` over `T[]` for array type annotations.
 - Use type guards and assertions when necessary.
 - Example:
 

.github/workflows/release.yml

@@ -7,15 +7,15 @@ permissions: {}
 
 jobs:
   get_config_values:
-    uses: NHSDigital/eps-common-workflows/.github/workflows/get-repo-config.yml@bda627e2ce1a32ea56bcc815aec57b06cfa63c9d
+    uses: NHSDigital/eps-common-workflows/.github/workflows/get-repo-config.yml@b83cff6a2951a8a2951b8c00a7734edd0cc832d3
     permissions:
       attestations: read
       contents: read
       packages: read
     with:
       verify_published_from_main_image: true
   quality_checks:
-    uses: NHSDigital/eps-common-workflows/.github/workflows/quality-checks-devcontainer.yml@bda627e2ce1a32ea56bcc815aec57b06cfa63c9d
+    uses: NHSDigital/eps-common-workflows/.github/workflows/quality-checks-devcontainer.yml@b83cff6a2951a8a2951b8c00a7734edd0cc832d3
     needs: [get_config_values]
     permissions:
       contents: read
@@ -38,7 +38,7 @@ jobs:
 
   tag_release:
     needs: [quality_checks, get_commit_id, get_config_values]
-    uses: NHSDigital/eps-common-workflows/.github/workflows/tag-release-devcontainer.yml@bda627e2ce1a32ea56bcc815aec57b06cfa63c9d
+    uses: NHSDigital/eps-common-workflows/.github/workflows/tag-release-devcontainer.yml@b83cff6a2951a8a2951b8c00a7734edd0cc832d3
     permissions:
       id-token: write
       contents: write