[v18] Sort generated CLI docs flag and argument tables

lib/utils/usage_docs.go

@@ -28,19 +28,36 @@ import (
 	"io/fs"
 	"os"
 	"path/filepath"
+	"regexp"
 	"slices"
 	"strings"
 
 	"github.com/alecthomas/kingpin/v2"
 	"gopkg.in/yaml.v3"
 )
 
+var nonLetters = regexp.MustCompile(`\W`)
+
+// lowerWordChars returns only the word characters (\w) from in, in lowercase,
+// so we can sort short-format flags alongside long-format flags in tables.
+func lowerWordChars(in string) string {
+	return strings.ToLower(nonLetters.ReplaceAllString(in, ""))
+}
+
 // formatThreeColMarkdownTable formats the provided row data into a three-column
-// Markdown table, minus the header.
+// Markdown table, minus the header, sorted lexicographically by the values of
+// the first column.
 func formatThreeColMarkdownTable(rows [][3]string) string {
-	var buf bytes.Buffer
+	newRows := slices.Clone(rows)
+	slices.SortFunc(newRows, func(a, b [3]string) int {
+		return strings.Compare(
+			lowerWordChars(a[0]),
+			lowerWordChars(b[0]),
+		)
+	})
 
-	for _, r := range rows {
+	var buf bytes.Buffer
+	for _, r := range newRows {
 		fmt.Fprintf(&buf, "\n|%v|%v|%v|", r[0], r[1], r[2])
 	}
 	return buf.String()