cmd: Print a message when reading from stdin implicitly (#78)

One thing that can be confusing about the UX of the CLI is that
when you call it without any arguments,
it's reading from stdin but you may not know that.
You may assume it's just taking forever to start up.

This changes it to print a message to stderr
if it's reading from stdin because no arguments were given
and no input is read for 200 milliseconds.

Author: abhinav

CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Unreleased
+### Changed
+- cmd/errtrace:
+  Print a message when reading from stdin because no arguments were given.
+  Use '-' as the file name to read from stdin without a warning.
+
 ## v0.2.0 - 2023-11-30
 
 This release contains minor improvements to the errtrace code transformer

cmd/errtrace/main.go

@@ -25,6 +25,7 @@ package main
 
 import (
 	"bytes"
+	"errors"
 	"flag"
 	"fmt"
 	"go/ast"
@@ -38,6 +39,7 @@ import (
 	"sort"
 	"strconv"
 	"strings"
+	"time"
 )
 
 func main() {
@@ -54,6 +56,8 @@ type mainParams struct {
 	List   bool     // -l
 	Format format   // -format
 	Files  []string // list of files to process
+
+	ImplicitStdin bool // whether stdin was picked because there were no args
 }
 
 func (p *mainParams) shouldFormat() bool {
@@ -93,6 +97,7 @@ func (p *mainParams) Parse(w io.Writer, args []string) error {
 	if len(p.Files) == 0 {
 		// Read file from stdin when there's no args, similar to gofmt.
 		p.Files = []string{"-"}
+		p.ImplicitStdin = true
 	}
 
 	return nil
@@ -175,10 +180,11 @@ func (cmd *mainCmd) Run(args []string) (exitCode int) {
 
 	for _, file := range p.Files {
 		req := fileRequest{
-			Format:   p.shouldFormat(),
-			Write:    p.Write,
-			List:     p.List,
-			Filename: file,
+			Format:        p.shouldFormat(),
+			Write:         p.Write,
+			List:          p.List,
+			Filename:      file,
+			ImplicitStdin: p.ImplicitStdin,
 		}
 		if err := cmd.processFile(req); err != nil {
 			cmd.log.Printf("%s:%s", file, err)
@@ -194,6 +200,8 @@ type fileRequest struct {
 	Write    bool
 	List     bool
 	Filename string
+
+	ImplicitStdin bool
 }
 
 // processFile processes a single file.
@@ -421,15 +429,50 @@ func (cmd *mainCmd) processFile(r fileRequest) error {
 	return err
 }
 
+var _stdinWait = 200 * time.Millisecond
+
 func (cmd *mainCmd) readFile(r fileRequest) ([]byte, error) {
-	if r.Filename == "-" {
-		if r.Write {
-			return nil, fmt.Errorf("can't use -w with stdin")
-		}
+	if r.Filename != "-" {
+		return os.ReadFile(r.Filename)
+	}
+
+	if r.Write {
+		return nil, fmt.Errorf("can't use -w with stdin")
+	}
+
+	if !r.ImplicitStdin {
 		return io.ReadAll(cmd.Stdin)
 	}
 
-	return os.ReadFile(r.Filename)
+	// If we're reading from stdin because there were no other arguments,
+	// wait a short time for the first read.
+	// If there's nothing, print a warning and continue waiting.
+	firstRead := make(chan struct{})
+	go func(firstRead <-chan struct{}) {
+		select {
+		case <-firstRead:
+		case <-time.After(_stdinWait):
+			cmd.log.Println("reading from stdin; use '-h' for help")
+		}
+	}(firstRead)
+
+	var buff bytes.Buffer
+	bs := make([]byte, 1024)
+	for {
+		n, err := cmd.Stdin.Read(bs)
+		buff.Write(bs[:n])
+		if err != nil {
+			if errors.Is(err, io.EOF) {
+				err = nil
+			}
+			return buff.Bytes(), err
+		}
+
+		if firstRead != nil {
+			close(firstRead)
+			firstRead = nil
+		}
+	}
 }
 
 type walker struct {

cmd/errtrace/main_test.go

@@ -14,6 +14,7 @@ import (
 	"strconv"
 	"strings"
 	"testing"
+	"time"
 
 	"braces.dev/errtrace/internal/diff"
 )
@@ -359,7 +360,7 @@ func TestFormatAuto(t *testing.T) {
 			Stdin:  strings.NewReader("unused"),
 			Stdout: &out,
 			Stderr: &err,
-		}).Run([]string{"-w"})
+		}).Run([]string{"-w", "-"})
 		if want := 1; exitCode != want {
 			t.Errorf("exit code = %d, want %d", exitCode, want)
 		}
@@ -440,6 +441,73 @@ func _() {
 	}
 }
 
+func TestStdinNoInputMessage(t *testing.T) {
+	// Verify that if there's no input on implicit stdin,
+	// we print a message to stderr to help the user.
+	defer func(old time.Duration) { _stdinWait = old }(_stdinWait)
+	_stdinWait = 10 * time.Millisecond // make the test run faster
+
+	tests := []struct {
+		name       string
+		delay      time.Duration // before writing
+		args       []string
+		wantStderr string
+	}{
+		{
+			name:  "no delay",
+			delay: 0,
+		},
+		{
+			name:       "delay",
+			delay:      20 * time.Millisecond,
+			wantStderr: "reading from stdin; use '-h' for help\n",
+		},
+		{
+			name:  "explicit stdin with delay",
+			args:  []string{"-"},
+			delay: 20 * time.Millisecond,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			// mainCmd.Run is blocking so this has to be in a goroutine.
+			stdin, stdinw := io.Pipe()
+			done := make(chan struct{})
+			go func() {
+				defer close(done)
+
+				if tt.delay > 0 {
+					time.Sleep(20 * time.Millisecond)
+				}
+				if _, err := io.WriteString(stdinw, "package foo\n"); err != nil {
+					t.Error(err)
+				}
+
+				if err := stdinw.Close(); err != nil {
+					t.Error(err)
+				}
+			}()
+			defer func() { <-done }()
+
+			var stderr bytes.Buffer
+			exitCode := (&mainCmd{
+				Stdin:  stdin,
+				Stdout: io.Discard,
+				Stderr: &stderr,
+			}).Run(tt.args)
+
+			if want := 0; exitCode != want {
+				t.Errorf("exit code = %d, want %d", exitCode, want)
+			}
+
+			if want, got := tt.wantStderr, stderr.String(); got != want {
+				t.Errorf("stderr = %q, want %q", got, want)
+			}
+		})
+	}
+}
+
 func indent(s string) string {
 	return "\t" + strings.ReplaceAll(s, "\n", "\n\t")
 }