main.go

// Package main provides a CLI tool for updating Terraform module versions, Terraform versions,
// and provider versions across multiple files.
//
// The tool supports five modes of operation:
//  1. Single Module Mode: Update one module at a time via command-line flags
//  2. Config File Mode: Update multiple modules using a YAML configuration file
//  3. Config Validation Mode: Validate a YAML configuration file without updating Terraform files
//  4. Terraform Version Mode: Update Terraform required_version in terraform blocks
//  5. Provider Version Mode: Update provider versions in terraform required_providers blocks
//
// It uses the official HashiCorp HCL library to parse and modify Terraform files while retaining
// comments and HCL structure. Changed files are normalised by hclwrite.Format.
package main

import (
	"bytes"
	"encoding/json"
	stderrors "errors"
	"flag"
	"fmt"
	"io"
	"io/fs"
	"log"
	"os"
	"path/filepath"
	"slices"
	"strings"
	"sync"

	"github.com/bmatcuk/doublestar/v4"
	"github.com/hashicorp/hcl/v2"
	"github.com/hashicorp/hcl/v2/hclsyntax"
	"github.com/hashicorp/hcl/v2/hclwrite"
	tfaddr "github.com/hashicorp/terraform-registry-address"
	"github.com/zclconf/go-cty/cty"
)

type visibleDirFS struct {
	fs.ReadDirFS
}

func (f visibleDirFS) ReadDir(name string) ([]fs.DirEntry, error) {
	entries, err := f.ReadDirFS.ReadDir(name)
	if err != nil {
		return nil, err
	}

	visible := entries[:0]
	for _, entry := range entries {
		if entry.IsDir() && strings.HasPrefix(entry.Name(), ".") {
			continue
		}
		visible = append(visible, entry)
	}
	return visible, nil
}

// Build information set by ldflags
var (
	version = "dev"
	commit  = "none"
	date    = "unknown"
)

var (
	hookMu   sync.Mutex // guards test hook variables
	exitFunc = os.Exit
	fatalf   = func(format string, v ...interface{}) {
		log.Printf(format, v...)
		exitFunc(1)
	}
	// renameReportFile moves a written report onto its destination, the last step of publishing it.
	renameReportFile = os.Rename
	// removeReportFile deletes a report an earlier run left where this run's report was to go.
	removeReportFile = os.Remove
	// openFileForRewrite opens a Terraform file to rewrite it in place: without O_CREATE, so a file
	// deleted since its parse is not recreated, and without O_TRUNC, so a failed write can be undone.
	openFileForRewrite = func(name string) (rewritableFile, error) {
		file, err := os.OpenFile(name, os.O_RDWR, 0)
		if err != nil {
			return nil, err
		}
		return file, nil
	}
	// createBackupFile creates the copy of a Terraform file's original bytes kept while it is
	// rewritten. It lives in the system temporary directory, which keeps it out of the reach of a
	// Terraform glob unless that directory is itself inside the tree being globbed.
	createBackupFile = func(pattern string) (backupFile, error) {
		file, err := os.CreateTemp("", pattern)
		if err != nil {
			return nil, err
		}
		return file, nil
	}
)

// stringSliceFlag is a custom flag type that allows a flag to be specified multiple times
type stringSliceFlag []string

// String returns the string representation of the flag
func (s *stringSliceFlag) String() string {
	return strings.Join(*s, ",")
}

// Set appends a value to the slice
func (s *stringSliceFlag) Set(value string) error {
	*s = append(*s, value)
	return nil
}

// quote formats a string with appropriate quoting based on the output format.
// For "text" output, uses single quotes. For "md" (Markdown) output, uses backticks.
//
// Parameters:
//   - s: The string to quote
//   - format: Output format ("text" or "md")
//
// Returns:
//   - string: The quoted string
//
// Examples:
//   - quote("vpc", "text") returns "'vpc'"
//   - quote("vpc", "md") returns "`vpc`"
func quote(s, format string) string {
	if format == "md" {
		return "`" + s + "`"
	}
	return "'" + s + "'"
}

// cliFlags holds all command-line flags
type cliFlags struct {
	pattern              string
	moduleSource         string
	toVersion            string
	fromVersions         stringSliceFlag
	ignoreVersions       stringSliceFlag
	ignoreModules        string
	branch               string
	configFile           string
	validationConfigFile string
	forceAdd             bool
	dryRun               bool
	check                bool
	verbose              bool
	showVersion          bool
	output               string
	terraformVersion     string
	providerName         string
	reportFile           string
	auditFile            string
	report               updateReport
}

type updateReport struct {
	SchemaVersion          int `json:"schema_version"`
	TerraformBlocksUpdated int `json:"terraform_blocks_updated"`
	ModuleBlocksUpdated    int `json:"module_blocks_updated"`
	ProviderBlocksUpdated  int `json:"provider_blocks_updated"`
	terraformBlockIDs      map[string]struct{}
	moduleBlockIDs         map[string]struct{}
	fileIdentities         []fs.FileInfo
}

type preparedReportFile struct {
	destination string
	file        *os.File
}

func (flags *cliFlags) reportRecorder() *updateReport {
	if flags.reportFile == "" {
		return nil
	}
	return &flags.report
}

func (report *updateReport) recordTerraformBlocks(filename string, blockIndexes []int) {
	var recorded int
	report.terraformBlockIDs, recorded = report.recordTopLevelBlocks(filename, blockIndexes, report.terraformBlockIDs)
	report.TerraformBlocksUpdated += recorded
}

func (report *updateReport) recordModuleBlocks(filename string, blockIndexes []int) {
	var recorded int
	report.moduleBlockIDs, recorded = report.recordTopLevelBlocks(filename, blockIndexes, report.moduleBlockIDs)
	report.ModuleBlocksUpdated += recorded
}

func (report *updateReport) recordTopLevelBlocks(filename string, blockIndexes []int, existingBlockIDs map[string]struct{}) (blockIDs map[string]struct{}, recordedBlocks int) {
	fileID := report.fileIdentity(filename)
	blockIDs = existingBlockIDs
	if blockIDs == nil {
		blockIDs = make(map[string]struct{})
	}
	for _, blockIndex := range blockIndexes {
		blockID := fmt.Sprintf("%s\x00%d", fileID, blockIndex)
		if _, recorded := blockIDs[blockID]; recorded {
			continue
		}
		blockIDs[blockID] = struct{}{}
		recordedBlocks++
	}
	return blockIDs, recordedBlocks
}

// recordProviderBlocks needs no de-duplication: a run names each provider once, and another path to
// the same file, a hard link or symlink, is read already at the target. Module entries can update
// one block more than once in a run, so modules, and Terraform blocks through the same helper, do.
func (report *updateReport) recordProviderBlocks(blockLocations []string) {
	report.ProviderBlocksUpdated += len(blockLocations)
}

func (report *updateReport) fileIdentity(filename string) string {
	fileInfo, err := os.Stat(filename)
	if err == nil {
		for index, existingIdentity := range report.fileIdentities {
			if os.SameFile(fileInfo, existingIdentity) {
				return fmt.Sprintf("file:%d", index)
			}
		}
		report.fileIdentities = append(report.fileIdentities, fileInfo)
		return fmt.Sprintf("file:%d", len(report.fileIdentities)-1)
	}
	return "path:" + canonicalFileIdentity(filename)
}

func canonicalFileIdentity(filename string) string {
	absolute, err := filepath.Abs(filename)
	if err == nil {
		filename = absolute
	}
	resolved, err := filepath.EvalSymlinks(filename)
	if err == nil {
		return filepath.Clean(resolved)
	}
	return filepath.Clean(filename)
}

