feat: Move GuDeveloperPolicy out of experiment

[kelvin-chappell]

Now that we have some developer policies in production in Janus the requirements of the CDK constructs are well understood.
In this change, we move the class and its supporting types into the iam/policies package and do some renaming and slight changes to attributes:

1. permission attribute -> grantId attribute
2. description attribute is now required
3. statements is now required and must have at least one statement

[changeset-bot]

🦋 Changeset detected

Latest commit: db58333

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@guardian/cdk	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[Copilot]

Pull request overview

Moves the Janus developer managed policy construct out of experimental into the stable constructs/iam/policies package, updating its API to match production usage and tightening required props.

Changes:

• Relocated the developer policy construct into src/constructs/iam/policies and exported it from the stable policies barrel.
• Renamed permission → grantId, made description required, and required at least one statement at the type level.
• Updated and expanded unit tests for the new construct and checker behavior.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/experimental/constructs/iam/policies/index.ts	Removes the experimental barrel export for the developer policy.
src/experimental/constructs/iam/policies/developer-policy.ts	Removes the experimental implementation (migrated to stable constructs).
src/constructs/iam/policies/index.ts	Exports the new stable developer-policy module.
src/constructs/iam/policies/developer-policy.ts	Adds the new GuDeveloperPolicy construct and its validation aspect.
src/constructs/iam/policies/developer-policy.test.ts	Updates tests to use the new construct/API and adds checker edge-case coverage.

Comments suppressed due to low confidence (1)

src/constructs/iam/policies/developer-policy.test.ts:36

• The first test asserts the synthesized template, but it doesn't assert that no annotation errors were added for a valid (non-wildcard) Allow statement. Adding a hasNoError assertion here would prevent regressions where the checker starts flagging valid statements (e.g. due to wildcard matching logic changes).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[akash1810]

What is a Janus DeveloperPolicyGrant? Can we link to any docs for this? The comment suggests it must be a particular string. Does Janus own this string? If so, could we reference it via an SSM Parameter instead of requiring clients to provide it?

[kelvin-chappell]

We are expecting these policies to outlive Janus so Janus doesn't really own this string. Perhaps it would be better to express it the other way around.

[akash1810]

Just a thought - it looks like the grantId is used to form the path. We say it is a "unique identifier" too - presumably this is unique across the account? Should we include the repository name in the path? That is:

path: `/developer-policy/${scope.repositoryName}/${props.grantId}/`

This would increase the chances of having a unique string and also increase discoverability of where the resource is defined in VCS.

[kelvin-chappell]

Actually that comment needs a bit of clarification. There's a one-to-many relationship between developer policy grants (which is an abstract concept as far as CDK is concerned) and developer policies. So there might be many policies with the same grantId in an AWS account (and across other AWS accounts). So the grantId is a unique identifier for a particular grant. I'll make that a bit clearer.
But including the repo name in the path might improve discoverability assuming anyone can find the path - it only appears in the AWS console in list view.

[akash1810]

Might janusDisplayName be more a intention revealing name for this property?

[akash1810]

Keep this short so it fits on a single line in the Janus UI.

This is quite abstract. Could we add a max length recommendation/check?

[kelvin-chappell]

It's slightly awkward that when you look at this in AWS it will have this as the managed policy description so it seems sensible to leave it as description and use the jsdoc to describe its use. But a max length check is an excellent idea.