feat: add formatter.stdin-options to invoke formatters in stdin mode

Author: jfly

cmd/root_test.go

@@ -2254,6 +2254,31 @@ help:
 			as.Equal(`# print this message
 help:
     just --list --list-submodules --unsorted
+`, string(out))
+		}),
+	)
+
+	// Format with embed-path. `embed-path` prefixes the file with its path. If
+	// this formatter didn't support the Stdin Specification, then we'd see a
+	// temp path get added instead of the true path to the file.
+	contents = `
+The formatter should add the path above this line.
+`
+	os.Stdin = test.TempFile(t, "", "stdin", &contents)
+
+	treefmt(t,
+		withArgs("-vvv", "--stdin", "path/to/foo.embed-path"),
+		withNoError(t),
+		withStats(t, map[stats.Type]int{
+			stats.Traversed: 1,
+			stats.Matched:   1,
+			stats.Formatted: 1,
+			stats.Changed:   1,
+		}),
+		withStdout(func(out []byte) {
+			as.Equal(`# path/to/foo.embed-path
+
+The formatter should add the path above this line.
 `, string(out))
 		}),
 	)

config/config.go

@@ -57,6 +57,12 @@ type Formatter struct {
 	Command string `mapstructure:"command" toml:"command"`
 	// Options are an optional list of args to be passed to Command.
 	Options []string `mapstructure:"options,omitempty" toml:"options,omitempty"`
+	// StringOptions are an optional list of args used to invoke the formatter
+	// in stdin mode (where it reads the buffer to format from stdin rather
+	// than a file). Any occurrences of `$path` will be replaced with the "advisory path"
+	// of the "file" being formatted (useful for formatters whose behavior
+	// depend on the path of the file being formatted).
+	StdinOptions []string `mapstructure:"stdin-options,omitempty" toml:"stdin-options,omitempty"`
 	// Includes is a list of glob patterns used to determine whether this Formatter should be applied against a path.
 	Includes []string `mapstructure:"includes,omitempty" toml:"includes,omitempty"`
 	// Excludes is an optional list of glob patterns used to exclude certain files from this Formatter.

docs/site/getting-started/configure.md

@@ -460,6 +460,15 @@ The command to invoke when applying the formatter.
 
 An optional list of args to be passed to `command`.
 
+### `stdin-options`
+
+An optional list of args used to invoke the formatter in "stdin mode" (where it
+reads the buffer to format from stdin rather than a file). Any occurrences of
+`$path` will be replaced with the "advisory path" of the "file" being formatted.
+
+This is useful for formatters whose behavior depend on the path of the file being
+formatted.
+
 ### `includes`
 
 A list of [glob patterns](#glob-patterns-format) used to determine whether the formatter should be applied against a given path.

format/formatter.go

@@ -107,12 +107,41 @@ func (f *Formatter) Apply(ctx context.Context, files []*walk.File) error {
 		return nil
 	}
 
-	// append paths to the args
-	for _, file := range files {
-		if file.TmpPath != "" {
-			args = append(args, file.TmpPath)
-		} else {
-			args = append(args, file.RelPath)
+	onlyFile := (*walk.File)(nil)
+	if len(files) == 1 {
+		onlyFile = files[0]
+	}
+
+	// If we have a TmpPath, that means we're formatting something other than the  file's RelPath
+	// mode". If the underlying formatter has its own stdin mode support, then
+	// we can invoke it in a way where we pass along the files's RelPath as an
+	// "advisory path", which may affect the behavior of the formatter.
+	useStdinMode := files[0].TmpPath != "" && f.config.StdinOptions != nil
+
+	stdin := (*os.File)(nil)
+
+	if useStdinMode {
+		// Feed the file to the formatter via stdin.
+		tmpFile, err := os.Open(onlyFile.TmpPath)
+		if err != nil {
+			panic(err)
+		}
+		defer tmpFile.Close()
+
+		stdin = tmpFile
+
+		replacer := strings.NewReplacer("$path", onlyFile.RelPath)
+		for _, arg := range f.config.StdinOptions {
+			args = append(args, replacer.Replace(arg))
+		}
+	} else {
+		// append paths to the args
+		for _, file := range files {
+			if file.TmpPath != "" {
+				args = append(args, file.TmpPath)
+			} else {
+				args = append(args, file.RelPath)
+			}
 		}
 	}
 
@@ -123,11 +152,13 @@ func (f *Formatter) Apply(ctx context.Context, files []*walk.File) error {
 		return cmd.Process.Signal(os.Interrupt)
 	}
 	cmd.Dir = f.workingDir
+	cmd.Stdin = stdin
 
 	// log out the command being executed
 	f.log.Debugf("executing: %s", cmd.String())
 
-	if out, err := cmd.CombinedOutput(); err != nil {
+	out, err := cmd.CombinedOutput()
+	if err != nil {
 		f.log.Errorf("failed to apply with options '%v': %s", f.config.Options, err)
 
 		if len(out) > 0 {
@@ -137,6 +168,16 @@ func (f *Formatter) Apply(ctx context.Context, files []*walk.File) error {
 		return fmt.Errorf("formatter '%s' with options '%v' failed to apply: %w", f.config.Command, f.config.Options, err)
 	}
 
+	// In stdin mode, the formatter won't write to the filesystem, it instead
+	// prints the formatted file to stdout. Take that output and write it back
+	// to the input file (`TmpPath`).
+	if useStdinMode {
+		path := onlyFile.TmpPath
+		if err = os.WriteFile(path, out, 0o600); err != nil {
+			return fmt.Errorf("couldn't write to '%s'", path)
+		}
+	}
+
 	f.log.Infof("%v file(s) processed in %v", len(files), time.Since(start))
 
 	return nil

nix/packages/treefmt/formatters.nix

@@ -69,4 +69,35 @@ with pkgs; [
       test-fmt-append "suffix" "$1"
     '';
   })
+  (pkgs.writeShellApplication {
+    name = "test-fmt-embed-path";
+    text = ''
+      stdin_filepath=""
+      while [[ $# -gt 0 ]]; do
+        case $1 in
+            --stdin-filepath)
+                shift
+                stdin_filepath=$1
+                shift
+                ;;
+            --* | -*)
+                echo "Unknown option $1" >&2
+                exit 1
+                ;;
+            *)
+                echo "Unknown positional argument $1" >&2
+                exit 1
+                ;;
+        esac
+      done
+
+      if [ -z "$stdin_filepath" ]; then
+          echo "I only support stdin mode (use --stdin-filepath [path/to/file])." >&2
+          exit 1
+      fi
+
+      echo "# $stdin_filepath"
+      cat /dev/stdin
+    '';
+  })
 ]

test/examples/treefmt.toml

@@ -94,3 +94,8 @@ command = "foo-fmt"
 command = "just"
 options = ["--fmt", "--unstable", "--justfile"]
 includes = ["**/justfile"]
+
+[formatter.embed-path]
+command = "test-fmt-embed-path"
+includes = ["*.embed-path"]
+stdin-options = ["--stdin-filepath", "$path"]