iam-floyd 0.761.0 → 0.764.0

package/AGENTS.md

@@ -10,138 +10,238 @@ IAM Floyd is an AWS IAM policy statement generator with a fluent interface. It g
 
 ### Generated Code Structure
 
-- `lib/generated/policy-statements/` - Contains generated TypeScript classes for each AWS service (400+ services)
-- `lib/generated/index.ts` - Main export file that re-exports all service classes
+- `lib/generated/policy-statements/` - Generated TypeScript class per AWS service (460+ files)
+- `lib/generated/index.ts` - Re-exports all service classes
 - `lib/generated/aws-managed-policies/` - Generated AWS managed policies
-- `lib/shared/` - Core shared classes like `PolicyStatement`, `All`, and `Operator`
-- `lib/collection/` - Predefined policy collections and utilities
+- `lib/shared/` - Hand-written core: `PolicyStatement`, `All`, `Operator`, `AccessLevel`
+- `lib/collection/` - Predefined policy collection utilities
+- `lib/generator/` - Scrapes AWS docs and generates `lib/generated/` via `cheerio` + `ts-morph`
 
-### Code Generation Pipeline
+### PolicyStatement Inheritance Chain
 
-The codebase uses a sophisticated generation system:
+Built in 10 numbered layers (`lib/shared/policy-statement/`):
 
-1. `bin/generate.ts` - Main generation entry point that orchestrates the process
-2. `lib/generator/` - Contains the generation logic that scrapes AWS documentation
-3. Generated files are created in TypeScript and compiled to JavaScript for distribution
+```
+1-base → 2-conditions → 3-actions → 4-resources → 5-effect
+       → 6-arn-defaults → 8-principals → 10-final (PolicyStatement)
+```
+
+Each `*.CDK.ts` file is the CDK variant of that layer (swapped in by `bin/mkcdk.ts`).
+
+### Dual Package Strategy
 
-### Key Classes
+One codebase produces two npm packages:
 
-- `PolicyStatement` - Base class for all policy statement builders
-- `All` - Global action provider for cross-service policies
-- Service-specific classes (e.g., `S3`, `EC2`, `Lambda`) - Each AWS service gets its own class with methods for actions, resources, and conditions
+- `iam-floyd` - Standalone (uses built-in base class)
+- `cdk-iam-floyd` - Extends `aws_iam.PolicyStatement` from AWS CDK
+
+`bin/mkcdk.ts` transforms between variants by swapping `*.CDK.ts` files and rewriting constructors.
 
 ## Development Commands
 
-### Building and Compilation
+### Build
 
 ```bash
-# Build the project (compiles TypeScript)
-make build
-# Convert project to CDK-variant
+make build           # tsc --build --force tsconfig.main.json
+make package         # build + npm pack
+make clean           # remove node_modules, *.js, *.d.ts
+make install         # clean + npm i
 ```
 
 ### Code Generation
 
 ```bash
-# Generate service classes from AWS documentation
-make generate
-# Force regeneration (ignores time-based cache)
-make generate-force
-# Generate AWS managed policies index
-make index-managed-policies
+make generate        # generate lib/generated/ from AWS docs (25hr cache)
+make generate-force  # NOCACHE=1 - ignores time-based cache
+make index-managed-policies  # regenerate AWS managed policies index
 ```
 
 ### Testing
 
+The project has **no unit test framework**. Tests are integration-style: TypeScript examples are compiled, run, and their output is diffed against stored `.result` files.
+
 ```bash
-# Run main tests
-make test
-# Run CDK-specific tests
-make cdk-test
-# Convert package to CDK variant and run CDK-specific tests
-make cdk-all
+make test            # compile examples/ + diff against *.result files (standalone)
+make test-typescript # same, via Test.TypeScript.Makefile
+make cdk-test        # CDK test: real deploy + destroy via AWS CDK
+make cdk-all         # cdk + install + build + cdk-test
 ```
 
-### Linting and Code Quality
+**Run a single example test manually:**
 
 ```bash
-# Run ESLint
-make eslint
-# ESLint is configured with TypeScript, Prettier, and deprecation rules
+# 1. Compile a single example
+npx tsc -p tsconfig.test-iam-floyd.json
+
+# 2. Run and compare output
+node examples/allow/allow.js > /tmp/out.txt
+diff /tmp/out.txt examples/allow/allow.result
+
+# Or run the integration test harness directly:
+npx ts-node test/main.ts
 ```
 
