18284275304

Committed 06 Oct 2025 02:34PM UTC coverage: 64.3% (+0.002%) from 64.298%

Build Type

push

github

Committed by GitHub

Commit Message

CLOUDP-347241: Remove all references to public preview in L1 commands (#4234)

Coverage Stats

25680 of 39938 relevant lines covered (64.3%)

0.8 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

0.0

/tools/cmd/docs/transformations.go

// 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 (
        "cmp"
        _ "embed"
        "fmt"
        "os"
        "regexp"
        "slices"
        "strconv"
        "strings"

        "github.com/mongodb/mongodb-atlas-cli/atlascli/internal/cli"
        pluginCmd "github.com/mongodb/mongodb-atlas-cli/atlascli/internal/cli/plugin"
        "github.com/mongodb/mongodb-atlas-cli/atlascli/internal/plugin"
        "github.com/mongodb/mongodb-atlas-cli/atlascli/tools/internal/metadatatypes"
        "github.com/spf13/cobra"
        "github.com/spf13/pflag"
)

// Snooty official Style documentation: https://www.mongodb.com/docs/meta/style-guide
//
//go:embed api_docs_long_text.txt
var atlasAPIDocsAdditionalLongText string

var additionalLongTexts = map[string]string{
        "atlas api": atlasAPIDocsAdditionalLongText,
}

func addAdditionalLongText(cmd *cobra.Command) {
        commandPath := cmd.CommandPath()
        if additionalLongText, found := additionalLongTexts[commandPath]; found && additionalLongText != "" {
                cmd.Long += "\n\n"
                cmd.Long += additionalLongText
        }
}

func isAPICommand(cmd *cobra.Command) bool {
        return regexp.MustCompile("^atlas api( |$)").MatchString(cmd.CommandPath())
}

func setDisableAutoGenTag(cmd *cobra.Command) {
        cmd.DisableAutoGenTag = true
}

func markAPICommands(cmd *cobra.Command) {
        if cmd.CommandPath() == "atlas api" {
                return // Skip the root command
        }
        cmd.Long = cli.APICommandText + cmd.Long
}

func updateAPICommandDescription(cmd *cobra.Command) {
        if len(cmd.Commands()) > 0 {
                return
        }

        lines := strings.Split(cmd.Long, "\n")
        // Replace last line if it contains the extected text: "For more information and examples, see: <AtlasCLI docs url>"
        if strings.HasPrefix(lines[len(lines)-1], "For more information and examples, see: https://www.mongodb.com/docs/atlas/cli/current/command/") {
                lines = lines[:len(lines)-1]
                newLine := "For more information and examples, see the referenced API documentation linked above."
                lines = append(lines, newLine)
        }

        cmd.Long = strings.Join(lines, "\n")
}

func isFirstClassPlugin(command *cobra.Command) bool {
        for _, fcp := range pluginCmd.FirstClassPlugins {
                cmd := fcp.Commands
                for _, c := range cmd {
                        if command.Name() == c.Name {
                                return true
                        }
                }
        }
        return false
}

func removePluginCommands(cmd *cobra.Command) {
        if plugin.IsPluginCmd(cmd) && !isFirstClassPlugin(cmd) {
                cmd.Parent().RemoveCommand(cmd)
        }
}

func replaceFlagUsage(cmd *cobra.Command, f *pflag.Flag) {
        operationID := cmd.Annotations["operationId"]
        if operationID == "" {
                return
        }

        cmdMetadata, ok := metadata[operationID]
        if !ok {
                return
        }

        paramMetadata, ok := cmdMetadata.Parameters[f.Name]
        if !ok {
                return
        }
        // Snooty does not support the string "|---|---|---|---|" that we use in some API field description to generate a table.
        // Snooty error: ERROR(): Substitution reference could not be replaced: "|---|"
        usage := strings.ReplaceAll(paramMetadata.Usage, "|---|---|---|---|", "")

        // Snooty error: ERROR() Malformed external link Did you mean: ` <database>.<collection>`
        usage = strings.ReplaceAll(usage, "`<database>.<collection>`", "``<database>.<collection>``")
        f.Usage = usage
}

func sortedKeys[K cmp.Ordered, V any](m map[K]V) []K {
        keys := make([]K, 0, len(m))
        for key := range m {
                keys = append(keys, key)
        }
        slices.Sort(keys)
        return keys
}

