more documentation

Author: anthony-nhs

CONTRIBUTING.md

@@ -1,38 +1,61 @@
 # Contribution Guidelines
 
 ## Raising an Issue
+
 If you raise an issue against this repository, please include as much information as possible to reproduce any bugs,
 or specific locations in the case of content errors.
 
 ## Contributing code
+
 To contribute code, please fork the repository and raise a pull request.
 
 Ideally pull requests should be fairly granular and aim to solve one problem each. It would also be helpful if they
 linked to an issue. If the maintainers cannot understand why a pull request was raised, it will be rejected,
 so please explain why the changes need to be made (unless it is self-evident).
 
 ### Merge responsibility
-* It is the responsibility of the reviewer to merge branches they have approved.
-* It is the responsibility of the author of the merge to ensure their merge is in a mergeable state.
-* It is the responsibility of the maintainers to ensure the merge process is unambiguous and automated where possible.
+
+- It is the responsibility of the reviewer to merge branches they have approved.
+- It is the responsibility of the author of the merge to ensure their merge is in a mergeable state.
+- It is the responsibility of the maintainers to ensure the merge process is unambiguous and automated where possible.
 
 ### Branch naming
+
 Branch names should be of the format:
 
 `aea-nnn-short-issue-description`
 
 Multiple branches are permitted for the same ticket.
 
 ### Commit messages
