plan

Documentation

Index

• Constants
• Variables
• func DefaultCriticalResources() []string
• func MergeCriticalResources(defaults, userDefined []string) []string
• type AnalysisConfig
  • func LoadAnalysisConfig(v *viper.Viper) *AnalysisConfig
• type AnalyzedResource
  • func FilterResources(resources []AnalyzedResource, filter *ResourceFilter) []AnalyzedResource
• type ChangeDetail
• type OutputChange
• type PlanAnalysis
  • func (a *PlanAnalysis) ExitCode() int
• type PlanAnalyzer
  • func NewPlanAnalyzer() *PlanAnalyzer
  • func NewPlanAnalyzerWithConfig(v *viper.Viper) *PlanAnalyzer
  • func NewPlanAnalyzerWithTypes(criticalTypes []string) *PlanAnalyzer
  • func (a *PlanAnalyzer) Analyze(plan *TerraformPlan) *PlanAnalysis
• type PlanFormatter
  • func NewPlanFormatter(useColor bool) *PlanFormatter
  • func NewPlanFormatterFiltered(useColor bool, topResourcesCount int, totalResourceCount int, ...) *PlanFormatter
  • func NewPlanFormatterWithConfig(useColor bool, topResourcesCount int) *PlanFormatter
  • func (f *PlanFormatter) Format(analysis *PlanAnalysis, outputFormat format.OutputFormat, w io.Writer) error
• type ResourceChange
• type ResourceFilter
  • func (f *ResourceFilter) Descriptions() []string
  • func (f *ResourceFilter) IsEmpty() bool
  • func (f *ResourceFilter) Match(r AnalyzedResource) bool
  • func (f *ResourceFilter) Validate() error
• type Severity
  • func (s Severity) Order() int
• type TerraformPlan
  • func ParsePlanFile(filename string) (_ *TerraformPlan, retErr error)

Constants

const (
	// ExitCodeSuccess indicates no infrastructure changes detected
	ExitCodeSuccess = 0
	// ExitCodeChanges indicates non-critical changes detected (creates, updates)
	ExitCodeChanges = 1
	// ExitCodeCritical indicates critical changes detected (deletes, replacements)
	ExitCodeCritical = 2
)

Exit codes for plan analysis

const (
	ActionCreate  = "create"
	ActionDelete  = "delete"
	ActionUpdate  = "update"
	ActionRead    = "read"
	ActionNoOp    = "no-op"
	ActionReplace = "replace" // synthetic: delete + create
)

Action string constants used across parsing, analysis, and formatting

const (
	// DefaultTopResourcesCount is the default number of resources to show in top-N summaries
	DefaultTopResourcesCount = 10
)

Variables

var (
	// ErrUnknownSeverity indicates an invalid severity filter value.
	ErrUnknownSeverity = errors.New("unknown severity")
	// ErrUnknownAction indicates an invalid action filter value.
	ErrUnknownAction = errors.New("unknown action")
	// ErrConflictingFilters indicates mutually exclusive filters were both set.
	ErrConflictingFilters = errors.New("--min-severity and --filter-severity are mutually exclusive")
)

var (
	// ErrBinaryFormat indicates the plan file is in binary format
	ErrBinaryFormat = errors.New("plan file is in binary format")
	// ErrMissingFormatVersion indicates the plan file is missing format_version
	ErrMissingFormatVersion = errors.New("invalid plan file: missing format_version")
)

var (
	// ErrUnsupportedPlanFormat indicates an unsupported output format
	ErrUnsupportedPlanFormat = errors.New("unsupported format")
)

Functions

func DefaultCriticalResources

func DefaultCriticalResources() []string

DefaultCriticalResources returns the default list of AWS resources considered critical. These resources are categorized by their risk level when modified or deleted.

func MergeCriticalResources

func MergeCriticalResources(defaults, userDefined []string) []string

MergeCriticalResources merges default and user-defined critical resources, removing duplicates and maintaining order (defaults first, then user-defined).

Types

type AnalysisConfig

type AnalysisConfig struct {
	CriticalResources []string `mapstructure:"critical_resources"`
	TopResourcesCount int      `mapstructure:"top_resources_count"`
}

AnalysisConfig holds plan analysis-specific configuration

func LoadAnalysisConfig