-### Package Management
+**Regenerate expected results** (after intentional changes):
 
 ```bash
-# Create npm package
-make package
-# Clean all generated files and dependencies
-make clean
-# Reinstall dependencies
-make install
+make regenerate-code-example-results
 ```
 
-### CDK Variant Management
+### Linting
 
 ```bash
-# Convert to CDK variant (modifies package.json and lib structure)
-make cdk
-# Revert CDK changes
-make uncdk
+make eslint          # npx eslint .
 ```
 
-## Project Structure Patterns
+### CDK Variant
 
-### Dual Package Strategy
+```bash
+make cdk             # transforms codebase to CDK variant (modifies lib/shared, lib/generated, package.json)
+make uncdk           # reverts via git stash (lib/generated, lib/shared, package.json)
+```
+
+## Fixing AWS Documentation Errors (`lib/generator/fixes.ts`)
+
+The generator scrapes live AWS docs, which sometimes contain errors or inconsistencies. `fixes.ts` is the central place to patch these before code is generated. **When the generator produces wrong output, add a fix here rather than editing generated files.**
+
+### `fixes` object (keyed by URL slug)
 
-The project maintains two npm packages from a single codebase:
+Each top-level key is the URL slug of a service's IAM docs page (e.g. `ec2`, `ssm`, `'neptune-db'`). Supported sub-keys:
 
-- `iam-floyd` - Standalone IAM policy generator
-- `cdk-iam-floyd` - AWS CDK integration that extends `iam.PolicyStatement`
+| Sub-key                              | Effect                                                                                                                                                        |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ignore: true`                       | Skip generating this service entirely (used for EOL services)                                                                                                 |
+| `name: 'slug'`                       | Override the generated filename and class name (needed when the same service prefix spans multiple doc pages, e.g. `pinpointemailservice` → `ses-pinpoint`)   |
+| `service: 'prefix'`                  | Override the IAM service prefix used in the generated code                                                                                                    |
+| `resourceTypes.<name>.arn`           | Replace the ARN template for a resource type with a corrected one                                                                                             |
+| `conditions.<key>.key`               | Rewrite the condition key string (used when docs have a concrete example key like `RequestTag/tag-key` instead of the parametric form `RequestTag/${TagKey}`) |
+| `conditions.<key>.methodName`        | Override the generated `ifXxx()` method name for a condition                                                                                                  |
+| `conditions.<key>.operator.type`     | Override the inferred operator type (e.g. force `date` instead of `string`)                                                                                   |
+| `conditions.<key>.operator.override` | Set `typeOverride` on the condition (used for custom operator generation)                                                                                     |
 
-The `bin/mkcdk.ts` script transforms the codebase between variants by modifying imports and package configuration.
+### Exported fixer functions
 
-### TypeScript Configuration
+- **`conditionFixer(service, condition)`** — Normalises condition types (`ArrayOfString` → `string`, `long` → `numeric`, etc.) and applies any key/operator overrides from `fixes`. Logs yellow `[L1/L2 fix …]` messages to stdout.
+- **`conditionKeyFixer(service, key)`** — Rewrites a raw condition key string using any `conditions.<key>.key` override defined in `fixes`.
+- **`arnFixer(service, resource, arn)`** — Applies a cascade of ARN normalisation rules:
+  1. Uppercases the first letter of every `${placeholder}` (L1)
+  2. Replaces trailing `*` wildcards with `${ResourceName}` (L2)
+  3. Deduplicates repeated placeholder names by appending a counter (L2, Rekognition workaround)
+  4. Applies the hard-coded ARN override from `fixes` if present (L3)
+     After fixing, validates the result against the canonical ARN regex and warns if it doesn't match (with a known-good exception list).
+- **`serviceFixer(service)`** — Rewrites the IAM service prefix if a `service` override is defined in `fixes`.
 
-- `tsconfig.json` - Main TypeScript configuration with strict settings
-- `tsconfig.main.json` - Production build configuration
-- `tsconfig.test-*.json` - Test-specific configurations
-- Uses SWC for faster compilation via ts-node
+### How to add a fix
 
-### Generated Code Conventions
+1. Find the service's URL slug from its IAM docs URL (e.g. `https://…/list_amazons3.html` → slug is `s3`).
+2. Add an entry to the `fixes` object in `lib/generator/fixes.ts`.
+3. Run `make generate-force` to regenerate with the fix applied.
 
-- All generated classes follow the pattern: `export class ServiceName extends PolicyStatement`
-- Method names correspond to AWS IAM action names (e.g., `getObject()`, `listBuckets()`)
-- Resource and condition methods use fluent interface patterns
-- Generated files include comprehensive JSDoc comments from AWS documentation
+## File Modification Rules
 
