feat: add unified --json output format for all commands (#134)

Add a global --json flag that produces machine-readable JSON output from
any SHOW or DESCRIBE command, eliminating truncation and table parsing
overhead for programmatic/AI consumption.

- Add OutputFormat type, TableResult struct, and writeResult/writeDescribeJSON
  helpers in mdl/executor/format.go
- Convert ~30 SHOW handlers to use writeResult() instead of inline fprintf
- Wrap all DESCRIBE handlers with writeDescribeJSON() at the dispatch level
- Wire --json persistent flag in CLI, with resolveFormat() for commands
  that already have --format flags (search, lint, check, report, describe)
- Add format_test.go with table, JSON, empty, and describe passthrough tests
- Update MDL_QUICK_REFERENCE.md with --json usage

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ako

cmd/mxcli/cmd_check.go

@@ -45,7 +45,7 @@ Examples:
 		filePath := args[0]
 		projectPath, _ := cmd.Flags().GetString("project")
 		checkRefs, _ := cmd.Flags().GetBool("references")
-		format, _ := cmd.Flags().GetString("format")
+		format := resolveFormat(cmd, "text")
 
 		// Read the file
 		content, err := os.ReadFile(filePath)

cmd/mxcli/cmd_describe.go

@@ -7,6 +7,7 @@ import (
 	"os"
 	"strings"
 
+	"github.com/mendixlabs/mxcli/mdl/executor"
 	"github.com/mendixlabs/mxcli/mdl/visitor"
 	"github.com/spf13/cobra"
 )
@@ -157,8 +158,11 @@ Example:
 			}
 		}
 
-		// Check for mermaid/elk format - bypass MDL parser and call directly
-		format, _ := cmd.Flags().GetString("format")
+		// Check for format overrides - bypass MDL parser for mermaid/elk, set executor for json
+		format := resolveFormat(cmd, "mdl")
+		if format == "json" {
+			exec.SetFormat(executor.FormatJSON)
+		}
 		typeArg := strings.Join(args[:len(args)-1], " ")
 		if format == "mermaid" {
 			if err := exec.DescribeMermaid(typeArg, name); err != nil {

cmd/mxcli/cmd_lint.go

@@ -79,7 +79,7 @@ Examples:
 `,
 	Run: func(cmd *cobra.Command, args []string) {
 		projectPath, _ := cmd.Flags().GetString("project")
-		format, _ := cmd.Flags().GetString("format")
+		format := resolveFormat(cmd, "text")
 		useColor, _ := cmd.Flags().GetBool("color")
 		listRules, _ := cmd.Flags().GetBool("list-rules")
 		excludeModules, _ := cmd.Flags().GetStringSlice("exclude")

cmd/mxcli/cmd_query.go

@@ -226,7 +226,7 @@ Examples:
 	Args: cobra.ExactArgs(1),
 	Run: func(cmd *cobra.Command, args []string) {
 		projectPath, _ := cmd.Flags().GetString("project")
-		format, _ := cmd.Flags().GetString("format")
+		format := resolveFormat(cmd, "table")
 		quiet, _ := cmd.Flags().GetBool("quiet")
 
 		if projectPath == "" {

cmd/mxcli/cmd_report.go

@@ -38,7 +38,7 @@ Examples:
 `,
 	Run: func(cmd *cobra.Command, args []string) {
 		projectPath, _ := cmd.Flags().GetString("project")
-		format, _ := cmd.Flags().GetString("format")
+		format := resolveFormat(cmd, "markdown")
 		outputPath, _ := cmd.Flags().GetString("output")
 		excludeModules, _ := cmd.Flags().GetStringSlice("exclude")
 

cmd/mxcli/main.go

@@ -106,6 +106,7 @@ Examples:
 				fmt.Fprintf(os.Stderr, "Using project: %s\n", discovered)
 			}
 		}
+		globalJSONFlag, _ = cmd.Flags().GetBool("json")
 	},
 	Run: func(cmd *cobra.Command, args []string) {
 		// Get flags
@@ -171,12 +172,32 @@ Examples:
 	},
 }
 
