SWG-4A-10: griff swang dump

[PhysShell]

SWG-4A-10 — griff swang dump

griff swang dump input.gp5
griff swang dump input.mid

Import runs through the existing adapters; the canonical level-2 exact text
goes to stdout and only to stdout; import warnings and diagnostics go to
stderr. No hidden normalization, and two runs of one file produce
byte-identical output.

A CLI surface over a writer that was finished in SWG-4A-05 — not another
slice of it. griff-swang and the importers are untouched: the diff is one
new griff-cli module, one clap subcommand, one dispatch arm, one
CliError variant, and this suite.

Level 2 is not frozen and Phase 4A is not closed.

Commits (no squash — the order is the evidence)

#	commit	what
1	f712131	red — the dump contract, tests only
2	ec17096	green — griff swang dump
3	82fc519	falsification guard (tests only) — the surviving mutation
4	1c55946	docs closure
5	4594ef1	review docs — warning entries, not physical lines

The RED is a real one. Commit 1 changes nothing under cli/src/, so the
suite cannot compile:

error[E0432]: unresolved import `griff_cli::swang_dump`
  --> cli/tests/swang_dump.rs:29:16

and the binary agrees at runtime:

$ griff swang dump /dev/null
error: unrecognized subcommand 'dump'
exit: 2

The one design decision

griff_cli::swang_dump::dump_score returns both surfaces together:

pub struct DumpOutput {
    pub document: String,      // stdout — exact::write_score, verbatim
    pub warnings: Vec<String>, // stderr — one entry per ImportWarning
}

write_score runs to completion before the value exists, so a refusal
produces no DumpOutput at all. That makes no partial document
structural rather than a discipline someone has to remember; main only
routes two finished surfaces to two streams. No second formatter appears
anywhere — the census already decided every byte.

Score.loss is rendered on both surfaces, deliberately. It is a
canonical fact the exact text is obliged to carry (§2.8); the stderr entry
is a courtesy to whoever is watching the terminal. Suppressing the block
because a human had already been told would make the canonical text depend
on who was looking at it, and would undo what SWG-4A-05 spent twenty
mutations establishing.

The contract, one test each

#	obligation	how it is checked
1	a Guitar Pro file dumps a level-2 document	.gp fixture written by the guitarpro crate's own serializer
2	a MIDI file does the same	midly-built fixture, same entry point
3	stdout is the document and nothing else	absence of CLI chatter and equality with write_score(import_score_auto(bytes))
4	a warning reaches stderr and stays in the exact text	track_name_invalid_utf8 present in stdout, described on stderr, document absent from stderr
5	two runs are byte-identical	same file, twice
6	import failure → non-zero, empty stdout	garbage bytes
7	a refused score yields no document at all	at the swang_dump seam (see below)
8	no hidden normalization	stdout compared to write_score(import_score_auto(bytes)), never a hand-copied golden
—	stderr entries keep LossReport vector order	a fixture where sorted ≠ vector order

Row 8 is the one that makes this a transport test rather than a second
formatter agreeing with the first about something wrong.

Both fixtures come from encoders independent of the code under test.
guitarpro is a new dev-dependency of griff-cli only — the crate is
already in the tree through griff-core's default gp feature, so this adds
test-time access, not third-party code.

Row 7 needed a finding to state honestly

No file reaching dump is refused by the writer. The MIDI reader rejects
ppqn 0 outright, and a zero meter numerator is silently normalised to 4/4
long before write_score sees it — both probed rather than assumed. So the
refusal is proved at the library seam, and the unreachability is written
down instead of being papered over with a fabricated fixture.

Falsification: eleven mutations

Each probe was applied to cli/src/swang_dump.rs or cli/src/main.rs in
isolation and the whole griff-cli suite re-run. The classifier is the
five-state one inherited from #190 — including NOT REBUILT, which
refuses to give a verdict on a run whose output does not contain
Compiling griff-cli, because this container's filesystem hands out
timestamps coarse enough for cargo to test the previous probe's binary.

Initial run: 10 CAUGHT / 1 SURVIVED.

The survivor was D3 sort the warning entries. Nothing in the suite looked
at their order — the matrix only counted them — so a rendering that
alphabetised the loss report would have passed. LossReport appends and the
exact walker compares positionally (§2.7); the stderr entries are a
rendering of that vector, so they inherit its order rather than choosing
one. The guard is commit 82fc519, with a fixture built to see the
difference: eleven tracks, invalid UTF-8 names at raw indices 2 and 10, so
"track 10" sorts before "track 2" — and the test asserts sorted ≠
vector order, which is what stops it passing vacuously if the fixture is
ever weakened.

