Skip to content

Commit 3c91fc7

Browse files
JackSpagnoliNHSJackSpagnoliNHS
authored
Merge branch 'main' into dependabot/maven/software.amazon.lambda-powertools-logging-2.1.1
2 parents e964f57 + 411c74d commit 3c91fc7

6 files changed

Lines changed: 63 additions & 11 deletions

File tree

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

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,40 @@ This file provides instructions for generating, reviewing, and maintaining AWS C
2323
- Suppress warnings with `nagSuppressions.ts` only when justified and documented
2424
- Use `bin/` for entrypoint apps, `constructs/` for reusable components, and `stacks/` for stack definitions
2525
- Prefer `props` interfaces for construct configuration
26+
- 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.
27+
- 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.
28+
- 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.
29+
- 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.
30+
31+
### Good Example - Inline Explicit Shape
32+
33+
```typescript
34+
interface ApisProps {
35+
readonly functions: {
36+
readonly status: TypescriptLambdaFunction
37+
}
38+
readonly stateMachines: {
39+
readonly getMyPrescriptions: ExpressStateMachine
40+
}
41+
}
42+
```
43+
44+
### Bad Example - Hidden Contract via Pick
45+
46+
```typescript
47+
interface ApisProps {
48+
readonly functions: Pick<FunctionResources, "status" | "capabilityStatement">
49+
}
50+
```
51+
52+
### Bad Example - Generic Map
53+
54+
```typescript
55+
interface ApisProps {
56+
functions: {[key: string]: TypescriptLambdaFunction}
57+
stateMachines: {[key: string]: ExpressStateMachine}
58+
}
59+
```
2660

2761
## Code Standards
2862

@@ -33,6 +67,7 @@ This file provides instructions for generating, reviewing, and maintaining AWS C
3367
- Variables: camelCase
3468
- Stacks: Suffix with `Stack` (e.g., `CptsApiAppStack`)
3569
- Entry points: Suffix with `App` (e.g., `CptsApiApp.ts`)
70+
- CDK app entry points must follow `<app acronym><Api|Ui>[Sandbox]App` naming (e.g., `PsuApiApp`, `PsuApiSandboxApp`)
3671

3772
### File Organization
3873