+// globalJSONFlag is set by PersistentPreRun when --json is passed.
+var globalJSONFlag bool
+
+// resolveFormat returns the effective output format for a command.
+// If the global --json flag is set and the command has a --format flag, it returns "json".
+// Otherwise it returns the command's --format flag value (or the provided default).
+func resolveFormat(cmd *cobra.Command, defaultFormat string) string {
+	if globalJSONFlag {
+		return "json"
+	}
+	if cmd.Flags().Lookup("format") != nil {
+		f, _ := cmd.Flags().GetString("format")
+		return f
+	}
+	return defaultFormat
+}
+
 // newLoggedExecutor creates an executor with diagnostics logging attached.
 // The caller must call logger.Close() when done (safe on nil).
 func newLoggedExecutor(mode string) (*executor.Executor, *diaglog.Logger) {
 	logger := diaglog.Init(version, mode)
 	exec := executor.New(os.Stdout)
 	exec.SetLogger(logger)
+	if globalJSONFlag {
+		exec.SetFormat(executor.FormatJSON)
+	}
 	return exec, logger
 }
 
@@ -216,6 +237,7 @@ func init() {
 
 	// Global flags
 	rootCmd.PersistentFlags().StringP("project", "p", "", "Path to Mendix project (.mpr file)")
+	rootCmd.PersistentFlags().Bool("json", false, "Output in JSON format")
 	rootCmd.Flags().StringP("command", "c", "", "Execute MDL command(s) and exit")
 
 	// Check command flags
@@ -234,7 +256,7 @@ func init() {
 	diffLocalCmd.Flags().IntP("width", "w", 120, "Terminal width for side-by-side format")
 
 	// Describe command flags
-	describeCmd.Flags().StringP("format", "f", "mdl", "Output format: mdl, mermaid, elk")
+	describeCmd.Flags().StringP("format", "f", "mdl", "Output format: mdl, json, mermaid, elk")
 
 	// Search command flags
 	searchCmd.Flags().StringP("format", "f", "table", "Output format: table, names, json")

docs/01-project/MDL_QUICK_REFERENCE.md

@@ -764,6 +764,7 @@ Cross-reference commands require `REFRESH CATALOG FULL` to populate reference da
 |---------|--------|-------|
 | Interactive REPL | `mxcli` | Interactive MDL shell |
 | Execute command | `mxcli -p app.mpr -c "SHOW ENTITIES"` | Single command |
+| JSON output | `mxcli -p app.mpr -c "SHOW ENTITIES" --json` | JSON for any command |
 | Execute script | `mxcli exec script.mdl -p app.mpr` | Script file |
 | Check syntax | `mxcli check script.mdl` | Parse-only validation |
 | Check references | `mxcli check script.mdl -p app.mpr --references` | With reference validation |

mdl/executor/cmd_associations.go

@@ -272,7 +272,7 @@ func (e *Executor) showAssociations(moduleName string) error {
 		}
 	}
 
-	// Collect rows and calculate column widths
+	// Collect rows
 	type row struct {
 		qualifiedName string
 		module        string
@@ -284,42 +284,6 @@ func (e *Executor) showAssociations(moduleName string) error {
 		storage       string
 	}
 	var rows []row
-	qnWidth := len("Qualified Name")
-	modWidth := len("Module")
-	nameWidth := len("Name")
-	parentWidth := len("Parent")
-	childWidth := len("Child")
-	typeWidth := len("Type")
-	ownerWidth := len("Owner")
-	storageWidth := len("Storage")
-
-	addRow := func(qualifiedName, modName, assocName, parent, child string, assocType, owner, storage string) {
-		rows = append(rows, row{qualifiedName, modName, assocName, parent, child, assocType, owner, storage})
-		if len(qualifiedName) > qnWidth {
-			qnWidth = len(qualifiedName)
-		}
-		if len(modName) > modWidth {
-			modWidth = len(modName)
-		}
-		if len(assocName) > nameWidth {
-			nameWidth = len(assocName)
-		}
-		if len(parent) > parentWidth {
-			parentWidth = len(parent)
-		}
-		if len(child) > childWidth {
-			childWidth = len(child)
-		}
-		if len(assocType) > typeWidth {
-			typeWidth = len(assocType)
-		}
-		if len(owner) > ownerWidth {
-			ownerWidth = len(owner)
-		}
-		if len(storage) > storageWidth {
-			storageWidth = len(storage)
-		}
-	}
 
 	for _, dm := range domainModels {
 		modName := moduleNames[dm.ContainerID]
@@ -338,7 +302,7 @@ func (e *Executor) showAssociations(moduleName string) error {
 			if child == "" {
 				child = string(assoc.ChildID)
 			}
-			addRow(qualifiedName, modName, assoc.Name, parent, child, string(assoc.Type), string(assoc.Owner), string(assoc.StorageFormat))
+			rows = append(rows, row{qualifiedName, modName, assoc.Name, parent, child, string(assoc.Type), string(assoc.Owner), string(assoc.StorageFormat)})
 		}
 		// Cross-module associations
 		for _, ca := range dm.CrossAssociations {
@@ -347,7 +311,7 @@ func (e *Executor) showAssociations(moduleName string) error {
 			if parent == "" {
 				parent = string(ca.ParentID)
 			}
-			addRow(qualifiedName, modName, ca.Name, parent, ca.ChildRef, string(ca.Type), string(ca.Owner), string(ca.StorageFormat))
+			rows = append(rows, row{qualifiedName, modName, ca.Name, parent, ca.ChildRef, string(ca.Type), string(ca.Owner), string(ca.StorageFormat)})
 		}
 	}
 
@@ -356,21 +320,15 @@ func (e *Executor) showAssociations(moduleName string) error {
 		return strings.ToLower(rows[i].qualifiedName) < strings.ToLower(rows[j].qualifiedName)
 	})
 
-	// Markdown table with aligned columns
-	fmt.Fprintf(e.output, "| %-*s | %-*s | %-*s | %-*s | %-*s | %-*s | %-*s | %-*s |\n",
-		qnWidth, "Qualified Name", modWidth, "Module", nameWidth, "Name",
-		parentWidth, "Parent", childWidth, "Child", typeWidth, "Type", ownerWidth, "Owner", storageWidth, "Storage")
-	fmt.Fprintf(e.output, "|-%s-|-%s-|-%s-|-%s-|-%s-|-%s-|-%s-|-%s-|\n",
-		strings.Repeat("-", qnWidth), strings.Repeat("-", modWidth), strings.Repeat("-", nameWidth),
-		strings.Repeat("-", parentWidth), strings.Repeat("-", childWidth),
-		strings.Repeat("-", typeWidth), strings.Repeat("-", ownerWidth), strings.Repeat("-", storageWidth))
+	// Build TableResult
+	result := &TableResult{
+		Columns: []string{"Qualified Name", "Module", "Name", "Parent", "Child", "Type", "Owner", "Storage"},
+		Summary: fmt.Sprintf("(%d associations)", len(rows)),
+	}
 	for _, r := range rows {
-		fmt.Fprintf(e.output, "| %-*s | %-*s | %-*s | %-*s | %-*s | %-*s | %-*s | %-*s |\n",
-			qnWidth, r.qualifiedName, modWidth, r.module, nameWidth, r.name,
-			parentWidth, r.parent, childWidth, r.child, typeWidth, r.assocType, ownerWidth, r.owner, storageWidth, r.storage)
+		result.Rows = append(result.Rows, []any{r.qualifiedName, r.module, r.name, r.parent, r.child, r.assocType, r.owner, r.storage})
 	}
-	fmt.Fprintf(e.output, "\n(%d associations)\n", len(rows))
-	return nil
+	return e.writeResult(result)
 }
 
 // showAssociation handles SHOW ASSOCIATION command.

mdl/executor/cmd_businessevents.go

@@ -51,7 +51,6 @@ func (e *Executor) showBusinessEventServices(inModule string) error {
 		msgCount, publishCount, subscribeCount int
 	}
 	var rows []row
-	modWidth, qnWidth, nameWidth := len("Module"), len("QualifiedName"), len("Service")
 
 	for _, svc := range filtered {
 		modID := h.FindModuleID(svc.ContainerID)
@@ -73,32 +72,17 @@ func (e *Executor) showBusinessEventServices(inModule string) error {
 			}
 		}
 
-		if len(moduleName) > modWidth {
-			modWidth = len(moduleName)
-		}
-		if len(qn) > qnWidth {
-			qnWidth = len(qn)
-		}
-		if len(svc.Name) > nameWidth {
-			nameWidth = len(svc.Name)
-		}
 		rows = append(rows, r)
 	}
 