Final rerun: 11 CAUGHT / 0 SURVIVED / 0 NOT REBUILT / 0 INVALID.

#	mutation	outcome	caught by
D1	drop loss once stderr has seen it	CAUGHT	a_dumped_score_carries_its_document_and_its_warnings_together, an_import_warning_is_reported_to_stderr_and_kept_in_the_document, the_cli_prints_exactly_what_the_writer_produces
D2	silence stderr when the document carries loss	CAUGHT	a_dumped_score_carries_its_document_and_its_warnings_together, an_import_warning_is_reported_to_stderr_and_kept_in_the_document, the_warning_lines_keep_the_loss_report_order
D3	sort the warning entries	CAUGHT (survived the initial run; guarded by 82fc519)	the_warning_lines_keep_the_loss_report_order
D4	reformat the document (trim its trailing newline)	CAUGHT	a_dumped_score_carries_its_document_and_its_warnings_together, stdout_carries_the_document_and_no_cli_chatter, the_cli_prints_exactly_what_the_writer_produces
D5	normalize the document (sort its lines)	CAUGHT	a_dumped_score_carries_its_document_and_its_warnings_together, a_guitar_pro_file_dumps_a_canonical_level_two_document, a_midi_file_dumps_a_canonical_level_two_document, stdout_carries_the_document_and_no_cli_chatter, the_cli_prints_exactly_what_the_writer_produces
M1	print the document to stderr	CAUGHT	a_guitar_pro_file_dumps_a_canonical_level_two_document, a_midi_file_dumps_a_canonical_level_two_document, an_import_warning_is_reported_to_stderr_and_kept_in_the_document, stdout_carries_the_document_and_no_cli_chatter, the_cli_prints_exactly_what_the_writer_produces
M2	print the warnings to stdout	CAUGHT	an_import_warning_is_reported_to_stderr_and_kept_in_the_document, the_cli_prints_exactly_what_the_writer_produces, the_warning_lines_keep_the_loss_report_order
M3	announce the input file on stdout	CAUGHT	a_guitar_pro_file_dumps_a_canonical_level_two_document, a_midi_file_dumps_a_canonical_level_two_document, an_unimportable_file_fails_with_a_diagnostic_and_no_document, stdout_carries_the_document_and_no_cli_chatter, the_cli_prints_exactly_what_the_writer_produces
M4	swallow the import error and print nothing	CAUGHT	an_unimportable_file_fails_with_a_diagnostic_and_no_document
M5	print a partial document before writing	CAUGHT	stdout_carries_the_document_and_no_cli_chatter, the_cli_prints_exactly_what_the_writer_produces
M6	add a trailing newline of its own	CAUGHT	stdout_carries_the_document_and_no_cli_chatter, the_cli_prints_exactly_what_the_writer_produces

The review round (commit 5)

Independent review found the closure overclaiming its own surface, not a
production defect. Several places promised "one line per import warning" on
stderr. ImportWarning::Other(String) is unrestricted and may contain an
embedded LF — SWG-4A-05 pinned exactly that case in the exact text, where
§6.5's frozen escape policy keeps a warning on one physical line there.
The terminal rendering has no such grammar and describe_warning passes an
Other message through verbatim, so one entry can legitimately occupy three
lines of stderr.

The fix is the sentence, not the code. Inventing an escaping or sanitization
policy for human stderr to make a docstring true would be adding a contract
nobody asked for: 4A-10's obligation is that warnings go to stderr, not
that they arrive one per line. The invariant that is real, and tested, is
one rendered entry per LossReport element in vector order. No new test —
the point is precisely not to freeze a stderr line policy. decisions.log.md
gets a continuation entry rather than an edit to the existing one.

Checks

• 1397 tests green across core, swang, pattern, cli, ui-core.
• cargo fmt --all --check and cargo clippy --workspace --all-targets
  clean.
• cargo check --workspace --all-targets clean, cockpit/preview/plugin
  included, via a stub alsa.pc (libasound is absent here). fuzz/ pins
  nightly and is left to CI.

Out of scope, deliberately

The parser lane (4A-02, INF-04, INF-06, 4A-06+), ExactScoreDocument,
ScoreBuilder, griff swang verify (4A-11 — this satisfies its CLI-side
dependency only; it still needs 4A-09), CORE-02 sealing, stdin support,
machine-readable diagnostics, any new normalization, importer behaviour, or
exact-text syntax, and the level-2 freeze.

Also deliberately untouched: the task-index rows for 4A-03 and 4A-04 are
missing the *(done)* marker their own sections and the dependency map
carry. Pre-existing bookkeeping, unrelated to this task.

---

Generated by Claude Code

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 27f98d89-2a7f-4614-b459-9c29caecc2eb

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}