@@ -88,11 +123,26 @@ export class CptsApiAppStack extends Stack {
88123
- Prefer VPC endpoints for private connectivity
89124
- Minimize resource creation in test environments
90125

126+
## Unit Testing
127+
128+
- Write unit tests for CDK stacks and constructs using synthesis-based assertions.
129+
- Prefer in-process tests that instantiate CDK `App` and `Stack` objects directly and assert on synthesized templates.
130+
- Keep assertions light-touch and stable, such as resource counts and a small number of important properties.
131+
- Avoid mocking AWS resources or writing tests that attempt to exercise live AWS behaviour.
132+
- CDK constructs suitable for reuse should be placed in `eps-cdk-utils` repo.
133+
- Do not test AWS implementation details owned by the CDK library. Test the resources and properties your code is responsible for declaring.
134+
135+
### Recommended Test Styles
136+
137+
- Smoke tests for `bin/` files: execute the entrypoint and assert that synthesis completes without throwing.
138+
- In-process synth tests for stacks and constructs: instantiate the stack directly and assert resource counts or key CloudFormation properties with `Template.fromStack(...)`.
139+
91140

92141
## Validation and Verification
93142

94143
- Build: `make cdk-synth`
95144
- Lint: `npm run lint --workspace packages/cdk`
145+
- Test: `npm test --workspace packages/cdk`
96146

97147
## Maintenance
98148

‎.github/instructions/languages/typescript.instructions.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ This document provides instructions for generating, reviewing, and maintaining T
2323
- Use destructuring for objects and arrays to improve readability.
2424
- Avoid magic numbers and hardcoded values; use named constants.
2525
- Keep functions pure and side-effect free when possible.
26+
- Do not use the `void` operator to silence unused-value warnings; prefer code that makes usage explicit.
2627

2728
## Code Standards
2829

@@ -92,6 +93,7 @@ This document provides instructions for generating, reviewing, and maintaining T
9293
### Type Safety
9394

9495
- Prefer interfaces and types. You MUST NOT use `any`.
96+
- Prefer `Array<T>` over `T[]` for array type annotations.
9597
- Use type guards and assertions when necessary.
9698
- Example:
9799

‎.github/workflows/ci.yml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,15 +8,15 @@ permissions: {}
88

99
jobs:
1010
get_config_values:
11-
uses: NHSDigital/eps-common-workflows/.github/workflows/get-repo-config.yml@e798d5aee897de6f7dc387dd5623fcd9ba4c8929
11+
uses: NHSDigital/eps-common-workflows/.github/workflows/get-repo-config.yml@bda627e2ce1a32ea56bcc815aec57b06cfa63c9d
1212
permissions:
1313
attestations: read
1414
contents: read
1515
packages: read
1616
with:
1717
verify_published_from_main_image: true
1818
quality_checks:
19-
uses: NHSDigital/eps-common-workflows/.github/workflows/quality-checks-devcontainer.yml@8399c1f015c1304e40771cbd8ccc24c7ed48fdbc
19+
uses: NHSDigital/eps-common-workflows/.github/workflows/quality-checks-devcontainer.yml@bda627e2ce1a32ea56bcc815aec57b06cfa63c9d
2020
needs: [get_config_values]
2121
permissions:
2222
contents: read
@@ -39,7 +39,7 @@ jobs:
3939
4040
tag_release:
4141
needs: [quality_checks, get_commit_id, get_config_values]
42-
uses: NHSDigital/eps-common-workflows/.github/workflows/tag-release-devcontainer.yml@e798d5aee897de6f7dc387dd5623fcd9ba4c8929
42+
uses: NHSDigital/eps-common-workflows/.github/workflows/tag-release-devcontainer.yml@bda627e2ce1a32ea56bcc815aec57b06cfa63c9d
4343
permissions:
4444
id-token: write
4545
contents: write

‎.github/workflows/pull_request.yml‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,15 +5,15 @@ on:
55
permissions: {}
66
jobs:
77
get_config_values:
8-
uses: NHSDigital/eps-common-workflows/.github/workflows/get-repo-config.yml@e798d5aee897de6f7dc387dd5623fcd9ba4c8929
8+
uses: NHSDigital/eps-common-workflows/.github/workflows/get-repo-config.yml@bda627e2ce1a32ea56bcc815aec57b06cfa63c9d
99
permissions:
1010
attestations: read
1111
contents: read
1212
packages: read
1313
with:
1414
verify_published_from_main_image: false
1515
quality_checks:
16-
uses: NHSDigital/eps-common-workflows/.github/workflows/quality-checks-devcontainer.yml@8399c1f015c1304e40771cbd8ccc24c7ed48fdbc
16+
uses: NHSDigital/eps-common-workflows/.github/workflows/quality-checks-devcontainer.yml@bda627e2ce1a32ea56bcc815aec57b06cfa63c9d
1717
needs: [get_config_values]
1818
permissions:
1919
contents: read
@@ -24,7 +24,7 @@ jobs:
2424
secrets:
2525
SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
2626
pr_title_format_check:
27-
uses: NHSDigital/eps-common-workflows/.github/workflows/pr_title_check.yml@e798d5aee897de6f7dc387dd5623fcd9ba4c8929
27+
uses: NHSDigital/eps-common-workflows/.github/workflows/pr_title_check.yml@bda627e2ce1a32ea56bcc815aec57b06cfa63c9d
2828
permissions:
2929
pull-requests: write
3030
get_issue_number:
@@ -54,7 +54,7 @@ jobs:
5454
result-encoding: string
5555
tag_release:
5656
needs: [get_config_values]
57-
uses: NHSDigital/eps-common-workflows/.github/workflows/tag-release-devcontainer.yml@e798d5aee897de6f7dc387dd5623fcd9ba4c8929
57+
uses: NHSDigital/eps-common-workflows/.github/workflows/tag-release-devcontainer.yml@bda627e2ce1a32ea56bcc815aec57b06cfa63c9d
5858
permissions:
5959
id-token: write
6060
contents: write

‎.github/workflows/release.yml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,15 +7,15 @@ permissions: {}
77

88
jobs:
99
get_config_values:
10-
uses: NHSDigital/eps-common-workflows/.github/workflows/get-repo-config.yml@e798d5aee897de6f7dc387dd5623fcd9ba4c8929
10+
uses: NHSDigital/eps-common-workflows/.github/workflows/get-repo-config.yml@bda627e2ce1a32ea56bcc815aec57b06cfa63c9d
1111
permissions:
1212
attestations: read
1313
contents: read
1414
packages: read
1515
with:
1616
verify_published_from_main_image: true
1717
quality_checks:
18-
uses: NHSDigital/eps-common-workflows/.github/workflows/quality-checks-devcontainer.yml@8399c1f015c1304e40771cbd8ccc24c7ed48fdbc
18+
uses: NHSDigital/eps-common-workflows/.github/workflows/quality-checks-devcontainer.yml@bda627e2ce1a32ea56bcc815aec57b06cfa63c9d
1919
needs: [get_config_values]
2020
permissions:
2121
contents: read
@@ -38,7 +38,7 @@ jobs:
3838
3939
tag_release:
4040
needs: [quality_checks, get_commit_id, get_config_values]
41-
uses: NHSDigital/eps-common-workflows/.github/workflows/tag-release-devcontainer.yml@e798d5aee897de6f7dc387dd5623fcd9ba4c8929
41+
uses: NHSDigital/eps-common-workflows/.github/workflows/tag-release-devcontainer.yml@bda627e2ce1a32ea56bcc815aec57b06cfa63c9d
4242
permissions:
4343
id-token: write
4444
contents: write

‎.github/workflows/sync_copilot.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ jobs:
1515

1616
steps:
1717
- name: Sync shared instructions
18-
uses: NHSDigital/eps-copilot-instructions@8b4d7f546fe9825a149cb8cc8cfdb31df58c3730
18+
uses: NHSDigital/eps-copilot-instructions@e6e445a93671466398e3f79d20cf1f64885150d8
1919
with:
2020
copilot_instructions_ref: main
2121
calling_repo_base_branch: main

0 commit comments

Comments
 (0)