Support direct validation of IaC (Terraform, Bicep etc) against a CALM Pattern

[graphlet]

Feature Proposal

Target Project:

The feature introduces a new CLI command and reuses or extends the shared validation pipeline.
• finos/calm-cli
• finos/calm-shared

Description of Feature:

Introduce support for Terraform to CALM validation. This will enable users to validate Terraform infrastructure directly against a CALM Architecture pattern. Terraform users will no longer have to convert back to a CALM architecture as they make changes to run the validation.

The feature will:

1. Extract details from a Terraform infrastructure via terraform plan -json or terraform show -json into a provider agnostic IaC IR Graph.
2. Derive a CALM architecture instance via configurable mapping rules from the IR
3. Validate the derived architecture using the existing CALM validation pipeline

User Stories:

As a platform engineer, I want to validate Terraform plans against a CALM pattern so that I can enforce architectural standards before deployment.

Current Limitations:

Currently there is no way to validate IaC directly - requires a manual (or AI based) translation to CALM Architecture. Also, it assumes that all changes to the IaC will be done by making changes to the CALM architecture first.

Proposed Implementation:

High-Level Architecture

Step 1: IaC Graph Extractor
Introduce a provider-agnostic IR model inside calm-shared:
• Resources (type, provider, module path, attributes)
• Relationships (references, dependencies)
• Provenance (resource address, optional file location)

This allows future support for other IaC systems (Bicep, ARM, CloudFormation).

Generate Terraform Plan/State JSON
Parses JSON output into the IR model.

Step 2: Mapping Engine (config-driven)
Introduce a mapping configuration file (YAML or JSON):

Example responsibilities:
• Map Terraform resource types → CALM node-types
• Define interface mappings
• Infer CALM controls from Terraform attributes
• Define relationship mappings
• Support rule precedence and overrides

This avoids hardcoding cloud-provider semantics into CALM.

Step 3: Derived CALM Architecture & validate
New CLI Command

calm validate-terraform \
  --pattern <pattern.json> \
  --tf-dir <terraform-directory> \
  [--mapping <mapping-config.json>]

Internally:
• Generate derived CALM architecture
• Call existing validate() in @finos/calm-shared
• Surface validation errors mapped back to Terraform resource addresses

API Changes
New exported functions in @finos/calm-shared:
• IacAdapter
• TerraformPlanAdapter
• deriveCalmArchitectureFromIac(ir, mappingConfig)
No breaking changes to existing validation APIs.

Alternatives Considered:

...what other approaches were considered and why were they rejected?

Testing Strategy:

Unit Tests
• Terraform JSON → IR conversion
• IR → CALM architecture mapping
• Mapping rule precedence and overrides
• Control inference logic

Integration Tests
• Sample Terraform project → validate against example CALM pattern
• Failure cases (missing controls, invalid topology)

CLI Tests
• Command invocation
• Error reporting

Documentation Requirements:

•	New documentation page: “Validating Terraform Against CALM Patterns”
•	Mapping configuration reference
•	CLI usage examples

Implementation Checklist:

• Design reviewed and approved
• Implementation completed
• Tests written and passing
• Documentation updated
• Relevant workflows updated (if needed)
• Performance impact assessed

Additional Context:

This feature positions CALM as a governance layer directly over real infrastructure code.
Future extensions:
• Bicep/ARM support
• CloudFormation support
• Drift detection (state vs pattern validation)