CLOUDP-279514 Detect and block breaking changes

.github/workflows/breaking-changes.yaml

@@ -0,0 +1,55 @@
+name: Detect Breaking Changes
+
+on:
+  pull_request:
+
+jobs:
+  breaking-changes-manifest:
+    name: Generate Breaking Changes Manifest
+    runs-on: ubuntu-latest
+    outputs:
+      breaking-changes: ${{ steps.breakvalidator.outputs.JSON }}
+    steps:
+      - uses: GitHubSecurityLab/actions-permissions/monitor@v1
+        with:
+          config: ${{ vars.PERMISSIONS_CONFIG }}
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.base.sha }}
+      - name: Install Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+      - name: Install dependencies
+        run: go mod download
+      - name: Run breaking changes validator
+        id: breakvalidator
+        run: |
+          set -e
+          {
+            echo "JSON<<EOF"
+            go run tools/cmd/breakvalidator/main.go generate
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+  detect-breaking-changes:
+    name: Detect Breaking Changes
+    runs-on: ubuntu-latest
+    needs: breaking-changes-manifest
+    steps:
+      - uses: GitHubSecurityLab/actions-permissions/monitor@v1
+        with:
+          config: ${{ vars.PERMISSIONS_CONFIG }}
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Install Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+      - name: Run breaking changes validator
+        env:
+          JSON: ${{ needs.breaking-changes-manifest.outputs.breaking-changes }}
+        run: |
+          set -e
+          echo "$JSON" > main.json
+          go run tools/cmd/breakvalidator/main.go validate < main.json

.github/workflows/close-jira.yml

@@ -10,6 +10,9 @@ jobs:
     runs-on: ubuntu-latest
     if: github.event.pull_request.merged == true && contains(github.event.pull_request.labels.*.name, 'auto_close_jira')
     steps:
+      - uses: GitHubSecurityLab/actions-permissions/monitor@v1
+        with:
+          config: ${{ vars.PERMISSIONS_CONFIG }}
       - name: set jira key (branch name)
         if: ${{ startsWith(github.event.pull_request.head.ref, 'CLOUDP') }}
         env:

scripts/add-copy.sh

@@ -21,6 +21,7 @@ find_files() {
 		\( \
 		-wholename '*mock*' \
 		-o -wholename '*third_party*' \
+		-o -wholename '*docs/command*' \
 		\) -prune \
 		\) \
 		\( -name '*.go' -o -name '*.sh' \)

tools/cmd/breakvalidator/main.go

@@ -0,0 +1,199 @@
+// Copyright 2025 MongoDB Inc
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package main
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"slices"
+
+	"github.com/mongodb/mongodb-atlas-cli/atlascli/internal/cli/root"
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+)
+
+var (
+	errFlagDeleted        = errors.New("flag was deleted")
+	errFlagTypeChanged    = errors.New("flag type changed")
+	errFlagDefaultChanged = errors.New("flag default value changed")
+	errCmdDeleted         = errors.New("command deleted")
+	errCmdRemovedAlias    = errors.New("command alias removed")
+	errFlagShortChanged   = errors.New("flag shorthand changed")
+)
+
+type flagData struct {
+	Type    string `json:"type"`
+	Default string `json:"default"`
+	Short   string `json:"short"`
+}
+
+type cmdData struct {
+	Aliases []string            `json:"aliases"`
+	Flags   map[string]flagData `json:"flags"`
+}
+
+func generateCmd(cmd *cobra.Command) cmdData {
+	data := cmdData{}
+	if len(cmd.Aliases) > 0 {
+		data.Aliases = cmd.Aliases
+	}
+	flags := false
+	data.Flags = map[string]flagData{}
+	cmd.Flags().VisitAll(func(f *pflag.Flag) {
+		data.Flags[f.Name] = flagData{
+			Type:    f.Value.Type(),
+			Default: f.DefValue,
+			Short:   f.Shorthand,
+		}
+		flags = true
+	})
+	if !flags {
+		data.Flags = nil
+	}
+	return data
+}
+
+func generateCmds(cmd *cobra.Command) map[string]cmdData {
+	data := map[string]cmdData{}
+	data[cmd.CommandPath()] = generateCmd(cmd)
+	for _, c := range cmd.Commands() {
+		for k, v := range generateCmds(c) {
+			data[k] = v
+		}
+	}
+	return data
+}
+
+func generateCmdRun(output io.Writer) error {
+	cliCmd := root.Builder()
+	data := generateCmds(cliCmd)
+	return json.NewEncoder(output).Encode(data)
+}
+
+func compareFlags(cmdPath string, mainFlags, changedFlags map[string]flagData) []error {
+	if mainFlags == nil {
+		return nil
+	}
+
+	changes := []error{}
+
+	for flagName, flagValue := range mainFlags {
+		changedFlagValue, ok := changedFlags[flagName]
+		if !ok {
+			changes = append(changes, fmt.Errorf("%w: %s --%s", errFlagDeleted, cmdPath, flagName))
+			continue
+		}
+
+		if flagValue.Type != changedFlagValue.Type {
+			changes = append(changes, fmt.Errorf("%w: %s --%s", errFlagTypeChanged, cmdPath, flagName))
+		}
+
+		if flagValue.Default != changedFlagValue.Default {
+			changes = append(changes, fmt.Errorf("%w: %s --%s", errFlagDefaultChanged, cmdPath, flagName))
+		}
+
+		if flagValue.Short != changedFlagValue.Short {
+			changes = append(changes, fmt.Errorf("%w: %s --%s", errFlagShortChanged, cmdPath, flagName))
+		}
+	}
+
+	return changes
+}
+
+func compareCmds(changedData, mainData map[string]cmdData) error {
+	changes := []error{}
+	for cmdPath, mv := range mainData {
+		cv, ok := changedData[cmdPath]
+		if !ok {
+			changes = append(changes, fmt.Errorf("%w: %s", errCmdDeleted, cmdPath))
+			continue
+		}
+
+		if mv.Aliases != nil {
+			mainAliases := mv.Aliases
+			changedAliases := cv.Aliases
+
+			for _, alias := range mainAliases {
+				if !slices.Contains(changedAliases, alias) {
+					changes = append(changes, fmt.Errorf("%w: %s", errCmdRemovedAlias, cmdPath))
+				}
+			}
+		}
+
+		changes = append(changes, compareFlags(cmdPath, mv.Flags, cv.Flags)...)
+	}
+
+	if len(changes) > 0 {
+		return errors.Join(changes...)
+	}
+
+	return nil
+}
+
+func validateCmdRun(output io.Writer, input io.Reader) error {
+	var inputData map[string]cmdData
+	if err := json.NewDecoder(input).Decode(&inputData); err != nil {
+		return err
+	}
+
+	cliCmd := root.Builder()
+	generatedData := generateCmds(cliCmd)
+
+	err := compareCmds(generatedData, inputData)
+	if err != nil {
+		return err
+	}
+
+	fmt.Fprintln(output, "no breaking changes detected")
+	return nil
+}
+
+func buildCmd() *cobra.Command {
+	generateCmd := &cobra.Command{
+		Use:   "generate",
+		Short: "Generate the CLI command structure.",
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return generateCmdRun(cmd.OutOrStdout())
+		},
+	}
+
+	validateCmd := &cobra.Command{
+		Use:   "validate",
+		Short: "Validate the CLI command structure.",
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return validateCmdRun(cmd.OutOrStdout(), cmd.InOrStdin())
+		},
+	}
+
+	rootCmd := &cobra.Command{
+		Use:   "breakvalidator",
+		Short: "CLI tool to validate breaking changes in the CLI.",
+	}
+	rootCmd.AddCommand(generateCmd)
+	rootCmd.AddCommand(validateCmd)
+
+	return rootCmd
+}
+
+func main() {
+	rootCmd := buildCmd()
+	err := rootCmd.Execute()
+	if err != nil {
+		os.Exit(1)
+	}
+}