-stdout sends error report to output file

[jespert]

Observed behaviour

On template instantiation failure, templ writes an error report to stdout. When the flag -stdout is used, this causes the error messages to be written to the file, instead of being reported back to the user via stderr.

This degrades the user experience because the feedback from the failure is hidden from the user. When templ is used from the command line, the only direct feedback is the exit code, which shells tend to hide from the user. When templ is used within most build tools, the tool will highlight the failure but give no explanation, which is generally expected to be the captured stderr output.

Expected behaviour

When the flag -stdout is used, the user receives visible feedback about the error, in both the command line and most build tools.

Suggested change

Use stdout for data output (instantiated templates), stderr for out-of-band messages such as errors and informational messages. This goes against the position stated in issue #439, but it would align templ closer to standard POSIX conventions, improve its user experience, and simplify its integration with build tools.

[a-h]

Thanks!

What's the command you're running, do you have an example reproduction?

[jespert]

Basic reproduction with just the command line

broken.templ:

package broken

templ foo() { // Missing closing brace

tools.go:

//go:build tools
package broken

import _ "github.com/a-h/templ/cmd/templ"

go.mod:

module broken

go 1.22.2

require github.com/a-h/templ v0.2.697

require (
	github.com/a-h/parse v0.0.0-20240121214402-3caf7543159a // indirect
	github.com/a-h/protocol v0.0.0-20230224160810-b4eec67c1c22 // indirect
	github.com/andybalholm/brotli v1.1.0 // indirect
	github.com/cenkalti/backoff/v4 v4.3.0 // indirect
	github.com/cli/browser v1.3.0 // indirect
	github.com/fatih/color v1.16.0 // indirect
	github.com/fsnotify/fsnotify v1.7.0 // indirect
	github.com/mattn/go-colorable v0.1.13 // indirect
	github.com/mattn/go-isatty v0.0.20 // indirect
	github.com/natefinch/atomic v1.0.1 // indirect
	github.com/segmentio/asm v1.2.0 // indirect
	github.com/segmentio/encoding v0.4.0 // indirect
	go.lsp.dev/jsonrpc2 v0.10.0 // indirect
	go.lsp.dev/pkg v0.0.0-20210717090340-384b27a52fb2 // indirect
	go.lsp.dev/uri v0.3.0 // indirect
	go.uber.org/multierr v1.11.0 // indirect
	go.uber.org/zap v1.27.0 // indirect
	golang.org/x/mod v0.17.0 // indirect
	golang.org/x/sys v0.19.0 // indirect
)

When I run:

go run github.com/a-h/templ/cmd/templ generate broken.templ -stdout > broken_templ.go

Then I see:

exit status 1

(This message wasn't there in v0.2.680, which my project is using, but it's useful -- thanks)

And these are the contents of broken_templ.go:

(!) templ version check: generator v0.2.696 is older than templ version v0.2.697 found in go.mod file, consider upgrading templ CLI
(✗) Error generating code [ file=/home/jespert/Scratch/templ/broken.templ error=/home/jespert/Scratch/templ/broken.templ parsing error: template closing brace not found: line 3, col 0 ]
(✗) Event handler failed [ error=failed to generate code for "/home/jespert/Scratch/templ/broken.templ": /home/jespert/Scratch/templ/broken.templ parsing error: template closing brace not found: line 3, col 0 ]
(✗) Error [ error=failed to generate code for "/home/jespert/Scratch/templ/broken.templ": /home/jespert/Scratch/templ/broken.templ parsing error: template closing brace not found: line 3, col 0 ]
(✗) Command failed: generation completed with 1 errors

[a-h]

I've refactored the log handling more generally to write to stderr. Help text is also written to stderr, unless --help/-h/templ help is called.

0 1 /Users/adrian/issue753test % templ generate broken.templ -stdout > broken_templ.go
(!) templ version check: generator v0.2.708 is newer than templ version v0.2.697 found in go.mod file, consider running `go get -u github.com/a-h/templ` to upgrade
(✗) Error generating code [ file=/Users/adrian/issue753test/broken.templ error=/Users/adrian/issue753test/broken.templ parsing error: template closing brace not found: line 3, col 0 ]
(✗) Event handler failed [ error=failed to generate code for "/Users/adrian/issue753test/broken.templ": /Users/adrian/issue753test/broken.templ parsing error: template closing brace not found: line 3, col 0 ]
(✗) Error [ error=failed to generate code for "/Users/adrian/issue753test/broken.templ": /Users/adrian/issue753test/broken.templ parsing error: template closing brace not found: line 3, col 0 ]
(✗) Command failed: generation completed with 1 errors
0 1 /Users/adrian/issue753test % ls
broken.templ    broken_templ.go go.mod          tools.go
0 0 /Users/adrian/issue753test % cat broken_templ.go
0 0 /Users/adrian/issue753test %