Replace message affixes with subject and body modifiers

Author: brandonbloom

README.md

@@ -250,8 +250,10 @@ Useful flags:
 | `--no-checkout` | Commit without materializing touched paths into the checkout. |
 | `--untracked` | Admit untracked source paths under CWD. |
 | `--message <m>` | Override the generated commit message. |
-| `--message-prefix <m>` | Prepend the generated commit message. |
-| `--message-suffix <m>` | Append the generated commit message. |
+| `--subject-prefix <s>` | Prepend literal text to the generated commit subject. |
+| `--subject-suffix <s>` | Append literal text to the generated commit subject. |
+| `--body-prefix <s>` | Prepend a body block before the generated commit body. |
+| `--body-suffix <s>` | Append a body block after the generated commit body. |
 | `--retries <n>` | Retry optimistic ref-update conflicts. The default is `3`. |
 | `--allow-empty` | Permit an empty commit for mutating invocations. |
 

docs/spec-review.md

@@ -541,8 +541,10 @@ Core flags:
   --no-checkout          commit without materializing touched paths
   --untracked            admit untracked source paths under CWD
   --message <m>          override generated commit message
-  --message-prefix <m>   prepend generated commit message
-  --message-suffix <m>   append generated commit message
+  --subject-prefix <s>   prepend literal text to generated commit subject
+  --subject-suffix <s>   append literal text to generated commit subject
+  --body-prefix <s>      prepend a block to generated commit body
+  --body-suffix <s>      append a block to generated commit body
   --retries <n>          retry CAS conflicts, default 3
   --allow-empty          permit empty commit for mutating invocations
   --version              print version and exit

internal/etch/catalog.go

