docs: write messages as single json document (#2519)

Closes #2498

Author: woylie

README.md

@@ -512,6 +512,15 @@ Some tests use fixtures. If payloads change, you can update them with:
 make test-update-snapshots
 ```
 
+This will only update the snapshots of the short tests. To update all snapshots,
+run:
+
+```bash
+UPDATE_SNAPSHOTS=true go test -p 4 -tags sqlite ./...
+```
+
+You can also run this command from a sub folder.
+
 ##### End-to-End Tests
 
 We use [Cypress](https://www.cypress.io) to run our e2e tests.

cmd/clidoc/main.go

@@ -136,11 +136,18 @@ func main() {
 		os.Exit(1)
 	}
 
-	if err := writeMessages(filepath.Join(os.Args[2], "concepts/ui-user-interface.mdx")); err != nil {
+	sortedMessages := sortMessages()
+
+	if err := writeMessages(filepath.Join(os.Args[2], "concepts/ui-user-interface.mdx"), sortedMessages); err != nil {
 		_, _ = fmt.Fprintf(os.Stderr, "Unable to generate message table: %+v\n", err)
 		os.Exit(1)
 	}
 
+	if err := writeMessagesJson(filepath.Join(os.Args[2], "concepts/messages.json"), sortedMessages); err != nil {
+		_, _ = fmt.Fprintf(os.Stderr, "Unable to generate messages.json: %+v\n", err)
+		os.Exit(1)
+	}
+
 	fmt.Println("All files have been generated and updated.")
 }
 
@@ -154,12 +161,7 @@ func codeEncode(in interface{}) string {
 	return string(out)
 }
 
-func writeMessages(path string) error {
-	content, err := os.ReadFile(path)
-	if err != nil {
-		return err
-	}
-
+func sortMessages() []*text.Message {
 	var toSort []*text.Message
 	for _, m := range messages {
 		toSort = append(toSort, m)
@@ -172,8 +174,17 @@ func writeMessages(path string) error {
 		return toSort[i].ID < toSort[j].ID
 	})
 
+	return toSort
+}
+
+func writeMessages(path string, sortedMessages []*text.Message) error {
+	content, err := os.ReadFile(path)
+	if err != nil {
+		return err
+	}
+
 	var w bytes.Buffer
-	for _, m := range toSort {
+	for _, m := range sortedMessages {
 		w.WriteString(fmt.Sprintf(`###### %s (%d)
 
 %s
@@ -200,6 +211,25 @@ func writeMessages(path string) error {
 	return nil
 }
 
+func writeMessagesJson(path string, sortedMessages []*text.Message) error {
+	result := codeEncode(sortedMessages)
+
+	f, err := os.OpenFile(path, os.O_RDWR|os.O_CREATE|os.O_TRUNC, 0755)
+	if err != nil {
+		return err
+	}
+
+	if _, err := f.WriteString(result); err != nil {
+		return err
+	}
+
+	if err := f.Close(); err != nil {
+		return err
+	}
+
+	return nil
+}
+
 func validateAllMessages(path string) error {
 	type message struct {
 		ID, Name string