// parseFlags parses and validates command-line flags
func parseFlags() *cliFlags {
	flags := &cliFlags{}
	usageOutput := flag.CommandLine.Output()
	flagSet := flag.NewFlagSet(os.Args[0], flag.ContinueOnError)
	flagSet.SetOutput(io.Discard)
	flag.CommandLine = flagSet

	flagSet.StringVar(&flags.pattern, "pattern", "", "Glob pattern for Terraform files; '**' matches any depth (e.g., '*.tf' or 'modules/**/*.tf')")
	flagSet.StringVar(&flags.moduleSource, "module", "", "Source of the module to update (e.g., 'terraform-aws-modules/vpc/aws')")
	flagSet.StringVar(&flags.toVersion, "to", "", "Desired version number")
	flagSet.Var(&flags.fromVersions, "from", "Optional: version to update from (can be specified multiple times, e.g., -from 3.0.0 -from '~> 3.0')")
	flagSet.Var(&flags.ignoreVersions, "ignore-version", "Optional: version(s) to skip (can be specified multiple times, e.g., -ignore-version 3.0.0 -ignore-version '~> 3.0')")
	flagSet.StringVar(&flags.ignoreModules, "ignore-modules", "", "Optional: comma-separated list of module names or patterns to ignore; a '<branch>/<module>' pattern requires -branch (e.g., 'vpc,legacy-*,release/*/vpc')")
	flagSet.StringVar(&flags.branch, "branch", "", "Optional: current branch name, required by branch-scoped ignore patterns (e.g., 'release/2026-09')")
	flagSet.StringVar(&flags.configFile, "config", "", "Path to YAML config file with multiple module updates")
	flagSet.StringVar(&flags.validationConfigFile, "validate-config", "", "Validate a YAML config file without updating Terraform files")
	flagSet.BoolVar(&flags.forceAdd, "force-add", false, "Add a missing version attribute to registry modules (default: skip with warning)")
	flagSet.BoolVar(&flags.dryRun, "dry-run", false, "Show what changes would be made without actually modifying files")
	flagSet.BoolVar(&flags.check, "check", false, "Exit 2 when updates are required without modifying files")
	flagSet.BoolVar(&flags.verbose, "verbose", false, "Show verbose output including skipped modules")
	flagSet.BoolVar(&flags.showVersion, "version", false, "Print version information and exit")
	flagSet.StringVar(&flags.output, "output", "text", "Output format: 'text' (default) or 'md' (Markdown)")
	flagSet.StringVar(&flags.terraformVersion, "terraform-version", "", "Update Terraform required_version in terraform blocks")
	flagSet.StringVar(&flags.providerName, "provider", "", "Provider name to update (e.g., 'aws', 'azurerm')")
	flagSet.StringVar(&flags.reportFile, "report-file", "", "Write exact updated Terraform, module, and provider block counts as JSON")
	flagSet.StringVar(&flags.auditFile, "audit-file", "", "Write each configured version value's current and expected version as JSON without changing files (config mode)")
	if err := flagSet.Parse(os.Args[1:]); err != nil {
		if stderrors.Is(err, flag.ErrHelp) {
			flagSet.SetOutput(usageOutput)
			if _, writeErr := fmt.Fprintf(usageOutput, "Usage of %s:\n", os.Args[0]); writeErr != nil {
				fatalf("Error writing help: %v", writeErr)
				return flags
			}
			flagSet.PrintDefaults()
			exitFunc(0)
			return flags
		}
		fatalf("Error: %v", err)
		return flags
	}
	flagSet.SetOutput(usageOutput)
	if flagSet.NArg() > 0 {
		fatalf("Error: unexpected positional argument(s): %s", strings.Join(flagSet.Args(), " "))
		return flags
	}

	// Validate output format
	if flags.output != "text" && flags.output != "md" {
		fatalf("Error: Invalid output format '%s'. Must be 'text' or 'md'", flags.output)
	}

	flags.branch = strings.TrimSpace(flags.branch)
	// Both of these name no branch, so every branch-scoped ignore pattern would be dropped
	// silently. 'git rev-parse --abbrev-ref HEAD' prints HEAD on a detached checkout, and
	// GITHUB_REF holds a full ref such as 'refs/heads/main'. Git permits a branch name that
	// starts with 'refs/', but a real branch is not realistically named that way.
	if flags.branch == "HEAD" {
		fatalf("Error: -branch must be a branch name, not 'HEAD'. Use 'git branch --show-current', which is empty on a detached checkout")
	}
	if strings.HasPrefix(flags.branch, "refs/") {
		fatalf("Error: -branch must be a branch name, not the ref '%s'. Use 'git branch --show-current' rather than a full ref such as GITHUB_REF", flags.branch)
	}

	return flags
}

// loadModuleUpdates loads module updates for single module CLI mode
func loadModuleUpdates(flags *cliFlags) []ModuleUpdate {
	// Single module mode - validate required flags
	if flags.pattern == "" || flags.moduleSource == "" || flags.toVersion == "" {
		fmt.Println("Usage:")
		fmt.Println("  Single module:  tf-version-bump -pattern <glob> -module <source> -to <version> [-from <version>]... [-ignore-version <version>]... [-ignore-modules <patterns>] [-branch <name>]")
		fmt.Println("  Config file:    tf-version-bump -pattern <glob> -config <config-file>")
		flag.PrintDefaults()
		exitFunc(1)
	}

	// Parse ignore patterns from comma-separated list
	var ignorePatterns []string
	if flags.ignoreModules != "" {
		for _, p := range strings.Split(flags.ignoreModules, ",") {
			if trimmed := strings.TrimSpace(p); trimmed != "" {
				ignorePatterns = append(ignorePatterns, trimmed)
			}
		}
	}

	updates := []ModuleUpdate{
		{Source: flags.moduleSource, Version: flags.toVersion, From: FromVersions(flags.fromVersions), IgnoreVersions: FromVersions(flags.ignoreVersions), IgnoreModules: ignorePatterns},
	}
	if err := resolveBranchIgnoreModules(updates, flags.branch); err != nil {
		fatalf("Error: %v", err)
		return nil
	}

	return updates
}

// resolveBranchIgnoreModules records, for each entry, the ignore_modules patterns that apply to
// branch. A branch-scoped pattern cannot be evaluated without a branch, so it is an error rather
// than a silent no-op that would bump a module the configuration excludes.
func resolveBranchIgnoreModules(updates []ModuleUpdate, branch string) error {
	for i := range updates {
		if len(updates[i].IgnoreModules) == 0 {
			continue
		}

		resolved := make([]string, 0, len(updates[i].IgnoreModules))
		for _, entry := range updates[i].IgnoreModules {
			branchPattern, modulePattern, err := splitIgnoreModuleEntry(entry)
			switch {
			case err != nil:
				return err
			case branchPattern == "":
				resolved = append(resolved, modulePattern)
			case branch == "":
				return fmt.Errorf("ignore pattern '%s' is scoped to a branch, but -branch is missing or empty; a detached checkout has no current branch", entry)
			case matchPattern(branch, branchPattern):
				resolved = append(resolved, modulePattern)
			}
		}
		updates[i].resolvedIgnoreModules = resolved
	}

	return nil
}

// loadResolvedConfig is the single entry point for reading a config into an executable form. The
// update and audit paths share it so their module filtering cannot drift apart.
func loadResolvedConfig(configFile, branch string) (*Config, error) {
	config, err := loadConfig(configFile)
	if err != nil {
		//nolint:staticcheck // The capitalised prefix is user-facing CLI output.
		return nil, fmt.Errorf("Error loading config file: %w", err)
	}
	if err := resolveBranchIgnoreModules(config.Modules, branch); err != nil {
		//nolint:staticcheck // The capitalised prefix is user-facing CLI output.
		return nil, fmt.Errorf("Error: %w", err)
	}
	return config, nil
}

// processFiles applies the module updates to every matching file in order, parsing each file once so
// an update meets the changes earlier updates made to it, in a dry run as in a real run. A file that
// cannot be read or parsed counts one error per update; each failed write counts one error, and the
// file is read again for the updates after it, and a file whose write kept its backup refuses that read.
func processFiles(files []string, updates []ModuleUpdate, flags *cliFlags) (totalUpdates, totalSkips, totalErrors int) {
	for _, file := range files {
		parsed, readErr := readTerraformFile(file)
		// Entries for one source are applied to the same file in turn, so one unpinned module is
		// skipped once per entry. The count speaks for modules, so the blocks are unioned.
		skippedBlocks := make(map[int]struct{})
		// Index rather than copy: gocritic's rangeValCopy rejects ranging over ModuleUpdate by value.
		for i := range updates {
			update := &updates[i]
			if readErr != nil {
				log.Printf("Error processing %s: %v", file, readErr)
				totalErrors++
				continue
			}
			updated, changedBlocks, blocksSkipped, err := applyModuleVersion(parsed, update.Source, update.Version, update.From, update.IgnoreVersions, update.resolvedIgnoreModules, flags.forceAdd, flags.dryRun, flags.verbose, flags.output)
			for _, blockIndex := range blocksSkipped {
				skippedBlocks[blockIndex] = struct{}{}
			}
			if err != nil {
				log.Printf("Error processing %s: %v", file, err)
				totalErrors++
				// Read the file again rather than keep the unsaved change: a restored file gives later
				// updates its original content, and a file whose backup was kept is refused.
				parsed, readErr = readTerraformFile(file)
				continue
			}
			if updated {
				if report := flags.reportRecorder(); report != nil && !flags.dryRun && len(changedBlocks) > 0 {
					report.recordModuleBlocks(file, changedBlocks)
				}
				prefix := "✓"
				action := "Updated"
				if flags.dryRun {
					prefix = "→"
					action = "Would update"
				}
				if len(update.From) > 0 {
					fmt.Printf("%s %s module source %s from version(s) %v to %s in %s\n", prefix, action, quote(update.Source, flags.output), update.From, quote(update.Version, flags.output), file)
				} else {
					fmt.Printf("%s %s module source %s to version %s in %s\n", prefix, action, quote(update.Source, flags.output), quote(update.Version, flags.output), file)
				}
				totalUpdates++
			}
		}
		totalSkips += len(skippedBlocks)
	}
	return totalUpdates, totalSkips, totalErrors
}

// failureNote reports the updates that failed, so a summary of what succeeded is never mistaken
// for the whole story of the run. Every counted failure is logged where it happens, so the count
// is also the number of diagnostics; it names stderr because the summary is on stdout, and a
// redirected stdout would otherwise end with a pointer to errors it does not contain.
func failureNote(errorCount int) string {
	if errorCount == 0 {
		return ""
	}
	return fmt.Sprintf("%d update(s) failed; see the errors on stderr\n", errorCount)
}

// skipNote reports the modules the run left unpinned, so a run that declined to act on a block
// it recognised does not read like a run with nothing to do. Every skip it counts is warned
// about, which is why it names the warnings rather than repeating them, but not every warned
// skip counts: a local module can never carry a version, so nothing is left outstanding.
func skipNote(skipCount int, kind string) string {
	if skipCount == 0 {
		return ""
	}
	return fmt.Sprintf("%d %s(s) skipped; see the warnings on stderr\n", skipCount, kind)
}

// printRunSummary prints one run's summary line followed by its failures. A run that updated
// nothing reports why instead of the line, which would otherwise claim a clean zero it cannot
// vouch for: a mistyped source, a glob over the wrong tree and an already-current file all
// counted as a success. It names every cause it cannot tell apart, including the skips the count
// below leaves out, so it never denies a skip the run has just printed. It promises no tool that
// answers "which", because -audit-file needs a config and -verbose lists only filtered modules.
func printRunSummary(line string, totalUpdates, errorCount int, skipped string, dryRun bool) {
	fmt.Println()
	switch {
	case totalUpdates > 0:
		fmt.Println(line)
	case errorCount > 0:
		// Nothing was updated and something failed, so the failures below are the whole summary:
		// a nothing-to-do line would read as a clean result. A skip does not suppress it, because
		// the line names skipping as one of the causes and the note then quantifies it.
	case dryRun:
		fmt.Println("No updates would be performed. Nothing matched, or every match was already at the target version or skipped.")
	default:
		fmt.Println("No updates were performed. Nothing matched, or every match was already at the target version or skipped.")
	}
	fmt.Print(failureNote(errorCount))
	fmt.Print(skipped)
}

