tools/flow: add debug support via CUE_DEBUG_TOOLS_FLOW

Setting CUE_DEBUG_TOOLS_FLOW to some value other than the empty string
now causes a mermaid graph to be printed out for each update of the flow
Controller.

This will help with debugging of tools/flow and cue cmd issues.

Signed-off-by: Paul Jolly <[email protected]>
Change-Id: Ic5f122250a0fa13a2134aa47161acbf8e570ee02
Reviewed-on: https://review.gerrithub.io/c/cue-lang/cue/+/546541
Unity-Result: CUEcueckoo <[email protected]>
Reviewed-by: Roger Peppe <[email protected]>
TryBot-Result: CUEcueckoo <[email protected]>

Author: myitcv

cmd/cue/cmd/testdata/script/cmd_debug.txtar

@@ -0,0 +1,44 @@
+env CUE_DEBUG_TOOLS_FLOW=1
+
+exec cue cmd bar
+cmp stderr stderr.golden
+
+-- x_tool.cue --
+package x
+
+import (
+	"tool/cli"
+)
+
+command: bar: {
+	a: cli.Print & {
+		text: "a"
+	}
+	"\"b#": cli.Print & {
+		text:   "b"
+		$after: a
+	}
+
+}
+-- stderr.golden --
+tools/flow task dependency graph:
+```mermaid
+graph TD
+  t0("command.bar.a [Ready]")
+  t1("command.bar.#quot;\#quot;b#35;#quot; [Waiting]")
+  t1-->t0
+```
+tools/flow task dependency graph:
+```mermaid
+graph TD
+  t0("command.bar.a [Terminated]")
+  t1("command.bar.#quot;\#quot;b#35;#quot; [Ready]")
+  t1-->t0
+```
+tools/flow task dependency graph:
+```mermaid
+graph TD
+  t0("command.bar.a [Terminated]")
+  t1("command.bar.#quot;\#quot;b#35;#quot; [Terminated]")
+  t1-->t0
+```

tools/flow/cycle_test.go

@@ -20,6 +20,9 @@ import (
 	"testing"
 )
 
+// MermaidGraph exports mermaidGraph for external tests
+var MermaidGraph = mermaidGraph
+
 func TestIsCyclic(t *testing.T) {
 	testCases := []struct {
 		// semi-colon-separated list of nodes with comma-separated list

tools/flow/flow.go

@@ -68,6 +68,9 @@ package flow
 
 import (
 	"context"
+	"fmt"
+	"os"
+	"strings"
 	"sync"
 
 	"cuelang.org/go/cue"
@@ -86,6 +89,8 @@ var (
 
 	// TODO: ErrUpdate: update and run a dependency, but don't complete a
 	// dependency as more results may come. This is useful in server mode.
+
+	debug = os.Getenv("CUE_DEBUG_TOOLS_FLOW") != ""
 )
 
 // A TaskFunc creates a Runner for v if v defines a task or reports nil
@@ -278,6 +283,27 @@ func (c *Controller) Value() cue.Value {
 	return c.inst
 }
 
+// We need to escape quotes in the path, per
+// https://mermaid-js.github.io/mermaid/#/flowchart?id=entity-codes-to-escape-characters
+// This also requires that we escape the quoting character #.
+var mermaidQuote = strings.NewReplacer("#", "#35;", `"`, "#quot;")
+
+// mermaidGraph generates a mermaid graph of the current state. This can be
+// pasted into https://mermaid-js.github.io/mermaid-live-editor/ for
+// visualization.
+func mermaidGraph(c *Controller) string {
+	w := &strings.Builder{}
+	fmt.Fprintln(w, "graph TD")
+	for i, t := range c.Tasks() {
+		path := mermaidQuote.Replace(t.Path().String())
+		fmt.Fprintf(w, "  t%d(\"%s [%s]\")\n", i, path, t.State())
+		for _, t := range t.Dependencies() {
+			fmt.Fprintf(w, "  t%d-->t%d\n", i, t.Index())
+		}
+	}
+	return w.String()
+}
+
 // A State indicates the state of a Task.
 //
 // The following state diagram indicates the possible state transitions:

tools/flow/flow_test.go

@@ -52,7 +52,7 @@ func TestFlow(t *testing.T) {
 		var tasksTotal stats.Counts
 
 		updateFunc := func(c *flow.Controller, task *flow.Task) error {
-			str := mermaidGraph(c)
+			str := flow.MermaidGraph(c)
 			step := fmt.Sprintf("t%d", seqNum)
 			fmt.Fprintln(t.Writer(step), str)
 
@@ -245,21 +245,6 @@ func waitSeqNum(seq int64) {
 	seqCond.L.Unlock()
 }
 
-// mermaidGraph generates a mermaid graph of the current state. This can be
-// pasted into https://mermaid-js.github.io/mermaid-live-editor/ for
-// visualization.
-func mermaidGraph(c *flow.Controller) string {
-	w := &strings.Builder{}
-	fmt.Fprintln(w, "graph TD")
-	for i, t := range c.Tasks() {
-		fmt.Fprintf(w, "  t%d(\"%s [%s]\")\n", i, t.Path(), t.State())
-		for _, t := range t.Dependencies() {
-			fmt.Fprintf(w, "  t%d-->t%d\n", i, t.Index())
-		}
-	}
-	return w.String()
-}
-
 // DO NOT REMOVE: for testing purposes.
 func TestX(t *testing.T) {
 	in := `
@@ -285,7 +270,7 @@ func TestX(t *testing.T) {
 		},
 	}, v, taskFunc)
 
-	t.Error(mermaidGraph(c))
+	t.Error(flow.MermaidGraph(c))
 
 	if err := c.Run(context.Background()); err != nil {
 		t.Fatal(errors.Details(err, nil))

tools/flow/run.go

@@ -26,6 +26,9 @@ package flow
 // future tasks may be long running, as discussed above.
 
 import (
+	"fmt"
+	"os"
+
 	"cuelang.org/go/cue/errors"
 	"cuelang.org/go/internal/core/adt"
 	"cuelang.org/go/internal/core/eval"
@@ -136,6 +139,13 @@ func (c *Controller) markReady(t *Task) {
 		}
 	}
 
+	if debug {
+		fmt.Fprintln(os.Stderr, "tools/flow task dependency graph:")
+		fmt.Fprintln(os.Stderr, "```mermaid")
+		fmt.Fprint(os.Stderr, mermaidGraph(c))
+		fmt.Fprintln(os.Stderr, "```")
+	}
+
 	if c.cfg.UpdateFunc != nil {
 		if err := c.cfg.UpdateFunc(c, t); err != nil {
 			c.addErr(err, "task completed")