-	fmt.Fprintf(e.output, "| %-*s | %-*s | %-*s | %-10s | %-10s | %-10s |\n",
-		modWidth, "Module", qnWidth, "QualifiedName", nameWidth, "Service", "Messages", "Publish", "Subscribe")
-	fmt.Fprintf(e.output, "|-%s-|-%s-|-%s-|-%s-|-%s-|-%s-|\n",
-		strings.Repeat("-", modWidth), strings.Repeat("-", qnWidth), strings.Repeat("-", nameWidth),
-		strings.Repeat("-", 10), strings.Repeat("-", 10), strings.Repeat("-", 10))
-
+	result := &TableResult{
+		Columns: []string{"Module", "QualifiedName", "Service", "Messages", "Publish", "Subscribe"},
+		Summary: fmt.Sprintf("(%d business event services)", len(filtered)),
+	}
 	for _, r := range rows {
-		fmt.Fprintf(e.output, "| %-*s | %-*s | %-*s | %10d | %10d | %10d |\n",
-			modWidth, r.module, qnWidth, r.qualifiedName, nameWidth, r.name,
-			r.msgCount, r.publishCount, r.subscribeCount)
+		result.Rows = append(result.Rows, []any{r.module, r.qualifiedName, r.name, r.msgCount, r.publishCount, r.subscribeCount})
 	}