// printSummary prints the final summary of updates. A direct run carries one module operation,
// so the count is always a count of files.
func printSummary(totalUpdates, errorCount, skipCount int, dryRun bool) {
	line := fmt.Sprintf("Successfully updated %d file(s)", totalUpdates)
	if dryRun {
		line = fmt.Sprintf("Dry run: would update %d file(s)", totalUpdates)
	}
	printRunSummary(line, totalUpdates, errorCount, skipNote(skipCount, "module"), dryRun)
}

func main() {
	flags := parseFlags()

	// Handle version flag
	if flags.showVersion {
		fmt.Printf("tf-version-bump %s\n", version)
		fmt.Printf("  commit: %s\n", commit)
		fmt.Printf("  built:  %s\n", date)
		exitFunc(0)
	}

	// Validate operation modes
	validateOperationModes(flags)
	if flags.validationConfigFile != "" {
		if err := validateConfigFile(flags.validationConfigFile); err != nil {
			fatalf("Error validating config file: %v", err)
		}
		fmt.Printf("Config '%s' is valid\n", flags.validationConfigFile)
		exitFunc(0)
	}
	if flags.check {
		flags.dryRun = true
	}

	// Find and validate matching files
	files := findMatchingFiles(flags)
	validateRequiredOperationFlags(flags)

	if flags.auditFile != "" {
		if err := runAuditMode(files, flags); err != nil {
			fatalf("%v", err)
		}
		return
	}

	totalUpdates, err := runUpdateMode(files, flags)
	if err != nil {
		fatalf("%v", err)
	}
	if flags.check && totalUpdates > 0 {
		exitFunc(2)
	}
}

// commandInputFiles lists every file the command reads: the selected Terraform files and, in
// config mode, the config. An output destination must not overwrite any of them.
func commandInputFiles(files []string, configFile string) []string {
	if configFile == "" {
		return files
	}
	return append(append([]string(nil), files...), configFile)
}

// runUpdateMode applies the selected updates and publishes any requested update report,
// returning the update-operation total that check mode turns into its exit status.
func runUpdateMode(files []string, flags *cliFlags) (int, error) {
	inputFiles := commandInputFiles(files, flags.configFile)
	preparedReport, err := prepareJSONOutput(updateReportOutput, flags.reportFile, inputFiles)
	if err != nil {
		return 0, err
	}

	var totalUpdates int
	if flags.configFile != "" {
		totalUpdates, err = runConfigFileMode(files, flags)
	} else {
		totalUpdates, err = runCLIMode(files, flags)
	}
	if err == nil && preparedReport != nil {
		flags.report.SchemaVersion = 2
		if publishErr := preparedReport.publish(&flags.report); publishErr != nil {
			err = fmt.Errorf("Error writing update report: %v", publishErr) //nolint:staticcheck // User-facing CLI diagnostic.
		}
	}
	if err == nil {
		return totalUpdates, nil
	}
	if preparedReport != nil {
		if discardErr := preparedReport.discard(); discardErr != nil {
			err = fmt.Errorf("%w; failed to discard prepared report: %v", err, discardErr)
		}
		// A report describes the tree it was written from. Only a run that changed that tree and
		// then failed leaves one describing a tree that no longer exists, so only such a run takes
		// it away: a run refused for its config, a run whose every file failed and a dry run all
		// leave the tree, and the report, exactly as they found them. A file a write left
		// untrusted counts as changed even though no update is counted for it, because it holds
		// neither version for certain. The publish failure reaches here too, which is the case
		// most certain to need it — the files changed and the counts describing them never
		// landed.
		if (totalUpdates > 0 && !flags.dryRun) || anyUntrusted() {
			if removeErr := preparedReport.removeDestination(); removeErr != nil {
				err = fmt.Errorf("%w; failed to remove the stale report: %v", err, removeErr)
			}
		}
	}
	return totalUpdates, err
}

func validateRequiredOperationFlags(flags *cliFlags) {
	if flags.moduleSource != "" {
		_ = loadModuleUpdates(flags)
	}
	if flags.providerName != "" && flags.toVersion == "" {
		fatalf("Error: -to flag is required when using -provider")
	}
}

// jsonOutput describes a JSON document the command writes through a temporary file once its
// work succeeds, and how diagnostics name it.
type jsonOutput struct {
	fileLabel     string // the destination, as in "report file must not overwrite input file"
	documentLabel string // the document, as in "Error preparing update report"
	tempPattern   string
}

var (
	updateReportOutput = jsonOutput{fileLabel: "report file", documentLabel: "update report", tempPattern: ".tf-version-bump-report-*"}
	auditOutput        = jsonOutput{fileLabel: "audit file", documentLabel: "audit", tempPattern: ".tf-version-bump-audit-*"}
)

func prepareJSONOutput(output jsonOutput, destination string, inputFiles []string) (*preparedReportFile, error) {
	if destination == "" {
		return nil, nil
	}
	if err := validateOutputDoesNotOverwriteInput(output, destination, inputFiles); err != nil {
		return nil, err
	}

	file, err := os.CreateTemp(filepath.Dir(destination), output.tempPattern)
	if err != nil {
		return nil, fmt.Errorf("Error preparing %s: %w", output.documentLabel, err) //nolint:staticcheck // User-facing CLI diagnostic.
	}
	return &preparedReportFile{destination: destination, file: file}, nil
}

func (prepared *preparedReportFile) publish(document any) error {
	var data bytes.Buffer
	encoder := json.NewEncoder(&data)
	// encoding/json writes <, > and & as Unicode escapes by default, which would make
	// constraints such as ">= 1.5" unreadable in the audit.
	encoder.SetEscapeHTML(false)
	encoder.SetIndent("", "  ")
	if err := encoder.Encode(document); err != nil {
		_ = prepared.discard()
		return fmt.Errorf("create report: %w", err)
	}
	if _, err := prepared.file.Write(data.Bytes()); err != nil {
		_ = prepared.discard()
		return err
	}
	if err := prepared.file.Sync(); err != nil {
		_ = prepared.discard()
		return err
	}
	temporaryName := prepared.file.Name()
	// Closing consumes the handle whether or not it succeeds, so the caller's discard must not
	// close it again and report a failure the run did not have.
	closeErr := prepared.file.Close()
	prepared.file = nil
	if closeErr != nil {
		_ = os.Remove(temporaryName)
		return closeErr
	}
	if err := renameReportFile(temporaryName, prepared.destination); err != nil {
		_ = os.Remove(temporaryName)
		return err
	}
	return nil
}

// removeDestination deletes a report an earlier run left at the destination. Its caller decides
// when that is right: only a failed run that changed files leaves a report describing a tree which
// no longer exists, where a consumer reading it without checking the exit status would act on
// counts for another run. Audit mode never removes its own destination, for the same reason a run
// that changed nothing does not: a failed audit changes nothing on disk, so the previous audit is
// still a true snapshot.
func (prepared *preparedReportFile) removeDestination() error {
	if prepared == nil {
		return nil
	}
	if err := removeReportFile(prepared.destination); err != nil && !stderrors.Is(err, fs.ErrNotExist) {
		return err
	}
	return nil
}

func (prepared *preparedReportFile) discard() error {
	if prepared == nil || prepared.file == nil {
		return nil
	}
	temporaryName := prepared.file.Name()
	closeErr := prepared.file.Close()
	prepared.file = nil
	removeErr := os.Remove(temporaryName)
	if closeErr != nil {
		return closeErr
	}
	return removeErr
}

func validateOutputDoesNotOverwriteInput(output jsonOutput, destination string, inputFiles []string) error {
	if destination == "" {
		return nil
	}

	destinationPath, err := filepath.Abs(destination)
	if err != nil {
		return fmt.Errorf("Error resolving %s: %w", output.fileLabel, err) //nolint:staticcheck // User-facing CLI diagnostic.
	}
	destinationInfo, destinationStatErr := os.Stat(destinationPath)
	if destinationStatErr != nil && !os.IsNotExist(destinationStatErr) {
		return fmt.Errorf("Error inspecting %s: %w", output.fileLabel, destinationStatErr) //nolint:staticcheck // User-facing CLI diagnostic.
	}
	if destinationStatErr == nil && destinationInfo.IsDir() {
		return fmt.Errorf("Error preparing %s: destination is a directory: %s", output.documentLabel, destination) //nolint:staticcheck // User-facing CLI diagnostic.
	}

	for _, inputFile := range inputFiles {
		inputPath, absErr := filepath.Abs(inputFile)
		if absErr != nil {
			return fmt.Errorf("Error resolving input file %s: %w", inputFile, absErr) //nolint:staticcheck // User-facing CLI diagnostic.
		}
		if filepath.Clean(destinationPath) == filepath.Clean(inputPath) {
			return fmt.Errorf("Error: %s must not overwrite input file: %s", output.fileLabel, destination) //nolint:staticcheck // User-facing CLI diagnostic.
		}
		if destinationStatErr != nil {
			continue
		}
		inputInfo, inputStatErr := os.Stat(inputPath)
		if inputStatErr != nil {
			return fmt.Errorf("Error inspecting input file %s: %w", inputFile, inputStatErr) //nolint:staticcheck // User-facing CLI diagnostic.
		}
		if os.SameFile(destinationInfo, inputInfo) {
			return fmt.Errorf("Error: %s must not overwrite input file: %s", output.fileLabel, destination) //nolint:staticcheck // User-facing CLI diagnostic.
		}
	}

	return nil
}

