[PRM-537] Introduce markdown validation check on PRs (#520)

Author: chrisbloe

…b/workflows/automated-sbom-repo-scan.yml …hub/workflows/automated-pr-validator.yml.github/workflows/automated-sbom-repo-scan.yml renamed to .github/workflows/automated-pr-validator.yml .github/workflows/automated-sbom-repo-scan.yml renamed to .github/workflows/automated-pr-validator.yml

@@ -1,23 +1,23 @@
-name: 'Z-AUTOMATED: SBOM Repo Scan'
+name: "Z-AUTOMATED: PR Validator"
 
 on:
   pull_request:
     types: [opened, synchronize, reopened]
 
-permissions:
-  actions: read   # Required for anchore/sbom-action
-  contents: write # Required for anchore/sbom-action
-  id-token: write # Required for requesting the JWT
-  pull-requests: write
-
 jobs:
   sbom_scan:
     name: SBOM Repo Scan
     runs-on: ubuntu-latest
+    permissions:
+      actions: read # Required for anchore/sbom-action
+      contents: write # Required for anchore/sbom-action
+      id-token: write # Required for requesting the JWT
+      pull-requests: write
     steps:
-      - uses: actions/checkout@v5
+      - name: Checkout
+        uses: actions/checkout@v5
         with:
-          fetch-depth: 0  # Shallow clones should be disabled for a better relevancy of analysis
+          fetch-depth: 0
 
       - uses: anchore/sbom-action@v0
         with:
@@ -51,14 +51,14 @@ jobs:
               repo: context.repo.repo,
               issue_number: context.issue.number,
             })
-            
+
             const botComment = comments.find(comment => {
               return comment.user.type === 'Bot' && comment.body.includes('Code security issues found')
             })
 
             // 2. Prepare format of the comment
             const output = `### Code security issues found
-            
+
             View full details [here](https://github.com/${{ github.repository }}/security/code-scanning?query=is%3Aopen+pr%3A${{ github.event.pull_request.number }}).`;
 
             // 3. If we have a comment, update it, otherwise create a new one
@@ -70,7 +70,7 @@ jobs:
                 body: output
               })
             }
-            
+
             github.rest.issues.createComment({
               issue_number: context.issue.number,
               owner: context.repo.owner,
@@ -89,7 +89,7 @@ jobs:
               repo: context.repo.repo,
               issue_number: context.issue.number,
             })
-            
+
             const botComment = comments.find(comment => {
               return comment.user.type === 'Bot' && comment.body.includes('Code security issues found')
             })
@@ -102,3 +102,21 @@ jobs:
                 comment_id: botComment.id
               })
             }
+
+  markdown-validation:
+    name: Markdown Validation
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Run Markdown Validation Script
+        id: validate
+        run: |
+          BRANCH_NAME=${{ github.event.repository.default_branch }}
+          chmod +x scripts/markdown-validator.sh
+          scripts/markdown-validator.sh

.markdownlint.jsonc

@@ -0,0 +1,4 @@
+{
+    "MD013": false,
+    "MD033": false
+}

.terraform-docs.yml

@@ -14,8 +14,11 @@ sections:
 
 content: |-
   {{ .Requirements }}
+
   {{ .Resources }}
+
   {{ .Inputs }}
+
   {{ .Outputs }}
 
 output:

README.md

