feat: Annotate users when givenName and familyName are identical (#529)

## Summary

When users sign up via GitHub with a single-word display name, the
identity provider populates both `givenName` and `familyName` with the
same value. Until now, front-end clients had no reliable signal to
detect this and prompt the user to provide distinct names.

This PR adds annotation-based signalling to the user controller. On
every reconcile, the controller evaluates whether `givenName` equals
`familyName` (both non-empty) and manages the
`iam.miloapis.com/name-review-required: "true"` annotation accordingly —
adding it when the names match, removing it once they differ. The
annotation key is exported as a typed constant in `user_types.go` with
documentation explaining semantics and usage for front-end consumers.

## Changes

- **`pkg/apis/iam/v1alpha1/user_types.go`** — Adds
`UserNameReviewRequiredAnnotation` constant with inline doc comment
covering purpose, expected front-end behavior, value semantics, and a
YAML example.
- **`internal/controllers/iam/user_controller.go`** — Adds
`reconcileNameReviewAnnotation` method and calls it in the main
reconcile loop after `ensureOwnerReferences`.

## Test plan

- [ ] User created via GitHub with a single-word name has the annotation
set after reconciliation
- [ ] Annotation is removed after the user updates their profile with
distinct given and family names
- [ ] User with already distinct names is not annotated
- [ ] No unnecessary API calls when annotation state is already correct
(no-op path)

Author: JoseSzycho

internal/controllers/iam/user_controller.go

@@ -71,6 +71,12 @@ func (r *UserController) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.
 		return ctrl.Result{}, err
 	}
 
+	// Reconcile the name-review annotation based on whether givenName and familyName match
+	if err := r.reconcileNameReviewAnnotation(ctx, user); err != nil {
+		log.Error(err, "Failed to reconcile name review annotation")
+		return ctrl.Result{}, err
+	}
+
 	// Determine desired state based on existence of any UserDeactivation for this user
 	var udList iamv1alpha1.UserDeactivationList
 	if err := r.Client.List(ctx, &udList, client.MatchingFields{"spec.userRef.name": user.Name}); err != nil {
@@ -131,6 +137,40 @@ func (r *UserController) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.
 	return ctrl.Result{}, nil
 }
 
+// reconcileNameReviewAnnotation adds or removes the name-review-required annotation depending on
+// whether givenName and familyName are identical. This situation arises when an identity provider
+// (e.g. GitHub) supplies a single display name and the system copies it into both fields.
+func (r *UserController) reconcileNameReviewAnnotation(ctx context.Context, user *iamv1alpha1.User) error {
+	log := log.FromContext(ctx).WithName("reconcile-name-review-annotation")
+
+	annotations := user.GetAnnotations()
+	_, annotationPresent := annotations[iamv1alpha1.UserNameReviewRequiredAnnotation]
+	namesAreEqual := user.Spec.GivenName != "" && user.Spec.GivenName == user.Spec.FamilyName
+
+	switch {
+	case namesAreEqual && !annotationPresent:
+		if annotations == nil {
+			annotations = map[string]string{}
+		}
+		annotations[iamv1alpha1.UserNameReviewRequiredAnnotation] = "true"
+		user.SetAnnotations(annotations)
+		if err := r.Client.Update(ctx, user); err != nil {
+			return fmt.Errorf("failed to add name-review annotation: %w", err)
+		}
+		log.Info("Added name-review-required annotation", "user", user.Name)
+
+	case !namesAreEqual && annotationPresent:
+		delete(annotations, iamv1alpha1.UserNameReviewRequiredAnnotation)
+		user.SetAnnotations(annotations)
+		if err := r.Client.Update(ctx, user); err != nil {
+			return fmt.Errorf("failed to remove name-review annotation: %w", err)
+		}
+		log.Info("Removed name-review-required annotation", "user", user.Name)
+	}
+
+	return nil
+}
+
 // ensureOwnerReferences ensures that PolicyBinding and UserPreference resources have proper owner references
 func (r *UserController) ensureOwnerReferences(ctx context.Context, user *iamv1alpha1.User) error {
 	log := log.FromContext(ctx).WithName("ensure-owner-references")

pkg/apis/iam/v1alpha1/user_types.go

@@ -130,3 +130,23 @@ const (
 	AuthProviderGitHub AuthProvider = "github"
 	AuthProviderGoogle AuthProvider = "google"
 )
+
+const (
+	// UserNameReviewRequiredAnnotation is set on a User when givenName and familyName are
+	// identical, which typically happens when the identity provider (e.g. GitHub) supplies
+	// only a single display name and the system splits it across both fields.
+	//
+	// Presence of this annotation signals that the user has not yet provided distinct given
+	// and family names. Front-end clients should prompt the user to review and update their
+	// profile when this annotation is present.
+	//
+	// The annotation value is always "true". The annotation is removed automatically by the
+	// user controller once givenName and familyName differ.
+	//
+	// Example:
+	//
+	//   metadata:
+	//     annotations:
+	//       iam.miloapis.com/name-review-required: "true"
+	UserNameReviewRequiredAnnotation = "iam.miloapis.com/name-review-required"
+)