// validateOperationModes validates that the CLI flags are properly set
func validateOperationModes(flags *cliFlags) {
	if flags.validationConfigFile != "" {
		if configValidationHasConflicts(flags) {
			fatalf("Error: Cannot use -validate-config with update or report flags")
		}
		return
	}
	if flags.auditFile != "" {
		validateAuditMode(flags)
	}
	if flags.check && flags.dryRun {
		fatalf("Error: Cannot use -check with -dry-run")
	}
	if flags.check && flags.reportFile != "" {
		fatalf("Error: Cannot use -check with -report-file")
	}

	// Config file mode is exclusive with all other CLI flags
	if flags.configFile != "" {
		validateConfigUpdateMode(flags)
		return
	}

	// CLI mode - validate that at least one operation is specified
	modesSet := 0
	if flags.moduleSource != "" {
		modesSet++
	}
	if flags.terraformVersion != "" {
		modesSet++
	}
	if flags.providerName != "" {
		modesSet++
	}

	if modesSet == 0 {
		fmt.Println("Usage:")
		fmt.Println("  Module update:     tf-version-bump -pattern <glob> -module <source> -to <version>")
		fmt.Println("  Config file:       tf-version-bump -pattern <glob> -config <config-file>")
		fmt.Println("  Config validation: tf-version-bump -validate-config <config-file>")
		fmt.Println("  Terraform version: tf-version-bump -pattern <glob> -terraform-version <version>")
		fmt.Println("  Provider version:  tf-version-bump -pattern <glob> -provider <name> -to <version>")
		flag.PrintDefaults()
		exitFunc(1)
	}

	if modesSet > 1 {
		fatalf("Error: Cannot use -module, -terraform-version, and -provider flags together. Choose one operation mode or use a config file.")
	}
}

func validateConfigUpdateMode(flags *cliFlags) {
	if flags.moduleSource != "" || flags.terraformVersion != "" || flags.providerName != "" ||
		flags.toVersion != "" || len(flags.fromVersions) > 0 || len(flags.ignoreVersions) > 0 || flags.ignoreModules != "" {
		fatalf("Error: Cannot use -config with other operation flags (-module, -to, -terraform-version, -provider, -from, -ignore-version, -ignore-modules)")
	}
}

// validateAuditMode keeps -audit-file read-only: it compares files with a config and never
// combines with flags that preview, check, report or add versions.
func validateAuditMode(flags *cliFlags) {
	if flags.configFile == "" {
		fatalf("Error: -audit-file requires -config")
	}
	if flags.dryRun || flags.check || flags.reportFile != "" || flags.forceAdd {
		fatalf("Error: Cannot use -audit-file with -dry-run, -check, -report-file or -force-add")
	}
}

// configValidationHasConflicts reports whether any update or report flag accompanies
// -validate-config, which validates a config on its own. It is split in two so neither half
// exceeds the cyclomatic limit as flags are added.
func configValidationHasConflicts(flags *cliFlags) bool {
	return configValidationHasOperationFlags(flags) || configValidationHasBehaviourFlags(flags)
}

// configValidationHasOperationFlags covers the flags naming what to update and where to write.
func configValidationHasOperationFlags(flags *cliFlags) bool {
	return flags.pattern != "" || flags.configFile != "" || flags.moduleSource != "" ||
		flags.toVersion != "" || flags.terraformVersion != "" || flags.providerName != "" ||
		flags.reportFile != "" || flags.auditFile != ""
}

// configValidationHasBehaviourFlags covers the filters and switches that change how an update or audit runs.
func configValidationHasBehaviourFlags(flags *cliFlags) bool {
	return len(flags.fromVersions) > 0 || len(flags.ignoreVersions) > 0 || flags.ignoreModules != "" ||
		flags.branch != "" || flags.forceAdd || flags.dryRun || flags.check || flags.verbose
}

// findMatchingFiles finds all files matching the pattern
func findMatchingFiles(flags *cliFlags) []string {
	if flags.pattern == "" {
		fatalf("Error: -pattern flag is required")
	}

	// doublestar rather than filepath.Glob: it supports '**', which spans zero or more
	// directories. filepath.Glob treats '**' as a plain '*', silently matching only one
	// level deep.
	//
	// The filtered filesystem prevents wildcards from walking into dot-directories, so
	// '**/*.tf' skips tool-managed .terraform and .git trees without excluding dotfiles.
	// Naming a dot-directory explicitly places it in the non-glob base path, so it remains
	// reachable.
	//   - WithNoFollow: don't traverse directory symlinks, which would otherwise match the
	//     same physical file via both its real path and the link.
	//   - WithFilesOnly: '**' matches directories as readily as files; we only want files.
	pattern := filepath.ToSlash(filepath.Clean(flags.pattern))
	base, globPattern := doublestar.SplitPattern(pattern)
	fileSystem := os.DirFS(base)
	if readDirFS, ok := fileSystem.(fs.ReadDirFS); ok {
		fileSystem = visibleDirFS{ReadDirFS: readDirFS}
	}

	matches, err := doublestar.Glob(
		fileSystem,
		globPattern,
		doublestar.WithNoFollow(),
		doublestar.WithFilesOnly(),
	)
	if err != nil {
		fatalf("Error matching pattern: %v", err)
	}

	files := make([]string, 0, len(matches))
	for _, match := range matches {
		filename := filepath.Join(base, filepath.FromSlash(match))
		info, lstatErr := os.Lstat(filename)
		if lstatErr == nil && info.Mode()&os.ModeSymlink != 0 {
			target, statErr := os.Stat(filename)
			if statErr == nil && target.IsDir() {
				continue
			}
		}
		files = append(files, filename)
	}

	// doublestar walks depth-first, so results come back in traversal order rather than
	// sorted. File order is user-visible in the per-file output.
	slices.Sort(files)

	if len(files) == 0 {
		fatalf("No files matched pattern: %s", flags.pattern)
	}

	fmt.Printf("Found %d file(s) matching pattern %s\n", len(files), quote(flags.pattern, flags.output))

	if flags.check {
		fmt.Println("Running in check mode - no files will be modified")
	} else if flags.dryRun {
		fmt.Println("Running in dry-run mode - no files will be modified")
	}

	return files
}

// runConfigFileMode handles config file mode operations.
func runConfigFileMode(files []string, flags *cliFlags) (int, error) {
	config, err := loadResolvedConfig(flags.configFile, flags.branch)
	if err != nil {
		return 0, err
	}
	// -validate-config rejects a config that asks for nothing, so an update run does too: a file
	// truncated by a bad merge would otherwise be a cheerful no-op. The refusal lives here rather
	// than in the loader, which audit mode shares and which must keep reporting such a config.
	if config.declaresNoUpdates() {
		return 0, fmt.Errorf("Error: %w", errConfigDeclaresNoUpdates) //nolint:staticcheck // User-facing CLI diagnostic.
	}

	var terraformUpdates, terraformErrors, providerUpdates, providerSkips, providerErrors, moduleUpdates, moduleSkips, moduleErrors int

	// Process terraform version if specified
	if config.TerraformVersion != "" {
		terraformUpdates, terraformErrors = processTerraformVersion(files, config.TerraformVersion, flags.dryRun, flags.output, flags.reportRecorder())
	}

	// Process provider updates if specified
	for _, provider := range config.Providers {
		count, skips, updateErrors := processProviderVersion(files, provider.Name, provider.Version, flags.dryRun, flags.output, flags.reportRecorder())
		providerUpdates += count
		providerSkips += skips
		providerErrors += updateErrors
	}

	// Process module updates if specified
	if len(config.Modules) > 0 {
		moduleUpdates, moduleSkips, moduleErrors = processFiles(files, config.Modules, flags)
	}

	// Print summary
	outcome := configOutcome{
		terraformUpdates: terraformUpdates, terraformErrors: terraformErrors,
		providerUpdates: providerUpdates, providerErrors: providerErrors,
		moduleUpdates: moduleUpdates, moduleErrors: moduleErrors,
		moduleSkips: moduleSkips, providerSkips: providerSkips,
	}
	printConfigSummary(outcome, flags.dryRun)
	if outcome.onlyModuleErrors() {
		return outcome.updates(), fmt.Errorf("Error: %d module update error(s)", outcome.moduleErrors) //nolint:staticcheck // User-facing CLI diagnostic.
	}
	if outcome.errors() > 0 {
		return outcome.updates(), fmt.Errorf("Error: %d update error(s)", outcome.errors()) //nolint:staticcheck // User-facing CLI diagnostic.
	}
	return outcome.updates(), nil
}

// runCLIMode handles CLI mode operations
func runCLIMode(files []string, flags *cliFlags) (int, error) {
	var totalUpdates int
	var updates []ModuleUpdate

	switch {
	case flags.terraformVersion != "":
		var totalErrors int
		totalUpdates, totalErrors = processTerraformVersion(files, flags.terraformVersion, flags.dryRun, flags.output, flags.reportRecorder())
		printTerraformSummary(totalUpdates, totalErrors, flags.dryRun)
		if totalErrors > 0 {
			return totalUpdates, fmt.Errorf("Error: %d Terraform version update error(s)", totalErrors) //nolint:staticcheck // User-facing CLI diagnostic.
		}
		return totalUpdates, nil
	case flags.providerName != "":
		if flags.toVersion == "" {
			fatalf("Error: -to flag is required when using -provider")
		}
		var totalErrors int
		var totalSkips int
		totalUpdates, totalSkips, totalErrors = processProviderVersion(files, flags.providerName, flags.toVersion, flags.dryRun, flags.output, flags.reportRecorder())
		printProviderSummary(flags.providerName, totalUpdates, totalErrors, totalSkips, flags.dryRun, flags.output)
		if totalErrors > 0 {
			return totalUpdates, fmt.Errorf("Error: %d provider update error(s)", totalErrors) //nolint:staticcheck // User-facing CLI diagnostic.
		}
		return totalUpdates, nil
	default:
		updates = loadModuleUpdates(flags)
		var totalErrors int
		var totalSkips int
		totalUpdates, totalSkips, totalErrors = processFiles(files, updates, flags)
		printSummary(totalUpdates, totalErrors, totalSkips, flags.dryRun)
		if totalErrors > 0 {
			return totalUpdates, fmt.Errorf("Error: %d module update error(s)", totalErrors) //nolint:staticcheck // User-facing CLI diagnostic.
		}
		return totalUpdates, nil
	}
}

