feat(graphql-transformer): warn on unused stackMappings keys during s…

[Simone319]

Description

Adds synthesis-time validation for stackMappings keys. When a user provides mapping keys that don't match any generated resolver, a warning is emitted during cdk synth (before deployment).

Problem

Invalid stackMappings keys (typos or stale entries after renaming a model) are silently ignored — the resolver falls back to its default stack with zero feedback. Users have no way to know their mapping isn't taking effect.

Solution

During the existing resolver collection phase in GraphQLTransform.collectResolvers(), track which stackMappings keys match a generated resolver's logical ID. After the loop, warn on any unmatched keys:

stackMappings contains keys that don't match any generated resolver: [CreateOrdersResolver]. These keys will be ignored.

This is a warning (not an error) to maintain backward compatibility with existing users who may have stale keys.

Changes

File	Change
packages/amplify-graphql-transformer-core/src/transformation/transform.ts	Added unused key detection inside collectResolvers() loop + console.warn
packages/amplify-graphql-transformer-core/src/transformer-context/resolver.ts	Made resolverLogicalId public readonly (needed for validation access)
packages/amplify-graphql-transformer/src/__tests__/stack-mappings-validation.test.ts	5 integration tests covering valid keys, invalid keys, empty mappings

How it works

Integrated into the existing collectResolvers() loop (single pass, no extra iteration):

const seenMappingKeys = new Set<string>();

for (const [resolverName, resolver] of resolverEntries) {
  const logicalId = (resolver as TransformerResolver).resolverLogicalId;
  if (this.stackMappingOverrides[logicalId]) {
    seenMappingKeys.add(logicalId);
  }
  // ... existing slot + synthesize logic ...
}

const unusedKeys = Object.keys(this.stackMappingOverrides).filter((key) => !seenMappingKeys.has(key));
if (unusedKeys.length > 0) {
  console.warn(`stackMappings contains keys that don't match any generated resolver: [${unusedKeys.join(', ')}]. These keys will be ignored.`);
}

Design decisions

• Warning, not error — Existing CDK-direct users of @aws-amplify/graphql-api-construct may have stale keys. Throwing would break them on upgrade.
• Single pass — Validation piggybacks on the existing resolver collection loop rather than iterating twice.
• No StackManager modification — Validation is done in transform.ts using collected resolvers, keeping StackManager clean (single responsibility).

Testing

• ✓ warns when stackMappings contains keys that do not match any generated resolver
• ✓ warns listing multiple invalid keys
• ✓ does not warn when stackMappings contains only valid resolver keys
• ✓ does not warn when stackMappings is empty
• ✓ does not warn when no stackMappings is provided

Companion PR

This validation works alongside the stackMappings exposure PR in amplify-backend: feat/stack-mappings

Checklist

• If this PR includes a functional change to the runtime behavior of the code, I have added or updated automated test coverage for this change.
• If this PR requires a change to the Project-Level Configuration Schema, I have added the schema change.

[adrianjoshua-strutt]

Should we use this.logs.push() here?

[Simone319]

Yes, updated to use this.logs.push().