Architecture¶

┌─────────────────────────────────────────────────────────────┐
│                         CLI Layer                           │
│  (cmd/terratidy - Cobra commands)                           │
├─────────────────────────────────────────────────────────────┤
│                      Core Orchestrator                      │
│  (internal/runner - Engine coordination, parallel execution)│
├─────────────────────────────────────────────────────────────┤
│                        Engine Layer                         │
│       ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐       │
│       │   Fmt   │ │  Style  │ │  Lint   │ │ Policy  │       │
│       └─────────┘ └─────────┘ └─────────┘ └─────────┘       │
├─────────────────────────────────────────────────────────────┤
│                       Plugin System                         │
│  (internal/plugins - Custom rule loading)                   │
├─────────────────────────────────────────────────────────────┤
│                         SDK Layer                           │
│  (pkg/sdk - Public API for plugins)                         │
└─────────────────────────────────────────────────────────────┘

terratidy/
├── cmd/
│   └── terratidy/           # CLI entry points
│       ├── main.go          # Main entry
│       ├── root.go          # Root command
│       ├── check.go         # Check command
│       ├── fmt.go           # Format command
│       ├── style.go         # Style command
│       ├── lint.go          # Lint command
│       ├── policy.go        # Policy command
│       └── lsp.go           # LSP server command
├── internal/
│   ├── runner/              # Engine runner, parallel execution
│   │   └── runner.go        # Engine interface, Runner struct
│   ├── config/              # Configuration loading
│   ├── output/              # Output formatting
│   ├── engines/             # Engine implementations
│   │   ├── fmt/             # Format engine
│   │   ├── style/           # Style engine
│   │   ├── lint/            # Lint engine
│   │   └── policy/          # Policy engine
│   ├── lsp/                 # Language server
│   └── plugins/             # Plugin system
├── pkg/
│   └── sdk/                 # Public SDK
│       └── types.go         # Rule interface, Finding, Context types
└── docs/                    # Documentation

type Engine interface {
    Name() string
    Run(ctx context.Context, files []string) ([]sdk.Finding, error)
}

type Finding struct {
    Rule     string      `json:"rule"`
    Message  string      `json:"message"`
    File     string      `json:"file"`
    Location Location    `json:"location"`
    Severity Severity    `json:"severity"`
    Fix      *FixResult  `json:"fix,omitempty"`
}

type FixResult struct {
    Content []byte
}

type Runner struct {
    engines  []Engine
    parallel bool
}

func (r *Runner) Run(ctx context.Context, files []string) ([]sdk.Finding, error) {
    if r.parallel {
        return r.runParallel(ctx, files)
    }
    return r.runSequential(ctx, files)
}

func (e *FmtEngine) Run(ctx context.Context, files []string) ([]Finding, error) {
    for _, file := range files {
        content, _ := os.ReadFile(file)
        formatted := hclwrite.Format(content)

        if !bytes.Equal(content, formatted) {
            findings = append(findings, Finding{
                Rule:    "fmt",
                Message: "File is not formatted",
                File:    file,
                Fix:     &FixResult{Content: formatted},
            })
        }
    }
    return findings, nil
}

func (e *StyleEngine) Run(ctx context.Context, files []string) ([]Finding, error) {
    for _, file := range files {
        ast, _ := hclparse.ParseHCLFile(file)

        for _, rule := range e.rules {
            if e.config.IsRuleEnabled(rule.Name()) {
                findings = append(findings, rule.Check(ast)...)
            }
        }
    }
    return findings, nil
}

func (e *LintEngine) Run(ctx context.Context, files []string) ([]Finding, error) {
    // Run built-in AST rules first
    for _, file := range files {
        findings = append(findings, e.runBuiltinRules(file)...)
    }

    // Optionally invoke TFLint as subprocess (not embedded)
    if e.config.UseTFLint {
        modules := groupByModule(files)
        for _, module := range modules {
            cmd := exec.CommandContext(ctx, "tflint", "--format=json", module.Path)
            output, _ := cmd.Output()
            findings = append(findings, parseTFLintOutput(output)...)
        }
    }
    return findings, nil
}

func (e *PolicyEngine) Run(ctx context.Context, files []string) ([]Finding, error) {
    // Parse Terraform to JSON
    input := parseToJSON(files)

    // Load policies
    policies := loadPolicies(e.policyDirs)

    // Evaluate
    r := rego.New(
        rego.Query("data.terraform.deny"),
        rego.Module("policy.rego", policies),
        rego.Input(input),
    )

    rs, _ := r.Eval(ctx)
    return processResults(rs), nil
}

func Load(path string) (*Config, error) {
    // Default to .terratidy.yaml
    if path == "" {
        path = ".terratidy.yaml"
    }

    // If file doesn't exist, return defaults
    if _, err := os.Stat(path); os.IsNotExist(err) {
        return DefaultConfig(), nil
    }

    // Read, expand env vars, unmarshal YAML
    data, err := os.ReadFile(path)
    // ... expand ${VAR} and ${VAR:-default} syntax ...

    // Load imports (glob patterns)
    if len(cfg.Imports) > 0 {
        cfg.loadImports(filepath.Dir(path))
    }

    // Validate and return
    cfg.Validate()
    return &cfg, nil
}

func (c *Config) ResolveProfile(name string) *Config {
    profile, ok := c.Profiles[name]
    if !ok {
        return c
    }

    // Merge profile with base config
    merged := c.Clone()
    merged.Merge(profile)
    return merged
}

type Formatter interface {
    Format(findings []sdk.Finding, w io.Writer) error
}

┌─────────────────────────────────────────┐
│              LSP Server                 │
├─────────────────────────────────────────┤
│  ┌─────────────┐   ┌─────────────────┐  │
│  │   Handler   │   │  Document Store │  │
│  └─────────────┘   └─────────────────┘  │
├─────────────────────────────────────────┤
│ ┌─────────────────────────────────────┐ │
│ │        Engine Integration           │ │
│ └─────────────────────────────────────┘ │
└─────────────────────────────────────────┘

func (s *Server) handleTextDocumentDidChange(params DidChangeParams) {
    // Update document store
    s.documents.Update(params.URI, params.Changes)

    // Run diagnostics
    go s.publishDiagnostics(params.URI)
}

func (s *Server) publishDiagnostics(uri string) {
    content := s.documents.Get(uri)
    findings := s.runner.Run(context.Background(), []string{uri})

    diagnostics := convertToDiagnostics(findings)
    s.client.PublishDiagnostics(uri, diagnostics)
}

func LoadPlugins(dirs []string) ([]Engine, error) {
    var plugins []Engine

    for _, dir := range dirs {
        files, _ := filepath.Glob(filepath.Join(dir, "*.so"))

        for _, file := range files {
            p, _ := plugin.Open(file)
            sym, _ := p.Lookup("Engine")
            engine := sym.(Engine)
            plugins = append(plugins, engine)
        }
    }

    return plugins, nil
}