-## Important Notes
+**CRITICAL: Never manually edit files in `lib/generated/`.**
+They are auto-generated from AWS documentation and will be overwritten on next `make generate`.
 
-### File Modification Rules
+Allowed manual edits:
 
-- **Never manually edit files in `lib/generated/`** - These are auto-generated and will be overwritten
-- Generated code is created from AWS documentation and should only be updated via the generation process
-- Manual changes should only be made to files in `lib/shared/`, `lib/collection/`, and core infrastructure
+- `lib/shared/` - Core shared classes
+- `lib/collection/` - Predefined collections
+- `lib/generator/` - Generation logic and fixes
+- `bin/` - CLI scripts
+- `test/` - Integration test scripts
+- `examples/` - Example files and their `.result` counterparts
 
-### Code Style
+## Code Style
 
-- ESLint enforces strict TypeScript rules with Prettier formatting
-- Single quotes for strings, except in YAML files
-- Comprehensive type checking with `noImplicitAny` and strict null checks
-- Generated files are excluded from linting (`lib/generated/*` in `.eslintrc`)
+### Formatting (Prettier + ESLint)
 
-### Testing Strategy
+- **Indentation**: 2 spaces (tabs only in Makefiles)
+- **Quotes**: Single quotes in TypeScript/JS; double quotes in YAML/JSON
+- **Trailing newline**: Required on all files
+- **No trailing whitespace**
+- Line endings: LF (`\n`)
 
-- Tests are located in the `test/` directory with its own Makefile
-- Supports both unit tests for the main package and CDK integration tests
-- CDK tests include actual deployment and destruction cycles for validation
+Run `make eslint` to check; Prettier is enforced via `eslint-plugin-prettier`.
+
+### TypeScript
+
+Strict settings enforced in `tsconfig.json`:
+
+```
+strict: true
+noImplicitAny: true
+strictNullChecks: true
+strictPropertyInitialization: true
+noUnusedLocals: true
+noUnusedParameters: true
+noImplicitReturns: true
+target: ES2020, module: CommonJS
+```
+
+- **No `any`**: Prefer explicit types or generics.
+- **Unused vars**: Prefix with `_` to suppress (`argsIgnorePattern: ^_`).
+- **Naming conventions**: Enforced via `@typescript-eslint/naming-convention`. Use `camelCase` for variables/functions, `PascalCase` for classes/interfaces.
+- **Template literals**: Prefer `` `${x}` `` over `'a' + x` (`prefer-template: error`).
+- **Deprecated APIs**: `deprecation/deprecation` rule is set to `error` — do not use deprecated APIs.
+- **No `require()`**: Use ES `import`/`export`.
+
+### Imports
+
+- Use named imports where possible: `import { Foo } from './foo'`
+- Relative imports within `lib/`; absolute for `node_modules`
+- `lib/generated/` is excluded from ESLint entirely
+
+### Fluent Interface Pattern
+
+All service classes return `this` to allow chaining:
+
+```typescript
+new Statement.S3()
+  .allow()
+  .toGetObject()
+  .on('arn:aws:s3:::my-bucket/*')
+  .ifAwsSourceVpc('vpc-123');
+```
+
+### JSDoc
+
+- All public methods in generated files have JSDoc with Access Level, conditions, resources, and an AWS docs URL
+- In `lib/shared/`, document non-obvious public methods and parameters
+
+## Generated Code Conventions
+
+- `export class ServiceName extends PolicyStatement`
+- Action methods: `toXxx()` — e.g., `toGetObject()`, `toListBuckets()`
+- Resource methods: `onXxx()` — e.g., `onBucket()`, `onObject()`
+- Condition methods: `ifXxx()` — e.g., `ifAwsSourceIp()`, `ifS3Prefix()`
+- All methods return `this` for chaining
+
+## TypeScript Compilation
+
+- `tsconfig.json` - Dev/generation (includes all files, uses SWC via `ts-node`)
+- `tsconfig.main.json` - Production build (excludes `bin/`, `lib/generator/`, `test/`, CDK files)
+- `tsconfig.test-iam-floyd.json` - Compiles `examples/` excluding `.cdk.ts`
+- `tsconfig.test-cdk-iam-floyd.json` - Compiles `examples/**/*.cdk.ts`
+
+SWC is used for faster transpilation: `"ts-node": { "swc": true }` in `tsconfig.json`.
 
 ## Git Commit Conventions
 
