test(cmd/morphic): pin the rendered help text with goldens

[fuad-daoud]

Summary

Adds golden files for the rendered root help and compile help, so wording changes show up as a reviewable diff rather than slipping by unnoticed. Regenerate with:

go test ./cmd/morphic -run TestHelp_MatchesGolden -update

That -update is ir/irtest's, not a second declaration in this package. Two flag.Bool("update", ...) calls do not shadow each other — both register on the same command-line FlagSet, so the test binary panics at init (flag redefined: update) the moment anything pulls irtest into these tests. Reusing the existing flag makes the collision unrepresentable.

The README gains the help forms and states that help exits 0. It also gets compile's real synopsis back alongside the root one: with only morphic <command> [flags] above it, the flag table read as though -o and --fail-on were root flags.

Test plan

• TestHelp_MatchesGolden compares both help texts against the committed goldens; deliberately not parallel because -update writes files.
• Checked the three things that usually go wrong with goldens, by executing rather than reading:
  • golden deleted → red, with read golden testdata/root-help.txt (run with -update to create)
  • -update → recreates both files, md5sum -c clean against the committed bytes
  • wording changed in writeRootHelp → red, golden mismatch for testdata/root-help.txt
• Confirmed the -update collision is gone: a test file importing irtest alongside these now runs, where before it panicked at init.
• gofmt -l, go vet ./..., golangci-lint run (0 issues), go build ./..., ./scripts/check-coverage.sh — 4232/4232 statements.

[OmarAlJarrah]

The golden mechanism holds up. I checked the three things that usually go wrong with goldens rather than reading it:

• golden removed: red, with the message that tells you to run -update
• -update: recreates both files byte for byte
• wording changed in writeRootHelp: red

Gate clean on the merged state: golangci-lint 0 issues, coverage 4234/4234.

Also worth noting this lands the README update that #205's Breaking section already claims. That claim is still wrong on #205 read on its own, since the file isn't in that PR.

Last thing: the five follow-ups in the description are good catches, but a squashed PR body isn't a tracker. None of them are open issues right now, so they'll be gone once this merges. Worth filing the ones you mean to keep, particularly the flag.ErrHelp handling being compile-specific, since that one gets more expensive with every subcommand added.

[OmarAlJarrah]

Don't define a second -update. ir/irtest already owns one, and this isn't a latent hazard, it's a live landmine: import ir/irtest anywhere in this package's tests and the binary panics at init before a single test runs.

morphic.test flag redefined: update
panic: ... flag redefined: update

Reuse the existing one and the collision can't happen:

Suggested change

var updateHelp = flag.Bool("update", false, "rewrite help golden files instead of comparing")

Then if *updateHelp { becomes if irtest.Update() {, with "github.com/dexpace/morphic/ir/irtest" in the imports. I ran it: -update still rewrites both goldens byte for byte, the package tests pass, and archtest is happy with the import.

That also clears one of the five follow-ups in the description.

[fuad-daoud]

Fixed — it uses irtest.Update() now.

Reproduced the panic first (a probe test importing irtest → flag redefined: update before any test ran), then confirmed it's gone: the same probe now runs clean. -update still rewrites both goldens byte for byte, checked with md5sum -c against the committed files, and archtest is green (it only audits non-test files, so the import is outside its allowlist by design).

[OmarAlJarrah]

The misuse text is the third thing that renders and the only one not pinned here. writeCommandUsage and the root help that misuse prints to stderr can both drift silently. Worth a third row, capturing stderr:

{"compile misuse", []string{"compile"}, "compile-usage.txt"},

Needs the helper to take stderr for that case, so only do it if you think the text is worth pinning. The two you have are the ones that matter most.

[fuad-daoud]

Holding this one until the rest of the stack settles — it needs the helper to take stderr, and I want to decide it alongside the flagSet→printFlags question on #204, which touches the same rendering. Leaning yes: the misuse text is the only one of the three renders that nothing pins.

[OmarAlJarrah]

Dropping the compile synopsis leaves the flag table sitting under morphic <command> [flags], so -o and --fail-on now read as root flags. They aren't. The old line was wrong in form but it did tell you whose flags these were.

Add compile's real synopsis back, in the form the CLI actually prints, so this can't drift again:

Suggested change

	morphic <command> [flags]
	morphic <command> [flags]
	morphic compile <spec-file> [flags]

[fuad-daoud]

Added compile's synopsis back in the form the CLI prints, alongside the root one. Also put a line above the table saying the flags are compile's, since the table itself gives no clue.

[OmarAlJarrah]

-help works too, same as -h and --help. Either list it or say "a help flag" rather than naming two of the three.

[fuad-daoud]

Fixed — it now says a help flag and lists all three.

[fuad-daoud]

Filed the surviving follow-ups so they outlive the squash — you were right that a PR body isn't a tracker:

• cmd/morphic: flag.ErrHelp handling is per-subcommand, not shared #230 — flag.ErrHelp handling is per-subcommand, not shared. The one you singled out.
• cmd/morphic: -- does not terminate flag parsing after the first positional #231 — -- does not terminate flag parsing after the first positional.
• cmd/morphic: root help pads the command column to a magic width #232 — root help pads the command column to a magic width. Worth adding: the golden this PR introduces will record the misalignment as expected output once a longer command name lands, rather than flag it.

The other two are closed by the stack rather than filed: the -update collision is fixed here, and TestCommands_TableIsWellFormed on #204 covers the malformed-entry case (blank name, duplicate name — both verified by planting the defect).