Add -explain flag to next-test command

Add a new -explain flag that finds tests with explain_todo entries,
sorted by fewest pending statements first. This helps prioritize
tests that are closest to being fully implemented.

Usage:
  go run ./cmd/next-test -explain

Author: claude

CLAUDE.md

@@ -2,6 +2,14 @@
 
 ## Next Steps
 
+To find the next explain test to work on (fewest pending statements first), run:
+
+```bash
+go run ./cmd/next-test -explain
+```
+
+This finds tests with `explain_todo` entries in their metadata.
+
 To find the next format roundtrip test to work on, run:
 
 ```bash

cmd/next-test/main.go

@@ -9,26 +9,30 @@ import (
 	"sort"
 )
 
-var formatFlag = flag.Bool("format", false, "Find tests with todo_format (required)")
+var formatFlag = flag.Bool("format", false, "Find tests with todo_format: true")
+var explainFlag = flag.Bool("explain", false, "Find tests with explain_todo entries (fewest first)")
 
 type testMetadata struct {
-	TodoFormat bool  `json:"todo_format,omitempty"`
-	Explain    *bool `json:"explain,omitempty"`
-	Skip       bool  `json:"skip,omitempty"`
-	ParseError bool  `json:"parse_error,omitempty"`
+	TodoFormat  bool            `json:"todo_format,omitempty"`
+	ExplainTodo map[string]bool `json:"explain_todo,omitempty"`
+	Explain     *bool           `json:"explain,omitempty"`
+	Skip        bool            `json:"skip,omitempty"`
+	ParseError  bool            `json:"parse_error,omitempty"`
 }
 
 type todoTest struct {
-	name      string
-	querySize int
+	name           string
+	querySize      int
+	explainTodoLen int
 }
 
 func main() {
 	flag.Parse()
 
-	if !*formatFlag {
-		fmt.Fprintf(os.Stderr, "Usage: go run ./cmd/next-test -format\n")
-		fmt.Fprintf(os.Stderr, "Finds tests with todo_format: true in metadata.\n")
+	if !*formatFlag && !*explainFlag {
+		fmt.Fprintf(os.Stderr, "Usage: go run ./cmd/next-test [-format | -explain]\n")
+		fmt.Fprintf(os.Stderr, "  -format   Find tests with todo_format: true\n")
+		fmt.Fprintf(os.Stderr, "  -explain  Find tests with explain_todo entries (fewest first)\n")
 		os.Exit(1)
 	}
 
@@ -60,16 +64,22 @@ func main() {
 			continue
 		}
 
-		// Check for todo_format
-		if !metadata.TodoFormat {
-			continue
-		}
-
 		// Skip tests with skip or explain=false or parse_error
 		if metadata.Skip || (metadata.Explain != nil && !*metadata.Explain) || metadata.ParseError {
 			continue
 		}
 
+		// Check based on flag
+		if *formatFlag {
+			if !metadata.TodoFormat {
+				continue
+			}
+		} else if *explainFlag {
+			if len(metadata.ExplainTodo) == 0 {
+				continue
+			}
+		}
+
 		// Read query to get its size
 		queryPath := filepath.Join(testDir, "query.sql")
 		queryBytes, err := os.ReadFile(queryPath)
@@ -78,26 +88,47 @@ func main() {
 		}
 
 		todoTests = append(todoTests, todoTest{
-			name:      entry.Name(),
-			querySize: len(queryBytes),
+			name:           entry.Name(),
+			querySize:      len(queryBytes),
+			explainTodoLen: len(metadata.ExplainTodo),
 		})
 	}
 
+	todoType := "todo_format"
+	if *explainFlag {
+		todoType = "explain_todo"
+	}
+
 	if len(todoTests) == 0 {
-		fmt.Printf("No todo_format tests found!\n")
+		fmt.Printf("No %s tests found!\n", todoType)
 		return
 	}
 
-	// Sort by query size (shortest first)
-	sort.Slice(todoTests, func(i, j int) bool {
-		return todoTests[i].querySize < todoTests[j].querySize
-	})
+	// Sort based on mode
+	if *explainFlag {
+		// Sort by explain_todo count (fewest first), then by query size
+		sort.Slice(todoTests, func(i, j int) bool {
+			if todoTests[i].explainTodoLen != todoTests[j].explainTodoLen {
+				return todoTests[i].explainTodoLen < todoTests[j].explainTodoLen
+			}
+			return todoTests[i].querySize < todoTests[j].querySize
+		})
+	} else {
+		// Sort by query size (shortest first)
+		sort.Slice(todoTests, func(i, j int) bool {
+			return todoTests[i].querySize < todoTests[j].querySize
+		})
+	}
 
-	// Print the shortest one
+	// Print the best candidate
 	next := todoTests[0]
 	testDir := filepath.Join(testdataDir, next.name)
 
-	fmt.Printf("Next todo_format test: %s\n\n", next.name)
+	if *explainFlag {
+		fmt.Printf("Next %s test: %s (%d pending statements)\n\n", todoType, next.name, next.explainTodoLen)
+	} else {
+		fmt.Printf("Next %s test: %s\n\n", todoType, next.name)
+	}
 
 	// Print query.sql contents
 	queryPath := filepath.Join(testDir, "query.sql")
@@ -110,5 +141,19 @@ func main() {
 		fmt.Printf("\nExpected EXPLAIN output:\n%s\n", string(explainBytes))
 	}
 
-	fmt.Printf("\nRemaining todo_format tests: %d\n", len(todoTests))
+	// Print explain_todo entries if in explain mode
+	if *explainFlag {
+		metadataPath := filepath.Join(testDir, "metadata.json")
+		if metadataBytes, err := os.ReadFile(metadataPath); err == nil {
+			var metadata testMetadata
+			if json.Unmarshal(metadataBytes, &metadata) == nil {
+				fmt.Printf("\nPending statements (explain_todo):\n")
+				for stmt := range metadata.ExplainTodo {
+					fmt.Printf("  - %s\n", stmt)
+				}
+			}
+		}
+	}
+
+	fmt.Printf("\nRemaining %s tests: %d\n", todoType, len(todoTests))
 }