// configOutcome counts what one config-mode run applied, or in a dry run would apply, and what
// it failed on. The summary needs the failures as well as the updates: without them a run whose
// every update failed cannot be told from one with nothing to do, and the operator is sent to
// the config when the files were at fault.
type configOutcome struct {
	terraformUpdates, terraformErrors int
	providerUpdates, providerErrors   int
	moduleUpdates, moduleErrors       int
	moduleSkips, providerSkips        int
}

// updates counts the Terraform, provider and module version updates.
func (o configOutcome) updates() int {
	return o.terraformUpdates + o.providerUpdates + o.moduleUpdates
}

// errors counts the failed Terraform, provider and module update operations.
func (o configOutcome) errors() int {
	return o.terraformErrors + o.providerErrors + o.moduleErrors
}

// onlyModuleErrors reports whether every failure was a module update, which lets the run name the
// modules in its error rather than blame the whole config.
func (o configOutcome) onlyModuleErrors() bool {
	return o.terraformErrors == 0 && o.providerErrors == 0 && o.moduleErrors > 0
}

// printConfigSummary prints the summary for config file mode
func printConfigSummary(outcome configOutcome, dryRun bool) {
	switch {
	case outcome.updates() > 0:
		fmt.Println("\n" + strings.Repeat("=", 50))
		fmt.Println("Config File Update Summary")
		fmt.Println(strings.Repeat("=", 50))
		if outcome.terraformUpdates > 0 {
			if dryRun {
				fmt.Printf("Terraform version: would update %d file(s)\n", outcome.terraformUpdates)
			} else {
				fmt.Printf("Terraform version: %d file(s) updated\n", outcome.terraformUpdates)
			}
		}
		if outcome.providerUpdates > 0 {
			if dryRun {
				fmt.Printf("Providers: would apply %d update(s)\n", outcome.providerUpdates)
			} else {
				fmt.Printf("Providers: %d update(s) applied\n", outcome.providerUpdates)
			}
		}
		if outcome.moduleUpdates > 0 {
			if dryRun {
				fmt.Printf("Modules: would apply %d update(s)\n", outcome.moduleUpdates)
			} else {
				fmt.Printf("Modules: %d update(s) applied\n", outcome.moduleUpdates)
			}
		}
	case outcome.errors() > 0:
		// Nothing was updated and something failed, so the notes below are the whole summary: a
		// "nothing to do" message here would blame the config for a file-level fault. A skip does
		// not suppress it, because the message names skipping and the note then quantifies it.
		fmt.Println()
	case dryRun:
		fmt.Println("\nNo updates would be performed. Every configured update is already applied, skipped or matched nothing; use -audit-file to see which.")
	default:
		fmt.Println("\nNo updates were performed. Every configured update is already applied, skipped or matched nothing; use -audit-file to see which.")
	}
	fmt.Print(failureNote(outcome.errors()))
	fmt.Print(skipNote(outcome.providerSkips, "provider"))
	fmt.Print(skipNote(outcome.moduleSkips, "module"))
}

// printTerraformSummary prints the summary for terraform version updates
func printTerraformSummary(totalUpdates, errorCount int, dryRun bool) {
	// A Terraform required_version is set whether or not one is already there, so nothing is skipped.
	line := fmt.Sprintf("Successfully updated Terraform version in %d file(s)", totalUpdates)
	if dryRun {
		line = fmt.Sprintf("Dry run: would update Terraform version in %d file(s)", totalUpdates)
	}
	printRunSummary(line, totalUpdates, errorCount, "", dryRun)
}

// printProviderSummary prints the summary for provider version updates
func printProviderSummary(providerName string, totalUpdates, errorCount, skipCount int, dryRun bool, outputFormat string) {
	line := fmt.Sprintf("Successfully updated %s provider version in %d file(s)", quote(providerName, outputFormat), totalUpdates)
	if dryRun {
		line = fmt.Sprintf("Dry run: would update %s provider version in %d file(s)", quote(providerName, outputFormat), totalUpdates)
	}
	printRunSummary(line, totalUpdates, errorCount, skipNote(skipCount, "provider"), dryRun)
}

// containsVersion checks if a version string is present in a slice of versions.
// This helper function reduces code duplication when checking version filters.
//
// Parameters:
//   - versions: List of version strings to search through
//   - version: The version string to search for
//
// Returns:
//   - bool: true if the version is found in the list, false otherwise
func containsVersion(versions []string, version string) bool {
	for _, v := range versions {
		if v == version {
			return true
		}
	}
	return false
}

// processTerraformVersion updates the required_version in terraform blocks across all files
//
// Parameters:
//   - files: List of file paths to process
//   - version: Target Terraform version to set
//   - dryRun: If true, show what would be changed without modifying files
//   - outputFormat: Output format ("text" or "md")
//
// Returns:
//   - totalUpdates: Number of files that were updated (or would be updated in dry-run mode)
//   - totalErrors: Number of files that could not be processed
func processTerraformVersion(files []string, version string, dryRun bool, outputFormat string, report *updateReport) (totalUpdates, totalErrors int) {
	for _, file := range files {
		updated, changedBlocks, err := updateTerraformVersionWithCount(file, version, dryRun)
		if err != nil {
			log.Printf("Error processing %s: %v", file, err)
			totalErrors++
			continue
		}
		if updated {
			if report != nil && !dryRun && len(changedBlocks) > 0 {
				report.recordTerraformBlocks(file, changedBlocks)
			}
			prefix := "✓"
			action := "Updated"
			if dryRun {
				prefix = "→"
				action = "Would update"
			}
			fmt.Printf("%s %s Terraform required_version to %s in %s\n", prefix, action, quote(version, outputFormat), file)
			totalUpdates++
		}
	}
	return totalUpdates, totalErrors
}

// processProviderVersion updates provider versions in terraform required_providers blocks across all files
//
// Parameters:
//   - files: List of file paths to process
//   - providerName: Name of the provider to update (e.g., "aws", "azurerm")
//   - version: Target provider version to set
//   - dryRun: If true, show what would be changed without modifying files
//   - outputFormat: Output format ("text" or "md")
//
// Returns:
//   - totalUpdates: Number of files that were updated (or would be updated in dry-run mode)
//   - totalErrors: Number of files that could not be processed
func processProviderVersion(files []string, providerName, version string, dryRun bool, outputFormat string, report *updateReport) (totalUpdates, totalSkips, totalErrors int) {
	for _, file := range files {
		updated, changedBlocks, skipReasons, err := updateProviderVersionWithCount(file, providerName, version, dryRun)
		// An entry this run matched and would not change is warned about per entry, as a module is.
		for _, reason := range skipReasons {
			fmt.Fprintf(os.Stderr, "Warning: Provider %s in %s %s, skipping\n", quote(providerName, outputFormat), file, reason)
		}
		totalSkips += len(skipReasons)
		if err != nil {
			log.Printf("Error processing %s: %v", file, err)
			totalErrors++
			continue
		}
		if updated {
			if report != nil && !dryRun && len(changedBlocks) > 0 {
				report.recordProviderBlocks(changedBlocks)
			}
			prefix := "✓"
			action := "Updated"
			if dryRun {
				prefix = "→"
				action = "Would update"
			}
			fmt.Printf("%s %s provider %s to version %s in %s\n", prefix, action, quote(providerName, outputFormat), quote(version, outputFormat), file)
			totalUpdates++
		}
	}
	return totalUpdates, totalSkips, totalErrors
}

// updateTerraformVersion updates the required_version attribute in terraform blocks
//
// Parameters:
//   - filename: Path to the Terraform file to process
//   - version: Target Terraform version to set
//   - dryRun: If true, show what would be changed without modifying files
//
// Returns:
//   - bool: true if a terraform block was updated (or would be updated in dry-run mode)
//   - error: Any error encountered during file reading, parsing, or writing
func updateTerraformVersion(filename, version string, dryRun bool) (bool, error) {
	updated, _, err := updateTerraformVersionWithCount(filename, version, dryRun)
	return updated, err
}

// updateTerraformVersionWithCount updates required_version and identifies changed terraform blocks.
func updateTerraformVersionWithCount(filename, version string, dryRun bool) (updated bool, changedBlocks []int, err error) {
	file, err := readTerraformFile(filename)
	if err != nil {
		return false, nil, err
	}

	for blockIndex, block := range file.hcl.Body().Blocks() {
		if block.Type() != "terraform" {
			continue
		}
		currentVersion := block.Body().GetAttribute("required_version")
		if currentVersion != nil && attributeHasStringValue(currentVersion, version) {
			continue
		}
		// Update or add the required_version attribute
		block.Body().SetAttributeValue("required_version", cty.StringVal(version))
		updated = true
		changedBlocks = append(changedBlocks, blockIndex)
	}

	if updated && !dryRun {
		if err := file.write(); err != nil {
			return false, nil, err
		}
	}

	return updated, changedBlocks, nil
}

