refactor: return errors from registry constructors and introduce SemVersion pflag type

Registry constructors (check.NewRegistry, dependencies.NewRegistry,
action.NewRegistry) now return (*Registry, error) instead of panicking
via MustRegister, propagating registration errors to callers.

Replace the TargetVersion string + parsedTargetVersion *semver.Version
pair in the lint Command with a single version.SemVersion type that
implements pflag.Value, validating at flag-parse time.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: lburgazzoli

cmd/lint/lint.go

@@ -74,18 +74,21 @@ func AddCommand(root *cobra.Command, flags *genericclioptions.ConfigFlags) {
 		ErrOut: root.ErrOrStderr(),
 	}
 
-	// Create command with ConfigFlags from parent to ensure CLI auth flags are used
-	command := lintpkg.NewCommand(streams, flags)
+	command, err := lintpkg.NewCommand(streams, flags)
+	if err != nil {
+		_, _ = fmt.Fprintf(root.ErrOrStderr(), "Error initializing lint command: %v\n", err)
+
+		return
+	}
 
 	cmd := &cobra.Command{
 		Use:           cmdName,
 		Short:         cmdShort,
 		Long:          cmdLong,
 		Example:       cmdExample,
 		SilenceUsage:  true,
-		SilenceErrors: true, // We'll handle error output manually based on --quiet flag
+		SilenceErrors: true,
 		RunE: func(cmd *cobra.Command, _ []string) error {
-			// Complete phase
 			if err := command.Complete(); err != nil {
 				if command.Verbose {
 					_, _ = fmt.Fprintf(cmd.ErrOrStderr(), "Error: %v\n", err)
@@ -94,7 +97,6 @@ func AddCommand(root *cobra.Command, flags *genericclioptions.ConfigFlags) {
 				return fmt.Errorf("completing command: %w", err)
 			}
 
-			// Validate phase
 			if err := command.Validate(); err != nil {
 				if command.Verbose {
 					_, _ = fmt.Fprintf(cmd.ErrOrStderr(), "Error: %v\n", err)
@@ -103,7 +105,6 @@ func AddCommand(root *cobra.Command, flags *genericclioptions.ConfigFlags) {
 				return fmt.Errorf("validating command: %w", err)
 			}
 
-			// Run phase
 			err := command.Run(cmd.Context())
 			if err != nil {
 				if command.Verbose {
@@ -117,7 +118,6 @@ func AddCommand(root *cobra.Command, flags *genericclioptions.ConfigFlags) {
 		},
 	}
 
-	// Register flags using AddFlags method
 	command.AddFlags(cmd.Flags())
 
 	root.AddCommand(cmd)

cmd/migrate/list/list.go

@@ -1,6 +1,8 @@
 package list
 
 import (
+	"fmt"
+
 	"github.com/spf13/cobra"
 
 	"k8s.io/cli-runtime/pkg/genericclioptions"
@@ -41,7 +43,13 @@ func AddCommand(
 	flags *genericclioptions.ConfigFlags,
 	streams genericiooptions.IOStreams,
 ) {
-	command := migrate.NewListCommand(streams)
+	command, err := migrate.NewListCommand(streams)
+	if err != nil {
+		_, _ = fmt.Fprintf(parent.ErrOrStderr(), "Error initializing list command: %v\n", err)
+
+		return
+	}
+
 	command.ConfigFlags = flags
 
 	cmd := &cobra.Command{

cmd/migrate/prepare/prepare.go

@@ -1,6 +1,8 @@
 package prepare
 
 import (
+	"fmt"
+
 	"github.com/spf13/cobra"
 
 	"k8s.io/cli-runtime/pkg/genericclioptions"
@@ -51,7 +53,13 @@ func AddCommand(
 	flags *genericclioptions.ConfigFlags,
 	streams genericiooptions.IOStreams,
 ) {
-	command := migrate.NewPrepareCommand(streams)
+	command, err := migrate.NewPrepareCommand(streams)
+	if err != nil {
+		_, _ = fmt.Fprintf(parent.ErrOrStderr(), "Error initializing prepare command: %v\n", err)
+
+		return
+	}
+
 	command.ConfigFlags = flags
 
 	cmd := &cobra.Command{

cmd/migrate/run/run.go

@@ -1,6 +1,8 @@
 package run
 
 import (
+	"fmt"
+
 	"github.com/spf13/cobra"
 
 	"k8s.io/cli-runtime/pkg/genericclioptions"
@@ -48,7 +50,13 @@ func AddCommand(
 	flags *genericclioptions.ConfigFlags,
 	streams genericiooptions.IOStreams,
 ) {
-	command := migrate.NewRunCommand(streams)
+	command, err := migrate.NewRunCommand(streams)
+	if err != nil {
+		_, _ = fmt.Fprintf(parent.ErrOrStderr(), "Error initializing run command: %v\n", err)
+
+		return
+	}
+
 	command.ConfigFlags = flags
 
 	cmd := &cobra.Command{

docs/lint/architecture.md

@@ -82,45 +82,44 @@ func NewCommand(
     streams genericiooptions.IOStreams,
     configFlags *genericclioptions.ConfigFlags,
     options ...CommandOption,
-) *Command {
-    registry := check.NewRegistry()
-
-    // Explicitly register all checks (no global state, full test isolation)
-    // Components (11)
-    registry.MustRegister(codeflare.NewRemovalCheck())
-    registry.MustRegister(dashboard.NewAcceleratorProfileMigrationCheck())
-    registry.MustRegister(dashboard.NewHardwareProfileMigrationCheck())
-    registry.MustRegister(datasciencepipelines.NewInstructLabRemovalCheck())
-    registry.MustRegister(datasciencepipelines.NewRenamingCheck())
-    registry.MustRegister(kserve.NewServerlessRemovalCheck())
-    registry.MustRegister(kserve.NewInferenceServiceConfigCheck())
-    registry.MustRegister(kueue.NewManagementStateCheck())
-    registry.MustRegister(kueue.NewOperatorInstalledCheck())
-    registry.MustRegister(modelmesh.NewRemovalCheck())
-    registry.MustRegister(trainingoperator.NewDeprecationCheck())
-
-    // Dependencies (3)
-    registry.MustRegister(certmanager.NewCheck())
-    registry.MustRegister(openshift.NewCheck())
-    registry.MustRegister(servicemeshoperator.NewCheck())
-
-    // Services (1)
-    registry.MustRegister(servicemesh.NewRemovalCheck())
-
-    // Workloads (8)
-    registry.MustRegister(guardrails.NewImpactedWorkloadsCheck())
-    registry.MustRegister(guardrails.NewOtelMigrationCheck())
-    registry.MustRegister(kserveworkloads.NewAcceleratorMigrationCheck())
-    registry.MustRegister(kserveworkloads.NewImpactedWorkloadsCheck())
-    registry.MustRegister(notebook.NewAcceleratorMigrationCheck())
-    registry.MustRegister(notebook.NewImpactedWorkloadsCheck())
-    registry.MustRegister(ray.NewImpactedWorkloadsCheck())
-    registry.MustRegister(trainingoperatorworkloads.NewImpactedWorkloadsCheck())
+) (*Command, error) {
+    registry, err := check.NewRegistry(
+        // Components (11)
+        codeflare.NewRemovalCheck(),
+        dashboard.NewAcceleratorProfileMigrationCheck(),
+        dashboard.NewHardwareProfileMigrationCheck(),
+        datasciencepipelines.NewInstructLabRemovalCheck(),
+        datasciencepipelines.NewRenamingCheck(),
+        kserve.NewServerlessRemovalCheck(),
+        kserve.NewInferenceServiceConfigCheck(),
+        kueue.NewManagementStateCheck(),
+        kueue.NewOperatorInstalledCheck(),
+        modelmesh.NewRemovalCheck(),
+        trainingoperator.NewDeprecationCheck(),
+        // Dependencies (3)
+        certmanager.NewCheck(),
+        openshift.NewCheck(),
+        servicemeshoperator.NewCheck(),
+        // Services (1)
+        servicemesh.NewRemovalCheck(),
+        // Workloads (8)
+        guardrails.NewImpactedWorkloadsCheck(),
+        guardrails.NewOtelMigrationCheck(),
+        kserveworkloads.NewAcceleratorMigrationCheck(),
+        kserveworkloads.NewImpactedWorkloadsCheck(),
+        notebook.NewAcceleratorMigrationCheck(),
+        notebook.NewImpactedWorkloadsCheck(),
+        ray.NewImpactedWorkloadsCheck(),
+        trainingoperatorworkloads.NewImpactedWorkloadsCheck(),
+    )
+    if err != nil {
+        return nil, fmt.Errorf("registering checks: %w", err)
+    }
 
     return &Command{
         SharedOptions: shared,
         registry:      registry,
-    }
+    }, nil
 }
 ```
 

docs/lint/writing-checks.md

@@ -79,11 +79,14 @@ func (c *Check) Validate(ctx context.Context, target check.Target) (*result.Diag
 }
 ```
 
-**Registration:** Checks are explicitly registered in `pkg/lint/command.go`:
+**Registration:** Checks are explicitly registered in `pkg/lint/command.go` via `check.NewRegistry(...)`:
 
 ```go
 // In NewCommand()
-registry.MustRegister(dashboard.NewCheck())
+registry, err := check.NewRegistry(
+    dashboard.NewCheck(),
+    // ... other checks
+)
 ```
 
 ### Using BaseCheck
@@ -129,34 +132,33 @@ func NewCommand(
     streams genericiooptions.IOStreams,
     configFlags *genericclioptions.ConfigFlags,
     options ...CommandOption,
-) *Command {
-    registry := check.NewRegistry()
-
-    // Explicitly register all checks
-    // Components (11)
-    registry.MustRegister(codeflare.NewRemovalCheck())
-    registry.MustRegister(dashboard.NewAcceleratorProfileMigrationCheck())
-    registry.MustRegister(dashboard.NewHardwareProfileMigrationCheck())
-    registry.MustRegister(datasciencepipelines.NewInstructLabRemovalCheck())
-    // ... additional component checks
-
-    // Dependencies (4)
-    registry.MustRegister(certmanager.NewCheck())
-    // ... additional dependency checks
-
-    // Services (1)
-    registry.MustRegister(servicemesh.NewRemovalCheck())
-
-    // Workloads (7)
-    registry.MustRegister(guardrails.NewOtelMigrationCheck())
-    registry.MustRegister(kserveworkloads.NewAcceleratorMigrationCheck())
-    registry.MustRegister(notebook.NewImpactedWorkloadsCheck())
-    // ... additional workload checks
+) (*Command, error) {
+    registry, err := check.NewRegistry(
+        // Components (11)
+        codeflare.NewRemovalCheck(),
+        dashboard.NewAcceleratorProfileMigrationCheck(),
+        dashboard.NewHardwareProfileMigrationCheck(),
+        datasciencepipelines.NewInstructLabRemovalCheck(),
+        // ... additional component checks
+        // Dependencies (4)
+        certmanager.NewCheck(),
+        // ... additional dependency checks
+        // Services (1)
+        servicemesh.NewRemovalCheck(),
+        // Workloads (7)
+        guardrails.NewOtelMigrationCheck(),
+        kserveworkloads.NewAcceleratorMigrationCheck(),
+        notebook.NewImpactedWorkloadsCheck(),
+        // ... additional workload checks
+    )
+    if err != nil {
+        return nil, fmt.Errorf("registering checks: %w", err)
+    }
 
     return &Command{
         SharedOptions: shared,
         registry:      registry,
-    }
+    }, nil
 }
 ```
 
@@ -852,8 +854,8 @@ func (c *RemovalCheck) Validate(ctx context.Context, target check.Target) (*resu
         Run(ctx, validate.Removal("CodeFlare is enabled (state: %s) but will be removed in RHOAI 3.x"))
 }
 
-// Registration is done explicitly in pkg/lint/command.go:
-// registry.MustRegister(codeflare.NewRemovalCheck())
+// Registration is done explicitly in pkg/lint/command.go via check.NewRegistry(...)
+// e.g. codeflare.NewRemovalCheck() is passed to check.NewRegistry()
 ```
 
 **Note:** For complex checks that don't fit the builder pattern, you can still write checks without builders using `c.NewResult()` and manually fetching resources via `client.GetDataScienceCluster(ctx, target.Client)`.

docs/migrate/implementation-plan.md

@@ -67,8 +67,8 @@ type ActionRegistry struct {
 ```
 Pattern matching via `ListByPattern()`, similar to CheckRegistry
 
-**File:** `pkg/migrate/action/global.go`
-Global registry with `MustRegisterAction()` for auto-registration
+**File:** `pkg/migrate/action/registry.go`
+Variadic `NewActionRegistry(actions ...Action) (*ActionRegistry, error)` constructor with error-returning `Register(actions ...Action) error`
 
 #### 1.3 Action Executor
 **File:** `pkg/migrate/action/executor.go`
@@ -389,16 +389,11 @@ if step1.Status == result.StepFailed {
 }
 ```
 
-### Auto-Registration Pattern
+### Explicit Registration Pattern
 ```go
-// In rhbok.go
-func init() {
-    action.MustRegisterAction(&RHBOKMigrationAction{})
-}
-
-// In cmd/migrate/migrate.go
-import (
-    _ "github.com/opendatahub-io/odh-cli/pkg/migrate/actions/kueue/rhbok"
+// Actions are registered explicitly in each command constructor:
+registry, err := action.NewActionRegistry(
+    &rhbok.RHBOKMigrationAction{},
 )
 ```
 

pkg/backup/command.go

@@ -96,13 +96,23 @@ func (c *Command) Complete() error {
 		}
 	}
 
-	// Create registry - always needed even if empty
-	c.depRegistry = dependencies.NewRegistry()
-
-	// Only register resolvers if dependency resolution is enabled
 	if c.Dependencies {
-		c.depRegistry.MustRegister(notebooks.NewResolver())
-		c.depRegistry.MustRegister(dspa.NewResolver())
+		registry, err := dependencies.NewRegistry(
+			notebooks.NewResolver(),
+			dspa.NewResolver(),
+		)
+		if err != nil {
+			return fmt.Errorf("registering dependency resolvers: %w", err)
+		}
+
+		c.depRegistry = registry
+	} else {
+		registry, err := dependencies.NewRegistry()
+		if err != nil {
+			return fmt.Errorf("creating dependency registry: %w", err)
+		}
+
+		c.depRegistry = registry
 	}
 
 	return nil