fix(cmd): long-form flags, honest counts and safer inference

Assisted-by: GLM 5.3

cmd/interpres-decode/infer.go

@@ -6,9 +6,11 @@ package main
 import (
 	"fmt"
 	"io"
+	"strconv"
 	"strings"
 	"time"
 	"unicode"
+	"unicode/utf8"
 
 	"sourcedock.dev/petrbalvin/interpres/v2"
 )
@@ -17,63 +19,115 @@ import (
 // like the document: one field per key in written order, nested tables as
 // nested struct types, an array of tables as a slice, and the field names
 // invented from the keys. It is the onboarding aid: the printed type compiles
-// and decodes the document it came from.
+// and decodes the document it came from. The definition is built whole and
+// written with a single call, so a failing standard output surfaces as one
+// error instead of being dropped mid-print.
 func inferStruct(data []byte, stdout io.Writer) error {
 	doc, err := interpres.Parse(data)
 	if err != nil {
 		return err
 	}
-	fmt.Fprintln(stdout, "// Generated by interpres-decode -struct; decode with")
-	fmt.Fprintln(stdout, "// sourcedock.dev/petrbalvin/interpres/v2.")
-	fmt.Fprintln(stdout, "type inferred struct {")
-	if err := writeInferredFields(stdout, doc.Root(), map[string]bool{}); err != nil {
-		return err
-	}
-	fmt.Fprintln(stdout, "}")
-	return nil
+	body := &strings.Builder{}
+	fmt.Fprintln(body, "// Generated by interpres-decode --struct; decode with")
+	fmt.Fprintln(body, "// sourcedock.dev/petrbalvin/interpres/v2.")
+	fmt.Fprintln(body, "type inferred struct {")
+	writeInferredFields(body, tableFields(doc.Root()), map[string]bool{})
+	fmt.Fprintln(body, "}")
+	_, err = io.WriteString(stdout, body.String())
+	return err
 }
 
-// writeInferredFields writes one field per entry of the table. invented
-// tracks the field names already used at one level, so two keys that clean
-// to the same name do not collide.
-func writeInferredFields(w io.Writer, t *interpres.Table, invented map[string]bool) error {
+// inferredField is one document key with the entry it is inferred from.
+type inferredField struct {
+	key   string
+	entry *interpres.Entry
+}
+
+// tableFields lists a table's entries in written order.
+func tableFields(t *interpres.Table) []inferredField {
+	out := make([]inferredField, 0, len(t.Keys()))
 	for _, key := range t.Keys() {
 		entry, _ := t.Get(key)
-		name := goFieldName(key, invented)
-		// An array of tables carries a node per element; the nodes of a value
-		// array are nil wherever an element is not a table, so the nils give
-		// it away.
-		var tables []*interpres.Table
-		for _, el := range entry.Elements() {
-			if el != nil {
-				tables = append(tables, el)
-			}
-		}
-		if len(tables) > 0 {
-			// The type comes from the first element.
-			fmt.Fprintf(w, "\t%s []struct {\n", name)
-			if err := writeInferredFields(w, tables[0], map[string]bool{}); err != nil {
-				return err
-			}
-			fmt.Fprintf(w, "\t} `toml:%q`\n", key)
-			continue
-		}
-		val := entry.Value()
-		if child := entry.Table(); child != nil {
-			fmt.Fprintf(w, "\t%s struct {\n", name)
-			if err := writeInferredFields(w, child, map[string]bool{}); err != nil {
-				return err
-			}
-			fmt.Fprintf(w, "\t} `toml:%q`\n", key)
-			continue
-		}
-		if items, ok := val.([]any); ok {
-			fmt.Fprintf(w, "\t%s []%s `toml:%q`\n", name, inferScalarType(items), key)
-			continue
-		}
-		fmt.Fprintf(w, "\t%s %s `toml:%q`\n", name, goTypeOf(val), key)
+		out = append(out, inferredField{key: key, entry: entry})
 	}
-	return nil
+	return out
+}
+
+// mergedTableFields merges the key sets of an array's elements in first-seen
+// order. An array's type has to cover every element, and a key may appear
+// only in a later one, so the first element alone does not decide the shape;
+// each key is inferred from the first element that carries it.
+func mergedTableFields(tables []*interpres.Table) []inferredField {
+	var out []inferredField
+	seen := map[string]bool{}
+	for _, t := range tables {
+		for _, f := range tableFields(t) {
+			if seen[f.key] {
+				continue
+			}
+			seen[f.key] = true
+			out = append(out, f)
+		}
+	}
+	return out
+}
+
+// writeInferredFields writes one field per entry, in the order given.
+// invented tracks the field names already used at one level, so two keys
+// that clean to the same name do not collide.
+func writeInferredFields(w *strings.Builder, fields []inferredField, invented map[string]bool) {
+	for _, f := range fields {
+		writeInferredField(w, f, invented)
+	}
+}
+
+// writeInferredField writes one field for one entry: an array of tables as a
+// slice of structs, a child table as a nested struct, and everything else as
+// the scalar or slice the decoded value names.
+func writeInferredField(w *strings.Builder, f inferredField, invented map[string]bool) {
+	name := goFieldName(f.key, invented)
+	// An array of tables carries a node per element; the nodes of a value
+	// array are nil wherever an element is not a table. Every node present
+	// is what tells the two apart: [1, {x=1}] stays a value array even
+	// though one of its elements is a table.
+	elements := f.entry.Elements()
+	allTables := len(elements) > 0
+	for _, el := range elements {
+		if el == nil {
+			allTables = false
+			break
+		}
+	}
+	if allTables {
+		fmt.Fprintf(w, "\t%s []struct {\n", name)
+		writeInferredFields(w, mergedTableFields(elements), map[string]bool{})
+		fmt.Fprintf(w, "\t} %s\n", structTag(f.key))
+		return
+	}
+	if child := f.entry.Table(); child != nil {
+		fmt.Fprintf(w, "\t%s struct {\n", name)
+		writeInferredFields(w, tableFields(child), map[string]bool{})
+		fmt.Fprintf(w, "\t} %s\n", structTag(f.key))
+		return
+	}
+	val := f.entry.Value()
+	if items, ok := val.([]any); ok {
+		fmt.Fprintf(w, "\t%s []%s %s\n", name, inferScalarType(items), structTag(f.key))
+		return
+	}
+	fmt.Fprintf(w, "\t%s %s %s\n", name, goTypeOf(val), structTag(f.key))
+}
+
+// structTag renders the toml tag of one key as a Go string literal. The raw
+// backtick literal is the conventional shape, but a key carrying a backtick
+// would end that literal early and the printed definition would not compile,
+// so such tags are rendered with strconv.Quote instead.
+func structTag(key string) string {
+	tag := `toml:"` + key + `"`
+	if !strings.ContainsAny(tag, "`\r") {
+		return "`" + tag + "`"
+	}
+	return strconv.Quote(tag)
 }
 
 // goTypeOf names the Go type the decoded value asks for.
@@ -106,8 +160,10 @@ func goTypeOf(val any) string {
 }
 
 // goFieldName cleans a document key into an exported Go identifier: the
-// words the punctuation splits become capitalised runs, a leading digit gains
-// an underscore, and a collision with an earlier name gains a counter.
+// words the punctuation splits become capitalised runs, a leading digit
+// gains a Field prefix, because an underscore would leave the field
+// unexported and the decoder would skip it, and a collision with an earlier
+// name gains a counter.
 func goFieldName(key string, invented map[string]bool) string {
 	var b strings.Builder
 	nextUpper := true
@@ -127,8 +183,10 @@ func goFieldName(key string, invented map[string]bool) string {
 	if name == "" {
 		name = "Field"
 	}
-	if unicode.IsDigit(rune(name[0])) {
-		name = "_" + name
+	// The first rune is decoded rather than taken as a byte, because a key
+	// may open with a digit beyond ASCII.
+	if first, _ := utf8.DecodeRuneInString(name); unicode.IsDigit(first) {
+		name = "Field" + name
 	}
 	for invented[name] {
 		name += "2"

cmd/interpres-decode/main.go

@@ -4,16 +4,16 @@
 // Command interpres-decode is the toml-test harness adapter and a TOML
 // validator. Without flags it reads a TOML document from standard input and
 // writes the toml-test "tagged JSON" representation to standard output. With
-// -encode it is the reverse: it reads tagged JSON and writes the TOML document
-// it describes. With -validate it checks the named documents, or standard
-// input when none are named, and exits non-zero on the first invalid one:
+// --encode it is the reverse: it reads tagged JSON and writes the TOML document
+// it describes. With --validate it checks the named documents, or standard
+// input when none are named, and exits non-zero when one is invalid:
 //
-//	interpres-decode -validate config.toml
-//	interpres-decode -encode < case.json
+//	interpres-decode --validate config.toml
+//	interpres-decode --encode < case.json
 //
 // Run the official suite in both directions against the adapter with:
 //
-//	toml-test test -decoder=./interpres-decode -encoder='./interpres-decode -encode'
+//	toml-test test -decoder=./interpres-decode -encoder='./interpres-decode --encode'
 package main
 
 import (
@@ -39,11 +39,16 @@ func main() {
 }
 
 // Run runs the command line and returns the process exit code: 0 success,
-// 1 an invalid document, 2 a usage, reading, encoding, or
+// 1 an invalid document, 2 a usage, reading, writing, encoding, or
 // unsupported-value error.
 func Run(args []string, stdin io.Reader, stdout, stderr io.Writer) int {
 	fs := flag.NewFlagSet("interpres-decode", flag.ContinueOnError)
-	fs.SetOutput(stderr)
+	// The flag package's own diagnostics and default usage render flags
+	// with a single dash, while the command spells every flag in its
+	// two-dash long form, the form the manpage documents. Its output is
+	// therefore discarded and the usage below is the only one printed.
+	fs.SetOutput(io.Discard)
+	fs.Usage = func() {}
 	version := fs.Bool("version", false, "print the version and exit")
 	validate := fs.Bool("validate", false, "validate the documents instead of emitting tagged JSON")
 	encode := fs.Bool("encode", false, "read tagged JSON from stdin and write TOML instead")
@@ -52,12 +57,18 @@ func Run(args []string, stdin io.Reader, stdout, stderr io.Writer) int {
 	schemaType := fs.String("schema", "", "write a TOML template for the named struct type; the source file follows as the first argument")
 	if err := fs.Parse(args); err != nil {
 		if errors.Is(err, flag.ErrHelp) {
+			usage(stdout)
 			return 0
 		}
+		fmt.Fprintf(stderr, "interpres-decode: %v\n", err)
+		usage(stderr)
 		return 2
 	}
 	if *version {
-		fmt.Fprintf(stdout, "interpres-decode %s\n", versionString())
+		if _, err := fmt.Fprintf(stdout, "interpres-decode %s\n", versionString()); err != nil {
+			fmt.Fprintln(stderr, "interpres-decode: write stdout:", err)
+			return 2
+		}
 		return 0
 	}
 	modes := 0
@@ -70,13 +81,19 @@ func Run(args []string, stdin io.Reader, stdout, stderr io.Writer) int {
 		modes++
 	}
 	if modes > 1 {
-		fmt.Fprintln(stderr, "interpres-decode: -validate, -encode, -struct and -schema cannot be combined")
+		fmt.Fprintln(stderr, "interpres-decode: --validate, --encode, --struct and --schema cannot be combined")
+		return 2
+	}
+	// --json shapes the decoding output only, so it is rejected with every
+	// mode uniformly instead of being silently ignored by some of them.
+	if *plainJSON && modes > 0 {
+		fmt.Fprintln(stderr, "interpres-decode: --json shapes the decoder output and cannot be combined with --encode, --struct, --validate or --schema")
 		return 2
 	}
 	if *schemaType != "" {
 		rest := fs.Args()
 		if len(rest) != 1 {
-			fmt.Fprintln(stderr, "interpres-decode: -schema needs the type name and exactly one Go source file")
+			fmt.Fprintln(stderr, "interpres-decode: --schema needs the type name and exactly one Go source file")
 			return 2
 		}
 		if err := runSchema(*schemaType, rest[0], stdout); err != nil {
@@ -88,12 +105,8 @@ func Run(args []string, stdin io.Reader, stdout, stderr io.Writer) int {
 	if *validate {
 		return validatePaths(fs.Args(), stdin, stderr)
 	}
-	if *encode && *plainJSON {
-		fmt.Fprintln(stderr, "interpres-decode: -json shapes the decoder output and cannot be combined with -encode")
-		return 2
-	}
 	if fs.NArg() > 0 {
-		fmt.Fprintln(stderr, "interpres-decode: the adapter mode takes no arguments; name files with -validate")
+		fmt.Fprintln(stderr, "interpres-decode: the adapter mode takes no arguments; name files with --validate")
 		return 2
 	}
 	if *encode {
@@ -101,19 +114,25 @@ func Run(args []string, stdin io.Reader, stdout, stderr io.Writer) int {
 	}
 	data, err := io.ReadAll(stdin)
 	if err != nil {
-		fmt.Fprintln(stderr, "read stdin:", err)
+		fmt.Fprintln(stderr, "interpres-decode: read stdin:", err)
 		return 2
 	}
 	if *infer {
 		if err := inferStruct(data, stdout); err != nil {
 			fmt.Fprintf(stderr, "interpres-decode: %v\n", err)
-			return 1
+			// A document that fails to parse keeps the adapter's invalid
+			// exit; anything else, a failed write among them, is a tool
+			// failure.
+			if _, ok := errors.AsType[*interpres.SyntaxError](err); ok {
+				return 1
+			}
+			return 2
 		}
 		return 0
 	}
 	tree, err := interpres.ParseMap(data)
 	if err != nil {
-		fmt.Fprintln(stderr, err)
+		fmt.Fprintf(stderr, "interpres-decode: %v\n", err)
 		return 1
 	}
 	if *plainJSON {
@@ -121,25 +140,48 @@ func Run(args []string, stdin io.Reader, stdout, stderr io.Writer) int {
 		enc.SetEscapeHTML(false)
 		enc.SetIndent("", "  ")
 		if err := enc.Encode(plainJSONValue(tree)); err != nil {
-			fmt.Fprintln(stderr, "encode:", err)
+			fmt.Fprintln(stderr, "interpres-decode: encode:", err)
 			return 2
 		}
 		return 0
 	}
 	tagged, err := tag(tree)
 	if err != nil {
-		fmt.Fprintln(stderr, err)
+		fmt.Fprintf(stderr, "interpres-decode: %v\n", err)
 		return 2
 	}
 	enc := json.NewEncoder(stdout)
 	enc.SetEscapeHTML(false)
 	if err := enc.Encode(tagged); err != nil {
-		fmt.Fprintln(stderr, "encode:", err)
+		fmt.Fprintln(stderr, "interpres-decode: encode:", err)
 		return 2
 	}
 	return 0
 }
 
+// usage prints the command line summary, with every flag in its two-dash
+// long form: the flag package's default usage printer renders a single dash,
+// and the manpage and docs/CLI.md spell the flags the way this text does.
+func usage(w io.Writer) {
+	fmt.Fprint(w, `Usage: interpres-decode [flags]
+
+Without a mode flag the command reads one TOML document from standard input
+and writes the toml-test tagged JSON representation to standard output.
+
+  --encode            read tagged JSON from standard input and write TOML
+                      instead
+  --help              print this usage
+  --json              with the default mode, print plain indented JSON
+                      instead of tagged JSON
+  --schema TYPE       write a TOML template for the named struct type; the
+                      Go source file follows as the first argument
+  --struct            infer a Go struct definition from the document on
+                      standard input and print it
+  --validate          validate the documents instead of emitting tagged JSON
+  --version           print the version and exit
+`)
+}
+
 // versionString names the version the binary was built at: the module
 // version the toolchain recorded, which is the tag when the release pipeline
 // builds it, and (devel) for an ordinary build from a working tree.
@@ -226,8 +268,8 @@ func validatePaths(paths []string, stdin io.Reader, stderr io.Writer) int {
 			return 2
 		}
 	}
-	valid := true
 	checked := 0
+	invalid := 0
 	for _, p := range files {
 		name := p
 		var data []byte
@@ -244,17 +286,17 @@ func validatePaths(paths []string, stdin io.Reader, stderr io.Writer) int {
 		}
 		checked++
 		if _, err := interpres.ParseMap(data); err != nil {
-			fmt.Fprintf(stderr, "%s: %v\n", name, err)
-			valid = false
+			fmt.Fprintf(stderr, "interpres-decode: %s: %v\n", name, err)
+			invalid++
 		}
 	}
 	// The single-document run stays quiet on success, the contract the
 	// compliance tooling relies on; a directory walk closes with the
 	// summary that makes the sweep readable.
 	if dirs > 0 {
-		fmt.Fprintf(stderr, "checked %d documents, %d invalid\n", checked, map[bool]int{true: 0, false: 1}[valid])
+		fmt.Fprintf(stderr, "checked %d documents, %d invalid\n", checked, invalid)
 	}
-	if !valid {
+	if invalid > 0 {
 		return 1
 	}
 	return 0
@@ -265,17 +307,17 @@ func validatePaths(paths []string, stdin io.Reader, stderr io.Writer) int {
 func encodeJSON(stdin io.Reader, stdout, stderr io.Writer) int {
 	data, err := io.ReadAll(stdin)
 	if err != nil {
-		fmt.Fprintln(stderr, "read stdin:", err)
+		fmt.Fprintln(stderr, "interpres-decode: read stdin:", err)
 		return 2
 	}
 	var desc any
 	if err := json.Unmarshal(data, &desc); err != nil {
-		fmt.Fprintln(stderr, "decode JSON:", err)
+		fmt.Fprintln(stderr, "interpres-decode: decode JSON:", err)
 		return 2
 	}
 	tree, err := untag(desc)
 	if err != nil {
-		fmt.Fprintln(stderr, err)
+		fmt.Fprintf(stderr, "interpres-decode: %v\n", err)
 		return 2
 	}
 	doc, ok := tree.(map[string]any)
@@ -285,11 +327,11 @@ func encodeJSON(stdin io.Reader, stdout, stderr io.Writer) int {
 	}
 	out, err := interpres.Marshal(doc)
 	if err != nil {
-		fmt.Fprintln(stderr, err)
+		fmt.Fprintf(stderr, "interpres-decode: %v\n", err)
 		return 2
 	}
 	if _, err := stdout.Write(out); err != nil {
-		fmt.Fprintln(stderr, "write stdout:", err)
+		fmt.Fprintln(stderr, "interpres-decode: write stdout:", err)
 		return 2
 	}
 	return 0

cmd/interpres-decode/main_test.go

@@ -7,6 +7,8 @@ import (
 	"bytes"
 	"encoding/json"
 	"errors"
+	"go/parser"
+	"go/token"
 	"os"
 	"path/filepath"
 	"reflect"
@@ -217,7 +219,7 @@ func TestTaggedHelper(t *testing.T) {
 func TestValidateStdinAcceptsValidDocument(t *testing.T) {
 	var stdout, stderr bytes.Buffer
 	in := bytes.NewReader([]byte("title = \"ok\"\n"))
-	if code := Run([]string{"-validate"}, in, &stdout, &stderr); code != 0 {
+	if code := Run([]string{"--validate"}, in, &stdout, &stderr); code != 0 {
 		t.Fatalf("Run returned %d, stderr = %q", code, stderr.String())
 	}
 	if stdout.Len() != 0 || stderr.Len() != 0 {
@@ -228,7 +230,7 @@ func TestValidateStdinAcceptsValidDocument(t *testing.T) {
 func TestValidateStdinRejectsInvalidDocument(t *testing.T) {
 	var stdout, stderr bytes.Buffer
 	in := bytes.NewReader([]byte("title = \"unterminated\n"))
-	if code := Run([]string{"-validate"}, in, &stdout, &stderr); code != 1 {
+	if code := Run([]string{"--validate"}, in, &stdout, &stderr); code != 1 {
 		t.Fatalf("Run returned %d, want 1; stderr = %q", code, stderr.String())
 	}
 	if !strings.Contains(stderr.String(), "<stdin>") || !strings.Contains(stderr.String(), "line 1") {
@@ -250,10 +252,10 @@ func TestValidateFiles(t *testing.T) {
 		t.Fatal(err)
 	}
 	var stdout, stderr bytes.Buffer
-	if code := Run([]string{"-validate", good}, nil, &stdout, &stderr); code != 0 {
+	if code := Run([]string{"--validate", good}, nil, &stdout, &stderr); code != 0 {
 		t.Fatalf("one valid file: Run returned %d, stderr = %q", code, stderr.String())
 	}
-	if code := Run([]string{"-validate", good, bad}, nil, &stdout, &stderr); code != 1 {
+	if code := Run([]string{"--validate", good, bad}, nil, &stdout, &stderr); code != 1 {
 		t.Fatalf("valid plus invalid: Run returned %d, want 1; stderr = %q", code, stderr.String())
 	}
 	if !strings.Contains(stderr.String(), bad) || !strings.Contains(stderr.String(), "line 1") {
@@ -263,7 +265,7 @@ func TestValidateFiles(t *testing.T) {
 
 func TestValidateMissingFileReturnsTwo(t *testing.T) {
 	var stdout, stderr bytes.Buffer
-	if code := Run([]string{"-validate", "no-such-file.toml"}, nil, &stdout, &stderr); code != 2 {
+	if code := Run([]string{"--validate", "no-such-file.toml"}, nil, &stdout, &stderr); code != 2 {
 		t.Fatalf("Run returned %d, want 2; stderr = %q", code, stderr.String())
 	}
 }
@@ -274,14 +276,14 @@ func TestAdapterModeRejectsPositionalArgument(t *testing.T) {
 	if code := Run([]string{"file.toml"}, in, &stdout, &stderr); code != 2 {
 		t.Fatalf("Run returned %d, want 2; stderr = %q", code, stderr.String())
 	}
-	if !strings.Contains(stderr.String(), "-validate") {
-		t.Fatalf("stderr = %q, want it to point at -validate", stderr.String())
+	if !strings.Contains(stderr.String(), "--validate") {
+		t.Fatalf("stderr = %q, want it to point at --validate", stderr.String())
 	}
 }
 
 func TestUnknownFlagReturnsTwo(t *testing.T) {
 	var stdout, stderr bytes.Buffer
-	if code := Run([]string{"-nope"}, nil, &stdout, &stderr); code != 2 {
+	if code := Run([]string{"--nope"}, nil, &stdout, &stderr); code != 2 {
 		t.Fatalf("Run returned %d, want 2; stderr = %q", code, stderr.String())
 	}
 }
@@ -303,7 +305,7 @@ func TestRunEncoderScalars(t *testing.T) {
 }
 `
 	var stdout, stderr bytes.Buffer
-	code := Run([]string{"-encode"}, strings.NewReader(in), &stdout, &stderr)
+	code := Run([]string{"--encode"}, strings.NewReader(in), &stdout, &stderr)
 	if code != 0 {
 		t.Fatalf("Run returned %d, stderr = %q", code, stderr.String())
 	}
@@ -334,7 +336,7 @@ func TestRunEncoderNested(t *testing.T) {
 }
 `
 	var stdout, stderr bytes.Buffer
-	code := Run([]string{"-encode"}, strings.NewReader(in), &stdout, &stderr)
+	code := Run([]string{"--encode"}, strings.NewReader(in), &stdout, &stderr)
 	if code != 0 {
 		t.Fatalf("Run returned %d, stderr = %q", code, stderr.String())
 	}
@@ -355,7 +357,7 @@ func TestRunEncoderFloatTagDecides(t *testing.T) {
 	// tag decides the type; the output must stay a float.
 	var stdout, stderr bytes.Buffer
 	in := `{"whole": {"type": "float", "value": "1"}, "exp": {"type": "float", "value": "5e+22"}}`
-	code := Run([]string{"-encode"}, strings.NewReader(in), &stdout, &stderr)
+	code := Run([]string{"--encode"}, strings.NewReader(in), &stdout, &stderr)
 	if code != 0 {
 		t.Fatalf("Run returned %d, stderr = %q", code, stderr.String())
 	}
@@ -380,7 +382,7 @@ func TestRunEncoderRejectsBadInput(t *testing.T) {
 	}
 	for _, c := range cases {
 		var stdout, stderr bytes.Buffer
-		code := Run([]string{"-encode"}, strings.NewReader(c.in), &stdout, &stderr)
+		code := Run([]string{"--encode"}, strings.NewReader(c.in), &stdout, &stderr)
 		if code != 2 {
 			t.Errorf("%s: Run returned %d, want 2; stderr = %q", c.name, code, stderr.String())
 			continue
@@ -396,7 +398,7 @@ func TestRunEncoderRejectsBadInput(t *testing.T) {
 
 func TestRunEncoderFlagConflicts(t *testing.T) {
 	var stdout, stderr bytes.Buffer
-	if code := Run([]string{"-encode", "-validate"}, strings.NewReader(""), &stdout, &stderr); code != 2 {
+	if code := Run([]string{"--encode", "--validate"}, strings.NewReader(""), &stdout, &stderr); code != 2 {
 		t.Errorf("Run returned %d, want 2 for the two modes together", code)
 	}
 	if !strings.Contains(stderr.String(), "cannot be combined") {
@@ -405,7 +407,7 @@ func TestRunEncoderFlagConflicts(t *testing.T) {
 
 	stdout.Reset()
 	stderr.Reset()
-	if code := Run([]string{"-encode", "file.json"}, strings.NewReader(""), &stdout, &stderr); code != 2 {
+	if code := Run([]string{"--encode", "file.json"}, strings.NewReader(""), &stdout, &stderr); code != 2 {
 		t.Errorf("Run returned %d, want 2 for an argument", code)
 	}
 }
@@ -432,7 +434,7 @@ n = "a"
 		t.Fatalf("decode returned %d, stderr = %q", code, stderr.String())
 	}
 	var out bytes.Buffer
-	if code := Run([]string{"-encode"}, bytes.NewReader(tagged.Bytes()), &out, &stderr); code != 0 {
+	if code := Run([]string{"--encode"}, bytes.NewReader(tagged.Bytes()), &out, &stderr); code != 0 {
 		t.Fatalf("encode returned %d, stderr = %q", code, stderr.String())
 	}
 	want, err := interpres.ParseMap([]byte(doc))
@@ -450,7 +452,7 @@ n = "a"
 
 func TestRunVersion(t *testing.T) {
 	var stdout, stderr bytes.Buffer
-	code := Run([]string{"-version"}, strings.NewReader(""), &stdout, &stderr)
+	code := Run([]string{"--version"}, strings.NewReader(""), &stdout, &stderr)
 	if code != 0 {
 		t.Fatalf("Run returned %d, want 0; stderr = %q", code, stderr.String())
 	}
@@ -463,7 +465,7 @@ func TestRunVersion(t *testing.T) {
 func TestRunPlainJSON(t *testing.T) {
 	var stdout, stderr bytes.Buffer
 	in := strings.NewReader("host = \"db\"\nwhen = 1979-05-27T07:32:00-07:00\nitems = [1, 2]\n")
-	code := Run([]string{"-json"}, in, &stdout, &stderr)
+	code := Run([]string{"--json"}, in, &stdout, &stderr)
 	if code != 0 {
 		t.Fatalf("Run returned %d, want 0; stderr = %q", code, stderr.String())
 	}
@@ -481,18 +483,31 @@ func TestRunPlainJSON(t *testing.T) {
 
 func TestValidateDirectorySummary(t *testing.T) {
 	dir := t.TempDir()
-	os.WriteFile(filepath.Join(dir, "good.toml"), []byte("a = 1\n"), 0o644)
-	os.WriteFile(filepath.Join(dir, "bad.toml"), []byte("a =\n"), 0o644)
+	if err := os.WriteFile(filepath.Join(dir, "good.toml"), []byte("a = 1\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "bad.toml"), []byte("a =\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
 	sub := filepath.Join(dir, "nested")
-	os.Mkdir(sub, 0o755)
-	os.WriteFile(filepath.Join(sub, "deep.toml"), []byte("b = true\n"), 0o644)
+	if err := os.Mkdir(sub, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(sub, "deep.toml"), []byte("b = true\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	// A second invalid document, so the summary's invalid count is
+	// exercised beyond the single failure the boolean tracked.
+	if err := os.WriteFile(filepath.Join(sub, "worse.toml"), []byte("c =\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
 
 	var stdout, stderr bytes.Buffer
-	code := Run([]string{"-validate", dir}, strings.NewReader(""), &stdout, &stderr)
+	code := Run([]string{"--validate", dir}, strings.NewReader(""), &stdout, &stderr)
 	if code != 1 {
-		t.Fatalf("Run returned %d, want 1 for a directory with an invalid file", code)
+		t.Fatalf("Run returned %d, want 1 for a directory with invalid files", code)
 	}
-	if !strings.Contains(stderr.String(), "checked 3 documents, 1 invalid") {
+	if !strings.Contains(stderr.String(), "checked 4 documents, 2 invalid") {
 		t.Errorf("stderr = %q, want the summary", stderr.String())
 	}
 }
@@ -500,7 +515,7 @@ func TestValidateDirectorySummary(t *testing.T) {
 func TestInferStruct(t *testing.T) {
 	var stdout, stderr bytes.Buffer
 	in := strings.NewReader("host = \"db\"\nport = 5432\ntags = [\"a\"]\n\n[server]\nname = \"edge\"\n\n[[items]]\nn = 1\n")
-	code := Run([]string{"-struct"}, in, &stdout, &stderr)
+	code := Run([]string{"--struct"}, in, &stdout, &stderr)
 	if code != 0 {
 		t.Fatalf("Run returned %d, want 0; stderr = %q", code, stderr.String())
 	}
@@ -545,7 +560,7 @@ type Item struct {
 		t.Fatal(err)
 	}
 	var stdout, stderr bytes.Buffer
-	code := Run([]string{"-schema", "Config", src}, strings.NewReader(""), &stdout, &stderr)
+	code := Run([]string{"--schema", "Config", src}, strings.NewReader(""), &stdout, &stderr)
 	if code != 0 {
 		t.Fatalf("Run returned %d, want 0; stderr = %q", code, stderr.String())
 	}
@@ -572,7 +587,7 @@ func TestRunPlainJSONShapes(t *testing.T) {
 	var stdout, stderr bytes.Buffer
 	in := strings.NewReader("when = 1979-05-27T07:32:00-07:00\nd = 1979-05-27\nt = 07:32:00\nwall = 1979-05-27T07:32:00\n" +
 		"items = [1, \"two\"]\n\n[[tables]]\nx = true\n")
-	code := Run([]string{"-json"}, in, &stdout, &stderr)
+	code := Run([]string{"--json"}, in, &stdout, &stderr)
 	if code != 0 {
 		t.Fatalf("Run returned %d, want 0; stderr = %q", code, stderr.String())
 	}
@@ -594,7 +609,7 @@ func TestRunPlainJSONShapes(t *testing.T) {
 func TestInferStructScalarShapes(t *testing.T) {
 	var stdout, stderr bytes.Buffer
 	in := strings.NewReader("f = 1.5\nb = true\nd = 1979-05-27\nldt = 1979-05-27T07:32:00\nlt = 07:32:00\nnums = [1, 2, 3]\nmixed = [1, \"a\"]\nempty = []\n")
-	code := Run([]string{"-struct"}, in, &stdout, &stderr)
+	code := Run([]string{"--struct"}, in, &stdout, &stderr)
 	if code != 0 {
 		t.Fatalf("Run returned %d, want 0; stderr = %q", code, stderr.String())
 	}
@@ -614,3 +629,372 @@ func TestInferStructScalarShapes(t *testing.T) {
 		}
 	}
 }
+
+func TestRunHelpPrintsLongFlags(t *testing.T) {
+	var stdout, stderr bytes.Buffer
+	code := Run([]string{"--help"}, strings.NewReader(""), &stdout, &stderr)
+	if code != 0 {
+		t.Fatalf("Run returned %d, want 0; stderr = %q", code, stderr.String())
+	}
+	out := stdout.String()
+	for _, flag := range []string{"--encode", "--help", "--json", "--schema", "--struct", "--validate", "--version"} {
+		if !strings.Contains(out, flag) {
+			t.Errorf("usage output missing %q:\n%s", flag, out)
+		}
+	}
+	// Every flag line of the list names its flag in the two-dash long form
+	// only, so no line opens with a single dash.
+	for line := range strings.SplitSeq(strings.TrimRight(out, "\n"), "\n") {
+		if after, ok := strings.CutPrefix(line, "  -"); ok && !strings.HasPrefix(after, "-") {
+			t.Errorf("usage line %q lists a flag with one dash", line)
+		}
+	}
+}
+
+func TestGoFieldName(t *testing.T) {
+	cases := []struct{ key, want string }{
+		{"host", "Host"},
+		{"ab", "Ab"},
+		{"http-host", "HttpHost"},
+		{"3d", "Field3d"},
+		{"", "Field"},
+	}
+	for _, c := range cases {
+		if got := goFieldName(c.key, map[string]bool{}); got != c.want {
+			t.Errorf("goFieldName(%q) = %q, want %q", c.key, got, c.want)
+		}
+	}
+}
+
+func TestGoFieldNameCollision(t *testing.T) {
+	// Two keys that clean to the same name must not collide; the counter
+	// keeps the fields apart and both stay exported.
+	invented := map[string]bool{}
+	cases := []struct{ key, want string }{
+		{"a-b", "AB"},
+		{"a b", "AB2"},
+		{"a_b", "AB22"},
+	}
+	for _, c := range cases {
+		if got := goFieldName(c.key, invented); got != c.want {
+			t.Errorf("goFieldName(%q) = %q, want %q", c.key, got, c.want)
+		}
+	}
+}
+
+func TestInferStructDigitLeadingKey(t *testing.T) {
+	var stdout, stderr bytes.Buffer
+	code := Run([]string{"--struct"}, strings.NewReader("3d = true\n"), &stdout, &stderr)
+	if code != 0 {
+		t.Fatalf("Run returned %d, want 0; stderr = %q", code, stderr.String())
+	}
+	if !strings.Contains(stdout.String(), "Field3d bool") {
+		t.Errorf("output missing the exported Field3d field:\n%s", stdout.String())
+	}
+}
+
+func TestInferStructBacktickKey(t *testing.T) {
+	// A backtick in the key would end a raw string literal early, so the
+	// tag has to be rendered as an interpreted literal instead.
+	var stdout, stderr bytes.Buffer
+	code := Run([]string{"--struct"}, strings.NewReader("\"a`b\" = 1\n"), &stdout, &stderr)
+	if code != 0 {
+		t.Fatalf("Run returned %d, want 0; stderr = %q", code, stderr.String())
+	}
+	out := stdout.String()
+	if !strings.Contains(out, "AB int64 \"toml:\\\"a`b\\\"\"") {
+		t.Errorf("output missing the quoted tag:\n%s", out)
+	}
+	// The printed definition has to compile; parsing it as Go is the
+	// syntax half of that proof.
+	if _, err := parser.ParseFile(token.NewFileSet(), "inferred.go", "package p\n\n"+out, 0); err != nil {
+		t.Errorf("the printed definition does not parse: %v\n%s", err, out)
+	}
+}
+
+func TestInferStructMergesArrayElements(t *testing.T) {
+	// The second element carries a key the first lacks, so the slice type
+	// has to be inferred from both.
+	var stdout, stderr bytes.Buffer
+	in := strings.NewReader("[[items]]\nn = 1\n\n[[items]]\nextra = \"late\"\n")
+	code := Run([]string{"--struct"}, in, &stdout, &stderr)
+	if code != 0 {
+		t.Fatalf("Run returned %d, want 0; stderr = %q", code, stderr.String())
+	}
+	out := stdout.String()
+	for _, want := range []string{
+		"Items []struct {",
+		"N int64 `toml:\"n\"`",
+		"Extra string `toml:\"extra\"`",
+	} {
+		if !strings.Contains(out, want) {
+			t.Errorf("output missing %q:\n%s", want, out)
+		}
+	}
+}
+
+func TestInferStructMixedArrayStaysValueArray(t *testing.T) {
+	// One table element does not make the array an array of tables; a
+	// struct slice would not decode the scalar element.
+	var stdout, stderr bytes.Buffer
+	code := Run([]string{"--struct"}, strings.NewReader("arr = [1, {x = 1}]\n"), &stdout, &stderr)
+	if code != 0 {
+		t.Fatalf("Run returned %d, want 0; stderr = %q", code, stderr.String())
+	}
+	out := stdout.String()
+	if !strings.Contains(out, "Arr []any") {
+		t.Errorf("output = %q, want a value array typed []any", out)
+	}
+	if strings.Contains(out, "[]struct") {
+		t.Errorf("output = %q, a mixed array must not become a struct slice", out)
+	}
+}
+
+func TestRunStructParseError(t *testing.T) {
+	var stdout, stderr bytes.Buffer
+	code := Run([]string{"--struct"}, strings.NewReader("a =\n"), &stdout, &stderr)
+	if code != 1 {
+		t.Fatalf("Run returned %d, want 1 (parse error); stderr = %q", code, stderr.String())
+	}
+	if stdout.Len() != 0 {
+		t.Errorf("stdout should be empty on parse error, got %q", stdout.String())
+	}
+	if !strings.Contains(stderr.String(), "line 1") {
+		t.Errorf("stderr = %q, want the library's line number", stderr.String())
+	}
+}
+
+func TestRunStructWriteFailure(t *testing.T) {
+	var stderr bytes.Buffer
+	code := Run([]string{"--struct"}, strings.NewReader("a = 1\n"), errorWriter{}, &stderr)
+	if code != 2 {
+		t.Fatalf("Run returned %d, want 2 (write error); stderr = %q", code, stderr.String())
+	}
+}
+
+func TestRunSchemaNeedsTypeAndExactlyOneFile(t *testing.T) {
+	for _, args := range [][]string{{"--schema", "Config"}, {"--schema", "Config", "a.go", "b.go"}} {
+		var stdout, stderr bytes.Buffer
+		code := Run(args, strings.NewReader(""), &stdout, &stderr)
+		if code != 2 {
+			t.Errorf("Run(%v) returned %d, want 2", args, code)
+		}
+		if !strings.Contains(stderr.String(), "--schema") {
+			t.Errorf("Run(%v) stderr = %q, want it to name --schema", args, stderr.String())
+		}
+	}
+}
+
+func TestRunSchemaUnparsableSource(t *testing.T) {
+	src := filepath.Join(t.TempDir(), "broken.go")
+	if err := os.WriteFile(src, []byte("this is not Go\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	var stdout, stderr bytes.Buffer
+	code := Run([]string{"--schema", "Config", src}, strings.NewReader(""), &stdout, &stderr)
+	if code != 2 {
+		t.Fatalf("Run returned %d, want 2; stderr = %q", code, stderr.String())
+	}
+	if !strings.Contains(stderr.String(), "broken.go") {
+		t.Errorf("stderr = %q, want it to name the source file", stderr.String())
+	}
+}
+
+func TestRunSchemaUnknownType(t *testing.T) {
+	src := filepath.Join(t.TempDir(), "config.go")
+	body := "package cfg\n\ntype Config struct {\n\tA int `toml:\"a\"`\n}\n"
+	if err := os.WriteFile(src, []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	var stdout, stderr bytes.Buffer
+	code := Run([]string{"--schema", "Missing", src}, strings.NewReader(""), &stdout, &stderr)
+	if code != 2 {
+		t.Fatalf("Run returned %d, want 2; stderr = %q", code, stderr.String())
+	}
+	if !strings.Contains(stderr.String(), `no struct type "Missing"`) {
+		t.Errorf("stderr = %q, want it to name the missing type", stderr.String())
+	}
+}
+
+func TestRunSchemaRecursiveType(t *testing.T) {
+	// A self-referential struct has no finite template; the generator has
+	// to name the recursion instead of exhausting the stack.
+	src := filepath.Join(t.TempDir(), "node.go")
+	body := "package cfg\n\ntype Node struct {\n\tNext *Node `toml:\"next\"`\n}\n"
+	if err := os.WriteFile(src, []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	var stdout, stderr bytes.Buffer
+	code := Run([]string{"--schema", "Node", src}, strings.NewReader(""), &stdout, &stderr)
+	if code != 2 {
+		t.Fatalf("Run returned %d, want 2; stderr = %q", code, stderr.String())
+	}
+	for _, want := range []string{"recursive", "Node"} {
+		if !strings.Contains(stderr.String(), want) {
+			t.Errorf("stderr = %q, want it to mention %q", stderr.String(), want)
+		}
+	}
+}
+
+func TestRunSchemaMultiNameField(t *testing.T) {
+	// A field list may name several fields of one type; each name is one
+	// TOML key.
+	src := filepath.Join(t.TempDir(), "range.go")
+	if err := os.WriteFile(src, []byte("package cfg\n\ntype Range struct {\n\tMin, Max int\n}\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	var stdout, stderr bytes.Buffer
+	code := Run([]string{"--schema", "Range", src}, strings.NewReader(""), &stdout, &stderr)
+	if code != 0 {
+		t.Fatalf("Run returned %d, want 0; stderr = %q", code, stderr.String())
+	}
+	out := stdout.String()
+	for _, want := range []string{"min = 0", "max = 0"} {
+		if !strings.Contains(out, want) {
+			t.Errorf("output missing %q:\n%s", want, out)
+		}
+	}
+}
+
+func TestRunSchemaEmbeddedStructs(t *testing.T) {
+	// The library inlines only untagged embedded structs; a tagged one
+	// keeps its own section.
+	src := filepath.Join(t.TempDir(), "embed.go")
+	body := `package cfg
+
+type Inner struct {
+	X int ` + "`toml:\"x\"`" + `
+}
+
+type Tagged struct {
+	Inner ` + "`toml:\"inner\"`" + `
+	Y int  ` + "`toml:\"y\"`" + `
+}
+
+type Flat struct {
+	Inner
+	Z int ` + "`toml:\"z\"`" + `
+}
+`
+	if err := os.WriteFile(src, []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	var stdout, stderr bytes.Buffer
+	code := Run([]string{"--schema", "Tagged", src}, strings.NewReader(""), &stdout, &stderr)
+	if code != 0 {
+		t.Fatalf("Tagged: Run returned %d, want 0; stderr = %q", code, stderr.String())
+	}
+	out := stdout.String()
+	if !strings.Contains(out, "y = 0") || !strings.Contains(out, "[inner]") {
+		t.Errorf("Tagged output = %q, want a y scalar and an [inner] section", out)
+	}
+
+	stdout.Reset()
+	stderr.Reset()
+	code = Run([]string{"--schema", "Flat", src}, strings.NewReader(""), &stdout, &stderr)
+	if code != 0 {
+		t.Fatalf("Flat: Run returned %d, want 0; stderr = %q", code, stderr.String())
+	}
+	out = stdout.String()
+	if !strings.Contains(out, "x = 0") || !strings.Contains(out, "z = 0") {
+		t.Errorf("Flat output = %q, want x and z flattened as scalars", out)
+	}
+	if strings.Contains(out, "[inner]") {
+		t.Errorf("Flat output = %q, an untagged embedded struct must not become a section", out)
+	}
+}
+
+func TestRunVersionWriteFailure(t *testing.T) {
+	var stderr bytes.Buffer
+	code := Run([]string{"--version"}, strings.NewReader(""), errorWriter{}, &stderr)
+	if code != 2 {
+		t.Fatalf("Run returned %d, want 2 (write error); stderr = %q", code, stderr.String())
+	}
+	if !strings.Contains(stderr.String(), "write stdout") {
+		t.Errorf("stderr = %q, want it to mention the failed write", stderr.String())
+	}
+}
+
+func TestRunSchemaWriteFailure(t *testing.T) {
+	src := filepath.Join(t.TempDir(), "config.go")
+	body := "package cfg\n\ntype Config struct {\n\tA int `toml:\"a\"`\n}\n"
+	if err := os.WriteFile(src, []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	var stderr bytes.Buffer
+	code := Run([]string{"--schema", "Config", src}, strings.NewReader(""), errorWriter{}, &stderr)
+	if code != 2 {
+		t.Fatalf("Run returned %d, want 2 (write error); stderr = %q", code, stderr.String())
+	}
+}
+
+func TestRunEncodeWriteFailure(t *testing.T) {
+	var stderr bytes.Buffer
+	in := `{"a": {"type": "integer", "value": "1"}}`
+	code := Run([]string{"--encode"}, strings.NewReader(in), errorWriter{}, &stderr)
+	if code != 2 {
+		t.Fatalf("Run returned %d, want 2 (write error); stderr = %q", code, stderr.String())
+	}
+	if !strings.Contains(stderr.String(), "write stdout") {
+		t.Errorf("stderr = %q, want it to mention the failed write", stderr.String())
+	}
+}
+
+func TestRunEmptyInput(t *testing.T) {
+	t.Run("default", func(t *testing.T) {
+		var stdout, stderr bytes.Buffer
+		code := Run(nil, strings.NewReader(""), &stdout, &stderr)
+		if code != 0 {
+			t.Fatalf("Run returned %d, want 0; stderr = %q", code, stderr.String())
+		}
+		if strings.TrimSpace(stdout.String()) != "{}" {
+			t.Errorf("stdout = %q, want an empty table", stdout.String())
+		}
+	})
+	t.Run("encode", func(t *testing.T) {
+		var stdout, stderr bytes.Buffer
+		code := Run([]string{"--encode"}, strings.NewReader(""), &stdout, &stderr)
+		if code != 2 {
+			t.Fatalf("Run returned %d, want 2, empty input is not JSON", code)
+		}
+	})
+	t.Run("struct", func(t *testing.T) {
+		var stdout, stderr bytes.Buffer
+		code := Run([]string{"--struct"}, strings.NewReader(""), &stdout, &stderr)
+		if code != 0 {
+			t.Fatalf("Run returned %d, want 0; stderr = %q", code, stderr.String())
+		}
+		if !strings.Contains(stdout.String(), "type inferred struct {\n}") {
+			t.Errorf("stdout = %q, want an empty struct", stdout.String())
+		}
+	})
+	t.Run("validate", func(t *testing.T) {
+		var stdout, stderr bytes.Buffer
+		code := Run([]string{"--validate"}, strings.NewReader(""), &stdout, &stderr)
+		if code != 0 {
+			t.Fatalf("Run returned %d, want 0; stderr = %q", code, stderr.String())
+		}
+		if stdout.Len() != 0 || stderr.Len() != 0 {
+			t.Errorf("validate should be quiet, stdout %q stderr %q", stdout.String(), stderr.String())
+		}
+	})
+}
+
+func TestRunJSONFlagConflicts(t *testing.T) {
+	for _, args := range [][]string{
+		{"--encode", "--json"},
+		{"--struct", "--json"},
+		{"--validate", "--json"},
+		{"--json", "--schema", "Config", "config.go"},
+	} {
+		var stdout, stderr bytes.Buffer
+		code := Run(args, strings.NewReader(""), &stdout, &stderr)
+		if code != 2 {
+			t.Errorf("Run(%v) returned %d, want 2", args, code)
+		}
+		if !strings.Contains(stderr.String(), "--json") {
+			t.Errorf("Run(%v) stderr = %q, want it to explain the --json conflict", args, stderr.String())
+		}
+	}
+}

cmd/interpres-decode/schema.go

@@ -9,8 +9,10 @@ import (
 	"go/parser"
 	"go/token"
 	"io"
+	"maps"
 	"path/filepath"
 	"reflect"
+	"slices"
 	"strconv"
 	"strings"
 )
@@ -34,7 +36,9 @@ func runSchema(typeName, sourcePath string, stdout io.Writer) error {
 		return fmt.Errorf("no struct type %q in %s", typeName, filepath.Base(sourcePath))
 	}
 	body := &strings.Builder{}
-	writeSchemaFields(body, st, types, "")
+	if err := writeSchemaFields(body, st, types, "", nil); err != nil {
+		return err
+	}
 	_, err = io.WriteString(stdout, strings.TrimLeft(body.String(), "\n"))
 	return err
 }
@@ -74,9 +78,18 @@ type fieldMeta struct {
 // writeSchemaFields writes the fields of one struct level: the scalar lines
 // first, then the sections, so the template re-parses with every value under
 // the header it belongs to. prefix is the dotted path the nested headers
-// carry.
-func writeSchemaFields(w *strings.Builder, st *ast.StructType, types map[string]*ast.StructType, prefix string) {
-	metas := metasOf(st, types)
+// carry. path holds the struct types of the levels currently being written,
+// so a type that reaches itself is reported as recursion instead of
+// exhausting the stack.
+func writeSchemaFields(w *strings.Builder, st *ast.StructType, types map[string]*ast.StructType, prefix string, path []*ast.StructType) error {
+	if slices.Contains(path, st) {
+		return recursionError(st, types)
+	}
+	path = append(path, st)
+	metas, err := metasOf(st, types)
+	if err != nil {
+		return err
+	}
 	for _, m := range metas {
 		if _, elemSt := elementStruct(m.typ, types); elemSt != nil {
 			continue
@@ -98,7 +111,9 @@ func writeSchemaFields(w *strings.Builder, st *ast.StructType, types map[string]
 		writeComment(w, m.comment)
 		fmt.Fprintf(w, "[%s%s]\n", prefix, m.key)
 		if sub := structOf(m.typ, types); sub != nil {
-			writeSchemaFields(w, sub, types, prefix+m.key+".")
+			if err := writeSchemaFields(w, sub, types, prefix+m.key+".", path); err != nil {
+				return err
+			}
 		}
 		fmt.Fprintln(w)
 	}
@@ -109,9 +124,12 @@ func writeSchemaFields(w *strings.Builder, st *ast.StructType, types map[string]
 		}
 		writeComment(w, m.comment)
 		fmt.Fprintf(w, "[[%s%s]]\n", prefix, m.key)
-		writeSchemaFields(w, elemSt, types, "")
+		if err := writeSchemaFields(w, elemSt, types, "", path); err != nil {
+			return err
+		}
 		fmt.Fprintln(w)
 	}
+	return nil
 }
 
 // writeComment writes the comment lines above a binding.
@@ -125,46 +143,103 @@ func writeComment(w *strings.Builder, text string) {
 }
 
 // metasOf flattens the exported fields of a struct. The key comes from the
-// toml tag, or the lower-cased field name; a `-` key drops the field.
-func metasOf(st *ast.StructType, types map[string]*ast.StructType) []fieldMeta {
+// toml tag, or the lower-cased field name; a `-` key drops the field. An
+// embedded struct without a tag name flattens into its parent, the way the
+// library inlines it, while a tagged one keeps its own section.
+func metasOf(st *ast.StructType, types map[string]*ast.StructType) ([]fieldMeta, error) {
+	return flattenMetas(st, types, nil)
+}
+
+// flattenMetas is metasOf with the chain of struct types currently being
+// flattened, which stops a struct that embeds itself, directly or through
+// another embedded type.
+func flattenMetas(st *ast.StructType, types map[string]*ast.StructType, chain map[*ast.StructType]bool) ([]fieldMeta, error) {
+	if chain[st] {
+		return nil, recursionError(st, types)
+	}
+	// A copy per branch: the chain is the path being flattened now, not the
+	// set ever visited, so a type embedded in two siblings is not mistaken
+	// for recursion.
+	chain = maps.Clone(chain)
+	if chain == nil {
+		chain = map[*ast.StructType]bool{}
+	}
+	chain[st] = true
 	var out []fieldMeta
 	for _, field := range st.Fields.List {
-		if len(field.Names) == 0 {
-			// An untagged embedded struct flattens into the parent.
-			if ident, ok := baseType(field.Type).(*ast.Ident); ok {
-				if inner, ok := types[ident.Name]; ok {
-					out = append(out, metasOf(inner, types)...)
-				}
-			}
-			continue
-		}
-		name := field.Names[0].Name
-		if !ast.IsExported(name) {
-			continue
-		}
 		tagText := ""
 		if field.Tag != nil {
 			tagText, _ = strconv.Unquote(field.Tag.Value)
 		}
 		toml := reflect.StructTag(tagText).Get("toml")
-		key, opts := "", ""
-		if toml != "" {
-			key, opts, _ = strings.Cut(toml, ",")
+		key, opts, _ := strings.Cut(toml, ",")
+		if len(field.Names) == 0 {
+			if key == "" {
+				// An untagged embedded struct flattens into its parent.
+				if ident, ok := baseType(field.Type).(*ast.Ident); ok {
+					if inner, ok := types[ident.Name]; ok {
+						metas, err := flattenMetas(inner, types, chain)
+						if err != nil {
+							return nil, err
+						}
+						out = append(out, metas...)
+					}
+				}
+				continue
+			}
+			if key == "-" {
+				continue
+			}
+			// A tagged embedded struct is a section of its own; the tag
+			// name is the only name it has.
+			out = append(out, fieldMeta{
+				key:     key,
+				comment: tagOption(opts, "comment="),
+				def:     tagOption(opts, "default="),
+				typ:     field.Type,
+			})
+			continue
 		}
 		if key == "-" {
 			continue
 		}
-		if key == "" {
-			key = strings.ToLower(name)
+		// A field list may name several fields of one type, `Min, Max int`;
+		// each name is one TOML key.
+		for _, name := range field.Names {
+			if !ast.IsExported(name.Name) {
+				continue
+			}
+			fieldKey := key
+			if fieldKey == "" {
+				fieldKey = strings.ToLower(name.Name)
+			}
+			out = append(out, fieldMeta{
+				key:     fieldKey,
+				comment: tagOption(opts, "comment="),
+				def:     tagOption(opts, "default="),
+				typ:     field.Type,
+			})
 		}
-		out = append(out, fieldMeta{
-			key:     key,
-			comment: tagOption(opts, "comment="),
-			def:     tagOption(opts, "default="),
-			typ:     field.Type,
-		})
 	}
-	return out
+	return out, nil
+}
+
+// recursionError names the struct type that reached itself. Such a type has
+// no finite TOML template: every level would nest another copy of the same
+// shape.
+func recursionError(st *ast.StructType, types map[string]*ast.StructType) error {
+	return fmt.Errorf("recursive type %s: the struct contains itself, so it has no finite template", typeName(st, types))
+}
+
+// typeName names the declared struct type st refers to, and "anonymous
+// struct" for a literal one that no declaration names.
+func typeName(st *ast.StructType, types map[string]*ast.StructType) string {
+	for name, t := range types {
+		if t == st {
+			return name
+		}
+	}
+	return "anonymous struct"
 }
 
 // tagOption returns the text a `name=` option carries in the option part of