// updateProviderVersionWithCount updates a provider version and counts blocks whose values changed.
//
// This implementation supports both provider syntax styles:
//
// Block-based syntax:
//
//	required_providers { aws { source = "..." version = "..." } }
//
// Attribute-based syntax:
//
//	required_providers { aws = { source = "..." version = "..." } }
//
// Parameters:
//   - filename: Path to the Terraform file to process
//   - providerName: Name of the provider to update (e.g., "aws", "azurerm")
//   - version: Target provider version to set
//   - dryRun: If true, show what would be changed without modifying files
//
// Returns:
//   - updated: true if a provider operation was applied (or would be applied in dry-run mode)
//   - changedBlocks: locations of provider blocks whose version values differ from the target
//   - error: Any error encountered during file reading, parsing, or writing
func updateProviderVersionWithCount(filename, providerName, version string, dryRun bool) (updated bool, changedBlocks, skipReasons []string, err error) {
	file, err := readTerraformFile(filename)
	if err != nil {
		return false, nil, nil, err
	}

	for blockIndex, block := range file.hcl.Body().Blocks() {
		blockUpdated, blockChanges, blockSkipReasons := updateProviderTerraformBlockResult(block, providerName, version)
		updated = updated || blockUpdated
		skipReasons = append(skipReasons, blockSkipReasons...)
		for _, blockChange := range blockChanges {
			changedBlocks = append(changedBlocks, fmt.Sprintf("%d/%s", blockIndex, blockChange))
		}
	}

	if updated && !dryRun {
		if err := file.write(); err != nil {
			return false, nil, skipReasons, err
		}
	}

	return updated, changedBlocks, skipReasons, nil
}

func updateProviderTerraformBlockResult(block *hclwrite.Block, providerName, version string) (updated bool, changedBlocks, skipReasons []string) {
	if block.Type() != "terraform" {
		return false, nil, nil
	}

	updated = false
	changedBlocks = nil
	for nestedIndex, nestedBlock := range block.Body().Blocks() {
		if nestedBlock.Type() != "required_providers" {
			continue
		}
		blockSyntaxUpdated, blockSyntaxChanges := updateProviderBlockSyntaxResult(nestedBlock, providerName, version)
		if blockSyntaxUpdated {
			updated = true
			for _, blockSyntaxIndex := range blockSyntaxChanges {
				changedBlocks = append(changedBlocks, fmt.Sprintf("%d/block/%d", nestedIndex, blockSyntaxIndex))
			}
			continue
		}
		attributeUpdated, attributeChanged, skipReason := updateProviderAttributeVersionResult(nestedBlock, providerName, version)
		if skipReason != "" {
			skipReasons = append(skipReasons, skipReason)
		}
		if attributeUpdated {
			updated = true
			if attributeChanged {
				changedBlocks = append(changedBlocks, fmt.Sprintf("%d/attribute/%s", nestedIndex, providerName))
			}
		}
	}

	return updated, changedBlocks, skipReasons
}

func updateProviderBlockSyntaxResult(nestedBlock *hclwrite.Block, providerName, version string) (updated bool, changedBlocks []int) {
	updated = false
	changedBlocks = nil
	for providerIndex, providerBlock := range nestedBlock.Body().Blocks() {
		if providerBlock.Type() != providerName {
			continue
		}
		versionAttribute := providerBlock.Body().GetAttribute("version")
		if versionAttribute != nil && attributeHasStringValue(versionAttribute, version) {
			continue
		}
		changedBlocks = append(changedBlocks, providerIndex)
		providerBlock.Body().SetAttributeValue("version", cty.StringVal(version))
		updated = true
	}

	return updated, changedBlocks
}

// updateProviderAttributeVersion updates the version value within a provider attribute's object expression
// This handles the attribute-based syntax: aws = { source = "..." version = "..." }
// The third result describes an entry this run matched and would not change, in the words the
// warning reports, or is empty when there is nothing to report. Block syntax never reaches it,
// because a missing version there is simply set.
func updateProviderAttributeVersionResult(nestedBlock *hclwrite.Block, providerName, newVersion string) (updated, changed bool, skipReason string) {
	objExpr, expression, ok, present := providerAttributeObject(nestedBlock, providerName)
	if !ok {
		if !present {
			return false, false, ""
		}
		return false, false, "is a version string rather than an object or block, which updates do not change"
	}

	updatedExpression, hasVersion, changed := replaceProviderObjectVersion(objExpr, expression, newVersion)
	if !hasVersion {
		return false, false, "has no version argument and updates cannot add one"
	}
	if !changed {
		return false, false, ""
	}

	newAttribute := append([]byte(providerName+" = "), updatedExpression...)
	newExpr, diags := hclwrite.ParseConfig(newAttribute, "inline", hcl.Pos{Line: 1, Column: 1})
	if diags.HasErrors() {
		return false, false, ""
	}

	for _, newAttr := range newExpr.Body().Attributes() {
		nestedBlock.Body().SetAttributeRaw(providerName, newAttr.Expr().BuildTokens(nil))
		return true, changed, ""
	}

	return false, false, ""
}

// The last result separates an entry this run cannot change from one that is not there at all: a
// provider given as a bare version string is matched, and left at the version it names, because
// updates change the object and block forms only.
func providerAttributeObject(nestedBlock *hclwrite.Block, providerName string) (objExpr *hclsyntax.ObjectConsExpr, expression []byte, ok, present bool) {
	attr, exists := nestedBlock.Body().Attributes()[providerName]
	if !exists {
		return nil, nil, false, false
	}

	tokens := attr.Expr().BuildTokens(nil)
	expression = tokens.Bytes()
	expr, diags := hclsyntax.ParseExpression(expression, "inline", hcl.Pos{Line: 1, Column: 1})
	if diags.HasErrors() {
		return nil, nil, false, true
	}

	objExpr, ok = expr.(*hclsyntax.ObjectConsExpr)
	return objExpr, expression, ok, true
}

func replaceProviderObjectVersion(objExpr *hclsyntax.ObjectConsExpr, expression []byte, newVersion string) (updated []byte, hasVersion, changed bool) {
	updated = append([]byte(nil), expression...)
	hasVersion = false
	changed = false
	newValue := hclwrite.TokensForValue(cty.StringVal(newVersion)).Bytes()

	for index := len(objExpr.Items) - 1; index >= 0; index-- {
		item := objExpr.Items[index]
		keyName, ok := providerObjectItemKey(item)
		if !ok || keyName != "version" {
			continue
		}

		valueRange := item.ValueExpr.Range()
		if valueRange.Start.Byte < 0 || valueRange.End.Byte > len(expression) || valueRange.Start.Byte > valueRange.End.Byte {
			return nil, false, false
		}
		hasVersion = true
		if expressionHasStringValue(expression[valueRange.Start.Byte:valueRange.End.Byte], newVersion) {
			continue
		}

		next := make([]byte, 0, len(updated)-valueRange.End.Byte+valueRange.Start.Byte+len(newValue))
		next = append(next, updated[:valueRange.Start.Byte]...)
		next = append(next, newValue...)
		next = append(next, updated[valueRange.End.Byte:]...)
		updated = next
		changed = true
	}

	return updated, hasVersion, changed
}

// expressionHasStringValue reports whether expression evaluates to value as an update would write
// it. cty strings are NFC-normalised, so value is normalised the same way; otherwise a version
// written from a decomposed string would never read back as applied.
func expressionHasStringValue(expression []byte, value string) bool {
	expr, diags := hclsyntax.ParseExpression(expression, "inline", hcl.Pos{Line: 1, Column: 1})
	if diags.HasErrors() {
		return false
	}
	expressionValue, diags := expr.Value(&hcl.EvalContext{})
	return !diags.HasErrors() && expressionValue.IsKnown() && !expressionValue.IsNull() &&
		expressionValue.Type().Equals(cty.String) && expressionValue.Equals(cty.StringVal(value)).True()
}

func providerObjectItemKey(item hclsyntax.ObjectConsItem) (string, bool) {
	keyExpr, ok := item.KeyExpr.(*hclsyntax.ObjectConsKeyExpr)
	if !ok {
		return "", false
	}

	traversal, ok := keyExpr.Wrapped.(*hclsyntax.ScopeTraversalExpr)
	if !ok || len(traversal.Traversal) == 0 {
		return "", false
	}

	rootName, ok := traversal.Traversal[0].(hcl.TraverseRoot)
	if !ok {
		return "", false
	}

	return rootName.Name, true
}

// updateModuleVersionWithCount updates modules with the specified source and counts changed blocks.
//
// The function retains comments and other HCL structures, then normalises the changed file with
// hclwrite.Format.
// If a matching module doesn't have a version attribute:
//   - When forceAdd is false (default): a warning is printed and the module is skipped
//   - When forceAdd is true and the source is a registry module: a version attribute is added
//   - When forceAdd is true and the source is not a registry module: a warning is printed and the
//     module is skipped because Terraform does not permit version constraints for those sources
//
// All modules with the same source attribute will be updated to the same version.
// If fromVersions is specified, only modules with current version matching any in the list will be updated.
// If ignoreVersions is specified, modules with current version matching any in the list will be skipped.
// If ignorePatterns is specified, modules with names matching any pattern will be skipped.
//
// Parameters:
//   - filename: Path to the Terraform file to process
//   - moduleSource: The module source to match (e.g., "terraform-aws-modules/vpc/aws")
//   - version: The target version to set (e.g., "5.0.0")
//   - fromVersions: Optional: only update if current version matches any in this list (e.g., ["4.0.0", "~> 3.0"])
//   - ignoreVersions: Optional: skip update if current version matches any in this list (e.g., ["4.0.0", "~> 3.0"])
//   - ignorePatterns: Optional: list of module names or patterns to ignore (e.g., ["vpc", "legacy-*"])
//   - forceAdd: If true, add a version attribute to registry modules that don't have one
//   - dryRun: If true, show what would be changed without modifying files
//   - verbose: If true, print informational messages about skipped modules
//   - outputFormat: Output format ("text" or "md")
//
// Returns:
//   - updated: true if at least one module operation was applied (or would be applied in dry-run mode)
//   - changedBlocks: indexes of module blocks whose version values differ from the target
//   - skippedBlocks: indexes of module blocks left unpinned by a skip the run warns about
//   - error: Any error encountered during file reading, parsing, or writing
func updateModuleVersionWithCount(filename, moduleSource, version string, fromVersions, ignoreVersions, ignorePatterns []string, forceAdd, dryRun, verbose bool, outputFormat string) (updated bool, changedBlocks, skippedBlocks []int, err error) {
	file, err := readTerraformFile(filename)
	if err != nil {
		return false, nil, nil, err
	}
	return applyModuleVersion(file, moduleSource, version, fromVersions, ignoreVersions, ignorePatterns, forceAdd, dryRun, verbose, outputFormat)
}