func countExamples(examples map[string][]metadatatypes.Example) int {
        count := 0
        for _, exs := range examples {
                count += len(exs)
        }
        return count
}

func buildExamples(cmd *cobra.Command, examples map[string][]metadatatypes.Example) (string, error) { //nolint:gocyclo // cyclomatic complexity is high, but the code is readable and only used for documentation generation
        if len(examples) == 0 {
                return "", nil
        }

        var sb strings.Builder
        sb.WriteString(`Examples
--------

`)

        tabs := countExamples(examples) != 1
        if tabs {
                sb.WriteString(`.. tabs::

`)
        }

        exampleIdx := 0
        for _, version := range sortedKeys(examples) {
                for _, ex := range examples[version] {
                        source := strings.ToLower(strings.ReplaceAll(ex.Source, " ", "_"))
                        if ex.Source == "-" {
                                source = "default"
                        }

                        if tabs {
                                sb.WriteString("   .. tab:: ")
                                if ex.Name == "" {
                                        sb.WriteString("Example")
                                        if exampleIdx > 0 {
                                                sb.WriteString(" ")
                                                sb.WriteString(strconv.Itoa(exampleIdx))
                                        }
                                        exampleIdx++
                                } else {
                                        sb.WriteString(ex.Name)
                                }
                                sb.WriteString("\n      :tabid: ")
                                sb.WriteString(version)
                                sb.WriteString("_")
                                sb.WriteString(source)
                                sb.WriteString("\n\n")
                        }

                        if ex.Value != "" {
                                if tabs {
                                        sb.WriteString("      ")
                                }
                                sb.WriteString(ex.Description + "\n\n")

                                if tabs {
                                        sb.WriteString("      ")
                                }
                                sb.WriteString("Create the file below and save it as ``payload.json``\n\n")

                                includePayloadFileName := fmt.Sprintf("%s-%s-%s-payload.json", strings.ReplaceAll(cmd.CommandPath(), " ", "-"), version, source)
                                const permissions = 0600
                                err := os.WriteFile(fmt.Sprintf("%s/%s", includesLocalPath, includePayloadFileName), []byte(ex.Value), permissions)
                                if err != nil {
                                        return "", fmt.Errorf("failed to write payload file %s: %w", includePayloadFileName, err)
                                }

                                if tabs {
                                        sb.WriteString("      ")
                                }
                                sb.WriteString(fmt.Sprintf("   .. literalinclude:: %s/%s\n", includesImportPath, includePayloadFileName))
                                if tabs {
                                        sb.WriteString("      ")
                                }
                                sb.WriteString("      :language: shell\n")
                                if tabs {
                                        sb.WriteString("      ")
                                }
                                sb.WriteString("After creating ``payload.json``, run the command below in the same directory.\n\n")
                        } else if tabs {
                                sb.WriteString("      ")
                        }

                        var cmdSB strings.Builder

                        cmdSB.WriteString(cmd.CommandPath())
                        cmdSB.WriteString(" --version " + version)
                        for _, flagName := range sortedKeys(ex.Flags) {
                                cmdSB.WriteString(" --" + flagName + " " + ex.Flags[flagName])
                        }
                        cmdSB.WriteString("\n")

                        includeCommandFileName := fmt.Sprintf("%s-%s-%s.sh", strings.ReplaceAll(cmd.CommandPath(), " ", "-"), version, source)
                        const permissions = 0600
                        err := os.WriteFile(fmt.Sprintf("%s/%s", includesLocalPath, includeCommandFileName), []byte(cmdSB.String()), permissions)
                        if err != nil {
                                return "", fmt.Errorf("failed to write file %s: %w", includeCommandFileName, err)
                        }

                        if tabs {
                                sb.WriteString("      ")
                        }
                        sb.WriteString(fmt.Sprintf(".. literalinclude:: %s/%s\n", includesImportPath, includeCommandFileName))
                        if tabs {
                                sb.WriteString("      ")
                        }
                        sb.WriteString("   :language: shell\n")
                }
        }

        return sb.String(), nil
}

func updateExamples(cmd *cobra.Command) error {
        operationID := cmd.Annotations["operationId"]
        if operationID == "" {
                return nil
        }

        cmdMetadata, ok := metadata[operationID]
        if !ok || cmdMetadata.Examples == nil {
                return nil
        }

        var err error
        cmd.Example, err = buildExamples(cmd, cmdMetadata.Examples)

        return err
}