@@ -8,7 +8,8 @@ This repository is used to build the infrastructure the NDR. That is it's sole p
 - [Terraform docs](https://github.com/terraform-docs/terraform-docs)
 
 To install terraform-docs on WSL use the following commands (e.g. for v0.20.0):
-```
+
+```shell
 curl -sSLo ./terraform-docs.tar.gz https://terraform-docs.io/dl/v0.20.0/terraform-docs-v0.20.0-$(uname)-amd64.tar.gz
 tar -xzf terraform-docs.tar.gz
 chmod +x terraform-docs
@@ -24,7 +25,7 @@ As this repository is a standalone infrastructure there is no python/node based
 
 - Set this repository to get it's pre-commit hooks from .githooks
 
-```
+```shell
 git config core.hooksPath .githooks
 ```
 

bootstrap/README.md

@@ -1,3 +1,5 @@
+# Terraform Bootstrap
+
 ## Requirements
 
 | Name | Version |

infrastructure/README.md

@@ -1,3 +1,5 @@
+# National Document Repository - Infrastructure as Code
+
 ## Requirements
 
 | Name                                                         | Version |

infrastructure/modules/README.md

@@ -1 +1,5 @@
-Modules folder for Terraform Modules 
+# Modules folder for Terraform Modules
+
+This directory contains reusable Terraform modules that can be resused for multiple resource instances. Each module is designed to encapsulate specific functionality, making it easier to manage and deploy infrastructure components consistently.
+
+Each module includes its own `README.md` file with detailed information on usage, inputs, outputs, and examples.

infrastructure/modules/app_config/README.md

@@ -38,6 +38,7 @@ module "app_config" {
 | Name | Version |
 |------|---------|
 | <a name="requirement_aws"></a> [aws](#requirement\_aws) | ~> 5.0 |
+
 ## Resources
 
 | Name | Type |
@@ -51,6 +52,7 @@ module "app_config" {
 | [aws_iam_policy.app_config_policy](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_policy) | resource |
 | [terraform_data.current_config_file_content](https://registry.terraform.io/providers/hashicorp/terraform/latest/docs/resources/data) | resource |
 | [aws_iam_policy_document.app_config_policy](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source |
+
 ## Inputs
 
 | Name | Description | Type | Default | Required |
@@ -60,6 +62,7 @@ module "app_config" {
 | <a name="input_dev_config_enabled"></a> [dev\_config\_enabled](#input\_dev\_config\_enabled) | n/a | `bool` | n/a | yes |
 | <a name="input_environment"></a> [environment](#input\_environment) | Deployment environment tag used for naming and labeling (e.g., dev, prod) | `string` | n/a | yes |
 | <a name="input_owner"></a> [owner](#input\_owner) | Identifies the team or person responsible for the resource (used for tagging). | `string` | n/a | yes |
+
 ## Outputs
 
 | Name | Description |

infrastructure/modules/app_config/configurations/README.md

@@ -1,11 +1,11 @@
-Important!
+# Important Notice About App Configurations
 
 If any app configurations are modified manually e.g. new flag version, terraform will not be able to delete the App Config instances as it does not own the Feature Flag versions.
-Therefore we have three instances of the configuration per deployment. 
+Therefore we have three instances of the configuration per deployment.
 
 {date}-dev.json  (sandboxes, dev and test)
 {date}-pre-prod.json
 {date}-prod.json
 
-It is recomended that all feature flags are enabled for the dev version to reduce manual app config actions. 
-The prod version should be set to what we expect our prod instances to represent.  
+It is recomended that all feature flags are enabled for the dev version to reduce manual app config actions.
+The prod version should be set to what we expect our prod instances to represent.

infrastructure/modules/cloudfront/README.md

@@ -36,6 +36,7 @@ module "cloudfront" {
 | Name | Version |
 |------|---------|
 | <a name="requirement_aws"></a> [aws](#requirement\_aws) | ~> 5.0 |
+
 ## Resources
 
 | Name | Type |
@@ -45,6 +46,7 @@ module "cloudfront" {
 | [aws_cloudfront_distribution.distribution_with_secondary_bucket](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cloudfront_distribution) | resource |
 | [aws_cloudfront_origin_access_control.cloudfront_s3_oac](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cloudfront_origin_access_control) | resource |
 | [aws_cloudfront_origin_request_policy.viewer_policy](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cloudfront_origin_request_policy) | resource |
+
 ## Inputs
 
 | Name | Description | Type | Default | Required |
@@ -58,6 +60,7 @@ module "cloudfront" {
 | <a name="input_secondary_bucket_id"></a> [secondary\_bucket\_id](#input\_secondary\_bucket\_id) | Secondary bucket ID | `string` | n/a | yes |
 | <a name="input_secondary_bucket_path_pattern"></a> [secondary\_bucket\_path\_pattern](#input\_secondary\_bucket\_path\_pattern) | Path pattern for secondary bucket | `string` | n/a | yes |
 | <a name="input_web_acl_id"></a> [web\_acl\_id](#input\_web\_acl\_id) | Web ACL to associate this CloudFront distribution with. | `string` | `""` | no |
+
 ## Outputs
 
 | Name | Description |