func LoadAnalysisConfig(v *viper.Viper) *AnalysisConfig

LoadAnalysisConfig loads plan analysis configuration from viper. Returns a config with user-defined critical resources, or empty list if not configured.

type AnalyzedResource

type AnalyzedResource struct {
	Address       string   `json:"address"`
	Type          string   `json:"type"`
	Name          string   `json:"name"`
	Provider      string   `json:"provider"`
	Actions       []string `json:"actions"`
	ActionString  string   `json:"action_string"`
	Severity      Severity `json:"severity"`
	ModuleAddress string   `json:"module_address,omitempty"`
}

AnalyzedResource represents a resource with analyzed change information

func FilterResources

func FilterResources(resources []AnalyzedResource, filter *ResourceFilter) []AnalyzedResource

FilterResources returns only the resources matching the filter. Returns the original slice unchanged if the filter is empty.

type ChangeDetail

type ChangeDetail struct {
	Actions         []string        `json:"actions"`
	Before          map[string]any  `json:"before"`
	After           map[string]any  `json:"after"`
	AfterUnknown    map[string]any  `json:"after_unknown,omitempty"`
	BeforeSensitive json.RawMessage `json:"before_sensitive,omitempty"`
	AfterSensitive  json.RawMessage `json:"after_sensitive,omitempty"`
}

ChangeDetail contains the details of what's changing Note: before_sensitive and after_sensitive can be either bool or map[string]any

type OutputChange

type OutputChange struct {
	Name      string   `json:"name"`
	Actions   []string `json:"actions"`
	Sensitive bool     `json:"sensitive"`
}

OutputChange represents a change to a Terraform output value

type PlanAnalysis

type PlanAnalysis struct {
	TotalChanges     int                `json:"total_changes"`
	Additions        int                `json:"additions"`
	Modifications    int                `json:"modifications"`
	Deletions        int                `json:"deletions"`
	Replacements     int                `json:"replacements"`
	ResourceChanges  []AnalyzedResource `json:"resource_changes"`
	TerraformVersion string             `json:"terraform_version"`
	HasChanges       bool               `json:"has_changes"`
	// Output change tracking
	OutputChanges       []OutputChange `json:"output_changes,omitempty"`
	OutputAdditions     int            `json:"output_additions"`
	OutputDeletions     int            `json:"output_deletions"`
	OutputModifications int            `json:"output_modifications"`
	OutputReplacements  int            `json:"output_replacements"`
	// Groupings for better visualization.
	// Note: These maps are not thread-safe. For concurrent usage, synchronization is required.
	ByType     map[string]int `json:"by_type,omitempty"`
	ByModule   map[string]int `json:"by_module,omitempty"`
	BySeverity map[string]int `json:"by_severity,omitempty"`
	ByAction   map[string]int `json:"by_action,omitempty"`
}

PlanAnalysis represents the analyzed plan results

func (*PlanAnalysis) ExitCode

func (a *PlanAnalysis) ExitCode() int

ExitCode returns the appropriate exit code based on analysis results. Returns ExitCodeSuccess (0) for no changes, ExitCodeChanges (1) for non-critical changes, and ExitCodeCritical (2) for critical changes (deletions or replacements).

type PlanAnalyzer

type PlanAnalyzer struct {
	// contains filtered or unexported fields
}

PlanAnalyzer analyzes terraform plans and assesses change severity

func NewPlanAnalyzer

func NewPlanAnalyzer() *PlanAnalyzer

NewPlanAnalyzer creates a new plan analyzer with default critical resource types

func NewPlanAnalyzerWithConfig

func NewPlanAnalyzerWithConfig(v *viper.Viper) *PlanAnalyzer

NewPlanAnalyzerWithConfig creates a plan analyzer with default critical resources merged with user-defined resources from viper config. This allows extending the default list via .tfskel.yaml configuration.

func NewPlanAnalyzerWithTypes

func NewPlanAnalyzerWithTypes(criticalTypes []string) *PlanAnalyzer

NewPlanAnalyzerWithTypes creates a plan analyzer with custom critical resource types

func (*PlanAnalyzer) Analyze

func (a *PlanAnalyzer) Analyze(plan *TerraformPlan) *PlanAnalysis

