trees: show its phases as N of M, with progress, elapsed time and ETA (closes #113)

trees now runs in four phases, open, read, group and write, each under
the progress display scan uses, from the line naming the database to
the summary line. open covers a wait on a busy database. read counts
the records first, as scan's load does, then reads them against that
count; group counts the directories, and write the groups. The display
gains a unit so that each rate names what its phase counts; every scan
phase passes files and prints as before. The tests that pinned trees'
stderr now allow the phase lines between the database line and the
summary.

Judgement call: opening the database is a phase of its own, so there are four phases, not the three the issue sketches.
Judgement call: the count and the read are separate queries, as in scan's load, so during a scan the read can end slightly past or short of its total.

Model: opus-5-5

trees_test.go

@@ -3,7 +3,9 @@ package main
 import (
 	"bytes"
 	"database/sql"
+	"os"
 	"slices"
+	"strings"
 	"testing"
 )
 
@@ -17,6 +19,11 @@ const (
 	f2Content = "f2c"
 )
 
+// treesOpenLine is the plain line of trees' open phase when it opens
+// the database at once; it prints it as the phase starts and as it ends.
+const treesOpenLine = "[1/4] open: opening the database, elapsed 0s, " +
+	"eta unknown"
+
 // smokeTreeRecs mirrors the README smoke-test tree layout: /d/t1 and
 // /d/t2 are identical, /d/t3 differs from them only by one filename.
 func smokeTreeRecs() []scanRec {
@@ -170,7 +177,7 @@ func TestTreeNamesSortingBeforeSlash(t *testing.T) {
 		t.Fatalf("directory paths = %q, want %q", got, want)
 	}
 
-	groups := collectTreeGroups(dirs, super)
+	groups := collectTreeGroups(dirs, super, nil)
 
 	gotGroups := groupPaths(groups)
 	wantGroups := [][]string{{"/a", "/c"}}
@@ -203,6 +210,60 @@ func TestRunTreesEscapesPaths(t *testing.T) {
 	}
 }
 
+// TestRunTreesProgressNamesEachPhase runs trees on the smoke-test
+// records with stderr not a terminal, and checks every line it prints
+// there. After the line naming the database, each phase prints a line
+// naming it with its place among the four as it starts and another as
+// it ends. read counts the 6 records before it reads them, group counts
+// the 8 directories, and write the 1 group. The summary comes last, and
+// stdout holds the report alone.
+func TestRunTreesProgressNamesEachPhase(t *testing.T) {
+	path := seedDatabase(t, smokeTreeRecs())
+	t.Setenv(databaseEnv, path)
+
+	stderr := captureStderr(t)
+
+	var stdout bytes.Buffer
+
+	code := run([]string{cmdTrees}, &stdout, os.Stderr)
+	if code != exitOK {
+		t.Fatalf("run(trees) = %d, want %d; stderr: %s",
+			code, exitOK, stderr())
+	}
+
+	report := "first\tdupe\tfiles\tsize\n/d/t1\t/d/t2\t2\t3100\n"
+	if got := stdout.String(); got != report {
+		t.Errorf("stdout = %q, want %q", got, report)
+	}
+
+	// How each line starts; the rate at the end of a phase varies.
+	want := []string{
+		"trees: database " + path + " (from " + databaseEnv + ")",
+		treesOpenLine,
+		treesOpenLine,
+		"[2/4] read: counting the records, elapsed 0s, eta unknown",
+		"[2/4] read: [6/6] 100%, ",
+		"[3/4] group: [0/8] 0%, 0 directories/s, elapsed 0s, eta unknown",
+		"[3/4] group: [8/8] 100%, ",
+		"[4/4] write: [0/1] 0%, 0 groups/s, elapsed 0s, eta unknown",
+		"[4/4] write: [1/1] 100%, ",
+		"trees: 6 records read, 1 duplicate tree groups, 1 dupe trees, ",
+	}
+
+	lines := strings.Split(strings.TrimSuffix(stderr(), "\n"), "\n")
+	if len(lines) != len(want) {
+		t.Fatalf("stderr lines = %q, want %d lines starting %q",
+			lines, len(want), want)
+	}
+
+	for i := range want {
+		if !strings.HasPrefix(lines[i], want[i]) {
+			t.Errorf("stderr line %d = %q, want it to start %q",
+				i+1, lines[i], want[i])
+		}
+	}
+}
+
 func TestTreeDigests(t *testing.T) {
 	t.Parallel()
 
@@ -254,7 +315,7 @@ func TestCollectTreeGroupsMaximal(t *testing.T) {
 
 	super, dirs := treeOf(t, smokeTreeRecs())
 
-	groups := collectTreeGroups(dirs, super)
+	groups := collectTreeGroups(dirs, super, nil)
 
 	want := [][]string{{"/d/t1", "/d/t2"}}
 	if got := groupPaths(groups); !slices.EqualFunc(got, want,
@@ -278,14 +339,14 @@ func TestCollectTreeGroupsDeterministic(t *testing.T) {
 
 	super, dirs := treeOf(t, recs)
 
-	forward := groupPaths(collectTreeGroups(dirs, super))
+	forward := groupPaths(collectTreeGroups(dirs, super, nil))
 
 	reversed := slices.Clone(recs)
 	slices.Reverse(reversed)
 
 	superR, dirsR := treeOf(t, reversed)
 
-	backward := groupPaths(collectTreeGroups(dirsR, superR))
+	backward := groupPaths(collectTreeGroups(dirsR, superR, nil))
 	if !slices.EqualFunc(forward, backward, slices.Equal) {
 		t.Fatalf("output depends on record order: %v vs %v",
 			forward, backward)
@@ -304,7 +365,7 @@ func TestCollectTreeGroupsSiblings(t *testing.T) {
 
 	super, dirs := treeOf(t, recs)
 
-	got := groupPaths(collectTreeGroups(dirs, super))
+	got := groupPaths(collectTreeGroups(dirs, super, nil))
 
 	want := [][]string{{"/p/x1", "/p/x2"}}
 	if !slices.EqualFunc(got, want, slices.Equal) {
@@ -326,7 +387,7 @@ func TestCollectTreeGroupsDifferingParents(t *testing.T) {
 
 	super, dirs := treeOf(t, recs)
 
-	got := groupPaths(collectTreeGroups(dirs, super))
+	got := groupPaths(collectTreeGroups(dirs, super, nil))
 
 	want := [][]string{{"/p/a/x", "/q/b/x"}}
 	if !slices.EqualFunc(got, want, slices.Equal) {