Add --sequential-helmfiles flag for optional sequential processing (#2350)

* Initial plan

* Fix helmfile.d parallel processing to respect alphabetical order

Changed multiple helmfile.d file processing from parallel to sequential
to match the documented behavior. Files are now processed in alphabetical
order as stated in the documentation, ensuring predictable deployment order.

This fixes issues where deployments would break because parallel processing
did not respect the intended ordering (e.g., databases before applications).

- Modified visitStatesWithContext to process files sequentially
- Removed unused processStateFileParallel function
- Updated test snapshots to reflect deterministic ordering

Co-authored-by: yxxhero <11087727+yxxhero@users.noreply.github.com>

* Add --sequential-helmfiles flag for opt-in sequential processing

Based on feedback, added a flag to control processing mode instead of
forcing sequential behavior. Parallel processing is now the default for
performance, with an opt-in --sequential-helmfiles flag for when order matters.

Changes:
- Added SequentialHelmfiles field to GlobalOptions and App
- Added --sequential-helmfiles CLI flag
- Modified visitStatesWithContext to check flag and choose parallel vs sequential
- Updated documentation to clarify parallel is default, sequential is opt-in
- Restored original parallel processing as default behavior

This gives users control over the behavior based on their needs.

Co-authored-by: yxxhero <11087727+yxxhero@users.noreply.github.com>

* Add documentation and improve code readability

- Added documentation to processStateFileParallel function
- Extracted shouldProcessInParallel variable for clarity
- All tests pass, security scan clean

Co-authored-by: yxxhero <11087727+yxxhero@users.noreply.github.com>

* Fix lint issue: remove trailing whitespace

Removed trailing whitespace from line 983 in pkg/app/app.go to fix
formatting lint error.

Co-authored-by: yxxhero <11087727+yxxhero@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: yxxhero <11087727+yxxhero@users.noreply.github.com>

pkg/app/app.go

@@ -38,6 +38,7 @@ type App struct {
 	EnforcePluginVerification       bool
 	HelmOCIPlainHTTP                bool
 	DisableKubeVersionAutoDetection bool
+	SequentialHelmfiles             bool
 
 	Logger      *zap.SugaredLogger
 	Kubeconfig  string
@@ -86,6 +87,7 @@ func New(conf ConfigProvider) *App {
 		DisableForceUpdate:         conf.DisableForceUpdate(),
 		EnforcePluginVerification:  conf.EnforcePluginVerification(),
 		HelmOCIPlainHTTP:           conf.HelmOCIPlainHTTP(),
+		SequentialHelmfiles:        conf.SequentialHelmfiles(),
 		Logger:                     conf.Logger(),
 		Kubeconfig:                 conf.Kubeconfig(),
 		Env:                        conf.Env(),
@@ -855,6 +857,9 @@ func (a *App) visitStates(fileOrDir string, defOpts LoadOpts, converge func(*sta
 	return a.visitStatesWithContext(fileOrDir, defOpts, converge, nil)
 }
 
+// processStateFileParallel processes a single helmfile state file in a goroutine.
+// It is used for parallel processing of multiple helmfile.d files.
+// Results are communicated via errChan (errors) and matchChan (whether file had matching releases).
 func (a *App) processStateFileParallel(relPath string, defOpts LoadOpts, converge func(*state.HelmState) (bool, []error), sharedCtx *Context, errChan chan error, matchChan chan bool) {
 	var file string
 	var dir string
@@ -974,7 +979,11 @@ func (a *App) visitStatesWithContext(fileOrDir string, defOpts LoadOpts, converg
 
 	desiredStateFiles, err := a.findDesiredStateFiles(fileOrDir, defOpts)
 
-	if len(desiredStateFiles) > 1 {
+	// Process files in parallel if we have multiple files and parallel mode is enabled
+	shouldProcessInParallel := len(desiredStateFiles) > 1 && !a.SequentialHelmfiles
+
+	if shouldProcessInParallel {
+		// Parallel processing for multiple files (default behavior)
 		var wg sync.WaitGroup
 		errChan := make(chan error, len(desiredStateFiles))
 		matchChan := make(chan bool, len(desiredStateFiles))
@@ -1002,7 +1011,7 @@ func (a *App) visitStatesWithContext(fileOrDir string, defOpts LoadOpts, converg
 			noMatchInHelmfiles = false
 		}
 	} else {
-		// Sequential processing for single file
+		// Sequential processing for single file or when --sequential-helmfiles is set
 		err = a.visitStateFiles(fileOrDir, defOpts, func(f, d string) (retErr error) {
 			opts := defOpts.DeepCopy()
 

pkg/app/config.go

@@ -13,6 +13,7 @@ type ConfigProvider interface {
 	HelmOCIPlainHTTP() bool
 	SkipDeps() bool
 	SkipRefresh() bool
+	SequentialHelmfiles() bool
 
 	FileOrDir() string
 	KubeContext() string