CloudFormation: Serverless / SAM-style placeholders

[aldokimi]

Context

MiniStack’s CloudFormation path parses JSON/YAML and resolves standard intrinsic functions (Ref, Fn::Sub, etc.). It does not evaluate tooling-specific syntax that often appears in templates before packaging, for example:

• ${file(...)} (Serverless Framework)
• ${self:...} (Serverless)
• Custom pseudo-types such as MasonFn::...

Those strings usually pass through unchanged, which can look like “MiniStack accepted the stack” even though values are not what you’d get after serverless package, sam package, or cdk synth.

Proposal (for discussion, not a firm design)

I’ve been exploring a small, opt-in layer that:

1. Scans the parsed template object for a few well-known substrings (cheap, no new deps).
2. Logs a warning when they appear (so operators see it in logs).
3. Optionally, with an env var such as MINISTACK_CFN_FAIL_ON_CUSTOM_SYNTAX=1, returns ValidationError on ValidateTemplate, CreateStack, UpdateStack, CreateChangeSet, and GetTemplateSummary so CI or local workflows can fail fast if someone submits an uncompiled template.

Documentation would spell out: “compile first; MiniStack is not a Serverless/SAM engine.”

Questions for maintainers and users

1. Is this direction wanted at all? Or do you prefer staying 100% passive (no scans, docs only)?
2. Default behavior: warn-only vs. reject-by-default is a big product decision. Is warn-only + opt-in strict the right split for MiniStack’s audience (CDK/TF/Serverless mix)?
3. Scope of patterns: Should we limit detection to a short allowlist (e.g. ${file(, ${self:, MasonFn::) to avoid false positives, or is there a list you’d like (e.g. ${AWS::, SAM AWS::Serverless::* only in Transform, etc.)?
4. API fidelity: Strict mode deliberately adds validation that real AWS might not perform the same way. Is that acceptable for an emulator if it’s env-gated and documented?
5. Alternatives: Would you rather see this only as README / docs and maybe ValidateTemplate CapabilitiesReason-style messaging, with no new env var?

What I’m not proposing (here)

Actually expanding ${file(...)} / ${self:...} inside MiniStack (full Serverless macro engine). That’s a different project (dependencies, config roots, variable scopes, plugins).

---

I’d love maintainer guidance on whether to pursue the “detect + document + optional strict gate” approach, adjust it, or drop it in favor of documentation only. Happy to turn consensus into a small PR once there’s alignment.

[jgrumboe]

What is AWS CloudFormation API doing with such a template? Would it be rejected or pass-through and then later the stack creation would fail with some error?