-This project follows conventional commit patterns:
+Follow conventional commits:
 
-- `chore(deps): description` - Dependency updates
 - `feat: description` - New features
 - `fix: description` - Bug fixes
+- `chore(deps): description` - Dependency updates
 - `docs: description` - Documentation changes
-- Simple format: "Updates AWS managed policies" for automated policy updates
+- `refactor: description` - Code refactoring
+- Simple prose for automated updates: `"Updates AWS managed policies"`
+
+**Never commit directly to `main`**. Use a feature branch. Commits may fail spell-checking; add missing words with `dict-add <word>`.
+
+## CI Workflows (`.github/workflows/`)
+
+- `generate.yml` - Daily: scrapes AWS docs, bumps patch version, opens PR with `automerge` label
+- `index-managed-policies.yml` - Daily: updates managed policies, opens PR with `automerge` label
+- `test-and-publish.yml` - On PR/push to main: `make install test-typescript` + CDK deploy test + npm publish
+- `automerge.yml` - Auto-merges PRs labeled `automerge` after tests pass
+- `test-docs.yml` - Builds Sphinx docs on `docs/**` changes

package/README.md

@@ -16,9 +16,9 @@
 Support for:
 
 - 445 Services
-- 20440 Actions
-- 2169 Resource Types
-- 2291 Condition keys
+- 20450 Actions
+- 2170 Resource Types
+- 2298 Condition keys
 <!-- /stats -->
 
 ![EXPERIMENTAL](https://img.shields.io/badge/stability-experimantal-orange?style=for-the-badge)**<br>This is an early version of the package. The API will change while I implement new features. Therefore make sure you use an exact version in your `package.json` before it reaches 1.0.0.**

package/lib/generated/aws-managed-policies/cdk-iam-floyd.d.ts

@@ -1604,6 +1604,14 @@ export declare class AwsManagedPolicy extends AwsManagedPolicyStatic {
     AWSElasticLoadBalancingClassicServiceRolePolicy(): aws_iam.IManagedPolicy;
     /** Service Linked Role Policy for AWS Elastic Load Balancing Control Plane */
     AWSElasticLoadBalancingServiceRolePolicy(): aws_iam.IManagedPolicy;
+    /** Provides full access to create MediaConnect Gateway Bridges and all its associated sub-resources. */
+    AWSElementalMediaConnectCreateBridge(): aws_iam.IManagedPolicy;
+    /** Provides full access to create MediaConnect Flows and all its associated sub-resources. */
+    AWSElementalMediaConnectCreateFlow(): aws_iam.IManagedPolicy;
+    /** Provides full access to delete MediaConnect Gateway Bridges and all its associated sub-resources. */
+    AWSElementalMediaConnectDeleteBridge(): aws_iam.IManagedPolicy;
+    /** Provides full access to delete MediaConnect Flows and all its associated sub-resources. */
+    AWSElementalMediaConnectDeleteFlow(): aws_iam.IManagedPolicy;
     /** Provides full access to AWS Elemental MediaConnect resources. */
     AWSElementalMediaConnectFullAccess(): aws_iam.IManagedPolicy;
     /** Provides read-only access to AWS Elemental MediaConnect resources. */
@@ -2024,6 +2032,12 @@ export declare class AwsManagedPolicy extends AwsManagedPolicyStatic {
     AWSPartnerCentralSellingResourceSnapshotJobExecutionRolePolicy(): aws_iam.IManagedPolicy;
     /** This policy can be used to grant read-only access to APIs that can read service metadata for services in your AWS account. You can use this policy to provide your partners in the Partner-Led Support Program with access to the services specified in the permissions details section below. */
     AWSPartnerLedSupportReadOnlyAccess(): aws_iam.IManagedPolicy;
+    /** Provides full access to ProServe tools. */
+    AWSPartnerProServeToolsFullAccess(): aws_iam.IManagedPolicy;
+    /** Provides access to create and manage own assessments in ProServe tools. */
+    AWSPartnerProServeToolsIndividualContributor(): aws_iam.IManagedPolicy;
+    /** Provides read access to organizational assessments with ability to manage own assessments. */
+    AWSPartnerProServeToolsOrganizationReaderIndividualContributor(): aws_iam.IManagedPolicy;
     /** Grants permission to AWS PCS compute nodes to connect to AWS PCS clusters. */
     AWSPCSComputeNodePolicy(): aws_iam.IManagedPolicy;
     /** Grants permissions to PCS to manage resources on your behalf. */