docs: Add README for RiffRaffYamlFile class

src/utils/riff-raff-yaml-file/README.md

@@ -0,0 +1,62 @@
+> **Note**
+> The `RiffRaffYamlFile` class is currently in alpha.
+> The API is subject to change.
+
+# riff-raff-yaml-file
+The `RiffRaffYamlFile` class can be used to synthesise a `riff-raff.yaml` for deployment of an application via Riff-Raff,
+so you don't have too!
+
+The aim is to produce a `riff-raff.yaml` file that works, the first time, and forever more.
+
+Currently it supports the following Riff-Raff deployment types:
+  - `cloud-formation`
+  - `aws-lambda` (for each `GuLambdaFunction` used)
+  - `autoscaling` (for each `GuAutoScalingGroup` used)
+
+## Usage
+Usage should require minimal changes to a GuCDK project:
+
+Update the file `/<repo-root>/cdk/bin/cdk.ts` from:
+
+```ts
+import { App } from "aws-cdk-lib";
+
+const app = new App();
+
+new MyStack(app, "my-stack-CODE", {});
+new MyStack(app, "my-stack-PROD", {});
+```
+
+To:
+
+```ts
+import { GuRoot } from "@guardian/cdk/lib/constructs/root";
+
+const app = new GuRoot();
+
+new MyStack(app, "my-stack-CODE", {});
+new MyStack(app, "my-stack-PROD", {});
+```
+
+When the CDK stack is synthesized, a `riff-raff.yaml` file will be created in the output directory, typically `/<repo-root>/cdk/cdk.out`.
+
+## Package layout
+`RiffRaffYamlFile` assumes CI has uploaded files in the following structure:
+
+```
+.
+├── cdk.out
+│   └── MyApplication.template.json
+├── my-application
+│   └── my-application.deb
+└── my-lambda
+    └── my-lambda.zip
+```
+
+That is, all CloudFormation templates sit in `cdk.out`, and application artifacts sit in `<app>/<filename>.deb`.
+
+Where:
+  - `app` matches the [`AppIdentity`](../../constructs/core/identity.ts) of each `GuLambdaFunction` or `GuAutoScalingGroup`
+  - `filename` matches the `filename` of each `GuLambdaFunction` or `app` of each `GuAutoScalingGroup`
+
+    Note the file extension is decided by you, `.deb` is used for illustration purposes.

src/utils/riff-raff-yaml-file.test.ts → src/utils/riff-raff-yaml-file/index.test.ts

@@ -2,11 +2,11 @@ import { App, Duration } from "aws-cdk-lib";
 import { InstanceClass, InstanceSize, InstanceType } from "aws-cdk-lib/aws-ec2";
 import { Schedule } from "aws-cdk-lib/aws-events";
 import { Runtime } from "aws-cdk-lib/aws-lambda";
-import { AccessScope } from "../constants";
-import type { GuStackProps } from "../constructs/core";
-import { GuStack } from "../constructs/core";
-import { GuEc2App, GuScheduledLambda } from "../patterns";
-import { RiffRaffYamlFile } from "./riff-raff-yaml-file";
+import { AccessScope } from "../../constants";
+import type { GuStackProps } from "../../constructs/core";
+import { GuStack } from "../../constructs/core";
+import { GuEc2App, GuScheduledLambda } from "../../patterns";
+import { RiffRaffYamlFile } from "./index";
 
 describe("The RiffRaffYamlFile class", () => {
   it("Should throw when there are missing stack definitions", () => {

src/utils/riff-raff-yaml-file.ts → src/utils/riff-raff-yaml-file/index.ts

@@ -4,10 +4,10 @@ import type { App } from "aws-cdk-lib";
 import { Token } from "aws-cdk-lib";
 import chalk from "chalk";
 import { dump } from "js-yaml";
-import { GuAutoScalingGroup } from "../constructs/autoscaling";
-import { GuStack } from "../constructs/core";
-import { GuLambdaFunction } from "../constructs/lambda";
-import { groupBy } from "./array";
+import { GuAutoScalingGroup } from "../../constructs/autoscaling";
+import { GuStack } from "../../constructs/core";
+import { GuLambdaFunction } from "../../constructs/lambda";
+import { groupBy } from "../array";
 
 // type aliases to, hopefully, improve readability
 type ClassName = string;