feature: Implement FORMAT and WIDTH in EXPLAIN/EXPLAIN ANALYZE (#229)

* Implement compact and wrap using spannerplan

* Update spannerplan to include latest changes

* Bump spanemuboost to v0.2.10

Author: apstndb

README.md

@@ -15,6 +15,7 @@ There are differences between spanner-mycli and spanner-cli that include not onl
 
 * [More concise `EXPLAIN` and `EXPLAIN ANALYZE` output](#more-concise-format-of-explain-and-explain-analyze), making efficient use of limited display space.
   * Optimized for narrower terminals and code blocks.
+  * Compact format and query plan wrapping to fit into  more limited space.
 * Respects my minor use cases
   * Protocol Buffers support as `SHOW LOCAL PROTO`, `SHOW REMOTE PROTO`, `SYNC PROTO BUNDLE` statement
   * Can use embedded emulator (`--embedded-emulator`)
@@ -1857,9 +1858,9 @@ spanner-mycli
 
 ```text
 +----+-----------------------------------------------------------------------------+------+-------+---------------+
-| ID | Query_Execution_Plan <execution_method> (metadata, ...)                     | Rows | Exec. | Total Latency |
+| ID | Operator <execution_method> (metadata, ...)                                 | Rows | Exec. | Total Latency |
 +----+-----------------------------------------------------------------------------+------+-------+---------------+
-|  0 | Distributed Union on Singers <Row> (split_ranges_aligned: false)            |    0 |     1 |    7.58 msecs |
+|  0 | Distributed Union on Singers <Row>                                          |    0 |     1 |    7.58 msecs |
 |  1 | +- Local Distributed Union <Row>                                            |    0 |     3 |    0.78 msecs |
 |  2 |    +- Serialize Result <Row>                                                |    0 |     3 |    0.75 msecs |
 | *3 |       +- Filter Scan <Row> (seekable_key_size: 0)                           |      |       |               |
@@ -1871,11 +1872,84 @@ Predicates(identified by ID):
 ```
 
 - `execution_method: {Row|Batch}` metadata is simply displayed as `<Row>` or `<Batch>` after display name of operator.
-- Target metadata, `distribution_table: <target>` and `scan_target: <target>`, are displayed as `on <target>` after display name of operator.
-- `Full scan: true` is shortened as `Full scan`.
+- Target metadata, `distribution_table: <target>`, `scan_target: <target>`, and `table: <target>` are displayed as `on <target>` after display name of operator.
+- Some metadata with boolean value is printed as label.
+  - For example, `Full scan: true` and `split_ranges_aligned: true` are shortened as `Full scan` and `split_ranges_aligned`, and they are not printed if the value is `false`.
 - Column names of `EXPLAIN ANALYZE` are shorter than before.
 
-Note: These changes except column names can be controlled using `SET CLI_SPANNER_CLI_COMPATIBLE_PLAN=TRUE`.
+Note: These changes except column names can be controlled using `EXPLAIN [ANALYZE] FORMAT=TRADITIONAL` or `SET CLI_EXPLAIN_FORMAT=TRADITIONAL`.
+
+To support more limited width environment, there are further options.
+#### Compact format
+
+`FORMAT=COMPACT` option removes characters that use width for readability, as long as it doesn't compromise information.
+
+- Whitespace is generally not inserted.
+- The characters used for the tree will only be one character wide per level.
+
+```
+spanner> EXPLAIN FORMAT=COMPACT
+         SELECT * FROM Singers
+         JOIN Albums USING (SingerId)
+         WHERE LastName LIKE "%son";
++-----+-------------------------------------------------------------------+
+| ID  | Operator <execution_method> (metadata, ...)                       |
++-----+-------------------------------------------------------------------+
+|   0 | Distributed Union on Albums<Row>                                  |
+|   1 | +Serialize Result<Row>                                            |
+|   2 |  +Cross Apply<Row>                                                |
+|   3 |   +[Input]Distributed Union on Singers<Row>                       |
+|   4 |   |+Local Distributed Union<Row>                                  |
+|  *5 |   | +Filter Scan<Row>(seekable_key_size:0)                        |
+|   6 |   |  +Table Scan on Singers<Row>(Full scan,scan_method:Automatic) |
+|  17 |   +[Map]Local Distributed Union<Row>                              |
+|  18 |    +Filter Scan<Row>(seekable_key_size:0)                         |
+| *19 |     +Table Scan on Albums<Row>(scan_method:Row)                   |
++-----+-------------------------------------------------------------------+
+Predicates(identified by ID):
+  5: Residual Condition: ($LastName LIKE '%son')
+ 19: Seek Condition: ($SingerId_1 = $SingerId)
+```
+
+#### Wrapped plans
+
+When you want to adjust the width, such as when displaying an execution plan on media where horizontal scrolling is not possible and content might be truncated or wrapped,
+you can use the `WIDTH=<width>` option to wrap the content of the `Operator` column at the specified width.
+
+For example, in the illustration below, by setting the width of the ASCII tree drawn in the Operator column to 39 characters,
+the entire output, including the ASCII table, can fit within 80 characters.
+
+```
+spanner> EXPLAIN ANALYZE FORMAT=COMPACT WIDTH=39
+         SELECT * FROM Singers
+         JOIN Albums USING (SingerId)
+         WHERE LastName LIKE "%r";
++-----+-----------------------------------------+------+-------+---------------+
+| ID  | Operator                                | Rows | Exec. | Total Latency |
++-----+-----------------------------------------+------+-------+---------------+
+|   0 | Distributed Union on Albums<Row>        |    1 |     1 |    3.82 msecs |
+|   1 | +Serialize Result<Row>                  |    1 |     3 |     2.2 msecs |
+|   2 |  +Cross Apply<Row>                      |    1 |     3 |    2.19 msecs |
+|   3 |   +[Input]Distributed Union on Singers< |    1 |     3 |    2.16 msecs |
+|     |   |Row>                                 |      |       |               |
+|   4 |   |+Local Distributed Union<Row>        |    1 |     4 |    0.25 msecs |
+|  *5 |   | +Filter Scan<Row>(seekable_key_size |      |       |               |
+|     |   |  :0)                                |      |       |               |
+|   6 |   |  +Table Scan on Singers<Row>(Full s |    1 |     4 |    0.21 msecs |
+|     |   |   can,scan_method:Automatic)        |      |       |               |
+|  17 |   +[Map]Local Distributed Union<Row>    |    1 |     1 |    0.03 msecs |
+|  18 |    +Filter Scan<Row>(seekable_key_size: |      |       |               |
+|     |     0)                                  |      |       |               |
+| *19 |     +Table Scan on Albums<Row>(scan_met |    1 |     1 |    0.03 msecs |
+|     |      hod:Row)                           |      |       |               |
++-----+-----------------------------------------+------+-------+---------------+
+Predicates(identified by ID):
+  5: Residual Condition: ($LastName LIKE '%r')
+ 19: Seek Condition: ($SingerId_1 = $SingerId)
+```
+
+Note: Since the widths of columns other than the Operator column are not deterministic, there may be cases where the output does not fit within 80 characters even with the same settings, such as when the number of Rows is large.
+
 
 ### Tab character handling
 

cli_test.go

@@ -648,9 +648,9 @@ func TestRenderPlanTree(t *testing.T) {
 			},
 			resultSetStats: lo.Must(protojsonUnmarshal[sppb.ResultSetStats, *sppb.ResultSetStats](dcaStatsJSON)),
 			want: `+-----+-------------------------------------------------------------------------------------------+------+---------+----------+
-| ID  | Query_Execution_Plan <execution_method> (metadata, ...)                                   | Rows | Scanned | Filtered |
+| ID  | Operator <execution_method> (metadata, ...)                                               | Rows | Scanned | Filtered |
 +-----+-------------------------------------------------------------------------------------------+------+---------+----------+
-|   0 | Distributed Union on AlbumsByAlbumTitle <Row> (split_ranges_aligned: false)               |   33 |         |          |
+|   0 | Distributed Union on AlbumsByAlbumTitle <Row>                                             |   33 |         |          |
 |  *1 | +- Distributed Cross Apply <Row>                                                          |   33 |         |          |
 |   2 |    +- [Input] Create Batch <Row>                                                          |      |         |          |
 |   3 |    |  +- Local Distributed Union <Row>                                                    |    7 |         |          |
@@ -679,7 +679,7 @@ optimizer statistics: auto_20250421_21_29_41UTC
 	for _, tcase := range tcases {
 		t.Run(tcase.desc, func(t *testing.T) {
 			stats := protostruct.DecodeToMap(tcase.resultSetStats.QueryStats)
-			result, err := generateExplainAnalyzeResult(tcase.sysVars, tcase.resultSetStats.QueryPlan, stats)
+			result, err := generateExplainAnalyzeResult(tcase.sysVars, tcase.resultSetStats.QueryPlan, stats, explainFormatUnspecified, 0)
 			if err != nil {
 				t.Errorf("shouldn't fail, but: %v", err)
 			}

client_side_statement_def.go

@@ -291,24 +291,46 @@ var clientSideStatementDefs = []*clientSideStatementDef{
 		Descriptions: []clientSideStatementDescription{
 			{
 				Usage:  `Show execution plan without execution`,
-				Syntax: `EXPLAIN <sql>`,
+				Syntax: `EXPLAIN [FORMAT=<format>] [WIDTH=<width>] <sql>`,
+				Note:   "Options can be in any order. Spaces are not allowed before or after the `=`.",
 			},
 			{
 				Usage:  `Execute query and show execution plan with profile`,
-				Syntax: `EXPLAIN ANALYZE <sql>`,
+				Syntax: `EXPLAIN ANALYZE [FORMAT=<format>] [WIDTH=<width>] <sql>`,
+				Note:   "Options can be in any order. Spaces are not allowed before or after the `=`.",
 			},
 		},
-		Pattern: regexp.MustCompile(`(?is)^EXPLAIN\s+(ANALYZE\s+)?(.+)$`),
+		// To prevent ReDoS, repetition is limit to 10. Maybe it will be enhanced.
+		Pattern: regexp.MustCompile(`(?is)^EXPLAIN\s+(ANALYZE\s+)?((?:(?:FORMAT|WIDTH)(?:|=\S+)\s+){0,10})(.+)$`),
 		HandleSubmatch: func(matched []string) (Statement, error) {
 			isAnalyze := matched[1] != ""
-			isDML := stmtkind.IsDMLLexical(matched[2])
+			options, err := parseExplainOptions(matched[2])
+			if err != nil {
+				return nil, fmt.Errorf("invalid EXPLAIN%s: %w", lo.Ternary(isAnalyze, " ANALYZE", ""), err)
+			}
+
+			format, err := parseExplainFormat(options["FORMAT"])
+			if err != nil {
+				return nil, fmt.Errorf("invalid EXPLAIN%s: %w", lo.Ternary(isAnalyze, " ANALYZE", ""), err)
+			}
+
+			var width int64
+			if widthStr := options["WIDTH"]; widthStr != "" {
+				width, err = strconv.ParseInt(widthStr, 10, 64)
+				if err != nil {
+					return nil, fmt.Errorf("invalid WIDTH: %v, expected a positive integer, err: %w", widthStr, err)
+				}
+			}
+
+			sql := matched[3]
+			isDML := stmtkind.IsDMLLexical(sql)
 			switch {
 			case isAnalyze && isDML:
-				return &ExplainAnalyzeDmlStatement{Dml: matched[2]}, nil
+				return &ExplainAnalyzeDmlStatement{Dml: sql, Format: format, Width: width}, nil
 			case isAnalyze:
-				return &ExplainAnalyzeStatement{Query: matched[2]}, nil
+				return &ExplainAnalyzeStatement{Query: sql, Format: format, Width: width}, nil
 			default:
-				return &ExplainStatement{Explain: matched[2], IsDML: isDML}, nil
+				return &ExplainStatement{Explain: sql, IsDML: isDML, Format: format, Width: width}, nil
 			}
 		},
 	},
@@ -769,6 +791,31 @@ var clientSideStatementDefs = []*clientSideStatementDef{
 	},
 }
 
+type explainFormat string
+
+const (
+	explainFormatUnspecified explainFormat = ""
+	explainFormatCurrent     explainFormat = "CURRENT"
+	explainFormatTraditional explainFormat = "TRADITIONAL"
+	explainFormatCompact     explainFormat = "COMPACT"
+)
+
+func parseExplainFormat(s string) (explainFormat, error) {
+	switch strings.ToUpper(s) {
+	case "COMPACT":
+		return explainFormatCompact, nil
+	case "CURRENT":
+		return explainFormatCurrent, nil
+	case "TRADITIONAL":
+		return explainFormatTraditional, nil
+	case "":
+		return explainFormatUnspecified, nil
+	default:
+		return "", fmt.Errorf("parse error: unknown explain format: %s", s)
+	}
+
+}
+
 // Helper functions for HandleSubmatch implementations
 
 func parseTransaction(s string) (isReadOnly bool, err error) {
@@ -867,3 +914,15 @@ func parseIsolationLevel(isolationLevel string) (sppb.TransactionOptions_Isolati
 	}
 	return sppb.TransactionOptions_IsolationLevel(p), nil
 }
+
+func parseExplainOptions(ss string) (map[string]string, error) {
+	m := make(map[string]string)
+	for s := range strings.FieldsSeq(ss) {
+		before, after, _ := strings.Cut(s, "=")
+		if before == "" {
+			return nil, fmt.Errorf("invalid EXPLAIN option, expect <key>[=<value>], but: %s", s)
+		}
+		m[strings.ToUpper(before)] = after
+	}
+	return m, nil
+}

go.mod

@@ -14,8 +14,8 @@ require (
 	github.com/apstndb/gsqlutils v0.0.0-20250517013444-d2334c88d6ae
 	github.com/apstndb/lox v0.0.0-20241212132733-62f24606dc82
 	github.com/apstndb/memebridge v0.5.0
-	github.com/apstndb/spanemuboost v0.2.8
-	github.com/apstndb/spannerplanviz v0.6.0
+	github.com/apstndb/spanemuboost v0.2.10
+	github.com/apstndb/spannerplan v0.1.1
 	github.com/apstndb/spantype v0.3.8
 	github.com/apstndb/spanvalue v0.1.6
 	github.com/bufbuild/protocompile v0.14.1
@@ -37,7 +37,7 @@ require (
 	github.com/olekukonko/tablewriter v1.0.6
 	github.com/samber/lo v1.49.1
 	github.com/sourcegraph/conc v0.3.0
-	github.com/testcontainers/testcontainers-go/modules/gcloud v0.36.0
+	github.com/testcontainers/testcontainers-go/modules/gcloud v0.37.0
 	github.com/vbauerster/mpb/v8 v8.9.3
 	go.uber.org/zap v1.27.0
 	golang.org/x/exp v0.0.0-20250408133849-7e4ce0ab07d0
@@ -65,6 +65,7 @@ require (
 	github.com/Microsoft/go-winio v0.6.2 // indirect
 	github.com/VividCortex/ewma v1.2.0 // indirect
 	github.com/acarl005/stripansi v0.0.0-20180116102854-5a71ef0e047d // indirect
+	github.com/apstndb/treeprint v0.0.0-20250529153958-e82576b37da6 // indirect
 	github.com/cenkalti/backoff/v4 v4.3.0 // indirect
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect
 	github.com/cncf/xds/go v0.0.0-20250326154945-ae57f3c0d45f // indirect
@@ -97,7 +98,7 @@ require (
 	github.com/hashicorp/golang-lru v1.0.2 // indirect
 	github.com/klauspost/compress v1.17.11 // indirect
 	github.com/lufia/plan9stats v0.0.0-20240909124753-873cd0166683 // indirect
-	github.com/magiconair/properties v1.8.9 // indirect
+	github.com/magiconair/properties v1.8.10 // indirect
 	github.com/mattn/go-colorable v0.1.14 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/mattn/go-tty v0.0.7 // indirect
@@ -125,10 +126,9 @@ require (
 	github.com/stretchr/testify v1.10.0 // indirect
 	github.com/swaggest/jsonschema-go v0.3.73 // indirect
 	github.com/swaggest/refl v1.3.0 // indirect
-	github.com/testcontainers/testcontainers-go v0.36.0 // indirect
+	github.com/testcontainers/testcontainers-go v0.37.0 // indirect
 	github.com/tklauser/go-sysconf v0.3.14 // indirect
 	github.com/tklauser/numcpus v0.9.0 // indirect
-	github.com/xlab/treeprint v1.2.0 // indirect
 	github.com/yusufpapurcu/wmi v1.2.4 // indirect
 	go.opencensus.io v0.24.0 // indirect
 	go.opentelemetry.io/auto/sdk v1.1.0 // indirect