@@ -50,8 +50,10 @@ func runCLIAt(cwd string, args []string, stdout, stderr io.Writer) (exitCode, er
 			&cli.BoolFlag{Name: "no-checkout", Usage: "commit without materializing touched paths", Destination: &opts.NoCheckout},
 			&cli.BoolFlag{Name: "untracked", Usage: "admit untracked source paths under CWD", Destination: &opts.Untracked},
 			&cli.StringFlag{Name: "message", Usage: "override generated commit message", Destination: &opts.Message},
-			&cli.StringFlag{Name: "message-prefix", Usage: "prepend generated commit message", Destination: &opts.MessagePrefix},
-			&cli.StringFlag{Name: "message-suffix", Usage: "append generated commit message", Destination: &opts.MessageSuffix},
+			&cli.StringFlag{Name: "subject-prefix", Usage: "prepend literal text to generated commit subject", Destination: &opts.SubjectPrefix},
+			&cli.StringFlag{Name: "subject-suffix", Usage: "append literal text to generated commit subject", Destination: &opts.SubjectSuffix},
+			&cli.StringFlag{Name: "body-prefix", Usage: "prepend a block to generated commit body", Destination: &opts.BodyPrefix},
+			&cli.StringFlag{Name: "body-suffix", Usage: "append a block to generated commit body", Destination: &opts.BodySuffix},
 			&cli.IntFlag{Name: "retries", Usage: "retry CAS conflicts", Value: 3, Destination: &opts.Retries},
 			&cli.BoolFlag{Name: "allow-empty", Usage: "permit empty commit for mutating invocations", Destination: &opts.AllowEmpty},
 			&cli.BoolFlag{Name: "version", Usage: "print version and exit"},
@@ -92,8 +94,8 @@ func runParsedCLI(opts GlobalOptions, rest []string, stdout, stderr io.Writer) (
 	if opts.Plan && opts.DryRun {
 		return exitUsage, usagef("--plan and --dry-run are mutually exclusive")
 	}
-	if opts.Message != "" && (opts.MessagePrefix != "" || opts.MessageSuffix != "") {
-		return exitUsage, usagef("--message is mutually exclusive with --message-prefix and --message-suffix")
+	if opts.Message != "" && (opts.SubjectPrefix != "" || opts.SubjectSuffix != "" || opts.BodyPrefix != "" || opts.BodySuffix != "") {
+		return exitUsage, usagef("--message is mutually exclusive with subject/body message modifiers")
 	}
 	if opts.Retries < 0 {
 		return exitUsage, usagef("--retries must be non-negative")
@@ -205,8 +207,10 @@ func globalFlagCompletions() []string {
 		"--no-checkout",
 		"--untracked",
 		"--message",
-		"--message-prefix",
-		"--message-suffix",
+		"--subject-prefix",
+		"--subject-suffix",
+		"--body-prefix",
+		"--body-suffix",
 		"--retries",
 		"--allow-empty",
 		"--version",

internal/etch/cli.go

@@ -0,0 +1,19 @@
+package etch
+
+import (
+	"errors"
+	"fmt"
+	"testing"
+)
+
+func TestClassifyErrUsesErrorsAs(t *testing.T) {
+	wrapped := fmt.Errorf("wrapped: %w", usagef("bad usage"))
+	if got := classifyErr(wrapped); got != exitUsage {
+		t.Fatalf("classifyErr(wrapped usage) = %d, want %d", got, exitUsage)
+	}
+
+	joined := errors.Join(fmt.Errorf("other"), usagef("bad usage"))
+	if got := classifyErr(joined); got != exitUsage {
+		t.Fatalf("classifyErr(joined usage) = %d, want %d", got, exitUsage)
+	}
+}

internal/etch/errors_test.go

@@ -107,7 +107,7 @@ func TestShellCompletionThroughCLI(t *testing.T) {
 	if err != nil || code != exitOK {
 		t.Fatalf("flag completion code=%d err=%v stderr=%s", code, err, errb.String())
 	}
-	for _, want := range []string{"--plan\n", "-n\n"} {
+	for _, want := range []string{"--plan\n", "-n\n", "--subject-prefix\n", "--body-suffix\n"} {
 		if !strings.Contains(out.String(), want) {
 			t.Fatalf("flag completion missing %q:\n%s", want, out.String())
 		}

internal/etch/help_test.go

@@ -503,7 +503,7 @@ func buildCommitMessage(opts GlobalOptions, ops []Operation) string {
 	msg := "etch: no changes"
 	if len(mut) == 1 {
 		subj := "etch " + mut[0].Descriptor
-		if len(subj) <= 72 && !strings.Contains(subj, "\n") {
+		if commitSubjectFits(subj, opts) {
 			msg = subj
 		} else {
 			msg = "etch " + descriptorWithoutValue(mut[0])
@@ -528,13 +528,45 @@ func buildCommitMessage(opts GlobalOptions, ops []Operation) string {
 			msg += "\n- " + op.Descriptor
 		}
 	}
-	if opts.MessagePrefix != "" {
-		msg = opts.MessagePrefix + msg
+	return applyCommitMessageModifiers(msg, opts)
+}
+
+func commitSubjectFits(subject string, opts GlobalOptions) bool {
+	subject = opts.SubjectPrefix + subject + opts.SubjectSuffix
+	return len(subject) <= 72 && !strings.Contains(subject, "\n")
+}
+
+func applyCommitMessageModifiers(msg string, opts GlobalOptions) string {
+	subject, body := splitCommitMessage(msg)
+	subject = opts.SubjectPrefix + subject + opts.SubjectSuffix
+	body = joinCommitBodyBlocks(opts.BodyPrefix, body, opts.BodySuffix)
+	if body == "" {
+		return subject
+	}
+	return subject + "\n\n" + body
+}
+
+func splitCommitMessage(msg string) (subject, body string) {
+	subject, body, ok := strings.Cut(msg, "\n\n")
+	if !ok {
+		return msg, ""
 	}
-	if opts.MessageSuffix != "" {
-		msg += opts.MessageSuffix
+	return subject, body
+}
+
+func joinCommitBodyBlocks(blocks ...string) string {
+	var out string
+	for _, block := range blocks {
+		if block == "" {
+			continue
+		}
+		if out == "" {
+			out = block
+			continue
+		}
+		out = strings.TrimRight(out, "\n") + "\n\n" + strings.TrimLeft(block, "\n")
 	}
-	return msg
+	return out
 }
 
 func descriptorWithoutValue(op Operation) string {

internal/etch/planner.go

@@ -142,6 +142,89 @@ func TestPlanHashUsesJCSCanonicalBytes(t *testing.T) {
 	}
 }
 
+func TestBuildCommitMessageAppliesSubjectAndBodyModifiers(t *testing.T) {
+	ops := []Operation{{
+		Verb:       "set",
+		Class:      ClassIdempotent,
+		Descriptor: `set state.json $.status "done"`,
+		Value:      `"done"`,
+	}}
+
+	got := buildCommitMessage(GlobalOptions{
+		SubjectPrefix: "feat: ",
+		SubjectSuffix: " [skip ci]",
+	}, ops)
+	want := `feat: etch set state.json $.status "done" [skip ci]`
+	if got != want {
+		t.Fatalf("message = %q, want %q", got, want)
+	}
+
+	got = buildCommitMessage(GlobalOptions{
+		BodySuffix: "Refs: #1",
+	}, ops)
+	want = `etch set state.json $.status "done"` + "\n\nRefs: #1"
+	if got != want {
+		t.Fatalf("message = %q, want %q", got, want)
+	}
+}
+
+func TestBuildCommitMessageJoinsBodyModifiersWithGeneratedBody(t *testing.T) {
+	ops := []Operation{
+		{
+			Verb:       "set",
+			Class:      ClassIdempotent,
+			Target:     PlanTarget{Path: "state.json"},
+			Descriptor: `set state.json $.status "done"`,
+			Value:      `"done"`,
+		},
+		{
+			Verb:       "delete",
+			Class:      ClassIdempotent,
+			Target:     PlanTarget{Path: "state.json"},
+			Descriptor: `delete state.json $.old`,
+		},
+	}
+
+	got := buildCommitMessage(GlobalOptions{
+		SubjectPrefix: "feat: ",
+		BodyPrefix:    "Context: generated",
+		BodySuffix:    "\n\nRefs: #1",
+	}, ops)
+	want := strings.Join([]string{
+		"feat: etch: 2 changes in state.json",
+		"",
+		"Context: generated",
+		"",
+		"Changes:",
+		`- set state.json $.status "done"`,
+		"- delete state.json $.old",
+		"",
+		"Refs: #1",
+	}, "\n")
+	if got != want {
+		t.Fatalf("message = %q, want %q", got, want)
+	}
+}
+
+func TestBuildCommitMessageSubjectModifiersAffectValueFallback(t *testing.T) {
+	ops := []Operation{{
+		Verb:       "set",
+		Class:      ClassIdempotent,
+		Descriptor: `set state.json $.status "1234567890123456789012345678901234567890"`,
+		Value:      `"1234567890123456789012345678901234567890"`,
+	}}
+
+	got := buildCommitMessage(GlobalOptions{SubjectPrefix: "feat: "}, ops)
+	want := strings.Join([]string{
+		"feat: etch set state.json $.status",
+		"",
+		`Value: "1234567890123456789012345678901234567890"`,
+	}, "\n")
+	if got != want {
+		t.Fatalf("message = %q, want %q", got, want)
+	}
+}
+
 func filepathJoin(elem ...string) string {
 	return filepath.Join(elem...)
 }

internal/etch/planner_test.go

@@ -49,8 +49,10 @@ type GlobalOptions struct {
 	NoCheckout    bool
 	Untracked     bool
 	Message       string
-	MessagePrefix string
-	MessageSuffix string
+	SubjectPrefix string
+	SubjectSuffix string
+	BodyPrefix    string
+	BodySuffix    string
 	Retries       int
 	AllowEmpty    bool
 }
@@ -72,6 +74,9 @@ type Statement struct {
 	Loc    SourceLoc
 }
 
+// CommandClass describes a command's content-change behavior within one
+// transaction. It is not a promise that re-running the same command after a
+// successful commit will still succeed against the new base.
 type CommandClass string
 
 const (