// terraformFile is a Terraform file parsed once, with the identity the untrusted-file check compares.
type terraformFile struct {
	name string
	info os.FileInfo
	hcl  *hclwrite.File
}

// rewritableFile is an open Terraform file that a write replaces in place.
type rewritableFile interface {
	io.Reader
	io.WriterAt
	Truncate(size int64) error
	Sync() error
	Close() error
}

// backupFile holds a Terraform file's original bytes while the file is rewritten.
type backupFile interface {
	io.Writer
	Sync() error
	Close() error
	Name() string
}

// untrustedFile is a Terraform file whose failed write kept a backup, so its content cannot be trusted.
type untrustedFile struct {
	info   os.FileInfo
	backup string
}

var (
	untrustedMu    sync.Mutex
	untrustedFiles []untrustedFile // refused by readTerraformFile for the rest of the run
)

// anyUntrusted reports whether a write left a file whose content cannot be confirmed. Such a file
// was changed by this run, and no update is counted for it, so the update total alone cannot say
// whether the tree still matches a report an earlier run left behind.
func anyUntrusted() bool {
	untrustedMu.Lock()
	defer untrustedMu.Unlock()
	return len(untrustedFiles) > 0
}

func markUntrusted(info os.FileInfo, backup string) {
	untrustedMu.Lock()
	defer untrustedMu.Unlock()
	untrustedFiles = append(untrustedFiles, untrustedFile{info: info, backup: backup})
}

// untrustedBackup returns the backup holding an untrusted file's original bytes. It compares file
// identities, so the same file reached through a symlink or a hard link is found too.
func untrustedBackup(info os.FileInfo) (backup string, untrusted bool) {
	untrustedMu.Lock()
	defer untrustedMu.Unlock()
	for _, file := range untrustedFiles {
		if os.SameFile(info, file.info) {
			return file.backup, true
		}
	}
	return "", false
}

func readTerraformFile(filename string) (*terraformFile, error) {
	fileInfo, err := os.Stat(filename)
	if err != nil {
		return nil, fmt.Errorf("failed to stat file: %w", err)
	}
	if backup, untrusted := untrustedBackup(fileInfo); untrusted {
		return nil, fmt.Errorf("file left untrusted by an earlier failed write; original content is in %s", backup)
	}

	src, err := os.ReadFile(filename)
	if err != nil {
		return nil, fmt.Errorf("failed to read file: %w", err)
	}

	file, diags := hclwrite.ParseConfig(src, filename, hcl.Pos{Line: 1, Column: 1})
	if diags.HasErrors() {
		return nil, fmt.Errorf("failed to parse HCL: %s", diags.Error())
	}

	return &terraformFile{name: filename, info: fileInfo, hcl: file}, nil
}

// write formats the file and rewrites it in place, so its permission bits, owner and links are
// untouched. The original bytes are backed up first: a failed rewrite is undone and the backup
// removed, and when the file's state cannot be confirmed the backup is kept and the error names it.
func (file *terraformFile) write() error {
	handle, err := openFileForRewrite(file.name)
	if err != nil {
		return fmt.Errorf("failed to write file: %w", err)
	}
	original, err := io.ReadAll(handle)
	if err != nil {
		_ = handle.Close()
		return fmt.Errorf("failed to write file: %w", err)
	}
	backup, err := writeBackup(file.name, original)
	if err != nil {
		_ = handle.Close()
		return fmt.Errorf("failed to write file: cannot back up %s: %w", file.name, err)
	}
	outcome, err := rewriteContents(handle, original, hclwrite.Format(file.hcl.Bytes()))
	if err != nil {
		_ = handle.Close()
		if outcome == rewriteUncertain {
			return file.keepBackup(backup, err)
		}
		removeBackup(backup)
		return fmt.Errorf("failed to write file: %w", err)
	}
	// The rewrite is synced, but a failed close leaves its state unconfirmed. Restoring would mean
	// reopening the file, so, as gofmt does, the backup is kept instead.
	if err := handle.Close(); err != nil {
		return file.keepBackup(backup, err)
	}
	removeBackup(backup)
	return nil
}

// keepBackup reports a write whose file may not hold its original bytes, naming the backup that
// does, and marks the file untrusted so the rest of the run refuses it.
func (file *terraformFile) keepBackup(backup string, err error) error {
	markUntrusted(file.info, backup)
	return fmt.Errorf("failed to write file: %w; original content is in %s", err, backup)
}

// writeBackup copies a Terraform file's original bytes into the system temporary directory and
// returns the copy's path. A copy that fails part way is removed.
func writeBackup(name string, original []byte) (string, error) {
	backup, err := createBackupFile("tf-version-bump-backup-" + filepath.Base(name) + "-*")
	if err != nil {
		return "", err
	}
	path := backup.Name()
	_, err = backup.Write(original)
	if err == nil {
		err = backup.Sync()
	}
	if closeErr := backup.Close(); err == nil {
		err = closeErr
	}
	if err != nil {
		removeBackup(path)
		return "", err
	}
	return path, nil
}

// rewriteOutcome says what a rewrite left in the file, so a caller never has to read it back.
type rewriteOutcome int

const (
	// rewriteComplete means the file holds the new bytes.
	rewriteComplete rewriteOutcome = iota
	// rewriteUndone means the rewrite failed and the file holds its original bytes.
	rewriteUndone
	// rewriteUncertain means the rewrite failed and the file may hold neither version in full.
	rewriteUncertain
)

// rewriteContents replaces the file's bytes with formatted. When that fails it writes the original
// bytes back, unless nothing reached the file, and the outcome says which of the three cases happened.
func rewriteContents(file rewritableFile, original, formatted []byte) (rewriteOutcome, error) {
	written, err := file.WriteAt(formatted, 0)
	if err != nil && written == 0 {
		// Nothing reached the file, so it still holds its original bytes.
		return rewriteUndone, err
	}
	if err == nil {
		err = truncateAndSync(file, len(formatted))
	}
	if err == nil {
		return rewriteComplete, nil
	}
	if restoreErr := writeContents(file, original); restoreErr != nil {
		return rewriteUncertain, fmt.Errorf("%w; restoring the original also failed: %w", err, restoreErr)
	}
	return rewriteUndone, fmt.Errorf("%w; original content restored", err)
}

// writeContents writes data over the start of the file, cuts the file to its length and syncs it.
func writeContents(file rewritableFile, data []byte) error {
	if _, err := file.WriteAt(data, 0); err != nil {
		return err
	}
	return truncateAndSync(file, len(data))
}

func truncateAndSync(file rewritableFile, size int) error {
	if err := file.Truncate(int64(size)); err != nil {
		return err
	}
	return file.Sync()
}

// removeBackup deletes a backup that is no longer needed. The Terraform file holds the content it
// should by then, so a failure is only a warning.
func removeBackup(backup string) {
	if err := os.Remove(backup); err != nil {
		fmt.Fprintf(os.Stderr, "Warning: could not remove backup %s: %v\n", backup, err)
	}
}

// applyModuleVersion applies one module update to a parsed file, changing it in memory so a later
// update to the same file meets this one's result, and writes the file unless dryRun is set.
func applyModuleVersion(file *terraformFile, moduleSource, version string, fromVersions, ignoreVersions, ignorePatterns []string, forceAdd, dryRun, verbose bool, outputFormat string) (updated bool, changedBlocks, skippedBlocks []int, err error) {
	opts := moduleUpdateOptions{
		filename:       file.name,
		moduleSource:   moduleSource,
		version:        version,
		fromVersions:   fromVersions,
		ignoreVersions: ignoreVersions,
		ignorePatterns: ignorePatterns,
		forceAdd:       forceAdd,
		verbose:        verbose,
		outputFormat:   outputFormat,
	}

	for blockIndex, block := range file.hcl.Body().Blocks() {
		blockUpdated, blockChanged, blockSkipped := updateModuleBlockResult(block, &opts)
		if blockSkipped {
			skippedBlocks = append(skippedBlocks, blockIndex)
		}
		if blockUpdated {
			updated = true
			if blockChanged {
				changedBlocks = append(changedBlocks, blockIndex)
			}
		}
	}

	if updated && !dryRun {
		if err := file.write(); err != nil {
			return false, nil, skippedBlocks, err
		}
	}

	return updated, changedBlocks, skippedBlocks, nil
}

type moduleUpdateOptions struct {
	filename       string
	moduleSource   string
	version        string
	fromVersions   []string
	ignoreVersions []string
	ignorePatterns []string
	forceAdd       bool
	verbose        bool
	outputFormat   string
}

