chore: improve debug formatting in path builder (#1355)

This produces format that is easier to read:

```
CreatePlanningPaths
===================

[pathBuilderVisitor]:  EnterSelectionSet ref: 2
[pathBuilderVisitor]:  EnterField ref: 2 fieldName: accounts typeName: Query
[pathBuilderVisitor]:  saveAddedPath {"ds":11987355753863978781,"path":"query","shouldWalkFields":true,"pathType":"parent"}
[pathBuilderVisitor]:  saveAddedPath {"ds":11987355753863978781,"path":"query.accounts","fieldRef":  2,"typeName":"Query","shouldWalkFields":true,"isRootNode":true,"pathType":"field"}
... SNIP ...
[pathBuilderVisitor]:  LeaveSelectionSet ref: 2

Planned paths on initial run #1:
  should revisit
  has missing paths
  has fields waiting for dependency

  Missing paths:
    query.accounts.full

Run #1. Planner ID 0
  ParentPath: query
  Datasource ID: id-1, name: id-1, hash: 11987355753863978781
  Paths:
{"ds":11987355753863978781,"path":"query","shouldWalkFields":true,"pathType":"parent"}
{"ds":11987355753863978781,"path":"query.accounts","fieldRef":  2,"typeName":"Query","shouldWalkFields":true,"isRootNode":true,"pathType":"field"}
{"ds":11987355753863978781,"path":"query.accounts.id","fieldRef":  0,"typeName":"User","shouldWalkFields":true,"isRootNode":true,"pathType":"field"}
{"ds":11987355753863978781,"path":"query.accounts.__typename","fieldRef":  4,"typeName":"User","shouldWalkFields":true,"isRootNode":false,"pathType":"field"}


Run #1. Planner ID 1
  ParentPath: query.accounts
  Datasource ID: id-2, name: id-2, hash: 14787246084284009732
  Depends on planner IDs: [0]
  Required fields:
    key: {"type_name":"User","selection_set":"id","RemappedPaths":null}
  Paths:
{"ds":14787246084284009732,"path":"query.accounts","shouldWalkFields":true,"pathType":"parent"}
{"ds":14787246084284009732,"path":"query.accounts.title","fieldRef":  3,"typeName":"User","shouldWalkFields":true,"isRootNode":true,"pathType":"field"}

[pathBuilderVisitor]:  EnterSelectionSet ref: 2
[pathBuilderVisitor]:  EnterField ref: 2 fieldName: accounts typeName: Query
[pathBuilderVisitor]:  EnterSelectionSet ref: 1
```


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Chores**
* Standardized and clarified diagnostic/log output across selection and
planning flows: run-aware headers, consistent labeling/indentation,
unified messages for node selection and path planning, improved
revisit/missing-path reporting, and deterministic handling of
potentially missing paths to improve troubleshooting.
* **Tests**
* Non-functional test change: an optional debug line added but left
commented out (no behavior change).

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: ysmolski

execution/engine/execution_engine_test.go

@@ -263,6 +263,7 @@ func TestExecutionEngine_Execute(t *testing.T) {
 			engineConf.plannerConfig.Debug = plan.DebugConfiguration{
 				// PrintOperationTransformations: true,
 				// PrintPlanningPaths:            true,
+				// PrintNodeSuggestions:          true,
 				// PrintQueryPlans:               true,
 				// ConfigurationVisitor:          true,
 				// PlanningVisitor:               true,

v2/pkg/engine/plan/node_selection_builder.go

@@ -96,7 +96,7 @@ func (p *NodeSelectionBuilder) SelectNodes(operation, definition *ast.Document,
 	}
 
 	if p.config.Debug.PrintOperationTransformations {
-		debugMessage("Initial operation:")
+		debugMessage("SelectNodes. Initial operation:\n===========")
 		p.printOperation(operation)
 	}
 
@@ -120,7 +120,7 @@ func (p *NodeSelectionBuilder) SelectNodes(operation, definition *ast.Document,
 	}
 
 	if p.config.Debug.PrintOperationTransformations {
-		debugMessage("Select nodes initial run - operation:")
+		debugMessage("Selected nodes on run #1 for operation:")
 		p.printOperation(operation)
 	}
 
@@ -146,11 +146,11 @@ func (p *NodeSelectionBuilder) SelectNodes(operation, definition *ast.Document,
 		}
 
 		if p.config.Debug.PrintOperationTransformations || p.config.Debug.PrintNodeSuggestions {
-			debugMessage(fmt.Sprintf("Select nodes run #%d", i))
+			debugMessage(fmt.Sprintf("Selected nodes on additional run #%d.", i+1))
 		}
 
 		if p.config.Debug.PrintNodeSuggestions {
-			p.nodeSelectionsVisitor.nodeSuggestions.printNodesWithFilter("\nRecalculated node suggestions:\n", p.config.Debug.PrintNodeSuggestionsFilterNotSelected)
+			p.nodeSelectionsVisitor.nodeSuggestions.printNodesWithFilter("\nUpdated node suggestions:\n", p.config.Debug.PrintNodeSuggestionsFilterNotSelected)
 		}
 
 		p.nodeSelectionsWalker.Walk(operation, definition, report)
@@ -159,8 +159,7 @@ func (p *NodeSelectionBuilder) SelectNodes(operation, definition *ast.Document,
 		}
 
 		if p.config.Debug.PrintOperationTransformations {
-			debugMessage("Operation with new required fields:")
-			debugMessage(fmt.Sprintf("Has new fields: %v", p.nodeSelectionsVisitor.hasNewFields))
+			debugMessage(fmt.Sprintf("Operation with new required fields (has new fields: %v):", p.nodeSelectionsVisitor.hasNewFields))
 			p.printOperation(operation)
 		}
 

v2/pkg/engine/plan/path_builder.go

@@ -45,7 +45,7 @@ func (p *PathBuilder) SetOperationName(name string) {
 
 func (p *PathBuilder) CreatePlanningPaths(operation, definition *ast.Document, report *operationreport.Report) []PlannerConfiguration {
 	if p.config.Debug.PrintPlanningPaths {
-		debugMessage("Create planning paths")
+		debugMessage("CreatePlanningPaths\n===================")
 	}
 
 	p.visitor.plannerConfiguration = p.config
@@ -71,9 +71,9 @@ func (p *PathBuilder) CreatePlanningPaths(operation, definition *ast.Document, r
 	// - walker.Stop was called and visiting was halted
 
 	if p.config.Debug.PrintPlanningPaths {
-		debugMessage("Planning paths after initial run")
+		fmt.Printf("\nPlanned paths on initial run #1:\n")
 		p.printRevisitInfo()
-		p.printPlanningPaths()
+		p.printPlanningPaths(1)
 	}
 
 	i := 1
@@ -89,12 +89,9 @@ func (p *PathBuilder) CreatePlanningPaths(operation, definition *ast.Document, r
 		p.visitor.populateMissingPaths()
 
 		if p.config.Debug.PrintPlanningPaths {
-			debugMessage(fmt.Sprintf("Create planning paths run #%d", i))
-		}
-
-		if p.config.Debug.PrintPlanningPaths {
+			fmt.Printf("\nPlanned paths on run #%d:\n", i+1)
 			p.printRevisitInfo()
-			p.printPlanningPaths()
+			p.printPlanningPaths(i + 1)
 		}
 
 		i++
@@ -116,8 +113,8 @@ func (p *PathBuilder) CreatePlanningPaths(operation, definition *ast.Document, r
 	// remove unnecessary fragment paths
 	hasRemovedPaths := p.removeUnnecessaryFragmentPaths()
 	if hasRemovedPaths && p.config.Debug.PrintPlanningPaths {
-		debugMessage("After removing unnecessary fragment paths")
-		p.printPlanningPaths()
+		debugMessage("Final paths after removing unnecessary fragment paths:")
+		p.printPlanningPaths(i)
 	}
 
 	return p.visitor.planners
@@ -138,34 +135,41 @@ func (p *PathBuilder) removeUnnecessaryFragmentPaths() (hasRemovedPaths bool) {
 }
 
 func (p *PathBuilder) printRevisitInfo() {
-	fmt.Println("Should revisit:", p.visitor.shouldRevisit())
-	fmt.Println("Has missing paths:", p.visitor.hasMissingPaths())
-	fmt.Println("Has fields waiting for dependency:", p.visitor.hasFieldsWaitingForDependency())
+	if p.visitor.shouldRevisit() {
+		fmt.Println("  should revisit")
+	}
+	if p.visitor.hasMissingPaths() {
+		fmt.Println("  has missing paths")
+	}
+	if p.visitor.hasFieldsWaitingForDependency() {
+		fmt.Println("  has fields waiting for dependency")
+	}
 
 	p.printMissingPaths()
 }
 
-func (p *PathBuilder) printPlanningPaths() {
-	debugMessage("\n\nPlanning paths:\n\n")
+func (p *PathBuilder) printPlanningPaths(run int) {
 	for i, planner := range p.visitor.planners {
-		fmt.Printf("\nPlanner id: %d\n", i)
-		fmt.Printf("Parent path: %s\n", planner.ParentPath())
+		fmt.Printf("\nRun #%d. Planner ID %d\n", run, i)
+		fmt.Printf("  ParentPath: %s\n", planner.ParentPath())
 		ds := planner.DataSourceConfiguration()
-		fmt.Printf("Datasource id: %s name: %s hash: %d\n", ds.Id(), ds.Name(), ds.Hash())
-		fmt.Printf("Depends on planner ids: %v\n", planner.ObjectFetchConfiguration().dependsOnFetchIDs)
+		fmt.Printf("  Datasource ID: %s, name: %s, hash: %d\n", ds.Id(), ds.Name(), ds.Hash())
+		if len(planner.ObjectFetchConfiguration().dependsOnFetchIDs) > 0 {
+			fmt.Printf("  Depends on planner IDs: %v\n", planner.ObjectFetchConfiguration().dependsOnFetchIDs)
+		}
 
 		requiredFields := planner.RequiredFields()
 		if requiredFields != nil && len(*requiredFields) > 0 {
-			fmt.Println("Required fields:")
+			fmt.Println("  Required fields:")
 			for _, field := range *requiredFields {
 				if field.FieldName != "" {
-					fmt.Printf("required by %s: %s\n", field.FieldName, field)
+					fmt.Printf("    required by %s: %s\n", field.FieldName, field)
 					continue
 				}
-				fmt.Println("key:", field)
+				fmt.Println("    key:", field)
 			}
 		}
-		fmt.Println("Paths:")
+		fmt.Println("  Paths:")
 		planner.ForEachPath(func(path *pathConfiguration) (shouldBreak bool) {
 			fmt.Println(path.String())
 			return false
@@ -176,9 +180,9 @@ func (p *PathBuilder) printPlanningPaths() {
 
 func (p *PathBuilder) printMissingPaths() {
 	if p.visitor.hasMissingPaths() {
-		debugMessage("Missing paths:")
+		fmt.Printf("\n  Missing paths:\n")
 		for path := range p.visitor.missingPathTracker {
-			fmt.Println(path)
+			fmt.Printf("    %v\n", path)
 		}
 	}
 }

v2/pkg/engine/plan/path_builder_visitor.go

@@ -1232,13 +1232,12 @@ func (c *pathBuilderVisitor) handleMissingPath(planned bool, typeName string, fi
 		if planned {
 			// __typename field on a union could not have a suggestion
 			return
-		} else {
-			if c.plannerConfiguration.Debug.PrintPlanningPaths {
-				fmt.Println("Adding potentially missing path", currentPath)
-			}
+		}
 
-			c.potentiallyMissingPathTracker[currentPath] = struct{}{}
+		if c.plannerConfiguration.Debug.PrintPlanningPaths {
+			fmt.Println("Found potentially missing path", currentPath)
 		}
+		c.potentiallyMissingPathTracker[currentPath] = struct{}{}
 	}
 
 	allSuggestionsPlanned := true