enhance

Author: camilamacedo86

docs/book/src/reference/commands/alpha_update.md

@@ -15,7 +15,7 @@ automates the process of running `kubebuilder alpha update` on a schedule
 workflow when new Kubebuilder releases are available.
 >
 > Moreover, you will be able to get help from AI models to understand what changes are needed to keep your project up to date
-and how to solve conflicts if any be faced.
+and how to solve conflicts if any are faced.
 
 ## When to Use It
 

pkg/cli/alpha/internal/update/helpers/open_gh_issue.go

@@ -146,6 +146,36 @@ List each conflicted file with a brief suggestion. For GENERATED files:
 Always end suggestions with: "run: make fmt vet lint-fix"
 </details>`
 
+// Static repository guidance for AI prompts (concise, model-friendly).
+const projectOverview = `## Repository Guidance (Project Overview)
+Use this as factual context to interpret file changes. Do not invent paths or files.
+
+- Type: Kubernetes Operator (Kubebuilder scaffold)
+- Language: Go (version pinned in go.mod)
+- Key libs: sigs.k8s.io/controller-runtime, k8s.io/*
+- Tools: sigs.k8s.io/controller-tools (controller-gen), kustomize, envtest, golangci-lint, kind (for e2e)
+
+## Project Layout
+- /api — CRD types and deepcopy files
+- internal/controllers — Reconciliation logic
+- internal/webhooks — Admission webhooks (defaulting and validating)
+- /cmd — Main entrypoint
+- /config — Kustomize manifests and operator configuration:
+  - certmanager/ — Certificates and issuers
+  - crd/ — CustomResourceDefinitions
+  - default/ — Default overlays
+  - manager/ — Manager deployment manifests
+  - network-policy/ — Network policies
+  - prometheus/ — Monitoring resources
+  - rbac/ — Roles and bindings
+  - samples/ — Example custom resources
+  - webhook/ — Webhook configurations
+- /test — E2E tests and helpers
+- /dist — Distribution artifacts
+- Makefile — Build automation
+- PROJECT — Project definition file (auto-generated; avoid manual edits)
+`
+
 // isGeneratedKB returns true for Kubebuilder-generated artifacts.
 func isGeneratedKB(path string) bool {
 	return strings.Contains(path, "/zz_generated.") ||
@@ -154,20 +184,6 @@ func isGeneratedKB(path string) bool {
 		path == "dist/install.yaml"
 }
 
-// readCopilotInstructions returns the contents of .github/copilot_instructions.md
-// from the repo root. If the file doesn't exist or can't be read, it returns "".
-// maxBytes trims the content to avoid overly large prompts (use 0 for no trim).
-func readCopilotInstructions() string {
-	const rel = ".github/copilot_instructions.md"
-	b, err := os.ReadFile(rel)
-	if err != nil || len(b) == 0 {
-		return ""
-	}
-	// Normalize line endings and trim extra whitespace to keep the prompt tidy.
-	s := strings.ReplaceAll(string(b), "\r\n", "\n")
-	return strings.TrimSpace(s)
-}
-
 // ListConflictFiles walks the working directory and finds files that contain
 // Git conflict markers, splitting results into SOURCE vs GENERATED buckets.
 // This version does not rely on `git grep`.
@@ -308,36 +324,87 @@ func ListChangedFiles(base, head string) (src []string, gen []string) {
 	return src, gen
 }
 
+// BuildAIPrompt builds the full positional prompt for `gh models run`.
+// Provide BOTH: changed files and conflicted files.
 // BuildAIPrompt builds the full positional prompt for `gh models run`.
 // Provide BOTH: changed files and conflicted files.
 func BuildAIPrompt(
-	from, to, out, compareURL, releaseURL string,
+	fromVersion, toVersion, baseBranch, outBranch, compareURL, releaseURL string,
 	changedSrc, changedGen []string,
 	conflictSrc, conflictGen []string,
 ) string {
 	var ctx strings.Builder
+
+	// Header/context
 	ctx.WriteString("PROJECT: Created with Kubebuilder\n")
-	fmt.Fprintf(&ctx, "Upgrade: from %s to %s\n", from, to)
-	fmt.Fprintf(&ctx, "Output branch: %s\n", out)
+	fmt.Fprintf(&ctx, "Upgrade: from %s to %s\n", fromVersion, toVersion)
+	fmt.Fprintf(&ctx, "Output branch: %s\n", outBranch)
 	fmt.Fprintf(&ctx, "Compare PR URL: %s\n", compareURL)
 	fmt.Fprintf(&ctx, "Release notes: %s\n\n", releaseURL)
 
-	// Optional: project guidance for the model (teaches the AI)
-	if s := strings.TrimSpace(readCopilotInstructions()); s != "" {
-		ctx.WriteString("## Repository Guidance (.github/copilot_instructions.md)\n")
-		ctx.WriteString(s)
-		ctx.WriteString("\n\n")
+	// Repository guidance (concise, model-friendly)
+	ctx.WriteString(projectOverview)
+	ctx.WriteString("\n\n")
+
+	// Teach the model the 3-way workflow and show explicit compare range with SHAs
+	ctx.WriteString("## Update Method (3-way merge)\n")
+	ctx.WriteString("- Ancestor: clean scaffold at FROM version\n")
+	ctx.WriteString("- Original: your current project from --from-branch\n")
+	ctx.WriteString("- Upgrade: clean scaffold at TO version\n")
+	ctx.WriteString("- Merge: Original -> Upgrade (then squash or keep history)\n\n")
+
+	base := strings.TrimSpace(baseBranch)
+	head := strings.TrimSpace(outBranch)
+	fmt.Fprintf(&ctx, "## Compare Range\nBASE: %s\nHEAD: %s\n", rev(base), rev(head))
+	if compareURL != "" {
+		fmt.Fprintf(&ctx, "Compare PR URL: %s\n\n", compareURL)
+	} else {
+		ctx.WriteString("\n")
+	}
+
+	// Whole-repo diff summaries
+	short := DiffShortStat(base, head)
+	nameStatus := DiffNameStatus(base, head)
+	stat := DiffStat(base, head)
+
+	ctx.WriteString("## Diff Summary (whole repo)\n")
+	if short != "" {
+		fmt.Fprintf(&ctx, "%s\n\n", short)
+	}
+	if stat != "" {
+		ctx.WriteString("### Per-file stat\n")
+		ctx.WriteString(stat + "\n\n")
+	}
+	if nameStatus != "" {
+		ctx.WriteString("### Name-Status (A/M/D/R)\n")
+		ctx.WriteString(nameStatus + "\n\n")
 	}
 
-	// List changed files so the AI can build the Reviewed Changes table.
+	// Dependency bump spotlight
+	ctx.WriteString("## go.mod Summary (require/replace/module)\n")
+	ctx.WriteString(summarizeGoModDiff(base, head) + "\n\n")
+
+	// Targeted patches for reviewer-relevant SOURCE files (exclude GENERATED)
+	important := pickImportantFiles(changedSrc, 10) // include /api; keep token budget tight
+	if len(important) > 0 {
+		ctx.WriteString("## Selected Patches (SOURCE)\n")
+		for _, p := range important {
+			patch := filePatch(base, head, p, 12<<10) // 12KB/file cap
+			if patch == "" {
+				continue
+			}
+			fmt.Fprintf(&ctx, "\n----- BEGIN PATCH %s -----\n%s\n----- END PATCH %s -----\n", p, patch, p)
+		}
+		ctx.WriteString("\n")
+	}
+
+	// File lists for the model to build tables/sections
 	if len(changedSrc) > 0 {
 		fmt.Fprintf(&ctx, "\nChanged [SOURCE] files:\n%s\n", bulletList(changedSrc))
 	}
 	if len(changedGen) > 0 {
 		fmt.Fprintf(&ctx, "\nChanged [GENERATED] files:\n%s\n", bulletList(changedGen))
 	}
-
-	// List conflicts for extra context (will be empty if none)
 	if len(conflictSrc) > 0 {
 		fmt.Fprintf(&ctx, "\nConflicted [SOURCE] files:\n%s\n", bulletList(conflictSrc))
 	}
@@ -347,3 +414,132 @@ func BuildAIPrompt(
 
 	return ctx.String() + "\n\n" + aiPRPrompt
 }
+
+// DiffShortStat returns "N files changed, X insertions(+), Y deletions(-)".
+func DiffShortStat(base, head string) string {
+	cmd := exec.Command("git", "diff", "--shortstat", base+".."+head)
+	out, _ := cmd.Output()
+	return strings.TrimSpace(string(out))
+}
+
+// DiffNameStatus returns lines like "M\tpath/file.go" (with renames).
+func DiffNameStatus(base, head string) string {
+	cmd := exec.Command("git", "diff", "--name-status", "-M", base+".."+head)
+	out, _ := cmd.Output()
+	return strings.TrimSpace(string(out))
+}
+
+// DiffStat returns per-file stat (compact summary with +/- bars).
+func DiffStat(base, head string) string {
+	cmd := exec.Command("git", "diff", "--stat", "-M", base+".."+head)
+	out, _ := cmd.Output()
+	return strings.TrimSpace(string(out))
+}
+
+// filePatch returns a unified diff for one file, truncated to maxBytes.
+func filePatch(base, head, path string, maxBytes int) string {
+	cmd := exec.Command("git", "diff", "--no-color", "--unified=3", base+".."+head, "--", path)
+	out, _ := cmd.Output()
+	if len(out) == 0 {
+		return ""
+	}
+	if maxBytes > 0 && len(out) > maxBytes {
+		out = append(out[:maxBytes], []byte("\n... [truncated] ...")...)
+	}
+	return strings.TrimSpace(string(out))
+}
+
+// pickImportantFiles chooses reviewer-relevant SOURCE files first.
+// Priority order: go.mod, Makefile, /api, internal/controllers, internal/webhooks, /cmd, then the rest.
+func pickImportantFiles(src []string, limit int) []string {
+	if len(src) == 0 || limit <= 0 {
+		return nil
+	}
+	orderFirst := []string{"go.mod", "Makefile"}
+	var api, ctrls, hooks, cmdPaths, rest []string
+	seen := map[string]bool{}
+
+	for _, p := range src {
+		switch {
+		case p == "go.mod" || p == "Makefile":
+			// handled later to keep strict top order
+		case strings.HasPrefix(p, "api/"):
+			api = append(api, p)
+			seen[p] = true
+		case strings.HasPrefix(p, "internal/controllers/"):
+			ctrls = append(ctrls, p)
+			seen[p] = true
+		case strings.HasPrefix(p, "internal/webhooks/"):
+			hooks = append(hooks, p)
+			seen[p] = true
+		case strings.HasPrefix(p, "cmd/"):
+			cmdPaths = append(cmdPaths, p)
+			seen[p] = true
+		default:
+			// defer to the end
+		}
+	}
+	for _, p := range src {
+		if !seen[p] && p != "go.mod" && p != "Makefile" {
+			rest = append(rest, p)
+		}
+	}
+
+	var out []string
+	// go.mod and Makefile first if present
+	for _, k := range orderFirst {
+		for _, p := range src {
+			if p == k {
+				out = append(out, p)
+				break
+			}
+		}
+	}
+	// then API, controllers, webhooks, cmd/, then the rest
+	out = append(out, api...)
+	out = append(out, ctrls...)
+	out = append(out, hooks...)
+	out = append(out, cmdPaths...)
+	out = append(out, rest...)
+
+	if len(out) > limit {
+		out = out[:limit]
+	}
+	return out
+}
+
+// summarizeGoModDiff extracts only require/replace/module lines for brevity.
+func summarizeGoModDiff(base, head string) string {
+	cmd := exec.Command("git", "diff", "--no-color", "--unified=0", base+".."+head, "--", "go.mod")
+	out, _ := cmd.Output()
+	if len(out) == 0 {
+		return "(no go.mod summary changes detected)"
+	}
+	lines := strings.Split(string(out), "\n")
+	var keep []string
+	for _, l := range lines {
+		t := strings.TrimSpace(l)
+		if strings.HasPrefix(t, "+require ") || strings.HasPrefix(t, "-require ") ||
+			strings.HasPrefix(t, "+replace ") || strings.HasPrefix(t, "-replace ") ||
+			strings.HasPrefix(t, "+module ") || strings.HasPrefix(t, "-module ") {
+			keep = append(keep, t)
+		}
+	}
+	s := strings.Join(keep, "\n")
+	s = strings.TrimSpace(s)
+	if s == "" {
+		return "(no go.mod summary changes detected)"
+	}
+	return s
+}
+
+// rev prints "<ref> @ <sha7>" if ref resolves, else returns the ref.
+func rev(ref string) string {
+	cmd := exec.Command("git", "rev-parse", "--short=7", ref)
+	out, _ := cmd.Output()
+	sha := strings.TrimSpace(string(out))
+	if sha == "" {
+		return ref
+	}
+	return fmt.Sprintf("%s @ %s", ref, sha)
+}

pkg/cli/alpha/internal/update/update.go

@@ -284,7 +284,12 @@ func (opts *Update) openGitHubIssue(hasConflicts bool) error {
 		releaseURL := fmt.Sprintf("https://github.com/kubernetes-sigs/kubebuilder/releases/tag/%s",
 			opts.ToVersion)
 		fullPrompt := helpers.BuildAIPrompt(
-			opts.FromVersion, opts.ToVersion, out, createPRURL, releaseURL,
+			opts.FromVersion, // FROM version
+			opts.ToVersion,   // TO version
+			opts.FromBranch,  // base branch for diff
+			out,              // output branch (HEAD) for diff
+			createPRURL,      // compare URL
+			releaseURL,       // release notes
 			changedSrc, changedGen, conflictSrc, conflictGen,
 		)