// The third result reports a skip that leaves the block unpinned or defeats an explicit
// -force-add, which the run counts. A module excluded by a filter, a local module and a module
// already at the target version were all skipped as asked, so they do not count.
func updateModuleBlockResult(block *hclwrite.Block, opts *moduleUpdateOptions) (updated, changed, skipped bool) {
	if block.Type() != "module" {
		return false, false, false
	}

	moduleName := moduleBlockName(block)
	sourceValue, ok := moduleSourceValue(block)
	if !ok || sourceValue != opts.moduleSource {
		return false, false, false
	}

	if isLocalModule(sourceValue) {
		fmt.Fprintf(os.Stderr, "Warning: Module %s in %s (source: %s) is a local module and cannot be version-bumped, skipping\n",
			quote(moduleName, opts.outputFormat), opts.filename, quote(opts.moduleSource, opts.outputFormat))
		return false, false, false
	}

	if shouldIgnoreModule(moduleName, opts.ignorePatterns) {
		if opts.verbose {
			fmt.Printf("  ⊗ Skipped module %s in %s (matches ignore pattern)\n", quote(moduleName, opts.outputFormat), opts.filename)
		}
		return false, false, false
	}

	versionAttr := block.Body().GetAttribute("version")
	if versionAttr == nil {
		if !opts.forceAdd {
			fmt.Fprintf(os.Stderr, "Warning: Module %s in %s (source: %s) has no version attribute, skipping\n",
				quote(moduleName, opts.outputFormat), opts.filename, quote(opts.moduleSource, opts.outputFormat))
			return false, false, true
		}
		if !isRegistryModule(sourceValue) {
			fmt.Fprintf(os.Stderr, "Warning: Module %s in %s (source: %s) is not a registry module and cannot use a version attribute, skipping\n",
				quote(moduleName, opts.outputFormat), opts.filename, quote(opts.moduleSource, opts.outputFormat))
			return false, false, true
		}
	} else {
		currentVersion := attributeStringValue(versionAttr)
		if shouldSkipModuleVersion(moduleName, currentVersion, opts) {
			return false, false, false
		}
		if attributeHasStringValue(versionAttr, opts.version) {
			return false, false, false
		}
		block.Body().SetAttributeValue("version", cty.StringVal(opts.version))
		return true, true, false
	}

	block.Body().SetAttributeValue("version", cty.StringVal(opts.version))
	return true, true, false
}

func moduleBlockName(block *hclwrite.Block) string {
	if len(block.Labels()) == 0 {
		return ""
	}
	return block.Labels()[0]
}

func moduleSourceValue(block *hclwrite.Block) (string, bool) {
	sourceAttr := block.Body().GetAttribute("source")
	if sourceAttr == nil {
		return "", false
	}
	return attributeStringValue(sourceAttr), true
}

func attributeStringValue(attr *hclwrite.Attribute) string {
	tokens := attr.Expr().BuildTokens(nil)
	return trimQuotes(strings.TrimSpace(string(tokens.Bytes())))
}

func attributeHasStringValue(attr *hclwrite.Attribute, value string) bool {
	return expressionHasStringValue(attr.Expr().BuildTokens(nil).Bytes(), value)
}

// moduleVersionFilter names the config filter that stops an update from currentVersion:
// "ignore_versions" when it lists the version, "from" when it is set and does not, or "" when
// neither applies. ignore_versions takes precedence over from.
func moduleVersionFilter(currentVersion string, ignoreVersions, fromVersions []string) string {
	if len(ignoreVersions) > 0 && containsVersion(ignoreVersions, currentVersion) {
		return "ignore_versions"
	}
	if len(fromVersions) > 0 && !containsVersion(fromVersions, currentVersion) {
		return "from"
	}
	return ""
}

func shouldSkipModuleVersion(moduleName, currentVersion string, opts *moduleUpdateOptions) bool {
	switch moduleVersionFilter(currentVersion, opts.ignoreVersions, opts.fromVersions) {
	case "ignore_versions":
		if opts.verbose {
			fmt.Printf("  ⊗ Skipped module %s in %s (current version %s matches 'ignore-version' filter %v)\n", quote(moduleName, opts.outputFormat), opts.filename, quote(currentVersion, opts.outputFormat), opts.ignoreVersions)
		}
		return true
	case "from":
		if opts.verbose {
			fmt.Printf("  ⊗ Skipped module %s in %s (current version %s does not match any 'from' filter %v)\n", quote(moduleName, opts.outputFormat), opts.filename, quote(currentVersion, opts.outputFormat), opts.fromVersions)
		}
		return true
	}
	return false
}

// isLocalModule checks if a module source is a local path.
// Local modules use relative or absolute paths instead of registry sources.
//
// Parameters:
//   - source: The module source to check
//
// Returns:
//   - bool: true if the source is a local path, false otherwise
//
// Examples:
//   - `./modules/vpc` returns true
//   - `../shared/modules` returns true
//   - `/absolute/path/module` returns true
//   - `terraform-aws-modules/vpc/aws` returns false
func isLocalModule(source string) bool {
	return strings.HasPrefix(source, "./") ||
		strings.HasPrefix(source, "../") ||
		strings.HasPrefix(source, "/")
}

func isRegistryModule(source string) bool {
	_, err := tfaddr.ParseModuleSource(source)
	return err == nil
}

// shouldIgnoreModule checks if a module name matches any of the ignore patterns.
// Patterns support wildcard matching using '*' for zero or more characters.
//
// Parameters:
//   - moduleName: The name of the module to check
//   - patterns: List of patterns to match against (e.g., ["vpc", "legacy-*", "*-test"])
//
// Returns:
//   - bool: true if the module name matches any pattern, false otherwise
//
// Examples:
//   - shouldIgnoreModule("vpc", ["vpc"]) returns true (exact match)
//   - shouldIgnoreModule("legacy-vpc", ["legacy-*"]) returns true (wildcard prefix)
//   - shouldIgnoreModule("vpc-test", ["*-test"]) returns true (wildcard suffix)
//   - shouldIgnoreModule("prod-vpc-test", ["*-vpc-*"]) returns true (wildcard both sides)
//   - shouldIgnoreModule("vpc", ["s3"]) returns false (no match)
func shouldIgnoreModule(moduleName string, patterns []string) bool {
	// Defensive: According to HCL/Terraform syntax, module blocks must have labels ("module" "name"),
	// so moduleName should never be empty in practice. This check handles malformed HCL or unexpected
	// parsing results. If moduleName is empty, do not ignore the module.
	if moduleName == "" {
		return false
	}

	if len(patterns) == 0 {
		return false
	}

	for _, pattern := range patterns {
		if matchPattern(moduleName, pattern) {
			return true
		}
	}
	return false
}

// matchPattern performs wildcard pattern matching.
// Supports '*' as a wildcard that matches zero or more characters.
//
// Matching behavior:
//   - Uses greedy matching for middle parts (finds first occurrence of each part in order)
//   - Consecutive wildcards (**, ***, etc.) are treated as a single wildcard
//   - For patterns with multiple wildcards and repeated literal parts (e.g., "a*c*c"),
//     the algorithm ensures all parts fit without overlapping by checking that middle
//     parts don't extend past where the suffix begins
//
// Parameters:
//   - name: The string to match
//   - pattern: The pattern to match against (may contain '*' wildcards)
//
// Returns:
//   - bool: true if the name matches the pattern, false otherwise
//
// Examples:
//   - matchPattern("vpc", "vpc") returns true (exact match)
//   - matchPattern("legacy-vpc", "legacy-*") returns true (wildcard suffix)
//   - matchPattern("vpc-test", "*-test") returns true (wildcard prefix)
//   - matchPattern("prod-vpc-test", "*-vpc-*") returns true (wildcard both sides)
//   - matchPattern("abc", "a**c") returns true (consecutive wildcards)
//   - matchPattern("acc", "a*c*c") returns true (repeated parts, wildcards match zero chars)
//   - matchPattern("vpc", "s3") returns false (no match)
func matchPattern(name, pattern string) bool {
	// If pattern has no wildcards, do exact match
	if !strings.Contains(pattern, "*") {
		return name == pattern
	}

	// Split pattern by '*' to get the literal parts
	parts := strings.Split(pattern, "*")

	if !patternBoundsMatch(name, parts) {
		return false
	}

	pos, ok := orderedMiddlePartsEnd(name, parts)
	return ok && suffixDoesNotOverlap(name, parts, pos)
}

func patternBoundsMatch(name string, parts []string) bool {
	first := parts[0]
	last := parts[len(parts)-1]

	if first != "" && !strings.HasPrefix(name, first) {
		return false
	}
	if last != "" && !strings.HasSuffix(name, last) {
		return false
	}

	return first == "" || last == "" || len(name) >= len(first)+len(last)
}

func orderedMiddlePartsEnd(name string, parts []string) (int, bool) {
	pos := 0
	for i, part := range parts {
		if part == "" {
			continue
		}
		if i == 0 {
			pos = len(part)
			continue
		}
		if i == len(parts)-1 {
			break
		}

		idx := strings.Index(name[pos:], part)
		if idx == -1 {
			return 0, false
		}
		pos += idx + len(part)
	}

	return pos, true
}

func suffixDoesNotOverlap(name string, parts []string, pos int) bool {
	last := parts[len(parts)-1]
	if last == "" {
		return true
	}

	return pos <= len(name)-len(last)
}

// trimQuotes removes surrounding single or double quotes from a string.
// If the string doesn't have matching quotes on both ends, it returns the original string.
//
// Parameters:
//   - s: The string to trim quotes from
//
// Returns:
//   - string: The string with quotes removed, or the original string if no matching quotes found
//
// Examples:
//   - `"hello"` returns `hello`
//   - `'hello'` returns `hello`
//   - `hello` returns `hello`
//   - `"hello'` returns `"hello'` (mismatched quotes)
func trimQuotes(s string) string {
	if len(s) >= 2 {
		if (s[0] == '"' && s[len(s)-1] == '"') || (s[0] == '\'' && s[len(s)-1] == '\'') {
			return s[1 : len(s)-1]
		}
	}
	return s
}