Analyze processes a terraform plan and produces detailed analysis. Returns an empty analysis if plan is nil.

type PlanFormatter

type PlanFormatter struct {
	// contains filtered or unexported fields
}

PlanFormatter handles formatting of plan analysis results

func NewPlanFormatter

func NewPlanFormatter(useColor bool) *PlanFormatter

NewPlanFormatter creates a new plan formatter with auto-detected terminal width

func NewPlanFormatterFiltered

func NewPlanFormatterFiltered(useColor bool, topResourcesCount int, totalResourceCount int, activeFilters []string) *PlanFormatter

NewPlanFormatterFiltered creates a formatter with filter metadata. totalResourceCount is the original unfiltered count, activeFilters are human-readable descriptions.

func NewPlanFormatterWithConfig

func NewPlanFormatterWithConfig(useColor bool, topResourcesCount int) *PlanFormatter

NewPlanFormatterWithConfig creates a new plan formatter with configuration. topResourcesCount: 0 = show all (unlimited), negative = use default (10), positive = use that limit.

func (*PlanFormatter) Format

func (f *PlanFormatter) Format(analysis *PlanAnalysis, outputFormat format.OutputFormat, w io.Writer) error

Format outputs the plan analysis in the specified format

type ResourceChange

type ResourceChange struct {
	Address       string       `json:"address"`
	ModuleAddress string       `json:"module_address,omitempty"`
	Mode          string       `json:"mode"`
	Type          string       `json:"type"`
	Name          string       `json:"name"`
	ProviderName  string       `json:"provider_name"`
	Change        ChangeDetail `json:"change"`
	ActionReason  string       `json:"action_reason,omitempty"`
}

ResourceChange represents a change to a resource in the plan

type ResourceFilter

type ResourceFilter struct {
	Severities  []string
	MinSeverity string
	Actions     []string
}

ResourceFilter holds filter criteria for plan resources. All non-empty fields use AND semantics across dimensions, OR semantics within each dimension. MinSeverity and Severities are mutually exclusive.

func (*ResourceFilter) Descriptions

func (f *ResourceFilter) Descriptions() []string

Descriptions returns human-readable strings describing each active filter, e.g. ["severity=critical,high", "action=delete"].

func (*ResourceFilter) IsEmpty

func (f *ResourceFilter) IsEmpty() bool

IsEmpty reports whether no filters are active.

func (*ResourceFilter) Match

func (f *ResourceFilter) Match(r AnalyzedResource) bool

Match reports whether the resource matches all active filters. Empty filter dimensions are skipped (match everything).

func (*ResourceFilter) Validate

func (f *ResourceFilter) Validate() error

Validate checks all filter values against known constants. Returns a descriptive error for unknown values or conflicting filters.

type Severity

type Severity string

Severity represents the risk level of a change

const (
	// SeverityLow indicates low-risk changes (additions)
	SeverityLow Severity = "low"
	// SeverityMedium indicates medium-risk changes (standard updates)
	SeverityMedium Severity = "medium"
	// SeverityHigh indicates high-risk changes (updates to critical resources)
	SeverityHigh Severity = "high"
	// SeverityCritical indicates critical changes (deletions or replacements)
	SeverityCritical Severity = "critical"
)

func (Severity) Order

func (s Severity) Order() int

Order returns the sort order for a severity level. Lower values are sorted first (higher priority).

type TerraformPlan

type TerraformPlan struct {
	FormatVersion    string           `json:"format_version"`
	TerraformVersion string           `json:"terraform_version"`
	PlannedValues    map[string]any   `json:"planned_values,omitempty"`
	ResourceChanges  []ResourceChange `json:"resource_changes"`
	OutputChanges    map[string]any   `json:"output_changes,omitempty"`
	PriorState       map[string]any   `json:"prior_state,omitempty"`
	Configuration    map[string]any   `json:"configuration,omitempty"`
}

TerraformPlan represents the structure of terraform plan JSON output

func ParsePlanFile

func ParsePlanFile(filename string) (_ *TerraformPlan, retErr error)

ParsePlanFile reads and parses a terraform plan JSON file using streaming decoder to reduce memory usage. The plan file must be in JSON format generated with:

terraform plan -out=tfplan.binary
terraform show -json tfplan.binary > tfplan.json