func removeCommandsWithOnlyPrivatePreview(cmd *cobra.Command) {
        operationID := cmd.Annotations["operationId"]
        if operationID == "" {
                return
        }

        cmdMetadata, ok := metadata[operationID]
        if ok && cmdMetadata.OnlyPrivatePreview {
                cmd.Parent().RemoveCommand(cmd)
        }
}

func applyTransformations(cmd *cobra.Command) error {
        setDisableAutoGenTag(cmd)
        removePluginCommands(cmd)
        addAdditionalLongText(cmd)

        if isAPICommand(cmd) {
                removeCommandsWithOnlyPrivatePreview(cmd)
                markAPICommands(cmd)
                updateAPICommandDescription(cmd)
                if err := updateExamples(cmd); err != nil {
                        return err
                }
        }

        cmd.Flags().VisitAll(func(f *pflag.Flag) {
                replaceFlagUsage(cmd, f)
        })

        for _, subCmd := range cmd.Commands() {
                if err := applyTransformations(subCmd); err != nil {
                        return err
                }
        }

        return nil
}

1	// Copyright 2025 MongoDB Inc
2	//
3	// Licensed under the Apache License, Version 2.0 (the "License");
4	// you may not use this file except in compliance with the License.
5	// You may obtain a copy of the License at
6	//
7	// http://www.apache.org/licenses/LICENSE-2.0
8	//
9	// Unless required by applicable law or agreed to in writing, software
10	// distributed under the License is distributed on an "AS IS" BASIS,
11	// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12	// See the License for the specific language governing permissions and
13	// limitations under the License.
14
15	package main
16
17	import (
18	"cmp"
19	_ "embed"
20	"fmt"
21	"os"
22	"regexp"
23	"slices"
24	"strconv"
25	"strings"
26
27	"github.com/mongodb/mongodb-atlas-cli/atlascli/internal/cli"
28	pluginCmd "github.com/mongodb/mongodb-atlas-cli/atlascli/internal/cli/plugin"
29	"github.com/mongodb/mongodb-atlas-cli/atlascli/internal/plugin"
30	"github.com/mongodb/mongodb-atlas-cli/atlascli/tools/internal/metadatatypes"
31	"github.com/spf13/cobra"
32	"github.com/spf13/pflag"
33	)
34
35	// Snooty official Style documentation: https://www.mongodb.com/docs/meta/style-guide
36	//
37	//go:embed api_docs_long_text.txt
38	var atlasAPIDocsAdditionalLongText string
39
40	var additionalLongTexts = map[string]string{
41	"atlas api": atlasAPIDocsAdditionalLongText,
42	}
43
44	func addAdditionalLongText(cmd *cobra.Command) {	×
45	commandPath := cmd.CommandPath()	×
46	if additionalLongText, found := additionalLongTexts[commandPath]; found && additionalLongText != "" {	×
47	cmd.Long += "\n\n"	×
48	cmd.Long += additionalLongText	×
49	}	×
50	}
51
52	func isAPICommand(cmd *cobra.Command) bool {	×
53	return regexp.MustCompile("^atlas api( \|$)").MatchString(cmd.CommandPath())	×
54	}	×
55
56	func setDisableAutoGenTag(cmd *cobra.Command) {	×
57	cmd.DisableAutoGenTag = true	×
58	}	×
59
60	func markAPICommands(cmd *cobra.Command) {	×
61	if cmd.CommandPath() == "atlas api" {	×
62	return // Skip the root command	×
63	}	×
64	cmd.Long = cli.APICommandText + cmd.Long	×
65	}
66
67	func updateAPICommandDescription(cmd *cobra.Command) {	×
68	if len(cmd.Commands()) > 0 {	×
69	return	×
70	}	×
71
72	lines := strings.Split(cmd.Long, "\n")	×
73	// Replace last line if it contains the extected text: "For more information and examples, see: <AtlasCLI docs url>"	×
74	if strings.HasPrefix(lines[len(lines)-1], "For more information and examples, see: https://www.mongodb.com/docs/atlas/cli/current/command/") {	×
75	lines = lines[:len(lines)-1]	×
76	newLine := "For more information and examples, see the referenced API documentation linked above."	×
77	lines = append(lines, newLine)	×
78	}	×
79
80	cmd.Long = strings.Join(lines, "\n")	×
81	}
82
83	func isFirstClassPlugin(command *cobra.Command) bool {	×
84	for _, fcp := range pluginCmd.FirstClassPlugins {	×
85	cmd := fcp.Commands	×
86	for _, c := range cmd {	×
87	if command.Name() == c.Name {	×
88	return true	×
89	}	×
90	}
91	}
92	return false	×
93	}
94
95	func removePluginCommands(cmd *cobra.Command) {	×
96	if plugin.IsPluginCmd(cmd) && !isFirstClassPlugin(cmd) {	×
97	cmd.Parent().RemoveCommand(cmd)	×
98	}	×
99	}
100
101	func replaceFlagUsage(cmd cobra.Command, f pflag.Flag) {	×
102	operationID := cmd.Annotations["operationId"]	×
103	if operationID == "" {	×
104	return	×
105	}	×
106
107	cmdMetadata, ok := metadata[operationID]	×
108	if !ok {	×
109	return	×
110	}	×
111
112	paramMetadata, ok := cmdMetadata.Parameters[f.Name]	×
113	if !ok {	×
114	return	×
115	}	×
116	// Snooty does not support the string "\|---\|---\|---\|---\|" that we use in some API field description to generate a table.
117	// Snooty error: ERROR(): Substitution reference could not be replaced: "\|---\|"
118	usage := strings.ReplaceAll(paramMetadata.Usage, "\|---\|---\|---\|---\|", "")	×
119		×
120	// Snooty error: ERROR() Malformed external link Did you mean: ` <database>.<collection>`	×
121	usage = strings.ReplaceAll(usage, "`<database>.<collection>`", "``<database>.<collection>``")	×
122	f.Usage = usage	×
123	}
124
125	func sortedKeys[K cmp.Ordered, V any](m map[K]V) []K {	×
126	keys := make([]K, 0, len(m))	×
127	for key := range m {	×
128	keys = append(keys, key)	×
129	}	×
130	slices.Sort(keys)	×
131	return keys	×
132	}
133
134	func countExamples(examples map[string][]metadatatypes.Example) int {	×
135	count := 0	×
136	for _, exs := range examples {	×
137	count += len(exs)	×
138	}	×
139	return count	×
140	}
141
142	func buildExamples(cmd *cobra.Command, examples map[string][]metadatatypes.Example) (string, error) { //nolint:gocyclo // cyclomatic complexity is high, but the code is readable and only used for documentation generation	×
143	if len(examples) == 0 {	×
144	return "", nil	×
145	}	×
146
147	var sb strings.Builder	×
148	sb.WriteString(`Examples	×
149	--------	×
150		×
151	`)	×
152		×
153	tabs := countExamples(examples) != 1	×
154	if tabs {	×
155	sb.WriteString(`.. tabs::	×
156		×
157	`)	×
158	}	×
159
160	exampleIdx := 0	×
161	for _, version := range sortedKeys(examples) {	×
162	for _, ex := range examples[version] {	×
163	source := strings.ToLower(strings.ReplaceAll(ex.Source, " ", "_"))	×
164	if ex.Source == "-" {	×
165	source = "default"	×
166	}	×
167
168	if tabs {	×
169	sb.WriteString(" .. tab:: ")	×
170	if ex.Name == "" {	×
171	sb.WriteString("Example")	×
172	if exampleIdx > 0 {	×
173	sb.WriteString(" ")	×
174	sb.WriteString(strconv.Itoa(exampleIdx))	×
175	}	×
176	exampleIdx++	×
177	} else {	×
178	sb.WriteString(ex.Name)	×
179	}	×
180	sb.WriteString("\n :tabid: ")	×
181	sb.WriteString(version)	×
182	sb.WriteString("_")	×
183	sb.WriteString(source)	×
184	sb.WriteString("\n\n")	×
185	}
186
187	if ex.Value != "" {	×
188	if tabs {	×
189	sb.WriteString(" ")	×
190	}	×
191	sb.WriteString(ex.Description + "\n\n")	×
192		×
193	if tabs {	×
194	sb.WriteString(" ")	×
195	}	×
196	sb.WriteString("Create the file below and save it as ``payload.json``\n\n")	×
197		×
198	includePayloadFileName := fmt.Sprintf("%s-%s-%s-payload.json", strings.ReplaceAll(cmd.CommandPath(), " ", "-"), version, source)	×
199	const permissions = 0600	×
200	err := os.WriteFile(fmt.Sprintf("%s/%s", includesLocalPath, includePayloadFileName), []byte(ex.Value), permissions)	×
201	if err != nil {	×
202	return "", fmt.Errorf("failed to write payload file %s: %w", includePayloadFileName, err)	×
203	}	×
204
205	if tabs {	×
206	sb.WriteString(" ")	×
207	}	×
208	sb.WriteString(fmt.Sprintf(" .. literalinclude:: %s/%s\n", includesImportPath, includePayloadFileName))	×
209	if tabs {	×
210	sb.WriteString(" ")	×
211	}	×
212	sb.WriteString(" :language: shell\n")	×
213	if tabs {	×
214	sb.WriteString(" ")	×
215	}	×
216	sb.WriteString("After creating ``payload.json``, run the command below in the same directory.\n\n")	×
217	} else if tabs {	×
218	sb.WriteString(" ")	×
219	}	×
220
221	var cmdSB strings.Builder	×
222		×
223	cmdSB.WriteString(cmd.CommandPath())	×
224	cmdSB.WriteString(" --version " + version)	×
225	for _, flagName := range sortedKeys(ex.Flags) {	×
226	cmdSB.WriteString(" --" + flagName + " " + ex.Flags[flagName])	×
227	}	×
228	cmdSB.WriteString("\n")	×
229		×
230	includeCommandFileName := fmt.Sprintf("%s-%s-%s.sh", strings.ReplaceAll(cmd.CommandPath(), " ", "-"), version, source)	×
231	const permissions = 0600	×
232	err := os.WriteFile(fmt.Sprintf("%s/%s", includesLocalPath, includeCommandFileName), []byte(cmdSB.String()), permissions)	×
233	if err != nil {	×
234	return "", fmt.Errorf("failed to write file %s: %w", includeCommandFileName, err)	×
235	}	×
236
237	if tabs {	×
238	sb.WriteString(" ")	×
239	}	×
240	sb.WriteString(fmt.Sprintf(".. literalinclude:: %s/%s\n", includesImportPath, includeCommandFileName))	×
241	if tabs {	×
242	sb.WriteString(" ")	×
243	}	×
244	sb.WriteString(" :language: shell\n")	×
245	}
246	}
247
248	return sb.String(), nil	×
249	}
250
251	func updateExamples(cmd *cobra.Command) error {	×
252	operationID := cmd.Annotations["operationId"]	×
253	if operationID == "" {	×
254	return nil	×
255	}	×
256
257	cmdMetadata, ok := metadata[operationID]	×
258	if !ok \|\| cmdMetadata.Examples == nil {	×
259	return nil	×
260	}	×
261
262	var err error	×
263	cmd.Example, err = buildExamples(cmd, cmdMetadata.Examples)	×
264		×
265	return err	×
266	}
267
268	func removeCommandsWithOnlyPrivatePreview(cmd *cobra.Command) {	×
269	operationID := cmd.Annotations["operationId"]	×
270	if operationID == "" {	×
271	return	×
272	}	×
273
274	cmdMetadata, ok := metadata[operationID]	×
275	if ok && cmdMetadata.OnlyPrivatePreview {	×
276	cmd.Parent().RemoveCommand(cmd)	×
277	}	×
278	}
279
280	func applyTransformations(cmd *cobra.Command) error {	×
281	setDisableAutoGenTag(cmd)	×
282	removePluginCommands(cmd)	×
283	addAdditionalLongText(cmd)	×
284		×
285	if isAPICommand(cmd) {	×
286	removeCommandsWithOnlyPrivatePreview(cmd)	×
287	markAPICommands(cmd)	×
288	updateAPICommandDescription(cmd)	×
289	if err := updateExamples(cmd); err != nil {	×
290	return err	×
291	}	×
292	}
293
294	cmd.Flags().VisitAll(func(f *pflag.Flag) {	×
295	replaceFlagUsage(cmd, f)	×
296	})	×
297
298	for _, subCmd := range cmd.Commands() {	×
299	if err := applyTransformations(subCmd); err != nil {	×
300	return err	×
301	}	×
302	}
303
304	return nil	×
305	}

mongodb / mongodb-atlas-cli / 18284275304

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous