Show the walk path on the line below its display (closes #160) (#166)

internal/sfdupes/progress.go

@@ -9,8 +9,10 @@ import (
 	"strings"
 	"sync"
 	"time"
+	"unicode"
 	"unicode/utf8"
 
+	"github.com/rivo/uniseg"
 	"github.com/schollz/progressbar/v3"
 	"golang.org/x/term"
 )
@@ -116,7 +118,8 @@ type drawnCount struct {
 // terminal's width. A phase with an exact total ends the line with its
 // percent and bar, at the terminal's right edge, when the terminal has
 // room for them. It is drawn again every redrawInterval, so its elapsed
-// time keeps moving while the phase waits for its next item. When
+// time keeps moving while the phase waits for its next item. Each draw
+// of the walk shows the path it reached last on the line below. When
 // stderr is not a TTY it emits no ANSI redraws: it prints line as the
 // phase starts, every plainInterval while it runs, and as it ends.
 //
@@ -141,6 +144,7 @@ type progress struct {
 	estimate   bool
 	waitingFor string
 	stalledOn  string
+	path       string // the path the walk reached last; "" for none
 	count      int64
 	start      time.Time // when the phase started, for the elapsed time
 	rateStart  time.Time // when the count started, for the time remaining
@@ -239,6 +243,82 @@ func (p *progress) draw() {
 	// less the terminal's last column, which spinnerMargin keeps clear. A
 	// bar's cells take one column each but more than one byte.
 	p.widest = max(p.widest, utf8.RuneCountInString(text)+spinnerMargin-1)
+
+	if p.path != "" {
+		// The library draws the path on the line below and returns to
+		// the phase's line. The path is escaped as warnings are, and its
+		// other control characters are written out, so that the terminal
+		// shows them instead of acting on them. It stays clear of the
+		// last column, so that no terminal wraps it.
+		shown := escapeControlChars(escapePath(p.path))
+		_ = p.bar.AddDetail(cutToColumns(shown, width-1))
+	}
+}
+
+// escapeControlChars returns s with each control character written as
+// \x and its code in two hex digits, as \x1b for the escape character.
+// The control characters are U+0000 to U+001F, U+007F and U+0080 to
+// U+009F, as unicode.IsControl reports them. A byte from 0x80 to 0x9F
+// that is not part of a valid UTF-8 character is written the same way,
+// as \x9b, since a terminal not in UTF-8 mode acts on it. Every other
+// byte is kept as it is.
+func escapeControlChars(s string) string {
+	var b strings.Builder
+
+	for rest := s; rest != ""; {
+		char, size := utf8.DecodeRuneInString(rest)
+		if char == utf8.RuneError && size == 1 {
+			// Not part of a valid UTF-8 character. A terminal not in
+			// UTF-8 mode reads the byte as the character with its code,
+			// so that 0x9b is a control character there and 0xe9 is not.
+			char = rune(rest[0])
+		}
+
+		if unicode.IsControl(char) {
+			fmt.Fprintf(&b, `\x%02x`, char)
+		} else {
+			b.WriteString(rest[:size])
+		}
+
+		rest = rest[size:]
+	}
+
+	return b.String()
+}
+
+// cutToColumns returns s cut to at most columns terminal columns, at a
+// character boundary. A wide character, as in Chinese, takes two
+// columns.
+func cutToColumns(s string, columns int) string {
+	used, end, state := 0, 0, -1
+
+	for rest := s; rest != ""; {
+		char, next, width, nextState := uniseg.FirstGraphemeClusterInString(
+			rest, state)
+		if used+width > columns {
+			break
+		}
+
+		used += width
+		end += len(char)
+		rest, state = next, nextState
+	}
+
+	return s[:end]
+}
+
+// clear erases the display from the terminal: its line, and the path on
+// the line below when one is shown. p.mu must be held.
+func (p *progress) clear() {
+	if p.bar == nil {
+		return
+	}
+
+	if p.path != "" {
+		_ = p.bar.AddDetail("")
+	}
+
+	_ = p.bar.Clear()
 }
 
 // newBar has the library make what draw draws: its spinner, followed by
@@ -263,6 +343,8 @@ func (p *progress) newBar(width int) {
 		// The text carries the elapsed time and the time remaining.
 		progressbar.OptionSetElapsedTime(false),
 		progressbar.OptionSetPredictTime(false),
+		// The line below the phase's line, for the walk's path.
+		progressbar.OptionSetMaxDetailRow(1),
 	)
 	p.widest = 0
 }
@@ -314,6 +396,19 @@ func (p *progress) increment() {
 	p.lastItem = now
 }
 
+// setPath records the path the walk reached last, which a display on a
+// terminal shows at its next draw.
+func (p *progress) setPath(path string) {
+	if p == nil {
+		return
+	}
+
+	p.mu.Lock()
+	defer p.mu.Unlock()
+
+	p.path = path
+}
+
 // warnf prints a one-line warning to stderr without corrupting the
 // display. The whole message is escaped like a report's path columns,
 // so a path holding a newline cannot split the warning.
@@ -327,11 +422,9 @@ func (p *progress) warnf(format string, args ...any) {
 	p.mu.Lock()
 	defer p.mu.Unlock()
 
-	if p.bar != nil {
-		// The warning takes the display's line; the next draw shows
-		// the display again, on the line below.
-		_ = p.bar.Clear()
-	}
+	// The warning takes the display's line; the next draw shows the
+	// display again, on the line below.
+	p.clear()
 
 	fmt.Fprintln(os.Stderr, msg)
 }
@@ -392,9 +485,7 @@ func (w *progressWriter) Flush() error {
 		w.p.mu.Lock()
 		defer w.p.mu.Unlock()
 
-		if w.p.bar != nil {
-			_ = w.p.bar.Clear()
-		}
+		w.p.clear()
 	}
 
 	_, err := w.out.Write(w.buf)
@@ -414,6 +505,13 @@ func (p *progress) finish() {
 	close(p.stop)
 	<-p.done
 
+	// The walk's path is only for someone watching the walk. Its line is
+	// erased, and the next phase is drawn on it.
+	p.mu.Lock()
+	p.clear()
+	p.path = ""
+	p.mu.Unlock()
+
 	p.draw()
 
 	if p.width != nil {

internal/sfdupes/progress_test.go

@@ -6,6 +6,7 @@ import (
 	"math"
 	"os"
 	"path/filepath"
+	"regexp"
 	"slices"
 	"strings"
 	"sync"
@@ -1138,3 +1139,164 @@ func TestWarningAfterLastItemKeepsBar(t *testing.T) {
 		t.Errorf("terminal shows %q, want a count of 2 of 2", shown)
 	}
 }
+
+func TestCutToColumns(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		s       string
+		columns int
+		want    string
+	}{
+		{"/srv/a", 10, "/srv/a"},
+		{"/srv/photos", 8, "/srv/pho"},
+		// Each of these two fullwidth letters takes two columns.
+		{"/ＡＢ/a", 4, "/Ａ"},
+		{"/ＡＢ/a", 5, "/ＡＢ"},
+		// An accent that combines with the letter before stays with it.
+		{"/café/a", 5, "/café"},
+		{"/srv", 0, ""},
+	}
+
+	for _, tc := range cases {
+		if got := cutToColumns(tc.s, tc.columns); got != tc.want {
+			t.Errorf("cutToColumns(%q, %d) = %q, want %q",
+				tc.s, tc.columns, got, tc.want)
+		}
+	}
+}
+
+func TestEscapeControlChars(t *testing.T) {
+	t.Parallel()
+
+	cases := map[string]string{
+		"/srv/music":    "/srv/music",
+		"/a\x1b[2Jb":    `/a\x1b[2Jb`,
+		"/a\x00\a\x7fb": `/a\x00\x07\x7fb`,
+		// U+009B takes two bytes in UTF-8.
+		"/a\u009b2Jb": `/a\x9b2Jb`,
+		// Byte 0x9b alone is not valid UTF-8. A terminal not in UTF-8
+		// mode acts on it, as on every byte from 0x80 to 0x9f.
+		"/a\x9b2Jb":       `/a\x9b2Jb`,
+		"/a\x80\x9f\xa0b": `/a\x80\x9f` + "\xa0b",
+		// In ě, which is c4 9b in UTF-8, byte 0x9b is part of a valid
+		// character.
+		"/aě2Jb":          "/aě2Jb",
+		"/café/ＡＢ":        "/café/ＡＢ",
+		"/latin1-caf\xe9": "/latin1-caf\xe9",
+	}
+	for in, want := range cases {
+		if got := escapeControlChars(in); got != want {
+			t.Errorf("escapeControlChars(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+// pathLines returns the text of each line the library wrote below a
+// display's line. It writes one as an erase to the end of the line, a
+// carriage return, the text and a newline.
+func pathLines(out string) []string {
+	matches := regexp.MustCompile("\x1b\\[K\r([^\n]*)\n").
+		FindAllStringSubmatch(out, -1)
+	lines := make([]string, 0, len(matches))
+
+	for _, m := range matches {
+		lines = append(lines, m[1])
+	}
+
+	return lines
+}
+
+// TestTerminalWalkShowsPathBelow checks that the walk's display on a
+// terminal 30 columns wide shows the path it reached last on the line
+// below, cut to 29 columns. That line is erased before a warning is
+// printed, and again when the walk ends, so the next phase is drawn on
+// an empty line.
+//
+//nolint:paralleltest // captureStderr replaces the process-wide os.Stderr
+func TestTerminalWalkShowsPathBelow(t *testing.T) {
+	stderr := captureStderr(t)
+	p := startProgress(progressParams{
+		label: scanPhase("walk"), unit: scanUnit, total: -1,
+	}, func() int { return 30 }, testRedraw, time.Now)
+
+	const shown = "/srv/photos/2026/holiday/beac"
+
+	p.setPath("/srv/photos/2026/holiday/beach.jpg")
+	p.increment()
+	awaitOutput(t, stderr, shown, 1)
+
+	p.warnf("warning")
+
+	before, _, _ := strings.Cut(stderr(), "warning")
+	if lines := pathLines(before); lines[len(lines)-1] != "" {
+		t.Errorf("line below shows %q as the warning is printed, want it "+
+			"empty", lines[len(lines)-1])
+	}
+
+	// Drawn again below the warning.
+	awaitOutput(t, stderr, shown, strings.Count(before, shown)+1)
+	p.finish()
+
+	lines := pathLines(stderr())
+	if !slices.Contains(lines, shown) {
+		t.Errorf("lines below the display = %q, want %q among them",
+			lines, shown)
+	}
+
+	if last := lines[len(lines)-1]; last != "" {
+		t.Errorf("line below the display shows %q after the walk, want it "+
+			"empty", last)
+	}
+}
+
+// TestTerminalWalkEscapesControlChars checks that a walked path holding
+// escape characters, which would clear the screen and set the window
+// title, puts none on the line below the walk's display. The line shows
+// each control character written out, as \x1b.
+//
+//nolint:paralleltest // captureStderr replaces the process-wide os.Stderr
+func TestTerminalWalkEscapesControlChars(t *testing.T) {
+	stderr := captureStderr(t)
+	p := startProgress(progressParams{
+		label: scanPhase("walk"), unit: scanUnit, total: -1,
+	}, func() int { return 80 }, testRedraw, time.Now)
+
+	p.setPath("/srv/\x1b[2J\x1b]0;title\a/beach.jpg")
+	p.increment()
+	awaitOutput(t, stderr, "beach.jpg", 1)
+	p.finish()
+
+	lines := pathLines(stderr())
+	for _, line := range lines {
+		if strings.Contains(line, "\x1b") {
+			t.Errorf("line below the display = %q, want no escape "+
+				"character", line)
+		}
+	}
+
+	const shown = `/srv/\x1b[2J\x1b]0;title\x07/beach.jpg`
+	if !slices.Contains(lines, shown) {
+		t.Errorf("lines below the display = %q, want %q among them",
+			lines, shown)
+	}
+}
+
+// TestPlainWalkShowsNoPath checks that the walk's display prints no path
+// when stderr is not a terminal.
+//
+//nolint:paralleltest // captureStderr replaces the process-wide os.Stderr
+func TestPlainWalkShowsNoPath(t *testing.T) {
+	stderr := captureStderr(t)
+	p := startProgress(progressParams{
+		label: scanPhase("walk"), unit: scanUnit, total: -1,
+	}, nil, testRedraw, time.Now)
+
+	p.setPath("/srv/a")
+	p.increment()
+	p.finish()
+
+	if strings.Contains(stderr(), "/srv/a") {
+		t.Errorf("stderr = %q, want no path", stderr())
+	}
+}

internal/sfdupes/scan.go

@@ -562,6 +562,7 @@ func (s *scanState) walkPhase(events <-chan walkEvent, roots []string) {
 
 		s.st.walked++
 
+		prog.setPath(ev.rec.path)
 		prog.increment()
 
 		old, ok := s.existing[ev.rec.path]