-Commit messages should be formatted as follows:
-```
-AEA-NNN Summary of changes
 
-Longer description of changes if explaining rationale is necessary,
-limited to 80 columns and spanning as many lines as you need.
+We do not enforce any conventions on commit messages to a branch, as we use squash commits when merging to main branch.   
+
+Commits from a pull request get squashed into a single commit on merge, using the pull request title as the commit message.
+Please format your pull request title using tags from [ESLint Convention](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-eslint) as follows:
+
+```text
+Tag: [AEA-NNNN] - Short description
 ```
 
+Tag can be one of:
+
+- `Fix` - for a bug fix. (Patch release)
+- `Update` - either for a backwards-compatible enhancement or for a rule change that adds reported problems. (Patch release)
+- `New` - implemented a new feature. (Minor release)
+- `Breaking` - for a backwards-incompatible enhancement or feature. (Major release)
+- `Docs` - changes to documentation only. (Patch release)
+- `Build` - changes to build process only. (No release)
+- `Upgrade` - for a dependency upgrade. (Patch release)
+- `Chore` - for refactoring, adding tests, etc. (anything that isn't user-facing). (Patch release)
+
+If the current release is x.y.z then
+- a patch release increases z by 1
+- a minor release increases y by 1
+- a major release increases x by 1
+
+Correct tagging is necessary for our automated versioning and release process ([Release](./RELEASE.md)).
+
 ### Changelog
-Every pull request must include a change to the changelog.
 
-Add changes to the top of the current date. If the date is old, the reviewer should update the changelog to be correct before merging.
+Release changelogs are generated from the titles of pull requests merged into the `main` branch. Please ensure that your pull request title is sufficiently descriptive of the changes made.

README.md

@@ -1,31 +1,98 @@
-# eps-cdk-utils
+# Electronic Prescription Service CDK Utils
 
-This contains a docker image used to deploy cdk to our environments and a cdk-constructs library
+![Build](https://github.com/NHSDigital/eps-cdk-utils/workflows/release/badge.svg?branch=main)
 
-# cdk-constructs
+This repository contains a docker image used to deploy CDK to our environments and a CDK constructs library for common EPS project patterns.
 
-This contains common cdk constructs used in eps projects
+- `docker/` Contains Dockerfile used to build image used fo for CDK deployments
+- `packages/cdkConstructs/` Contains common CDK constructs used in EPS projects
+- `scripts/` Utilities helpful to developers of this specification
+- `.github/` Contains GitHub workflows that are used for building and deploying from pull requests and releases
 
-Available constructs are
+## CDK Constructs
 
-- TypescriptLambdaFunction
+This contains common CDK constructs used in EPS projects.
 
-# development
+Available constructs are:
 
-If you want to test a new construct, add it to packages/cdkConstructs
-Run the following to produce a distributable tarball
-```
+- `TypescriptLambdaFunction` - A reusable construct for TypeScript Lambda functions
+
+## Contributing
+
+Contributions to this project are welcome from anyone, providing that they
+conform to the [guidelines for contribution](./CONTRIBUTING.md) and the [community code of conduct](./CODE_OF_CONDUCT.md).
+
+### Licensing
+
+This code is dual licensed under the MIT license and the OGL (Open Government
+License). Any new work added to this repository must conform to the conditions of
+these licenses. In particular this means that this project may not depend on
+GPL-licensed or AGPL-licensed libraries, as these would violate the terms of those
+libraries' licenses.
+
+The contents of this repository are protected by Crown Copyright (C).
+
+## Development
+
+It is recommended that you use Visual Studio Code and a devcontainer as this
+will install all necessary components and correct versions of tools and languages.
+See [https://code.visualstudio.com/docs/devcontainers/containers](https://code.visualstudio.com/docs/devcontainers/containers) for details on how to set this up on your host machine.
+
+All commits must be made using [signed commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits).
+
+### Setup
+
+If you want to test a new construct, add it to `packages/cdkConstructs`.
+
+### Testing New Constructs
+
+Run the following to produce a distributable tarball:
+
+```bash
 make package
 ```
-This will produce a tarball file in lib folder
 
-Copy this to the project you want to use it in and use the following to install it
+This will produce a tarball file in the `lib` folder.
 
-```
-npm install --save NHSDigital-eps-cdk-constructs-1.0.0.tgz --workspace packages/cdk/ 
-```
+Copy this to the project you want to use it in and use the following to install it:
 
-You will then be able to use it - eg
+```bash
+npm install --save NHSDigital-eps-cdk-constructs-1.0.0.tgz --workspace packages/cdk/
 ```
+
+You will then be able to use it - for example:
+
+```typescript
 import {TypescriptLambdaFunction} from "@NHSDigital/eps-cdk-constructs"
 ```
+
+### Make Commands
+
+There are `make` commands that are run as part of the CI pipeline and help alias some
+functionality during development.
+
+#### Install targets
+
+- `install-node` Installs node dependencies
+- `install-python` Installs python dependencies
+- `install-hooks` Installs git pre commit hooks
+- `install` Runs all install targets
+
+#### Linting and testing
+
+- `lint` Runs lint for all code
+- `test` Runs unit tests for all code
+
+#### Compiling
+
+- `compile` Compiles all code
+- `package` Creates distributable tarball of CDK constructs
+
+#### Check licenses
+
+- `check-licenses` Checks licenses for all packages used
+
+#### Clean targets
+
+- `clean` Clears up any files that have been generated by building or testing locally
+- `deep-clean` Runs clean target and also removes any node_modules and python libraries installed locally

packages/cdkConstructs/src/constructs/TypescriptLambdaFunction.ts

@@ -108,7 +108,11 @@ const getDefaultLambdaOptions = (
  * - CloudWatch log group with KMS encryption
  * - IAM role for execution with necessary permissions
  * - Subscription filter on logs so they are forwarded to splunk
- * - Lambda Insights layer for monitoring
+ *
+ * It also
+ * - attaches the Lambda Insights layer for monitoring.
+ * - adds cfnGuard suppressions for common issues.
+ * - adds cdk-nag suppressions for common issues.
  *
  * @example
  * ```typescript

packages/cdkConstructs/tests/functionConstruct.test.ts

@@ -248,7 +248,7 @@ describe("functionConstruct works correctly with additional layers", () => {
     template = Template.fromStack(stack)
   })
 
-  test("it has the correct policies in the role", () => {
+  test("it has the correct layers added", () => {
     template.hasResourceProperties("AWS::Lambda::Function", {
       Handler: "index.handler",
       Runtime: "nodejs22.x",
@@ -263,3 +263,39 @@ describe("functionConstruct works correctly with additional layers", () => {
     })
   })
 })
+
+describe("functionConstruct works correctly with custom timeout", () => {
+  let stack: Stack
+  let app: App
+  let template: assertions.Template
+
+  beforeAll(() => {
+    app = new App()
+    stack = new Stack(app, "lambdaConstructStack")
+    new TypescriptLambdaFunction(stack, "dummyFunction", {
+      functionName: "testLambda",
+      packageBasePath: "packages/cdkConstructs",
+      entryPoint: "tests/src/dummyLambda.ts",
+      environmentVariables: {},
+      logRetentionInDays: 30,
+      logLevel: "DEBUG",
+      version: "1.0.0",
+      layers: [],
+      commitId: "abcd1234",
+      baseDir: resolve(__dirname, "../../.."),
+      timeoutInSeconds: 120
+    })
+    template = Template.fromStack(stack)
+  })
+
+  test("it has the correct timeout", () => {
+    template.hasResourceProperties("AWS::Lambda::Function", {
+      Handler: "index.handler",
+      Runtime: "nodejs22.x",
+      FunctionName: "testLambda",
+      MemorySize: 256,
+      Architectures: ["x86_64"],
+      Timeout: 120
+    })
+  })
+})

sonar-project.properties

@@ -9,3 +9,15 @@ sonar.coverage.exclusions=\
   eslint.config.mjs, \
   **/tests/*, \
   release.config.js
+
+sonar.cpd.exclusions=\
+    **/*.test.*
+
+# Define the modules
+sonar.modules=\
+    cdkConstructs
+
+# Modules
+cdkConstructs.sonar.projectBaseDir=packages/cdkConstructs
+cdkConstructs.sonar.sources=.
+cdkConstructs.sonar.javascript.lcov.reportPaths=coverage/lcov.info