-
-	fmt.Fprintf(e.output, "\n(%d business event services)\n", len(filtered))
-	return nil
+	return e.writeResult(result)
 }
 
 // showBusinessEventClients displays a table of all business event client documents.
@@ -128,10 +112,6 @@ func (e *Executor) showBusinessEvents(inModule string) error {
 		attrs                               int
 	}
 	var rows []row
-	svcWidth := len("Service")
-	msgWidth := len("Message")
-	opWidth := len("Operation")
-	entityWidth := len("Entity")
 
 	for _, svc := range services {
 		modID := h.FindModuleID(svc.ContainerID)
@@ -157,26 +137,13 @@ func (e *Executor) showBusinessEvents(inModule string) error {
 						opStr = strings.ToUpper(op.Operation)
 						entityStr = op.Entity
 					}
-					r := row{
+					rows = append(rows, row{
 						service:   svcQN,
 						message:   msg.MessageName,
 						operation: opStr,
 						entity:    entityStr,
 						attrs:     len(msg.Attributes),
-					}
-					if len(svcQN) > svcWidth {
-						svcWidth = len(svcQN)
-					}
-					if len(msg.MessageName) > msgWidth {
-						msgWidth = len(msg.MessageName)
-					}
-					if len(opStr) > opWidth {
-						opWidth = len(opStr)
-					}
-					if len(entityStr) > entityWidth {
-						entityWidth = len(entityStr)
-					}
-					rows = append(rows, r)
+					})
 				}
 			}
 		}
@@ -191,20 +158,14 @@ func (e *Executor) showBusinessEvents(inModule string) error {
 		return nil
 	}
 
-	fmt.Fprintf(e.output, "| %-*s | %-*s | %-*s | %-*s | %-10s |\n",
-		svcWidth, "Service", msgWidth, "Message", opWidth, "Operation", entityWidth, "Entity", "Attributes")
-	fmt.Fprintf(e.output, "|-%s-|-%s-|-%s-|-%s-|-%s-|\n",
-		strings.Repeat("-", svcWidth), strings.Repeat("-", msgWidth),
-		strings.Repeat("-", opWidth), strings.Repeat("-", entityWidth), strings.Repeat("-", 10))
-
+	result := &TableResult{
+		Columns: []string{"Service", "Message", "Operation", "Entity", "Attributes"},
+		Summary: fmt.Sprintf("(%d business events)", len(rows)),
+	}
 	for _, r := range rows {
-		fmt.Fprintf(e.output, "| %-*s | %-*s | %-*s | %-*s | %10d |\n",
-			svcWidth, r.service, msgWidth, r.message, opWidth, r.operation,
-			entityWidth, r.entity, r.attrs)
+		result.Rows = append(result.Rows, []any{r.service, r.message, r.operation, r.entity, r.attrs})
 	}
-
-	fmt.Fprintf(e.output, "\n(%d business events)\n", len(rows))
-	return nil
+	return e.writeResult(result)
 }
 
 // describeBusinessEventService outputs the full MDL description of a business event service.